fix: require matrix agent registry in real mode

adapter/matrix/bot.py

@@ -30,7 +30,7 @@ from adapter.matrix.files import (
     matrix_msgtype_for_attachment,
     resolve_workspace_attachment_path,
 )
-from adapter.matrix.agent_registry import load_agent_registry
+from adapter.matrix.agent_registry import AgentRegistryError, load_agent_registry
 from adapter.matrix.handlers import register_matrix_handlers
 from adapter.matrix.handlers.auth import handle_invite, provision_workspace_chat
 from adapter.matrix.handlers.context_commands import (
@@ -125,27 +125,27 @@ def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> Pla
     if backend == "real":
         prototype_state = PrototypeStateStore()
         registry_path = os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip()
-        if registry_path:
+        if not registry_path:
-            registry = load_agent_registry(registry_path)
+            raise RuntimeError(
-            delegates = {
+                "MATRIX_AGENT_REGISTRY_PATH is required when MATRIX_PLATFORM_BACKEND=real"
-                agent.agent_id: RealPlatformClient(
-                    agent_id=agent.agent_id,
-                    agent_base_url=_agent_base_url_from_env(),
-                    prototype_state=prototype_state,
-                    platform="matrix",
-                )
-                for agent in registry.agents
-            }
-            return RoutedPlatformClient(
-                chat_mgr=chat_mgr,
-                store=store,
-                delegates=delegates,
             )
-        return RealPlatformClient(
+        try:
-            agent_id="matrix-bot",
+            registry = load_agent_registry(registry_path)
-            agent_base_url=_agent_base_url_from_env(),
+        except (AgentRegistryError, OSError) as exc:
-            prototype_state=prototype_state,
+            raise RuntimeError(f"failed to load matrix agent registry: {registry_path}") from exc
-            platform="matrix",
+        delegates = {
+            agent.agent_id: RealPlatformClient(
+                agent_id=agent.agent_id,
+                agent_base_url=_agent_base_url_from_env(),
+                prototype_state=prototype_state,
+                platform="matrix",
+            )
+            for agent in registry.agents
+        }
+        return RoutedPlatformClient(
+            chat_mgr=chat_mgr,
+            store=store,
+            delegates=delegates,
         )
     return MockPlatformClient()
 

tests/adapter/matrix/test_routed_platform.py

@@ -214,6 +214,28 @@ async def test_build_runtime_real_backend_uses_routed_platform_with_registry(
     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())