clearotron 0.2.2 → 0.2.4

package/scripts/generated-files-are-current.mjs

@@ -0,0 +1,125 @@
+#!/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
+//
+// EVERY GENERATED FILE IN THIS TREE IS CURRENT, or this says which one is not.
+//
+//   node scripts/generated-files-are-current.mjs
+//
+// ── WHY THIS EXISTS, AND WHY IT DISCOVERS ITS OWN POPULATION ─────────────────────────────────────
+//
+// Each `scripts/mint-*.mjs` writes a file that is committed and derived, and each takes `--check` to
+// say whether the committed copy still matches the tree. Until now CI ran exactly one of them. The
+// other three could go stale on `main` and nothing here would say so — the failure surfaced instead
+// in a private control that refuses to start on a stale fixture, which is the most expensive place
+// to learn it and the furthest from whoever caused it.
+//
+// So this enumerates `scripts/mint-*.mjs` rather than naming them. A list would have to be extended
+// by whoever adds the fifth minter, and the whole reason the fourth went unchecked is that nobody
+// extended anything. A discovered population is covered by construction.
+//
+// AN EMPTY POPULATION IS A FAULT, NOT A PASS. If the glob matches nothing, this file has been moved
+// or the naming convention has changed, and reporting "all current" over zero checks is exactly the
+// shape of green this guard exists to refuse.
+import { readdirSync } from "node:fs";
+import { spawnSync, execFileSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, "..");
+
+/** Every minter in `scripts/`, by filename, ordered. */
+export function minters(dir = HERE) {
+  return readdirSync(dir).filter((f) => f.startsWith("mint-") && f.endsWith(".mjs")).sort();
+}
+
+/**
+ * What the working tree looks like, so a minter that WROTE during `--check` can be caught writing.
+ *
+ * Returns null when the tree cannot be read — outside a checkout, say — and a null is carried as a
+ * stated limit rather than as a pass: the contract simply goes unchecked and the run says so.
+ */
+export function treeState(root = ROOT) {
+  try {
+    return execFileSync("git", ["-C", root, "status", "--porcelain"], { encoding: "utf8", maxBuffer: 1 << 28 });
+  } catch { return null; }
+}
+
+/**
+ * Run every minter's `--check` and sort the answers.
+ *
+ * `dir` and `root` are parameters so the arms can drive all three outcomes over throwaway minters.
+ * The alternative — dirtying a real generated file and restoring it — is a shared-file mutation, and
+ * the test runner runs files in parallel, so it would be a race that reddens somebody else's arm.
+ */
+export function checkAll({ dir = HERE, root = ROOT, log = console.log, readTree = () => treeState(root) } = {}) {
+  const found = minters(dir);
+  if (!found.length) return { found, stale: [], unreadable: [], wrote: [], empty: true };
+
+  const stale = [];
+  const unreadable = [];
+  const wrote = [];
+  for (const m of found) {
+    // ── `--check` IS A CONTRACT, AND NOTHING WAS VERIFYING IT ──────────────────────────────────────
+    //
+    // Every minter here is trusted to treat `--check` as "report, change nothing". A minter that
+    // ignores the flag and re-mints repairs the drift and then reports `current` — so the file is
+    // quietly fixed on whoever's machine ran it, the commit does not carry the repair, and this guard
+    // logs a clean line over a check that never happened. That is this file's own sentence one level
+    // in: a pass from a minter that did not look is not a pass either.
+    //
+    // The probe is the contract stated directly. `--check` must not write, so if the tree moved while
+    // one ran, it wrote. THE LIMIT, SAID RATHER THAN LEFT: this catches the harmful inert form, the
+    // one that silently repairs. A minter that ignores the flag and does nothing at all still reports
+    // `current`, and no probe from out here can tell that from a file that really is current.
+    const before = readTree();
+    const r = spawnSync(process.execPath, [join(dir, m), "--check"], { cwd: root, encoding: "utf8" });
+    const after = readTree();
+    const out = ((r.stdout || "") + (r.stderr || "")).trim();
+    if (before !== null && after !== null && before !== after) {
+      wrote.push({ m, out });
+      log(`  WROTE    ${m} (during --check)`);
+      continue;
+    }
+    // 0 is current, 1 is stale, anything else is a minter that could not look — reported separately,
+    // because "I could not read the tree" and "the file is out of date" need different things done.
+    if (r.status === 0) { log(`  current  ${m}`); continue; }
+    if (r.status === 1) { stale.push({ m, out }); log(`  STALE    ${m}`); continue; }
+    unreadable.push({ m, out, code: r.status });
+    log(`  ?        ${m} (exit ${r.status})`);
+  }
+  return { found, stale, unreadable, wrote, empty: false, contractChecked: readTree() !== null };
+}
+
+function main() {
+  const { found, stale, unreadable, wrote, empty, contractChecked } = checkAll();
+  if (empty) {
+    console.error("generated-files-are-current: no scripts/mint-*.mjs found. Either they moved or the "
+      + "naming changed — and a pass over nothing is not a pass.");
+    process.exit(2);
+  }
+  console.log(`\ngenerated-files-are-current: checked ${found.length} minter(s)`
+    + (contractChecked ? "" : "; the tree could not be read, so nothing verified that `--check` changed nothing"));
+
+  for (const { m, out } of [...wrote, ...stale, ...unreadable]) {
+    console.error(`\n──── ${m} ────\n${out}`);
+  }
+  if (wrote.length) {
+    console.error(`\n${wrote.length} minter(s) CHANGED THE TREE while running \`--check\`. \`--check\` `
+      + `reports and changes nothing; one that re-mints repairs the drift on whoever ran it, leaves the `
+      + `commit without the repair, and reports current over a check that did not happen. Fix the minter.`);
+    process.exit(2);
+  }
+  if (unreadable.length) {
+    console.error(`\n${unreadable.length} minter(s) could not look. That is not a pass; fix the minter first.`);
+    process.exit(2);
+  }
+  if (stale.length) {
+    console.error(`\n${stale.length} generated file(s) are out of date. Re-mint each one named above and `
+      + `commit the result — a derived file that drifts is a check reporting on a tree that no longer exists.`);
+    process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/scripts/live-surface-check.mjs

@@ -90,7 +90,7 @@ import { unitsActiveVerdict } from "../driver/unit-state-verdict.mjs";
 import { deploymentBox } from "../shared/deployment-box.mjs";   // — extracted; one allowlist, two readers
 import { unitFileDriftVerdict } from "../driver/unit-file-drift.mjs";   //
 import { placeholdersIn, resolveValues, renderUnit } from "../driver/systemd/render-units.mjs";   //
-import { CHECKED_UNITS, unitInventoryVerdict, serviceCommitVerdict, unitWorkingDirectory, unitClone } from "../driver/unit-inventory.mjs";   // · -bundle ·
+import { CHECKED_UNITS, CHECKED_TIMERS, timerVerdict, unitInventoryVerdict, serviceCommitVerdict, unitWorkingDirectory, unitClone } from "../driver/unit-inventory.mjs";   // · -bundle ·
 import { entrypointOf } from "../driver/systemd/install-census.mjs";   // the ONE ExecStart parser — a unit says which module it runs
 import { treeOfRunning } from "../shared/checkout-move.mjs";           // …and the live argv says which tree that module came from
 import { findUnitFiles, unitFilePath } from "../driver/unit-files.mjs";   //
@@ -226,6 +226,35 @@ function userBusEnv() {
 // Returns {clones, probe}. `probe` is the honest answer to "could I look at all?" — {ok, why} — and it is
 // SEPARATE from the clones list on purpose. "enumerated, nothing to compare" and "could not enumerate"
 // were the same empty array before, and this suite exists because absences were read as successes.
+/**
+ * Ask each declared TIMER about itself, as a timer.
+ *
+ * Deliberately not folded into the loop below. That loop asks a service for its WorkingDirectory and
+ * MainPID and attributes a running process to a checkout — none of which a `.timer` has, so putting
+ * timers through it would produce rows whose every attribution field is empty for a reason that is not
+ * a finding. Two questions, two calls, and each says what it could not answer.
+ */
+function declaredTimers() {
+  if (!CHECKED_TIMERS.length) return { rows: [], probeFailed: null };
+  const env = userBusEnv();
+  const rows = [];
+  let probeFailed = null;
+  for (const unit of CHECKED_TIMERS) {
+    try {
+      const shown = execFileSync("systemctl", ["--user", "show", unit, "-p", "ActiveState", "-p", "LoadState"],
+        { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] });
+      const f = Object.fromEntries(shown.split("\n").filter(Boolean).map((l) => { const [k, ...v] = l.split("="); return [k, v.join("=")]; }));
+      // An EMPTY answer is the no-session-bus case, and it must not read as a stopped timer — that is
+      // the shape that turns "could not ask" into a finding about the box.
+      if (!f.ActiveState) { probeFailed = probeFailed ?? `systemctl --user answered nothing for ${unit}`; continue; }
+      rows.push({ unit, active: f.ActiveState || null, load: f.LoadState || null });
+    } catch (e) {
+      probeFailed = probeFailed ?? String(e?.message ?? e).slice(0, 120);
+    }
+  }
+  return { rows, probeFailed };
+}
+
 function serviceClones() {
   // — the list is DECLARED, not written here. It used to be eight names inline, which put a unit
   // inside the drift guarantee or outside it by omission: `client-access` was live on production and in
@@ -889,6 +918,14 @@ else {
   const v = unitInventoryVerdict({ live: liveUnits, files: walk.files, collisions: walk.collisions,
     filesError: walk.error, box, probe });
   record("every live unit is declared", v.state, v.message);
+
+  // — AND WHETHER ANYTHING STILL STARTS THE TIMER-DRIVEN ONES. Reported separately from the line above
+  // because it answers a different question: that one says a declared unit exists and is not adrift,
+  // this one says its timer is still armed. A service whose timer was stopped satisfies the first and
+  // fails the second, and reads `inactive` for both — which is why one line could not carry both.
+  const t = declaredTimers();
+  const tv = timerVerdict(t.rows, { probeFailed: t.probeFailed });
+  record("every declared timer is still armed", tv.state, tv.message);
 }
 
 // ── — EVERY QUEUE THIS DEPLOYMENT WOULD DRAIN IS WATCHED BY SOMETHING ──────────────────────────

package/scripts/mint-names-in-force.mjs

@@ -21,7 +21,7 @@
 // ── THE ORACLE THIS DERIVATION IS CHECKED AGAINST ────────────────────────────────────────────────
 //
 // A derivation that is only ever compared against itself proves nothing, which is the shape this repo
-// keeps paying for. So the arm in driver/test/retired-env-spellings.test.mjs holds this output to the
+// keeps paying for. So scripts/generated-files-are-current.mjs, in CI's guards job, holds this output to the
 // THIRTEEN dead names Cart measured in the production install's own env file on 2026-09-05 — a
 // population this script never saw and cannot influence. All thirteen must resolve to a replacement.
 // If a future sweep breaks the suffix rule, that arm reds on real-world data rather than on a
@@ -82,7 +82,9 @@ function render(names) {
 //
 //   node scripts/mint-names-in-force.mjs
 //
-// driver/test/retired-env-spellings.test.mjs regenerates this and refuses a stale copy.
+// CI refuses a stale copy, from the guards job: scripts/generated-files-are-current.mjs runs every
+// minter in scripts/ with --check. (This line used to name a test file that does not exist in this
+// tree, so the only thing that ever caught this drifting was a private control refusing to start.)
 
 export const NAMES_IN_FORCE = Object.freeze([
 ${names.map((n) => `  "${n}",`).join("\n")}

package/scripts/mint-public-residue.mjs

@@ -0,0 +1,74 @@
+#!/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
+//
+// RE-MINT THE PUBLIC RESIDUE BACKLOG — the per-file, per-class count that may only go down.
+//
+//   node scripts/mint-public-residue.mjs            # report the delta, change nothing
+//   node scripts/mint-public-residue.mjs --check    # ... and exit 1 if the file is out of date
+//   node scripts/mint-public-residue.mjs --apply    # write it
+//
+// THE ONLY REASON TO RUN `--apply` IS THAT THE NUMBER WENT DOWN. Nothing here refuses to write a
+// higher one — a table that could not record growth would be unable to describe a tree somebody
+// widened a class over — but the floor arm in driver/test/the-public-residue-is-a-floor.test.mjs
+// refuses the growth itself, and it reads the committed file rather than this script's output. So an
+// author who mints upward has recorded the regression rather than absorbed it, and the suite says so
+// on the next run. The two halves are deliberately not the same program.
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLASSES, censusOf, publishedOf } from "../shared/reference-guard-classes.mjs";
+import { trackedFiles, skipReason } from "../shared/tracked-files.mjs";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const FIXTURE = join(ROOT, "driver/test/fixtures/public-residue-backlog.json");
+const GUARD = "public-residue-backlog";
+
+/** The tree's current census, as the fixture records it. */
+export function mint() {
+  const tracked = trackedFiles(GUARD, { root: ROOT });
+  if (tracked === null) return null;
+  // THE SAME POPULATION THE FLOOR READS, from the same helper. A mint over the index and a floor over
+  // HEAD would disagree under the overlay, and `--check` would report a difference that is only the
+  // two instruments asking different questions.
+  const p = publishedOf(tracked, ROOT);
+  if (p.error) { console.error(`mint-public-residue: ${p.error}`); process.exit(2); }
+  if (p.laid) console.log(`mint-public-residue: ${p.laid} tracked path(s) are not in HEAD — laid over this checkout, not published in it, and not counted`);
+  const c = censusOf(p.files, (f) => readFileSync(join(ROOT, f), "utf8"));
+  return { classes: CLASSES.map((x) => x.id), total: c.total, files: c.files };
+}
+
+/** Per-class totals, for a reader who wants to know WHICH number moved. */
+export const byClass = (table) =>
+  CLASSES.map((c, i) => [c.id, Object.values(table.files).reduce((a, v) => a + v[i], 0)]);
+
+function main() {
+  const apply = process.argv.includes("--apply");
+  const check = process.argv.includes("--check");
+
+  const now = mint();
+  // A COULD-NOT-LOOK EXITS 2, never 0. Outside a checkout there is no corpus, and a mint that wrote an
+  // empty table here would replace the whole backlog with nothing and call it a repair.
+  if (now === null) { console.error(`mint-public-residue: ${skipReason(GUARD)}`); process.exit(2); }
+
+  let was = null;
+  try { was = JSON.parse(readFileSync(FIXTURE, "utf8")); } catch { /* first mint */ }
+
+  console.log(`public residue: ${now.total} line(s) across ${Object.keys(now.files).length} file(s)`);
+  for (const [id, n] of byClass(now)) console.log(`  ${String(n).padStart(5)}  ${id}`);
+
+  const next = JSON.stringify(now, null, 2) + "\n";
+  const same = was && JSON.stringify(was, null, 2) + "\n" === next;
+  if (same) { console.log("the backlog is current"); return; }
+
+  if (was) {
+    const delta = now.total - was.total;
+    console.log(`\ntotal ${was.total} → ${now.total} (${delta >= 0 ? "+" : ""}${delta})`);
+  }
+  if (apply) { writeFileSync(FIXTURE, next); console.log("written"); return; }
+  console.log("\nre-run with --apply to write it");
+  if (check) process.exit(1);
+}
+
+if (isEntrypoint(import.meta.url)) main();

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/nightly-notice.mjs

@@ -151,8 +151,6 @@ export function noticeBody({ runUrl, sha, subject, failedJobs = [], lastGreenAt,
         + "passes — a run that never started cannot make the platform green."
       : "This thread is reused for every red night. Close it once the platform is green again — the next "
         + "red opens a new one.",
-    "",
-    "Agent: role-dev · bergface",
   ].join("\n");
 }
 

package/scripts/preinstall-node-check.mjs

@@ -0,0 +1,24 @@
+// 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
+//
+// The install refuses an unsupported Node BEFORE anything is written — tracker issue 364.
+//
+// Three declarations already stated the requirement and none of them bound anyone: `engines.node` is a
+// WARNING unless the person installing has set `engine-strict`, `.nvmrc` is read by nvm and nothing
+// else, and the install guide is prose. An outside report arrived as "some node issues, not as obvious
+// as the README made it seem" — which is what a warning inside an install log looks like from outside.
+//
+// So this is a `preinstall` hook, node builtins only, because nothing is installed when it runs.
+//
+// IT NAMES THE LATER FAILURE, not just the version. The whole defect is that an unsupported Node
+// installs cleanly and then fails somewhere else saying nothing about Node, so a message that only
+// prints a semver range leaves the reader where they started.
+import { declaredRange, floorOf, meetsFloor, nodeFloorRefusal } from "../shared/node-floor.mjs";
+
+const range = declaredRange();
+if (!meetsFloor(process.versions.node, floorOf(range))) {
+  process.stderr.write(`\n${nodeFloorRefusal({ current: process.versions.node, required: floorOf(range).join("."), range })}\n`);
+  process.stderr.write("  Nothing has been installed.\n\n      nvm install 22 && nvm use 22\n\n");
+  process.stderr.write("  Without nvm, take the current 22.x from https://nodejs.org/.\n\n");
+  process.exit(1);
+}

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";
 
@@ -77,6 +78,15 @@ export const EXCLUDED = [
   "driver/test/a-bare-reference-added-in-a-diff-is-refused.test.mjs",
   "driver/test/prompt-payload-names-no-tracker-issue.test.mjs",
   "driver/test/euipo-environment-doctrine.test.mjs",
+  // THIS RULE'S OWN DEFINITION, and it caught itself. Both files below QUOTE the residue in order to
+  // define it — the specimens the sweep is tested against, and the worked examples in the header above.
+  // Sweeping them rewrites the corpus this instrument is checked by, and it would then pass on something
+  // it had stopped checking: the arms would assert that a stripped line equals a stripped line. The
+  // sibling module that counts the earlier strip's residue learned the same lesson and names its own
+  // three files for the same reason. Found by running the sweep after fixing its report, which is the
+  // only reason it surfaced: before that, these lines were counted and never listed.
+  "scripts/strip-tracker-citations.mjs",
+  "driver/test/the-citation-strip-removes-openers-and-nothing-else.test.mjs",
   // Pinned at a content hash; a prose repair is not worth spending a freeze on.
   "driver/publish/render.mjs",
 ];
@@ -86,28 +96,49 @@ export const isScannable = (f) =>
 
 /** Per-file classification. PURE, and `read` is injected so an arm can drive it over a synthetic tree. */
 export function surveyOf(files, read) {
-  const stripped = {}, handoff = [];
+  const stripped = {}, handoff = [], unreadable = [];
   let strippedTotal = 0, remainingTotal = 0;
   for (const f of files.filter(isScannable)) {
     let text;
-    try { text = read(f); } catch { continue; }
+    // AN UNREADABLE FILE IS A FINDING, NOT A QUIET SKIP. This used to `continue` into no counter and no
+    // error channel, so "I could not open this" and "there was nothing to do here" produced identical
+    // output — in the report whose whole job is to tell somebody a hundred-file rewrite is safe. The
+    // count is reported before anything else when it is non-zero.
+    try { text = read(f); } catch (e) { unreadable.push({ file: f, why: String(e?.message ?? e).slice(0, 120) }); continue; }
     let n = 0;
+    // CLASSIFY AFTER REPLACING, NOT INSTEAD OF IT. The replacement is not global, so a line carrying an
+    // opener AND a second citation further along was stripped once, counted as done, and never reached
+    // the hand-off list a person is told to read — its survivor was invisible in the one place it should
+    // have been named. Test the RESULT: a line can be both stripped and still owed to a reader.
     const out = text.split("\n").map((line, i) => {
-      if (OPENER.test(line)) { n++; return line.replace(OPENER, "$1"); }
-      if (ANY_CITATION.test(line)) handoff.push({ file: f, line: i + 1, text: line.trim() });
-      return line;
+      const after = OPENER.test(line) ? (n++, line.replace(OPENER, "$1")) : line;
+      if (ANY_CITATION.test(after)) handoff.push({ file: f, line: i + 1, text: after.trim() });
+      return after;
     });
     if (n) { stripped[f] = n; strippedTotal += n; }
     remainingTotal += out.filter((l) => ANY_CITATION.test(l)).length;
     if (APPLY && n) writeFileSync(join(ROOT, f), out.join("\n"));
   }
-  return { strippedTotal, remainingTotal, stripped, handoff };
+  return { strippedTotal, remainingTotal, stripped, handoff, unreadable };
 }
 
 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) {
+    console.log(`${s.unreadable.length} file(s) COULD NOT BE READ — every count below excludes them:`);
+    for (const u of s.unreadable) console.log(`  ${u.file}  ${u.why}`);
+    console.log("");
+  }
   console.log(`${APPLY ? "stripped" : "would strip"} ${s.strippedTotal} opener(s) across ${Object.keys(s.stripped).length} file(s)`);
   console.log(`${s.handoff.length} citation(s) are NOT openers and need a reader — the hand-off list:`);
   for (const h of s.handoff) console.log(`  ${h.file}:${h.line}  ${h.text.slice(0, 110)}`);