clearotron 0.2.1 → 0.2.3

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,10 @@ 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
+// ONE CLASSIFIER FOR WHAT A STAFF RULE ADMITS, shared with the setup wizard. Two copies of this
+// judgement would be a wizard that asks about one rule and a launcher that writes another.
+import { classifyStaffDomain, staffDomainRefusal, staffGrantSentence } from "../shared/staff-domain.mjs";
 
 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 +324,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
@@ -366,6 +369,11 @@ export function installPaths(base) {
   };
 }
 
+/** A staff rule this command will not build. Carries the sentence the operator reads, and why. */
+export class StaffDomainRefused extends Error {
+  constructor(domain, message) { super(message); this.name = "StaffDomainRefused"; this.domain = domain; }
+}
+
 /**
  * The one address that signs in, and the staff domain derived from it.
  *
@@ -374,10 +382,61 @@ export function installPaths(base) {
  * it safe here and would not be safe on a hosted instance. Without it the sign-in succeeds and every
  * page 403s, because signing in is not being enrolled (portal-access.mjs decides that, and it is
  * deliberately blind to which door you came through).
+ *
+ * ── AND THAT PARAGRAPH IS ONLY TRUE OF `<account>@localhost` ─────────────────────────────────────────
+ *
+ * "admits exactly that address and nobody else" is a property of the DOMAIN, not of the mode. It holds
+ * for `localhost`. It does not hold for a domain other people have addresses at: the rule this line
+ * produces from `alex@a-firm.example-tld` says *anyone at that domain*, the settings page then reports
+ * it back in those words, and on a deployment where identity arrives from an external login system the
+ * domain is the whole of the check. Nobody was asked, and there is nothing on the box recording that a
+ * grant was made.
+ *
+ * So the derivation now refuses the domains that can never be a staff rule — a webmail provider, a
+ * documentation domain — and hands anything wider than one machine back to the caller to state and
+ * confirm. `shared/staff-domain.mjs` is the one classifier, shared with the setup wizard, so the
+ * question the wizard asks and the rule this command builds cannot drift apart.
+ *
+ * An UNPARSEABLE address still returns `""`, and that is not the same answer as a refusal: nothing was
+ * classified, so nothing was decided. The caller already refuses a non-address one line earlier.
  */
 export function staffDomainFor(email) {
   const at = String(email ?? "").lastIndexOf("@");
-  return at > 0 ? String(email).slice(at + 1).toLowerCase() : "";
+  const domain = at > 0 ? String(email).slice(at + 1).toLowerCase() : "";
+  if (!domain) return "";
+  const refusal = staffDomainRefusal(domain);
+  if (refusal) throw new StaffDomainRefused(domain, refusal);
+  return domain;
+}
+
+/**
+ * What to say when the derived domain is a real one — wider than this machine, and never assumed.
+ *
+ * A REFUSAL RATHER THAN A PROMPT, and the reason is that this command has no reader. `start` runs from
+ * a script, from `--background`, and from a service manager as often as from a terminal; a question
+ * asked there either hangs or is answered by whatever happens to be on stdin. Every other decision on
+ * this boundary already refuses instead — an unset access file, a multi-`@` identity, local mode off
+ * loopback — so this is the idiom the rest of the door speaks.
+ *
+ * The consent itself lives where a person is definitionally present: `clearotron install` asks for the
+ * address, shows this same sentence, and writes the answer down as an explicit `PORTAL_STAFF_DOMAINS`.
+ * After that the `||` above this call short-circuits and the derivation is never reached again.
+ */
+export function wideStaffDomainRefusal({ user, domain, envPath }) {
+  return `${user} would make every address at ${domain} an administrator of this install.\n`
+    + "\n"
+    + `  The rule that would be written is:  ${staffGrantSentence(domain, { staffLabel: `${BRAND.name} staff` })}\n`
+    + "\n"
+    + "  That is a grant to a group, and this command will not make one on your behalf. Pick the one\n"
+    + "  that is true here:\n"
+    + "\n"
+    + `    · only you use this machine — start without --user, or use ${String(user).slice(0, String(user).lastIndexOf("@"))}@localhost.\n`
+    + `      The rule is then this machine and nobody else, and nothing is granted to anyone.\n`
+    + `    · your colleagues at ${domain} should all be administrators — say so once, in writing:\n`
+    + `        PORTAL_STAFF_DOMAINS=${domain}\n`
+    + `      in ${envPath}, or in the environment. The settings page then names that file as where the\n`
+    + "      rule came from, so whoever reads it later can undo it.\n"
+    + `    · run \`${invocationPrefix()}clearotron install\`, which asks for the address and this question with it.`;
 }
 
 /**
@@ -424,9 +483,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 +498,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 +509,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 +678,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;
@@ -780,6 +836,10 @@ if (isMain) {
   // bound anywhere else in any mode. Sign-in is untouched — the demo signs in like any first start, and
   // the portal mints and prints its passphrase exactly as it does for a real one.
   const DEMO = argv.includes("--demo");
+  // THE DEMO BRINGS ITS OWN ACCOUNT. A fresh install resolves `generic` and nothing else (owner
+  // ruling, 2026-09-08), so the demo account is refused from the roster unless somebody asked for it.
+  // Asked here, once and visibly, rather than at each site that happens to read a roster.
+  if (DEMO) process.env.CLEAROTRON_DEMO_PROFILES ??= "1";
   // ── `--port` MOVES EVERY DOOR IT OPENS (tracker issue 166) ───────────────────────────────────────
   //
   // It used to move ONE of the three. `resolvePorts` reads three independent variables with three
@@ -815,16 +875,47 @@ if (isMain) {
     run: (cmd, args) => spawnSync(cmd, args, { cwd: REPO, stdio: "inherit", shell: process.platform === "win32" }).status ?? 1,
   });
 
-  // Nobody is asked for this. A local install has one user, this machine already knows their name, and
-  // the address never leaves the machine — `--user` is there for a reader who wants their real one, and
-  // whatever is resolved here is written to `.env` so the question is never put twice.
+  // The ADDRESS is not asked for here: a local install has one user, this machine already knows their
+  // name, and the address never leaves the machine — `--user` is there for a reader who wants their real
+  // one, and whatever is resolved here is written to `.env` so the question is never put twice. What IS
+  // asked for, and used not to be, is the staff rule the address implies once it is a real one; that is
+  // the block below the address, and `clearotron install` is where the question is actually put.
   let whoami = "user";
   try { whoami = userInfo().username || "user"; } catch { /* a container with no passwd entry */ }
   // In a demo the address is the demo's own and is never written anywhere: see the DEMO block above.
   const user = String(flag("--user", DEMO ? "demo@localhost" : (process.env.PORTAL_LOCAL_USER || `${whoami}@localhost`))).trim().toLowerCase();
   if (!user.includes("@") || user.indexOf("@") !== user.lastIndexOf("@"))
     fatal(`--user "${user}" is not a single email address. It is the one identity that signs in here, and the portal refuses a multi-@ identity outright.`);
-  const staffDomains = process.env.PORTAL_STAFF_DOMAINS || staffDomainFor(user);
+  // ── THE STAFF RULE THIS ADDRESS IMPLIES, STATED BEFORE IT IS WRITTEN ──────────────────────────────
+  //
+  // An explicit `PORTAL_STAFF_DOMAINS` is a decision somebody already made in writing, and it wins
+  // untouched — including a domain the classifier would otherwise refuse, because an operator who
+  // typed it has said what they mean and this command does not overrule that.
+  //
+  // Absent one, the rule is DERIVED from the single address, and that derivation is the defect this
+  // block exists to close. Three outcomes:
+  //
+  //   `localhost` (or any bare hostname)  — one machine, no second person, nothing to ask. Silent, as
+  //                                         it has always been. This is the default path and the only
+  //                                         one a laptop ever reaches.
+  //   a webmail or documentation domain   — refused by `staffDomainFor` itself; there is no yes that
+  //                                         makes it right.
+  //   any other real domain               — refused HERE, with the rule quoted in the words the
+  //                                         settings page uses and the three ways out named.
+  //
+  // BEFORE THIS RUN CHANGES THE BOX, deliberately — it sits above the state-written divide further
+  // down, with the units gate, the auth-mode gate and the port probe. A refused start has written no
+  // `.env`, minted no secret and placed no unit, so the reader's only question — is my install
+  // half-made — has one answer.
+  let staffDomains = process.env.PORTAL_STAFF_DOMAINS;
+  if (!staffDomains) {
+    let derived = "";
+    try { derived = staffDomainFor(user); }
+    catch (e) { fatal(e.message); }
+    if (derived && classifyStaffDomain(derived) === "wide")
+      fatal(wideStaffDomainRefusal({ user, domain: derived, envPath: ENV_PATH }));
+    staffDomains = derived;
+  }
 
   say("");
   say(`  ${BRAND.name} ${BRAND.product.toLowerCase()} — local install`);
@@ -834,7 +925,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 +948,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 +983,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 +1051,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 +1339,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 +1502,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 +1562,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 +1581,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 +1590,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 +1599,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.
@@ -1577,10 +1668,40 @@ if (isMain) {
       // sequence rather than a race between the terminal's signal and ours. It also means the group
       // kill below reaches anything a child spawns, not just the child.
       detached: true,
-      stdio: ["ignore", "inherit", "inherit"],
+      // — STDERR IS TEED RATHER THAN INHERITED, AND ONLY STDERR.
+      //
+      // These children announce a refusal as one FATAL line on stderr and exit 1. With `inherit` the
+      // parent holds no copy, so the failure message below could only point at output it had never seen —
+      // and on one report that output never reached the reader's terminal at all. It said "its own output
+      // above says why" about a line that was not above, which is worse than saying nothing: it sends
+      // somebody scrolling for a sentence they will not find.
+      //
+      // stdout stays inherited. It carries no refusal — measured: on a refusing door stdout is empty and
+      // stderr holds the whole of it — and leaving it alone keeps the child's terminal detection and any
+      // progress rendering intact. Piping a stream costs the child its TTY, so only the stream that has to
+      // be read is piped.
+      stdio: ["ignore", "inherit", "pipe"],
       env: { ...process.env, ...env },
     });
-    const rec = { name, script, child, alive: true };
+    // The last lines of that child's stderr, forwarded on as they arrive so nothing is delayed or
+    // swallowed, and kept so the failure can QUOTE them rather than refer to them.
+    const tail = [];
+    // A CHUNK IS NOT A LINE. `data` arrives on whatever boundary the pipe gives us, so a stream split
+    // mid-sentence would push two half-lines and the quoted last words would reach the reader cut in
+    // half — on precisely the message that exists because they could not see the original. The partial
+    // remainder is held over and completed by the next chunk; whatever is left when the stream ends is
+    // flushed, because a process that dies mid-line still said the thing it was saying.
+    let pending = "";
+    const keep = (line) => { if (line.trim()) tail.push(line); while (tail.length > 12) tail.shift(); };
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      process.stderr.write(chunk);
+      const parts = (pending + String(chunk)).split("\n");
+      pending = parts.pop() ?? "";
+      for (const line of parts) keep(line);
+    });
+    child.stderr?.on("end", () => { keep(pending); pending = ""; });
+    const rec = { name, script, child, alive: true, tail };
     children.push(rec);
     child.on("exit", (code, signal) => {
       rec.alive = false;
@@ -1593,7 +1714,7 @@ if (isMain) {
           + ` but nothing is draining the queue now. Start one with:\n    node ${script} --watch\n`);
         return;
       }
-      err(`\nstart: ${name} (${script}) exited ${signal ? `on ${signal}` : `with code ${code}`} — its own output above says why. Stopping the rest.\n`);
+      err(childExitReport({ name, script, code, signal, tail }));
       void shutdown(1);
     });
     child.on("error", (e) => {
@@ -1601,7 +1722,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`);
@@ -1864,3 +1985,25 @@ if (isMain) {
   say("  — same product, managed by systemd, and it survives logout.");
   say("");
 }
+
+/**
+ * What a reader is told when a child this install cannot run without exits.
+ *
+ * QUOTED, NOT POINTED AT. This used to end "its own output above says why" while the parent inherited
+ * the child's stderr and therefore held no copy of it. On one report that output never reached the
+ * reader's terminal at all, so the sentence sent somebody scrolling for a line that was not there —
+ * worse than saying nothing, because it reads as a working instruction.
+ *
+ * An empty tail is reported as an empty tail. A child that exits silently is a finding about the child,
+ * and printing a heading with nothing under it would hide exactly that.
+ *
+ * PURE, and exported, so this can be driven without starting a supervisor — the failure path of a
+ * process manager is the one nobody exercises by hand.
+ */
+export function childExitReport({ name, script, code, signal, tail = [] }) {
+  const how = signal ? `on ${signal}` : `with code ${code}`;
+  const said = tail.length
+    ? `Its last line${tail.length > 1 ? "s" : ""}:\n${tail.map((l) => `    ${l}`).join("\n")}\n`
+    : "It exited without printing anything, which is itself the thing to report.\n";
+  return `\nstart: ${name} (${script}) exited ${how}. Stopping the rest.\n${said}`;
+}

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": "5c8eca66a5f226dde9e1d01affd63da4eda61bbd",
+  "version": "0.2.3"
 }

package/demo/full-country-search/run/_driver/framework.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "framework_key": "house-default",
   "title": "Generic default risk framework",
-  "source_deck": "Generic house default — IP Risk Assessment Framework.pptx (Privileged & Confidential), completed by the reviewing lawyer 2026-08-31; supersedes the 2026-07-05 transcription (doc 50), which was partial",
+  "source_deck": "Cordillera house risk framework, authored in-house and reviewed by counsel; 2026-08-31 revision",
   "entity_label": "the company",
   "bands": [
     {

package/demo/global-preliminary-search/run/_driver/framework.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "framework_key": "house-default",
   "title": "Generic default risk framework",
-  "source_deck": "Generic house default — IP Risk Assessment Framework.pptx (Privileged & Confidential), completed by the reviewing lawyer 2026-08-31; supersedes the 2026-07-05 transcription (doc 50), which was partial",
+  "source_deck": "Cordillera house risk framework, authored in-house and reviewed by counsel; 2026-08-31 revision",
   "entity_label": "the company",
   "bands": [
     {

package/demo/knockout-search/run/_driver/framework.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "framework_key": "house-triage",
   "title": "House knockout triage ladder (Stage 0)",
-  "source_deck": "Ported from the interactive knockout-searches skill's 5-tier rating system (SKILL.md rating table + calibration rules), doc 50 shape",
+  "source_deck": "Cordillera house triage scale for knockout screening, authored in-house; five rating tiers",
   "entity_label": "the client",
   "bands": [
     {

package/demo/multi-country-focus-search/run/_driver/framework.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "framework_key": "house-default",
   "title": "Generic default risk framework",
-  "source_deck": "Generic house default — IP Risk Assessment Framework.pptx (Privileged & Confidential), completed by the reviewing lawyer 2026-08-31; supersedes the 2026-07-05 transcription (doc 50), which was partial",
+  "source_deck": "Cordillera house risk framework, authored in-house and reviewed by counsel; 2026-08-31 revision",
   "entity_label": "the company",
   "bands": [
     {