clearotron 0.2.0 → 0.2.2

package/.env.example

@@ -403,3 +403,108 @@ CLEAROTRON_DEMO=
 # Read by driver/whatif-worker.mjs. Refs tracker issue 1953.
 # effect: tuning
 CLEAROTRON_WHATIF_MAX_CONCURRENT=1
+
+# The checkout every shipped systemd unit interpolates — and the one name in this file you are most
+# likely to meet before you meet this file. Ten units name it in their `ExecStart`
+# (clearotron-portal, -worker, -deploy, -client-mcp, -mcp-face, prelim-driver, prelim-outbox, the two
+# mcp-server/remote units and the courtlistener bridge), and production's units all depend on it.
+#
+# YOU ALMOST CERTAINLY DO NOT SET THIS. `clearotron connect` writes it into the install's env file, set
+# to the checkout it just installed (bin/connect.mjs, shared/checkout-move.mjs), and it rewrites it when
+# the checkout moves. So this is not a decision waiting for you at install time, and the row does not
+# exist because a deployment cannot be configured without it.
+#
+# IT EXISTS BECAUSE OF WHO READS IT AT 2AM. Somebody whose unit will not start reads
+# `${CLEAROTRON_CHECKOUT_DIR}` in an ExecStart, comes to the file INSTALL.md §8 calls the catalogue, and
+# finds nothing. `shared/names-in-force.mjs` already knew the name; neither governance document did.
+# A row that says "the installer writes this" is the answer to their question — the absence was not.
+#
+# Surfaced by the cut-over overlay control once the withheld `ops/` bucket was laid back over the public
+# tree: the ratchets that would have caught it had had no subject since the cut, so this is a gap of
+# long standing rather than a regression. Refs tracker issue 213.
+#
+# Left EMPTY here on purpose. A path in this file would read as a default; there is none, and the
+# installer supplies the real value.
+# effect: deployment
+CLEAROTRON_CHECKOUT_DIR=
+
+# ── The release pipeline's own two names ─────────────────────────────────────────────────────────
+# Both are set by `.github/workflows/release.yml` and read by the release scripts. NEITHER is an
+# operator's decision, and on an install both are unset and the defaults are the right answer. They are
+# catalogued for the same reason CLEAROTRON_CHECKOUT_DIR above is: they are OUR names, read by code that
+# ships, and a reader who meets one in a workflow log needs somewhere to look it up.
+#
+# They are NOT in the system-owned list beside GITHUB_OUTPUT, and the line between them is worth stating:
+# GitHub sets GITHUB_*, so a row would document somebody else's decision. We set these, so a row
+# documents ours.
+#
+# Found by the audit while closing tracker issue 213, not by that issue's diagnosis — they arrived with
+# tonight's release-pipeline work and the catalogue ratchet caught them on the next run, which is the
+# ratchet doing its job. Raised with the release lane rather than silently absorbed.
+
+# The commit the cut decision is ABOUT. The workflow sets it to `github.sha` — the push — because the
+# 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.
+#
+# 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
+# budget; the workflow sets it to 0 on a `workflow_dispatch` rehearsal so a dry run does not sit out the
+# full wait. A malformed value REFUSES rather than defaulting — taken as 0 it would skip the wait
+# 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
@@ -115,16 +116,31 @@ Nothing here requires an agent platform or a database — reports are written to
 
 ```
 npm install -g clearotron          # stable — the tested one
-npm install -g clearotron@beta     # newest — every merge, minutes after it lands
+npm install -g clearotron@beta     # newest — cut when there is something worth testing
 ```
 
 A **stable** has run a real clearance end to end and had a from-scratch install driven by somebody who has
-never seen the product, before it was published. A **beta** is published automatically on every merge to
-`main`; it built and the suite passed, and nothing has driven a live register through it.
+never seen the product, before it was published. A **beta** is published when a change lands that is worth
+testing, or while a stable is being prepared — days apart, not on every merge; it built and the suite
+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.
 
@@ -229,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
@@ -275,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.
 
@@ -667,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
@@ -776,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".
@@ -948,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
@@ -1112,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/README.md

@@ -39,7 +39,8 @@ Node 22 or newer, on macOS, Linux, or Windows via WSL2. That puts `clearotron` o
 command below works in that short form.
 
 That command gives you the **stable** release — the one that has run a real clearance end to end before it
-was published. If you want the newest code instead, every merge publishes a beta within minutes:
+was published. If you want the newest code instead, a beta is published whenever there is something worth
+testing — deliberately, days apart, not on every merge:
 
 ```bash
 npm install -g clearotron@beta

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

@@ -40,8 +40,8 @@ import "../shared/env-local.mjs";   // step 4 / — FIRST: this program read a
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync } from "node:fs";
 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 { join, resolve, dirname, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { basename, dirname, join, resolve, sep } from "node:path";
+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,15 +100,30 @@ 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);
-const sampleDir = resolve(
-  flag("--run-dir")
-  ?? (wanted ? join(DEMO_ROOT, wanted) : (children[0] ? join(DEMO_ROOT, children[0]) : DEMO_ROOT)),
-);
-if (!isFrozen(sampleDir)) {
+
+// ── ALL OF THEM, UNLESS THE CALLER NARROWED IT (tracker issue 277) ──────────────────────────────────
+//
+// This used to replay `children[0]` and stop. The package ships one finished report per product, and a
+// first-time reader met one of them with nothing on screen saying the other three existed — so three
+// quarters of what was shipped was reachable only by someone who already knew to ask for it. The owner's
+// ruling is that they auto-load: "it should auto-load since it is NOT obvious these runs are there unless
+// you know about it."
+//
+// `--product` and `--run-dir` still narrow to one, because "show me just this one" is a real thing to
+// want. Neither given now means every product this tree ships, in the container's own order.
+const sampleDirs = flag("--run-dir")
+  ? [resolve(flag("--run-dir"))]
+  : wanted
+    ? [resolve(join(DEMO_ROOT, wanted))]
+    : children.map((c) => resolve(join(DEMO_ROOT, c)));
+// The refusal below is about ONE directory, and with nothing shipped there is no directory to name — so
+// the container itself is what it looks at, which is what it always did when `demo/` was empty.
+const sampleDir = sampleDirs[0] ?? resolve(DEMO_ROOT);
+if (!sampleDirs.length || !isFrozen(sampleDir)) {
   // AN ABSENCE IS A FINDING, AND IT NAMES WHAT IT LOOKED AT. This exits 1 and always has; tracker issue
   // 2193 reported it exiting 0, which did not reproduce at v0.1.0 or at main's tip. An arm pins it.
   die(
@@ -128,10 +147,17 @@ if (!isFrozen(sampleDir)) {
 // PUBLISHING WRITES A RECEIPT INTO THE RUN DIRECTORY, and `demo/` is tracked — so a reader who only READ
 // the demo came back to a dirty checkout. `publishSource` is the one definition of that rule, shared with
 // the launcher, which seeds the pool from the same container on every `--demo` start.
-const publishFrom = publishSource(sampleDir, { repoRoot: REPO });
-
-const meta = JSON.parse(readFileSync(join(sampleDir, "meta.json"), "utf8"));
-if (!meta?.runId) die(`example: ${join(sampleDir, "meta.json")} names no runId — it is not a frozen example manifest.`);
+// EVERY ONE THAT WAS ASKED FOR IS READ BEFORE ANY IS PUBLISHED, so a manifest missing a runId is a
+// refusal about that demo by name rather than a partial pool nobody can account for.
+const samples = sampleDirs.map((dir) => {
+  const manifest = join(dir, "meta.json");
+  if (!isFrozen(dir)) die(`demo: ${dir} is not a frozen demo — it holds no meta.json and lane entry file.`);
+  const m = JSON.parse(readFileSync(manifest, "utf8"));
+  if (!m?.runId) die(`example: ${manifest} names no runId — it is not a frozen example manifest.`);
+  return { dir, meta: m, publishFrom: publishSource(dir, { repoRoot: REPO }), name: basename(dir) };
+});
+const publishFrom = samples[0].publishFrom;
+const meta = samples[0].meta;
 
 // ── 2. the pool guard ────────────────────────────────────────────────────────────────────────────────
 // Resolve through symlinks. A $HOME that resolves inside the archive is exactly the shape a `===` test
@@ -158,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>`,
 );
@@ -192,19 +218,38 @@ if (existsSync(poolRoot) && !statSync(poolRoot).isDirectory()) die(`demo: ${pool
 
 // ── 3. replay ────────────────────────────────────────────────────────────────────────────────────────
 console.log(`\n  ${BRAND.name} ${BRAND.product.toLowerCase()} — demo\n`);
-console.log(`  sample:  ${sampleDir}`);
-console.log(`  pool:    ${poolRoot}\n`);
+console.log(samples.length === 1
+  ? `  sample:  ${samples[0].dir}`
+  : `  samples: ${samples.length} — ${samples.map((x) => x.name).join(", ")}`);
+console.log(`  reports folder:  ${poolRoot}\n`);
 
 mkdirSync(poolRoot, { recursive: true });
-const { republishRun } = await import(join(REPO, "driver", "publish", "report-registry.mjs"));
-let published;
-try {
-  // poolUrl "" on purpose: the report's own link block is for a deployment that serves the pool at a
-  // public URL. This one is served from this process, at a port picked below.
-  published = await republishRun({ runId: meta.runId, meta, pool: poolRoot, poolUrl: "", runDir: join(publishFrom, "run") });
-} catch (e) {
-  die(`demo: replaying the sample failed: ${String(e?.message ?? e)}`);
+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) ─────────
+//
+// Publishing stopped at the first error, which was right when there was one demo and is wrong now: a
+// reader whose knockout capture is unreadable should still get the other three, and should be TOLD which
+// one is missing. "3 published" with no other line is the shape this repository calls a silent count —
+// the number is true and the reader cannot tell it is short.
+//
+// The failures are collected and reported together at the end, and the process exits non-zero, because a
+// demo that came up missing a quarter of itself is not a success however good the three look.
+const results = [];
+const failures = [];
+for (const s0 of samples) {
+  try {
+    // poolUrl "" on purpose: the report's own link block is for a deployment that serves the pool at a
+    // public URL. This one is served from this process, at a port picked below.
+    results.push({ ...s0, published: await republishRun({ runId: s0.meta.runId, meta: s0.meta, pool: poolRoot, poolUrl: "", runDir: join(s0.publishFrom, "run") }) });
+  } catch (e) {
+    failures.push({ name: s0.name, why: String(e?.message ?? e) });
+  }
+}
+if (!results.length) {
+  die(`demo: no demo could be replayed.`, "", ...failures.map((f) => `  ${f.name}: ${f.why}`));
 }
+const published = results[0].published;
 
 // THE LABEL. The reader is about to look at a document that reads like advice about a real mark. It is
 // not, and the demo says so before the browser opens rather than in a footnote nobody reaches.
@@ -227,18 +272,34 @@ console.log("  re-rendered from its artifacts. It is an example, not advice.\n")
 //
 // The third branch is the point: a lane whose publisher reports no count says so. This line printed a
 // bare "?" to the knockout — a could-not-look wearing the costume of a number.
-const spine =
-  Number.isFinite(published.counts?.findings)
-    ? `${published.counts.findings} finding(s) recorded in the run's audit spine; the report shows
+// PER LANE, FOR EVERY DEMO — not for the first one with the rest reduced to a product name. The three
+// branches below are the whole point of this sentence: two lanes count different populations and a third
+// counts none, and printing one lane's number beside four reports would state the wrong population three
+// times.
+const spineOf = (pub) =>
+  Number.isFinite(pub.counts?.findings)
+    ? `${pub.counts.findings} finding(s) recorded in the run's audit trail; the report shows
              the ones it retains`
-    : Number.isFinite(published.receipts?.findings)
-      ? `${published.receipts.findings} finding(s) with citations traced to this run's own held
-             evidence, on ${published.receipts.citing}/${published.receipts.marks} mark(s)`
+    : Number.isFinite(pub.receipts?.findings)
+      ? `${pub.receipts.findings} finding(s) with citations traced to this run's own held
+             evidence, on ${pub.receipts.citing}/${pub.receipts.marks} mark(s)`
       : `this lane's publisher reported no finding count — the report itself is the record`;
-console.log(`  published: ${published.runId}  (${spine})`);
+for (const r of results) console.log(`  published: ${r.published.runId}\n             ${r.name} — ${spineOf(r.published)}`);
+if (results.length > 1) console.log(`\n  ${results.length} demo reports are published and listed — one per product.`);
+// LOUD, AND ON STDERR, AND NON-ZERO. Said after the successes so a reader sees what they DID get first,
+// and cannot mistake the run for a clean one.
+if (failures.length) {
+  console.error(`\n  ${failures.length} of ${samples.length} demo(s) could NOT be replayed:`);
+  for (const f of failures) console.error(`    ${f.name}: ${f.why}`);
+  console.error(`  The portal below lists the ${results.length} that published. This exits non-zero.`);
+  process.exitCode = 1;
+}
 
 if (has("--once")) {
-  console.log(`\n  report: ${join(poolRoot, meta.runId, "report.html")}`);
+  // EVERY REPORT THAT WAS PUBLISHED, not the first one. Naming one of four here is the same defect as
+  // publishing one of four: the reader is handed a path and has no way to learn the others exist.
+  console.log("");
+  for (const r of results) console.log(`  report: ${join(poolRoot, r.published.runId, "report.html")}`);
   //, criterion 5 — SAY WHAT WAS CREATED, ON EVERY PATH THAT CREATES SOMETHING.
   //
   // The portal path below prints this and `--once` did not, so the one invocation a reader is most
@@ -251,7 +312,11 @@ if (has("--once")) {
   // does — worse than silence, because it reads as an answer.
   const created = flag("--pool") ? poolRoot : demoBase;
   console.log(`  Removing it later is one directory:  rm -rf ${created}\n`);
-  process.exit(0);
+  // NOT A BARE ZERO. A demo that failed to replay one of its four sets `exitCode` above, and exiting 0
+  // here would discard it — printing the failure and then reporting success, which is the shape this
+  // change exists to remove. `--once` is also the invocation a script is most likely to use, so it is
+  // the one where a swallowed code does the most damage.
+  process.exit(process.exitCode ?? 0);
 }
 
 /**
@@ -306,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