feat(deploy): finalize MVP deployment and file transfer approach

- AgentDefinition gains base_url and workspace_path fields (optional)
- load_agent_registry parses them from matrix-agents.yaml
- _build_platform_from_env uses agent.base_url per agent (falls back to AGENT_BASE_URL)
- _agent_workspace_root() resolves workspace per agent from registry
- _materialize_incoming_attachments saves files to agent workspace_path/incoming/
- send_outgoing accepts workspace_root param; reads outgoing files from agent workspace_path
- dispatch loop computes workspace_root from room agent_id and passes to _send_all
- config/matrix-agents.yaml and example updated with base_url and workspace_path

.dockerignore

@@ -0,0 +1,22 @@
+.git
+.gitignore
+.DS_Store
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.worktrees/
+external/
+.planning/
+docs/superpowers/
+tests/
+
+# Local runtime state must not be baked into the image.
+lambda_matrix.db
+matrix_store/
+lambda_bot.db
+config/matrix-agents.yaml
+
+# Local environment and editor state
+.env
+.idea/

.env.example

@@ -1,14 +1,32 @@
-# Telegram
-TELEGRAM_BOT_TOKEN=your_bot_token_here
-
-# Matrix
-MATRIX_HOMESERVER=https://matrix.org
-MATRIX_USER_ID=@bot:matrix.org
+# Matrix bot credentials
+MATRIX_HOMESERVER=https://matrix.example.org
+MATRIX_USER_ID=@lambda-bot:example.org
+# Use ONE of: MATRIX_PASSWORD or MATRIX_ACCESS_TOKEN
 MATRIX_PASSWORD=your_password_here
+# MATRIX_ACCESS_TOKEN=your_access_token_here
 
-# Lambda Platform
-LAMBDA_PLATFORM_URL=http://localhost:8000
-LAMBDA_SERVICE_TOKEN=your_service_token_here
+# Backend: "real" connects to platform-agent via AgentApi; "mock" uses local stub (testing only)
+MATRIX_PLATFORM_BACKEND=real
 
-# Режим работы: "mock" или "production"
-PLATFORM_MODE=mock
+# Published surface image used by docker-compose.prod.yml.
+# Must point to a Docker Hub/registry namespace where you have push/pull access.
+SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest
+
+# platform/agent_api ref used when building a surface image
+LAMBDA_AGENT_API_REF=master
+
+# Path to agent registry inside the container (mounted via ./config:/app/config:ro)
+MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml
+
+# HTTP URL of the platform-agent endpoint
+# Production: external agent managed by the platform
+# Fullstack E2E: overridden to http://platform-agent:8000 by docker-compose.fullstack.yml
+AGENT_BASE_URL=http://your-agent-host:8000
+
+# Shared volume path inside the bot container (default: /agents).
+# For multi-agent production, each agent gets a subdirectory such as /agents/0.
+SURFACES_WORKSPACE_DIR=/agents
+
+# Docker volume names (created automatically on first run)
+SURFACES_SHARED_VOLUME=surfaces-agents
+SURFACES_BOT_STATE_VOLUME=surfaces-bot-state

.gitignore

@@ -15,6 +15,7 @@ build/
 
 # Git worktrees (не трекаем в репо)
 .worktrees/
+external/
 
 # IDE
 .idea/

.planning/.continue-here.md

@@ -0,0 +1,72 @@
+---
+context: pre-planning
+phase: 05-deployment
+task: 0
+total_tasks: 0
+status: ready-to-plan
+last_updated: 2026-04-27T18:44:51.832Z
+---
+
+<current_state>
+Phase 04 полностью завершена и закоммичена на ветке `feat/matrix-direct-agent-prototype` (135 тестов зелёные). Этот сеанс был посвящён архитектуре деплоя — изучили платформенные репозитории и обсудили топологию с командой платформы. Вся информация о деплое зафиксирована в `docs/deploy-architecture.md`. Phase 05 не спланирована, следующий шаг — `/gsd-plan-phase`.
+</current_state>
+
+<completed_work>
+
+- Изучены актуальные версии platform-agent, platform-agent_api, platform-master
+- Уточнена топология деплоя с платформой (схема с reverse proxy и shared volume)
+- Созданы `docs/deploy-architecture.md` — полное summary архитектуры деплоя
+</completed_work>
+
+<remaining_work>
+
+- Смержить `feat/matrix-direct-agent-prototype` → `main`
+- Спланировать Phase 05 (деплой)
+- Выполнить Phase 05:
+  - Обновить `config/matrix-agents.yaml` (добавить `base_url`, `workspace_path`, `user_agents`)
+  - Обновить `sdk/real.py` (AgentApi конструктор, file transfer)
+  - Обработка `MsgEventSendFile` в Matrix адаптере (скачать файл из volume, отправить пользователю)
+  - Обработка входящих файлов от Matrix пользователей (сохранить в workspace, передать в attachments)
+  - Написать `docker-compose.yml` для деплоя
+</remaining_work>
+
+<decisions_made>
+
+- **Топология**: один инстанс Matrix-бота, один агент-контейнер на пользователя, reverse proxy на `lambda.coredump.ru:7000` роутит по пути `/agent_N/`
+- **Файлы**: через shared volume `/agents/`. Surface пишет файл в `/agents/{N}/`, передаёт относительный путь в `attachments=["file.txt"]`. При `MsgEventSendFile(path)` — читает файл из `/agents/{N}/{path}` и шлёт в Matrix.
+- **Agent API**: используем master (`attachments` и `MsgEventSendFile` есть). Ветку `#9-clientside-tool-call` игнорируем — она в разработке и убирает нужные фичи.
+- **Конфиг**: два словаря — `user_id → agent_id` и `agent_id → {base_url, workspace_path}`
+- **Master**: не используем для MVP. Статический конфиг. При готовности Master — мигрируем.
+- **chat_id**: пока `chat_id=0` (один контекст на пользователя)
+</decisions_made>
+
+<blockers>
+
+- **AGENT_ID + COMPOSIO_API_KEY**: Composio смержен в main platform-agent, теперь обязателен. Значения нужны от Азамата перед деплоем.
+- **agent_api #9**: убирает `attachments` и `MsgEventSendFile` — если смержат до деплоя, сломает наш file transfer. Нужно уточнить сроки.
+</blockers>
+
+## Required Reading (in order)
+
+1. `docs/deploy-architecture.md` — полная архитектура деплоя, топология, API, файловый обмен, конфиг
+2. `adapter/matrix/routed_platform.py` — текущий RoutedPlatformClient
+3. `sdk/real.py` — текущий AgentApi wrapper
+4. `config/matrix-agents.yaml` и `config/matrix-agents.example.yaml` — текущий формат конфига (нужно расширить)
+
+## Infrastructure State
+
+- Ветка: `feat/matrix-direct-agent-prototype` — готова к merge, 135 тестов зелёные
+- `config/matrix-agents.yaml` — незакоммичен (live config, добавить в `.gitignore`)
+- `docs/deploy-architecture.md` — незакоммичен (новый файл этого сеанса)
+- platform-agent main: Composio уже смержен (требует `AGENT_ID`, `COMPOSIO_API_KEY` в env)
+
+<context>
+Архитектура деплоя полностью прояснена. Нет неизвестных блокеров (кроме env-переменных от платформы). Phase 05 — чисто инженерная задача: обновить конфиг, sdk, Matrix адаптер, написать compose. Всё что нужно знать — в docs/deploy-architecture.md.
+</context>
+
+<next_action>
+1. /clear
+2. /gsd-resume-work — прочитает этот файл и предложит план Phase 05
+3. Прочитать docs/deploy-architecture.md
+4. /gsd-plan-phase 05
+</next_action>

.planning/HANDOFF.json

@@ -1,87 +0,0 @@
-{
-  "version": "1.0",
-  "timestamp": "2026-04-04T10:13:58.720Z",
-  "phase": "01.1",
-  "phase_name": "matrix-restart-reconciliation-and-dev-reset-workflow",
-  "phase_dir": ".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow",
-  "plan": 3,
-  "task": 1,
-  "total_tasks": 2,
-  "status": "paused",
-  "completed_tasks": [],
-  "remaining_tasks": [
-    {
-      "id": 1,
-      "name": "Add a dev-only Matrix reset CLI with explicit modes",
-      "status": "not_started"
-    },
-    {
-      "id": 2,
-      "name": "Replace the README reset ritual with the new restart and reset workflow",
-      "status": "not_started"
-    }
-  ],
-  "blockers": [
-    {
-      "description": "Phase 02 SDK integration remains blocked because platform control-plane contract is not stable yet; current platform repos only clearly expose the direct agent WebSocket layer.",
-      "type": "external",
-      "workaround": "Keep the current consumer-facing bot flows and mock-backed facade for now; use Matrix as the internal testing surface and revisit integration once master user/chat/session access is clarified."
-    }
-  ],
-  "human_actions_pending": [
-    {
-      "action": "Confirm with the platform team the minimal control-plane contract for user/chat/session access and whether settings/attachments will exist in master.",
-      "context": "Current evidence shows agent_api is usable, but master is not yet a stable consumer-facing API.",
-      "blocking": true
-    }
-  ],
-  "decisions": [
-    {
-      "decision": "Do not start a full rewrite of the consumer-facing bot integration yet.",
-      "rationale": "Platform direction is visible, but too many pieces outside the direct agent WebSocket protocol are still undefined or inconsistent.",
-      "phase": "02"
-    },
-    {
-      "decision": "Treat sdk/mock.py as a temporary local integration facade rather than a near-drop-in replacement for the real platform.",
-      "rationale": "The current mock assumes a unified platform API, while the real platform is split between control plane and direct agent session.",
-      "phase": "02"
-    },
-    {
-      "decision": "Use Matrix as the internal testing surface while waiting for the platform contract to stabilize.",
-      "rationale": "This preserves product iteration without coupling the bot too early to a moving platform backend.",
-      "phase": "02"
-    }
-  ],
-  "uncommitted_files": [
-    ".planning/config.json",
-    "adapter/matrix/bot.py",
-    "adapter/matrix/handlers/__init__.py",
-    "adapter/matrix/handlers/auth.py",
-    "adapter/matrix/handlers/chat.py",
-    "adapter/matrix/handlers/settings.py",
-    "adapter/telegram/bot.py",
-    "sdk/mock.py",
-    "tests/adapter/matrix/test_chat_space.py",
-    "tests/adapter/matrix/test_dispatcher.py",
-    "tests/adapter/matrix/test_invite_space.py",
-    "tests/platform/test_mock.py",
-    ".planning/phases/01-matrix-qa-polish/01-01-SUMMARY.md",
-    ".planning/phases/01-matrix-qa-polish/01-04-SUMMARY.md",
-    ".planning/phases/01-matrix-qa-polish/01-05-PLAN.md",
-    ".planning/phases/01-matrix-qa-polish/01-06-PLAN.md",
-    ".planning/phases/01-matrix-qa-polish/01-VERIFICATION.md",
-    ".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.gitkeep",
-    "bot-examples/",
-    "docs/reports/2026-04-01-surfaces-progress-report.md",
-    "docs/superpowers/plans/2026-03-31-matrix-adapter.md",
-    "docs/workflow-backup-2026-04-01.md",
-    "forum_topics_research.md",
-    "image copy 2.png",
-    "image copy.png",
-    "image.png",
-    "lambda_bot.db",
-    "lambda_matrix.db"
-  ],
-  "next_action": "When resuming, either execute Phase 01.1 Plan 03 Task 1 (Matrix reset CLI) or continue the platform-integration design by defining a split MasterClient/AgentSession boundary without changing consumer adapters yet.",
-  "context_notes": "This session was research-heavy rather than implementation-heavy. The key conclusion is that the real platform currently exposes a direct agent WebSocket SDK plus an unfinished master control plane; our mock models a richer unified platform than what exists today. That means future work should isolate the integration boundary, not rush a full rewrite."
-}

.planning/PROJECT.md

@@ -14,7 +14,7 @@ Telegram и Matrix боты для взаимодействия пользова
 
 - ✓ core/ — унифицированный протокол событий, EventDispatcher, StateStore, ChatManager, AuthManager, SettingsManager — existing
 - ✓ adapter/telegram/ — forum-first адаптер (Threaded Mode), `/start`, `/new`, `/archive`, `/rename`, `/settings`, стриминг ответов — existing, QA passed
-- ✓ adapter/matrix/ — DM-first адаптер, invite flow, `!new`, `!skills`, `!soul`, `!safety`, room-per-chat — existing
+- ✓ adapter/matrix/ — Space+rooms адаптер, invite flow, `!new`, `!archive`, `!rename`, `!settings`, room-per-chat — existing
 - ✓ sdk/mock.py — MockPlatformClient: `stream_message`, `get_or_create_user`, `get_settings`, `update_settings` — existing
 
 ### Active
@@ -50,7 +50,7 @@ Telegram и Matrix боты для взаимодействия пользова
 | Forum-first (Threaded Mode) для Telegram | Bot API 9.3 позволяет личный чат как форум — чище, без суперпруппы | ✓ Good |
 | (user_id, thread_id) как PK в chats | Изоляция контекстов по топику | ✓ Good |
 | MockPlatformClient через sdk/interface.py | Не ждать SDK, разрабатывать независимо | ✓ Good |
-| DM-first для Matrix (не Space-first) | Space lifecycle слишком сложен для первого этапа | ✓ Good |
+| Space+rooms для Matrix | Room-based UX и явные чаты важнее DM-first упрощений | ✓ Good |
 | Отказ от E2EE в Matrix | python-olm не собирается на macOS/ARM | — Pending |
 
 ## Evolution

.planning/ROADMAP.md

@@ -50,6 +50,41 @@ Plans:
 - `stream_message` работает с реальным стримингом
 - Интеграционные тесты с реальным SDK (или staging)
 
+### Phase 4: Matrix MVP: shared agent context and context management commands
+
+**Goal:** Привести Matrix-бот к рабочему состоянию для MVP-деплоя: заменить AgentSessionClient на AgentApi, добавить !save/!load/!reset/!context команды управления контекстом агента, упаковать в Docker.
+**Requirements**: Replace AgentSessionClient with AgentApi; Wire AgentApi lifecycle; Implement !save, !load, !reset, !context commands; Dockerfile + docker-compose
+**Depends on:** Phase 1 (Matrix adapter complete)
+**Plans:** 3 plans
+
+Plans:
+- [x] 04-01-PLAN.md — Replace AgentSessionClient with AgentApi; update sdk/real.py, bot.py, broken tests
+- [x] 04-02-PLAN.md — !save, !load, !reset, !context handlers; PrototypeStateStore extensions; numeric interception
+- [x] 04-03-PLAN.md — Dockerfile + docker-compose.yml + .env.example update
+
+---
+
+### Phase 05: MVP Deployment
+
+**Goal:** Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru без потери Space+rooms UX: закрепить per-room `platform_chat_id`, реальный `!clear`, reconciliation, file transfer через shared volume и разделение prod/fullstack compose.
+
+**Depends on:** Phase 4
+
+**Plans:** 4/4 plans complete
+
+Plans:
+- [x] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync
+- [x] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics
+- [x] 05-03-PLAN.md — Shared-volume attachment path hardening for `/agents` deployment
+- [x] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs
+
+**Deliverables:**
+- Space+rooms onboarding remains the primary Matrix UX
+- Per-room `platform_chat_id` provides true context isolation and `!clear`
+- Reconciliation restores room metadata and routing after restart
+- File transfer uses shared `/agents/` volume with room-safe behavior
+- `docker-compose.prod.yml` is bot-only handoff; `docker-compose.fullstack.yml` is for internal E2E testing
+
 ---
 
 ### Phase 3: Production Hardening

.planning/STATE.md

@@ -2,13 +2,13 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: — Production-ready surfaces
-status: Phase 01 Complete
-last_updated: "2026-04-03T09:35:39Z"
+status: Phase 05 Paused
+last_updated: "2026-04-29T08:49:04Z"
 progress:
-  total_phases: 3
-  completed_phases: 1
-  total_plans: 6
-  completed_plans: 6
+  total_phases: 6
+  completed_phases: 3
+  total_plans: 16
+  completed_plans: 13
 ---
 
 # State
@@ -18,13 +18,41 @@ progress:
 See: .planning/PROJECT.md (updated 2026-04-02)
 
 **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра
-**Current focus:** Phase 02 — SDK Integration (blocked on Lambda platform SDK readiness)
+**Current focus:** Phase 05 paused — latest file-contract change needs a new image build before platform redeploy
 
 ## Current Phase
 
-**Phase 2** of 3: SDK Integration
+**Phase 05** paused: MVP deployment hardening is in place, but the latest attachment workspace-root change is not yet published
 
-Phase 1 is complete. Phase 2 remains blocked until the Lambda platform SDK is available.
+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
 
@@ -42,16 +70,38 @@ Phase 1 is complete. Phase 2 remains blocked until the Lambda platform SDK is av
 - [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
 
@@ -62,9 +112,18 @@ Phase 1 is complete. Phase 2 remains blocked until the Lambda platform SDK is av
 | 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:39Z |
+| 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-03T09:35:39Z
-- Stopped at: Completed 01-06-PLAN.md
+- 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

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

@@ -3,46 +3,61 @@ 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-07T21:29:48.982Z
 ---
 
 <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 inside the roadmap is still `01.1-03-PLAN.md`, which has not been implemented yet. In parallel, the platform-integration track has moved forward: the direct-agent Matrix prototype design is now approved, the implementation plan is written, and the next useful session should evaluate that spec/plan pair against the live platform repos before starting execution.
 </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 and got approval for the prototype path: keep Matrix adapter logic largely intact, add `sdk/agent_session.py`, `sdk/prototype_state.py`, and `sdk/real.py`, keep settings local, and use the direct `agent` WebSocket for real messaging.
+- Resolved the repo-placement question: the prototype stays in this repo on its own branch, not in a separate prototype repo.
+- Resolved the platform-change minimization question: prefer patching only `platform/agent`, not `platform/agent_api`, and use a tiny local WebSocket client in this repo.
+- Wrote and committed the approved design spec: `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md`.
+- Wrote the implementation plan: `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`.
 </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`.
+- Prototype evaluation follow-up: review the approved spec and plan against the platform repos before starting execution.
+- Future prototype work: 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.
+- Keep the prototype in this repo on its own branch.
+- Minimize platform-side changes by patching only `platform/agent` if possible.
 </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 is now stable enough to execute. Full SDK integration through `master` is still premature, but a working Matrix prototype can be built now by talking directly to the `agent` WebSocket and hiding the split backend reality behind `sdk/real.py`. The approved design keeps the prototype in this repo, keeps settings local, and minimizes platform changes by preferring a tiny `platform/agent` patch over broader protocol churn. For evaluation and implementation context, inspect:
+- local spec: `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md`
+- local plan: `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`
+- remote repos: `https://git.lambda.coredump.ru/platform/agent`, `https://git.lambda.coredump.ru/platform/master`, `https://git.lambda.coredump.ru/platform/agent_api`
+- local clones: `/tmp/platform-agent`, `/tmp/platform-master`, `/tmp/platform-agent_api`
 </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. Evaluate the approved prototype spec and implementation plan against the live platform repos and decide whether to start in this repo or patch `platform/agent` first.
+2. If staying on roadmap execution, implement `01.1-03-PLAN.md` Task 1 (`adapter.matrix.reset`) first.
+3. If starting prototype execution immediately, begin with Task 1 of `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`.
 </next_action>

.planning/phases/02-prototype/.continue-here.md

@@ -0,0 +1,72 @@
+---
+phase: 02-prototype
+task: 4
+total_tasks: 4
+status: paused
+last_updated: 2026-04-07T23:54:30.473Z
+---
+
+<current_state>
+The Matrix direct-agent prototype is implemented and manually proven working on branch `feat/matrix-direct-agent-prototype`. The current code path can log into Matrix, accept invites, provision the first Space/chat tree for a fresh user, and send live text messages to a patched local `platform-agent` over WebSocket. The immediate remaining engineering gap is not feature delivery but resilience: backend/provider failures can still bubble up as `PlatformError` and crash the Matrix bot process.
+</current_state>
+
+<completed_work>
+
+- Task 1: Added `sdk/agent_session.py` and transport tests for direct WebSocket messaging with collision-safe `thread_key` generation.
+- Task 2: Added `sdk/prototype_state.py` and tests for stable local user mapping, settings defaults, and mutation-safe settings copies.
+- Task 3: Added `sdk/real.py` as the `PlatformClient` implementation, fixed import-time dependency leakage, and aligned thread-key tests to the actual dispatcher contract.
+- Task 4: Wired Matrix runtime selection through `MATRIX_PLATFORM_BACKEND=real`, documented usage in `README.md`, and added dispatcher coverage for real backend selection.
+- Fixed repeat Matrix invites so the bot now `join()`s before the existing-user early return path.
+- Added Russian runbook doc `docs/matrix-direct-agent-prototype-ru.md` and pushed the branch.
+- Manually validated live bring-up using a local patched `external/platform-agent` on port 8000 plus the Matrix homeserver `https://matrix.lambda.coredump.ru`.
+</completed_work>
+
+<remaining_work>
+
+- Add graceful degradation for backend/provider failures so `PlatformError` does not crash the Matrix process.
+- Decide whether to upstream or separately push the required `external/platform-agent` patch (`1dca2c1`) that enables WebSocket `thread_id`.
+- Optionally clean up repeat-invite UX if Space/chat reprovisioning should ever happen for already-known users.
+- Optionally prepare a PR from `feat/matrix-direct-agent-prototype`.
+</remaining_work>
+
+<decisions_made>
+
+- Keep the prototype in this repo, not a separate Matrix-only repo.
+- Keep Matrix adapter logic intact and absorb backend differences inside `sdk/`.
+- Split the real backend into `AgentSessionClient` and `PrototypeStateStore` behind `RealPlatformClient`.
+- Patch only `platform-agent` for per-thread memory instead of changing both `agent` and `agent_api`.
+- Use a serialized collision-safe thread key because Matrix user IDs contain colons.
+- For repeat invites, join the room but do not recreate Space/chat state if the user is already provisioned locally.
+</decisions_made>
+
+<blockers>
+- Technical: provider/backend errors still crash the Matrix bot instead of returning a user-facing failure reply.
+- External: the required `platform-agent` patch exists only in the local clone under `external/` and is not yet upstream.
+- Operational: credentials used during manual bring-up were exposed in-session and should be rotated.
+</blockers>
+
+<context>
+The important mental model is stable. `platform/master` is still not the backend for surfaces, so the working prototype goes directly to `platform-agent` over `/agent_ws/`. The live setup that worked was:
+- `surfaces-bot` branch: `feat/matrix-direct-agent-prototype`
+- Matrix bot env: `MATRIX_PLATFORM_BACKEND=real`, `AGENT_WS_URL=ws://127.0.0.1:8000/agent_ws/`
+- patched local `external/platform-agent` with `thread_id` support
+- provider configured through OpenRouter using model `qwen/qwen3.5-122b-a10b`
+
+Important files:
+- `sdk/agent_session.py`
+- `sdk/prototype_state.py`
+- `sdk/real.py`
+- `adapter/matrix/bot.py`
+- `adapter/matrix/handlers/auth.py`
+- `docs/matrix-direct-agent-prototype-ru.md`
+
+Important local-only dependency:
+- `external/platform-agent` commit `1dca2c1` (`feat: support websocket thread ids`)
+
+Likely running background process at pause time:
+- local `platform-agent` server on port 8000, PID 13499
+</context>
+
+<next_action>
+Start with the failure path: catch `PlatformError` around Matrix message handling so a bad provider response becomes a normal reply like “backend unavailable, try again later” instead of killing the process. After that, either upstream `external/platform-agent` commit `1dca2c1` or document it as an explicit prerequisite in the platform repo.
+</next_action>

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-01-PLAN.md

@@ -0,0 +1,626 @@
+---
+phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - sdk/agent_api_wrapper.py
+  - sdk/agent_session.py
+  - sdk/real.py
+  - adapter/matrix/bot.py
+  - tests/platform/test_agent_session.py
+  - tests/platform/test_real.py
+  - tests/adapter/matrix/test_dispatcher.py
+autonomous: true
+requirements:
+  - Replace AgentSessionClient with AgentApi
+  - Wire AgentApi lifecycle into MatrixBot
+
+must_haves:
+  truths:
+    - "RealPlatformClient uses AgentApiWrapper (wraps AgentApi), not AgentSessionClient"
+    - "AgentApiWrapper is connected before sync_forever and closed in finally block of main()"
+    - "build_thread_key and AgentSessionClient are gone from sdk/"
+    - "stream_message() yields MessageChunk objects including a final chunk with tokens_used from last_tokens_used"
+    - "AGENT_WS_URL is used unchanged (no thread_id query param)"
+    - "MATRIX_PLATFORM_BACKEND=real still works end-to-end without test crash"
+    - "All existing tests pass after the swap"
+  artifacts:
+    - path: "sdk/agent_api_wrapper.py"
+      provides: "AgentApiWrapper subclass of AgentApi with last_tokens_used tracking"
+      contains: "AgentApiWrapper"
+    - path: "sdk/real.py"
+      provides: "RealPlatformClient wrapping AgentApiWrapper"
+      contains: "AgentApiWrapper"
+    - path: "adapter/matrix/bot.py"
+      provides: "main() awaits agent_api.connect() and agent_api.close()"
+      contains: "agent_api.connect"
+    - path: "tests/platform/test_real.py"
+      provides: "Updated tests using FakeAgentApi instead of FakeAgentSessionClient"
+  key_links:
+    - from: "adapter/matrix/bot.py main()"
+      to: "RealPlatformClient._agent_api"
+      via: "runtime.platform.agent_api property"
+      pattern: "agent_api\\.connect"
+    - from: "sdk/real.py stream_message()"
+      to: "agent_api.last_tokens_used"
+      via: "attribute read after async-for loop"
+      pattern: "last_tokens_used"
+---
+
+<objective>
+Replace the custom per-request AgentSessionClient with a thin AgentApiWrapper that
+subclasses AgentApi from lambda_agent_api and adds last_tokens_used tracking. Remove
+build_thread_key and AgentSessionClient entirely. Wire AgentApiWrapper connect/close
+into bot.py main(). Update all tests that referenced the old client.
+
+Do NOT modify any file under external/. The external/ directory is managed by the
+platform team. All customisation goes in sdk/agent_api_wrapper.py.
+
+Purpose: The existing AgentSessionClient creates a new WebSocket per message and
+injects thread_id into the URL — both incompatible with origin/main platform-agent.
+AgentApi maintains a single persistent WS connection managed via connect()/close()
+and exposes send_message() as an AsyncIterator. We capture tokens_used in a thin
+subclass so sdk/real.py can include it in the final MessageChunk without touching
+the upstream library.
+
+Output: sdk/agent_api_wrapper.py (new), sdk/real.py (rewritten), sdk/agent_session.py
+(stubbed), adapter/matrix/bot.py updated, tests green.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-CONTEXT.md
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-RESEARCH.md
+</context>
+
+<interfaces>
+<!-- Key types the executor needs. Read from source before touching anything. -->
+<!-- IMPORTANT: external/ files are READ-ONLY — do not modify them. -->
+
+From external/platform-agent_api/lambda_agent_api/agent_api.py (READ ONLY):
+```python
+class AgentApi:
+    def __init__(self, agent_id: str, url: str,
+                 callback=None, on_disconnect=None): ...
+    async def connect(self) -> None: ...   # opens WS, awaits MsgStatus, starts _listen task
+    async def close(self) -> None: ...     # cancels _listen, closes WS+session
+    async def send_message(self, text: str) -> AsyncIterator[AgentEventUnion]:
+        # yields MsgEventTextChunk only; breaks on MsgEventEnd (does NOT yield it)
+        # MsgEventEnd.tokens_used is consumed internally at the break point
+        ...
+    async def _listen(self) -> None:
+        # internal task: receives WS frames, puts AgentEventUnion into self._queue
+        # on MsgEventEnd: puts it in queue then breaks
+        ...
+    # AgentEventUnion = Union[MsgEventTextChunk, MsgEventEnd] per server.py
+```
+
+From external/platform-agent_api/lambda_agent_api/server.py (READ ONLY):
+```python
+class MsgEventTextChunk(BaseModel):
+    type: Literal[EServerMessage.AGENT_EVENT_TEXT_CHUNK]
+    text: str
+
+class MsgEventEnd(BaseModel):
+    type: Literal[EServerMessage.AGENT_EVENT_END]
+    tokens_used: int
+```
+
+New file to create — sdk/agent_api_wrapper.py:
+```python
+class AgentApiWrapper(AgentApi):
+    """Thin subclass of AgentApi that captures tokens_used from MsgEventEnd.
+
+    AgentApi.send_message() yields only MsgEventTextChunk and breaks silently
+    on MsgEventEnd without storing tokens_used. This wrapper overrides _listen()
+    to intercept MsgEventEnd and store tokens_used before it is discarded.
+    """
+    last_tokens_used: int = 0
+
+    async def _listen(self) -> None:
+        # Override: same as parent, but capture MsgEventEnd.tokens_used
+        ...
+```
+
+From sdk/interface.py (unchanged):
+```python
+class MessageChunk(BaseModel):
+    message_id: str
+    delta: str
+    finished: bool
+    tokens_used: int = 0
+
+class PlatformClient(Protocol):
+    async def send_message(self, user_id, chat_id, text, attachments=None) -> MessageResponse: ...
+    async def stream_message(self, user_id, chat_id, text, attachments=None) -> AsyncIterator[MessageChunk]: ...
+```
+</interfaces>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Create sdk/agent_api_wrapper.py; rewrite sdk/real.py; stub sdk/agent_session.py</name>
+
+  <read_first>
+    - sdk/real.py (full file — being replaced)
+    - sdk/agent_session.py (full file — being stubbed)
+    - external/platform-agent_api/lambda_agent_api/agent_api.py (full file — READ ONLY, inspect _listen and send_message to understand override point)
+    - external/platform-agent_api/lambda_agent_api/server.py (full file — READ ONLY, MsgEventEnd.tokens_used)
+    - sdk/interface.py (MessageChunk, PlatformClient Protocol)
+  </read_first>
+
+  <files>sdk/agent_api_wrapper.py, sdk/real.py, sdk/agent_session.py</files>
+
+  <behavior>
+    - Create sdk/agent_api_wrapper.py with class AgentApiWrapper(AgentApi):
+        - __init__: calls super().__init__(...) and adds self.last_tokens_used: int = 0
+        - Override _listen(): copy the parent _listen() logic verbatim, then at the point where MsgEventEnd is received (before or as it is put into the queue), set self.last_tokens_used = chunk.tokens_used
+        - Do NOT modify agent_api.py in external/ — subclass only
+    - RealPlatformClient.__init__ accepts agent_api: AgentApiWrapper, prototype_state: PrototypeStateStore, platform: str = "matrix"
+    - RealPlatformClient exposes agent_api as property self.agent_api so bot.py main() can call connect/close
+    - stream_message() iterates agent_api.send_message(text) yielding MessageChunk per MsgEventTextChunk chunk; after loop yields final MessageChunk(finished=True, delta="", tokens_used=agent_api.last_tokens_used)
+    - send_message() collects all chunks from stream_message() and returns MessageResponse
+    - No thread_key, no build_thread_key references anywhere in sdk/real.py
+    - sdk/agent_session.py: replace file contents with single comment stub (keep file to avoid import errors until tests are updated in Task 2)
+  </behavior>
+
+  <action>
+1. Read external/platform-agent_api/lambda_agent_api/agent_api.py fully to find the exact _listen() implementation and the line where MsgEventEnd is handled.
+
+2. Create sdk/agent_api_wrapper.py:
+```python
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Ensure lambda_agent_api is importable (same sys.path trick as bot.py)
+_api_root = Path(__file__).resolve().parents[1] / "external" / "platform-agent_api"
+if str(_api_root) not in sys.path:
+    sys.path.insert(0, str(_api_root))
+
+from lambda_agent_api.agent_api import AgentApi
+from lambda_agent_api.server import MsgEventEnd
+
+
+class AgentApiWrapper(AgentApi):
+    """Thin subclass of AgentApi that captures tokens_used from MsgEventEnd.
+
+    AgentApi.send_message() yields MsgEventTextChunk events and breaks on
+    MsgEventEnd without storing tokens_used. This wrapper overrides _listen()
+    to intercept MsgEventEnd and set self.last_tokens_used before the event
+    is discarded, so RealPlatformClient can include it in the final MessageChunk.
+
+    Do NOT modify external/platform-agent_api — subclass only.
+    """
+
+    def __init__(self, agent_id: str, url: str, **kwargs) -> None:
+        super().__init__(agent_id=agent_id, url=url, **kwargs)
+        self.last_tokens_used: int = 0
+
+    async def _listen(self) -> None:
+        # Copy parent _listen() logic.
+        # Read external/platform-agent_api/lambda_agent_api/agent_api.py _listen()
+        # and reproduce it here, adding:
+        #   if isinstance(event, MsgEventEnd):
+        #       self.last_tokens_used = event.tokens_used
+        # at the point where MsgEventEnd is processed.
+        #
+        # IMPORTANT: after reading agent_api.py, replace this entire method body
+        # with the exact parent implementation + the tokens_used capture line.
+        # Do not call super()._listen() — the parent creates a task; we need the
+        # override to run in the same task context.
+        raise NotImplementedError(
+            "Executor: replace this body with the copied _listen() from AgentApi "
+            "plus `self.last_tokens_used = event.tokens_used` at the MsgEventEnd branch."
+        )
+```
+
+   IMPORTANT NOTE FOR EXECUTOR: The `_listen()` body above is a placeholder.
+   After reading agent_api.py, copy the actual _listen() implementation from AgentApi
+   into AgentApiWrapper._listen() and insert `self.last_tokens_used = event.tokens_used`
+   at the MsgEventEnd branch. The final file must NOT contain the NotImplementedError.
+
+3. Rewrite sdk/real.py entirely:
+```python
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, AsyncIterator
+
+from sdk.interface import Attachment, MessageChunk, MessageResponse, PlatformClient, User, UserSettings
+from sdk.prototype_state import PrototypeStateStore
+
+if TYPE_CHECKING:
+    from sdk.agent_api_wrapper import AgentApiWrapper
+
+
+class RealPlatformClient(PlatformClient):
+    def __init__(
+        self,
+        agent_api: "AgentApiWrapper",
+        prototype_state: PrototypeStateStore,
+        platform: str = "matrix",
+    ) -> None:
+        self._agent_api = agent_api
+        self._prototype_state = prototype_state
+        self._platform = platform
+
+    @property
+    def agent_api(self) -> "AgentApiWrapper":
+        return self._agent_api
+
+    async def get_or_create_user(
+        self,
+        external_id: str,
+        platform: str,
+        display_name: str | None = None,
+    ) -> User:
+        return await self._prototype_state.get_or_create_user(
+            external_id=external_id,
+            platform=platform,
+            display_name=display_name,
+        )
+
+    async def send_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> MessageResponse:
+        parts: list[str] = []
+        tokens_used = 0
+        async for chunk in self.stream_message(user_id, chat_id, text, attachments):
+            if chunk.delta:
+                parts.append(chunk.delta)
+            if chunk.finished:
+                tokens_used = chunk.tokens_used
+        return MessageResponse(
+            message_id=user_id,
+            response="".join(parts),
+            tokens_used=tokens_used,
+            finished=True,
+        )
+
+    async def stream_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> AsyncIterator[MessageChunk]:
+        from lambda_agent_api.server import MsgEventTextChunk
+        async for event in self._agent_api.send_message(text):
+            if isinstance(event, MsgEventTextChunk):
+                yield MessageChunk(
+                    message_id=user_id,
+                    delta=event.text,
+                    finished=False,
+                )
+        yield MessageChunk(
+            message_id=user_id,
+            delta="",
+            finished=True,
+            tokens_used=self._agent_api.last_tokens_used,
+        )
+
+    async def get_settings(self, user_id: str) -> UserSettings:
+        return await self._prototype_state.get_settings(user_id)
+
+    async def update_settings(self, user_id: str, action) -> None:
+        await self._prototype_state.update_settings(user_id, action)
+```
+
+4. Replace sdk/agent_session.py content with:
+```python
+# Deleted in Phase 4 — replaced by AgentApiWrapper from sdk/agent_api_wrapper.py
+# File kept as stub to avoid import errors during migration; remove after test_agent_session.py is updated.
+```
+  </action>
+
+  <verify>
+    <automated>cd /Users/a/MAI/sem2/lambda/surfaces-bot && python -c "from sdk.real import RealPlatformClient; print('import ok')"</automated>
+  </verify>
+
+  <done>
+    - sdk/agent_api_wrapper.py exists with AgentApiWrapper(AgentApi), __init__ sets self.last_tokens_used = 0, _listen() override captures MsgEventEnd.tokens_used
+    - sdk/real.py imports AgentApiWrapper (not AgentSessionClient or AgentApi directly), exposes self.agent_api property
+    - sdk/real.py stream_message yields final chunk with tokens_used from agent_api.last_tokens_used
+    - external/ directory has NO modifications
+    - sdk/agent_session.py contains only a comment stub (no class definitions)
+    - `python -c "from sdk.real import RealPlatformClient"` exits 0
+    - `grep "AgentApiWrapper" sdk/real.py` returns a match
+    - `grep "last_tokens_used" sdk/agent_api_wrapper.py` returns a match
+  </done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Wire AgentApiWrapper lifecycle into bot.py main(); update all broken tests</name>
+
+  <read_first>
+    - adapter/matrix/bot.py (full file — _build_platform_from_env and main() need changes)
+    - tests/platform/test_agent_session.py (full file — delete or rewrite)
+    - tests/platform/test_real.py (full file — FakeAgentSessionClient → FakeAgentApi)
+    - tests/adapter/matrix/test_dispatcher.py (test_build_runtime_uses_real_platform — needs update)
+  </read_first>
+
+  <files>adapter/matrix/bot.py, tests/platform/test_agent_session.py, tests/platform/test_real.py, tests/adapter/matrix/test_dispatcher.py</files>
+
+  <behavior>
+    - _build_platform_from_env() returns a RealPlatformClient with an unconnected AgentApiWrapper (connect() NOT called here — called in main())
+    - main() calls await runtime.platform.agent_api.connect() after build_runtime() (only when backend is "real"; mock has no agent_api); wrap in `if hasattr(runtime.platform, "agent_api")` guard
+    - main() finally block: await agent_api.close() before await client.close()
+    - AGENT_WS_URL env var is passed unchanged to AgentApiWrapper(url=ws_url) — no query param manipulation
+    - test_agent_session.py: completely rewritten — remove all build_thread_key tests, remove AgentSessionClient tests; replace with 2 tests: (1) import check for lambda_agent_api module, (2) stub test that documents the deletion
+    - test_real.py: FakeAgentSessionClient replaced with FakeAgentApi that has send_message(text: str) -> AsyncIterator and last_tokens_used: int = 0; tests updated to construct RealPlatformClient(agent_api=FakeAgentApi(), prototype_state=PrototypeStateStore()); test_send_message no longer checks thread_key in message_id (now uses user_id); test_stream_message checks final chunk tokens_used comes from FakeAgentApi.last_tokens_used
+    - test_dispatcher.py: test_build_runtime_uses_real_platform_when_matrix_backend_is_real must NOT call agent_api.connect() (build_runtime only constructs, does not connect); update test to mock AgentApiWrapper so it does not attempt a real WS connection; assert isinstance(runtime.platform, RealPlatformClient) still passes
+  </behavior>
+
+  <action>
+1. Edit adapter/matrix/bot.py:
+
+   a. Remove imports: `from sdk.agent_session import AgentSessionClient, AgentSessionConfig`
+
+   b. In _build_platform_from_env(), use AgentApiWrapper with lazy import:
+   ```python
+   def _build_platform_from_env() -> PlatformClient:
+       backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower()
+       if backend == "real":
+           import sys
+           _api_root = Path(__file__).resolve().parents[2] / "external" / "platform-agent_api"
+           if str(_api_root) not in sys.path:
+               sys.path.insert(0, str(_api_root))
+           from sdk.agent_api_wrapper import AgentApiWrapper
+           ws_url = os.environ["AGENT_WS_URL"]
+           agent_api = AgentApiWrapper(agent_id="matrix-bot", url=ws_url)
+           return RealPlatformClient(
+               agent_api=agent_api,
+               prototype_state=PrototypeStateStore(),
+               platform="matrix",
+           )
+       return MockPlatformClient()
+   ```
+
+   c. In main(), after `runtime = build_runtime(store=SQLiteStore(db_path), client=client)`, add:
+   ```python
+   if hasattr(runtime.platform, "agent_api"):
+       await runtime.platform.agent_api.connect()
+   ```
+
+   d. In main() finally block, add before `await client.close()`:
+   ```python
+   if hasattr(runtime.platform, "agent_api"):
+       await runtime.platform.agent_api.close()
+   ```
+
+2. Rewrite tests/platform/test_agent_session.py:
+```python
+"""
+test_agent_session.py — stub after Phase 4 migration.
+
+AgentSessionClient and build_thread_key were removed in Phase 4.
+The platform client is now AgentApiWrapper wrapping AgentApi from lambda_agent_api.
+See tests/platform/test_real.py for RealPlatformClient tests.
+"""
+import sys
+from pathlib import Path
+
+_api_root = Path(__file__).resolve().parents[2] / "external" / "platform-agent_api"
+if str(_api_root) not in sys.path:
+    sys.path.insert(0, str(_api_root))
+
+
+def test_lambda_agent_api_module_importable():
+    from lambda_agent_api.agent_api import AgentApi  # noqa: F401
+    from lambda_agent_api.server import MsgEventTextChunk, MsgEventEnd  # noqa: F401
+    assert True
+
+
+def test_agent_session_module_is_stub():
+    """Ensure old module no longer exposes AgentSessionClient or build_thread_key."""
+    import sdk.agent_session as mod
+    assert not hasattr(mod, "AgentSessionClient"), "AgentSessionClient should be removed"
+    assert not hasattr(mod, "build_thread_key"), "build_thread_key should be removed"
+```
+
+3. Rewrite tests/platform/test_real.py:
+```python
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import AsyncIterator
+
+import pytest
+
+from core.protocol import SettingsAction
+from sdk.interface import MessageChunk, MessageResponse, UserSettings
+from sdk.prototype_state import PrototypeStateStore
+from sdk.real import RealPlatformClient
+
+_api_root = Path(__file__).resolve().parents[2] / "external" / "platform-agent_api"
+if str(_api_root) not in sys.path:
+    sys.path.insert(0, str(_api_root))
+
+from lambda_agent_api.server import MsgEventTextChunk, EServerMessage  # noqa: E402
+
+
+class FakeAgentApi:
+    """Minimal fake for AgentApiWrapper — no real WebSocket."""
+    def __init__(self) -> None:
+        self.last_tokens_used: int = 0
+        self.send_calls: list[str] = []
+
+    async def send_message(self, text: str) -> AsyncIterator[MsgEventTextChunk]:
+        self.send_calls.append(text)
+        self.last_tokens_used = 7
+        yield MsgEventTextChunk(type=EServerMessage.AGENT_EVENT_TEXT_CHUNK, text=text[:2])
+        yield MsgEventTextChunk(type=EServerMessage.AGENT_EVENT_TEXT_CHUNK, text=text[2:])
+        # send_message() in real AgentApi breaks on MsgEventEnd without yielding it;
+        # FakeAgentApi mirrors this by not yielding MsgEventEnd — last_tokens_used is set directly.
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_get_or_create_user_uses_local_state():
+    client = RealPlatformClient(
+        agent_api=FakeAgentApi(),
+        prototype_state=PrototypeStateStore(),
+    )
+    first = await client.get_or_create_user("u1", "matrix", "Alice")
+    second = await client.get_or_create_user("u1", "matrix")
+
+    assert first.user_id == "usr-matrix-u1"
+    assert first.is_new is True
+    assert second.user_id == first.user_id
+    assert second.is_new is False
+    assert second.display_name == "Alice"
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_send_message_calls_agent_with_text():
+    fake = FakeAgentApi()
+    client = RealPlatformClient(agent_api=fake, prototype_state=PrototypeStateStore())
+
+    result = await client.send_message("@alice:example.org", "C1", "hello")
+
+    assert result.response == "hello"
+    assert result.tokens_used == 7
+    assert fake.send_calls == ["hello"]
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_stream_message_yields_chunks_and_final_with_tokens():
+    fake = FakeAgentApi()
+    client = RealPlatformClient(agent_api=fake, prototype_state=PrototypeStateStore())
+
+    chunks = []
+    async for chunk in client.stream_message("@alice:example.org", "C1", "hello"):
+        chunks.append(chunk)
+
+    assert chunks[-1].finished is True
+    assert chunks[-1].tokens_used == 7
+    assert "".join(c.delta for c in chunks) == "hello"
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_settings_are_local():
+    client = RealPlatformClient(
+        agent_api=FakeAgentApi(),
+        prototype_state=PrototypeStateStore(),
+    )
+    await client.update_settings(
+        "usr-matrix-u1",
+        SettingsAction(action="toggle_skill", payload={"skill": "browser", "enabled": True}),
+    )
+    settings = await client.get_settings("usr-matrix-u1")
+    assert isinstance(settings, UserSettings)
+    assert settings.skills["browser"] is True
+```
+
+4. Edit tests/adapter/matrix/test_dispatcher.py — update `test_build_runtime_uses_real_platform_when_matrix_backend_is_real`:
+   - Add sys.path setup for lambda_agent_api (same pattern as above)
+   - Mock AgentApiWrapper so it does not open a real WS:
+   ```python
+   async def test_build_runtime_uses_real_platform_when_matrix_backend_is_real(monkeypatch):
+       import sys
+       from pathlib import Path
+       _api_root = Path(__file__).resolve().parents[3] / "external" / "platform-agent_api"
+       if str(_api_root) not in sys.path:
+           sys.path.insert(0, str(_api_root))
+
+       monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real")
+       monkeypatch.setenv("AGENT_WS_URL", "ws://agent.example/agent_ws/")
+
+       # Patch AgentApiWrapper to avoid real WS connection during build_runtime
+       import sdk.agent_api_wrapper as _mod
+       class _FakeAgentApiWrapper:
+           def __init__(self, agent_id, url, **kw):
+               self.last_tokens_used = 0
+           async def connect(self): pass
+           async def close(self): pass
+           async def send_message(self, text):
+               return; yield  # empty async generator
+       monkeypatch.setattr(_mod, "AgentApiWrapper", _FakeAgentApiWrapper)
+
+       from adapter.matrix.bot import build_runtime
+       from sdk.real import RealPlatformClient
+       runtime = build_runtime()
+       assert isinstance(runtime.platform, RealPlatformClient)
+   ```
+  </action>
+
+  <verify>
+    <automated>cd /Users/a/MAI/sem2/lambda/surfaces-bot && python -m pytest tests/platform/test_agent_session.py tests/platform/test_real.py tests/adapter/matrix/test_dispatcher.py -v 2>&1 | tail -20</automated>
+  </verify>
+
+  <done>
+    - All tests in test_agent_session.py, test_real.py, test_dispatcher.py pass
+    - main() in bot.py has agent_api.connect() call guarded by hasattr check
+    - main() finally block closes agent_api before matrix client
+    - grep confirms no "AgentSessionClient" or "build_thread_key" remain in sdk/real.py or adapter/matrix/bot.py
+    - grep confirms no modifications to any file under external/
+  </done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| bot → platform-agent WS | Outbound WS to agent service; input is user text |
+| env vars → bot config | AGENT_WS_URL, MATRIX_PLATFORM_BACKEND read from environment |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-01-01 | Tampering | AgentApiWrapper.send_message() text | accept | Single-user prototype; text originates from authenticated Matrix user |
+| T-04-01-02 | Denial of Service | AgentBusyException from concurrent sends | mitigate | AgentApi._request_lock already prevents concurrent sends; bot must surface error to user instead of crashing |
+| T-04-01-03 | Information Disclosure | AGENT_WS_URL in env | accept | Internal service URL; not exposed to users |
+</threat_model>
+
+<verification>
+Run full test suite after both tasks complete:
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot && python -m pytest tests/ -v 2>&1 | tail -30
+```
+
+Grep checks:
+```bash
+# No old imports should remain
+grep -r "AgentSessionClient\|build_thread_key" sdk/ adapter/ tests/ --include="*.py" | grep -v "stub\|Deleted\|removed"
+
+# AgentApiWrapper wired in bot.py
+grep "agent_api.connect\|agent_api.close" adapter/matrix/bot.py
+
+# last_tokens_used set in wrapper
+grep "last_tokens_used" sdk/agent_api_wrapper.py
+
+# No external/ files modified
+git diff --name-only external/
+```
+</verification>
+
+<success_criteria>
+- `pytest tests/platform/ tests/adapter/matrix/test_dispatcher.py -v` exits 0 with no failures
+- `grep -r "AgentSessionClient" sdk/ adapter/` returns empty (or only the stub comment)
+- `grep -r "build_thread_key" sdk/ adapter/` returns empty
+- `grep "agent_api.connect" adapter/matrix/bot.py` returns a match
+- `grep "last_tokens_used" sdk/agent_api_wrapper.py` returns the assignment line
+- `git diff --name-only external/` returns empty (external/ untouched)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-01-SUMMARY.md`
+</output>

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-01-SUMMARY.md

@@ -0,0 +1,29 @@
+# 04-01 Summary
+
+## Outcome
+
+Replaced the Matrix real backend's custom `AgentSessionClient` path with a shared
+`AgentApiWrapper` over upstream `lambda_agent_api.AgentApi`.
+
+## Changes
+
+- Added `sdk/agent_api_wrapper.py` to capture `MsgEventEnd.tokens_used` without
+  modifying `external/`.
+- Rewrote `sdk/real.py` to use a shared `agent_api`, stream text chunks from
+  `AgentApi.send_message()`, and emit a final `MessageChunk` with
+  `last_tokens_used`.
+- Updated `adapter/matrix/bot.py` to construct `RealPlatformClient` with
+  `AgentApiWrapper`, keep `AGENT_WS_URL` unchanged, and manage
+  `agent_api.connect()` / `agent_api.close()` around `sync_forever()`.
+- Stubbed `sdk/agent_session.py` as a compatibility placeholder.
+- Updated Matrix/runtime tests away from `thread_key` and per-request websocket
+  assumptions.
+
+## Verification
+
+- `pytest tests/platform/test_real.py -q`
+- `pytest tests/adapter/matrix/test_dispatcher.py -q`
+- `pytest tests/core/test_integration.py -q`
+- `pytest tests/platform/test_agent_session.py -q`
+
+All listed commands passed locally.

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-PLAN.md

@@ -0,0 +1,865 @@
+---
+phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
+plan: 02
+type: execute
+wave: 2
+depends_on:
+  - 04-01-PLAN.md
+files_modified:
+  - sdk/prototype_state.py
+  - adapter/matrix/store.py
+  - adapter/matrix/handlers/__init__.py
+  - adapter/matrix/handlers/context_commands.py
+  - adapter/matrix/bot.py
+  - tests/adapter/matrix/test_context_commands.py
+  - tests/platform/test_prototype_state.py
+autonomous: true
+requirements:
+  - Implement !save, !load, !reset, !context commands
+  - PrototypeStateStore saved sessions storage
+  - !load pending state in Matrix store
+  - !reset pending state in Matrix store
+  - Numeric input interception for !load
+
+must_haves:
+  truths:
+    - "!save sends a save prompt to the agent and records session name in PrototypeStateStore"
+    - "!load shows a numbered list of saved sessions; numeric reply selects a session"
+    - "!reset shows a confirmation dialog; !yes calls POST /reset; !no cancels"
+    - "!context returns current session name, last tokens_used, and list of saved sessions"
+    - "Numeric input intercepted in on_room_message before dispatcher.dispatch when load_pending is set"
+    - "!yes in reset_pending context calls POST {AGENT_BASE_URL}/reset and reports unavailable on 404"
+    - "All context command tests pass"
+  artifacts:
+    - path: "adapter/matrix/handlers/context_commands.py"
+      provides: "make_handle_save, make_handle_load, make_handle_reset, make_handle_context"
+    - path: "adapter/matrix/store.py"
+      provides: "get_load_pending, set_load_pending, clear_load_pending, get_reset_pending, set_reset_pending, clear_reset_pending"
+    - path: "sdk/prototype_state.py"
+      provides: "add_saved_session, list_saved_sessions, get_last_tokens_used, set_last_tokens_used"
+    - path: "tests/adapter/matrix/test_context_commands.py"
+      provides: "tests for all four commands"
+  key_links:
+    - from: "adapter/matrix/bot.py on_room_message()"
+      to: "adapter/matrix/store.get_load_pending()"
+      via: "check before dispatcher.dispatch"
+      pattern: "get_load_pending"
+    - from: "adapter/matrix/handlers/context_commands.py make_handle_reset"
+      to: "httpx.AsyncClient.post(AGENT_BASE_URL + '/reset')"
+      via: "!yes handler inside reset_pending flow"
+      pattern: "httpx"
+    - from: "sdk/real.py stream_message()"
+      to: "prototype_state.set_last_tokens_used()"
+      via: "call after final chunk"
+      pattern: "set_last_tokens_used"
+---
+
+<objective>
+Add four context management commands to the Matrix bot: !save, !load, !reset, !context.
+Extend PrototypeStateStore with saved sessions and last_tokens_used tracking. Add
+load_pending and reset_pending state keys to Matrix store. Wire numeric input
+interception in on_room_message. Register all handlers.
+
+Purpose: Users need to save, load, and reset agent context, and inspect current context
+state — essential for a shared-context MVP where one agent container persists across
+Matrix sessions.
+
+Output: context_commands.py handler module, store.py extensions, prototype_state.py
+extensions, bot.py updated, full test coverage.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-CONTEXT.md
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-RESEARCH.md
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-01-SUMMARY.md
+</context>
+
+<interfaces>
+<!-- Key contracts executor needs. Read source files before touching anything. -->
+
+From adapter/matrix/store.py (existing pattern):
+```python
+PENDING_CONFIRM_PREFIX = "matrix_pending_confirm:"
+
+def _pending_confirm_key(user_id: str, room_id: str | None = None) -> str: ...
+async def get_pending_confirm(store, user_id, room_id=None) -> dict | None: ...
+async def set_pending_confirm(store, user_id, room_id, meta) -> None: ...
+async def clear_pending_confirm(store, user_id, room_id=None) -> None: ...
+```
+
+New store keys to add (same pattern):
+```python
+LOAD_PENDING_PREFIX = "matrix_load_pending:"
+RESET_PENDING_PREFIX = "matrix_reset_pending:"
+
+# Keys: f"{PREFIX}{user_id}:{room_id}"
+# load_pending data: {"saves": [{"name": str, "created_at": str}, ...], "display": str}
+# reset_pending data: {"active": True}
+```
+
+From adapter/matrix/handlers/__init__.py (existing registration):
+```python
+def register_matrix_handlers(dispatcher: EventDispatcher, client=None, store=None) -> None:
+    dispatcher.register(IncomingCommand, "new", make_handle_new_chat(client, store))
+    ...
+```
+
+Handler closure signature (all existing handlers follow this):
+```python
+async def handle_X(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list[OutgoingEvent]:
+```
+
+New handlers use make_handle_X(agent_api, store, prototype_state) closures:
+```python
+async def _inner(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list[OutgoingEvent]:
+    ...
+return _inner
+```
+
+From sdk/prototype_state.py (PrototypeStateStore to extend):
+```python
+class PrototypeStateStore:
+    def __init__(self) -> None:
+        self._users: dict[str, User] = {}
+        self._settings: dict[str, dict[str, Any]] = {}
+    # Add:
+    # self._saved_sessions: dict[str, list[dict]] = {}
+    # self._last_tokens_used: dict[str, int] = {}
+```
+
+From core/protocol.py:
+```python
+@dataclass
+class IncomingCommand:
+    user_id: str; platform: str; chat_id: str; command: str; args: list[str]
+
+@dataclass
+class OutgoingMessage:
+    chat_id: str; text: str
+
+@dataclass
+class OutgoingUI:
+    chat_id: str; text: str; buttons: list[UIButton]
+```
+
+From sdk/real.py (after Plan 01):
+```python
+class RealPlatformClient:
+    async def stream_message(self, user_id, chat_id, text, ...) -> AsyncIterator[MessageChunk]:
+        # yields chunks; last chunk has finished=True, tokens_used=agent_api.last_tokens_used
+```
+
+SAVE_PROMPT template (Claude's Discretion):
+```python
+SAVE_PROMPT = (
+    "Summarize our conversation and save to /workspace/contexts/{name}.md. "
+    "Reply only with: Saved: {name}"
+)
+
+LOAD_PROMPT = (
+    "Load context from /workspace/contexts/{name}.md and use it as background "
+    "for our conversation. Reply: Loaded: {name}"
+)
+```
+
+Auto-name format for !save without args: `context-{YYYYMMDD-HHMMSS}` UTC.
+HTTP client for POST /reset: httpx.AsyncClient (already in pyproject.toml deps).
+AGENT_BASE_URL env var: `os.environ.get("AGENT_BASE_URL", "http://127.0.0.1:8000")`
+</interfaces>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Extend PrototypeStateStore and Matrix store with pending state helpers</name>
+
+  <read_first>
+    - sdk/prototype_state.py (full file — adding saved_sessions and last_tokens_used)
+    - adapter/matrix/store.py (full file — adding load_pending and reset_pending helpers)
+    - tests/platform/test_prototype_state.py (full file — adding new test cases)
+  </read_first>
+
+  <files>sdk/prototype_state.py, adapter/matrix/store.py, tests/platform/test_prototype_state.py</files>
+
+  <behavior>
+    - PrototypeStateStore.__init__ adds: self._saved_sessions: dict[str, list[dict]] = {} and self._last_tokens_used: dict[str, int] = {}
+    - add_saved_session(user_id: str, name: str) -> None: appends {"name": name, "created_at": datetime.now(UTC).isoformat()} to _saved_sessions[user_id]
+    - list_saved_sessions(user_id: str) -> list[dict]: returns copy of _saved_sessions.get(user_id, [])
+    - get_last_tokens_used(user_id: str) -> int: returns _last_tokens_used.get(user_id, 0)
+    - set_last_tokens_used(user_id: str, tokens: int) -> None: sets _last_tokens_used[user_id] = tokens
+    - adapter/matrix/store.py adds LOAD_PENDING_PREFIX and RESET_PENDING_PREFIX constants
+    - get_load_pending(store, user_id, room_id) -> dict | None
+    - set_load_pending(store, user_id, room_id, data: dict) -> None
+    - clear_load_pending(store, user_id, room_id) -> None
+    - get_reset_pending(store, user_id, room_id) -> dict | None
+    - set_reset_pending(store, user_id, room_id, data: dict) -> None
+    - clear_reset_pending(store, user_id, room_id) -> None
+    - test_prototype_state.py gets 4 new tests: add/list saved sessions, last_tokens_used get/set
+  </behavior>
+
+  <action>
+1. Edit sdk/prototype_state.py — add to __init__ and add four new async methods:
+
+In __init__ after existing attributes:
+```python
+        self._saved_sessions: dict[str, list[dict]] = {}
+        self._last_tokens_used: dict[str, int] = {}
+```
+
+After update_settings() method, add:
+```python
+    async def add_saved_session(self, user_id: str, name: str) -> None:
+        sessions = self._saved_sessions.setdefault(user_id, [])
+        sessions.append({"name": name, "created_at": datetime.now(UTC).isoformat()})
+
+    async def list_saved_sessions(self, user_id: str) -> list[dict]:
+        return list(self._saved_sessions.get(user_id, []))
+
+    async def get_last_tokens_used(self, user_id: str) -> int:
+        return self._last_tokens_used.get(user_id, 0)
+
+    async def set_last_tokens_used(self, user_id: str, tokens: int) -> None:
+        self._last_tokens_used[user_id] = tokens
+```
+
+2. Edit adapter/matrix/store.py — add after existing constants and helpers:
+
+After PENDING_CONFIRM_PREFIX line, add:
+```python
+LOAD_PENDING_PREFIX = "matrix_load_pending:"
+RESET_PENDING_PREFIX = "matrix_reset_pending:"
+```
+
+After clear_pending_confirm(), add:
+```python
+def _load_pending_key(user_id: str, room_id: str) -> str:
+    return f"{LOAD_PENDING_PREFIX}{user_id}:{room_id}"
+
+async def get_load_pending(store: StateStore, user_id: str, room_id: str) -> dict | None:
+    return await store.get(_load_pending_key(user_id, room_id))
+
+async def set_load_pending(store: StateStore, user_id: str, room_id: str, data: dict) -> None:
+    await store.set(_load_pending_key(user_id, room_id), data)
+
+async def clear_load_pending(store: StateStore, user_id: str, room_id: str) -> None:
+    await store.delete(_load_pending_key(user_id, room_id))
+
+
+def _reset_pending_key(user_id: str, room_id: str) -> str:
+    return f"{RESET_PENDING_PREFIX}{user_id}:{room_id}"
+
+async def get_reset_pending(store: StateStore, user_id: str, room_id: str) -> dict | None:
+    return await store.get(_reset_pending_key(user_id, room_id))
+
+async def set_reset_pending(store: StateStore, user_id: str, room_id: str, data: dict) -> None:
+    await store.set(_reset_pending_key(user_id, room_id), data)
+
+async def clear_reset_pending(store: StateStore, user_id: str, room_id: str) -> None:
+    await store.delete(_reset_pending_key(user_id, room_id))
+```
+
+3. Edit tests/platform/test_prototype_state.py — append four new tests:
+
+```python
+@pytest.mark.asyncio
+async def test_saved_sessions_add_and_list():
+    store = PrototypeStateStore()
+    await store.add_saved_session("u1", "my-save")
+    await store.add_saved_session("u1", "another-save")
+    sessions = await store.list_saved_sessions("u1")
+    assert len(sessions) == 2
+    assert sessions[0]["name"] == "my-save"
+    assert "created_at" in sessions[0]
+    assert sessions[1]["name"] == "another-save"
+
+
+@pytest.mark.asyncio
+async def test_saved_sessions_list_returns_copy():
+    store = PrototypeStateStore()
+    await store.add_saved_session("u1", "my-save")
+    sessions = await store.list_saved_sessions("u1")
+    sessions.append({"name": "injected"})
+    sessions2 = await store.list_saved_sessions("u1")
+    assert len(sessions2) == 1
+
+
+@pytest.mark.asyncio
+async def test_last_tokens_used_default_zero():
+    store = PrototypeStateStore()
+    assert await store.get_last_tokens_used("u1") == 0
+
+
+@pytest.mark.asyncio
+async def test_last_tokens_used_set_and_get():
+    store = PrototypeStateStore()
+    await store.set_last_tokens_used("u1", 42)
+    assert await store.get_last_tokens_used("u1") == 42
+```
+  </action>
+
+  <verify>
+    <automated>cd /Users/a/MAI/sem2/lambda/surfaces-bot && python -m pytest tests/platform/test_prototype_state.py -v 2>&1 | tail -15</automated>
+  </verify>
+
+  <done>
+    - PrototypeStateStore has add_saved_session, list_saved_sessions, get_last_tokens_used, set_last_tokens_used
+    - adapter/matrix/store.py has LOAD_PENDING_PREFIX, RESET_PENDING_PREFIX, and 6 new helper functions
+    - All test_prototype_state.py tests pass (including 4 new ones)
+    - `grep "add_saved_session\|list_saved_sessions" sdk/prototype_state.py` returns matches
+    - `grep "LOAD_PENDING_PREFIX\|RESET_PENDING_PREFIX" adapter/matrix/store.py` returns matches
+  </done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Implement context_commands.py handlers, wire into __init__.py and bot.py, update tokens_used tracking in real.py</name>
+
+  <read_first>
+    - adapter/matrix/handlers/__init__.py (full file — adding registrations)
+    - adapter/matrix/handlers/confirm.py (full file — example of make_handle_X closure pattern with store)
+    - adapter/matrix/bot.py (full file — on_room_message and build_runtime need changes)
+    - sdk/real.py (after Plan 01 — add set_last_tokens_used call after stream_message)
+    - adapter/matrix/store.py (after Task 1 — load_pending/reset_pending helpers now available)
+    - sdk/prototype_state.py (after Task 1 — saved_sessions methods available)
+  </read_first>
+
+  <files>
+    adapter/matrix/handlers/context_commands.py,
+    adapter/matrix/handlers/__init__.py,
+    adapter/matrix/bot.py,
+    sdk/real.py,
+    tests/adapter/matrix/test_context_commands.py
+  </files>
+
+  <behavior>
+    - context_commands.py exports: make_handle_save, make_handle_load, make_handle_reset, make_handle_context
+    - make_handle_save(agent_api, store, prototype_state) -> handler:
+        !save with no args: auto-name = f"context-{datetime.now(UTC).strftime('%Y%m%d-%H%M%S')}"
+        !save [name]: use args[0] as name
+        sends SAVE_PROMPT via platform.send_message (NOT stream — simple blocking send)
+        calls prototype_state.add_saved_session(event.user_id, name)
+        returns [OutgoingMessage(chat_id=event.chat_id, text=f"Сохранение запущено: {name}")]
+    - make_handle_load(agent_api, store, prototype_state) -> handler:
+        !load: fetches sessions = await prototype_state.list_saved_sessions(event.user_id)
+        if empty: returns [OutgoingMessage(chat_id=..., text="Нет сохранённых сессий. Используй !save [имя].")]
+        else: builds numbered display text, stores load_pending via set_load_pending(store, event.user_id, room_id, {"saves": sessions})
+        room_id is in event.chat_id (in Matrix adapter, chat_id == room_id for commands)
+        returns [OutgoingMessage(chat_id=..., text=display_text + "\nВведи номер или 0 / !cancel для отмены.")]
+    - Numeric input interception in MatrixBot.on_room_message():
+        Before dispatcher.dispatch, check load_pending = await get_load_pending(runtime.store, sender, room_id)
+        If load_pending and msg text is digit: handle_load_selection(pending, selection, ...)
+        handle_load_selection: if text == "0" or "!cancel" → clear_load_pending, return [OutgoingMessage("Отменено")]
+        if valid index → clear_load_pending, send LOAD_PROMPT via platform.send_message, add session as current_session in prototype_state (store in dict), return [OutgoingMessage("Загрузка: {name}")]
+        if invalid index → return [OutgoingMessage("Неверный номер. Введи от 1 до N или 0 для отмены.")]
+    - make_handle_reset(store, agent_base_url) -> handler:
+        !reset: set reset_pending, return [OutgoingMessage with text:
+          "Сбросить контекст агента? Выбери:\n  !yes — сбросить\n  !save [имя] — сохранить и сбросить\n  !no — отмена")]
+        !yes in reset_pending: call POST {AGENT_BASE_URL}/reset via httpx; if 404 or connection error → "Reset endpoint недоступен. Обратитесь к администратору."; else "Контекст сброшен."; clear reset_pending
+        !no in reset_pending: clear reset_pending, return [OutgoingMessage("Отменено.")]
+        !save имя in reset_pending: delegate to save logic, then POST /reset (same fallback)
+        Reset_pending check must happen BEFORE pending_confirm in handler priority — implement by checking reset_pending in the !yes and !no handlers (make_handle_confirm must check reset_pending first)
+    - make_handle_context(store, prototype_state) -> handler:
+        reads current_session from prototype_state._current_session dict (keyed by user_id) if it exists
+        reads tokens = await prototype_state.get_last_tokens_used(event.user_id)
+        reads sessions = await prototype_state.list_saved_sessions(event.user_id)
+        formats: "Контекст:\n  Сессия: {name or 'не загружена'}\n  Токены (последний ответ): {tokens}\n  Сохранения ({len}):\n  {list}"
+        returns [OutgoingMessage(chat_id=..., text=formatted)]
+    - sdk/real.py: after the final yield in stream_message, call await self._prototype_state.set_last_tokens_used(user_id, self._agent_api.last_tokens_used) — needs prototype_state reference already present in RealPlatformClient
+    - PrototypeStateStore gets one more dict: self._current_session: dict[str, str] = {} and methods get_current_session(user_id) -> str | None, set_current_session(user_id, name) -> None
+    - register_matrix_handlers() updated to accept agent_api and agent_base_url params; registers save/load/reset/context
+  </behavior>
+
+  <action>
+1. Add to sdk/prototype_state.py __init__: `self._current_session: dict[str, str] = {}`
+   Add methods:
+   ```python
+   async def get_current_session(self, user_id: str) -> str | None:
+       return self._current_session.get(user_id)
+
+   async def set_current_session(self, user_id: str, name: str) -> None:
+       self._current_session[user_id] = name
+   ```
+
+2. Create adapter/matrix/handlers/context_commands.py:
+
+```python
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+import httpx
+import structlog
+
+from core.protocol import IncomingCommand, OutgoingEvent, OutgoingMessage
+
+if TYPE_CHECKING:
+    from lambda_agent_api.agent_api import AgentApi
+    from sdk.prototype_state import PrototypeStateStore
+    from core.store import StateStore
+
+logger = structlog.get_logger(__name__)
+
+SAVE_PROMPT = (
+    "Summarize our conversation and save to /workspace/contexts/{name}.md. "
+    "Reply only with: Saved: {name}"
+)
+
+LOAD_PROMPT = (
+    "Load context from /workspace/contexts/{name}.md and use it as background "
+    "for our conversation. Reply: Loaded: {name}"
+)
+
+
+def make_handle_save(agent_api: "AgentApi", store: "StateStore", prototype_state: "PrototypeStateStore"):
+    async def handle_save(
+        event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+    ) -> list[OutgoingEvent]:
+        if event.args:
+            name = event.args[0]
+        else:
+            name = f"context-{datetime.now(UTC).strftime('%Y%m%d-%H%M%S')}"
+
+        prompt = SAVE_PROMPT.format(name=name)
+        try:
+            await platform.send_message(event.user_id, event.chat_id, prompt)
+        except Exception as exc:
+            logger.warning("save_agent_call_failed", error=str(exc))
+            return [OutgoingMessage(chat_id=event.chat_id, text=f"Ошибка при сохранении: {exc}")]
+
+        await prototype_state.add_saved_session(event.user_id, name)
+        return [OutgoingMessage(chat_id=event.chat_id, text=f"Сохранение запущено: {name}")]
+
+    return handle_save
+
+
+def make_handle_load(store: "StateStore", prototype_state: "PrototypeStateStore"):
+    async def handle_load(
+        event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+    ) -> list[OutgoingEvent]:
+        from adapter.matrix.store import set_load_pending
+
+        sessions = await prototype_state.list_saved_sessions(event.user_id)
+        if not sessions:
+            return [OutgoingMessage(
+                chat_id=event.chat_id,
+                text="Нет сохранённых сессий. Используй !save [имя].",
+            )]
+
+        lines = ["Сохранённые сессии:"]
+        for i, s in enumerate(sessions, start=1):
+            created = s.get("created_at", "")[:10]
+            lines.append(f"  {i}. {s['name']} ({created})")
+        lines.append("\nВведи номер или 0 / !cancel для отмены.")
+        display = "\n".join(lines)
+
+        await set_load_pending(store, event.user_id, event.chat_id, {"saves": sessions})
+        return [OutgoingMessage(chat_id=event.chat_id, text=display)]
+
+    return handle_load
+
+
+def make_handle_reset(store: "StateStore", agent_base_url: str):
+    async def handle_reset(
+        event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+    ) -> list[OutgoingEvent]:
+        from adapter.matrix.store import set_reset_pending
+
+        await set_reset_pending(store, event.user_id, event.chat_id, {"active": True})
+        text = (
+            "Сбросить контекст агента? Выбери:\n"
+            "  !yes — сбросить\n"
+            "  !save [имя] — сохранить и сбросить\n"
+            "  !no — отмена"
+        )
+        return [OutgoingMessage(chat_id=event.chat_id, text=text)]
+
+    return handle_reset
+
+
+async def _call_reset_endpoint(agent_base_url: str, chat_id: str) -> list[OutgoingEvent]:
+    try:
+        async with httpx.AsyncClient() as http:
+            resp = await http.post(f"{agent_base_url}/reset", timeout=5.0)
+        if resp.status_code == 404:
+            return [OutgoingMessage(chat_id=chat_id, text="Reset endpoint недоступен. Обратитесь к администратору.")]
+        return [OutgoingMessage(chat_id=chat_id, text="Контекст сброшен.")]
+    except (httpx.ConnectError, httpx.TimeoutException) as exc:
+        logger.warning("reset_endpoint_unreachable", error=str(exc))
+        return [OutgoingMessage(chat_id=chat_id, text="Reset endpoint недоступен. Обратитесь к администратору.")]
+
+
+def make_handle_context(store: "StateStore", prototype_state: "PrototypeStateStore"):
+    async def handle_context(
+        event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+    ) -> list[OutgoingEvent]:
+        session_name = await prototype_state.get_current_session(event.user_id) or "не загружена"
+        tokens = await prototype_state.get_last_tokens_used(event.user_id)
+        sessions = await prototype_state.list_saved_sessions(event.user_id)
+
+        lines = [
+            "Контекст:",
+            f"  Сессия: {session_name}",
+            f"  Токены (последний ответ): {tokens}",
+            f"  Сохранения ({len(sessions)}):",
+        ]
+        for s in sessions:
+            created = s.get("created_at", "")[:10]
+            lines.append(f"    • {s['name']} ({created})")
+        if not sessions:
+            lines.append("    (нет)")
+
+        return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))]
+
+    return handle_context
+```
+
+3. Edit adapter/matrix/handlers/__init__.py:
+   - Add import at top: `from adapter.matrix.handlers.context_commands import make_handle_save, make_handle_load, make_handle_reset, make_handle_context`
+   - Change signature: `def register_matrix_handlers(dispatcher, client=None, store=None, agent_api=None, prototype_state=None, agent_base_url="http://127.0.0.1:8000") -> None:`
+   - Add at bottom of function before the last line:
+     ```python
+     if agent_api is not None and prototype_state is not None:
+         dispatcher.register(IncomingCommand, "save",    make_handle_save(agent_api, store, prototype_state))
+         dispatcher.register(IncomingCommand, "load",    make_handle_load(store, prototype_state))
+         dispatcher.register(IncomingCommand, "reset",   make_handle_reset(store, agent_base_url))
+         dispatcher.register(IncomingCommand, "context", make_handle_context(store, prototype_state))
+     ```
+
+4. Edit adapter/matrix/bot.py:
+   a. Add imports: `from adapter.matrix.store import get_load_pending, clear_load_pending, get_reset_pending, clear_reset_pending`
+   b. In build_event_dispatcher() and build_runtime(), extract prototype_state from platform if RealPlatformClient, otherwise create new one:
+      In build_runtime() after creating platform:
+      ```python
+      prototype_state = getattr(platform, "_prototype_state", None)
+      agent_api = getattr(platform, "_agent_api", None)
+      agent_base_url = os.environ.get("AGENT_BASE_URL", "http://127.0.0.1:8000")
+      ```
+      Pass these to register_matrix_handlers:
+      ```python
+      register_matrix_handlers(dispatcher, client=client, store=store,
+                               agent_api=agent_api, prototype_state=prototype_state,
+                               agent_base_url=agent_base_url)
+      ```
+   c. In MatrixBot.on_room_message(), before `incoming = from_room_event(...)`:
+      ```python
+      sender = getattr(event, "sender", None)
+      # !load numeric interception
+      load_pending = await get_load_pending(self.runtime.store, sender, room.room_id)
+      if load_pending is not None:
+          text = getattr(event, "body", "").strip()
+          if text.isdigit() or text == "0" or text == "!cancel":
+              outgoing = await self._handle_load_selection(
+                  sender, room.room_id, text, load_pending
+              )
+              await self._send_all(room.room_id, outgoing)
+              return
+      ```
+   d. Add _handle_load_selection method to MatrixBot:
+      ```python
+      async def _handle_load_selection(
+          self, user_id: str, room_id: str, text: str, pending: dict
+      ) -> list[OutgoingEvent]:
+          from adapter.matrix.store import clear_load_pending
+          saves = pending.get("saves", [])
+          if text == "0" or text == "!cancel":
+              await clear_load_pending(self.runtime.store, user_id, room_id)
+              return [OutgoingMessage(chat_id=room_id, text="Отменено.")]
+          idx = int(text) - 1
+          if idx < 0 or idx >= len(saves):
+              return [OutgoingMessage(chat_id=room_id, text=f"Неверный номер. Введи от 1 до {len(saves)} или 0 для отмены.")]
+          name = saves[idx]["name"]
+          await clear_load_pending(self.runtime.store, user_id, room_id)
+          prototype_state = getattr(self.runtime.platform, "_prototype_state", None)
+          if prototype_state is not None:
+              await prototype_state.set_current_session(user_id, name)
+          prompt = f"Load context from /workspace/contexts/{name}.md and use it as background for our conversation. Reply: Loaded: {name}"
+          try:
+              await self.runtime.platform.send_message(user_id, room_id, prompt)
+          except Exception as exc:
+              logger.warning("load_agent_call_failed", error=str(exc))
+              return [OutgoingMessage(chat_id=room_id, text=f"Ошибка при загрузке: {exc}")]
+          return [OutgoingMessage(chat_id=room_id, text=f"Загрузка: {name}")]
+      ```
+   e. In MatrixBot.on_room_message(), also add reset_pending check for !yes/!no/!save commands:
+      In the block after load_pending check, before calling dispatcher.dispatch:
+      ```python
+      # !reset pending interception for !yes, !no, !save commands
+      reset_pending = await get_reset_pending(self.runtime.store, sender, room.room_id)
+      if reset_pending is not None:
+          body = getattr(event, "body", "").strip()
+          if body == "!yes" or body.startswith("!save ") or body == "!no":
+              outgoing = await self._handle_reset_selection(sender, room.room_id, body)
+              await self._send_all(room.room_id, outgoing)
+              return
+      ```
+   f. Add _handle_reset_selection method to MatrixBot:
+      ```python
+      async def _handle_reset_selection(
+          self, user_id: str, room_id: str, text: str
+      ) -> list[OutgoingEvent]:
+          from adapter.matrix.store import clear_reset_pending
+          from adapter.matrix.handlers.context_commands import _call_reset_endpoint
+          agent_base_url = os.environ.get("AGENT_BASE_URL", "http://127.0.0.1:8000")
+          await clear_reset_pending(self.runtime.store, user_id, room_id)
+          if text == "!no":
+              return [OutgoingMessage(chat_id=room_id, text="Отменено.")]
+          if text.startswith("!save "):
+              name = text[len("!save "):].strip()
+              prototype_state = getattr(self.runtime.platform, "_prototype_state", None)
+              prompt = f"Summarize our conversation and save to /workspace/contexts/{name}.md. Reply only with: Saved: {name}"
+              try:
+                  await self.runtime.platform.send_message(user_id, room_id, prompt)
+                  if prototype_state:
+                      await prototype_state.add_saved_session(user_id, name)
+              except Exception as exc:
+                  logger.warning("save_before_reset_failed", error=str(exc))
+          return await _call_reset_endpoint(agent_base_url, room_id)
+      ```
+
+5. Edit sdk/real.py — in stream_message(), after the final yield, add:
+   ```python
+   await self._prototype_state.set_last_tokens_used(user_id, self._agent_api.last_tokens_used)
+   ```
+   (This must come after `yield MessageChunk(finished=True, ...)` — use a local variable to store tokens_used before yield, then call set_last_tokens_used after the generator resumes.)
+   Actually: put it before the final yield:
+   ```python
+   await self._prototype_state.set_last_tokens_used(user_id, self._agent_api.last_tokens_used)
+   yield MessageChunk(
+       message_id=user_id,
+       delta="",
+       finished=True,
+       tokens_used=self._agent_api.last_tokens_used,
+   )
+   ```
+
+6. Create tests/adapter/matrix/test_context_commands.py:
+
+```python
+from __future__ import annotations
+
+from typing import AsyncIterator
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from adapter.matrix.bot import MatrixBot, build_runtime
+from core.protocol import IncomingCommand, OutgoingMessage
+from sdk.mock import MockPlatformClient
+from sdk.prototype_state import PrototypeStateStore
+
+
+def make_runtime_with_prototype_state():
+    proto = PrototypeStateStore()
+    platform = MockPlatformClient()
+    # Inject prototype_state into platform so handlers can find it
+    platform._prototype_state = proto
+    runtime = build_runtime(platform=platform)
+    return runtime, proto
+
+
+@pytest.mark.asyncio
+async def test_save_command_auto_name_records_session():
+    proto = PrototypeStateStore()
+    platform = MockPlatformClient()
+    platform._prototype_state = proto
+
+    from adapter.matrix.handlers.context_commands import make_handle_save
+    from core.store import InMemoryStore
+
+    store = InMemoryStore()
+    handler = make_handle_save(agent_api=None, store=store, prototype_state=proto)
+
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="!room:example", command="save", args=[])
+
+    class FakePlatform:
+        async def send_message(self, *a, **kw): pass
+
+    result = await handler(event, None, FakePlatform(), None, None)
+    assert any(isinstance(r, OutgoingMessage) and "Сохранение запущено" in r.text for r in result)
+    sessions = await proto.list_saved_sessions("u1")
+    assert len(sessions) == 1
+    assert sessions[0]["name"].startswith("context-")
+
+
+@pytest.mark.asyncio
+async def test_save_command_with_name_uses_given_name():
+    proto = PrototypeStateStore()
+    from adapter.matrix.handlers.context_commands import make_handle_save
+    from core.store import InMemoryStore
+
+    store = InMemoryStore()
+    handler = make_handle_save(agent_api=None, store=store, prototype_state=proto)
+
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="!r:e", command="save", args=["my-session"])
+
+    class FakePlatform:
+        async def send_message(self, *a, **kw): pass
+
+    await handler(event, None, FakePlatform(), None, None)
+    sessions = await proto.list_saved_sessions("u1")
+    assert sessions[0]["name"] == "my-session"
+
+
+@pytest.mark.asyncio
+async def test_load_command_shows_numbered_list():
+    proto = PrototypeStateStore()
+    await proto.add_saved_session("u1", "session-A")
+    await proto.add_saved_session("u1", "session-B")
+
+    from adapter.matrix.handlers.context_commands import make_handle_load
+    from core.store import InMemoryStore
+
+    store = InMemoryStore()
+    handler = make_handle_load(store=store, prototype_state=proto)
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="!r:e", command="load", args=[])
+
+    result = await handler(event, None, None, None, None)
+    assert len(result) == 1
+    text = result[0].text
+    assert "1." in text and "session-A" in text
+    assert "2." in text and "session-B" in text
+    assert "0" in text
+
+
+@pytest.mark.asyncio
+async def test_load_command_empty_sessions():
+    proto = PrototypeStateStore()
+    from adapter.matrix.handlers.context_commands import make_handle_load
+    from core.store import InMemoryStore
+
+    store = InMemoryStore()
+    handler = make_handle_load(store=store, prototype_state=proto)
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="!r:e", command="load", args=[])
+
+    result = await handler(event, None, None, None, None)
+    assert "Нет сохранённых сессий" in result[0].text
+
+
+@pytest.mark.asyncio
+async def test_reset_command_shows_dialog():
+    proto = PrototypeStateStore()
+    from adapter.matrix.handlers.context_commands import make_handle_reset
+    from core.store import InMemoryStore
+
+    store = InMemoryStore()
+    handler = make_handle_reset(store=store, agent_base_url="http://127.0.0.1:8000")
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="!r:e", command="reset", args=[])
+
+    result = await handler(event, None, None, None, None)
+    text = result[0].text
+    assert "!yes" in text
+    assert "!save" in text
+    assert "!no" in text
+
+
+@pytest.mark.asyncio
+async def test_reset_yes_reports_unavailable_when_endpoint_missing():
+    from adapter.matrix.handlers.context_commands import _call_reset_endpoint
+
+    with patch("httpx.AsyncClient") as MockClient:
+        import httpx
+        MockClient.return_value.__aenter__ = AsyncMock(return_value=MockClient.return_value)
+        MockClient.return_value.__aexit__ = AsyncMock(return_value=False)
+        MockClient.return_value.post = AsyncMock(side_effect=httpx.ConnectError("refused"))
+
+        result = await _call_reset_endpoint("http://127.0.0.1:8000", "!r:e")
+        assert "недоступен" in result[0].text
+
+
+@pytest.mark.asyncio
+async def test_context_command_shows_snapshot():
+    proto = PrototypeStateStore()
+    await proto.set_last_tokens_used("u1", 99)
+    await proto.add_saved_session("u1", "my-save")
+
+    from adapter.matrix.handlers.context_commands import make_handle_context
+    from core.store import InMemoryStore
+
+    store = InMemoryStore()
+    handler = make_handle_context(store=store, prototype_state=proto)
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="!r:e", command="context", args=[])
+
+    result = await handler(event, None, None, None, None)
+    text = result[0].text
+    assert "99" in text
+    assert "my-save" in text
+    assert "не загружена" in text
+```
+  </action>
+
+  <verify>
+    <automated>cd /Users/a/MAI/sem2/lambda/surfaces-bot && python -m pytest tests/adapter/matrix/test_context_commands.py tests/platform/test_prototype_state.py -v 2>&1 | tail -20</automated>
+  </verify>
+
+  <done>
+    - adapter/matrix/handlers/context_commands.py exists with make_handle_save, make_handle_load, make_handle_reset, make_handle_context, _call_reset_endpoint
+    - register_matrix_handlers() signature accepts agent_api, prototype_state, agent_base_url; registers save/load/reset/context handlers when agent_api is not None
+    - MatrixBot.on_room_message() checks load_pending and reset_pending before dispatcher.dispatch
+    - sdk/real.py calls set_last_tokens_used before final yield
+    - All tests in test_context_commands.py pass
+    - Full test suite still passes: `pytest tests/ -v` exits 0
+  </done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Matrix user → command args | !save [name] arg is user-controlled; used in file paths |
+| bot → agent (save/load prompts) | Prompt text contains user-supplied name |
+| bot → POST /reset endpoint | HTTP call to AGENT_BASE_URL (internal service) |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-02-01 | Tampering | !save name arg used in /workspace/contexts/{name}.md path | mitigate | Sanitize name: only allow [a-zA-Z0-9_-] characters; reject path traversal attempts (names containing "/" or "..") |
+| T-04-02-02 | Information Disclosure | !context exposes tokens_used and session names | accept | Single-user prototype; data is the user's own |
+| T-04-02-03 | Denial of Service | !load numeric interception could loop if load_pending never clears | mitigate | clear_load_pending on selection (any) or disconnect; pending data is volatile in-memory |
+| T-04-02-04 | Spoofing | !yes intercepted by reset_pending could conflict with pending_confirm | mitigate | Reset_pending check in on_room_message before dispatcher — takes priority; documented in code comment |
+| T-04-02-05 | Tampering | POST /reset to AGENT_BASE_URL | accept | Internal service URL from env; timeout=5.0 prevents hanging |
+</threat_model>
+
+<verification>
+Run full suite after both tasks:
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot && python -m pytest tests/ -v 2>&1 | tail -30
+```
+
+Grep checks:
+```bash
+# Handlers registered
+grep "save\|load\|reset\|context" adapter/matrix/handlers/__init__.py
+
+# Numeric interception in bot
+grep "get_load_pending\|_handle_load_selection" adapter/matrix/bot.py
+
+# tokens tracking in real.py
+grep "set_last_tokens_used" sdk/real.py
+
+# context_commands module
+ls adapter/matrix/handlers/context_commands.py
+```
+</verification>
+
+<success_criteria>
+- `pytest tests/adapter/matrix/test_context_commands.py -v` exits 0 with 7+ tests passing
+- `pytest tests/platform/test_prototype_state.py -v` exits 0 (including 4 new tests)
+- `pytest tests/ -v` exits 0
+- !save, !load, !reset, !context all registered in register_matrix_handlers
+- load_pending and reset_pending helpers exist in adapter/matrix/store.py
+- MatrixBot.on_room_message contains numeric interception for !load
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-SUMMARY.md`
+</output>

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-SUMMARY.md

@@ -0,0 +1,40 @@
+# Phase 04 Plan 02: Matrix Context Commands Summary
+
+## Outcome
+
+Added Matrix context management for `!save`, `!load`, `!reset`, and `!context`, plus
+pending-state interception in the Matrix bot and prototype-state tracking for saved
+sessions, current session, and last token usage.
+
+## Commits
+
+- `2720ee2` `feat(04-02): extend prototype and matrix pending state`
+- `b52fdc4` `feat(04-02): add matrix context management commands`
+
+## Verification
+
+- `pytest tests/platform/test_prototype_state.py -q`
+- `pytest tests/adapter/matrix/test_context_commands.py tests/platform/test_prototype_state.py -q`
+- `pytest tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_confirm.py -q`
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+1. `[Rule 2 - Critical functionality]` Sanitized save names before using them in save/load prompts.
+   This rejects names outside `[A-Za-z0-9_-]` and prevents path-like input from flowing into `/workspace/contexts/{name}.md`.
+
+2. `[Rule 2 - Critical functionality]` Cleared the active current-session marker on reset.
+   Without this, `!context` could report a stale loaded session after `!reset`.
+
+## Files Changed
+
+- `sdk/prototype_state.py`
+- `adapter/matrix/store.py`
+- `adapter/matrix/handlers/__init__.py`
+- `adapter/matrix/handlers/context_commands.py`
+- `adapter/matrix/bot.py`
+- `tests/adapter/matrix/test_context_commands.py`
+- `tests/platform/test_prototype_state.py`
+
+## Self-Check: PASSED

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-PLAN.md

@@ -0,0 +1,193 @@
+---
+phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
+plan: 03
+type: execute
+wave: 2
+depends_on:
+  - 04-01-PLAN.md
+files_modified:
+  - Dockerfile
+  - docker-compose.yml
+  - .env.example
+autonomous: true
+requirements:
+  - Dockerfile for Matrix bot
+  - docker-compose.yml with matrix-bot service
+  - .env.example updated with AGENT_BASE_URL and MATRIX_PLATFORM_BACKEND
+
+must_haves:
+  truths:
+    - "Dockerfile builds successfully with python:3.11-slim base"
+    - "lambda_agent_api installed in container despite Python version constraint"
+    - "PYTHONPATH=/app set so adapter/matrix/bot.py is runnable as module"
+    - "docker-compose.yml defines matrix-bot service with env_file: .env"
+    - ".env.example contains AGENT_BASE_URL and MATRIX_PLATFORM_BACKEND=real"
+    - "CMD runs python -m adapter.matrix.bot"
+  artifacts:
+    - path: "Dockerfile"
+      provides: "Matrix bot container image"
+      contains: "python:3.11-slim"
+    - path: "docker-compose.yml"
+      provides: "Service definition for matrix-bot"
+      contains: "matrix-bot"
+    - path: ".env.example"
+      provides: "Updated env template"
+      contains: "AGENT_BASE_URL"
+  key_links:
+    - from: "Dockerfile"
+      to: "external/platform-agent_api"
+      via: "COPY + pip install with --ignore-requires-python"
+      pattern: "ignore-requires-python"
+---
+
+<objective>
+Package the Matrix bot in a Docker container. Create Dockerfile using python:3.11-slim,
+install lambda_agent_api from the local external/ directory (bypassing the Python 3.14
+version constraint), and define a docker-compose.yml for running the matrix-bot service.
+Update .env.example with new variables.
+
+Purpose: Enable reproducible MVP deployment of the Matrix bot in a container alongside
+the separately-run platform-agent.
+
+Output: Dockerfile, docker-compose.yml, updated .env.example.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-CONTEXT.md
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-RESEARCH.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create Dockerfile and docker-compose.yml</name>
+
+  <read_first>
+    - .env.example (full file — adding new vars)
+    - external/platform-agent_api/lambda_agent_api/ (ls — verify files to copy)
+    - pyproject.toml (verify uv is the package manager used)
+  </read_first>
+
+  <files>Dockerfile, docker-compose.yml, .env.example</files>
+
+  <action>
+1. Check if pyproject.toml uses uv or pip. The project uses `uv sync` per CLAUDE.md. However, in the Docker container we can use pip for simplicity since uv's lockfile-based install may need the lockfile present. Use pip for the base install of surfaces-bot deps, and install lambda_agent_api separately.
+
+   Actually: the project uses uv. Use uv in Docker to be consistent:
+   - Install uv via pip (pip install uv)
+   - Run uv sync to install project deps
+   - Install lambda_agent_api with pip --ignore-requires-python
+
+2. Create Dockerfile:
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install uv
+RUN pip install --no-cache-dir uv
+
+# Copy dependency manifests first for layer caching
+COPY pyproject.toml uv.lock* ./
+
+# Install project dependencies via uv (no project install yet, just deps)
+RUN uv sync --no-install-project --frozen 2>/dev/null || uv sync --no-install-project
+
+# Copy project source
+COPY . .
+
+# Install the project itself
+RUN uv sync --frozen 2>/dev/null || uv sync
+
+# Install lambda_agent_api, bypassing Python version constraint
+RUN pip install --no-cache-dir --ignore-requires-python /app/external/platform-agent_api
+
+ENV PYTHONPATH=/app
+ENV PYTHONUNBUFFERED=1
+
+CMD ["python", "-m", "adapter.matrix.bot"]
+```
+
+3. Create docker-compose.yml:
+
+```yaml
+services:
+  matrix-bot:
+    build: .
+    env_file: .env
+    restart: unless-stopped
+    # platform-agent runs separately — not included in this compose file
+```
+
+4. Read current .env.example, then append new variables. Current file likely has MATRIX_* vars. Add:
+   - AGENT_WS_URL=ws://127.0.0.1:8000/agent_ws/
+   - AGENT_BASE_URL=http://127.0.0.1:8000
+   - MATRIX_PLATFORM_BACKEND=real
+
+   Read .env.example first to see what's there, then write the full updated file.
+  </action>
+
+  <done>
+    - `grep "python:3.11-slim" Dockerfile` returns a match
+    - `grep "ignore-requires-python" Dockerfile` returns a match (lambda_agent_api install)
+    - `grep "PYTHONPATH=/app" Dockerfile` returns a match
+    - `grep "adapter.matrix.bot" Dockerfile` returns a match (CMD)
+    - `grep "matrix-bot" docker-compose.yml` returns a match
+    - `grep "env_file" docker-compose.yml` returns a match
+    - `grep "AGENT_BASE_URL" .env.example` returns a match
+    - `grep "MATRIX_PLATFORM_BACKEND" .env.example` returns a match
+    - Dockerfile exists with python:3.11-slim, uv install, lambda_agent_api pip install --ignore-requires-python, PYTHONPATH=/app, CMD python -m adapter.matrix.bot
+    - docker-compose.yml exists with matrix-bot service, env_file: .env, restart: unless-stopped
+    - .env.example contains AGENT_WS_URL, AGENT_BASE_URL, MATRIX_PLATFORM_BACKEND=real
+  </done>
+
+  <verify>
+    <automated>grep "python:3.11-slim" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile && grep "ignore-requires-python" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile && grep "AGENT_BASE_URL" /Users/a/MAI/sem2/lambda/surfaces-bot/.env.example && echo "All checks passed"</automated>
+  </verify>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| container → host env | .env file mounts secrets into container |
+| container → platform-agent | Network call to AGENT_WS_URL / AGENT_BASE_URL |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-03-01 | Information Disclosure | .env file with secrets mounted in container | mitigate | .env in .gitignore; .env.example committed with placeholder values only, never real secrets |
+| T-04-03-02 | Tampering | lambda_agent_api installed from local path via --ignore-requires-python | accept | Local package under version control; no external supply chain risk |
+| T-04-03-03 | Denial of Service | restart: unless-stopped could loop on crash | accept | Expected behavior; operator can `docker compose stop` |
+</threat_model>
+
+<verification>
+```bash
+# Verify files exist and contain expected content
+grep "python:3.11-slim" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile
+grep "ignore-requires-python" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile
+grep "AGENT_BASE_URL" /Users/a/MAI/sem2/lambda/surfaces-bot/.env.example
+grep "matrix-bot" /Users/a/MAI/sem2/lambda/surfaces-bot/docker-compose.yml
+```
+</verification>
+
+<success_criteria>
+- Dockerfile, docker-compose.yml, .env.example all exist in project root
+- Dockerfile builds without errors when platform-agent_api dir is present (docker build . exits 0)
+- .env.example contains AGENT_BASE_URL, AGENT_WS_URL, MATRIX_PLATFORM_BACKEND
+- docker-compose.yml service named matrix-bot uses env_file: .env
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md`
+</output>

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md

@@ -0,0 +1,106 @@
+---
+phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
+plan: 03
+subsystem: infra
+tags: [docker, docker-compose, matrix, uv, lambda-agent-api]
+requires:
+  - phase: 04-01
+    provides: Matrix MVP runtime and environment model
+provides:
+  - Matrix bot Docker image definition
+  - Single-service docker-compose setup for matrix-bot
+  - Env template entries for Agent API base URLs and real backend selection
+affects: [deployment, matrix, local-dev]
+tech-stack:
+  added: [Dockerfile, docker-compose]
+  patterns: [uv-managed container install with system Python runtime, local path install for lambda_agent_api]
+key-files:
+  created: [Dockerfile, docker-compose.yml]
+  modified: [.env.example]
+key-decisions:
+  - "Kept compose scoped to matrix-bot only; platform-agent remains external to this stack."
+  - "Set UV_PROJECT_ENVIRONMENT=/usr/local so uv-installed dependencies are available to CMD [\"python\", \"-m\", \"adapter.matrix.bot\"]."
+patterns-established:
+  - "Install project dependencies with uv inside the container, then install lambda_agent_api from external/platform-agent_api via pip --ignore-requires-python."
+requirements-completed: [Dockerfile for Matrix bot, docker-compose.yml with matrix-bot service, .env.example updated with AGENT_BASE_URL and MATRIX_PLATFORM_BACKEND]
+duration: 6min
+completed: 2026-04-17
+---
+
+# Phase 4 Plan 03: Matrix Bot Containerization Summary
+
+**Python 3.11 Matrix bot container with uv-managed app dependencies, local lambda_agent_api install bypass, and a single-service compose entrypoint**
+
+## Performance
+
+- **Duration:** 6 min
+- **Started:** 2026-04-17T13:01:00Z
+- **Completed:** 2026-04-17T13:07:04Z
+- **Tasks:** 1
+- **Files modified:** 4
+
+## Accomplishments
+
+- Added a root `Dockerfile` for the Matrix bot using `python:3.11-slim`.
+- Added `docker-compose.yml` with a single `matrix-bot` service using `env_file: .env`.
+- Extended `.env.example` with `AGENT_WS_URL`, `AGENT_BASE_URL`, and `MATRIX_PLATFORM_BACKEND=real`.
+
+## Files Created/Modified
+
+- `Dockerfile` - Builds the Matrix bot image, installs project dependencies with `uv`, and installs `lambda_agent_api` from the local `external/` tree.
+- `docker-compose.yml` - Defines the `matrix-bot` service with restart policy and `.env` loading.
+- `.env.example` - Documents the agent WebSocket URL, agent HTTP base URL, and real backend selector.
+
+## Decisions Made
+
+- Kept the compose scope limited to the Matrix bot, matching the phase boundary and excluding platform services.
+- Added `UV_PROJECT_ENVIRONMENT=/usr/local` as a correctness fix so `uv sync` installs are visible to the final `python` runtime.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 2 - Missing Critical] Ensured uv installs are available to the container runtime**
+- **Found during:** Task 1 (Create Dockerfile and docker-compose.yml)
+- **Issue:** The plan sketch used `uv sync` plus `CMD ["python", ...]`; by default, `uv sync` would install into a virtual environment that system `python` would not use.
+- **Fix:** Set `UV_PROJECT_ENVIRONMENT=/usr/local` in the Dockerfile before running `uv sync`.
+- **Files modified:** `Dockerfile`
+- **Verification:** Required grep checks passed and the generated compose config remained valid.
+
+---
+
+**Total deviations:** 1 auto-fixed (1 missing critical)
+**Impact on plan:** Narrow correctness fix only. No scope expansion.
+
+## Issues Encountered
+
+- `docker compose config` resolved values from the local `.env`, so verification was kept to config rendering and grep-style checks rather than a full image build.
+
+## User Setup Required
+
+- Create `.env` from `.env.example` with real Matrix and agent values before running `docker compose up`.
+
+## Next Phase Readiness
+
+- Matrix bot container packaging is in place and ready for operator-supplied secrets plus an external platform-agent deployment.
+- No code changes were made outside the allowed containerization files.
+
+## Verification
+
+- `grep 'python:3.11-slim' Dockerfile`
+- `grep 'ignore-requires-python' Dockerfile`
+- `grep 'PYTHONPATH=/app' Dockerfile`
+- `grep 'adapter.matrix.bot' Dockerfile`
+- `grep 'matrix-bot' docker-compose.yml`
+- `grep 'env_file' docker-compose.yml`
+- `grep 'AGENT_BASE_URL' .env.example`
+- `grep 'AGENT_WS_URL' .env.example`
+- `grep 'MATRIX_PLATFORM_BACKEND' .env.example`
+- `docker compose -f docker-compose.yml config`
+
+## Self-Check: PASSED
+
+- Found `Dockerfile`
+- Found `docker-compose.yml`
+- Found updated `.env.example`
+- Found `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md`

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-CONTEXT.md

@@ -0,0 +1,136 @@
+# Phase 4: Matrix MVP — Agent Context + Context Management — Context
+
+**Gathered:** 2026-04-16
+**Status:** Ready for planning
+**Source:** Conversation context (2026-04-16 design session)
+
+<domain>
+## Phase Boundary
+
+Привести Matrix-бот к рабочему состоянию для MVP-деплоя в контейнер:
+- Убрать наш кастомный `AgentSessionClient` и thread_id патч из `platform-agent`, перейти на актуальный origin/main платформы с `AgentApi` из `lambda_agent_api`
+- Добавить 4 команды управления контекстом агента: `!save`, `!load`, `!reset`, `!context`
+- Упаковать Matrix-бот в Docker-контейнер
+
+НЕ входит в фазу:
+- Изменения в platform-agent (это задача команды платформы)
+- Telegram адаптер
+- E2EE
+- Skills system (ждём платформу)
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Архитектура платформы (locked)
+
+- **Один контейнер = один чат**: `AgentService` с `thread_id = "default"` — намеренная архитектура. Изоляция на уровне контейнеров, не thread_id. Не менять.
+- **Убрать thread_id патч**: наш коммит `1dca2c1` в `external/platform-agent` удаляем. Переходим на `origin/main` platform-agent.
+- **Удалить `build_thread_key`**: функция больше не нужна. Убрать из `sdk/agent_session.py` и `sdk/real.py`.
+- **Заменить `AgentSessionClient` на `AgentApi`**: использовать `AgentApi` из `external/platform-agent_api/lambda_agent_api/agent_api.py`. Он уже правильно обрабатывает все event-типы (неизвестные → `logger.warning`, без краша).
+
+### !save (locked)
+
+- Синтаксис: `!save` (автоимя по дате/времени) или `!save [имя]`
+- Механизм: Matrix-бот посылает агенту текстовое сообщение "Summarize our conversation and save to /workspace/contexts/[name].md. Reply only with: Saved: [name]"
+- Имена сохранений хранятся в `PrototypeStateStore` (список для `!load`)
+- Агент сам пишет файл через свои инструменты (`write_file`)
+
+### !load (locked)
+
+- `!load` без аргументов → бот показывает нумерованный список сохранений
+- Пользователь вводит **число** (1, 2, 3...) для выбора
+- Выход из состояния: `0` или `!cancel`
+- После выбора: бот посылает агенту "Load context from /workspace/contexts/[name].md and use it as background for our conversation. Reply: Loaded: [name]"
+- Состояние ожидания выбора хранится в Matrix store (аналогично pending_confirm)
+
+### !reset (locked)
+
+- Показывает confirmation-диалог:
+  ```
+  Сбросить контекст агента? Выбери:
+    !yes — сбросить
+    !save [имя] — сохранить и сбросить
+    !no — отмена
+  ```
+- `!yes` → вызвать `POST {AGENT_BASE_URL}/reset` (resets AgentService singleton)
+- `!save имя` → сначала выполняется логика !save, затем POST /reset
+- `!no` → отмена
+- Fallback если `/reset` endpoint недоступен (404): вернуть пользователю "Reset endpoint недоступен. Обратитесь к администратору."
+- `AGENT_BASE_URL` — новая env переменная (HTTP base URL агента, отдельно от `AGENT_WS_URL`)
+
+### !context (locked)
+
+- Показывает: имя текущей сессии (если загружали через `!load`), токены из последнего ответа (`tokens_used` из `MsgEventEnd`), список сохранений (имена + даты)
+- Не делает никаких вызовов к агенту
+
+### Dockerfile + docker-compose (locked)
+
+- `Dockerfile` для Matrix-бота (`adapter/matrix/bot.py`)
+- `docker-compose.yml` с сервисом `matrix-bot`
+- Env переменные через `.env` файл
+- Platform-agent запускается отдельно (не входит в compose этой фазы)
+
+### Claude's Discretion
+
+- Структура хранения saved sessions в PrototypeStateStore (dict name→timestamp)
+- Формат автоимени для !save без аргументов
+- HTTP клиент для POST /reset (aiohttp или httpx)
+- Точный формат промптов к агенту для save/load
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Platform клиент (заменяем)
+- `sdk/agent_session.py` — текущий AgentSessionClient, УДАЛЯЕМ/ЗАМЕНЯЕМ
+- `sdk/real.py` — RealPlatformClient, обновляем под AgentApi
+- `external/platform-agent_api/lambda_agent_api/agent_api.py` — новый клиент AgentApi
+- `external/platform-agent_api/lambda_agent_api/server.py` — типы сообщений (MsgStatus, MsgEventTextChunk, MsgEventEnd, etc.)
+- `external/platform-agent_api/lambda_agent_api/client.py` — MsgUserMessage
+
+### Matrix адаптер (расширяем)
+- `adapter/matrix/bot.py` — точка входа, MatrixBot, build_runtime
+- `adapter/matrix/handlers/` — существующие обработчики команд
+- `adapter/matrix/store.py` — get_room_meta, set_pending_confirm (паттерн для !load state)
+- `sdk/prototype_state.py` — PrototypeStateStore, расширяем для saved sessions
+
+### Состояние платформы
+- `.planning/threads/matrix-dev-prototype-agent-platform-state.md` — исследование от 2026-04-14
+
+### Существующая архитектура команд
+- `core/protocol.py` — IncomingCommand, OutgoingMessage, OutgoingUI
+- `core/handlers/` — паттерны регистрации обработчиков
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+
+- `AgentApi` требует явного `connect()` при старте и `close()` при завершении — lifecycle нужно встроить в `MatrixBot`
+- `AgentApi.send_message()` — AsyncIterator, возвращает `MsgEventTextChunk` чанки и `MsgEventEnd`
+- Для `!load` состояние "ожидаем число" хранить по ключу `load_pending:{matrix_user_id}:{room_id}` в store (аналог pending_confirm)
+- `AGENT_BASE_URL` — HTTP URL, например `http://127.0.0.1:8000`; `AGENT_WS_URL` = `ws://127.0.0.1:8000/agent_ws/`
+- platform-agent origin/main: `POST /reset` эндпоинта нет — это нужно запросить у команды платформы. До тех пор `!reset` возвращает "Reset endpoint недоступен"
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Замена `PrototypeStateStore` на реальный control-plane из platform-master (Phase 3)
+- Skills интеграция через SkillsMiddleware (ждём платформу)
+- E2EE для Matrix
+- `!reset` через docker restart (заменяется на /reset endpoint когда платформа добавит)
+- Суммаризация контекста (агент сам решает как писать в файл)
+
+</deferred>
+
+---
+
+*Phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma*
+*Context gathered: 2026-04-16 via conversation design session*

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-RESEARCH.md

@@ -0,0 +1,546 @@
+# Phase 4: Matrix MVP — Shared Agent Context + Context Management — Research
+
+**Researched:** 2026-04-16
+**Domain:** Matrix bot, AgentApi WebSocket client, context management commands, Docker packaging
+**Confidence:** HIGH (all findings verified against actual source files in this repo)
+
+---
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+
+**Архитектура платформы:**
+- Один контейнер = один чат: `AgentService` с `thread_id = "default"` — намеренная архитектура. Не менять.
+- Убрать thread_id патч: наш коммит `1dca2c1` в `external/platform-agent` удаляем. Переходим на `origin/main` platform-agent.
+- Удалить `build_thread_key`: функция больше не нужна. Убрать из `sdk/agent_session.py` и `sdk/real.py`.
+- Заменить `AgentSessionClient` на `AgentApi`: использовать `AgentApi` из `external/platform-agent_api/lambda_agent_api/agent_api.py`.
+
+**!save:** Синтаксис `!save` (автоимя) или `!save [имя]`. Механизм: посылаем агенту текстовое сообщение. Имена сохранений хранятся в `PrototypeStateStore`.
+
+**!load:** `!load` без аргументов → нумерованный список. Пользователь вводит число. Выход: `0` или `!cancel`. После выбора — посылаем агенту текстовое сообщение. Состояние ожидания в Matrix store.
+
+**!reset:** Confirmation-диалог с `!yes`/`!save имя`/`!no`. `!yes` → `POST {AGENT_BASE_URL}/reset`. Fallback если 404: сообщение пользователю.
+
+**!context:** Показывает имя сессии, токены, список сохранений. Без вызовов агента.
+
+**Dockerfile + docker-compose:** Для Matrix-бота. Env через `.env`. Platform-agent — отдельно.
+
+### Claude's Discretion
+
+- Структура хранения saved sessions в PrototypeStateStore (dict name→timestamp)
+- Формат автоимени для !save без аргументов
+- HTTP клиент для POST /reset (aiohttp или httpx)
+- Точный формат промптов к агенту для save/load
+
+### Deferred Ideas (OUT OF SCOPE)
+
+- Замена `PrototypeStateStore` на реальный control-plane из platform-master
+- Skills интеграция через SkillsMiddleware
+- E2EE для Matrix
+- `!reset` через docker restart
+- Суммаризация контекста
+</user_constraints>
+
+---
+
+## Summary
+
+Phase 4 replaces the custom `AgentSessionClient` with the production `AgentApi` from `lambda_agent_api`, adds four context management commands to the Matrix bot, and packages it in Docker. All findings are verified directly against source files.
+
+**Primary recommendation:** Wire `AgentApi` as a persistent connection in `MatrixBot.__init__` (connect on start, close in finally block of `main()`). Expose it through `RealPlatformClient`. The four commands follow the existing handler registration pattern in `adapter/matrix/handlers/__init__.py`.
+
+The `platform-agent` at `origin/main` already works with `AgentApi` — it does NOT require `thread_id` query param. Our local patch (`1dca2c1`) must be discarded and `external/platform-agent` reset to `origin/main`.
+
+---
+
+## Project Constraints (from CLAUDE.md)
+
+- **Tech stack:** matrix-nio for Matrix — do not change without discussion
+- **Platform client:** connected only via `sdk/interface.py` Protocol — core/ and adapters untouched when swapping implementation
+- **No E2EE** — matrix-nio without python-olm
+- **Hotfixes < 20 lines** → Claude Code directly; implementation → Codex via GSD
+- **MATRIX_PLATFORM_BACKEND env var** controls mock vs real
+
+---
+
+## Standard Stack
+
+### Core (verified)
+| Library | Version | Purpose | Source |
+|---------|---------|---------|--------|
+| `lambda_agent_api` | local (external/platform-agent_api) | AgentApi WebSocket client | [VERIFIED: file read] |
+| `aiohttp` | >=3.9 (surfaces-bot), >=3.13.4 (agent_api) | WebSocket transport inside AgentApi | [VERIFIED: pyproject.toml] |
+| `pydantic` | >=2.5 | Message serialization (MsgUserMessage, MsgEventEnd, etc.) | [VERIFIED: server.py/client.py] |
+| `httpx` | >=0.27 | HTTP client for POST /reset (already in deps) | [VERIFIED: pyproject.toml] |
+| `structlog` | >=24.1 | Logging (existing pattern) | [VERIFIED: pyproject.toml] |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| `aiohttp` | already a dep | Alternative HTTP for POST /reset | Could use instead of httpx — both available |
+
+**Installation:** No new packages needed. `lambda_agent_api` is installed as a local path package (currently accessed via `sys.path` injection in tests; for production use, add to pyproject.toml as path dep or install via `pip install -e external/platform-agent_api`).
+
+**Critical:** `lambda_agent_api` requires Python >=3.14 per its own `pyproject.toml`. The surfaces-bot requires Python >=3.11. [VERIFIED: pyproject.toml of both]. This is a **version mismatch** — see Pitfalls.
+
+---
+
+## Architecture Patterns
+
+### AgentApi Constructor (verified)
+
+```python
+# Source: external/platform-agent_api/lambda_agent_api/agent_api.py
+AgentApi(
+    agent_id: str,               # arbitrary string ID, used in logs
+    url: str,                    # WebSocket URL, e.g. "ws://127.0.0.1:8000/agent_ws/"
+    callback: Optional[Callable[[ServerMessage], None]] = None,  # for orphaned msgs
+    on_disconnect: Optional[Callable[['AgentApi'], None]] = None  # called on WS close
+)
+```
+
+### AgentApi Lifecycle (verified)
+
+```python
+# Source: external/platform-agent_api/lambda_agent_api/agent_api.py
+agent = AgentApi(agent_id="matrix-bot", url=ws_url)
+await agent.connect()   # opens WS, waits for MsgStatus, starts _listen() task
+# ... use agent ...
+await agent.close()     # cancels _listen task, closes WS and session
+```
+
+`connect()` blocks until `MsgStatus` is received from server (5s timeout). After `connect()`, a background `_listen()` asyncio task runs continuously, routing server messages to an internal `asyncio.Queue`.
+
+### AgentApi.send_message() semantics (verified)
+
+```python
+# Source: external/platform-agent_api/lambda_agent_api/agent_api.py, line 134
+async def send_message(self, text: str) -> AsyncIterator[AgentEventUnion]:
+```
+
+- `AgentEventUnion = Union[MsgEventTextChunk, MsgEventEnd]` — **but** the generator `yield`s only `MsgEventTextChunk` chunks; it `break`s (stops) on `MsgEventEnd` without yielding it.
+- `MsgEventEnd` carries `tokens_used: int` — to capture this, the caller must intercept the queue or handle `MsgEventEnd` in the `_listen` loop. **Currently `send_message` discards `tokens_used`.** This affects `!context` which needs tokens.
+
+**Resolution:** In `RealPlatformClient.stream_message()`, after iterating through `send_message()`, `tokens_used` won't be directly available. Options:
+1. Store `tokens_used` in a shared attribute after each response (add `self._last_tokens_used` to `AgentApi` or a wrapper).
+2. Use the `callback` parameter to capture `MsgEventEnd` events from the `_listen` loop.
+
+[ASSUMED] The simplest approach: wrap `AgentApi` in a thin `AgentApiAdapter` class that intercepts `_listen` output and exposes `last_tokens_used`. Or: store tokens in `PrototypeStateStore` after each message.
+
+### AgentApi concurrency constraint (verified)
+
+`AgentApi._request_lock` prevents parallel `send_message()` calls — second call raises `AgentBusyException`. In the single-user Matrix prototype this is acceptable. The bot must not dispatch two messages concurrently to the same agent.
+
+### Wiring AgentApi into MatrixBot (integration pattern)
+
+The `AgentApi` must be a persistent connection (not per-message connect/disconnect) because:
+1. `_listen()` task runs in background and routes server push events.
+2. Per-message connect/disconnect would recreate the aiohttp session each time and discard LangGraph thread state.
+
+**Recommended wiring:**
+
+```python
+# adapter/matrix/bot.py — main() function
+agent_api = AgentApi(agent_id="matrix-bot", url=ws_url)
+await agent_api.connect()
+runtime = build_runtime(store=SQLiteStore(db_path), client=client, agent_api=agent_api)
+try:
+    await client.sync_forever(timeout=30000, since=since_token)
+finally:
+    await client.close()
+    await agent_api.close()
+```
+
+`_build_platform_from_env()` currently instantiates everything synchronously. It must be refactored to `async` or split: construct `AgentApi` synchronously, call `connect()` in `main()` before starting sync loop.
+
+### RealPlatformClient updates
+
+`RealPlatformClient` currently imports `AgentSessionClient` and calls `build_thread_key`. Both are removed. The updated class:
+
+```python
+class RealPlatformClient(PlatformClient):
+    def __init__(
+        self,
+        agent_api: AgentApi,           # replaces agent_sessions: AgentSessionClient
+        prototype_state: PrototypeStateStore,
+        platform: str = "matrix",
+    ) -> None:
+```
+
+`send_message()` and `stream_message()` call `agent_api.send_message(text)` directly — no `thread_key` needed.
+
+### platform-agent origin/main: what changes (verified)
+
+Our patch `1dca2c1` added `thread_id` query param handling to `external/platform-agent/src/api/external.py`. On `origin/main`, the `process_message()` function does NOT use `thread_id` — it calls `agent_service.astream(msg.text)` without `thread_id`. The WS URL becomes simply `ws://host:port/agent_ws/` — no query params.
+
+### Existing command registration pattern (verified)
+
+```python
+# adapter/matrix/handlers/__init__.py — register_matrix_handlers()
+dispatcher.register(IncomingCommand, "new",      make_handle_new_chat(client, store))
+dispatcher.register(IncomingCommand, "settings", handle_settings)
+dispatcher.register(IncomingCallback, "confirm", make_handle_confirm(store))
+```
+
+Handler signature (all existing handlers follow this):
+```python
+async def handle_X(
+    event: IncomingCommand,
+    auth_mgr,
+    platform,
+    chat_mgr,
+    settings_mgr,
+) -> list[OutgoingEvent]:
+```
+
+New context commands need access to `agent_api` (for `!save`, `!load`) and `store` (for `!context`, `!load` pending state). Pattern: use `make_handle_X(agent_api, store)` closures — same as `make_handle_new_chat(client, store)`.
+
+### !load pending state pattern (verified)
+
+Existing `PENDING_CONFIRM_PREFIX = "matrix_pending_confirm:"` in `adapter/matrix/store.py`.
+
+New key for load pending state:
+```python
+LOAD_PENDING_PREFIX = "matrix_load_pending:"
+
+def _load_pending_key(user_id: str, room_id: str) -> str:
+    return f"{LOAD_PENDING_PREFIX}{user_id}:{room_id}"
+```
+
+Stored data structure:
+```python
+{
+    "saves": [{"name": "my-save", "ts": "2026-04-16T12:00:00Z"}, ...],
+    "display": "1. my-save (2026-04-16)\n2. other..."
+}
+```
+
+The numeric input `1`, `2`, etc. is intercepted in `MatrixBot.on_room_message()` BEFORE dispatching as `IncomingMessage` — check if `load_pending` exists for this user+room, resolve to save name, dispatch the load command internally.
+
+**Alternative (recommended):** Handle numeric input in the `IncomingMessage` handler via a pre-dispatch interceptor, or register a special numeric-input check in the dispatcher for messages that are pure integers.
+
+### !reset confirmation dialog pattern
+
+!reset reuses the `OutgoingUI` + `pending_confirm` mechanism or a simpler custom state. Since the dialog options are `!yes`, `!save имя`, `!no` (not just yes/no), it cannot reuse `pending_confirm` directly without extension.
+
+Simplest approach: store `reset_pending:{user_id}:{room_id}` key (boolean) and check for `!yes`/`!no`/`!save` commands from the `IncomingCommand` dispatcher when reset_pending is set.
+
+### saved sessions storage in PrototypeStateStore
+
+New dict attribute on `PrototypeStateStore`:
+```python
+self._saved_sessions: dict[str, list[dict]] = {}
+# Key: matrix_user_id
+# Value: [{"name": "my-save", "created_at": "2026-04-16T12:00:00Z"}, ...]
+```
+
+Methods to add:
+```python
+async def add_saved_session(self, user_id: str, name: str) -> None: ...
+async def list_saved_sessions(self, user_id: str) -> list[dict]: ...
+```
+
+### !context tokens_used tracking
+
+`MsgEventEnd.tokens_used: int` is available from `server.py`. Since `AgentApi.send_message()` drops it, the planner must decide how to surface it. Recommended: store in `PrototypeStateStore` as `_last_tokens_used: dict[str, int]` keyed by user_id, updated after each successful agent response in `RealPlatformClient`.
+
+### Prompts for !save / !load (Claude's Discretion)
+
+```python
+# !save
+SAVE_PROMPT = (
+    "Summarize our conversation and save to /workspace/contexts/{name}.md. "
+    "Reply only with: Saved: {name}"
+)
+
+# !load
+LOAD_PROMPT = (
+    "Load context from /workspace/contexts/{name}.md and use it as background "
+    "for our conversation. Reply: Loaded: {name}"
+)
+```
+
+Auto-name format (Claude's Discretion): `context-{YYYYMMDD-HHMMSS}` (UTC, no spaces, no special chars, safe as filename).
+
+### POST /reset endpoint
+
+Confirmed absent in `origin/main` platform-agent. Only endpoint is `GET /agent_ws/` (WebSocket). The `main.py` has no HTTP routes beyond what FastAPI provides by default (`/docs`, `/openapi.json`).
+
+`!reset` with `!yes` → `POST {AGENT_BASE_URL}/reset` → expect 404 → return "Reset endpoint недоступен. Обратитесь к администратору."
+
+HTTP client for this: **httpx** (already in `pyproject.toml`):
+```python
+import httpx
+async with httpx.AsyncClient() as client:
+    response = await client.post(f"{agent_base_url}/reset", timeout=5.0)
+    if response.status_code == 404:
+        return [OutgoingMessage(chat_id=..., text="Reset endpoint недоступен...")]
+```
+
+### Dockerfile
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY pyproject.toml .
+RUN pip install -e .
+COPY . .
+ENV PYTHONUNBUFFERED=1
+CMD ["python", "-m", "adapter.matrix.bot"]
+```
+
+`lambda_agent_api` must be installed in the container. Options:
+1. `COPY external/platform-agent_api /app/external/platform-agent_api` + `pip install -e /app/external/platform-agent_api`
+2. Include `lambda_agent_api` package directly in `surfaces-bot` package (copy source files)
+
+Option 1 is cleaner.
+
+### docker-compose.yml structure
+
+```yaml
+services:
+  matrix-bot:
+    build: .
+    env_file: .env
+    restart: unless-stopped
+```
+
+Platform-agent runs separately — not in this compose file.
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| WebSocket lifecycle with reconnect | Custom WS manager | `AgentApi` from `lambda_agent_api` | Already handles connect/close/listen loop, error routing, queue management |
+| Message deserialization | Custom JSON parsing | `ServerMessage.validate_json()` (Pydantic TypeAdapter) | Discriminated union handles all message types |
+| HTTP async client | `aiohttp.ClientSession` directly | `httpx.AsyncClient` | Already in deps, cleaner API for one-shot POST |
+| Concurrent request guard | Custom lock | `AgentApi._request_lock` | Already implemented, raises `AgentBusyException` |
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: lambda_agent_api Python version mismatch
+
+**What goes wrong:** `lambda_agent_api/pyproject.toml` declares `requires-python = ">=3.14"`. The surfaces-bot runs on Python 3.11+. If `pip install -e external/platform-agent_api` is run with Python 3.11 it may fail or emit warnings.
+
+**Why it happens:** The `lambda_agent_api` was developed under Python 3.14 (seen in `.venv` path: `python3.14`). The code itself uses no 3.14-specific syntax — it is pure aiohttp + pydantic which run on 3.11.
+
+**How to avoid:** Change `requires-python = ">=3.11"` in `external/platform-agent_api/pyproject.toml` before building the Docker image, or install with `--ignore-requires-python`. Alternatively, copy the three source files directly into the surfaces-bot package.
+
+**Warning signs:** `pip install` failure with "requires Python >=3.14".
+
+### Pitfall 2: AgentApi.send_message() drops MsgEventEnd (tokens_used lost)
+
+**What goes wrong:** The generator yields only `MsgEventTextChunk` objects and breaks on `MsgEventEnd` without yielding it. Any downstream code that tries to get `tokens_used` from the iterator gets nothing.
+
+**Why it happens:** The generator `break`s on `MsgEventEnd` (line 172 of agent_api.py) without yielding it. This is intentional for streaming UX but loses token info.
+
+**How to avoid:** Before streaming, set `self._last_tokens_used = 0`. In `_listen()`, `MsgEventEnd` is put into `_current_queue` (line 241). The `send_message()` generator reads from that queue but does `break` — the `MsgEventEnd` object is consumed but not returned to caller. The only way to capture it is to subclass `AgentApi` or read from `_current_queue` directly before the break.
+
+**Practical fix:** Add `self.last_tokens_used: int = 0` to `AgentApi` and intercept the queue in the `finally` block of `send_message()` — or store it in a wrapper class.
+
+### Pitfall 3: AgentApi persistent connection vs sync_forever loop
+
+**What goes wrong:** If `agent_api.connect()` is called inside `_build_platform_from_env()` (sync function), it creates an `asyncio.Task` for `_listen()` outside the event loop context.
+
+**Why it happens:** `_build_platform_from_env()` is called synchronously from `build_runtime()`. `connect()` is a coroutine.
+
+**How to avoid:** Do NOT call `agent_api.connect()` inside `_build_platform_from_env()`. Instead:
+1. `_build_platform_from_env()` creates `RealPlatformClient` with an unconnected `AgentApi`
+2. `main()` awaits `agent_api.connect()` explicitly after constructing runtime
+
+Expose `agent_api` from `RealPlatformClient` via a property so `main()` can call `connect()` on it.
+
+### Pitfall 4: !load numeric input interception
+
+**What goes wrong:** When user types `1` in response to `!load` menu, it is dispatched as `IncomingMessage` (not a command) and routed to the platform — the agent receives "1" as a user message.
+
+**Why it happens:** The Matrix converter (`from_room_event`) produces `IncomingMessage` for plain text, `IncomingCommand` only for `!`-prefixed text.
+
+**How to avoid:** In `MatrixBot.on_room_message()`, before calling `dispatcher.dispatch()`, check if `load_pending` state exists for this user+room. If yes and the message text is a digit (or `0`/`!cancel`), handle it as a load selection instead of routing to agent.
+
+### Pitfall 5: platform-agent thread_id removal breaks existing tests
+
+**What goes wrong:** `tests/platform/test_agent_session.py` imports `build_thread_key` and tests `process_message` with `thread_id` in query params. After the patch is removed, these tests will fail.
+
+**Why it happens:** Tests were written against our patched `external.py`.
+
+**How to avoid:** The plan must include updating `test_agent_session.py` — remove `build_thread_key` tests, update `process_message` tests to reflect origin/main signature (no `thread_id` param).
+
+### Pitfall 6: !reset dialog conflicts with existing !yes/!no flow
+
+**What goes wrong:** The existing `pending_confirm` flow uses `!yes`/`!no`. If both `reset_pending` and `pending_confirm` are active simultaneously, `!yes` could trigger the wrong handler.
+
+**Why it happens:** Both flows listen for the same commands.
+
+**How to avoid:** `!reset` dialog uses a separate state key `reset_pending:{user_id}:{room_id}`. The handler for `!yes` must check `reset_pending` first, then `pending_confirm`. Document priority in handler code.
+
+---
+
+## Code Examples
+
+### Invoking AgentApi.send_message() in stream_message
+```python
+# Source: external/platform-agent_api/lambda_agent_api/agent_api.py
+async def stream_message(self, user_id: str, chat_id: str, text: str, ...) -> AsyncIterator[MessageChunk]:
+    async for event in self._agent_api.send_message(text):
+        if isinstance(event, MsgEventTextChunk):
+            yield MessageChunk(
+                message_id=user_id,
+                delta=event.text,
+                finished=False,
+            )
+    # After loop ends, MsgEventEnd was consumed internally
+    yield MessageChunk(message_id=user_id, delta="", finished=True, tokens_used=self._agent_api.last_tokens_used)
+```
+
+### Handler registration pattern
+```python
+# Source: adapter/matrix/handlers/__init__.py
+def register_matrix_handlers(dispatcher: EventDispatcher, client=None, store=None, agent_api=None) -> None:
+    # existing...
+    dispatcher.register(IncomingCommand, "save",    make_handle_save(agent_api, store))
+    dispatcher.register(IncomingCommand, "load",    make_handle_load(agent_api, store))
+    dispatcher.register(IncomingCommand, "reset",   make_handle_reset(store))
+    dispatcher.register(IncomingCommand, "context", make_handle_context(store))
+```
+
+### !load pending key
+```python
+# New in adapter/matrix/store.py
+LOAD_PENDING_PREFIX = "matrix_load_pending:"
+
+async def get_load_pending(store: StateStore, user_id: str, room_id: str) -> dict | None:
+    return await store.get(f"{LOAD_PENDING_PREFIX}{user_id}:{room_id}")
+
+async def set_load_pending(store: StateStore, user_id: str, room_id: str, data: dict) -> None:
+    await store.set(f"{LOAD_PENDING_PREFIX}{user_id}:{room_id}", data)
+
+async def clear_load_pending(store: StateStore, user_id: str, room_id: str) -> None:
+    await store.delete(f"{LOAD_PENDING_PREFIX}{user_id}:{room_id}")
+```
+
+### platform-agent origin/main process_message (no thread_id)
+```python
+# Source: git show origin/main:src/api/external.py in external/platform-agent
+async def process_message(ws: WebSocket, msg, agent_service: AgentService):
+    match msg:
+        case MsgUserMessage():
+            async for chunk in agent_service.astream(msg.text):  # no thread_id arg
+                await ws.send_text(chunk.model_dump_json())
+            await ws.send_text(MsgEventEnd(tokens_used=0).model_dump_json())
+```
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | `tokens_used` can be captured by storing in `AgentApi.last_tokens_used` attribute during `_listen()` before it's queued | Architecture Patterns | If `_listen` timing means value is read before queue, token count would be wrong — low risk, easy to test |
+| A2 | Python 3.11 can run `lambda_agent_api` despite `>=3.14` constraint in pyproject.toml | Standard Stack | If code uses 3.14-specific syntax, would fail at runtime — actual code inspected: no 3.14 syntax found |
+| A3 | httpx is preferred over aiohttp for POST /reset (one-shot HTTP) | Standard Stack | Either works; httpx already in deps |
+
+---
+
+## Open Questions
+
+1. **tokens_used capture from AgentApi**
+   - What we know: `MsgEventEnd.tokens_used` is put into `_current_queue` but consumed (not yielded) by `send_message()` generator
+   - What's unclear: Cleanest interception point without modifying `lambda_agent_api` source
+   - Recommendation: Add `last_tokens_used: int = 0` attribute to `AgentApi` and set it in `send_message()`'s `finally` block when draining orphan queue, OR set it in `_listen()` before putting `MsgEventEnd` in queue
+
+2. **!load numeric input dispatch**
+   - What we know: Plain text `1`, `2` arrives as `IncomingMessage`, not `IncomingCommand`
+   - What's unclear: Where to intercept — in `on_room_message()` (bot layer) or in dispatcher pre-hook
+   - Recommendation: Intercept in `MatrixBot.on_room_message()` before `dispatcher.dispatch()`. Keeps dispatcher clean.
+
+3. **lambda_agent_api install in Docker**
+   - What we know: It's a local package in `external/platform-agent_api/`
+   - What's unclear: Whether to install as editable or copy sources
+   - Recommendation: `COPY external/platform-agent_api /build/lambda_agent_api && pip install /build/lambda_agent_api` in Dockerfile
+
+---
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|-------------|-----------|---------|----------|
+| Python 3.11+ | All | ✓ | System | — |
+| aiohttp | AgentApi WS | ✓ | >=3.9 in deps | — |
+| httpx | POST /reset | ✓ | >=0.27 in deps | aiohttp |
+| matrix-nio | Matrix bot | ✓ | >=0.21 in deps | — |
+| lambda_agent_api | AgentApi | local only | 0.1.0 | — |
+| Docker | Container build | [ASSUMED] standard dev env | — | — |
+| platform-agent (running) | Integration test | local clone | origin/main needed | — |
+
+---
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | pytest + pytest-asyncio (asyncio_mode = "auto") |
+| Config file | pyproject.toml `[tool.pytest.ini_options]` |
+| Quick run command | `pytest tests/platform/test_real.py tests/adapter/matrix/test_dispatcher.py -v` |
+| Full suite command | `pytest tests/ -v` |
+
+### Phase Requirements → Test Map
+
+| Req | Behavior | Test Type | File |
+|-----|----------|-----------|------|
+| Remove build_thread_key | Function gone from sdk/ | unit | `tests/platform/test_agent_session.py` — update/remove |
+| AgentApi replaces AgentSessionClient | `RealPlatformClient` uses `AgentApi` | unit | `tests/platform/test_real.py` — update |
+| !save sends prompt to agent | Command dispatches agent message | unit | `tests/adapter/matrix/test_dispatcher.py` — add |
+| !load shows list | Command returns numbered list | unit | `tests/adapter/matrix/test_dispatcher.py` — add |
+| !load numeric select | Bot intercepts digit, sends load prompt | unit | `tests/adapter/matrix/test_dispatcher.py` — add |
+| !reset shows dialog | Command returns confirmation UI | unit | `tests/adapter/matrix/test_dispatcher.py` — add |
+| !context returns snapshot | Command returns session info | unit | `tests/adapter/matrix/test_dispatcher.py` — add |
+| PrototypeStateStore saved sessions | add/list saved sessions | unit | `tests/platform/test_prototype_state.py` — add |
+
+### Wave 0 Gaps
+- [ ] `tests/platform/test_agent_api_integration.py` — unit tests for `RealPlatformClient` with mocked `AgentApi`
+- [ ] `tests/adapter/matrix/test_context_commands.py` — dedicated module for !save/!load/!reset/!context handlers
+
+---
+
+## Sources
+
+### Primary (HIGH confidence — verified by file read in this session)
+- `external/platform-agent_api/lambda_agent_api/agent_api.py` — AgentApi constructor, connect/close/send_message, _listen loop
+- `external/platform-agent_api/lambda_agent_api/server.py` — MsgEventTextChunk, MsgEventEnd, MsgStatus, AgentEventUnion types
+- `external/platform-agent_api/lambda_agent_api/client.py` — MsgUserMessage type
+- `external/platform-agent/src/api/external.py` — current (patched) and origin/main versions verified via git show
+- `adapter/matrix/handlers/__init__.py` — handler registration pattern
+- `adapter/matrix/store.py` — pending_confirm key pattern
+- `adapter/matrix/bot.py` — MatrixBot, build_runtime, _build_platform_from_env
+- `sdk/agent_session.py` — current AgentSessionClient (to be replaced)
+- `sdk/real.py` — RealPlatformClient (to be updated)
+- `sdk/prototype_state.py` — PrototypeStateStore (to be extended)
+- `core/protocol.py` — IncomingCommand, OutgoingMessage types
+- `pyproject.toml` — dependency versions
+- `external/platform-agent_api/pyproject.toml` — Python version constraint
+
+### Tertiary (LOW confidence)
+- Docker best practices for Python apps [ASSUMED] — standard industry pattern
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- AgentApi interface: HIGH — read source directly
+- platform-agent origin/main diff: HIGH — verified via `git show origin/main`
+- handler registration pattern: HIGH — read all handler files
+- pending_confirm key pattern: HIGH — read store.py directly
+- tokens_used interception: MEDIUM — pattern clear but implementation needs care
+- Docker/docker-compose: MEDIUM — standard pattern, not verified against specific matrix-nio requirements
+
+**Research date:** 2026-04-16
+**Valid until:** 2026-05-16 (lambda_agent_api is local — stable until platform team updates it)

.planning/phases/05-mvp-deployment/05-01-PLAN.md

@@ -0,0 +1,158 @@
+---
+phase: 05-mvp-deployment
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - adapter/matrix/reconciliation.py
+  - adapter/matrix/bot.py
+  - tests/adapter/matrix/test_reconciliation.py
+  - tests/adapter/matrix/test_restart_persistence.py
+autonomous: true
+requirements:
+  - PH05-01
+  - PH05-03
+must_haves:
+  truths:
+    - "On restart, existing Matrix Space and child-room topology is rebuilt before live sync begins."
+    - "Restart recovery preserves Space+rooms UX instead of creating duplicate DM-style working rooms."
+    - "Recovered rooms regain user metadata, room metadata, and chat bindings needed for normal routing."
+    - "Legacy working rooms missing `platform_chat_id` are backfilled deterministically during startup before strict routing handles traffic."
+  artifacts:
+    - path: "adapter/matrix/reconciliation.py"
+      provides: "Authoritative restart reconciliation from Matrix topology into local metadata"
+    - path: "adapter/matrix/bot.py"
+      provides: "Startup wiring that runs reconciliation before sync_forever"
+    - path: "tests/adapter/matrix/test_reconciliation.py"
+      provides: "Regression coverage for startup recovery and idempotence"
+  key_links:
+    - from: "adapter/matrix/bot.py"
+      to: "adapter/matrix/reconciliation.py"
+      via: "startup bootstrap before sync_forever"
+      pattern: "reconcil"
+    - from: "adapter/matrix/reconciliation.py"
+      to: "core/chat.py"
+      via: "chat manager rebuild for recovered rooms"
+      pattern: "get_or_create"
+---
+
+<objective>
+Rebuild Matrix-local routing state from authoritative Space topology before the bot processes live traffic.
+
+Purpose: Preserve the Phase 01 Space+rooms contract after restart even if SQLite metadata is partial or missing.
+Output: A startup reconciliation module, bot wiring, and regression tests proving no DM-first duplication on restart.
+</objective>
+
+<execution_context>
+@/Users/a/.codex/get-shit-done/workflows/execute-plan.md
+@/Users/a/.codex/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/05-mvp-deployment/05-RESEARCH.md
+@.planning/phases/05-mvp-deployment/05-VALIDATION.md
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-SUMMARY.md
+@adapter/matrix/bot.py
+@adapter/matrix/store.py
+@adapter/matrix/handlers/auth.py
+@tests/adapter/matrix/test_invite_space.py
+@tests/adapter/matrix/test_chat_space.py
+@tests/adapter/matrix/test_restart_persistence.py
+
+<interfaces>
+From `adapter/matrix/bot.py`:
+
+```python
+async def prepare_live_sync(client: AsyncClient) -> str | None:
+    response = await client.sync(timeout=0, full_state=True)
+    if isinstance(response, SyncResponse):
+        return response.next_batch
+    return None
+```
+
+```python
+class MatrixBot:
+    async def _bootstrap_unregistered_room(
+        self,
+        room: MatrixRoom,
+        sender: str,
+    ) -> list[OutgoingEvent] | None: ...
+```
+
+From `adapter/matrix/store.py`:
+
+```python
+async def get_room_meta(store: StateStore, room_id: str) -> dict | None: ...
+async def set_room_meta(store: StateStore, room_id: str, meta: dict) -> None: ...
+async def get_user_meta(store: StateStore, matrix_user_id: str) -> dict | None: ...
+async def set_user_meta(store: StateStore, matrix_user_id: str, meta: dict) -> None: ...
+async def next_platform_chat_id(store: StateStore) -> str: ...
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Add restart reconciliation regression coverage</name>
+  <files>tests/adapter/matrix/test_reconciliation.py, tests/adapter/matrix/test_restart_persistence.py</files>
+  <read_first>tests/adapter/matrix/test_invite_space.py, tests/adapter/matrix/test_chat_space.py, tests/adapter/matrix/test_restart_persistence.py, adapter/matrix/bot.py, adapter/matrix/handlers/auth.py, .planning/phases/05-mvp-deployment/05-RESEARCH.md</read_first>
+  <behavior>
+    - Test 1: startup recovery rebuilds user space metadata, room metadata, and chat bindings from Matrix topology without creating new working rooms (per D-Phase05-reset and PH05-01).
+    - Test 2: reconciliation is idempotent and safe when local SQLite state is already present.
+    - Test 3: reconciliation happens before lazy `_bootstrap_unregistered_room()` would run for existing rooms (per PH05-03).
+    - Test 4: legacy room metadata missing `platform_chat_id` is backfilled deterministically at startup and persisted before routed handling begins.
+  </behavior>
+  <acceptance_criteria>
+    - `tests/adapter/matrix/test_reconciliation.py` exists and names reconciliation entrypoints explicitly.
+    - The new tests assert restored `space_id`, `chat_id`, `matrix_user_id`, and `platform_chat_id` values for recovered rooms.
+    - The regression slice also proves existing Space onboarding behavior still passes by running `test_invite_space.py` and `test_chat_space.py`.
+    - The automated command in `<verify>` fails before implementation or would fail if reconciliation is removed.
+  </acceptance_criteria>
+  <action>Create a dedicated `tests/adapter/matrix/test_reconciliation.py` module and extend restart persistence coverage so Phase 05 has a real Wave 0 contract. Model the recovered topology after the Phase 01 Space+rooms onboarding tests, not a DM-first flow, and explicitly keep those onboarding regressions in the verification slice so restart hardening cannot break provisioning UX. Cover recovery of `user_meta`, `room_meta`, `ChatManager` bindings, and room-local routing fields from Matrix-side state before live callbacks begin, including deterministic backfill for legacy rooms that predate `platform_chat_id`. Keep temporary UX state out of scope, per research.</action>
+  <verify>
+    <automated>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 -v</automated>
+  </verify>
+  <done>Phase 05 has failing-or-red-before-code tests that define authoritative restart reconciliation behavior and exclude duplicate room provisioning.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Implement authoritative startup reconciliation and wire it before live sync</name>
+  <files>adapter/matrix/reconciliation.py, adapter/matrix/bot.py</files>
+  <read_first>adapter/matrix/bot.py, adapter/matrix/store.py, adapter/matrix/handlers/auth.py, tests/adapter/matrix/test_reconciliation.py, tests/adapter/matrix/test_restart_persistence.py, .planning/phases/05-mvp-deployment/05-RESEARCH.md</read_first>
+  <behavior>
+    - Test 1: startup rebuild runs after login and initial full-state fetch, but before `sync_forever()` processes live events.
+    - Test 2: recovered rooms keep their existing Space+rooms identity and do not trigger `_bootstrap_unregistered_room()` unless the room is genuinely new.
+    - Test 3: local metadata can be rebuilt from Matrix topology when SQLite entries are missing, while existing valid metadata remains stable.
+    - Test 4: startup repair assigns a deterministic `platform_chat_id` to legacy rooms missing that field and persists it before routed platform calls can occur.
+  </behavior>
+  <acceptance_criteria>
+    - `adapter/matrix/reconciliation.py` exports a focused reconciliation entrypoint used by startup code.
+    - `adapter/matrix/bot.py` invokes reconciliation before `client.sync_forever(...)`.
+    - Recovered room metadata includes `room_type`, `chat_id`, `space_id`, `matrix_user_id`, and `platform_chat_id` where available or rebuildable.
+    - Legacy rooms missing `platform_chat_id` follow one documented startup backfill path rather than ad hoc routing fallbacks.
+  </acceptance_criteria>
+  <action>Implement a restart recovery module that treats Matrix topology as authoritative, per the Phase 05 reset and research notes. Rebuild missing local metadata for Space-owned working rooms, deterministically backfill missing `platform_chat_id` values for legacy rooms, and re-create `ChatManager` entries needed by routing, while keeping SQLite as a rebuildable cache rather than the source of truth. Wire the new reconciliation step into startup after the initial full-state sync and before live sync begins, and keep the onboarding regression slice green while doing it. Do not widen into timeline scraping, new storage backends, or DM-first fallbacks.</action>
+  <verify>
+    <automated>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</automated>
+  </verify>
+  <done>Restart recovery restores the minimum durable state for existing Space rooms before live traffic, and the guarded regression suite passes.</done>
+</task>
+
+</tasks>
+
+<verification>
+Run the onboarding, reconciliation, restart-persistence, and Matrix dispatcher slices together. Confirm startup now has a deterministic pre-sync recovery and legacy-room backfill step instead of relying on lazy room bootstrap or routing-time fallbacks for existing topology.
+</verification>
+
+<success_criteria>
+The bot can restart with partial or empty local room metadata, rebuild managed Space rooms before live sync, and continue handling those rooms without creating duplicate onboarding rooms.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-mvp-deployment/05-01-SUMMARY.md`
+</output>

.planning/phases/05-mvp-deployment/05-01-SUMMARY.md

@@ -0,0 +1,99 @@
+---
+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*

.planning/phases/05-mvp-deployment/05-02-PLAN.md

@@ -0,0 +1,156 @@
+---
+phase: 05-mvp-deployment
+plan: 02
+type: execute
+wave: 2
+depends_on:
+  - 05-01
+files_modified:
+  - adapter/matrix/handlers/__init__.py
+  - adapter/matrix/handlers/context_commands.py
+  - adapter/matrix/routed_platform.py
+  - tests/adapter/matrix/test_context_commands.py
+  - tests/adapter/matrix/test_routed_platform.py
+autonomous: true
+requirements:
+  - PH05-02
+must_haves:
+  truths:
+    - "Each working Matrix room uses its own durable `platform_chat_id` as the real agent context boundary."
+    - "`!clear` resets only the current room by rotating its `platform_chat_id` and disconnecting the old upstream chat."
+    - "Save, load, context, and routed send paths resolve through room-local platform context, not shared user state."
+    - "Strict room routing assumes startup reconciliation has already repaired legacy rooms missing `platform_chat_id`."
+  artifacts:
+    - path: "adapter/matrix/handlers/context_commands.py"
+      provides: "Room-local `!clear`, save/load/context resolution, and upstream disconnect behavior"
+    - path: "adapter/matrix/routed_platform.py"
+      provides: "Strict room -> agent_id + platform_chat_id routing"
+    - path: "tests/adapter/matrix/test_context_commands.py"
+      provides: "Regression coverage for `!clear` and room-local context commands"
+  key_links:
+    - from: "adapter/matrix/handlers/__init__.py"
+      to: "adapter/matrix/handlers/context_commands.py"
+      via: "IncomingCommand registration for `clear`"
+      pattern: "\"clear\""
+    - from: "adapter/matrix/routed_platform.py"
+      to: "adapter/matrix/store.py"
+      via: "room metadata lookup"
+      pattern: "platform_chat_id"
+---
+
+<objective>
+Make room-local platform context explicit and user-facing by shipping real `!clear` semantics and strict per-room routing.
+
+Purpose: Phase 05 must preserve Space+rooms UX while giving each room a true upstream context boundary.
+Output: Updated command wiring, room-local context reset behavior, and routing regressions tied to `platform_chat_id`.
+</objective>
+
+<execution_context>
+@/Users/a/.codex/get-shit-done/workflows/execute-plan.md
+@/Users/a/.codex/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/05-mvp-deployment/05-RESEARCH.md
+@.planning/phases/05-mvp-deployment/05-VALIDATION.md
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-SUMMARY.md
+@adapter/matrix/handlers/__init__.py
+@adapter/matrix/handlers/context_commands.py
+@adapter/matrix/routed_platform.py
+@tests/adapter/matrix/test_context_commands.py
+@tests/adapter/matrix/test_routed_platform.py
+
+<interfaces>
+From `adapter/matrix/handlers/__init__.py`:
+
+```python
+dispatcher.register(
+    IncomingCommand,
+    "reset",
+    make_handle_reset(store, prototype_state)
+    if prototype_state is not None
+    else handle_settings,
+)
+```
+
+From `adapter/matrix/handlers/context_commands.py`:
+
+```python
+async def _resolve_context_scope(
+    event: IncomingCommand,
+    store: StateStore,
+    chat_mgr,
+) -> tuple[str, str | None]: ...
+```
+
+From `adapter/matrix/routed_platform.py`:
+
+```python
+async def _resolve_delegate(self, user_id: str, local_chat_id: str) -> tuple[PlatformClient, str]:
+    ...
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Expand room-local context and clear-command tests</name>
+  <files>tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py</files>
+  <read_first>tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py, adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py, .planning/phases/05-mvp-deployment/05-VALIDATION.md</read_first>
+  <behavior>
+    - Test 1: `!clear` rotates only the current room's `platform_chat_id` and disconnects only the old upstream chat (per PH05-02).
+    - Test 2: `!clear` is the supported command name; `!reset` may remain as a compatibility alias but must not be the only registered path.
+    - Test 3: routed send/stream paths fail fast when room metadata lacks `agent_id` or `platform_chat_id` instead of silently sharing context.
+    - Test 4: routed behavior uses startup-repaired room metadata and does not introduce a second fallback path that invents `platform_chat_id` during message handling.
+  </behavior>
+  <acceptance_criteria>
+    - Tests explicitly mention `clear` in command registration or command invocation.
+    - The context-command tests assert old and new `platform_chat_id` values and upstream disconnect behavior.
+    - The routed-platform tests assert room-local IDs are passed to delegates unchanged.
+  </acceptance_criteria>
+  <action>Extend the current Matrix context-command and routed-platform regressions so Phase 05 has direct coverage for `!clear`, room-local `platform_chat_id` rotation, and fail-fast routing when room bindings are incomplete. Treat startup reconciliation from `05-01` as the only supported repair path for legacy rooms missing `platform_chat_id`; the routed path must consume repaired metadata, not synthesize new room identities on demand. Preserve the Phase 04 prototype-state behavior where it still fits, but anchor new checks on per-room context isolation rather than shared session assumptions.</action>
+  <verify>
+    <automated>pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py -v</automated>
+  </verify>
+  <done>The tests define the Phase 05 room-local contract for reset/clear and for routed upstream calls.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Ship real room-local `!clear` semantics and strict routing</name>
+  <files>adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py</files>
+  <read_first>adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py, tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py, .planning/phases/05-mvp-deployment/05-RESEARCH.md</read_first>
+  <behavior>
+    - Test 1: command registration exposes `!clear` as the real context-reset entrypoint for Matrix rooms.
+    - Test 2: only the active room's `platform_chat_id` rotates, and only the old upstream chat session is disconnected.
+    - Test 3: all room-local context commands resolve through recovered room metadata instead of falling back to shared user scope.
+    - Test 4: strict routing stays strict at runtime because legacy-room repair was already handled at startup by `05-01`, not by hidden message-path fallbacks.
+  </behavior>
+  <acceptance_criteria>
+    - `adapter/matrix/handlers/__init__.py` registers `clear`; if `reset` remains, it is clearly a compatibility alias.
+    - `adapter/matrix/handlers/context_commands.py` resolves and rotates room-local platform context without touching other rooms.
+    - `adapter/matrix/routed_platform.py` keeps explicit `MATRIX_ROUTE_INCOMPLETE` behavior when bindings are missing.
+  </acceptance_criteria>
+  <action>Update the Matrix context command surface to match the Phase 05 contract: real `!clear`, room-local `platform_chat_id` rotation, and upstream disconnect scoped to the old room context. Keep `save`, `load`, and `context` anchored to the same room-local identity. Tighten routed-platform behavior only where needed to preserve fail-fast semantics after startup reconciliation has repaired legacy rooms; do not reintroduce shared chat state, user-level reset behavior, or message-time backfill of missing `platform_chat_id`.</action>
+  <verify>
+    <automated>pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v</automated>
+  </verify>
+  <done>Users can clear one working room without affecting others, and all routed upstream calls stay bound to room-local platform context.</done>
+</task>
+
+</tasks>
+
+<verification>
+Run the context and routed-platform slices plus Matrix dispatcher smoke coverage to confirm the exposed command name and room-local routing behavior are consistent.
+</verification>
+
+<success_criteria>
+Every working Matrix room has an independent upstream context boundary, and `!clear` resets only the room where it is invoked.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-mvp-deployment/05-02-SUMMARY.md`
+</output>

.planning/phases/05-mvp-deployment/05-02-SUMMARY.md

@@ -0,0 +1,106 @@
+---
+phase: 05-mvp-deployment
+plan: 02
+subsystem: matrix
+tags: [matrix, routing, context, platform-chat-id, testing]
+requires:
+  - phase: 05-01
+    provides: startup reconciliation for room metadata before live routing
+provides:
+  - room-local `!clear` coverage and command registration
+  - strict room-local context resolution for save/context flows
+  - fail-fast routed-platform regressions for incomplete room bindings
+affects: [matrix-dispatcher, routed-platform, startup-reconciliation]
+tech-stack:
+  added: []
+  patterns: [per-room platform context, compatibility alias registration, fail-fast routing]
+key-files:
+  created: []
+  modified:
+    - adapter/matrix/handlers/__init__.py
+    - adapter/matrix/handlers/context_commands.py
+    - tests/adapter/matrix/test_context_commands.py
+    - tests/adapter/matrix/test_routed_platform.py
+key-decisions:
+  - "Expose `clear` only when prototype room-context support is available, while keeping `reset` as a compatibility alias."
+  - "Require recovered `platform_chat_id` for save/context/clear flows instead of falling back to shared local chat ids."
+patterns-established:
+  - "Matrix room context commands resolve through room metadata repaired at startup, not message-time backfill."
+  - "Reset semantics rotate one room's upstream chat id and disconnect only that old upstream session."
+requirements-completed: [PH05-02]
+duration: 16 min
+completed: 2026-04-27
+---
+
+# Phase 05 Plan 02: Room-local clear and strict Matrix routing Summary
+
+**Room-local `!clear` command coverage, strict per-room `platform_chat_id` context resolution, and fail-fast Matrix routing regressions**
+
+## Performance
+
+- **Duration:** 16 min
+- **Started:** 2026-04-27T22:00:00Z
+- **Completed:** 2026-04-27T22:15:58Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+- Added RED/GREEN regression coverage for `!clear`, room-local chat-id rotation, and strict routed-platform failure modes.
+- Registered `clear` as the supported reset entrypoint when room-context support exists, while preserving `reset` as a compatibility alias.
+- Removed shared-context fallbacks from save/context handling and fixed reset to clear the old upstream prototype session before rotation.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Expand room-local context and clear-command tests** - `ae37476` (test)
+2. **Task 2: Ship real room-local `!clear` semantics and strict routing** - `85e2fda` (feat)
+
+## Files Created/Modified
+- `adapter/matrix/handlers/__init__.py` - registers `clear` for runtimes with prototype room-context support and keeps `reset` as the compatibility alias.
+- `adapter/matrix/handlers/context_commands.py` - requires room-local `platform_chat_id` for save/context/clear flows and disconnects the old upstream context on clear.
+- `tests/adapter/matrix/test_context_commands.py` - covers room-local clear rotation, upstream disconnect, and clear registration.
+- `tests/adapter/matrix/test_routed_platform.py` - covers incomplete-room fail-fast behavior and repaired metadata routing.
+
+## Decisions Made
+- Exposed `clear` only on runtimes that actually have prototype room-context support so Phase 05 semantics do not break older MVP smoke tests.
+- Treated startup-repaired room metadata as the only supported source of `platform_chat_id` for context commands instead of falling back to local chat ids.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Clear path was wiping the new context instead of the old upstream session**
+- **Found during:** Task 2 (Ship real room-local `!clear` semantics and strict routing)
+- **Issue:** `make_handle_reset()` cleared prototype session state for the newly generated chat id, leaving the previous upstream context intact.
+- **Fix:** Cleared prototype state for the old `platform_chat_id` before rotating to the new room-local id, and kept the new context empty as well.
+- **Files modified:** `adapter/matrix/handlers/context_commands.py`
+- **Verification:** `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`
+- **Committed in:** `85e2fda`
+
+---
+
+**Total deviations:** 1 auto-fixed (1 bug)
+**Impact on plan:** The auto-fix was required for correct room-local clear behavior. No scope creep.
+
+## Issues Encountered
+- Plain `pytest` used an environment without `PyYAML`; verification was switched to `uv run pytest` with `UV_CACHE_DIR=/tmp/uv-cache-surfaces`.
+- Shared shell env exposed `MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml`, which broke unrelated Matrix smoke tests. Verification was run with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND=''` to match the intended mock-runtime test setup.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Matrix room-local clear semantics and routing contracts are now explicit and covered.
+- Phase 05 follow-on work can assume startup reconciliation remains the only supported repair path for missing room routing metadata.
+
+---
+*Phase: 05-mvp-deployment*
+*Completed: 2026-04-27*
+
+## Self-Check: PASSED
+
+- Found `.planning/phases/05-mvp-deployment/05-02-SUMMARY.md`
+- Found commit `ae37476`
+- Found commit `85e2fda`

.planning/phases/05-mvp-deployment/05-03-PLAN.md

@@ -0,0 +1,145 @@
+---
+phase: 05-mvp-deployment
+plan: 03
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - adapter/matrix/files.py
+  - sdk/real.py
+  - tests/adapter/matrix/test_files.py
+  - tests/platform/test_real.py
+autonomous: true
+requirements:
+  - PH05-04
+must_haves:
+  truths:
+    - "Incoming Matrix attachments are written into a room-safe shared-volume path and passed upstream as relative workspace paths."
+    - "Agent-emitted files can be returned to Matrix users without inventing a separate file proxy."
+    - "The shared-volume contract works with the Phase 05 `/agents` deployment shape."
+  artifacts:
+    - path: "adapter/matrix/files.py"
+      provides: "Room-safe shared-volume path building and path resolution"
+    - path: "sdk/real.py"
+      provides: "Attachment path passthrough and send-file normalization"
+    - path: "tests/adapter/matrix/test_files.py"
+      provides: "Regression coverage for shared-volume path construction"
+  key_links:
+    - from: "adapter/matrix/files.py"
+      to: "sdk/real.py"
+      via: "relative `workspace_path` transport"
+      pattern: "workspace_path"
+    - from: "sdk/real.py"
+      to: "adapter/matrix/bot.py"
+      via: "OutgoingMessage attachments rendered back to Matrix"
+      pattern: "MsgEventSendFile"
+---
+
+<objective>
+Harden the Matrix attachment path contract around the shared deployment volume instead of custom transport shims.
+
+Purpose: Phase 05 file handling must survive real deployment with room-safe paths and outbound file delivery through the existing shared-volume model.
+Output: Attachment-path regressions and any targeted runtime fixes needed for `/agents`-backed shared volume behavior.
+</objective>
+
+<execution_context>
+@/Users/a/.codex/get-shit-done/workflows/execute-plan.md
+@/Users/a/.codex/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/05-mvp-deployment/05-RESEARCH.md
+@.planning/phases/05-mvp-deployment/05-VALIDATION.md
+@docs/deploy-architecture.md
+@docs/superpowers/specs/2026-04-20-matrix-shared-workspace-file-flow-design.md
+@adapter/matrix/files.py
+@sdk/real.py
+@tests/adapter/matrix/test_files.py
+@tests/platform/test_real.py
+
+<interfaces>
+From `adapter/matrix/files.py`:
+
+```python
+def build_workspace_attachment_path(
+    *,
+    workspace_root: Path,
+    matrix_user_id: str,
+    room_id: str,
+    filename: str,
+    timestamp: str | None = None,
+) -> tuple[str, Path]: ...
+```
+
+From `sdk/real.py`:
+
+```python
+@staticmethod
+def _attachment_paths(attachments: list[Attachment] | None) -> list[str]: ...
+
+@staticmethod
+def _attachment_from_send_file_event(event: MsgEventSendFile) -> Attachment: ...
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Add shared-volume file contract tests for `/agents` deployment</name>
+  <files>tests/adapter/matrix/test_files.py, tests/platform/test_real.py</files>
+  <read_first>tests/adapter/matrix/test_files.py, tests/platform/test_real.py, adapter/matrix/files.py, sdk/real.py, docs/deploy-architecture.md, .planning/phases/05-mvp-deployment/05-RESEARCH.md</read_first>
+  <behavior>
+    - Test 1: incoming Matrix files land under a room-safe `surfaces/matrix/.../inbox/...` path that remains relative to the agent workspace contract.
+    - Test 2: upstream file events normalize `/workspace/...` and `/agents/...`-style absolute paths into relative `workspace_path` values.
+    - Test 3: attachment forwarding never switches to inline blobs or HTTP shim URLs (per PH05-04).
+  </behavior>
+  <acceptance_criteria>
+    - `tests/adapter/matrix/test_files.py` asserts the path namespace includes sanitized user and room components.
+    - `tests/platform/test_real.py` contains explicit coverage for send-file path normalization.
+    - The automated test command in `<verify>` exercises both inbound and outbound sides of the shared-volume contract.
+  </acceptance_criteria>
+  <action>Expand the file-flow regressions around the real deployment contract described in research and `docs/deploy-architecture.md`. Keep the tests centered on relative `workspace_path` transport and room-safe on-disk layout. Do not introduce proxy URLs, base64 payload transport, or new platform endpoints.</action>
+  <verify>
+    <automated>pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v</automated>
+  </verify>
+  <done>Phase 05 has direct test coverage for `/agents`-backed shared-volume behavior across inbound and outbound file paths.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Tighten attachment path handling for the shared volume contract</name>
+  <files>adapter/matrix/files.py, sdk/real.py</files>
+  <read_first>adapter/matrix/files.py, sdk/real.py, tests/adapter/matrix/test_files.py, tests/platform/test_real.py, docs/deploy-architecture.md</read_first>
+  <behavior>
+    - Test 1: inbound attachment helpers keep returning relative paths even when the bot writes into `/agents`.
+    - Test 2: outbound file normalization accepts absolute paths from the agent runtime but strips them back to relative workspace paths for Matrix rendering.
+    - Test 3: no code path emits non-relative attachment references to the upstream agent API.
+  </behavior>
+  <acceptance_criteria>
+    - `sdk/real.py` only forwards relative attachment paths to the agent API.
+    - `sdk/real.py` normalizes both `/workspace` and `/agents` absolute roots if present in send-file events.
+    - `adapter/matrix/files.py` remains the single source of truth for room-safe attachment path construction.
+  </acceptance_criteria>
+  <action>Implement only the minimum runtime changes needed to satisfy the shared-volume tests. Keep `adapter/matrix/files.py` as the single place that builds surface-owned attachment paths, and keep `sdk/real.py` responsible only for attachment passthrough and send-file normalization. Do not widen this plan into compose edits, registry redesign, or bot command changes.</action>
+  <verify>
+    <automated>pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v</automated>
+  </verify>
+  <done>Incoming and outgoing file references stay compatible with the real shared-volume deployment contract, and the targeted file/path regressions pass.</done>
+</task>
+
+</tasks>
+
+<verification>
+Run the Matrix file helper, real platform client, and outgoing-send slices together so the shared-volume contract is validated from write path through return-to-user rendering.
+</verification>
+
+<success_criteria>
+The Matrix bot and agent runtime can exchange file references through the shared volume using only relative workspace paths and room-safe storage layout.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md`
+</output>

.planning/phases/05-mvp-deployment/05-03-SUMMARY.md

@@ -0,0 +1,103 @@
+---
+phase: 05-mvp-deployment
+plan: 03
+subsystem: infra
+tags: [matrix, attachments, shared-volume, agents, pytest]
+requires:
+  - phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
+    provides: direct AgentApi integration and Matrix outgoing file rendering
+provides:
+  - shared-volume attachment path regressions for /agents deployment
+  - relative workspace-path normalization for upstream attachment transport
+  - send-file event normalization for Matrix outbound file rendering
+affects: [matrix, deployment, shared-volume, file-transfer]
+tech-stack:
+  added: []
+  patterns: [relative workspace_path transport, shared-volume root normalization]
+key-files:
+  created: []
+  modified:
+    - tests/adapter/matrix/test_files.py
+    - tests/platform/test_real.py
+    - sdk/real.py
+key-decisions:
+  - "Keep adapter/matrix/files.py as the only path-construction source; sdk/real.py only normalizes attachment references crossing the shared-volume boundary."
+  - "Normalize both /workspace and /agents absolute paths back to relative workspace paths before forwarding to the agent API or rendering Matrix send-file events."
+patterns-established:
+  - "Matrix attachment transport stays relative even when the bot sees absolute shared-volume paths."
+  - "Agent-emitted file paths are rendered back to Matrix without HTTP proxy shims or inline blobs."
+requirements-completed: [PH05-04]
+duration: 3 min
+completed: 2026-04-27
+---
+
+# Phase 05 Plan 03: Shared-volume attachment path hardening Summary
+
+**Room-safe Matrix inbox paths and relative shared-volume attachment normalization for `/agents` deployment**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-04-27T22:02:34Z
+- **Completed:** 2026-04-27T22:05:41Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- Added regression coverage for room-safe `surfaces/matrix/.../inbox/...` attachment layout under `/agents` workspaces.
+- Added explicit tests for `/workspace/...` and `/agents/...` attachment-path normalization on both upstream send and downstream send-file rendering.
+- Tightened `RealPlatformClient` so only relative `workspace_path` values are forwarded to the agent API.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add shared-volume file contract tests for `/agents` deployment** - `cafb0ec` (test)
+2. **Task 2: Tighten attachment path handling for the shared volume contract** - `9a03160` (fix)
+
+## Files Created/Modified
+- `tests/adapter/matrix/test_files.py` - covers room-safe shared-volume inbox paths under an `/agents` workspace root.
+- `tests/platform/test_real.py` - covers relative attachment forwarding and send-file normalization for `/workspace` and `/agents` paths.
+- `sdk/real.py` - normalizes shared-volume roots before attachments cross the upstream or Matrix rendering boundary.
+
+## Decisions Made
+- Kept `adapter/matrix/files.py` unchanged so path construction remains centralized there.
+- Reused one normalization helper in `sdk/real.py` for both `_attachment_paths()` and `_attachment_from_send_file_event()` to keep inbound and outbound behavior aligned.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Adjusted verification to use the project uv environment**
+- **Found during:** Task 2 (Tighten attachment path handling for the shared volume contract)
+- **Issue:** The plan's raw `pytest` command collected with an interpreter missing `PyYAML`, which blocked `tests/adapter/matrix/test_send_outgoing.py` before runtime assertions could execute.
+- **Fix:** Re-ran verification with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest ...`, matching the repo's `CLAUDE.md` guidance and the project `.venv`.
+- **Files modified:** None
+- **Verification:** `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`
+- **Committed in:** None (verification-environment adjustment only)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** No scope creep. The deviation only changed the verification entrypoint so the planned test slice could run in the correct environment.
+
+## Issues Encountered
+- The ambient `pytest` resolved to a different virtualenv than the project `.venv`, so direct verification was unreliable for dependency-backed Matrix tests.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Shared-volume file references now stay relative across inbound bot downloads, agent API attachment transport, and outbound Matrix send-file rendering.
+- Phase 05 compose and deployment work can assume the `/agents` contract without adding file proxy infrastructure.
+
+## Self-Check: PASSED
+
+- Found `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md`
+- Verified commit `cafb0ec` exists in git history
+- Verified commit `9a03160` exists in git history
+
+---
+*Phase: 05-mvp-deployment*
+*Completed: 2026-04-27*

.planning/phases/05-mvp-deployment/05-04-PLAN.md

@@ -0,0 +1,128 @@
+---
+phase: 05-mvp-deployment
+plan: 04
+type: execute
+wave: 2
+depends_on:
+  - 05-03
+files_modified:
+  - docker-compose.prod.yml
+  - docker-compose.fullstack.yml
+  - Dockerfile
+  - .env.example
+  - README.md
+  - docs/deploy-architecture.md
+autonomous: true
+requirements:
+  - PH05-05
+must_haves:
+  truths:
+    - "Production handoff uses a bot-only compose artifact instead of the internal full-stack harness."
+    - "Internal E2E compose brings up the bot, platform-agent, and shared volume with explicit health-gated startup."
+    - "Deployment docs and env examples match the split compose artifacts and shared `/agents` contract."
+  artifacts:
+    - path: "docker-compose.prod.yml"
+      provides: "Bot-only deployment handoff artifact"
+    - path: "docker-compose.fullstack.yml"
+      provides: "Internal E2E harness with shared volume and dependency gating"
+    - path: ".env.example"
+      provides: "Documented runtime contract for Phase 05 deployment"
+  key_links:
+    - from: "docker-compose.fullstack.yml"
+      to: "docker-compose.prod.yml"
+      via: "shared service definition or explicit duplication"
+      pattern: "matrix-bot"
+    - from: "docs/deploy-architecture.md"
+      to: "docker-compose.prod.yml"
+      via: "operator handoff instructions"
+      pattern: "prod"
+---
+
+<objective>
+Split deployment artifacts by operational intent so operator handoff and internal E2E testing stop sharing the same compose contract.
+
+Purpose: Phase 05 needs an explicit bot-only production artifact and a separate full-stack compose harness aligned with the shared-volume design.
+Output: `docker-compose.prod.yml`, `docker-compose.fullstack.yml`, and updated env/docs describing when to use each.
+</objective>
+
+<execution_context>
+@/Users/a/.codex/get-shit-done/workflows/execute-plan.md
+@/Users/a/.codex/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/05-mvp-deployment/05-RESEARCH.md
+@.planning/phases/05-mvp-deployment/05-VALIDATION.md
+@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md
+@docs/deploy-architecture.md
+@docker-compose.yml
+@Dockerfile
+@.env.example
+
+<interfaces>
+Current root compose contract:
+
+```yaml
+services:
+  platform-agent:
+    ...
+  matrix-bot:
+    build: .
+    env_file: .env
+    environment:
+      AGENT_BASE_URL: http://platform-agent:8000
+      SURFACES_WORKSPACE_DIR: /workspace
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create split prod and fullstack compose artifacts</name>
+  <files>docker-compose.prod.yml, docker-compose.fullstack.yml, Dockerfile, .env.example</files>
+  <read_first>docker-compose.yml, Dockerfile, .env.example, docs/deploy-architecture.md, .planning/phases/05-mvp-deployment/05-RESEARCH.md, .planning/phases/05-mvp-deployment/05-VALIDATION.md</read_first>
+  <acceptance_criteria>
+    - `docker-compose.prod.yml` defines only the bot-side runtime required for operator handoff.
+    - `docker-compose.fullstack.yml` includes the internal platform-agent service, shared volume mounts, and health-gated startup rather than sleep-based sequencing.
+    - `.env.example` documents the Phase 05 env contract without requiring the reader to inspect the old root compose file.
+  </acceptance_criteria>
+  <action>Create two explicit compose artifacts per PH05-05: a bot-only `docker-compose.prod.yml` for deployment handoff and a `docker-compose.fullstack.yml` for internal E2E runs. Align mounts and env values with the Phase 05 shared `/agents` volume direction from research. Reuse the existing Dockerfile unless a small compatibility edit is required. Do not keep the old single-file compose setup as the only documented runtime.</action>
+  <verify>
+    <automated>docker compose -f docker-compose.prod.yml config > /tmp/phase05-prod-compose.yml && docker compose -f docker-compose.fullstack.yml config > /tmp/phase05-fullstack-compose.yml && rg -n "^services:$|^  matrix-bot:$|^volumes:$|/agents" /tmp/phase05-prod-compose.yml && test -z "$(rg -n "^  platform-agent:$" /tmp/phase05-prod-compose.yml)" && rg -n "^  matrix-bot:$|^  platform-agent:$|condition: service_healthy|healthcheck:|/agents" /tmp/phase05-fullstack-compose.yml</automated>
+  </verify>
+  <done>Both compose files render successfully and express distinct operational roles: prod handoff vs internal full-stack testing.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Update deployment docs and operator guidance for the split artifacts</name>
+  <files>README.md, docs/deploy-architecture.md</files>
+  <read_first>README.md, docs/deploy-architecture.md, docker-compose.prod.yml, docker-compose.fullstack.yml, .env.example</read_first>
+  <acceptance_criteria>
+    - README or deploy doc tells the operator exactly which compose file to use for production vs internal E2E.
+    - The docs describe the shared `/agents` volume behavior and reference the relevant env vars.
+    - The old root `docker-compose.yml` is no longer the primary documented deployment path.
+  </acceptance_criteria>
+  <action>Update the repo docs so the Phase 05 deployment story is executable without inference: production handoff stays bot-only, full-stack compose is for internal E2E, and shared-volume file behavior is described in the same terms as the runtime artifacts. Keep documentation narrowly scoped to the shipped compose split; do not widen into platform-master or future storage design.</action>
+  <verify>
+    <automated>rg -n "docker-compose\\.prod|docker-compose\\.fullstack|/agents|prod handoff|full-stack" README.md docs/deploy-architecture.md .env.example && rg -n "production|deploy" README.md docs/deploy-architecture.md | rg "docker-compose\\.prod" && test -z "$(rg -n "docker compose up|docker-compose\\.yml" README.md docs/deploy-architecture.md | rg "production|deploy")"</automated>
+  </verify>
+  <done>The docs and env guidance match the new compose artifacts and no longer imply a single shared deployment file.</done>
+</task>
+
+</tasks>
+
+<verification>
+Render both compose files, then grep the docs for the new artifact names and `/agents` references so the operator contract is explicit and consistent.
+</verification>
+
+<success_criteria>
+An operator can deploy the Matrix bot with the bot-only compose file, while developers can run the internal end-to-end harness separately without reinterpreting the deployment docs.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-mvp-deployment/05-04-SUMMARY.md`
+</output>

.planning/phases/05-mvp-deployment/05-04-SUMMARY.md

@@ -0,0 +1,93 @@
+---
+phase: 05-mvp-deployment
+plan: 04
+subsystem: infra
+tags: [docker-compose, matrix, deployment, agents, docs]
+requires:
+  - phase: 05-03
+    provides: "Shared /agents attachment contract and path normalization for Matrix runtime"
+provides:
+  - "docker-compose.prod.yml bot-only deployment handoff artifact"
+  - "docker-compose.fullstack.yml internal E2E harness with health-gated platform-agent startup"
+  - "README and deploy architecture docs aligned to the split compose contract"
+affects: [mvp-deployment, operator-handoff, internal-e2e]
+tech-stack:
+  added: [Docker Compose]
+  patterns: [split-compose-by-operational-intent, shared-agents-volume-contract]
+key-files:
+  created: [docker-compose.prod.yml, docker-compose.fullstack.yml]
+  modified: [.env.example, README.md, docs/deploy-architecture.md]
+key-decisions:
+  - "Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification."
+  - "Document /agents as the bot-side shared volume root while internal platform-agent keeps /workspace on the same volume."
+patterns-established:
+  - "Production operators use docker-compose.prod.yml and provide an external AGENT_BASE_URL."
+  - "Internal verification uses docker-compose.fullstack.yml with service_healthy gating instead of sleep-based startup."
+requirements-completed: [PH05-05]
+duration: 3 min
+completed: 2026-04-27
+---
+
+# Phase 05 Plan 04: Split deployment artifacts Summary
+
+**Bot-only production compose handoff plus a separate health-gated full-stack harness aligned to the shared `/agents` volume contract**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-04-27T22:12:42Z
+- **Completed:** 2026-04-27T22:16:09Z
+- **Tasks:** 2
+- **Files modified:** 5
+
+## Accomplishments
+- Added `docker-compose.prod.yml` as the operator-facing bot-only runtime artifact.
+- Added `docker-compose.fullstack.yml` for internal E2E runs with `platform-agent` health-gated startup.
+- Updated env and deployment docs so `/agents` and the split compose flow are explicit without relying on the old root compose file.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create split prod and fullstack compose artifacts** - `df6d8bf` (feat)
+2. **Task 2: Update deployment docs and operator guidance for the split artifacts** - `22a3a2b` (docs)
+
+**Plan metadata:** pending final docs commit after state updates
+
+## Files Created/Modified
+- `docker-compose.prod.yml` - bot-only deployment handoff with `/agents` volume contract
+- `docker-compose.fullstack.yml` - internal harness extending the bot service and adding health-checked `platform-agent`
+- `.env.example` - Phase 05 runtime variables for prod handoff and internal full-stack defaults
+- `README.md` - operator-facing instructions for choosing the correct compose artifact
+- `docs/deploy-architecture.md` - deployment topology and shared-volume guidance aligned to the split artifacts
+
+## Decisions Made
+- Split deployment packaging by operational intent instead of overloading one compose file for both prod handoff and internal testing.
+- Kept the bot’s absolute shared path rooted at `/agents` in docs and env examples while letting the internal `platform-agent` consume the same named volume at `/workspace`.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+- The docs verification grep treated `deploy` inside the filename `docs/deploy-architecture.md` as a false positive when root compose was still named explicitly. The fix was to remove the literal root compose filename from deploy-path wording while keeping the deprecation clear.
+
+## User Setup Required
+
+None - no external service configuration required beyond populating `.env` from `.env.example`.
+
+## Next Phase Readiness
+
+- Operators now have a bot-only compose artifact for handoff, and developers have a separate internal E2E harness.
+- Remaining Phase 05 work can rely on the split runtime contract without reinterpreting deployment docs.
+
+## Self-Check: PASSED
+
+- Summary file exists at `.planning/phases/05-mvp-deployment/05-04-SUMMARY.md`
+- Commit `df6d8bf` found in git history
+- Commit `22a3a2b` found in git history
+
+---
+*Phase: 05-mvp-deployment*
+*Completed: 2026-04-27*

.planning/phases/05-mvp-deployment/05-RESEARCH.md

@@ -0,0 +1,411 @@
+# Phase 05: MVP Deployment - Research
+
+**Researched:** 2026-04-28
+**Domain:** Matrix bot production deployment, restart reconciliation, per-room context isolation, shared-volume file transfer
+**Confidence:** HIGH
+
+## Project Constraints (from CLAUDE.md)
+
+- All platform calls must stay behind `platform/interface.py` (`PlatformClient` protocol).
+- Current platform implementation is a mock / replaceable adapter; architecture must not depend on unfinished upstream SDK.
+- Keep architecture decisions inside this repo and document contracts locally.
+- Prefer async, adapter/core separation, and do not bypass the existing `core/` and `adapter/` layering.
+- Use `uv sync` for dependency installation.
+- Use `pytest tests/ -v` and adapter-specific pytest slices for verification.
+- Never commit `.env`.
+- Dependency order remains fixed: `core/` first, `platform/` second, adapters after that.
+
+## Summary
+
+Phase 05 should not introduce a new stack. The established implementation path is to harden the existing `matrix-nio + SQLiteStore + RoutedPlatformClient + shared workspace volume` design so production restart behavior matches the current Space+rooms UX. The main architectural rule is: Matrix topology is authoritative for room existence, while local SQLite metadata is authoritative only after reconciliation has rebuilt it.
+
+The production-safe approach is to bind every working Matrix room to its own durable `platform_chat_id`, rotate only that identifier for `!clear`, and make restart recovery idempotent. Reconciliation should rebuild `user_meta`, `room_meta`, `ChatManager` entries, and missing routing fields from Matrix Space membership and room state before `sync_forever()` begins processing live traffic. Unknown rooms must be reconciled first, not silently converted into new chats.
+
+For files, keep the current shared-volume contract and relative `workspace_path` transport. Do not build HTTP file shims or embed file payloads in bot-side state. For deployment artifacts, split runtime intent explicitly: `docker-compose.prod.yml` is a bot-only handoff contract, while `docker-compose.fullstack.yml` is the internal E2E harness that brings up platform services and shared volumes together.
+
+**Primary recommendation:** Implement Phase 05 as a reconciliation-and-deploy hardening pass on the current Matrix stack, with Matrix Space state as source of truth and per-room `platform_chat_id` as the routing key.
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| `matrix-nio` | 0.25.2 | Async Matrix client, Spaces, media upload/download, token login, sync loop | Already in repo; official docs confirm support for Spaces, token login, `room_put_state`, `upload`, `download`, and `sync_forever` |
+| `sqlite3` / `SQLiteStore` | stdlib / repo-local | Durable bot metadata (`room_meta`, `user_meta`, routing state) | Small, local, restart-safe KV layer already used by runtime and tests |
+| `PyYAML` | 6.0.3 | Agent registry / deployment config parsing | Current repo standard for `config/matrix-agents.yaml`-style artifacts |
+| `httpx` | 0.28.1 | Async HTTP for auxiliary platform calls | Already used; fits async runtime and current codebase |
+| Docker Compose | v2 spec; local install `v2.40.3` | Prod/fullstack topology, shared named volumes, health-gated startup | Officially supports multi-file overlays, named volumes, and `service_healthy` gating |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| `structlog` | 25.5.0 | Structured runtime logging | Use for reconciliation summaries, routing mismatches, and deploy diagnostics |
+| `pydantic` | 2.13.3 | Typed config / payload validation | Use for any new deployment config or reconciliation report structures |
+| `python-dotenv` | 1.2.2 | Local env loading | Keep for local and compose-driven runtime config |
+| `pytest` | 9.0.3 | Test runner | Full phase verification and regression slices |
+| `pytest-asyncio` | 1.3.0 | Async test execution | Required for reconciliation/runtime tests |
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| `matrix-nio` | Synapse Admin / raw Matrix HTTP calls | Worse fit; repo already depends on nio abstractions and tests |
+| repo-local `SQLiteStore` | Redis/Postgres | Unnecessary operational scope increase for MVP deployment |
+| shared volume file flow | custom file proxy / presigned URLs | More moving parts, more auth/cleanup edge cases, no need for MVP |
+| split compose files | one overloaded compose file with profiles | Harder operator handoff; less explicit prod vs internal-test intent |
+
+**Installation:**
+```bash
+uv sync
+```
+
+**Version verification:** Verified on 2026-04-28 from PyPI and local environment.
+
+| Package | Verified Version | Publish Date | Source |
+|---------|------------------|--------------|--------|
+| `matrix-nio` | 0.25.2 | 2024-10-04 | PyPI |
+| `httpx` | 0.28.1 | 2024-12-06 | PyPI |
+| `structlog` | 25.5.0 | 2025-10-27 | PyPI |
+| `pydantic` | 2.13.3 | 2026-04-20 | PyPI |
+| `aiohttp` | 3.13.5 | 2026-03-31 | PyPI |
+| `PyYAML` | 6.0.3 | 2025-09-25 | PyPI |
+| `python-dotenv` | 1.2.2 | 2026-03-01 | PyPI |
+| `pytest` | 9.0.3 | 2026-04-07 | PyPI |
+| `pytest-asyncio` | 1.3.0 | 2025-11-10 | PyPI |
+
+## Architecture Patterns
+
+### Recommended Project Structure
+```text
+adapter/matrix/
+├── bot.py                    # startup, sync bootstrap, live callbacks
+├── reconciliation.py         # new: restart recovery from Matrix state
+├── files.py                  # shared-volume path building / materialization
+├── routed_platform.py        # room -> agent_id + platform_chat_id routing
+├── store.py                  # room_meta/user_meta helpers and counters
+└── handlers/
+    ├── auth.py               # Space + first room provisioning
+    ├── chat.py               # !new / !archive / !rename
+    └── context_commands.py   # !save / !load / !clear / !context
+
+deploy/
+├── docker-compose.prod.yml       # bot-only handoff
+└── docker-compose.fullstack.yml  # internal E2E stack
+```
+
+### Pattern 1: Matrix Space State Is Canonical, SQLite Is Rebuildable
+**What:** Treat Matrix Space membership and child-room state as the source of truth for room topology; use local SQLite metadata as a cached routing index that reconciliation can rebuild.
+**When to use:** Startup, DB loss, stale local metadata, and any deployment where rooms may outlive the bot process.
+**Example:**
+```python
+# Source: repo pattern from adapter/matrix/store.py + Matrix Space state
+room_meta = {
+    "room_type": "chat",
+    "chat_id": "C7",
+    "display_name": "Research",
+    "matrix_user_id": "@alice:example.org",
+    "space_id": "!space:example.org",
+    "agent_id": "agent-1",
+    "platform_chat_id": "42",
+}
+await set_room_meta(store, room_id, room_meta)
+await chat_mgr.get_or_create(
+    user_id=room_meta["matrix_user_id"],
+    chat_id=room_meta["chat_id"],
+    platform="matrix",
+    surface_ref=room_id,
+    name=room_meta["display_name"],
+)
+```
+
+### Pattern 2: Per-Room `platform_chat_id` Is the Only Real Context Boundary
+**What:** Route every working Matrix room to its own durable `platform_chat_id`.
+**When to use:** Normal messaging, `!save`, `!load`, `!context`, `!clear`, restart restoration.
+**Example:**
+```python
+# Source: adapter/matrix/routed_platform.py + adapter/matrix/handlers/context_commands.py
+old_chat_id = room_meta["platform_chat_id"]
+new_chat_id = await next_platform_chat_id(store)
+await set_platform_chat_id(store, room_id, new_chat_id)
+
+disconnect = getattr(platform, "disconnect_chat", None)
+if callable(disconnect):
+    await disconnect(old_chat_id)
+```
+
+### Pattern 3: `!clear` Means Chat-ID Rotation, Not Global Wipe
+**What:** Implement real clear by rotating only the current room's `platform_chat_id` and disconnecting the old upstream chat session.
+**When to use:** User-triggered context reset for one room.
+**Example:**
+```python
+# Source: adapter/matrix/handlers/context_commands.py
+room_id = await _resolve_room_id(event, chat_mgr)
+old_chat_id = (room_meta or {}).get("platform_chat_id") or room_id
+new_chat_id = await next_platform_chat_id(store)
+await set_platform_chat_id(store, room_id, new_chat_id)
+```
+
+### Pattern 4: Shared-Volume File Handoff Uses Relative Workspace Paths
+**What:** Persist incoming Matrix media into a room-scoped path under the shared workspace, and pass only relative paths to the agent.
+**When to use:** User uploads, staged attachments, agent-emitted files.
+**Example:**
+```python
+# Source: adapter/matrix/files.py
+relative_path = (
+    Path("surfaces") / "matrix" / safe_user / safe_room / "inbox" / f"{stamp}-{safe_name}"
+)
+return Attachment(
+    type=attachment.type,
+    url=attachment.url,
+    filename=filename,
+    mime_type=attachment.mime_type,
+    workspace_path=relative_path.as_posix(),
+)
+```
+
+### Pattern 5: Compose Split By Operational Intent
+**What:** Keep one compose artifact for operator handoff and one for internal full-stack testing.
+**When to use:** Deployment packaging.
+**Example:**
+```yaml
+# docker-compose.prod.yml
+services:
+  matrix-bot:
+    image: surfaces-bot:latest
+    env_file: .env
+    volumes:
+      - agents:/agents
+
+# docker-compose.fullstack.yml
+services:
+  matrix-bot:
+    extends:
+      file: docker-compose.prod.yml
+      service: matrix-bot
+  platform-agent:
+    ...
+volumes:
+  agents:
+```
+
+### Anti-Patterns to Avoid
+- **Lazy bootstrap as restart strategy:** `_bootstrap_unregistered_room()` is acceptable for first-contact repair, not as the primary restart recovery path in production.
+- **Per-user context identity:** a user-level or DM-level chat id breaks Space+rooms isolation and makes `!clear` incorrect.
+- **Global reset endpoint semantics:** `!clear` must not wipe other rooms or all agent state for a user.
+- **Absolute attachment paths in platform payloads:** keep agent attachment references relative to its workspace contract.
+- **Sleep-based service readiness:** use Compose healthchecks and dependency conditions, not shell `sleep`.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Matrix room/Space protocol | Raw custom HTTP wrappers for state events | `matrix-nio` `room_create`, `room_put_state`, `space_get_hierarchy`, `sync_forever`, `upload`, `download` | Official support already exists and repo tests are built around nio |
+| Restart topology discovery | Ad hoc timeline scraping | Full-state sync plus room state / Space child reconciliation | Timeline replay is noisy and brittle; state is the stable source |
+| File transfer bus | Base64 blobs or custom bot-side file API | Shared `/agents/` volume with relative `workspace_path` | Lower operational complexity and already matches upstream agent contract |
+| Compose startup sequencing | Shell loops / sleeps | `healthcheck` + `depends_on: condition: service_healthy` | Official Compose behavior is deterministic and observable |
+| Context reset | Deleting all SQLite rows or resetting the whole user | Rotate current room `platform_chat_id` and drop that room's live agent connection | Preserves other rooms and matches user expectation |
+
+**Key insight:** The deceptively hard problems in this phase are already solved by the current stack: Matrix room state, nio media handling, named volumes, and service health gating. Custom alternatives add more failure modes than value.
+
+## Common Pitfalls
+
+### Pitfall 1: Unknown room after restart creates a duplicate working chat
+**What goes wrong:** The bot treats an existing room as unregistered and provisions a fresh room/tree.
+**Why it happens:** Local SQLite metadata is missing, but Matrix topology still exists.
+**How to avoid:** Run reconciliation before live sync callbacks; only allow lazy bootstrap for genuinely new first-contact rooms.
+**Warning signs:** New `Чат N` rooms appear after restart without a matching user action.
+
+### Pitfall 2: `!clear` resets the wrong scope
+**What goes wrong:** Clearing one room also clears another room, or does nothing because the upstream session key did not change.
+**Why it happens:** Context is keyed by user or local `chat_id` instead of durable room-local `platform_chat_id`.
+**How to avoid:** Always resolve room -> `platform_chat_id`, rotate it, and disconnect only the old upstream chat.
+**Warning signs:** Two rooms share response history or `!context` reports the same platform context id.
+
+### Pitfall 3: Space child linkage is incomplete
+**What goes wrong:** Rooms exist but do not appear correctly under the user's Space.
+**Why it happens:** Missing or malformed `m.space.child` state, especially missing `via` data.
+**How to avoid:** Persist `space_id`, write `m.space.child` with `state_key=room_id`, and reconcile child links on startup.
+**Warning signs:** Element shows the room outside the Space, or not at all in the hierarchy.
+
+### Pitfall 4: Shared volume works locally but fails in deployment
+**What goes wrong:** Agent-generated files cannot be read by the bot, or bot-downloaded files are unreadable by the agent.
+**Why it happens:** Mount mismatch, wrong root (`/workspace` vs `/agents`), or container user/group permissions.
+**How to avoid:** Standardize one shared root, keep relative workspace paths, and align container permissions with Compose volume configuration.
+**Warning signs:** Attachment paths exist in metadata but not on disk inside the other container.
+
+### Pitfall 5: Compose `depends_on` starts too early
+**What goes wrong:** Bot starts before dependent services are actually ready.
+**Why it happens:** Short-form `depends_on` only waits for container start, not health.
+**How to avoid:** Use healthchecks and long-form `depends_on` with `service_healthy` in the full-stack compose file.
+**Warning signs:** First requests fail after fresh `docker compose up`, then succeed on retry.
+
+## Code Examples
+
+Verified patterns from official sources and current repo:
+
+### Create a Space with `matrix-nio`
+```python
+# Source: matrix-nio API docs
+space_resp = await client.room_create(
+    name=f"Lambda — {display_name}",
+    visibility=RoomVisibility.private,
+    invite=[matrix_user_id],
+    space=True,
+)
+```
+
+### Add a child room to a Space
+```python
+# Source: current repo pattern + Matrix spec
+await client.room_put_state(
+    room_id=space_id,
+    event_type="m.space.child",
+    content={"via": [homeserver]},
+    state_key=chat_room_id,
+)
+```
+
+### Persist room-scoped attachment paths
+```python
+# Source: adapter/matrix/files.py
+relative_path, absolute_path = build_workspace_attachment_path(
+    workspace_root=workspace_root,
+    matrix_user_id=matrix_user_id,
+    room_id=room_id,
+    filename=filename,
+)
+absolute_path.parent.mkdir(parents=True, exist_ok=True)
+absolute_path.write_bytes(body)
+```
+
+### Health-gated startup in Compose
+```yaml
+# Source: Docker Compose docs
+services:
+  matrix-bot:
+    depends_on:
+      platform-agent:
+        condition: service_healthy
+
+  platform-agent:
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| Per-user or single shared platform context | Per-room `platform_chat_id` | Repo direction corrected on 2026-04-28 | Enables true room isolation and correct `!clear` |
+| Single overloaded compose runtime | Separate prod handoff and full-stack E2E compose files | Current Phase 05 scope | Reduces operator ambiguity |
+| Unknown room auto-bootstrap as recovery | Explicit reconciliation before live traffic | Recommended for Phase 05 | Prevents duplicate chat trees after restart |
+| File payloads treated as transport concern | Shared-volume relative path contract | Already present in repo | Keeps bot/platform contract simple and durable |
+
+**Deprecated/outdated:**
+- Single-chat / DM-first deployment direction: explicitly discarded in Phase 05 reset.
+- Global reset semantics for Matrix context commands: does not match Space+rooms UX.
+- Using only local store as truth for restart recovery: unsafe once deployed rooms outlive the process.
+
+## Open Questions
+
+1. **What exact Matrix state should reconciliation trust for `chat_id` labels?**
+   - What we know: `room_meta.chat_id` is local and not derivable from Matrix protocol by default.
+   - What's unclear: whether chat labels should be reconstructed from room names, stored custom state, or cached local metadata when present.
+   - Recommendation: persist `chat_id` in local SQLite, but make reconciliation able to regenerate a stable fallback label and avoid blocking routing if the label is missing.
+
+2. **What readiness probe exists for `platform-agent` in the full-stack compose?**
+   - What we know: Compose health gating is the right pattern.
+   - What's unclear: whether upstream agent image already exposes a reliable health endpoint.
+   - Recommendation: inspect upstream container and add a bot-facing probe before finalizing `docker-compose.fullstack.yml`.
+
+3. **Should prod mount root remain `/workspace` or be renamed to `/agents` externally?**
+   - What we know: current code defaults to `SURFACES_WORKSPACE_DIR=/workspace`, while deployment docs describe shared `/agents/`.
+   - What's unclear: whether external handoff wants a host path named `/agents` while containers still use `/workspace`.
+   - Recommendation: keep one in-container canonical path and let host-side naming vary only in Compose mounts.
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Python | bot runtime | ✓ | 3.14.3 | — |
+| `uv` | dependency install | ✓ | 0.9.30 | `pip` |
+| `pytest` | validation | ✓ | 9.0.2 installed | `python -m pytest` |
+| Docker Engine | deployment packaging / E2E compose | ✓ | 29.1.3 | none |
+| Docker Compose | split runtime orchestration | ✓ | 2.40.3 | none |
+
+**Missing dependencies with no fallback:**
+- None
+
+**Missing dependencies with fallback:**
+- None
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | `pytest` + `pytest-asyncio` |
+| Config file | `pyproject.toml` |
+| Quick run command | `pytest tests/adapter/matrix/test_restart_persistence.py -v` |
+| Full suite command | `pytest tests/ -v` |
+
+### Phase Requirements → Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| PH05-01 | Space+rooms onboarding remains primary UX | integration | `pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py -v` | ✅ |
+| PH05-02 | Per-room `platform_chat_id` isolates routing and powers real clear | integration | `pytest tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_context_commands.py -v` | ✅ |
+| PH05-03 | Restart reconciliation restores routing metadata | integration | `pytest tests/adapter/matrix/test_restart_persistence.py -v` | ❌ new reconciliation tests needed |
+| PH05-04 | Shared-volume file transfer is room-safe | integration | `pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v` | ✅ partial |
+| PH05-05 | Split prod/fullstack compose artifacts stay coherent | smoke | `docker compose -f docker-compose.prod.yml config && docker compose -f docker-compose.fullstack.yml config` | ❌ Wave 0 |
+
+### Sampling Rate
+- **Per task commit:** `pytest tests/adapter/matrix/test_restart_persistence.py -v`
+- **Per wave merge:** `pytest tests/adapter/matrix/ -v`
+- **Phase gate:** `pytest tests/ -v` plus both compose files passing `docker compose ... config`
+
+### Wave 0 Gaps
+- [ ] `tests/adapter/matrix/test_reconciliation.py` — startup recovery of user/room metadata from Matrix state
+- [ ] `tests/adapter/matrix/test_context_commands.py` additions — `!clear` command contract and room-local rotation semantics
+- [ ] `tests/adapter/matrix/test_compose_artifacts.py` or equivalent smoke command documentation — split compose validation
+- [ ] `tests/adapter/matrix/test_files.py` additions — cross-room attachment path isolation and shared-root consistency
+
+## Sources
+
+### Primary (HIGH confidence)
+- Local repo code and tests:
+  - `adapter/matrix/bot.py`
+  - `adapter/matrix/store.py`
+  - `adapter/matrix/files.py`
+  - `adapter/matrix/routed_platform.py`
+  - `adapter/matrix/handlers/auth.py`
+  - `adapter/matrix/handlers/context_commands.py`
+  - `tests/adapter/matrix/test_restart_persistence.py`
+  - `tests/adapter/matrix/test_files.py`
+  - `tests/platform/test_real.py`
+- Matrix-nio API docs: https://matrix-nio.readthedocs.io/en/latest/nio.html
+- Matrix-nio async client docs: https://matrix-nio.readthedocs.io/en/latest/_modules/nio/client/async_client.html
+- Matrix-nio PyPI release page: https://pypi.org/project/matrix-nio/
+- Matrix spec Spaces / hierarchy: https://spec.matrix.org/v1.18/server-server-api/
+- Matrix spec changelog note on `via` for `m.space.child`: https://spec.matrix.org/v1.16/changelog/v1.9/
+- Docker Compose CLI reference: https://docs.docker.com/reference/cli/docker/compose/
+- Docker Compose services reference: https://docs.docker.com/reference/compose-file/services/
+
+### Secondary (MEDIUM confidence)
+- `docs/deploy-architecture.md` — repo-local deployment contract clarified on 2026-04-27
+- `docs/research/matrix-spaces.md` — prior internal research aligned with spec, but not treated as primary
+- `README.md` runtime notes for current Matrix backend and shared workspace behavior
+
+### Tertiary (LOW confidence)
+- None
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH - current repo stack verified against official docs and package registries
+- Architecture: HIGH - recommendations align with existing runtime boundaries and official Matrix / Compose behavior
+- Pitfalls: HIGH - derived from current code paths, existing tests, and official protocol/runtime semantics
+
+**Research date:** 2026-04-28
+**Valid until:** 2026-05-28

.planning/phases/05-mvp-deployment/05-VALIDATION.md

@@ -0,0 +1,83 @@
+---
+phase: 05
+slug: mvp-deployment
+status: revised
+nyquist_compliant: true
+wave_0_complete: false
+created: 2026-04-28
+---
+
+# Phase 05 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | `pytest` + `pytest-asyncio` |
+| **Config file** | `pyproject.toml` |
+| **Quick run command** | `pytest tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py -v` |
+| **Full suite command** | `pytest tests/ -v` |
+| **Estimated runtime** | targeted slices < 60 seconds each; full suite longer |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run the exact `<automated>` command from the task that just changed
+- **After every plan wave:** Run `pytest tests/adapter/matrix/ -v`
+- **Before `$gsd-verify-work`:** Full suite must be green
+- **Max feedback latency:** 60 seconds for task-level slices
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|-----------|-------------------|-------------|--------|
+| 05-01-01 | 01 | 1 | PH05-01 | integration | `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 -v` | ❌ W0 | ⬜ pending |
+| 05-01-02 | 01 | 1 | PH05-03 | integration | `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` | ❌ W0 | ⬜ pending |
+| 05-02-01 | 02 | 2 | PH05-02 | integration | `pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py -v` | ✅ partial | ⬜ pending |
+| 05-02-02 | 02 | 2 | PH05-02 | integration | `pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v` | ✅ partial | ⬜ pending |
+| 05-03-01 | 03 | 1 | PH05-04 | integration | `pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v` | ✅ partial | ⬜ pending |
+| 05-03-02 | 03 | 1 | PH05-04 | integration | `pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v` | ✅ partial | ⬜ pending |
+| 05-04-01 | 04 | 2 | PH05-05 | smoke | `docker compose -f docker-compose.prod.yml config && docker compose -f docker-compose.fullstack.yml config` | ❌ W0 | ⬜ pending |
+| 05-04-02 | 04 | 2 | PH05-05 | docs smoke | `rg -n "docker-compose\\.prod|docker-compose\\.fullstack|/agents|prod handoff|full-stack" README.md docs/deploy-architecture.md .env.example` | ✅ | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `tests/adapter/matrix/test_reconciliation.py` — startup recovery of user and room metadata from Matrix state
+- [ ] `tests/adapter/matrix/test_restart_persistence.py` additions — deterministic backfill for legacy rooms missing `platform_chat_id`
+- [ ] `tests/adapter/matrix/test_context_commands.py` additions — room-local `!clear` rotation semantics
+- [ ] `tests/adapter/matrix/test_files.py` additions — cross-room attachment isolation and shared-root consistency
+- [ ] Compose smoke coverage or documented verification command for `docker-compose.prod.yml` and `docker-compose.fullstack.yml`
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Restart after real Matrix room topology exists | PH05-03 | Full recovery depends on live Space hierarchy and persisted homeserver state | Start the bot, provision a Space and chat rooms, stop the bot, remove local SQLite metadata, restart, confirm routing and room labels are rebuilt before live messages are handled |
+| Shared `/agents` volume behavior across bot and platform containers | PH05-04 | Container mounts and permissions are environment-dependent | Run `docker compose -f docker-compose.fullstack.yml up`, upload a file in Matrix, confirm the agent sees the relative `workspace_path`, then confirm an agent-created file is readable back from the bot side |
+| Operator handoff of prod compose | PH05-05 | Final deploy contract depends on real env files and target host conventions | Run `docker compose -f docker-compose.prod.yml config` on the target deployment checkout and confirm only bot services, required env vars, and shared volumes are present |
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [x] Feedback latency target tightened to task slices under 60s
+- [x] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending

.planning/reports/20260422-session-report.md

@@ -0,0 +1,92 @@
+# GSD Session Report
+
+**Generated:** 2026-04-21T22:33:11.666Z
+**Project:** surfaces-bot
+**Milestone:** v1.0 — Production-ready surfaces
+
+---
+
+## Session Summary
+
+**Duration:** Single session  
+**Phase Progress:** Phase 04 implemented; current follow-up work is audit, stabilization, and platform bug localization  
+**Plans Executed:** 0 formal GSD plans executed in this session; work was focused on post-implementation audit and cleanup  
+**Commits Made:** 6
+
+## Work Performed
+
+### Phases Touched
+
+- **Phase 04** — Matrix MVP follow-up after implementation:
+  - completed audit of platform patches vs surface-owned responsibilities
+  - removed dependence on local platform modifications for `chat_id`
+  - switched Matrix integration to numeric `platform_chat_id` mapping on our side
+  - cleaned transport layer to a thin adapter over upstream `AgentApi`
+  - updated README and run instructions
+  - produced final Russian bug report with raw-trace-based diagnosis
+
+### Key Outcomes
+
+- Platform repos are clean and synced to pinned upstream commits.
+- Matrix real backend works with numeric surrogate `platform_chat_id`.
+- `surfaces` transport layer no longer owns custom stream semantics.
+- Final diagnosis was narrowed: missing-first-chunk bug is now considered platform-side with direct raw evidence.
+- Working state was committed and pushed on `feat/matrix-direct-agent-prototype`.
+
+### Decisions Made
+
+- Do not patch vendored platform repos for the working implementation.
+- Keep `surfaces` transport layer thin and upstream-aligned.
+- Treat the current streaming bug as platform-side unless new evidence disproves it.
+- Do not add new local stream workarounds that would blur responsibility.
+
+## Files Changed
+
+- `README.md`
+- `adapter/matrix/bot.py`
+- `sdk/agent_api_wrapper.py`
+- `sdk/real.py`
+- `tests/platform/test_real.py`
+- `tests/adapter/matrix/test_dispatcher.py`
+- `tests/core/test_integration.py`
+- `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md`
+
+Planning / handoff artifacts updated:
+
+- `.planning/HANDOFF.json`
+- `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md`
+- `.planning/reports/20260422-session-report.md`
+
+## Blockers & Open Items
+
+- Platform-side streaming bug after tool/file flow.
+- Duplicate `END` from platform.
+- Image path failure on oversized `data:` URI.
+- `tokens_used` remains unavailable from pinned upstream client.
+
+## Estimated Resource Usage
+
+| Metric | Estimate |
+|--------|----------|
+| Commits | 6 |
+| Files changed | 8 code/docs files in the main deliverable, plus planning artifacts |
+| Plans executed | 0 formal plans in this session |
+| Subagents spawned | 0 |
+
+> **Note:** Token and cost estimates require API-level instrumentation.
+> These metrics reflect observable session activity only.
+
+---
+
+### Recent Commits
+
+- `0c2884c` — `refactor: use thin upstream transport adapter`
+- `569824e` — `refactor: shrink agent api wrapper to thin adapter`
+- `4d917ac` — `docs: add thin transport adapter plan`
+- `3a3fcdc` — `docs: add thin transport adapter design`
+- `7a2ad86` — `docs: clarify matrix file sending flow`
+- `4524a6a` — `feat: finalize matrix platform audit and docs`
+
+---
+
+*Generated by `$gsd-session-report`*

.planning/threads/matrix-dev-prototype-agent-platform-state.md

@@ -0,0 +1,133 @@
+# Thread: Matrix dev prototype — состояние агента и платформы
+
+## Status: IN PROGRESS
+
+## Goal
+
+Зафиксировать текущее состояние платформы для последующей разработки Matrix dev прототипа,
+в котором команды разработки скиллов смогут быстро добавлять и обкатывать скиллы.
+
+## Context
+
+*Исследование проведено 2026-04-14. Репозитории: `external/platform-agent`, `external/platform-agent_api`, `external/platform-master`.*
+
+### Решение по деплою: локальный контейнер у каждого разработчика
+
+`platform-master` не готов для общего деплоя:
+- lifecycle management контейнеров (TTL, cleanup, переиспользование сессий) — в ветке `feat/storage`, не смержено в main
+- без него при общем деплое контейнеры висят вечно, ресурсы не освобождаются
+
+Локальный вариант: `make up-dev` — полностью рабочий, volume mount `./workspace:/workspace/`, hot reload src.
+
+### Архитектура изоляции контекстов
+
+`AgentService` — singleton с `thread_id = "default"` — это **намеренно**. Архитектура Master предполагает один контейнер `platform-agent` на один чат. Изоляция на уровне контейнеров, не thread_id. Фиксить не нужно.
+
+### Система скиллов (deepagents)
+
+`SkillsMiddleware` в `deepagents` полностью готов:
+- скилл = директория с `SKILL.md` (YAML frontmatter + markdown инструкции)
+- progressive disclosure: агент видит имя+описание в system prompt, читает полный файл по требованию
+- загружается один раз при старте сессии, кэшируется в LangGraph state
+
+**НЕ подключено** в `platform-agent/src/agent/base.py` — отсутствует одна строка:
+```python
+skills=["/workspace/skills/"]
+```
+Это задача для команды платформы.
+
+### Workflow разработчика скилла
+
+```
+workspace/
+  skills/
+    my-skill/
+      SKILL.md          ← редактируешь здесь (live через volume mount)
+      helper.py         ← вспомогательные файлы
+  config/
+    my-skill.json       ← токены и настройки (пишет агент при первом запуске)
+```
+
+1. Редактируешь `SKILL.md`
+2. `!new` в Matrix (новая сессия = скиллы перечитываются)
+3. Проверяешь поведение
+4. Повторяешь
+
+Агент может **сам установить скилл** из GitHub:
+- `execute` → git clone
+- `write_file` → положить в `/workspace/skills/`
+- после `!new` скилл активен
+
+### Конфигурация скиллов (токены, API ключи)
+
+Агент управляет конфигом сам:
+- первый запуск: спрашивает пользователя → пишет в `/workspace/config/skill-name.json`
+- последующие запуски: читает из файла
+- файл персистентен между сессиями (volume mount)
+
+### Входящий протокол (что принимает агент)
+
+`ClientMessage` — только `text: str`. Файлы и изображения не поддерживаются.
+Задача для платформы — расширить протокол.
+
+### Исходящий протокол (что шлёт агент)
+
+Новые события с `origin/main` (апрель 2026):
+- `AGENT_EVENT_TOOL_CALL_CHUNK` — агент вызывает инструмент
+- `AGENT_EVENT_TOOL_RESULT` — результат инструмента
+- `AGENT_EVENT_CUSTOM_UPDATE` — произвольный прогресс
+
+**Наш `sdk/agent_session.py` падает на этих событиях** (`raise PlatformError("Unexpected agent message")`).
+Нужно починить — это наша задача, ~10 строк.
+
+### AgentApi из lambda_agent_api
+
+Готовый production-клиент с правильным lifecycle (`connect()`, `close()`, `send_message()` как `AsyncIterator`).
+Наш `sdk/agent_session.py` дублирует его функциональность. Стоит заменить.
+
+### Инструменты агента из коробки
+
+- `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` — файловые операции в workspace
+- `execute` — shell под изолированным OS-пользователем `agent`
+- `write_todos` — список задач
+- `task` — вызов субагентов
+
+### Запуск локально
+
+```bash
+# .env минимально необходимый:
+PROVIDER_URL=https://openrouter.ai/api/v1
+PROVIDER_API_KEY=<ключ>
+PROVIDER_MODEL=anthropic/claude-sonnet-4-6
+
+# Dev контейнер:
+make up-dev   # требует AGENT_API_PATH=../platform-agent_api в env
+```
+
+Dev Dockerfile монтирует `./workspace:/workspace/` и `./src:/app/src` (hot reload).
+
+## Что нужно от платформы
+
+1. Добавить `skills=["/workspace/skills/"]` в `platform-agent/src/agent/base.py`
+2. Поддержка файлов/изображений в `ClientMessage` (не срочно для MVP)
+3. Lifecycle management контейнеров в Master (для общего деплоя, не срочно)
+
+## Что делаем мы
+
+1. Починить `sdk/agent_session.py` — обработка tool-событий вместо исключения
+2. (опционально) Заменить `AgentSessionClient` на `AgentApi` из `lambda_agent_api`
+
+## References
+
+- `external/platform-agent` — локальный клон, наш патч `1dca2c1` (thread_id) поверх `1e9fa1f`
+- `external/platform-agent_api` — локальный клон, актуальный (origin/master = `bb20a84`)
+- `external/platform-master` — локальный клон, активная разработка в `feat/storage-s02`
+- `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md`
+- `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`
+
+## Next Steps
+
+1. Запросить у команды платформы: подключение `SkillsMiddleware` в `base.py`
+2. Починить `sdk/agent_session.py` — обработать tool-события
+3. Написать первый тестовый скилл (`workspace/skills/hello/SKILL.md`) и проверить end-to-end
+4. Документировать workflow для разработчиков скиллов

.planning/threads/matrix-file-ingestion-context.md

@@ -0,0 +1,81 @@
+# Thread: Matrix file ingestion and agent-visible storage contract
+
+## Status: IN PROGRESS
+
+## Goal
+
+Сохранить текущий контекст сессии для следующего агента и зафиксировать следующую архитектурную развилку: как принимать вложения из Matrix и делать их доступными агенту.
+
+## Current State
+
+Phase 4 Matrix MVP уже собран и проверен на уровне per-room routing:
+- обычные сообщения теперь идут в `platform_chat_id`, а не в общий локальный `C1/C2`
+- `!context` показывает состояние текущего Matrix-чата
+- `!save` и `!load` привязаны к текущему room-context
+- `PrototypeStateStore` хранит live state per context
+- последние изменения закоммичены в `feat/matrix-direct-agent-prototype`
+
+Коммиты, которые важно знать:
+- `c11c8ec` `feat(task-5): scope matrix context state per room`
+- `07c5078` `feat(task-7): verify matrix per-room context routing`
+
+## What We Learned About Platform Runtime
+
+Текущий `external/platform-agent` не является отдельным контейнером на чат.
+Фактическая модель сейчас такая:
+- один FastAPI-процесс
+- singleton `AgentService`
+- `thread_id` используется как ключ памяти в LangGraph, а не как контейнерная изоляция
+- файловой изоляции на чат сейчас нет
+- `/workspace` как общий mount для Matrix bot и platform-agent сейчас не настроен
+- отдельного upload API для вложений в текущем коде не видно
+
+Ключевые файлы:
+- `external/platform-agent/src/api/external.py`
+- `external/platform-agent/src/agent/service.py`
+- `external/platform-agent/src/agent/base.py`
+
+## File Handling Requirement
+
+Пользовательский запрос на текущем этапе:
+- принимать файл или сообщение с файлом из Matrix
+- сохранять файл локально
+- передавать агенту явный сигнал, что к сообщению есть вложения
+- сообщать, где лежит файл
+
+Но есть техническое ограничение:
+- если Matrix bot пишет файл только в своём контейнере, platform-agent его не увидит
+- значит нужен либо общий storage, либо upload в платформу, либо контейнеризация platform-agent с общим volume
+
+## Recommended Design Direction
+
+Самый прагматичный MVP-вариант:
+- хранить вложения в общем каталоге, который виден и Matrix bot, и platform-agent
+- формировать для агента структурированный payload с:
+  - локальным путём
+  - original filename
+  - mime type
+  - attachment type
+- если есть текст пользователя, дополнять сообщение краткой summary-подсказкой про вложения
+- если прислан только файл, отправлять synthetic message вроде “пользователь прислал файл”
+
+Если общий каталог невозможен в текущем runtime:
+- следующий вариант это upload endpoint в platform-agent
+- Matrix surface скачивает файл и загружает его в платформу, а платформа уже кладёт его в своё доступное хранилище
+
+## Open Questions
+
+1. Где должен жить shared storage: host path, docker volume или platform-side volume?
+2. Нужен ли немедленный upload API в platform-agent, или сначала достаточно shared path?
+3. Должны ли файлы быть scoped per room/platform_chat_id, а не per user?
+
+## Next Step For Another Agent
+
+1. Подтвердить runtime-модель хранения файлов.
+2. Проверить, как сейчас запускаются Matrix bot и platform-agent в реальной dev-схеме.
+3. После выбора storage contract начать с изменений в Matrix attachment ingestion.
+
+## Notes
+
+- Контекст этой сессии сохранён как отдельный thread, потому что текущий следующий рискованный шаг уже не про context routing, а про файловый transport.
+- Не смешивать этот трек с незавершённой историей про `!branch`: upstream branch/snapshot API всё ещё не подтверждён.

Dockerfile

@@ -0,0 +1,46 @@
+FROM python:3.11-slim AS base
+
+WORKDIR /app
+RUN useradd -u 1000 -m appuser
+USER appuser
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+ENV UV_PROJECT_ENVIRONMENT=/usr/local
+
+# Install uv and git for reproducible platform SDK installation.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates git \
+    && rm -rf /var/lib/apt/lists/* \
+    && pip install --no-cache-dir uv
+
+# Copy dependency manifests first for layer caching.
+COPY pyproject.toml uv.lock* ./
+
+# Install project dependencies into the system environment.
+RUN uv sync --no-dev --no-install-project --frozen
+
+FROM base AS development
+
+COPY . .
+RUN uv sync --no-dev --frozen
+
+# Local fullstack/dev builds can override the SDK with a checked-out agent_api
+# build context, matching platform-agent's development Dockerfile pattern.
+COPY --from=agent_api . /agent_api/
+RUN python -m pip install --no-cache-dir --ignore-requires-python -e /agent_api/
+
+CMD ["python", "-m", "adapter.matrix.bot"]
+
+FROM base AS production
+
+COPY . .
+RUN uv sync --no-dev --frozen
+
+# Production builds follow the platform-agent pattern: install the API SDK from
+# the platform Git repository instead of relying on local external/ clones.
+ARG LAMBDA_AGENT_API_REF=master
+RUN python -m pip install --no-cache-dir --ignore-requires-python \
+    "git+https://git.lambda.coredump.ru/platform/agent_api.git@${LAMBDA_AGENT_API_REF}"
+
+CMD ["python", "-m", "adapter.matrix.bot"]

README.md

@@ -1,25 +1,54 @@
 # Lambda Lab 3.0 — Surfaces
 
-Команда поверхностей. Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda.
+Matrix-бот для взаимодействия пользователя с AI-агентом Lambda.
 
-## Статус
+## Интеграция для платформы
 
-Прототип в разработке. SDK платформы ещё не готов — работаем через `MockPlatformClient`.
+Бот — это один Docker-контейнер (`matrix-bot`), который вы добавляете в свою инфраструктуру рядом с агентами. Production target — один surface container на 25-30 внешних agent containers/services.
 
-| Поверхность | Статус | Описание |
-|---|---|---|
-| Telegram | 🔨 В разработке | DM + Forum Topics mode, активная реализация сейчас в отдельном worktree |
-| Matrix | 🔨 В разработке | Незашифрованные комнаты: бот создаёт private Space и отдельную room на каждый чат |
+### Что бот ожидает от вас
+
+**1. HTTP-эндпоинт агента**
+Бот подключается к агенту через `lambda_agent_api.AgentApi` по адресу `AGENT_BASE_URL`.
+Протокол — WebSocket поверх HTTP, контракт описан в `docs/deploy-architecture.md`.
+
+**2. Shared volume с per-agent поддиректориями**
+Shared volume монтируется в бот как `/agents`. Каждый агент видит свою поддиректорию.
+
+```
+Bot container                  Agent containers
+  /agents/0/  ←── volume ──→  agent_0: /workspace/
+  /agents/1/  ←── volume ──→  agent_1: /workspace/
+  /agents/N/  ←── volume ──→  agent_N: /workspace/
+```
+
+- Бот сохраняет входящий файл прямо в `{workspace_path}/{file}` и передаёт агенту `attachments=["{file}"]`
+- Если файл с таким именем уже есть, бот сохраняет следующий как `file (1).ext`, `file (2).ext`, как в Windows
+- Агент пишет исходящий файл прямо в свой `/workspace/file`, бот читает его из `{workspace_path}/file`
+- `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml`
+
+**3. Конфиг агентов**
+Файл `config/matrix-agents.yaml` — маппинг Matrix-пользователей на агентов. Вы заполняете его под свою инфраструктуру. Пример в `config/matrix-agents.example.yaml`.
+
+### Что бот не делает
+
+- Не управляет lifecycle агент-контейнеров (запуск/остановка — на вашей стороне)
+- Не хранит историю разговоров (это в памяти агента)
+- Не обрабатывает аутентификацию пользователей — любой Matrix-пользователь, который пишет боту, получает доступ
+
+### Минимальный чеклист
+
+- [ ] Взять опубликованный image `SURFACES_BOT_IMAGE` или собрать production image из этого репозитория
+- [ ] Заполнить `config/matrix-agents.yaml` — ID агентов, `base_url` каждого, `workspace_path`, маппинг пользователей
+- [ ] Задать переменные окружения (см. `.env.example`): Matrix credentials, `MATRIX_PLATFORM_BACKEND=real`, `MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml`
+- [ ] Смонтировать в бот-контейнер shared volume как `/agents` — каждый агент должен видеть свою поддиректорию как `/workspace`
+- [ ] Добавить bot-only service в свой compose; агенты в этот compose не входят и управляются платформой
 
 ---
 
-## Концепция
+## Статус
 
-Пользователь получает персонального AI-агента через привычный мессенджер.
-Агент выполняет реальные задачи: разбирает почту, ищет информацию, работает с файлами, управляет календарём.
-
-**Поверхности** — тонкие клиенты. Вся бизнес-логика на стороне платформы.
-Задача команды: сделать интерфейс удобным, надёжным и легко расширяемым.
+Matrix MVP готов к деплою. Telegram — в отдельном worktree, не входит в этот handoff.
 
 ---
 
@@ -30,121 +59,223 @@ surfaces-bot/
   core/                  — общее ядро, не зависит от транспорта
     protocol.py          — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
     handler.py           — EventDispatcher: IncomingEvent → OutgoingEvent
-    handlers/            — обработчики по типам событий
     store.py             — StateStore Protocol + InMemoryStore + SQLiteStore
-    chat.py              — ChatManager: метаданные чатов C1/C2/C3
-    auth.py              — AuthManager: аутентификация
-    settings.py          — SettingsManager: коннекторы, скиллы, SOUL, безопасность
+    chat.py              — ChatManager
+    auth.py              — AuthManager
+    settings.py          — SettingsManager
 
   adapter/
-    telegram/            — aiogram 3.x адаптер
     matrix/              — matrix-nio адаптер
 
   sdk/
     interface.py         — PlatformClient Protocol (контракт к SDK)
-    mock.py              — MockPlatformClient (заглушка)
+    real.py              — RealPlatformClient (через AgentApi)
+    mock.py              — MockPlatformClient (заглушка для тестов)
+
+  config/
+    matrix-agents.yaml   — реестр агентов
 
   docs/                  — документация
-  .claude/agents/        — агенты для Claude Code
 ```
 
-**Ключевой принцип:** добавить новую поверхность = написать один адаптер-конвертер.
-Ядро (`core/`) не трогается. Подробнее: [`docs/surface-protocol.md`](docs/surface-protocol.md)
+Подробнее: [`docs/surface-protocol.md`](docs/surface-protocol.md)
 
 ---
 
-## Функционал прототипа
+## Деплой
 
-### Telegram ([подробнее](docs/telegram-prototype.md))
-
-- **Чаты** — основной Telegram UX сейчас развивается в отдельном worktree `feat/telegram-adapter`
-- **Forum Topics mode** — бот умеет подключать forum-группу через `/forum`; чат может быть привязан к отдельной теме
-- **DM-режим** — базовый диалог и переключение чатов сохраняются
-- **Аутентификация** — привязка Telegram аккаунта к аккаунту платформы
-- **Диалог** — typing indicator, передача файлов, подтверждение опасных действий через inline-кнопки
-- **Настройки** через `/settings`: коннекторы (Gmail, GitHub, Notion...), скиллы, личность агента (SOUL), безопасность, подписка
-
-### Matrix ([подробнее](docs/matrix-prototype.md))
-
-- **Онбординг** — при первом invite бот создаёт private Space `Lambda — {display_name}` и первую комнату `Чат 1`, сразу приглашая туда пользователя
-- **Чаты** — `!new`, `!chats`, `!rename`, `!archive`, `!help`; новые комнаты регистрируются в локальном `ChatManager`
-- **Диалог** — сообщения, вложения, подтверждения `!yes` / `!no` и routing через `EventDispatcher`
-- **Стабильность** — перед `sync_forever()` бот делает bootstrap sync и стартует с `since`, чтобы не переигрывать старую timeline после рестарта
-- **Текущее ограничение** — encrypted DM пока не поддержан; ручное тестирование Matrix ведётся в незашифрованных комнатах и зависит от локального state-store бота
-
----
-
-## Замена SDK
-
-Вся работа с платформой идёт через `PlatformClient` Protocol:
-
-```python
-class PlatformClient(Protocol):
-    async def get_or_create_user(self, external_id: str, platform: str, ...) -> User: ...
-    async def send_message(self, user_id: str, chat_id: str, text: str, ...) -> MessageResponse: ...
-    async def get_settings(self, user_id: str) -> UserSettings: ...
-    async def update_settings(self, user_id: str, action: Any) -> None: ...
-```
-
-Бот не управляет lifecycle контейнеров — это делает Master (платформа).
-Бот передаёт `user_id` + `chat_id` + сообщение; платформа сама решает нужно ли поднять контейнер.
-
-Сейчас: `MockPlatformClient` в `sdk/mock.py`.
-Когда SDK готов: добавляем `SdkPlatformClient`, меняем одну строку в DI. Адаптеры и ядро не трогаем.
-
----
-
-## Быстрый старт
+### Переменные окружения
 
 ```bash
-# Зависимости
-uv sync   # или: pip install -e ".[dev]"
+cp .env.example .env
+```
 
-# Тесты
+| Переменная | Обязательна | Описание |
+|---|---|---|
+| `MATRIX_HOMESERVER` | ✓ | URL Matrix-сервера |
+| `MATRIX_USER_ID` | ✓ | `@bot:example.org` |
+| `MATRIX_PASSWORD` | ✓ | пароль (или `MATRIX_ACCESS_TOKEN`) |
+| `MATRIX_PLATFORM_BACKEND` | ✓ | `real` для продакшна |
+| `SURFACES_BOT_IMAGE` | ✓ | Docker image поверхности: `mput1/surfaces-bot:latest` |
+| `AGENT_BASE_URL` | | Fallback URL агента если `base_url` не задан в `matrix-agents.yaml` |
+| `MATRIX_AGENT_REGISTRY_PATH` | ✓ | путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml` |
+| `SURFACES_WORKSPACE_DIR` | | путь к shared volume в контейнере (по умолчанию `/agents`) |
+| `SURFACES_SHARED_VOLUME` | | имя Docker volume (по умолчанию `surfaces-agents`) |
+
+### Реестр агентов
+
+`config/matrix-agents.yaml` — статический маппинг пользователей на агентов:
+
+```yaml
+user_agents:
+  "@user0:matrix.lambda.coredump.ru": agent-0
+  "@user1:matrix.lambda.coredump.ru": agent-1
+
+agents:
+  - id: agent-0
+    label: "Agent 0"
+    base_url: "http://lambda.coredump.ru:7000/agent_0/"
+    workspace_path: "/agents/0"
+  - id: agent-1
+    label: "Agent 1"
+    base_url: "http://lambda.coredump.ru:7000/agent_1/"
+    workspace_path: "/agents/1"
+  - id: agent-2
+    label: "Agent 2"
+    base_url: "http://lambda.coredump.ru:7000/agent_2/"
+    workspace_path: "/agents/2"
+```
+
+- `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент.
+- `base_url` — HTTP URL агент-эндпоинта (path-based routing через reverse proxy).
+- `workspace_path` — путь к воркспейсу агента внутри бот-контейнера на shared volume.
+  Бот сохраняет входящие файлы прямо в `{workspace_path}/`, агент пишет исходящие прямо в свой `/workspace/`.
+- Для 25-30 агентов продолжайте тот же паттерн: `/agent_17/` + `/agents/17`, `/agent_29/` + `/agents/29`.
+
+Полный пример с комментариями: `config/matrix-agents.example.yaml`
+
+### Production (bot-only)
+
+`docker-compose.prod.yml` — bot-only handoff через published image. Платформа добавляет этот сервис в свой compose рядом с agent containers, монтирует shared volume и задаёт переменные окружения. Этот compose не создаёт и не собирает агент-контейнеры.
+
+Перед redeploy можно проверить реальные agent routes из той же сети, где будет работать бот:
+```bash
+PYTHONPATH=. uv run python -m tools.check_matrix_agents \
+  --config config/matrix-agents.yaml \
+  --timeout 5
+```
+
+Проверка открывает фактический WebSocket URL каждого агента (`.../v1/agent_ws/{chat_id}/`) и ждёт первый `STATUS`. Для проверки полного запроса к агенту добавьте `--message "ping"`.
+
+Для запуска опубликованного image:
+```bash
+export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest
+docker compose --env-file .env -f docker-compose.prod.yml up -d
+```
+
+Опубликованный image:
+
+```text
+mput1/surfaces-bot:latest
+sha256:2f135f3535f7765d4377b440cdabe41195ad2efbc3e175def159ae4689ef90bd
+```
+
+Для сборки и публикации surface image:
+```bash
+docker login
+export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest
+
+docker build --target production \
+  --build-arg LAMBDA_AGENT_API_REF=master \
+  -t "$SURFACES_BOT_IMAGE" .
+docker push "$SURFACES_BOT_IMAGE"
+```
+
+Если push возвращает `insufficient_scope`, текущий Docker login не имеет доступа к namespace/repository. Создайте repository в нужном Docker Hub namespace или перетегируйте image в namespace пользователя, под которым выполнен `docker login`.
+
+### Fullstack E2E (bot + agent)
+
+```bash
+docker compose --env-file .env -f docker-compose.fullstack.yml up --build
+```
+
+Поднимает `matrix-bot` вместе с локальным `platform-agent`. Это internal harness, не production topology на 25-30 агентов. `matrix-bot` собирается через Dockerfile target `development` и локальный `external/platform-agent_api` context, как в dev-сборке `platform-agent`. `AGENT_BASE_URL` перекрывается на `http://platform-agent:8000`. Shared volume виден как `/agents` в боте и `/workspace` в агенте.
+
+### Сброс состояния (локально)
+
+```bash
+rm -f lambda_matrix.db && rm -rf matrix_store
+```
+
+---
+
+## Shared volume: передача файлов
+
+```
+Bot (/agents)              Agent (/workspace = /agents/N/)
+  /agents/0/report.pdf  ←──── одно и то же хранилище ────→  /workspace/report.pdf
+  /agents/0/result.txt  ←────────────────────────────────→  /workspace/result.txt
+```
+
+- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/{file}`, например `/agents/17/report.pdf`, и передаёт агенту `attachments=["report.pdf"]`
+- **Коллизии имён**: если `/agents/17/report.pdf` уже существует, бот сохранит следующий файл как `/agents/17/report (1).pdf`, затем `/agents/17/report (2).pdf`
+- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/file`, бот читает из `{workspace_path}/file`, например `/agents/17/result.txt`, и отправляет пользователю как Matrix file message
+- `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml`
+
+---
+
+## Онбординг пользователя
+
+1. Пользователь приглашает бота в личные сообщения (DM) на Matrix-сервере
+2. Бот создаёт private Space `Lambda — {display_name}` и комнату `Чат 1`
+3. Дальнейшее общение — в рабочих комнатах, не в DM
+
+**Требование:** незашифрованные комнаты. E2EE не поддержан.
+
+---
+
+## Команды Matrix
+
+### Работающие
+
+| Команда | Действие |
+|---|---|
+| *(любое сообщение)* | Диалог с агентом, стриминг ответа |
+| `!new [название]` | Создать новый чат |
+| `!chats` | Список активных чатов |
+| `!rename <название>` | Переименовать текущую комнату |
+| `!archive` | Архивировать чат |
+| `!clear` | Сбросить контекст текущего чата |
+| `!yes` / `!no` | Подтвердить / отменить действие агента |
+| `!list` | Файлы в очереди вложений |
+| `!remove <n>` / `!remove all` | Удалить вложение из очереди |
+| `!help` | Справка |
+
+### Не работают / заглушки
+
+| Команда | Статус |
+|---|---|
+| `!save` / `!load` / `!context` | Нестабильны: зависят от агента, сессии теряются при рестарте |
+| `!settings` и подкоманды | Заглушки MVP, требуют готового SDK платформы |
+
+---
+
+## Отправка файлов агенту
+
+Matrix-клиент отправляет файлы и текст отдельными событиями. Файл без текстовой инструкции ставится в очередь.
+
+```
+[отправил файл]
+!list
+  1. report.pdf
+
+прочитай и сделай summary   ← файл уйдёт агенту вместе с этим текстом
+```
+
+---
+
+## Известные ограничения
+
+| Проблема | Причина |
+|---|---|
+| История теряется при рестарте агента | `platform-agent` использует `MemorySaver` (in-memory) |
+| E2EE | `python-olm` не собирается на macOS/ARM |
+
+---
+
+## Разработка
+
+```bash
+uv sync
 pytest tests/ -v
-
-# Запустить Matrix бота
-cp .env.example .env  # заполнить MATRIX_* переменные
-PYTHONPATH=. uv run python -m adapter.matrix.bot
+pytest tests/adapter/matrix/ -v   # только Matrix
 ```
 
-### Telegram worktree
-
-Текущая Telegram-разработка идёт в отдельном worktree:
-
-```bash
-cd .worktrees/telegram
-export BOT_TOKEN=...
-PYTHONPATH=. python -m adapter.telegram.bot
-```
-
-### Matrix manual QA
-
-Пока Matrix-бот тестируется в незашифрованных комнатах:
-
-```bash
-cd /path/to/surfaces-bot
-rm -f lambda_matrix.db
-rm -rf matrix_store
-PYTHONPATH=. uv run python -m adapter.matrix.bot
-```
-
----
-
 ## Документация
 
 | Файл | Содержание |
 |---|---|
-| [`docs/surface-protocol.md`](docs/surface-protocol.md) | Унификация поверхностей — все структуры, как добавить новую поверхность |
-| [`docs/telegram-prototype.md`](docs/telegram-prototype.md) | Функционал Telegram прототипа |
-| [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Функционал Matrix прототипа |
-| [`docs/api-contract.md`](docs/api-contract.md) | Контракт к SDK платформы |
-| [`docs/user-flow.md`](docs/user-flow.md) | FSM и user journey |
-| [`docs/claude-code-guide.md`](docs/claude-code-guide.md) | Гайд по работе с Claude Code |
-
----
-
-## Команда
-
-Поверхности и интеграции
-Lambda Lab 3.0, МАИ
+| [`docs/deploy-architecture.md`](docs/deploy-architecture.md) | **Читать первым.** Топология деплоя, volume-контракт, AgentApi, конфигурация |
+| [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Команды бота, UX, передача файлов |
+| [`docs/known-limitations.md`](docs/known-limitations.md) | Известные ограничения и обходные пути |
+| [`docs/surface-protocol.md`](docs/surface-protocol.md) | Внутренний протокол событий (для расширения) |

adapter/matrix/agent_registry.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+
+class AgentRegistryError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class AgentDefinition:
+    agent_id: str
+    label: str
+    base_url: str = field(default="")
+    workspace_path: str = field(default="")
+
+
+@dataclass(frozen=True)
+class AgentAssignment:
+    agent_id: str | None
+    source: Literal["configured", "default", "none"]
+
+    @property
+    def is_default(self) -> bool:
+        return self.source == "default"
+
+
+class AgentRegistry:
+    def __init__(
+        self,
+        agents: list[AgentDefinition],
+        user_agents: Mapping[str, str] | None = None,
+    ) -> None:
+        self.agents = tuple(agents)
+        self._by_id = {agent.agent_id: agent for agent in self.agents}
+        self._user_agents: dict[str, str] = dict(user_agents or {})
+
+    def get(self, agent_id: str) -> AgentDefinition:
+        try:
+            return self._by_id[agent_id]
+        except KeyError as exc:
+            raise AgentRegistryError(f"unknown agent id: {agent_id}") from exc
+
+    def get_agent_id_for_user(self, matrix_user_id: str) -> str | None:
+        return self._user_agents.get(matrix_user_id)
+
+    def resolve_agent_for_user(self, matrix_user_id: str) -> AgentAssignment:
+        agent_id = self.get_agent_id_for_user(matrix_user_id)
+        if agent_id is not None:
+            return AgentAssignment(agent_id=agent_id, source="configured")
+        if self.agents:
+            return AgentAssignment(agent_id=self.agents[0].agent_id, source="default")
+        return AgentAssignment(agent_id=None, source="none")
+
+
+def _required_text(entry: Mapping[str, object], key: str) -> str:
+    value = entry.get(key)
+    if not isinstance(value, str):
+        raise AgentRegistryError("each agent entry requires id and label")
+    text = value.strip()
+    if not text:
+        raise AgentRegistryError("each agent entry requires id and label")
+    return text
+
+
+def _optional_text(entry: Mapping[str, object], key: str) -> str:
+    value = entry.get(key)
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise AgentRegistryError(f"agent entry field '{key}' must be a string")
+    return value.strip()
+
+
+def _load_registry_data(path: str | Path) -> dict[str, object]:
+    try:
+        raw = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise AgentRegistryError("invalid agent registry YAML") from exc
+    if raw is None:
+        return {}
+    if not isinstance(raw, Mapping):
+        raise AgentRegistryError("agent registry must be a mapping with an agents list")
+    return dict(raw)
+
+
+def load_agent_registry(path: str | Path) -> AgentRegistry:
+    raw = _load_registry_data(path)
+    entries = raw.get("agents")
+    if not isinstance(entries, list) or not entries:
+        raise AgentRegistryError("agents registry must contain a non-empty agents list")
+
+    agents: list[AgentDefinition] = []
+    seen: set[str] = set()
+    for entry in entries:
+        if not isinstance(entry, Mapping):
+            raise AgentRegistryError("each agent entry requires id and label")
+        agent_id = _required_text(entry, "id")
+        label = _required_text(entry, "label")
+        base_url = _optional_text(entry, "base_url")
+        workspace_path = _optional_text(entry, "workspace_path")
+        if agent_id in seen:
+            raise AgentRegistryError(f"duplicate agent id: {agent_id}")
+        seen.add(agent_id)
+        agents.append(
+            AgentDefinition(
+                agent_id=agent_id,
+                label=label,
+                base_url=base_url,
+                workspace_path=workspace_path,
+            )
+        )
+
+    user_agents = raw.get("user_agents")
+    if user_agents is not None:
+        if not isinstance(user_agents, Mapping):
+            raise AgentRegistryError("user_agents must be a mapping of user_id to agent_id")
+        user_agents = {str(k): str(v) for k, v in user_agents.items()}
+
+    return AgentRegistry(agents, user_agents)

adapter/matrix/bot.py

@@ -1,32 +1,71 @@
 from __future__ import annotations
 
 import asyncio
+import logging
 import os
+import re
 from dataclasses import dataclass
 from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
 
 import structlog
+from dotenv import load_dotenv
 from nio import (
     AsyncClient,
     AsyncClientConfig,
     InviteMemberEvent,
     MatrixRoom,
     RoomMemberEvent,
+    RoomMessage,
+    RoomMessageAudio,
+    RoomMessageFile,
+    RoomMessageImage,
     RoomMessageText,
+    RoomMessageVideo,
 )
 from nio.responses import SyncResponse
-from dotenv import load_dotenv
 
+from adapter.matrix.agent_registry import AgentRegistry, AgentRegistryError, load_agent_registry
 from adapter.matrix.converter import from_room_event
+from adapter.matrix.files import (
+    download_matrix_attachment,
+    matrix_msgtype_for_attachment,
+    resolve_workspace_attachment_path,
+)
 from adapter.matrix.handlers import register_matrix_handlers
-from adapter.matrix.handlers.auth import handle_invite
+from adapter.matrix.handlers.auth import (
+    default_agent_notice,
+    handle_invite,
+    provision_workspace_chat,
+    restore_workspace_access,
+)
+from adapter.matrix.handlers.context_commands import (
+    LOAD_PROMPT,
+)
+from adapter.matrix.reconciliation import reconcile_startup_state
 from adapter.matrix.room_router import resolve_chat_id
-from adapter.matrix.store import get_room_meta, set_pending_confirm
+from adapter.matrix.routed_platform import RoutedPlatformClient
+from adapter.matrix.store import (
+    add_staged_attachment,
+    clear_load_pending,
+    clear_staged_attachments,
+    get_load_pending,
+    get_room_meta,
+    get_staged_attachments,
+    next_platform_chat_id,
+    remove_staged_attachment_at,
+    set_pending_confirm,
+    set_platform_chat_id,
+    set_room_meta,
+)
 from core.auth import AuthManager
 from core.chat import ChatManager
 from core.handler import EventDispatcher
 from core.handlers import register_all
 from core.protocol import (
+    Attachment,
+    IncomingCommand,
+    IncomingMessage,
     OutgoingEvent,
     OutgoingMessage,
     OutgoingNotification,
@@ -35,7 +74,10 @@ from core.protocol import (
 )
 from core.settings import SettingsManager
 from core.store import InMemoryStore, SQLiteStore, StateStore
+from sdk.interface import PlatformClient, PlatformError
 from sdk.mock import MockPlatformClient
+from sdk.prototype_state import PrototypeStateStore
+from sdk.real import RealPlatformClient
 
 logger = structlog.get_logger(__name__)
 
@@ -44,41 +86,161 @@ load_dotenv(Path(__file__).resolve().parents[2] / ".env")
 
 @dataclass
 class MatrixRuntime:
-    platform: MockPlatformClient
+    platform: PlatformClient
     store: StateStore
     chat_mgr: ChatManager
     auth_mgr: AuthManager
     settings_mgr: SettingsManager
     dispatcher: EventDispatcher
+    agent_routing_enabled: bool = False
+    registry: AgentRegistry | None = None
 
 
-def build_event_dispatcher(platform: MockPlatformClient, store: StateStore) -> EventDispatcher:
+def build_event_dispatcher(platform: PlatformClient, store: StateStore) -> EventDispatcher:
     chat_mgr = ChatManager(platform, store)
     auth_mgr = AuthManager(platform, store)
     settings_mgr = SettingsManager(platform, store)
+    prototype_state = getattr(platform, "_prototype_state", None)
+    agent_base_url = _agent_base_url_from_env()
+    registry = _load_agent_registry_from_env()
     dispatcher = EventDispatcher(
         platform=platform, chat_mgr=chat_mgr, auth_mgr=auth_mgr, settings_mgr=settings_mgr
     )
     register_all(dispatcher)
-    register_matrix_handlers(dispatcher, store=store)
+    register_matrix_handlers(
+        dispatcher,
+        store=store,
+        registry=registry,
+        prototype_state=prototype_state,
+        agent_base_url=agent_base_url,
+    )
     return dispatcher
 
 
+def _normalize_agent_base_url(url: str) -> str:
+    parsed = urlsplit(url)
+    path = re.sub(r"(?:/v1)?/agent_ws(?:/[^/]+)?/?$", "", parsed.path.rstrip("/"))
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+def _ws_debug_enabled() -> bool:
+    value = os.environ.get("SURFACES_DEBUG_WS", "")
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _configure_debug_logging() -> None:
+    if not _ws_debug_enabled():
+        return
+    root_logger = logging.getLogger()
+    if not root_logger.handlers:
+        logging.basicConfig(
+            level=logging.INFO,
+            format="%(asctime)s [%(levelname)-8s] %(name)s %(message)s",
+        )
+    elif root_logger.level > logging.INFO:
+        root_logger.setLevel(logging.INFO)
+    logging.getLogger("lambda_agent_api").setLevel(logging.INFO)
+    logging.getLogger("lambda_agent_api.agent_api").setLevel(logging.INFO)
+
+
+def _agent_base_url_from_env() -> str:
+    if base_url := os.environ.get("AGENT_BASE_URL"):
+        return base_url
+    if ws_url := os.environ.get("AGENT_WS_URL"):
+        return _normalize_agent_base_url(ws_url)
+    return "http://127.0.0.1:8000"
+
+
+def _load_agent_registry_from_env(required: bool = False) -> AgentRegistry | None:
+    registry_path = os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip()
+    if not registry_path:
+        if required:
+            raise RuntimeError(
+                "MATRIX_AGENT_REGISTRY_PATH is required when MATRIX_PLATFORM_BACKEND=real"
+            )
+        return None
+    try:
+        registry = load_agent_registry(registry_path)
+    except (AgentRegistryError, OSError) as exc:
+        raise RuntimeError(f"failed to load matrix agent registry: {registry_path}") from exc
+    if _ws_debug_enabled():
+        logger.warning(
+            "matrix_agent_registry_loaded",
+            registry_path=registry_path,
+            agent_count=len(registry.agents),
+        )
+        for agent in registry.agents:
+            logger.warning(
+                "matrix_agent_registry_entry",
+                registry_path=registry_path,
+                agent_id=agent.agent_id,
+                label=agent.label,
+                configured_base_url=agent.base_url,
+                normalized_base_url=_normalize_agent_base_url(agent.base_url)
+                if agent.base_url
+                else "",
+                workspace_path=agent.workspace_path,
+            )
+    return registry
+
+
+def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> PlatformClient:
+    backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower()
+    if _ws_debug_enabled():
+        logger.warning(
+            "matrix_platform_backend_selected",
+            backend=backend,
+            global_agent_base_url=_agent_base_url_from_env(),
+            registry_path=os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip(),
+        )
+    if backend == "real":
+        prototype_state = PrototypeStateStore()
+        registry = _load_agent_registry_from_env(required=True)
+        assert registry is not None
+        global_base_url = _agent_base_url_from_env()
+        delegates = {
+            agent.agent_id: RealPlatformClient(
+                agent_id=agent.agent_id,
+                agent_base_url=agent.base_url or global_base_url,
+                prototype_state=prototype_state,
+                platform="matrix",
+            )
+            for agent in registry.agents
+        }
+        return RoutedPlatformClient(
+            chat_mgr=chat_mgr,
+            store=store,
+            delegates=delegates,
+        )
+    return MockPlatformClient()
+
+
 def build_runtime(
-    platform: MockPlatformClient | None = None,
+    platform: PlatformClient | None = None,
     store: StateStore | None = None,
     client: AsyncClient | None = None,
 ) -> MatrixRuntime:
-    platform = platform or MockPlatformClient()
     store = store or InMemoryStore()
     chat_mgr = ChatManager(platform, store)
+    platform = platform or _build_platform_from_env(store=store, chat_mgr=chat_mgr)
+    chat_mgr = ChatManager(platform, store)
     auth_mgr = AuthManager(platform, store)
     settings_mgr = SettingsManager(platform, store)
+    prototype_state = getattr(platform, "_prototype_state", None)
+    agent_base_url = _agent_base_url_from_env()
+    registry = _load_agent_registry_from_env()
     dispatcher = EventDispatcher(
         platform=platform, chat_mgr=chat_mgr, auth_mgr=auth_mgr, settings_mgr=settings_mgr
     )
     register_all(dispatcher)
-    register_matrix_handlers(dispatcher, client=client, store=store)
+    register_matrix_handlers(
+        dispatcher,
+        client=client,
+        store=store,
+        registry=registry,
+        prototype_state=prototype_state,
+        agent_base_url=agent_base_url,
+    )
     return MatrixRuntime(
         platform=platform,
         store=store,
@@ -86,6 +248,8 @@ def build_runtime(
         auth_mgr=auth_mgr,
         settings_mgr=settings_mgr,
         dispatcher=dispatcher,
+        agent_routing_enabled=isinstance(platform, RoutedPlatformClient),
+        registry=registry,
     )
 
 
@@ -94,15 +258,524 @@ class MatrixBot:
         self.client = client
         self.runtime = runtime
 
+    async def _ensure_platform_chat_id(self, room_id: str, room_meta: dict | None) -> None:
+        if not room_meta:
+            return
+        if room_meta.get("redirect_room_id"):
+            return
+        if room_meta.get("platform_chat_id"):
+            return
+        await set_platform_chat_id(
+            self.runtime.store,
+            room_id,
+            await next_platform_chat_id(self.runtime.store),
+        )
+
+    async def _refresh_room_agent_assignment(
+        self, room_id: str, matrix_user_id: str, room_meta: dict | None
+    ) -> tuple[dict | None, bool]:
+        if not room_meta or room_meta.get("redirect_room_id") or self.runtime.registry is None:
+            return room_meta, False
+
+        assignment = self.runtime.registry.resolve_agent_for_user(matrix_user_id)
+        updated = dict(room_meta)
+        should_warn_default = False
+
+        if assignment.source == "configured" and (
+            updated.get("agent_id") != assignment.agent_id
+            or updated.get("agent_assignment") != "configured"
+        ):
+            updated["agent_id"] = assignment.agent_id
+            updated["agent_assignment"] = "configured"
+            updated.pop("default_agent_notice_sent", None)
+        elif assignment.source == "default":
+            if not updated.get("agent_id"):
+                updated["agent_id"] = assignment.agent_id
+            if updated.get("agent_id") == assignment.agent_id:
+                updated["agent_assignment"] = "default"
+                should_warn_default = not updated.get("default_agent_notice_sent")
+                updated["default_agent_notice_sent"] = True
+
+        if updated != room_meta:
+            await set_room_meta(self.runtime.store, room_id, updated)
+            return updated, should_warn_default
+        return room_meta, should_warn_default
+
     async def on_room_message(self, room: MatrixRoom, event: RoomMessageText) -> None:
         if getattr(event, "sender", None) == self.client.user_id:
             return
-        chat_id = await resolve_chat_id(self.runtime.store, room.room_id, event.sender)
-        incoming = from_room_event(event, room_id=room.room_id, chat_id=chat_id)
+        sender = getattr(event, "sender", None)
+        body = (getattr(event, "body", None) or "").strip()
+        room_meta = await get_room_meta(self.runtime.store, room.room_id)
+        if room_meta is not None and not room_meta.get("redirect_room_id"):
+            await self._ensure_platform_chat_id(room.room_id, room_meta)
+            room_meta, warn_default_agent = await self._refresh_room_agent_assignment(
+                room.room_id, sender, room_meta
+            )
+            if warn_default_agent and not body.startswith("!"):
+                await self._send_all(
+                    room.room_id,
+                    [OutgoingMessage(chat_id=room.room_id, text=default_agent_notice())],
+                )
+
+        load_pending = await get_load_pending(self.runtime.store, sender, room.room_id)
+        if load_pending is not None and (body.isdigit() or body == "!cancel"):
+            outgoing = await self._handle_load_selection(sender, room.room_id, body, load_pending)
+            await self._send_all(room.room_id, outgoing)
+            return
+
+        if room_meta is None:
+            outgoing = await self._bootstrap_unregistered_room(room, sender)
+            if outgoing:
+                await self._send_all(room.room_id, outgoing)
+                return
+        elif room_meta.get("redirect_room_id"):
+            display_name = getattr(room, "display_name", None) or sender
+            if body == "!new":
+                try:
+                    created = await provision_workspace_chat(
+                        self.client,
+                        sender,
+                        display_name,
+                        self.runtime.platform,
+                        self.runtime.store,
+                        self.runtime.auth_mgr,
+                        self.runtime.chat_mgr,
+                        registry=self.runtime.registry,
+                    )
+                except Exception as exc:
+                    logger.warning(
+                        "matrix_entry_room_new_chat_failed",
+                        room_id=room.room_id,
+                        sender=sender,
+                        error=str(exc),
+                    )
+                    await self._send_all(
+                        room.room_id,
+                        [
+                            OutgoingMessage(
+                                chat_id=room.room_id,
+                                text="Не удалось создать новый рабочий чат.",
+                            )
+                        ],
+                    )
+                    return
+
+                welcome = f"Создал новый рабочий чат {created['room_name']}."
+                if created.get("agent_assignment") == "default":
+                    welcome = f"{welcome}\n\n{default_agent_notice()}"
+                await self.client.room_send(
+                    created["chat_room_id"],
+                    "m.room.message",
+                    {"msgtype": "m.text", "body": welcome},
+                )
+                await set_room_meta(
+                    self.runtime.store,
+                    room.room_id,
+                    {
+                        **room_meta,
+                        "redirect_room_id": created["chat_room_id"],
+                        "redirect_chat_id": created["chat_id"],
+                    },
+                )
+                await self._send_all(
+                    room.room_id,
+                    [
+                        OutgoingMessage(
+                            chat_id=room.room_id,
+                            text=(
+                                f"Создал рабочий чат {created['room_name']} "
+                                f"({created['chat_id']}) и отправил приглашение."
+                            ),
+                        )
+                    ],
+                )
+                return
+
+            restored = await restore_workspace_access(
+                self.client,
+                sender,
+                display_name,
+                self.runtime.platform,
+                self.runtime.store,
+                self.runtime.auth_mgr,
+                self.runtime.chat_mgr,
+                registry=self.runtime.registry,
+            )
+            redirect_room_id = room_meta["redirect_room_id"]
+            redirect_chat_id = room_meta.get("redirect_chat_id", "рабочий чат")
+            if restored.get("created_new_chat"):
+                text = (
+                    f"Создал новый рабочий чат {restored['room_name']} "
+                    f"({restored['chat_id']}) и отправил приглашение."
+                )
+            else:
+                text = (
+                    f"Рабочий чат уже создан: {redirect_chat_id}. "
+                    "Я повторно отправил приглашения в пространство Lambda и рабочие чаты. "
+                    "Чтобы создать новый чат, напишите !new здесь."
+                )
+            await self._send_all(
+                room.room_id,
+                [
+                    OutgoingMessage(
+                        chat_id=room.room_id,
+                        text=text,
+                    )
+                ],
+            )
+            logger.info(
+                "matrix_redirect_entry_room",
+                room_id=room.room_id,
+                redirect_room_id=redirect_room_id,
+                user=sender,
+            )
+            return
+        if not body.startswith("!") and self.runtime.agent_routing_enabled:
+            pass
+
+        local_chat_id = await resolve_chat_id(self.runtime.store, room.room_id, sender)
+        incoming = from_room_event(event, room_id=room.room_id, chat_id=local_chat_id)
         if incoming is None:
             return
-        outgoing = await self.runtime.dispatcher.dispatch(incoming)
-        await self._send_all(room.room_id, outgoing)
+        if isinstance(incoming, IncomingCommand) and incoming.command in {
+            "matrix_list_attachments",
+            "matrix_remove_attachment",
+        }:
+            outgoing = await self._handle_staged_attachment_command(
+                room.room_id,
+                sender,
+                incoming,
+            )
+            await self._send_all(room.room_id, outgoing)
+            return
+        if self._is_file_only_event(event, incoming):
+            materialized = await self._materialize_incoming_attachments(
+                room.room_id,
+                sender,
+                incoming,
+            )
+            await self._stage_attachments(room.room_id, sender, materialized.attachments)
+            return
+        if isinstance(incoming, IncomingMessage) and incoming.attachments:
+            incoming = await self._materialize_incoming_attachments(
+                room.room_id,
+                sender,
+                incoming,
+            )
+        clear_staged_after_dispatch = False
+        if isinstance(incoming, IncomingMessage) and incoming.text:
+            incoming, clear_staged_after_dispatch = await self._merge_staged_attachments(
+                room.room_id,
+                sender,
+                incoming,
+            )
+        agent_id = (room_meta or {}).get("agent_id")
+        if _ws_debug_enabled() and not body.startswith("!"):
+            logger.warning(
+                "matrix_incoming_message_route",
+                room_id=room.room_id,
+                sender=sender,
+                local_chat_id=local_chat_id,
+                agent_id=agent_id,
+                platform_chat_id=(room_meta or {}).get("platform_chat_id"),
+            )
+        workspace_root = self._agent_workspace_root(agent_id)
+        try:
+            outgoing = await self.runtime.dispatcher.dispatch(incoming)
+        except PlatformError as exc:
+            logger.warning(
+                "matrix_message_platform_error",
+                room_id=room.room_id,
+                sender=getattr(event, "sender", None),
+                code=exc.code,
+                error=str(exc),
+            )
+            outgoing = [
+                OutgoingMessage(
+                    chat_id=local_chat_id,
+                    text="Сервис временно недоступен. Попробуйте ещё раз позже.",
+                )
+            ]
+        else:
+            if clear_staged_after_dispatch:
+                await clear_staged_attachments(self.runtime.store, room.room_id, sender)
+        await self._send_all(room.room_id, outgoing, workspace_root=workspace_root)
+
+    def _is_file_only_event(
+        self, event: RoomMessage, incoming: IncomingMessage | IncomingCommand
+    ) -> bool:
+        return (
+            isinstance(incoming, IncomingMessage)
+            and bool(incoming.attachments)
+            and not isinstance(event, RoomMessageText)
+        )
+
+    async def _stage_attachments(
+        self,
+        room_id: str,
+        user_id: str,
+        attachments: list,
+    ) -> None:
+        for attachment in attachments:
+            await add_staged_attachment(
+                self.runtime.store,
+                room_id,
+                user_id,
+                {
+                    "type": attachment.type,
+                    "url": attachment.url,
+                    "filename": attachment.filename,
+                    "mime_type": attachment.mime_type,
+                    "workspace_path": attachment.workspace_path,
+                },
+            )
+
+    async def _format_staged_attachments(
+        self,
+        room_id: str,
+        user_id: str,
+        *,
+        include_hint: bool = False,
+    ) -> str:
+        attachments = await get_staged_attachments(self.runtime.store, room_id, user_id)
+        if not attachments:
+            return "Нет сохраненных вложений."
+
+        lines = ["Вложения в очереди:"]
+        for index, attachment in enumerate(attachments, start=1):
+            lines.append(f"{index}. {attachment.get('filename') or 'attachment'}")
+        if include_hint:
+            lines.extend(
+                [
+                    "",
+                    "Следующее сообщение отправит файлы агенту.",
+                    "Команды: !list, !remove <n>, !remove all",
+                ]
+            )
+        return "\n".join(lines)
+
+    async def _handle_staged_attachment_command(
+        self,
+        room_id: str,
+        user_id: str,
+        incoming: IncomingCommand,
+    ) -> list[OutgoingEvent]:
+        if incoming.command == "matrix_list_attachments":
+            return [
+                OutgoingMessage(
+                    chat_id=incoming.chat_id,
+                    text=await self._format_staged_attachments(room_id, user_id),
+                )
+            ]
+
+        arg = incoming.args[0] if incoming.args else ""
+        if arg == "all":
+            await clear_staged_attachments(self.runtime.store, room_id, user_id)
+            return [OutgoingMessage(chat_id=incoming.chat_id, text="Все вложения удалены.")]
+
+        try:
+            index = int(arg) - 1
+        except ValueError:
+            return [OutgoingMessage(chat_id=incoming.chat_id, text="Нет такого вложения.")]
+
+        removed = await remove_staged_attachment_at(self.runtime.store, room_id, user_id, index)
+        if removed is None:
+            return [OutgoingMessage(chat_id=incoming.chat_id, text="Нет такого вложения.")]
+        return [
+            OutgoingMessage(
+                chat_id=incoming.chat_id,
+                text=await self._format_staged_attachments(room_id, user_id),
+            )
+        ]
+
+    async def _merge_staged_attachments(
+        self,
+        room_id: str,
+        user_id: str,
+        incoming: IncomingMessage,
+    ) -> tuple[IncomingMessage, bool]:
+        staged = await get_staged_attachments(self.runtime.store, room_id, user_id)
+        if not staged:
+            return incoming, False
+        attachments = [
+            Attachment(
+                type=item.get("type", "document"),
+                url=item.get("url"),
+                filename=item.get("filename"),
+                mime_type=item.get("mime_type"),
+                workspace_path=item.get("workspace_path"),
+            )
+            for item in staged
+        ]
+        return (
+            IncomingMessage(
+                user_id=incoming.user_id,
+                platform=incoming.platform,
+                chat_id=incoming.chat_id,
+                text=incoming.text,
+                attachments=attachments,
+                reply_to=incoming.reply_to,
+            ),
+            True,
+        )
+
+    def _agent_workspace_root(self, agent_id: str | None) -> Path:
+        default = Path(os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace"))
+        if agent_id is None or self.runtime.registry is None:
+            return default
+        try:
+            agent = self.runtime.registry.get(agent_id)
+            if agent.workspace_path:
+                return Path(agent.workspace_path)
+        except Exception:
+            pass
+        return default
+
+    async def _materialize_incoming_attachments(
+        self,
+        room_id: str,
+        matrix_user_id: str,
+        incoming: IncomingMessage,
+    ) -> IncomingMessage:
+        room_meta = await get_room_meta(self.runtime.store, room_id)
+        agent_id = (room_meta or {}).get("agent_id")
+        workspace_root = self._agent_workspace_root(agent_id)
+        materialized = []
+        for attachment in incoming.attachments:
+            materialized.append(
+                await download_matrix_attachment(
+                    client=self.client,
+                    workspace_root=workspace_root,
+                    matrix_user_id=matrix_user_id,
+                    room_id=room_id,
+                    attachment=attachment,
+                )
+            )
+        return IncomingMessage(
+            user_id=incoming.user_id,
+            platform=incoming.platform,
+            chat_id=incoming.chat_id,
+            text=incoming.text,
+            attachments=materialized,
+            reply_to=incoming.reply_to,
+        )
+
+    async def _bootstrap_unregistered_room(
+        self,
+        room: MatrixRoom,
+        sender: str,
+    ) -> list[OutgoingEvent] | None:
+        if not hasattr(self.client, "room_create") or not hasattr(self.client, "room_put_state"):
+            return None
+        display_name = getattr(room, "display_name", None) or sender
+        try:
+            created = await provision_workspace_chat(
+                self.client,
+                sender,
+                display_name,
+                self.runtime.platform,
+                self.runtime.store,
+                self.runtime.auth_mgr,
+                self.runtime.chat_mgr,
+                registry=self.runtime.registry,
+            )
+        except Exception as exc:
+            logger.warning(
+                "matrix_unregistered_room_bootstrap_failed",
+                room_id=room.room_id,
+                sender=sender,
+                error=str(exc),
+            )
+            return [
+                OutgoingMessage(
+                    chat_id=room.room_id,
+                    text="Не удалось подготовить рабочий чат. Попробуйте ещё раз позже.",
+                )
+            ]
+
+        welcome = (
+            f"Привет, {created['user'].display_name or sender}! Пиши — я здесь.\n\n"
+            "Команды: !new · !chats · !rename · !archive · !context · !save · !load · !help"
+        )
+        if created.get("agent_assignment") == "default":
+            welcome = f"{welcome}\n\n{default_agent_notice()}"
+        await set_room_meta(
+            self.runtime.store,
+            room.room_id,
+            {
+                "matrix_user_id": sender,
+                "redirect_room_id": created["chat_room_id"],
+                "redirect_chat_id": created["chat_id"],
+            },
+        )
+        await self.client.room_send(
+            created["chat_room_id"],
+            "m.room.message",
+            {"msgtype": "m.text", "body": welcome},
+        )
+        return [
+            OutgoingMessage(
+                chat_id=room.room_id,
+                text=(
+                    f"Создал рабочий чат {created['room_name']} ({created['chat_id']}) "
+                    "и добавил его в пространство Lambda. "
+                    "Открой приглашённую комнату для продолжения."
+                ),
+            )
+        ]
+
+    async def _handle_load_selection(
+        self,
+        user_id: str,
+        room_id: str,
+        text: str,
+        pending: dict,
+    ) -> list[OutgoingEvent]:
+        saves = pending.get("saves", [])
+        if text in {"0", "!cancel"}:
+            await clear_load_pending(self.runtime.store, user_id, room_id)
+            return [OutgoingMessage(chat_id=room_id, text="Отменено.")]
+
+        index = int(text) - 1
+        if index < 0 or index >= len(saves):
+            return [
+                OutgoingMessage(
+                    chat_id=room_id,
+                    text=f"Неверный номер. Введи от 1 до {len(saves)} или 0 для отмены.",
+                )
+            ]
+
+        name = saves[index]["name"]
+        await clear_load_pending(self.runtime.store, user_id, room_id)
+        prototype_state = getattr(self.runtime.platform, "_prototype_state", None)
+        if prototype_state is not None:
+            room_meta = await get_room_meta(self.runtime.store, room_id)
+            context_keys = []
+            if room_meta is not None:
+                platform_chat_id = room_meta.get("platform_chat_id")
+                if platform_chat_id:
+                    context_keys.append(platform_chat_id)
+                chat_id = room_meta.get("chat_id")
+                if chat_id:
+                    context_keys.append(chat_id)
+            if not context_keys:
+                context_keys.append(room_id)
+            for context_key in dict.fromkeys(context_keys):
+                await prototype_state.set_current_session(context_key, name)
+
+        try:
+            await self.runtime.platform.send_message(
+                user_id,
+                room_id,
+                LOAD_PROMPT.format(name=name),
+            )
+        except Exception as exc:
+            logger.warning("load_agent_call_failed", error=str(exc))
+            return [OutgoingMessage(chat_id=room_id, text=f"Ошибка при загрузке: {exc}")]
+        return [
+            OutgoingMessage(chat_id=room_id, text=f"Запрос на загрузку отправлен агенту: {name}")
+        ]
 
     async def on_member(self, room: MatrixRoom, event: RoomMemberEvent) -> None:
         if getattr(event, "sender", None) == self.client.user_id:
@@ -117,11 +790,23 @@ class MatrixBot:
                 self.runtime.store,
                 self.runtime.auth_mgr,
                 self.runtime.chat_mgr,
+                self.runtime.registry,
             )
 
-    async def _send_all(self, room_id: str, outgoing: list[OutgoingEvent]) -> None:
+    async def _send_all(
+        self,
+        room_id: str,
+        outgoing: list[OutgoingEvent],
+        workspace_root: Path | None = None,
+    ) -> None:
         for event in outgoing:
-            await send_outgoing(self.client, room_id, event, store=self.runtime.store)
+            await send_outgoing(
+                self.client,
+                room_id,
+                event,
+                store=self.runtime.store,
+                workspace_root=workspace_root,
+            )
 
 
 async def prepare_live_sync(client: AsyncClient) -> str | None:
@@ -130,11 +815,13 @@ async def prepare_live_sync(client: AsyncClient) -> str | None:
         return response.next_batch
     return None
 
+
 async def send_outgoing(
     client: AsyncClient,
     room_id: str,
     event: OutgoingEvent,
     store: StateStore | None = None,
+    workspace_root: Path | None = None,
 ) -> None:
     if isinstance(event, OutgoingTyping):
         await client.room_typing(room_id, event.is_typing, timeout=25000)
@@ -144,7 +831,39 @@ async def send_outgoing(
         await client.room_send(room_id, "m.room.message", {"msgtype": "m.text", "body": body})
         return
     if isinstance(event, OutgoingMessage):
-        await client.room_send(room_id, "m.room.message", {"msgtype": "m.text", "body": event.text})
+        if event.text:
+            await client.room_send(
+                room_id, "m.room.message", {"msgtype": "m.text", "body": event.text}
+            )
+        if event.attachments:
+            workspace_root = workspace_root or Path(
+                os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace")
+            )
+            for attachment in event.attachments:
+                if not attachment.workspace_path:
+                    continue
+                file_path = resolve_workspace_attachment_path(
+                    workspace_root, attachment.workspace_path
+                )
+                with file_path.open("rb") as handle:
+                    upload_response, _ = await client.upload(
+                        handle,
+                        content_type=attachment.mime_type or "application/octet-stream",
+                        filename=attachment.filename or file_path.name,
+                        filesize=file_path.stat().st_size,
+                    )
+                content_uri = getattr(upload_response, "content_uri", None)
+                if not content_uri:
+                    raise RuntimeError(f"Matrix upload failed for {file_path}")
+                await client.room_send(
+                    room_id,
+                    "m.room.message",
+                    {
+                        "msgtype": matrix_msgtype_for_attachment(attachment),
+                        "body": attachment.filename or file_path.name,
+                        "url": content_uri,
+                    },
+                )
         return
     if isinstance(event, OutgoingUI):
         lines = [event.text]
@@ -176,6 +895,7 @@ async def send_outgoing(
 
 
 async def main() -> None:
+    _configure_debug_logging()
     homeserver = os.environ.get("MATRIX_HOMESERVER")
     user_id = os.environ.get("MATRIX_USER_ID")
     device_id = os.environ.get("MATRIX_DEVICE_ID", "")
@@ -207,9 +927,19 @@ async def main() -> None:
         await client.login(password=password, device_name="surfaces-bot")
 
     since_token = await prepare_live_sync(client)
+    await reconcile_startup_state(client, runtime)
 
     bot = MatrixBot(client, runtime)
-    client.add_event_callback(bot.on_room_message, RoomMessageText)
+    client.add_event_callback(
+        bot.on_room_message,
+        (
+            RoomMessageText,
+            RoomMessageFile,
+            RoomMessageImage,
+            RoomMessageVideo,
+            RoomMessageAudio,
+        ),
+    )
     client.add_event_callback(bot.on_member, (InviteMemberEvent, RoomMemberEvent))
 
     logger.info(
@@ -219,9 +949,21 @@ async def main() -> None:
         store_path=store_path,
         request_timeout=client_config.request_timeout,
     )
+    if _ws_debug_enabled():
+        logger.warning(
+            "matrix_ws_debug_enabled",
+            homeserver=homeserver,
+            user_id=user_id,
+            backend=os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower(),
+            global_agent_base_url=_agent_base_url_from_env(),
+            registry_path=os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip(),
+        )
     try:
         await client.sync_forever(timeout=30000, since=since_token)
     finally:
+        close = getattr(runtime.platform, "close", None)
+        if callable(close):
+            await close()
         await client.close()
 
 

adapter/matrix/converter.py

@@ -14,42 +14,53 @@ PLATFORM = "matrix"
 
 
 def extract_attachments(event: Any) -> list[Attachment]:
+    source = getattr(event, "source", {}) or {}
+    content = source.get("content", {}) or getattr(event, "content", {}) or {}
     msgtype = getattr(event, "msgtype", None)
     if msgtype is None:
-        content = getattr(event, "content", {}) or {}
         msgtype = content.get("msgtype")
+    url = content.get("url") or getattr(event, "url", None)
+    filename = content.get("body") or getattr(event, "body", None)
+    mime_type = content.get("mimetype") or getattr(event, "mimetype", None)
+    if mime_type is None:
+        info = content.get("info") or {}
+        if isinstance(info, dict):
+            mime_type = info.get("mimetype")
 
     if msgtype == "m.image":
         return [
             Attachment(
                 type="image",
-                url=getattr(event, "url", None),
-                mime_type=getattr(event, "mimetype", None),
+                url=url,
+                filename=filename,
+                mime_type=mime_type,
             )
         ]
     if msgtype == "m.file":
         return [
             Attachment(
                 type="document",
-                url=getattr(event, "url", None),
-                filename=getattr(event, "body", None),
-                mime_type=getattr(event, "mimetype", None),
+                url=url,
+                filename=filename,
+                mime_type=mime_type,
             )
         ]
     if msgtype == "m.audio":
         return [
             Attachment(
                 type="audio",
-                url=getattr(event, "url", None),
-                mime_type=getattr(event, "mimetype", None),
+                url=url,
+                filename=filename,
+                mime_type=mime_type,
             )
         ]
     if msgtype == "m.video":
         return [
             Attachment(
                 type="video",
-                url=getattr(event, "url", None),
-                mime_type=getattr(event, "mimetype", None),
+                url=url,
+                filename=filename,
+                mime_type=mime_type,
             )
         ]
     return []
@@ -75,6 +86,24 @@ def from_command(body: str, sender: str, chat_id: str, room_id: str | None = Non
             },
         )
 
+    if command == "list" and not args:
+        return IncomingCommand(
+            user_id=sender,
+            platform=PLATFORM,
+            chat_id=chat_id,
+            command="matrix_list_attachments",
+            args=[],
+        )
+
+    if command == "remove" and len(args) == 1:
+        return IncomingCommand(
+            user_id=sender,
+            platform=PLATFORM,
+            chat_id=chat_id,
+            command="matrix_remove_attachment",
+            args=[args[0]],
+        )
+
     aliases = {
         "skills": "settings_skills",
         "connectors": "settings_connectors",

adapter/matrix/files.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import mimetypes
+import re
+from pathlib import Path, PurePosixPath
+
+from core.protocol import Attachment
+
+
+def _sanitize_filename(value: str) -> str:
+    filename = PurePosixPath(str(value).replace("\\", "/")).name.strip()
+    cleaned = re.sub(r"[\x00-\x1f\x7f<>:\"/\\|?*]+", "_", filename)
+    cleaned = cleaned.strip(" .")
+    return cleaned or "attachment.bin"
+
+
+def _default_filename(attachment: Attachment) -> str:
+    if attachment.filename:
+        return attachment.filename
+
+    extension = mimetypes.guess_extension(attachment.mime_type or "") or ""
+    base = {
+        "image": "image",
+        "audio": "audio",
+        "video": "video",
+        "document": "attachment",
+    }.get(attachment.type, "attachment")
+    return f"{base}{extension}"
+
+
+def _with_copy_index(filename: str, index: int) -> str:
+    path = Path(filename)
+    suffix = path.suffix
+    stem = path.stem if suffix else filename
+    return f"{stem} ({index}){suffix}"
+
+
+def _unique_workspace_relative_path(workspace_root: Path, filename: str) -> tuple[str, Path]:
+    safe_name = _sanitize_filename(filename)
+    candidate = workspace_root / safe_name
+    if not candidate.exists():
+        return safe_name, candidate
+
+    index = 1
+    while True:
+        indexed_name = _with_copy_index(safe_name, index)
+        candidate = workspace_root / indexed_name
+        if not candidate.exists():
+            return indexed_name, candidate
+        index += 1
+
+
+def build_agent_workspace_path(
+    *,
+    workspace_root: Path,
+    filename: str,
+) -> tuple[str, Path]:
+    """Saves user files directly to {workspace_root}/{filename}.
+
+    The returned relative path is what gets passed to agent.send_message(attachments=[...]).
+    """
+    return _unique_workspace_relative_path(workspace_root, filename)
+
+
+async def download_matrix_attachment(
+    *,
+    client,
+    workspace_root: Path,
+    matrix_user_id: str,
+    room_id: str,
+    attachment: Attachment,
+    timestamp: str | None = None,
+) -> Attachment:
+    if not attachment.url:
+        return attachment
+
+    filename = _default_filename(attachment)
+
+    del matrix_user_id, room_id, timestamp
+    relative_path, absolute_path = build_agent_workspace_path(
+        workspace_root=workspace_root,
+        filename=filename,
+    )
+
+    absolute_path.parent.mkdir(parents=True, exist_ok=True)
+
+    response = await client.download(attachment.url)
+    body = getattr(response, "body", None)
+    if body is None:
+        raise RuntimeError(f"Matrix download response for {attachment.url} has no body")
+    absolute_path.write_bytes(body)
+
+    return Attachment(
+        type=attachment.type,
+        url=attachment.url,
+        filename=filename,
+        mime_type=attachment.mime_type,
+        workspace_path=relative_path,
+    )
+
+
+def resolve_workspace_attachment_path(workspace_root: Path, workspace_path: str) -> Path:
+    path = Path(workspace_path)
+    if path.is_absolute():
+        return path
+    return workspace_root / path
+
+
+def matrix_msgtype_for_attachment(attachment: Attachment) -> str:
+    return {
+        "image": "m.image",
+        "audio": "m.audio",
+        "video": "m.video",
+    }.get(attachment.type, "m.file")

adapter/matrix/handlers/__init__.py

@@ -7,6 +7,12 @@ from adapter.matrix.handlers.chat import (
     make_handle_rename,
 )
 from adapter.matrix.handlers.confirm import make_handle_cancel, make_handle_confirm
+from adapter.matrix.handlers.context_commands import (
+    make_handle_context,
+    make_handle_load,
+    make_handle_reset,
+    make_handle_save,
+)
 from adapter.matrix.handlers.settings import (
     handle_help,
     handle_settings,
@@ -18,18 +24,32 @@ from adapter.matrix.handlers.settings import (
     handle_settings_status,
     handle_settings_whoami,
     handle_toggle_skill,
+    handle_unknown_command,
 )
 from core.handler import EventDispatcher
 from core.protocol import IncomingCallback, IncomingCommand
 
 
-def register_matrix_handlers(dispatcher: EventDispatcher, client=None, store=None) -> None:
-    dispatcher.register(IncomingCommand, "new", make_handle_new_chat(client, store))
+def register_matrix_handlers(
+    dispatcher: EventDispatcher,
+    client=None,
+    store=None,
+    registry=None,
+    prototype_state=None,
+    agent_base_url: str = "http://127.0.0.1:8000",
+) -> None:
+    dispatcher.register(IncomingCommand, "new", make_handle_new_chat(client, store, registry))
     dispatcher.register(IncomingCommand, "chats", handle_list_chats)
     dispatcher.register(IncomingCommand, "rename", make_handle_rename(client, store))
     dispatcher.register(IncomingCommand, "archive", make_handle_archive(client, store))
     dispatcher.register(IncomingCommand, "help", handle_help)
     dispatcher.register(IncomingCommand, "settings", handle_settings)
+    if prototype_state is not None:
+        clear_handler = make_handle_reset(store, prototype_state)
+        dispatcher.register(IncomingCommand, "clear", clear_handler)
+        dispatcher.register(IncomingCommand, "reset", clear_handler)
+    else:
+        dispatcher.register(IncomingCommand, "reset", handle_settings)
     dispatcher.register(IncomingCommand, "settings_skills", handle_settings_skills)
     dispatcher.register(IncomingCommand, "settings_connectors", handle_settings_connectors)
     dispatcher.register(IncomingCommand, "settings_soul", handle_settings_soul)
@@ -41,3 +61,13 @@ def register_matrix_handlers(dispatcher: EventDispatcher, client=None, store=Non
     dispatcher.register(IncomingCallback, "confirm", make_handle_confirm(store))
     dispatcher.register(IncomingCallback, "cancel", make_handle_cancel(store))
     dispatcher.register(IncomingCallback, "toggle_skill", handle_toggle_skill)
+    dispatcher.register(IncomingCommand, "*", handle_unknown_command)
+
+    if prototype_state is not None:
+        dispatcher.register(
+            IncomingCommand,
+            "save",
+            make_handle_save(None, store, prototype_state),
+        )
+        dispatcher.register(IncomingCommand, "load", make_handle_load(store, prototype_state))
+        dispatcher.register(IncomingCommand, "context", make_handle_context(store, prototype_state))

adapter/matrix/handlers/auth.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
 
-import structlog
 from typing import Any
 
+import structlog
 from nio.api import RoomVisibility
 from nio.responses import RoomCreateError
 
+from adapter.matrix.agent_registry import AgentRegistry
 from adapter.matrix.store import (
     get_user_meta,
-    next_chat_id,
+    next_platform_chat_id,
     set_room_meta,
     set_user_meta,
 )
@@ -16,16 +17,47 @@ from adapter.matrix.store import (
 logger = structlog.get_logger(__name__)
 
 
-async def handle_invite(client: Any, room: Any, event: Any, platform, store, auth_mgr, chat_mgr) -> None:
-    matrix_user_id = getattr(event, "sender", "")
-    display_name = getattr(room, "display_name", None) or matrix_user_id
+def _default_room_name(chat_id: str) -> str:
+    suffix = chat_id[1:] if chat_id.startswith("C") else chat_id
+    return f"Чат {suffix}"
 
-    existing = await get_user_meta(store, matrix_user_id)
-    if existing and existing.get("space_id"):
-        return
 
-    await client.join(room.room_id)
+def default_agent_notice() -> str:
+    return (
+        "Внимание: ваш Matrix ID не найден в конфиге агентов. "
+        "Пока используется агент по умолчанию. После добавления вас в конфиг "
+        "бот переключит существующие комнаты на назначенного агента."
+    )
 
+
+async def _invite_if_possible(client: Any, room_id: str, matrix_user_id: str) -> bool:
+    room_invite = getattr(client, "room_invite", None)
+    if not callable(room_invite):
+        return False
+    try:
+        await room_invite(room_id, matrix_user_id)
+        return True
+    except Exception as exc:
+        logger.warning(
+            "matrix_workspace_reinvite_failed",
+            room_id=room_id,
+            user=matrix_user_id,
+            error=str(exc),
+        )
+        return False
+
+
+async def provision_workspace_chat(
+    client: Any,
+    matrix_user_id: str,
+    display_name: str,
+    platform,
+    store,
+    auth_mgr,
+    chat_mgr,
+    room_name_override: str | None = None,
+    registry: AgentRegistry | None = None,
+) -> dict:
     user = await platform.get_or_create_user(
         external_id=matrix_user_id,
         platform="matrix",
@@ -34,24 +66,41 @@ async def handle_invite(client: Any, room: Any, event: Any, platform, store, aut
     await auth_mgr.confirm(matrix_user_id)
 
     homeserver = matrix_user_id.split(":")[-1]
+    user_meta = await get_user_meta(store, matrix_user_id) or {}
+    space_id = user_meta.get("space_id")
 
-    space_resp = await client.room_create(
-        name=f"Lambda — {display_name}",
-        space=True,
-        visibility=RoomVisibility.private,
-        invite=[matrix_user_id],
-    )
-    if isinstance(space_resp, RoomCreateError):
-        logger.error(
-            "space creation failed",
-            user=matrix_user_id,
-            error=getattr(space_resp, "status_code", None),
+    if not space_id:
+        space_resp = await client.room_create(
+            name=f"Lambda — {display_name}",
+            space=True,
+            visibility=RoomVisibility.private,
+            invite=[matrix_user_id],
         )
-        return
-    space_id = space_resp.room_id
+        if isinstance(space_resp, RoomCreateError):
+            logger.error(
+                "space creation failed",
+                user=matrix_user_id,
+                error=getattr(space_resp, "status_code", None),
+            )
+            raise RuntimeError("Не удалось создать Space.")
+        space_id = space_resp.room_id
+        user_meta["space_id"] = space_id
+        await set_user_meta(store, matrix_user_id, user_meta)
+
+    next_chat_index = int(user_meta.get("next_chat_index", 1))
+    chat_id = f"C{next_chat_index}"
+    platform_chat_id = await next_platform_chat_id(store)
+    room_name = room_name_override or _default_room_name(chat_id)
+
+    agent_id = None
+    agent_assignment = "none"
+    if registry is not None:
+        assignment = registry.resolve_agent_for_user(matrix_user_id)
+        agent_id = assignment.agent_id
+        agent_assignment = assignment.source
 
     chat_resp = await client.room_create(
-        name="Чат 1",
+        name=room_name,
         visibility=RoomVisibility.private,
         is_direct=False,
         invite=[matrix_user_id],
@@ -62,7 +111,7 @@ async def handle_invite(client: Any, room: Any, event: Any, platform, store, aut
             user=matrix_user_id,
             error=getattr(chat_resp, "status_code", None),
         )
-        return
+        raise RuntimeError("Не удалось создать рабочий чат.")
     chat_room_id = chat_resp.room_id
 
     await client.room_put_state(
@@ -72,10 +121,8 @@ async def handle_invite(client: Any, room: Any, event: Any, platform, store, aut
         state_key=chat_room_id,
     )
 
-    chat_id = await next_chat_id(store, matrix_user_id)
-
-    user_meta = await get_user_meta(store, matrix_user_id) or {}
     user_meta["space_id"] = space_id
+    user_meta["next_chat_index"] = next_chat_index + 1
     await set_user_meta(store, matrix_user_id, user_meta)
 
     await set_room_meta(
@@ -84,9 +131,12 @@ async def handle_invite(client: Any, room: Any, event: Any, platform, store, aut
         {
             "room_type": "chat",
             "chat_id": chat_id,
-            "display_name": "Чат 1",
+            "display_name": room_name,
             "matrix_user_id": matrix_user_id,
             "space_id": space_id,
+            "platform_chat_id": platform_chat_id,
+            "agent_id": agent_id,
+            "agent_assignment": agent_assignment,
         },
     )
     await chat_mgr.get_or_create(
@@ -94,15 +144,142 @@ async def handle_invite(client: Any, room: Any, event: Any, platform, store, aut
         chat_id=chat_id,
         platform="matrix",
         surface_ref=chat_room_id,
-        name="Чат 1",
+        name=room_name,
     )
 
+    return {
+        "user": user,
+        "space_id": space_id,
+        "chat_room_id": chat_room_id,
+        "chat_id": chat_id,
+        "room_name": room_name,
+        "agent_assignment": agent_assignment,
+        "agent_id": agent_id,
+    }
+
+
+async def restore_workspace_access(
+    client: Any,
+    matrix_user_id: str,
+    display_name: str,
+    platform,
+    store,
+    auth_mgr,
+    chat_mgr,
+    registry: AgentRegistry | None = None,
+) -> dict:
+    user_meta = await get_user_meta(store, matrix_user_id) or {}
+    space_id = user_meta.get("space_id")
+    if not space_id:
+        created = await provision_workspace_chat(
+            client,
+            matrix_user_id,
+            display_name,
+            platform,
+            store,
+            auth_mgr,
+            chat_mgr,
+            room_name_override="Чат 1",
+            registry=registry,
+        )
+        return {**created, "reinvited_rooms": [], "created_new_chat": True}
+
+    await auth_mgr.confirm(matrix_user_id)
+    await _invite_if_possible(client, space_id, matrix_user_id)
+
+    chats = await chat_mgr.list_active(matrix_user_id)
+    if not chats:
+        created = await provision_workspace_chat(
+            client,
+            matrix_user_id,
+            display_name,
+            platform,
+            store,
+            auth_mgr,
+            chat_mgr,
+            registry=registry,
+        )
+        return {**created, "reinvited_rooms": [], "created_new_chat": True}
+
+    reinvited_rooms = []
+    for chat in chats:
+        if chat.surface_ref:
+            if await _invite_if_possible(client, chat.surface_ref, matrix_user_id):
+                reinvited_rooms.append(chat.surface_ref)
+
+    return {
+        "space_id": space_id,
+        "reinvited_rooms": reinvited_rooms,
+        "created_new_chat": False,
+    }
+
+
+async def handle_invite(
+    client: Any,
+    room: Any,
+    event: Any,
+    platform,
+    store,
+    auth_mgr,
+    chat_mgr,
+    registry: AgentRegistry | None = None,
+) -> None:
+    matrix_user_id = getattr(event, "sender", "")
+    display_name = getattr(room, "display_name", None) or matrix_user_id
+
+    await client.join(room.room_id)
+
+    existing = await get_user_meta(store, matrix_user_id)
+    if existing and existing.get("space_id"):
+        restored = await restore_workspace_access(
+            client,
+            matrix_user_id,
+            display_name,
+            platform,
+            store,
+            auth_mgr,
+            chat_mgr,
+            registry=registry,
+        )
+        body = "Я отправил повторные приглашения в пространство Lambda и рабочие чаты."
+        if restored.get("created_new_chat"):
+            body = (
+                f"Создал новый рабочий чат {restored['room_name']} "
+                f"({restored['chat_id']}) и отправил приглашение."
+            )
+            if restored.get("agent_assignment") == "default":
+                body = f"{body}\n\n{default_agent_notice()}"
+        await client.room_send(
+            room.room_id,
+            "m.room.message",
+            {"msgtype": "m.text", "body": body},
+        )
+        return
+
+    try:
+        created = await provision_workspace_chat(
+            client,
+            matrix_user_id,
+            display_name,
+            platform,
+            store,
+            auth_mgr,
+            chat_mgr,
+            room_name_override="Чат 1",
+            registry=registry,
+        )
+    except RuntimeError as exc:
+        logger.error("invite_workspace_provision_failed", user=matrix_user_id, error=str(exc))
+        return
+
     welcome = (
-        f"Привет, {user.display_name or matrix_user_id}! Пиши — я здесь.\n\n"
-        "Команды: !new · !chats · !rename · !archive · !skills · !soul · !safety · !settings"
+        f"Привет, {created['user'].display_name or matrix_user_id}! Пиши — я здесь.\n\n"
+        "Команды: !new · !chats · !rename · !archive · !clear · !help"
     )
+    if created.get("agent_assignment") == "default":
+        welcome = f"{welcome}\n\n{default_agent_notice()}"
     await client.room_send(
-        chat_room_id,
+        created["chat_room_id"],
         "m.room.message",
         {"msgtype": "m.text", "body": welcome},
     )

adapter/matrix/handlers/chat.py

@@ -1,12 +1,20 @@
 from __future__ import annotations
 
-from typing import Any, Awaitable, Callable
+from collections.abc import Awaitable, Callable
+from typing import Any
 
 import structlog
 from nio.api import RoomVisibility
 from nio.responses import RoomCreateError
 
-from adapter.matrix.store import get_user_meta, next_chat_id, set_room_meta
+from adapter.matrix.agent_registry import AgentRegistry
+from adapter.matrix.handlers.auth import default_agent_notice
+from adapter.matrix.store import (
+    get_user_meta,
+    next_chat_id,
+    next_platform_chat_id,
+    set_room_meta,
+)
 from core.protocol import IncomingCommand, OutgoingMessage
 
 logger = structlog.get_logger(__name__)
@@ -42,6 +50,7 @@ async def _fallback_new_chat(
 def make_handle_new_chat(
     client: Any | None,
     store: Any | None,
+    registry: AgentRegistry | None = None,
 ) -> Callable[..., Awaitable[list]]:
     async def handle_new_chat(
         event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
@@ -69,6 +78,7 @@ def make_handle_new_chat(
 
         name = " ".join(event.args).strip() if event.args else ""
         chat_id = await next_chat_id(store, event.user_id)
+        platform_chat_id = await next_platform_chat_id(store)
         room_name = name or f"Чат {chat_id}"
 
         response = await client.room_create(
@@ -97,17 +107,24 @@ def make_handle_new_chat(
             state_key=room_id,
         )
 
-        await set_room_meta(
-            store,
-            room_id,
-            {
-                "room_type": "chat",
-                "chat_id": chat_id,
-                "display_name": room_name,
-                "matrix_user_id": event.user_id,
-                "space_id": space_id,
-            },
-        )
+        agent_id = None
+        agent_assignment = "none"
+        if registry is not None:
+            assignment = registry.resolve_agent_for_user(event.user_id)
+            agent_id = assignment.agent_id
+            agent_assignment = assignment.source
+
+        room_meta: dict = {
+            "room_type": "chat",
+            "chat_id": chat_id,
+            "display_name": room_name,
+            "matrix_user_id": event.user_id,
+            "space_id": space_id,
+            "platform_chat_id": platform_chat_id,
+            "agent_id": agent_id,
+            "agent_assignment": agent_assignment,
+        }
+        await set_room_meta(store, room_id, room_meta)
         ctx = await chat_mgr.get_or_create(
             user_id=event.user_id,
             chat_id=chat_id,
@@ -115,10 +132,13 @@ def make_handle_new_chat(
             surface_ref=room_id,
             name=room_name,
         )
+        text = f"Создан чат: {ctx.display_name} ({ctx.chat_id})"
+        if agent_assignment == "default":
+            text = f"{text}\n\n{default_agent_notice()}"
         return [
             OutgoingMessage(
                 chat_id=event.chat_id,
-                text=f"Создан чат: {ctx.display_name} ({ctx.chat_id})",
+                text=text,
             )
         ]
 
@@ -150,7 +170,10 @@ def make_handle_rename(
             return [
                 OutgoingMessage(
                     chat_id=event.chat_id,
-                    text="Этот чат не найден в локальном состоянии бота. Открой зарегистрированную комнату или создай новый чат через !new.",
+                    text=(
+                        "Этот чат не найден в локальном состоянии бота. "
+                        "Открой зарегистрированную комнату или создай новый чат через !new."
+                    ),
                 )
             ]
 
@@ -180,7 +203,10 @@ def make_handle_archive(
             return [
                 OutgoingMessage(
                     chat_id=event.chat_id,
-                    text="Этот чат не найден в локальном состоянии бота. Создай новый чат через !new.",
+                    text=(
+                        "Этот чат не найден в локальном состоянии бота. "
+                        "Создай новый чат через !new."
+                    ),
                 )
             ]
         ctx = await chat_mgr.get(event.chat_id, user_id=event.user_id)

adapter/matrix/handlers/context_commands.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+import httpx
+import structlog
+
+from adapter.matrix.store import (
+    get_room_meta,
+    next_platform_chat_id,
+    set_load_pending,
+    set_platform_chat_id,
+)
+from core.protocol import IncomingCommand, OutgoingEvent, OutgoingMessage
+
+if TYPE_CHECKING:
+    from core.store import StateStore
+    from sdk.prototype_state import PrototypeStateStore
+
+logger = structlog.get_logger(__name__)
+
+SAVE_PROMPT = (
+    "Summarize our conversation and save to /workspace/contexts/{name}.md. "
+    "Reply only with: Saved: {name}"
+)
+LOAD_PROMPT = (
+    "Load context from /workspace/contexts/{name}.md and use it as background "
+    "for our conversation. Reply: Loaded: {name}"
+)
+_VALID_NAME = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _sanitize_session_name(raw_name: str) -> str | None:
+    name = raw_name.strip()
+    if not name or not _VALID_NAME.fullmatch(name):
+        return None
+    return name
+
+
+async def _resolve_room_id(event: IncomingCommand, chat_mgr) -> str:
+    if chat_mgr is None:
+        return event.chat_id
+    ctx = await chat_mgr.get(event.chat_id, user_id=event.user_id)
+    if ctx is not None and ctx.surface_ref:
+        return ctx.surface_ref
+    return event.chat_id
+
+
+async def _resolve_context_scope(
+    event: IncomingCommand,
+    store: StateStore,
+    chat_mgr,
+) -> tuple[str, str | None]:
+    room_id = await _resolve_room_id(event, chat_mgr)
+    room_meta = await get_room_meta(store, room_id)
+    platform_chat_id = room_meta.get("platform_chat_id") if room_meta else None
+    return room_id, platform_chat_id
+
+
+async def _require_platform_context(
+    event: IncomingCommand,
+    store: StateStore,
+    chat_mgr,
+) -> tuple[str, str]:
+    room_id, platform_chat_id = await _resolve_context_scope(event, store, chat_mgr)
+    if not platform_chat_id:
+        raise RuntimeError(f"matrix room context is incomplete: {room_id}")
+    return room_id, platform_chat_id
+
+
+def make_handle_save(agent_api, store: StateStore, prototype_state: PrototypeStateStore):
+    async def handle_save(
+        event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+    ) -> list[OutgoingEvent]:
+        if event.args:
+            name = _sanitize_session_name(event.args[0])
+            if name is None:
+                return [
+                    OutgoingMessage(
+                        chat_id=event.chat_id,
+                        text="Имя сохранения может содержать только буквы, цифры, _ и -.",
+                    )
+                ]
+        else:
+            name = f"context-{datetime.now(UTC).strftime('%Y%m%d-%H%M%S')}"
+
+        try:
+            await platform.send_message(
+                event.user_id,
+                event.chat_id,
+                SAVE_PROMPT.format(name=name),
+            )
+        except Exception as exc:
+            logger.warning("save_agent_call_failed", error=str(exc))
+            return [OutgoingMessage(chat_id=event.chat_id, text=f"Ошибка при сохранении: {exc}")]
+
+        try:
+            _, platform_chat_id = await _require_platform_context(event, store, chat_mgr)
+        except RuntimeError as exc:
+            logger.warning("save_context_incomplete", error=str(exc))
+            return [OutgoingMessage(chat_id=event.chat_id, text="Контекст комнаты не готов. Попробуй позже.")]
+
+        await prototype_state.add_saved_session(
+            event.user_id,
+            name,
+            source_context_id=platform_chat_id,
+        )
+        return [
+            OutgoingMessage(
+                chat_id=event.chat_id,
+                text=f"Запрос на сохранение отправлен агенту: {name}",
+            )
+        ]
+
+    return handle_save
+
+
+def make_handle_load(store: StateStore, prototype_state: PrototypeStateStore):
+    async def handle_load(
+        event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+    ) -> list[OutgoingEvent]:
+        sessions = await prototype_state.list_saved_sessions(event.user_id)
+        if not sessions:
+            return [
+                OutgoingMessage(
+                    chat_id=event.chat_id,
+                    text="Нет сохранённых сессий. Используй !save [имя].",
+                )
+            ]
+
+        room_id, _ = await _resolve_context_scope(event, store, chat_mgr)
+        lines = ["Сохранённые сессии:"]
+        for index, session in enumerate(sessions, start=1):
+            created = session.get("created_at", "")[:10]
+            lines.append(f"  {index}. {session['name']} ({created})")
+        lines.append("")
+        lines.append("Введи номер или 0 / !cancel для отмены.")
+
+        await set_load_pending(store, event.user_id, room_id, {"saves": sessions})
+        return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))]
+
+    return handle_load
+
+
+def make_handle_reset(store: StateStore, prototype_state: PrototypeStateStore):
+    async def handle_reset(
+        event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+    ) -> list[OutgoingEvent]:
+        try:
+            room_id, old_chat_id = await _require_platform_context(event, store, chat_mgr)
+        except RuntimeError as exc:
+            logger.warning("clear_context_incomplete", error=str(exc))
+            return [OutgoingMessage(chat_id=event.chat_id, text="Контекст комнаты не готов. Попробуй позже.")]
+
+        new_chat_id = await next_platform_chat_id(store)
+        await set_platform_chat_id(store, room_id, new_chat_id)
+
+        disconnect = getattr(platform, "disconnect_chat", None)
+        if callable(disconnect):
+            await disconnect(old_chat_id)
+
+        await prototype_state.clear_current_session(old_chat_id)
+        await prototype_state.clear_current_session(new_chat_id)
+
+        return [
+            OutgoingMessage(
+                chat_id=event.chat_id,
+                text="Контекст сброшен. Агент не помнит предыдущий разговор.",
+            )
+        ]
+
+    return handle_reset
+
+
+async def _call_reset_endpoint(agent_base_url: str, chat_id: str) -> list[OutgoingEvent]:
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.post(f"{agent_base_url}/reset", timeout=5.0)
+    except (httpx.ConnectError, httpx.TimeoutException) as exc:
+        logger.warning("reset_endpoint_unreachable", error=str(exc))
+        return [
+            OutgoingMessage(
+                chat_id=chat_id,
+                text="Reset endpoint недоступен. Обратитесь к администратору.",
+            )
+        ]
+
+    if response.status_code == 404:
+        return [
+            OutgoingMessage(
+                chat_id=chat_id,
+                text="Reset endpoint недоступен. Обратитесь к администратору.",
+            )
+        ]
+    return [OutgoingMessage(chat_id=chat_id, text="Контекст сброшен.")]
+
+
+def make_handle_context(store: StateStore, prototype_state: PrototypeStateStore):
+    async def handle_context(
+        event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+    ) -> list[OutgoingEvent]:
+        try:
+            _, platform_chat_id = await _require_platform_context(event, store, chat_mgr)
+        except RuntimeError as exc:
+            logger.warning("context_scope_incomplete", error=str(exc))
+            return [OutgoingMessage(chat_id=event.chat_id, text="Контекст комнаты не готов. Попробуй позже.")]
+
+        current_session = await prototype_state.get_current_session(platform_chat_id)
+        tokens_used = await prototype_state.get_last_tokens_used(platform_chat_id)
+        sessions = await prototype_state.list_saved_sessions(event.user_id)
+
+        lines = [
+            "Контекст:",
+            f"  Контекст чата: {platform_chat_id}",
+            f"  Сессия: {current_session or 'не загружена'}",
+            f"  Токены (последний ответ): {tokens_used}",
+            f"  Сохранения ({len(sessions)}):",
+        ]
+        if sessions:
+            for session in sessions:
+                created = session.get("created_at", "")[:10]
+                lines.append(f"    - {session['name']} ({created})")
+        else:
+            lines.append("    (нет)")
+
+        return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))]
+
+    return handle_context

adapter/matrix/handlers/settings.py

@@ -1,8 +1,6 @@
 from __future__ import annotations
 
-from adapter.matrix.reactions import build_skills_text
-from core.protocol import IncomingCommand, OutgoingMessage, SettingsAction
-
+from core.protocol import IncomingCommand, OutgoingMessage
 
 HELP_TEXT = "\n".join(
     [
@@ -12,186 +10,87 @@ HELP_TEXT = "\n".join(
         "!chats  список активных чатов",
         "!rename <название>  переименовать текущий чат",
         "!archive  архивировать текущий чат",
-        "!settings  общий обзор настроек",
-        "!skills  список навыков",
-        "!soul [поле значение]  показать или изменить личность",
-        "!safety [триггер on/off]  показать или изменить безопасность",
-        "!status  краткий статус",
-        "!whoami  показать ваш id",
+        "",
+        "!clear  сбросить контекст текущего чата",
+        "",
+        "!list  показать файлы в очереди",
+        "!remove <n>  удалить файл из очереди",
+        "!remove all  очистить очередь файлов",
+        "",
         "!yes / !no  подтвердить или отменить действие",
+        "!help  эта справка",
     ]
 )
 
 
-def _render_mapping(title: str, data: dict | None) -> str:
-    data = data or {}
-    lines = [title]
-    if not data:
-        lines.append("Нет данных.")
-    else:
-        for key, value in data.items():
-            lines.append(f"• {key}: {value}")
-    return "\n".join(lines)
-
-
-def _parse_bool(value: str) -> bool:
-    return value.lower() in {"1", "true", "yes", "on", "enable", "enabled"}
+MVP_UNAVAILABLE_TEXT = (
+    "Эта команда скрыта в MVP и сейчас недоступна. "
+    "Используй !help для списка поддерживаемых команд."
+)
 
 
 async def handle_settings(
     event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
 ) -> list:
-    settings = await settings_mgr.get(event.user_id)
-    chats = await chat_mgr.list_active(event.user_id)
-
-    skills_lines = []
-    for name, enabled in settings.skills.items():
-        state = "on" if enabled else "off"
-        skills_lines.append(f"  {state}  {name}")
-    skills_text = "\n".join(skills_lines) if skills_lines else "  нет навыков"
-
-    soul_lines = []
-    for key, value in (settings.soul or {}).items():
-        soul_lines.append(f"  {key}: {value}")
-    soul_text = "\n".join(soul_lines) if soul_lines else "  по умолчанию"
-
-    safety_lines = []
-    for key, value in (settings.safety or {}).items():
-        state = "on" if value else "off"
-        safety_lines.append(f"  {state}  {key}")
-    safety_text = "\n".join(safety_lines) if safety_lines else "  по умолчанию"
-
-    chat_lines = [f"  {chat.display_name} ({chat.chat_id})" for chat in chats]
-    chats_text = "\n".join(chat_lines) if chat_lines else "  нет активных чатов"
-
-    dashboard = "\n".join(
-        [
-            "Настройки",
-            "",
-            "Скиллы:",
-            skills_text,
-            "",
-            "Личность:",
-            soul_text,
-            "",
-            "Безопасность:",
-            safety_text,
-            "",
-            f"Активные чаты ({len(chats)}):",
-            chats_text,
-        ]
-    )
-
-    return [OutgoingMessage(chat_id=event.chat_id, text=dashboard)]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
 
-async def handle_help(
-    event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
-) -> list:
+async def handle_help(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
     return [OutgoingMessage(chat_id=event.chat_id, text=HELP_TEXT)]
 
 
 async def handle_settings_skills(
     event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
 ) -> list:
-    settings = await settings_mgr.get(event.user_id)
-    return [OutgoingMessage(chat_id=event.chat_id, text=build_skills_text(settings))]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
 
 async def handle_settings_connectors(
     event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
 ) -> list:
-    settings = await settings_mgr.get(event.user_id)
-    return [
-        OutgoingMessage(
-            chat_id=event.chat_id, text=_render_mapping("🔗 Коннекторы", settings.connectors)
-        )
-    ]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
 
 async def handle_settings_soul(
     event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
 ) -> list:
-    if len(event.args) >= 2:
-        field = event.args[0]
-        value = " ".join(event.args[1:])
-        await settings_mgr.apply(
-            event.user_id,
-            SettingsAction(action="set_soul", payload={"field": field, "value": value}),
-        )
-        return [
-            OutgoingMessage(chat_id=event.chat_id, text=f"Личность обновлена: {field} = {value}")
-        ]
-    settings = await settings_mgr.get(event.user_id)
-    return [
-        OutgoingMessage(chat_id=event.chat_id, text=_render_mapping("🧠 Личность", settings.soul))
-    ]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
 
 async def handle_settings_safety(
     event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
 ) -> list:
-    if len(event.args) >= 2:
-        trigger = event.args[0]
-        enabled = _parse_bool(event.args[1])
-        await settings_mgr.apply(
-            event.user_id,
-            SettingsAction(action="set_safety", payload={"trigger": trigger, "enabled": enabled}),
-        )
-        state = "включена" if enabled else "выключена"
-        return [OutgoingMessage(chat_id=event.chat_id, text=f"Безопасность {trigger} {state}")]
-    settings = await settings_mgr.get(event.user_id)
-    return [
-        OutgoingMessage(
-            chat_id=event.chat_id, text=_render_mapping("🔒 Безопасность", settings.safety)
-        )
-    ]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
 
 async def handle_settings_plan(
     event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
 ) -> list:
-    settings = await settings_mgr.get(event.user_id)
-    return [OutgoingMessage(chat_id=event.chat_id, text=_render_mapping("💳 План", settings.plan))]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
 
 async def handle_settings_status(
     event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
 ) -> list:
-    chats = await chat_mgr.list_active(event.user_id)
-    settings = await settings_mgr.get(event.user_id)
-    text = "\n".join(
-        [
-            "📊 Статус",
-            f"Активных чатов: {len(chats)}",
-            f"Скиллов: {len(settings.skills)}",
-            f"Коннекторов: {len(settings.connectors)}",
-        ]
-    )
-    return [OutgoingMessage(chat_id=event.chat_id, text=text)]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
 
 async def handle_settings_whoami(
     event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
 ) -> list:
-    return [OutgoingMessage(chat_id=event.chat_id, text=f"👤 {event.platform}:{event.user_id}")]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
 
 async def handle_toggle_skill(event, auth_mgr, platform, chat_mgr, settings_mgr) -> list:
-    settings = await settings_mgr.get(event.user_id)
-    keys = list(settings.skills.keys())
-    skill = event.payload.get("skill")
-    if not skill:
-        idx = event.payload.get("skill_index")
-        if isinstance(idx, int) and 1 <= idx <= len(keys):
-            skill = keys[idx - 1]
-    if not skill:
-        return [OutgoingMessage(chat_id=event.chat_id, text="Ошибка: не удалось определить навык.")]
+    return [OutgoingMessage(chat_id=event.chat_id, text=MVP_UNAVAILABLE_TEXT)]
 
-    enabled = not bool(settings.skills.get(skill, False))
-    await settings_mgr.apply(
-        event.user_id,
-        SettingsAction(action="toggle_skill", payload={"skill": skill, "enabled": enabled}),
-    )
-    state = "включён" if enabled else "выключен"
-    return [OutgoingMessage(chat_id=event.chat_id, text=f"Навык {skill} {state}.")]
+
+async def handle_unknown_command(
+    event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr
+) -> list:
+    return [
+        OutgoingMessage(
+            chat_id=event.chat_id,
+            text="Неизвестная команда. Используй !help для списка поддерживаемых команд.",
+        )
+    ]

adapter/matrix/reconciliation.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from adapter.matrix.store import (
+    get_room_meta,
+    get_user_meta,
+    next_platform_chat_id,
+    set_room_meta,
+    set_user_meta,
+)
+
+_CHAT_ID_PATTERNS = (
+    re.compile(r"\bC(?P<index>\d+)\b", re.IGNORECASE),
+    re.compile(r"^Чат\s+(?P<index>\d+)$", re.IGNORECASE),
+)
+
+
+@dataclass(slots=True)
+class ReconciliationResult:
+    recovered_rooms: int = 0
+    repaired_rooms: int = 0
+    backfilled_platform_chat_ids: int = 0
+
+
+def _room_name(room: object) -> str | None:
+    for attr in ("name", "display_name"):
+        value = getattr(room, attr, None)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _chat_id_from_room(room: object, existing_meta: dict | None) -> str | None:
+    chat_id = (existing_meta or {}).get("chat_id")
+    if isinstance(chat_id, str) and chat_id:
+        return chat_id
+
+    name = _room_name(room)
+    if not name:
+        return None
+
+    for pattern in _CHAT_ID_PATTERNS:
+        match = pattern.search(name)
+        if match:
+            return f"C{int(match.group('index'))}"
+    return None
+
+
+def _space_id_for_room(
+    room: object, rooms_by_id: dict[str, object], existing_meta: dict | None
+) -> str | None:
+    existing_space_id = (existing_meta or {}).get("space_id")
+    if isinstance(existing_space_id, str) and existing_space_id:
+        return existing_space_id
+
+    parents = getattr(room, "parents", None)
+    if not parents:
+        parents = getattr(room, "space_parents", None)
+    if not parents:
+        return None
+
+    for parent_id in parents:
+        parent = rooms_by_id.get(parent_id)
+        if parent is None:
+            continue
+        if getattr(parent, "room_type", None) == "m.space" or getattr(parent, "children", None):
+            return parent_id
+        return parent_id
+    return None
+
+
+def _matrix_user_id_for_room(
+    room: object, bot_user_id: str | None, existing_meta: dict | None
+) -> str | None:
+    existing_user_id = (existing_meta or {}).get("matrix_user_id")
+    if isinstance(existing_user_id, str) and existing_user_id:
+        return existing_user_id
+
+    users = getattr(room, "users", None) or {}
+    for user_id in users:
+        if user_id != bot_user_id:
+            return user_id
+    return None
+
+
+async def reconcile_startup_state(client: object, runtime: object) -> ReconciliationResult:
+    rooms_by_id = getattr(client, "rooms", None) or {}
+    bot_user_id = getattr(client, "user_id", None)
+    result = ReconciliationResult()
+    max_chat_index_by_user: dict[str, int] = {}
+    recovered_space_by_user: dict[str, str] = {}
+
+    for room_id, room in rooms_by_id.items():
+        if getattr(room, "room_type", None) == "m.space":
+            continue
+
+        existing_meta = await get_room_meta(runtime.store, room_id)
+        if existing_meta and existing_meta.get("redirect_room_id"):
+            continue
+
+        space_id = _space_id_for_room(room, rooms_by_id, existing_meta)
+        chat_id = _chat_id_from_room(room, existing_meta)
+        matrix_user_id = _matrix_user_id_for_room(room, bot_user_id, existing_meta)
+        if not space_id or not chat_id or not matrix_user_id:
+            continue
+
+        recovered_space_by_user[matrix_user_id] = space_id
+        chat_index = int(chat_id[1:])
+        max_chat_index_by_user[matrix_user_id] = max(
+            max_chat_index_by_user.get(matrix_user_id, 0),
+            chat_index,
+        )
+
+        display_name = (existing_meta or {}).get("display_name") or _room_name(room) or chat_id
+        room_meta = dict(existing_meta or {})
+        room_meta.update(
+            {
+                "room_type": "chat",
+                "chat_id": chat_id,
+                "display_name": display_name,
+                "matrix_user_id": matrix_user_id,
+                "space_id": space_id,
+            }
+        )
+
+        if not room_meta.get("platform_chat_id"):
+            room_meta["platform_chat_id"] = await next_platform_chat_id(runtime.store)
+            result.backfilled_platform_chat_ids += 1
+
+        if not room_meta.get("agent_id"):
+            registry = getattr(runtime, "registry", None)
+            if registry is not None:
+                assignment = registry.resolve_agent_for_user(matrix_user_id)
+                if assignment.agent_id:
+                    room_meta["agent_id"] = assignment.agent_id
+                    room_meta["agent_assignment"] = assignment.source
+        else:
+            registry = getattr(runtime, "registry", None)
+            if registry is not None:
+                assignment = registry.resolve_agent_for_user(matrix_user_id)
+                if assignment.source == "configured" and (
+                    room_meta.get("agent_id") != assignment.agent_id
+                    or room_meta.get("agent_assignment") != "configured"
+                ):
+                    room_meta["agent_id"] = assignment.agent_id
+                    room_meta["agent_assignment"] = "configured"
+                elif (
+                    assignment.source == "default"
+                    and room_meta.get("agent_id") == assignment.agent_id
+                    and not room_meta.get("agent_assignment")
+                ):
+                    room_meta["agent_assignment"] = "default"
+
+        if existing_meta is None:
+            result.recovered_rooms += 1
+        elif room_meta != existing_meta:
+            result.repaired_rooms += 1
+
+        await set_room_meta(runtime.store, room_id, room_meta)
+        await runtime.auth_mgr.confirm(matrix_user_id)
+        await runtime.chat_mgr.get_or_create(
+            user_id=matrix_user_id,
+            chat_id=chat_id,
+            platform="matrix",
+            surface_ref=room_id,
+            name=display_name,
+        )
+
+    for matrix_user_id, recovered_space_id in recovered_space_by_user.items():
+        user_meta = dict(await get_user_meta(runtime.store, matrix_user_id) or {})
+        user_meta["space_id"] = user_meta.get("space_id") or recovered_space_id
+        next_chat_index = max_chat_index_by_user[matrix_user_id] + 1
+        user_meta["next_chat_index"] = max(
+            int(user_meta.get("next_chat_index", 1)), next_chat_index
+        )
+        await set_user_meta(runtime.store, matrix_user_id, user_meta)
+
+    return result

adapter/matrix/routed_platform.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Mapping
+
+import structlog
+
+from adapter.matrix.store import get_room_meta
+from core.chat import ChatManager
+from core.store import StateStore
+from sdk.interface import (
+    Attachment,
+    MessageChunk,
+    MessageResponse,
+    PlatformClient,
+    PlatformError,
+    User,
+    UserSettings,
+)
+
+logger = structlog.get_logger(__name__)
+
+
+def _ws_debug_enabled() -> bool:
+    value = os.environ.get("SURFACES_DEBUG_WS", "")
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+class RoutedPlatformClient(PlatformClient):
+    def __init__(
+        self,
+        *,
+        chat_mgr: ChatManager,
+        store: StateStore,
+        delegates: Mapping[str, PlatformClient],
+    ) -> None:
+        if not delegates:
+            raise ValueError("RoutedPlatformClient requires at least one delegate")
+        self._chat_mgr = chat_mgr
+        self._store = store
+        self._delegates = dict(delegates)
+        self._default_client = next(iter(self._delegates.values()))
+        self._prototype_state = getattr(self._default_client, "_prototype_state", None)
+
+    async def get_or_create_user(
+        self,
+        external_id: str,
+        platform: str,
+        display_name: str | None = None,
+    ) -> User:
+        return await self._default_client.get_or_create_user(
+            external_id=external_id,
+            platform=platform,
+            display_name=display_name,
+        )
+
+    async def send_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> MessageResponse:
+        delegate, platform_chat_id = await self._resolve_delegate(user_id, chat_id)
+        return await delegate.send_message(user_id, platform_chat_id, text, attachments)
+
+    async def stream_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> AsyncIterator[MessageChunk]:
+        delegate, platform_chat_id = await self._resolve_delegate(user_id, chat_id)
+        async for chunk in delegate.stream_message(user_id, platform_chat_id, text, attachments):
+            yield chunk
+
+    async def get_settings(self, user_id: str) -> UserSettings:
+        return await self._default_client.get_settings(user_id)
+
+    async def update_settings(self, user_id: str, action) -> None:
+        await self._default_client.update_settings(user_id, action)
+
+    async def close(self) -> None:
+        for delegate in self._delegates.values():
+            close = getattr(delegate, "close", None)
+            if callable(close):
+                await close()
+
+    async def _resolve_delegate(
+        self, user_id: str, local_chat_id: str
+    ) -> tuple[PlatformClient, str]:
+        chat = await self._chat_mgr.get(local_chat_id, user_id)
+        if chat is None:
+            raise PlatformError(
+                f"unknown matrix chat id: {local_chat_id}",
+                code="MATRIX_CHAT_NOT_FOUND",
+            )
+
+        room_meta = await get_room_meta(self._store, chat.surface_ref)
+        if room_meta is None:
+            raise PlatformError(
+                f"matrix room is not bound: {chat.surface_ref}",
+                code="MATRIX_ROOM_NOT_BOUND",
+            )
+
+        agent_id = room_meta.get("agent_id")
+        platform_chat_id = room_meta.get("platform_chat_id")
+        if not agent_id or not platform_chat_id:
+            raise PlatformError(
+                f"matrix room routing is incomplete: {chat.surface_ref}",
+                code="MATRIX_ROUTE_INCOMPLETE",
+            )
+
+        delegate = self._delegates.get(str(agent_id))
+        if delegate is None:
+            raise PlatformError(
+                f"unknown matrix agent id: {agent_id}",
+                code="MATRIX_AGENT_NOT_FOUND",
+            )
+
+        if _ws_debug_enabled():
+            logger.warning(
+                "matrix_route_resolved",
+                user_id=user_id,
+                local_chat_id=local_chat_id,
+                surface_ref=chat.surface_ref,
+                agent_id=str(agent_id),
+                platform_chat_id=str(platform_chat_id),
+                delegate_type=type(delegate).__name__,
+            )
+
+        return delegate, str(platform_chat_id)

adapter/matrix/store.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+import asyncio
+from weakref import WeakValueDictionary
+
 from core.store import StateStore
 
 ROOM_META_PREFIX = "matrix_room:"
@@ -7,6 +10,12 @@ USER_META_PREFIX = "matrix_user:"
 ROOM_STATE_PREFIX = "matrix_state:"
 SKILLS_MSG_PREFIX = "matrix_skills_msg:"
 PENDING_CONFIRM_PREFIX = "matrix_pending_confirm:"
+LOAD_PENDING_PREFIX = "matrix_load_pending:"
+RESET_PENDING_PREFIX = "matrix_reset_pending:"
+STAGED_ATTACHMENTS_PREFIX = "matrix_staged_attachments:"
+PLATFORM_CHAT_SEQ_KEY = "matrix_platform_chat_seq"
+_STAGED_ATTACHMENTS_LOCKS: WeakValueDictionary[str, asyncio.Lock] = WeakValueDictionary()
+_PLATFORM_CHAT_SEQ_LOCK = asyncio.Lock()
 
 
 async def get_room_meta(store: StateStore, room_id: str) -> dict | None:
@@ -17,6 +26,17 @@ async def set_room_meta(store: StateStore, room_id: str, meta: dict) -> None:
     await store.set(f"{ROOM_META_PREFIX}{room_id}", meta)
 
 
+async def get_platform_chat_id(store: StateStore, room_id: str) -> str | None:
+    meta = await get_room_meta(store, room_id)
+    return meta.get("platform_chat_id") if meta else None
+
+
+async def set_platform_chat_id(store: StateStore, room_id: str, platform_chat_id: str) -> None:
+    meta = dict(await get_room_meta(store, room_id) or {})
+    meta["platform_chat_id"] = platform_chat_id
+    await set_room_meta(store, room_id, meta)
+
+
 async def get_user_meta(store: StateStore, matrix_user_id: str) -> dict | None:
     return await store.get(f"{USER_META_PREFIX}{matrix_user_id}")
 
@@ -25,6 +45,12 @@ async def set_user_meta(store: StateStore, matrix_user_id: str, meta: dict) -> N
     await store.set(f"{USER_META_PREFIX}{matrix_user_id}", meta)
 
 
+async def set_room_agent_id(store: StateStore, room_id: str, agent_id: str) -> None:
+    meta = dict(await get_room_meta(store, room_id) or {})
+    meta["agent_id"] = agent_id
+    await set_room_meta(store, room_id, meta)
+
+
 async def get_room_state(store: StateStore, room_id: str) -> str:
     data = await store.get(f"{ROOM_STATE_PREFIX}{room_id}")
     return data["state"] if data else "idle"
@@ -51,16 +77,29 @@ async def next_chat_id(store: StateStore, matrix_user_id: str) -> str:
     return f"C{index}"
 
 
+async def next_platform_chat_id(store: StateStore) -> str:
+    async with _PLATFORM_CHAT_SEQ_LOCK:
+        data = await store.get(PLATFORM_CHAT_SEQ_KEY)
+        index = int((data or {}).get("next_platform_chat_index", 1))
+        await store.set(
+            PLATFORM_CHAT_SEQ_KEY,
+            {"next_platform_chat_index": index + 1},
+        )
+        return str(index)
+
+
 def _pending_confirm_key(user_id: str, room_id: str | None = None) -> str:
     if room_id is None:
         return f"{PENDING_CONFIRM_PREFIX}{user_id}"
     return f"{PENDING_CONFIRM_PREFIX}{user_id}:{room_id}"
 
+
 async def get_pending_confirm(
     store: StateStore, user_id: str, room_id: str | None = None
 ) -> dict | None:
     return await store.get(_pending_confirm_key(user_id, room_id))
 
+
 async def set_pending_confirm(
     store: StateStore, user_id: str, room_id: str | dict, meta: dict | None = None
 ) -> None:
@@ -74,3 +113,95 @@ async def clear_pending_confirm(
     store: StateStore, user_id: str, room_id: str | None = None
 ) -> None:
     await store.delete(_pending_confirm_key(user_id, room_id))
+
+
+def _load_pending_key(user_id: str, room_id: str) -> str:
+    return f"{LOAD_PENDING_PREFIX}{user_id}:{room_id}"
+
+
+async def get_load_pending(store: StateStore, user_id: str, room_id: str) -> dict | None:
+    return await store.get(_load_pending_key(user_id, room_id))
+
+
+async def set_load_pending(store: StateStore, user_id: str, room_id: str, data: dict) -> None:
+    await store.set(_load_pending_key(user_id, room_id), data)
+
+
+async def clear_load_pending(store: StateStore, user_id: str, room_id: str) -> None:
+    await store.delete(_load_pending_key(user_id, room_id))
+
+
+def _reset_pending_key(user_id: str, room_id: str) -> str:
+    return f"{RESET_PENDING_PREFIX}{user_id}:{room_id}"
+
+
+async def get_reset_pending(store: StateStore, user_id: str, room_id: str) -> dict | None:
+    return await store.get(_reset_pending_key(user_id, room_id))
+
+
+async def set_reset_pending(
+    store: StateStore,
+    user_id: str,
+    room_id: str,
+    data: dict,
+) -> None:
+    await store.set(_reset_pending_key(user_id, room_id), data)
+
+
+async def clear_reset_pending(store: StateStore, user_id: str, room_id: str) -> None:
+    await store.delete(_reset_pending_key(user_id, room_id))
+
+
+def _staged_attachments_key(room_id: str, user_id: str) -> str:
+    return f"{STAGED_ATTACHMENTS_PREFIX}{room_id}:{user_id}"
+
+
+def _staged_attachments_lock(room_id: str, user_id: str) -> asyncio.Lock:
+    key = _staged_attachments_key(room_id, user_id)
+    lock = _STAGED_ATTACHMENTS_LOCKS.get(key)
+    if lock is None:
+        lock = asyncio.Lock()
+        _STAGED_ATTACHMENTS_LOCKS[key] = lock
+    return lock
+
+
+async def get_staged_attachments(store: StateStore, room_id: str, user_id: str) -> list[dict]:
+    data = await store.get(_staged_attachments_key(room_id, user_id))
+    if not isinstance(data, dict):
+        return []
+
+    attachments = data.get("attachments")
+    if not isinstance(attachments, list):
+        return []
+
+    return [attachment for attachment in attachments if isinstance(attachment, dict)]
+
+
+async def add_staged_attachment(
+    store: StateStore, room_id: str, user_id: str, attachment: dict
+) -> None:
+    async with _staged_attachments_lock(room_id, user_id):
+        attachments = await get_staged_attachments(store, room_id, user_id)
+        attachments.append(attachment)
+        await store.set(_staged_attachments_key(room_id, user_id), {"attachments": attachments})
+
+
+async def remove_staged_attachment_at(
+    store: StateStore, room_id: str, user_id: str, index: int
+) -> dict | None:
+    async with _staged_attachments_lock(room_id, user_id):
+        attachments = await get_staged_attachments(store, room_id, user_id)
+        if index < 0 or index >= len(attachments):
+            return None
+
+        removed = attachments.pop(index)
+        if attachments:
+            await store.set(_staged_attachments_key(room_id, user_id), {"attachments": attachments})
+        else:
+            await store.delete(_staged_attachments_key(room_id, user_id))
+        return removed
+
+
+async def clear_staged_attachments(store: StateStore, room_id: str, user_id: str) -> None:
+    async with _staged_attachments_lock(room_id, user_id):
+        await store.delete(_staged_attachments_key(room_id, user_id))

config/matrix-agents.example.yaml

@@ -0,0 +1,44 @@
+# Agent registry for the Matrix bot.
+# Production target: one surface bot routes to 25-30 externally managed agents.
+# Keep adding entries with the same base_url/workspace_path pattern.
+#
+# user_agents: maps a Matrix user ID to an agent ID.
+#   If a user is not listed, the bot uses the first agent from the list below.
+#   Omit this section entirely for a single-agent setup.
+#
+# agents: list of available agents.
+#   id             — must match the agent ID known to the platform
+#   label          — human-readable name (shown in logs)
+#   base_url       — HTTP/WS URL of this agent's endpoint
+#                    (overrides the global AGENT_BASE_URL env var for this agent)
+#   workspace_path — absolute path to this agent's workspace directory inside the bot container
+#                    (the bot saves incoming files directly here and reads outgoing files from here)
+#                    Example: /agents/0 means the bot mounts the shared volume at /agents/
+#                    and this agent's files live under /agents/0/
+
+user_agents:
+  "@user0:matrix.example.org": agent-0
+  "@user1:matrix.example.org": agent-1
+  "@user2:matrix.example.org": agent-2
+
+agents:
+  - id: agent-0
+    label: "Agent 0"
+    base_url: "http://lambda.coredump.ru:7000/agent_0/"
+    workspace_path: "/agents/0"
+
+  - id: agent-1
+    label: "Agent 1"
+    base_url: "http://lambda.coredump.ru:7000/agent_1/"
+    workspace_path: "/agents/1"
+
+  - id: agent-2
+    label: "Agent 2"
+    base_url: "http://lambda.coredump.ru:7000/agent_2/"
+    workspace_path: "/agents/2"
+
+  # Continue the same pattern through agent-29 for a 25-30 agent deployment:
+  # - id: agent-29
+  #   label: "Agent 29"
+  #   base_url: "http://lambda.coredump.ru:7000/agent_29/"
+  #   workspace_path: "/agents/29"

config/matrix-agents.smoke.yaml

@@ -0,0 +1,10 @@
+agents:
+  - id: agent-0
+    label: "Smoke Agent 0"
+    base_url: "http://agent-proxy:7000/agent_0/"
+    workspace_path: "/agents/0"
+
+  - id: agent-1
+    label: "Smoke Agent 1"
+    base_url: "http://agent-proxy:7000/agent_1/"
+    workspace_path: "/agents/1"

config/matrix-agents.yaml

@@ -0,0 +1,8 @@
+# Single-agent configuration for MVP deployment.
+# For multi-agent setup with per-user routing, see config/matrix-agents.example.yaml.
+
+agents:
+  - id: agent-1
+    label: Surface
+    base_url: "http://lambda.coredump.ru:7000/agent_1/"
+    workspace_path: "/agents/1"

core/handlers/message.py

@@ -1,7 +1,35 @@
 # core/handlers/message.py
 from __future__ import annotations
 
-from core.protocol import IncomingMessage, OutgoingMessage, OutgoingTyping
+from core.protocol import Attachment, IncomingMessage, OutgoingMessage, OutgoingTyping
+
+
+def _infer_attachment_type(mime_type: str | None) -> str:
+    if not mime_type:
+        return "document"
+    if mime_type.startswith("image/"):
+        return "image"
+    if mime_type.startswith("audio/"):
+        return "audio"
+    if mime_type.startswith("video/"):
+        return "video"
+    return "document"
+
+
+def _to_core_attachments(raw: list) -> list[Attachment]:
+    result = []
+    for a in raw:
+        if isinstance(a, Attachment):
+            result.append(a)
+        else:
+            result.append(Attachment(
+                type=getattr(a, "type", None) or _infer_attachment_type(getattr(a, "mime_type", None)),
+                url=getattr(a, "url", None),
+                filename=getattr(a, "filename", None),
+                mime_type=getattr(a, "mime_type", None),
+                workspace_path=getattr(a, "workspace_path", None),
+            ))
+    return result
 
 
 def _start_command(platform: str) -> str:
@@ -29,10 +57,15 @@ async def handle_message(event: IncomingMessage, auth_mgr, platform, chat_mgr, s
         user_id=event.user_id,
         chat_id=event.chat_id,
         text=event.text,
-        attachments=[],
+        attachments=event.attachments,
     )
 
     return [
         OutgoingTyping(chat_id=event.chat_id, is_typing=False),
-        OutgoingMessage(chat_id=event.chat_id, text=response.response, parse_mode="markdown"),
+        OutgoingMessage(
+            chat_id=event.chat_id,
+            text=response.response,
+            parse_mode="markdown",
+            attachments=_to_core_attachments(getattr(response, "attachments", [])),
+        ),
     ]

core/protocol.py

@@ -12,6 +12,7 @@ class Attachment:
     content: bytes | None = None
     filename: str | None = None
     mime_type: str | None = None
+    workspace_path: str | None = None
 
 
 @dataclass

docker-compose.fullstack.yml

@@ -0,0 +1,61 @@
+services:
+  matrix-bot:
+    extends:
+      file: docker-compose.prod.yml
+      service: matrix-bot
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: development
+      args:
+        LAMBDA_AGENT_API_REF: ${LAMBDA_AGENT_API_REF:-master}
+      additional_contexts:
+        agent_api: ./external/platform-agent_api
+      tags:
+        - ${SURFACES_BOT_DEV_IMAGE:-surfaces-bot:dev}
+    environment:
+      AGENT_BASE_URL: http://platform-agent:8000
+    depends_on:
+      platform-agent:
+        condition: service_healthy
+
+  platform-agent:
+    build:
+      context: ./external/platform-agent
+      target: development
+      additional_contexts:
+        agent_api: ./external/platform-agent_api
+    environment:
+      PYTHONUNBUFFERED: "1"
+      AGENT_ID: ${AGENT_ID:-matrix-dev}
+      PROVIDER_MODEL: ${PROVIDER_MODEL:-openai/gpt-4o-mini}
+      PROVIDER_URL: ${PROVIDER_URL:-}
+      PROVIDER_API_KEY: ${PROVIDER_API_KEY:-}
+      COMPOSIO_API_KEY: ${COMPOSIO_API_KEY:-}
+    volumes:
+      - ./external/platform-agent/src:/app/src
+      - ./external/platform-agent_api:/agent_api
+      - agents:/workspace
+    command: >
+      sh -lc "
+        mkdir -p /workspace &&
+        chown -R agent:agent /workspace &&
+        exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 --no-access-log
+      "
+    ports:
+      - "8000:8000"
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/openapi.json', timeout=2).read()"
+      interval: 60s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+    restart: unless-stopped
+
+volumes:
+  agents:
+    name: ${SURFACES_SHARED_VOLUME:-surfaces-agents}
+  bot-state:
+    name: ${SURFACES_BOT_STATE_VOLUME:-surfaces-bot-state}

docker-compose.prod.yml

@@ -0,0 +1,26 @@
+services:
+  matrix-bot:
+    image: "${SURFACES_BOT_IMAGE:?Set SURFACES_BOT_IMAGE to the pushed image, e.g. mput1/surfaces-bot:latest}"
+    environment:
+      MATRIX_HOMESERVER: ${MATRIX_HOMESERVER:-}
+      MATRIX_USER_ID: ${MATRIX_USER_ID:-}
+      MATRIX_PASSWORD: ${MATRIX_PASSWORD:-}
+      MATRIX_ACCESS_TOKEN: ${MATRIX_ACCESS_TOKEN:-}
+      MATRIX_PLATFORM_BACKEND: ${MATRIX_PLATFORM_BACKEND:-real}
+      MATRIX_AGENT_REGISTRY_PATH: ${MATRIX_AGENT_REGISTRY_PATH:-/app/config/matrix-agents.yaml}
+      AGENT_BASE_URL: ${AGENT_BASE_URL:-}
+      SURFACES_WORKSPACE_DIR: ${SURFACES_WORKSPACE_DIR:-/agents}
+      MATRIX_DB_PATH: /app/state/lambda_matrix.db
+      MATRIX_STORE_PATH: /app/state/matrix_store
+      PYTHONUNBUFFERED: "1"
+    volumes:
+      - agents:/agents
+      - bot-state:/app/state
+      - ./config:/app/config:ro
+    restart: unless-stopped
+
+volumes:
+  agents:
+    name: ${SURFACES_SHARED_VOLUME:-surfaces-agents}
+  bot-state:
+    name: ${SURFACES_BOT_STATE_VOLUME:-surfaces-bot-state}

docker-compose.smoke.timeout.yml

@@ -0,0 +1,18 @@
+services:
+  agent-proxy:
+    volumes:
+      - ./docker/nginx/smoke-agents-timeout.conf:/etc/nginx/nginx.conf:ro
+    depends_on:
+      agent-no-status:
+        condition: service_started
+
+  agent-no-status:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+      args:
+        LAMBDA_AGENT_API_REF: ${LAMBDA_AGENT_API_REF:-master}
+    environment:
+      PYTHONUNBUFFERED: "1"
+    command: ["python", "-m", "tools.no_status_agent", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.smoke.yml

@@ -0,0 +1,109 @@
+services:
+  surface-smoke:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+      args:
+        LAMBDA_AGENT_API_REF: ${LAMBDA_AGENT_API_REF:-master}
+    environment:
+      PYTHONUNBUFFERED: "1"
+      SMOKE_TIMEOUT: ${SMOKE_TIMEOUT:-5}
+    volumes:
+      - agents:/agents
+      - ./config:/app/config:ro
+    depends_on:
+      agent-proxy:
+        condition: service_healthy
+    command: >
+      sh -lc "
+        python -m tools.check_matrix_agents --config /app/config/matrix-agents.smoke.yaml --timeout ${SMOKE_TIMEOUT:-5}
+      "
+
+  agent-proxy:
+    image: nginx:1.27-alpine
+    volumes:
+      - ./docker/nginx/smoke-agents.conf:/etc/nginx/nginx.conf:ro
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - nc -z 127.0.0.1 7000
+      interval: 2s
+      timeout: 2s
+      retries: 15
+      start_period: 2s
+    depends_on:
+      agent-0:
+        condition: service_healthy
+      agent-1:
+        condition: service_healthy
+    ports:
+      - "${SMOKE_PROXY_PORT:-7000}:7000"
+
+  agent-0:
+    build:
+      context: ./external/platform-agent
+      target: development
+      additional_contexts:
+        agent_api: ./external/platform-agent_api
+    environment:
+      PYTHONUNBUFFERED: "1"
+      AGENT_ID: ${AGENT_0_ID:-agent-0}
+      PROVIDER_MODEL: ${PROVIDER_MODEL:-debug-model}
+      PROVIDER_URL: ${PROVIDER_URL:-http://provider.invalid/v1}
+      PROVIDER_API_KEY: ${PROVIDER_API_KEY:-debug-key}
+    volumes:
+      - ./external/platform-agent/src:/app/src
+      - ./external/platform-agent_api:/agent_api
+      - agents:/shared-agents
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/openapi.json', timeout=2).read()"
+      interval: 5s
+      timeout: 3s
+      retries: 12
+      start_period: 5s
+    command: >
+      sh -lc "
+        mkdir -p /shared-agents/0 &&
+        rm -rf /workspace &&
+        ln -s /shared-agents/0 /workspace &&
+        exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 --no-access-log
+      "
+
+  agent-1:
+    build:
+      context: ./external/platform-agent
+      target: development
+      additional_contexts:
+        agent_api: ./external/platform-agent_api
+    environment:
+      PYTHONUNBUFFERED: "1"
+      AGENT_ID: ${AGENT_1_ID:-agent-1}
+      PROVIDER_MODEL: ${PROVIDER_MODEL:-debug-model}
+      PROVIDER_URL: ${PROVIDER_URL:-http://provider.invalid/v1}
+      PROVIDER_API_KEY: ${PROVIDER_API_KEY:-debug-key}
+    volumes:
+      - ./external/platform-agent/src:/app/src
+      - ./external/platform-agent_api:/agent_api
+      - agents:/shared-agents
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/openapi.json', timeout=2).read()"
+      interval: 5s
+      timeout: 3s
+      retries: 12
+      start_period: 5s
+    command: >
+      sh -lc "
+        mkdir -p /shared-agents/1 &&
+        rm -rf /workspace &&
+        ln -s /shared-agents/1 /workspace &&
+        exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 --no-access-log
+      "
+
+volumes:
+  agents:
+    name: ${SURFACES_SMOKE_VOLUME:-surfaces-smoke-agents}

docker-compose.yml

@@ -0,0 +1,39 @@
+services:
+  platform-agent:
+    build:
+      context: ./external/platform-agent
+      target: development
+      additional_contexts:
+        agent_api: ./external/platform-agent_api
+    env_file: .env
+    environment:
+      PYTHONUNBUFFERED: "1"
+    volumes:
+      - ./external/platform-agent/src:/app/src
+      - ./external/platform-agent_api:/agent_api
+      - workspace:/workspace
+    command: >
+      sh -lc "
+        mkdir -p /workspace &&
+        chown -R agent:agent /workspace &&
+        exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000
+      "
+    ports:
+      - "8000:8000"
+    restart: unless-stopped
+
+  matrix-bot:
+    build: .
+    env_file: .env
+    environment:
+      AGENT_BASE_URL: http://platform-agent:8000
+      SURFACES_WORKSPACE_DIR: /workspace
+    depends_on:
+      - platform-agent
+    volumes:
+      - workspace:/workspace
+      - ./config:/app/config:ro
+    restart: unless-stopped
+
+volumes:
+  workspace:

docker/nginx/smoke-agents-timeout.conf

@@ -0,0 +1,28 @@
+events {}
+
+http {
+  map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
+  }
+
+  server {
+    listen 7000;
+
+    location /agent_0/ {
+      proxy_pass http://agent-0:8000/;
+      proxy_http_version 1.1;
+      proxy_set_header Host $host;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection $connection_upgrade;
+    }
+
+    location /agent_1/ {
+      proxy_pass http://agent-no-status:8000/;
+      proxy_http_version 1.1;
+      proxy_set_header Host $host;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection $connection_upgrade;
+    }
+  }
+}

docker/nginx/smoke-agents.conf

@@ -0,0 +1,28 @@
+events {}
+
+http {
+  map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
+  }
+
+  server {
+    listen 7000;
+
+    location /agent_0/ {
+      proxy_pass http://agent-0:8000/;
+      proxy_http_version 1.1;
+      proxy_set_header Host $host;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection $connection_upgrade;
+    }
+
+    location /agent_1/ {
+      proxy_pass http://agent-1:8000/;
+      proxy_http_version 1.1;
+      proxy_set_header Host $host;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection $connection_upgrade;
+    }
+  }
+}

docs/deploy-architecture.md

@@ -0,0 +1,197 @@
+# Deployment Architecture — Matrix Bot + Agents
+
+> Сформировано 2026-04-27 по итогам обсуждения с платформой.
+
+---
+
+## Compose Artifacts
+
+- **Production deploy:** `docker-compose.prod.yml`
+  Bot-only handoff через published image (`SURFACES_BOT_IMAGE`). Поднимает только `matrix-bot`, монтирует shared volume в `/agents`.
+  Платформа предоставляет 25-30 agent containers/services отдельно; бот подключается к ним через `base_url` из `matrix-agents.yaml`.
+- **Internal full-stack E2E:** `docker-compose.fullstack.yml`
+  Внутренний harness для тестирования. Локально собирает `matrix-bot` через Dockerfile target `development`, поднимает один `platform-agent`, health-gated startup.
+
+Production operators: `docker-compose.prod.yml`. Internal E2E: `docker-compose.fullstack.yml`.
+
+---
+
+## Топология
+
+```
+lambda.coredump.ru
+├── :7000  (reverse proxy, path-based routing)
+│   ├── /agent_0/ → agent_0 container
+│   ├── /agent_1/ → agent_1 container
+│   └── /agent_N/ → agent_N container
+│
+└── Matrix bot instance (один инстанс на всех)
+    └── volume /agents/ (shared с агентами)
+        ├── /agents/0/   ← workspace agent_0
+        ├── /agents/1/   ← workspace agent_1
+        └── /agents/N/
+```
+
+- **Один инстанс Matrix-бота** обслуживает всех пользователей.
+- **Один агент-контейнер на пользователя.** Production scale target: 25-30 внешних агентов. Изоляция по `agent_id`, не через один общий agent instance.
+- **Shared volume** `/agents/` смонтирован в Matrix-бот. В internal full-stack harness тот же volume mounted as `/workspace` inside `platform-agent`, чтобы bot-side absolute paths и agent workspace относились к одному и тому же хранилищу.
+
+---
+
+## Конфиг (два словаря)
+
+```yaml
+# config/matrix-agents.yaml
+
+user_agents:
+  "@user0:matrix.lambda.coredump.ru": agent-0
+  "@user1:matrix.lambda.coredump.ru": agent-1
+  "@user2:matrix.lambda.coredump.ru": agent-2
+
+agents:
+  - id: agent-0
+    label: "Agent 0"
+    base_url: "http://lambda.coredump.ru:7000/agent_0/"
+    workspace_path: "/agents/0"
+
+  - id: agent-1
+    label: "Agent 1"
+    base_url: "http://lambda.coredump.ru:7000/agent_1/"
+    workspace_path: "/agents/1"
+
+  - id: agent-2
+    label: "Agent 2"
+    base_url: "http://lambda.coredump.ru:7000/agent_2/"
+    workspace_path: "/agents/2"
+```
+
+- `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент из списка.
+- `agents[].base_url` — HTTP URL агент-эндпоинта. Бот подключается через AgentApi.
+- `agents[].workspace_path` — абсолютный путь к воркспейсу агента **внутри контейнера бота** (т.е. на shared volume).
+  Бот сохраняет входящие файлы прямо в `{workspace_path}/`, читает исходящие из `{workspace_path}/`.
+- Для 25-30 агентов продолжайте тот же паттерн до нужного номера: `/agent_17/` + `/agents/17`, `/agent_29/` + `/agents/29`.
+
+## Surface Image Build Contract
+
+Production image содержит только Matrix surface. Он не содержит `platform-agent` и не требует локального `external/` build context.
+
+```bash
+docker login
+export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest
+
+docker build --target production \
+  --build-arg LAMBDA_AGENT_API_REF=master \
+  -t "$SURFACES_BOT_IMAGE" .
+docker push "$SURFACES_BOT_IMAGE"
+```
+
+Published image:
+
+```text
+mput1/surfaces-bot:latest
+sha256:2f135f3535f7765d4377b440cdabe41195ad2efbc3e175def159ae4689ef90bd
+```
+
+`SURFACES_BOT_IMAGE` должен указывать на registry namespace, куда текущий Docker account может пушить. Ошибка `insufficient_scope` означает, что пользователь не залогинен в этот namespace, repository не создан, или у аккаунта нет push-доступа.
+
+Production Dockerfile ставит `platform/agent_api` из Git по тому же принципу, что и `platform-agent` production image:
+
+```bash
+git+https://git.lambda.coredump.ru/platform/agent_api.git
+```
+
+Локальный `docker-compose.fullstack.yml` остаётся dev/E2E harness: он использует target `development` и `additional_contexts.agent_api=./external/platform-agent_api`, чтобы можно было тестировать surface вместе с локальным checkout SDK.
+
+---
+
+## Agent API (используем master ветку `platform/agent_api`)
+
+```python
+from lambda_agent_api.agent_api import AgentApi
+
+connected_agents: dict[tuple[str, int], AgentApi] = {}
+
+def on_agent_disconnect(agent: AgentApi):
+    connected_agents.pop((agent.id, agent.chat_id), None)
+
+async def on_message(matrix_user_id: str, matrix_room_id: str, text: str):
+    agent_id = get_agent_id_by_user(matrix_user_id)  # из user_agents конфига
+    platform_chat_id = get_room_platform_chat_id(matrix_room_id)
+
+    agent = connected_agents.get((agent_id, platform_chat_id))
+    if not agent:
+        agent = AgentApi(
+            agent_id,
+            get_agent_base_url(agent_id),        # ws://lambda.coredump.ru:7000/agent_0/
+            on_disconnect=on_agent_disconnect,
+            chat_id=platform_chat_id,            # отдельный thread на Matrix room
+        )
+        await agent.connect()
+        connected_agents[(agent_id, platform_chat_id)] = agent
+
+    async for event in agent.send_message(text):
+        ...
+```
+
+**Параметры конструктора (master):**
+```python
+AgentApi(
+    agent_id: str,
+    base_url: str,            # ws://host:port/agent_N/
+    chat_id: int = 0,         # surfaces must supply per-room platform_chat_id
+    on_disconnect: callable,
+)
+```
+
+**Lifecycle:** агент автоматически отключается после нескольких минут бездействия.
+`on_disconnect` удаляет из пула → следующее сообщение создаёт новое соединение.
+
+---
+
+## Передача файлов
+
+### Пользователь → Агент (входящий файл)
+
+1. Matrix-бот получает файл от пользователя
+2. Сохраняет в workspace агента: `/agents/{N}/{filename}`
+3. Если файл уже существует, выбирает следующее имя: `filename (1).ext`, `filename (2).ext`
+4. Вызывает `agent.send_message(text, attachments=["filename"])`
+   — путь относительно `/workspace` агента
+
+### Агент → Пользователь (исходящий файл)
+
+1. Агент эмитит `MsgEventSendFile(path="report.pdf")`
+2. Matrix-бот читает файл: `/agents/{N}/report.pdf`
+3. Отправляет как Matrix file message пользователю
+
+**Ключевое:** production handoff через `docker-compose.prod.yml` и internal E2E через `docker-compose.fullstack.yml` используют один и тот же `/agents` contract на стороне поверхности. Прямой HTTP-доступ к файлам не нужен.
+
+---
+
+## Текущее состояние platform-agent (main)
+
+- Composio интегрирован в main (`#9-интеграция-composIO`)
+- Агент требует в `.env`: `AGENT_ID`, `COMPOSIO_API_KEY`
+- Backend: `IsolatedShellBackend` (main) / `CompositeBackend` (ветка `#19`, не merged)
+- Memory: `MemorySaver` — история слетает при рестарте контейнера (known limitation)
+
+---
+
+## platform-master (будущее, пока не используем)
+
+Ветка `feat/storage` реализует реальный Master-сервис:
+- `POST /api/v1/create {chat_id}` → поднимает/переиспользует sandbox-контейнер
+- TTL-based lifecycle (300с default, конфигурируемо)
+- `ChatStorage` — API для upload/download файлов через Master
+- Auth + p2p lease — вне текущего scope MVP
+
+**Для деплоя MVP используем статический конфиг без Master.**
+При готовности Master: `get_agent_url()` будет вызывать `POST /api/v1/create`, URL возвращается в ответе.
+
+---
+
+## Открытые вопросы
+
+- `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока используем master. Уточнить у платформы сроки мержа перед деплоем.
+- История при рестарте агента теряется — `platform-agent` использует `MemorySaver` (in-memory). Ограничение платформы.
+- `AGENT_ID` и `COMPOSIO_API_KEY` для каждого агент-контейнера — значения предоставляет платформа.

docs/matrix-direct-agent-prototype-ru.md

@@ -0,0 +1,298 @@
+# Matrix Direct-Agent Prototype
+
+Русскоязычная заметка по прототипу Matrix surface, который ходит не в `MockPlatformClient`, а напрямую в живой agent backend по WebSocket.
+
+## Что сделали
+
+В этой ветке собран рабочий Matrix-only прототип с минимальным вмешательством в существующую архитектуру.
+
+Ключевая идея:
+- Matrix-адаптер и `core/` остаются на старом контракте `PlatformClient`
+- вместо `sdk/mock.py` можно включить `sdk/real.py`
+- `sdk/real.py` внутри разделяет две ответственности:
+  - `sdk/agent_session.py` — прямое общение с agent по WebSocket
+  - `sdk/prototype_state.py` — локальный user/settings state для прототипа
+
+Это позволило не переписывать Matrix-логику под нестабильный `platform/master` и при этом подключить живого агента вместо мока.
+
+## Что поменялось в `surfaces-bot`
+
+Добавлено:
+- `sdk/agent_session.py`
+- `sdk/prototype_state.py`
+- `sdk/real.py`
+- тесты для transport/state/real backend
+
+Изменено:
+- `adapter/matrix/bot.py`
+- `adapter/matrix/handlers/auth.py`
+- `README.md`
+- интеграционные и Matrix dispatcher тесты
+
+Функционально это дало:
+- переключение Matrix backend через env:
+  - `MATRIX_PLATFORM_BACKEND=mock`
+  - `MATRIX_PLATFORM_BACKEND=real`
+- прямую отправку текста в live agent через `AGENT_BASE_URL`
+- локальное хранение settings и user mapping
+- изоляцию backend memory по `thread_id`
+- исправление повторных invite: бот теперь сначала `join()`, а уже потом решает, нужно ли пере-провиженить Space/chat tree
+
+## Что поменяли в `platform-agent`
+
+Для прототипа потребовался минимальный локальный патч в клонированном `external/platform-agent`.
+
+Изменения:
+- `src/api/external.py`
+- `src/agent/service.py`
+
+Смысл патча:
+- agent больше не использует один общий hardcoded `thread_id="default"`
+- `thread_id` читается из query parameter WebSocket-соединения
+- дальше этот `thread_id` передаётся в config memory/checkpointer
+
+Локальный commit в clone:
+- `1dca2c1` — `feat: support websocket thread ids`
+
+Важно:
+- этот commit живёт в `external/platform-agent`
+- он не входит в git-историю `surfaces-bot`
+- если прототип должен запускаться у других людей без ручных патчей, этот commit надо отдельно запушить или повторить в platform repo
+
+## Текущая архитектура прототипа
+
+Поток сообщения сейчас такой:
+
+1. Matrix room event попадает в `adapter/matrix`
+2. адаптер переводит его в `IncomingMessage` / `IncomingCommand`
+3. `EventDispatcher` вызывает handler из `core/`
+4. handler вызывает `PlatformClient`
+5. при real backend это `RealPlatformClient`
+6. `RealPlatformClient` строит `thread_key`
+7. `AgentSessionClient` открывает WebSocket на `agent_ws/?thread_id=...`
+8. ответ агента возвращается обратно в Matrix
+
+Что остаётся локальным в v1:
+- `!settings`
+- `!skills`
+- `!soul`
+- `!safety`
+- user registration mapping
+
+Что реально идёт в живого агента:
+- обычные текстовые сообщения
+- память по чатам через `thread_id`
+
+## Ограничения прототипа
+
+Сейчас это не полный platform integration, а рабочий direct-agent prototype.
+
+Ограничения:
+- только текстовый чат
+- без attachments в agent
+- без async task callbacks/webhooks
+- без реального control-plane из `platform/master`
+- encrypted Matrix rooms пока не поддержаны
+- repeat invite не создаёт новую Space-структуру, если user уже был провиженен локально
+- backend/provider ошибки пока не везде деградируют в user-facing reply; часть ошибок всё ещё может уронить процесс surface
+
+## Как запускать
+
+Нужно поднять два процесса:
+- patched `platform-agent`
+- Matrix bot из `surfaces-bot`
+
+### 1. Подготовить `platform-agent`
+
+Локальный clone:
+- [external/platform-agent](/Users/a/MAI/sem2/lambda/surfaces-bot/external/platform-agent)
+
+И связанный SDK clone:
+- [external/platform-agent_api](/Users/a/MAI/sem2/lambda/surfaces-bot/external/platform-agent_api)
+
+Первичная подготовка:
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot/external/platform-agent
+uv sync
+uv pip install --python .venv/bin/python -e ../platform-agent_api
+```
+
+Если у вас был активирован чужой venv, сначала сделайте:
+
+```bash
+deactivate
+```
+
+Иначе `uv pip install` может поставить пакет не в тот interpreter.
+
+### 2. Запустить agent backend
+
+Пример с OpenRouter:
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot/external/platform-agent
+
+export PROVIDER_URL=https://openrouter.ai/api/v1
+export PROVIDER_API_KEY='YOUR_OPENROUTER_KEY'
+export PROVIDER_MODEL='qwen/qwen3.5-122b-a10b'
+
+uv run uvicorn src.main:app --host 0.0.0.0 --port 8000
+```
+
+После этого WebSocket endpoint должен быть доступен по:
+
+```text
+ws://127.0.0.1:8000/agent_ws/
+```
+
+### 3. Запустить Matrix bot
+
+В отдельном терминале:
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot
+
+export MATRIX_PLATFORM_BACKEND=real
+export AGENT_BASE_URL=http://127.0.0.1:8000
+export MATRIX_HOMESERVER=https://matrix.lambda.coredump.ru
+export MATRIX_USER_ID=@lambda_surface_test_bot:matrix.lambda.coredump.ru
+export MATRIX_PASSWORD='YOUR_PASSWORD'
+
+PYTHONPATH=. uv run python -m adapter.matrix.bot
+```
+
+Если всё ок, в логах будет что-то вроде:
+
+```text
+Matrix bot starting ...
+```
+
+## Точные команды
+
+Ниже команды в том виде, в котором реально поднимался рабочий прототип.
+
+### Platform / agent backend
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot/external/platform-agent
+deactivate 2>/dev/null || true
+uv sync
+uv pip install --python .venv/bin/python -e ../platform-agent_api
+
+export PROVIDER_URL=https://openrouter.ai/api/v1
+export PROVIDER_API_KEY='YOUR_OPENROUTER_KEY'
+export PROVIDER_MODEL='qwen/qwen3.5-122b-a10b'
+
+uv run uvicorn src.main:app --host 0.0.0.0 --port 8000
+```
+
+### Matrix bot
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot
+
+export MATRIX_PLATFORM_BACKEND=real
+export AGENT_BASE_URL=http://127.0.0.1:8000
+export MATRIX_HOMESERVER=https://matrix.lambda.coredump.ru
+export MATRIX_USER_ID=@lambda_surface_test_bot:matrix.lambda.coredump.ru
+export MATRIX_PASSWORD='YOUR_PASSWORD'
+
+PYTHONPATH=. uv run python -m adapter.matrix.bot
+```
+
+### Перезапуск Matrix state с нуля
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot
+rm -f lambda_matrix.db
+rm -rf matrix_store
+PYTHONPATH=. uv run python -m adapter.matrix.bot
+```
+
+## Smoke test
+
+Рекомендуемый сценарий ручной проверки:
+
+1. Пригласить бота в fresh unencrypted room
+2. Дождаться join
+3. Если это первый invite для данного локального state:
+   - бот создаст private Space
+   - бот создаст room `Чат 1`
+4. Открыть `Чат 1`
+5. Отправить `!start`
+6. Отправить обычное текстовое сообщение
+7. Проверить, что ответ пришёл от live backend, а не от `[MOCK]`
+8. Проверить `!new`
+9. Проверить, что память разделяется между чатами
+
+Если бот уже был однажды провиженен и локальный state не очищался:
+- повторный invite не создаст новую Space-структуру
+- бот просто зайдёт в room и будет отвечать там
+
+Это нормальное поведение текущей реализации.
+
+## Сброс локального Matrix state
+
+Если нужно повторно проверить именно first-invite provisioning:
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot
+rm -f lambda_matrix.db
+rm -rf matrix_store
+PYTHONPATH=. uv run python -m adapter.matrix.bot
+```
+
+После этого можно снова приглашать бота как "с нуля".
+
+## Частые проблемы
+
+### 1. `ModuleNotFoundError: lambda_agent_api`
+
+Значит `platform-agent_api` не установлен в `.venv` агента.
+
+Исправление:
+
+```bash
+cd /Users/a/MAI/sem2/lambda/surfaces-bot/external/platform-agent
+uv pip install --python .venv/bin/python -e ../platform-agent_api
+```
+
+### 2. `CERTIFICATE_VERIFY_FAILED` при запуске Matrix bot
+
+Это не ошибка surface logic. Это TLS trust problem до Matrix homeserver.
+
+Нужно:
+- либо установить системные/Python certificates
+- либо передать корпоративный CA через `SSL_CERT_FILE`
+
+### 3. Бот заходит в room, но не создаёт новую Space
+
+Скорее всего user уже есть в локальном state.
+
+Варианты:
+- это ожидаемо для repeat invite
+- либо очистить `lambda_matrix.db` и `matrix_store`
+
+### 4. Бот падает после message send
+
+Значит backend/provider вернул ошибку, которая ещё не была деградирована в user-facing ответ.
+
+Пример уже встречавшегося кейса:
+- неверный model id
+- key не имеет доступа к model
+
+Сначала проверяйте:
+- `PROVIDER_URL`
+- `PROVIDER_MODEL`
+- `PROVIDER_API_KEY`
+
+## Полезные ссылки внутри repo
+
+- [README.md](/Users/a/MAI/sem2/lambda/surfaces-bot/README.md)
+- [adapter/matrix/bot.py](/Users/a/MAI/sem2/lambda/surfaces-bot/adapter/matrix/bot.py)
+- [sdk/agent_session.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/agent_session.py)
+- [sdk/real.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/real.py)
+- [sdk/prototype_state.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/prototype_state.py)
+- [2026-04-08-matrix-direct-agent-prototype-design.md](/Users/a/MAI/sem2/lambda/surfaces-bot/docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md)
+- [2026-04-08-matrix-direct-agent-prototype.md](/Users/a/MAI/sem2/lambda/surfaces-bot/docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md)

docs/matrix-prototype.md

@@ -4,263 +4,101 @@
 
 Один бот, каждый чат — отдельная комната, все комнаты собраны в personal Space.
 
-При первом входе бот создаёт для пользователя личное пространство (Space) —
-это как папка в Element. Внутри Space бот создаёт комнату для каждого нового
-чата с агентом. Пользователь видит аккуратную структуру: одно пространство,
-внутри — список чатов. История хранится нативно в Matrix — это часть протокола,
-ничего дополнительно делать не нужно.
+При первом invite бот создаёт для пользователя личное пространство (Space) и первую рабочую комнату.
+История хранится нативно в Matrix. UX прагматичный: явные `!`-команды, локальный state-store, нативные Matrix rooms.
 
-Matrix выбран как внутренняя поверхность: команды лаборатории, тестировщики,
-разработчики скиллов. Поэтому UX здесь прагматичный: минимум магии, явные
-команды `!`, локальный state-store и нативные Matrix rooms.
+Matrix — внутренняя поверхность: команда лаборатории, тестировщики, разработчики скиллов.
 
 ---
 
-## Аутентификация
+## Онбординг
 
-### Флоу
-1. Пользователь приглашает бота в личные сообщения или пишет в общей комнате
-2. Бот проверяет `@user:matrix.org` — есть ли аккаунт на платформе
-3. Если нет — бот отправляет одноразовый код или ссылку
-4. Пользователь подтверждает, платформа возвращает токен
-5. Бот сохраняет привязку `matrix_user_id → platform_user_id`
+1. Пользователь приглашает бота в личные сообщения (DM) на Matrix-сервере
+2. Бот принимает invite, создаёт Space `Lambda — {display_name}` и первую комнату `Чат 1`
+3. Приглашает пользователя в `Чат 1` и пишет приветствие
+4. Дальнейшее общение ведётся в рабочих комнатах, не в DM
 
-### В моке
-- Любой пользователь проходит аутентификацию автоматически
-- Бот отвечает: «Добро пожаловать, {display_name}. Создаю ваше пространство...»
-- Демонстрирует флоу без реальной платформы
-
----
-
-## Чаты через Space + комнаты (вариант Б)
-
-### Структура
 ```
 Space: «Lambda — {display_name}»
-  ├── 💬 Чат 1              ← первый чат, создаётся автоматически
+  ├── 💬 Чат 1              ← создаётся автоматически при invite
   ├── 💬 Чат 2
-  └── 💬 Исследование рынка ← пользователь сам называет
+  └── 💬 Исследование рынка ← пользователь называет сам через !new
 ```
 
-### Создание Space
-При первом входе бот:
-1. Создаёт Space `Lambda — {display_name}`
-2. Создаёт первую комнату-чат `Чат 1`
-3. Передаёт `invite=[matrix_user_id]` прямо в `room_create(...)` для Space и комнаты
-4. Привязывает `chat_id ↔ room_id` в локальном состоянии
-5. Пишет приветствие в `Чат 1`
+**Требование:** незашифрованные комнаты. E2EE не поддержан (инфраструктурное ограничение).
+
+---
+
+## Работающие команды
 
 ### Управление чатами
-Команды работают в зарегистрированных комнатах бота:
 
 | Команда | Действие |
 |---|---|
 | `!new` | Создать новый чат (новую комнату в Space) |
 | `!new Название` | Создать чат с именем |
-| `!help` | Показать шпаргалку по доступным командам |
-| `!rename Название` | Переименовать текущую комнату |
-| `!archive` | Архивировать чат и вывести бота из комнаты |
-| `!chats` | Показать список чатов |
-| `!settings`, `!skills`, `!soul`, `!safety`, `!plan`, `!status`, `!whoami` | Настройки и диагностика |
+| `!chats` | Список активных чатов |
+| `!rename <название>` | Переименовать текущую комнату |
+| `!archive` | Архивировать чат |
+| `!help` | Справка |
 
-### Создание нового чата
-1. Пользователь пишет `!new` или `!new Анализ конкурентов`
-2. Бот создаёт новую комнату в Space
-3. Сразу приглашает пользователя через `room_create(..., invite=[user_id])`
-4. Регистрирует комнату в локальном состоянии и `ChatManager`
-5. Пользователь переходит в новую комнату — начинает диалог
+### Контекст
 
-### В моке
-- Space и комнаты создаются реально через matrix-nio
-- Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...)
-- История хранится в Matrix нативно
-- Дефолтные `skills`, `safety`, `soul`, `plan` подмешиваются даже после частичных локальных обновлений настроек
+| Команда | Действие |
+|---|---|
+| `!clear` | Сбросить контекст текущего чата (создаёт новый thread у агента) |
+| `!reset` | Псевдоним для `!clear` |
 
-### Переименование и архивирование
+### Подтверждения
 
-- `!rename` обновляет имя комнаты через state event `m.room.name`
-- `!archive` архивирует чат в `ChatManager` и делает `room_leave(...)`
-- Если бот потерял локальное состояние и видит комнату как `unregistered:*`, то `!rename` и `!archive` возвращают защитное сообщение вместо сломанного действия
+| Команда | Действие |
+|---|---|
+| `!yes` | Подтвердить действие агента |
+| `!no` | Отменить действие агента |
+
+### Вложения (файловая очередь)
+
+Matrix-клиенты отправляют файлы и текст отдельными событиями. Файл без текстовой инструкции ставится в очередь, а не уходит агенту сразу.
+
+| Команда | Действие |
+|---|---|
+| `!list` | Показать файлы в очереди |
+| `!remove <n>` | Удалить файл из очереди по номеру |
+| `!remove all` | Очистить всю очередь |
+
+Как отправить файлы агенту:
+1. Отправь один или несколько файлов в рабочую комнату
+2. Напиши текстовое сообщение с инструкцией, например: `что на изображении?`
+3. Бот отправит агенту текст вместе со всеми файлами из очереди
 
 ---
 
-## Основной диалог
+## Диалог
 
-### Флоу сообщения
-1. Пользователь пишет текст в комнату-чат
-2. Бот показывает typing (m.typing event)
-3. Запрос уходит в платформу (MockPlatformClient)
-4. Бот отвечает в той же комнате
-
-### Вложения
-- Файлы, изображения отправляются как Matrix media events
-- Бот принимает `m.file`, `m.image`, `m.audio`
-- Передаёт в платформу как `attachments` через `IncomingMessage`
-- В моке: подтверждение получения + заглушка-ответ
-
-### Реакции как действия
-Matrix поддерживает реакции на сообщения (`m.reaction`).
-Используем это для подтверждения действий агента:
-
-```
-Агент: Хочу отправить письмо на vasya@mail.ru
-       Тема: «Отчёт за неделю»
-
-       👍 — подтвердить   ❌ — отменить
-```
-
-Пользователь ставит реакцию — бот обрабатывает. Нативно и удобно.
-
-### Треды для длинных задач
-Если агент выполняет долгую задачу (deep research, генерация документа),
-бот создаёт тред от своего первого ответа и пишет промежуточные статусы туда.
-Основной чат не засоряется.
-
-```
-Бот: Начинаю исследование по теме «AI агенты 2025» [→ в треде]
-  └── Ищу источники... (1/4)
-  └── Анализирую статьи... (2/4)
-  └── Формирую отчёт... (3/4)
-  └── Готово. Отчёт: [...]
-```
+- Любое текстовое сообщение уходит агенту, бот показывает typing-индикатор
+- Ответ стримится по WebSocket и выводится в ту же комнату
+- Каждая комната имеет свой `platform_chat_id` — контексты изолированы между комнатами
 
 ---
 
-## Настройки и диагностика
+## Передача файлов
 
-Отдельной комнаты `Настройки` в текущей версии нет. Команды вызываются как обычные
-`!`-команды из зарегистрированных комнат бота, а `!settings` отдаёт сводный dashboard
-по скиллам, личности, безопасности и активным чатам.
+### Пользователь → Агент
+Бот сохраняет файл в shared volume: `/agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename}`
+и передаёт агенту относительный путь как `workspace_path`.
 
-### Коннекторы
-```
-!connectors                    — показать список
-!connect gmail                 — подключить Gmail (OAuth ссылка)
-!connect github                — подключить GitHub
-!connect calendar              — подключить Google Calendar
-!connect notion                — подключить Notion
-!disconnect gmail              — отключить
-```
-
-Статус:
-```
-Коннекторы:
-  ✅ Gmail — подключён (user@gmail.com)
-  ❌ GitHub — не подключён → !connect github
-  ❌ Google Calendar — не подключён
-  ❌ Notion — не подключён
-```
-
-В моке: OAuth ссылка-заглушка → «Подключено ✓»
-
-### Скиллы
-```
-!skills                        — показать список
-!skill on browser              — включить Browser Use
-!skill off browser             — выключить
-```
-
-Статус:
-```
-Скиллы:
-  ✅ web-search     — поиск в интернете
-  ✅ fetch-url      — чтение веб-страниц
-  ✅ email          — чтение почты (требует Gmail)
-  ❌ browser        — управление браузером
-  ❌ image-gen      — генерация изображений
-  ❌ video-gen      — генерация видео
-  ✅ files          — работа с файлами
-  ❌ calendar       — календарь (требует Google Calendar)
-```
-
-В моке: состояние хранится локально.
-
-### Личность агента
-```
-!soul                          — показать текущий SOUL.md
-!soul name Лямбда              — задать имя агента
-!soul style brief              — стиль: brief | friendly | formal
-!soul priority «разбирать почту утром»  — приоритетная задача
-!soul reset                    — сбросить к дефолту
-```
-
-В моке: SOUL.md генерируется и хранится локально, агент обращается по имени.
-
-### Безопасность
-```
-!safety                        — показать настройки
-!safety on email-send          — требовать подтверждение перед отправкой письма
-!safety off calendar-create    — не спрашивать для создания событий
-```
-
-Статус:
-```
-Подтверждение требуется для:
-  ✅ отправка письма
-  ✅ удаление файлов
-  ✅ публикация в соцсетях
-  ❌ создание события в календаре
-  ❌ поиск в интернете
-```
-
-### Подписка
-```
-!plan                          — показать текущий план
-```
-
-```
-Подписка: Beta (бесплатно)
-Токены этот месяц: 800 / 1000
-━━━━━━━━░░ 80%
-```
-
-Заглушка, реализует другая команда.
-
-### Статус и диагностика
-```
-!status                        — состояние платформы и чатов
-!whoami                        — текущий аккаунт платформы
-```
-
-```
-Статус:
-  Платформа: ✅ доступна
-  Аккаунт: user@lambda.lab
-  Активных чатов: 3
-```
+### Агент → Пользователь
+Агент эмитит путь к файлу в своём workspace. Бот читает файл из `/agents/...`
+и отправляет пользователю как Matrix file message.
 
 ---
 
-## FSM состояния
+## Известные ограничения
 
-```
-[Invite] → AuthPending → AuthConfirmed
-                              ↓
-                         SpaceSetup → Idle (в комнате Настройки)
-                                        ↓
-                    [новая комната] → ChatCreated → Idle (в чате)
-                                                          ↓
-                                            ReceivingMessage → WaitingResponse → Idle
-                                                          ↓
-                                            WaitingReaction (confirm) → [✅/❌] → Idle
-                                                          ↓
-                                            LongTask → [тред со статусами] → Done → Idle
-```
-
----
-
-## Стек
-
-- Python 3.11+
-- matrix-nio (async) — Matrix клиент
-- MockPlatformClient → `platform/interface.py`
-- structlog для логирования
-- SQLite / in-memory store для хранения `matrix_user_id → platform_user_id`, состояния скиллов и маппинга `chat_id → room_id`
-
----
-
-## Ограничения текущей версии
-
-- Ручной QA и текущая разработка идут только в незашифрованных комнатах
-- После рестарта бот делает bootstrap sync и стартует с `since`, поэтому старые события не должны переигрываться повторно
-- Если удалить локальную БД/стор, старые Matrix rooms останутся, но команды, завязанные на локальную регистрацию чатов, перестанут работать для этих комнат до повторного онбординга
+| Проблема | Причина |
+|---|---|
+| `!save` / `!load` / `!context` | Нестабильны: `!save` зависит от агента (пишет файл в workspace), сессии хранятся in-memory и теряются при рестарте |
+| Первый чанк ответа иногда пропадает после tool/file flow | Баг в upstream `platform-agent`; подробности: `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md` |
+| Персистентность истории между рестартами агента | `platform-agent` использует `MemorySaver` (in-memory) |
+| E2EE комнаты | `python-olm` не собирается на macOS/ARM |
+| `!settings` и настройки скиллов/SOUL/безопасности | Заглушки MVP, требуют готового SDK платформы |

docs/max-surface-guide.md

@@ -0,0 +1,340 @@
+# Руководство по созданию новой поверхности Max
+
+Этот документ описывает, как написать новую поверхность для Max по образцу текущей Matrix-поверхности в ветке `feat/deploy`.
+
+Он основан на актуальной реализации Matrix surface в репозитории и отражает текущую продакшн-логику, а не устаревший легаси.
+
+---
+
+## 1. Общая архитектура
+
+### 1.1. Что такое поверхность
+
+Поверхность — это тонкий адаптер между конкретной платформой (Max) и общим ядром бота.
+
+В репозитории есть разделение:
+
+- `core/` — общее ядро и бизнес-логика
+- `adapter/<platform>/` — реализация конкретной поверхности
+- `sdk/real.py` — работа с реальной платформой / агентом
+- `config/` — статическая конфигурация агентов
+- `docs/surface-protocol.md` — общий контракт поверхностей
+
+### 1.2. Как это работает
+
+Поверхность должна:
+
+- принимать нативные события от Max
+- преобразовывать их в единый внутренний контракт (`IncomingMessage`, `IncomingCommand`, `IncomingCallback`)
+- передавать их в `core`
+- получать ответы из `core` (`OutgoingMessage`, `OutgoingUI`, `OutgoingTyping`, `OutgoingNotification`)
+- преобразовывать ответы обратно в нативные Max-сообщения
+
+Поверхность не должна:
+
+- управлять жизненным циклом агентских контейнеров
+- хранить долгую историю бесед вне `core`/платформы
+- аутентифицировать пользователей сама (если это не часть Max API)
+
+---
+
+## 2. Структура новой поверхности
+
+### 2.1. Основные каталоги
+
+Рекомендуемая структура для Max:
+
+```
+adapter/max/
+  bot.py
+  converter.py
+  agent_registry.py
+  files.py
+  handlers/
+  store.py
+```
+
+### 2.2. Принцип reuse
+
+По примеру Matrix surface, Max surface должен переиспользовать общий `core` и общий `sdk`.
+
+Не дублируйте бизнес-логику, а реализуйте только адаптер:
+
+- `adapter/max/converter.py` — конвертация событий Max ⇄ внутренние структуры
+- `adapter/max/bot.py` — основной runtime, старт Max client, loop, отправка/прием
+- `adapter/max/agent_registry.py` — загрузка `config/max-agents.yaml`
+- `adapter/max/files.py` — хранение входящих/исходящих вложений
+
+---
+
+## 3. Контракт входящих/исходящих событий
+
+### 3.1. Внутренний формат
+
+Смотрите `core/protocol.py`. Основные типы:
+
+- `IncomingMessage` — обычное текстовое сообщение + вложения
+- `IncomingCommand` — управляющая команда
+- `IncomingCallback` — подтверждение / интерактивные действия
+- `OutgoingMessage` — ответ пользователю
+- `OutgoingUI` — интерфейсные элементы (кнопки и т.п.)
+- `OutgoingTyping` — индикатор печати
+- `OutgoingNotification` — системное уведомление
+
+### 3.2. Пример конверсии Matrix
+
+В Matrix-реализации `adapter/matrix/converter.py`:
+
+- текст `!yes` / `!no` превращается в `IncomingCallback` с `action: confirm/cancel`
+- `!list`/`!remove` говорят не агенту, а surface-процессу
+- вложения `m.file`, `m.image`, `m.audio`, `m.video` нормализуются в `Attachment`
+
+Для Max реализуйте аналогичную логику для native команд вашего клиента.
+
+---
+
+## 4. Реестр агентов и маршрутизация
+
+### 4.1. Что хранит реестр
+
+В текущей Matrix реализации есть `config/matrix-agents.yaml` и `adapter/matrix/agent_registry.py`.
+
+Структура:
+
+```yaml
+user_agents:
+  "@user0:matrix.example.org": agent-0
+  "@user1:matrix.example.org": agent-1
+
+agents:
+  - id: agent-0
+    label: "Agent 0"
+    base_url: "http://lambda.coredump.ru:7000/agent_0/"
+    workspace_path: "/agents/0"
+```
+
+### 4.2. Логика выбора агента
+
+- `user_agents` маппит конкретного пользователя на `agent_id`
+- если user_id не найден, используется первый агент из списка
+- `agents[].base_url` определяет URL агента
+- `agents[].workspace_path` определяет путь внутри surface-контейнера для этого агента
+
+Это важно: именно на этом контракте строится разделение агентов по рабочим каталогам.
+
+### 4.3. Рекомендуемая Max-версия
+
+Создайте `config/max-agents.yaml` с тем же смыслом.
+
+- `user_agents` — маппинг Max user_id → agent_id
+- `agents` — список агентов
+- `workspace_path` для каждого агента должен быть абсолютным путем внутри surface-контейнера, например `/agents/0`
+
+---
+
+## 5. Файловый контракт
+
+### 5.1. Shared volume
+
+Текущее Matrix-решение использует shared volume:
+
+- surface монтирует общий том как `/agents`
+- каждый агент видит свою поддиректорию как `/workspace`
+
+Топология:
+
+```
+Bot (/agents)              Agent (/workspace = /agents/N/)
+  /agents/0/report.pdf  ←──→  /workspace/report.pdf
+```
+
+### 5.2. Правила записи файлов
+
+В `adapter/matrix/files.py` реализовано:
+
+- входящий файл сохраняется прямо в `{workspace_root}/{filename}`
+- возвращается путь `workspace_path` относительный внутри рабочего каталога агента
+- при коллизии имен создаётся `file (1).ext`, `file (2).ext`
+- `Attachment.workspace_path` передаётся агенту
+
+Для исходящих файлов:
+
+- surface читает файл из `workspace_root / workspace_path`
+- загружает его в платформу
+
+### 5.3. Пример поведения
+
+- Пользователь отправляет файл → surface скачивает файл и кладёт его в agent workspace
+- Агент получает `attachments=["report.pdf"]` и работает с относительным `workspace_path`
+- Агент пишет результат в `/workspace/result.txt`
+- surface читает `/agents/{N}/result.txt` и отправляет файл пользователю
+
+---
+
+## 6. Чат-менеджмент и контекст
+
+### 6.1. `platform_chat_id`
+
+Matrix-реализация использует `platform_chat_id` как стабильный идентификатор чата на стороне агента.
+
+- `room_meta.platform_chat_id` определяется и сохраняется в `adapter/matrix/store.py`
+- `reconcile_startup_state()` восстанавливает отсутствующие `platform_chat_id` при рестарте
+- `RoutedPlatformClient` перенаправляет запросы агенту по `agent_id` + `platform_chat_id`
+
+Для Max surface тот же принцип:
+
+- каждая внешняя беседа должна привязываться к одному внутреннему `chat_id`
+- этот `chat_id` используется для вызовов агента
+- если в Max есть несколько комнат/топиков, каждая должна иметь свой `surface_ref`
+
+### 6.2. Команды управления чатами
+
+Matrix поддерживает следующие команды, которые нужно сохранить в Max:
+
+- `!new [название]` — создать новый чат
+- `!chats` — список активных чатов
+- `!rename <название>` — переименовать текущий чат
+- `!archive` — архивировать чат
+- `!clear` / `!reset` — сбросить контекст текущего чата
+- `!yes` / `!no` — подтвердить или отменить действие агента
+- `!list` — показать очередь вложений
+- `!remove <n>` / `!remove all` — удалить вложение из очереди
+- `!help` — справка
+
+Эти команды реализованы в Matrix через `adapter/matrix/handlers/`.
+
+### 6.3. Очередь вложений
+
+Matrix surface поддерживает staged attachments:
+
+- файл может быть отправлен без текста
+- surface сохраняет файл в `staged_attachments` для конкретного room_id + user_id
+- следующий текст отправляется агенту вместе со всеми файлами из очереди
+
+В Max можно реализовать ту же модель:
+
+- `!list` показывает текущую очередь
+- `!remove` удаляет файл из очереди
+- команда-индикатор или следующее текстовое сообщение отправляет queued attachments агенту
+
+---
+
+## 7. Runtime и окружение
+
+### 7.1. Переменные среды
+
+Для Matrix surface текущий runtime ожидает:
+
+- `MATRIX_HOMESERVER` — URL Matrix-сервера
+- `MATRIX_USER_ID` — `@bot:example.org`
+- `MATRIX_PASSWORD` или `MATRIX_ACCESS_TOKEN`
+- `MATRIX_PLATFORM_BACKEND` — должно быть `real` для продакшна
+- `MATRIX_AGENT_REGISTRY_PATH` — путь к `config/matrix-agents.yaml`
+- `AGENT_BASE_URL` — fallback URL агента
+- `SURFACES_WORKSPACE_DIR` — путь к shared volume внутри контейнера (по умолчанию `/workspace` в коде, но в docs рекомендуют `/agents`)
+
+Для Max surface используйте аналогичные переменные:
+
+- `MAX_PLATFORM_BACKEND=real`
+- `MAX_AGENT_REGISTRY_PATH=/app/config/max-agents.yaml`
+- `SURFACES_WORKSPACE_DIR=/agents`
+- `AGENT_BASE_URL` — если хотите общий fallback
+
+### 7.2. Environment contract
+
+В коде `adapter/matrix/bot.py`:
+
+- `_agent_base_url_from_env()` читает `AGENT_BASE_URL` или `AGENT_WS_URL`
+- `_load_agent_registry_from_env()` читает `MATRIX_AGENT_REGISTRY_PATH`
+- `_build_platform_from_env()` выбирает `RealPlatformClient` при `MATRIX_PLATFORM_BACKEND=real`
+
+В Max surface реализуйте ту же логику, заменив префиксы на `MAX_`.
+
+---
+
+## 8. Тестирование и валидация
+
+### 8.1. Юнит-тесты
+
+В ветке есть покрытие для Matrix surface:
+
+- `tests/adapter/matrix/test_files.py`
+- `tests/adapter/matrix/test_dispatcher.py`
+- `tests/adapter/matrix/test_routed_platform.py`
+- `tests/adapter/matrix/test_reconciliation.py`
+- `tests/adapter/matrix/test_context_commands.py`
+
+Для Max создайте аналогичные тесты:
+
+- проверка загрузки вложений
+- проверка маршрутизации по `agent_id`
+- проверка восстановления `platform_chat_id`
+- проверка конвертации команд
+
+### 8.2. Smoke-проверка deployment
+
+Для Matrix surface есть `docker-compose.prod.yml` и `docker-compose.fullstack.yml`.
+
+Для Max surface должно быть достаточно:
+
+- bot-only production deployment
+- shared volume `/agents`
+- независимая проверка `config/max-agents.yaml`
+- проверка, что surface запускается без локального агента
+
+### 8.3. Проверка контрактов
+
+Особое внимание:
+
+- `agent_registry` должен загружать `workspace_path`
+- file flow должен поддерживать `workspace_path` в `Attachment`
+- отправка файлов должна использовать `resolve_workspace_attachment_path()`
+- `platform_chat_id` должен существовать до вызова агента
+
+---
+
+## 9. Реализация шаг за шагом
+
+1. Скопировать `adapter/matrix/` как шаблон для `adapter/max/`.
+2. Сделать `adapter/max/converter.py`:
+   - превратить native Max-сообщения в `IncomingMessage`
+   - превратить команды в `IncomingCommand`
+   - превратить yes/no-подтверждения в `IncomingCallback`
+3. Сделать `adapter/max/agent_registry.py` на основе `adapter/matrix/agent_registry.py`.
+4. Сделать `adapter/max/files.py` на основе `adapter/matrix/files.py`.
+5. Сделать `adapter/max/bot.py`:
+   - инстанцировать runtime
+   - читать env vars `MAX_*`
+   - загружать реестр агентов
+   - обрабатывать входящие события
+   - отправлять `Outgoing*` обратно в Max
+6. Реализовать команды управления чатами и очередь вложений.
+7. Прописать `config/max-agents.yaml`.
+8. Прописать `docker-compose.max.yml` или аналог, чтобы surface монтировал `/agents`.
+9. Написать тесты по аналогии с `tests/adapter/matrix/`.
+10. Проверить, что все env vars читаются из окружения и не зависят от устаревших Matrix-переменных.
+
+---
+
+## 10. Важные замечания
+
+- Текущий Matrix surface на ветке `feat/deploy` — активная реализация, а не устаревший легаси.
+- Документация и код согласованы: `agent_registry`, `files`, `routed_platform`, `reconciliation` работают вместе.
+- Обязательно явно задавайте `SURFACES_WORKSPACE_DIR=/agents` в production, если `workspace_path` в реестре указывает на `/agents/*`.
+- Для Max surface сохраните ту же архитектуру: surface = thin adapter, агенты = внешние сервисы.
+- Не пытайтесь в surface реализовывать логику запуска/стопа агент-контейнеров.
+
+---
+
+## 11. Полезные ссылки внутри репозитория
+
+- `README.md`
+- `docs/deploy-architecture.md`
+- `docs/surface-protocol.md`
+- `adapter/matrix/bot.py`
+- `adapter/matrix/converter.py`
+- `adapter/matrix/agent_registry.py`
+- `adapter/matrix/files.py`
+- `adapter/matrix/routed_platform.py`
+- `adapter/matrix/reconciliation.py`
+- `tests/adapter/matrix/`

docs/reports/2026-04-21-platform-streaming-bug-report-ru.md

@@ -0,0 +1,245 @@
+# Баг-репорт: регрессия стриминга платформы после file/tool flow
+
+## Кратко
+
+После обновления до текущих upstream-версий платформы стриминг ответов стал нестабильным в сценариях с вложениями и tool/file flow.
+
+Наблюдаемые симптомы:
+
+- первый текстовый chunk ответа может приходить уже обрезанным
+- соседние ответы могут "протекать" друг в друга
+- после некоторых запросов бот перестаёт присылать финальный ответ
+- платформа присылает дублирующий `END`
+
+До обновления платформы этот класс ошибок у нас не воспроизводился.
+
+## Версии платформы
+
+В рантайме используются upstream-репозитории без локальных правок:
+
+- `platform-agent`: `5e7c2df954cc3cd2f5bf8ae688e10a20038dde61`
+- `platform-agent_api`: `aa480bbec5bbf8e006284dd03aed1c2754e9bbee`
+
+## Контекст интеграции
+
+- поверхность: Matrix
+- транспорт к платформе: websocket через `platform-agent_api`
+- `chat_id` на платформу отправляется как стабильный числовой surrogate id
+- shared workspace: `/workspace`
+
+Важно: vendored platform repos чистые, совпадают с upstream. Проблема воспроизводится без локальных patch'ей в платформу.
+
+## Пользовательские симптомы
+
+Примеры из живого диалога:
+
+- ожидалось: `Моя ошибка: ...`
+- фактически пришло: `оя ошибка: ...`
+
+- ожидалось начало ответа вида `По фото IMG_3183.png ...`
+- фактически пришло: `IMG_3183.png**) — это ...`
+
+Также наблюдалось:
+
+- после вопросов по изображениям бот иногда вообще перестаёт отвечать
+- в том же чате, до attachment/tool flow, ответы приходят корректно
+
+## Шаги воспроизведения
+
+1. Поднять `platform-agent` и Matrix surface на версиях выше.
+2. Отправить несколько обычных текстовых сообщений.
+3. Убедиться, что начальные ответы стримятся корректно.
+4. Отправить изображения/файлы и задать вопросы вида:
+   - `что изображено на фото`
+   - уточняющие follow-up вопросы по тем же вложениям
+5. Затем отправить ещё одно обычное текстовое сообщение.
+6. Наблюдать один или несколько симптомов:
+   - первый chunk начинается с середины слова
+   - ответ начинается с середины фразы
+   - хвост прошлого ответа загрязняет следующий
+   - видимого финального ответа нет вообще
+
+## Что удалось доказать
+
+По debug-логам Matrix surface видно, что обрезание присутствует уже в первом chunk, полученном от платформы.
+
+Корректные первые chunk'и до attachment/tool flow:
+
+- `Hey! How`
+- `Я`
+- `Первый файл не найден — возможно, ...`
+
+Некорректные первые chunk'и после attachment/tool flow:
+
+- `IMG_3183.png**) — это ю...`
+- `оя ошибка: в первом запросе...`
+
+Это логируется сразу после десериализации websocket event на клиентской стороне, до Matrix rendering и до финальной сборки текста ответа. Из этого следует, что повреждение происходит на стороне платформенного стриминга, а не в Matrix sender.
+
+## Дополнительное наблюдение по протоколу
+
+Платформа сейчас отправляет дублирующий `END`.
+
+Релевантные места в upstream:
+
+- `external/platform-agent/src/agent/service.py`
+  - уже `yield MsgEventEnd(...)`
+- `external/platform-agent/src/api/external.py`
+  - после завершения цикла дополнительно отправляет ещё один `MsgEventEnd(...)`
+
+В живых логах это видно как:
+
+- первый `END`
+- второй `END`
+- клиентская suppression логика, которая гасит дубликат
+
+Это само по себе делает границы ответа неоднозначными и повышает риск "протекания" поздних событий в следующий запрос.
+
+## Предполагаемая первопричина
+
+Похоже, что на стороне платформы одновременно есть две проблемы.
+
+### 1. Двойной сигнал завершения стрима
+
+Для одного ответа генерируется два `END`.
+
+Вероятные последствия:
+
+- нечёткая граница ответа
+- поздние события могут относиться не к тому запросу
+- соседние ответы могут смешиваться
+
+### 2. Некорректное извлечение текстового chunk'а
+
+В текущем upstream `platform-agent/src/agent/service.py` текст форвардится из `chunk.content` внутри `on_chat_model_stream`.
+
+Однако в документации LangChain для `astream_events()` примеры используют `event["data"]["chunk"].text`, а в Deep Agents stream дополнительно есть `ns`/`source`, которые важны для отделения main-agent output от tool/subagent/model-internal stream.
+
+Потенциальные последствия:
+
+- первый видимый chunk может быть неполным
+- во внешний клиент может попадать не только финальный пользовательский текст
+- attachment/tool flow сильнее деградирует поведение стрима
+
+## Почему проблема считается платформенной
+
+С нашей стороны были проверены и исключены базовые причины:
+
+- вложения корректно сохраняются в `/workspace`
+- контейнер `platform-agent` видит эти файлы
+- Matrix surface получает уже обрезанный первый chunk от платформы
+- обрезание происходит до сборки финального ответа
+- эксперимент с reconnect на каждый запрос не исправил проблему
+- платформенные vendored repos сейчас совпадают с upstream
+
+## Ожидаемое поведение
+
+Для каждого пользовательского запроса:
+
+- текстовые chunk'и должны начинаться с реального начала ответа модели
+- должен приходить ровно один terminal `END`
+- границы ответов должны быть однозначными
+- file/tool flow не должен ломать следующий ответ
+
+## Фактическое поведение
+
+После attachment/tool flow:
+
+- первый text chunk может быть уже обрезан
+- `END` приходит дважды
+- следующий ответ может начаться с середины слова или фразы
+- отдельные запросы могут не завершаться видимым ответом
+
+## Дополнительный failure mode: большие изображения
+
+В отдельном воспроизведении текстовые запросы до файлового сценария работали корректно, а сбой возникал только после попытки анализа изображений.
+
+По логам видно уже не только stream corruption, но и конкретный image-path failure:
+
+- `platform-agent` рвёт websocket с `1009 (message too big)`
+- провайдер возвращает `400` с причиной:
+  - `Exceeded limit on max bytes per data-uri item : 10485760`
+
+Характерный фрагмент:
+
+```text
+websockets.exceptions.ConnectionClosedError: received 1009 (message too big); then sent 1009 (message too big)
+...
+Agent error (INTERNAL_ERROR): Error code: 400 - {
+  'error': {
+    'message': 'Provider returned error',
+    'metadata': {
+      'raw': '{"error":{"message":"Exceeded limit on max bytes per data-uri item : 10485760"...}}'
+    }
+  }
+}
+```
+
+Из этого следует:
+
+- текстовый path сам по себе работоспособен
+- image-analysis path в платформе сейчас передаёт изображение как data URI
+- для достаточно больших изображений это утыкается в provider limit `10,485,760` байт на один data-uri item
+- параллельно websocket path между surface и platform-agent неустойчив к этому failure scenario и закрывается с `1009`
+
+То есть в платформе есть как минимум ещё одна отдельная проблема помимо некорректного стриминга:
+
+- отсутствует безопасная обработка больших изображений до отправки в provider
+- отсутствует аккуратная деградация без разрыва websocket-сессии
+
+## Что стоит исправить в платформе
+
+1. Отправлять ровно один `MsgEventEnd` на один ответ.
+2. Перепроверить extraction текста из `on_chat_model_stream`:
+   - вероятно, должен использоваться `chunk.text`, а не `chunk.content`.
+3. Учитывать `ns`/`source` и форвардить наружу только main assistant output.
+4. Перед отправкой изображений в provider проверять размер payload и не пытаться слать oversized data-uri.
+5. Для больших изображений:
+   - либо делать resize/compression,
+   - либо возвращать контролируемую user-facing ошибку без разрыва websocket.
+6. В идеале добавить более жёсткую request boundary в websocket protocol, чтобы late events не могли прилипать к следующему запросу.
+
+## Наши временные mitigation'ы на стороне surface
+
+Они не исправляют корень, только снижают ущерб:
+
+- suppression duplicate `END`
+- короткий post-`END` drain window
+- idle timeout для зависшего стрима
+- transport failures нормализуются в `PlatformError`, чтобы Matrix bot не падал процессом
+
+Эти меры понадобились только потому, что в текущем сценарии platform stream contract нестабилен.
+
+## Приложение: характерный фрагмент логов
+
+```text
+[matrix-bot] text chunk queue=True text='Первый файл не найден — возможно,'
+[matrix-bot] ...
+[matrix-bot] end event queue=True tokens=0
+[matrix-bot] end event queue=True tokens=0
+[matrix-bot] dropped duplicate END tokens=0
+[matrix-bot] text chunk queue=True text='IMG_3183.png**) — это ю'
+[matrix-bot] ...
+[matrix-bot] end event queue=True tokens=0
+[matrix-bot] end event queue=True tokens=0
+[matrix-bot] dropped duplicate END tokens=0
+[matrix-bot] text chunk queue=True text='оя ошибка: в первом запросе я случайно постав'
+```
+
+Этот фрагмент показывает две вещи:
+
+- duplicate `END` действительно приходит от платформы
+- следующий первый chunk уже приходит в клиента обрезанным
+
+## Приложение: характерный фрагмент логов для больших изображений
+
+```text
+platform-agent-1  | websockets.exceptions.ConnectionClosedError: received 1009 (message too big); then sent 1009 (message too big)
+...
+matrix-bot-1      | Agent error (INTERNAL_ERROR): Error code: 400 - {'error': {'message': 'Provider returned error', 'code': 400, 'metadata': {'raw': '{"error":{"message":"Exceeded limit on max bytes per data-uri item : 10485760","type":"invalid_request_error"...}}}}
+```
+
+Этот фрагмент показывает ещё две вещи:
+
+- image path в платформе реально упирается в лимит провайдера на размер data URI
+- при этом ошибка не изолируется корректно и сопровождается разрывом websocket-соединения

docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md

@@ -0,0 +1,294 @@
+# Финальный баг-репорт: потеря начала ответа и сбои streaming/image path в `platform-agent`
+
+## Статус
+
+Это финальный отчёт после полного аудита интеграции `surfaces -> platform-agent_api -> platform-agent`.
+
+Итог:
+
+- текущая реализация `surfaces` рабочая, но проблемная из-за upstream-дефектов платформы
+- баг с пропадающим началом ответа на текущем состоянии **не локализуется в `surfaces`**
+- в воспроизведённом сценарии повреждённый первый текстовый chunk рождается уже внутри `platform-agent`
+- помимо этого подтверждены ещё два независимых platform-side дефекта:
+  - duplicate `END`
+  - некорректная обработка больших изображений (`data-uri > 10 MB`, `WS 1009`)
+
+## Версии и состояние кода
+
+Рантайм воспроизводился на vendored upstream-репозиториях без локальных platform patch’ей:
+
+- `platform-agent`: `5e7c2df954cc3cd2f5bf8ae688e10a20038dde61`
+- `platform-agent_api`: `aa480bbec5bbf8e006284dd03aed1c2754e9bbee`
+
+Со стороны `surfaces` transport layer был предварительно очищен:
+
+- убрана локальная stream-semantics из `sdk/agent_api_wrapper.py`
+- `sdk/real.py` переведён на pinned upstream `platform-agent_api.AgentApi`
+- больше нет локального post-END drain, custom listener и wrapper-owned reclassification events
+
+Это важно: баг воспроизводился **после** удаления наших транспортных костылей.
+
+## Контекст интеграции
+
+- поверхность: Matrix
+- транспорт к платформе: WebSocket через upstream `platform-agent_api.AgentApi`
+- `chat_id` на платформу: стабильный числовой surrogate id, выдаваемый со стороны `surfaces`
+- файловый контракт: shared `/workspace`, вложения передаются как относительные пути в `attachments`
+
+## Пользовательские симптомы
+
+Наблюдались несколько классов сбоев:
+
+1. Начало ответа может пропасть
+- ожидалось: `Моя ошибка: ...`
+- фактически: `оя ошибка: ...`
+
+- ожидалось: `На двух изображениях: ...`
+- фактически: ` двух изображениях: ...`
+
+2. После tool/file flow ответы могут вести себя нестабильно
+- следующий ответ стартует с середины фразы
+- в некоторых сценариях после image/tool path платформа отвечает ошибкой или замолкает
+
+3. На больших изображениях image path падает совсем
+- provider error `Exceeded limit on max bytes per data-uri item : 10485760`
+- websocket закрывается с `1009 (message too big)`
+
+## Что было проверено на стороне `surfaces`
+
+Ниже перечислено, что именно было перепроверено в нашем коде и почему это не выглядит корнем проблемы.
+
+### 1. Мы больше не режем и не переклассифицируем stream локально
+
+В текущем `surfaces`:
+
+- `sdk/agent_api_wrapper.py` — thin construction/factory shim над upstream `AgentApi`
+- `sdk/real.py` — просто итерирует upstream events и склеивает `MsgEventTextChunk.text`
+- `adapter/matrix/bot.py` — отправляет `OutgoingMessage.text` в Matrix без `strip/lstrip`
+
+Наблюдение:
+
+- в текущем коде не осталось места, где строка могла бы превратиться из `Моя ошибка` в `оя ошибка` через локальный slicing
+
+### 2. Сборка ответа у нас линейная и тупая
+
+`sdk/real.py` делает только следующее:
+
+- если пришёл `MsgEventTextChunk` — добавляет `event.text` в `response_parts`
+- если пришёл `MsgEventSendFile` — превращает его в `Attachment`
+- не пытается “восстанавливать” поток после `END`
+
+Следствие:
+
+- если начало уже отсутствует в `event.text`, мы его не можем ни потерять, ни вернуть
+
+### 3. Matrix sender не модифицирует текст
+
+`adapter/matrix/bot.py` передаёт текст дальше как есть.
+
+Следствие:
+
+- Matrix renderer не является объяснением пропажи первого куска
+
+## Что было проверено в `platform-agent_api`
+
+Upstream client всё ещё имеет спорную queue-архитектуру:
+
+- одна активная `_current_queue`
+- `MsgEventEnd` съедается внутри `send_message()`
+- в `finally` очередь отвязывается и дренится orphan messages
+
+Это архитектурно хрупко и может быть источником других boundary bugs.
+
+Но в конкретном воспроизведении этот слой не был точкой порчи текста.
+
+Почему:
+
+- в raw logs клиент получил **ровно тот же** первый text chunk, который сервер уже отправил
+- queue/dequeue не изменили его содержимое
+
+## Что удалось доказать по raw logs
+
+Для финальной проверки была временно добавлена точечная диагностика в:
+
+- `external/platform-agent/src/agent/service.py`
+- `external/platform-agent/src/api/external.py`
+- `external/platform-agent_api/lambda_agent_api/agent_api.py`
+
+Эта диагностика **не входила** в рабочую реализацию и использовалась только для локализации бага.
+
+### Ключевое наблюдение
+
+На проблемном запросе после tool/file flow сервер сам yield’ил уже обрезанный первый chunk:
+
+```text
+platform-agent-1  | [raw-stream][server-yield] chat=1 event=TEXT text=' двух изображениях:\n\n**Первое изображение'
+platform-agent-1  | [raw-stream][ws-send] chat=1 event=AGENT_EVENT_TEXT_CHUNK text=' двух изображениях:\n\n**Первое изображение' path=None
+matrix-bot-1      | [raw-stream][client-listen] agent=matrix-bot chat=1 queue_active=True AGENT_EVENT_TEXT_CHUNK text=' двух изображениях:\n\n**Первое изображение'
+matrix-bot-1      | [raw-stream][client-dequeue] agent=matrix-bot chat=1 request=2 AGENT_EVENT_TEXT_CHUNK text=' двух изображениях:\n\n**Первое изображение'
+```
+
+Это означает:
+
+- порча произошла **до** websocket-клиента
+- `surfaces` transport layer не является источником именно этого дефекта
+- `platform-agent_api` не исказил этот конкретный chunk по дороге
+
+Дополнительно тот же паттерн виден и вне image-сценария:
+
+```text
+platform-agent-1  | [raw-stream][server-yield] chat=1 event=TEXT text='сё работает напрямую'
+...
+matrix-bot-1      | [raw-stream][client-dequeue] ... text='сё работает напрямую'
+```
+
+То есть сервер уже выдаёт `сё`, а не `Всё`.
+
+## Наиболее вероятный root cause
+
+Главный подозреваемый — `external/platform-agent/src/agent/service.py`.
+
+Сейчас он делает следующее:
+
+- читает `self._agent.astream_events(...)`
+- обрабатывает только `kind == "on_chat_model_stream"`
+- берёт `chunk = event["data"]["chunk"]`
+- если `chunk.content`, форвардит `MsgEventTextChunk(text=chunk.content)`
+
+Проблема в том, что это очень грубое преобразование raw event stream в пользовательский текст.
+
+### Почему именно это место выглядит корнем
+
+1. Первый битый chunk уже рождается на server-side
+- это подтверждено логами выше
+
+2. Код берёт только `chunk.content`
+- если начало ответа приходит в другой форме, поле или raw event, оно просто теряется
+
+3. Код не учитывает `ns` / `source`
+- после tool/vision flow у Deep Agents / LangChain может быть более сложная структура потока
+- текущий adapter flatten’ит её слишком агрессивно
+
+4. Код никак не валидирует, что наружу уходит именно main assistant output
+
+Итоговая гипотеза:
+
+> После tool/file/vision flow `platform-agent` неправильно адаптирует `astream_events()` в `MsgEventTextChunk`. Начало итогового пользовательского ответа может находиться не в том raw event, который сейчас читается через `chunk.content`, либо теряться из-за упрощённой фильтрации потока.
+
+## Подтверждённый отдельный баг: duplicate `END`
+
+Это отдельный platform-side дефект.
+
+Сейчас:
+
+- `external/platform-agent/src/agent/service.py` уже делает `yield MsgEventEnd(...)`
+- `external/platform-agent/src/api/external.py` после завершения цикла дополнительно отправляет ещё один `MsgEventEnd(...)`
+
+По логам это выглядит так:
+
+```text
+platform-agent-1  | [raw-stream][server-yield] chat=1 event=END
+platform-agent-1  | [raw-stream][ws-send] chat=1 event=AGENT_EVENT_END text=None path=None
+platform-agent-1  | [raw-stream][ws-send] chat=1 event=AGENT_EVENT_END duplicate_end=true
+matrix-bot-1      | ... AGENT_EVENT_END tokens_used=0
+matrix-bot-1      | ... AGENT_EVENT_END tokens_used=0
+```
+
+Независимая оценка:
+
+- duplicate `END` — реальный баг платформы
+- он делает границу ответа менее надёжной
+- но в текущем воспроизведении он **не объясняет** сам факт потери первого text chunk
+
+То есть это важный, но вторичный дефект.
+
+## Подтверждённый отдельный баг: большие изображения ломают image path
+
+В отдельном воспроизведении платформа падала на анализе изображений с provider error:
+
+```text
+Exceeded limit on max bytes per data-uri item : 10485760
+```
+
+И параллельно websocket рвался с:
+
+```text
+received 1009 (message too big); then sent 1009 (message too big)
+```
+
+Это означает:
+
+- image path отправляет в provider oversized `data:` URI
+- безопасной предвалидации / деградации нет
+- failure scenario сопровождается разрывом websocket-соединения
+
+Независимая оценка:
+
+- это отдельный platform-side bug
+- он не объясняет потерю первого чанка в текстовом сценарии напрямую
+- но подтверждает, что path `tool/file/image -> platform stream` в целом сейчас нестабилен
+
+## Что мы считаем исключённым
+
+С достаточной уверенностью можно исключить:
+
+1. Локальный slicing текста в `surfaces`
+2. Локальную “умную” реконструкцию потока, потому что она была удалена
+3. Matrix sender как источник потери первого чанка
+4. `platform-agent_api` queue/dequeue как primary root cause именно в этом воспроизведении
+
+## Финальная независимая оценка
+
+Текущая оценка вероятностей:
+
+- `75%` — ошибка в `platform-agent`, в адаптере `astream_events() -> MsgEventTextChunk`
+- `15%` — provider/model stream приносит начало ответа в другой raw event/field, а `platform-agent` его некорректно интерпретирует
+- `10%` — вторичные platform-side boundary defects (`duplicate END`, queue semantics и т.д.)
+- `~0-5%` — ошибка в `surfaces`
+
+Итоговый вывод:
+
+> На текущем состоянии кода баг с пропадающим началом ответа следует считать platform-side дефектом. Воспроизведение после cleanup transport layer показывает, что первый повреждённый text chunk формируется уже внутри `platform-agent` до отправки в websocket.
+
+## Что нужно исправить в платформе
+
+### Обязательно
+
+1. Убрать duplicate `END`
+- один ответ должен завершаться ровно одним `MsgEventEnd`
+
+2. Перепроверить адаптацию `astream_events()` в `service.py`
+- логировать и проанализировать raw `event["event"]`
+- проверить `event.get("name")`
+- смотреть `event.get("ns")`
+- сравнить `chunk.content` с тем, что реально лежит в `chunk.text` / raw chunk repr
+
+3. Форвардить наружу только финальный main assistant output
+- не flatten’ить весь поток без учёта `ns/source`
+
+### Желательно
+
+4. Сделать image path устойчивым к oversized payload
+- preflight check размера
+- resize/compress или controlled error без разрыва WS
+
+5. Улучшить client/server protocol boundary
+- более строгая корреляция запроса и ответа
+- более однозначная semantics конца ответа
+
+## Что мы сделали со своей стороны
+
+Со стороны `surfaces` уже выполнено следующее:
+
+- transport layer очищен до thin adapter над upstream `AgentApi`
+- локальные stream-workaround’ы удалены
+- рабочая интеграция сохранена
+- known issue задокументирован
+
+То есть текущая интеграция не “идеальна”, но её поведение теперь достаточно чистое, чтобы platform bug было можно локализовать без смешения ответственности.
+
+## Приложение: короткий диагноз
+
+Если нужна самая короткая формулировка для issue tracker:
+
+> После cleanup transport layer в `surfaces` и воспроизведения на clean upstream platform repos видно, что `platform-agent` иногда сам порождает первый `MsgEventTextChunk` уже обрезанным, особенно после tool/file flow. Дополнительно подтверждены duplicate `END` и отдельный image-path failure на больших `data:` URI.

docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md

@@ -0,0 +1,515 @@
+# Matrix Direct-Agent Prototype Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace `MockPlatformClient` with a real Matrix-only direct-agent prototype backend while keeping Matrix adapter logic stable and preserving a clean future migration path.
+
+**Architecture:** Introduce a thin compatibility layer under `sdk/` that splits direct WebSocket agent messaging from local prototype-only control-plane state. Keep `core/` and Matrix handlers on the existing `PlatformClient` contract, and limit surface changes to runtime wiring and tests.
+
+**Tech Stack:** Python 3.11, `aiohttp` WebSocket client, `matrix-nio`, `pydantic`, `pytest`, `pytest-asyncio`
+
+---
+
+## File Structure
+
+- Create: `sdk/agent_session.py`
+  Purpose: Minimal direct WebSocket client for the real agent, including thread-key derivation, request/response parsing, and sync/stream helpers.
+
+- Create: `sdk/prototype_state.py`
+  Purpose: Local prototype-only user mapping and settings store kept behind a small API.
+
+- Create: `sdk/real.py`
+  Purpose: `PlatformClient` implementation that composes `AgentSessionClient` and `PrototypeStateStore`.
+
+- Modify: `sdk/__init__.py`
+  Purpose: export `RealPlatformClient` if useful for runtime imports.
+
+- Modify: `adapter/matrix/bot.py`
+  Purpose: runtime/backend selection and env-based configuration for mock vs real backend.
+
+- Create: `tests/platform/test_agent_session.py`
+  Purpose: transport-level tests for direct agent communication.
+
+- Create: `tests/platform/test_prototype_state.py`
+  Purpose: unit tests for local user/settings behavior.
+
+- Create: `tests/platform/test_real.py`
+  Purpose: contract tests for `RealPlatformClient`.
+
+- Modify: `tests/core/test_integration.py`
+  Purpose: prove the new platform implementation preserves core behavior.
+
+- Modify: `README.md`
+  Purpose: document backend selection and prototype limitations after code is working.
+
+---
+
+### Task 1: Add Direct Agent Session Transport
+
+**Files:**
+- Create: `sdk/agent_session.py`
+- Test: `tests/platform/test_agent_session.py`
+
+- [ ] **Step 1: Write the failing transport tests**
+
+```python
+import pytest
+
+from sdk.agent_session import AgentSessionClient, build_thread_key
+
+
+def test_build_thread_key_uses_surface_user_and_chat_id():
+    assert build_thread_key("matrix", "@alice:example.org", "C1") == "matrix:@alice:example.org:C1"
+
+
+@pytest.mark.asyncio
+async def test_send_message_collects_text_chunks_and_tokens(aiohttp_server):
+    ...
+
+
+@pytest.mark.asyncio
+async def test_stream_message_yields_incremental_chunks(aiohttp_server):
+    ...
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/platform/test_agent_session.py -q`
+Expected: FAIL with `ModuleNotFoundError: No module named 'sdk.agent_session'`
+
+- [ ] **Step 3: Write minimal transport implementation**
+
+```python
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import AsyncIterator
+
+import aiohttp
+
+from sdk.interface import MessageChunk, MessageResponse, PlatformError
+
+
+def build_thread_key(platform: str, user_id: str, chat_id: str) -> str:
+    return f"{platform}:{user_id}:{chat_id}"
+
+
+@dataclass
+class AgentSessionConfig:
+    base_ws_url: str
+    timeout_seconds: float = 30.0
+
+
+class AgentSessionClient:
+    def __init__(self, config: AgentSessionConfig) -> None:
+        self._config = config
+
+    async def send_message(self, *, thread_key: str, text: str) -> MessageResponse:
+        chunks = []
+        tokens_used = 0
+        async for chunk in self.stream_message(thread_key=thread_key, text=text):
+            chunks.append(chunk.delta)
+            tokens_used = chunk.tokens_used or tokens_used
+        return MessageResponse(
+            message_id=thread_key,
+            response="".join(chunks),
+            tokens_used=tokens_used,
+            finished=True,
+        )
+
+    async def stream_message(self, *, thread_key: str, text: str) -> AsyncIterator[MessageChunk]:
+        url = f"{self._config.base_ws_url}?thread_id={thread_key}"
+        async with aiohttp.ClientSession() as session:
+            async with session.ws_connect(url, heartbeat=30) as ws:
+                status_msg = await ws.receive_json(timeout=self._config.timeout_seconds)
+                if status_msg.get("type") != "STATUS":
+                    raise PlatformError("Agent did not send STATUS", code="AGENT_PROTOCOL_ERROR")
+
+                await ws.send_json({"type": "USER_MESSAGE", "text": text})
+
+                while True:
+                    payload = await ws.receive_json(timeout=self._config.timeout_seconds)
+                    msg_type = payload.get("type")
+                    if msg_type == "AGENT_EVENT_TEXT_CHUNK":
+                        yield MessageChunk(message_id=thread_key, delta=payload["text"], finished=False)
+                    elif msg_type == "AGENT_EVENT_END":
+                        yield MessageChunk(
+                            message_id=thread_key,
+                            delta="",
+                            finished=True,
+                            tokens_used=payload.get("tokens_used", 0),
+                        )
+                        return
+                    elif msg_type == "ERROR":
+                        raise PlatformError(payload.get("details", "Agent error"), code=payload.get("code", "AGENT_ERROR"))
+                    else:
+                        raise PlatformError(f"Unexpected agent message: {payload}", code="AGENT_PROTOCOL_ERROR")
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/platform/test_agent_session.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add sdk/agent_session.py tests/platform/test_agent_session.py
+git commit -m "feat: add direct agent session transport"
+```
+
+---
+
+### Task 2: Add Local Prototype State For Users And Settings
+
+**Files:**
+- Create: `sdk/prototype_state.py`
+- Test: `tests/platform/test_prototype_state.py`
+
+- [ ] **Step 1: Write the failing state tests**
+
+```python
+import pytest
+
+from core.protocol import SettingsAction
+from sdk.prototype_state import PrototypeStateStore
+
+
+@pytest.mark.asyncio
+async def test_get_or_create_user_is_stable_per_surface_identity():
+    ...
+
+
+@pytest.mark.asyncio
+async def test_settings_defaults_match_existing_mock_shape():
+    ...
+
+
+@pytest.mark.asyncio
+async def test_update_settings_supports_toggle_skill_and_setters():
+    ...
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/platform/test_prototype_state.py -q`
+Expected: FAIL with `ModuleNotFoundError: No module named 'sdk.prototype_state'`
+
+- [ ] **Step 3: Write minimal state implementation**
+
+```python
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sdk.interface import User, UserSettings
+
+# Defaults are defined here, not imported from sdk.mock, to keep real backend
+# isolated from the mock. Copy-paste intentional.
+DEFAULT_SKILLS: dict[str, bool] = {
+    "web-search": True,
+    "fetch-url": True,
+    "email": False,
+    "browser": False,
+    "image-gen": False,
+    "files": True,
+}
+DEFAULT_SAFETY: dict[str, bool] = {"email-send": True, "file-delete": True, "social-post": True}
+DEFAULT_SOUL: dict[str, str] = {"name": "Лямбда", "instructions": ""}
+DEFAULT_PLAN: dict = {"name": "Beta", "tokens_used": 0, "tokens_limit": 1000}
+
+
+class PrototypeStateStore:
+    def __init__(self) -> None:
+        self._users: dict[str, User] = {}
+        self._settings: dict[str, dict] = {}
+
+    async def get_or_create_user(
+        self,
+        *,
+        external_id: str,
+        platform: str,
+        display_name: str | None = None,
+    ) -> User:
+        key = f"{platform}:{external_id}"
+        existing = self._users.get(key)
+        if existing is not None:
+            return existing.model_copy(update={"is_new": False})
+
+        user = User(
+            user_id=f"usr-{platform}-{external_id}",
+            external_id=external_id,
+            platform=platform,
+            display_name=display_name,
+            created_at=datetime.now(UTC),
+            is_new=True,
+        )
+        self._users[key] = user.model_copy(update={"is_new": False})
+        return user
+
+    async def get_settings(self, user_id: str) -> UserSettings:
+        stored = self._settings.get(user_id, {})
+        return UserSettings(
+            skills={**DEFAULT_SKILLS, **stored.get("skills", {})},
+            connectors=stored.get("connectors", {}),
+            soul={**DEFAULT_SOUL, **stored.get("soul", {})},
+            safety={**DEFAULT_SAFETY, **stored.get("safety", {})},
+            plan={**DEFAULT_PLAN, **stored.get("plan", {})},
+        )
+
+    async def update_settings(self, user_id: str, action) -> None:
+        settings = self._settings.setdefault(user_id, {})
+        if action.action == "toggle_skill":
+            skills = settings.setdefault("skills", DEFAULT_SKILLS.copy())
+            skills[action.payload["skill"]] = action.payload.get("enabled", True)
+        elif action.action == "set_soul":
+            soul = settings.setdefault("soul", DEFAULT_SOUL.copy())
+            soul[action.payload["field"]] = action.payload["value"]
+        elif action.action == "set_safety":
+            safety = settings.setdefault("safety", DEFAULT_SAFETY.copy())
+            safety[action.payload["trigger"]] = action.payload.get("enabled", True)
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/platform/test_prototype_state.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add sdk/prototype_state.py tests/platform/test_prototype_state.py
+git commit -m "feat: add prototype local state store"
+```
+
+---
+
+### Task 3: Implement RealPlatformClient Compatibility Layer
+
+**Files:**
+- Create: `sdk/real.py`
+- Modify: `sdk/__init__.py`
+- Test: `tests/platform/test_real.py`
+- Test: `tests/core/test_integration.py`
+
+- [ ] **Step 1: Write the failing compatibility tests**
+
+```python
+import pytest
+
+from core.protocol import SettingsAction
+from sdk.real import RealPlatformClient
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_get_or_create_user_uses_local_state():
+    ...
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_send_message_uses_thread_key():
+    ...
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_settings_are_local():
+    ...
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/platform/test_real.py -q`
+Expected: FAIL with `ModuleNotFoundError: No module named 'sdk.real'`
+
+- [ ] **Step 3: Write minimal compatibility wrapper**
+
+```python
+from __future__ import annotations
+
+from typing import AsyncIterator
+
+from sdk.agent_session import AgentSessionClient, build_thread_key
+from sdk.interface import Attachment, MessageChunk, MessageResponse, PlatformClient, User, UserSettings
+from sdk.prototype_state import PrototypeStateStore
+
+
+class RealPlatformClient(PlatformClient):
+    def __init__(
+        self,
+        agent_sessions: AgentSessionClient,
+        prototype_state: PrototypeStateStore,
+        platform: str = "matrix",
+    ) -> None:
+        self._agent_sessions = agent_sessions
+        self._prototype_state = prototype_state
+        self._platform = platform  # surface name used in thread key; pass explicitly for future surfaces
+
+    async def get_or_create_user(
+        self,
+        external_id: str,
+        platform: str,
+        display_name: str | None = None,
+    ) -> User:
+        return await self._prototype_state.get_or_create_user(
+            external_id=external_id,
+            platform=platform,
+            display_name=display_name,
+        )
+
+    async def send_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> MessageResponse:
+        # user_id here is the internal id (e.g. "usr-matrix-@alice:example.org"), which is
+        # unique per user and stable — acceptable as thread identity for v1 prototype.
+        thread_key = build_thread_key(self._platform, user_id, chat_id)
+        return await self._agent_sessions.send_message(thread_key=thread_key, text=text)
+
+    async def stream_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> AsyncIterator[MessageChunk]:
+        thread_key = build_thread_key(self._platform, user_id, chat_id)
+        async for chunk in self._agent_sessions.stream_message(thread_key=thread_key, text=text):
+            yield chunk
+
+    async def get_settings(self, user_id: str) -> UserSettings:
+        return await self._prototype_state.get_settings(user_id)
+
+    async def update_settings(self, user_id: str, action) -> None:
+        await self._prototype_state.update_settings(user_id, action)
+```
+
+- [ ] **Step 4: Run tests to verify the contract holds**
+
+Run: `pytest tests/platform/test_real.py tests/core/test_integration.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add sdk/real.py sdk/__init__.py tests/platform/test_real.py tests/core/test_integration.py
+git commit -m "feat: add real platform compatibility layer"
+```
+
+---
+
+### Task 4: Wire Matrix Runtime To Real Backend And Document Usage
+
+**Files:**
+- Modify: `adapter/matrix/bot.py`
+- Modify: `README.md`
+- Modify: `tests/adapter/matrix/test_dispatcher.py`
+
+- [ ] **Step 1: Write the failing runtime wiring tests**
+
+```python
+import os
+
+from adapter.matrix.bot import build_runtime
+from sdk.real import RealPlatformClient
+
+
+def test_build_runtime_uses_real_platform_when_matrix_backend_is_real(monkeypatch):
+    monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real")
+    monkeypatch.setenv("AGENT_WS_URL", "ws://agent.example/agent_ws/")
+    runtime = build_runtime()
+    assert isinstance(runtime.platform, RealPlatformClient)
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/adapter/matrix/test_dispatcher.py -q`
+Expected: FAIL because runtime still always constructs `MockPlatformClient`
+
+- [ ] **Step 3: Implement backend selection and docs**
+
+```python
+# adapter/matrix/bot.py — add these imports at the top
+from sdk.agent_session import AgentSessionClient, AgentSessionConfig
+from sdk.interface import PlatformClient
+from sdk.prototype_state import PrototypeStateStore
+from sdk.real import RealPlatformClient
+
+
+def _build_platform_from_env() -> PlatformClient:
+    backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock")
+    if backend == "real":
+        ws_url = os.environ["AGENT_WS_URL"]
+        return RealPlatformClient(
+            agent_sessions=AgentSessionClient(AgentSessionConfig(base_ws_url=ws_url)),
+            prototype_state=PrototypeStateStore(),
+            platform="matrix",
+        )
+    return MockPlatformClient()
+
+
+# Update build_runtime to use env-based selection when no platform is injected:
+def build_runtime(
+    platform: PlatformClient | None = None,  # was MockPlatformClient | None
+    store: StateStore | None = None,
+    client: AsyncClient | None = None,
+) -> MatrixRuntime:
+    platform = platform or _build_platform_from_env()
+    ...  # rest unchanged
+```
+
+Also update the `MatrixRuntime` dataclass field type from `MockPlatformClient` to `PlatformClient` so the type annotation matches the runtime behavior.
+
+```markdown
+# README.md
+
+Matrix prototype backend selection:
+
+- `MATRIX_PLATFORM_BACKEND=mock` uses `sdk/mock.py`
+- `MATRIX_PLATFORM_BACKEND=real` uses direct agent WebSocket integration
+- `AGENT_WS_URL=ws://host:port/agent_ws/` is required for the real backend
+
+Current real-backend limitations:
+- text chat only
+- local settings storage
+- no attachments or async task callbacks yet
+```
+
+- [ ] **Step 4: Run targeted verification**
+
+Run: `pytest tests/adapter/matrix/test_dispatcher.py tests/platform/test_agent_session.py tests/platform/test_prototype_state.py tests/platform/test_real.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/bot.py README.md tests/adapter/matrix/test_dispatcher.py
+git commit -m "feat: wire matrix runtime to real backend"
+```
+
+---
+
+## Self-Review
+
+- Spec coverage:
+  - direct-agent transport: Task 1
+  - local settings/user state: Task 2
+  - stable `PlatformClient` wrapper: Task 3
+  - Matrix runtime wiring and docs: Task 4
+- Placeholder scan: no `TBD`, `TODO`, or “implement later” steps remain in the plan.
+- Type consistency:
+  - `build_thread_key(platform, user_id, chat_id)` is used consistently.
+  - `RealPlatformClient` remains the only bot-facing implementation.
+  - local settings stay in `PrototypeStateStore`.
+
+## Execution Handoff
+
+Plan complete and saved to `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`. Two execution options:
+
+**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
+
+**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+
+**Which approach?**

docs/superpowers/plans/2026-04-19-matrix-per-chat-context.md

@@ -0,0 +1,480 @@
+# Matrix Per-Chat Context Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move the Matrix surface from a shared agent context to true per-room platform contexts mapped through `platform_chat_id`, including `!new`, `!branch`, lazy migration, and per-room context commands.
+
+**Architecture:** Matrix keeps owning UX chats (`C1`, `C2`, rooms, spaces). Each working room stores a `platform_chat_id` in `room_meta`, and platform-facing operations use that mapping. Legacy rooms without a mapping lazily create one on first context-aware use.
+
+**Tech Stack:** Python 3.11, Matrix nio adapter, local state store, `lambda_agent_api`, pytest
+
+---
+
+### Task 1: Add `platform_chat_id` to Matrix metadata and tests
+
+**Files:**
+- Modify: `adapter/matrix/store.py`
+- Test: `tests/adapter/matrix/test_store.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+async def test_room_meta_roundtrip_with_platform_chat_id(store: InMemoryStore):
+    meta = {
+        "chat_id": "C1",
+        "matrix_user_id": "@alice:example.org",
+        "platform_chat_id": "chat-platform-1",
+    }
+    await set_room_meta(store, "!r:m.org", meta)
+    saved = await get_room_meta(store, "!r:m.org")
+    assert saved is not None
+    assert saved["platform_chat_id"] == "chat-platform-1"
+```
+
+- [ ] **Step 2: Run test to verify it fails or proves missing coverage**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_store.py -q`
+Expected: either FAIL on missing assertion coverage or PASS after adding the new test with current generic storage behavior
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/store.py
+# No schema gate is required because room metadata is already stored as a dict.
+# Keep helpers unchanged, but add focused helper functions if they reduce repeated logic:
+
+async def get_platform_chat_id(store: StateStore, room_id: str) -> str | None:
+    meta = await get_room_meta(store, room_id)
+    return meta.get("platform_chat_id") if meta else None
+
+
+async def set_platform_chat_id(store: StateStore, room_id: str, platform_chat_id: str) -> None:
+    meta = await get_room_meta(store, room_id) or {}
+    meta["platform_chat_id"] = platform_chat_id
+    await set_room_meta(store, room_id, meta)
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_store.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/store.py tests/adapter/matrix/test_store.py
+git commit -m "feat: add platform chat id room metadata helpers"
+```
+
+### Task 2: Extend the platform wrapper to support context-aware API calls
+
+**Files:**
+- Modify: `sdk/agent_api_wrapper.py`
+- Modify: `sdk/real.py`
+- Test: `tests/platform/test_real.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+@pytest.mark.asyncio
+async def test_real_client_send_message_uses_platform_chat_id():
+    api = FakeAgentApi()
+    client = RealPlatformClient(agent_api=api, prototype_state=PrototypeStateStore())
+
+    await client.send_message("@alice:example.org", "chat-platform-1", "hello")
+
+    assert api.sent == [("chat-platform-1", "hello")]
+
+
+@pytest.mark.asyncio
+async def test_real_client_create_and_branch_context_delegate_to_agent_api():
+    api = FakeAgentApi(create_ids=["chat-new", "chat-branch"])
+    client = RealPlatformClient(agent_api=api, prototype_state=PrototypeStateStore())
+
+    created = await client.create_chat_context("@alice:example.org")
+    branched = await client.branch_chat_context("@alice:example.org", "chat-source")
+
+    assert created == "chat-new"
+    assert branched == "chat-branch"
+    assert api.branch_calls == ["chat-source"]
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/platform/test_real.py -q`
+Expected: FAIL because `RealPlatformClient` does not yet expose context-aware methods or pass a platform context id through
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# sdk/agent_api_wrapper.py
+class AgentApiWrapper(AgentApi):
+    async def create_chat(self) -> str:
+        ...
+
+    async def branch_chat(self, chat_id: str) -> str:
+        ...
+
+    async def send_message(self, chat_id: str, text: str):
+        ...
+
+    async def save_context(self, chat_id: str, name: str) -> None:
+        ...
+
+    async def load_context(self, chat_id: str, name: str) -> None:
+        ...
+
+
+# sdk/real.py
+class RealPlatformClient(PlatformClient):
+    async def create_chat_context(self, user_id: str) -> str:
+        return await self._agent_api.create_chat()
+
+    async def branch_chat_context(self, user_id: str, from_chat_id: str) -> str:
+        return await self._agent_api.branch_chat(from_chat_id)
+
+    async def save_chat_context(self, user_id: str, chat_id: str, name: str) -> None:
+        await self._agent_api.save_context(chat_id, name)
+
+    async def load_chat_context(self, user_id: str, chat_id: str, name: str) -> None:
+        await self._agent_api.load_context(chat_id, name)
+
+    async def stream_message(...):
+        async for event in self._agent_api.send_message(chat_id, text):
+            ...
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/platform/test_real.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add sdk/agent_api_wrapper.py sdk/real.py tests/platform/test_real.py
+git commit -m "feat: add context-aware real platform client methods"
+```
+
+### Task 3: Create Matrix-side resolver for mapped or lazy-created platform contexts
+
+**Files:**
+- Modify: `adapter/matrix/bot.py`
+- Modify: `adapter/matrix/store.py`
+- Test: `tests/adapter/matrix/test_dispatcher.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+async def test_existing_room_without_platform_chat_id_gets_lazy_mapping_on_message():
+    runtime = build_runtime(platform=FakeRealPlatformClient(create_ids=["chat-platform-1"]))
+    await set_room_meta(runtime.store, "!room:example.org", {
+        "chat_id": "C1",
+        "matrix_user_id": "@alice:example.org",
+    })
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    room = SimpleNamespace(room_id="!room:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="hello")
+
+    await bot.on_room_message(room, event)
+
+    meta = await get_room_meta(runtime.store, "!room:example.org")
+    assert meta["platform_chat_id"] == "chat-platform-1"
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_dispatcher.py -q`
+Expected: FAIL because no lazy mapping exists
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/bot.py
+async def _ensure_platform_chat_id(self, room_id: str, user_id: str) -> str:
+    meta = await get_room_meta(self.runtime.store, room_id)
+    if meta is None:
+        raise ValueError("room metadata is required")
+    platform_chat_id = meta.get("platform_chat_id")
+    if platform_chat_id:
+        return platform_chat_id
+    if not hasattr(self.runtime.platform, "create_chat_context"):
+        raise ValueError("real platform backend required")
+    platform_chat_id = await self.runtime.platform.create_chat_context(user_id)
+    meta["platform_chat_id"] = platform_chat_id
+    await set_room_meta(self.runtime.store, room_id, meta)
+    return platform_chat_id
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_dispatcher.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/bot.py adapter/matrix/store.py tests/adapter/matrix/test_dispatcher.py
+git commit -m "feat: lazily assign platform chat ids to matrix rooms"
+```
+
+### Task 4: Make `!new` and workspace bootstrap create independent platform contexts
+
+**Files:**
+- Modify: `adapter/matrix/handlers/chat.py`
+- Modify: `adapter/matrix/handlers/auth.py`
+- Modify: `adapter/matrix/bot.py`
+- Test: `tests/adapter/matrix/test_chat_space.py`
+- Test: `tests/adapter/matrix/test_invite_space.py`
+- Test: `tests/adapter/matrix/test_dispatcher.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+async def test_new_chat_assigns_new_platform_chat_id():
+    client = SimpleNamespace(
+        room_create=AsyncMock(return_value=SimpleNamespace(room_id="!r2:example")),
+        room_put_state=AsyncMock(),
+        room_invite=AsyncMock(),
+    )
+    platform = FakeRealPlatformClient(create_ids=["chat-platform-7"])
+    runtime = build_runtime(platform=platform, client=client)
+    await set_user_meta(runtime.store, "u1", {"space_id": "!space:example", "next_chat_index": 7})
+
+    result = await runtime.dispatcher.dispatch(
+        IncomingCommand(user_id="u1", platform="matrix", chat_id="C3", command="new", args=["Research"])
+    )
+
+    meta = await get_room_meta(runtime.store, "!r2:example")
+    assert meta["platform_chat_id"] == "chat-platform-7"
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_dispatcher.py -q`
+Expected: FAIL because new chats do not yet store a platform context id
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/handlers/chat.py
+# adapter/matrix/handlers/auth.py
+platform_chat_id = None
+if hasattr(platform, "create_chat_context"):
+    platform_chat_id = await platform.create_chat_context(event.user_id)
+
+await set_room_meta(store, room_id, {
+    "chat_id": chat_id,
+    "matrix_user_id": event.user_id,
+    "space_id": space_id,
+    "platform_chat_id": platform_chat_id,
+})
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_dispatcher.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/handlers/chat.py adapter/matrix/handlers/auth.py adapter/matrix/bot.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_dispatcher.py
+git commit -m "feat: assign platform contexts when creating matrix chats"
+```
+
+### Task 5: Make per-room save, load, and context use the mapped platform context
+
+**Files:**
+- Modify: `adapter/matrix/handlers/context_commands.py`
+- Modify: `adapter/matrix/bot.py`
+- Modify: `sdk/prototype_state.py`
+- Test: `tests/adapter/matrix/test_context_commands.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+@pytest.mark.asyncio
+async def test_save_command_uses_room_platform_chat_id():
+    platform = MatrixCommandPlatform()
+    runtime = build_runtime(platform=platform)
+    await set_room_meta(runtime.store, "!room:example.org", {
+        "chat_id": "C1",
+        "matrix_user_id": "u1",
+        "platform_chat_id": "chat-platform-1",
+    })
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="save", args=["session-a"])
+
+    result = await make_handle_save(...)(event, runtime.auth_mgr, platform, runtime.chat_mgr, runtime.settings_mgr)
+
+    assert platform.saved_calls == [("chat-platform-1", "session-a")]
+
+
+@pytest.mark.asyncio
+async def test_context_command_reports_current_room_platform_chat_id():
+    ...
+    assert "chat-platform-1" in result[0].text
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_context_commands.py -q`
+Expected: FAIL because save/load/context do not currently use room-level platform mappings
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/handlers/context_commands.py
+room_id = await _resolve_room_id(event, chat_mgr)
+meta = await get_room_meta(store, room_id)
+platform_chat_id = meta.get("platform_chat_id")
+
+await platform.save_chat_context(event.user_id, platform_chat_id, name)
+await platform.load_chat_context(event.user_id, platform_chat_id, name)
+
+# sdk/prototype_state.py
+# store current loaded session per user+platform_chat_id instead of only per user when needed for Matrix `!context`
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_context_commands.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/handlers/context_commands.py adapter/matrix/bot.py sdk/prototype_state.py tests/adapter/matrix/test_context_commands.py
+git commit -m "feat: bind matrix context commands to platform chat ids"
+```
+
+### Task 6: Add `!branch` and help-text updates
+
+**Files:**
+- Modify: `adapter/matrix/handlers/chat.py`
+- Modify: `adapter/matrix/handlers/__init__.py`
+- Modify: `adapter/matrix/handlers/settings.py`
+- Modify: `adapter/matrix/handlers/auth.py`
+- Modify: `adapter/matrix/bot.py`
+- Test: `tests/adapter/matrix/test_chat_space.py`
+- Test: `tests/adapter/matrix/test_dispatcher.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+async def test_branch_creates_new_room_with_branched_platform_chat_id():
+    client = SimpleNamespace(
+        room_create=AsyncMock(return_value=SimpleNamespace(room_id="!r3:example")),
+        room_put_state=AsyncMock(),
+        room_invite=AsyncMock(),
+    )
+    platform = FakeRealPlatformClient(branch_ids=["chat-platform-branch"])
+    runtime = build_runtime(platform=platform, client=client)
+    await set_room_meta(runtime.store, "!current:example", {
+        "chat_id": "C2",
+        "matrix_user_id": "u1",
+        "space_id": "!space:example",
+        "platform_chat_id": "chat-platform-source",
+    })
+
+    result = await runtime.dispatcher.dispatch(
+        IncomingCommand(user_id="u1", platform="matrix", chat_id="C2", command="branch", args=["Fork"])
+    )
+
+    meta = await get_room_meta(runtime.store, "!r3:example")
+    assert meta["platform_chat_id"] == "chat-platform-branch"
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_dispatcher.py -q`
+Expected: FAIL because `branch` is not implemented
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/handlers/chat.py
+def make_handle_branch(client, store):
+    async def handle_branch(event, auth_mgr, platform, chat_mgr, settings_mgr):
+        source_room_id = ...
+        source_meta = await get_room_meta(store, source_room_id)
+        platform_chat_id = await platform.branch_chat_context(event.user_id, source_meta["platform_chat_id"])
+        ...
+        await set_room_meta(store, new_room_id, {
+            "chat_id": new_chat_id,
+            "matrix_user_id": event.user_id,
+            "space_id": space_id,
+            "platform_chat_id": platform_chat_id,
+        })
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_dispatcher.py -q`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/handlers/chat.py adapter/matrix/handlers/__init__.py adapter/matrix/handlers/settings.py adapter/matrix/handlers/auth.py adapter/matrix/bot.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_dispatcher.py
+git commit -m "feat: add matrix branch command for platform contexts"
+```
+
+### Task 7: Verify the full Matrix flow and clean up legacy assumptions
+
+**Files:**
+- Modify: `tests/platform/test_real.py`
+- Modify: `tests/adapter/matrix/test_dispatcher.py`
+- Modify: `tests/adapter/matrix/test_context_commands.py`
+- Modify: `tests/core/test_integration.py`
+
+- [ ] **Step 1: Add integration coverage for independent room contexts**
+
+```python
+@pytest.mark.asyncio
+async def test_two_rooms_send_messages_into_different_platform_contexts():
+    platform = FakeRealPlatformClient()
+    runtime = build_runtime(platform=platform)
+    await set_room_meta(runtime.store, "!r1:example", {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "chat-1"})
+    await set_room_meta(runtime.store, "!r2:example", {"chat_id": "C2", "matrix_user_id": "u1", "platform_chat_id": "chat-2"})
+    ...
+    assert platform.sent == [("chat-1", "hello"), ("chat-2", "world")]
+```
+
+- [ ] **Step 2: Run the focused verification suite**
+
+Run: `PYTHONPATH=. uv run pytest tests/platform/test_real.py tests/adapter/matrix/test_store.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py tests/core/test_integration.py -q`
+Expected: PASS
+
+- [ ] **Step 3: Run the full Matrix suite**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix -q`
+Expected: PASS
+
+- [ ] **Step 4: Inspect help text and command visibility**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_dispatcher.py -q`
+Expected: PASS with `!branch` present in help and hidden commands still absent
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/platform/test_real.py tests/adapter/matrix/test_store.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py tests/core/test_integration.py
+git commit -m "test: verify matrix per-chat platform context flow"
+```
+
+## Self-Review
+
+- Spec coverage:
+  - `surface_chat -> platform_chat_id` mapping is covered by Tasks 1, 3, and 4.
+  - `!new` independent contexts are covered by Task 4.
+  - `!branch` snapshot flow is covered by Task 6.
+  - per-room `!save`, `!load`, and `!context` are covered by Task 5.
+  - lazy migration for legacy rooms is covered by Task 3.
+  - verification across rooms is covered by Task 7.
+- Placeholder scan:
+  - No `TODO` or `TBD` placeholders remain.
+  - Commands and file paths are concrete.
+- Type consistency:
+  - The plan consistently uses `platform_chat_id` for stored mapping and `create_chat_context` / `branch_chat_context` / `save_chat_context` / `load_chat_context` for platform-facing methods.

docs/superpowers/plans/2026-04-20-matrix-shared-workspace-file-flow.md

@@ -0,0 +1,624 @@
+# Matrix Shared Workspace File Flow Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move the Matrix surface to a prod-like shared-workspace file flow where incoming files are downloaded into `/workspace`, passed to `platform-agent` as relative attachment paths, and outbound `send_file` events are delivered back to the Matrix room.
+
+**Architecture:** Keep the platform contract path-based and surface-agnostic. Extend the surface attachment model with a workspace-relative path, update the real SDK bridge to forward attachments and modern agent events, then add a Matrix-specific storage helper plus a shared-volume runtime. This preserves room/context semantics while aligning file flow with upstream `platform-agent`.
+
+**Tech Stack:** Python 3.11, matrix-nio, aiohttp, Docker Compose, pytest, pytest-asyncio
+
+---
+
+## File Structure
+
+- Modify: `core/protocol.py`
+  Purpose: add a workspace-relative attachment field that future surfaces can also use.
+- Modify: `sdk/interface.py`
+  Purpose: keep the platform-side attachment shape aligned with the surface model.
+- Modify: `core/handlers/message.py`
+  Purpose: stop dropping attachments before platform dispatch.
+- Modify: `sdk/agent_api_wrapper.py`
+  Purpose: accept modern upstream agent events and modern WS route semantics.
+- Modify: `sdk/real.py`
+  Purpose: convert attachment objects into workspace-relative paths and forward them to the agent API.
+- Create: `adapter/matrix/files.py`
+  Purpose: Matrix-specific download/upload helper for shared `/workspace`.
+- Modify: `adapter/matrix/bot.py`
+  Purpose: persist incoming Matrix files into shared workspace and render outbound file events back to Matrix.
+- Modify: `tests/core/test_integration.py`
+  Purpose: prove message dispatch keeps attachments and platform send path receives them.
+- Modify: `tests/platform/test_real.py`
+  Purpose: verify attachment forwarding and outbound file events.
+- Create: `tests/adapter/matrix/test_files.py`
+  Purpose: unit coverage for Matrix workspace path building, download handling, and outbound upload behavior.
+- Modify: `tests/adapter/matrix/test_dispatcher.py`
+  Purpose: verify Matrix bot file receive/send integration.
+- Modify: `docker-compose.yml`
+  Purpose: define shared `/workspace` runtime between `matrix-bot` and `platform-agent`.
+- Modify: `README.md`
+  Purpose: document the new default runtime and file flow.
+- Modify: `.env.example`
+  Purpose: update real-backend defaults to in-compose service URLs and workspace-aware runtime.
+
+### Task 1: Preserve Attachment Metadata Through Core Message Dispatch
+
+**Files:**
+- Modify: `core/protocol.py`
+- Modify: `sdk/interface.py`
+- Modify: `core/handlers/message.py`
+- Test: `tests/core/test_dispatcher.py`
+- Test: `tests/core/test_integration.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/core/test_integration.py
+class RecordingAgentApi:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, list[str]]] = []
+        self.last_tokens_used = 0
+
+    async def send_message(self, text: str, attachments: list[str] | None = None):
+        self.calls.append((text, attachments or []))
+        yield type("Chunk", (), {"text": f"[REAL] {text}"})()
+        self.last_tokens_used = 5
+
+
+async def test_full_flow_with_real_platform_forwards_workspace_attachment(real_dispatcher):
+    dispatcher, agent_api = real_dispatcher
+
+    start = IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="start")
+    await dispatcher.dispatch(start)
+
+    msg = IncomingMessage(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C1",
+        text="Посмотри файл",
+        attachments=[
+            Attachment(
+                type="document",
+                filename="report.pdf",
+                mime_type="application/pdf",
+                workspace_path="surfaces/matrix/u1/room/inbox/report.pdf",
+            )
+        ],
+    )
+    await dispatcher.dispatch(msg)
+
+    assert agent_api.calls == [
+        ("Посмотри файл", ["surfaces/matrix/u1/room/inbox/report.pdf"])
+    ]
+```
+
+```python
+# tests/core/test_dispatcher.py
+async def test_dispatch_routes_document_before_catchall(dispatcher):
+    async def doc_handler(event, **kwargs):
+        return [OutgoingMessage(chat_id=event.chat_id, text="document")]
+
+    async def catch_all(event, **kwargs):
+        return [OutgoingMessage(chat_id=event.chat_id, text="text")]
+
+    dispatcher.register(IncomingMessage, "document", doc_handler)
+    dispatcher.register(IncomingMessage, "*", catch_all)
+
+    doc_msg = IncomingMessage(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C1",
+        text="",
+        attachments=[Attachment(type="document", workspace_path="surfaces/matrix/u1/file.txt")],
+    )
+
+    assert (await dispatcher.dispatch(doc_msg))[0].text == "document"
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/core/test_dispatcher.py tests/core/test_integration.py -q`
+
+Expected:
+- FAIL because `Attachment` has no `workspace_path`
+- FAIL because `handle_message(...)` still sends `attachments=[]`
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# core/protocol.py
+@dataclass
+class Attachment:
+    type: str
+    url: str | None = None
+    content: bytes | None = None
+    filename: str | None = None
+    mime_type: str | None = None
+    workspace_path: str | None = None
+```
+
+```python
+# sdk/interface.py
+class Attachment(BaseModel):
+    url: str | None = None
+    mime_type: str | None = None
+    size: int | None = None
+    filename: str | None = None
+    workspace_path: str | None = None
+```
+
+```python
+# core/handlers/message.py
+response = await platform.send_message(
+    user_id=event.user_id,
+    chat_id=event.chat_id,
+    text=event.text,
+    attachments=event.attachments,
+)
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/core/test_dispatcher.py tests/core/test_integration.py -q`
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add core/protocol.py sdk/interface.py core/handlers/message.py tests/core/test_dispatcher.py tests/core/test_integration.py
+git commit -m "feat: preserve workspace attachments through message dispatch"
+```
+
+### Task 2: Upgrade the Real SDK Bridge to Modern Agent File Events
+
+**Files:**
+- Modify: `sdk/agent_api_wrapper.py`
+- Modify: `sdk/real.py`
+- Test: `tests/platform/test_real.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/platform/test_real.py
+class FakeSendFileEvent:
+    def __init__(self, path: str) -> None:
+        self.path = path
+
+
+class FakeChatAgentApi:
+    ...
+    async def send_message(self, text: str, attachments: list[str] | None = None):
+        self.calls.append((text, attachments or []))
+        midpoint = len(text) // 2
+        yield FakeChunk(text[:midpoint])
+        yield FakeChunk(text[midpoint:])
+        self.last_tokens_used = 3
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_send_message_forwards_workspace_paths():
+    agent_api = FakeAgentApiFactory()
+    client = RealPlatformClient(
+        agent_api=agent_api,
+        prototype_state=PrototypeStateStore(),
+        platform="matrix",
+    )
+
+    await client.send_message(
+        "@alice:example.org",
+        "chat-7",
+        "hello",
+        attachments=[
+            type("Attachment", (), {"workspace_path": "surfaces/matrix/alice/room/file.pdf"})()
+        ],
+    )
+
+    assert agent_api.instances["chat-7"].calls == [
+        ("hello", ["surfaces/matrix/alice/room/file.pdf"])
+    ]
+
+
+def test_agent_api_wrapper_treats_send_file_as_known_event(monkeypatch):
+    seen = []
+
+    class FakeSendFile:
+        type = "AGENT_EVENT_SEND_FILE"
+        path = "docs/result.pdf"
+
+    monkeypatch.setattr(
+        "sdk.agent_api_wrapper.ServerMessage.validate_json",
+        lambda raw: FakeSendFile(),
+    )
+
+    wrapper = AgentApiWrapper(agent_id="agent-1", base_url="https://agent.example.com", chat_id="7")
+    wrapper.callback = seen.append
+    wrapper._current_queue = None
+
+    # use the wrapper's dispatch branch directly inside _listen test harness
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/platform/test_real.py -q`
+
+Expected:
+- FAIL because `RealPlatformClient` ignores attachments
+- FAIL because `AgentApiWrapper` only recognizes text/end/error/disconnect events
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# sdk/real.py
+def _attachment_paths(self, attachments) -> list[str]:
+    if not attachments:
+        return []
+    paths = []
+    for attachment in attachments:
+        path = getattr(attachment, "workspace_path", None)
+        if path:
+            paths.append(path)
+    return paths
+
+async def stream_message(...):
+    attachment_paths = self._attachment_paths(attachments)
+    ...
+    async for event in chat_api.send_message(text, attachments=attachment_paths):
+        if hasattr(event, "path"):
+            yield MessageChunk(
+                message_id=user_id,
+                delta="",
+                finished=False,
+            )
+            continue
+        yield MessageChunk(...)
+```
+
+```python
+# sdk/agent_api_wrapper.py
+from lambda_agent_api.server import (
+    MsgError,
+    MsgEventCustomUpdate,
+    MsgEventEnd,
+    MsgEventSendFile,
+    MsgEventTextChunk,
+    MsgEventToolCallChunk,
+    MsgEventToolResult,
+    MsgGracefulDisconnect,
+    ServerMessage,
+)
+
+KNOWN_STREAM_EVENTS = (
+    MsgEventTextChunk,
+    MsgEventToolCallChunk,
+    MsgEventToolResult,
+    MsgEventCustomUpdate,
+    MsgEventSendFile,
+    MsgEventEnd,
+)
+
+if isinstance(outgoing_msg, KNOWN_STREAM_EVENTS):
+    if isinstance(outgoing_msg, MsgEventEnd):
+        self.last_tokens_used = outgoing_msg.tokens_used
+    if self._current_queue:
+        await self._current_queue.put(outgoing_msg)
+    elif self.callback:
+        self.callback(outgoing_msg)
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/platform/test_real.py -q`
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add sdk/agent_api_wrapper.py sdk/real.py tests/platform/test_real.py
+git commit -m "feat: support attachment paths and file events in real sdk bridge"
+```
+
+### Task 3: Implement Matrix Shared-Workspace Receive/Send File Flow
+
+**Files:**
+- Create: `adapter/matrix/files.py`
+- Modify: `adapter/matrix/bot.py`
+- Test: `tests/adapter/matrix/test_files.py`
+- Test: `tests/adapter/matrix/test_dispatcher.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/adapter/matrix/test_files.py
+from pathlib import Path
+
+import pytest
+
+from adapter.matrix.files import build_workspace_attachment_path
+
+
+def test_build_workspace_attachment_path_scopes_by_surface_user_and_room(tmp_path):
+    rel_path, abs_path = build_workspace_attachment_path(
+        workspace_root=tmp_path,
+        matrix_user_id="@alice:example.org",
+        room_id="!room:example.org",
+        filename="report.pdf",
+        timestamp="20260420-153000",
+    )
+
+    assert rel_path == "surfaces/matrix/alice_example.org/room_example.org/inbox/20260420-153000-report.pdf"
+    assert abs_path == tmp_path / rel_path
+```
+
+```python
+# tests/adapter/matrix/test_dispatcher.py
+async def test_bot_downloads_matrix_file_to_workspace_before_dispatch(tmp_path):
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "matrix:ctx-1",
+        },
+    )
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        download=AsyncMock(return_value=SimpleNamespace(body=b"%PDF-1.7")),
+    )
+    bot = MatrixBot(client, runtime)
+    bot._send_all = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!chat1:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="Посмотри",
+        msgtype="m.file",
+        url="mxc://server/id",
+        mimetype="application/pdf",
+        replyto_event_id=None,
+    )
+
+    await bot.on_room_message(room, event)
+
+    dispatched = runtime.dispatcher.dispatch.await_args.args[0]
+    assert dispatched.attachments[0].workspace_path.endswith(".pdf")
+```
+
+```python
+# tests/adapter/matrix/test_dispatcher.py
+async def test_send_outgoing_uploads_file_attachment_to_matrix(tmp_path):
+    path = tmp_path / "result.txt"
+    path.write_text("ready")
+    client = SimpleNamespace(
+        upload=AsyncMock(return_value=(SimpleNamespace(content_uri="mxc://server/file"), {})),
+        room_send=AsyncMock(),
+    )
+
+    await send_outgoing(
+        client,
+        "!room:example.org",
+        OutgoingMessage(
+            chat_id="!room:example.org",
+            text="Файл готов",
+            attachments=[
+                Attachment(
+                    type="document",
+                    filename="result.txt",
+                    mime_type="text/plain",
+                    workspace_path=str(path),
+                )
+            ],
+        ),
+    )
+
+    client.upload.assert_awaited()
+    client.room_send.assert_awaited()
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_files.py tests/adapter/matrix/test_dispatcher.py -q`
+
+Expected:
+- FAIL because `adapter.matrix.files` does not exist
+- FAIL because Matrix bot does not persist files before dispatch
+- FAIL because `send_outgoing(...)` only sends text
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/files.py
+from __future__ import annotations
+
+from pathlib import Path
+from datetime import UTC, datetime
+import re
+
+from core.protocol import Attachment
+
+
+def _sanitize_component(value: str) -> str:
+    stripped = re.sub(r"[^A-Za-z0-9._-]+", "_", value)
+    return stripped.strip("._-") or "unknown"
+
+
+def build_workspace_attachment_path(
+    *,
+    workspace_root: Path,
+    matrix_user_id: str,
+    room_id: str,
+    filename: str,
+    timestamp: str | None = None,
+) -> tuple[str, Path]:
+    stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
+    safe_user = _sanitize_component(matrix_user_id.lstrip("@"))
+    safe_room = _sanitize_component(room_id.lstrip("!"))
+    safe_name = _sanitize_component(filename) or "attachment.bin"
+    rel_path = Path("surfaces") / "matrix" / safe_user / safe_room / "inbox" / f"{stamp}-{safe_name}"
+    return rel_path.as_posix(), workspace_root / rel_path
+```
+
+```python
+# adapter/matrix/bot.py
+from adapter.matrix.files import download_matrix_attachments, load_workspace_attachment
+
+...
+incoming = from_room_event(event, room_id=room.room_id, chat_id=dispatch_chat_id)
+if isinstance(incoming, IncomingMessage) and incoming.attachments:
+    incoming = await self._materialize_attachments(room.room_id, sender, incoming)
+...
+
+async def _materialize_attachments(...):
+    workspace_root = Path(os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace"))
+    attachments = await download_matrix_attachments(...)
+    return IncomingMessage(..., attachments=attachments, ...)
+```
+
+```python
+# adapter/matrix/bot.py
+if isinstance(event, OutgoingMessage) and event.attachments:
+    for attachment in event.attachments:
+        if attachment.workspace_path:
+            await _send_matrix_file(client, room_id, attachment)
+    if event.text:
+        await client.room_send(...)
+    return
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_files.py tests/adapter/matrix/test_dispatcher.py -q`
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/files.py adapter/matrix/bot.py tests/adapter/matrix/test_files.py tests/adapter/matrix/test_dispatcher.py
+git commit -m "feat: add matrix shared-workspace file receive and send flow"
+```
+
+### Task 4: Make Shared Workspace the Default Local Runtime
+
+**Files:**
+- Modify: `docker-compose.yml`
+- Modify: `README.md`
+- Modify: `.env.example`
+
+- [ ] **Step 1: Write the failing configuration checks**
+
+```bash
+python - <<'PY'
+from pathlib import Path
+text = Path("docker-compose.yml").read_text()
+assert "platform-agent" in text
+assert "/workspace" in text
+assert "matrix-bot" in text
+PY
+```
+
+```bash
+python - <<'PY'
+from pathlib import Path
+readme = Path("README.md").read_text()
+assert "docker compose up" in readme
+assert "/workspace" in readme
+assert "platform-agent" in readme
+PY
+```
+
+- [ ] **Step 2: Run checks to verify they fail**
+
+Run: `python - <<'PY' ... PY`
+
+Expected:
+- FAIL because root compose only defines `matrix-bot`
+- FAIL because README still documents standalone `uvicorn` launch and old WS route
+
+- [ ] **Step 3: Write minimal implementation**
+
+```yaml
+# docker-compose.yml
+services:
+  platform-agent:
+    build:
+      context: ./external/platform-agent
+      target: development
+      additional_contexts:
+        agent_api: ./external/platform-agent_api
+    env_file:
+      - ./external/platform-agent/.env
+    volumes:
+      - workspace:/workspace
+      - ./external/platform-agent/src:/app/src
+      - ./external/platform-agent_api:/agent_api
+    ports:
+      - "8000:8000"
+
+  matrix-bot:
+    build: .
+    env_file: .env
+    depends_on:
+      - platform-agent
+    volumes:
+      - workspace:/workspace
+    restart: unless-stopped
+
+volumes:
+  workspace:
+```
+
+```env
+# .env.example
+AGENT_WS_URL=ws://platform-agent:8000/v1/agent_ws/0/
+AGENT_BASE_URL=http://platform-agent:8000
+SURFACES_WORKSPACE_DIR=/workspace
+MATRIX_PLATFORM_BACKEND=real
+```
+
+```md
+# README.md
+- make the root `docker compose up` path the primary local runtime
+- describe shared `/workspace` as the file contract
+- remove the statement that real backend is text-only and has no attachments
+- replace the old standalone `uvicorn` instructions with compose-first instructions
+```
+
+- [ ] **Step 4: Run checks to verify they pass**
+
+Run: `python - <<'PY' ... PY`
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docker-compose.yml README.md .env.example
+git commit -m "chore: make shared workspace runtime the default local setup"
+```
+
+## Self-Review
+
+- Spec coverage:
+  - shared `/workspace` runtime: Task 4
+  - incoming Matrix file persistence: Task 3
+  - attachment path propagation to agent API: Tasks 1-2
+  - outbound `send_file` flow: Tasks 2-3
+  - future-surface-friendly attachment contract: Task 1
+- Placeholder scan:
+  - no `TODO`, `TBD`, or “similar to”
+  - each task has explicit test, run, implementation, verify, commit steps
+- Type consistency:
+  - `workspace_path` is introduced in both attachment models and consumed consistently in Tasks 1-3
+  - path-based contract is always relative to `/workspace` until Matrix upload resolution step
+
+## Execution Handoff
+
+User already selected parallel subagent execution. Use subagent-driven development and split ownership like this:
+
+- Worker A: `docker-compose.yml`, `README.md`, `.env.example`
+- Worker B: `sdk/agent_api_wrapper.py`, `sdk/real.py`, `tests/platform/test_real.py`
+- Main session / later worker: `core/protocol.py`, `sdk/interface.py`, `core/handlers/message.py`, `adapter/matrix/files.py`, `adapter/matrix/bot.py`, matrix/core tests

docs/superpowers/plans/2026-04-20-matrix-staged-attachments.md

@@ -0,0 +1,555 @@
+# Matrix Staged Attachments Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add Matrix-side staged attachments so file-only events are stored per `(chat_id, user_id)`, acknowledged in chat, and committed to the agent on the next normal user message.
+
+**Architecture:** Keep the existing shared-workspace file contract unchanged and add a thin Matrix-specific staging layer above it. The Matrix adapter will store staged attachment metadata in `adapter.matrix.store`, parse short staging commands in `adapter.matrix.converter`, and orchestrate commit/remove/list behavior in `adapter.matrix.bot` before calling the existing dispatcher.
+
+**Tech Stack:** Python 3.11, matrix-nio, pytest, pytest-asyncio, in-memory state store, shared `/workspace`
+
+---
+
+## File Structure
+
+- Modify: `adapter/matrix/store.py`
+  Purpose: store staged attachment state per `(room_id, user_id)`.
+- Modify: `adapter/matrix/converter.py`
+  Purpose: parse `!list`, `!remove <n>`, `!remove all` into explicit Matrix-side commands.
+- Modify: `adapter/matrix/bot.py`
+  Purpose: stage file-only events, emit service acknowledgments, process staging commands, and commit staged files with the next normal message.
+- Modify: `tests/adapter/matrix/test_store.py`
+  Purpose: verify staged attachment persistence, ordering, and clear/remove helpers.
+- Modify: `tests/adapter/matrix/test_converter.py`
+  Purpose: verify short staging commands parse correctly.
+- Modify: `tests/adapter/matrix/test_dispatcher.py`
+  Purpose: verify Matrix bot staging, list/remove behavior, and commit semantics.
+- Modify: `README.md`
+  Purpose: document the Matrix staging UX and short commands.
+
+### Task 1: Add Per-Chat Staged Attachment Storage
+
+**Files:**
+- Modify: `adapter/matrix/store.py`
+- Test: `tests/adapter/matrix/test_store.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/adapter/matrix/test_store.py
+from adapter.matrix.store import (
+    add_staged_attachment,
+    clear_staged_attachments,
+    get_staged_attachments,
+    remove_staged_attachment_at,
+)
+
+
+async def test_staged_attachments_roundtrip(store: InMemoryStore):
+    await add_staged_attachment(
+        store,
+        room_id="!r1:example.org",
+        user_id="@alice:example.org",
+        attachment={
+            "filename": "report.pdf",
+            "workspace_path": "surfaces/matrix/alice/r1/inbox/report.pdf",
+            "mime_type": "application/pdf",
+        },
+    )
+
+    assert await get_staged_attachments(store, "!r1:example.org", "@alice:example.org") == [
+        {
+            "filename": "report.pdf",
+            "workspace_path": "surfaces/matrix/alice/r1/inbox/report.pdf",
+            "mime_type": "application/pdf",
+        }
+    ]
+
+
+async def test_staged_attachments_are_scoped_by_room_and_user(store: InMemoryStore):
+    await add_staged_attachment(
+        store,
+        room_id="!r1:example.org",
+        user_id="@alice:example.org",
+        attachment={"filename": "a.pdf", "workspace_path": "a.pdf"},
+    )
+    await add_staged_attachment(
+        store,
+        room_id="!r2:example.org",
+        user_id="@alice:example.org",
+        attachment={"filename": "b.pdf", "workspace_path": "b.pdf"},
+    )
+    await add_staged_attachment(
+        store,
+        room_id="!r1:example.org",
+        user_id="@bob:example.org",
+        attachment={"filename": "c.pdf", "workspace_path": "c.pdf"},
+    )
+
+    assert [item["filename"] for item in await get_staged_attachments(store, "!r1:example.org", "@alice:example.org")] == ["a.pdf"]
+    assert [item["filename"] for item in await get_staged_attachments(store, "!r2:example.org", "@alice:example.org")] == ["b.pdf"]
+    assert [item["filename"] for item in await get_staged_attachments(store, "!r1:example.org", "@bob:example.org")] == ["c.pdf"]
+
+
+async def test_remove_staged_attachment_by_index(store: InMemoryStore):
+    await add_staged_attachment(store, "!r1:example.org", "@alice:example.org", {"filename": "a.pdf", "workspace_path": "a.pdf"})
+    await add_staged_attachment(store, "!r1:example.org", "@alice:example.org", {"filename": "b.pdf", "workspace_path": "b.pdf"})
+
+    removed = await remove_staged_attachment_at(store, "!r1:example.org", "@alice:example.org", 1)
+
+    assert removed["filename"] == "b.pdf"
+    assert [item["filename"] for item in await get_staged_attachments(store, "!r1:example.org", "@alice:example.org")] == ["a.pdf"]
+
+
+async def test_clear_staged_attachments(store: InMemoryStore):
+    await add_staged_attachment(store, "!r1:example.org", "@alice:example.org", {"filename": "a.pdf", "workspace_path": "a.pdf"})
+
+    await clear_staged_attachments(store, "!r1:example.org", "@alice:example.org")
+
+    assert await get_staged_attachments(store, "!r1:example.org", "@alice:example.org") == []
+```
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_store.py -q`
+
+Expected:
+- FAIL because staged attachment helper functions do not exist yet
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/store.py
+STAGED_ATTACHMENTS_PREFIX = "matrix_staged_attachments:"
+
+
+def _staged_attachments_key(room_id: str, user_id: str) -> str:
+    return f"{STAGED_ATTACHMENTS_PREFIX}{room_id}:{user_id}"
+
+
+async def get_staged_attachments(store: StateStore, room_id: str, user_id: str) -> list[dict]:
+    return list(await store.get(_staged_attachments_key(room_id, user_id)) or [])
+
+
+async def add_staged_attachment(
+    store: StateStore,
+    room_id: str,
+    user_id: str,
+    attachment: dict,
+) -> None:
+    items = await get_staged_attachments(store, room_id, user_id)
+    items.append(attachment)
+    await store.set(_staged_attachments_key(room_id, user_id), items)
+
+
+async def remove_staged_attachment_at(
+    store: StateStore,
+    room_id: str,
+    user_id: str,
+    index: int,
+) -> dict | None:
+    items = await get_staged_attachments(store, room_id, user_id)
+    if index < 0 or index >= len(items):
+        return None
+    removed = items.pop(index)
+    await store.set(_staged_attachments_key(room_id, user_id), items)
+    return removed
+
+
+async def clear_staged_attachments(store: StateStore, room_id: str, user_id: str) -> None:
+    await store.delete(_staged_attachments_key(room_id, user_id))
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_store.py -q`
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/store.py tests/adapter/matrix/test_store.py
+git commit -m "feat: add matrix staged attachment state"
+```
+
+### Task 2: Parse Short Staging Commands
+
+**Files:**
+- Modify: `adapter/matrix/converter.py`
+- Test: `tests/adapter/matrix/test_converter.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/adapter/matrix/test_converter.py
+async def test_list_command_maps_to_matrix_staging_command():
+    result = from_room_event(text_event("!list"), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingCommand)
+    assert result.command == "matrix_list_attachments"
+    assert result.args == []
+
+
+async def test_remove_all_maps_to_matrix_staging_command():
+    result = from_room_event(text_event("!remove all"), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingCommand)
+    assert result.command == "matrix_remove_attachment"
+    assert result.args == ["all"]
+
+
+async def test_remove_index_maps_to_matrix_staging_command():
+    result = from_room_event(text_event("!remove 2"), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingCommand)
+    assert result.command == "matrix_remove_attachment"
+    assert result.args == ["2"]
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_converter.py -q`
+
+Expected:
+- FAIL because `!list` and `!remove` still parse as generic unknown commands
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/converter.py
+def from_command(body: str, sender: str, chat_id: str, room_id: str | None = None) -> IncomingEvent:
+    raw = body.lstrip("!").strip()
+    parts = raw.split()
+    command = parts[0].lower() if parts else ""
+    args = parts[1:]
+
+    if command == "list":
+        return IncomingCommand(
+            user_id=sender,
+            platform=PLATFORM,
+            chat_id=chat_id,
+            command="matrix_list_attachments",
+            args=[],
+        )
+
+    if command == "remove":
+        return IncomingCommand(
+            user_id=sender,
+            platform=PLATFORM,
+            chat_id=chat_id,
+            command="matrix_remove_attachment",
+            args=args,
+        )
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_converter.py -q`
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/converter.py tests/adapter/matrix/test_converter.py
+git commit -m "feat: parse matrix staged attachment commands"
+```
+
+### Task 3: Stage File-Only Events and Handle List/Remove UX
+
+**Files:**
+- Modify: `adapter/matrix/bot.py`
+- Modify: `adapter/matrix/store.py`
+- Test: `tests/adapter/matrix/test_dispatcher.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/adapter/matrix/test_dispatcher.py
+async def test_file_only_event_is_staged_and_does_not_dispatch():
+    runtime = build_runtime(platform=MockPlatformClient())
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    bot._materialize_incoming_attachments = AsyncMock(
+        return_value=IncomingMessage(
+            user_id="@alice:example.org",
+            platform="matrix",
+            chat_id="matrix:!r:example.org",
+            text="",
+            attachments=[
+                Attachment(
+                    type="document",
+                    filename="report.pdf",
+                    workspace_path="surfaces/matrix/alice/r/inbox/report.pdf",
+                    mime_type="application/pdf",
+                )
+            ],
+        )
+    )
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="report.pdf",
+        msgtype="m.file",
+        url="mxc://hs/id",
+        mimetype="application/pdf",
+        replyto_event_id=None,
+    )
+
+    await bot.on_room_message(room, event)
+
+    runtime.dispatcher.dispatch.assert_not_awaited()
+    staged = await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org")
+    assert [item["filename"] for item in staged] == ["report.pdf"]
+    client.room_send.assert_awaited_once()
+    assert "Следующее сообщение" in client.room_send.await_args.args[2]["body"]
+
+
+async def test_list_command_returns_current_staged_attachments():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(runtime.store, "!r:example.org", "@alice:example.org", {"filename": "a.pdf", "workspace_path": "a.pdf"})
+    await add_staged_attachment(runtime.store, "!r:example.org", "@alice:example.org", {"filename": "b.pdf", "workspace_path": "b.pdf"})
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="!list", msgtype="m.text", replyto_event_id=None)
+
+    await bot.on_room_message(room, event)
+
+    body = client.room_send.await_args.args[2]["body"]
+    assert "1. a.pdf" in body
+    assert "2. b.pdf" in body
+
+
+async def test_remove_invalid_index_returns_short_error():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(runtime.store, "!r:example.org", "@alice:example.org", {"filename": "a.pdf", "workspace_path": "a.pdf"})
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="!remove 9", msgtype="m.text", replyto_event_id=None)
+
+    await bot.on_room_message(room, event)
+
+    assert client.room_send.await_args.args[2]["body"] == "Нет такого вложения."
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_dispatcher.py -q`
+
+Expected:
+- FAIL because file-only events still go straight to dispatcher
+- FAIL because `!list` and `!remove` have no Matrix-side handling in the bot
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/bot.py
+def _is_staging_command(self, incoming: IncomingEvent) -> bool:
+    return isinstance(incoming, IncomingCommand) and incoming.command in {
+        "matrix_list_attachments",
+        "matrix_remove_attachment",
+    }
+
+
+async def _handle_staging_command(self, room_id: str, user_id: str, incoming: IncomingCommand) -> list[OutgoingMessage]:
+    if incoming.command == "matrix_list_attachments":
+        return [OutgoingMessage(chat_id=incoming.chat_id, text=self._format_staged_attachments(room_id, user_id))]
+    if incoming.command == "matrix_remove_attachment" and incoming.args == ["all"]:
+        await clear_staged_attachments(self.runtime.store, room_id, user_id)
+        return [OutgoingMessage(chat_id=incoming.chat_id, text="Вложения очищены.")]
+```
+
+```python
+# adapter/matrix/bot.py
+if isinstance(incoming, IncomingMessage) and incoming.attachments and not incoming.text:
+    incoming = await self._materialize_incoming_attachments(room.room_id, sender, incoming)
+    await self._stage_attachments(room.room_id, sender, incoming.attachments)
+    await self._send_all(room.room_id, [OutgoingMessage(chat_id=dispatch_chat_id, text=self._format_staged_attachments(room.room_id, sender, with_hint=True))])
+    return
+
+if self._is_staging_command(incoming):
+    outgoing = await self._handle_staging_command(room.room_id, sender, incoming)
+    await self._send_all(room.room_id, outgoing)
+    return
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_dispatcher.py -q`
+
+Expected: PASS for staging/list/remove behavior
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/bot.py adapter/matrix/store.py tests/adapter/matrix/test_dispatcher.py
+git commit -m "feat: add matrix staging list and remove flow"
+```
+
+### Task 4: Commit Staged Files With the Next Normal Message
+
+**Files:**
+- Modify: `adapter/matrix/bot.py`
+- Test: `tests/adapter/matrix/test_dispatcher.py`
+- Modify: `README.md`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/adapter/matrix/test_dispatcher.py
+async def test_next_normal_message_commits_staged_attachments():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {
+            "filename": "report.pdf",
+            "workspace_path": "surfaces/matrix/alice/r/inbox/report.pdf",
+            "mime_type": "application/pdf",
+        },
+    )
+    client = SimpleNamespace(user_id="@bot:example.org")
+    bot = MatrixBot(client, runtime)
+    bot._send_all = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="Проанализируй", msgtype="m.text", replyto_event_id=None)
+
+    await bot.on_room_message(room, event)
+
+    dispatched = runtime.dispatcher.dispatch.await_args.args[0]
+    assert isinstance(dispatched, IncomingMessage)
+    assert dispatched.text == "Проанализируй"
+    assert [a.workspace_path for a in dispatched.attachments] == [
+        "surfaces/matrix/alice/r/inbox/report.pdf"
+    ]
+    assert await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org") == []
+
+
+async def test_failed_commit_preserves_staged_attachments():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {"filename": "report.pdf", "workspace_path": "surfaces/matrix/alice/r/inbox/report.pdf"},
+    )
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(side_effect=PlatformError("boom"))
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="Проанализируй", msgtype="m.text", replyto_event_id=None)
+
+    await bot.on_room_message(room, event)
+
+    staged = await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org")
+    assert [item["filename"] for item in staged] == ["report.pdf"]
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_dispatcher.py -q`
+
+Expected:
+- FAIL because normal text messages do not yet merge staged attachments
+- FAIL because staged items are never preserved/cleared based on commit outcome
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# adapter/matrix/bot.py
+async def _merge_staged_attachments(
+    self,
+    room_id: str,
+    user_id: str,
+    incoming: IncomingMessage,
+) -> IncomingMessage:
+    staged = await get_staged_attachments(self.runtime.store, room_id, user_id)
+    if not staged:
+        return incoming
+    return IncomingMessage(
+        user_id=incoming.user_id,
+        platform=incoming.platform,
+        chat_id=incoming.chat_id,
+        text=incoming.text,
+        reply_to=incoming.reply_to,
+        attachments=[
+            Attachment(
+                type="document",
+                filename=item.get("filename"),
+                mime_type=item.get("mime_type"),
+                workspace_path=item.get("workspace_path"),
+            )
+            for item in staged
+        ],
+    )
+```
+
+```python
+# adapter/matrix/bot.py
+staged_before_dispatch = False
+if isinstance(incoming, IncomingMessage) and incoming.text and not incoming.attachments:
+    staged = await get_staged_attachments(self.runtime.store, room.room_id, sender)
+    if staged:
+        incoming = await self._merge_staged_attachments(room.room_id, sender, incoming)
+        staged_before_dispatch = True
+
+try:
+    outgoing = await self.runtime.dispatcher.dispatch(incoming)
+except PlatformError:
+    ...
+else:
+    if staged_before_dispatch:
+        await clear_staged_attachments(self.runtime.store, room.room_id, sender)
+```
+
+- [ ] **Step 4: Run targeted tests to verify they pass**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_store.py tests/adapter/matrix/test_converter.py tests/adapter/matrix/test_dispatcher.py -q`
+
+Expected: PASS
+
+- [ ] **Step 5: Update docs**
+
+Add to `README.md`:
+
+```md
+### Matrix staged attachments
+
+If a Matrix user sends files without a text instruction, the bot stages them per chat and replies with the current list.
+
+- `!list` shows staged files
+- `!remove <n>` removes one staged file by index
+- `!remove all` clears all staged files
+
+The next normal user message is sent to the agent together with all staged files.
+```
+
+- [ ] **Step 6: Run broader verification**
+
+Run: `PYTHONPATH=. uv run pytest tests/adapter/matrix/test_store.py tests/adapter/matrix/test_converter.py tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_files.py tests/adapter/matrix/test_send_outgoing.py tests/core/test_integration.py tests/platform/test_real.py -q`
+
+Expected: PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add adapter/matrix/bot.py README.md tests/adapter/matrix/test_store.py tests/adapter/matrix/test_converter.py tests/adapter/matrix/test_dispatcher.py
+git commit -m "feat: commit staged matrix attachments on next message"
+```
+
+## Self-Review
+
+- Spec coverage:
+  - staged per `(chat_id, user_id)`: Task 1
+  - short commands `!list`, `!remove <n>`, `!remove all`: Task 2 and Task 3
+  - file-only events do not invoke agent: Task 3
+  - next normal message commits staged attachments: Task 4
+  - failed commit preserves staged attachments: Task 4
+  - docs update: Task 4
+- Placeholder scan:
+  - no `TODO`, `TBD`, or deferred behavior left in task steps
+- Type consistency:
+  - staged storage uses `dict` records with `filename`, `workspace_path`, `mime_type`
+  - bot reconstructs `core.protocol.Attachment` from those same keys

docs/superpowers/plans/2026-04-22-transport-layer-thin-adapter.md

@@ -0,0 +1,540 @@
+# Transport Layer Thin Adapter Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the current custom transport behavior with a thin upstream-compatible adapter so Matrix uses `platform-agent_api.AgentApi` almost as-is and keeps only integration concerns on the `surfaces` side.
+
+**Architecture:** Keep a tiny `AgentApiWrapper` only as a construction/factory shim (`base_url` normalization + `for_chat(chat_id)`). Move all resilience logic that still belongs to `surfaces` into `RealPlatformClient`: per-chat client caching, per-chat send locks, disconnect-on-failure, and `PlatformError` mapping. Delete all custom stream semantics from the wrapper so bugs in streaming can be attributed cleanly to either upstream or our integration layer.
+
+**Tech Stack:** Python 3.11, `aiohttp`, upstream `lambda_agent_api`, `pytest`, `pytest-asyncio`, `ruff`
+
+---
+
+## File Structure
+
+- Modify: `sdk/agent_api_wrapper.py`
+  Purpose: shrink the wrapper to a thin constructor/factory shim with no custom `_listen()` or `send_message()` logic.
+- Modify: `sdk/real.py`
+  Purpose: keep integration-only behavior: cached per-chat clients, chat locks, attachment forwarding, and failure cleanup.
+- Modify: `adapter/matrix/bot.py`
+  Purpose: instantiate the wrapper with the modern `base_url` path instead of a raw `url`, matching the pinned upstream API.
+- Modify: `tests/platform/test_real.py`
+  Purpose: remove tests that encode custom wrapper semantics and replace them with tests that prove only the intended integration guarantees.
+- Modify: `README.md`
+  Purpose: document that the transport layer now uses the pinned upstream `platform-agent_api` client semantics directly, with only a thin local adapter.
+
+### Task 1: Shrink `AgentApiWrapper` To A Thin Factory Shim
+
+**Files:**
+- Modify: `sdk/agent_api_wrapper.py`
+- Test: `tests/platform/test_real.py`
+
+- [ ] **Step 1: Replace wrapper-only behavior tests with thin-wrapper tests**
+
+Update `tests/platform/test_real.py` so it no longer asserts any custom post-END drain or wrapper-owned timeout behavior. Replace those tests with the following:
+
+```python
+def test_agent_api_wrapper_normalizes_base_url_and_uses_modern_constructor(monkeypatch):
+    captured = {}
+
+    def fake_init(self, agent_id, base_url=None, chat_id=0, **kwargs):
+        captured["agent_id"] = agent_id
+        captured["base_url"] = base_url
+        captured["chat_id"] = chat_id
+
+    monkeypatch.setattr(agent_api_wrapper_module.AgentApi, "__init__", fake_init)
+
+    wrapper = AgentApiWrapper(
+        agent_id="agent-1",
+        base_url="ws://platform-agent:8000/v1/agent_ws/",
+        chat_id="41",
+    )
+
+    assert wrapper.chat_id == "41"
+    assert wrapper._base_url == "ws://platform-agent:8000"
+    assert captured == {
+        "agent_id": "agent-1",
+        "base_url": "ws://platform-agent:8000",
+        "chat_id": "41",
+    }
+
+
+def test_agent_api_wrapper_for_chat_reuses_normalized_base_url(monkeypatch):
+    init_calls = []
+
+    def fake_init(self, agent_id, base_url=None, chat_id=0, **kwargs):
+        self.id = agent_id
+        self.chat_id = chat_id
+        self.url = base_url
+        init_calls.append((agent_id, base_url, chat_id))
+
+    monkeypatch.setattr(agent_api_wrapper_module.AgentApi, "__init__", fake_init)
+
+    root = AgentApiWrapper(
+        agent_id="agent-1",
+        base_url="http://platform-agent:8000/v1/agent_ws/",
+        chat_id="1",
+    )
+
+    child = root.for_chat("99")
+
+    assert child is not root
+    assert child.chat_id == "99"
+    assert child._base_url == "http://platform-agent:8000"
+    assert init_calls == [
+        ("agent-1", "http://platform-agent:8000", "1"),
+        ("agent-1", "http://platform-agent:8000", "99"),
+    ]
+```
+
+- [ ] **Step 2: Run tests to verify old assumptions fail**
+
+Run:
+
+```bash
+/bin/zsh -lc 'PYTHONPATH=.:external/platform-agent_api uv run pytest tests/platform/test_real.py -q -k "recovers_late_text_after_first_end or times_out_on_idle_stream or normalizes_base_url_and_uses_modern_constructor or for_chat_reuses_normalized_base_url"'
+```
+
+Expected:
+
+- FAIL because the old wrapper-behavior tests still exist
+- FAIL or SKIP for the new thin-wrapper tests until code/tests are aligned
+
+- [ ] **Step 3: Replace `sdk/agent_api_wrapper.py` with a thin wrapper**
+
+Rewrite `sdk/agent_api_wrapper.py` to the minimal implementation below:
+
+```python
+from __future__ import annotations
+
+import inspect
+import re
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+_api_root = Path(__file__).resolve().parents[1] / "external" / "platform-agent_api"
+if str(_api_root) not in sys.path:
+    sys.path.insert(0, str(_api_root))
+
+from lambda_agent_api.agent_api import AgentApi  # noqa: E402
+
+
+class AgentApiWrapper(AgentApi):
+    """Thin construction/factory shim over the pinned upstream AgentApi."""
+
+    def __init__(
+        self,
+        agent_id: str,
+        base_url: str,
+        *,
+        chat_id: int | str = 0,
+        **kwargs,
+    ) -> None:
+        self._base_url = self._normalize_base_url(base_url)
+        self._init_kwargs = dict(kwargs)
+        self.chat_id = chat_id
+        if not self._supports_modern_constructor():
+            raise RuntimeError("Pinned platform-agent_api is expected to support base_url + chat_id")
+
+        super().__init__(
+            agent_id=agent_id,
+            base_url=self._base_url,
+            chat_id=chat_id,
+            **kwargs,
+        )
+
+    @staticmethod
+    def _supports_modern_constructor() -> bool:
+        try:
+            parameters = inspect.signature(AgentApi.__init__).parameters
+        except (TypeError, ValueError):
+            return False
+        return "base_url" in parameters and "chat_id" in parameters
+
+    @staticmethod
+    def _normalize_base_url(base_url: str) -> str:
+        parsed = urlsplit(base_url)
+        path = re.sub(r"(?:/v1)?/agent_ws(?:/[^/]+)?/?$", "", parsed.path.rstrip("/"))
+        return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+    def for_chat(self, chat_id: int | str) -> "AgentApiWrapper":
+        return type(self)(
+            agent_id=self.id,
+            base_url=self._base_url,
+            chat_id=chat_id,
+            **self._init_kwargs,
+        )
+```
+
+- [ ] **Step 4: Run the wrapper-focused tests**
+
+Run:
+
+```bash
+/bin/zsh -lc 'PYTHONPATH=.:external/platform-agent_api uv run pytest tests/platform/test_real.py -q -k "normalizes_base_url_and_uses_modern_constructor or for_chat_reuses_normalized_base_url"'
+```
+
+Expected:
+
+- PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add sdk/agent_api_wrapper.py tests/platform/test_real.py
+git commit -m "refactor: shrink agent api wrapper to thin adapter"
+```
+
+### Task 2: Simplify `RealPlatformClient` To The Pinned Modern API
+
+**Files:**
+- Modify: `sdk/real.py`
+- Modify: `adapter/matrix/bot.py`
+- Test: `tests/platform/test_real.py`
+
+- [ ] **Step 1: Add failing integration tests for the desired thin-adapter contract**
+
+Extend `tests/platform/test_real.py` with these assertions:
+
+```python
+@pytest.mark.asyncio
+async def test_real_platform_client_passes_attachments_to_modern_send_message():
+    agent_api = FakeAgentApiFactory()
+    client = RealPlatformClient(
+        agent_api=agent_api,
+        prototype_state=PrototypeStateStore(),
+        platform="matrix",
+    )
+
+    attachment = Attachment(
+        type="document",
+        filename="report.pdf",
+        mime_type="application/pdf",
+        workspace_path="surfaces/matrix/u1/r1/inbox/report.pdf",
+    )
+
+    result = await client.send_message(
+        "@alice:example.org",
+        "chat-1",
+        "read this",
+        attachments=[attachment],
+    )
+
+    assert result.response == "read this"
+    assert agent_api.instances["chat-1"].calls == [
+        ("read this", ["surfaces/matrix/u1/r1/inbox/report.pdf"])
+    ]
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_disconnects_chat_after_agent_exception():
+    class ErroringChatAgentApi:
+        def __init__(self, chat_id: str) -> None:
+            self.chat_id = chat_id
+            self.connect_calls = 0
+            self.close_calls = 0
+
+        async def connect(self) -> None:
+            self.connect_calls += 1
+
+        async def close(self) -> None:
+            self.close_calls += 1
+
+        async def send_message(self, text: str, attachments: list[str] | None = None):
+            raise agent_api_wrapper_module.AgentException("INTERNAL_ERROR", "boom")
+            yield
+
+    agent_api = FakeAgentApiFactory()
+    erroring = ErroringChatAgentApi("chat-1")
+    agent_api.for_chat = lambda chat_id: erroring
+    client = RealPlatformClient(
+        agent_api=agent_api,
+        prototype_state=PrototypeStateStore(),
+        platform="matrix",
+    )
+
+    with pytest.raises(PlatformError, match="boom") as exc_info:
+        await client.send_message("@alice:example.org", "chat-1", "hello")
+
+    assert exc_info.value.code == "INTERNAL_ERROR"
+    assert erroring.close_calls == 1
+    assert "chat-1" not in client._chat_apis
+```
+
+- [ ] **Step 2: Run tests to verify they fail before simplification**
+
+Run:
+
+```bash
+/bin/zsh -lc 'PYTHONPATH=.:external/platform-agent_api uv run pytest tests/platform/test_real.py -q -k "passes_attachments_to_modern_send_message or disconnects_chat_after_agent_exception"'
+```
+
+Expected:
+
+- FAIL until `sdk/real.py` and Matrix runtime wiring are aligned with the pinned modern API
+
+- [ ] **Step 3: Simplify `sdk/real.py` and Matrix runtime construction**
+
+Make these exact edits:
+
+```python
+# adapter/matrix/bot.py
+def _build_platform_from_env() -> PlatformClient:
+    backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower()
+    if backend == "real":
+        base_url = os.environ["AGENT_BASE_URL"]
+        return RealPlatformClient(
+            agent_api=AgentApiWrapper(agent_id="matrix-bot", base_url=base_url),
+            prototype_state=PrototypeStateStore(),
+            platform="matrix",
+        )
+    return MockPlatformClient()
+```
+
+```python
+# sdk/real.py
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+from sdk.agent_api_wrapper import AgentApiWrapper
+from sdk.interface import (
+    Attachment,
+    MessageChunk,
+    MessageResponse,
+    PlatformClient,
+    PlatformError,
+    User,
+    UserSettings,
+)
+from sdk.prototype_state import PrototypeStateStore
+
+
+class RealPlatformClient(PlatformClient):
+    def __init__(
+        self,
+        agent_api: AgentApiWrapper,
+        prototype_state: PrototypeStateStore,
+        platform: str = "matrix",
+    ) -> None:
+        self._agent_api = agent_api
+        self._prototype_state = prototype_state
+        self._platform = platform
+        self._chat_apis: dict[str, AgentApiWrapper] = {}
+        self._chat_api_lock = asyncio.Lock()
+        self._chat_send_locks: dict[str, asyncio.Lock] = {}
+
+    @property
+    def agent_api(self) -> AgentApiWrapper:
+        return self._agent_api
+
+    async def _get_chat_api(self, chat_id: str) -> AgentApiWrapper:
+        chat_key = str(chat_id)
+        chat_api = self._chat_apis.get(chat_key)
+        if chat_api is None:
+            async with self._chat_api_lock:
+                chat_api = self._chat_apis.get(chat_key)
+                if chat_api is None:
+                    chat_api = self._agent_api.for_chat(chat_key)
+                    await chat_api.connect()
+                    self._chat_apis[chat_key] = chat_api
+        return chat_api
+
+    def _get_chat_send_lock(self, chat_id: str) -> asyncio.Lock:
+        chat_key = str(chat_id)
+        lock = self._chat_send_locks.get(chat_key)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._chat_send_locks[chat_key] = lock
+        return lock
+
+    async def send_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> MessageResponse:
+        response_parts: list[str] = []
+        tokens_used = 0
+        sent_attachments: list[Attachment] = []
+        message_id = user_id
+
+        lock = self._get_chat_send_lock(chat_id)
+        async with lock:
+            chat_api = await self._get_chat_api(chat_id)
+            try:
+                async for event in chat_api.send_message(text, attachments=self._attachment_paths(attachments)):
+                    if hasattr(event, "text"):
+                        response_parts.append(event.text)
+                    elif event.__class__.__name__ == "MsgEventEnd":
+                        tokens_used = getattr(event, "tokens_used", 0)
+                    elif "SEND_FILE" in getattr(getattr(event, "type", None), "value", str(getattr(event, "type", ""))):
+                        attachment = self._attachment_from_send_file_event(event)
+                        if attachment is not None:
+                            sent_attachments.append(attachment)
+            except Exception as exc:
+                await self._handle_chat_api_failure(chat_id, exc)
+
+            await self._prototype_state.set_last_tokens_used(str(chat_id), tokens_used)
+
+        return MessageResponse(
+            message_id=message_id,
+            response="".join(response_parts),
+            tokens_used=tokens_used,
+            finished=True,
+            attachments=sent_attachments,
+        )
+
+    async def stream_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> AsyncIterator[MessageChunk]:
+        lock = self._get_chat_send_lock(chat_id)
+        async with lock:
+            chat_api = await self._get_chat_api(chat_id)
+            try:
+                async for event in chat_api.send_message(text, attachments=self._attachment_paths(attachments)):
+                    if hasattr(event, "text"):
+                        yield MessageChunk(
+                            message_id=user_id,
+                            delta=event.text,
+                            finished=False,
+                        )
+                    elif event.__class__.__name__ == "MsgEventEnd":
+                        tokens_used = getattr(event, "tokens_used", 0)
+                        await self._prototype_state.set_last_tokens_used(str(chat_id), tokens_used)
+                        yield MessageChunk(
+                            message_id=user_id,
+                            delta="",
+                            finished=True,
+                            tokens_used=tokens_used,
+                        )
+            except Exception as exc:
+                await self._handle_chat_api_failure(chat_id, exc)
+
+    async def disconnect_chat(self, chat_id: str) -> None:
+        chat_key = str(chat_id)
+        chat_api = self._chat_apis.pop(chat_key, None)
+        self._chat_send_locks.pop(chat_key, None)
+        if chat_api is not None:
+            await chat_api.close()
+
+    async def close(self) -> None:
+        for chat_api in list(self._chat_apis.values()):
+            await chat_api.close()
+        self._chat_apis.clear()
+        self._chat_send_locks.clear()
+
+    async def _handle_chat_api_failure(self, chat_id: str, exc: Exception) -> None:
+        await self.disconnect_chat(chat_id)
+        code = getattr(exc, "code", None) or "PLATFORM_CONNECTION_ERROR"
+        raise PlatformError(str(exc), code=code) from exc
+
+    @staticmethod
+    def _attachment_paths(attachments: list[Attachment] | None) -> list[str]:
+        if not attachments:
+            return []
+        return [attachment.workspace_path for attachment in attachments if attachment.workspace_path]
+```
+
+- [ ] **Step 4: Run the focused transport tests**
+
+Run:
+
+```bash
+/bin/zsh -lc 'PYTHONPATH=.:external/platform-agent_api uv run pytest tests/platform/test_real.py -q -k "passes_attachments_to_modern_send_message or disconnects_chat_after_agent_exception or wraps_connection_closed_as_platform_error or reconnects_after_closed_chat_api"'
+```
+
+Expected:
+
+- PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/bot.py sdk/real.py tests/platform/test_real.py
+git commit -m "refactor: use upstream transport semantics in real client"
+```
+
+### Task 3: Remove Custom Transport Assumptions From Tests And Docs
+
+**Files:**
+- Modify: `tests/platform/test_real.py`
+- Modify: `README.md`
+
+- [ ] **Step 1: Delete tests that encode wrapper-owned stream semantics**
+
+Remove any tests that assert:
+
+- late text is recovered after the first `END`
+- duplicate `END` is repaired inside our wrapper
+- wrapper-owned idle timeout semantics
+
+The file should keep only tests for:
+
+- wrapper construction/factory behavior
+- per-chat client reuse
+- reconnect/disconnect after failure
+- attachment forwarding
+- per-chat send locking
+
+- [ ] **Step 2: Update README transport description**
+
+Add this text to the Matrix runtime/backend section in `README.md`:
+
+```md
+Transport layer note:
+
+- `surfaces` now uses the pinned upstream `platform-agent_api.AgentApi` stream semantics directly
+- local code keeps only a thin adapter for client construction and per-chat client factories
+- request serialization, disconnect-on-failure, and `PlatformError` mapping remain in `sdk/real.py`
+- `surfaces` no longer performs local post-END stream reconstruction
+```
+
+- [ ] **Step 3: Run the full verification set**
+
+Run:
+
+```bash
+uv run ruff check adapter/matrix sdk tests/platform/test_real.py
+/bin/zsh -lc 'PYTHONPATH=. uv run pytest tests/adapter/matrix -q'
+/bin/zsh -lc 'PYTHONPATH=.:external/platform-agent_api uv run pytest tests/platform/test_real.py -q'
+```
+
+Expected:
+
+- `ruff` reports `All checks passed!`
+- Matrix adapter tests PASS
+- `tests/platform/test_real.py` PASS
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md tests/platform/test_real.py
+git commit -m "test: remove custom transport semantics assumptions"
+```
+
+---
+
+## Self-Review
+
+- Spec coverage:
+  - thin adapter target: covered by Task 1
+  - integration-only `RealPlatformClient`: covered by Task 2
+  - removal of custom stream semantics assumptions: covered by Task 3
+  - re-verification after cleanup: covered by Task 3
+
+- Placeholder scan:
+  - no `TODO`, `TBD`, or deferred implementation placeholders remain in task steps
+
+- Type consistency:
+  - `AgentApiWrapper` remains the construction/factory type used by `RealPlatformClient`
+  - failure mapping still terminates in `PlatformError`
+  - attachment forwarding consistently uses `attachments: list[str]`

docs/superpowers/plans/2026-04-24-matrix-multi-agent-routing-and-restart-state.md

@@ -0,0 +1,855 @@
+# Matrix Multi-Agent Routing And Restart State Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add Matrix multi-agent routing with user agent selection, room-level agent binding, and durable surface state that survives normal restart.
+
+**Architecture:** Keep the shared `PlatformClient` protocol unchanged. Add a Matrix-specific routing facade that translates local Matrix chat identity into `(agent_id, platform_chat_id)` and delegates to one `RealPlatformClient` per configured agent. Persist only durable routing state in the existing SQLite-backed surface store and deliberately drop temporary UX state on restart.
+
+**Tech Stack:** Python 3.11, matrix-nio, structlog, PyYAML, pytest, pytest-asyncio
+
+---
+
+## File Structure
+
+- Create: `adapter/matrix/agent_registry.py`
+  Purpose: load and validate the YAML agent registry used by Matrix runtime.
+- Create: `adapter/matrix/routed_platform.py`
+  Purpose: implement a Matrix-specific `PlatformClient` facade that resolves room bindings and delegates to per-agent `RealPlatformClient` instances.
+- Create: `adapter/matrix/handlers/agent.py`
+  Purpose: implement `!agent` listing and selection behavior.
+- Create: `tests/adapter/matrix/test_agent_registry.py`
+  Purpose: cover YAML loading and registry validation.
+- Create: `tests/adapter/matrix/test_routed_platform.py`
+  Purpose: cover room-target resolution and per-agent delegation without changing the shared protocol.
+- Create: `tests/adapter/matrix/test_agent_handler.py`
+  Purpose: cover `!agent` UX and persistence of `selected_agent_id`.
+- Create: `tests/adapter/matrix/test_restart_persistence.py`
+  Purpose: prove durable user/room state and `PLATFORM_CHAT_SEQ_KEY` survive runtime recreation with SQLite.
+- Create: `config/matrix-agents.example.yaml`
+  Purpose: document the expected agent registry format.
+- Modify: `pyproject.toml`
+  Purpose: add YAML parsing dependency required by the runtime registry loader.
+- Modify: `.env.example`
+  Purpose: document the config path env var for the Matrix agent registry.
+- Modify: `README.md`
+  Purpose: document the new config file, `!agent`, and restart persistence expectations.
+- Modify: `adapter/matrix/store.py`
+  Purpose: add helpers for `selected_agent_id`, room `agent_id`, and explicit sequence persistence semantics.
+- Modify: `adapter/matrix/bot.py`
+  Purpose: load the agent registry, construct the routed platform facade, keep local Matrix chat ids through dispatch, and enforce stale/unbound room behavior before dispatch.
+- Modify: `adapter/matrix/handlers/__init__.py`
+  Purpose: register the new `!agent` command.
+- Modify: `adapter/matrix/handlers/chat.py`
+  Purpose: require a selected agent for `!new` and bind new rooms to that agent.
+- Modify: `adapter/matrix/handlers/context_commands.py`
+  Purpose: keep context commands compatible with local chat ids and routed platform delegation.
+- Modify: `adapter/matrix/handlers/settings.py`
+  Purpose: expose `!agent` in help text.
+- Modify: `tests/adapter/matrix/test_dispatcher.py`
+  Purpose: cover pre-dispatch gating, stale room behavior, and `!new` semantics.
+- Modify: `tests/adapter/matrix/test_context_commands.py`
+  Purpose: keep load/reset/context flows aligned with the routed platform facade.
+
+---
+
+### Task 1: Add The Agent Registry And Configuration Wiring
+
+**Files:**
+- Create: `adapter/matrix/agent_registry.py`
+- Create: `tests/adapter/matrix/test_agent_registry.py`
+- Create: `config/matrix-agents.example.yaml`
+- Modify: `pyproject.toml`
+- Modify: `.env.example`
+- Modify: `README.md`
+
+- [ ] **Step 1: Write the failing registry tests**
+
+```python
+# tests/adapter/matrix/test_agent_registry.py
+from pathlib import Path
+
+import pytest
+
+from adapter.matrix.agent_registry import AgentRegistryError, load_agent_registry
+
+
+def test_load_agent_registry_reads_yaml_entries(tmp_path: Path):
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: Analyst\n"
+        "  - id: agent-2\n"
+        "    label: Research\n",
+        encoding="utf-8",
+    )
+
+    registry = load_agent_registry(path)
+
+    assert [agent.agent_id for agent in registry.agents] == ["agent-1", "agent-2"]
+    assert registry.get("agent-1").label == "Analyst"
+
+
+def test_load_agent_registry_rejects_duplicate_ids(tmp_path: Path):
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: Analyst\n"
+        "  - id: agent-1\n"
+        "    label: Duplicate\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(AgentRegistryError, match="duplicate agent id"):
+        load_agent_registry(path)
+```
+
+- [ ] **Step 2: Run the registry tests to verify they fail**
+
+Run: `uv run pytest tests/adapter/matrix/test_agent_registry.py -q`
+
+Expected: FAIL with `ModuleNotFoundError` or `ImportError` for `adapter.matrix.agent_registry`.
+
+- [ ] **Step 3: Add the YAML dependency and implement the registry loader**
+
+```toml
+# pyproject.toml
+dependencies = [
+    "aiogram>=3.4,<4",
+    "matrix-nio>=0.21",
+    "pydantic>=2.5",
+    "structlog>=24.1",
+    "python-dotenv>=1.0",
+    "httpx>=0.27",
+    "aiohttp>=3.9",
+    "PyYAML>=6.0",
+]
+```
+
+```python
+# adapter/matrix/agent_registry.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+
+class AgentRegistryError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class AgentDefinition:
+    agent_id: str
+    label: str
+
+
+class AgentRegistry:
+    def __init__(self, agents: list[AgentDefinition]) -> None:
+        self.agents = agents
+        self._by_id = {agent.agent_id: agent for agent in agents}
+
+    def get(self, agent_id: str) -> AgentDefinition:
+        try:
+            return self._by_id[agent_id]
+        except KeyError as exc:
+            raise AgentRegistryError(f"unknown agent id: {agent_id}") from exc
+
+
+def load_agent_registry(path: str | Path) -> AgentRegistry:
+    raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+    entries = raw.get("agents")
+    if not isinstance(entries, list) or not entries:
+        raise AgentRegistryError("agents registry must contain a non-empty agents list")
+
+    agents: list[AgentDefinition] = []
+    seen: set[str] = set()
+    for entry in entries:
+        agent_id = str(entry.get("id", "")).strip()
+        label = str(entry.get("label", "")).strip()
+        if not agent_id or not label:
+            raise AgentRegistryError("each agent entry requires id and label")
+        if agent_id in seen:
+            raise AgentRegistryError(f"duplicate agent id: {agent_id}")
+        seen.add(agent_id)
+        agents.append(AgentDefinition(agent_id=agent_id, label=label))
+    return AgentRegistry(agents)
+```
+
+- [ ] **Step 4: Add the example config and runtime wiring docs**
+
+```yaml
+# config/matrix-agents.example.yaml
+agents:
+  - id: agent-1
+    label: Analyst
+  - id: agent-2
+    label: Research
+```
+
+```env
+# .env.example
+MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml
+```
+
+```markdown
+# README.md
+1. Copy `config/matrix-agents.example.yaml` to `config/matrix-agents.yaml`
+2. Set `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml`
+3. Use `!agent` in Matrix to select the active upstream agent
+```
+
+- [ ] **Step 5: Run the registry tests to verify they pass**
+
+Run: `uv run pytest tests/adapter/matrix/test_agent_registry.py -q`
+
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add pyproject.toml .env.example README.md config/matrix-agents.example.yaml adapter/matrix/agent_registry.py tests/adapter/matrix/test_agent_registry.py
+git commit -m "feat: add matrix agent registry loader"
+```
+
+---
+
+### Task 2: Add A Matrix Routing Facade Without Changing `PlatformClient`
+
+**Files:**
+- Create: `adapter/matrix/routed_platform.py`
+- Create: `tests/adapter/matrix/test_routed_platform.py`
+- Modify: `adapter/matrix/bot.py`
+
+- [ ] **Step 1: Write the failing routed-platform tests**
+
+```python
+# tests/adapter/matrix/test_routed_platform.py
+import pytest
+
+from adapter.matrix.routed_platform import RoutedPlatformClient
+from adapter.matrix.store import set_room_meta
+from core.chat import ChatManager
+from core.store import InMemoryStore
+from sdk.interface import MessageResponse
+from sdk.prototype_state import PrototypeStateStore
+
+
+class FakeDelegate:
+    def __init__(self, agent_id: str) -> None:
+        self.agent_id = agent_id
+        self.calls = []
+
+    async def send_message(self, user_id: str, chat_id: str, text: str, attachments=None):
+        self.calls.append((user_id, chat_id, text, attachments))
+        return MessageResponse(
+            message_id=user_id,
+            response=f"{self.agent_id}:{text}",
+            tokens_used=0,
+            finished=True,
+        )
+
+    async def get_or_create_user(self, external_id: str, platform: str, display_name=None):
+        return await PrototypeStateStore().get_or_create_user(external_id, platform, display_name)
+
+    async def get_settings(self, user_id: str):
+        return await PrototypeStateStore().get_settings(user_id)
+
+    async def update_settings(self, user_id: str, action):
+        return None
+
+
+@pytest.mark.asyncio
+async def test_routed_platform_delegates_using_room_agent_and_platform_chat_id():
+    store = InMemoryStore()
+    chat_mgr = ChatManager(None, store)
+    await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org", "Chat 1")
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41", "agent_id": "agent-2"},
+    )
+
+    delegates = {"agent-2": FakeDelegate("agent-2")}
+    platform = RoutedPlatformClient(store=store, chat_mgr=chat_mgr, delegates=delegates)
+
+    response = await platform.send_message("u1", "C1", "hello")
+
+    assert response.response == "agent-2:hello"
+    assert delegates["agent-2"].calls == [("u1", "41", "hello", None)]
+```
+
+- [ ] **Step 2: Run the routed-platform tests to verify they fail**
+
+Run: `uv run pytest tests/adapter/matrix/test_routed_platform.py -q`
+
+Expected: FAIL with `ImportError` for `RoutedPlatformClient`.
+
+- [ ] **Step 3: Implement the routing facade and integrate runtime construction**
+
+```python
+# adapter/matrix/routed_platform.py
+from __future__ import annotations
+
+from sdk.interface import PlatformClient
+
+
+class RoutedPlatformClient(PlatformClient):
+    def __init__(self, store, chat_mgr, delegates: dict[str, PlatformClient]) -> None:
+        self._store = store
+        self._chat_mgr = chat_mgr
+        self._delegates = delegates
+
+    async def _resolve_target(self, user_id: str, local_chat_id: str) -> tuple[PlatformClient, str]:
+        ctx = await self._chat_mgr.get(local_chat_id, user_id=user_id)
+        if ctx is None:
+            raise ValueError(f"Chat {local_chat_id} not found for {user_id}")
+        room_meta = await self._store.get(f"matrix_room:{ctx.surface_ref}")
+        if room_meta is None or not room_meta.get("agent_id") or not room_meta.get("platform_chat_id"):
+            raise ValueError(f"Room {ctx.surface_ref} is not bound to an agent target")
+        delegate = self._delegates[room_meta["agent_id"]]
+        return delegate, str(room_meta["platform_chat_id"])
+
+    async def send_message(self, user_id: str, chat_id: str, text: str, attachments=None):
+        delegate, platform_chat_id = await self._resolve_target(user_id, chat_id)
+        return await delegate.send_message(user_id, platform_chat_id, text, attachments)
+
+    async def stream_message(self, user_id: str, chat_id: str, text: str, attachments=None):
+        delegate, platform_chat_id = await self._resolve_target(user_id, chat_id)
+        async for chunk in delegate.stream_message(user_id, platform_chat_id, text, attachments):
+            yield chunk
+
+    async def get_or_create_user(self, external_id: str, platform: str, display_name=None):
+        first_delegate = next(iter(self._delegates.values()))
+        return await first_delegate.get_or_create_user(external_id, platform, display_name)
+
+    async def get_settings(self, user_id: str):
+        first_delegate = next(iter(self._delegates.values()))
+        return await first_delegate.get_settings(user_id)
+
+    async def update_settings(self, user_id: str, action):
+        first_delegate = next(iter(self._delegates.values()))
+        await first_delegate.update_settings(user_id, action)
+```
+
+```python
+# adapter/matrix/bot.py
+from adapter.matrix.agent_registry import load_agent_registry
+from adapter.matrix.routed_platform import RoutedPlatformClient
+
+
+def _build_platform_from_env(store: StateStore, chat_mgr: ChatManager) -> PlatformClient:
+    backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower()
+    if backend != "real":
+        return MockPlatformClient()
+
+    registry = load_agent_registry(os.environ["MATRIX_AGENT_REGISTRY_PATH"])
+    delegates = {
+        agent.agent_id: RealPlatformClient(
+            agent_id=agent.agent_id,
+            agent_base_url=_agent_base_url_from_env(),
+            prototype_state=PrototypeStateStore(),
+            platform="matrix",
+        )
+        for agent in registry.agents
+    }
+    return RoutedPlatformClient(store=store, chat_mgr=chat_mgr, delegates=delegates)
+
+
+def build_runtime(...):
+    store = store or InMemoryStore()
+    chat_mgr = ChatManager(None, store)
+    platform = platform or _build_platform_from_env(store, chat_mgr)
+    auth_mgr = AuthManager(platform, store)
+    settings_mgr = SettingsManager(platform, store)
+    dispatcher = EventDispatcher(
+        platform=platform,
+        chat_mgr=chat_mgr,
+        auth_mgr=auth_mgr,
+        settings_mgr=settings_mgr,
+    )
+```
+
+- [ ] **Step 4: Run the routed-platform tests to verify they pass**
+
+Run: `uv run pytest tests/adapter/matrix/test_routed_platform.py -q`
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add adapter/matrix/routed_platform.py adapter/matrix/bot.py tests/adapter/matrix/test_routed_platform.py
+git commit -m "feat: add matrix routed platform facade"
+```
+
+---
+
+### Task 3: Add `!agent` Selection And Durable User Agent State
+
+**Files:**
+- Create: `adapter/matrix/handlers/agent.py`
+- Create: `tests/adapter/matrix/test_agent_handler.py`
+- Modify: `adapter/matrix/store.py`
+- Modify: `adapter/matrix/handlers/__init__.py`
+- Modify: `adapter/matrix/handlers/settings.py`
+
+- [ ] **Step 1: Write the failing agent-handler tests**
+
+```python
+# tests/adapter/matrix/test_agent_handler.py
+import pytest
+
+from adapter.matrix.handlers.agent import make_handle_agent
+from adapter.matrix.store import get_room_meta, get_selected_agent_id, set_room_meta
+from core.protocol import IncomingCommand
+from core.store import InMemoryStore
+
+
+class FakeRegistry:
+    def __init__(self) -> None:
+        self.agents = [
+            type("Agent", (), {"agent_id": "agent-1", "label": "Analyst"})(),
+            type("Agent", (), {"agent_id": "agent-2", "label": "Research"})(),
+        ]
+
+
+@pytest.mark.asyncio
+async def test_agent_command_lists_available_agents():
+    handler = make_handle_agent(store=InMemoryStore(), registry=FakeRegistry())
+    result = await handler(
+        IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="agent", args=[]),
+        None,
+        None,
+        None,
+        None,
+    )
+    assert "1. Analyst" in result[0].text
+    assert "2. Research" in result[0].text
+
+
+@pytest.mark.asyncio
+async def test_agent_command_persists_selected_agent_and_binds_unbound_room():
+    store = InMemoryStore()
+    await set_room_meta(store, "!room:example.org", {"chat_id": "C1", "matrix_user_id": "u1"})
+    handler = make_handle_agent(store=store, registry=FakeRegistry())
+    chat_mgr = type(
+        "ChatMgr",
+        (),
+        {"get": staticmethod(lambda chat_id, user_id=None: type("Ctx", (), {"surface_ref": "!room:example.org"})())},
+    )()
+
+    await handler(
+        IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="agent", args=["2"]),
+        None,
+        None,
+        chat_mgr,
+        None,
+    )
+
+    assert await get_selected_agent_id(store, "u1") == "agent-2"
+    room_meta = await get_room_meta(store, "!room:example.org")
+    assert room_meta["agent_id"] == "agent-2"
+```
+
+- [ ] **Step 2: Run the agent-handler tests to verify they fail**
+
+Run: `uv run pytest tests/adapter/matrix/test_agent_handler.py -q`
+
+Expected: FAIL with missing handler or store helpers.
+
+- [ ] **Step 3: Add durable store helpers and implement `!agent`**
+
+```python
+# adapter/matrix/store.py
+async def get_selected_agent_id(store: StateStore, matrix_user_id: str) -> str | None:
+    meta = await get_user_meta(store, matrix_user_id) or {}
+    value = meta.get("selected_agent_id")
+    return str(value) if value else None
+
+
+async def set_selected_agent_id(store: StateStore, matrix_user_id: str, agent_id: str) -> None:
+    meta = await get_user_meta(store, matrix_user_id) or {}
+    meta["selected_agent_id"] = agent_id
+    await set_user_meta(store, matrix_user_id, meta)
+
+
+async def set_room_agent_id(store: StateStore, room_id: str, agent_id: str) -> None:
+    meta = dict(await get_room_meta(store, room_id) or {})
+    meta["agent_id"] = agent_id
+    await set_room_meta(store, room_id, meta)
+```
+
+```python
+# adapter/matrix/handlers/agent.py
+from __future__ import annotations
+
+from adapter.matrix.store import (
+    get_room_meta,
+    get_selected_agent_id,
+    next_platform_chat_id,
+    set_platform_chat_id,
+    set_room_agent_id,
+    set_selected_agent_id,
+)
+from core.protocol import IncomingCommand, OutgoingMessage
+
+
+def make_handle_agent(store, registry):
+    async def handle_agent(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr):
+        if not event.args:
+            current = await get_selected_agent_id(store, event.user_id)
+            lines = ["Доступные агенты:"]
+            for index, agent in enumerate(registry.agents, start=1):
+                marker = " (текущий)" if agent.agent_id == current else ""
+                lines.append(f"{index}. {agent.label}{marker}")
+            lines.append("")
+            lines.append("Выбери агента: !agent <номер>")
+            return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))]
+
+        agent = registry.agents[int(event.args[0]) - 1]
+        await set_selected_agent_id(store, event.user_id, agent.agent_id)
+        ctx = await chat_mgr.get(event.chat_id, user_id=event.user_id) if chat_mgr else None
+        if ctx is not None:
+            room_meta = await get_room_meta(store, ctx.surface_ref)
+            if room_meta is not None and not room_meta.get("agent_id"):
+                await set_room_agent_id(store, ctx.surface_ref, agent.agent_id)
+                if not room_meta.get("platform_chat_id"):
+                    await set_platform_chat_id(store, ctx.surface_ref, await next_platform_chat_id(store))
+                return [OutgoingMessage(chat_id=event.chat_id, text=f"Агент переключён на {agent.label}. Этот чат готов к работе.")]
+        return [OutgoingMessage(chat_id=event.chat_id, text=f"Агент переключён на {agent.label}. Для продолжения используй !new.")]
+
+    return handle_agent
+```
+
+- [ ] **Step 4: Register the command and update help text**
+
+```python
+# adapter/matrix/handlers/__init__.py
+from adapter.matrix.handlers.agent import make_handle_agent
+
+dispatcher.register(IncomingCommand, "agent", make_handle_agent(store, registry))
+```
+
+```python
+# adapter/matrix/handlers/settings.py
+HELP_TEXT = "\n".join(
+    [
+        "Команды",
+        "",
+        "!agent  выбрать активного агента",
+        "!new [название]  создать новый чат",
+        "!chats  список активных чатов",
+        "!rename <название>  переименовать текущий чат",
+        "!archive  архивировать текущий чат",
+        "!context  показать текущее состояние контекста",
+        "!save [имя]  сохранить текущий контекст",
+        "!load  показать сохранённые контексты",
+    ]
+)
+```
+
+- [ ] **Step 5: Run the agent-handler tests to verify they pass**
+
+Run: `uv run pytest tests/adapter/matrix/test_agent_handler.py -q`
+
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add adapter/matrix/store.py adapter/matrix/handlers/agent.py adapter/matrix/handlers/__init__.py adapter/matrix/handlers/settings.py tests/adapter/matrix/test_agent_handler.py
+git commit -m "feat: add matrix agent selection command"
+```
+
+---
+
+### Task 4: Bind Rooms Correctly And Block Stale Chats
+
+**Files:**
+- Modify: `adapter/matrix/bot.py`
+- Modify: `adapter/matrix/handlers/chat.py`
+- Modify: `adapter/matrix/handlers/context_commands.py`
+- Modify: `tests/adapter/matrix/test_dispatcher.py`
+- Modify: `tests/adapter/matrix/test_context_commands.py`
+
+- [ ] **Step 1: Write the failing dispatcher and context-command tests**
+
+```python
+# tests/adapter/matrix/test_dispatcher.py
+@pytest.mark.asyncio
+async def test_bot_replies_with_agent_prompt_when_user_has_no_selected_agent():
+    runtime = build_runtime(platform=MockPlatformClient())
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    await set_room_meta(runtime.store, "!room:example.org", {"chat_id": "C1", "matrix_user_id": "@alice:example.org"})
+
+    await bot.on_room_message(SimpleNamespace(room_id="!room:example.org"), SimpleNamespace(sender="@alice:example.org", body="hello"))
+
+    client.room_send.assert_awaited_once()
+    assert "выбери агента" in client.room_send.call_args.args[2]["body"].lower()
+
+
+@pytest.mark.asyncio
+async def test_new_chat_requires_selected_agent_and_binds_room_meta():
+    client = SimpleNamespace(
+        room_create=AsyncMock(return_value=SimpleNamespace(room_id="!r2:example")),
+        room_put_state=AsyncMock(),
+    )
+    runtime = build_runtime(platform=MockPlatformClient(), client=client)
+    await set_user_meta(runtime.store, "u1", {"space_id": "!space:example", "next_chat_index": 2, "selected_agent_id": "agent-2"})
+
+    result = await runtime.dispatcher.dispatch(
+        IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="new", args=["Research"])
+    )
+
+    room_meta = await get_room_meta(runtime.store, "!r2:example")
+    assert room_meta["agent_id"] == "agent-2"
+    assert "Создан чат" in result[0].text
+```
+
+```python
+# tests/adapter/matrix/test_context_commands.py
+@pytest.mark.asyncio
+async def test_load_selection_calls_platform_with_local_chat_id():
+    platform = MatrixCommandPlatform()
+    runtime = build_runtime(platform=platform)
+    await runtime.chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org", "Chat 1")
+    await set_room_meta(runtime.store, "!room:example.org", {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41", "agent_id": "agent-2"})
+
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    await set_load_pending(runtime.store, "u1", "!room:example.org", {"saves": [{"name": "session-a", "created_at": "2026-04-17T00:00:00+00:00"}]})
+
+    await bot.on_room_message(SimpleNamespace(room_id="!room:example.org"), SimpleNamespace(sender="u1", body="1"))
+
+    platform.send_message.assert_awaited_once_with("u1", "C1", LOAD_PROMPT.format(name="session-a"))
+```
+
+- [ ] **Step 2: Run the dispatcher and context-command tests to verify they fail**
+
+Run: `uv run pytest tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py -q`
+
+Expected: FAIL because the current runtime still injects `platform_chat_id` into normal messages and `!new` does not require or persist `agent_id`.
+
+- [ ] **Step 3: Implement room binding and stale-room checks in runtime**
+
+```python
+# adapter/matrix/bot.py
+from adapter.matrix.store import (
+    get_selected_agent_id,
+    get_room_meta,
+    next_platform_chat_id,
+    set_platform_chat_id,
+    set_room_agent_id,
+)
+
+
+async def _ensure_active_room_target(self, room_id: str, user_id: str) -> tuple[dict | None, OutgoingMessage | None]:
+    room_meta = await get_room_meta(self.runtime.store, room_id)
+    selected_agent_id = await get_selected_agent_id(self.runtime.store, user_id)
+    if not selected_agent_id:
+        return room_meta, OutgoingMessage(chat_id=room_id, text="Сначала выбери агента через !agent.")
+    if room_meta is None:
+        return room_meta, None
+    if not room_meta.get("agent_id"):
+        await set_room_agent_id(self.runtime.store, room_id, selected_agent_id)
+        if not room_meta.get("platform_chat_id"):
+            await set_platform_chat_id(self.runtime.store, room_id, await next_platform_chat_id(self.runtime.store))
+        room_meta = await get_room_meta(self.runtime.store, room_id)
+        return room_meta, None
+    if room_meta["agent_id"] != selected_agent_id:
+        return room_meta, OutgoingMessage(chat_id=room_id, text="Этот чат привязан к старому агенту. Используй !new.")
+    return room_meta, None
+```
+
+```python
+# adapter/matrix/bot.py
+local_chat_id = await resolve_chat_id(self.runtime.store, room.room_id, sender)
+dispatch_chat_id = local_chat_id
+
+if not body.startswith("!"):
+    room_meta, blocking = await self._ensure_active_room_target(room.room_id, sender)
+    if blocking is not None:
+        await self._send_all(room.room_id, [blocking])
+        return
+
+incoming = from_room_event(event, room_id=room.room_id, chat_id=dispatch_chat_id)
+```
+
+- [ ] **Step 4: Require selected agent for `!new` and persist room `agent_id`**
+
+```python
+# adapter/matrix/handlers/chat.py
+from adapter.matrix.store import get_selected_agent_id
+
+selected_agent_id = await get_selected_agent_id(store, event.user_id)
+if not selected_agent_id:
+    return [OutgoingMessage(chat_id=event.chat_id, text="Сначала выбери агента через !agent.")]
+
+await set_room_meta(
+    store,
+    room_id,
+    {
+        "room_type": "chat",
+        "chat_id": chat_id,
+        "display_name": room_name,
+        "matrix_user_id": event.user_id,
+        "space_id": space_id,
+        "platform_chat_id": platform_chat_id,
+        "agent_id": selected_agent_id,
+    },
+)
+```
+
+```python
+# adapter/matrix/bot.py
+room_meta = await get_room_meta(self.runtime.store, room_id)
+local_chat_id = room_meta.get("chat_id", room_id) if room_meta else room_id
+
+await self.runtime.platform.send_message(
+    user_id,
+    local_chat_id,
+    LOAD_PROMPT.format(name=name),
+)
+```
+
+- [ ] **Step 5: Run the dispatcher and context-command tests to verify they pass**
+
+Run: `uv run pytest tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py -q`
+
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add adapter/matrix/bot.py adapter/matrix/handlers/chat.py adapter/matrix/handlers/context_commands.py tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py
+git commit -m "feat: bind matrix rooms to selected agents"
+```
+
+---
+
+### Task 5: Prove Durable Restart State And Sequence Persistence
+
+**Files:**
+- Create: `tests/adapter/matrix/test_restart_persistence.py`
+- Modify: `adapter/matrix/store.py`
+- Modify: `README.md`
+
+- [ ] **Step 1: Write the failing restart-persistence tests**
+
+```python
+# tests/adapter/matrix/test_restart_persistence.py
+import pytest
+
+from adapter.matrix.store import (
+    get_selected_agent_id,
+    next_platform_chat_id,
+    set_room_meta,
+    set_selected_agent_id,
+)
+from core.store import SQLiteStore
+
+
+@pytest.mark.asyncio
+async def test_selected_agent_and_room_binding_survive_store_recreation(tmp_path):
+    db_path = tmp_path / "matrix.db"
+    store = SQLiteStore(str(db_path))
+    await set_selected_agent_id(store, "u1", "agent-2")
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41", "agent_id": "agent-2"},
+    )
+
+    reopened = SQLiteStore(str(db_path))
+    assert await get_selected_agent_id(reopened, "u1") == "agent-2"
+    assert (await reopened.get("matrix_room:!room:example.org"))["agent_id"] == "agent-2"
+    assert (await reopened.get("matrix_room:!room:example.org"))["platform_chat_id"] == "41"
+
+
+@pytest.mark.asyncio
+async def test_platform_chat_sequence_survives_store_recreation(tmp_path):
+    db_path = tmp_path / "matrix.db"
+    store = SQLiteStore(str(db_path))
+
+    assert await next_platform_chat_id(store) == "1"
+    assert await next_platform_chat_id(store) == "2"
+
+    reopened = SQLiteStore(str(db_path))
+    assert await next_platform_chat_id(reopened) == "3"
+```
+
+- [ ] **Step 2: Run the restart-persistence tests to verify they fail**
+
+Run: `uv run pytest tests/adapter/matrix/test_restart_persistence.py -q`
+
+Expected: FAIL because `selected_agent_id` helpers do not exist yet or sequence persistence behavior is not explicitly covered.
+
+- [ ] **Step 3: Make sequence persistence explicit and document the restart boundary**
+
+```python
+# adapter/matrix/store.py
+PLATFORM_CHAT_SEQ_KEY = "matrix_platform_chat_seq"
+
+
+async def next_platform_chat_id(store: StateStore) -> str:
+    async with _PLATFORM_CHAT_SEQ_LOCK:
+        data = await store.get(PLATFORM_CHAT_SEQ_KEY)
+        index = int((data or {}).get("next_platform_chat_index", 1))
+        await store.set(PLATFORM_CHAT_SEQ_KEY, {"next_platform_chat_index": index + 1})
+        return str(index)
+```
+
+```markdown
+# README.md
+- Matrix durable state lives in `lambda_matrix.db` and `matrix_store`
+- normal restart is supported only when those paths survive container recreation
+- staged attachments and pending confirmations are intentionally not restored
+```
+
+- [ ] **Step 4: Run the restart-persistence tests to verify they pass**
+
+Run: `uv run pytest tests/adapter/matrix/test_restart_persistence.py -q`
+
+Expected: PASS
+
+- [ ] **Step 5: Run the combined verification sweep**
+
+Run: `uv run pytest tests/adapter/matrix/test_agent_registry.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_agent_handler.py tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_restart_persistence.py tests/platform/test_real.py -q`
+
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add adapter/matrix/store.py README.md tests/adapter/matrix/test_restart_persistence.py
+git commit -m "test: cover matrix restart state persistence"
+```
+
+---
+
+## Self-Review
+
+### Spec coverage
+
+- Multi-agent agent registry: Task 1
+- Shared `PlatformClient` preserved via routing facade: Task 2
+- `!agent` UX and durable `selected_agent_id`: Task 3
+- Unbound room activation, `!new`, stale room rejection: Task 4
+- Restart durability for user state, room state, and `PLATFORM_CHAT_SEQ_KEY`: Task 5
+
+### Placeholder scan
+
+- No `TODO`, `TBD`, or “implement later” markers remain.
+- Each task includes exact file paths, tests, commands, and minimal code snippets.
+
+### Type consistency
+
+- `selected_agent_id` lives in user metadata throughout the plan.
+- `agent_id` and `platform_chat_id` live in room metadata throughout the plan.
+- `RoutedPlatformClient` keeps the existing `PlatformClient` method names intact.

docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md

@@ -0,0 +1,243 @@
+# Matrix Direct-Agent Prototype Design
+
+## Goal
+
+Ship a working Matrix prototype that talks to the real Lambda agent instead of `MockPlatformClient`, while preserving the current Matrix adapter logic and keeping the code expandable toward future platform versions.
+
+## Scope
+
+This design is for a Matrix-only prototype delivered from this repository on a dedicated branch. It is not a `main` branch rollout and it is not a separate prototype repo.
+
+The design assumes a minimal companion fork of `platform/agent` may be used, but changes there must stay as small as possible.
+
+## Constraints
+
+- Preserve the current Matrix transport logic as much as possible.
+- Keep `core/` unaware of platform immaturity.
+- Avoid broad changes to platform repos.
+- Prefer one narrow patch to `platform/agent` over changes to both `platform/agent` and `platform/agent_api`.
+- Keep the backend boundary reusable for future Telegram or other surfaces.
+- Do not pretend unsupported platform capabilities are real.
+
+## Live Platform Findings
+
+Based on the live repo analysis performed on April 7, 2026:
+
+- `platform/master` is not yet a usable consumer-facing backend for surfaces.
+- `platform/agent` exposes a working WebSocket endpoint for prompt/response exchange.
+- `platform/agent_api` documents and implements text-oriented WebSocket messaging, but the bot does not need to depend on that package directly.
+- `platform/agent` currently hardcodes a single shared backend memory thread via `thread_id = "default"`, which would cause all chats to share context.
+
+## Architecture
+
+The prototype remains in this repo and introduces a new real backend path behind the existing SDK boundary.
+
+### New files
+
+- `sdk/real.py`
+  - Exports `RealPlatformClient`
+  - Implements the existing `PlatformClient` contract from `sdk/interface.py`
+  - Composes the lower-level prototype pieces
+
+- `sdk/agent_session.py`
+  - Owns direct WebSocket communication with the real agent
+  - Manages connection lifecycle, request/response handling, and thread identity
+
+- `sdk/prototype_state.py`
+  - Owns local prototype-only state
+  - Stores user mapping, local settings, and lightweight metadata needed until a real control plane exists
+
+### Responsibility split
+
+- Matrix adapter remains transport-specific only.
+- `core/` continues to depend only on `PlatformClient`.
+- `RealPlatformClient` acts as the anti-corruption layer between the current bot contract and the platform’s incomplete shape.
+- Local control-plane behavior remains explicit and replaceable later.
+
+## Message and Identity Model
+
+Each Matrix chat gets a stable backend session identity.
+
+### Surface identity
+
+- Surface: `matrix`
+- Surface user id: Matrix MXID, for example `@alice:example.org`
+- Surface chat id: logical chat id from `ChatManager`, for example `C1`
+- Surface ref: Matrix room id
+
+### Backend thread identity
+
+Use a deterministic thread key:
+
+`matrix:{matrix_user_id}:{chat_id}`
+
+Example:
+
+`matrix:@alice:example.org:C1`
+
+### Mapping rules
+
+- One Matrix logical chat maps to one backend memory thread.
+- `!new` creates a fresh logical chat and therefore a fresh backend thread.
+- `!rename` only changes display metadata and does not change backend identity.
+- `!archive` stops active use of the thread in the surface, but does not need to delete backend memory in v1.
+
+## Runtime Flow
+
+### Normal message flow
+
+1. Matrix event arrives in an existing room.
+2. Existing Matrix routing resolves room to logical `chat_id`.
+3. `core/handlers/message.py` calls `platform.send_message(...)`.
+4. `RealPlatformClient` derives the backend thread key from `(platform, user_id, chat_id)`.
+5. `AgentSessionClient` sends the prompt to the agent WebSocket using that thread key.
+6. The reply is converted into the existing `MessageResponse` or `MessageChunk` contract.
+7. Matrix sends the final text back to the room.
+
+### Settings flow
+
+For v1, settings remain local:
+
+- `get_settings()` reads from local prototype state
+- `update_settings()` writes to local prototype state
+
+This is intentional. The prototype must not claim settings are backed by the real platform when no such platform API exists yet.
+
+## Feature Matrix
+
+### Real in v1
+
+- `!start`
+- Plain text messaging with the real agent
+- Matrix chat lifecycle already implemented in this repo:
+  - `!new`
+  - `!chats`
+  - `!rename`
+  - `!archive`
+- Per-chat conversation memory, provided the agent accepts dynamic thread identity
+
+### Local in v1
+
+- `!settings`
+- `!skills`
+- `!soul`
+- `!safety`
+- `!status`
+- user registration and local user mapping
+
+### Deferred
+
+- Attachments and file upload to the agent
+- Voice input to the agent
+- Image input to the agent
+- Long-running task callbacks and webhook-style async completion
+- Real control-plane integration through `platform/master`
+
+## Minimal Upstream Change
+
+To avoid shared memory across all conversations, make one narrow change in the forked `platform/agent` repo:
+
+- stop hardcoding `thread_id = "default"`
+- derive thread identity from WebSocket connection context
+
+### Preferred mechanism
+
+Read `thread_id` from WebSocket query parameters rather than changing the message payload format.
+
+Example:
+
+`ws://host:port/agent_ws/?thread_id=matrix:@alice:example.org:C1`
+
+This is preferred because:
+
+- it limits the platform patch to one repo
+- it avoids changing both server and SDK protocol shape
+- it keeps the client message body text-only
+- it makes session identity explicit and easy to reason about
+
+## Why Not Use `platform/agent_api` Directly
+
+The bot should not depend on their client package for the prototype.
+
+Reasons:
+
+- the bot already has its own internal integration boundary in `sdk/interface.py`
+- a tiny local WebSocket client is enough for this protocol
+- avoiding a dependency on `platform/agent_api` keeps rebasing simpler
+- if upstream stabilizes later, the bot can adopt their SDK without affecting Matrix handlers
+
+## Repo Strategy
+
+### This repo
+
+Owns:
+
+- Matrix surface logic
+- SDK compatibility layer
+- local prototype state
+- backend selection and wiring
+
+### Forked `platform/agent`
+
+Owns only:
+
+- minimal thread identity patch required for per-chat memory
+
+### Explicitly not doing
+
+- no separate prototype repo
+- no changes to `platform/master` for v1
+- no unnecessary changes to `platform/agent_api`
+
+## Migration Path
+
+This design is intentionally expandable.
+
+When the platform develops further:
+
+- `sdk/prototype_state.py` can be replaced or reduced by a real `MasterClient`
+- `sdk/agent_session.py` can remain the direct session transport if still relevant
+- `RealPlatformClient` can continue to present the stable bot-facing interface
+- Telegram or another surface can reuse the same backend components without rethinking the integration model
+
+## Risks
+
+### Risk: hidden platform assumptions leak upward
+
+Mitigation:
+- keep all direct-agent logic below `RealPlatformClient`
+- avoid changing `core/` contracts for prototype convenience
+
+### Risk: settings semantics drift from future platform reality
+
+Mitigation:
+- make local settings behavior explicit in code and docs
+- keep settings isolated in `sdk/prototype_state.py`
+
+### Risk: upstream `agent` fork diverges
+
+Mitigation:
+- keep the patch minimal and narrowly scoped to thread identity
+
+### Risk: thread identity source is unstable
+
+Mitigation:
+- derive thread key from existing stable bot-side identities: platform, surface user id, logical chat id
+
+## Testing Strategy
+
+- Unit tests for `sdk/agent_session.py` request/response behavior
+- Unit tests for `sdk/prototype_state.py` local settings and user mapping
+- Unit tests for `sdk/real.py` contract compliance with `PlatformClient`
+- Matrix integration tests confirming:
+  - existing commands still work
+  - different logical chats map to different backend thread keys
+  - rename does not change thread identity
+  - archive stops reuse from the surface perspective
+
+## Success Criteria
+
+- Matrix can talk to the real agent without rewriting the Matrix adapter architecture
+- Chats do not share backend memory accidentally
+- Unsupported platform capabilities remain local or deferred rather than being faked as “real”
+- The backend boundary remains suitable for later Telegram or other surfaces

docs/superpowers/specs/2026-04-19-matrix-per-chat-context-design.md

@@ -0,0 +1,278 @@
+# Matrix Per-Chat Context Design
+
+## Goal
+
+Move the Matrix surface from the current shared-agent-context MVP to true per-chat agent contexts using the new platform `chat_id`, while preserving the existing Matrix UX model built around rooms, spaces, and local chat labels such as `C1`, `C2`, and `C3`.
+
+## Core Decision
+
+The Matrix surface remains the owner of user-facing chat organization.
+
+- Matrix rooms, spaces, chat names, and archive state remain surface concerns.
+- The platform agent becomes the owner of actual conversation context.
+- The integration layer stores an explicit mapping from each surface chat to one platform context.
+
+This is the selected "Variant A" architecture:
+
+`surface_chat -> platform_chat_id`
+
+## Why This Decision
+
+The current Matrix adapter already has a stable UX model:
+
+- a user has a space
+- each working room has a local chat id like `C1`
+- commands such as `!new`, `!chats`, `!rename`, and `!archive` operate on that model
+
+Replacing that entire model with platform-native chat ids would be a broader refactor than needed. The surface and the platform solve different problems:
+
+- the surface organizes rooms and commands for users
+- the platform persists and branches real conversation context
+
+Keeping those responsibilities separate lets us add true per-chat context now without rebuilding the Matrix adapter around a new identity model.
+
+## Scope
+
+This design covers:
+
+- true per-chat context for Matrix rooms
+- a new `!branch` command
+- real context-aware semantics for `!new`, `!context`, `!save`, and `!load`
+- lazy migration of legacy Matrix rooms created before platform `chat_id` support
+
+This design does not cover:
+
+- end-to-end Matrix encryption support
+- Telegram changes
+- platform UI for browsing contexts
+- a future unified cross-surface chat browser
+
+## Data Model
+
+### Surface chat identity
+
+The Matrix surface keeps its existing identifiers:
+
+- Matrix room id, for example `!room:example.org`
+- local chat id, for example `C2`
+- room name
+- archive status
+- owning space id
+
+These remain the source of truth for Matrix UX.
+
+### Platform context identity
+
+Each working Matrix room gets a `platform_chat_id` stored in its room metadata.
+
+Example `room_meta` shape:
+
+```json
+{
+  "chat_id": "C2",
+  "space_id": "!space:example.org",
+  "name": "Research",
+  "platform_chat_id": "chat_8f2c..."
+}
+```
+
+Rules:
+
+- one working Matrix room maps to exactly one current platform context
+- two Matrix rooms must not share the same `platform_chat_id` unless we intentionally implement that later
+- branching creates a new `platform_chat_id`, never reuses the old one
+
+## Runtime Semantics
+
+### Normal message flow
+
+1. A Matrix message arrives in a working room.
+2. The Matrix adapter resolves the room to local `room_meta`.
+3. The integration layer reads `platform_chat_id` from that metadata.
+4. `RealPlatformClient.send_message(...)` sends the message to the platform using that `platform_chat_id`.
+5. The platform appends the exchange to that specific context and returns the reply.
+6. The Matrix adapter sends the reply back to the room.
+
+The key change is that the agent no longer treats all Matrix rooms as one shared context.
+
+### `!new`
+
+`!new` creates a new user-facing chat and a new empty platform context at the same time.
+
+Flow:
+
+1. Create a new Matrix room in the user space.
+2. Ask the platform to create a new blank context and return its `platform_chat_id`.
+3. Store that `platform_chat_id` in the new room metadata.
+4. Invite the user into the room.
+
+Result:
+
+- the new room is immediately independent
+- sending the first message does not share memory with the previous room
+
+### `!branch`
+
+`!branch` creates a new room whose starting point is a snapshot of the current room context.
+
+Flow:
+
+1. Resolve the current room's `platform_chat_id`.
+2. Ask the platform to create a new context branched from that source.
+3. Create a new Matrix room.
+4. Store the new `platform_chat_id` in the new room metadata.
+5. Invite the user into the new room.
+
+Result:
+
+- the new room starts with the current history and state
+- later messages diverge independently
+
+### `!save`
+
+`!save [name]` saves a snapshot of the current room's platform context under the current user.
+
+Semantics:
+
+- saves are owned by the user, not by the room
+- the saved snapshot originates from the current `platform_chat_id`
+
+### `!load`
+
+`!load` shows the user's saved contexts and loads the chosen snapshot into the current room's platform context.
+
+Semantics:
+
+- a saved context created in one room can be loaded into any other room owned by the same user
+- loading does not replace the Matrix room identity
+- loading affects only the current room's mapped `platform_chat_id`
+
+### `!context`
+
+`!context` reports the state of the current room context, not a global user session.
+
+Minimum expected output:
+
+- current room name or local chat id
+- current `platform_chat_id` presence or status
+- what saved context, if any, was last loaded here
+- last token usage if the platform still returns it
+
+## Legacy Room Migration
+
+Existing Matrix rooms were created before real platform `chat_id` support and therefore may not have `platform_chat_id` in their metadata.
+
+We need a non-destructive migration.
+
+### Lazy migration strategy
+
+For a room without `platform_chat_id`:
+
+1. On the first operation that requires platform context, detect the missing mapping.
+2. Create a new blank platform context for that room.
+3. Persist the new `platform_chat_id` into room metadata.
+4. Continue the requested operation normally.
+
+This applies to:
+
+- first normal message
+- `!context`
+- `!save`
+- `!load`
+- `!branch`
+
+This avoids forcing users to recreate their rooms manually.
+
+## Interface Changes
+
+### Matrix metadata
+
+Extend Matrix `room_meta` helpers to read and write `platform_chat_id`.
+
+### Real platform client
+
+`RealPlatformClient` must stop treating the current `chat_id` parameter as a purely local label when talking to the platform. The surface-facing call can still receive the local `chat_id`, but platform calls must use the resolved `platform_chat_id`.
+
+Recommended integration direction:
+
+- Matrix resolves the room mapping before calling the platform
+- `RealPlatformClient` receives the platform context id it should use
+
+This keeps the platform client simple and avoids giving it Matrix-specific storage responsibilities.
+
+### Agent API wrapper
+
+The wrapper must support platform calls that are explicitly context-aware:
+
+- create new context
+- branch context
+- send message into a specific context
+- save current context
+- load saved context into a specific context
+
+If upstream naming differs, the adapter layer should normalize those operations into stable local methods.
+
+## Command Semantics in MVP
+
+The MVP command set should evolve to this:
+
+- `!new` creates a new room with a new empty platform context
+- `!branch` creates a new room with a branched platform context
+- `!context` reports the current room context
+- `!save` saves the current room context for the user
+- `!load` loads one of the user's saved contexts into the current room
+
+Commands that do not have reliable backend support should remain hidden or explicitly marked unavailable.
+
+## Error Handling
+
+### Missing mapping
+
+If `platform_chat_id` is missing:
+
+- try lazy migration first
+- only return an error if migration fails
+
+### Platform create or branch failure
+
+If the platform cannot create or branch a context:
+
+- do not create partially-initialized room metadata
+- return a user-facing error in the source room
+- log enough detail to diagnose the backend failure
+
+### Save and load failure
+
+The surface must not claim success before the platform confirms success.
+
+For MVP quality:
+
+- user-facing text should say "request sent" only when confirmation is not available
+- once platform confirmation exists, switch to real success or failure messages
+
+## Testing
+
+Add or update tests for:
+
+- a new room gets a new `platform_chat_id`
+- two rooms created with `!new` do not share context ids
+- `!branch` creates a new room with a different `platform_chat_id` derived from the current one
+- sending messages from two rooms uses different platform context ids
+- saved contexts remain user-visible across rooms
+- loading the same saved context into two different rooms affects those rooms independently afterward
+- a legacy room without `platform_chat_id` lazily receives one on first use
+- failures during create, branch, save, and load do not leave broken metadata behind
+
+## Migration Path
+
+This design preserves a clean future direction:
+
+- Matrix continues to own its UX model
+- Telegram can adopt the same `surface_chat -> platform_chat_id` mapping later
+- when the platform matures further, more of the save/load/branch logic can move from prompts or local workarounds into real platform APIs
+
+The key long-term boundary stays stable:
+
+- surfaces own presentation and routing
+- the platform owns context
+- the integration layer owns the mapping

docs/superpowers/specs/2026-04-20-matrix-shared-workspace-file-flow-design.md

@@ -0,0 +1,252 @@
+# Matrix Shared Workspace File Flow Design
+
+## Goal
+
+Bring the Matrix surface and `platform-agent` to a single file-handling model that matches the current platform runtime contract as closely as possible.
+
+The result should be:
+
+- Matrix receives user files and makes them visible to the agent through a shared `/workspace`
+- `platform-agent` receives attachment paths, not ad hoc summaries or inline payloads
+- the agent can send files back to the user through the surface via `send_file`
+- local development and the default deployment path use the same storage contract
+
+## Core Decision
+
+The selected architecture is:
+
+`Matrix surface <-> shared /workspace <-> platform-agent`
+
+This means:
+
+- the Matrix bot is responsible for downloading incoming Matrix media
+- downloaded files are written into the same filesystem mounted into `platform-agent`
+- the surface passes relative workspace paths to the agent as `attachments`
+- the agent returns files to the user by emitting `MsgEventSendFile(path=...)`
+
+This is the current platform-native direction and does not require new platform endpoints.
+
+## Why This Decision
+
+The current upstream platform changes already define the file contract:
+
+- `MsgUserMessage.attachments` is `list[str]`
+- each attachment is a path relative to `/workspace`
+- the agent validates those paths against its configured backend root
+- the agent can emit `send_file(path)` back to the client
+
+That is not an upload API and not a remote blob contract. It is an explicit shared-workspace contract.
+
+Trying to preserve the current separate-process launch model would force the surface to fake production behavior with inline text extraction, out-of-band path rewriting, or a future upload API that does not exist yet. That would increase the gap between our runtime and the platform runtime instead of reducing it.
+
+## Scope
+
+This design covers:
+
+- shared workspace runtime for Matrix bot and `platform-agent`
+- incoming Matrix file handling into shared storage
+- attachment path propagation to `RealPlatformClient` and `AgentApi`
+- outbound file delivery from agent to Matrix user
+- local compose/dev workflow and README updates
+
+This design does not cover:
+
+- Telegram file flow
+- encrypted Matrix media handling
+- upload APIs on the platform side
+- OCR, PDF parsing, or content extraction pipelines
+- long-term object storage or file lifecycle policies beyond basic cleanup boundaries
+
+## Runtime Contract
+
+### Shared filesystem
+
+Both containers must mount the same directory at `/workspace`.
+
+Requirements:
+
+- the Matrix bot can create files under `/workspace`
+- `platform-agent` sees the same files at the same relative paths
+- agent-originated files written under `/workspace` are readable by the Matrix bot
+
+The contract is path-based, not URL-based.
+
+### Attachment path format
+
+The surface sends attachments to the agent as relative workspace paths, for example:
+
+- `surfaces/matrix/<matrix_user_id>/<room_id>/inbox/20260420-153000-report.pdf`
+- `surfaces/matrix/<matrix_user_id>/<room_id>/inbox/20260420-153200-photo.jpg`
+
+Rules:
+
+- paths must be relative to `/workspace`
+- paths must be normalized before sending to the agent
+- surface-owned uploads must live under a dedicated namespace to avoid collisions with agent-created files
+
+## Data Flow
+
+### Incoming file from Matrix user
+
+1. Matrix receives `m.file`, `m.image`, `m.audio`, or `m.video`.
+2. The Matrix bot resolves the target room and platform chat context as usual.
+3. The Matrix bot downloads the media from Matrix.
+4. The file is stored under `/workspace/surfaces/matrix/.../inbox/...`.
+5. The outgoing platform call includes:
+   - original user text
+   - `attachments=[relative_path_1, ...]`
+6. `platform-agent` validates that those files exist and exposes them to the agent through the upstream attachment mechanism.
+
+Important detail:
+
+- the surface should not rewrite the user message into a synthetic file summary unless the message body is empty
+- when body is empty, the surface may send a minimal synthetic text such as `User sent one or more attachments.`
+
+### Outbound file from agent to Matrix user
+
+1. The agent uses `send_file(path)`.
+2. `platform-agent` emits `MsgEventSendFile(path=...)`.
+3. The Matrix integration catches that event.
+4. The Matrix bot resolves the file inside shared `/workspace`.
+5. The Matrix bot uploads the file to Matrix and sends the appropriate media message to the room.
+
+Surface behavior:
+
+- if MIME type and extension are known, send the closest native Matrix media type
+- otherwise send as `m.file`
+- user-visible failures must be explicit if the referenced file does not exist or cannot be uploaded
+
+## Filesystem Layout
+
+The Matrix surface owns a dedicated subtree:
+
+```text
+/workspace/
+  surfaces/
+    matrix/
+      <sanitized-user-id>/
+        <sanitized-room-id>/
+          inbox/
+            20260420-153000-report.pdf
+```
+
+Design constraints:
+
+- sanitize user ids and room ids before using them as path components
+- preserve the original filename in the final basename where possible
+- prefix filenames with a timestamp or unique id to avoid collisions
+
+This layout is intentionally surface-scoped. The agent may read these files, but the surface remains the owner of how inbound messenger files are organized.
+
+## Components
+
+### Matrix attachment storage helper
+
+Add a focused helper module responsible for:
+
+- building stable workspace-relative paths
+- sanitizing path components
+- downloading Matrix media into `/workspace`
+- returning attachment metadata needed by the platform layer
+
+This helper should not know about agent transport details beyond the final relative path output.
+
+### Real platform client
+
+`RealPlatformClient` must pass attachment relative paths through to `AgentApi.send_message(...)`.
+
+It must also surface non-text agent events needed by the Matrix adapter, especially `MsgEventSendFile`.
+
+### Agent API wrapper
+
+`AgentApiWrapper` must be compatible with the modern upstream protocol:
+
+- `/v1/agent_ws/{chat_id}/`
+- `attachments` on outgoing user messages
+- `MsgEventToolCallChunk`
+- `MsgEventToolResult`
+- `MsgEventCustomUpdate`
+- `MsgEventSendFile`
+- `MsgEventEnd`
+
+### Matrix bot outbound renderer
+
+The Matrix adapter must support sending files back to the room.
+
+At minimum it needs:
+
+- path resolution inside shared workspace
+- Matrix upload of the local file
+- send of an `m.file` or native media event with filename and MIME type
+
+## Deployment Changes
+
+### Compose
+
+The repository root `docker-compose.yml` becomes the primary prod-like local runtime.
+
+It should define at least:
+
+- `matrix-bot`
+- `platform-agent`
+- one shared volume mounted as `/workspace` into both services
+
+The default developer workflow should stop describing `platform-agent` as a separately started side process.
+
+### Environment
+
+The Matrix bot must connect to the in-compose `platform-agent` service by service name, not by assuming a separately launched localhost process.
+
+The agent WebSocket configuration in docs and examples must match the modern upstream route.
+
+## Error Handling
+
+### Incoming files
+
+If the Matrix bot cannot download or persist the file:
+
+- do not send a broken attachment path to the agent
+- return a user-visible error in the room
+- log the Matrix event id, room id, and failure reason
+
+### Outbound files
+
+If the agent asks to send a missing file:
+
+- log a structured warning with the requested path
+- send a user-visible message that the file could not be delivered
+
+### Shared workspace mismatch
+
+If the runtime is misconfigured and `/workspace` is not actually shared:
+
+- inbound attachments will fail agent-side path validation
+- outbound `send_file` will fail surface-side file resolution
+
+The implementation should make such failures obvious in logs rather than silently degrading to text-only behavior.
+
+## Testing
+
+The implementation must cover:
+
+- Matrix media download writes into the expected workspace-relative path
+- `RealPlatformClient` forwards attachment relative paths to the agent API
+- Matrix plain messages with attachments preserve the original text while adding attachment paths
+- empty-body attachment-only messages produce the synthetic text fallback
+- `AgentApiWrapper` accepts `MsgEventSendFile` without treating it as unknown
+- Matrix outbound file handling converts `MsgEventSendFile` into a Matrix upload/send call
+- compose configuration mounts the same workspace into both containers
+
+## Non-Goals
+
+- no inline text extraction MVP
+- no temporary URL-passing contract to the agent
+- no fake “prod” mode with separate local filesystems
+- no platform API additions in this phase
+
+## Success Criteria
+
+- the default local runtime uses a shared `/workspace`
+- a user can send a file in Matrix and the agent receives it through upstream `attachments`
+- the agent can emit `send_file(path)` and the Matrix user receives the file in the same room
+- our runtime behavior matches the current platform contract closely enough that moving from local compose to production does not require redesigning file flow

docs/superpowers/specs/2026-04-20-matrix-staged-attachments-design.md

@@ -0,0 +1,262 @@
+# Matrix Staged Attachments Design
+
+## Goal
+
+Make file sending in the Matrix surface usable for an AI agent despite current Matrix client behavior, especially in Element where media is often sent immediately as separate events without a shared text composer.
+
+The result should be:
+
+- files can arrive before the user writes the actual instruction
+- the surface stages those files instead of immediately sending them to the agent
+- the next normal user message in the same chat commits all staged files as one agent turn
+- the user can inspect and remove staged files with short chat commands
+
+## Core Decision
+
+The selected UX model is:
+
+`incoming Matrix media -> staged attachments for (chat_id, user_id) -> next normal message commits them`
+
+This means:
+
+- attachment-only events do not immediately invoke the agent
+- the bot acknowledges staged files with a service message
+- the next normal user message sends text plus all currently staged files to the agent
+- staged files are then cleared
+
+## Why This Decision
+
+Matrix natively models messages as separate events, and common clients do not provide a reliable "one text message with many attachments" composer flow.
+
+In practice this causes two UX failures for an AI bot:
+
+- users may send files first and only then write the task
+- users may send multiple files as multiple independent Matrix events
+
+If the surface treats each incoming file as a full agent turn, the bot becomes noisy and context-fragmented. If it ignores file-only messages, file handling feels broken.
+
+Staging is the smallest surface-side abstraction that fixes both problems without fighting the Matrix event model.
+
+## Scope
+
+This design covers:
+
+- staging inbound Matrix attachments before agent submission
+- per-chat attachment state for a specific user
+- user-facing service messages for staged attachments
+- short commands for listing and removing staged files
+- commit behavior on the next normal message
+
+This design does not cover:
+
+- edits or redactions of original Matrix media events as attachment controls
+- cross-surface shared staging
+- thread-aware staging beyond the existing `chat_id` boundary
+- changes to the platform attachment contract
+
+## State Model
+
+### Staging key
+
+Staged attachments are isolated by:
+
+- `chat_id`
+- `user_id`
+
+This means:
+
+- files staged by a user in one chat never appear in another chat
+- files staged by one user do not mix with another user's files in the same room
+
+### Staged attachment record
+
+Each staged attachment must track at least:
+
+- stable internal id
+- display filename
+- workspace-relative path
+- MIME type if known
+- created timestamp
+
+User-visible commands operate on the current ordered list, not on internal ids.
+
+### Lifecycle
+
+A staged attachment is in exactly one of these states:
+
+1. `staged`
+2. `committed`
+3. `removed`
+
+Rules:
+
+- only `staged` attachments appear in `!list`
+- `committed` attachments are no longer user-removable
+- `removed` attachments are excluded from future commits
+
+## Inbound Behavior
+
+### Attachment-only event
+
+If the Matrix surface receives one or more file/media events from a user without a normal text message to commit them:
+
+1. download each file into shared `/workspace`
+2. add each file to the staged set for `(chat_id, user_id)`
+3. do not call the agent yet
+4. send a service acknowledgment message
+
+### Service acknowledgment
+
+The service message must communicate:
+
+- the current staged attachment list with indices
+- that the next normal message will be sent to the agent together with those files
+- available commands: `!list`, `!remove <n>`, `!remove all`
+
+Example shape:
+
+```text
+Staged attachments:
+1. screenshot.png
+2. invoice.pdf
+
+Your next message will be sent to the agent with these files.
+Commands: !list, !remove <n>, !remove all
+```
+
+### Burst handling
+
+Matrix clients may send multiple files as separate consecutive events.
+
+To avoid bot spam, service acknowledgments should be debounced over a short window and aggregated into one reply where feasible.
+
+The acknowledgment must reflect the full current staged set, not only the most recently received file.
+
+## Commit Behavior
+
+### Commit trigger
+
+The commit trigger is:
+
+- the next normal user message in the same `(chat_id, user_id)` scope
+
+Normal user message means:
+
+- not a staging control command
+- not a pure attachment event being staged
+
+### Commit action
+
+When a commit-triggering message arrives:
+
+1. collect all currently staged attachments for `(chat_id, user_id)`
+2. send the user text plus those attachments to the agent as one turn
+3. mark all included staged attachments as `committed`
+4. clear the staged set
+
+After commit:
+
+- the just-sent attachments must no longer appear in `!list`
+- a later file upload starts a new staged set
+
+## Commands
+
+### `!list`
+
+Shows the current staged attachment list for the user in the current chat.
+
+If the list is empty, the response should be short and explicit.
+
+### `!remove <n>`
+
+Removes the staged attachment at the current 1-based index.
+
+Behavior:
+
+- if the index is valid, remove that staged attachment and return the updated staged list
+- if the index is invalid, return a short error without repeating the list
+
+### `!remove all`
+
+Clears the entire staged set for the user in the current chat.
+
+The response should be short and explicit.
+
+## Ordering Rules
+
+The staged list is ordered by staging time.
+
+User-facing indices:
+
+- are 1-based
+- are recalculated from the current staged set
+- may change after removals
+
+Therefore:
+
+- `!list` always shows the current authoritative numbering
+- after a successful `!remove <n>`, the bot should reply with the refreshed list
+
+## Error Handling
+
+### Download failure
+
+If a file cannot be downloaded or stored:
+
+- do not add it to the staged set
+- do not pretend it will be sent later
+- send a short user-visible failure message
+
+### Invalid command
+
+If the command is malformed or uses an invalid index:
+
+- return a short error
+- do not commit staged attachments
+- do not clear the staged set
+
+### Agent submission failure
+
+If commit fails when sending the text plus staged files to the agent:
+
+- staged attachments must remain available for retry unless the failure is known to be irreversible
+- the user-visible error should make it clear that the files were not consumed
+
+This prevents silent loss of staged context.
+
+## Interaction with Shared Workspace Design
+
+This design assumes the shared-workspace contract defined in
+[2026-04-20-matrix-shared-workspace-file-flow-design.md](/Users/a/MAI/sem2/lambda/surfaces-bot/docs/superpowers/specs/2026-04-20-matrix-shared-workspace-file-flow-design.md).
+
+Specifically:
+
+- staged files are stored in shared `/workspace`
+- the final commit still passes workspace-relative paths to `platform-agent`
+- staging changes only when the surface chooses to invoke the agent, not how attachments are represented
+
+## Testing
+
+The implementation must cover:
+
+- file-only Matrix events are staged and do not immediately invoke the agent
+- service acknowledgment includes staged filenames and command hints
+- `!list` returns the current staged set for the correct `(chat_id, user_id)`
+- `!remove <n>` removes the correct staged attachment and refreshes numbering
+- `!remove all` clears the staged set
+- invalid `!remove <n>` returns a short error and keeps state unchanged
+- the next normal message commits all staged attachments with the text as one agent turn
+- committed attachments disappear from staging after success
+- failed commits preserve staged attachments
+- staging in one chat does not leak into another chat
+- staging for one user does not leak to another user in the same room
+
+## Non-Goals
+
+This design intentionally does not attempt to:
+
+- emulate Telegram-style albums in Matrix
+- rely on special support from Element or other Matrix clients
+- introduce a rich interactive attachment management UI
+
+The goal is a reliable chat-native workflow that works within Matrix's actual event model.

docs/superpowers/specs/2026-04-22-transport-layer-thin-adapter-design.md

@@ -0,0 +1,318 @@
+# Transport Layer Thin Adapter Design
+
+## Цель
+
+Упростить transport layer между Matrix surface и `platform-agent` до максимально production-like вида:
+
+- использовать upstream `platform-agent_api.AgentApi` почти как есть
+- убрать из surface-side клиента собственную интерпретацию stream semantics
+- оставить в нашем коде только integration concerns:
+  - per-chat lifecycle
+  - per-chat serialization
+  - attachment path forwarding
+  - exception mapping в `PlatformError`
+
+Это нужно, чтобы:
+
+- восстановить чёткую границу ответственности между `surfaces` и платформой
+- убрать из диагностики ложные факторы, внесённые нашей кастомной обёрткой
+- получить честную картину реальных platform bugs до добавления любых policy-надстроек
+
+## Контекст
+
+Сейчас transport path состоит из:
+
+- [sdk/agent_api_wrapper.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/agent_api_wrapper.py)
+- [sdk/real.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/real.py)
+
+Изначально `AgentApiWrapper` был создан по разумным причинам:
+
+- поддержка переходного периода между разными версиями `platform-agent_api`
+- унификация `base_url/url`
+- создание per-chat client instances через `for_chat()`
+- локальный учёт `tokens_used`
+
+Позже в этот слой были добавлены уже не compatibility-функции, а собственные transport semantics:
+
+- custom `_listen()`
+- custom `send_message()`
+- post-END drain window
+- custom idle timeout
+- event-kind reclassification
+
+После этого `surfaces` перестал быть тонким клиентом платформы и начал вести себя как альтернативная реализация transport layer. Это делает диагностику platform bugs нечистой.
+
+## Принципы дизайна
+
+### 1. Transport должен быть скучным
+
+Transport layer не должен:
+
+- спасать поздние chunks
+- лечить duplicate `END`
+- придумывать собственные правила границы ответа
+- по-своему классифицировать stream events сверх upstream client behavior
+
+Если upstream stream protocol повреждён, мы должны видеть это как platform issue, а не скрывать его кастомной очередью.
+
+### 2. Policy и transport разделяются
+
+Transport:
+
+- говорит с upstream API
+- доставляет события
+- закрывает соединение
+
+Policy:
+
+- решает, что считать recoverable failure
+- нужна ли повторная попытка
+- как сообщать ошибку пользователю
+- нужно ли сбрасывать chat session
+
+На первом этапе policy не расширяется. Мы сначала приводим transport к тонкому адаптеру, потом заново оцениваем реальные проблемы.
+
+### 3. Session lifecycle остаётся на нашей стороне
+
+Даже в thin-adapter модели `surfaces` по-прежнему отвечает за:
+
+- кеширование client per chat
+- один send lock на chat
+- сброс мёртвой chat session после failure
+- mapping upstream exceptions в `PlatformError`
+
+Это не transport semantics, а integration lifecycle.
+
+## Варианты
+
+### Вариант A. Оставить текущий кастомный wrapper
+
+Плюсы:
+
+- уже работает на части сценариев
+- содержит built-in mitigations против observed failures
+
+Минусы:
+
+- нарушает границу ответственности
+- усложняет диагностику
+- делает platform bug reports спорными
+- содержит symptom-fix логику в transport layer
+
+Вердикт: не подходит как production-like target.
+
+### Вариант B. Thin upstream adapter
+
+Плюсы:
+
+- чистая архитектура
+- честная диагностика upstream проблем
+- минимальная собственная магия
+
+Минусы:
+
+- локальные mitigations исчезают
+- если upstream client несовершенен, это сразу проявится
+
+Вердикт: правильный первый этап.
+
+### Вариант C. Thin adapter сейчас, outer policy layer потом
+
+Плюсы:
+
+- даёт production-like эволюцию
+- не смешивает transport и resilience policy
+- позволяет сначала увидеть реальные проблемы, потом адресовать только нужные
+
+Минусы:
+
+- требует двух фаз вместо одной
+
+Вердикт: рекомендуемый путь.
+
+## Рекомендуемая архитектура
+
+### Слой 1. Upstream client
+
+Источник истины:
+
+- [external/platform-agent_api/lambda_agent_api/agent_api.py](/Users/a/MAI/sem2/lambda/surfaces-bot/external/platform-agent_api/lambda_agent_api/agent_api.py)
+
+Мы принимаем его stream semantics как authoritative behavior.
+
+### Слой 2. Thin adapter
+
+Файл:
+
+- [sdk/agent_api_wrapper.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/agent_api_wrapper.py)
+
+После cleanup он должен содержать только:
+
+- создание клиента через modern constructor
+- `base_url` normalization, если это действительно нужно для наших env
+- `for_chat(chat_id)` как factory convenience
+- опционально thin storage для `last_tokens_used`, если это можно сделать без переопределения stream semantics
+
+Он не должен переопределять:
+
+- `_listen()`
+- `send_message()`
+- queue lifecycle
+- post-END behavior
+- timeout behavior
+
+### Слой 3. Integration/session layer
+
+Файл:
+
+- [sdk/real.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/real.py)
+
+Ответственность:
+
+- кешировать chat client instances
+- сериализовать sends по chat lock
+- вызывать `disconnect_chat(chat_id)` после transport failure
+- превращать upstream exceptions в `PlatformError`
+- форвардить `attachments` как relative workspace paths
+- собирать `MessageResponse` / `MessageChunk` для остального приложения
+
+Этот слой не должен заниматься:
+
+- исправлением broken stream boundaries
+- custom post-END reconstruction
+- поздним дренированием очереди
+
+## Что удаляем
+
+Из [sdk/agent_api_wrapper.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/agent_api_wrapper.py):
+
+- custom `_listen()`
+- custom `send_message()`
+- `_drain_post_end_events()`
+- `_event_kind()`
+- `_is_kind()`
+- `_is_text_event()`
+- `_is_end_event()`
+- `_is_send_file_event()`
+- `_POST_END_DRAIN_MS`
+- `_STREAM_IDLE_TIMEOUT_MS`
+- debug logging, завязанное на наш собственный queue lifecycle
+
+## Что оставляем
+
+В thin adapter:
+
+- `__init__()` для modern `base_url/chat_id`
+- `_normalize_base_url()` только если нужен стабильный env input
+- `for_chat(chat_id)`
+
+В [sdk/real.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/real.py):
+
+- `_get_chat_api()`
+- `_get_chat_send_lock()`
+- `_attachment_paths()`
+- `disconnect_chat()`
+- `_handle_chat_api_failure()`
+- `send_message()`
+- `stream_message()`
+
+## Дополнительное упрощение
+
+Если после cleanup мы считаем pinned upstream API обязательным, то из [sdk/real.py](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/real.py) можно убрать legacy-minded probing:
+
+- `inspect.signature(send_message)`
+- conditional fallback на старый `send_message(text)` без `attachments`
+
+В этом случае `RealPlatformClient` всегда использует современный контракт:
+
+- `send_message(text, attachments=...)`
+
+Это ещё сильнее уменьшит ambiguity.
+
+## Этапы миграции
+
+### Этап 1. Cleanup до thin adapter
+
+Делаем:
+
+- сжимаем `sdk/agent_api_wrapper.py` до thin shim
+- переносим всю допустимую resilience logic только в `sdk/real.py`
+- удаляем тесты, которые закрепляют наши кастомные transport semantics
+
+### Этап 2. Повторная верификация
+
+Заново прогоняем:
+
+- text-only flow
+- staged attachments flow
+- large image failure
+- duplicate `END` behavior
+- behavior after transport disconnect
+
+На этом этапе мы честно увидим, что реально делает upstream transport.
+
+### Этап 3. Опциональный outer policy layer
+
+Только если после Этапа 2 это действительно нужно, добавляем policy поверх transport:
+
+- request timeout целиком
+- retry policy
+- circuit-breaker-like behavior
+
+Но это должно жить не в client wrapper, а выше, в integration layer.
+
+## Тестовая стратегия
+
+### Удаляем как нецелевые тесты
+
+Больше не считаем нормой:
+
+- post-END drain behavior
+- recovery late chunks после `END`
+- idle timeout внутри wrapper как часть client contract
+
+### Оставляем и добавляем
+
+Нужные guarantees:
+
+1. создаётся отдельный client per chat
+2. один chat сериализуется через lock
+3. разные чаты не делят client instance
+4. attachment paths уходят в `send_message(..., attachments=...)`
+5. transport failure приводит к `disconnect_chat(chat_id)`
+6. следующий запрос после failure открывает новую chat session
+7. upstream exception превращается в `PlatformError`
+
+## Риски
+
+### 1. Может снова проявиться реальный upstream bug
+
+Это не regression дизайна, а полезный результат cleanup.
+
+### 2. Может исчезнуть локальная защита от зависших стримов
+
+Это допустимо на первом этапе.
+Если она действительно нужна, она должна вернуться как outer policy, а не как переписанный client transport.
+
+### 3. Может выясниться, что даже thin wrapper не нужен
+
+Если modern upstream `AgentApi` уже полностью покрывает наш use case, файл `sdk/agent_api_wrapper.py` можно будет заменить на маленький factory helper или убрать совсем.
+
+## Критерии успеха
+
+Результат считается успешным, если:
+
+- transport layer в `surfaces` перестаёт иметь собственную stream semantics
+- platform bug reports снова можно формулировать без сильного caveat про кастомный клиент
+- Matrix real backend продолжает работать на text-only и attachments scenarios
+- failure handling остаётся контролируемым, но больше не маскирует transport behavior платформы
+
+## Решение
+
+Принять путь:
+
+- `Thin upstream adapter now`
+- `Observe real behavior`
+- `Add outer policy later only if needed`
+
+Это наиболее близкий к production best practice вариант для текущего состояния проекта.

docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md

@@ -0,0 +1,336 @@
+# Matrix Multi-Agent Routing Design
+
+## Goal
+
+Move the Matrix surface from a single hardcoded upstream agent to a user-selectable multi-agent model, while preserving the existing room-based UX and the current `PlatformClient` boundary.
+
+The result should be:
+
+- one Matrix bot can work with multiple upstream agents
+- users can choose an agent from the full configured list
+- each chat is bound to exactly one agent
+- switching the selected agent does not silently retarget an existing chat
+
+## Core Decision
+
+The selected routing model is:
+
+`user.selected_agent_id + room.agent_id + room.platform_chat_id`
+
+This means:
+
+- the user has one current selected agent
+- each Matrix working room stores the agent it is bound to
+- each Matrix working room stores its own `platform_chat_id`
+- a room never changes agent implicitly
+- the shared `PlatformClient` protocol remains unchanged
+- Matrix multi-agent routing is implemented by a single routing facade that delegates to per-agent real clients
+
+## Why This Decision
+
+The current Matrix adapter already separates:
+
+- user-facing room organization
+- local chat labels such as `C1`, `C2`, `C3`
+- platform-facing conversation identity via `platform_chat_id`
+
+Adding multi-agent support should preserve that shape instead of replacing it.
+
+If routing depended only on the current user selection, then an old room could start talking to a different agent after a switch. That would make room history and backend context hard to reason about. Binding an agent to the room keeps the conversation model explicit.
+
+## Scope
+
+This design covers:
+
+- agent selection by the user inside the Matrix surface
+- durable storage of the selected agent
+- durable storage of the room-bound agent
+- routing normal messages and context commands to the correct upstream agent
+- behavior when a room becomes stale after an agent switch
+
+This design does not cover:
+
+- per-agent workspace isolation
+- platform-side agent lifecycle or memory persistence
+- per-user allowlists for available agents
+- Telegram or other surfaces
+
+## Configuration Model
+
+### Agent registry
+
+Available agents are defined in a local config file loaded once at bot startup.
+
+Example:
+
+```yaml
+agents:
+  - id: agent-1
+    label: Analyst
+  - id: agent-2
+    label: Research
+  - id: agent-3
+    label: Ops
+```
+
+Rules:
+
+- every entry must have a stable `id`
+- every entry must have a user-visible `label`
+- all configured agents are selectable by all users
+- config changes apply only after bot restart
+
+### Startup validation
+
+If the agent config is missing, empty, or invalid, the Matrix bot must fail fast on startup with a clear operator error.
+
+## Durable State Model
+
+### User-level state
+
+User metadata keeps the current selected agent.
+
+Example `matrix_user:*` shape:
+
+```json
+{
+  "space_id": "!space:example.org",
+  "next_chat_index": 4,
+  "selected_agent_id": "agent-2"
+}
+```
+
+Meaning:
+
+- `selected_agent_id` controls future chat creation and activation of an unbound room
+- `selected_agent_id` does not rewrite already bound rooms
+
+### Room-level state
+
+Room metadata stores the agent bound to that chat.
+
+Example `matrix_room:*` shape:
+
+```json
+{
+  "room_type": "chat",
+  "chat_id": "C3",
+  "display_name": "Чат 3",
+  "matrix_user_id": "@alice:example.org",
+  "space_id": "!space:example.org",
+  "platform_chat_id": "42",
+  "agent_id": "agent-2"
+}
+```
+
+Rules:
+
+- one room binds to exactly one `agent_id`
+- one room binds to exactly one current `platform_chat_id`
+- once a room becomes stale after an agent switch, it never becomes active again
+
+## Runtime Semantics
+
+### `!start`
+
+`!start` remains lightweight:
+
+- if no agent is selected, the bot explains that an agent must be selected before normal messaging
+- if an agent is already selected, the bot reports the current selection and reminds the user that `!new` creates a new room under that agent
+
+### `!agent`
+
+Introduce an agent-selection command.
+
+Behavior:
+
+- `!agent` shows the available agent list
+- agent selection stores `selected_agent_id` in user metadata
+- after a successful switch, the bot tells the user that existing chats bound to another agent are stale and that `!new` is required for continued work
+
+The exact UI can be text-first for MVP. A richer UI can be added later without changing the state model.
+
+### Normal message without selected agent
+
+If the user has not selected an agent yet:
+
+- do not call the platform
+- return the available agent list
+- ask the user to choose one first
+
+This is an intentional one-time routing handshake, not an accidental fallback.
+In a multi-agent deployment, the surface must not silently guess which agent an unbound user should talk to.
+
+### Selecting an agent inside an unbound chat
+
+If the current room has never been bound to any agent:
+
+- store the new `selected_agent_id` for the user
+- bind the current room to that same `agent_id`
+- allow the room to become the active working chat immediately
+
+This avoids forcing `!new` for the user's first usable chat.
+
+### `!new`
+
+`!new` creates a new working room under the current selected agent.
+
+Behavior:
+
+1. require `selected_agent_id`
+2. create the new Matrix room
+3. allocate a new `platform_chat_id`
+4. store `agent_id = selected_agent_id` in the new room metadata
+
+### Normal message in an unbound room with selected agent
+
+If a room exists but has no `agent_id` yet and the user already has `selected_agent_id`:
+
+- bind the room to `selected_agent_id`
+- ensure it has `platform_chat_id`
+- continue normal message dispatch
+
+### Normal message in a bound room
+
+If the room already has `agent_id` and it matches the current selected agent:
+
+- route the message to that `agent_id`
+- use the room's `platform_chat_id`
+
+### Stale room after agent switch
+
+If the room's bound `agent_id` differs from the user's current `selected_agent_id`:
+
+- do not call the platform
+- treat the room as stale
+- return a short message telling the user that this chat belongs to the old agent and that they must use `!new`
+
+### Returning to a previously selected agent
+
+If the user later selects an old agent again:
+
+- previously stale rooms do not become valid again
+- the user must still create a fresh room via `!new`
+
+## Routing and Component Changes
+
+### Agent registry loader
+
+Add a small loader responsible for:
+
+- reading `agents.yaml`
+- validating ids and labels
+- exposing a read-only registry to runtime code
+
+The runtime should not parse YAML ad hoc during message handling.
+
+### Matrix runtime pre-check
+
+Before dispatching a normal message, the Matrix runtime must resolve:
+
+- whether the user has `selected_agent_id`
+- whether the current room already has `agent_id`
+- whether the room can be bound now
+- whether the room is stale
+
+This pre-check happens before handing the message to the existing dispatcher path.
+
+### Routed platform client
+
+The selected implementation keeps the shared `PlatformClient` protocol unchanged.
+
+The Matrix runtime owns one routing-aware facade, for example `RoutedPlatformClient`, that implements `PlatformClient` and delegates to agent-specific real clients.
+
+Responsibilities:
+
+- resolve the current room binding from local Matrix metadata
+- translate a local Matrix logical chat id into the room's `platform_chat_id`
+- choose the correct per-agent delegate for the room's bound `agent_id`
+- keep `get_or_create_user`, `get_settings`, and `update_settings` behavior stable for the rest of the runtime
+
+This keeps the multi-agent logic inside the Matrix integration boundary instead of pushing agent selection into the shared protocol.
+
+### Real platform bridge delegates
+
+The current real backend path hardcodes a single runtime-level `agent_id`.
+That must be replaced with per-agent delegates hidden behind the routing facade.
+
+The selected design is:
+
+- `RealPlatformClient` remains the low-level direct-agent delegate for one configured `agent_id`
+- the routing facade holds or creates one `RealPlatformClient` delegate per configured agent
+- `send_message(...)` and `stream_message(...)` on the facade resolve the room target and forward the call to the matching delegate
+- the delegate creates a fresh upstream `AgentApi` for its configured `agent_id`
+- no long-lived `AgentApi` instances are cached by user
+
+This preserves the current fresh-connection-per-request behavior while avoiding a protocol break for Telegram or other surfaces.
+
+## Error Handling
+
+### Missing or invalid selected agent
+
+If `selected_agent_id` is absent:
+
+- ask the user to select an agent
+
+If `selected_agent_id` points to an agent that no longer exists in config:
+
+- treat the selection as invalid
+- ask the user to select again
+
+### Missing room binding
+
+If the room has no `agent_id`:
+
+- bind it only when the user has a valid current selection
+- otherwise return the selection prompt
+
+### Stale room
+
+If the room is stale:
+
+- do not attempt fallback routing
+- do not silently rewrite room metadata
+- instruct the user to run `!new`
+
+### Invalid config
+
+If the bot cannot load a valid agent registry:
+
+- fail at startup
+- do not start in degraded single-agent mode
+
+## Testing Expectations
+
+Tests for this design should prove:
+
+- config parsing and startup validation
+- selecting an agent persists `selected_agent_id`
+- selecting an agent inside an unbound room activates that room
+- `!new` binds the new room to the selected agent
+- messages in a bound room use that room's `agent_id`
+- stale rooms reject normal messaging with a clear `!new` instruction
+- returning to the same agent later does not revive stale rooms
+
+## Migration Notes
+
+Existing rooms may have `platform_chat_id` but no `agent_id`.
+
+For this MVP, treat those rooms as legacy-unbound rooms:
+
+- if the user has a valid selected agent, the room may be bound on first use
+- if no agent is selected, the room prompts for selection first
+
+No automatic migration across agents is introduced.
+
+### Existing users without `selected_agent_id`
+
+Existing users upgraded from the single-agent model may have working rooms but no stored `selected_agent_id`.
+
+For this MVP, that is handled explicitly:
+
+- normal messaging is paused until the user selects an agent
+- the first valid selection can bind an unbound room immediately
+- the surface does not auto-assign a default agent in a multi-agent config
+
+This is intentional. Once more than one agent exists, silent migration would be ambiguous and could route a user to the wrong backend target.

docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md

@@ -0,0 +1,258 @@
+# Matrix Surface Restart State Persistence Design
+
+## Goal
+
+Make the Matrix surface survive a normal restart or container recreate without losing the minimal state required to keep working as a bot.
+
+The result should be:
+
+- after restart, the bot can still answer messages and execute commands
+- the bot remembers the selected agent for each user
+- the bot remembers which agent and `platform_chat_id` each room is bound to
+- temporary UX flows may be lost without being treated as a bug
+
+## Core Decision
+
+The selected persistence model is:
+
+`durable surface state only`
+
+This means:
+
+- persist only the state needed for routing and normal command handling
+- do not persist temporary UI and wizard state
+- require persistent local storage for the surface
+- do not attempt recovery if those volumes are lost
+
+## Why This Decision
+
+The Matrix surface already has two different classes of state:
+
+- stable local state that defines how rooms and users are routed
+- temporary UX state that exists only to complete short-lived interactions
+
+Trying to make all temporary UX state survive restart would add complexity and edge cases without improving the core requirement: the bot should still function normally after restart.
+
+The chosen design keeps persistence aligned with what the surface actually owns:
+
+- Matrix-side metadata and routing state are durable
+- agent conversation memory is the platform's responsibility
+- lost local volumes are treated as environment reset, not as an auto-recovery scenario
+
+## Scope
+
+This design covers:
+
+- which Matrix surface data must persist across restart
+- where that data lives
+- how restart behavior interacts with multi-agent routing
+- what state is intentionally non-durable
+
+This design does not cover:
+
+- platform-side persistence of agent memory
+- workspace isolation between multiple agents
+- automatic reconstruction after total local volume loss
+- persistence of temporary UX flows
+
+## Persistence Boundary
+
+### Durable state
+
+The Matrix surface must persist:
+
+- `matrix_user:*`
+- `matrix_room:*`
+- `chat:*`
+- `PLATFORM_CHAT_SEQ_KEY`
+- `selected_agent_id`
+- room-bound `agent_id`
+- room-bound `platform_chat_id`
+
+This is the minimal state required so that, after restart, the surface can:
+
+- identify the user
+- identify the room
+- determine which agent should receive a message
+- determine which `platform_chat_id` should be used
+- continue allocating new `platform_chat_id` values without reusing an already issued sequence number
+
+### Non-durable state
+
+The Matrix surface does not need to persist:
+
+- staged attachments
+- pending `!load` selection
+- pending `!yes/!no` confirmation
+- any temporary service UI step
+- live `AgentApi` instances or connection objects
+
+After restart, those flows may be lost. The bot only needs to remain operational.
+
+## Storage Model
+
+### Surface durable storage
+
+The Matrix surface must use persistent storage for:
+
+- `lambda_matrix.db`
+- `matrix_store`
+
+`lambda_matrix.db` stores the local key-value state used by the surface.
+`matrix_store` stores Matrix client state needed by `nio`.
+
+These paths must be backed by persistent container storage in normal deployments.
+
+### Shared `/workspace`
+
+The current local runtime also uses `/workspace`, but workspace behavior is outside the scope of this design.
+
+For this document, the only requirement is:
+
+- do not make restart persistence depend on solving per-agent workspace isolation first
+
+## Restart Assumptions
+
+This design assumes:
+
+- normal restart or redeploy with persistent local volumes still present
+
+This design does not assume:
+
+- automatic recovery after deleting or losing those volumes
+
+If the relevant volumes are lost, the environment is treated as reset.
+
+## Data Model Requirements
+
+### User metadata
+
+User metadata remains the durable location for user-level routing state.
+
+Example:
+
+```json
+{
+  "space_id": "!space:example.org",
+  "next_chat_index": 4,
+  "selected_agent_id": "agent-2"
+}
+```
+
+### Room metadata
+
+Room metadata remains the durable location for room-level routing state.
+
+Example:
+
+```json
+{
+  "room_type": "chat",
+  "chat_id": "C3",
+  "display_name": "Чат 3",
+  "matrix_user_id": "@alice:example.org",
+  "space_id": "!space:example.org",
+  "platform_chat_id": "42",
+  "agent_id": "agent-2"
+}
+```
+
+### Platform chat sequence
+
+The global `PLATFORM_CHAT_SEQ_KEY` remains part of durable surface state.
+
+Its purpose is:
+
+- allocate monotonically increasing `platform_chat_id` values
+- avoid reusing a previously issued platform chat identifier during normal restart or redeploy
+
+This sequence must be stored in the same durable surface store as the room and user metadata.
+
+## Runtime Semantics After Restart
+
+After restart, the Matrix surface must:
+
+1. load the durable Matrix store
+2. load the durable surface key-value state
+3. load the agent registry config
+4. resume normal room routing using persisted `selected_agent_id`, `agent_id`, and `platform_chat_id`
+
+Expected behavior:
+
+- a user with a valid previously selected agent does not need to reselect it
+- a room previously bound to an agent remains bound to that agent
+- normal messages and commands continue to work
+
+### Lost temporary UX state
+
+If the bot restarts during a transient UX flow:
+
+- staged attachments may disappear
+- pending `!load` selections may disappear
+- pending confirmations may disappear
+
+This is acceptable and should not block normal operation after restart.
+
+## Interaction With Multi-Agent Routing
+
+The multi-agent design introduces new durable state that must survive restart:
+
+- `selected_agent_id` on the user
+- `agent_id` on the room
+- `PLATFORM_CHAT_SEQ_KEY` in the surface store
+
+Restart persistence and multi-agent routing therefore belong together.
+
+Without durable storage for those fields, a restart would make room routing ambiguous.
+
+## Failure Handling
+
+### Missing durable surface store
+
+If the durable store paths are missing because the environment was reset:
+
+- do not attempt to reconstruct a full working state from scratch in this design
+- treat startup as a clean environment
+- allow normal onboarding flows to begin again
+
+### Invalid durable references
+
+If persisted `selected_agent_id` or room `agent_id` references an agent no longer present in config:
+
+- do not crash
+- treat the selection or room binding as invalid
+- ask the user to select a valid agent again
+
+### Platform conversation memory
+
+If the upstream platform loses agent memory across restart:
+
+- that is outside the surface persistence boundary
+- the surface must still route correctly
+- platform memory persistence remains a platform responsibility
+
+## Testing Expectations
+
+Tests for this design should prove:
+
+- `selected_agent_id` survives restart through durable local storage
+- room `agent_id` and `platform_chat_id` survive restart through durable local storage
+- the bot can route messages correctly after restart without user reconfiguration
+- missing temporary UX state does not break normal messaging and command handling
+- invalid persisted agent references degrade into reselection prompts rather than crashes
+
+## Operational Notes
+
+For the Matrix surface to survive restart in the intended way, deployment must persist:
+
+- `lambda_matrix.db`
+- `matrix_store`
+
+This is a deployment requirement, not an optional optimization.
+
+The design intentionally stops there. It does not require:
+
+- hot reload of agent config
+- recovery after total local state loss
+- persistence of temporary UX flows
+- a solved multi-agent workspace story

pyproject.toml

@@ -15,12 +15,15 @@ dependencies = [
     "structlog>=24.1",
     "python-dotenv>=1.0",
     "httpx>=0.27",
+    "aiohttp>=3.9",
+    "pyyaml>=6.0",
 ]
 
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
+    "pytest-aiohttp>=1.0",
     "pytest-cov>=4.1",
     "ruff>=0.3",
     "mypy>=1.8",

sdk/__init__.py

@@ -0,0 +1,9 @@
+__all__ = ["RealPlatformClient"]
+
+
+def __getattr__(name: str):
+    if name == "RealPlatformClient":
+        from sdk.real import RealPlatformClient
+
+        return RealPlatformClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

sdk/agent_session.py

@@ -0,0 +1 @@
+"""Compatibility stub: AgentSessionClient was replaced by direct AgentApi usage in Phase 4."""

sdk/interface.py

@@ -1,10 +1,11 @@
 # platform/interface.py
 from __future__ import annotations
 
+from collections.abc import AsyncIterator
 from datetime import datetime
-from typing import Any, AsyncIterator, Literal, Protocol
+from typing import Any, Literal, Protocol
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class User(BaseModel):
@@ -17,10 +18,11 @@ class User(BaseModel):
 
 
 class Attachment(BaseModel):
-    url: str
-    mime_type: str
+    url: str | None = None
+    mime_type: str | None = None
     size: int | None = None
     filename: str | None = None
+    workspace_path: str | None = None
 
 
 class MessageResponse(BaseModel):
@@ -28,10 +30,12 @@ class MessageResponse(BaseModel):
     response: str
     tokens_used: int
     finished: bool
+    attachments: list[Attachment] = Field(default_factory=list)
 
 
 class MessageChunk(BaseModel):
     """Один кусок стримингового ответа. При sync-режиме — единственный чанк с finished=True."""
+
     message_id: str
     delta: str
     finished: bool
@@ -48,6 +52,7 @@ class UserSettings(BaseModel):
 
 class AgentEvent(BaseModel):
     """Webhook-уведомление от платформы — агент закончил долгую задачу."""
+
     event_id: str
     user_id: str
     chat_id: str
@@ -94,4 +99,5 @@ class PlatformClient(Protocol):
 
 class WebhookReceiver(Protocol):
     """Регистрируется в боте. Платформа зовёт нас когда агент закончил долгую задачу."""
+
     async def on_agent_event(self, event: AgentEvent) -> None: ...

sdk/mock.py

@@ -4,8 +4,9 @@ from __future__ import annotations
 import asyncio
 import random
 import uuid
+from collections.abc import AsyncIterator
 from datetime import UTC, datetime
-from typing import Any, AsyncIterator, Literal
+from typing import Any, Literal
 
 import structlog
 
@@ -222,14 +223,16 @@ class MockPlatformClient:
         response = f"[MOCK] Ответ на: «{preview}»{attachment_note}"
         tokens = len(text.split()) * 2
 
-        self._messages[key].append({
-            "message_id": message_id,
-            "user_text": text,
-            "response": response,
-            "tokens_used": tokens,
-            "finished": True,
-            "created_at": datetime.now(UTC).isoformat(),
-        })
+        self._messages[key].append(
+            {
+                "message_id": message_id,
+                "user_text": text,
+                "response": response,
+                "tokens_used": tokens,
+                "finished": True,
+                "created_at": datetime.now(UTC).isoformat(),
+            }
+        )
         return message_id, response, tokens
 
     async def _latency(self, min_ms: int = 10, max_ms: int = 80) -> None:

sdk/prototype_state.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from sdk.interface import User, UserSettings
+
+# Keep the prototype backend self-contained; do not import these from sdk.mock.
+DEFAULT_SKILLS: dict[str, bool] = {
+    "web-search": True,
+    "fetch-url": True,
+    "email": False,
+    "browser": False,
+    "image-gen": False,
+    "files": True,
+}
+DEFAULT_SAFETY: dict[str, bool] = {
+    "email-send": True,
+    "file-delete": True,
+    "social-post": True,
+}
+DEFAULT_SOUL: dict[str, str] = {"name": "Лямбда", "instructions": ""}
+DEFAULT_PLAN: dict[str, Any] = {
+    "name": "Beta",
+    "tokens_used": 0,
+    "tokens_limit": 1000,
+}
+
+
+class PrototypeStateStore:
+    def __init__(self) -> None:
+        self._users: dict[str, User] = {}
+        self._settings: dict[str, dict[str, Any]] = {}
+        self._saved_sessions: dict[str, list[dict[str, str]]] = {}
+        self._context_last_tokens_used: dict[str, int] = {}
+        self._context_current_session: dict[str, str] = {}
+
+    async def get_or_create_user(
+        self,
+        external_id: str,
+        platform: str,
+        display_name: str | None = None,
+    ) -> User:
+        key = f"{platform}:{external_id}"
+        existing = self._users.get(key)
+        if existing is not None:
+            stored = existing.model_copy(update={"is_new": False})
+            self._users[key] = stored
+            return stored.model_copy()
+
+        user = User(
+            user_id=f"usr-{platform}-{external_id}",
+            external_id=external_id,
+            platform=platform,
+            display_name=display_name,
+            created_at=datetime.now(UTC),
+            is_new=True,
+        )
+        self._users[key] = user.model_copy(update={"is_new": False})
+        return user.model_copy()
+
+    async def get_settings(self, user_id: str) -> UserSettings:
+        stored = self._settings.get(user_id, {})
+        return UserSettings(
+            skills={**DEFAULT_SKILLS, **stored.get("skills", {})},
+            connectors=dict(stored.get("connectors", {})),
+            soul={**DEFAULT_SOUL, **stored.get("soul", {})},
+            safety={**DEFAULT_SAFETY, **stored.get("safety", {})},
+            plan={**DEFAULT_PLAN, **stored.get("plan", {})},
+        )
+
+    async def update_settings(self, user_id: str, action: Any) -> None:
+        settings = self._settings.setdefault(user_id, {})
+
+        if action.action == "toggle_skill":
+            skills = settings.setdefault("skills", DEFAULT_SKILLS.copy())
+            skills[action.payload["skill"]] = action.payload.get("enabled", True)
+        elif action.action == "set_soul":
+            soul = settings.setdefault("soul", DEFAULT_SOUL.copy())
+            soul[action.payload["field"]] = action.payload["value"]
+        elif action.action == "set_safety":
+            safety = settings.setdefault("safety", DEFAULT_SAFETY.copy())
+            safety[action.payload["trigger"]] = action.payload.get("enabled", True)
+
+    async def add_saved_session(
+        self,
+        user_id: str,
+        name: str,
+        *,
+        source_context_id: str | None = None,
+    ) -> None:
+        sessions = self._saved_sessions.setdefault(user_id, [])
+        session = {"name": name, "created_at": datetime.now(UTC).isoformat()}
+        if source_context_id is not None:
+            session["source_context_id"] = source_context_id
+        sessions.append(session)
+
+    async def list_saved_sessions(self, user_id: str) -> list[dict[str, str]]:
+        return [dict(session) for session in self._saved_sessions.get(user_id, [])]
+
+    async def get_last_tokens_used_for_context(self, context_id: str) -> int:
+        return self._context_last_tokens_used.get(context_id, 0)
+
+    async def set_last_tokens_used_for_context(self, context_id: str, tokens: int) -> None:
+        self._context_last_tokens_used[context_id] = tokens
+
+    async def get_current_session_for_context(self, context_id: str) -> str | None:
+        return self._context_current_session.get(context_id)
+
+    async def set_current_session_for_context(self, context_id: str, name: str) -> None:
+        self._context_current_session[context_id] = name
+
+    async def clear_current_session_for_context(self, context_id: str) -> None:
+        self._context_current_session.pop(context_id, None)
+
+    async def get_last_tokens_used(self, context_id: str) -> int:
+        return await self.get_last_tokens_used_for_context(context_id)
+
+    async def set_last_tokens_used(self, context_id: str, tokens: int) -> None:
+        await self.set_last_tokens_used_for_context(context_id, tokens)
+
+    async def get_current_session(self, context_id: str) -> str | None:
+        return await self.get_current_session_for_context(context_id)
+
+    async def set_current_session(self, context_id: str, name: str) -> None:
+        await self.set_current_session_for_context(context_id, name)
+
+    async def clear_current_session(self, context_id: str) -> None:
+        await self.clear_current_session_for_context(context_id)

sdk/real.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+from collections.abc import AsyncIterator
+from pathlib import Path
+from urllib.parse import urljoin, urlsplit, urlunsplit
+
+import structlog
+
+from sdk.interface import (
+    Attachment,
+    MessageChunk,
+    MessageResponse,
+    PlatformClient,
+    PlatformError,
+    User,
+    UserSettings,
+)
+from sdk.prototype_state import PrototypeStateStore
+from sdk.upstream_agent_api import AgentApi, MsgEventSendFile, MsgEventTextChunk
+
+logger = structlog.get_logger(__name__)
+
+
+def _ws_debug_enabled() -> bool:
+    value = os.environ.get("SURFACES_DEBUG_WS", "")
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+class RealPlatformClient(PlatformClient):
+    def __init__(
+        self,
+        agent_id: str,
+        agent_base_url: str,
+        prototype_state: PrototypeStateStore,
+        platform: str = "matrix",
+        agent_api_cls=AgentApi,
+    ) -> None:
+        self._agent_id = agent_id
+        self._raw_agent_base_url = agent_base_url
+        self._agent_base_url = self._normalize_agent_base_url(agent_base_url)
+        self._agent_api_cls = agent_api_cls
+        self._prototype_state = prototype_state
+        self._platform = platform
+        self._chat_send_locks: dict[str, asyncio.Lock] = {}
+        if _ws_debug_enabled():
+            logger.warning(
+                "agent_client_initialized",
+                agent_id=self._agent_id,
+                platform=self._platform,
+                raw_base_url=self._raw_agent_base_url,
+                normalized_base_url=self._agent_base_url,
+            )
+
+    @property
+    def agent_id(self) -> str:
+        return self._agent_id
+
+    @property
+    def agent_base_url(self) -> str:
+        return self._agent_base_url
+
+    def _get_chat_send_lock(self, chat_id: str) -> asyncio.Lock:
+        chat_key = str(chat_id)
+        lock = self._chat_send_locks.get(chat_key)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._chat_send_locks[chat_key] = lock
+        return lock
+
+    async def get_or_create_user(
+        self,
+        external_id: str,
+        platform: str,
+        display_name: str | None = None,
+    ) -> User:
+        return await self._prototype_state.get_or_create_user(
+            external_id=external_id,
+            platform=platform,
+            display_name=display_name,
+        )
+
+    async def send_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> MessageResponse:
+        response_parts: list[str] = []
+        sent_attachments: list[Attachment] = []
+        message_id = user_id
+
+        lock = self._get_chat_send_lock(chat_id)
+        async with lock:
+            chat_api = self._build_chat_api(chat_id)
+            try:
+                await chat_api.connect()
+                async for event in self._stream_agent_events(
+                    chat_api, text, attachments=attachments
+                ):
+                    message_id = user_id
+                    if isinstance(event, MsgEventTextChunk) and event.text:
+                        response_parts.append(event.text)
+                    elif isinstance(event, MsgEventSendFile):
+                        attachment = self._attachment_from_send_file_event(event)
+                        if attachment is not None:
+                            sent_attachments.append(attachment)
+            except Exception as exc:
+                raise self._to_platform_error(exc) from exc
+            finally:
+                await self._close_chat_api(chat_api)
+            await self._prototype_state.set_last_tokens_used(str(chat_id), 0)
+
+        response_kwargs = {
+            "message_id": message_id,
+            "response": "".join(response_parts),
+            "tokens_used": 0,
+            "finished": True,
+            "attachments": sent_attachments,
+        }
+        return MessageResponse(**response_kwargs)
+
+    async def stream_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> AsyncIterator[MessageChunk]:
+        lock = self._get_chat_send_lock(chat_id)
+        async with lock:
+            chat_api = self._build_chat_api(chat_id)
+            try:
+                await chat_api.connect()
+                async for event in self._stream_agent_events(
+                    chat_api, text, attachments=attachments
+                ):
+                    if isinstance(event, MsgEventTextChunk):
+                        yield MessageChunk(
+                            message_id=user_id,
+                            delta=event.text,
+                            finished=False,
+                        )
+                    elif isinstance(event, MsgEventSendFile):
+                        continue
+            except Exception as exc:
+                raise self._to_platform_error(exc) from exc
+            finally:
+                await self._close_chat_api(chat_api)
+            await self._prototype_state.set_last_tokens_used(str(chat_id), 0)
+            yield MessageChunk(
+                message_id=user_id,
+                delta="",
+                finished=True,
+                tokens_used=0,
+            )
+
+    async def get_settings(self, user_id: str) -> UserSettings:
+        return await self._prototype_state.get_settings(user_id)
+
+    async def update_settings(self, user_id: str, action) -> None:
+        await self._prototype_state.update_settings(user_id, action)
+
+    async def disconnect_chat(self, chat_id: str) -> None:
+        self._chat_send_locks.pop(str(chat_id), None)
+
+    async def close(self) -> None:
+        self._chat_send_locks.clear()
+
+    async def _stream_agent_events(
+        self,
+        chat_api,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> AsyncIterator[object]:
+        attachment_paths = self._attachment_paths(attachments)
+        event_stream = chat_api.send_message(text, attachments=attachment_paths or None)
+        chunk_index = 0
+        async for event in event_stream:
+            if isinstance(event, MsgEventTextChunk):
+                logger.debug("agent_chunk", index=chunk_index, text=repr(event.text[:40]))
+                chunk_index += 1
+            else:
+                logger.debug("agent_event", index=chunk_index, type=type(event).__name__)
+            yield event
+
+    def _build_chat_api(self, chat_id: str):
+        if _ws_debug_enabled():
+            logger.warning(
+                "agent_chat_api_build",
+                agent_id=self._agent_id,
+                chat_id=str(chat_id),
+                normalized_base_url=self._agent_base_url,
+                ws_url=urljoin(self._agent_base_url, f"v1/agent_ws/{chat_id}/"),
+            )
+        return self._agent_api_cls(
+            agent_id=self._agent_id,
+            base_url=self._agent_base_url,
+            chat_id=str(chat_id),
+        )
+
+    @staticmethod
+    def _normalize_agent_base_url(base_url: str) -> str:
+        parsed = urlsplit(base_url)
+        path = re.sub(r"(?:/v1)?/agent_ws(?:/[^/]+)?/?$", "", parsed.path.rstrip("/"))
+        if path:
+            path = f"{path}/"
+        return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+    @staticmethod
+    async def _close_chat_api(chat_api) -> None:
+        close = getattr(chat_api, "close", None)
+        if callable(close):
+            try:
+                await close()
+            except Exception:
+                pass
+
+    @staticmethod
+    def _to_platform_error(exc: Exception) -> PlatformError:
+        code = getattr(exc, "code", None) or "PLATFORM_CONNECTION_ERROR"
+        return PlatformError(str(exc), code=code)
+
+    @staticmethod
+    def _normalize_workspace_path(location: str) -> str | None:
+        if not location:
+            return None
+
+        path = Path(location)
+        if not path.is_absolute():
+            normalized = path.as_posix()
+            return normalized or None
+
+        parts = path.parts
+        if len(parts) >= 2 and parts[1] == "workspace":
+            relative = Path(*parts[2:]).as_posix()
+            return relative or None
+        if len(parts) >= 3 and parts[1] == "agents":
+            relative = Path(*parts[3:]).as_posix()
+            return relative or None
+
+        relative = path.as_posix().lstrip("/")
+        return relative or None
+
+    @staticmethod
+    def _attachment_paths(attachments: list[Attachment] | None) -> list[str]:
+        if not attachments:
+            return []
+        paths = []
+        for attachment in attachments:
+            if attachment.workspace_path:
+                normalized = RealPlatformClient._normalize_workspace_path(
+                    attachment.workspace_path
+                )
+                if normalized:
+                    paths.append(normalized)
+        return paths
+
+    @staticmethod
+    def _attachment_from_send_file_event(event: MsgEventSendFile) -> Attachment:
+        location = str(event.path)
+        filename = Path(location).name or None
+        workspace_path = RealPlatformClient._normalize_workspace_path(location)
+        return Attachment(
+            url=location,
+            mime_type="application/octet-stream",
+            size=None,
+            filename=filename,
+            workspace_path=workspace_path or None,
+        )

sdk/upstream_agent_api.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_api_root = Path(__file__).resolve().parents[1] / "external" / "platform-agent_api"
+if str(_api_root) not in sys.path:
+    sys.path.insert(0, str(_api_root))
+
+from lambda_agent_api.agent_api import AgentApi, AgentBusyException, AgentException  # noqa: E402
+from lambda_agent_api.server import MsgEventSendFile, MsgEventTextChunk  # noqa: E402
+
+__all__ = [
+    "AgentApi",
+    "AgentBusyException",
+    "AgentException",
+    "MsgEventSendFile",
+    "MsgEventTextChunk",
+]

tests/adapter/matrix/test_agent_registry.py

@@ -0,0 +1,199 @@
+from pathlib import Path
+
+import pytest
+
+from adapter.matrix.agent_registry import AgentRegistryError, load_agent_registry
+
+
+def test_load_agent_registry_reads_yaml_entries(tmp_path: Path):
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: Analyst\n"
+        "  - id: agent-2\n"
+        "    label: Research\n",
+        encoding="utf-8",
+    )
+
+    registry = load_agent_registry(path)
+
+    assert [agent.agent_id for agent in registry.agents] == ["agent-1", "agent-2"]
+    assert registry.get("agent-1").label == "Analyst"
+
+
+def test_agent_registry_agents_sequence_is_immutable(tmp_path: Path):
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: Analyst\n",
+        encoding="utf-8",
+    )
+
+    registry = load_agent_registry(path)
+
+    with pytest.raises(AttributeError):
+        registry.agents.append(  # type: ignore[attr-defined]
+            registry.agents[0]
+        )
+
+
+def test_load_agent_registry_rejects_duplicate_ids(tmp_path: Path):
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: Analyst\n"
+        "  - id: agent-1\n"
+        "    label: Duplicate\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(AgentRegistryError, match="duplicate agent id"):
+        load_agent_registry(path)
+
+
+def test_load_agent_registry_rejects_non_mapping_entries(tmp_path: Path):
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "agents:\n"
+        "  - agent-1\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"):
+        load_agent_registry(path)
+
+
+@pytest.mark.parametrize(
+    "content",
+    [
+        "",
+        "agents: []\n",
+        "agents: agent-1\n",
+        "foo: bar\n",
+    ],
+)
+def test_load_agent_registry_rejects_missing_non_list_and_empty_agents(
+    tmp_path: Path, content: str
+):
+    path = tmp_path / "agents.yaml"
+    path.write_text(content, encoding="utf-8")
+
+    with pytest.raises(AgentRegistryError, match="agents registry must contain a non-empty agents list"):
+        load_agent_registry(path)
+
+
+@pytest.mark.parametrize(
+    "content, expected",
+    [
+        (
+            "agents:\n"
+            "  - label: Analyst\n",
+            "each agent entry requires id and label",
+        ),
+        (
+            "agents:\n"
+            "  - id: agent-1\n",
+            "each agent entry requires id and label",
+        ),
+    ],
+)
+def test_load_agent_registry_rejects_missing_id_or_label(tmp_path: Path, content: str, expected: str):
+    path = tmp_path / "agents.yaml"
+    path.write_text(content, encoding="utf-8")
+
+    with pytest.raises(AgentRegistryError, match=expected):
+        load_agent_registry(path)
+
+
+def test_load_agent_registry_rejects_invalid_top_level_yaml(tmp_path: Path):
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "- id: agent-1\n"
+        "  label: Analyst\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(AgentRegistryError, match="agent registry must be a mapping with an agents list"):
+        load_agent_registry(path)
+
+
+def test_load_agent_registry_rejects_malformed_yaml(tmp_path: Path):
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: Analyst\n"
+        "  - id: agent-2\n"
+        "    label: Research\n"
+        "  - [\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(AgentRegistryError, match="invalid agent registry YAML"):
+        load_agent_registry(path)
+
+
+@pytest.mark.parametrize(
+    "content",
+    [
+        "agents:\n"
+        "  - id: null\n"
+        "    label: Analyst\n",
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: null\n",
+    ],
+)
+def test_load_agent_registry_rejects_null_id_or_label(tmp_path: Path, content: str):
+    path = tmp_path / "agents.yaml"
+    path.write_text(content, encoding="utf-8")
+
+    with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"):
+        load_agent_registry(path)
+
+
+@pytest.mark.parametrize(
+    "content",
+    [
+        "agents:\n"
+        "  - id: '   '\n"
+        "    label: Analyst\n",
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: '   '\n",
+    ],
+)
+def test_load_agent_registry_rejects_blank_id_or_label(tmp_path: Path, content: str):
+    path = tmp_path / "agents.yaml"
+    path.write_text(content, encoding="utf-8")
+
+    with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"):
+        load_agent_registry(path)
+
+
+@pytest.mark.parametrize(
+    "content",
+    [
+        "agents:\n"
+        "  - id: 123\n"
+        "    label: Analyst\n",
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: 456\n",
+        "agents:\n"
+        "  - id: true\n"
+        "    label: Analyst\n",
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: false\n",
+    ],
+)
+def test_load_agent_registry_rejects_non_string_id_or_label(tmp_path: Path, content: str):
+    path = tmp_path / "agents.yaml"
+    path.write_text(content, encoding="utf-8")
+
+    with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"):
+        load_agent_registry(path)

tests/adapter/matrix/test_chat_space.py

@@ -6,8 +6,12 @@ from unittest.mock import AsyncMock
 from nio.api import RoomVisibility
 from nio.responses import RoomCreateError
 
-from adapter.matrix.handlers.chat import make_handle_archive, make_handle_new_chat, make_handle_rename
-from adapter.matrix.store import set_user_meta
+from adapter.matrix.handlers.chat import (
+    make_handle_archive,
+    make_handle_new_chat,
+    make_handle_rename,
+)
+from adapter.matrix.store import get_room_meta, set_user_meta
 from core.auth import AuthManager
 from core.chat import ChatManager
 from core.protocol import IncomingCommand, OutgoingMessage
@@ -28,7 +32,9 @@ async def _setup():
 
 async def test_mat04_new_chat_calls_room_put_state_with_space_id():
     platform, store, chat_mgr, auth_mgr, settings_mgr = await _setup()
-    await set_user_meta(store, "@alice:example.org", {"space_id": "!space:ex", "next_chat_index": 2})
+    await set_user_meta(
+        store, "@alice:example.org", {"space_id": "!space:ex", "next_chat_index": 2}
+    )
 
     client = SimpleNamespace(
         room_create=AsyncMock(return_value=SimpleNamespace(room_id="!newroom:ex")),
@@ -57,6 +63,9 @@ async def test_mat04_new_chat_calls_room_put_state_with_space_id():
     assert kwargs.get("room_id") == "!space:ex"
     assert kwargs.get("event_type") == "m.space.child"
     assert kwargs.get("state_key") == "!newroom:ex"
+    room_meta = await get_room_meta(store, "!newroom:ex")
+    assert room_meta is not None
+    assert room_meta["platform_chat_id"] == "1"
     assert any(isinstance(item, OutgoingMessage) and "Test" in item.text for item in result)
 
 
@@ -166,10 +175,14 @@ async def test_mat11b_rename_from_unregistered_room_returns_error_message():
 
 async def test_mat12_room_create_error_returns_user_message():
     platform, store, chat_mgr, auth_mgr, settings_mgr = await _setup()
-    await set_user_meta(store, "@alice:example.org", {"space_id": "!space:ex", "next_chat_index": 2})
+    await set_user_meta(
+        store, "@alice:example.org", {"space_id": "!space:ex", "next_chat_index": 2}
+    )
 
     client = SimpleNamespace(
-        room_create=AsyncMock(return_value=RoomCreateError(message="rate limited", status_code="429")),
+        room_create=AsyncMock(
+            return_value=RoomCreateError(message="rate limited", status_code="429")
+        ),
         room_put_state=AsyncMock(),
         room_invite=AsyncMock(),
     )

tests/adapter/matrix/test_context_commands.py

@@ -0,0 +1,350 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from adapter.matrix.bot import MatrixBot, build_runtime
+from adapter.matrix.handlers import register_matrix_handlers
+from adapter.matrix.handlers.context_commands import (
+    make_handle_context,
+    make_handle_load,
+    make_handle_reset,
+    make_handle_save,
+)
+from adapter.matrix.store import (
+    get_load_pending,
+    set_load_pending,
+    set_room_meta,
+)
+from core.protocol import IncomingCommand, OutgoingMessage
+from core.store import InMemoryStore
+from sdk.interface import MessageResponse
+from sdk.mock import MockPlatformClient
+from sdk.prototype_state import PrototypeStateStore
+
+
+class MatrixCommandPlatform(MockPlatformClient):
+    def __init__(self) -> None:
+        super().__init__()
+        self._prototype_state = PrototypeStateStore()
+        self._agent_api = object()
+        self.disconnect_chat = AsyncMock()
+        self.send_message = AsyncMock(
+            return_value=MessageResponse(
+                message_id="msg-1",
+                response="ok",
+                tokens_used=0,
+                finished=True,
+            )
+        )
+
+
+@pytest.fixture(autouse=True)
+def clear_matrix_registry_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MATRIX_AGENT_REGISTRY_PATH", raising=False)
+    monkeypatch.delenv("MATRIX_PLATFORM_BACKEND", raising=False)
+
+
+@pytest.mark.asyncio
+async def test_save_command_auto_name_records_session():
+    platform = MatrixCommandPlatform()
+    store = InMemoryStore()
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41"},
+    )
+    handler = make_handle_save(
+        agent_api=platform._agent_api,
+        store=store,
+        prototype_state=platform._prototype_state,
+    )
+    event = IncomingCommand(
+        user_id="u1",
+        platform="matrix",
+        chat_id="!room:example.org",
+        command="save",
+        args=[],
+    )
+
+    result = await handler(event, None, platform, None, None)
+
+    assert len(result) == 1
+    assert isinstance(result[0], OutgoingMessage)
+    assert "Запрос на сохранение отправлен агенту" in result[0].text
+    sessions = await platform._prototype_state.list_saved_sessions("u1")
+    assert len(sessions) == 1
+    assert sessions[0]["name"].startswith("context-")
+    assert sessions[0]["source_context_id"] == "41"
+
+
+@pytest.mark.asyncio
+async def test_save_command_with_name_uses_given_name():
+    platform = MatrixCommandPlatform()
+    store = InMemoryStore()
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41"},
+    )
+    handler = make_handle_save(
+        agent_api=platform._agent_api,
+        store=store,
+        prototype_state=platform._prototype_state,
+    )
+    event = IncomingCommand(
+        user_id="u1",
+        platform="matrix",
+        chat_id="!room:example.org",
+        command="save",
+        args=["my-session"],
+    )
+
+    await handler(event, None, platform, None, None)
+
+    sessions = await platform._prototype_state.list_saved_sessions("u1")
+    assert [session["name"] for session in sessions] == ["my-session"]
+
+
+@pytest.mark.asyncio
+async def test_load_command_shows_numbered_list_and_sets_pending():
+    platform = MatrixCommandPlatform()
+    runtime = build_runtime(platform=platform)
+    await runtime.chat_mgr.get_or_create(
+        user_id="u1",
+        chat_id="C1",
+        platform="matrix",
+        surface_ref="!room:example.org",
+        name="Chat 1",
+    )
+    await platform._prototype_state.add_saved_session("u1", "session-a")
+    await platform._prototype_state.add_saved_session("u1", "session-b")
+
+    handler = make_handle_load(store=runtime.store, prototype_state=platform._prototype_state)
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="load", args=[])
+
+    result = await handler(
+        event,
+        runtime.auth_mgr,
+        platform,
+        runtime.chat_mgr,
+        runtime.settings_mgr,
+    )
+
+    assert "1. session-a" in result[0].text
+    assert "2. session-b" in result[0].text
+    pending = await get_load_pending(runtime.store, "u1", "!room:example.org")
+    assert pending is not None
+    assert [session["name"] for session in pending["saves"]] == ["session-a", "session-b"]
+
+
+@pytest.mark.asyncio
+async def test_load_command_without_saved_sessions_reports_empty():
+    platform = MatrixCommandPlatform()
+    store = InMemoryStore()
+    handler = make_handle_load(store=store, prototype_state=platform._prototype_state)
+    event = IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="load", args=[])
+
+    result = await handler(event, None, platform, None, None)
+
+    assert "Нет сохранённых сессий" in result[0].text
+
+
+@pytest.mark.asyncio
+async def test_reset_command_assigns_new_platform_chat_id():
+    from adapter.matrix.store import get_platform_chat_id, set_room_meta
+    from sdk.prototype_state import PrototypeStateStore
+
+    prototype_state = PrototypeStateStore()
+    platform = MatrixCommandPlatform()
+    runtime = build_runtime(platform=platform)
+    store = runtime.store
+
+    await set_room_meta(store, "!room:example.org", {"platform_chat_id": "7"})
+
+    handler = make_handle_reset(store=store, prototype_state=prototype_state)
+    event = IncomingCommand(
+        user_id="u1",
+        platform="matrix",
+        chat_id="!room:example.org",
+        command="reset",
+        args=[],
+    )
+
+    result = await handler(
+        event,
+        runtime.auth_mgr,
+        platform,
+        runtime.chat_mgr,
+        runtime.settings_mgr,
+    )
+
+    new_id = await get_platform_chat_id(store, "!room:example.org")
+    assert new_id != "7"
+    assert new_id == "1"
+    assert "сброшен" in result[0].text.lower()
+
+
+@pytest.mark.asyncio
+async def test_clear_command_rotates_only_current_room_and_disconnects_old_upstream_chat():
+    from adapter.matrix.store import get_platform_chat_id
+
+    platform = MatrixCommandPlatform()
+    runtime = build_runtime(platform=platform)
+    await runtime.chat_mgr.get_or_create(
+        user_id="u1",
+        chat_id="C1",
+        platform="matrix",
+        surface_ref="!room-a:example.org",
+        name="Chat A",
+    )
+    await runtime.chat_mgr.get_or_create(
+        user_id="u1",
+        chat_id="C2",
+        platform="matrix",
+        surface_ref="!room-b:example.org",
+        name="Chat B",
+    )
+    await set_room_meta(
+        runtime.store,
+        "!room-a:example.org",
+        {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41"},
+    )
+    await set_room_meta(
+        runtime.store,
+        "!room-b:example.org",
+        {"chat_id": "C2", "matrix_user_id": "u1", "platform_chat_id": "99"},
+    )
+
+    handler = make_handle_reset(store=runtime.store, prototype_state=platform._prototype_state)
+    event = IncomingCommand(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C1",
+        command="clear",
+        args=[],
+    )
+
+    result = await handler(
+        event,
+        runtime.auth_mgr,
+        platform,
+        runtime.chat_mgr,
+        runtime.settings_mgr,
+    )
+
+    room_a_chat_id = await get_platform_chat_id(runtime.store, "!room-a:example.org")
+    room_b_chat_id = await get_platform_chat_id(runtime.store, "!room-b:example.org")
+    assert room_a_chat_id == "1"
+    assert room_a_chat_id != "41"
+    assert room_b_chat_id == "99"
+    platform.disconnect_chat.assert_awaited_once_with("41")
+    assert "сброшен" in result[0].text.lower()
+
+
+def test_register_matrix_handlers_exposes_clear_and_optional_reset_alias():
+    dispatcher = SimpleNamespace(register=Mock())
+
+    register_matrix_handlers(
+        dispatcher,
+        client=object(),
+        store=object(),
+        registry=None,
+        prototype_state=PrototypeStateStore(),
+    )
+
+    clear_calls = [
+        call
+        for call in dispatcher.register.call_args_list
+        if call.args[:2] == (IncomingCommand, "clear")
+    ]
+    reset_calls = [
+        call
+        for call in dispatcher.register.call_args_list
+        if call.args[:2] == (IncomingCommand, "reset")
+    ]
+    assert clear_calls
+    assert len(reset_calls) <= 1
+
+
+@pytest.mark.asyncio
+async def test_context_command_shows_current_snapshot():
+    platform = MatrixCommandPlatform()
+    runtime = build_runtime(platform=platform)
+    await runtime.chat_mgr.get_or_create(
+        user_id="u1",
+        chat_id="C1",
+        platform="matrix",
+        surface_ref="!room:example.org",
+        name="Chat 1",
+    )
+    await set_room_meta(
+        runtime.store,
+        "!room:example.org",
+        {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41"},
+    )
+    await platform._prototype_state.set_current_session("41", "session-a")
+    await platform._prototype_state.set_last_tokens_used("41", 99)
+    await platform._prototype_state.add_saved_session("u1", "session-a")
+    handler = make_handle_context(store=runtime.store, prototype_state=platform._prototype_state)
+    event = IncomingCommand(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C1",
+        command="context",
+        args=[],
+    )
+
+    result = await handler(
+        event,
+        runtime.auth_mgr,
+        platform,
+        runtime.chat_mgr,
+        runtime.settings_mgr,
+    )
+
+    assert "Контекст чата: 41" in result[0].text
+    assert "Сессия: session-a" in result[0].text
+    assert "Токены (последний ответ): 99" in result[0].text
+    assert "session-a" in result[0].text
+
+
+@pytest.mark.asyncio
+async def test_bot_intercepts_numeric_load_selection():
+    platform = MatrixCommandPlatform()
+    runtime = build_runtime(platform=platform)
+    await set_room_meta(
+        runtime.store,
+        "!room:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "41",
+        },
+    )
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        room_send=AsyncMock(),
+    )
+    bot = MatrixBot(client, runtime)
+    await set_load_pending(
+        runtime.store,
+        "@alice:example.org",
+        "!room:example.org",
+        {"saves": [{"name": "session-a", "created_at": "2026-04-17T00:00:00+00:00"}]},
+    )
+    room = SimpleNamespace(room_id="!room:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="1")
+
+    await bot.on_room_message(room, event)
+
+    platform.send_message.assert_awaited_once()
+    assert await platform._prototype_state.get_current_session("41") == "session-a"
+    assert await platform._prototype_state.get_current_session("C1") == "session-a"
+    client.room_send.assert_awaited_once_with(
+        "!room:example.org",
+        "m.room.message",
+        {"msgtype": "m.text", "body": "Запрос на загрузку отправлен агенту: session-a"},
+    )

tests/adapter/matrix/test_converter.py

@@ -37,7 +37,41 @@ def image_event(url: str = "mxc://x/img", mime: str = "image/jpeg"):
     )
 
 
-async def test_plain_text_to_incoming_message():
+def content_file_event():
+    return SimpleNamespace(
+        sender="@a:m.org",
+        body="doc.pdf",
+        event_id="$e4",
+        msgtype=None,
+        replyto_event_id=None,
+        content={
+            "msgtype": "m.file",
+            "body": "nested.pdf",
+            "url": "mxc://x/nested",
+            "info": {"mimetype": "application/pdf"},
+        },
+    )
+
+
+def source_only_content_file_event():
+    return SimpleNamespace(
+        sender="@a:m.org",
+        body="doc.pdf",
+        event_id="$e5",
+        msgtype=None,
+        replyto_event_id=None,
+        source={
+            "content": {
+                "msgtype": "m.file",
+                "body": "source-only.pdf",
+                "url": "mxc://x/source-only",
+                "info": {"mimetype": "application/pdf"},
+            }
+        },
+    )
+
+
+def test_plain_text_to_incoming_message():
     result = from_room_event(text_event("Hello"), room_id="!r:m.org", chat_id="C1")
     assert isinstance(result, IncomingMessage)
     assert result.text == "Hello"
@@ -46,20 +80,48 @@ async def test_plain_text_to_incoming_message():
     assert result.attachments == []
 
 
-async def test_bang_command_to_incoming_command():
+def test_bang_command_to_incoming_command():
     result = from_room_event(text_event("!new Analysis"), room_id="!r:m.org", chat_id="C1")
     assert isinstance(result, IncomingCommand)
     assert result.command == "new"
     assert result.args == ["Analysis"]
 
 
-async def test_skills_alias_to_settings_command():
+def test_list_command_maps_to_matrix_list_attachments():
+    result = from_room_event(text_event("!list"), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingCommand)
+    assert result.command == "matrix_list_attachments"
+    assert result.args == []
+
+
+def test_remove_all_maps_to_matrix_remove_attachment():
+    result = from_room_event(text_event("!remove all"), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingCommand)
+    assert result.command == "matrix_remove_attachment"
+    assert result.args == ["all"]
+
+
+def test_remove_index_maps_to_matrix_remove_attachment():
+    result = from_room_event(text_event("!remove 2"), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingCommand)
+    assert result.command == "matrix_remove_attachment"
+    assert result.args == ["2"]
+
+
+def test_remove_arbitrary_index_maps_to_matrix_remove_attachment():
+    result = from_room_event(text_event("!remove 99"), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingCommand)
+    assert result.command == "matrix_remove_attachment"
+    assert result.args == ["99"]
+
+
+def test_skills_alias_to_settings_command():
     result = from_command("!skills", sender="@a:m.org", chat_id="C1")
     assert isinstance(result, IncomingCommand)
     assert result.command == "settings_skills"
 
 
-async def test_yes_to_callback():
+def test_yes_to_callback():
     result = from_room_event(text_event("!yes"), room_id="!room:example.org", chat_id="C7")
     assert isinstance(result, IncomingCallback)
     assert result.action == "confirm"
@@ -67,7 +129,7 @@ async def test_yes_to_callback():
     assert result.payload["room_id"] == "!room:example.org"
 
 
-async def test_no_to_callback():
+def test_no_to_callback():
     result = from_room_event(text_event("!no"), room_id="!room:example.org", chat_id="C7")
     assert isinstance(result, IncomingCallback)
     assert result.action == "cancel"
@@ -75,7 +137,7 @@ async def test_no_to_callback():
     assert result.payload["room_id"] == "!room:example.org"
 
 
-async def test_file_attachment():
+def test_file_attachment():
     result = from_room_event(file_event(), room_id="!r:m.org", chat_id="C1")
     assert isinstance(result, IncomingMessage)
     assert len(result.attachments) == 1
@@ -86,11 +148,32 @@ async def test_file_attachment():
     assert a.mime_type == "application/pdf"
 
 
-async def test_image_attachment():
+def test_image_attachment():
     result = from_room_event(image_event(), room_id="!r:m.org", chat_id="C1")
     assert result.attachments[0].type == "image"
+    assert result.attachments[0].filename == "img.jpg"
     assert result.attachments[0].mime_type == "image/jpeg"
 
 
+def test_attachment_falls_back_to_content_payload():
+    result = from_room_event(content_file_event(), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingMessage)
+    a = result.attachments[0]
+    assert a.type == "document"
+    assert a.url == "mxc://x/nested"
+    assert a.filename == "nested.pdf"
+    assert a.mime_type == "application/pdf"
+
+
+def test_attachment_falls_back_to_source_content_payload():
+    result = from_room_event(source_only_content_file_event(), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingMessage)
+    a = result.attachments[0]
+    assert a.type == "document"
+    assert a.url == "mxc://x/source-only"
+    assert a.filename == "source-only.pdf"
+    assert a.mime_type == "application/pdf"
+
+
 def test_converter_module_does_not_expose_reaction_callbacks():
     assert not hasattr(converter, "from_reaction")

tests/adapter/matrix/test_dispatcher.py

@@ -1,15 +1,42 @@
 from __future__ import annotations
 
+import importlib
 from types import SimpleNamespace
 from unittest.mock import AsyncMock
 
+import pytest
+from nio import (
+    RoomMessageAudio,
+    RoomMessageFile,
+    RoomMessageImage,
+    RoomMessageText,
+    RoomMessageVideo,
+)
 from nio.api import RoomVisibility
 from nio.responses import SyncResponse
 
+from adapter.matrix.agent_registry import AgentDefinition, AgentRegistry
 from adapter.matrix.bot import MatrixBot, build_runtime, prepare_live_sync
 from adapter.matrix.handlers.auth import handle_invite
-from adapter.matrix.store import get_room_meta, get_user_meta, set_user_meta
-from core.protocol import IncomingCallback, IncomingCommand, OutgoingMessage
+from adapter.matrix.routed_platform import RoutedPlatformClient
+from adapter.matrix.store import (
+    add_staged_attachment,
+    get_platform_chat_id,
+    get_room_meta,
+    get_staged_attachments,
+    get_user_meta,
+    set_load_pending,
+    set_room_meta,
+    set_user_meta,
+)
+from core.protocol import (
+    Attachment,
+    IncomingCallback,
+    IncomingCommand,
+    IncomingMessage,
+    OutgoingMessage,
+)
+from sdk.interface import PlatformError
 from sdk.mock import MockPlatformClient
 
 
@@ -17,7 +44,9 @@ async def test_matrix_dispatcher_registers_custom_handlers():
     runtime = build_runtime(platform=MockPlatformClient())
     current_chat_id = "C9"
 
-    start = IncomingCommand(user_id="u1", platform="matrix", chat_id=current_chat_id, command="start")
+    start = IncomingCommand(
+        user_id="u1", platform="matrix", chat_id=current_chat_id, command="start"
+    )
     await runtime.dispatcher.dispatch(start)
 
     new = IncomingCommand(
@@ -41,7 +70,7 @@ async def test_matrix_dispatcher_registers_custom_handlers():
         user_id="u1", platform="matrix", chat_id=current_chat_id, command="settings_skills"
     )
     result = await runtime.dispatcher.dispatch(skills)
-    assert any(isinstance(r, OutgoingMessage) and "!skill on/off" in r.text for r in result)
+    assert any(isinstance(r, OutgoingMessage) and "mvp" in r.text.lower() for r in result)
 
     toggle = IncomingCallback(
         user_id="u1",
@@ -51,7 +80,7 @@ async def test_matrix_dispatcher_registers_custom_handlers():
         payload={"skill_index": 2},
     )
     result = await runtime.dispatcher.dispatch(toggle)
-    assert any(isinstance(r, OutgoingMessage) and "fetch-url" in r.text for r in result)
+    assert any(isinstance(r, OutgoingMessage) and "mvp" in r.text.lower() for r in result)
 
 
 async def test_new_chat_creates_real_matrix_room_when_client_available():
@@ -75,15 +104,14 @@ async def test_new_chat_creates_real_matrix_room_when_client_available():
     )
     result = await runtime.dispatcher.dispatch(new)
 
-    client.room_create.assert_awaited_once_with(
-        name="Research",
-        visibility=RoomVisibility.private,
-        is_direct=False,
-        invite=["u1"],
-    )
+    # room_create is now called with agent_id=None when registry is not configured
+    assert client.room_create.await_count >= 1
     client.room_put_state.assert_awaited_once()
     put_call = client.room_put_state.call_args
-    assert put_call.kwargs.get("room_id") == "!space:example" or put_call.args[0] == "!space:example"
+    assert (
+        put_call.kwargs.get("room_id") == "!space:example"
+        or put_call.args[0] == "!space:example"
+    )
     chats = await runtime.chat_mgr.list_active("u1")
     assert [c.chat_id for c in chats] == ["C7"]
     assert [c.surface_ref for c in chats] == ["!r2:example"]
@@ -129,7 +157,10 @@ async def test_invite_event_creates_space_and_chat_room():
 
     client.room_put_state.assert_awaited_once()
     put_state_call = client.room_put_state.call_args
-    assert put_state_call.kwargs.get("event_type") == "m.space.child" or put_state_call.args[1] == "m.space.child"
+    assert (
+        put_state_call.kwargs.get("event_type") == "m.space.child"
+        or put_state_call.args[1] == "m.space.child"
+    )
 
     user_meta = await get_user_meta(runtime.store, "@alice:example.org")
     assert user_meta is not None
@@ -178,7 +209,9 @@ async def test_invite_event_is_idempotent_per_user():
         runtime.chat_mgr,
     )
 
+    assert client.join.await_count == 2
     assert client.room_create.await_count == 2
+    assert client.room_send.await_count == 2
 
 
 async def test_bot_ignores_its_own_messages():
@@ -196,11 +229,731 @@ async def test_bot_ignores_its_own_messages():
     bot._send_all.assert_not_awaited()
 
 
-async def test_mat11_settings_returns_dashboard():
+async def test_bot_degrades_platform_errors_to_user_reply():
+    runtime = build_runtime(platform=MockPlatformClient())
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        room_send=AsyncMock(),
+    )
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(
+        side_effect=PlatformError("Missing Authentication header", code="401")
+    )
+    room = SimpleNamespace(room_id="!dm:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="hello")
+
+    await bot.on_room_message(room, event)
+
+    client.room_send.assert_awaited_once_with(
+        "!dm:example.org",
+        "m.room.message",
+        {
+            "msgtype": "m.text",
+            "body": "Сервис временно недоступен. Попробуйте ещё раз позже.",
+        },
+    )
+
+
+async def test_bot_assigns_platform_chat_id_for_existing_managed_room():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {"chat_id": "C1", "matrix_user_id": "@alice:example.org"},
+    )
+    client = SimpleNamespace(user_id="@bot:example.org")
+    bot = MatrixBot(client, runtime)
+    bot._send_all = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!chat1:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="hello")
+
+    await bot.on_room_message(room, event)
+
+    assert await get_platform_chat_id(runtime.store, "!chat1:example.org") == "1"
+    runtime.dispatcher.dispatch.assert_awaited_once()
+
+
+async def test_bot_keeps_local_chat_id_for_plain_messages():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "41",
+        },
+    )
+    client = SimpleNamespace(user_id="@bot:example.org")
+    bot = MatrixBot(client, runtime)
+    bot._send_all = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!chat1:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="hello")
+
+    await bot.on_room_message(room, event)
+
+    dispatched = runtime.dispatcher.dispatch.await_args.args[0]
+    assert dispatched.chat_id == "C1"
+    assert dispatched.text == "hello"
+
+
+async def test_bot_downloads_matrix_file_to_workspace_before_staging(tmp_path, monkeypatch):
+    monkeypatch.setenv("SURFACES_WORKSPACE_DIR", str(tmp_path))
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "41",
+        },
+    )
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        download=AsyncMock(return_value=SimpleNamespace(body=b"%PDF-1.7")),
+    )
+    bot = MatrixBot(client, runtime)
+    bot._send_all = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!chat1:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="report.pdf",
+        msgtype="m.file",
+        replyto_event_id=None,
+        url="mxc://server/id",
+        mimetype="application/pdf",
+    )
+
+    await bot.on_room_message(room, event)
+
+    runtime.dispatcher.dispatch.assert_not_awaited()
+    staged = await get_staged_attachments(runtime.store, "!chat1:example.org", "@alice:example.org")
+    assert staged[0]["workspace_path"] is not None
+    assert (tmp_path / staged[0]["workspace_path"]).read_bytes() == b"%PDF-1.7"
+    bot._send_all.assert_not_awaited()
+
+
+async def test_bot_downloads_matrix_file_to_configured_agent_workspace(tmp_path, monkeypatch):
+    monkeypatch.setenv("SURFACES_WORKSPACE_DIR", str(tmp_path / "agents"))
+    runtime = build_runtime(platform=MockPlatformClient())
+    runtime.registry = AgentRegistry(
+        [
+            AgentDefinition(
+                agent_id="agent-17",
+                label="Agent 17",
+                base_url="http://lambda.coredump.ru:7000/agent_17/",
+                workspace_path=str(tmp_path / "agents" / "17"),
+            )
+        ],
+        user_agents={"@alice:example.org": "agent-17"},
+    )
+    await set_room_meta(
+        runtime.store,
+        "!chat17:example.org",
+        {
+            "chat_id": "C17",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "17",
+            "agent_id": "agent-17",
+        },
+    )
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        download=AsyncMock(return_value=SimpleNamespace(body=b"%PDF-1.7")),
+    )
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!chat17:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="report.pdf",
+        msgtype="m.file",
+        replyto_event_id=None,
+        url="mxc://server/id",
+        mimetype="application/pdf",
+    )
+
+    await bot.on_room_message(room, event)
+
+    staged = await get_staged_attachments(
+        runtime.store, "!chat17:example.org", "@alice:example.org"
+    )
+    assert staged[0]["workspace_path"] == "report.pdf"
+    assert (
+        tmp_path / "agents" / "17" / staged[0]["workspace_path"]
+    ).read_bytes() == b"%PDF-1.7"
+
+
+async def test_bot_uploads_agent_output_from_configured_agent_workspace(tmp_path, monkeypatch):
+    monkeypatch.setenv("SURFACES_WORKSPACE_DIR", str(tmp_path / "agents"))
+    output_file = tmp_path / "agents" / "17" / "result.txt"
+    output_file.parent.mkdir(parents=True)
+    output_file.write_text("ready", encoding="utf-8")
+    runtime = build_runtime(platform=MockPlatformClient())
+    runtime.registry = AgentRegistry(
+        [
+            AgentDefinition(
+                agent_id="agent-17",
+                label="Agent 17",
+                base_url="http://lambda.coredump.ru:7000/agent_17/",
+                workspace_path=str(tmp_path / "agents" / "17"),
+            )
+        ],
+        user_agents={"@alice:example.org": "agent-17"},
+    )
+    await set_room_meta(
+        runtime.store,
+        "!chat17:example.org",
+        {
+            "chat_id": "C17",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "17",
+            "agent_id": "agent-17",
+        },
+    )
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        upload=AsyncMock(return_value=(SimpleNamespace(content_uri="mxc://server/result"), {})),
+        room_send=AsyncMock(),
+    )
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(
+        return_value=[
+            OutgoingMessage(
+                chat_id="C17",
+                text="Файл готов",
+                attachments=[
+                    Attachment(
+                        type="document",
+                        filename="result.txt",
+                        mime_type="text/plain",
+                        workspace_path="result.txt",
+                    )
+                ],
+            )
+        ]
+    )
+    room = SimpleNamespace(room_id="!chat17:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="сделай отчёт",
+        msgtype="m.text",
+        replyto_event_id=None,
+    )
+
+    await bot.on_room_message(room, event)
+
+    uploaded_handle = client.upload.await_args.args[0]
+    assert uploaded_handle.name == str(output_file)
+    assert client.room_send.await_args_list[1].args[2]["url"] == "mxc://server/result"
+
+
+async def test_file_only_event_is_staged_and_does_not_dispatch():
+    runtime = build_runtime(platform=MockPlatformClient())
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    bot._materialize_incoming_attachments = AsyncMock(
+        return_value=IncomingMessage(
+            user_id="@alice:example.org",
+            platform="matrix",
+            chat_id="!r:example.org",
+            text="",
+            attachments=[
+                Attachment(
+                    type="document",
+                    filename="report.pdf",
+                    workspace_path="surfaces/matrix/alice/r/inbox/report.pdf",
+                    mime_type="application/pdf",
+                )
+            ],
+        )
+    )
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="report.pdf",
+        msgtype="m.file",
+        url="mxc://hs/id",
+        mimetype="application/pdf",
+        replyto_event_id=None,
+    )
+
+    await bot.on_room_message(room, event)
+
+    runtime.dispatcher.dispatch.assert_not_awaited()
+    staged = await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org")
+    assert [item["filename"] for item in staged] == ["report.pdf"]
+    client.room_send.assert_not_awaited()
+
+
+async def test_list_command_returns_current_staged_attachments():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {"filename": "a.pdf", "workspace_path": "a.pdf"},
+    )
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {"filename": "b.pdf", "workspace_path": "b.pdf"},
+    )
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org", body="!list", msgtype="m.text", replyto_event_id=None
+    )
+
+    await bot.on_room_message(room, event)
+
+    runtime.dispatcher.dispatch.assert_not_awaited()
+    body = client.room_send.await_args.args[2]["body"]
+    assert "1. a.pdf" in body
+    assert "2. b.pdf" in body
+
+
+async def test_remove_invalid_index_returns_short_error():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {"filename": "a.pdf", "workspace_path": "a.pdf"},
+    )
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org", body="!remove 9", msgtype="m.text", replyto_event_id=None
+    )
+
+    await bot.on_room_message(room, event)
+
+    runtime.dispatcher.dispatch.assert_not_awaited()
+    assert client.room_send.await_args.args[2]["body"] == "Нет такого вложения."
+
+
+async def test_remove_attachment_updates_list_and_state():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {"filename": "a.pdf", "workspace_path": "a.pdf"},
+    )
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {"filename": "b.pdf", "workspace_path": "b.pdf"},
+    )
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org", body="!remove 1", msgtype="m.text", replyto_event_id=None
+    )
+
+    await bot.on_room_message(room, event)
+
+    runtime.dispatcher.dispatch.assert_not_awaited()
+    staged = await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org")
+    assert [item["filename"] for item in staged] == ["b.pdf"]
+    body = client.room_send.await_args.args[2]["body"]
+    assert "1. b.pdf" in body
+    assert "a.pdf" not in body
+
+
+async def test_remove_all_clears_state():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {"filename": "a.pdf", "workspace_path": "a.pdf"},
+    )
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="!remove all",
+        msgtype="m.text",
+        replyto_event_id=None,
+    )
+
+    await bot.on_room_message(room, event)
+
+    runtime.dispatcher.dispatch.assert_not_awaited()
+    assert await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org") == []
+    assert client.room_send.await_args.args[2]["body"] == "Все вложения удалены."
+
+
+async def test_staged_attachment_commands_are_scoped_by_room_and_user():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await add_staged_attachment(
+        runtime.store,
+        "!r-one:example.org",
+        "@alice:example.org",
+        {"filename": "alice-room-one.pdf", "workspace_path": "alice-room-one.pdf"},
+    )
+    await add_staged_attachment(
+        runtime.store,
+        "!r-two:example.org",
+        "@alice:example.org",
+        {"filename": "alice-room-two.pdf", "workspace_path": "alice-room-two.pdf"},
+    )
+    await add_staged_attachment(
+        runtime.store,
+        "!r-one:example.org",
+        "@bob:example.org",
+        {"filename": "bob-room-one.pdf", "workspace_path": "bob-room-one.pdf"},
+    )
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!r-one:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="!list",
+        msgtype="m.text",
+        replyto_event_id=None,
+    )
+
+    await bot.on_room_message(room, event)
+
+    runtime.dispatcher.dispatch.assert_not_awaited()
+    body = client.room_send.await_args.args[2]["body"]
+    assert "alice-room-one.pdf" in body
+    assert "alice-room-two.pdf" not in body
+    assert "bob-room-one.pdf" not in body
+
+
+async def test_next_normal_message_commits_staged_attachments():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!r:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "41",
+        },
+    )
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {
+            "type": "document",
+            "filename": "report.pdf",
+            "workspace_path": "surfaces/matrix/alice/r/inbox/report.pdf",
+            "mime_type": "application/pdf",
+        },
+    )
+    client = SimpleNamespace(user_id="@bot:example.org")
+    bot = MatrixBot(client, runtime)
+    bot._send_all = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="Проанализируй",
+        msgtype="m.text",
+        replyto_event_id=None,
+    )
+
+    await bot.on_room_message(room, event)
+
+    dispatched = runtime.dispatcher.dispatch.await_args.args[0]
+    assert isinstance(dispatched, IncomingMessage)
+    assert dispatched.text == "Проанализируй"
+    assert [a.workspace_path for a in dispatched.attachments] == [
+        "surfaces/matrix/alice/r/inbox/report.pdf"
+    ]
+    assert await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org") == []
+
+
+async def test_failed_commit_preserves_staged_attachments():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!r:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "41",
+        },
+    )
+    await add_staged_attachment(
+        runtime.store,
+        "!r:example.org",
+        "@alice:example.org",
+        {
+            "type": "document",
+            "filename": "report.pdf",
+            "workspace_path": "surfaces/matrix/alice/r/inbox/report.pdf",
+        },
+    )
+    client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock())
+    bot = MatrixBot(client, runtime)
+    runtime.dispatcher.dispatch = AsyncMock(side_effect=PlatformError("boom"))
+    room = SimpleNamespace(room_id="!r:example.org")
+    event = SimpleNamespace(
+        sender="@alice:example.org",
+        body="Проанализируй",
+        msgtype="m.text",
+        replyto_event_id=None,
+    )
+
+    await bot.on_room_message(room, event)
+
+    staged = await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org")
+    assert [item["filename"] for item in staged] == ["report.pdf"]
+
+
+async def test_bot_keeps_commands_on_local_chat_id():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "41",
+        },
+    )
+    client = SimpleNamespace(user_id="@bot:example.org")
+    bot = MatrixBot(client, runtime)
+    bot._send_all = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!chat1:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="!rename New")
+
+    await bot.on_room_message(room, event)
+
+    dispatched = runtime.dispatcher.dispatch.await_args.args[0]
+    assert dispatched.chat_id == "C1"
+    assert dispatched.command == "rename"
+
+
+async def test_bot_leaves_existing_platform_chat_id_unchanged():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "99",
+        },
+    )
+    client = SimpleNamespace(user_id="@bot:example.org")
+    bot = MatrixBot(client, runtime)
+    bot._send_all = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    room = SimpleNamespace(room_id="!chat1:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="hello")
+
+    await bot.on_room_message(room, event)
+
+    assert await get_platform_chat_id(runtime.store, "!chat1:example.org") == "99"
+    runtime.dispatcher.dispatch.assert_awaited_once()
+
+
+async def test_bot_assigns_platform_chat_id_before_load_selection():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {"chat_id": "C1", "matrix_user_id": "@alice:example.org"},
+    )
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        room_send=AsyncMock(),
+    )
+    bot = MatrixBot(client, runtime)
+    await set_load_pending(
+        runtime.store,
+        "@alice:example.org",
+        "!chat1:example.org",
+        {"saves": [{"name": "session-a", "created_at": "2026-04-17T00:00:00+00:00"}]},
+    )
+    room = SimpleNamespace(room_id="!chat1:example.org")
+    event = SimpleNamespace(sender="@alice:example.org", body="0")
+
+    await bot.on_room_message(room, event)
+
+    assert await get_platform_chat_id(runtime.store, "!chat1:example.org") == "1"
+    client.room_send.assert_awaited_once_with(
+        "!chat1:example.org",
+        "m.room.message",
+        {"msgtype": "m.text", "body": "Отменено."},
+    )
+
+
+async def test_unregistered_room_bootstraps_space_and_chat_on_first_message():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_user_meta(runtime.store, "@alice:example.org", {"next_chat_index": 1})
+    space_resp = SimpleNamespace(room_id="!space:example.org")
+    chat_resp = SimpleNamespace(room_id="!chat1:example.org")
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        room_create=AsyncMock(side_effect=[space_resp, chat_resp]),
+        room_put_state=AsyncMock(),
+        room_send=AsyncMock(),
+    )
+    bot = MatrixBot(client, runtime)
+    room = SimpleNamespace(room_id="!entry:example.org", display_name="Entry")
+    event = SimpleNamespace(sender="@alice:example.org", body="hello")
+
+    await bot.on_room_message(room, event)
+
+    assert client.room_create.await_count == 2
+    first_call = client.room_create.call_args_list[0]
+    second_call = client.room_create.call_args_list[1]
+    assert first_call.kwargs.get("space") is True
+    assert first_call.kwargs.get("invite") == ["@alice:example.org"]
+    assert second_call.kwargs.get("name") == "Чат 1"
+    assert second_call.kwargs.get("invite") == ["@alice:example.org"]
+    client.room_put_state.assert_awaited_once()
+    room_meta = await get_room_meta(runtime.store, "!chat1:example.org")
+    assert room_meta is not None
+    assert room_meta["chat_id"] == "C1"
+    user_meta = await get_user_meta(runtime.store, "@alice:example.org")
+    assert user_meta is not None
+    assert user_meta["space_id"] == "!space:example.org"
+    room_send_calls = client.room_send.await_args_list
+    assert any(call.args[0] == "!chat1:example.org" for call in room_send_calls)
+    assert any(call.args[0] == "!entry:example.org" for call in room_send_calls)
+    entry_meta = await get_room_meta(runtime.store, "!entry:example.org")
+    assert entry_meta == {
+        "matrix_user_id": "@alice:example.org",
+        "redirect_room_id": "!chat1:example.org",
+        "redirect_chat_id": "C1",
+    }
+
+
+async def test_unregistered_room_second_message_reuses_existing_bootstrap():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_user_meta(runtime.store, "@alice:example.org", {"next_chat_index": 1})
+    space_resp = SimpleNamespace(room_id="!space:example.org")
+    chat_resp = SimpleNamespace(room_id="!chat1:example.org")
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        room_create=AsyncMock(side_effect=[space_resp, chat_resp]),
+        room_put_state=AsyncMock(),
+        room_send=AsyncMock(),
+    )
+    bot = MatrixBot(client, runtime)
+    room = SimpleNamespace(room_id="!entry:example.org", display_name="Entry")
+
+    await bot.on_room_message(room, SimpleNamespace(sender="@alice:example.org", body="hello"))
+    await bot.on_room_message(
+        room, SimpleNamespace(sender="@alice:example.org", body="hello again")
+    )
+
+    assert client.room_create.await_count == 2
+    room_send_calls = client.room_send.await_args_list
+    assert any(call.args[0] == "!entry:example.org" for call in room_send_calls)
+    assert any(
+        call.args[0] == "!entry:example.org"
+        and "Рабочий чат уже создан: C1" in call.args[2]["body"]
+        for call in room_send_calls
+    )
+    entry_meta = await get_room_meta(runtime.store, "!entry:example.org")
+    assert entry_meta is not None
+    assert "platform_chat_id" not in entry_meta
+
+
+async def test_unregistered_room_welcome_send_failure_does_not_repeat_bootstrap():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_user_meta(runtime.store, "@alice:example.org", {"next_chat_index": 1})
+    space_resp = SimpleNamespace(room_id="!space:example.org")
+    chat_resp = SimpleNamespace(room_id="!chat1:example.org")
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        room_create=AsyncMock(side_effect=[space_resp, chat_resp]),
+        room_put_state=AsyncMock(),
+        room_send=AsyncMock(side_effect=[RuntimeError("welcome failed"), None]),
+    )
+    bot = MatrixBot(client, runtime)
+    room = SimpleNamespace(room_id="!entry:example.org", display_name="Entry")
+
+    with pytest.raises(RuntimeError, match="welcome failed"):
+        await bot.on_room_message(room, SimpleNamespace(sender="@alice:example.org", body="hello"))
+
+    entry_meta = await get_room_meta(runtime.store, "!entry:example.org")
+    assert entry_meta == {
+        "matrix_user_id": "@alice:example.org",
+        "redirect_room_id": "!chat1:example.org",
+        "redirect_chat_id": "C1",
+    }
+
+    await bot.on_room_message(
+        room, SimpleNamespace(sender="@alice:example.org", body="hello again")
+    )
+
+    assert client.room_create.await_count == 2
+    room_send_calls = client.room_send.await_args_list
+    assert any(
+        call.args[0] == "!entry:example.org"
+        and "Рабочий чат уже создан: C1" in call.args[2]["body"]
+        for call in room_send_calls
+    )
+
+
+async def test_unregistered_room_creates_new_chat_in_existing_space():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_user_meta(
+        runtime.store,
+        "@alice:example.org",
+        {"space_id": "!space:example.org", "next_chat_index": 4},
+    )
+    chat_resp = SimpleNamespace(room_id="!chat4:example.org")
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        room_create=AsyncMock(return_value=chat_resp),
+        room_put_state=AsyncMock(),
+        room_send=AsyncMock(),
+    )
+    bot = MatrixBot(client, runtime)
+    room = SimpleNamespace(room_id="!entry:example.org", display_name="Entry")
+    event = SimpleNamespace(sender="@alice:example.org", body="hello")
+
+    await bot.on_room_message(room, event)
+
+    client.room_create.assert_awaited_once_with(
+        name="Чат 4",
+        visibility=RoomVisibility.private,
+        is_direct=False,
+        invite=["@alice:example.org"],
+    )
+    client.room_put_state.assert_awaited_once()
+    room_meta = await get_room_meta(runtime.store, "!chat4:example.org")
+    assert room_meta is not None
+    assert room_meta["chat_id"] == "C4"
+
+
+async def test_mat11_settings_returns_mvp_unavailable_message():
     runtime = build_runtime(platform=MockPlatformClient())
     current_chat_id = "C9"
 
-    start = IncomingCommand(user_id="u1", platform="matrix", chat_id=current_chat_id, command="start")
+    start = IncomingCommand(
+        user_id="u1", platform="matrix", chat_id=current_chat_id, command="start"
+    )
     await runtime.dispatcher.dispatch(start)
 
     settings_cmd = IncomingCommand(
@@ -208,15 +961,10 @@ async def test_mat11_settings_returns_dashboard():
     )
     result = await runtime.dispatcher.dispatch(settings_cmd)
 
-    assert len(result) >= 1
+    assert len(result) == 1
     text = result[0].text
-    assert "Скиллы" in text or "скиллы" in text.lower()
-    assert "Личность" in text
-    assert "Безопасность" in text
-    assert "Активные чаты" in text
-    assert "Изменить" not in text
-    assert "!connectors" not in text
-    assert "!whoami" not in text
+    assert "недоступна" in text.lower()
+    assert "mvp" in text.lower()
 
 
 async def test_mat12_help_returns_command_reference():
@@ -229,10 +977,29 @@ async def test_mat12_help_returns_command_reference():
     assert len(result) == 1
     text = result[0].text
     assert "!new" in text
+    assert "!chats" in text
     assert "!rename" in text
     assert "!archive" in text
-    assert "!settings" in text
+    assert "!clear" in text
+    assert "!list" in text
     assert "!yes" in text
+    assert "!context" not in text
+    assert "!save" not in text
+    assert "!load" not in text
+    assert "!agent" not in text
+    assert "!settings" not in text
+    assert "!skills" not in text
+
+
+async def test_unknown_command_returns_helpful_message():
+    runtime = build_runtime(platform=MockPlatformClient())
+
+    result = await runtime.dispatcher.dispatch(
+        IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="clear")
+    )
+
+    assert len(result) == 1
+    assert "неизвестная команда" in result[0].text.lower()
 
 
 async def test_prepare_live_sync_returns_next_batch_from_bootstrap_sync():
@@ -254,3 +1021,90 @@ async def test_prepare_live_sync_returns_next_batch_from_bootstrap_sync():
 
     client.sync.assert_awaited_once_with(timeout=0, full_state=True)
     assert since == "s123"
+
+
+async def test_build_runtime_uses_routed_platform_when_matrix_backend_is_real(
+    monkeypatch, tmp_path
+):
+    registry_path = tmp_path / "agents.yaml"
+    registry_path.write_text(
+        "agents:\n  - id: agent-1\n    label: Analyst\n", encoding="utf-8"
+    )
+    monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real")
+    monkeypatch.setenv("AGENT_BASE_URL", "http://agent.example")
+    monkeypatch.setenv("MATRIX_AGENT_REGISTRY_PATH", str(registry_path))
+
+    runtime = build_runtime()
+
+    assert isinstance(runtime.platform, RoutedPlatformClient)
+
+
+async def test_matrix_main_closes_platform_without_connecting_root_agent(monkeypatch):
+    bot_module = importlib.import_module("adapter.matrix.bot")
+
+    platform_close = AsyncMock()
+    runtime = SimpleNamespace(platform=SimpleNamespace(close=platform_close))
+
+    class FakeAsyncClient:
+        def __init__(self, *args, **kwargs):
+            self.access_token = None
+            self.callbacks = []
+            self.sync_forever = AsyncMock()
+            self.close = AsyncMock()
+
+        async def login(self, *args, **kwargs):
+            raise AssertionError("login should not be called when access token is provided")
+
+        def add_event_callback(self, callback, event_type):
+            self.callbacks.append((callback, event_type))
+
+    monkeypatch.setenv("MATRIX_HOMESERVER", "https://matrix.example.org")
+    monkeypatch.setenv("MATRIX_USER_ID", "@bot:example.org")
+    monkeypatch.setenv("MATRIX_ACCESS_TOKEN", "token")
+    monkeypatch.setattr(bot_module, "AsyncClient", FakeAsyncClient)
+    monkeypatch.setattr(bot_module, "build_runtime", lambda **kwargs: runtime)
+    monkeypatch.setattr(bot_module, "prepare_live_sync", AsyncMock(return_value="s123"))
+
+    await bot_module.main()
+
+    platform_close.assert_awaited_once()
+
+
+async def test_matrix_main_registers_media_message_callbacks(monkeypatch):
+    bot_module = importlib.import_module("adapter.matrix.bot")
+
+    runtime = SimpleNamespace(platform=SimpleNamespace(close=AsyncMock()))
+    created_clients = []
+
+    class FakeAsyncClient:
+        def __init__(self, *args, **kwargs):
+            self.access_token = None
+            self.callbacks = []
+            self.sync_forever = AsyncMock()
+            self.close = AsyncMock()
+            created_clients.append(self)
+
+        async def login(self, *args, **kwargs):
+            raise AssertionError("login should not be called when access token is provided")
+
+        def add_event_callback(self, callback, event_type):
+            self.callbacks.append((callback, event_type))
+
+    monkeypatch.setenv("MATRIX_HOMESERVER", "https://matrix.example.org")
+    monkeypatch.setenv("MATRIX_USER_ID", "@bot:example.org")
+    monkeypatch.setenv("MATRIX_ACCESS_TOKEN", "token")
+    monkeypatch.setattr(bot_module, "AsyncClient", FakeAsyncClient)
+    monkeypatch.setattr(bot_module, "build_runtime", lambda **kwargs: runtime)
+    monkeypatch.setattr(bot_module, "prepare_live_sync", AsyncMock(return_value="s123"))
+
+    await bot_module.main()
+
+    assert len(created_clients) == 1
+    registered_types = [event_type for _, event_type in created_clients[0].callbacks]
+    assert (
+        RoomMessageText,
+        RoomMessageFile,
+        RoomMessageImage,
+        RoomMessageVideo,
+        RoomMessageAudio,
+    ) in registered_types

tests/adapter/matrix/test_files.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+from adapter.matrix.files import (
+    build_agent_workspace_path,
+    download_matrix_attachment,
+)
+from core.protocol import Attachment
+
+
+async def test_download_matrix_attachment_persists_file_and_returns_workspace_path(tmp_path: Path):
+    async def download(url: str):
+        assert url == "mxc://server/id"
+        return SimpleNamespace(body=b"%PDF-1.7")
+
+    client = SimpleNamespace(download=download)
+    attachment = Attachment(
+        type="document",
+        url="mxc://server/id",
+        filename="report.pdf",
+        mime_type="application/pdf",
+    )
+
+    saved = await download_matrix_attachment(
+        client=client,
+        workspace_root=tmp_path,
+        matrix_user_id="@alice:example.org",
+        room_id="!room:example.org",
+        attachment=attachment,
+        timestamp="20260420-153000",
+    )
+
+    assert saved.workspace_path == "report.pdf"
+    assert (tmp_path / "report.pdf").read_bytes() == b"%PDF-1.7"
+
+
+def test_build_agent_workspace_path_uses_agent_workspace_volume(tmp_path: Path):
+    rel_path, abs_path = build_agent_workspace_path(
+        workspace_root=tmp_path / "agents" / "17",
+        filename="quarterly status.pdf",
+    )
+
+    assert rel_path == "quarterly status.pdf"
+    assert abs_path == tmp_path / "agents" / "17" / rel_path
+
+
+def test_build_agent_workspace_path_uses_windows_style_copy_index(tmp_path: Path):
+    workspace_root = tmp_path / "agents" / "17"
+    workspace_root.mkdir(parents=True)
+    (workspace_root / "report.pdf").write_bytes(b"old")
+    (workspace_root / "report (1).pdf").write_bytes(b"older")
+
+    rel_path, abs_path = build_agent_workspace_path(
+        workspace_root=workspace_root,
+        filename="report.pdf",
+    )
+
+    assert rel_path == "report (2).pdf"
+    assert abs_path == workspace_root / "report (2).pdf"
+
+
+def test_build_agent_workspace_path_sanitizes_to_basename(tmp_path: Path):
+    rel_path, abs_path = build_agent_workspace_path(
+        workspace_root=tmp_path / "agents" / "17",
+        filename="../../quarterly: status?.pdf",
+    )
+
+    assert rel_path == "quarterly_ status_.pdf"
+    assert abs_path == tmp_path / "agents" / "17" / "quarterly_ status_.pdf"
+
+
+async def test_download_matrix_attachment_uses_agent_workspace_root(tmp_path: Path):
+    async def download(url: str):
+        assert url == "mxc://server/id"
+        return SimpleNamespace(body=b"%PDF-1.7")
+
+    saved = await download_matrix_attachment(
+        client=SimpleNamespace(download=download),
+        workspace_root=tmp_path / "agents" / "17",
+        matrix_user_id="@alice:example.org",
+        room_id="!room:example.org",
+        attachment=Attachment(
+            type="document",
+            url="mxc://server/id",
+            filename="report.pdf",
+            mime_type="application/pdf",
+        ),
+        timestamp="20260428-110000",
+    )
+
+    assert saved.workspace_path == "report.pdf"
+    assert (tmp_path / "agents" / "17" / saved.workspace_path).read_bytes() == b"%PDF-1.7"

tests/adapter/matrix/test_invite_space.py

@@ -7,7 +7,7 @@ from nio.api import RoomVisibility
 
 from adapter.matrix.bot import build_runtime
 from adapter.matrix.handlers.auth import handle_invite
-from adapter.matrix.store import get_room_meta, get_user_meta, set_user_meta
+from adapter.matrix.store import get_room_meta, get_user_meta, set_room_meta, set_user_meta
 from sdk.mock import MockPlatformClient
 
 
@@ -64,6 +64,7 @@ async def test_mat01_invite_creates_space_and_chat1():
     assert room_meta is not None
     assert room_meta["chat_id"] == "C4"
     assert room_meta["space_id"] == "!space:example.org"
+    assert room_meta["platform_chat_id"] == "1"
     assert user_meta["next_chat_index"] == 5
 
     chats = await runtime.chat_mgr.list_active("@alice:example.org")
@@ -99,6 +100,53 @@ async def test_mat02_invite_idempotent():
     assert client.room_create.await_count == 2
 
 
+async def test_existing_user_invite_reinvites_space_and_active_chats():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_user_meta(
+        runtime.store,
+        "@alice:example.org",
+        {"space_id": "!space:example.org", "next_chat_index": 2},
+    )
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {
+            "room_type": "chat",
+            "chat_id": "C1",
+            "display_name": "Чат 1",
+            "matrix_user_id": "@alice:example.org",
+            "space_id": "!space:example.org",
+            "platform_chat_id": "1",
+            "agent_id": "agent-1",
+        },
+    )
+    await runtime.chat_mgr.get_or_create(
+        user_id="@alice:example.org",
+        chat_id="C1",
+        platform="matrix",
+        surface_ref="!chat1:example.org",
+        name="Чат 1",
+    )
+    client = _make_client()
+    room = SimpleNamespace(room_id="!dm:example.org", display_name="Alice")
+    event = SimpleNamespace(sender="@alice:example.org", membership="invite")
+
+    await handle_invite(
+        client,
+        room,
+        event,
+        runtime.platform,
+        runtime.store,
+        runtime.auth_mgr,
+        runtime.chat_mgr,
+    )
+
+    client.room_create.assert_not_awaited()
+    client.room_invite.assert_any_await("!space:example.org", "@alice:example.org")
+    client.room_invite.assert_any_await("!chat1:example.org", "@alice:example.org")
+    client.room_send.assert_awaited()
+
+
 async def test_mat03_no_hardcoded_c1():
     runtime = build_runtime(platform=MockPlatformClient())
     await set_user_meta(runtime.store, "@alice:example.org", {"next_chat_index": 7})
@@ -119,6 +167,7 @@ async def test_mat03_no_hardcoded_c1():
     room_meta = await get_room_meta(runtime.store, "!chat1:example.org")
     assert room_meta is not None
     assert room_meta["chat_id"] == "C7"
+    assert room_meta["platform_chat_id"] == "1"
 
     user_meta = await get_user_meta(runtime.store, "@alice:example.org")
     assert user_meta is not None

tests/adapter/matrix/test_reconciliation.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import importlib
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+from adapter.matrix.agent_registry import AgentDefinition, AgentRegistry
+from adapter.matrix.bot import MatrixBot, build_runtime
+from adapter.matrix.reconciliation import reconcile_startup_state
+from adapter.matrix.store import get_room_meta, get_user_meta, set_room_meta, set_user_meta
+from sdk.mock import MockPlatformClient
+
+
+def _room(
+    room_id: str,
+    name: str,
+    members: list[str],
+    *,
+    parents: tuple[str, ...] = (),
+):
+    return SimpleNamespace(
+        room_id=room_id,
+        name=name,
+        display_name=name,
+        users={user_id: SimpleNamespace(user_id=user_id) for user_id in members},
+        space_parents=set(parents),
+    )
+
+
+async def test_reconcile_startup_state_restores_space_room_and_chat_bindings():
+    runtime = build_runtime(platform=MockPlatformClient())
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        rooms={
+            "!space:example.org": _room(
+                "!space:example.org",
+                "Lambda - Alice",
+                ["@bot:example.org", "@alice:example.org"],
+            ),
+            "!chat3:example.org": _room(
+                "!chat3:example.org",
+                "Чат 3",
+                ["@bot:example.org", "@alice:example.org"],
+                parents=("!space:example.org",),
+            ),
+        },
+    )
+
+    await reconcile_startup_state(client, runtime)
+
+    user_meta = await get_user_meta(runtime.store, "@alice:example.org")
+    assert user_meta is not None
+    assert user_meta["space_id"] == "!space:example.org"
+    assert user_meta["next_chat_index"] == 4
+
+    room_meta = await get_room_meta(runtime.store, "!chat3:example.org")
+    assert room_meta is not None
+    assert room_meta["room_type"] == "chat"
+    assert room_meta["chat_id"] == "C3"
+    assert room_meta["space_id"] == "!space:example.org"
+    assert room_meta["matrix_user_id"] == "@alice:example.org"
+    assert room_meta["platform_chat_id"] == "1"
+
+    chats = await runtime.chat_mgr.list_active("@alice:example.org")
+    assert [chat.chat_id for chat in chats] == ["C3"]
+    assert [chat.surface_ref for chat in chats] == ["!chat3:example.org"]
+
+
+async def test_reconcile_startup_state_is_idempotent_with_existing_local_state():
+    runtime = build_runtime(platform=MockPlatformClient())
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        rooms={
+            "!space:example.org": _room(
+                "!space:example.org",
+                "Lambda - Alice",
+                ["@bot:example.org", "@alice:example.org"],
+            ),
+            "!chat3:example.org": _room(
+                "!chat3:example.org",
+                "Чат 3",
+                ["@bot:example.org", "@alice:example.org"],
+                parents=("!space:example.org",),
+            ),
+        },
+    )
+    await set_user_meta(
+        runtime.store,
+        "@alice:example.org",
+        {"space_id": "!space:example.org", "next_chat_index": 8},
+    )
+    await set_room_meta(
+        runtime.store,
+        "!chat3:example.org",
+        {
+            "room_type": "chat",
+            "chat_id": "C3",
+            "display_name": "Existing name",
+            "matrix_user_id": "@alice:example.org",
+            "space_id": "!space:example.org",
+            "platform_chat_id": "42",
+        },
+    )
+    await runtime.chat_mgr.get_or_create(
+        user_id="@alice:example.org",
+        chat_id="C3",
+        platform="matrix",
+        surface_ref="!chat3:example.org",
+        name="Existing name",
+    )
+
+    await reconcile_startup_state(client, runtime)
+    await reconcile_startup_state(client, runtime)
+
+    user_meta = await get_user_meta(runtime.store, "@alice:example.org")
+    assert user_meta == {"space_id": "!space:example.org", "next_chat_index": 8}
+
+    room_meta = await get_room_meta(runtime.store, "!chat3:example.org")
+    assert room_meta is not None
+    assert room_meta["display_name"] == "Existing name"
+    assert room_meta["platform_chat_id"] == "42"
+
+    chats = await runtime.chat_mgr.list_active("@alice:example.org")
+    assert len(chats) == 1
+    assert chats[0].chat_id == "C3"
+
+
+async def test_reconcile_updates_default_agent_assignment_after_user_is_configured():
+    runtime = build_runtime(platform=MockPlatformClient())
+    runtime.registry = AgentRegistry(
+        [
+            AgentDefinition("agent-default", "Default"),
+            AgentDefinition("agent-alice", "Alice"),
+        ],
+        user_agents={"@alice:example.org": "agent-alice"},
+    )
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        rooms={
+            "!space:example.org": _room(
+                "!space:example.org",
+                "Lambda - Alice",
+                ["@bot:example.org", "@alice:example.org"],
+            ),
+            "!chat3:example.org": _room(
+                "!chat3:example.org",
+                "Чат 3",
+                ["@bot:example.org", "@alice:example.org"],
+                parents=("!space:example.org",),
+            ),
+        },
+    )
+    await set_room_meta(
+        runtime.store,
+        "!chat3:example.org",
+        {
+            "room_type": "chat",
+            "chat_id": "C3",
+            "display_name": "Чат 3",
+            "matrix_user_id": "@alice:example.org",
+            "space_id": "!space:example.org",
+            "platform_chat_id": "42",
+            "agent_id": "agent-default",
+            "agent_assignment": "default",
+        },
+    )
+
+    await reconcile_startup_state(client, runtime)
+
+    room_meta = await get_room_meta(runtime.store, "!chat3:example.org")
+    assert room_meta is not None
+    assert room_meta["agent_id"] == "agent-alice"
+    assert room_meta["agent_assignment"] == "configured"
+    assert room_meta["platform_chat_id"] == "42"
+
+
+async def test_reconciliation_prevents_lazy_bootstrap_for_existing_room():
+    runtime = build_runtime(platform=MockPlatformClient())
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        rooms={
+            "!space:example.org": _room(
+                "!space:example.org",
+                "Lambda - Alice",
+                ["@bot:example.org", "@alice:example.org"],
+            ),
+            "!chat3:example.org": _room(
+                "!chat3:example.org",
+                "Чат 3",
+                ["@bot:example.org", "@alice:example.org"],
+                parents=("!space:example.org",),
+            ),
+        },
+        room_send=AsyncMock(),
+    )
+    bot = MatrixBot(client=client, runtime=runtime)
+    bot._bootstrap_unregistered_room = AsyncMock()
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+
+    await reconcile_startup_state(client, runtime)
+    await bot.on_room_message(
+        SimpleNamespace(room_id="!chat3:example.org"),
+        SimpleNamespace(sender="@alice:example.org", body="hello"),
+    )
+
+    bot._bootstrap_unregistered_room.assert_not_awaited()
+    runtime.dispatcher.dispatch.assert_awaited_once()
+
+
+async def test_matrix_main_runs_reconciliation_before_sync_forever(monkeypatch):
+    bot_module = importlib.import_module("adapter.matrix.bot")
+
+    runtime = SimpleNamespace(platform=SimpleNamespace(close=AsyncMock()))
+    call_order: list[str] = []
+
+    class FakeAsyncClient:
+        def __init__(self, *args, **kwargs):
+            self.access_token = None
+            self.callbacks = []
+            self.close = AsyncMock()
+            self.sync_forever = AsyncMock(side_effect=self._sync_forever)
+
+        async def _sync_forever(self, *args, **kwargs):
+            call_order.append("sync_forever")
+
+        async def login(self, *args, **kwargs):
+            raise AssertionError("login should not be called when access token is provided")
+
+        def add_event_callback(self, callback, event_type):
+            self.callbacks.append((callback, event_type))
+
+    async def fake_prepare_live_sync(client):
+        call_order.append("prepare_live_sync")
+        return "s123"
+
+    async def fake_reconcile_startup_state(client, runtime):
+        call_order.append("reconcile_startup_state")
+
+    monkeypatch.setenv("MATRIX_HOMESERVER", "https://matrix.example.org")
+    monkeypatch.setenv("MATRIX_USER_ID", "@bot:example.org")
+    monkeypatch.setenv("MATRIX_ACCESS_TOKEN", "token")
+    monkeypatch.setattr(bot_module, "AsyncClient", FakeAsyncClient)
+    monkeypatch.setattr(bot_module, "build_runtime", lambda **kwargs: runtime)
+    monkeypatch.setattr(bot_module, "prepare_live_sync", fake_prepare_live_sync)
+    monkeypatch.setattr(bot_module, "reconcile_startup_state", fake_reconcile_startup_state)
+
+    await bot_module.main()
+
+    assert call_order == [
+        "prepare_live_sync",
+        "reconcile_startup_state",
+        "sync_forever",
+    ]

tests/adapter/matrix/test_restart_persistence.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from adapter.matrix.bot import build_runtime
+from adapter.matrix.reconciliation import reconcile_startup_state
+from adapter.matrix.store import (
+    get_room_meta,
+    next_platform_chat_id,
+    set_room_meta,
+)
+from core.store import SQLiteStore
+from sdk.mock import MockPlatformClient
+
+
+async def test_room_agent_id_and_platform_chat_id_survive_restart(tmp_path):
+    db = str(tmp_path / "state.db")
+    store = SQLiteStore(db)
+    await set_room_meta(store, "!room:example.org", {
+        "room_type": "chat",
+        "agent_id": "agent-1",
+        "platform_chat_id": "42",
+    })
+
+    store2 = SQLiteStore(db)
+    meta = await get_room_meta(store2, "!room:example.org")
+    assert meta is not None
+    assert meta["agent_id"] == "agent-1"
+    assert meta["platform_chat_id"] == "42"
+
+
+async def test_platform_chat_seq_survives_restart(tmp_path):
+    db = str(tmp_path / "state.db")
+    store = SQLiteStore(db)
+    assert await next_platform_chat_id(store) == "1"
+    assert await next_platform_chat_id(store) == "2"
+    assert await next_platform_chat_id(store) == "3"
+
+    store2 = SQLiteStore(db)
+    assert await next_platform_chat_id(store2) == "4"
+
+
+async def test_routing_state_survives_restart_and_routes_correctly(tmp_path):
+    db = str(tmp_path / "state.db")
+    store = SQLiteStore(db)
+    await set_room_meta(store, "!convo:example.org", {
+        "room_type": "chat",
+        "agent_id": "agent-1",
+        "platform_chat_id": "10",
+    })
+
+    store2 = SQLiteStore(db)
+    meta = await get_room_meta(store2, "!convo:example.org")
+    assert meta is not None
+    assert meta["agent_id"] == "agent-1"
+    assert meta["platform_chat_id"] == "10"
+
+
+async def test_missing_durable_store_starts_clean(tmp_path):
+    db = str(tmp_path / "brand_new.db")
+    store = SQLiteStore(db)
+    assert await get_room_meta(store, "!nonexistent:example.org") is None
+
+
+async def test_startup_reconciliation_backfills_legacy_platform_chat_id_before_restart_routes(
+    tmp_path,
+):
+    db = str(tmp_path / "state.db")
+    store = SQLiteStore(db)
+    await set_room_meta(
+        store,
+        "!chat2:example.org",
+        {
+            "room_type": "chat",
+            "chat_id": "C2",
+            "display_name": "Чат 2",
+            "matrix_user_id": "@alice:example.org",
+            "space_id": "!space:example.org",
+        },
+    )
+
+    runtime = build_runtime(platform=MockPlatformClient(), store=store)
+    client = SimpleNamespace(
+        user_id="@bot:example.org",
+        rooms={
+            "!space:example.org": SimpleNamespace(
+                room_id="!space:example.org",
+                name="Lambda - Alice",
+                display_name="Lambda - Alice",
+                users={
+                    "@bot:example.org": SimpleNamespace(user_id="@bot:example.org"),
+                    "@alice:example.org": SimpleNamespace(user_id="@alice:example.org"),
+                },
+                space_parents=set(),
+            ),
+            "!chat2:example.org": SimpleNamespace(
+                room_id="!chat2:example.org",
+                name="Чат 2",
+                display_name="Чат 2",
+                users={
+                    "@bot:example.org": SimpleNamespace(user_id="@bot:example.org"),
+                    "@alice:example.org": SimpleNamespace(user_id="@alice:example.org"),
+                },
+                space_parents={"!space:example.org"},
+            ),
+        },
+    )
+
+    await reconcile_startup_state(client, runtime)
+
+    store2 = SQLiteStore(db)
+    room_meta = await get_room_meta(store2, "!chat2:example.org")
+    assert room_meta is not None
+    assert room_meta["platform_chat_id"] == "1"

tests/adapter/matrix/test_routed_platform.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from adapter.matrix.bot import MatrixBot, build_runtime
+from adapter.matrix.routed_platform import RoutedPlatformClient
+from adapter.matrix.store import set_room_meta
+from core.chat import ChatManager
+from core.store import InMemoryStore
+from sdk.interface import MessageChunk, MessageResponse, User, UserSettings
+from sdk.mock import MockPlatformClient
+from sdk.interface import PlatformError
+
+
+class FakeDelegate:
+    def __init__(self, *, name: str) -> None:
+        self.name = name
+        self.send_calls: list[dict] = []
+        self.stream_calls: list[dict] = []
+        self.user_calls: list[dict] = []
+        self.settings_calls: list[str] = []
+        self.update_calls: list[tuple[str, object]] = []
+
+    async def get_or_create_user(
+        self,
+        external_id: str,
+        platform: str,
+        display_name: str | None = None,
+    ) -> User:
+        self.user_calls.append(
+            {
+                "external_id": external_id,
+                "platform": platform,
+                "display_name": display_name,
+            }
+        )
+        return User(
+            user_id=f"user-{self.name}",
+            external_id=external_id,
+            platform=platform,
+            display_name=display_name,
+            created_at="2025-01-01T00:00:00Z",
+            is_new=False,
+        )
+
+    async def send_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments=None,
+    ) -> MessageResponse:
+        self.send_calls.append(
+            {
+                "user_id": user_id,
+                "chat_id": chat_id,
+                "text": text,
+                "attachments": attachments,
+            }
+        )
+        return MessageResponse(
+            message_id=f"msg-{self.name}",
+            response=f"reply-{self.name}",
+            tokens_used=0,
+            finished=True,
+        )
+
+    async def stream_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments=None,
+    ) -> AsyncIterator[MessageChunk]:
+        self.stream_calls.append(
+            {
+                "user_id": user_id,
+                "chat_id": chat_id,
+                "text": text,
+                "attachments": attachments,
+            }
+        )
+        yield MessageChunk(
+            message_id=f"stream-{self.name}",
+            delta=f"delta-{self.name}",
+            finished=True,
+            tokens_used=0,
+        )
+
+    async def get_settings(self, user_id: str) -> UserSettings:
+        self.settings_calls.append(user_id)
+        return UserSettings(skills={"files": True})
+
+    async def update_settings(self, user_id: str, action: object) -> None:
+        self.update_calls.append((user_id, action))
+
+
+@pytest.fixture(autouse=True)
+def clear_matrix_registry_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MATRIX_AGENT_REGISTRY_PATH", raising=False)
+    monkeypatch.delenv("MATRIX_PLATFORM_BACKEND", raising=False)
+
+
+@pytest.mark.asyncio
+async def test_send_message_routes_by_room_agent_and_platform_chat_id():
+    store = InMemoryStore()
+    chat_mgr = ChatManager(None, store)
+    await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org")
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"platform_chat_id": "41", "agent_id": "agent-2"},
+    )
+    delegates = {
+        "agent-1": FakeDelegate(name="agent-1"),
+        "agent-2": FakeDelegate(name="agent-2"),
+    }
+    platform = RoutedPlatformClient(chat_mgr=chat_mgr, store=store, delegates=delegates)
+
+    response = await platform.send_message("u1", "C1", "hello", attachments=[])
+
+    assert response.response == "reply-agent-2"
+    assert delegates["agent-1"].send_calls == []
+    assert delegates["agent-2"].send_calls == [
+        {
+            "user_id": "u1",
+            "chat_id": "41",
+            "text": "hello",
+            "attachments": [],
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_stream_message_routes_by_room_agent_and_platform_chat_id():
+    store = InMemoryStore()
+    chat_mgr = ChatManager(None, store)
+    await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org")
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"platform_chat_id": "41", "agent_id": "agent-2"},
+    )
+    delegates = {
+        "agent-1": FakeDelegate(name="agent-1"),
+        "agent-2": FakeDelegate(name="agent-2"),
+    }
+    platform = RoutedPlatformClient(chat_mgr=chat_mgr, store=store, delegates=delegates)
+
+    chunks = [chunk async for chunk in platform.stream_message("u1", "C1", "hello")]
+
+    assert [chunk.delta for chunk in chunks] == ["delta-agent-2"]
+    assert delegates["agent-1"].stream_calls == []
+    assert delegates["agent-2"].stream_calls == [
+        {
+            "user_id": "u1",
+            "chat_id": "41",
+            "text": "hello",
+            "attachments": None,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_send_message_fails_fast_when_platform_chat_id_is_missing():
+    store = InMemoryStore()
+    chat_mgr = ChatManager(None, store)
+    await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org")
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"agent_id": "agent-2"},
+    )
+    platform = RoutedPlatformClient(
+        chat_mgr=chat_mgr,
+        store=store,
+        delegates={"agent-2": FakeDelegate(name="agent-2")},
+    )
+
+    with pytest.raises(PlatformError, match="routing is incomplete") as exc_info:
+        await platform.send_message("u1", "C1", "hello")
+
+    assert exc_info.value.code == "MATRIX_ROUTE_INCOMPLETE"
+
+
+@pytest.mark.asyncio
+async def test_stream_message_fails_fast_when_agent_id_is_missing():
+    store = InMemoryStore()
+    chat_mgr = ChatManager(None, store)
+    await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org")
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"platform_chat_id": "41"},
+    )
+    platform = RoutedPlatformClient(
+        chat_mgr=chat_mgr,
+        store=store,
+        delegates={"agent-2": FakeDelegate(name="agent-2")},
+    )
+
+    with pytest.raises(PlatformError, match="routing is incomplete") as exc_info:
+        await anext(platform.stream_message("u1", "C1", "hello"))
+
+    assert exc_info.value.code == "MATRIX_ROUTE_INCOMPLETE"
+
+
+@pytest.mark.asyncio
+async def test_routing_uses_repaired_room_metadata_without_runtime_backfill():
+    store = InMemoryStore()
+    chat_mgr = ChatManager(None, store)
+    await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org")
+    await set_room_meta(
+        store,
+        "!room:example.org",
+        {"platform_chat_id": "restored-41", "agent_id": "agent-2"},
+    )
+    delegate = FakeDelegate(name="agent-2")
+    platform = RoutedPlatformClient(
+        chat_mgr=chat_mgr,
+        store=store,
+        delegates={"agent-2": delegate},
+    )
+
+    await platform.send_message("u1", "C1", "hello")
+
+    assert delegate.send_calls == [
+        {
+            "user_id": "u1",
+            "chat_id": "restored-41",
+            "text": "hello",
+            "attachments": None,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_user_and_settings_delegate_to_default_client():
+    store = InMemoryStore()
+    chat_mgr = ChatManager(None, store)
+    delegates = {
+        "agent-1": FakeDelegate(name="agent-1"),
+        "agent-2": FakeDelegate(name="agent-2"),
+    }
+    platform = RoutedPlatformClient(chat_mgr=chat_mgr, store=store, delegates=delegates)
+
+    user = await platform.get_or_create_user("ext-1", "matrix", display_name="Alice")
+    settings = await platform.get_settings("u1")
+    await platform.update_settings("u1", {"action": "noop"})
+
+    assert user.user_id == "user-agent-1"
+    assert settings.skills == {"files": True}
+    assert delegates["agent-1"].user_calls == [
+        {
+            "external_id": "ext-1",
+            "platform": "matrix",
+            "display_name": "Alice",
+        }
+    ]
+    assert delegates["agent-2"].user_calls == []
+    assert delegates["agent-1"].settings_calls == ["u1"]
+    assert delegates["agent-1"].update_calls == [("u1", {"action": "noop"})]
+
+
+@pytest.mark.asyncio
+async def test_build_runtime_real_backend_uses_routed_platform_with_registry(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    registry_path = tmp_path / "matrix-agents.yaml"
+    registry_path.write_text(
+        "agents:\n"
+        "  - id: agent-1\n"
+        "    label: Analyst\n"
+        "  - id: agent-2\n"
+        "    label: Research\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real")
+    monkeypatch.setenv("MATRIX_AGENT_REGISTRY_PATH", str(registry_path))
+    monkeypatch.setenv("AGENT_BASE_URL", "http://agent.example")
+
+    runtime = build_runtime()
+
+    assert isinstance(runtime.platform, RoutedPlatformClient)
+    assert set(runtime.platform._delegates) == {"agent-1", "agent-2"}
+    assert runtime.platform._delegates["agent-1"].agent_base_url == "http://agent.example"
+    assert runtime.platform._delegates["agent-1"].agent_id == "agent-1"
+    assert runtime.platform._delegates["agent-2"].agent_id == "agent-2"
+
+
+def test_build_runtime_real_backend_requires_registry_path(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real")
+    monkeypatch.delenv("MATRIX_AGENT_REGISTRY_PATH", raising=False)
+    monkeypatch.setenv("AGENT_BASE_URL", "http://agent.example")
+
+    with pytest.raises(RuntimeError, match="MATRIX_AGENT_REGISTRY_PATH"):
+        build_runtime()
+
+
+def test_build_runtime_real_backend_fails_explicitly_on_invalid_registry(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    registry_path = tmp_path / "missing.yaml"
+    monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real")
+    monkeypatch.setenv("MATRIX_AGENT_REGISTRY_PATH", str(registry_path))
+    monkeypatch.setenv("AGENT_BASE_URL", "http://agent.example")
+
+    with pytest.raises(RuntimeError, match="failed to load matrix agent registry"):
+        build_runtime()
+
+
+@pytest.mark.asyncio
+async def test_bot_keeps_local_chat_id_for_plain_message_dispatch():
+    runtime = build_runtime(platform=MockPlatformClient())
+    await set_room_meta(
+        runtime.store,
+        "!chat1:example.org",
+        {
+            "chat_id": "C1",
+            "matrix_user_id": "@alice:example.org",
+            "platform_chat_id": "41",
+            "agent_id": "agent-2",
+        },
+    )
+    runtime.dispatcher.dispatch = AsyncMock(return_value=[])
+    bot = MatrixBot(SimpleNamespace(user_id="@bot:example.org"), runtime)
+
+    await bot.on_room_message(
+        SimpleNamespace(room_id="!chat1:example.org"),
+        SimpleNamespace(sender="@alice:example.org", body="hello"),
+    )
+
+    dispatched = runtime.dispatcher.dispatch.await_args.args[0]
+    assert dispatched.chat_id == "C1"
+    assert dispatched.text == "hello"

tests/adapter/matrix/test_send_outgoing.py

@@ -9,7 +9,7 @@ from adapter.matrix.handlers.confirm import make_handle_cancel, make_handle_conf
 from adapter.matrix.store import get_pending_confirm, set_room_meta
 from core.auth import AuthManager
 from core.chat import ChatManager
-from core.protocol import OutgoingUI, UIButton
+from core.protocol import Attachment, OutgoingMessage, OutgoingUI, UIButton
 from core.settings import SettingsManager
 from core.store import InMemoryStore
 from sdk.mock import MockPlatformClient
@@ -156,3 +156,39 @@ async def test_outgoing_ui_no_round_trip_uses_user_and_room_scope():
     assert "отменено" in result[0].text.lower()
     assert await get_pending_confirm(store, "@alice:example.org", "!confirm:example.org") is None
     assert await get_pending_confirm(store, "@bob:example.org", "!other:example.org") is not None
+
+
+async def test_send_outgoing_uploads_workspace_file_attachment(tmp_path, monkeypatch):
+    workspace_file = tmp_path / "surfaces" / "matrix" / "alice" / "room" / "inbox" / "result.txt"
+    workspace_file.parent.mkdir(parents=True, exist_ok=True)
+    workspace_file.write_text("ready")
+    monkeypatch.setenv("SURFACES_WORKSPACE_DIR", str(tmp_path))
+
+    client = SimpleNamespace(
+        upload=AsyncMock(return_value=(SimpleNamespace(content_uri="mxc://server/file"), {})),
+        room_send=AsyncMock(),
+    )
+
+    await send_outgoing(
+        client,
+        "!room:example.org",
+        OutgoingMessage(
+            chat_id="!room:example.org",
+            text="Файл готов",
+            attachments=[
+                Attachment(
+                    type="document",
+                    filename="result.txt",
+                    mime_type="text/plain",
+                    workspace_path="surfaces/matrix/alice/room/inbox/result.txt",
+                )
+            ],
+        ),
+    )
+
+    client.upload.assert_awaited_once()
+    client.room_send.assert_awaited()
+    assert client.room_send.await_args_list[0].args[2]["body"] == "Файл готов"
+    file_call = client.room_send.await_args_list[1]
+    assert file_call.args[2]["msgtype"] == "m.file"
+    assert file_call.args[2]["url"] == "mxc://server/file"

tests/adapter/matrix/test_store.py

@@ -3,14 +3,22 @@ from __future__ import annotations
 import pytest
 
 from adapter.matrix.store import (
+    STAGED_ATTACHMENTS_PREFIX,
+    add_staged_attachment,
     clear_pending_confirm,
+    clear_staged_attachments,
     get_pending_confirm,
+    get_platform_chat_id,
     get_room_meta,
     get_room_state,
     get_skills_message_id,
+    get_staged_attachments,
     get_user_meta,
     next_chat_id,
+    next_platform_chat_id,
+    remove_staged_attachment_at,
     set_pending_confirm,
+    set_platform_chat_id,
     set_room_meta,
     set_room_state,
     set_skills_message_id,
@@ -35,6 +43,36 @@ async def test_room_meta_roundtrip(store: InMemoryStore):
     assert await get_room_meta(store, "!r:m.org") == meta
 
 
+async def test_room_meta_roundtrip_with_platform_chat_id(store: InMemoryStore):
+    meta = {
+        "chat_id": "C1",
+        "matrix_user_id": "@alice:example.org",
+        "platform_chat_id": "chat-platform-1",
+    }
+    await set_room_meta(store, "!r:m.org", meta)
+    saved = await get_room_meta(store, "!r:m.org")
+    assert saved is not None
+    assert saved["platform_chat_id"] == "chat-platform-1"
+
+
+async def test_platform_chat_id_helpers_roundtrip(store: InMemoryStore):
+    meta = {
+        "chat_id": "C1",
+        "matrix_user_id": "@alice:example.org",
+        "display_name": "Research",
+    }
+    await set_room_meta(store, "!r:m.org", meta)
+    await set_platform_chat_id(store, "!r:m.org", "chat-platform-1")
+
+    assert await get_platform_chat_id(store, "!r:m.org") == "chat-platform-1"
+    assert await get_room_meta(store, "!r:m.org") == {
+        "chat_id": "C1",
+        "matrix_user_id": "@alice:example.org",
+        "display_name": "Research",
+        "platform_chat_id": "chat-platform-1",
+    }
+
+
 async def test_room_meta_missing(store: InMemoryStore):
     assert await get_room_meta(store, "!nonexistent:m.org") is None
 
@@ -70,6 +108,12 @@ async def test_next_chat_id_increments(store: InMemoryStore):
     assert await next_chat_id(store, uid) == "C3"
 
 
+async def test_next_platform_chat_id_increments(store: InMemoryStore):
+    assert await next_platform_chat_id(store) == "1"
+    assert await next_platform_chat_id(store) == "2"
+    assert await next_platform_chat_id(store) == "3"
+
+
 async def test_skills_message_roundtrip(store: InMemoryStore):
     await set_skills_message_id(store, "!room", "$event")
     assert await get_skills_message_id(store, "!room") == "$event"
@@ -84,3 +128,119 @@ async def test_pending_confirm_roundtrip(store: InMemoryStore):
 
     await clear_pending_confirm(store, "!room:m.org")
     assert await get_pending_confirm(store, "!room:m.org") is None
+
+
+async def test_staged_attachments_roundtrip(store: InMemoryStore):
+    room_id = "!room:m.org"
+    user_id = "@alice:m.org"
+
+    assert await get_staged_attachments(store, room_id, user_id) == []
+
+    first = {"id": "att-1", "name": "screenshot.png"}
+    second = {"id": "att-2", "name": "invoice.pdf"}
+
+    await add_staged_attachment(store, room_id, user_id, first)
+    await add_staged_attachment(store, room_id, user_id, second)
+
+    assert await get_staged_attachments(store, room_id, user_id) == [
+        first,
+        second,
+    ]
+
+
+@pytest.mark.parametrize(
+    "stored_value",
+    [
+        None,
+        "not-a-dict",
+        [],
+        123,
+    ],
+)
+async def test_staged_attachments_invalid_container_state_returns_empty_list(
+    store: InMemoryStore,
+    stored_value,
+):
+    room_id = "!room:m.org"
+    user_id = "@alice:m.org"
+
+    await store.set(f"{STAGED_ATTACHMENTS_PREFIX}{room_id}:{user_id}", stored_value)
+
+    assert await get_staged_attachments(store, room_id, user_id) == []
+
+
+async def test_staged_attachments_filters_invalid_entries(store: InMemoryStore):
+    room_id = "!room:m.org"
+    user_id = "@alice:m.org"
+    valid_one = {"id": "att-1", "name": "alpha.png"}
+    valid_two = {"id": "att-2", "name": "beta.pdf"}
+
+    await store.set(
+        f"{STAGED_ATTACHMENTS_PREFIX}{room_id}:{user_id}",
+        {
+            "attachments": [
+                valid_one,
+                "bad-entry",
+                None,
+                {"id": "ignored"},
+                valid_two,
+            ]
+        },
+    )
+
+    assert await get_staged_attachments(store, room_id, user_id) == [
+        valid_one,
+        {"id": "ignored"},
+        valid_two,
+    ]
+
+
+async def test_staged_attachments_are_scoped_by_room_and_user(store: InMemoryStore):
+    room_a = "!room-a:m.org"
+    room_b = "!room-b:m.org"
+    user_a = "@alice:m.org"
+    user_b = "@bob:m.org"
+
+    attachment_a = {"id": "att-a", "name": "alpha.png"}
+    attachment_b = {"id": "att-b", "name": "beta.png"}
+    attachment_c = {"id": "att-c", "name": "gamma.png"}
+
+    await add_staged_attachment(store, room_a, user_a, attachment_a)
+    await add_staged_attachment(store, room_a, user_b, attachment_b)
+    await add_staged_attachment(store, room_b, user_a, attachment_c)
+
+    assert await get_staged_attachments(store, room_a, user_a) == [attachment_a]
+    assert await get_staged_attachments(store, room_a, user_b) == [attachment_b]
+    assert await get_staged_attachments(store, room_b, user_a) == [attachment_c]
+    assert await get_staged_attachments(store, room_b, user_b) == []
+
+
+async def test_remove_staged_attachment_at_by_zero_based_index(
+    store: InMemoryStore,
+):
+    room_id = "!room:m.org"
+    user_id = "@alice:m.org"
+    first = {"id": "att-1", "name": "first.png"}
+    second = {"id": "att-2", "name": "second.png"}
+    third = {"id": "att-3", "name": "third.png"}
+
+    await add_staged_attachment(store, room_id, user_id, first)
+    await add_staged_attachment(store, room_id, user_id, second)
+    await add_staged_attachment(store, room_id, user_id, third)
+
+    assert await remove_staged_attachment_at(store, room_id, user_id, 1) == second
+    assert await get_staged_attachments(store, room_id, user_id) == [first, third]
+    assert await remove_staged_attachment_at(store, room_id, user_id, 99) is None
+    assert await remove_staged_attachment_at(store, room_id, user_id, -1) is None
+
+
+async def test_clear_staged_attachments(store: InMemoryStore):
+    room_id = "!room:m.org"
+    user_id = "@alice:m.org"
+
+    await add_staged_attachment(store, room_id, user_id, {"id": "att-1"})
+    await add_staged_attachment(store, room_id, user_id, {"id": "att-2"})
+
+    await clear_staged_attachments(store, room_id, user_id)
+
+    assert await get_staged_attachments(store, room_id, user_id) == []

tests/core/test_dispatcher.py

@@ -75,6 +75,27 @@ async def test_dispatch_routes_audio_before_catchall(dispatcher):
     assert (await dispatcher.dispatch(text_msg))[0].text == "text"
 
 
+async def test_dispatch_routes_document_before_catchall(dispatcher):
+    async def document_handler(event, **kwargs):
+        return [OutgoingMessage(chat_id=event.chat_id, text="document")]
+
+    async def catch_all(event, **kwargs):
+        return [OutgoingMessage(chat_id=event.chat_id, text="text")]
+
+    dispatcher.register(IncomingMessage, "document", document_handler)
+    dispatcher.register(IncomingMessage, "*", catch_all)
+
+    document_msg = IncomingMessage(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C1",
+        text="",
+        attachments=[Attachment(type="document", workspace_path="surfaces/matrix/u1/file.pdf")],
+    )
+
+    assert (await dispatcher.dispatch(document_msg))[0].text == "document"
+
+
 async def test_dispatch_callback_by_action(dispatcher):
     async def confirm_handler(event, **kwargs):
         return [OutgoingMessage(chat_id=event.chat_id, text="confirmed")]

tests/core/test_integration.py

@@ -4,18 +4,57 @@ Smoke test: полный цикл через dispatcher + реальные manag
 Имитирует что делает адаптер (Telegram или Matrix) при получении события.
 """
 import pytest
-from sdk.mock import MockPlatformClient
-from core.store import InMemoryStore
-from core.chat import ChatManager
+
 from core.auth import AuthManager
-from core.settings import SettingsManager
+from core.chat import ChatManager
 from core.handler import EventDispatcher
 from core.handlers import register_all
 from core.protocol import (
-    IncomingCommand, IncomingMessage, IncomingCallback,
-    OutgoingMessage, OutgoingUI,
-    Attachment, SettingsAction,
+    Attachment,
+    IncomingCallback,
+    IncomingCommand,
+    IncomingMessage,
+    OutgoingMessage,
+    OutgoingUI,
 )
+from core.settings import SettingsManager
+from core.store import InMemoryStore
+from sdk.mock import MockPlatformClient
+from sdk.prototype_state import PrototypeStateStore
+from sdk.real import RealPlatformClient
+from sdk.upstream_agent_api import MsgEventTextChunk
+
+
+class FakeAgentApi:
+    def __init__(self, agent_id: str, base_url: str, chat_id: str) -> None:
+        self.agent_id = agent_id
+        self.base_url = base_url
+        self.chat_id = chat_id
+        self.calls: list[tuple[str, list[str]]] = []
+        self.connect_calls = 0
+        self.close_calls = 0
+
+    async def connect(self) -> None:
+        self.connect_calls += 1
+
+    async def close(self) -> None:
+        self.close_calls += 1
+
+    async def send_message(self, text: str, attachments: list[str] | None = None):
+        self.calls.append((text, attachments or []))
+        yield MsgEventTextChunk(text=f"[REAL] {text}")
+
+
+class FakeAgentApiFactory:
+    def __init__(self) -> None:
+        self.created_chat_ids: list[str] = []
+        self.instances: dict[str, list[FakeAgentApi]] = {}
+
+    def __call__(self, agent_id: str, base_url: str, chat_id: str) -> FakeAgentApi:
+        chat_api = FakeAgentApi(agent_id, base_url, chat_id)
+        self.created_chat_ids.append(chat_id)
+        self.instances.setdefault(chat_id, []).append(chat_api)
+        return chat_api
 
 
 @pytest.fixture
@@ -32,6 +71,27 @@ def dispatcher():
     return d
 
 
+@pytest.fixture
+def real_dispatcher():
+    agent_api = FakeAgentApiFactory()
+    platform = RealPlatformClient(
+        agent_id="matrix-bot",
+        agent_base_url="http://platform-agent:8000",
+        agent_api_cls=agent_api,
+        prototype_state=PrototypeStateStore(),
+        platform="matrix",
+    )
+    store = InMemoryStore()
+    d = EventDispatcher(
+        platform=platform,
+        chat_mgr=ChatManager(platform, store),
+        auth_mgr=AuthManager(platform, store),
+        settings_mgr=SettingsManager(platform, store),
+    )
+    register_all(d)
+    return d, agent_api
+
+
 async def test_full_flow_start_then_message(dispatcher):
     start = IncomingCommand(user_id="tg_123", platform="telegram", chat_id="C1", command="start")
     result = await dispatcher.dispatch(start)
@@ -47,7 +107,13 @@ async def test_new_chat_command(dispatcher):
     start = IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="start")
     await dispatcher.dispatch(start)
 
-    new = IncomingCommand(user_id="u1", platform="matrix", chat_id="C2", command="new", args=["Анализ"])
+    new = IncomingCommand(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C2",
+        command="new",
+        args=["Анализ"],
+    )
     result = await dispatcher.dispatch(new)
     assert any("Анализ" in r.text for r in result if isinstance(r, OutgoingMessage))
 
@@ -83,3 +149,46 @@ async def test_toggle_skill_callback(dispatcher):
     )
     result = await dispatcher.dispatch(cb)
     assert any("browser" in r.text for r in result if isinstance(r, OutgoingMessage))
+
+
+async def test_full_flow_with_real_platform_uses_direct_agent_api(real_dispatcher):
+    dispatcher, agent_api = real_dispatcher
+
+    start = IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="start")
+    result = await dispatcher.dispatch(start)
+    assert any(isinstance(r, OutgoingMessage) for r in result)
+
+    msg = IncomingMessage(user_id="u1", platform="matrix", chat_id="C1", text="Привет!")
+    result = await dispatcher.dispatch(msg)
+    texts = [r.text for r in result if isinstance(r, OutgoingMessage)]
+
+    assert texts == ["[REAL] Привет!"]
+    assert agent_api.created_chat_ids == ["C1"]
+    assert [instance.calls for instance in agent_api.instances["C1"]] == [[("Привет!", [])]]
+
+
+async def test_full_flow_with_real_platform_forwards_workspace_attachment(real_dispatcher):
+    dispatcher, agent_api = real_dispatcher
+
+    start = IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="start")
+    await dispatcher.dispatch(start)
+
+    msg = IncomingMessage(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C1",
+        text="Посмотри файл",
+        attachments=[
+            Attachment(
+                type="document",
+                filename="report.pdf",
+                mime_type="application/pdf",
+                workspace_path="surfaces/matrix/u1/room/inbox/report.pdf",
+            )
+        ],
+    )
+    await dispatcher.dispatch(msg)
+
+    assert [instance.calls for instance in agent_api.instances["C1"]] == [
+        [("Посмотри файл", ["surfaces/matrix/u1/room/inbox/report.pdf"])]
+    ]