clearotron 0.2.1 → 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
@@ -1248,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
@@ -1411,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); }
@@ -1471,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,
@@ -1490,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" }); }
@@ -1499,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
@@ -1508,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.
@@ -1601,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": "df42f25966148479a5a6d34aba3f82c110a1ba43",
-  "version": "0.2.1"
+  "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/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. |
@@ -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. |

package/docs/architecture/05-config-governance.md

@@ -97,11 +97,11 @@ product doc.
 | **Client allowlist** (`{version, grants:[{email, customer}]}`) | T2 | git + PR on the `CLIENT_ACCESS_MAP` file | see §2 row 4 | LIVE, file-only; surfaced read-only at `admin.access` |
 | **Ops tokens** (scope ops/user, verbs, accounts, TTL) | T4 | `mint-token.mjs` CLI; jti denylist file | operator-held tokens | LIVE, CLI |
 
-## 4b. The install surface names (,)
+## 4b. The install surface names ()
 
 The variables a **customer or installer** ever types carry the product’s own prefix. They are listed
 by name in §5 below and in the upgrade table in INSTALL.md.
-`PRELIM` is the internal codename of the first product this engine shipped and means nothing to a reader
+`CLEAROTRON` is the internal codename of the first product this engine shipped and means nothing to a reader
 who has not read the code. Vendor credentials keep the vendor’s name (`SIGNA_API_KEY`,
 `PERPLEXITY_API_KEY`, `ANTHROPIC_API_KEY`) — that already says who you bought them from.
 
@@ -226,10 +226,13 @@ environment including production**; unset resolves to `null` and throws at first
 
 `CLEAROTRON_WORK_DIR` (~/trademark/workspace since; the two`.path` units
 hardcode the old glob — see 04), `CLEAROTRON_WORKSPACE_PREFIX` (workspace-), `CLEAROTRON_QUEUE_DIR`,
+`CLEAROTRON_CHECKOUT_DIR` (the installed package root every unit's `ExecStart` names; npm-owned and
+replaced wholesale on upgrade, which is why the settings file lives OUTSIDE it — and why a service not
+restarted after an upgrade keeps serving the deleted tree),
 `CLEAROTRON_INSTRUCTIONS_DIR` (config store), `CLEAROTRON_CUSTOMERS_DIR` (config store), `CLEAROTRON_RECIPES_DIR`,
 `CLEAROTRON_REPORTS_DIR` (**no default since — unset refuses**),`CLEAROTRON_RUN_LOCK_DIR`, `CLEAROTRON_OUTBOX_DIR`,
 `CLEAROTRON_STAFF_POOL_ROOT`, `CLEAROTRON_REGISTER_CALL_LOG` (~/trademark/telemetry/…, homedir-derived at
-call time, resolved by existence over the pre- telemetry directory too; the pre-
+call time, resolved by existence over the pre-change telemetry directory too; the pre-
 `CORSEARCH_*_LOG` names remain accepted for one release),
 `CLEAROTRON_REGISTER_RECORD_LOG` (**no longer a box path since ** — the driver injects
 `<runDir>/_driver/register-record-bodies.jsonl` per run; setting it by hand pins every run's record
@@ -255,6 +258,19 @@ drops BACKOFF from the prefix, which the elided spelling this row used to carry
 `CLEAROTRON_OUTBOX_NOPROGRESS_MAX`, `TRADEMARK_MSGID_DOMAIN` (enqueue.local).
 Code-set per stage (not operator-set): `CLEAROTRON_GATHER_AGENT` / `CLEAROTRON_GATHER_SESSION_KEY` / `CLEAROTRON_GATHER_SESSION_ID`.
 
+**Who the completion notice reaches** — `CLEAROTRON_REQUESTER_WHATSAPP` (empty; effect: deployment) is a
+JSON map of requester email or handle → number, and `CLEAROTRON_WHATSAPP_OPERATOR_COPY` (on unless `0`,
+`false` or `no`; effect: deployment) keeps or drops the operator's own copy of the same notice. The two are
+independent: an operator can stop receiving copies of other people's runs without changing who the
+requester notice reaches.
+
+`CLEAROTRON_AGENT_WHATSAPP` above is keyed by AGENT id, and every user of a deployment shares one agent —
+which is why the notice used to reach the operator and never the person who ordered the search. Unset is
+an EMPTY roster and never a demo one: a deployment that configures nothing routes no notice, and the
+delivery record names whose number is missing rather than quietly substituting the operator's.
+`CLEAROTRON_REQUESTER_WHATSAPP` holds contact data; treat it as a mirror-aware value under §6 wherever an
+integrator holds a copy.
+
 ### 5.8 Credentials — T4 (secrets; EnvironmentFile only; mirror-aware — see §6)
 
 `ANTHROPIC_API_KEY`, `CORSEARCH_SESSION_KEY` (fail-closed preflight),
@@ -303,7 +319,7 @@ systemd, writes no heartbeat, and must keep saying "waiting to start" rather tha
 repo** — `git grep process.env.CLIENT_ACCESS` here returns nothing, so they are governed here and
 never appear in the audit).
 
-**Which identity source the portal runs (,) — T4, and it is chosen by name, never inferred.**
+**Which identity source the portal runs () — T4, and it is chosen by name, never inferred.**
 `PORTAL_AUTH_MODE` selects the door: unset or `auth-proxy` (the default for a hosted deployment) means
 any login system in front that authenticates in the browser and forwards a verifiable JWT per request.
 **Any OIDC or JWT proxy is a choice per deployment** — for example Cloudflare Access, which is not a
@@ -318,7 +334,7 @@ values the staff MCP face already reads as `TRADEMARK_MCP_OIDC_ISSUER`, `TRADEMA
 never passed them, which is how one product shipped a provider-agnostic API face and a single-vendor
 web portal.
 
-**ALL FIVE DOORS READ THE FOUR NOW, and 's "the auth mechanism is out of scope" boundary is
+**ALL FIVE DOORS READ THE FOUR NOW, and the "the auth mechanism is out of scope" boundary is
 superseded** (owner, 2026-08-23: an installation brings its own identity provider and this product may
 not force one). The two write services and the client MCP origin gained the set they lacked; the table
 below names every one of the twelve. The client door's four fall back to the staff face's equivalents
@@ -441,6 +457,23 @@ it in CI and nowhere else — on a deployed box it silences the one check that n
 `portal-ui/` has **zero** env config (no `VITE_*`, no `import.meta.env`) — the SPA talks to its
 origin; all portal config lives server-side in portal-service.
 
+### 5.11 Release pipeline — CI only (never set on a deployment)
+
+These are read by the release workflow and by nothing a deployment runs. They are listed here because a
+name absent from this register is a name nobody can look up, not because an operator has any reason to set
+one — and setting either on a box does nothing at all.
+
+`CLEAROTRON_CUT_REF` (default `HEAD`) — which ref the cut decision reads the version from. 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 being decided about. A job that asks about the wrong
+subject gets a confident wrong answer.
+
+`CLEAROTRON_RELEASE_WAIT_MS` (default 25 minutes) — how long a requested cut waits for the version pull
+request to merge itself. A rehearsal sets `0`, so the wiring is exercised without holding a runner. Giving
+up is a quiet success by design and the scheduled run underneath catches what it misses, so a budget that
+is wrong shows up as a slow job rather than a red one — which is why it is written down rather than left
+to be inferred from a timeout.
+
 ## 6. Drift patterns — values that are mirrored by design
 
 Wherever one value must exist in more than one place, name every copy and rotate them in one

package/docs/architecture/06-operations-runbook.md

@@ -110,6 +110,18 @@ and the environment file holding the secrets.
 - **A scheduled gateway restart** (chat-channel session and plugin-loader hygiene) should *defer*
   off live work rather than skip: wait while a run is live, up to a bound, then restart anyway.
   `XDG_RUNTIME_DIR` must be set for `systemctl --user` to work from cron.
+- **Pin the agent id before upgrading an install made before 0.2.2.** The default agent id changed
+  from `clawdi` to `localagent`, and that id is a path segment: runs live under
+  `<workspaceRoot>/workspace-<agent>/studio/prelim-search/`. An install that never set one starts
+  reading an empty workspace, and empty reads as "no runs" rather than as an error. Set **both**
+  variables in the environment file — the gather servers read their own:
+
+  ```
+  CLEAROTRON_DEFAULT_AGENT=clawdi
+  CLEAROTRON_GATHER_AGENT=clawdi
+  ```
+
+  An install that already sets them is unaffected, and a fresh install needs neither.
 - **Integrator-platform upgrades** go through that platform's own guarded upgrade path — dry-run,
   exact-version confirm, stop → update → start. Never `npm i -g` / `pnpm add -g` directly.
 
@@ -242,7 +254,7 @@ the measurement that says so is.
 
 A box upgraded across the rename keeps whatever NAME its **call** ledger already had
 (`corsearch-calls.jsonl`), and across the move keeps whatever DIRECTORY it sits in (the
-pre- telemetry directory), because the resolver reads the file that is there. Read
+pre-change telemetry directory), because the resolver reads the file that is there. Read
 `providers/_shared/ledger-path.mjs` to see which of the four candidates a box resolves to.
 
 ## Access control and instance isolation

package/docs/architecture/09-security-and-data.md

@@ -203,7 +203,7 @@ stylesheets above.
 | **Doctrine** | `skills/`, framework decks, worked examples | The asset; transfers under the definitive agreement. Worked examples derive from real matters — treat as client-adjacent |
 | **Customer profiles** | `profiles/*.json`, context packs, `_audit.log` | Client-identifying by design (names, own brands, competitor lists) — the reason this *pack* names no clients |
 | **Reference library / calibration corpus** | outside the repo | Built on real client matters — **confidential client material, not freely transferable IP**; transfer needs a client-consent/sanitization plan |
-| **Telemetry** | `~/trademark/telemetry/*.jsonl` (a box upgraded across the move keeps the pre- telemetry directory — resolved by existence, oldest first),`_driver/*.jsonl` | Billing-grade provider usage + attempt telemetry; append-only; no automated retention |
+| **Telemetry** | `~/trademark/telemetry/*.jsonl` (a box upgraded across the move keeps the pre-change telemetry directory — resolved by existence, oldest first),`_driver/*.jsonl` | Billing-grade provider usage + attempt telemetry; append-only; no automated retention |
 
 **Posture commitments** (engineering-true, restated from the outward materials): no client data
 trains any model; each client's context is isolated in its profile bundle and frozen per run;

package/docs/decisions/0004-documentation-structure.md

@@ -69,7 +69,7 @@ at runtime.
   exceed the threshold, 15 were already named by an ancestor**, and three one-line additions closed the
   rest. The mechanism was not new — it was unchecked.
 
-  **This paragraph is what 's absence-record predicted it would become.** That record said "a new
+  **This paragraph is what the absence-record predicted it would become.** That record said "a new
   directory ships without a front door and nothing says so", named itself as a known gap rather than a
   mechanism, and ended "if the guard is built later, this paragraph is what it replaces". It has been.