Add reader brain health diagnostics

Co-authored-by: Codex <codex@openai.com>

app.py

@@ -647,6 +647,7 @@ def _runtime_status_core() -> dict[str, Any]:
     llama_start = time.perf_counter()
     llama_status: dict[str, Any]
     if not LLAMA_CPP_BASE_URL:
+        _runtime_log("llama.cpp reader brain endpoint is not configured; using narration fallback")
         llama_status = {
             "available": False,
             "status": "fallback-ready",
@@ -657,15 +658,25 @@ def _runtime_status_core() -> dict[str, Any]:
             "elapsed_ms": _elapsed_ms(llama_start),
         }
     else:
+        models_url = f"{LLAMA_CPP_BASE_URL}/models"
         try:
+            _runtime_log(
+                "llama.cpp reader brain health check "
+                f"url={models_url} token={'configured' if LLAMA_CPP_TOKEN else 'not-set'} "
+                "timeout=1.5s"
+            )
             request = urllib.request.Request(
-                f"{LLAMA_CPP_BASE_URL}/models",
+                models_url,
                 headers=_llama_cpp_headers(),
                 method="GET",
             )
             with urllib.request.urlopen(request, timeout=1.5) as response:
                 payload = json.loads(response.read().decode("utf-8"))
             model_ids = [item.get("id", "") for item in payload.get("data", []) if isinstance(item, dict)]
+            _runtime_log(
+                "llama.cpp reader brain health response "
+                f"models={model_ids[:6]} expected={LLAMA_CPP_MODEL}"
+            )
             llama_status = {
                 "available": True,
                 "status": "online",
@@ -675,13 +686,16 @@ def _runtime_status_core() -> dict[str, Any]:
                 "elapsed_ms": _elapsed_ms(llama_start),
             }
         except (OSError, urllib.error.URLError, TimeoutError, ValueError, json.JSONDecodeError) as exc:
+            detail = _http_exception_detail(exc)
+            _runtime_log(f"llama.cpp reader brain health failed url={models_url} error={detail}")
             llama_status = {
                 "available": False,
                 "status": "fallback-ready",
                 "base_url": LLAMA_CPP_BASE_URL,
                 "model": LLAMA_CPP_MODEL,
                 "fallback": "rule-based local narration",
-                "warning": exc.__class__.__name__,
+                "health_url": models_url,
+                "warning": detail,
                 "elapsed_ms": _elapsed_ms(llama_start),
             }
 

scripts/verify.py

@@ -579,6 +579,42 @@ def verify_modal_klein_integration() -> None:
             "Runtime setup should show reader token as configured without exposing the value",
         )
 
+    # Test: reader-brain runtime status exposes actionable health details without leaking tokens
+    with patch.object(app, "LLAMA_CPP_BASE_URL", "https://reader.example/v1"), patch.object(app, "LLAMA_CPP_TOKEN", "reader-secret"):
+        http_error = urllib.error.HTTPError(
+            "https://reader.example/v1/models",
+            401,
+            "Unauthorized",
+            {},
+            None,
+        )
+        http_error.fp = MagicMock()
+        http_error.fp.read.return_value = b'{"detail":"Unauthorized"}'
+        with patch("urllib.request.urlopen", side_effect=http_error) as urlopen_mock:
+            status = app._runtime_status_core()
+            reader_status = status["reader_brain"]
+            health_request = urlopen_mock.call_args.args[0]
+            assert_true(
+                health_request.headers.get("Authorization") == "Bearer reader-secret",
+                "Reader-brain health checks should send Bearer token when configured",
+            )
+            assert_true(
+                "HTTPError status=401" in reader_status["warning"],
+                "Reader-brain runtime warning should include HTTP status details",
+            )
+            assert_true(
+                "Unauthorized" in reader_status["warning"],
+                "Reader-brain runtime warning should include response body details",
+            )
+            assert_true(
+                "reader-secret" not in json.dumps(reader_status),
+                "Reader-brain runtime status should not expose token values",
+            )
+            assert_true(
+                reader_status["health_url"] == "https://reader.example/v1/models",
+                "Reader-brain runtime status should expose the health URL",
+            )
+
     # Test: runtime status includes Modal Klein path
     with patch.object(app, "KLEIN_MODAL_ENDPOINT", ""):
         status = app._runtime_status_core()