clearotron 0.2.1 → 0.2.2

package/driver/unit-inventory.mjs

@@ -23,6 +23,11 @@
 //   | recipe-service              |  —   |  —   |  yes    | yes                     |
 //   | portal-service              |  —   |  —   |  yes    | NO                      |
 //
+// THAT TABLE IS THE 2026-08-11 READING AND IS NOT REFRESHED. Two of its rows name units that no longer
+// exist: `prelim-driver` and `prelim-outbox` were retired with the path-watcher drain posture and their
+// files left the tree once production was rebuilt. They stay in the table because it records what was
+// measured on that date, and a measurement edited to match today is no longer a measurement.
+//
 // TWO CORRECTIONS TO THE ISSUE ARE BAKED INTO THIS TABLE, and one of them inverts a fix. lists
 // `profile-service` and `prelim-outbox` under "tracked and never run". That reading comes from the test
 // box, where neither is installed. PRODUCTION RUNS BOTH — so deleting their tracked files as dead
@@ -52,7 +57,7 @@
 // each was already in the tree, in `mcp-server/remote/`. The repo's own governance doc names BOTH
 // directories (`docs/architecture/05-config-governance.md`, tier 2); the guard named one.
 //
-// That is the same defect one layer up from the one this file was built to fix. 's inline array made
+// That is the same defect one layer up from the one this file was built to fix. That inline array made
 // a unit's membership of the guarantee an omission; the hardcoded directory made a FILE's membership an
 // omission, and the result was three statements of fact that were false with nothing able to contradict
 // them. The tracked-file lookup is now a repo-wide walk (driver/unit-files.mjs), and `unitInventoryVerdict`
@@ -70,7 +75,7 @@
 /** Where a unit is expected to be installed. "none" is a claim, not an absence — see ORPHANED below. */
 export const BOXES = Object.freeze(["prod", "test", "dev"]);
 
-// ── RESOLVED UNITS (, owner ruling 2026-08-25 — option B) ──────────────────────
+// ── RESOLVED UNITS (owner ruling 2026-08-25 — option B) ──────────────────────
 //
 // `resolved: [...]` names tracked files the INSTALLER rewrites before installing. Three units carry
 // `@NAME@` placeholders because configuration cannot reach them: a `.path` unit reads no environment at
@@ -98,6 +103,13 @@ export const BOXES = Object.freeze(["prod", "test", "dev"]);
 // 2026-08-26), so the rebuild is the event that releases the files, and until then entry and tree
 // disagree ON PURPOSE.
 //
+// THE REBUILD HAPPENED, and the first two entries this field ever carried have gone with their files.
+// Measured on the production install 2026-09-07 (tracker issue 265): seven units, all under the current
+// names, none of the retired ones, with a clearance delivered end to end. `prelim-driver.*` and
+// `prelim-outbox.*` left the tree in the same change that removed their entries. Read the paragraph
+// above as the rule and this one as the event that discharged it — without this line a reader concludes
+// the files are still owed and that their absence is the drift.
+//
 // Two consumers, so this is not prose: `unitInventoryVerdict` reports a retired unit's absence as
 // EXPECTED rather than as drift, and a claimed-but-missing tracked file is a fault whatever the
 // retirement says. That pair is what asks for — absent-and-expected-to-be told
@@ -110,7 +122,8 @@ export const UNIT_INVENTORY = Object.freeze([
     // rather than the day it first runs, because a unit file no entry claims is exactly what this file
     // exists to make impossible — and a mechanism that installs itself is the easiest kind to ship
     // undeclared.
-    unit: "clearotron-deploy", runsOn: [],
+    unit: "clearotron-deploy", runsOn: ["test"],
+      measured: "2026-09-07, test box: the timer and its service are installed under ~/.config/systemd/user/ and the service has run — see /home/testuser/deploy/autodeploy.log. The timer's ARMED state is not part of this claim; a lane may hold it, and a hold is recorded in the deploy log rather than inferred from ActiveState.",
     tracked: ["clearotron-deploy.service", "clearotron-deploy.timer"],
     note: "the install's own updater. Ships tracked, runs nowhere yet.",
     orphanReason: "SHIPPED AND PLACED ON NO BOX YET, which is a THIRD kind of orphan and not either of "
@@ -121,30 +134,6 @@ export const UNIT_INVENTORY = Object.freeze([
       + "\"not compared\" row that reads like a fault and is not one. It goes on with "
       + "`systemctl --user enable --now clearotron-deploy.timer` once bin/onboard.mjs has written both files.",
   },
-  {
-    unit: "prelim-driver", runsOn: ["prod", "test"],
-    tracked: ["prelim-driver.service", "prelim-driver.path", "prelim-driver.timer"],
-    resolved: ["prelim-driver.path"],   // option B — see RESOLVED below
-    retired: {
-      ruled: "2026-08-26, restated 2026-08-31",
-      filesStayUntil: "prod",
-      why: "the path-watcher/timer drain posture is retired (tracker issue 1863): the built-in worker "
-        + "is the product's drain, and a hosted deployment gets ONE plain service unit invoking the "
-        + "entrypoint directly rather than a oneshot woken by a timer and a queue glob. Absence on any "
-        + "box is now the EXPECTED direction rather than drift. The replacement is deliberately not "
-        + "named here — a pointer outlives the file it points at, which is why `supersedes:` was "
-        + "removed from this file once already; the pinned background list is where the current drain "
-        + "is stated, and it is code rather than prose.",
-    },
-    note: "the driver itself — the one unit the drift check has always been able to compare. "
-      + "SETTLED (tracker issue 1888, measured on the owner's fresh production install 2026-08-31): "
-      + "the documented install creates NO units at all — not even the unit directory — and a knockout "
-      + "delivered end to end without them, so units are the hosted-deployment OPT-IN step, never the "
-      + "install's output. Absent on a box is the install's normal state; present means someone ran the "
-      + "hosted step there. `runsOn` lists exactly the boxes MEASURED to carry it, which is why absence "
-      + "anywhere else is not drift — the earlier expectation that the .path unit ships with the install "
-      + "was the wrong half of the disagreement.",
-  },
   {
     // ── `tracked` WAS A CLAIM ABOUT A FILE THAT HAS NEVER EXISTED (tracker issue 175) ──────────────
     //
@@ -175,7 +164,7 @@ export const UNIT_INVENTORY = Object.freeze([
     // it loaded no EnvironmentFile and so had no `${VAR}` systemd could expand. The owner's one-config-
     // per-server-box ruling gives it `EnvironmentFile=%h/.env` like every other service, which makes the
     // checkout path an ordinary systemd expansion and leaves no placeholder to render.
-    note: "LIVE ON PRODUCTION. #685's body lists it as never run; that is true of the test box only. "
+    note: "LIVE ON PRODUCTION. an earlier record lists it as never run; that is true of the test box only. "
       + "Was a TEMPLATE unit carrying CF Access values inline; generic since tracker issue 1925.",
   },
   {
@@ -185,7 +174,8 @@ export const UNIT_INVENTORY = Object.freeze([
     // say "the repo ships this, nothing runs it, and here is the decision it waits on" — orphans are
     // REPORTED, never a fault, for exactly this case. It becomes `["prod"]` in the change that DEPLOYS
     // it, against a fresh enumeration, which is the ratchet working rather than being edited around.
-    unit: "clearotron-portal", runsOn: [], tracked: ["clearotron-portal.service"],
+    unit: "clearotron-portal", runsOn: ["test"], tracked: ["clearotron-portal.service"],
+      measured: "2026-09-07, test box, `systemctl --user show` with a working user bus: ActiveState=active, UnitFileState=enabled, fragment under ~/.config/systemd/user/.",
     note: "NEW, tracker issue 1925, SHIPPED BUT NOT YET DEPLOYED. The portal had NO unit at all — it "
       + "and the MCP face are the two children bin/start.mjs supervises, and neither ran under systemd, "
       + "so a hosted deployment kept them alive with a hand launcher and `clearotron start` had nothing "
@@ -201,7 +191,8 @@ export const UNIT_INVENTORY = Object.freeze([
   {
     // Same as clearotron-portal above: shipped, running nowhere, declared as an orphan rather than
     // asserting a production state no enumeration has ever shown.
-    unit: "clearotron-mcp-face", runsOn: [], tracked: ["clearotron-mcp-face.service"],
+    unit: "clearotron-mcp-face", runsOn: ["test"], tracked: ["clearotron-mcp-face.service"],
+      measured: "2026-09-07, test box, `systemctl --user show` with a working user bus: ActiveState=active, UnitFileState=enabled, fragment under ~/.config/systemd/user/.",
     note: "NEW, tracker issue 1925, SHIPPED BUT NOT YET DEPLOYED. The engine door the portal calls over "
       + "MCP; the other of the two processes that had no unit.",
     orphanReason: "THE ENGINE DOOR THE PORTAL CALLS, shipped with no box carrying it yet. Same kind as "
@@ -218,7 +209,7 @@ export const UNIT_INVENTORY = Object.freeze([
     // are then enabled like anything else. This one is shipped and DELIBERATELY NOT INSTALLED BY ANY
     // INSTALL PATH — `clearotron start` neither installs nor starts it, and a rebuild must not either.
     //
-    // ── IT INSTALLS WITH THE PRODUCT SINCE 2026-09-03 (, settled point 2) ────────
+    // ── IT INSTALLS WITH THE PRODUCT SINCE 2026-09-03 (settled point 2) ────────
     //
     // Until then it was an orphan BY DESIGN: `clearotron connect` installed and started it on demand,
     // because starting it turned on client-account access and a unit that came up with everything else
@@ -229,7 +220,8 @@ export const UNIT_INVENTORY = Object.freeze([
     // So it is now an orphan of the FIRST kind, awaiting a box, exactly like the portal and the engine
     // door beside it: it is in SERVER_INSTALL_SET, and it leaves this list on the day a measured
     // enumeration of a box shows it running.
-    unit: "clearotron-client-mcp", runsOn: [], tracked: ["clearotron-client-mcp.service"],
+    unit: "clearotron-client-mcp", runsOn: ["test"], tracked: ["clearotron-client-mcp.service"],
+      measured: "2026-09-07, test box, `systemctl --user show` with a working user bus: ActiveState=active, UnitFileState=enabled, fragment under ~/.config/systemd/user/.",
     note: "tracker issue 1976, and INSTALLED WITH THE PRODUCT since tracker issue 2148. The client door "
       + "— the one surface that accepts an account-scoped key, and a separate process from the engine "
       + "door, which refuses one outright.",
@@ -246,7 +238,8 @@ export const UNIT_INVENTORY = Object.freeze([
     // supervises the portal, the engine door and this worker; 1925 shipped units for the first two.
     // Written as part of retiring the path-watcher posture, because retiring `prelim-driver.*` without
     // it leaves a hosted box healthy-looking and draining nothing.
-    unit: "clearotron-worker", runsOn: [], tracked: ["clearotron-worker.service"],
+    unit: "clearotron-worker", runsOn: ["test"], tracked: ["clearotron-worker.service"],
+      measured: "2026-09-07, test box, `systemctl --user show` with a working user bus: ActiveState=active, UnitFileState=enabled, fragment under ~/.config/systemd/user/.",
     note: "NEW, tracker issue 1863. The drain, as one plain service unit invoking the entrypoint "
       + "directly (owner ruling 2026-08-31). Ships tracked, runs nowhere yet — production takes it at "
       + "its rebuild, which is the same event that lets the retired units' files leave the tree.",
@@ -256,21 +249,8 @@ export const UNIT_INVENTORY = Object.freeze([
       + "alternatives, and running both puts a second claimant on one queue.",
   },
   {
-    unit: "prelim-outbox", runsOn: ["prod"],
-    tracked: ["prelim-outbox.service", "prelim-outbox.path", "prelim-outbox.timer"],
-    retired: {
-      ruled: "2026-08-31",
-      filesStayUntil: "prod",
-      why: "the timer retires with the watcher it backstopped, by name in the ruling. That watcher also "
-        + "carried the last dead OpenClaw literal in the tree. Channel delivery is the "
-        + "integrator's (INSTALL.md §9), so retiring these takes away nothing the product promises — "
-        + "the worked example moves into the document rather than being deleted with them.",
-    },
-    note: "LIVE ON PRODUCTION (path and timer active-waiting). Was absent from the health check's unit "
-      + "list, so its drift was never checked despite being tracked.",
-  },
-  {
-    unit: "trademark-portal", runsOn: ["prod", "test"], tracked: null,
+    unit: "trademark-portal", runsOn: ["prod"],
+      measured: "2026-09-07, test box: LoadState=not-found. No unit of this name exists there. The `test` claim was inherited from before the rename to clearotron-* and was never remeasured; the `prod` claim is left alone because production was NOT measured here.", tracked: null,
     untrackedReason: "the deployed copy carries real Cloudflare Access team/AUD/domain values inline. "
       + "A tracked file would be the placeholder TEMPLATE, merged by hand after a "
       + "diff — writing one carelessly replaces working auth with placeholders that look configured.",
@@ -281,11 +261,13 @@ export const UNIT_INVENTORY = Object.freeze([
     supersededName: "portal-service.service (deleted, owner-ruled 2026-08-14)",
   },
   {
-    unit: "trademark-ops-mcp", runsOn: ["prod", "test"], tracked: null,
+    unit: "trademark-ops-mcp", runsOn: ["prod"],
+      measured: "2026-09-07, test box: LoadState=not-found. No unit of this name exists there. The `test` claim was inherited from before the rename to clearotron-* and was never remeasured; the `prod` claim is left alone because production was NOT measured here.", tracked: null,
     untrackedReason: "same CF Access inline-values shape as the portal it serves.",
   },
   {
-    unit: "client-mcp", runsOn: ["prod", "test"], tracked: ["client-mcp.service"],
+    unit: "client-mcp", runsOn: ["prod"],
+      measured: "2026-09-07, test box: LoadState=not-found. No unit of this name exists there. The `test` claim was inherited from before the rename to clearotron-* and was never remeasured; the `prod` claim is left alone because production was NOT measured here.", tracked: ["client-mcp.service"],
     note: "TRACKED, in mcp-server/remote/ — this entry said it had no file, and the file was there. It is "
       + "a banner-marked TEMPLATE, so the live copy differing from it is the arrangement, not drift. "
       + "#1147 ADDED THE TEST BOX (2026-08-18): the client surface ran nowhere but production, so the test "
@@ -415,13 +397,21 @@ export const UNIT_INVENTORY = Object.freeze([
       + "checkout's bridge, not this clone's.",
   },
   {
-    unit: "trademark-test-deploy", runsOn: ["test"], tracked: null,
+    unit: "trademark-test-deploy", runsOn: [],
+      measured: "2026-09-07, test box: LoadState=not-found. The hourly deploy runs as clearotron-deploy.timer, which has its own entry; this name is what that one used to be called.", tracked: null,
+    // AN EMPTY runsOn OWES A REASON, and this one is a supersession rather than an orphan: the hourly
+    // deploy still runs on the test box, under the name `clearotron-deploy`, which has its own entry and
+    // its own measurement. This name is what that unit used to be called. It is kept rather than deleted
+    // because the unit FILE is still tracked and an inventory of what ships should account for every
+    // tracked file — deleting the entry would make the file unaccounted for, which is the ratchet this
+    // file exists to keep shut.
+    orphanReason: "SUPERSEDED, NOT RETIRED — the hourly deploy of the test instance runs as `clearotron-deploy`, measured active there on 2026-09-07. This entry is the pre-rename name for the same job, so it runs on no box under THIS name and the boxes moved to the entry that replaced it. The tracked file stays until production is rebuilt, which is the same disposition the other retired units carry.",
     untrackedReason: "the hourly --ff-only deploy of the TEST instance. It exists on the test box only "
       + "and by design: production never auto-deploys, so a tracked file shipped to both would be a unit "
       + "production must be trusted never to enable.",
   },
   // register-ledger-prune is DELIBERATELY not listed, and the sequence is worth keeping because the
-  // row was right until the moment it was wrong. 's nightly rotation was retired in code by:
+  // row was right until the moment it was wrong. That nightly rotation was retired in code by:
   // bin/register-ledger-prune.mjs is deleted, record bodies now live in each run's own directory and
   // are purged with the run, so there is no global file left to rotate. The row stayed here on
   // purpose while the TIMER was still installed on the test box — dropping it first would have made
@@ -489,6 +479,11 @@ export const ACCOUNTED_FILES = Object.freeze(
  */
 export function unitInventoryVerdict({
   live = [], files = [], collisions = [], filesError = null, box = null, probe = { ok: true },
+  // INJECTED so the retirement branch can be PLANTED. `retired:` has no members today — the two it
+  // carried left with their files — so `absentByRetirement` and the line it feeds are unreachable
+  // against the real table, and a branch nothing exercises is a branch that will not fire the next
+  // time somebody retires a unit. That is this file's own failure mode pointed at itself.
+  inventory = UNIT_INVENTORY,
 } = {}) {
   if (!probe.ok) {
     return { state: "skip", undeclared: [], orphaned: [], absent: [], misdeclared: [],
@@ -496,7 +491,7 @@ export function unitInventoryVerdict({
         + "A failure to look is not a finding about the deployment." };
   }
   const base = (u) => String(u).replace(/\.(service|timer|path|socket|target|mount|slice)$/, "");
-  const known = new Set(UNIT_INVENTORY.map((u) => u.unit));
+  const known = new Set(inventory.map((u) => u.unit));
   const liveBases = [...new Set(live.map(base))];
 
   const undeclared = liveBases.filter((u) => !known.has(u)).sort();
@@ -506,7 +501,20 @@ export function unitInventoryVerdict({
   // reason attached, and the difference is the whole point of writing the reasons down.
   const accounted = new Set(ACCOUNTED_FILES);
   const unaccountedFiles = files.filter((f) => !accounted.has(f)).sort();
-  const orphaned = UNIT_INVENTORY.filter((u) => u.runsOn.length === 0).map((u) => u.unit).sort();
+  const orphaned = inventory.filter((u) => u.runsOn.length === 0).map((u) => u.unit).sort();
+
+  // RUNNING HERE, DECLARED TO RUN NOWHERE. The defect the rename to clearotron-* left behind: the new
+  // units shipped WITH entries, those entries kept `runsOn: []`, and the pre-rename names kept the
+  // boxes. Every arm scoped to CHECKED_UNITS — which filters on a NON-EMPTY runsOn — therefore asked
+  // systemd about sixteen names that mostly named nothing and reported "0 active; 16 at rest", while
+  // four services ran under names no entry claimed. Measured on the test box 2026-09-07.
+  //
+  // This needs NO knowledge of which box it is running on, which is what makes it the right shape: an
+  // entry saying a unit runs on no box is contradicted by that unit running HERE, wherever here is.
+  // The mirror — declared for a box and absent from it — cannot be judged without a box identity this
+  // tree does not carry, and is reported as information rather than as a verdict.
+  const orphanSet = new Set(orphaned);
+  const runningButDeclaredNowhere = liveBases.filter((u) => orphanSet.has(u)).sort();
 
   // THE RATCHET THAT MAKES THIS FILE'S OWN DEFECT UNREPRESENTABLE. An entry with no tracked file states
   // a fact about the tree, and until the lookup went repo-wide it was a fact nothing could check —
@@ -514,7 +522,7 @@ export function unitInventoryVerdict({
   // is why writing one is dangerous" while the tracked file sat one directory over. A reader asking what
   // configuration the client door runs was told, with confidence, to look at nothing.
   const trackedNames = new Set(files);
-  const misdeclared = UNIT_INVENTORY
+  const misdeclared = inventory
     .filter((u) => !u.tracked)
     .filter((u) => ["service", "timer", "path"].some((s) => trackedNames.has(`${u.unit}.${s}`)))
     .map((u) => u.unit).sort();
@@ -529,7 +537,7 @@ export function unitInventoryVerdict({
   // It matters now because the retirement above deletes unit files on a schedule set by production's
   // rebuild rather than by this PR, so entry and tree are deliberately going to disagree for a while,
   // and the disagreement must be the kind that gets reported rather than the kind that is invisible.
-  const claimedAbsent = files.length === 0 || filesError ? [] : UNIT_INVENTORY
+  const claimedAbsent = files.length === 0 || filesError ? [] : inventory
     .flatMap((u) => (u.tracked ?? []).map((f) => ({ unit: u.unit, file: f })))
     .filter((c) => !trackedNames.has(c.file))
     .map((c) => `${c.file} (claimed by ${c.unit})`).sort();
@@ -538,16 +546,16 @@ export function unitInventoryVerdict({
   // reporting every production unit missing on a dev box is a false alarm, and it would train a reader
   // to skim this check. But an arm that did not run is not an arm that passed — this file's whole
   // thesis — so an unnameable box is STATED rather than silently skipped.
-  // ABSENT-AND-EXPECTED-TO-BE vs ABSENT-AND-SHOULD-NOT-BE (, criterion 3). A retired
+  // ABSENT-AND-EXPECTED-TO-BE vs ABSENT-AND-SHOULD-NOT-BE (criterion 3). A retired
   // unit that is gone from a box is the ruling taking effect, not drift; reporting it as a fault trains
   // a reader to skim the arm that would have caught a real one. Both are still REPORTED — the
   // distinction is which of them is a fault.
   const declaredHere = (u) => box && u.runsOn.includes(box) && !liveBases.includes(u.unit);
   const absent = box
-    ? UNIT_INVENTORY.filter((u) => declaredHere(u) && !u.retired).map((u) => u.unit).sort()
+    ? inventory.filter((u) => declaredHere(u) && !u.retired).map((u) => u.unit).sort()
     : [];
   const absentByRetirement = box
-    ? UNIT_INVENTORY.filter((u) => declaredHere(u) && u.retired).map((u) => u.unit).sort()
+    ? inventory.filter((u) => declaredHere(u) && u.retired).map((u) => u.unit).sort()
     : [];
   const boxLine = box ? "" : " The box could not be named, so 'declared here and not running' was NOT "
     + "checked — that half did not run, which is not the same as passing.";
@@ -572,6 +580,11 @@ export function unitInventoryVerdict({
       + "A unit nothing declares is compared against nothing and reported by nothing — add it to "
       + "driver/unit-inventory.mjs, tracked or with the reason it is not.");
   }
+  if (runningButDeclaredNowhere.length) {
+    faults.push(`${runningButDeclaredNowhere.join(", ")} — ${runningButDeclaredNowhere.length} unit(s) are `
+      + `RUNNING on this box while their inventory entry declares runsOn: [], so every check scoped to `
+      + `the declared list is judging a population that excludes them`);
+  }
   if (misdeclared.length) {
     faults.push(`${misdeclared.length} entr(y/ies) claim NO tracked file while a unit file of that name is `
       + `in the tree: ${misdeclared.join(", ")}. The entry is not merely incomplete, it is false — and a `
@@ -618,8 +631,8 @@ export function unitInventoryVerdict({
   return {
     state: "pass", undeclared, orphaned, absent, misdeclared, claimedAbsent, absentByRetirement,
     message: `${liveBases.length} live unit(s), all declared; `
-      + `${UNIT_INVENTORY.filter((u) => u.tracked).length} entr(y/ies) tracked, `
-      + `${UNIT_INVENTORY.filter((u) => u.runsOn.length && !u.tracked).length} live-and-untracked BY DECLARATION `
+      + `${inventory.filter((u) => u.tracked).length} entr(y/ies) tracked, `
+      + `${inventory.filter((u) => u.runsOn.length && !u.tracked).length} live-and-untracked BY DECLARATION `
       + `with a stated reason.${retiredLine}${orphanLine}${boxLine}${filesLine}`,
   };
 }
@@ -641,6 +654,53 @@ export function unitInventoryVerdict({
  * @param {string|null} raw  the value `systemctl show -p WorkingDirectory` printed
  * @returns {{path: string|null, prefixes: string, why: string|null}}
  */
+/**
+ * Which checkout is a unit actually serving — and which piece of evidence said so.
+ *
+ * A unit can be attributed two ways and they are not equally good.
+ *
+ * `WorkingDirectory` is a DECLARATION. It is what the unit file asks for, and it is frequently not a
+ * checkout at all: a unit written as `WorkingDirectory=~` reports `!/home/<user>`, which resolves to a
+ * home directory that is not a git tree, and the unit then drops out of the comparison entirely. That is
+ * not a rare shape — it is what a unit looks like when its author put the checkout in `ExecStart=`
+ * instead, which is the normal thing to do, because systemd cannot expand a variable in
+ * `WorkingDirectory=` and can in `ExecStart=`.
+ *
+ * The RUNNING COMMAND LINE is an OBSERVATION: the absolute path the live process was actually started
+ * with. So it wins, and that order is the point rather than a preference. The incident this comparison
+ * exists for is a deployment that served its portal from one clone while running its runner from
+ * another — and in that state the declaration and the process disagree, with the process telling the
+ * truth. Preferring the declaration would take the wrong side of exactly the case the check is for.
+ *
+ * WHEN BOTH RESOLVE AND DISAGREE, that IS the finding, and it is returned rather than quietly resolved:
+ * a unit whose declared tree and running tree differ has been repointed since it started, and it is
+ * serving the older one until something restarts it.
+ *
+ * PURE — the caller does the reading (systemd, the unit file, the process table) and this decides.
+ *
+ * @param {object} a
+ * @param {string|null} a.declaredTree  a git tree resolved from `WorkingDirectory`, or null
+ * @param {string|null} a.runningTree   a git tree resolved from the live process's argv, or null
+ * @param {string|null} a.declaredWhy   why the declaration gave nothing, if it gave nothing
+ * @param {string|null} a.runningWhy    why the process gave nothing, if it gave nothing
+ * @returns {{clone: string|null, source: string|null, disagreement: string|null, why: string|null}}
+ */
+export function unitClone({ declaredTree = null, runningTree = null, declaredWhy = null, runningWhy = null } = {}) {
+  const norm = (p) => String(p ?? "").replace(/\/+$/, "") || null;
+  const declared = norm(declaredTree);
+  const running = norm(runningTree);
+  const disagreement = declared && running && declared !== running
+    ? `the unit declares ${declared} and its running process was started from ${running} — it is serving the second until something restarts it`
+    : null;
+  if (running) return { clone: running, source: "the running command line", disagreement, why: null };
+  if (declared) return { clone: declared, source: "WorkingDirectory", disagreement, why: null };
+  // BOTH REASONS, never the first one that came to hand. A caller that reports only "no WorkingDirectory"
+  // sends the next reader to fix a unit file when the process table was the half that could not be read.
+  const parts = [declaredWhy, runningWhy].filter(Boolean);
+  return { clone: null, source: null, disagreement: null,
+    why: parts.length ? parts.join("; and ") : "neither the unit's WorkingDirectory nor its running command line named a checkout" };
+}
+
 export function unitWorkingDirectory(raw) {
   const s = String(raw ?? "").trim();
   if (!s) return { path: null, prefixes: "", why: "the unit reported no WorkingDirectory" };

package/driver/unit-state-verdict.mjs

@@ -14,9 +14,9 @@
 //
 // Anything that is neither `active` nor `inactive` is a fault. `prelim-driver` is a `Type=oneshot` fired
 // by a 90-second timer, so EVERY drain passes through `activating` — and `activating` landed in that
-// list. The filter tolerated the oneshot at rest and failed it for working. deploy-test.sh gates the
-// hourly test-instance deploy on this script's exit code, so a deploy that happened to land inside a
-// drain window reported the instance unhealthy and exited 1 on a deployment that was fine.
+// list. The filter tolerated the oneshot at rest and failed it for working. The hourly test-instance
+// deploy gates on this script's exit code, so a deploy that happened to land inside a drain window
+// reported the instance unhealthy and exited 1 on a deployment that was fine.
 //
 // The bug is not the enumeration — was right to give this three outcomes instead of two. The bug is
 // INVERSE ENUMERATION over an incomplete vocabulary: listing the two states you have seen and calling
@@ -39,7 +39,7 @@
 // The ruling on says "starting and stopping are both tolerated for a one-shot". That is descriptive
 // of the case that was observed, not a restriction: the issue's own Scope section carries no unit-type
 // qualifier, the arm has never been unit-type-aware, and it already tolerates `inactive` for everything.
-// It is also the wrong place to draw the line — deploy-test.sh RESTARTS the long-running services
+// It is also the wrong place to draw the line — the hourly deploy RESTARTS the long-running services
 // immediately before running this check, so `trademark-portal=activating` is the same race with a
 // different unit, and a oneshot-only fix would leave it standing. The unit's Type is still carried into
 // the message so a reader can tell a oneshot mid-fire from a service mid-restart.
@@ -56,16 +56,16 @@
 //
 // ── what this module deliberately does NOT touch: the zero-check ────────────────────────────────
 //
-// 's Scope is one paragraph and it names one thing — the state vocabulary. So the FAULT branch is
-// the only branch whose behaviour changes. 's separate guard, "0 active is not a pass", keeps
+// That Scope is one paragraph and it names one thing — the state vocabulary. So the FAULT branch is
+// the only branch whose behaviour changes. That separate guard, "0 active is not a pass", keeps
 // origin/main's predicate (`ActiveState === "active"`, literally) and origin/main's message.
 //
 // This is not caution for its own sake. An earlier draft of this fix also widened the count to treat
 // transitional units as up, on the reasoning that a oneshot mid-fire is "not nothing". The consequence:
 // {5 services activating, 3 inactive} returned `pass` with a message that began "0 active" — a green
-// tick on the deploy's final gate having confirmed that ZERO services were running. deploy-test.sh
+// tick on the deploy's final gate having confirmed that ZERO services were running. The hourly deploy
 // restarts the long-running services immediately before running this check, so that is the ordinary
-// shape of the box, not a corner. Widening a count to make a message read better is how a guard dies.
+// shape of the instance, not a corner. Widening a count to make a message read better is how a guard dies.
 
 /** The six documented ActiveState values of systemd 255, mapped to what the check must do about them. */
 export const ACTIVE_STATE_MEANING = Object.freeze({
@@ -134,19 +134,27 @@ export function unitsActiveVerdict({ units, probe }) {
   // CHANGES NOTHING HERE. The count below is origin/main's, predicate and message unchanged:
   // `active`, literally, and nothing else. An earlier draft of this fix widened it to count
   // transitional units as up, which defeated this guard outright — {5 activating, 3 inactive} then
-  // returned `pass` with a message that began "0 active", on the deploy's FINAL gate, on a box where
-  // deploy-test.sh has just restarted every long-running service. 's Scope names one thing, the
+  // returned `pass` with a message that began "0 active", on the deploy's FINAL gate, on an instance
+  // where the hourly deploy has just restarted every long-running service. Scope names one thing, the
   // state vocabulary of the FAULT branch above. Transitional units are named in the messages here so
   // they are never swallowed; they are counted as up nowhere.
+  // A unit this inventory declares can be absent from THIS box for a legitimate reason: the inventory
+  // spans prod and test, so on the test box every prod-only entry reports `LoadState=not-found`. So the
+  // count is INFORMATION in the message and never a verdict of its own — a warn here would fire on every
+  // run of the test box and be ignored by the second week. The finding that matters is the mirror of it
+  // and lives in unitInventoryVerdict: a unit RUNNING here whose entry claims it runs on no box.
+  const absentHere = (units ?? []).filter((u) => u.load === "not-found").length;
+  const notHere = absentHere ? `; ${absentHere} declared unit(s) do not exist on this box` : "";
+
   const activeCount = (units ?? []).filter((u) => u.active === "active").length;
   const alsoSeen = (by.transitional.length ? `; ${by.transitional.length} starting or stopping — ${by.transitional.map(label).join(", ")}` : "")
     + (by["at-rest"].length ? `; ${by["at-rest"].length} at rest` : "");
 
   if (activeCount === 0)
     return { state: "skip", message: "systemd --user answered and reported 0 active units — nothing was probed, "
-      + `which is not the same as nothing being wrong${alsoSeen}` };
+      + `which is not the same as nothing being wrong${alsoSeen}${notHere}` };
 
-  return { state: "pass", message: `${activeCount} active`
+  return { state: "pass", message: `${activeCount} active${notHere}`
     + (by.transitional.length ? `; ${by.transitional.length} starting or stopping — ${by.transitional.map(label).join(", ")}, which is a unit doing its job, not a fault` : "")
     + (by["at-rest"].length ? `; ${by["at-rest"].length} at rest` : "") };
 }

package/driver/verify-knockout.mjs

@@ -442,7 +442,7 @@ export const validators = {
       // — the register reads and the per-finding weighed lists, both joined to the store.
       if (m.registerReads !== undefined && m.registerReads !== null) {
         if (!Array.isArray(m.registerReads))
-          return { ok: false, reason: `mark "${m.name}": registerReads must be an ARRAY of { recordId, read } rows, or omitted entirely` };
+          return { ok: false, reason: `mark "${m.name}": registerReads must be an ARRAY of { recordId, read, band? } rows, or omitted entirely` };
         const held = registerRecordIdsFor(runDir, m.name);
         for (const row of m.registerReads) {
           const id = String(row?.recordId ?? "").trim();
@@ -451,6 +451,14 @@ export const validators = {
           if (!read) return { ok: false, reason: `mark "${m.name}": registerReads row "${id}" has an empty read. Omit the row rather than sending an empty one: a filing with no read keeps the card's neutral line, which is true` };
           if (!held.has(id))
             return { ok: false, reason: `mark "${m.name}": registerReads cites "${id}", which is not a record this run holds for that mark. The id must be copied from the filings you were handed — the driver joins it against the store and never takes your word for it` };
+          // The band is OPTIONAL and, when present, is the same closed vocabulary the mark's own rating
+          // uses — the card prints it as this filing's rating, so a word outside the frozen ladder would
+          // put a chip on the page in a dialect the framework does not define. Absence stays free: a read
+          // with no band prints the read and no chip, which is what every run before this one produced.
+          if (row?.band != null && String(row.band).trim()) {
+            if (ladder.length && bandIdx(ladder, row.band) < 0)
+              return { ok: false, reason: `knockout_band_unknown:${m.name}: registerReads row "${id}" carries band "${row.band}", which is not in the frozen ladder (${ladder.join(" / ")}) — rate the filing in the framework's own vocabulary, or omit the band and let the read stand alone` };
+          }
         }
       }
       for (const f of (Array.isArray(m.findings) ? m.findings : [])) {
@@ -490,7 +498,7 @@ export const validators = {
       // THE TYPED RECORD. findings-model.mjs owns the shape; this is where it becomes a GATE.
       // Unconditional — no shape sniffing: this validator only ever reads a chunk THIS run's assess turn
       // just wrote, so a "looks like the old shape, validate it loosely" arm could only ever be a way to
-      // skip the check. A resumed run holding a pre- chunk file fails here and re-asks the turn
+      // skip the check. A resumed run holding a pre-change chunk file fails here and re-asks the turn
       // (pipeline-knockout.mjs koStage logs stage-stale and re-runs), which is the correct outcome: the
       // report renders `net`/`basis`/`evidence[]` and a prose row cannot fill them.
       //

package/driver/verify.mjs

@@ -146,7 +146,7 @@ function nonEmpty(content, min = MIN) {
  * The obvious fix — emit the failing marker INSTEAD of the label — silently breaks the corrective hints.
  * `correctionHint` branches on the label text (`gateway.mjs:2181` on `findings+ledger`, `:2188` on
  * `negative-results|coverage-ledger|audit-trail|findings-heading`), so a renamed token would fall through
- * to a generic hint. 's comment records that arm being removed once already on a reading that was
+ * to a generic hint. That comment records that arm being removed once already on a reading that was
  * true for only one lane, and put back. Appending keeps every existing matcher matching — they all test
  * substrings — and gives the seat the one word it was missing.
  *
@@ -289,7 +289,7 @@ const COMMONLAW_UNAVAILABLE_RE = /(perplexity|marketplace research|common.?law (
 // Deliberately NOT done: loosening the honesty vocabulary. The prose is correct and stays.
 //
 // Driver-bug tokens are never masked. `half_path_unrecognized` says the DRIVER called this validator
-// with a path it does not own; "write NO findings file" is the wrong remedy for that, and pre- the
+// with a path it does not own; "write NO findings file" is the wrong remedy for that, and pre-change the
 // path guard returned before the regex was ever reached. Keep it that way.
 const VETO_NEVER_MASKS = new Set(["half_path_unrecognized"]);
 
@@ -651,7 +651,7 @@ export function parseVerdict(content) {
  * `UPSTREAM_STALE_REPAIR["narrative-refutation"]` re-runs the reviewer at DELIVERY time, long after the
  * verdict gate. Its caller re-reads what the repaired stage wrote — findings.json, the case-law layer —
  * but not `senior-eye-review.md`, which is the one artifact that stage authors. So the reviewer could
- * refuse to sign at 00:52 and the run would deliver on the verdict it settled at 00:22 (,
+ * refuse to sign at 00:52 and the run would deliver on the verdict it settled at 00:22 (
  * `bf21580e`, 2026-08-23: a registration date contradicting the fetched record reached the client).
  *
  * ONE DIRECTION ONLY, and that is deliberate. This returns the file's verdict when it is STRICTER than
@@ -683,7 +683,7 @@ export function verdictHardenedTo(carried, reviewMd) {
 // The two guards must not share a POLICY and they still do not: what separates them is which sections
 // they read, and whether a bullet under a flag is that flag's body. Whether a line is a list item at
 // all is NOT policy — and while each walk carried its own copy of that answer, the copies drifted.
-// taught one of them to see `**1.` and left the other on the pre- pattern, so the walk whose
+// taught one of them to see `**1.` and left the other on the pre-change pattern, so the walk whose
 // job is to decide whether to DISCARD a review quietly became the stricter of the two.
 //
 // Restating the marker in a second place is what made that possible, so it is stated once here. Both
@@ -692,7 +692,7 @@ export function verdictHardenedTo(carried, reviewMd) {
 // The trailing `\*{0,2}` is the bold CLOSER: reviewers write both `**1. [kind: …]** text` (bold around
 // the marker and its tokens) and `**1.** text` (bold around the marker alone). The second counted ZERO
 // on both walks — consistently, so it is not the asymmetry above, but it is the same defect wearing a
-// different style, and 's criterion says a bold-numbered flag must count. It cannot swallow prose:
+// different style, and the criterion says a bold-numbered flag must count. It cannot swallow prose:
 // a single letter or digit must still be followed by its own `.` or `)`, so `**Note.** …` matches nothing.
 const LIST_MARKER = String.raw`(?:\*{0,2})(?:[-*•]|\d+[.)]|[A-Za-z][.)])(?:\*{0,2})\s+`;
 const LIST_LINE_RE = new RegExp(`^${LIST_MARKER}\\S`);
@@ -819,7 +819,7 @@ function parseOn(line) {
 // deferrals`, `Headline, re-derived independently`, `Grounded profiles` and the plan audit.
 //
 // THE HEADLESS FALLBACK IS DELIBERATE AND IT IS NOT A DENYLIST IN DISGUISE. A review with NO corrections
-// heading anywhere still has corrections — 's fixture is exactly that, and 's writes them under
+// heading anywhere still has corrections — the fixture is exactly that, and the writes them under
 // `## Corrections`. So: if the document names a corrections section, ONLY that section is read; if it
 // names none, the whole document is read as before. The fallback cannot reopen this defect, because it
 // only applies to documents that have no section structure to get wrong.
@@ -840,7 +840,7 @@ export const NOT_A_CORRECTIONS_SECTION_RE =
 //
 // THE FAILURE IS SILENT IN THE WORST DIRECTION. An unreadable flag does not error — it is simply not
 // there, and every downstream count agrees with itself about a document it never read. Both directions
-// of 's lesson apply at the LINE level too: too permissive publishes noise as grounds, too strict
+// of the lesson apply at the LINE level too: too permissive publishes noise as grounds, too strict
 // drops the grounds entirely.
 //
 // SCOPE OF THE WIDENING, MEASURED RATHER THAN ASSUMED. Across the 28 distinct reviews on both scratch
@@ -874,7 +874,7 @@ export const opensWithKind = (content) => /^\[kind:/i.test(String(content ?? "")
  * matched and the whole document was skipped". The allowlist fails closed on purpose, and a guard that
  * fails closed silently is how a real defect reads as a clean run.
  *
- * `named: false` is not a fault — it is the headless document 's fixture is built from, and the walk
+ * `named: false` is not a fault — it is the headless document the fixture is built from, and the walk
  * falls back to the whole document. It is reported so a caller can tell the two apart.
  *
  * PURE.
@@ -918,7 +918,7 @@ export function parseCorrections(reviewMd) {
     // underneath as `- "…"` bullets. Those are evidence FOR a correction, not five more corrections,
     // and counting them is how five quoted excerpts became five of the published grounds of a BLOCKING
     // verdict. A review that writes its flags as BULLETS never trips this — no numbered flag is ever
-    // seen, so every bullet stays a flag, which is 's contract and 's fail-safe both intact.
+    // seen, so every bullet stays a flag, which is the contract and the fail-safe both intact.
     // ORDER MATTERS: ask "is this enumerated" FIRST. `**2. [kind: …]` begins with an asterisk, so a
     // bullet test run before the enumerated test swallows every flag after the first as the first
     // one's body.
@@ -1023,7 +1023,7 @@ export function findReviewerCoherenceFlags(md) {
 // divergent arms of one requirement. They are three different contracts:
 //   · commonLawStructural (LIVE) — the common-law findings' prose Coverage ledger still carries these
 //     tokens, and this floor still polices it.
-//   · registerFindings' UNSTAMPED arm (ARCHIVE-ONLY since  M6) — judges pre- archived replays
+//   · registerFindings' UNSTAMPED arm (ARCHIVE-ONLY since  M6) — judges pre-change archived replays
 //     whose seats hand-wrote the prose table. No live run reaches it; replay verdicts get quoted, so
 //     it stays.
 //   · register-digest's LIVE path carries the same three tokens as VALUES through the
@@ -1957,7 +1957,7 @@ export const validators = {
     // So the old floor and the new gate are armed by the SAME condition, and it is this one:
     //   stamped   ⇒ the driver wrote a form, the seat was told not to write a table, and the form is the
     //               whole coverage judgement (below).
-    //   unstamped ⇒ every pre- check applies unchanged, and stages.mjs — reading THIS SAME STAMP —
+    //   unstamped ⇒ every pre-change check applies unchanged, and stages.mjs — reading THIS SAME STAMP —
     //               tells the seat to write the prose table. The two cannot disagree about which
     //               document the run owes.
     //
@@ -1967,7 +1967,7 @@ export const validators = {
     // digest and before it — so NO LIVE RUN reaches here unstamped, and stages.mjs no longer has a
     // second arm to tell a seat to write the prose table. The prose floor below, and the prose-era
     // joins it feeds (findUnaccountedDeferredSlices, findUnverifiedIncompleteCleanClaims), are
-    // therefore DEAD FOR LIVE RUNS and LOAD-BEARING FOR REPLAY: an archived pre- run carries no
+    // therefore DEAD FOR LIVE RUNS and LOAD-BEARING FOR REPLAY: an archived pre-change run carries no
     // stamp at all, and its coverage verdict is judged by exactly this arm.
     //
     // DO NOT DELETE THEM AS DEAD CODE. Removing them does not change any live run's answer; it changes