clearotron 0.2.0 → 0.3.0-beta.0

package/scripts/live-surface-check.mjs

@@ -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, 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";                          //
@@ -234,14 +236,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;
     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"],
         { 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 +260,73 @@ 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;
       }
     } 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, 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, 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 +503,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 +659,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.

package/scripts/mint-reference-strip-backlog.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// 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
+//
+// Mints `driver/test/fixtures/reference-strip-backlog.json` — the per-file floor under the repair of
+// the sentences the reference strip broke (tracker issue 185).
+//
+// Run it AFTER repairing lines, never to make a red arm green: the arm it feeds refuses any count that
+// went UP, so re-minting is how a repair is recorded, not how a regression is absorbed.
+//
+//     node scripts/mint-reference-strip-backlog.mjs [--check]
+//
+// `--check` re-derives and exits non-zero if the committed table disagrees with the tree, which is what
+// CI runs. Without it, the table is rewritten.
+import { readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SIGNATURES, censusOf } from "../driver/reference-strip-signatures.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const TABLE = join(ROOT, "driver/test/fixtures/reference-strip-backlog.json");
+
+const tracked = execFileSync("git", ["-C", ROOT, "ls-files"], { encoding: "utf8", maxBuffer: 1 << 28 })
+  .split("\n").filter(Boolean);
+const minted = censusOf(ROOT, tracked, (f) => readFileSync(join(ROOT, f), "utf8"));
+
+if (process.argv.includes("--check")) {
+  const have = JSON.parse(readFileSync(TABLE, "utf8"));
+  const a = JSON.stringify(have.files), b = JSON.stringify(minted.files);
+  if (a !== b || have.total !== minted.total) {
+    console.error("reference-strip backlog is STALE against the tree.");
+    console.error(`  committed total ${have.total}, tree has ${minted.total}`);
+    console.error("  re-mint with: node scripts/mint-reference-strip-backlog.mjs");
+    process.exit(1);
+  }
+  console.log(`reference-strip backlog: current — ${minted.total} line(s) still to repair`);
+} else {
+  writeFileSync(TABLE, JSON.stringify({ signatures: SIGNATURES.map((s) => s.name), ...minted }, null, 2) + "\n");
+  console.log(`minted ${TABLE}: ${minted.total} line(s) across ${Object.keys(minted.files).length} file(s)`);
+}

package/scripts/release-await-cut.mjs

@@ -54,11 +54,33 @@ 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.
  *
- * FIFTEEN, and the job's `timeout-minutes` is 30 to contain it — a budget smaller than its own longest
- * step cancels the job at the moment it was about to publish, and a cancelled run reads as neither a
- * success nor a failure to anybody scanning the list.
+ * 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
+ * 552 s, 622 s and 686 s against a 900 s budget — rising every time, and the thing it waits on is the
+ * offline suite, which grows on purpose every time anybody adds an arm. The margin was one slow queue.
+ *
+ * AND THE FAILURE IS SILENT, which is why the margin has to be generous rather than adequate. Running
+ * out is a quiet exit 0 by design — an ordinary "nothing merged" must not read as a fault — so the
+ * first time this budget is exceeded, the release is simply stranded behind a green tick. There is no
+ * red to notice. The cron floor underneath would eventually publish it, which makes the silence worse
+ * rather than better: the version ships late, from a different run, with nobody told why.
+ *
+ * THE JOB'S `timeout-minutes` MUST EXCEED THIS, with room for the checkout and install above it. A
+ * budget smaller than its own longest step cancels the job at the moment it was about to publish, and a
+ * cancelled run reads as neither a success nor a failure to anybody scanning the list. The comment here
+ * used to say the job was capped at 30 while the job actually said 25 — harmless at a 15 minute wait,
+ * and exactly the sort of thing that stops being harmless when somebody raises one number and believes
+ * a sentence about the other. `MIN_JOB_MARGIN_MS` is what an arm holds the pair to now.
+ */
+export const WAIT_MS = 25 * 60 * 1000;
+
+/**
+ * How far the job's budget must exceed the wait's: enough for the checkout, the install and the pack
+ * that surround it. Five minutes, which is generous against the ~90 s those actually take, because the
+ * cost of being wrong in this direction is a cancelled publish and the cost of being wrong in the other
+ * is a runner held slightly longer.
  */
-export const WAIT_MS = 15 * 60 * 1000;
+export const MIN_JOB_MARGIN_MS = 5 * 60 * 1000;
 
 /**
  * The bound, overridable for one caller only: the dry-run rehearsal.
@@ -111,6 +133,70 @@ export async function awaitCut({ refresh, read, sleep, waitMs = WAIT_MS, stepMs
 
 const git = (args) => execFileSync("git", args, { encoding: "utf8" });
 
+/**
+ * One read of `main`: the version it carries, whether that version is tagged, and WHICH COMMIT said so.
+ *
+ * THE COMMIT IS READ IN THE SAME PASS AS THE VERSION, and that is the whole point of this function
+ * existing rather than being three calls at the call site (tracker issue 238). The job below used to
+ * check out `main` by name after this loop returned, so a commit landing in between — one that moves no
+ * version, an instrument fix with no note — was packed and published under a number whose changelog
+ * never described it. Nothing downstream could see it: the tip check compares VERSIONS, and the version
+ * had not moved. Naming the commit here is what makes the two ends of the pipeline talk about the same
+ * tree.
+ *
+ * No fetch happens between the two reads, so they cannot straddle one.
+ *
+ * EVERY READER IS AN ARGUMENT, and that is not decoration. An arm that injected only `run` still asked
+ * real git for the version and the tags, so it answered differently on a box where `main` is tagged than
+ * on a runner where the checkout has neither `origin/main` nor tags — green here, red there, for reasons
+ * that have nothing to do with what it was checking. This file's own suite header warns about exactly
+ * that shape, and one of these arms was written into it anyway.
+ */
+export function versionBumpCommit({ version, ref = "origin/main", run = git, versionAt = versionAtHead, maxWalk = 100 }) {
+  const shas = run(["rev-list", "--first-parent", `-n${maxWalk}`, ref]).trim().split("\n").filter(Boolean);
+  let answer = null;
+  let sawTheChange = false;
+  for (const sha of shas) {
+    if (versionAt({ ref: sha }) !== version) { sawTheChange = true; break; }
+    // KEEP WALKING PAST THE FIRST MATCH. Every commit landing after the bump and before this read also
+    // carries the version — that is precisely the class of commit this exists to leave out — so the
+    // answer is the OLDEST consecutive one, not the newest.
+    answer = sha;
+  }
+  // A WALK THAT NEVER SAW THE VERSION CHANGE HAS NOT FOUND THE BUMP; it has run out of road. The oldest
+  // commit it happened to reach carries the version by coincidence of the window, and publishing that
+  // would ship a tree from before the release. An absence is a finding.
+  return sawTheChange ? answer : null;
+}
+
+export function readMain({ run = git, versionAt = versionAtHead, tags = tagsHere, decide = cutDecision } = {}) {
+  const sha = run(["rev-parse", "origin/main"]).trim();
+  // CHECKED BEFORE THE VERSION IS READ, so a checkout with no `origin/main` refuses here rather than
+  // going on to answer confidently about a tree it could not name. `git rev-parse` prints the name back
+  // when it cannot resolve it, so the failure looks like a value rather than like an error.
+  if (!/^[0-9a-f]{40}$/.test(sha)) {
+    throw new Error(`release-await-cut: \`git rev-parse origin/main\` answered "${sha.slice(0, 80)}", which is `
+      + "not a commit. The publish below checks out what this reports, so a name it cannot resolve must "
+      + "refuse here rather than resolve to something else there.");
+  }
+  const d = decide({ version: versionAt({ ref: "origin/main" }), tags: tags() });
+  // NOT THE TIP. `origin/main` is where the branch points in this pass, and a commit that landed after
+  // the version bump carries the same version — so the tip check downstream, which compares versions,
+  // passes on exactly the commit that made the tarball disagree with its changelog. The answer is the
+  // commit that MOVED the version, which is the version pull request's merge.
+  //
+  // Only asked when there is something to publish. On the ordinary "nothing merged" answer the tip is
+  // what a reader wants recorded, and there is no version whose bump could be looked for.
+  if (!d.cut) return { ...d, sha, tip: sha };
+  const bump = versionBumpCommit({ version: d.version, run, versionAt });
+  if (!bump) {
+    throw new Error(`release-await-cut: main carries ${d.version} but no commit in the last 100 could be `
+      + "found that moved it there. The publish below checks out what this reports, and reporting the "
+      + "branch tip instead would publish whatever else has landed since.");
+  }
+  return { ...d, sha: bump, tip: sha };
+}
+
 function main() {
   const out = process.env.GITHUB_OUTPUT;
   const started = Date.now();
@@ -120,7 +206,7 @@ function main() {
     // tags never arrived answers "no tag" about every version there has ever been. That is the one wrong
     // answer this pipeline cannot afford, so it is refreshed on every pass rather than once at checkout.
     refresh: async () => { git(["fetch", "--no-tags", "--prune", "origin", "+refs/heads/main:refs/remotes/origin/main"]); git(["fetch", "--tags", "--force", "origin"]); },
-    read: () => cutDecision({ version: versionAtHead({ ref: "origin/main" }), tags: tagsHere() }),
+    read: () => readMain(),
     sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
     now: () => Date.now() - started,
   }).catch((e) => {
@@ -137,7 +223,7 @@ function main() {
       + `(${String(e?.message ?? e).slice(0, 200)}). This is a failure to LOOK, not a finding that `
       + "nothing was cut — nothing downstream may treat it as one.");
     process.exitCode = 2;
-    if (out) appendFileSync(out, "cut=false\nversion=\nlooked=false\n");
+    if (out) appendFileSync(out, "cut=false\nversion=\nsha=\nlooked=false\n");
   }).then((r) => {
     if (!r) return;
     const secs = Math.round(r.waitedMs / 1000);
@@ -148,7 +234,9 @@ function main() {
     // `looked` SEPARATES the two negatives above: a loop that ran and found nothing merged, from one
     // that could not read main at all. The publish job below requires `cut=true`, so neither publishes —
     // but a reader deciding whether a release went missing needs to know which of the two happened.
-    if (out) appendFileSync(out, `cut=${r.cut ? "true" : "false"}\nversion=${r.version}\nlooked=true\n`);
+    // `sha` IS WRITTEN ON BOTH ANSWERS, not only on a cut. It records which commit this loop's verdict is
+    // about, so a run that published nothing can still be read back against the tree it looked at.
+    if (out) appendFileSync(out, `cut=${r.cut ? "true" : "false"}\nversion=${r.version}\nsha=${r.sha ?? ""}\nlooked=true\n`);
   });
 }
 

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

@@ -131,7 +131,31 @@ export function checksVerdict({ checkRuns = [], workflowRuns = [], policy = null
  * incident, and this is the difference between a false red on the version job — cheap, loud, retried by
  * the next push — and a red that means what it says.
  */
-export async function waitForChecks({ read, sleep, attempts = 32, everyMs = 15000 } = {}) {
+/**
+ * This file's own window: 32 attempts at 15 s, or eight minutes.
+ *
+ * NAMED SO AN ARM CAN COUPLE THE JOB'S BUDGET TO IT (tracker issue 247). The `version` job's
+ * `timeout-minutes` has to contain THIS wait, and the arm that claimed to check that compared the job
+ * against `release-await-cut.mjs`'s constant instead — a different wait, in a different job, which this
+ * job never runs. It held by luck and would have failed the moment that unrelated number was raised.
+ */
+export const CHECK_ATTEMPTS = 32;
+export const CHECK_EVERY_MS = 15_000;
+export const CHECKS_WINDOW_MS = CHECK_ATTEMPTS * CHECK_EVERY_MS;
+
+/**
+ * What the `version` job spends around this wait: checkout, install, the changesets action that cuts the
+ * pull request, and the cut/awaited steps either side of it.
+ *
+ * This margin belongs to THIS file for the same reason the window does. `release-await-cut.mjs` exports a
+ * margin of its own with the same name-shape and a different subject — the checkout and install around the
+ * `awaited` job's wait. Coupling the version job's budget to that one repeats the very defect this issue
+ * closes, one size smaller: raising the other job's margin would move this job's requirement, about a job
+ * whose behaviour had not changed. Two jobs, two waits, two margins, and no number shared between them.
+ */
+export const CHECKS_JOB_MARGIN_MS = 4 * 60 * 1000;
+
+export async function waitForChecks({ read, sleep, attempts = CHECK_ATTEMPTS, everyMs = CHECK_EVERY_MS } = {}) {
   if (typeof read !== "function") throw new Error("release-version-pr-checks: waitForChecks needs a read()");
   let seen = null;
   for (let i = 1; i <= attempts; i++) {

package/scripts/render-check.mjs

@@ -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
@@ -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,6 +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 { execFileSync } from "node:child_process";
 import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -63,6 +64,17 @@ function main() {
       "--virtual-time-budget=8000", "--dump-dom", `file://${join(work, "verify.html")}`,
     ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 120000 });
 
+    // ── IS THIS OUR PAGE, OR CHROME'S ERROR PAGE? (tracker issue 227) ───────────────────────────────
+    //
+    // `--dump-dom` prints whatever chrome ended up showing, and a file it could not read produces the
+    // interstitial — which has a `<title>` of its own. This was saved from reporting a pass only by the
+    // marker below being specific: the title has to parse as JSON with a `kept` array. That is luck, not
+    // a check, and the next person to loosen the parse removes it. Said out loud instead.
+    if (chromeErrorPage(out)) {
+      console.log(`FAILED — chrome could not open the page and dumped its own error document instead. `
+        + `Nothing below is about the report.`);
+      process.exit(1);
+    }
     const m = /<title>(.*?)<\/title>/s.exec(out);
     if (!m || m[1] === "pending") { console.log("FAILED — the page never reported"); process.exit(1); }
     const kept = JSON.parse(m[1]).kept;

package/scripts/report-screenshot.mjs

@@ -19,6 +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 { mkdtempSync, writeFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, resolve } from "node:path";
@@ -29,6 +30,9 @@ const OUT = resolve(process.argv[3] ?? join(ROOT, "docs", "assets", "example-rep
 const WIDTH = 1280, HEIGHT = 1040;
 // The frame starts here rather than at the top of the document — see the scroll block below.
 const ANCHOR = process.argv.includes("--anchor") ? process.argv[process.argv.indexOf("--anchor") + 1] : "h1";
+// WHAT ONLY A REPORT CARRIES. `h1` is the ANCHOR — where to start the frame — and it is on every HTML
+// page including Chrome's error interstitial, so it cannot also be the proof that this IS a report.
+const MARKER = process.argv.includes("--marker") ? process.argv[process.argv.indexOf("--marker") + 1] : "[data-run-id]";
 
 const src = process.argv[2];
 if (!src) { console.error("usage: node scripts/report-screenshot.mjs <report.html> [out.png]"); process.exit(2); }
@@ -69,6 +73,34 @@ const sessionId = sess.sessionId;
 const cmd = (method, params = {}) => new Promise((r) => { const n = ++id; pending.set(n, r); ws.send(JSON.stringify({ id: n, sessionId, method, params })); });
 
 await cmd("Page.enable");
+
+// ── IS THIS THE REPORT, OR CHROME'S OWN ERROR PAGE? (tracker issue 227) ──────────────────────────────
+//
+// Chrome is launched with the file URL as an ARGUMENT, so there is no navigation response to check and
+// nothing here ever asked. When the file could not be read, Chrome showed `ERR_ACCESS_DENIED` — a page
+// with an `<h1>` — the anchor below resolved against it, the clip was taken, and this exited 0 having
+// written 38 KB of grey error page over the README's example frame. The successful run and the failed
+// one differed in the log by an anchor offset and a font count, neither of which was asserted on.
+//
+// `existsSync` above does not cover it: a file that EXISTS and cannot be READ passes that check and
+// fails in Chrome. So does a file that is readable and is not a report.
+//
+// THE MARKER IS THE RUN ID, not a tag. `h1` is what the error page has; `[data-run-id]` is what only a
+// rendered report has, and naming it in the log is what makes the success line say what it certified
+// rather than "an h1 was found".
+const evaluate = async (expression) => {
+  const r = await cmd("Runtime.evaluate", { expression, returnByValue: true });
+  return r?.result?.result?.value;
+};
+const loaded = await assertPageLoaded(evaluate, {
+  expected: `file://${page}`,
+  marker: `document.querySelector(${JSON.stringify(MARKER)})`,
+  markerName: `a report element (${MARKER})`,
+  what: "report-screenshot",
+});
+if (!loaded.ok) { chrome.kill(); process.exit(1); }
+const runId = await evaluate(`(document.querySelector(${JSON.stringify(MARKER)})?.getAttribute("data-run-id") ?? "")`);
+
 // The fonts are the point of allowing the network at all, so wait for them rather than for a fixed
 // sleep: a timer long enough on this box is a timer too short on a slower one, and the failure is a
 // screenshot in the wrong typeface that nobody notices until it is in the README.
@@ -91,11 +123,39 @@ if (typeof top !== "number") {
   console.error(`report-screenshot: no element matched ${JSON.stringify(ANCHOR)} — nothing to anchor the frame to.`);
   chrome.kill(); process.exit(1);
 }
+// ── CAN THIS BOX DRAW WHAT THE PAGE SAYS? (tracker issue 227) ───────────────────────────────────────
+//
+// The default demo product's report carries the mark's native-script renderings — ベンクリ, ベンコリ,
+// ヴェンコリ — and they are load-bearing: the verdict sentence reads "A live Japanese class 9
+// registration reading ベンクリ covers measuring and testing instruments". With no CJK-capable font
+// those render as empty boxes, twice in the captured frame, and nothing said so.
+//
+// The wait for `document.fonts.ready` above was written against exactly this class — "the failure is a
+// screenshot in the wrong typeface that nobody notices until it is in the README" — and solved the
+// TYPEFACE half. This is the WRITING-SYSTEM half, in the same script.
+//
+// REFUSES rather than warns. This writes an image that goes into the README by hand; a warning on a
+// terminal nobody is reading when the file is already written is the shape that produced the defect
+// above it. `--allow-tofu` is there for a reader who genuinely wants the frame anyway and has been told
+// what is in it.
+const pageText = await evaluate("document.body ? document.body.innerText : ''");
+const cjkChars = cjkCharsIn(pageText);
+const glyphs = cjkVerdict({ cjkChars, covering: fontsCovering("ja"),
+  sample: (String(pageText).match(/[\u3040-\u30ff\u4e00-\u9fff]{2,8}/u) ?? [])[0] ?? "" });
+if (!glyphs.ok && !process.argv.includes("--allow-tofu")) {
+  console.error(`report-screenshot: ${glyphs.why}`);
+  console.error("  Pass --allow-tofu to capture it anyway, knowing the frame is missing those glyphs.");
+  chrome.kill(); process.exit(1);
+}
+if (!glyphs.ok) console.error(`report-screenshot: WARNING — ${glyphs.why} Capturing anyway (--allow-tofu).`);
+
 const y = Math.max(top - 56, 0);   // a little air above the title, so the page does not read as cropped
 const shot = await cmd("Page.captureScreenshot", { format: "png", captureBeyondViewport: true,
   clip: { x: 0, y, width: WIDTH, height: HEIGHT, scale: 1 } });
 if (!shot?.result?.data) { console.error(`report-screenshot: chrome returned no image. ${JSON.stringify(shot).slice(0, 300)}`); chrome.kill(); process.exit(1); }
 writeFileSync(OUT, Buffer.from(shot.result.data, "base64"));
-const loaded = await cmd("Runtime.evaluate", { expression: "document.fonts.size + ':' + [...document.fonts].filter(f=>f.status==='loaded').length", returnByValue: true });
+const fonts = await cmd("Runtime.evaluate", { expression: "document.fonts.size + ':' + [...document.fonts].filter(f=>f.status==='loaded').length", returnByValue: true });
 chrome.kill();
-console.log(`report-screenshot: wrote ${OUT} (${WIDTH}x${HEIGHT}, anchor ${JSON.stringify(ANCHOR)} at y=${Math.round(y)}, fonts ${loaded?.result?.result?.value ?? "?"})`);
+// NAMES WHAT IT CERTIFIED. "an h1 was found" is true of the error page this used to photograph; the
+// run id is read out of the document and is the thing a reader can check against the report they meant.
+console.log(`report-screenshot: wrote ${OUT} of run ${runId || "(no run id in the page)"} (${WIDTH}x${HEIGHT}, anchor ${JSON.stringify(ANCHOR)} at y=${Math.round(y)}, fonts ${fonts?.result?.result?.value ?? "?"}, ${glyphs.kind})`);

package/scripts/revisit-render-check.mjs

@@ -59,6 +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 { createServer } from 'node:http'
 import { readFileSync, existsSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs'
 import { join, extname, dirname } from 'node:path'
@@ -284,7 +285,7 @@ const record = {}
 
 // The shell, once. Everything after this is client-side.
 epoch = 'boot'
-await cmd('Page.navigate', { url: `${origin}/portal/home` })
+await navigateOrRefuse(cmd, `${origin}/portal/home`, { what: 'revisit-render-check' })
 if (!(await settle())) say(false, 'the shell never went quiet within 12s — it is still requesting')
 const bootPath = await where()
 say(bootPath === '/portal/home', `the shell loaded on /portal/home (got ${bootPath})`)
@@ -375,7 +376,7 @@ await twice('clearances', () => clickNav('Clearances'), '/portal/clearances')
 // URL and the SECOND is the Back button, which is the revisit a reader actually performs and the one that
 // runs AppShell's popstate listener rather than its click funnel.
 epoch = 'result:1'
-await cmd('Page.navigate', { url: `${origin}/portal/result/${RUN_ID}` })
+await navigateOrRefuse(cmd, `${origin}/portal/result/${RUN_ID}`, { what: 'revisit-render-check' })
 const rq1 = await settle()
 const rp1 = await where()
 const rt1 = await screenText()