health: /healthz reports live state, one payload on every backend

Production verification could not answer "is the geo denylist actually in
force?" from outside. The control board and the public policy showcase
both showed seven countries denied while every request was served 200,
and the only surfaces that could have settled it — the boot log and the
token-gated operator panel — need credentials a verification pass does
not have. So the probe now carries what it takes to tell.

Adds two fields:
  app  — WHICH satellite answered. `build` says which commit; on a fleet
         where several hosts share a template and a hostname can be
         repointed between services, those are different questions.
  geo  — {configured, denied}. Counts and flags only, never the country
         codes: they are already public on /showcase/policy-panel, but a
         health endpoint is not where anyone should learn policy.

FIXES TWO INHERITED DEFECTS found while adding them.

1. THE PAYLOAD WAS A SNAPSHOT. register_health_route computed it ONCE at
   registration and the route closed over that dict. Harmless while every
   field was static (ok/backend/dash_version/build never change for a
   running process) and silently wrong the moment one is not — the route
   is registered at run.py:566 and configure_geo runs ~150 lines later,
   so the first version of this diagnostic reported the guardrail
   UNCONFIGURED on a host where it is configured. The diagnostic lying in
   exactly the situation it exists for. Now built per request.

2. FASTAPI HAD ITS OWN PAYLOAD. lib/asgi_routes.py constructed
   HealthResponse independently and never called health_payload, so a
   FastAPI deployment silently lacked `build` — and cd.yml's build-match
   wait polls /healthz for precisely that field. It would have fallen
   into the "predates the build field" warning path forever, verifying
   whichever release happened to be serving rather than the one it
   shipped. That is the muicharts defect the wait was written to prevent,
   reintroduced by backend. Both backends now render from one function;
   HealthResponse only types it for Swagger.

Three tests pin it: the app identity, that a live configure_geo change is
reflected (the snapshot regression), and that country codes never appear
in the body.

600 passed / 1 skipped (flask); 597 / 4 (fastapi); flake8 clean.

Author: pip-install-python

lib/asgi_routes.py

@@ -50,9 +50,23 @@ class PageListResponse(BaseModel):
 
 
 class HealthResponse(BaseModel):
+    """The probe contract, identical on every backend.
+
+    `lib.health.health_payload` is the single source — this model only types
+    it for Swagger. It used to be built independently here, which meant a
+    FastAPI deployment silently lacked `build`: CD's build-match wait polls
+    /healthz for exactly that field, so it would have fallen into the
+    "predates the build field" warning path forever, verifying whichever
+    release happened to be serving.
+    """
+
     ok: bool = True
     backend: str
     dash_version: str
+    # Optional because they are environment-dependent, not backend-dependent.
+    build: Optional[str] = None
+    app: Optional[str] = None
+    geo: Optional[dict] = None
 
 
 # ---------------------------------------------------------------------------
@@ -102,11 +116,12 @@ def build_health_router() -> APIRouter:
 
     @router.get("/healthz", response_model=HealthResponse, summary="Liveness probe")
     def healthz() -> HealthResponse:
-        return HealthResponse(
-            ok=True,
-            backend="fastapi",
-            dash_version=dash.__version__,
-        )
+        # One payload builder for all three backends — see HealthResponse.
+        # Built per request: `geo` reports live state, and this route is
+        # mounted long before configure_geo runs.
+        from lib.health import health_payload
+
+        return HealthResponse(**health_payload("fastapi"))
 
     return router
 

lib/health.py

@@ -32,6 +32,34 @@ def health_payload(backend: str) -> dict:
     build = os.environ.get("RENDER_GIT_COMMIT")
     if build:
         payload["build"] = build
+
+    # WHICH satellite answered. `build` says which commit, this says which
+    # app — and on a fleet where several hosts share a template and a
+    # hostname can be repointed, "is this the site I think it is?" is a
+    # different question from "is this the build I shipped?". Cheap, and the
+    # hub's sweep gets it for free.
+    payload["app"] = os.environ.get("SATELLITE_APP_KEY") or "unknown"
+
+    # The geo guardrail's LIVE state. Added 2026-08-23 after a production
+    # verification could not answer "is the denylist actually in force?"
+    # from outside: the control board and the public policy showcase both
+    # showed countries denied while every request was served 200, and the
+    # only surfaces that could have settled it (the boot log, the operator
+    # panel) need credentials this check does not have.
+    #
+    # Counts and flags only — never the country codes. The codes are already
+    # public on /showcase/policy-panel, but a health endpoint should not be
+    # the place anyone learns policy.
+    try:
+        from dash_improve_my_llms import geo
+
+        payload["geo"] = {
+            "configured": bool(geo.is_configured()),
+            "denied": len(geo.effective_policy().get("deny_countries") or []),
+        }
+    except Exception:  # never let a diagnostic break the health probe
+        payload["geo"] = {"configured": False, "denied": 0, "error": True}
+
     return payload
 
 
@@ -41,20 +69,26 @@ def register_health_route(app, backend: str) -> None:
         return
 
     server = app.server
-    payload = health_payload(backend)
 
+    # Built PER REQUEST, not once at registration. It used to be a snapshot
+    # closed over by the route — harmless while every field was static
+    # (ok/backend/dash_version/build never change for a running process), and
+    # silently wrong the moment one is not. This route is registered at
+    # run.py:566 and `configure_geo` runs ~150 lines later, so a snapshot
+    # reported the guardrail as unconfigured on a host where it is configured
+    # — the diagnostic lying in exactly the situation it exists for.
     if backend == "quart":
         from quart import jsonify
 
         @server.get("/healthz")
         async def _healthz():  # pragma: no cover — quart runtime
-            return jsonify(payload)
+            return jsonify(health_payload(backend))
     else:
         from flask import jsonify
 
         @server.get("/healthz")
         def _healthz():
-            return jsonify(payload)
+            return jsonify(health_payload(backend))
 
     print(f"[boilerplate] /healthz registered ({backend}) — "
           "the 2plot.ai hourly health sweep probes this path.")

tests/test_llms_routes.py

@@ -277,3 +277,76 @@ def test_nav_block_is_absent_from_the_root_index(client):
     body = client.get("/llms.txt").text
     assert "## Pages" in body, "the root document should be an index"
     assert not CHROME.search(body), "viewer chrome leaked into the root index"
+
+
+# ---------------------------------------------------------------------------
+# /healthz is a LIVE report, not a snapshot
+# ---------------------------------------------------------------------------
+
+def test_healthz_reports_which_app_answered(client):
+    """`build` says which commit; `app` says which satellite.
+
+    On a fleet where several hosts share a template and a hostname can be
+    repointed between services, those are different questions.
+    """
+    import json
+
+    payload = json.loads(client.get("/healthz").text)
+    assert payload["app"], "no app identity on /healthz"
+    assert payload["ok"] is True
+
+
+def test_healthz_reports_the_live_geo_state(app_module, client):
+    """The regression pin for a snapshot payload.
+
+    `register_health_route` used to compute the payload ONCE at registration
+    and close over it. Harmless while every field was static — and silently
+    wrong the moment one is not. The route is registered ~150 lines before
+    `configure_geo` runs, so a snapshot reported the guardrail unconfigured
+    on a host where it is configured: the diagnostic lying in exactly the
+    situation it exists for.
+    """
+    import json
+
+    from lib import policy_store
+
+    before = json.loads(client.get("/healthz").text)["geo"]
+    assert before["configured"] is True, (
+        "this app calls configure_geo unconditionally, so /healthz must "
+        "report it configured"
+    )
+
+    try:
+        app_module.configure_geo(deny_countries=["RU", "CN"])
+        after = json.loads(client.get("/healthz").text)["geo"]
+        assert after["denied"] == 2, (
+            f"/healthz did not follow a live config change ({after}) — it is "
+            "a snapshot again"
+        )
+    finally:
+        app_module.configure_geo(
+            deny_countries=policy_store.geo_deny,
+            unknown=policy_store.geo_unknown(),
+            exempt_paths=("/healthz", "/health", "/livez", "/readyz"),
+        )
+
+
+def test_healthz_never_publishes_the_country_codes(app_module, client):
+    """Counts and flags only. The codes are already public on the policy
+    showcase, but a health endpoint is not where anyone should learn policy.
+    """
+    import json
+
+    from lib import policy_store
+
+    try:
+        app_module.configure_geo(deny_countries=["RU", "CN"])
+        body = client.get("/healthz").text
+        assert "RU" not in body and "CN" not in body, body
+        assert json.loads(body)["geo"]["denied"] == 2
+    finally:
+        app_module.configure_geo(
+            deny_countries=policy_store.geo_deny,
+            unknown=policy_store.geo_unknown(),
+            exempt_paths=("/healthz", "/health", "/livez", "/readyz"),
+        )