clearotron 0.2.1 → 0.2.2

package/.env.example

@@ -446,7 +446,12 @@ CLEAROTRON_CHECKOUT_DIR=
 # checkout may have moved on since, and a decision made about "whatever HEAD is now" tried to republish
 # an already-released version. Unset falls back to HEAD, which is correct for the cron and for a hand
 # run, where nothing has moved. Read by scripts/release-cut-decision.mjs.
-# effect: deployment
+#
+# DECLARED `deployment` FIRST, AND THAT WAS THE WRONG HALF OF THE DEFINITION. `deployment` is "where
+# input and output live" — a pool root, an outbox, a database path. A git ref is not a location any
+# input or output lives at; it is which subject the decision is taken about, and it changes only whether
+# the pipeline republishes something it already shipped. Nothing a clearance run produces moves.
+# effect: tuning
 CLEAROTRON_CUT_REF=
 
 # How long publishing waits for a parked version run, in whole milliseconds. Unset uses the built-in
@@ -455,3 +460,51 @@ CLEAROTRON_CUT_REF=
 # entirely, which is that script not running at all. Read by scripts/release-await-cut.mjs.
 # effect: tuning
 CLEAROTRON_RELEASE_WAIT_MS=
+
+# ── The local key door's socket ───────────────────────────────
+# Same shape as the two below: read by product code, in neither this file nor the governance table
+# until a private environment-contract ratchet caught it.
+
+# WHERE the local key door listens. Unset means there is no key door and a deployment gets exactly the
+# door it had before — this adds a path, it does not widen the existing one.
+#
+# WHY A SOCKET AND NOT A PORT. This interface serves two populations that authenticate differently:
+# people arriving through a tunnel, who prove themselves with a proxy identity, and programs on the same
+# machine holding a scoped access key, which can never produce one. "Only accept a key from loopback"
+# does not separate them — the tunnel daemon runs on the same machine, so a request forwarded from the
+# internet and one from the local portal arrive with the same peer address. A tunnel forwards to a port;
+# it cannot reach a socket, so the transport is the discriminator.
+#
+# The socket is created 0660, owner and group only, and the mode is set after listen because listen
+# creates the file and the umask decides what it starts as. The door refuses to open at all without a
+# grants file, alongside the authentication bypass, or in token mode — that mode makes the NETWORK door
+# take a key too, which is the thing this exists to prevent.
+#
+# Read by mcp-server/key-socket.mjs.
+# effect: deployment
+TRADEMARK_MCP_KEY_SOCKET=
+
+# ── Who the completion notice reaches ────────────────────────────────────────────────────────────
+# Both arrived with tracker issue 289 and shipped undeclared: they are read by product code and were in
+# neither this file nor the governance table, which six private environment-contract ratchets caught on
+# the next overlay run. Catalogued here on the same terms as the release names above — they are OUR
+# names, read by code that ships.
+
+# WHO the chat notice is addressed to: a JSON object of requester email or handle → number, e.g.
+# {"lisa@tenant.example":"+41...","jordan":"+41..."}. Before this, the notice went to a map keyed by
+# AGENT id, and every user of a deployment shares one agent — so the operator was notified about work
+# other people ordered and the requester was told nothing.
+#
+# UNSET IS AN EMPTY ROSTER, never a demo one. A deployment that configures nothing routes no notice and
+# the delivery record says whose number is missing, by name. The sibling agent map carries invented
+# numbers for offline tests; doing that here would aim a real client's completion notice at a fixture.
+#
+# It holds contact data. Read by driver/stages.mjs (whatsappRouting).
+# effect: deployment
+CLEAROTRON_REQUESTER_WHATSAPP=
+
+# The operator's own copy of the same notice, ON unless this is `0`, `false` or `no`. Independent of the
+# roster above: an operator can stop receiving copies of everyone else's runs without touching who the
+# requester notice reaches. Read by driver/stages.mjs (whatsappRouting).
+# effect: deployment
+CLEAROTRON_WHATSAPP_OPERATOR_COPY=

package/CONTRIBUTING.md

@@ -91,9 +91,9 @@ any writing pass over the documentation, applies to them.
 
 ## The three rules that fail CI
 
-**1. Rebuild `portal-ui/dist` and commit it.** The bundle is committed so a deploy never builds. CI
-rebuilds it from source and requires byte equality, so a change under `portal-ui/src` that ships
-without its rebuilt bundle fails:
+**1. Rebuild `portal-ui/dist` before you push.** The bundle is not committed — CI builds it from
+source and requires byte equality, so a change under `portal-ui/src` that does not build cleanly
+fails:
 
 ```bash
 npm run build:ui

package/INSTALL.md

@@ -41,10 +41,11 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
 - **Node.js >= 22**, and npm. A hard floor: `package.json` declares it, `.nvmrc` pins it, and the free
   US register runs on `node:sqlite`, which ships with FTS5 from Node 22. Node 20 installs and then fails
   at the first US search. `nvm use` picks the pin up.
-- **macOS, Linux, or Windows via WSL2.** Native Windows is not supported: the engine resolves the
-  reasoning CLI the POSIX way, so a native-Windows run refuses at preflight even with the CLI on `PATH`.
-  On Windows, `wsl --install`, then install Node 22 **inside** the Linux distribution and work through
-  this page from there. `npx clearotron demo` is the exception and runs anywhere Node does. A *hosted*
+- **macOS, Linux, or native Windows for the demo; WSL2 with Node 22 for a clearance.** `npx clearotron
+  demo` runs anywhere Node does, native Windows included. A real clearance does not: the engine resolves
+  the reasoning CLI the POSIX way, so a native-Windows clearance refuses at preflight even with the CLI
+  on `PATH`. On Windows, `wsl --install`, then install Node 22 **inside** the Linux distribution and work
+  through this page from there. A *hosted*
   deployment needs Linux for one further thing, the systemd outbox trigger —
   [driver/systemd/README.md](driver/systemd/README.md).
 - **A reasoning CLI on your `PATH`, signed in.** This is the prerequisite people miss. Every stage runs
@@ -126,6 +127,20 @@ passed, and nothing has driven a live register through it.
 **Upgrade production to stables only.** What each channel promises and how often one is cut:
 **[docs/RELEASES.md](docs/RELEASES.md)**.
 
+**Upgrading an install made before 0.2.2: pin the agent id first.** The default agent id changed from
+`clawdi` to `localagent`, and that id is part of a path — your runs live under
+`<workspaceRoot>/workspace-<agent>/studio/prelim-search/`. If you never set an agent id, the upgraded
+install reads a workspace that does not exist yet, and an empty workspace looks like an account with no
+runs rather than like a misconfiguration. Set **both** names in your environment file before starting
+it, because the register-search servers read their own:
+
+```
+CLEAROTRON_DEFAULT_AGENT=clawdi
+CLEAROTRON_GATHER_AGENT=clawdi
+```
+
+If your environment file already sets them, nothing changes. A first-time install needs neither.
+
 The rest of this section is about the two ways a package reaches you, which is a separate question from
 which version it is.
 
@@ -230,9 +245,9 @@ the line between them. Either way nothing is contacted and nothing is billed —
 it starts. Neither runs on a packaged install: the test files are not in the package.
 
 The engine itself has no build step. The **portal UI does** — `portal-ui/` is React + Vite — but its
-built bundle (`portal-ui/dist/`) is **committed to git** and travels in the package, so a clone and a
-tarball install are both already runnable and a deploy never builds. You only need to build after
-changing something under `portal-ui/src`:
+built bundle (`portal-ui/dist/`) is **not committed to git**: it travels in the published package and
+CI builds it, so a tarball install is already runnable while a clone needs one build first. You also
+need to build after changing something under `portal-ui/src`:
 
 ```
 npm run tokens         # regenerate the design tokens from shared/brand.mjs, if colours changed
@@ -276,45 +291,6 @@ Three more things about it are worth knowing before you write one:
 **Or the environment directly** — your shell, a container spec, a systemd `EnvironmentFile`. This is
 what production does, and nothing about it changed.
 
-### An install that used `PRELIM_*` names
-
-The variables an installer types are `CLEAROTRON_*`, and they are the only spelling. The old names are
-not read, not translated and not looked for — a line using one is a line nothing reads.
-
-**Rebuilding is the supported path**, and it is the only one that is tested: `npx clearotron install`
-writes a correct file from scratch, which is the path a new reader walks. If you would rather edit the
-file you have, rename every line in one pass and use the table below — a half-renamed file leaves the
-un-renamed half unset.
-
-| Old name | Write instead |
-|---|---|
-| `PRELIM_ENGINE` | `CLEAROTRON_AI` |
-| `PRELIM_ANTHROPIC_AUTH` · `PRELIM_OPENAI_AUTH` | `CLEAROTRON_AI_BILLING` |
-| `PRELIM_CLAUDE_BIN` | `CLEAROTRON_CLAUDE_PATH` |
-| `PRELIM_CODEX_BIN` | `CLEAROTRON_CODEX_PATH` |
-| `PRELIM_REGISTER_PROVIDER` | `CLEAROTRON_DATABASE` |
-| `PRELIM_POOL_ROOT` · `PRELIM_POOL_URL` | `CLEAROTRON_REPORTS_DIR` · `CLEAROTRON_REPORTS_URL` |
-| `PRELIM_WORKSPACE_ROOT` | `CLEAROTRON_WORK_DIR` |
-| `PRELIM_PROFILES_DIR` | `CLEAROTRON_CUSTOMERS_DIR` |
-| `PRELIM_SKILLS_DIR` | `CLEAROTRON_INSTRUCTIONS_DIR` |
-| `PRELIM_QUEUE_DIR` · `PRELIM_OUTBOX_DIR` | `CLEAROTRON_QUEUE_DIR` · `CLEAROTRON_OUTBOX_DIR` |
-| `PRELIM_GRANTS_FILE` | `CLEAROTRON_ACCESS_FILE` |
-| `PRELIM_NO_ENV_FILE` | `CLEAROTRON_NO_ENV_FILE` |
-| `CF_ACCESS_AUD` · `CLIENT_CF_ACCESS_AUD` | `CLEAROTRON_OIDC_AUDIENCE` · `CLEAROTRON_CLIENT_OIDC_AUDIENCE` |
-| `PRELIM_BRAND_NAME` · `PRELIM_BRAND_TAGLINE` · `PRELIM_BRAND_PRODUCT` | `CLEAROTRON_BRAND_*` |
-| `PRELIM_LANE_<code>` | `CLEAROTRON_NATIVE_LANGUAGE_<code>` |
-| `PRELIM_DELIVERY` | nothing — **retired, see below** |
-
-
-> **A note on the 2026-09-04 rename.** The left column above is HISTORY and keeps the dead spelling on
-> purpose — it is the only thing that makes the table usable, and a text sweep that "corrects" it turns
-> a migration guide into two identical columns. On 2026-09-04 the owner extended the rename to the whole
-> namespace, including the internal variables an installer never types and the two names the August
-> sweep had deliberately exempted as engine internals. There is one prefix now, everywhere, with no
-> compatibility layer and no alias reading: greenfield, no public installs, our own boxes rebuilt rather
-> than migrated. If you are reading this holding a file older than that, the rule is unchanged and
-> simpler than the table: rebuild.
-
 Vendor credentials keep their vendor’s name — `SIGNA_API_KEY`, `PERPLEXITY_API_KEY`,
 `ANTHROPIC_API_KEY` — because those already say who you bought them from.
 
@@ -668,7 +644,7 @@ A run stopped by a **provider rate limit** or parked for **automatic recovery**
 that is the systemd units in `driver/systemd/`. Everywhere else, run the watcher yourself:
 
 ```
-npx clearotron drain --watch
+npx clearotron run-queue --watch
 ```
 
 That polls every 90 seconds for queued jobs and for parked runs whose window has elapsed, and it resumes
@@ -777,11 +753,11 @@ Before the worker ran, that promise was untrue in your favour: confirming queued
 spent until you gave a second command in another terminal.
 
 If you want the old separation — order here, drain deliberately over there — start with `--no-worker` and
-run the drain yourself:
+run the queue yourself:
 
 ```
 npx clearotron start --no-worker
-npx clearotron drain --watch
+npx clearotron run-queue --watch
 ```
 
 A queued job whose worker is not running says so on the portal rather than sitting at "Waiting to start".
@@ -949,6 +925,30 @@ you.
   `TRADEMARK_MCP_AUTH_MODE=cf-access` so the origin re-validates the proxy's JWT rather than trusting
   it — the mechanism is generic, whichever proxy is in front.
 
+**One process, two doors.** A deployment that serves both people arriving through a tunnel and programs
+on the same machine no longer needs to run this service twice. Set `TRADEMARK_MCP_KEY_SOCKET` to a
+socket path and the service listens for a scoped access key there, while its network port continues to
+take the proxy identity and never honours a key. A tunnel forwards to a port and cannot reach a socket,
+so the key path is not addressable from outside the machine; who may present a key is stated by the
+socket's permissions, which the startup lines print beside its path.
+
+This replaces a **second unit run for its authentication shape** — a loopback port in key mode beside
+the tunnel-fronted one — and nothing else. It is not the test-instance-beside-a-live-one arrangement
+described in §8: that separation is about data and ports, it is unaffected, and its seven variables are
+still all required. Removing the auth-shape duplicate is a deployment decision and nothing here does it
+for you.
+
+**Do not set `TRADEMARK_MCP_AUTH_MODE=token` alongside the socket.** That mode makes the network port
+take a key as well, which is what the socket exists to avoid; the service refuses to start and says so.
+
+**Put the socket somewhere only the service's own group can write.** The socket's own permissions decide
+who may *present* a key. Whether the socket can be *replaced* is decided by the directory holding it — a
+process that can remove the file can bind its own listener on the same path, and callers would then
+present their keys to it. That is a different permission from the socket's and it is the one worth
+checking. The service refuses to start if that directory is writable by everyone without the sticky bit,
+and prints the directory's mode beside the socket's on its startup line so the number is readable without
+going to look.
+
 > ⚠ **What does not work is an INTERACTIVE-only sign-in policy on a route an assistant must reach
 > without a browser.** Such a policy demands a login the vendor's servers cannot complete: they present
 > a credential and get a login page back, and the connection fails with nothing useful said on either
@@ -1113,6 +1113,10 @@ that fails at boot, which reads as a broken install rather than as a port alread
 
 Set all seven. Nothing else separates them.
 
+A deployment that once ran the service twice for a different reason — one door needing a key and the
+other a proxy identity — no longer has to; see *One process, two doors* in §9. That is an
+authentication arrangement and has nothing to do with this one. The seven above are still all required.
+
 ## 9. What the integrator supplies
 
 The engine is complete as a clearance-and-report producer. A deployment adds:

package/bin/brandowner.mjs

@@ -288,7 +288,7 @@ export async function add(argv, {
 } = {}) {
   const args = parseArgs(argv);
   if (!args.key) throw new Refusal(`this command needs a brand owner key.${USAGE}`);
-  // A REFUSAL, NOT A STACK (, acceptance: "refuses malformed input BY NAME — key
+  // A REFUSAL, NOT A STACK (acceptance: "refuses malformed input BY NAME — key
   // pattern"). `assertProfileKey` throws a plain Error, and main() deliberately lets a non-Refusal keep
   // its stack because an unexpected throw here is a defect worth debugging. A key an operator typed is
   // not that: it is the first thing this command validates and the most likely thing to get wrong, and

package/bin/clearotron.mjs

@@ -52,7 +52,7 @@ export const VERBS = {
   connect: ["bin/connect.mjs"],
   disconnect: ["bin/disconnect.mjs"],
   run:     ["driver/pipeline.mjs"],
-  drain:   ["driver/runner.mjs"],
+  "run-queue": ["driver/runner.mjs"],
   cancel:  ["bin/cancel.mjs"],
   grant:   ["bin/grant.mjs"],
   key:     ["bin/key.mjs"],
@@ -73,7 +73,7 @@ export const SUMMARY = {
   connect: "connect the assistant you already use — pick it by name and get the one thing it needs",
   disconnect: "close what connect opened and revoke the key it issued — the enrolment stays",
   run:     "run one clearance from a job file",
-  drain:   "do the queued work. THIS SPENDS: hours of model time and real register calls",
+  "run-queue": "do the queued work. THIS SPENDS: hours of model time and real register calls",
   cancel:  "stop one run by name. The rest of the product keeps running, and nothing resumes it",
   grant:   "enrol a client, or list who may see what",
   key:     "issue the key a person's own assistant presents — after you have enrolled them with `grant`",
@@ -135,7 +135,7 @@ const [verb, ...rest] = process.argv.slice(2);
 
   // — EVERY VERB ANSWERS --help, INCLUDING THE TWO WHOSE CHILDREN REFUSE IT.
   //
-  // `run` and `drain` dispatch to driver/pipeline.mjs and driver/runner.mjs, orchestrator entry points
+  // `run` and `run-queue` dispatch to driver/pipeline.mjs and driver/runner.mjs, orchestrator entry points
   // with strict argument parsers and no help path: `--help` came back as `error: unknown flag --help`,
   // exit non-zero. Their parsers are RIGHT to refuse what they do not understand -- that is what makes
   // them fail safe, and showed what the permissive alternative costs (`update --help` performed
@@ -149,7 +149,7 @@ const [verb, ...rest] = process.argv.slice(2);
     console.log(`\n  ${invocationPrefix()}clearotron ${verb} — ${SUMMARY[verb]}\n`);
     console.log(`  Options after the verb are passed through to ${VERBS[verb][0]}, which has no --help of`);
     console.log(`  its own. Run it with no arguments to see what it requires.\n`);
-    if (verb === "run" || verb === "drain") {
+    if (verb === "run" || verb === "run-queue") {
       console.log(`  THIS SPENDS: hours of model time and real register calls. See INSTALL.md §5 and §6.\n`);
     }
     process.exit(0);

package/bin/connect.mjs

@@ -58,7 +58,7 @@ import { checkoutMove, movePosture, describeMove, describeConflict } from "../sh
 import { unitEnvironment, unitValue, couldNotDetermine } from "../driver/unit-environment.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 import { looksLikeBusFailure, systemdSaid, userBusEnv, CAPTURE_STDERR,
-  systemdFailure as sharedSystemdFailure } from "../shared/systemd-failure.mjs";   // tracker issue 203 — `start` needed the same three answers
+  systemdFailure as sharedSystemdFailure } from "../shared/systemd-failure.mjs";   // `start` needed the same three answers
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 // `userBusEnv` and `busRemedy` MOVED TO shared/systemd-failure.mjs, unchanged, because
@@ -372,7 +372,7 @@ export function unitIsHealthy(name, { show = showUnit, pause = settle } = {}) {
   if (error) {
     // ── A BUS THAT COULD NOT BE REACHED IS NOT A DOOR THAT IS DOWN (tracker issue 130) ────────────
     //
-    // Returning false here is what made the operator worse off than before tracker issue 121's fix.
+    // Returning false here is what made the operator worse off than before that fix.
     // The caller renders false as "the door is not open, so no key was issued" — a confident, wrong,
     // client-facing sentence about a door that is `active`, with the real cause discarded. And it is
     // reachable on the ordinary path: a box whose door is already installed and running never calls

package/bin/example.mjs

@@ -41,7 +41,7 @@ import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync,
 import { homedir, tmpdir } from "node:os";
 import { invoke } from "../shared/invocation.mjs";   // — the printed command is resolved once, for the reader who is actually standing there
 import { basename, dirname, join, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
 import { BRAND } from "../shared/brand.mjs";   // — the installer's own name, from the tenant seam
 import { envFrom } from "../shared/env-aliases.mjs";   // — resolves EITHER spelling; names the retired one because that is the live-writable half
@@ -68,7 +68,11 @@ if (has("--help") || has("-h")) {
   const shipped = demoChildren(join(REPO, "demo"));
   if (shipped.length) {
     console.log(`\n  --product takes one of:`);
-    for (const id of shipped) console.log(`    ${id}${id === shipped[0] ? "   (the default, when --product is not given)" : ""}`);
+    // NO "DEFAULT" MARKER (tracker issue 277). This printed "(the default, when --product is not given)"
+    // beside the first id, and kept printing it after the default became ALL of them — so `--help` taught
+    // a reader the exact belief the change removed, in the command it was reported against.
+    for (const id of shipped) console.log(`    ${id}`);
+    console.log(`\n  With no --product, every one of them is published.`);
     console.log("");
   } else {
     // An absence is a finding: a tree with no demo says so rather than printing an empty list.
@@ -96,8 +100,8 @@ const DEMO_ROOT = join(REPO, "demo");
 // disagreed. That file records what a knockout demo carries instead of a report.md, and why this line
 // once let `demo/knockout-search` ship and stay unopenable..
 
-// --run-dir takes a directory outright. --product names a child. Neither given: the first child, and the
-// name is PRINTED below rather than assumed, because "the demo" is about to mean one of several.
+// --run-dir takes a directory outright. --product names a child. Neither given: EVERY child, and the
+// names are PRINTED below rather than assumed, because "the demo" means several.
 const wanted = flag("--product");
 const children = demoChildren(DEMO_ROOT);
 
@@ -180,7 +184,7 @@ const demoBase = resolve(flag("--base") ?? join(homedir(), "trademark-demo"));
 if (flag("--pool") && !has("--once")) die(
   "demo: --pool is for --once, which publishes and exits.",
   "",
-  "The demo serves the portal's own archive, which lives inside its base directory, so a pool chosen",
+  "The demo serves the portal's own archive, which lives inside its base directory, so a reports folder chosen",
   "somewhere else would be published to and never served. Move the whole demo instead:",
   `  ${invoke("demo")} --base <dir>`,
 );
@@ -217,10 +221,10 @@ console.log(`\n  ${BRAND.name} ${BRAND.product.toLowerCase()} — demo\n`);
 console.log(samples.length === 1
   ? `  sample:  ${samples[0].dir}`
   : `  samples: ${samples.length} — ${samples.map((x) => x.name).join(", ")}`);
-console.log(`  pool:    ${poolRoot}\n`);
+console.log(`  reports folder:  ${poolRoot}\n`);
 
 mkdirSync(poolRoot, { recursive: true });
-const { republishRun } = await import(join(REPO, "driver", "publish", "report-registry.mjs"));
+const { republishRun } = await import(pathToFileURL(join(REPO, "driver", "publish", "report-registry.mjs")).href);
 
 // ── ONE FAILURE MUST NOT COST THE OTHERS, AND MUST NOT BE A QUIET COUNT (tracker issue 277) ─────────
 //
@@ -274,7 +278,7 @@ console.log("  re-rendered from its artifacts. It is an example, not advice.\n")
 // times.
 const spineOf = (pub) =>
   Number.isFinite(pub.counts?.findings)
-    ? `${pub.counts.findings} finding(s) recorded in the run's audit spine; the report shows
+    ? `${pub.counts.findings} finding(s) recorded in the run's audit trail; the report shows
              the ones it retains`
     : Number.isFinite(pub.receipts?.findings)
       ? `${pub.receipts.findings} finding(s) with citations traced to this run's own held
@@ -367,9 +371,21 @@ child.on("error", (e) => die(`demo: could not start the portal: ${String(e?.mess
 // Its exit code is the demo's. A supervisor that swallowed a child's refusal would report a demo that
 // is up when nothing is listening.
 child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
-// Ctrl-C reaches the child through the shared terminal; this process waits for it to finish tearing
-// down rather than exiting first and orphaning it.
-process.on("SIGINT", () => {});
+// ── SIGINT IS FORWARDED, FOR THE SAME REASON SIGTERM IS ─────────────────────────────────────────
+//
+// This was a no-op, on the reasoning that a terminal delivers SIGINT to the whole foreground process
+// group so `start.mjs` gets its own copy. That is true of a terminal and it is the only case it is true
+// of. MEASURED on this tree: with the demo running on three ports, a SIGINT delivered to THIS PID ALONE
+// left all three still bound and both processes alive, because the no-op tore nothing down and the
+// services sit in their own process group where a group signal aimed at the terminal never reaches
+// them. A SIGINT sent to the group tears everything down correctly; only the pid-alone case leaked.
+//
+// That is the same defect, and the same shape, as the SIGTERM case recorded below — which was found by
+// somebody killing the one pid a reader can see. This half was left as a no-op then.
+//
+// Forwarding is safe when the terminal ALSO delivered its own copy: `start.mjs`'s shutdown is
+// re-entrant (`if (stopping) return`), so the second signal is ignored rather than racing the first.
+process.on("SIGINT", () => { try { child.kill("SIGINT"); } catch { /* already gone */ } });
 // ── AND SIGTERM, WHICH DOES NOT REACH THE CHILD ─────────────────────────────────────────────────
 //
 // SIGINT is delivered to the whole foreground process group by the terminal, so the no-op above is

package/bin/grant.mjs

@@ -46,7 +46,7 @@
 //
 // It is also why FILE below reads the CLEAROTRON_* spelling. An operator sets CLEAROTRON_ACCESS_FILE;
 // `applyEnvAliases` translates it. Reading the operator's spelling directly would work — and would put
-// the first direct CLEAROTRON_* product read in the tree, which 's arm catches, because the
+// the first direct CLEAROTRON_* product read in the tree, which the arm catches, because the
 // declaration ratchet is keyed on the CLEAROTRON_* prefix and goes blind the moment that premise stops
 // holding. One reader, one spelling.
 import "../shared/env-local.mjs";
@@ -59,7 +59,7 @@ import { makePrincipal } from "../driver/portal-access.mjs";
 import { envFrom } from "../shared/env-aliases.mjs";   // — resolves EITHER spelling; names the retired one because that is the live-writable half
 import { defaultGrantsPath } from "./start.mjs";       // — one owner for the roster's path
 
-// — bb8's F13. This read the variable and nothing else, so it refused with
+// — found in review. This read the variable and nothing else, so it refused with
 // "Set CLEAROTRON_ACCESS_FILE" — a name NOTHING writes. `start` injects it into the environment of the
 // services it supervises and never persists it, so the door found the roster and this command, run in
 // the operator's own shell, could not. Enrolling a client had no working path at all.
@@ -184,7 +184,7 @@ if (cmd === "add") {
   // The route exists — it is the file — and `grant --help` documents it. What was missing is that the
   // refusal which STOPS you did not carry it, so the shape of the object is printed here, against this
   // install's own path, rather than left to a reader to find in another command's help.
-  // — bb8's F13. THE FIRST TENANT IS CREATED HERE. Before this, enrolling anyone
+  // — found in review. THE FIRST TENANT IS CREATED HERE. Before this, enrolling anyone
   // on a fresh install ran out of road: the file is {"tenants":{}}, `brandowner` does not write tenants,
   // and this command refused because none existed. 2176's F38 fix printed the JSON shape into the
   // refusal, which is better than a bare stop and still asks a person to hand-edit the file the product

package/bin/key.mjs

@@ -84,7 +84,7 @@ try {
 
 for (const line of minted.notes) console.error(line);
 
-// — bb8's F13. A KEY FOR AN IDENTITY ON NO LIST IS A KEY THAT 403s. This command
+// — found in review. A KEY FOR AN IDENTITY ON NO LIST IS A KEY THAT 403s. This command
 // minted rc 0 for any address, printed the token once — it cannot be shown again — and the operator
 // handed it to a client whose first request was refused, with nothing on either side saying why.
 //