clearotron 0.2.1 → 0.3.0-beta.0

package/scripts/freeze-example-run.mjs

@@ -47,7 +47,7 @@ import { join, dirname, relative, basename } from "node:path";
 import { createHash } from "node:crypto";
 import { driverDir } from "../shared/driver-dir.mjs";   //
 import { tmpdir } from "node:os";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -123,7 +123,7 @@ const FROZEN_DIRS = [
 //
 // research/ IS REQUIRED AND THE PROOF IS WHAT FOUND IT. publish/knockout.mjs
 // traces every finding citation back to the run's own research payload — `research/<mark>.md`, read from
-// the workspace (knockout.mjs:317) — and REFUSES the publish when a citation cannot be traced. The first
+// the workspace (publish/knockout.mjs:317) — and REFUSES the publish when a citation cannot be traced. The first
 // knockout freeze copied nine files, left research/ behind, and the republish proof threw:
 //
 //   knockout publish REFUSED: 2 finding citation(s) could not be traced to this run's own research
@@ -506,7 +506,7 @@ const poolFull = join(scratch, "full");
 const poolFrozen = join(scratch, "frozen");
 const meta = { runId, codename, customerKey, template };
 
-const { republishRun } = await import(join(REPO, "driver", "publish", "report-registry.mjs"));
+const { republishRun } = await import(pathToFileURL(join(REPO, "driver", "publish", "report-registry.mjs")).href);
 const publishInto = async (pool, dir) => {
   mkdirSync(pool, { recursive: true });
   return republishRun({ runId, meta, pool, poolUrl: "", runDir: dir, skipRegen: true });

package/scripts/headless-page.mjs

@@ -36,6 +36,12 @@ 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?
@@ -74,6 +80,25 @@ export function pageVerdict({ href = "", expected = "", marker = null, markerNam
         + "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); } };
@@ -103,8 +128,32 @@ export function pageVerdict({ href = "", expected = "", marker = null, markerNam
  * 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 } = {}) {
-  const href = await evaluate("location.href");
+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) {

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