clearotron 0.2.1 → 0.2.3

package/scripts/live-surface-check.mjs

@@ -54,7 +54,7 @@
 // WRONG — the deployment was fine; the caller was not. With the portal's own ops token the same call
 // answers `clients: 10`.
 //
-// #98's validation failed because it ran in the wrong ENVIRONMENT. A probe can fail the same way by
+// an earlier validation failed because it ran in the wrong ENVIRONMENT. A probe can fail the same way by
 // running as the wrong IDENTITY. So this check authenticates the way the portal does, and a missing
 // token is reported as "not probed" rather than quietly producing a false failure.
 //
@@ -90,7 +90,9 @@ import { unitsActiveVerdict } from "../driver/unit-state-verdict.mjs";
 import { deploymentBox } from "../shared/deployment-box.mjs";   // — extracted; one allowlist, two readers
 import { unitFileDriftVerdict } from "../driver/unit-file-drift.mjs";   //
 import { placeholdersIn, resolveValues, renderUnit } from "../driver/systemd/render-units.mjs";   //
-import { CHECKED_UNITS, unitInventoryVerdict, serviceCommitVerdict, unitWorkingDirectory } from "../driver/unit-inventory.mjs";   // · -bundle ·
+import { CHECKED_UNITS, CHECKED_TIMERS, timerVerdict, unitInventoryVerdict, serviceCommitVerdict, unitWorkingDirectory, unitClone } from "../driver/unit-inventory.mjs";   // · -bundle ·
+import { entrypointOf } from "../driver/systemd/install-census.mjs";   // the ONE ExecStart parser — a unit says which module it runs
+import { treeOfRunning } from "../shared/checkout-move.mjs";           // …and the live argv says which tree that module came from
 import { findUnitFiles, unitFilePath } from "../driver/unit-files.mjs";   //
 import { managerGroupsVerdict } from "../driver/manager-groups-verdict.mjs";   //
 import { config } from "../driver/driver.config.mjs";                          //
@@ -224,6 +226,35 @@ function userBusEnv() {
 // Returns {clones, probe}. `probe` is the honest answer to "could I look at all?" — {ok, why} — and it is
 // SEPARATE from the clones list on purpose. "enumerated, nothing to compare" and "could not enumerate"
 // were the same empty array before, and this suite exists because absences were read as successes.
+/**
+ * Ask each declared TIMER about itself, as a timer.
+ *
+ * Deliberately not folded into the loop below. That loop asks a service for its WorkingDirectory and
+ * MainPID and attributes a running process to a checkout — none of which a `.timer` has, so putting
+ * timers through it would produce rows whose every attribution field is empty for a reason that is not
+ * a finding. Two questions, two calls, and each says what it could not answer.
+ */
+function declaredTimers() {
+  if (!CHECKED_TIMERS.length) return { rows: [], probeFailed: null };
+  const env = userBusEnv();
+  const rows = [];
+  let probeFailed = null;
+  for (const unit of CHECKED_TIMERS) {
+    try {
+      const shown = execFileSync("systemctl", ["--user", "show", unit, "-p", "ActiveState", "-p", "LoadState"],
+        { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] });
+      const f = Object.fromEntries(shown.split("\n").filter(Boolean).map((l) => { const [k, ...v] = l.split("="); return [k, v.join("=")]; }));
+      // An EMPTY answer is the no-session-bus case, and it must not read as a stopped timer — that is
+      // the shape that turns "could not ask" into a finding about the box.
+      if (!f.ActiveState) { probeFailed = probeFailed ?? `systemctl --user answered nothing for ${unit}`; continue; }
+      rows.push({ unit, active: f.ActiveState || null, load: f.LoadState || null });
+    } catch (e) {
+      probeFailed = probeFailed ?? String(e?.message ?? e).slice(0, 120);
+    }
+  }
+  return { rows, probeFailed };
+}
+
 function serviceClones() {
   // — the list is DECLARED, not written here. It used to be eight names inline, which put a unit
   // inside the drift guarantee or outside it by omission: `client-access` was live on production and in
@@ -234,14 +265,20 @@ function serviceClones() {
   const out = [];
   let reached = 0, lastErr = null;
   for (const u of units) {
-    let wd = null, active = null, type = null, since = null;
+    let wd = null, active = null, type = null, since = null, mainPid = null, fragment = null, load = null;
     try {
       // — `Type` and `StateChangeTimestamp` ride along on a call that was already being made. Both
       // are for the MESSAGE, never for the verdict: Type tells a reader whether an `activating` unit is a
       // oneshot mid-fire or a service mid-restart, and the timestamp lets a human judge a long
       // `activating` that this check deliberately does not judge (see driver/unit-state-verdict.mjs).
+      //
+      // `MainPID` and `FragmentPath` ride along for the SECOND way to attribute a unit to a checkout,
+      // below. Same call, no extra round trip. Deliberately NOT `ExecStart`: systemd renders it
+      // unexpanded — `argv[]=/usr/bin/node ${CLEAROTRON_CHECKOUT_DIR}/driver/runner.mjs` — so the one
+      // field that looks like it names the tree is the one field that does not.
       const shown = execFileSync("systemctl", ["--user", "show", u,
-        "-p", "WorkingDirectory", "-p", "ActiveState", "-p", "Type", "-p", "StateChangeTimestamp"],
+        "-p", "WorkingDirectory", "-p", "ActiveState", "-p", "Type", "-p", "StateChangeTimestamp",
+        "-p", "MainPID", "-p", "FragmentPath", "-p", "LoadState"],
         { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] });
       // `show` answers for a unit that does not exist too (ActiveState=inactive), so a PARSED answer is
       // proof the bus was reachable — which is exactly the fact the old catch destroyed.
@@ -252,19 +289,77 @@ function serviceClones() {
         if (k === "ActiveState") active = v.join("=") || null;
         if (k === "Type") type = v.join("=") || null;
         if (k === "StateChangeTimestamp") since = v.join("=") || null;
+        if (k === "MainPID") mainPid = v.join("=") || null;
+        if (k === "FragmentPath") fragment = v.join("=") || null;
+        // `LoadState` is the discriminator the comment above names and nothing acted on: `not-found`
+        // means this deployment DECLARES a unit that does not exist on this box — a defect in the
+        // declaration, not a unit at rest. Both used to arrive here as `ActiveState=inactive`.
+        if (k === "LoadState") load = v.join("=") || null;
       }
     } catch (e) { lastErr = String(e?.stderr || e?.message || e).replace(/\s+/g, " ").trim().slice(0, 160); }
-    // — an inactive unit reporting nothing is NOT a gap in the population; there is genuinely
-    // nothing to compare, and `unreadable: null` says so. Only the two branches below are gaps.
-    if (!wd) { out.push({ unit: u, active, type, since, clone: null, head: null, unreadable: null }); continue; }
-    const parsed = unitWorkingDirectory(wd);
-    if (!parsed.path) { out.push({ unit: u, active, type, since, clone: null, head: null, unreadable: parsed.why }); continue; }
-    const top = gitTry(parsed.path, "rev-parse", "--show-toplevel");
-    if (!top.ok) { out.push({ unit: u, active, type, since, clone: null, head: null, unreadable: `git could not read ${parsed.path}: ${top.err}` }); continue; }
-    const root = top.out;
-    const head = gitTry(root, "rev-parse", "HEAD");
-    out.push({ unit: u, active, type, since, clone: root, head: head.ok ? head.out : null,
-      unreadable: head.ok ? null : `git could not read HEAD in ${root}: ${head.err}` });
+
+    // ── ATTRIBUTION ONE: THE DECLARATION ────────────────────────────────────────────────────────────
+    let declaredTree = null, declaredWhy = null;
+    if (!wd) declaredWhy = "the unit reported no WorkingDirectory";
+    else {
+      const parsed = unitWorkingDirectory(wd);
+      if (!parsed.path) declaredWhy = parsed.why;
+      else {
+        const top = gitTry(parsed.path, "rev-parse", "--show-toplevel");
+        if (top.ok) declaredTree = top.out;
+        else declaredWhy = `git could not read ${parsed.path}: ${top.err}`;
+      }
+    }
+
+    // ── ATTRIBUTION TWO: WHAT THE PROCESS IS ACTUALLY RUNNING ───────────────────────────────────────
+    //
+    // The unit file names its entrypoint as `${CLEAROTRON_CHECKOUT_DIR}/<module>`; the LIVE process was
+    // started with that expanded, and `/proc/<pid>/cmdline` carries the resolved absolute path. So the
+    // unit file says WHICH module to look for and the process says WHERE it came from. Both readers
+    // already exist and are tested — this composes them rather than parsing anything new.
+    let runningTree = null, runningWhy = null;
+    const pid = Number(mainPid);
+    if (!pid) runningWhy = "the unit reported no MainPID, so no running process could be read";
+    else if (!fragment) runningWhy = `pid ${pid} is running but the unit reported no FragmentPath, so nothing says which module to look for`;
+    else {
+      let unitText = null;
+      try { unitText = readFileSync(fragment, "utf8"); }
+      catch (e) { runningWhy = `the unit file ${fragment} could not be read: ${String(e?.message ?? e).slice(0, 80)}`; }
+      if (unitText !== null) {
+        const { rel, unreadable } = entrypointOf(unitText);
+        if (!rel) runningWhy = unreadable;
+        else {
+          let cmdline = null;
+          try { cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8"); }
+          catch (e) { runningWhy = `/proc/${pid}/cmdline could not be read: ${String(e?.message ?? e).slice(0, 80)}`; }
+          if (cmdline !== null) {
+            const { tree, why } = treeOfRunning(cmdline, rel);
+            if (!tree) runningWhy = why;
+            else {
+              const top = gitTry(tree, "rev-parse", "--show-toplevel");
+              if (top.ok) runningTree = top.out;
+              else runningWhy = `git could not read ${tree}, which pid ${pid} is running from: ${top.err}`;
+            }
+          }
+        }
+      }
+    }
+
+    const chosen = unitClone({ declaredTree, runningTree, declaredWhy, runningWhy });
+    // — an inactive unit that reported nothing is NOT a gap in the population; there is genuinely
+    // nothing to compare, and `unreadable: null` says so. A unit that IS running and could not be
+    // attributed is a gap, and the reason names both halves.
+    if (!chosen.clone) {
+      const idle = !wd && !pid;
+      out.push({ unit: u, active, load, type, since, clone: null, head: null, source: null,
+        unreadable: idle ? null : chosen.why });
+      continue;
+    }
+    const head = gitTry(chosen.clone, "rev-parse", "HEAD");
+    out.push({ unit: u, active, load, type, since, clone: chosen.clone, source: chosen.source,
+      disagreement: chosen.disagreement,
+      head: head.ok ? head.out : null,
+      unreadable: head.ok ? null : `git could not read HEAD in ${chosen.clone}: ${head.err}` });
   }
   const probe = reached > 0
     ? { ok: true, why: null }
@@ -441,7 +536,12 @@ try {
   //
   // The arm above already travels the route the harness uses (`mcpToolCall` on `MCP_URL`, the same
   // client `scripts/e2e.mjs` enqueues through), so a door that 401s every caller ALREADY fails this
-  // check and already fails the deploy — `scripts/deploy-test.sh` gates on this script's exit code.
+  // check and already fails the deploy — WHEN a deploy runs this script, which at the time of writing
+  // nothing does. `scripts/deploy-test.sh` gated on this script's exit code; that script is retired, and
+  // what replaced it was measured on the operations side and does NOT invoke this one. Nothing here is
+  // wrong: the check is a real instrument and its reasoning holds. It is simply not reached, and a caller
+  // is being wired back in. Until it is, read this as what the check is FOR, not as evidence that
+  // something enforces it.
   // That is the issue's first criterion, by its sanctioned second branch, and its third and fourth.
   //
   // What neither arm could say is WHY the door has the posture it has. This face reaches the auth-proxy
@@ -592,8 +692,10 @@ const { clones, probe: unitProbe } = serviceClones();
 const running = clones.filter((c) => c.head);
 const heads = [...new Set(running.map((c) => c.head))];
 // — THREE OUTCOMES, NOT TWO. This arm is the one whose entire purpose is to catch a service still
-// running an old bundle after a deploy, and deploy-test.sh runs it as the final gate on an instance that
-// deploys itself every hour. It had been degrading to `skip` with a reason that ASSERTED the deployment
+// running an old bundle after a deploy. `deploy-test.sh` ran it as the final gate on an instance that
+// deploys itself every hour; that script is retired and its replacement does not invoke this one, so at
+// the time of writing nothing reaches this arm on a deploy — see the note above. It had been degrading to
+// `skip` with a reason that ASSERTED the deployment
 // was not systemd --user — on a box where it is, and where the units are running.
 //   · could not look       → skip, naming the error. Not probed is not passed.
 //   · looked, found none   → skip, saying so. A genuinely non-systemd deployment lands here honestly.
@@ -664,7 +766,7 @@ else {
       // second criterion — an orphaned drainer in a closed login session is a
       // state health must say out loud, whatever the ruling on the posture.
       ppidOf: defaultPpidOf,
-      // tracker issue 206 — THE SAME TWO PROBES THE QUEUE ARM READS, so this arm and that one cannot
+      // THE SAME TWO PROBES THE QUEUE ARM READS, so this arm and that one cannot
       // reach opposite conclusions about one box. They did: the queue arm read the worker unit and said
       // the timer posture is retired here, while this one read nothing and called an absent drainer a
       // fault in the same report. A probe that throws answers `enabled: null`, which the rule resolves
@@ -816,6 +918,14 @@ else {
   const v = unitInventoryVerdict({ live: liveUnits, files: walk.files, collisions: walk.collisions,
     filesError: walk.error, box, probe });
   record("every live unit is declared", v.state, v.message);
+
+  // — AND WHETHER ANYTHING STILL STARTS THE TIMER-DRIVEN ONES. Reported separately from the line above
+  // because it answers a different question: that one says a declared unit exists and is not adrift,
+  // this one says its timer is still armed. A service whose timer was stopped satisfies the first and
+  // fails the second, and reads `inactive` for both — which is why one line could not carry both.
+  const t = declaredTimers();
+  const tv = timerVerdict(t.rows, { probeFailed: t.probeFailed });
+  record("every declared timer is still armed", tv.state, tv.message);
 }
 
 // ── — EVERY QUEUE THIS DEPLOYMENT WOULD DRAIN IS WATCHED BY SOMETHING ──────────────────────────

package/scripts/main-health.mjs

@@ -15,7 +15,7 @@
 // and that a red no fix can clear turns into a tax. The next person either stops, or learns to reason
 // past a red main, and the second one is how a real regression gets merged over.
 //
-// THIS IS 's DISTINCTION ONE SUBSYSTEM OVER. There it was `systemctl --user` with no bus reported
+// THIS IS the DISTINCTION ONE SUBSYSTEM OVER. There it was `systemctl --user` with no bus reported
 // as "the unit is not there"; here it is an unallocated runner reported as "the suite failed". Both are
 // could-not-look rendered as a finding, and both are fixed by refusing to answer rather than answering
 // wrongly.

package/scripts/merge-presence-check.mjs

@@ -5,7 +5,7 @@
 //
 // ── WHY THIS EXISTS ──────────────────────────────────────────────────────────────────────────────
 //
-// merged at 18:45:01Z. The commit carrying 's own acceptance check was authored at
+// merged at 18:45:01Z. The commit carrying its own acceptance check was authored at
 // 18:53:12Z — eight minutes AFTER the merge — and never reached `main`. The pull request closed
 // green showing one commit, the branch was deleted, and was labelled ready-for-verification
 // against a fix whose check did not exist. Nothing in the repository noticed. It surfaced because
@@ -213,8 +213,8 @@ export function presenceOf(sha, git, base = "origin/main") {
   // ── LANDED-AND-SINCE-REMOVED IS NOT LOST WORK, AND CALLING IT LOST IS THE WHOLE FAILURE ────────
   //
   // The first cut of this script reported six MISSING rows and every one of them was a merge that
-  // landed perfectly and was later retired ON PURPOSE: 's bin/register-ledger-prune.mjs deleted
-  // by, 's snapshot machinery deleted by, three env-governance.test.mjs rows rewritten
+  // landed perfectly and was later retired ON PURPOSE: the bin/register-ledger-prune.mjs deleted
+  // by, the snapshot machinery deleted by, three env-governance.test.mjs rows rewritten
   // by the same. Publishing those as lost work would have been six false accusations drawn
   // from a real signal — the exact shape this check exists to catch, running in the other direction.
   //

package/scripts/mint-suite-census.mjs

@@ -150,7 +150,7 @@ function main() {
   try { prev = JSON.parse(readFileSync(CENSUS, "utf8")); } catch { /* first mint */ }
 
   const lost = [];
-  // tracker issue 205 — THE THIRD BUCKET, ruled by overwatch 2026-09-06.
+  // THE THIRD BUCKET, ruled by overwatch 2026-09-06.
   //
   // A reasoned skip is neither a pass nor a loss, and this census had no place to put one. Two guards
   // that are each right about their own failure had come to disagree: `a-bail-on-an-unmeetable-
@@ -166,7 +166,7 @@ function main() {
   for (const { ws } of CENSUS_WORKSPACES) {
     const a = prev?.workspaces?.[ws]?.perFile ?? {};
     const b = next.workspaces[ws].perFile;
-    // tracker issue 205 — the buckets are decided in shared/suite-census.mjs, where a test can reach
+    // the buckets are decided in shared/suite-census.mjs, where a test can reach
     // them, and BOTH populations below read the same function. The two loops used to spell the decision
     // out separately and had already drifted on their all-clear line.
     const { added, gone, shrunk, grew, losses, notes, allClear } = censusBuckets({ prev: a, next: b });
@@ -175,14 +175,14 @@ function main() {
         ? `${ws}  REMOVED  ${f}  (was ${a[f].tests} tests, ${a[f].asserts} asserts)`
         : `${ws}  SHRANK   ${f}  ${a[f].tests}\u2192${b[f].tests} tests, ${a[f].asserts}\u2192${b[f].asserts} asserts`);
     }
-    // tracker issue 205 — a rising skip count is NOT a loss and does not refuse. It is collected for
+    // a rising skip count is NOT a loss and does not refuse. It is collected for
     // the bucket printed after both loops, where it is neither excused nor counted against the tree.
     for (const { file: f } of notes) noted.push(`${ws}  ${f}  ${a[f].skips ?? 0}\u2192${b[f].skips ?? 0} skip(s), `
       + `${a[f].todos ?? 0}\u2192${b[f].todos ?? 0} todo(s)`);
     console.log(`\n${ws}: ${Object.keys(next.workspaces[ws].perFile ?? {}).length} file(s)`);
     for (const f of added) console.log(`  + ${f}  (${b[f].tests} tests, ${b[f].asserts} asserts)`);
     // A file leaving the census, or shrinking inside it, is the shape this whole thing exists for.
-    // Printed loudly and separately, and — since 's loss arm — REFUSED below unless --allow-loss
+    // Printed loudly and separately, and — since the loss arm — REFUSED below unless --allow-loss
     // is passed. This comment used to end "an --apply that scrolls past these is the laundering", which
     // was an accurate description of what the code then did: it printed both lines and wrote the file.
     for (const f of gone) console.log(`  REMOVED  ${f}  (was ${a[f].tests} tests, ${a[f].asserts} asserts)`);
@@ -197,7 +197,7 @@ function main() {
     // a verdict. So growth is now printed as its own shape, and the all-clear says what it actually
     // checked instead of implying currency it never established.
     for (const f of grew) console.log(`  grew     ${f}  ${a[f].tests}→${b[f].tests} tests, ${a[f].asserts}→${b[f].asserts} asserts`);
-    // tracker issue 205 — `allClear` counts skips. Without that a file that gained nothing but skips
+    // `allClear` counts skips. Without that a file that gained nothing but skips
     // printed "(unchanged)" over a tree where an arm had stopped running, which is the exact
     // reassuring-narrator failure the growth line above was added to repair.
     if (allClear) console.log("  (unchanged — no file added, removed, grown, shrunk or newly skipped)");
@@ -239,7 +239,7 @@ function main() {
     else if (!undeclaredGone.length && !shrunk.length && !added.length) console.log("  (nothing LOST — the counts above moved, so the census on disk is stale)");
   }
 
-  // tracker issue 205 — PRINTED WHENEVER IT IS NON-EMPTY, on every mode this script has. `--check`
+  // PRINTED WHENEVER IT IS NON-EMPTY, on every mode this script has. `--check`
   // returns before `--apply`'s refusal and `--apply` returns before `--check`'s comparison, so a bucket
   // printed inside either one would be invisible from the other — and the mode a lane gate runs is the
   // one nobody watches.

package/scripts/nightly-notice.mjs

@@ -43,7 +43,7 @@ export function hoursSince(thenISO, nowISO) {
   return Math.floor((now - then) / 3_600_000);
 }
 
-/** The job's name, whichever shape the caller had. A bare string is the pre- form. */
+/** The job's name, whichever shape the caller had. A bare string is the pre-change form. */
 export function jobName(job) { return typeof job === "string" ? job : String(job?.name ?? "?"); }
 
 /**
@@ -151,8 +151,6 @@ export function noticeBody({ runUrl, sha, subject, failedJobs = [], lastGreenAt,
         + "passes — a run that never started cannot make the platform green."
       : "This thread is reused for every red night. Close it once the platform is green again — the next "
         + "red opens a new one.",
-    "",
-    "Agent: role-dev · bergface",
   ].join("\n");
 }
 

package/scripts/preinstall-node-check.mjs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// The install refuses an unsupported Node BEFORE anything is written — tracker issue 364.
+//
+// Three declarations already stated the requirement and none of them bound anyone: `engines.node` is a
+// WARNING unless the person installing has set `engine-strict`, `.nvmrc` is read by nvm and nothing
+// else, and the install guide is prose. An outside report arrived as "some node issues, not as obvious
+// as the README made it seem" — which is what a warning inside an install log looks like from outside.
+//
+// So this is a `preinstall` hook, node builtins only, because nothing is installed when it runs.
+//
+// IT NAMES THE LATER FAILURE, not just the version. The whole defect is that an unsupported Node
+// installs cleanly and then fails somewhere else saying nothing about Node, so a message that only
+// prints a semver range leaves the reader where they started.
+import { declaredRange, floorOf, meetsFloor, nodeFloorRefusal } from "../shared/node-floor.mjs";
+
+const range = declaredRange();
+if (!meetsFloor(process.versions.node, floorOf(range))) {
+  process.stderr.write(`\n${nodeFloorRefusal({ current: process.versions.node, required: floorOf(range).join("."), range })}\n`);
+  process.stderr.write("  Nothing has been installed.\n\n      nvm install 22 && nvm use 22\n\n");
+  process.stderr.write("  Without nvm, take the current 22.x from https://nodejs.org/.\n\n");
+  process.exit(1);
+}

package/scripts/reconcile-runs.mjs

@@ -50,7 +50,7 @@ const WORKSPACE_ROOT = argValue("--workspace-root") ?? envFrom(process.env, "CLE
 // The default is the CANONICAL agent alone. It used to name two of this firm's people, which shipped
 // their identities to every clone and told an installer nothing. Per-agent rosters are a
 // property of a deployment, so they are passed: --agents a,b,c
-const AGENTS = (argValue("--agents") ?? "clawdi").split(",").map((s) => s.trim()).filter(Boolean);
+const AGENTS = (argValue("--agents") ?? "localagent").split(",").map((s) => s.trim()).filter(Boolean);
 const APPLY = process.argv.includes("--apply");
 const QUIET_MS = (() => {
   const raw = argValue("--quiet-hours");

package/scripts/release-await-cut.mjs

@@ -52,7 +52,8 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 import { cutDecision, versionAtHead, tagsHere } from "./release-cut-decision.mjs";
 
 /**
- * Default bound: fifteen minutes at thirty-second steps. Both are arguments so an arm can drive the loop.
+ * Default bound: twenty-five minutes at thirty-second steps. Both are arguments so an arm can drive
+ * the loop.
  *
  * TWENTY-FIVE, RAISED FROM FIFTEEN (tracker issue 247), because this waits for the version pull
  * request's OWN CI and that is what it must clear. Measured over the first three cuts, the wait held
@@ -86,9 +87,10 @@ export const MIN_JOB_MARGIN_MS = 5 * 60 * 1000;
  * The bound, overridable for one caller only: the dry-run rehearsal.
  *
  * A rehearsal must exercise this path — a step nobody rehearses is a step that first runs for real on
- * the day it matters — but it has nothing to wait FOR, and fifteen minutes of polling to establish that
- * is fifteen minutes of a runner held for no answer. `awaitCut` asks before its first sleep, so a bound
- * of 0 does exactly one read and returns, which is the whole of what a rehearsal needs to prove.
+ * the day it matters — but it has nothing to wait FOR, and twenty-five minutes of polling to establish
+ * that is twenty-five minutes of a runner held for no answer. `awaitCut` asks before its first sleep,
+ * so a bound of 0 does exactly one read and returns, which is the whole of what a rehearsal needs to
+ * prove.
  *
  * REFUSES A VALUE IT CANNOT READ rather than falling back to the default. A typo here would silently
  * restore the full wait on the rehearsal, or — worse in the other direction — a real run would take a

package/scripts/release-version-pr-checks.mjs

@@ -194,7 +194,7 @@ export function surfacesFor(repo, sha, api = gh) {
 }
 
 /**
- * What each verdict costs the run — the half of tracker issue 208 that had the defect, so the half
+ * What each verdict costs the run — the half that had the defect, so the half
  * worth driving rather than reading.
  *
  * `0` is not "everything is fine"; it is "nothing here needs to stop the release". A parked run clears

package/scripts/release-version.mjs

@@ -7,8 +7,8 @@
 // because it is workspace-aware and this repository has four workspaces. It is, and it does not cover
 // the case that matters: `changeset version` versions the WORKSPACE packages and leaves the ROOT
 // package alone, and the root package is `clearotron` — the one thing a user installs and the only
-// version they will ever quote back to us. Measured on 3.0.1: a note against `prelim-driver` moved
-// prelim-driver 0.1.0 -> 0.1.1 and left `clearotron` at 0.1.0, with a changelog written per workspace
+// version they will ever quote back to us. Measured on 3.0.1: a note against `clearotron-driver` moved
+// clearotron-driver 0.1.0 -> 0.1.1 and left `clearotron` at 0.1.0, with a changelog written per workspace
 // and none at the root.
 //
 // So the four workspaces are a `fixed` group — one version number moves them together — and this script

package/scripts/render-check.mjs

@@ -37,7 +37,7 @@
 //
 // The demo is SPAWNED rather than reimplemented, and that is a safety property, not a shortcut: it
 // inherits bin/example.mjs's FORBIDDEN containment refusal, so a fixture pool can never resolve inside
-// /srv/trademark-archive or this environment's CLEAROTRON_REPORTS_DIR. 's rule is untouched — there is
+// /srv/trademark-archive or this environment's CLEAROTRON_REPORTS_DIR. That rule is untouched — there is
 // still no default pool; `--fixture-pool` is an explicit request that writes only to a fresh temp dir
 // and deletes it again unless `--keep`.
 //
@@ -64,7 +64,7 @@ import { execFileSync, spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { basename, extname } from "node:path";
 import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { tmpdir } from "node:os";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
 import { envFrom } from "../shared/env-aliases.mjs";   // — the name a reader is told to set is the one in force
@@ -160,7 +160,7 @@ const PROBE = `<script>
 // Reports from INSIDE the frame, which is the only place the truth lives: the parent cannot read a
 // cross-origin document.
 //
-// tracker issue 1155 — MEASURED ON A LAYOUT EVENT, NEVER ON A CLOCK, and the reason is not style.
+// MEASURED ON A LAYOUT EVENT, NEVER ON A CLOCK, and the reason is not style.
 //
 // This used to be \`setInterval(…, 400)\`, and it never fired once: the three assertions that depend on
 // this script reported "no-probe" for the whole life of the check.
@@ -198,7 +198,7 @@ const PROBE = `<script>
         winInnerH:window.innerHeight,
         trueContent:Math.ceil(b.getBoundingClientRect().bottom),
         SCROLLABLE:d.scrollHeight>window.innerHeight,
-        // tracker issue 485: every assertion in this file was about HEIGHT, and the report was 26px too WIDE.
+        // every assertion in this file was about HEIGHT, and the report was 26px too WIDE.
         hOverflowPx:d.scrollWidth-d.clientWidth,
         slackPx:window.innerHeight-Math.ceil(b.getBoundingClientRect().bottom)},'*');
     } catch (e) {
@@ -219,7 +219,7 @@ const PROBE = `<script>
 /**
  * A DELIBERATE 26px sideways overflow, injected into the report on `--plant-overflow`.
  *
- * 's acceptance has two halves and this is the one that matters more: nine green assertions prove
+ * That acceptance has two halves and this is the one that matters more: nine green assertions prove
  * nothing unless the same harness still REDDENS on a report that is actually broken. The old check
  * returned `stale-probe` for the sideways assertion in most runs, so it could not have caught this —
  * and a run of nine PASSes from an instrument that cannot fail is the exact false authority the whole
@@ -255,7 +255,7 @@ const SHELL = `<!doctype html><html><head><meta charset="utf-8"><title>render-ch
 <script>
 var f=document.getElementById('f'),st={heightMsgs:0},lastHeightAt=Date.now();
 window.addEventListener('message',function(e){var d=e.data;
-  // tracker issue 1155 — COUNT EVERY MESSAGE BEFORE THE SOURCE FILTER, and keep the count.
+  // COUNT EVERY MESSAGE BEFORE THE SOURCE FILTER, and keep the count.
   //
   // msgsAll minus probeMsgs minus heightMsgs is an accounting: it separates "nothing arrived from
   // inside the frame" from "something arrived and this handler discarded it", which a post-filter
@@ -447,12 +447,36 @@ async function measureAtZoom(zoom, deadlineMs = 90_000) {
   }
 }
 
+/**
+ * PURE. Did the in-frame probe post, and if not, which of the two causes does the evidence name?
+ *
+ * SEPARATED SO EVERY BRANCH CAN BE DRIVEN. The whole finding here is a check that reported three failed
+ * measurements about values it never read, and an arm that could only reach this through a real browser on
+ * a starved runner would be the same shape one level up: untestable except by luck.
+ *
+ * `heightMsgs` is the discriminator and was already being collected. It counts messages from the report's
+ * OWN height bridge, which travels the same postMessage path as the probe — so non-zero means the frame
+ * loaded, ran scripts and reached this shell, and a missing probe is then the probe's problem. Zero means
+ * nothing arrived from inside at all, and the probe is not the thing to look at.
+ */
+export function probeVerdict({ innerScrollbar, hOverflowPx, slackPx, heightMsgs = 0 } = {}) {
+  const missing = innerScrollbar === "no-probe" || hOverflowPx === "no-probe" || slackPx === null;
+  if (!missing) return { measured: true, cause: null, why: null };
+  return heightMsgs > 0
+    ? { measured: false, cause: "probe-only",
+        why: `${heightMsgs} height post(s) DID arrive, so the frame loaded and its scripts ran and reached `
+          + "this shell. The probe alone is missing — look at the probe, not at the report." }
+    : { measured: false, cause: "nothing-from-inside",
+        why: "No message of any kind arrived from inside the frame. The frame did not load, or its scripts "
+          + "did not run. The probe is not the thing to look at." };
+}
+
 async function main() {
   const { pool: POOL, built } = resolvePool();
   const runId = pickRun(POOL);
   mkdirSync(WORK, { recursive: true });
 
-  const { readReport } = await import(join(REPO, "driver", "portal-report.mjs"));
+  const { readReport } = await import(pathToFileURL(join(REPO, "driver", "portal-report.mjs")).href);
   const html = readReport(join(POOL, runId), { staff: true, poolRoot: POOL });
   // chrome.css carries 35KB of typography; without it the layout is not the one users see. What must be
   // true is that NO external stylesheet link survives into the measured document — either it was inlined,
@@ -473,12 +497,40 @@ async function main() {
     console.log("  Expect the sideways assertion to FAIL. A clean run here means the instrument is blind.\n");
   }
   let failures = 0;
+  // A COULD-NOT-LOOK IS NOT A FAILED MEASUREMENT (tracker issue 239). Counted apart from `failures`
+  // because the two mean different things to whoever reads the exit code: 1 says the layout is wrong,
+  // 2 says nothing was measured. Merging them is how a starved runner sends a reader to look at CSS.
+  let unmeasured = 0;
 
   for (const zoom of ZOOMS) {
     const measured = await measureAtZoom(zoom);
     if (!measured.ok) { console.log(`  zoom ${zoom}: FAILED — ${measured.why}`); failures++; continue; }
     const r = measured.state;
 
+    // ── THE THREE ASSERTIONS BELOW READ THE IN-FRAME PROBE, AND IT MAY NEVER HAVE POSTED ────────────
+    //
+    // `no-probe` and `null` are not measurements that disagreed with the expectation — they are the
+    // expectation never being tested. Rendering them as `FAIL … (got "no-probe")` is a check that could
+    // not look, reported as a check that looked and disliked what it saw, and it sends a reader to the
+    // report's CSS where there is nothing to find. Measured on a starved runner: three assertions failed
+    // on a branch whose diff was comments, a documentation line and a new test file.
+    //
+    // `heightMsgs` separates the two causes and was already being collected. It counts messages from the
+    // report's OWN height bridge, which travels the same postMessage path as the probe: non-zero means
+    // the frame loaded, ran scripts and reached the parent, so a missing probe is the probe's problem.
+    // Zero means nothing from inside arrived at all, and the probe is not the thing to look at.
+    const probe = probeVerdict(r);
+    if (!probe.measured) {
+      unmeasured++;
+      console.log(`  zoom ${zoom}:  (ready by ${r.readyBy}, heights ${r.heightsQuiet}, `
+        + `settled after ${r.settleTries} × 25ms, ${r.heightMsgs} height post(s), ${r.probeMsgs} probe post(s))`);
+      console.log(`    COULD NOT MEASURE — the in-frame probe never posted, so the report's own scrollbar,`);
+      console.log(`    its sideways overflow and the frame's slack were not read at zoom ${zoom}.`);
+      console.log(`    ${probe.why}`);
+      console.log(`    ── raw state: ${JSON.stringify(r)}`);
+      continue;
+    }
+
     const checks = [
       ["no border stealing from the frame's viewport", r.borderSteals === 0, r.borderSteals],
       ["the report has NO scrollbar of its own", r.innerScrollbar === false, r.innerScrollbar],
@@ -540,6 +592,13 @@ async function main() {
         + "clean run of this check is not evidence the report is clean.");
     process.exit(caught ? 0 : 1);
   }
+  if (unmeasured) {
+    // EXIT 2, THE HOUSE MEANING FOR COULD-NOT-LOOK. It still stops CI — nothing is waved through — but it
+    // does not claim the layout was measured and found wrong.
+    console.error(`\nrender-check: nothing was measured at ${unmeasured} zoom level(s) — the in-frame probe `
+      + `never posted. This is a failure to LOOK, not a finding about the report.`);
+    process.exit(2);
+  }
   console.log(failures ? `\nrender-check: ${failures} FAILED` : "\nrender-check: all checks passed");
   process.exit(failures ? 1 : 0);
 }

package/scripts/report-frame-check.mjs

@@ -22,7 +22,7 @@
 // Needs `google-chrome` (on the VM). Same mechanism as render-check.mjs: a page computes its verdict
 // and writes it into <title>, which --dump-dom hands back.
 
-import { chromeErrorPage } from "./headless-page.mjs";   // tracker issue 227 — a dumped DOM can be chrome's own error document
+import { chromeErrorPage } from "./headless-page.mjs";   // a dumped DOM can be chrome's own error document
 import { execFileSync } from "node:child_process";
 import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";

package/scripts/report-screenshot.mjs

@@ -19,7 +19,7 @@
 // receives, so it loads the brand webfonts the client's browser loads. Two scripts, two intents; do not
 // "fix" either to match the other.
 import { spawn } from "node:child_process";
-import { assertPageLoaded, cjkCharsIn, cjkVerdict, fontsCovering } from "./headless-page.mjs";   // tracker issue 227 — did chrome open the report, or its own error page?
+import { assertPageLoaded, cjkCharsIn, cjkVerdict, fontsCovering } from "./headless-page.mjs";   // did chrome open the report, or its own error page?
 import { mkdtempSync, writeFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, resolve } from "node:path";

package/scripts/revisit-render-check.mjs

@@ -59,7 +59,7 @@
 // MUST NOT run as a user with a virtual-memory ulimit (`ulimit -v`) — Chrome dumps core under one. Run it
 // as a user with `ulimit -v unlimited`. The dbus/UPower errors Chrome prints on a headless box are noise.
 
-import { navigateOrRefuse } from './headless-page.mjs'   // tracker issue 227 — Page.navigate returns an errorText, and nothing read it
+import { navigateOrRefuse } from './headless-page.mjs'   // Page.navigate returns an errorText, and nothing read it
 import { createServer } from 'node:http'
 import { readFileSync, existsSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs'
 import { join, extname, dirname } from 'node:path'

package/scripts/score.mjs

@@ -159,7 +159,7 @@ function findingsOf(runDir) {
       // Its finding rows carry no typed source at all: a `type` ("Active Business", "Famous Brand") that
       // is free model prose, and a `url`. The class is not missing by accident — the lane's register
       // component is a two-predicate count of the mark string and structurally cannot reach a register
-      // family (, ruled and closed). Everything it PUBLISHES comes off the common-law screen.
+      // family (ruled and closed). Everything it PUBLISHES comes off the common-law screen.
       //
       // So the class is asserted here rather than guessed from `type`, and it is asserted in the
       // direction that cannot overstate recall: a register gold entry is never satisfied by a knockout
@@ -496,7 +496,7 @@ function print(id, ref, run, s, delta, refPath) {
   console.log(deliveryLine(run));
   // — THE INSTRUMENT, BESIDE THE NUMBER. `--json` has carried `scorer_version` since this file
   // shipped; the human path did not, and the human path is the one whose numbers get pasted into an
-  // issue. 's body states 6/9 for a run that re-scores 5/2/2 today across two scorer changes
+  // issue. That body states 6/9 for a run that re-scores 5/2/2 today across two scorer changes
   // (`fd9938ce`, `212cdf73`), so every delta quoted from it crosses an unmarked boundary. A number a
   // reader can carry away must carry the instrument with it.
   //
@@ -805,11 +805,11 @@ function print(id, ref, run, s, delta, refPath) {
     // Now: `asked=` and `ran=` side by side, and — per the owner's ruling, flag rather than gate — a
     // LOUD marker when the ask was not met, carrying the cause on the same line so the reader is not
     // sent to the artifact to find out which switch was off (the rule for degradedCause, applied
-    // to the field beside it). An unrecorded verdict prints as unrecorded: a pre- artifact cannot
+    // to the field beside it). An unrecorded verdict prints as unrecorded: a pre-change artifact cannot
     // answer this and must not look like a lane that met its ask.
     // `(not stated)` and `(not established)` are DIFFERENT cells and the row keeps them apart, in the
     // vocabulary it already uses one column over: `not stated` = this artifact never answered the
-    // question (a pre- run), `not established` = it answered and the answer is that its own record
+    // question (a pre-change run), `not established` = it answered and the answer is that its own record
     // cannot settle what ran. Neither is `candidates`, and neither may read as a met ask.
     //
     // THE REASON DOES NOT GO IN THE CELL. A row is a row: the first cut interpolated the verdict's whole