clearotron 0.2.0 → 0.2.2

package/bin/start.mjs

@@ -75,7 +75,7 @@
 // long-lived engine credential is written to disk by a command whose job is to show you the product.
 
 import { envLocalPath, envFileRead } from "../shared/env-local.mjs";   // side effect: apply this install's .env when THIS file is the CLI entry (never on library import)
-import { systemdFailure, systemdSaid, CAPTURE_STDERR } from "../shared/systemd-failure.mjs";   // tracker issue 203 — a refusal, not a stack trace
+import { systemdFailure, systemdSaid, CAPTURE_STDERR } from "../shared/systemd-failure.mjs";   // a refusal, not a stack trace
 import { writeSecretFile } from "../shared/secret-file.mjs";   // one atomic write for every file holding credentials, and it creates the directory
 // — ONE AUTHORITY for what a clearance needs from its environment, used twice
 // below: to COMPOSE the units' environment and to GUARD it before this command reports success. The
@@ -129,7 +129,7 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-p
 import { productIdentity } from "../shared/product-identity.mjs";   // AGPL §13 — one answer, three surfaces
 import { pinEnvAll } from "../shared/env-aliases.mjs";   // — a pin that names one spelling has set nothing that wins
 import { BRAND } from "../shared/brand.mjs";   // — the installer's own name, from the tenant seam
-import { rebuildIfStale } from "../shared/bundle-rebuild.mjs";   // tracker issue 160 — never serve a bundle older than its sources
+import { rebuildIfStale } from "../shared/bundle-rebuild.mjs";   // never serve a bundle older than its sources
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 const ENV_PATH = envLocalPath({ repoRoot: REPO });   // resolved, never composed: one resolver, so moving this file later is one line
@@ -321,7 +321,7 @@ export function portsForFlag(portFlag, ports, env = {}) {
 /**
  * Where the grants file is, for a command that is NOT the supervisor.
  *
- * — bb8's F13. `start` injects CLEAROTRON_ACCESS_FILE into the environment of
+ * — found in review. `start` injects CLEAROTRON_ACCESS_FILE into the environment of
  * the services it supervises (see the child env below) and never persists it, so the door finds the
  * roster and every sibling CLI in the operator's own shell does not. `clearotron grant` then refused
  * with "Set CLEAROTRON_ACCESS_FILE" — a variable nothing writes — and enrolling a client had no working
@@ -424,9 +424,12 @@ const unitTypeOf = (u) => {
 // cost is the admission cap: counts are serial per queue while queues drain concurrently, so two
 // claimers can overshoot a per-account cap by a bounded one per queue. A bounded overshoot is not a
 // reason to leave a retired unit running when disarming it is one call.
-export const BACKGROUND_RETIRED = Object.freeze([
-  "prelim-driver.service", "prelim-driver.timer", "prelim-driver.path",
-]);
+// EMPTY, AND KEPT RATHER THAN DELETED. The retired path-watcher/timer units it named are gone from the
+// tree, so naming them here would describe files this repo does not ship — which is exactly what the
+// "every retired unit is a unit this repo actually ships" check refuses. The export stays because the
+// next retirement wants somewhere to go, and an empty list is a statement that nothing is currently
+// retired-but-shipped.
+export const BACKGROUND_RETIRED = Object.freeze([]);
 
 export const BACKGROUND_EXCLUDED = Object.freeze({
   // ── `clearotron-client-mcp.service` LEFT THIS TABLE ON 2026-09-03, AND SAYING SO IS THE POINT ────
@@ -436,7 +439,7 @@ export const BACKGROUND_EXCLUDED = Object.freeze({
   // that included it would have made that consent meaningless. That reasoning was right under that
   // ruling and the exclusion was not an oversight.
   //
-  // The owner superseded it knowingly (, settled point 2): the door auto-starts with
+  // The owner superseded it knowingly (settled point 2): the door auto-starts with
   // the product and the per-account key is the gate. It is now in SERVER_INSTALL_SET — which IS
   // BACKGROUND_UNITS — and the pin/exclusion partition means it cannot be in both, so the row is gone
   // rather than reworded. `--background` writes its settings from `enablePlan` before installing it.
@@ -447,12 +450,6 @@ export const BACKGROUND_EXCLUDED = Object.freeze({
   // because production runs them today and deleting them would remove the only tracked description of a
   // live service. An exclusion reason is required to be a sentence, and the true sentence is that the
   // unit is going — not that a workstation should not start it.
-  "prelim-driver.service": "RETIRED with the path-watcher/timer drain posture (owner ruling 2026-08-26, restated 2026-08-31) — clearotron-worker.service is the drain, and this file survives only until production's rebuild",
-  "prelim-driver.timer": "RETIRED with prelim-driver.service — the 90s pull the worker's --watch replaces",
-  "prelim-driver.path": "RETIRED with prelim-driver.service — the queue watcher whose glob a documented install never writes",
-  "prelim-outbox.service": "the delivery outbox drains toward real clients — a production lane, not something a workstation should start by default",
-  "prelim-outbox.path": "the outbox watcher — excluded with its service",
-  "prelim-outbox.timer": "the outbox sweep — excluded with its service",
   "profile-service.service": "the portal constructs the profile service IN-PROCESS (driver/portal-service.mjs); the standalone unit is the separate-editor deployment shape and running both double-serves the store",
 });
 
@@ -622,7 +619,7 @@ if (isMain) {
   const argv = process.argv.slice(2);
   const say = (s = "") => process.stdout.write(`${s}\n`);
   const err = (s) => process.stderr.write(`${s}\n`);
-  // Flipped at the first state-changing act ('s third criterion): a refusal AFTER
+  // Flipped at the first state-changing act (the third criterion): a refusal AFTER
   // writes must say what survives and that re-running is safe — the reader's only question at that
   // moment, and one the screen never answered while the writes sat above the port probe.
   let wroteState = false;
@@ -834,7 +831,7 @@ if (isMain) {
   say(`  reports        ${paths.pool}`);
   say(`  signs in as    ${user}`);
 
-  // ── THE PORTS, PROBED BEFORE ANYTHING IS WRITTEN ('s sibling,) ──
+  // ── THE PORTS, PROBED BEFORE ANYTHING IS WRITTEN (the sibling,) ──
   //
   // This block used to sit in section 4, after the secrets were minted, the data plane created, the
   // grants file written and an example report seeded. So a box where another copy already held the port
@@ -857,7 +854,7 @@ if (isMain) {
     s.once("listening", () => s.close(() => resolve(null)));
     s.listen(port, HOST);
   });
-  // ALL THREE DOORS, NOT TWO ( — bb8's F11). The client door's port is resolved
+  // ALL THREE DOORS, NOT TWO (found in review). The client door's port is resolved
   // beside the other two, three lines up, and was left out of the loop written for exactly this
   // principle. So a held client port was discovered AFTER the portal and the engine door had bound: the
   // run fatalled mid-flight, tore down what it had started, and then did not exit — measured at rc=124
@@ -892,7 +889,7 @@ if (isMain) {
         continue;
       }
     }
-    // 's wording, not a second copy of it. That helper already distinguishes EADDRINUSE from EACCES
+    // That wording, not a second copy of it. That helper already distinguishes EADDRINUSE from EACCES
     // on a privileged port and from an address this host does not have, and names the way out of each;
     // the launcher having its own shorter sentence for one of the three would mean a user meets two
     // different answers to the same question depending on which door refused first.
@@ -960,7 +957,7 @@ if (isMain) {
     catch (e) { fatal(`could not create the grants file at ${paths.grants} (${String(e?.message ?? e)}).`); }
     say(`  created        ${paths.grants} (an empty roster — one staff address, no clients yet)`);
   }
-  // THE REVOCATION LIST, CREATED — not merely named (, bb8's F14).
+  // THE REVOCATION LIST, CREATED — not merely named (found in review).
   //
   // The door is started with TRADEMARK_MCP_TOKEN_DENYLIST pointing here, and since this branch
   // `isRevoked` fails CLOSED on an unreadable file — it refuses the token rather than assuming it was
@@ -1057,6 +1054,12 @@ if (isMain) {
     // — `clearotron demo` hands over to this — so fixing the player alone left the defect where it was.
     const { publishSource } = await import("../driver/demo-container.mjs");
     const seed = await seedPool({ pool: paths.pool, examplesDir: publishSource(join(REPO, "demo"), { repoRoot: REPO }), republish: republishRun });
+    // WHAT WAS ALREADY THERE IS SAID TOO (tracker issue 277). This branch used to run only when the pool
+    // was empty; it now tops a stale pool up to the package's set, so "seeded 1" on an upgrade is a fact
+    // about what was MISSING and says nothing on its own about how many are now listed.
+    if (seed.already?.length) {
+      say(`  archive        ${seed.already.length} example report(s) already published here`);
+    }
     if (seed.seeded.length) {
       say(`  seeded         ${seed.seeded.length} example report(s) into ${paths.pool}`);
       // THE LABEL. is delivered: the report now carries the owner's own sample sentence on its
@@ -1070,6 +1073,7 @@ if (isMain) {
     }
     // Never a silent nothing. "The archive is empty" and "the archive is empty and nobody noticed why"
     // look identical in the browser, so both other outcomes are said out loud.
+    if (seed.skipped) say(`  archive        ${seed.skipped}`);
     for (const p of seed.problems) err(`  WARNING: sample seeding — ${p}`);
   } catch (e) {
     err(`  WARNING: the example report could not be seeded (${String(e?.message ?? e)}) — the archive will come up empty. Everything else works; \`npm run example\` shows a sample without touching this install.`);
@@ -1241,7 +1245,7 @@ if (isMain) {
       } catch { /* no file yet — the union is the whole of it */ }
       // ONE COMPOSER for "where do I set these", used by the start-time refusal and by the order-time
       // announcement below it. Two copies of this sentence is how one of them comes to name a file the
-      // reader cannot use — which is the whole of tracker issue 202.
+      // reader cannot use.
       const orderRemedy = (homeEnv) => {
         const cliEnv = envFileRead();
         return cliEnv
@@ -1404,7 +1408,7 @@ if (isMain) {
     // deriving the bus at two of them is worse than at none: `enable --now` would succeed against the
     // derived bus while the health read three screens down still asks the bus-less one, so every unit
     // would start and then be reported as not running. Driven into by accident while building
-    // tracker issue 203 — "4 of 4 unit(s) did not come up" over four units that had just been enabled.
+    // "4 of 4 unit(s) did not come up" over four units that had just been enabled.
     // Making all five derive it is a real improvement to the install path and is its own change with its
     // own drive, not a side effect of repairing a refusal.
     try { execFileSync("systemctl", ["--user", "daemon-reload"], CAPTURE_STDERR); }
@@ -1464,7 +1468,7 @@ if (isMain) {
     }
     // enable --now on an ALREADY-ACTIVE unit is a no-op, so a refresh would leave the old process
     // running the old files. EVERY long-running unit in the set is restarted, not a hardcoded pair
-    // (, Hera's review): the pair here matched the pair the health check used three
+    // (found in review): the pair here matched the pair the health check used three
     // lines down, and carried the same stale justification about "the oneshot and its triggers". There
     // is no oneshot in the set. So a refresh restarted the portal and the engine door onto new code and
     // left the worker and the client door on the old — while the check below now reports all four up,
@@ -1483,7 +1487,7 @@ if (isMain) {
     // reintroduce it through a second door.
     //
     // The restart keeps the port and the key: both live in the unit's environment and the access file,
-    // not in the process. That is tracker issue 228's criterion 2, and it is why this is a restart
+    // not in the process. That is why this is a restart rather than a re-place
     // rather than a re-place.
     if (adoptedClientDoor && !backgroundRefresh) {
       try { execFileSync("systemctl", ["--user", "restart", CLIENT_DOOR_UNIT], { stdio: "ignore" }); }
@@ -1492,7 +1496,7 @@ if (isMain) {
 
     // STARTED IS NOT RUNNING (the connect lesson): settle, then read each service's own state.
     //
-    // EVERY UNIT THIS FLAG INSTALLS, DERIVED FROM THE SET ( — bb8's F15). This checked
+    // EVERY UNIT THIS FLAG INSTALLS, DERIVED FROM THE SET (found in review). This checked
     // a hardcoded PAIR while `enable --now` had just started FOUR. So a client door crash-looping against
     // a held port got no ✗, was never named in the banner, and `start --background` printed its success
     // block and exited 0 over a product that was two-thirds up. The worker was unchecked for the same
@@ -1501,7 +1505,7 @@ if (isMain) {
     // The comment here used to justify the gap: "the oneshot worker and its timer/path are judged by
     // being enabled". That is stale — clearotron-worker.service is `runner.mjs --watch`, Type=simple,
     // Restart=on-failure, and there is no timer or path unit in the install set at all. It described the
-    // retired prelim-* units. A stale justification is worse than none: it reads as a decision.
+    // retired clearotron-* units. A stale justification is worse than none: it reads as a decision.
     //
     // Judged by the unit's OWN declared Type rather than by a list kept here, so a oneshot added to the
     // set later is judged correctly instead of being reported as broken for exiting.
@@ -1594,7 +1598,7 @@ if (isMain) {
       if (stopping) return;
       if (!fatal) {
         err(`\nstart: ${name} (${script}) could not be started: ${String(e?.message ?? e)} — the portal is still up,`
-          + ` but the queue will not drain.\n`);
+          + ` but the queue will not be worked.\n`);
         return;
       }
       err(`\nstart: ${name} (${script}) could not be started: ${String(e?.message ?? e)}\n`);

package/bin/stop.mjs

@@ -19,12 +19,16 @@ import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
+import { systemdSaid, looksLikeBusFailure, busRemedy, CAPTURE_STDERR } from "../shared/systemd-failure.mjs";   // a stop that could not look must not report that it stopped
 import { BACKGROUND_UNITS } from "./start.mjs";
 import { CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
 import { invoke } from "../shared/invocation.mjs";
 
 const UNIT_DIR = join(homedir(), ".config", "systemd", "user");
 const say = (s = "") => console.log(s);
+// ON STDERR, because a refusal that scrolls past in the same stream as the success lines is a
+// refusal a script cannot act on and a reader skims (tracker issue 270).
+const err = (s = "") => console.error(s);
 
 const argv = process.argv.slice(2);
 if (argv.includes("--help") || argv.includes("-h")) {
@@ -39,20 +43,76 @@ if (argv.includes("--help") || argv.includes("-h")) {
 }
 
 let found = 0;
+const failures = [];
 for (const u of BACKGROUND_UNITS) {
   if (u === CLIENT_DOOR_UNIT) continue;   // structurally unreachable (the pin's census forbids it); belt anyway
   const file = join(UNIT_DIR, u);
   if (!existsSync(file)) continue;
   found++;
-  try { execFileSync("systemctl", ["--user", "disable", "--now", u], { stdio: "ignore" }); } catch { /* already down */ }
+  // ── THE STOP IS VERIFIED, AND THE FILE GOES ONLY IF IT WORKED (tracker issue 270) ────────────────
+  //
+  // This was `catch { /* already down */ }` — a COMMENT standing in for a check. The comment guessed why
+  // the call failed, the next line deleted the unit file regardless, and the line after that announced
+  // "stopped and removed". Measured on a test box: `disable --now` failed for want of a session bus, all
+  // four services stayed up on unchanged pids holding all three ports, three unit files were deleted, and
+  // the command exited 0 saying the box ran nothing. The services were then unmanageable — running, with
+  // no unit file to stop them by — which is strictly worse than leaving both alone.
+  //
+  // `is-active` is what decides, not the exit code of the disable, because the exit code is what lied.
+  let stopped = false;
+  let why = null;
+  try {
+    execFileSync("systemctl", ["--user", "disable", "--now", u], CAPTURE_STDERR);
+  } catch (e) {
+    why = systemdSaid(e);
+  }
+  // ASKED AFTER, WHATEVER THE DISABLE SAID. A disable that reported failure may still have stopped it,
+  // and one that reported success may not have — only the state answers.
+  try {
+    const state = execFileSync("systemctl", ["--user", "is-active", u], { ...CAPTURE_STDERR, stdio: ["ignore", "pipe", "pipe"] });
+    stopped = String(state).trim() !== "active";
+  } catch (e) {
+    // `is-active` exits non-zero for an inactive unit, which is the answer we want — but it exits
+    // non-zero for "cannot reach systemd" too, and those must not read the same. The stdout is the
+    // discriminator: an unreachable systemd prints nothing there.
+    const said = String(e?.stdout ?? "").trim();
+    if (said && said !== "active") stopped = true;
+    else why = why ?? systemdSaid(e);
+  }
+
+  if (!stopped) {
+    // NOT DELETED. A running service with no unit file cannot be stopped by any ordinary means.
+    failures.push({ unit: u, why: why ?? "systemd still reports it active" });
+    say(`  COULD NOT STOP ${u} — its unit file is left in place, so it can still be stopped`);
+    continue;
+  }
   try { rmSync(file, { force: true }); } catch { /* already gone */ }
   say(`  stopped and removed ${u}`);
 }
-try { execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" }); } catch { /* no user bus */ }
+// THE COMMENT HERE ALREADY NAMED THE CAUSE AND SHRUGGED AT IT. If there is no user bus, the disables
+// above did not happen either — so this is where that is said.
+try {
+  execFileSync("systemctl", ["--user", "daemon-reload"], CAPTURE_STDERR);
+} catch (e) {
+  const said = systemdSaid(e);
+  err(`  could not ask systemd to reload its units — ${said}`);
+  if (looksLikeBusFailure(said)) err(`\n${busRemedy()}\n`);
+}
 
 if (!found) {
   say("  Nothing was running in the background — no pinned unit is installed on this box.");
   say("  Nothing to do, and nothing was changed.");
+} else if (failures.length) {
+  // THE SENTENCE THAT WAS WRONG. "The background product is stopped and the box runs nothing again" was
+  // printed unconditionally — including on the run where four services stayed up. A reader who is told
+  // that has no reason to look, which is what made the state unmanageable rather than merely wrong.
+  err("");
+  err(`  ${failures.length} of ${found} service(s) could NOT be stopped, and their unit files are left in place:`);
+  for (const f of failures) err(`    ${f.unit}: ${f.why}`);
+  if (failures.some((f) => looksLikeBusFailure(f.why))) err(`\n${busRemedy()}\n`);
+  err("  Nothing was removed for these, so they can still be stopped once systemd can be reached.");
+  err("  The box is NOT idle. This exits non-zero.");
+  process.exitCode = 1;
 } else {
   say("");
   say("  The background product is stopped and the box runs nothing again — plain `clearotron start`");
@@ -60,4 +120,6 @@ if (!found) {
   const door = existsSync(join(UNIT_DIR, CLIENT_DOOR_UNIT));
   if (door) say(`  Your assistant connection is untouched and still up; \`${invoke("disconnect")}\` is what closes it and revokes its key.`);
 }
-process.exit(0);
+// NOT A BARE ZERO. A stop that could not stop something sets `exitCode` above, and exiting 0 here would
+// discard it — printing the refusal and then reporting success, which is the shape this change removes.
+process.exit(process.exitCode ?? 0);

package/bin/update.mjs

@@ -58,7 +58,7 @@ import { liveRunHolds } from "../driver/deploy-live-run-guard.mjs";   // — one
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
 import { readEnvFile } from "./onboard.mjs";
 import { invoke, invocationPrefix } from "../shared/invocation.mjs";   // — name a command the reader can actually type
-import { rebuildIfStale } from "../shared/bundle-rebuild.mjs";   // tracker issue 160 — a pull cannot update an untracked bundle
+import { rebuildIfStale } from "../shared/bundle-rebuild.mjs";   // a pull cannot update an untracked bundle
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 const ENV_PATH = envLocalPath({ repoRoot: REPO });   // resolved, never composed: one resolver, so moving this file later is one line
@@ -155,7 +155,7 @@ function reportRefusal(risky) {
   say("      mv <the-path-above> <somewhere-outside>/");
   say("");
   say(`  then point the variable at the new location in your .env, and run \`${invoke("doctor")}\` to`);
-  say("  confirm it. This command will not move your files for you: where your own doctrine and");
+  say("  confirm it. This command will not move your files for you: where your own instructions and");
   say("  customer records live is your decision, not a side effect of an upgrade.\n");
 }
 
@@ -170,7 +170,7 @@ function reportRefusal(risky) {
  * update` from inside some other repository must not have that repository answered about.
  */
 export function isGitCheckout(repo = REPO, exists = existsSync) {
-  // NO SPAWN HERE, DELIBERATELY. 's arm requires that update.mjs hold exactly ONE spawn site, so
+  // NO SPAWN HERE, DELIBERATELY. That arm requires that update.mjs hold exactly ONE spawn site, so
   // that one helper owns every command and pins `cwd` — "a later addition inherits whatever directory
   // the user happened to be standing in". A `git rev-parse` here was that later addition, and the arm
   // caught it. It is also more than the question needs: a packaged install has no `.git` at all, and a
@@ -276,7 +276,7 @@ export async function update(argv = process.argv.slice(2)) {
     for (const c of holds.claimed) console.error(`    claimed  ${c.id}  pid ${c.pid ?? "unknown"}`);
     for (const sl of holds.slots) console.error(`    slot     ${sl.file}  pid ${sl.pid}`);
     console.error("\n  `npm ci` rebuilds node_modules under whatever is running. Nothing was touched.");
-    console.error("  Wait for the queue to drain, or clear it, and run this again.\n");
+    console.error("  Wait for the queue to empty, or clear it, and run this again.\n");
     return 4;
   }
   if (holds.unreadable.length) {
@@ -292,7 +292,7 @@ export async function update(argv = process.argv.slice(2)) {
   say("\n  Configuration store is outside the checkout. Updating the product.");
   for (const e of entries) say(`    ${e.name}=${e.value} (${e.from})`);
   if (!entries.length) {
-    say("    Nothing set — this install runs the bundled demo customers and our doctrine. That is a");
+    say("    Nothing set — this install runs the bundled demo customers and our instructions. That is a");
     say("    fine way to start, and it means an upgrade has nothing of yours to land on.");
   }
 
@@ -326,7 +326,7 @@ export async function update(argv = process.argv.slice(2)) {
   //
   // The point of running it HERE is that a pull is exactly the moment our files move under a user's
   // overrides. Reported, never judged — an override is a choice, not a fault, and drift is information.
-  say("\n  Doctrine overlay");
+  say("\n  Custom instructions");
   try {
     const report = overlayReport({ baseRoot: config.skillsBaseDir, overlayRoot: config.skillsOverlayDir });
     for (const line of renderOverlayReport(report, { indent: "" })) say(`  ${line}`);
@@ -334,7 +334,7 @@ export async function update(argv = process.argv.slice(2)) {
   } catch (e) {
     // An unreadable overlay throws by design. It must not abort the verb after a successful update: the
     // update DID happen, and exiting nonzero here would tell a script it did not.
-    console.error(`  the doctrine overlay could not be read — ${e.message}`);
+    console.error(`  the custom instructions could not be read — ${e.message}`);
   }
 
   say("\n  Up to date.\n");

package/bin/uspto-sync.mjs

@@ -76,7 +76,7 @@ if (!dbPath) die(`no index path. Pass --db, or set USPTO_LOCAL_DB (the same vari
 //
 // So the old check demanded 43.8 GB for a build that fits in 17, and INSTALL.md told the reader to
 // provision 60. On the free tier that is the difference between "I can try this on the disk I have" and
-// "I cannot", which is the whole of 's Why.
+// "I cannot", which is the whole of the Why.
 //
 // The ratio, the headroom and the arithmetic now live in shared/uspto-index-size.mjs with their
 // provenance, because the same numbers are what the wizard prints and what INSTALL.md promises, and

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "1054d6ef379db87612033acbaa73bdb737b5128c",
-  "version": "0.2.0"
+  "commit": "66760dc4f4b83293e80c8422e0633cdee2aabb41",
+  "version": "0.2.2"
 }

package/docs/DELIVERY.md

@@ -53,7 +53,9 @@ both forms as defence.
 | `msgId` | string | thread with `In-Reply-To:` on the email |
 | `subject` | string | on a clearance, `<the product's own name> — <mark>` (`deliverySubject`, e.g. `Global preliminary search — NOVAPULSE`; the mark falls back to `ref`, then `matter`). On a knockout, `Knockout trademark review — <ref> (N marks)` |
 | `emailBodyHtml` | string | the FULL email body, one self-contained inline-HTML fragment — send **verbatim**, do not re-encode; report + audit links are already inside |
-| `whatsappTo` | string \| null | optional chat recipient |
+| `whatsappTo` | string \| null | the chat recipient: **the person who requested the run**, when a number is held for them. `null` when none is — see `whatsappToReason` |
+| `whatsappToReason` | string \| null | why `whatsappTo` is null. Present only when it is. The packet states the gap rather than quietly routing the notice somewhere else |
+| `whatsappCcOperator` | string \| null | the operator's own copy of the same notice, from the agent roster. `null` when the deployment has switched it off. Independent of `whatsappTo`: either, both or neither may be present |
 | `whatsappText` | string | ready-to-send completion line (includes every report URL) |
 | `url` | string \| null | the run's published report URL — **null for a multi-name knockout**, which has no single report. See below |
 | `reports` | `[{mark, url}]` | one entry per published document, one per name. Written by the KNOCKOUT lane only — **absent** on a clearance packet, whose single document is`url` |
@@ -145,7 +147,9 @@ The filesystem loop below remains equivalent for integrators that do have data-p
    for `state: "delivered", sendPending: true` (backstop).
 2. **Send**: for `delivered`, email `emailBodyHtml` verbatim to the requester behind
    `forwarder`/`forwarderEmail`, `Subject:` = `subject`, `In-Reply-To:` = `msgId`; optionally
-   chat `whatsappText` to `whatsappTo`. For every other kind, `text` is ready to route as-is.
+   chat `whatsappText` to `whatsappTo` and, separately, to `whatsappCcOperator` when present. A null
+   `whatsappTo` with a `whatsappToReason` means nobody is reachable for that requester — surface it, do
+   not redirect the notice to the operator instead. For every other kind, `text` is ready to route as-is.
 3. **Write back**: create a `.sent` marker in the (archived) run dir after a successful send —
    the idempotency guard that prevents double-sends if markers fire twice. Then clear the
    consumed `.pending` files. The MCP verb writes it as JSON

package/docs/RELEASES.md

@@ -8,7 +8,7 @@ nothing else.
 
 ```bash
 npm install -g clearotron          # stable — the tested one
-npm install -g clearotron@beta     # newest — every merge, minutes after it lands
+npm install -g clearotron@beta     # newest — cut when there is something worth testing
 ```
 
 ## What each channel promises
@@ -16,7 +16,7 @@ npm install -g clearotron@beta     # newest — every merge, minutes after it la
 | | `latest` (stable) | `beta` |
 |---|---|---|
 | **Version looks like** | `0.2.0` | `0.2.1-beta.4` |
-| **Cut when** | a beta has passed a full clearance run and a from-scratch install by somebody who has never seen the product, and the owner says go | every merge to `main`, automatically |
+| **Cut when** | a beta has passed a full clearance run and a from-scratch install by somebody who has never seen the product, and the owner says go | when a change lands that is worth testing, or while a stable is being prepared |
 | **Promises** | it installed and ran a real clearance end to end before it was published | it built, and the automated suite passed |
 | **Use it if** | you are running this for real work | you want a fix that landed today, or you are helping test |
 
@@ -35,8 +35,10 @@ suggest for yours.
 
 ## How often
 
-A stable is cut when a beta earns it, which we aim at roughly weekly. Betas arrive whenever something
-merges — several a day when a round is running, none for a day when nothing lands.
+A stable is cut when a beta earns it, which we aim at roughly weekly. **Betas are cut deliberately, days
+apart** — when a change lands that somebody should test, or while a stable is being prepared. They are not
+published on every merge, so `beta` is a version somebody chose to publish rather than whatever merged
+last. Some stables have several betas before them and some have none.
 
 Numbering follows the change, not the calendar: `0.2.x` for fixes, `0.3.0` when a feature lands, `1.0`
 when the hit-list redesign ships.

package/docs/architecture/01-product-overview.md

@@ -3,7 +3,7 @@
 > Part of the architecture pack (`docs/architecture/`). The driver's module tree and the headless
 > integrator contract are in [`driver/README.md`](../../driver/README.md).
 
-The prelim driver turns a plain-language clearance request into a delivered, lawyer-vetted
+The clearotron driver turns a plain-language clearance request into a delivered, lawyer-vetted
 preliminary trademark clearance report. One matter in, one decision out — with the investigation,
 the reasoning, the challenge, and the paper trail in between run by deterministic code that treats
 the model as a reasoning step, never as the orchestrator.
@@ -54,7 +54,7 @@ flowchart LR
     E -.- e2["Client's framework and format;<br/>lawyer vets, then it moves"]
 
     classDef phase fill:#1a3a5c,stroke:#4a90d9,color:#fff
-    classDef note fill:none,stroke:none,color:tracker issue 888,font-size:12px
+    classDef note fill:none,stroke:none,color:#888,font-size:12px
     class A,B,C,D,E phase
     class a2,b2,c2,d2,e2 note
 ```

package/docs/architecture/02-architecture.md

@@ -48,7 +48,7 @@ flowchart TB
         PL["Register-provider plugins<br/>(gateway-hosted tools)"]
     end
 
-    subgraph DRV["The product: prelim driver — plain Node, systemd, no agent sandbox"]
+    subgraph DRV["The product: clearotron driver — plain Node, systemd, no agent sandbox"]
         direction TB
         RUN["runner.mjs<br/>queue drain · claims · dedup · parks"]
         PIPE["pipeline.mjs<br/>stage sequence · gates · clamps · recovery"]
@@ -81,7 +81,7 @@ flowchart TB
     OB -. "wake" .-> AG
     POOL -.-> MCPQ
 
-    classDef product fill:tracker issue 12324f,stroke:#4a90d9,color:#fff
+    classDef product fill:#12324f,stroke:#4a90d9,color:#fff
     class DRV,RUN,PIPE,STG,GWM,ENG,SKL,PROF,PUB product
 ```
 

package/docs/architecture/04-configuration-reference.md

@@ -157,7 +157,7 @@ own declared `model`, or `axisTier(axis)` where it declares none (`register-unit
 — with the thinking tier `thinkingFor()` gives it. There is no fallback rung and no cross-provider tail.
 
 There used to be: a model-failover chain (same-family fallback, then `azure` and `gemini`) gated on a
-multi-provider engine. It is **deleted** (, 2026-08-03). It had never run — no stage ever declared
+multi-provider engine. It is **deleted** (2026-08-03). It had never run — no stage ever declared
 a fallback and the engine gate was never true — so it was dead machinery with a report-HTML block and a
 test attached. It was deleted rather than armed, because arming it means untested code firing for the
 first time in the middle of a production failure, and a silent mid-run model swap changes which model
@@ -188,8 +188,9 @@ deployment may override (verify live values per deployment).
 | Var | Default | Meaning |
 |---|---|---|
 | `CLEAROTRON_WORK_DIR` | `$HOME/trademark/workspace` | Root holding `workspace-<agent>/` (queues, run dirs). Same name as before, new default: it used to be an agent platform's own dot-directory, which README says in bold the engine does not require. Nothing to migrate — the variable's spelling did not change — but **a deployment that ran on the old default and does not pin this variable moves its run directories on upgrade**, and`driver/systemd/prelim-driver.path` / `prelim-outbox.path` hardcode absolute globs that no environment variable can reach (read the units — the literal is in them). Set it explicitly on every deployed box; the units' globs must name the same root. |
+| `CLEAROTRON_CHECKOUT_DIR` | the installed package root | Where the running code lives, and what the service units execute — every unit's `ExecStart` is `${CLEAROTRON_CHECKOUT_DIR}/…`. On a packaged install that is `<home>/app/node_modules/clearotron`, which is npm-owned and **replaced wholesale on upgrade**: an install deletes and recreates that tree, so anything kept inside it does not survive. This is why the settings file lives outside it. A running service holds its own copy of the deleted tree until restarted, so after an upgrade the units serve the OLD code until they are restarted deliberately — including any hand-made unit nobody remembered to restart. |
 | `CLEAROTRON_INSTRUCTIONS_DIR` | `<driver>/skills` | Compute-skills tree; the engine absolutizes `skills/…` refs against it and grants `--add-dir`. |
-| `CLEAROTRON_SKILLS_STORE_STRICT` | unset (warn) | Hard mode for the run door's doctrine-store check (,`driver/skills-store-provenance.mjs`). The door classifies the store `CLEAROTRON_INSTRUCTIONS_DIR` names into the publication gate's three outcomes — **pass**, **fail** (uncommitted changes under the served path, or a HEAD not contained in the main line), **blocked** (could not be determined: git absent, an unreadable ancestor, no main-line ref, or a store no commit tracks). A store affirmatively outside any checkout passes: the walk to the filesystem root must complete with every step readable, so "no git evidence" can never be inferred from a directory this process cannot see. Unset, a non-pass prints one `[preflight]` line to stderr and stamps a `skills-store` event into the run's `_driver/run.jsonl`, and the run proceeds. Set (`1`; `0`/`off`/`false`/`no`/empty do not arm it), any non-pass **refuses the run before any spend** — `blocked` included, because a store whose state nobody can name is not a store anybody can reproduce. |
+| `CLEAROTRON_SKILLS_STORE_STRICT` | unset (warn) | Hard mode for the run door's doctrine-store check (`driver/skills-store-provenance.mjs`). The door classifies the store `CLEAROTRON_INSTRUCTIONS_DIR` names into the publication gate's three outcomes — **pass**, **fail** (uncommitted changes under the served path, or a HEAD not contained in the main line), **blocked** (could not be determined: git absent, an unreadable ancestor, no main-line ref, or a store no commit tracks). A store affirmatively outside any checkout passes: the walk to the filesystem root must complete with every step readable, so "no git evidence" can never be inferred from a directory this process cannot see. Unset, a non-pass prints one `[preflight]` line to stderr and stamps a `skills-store` event into the run's `_driver/run.jsonl`, and the run proceeds. Set (`1`; `0`/`off`/`false`/`no`/empty do not arm it), any non-pass **refuses the run before any spend** — `blocked` included, because a store whose state nobody can name is not a store anybody can reproduce. |
 | `CLEAROTRON_SKILLS_STORE_MAIN_BRANCH` | `main` | Which branch name the check above treats as the main line. A deployment whose config store is on `master` sets this; otherwise that store has no main-line ref to be measured against and every run reports `blocked`. Only the branch name — the check prefers `origin/<name>` and falls back to the local ref. |
 | `CLEAROTRON_MIN_FREE_DISK_MB` | `500` | Free space the run door requires on the filesystem holding `CLEAROTRON_WORK_DIR`, in MB. Below it a run is **refused** before anything is written — a disk that fills mid-run surfaces as a *missing artifact* at some later stage, which is indistinguishable from an engine or provider fault. Not a sizing estimate: one real delivered run measured 5.85 MB, so 500 MB is the line below which the filesystem is in trouble for reasons of its own.`0` disables the check; a non-numeric value **throws** rather than silently disabling it. A disk that cannot be measured is reported and the run proceeds — never read as room. |
 | `CLEAROTRON_REPORTS_DIR` | **none — set it** | Publish pool (web-served). **No default since: unset refuses and names the variable.** It read`/srv/trademark-archive` — a deployed server's real client archive — so a forgotten export published into somebody else's matter, and two entry points already carried hand-written defences against exactly that (`bin/onboard.mjs`, `bin/example.mjs`). Same shape as `CLEAROTRON_DATABASE` and `scripts/purge-runs.mjs`: guessing wrong is expensive, so it does not guess. Read-only surfaces (flag snapshot, status page, MCP options) degrade to "no pool" instead of throwing; anything that writes refuses. `driver/production-pool-guard.mjs` still names `/srv/trademark-archive` on purpose — that constant is a fact about where the archive is, not a default. |
@@ -200,7 +201,7 @@ deployment may override (verify live values per deployment).
 | `CLEAROTRON_OAUTH_BRIDGE` | module-relative `providers/oauth-mcp-bridge/bridge.mjs` | Case-law MCP bridge script. (Portable since the module-relative default; set explicitly only for a bridge outside the repo tree.) |
 | `CLEAROTRON_REGISTER_CALL_LOG` | `~/trademark/telemetry/register-calls.jsonl`, or the existing file wherever it already is | Billing-grade provider-call ledger, shared by whichever ONE register provider is wired — not a vendor artifact. Every read site derives the default from`homedir()` at call time (2026-07-19: two sites had hardcoded a literal account home, splitting the ledger under any other service account — guarded by `test/deployment-hostnames.test.mjs`). |
 | `CLEAROTRON_REGISTER_RECORD_LOG` | **runtime-injected per run**: `<runDir>/_driver/register-record-bodies.jsonl` | Citation-fidelity log: the BODY of every fetched official record. ** moved it INTO the run** — created with the run, unioned into the run's`_records/`, archived and purged with it. There is no retention setting and no cleanup job, because it no longer grows on the box: held globally it reached 432 MB in 61 days on production and needed a rotation timer on every install. **Do not set this by hand** — a fixed value pins every run's bodies to one file and restores the problem. A box upgraded across still holds its old global file; nothing writes or reads it, the driver names it once per process on stderr, and archiving it is one`mv`. An empty log cannot read as verified: the run's successful `record_fetch` rows in the (still global) call ledger are compared against the assembled record set, and a gap is reported as a failure. |
-| `CORSEARCH_CALL_LOG` / `CORSEARCH_RECORD_LOG` | — | **Deprecated, honoured for one release.** The pre- names. Unset on every deployed box (all three ran the homedir default), so what actually protects an upgrade is the filename fallback: a`corsearch-calls.jsonl` / `corsearch-records.jsonl` already on disk keeps being read where it sits. Resolution order is in `providers/_shared/ledger-path.mjs`. |
+| `CORSEARCH_CALL_LOG` / `CORSEARCH_RECORD_LOG` | — | **Deprecated, honoured for one release.** These are the names these two variables carried before the rename. Unset on every deployed box (all three ran the homedir default), so what actually protects an upgrade is the filename fallback: a`corsearch-calls.jsonl` / `corsearch-records.jsonl` already on disk keeps being read where it sits. Resolution order is in `providers/_shared/ledger-path.mjs`. |
 | `CLEAROTRON_BAND_RUN_DIR` | set per dispatch | The run dir the band MCP server writes into, injected per stage — unset means the server has no run to write to and says so rather than guessing one. |
 | `CLEAROTRON_FEEDBACK_DIR` | `<poolRoot>/_feedback` | Where report feedback flags are stored. Beside the pool by default so a deployment that moves the pool moves the flags with it. |
 | `USPTO_LOCAL_DB` | **none — set it to use `uspto-local`** | The local USPTO index (`node:sqlite` + FTS5) that `bin/uspto-sync.mjs` builds and the free US register reads. Named in `.env.example`; this is the reference row. |
@@ -276,7 +277,7 @@ of truncations.
 ### Surfaces beside the driver — portal, demo, e2e harness
 
 These are read by code that ships in this repository but is not a clearance stage. They are here
-because 's rule is about what PRODUCT CODE reads, not about what a run reads.
+because the rule is about what PRODUCT CODE reads, not about what a run reads.
 
 | Var | Default | Meaning |
 |---|---|---|
@@ -286,6 +287,8 @@ because 's rule is about what PRODUCT CODE reads, not about what a run reads.
 | `PORTAL_LOCAL_PASSPHRASE` | unset | **NEVER set this in a file.** An internal one-shot handoff, not an operator control: on a first FOREGROUND start the supervisor mints the passphrase and hands it to the portal it spawns *at the spawn call*, so the closing summary can print the value beside the address rather than sending a first-time reader back into eleven startup log lines for the one value in this product that cannot be read back. It is deliberately absent from the composed child environments, because that composition is what `--background` writes into the units' env file — a passphrase there would be a permanent plaintext copy on disk and the product's own sentence, "it is stored only as a digest", would stop being true. Setting it in any env file recreates exactly that. Lost passphrase: `clearotron passphrase --reset`. |
 | `PORTAL_URL` | `http://127.0.0.1:18802`, or built from `PORTAL_SERVICE_HOST`/`PORTAL_SERVICE_PORT` | Where the deploy tick's live-surface check expects to reach the portal. |
 | `PORTAL_OPS_TOKEN_FILE` | `~/.config/systemd/user/trademark-portal.service.d/secrets.conf` | The systemd drop-in the live-surface check reads `PORTAL_OPS_TOKEN` out of. It reads the FILE rather than the environment so a check run by hand sees the same token the service does. |
+| `CLEAROTRON_CUT_REF` | `HEAD` | Which ref the cut decision reads the version from. **Read only by the release workflow, never set on a deployment.** The jobs that ask about `main` set it to `origin/main` explicitly, because their checkout is pinned to the run's own ref and `HEAD` there is that ref rather than the branch they are deciding about. A job that asks the wrong subject gets a confident wrong answer. |
+| `CLEAROTRON_RELEASE_WAIT_MS` | 25 minutes | How long a requested cut waits for the version pull request to merge itself before giving up. **Read only by the release workflow.** A rehearsal sets it to `0` so the wiring is exercised without holding a runner. Giving up is a quiet success by design — the scheduled run underneath catches a cut whose wait expired — so this budget failing shows up as a slow job rather than a red one. |
 | `CLEAROTRON_AGENT_MCP_URL` | unset (⇒ `null`) | The API-key MCP door advertised to a signed-in client. Null until that door is deployed, and the UI keeps its honest empty state rather than inventing a URL. |
 | `CLEAROTRON_AGENTS` | derived | Comma-separated agent ids for `scripts/purge-runs.mjs` to sweep. |
 | `CLEAROTRON_E2E_DIR` | **none — the script refuses without it** | The config repo's `e2e/` directory. There is one suite and it is not in this repo (owner ruling 2026-08-07), so the comparison script names the variable rather than defaulting anywhere. |