---
phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow
task: 1
total_tasks: 2
status: paused
last_updated: 2026-04-04T10:13:58.720Z
---

<current_state>
Formally, the most recently active GSD artifact is `01.1-03-PLAN.md`, which has not been executed yet. In parallel, an out-of-band research pass compared the local mock SDK against platform repos and concluded that Phase 02 SDK integration is still blocked on an unstable control-plane contract.
</current_state>

<completed_work>

- Session research: inspected local `sdk/interface.py`, `sdk/mock.py`, core message/settings usage, and platform repos `agent_api`, `agent`, `master`, `docs`.
- Established that the real platform currently provides a direct WebSocket `agent_api` for talking to the agent, while `master` is still mostly a control-plane skeleton rather than a stable consumer-facing API.
- Confirmed that the current local mock assumes a richer unified platform API than what is actually implemented today.
- Concluded that consumer adapters should not be deeply rewritten yet; Matrix remains the right internal testing surface for now.
</completed_work>

<remaining_work>

- Task 1: Implement `adapter.matrix.reset` with `local-only`, `server-leave-forget`, and `--dry-run`, plus tests.
- Task 2: Update `README.md` so restart vs explicit reset workflow is documented and the old manual reset ritual is removed.
- Phase 02 follow-up, once platform stabilizes: split the current platform boundary into control-plane and direct-agent-session abstractions instead of keeping a single `PlatformClient`.
</remaining_work>

<decisions_made>

- Keep the current consumer-facing bot logic largely intact for now; do not force an early rewrite around the incomplete platform backend.
- Treat `sdk/mock.py` as a temporary local integration facade, not as a near-drop-in simulation of the real platform.
- Use Matrix for internal testing while waiting for the platform team to finalize the minimal control-plane contract.
</decisions_made>

<blockers>
- Platform contract blocker: `agent_api` is concrete enough to study, but `master` still does not expose a stable user/chat/session/settings API for surfaces.
- Product contract blocker: attachments, settings, webhook-style long task events, and exact session bootstrap flow are still unclear on the platform side.
</blockers>

<context>
The key mental model from this session: our mock pretends the platform is already a complete backend, but the real platform today is split. There is a usable direct agent WebSocket protocol, and there is a developing master control plane, but they have not converged into the unified SDK shape that the bot currently assumes. Because of that, the right near-term move is not to rush integration, but to preserve momentum with Matrix/internal testing and keep the future integration boundary explicit.
</context>

<next_action>
Start with one of these, depending on priority:
1. Execute `01.1-03-PLAN.md` Task 1 and build the Matrix reset CLI.
2. If returning to platform research, write a concrete draft interface for `MasterClient` + `AgentSession` while leaving consumer adapters unchanged.
</next_action>