clearotron 0.2.0 → 0.3.0-beta.0

package/mcp-server/server.mjs

@@ -54,6 +54,13 @@ import { accountRun, accountTrace, accountTimeline, accountFinding, accountFindi
   accountWhatIfPlan, accountWhatIfQueued, accountWhatIfResult, CLIENT_FAILURE_NOTE as clientFailureNote } from "./lib/audit-view.mjs";
 import { scrubMarkdown, scrubBody, scrubFrontMatter, scrubCards } from "./lib/scrub.mjs";
 import { evidenceRecords, searchLog, coverageStatement } from "./lib/evidence.mjs";
+// The knockout lane's projections. Every audit tool below branches on `isKnockoutRun` because the
+// clearance projections read artifacts this product does not write, and returned empty rather than saying
+// so (tracker issue 275).
+import {
+  isKnockoutRun, knockoutDoc, knockoutArtifacts, knockoutArtifactPath, knockoutFindings,
+  knockoutEvidence, knockoutSearches, knockoutCoverage, traceKnockout, notProducedOnThisProduct,
+} from "./lib/knockout.mjs";
 import { instructionsFor } from "./lib/instructions.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
 import { BRAND } from "../shared/brand.mjs";   // — the operator name a client is told to expect, from the tenant seam
@@ -82,6 +89,18 @@ function mustRun(runId) {
 function artifactPath(run, name) {
   const { P, runDir } = run;
   if (name === "status.json") return join(runDir, "status.json");
+  // THE KNOCKOUT TABLE IS TERMINAL ON A KNOCKOUT, and both halves of that matter (tracker issue 275).
+  //
+  // Resolving FIRST is what fixes `report`: a knockout's report.md is written to the POOL and never into
+  // the run dir, so the clearance table returned the run dir's own `report` slot — a path that does not
+  // exist — and the tool answered `exists: false` about a file sitting on disk.
+  //
+  // Not FALLING THROUGH is the other half, and it was caught by an arm rather than by design. With a
+  // fall-through, `read_artifact narrative` on a knockout resolves against the clearance table, finds the
+  // slot, and returns `exists: false` — reporting a document this product never writes as a missing one.
+  // That is the defect this issue is about, reappearing one layer down. Returning null instead makes the
+  // tool refuse the name and name the artifacts this run actually has.
+  if (isKnockoutRun(run)) return knockoutArtifactPath(run, name);
   if (name === "run.jsonl" || name === "telemetry/run.jsonl") return driverDir(runDir, "run.jsonl");
   if (REGISTER_AXES.includes(name)) return P.registerUnit(name);
   // validate the axis against the known set — never let a "registerUnit:../../x" escape the run-dir
@@ -93,6 +112,10 @@ function artifactPath(run, name) {
 }
 
 function listArtifacts(run) {
+  // The error message a caller sees when a name does not resolve is built from this list, so on a knockout
+  // it has to name the knockout's own artifacts — otherwise the tool refuses a name and then suggests
+  // eleven documents this product does not write.
+  if (isKnockoutRun(run)) return knockoutArtifacts(run).filter((a) => a.exists).map(({ name, file }) => ({ name, file }));
   const { P } = run; const out = [];
   for (const [k, v] of Object.entries(P)) { if (k === "runDir" || typeof v === "function") continue; if (existsSync(v)) out.push({ name: k, file: basename(v) }); }
   for (const ax of REGISTER_AXES) { const p = P.registerUnit(ax); if (existsSync(p)) out.push({ name: `registerUnit:${ax}`, file: basename(p) }); }
@@ -227,6 +250,28 @@ const tools = {
   get_run({ runId }) {
     const run = mustRun(runId);
     const { stages, failover } = getStages(run.runDir);
+    // THE LANE DECIDES THE ARTIFACT LIST. Appending REGISTER_AXES unconditionally is what manufactured
+    // eleven `exists: false` rows on a product that writes none of those documents — a wall of false
+    // negatives, which a reader is entitled to read as a run with nothing on disk.
+    if (isKnockoutRun(run)) {
+      const doc = knockoutDoc(run);
+      const negatives = knockoutFindings(run, { kind: "negatives" }).items;
+      return {
+        run: runSummary(run),
+        product: "knockout",
+        stages, failover,
+        artifacts: knockoutArtifacts(run),
+        coverageSummary: {
+          // No ledger EXISTS on this lane, and saying so as a fact beats reporting it as a missing file.
+          coverageLedgerPresent: false,
+          coverageLedgerNote: "A Knockout search keeps no coverage ledger; get_search_coverage answers "
+            + "from the run's own per-mark record instead.",
+          complete: Boolean(doc),
+          findings: knockoutFindings(run).items.length,
+          negativeResults: negatives.length,
+        },
+      };
+    }
     return {
       run: runSummary(run),
       stages, failover,
@@ -249,6 +294,18 @@ const tools = {
   },
   list_findings({ runId, kind, sourceLayer, group }) {
     const run = mustRun(runId);
+    if (isKnockoutRun(run)) {
+      // `group` is the clearance report's on-field/off-field/out-of-scope curation. A knockout report has
+      // no such sectioning, so the honest answer names that rather than filtering to nothing.
+      if (group) {
+        return {
+          _note: BRIEFING_NOTE, kind: "cards", group, items: [],
+          ...notProducedOnThisProduct("on-field/off-field/out-of-scope card groups",
+            "Call list_findings without `group` for this run's findings, each with its band."),
+        };
+      }
+      return { _note: BRIEFING_NOTE, ...knockoutFindings(run, { kind, sourceLayer }) };
+    }
     if (group) { const cards = loadCards(run.P); return { _note: BRIEFING_NOTE, kind: "cards", group, items: cards.cards.filter((c) => c.group === group), note: cards.note }; }
     return { _note: BRIEFING_NOTE, ...filterFindings(run.P, { kind, sourceLayer }) };
   },
@@ -256,17 +313,20 @@ const tools = {
   // Data, not narrative: no BRIEFING_NOTE rides on these. The projections — and the reasoning about what
   // is evidence and what is method — live in lib/evidence.mjs; nothing is decided here.
   list_evidence({ runId, layer }) {
-    const out = evidenceRecords(mustRun(runId));
+    const run = mustRun(runId);
+    const out = isKnockoutRun(run) ? knockoutEvidence(run) : evidenceRecords(run);
     return layer ? { ...out, records: out.records.filter((r) => r.layer === layer) } : out;
   },
   list_searches({ runId, outcome }) {
-    const out = searchLog(mustRun(runId));
+    const run = mustRun(runId);
+    const out = isKnockoutRun(run) ? knockoutSearches(run) : searchLog(run);
     if (!outcome) return out;
     const searches = out.searches.filter((s) => s.outcome === outcome);
     return { ...out, count: searches.length, searches, totalCount: out.count };
   },
   get_search_coverage({ runId }) {
-    return coverageStatement(mustRun(runId));
+    const run = mustRun(runId);
+    return isKnockoutRun(run) ? knockoutCoverage(run) : coverageStatement(run);
   },
   get_finding({ runId, id }) {
     const run = mustRun(runId);
@@ -275,7 +335,12 @@ const tools = {
     return f;
   },
   trace({ runId, target, depth, shallow }) {
-    return trace(mustRun(runId), target, { depth: depth ?? 2, shallow: shallow === true });
+    const run = mustRun(runId);
+    // The clearance trace's target table is built from STAGE_ORDER, the register axes and the clearance
+    // findings spine, so on a knockout it resolved nothing at all — including "verdict" — and its error
+    // enumerated fifteen stages, none of them from this lane.
+    if (isKnockoutRun(run)) return traceKnockout(run, target, readEvents(run.runDir));
+    return trace(run, target, { depth: depth ?? 2, shallow: shallow === true });
   },
   get_telemetry({ runId, stage, axis }) {
     const run = mustRun(runId);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clearotron",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0-beta.0",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0-beta.0",
   "license": "AGPL-3.0-only",
   "description": "The unified trademark portal UI. One address, one login: who you are decides what you see. Built as a static bundle, served by driver/portal-service.mjs — the browser never reaches profile-service or recipe-service.",
   "engines": {

package/providers/oauth-mcp-bridge/CHANGELOG.md

@@ -1,5 +1,15 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.0-beta.0
+
+## 0.2.1
+
+## 0.2.1-beta.2
+
+## 0.2.1-beta.1
+
+## 0.2.1-beta.0
+
 ## 0.2.0
 
 ## 0.1.12

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

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.2.0",
+  "version": "0.3.0-beta.0",
   "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/drain-preflight.mjs

@@ -29,7 +29,7 @@
 
 import { spawnSync } from "node:child_process";
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { join, dirname } from "node:path";
 import { homedir, userInfo } from "node:os";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
@@ -244,7 +244,7 @@ export async function preflight({ home = homedir(), root = ROOT } = {}) {
   const unitPath = join(root, "driver", "systemd", "prelim-driver.path");
   const unitText = existsSync(unitPath) ? readFileSync(unitPath, "utf8") : null;
 
-  const { config } = await import(join(root, "driver", "driver.config.mjs"));
+  const { config } = await import(pathToFileURL(join(root, "driver", "driver.config.mjs")).href);
   const queueDirs = config.queueDirs ?? [];
   const watched = unitText == null ? null : watchedQueueDirs(unitText, home);
 

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/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

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

package/scripts/home-render-check.mjs

@@ -18,6 +18,7 @@
 // Exits non-zero on the first state that fails to draw, scrolls sideways, or renders a pip count that
 // contradicts the run it is drawn from.
 
+import { navigateOrRefuse } from './headless-page.mjs'   // 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`)