clearotron 0.3.0-beta.1 → 0.3.0-beta.2

package/portal-ui/dist/assets/{index-KpytsmNH.css → index-CsCuPshD.css}

@@ -2049,9 +2049,14 @@ input.filter {
   cursor: not-allowed;
 }
 
-/* the sentence that replaces the Stop button while a stop is in flight. */
-.home2-stopping {
+/* The sentence that replaces the Stop button while a stop is in flight.
+   ITS OWN ROW, BELOW THE FOOT, not a flex item inside it. `home2-card-foot` is a flex row of short
+   things — the elapsed line and one button — and this is a paragraph. As a member of that row it
+   squeezed "1 min so far" into a two-character column and the card read as garbled on a real run. */
+.home2-stop-note {
+  margin-top: 10px;
   font-size: 12px;
+  line-height: 1.5;
   color: var(--text-muted);
   font-style: italic;
 }

package/portal-ui/dist/index.html

@@ -49,8 +49,8 @@
     -->
     <link rel="preconnect" href="https://api.fontshare.com" crossorigin />
     <link href="https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700,900&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/portal/assets/index-CWTHP0sH.js"></script>
-    <link rel="stylesheet" crossorigin href="/portal/assets/index-KpytsmNH.css">
+    <script type="module" crossorigin src="/portal/assets/index-CcFjgM78.js"></script>
+    <link rel="stylesheet" crossorigin href="/portal/assets/index-CsCuPshD.css">
   </head>
   <body>
     <div id="root"></div>

package/portal-ui/package.json

@@ -2,17 +2,17 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.2",
   "license": "AGPL-3.0-only",
   "description": "The unified trademark portal UI. One address, one login: who you are decides what you see. Built as a static bundle, served by driver/portal-service.mjs — the browser never reaches profile-service or recipe-service.",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13.0"
   },
   "scripts": {
     "build": "vite build",
     "dev": "vite",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && node ../scripts/test-run.mjs node --test test/*.test.ts",
+    "test": "npm run typecheck && node ../scripts/test-run.mjs node --experimental-strip-types --test test/*.test.ts",
     "test:full": "npm run test"
   },
   "dependencies": {

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

@@ -1,5 +1,9 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.0-beta.2
+
+No changes in this release.
+
 ## 0.3.0-beta.1
 
 No changes in this release.

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

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.2",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "OAuth 2.1 MCP stdio bridge used by the engine's case-law gather stage (courtlistener / legaldatahunter).",
@@ -9,5 +9,5 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
-  "engines": { "node": ">=22" }
+  "engines": { "node": ">=22.13.0" }
 }

package/scripts/changelog-plain-language.mjs

@@ -17,48 +17,25 @@
 // to who wrote the line.
 import { readFileSync } from "node:fs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+import { lineFindings, sourceDirectories, userDocs } from "./plain-language-rules.mjs";
 
-// The four the issue names, plus the two spellings each of the -ise/-ize pair it names once. A word
-// list is checked whole: "implementation" is jargon, "implement" inside "implemented" is the same word,
-// but "complement" is not, which is why this is a boundary match and not a substring one.
-export const BANNED_WORDS = [
-  "refactor", "refactors", "refactored", "refactoring",
-  "implement", "implements", "implemented", "implementing", "implementation", "implementations",
-  "leverage", "leverages", "leveraged", "leveraging",
-  "optimise", "optimises", "optimised", "optimising", "optimisation",
-  "optimize", "optimizes", "optimized", "optimizing", "optimization",
-  "utilise", "utilises", "utilised", "utilising", "utilisation",
-  "utilize", "utilizes", "utilized", "utilizing", "utilization",
-];
+// THE RULES live in plain-language-rules.mjs, shared with the note lint, so a note CI passes cannot turn
+// this gate red after the merge. BANNED_WORDS is re-exported for the callers that read it from here.
+export { BANNED_WORDS } from "./plain-language-rules.mjs";
 
-// A FILE NAME is the thing a reader cannot act on: they do not have the tree open. Matched by
-// extension, because a bare word with a dot in it is how every file name in this repository reads.
-const FILE_NAME_RE = /\b[\w.-]+\.(mjs|js|cjs|ts|tsx|jsx|json|yml|yaml|md|sh|txt)\b/g;
-// A PATH, with or without an extension: two segments joined by a slash.
-const PATH_RE = /\b[\w.-]+\/[\w./-]+/g;
-// A FUNCTION NAME, in the two shapes this tree writes them: a call, and a bare camelCase identifier.
-const FUNCTION_RE = /\b[a-z][A-Za-z0-9_]*\(\)|\b[a-z]+[A-Z][A-Za-z0-9]*\b/g;
-
-const WORD_RE = new RegExp(`\\b(${BANNED_WORDS.join("|")})\\b`, "gi");
 
 /**
  * Every reason this text may not be shown to a reader. Empty means it may.
  *
- * Code spans are exempt: a line that says `` `clearotron --version` `` is telling a reader what to
- * type, which is the opposite of jargon. Everything outside the backticks is still checked.
+ * The line rules are plain-language-rules.mjs's, the same ones the note lint applies on the pull request.
  */
-export function findings(text) {
+export function findings(text, { sourceDirs = sourceDirectories(), docs = userDocs() } = {}) {
   const out = [];
   const lines = text.split("\n");
   for (const [i, raw] of lines.entries()) {
     // A heading is changesets' own furniture ("## 0.2.0", "### Patch Changes"), not authored prose.
     if (/^\s*#{1,6}\s/.test(raw)) continue;
-    const line = raw.replace(/`[^`]*`/g, (m) => " ".repeat(m.length));
-    const at = (what, m) => out.push({ line: i + 1, kind: what, match: m, text: raw.trim() });
-    for (const m of line.matchAll(WORD_RE)) at("jargon word", m[0]);
-    for (const m of line.matchAll(FILE_NAME_RE)) at("file name", m[0]);
-    for (const m of line.matchAll(PATH_RE)) at("path", m[0]);
-    for (const m of line.matchAll(FUNCTION_RE)) at("function name", m[0]);
+    for (const f of lineFindings(raw, { sourceDirs, docs })) out.push({ line: i + 1, kind: f.kind, match: f.match, text: raw.trim() });
   }
   return out;
 }

package/scripts/e2e.mjs

@@ -2393,6 +2393,8 @@ export function doorRefusal(receipt, ref, expect = null) {
 const secs = (n) => (n == null ? "?" : n >= 3600 ? `${Math.floor(n / 3600)}h${String(Math.floor((n % 3600) / 60)).padStart(2, "0")}m`
   : n >= 60 ? `${Math.floor(n / 60)}m${String(Math.round(n % 60)).padStart(2, "0")}s` : `${Math.round(n)}s`);
 
+const DEPTH_UNREAD = "narrative-write-ups:could-not-read";
+
 function runLedger(runDir) {
   const st = readJson(join(runDir, "status.json")) ?? {};
   const dd = driverDir(runDir);
@@ -2437,7 +2439,15 @@ function runLedger(runDir) {
     if (row?.degraded) degraded.push(`unit ${key}: ${row.degradedCause ?? "cause not recorded"} (attempt ${row.attempts ?? "not recorded"})`);
   }
 
-  return { st, attempts, wall, degraded, stageLogs: files.length };
+  // A GRADED RUN WHOSE NARRATIVE THE DEPTH CHECK COULD NOT READ delivered with the depth rules applied to
+  // nothing. The receipt says so in a check of its own, and nothing a test lane reads carried it: the
+  // client's mail holds no machine-check lines, and the workbook's Machine Checks sheet is for the reviewing
+  // lawyer. Read from either shape a receipt carries, the check object or the stored list of failing ids.
+  const lint = readJson(join(dd, "predelivery-lint.json"));
+  const depthCheck = (Array.isArray(lint?.checks) ? lint.checks : []).find((c) => c?.id === DEPTH_UNREAD) ?? null;
+  const depthUnread = depthCheck ? depthCheck.pass === false : (Array.isArray(lint?.failures) && lint.failures.includes(DEPTH_UNREAD));
+
+  return { st, attempts, wall, degraded, depthUnread, stageLogs: files.length };
 }
 
 // Everything worth a human's attention, in one list. Each entry is a thing to INVESTIGATE — never a
@@ -2453,7 +2463,7 @@ function brief(s, max = 150) {
   return `${t.slice(0, head)} … ${t.slice(-(max - head - 3))}`;
 }
 
-function investigate({ st, attempts, degraded }) {
+function investigate({ st, attempts, degraded, depthUnread = false }) {
   const out = [];
   if (!attempts.length) out.push(`no model-attempt records found — the ledger cannot describe this run; do not read that as clean`);
 
@@ -2489,6 +2499,7 @@ function investigate({ st, attempts, degraded }) {
   // the row names its own kind ("lane zh: …" / "unit serp-grid:zh: …") — units degrade for different
   // reasons than lanes do, and a hardcoded "lane" here would mislabel every one of them
   for (const d of degraded) out.push(`degraded — ${d}`);
+  if (depthUnread) out.push(`depth rules applied to nothing — ${DEPTH_UNREAD}: the narrative carries no write-up block this check can read, so neither the band-rank cut nor the word cap was verified on this run`);
   if (st.state && st.state !== "delivered") out.push(`terminal state is "${st.state}"${st.failedStage ? ` at ${st.failedStage}` : ""}${st.reason ? ` — ${brief(st.reason, 120)}` : ""}`);
   return out;
 }

package/scripts/env-audit.mjs

@@ -79,7 +79,13 @@ const asList = process.argv.includes("--list");
 //      the catalogue ratchet then demands an operator row for a value the driver overwrites — a row
 //      teaching the operator to configure something they must not touch. `==`/`===` are excluded from
 //      the exclusion, because a comparison is a read.
-const READ_RE = /(?<![.\w$])(?:process\.)?env\.([A-Z][A-Z0-9_]*)(?![A-Z0-9_])(?!\s*=[^=])|(?<![.\w$])(?:process\.)?env\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\](?!\s*=[^=])/g;
+//
+// AND `?.` IS THE SAME READ. `env?.X`, `process.env?.X` and `env?.["X"]` read exactly what `env.X`
+// reads, and the pattern used to stop at the `?`: a name read only that way needed no governance row,
+// no catalogue row and no effect declaration, and every catalogue check stayed green about it. Measured
+// 2026-09-10, three product names were read only through `?.`. An optional chain cannot be assigned
+// through, so the assignment guard has nothing new to exclude.
+const READ_RE = /(?<![.\w$])(?:process\??\.)?env\??\.([A-Z][A-Z0-9_]*)(?![A-Z0-9_])(?!\s*=[^=])|(?<![.\w$])(?:process\??\.)?env(?:\?\.)?\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\](?!\s*=[^=])/g;
 const CODE_RE = /\.(mjs|js|cjs|ts)$/;
 
 // ── AN ACCESSOR CALL IS A READ, AND STEP 4 MADE IT THE COMMON ONE ────────────────────────────────
@@ -193,8 +199,9 @@ export function mergeEnvNameBindings(perFile) {
 }
 
 // The computed read whose subscript is a BARE IDENTIFIER. `env["X"]` is READ_RE's; this is the one that
-// needs the map. Same assignment guard as its siblings — `env[X] = v` is a write.
-const CONST_READ_RE = /(?<![.\w$])(?:process\.)?env\[\s*([A-Z][A-Z0-9_]*)\s*\](?!\s*=[^=])/g;
+// needs the map. Same assignment guard as its siblings — `env[X] = v` is a write. `env?.[X]` is the same
+// read as `env[X]`, for the reason READ_RE gives.
+const CONST_READ_RE = /(?<![.\w$])(?:process\??\.)?env(?:\?\.)?\[\s*([A-Z][A-Z0-9_]*)\s*\](?!\s*=[^=])/g;
 
 export function namesRead(text, bindings = null) {
   const found = new Set();

package/scripts/env-classify.mjs

@@ -10,6 +10,7 @@
 //   node scripts/env-classify.mjs            print the classification
 //   node scripts/env-classify.mjs --apply    write docs/architecture/env-classification.json
 //   node scripts/env-classify.mjs --check    rebuild and diff against the committed artifact
+//   node scripts/env-classify.mjs --check --artifact <path>   …against another copy, for a driven check
 //   node scripts/env-classify.mjs --gather-prod --unit-dir <d> --env-file <f>   the production name list
 //
 // ── WHAT IS READ, AND WHAT IS NEVER READ ─────────────────────────────────────────────────────────
@@ -47,6 +48,7 @@ import { execFileSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+import { catalogueRows } from "./env-audit.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const ART = join(ROOT, "docs/architecture/env-classification.json");
@@ -54,6 +56,33 @@ const PROD = join(ROOT, "docs/architecture/env-set-in-production.txt");
 const read = (p) => { try { return readFileSync(p, "utf8"); } catch { return ""; } };
 const git = (...a) => { try { return execFileSync("git", ["-C", ROOT, ...a], { encoding: "utf8", maxBuffer: 1e8 }); } catch { return ""; } };
 
+// THE ENV EXAMPLE FILES, NAMED ONCE AND READ ONE WAY. This module had two lists of them, and the one that
+// decides `documented` left out `.env.deployment.example`, the largest, while the other read all four.
+// Every name documented only there was recorded as undocumented: 159 in the committed classification
+// when that was measured, 2026-09-10. A row is read by the catalogue's own `catalogueRows`, so "has a
+// row" means here what it means in the audit.
+export const ENV_EXAMPLE_FILES = [".env.example", ".env.deployment.example", ".env.dev.example", ".env.prod.example"];
+
+/**
+ * Every name the example files carry a row for, commented or not.
+ *
+ * AN ABSENT FILE ADDS NOTHING. Three of the four are withheld from the public tree, and a public checkout
+ * must still gather; the artifact is minted only where they are laid, because it refuses without the
+ * production list that is withheld with them. A file that EXISTS and cannot be read refuses instead, for
+ * the reason `mustRead` gives: read as empty, every name it documents would record as undocumented.
+ */
+export function exampleNames(root = ROOT) {
+  return ENV_EXAMPLE_FILES.flatMap((f) => {
+    const p = join(root, f);
+    let text = "";
+    try { text = readFileSync(p, "utf8"); } catch (e) {
+      if (e.code !== "ENOENT")
+        throw new Error(`env-classify: ${p} exists and could not be read (${e.code}). Read as empty, every name it documents would record as undocumented.`);
+    }
+    return catalogueRows(text).map((r) => r.name);
+  });
+}
+
 /** Assignment NAMES from a shell-shaped env file. Values are matched and discarded, never returned. */
 export function namesInEnvFile(text) {
   return [...text.matchAll(/^[ \t]*(?:export[ \t]+)?([A-Z][A-Z0-9_]*)=/gm)].map((m) => m[1]);
@@ -169,8 +198,7 @@ export function gather({ root = ROOT, prodList = null } = {}) {
     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]))),
+    docs: set(exampleNames(root)),
     _tracked: tracked,
   };
 }
@@ -194,11 +222,101 @@ export function setupNames(root = ROOT) {
   // the wizard writes it through a COMPUTED key, `candidate[eng.headless.tokenEnv]`, so the literal
   // candidate-write matchers above cannot see it; the table field is the one derivable spelling).
   for (const m of cfg.matchAll(/(?:env|authEnv|apiKeyEnv|credEnv|tokenEnv):\s*"([A-Z][A-Z0-9_]*)"/g)) seed.add(m[1]);
+  // THE NAMES A HELPER RETURNS AND THE WIZARD MERGES IN. The sign-in step hands back the `.env` keys it
+  // wants written, and the wizard writes them with `Object.assign(candidate, await askSignIn(…))`. None of
+  // the matchers above sees a key inside a returned object, so both names that step writes — the address
+  // that signs in and the organisation's name — fell through every shape, the organisation's name to
+  // `tuning`: the residual bucket, and the one a cleanup deletes from. Read from the MERGE, not from the
+  // object's shape: a rule taking every object literal with upper-case keys would take in every constant
+  // table in the wizard, and grow this population by names nothing writes.
+  for (const n of namesMergedIntoCandidate(onboard)) seed.add(n);
   const out = new Set();
   for (const n of seed) for (const sp of [n]) out.add(sp);
   return out;
 }
 
+/**
+ * Every name the wizard writes through an object a helper RETURNS: each `Object.assign(candidate, NAME(…))`
+ * names a helper, and the top-level keys of the object literals it returns are the names it writes.
+ *
+ * A helper named at a merge and not defined in the wizard REFUSES, and so does one whose returns name no
+ * key. Either way its names are written at install and cannot be read here, and reading them as none puts
+ * them in `tuning` with nothing saying the look failed — the silence `mustRead` exists for.
+ */
+function namesMergedIntoCandidate(src) {
+  const names = new Set();
+  const helpers = new Set([...src.matchAll(/Object\.assign\(\s*candidate\s*,\s*(?:await\s+)?([A-Za-z_$][\w$]*)\s*\(/g)]
+    .map((m) => m[1]));
+  for (const fn of helpers) {
+    const at = src.search(new RegExp(`\\bfunction\\s+${fn.replace(/\$/g, "\\$")}\\s*\\(`));
+    const refuse = (why) => new Error(`env-classify: bin/onboard.mjs writes what ${fn}() returns, and ${why}, so `
+      + "the names it writes cannot be read. Read as none, they would land in `tuning` and on the deletion "
+      + "population; that is this script failing to look, not a finding about the wizard.");
+    if (at < 0) throw refuse(`no function ${fn} is defined there`);
+    // From the declaration on, with comments and the inside of every string blanked, so a brace, a comma or
+    // a `return` in either is not read as code. A parameter default can hold braces, so the body is the
+    // first `{` after the parameter list, not the first `{`.
+    const text = src.slice(at), code = blankNonCode(text);
+    const open = code.indexOf("{", closingOf(code, code.indexOf("(")));
+    const close = closingOf(code, open);
+    let found = 0;
+    for (const r of code.slice(open, close).matchAll(/\breturn\s*\{/g)) {
+      for (const key of topLevelKeys(text, code, open + r.index + r[0].length - 1)) { names.add(key); found++; }
+    }
+    if (!found) throw refuse("none of its returns is an object literal naming a key");
+  }
+  return names;
+}
+
+/** `text` with every comment and the inside of every string turned to spaces. Same length, same lines. */
+function blankNonCode(text) {
+  let out = "", i = 0;
+  const blank = (to) => { out += text.slice(i, to).replace(/[^\n]/g, " "); i = to; };
+  while (i < text.length) {
+    const c = text[i], d = text[i + 1];
+    if (c === "/" && (d === "/" || d === "*")) {
+      const end = d === "/" ? text.indexOf("\n", i) : text.indexOf("*/", i + 2) + 2;
+      blank(end < i + 2 ? text.length : end);
+    } else if (c === '"' || c === "'" || c === "`") {
+      let j = i + 1;
+      while (j < text.length && text[j] !== c && (c === "`" || text[j] !== "\n")) j += text[j] === "\\" ? 2 : 1;
+      out += c; i += 1; blank(Math.min(j, text.length));
+      if (i < text.length) out += text[i++];
+    } else {
+      out += c; i += 1;
+    }
+  }
+  return out;
+}
+
+/** The index of the bracket closing the one at `at`, counting every kind; `code` is already blanked. */
+function closingOf(code, at) {
+  let depth = 0;
+  for (let i = at; i < code.length; i++) {
+    if ("([{".includes(code[i])) depth++;
+    else if (")]}".includes(code[i]) && --depth === 0) return i;
+  }
+  return code.length;
+}
+
+/** The top-level keys of the object literal opening at `open`: a nested object's keys are its own. */
+function topLevelKeys(text, code, open) {
+  const keys = [];
+  const close = closingOf(code, open);
+  let depth = 0, from = open + 1;
+  for (let i = open + 1; i <= close; i++) {
+    const c = code[i];
+    if (i < close && "([{".includes(c)) depth++;
+    else if (i < close && ")]}".includes(c)) depth--;
+    else if (i === close || (c === "," && depth === 0)) {
+      const m = /^\s*(["']?)([A-Z][A-Z0-9_]*)\1\s*:/.exec(text.slice(from, i));
+      if (m) keys.push(m[2]);
+      from = i + 1;
+    }
+  }
+  return keys;
+}
+
 // THE AUDIENCE DECISION FOR NAMES A PREFIX USED TO CARRY — listed, because a rename must not move it.
 //
 // Every name here was classified `deployment` by one of DEPLOY_RE's PREFIX arms and by nothing else.
@@ -210,7 +328,9 @@ export function setupNames(root = ROOT) {
 //
 // Nothing would have said so. `--check` is the only thing that compares the artifact to the tree, and
 // it ran in no workflow, no hook and no test; the reproducibility arm deliberately does not re-run the
-// classifier. This commit wires `--check` into CI, which is the half that makes the drift audible.
+// classifier. It cannot run in this repository's CI at all: the artifact and the production name list it
+// needs are withheld from the public tree, so here it stops at "could not look". It runs where they are
+// laid, in the private control, and a stale artifact there names the rows that moved.
 //
 // The comment beside AUDIENCE/ISSUER below already recorded this class, one name at a time:
 // "a rename is exactly when a shape-based classifier goes wrong, and this one is a rename programme."
@@ -226,6 +346,14 @@ export const DEPLOYMENT_NAMES = new Set([
   // by nothing else, so moving it to the house prefix dropped it through to `tuning` — the bucket step 3
   // deletes from. The audience did not change; only the spelling did, and this list is what says so.
   "CLEAROTRON_DEMO",
+  // Three names read only through optional chaining, so no catalogue check saw them until the scanner
+  // learned `?.`. Each row declares `deployment`, and no shape matches them (`_PORT$` does not take
+  // `_PORTS`), so unlisted each fell through to `tuning`, the bucket step 3 deletes from. The first is set
+  // by the dispatcher for the verb it runs and never by an operator; the other two are a server install's
+  // port and deploy-health settings.
+  "CLEAROTRON_INVOKED_AS",
+  "CLEAROTRON_REQUIRE_EXPLICIT_PORTS",
+  "CLEAROTRON_UPDATER_STAMP",
   "CLIENT_MCP_ACCOUNT_ACCESS",
   "CLIENT_MCP_ALLOWED_HOSTS",
   "CLIENT_MCP_AUTH_DISABLED",
@@ -270,6 +398,9 @@ export const DEPLOYMENT_NAMES = new Set([
   "TRADEMARK_MCP_AUTH_MODE",
   "TRADEMARK_MCP_DEV",
   "TRADEMARK_MCP_EMAIL_CLAIM",
+  // The key door's socket path. Its row declares `deployment`, and until it was listed the
+  // `TRADEMARK_MCP_` prefix arm was its only route there, which a house-prefix sweep would take away.
+  "TRADEMARK_MCP_KEY_SOCKET",
   "TRADEMARK_MCP_MAX_BYTES",
   "TRADEMARK_MCP_SESSION_MAX",
   "TRADEMARK_MCP_SESSION_TTL_MS",
@@ -373,6 +504,9 @@ export function classify({ catalogue, sources, setup = setupNames(), readSites =
     // `declared` is the catalogue's own `# effect:` for this name, carried on the row so the artifact
     // says what the document claims beside what this script derived. The two are different questions and
     // the row is where a reader compares them.
+    //
+    // `documented` is a row in any example file. The minted catalogue is itself read from two of those
+    // files, so every row there reads true; a false would mean a name reached it from somewhere else.
     return { name, class: cls(name), everSet: setIn, declared: declared.get(name) ?? null,
       documented: Boolean(sources.docs?.has(name)) };
   });
@@ -465,6 +599,60 @@ export function classify({ catalogue, sources, setup = setupNames(), readSites =
   } };
 }
 
+/**
+ * PURE. Which rows of the classification moved between the committed artifact and the tree.
+ *
+ * @param {object|null} prev  the committed artifact, parsed; null when it could not be read
+ * @param {object} next  the classification this tree produces
+ * @returns {{ added: string[], removed: string[], changed: Array<{ name: string, fields: string[] }>, header: string[] }}
+ *   `changed` lists every field that differs, compared as JSON, so a field one side lacks counts as changed.
+ *   `header` names the top-level keys other than `rows` that differ, such as the counts.
+ */
+export function classificationDrift(prev, next) {
+  // A NAME CAN SIT ON MORE THAN ONE ROW. The catalogue can list a name more than once, and the
+  // classification then carries it once per listing, the rows identical in every field. So rows are
+  // grouped by name and compared as lists. Keyed by name alone, the last row of each name hid the others,
+  // and a change to the first of two rows read as "only the formatting differs".
+  const rowsOf = (a) => {
+    const m = new Map();
+    for (const r of Array.isArray(a?.rows) ? a.rows : []) m.set(r?.name, [...(m.get(r?.name) ?? []), r]);
+    return m;
+  };
+  const was = rowsOf(prev), now = rowsOf(next);
+  const added = [...now.keys()].filter((n) => !was.has(n)).sort();
+  const removed = [...was.keys()].filter((n) => !now.has(n)).sort();
+  const changed = [];
+  for (const [name, rows] of now) {
+    const before = was.get(name);
+    if (!before) continue;
+    if (before.length !== rows.length) { changed.push({ name, fields: [`${before.length} row${before.length === 1 ? "" : "s"}, now ${rows.length}`] }); continue; }
+    const fields = new Set();
+    rows.forEach((row, i) => {
+      for (const k of new Set([...Object.keys(before[i]), ...Object.keys(row)]))
+        if (JSON.stringify(before[i][k]) !== JSON.stringify(row[k])) fields.add(k);
+    });
+    if (fields.size) changed.push({ name, fields: [...fields].sort() });
+  }
+  changed.sort((a, b) => a.name.localeCompare(b.name));
+  const header = [...new Set([...Object.keys(prev ?? {}), ...Object.keys(next ?? {})])]
+    .filter((k) => k !== "rows" && JSON.stringify(prev?.[k]) !== JSON.stringify(next?.[k])).sort();
+  return { added, removed, changed, header };
+}
+
+/** PURE. The drift as lines a reader can act on, each list capped so a large drift stays readable. */
+export function describeDrift(d, { cap = 12, unreadable = false, missing = false } = {}) {
+  const list = (names) => names.length > cap ? `${names.slice(0, cap).join(", ")} and ${names.length - cap} more` : names.join(", ");
+  const out = [];
+  if (missing) out.push("  the committed artifact is absent, so every row below reads as added");
+  if (unreadable) out.push("  the committed artifact is not valid JSON, so every row below reads as added");
+  if (d.added.length) out.push(`  ${d.added.length} row(s) added: ${list(d.added)}`);
+  if (d.removed.length) out.push(`  ${d.removed.length} row(s) removed: ${list(d.removed)}`);
+  if (d.changed.length) out.push(`  ${d.changed.length} row(s) changed: ${list(d.changed.map((c) => `${c.name} (${c.fields.join(", ")})`))}`);
+  if (d.header.length) out.push(`  outside the rows: ${d.header.join(", ")}`);
+  if (!out.length) out.push("  no row differs, and neither does anything outside the rows: the difference is in the file's formatting");
+  return out;
+}
+
 function build() {
   const audit = JSON.parse(execFileSync(process.execPath, [join(ROOT, "scripts/env-audit.mjs"), "--json"],
     { encoding: "utf8", cwd: ROOT, maxBuffer: 1e8 }));
@@ -534,13 +722,8 @@ function main() {
     // AND IT REPORTS WHAT IT DROPPED. A filter that drops silently replaces one invisible loss with
     // another; the shape goes to stderr so the artifact stays exactly the names, and it is grouped by
     // first token and COUNTED rather than listed, because a dropped name can identify someone.
-    const catalogueNames = [];
-    for (const f of [".env.example", ".env.deployment.example", ".env.dev.example", ".env.prod.example"]) {
-      try {
-        const txt = readFileSync(new URL(`../${f}`, import.meta.url), "utf8");
-        for (const m of txt.matchAll(/^#?\s*([A-Z][A-Z0-9_]*)\s*=/gm)) catalogueNames.push(m[1]);
-      } catch { /* an absent example file narrows the allowlist; the drop report shows the effect */ }
-    }
+    // An absent example file narrows the allowlist; the drop report shows the effect.
+    const catalogueNames = exampleNames();
     const isOwned = makeIsProductOwned({ credentialNames: AMBIENT_KEYS, catalogueNames });
     const { kept, dropped } = partitionByOwnership([...names], isOwned);
     console.error(`# ${FILTER_DECLARATION}`);
@@ -564,10 +747,20 @@ function main() {
   }
   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") : "";
+    // `--artifact <path>` compares against another copy instead of the committed one, so a driven check
+    // can hand it an artifact with a row removed without touching the file a reviewer reads.
+    const against = flag("artifact") || ART;
+    const prev = existsSync(against) ? readFileSync(against, "utf8") : "";
     const same = prev === JSON.stringify(next, null, 2) + "\n";
     console.log(same ? "CHECK — the committed classification matches this tree." : "CHECK FAILED — the classification is stale. Re-stamp: node scripts/env-classify.mjs --apply");
-    if (!same) process.exitCode = 1;
+    if (!same) {
+      // SAY WHICH ROWS. "Stale" alone sends the reader to diff two large JSON files by eye; the rows that
+      // moved are what they have to judge, and they are the part a regeneration would silently absorb.
+      let before = null;
+      try { before = JSON.parse(prev); } catch { /* unreadable: said below */ }
+      for (const line of describeDrift(classificationDrift(before, next), { unreadable: prev !== "" && before === null, missing: prev === "" })) console.log(line);
+      process.exitCode = 1;
+    }
     return;
   }
   console.log(JSON.stringify(next._counts));

package/scripts/live-surface-check.mjs

@@ -88,7 +88,7 @@ import { rosterVerdict } from "../driver/roster-verdict.mjs";
 import { triggerCapGap, triggerCapWarning } from "../driver/trigger-cap.mjs";   // the portal's own sentence about a key's gap
 import { bundledDemoKeys } from "../driver/bundled-demos.mjs";
 import { unitsActiveVerdict } from "../driver/unit-state-verdict.mjs";
-import { deploymentBox } from "../shared/deployment-box.mjs";   // — extracted; one allowlist, two readers
+import { deploymentBox, DEPLOYMENT_BOXES } from "../shared/deployment-box.mjs";   // — extracted; one allowlist, every reader
 import { unitFileDriftVerdict } from "../driver/unit-file-drift.mjs";   //
 import { placeholdersIn, resolveValues, renderUnit } from "../driver/systemd/render-units.mjs";   //
 import { CHECKED_UNITS, CHECKED_TIMERS, timerVerdict, unitInventoryVerdict, serviceCommitVerdict, unitWorkingDirectory, unitClone } from "../driver/unit-inventory.mjs";   // · -bundle ·
@@ -100,6 +100,7 @@ import { config } from "../driver/driver.config.mjs";                          /
 import { probeQueueWatch, probeWorker, probeTimer } from "../driver/queue-watch-probe.mjs";   // · and, tracker issue 206, the units that say HOW this box drains
 import { doorPostureVerdict } from "../mcp-server/door-posture.mjs";   // — a door whose mode came from another door's variables
 import { readDrainerStamp, drainerVerdict, defaultPpidOf } from "../driver/drainer-identity.mjs";   // — the process that EXECUTES runs
+import { readUpdaterStamp, updaterVerdict, resolveUpdaterStampPath, updaterAbsentHere, UPDATER_STAMP_BASENAME } from "../driver/updater-identity.mjs";   // — the mechanism that PLACES commits
 import { claimerIsAlive } from "../driver/claim-liveness.mjs";                       // the shared liveness test, same polarity as the queue's
 import { processTable } from "../shared/process-table.mjs";                          // — /proc is not the only box
 import { envFrom } from "../shared/env-aliases.mjs";   // — the name a reader is told to set is the one in force
@@ -801,6 +802,77 @@ else {
   }
 }
 
+// ── 8c. — THE MECHANISM THAT PLACES THE COMMITS, WHICH ARM 8 CANNOT ATTRIBUTE ────────────
+//
+// Arm 8 attributes a unit to a commit two ways: the tree under its WorkingDirectory, and the tree the
+// running process was launched from. Both fail for exactly one unit, and it is the updater — a oneshot
+// running from a home directory with no checkout under it, whose command line is the update script
+// rather than the product entry point. So the unit that places every commit on this box was the one
+// unit reported as "could NOT be read and was NOT compared". An updater running from a stale copy
+// would place a stale tree and this check would pass, which is the straddle pointed at the mechanism
+// that does the deploying.
+//
+// IT IS JUDGED ON A STAMP IT WRITES ABOUT ITSELF, the way the drainer above is, and arm 8 now names it
+// as stamped rather than dropping it into the unreadable pile. The two arms cannot disagree because
+// neither judges the other's population: this one owns the updater, that one owns everything with a
+// tree under it, and the inventory decides which is which.
+//
+// IT FAILS ON COULD-NOT-LOOK, for the reason arm 8b does and one more of its own: the stamp writer
+// shipped IN the updater, so a copy old enough to predate it writes no stamp — and that is not a gap in
+// the reporting, it is the stale updater this arm exists to catch, arriving as an absence.
+{
+  // WHERE THE STAMP IS, WITHOUT SPELLING A LOGIN INTO A PUBLIC FILE. The environment wins, because a
+  // box that redirects its updater must not be told it has no updater; otherwise the directory is the
+  // one the unit itself reports, which is where the updater runs and therefore where it stamps. A
+  // hardcoded home would publish an account name AND red every box that moved it.
+  //
+  // THE ENVIRONMENT IS READ INSIDE THE MODULE, under the name the WRITER already honours, so the two
+  // halves cannot look in different places. A reader-only variable would let a redirected updater stamp
+  // one path while this looked at another and reported "no stamp" — the loud branch — about a
+  // deployment that is working. What is derived here is only the fallback.
+  //
+  // A BOX WITH NO UPDATER IS ASKED FIRST (updaterAbsentHere): skipped with its reason, never failed.
+  const absent = updaterAbsentHere(clones.find((c) => c.unit === "clearotron-deploy"));
+  if (absent) skip("the updater that deploys this box is the current one", absent);
+  else {
+  let deployDir = null, resolveWhy = null;
+  {
+    const row = clones.find((c) => c.unit === "clearotron-deploy");
+    if (!row) resolveWhy = "no updater unit was probed on this box";
+    else {
+      // The unit is a oneshot: between ticks it is inactive and reports its WorkingDirectory anyway,
+      // which is the whole reason this attribution works where the process-based one cannot.
+      let wd = null;
+      try {
+        const shown = execFileSync("systemctl", ["--user", "show", "clearotron-deploy", "-p", "WorkingDirectory"],
+          { encoding: "utf8", env: userBusEnv(), stdio: ["ignore", "pipe", "pipe"] });
+        wd = /^WorkingDirectory=(.*)$/m.exec(shown)?.[1]?.trim() || null;
+      } catch (e) { resolveWhy = `systemctl could not be asked where the updater runs: ${String(e?.message ?? e).slice(0, 100)}`; }
+      if (wd !== null) {
+        const parsed = unitWorkingDirectory(wd);
+        if (!parsed.path) resolveWhy = parsed.why;
+        else deployDir = join(parsed.path, "deploy");
+      } else if (!resolveWhy) resolveWhy = "the updater unit reported no WorkingDirectory, so where it stamps could not be derived";
+    }
+  }
+
+  if (!resolveUpdaterStampPath(deployDir)) {
+    fail("the updater that deploys this box is the current one",
+      `where the updater stamps itself could not be resolved (${resolveWhy ?? "no value"}), so `
+      + `${UPDATER_STAMP_BASENAME} was not looked for. This is a failure to look, never a pass.`);
+  } else {
+    const v = updaterVerdict({
+      stamp: readUpdaterStamp(deployDir),
+      now: Math.floor(Date.now() / 1000),
+      // The same clone arm 8 scoped itself to, so the two arms cannot hold different opinions about
+      // which tree this deploy is. Reading it twice is how they would come to.
+      deployClone,
+    });
+    record("the updater that deploys this box is the current one", v.state, v.message);
+  }
+  }
+}
+
 //: "0 active" is not a pass. It is either "I could not look" or "there is nothing running here".
 //: and "not active" is not "broken". Both state comparisons this arm used to make lived here as
 // inline string equality over a two-word vocabulary, which is why a `Type=oneshot` doing its job read as
@@ -940,7 +1012,7 @@ else {
   // unit missing. Deployments set it in the service environment file beside the other box-scoped vars.
   const box = deploymentBox();   // — the shared rule, so /portal/health cannot disagree with this
   const v = unitInventoryVerdict({ live: liveUnits, files: walk.files, collisions: walk.collisions,
-    filesError: walk.error, box, probe });
+    filesError: walk.error, box, probe, boxNames: DEPLOYMENT_BOXES });
   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