clearotron 0.2.0 → 0.2.1

package/providers/oauth-mcp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "OAuth 2.1 MCP stdio bridge used by the engine's case-law gather stage (courtlistener / legaldatahunter).",

package/scripts/ai-page-render-check.mjs

@@ -41,6 +41,7 @@
 //                    per assistant, with a reason, and render no button. Zero buttons is the pass.
 //   wired-client     the hosted shape: address assistants live, stdio ones honestly absent.
 //   wired-staff      everything on offer at once — the widest bijection.
+import { navigateOrRefuse } from './headless-page.mjs'   // tracker issue 227 — 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, mkdtempSync, rmSync } from 'node:fs'
@@ -350,7 +351,7 @@ for (const state of Object.keys(STATES)) {
   mints = 0
   await cmd('Page.navigate', { url: 'about:blank' })
   await new Promise((r) => setTimeout(r, 150))
-  await cmd('Page.navigate', { url: `${origin}/portal/ai` })
+  await navigateOrRefuse(cmd, `${origin}/portal/ai`, { what: 'ai-page-render-check' })
   await new Promise((r) => setTimeout(r, 1400))
 
   const access = accessFor(STATES[state])

package/scripts/clearances-render-check.mjs

@@ -9,6 +9,7 @@
 //
 // Because nothing else in this repo can answer the question. portal-ui runs `node --test` with type
 // stripping and carries no jsdom and no React test renderer — Node cannot import a `.tsx` at all — so the
+import { navigateOrRefuse } from './headless-page.mjs'   // tracker issue 227 — Page.navigate returns an errorText, and nothing read it
 import { reapOnExit } from "../shared/reap-on-exit.mjs";   // — a detached group dies with this script
 // four source-text tests over Clearances.tsx can prove a string is in a file and nothing more. They
 // cannot see a width, an alignment, or a scrollbar, which is precisely what and are about.
@@ -318,7 +319,7 @@ const cmd = (method, params) => new Promise((r) => { const i = ++id; pending.set
 const value = async (expr) => (await cmd('Runtime.evaluate', { expression: expr, awaitPromise: true, returnByValue: true })).result?.result?.value ?? null
 
 const reload = async () => {
-  await cmd('Page.navigate', { url: `${origin}/portal/clearances` })
+  await navigateOrRefuse(cmd, `${origin}/portal/clearances`, { what: 'clearances-render-check' })
   await new Promise((r) => setTimeout(r, 1800))
 }
 

package/scripts/env-audit.mjs

@@ -244,6 +244,26 @@ export const SYSTEM_OWNED = new Set([
   // pushed back is right to have made this an explicit decision rather than an omission: they ARE read
   // by product code, and the only honest answers were a row or this list.
   "NO_COLOR", "FORCE_COLOR",
+  // ── THE GITHUB ACTIONS RUNTIME (tracker issue 213) ──────────────────────────────────────────────
+  //
+  // `CI` above is already here for exactly this reason; these two arrived with the release scripts and
+  // want the same answer. GitHub sets both INSIDE a workflow run — `GITHUB_OUTPUT` is the step-output
+  // file the runner creates, `GITHUB_REPOSITORY` the owner/name of the repository the run belongs to —
+  // and `scripts/release-await-cut.mjs`, `release-cut-decision.mjs` and `release-version-pr-checks.mjs`
+  // read them there.
+  //
+  // A row in `.env.example` for `GITHUB_OUTPUT` would tell an operator to set a variable GitHub sets
+  // for them, on a machine where it has no meaning at all. That makes the catalogue LESS true, not more
+  // — and `INSTALL.md §8` points a new user at that file as the register they must read. The ratchet
+  // was right that these are undocumented; the honest answer is the one `NO_COLOR` got, not a row.
+  //
+  // They surfaced only when the withheld `ops/` bucket was laid back over the public tree, so these
+  // arms had had no subject since the cut. Not a regression, and not a documentation gap.
+  //
+  // NARROW ON PURPOSE — these two names, not a `GITHUB_*` prefix. This list is closed so that a name
+  // genuinely ours cannot vanish from the audit by resembling a system name, and a prefix arm here
+  // would silently swallow any future `GITHUB_`-prefixed variable this product did come to own.
+  "GITHUB_OUTPUT", "GITHUB_REPOSITORY",
 ]);
 
 /** A file that ships and runs in production, as opposed to one that only ever runs a test. */

package/scripts/headless-page.mjs

@@ -0,0 +1,225 @@
+// 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:";
+
+/**
+ * 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." };
+  }
+  // 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 } = {}) {
+  const 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'   // tracker issue 227 — 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'
@@ -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/mint-reference-strip-backlog.mjs

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

package/scripts/release-await-cut.mjs

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

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

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

package/scripts/report-frame-check.mjs

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