wip: matrix-restart-reconciliation-and-dev-reset-workflow paused at task 1/2

.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md

@@ -3,46 +3,52 @@ 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
+last_updated: 2026-04-07T15:11:42.203Z
 ---
 
 <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.
+Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`, which has not been implemented yet. Since the earlier checkpoint, a fresh live review of the platform repos confirmed that `master` still does not provide a usable consumer-facing control-plane API, but a working Matrix prototype is now feasible by talking directly to the `agent` WebSocket through a new `sdk/real.py` compatibility shim.
 </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.
+- Re-analysed live platform repos on 2026-04-07 by cloning `platform/agent`, `platform/agent_api`, `platform/master`, and `platform/docs`.
+- Confirmed `master` is still only a thin HTTP skeleton with `/health` and `/users/{user_id}`, not a chat/session/settings backend for surfaces.
+- Confirmed `agent` exposes a working `/agent_ws/` WebSocket and `agent_api` provides enough protocol/client code to stream model output.
+- Identified the real technical gap for a prototype: `agent` currently uses a singleton service with a fixed `thread_id="default"`, so all conversations would share memory unless that is parameterized.
+- Derived the recommended prototype path: keep Matrix adapter logic largely intact, add a new `sdk/real.py` shim for direct agent communication, and ask the platform team for a minimal agent-side change to support per-chat thread identity.
+- Started a product/architecture discussion about where that prototype should live: in this repo as the first real backend path, or in a separate repo as a Matrix-only spike. The user asked to save the session before answering that design question.
 </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`.
+- Design follow-up: decide whether the direct-agent prototype belongs in this repo or a separate repo.
+- Future prototype work, once design is approved: introduce `sdk/real.py` plus a narrow compatibility boundary that keeps Matrix adapter logic stable while allowing later expansion toward a fuller platform split.
 </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.
+- Do not integrate with `master` yet; it is still not the backend surfaces needs.
+- Use the direct `agent` WebSocket as the only realistic path for a working prototype right now.
+- Keep consumer-facing Matrix logic as intact as possible and absorb backend differences inside a shim under `sdk/`.
+- Treat future platform evolution as likely to split into at least two concerns: control-plane access and direct agent session streaming.
 </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.
+- Phase 01.1 itself is not blocked; it is simply paused.
+- Prototype blocker: the `agent` repo currently hardcodes a shared `thread_id`, so per-user/per-chat conversation isolation requires either a small upstream change or a careful workaround.
+- Platform contract blocker remains for the longer-term Phase 02 direction: `master` still lacks stable user/chat/session/settings APIs for surfaces.
 </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.
+The important mental model changed slightly since the earlier checkpoint. Before, the conclusion was mainly “Phase 02 is blocked because the platform contract is unstable.” That is still true for full SDK integration through `master`, but it is no longer the whole story. There is now a practical bridge strategy: use the existing `agent` WebSocket directly for message generation, keep settings/user mapping local for the prototype, and preserve adapter stability by hiding all of this behind a new `sdk/real.py` implementation. The open architecture decision is repo placement: short-lived prototype repo versus building the first durable real-backend path here.
 </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.
+Resume with one of these depending on priority:
+1. If continuing phase execution, implement `01.1-03-PLAN.md` Task 1 (`adapter.matrix.reset`) first.
+2. If continuing platform design, answer the pending repo-placement question: keep the prototype in this repo or create a separate repo for a Matrix-only spike.
+3. After that decision, write the design for the direct-agent shim path before touching code.
 </next_action>