feat(gateway): add authenticated runtime readiness checks

tests/gateway/test_api_server.py

@@ -764,7 +764,8 @@ class TestHealthDetailedEndpoint:
                 resp = await cli.get("/health/detailed")
                 assert resp.status == 200
                 data = await resp.json()
-                assert data["status"] == "ok"
+                assert data["status"] == "degraded"
+                assert data["readiness"]["checks"]["gateway"]["status"] == "degraded"
                 assert data["gateway_state"] is None
                 assert data["platforms"] == {}
                 # No runtime file ⇒ state None ⇒ not busy, not drainable.
@@ -789,6 +790,36 @@ class TestHealthDetailedEndpoint:
                 resp = await cli.get("/health/detailed", headers=headers)
                 assert resp.status == 200
 
+    @pytest.mark.asyncio
+    async def test_health_detailed_reports_runtime_readiness(self, adapter):
+        """Detailed health exposes bounded readiness probes without changing /health."""
+        app = _create_app(adapter)
+        expected = {
+            "status": "degraded",
+            "checks": {
+                "state_db": {"status": "ok"},
+                "config": {"status": "degraded", "detail": "using last-known-good"},
+            },
+        }
+        with patch("gateway.status.read_runtime_status", return_value={"gateway_state": "running"}), \
+             patch("gateway.platforms.api_server.collect_runtime_readiness", return_value=expected):
+            async with TestClient(TestServer(app)) as cli:
+                resp = await cli.get("/health/detailed")
+                assert resp.status == 200
+                data = await resp.json()
+                assert data["status"] == "degraded"
+                assert data["readiness"] == expected
+
+    @pytest.mark.asyncio
+    async def test_public_health_does_not_run_readiness_probes(self, adapter):
+        app = _create_app(adapter)
+        with patch("gateway.platforms.api_server.collect_runtime_readiness") as probe:
+            async with TestClient(TestServer(app)) as cli:
+                resp = await cli.get("/health")
+                assert resp.status == 200
+                assert (await resp.json())["status"] == "ok"
+        probe.assert_not_called()
+
 
 # ---------------------------------------------------------------------------
 # /v1/models endpoint

tests/gateway/test_readiness.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+
+from gateway.readiness import collect_runtime_readiness
+
+
+def test_collect_runtime_readiness_reports_healthy_local_runtime(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        "model:\n  provider: openrouter\n  model: test/model\n",
+        encoding="utf-8",
+    )
+    with sqlite3.connect(home / "state.db") as conn:
+        conn.execute("CREATE TABLE probe (id INTEGER PRIMARY KEY)")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    result = collect_runtime_readiness(
+        model_name="test/model",
+        runtime_status={
+            "gateway_state": "running",
+            "platforms": {"telegram": {"state": "connected"}},
+            "updated_at": "2026-07-09T00:00:00Z",
+        },
+        api_run_queue_depth=2,
+    )
+
+    assert result["status"] == "ok"
+    assert result["checks"]["state_db"]["status"] == "ok"
+    assert result["checks"]["config"]["status"] == "ok"
+    assert result["checks"]["provider"]["status"] == "ok"
+    assert result["checks"]["gateway"]["status"] == "ok"
+    assert result["checks"]["background_queues"]["api_runs"] == 2
+    assert result["checks"]["disk"]["status"] in {"ok", "degraded"}
+
+
+def test_collect_runtime_readiness_degrades_on_invalid_config_and_stopped_gateway(
+    tmp_path, monkeypatch
+):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text("model: [unterminated", encoding="utf-8")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    result = collect_runtime_readiness(
+        model_name="",
+        runtime_status={"gateway_state": "stopped", "platforms": {}},
+    )
+
+    assert result["status"] == "degraded"
+    assert result["checks"]["config"]["status"] == "degraded"
+    assert result["checks"]["provider"]["status"] == "degraded"
+    assert result["checks"]["gateway"]["status"] == "degraded"
+    # Readiness is diagnostic data, not an exception or a destructive repair.
+    assert (home / "config.yaml").read_text(encoding="utf-8") == "model: [unterminated"
+
+
+def test_collect_runtime_readiness_marks_corrupt_state_db_degraded(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "config.yaml").write_text("{}\n", encoding="utf-8")
+    (home / "state.db").write_bytes(b"not sqlite")
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    result = collect_runtime_readiness(model_name="configured-model", runtime_status={})
+
+    assert result["status"] == "degraded"
+    assert result["checks"]["state_db"]["status"] == "degraded"
+    assert "detail" in result["checks"]["state_db"]
+
+
+def test_collect_runtime_readiness_never_exposes_config_values(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    secret = "do-not-return-this-value"
+    (home / "config.yaml").write_text(
+        f"model:\n  provider: openrouter\nprivate_value: {secret}\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HERMES_HOME", str(home))
+
+    result = collect_runtime_readiness(model_name="model", runtime_status={})
+
+    assert secret not in json.dumps(result)
+    assert str(home) not in json.dumps(result)
+    assert result["checks"]["config"]["status"] == "ok"
+
+
+def test_collect_runtime_readiness_uses_active_profile_home(tmp_path, monkeypatch):
+    profile_home = tmp_path / "profiles" / "coder"
+    profile_home.mkdir(parents=True)
+    (profile_home / "config.yaml").write_text("{}\n", encoding="utf-8")
+    monkeypatch.setenv("HERMES_HOME", str(profile_home))
+
+    result = collect_runtime_readiness(model_name="model", runtime_status={})
+
+    assert result["checks"]["config"]["status"] == "ok"
+    assert not (tmp_path / ".hermes" / "state.db").exists()
+    assert os.environ["HERMES_HOME"] == str(profile_home)