fix(diagnostics): make optional failures observable and safe

tests/unit/test_architecture_guardrails.py

@@ -34,6 +34,20 @@ class TestCliBackendBoundaries(unittest.TestCase):
 
 
 class TestRuntimeModuleSizes(unittest.TestCase):
+    def test_no_runtime_module_grows_beyond_global_ceiling(self) -> None:
+        """A coarse ceiling catches new monoliths; focused caps stay tighter."""
+        ceiling = 850
+        oversized = [
+            f"{path.relative_to(ROOT)} ({len(path.read_text().splitlines())})"
+            for path in (ROOT / "bot_bottle").rglob("*.py")
+            if len(path.read_text().splitlines()) > ceiling
+        ]
+        self.assertEqual(
+            [], oversized,
+            f"runtime modules must stay at or below {ceiling} lines: "
+            + ", ".join(oversized),
+        )
+
     def test_egress_modules_stay_focused(self) -> None:
         caps = {
             "addon_core.py": 100,

tests/unit/test_backend_secret_reprovision.py

@@ -48,12 +48,13 @@ class TestSharedReprovision(unittest.TestCase):
         client.reprovision_gateway.side_effect = [
             OrchestratorClientError("bad key"), True,
         ]
-        self.assertEqual(
-            1,
-            reprovision_bottles(
+        with patch("bot_bottle.orchestrator.reprovision.debug") as debug:
+            count = reprovision_bottles(
                 client, {"10.0.0.1": "key-1", "10.0.0.2": "key-2"},
-            ),
-        )
+            )
+        self.assertEqual(1, count)
+        self.assertEqual("b1", debug.call_args.kwargs["context"]["bottle_id"])
+        self.assertNotIn("bad key", repr(debug.call_args))
 
 
 class TestMacosReprovision(unittest.TestCase):

tests/unit/test_cli_tui.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import unittest
 from typing import Any, Optional
+from unittest.mock import patch
 
 from bot_bottle.cli.tui import _filter_items, _multiselect_loop, filter_multiselect, filter_select
 
@@ -49,8 +50,10 @@ class TestFilterSelectEmptyItems(unittest.TestCase):
 
     def test_returns_none_when_tty_unavailable(self):
         # /nonexistent is guaranteed to not open.
-        result = filter_select(["a", "b"], tty_path="/nonexistent/tty")
+        with patch("bot_bottle.cli.tui.debug") as debug:
+            result = filter_select(["a", "b"], tty_path="/nonexistent/tty")
         self.assertIsNone(result)
+        self.assertEqual("FileNotFoundError", debug.call_args.kwargs["context"]["error_type"])
 
 
 class TestFilterMultiselectEmptyItems(unittest.TestCase):
@@ -60,8 +63,10 @@ class TestFilterMultiselectEmptyItems(unittest.TestCase):
         self.assertEqual([], result)
 
     def test_returns_none_when_tty_unavailable(self):
-        result = filter_multiselect(["a", "b"], tty_path="/nonexistent/tty")
+        with patch("bot_bottle.cli.tui.debug") as debug:
+            result = filter_multiselect(["a", "b"], tty_path="/nonexistent/tty")
         self.assertIsNone(result)
+        self.assertEqual("FileNotFoundError", debug.call_args.kwargs["context"]["error_type"])
 
 
 class TestMultiselectLoopReordering(unittest.TestCase):

tests/unit/test_egress_multitenant.py

@@ -3,15 +3,16 @@
 from __future__ import annotations
 
 import unittest
+from unittest.mock import patch
 
-from bot_bottle.gateway.egress.addon_core import (
+from bot_bottle.gateway.egress.context import (
     DENY_RESOLVER_ERROR,
     DENY_UNATTRIBUTED,
     DENY_UNPARSEABLE,
-    decide,
     resolve_client_config,
     resolve_client_context,
 )
+from bot_bottle.gateway.egress.matching import decide
 from bot_bottle.gateway.policy_resolver import PolicyResolveError
 
 
@@ -44,7 +45,13 @@ class TestResolveClientConfig(unittest.TestCase):
 
     def test_resolver_error_denies_all(self) -> None:
         # Orchestrator unreachable/errored must never widen egress.
-        self.assertEqual((), resolve_client_config(_FakeResolver(raises=True), "10.243.0.1").routes)
+        with patch("bot_bottle.gateway.egress.context.debug") as debug:
+            config = resolve_client_config(_FakeResolver(raises=True), "10.243.0.1")
+        self.assertEqual((), config.routes)
+        self.assertEqual(
+            "PolicyResolveError", debug.call_args.kwargs["context"]["error_type"],
+        )
+        self.assertNotIn("orchestrator down", repr(debug.call_args))
 
     def test_unparseable_policy_denies_all(self) -> None:
         cfg = resolve_client_config(_FakeResolver(result="routes: notalist\n"), "10.243.0.1")

tests/unit/test_orchestrator_client.py

@@ -12,7 +12,9 @@ from bot_bottle.orchestrator.client import (
     OrchestratorClient,
     OrchestratorClientError,
     RegisteredBottle,
+    BackendProbeFailure,
     _host_auth_token,
+    _probe_failure,
 )
 
 _URLOPEN = "bot_bottle.orchestrator.client.urllib.request.urlopen"
@@ -33,6 +35,15 @@ class TestHostAuthToken(unittest.TestCase):
             self.assertEqual("", _host_auth_token())
 
 
+class TestBackendProbeFailure(unittest.TestCase):
+    def test_records_safe_typed_diagnostic(self) -> None:
+        with patch("bot_bottle.orchestrator.client.debug") as debug:
+            result = _probe_failure("firecracker", RuntimeError("secret detail"))
+        self.assertEqual(BackendProbeFailure("firecracker", "RuntimeError"), result)
+        rendered = repr(debug.call_args)
+        self.assertNotIn("secret detail", rendered)
+
+
 def _resp(status: int, payload: object) -> MagicMock:
     m = MagicMock()
     inner = m.__enter__.return_value

tests/unit/test_orchestrator_server.py

@@ -7,6 +7,7 @@ server tests), plus one real-socket round-trip to prove the handler wiring.
 from __future__ import annotations
 
 import base64
+import io
 import json
 import secrets
 import sqlite3
@@ -17,7 +18,7 @@ import urllib.error
 import urllib.request
 from contextlib import closing
 from pathlib import Path
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 from bot_bottle.orchestrator_auth import ROLE_CLI, ROLE_GATEWAY, mint
 from bot_bottle.orchestrator.broker import StubBroker
@@ -283,6 +284,25 @@ class TestServerRoundTrip(unittest.TestCase):
         ))
         self.assertEqual(reg["bottle_id"], attr["bottle_id"])
 
+    def test_internal_failure_is_contextual_but_redacted(self) -> None:
+        orch = MagicMock()
+        orch.registry.all.side_effect = RuntimeError("SENSITIVE request value")
+        with patch("sys.stderr", io.StringIO()) as stderr:
+            server = make_server(orch, "127.0.0.1", 0)
+            self.addCleanup(server.server_close)
+            thread = threading.Thread(target=server.serve_forever, daemon=True)
+            thread.start()
+            self.addCleanup(server.shutdown)
+            host, port = server.server_address[0], server.server_address[1]
+            with self.assertRaises(urllib.error.HTTPError) as raised:
+                urllib.request.urlopen(f"http://{host}:{port}/bottles", timeout=5)
+            payload = json.loads(raised.exception.read())
+            output = stderr.getvalue()
+        self.assertEqual({"error": "internal error"}, payload)
+        self.assertIn("GET /bottles", output)
+        self.assertIn("RuntimeError", output)
+        self.assertNotIn("SENSITIVE", output)
+
 
 class TestOrchestratorAuth(unittest.TestCase):
     """Role-scoped control-plane tokens (issue #400 / #469 review): every route