clearotron 0.2.1 → 0.2.2

package/scripts/composer-render-check.mjs

@@ -194,7 +194,7 @@ const SCRIPT = `
     return false;
   };
   const txt = () => document.body.innerText;
-  // tracker issue 1809 — A MISS THROWS, NAMING WHAT IT MISSED. This returned undefined, and the thirteen sites below
+  // A MISS THROWS, NAMING WHAT IT MISSED. This returned undefined, and the thirteen sites below
   // that dereference it immediately turned a missing button into "Cannot read properties of undefined
   // (reading 'click')" — a message naming no selector, no screen and no step. It was intermittent, so it
   // read as a flaky suite rather than as a driver that could not say what it had not found.
@@ -303,7 +303,7 @@ const SCRIPT = `
 
   // ...and the segmented toggle switches back, persistently.
   findByText('button', /Set it up myself/).click();
-  // tracker issue 1809 — THIS WAIT WAS DEAD. It watched for the text "Start point", which the composer stopped
+  // THIS WAIT WAS DEAD. It watched for the text "Start point", which the composer stopped
   // rendering; the only "Start point" left in the tree is a COMMENT in NewClearance.tsx. Because settle
   // returned false silently, it degraded into a flat 6-second sleep and the check still reported
   // "render check passed" — making the wait loud is what surfaced it. Waits on the picker the manual
@@ -388,7 +388,7 @@ const SCRIPT = `
   out.knockoutTier = /Knockout search/.test(tierText() || '');
   out.knockoutSweep = /1 broad sweep per name/.test(txt());
   out.nativeHiddenOnKnockout = !maybeByText('button', /Native-language investigation/);
-  // tracker issue 706 — the copy changed and the assertion follows it. The OLD string ("not searched; filing counts
+  // the copy changed and the assertion follows it. The OLD string ("not searched; filing counts
   // only") led with the absence and then contradicted it in the same clause; what a Knockout buys at the
   // register is three counts per name in the classes named, and what it does not buy is a reading of the
   // filings behind them. This measures the same thing the ok() below claims: that the card states the
@@ -527,7 +527,7 @@ const SCRIPT = `
   // The blocker text only proves the label. What matters is that NOTHING is posted: a screen that shows
   // a blocker and posts anyway is a screen whose refusal is decoration.
   //
-  // tracker issue 2119 — WAIT FOR THE BUTTON, NOT FOR ITS NEIGHBOUR. The settle above waits for the
+  // WAIT FOR THE BUTTON, NOT FOR ITS NEIGHBOUR. The settle above waits for the
   // failure notice to CLEAR, and the notice can clear before the dialog re-renders its controls. This
   // click then landed on a screen that had not finished and threw "no button matching /Back to edit/ is
   // on screen" — which reads as a missing control and was a missing wait. Measured on CI run
@@ -653,7 +653,7 @@ const SCRIPT = `
     // full product names the table ran ~2x its wrapper and barely two of the columns were visible — a
     // boolean could not tell that from the 40px the 760px min-width has always cost.
     out.matrixOverflowPx = wrap && table ? table.scrollWidth - wrap.clientWidth : null;
-    // ── Refs tracker issue 2144 — THE ESCAPE MUST BE A CHILD OF THE THING THAT CAPS IT ─────────────
+    // ── THE ESCAPE MUST BE A CHILD OF THE THING THAT CAPS IT ─────────────
     // The cap is a direct-child selector. The opt-out spent two rounds of fixing applied to a
     // GRANDCHILD, where lifting the max-width asks a box to be wider than the box it lives in — which
     // is why the table stayed at 718px while reading, in the source, as though it had opted out. No
@@ -732,7 +732,7 @@ const SCRIPT = `
     // assertion to touch a missing key blew up with a TypeError instead. out.steps says how far it got.
     out.fatal = String(e && e.message ? e.message : e);
     out.raw = 'driver threw after: ' + out.steps.join(' -> ');
-    // tracker issue 1809 — the named throw says WHAT was missing; this says what was on screen instead. Without it a
+    // the named throw says WHAT was missing; this says what was on screen instead. Without it a
     // diagnostic fix still loses the diagnosis, which is the whole complaint this change answers.
     out.body = txt().slice(0, 900);
     return out;

package/scripts/contract-dictation-scan.mjs

@@ -7,7 +7,7 @@
 // that touches disk, and it exists so the planted-divergence test can hand the checker an invented
 // file instead of writing one into the tree.
 //
-// THE CORPUS IS DISCOVERED, NEVER ENUMERATED, and that is 's hardest requirement rather than a
+// THE CORPUS IS DISCOVERED, NEVER ENUMERATED, and that is the hardest requirement rather than a
 // preference: "plant a divergence in a NEW authoring layer — the check must find it structurally, not
 // because the layer was enumerated." So the corpus is every tracked `.mjs` and `.md` under `driver/`,
 // full stop. A new dispatch module, a new skill file, a seventh authoring surface nobody has thought
@@ -15,7 +15,7 @@
 //
 // `git ls-files`, via shared/tracked-files.mjs, because a directory walk lists a different set (build
 // output, an editor backup, a contributor's scratch file) and because a guard that cannot see its
-// corpus must SAY SO rather than report a clean zero. 's lesson, and CLAUDE.md's hard rule: an
+// corpus must SAY SO rather than report a clean zero. That lesson, and CLAUDE.md's hard rule: an
 // absence is a finding.
 //
 //   node scripts/contract-dictation-scan.mjs           report; exit 1 on any divergence

package/scripts/dead-names.mjs

@@ -45,7 +45,7 @@ export const GUARD = "dead-names (#853)";
 // `clawdi-lisa` and `clawdi-lidia` are 's, not 's, and they are here rather than in a second
 // scanner because the mechanism is identical: a name that must never reappear. They were per-person
 // agent identities for individuals at this firm, shipped in an operator script's default roster, in a
-// systemd unit watching their queues, and in two test fixtures. 's out-of-scope note ruled `alex`
+// systemd unit watching their queues, and in two test fixtures. That out-of-scope note ruled `alex`
 // and `sam` INVENTED, which is why those stay; these two were never covered by that ruling.
 export const DEAD_NAME_RE = /lorestar|lore_(pool|url|flags)|prelim_lore|lorectl|loreurl|lorecontrols|trademark-lore|\blore\b|\baughra|clawdi-(lisa|lidia)/i;
 

package/scripts/drain-preflight.mjs

@@ -5,7 +5,7 @@
 //
 // The question came from the codex round (18 Aug): an engine override is carried by the DRIVER
 // ACTIVATION's environment, and an activation that never happens carries no environment. On the box this
-// was first asked about, no runner process was running for any user and no prelim unit existed at system
+// was first asked about, no runner process was running for any user and no clearotron unit existed at system
 // level — so every job enqueued would have sat there, and the round would have been fiction.
 //
 // Nothing here builds a drainer. ONE ALREADY SHIPS: `driver/systemd/prelim-driver.path` (inotify),
@@ -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
@@ -132,7 +132,7 @@ export function watchedQueueDirs(unitText, home) {
     //
     // Reading the list without the reset is wrong in BOTH directions — it keeps globs the deployment
     // has disowned, and (because the caller then compares against a superset) it can report a directory
-    // as watched that nothing watches. The second is 's original harm, produced by the guard built
+    // as watched that nothing watches. The second is the original harm, produced by the guard built
     // to prevent it.
     if (!m[1].trim()) { out.length = 0; continue; }
     // EXTENSION-AGNOSTIC. The queue watcher globs `*.json` and the outbox watcher globs `*.pending`;
@@ -223,7 +223,7 @@ export function runnerRunning() {
   return { known: true, procs };
 }
 
-// ── THE OUTBOX IS THE SAME HAZARD, ONE LANE OVER ('s tail) ───────────────────────────────────────
+// ── THE OUTBOX IS THE SAME HAZARD, ONE LANE OVER (the tail) ───────────────────────────────────────
 //
 // `prelim-outbox.path` carries the identical literal glob and says so in its own header: "this literal
 // and the driver's `config.outboxDir` are two spellings of one fact with nothing checking them against
@@ -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/e2e-unread-terminals.mjs

@@ -39,7 +39,7 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { driverDir } from "../shared/driver-dir.mjs";   //
 // The seat-record reader, imported rather than re-derived: "does this run have work in it" must be the
-// SAME question the retry instrument asks, or two tools disagree about one fact (,).
+// SAME question the retry instrument asks, or two tools disagree about one fact ().
 import { dispatchRows } from "../driver/seat-attempts.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — realpath both sides, or a symlinked invocation exits 0 silently
 

package/scripts/e2e.mjs

@@ -44,7 +44,7 @@ import { mcpToolCall } from "../driver/portal-mcp-client.mjs";
 // resolve the depth the same way every other door does — never from a word the scenario file typed.
 import { reportIdentityFor, ORDERABLE_PRODUCTS, RETIRED_PRODUCTS } from "../driver/search-policy.mjs";
 // The queue's filename vocabulary, from the module that owns it. created that module because the
-// vocabulary "has now been written down three times and the copies disagreed"; 's first draft wrote it
+// vocabulary "has now been written down three times and the copies disagreed"; the first draft wrote it
 // down twice more here, from memory, and false-alarmed on every prose sidecar of every live job. Sourced,
 // so the next suffix the engine adds reaches this harness the day it lands. queue-markers.mjs is PURE —
 // importing it pulls in nothing, which is why this file can have it and cannot have runner.mjs (that chain
@@ -57,10 +57,10 @@ import { isLiveQueueMarker, isQueueSidecar, liveQueueState, LIVE_QUEUE_STATES, T
 // leave the real one to park tomorrow's re-run as a duplicate. usage-ledger.mjs is a pure leaf too
 // (node:fs + node:path + queue-markers.mjs), so it drags no driver machinery in either.
 import { matterLedgerPath } from "../driver/usage-ledger.mjs";
-import { probeWorker } from "../driver/queue-watch-probe.mjs";   // tracker issue 181 — the drain this deployment actually has
+import { probeWorker } from "../driver/queue-watch-probe.mjs";   // the drain this deployment actually has
 // Teardown asks whether a process is actually producing a run before it rewrites the record that says so.
 import { claimLivenessForCodename, claimForbidsDestruction } from "../driver/claim-liveness.mjs";
-// The store admission sweep (, moved here from a bundled-store CI test when the bundled scenarios
+// The store admission sweep (moved here from a bundled-store CI test when the bundled scenarios
 // were deleted): every job block in the configured store must be treated by the doors exactly the way
 // its scenario declares, and the check has to run where the store exists — CI cannot read it.
 import { validateJob } from "../driver/enqueue-schema.mjs";
@@ -82,7 +82,7 @@ import { readReceipt, appendRound, stampRound, tokenFromRef, roundsFromRuns, mer
   roundLetters, receiptPath, scenarioRefs as scenarioRefsOf, findRunsByRef as findRunsIn,
   SCENARIO_FILE, byScenarioNumber, tierOf, SCENARIO_TIERS, DEFAULT_TIER }
   from "../driver/e2e-rounds.mjs";
-// 's refusal — "is this data plane production" — sourced, because this file used to restate it and
+// That refusal — "is this data plane production" — sourced, because this file used to restate it and
 // the two copies had ALREADY drifted, in both directions:
 //   CLEAROTRON_REPORTS_DIR=/srv/trademark-archive-dev  the guard passes (it matches the archive as a path
 //     PREFIX, and its own test requires that a name merely resembling production's passes). The copy
@@ -403,7 +403,7 @@ export function lintScenarios(scenarios) {
     //
     // Deliberately here rather than at a selection site, because that is what gets the SCOPE right for
     // nothing: `sweepStoreOrDie()` bare (cmdList) refuses on any scenario's finding, and
-    // `sweepStoreOrDie(id)` (cmdRun) refuses only on the named scenario's — 's split, already
+    // `sweepStoreOrDie(id)` (cmdRun) refuses only on the named scenario's — the split, already
     // implemented at the two call sites. A round that selects BY tier has to read every tier to choose,
     // so a typo anywhere corrupts the selection rather than one entry; a run that named its scenario is
     // answerable only for that one. Both fall out of where this line sits.
@@ -886,7 +886,7 @@ function enqueueViaCli(job) {
   } finally { rmSync(dir, { recursive: true, force: true }); }
 }
 
-// EXPORTED for 's arm: the not-configured branch is the whole subject, and the only honest way to
+// EXPORTED for the arm: the not-configured branch is the whole subject, and the only honest way to
 // drive it is to call this function in a process with no MCP port in scope — the state a rebuilt box
 // is actually in. Asserting on the source text instead would pass on a file that no longer runs it.
 export async function enqueueViaMcp(job, { clientPrincipal = false, forwarder = null } = {}) {
@@ -894,7 +894,7 @@ export async function enqueueViaMcp(job, { clientPrincipal = false, forwarder =
   // refusing one. A door that is not configured on this deployment never saw the job, so it holds no
   // opinion about it: recording it as a refusal manufactures agreement on the refusal cases (a
   // correctly-refusing door and an absent one produce the same line) and, on the admit cases, fires
-  // #98's "the one that ACCEPTED is the defect" at the door that behaved. This is 's rule reaching
+  // the "the one that ACCEPTED is the defect" rule at the door that behaved. This is that rule reaching
   // the one transport failure that happens BEFORE any request: not-configured is could-not-ask.
   if (!MCP_URL) return { ok: false, transport: true, status: null,
     out: "no TRADEMARK_MCP_HTTP_PORT in scope — this door is not configured on this deployment, so it was never asked" };
@@ -1601,7 +1601,7 @@ function queueDrainState({
 // THREE STATES, NOT TWO, and the third is the reason this is a function rather than a field read.
 // A scenario that states nothing must read as CANNOT TELL — never as synthetic, and never as silence.
 // Defaulting an absent label to "synthetic" would be a guess presented as a fact, and letting it print
-// nothing is 's defect exactly: a benchmark that printed only when the key was present rendered as
+// nothing is the defect exactly: a benchmark that printed only when the key was present rendered as
 // silence, which reads exactly like a benchmark that was met. An unstated label is reported, every time.
 export const MARK_PROVENANCE = { LIVE: "live", SYNTHETIC: "synthetic", UNSTATED: "unstated" };
 

package/scripts/env-audit.mjs

@@ -10,7 +10,7 @@
 // ── why this exists ──────────────────────────────────────────────────────────────────────────────
 //
 // `docs/architecture/05-config-governance.md` states its own maintenance rule: "adding a var anywhere
-// in the repo means adding its row here". 's review found that rule has NO enforcement — the
+// in the repo means adding its row here". That review found that rule has NO enforcement — the
 // placeholder-default guard checks fallbacks, not existence — so it has been prose since it was
 // written, and the surface has grown the whole time.
 //
@@ -36,7 +36,7 @@
 //
 // ── what it deliberately does not do ─────────────────────────────────────────────────────────────
 //
-// It deletes nothing. 's tier 2 (delete the dead) is explicitly not this, and the issue's own
+// It deletes nothing. That tier 2 (delete the dead) is explicitly not this, and the issue's own
 // queue note says deleting toggles mid-verification moves the range again. This reports; a person
 // decides.
 
@@ -108,7 +108,7 @@ const CODE_RE = /\.(mjs|js|cjs|ts)$/;
 // above describes happening again. Converting the eight numeric getters from
 // `Number(this.envValue("NAME") || d)` to `numericSetting("NAME")` moved the name out of a shape this
 // scanner knew and into one it did not: the audit stopped seeing CLEAROTRON_MAX_CLAIM_AGE_MS and
-// CLEAROTRON_CARD_CONCURRENCY, whose ONLY reads are accessor reads, and 's product-read arm went red.
+// CLEAROTRON_CARD_CONCURRENCY, whose ONLY reads are accessor reads, and the product-read arm went red.
 // It went red because that arm names those two variables — which is the whole reason it names them. A
 // conversion narrows this guard silently, so both spellings land in the same commit as the conversion.
 const ACCESSOR_RE = /\b(?:envValue|envOn|envGateOn|numericSetting|resolveNumericSetting)\s*\(\s*["']([A-Z][A-Z0-9_]*)["']|\benvFrom\s*\(\s*[^,()]+,\s*["']([A-Z][A-Z0-9_]*)["']/g;
@@ -154,7 +154,7 @@ const stripCommentLines = (text) => text.split("\n").filter((l) => !COMMENT_LINE
 // — no `env`-prefixed regex can match a read where the name never appears beside an `env` token.
 //
 // THE BINDING IS SCREAMING_CASE AND THE LITERAL IS ENV-SHAPED, both required. `const label = "x"` is
-// not an env binding, and neither is `const PREFIX = "prelim-"`. The pair is what makes this a
+// not an env binding, and neither is `const PREFIX = "clearotron-"`. The pair is what makes this a
 // declaration of an environment name rather than a string that happens to be uppercase.
 const BINDING_RE = /(?<![.\w$])const\s+([A-Z][A-Z0-9_]*)\s*=\s*["']([A-Z][A-Z0-9_]{2,})["']/g;
 
@@ -230,7 +230,7 @@ export const SYSTEM_OWNED = new Set([
   // — both arrived with the injected-`env` widening above, and both are set by the service
   // manager rather than by any deployment of this product: systemd sets INVOCATION_ID (which is
   // exactly what shared/env-local.mjs reads it to detect), and the session bus sets
-  // DBUS_SESSION_BUS_ADDRESS. 's body asserts the audit already excluded these two. It did not —
+  // DBUS_SESSION_BUS_ADDRESS. That body asserts the audit already excluded these two. It did not —
   // they were absent from this list, and they only stayed out of the register because the scanner
   // could not see the reads at all.
   "INVOCATION_ID", "DBUS_SESSION_BUS_ADDRESS",
@@ -520,7 +520,7 @@ export function auditEnv(root = ROOT) {
 //                         1  CLEAROTRON_SEND_TOOL_PREFIX — genuinely dead, and this direction does not
 //                            catch it either: its one surviving mention is a governance-doc line, and
 //                            a mention is enough to spare a row. Under-firing is the cost of the
-//                            trade, taken deliberately. It is 's prose-sweep class.
+//                            trade, taken deliberately. It is the prose-sweep class.
 //
 //                       So SIX of ten deletions would have been wrong, two of them credential rows.
 //                       Evidence used instead: the bare NAME, on a name boundary, anywhere in the
@@ -639,7 +639,7 @@ export function orphanRows(rows, mentioned) {
 }
 
 // The catalogues describe the contract; they are not readers of it. Include them and every row is its
-// own evidence, which is the circularity 's "a check cannot use its own source as evidence" names.
+// own evidence, which is the circularity the "a check cannot use its own source as evidence" names.
 // — `docs/architecture/env-set-in-production.txt` joins them, and the reason is the rule this set
 // exists for. It is a LIST OF NAMES, committed as step 1's production evidence because a reviewer cannot
 // make that read. Left in the corpus it becomes an alibi for every catalogue row at once: each row

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]);
@@ -246,11 +322,44 @@ 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" };
+  // 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"
@@ -306,6 +415,7 @@ function build() {
   const catalogue = audit.catalogue.rows.map((r) => r.name);
   const sources = gather();
   const { rows, buckets } = classify({ catalogue, sources });
+  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.",
@@ -323,6 +433,7 @@ function build() {
       "non-numeric-default": buckets["non-numeric-default"], "no-default-found": buckets["no-default-found"],
     },
     rows,
+    _productionListRead: prodRead,
   };
 }
 
@@ -375,6 +486,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 +507,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) {