gig-preflight: judge CPU knobs against the thermal-pilot's declared rung

Rung 1 (epp=balance_power, ceiling 65%) is the pilot's resting posture, so
the fixed 'must be 100%' check turned every launch into a NO-GO whose fixes
fought the pilot. Pass when the knobs match the declared rung; FAIL only when
they disagree (a second writer). Stale or absent state keeps the old strict
behaviour.

tools/gig-preflight.py

@@ -99,6 +99,26 @@ def run(cmd: list[str], timeout=5) -> str:
 # --------------------------------------------------------------------------- #
 # 1. the perf regime — the one that cost 2671 xruns/hour
 # --------------------------------------------------------------------------- #
+PILOT_STATE = Path(os.environ.get("THERMAL_PILOT_STATE", "/run/thermal-pilot.state"))
+PILOT_FRESH_S = 120      # the pilot rewrites its state every tick; older = not steering
+# rung -> (epp, ceiling is 100%?). Mirrors rung_knobs() in SRE/thermal/thermal-pilot;
+# the rung-1 percentage is an env knob there (RUNG1_PCT), so only "below 100" is
+# asserted here, never the number.
+PILOT_RUNG_KNOBS = {0: ("power", True), 1: ("balance_power", False),
+                    2: ("balance_performance", True)}
+
+
+def pilot_rung() -> int | None:
+    """The rung the thermal-pilot declares RIGHT NOW, or None when it is not steering
+    (no state file, stale, or it wrote `off`). None means: judge the knobs on their
+    own, as before."""
+    try:
+        if time.time() - PILOT_STATE.stat().st_mtime > PILOT_FRESH_S:
+            return None
+        m = re.match(r"rung=(\d+)", PILOT_STATE.read_text())
+    except OSError:
+        return None
+    return int(m.group(1)) if m else None
 def check_perf() -> None:
     """Clock ceiling, power bias and live frequency, read from sysfs.
 
@@ -114,19 +134,48 @@ def check_perf() -> None:
     cur = read_int(f"{cpu}/cpu0/cpufreq/scaling_cur_freq", 0) // 1000
     ceil = read_int(f"{cpu}/cpu0/cpufreq/scaling_max_freq", 0) // 1000
 
-    if epp in ("power", "balance_power"):
+    rung = pilot_rung()
+    if rung is not None:
+        # The thermal-pilot owns epp, max_perf_pct and turbo and moves them as it
+        # walks its heat ladder. Rung 1 (epp=balance_power, ceiling 65%) is the
+        # deliberate resting posture of the `performance` profile, so judging
+        # those knobs against a fixed "must be 100%" blocked every launch with
+        # two FAILs that told the owner to fight the pilot. The question that
+        # matters is whether the knobs are the ones the pilot DECLARED: a
+        # mismatch means a second writer, and that is the real fault.
+        want_epp, want_full = PILOT_RUNG_KNOBS.get(rung, (None, None))
+        again = pilot_rung()                      # the rung may step mid-read
+        for r in {rung, again} - {None}:
+            w_epp, w_full = PILOT_RUNG_KNOBS.get(r, (None, None))
+            if epp == w_epp and ((maxp == 100) if w_full else (maxp < 100)):
+                add("cpu energy bias", OK, f"epp={epp} (pilot rung {r}, by design)")
+                add("clock ceiling", OK,
+                    f"max_perf_pct={maxp}% of {ceil}MHz (pilot rung {r}, by design)")
+                add("cpu governor", OK, f"gov={gov} (pilot rung {r})")
+                break
+        else:
+            add("cpu energy bias", FAIL,
+                f"epp={epp}, max_perf_pct={maxp}% but the pilot says rung {rung} "
+                f"(expects epp={want_epp}) — another writer is on the knobs",
+                "journalctl -t thermal-pilot --since -10min; look for perf.sh / "
+                "bridge perf-watch / thermal-mode writing against the pilot")
+    elif epp in ("power", "balance_power"):
         add("cpu energy bias", FAIL, f"epp={epp} — HWP will sit at the floor",
             "sudo cpupower set --epp performance   # or: bridge.py perf standard")
     else:
         add("cpu energy bias", OK, f"epp={epp}")
 
-    if gov == "powersave":
+    if rung is not None:
+        pass                                      # judged above, against the pilot
+    elif gov == "powersave":
         add("cpu governor", WARN, f"gov={gov}",
             "cd ~/Work/Sound/Tidal/tools/bridge && python3 bridge.py perf standard")
     else:
         add("cpu governor", OK, f"gov={gov}")
 
-    if maxp is not None and maxp < 100:
+    if rung is not None:
+        pass
+    elif maxp is not None and maxp < 100:
         eff = int(ceil * maxp / 100) if ceil else 0
         add("clock ceiling", FAIL,
             f"max_perf_pct={maxp}% — capped at ~{eff}MHz of {ceil}MHz",

tools/tests/test_gig_preflight_pilot.py

+"""The preflight judges the CPU knobs against the thermal-pilot's declared rung.
+
+2026-10-11. Every launch ended `NO-GO` on two FAILs (`epp=balance_power`,
+`max_perf_pct=65%`) whose suggested fixes would have fought the pilot: those
+are rung 1 of its heat ladder, the resting posture of the `performance` profile.
+A gate that cries wolf on every boot gets ignored, and that day it ignored the
+one real fault (the LCXL3 driver down) sitting among eleven WARNs.
+
+These tests pin the reader that tells "the pilot is steering" from "it is not".
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import pathlib
+import time
+
+TOOLS = pathlib.Path(__file__).resolve().parents[1]
+
+
+def _load():
+    spec = importlib.util.spec_from_file_location(
+        "gig_preflight", TOOLS / "gig-preflight.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _with_state(tmp_path, text, age_s=0):
+    mod = _load()
+    p = tmp_path / "thermal-pilot.state"
+    p.write_text(text)
+    if age_s:
+        old = time.time() - age_s
+        os.utime(p, (old, old))
+    mod.PILOT_STATE = p
+    return mod
+
+
+def test_fresh_state_gives_the_declared_rung(tmp_path):
+    mod = _with_state(tmp_path, "rung=1 profile=performance pkg=67 fan=0")
+    assert mod.pilot_rung() == 1
+
+
+def test_each_rung_is_read_not_assumed(tmp_path):
+    for r in (0, 1, 2):
+        mod = _with_state(tmp_path, f"rung={r} profile=auto pkg=60 fan=0")
+        assert mod.pilot_rung() == r
+
+
+def test_stale_state_means_the_pilot_is_not_steering(tmp_path):
+    mod = _with_state(tmp_path, "rung=1 profile=performance", age_s=600)
+    assert mod.pilot_rung() is None
+
+
+def test_off_and_garbage_mean_not_steering(tmp_path):
+    assert _with_state(tmp_path, "off").pilot_rung() is None
+    assert _with_state(tmp_path, "").pilot_rung() is None
+    assert _with_state(tmp_path, "nonsense").pilot_rung() is None
+
+
+def test_missing_file_means_not_steering(tmp_path):
+    mod = _load()
+    mod.PILOT_STATE = tmp_path / "does-not-exist"
+    assert mod.pilot_rung() is None
+
+
+def test_rung_table_mirrors_the_pilots_ladder():
+    """Rung 0 and 2 run at full ceiling; rung 1 is the capped posture."""
+    knobs = _load().PILOT_RUNG_KNOBS
+    assert knobs[0] == ("power", True)
+    assert knobs[1] == ("balance_power", False)
+    assert knobs[2] == ("balance_performance", True)