---
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*