monitor: calibrate staleness detection to the 3h scan cadence

The map stopped moving at 2026-08-28T00:29Z and every signal this
repository publishes stayed green for the next seven hours: all seven
workflow badges passing, no alert issue, no red run. That is the exact
silent-failure mode health.yml was written to prevent, and it did not
fire because the monitor is calibrated to a round number instead of to
the cadence of the thing it monitors.

The arithmetic: the engine publishes every 3h, the monitor runs every
12h ("43 6,18 * * *") against a 12h threshold. Data that freezes just
after a check is 11.9h old at the next one — under the limit — and is
not reported until the check after that. Worst-case detection latency
is ~24h for a pipeline whose whole claim is a 3h refresh.

Three changes, no new dependencies:

  * MAX_AGE_HOURS 12 -> 7, overridable via RADAR_MAX_AGE_HOURS. One
    dropped scheduled run is normal on GitHub and must not page anyone;
    two consecutive misses is a stalled pipeline. 7h is 6h of missed
    scans plus grace for engine runtime and sync lag.

  * health.yml cron "43 6,18 * * *" -> "43 */3 * * *", still offset from
    the engine (:17) and the sync (:37). The check reads two small JSON
    files over HTTPS; running it eight times a day costs seconds on a
    public repository and cuts worst-case detection from ~24h to ~10h.

  * sync.yml gains a freshness readout after the contract gate. The gate
    proves the payload is well-formed; it cannot prove it is recent. A
    frozen engine keeps serving last night's valid JSON, the sync finds
    nothing to commit and exits 0. The readout prints the payload age on
    every run and raises a ::warning:: past the threshold, so a stalled
    upstream is visible in the run log itself rather than only in an
    issue that may not open for hours.

This does not fix the outage. The sync path is healthy: it pulled the
00:24Z payload, the contract gate passed, and there has been nothing new
upstream since. The engine (private) is what stopped publishing. This
change is about the second defect the outage exposed — that nothing here
said so.

Author: Denis Yermakou

.github/workflows/health.yml

@@ -7,7 +7,12 @@ name: Health monitor
 
 on:
   schedule:
-    - cron: "43 6,18 * * *"   # twice a day, offset from the radar cron
+    # Every 3h, offset from the engine (:17) and the sync (:37). A monitor
+    # that runs every 12h against a 12h threshold cannot see an outage shorter
+    # than ~24h — which is how a 7h freeze stayed green with every badge
+    # passing. The check reads two small JSON files; running it 8x a day costs
+    # seconds on a public repo and cuts worst-case detection to ~10h.
+    - cron: "43 */3 * * *"
   workflow_dispatch:
 
 permissions:

.github/workflows/sync.yml

@@ -81,6 +81,32 @@ jobs:
           print("contract gate: schema + feed well-formed")
           GATE
 
+      - name: Freshness readout
+        # The contract gate proves the payload is well-formed. It cannot prove
+        # the payload is recent: a frozen engine keeps serving last night's
+        # valid JSON, this workflow finds nothing to commit, exits 0, and the
+        # badge stays green while the public map quietly stops moving. That is
+        # the failure this repository already paid for once. Read the age out
+        # loud on every run so a stalled upstream is visible in the run log
+        # rather than only in an issue the monitor may not open for hours.
+        run: |
+          python3 - <<'FRESH'
+          import json, os
+          from datetime import datetime, timezone
+          limit = float(os.environ.get("RADAR_MAX_AGE_HOURS", "7"))
+          at = json.load(open("data/last_run.json"))["at"]
+          dt = datetime.fromisoformat(at.replace("Z", "+00:00"))
+          age = (datetime.now(timezone.utc) - dt).total_seconds() / 3600
+          line = f"last engine publish {at} — {age:.1f}h old (limit {limit:.0f}h)"
+          print(line)
+          with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as fh:
+              fh.write(f"- {'STALE' if age > limit else 'fresh'}: {line}\n")
+          if age > limit:
+              print(f"::warning title=Engine data is stale::{line}. The sync "
+                    "path is healthy; the upstream engine has not published. "
+                    "Check the engine repository's Actions quota and schedule.")
+          FRESH
+
       - name: Redeploy the site with whatever arrived
         env:
           GH_TOKEN: ${{ github.token }}

scripts/health_check.py

@@ -6,7 +6,9 @@
 radar is healthy:
 
   * STALE   — status.generated_at older than MAX_AGE_HOURS (scans run every
-              3 hours; 12h of silence means several consecutive failures).
+              3 hours, so 7h of silence means two consecutive scans are gone;
+              one dropped scheduled run is tolerated, two are not). Override
+              with RADAR_MAX_AGE_HOURS when the upstream cadence changes.
   * FAILED  — the last recorded run ended with ok=false.
 
 On a problem it opens (or updates) a single, marker-identified alert issue.
@@ -32,7 +34,11 @@
 PAGES = f"https://{OWNER.lower()}.github.io/{NAME}/"
 API = f"https://api.github.com/repos/{REPO}"
 MARKER = "<!-- axonos-radar-health-alert f3a91c2e -->"
-MAX_AGE_HOURS = 12
+# Calibrated to the cadence of the thing being monitored, not to a round
+# number. The engine publishes every 3h; GitHub routinely drops one scheduled
+# run, so a single miss must not page anyone. Two consecutive misses is a
+# stalled pipeline and has to be visible the same day, not a day later.
+MAX_AGE_HOURS = float(os.environ.get("RADAR_MAX_AGE_HOURS", "7"))
 BOT_LOGINS = ("github-actions[bot]", "github-actions")
 
 HEADERS = {"Accept": "application/vnd.github+json", "User-Agent": "axonos-radar-health",