clearotron 0.2.0 → 0.2.2

package/scripts/reconcile-runs.mjs

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

package/scripts/release-await-cut.mjs

@@ -52,21 +52,45 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 import { cutDecision, versionAtHead, tagsHere } from "./release-cut-decision.mjs";
 
 /**
- * Default bound: fifteen minutes at thirty-second steps. Both are arguments so an arm can drive the loop.
+ * Default bound: twenty-five minutes at thirty-second steps. Both are arguments so an arm can drive
+ * the loop.
  *
- * 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.
  *
  * A rehearsal must exercise this path — a step nobody rehearses is a step that first runs for real on
- * the day it matters — but it has nothing to wait FOR, and fifteen minutes of polling to establish that
- * is fifteen minutes of a runner held for no answer. `awaitCut` asks before its first sleep, so a bound
- * of 0 does exactly one read and returns, which is the whole of what a rehearsal needs to prove.
+ * the day it matters — but it has nothing to wait FOR, and twenty-five minutes of polling to establish
+ * that is twenty-five minutes of a runner held for no answer. `awaitCut` asks before its first sleep,
+ * so a bound of 0 does exactly one read and returns, which is the whole of what a rehearsal needs to
+ * prove.
  *
  * REFUSES A VALUE IT CANNOT READ rather than falling back to the default. A typo here would silently
  * restore the full wait on the rehearsal, or — worse in the other direction — a real run would take a
@@ -111,6 +135,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 +208,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 +225,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 +236,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++) {
@@ -170,7 +194,7 @@ export function surfacesFor(repo, sha, api = gh) {
 }
 
 /**
- * What each verdict costs the run — the half of tracker issue 208 that had the defect, so the half
+ * What each verdict costs the run — the half that had the defect, so the half
  * worth driving rather than reading.
  *
  * `0` is not "everything is fine"; it is "nothing here needs to stop the release". A parked run clears

package/scripts/release-version.mjs

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

package/scripts/render-check.mjs

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

package/scripts/report-frame-check.mjs

@@ -22,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";   // 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";   // 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'   // 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()

package/scripts/score.mjs

@@ -159,7 +159,7 @@ function findingsOf(runDir) {
       // Its finding rows carry no typed source at all: a `type` ("Active Business", "Famous Brand") that
       // is free model prose, and a `url`. The class is not missing by accident — the lane's register
       // component is a two-predicate count of the mark string and structurally cannot reach a register
-      // family (, ruled and closed). Everything it PUBLISHES comes off the common-law screen.
+      // family (ruled and closed). Everything it PUBLISHES comes off the common-law screen.
       //
       // So the class is asserted here rather than guessed from `type`, and it is asserted in the
       // direction that cannot overstate recall: a register gold entry is never satisfied by a knockout
@@ -496,7 +496,7 @@ function print(id, ref, run, s, delta, refPath) {
   console.log(deliveryLine(run));
   // — THE INSTRUMENT, BESIDE THE NUMBER. `--json` has carried `scorer_version` since this file
   // shipped; the human path did not, and the human path is the one whose numbers get pasted into an
-  // issue. 's body states 6/9 for a run that re-scores 5/2/2 today across two scorer changes
+  // issue. That body states 6/9 for a run that re-scores 5/2/2 today across two scorer changes
   // (`fd9938ce`, `212cdf73`), so every delta quoted from it crosses an unmarked boundary. A number a
   // reader can carry away must carry the instrument with it.
   //
@@ -646,6 +646,20 @@ function print(id, ref, run, s, delta, refPath) {
     for (const c of B.collisions)
       console.log(`    · ${c.owner}: reference "${c.entry}" is ${c.bucket}, surfaced "${c.noise}" is noise`);
   }
+  // ── SAME PROPRIETOR, DIFFERENT MARKS — REPORTED, NEVER SUPPRESSING (tracker issue 249) ───────────
+  //
+  // These used to print under the line above, which tells the reader not to read the recall numbers.
+  // One large filer anywhere in a matter therefore suppressed a whole run's measurement, and did: R2's
+  // real 88% → 63% recall movement went unquoted on the regression issue because `Novartis AG` held one
+  // withheld reference mark and one surfaced non-reference mark. Those two rows are both true.
+  //
+  // Kept visible because a reader may still want the pairing, and deliberately WITHOUT a verdict: this
+  // is an observation about the matter, not a fault in the scorer.
+  if (B.ownerEchoes?.length) {
+    console.log(`\n  same-proprietor rows (${B.ownerEchoes.length}) — NOT a collision, and the recall numbers above stand:`);
+    for (const c of B.ownerEchoes)
+      console.log(`    · ${c.owner}: reference "${c.entry}" is ${c.bucket}, surfaced "${c.noise}" is noise (different marks)`);
+  }
 
   for (const [name, label] of [["withheld", "WITHHELD — in this run's own records, absent from its findings"],
                                ["lost", "LOST — never retrieved"],
@@ -791,11 +805,11 @@ function print(id, ref, run, s, delta, refPath) {
     // Now: `asked=` and `ran=` side by side, and — per the owner's ruling, flag rather than gate — a
     // LOUD marker when the ask was not met, carrying the cause on the same line so the reader is not
     // sent to the artifact to find out which switch was off (the rule for degradedCause, applied
-    // to the field beside it). An unrecorded verdict prints as unrecorded: a pre- artifact cannot
+    // to the field beside it). An unrecorded verdict prints as unrecorded: a pre-change artifact cannot
     // answer this and must not look like a lane that met its ask.
     // `(not stated)` and `(not established)` are DIFFERENT cells and the row keeps them apart, in the
     // vocabulary it already uses one column over: `not stated` = this artifact never answered the
-    // question (a pre- run), `not established` = it answered and the answer is that its own record
+    // question (a pre-change run), `not established` = it answered and the answer is that its own record
     // cannot settle what ran. Neither is `candidates`, and neither may read as a met ask.
     //
     // THE REASON DOES NOT GO IN THE CELL. A row is a row: the first cut interpolated the verdict's whole