clearotron 0.2.1 → 0.2.3

package/scripts/env-classify.mjs

@@ -38,7 +38,7 @@ import "../shared/env-local.mjs";   // — FIRST, and it became REQUIRED here:
                                      // the capture evaluates before the CLEAROTRON_* translation lands. A
                                      // call in this file's BODY would run too late. The guard named the
                                      // file, the module it reaches, and the fix.
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, readdirSync, writeFileSync, existsSync } from "node:fs";
 // — the product-owned-names rule, shared rather than a regex in this file.
 import { makeIsProductOwned, partitionByOwnership, droppedShape, FILTER_DECLARATION }
   from "../shared/product-owned-names.mjs";
@@ -60,7 +60,7 @@ export function namesInEnvFile(text) {
 }
 /** Every house or vendor variable MENTIONED in a script — the shape the config repo's bin/ writes. */
 export function namesMentioned(text) {
-  return [...text.matchAll(/\b(?:PRELIM|CLEAROTRON|PORTAL|TRADEMARK_MCP|CLIENT_MCP|CLIENT_ACCESS|PROFILE|RECIPE|MOCK)_[A-Z0-9_]+/g)].map((m) => m[0]);
+  return [...text.matchAll(/\b(?:CLEAROTRON|CLEAROTRON|PORTAL|TRADEMARK_MCP|CLIENT_MCP|CLIENT_ACCESS|PROFILE|RECIPE|MOCK)_[A-Z0-9_]+/g)].map((m) => m[0]);
 }
 
 /**
@@ -73,7 +73,7 @@ export function namesMentioned(text) {
 // — NO EXECUTABLE LINE NAMES A SPECIFIC ACCOUNT'S HOME. These paths are per-box facts and this
 // script ships. They arrive as COMMAND-LINE FLAGS, not environment variables.
 //
-// The first fix used four new house-prefixed variables instead, and 's ratchet refused them —
+// The first fix used four new house-prefixed variables instead, and the ratchet refused them —
 // correctly: adding four names to the configuration surface is precisely wrong in the tool built to
 // shrink it, and a maintainer's per-invocation path is an argument. The names are deliberately not
 // written out even here: `namesRead` scans comments too, and a variable that exists only in prose is
@@ -83,7 +83,74 @@ const flag = (name) => {
   return i > 0 && process.argv[i + 1] && !process.argv[i + 1].startsWith("--") ? process.argv[i + 1] : "";
 };
 
-export function gather({ root = ROOT, prodList = read(PROD) } = {}) {
+/**
+ * A SHIPPED FILE THIS SCRIPT CANNOT WORK WITHOUT — read it, or say so and stop.
+ *
+ * `read()` answers "" on ENOENT, which is right where a file is legitimately absent and wrong where its
+ * absence means the tree is broken. Every caller here is the second kind: they are files the product
+ * always ships, and an empty read of one silently empties a source that feeds `everSet` — and a name
+ * nothing is recorded as setting is a name a configuration cleanup removes.
+ *
+ * One helper rather than a check at each site, so a source added later cannot get this wrong by being
+ * written the obvious way: reading through it is how you read.
+ */
+function mustRead(root, rel, why) {
+  const p = join(root, rel);
+  // READ FIRST AND KEEP THE REASON. Going through `read()` and then asking `existsSync` would separate
+  // absent from present only by accident of which case that second call can see: `read()` swallows
+  // EVERY error, so a file that EXISTS and cannot be read — a permission, a directory standing where a
+  // file belongs, a truncated mount — comes back "" and passes straight through as though it held
+  // nothing. Same consequence as absence and the same silence, one test narrower.
+  try {
+    return readFileSync(p, "utf8");
+  } catch (e) {
+    const tail = `${why} Reading it as empty would put every name it holds on the deletion population.`;
+    if (e.code !== "ENOENT")
+      throw new Error(`env-classify: ${p} exists and could not be read (${e.code}). ${tail}`);
+    throw new Error(`env-classify: ${p} is absent. ${tail} Its absence is this script failing to look, `
+      + "not a finding about the tree.");
+  }
+}
+
+/**
+ * Every variable name a WORKFLOW sets, across all of them.
+ *
+ * This source used to read `.github/workflows/ci.yml` and nothing else, which made the release workflow
+ * invisible to it. `CLEAROTRON_CUT_REF` and `CLEAROTRON_RELEASE_WAIT_MS` are set there and nowhere else,
+ * so both reported `everSet: []` and both landed on the deletion population — two names a reviewer would
+ * have been asked to remove because the one file that sets them was not being read. A name being set by
+ * the release surface rather than the test surface says nothing about whether it is a knob.
+ *
+ * AN ABSENT DIRECTORY THROWS instead of returning nothing. `read()` answers "" on ENOENT, so the old
+ * single-file read degraded silently: a renamed or moved ci.yml would have emptied this source, reported
+ * every workflow-set name as never set, and nothing in the output would have said the look had failed.
+ */
+function workflowNames(root) {
+  const dir = join(root, ".github/workflows");
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => /\.ya?ml$/.test(f)).sort();
+  } catch (e) {
+    throw new Error(`env-classify: cannot read ${dir} (${e.code}). That is this script failing to look, `
+      + "not a tree with no workflows, and an empty CI source silently widens the deletion population.");
+  }
+  if (!files.length)
+    throw new Error(`env-classify: ${dir} holds no .yml files. Every workflow-set name would read as `
+      + "never set, which is the shape this source exists to prevent.");
+  return files.flatMap((f) => [...read(join(dir, f)).matchAll(/^\s*([A-Z][A-Z0-9_]*):/gm)].map((m) => m[1]));
+}
+
+export function gather({ root = ROOT, prodList = null } = {}) {
+  // THE PRODUCTION HALF CAN BE ABSENT, AND ABSENT MUST NOT READ AS "PRODUCTION SETS NOTHING". `read()`
+  // answers "" on ENOENT, so a missing list made all 72 production-set names report `everSet: []` — and
+  // `tuning` with an empty `everSet` IS the deletion population. That is the same failure the CI source
+  // carried, one source over: the file is withheld from the public tree, so on a public checkout this
+  // silently classified production's own configuration as unused. `prodRead` records whether the look
+  // happened, so a caller can tell a real answer from no answer. A list passed in is its caller's claim
+  // to make, and counts as read.
+  const prodGiven = prodList !== null;
+  const prodText = prodGiven ? prodList : read(PROD);
+  const prodRead = prodGiven || existsSync(PROD);
   const set = (xs) => new Set(xs.filter(Boolean));
   const tracked = (glob) => git("ls-files", "--", glob).split("\n").filter(Boolean);
   const sudoRead = (p) => { try { return execFileSync("sudo", ["-n", "cat", p], { encoding: "utf8" }); } catch { return ""; } };
@@ -91,14 +158,16 @@ export function gather({ root = ROOT, prodList = read(PROD) } = {}) {
   const config = flag("config-repo") ? [flag("config-repo")] : [];
   return {
     // COMMITTED, not gathered: the production read needs privilege a reviewer does not have.
-    prod: set(prodList.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"))),
+    prod: set(prodText.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"))),
+    prodRead,
     test: set(flag("test-env") ? namesInEnvFile(sudoRead(flag("test-env"))) : []),
     config: set(config.flatMap((r) => {
       let files = []; try { files = execFileSync("sudo", ["-n", "find", r, "-type", "f", "-not", "-path", "*/.git/*"], { encoding: "utf8" }).split("\n").filter(Boolean); } catch { return []; }
       return files.flatMap((f) => { const t = sudoRead(f); return [...namesInEnvFile(t), ...namesMentioned(t)]; });
     })),
-    ci: set([...read(join(root, ".github/workflows/ci.yml")).matchAll(/^\s*([A-Z][A-Z0-9_]*):/gm)].map((m) => m[1])),
-    e2e: set(["scripts/e2e.mjs", "scripts/test-run.mjs"].flatMap((f) => namesMentioned(read(join(root, f))))),
+    ci: set(workflowNames(root)),
+    e2e: set(["scripts/e2e.mjs", "scripts/test-run.mjs"]
+      .flatMap((f) => namesMentioned(mustRead(root, f, "It is the end-to-end surface, and the names it sets are set nowhere else.")))),
     // A DESCRIPTION, never a setting. Kept apart so `everSet` cannot be satisfied by documentation.
     docs: set([".env.example", ".env.dev.example", ".env.prod.example"]
       .flatMap((f) => [...read(join(root, f)).matchAll(/^#?\s*([A-Z][A-Z0-9_]*)=/gm)].map((m) => m[1]))),
@@ -108,8 +177,15 @@ export function gather({ root = ROOT, prodList = read(PROD) } = {}) {
 
 /** The setup population: what the wizard WRITES, expanded through the alias table. */
 export function setupNames(root = ROOT) {
-  const onboard = read(join(root, "bin/onboard.mjs"));
-  const cfg = read(join(root, "driver/driver.config.mjs"));
+  // THE WORST ONE TO LOSE, and the reason it is read through `mustRead`. This is the population that
+  // separates "the wizard writes this at install" from "nobody sets this anywhere". Empty, every setup
+  // name falls through the shape tests to `tuning` — the residual bucket — and `tuning` with no recorded
+  // set-site IS the deletion population. So a missing wizard would not merely lose a source; it would
+  // propose the whole install surface for removal, with nothing in the output saying the file was gone.
+  const onboard = mustRead(root, "bin/onboard.mjs",
+    "It is the install wizard, and what it writes is the whole setup population.");
+  const cfg = mustRead(root, "driver/driver.config.mjs",
+    "It carries the table whose credential fields name the rest of that population.");
   const seed = new Set();
   for (const m of onboard.matchAll(/candidate\.([A-Z][A-Z0-9_]*)\s*=/g)) seed.add(m[1]);
   for (const m of onboard.matchAll(/candidate\["([A-Z][A-Z0-9_]*)"\]\s*=/g)) seed.add(m[1]);
@@ -245,12 +321,45 @@ export function defaultAtReadSite(name, root = ROOT) {
 
 /** The whole classification, pure over its inputs so a test drives it without a box. */
 export function classify({ catalogue, sources, setup = setupNames(), readSites = defaultAtReadSite,
-  deploymentNames = DEPLOYMENT_NAMES } = {}) {
-  // ONE NAMED OVERRIDE, and it is listed rather than folded into a pattern so that it can be argued
-  // with. `CLEAROTRON_AGENT_WHATSAPP` matches no deployment shape and is not a knob: production sets it to
-  // a contact map, so it is a notification DESTINATION. Established from the SHAPE of the value, never
-  // its content. A pattern wide enough to catch it would have swept in real knobs.
-  const OVERRIDES = { CLEAROTRON_AGENT_WHATSAPP: "deployment" };
+  deploymentNames = DEPLOYMENT_NAMES, declared = new Map() } = {}) {
+  // NAMED OVERRIDES, listed rather than folded into a pattern so that each can be argued with.
+  //
+  // `CLEAROTRON_AGENT_WHATSAPP` matches no deployment shape and is not a knob: production sets it to a
+  // contact map, so it is a notification DESTINATION. Established from the SHAPE of the value, never its
+  // content. A pattern wide enough to catch it would have swept in real knobs.
+  //
+  // The other two are the same fact about the same thing, and they are here because the register already
+  // declares them `deployment` while this classifier — which keys on the NAME — filed them as `tuning`.
+  // That disagreement is not cosmetic: tuning names with no recorded set-site are the population this
+  // script walks for deletion candidates, and both are destinations a deployment may legitimately leave
+  // unset. A one-word mismatch would have put a notification address on a list of names to remove.
+  //
+  //   · CLEAROTRON_REQUESTER_WHATSAPP     — the map of requester → number. A destination, like the agent
+  //                                          map above, and the reason that one is here applies verbatim.
+  //   · CLEAROTRON_WHATSAPP_OPERATOR_COPY — whether the operator keeps a copy. It reads as a knob and is
+  //                                          not one: it decides WHETHER a second destination is used, so
+  //                                          changing it changes who is told, never what a run concludes.
+  //
+  // `CLEAROTRON_JX_SUBCLASS_DB` is the fourth, and it is the plainest reading of `deployment` on this
+  // list: the catalogue row says it names WHERE THE SUBCLASS TABLE LIVES, and that what the table says
+  // belongs to the build. Where input lives, with the conclusion a run reaches unchanged — the
+  // definition, almost word for word. The classifier filed it `tuning` because no shape in this file
+  // matches the spelling, and `tuning` is the residual bucket, so the row was not an opinion about the
+  // name so much as the absence of one.
+  //
+  // It is here rather than in a widened pattern because the name has no default and the lane REFUSES
+  // when it is unset. That makes it the worst possible member of a deletion population: removing it
+  // does not retire an unused knob, it takes out the only way the lane can be pointed at a table at all.
+  //
+  // The first three were found in review, not by the classifier, because nothing reconciled the
+  // catalogue's declared effect against this table and the two could disagree indefinitely. That
+  // comparison now runs as an arm, and this entry is the first thing it produced.
+  const OVERRIDES = {
+    CLEAROTRON_AGENT_WHATSAPP: "deployment",
+    CLEAROTRON_REQUESTER_WHATSAPP: "deployment",
+    CLEAROTRON_WHATSAPP_OPERATOR_COPY: "deployment",
+    CLEAROTRON_JX_SUBCLASS_DB: "deployment",
+  };
 
   const cls = (name) => OVERRIDES[name] ?? (setup.has(name) ? "setup"
     : VENDOR_RE.test(name) ? "vendor-credential"
@@ -261,7 +370,11 @@ export function classify({ catalogue, sources, setup = setupNames(), readSites =
 
   const rows = catalogue.map((name) => {
     const setIn = ["prod", "test", "config", "ci", "e2e"].filter((k) => sources[k]?.has(name));
-    return { name, class: cls(name), everSet: setIn, documented: Boolean(sources.docs?.has(name)) };
+    // `declared` is the catalogue's own `# effect:` for this name, carried on the row so the artifact
+    // says what the document claims beside what this script derived. The two are different questions and
+    // the row is where a reader compares them.
+    return { name, class: cls(name), everSet: setIn, declared: declared.get(name) ?? null,
+      documented: Boolean(sources.docs?.has(name)) };
   });
 
   // "Set nowhere" is not by itself a licence to delete, and this is where 62 of 84 left the list.
@@ -269,6 +382,57 @@ export function classify({ catalogue, sources, setup = setupNames(), readSites =
   const GATE_RE = /(===|!==|==|!=)\s*"[01]"|"[01]"\s*(===|!==|==|!=)|\|\|\s*"1"/;
   const sub = {};
   for (const n of tuning) {
+    // ── A DOCUMENT SAYING "THIS IS NOT A KNOB" KEEPS ITS NAME OFF THIS LIST ────────────────────────
+    //
+    // The classifier keys on the NAME and `tuning` is its residual — what a name falls to when no shape
+    // matches. So a name whose catalogue row declares any other effect reaches the deletion walk on a
+    // class its own documentation contradicts.
+    //
+    // THE TEST IS `!== "tuning"`, SO IT EXCLUDES ALL FIVE OTHER CLASSES. `tuning` is the only declared
+    // effect that AGREES with being a knob, so it is the only one that may reach the walk. Each of the
+    // five, in the catalogue's own words, and why deleting the name would cost something:
+    //
+    //   silent-output-change  "changes what a run produces, and nothing in the run's own artifacts says
+    //                         so" — the worst one to delete, because the loss is invisible in the output.
+    //   disclosed-gate        "changes what a run covers, AND the run discloses the gap" — deleting it
+    //                         silently restores coverage the operator chose to switch off, or removes
+    //                         their ability to switch it off at all.
+    //   credential            "absent, the run refuses at preflight by name" — deleting it turns a
+    //                         named refusal into an unexplained one.
+    //   deployment            "where input and output live; the conclusion a run reaches is unchanged"
+    //                         — unchanged CONCLUSION is not unchanged behaviour. This is the class the
+    //                         whole rule comes from: two notification addresses, legitimately unset on
+    //                         the deployment being read, were proposed for deletion on exactly this
+    //                         mismatch. Excluding it is the original finding, not an extension of it.
+    //   harness               "read only on a fixture, replay or self-test path; no production run
+    //                         reaches it" — the one that reads as safe to delete and is not. Deleting a
+    //                         harness name does not remove a knob nobody uses; it removes the only way
+    //                         a test can run. That argument is already made below for `instrument`, and
+    //                         it is the same argument. A declaration is a stronger version of it,
+    //                         because it does not depend on the spelling.
+    //
+    // The alternative — narrowing to the three classes this comment used to name — would put
+    // `deployment` back on the list and re-admit the defect the rule exists to stop.
+    //
+    // WHAT THIS TREE CAN SHOW YOU, and it is not the number to look for. Measured 2026-09-08: this tree
+    // carries 43 catalogued rows and 12 declarations, and NO name is in the contradicting position, so
+    // the rule changes nothing here and a check written against the live catalogue would pass while
+    // looking at nothing. That is why the checks plant a catalogue rather than reading this one. Over
+    // the full catalogue the same day the position holds seventeen names — ten declared
+    // `silent-output-change`, four `disclosed-gate`, two `harness`, one `credential` — and every one of
+    // them leaves the walk further down for an UNRELATED reason: the instrument regex matching their
+    // spelling, a non-numeric default, or no default found. The file already says what that is worth
+    // about a different name: exclusion "for an unrelated reason (no default found), which is luck, not
+    // a rule". Rename one of them to something without `DUMP` or `PROBE` in it and it joins the deletion
+    // population with a document beside it saying it changes what a run produces.
+    //
+    // Those counts are a dated reading and they move; two of the seventeen were added the same week.
+    // The RULE is what is being asserted here, not the population.
+    //
+    // So the declaration is read FIRST and it is the rule. Nothing is silently dropped: the names land
+    // in their own bucket, and the row carries the declaration that put them there.
+    const say = declared.get(n);
+    if (say && say !== "tuning") { sub[n] = "declared-not-a-knob"; continue; }
     const body = git("grep", "-n", "--", n, "--", "*.mjs", "*.js")
       .split("\n").filter((l) => l && !/(^|\/)test\//.test(l)).join("\n");
     const onlyTests = git("grep", "-l", "--", n, "--", "*.mjs", "*.js").split("\n").filter(Boolean)
@@ -296,6 +460,7 @@ export function classify({ catalogue, sources, setup = setupNames(), readSites =
     instrument: of("instrument"), "path-switch": of("path-switch"),
     "model-or-agent-selector": of("model-or-agent-selector"),
     "non-numeric-default": of("non-numeric-default"), "no-default-found": of("no-default-found"),
+    "declared-not-a-knob": of("declared-not-a-knob"),
     "deletable-number": of("deletable-number"),
   } };
 }
@@ -305,7 +470,12 @@ function build() {
     { encoding: "utf8", cwd: ROOT, maxBuffer: 1e8 }));
   const catalogue = audit.catalogue.rows.map((r) => r.name);
   const sources = gather();
-  const { rows, buckets } = classify({ catalogue, sources });
+  // The catalogue's own declarations, handed in so the deletion walk can read them. Same rows the
+  // audit already produced — not a second parse of the same documents, which would be a second thing
+  // to keep in step.
+  const declared = new Map(audit.catalogue.rows.filter((r) => r.effect).map((r) => [r.name, r.effect]));
+  const { rows, buckets } = classify({ catalogue, sources, declared });
+  const prodRead = sources.prodRead;
   const by = (k) => rows.filter((r) => r.class === k).length;
   return {
     _what: "#1838 step 1 — every catalogued variable classified, and for every TUNING name the environments that have ever set it.",
@@ -318,11 +488,16 @@ function build() {
       names: buckets["deletable-number"], count: buckets["deletable-number"].length,
     },
     _excludedFromDeletion: {
+      // FIRST, because it is the only one of these that is a RULE rather than an observation about a
+      // name's spelling or its default: the catalogue says this name changes what a run produces, so it
+      // is not a spare knob whatever its shape suggests.
+      "declared-not-a-knob": buckets["declared-not-a-knob"],
       instrument: buckets.instrument, "path-switch": buckets["path-switch"],
       "model-or-agent-selector": buckets["model-or-agent-selector"],
       "non-numeric-default": buckets["non-numeric-default"], "no-default-found": buckets["no-default-found"],
     },
     rows,
+    _productionListRead: prodRead,
   };
 }
 
@@ -375,6 +550,18 @@ function main() {
     return;
   }
   const next = build();
+  // A COULD-NOT-LOOK IS NOT AN ANSWER, and this is the one place it would have become one. Without the
+  // production list every name production sets reports `everSet: []`, and `tuning` with an empty
+  // `everSet` is the deletion population — so stamping here would record production's own configuration
+  // as a list of names to remove, in the artifact a reviewer reads to authorise removing them. Exit 2,
+  // not 1: this is the look failing, not the tree being stale, and `--check` already has 1.
+  if (!next._productionListRead && (arg === "--apply" || arg === "--check")) {
+    console.error(`env-classify: ${PROD} is absent, so nothing is known about what production sets.\n`
+      + "  Every production-set name would report `everSet: []` and land on the deletion population.\n"
+      + "  That is this script failing to look, not a finding. Refresh it with `--gather-prod` on the\n"
+      + "  production box, or run this where the list is present.");
+    process.exitCode = 2; return;
+  }
   if (arg === "--apply") { writeFileSync(ART, JSON.stringify(next, null, 2) + "\n"); console.log(`wrote ${ART}`); return; }
   if (arg === "--check") {
     const prev = existsSync(ART) ? readFileSync(ART, "utf8") : "";
@@ -384,7 +571,8 @@ function main() {
     return;
   }
   console.log(JSON.stringify(next._counts));
-  console.log(`step-3 population: ${next._stepThreePopulation.count}`);
+  console.log(`step-3 population: ${next._stepThreePopulation.count}`
+    + (next._productionListRead ? "" : "   — WITHOUT the production list, so every name production sets is counted as never set"));
   for (const [k, v] of Object.entries(next._excludedFromDeletion)) console.log(`  excluded ${k.padEnd(24)} ${v.length}`);
 }
 

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/head-arrived-gated.mjs

@@ -113,7 +113,7 @@ export function fetchPulls(sha, repo, run = ghJson) {
 /**
  * `owner/repo` for the checkout this runs in, from its own origin remote.
  *
- * DERIVED, NOT CONFIGURED, and deliberately not an environment variable: 's ratchet is right that
+ * DERIVED, NOT CONFIGURED, and deliberately not an environment variable: the ratchet is right that
  * a new knob owes a documented row, and this one would document a fact the checkout already knows.
  * It also keeps the script honest in a fork — a published clone asks about ITS repository
  * rather than about ours.

package/scripts/headless-page.mjs

@@ -36,6 +36,12 @@ import { execFileSync } from "node:child_process";
 
 /** Chrome's own error pages live under this scheme. Nothing a real document is served from does. */
 export const CHROME_ERROR_SCHEME = "chrome-error:";
+/** What Chrome shows before it has navigated. Not a document, and not a wrong one. */
+export const START_PAGE = "about:blank";
+/** How long `assertPageLoaded` will wait for the browser to leave its start page. */
+export const NAVIGATION_GRACE_MS = 5000;
+/** How often it asks, inside that grace. */
+export const NAVIGATION_POLL_MS = 100;
 
 /**
  * PURE. Given what the page says about itself, is it the document we asked for?
@@ -74,6 +80,25 @@ export function pageVerdict({ href = "", expected = "", marker = null, markerNam
         + "captured is Chrome's interstitial, not the artefact — and that page carries an `<h1>`, a "
         + "`<title>` and a body, so a content check alone reads it as a success." };
   }
+  // ── THE BROWSER'S START PAGE IS NOT A WRONG DOCUMENT (tracker issue 273) ────────────────────────
+  //
+  // `about:blank` is what Chrome shows before it has navigated anywhere. Reaching the check below, it
+  // compares unequal to the expected URL and was reported as `wrong-document` — "a redirect, a stale tab
+  // or a second page target" — which is a finding about a page. It is not one. Nothing was ever loaded,
+  // so nothing about the target document has been measured either way.
+  //
+  // This mattered because it is what a LOADED BOX produces: three of these scripts launch Chrome with the
+  // URL as a command-line argument and cannot wait for a navigation event, so under load the address is
+  // read before the browser has moved. A real defect and a slow browser then arrived as the same message,
+  // and the arms that exist to catch a wrong page were the ones that fired.
+  if (said === START_PAGE || said.startsWith(`${START_PAGE}?`) || said.startsWith(`${START_PAGE}#`)) {
+    return { ok: false, kind: "not-navigated",
+      why: `chrome is on its start page (${said}) and never reached ${expected}. Nothing about that `
+        + "document has been measured, so this is not a finding about the page. TWO THINGS LOOK LIKE "
+        + "THIS and the address cannot tell them apart: a navigation that failed without saying so, and "
+        + "one that had not happened yet. That is why the caller waits before asking — a verdict of this "
+        + "kind means it waited and the browser never left the start page." };
+  }
   // NORMALISED ON BOTH SIDES. Chrome resolves and percent-encodes a `file://` argument, so a raw string
   // comparison fails on a path with a space and reports "the wrong document" about the right one.
   const norm = (u) => { try { return new URL(u).href; } catch { return String(u); } };
@@ -103,8 +128,32 @@ export function pageVerdict({ href = "", expected = "", marker = null, markerNam
  * handshake before this file existed and rewriting seven of them to share one is a bigger change than the
  * defect warrants. What they must share is the QUESTION.
  */
-export async function assertPageLoaded(evaluate, { expected, marker = null, markerName = "the page's own content", what = "this page", errorText = null } = {}) {
-  const href = await evaluate("location.href");
+export async function assertPageLoaded(evaluate, { expected, marker = null, markerName = "the page's own content", what = "this page", errorText = null,
+  graceMs = NAVIGATION_GRACE_MS, pollMs = NAVIGATION_POLL_MS,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = () => Date.now() } = {}) {
+  // ── WAIT FOR THE BROWSER TO LEAVE ITS START PAGE, THEN JUDGE (tracker issue 273) ─────────────────
+  //
+  // Three of these scripts launch Chrome with the URL as an argument and get no response to wait on, so
+  // the first read of `location.href` can land before the browser has moved. On an idle box it never
+  // does; under a full parallel suite it did, repeatedly, and the arms reported the start page as a
+  // wrong document.
+  //
+  // BOUNDED, AND THE BOUND IS THE POINT. This waits for the browser to become ready — it does not wait
+  // for the page to become correct. If the address is anything other than the start page it is judged
+  // immediately, so a genuinely wrong document still fails on the first read and fails as fast as it did
+  // before. Only the "nothing has happened yet" case costs time, and only up to the grace.
+  //
+  // When the grace runs out the verdict is `not-navigated`, which is a could-not-look and says so.
+  // Deadline arithmetic is the caller's to drive: `sleep` and `now` are injected so the exhausted path
+  // can be exercised without a browser and without waiting.
+  let href = await evaluate("location.href");
+  if (String(href ?? "") === START_PAGE) {
+    const until = now() + graceMs;
+    while (String(href ?? "") === START_PAGE && now() < until) {
+      await sleep(pollMs);
+      href = await evaluate("location.href");
+    }
+  }
   const found = marker == null ? null : Boolean(await evaluate(`Boolean(${marker})`));
   const verdict = pageVerdict({ href, expected, marker: found, markerName, errorText });
   if (!verdict.ok) {