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