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

phase	task	total_tasks	status	last_updated
01.1-matrix-restart-reconciliation-and-dev-reset-workflow	1	2	paused	2026-04-07T15:11:42.203Z

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

• 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.
• 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>

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

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

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