feat(deploy): finalize MVP deployment and file transfer approach

.planning/phases/05-mvp-deployment/05-01-SUMMARY.md

@@ -0,0 +1,99 @@
+---
+phase: 05-mvp-deployment
+plan: 01
+subsystem: infra
+tags: [matrix, reconciliation, sqlite, startup, testing]
+requires:
+  - phase: 01-matrix-mvp
+    provides: Space+rooms onboarding, room metadata, and Matrix dispatcher behavior
+  - phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
+    provides: durable platform_chat_id and restart persistence primitives
+provides:
+  - authoritative startup reconciliation from Matrix room topology into local metadata
+  - pre-sync startup wiring that repairs managed rooms before live traffic
+  - restart regression coverage for reconciliation, idempotence, and legacy platform_chat_id backfill
+affects: [matrix, startup, deployment, restart-persistence]
+tech-stack:
+  added: []
+  patterns: [matrix-topology-as-source-of-truth, sqlite-cache-rebuild, pre-sync-reconciliation]
+key-files:
+  created: [adapter/matrix/reconciliation.py, tests/adapter/matrix/test_reconciliation.py]
+  modified: [adapter/matrix/bot.py, tests/adapter/matrix/test_restart_persistence.py]
+key-decisions:
+  - "Treat synced Matrix parent/child topology as authoritative for managed room recovery; keep SQLite rebuildable."
+  - "Backfill missing platform_chat_id values during startup reconciliation instead of routing-time fallbacks."
+patterns-established:
+  - "Startup runs full-state sync, then reconciliation, then sync_forever."
+  - "Recovered Matrix rooms rebuild user_meta, room_meta, auth state, and ChatManager bindings idempotently."
+requirements-completed: [PH05-01, PH05-03]
+duration: 8min
+completed: 2026-04-27
+---
+
+# Phase 05 Plan 01: Restart Reconciliation Summary
+
+**Matrix startup now rebuilds Space-owned working rooms into durable local routing state before live sync begins**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-04-27T22:00:47Z
+- **Completed:** 2026-04-27T22:08:47Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+- Added a dedicated reconciliation module that restores `user_meta`, `room_meta`, auth state, chat bindings, and missing `platform_chat_id` values from the synced Matrix room graph.
+- Wired startup to run reconciliation immediately after the initial full-state sync and before `sync_forever()`.
+- Added regression coverage for recovery, idempotence, pre-sync ordering, onboarding compatibility, and legacy restart backfill.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add restart reconciliation regression coverage** - `a75b26a` (test)
+2. **Task 2: Implement authoritative startup reconciliation and wire it before live sync** - `8a80d00` (feat)
+
+## Files Created/Modified
+- `adapter/matrix/reconciliation.py` - Startup recovery from Matrix topology into local room and user metadata.
+- `adapter/matrix/bot.py` - Startup wiring that runs reconciliation after the bootstrap sync and before live sync.
+- `tests/adapter/matrix/test_reconciliation.py` - Recovery, idempotence, and startup-order regression coverage.
+- `tests/adapter/matrix/test_restart_persistence.py` - Legacy `platform_chat_id` backfill persistence coverage.
+
+## Decisions Made
+- Used the synced Matrix room graph as the authoritative source for restart recovery, while preserving existing local metadata whenever it is already valid.
+- Kept legacy `platform_chat_id` repair on a single startup path so routed handling never needs ad hoc fallback creation for existing rooms.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Switched verification to a clean `uv run pytest` environment**
+- **Found during:** Task 1 and Task 2 verification
+- **Issue:** The default `pytest` path used a mismatched virtualenv without repo dependencies, and `.env` injected Matrix backend variables that polluted mock-mode tests.
+- **Fix:** Ran the verification slice through `uv run pytest` with `UV_CACHE_DIR=/tmp/uv-cache-surfaces` and blank `MATRIX_AGENT_REGISTRY_PATH` / `MATRIX_PLATFORM_BACKEND` values to match the intended test environment.
+- **Files modified:** None
+- **Verification:** `uv run pytest` slice passed with 50/50 tests green
+- **Committed in:** not applicable (verification-only adjustment)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Verification needed an environment correction, but code scope stayed within the plan and owned files.
+
+## Issues Encountered
+- The shell environment loaded deployment-oriented Matrix backend settings from `.env`; these had to be neutralized for the mock-mode regression slice.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Restart recovery is in place for existing Space rooms, including deterministic legacy `platform_chat_id` repair.
+- Remaining Phase 05 plans can build on a stable pre-sync recovery path instead of lazy bootstrap for existing topology.
+
+## Self-Check: PASSED
+
+---
+*Phase: 05-mvp-deployment*
+*Completed: 2026-04-27*