clearotron 0.2.0 → 0.2.2

package/scripts/headless-page.mjs

@@ -0,0 +1,274 @@
+// 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
+//
+// headless-page.mjs — did the browser open the page we asked for, or something of its own?
+//
+// (and, since tracker issue 227 criteria 3-4, whether this box can draw what that page says)
+//
+// ── WHY THIS EXISTS (tracker issue 227) ─────────────────────────────────────────────────────────────
+//
+// Seven scripts drive headless Chrome and none of them asked. They cannot ask the obvious way: Chrome is
+// launched with the file URL as a COMMAND-LINE ARGUMENT, so there is no navigation call whose response
+// could be checked. The page simply becomes whatever Chrome ends up showing.
+//
+// What it ends up showing, when the file cannot be read, is Chrome's own interstitial — and that page
+// has an `<h1>`. `report-screenshot.mjs` asserted `document.querySelector("h1")` and nothing else, so it
+// photographed `ERR_ACCESS_DENIED`, wrote 38 KB of grey error page over the README's example frame, and
+// exited 0. Measured: 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.
+//
+// Six of the seven were saved only by an unrelated content assertion that happened to be specific enough.
+// That is luck, and it is per-script: the next assertion somebody writes to be tolerant removes it.
+//
+// ── THE DISCRIMINATOR IS THE ADDRESS, NOT THE CONTENT ───────────────────────────────────────────────
+//
+// `location.href` reads `chrome-error://chromewebdata/` on the interstitial and the requested `file://`
+// URL on a real load. It is the one thing the error page cannot fake, because it is not part of the
+// document — an `<h1>`, a `<title>`, a body class are all things an arbitrary HTML page can carry, and an
+// error page IS an arbitrary HTML page.
+//
+// A MARKER IS STILL REQUIRED, because the address only proves Chrome opened the file. A file that exists,
+// is readable, and is not the artefact this script is about would pass the address check — an empty
+// render, a stale page, a half-written document. So the caller names one thing that only its own artefact
+// carries, and the verdict says which of the two failed.
+
+import { execFileSync } from "node:child_process";
+
+/** Chrome's own error pages live under this scheme. Nothing a real document is served from does. */
+export const CHROME_ERROR_SCHEME = "chrome-error:";
+/** What Chrome shows before it has navigated. Not a document, and not a wrong one. */
+export const START_PAGE = "about:blank";
+/** How long `assertPageLoaded` will wait for the browser to leave its start page. */
+export const NAVIGATION_GRACE_MS = 5000;
+/** How often it asks, inside that grace. */
+export const NAVIGATION_POLL_MS = 100;
+
+/**
+ * PURE. Given what the page says about itself, is it the document we asked for?
+ *
+ * Separated from the evaluation so every branch can be driven — the whole finding here is a check that
+ * returned a verdict about a page it never identified, and an arm that could only exercise this through
+ * a real browser would be the same shape one level up.
+ *
+ * @param {string}  href       `location.href` as the page reports it
+ * @param {string}  expected   the `file://` URL the caller asked Chrome to open
+ * @param {boolean|null} marker  did the caller's own content marker resolve? `null` means not asked
+ * @param {string}  markerName  what the marker is, for the message
+ */
+export function pageVerdict({ href = "", expected = "", marker = null, markerName = "the page's own content", errorText = null } = {}) {
+  const said = String(href ?? "");
+  // ── THE TWO SHAPES IN THIS REPOSITORY ───────────────────────────────────────────────────────────
+  //
+  // Four of these scripts call `Page.navigate`, which RETURNS an `errorText` on failure and which none
+  // of them read. Three launch Chrome with the URL as an argument and have no response at all. One
+  // verdict serves both: `errorText` is checked when the caller has one, and the address is checked
+  // either way — because a failed `Page.navigate` can also leave the page at `about:blank`, which no
+  // error text describes and which a content check reads as an empty document rather than a failure.
+  if (errorText) {
+    return { ok: false, kind: "navigate-failed",
+      why: `chrome refused to navigate to ${expected}: ${errorText}. The page is whatever it was showing `
+        + "before, so anything measured now is about the wrong document." };
+  }
+  if (!said) {
+    return { ok: false, kind: "silent",
+      why: "the page reported no address at all, so nothing here identifies what was captured. A "
+        + "screenshot taken now certifies an unknown document." };
+  }
+  if (said.startsWith(CHROME_ERROR_SCHEME)) {
+    return { ok: false, kind: "chrome-error",
+      why: `chrome could not open ${expected} and is showing ITS OWN error page (${said}). Whatever was `
+        + "captured is Chrome's interstitial, not the artefact — and that page carries an `<h1>`, a "
+        + "`<title>` and a body, so a content check alone reads it as a success." };
+  }
+  // ── THE BROWSER'S START PAGE IS NOT A WRONG DOCUMENT (tracker issue 273) ────────────────────────
+  //
+  // `about:blank` is what Chrome shows before it has navigated anywhere. Reaching the check below, it
+  // compares unequal to the expected URL and was reported as `wrong-document` — "a redirect, a stale tab
+  // or a second page target" — which is a finding about a page. It is not one. Nothing was ever loaded,
+  // so nothing about the target document has been measured either way.
+  //
+  // This mattered because it is what a LOADED BOX produces: three of these scripts launch Chrome with the
+  // URL as a command-line argument and cannot wait for a navigation event, so under load the address is
+  // read before the browser has moved. A real defect and a slow browser then arrived as the same message,
+  // and the arms that exist to catch a wrong page were the ones that fired.
+  if (said === START_PAGE || said.startsWith(`${START_PAGE}?`) || said.startsWith(`${START_PAGE}#`)) {
+    return { ok: false, kind: "not-navigated",
+      why: `chrome is on its start page (${said}) and never reached ${expected}. Nothing about that `
+        + "document has been measured, so this is not a finding about the page. TWO THINGS LOOK LIKE "
+        + "THIS and the address cannot tell them apart: a navigation that failed without saying so, and "
+        + "one that had not happened yet. That is why the caller waits before asking — a verdict of this "
+        + "kind means it waited and the browser never left the start page." };
+  }
+  // NORMALISED ON BOTH SIDES. Chrome resolves and percent-encodes a `file://` argument, so a raw string
+  // comparison fails on a path with a space and reports "the wrong document" about the right one.
+  const norm = (u) => { try { return new URL(u).href; } catch { return String(u); } };
+  if (expected && norm(said) !== norm(expected)) {
+    return { ok: false, kind: "wrong-document",
+      why: `chrome is showing ${said}, and this run asked for ${expected}. A redirect, a stale tab or a `
+        + "second page target — whichever it is, the frame is not of the document this script names." };
+  }
+  if (marker === false) {
+    return { ok: false, kind: "not-the-artefact",
+      why: `chrome opened ${said} and ${markerName} is not in it. The address is right and the CONTENT is `
+        + "not what this script is about — an empty render, a stale file, or a document half written." };
+  }
+  if (marker === null) {
+    return { ok: false, kind: "unmarked",
+      why: "no content marker was asked for, so this run proves only that a file opened. Name one thing "
+        + "the artefact carries and nothing else does — an address alone cannot tell an artefact from any "
+        + "other readable file." };
+  }
+  return { ok: true, kind: "loaded", why: `${said} is open and ${markerName} is in it.` };
+}
+
+/**
+ * Ask the live page, then judge. `evaluate` runs an expression and returns its value.
+ *
+ * The caller passes its own CDP `Runtime.evaluate` wrapper, because each of these scripts built its own
+ * handshake before this file existed and rewriting seven of them to share one is a bigger change than the
+ * defect warrants. What they must share is the QUESTION.
+ */
+export async function assertPageLoaded(evaluate, { expected, marker = null, markerName = "the page's own content", what = "this page", errorText = null,
+  graceMs = NAVIGATION_GRACE_MS, pollMs = NAVIGATION_POLL_MS,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = () => Date.now() } = {}) {
+  // ── WAIT FOR THE BROWSER TO LEAVE ITS START PAGE, THEN JUDGE (tracker issue 273) ─────────────────
+  //
+  // Three of these scripts launch Chrome with the URL as an argument and get no response to wait on, so
+  // the first read of `location.href` can land before the browser has moved. On an idle box it never
+  // does; under a full parallel suite it did, repeatedly, and the arms reported the start page as a
+  // wrong document.
+  //
+  // BOUNDED, AND THE BOUND IS THE POINT. This waits for the browser to become ready — it does not wait
+  // for the page to become correct. If the address is anything other than the start page it is judged
+  // immediately, so a genuinely wrong document still fails on the first read and fails as fast as it did
+  // before. Only the "nothing has happened yet" case costs time, and only up to the grace.
+  //
+  // When the grace runs out the verdict is `not-navigated`, which is a could-not-look and says so.
+  // Deadline arithmetic is the caller's to drive: `sleep` and `now` are injected so the exhausted path
+  // can be exercised without a browser and without waiting.
+  let href = await evaluate("location.href");
+  if (String(href ?? "") === START_PAGE) {
+    const until = now() + graceMs;
+    while (String(href ?? "") === START_PAGE && now() < until) {
+      await sleep(pollMs);
+      href = await evaluate("location.href");
+    }
+  }
+  const found = marker == null ? null : Boolean(await evaluate(`Boolean(${marker})`));
+  const verdict = pageVerdict({ href, expected, marker: found, markerName, errorText });
+  if (!verdict.ok) {
+    console.error(`${what}: ${verdict.why}`);
+    return { ...verdict, href };
+  }
+  return { ...verdict, href };
+}
+
+/**
+ * Navigate, and refuse if chrome says it could not.
+ *
+ * `Page.navigate` RETURNS `{ frameId, loaderId, errorText }`, and every caller in this repository threw
+ * the result away. So a portal that was not listening, a DNS failure, a refused connection — each left
+ * the page showing whatever it had before, and the assertions that followed measured the previous page
+ * or an empty one. Six of these scripts were saved from reporting a pass by an unrelated content
+ * assertion that happened to be specific enough; that is luck, per script, and the next person to write
+ * a more tolerant assertion removes it.
+ *
+ * THROWS rather than returning a verdict, because there is nothing sensible for a caller to do with a
+ * navigation that did not happen, and the alternative — a boolean somebody forgets to read — is the
+ * shape this fixes.
+ */
+export async function navigateOrRefuse(cmd, url, { what = "this page" } = {}) {
+  const r = await cmd("Page.navigate", { url });
+  const errorText = r?.result?.errorText ?? r?.errorText ?? null;
+  if (errorText) {
+    const verdict = pageVerdict({ errorText, expected: url });
+    throw new Error(`${what}: ${verdict.why}`);
+  }
+  return r;
+}
+
+/**
+ * Does this dumped DOM belong to chrome's own error page?
+ *
+ * For the callers that use `--dump-dom` rather than CDP: there is no `location.href` to ask, only the
+ * bytes chrome printed. Chrome's interstitial is recognisable by the error-code element it always
+ * carries and by its `neterror`/`chrome-error` markers — none of which a document we authored has.
+ *
+ * DELIBERATELY NARROW. A page that merely CONTAINS the words "error" or "denied" is not this; a report
+ * about a refused search would say both. What is matched is chrome's own furniture.
+ */
+export function chromeErrorPage(dom = "") {
+  const t = String(dom);
+  return /chrome-error:\/\//.test(t)
+    || /id="?main-frame-error"?/.test(t)
+    || /jstcache=|<body[^>]*\bid="?neterror"?/.test(t);
+}
+
+// ── CAN THIS BOX DRAW WHAT THE PAGE SAYS? (tracker issue 227, criteria 3 and 4) ──────────────────────
+//
+// The default demo product is a full-country search, and its report carries the mark's native-script
+// renderings — ベンクリ, ベンコリ, ヴェンコリ. They are LOAD-BEARING: the verdict sentence reads "A live
+// Japanese class 9 registration reading ベンクリ covers measuring and testing instruments".
+//
+// On a box with no CJK-capable font those render as `□□□`, twice in the captured frame, and nothing
+// says so. The script's own comment already names this class of failure — "the failure is a screenshot
+// in the wrong typeface that nobody notices until it is in the README" — and it waits for
+// `document.fonts.ready` to prevent it. That solved the TYPEFACE problem and left the WRITING-SYSTEM one,
+// in the same script, with the same failure mode.
+//
+// ASKED OF FONTCONFIG, not of the page. `document.fonts` reports the faces a page ASKED for and got; it
+// says nothing about whether the glyphs exist. `fc-list :lang=ja` answers the question actually being
+// asked — can anything on this box draw these characters — and it is the same source a reader would
+// check by hand.
+
+/** Han, Hiragana, Katakana, Hangul — the ranges a Latin-only font set leaves as tofu. */
+const CJK = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uac00-\ud7af]/gu;
+
+/** How many characters in this text need a CJK-capable font. */
+export function cjkCharsIn(text = "") {
+  return (String(text).match(CJK) ?? []).length;
+}
+
+/**
+ * PURE. Given what the page needs and what the box has, is the frame trustworthy?
+ *
+ * `covering` is the number of fonts fontconfig reports for the writing system — `null` means the caller
+ * could not ask, which is NOT zero: a box where `fc-list` is missing is a box this cannot judge, and
+ * reporting it as "no coverage" would refuse a machine that may be fine.
+ */
+export function cjkVerdict({ cjkChars = 0, covering = 0, sample = "" } = {}) {
+  if (!cjkChars) return { ok: true, kind: "no-cjk", why: "the page carries no CJK characters." };
+  if (covering === null) {
+    return { ok: true, kind: "unknown-coverage",
+      why: `the page carries ${cjkChars} CJK character(s) and this run could not ask fontconfig what can `
+        + "draw them. Not a refusal — a box that cannot be asked is not a box known to be missing fonts — "
+        + "but the frame is unverified on that point." };
+  }
+  if (covering > 0) {
+    return { ok: true, kind: "covered",
+      why: `the page carries ${cjkChars} CJK character(s) and ${covering} installed font(s) cover them.` };
+  }
+  return { ok: false, kind: "tofu",
+    why: `the page carries ${cjkChars} CJK character(s)${sample ? ` (${sample})` : ""} and NO installed `
+      + "font can draw them — `fc-list :lang=ja` reports none. They render as empty boxes, and the frame "
+      + "would go out with the mark's own native-script rendering missing. Install a CJK font (on Debian "
+      + "and Ubuntu: `fonts-noto-cjk`), or set XDG_DATA_HOME to a directory holding one." };
+}
+
+/**
+ * How many installed fonts cover a writing system, per fontconfig — or `null` if we could not ask.
+ *
+ * `null` IS THE POINT. `fc-list` missing, or a fontconfig that errors, is a box this cannot judge, and
+ * collapsing that into 0 would refuse a machine that may be perfectly able to draw the page. The caller
+ * treats the two differently, which is the whole reason this returns three values and not a number.
+ */
+export function fontsCovering(lang = "ja", { run } = {}) {
+  try {
+    const out = run
+      ? run(["-f", "%{file}\\n", `:lang=${lang}`])
+      : execFileSync("fc-list", ["-f", "%{file}\\n", `:lang=${lang}`], { encoding: "utf8", timeout: 20_000 });
+    return String(out).split("\n").map((l) => l.trim()).filter(Boolean).length;
+  } catch {
+    return null;
+  }
+}

package/scripts/home-render-check.mjs

@@ -18,6 +18,7 @@
 // Exits non-zero on the first state that fails to draw, scrolls sideways, or renders a pip count that
 // contradicts the run it is drawn from.
 
+import { navigateOrRefuse } from './headless-page.mjs'   // Page.navigate returns an errorText, and nothing read it
 import { createServer } from 'node:http'
 import { reapOnExit } from "../shared/reap-on-exit.mjs";   // — a detached group dies with this script
 import { readFileSync, existsSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs'
@@ -47,7 +48,7 @@ const ago = (m) => new Date(now - m * 60_000).toISOString()
 const run = (o) => ({
   runId: o.runId, account: o.account ?? 'zephyr', title: o.mark, markName: o.mark,
   projectKey: o.projectKey ?? null, projectName: o.projectName ?? null,
-  // `product` is meta.searchLevel off the wire, and it holds a PRODUCT ID. The fixtures said `prelim`
+  // `product` is meta.searchLevel off the wire, and it holds a PRODUCT ID. The fixtures said `clearotron`
   // — a RETIRED slug — for every state, so this check could not see that depthLabel had no case for any
   // current product and the chip rendered EMPTY on every run the build creates. A fixture that speaks a
   // vocabulary the build no longer produces certifies the bug.
@@ -377,7 +378,7 @@ for (const [name, spec] of Object.entries(STATES)) {
     }
 
     await evalIn(`window.__renderCheckDoc = 1`)
-    await cmd('Page.navigate', { url: `${origin}/portal/home` })
+    await navigateOrRefuse(cmd, `${origin}/portal/home`, { what: 'home-render-check' })
     if (!await homeReady('navigate')) continue
     await evalIn(`localStorage.setItem('cordillera-theme', ${JSON.stringify(theme)})`)
     await evalIn(`window.__renderCheckDoc = 1`)

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, 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, 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 +260,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 +507,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 +663,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 +737,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

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-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/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 ?? "?"); }
 
 /**

package/scripts/portal-lifecycle-check.mjs

@@ -221,7 +221,7 @@ const HELPERS = `
     return false;
   };
   const txt = () => document.body.innerText;
-  // tracker issue 1809 — A MISS THROWS, NAMING WHAT IT MISSED. Same defect as composer-render-check.mjs, in this
+  // A MISS THROWS, NAMING WHAT IT MISSED. Same defect as composer-render-check.mjs, in this
   // file's own copy of the helper: six sites below dereference the result immediately, so a button that
   // had not painted arrived as "Cannot read properties of undefined (reading 'click')".
   // maybeByText keeps the undefined return for the one site where absence is the thing being measured.
@@ -315,7 +315,7 @@ ${HELPERS}
   out.topbarHeading = (document.querySelector('.topbar h1') || {}).innerText || null;
 
   await goto('/portal/new');
-  // tracker issue 1809 — THIS WAIT WAS IDENTITY-DEPENDENT AND SILENTLY DEAD FOR ONE OF THE THREE. "Brand owner" is
+  // THIS WAIT WAS IDENTITY-DEPENDENT AND SILENTLY DEAD FOR ONE OF THE THREE. "Brand owner" is
   // the rail switcher's eyebrow (AppShell.tsx), which a SINGLE-OWNER client never gets — that identity
   // reads its owner in the Account corner instead. So this timed out on every client run, and because
   // settle returned false without objecting it degraded into an 8-second sleep. Waits on the context
@@ -395,7 +395,7 @@ ${HELPERS}
   out.bringBackOnProject = allByText('button', /^Bring back$/).length >= 1;
   out.projectArchiveOnRow = allByText('button', /^Archive$/).length >= 1;
   findByText('button', /New project/).click();
-  // "Project name" since tracker issue 1958's copy pass, which shortened the label from "What is this
+  // "Project name" since the copy pass that shortened the label from "What is this
   // project called?". A driver that opens the real screen is the one thing that notices a rename like
   // this, and it noticed: the whole lifecycle failed here rather than anywhere near the cause.
   await mustSettle(() => /Project name/.test(txt()), 8000, 'the project name prompt never appeared');