clearotron 0.2.3 → 0.2.4

package/scripts/mint-reference-strip-backlog.mjs

@@ -14,6 +14,7 @@
 // CI runs. Without it, the table is rewritten.
 import { readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { publishedOf } from "../shared/reference-guard-classes.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { SIGNATURES, censusOf } from "../driver/reference-strip-signatures.mjs";
@@ -21,8 +22,18 @@ import { SIGNATURES, censusOf } from "../driver/reference-strip-signatures.mjs";
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const TABLE = join(ROOT, "driver/test/fixtures/reference-strip-backlog.json");
 
-const tracked = execFileSync("git", ["-C", ROOT, "ls-files"], { encoding: "utf8", maxBuffer: 1 << 28 })
+// THE PUBLISHED POPULATION, NOT THE INDEX. `git ls-files` reads the index, and an overlay run stages
+// the withheld corpus over a clone without committing it — so minting there wrote withheld hits into
+// this public table with nothing reporting it. `publishedOf` filters the tracked list down to what
+// HEAD carries; one helper, shared with the residue floor, because two spellings of this rule would
+// disagree under the overlay and `--check` would report a difference that is only the two
+// instruments asking different questions.
+const all = execFileSync("git", ["-C", ROOT, "ls-files"], { encoding: "utf8", maxBuffer: 1 << 28 })
   .split("\n").filter(Boolean);
+const p = publishedOf(all, ROOT);
+if (p.error) { console.error(`mint-reference-strip-backlog: ${p.error}`); process.exit(2); }
+if (p.laid) console.log(`mint-reference-strip-backlog: ${p.laid} tracked path(s) are not in HEAD — laid over this checkout, not published in it, and not counted`);
+const tracked = p.files;
 const minted = censusOf(ROOT, tracked, (f) => readFileSync(join(ROOT, f), "utf8"));
 
 if (process.argv.includes("--check")) {

package/scripts/mint-suite-census.mjs

@@ -36,6 +36,9 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CENSUS_WORKSPACES, CENSUS_ROOT_SCRIPTS, countTestSites, collectionFromManifests, censusDisagreements,
   rootScriptDisagreements, censusBuckets } from "../shared/suite-census.mjs";
+// THE MEASUREMENT SIDE of the root-script check: the census states the globs it expects and this
+// supplies what the corpus actually resolves to, so the two can disagree.
+import { providerTestFiles } from "./test-full.mjs";
 import { withheldEntryFor, announceWithheldMode } from "../shared/withheld-paths-access.mjs";   // — withheld is a stated absence, not a loss.: the record does not ship, and without it every absence is a loss
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — realpath both sides, or a symlinked invocation exits 0 silently
 
@@ -129,7 +132,7 @@ function main() {
   // — the same question of the ROOT scripts. Narrowing `test:providers`' glob silences a third of
   // that population at exit 0, and no per-workspace check can see it: `providers` is not a workspace.
   const disagreements = [...censusDisagreements(collectionFromManifests(readManifest)),
-    ...rootScriptDisagreements(readManifest)];
+    ...rootScriptDisagreements(readManifest, undefined, () => providerTestFiles())];
   if (disagreements.length) {
     // — the message names BOTH declared sources now. It used to say "the census and `npm run
     // test:full` disagree" whatever had moved, so a root-script disagreement sent the reader to look at
@@ -150,7 +153,7 @@ function main() {
   try { prev = JSON.parse(readFileSync(CENSUS, "utf8")); } catch { /* first mint */ }
 
   const lost = [];
-  // THE THIRD BUCKET, ruled by overwatch 2026-09-06.
+  // THE THIRD BUCKET, decided 2026-09-06.
   //
   // A reasoned skip is neither a pass nor a loss, and this census had no place to put one. Two guards
   // that are each right about their own failure had come to disagree: `a-bail-on-an-unmeetable-

package/scripts/render-check.mjs

@@ -59,7 +59,8 @@
 // coupling ever bites, that is the moment to mount the real component instead of copying it.
 
 import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync, existsSync, readdirSync } from "node:fs";
-import { reapOnExit } from "../shared/reap-on-exit.mjs";   // — a detached group dies with this script
+import { reapOnExit, removeOnExit } from "../shared/reap-on-exit.mjs";
+import { assertRootFits, browserEnv } from "../shared/browser-temp-root.mjs";   // — a detached group dies with this script
 import { execFileSync, spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { basename, extname } from "node:path";
@@ -76,6 +77,16 @@ const has = (n) => process.argv.includes(`--${n}`);
 
 const ZOOMS = arg("zoom", "1.0,1.25").split(",").map((z) => z.trim()).filter(Boolean);
 const WORK = join(tmpdir(), `render-check-${process.pid}`);
+// WORK is this run's browser temp root as well as its scratch: the browser is spawned with TMPDIR
+// pointing here, so the process-singleton lock it creates lands inside and leaves with it. Asserted
+// rather than assumed, because the budget is on the PATH and nothing about this one is fixed.
+assertRootFits(WORK);
+// The removal below runs on the paths somebody wrote a branch for. This one also covers the exits
+// nobody writes a branch for, which is where the leaked locks came from.
+const stopRootSweep = removeOnExit(WORK);
+// ...unless the caller asked to keep it. Read here rather than at the cleanup below, because the
+// sweep is registered at import time and `--keep` has to be honoured before any exit can happen.
+if (has("keep")) stopRootSweep();
 
 /**
  * Replay the committed frozen run into a fresh pool and return its path.
@@ -412,7 +423,7 @@ async function measureAtZoom(zoom, deadlineMs = 90_000) {
   // — DETACHED so Chrome LEADS A PROCESS GROUP. Its renderer, GPU and zygote processes are
   // separate PIDs; without a group there is nothing to signal them with, and the teardown below could
   // only ever reach the parent.
-  ], { stdio: ["ignore", "ignore", "ignore"], detached: true });
+  ], { stdio: ["ignore", "ignore", "ignore"], detached: true, env: browserEnv(WORK) });
   // — and the group dies with THIS script, on every exit it can observe.
   // The teardown below runs on the paths somebody wrote a branch for; a cancelled CI job (SIGTERM),
   // a Ctrl-C, or a throw elsewhere in this file are not among them — and that is where the measured

package/scripts/report-frame-check.mjs

@@ -29,6 +29,8 @@ import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
+import { removeOnExit } from "../shared/reap-on-exit.mjs";
+import { assertRootFits, browserEnv } from "../shared/browser-temp-root.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -48,6 +50,11 @@ function main() {
   console.log(`shipped sandbox: ${tokens.join(" ")}`);
 
   const work = mkdtempSync(join(tmpdir(), "frame-check-"));
+  // The browser inherits TMPDIR from here, so its process-singleton lock lands under `work` and goes
+  // with it. `removeOnExit` covers the exits the `finally` below cannot see — a cancelled job, a
+  // Ctrl-C — which are the ones that left locks behind in the shared temp directory.
+  assertRootFits(work);
+  removeOnExit(work);
   try {
     // The page builds the frame with the SHIPPED string and reports what the browser kept.
     writeFileSync(join(work, "verify.html"), `<!doctype html><title>pending</title><body>
@@ -62,7 +69,7 @@ function main() {
       "--headless=new", "--disable-gpu", "--no-sandbox",
       `--user-data-dir=${join(work, "prof")}`,
       "--virtual-time-budget=8000", "--dump-dom", `file://${join(work, "verify.html")}`,
-    ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 120000 });
+    ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 120000, env: browserEnv(work) });
 
     // ── IS THIS OUR PAGE, OR CHROME'S ERROR PAGE? (tracker issue 227) ───────────────────────────────
     //

package/scripts/report-screenshot.mjs

@@ -20,10 +20,11 @@
 // "fix" either to match the other.
 import { spawn } from "node:child_process";
 import { assertPageLoaded, cjkCharsIn, cjkVerdict, fontsCovering } from "./headless-page.mjs";   // did chrome open the report, or its own error page?
-import { mkdtempSync, writeFileSync, existsSync } from "node:fs";
+import { writeFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { browserRun } from "../shared/browser-temp-root.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const OUT = resolve(process.argv[3] ?? join(ROOT, "docs", "assets", "example-report.png"));
@@ -43,12 +44,14 @@ if (!existsSync(page)) {
   process.exit(2);
 }
 
-const userDir = mkdtempSync(join(tmpdir(), "report-shot-"));
+// The profile goes inside a run root whose TMPDIR the browser inherits, so the singleton
+// lock it writes there leaves with the root instead of accumulating in the shared one.
+const { profile: userDir, env: chromeEnv } = browserRun("report-shot-");
 const chrome = spawn("google-chrome", [
   "--headless=new", "--disable-gpu", "--no-sandbox", "--hide-scrollbars",
   `--user-data-dir=${userDir}`, `--window-size=${WIDTH},${HEIGHT}`,
   "--remote-debugging-port=0", `file://${page}`,
-], { stdio: ["ignore", "pipe", "pipe"] });
+], { stdio: ["ignore", "pipe", "pipe"], env: chromeEnv });
 
 let stderr = "";
 const wsUrl = await new Promise((res, rej) => {

package/scripts/revisit-render-check.mjs

@@ -61,12 +61,13 @@
 
 import { navigateOrRefuse } from './headless-page.mjs'   // Page.navigate returns an errorText, and nothing read it
 import { createServer } from 'node:http'
-import { readFileSync, existsSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs'
+import { readFileSync, existsSync, writeFileSync, rmSync } from 'node:fs'
 import { join, extname, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { spawn } from 'node:child_process'
 import { tmpdir } from 'node:os'
 import { reapOnExit } from '../shared/reap-on-exit.mjs' // — a detached group dies with this script
+import { browserRun } from "../shared/browser-temp-root.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const DIST = join(HERE, '..', 'portal-ui', 'dist')
@@ -174,11 +175,13 @@ const origin = `http://127.0.0.1:${server.address().port}`
 
 // ── chrome ──────────────────────────────────────────────────────────────────────────────────────────
 
-const profile = mkdtempSync(join(tmpdir(), 'revisit-check-'))
+// The profile goes inside a run root whose TMPDIR the browser inherits, so the singleton
+// lock it writes there leaves with the root instead of accumulating in the shared one.
+const { profile, env: chromeEnv } = browserRun("revisit-check-")
 const chrome = spawn('google-chrome', [
   '--headless=new', '--disable-gpu', '--no-sandbox', '--remote-debugging-port=0',
   `--user-data-dir=${profile}`, '--window-size=1440,900', 'about:blank',
-], { stdio: ['ignore', 'ignore', 'pipe'] })
+], { stdio: ['ignore', 'ignore', 'pipe'], env: chromeEnv })
 reapOnExit(chrome)
 
 const wsUrl = await new Promise((resolve, reject) => {

package/scripts/score.mjs

@@ -583,7 +583,7 @@ function print(id, ref, run, s, delta, refPath) {
     // workspace archive instead of the pool — and the lane fact is visible on the `lane:` line anyway.
     console.log(row("withheld", "n/a", s.collapseReason));
   } else {
-    // — THE SCOPE ON THE LINE, not in a footnote. `role-e2e` calls this "the bucket that changes
+    // — THE SCOPE ON THE LINE, not in a footnote. The testing doctrine calls this "the bucket that changes
     // what you fix", so a bare `0` beside that sentence reads as "no seam defect this round" — and on
     // the round that measured it, two live in-class rights the run retrieved and dropped were outside
     // the reference and could not have raised it. The footnote saying `withheld` is a reference-entry

package/scripts/strip-tracker-citations.mjs

@@ -58,6 +58,7 @@
 // wants a guard against reintroduction rather than a backlog. Different residue, different repair.
 import { readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { publishedOf } from "../shared/reference-guard-classes.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -122,8 +123,15 @@ export function surveyOf(files, read) {
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  const tracked = execFileSync("git", ["-C", ROOT, "ls-files"], { encoding: "utf8", maxBuffer: 1 << 28 })
+  // THE PUBLISHED POPULATION, NOT THE INDEX. The counts this prints are read as a statement about the
+  // public tree, and under an overlay `git ls-files` would have made them a statement about the
+  // withheld corpus instead. Same helper as the residue floor and the backlog minter.
+  const all = execFileSync("git", ["-C", ROOT, "ls-files"], { encoding: "utf8", maxBuffer: 1 << 28 })
     .split("\n").filter(Boolean);
+  const pub = publishedOf(all, ROOT);
+  if (pub.error) { console.error(`strip-tracker-citations: ${pub.error}`); process.exit(2); }
+  if (pub.laid) console.log(`${pub.laid} tracked path(s) are not in HEAD — laid over this checkout, not published in it, and not read`);
+  const tracked = pub.files;
   const s = surveyOf(tracked, (f) => readFileSync(join(ROOT, f), "utf8"));
   // BEFORE ANYTHING ELSE, because every number under it is about the files that COULD be read.
   if (s.unreadable.length) {

package/scripts/test-full.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// RUN EVERY CORPUS, AND REFUSE TO BE SILENT ABOUT ONE THAT WAS NOT RUN.
+//
+//   node scripts/test-full.mjs                 # every corpus
+//   node scripts/test-full.mjs --only providers # one of them
+//   node scripts/test-full.mjs --list           # the plan, run nothing
+//
+// ── WHAT THIS REPLACES, AND WHY A FLAG WAS NOT ENOUGH ────────────────────────────────────────────
+//
+// `npm run test:full --workspaces --if-present` reported this suite green while running part of it.
+// Two separate holes, and only the smaller one is about the flag:
+//
+//   - `providers/` holds twelve directories of register-adapter tests. ELEVEN OF THEM ARE NOT
+//     WORKSPACES — they have no package.json at all — so no `--workspaces` command can reach them,
+//     with or without `--if-present`. That is the larger half and no flag fixes it.
+//   - `--if-present` turns "this workspace declares no such script" into a silent skip. An absence
+//     reading as a pass is the shape this repository refuses everywhere else.
+//
+// So the population is declared here rather than inferred from a flag, and every member of it is
+// either run or named. A corpus that was not run is a line on stdout, never an omission.
+//
+// ── THE RULE, AND THE ONE THING THAT MAY SOFTEN IT ───────────────────────────────────────────────
+//
+// A declared workspace that does not define `test:full` FAILS this command. That is the permissive
+// half of the old gate written the other way round.
+//
+// One softening, because refusing here would be a false refusal: a workspace whose tests are already
+// run by another corpus is COVERED, not missing. `providers/oauth-mcp-bridge` is a workspace with no
+// scripts block whose ten tests run every time the providers corpus does. Failing it would refuse a
+// workspace whose tests demonstrably execute, and giving it a script of its own would split one
+// corpus across two mechanisms and run those files twice.
+//
+// THE EXEMPTION IS CHECKED, NEVER TRUSTED. For each entry below, this command asserts that the
+// covering corpus's own file list actually reaches that workspace, and that the workspace has test
+// files at all. Both halves matter: an intersection with an empty set is empty, so a workspace that
+// lost its tests would satisfy a reachability check that only asked "is nothing missing". If someone
+// narrows the providers file list until it no longer reaches this workspace, the exemption stops
+// being true and this command says so instead of going quiet.
+import { spawnSync } from "node:child_process";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Every `*.test.mjs` under `providers/`, at any depth, deduplicated and ordered.
+ *
+ * RECURSIVE, AND THAT IS THE POINT. This read `providers/<dir>/test/*.test.mjs` and nothing else, one
+ * level deep — and the exemption check below counted a covered workspace's own files with the SAME
+ * shape. So a test at `providers/x/y.test.mjs`, or at `providers/x/test/sub/y.test.mjs`, was in no
+ * corpus at all, both sides missed it together and therefore agreed, and every check reported clean
+ * under a command whose whole claim is that it runs every corpus. Two derived sides sharing one
+ * assumption cannot disagree about it; that is this file's own argument, and it applied here.
+ *
+ * `node_modules` is excluded because an installed dependency's tests are not this repository's corpus.
+ * Nothing else is: a file is either collected or it is a fault, never quietly outside the shape.
+ */
+export function providerTestFiles(root = ROOT) {
+  const base = join(root, "providers");
+  if (!existsSync(base)) return [];
+  const out = new Set();
+  const walk = (dir, rel) => {
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+      if (d.name === "node_modules") continue;
+      const here = `${rel}/${d.name}`;
+      if (d.isDirectory()) walk(join(dir, d.name), here);
+      else if (d.name.endsWith(".test.mjs")) out.add(here);
+    }
+  };
+  walk(base, "providers");
+  // DEDUPLICATED ON PURPOSE. The shell form this replaced listed `providers/_shared/test/*.test.mjs`
+  // and then `providers/*/test/*.test.mjs`, which matches `_shared` as well — 51 paths for 37 files.
+  // Measured before it was called a defect: `node --test` runs a repeated path once, so the old form
+  // executed nothing twice. Building the list here makes that a property rather than a coincidence.
+  return [...out].sort();
+}
+
+/**
+ * A workspace with no `test:full`, whose tests another corpus already runs.
+ * `reaches` is the claim this command verifies on every run — not documentation.
+ */
+export const COVERED_ELSEWHERE = [
+  {
+    workspace: "providers/oauth-mcp-bridge",
+    corpus: "providers",
+    why: "a workspace for its dependencies, not for a suite of its own: its tests sit in "
+      + "providers/<name>/test like every other adapter's and run with them. A script here would "
+      + "split one corpus across two mechanisms.",
+  },
+];
+
+/**
+ * The corpora, discovered from the manifest rather than listed.
+ *
+ * `providerFiles` is injectable for one reason: the exemption check below compares the covering
+ * corpus's file list against the workspace's own directory, and if both are always read from the
+ * same place the comparison can never fail — coverage in appearance with nothing underneath. The
+ * state worth refusing is a NARROWED corpus, which is an edit to `providerTestFiles`, so an arm has
+ * to be able to hand in a narrowed list and see the refusal.
+ */
+export function plan(root = ROOT, { providerFiles } = {}) {
+  const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const workspaces = manifest.workspaces ?? [];
+  const corpora = [];
+  const faults = [];
+
+  for (const ws of workspaces) {
+    let scripts = null;
+    try { scripts = JSON.parse(readFileSync(join(root, ws, "package.json"), "utf8")).scripts ?? {}; }
+    catch { scripts = null; }
+    // A DECLARED WORKSPACE WITH NO READABLE MANIFEST IS A FAULT, not a skip. The old command could
+    // not tell this apart from a workspace that simply had nothing to run.
+    if (scripts === null) { faults.push(`${ws} is a declared workspace and its package.json could not be read`); continue; }
+
+    if (scripts["test:full"]) {
+      corpora.push({ name: ws, kind: "workspace", argv: ["npm", "run", "test:full", "-w", ws] });
+      continue;
+    }
+
+    const cover = COVERED_ELSEWHERE.find((c) => c.workspace === ws);
+    if (!cover) {
+      faults.push(`${ws} is a declared workspace and defines no \`test:full\` script. Either give it `
+        + `one, or add it to COVERED_ELSEWHERE in scripts/test-full.mjs naming the corpus that runs `
+        + `its tests — which is checked, so the claim has to be true.`);
+      continue;
+    }
+    corpora.push({ name: ws, kind: "covered", cover });
+  }
+
+  const files = providerFiles ?? providerTestFiles(root);
+  corpora.push({
+    name: "providers",
+    kind: "files",
+    files,
+    argv: ["node", "scripts/test-run.mjs", "node", "--test", ...files],
+  });
+
+  // ── THE EXEMPTIONS, CHECKED ────────────────────────────────────────────────────────────────────
+  for (const c of corpora.filter((x) => x.kind === "covered")) {
+    const covering = corpora.find((x) => x.name === c.cover.corpus);
+    if (!covering || !Array.isArray(covering.files)) {
+      faults.push(`${c.name} is recorded as covered by the \`${c.cover.corpus}\` corpus, and this `
+        + `command has no such corpus with a file list to check that against.`);
+      continue;
+    }
+    const own = covering.files.filter((f) => f.startsWith(c.name + "/"));
+    // BOTH HALVES. A workspace that lost its own tests would pass a check that only asked whether
+    // the covering corpus was missing any of them, because nothing is missing from nothing.
+    const here = existsSync(join(root, c.name, "test"))
+      ? readdirSync(join(root, c.name, "test")).filter((f) => f.endsWith(".test.mjs")).length : 0;
+    if (!here) {
+      faults.push(`${c.name} is recorded as covered by the \`${c.cover.corpus}\` corpus, but it has `
+        + `no test files of its own, so that claim covers nothing. Remove the entry or restore the tests.`);
+    } else if (own.length !== here) {
+      faults.push(`${c.name} is recorded as covered by the \`${c.cover.corpus}\` corpus, which reaches `
+        + `${own.length} of its ${here} test file(s). The exemption is no longer true.`);
+    }
+    c.reaches = own.length;
+    c.hasTests = here;
+  }
+
+  return { corpora, faults };
+}
+
+function main() {
+  const only = (() => { const i = process.argv.indexOf("--only"); return i === -1 ? null : process.argv[i + 1]; })();
+  const listOnly = process.argv.includes("--list");
+  const { corpora, faults } = plan();
+
+  // FAULTS BEFORE ANYTHING RUNS. A missing corpus discovered after a green suite reads as an
+  // afterthought; discovered first, it is the answer.
+  if (faults.length) {
+    console.error(`\ntest-full: ${faults.length} declared workspace(s) this command cannot account for:\n`);
+    for (const f of faults) console.error(`  - ${f}`);
+    console.error("");
+    process.exit(1);
+  }
+
+  const chosen = only ? corpora.filter((c) => c.name === only || c.name.endsWith("/" + only)) : corpora;
+  if (only && !chosen.length) {
+    console.error(`test-full: no corpus named ${only}. Known: ${corpora.map((c) => c.name).join(", ")}`);
+    process.exit(2);
+  }
+
+  if (listOnly) {
+    for (const c of chosen) {
+      console.log(c.kind === "covered"
+        ? `  ${c.name}: covered by the ${c.cover.corpus} corpus (${c.reaches}/${c.hasTests} file(s))`
+        : `  ${c.name}: ${c.kind === "files" ? `${c.files.length} file(s)` : "workspace script"}`);
+    }
+    return;
+  }
+
+  const ran = [];
+  for (const c of chosen) {
+    if (c.kind === "covered") { ran.push({ ...c, status: "covered" }); continue; }
+    console.log(`\n──── ${c.name} ────`);
+    // STDIO INHERITED, NOT CAPTURED. CI reads the child stream for the corpus-guard markers, and a
+    // runner that buffered its children would take those markers out of the log the check greps.
+    const r = spawnSync(c.argv[0], c.argv.slice(1), { cwd: ROOT, stdio: "inherit" });
+    ran.push({ ...c, status: r.status === 0 ? "ok" : "FAILED", code: r.status });
+  }
+
+  // ── THE SUMMARY, AT THE END, ON STDOUT ─────────────────────────────────────────────────────────
+  // The point of the whole file. A reader who scrolls to the bottom of a long run sees every corpus
+  // this command knows about and what became of it, so "the full suite is green" is a claim they can
+  // check rather than one they have to trust.
+  console.log(`\n──── what test-full ran ────`);
+  for (const c of ran) {
+    if (c.status === "covered") {
+      console.log(`  covered  ${c.name} — ${c.hasTests} file(s), run by the ${c.cover.corpus} corpus: ${c.cover.why}`);
+    } else {
+      const n = c.kind === "files" ? `${c.files.length} file(s)` : "workspace suite";
+      console.log(`  ${c.status === "ok" ? "ran    " : "FAILED "}  ${c.name} — ${n}${c.code ? ` (exit ${c.code})` : ""}`);
+    }
+  }
+  const bad = ran.filter((c) => c.status === "FAILED");
+  console.log(bad.length ? `\n${bad.length} corpus/corpora failed.` : `\nEvery corpus above was run or accounted for.`);
+  if (bad.length) process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/shared/README.md

@@ -25,7 +25,8 @@ resolves the running commit for artifact provenance, but it cannot be the shared
 | `listen.mjs` | The one place a bind failure becomes a sentence rather than a stack trace. |
 | `driver-dir.mjs` | Where a run's `_driver/` is: the name, the path, and the one creation call. Product code no longer builds it by hand, so the directory's location — and one day its mode — is a decision in one place rather than a convention in 1123. |
 | `site-nav.mjs`, `anon-overlay.mjs` | The single top nav shared by the internal staff pages, and the display-only overlay that masks client names and marks so those pages can be screen-shared. |
-| `identifier-scan.mjs`, `identifier-blocklist.mjs`, `vetted-identities.mjs` | One matcher, one name table, one list of declared exceptions — shared by the guard that sweeps the tracked tree and the scan that sweeps the whole history. |
+| `identifier-scan.mjs`, `identifier-sentinels.mjs`, `vetted-identities.mjs` | One matcher, one name table, one list of declared exceptions — shared by the guard that sweeps the tracked tree and the scan that sweeps the whole history. The real table is private; the sentinels are what make a zero from that sweep mean something. |
+| `reference-guard-classes.mjs` | What a public tree must not acquire, as one table: citations, account names, home directories on the build machines, private repository names, this project's own words for how it is organised, and both attribution trailers. Read by the diff guard in `scripts/added-reference-check.mjs` and by the per-file floor beside it. |
 
 `brand/assets/` holds the vendored logo SVGs. `tools/` holds the two brand-system generators — see
 [`tools/README.md`](tools/README.md).

package/shared/browser-temp-root.mjs

@@ -0,0 +1,142 @@
+// 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
+// browser-temp-root.mjs — give a browser launch its own temp root, so an untidy exit leaks nothing shared.
+//
+// ── WHAT LEAKS, AND WHY IT IS NOT THE PROFILE DIRECTORY ───────────────────────────────────────────
+//
+// Chrome does not keep its process-singleton lock in `--user-data-dir`. It creates a directory named
+// `com.google.Chrome.XXXXXX` in the system temp directory, holding `SingletonCookie` and a
+// `SingletonSocket` unix socket, and symlinks the profile's entry at it. The reason is length: a
+// profile path may be too long for a unix socket, so the lock is shortened through the temp root.
+//
+// Every launcher here already removes its own profile directory. None of them could remove that one,
+// because none of them knows its name. Measured on a development machine 2026-09-09: 4,855 such
+// directories under one shared temp root, the oldest five days old, still accumulating — the residue
+// of runs that ended without running their cleanup, mostly cancelled continuous-integration jobs.
+//
+// The fix is not to find and delete them. It is to stop them being shared: the directory is created in
+// `GetTempDir()`, which honours `TMPDIR`, so a run that exports its own temp root gets its own copy of
+// the lock inside it and takes it away when the root goes.
+//
+// ── THE BYTE BUDGET, WHICH IS WHY THIS FILE REFUSES RATHER THAN TRUSTS ────────────────────────────
+//
+// A unix socket address is a fixed 108-byte field, so the socket path must fit in 107 bytes plus a
+// terminator. The lock directory and socket name add a fixed 41 characters to the temp root, leaving
+// 66 for the root itself. One character more and Chrome does not degrade — it aborts, with a fatal
+// log line about the socket path and a core dump.
+//
+// That failure is why the check below exists. A crash in a continuous-integration step, reported as a
+// core dump, is not something a reader connects to the length of a checkout path; and the length is
+// not a constant of this project, because a run can be rooted anywhere a caller or a runner puts it.
+// So the budget is asserted at the point the root is chosen, and the refusal states the length it
+// measured, the limit, and the path — which is the whole of what a reader needs to fix it.
+//
+// The boundary is measured, not derived: walking root lengths across it, 66 starts and 67 aborts.
+import { mkdtempSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeOnExit } from "./reap-on-exit.mjs";
+
+/** A unix socket address field is 108 bytes; the last is the terminator. */
+export const SUN_PATH_MAX = 107;
+
+/** `/com.google.Chrome.XXXXXX/SingletonSocket` — what the lock adds to the temp root. */
+export const LOCK_SUFFIX = "/com.google.Chrome.XXXXXX/SingletonSocket";
+
+/** The longest temp root a browser can be launched under. */
+export const MAX_ROOT_LENGTH = SUN_PATH_MAX - LOCK_SUFFIX.length;
+
+/**
+ * The root's own prefix, and it is SHORT ON PURPOSE — this is the one lever on the budget.
+ *
+ * Every character here is spent on every browser run, and roots nest: under the suite runner the
+ * ambient temp directory already carries one `ct-testrun-XXXXXX` level before this is appended.
+ * Measured on a development machine 2026-09-09, ambient temp 18 characters:
+ *
+ *              root length     worst case with a 22-character name in the root   with this prefix
+ *   ambient        18                       47  (19 to spare)                     29  (37 to spare)
+ *   one runner     36                       65  (ONE to spare)                    47  (19 to spare)
+ *   nested         54                       83  (refuses)                         65  (1 to spare)
+ *
+ * The middle row is why this is not cosmetic. Naming the root after the check spent the budget on a
+ * label, and left an ordinary single-level suite run one character from refusing — a host with a
+ * temp directory one character longer, or this one renamed a level deeper, and every browser check
+ * would refuse at once while the tree looked broken. So the root is named for what it IS, and the
+ * check that made it is named by the directory INSIDE it, where length costs nothing.
+ *
+ * A leaked root is still sweepable by name, which was the point of naming it at all, and now it is
+ * attributable too: open it and the profile directory says which check left it.
+ */
+export const ROOT_PREFIX = "ctb-";
+
+/**
+ * Why `dir` cannot be a browser temp root, or `null` if it can.
+ *
+ * Returned rather than thrown so a caller can decide: a check that has already produced a result
+ * should say this and exit, not lose the result to an exception.
+ */
+export function rootRefusal(dir) {
+  if (typeof dir !== "string" || dir === "") return "a browser temp root must be a non-empty path";
+  if (dir.length <= MAX_ROOT_LENGTH) return null;
+  return (
+    `browser temp root is ${dir.length} characters and the limit is ${MAX_ROOT_LENGTH}: ${dir}\n` +
+    `  A browser writes its process-singleton socket at <root>${LOCK_SUFFIX}, and a unix socket ` +
+    `address holds ${SUN_PATH_MAX} characters. Over that the browser aborts with a fatal error about ` +
+    `the socket path rather than reporting anything this check could read.\n` +
+    `  Run from a shorter path, or set TMPDIR to one.`
+  );
+}
+
+/** The refusal as an exception, for a caller with nothing to lose by throwing. */
+export function assertRootFits(dir) {
+  const why = rootRefusal(dir);
+  if (why) throw new Error(why);
+  return dir;
+}
+
+/**
+ * A temp root for one browser run, removed when this process exits by any route it can observe.
+ *
+ * Rooted at the ambient temp directory rather than anywhere relative to the checkout, and that is a
+ * decision rather than a convenience: the ambient root is short by construction, while a checkout,
+ * a worktree or a per-session scratch directory is routinely past the budget above. Nesting is
+ * still correct — under a test runner that has already exported its own root, this lands inside it
+ * and is carried away with it.
+ */
+export function browserTempRoot() {
+  const root = mkdtempSync(join(tmpdir(), ROOT_PREFIX));
+  assertRootFits(root);
+  removeOnExit(root);
+  return root;
+}
+
+/**
+ * The environment a browser must be spawned with so its singleton lock lands under `root`.
+ *
+ * `TMPDIR` is the whole mechanism, so this refuses rather than passing a root that cannot work.
+ */
+export function browserEnv(root, env = process.env) {
+  assertRootFits(root);
+  return { ...env, TMPDIR: root };
+}
+
+/**
+ * A temp root and a profile directory inside it, plus the environment to spawn with.
+ *
+ * The profile goes INSIDE the root so one removal covers both. Several call sites used to make the
+ * profile directly in the shared temp directory and remove it on their success path; that left the
+ * singleton lock behind on every other path, which is the leak this module exists for.
+ */
+export function browserRun(label = "browser") {
+  const root = mkdtempSync(join(tmpdir(), ROOT_PREFIX));
+  assertRootFits(root);
+  const keep = removeOnExit(root);
+  // The CALLER'S NAME GOES HERE, inside the root, where it costs nothing against the socket budget.
+  // Callers pass the name they used to prefix the root with, trailing dash and all, so this reads as
+  // `<root>/home-check` and an operator opening a leaked root learns which check left it.
+  const profile = join(root, label.replace(/-+$/, "") || "browser");
+  mkdirSync(profile, { recursive: true });
+  // `keep` deregisters the root from the exit sweep. A caller with a `--keep` flag MUST call it, or
+  // the flag reads as working while the directory it promised goes at exit.
+  return { root, profile, env: browserEnv(root), keep };
+}

package/shared/checkout-move.mjs

@@ -9,7 +9,7 @@
 // so that one line decides which tree the whole deployment executes — and connect said nothing about
 // having written it.
 //
-// Driven on testuser: a lane made a worktree to test a branch, ran `connect` from it once, and
+// Driven on the test deployment: a lane made a worktree to test a branch, ran `connect` from it once, and
 //
 //   · the next deploy tick fast-forwarded the DETACHED worktree and failed with "You are not currently
 //     on a branch" — a message about branches, for a box that was silently a merge behind; and