--- gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces status: Phase 05 Paused last_updated: "2026-04-29T08:49:04Z" progress: total_phases: 6 completed_phases: 3 total_plans: 16 completed_plans: 13 --- # State ## Project Reference See: .planning/PROJECT.md (updated 2026-04-02) **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра **Current focus:** Phase 05 paused — latest file-contract change needs a new image build before platform redeploy ## Current Phase **Phase 05** paused: MVP deployment hardening is in place, but the latest attachment workspace-root change is not yet published Deployment handoff follow-up is external. The last published image predates the latest file-handling change; the next step is to rebuild and publish a fresh image, then ask the platform to redeploy Matrix with the shared `/agents` volumes and `config/matrix-agents.yaml`. Plan `05-01` is complete. Matrix startup now reconciles managed Space rooms from synced topology before live traffic, restoring local metadata and deterministic legacy `platform_chat_id` bindings on restart. - `a75b26a` — failing restart reconciliation regressions for recovery, idempotence, startup ordering, and legacy backfill - `8a80d00` — startup reconciliation module and pre-sync wiring in the Matrix runtime Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py tests/adapter/matrix/test_dispatcher.py -v`. Plan `05-02` is complete. Matrix room-local context commands now rely on repaired per-room `platform_chat_id` bindings, and `!clear` rotates only the active room's upstream context when prototype room state is available. - `ae37476` — failing regressions for clear registration, room-local rotation, and strict routed-platform metadata requirements - `85e2fda` — room-local clear semantics, compatibility alias wiring, and strict context resolution without shared chat fallbacks Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v`. Plan `05-03` is complete. Shared-volume attachment handling now preserves relative agent paths while tolerating both `/workspace` and `/agents` absolute prefixes during normalization and Matrix file rendering. - `7a12a71` — failing regressions for shared-volume path normalization and room-safe attachment handling - `5eddf16` — `/agents` deployment path hardening for Matrix files and routed platform attachments Verified with `uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`. Plan `05-04` is complete. Production handoff now uses `docker-compose.prod.yml` for a bot-only runtime, while internal end-to-end verification uses `docker-compose.fullstack.yml` with shared `/agents` volume guidance and health-gated startup. - `df6d8bf` — split prod and full-stack compose artifacts with the shared `/agents` contract - `22a3a2b` — operator and deployment docs aligned to the split compose artifacts Verified with `docker compose -f docker-compose.prod.yml config`, `docker compose -f docker-compose.fullstack.yml config`, and docs grep checks for `docker-compose.prod.yml`, `docker-compose.fullstack.yml`, and `/agents`. ## Decisions - Продолжаем с Threaded Mode несмотря на баги Mac клиента (2026-04-02) - Invite flow Matrix переведён на idempotent-проверку через `user_meta.space_id`, а не через invite-room metadata (2026-04-02) - Неизвестные Matrix rooms больше не auto-register в роутере; используется явный fallback `unregistered:{room_id}` с warning-логом (2026-04-02) - [Phase 01]: Use ChatContext.surface_ref as the Matrix room identifier for !rename updates. - [Phase 01]: Keep !archive limited to core archive state in Phase 1; Space child removal remains deferred. - [Phase 01]: Matrix OutgoingUI no longer emits reactions; confirmation state is persisted and resumed via `!yes` / `!no`. - [Phase 01]: `!settings` now renders a dashboard snapshot instead of advertising mutable subcommands. - [Phase 01]: Split Matrix regression coverage into dedicated invite/chat/send_outgoing/confirm test modules. - [Phase 01]: Kept 01-04 scoped to test coverage without widening into production-code changes. - [Phase 01]: Matrix command callbacks now include room_id in payload for !yes and !no so confirm handlers can resolve runtime state without changing core protocol types. - [Phase 01]: Pending confirmations are stored under the D-08 composite key of matrix user id plus room id, with a narrow legacy fallback only for callers that omit room context. - [Phase 01]: Removed Matrix reaction conversion entirely and kept command callbacks limited to !yes/!no. - [Phase 01]: Kept !settings as a pure snapshot surface while preserving mutable subcommands outside the dashboard. - [Phase 01]: Seeded invite and dispatcher tests with explicit next_chat_index and room ids instead of treating C1 as Matrix transport identity. - [Phase 04]: Replaced AgentSessionClient with AgentApiWrapper and persistent agent connection lifecycle in Matrix runtime. - [Phase 04]: Added !save, !load, !reset, and !context commands with pending-state interception and local prototype session metadata. - [Phase 04]: Added Matrix-only Docker packaging for MVP deployment; platform services remain external to this compose setup. - [Phase 04]: Replaced the Matrix prod path again with direct upstream `AgentApi` per request; removed the local runtime wrapper from the prod flow. - [Phase 04]: Adopted `AGENT_BASE_URL` as the primary runtime contract and kept `AGENT_WS_URL` only as backward-compatible env fallback. - [Phase 04 follow-up]: Kept shared PlatformClient unchanged; introduced Matrix-specific RoutedPlatformClient to avoid breaking Telegram adapter. - [Phase 04 follow-up]: agent_routing_enabled flag on MatrixRuntime activates stale-room check only in real multi-agent mode (RoutedPlatformClient). - [Phase 04 follow-up]: !new binds agent_id at room creation time using selected_agent_id from user metadata. - [Phase 04 follow-up]: platform_chat_seq (PLATFORM_CHAT_SEQ_KEY) is stored in SQLiteStore and survives restart — confirmed by test. - [Phase 05 reset]: Discard the single-chat / DM-first deployment direction. Replan around Space+rooms, per-room `platform_chat_id`, real `!clear`, reconciliation, and split prod/fullstack compose artifacts. - [Phase 05]: Keep adapter/matrix/files.py as the sole path builder; sdk/real.py only normalizes shared-volume attachment references. - [Phase 05]: Normalize /workspace and /agents absolute file paths back to relative workspace_path values before agent transport and Matrix file rendering. - [Phase 05]: Treat synced Matrix topology as authoritative for startup recovery; keep SQLite rebuildable. - [Phase 05]: Backfill missing platform_chat_id values during startup reconciliation before routed handling begins. - [Phase 05]: Expose `clear` only when prototype room-context support is available, while keeping `reset` as a compatibility alias. - [Phase 05]: Require recovered `platform_chat_id` for save/context/clear flows instead of falling back to shared local chat ids. - [Phase 05]: Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification. - [Phase 05]: Document /agents as the bot-side shared volume root while internal platform-agent keeps /workspace on the same named volume. ## Blockers - Lambda platform SDK не готов — Phase 2 заблокирована до готовности платформы - Full production verification depends on the platform team's real multi-agent orchestration, production Matrix credentials, `config/matrix-agents.yaml`, and shared `/agents/N` volume mounts. ## Accumulated Context ### Roadmap Evolution - Phase 01.1 inserted after Phase 01: Matrix restart reconciliation and dev reset workflow (URGENT) - Phase 4 added: Matrix MVP: shared agent context and context management command - Phase 04 follow-up added inline: multi-agent routing (RoutedPlatformClient, !agent, stale room blocking, restart persistence) - Phase 05 reset on 2026-04-28: erroneous single-chat deployment artifacts were removed before fresh planning. ## Performance Metrics | Phase | Plan | Duration | Tasks | Files | Recorded | | --- | --- | --- | --- | --- | --- | | 01 | 01 | 1 min | 3 | 3 | 2026-04-02T19:50:50Z | | 01 | 02 | 1 min | 2 | 2 | 2026-04-02 | | 01 | 03 | 3 min | 2 | 5 | 2026-04-02T19:57:34Z | | 01 | 04 | 3 min | 2 | 7 | 2026-04-02T20:03:38Z | | 01 | 05 | 2 min | 2 | 7 | 2026-04-03T09:28:47Z | | 01 | 06 | 4 min | 2 | 7 | 2026-04-03T09:35:47Z | | 04 | 01 | 1 session | 1 wave | 8 | 2026-04-17 | | 04 | 02 | 1 session | 2 commits + summary | 8 | 2026-04-17 | | 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 | | 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 | | 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z | | 05 | 01 | 8 min | 2 | 4 | 2026-04-27T22:09:28Z | | 05 | 02 | 16 min | 2 | 4 | 2026-04-27T22:15:58Z | | 05 | 04 | 3 min | 2 | 5 | 2026-04-27T22:17:10Z | ## Session - Last session: 2026-04-29T08:49:04Z - Stopped at: Handoff updated after attachment workspace-root change; waiting for image rebuild and platform redeploy - Resume file: .planning/phases/05-mvp-deployment/.continue-here.md