clearotron 0.3.2-beta.11 → 0.3.2-beta.13

package/.env.example

@@ -578,7 +578,7 @@ TRADEMARK_MCP_KEY_SOCKET=
 # 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
+# {"robin@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.
 #

package/CONTRIBUTING.md

@@ -60,9 +60,10 @@ Four more things run for free:
 | `npx clearotron demo` | Replays `demo/` — a real run on a fictional mark — through the real publisher into `~/trademark-demo/pool` and serves it. No keys, no model, no engine. |
 
 **About `npx clearotron demo`.** `npx clearotron demo --no-open --once` publishes the sample and exits without
-touching a browser. `npx clearotron demo --pool <dir>`
-puts the pool somewhere else, and `npx clearotron demo --run-dir <dir>` replays a finished run of your
-own instead of the shipped example.
+touching a browser. Without `--once` it serves the portal until it is stopped: `--no-open` keeps it from
+opening a browser, `--port <n>` moves its three doors to `n`, `n+1` and `n+2`, and `--keep` leaves its folder
+behind when it stops. `npx clearotron demo --pool <dir>` puts the pool somewhere else, and
+`npx clearotron demo --run-dir <dir>` replays a finished run of your own instead of the shipped example.
 
 Fix a bug, add a jurisdiction, add a doctrine test case: all of it is reachable from here.
 
@@ -90,7 +91,7 @@ this tree does not carry has to be declared with its reason, and the publication
 fails an undeclared one.
 
 **`driver/skills/**` is engine input, not documentation.** Those Markdown files are the prompt payload
-served to the model at run time — `synthesis-rules.md` is a 16,000-word program. Editing them for
+served to the model at run time — `synthesis-rules.md` is a 12,000-word program. Editing them for
 brevity, tone or tidiness changes what a clearance concludes. Nothing in this section, and nothing in
 any writing pass over the documentation, applies to them.
 
@@ -192,7 +193,7 @@ with no runner assigned and no steps recorded, and every job that gates on it is
 this repository: two runs on one SHA, thirty minutes apart, the push run green on every job and the
 scheduled one red having run nothing.
 
-That is **could-not-look**, not a fault, and this tool says so rather than making you open the run and
+That is **a check that could not look**, not a fault, and this tool says so rather than making you open the run and
 read timings to find out. It does not block on it — nothing ran, so nothing can have regressed.
 
 **It also does not call it green.** A run that never ran told you nothing about `main`, and the last

package/INSTALL.md

@@ -242,16 +242,15 @@ refuses for every real user.
 
 Two further constraints, both of which stop a package being cut from just anywhere:
 
-- **The de-identification scan needs a full clone.** It refuses a shallow one (exit 2 — could-not-look,
-  not a pass) because it walks history it cannot see.
+- **The de-identification scan needs a full clone.** It refuses a shallow one (exit 2 — a check that could
+  not look, not a pass) because it walks history it cannot see.
 - **It also needs its table**, passed with `--blocklist` (or `CLEAROTRON_IDENTIFIER_BLOCKLIST`), and
   that table lives in the private config store rather than in this repository. Without it the scan
   exits 2 rather than arming a weaker rule set quietly.
 
 Both refusals are correct and neither is a workaround to route around.
 
-**Every `clearotron` command in this document is written `npx clearotron …`, and that is not a
-stylistic choice.** This repository *is* the `clearotron` package, and npm links a package's `bin` into
+This repository *is* the `clearotron` package, and npm links a package's `bin` into
 `node_modules/.bin` only for its **dependencies** — never for the package itself. So after `npm install`
 succeeds there is no `clearotron` on your `PATH` and none in `node_modules/.bin`; a bare `clearotron`
 would be `command not found` with nothing having failed.

package/README.md

@@ -33,7 +33,8 @@ the address in your browser. No sign-up, no credentials, no network calls to us.
 The demo runs for as long as that window stays open, and removes everything it made when you close it —
 nothing of it is left on the machine, and running it again later starts clean. If you want to keep the
 sample reports after closing the window, run `npx clearotron demo --keep`; it prints the one command
-that removes the folder when you are done with it.
+that removes the folder when you are done with it. `npx clearotron demo --once` publishes the reports and
+exits, and keeps the folder the same way.
 
 **Then install it.**
 

package/bin/clearotron.mjs

@@ -24,6 +24,7 @@ import { constants as SIG } from "node:os";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 import { nodeFloorVerdict, nodeFloorRefusal } from "../shared/node-floor.mjs";   // — one floor, read from package.json
 import { invocationPrefix } from "../shared/invocation.mjs";   // — print a command the reader can type
+import { watchParent } from "../shared/parent-watch.mjs";
 
 export const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -229,6 +230,19 @@ const [verb, ...rest] = process.argv.slice(2);
     };
     process.on(sig, forward);
   }
+
+  // ── AND THE DEMO STOPS WHEN WHATEVER STARTED IT IS GONE ─────────────────────────────────────────────
+  //
+  // The forwarding above covers a signal sent to THIS pid. Through npx it is not this pid a reader holds:
+  // npm → `sh -c` → this launcher, and a TERM to npm dies at that `sh` (shared/parent-watch.mjs). This
+  // launcher is then reparented, and the demo runs on holding its three ports while the reader believes
+  // it stopped. So the demo takes its parent's death as a TERM, and stops everything it started.
+  //
+  // THE DEMO ONLY. A foreground `start` or a `run` outliving the shell that started it can be what the
+  // reader meant: `nohup clearotron start &` on a server they are about to log out of, or an hours-long
+  // clearance they will not babysit. The demo is a replay nobody leaves running on purpose, and its own
+  // banner already says it lasts only as long as the command that started it.
+  if (verb === "demo") watchParent(() => { try { child.kill("SIGTERM"); } catch { /* already gone */ } });
 }
 
 // RESOLVE BOTH SIDES THROUGH SYMLINKS. `npm install` puts a symlink at node_modules/.bin/clearotron, so

package/bin/connect.mjs

@@ -40,7 +40,7 @@ import { createInterface } from "node:readline/promises";
 import { requireInteractive } from "../shared/invocation.mjs";   // — a prompt with nobody to answer it
 import { stdin, stdout } from "node:process";
 import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, resolve } from "node:path";
 import { homedir, userInfo } from "node:os";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
@@ -48,7 +48,11 @@ import { createServer } from "node:net";
 import { CONNECT_CLIENTS, WHERE_FLAG, clientById, leadRouteFor, plainStep, whatItNeeds } from "../shared/connect-clients.mjs";
 import { stdioConnectFor, STDIO_SHAPES } from "../shared/stdio-connect.mjs";
 import { isWsl, wslTarget } from "../shared/wsl.mjs";   // — and which distribution a row should start the server in
-import { defaultDenylistPath, clientDoorAddress, clientDoorPort, clientDoorState, enablePlan, applyEnablePlan, describeChange, recordConnectKey, CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
+import { defaultDenylistPath, clientDoorAddress, clientDoorPort, clientDoorState, enablePlan, applyEnablePlan, describeChange, recordConnectKey, CLIENT_DOOR_UNIT, demoTokenSecretPath, keyPurposeLine, demoConnectCommand } from "../shared/client-door.mjs";
+import { readRunning } from "../shared/running-start.mjs";
+import { readLocalCredential, passphraseResetCommand, INSTALL_CREDENTIAL_FILE } from "../driver/portal-local-auth.mjs";
+import { invocationPrefix } from "../shared/invocation.mjs";
+import { BRAND } from "../shared/brand.mjs";
 import { mintToken, tokenId, resolvePerson, loadGrants } from "../shared/scope.mjs";
 import { envFrom } from "../shared/env-aliases.mjs";
 import { atomicWrite } from "../driver/progress.mjs";
@@ -654,6 +658,59 @@ function printSteps(offer, key) {
   }
 }
 
+/**
+ * ── A RUNNING DEMO, NAMED BY ITS FOLDER (owner, 2026-09-19) ─────────────────────────────────────────
+ *
+ * The demo is how a newcomer meets the product, and the next thing they ask an assistant is to connect.
+ * The route that works is the demo's own client door with an account key, and reaching it took a key
+ * issued by hand and an address read out of the startup log. This does both: it finds the demo that is
+ * running from that folder, mints a key with the demo's own secret for the demo's one user, and prints
+ * the address and the key, and nothing else is changed. No unit is written and no setting touched: the
+ * demo's door is already open, and everything of the demo goes when it stops.
+ *
+ * The address route's steps are not printed. They are written for a door behind a sign-in service,
+ * reached over the web, and a demo's door is on this machine and takes the key instead.
+ */
+async function connectDemo({ base, dryRun, clientName = null, running = readRunning() } = {}) {
+  const at = resolve(base);
+  const prefix = invocationPrefix();
+  say("");
+  if (clientName) { say(`  ${clientName}`); say(""); }
+  const demo = running.find((r) => r.demo && resolve(String(r.base ?? "")) === at);
+  if (!demo) {
+    say(`  Not available here — no demo is running from ${at}.`);
+    say(`  What would change it: start it with \`${prefix}clearotron demo --base ${/\s/.test(at) ? `"${at}"` : at}\`, then run this again.`);
+    return 1;
+  }
+  if (!demo.ports?.client) {
+    say(`  Not available here — the demo running from ${at} has no client door open.`);
+    say("  What would change it: stop the demo and start it again; its output says why the door did not start.");
+    return 1;
+  }
+  const address = `http://${!demo.host || demo.host === "0.0.0.0" ? "127.0.0.1" : demo.host}:${demo.ports.client}/mcp`;
+  const credentialPath = join(at, INSTALL_CREDENTIAL_FILE);
+  let email = "demo@localhost";
+  try { email = readLocalCredential(credentialPath)?.email || email; } catch { /* the demo's own user stands */ }
+  if (dryRun) {
+    say("  (dry run — nothing was changed)");
+    say(`  Address:  ${address}`);
+    return 0;
+  }
+  let secret = "";
+  try { secret = readFileSync(demoTokenSecretPath(at), "utf8").trim(); } catch { /* said below */ }
+  if (!secret) {
+    say(`  Not available here — the demo running from ${at} keeps no key secret this command can read.`);
+    say("  What would change it: run this as the user who started the demo.");
+    return 1;
+  }
+  const key = withSecret(secret, () => mintToken({ scope: "account", sub: email, ttlSec: 90 * 24 * 3600 }));
+  say(`  ${keyPurposeLine({ email, brand: BRAND.name, reset: passphraseResetCommand({ prefix, credentialPath }) })}`);
+  say("");
+  say(`  Address:  ${address}`);
+  say(`  Key:      ${key}`);
+  return 0;
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   // `--help` IS ANSWERED, not rejected. Running this bare drops the reader into a question, so "run it
@@ -674,6 +731,7 @@ async function main() {
     say("                      internet, with a key made for you now");
     say("    --list            the assistants this build knows");
     say("    --dry-run         say what would change, change nothing");
+    say("    --base <dir>      a running demo's folder: mint a key for its client door, and print both");
     say("    --allow-checkout-move");
     say("                      write this checkout's path even though services are running from");
     say("                      another one. Every unit's ExecStart follows that value, so the ones");
@@ -681,7 +739,7 @@ async function main() {
     say("");
     return 0;
   }
-  const known = new Set(["--client", "--where", "--list", "--dry-run", "--allow-checkout-move", "--help", "-h"]);
+  const known = new Set(["--client", "--where", "--list", "--dry-run", "--base", "--allow-checkout-move", "--help", "-h"]);
   const unknown = argv.filter((a) => a.startsWith("--") && !known.has(a));
   if (unknown.length) {
     console.error(`connect: unrecognised flag(s): ${unknown.join(", ")}`);
@@ -689,6 +747,13 @@ async function main() {
     process.exit(2);
   }
   const dryRun = argv.includes("--dry-run");
+  const b = argv.indexOf("--base");
+  if (b >= 0) {
+    const base = argv[b + 1];
+    if (!base || base.startsWith("--")) { console.error("connect: --base needs the demo's folder."); process.exit(2); }
+    const c = argv.indexOf("--client");
+    return await connectDemo({ base, dryRun, clientName: c >= 0 ? clientById(argv[c + 1])?.name ?? null : null });
+  }
   const w = argv.indexOf("--where");
   if (w >= 0 && !Object.hasOwn(WHERE_FLAG, argv[w + 1] ?? "")) {
     console.error(`connect: --where takes one of: ${Object.keys(WHERE_FLAG).join(", ")}`);

package/bin/example.mjs

@@ -47,7 +47,7 @@ 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
-import { isFrozen, demoChildren, demoInventory, prepareSample } from "../driver/demo-container.mjs";   // — one definition of what a frozen demo is, for the player AND the gate
+import { isFrozen, demoChildren, demoInventory, prepareSample, releaseDemoCopies } from "../driver/demo-container.mjs";   // — one definition of what a frozen demo is, for the player AND the gate
 import { ensureDemoProgram, demoProgramEnv } from "../shared/permanent-install.mjs";
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -168,6 +168,14 @@ if (!sampleDirs.length || !isFrozen(sampleDir)) {
 // rest are published. An unreadable file inside one sample used to throw out of the copy here and take
 // every demo down with a stack trace (measured on a published beta, 2026-09-11).
 const failures = ALL ? inventory.unusable.map((u) => ({ name: u.name, why: u.why })) : [];
+// A STOP WHILE THE SAMPLES ARE COPIED OR PUBLISHED still takes the copies with it. The copies go on exit
+// (driver/demo-container.mjs), and a signal's default ends the process without one. Taken off again once
+// the copies are gone, before the portal's own handlers are installed.
+const stopEarly = [["SIGINT", 2], ["SIGTERM", 15], ["SIGHUP", 1]].map(([sig, no]) => {
+  const h = () => process.exit(128 + no);
+  process.once(sig, h);
+  return [sig, h];
+});
 const samples = [];
 for (const dir of sampleDirs) {
   const r = prepareSample(dir, { repoRoot: REPO });
@@ -277,6 +285,9 @@ for (const s0 of samples) {
     failures.push({ name: s0.name, why: String(e?.message ?? e) });
   }
 }
+// PUBLISHED, SO THE COPIES THEY WERE PUBLISHED FROM GO NOW, whatever comes next.
+releaseDemoCopies();
+for (const [sig, h] of stopEarly) process.off(sig, h);
 if (!results.length) {
   die(`demo: no demo could be replayed.`, "", ...failures.map((f) => `  ${f.name}: ${f.why}`));
 }

package/bin/key.mjs

@@ -28,9 +28,10 @@
 // question would be two answers, and the wrong one would be the one nobody read.
 import "../shared/env-local.mjs";   // side effect: apply the install's .env — FIRST, before anything reads process.env
 import { invocationPrefix } from "../shared/invocation.mjs";
+import { BRAND } from "../shared/brand.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { defaultGrantsPath, installPaths } from "./start.mjs";
-import { demoTokenSecretPath } from "../shared/client-door.mjs";
+import { demoTokenSecretPath, keyPurposeLine } from "../shared/client-door.mjs";
 import { resolvePerson } from "../shared/scope.mjs";   // the door's own reading of the guest list, so one answer serves both
 import { mintFromOptions } from "../mcp-server/mint-token.mjs";
 
@@ -96,6 +97,10 @@ try {
   die(e.message);
 }
 
+// WHAT THIS KEY IS FOR, FIRST, in the owner's words (2026-09-19): a person who found this verb before the
+// passphrase minted a key and could not sign in to the portal with it. Standard error, as every line here
+// is, so the token stays alone on standard output.
+console.error(keyPurposeLine({ email, brand: BRAND.name, reset: `${p}clearotron passphrase --reset` }));
 for (const line of minted.notes) console.error(line);
 
 // — found in review. A KEY FOR AN IDENTITY ON NO LIST IS A KEY THAT 403s. This command

package/bin/onboard.mjs

@@ -2818,6 +2818,9 @@ export async function runCheck() {
       info(`the units are installed but their environment could not be read (${unitEnv?.why ?? "no reason given"}) — `
         + "the door verdicts below are withheld rather than guessed, because a failure to look is not a finding");
     if (door.shape === "local") {
+      // WHO THAT ONE USER IS, in the owner's words (2026-09-19), resolved as `start` resolves it.
+      const oneUser = String(effectiveForService("PORTAL_LOCAL_USER")?.v || `${userInfo().username}@localhost`).trim().toLowerCase();
+      say(`  · Portal sign-in: one user, ${oneUser}, by passphrase.`);
       say(`  · local passphrase door (${typed}) — one operator, one passphrase, no identity provider`);
       info(`a lost passphrase is recoverable: ${invocationPrefix()}clearotron passphrase --reset`);
     } else if (door.shape === "fronted") {
@@ -3194,7 +3197,10 @@ export async function runCheck() {
         try { const s = statSync(p); if (s.size > 0) { wrote = p; break; } } catch { /* not this one */ }
       }
       if (wrote) {
-        ok(`the client door's access log is being written: ${wrote}`);
+        // WHAT WAS READ, AND NOTHING MORE. This said "is being written" from any non-empty file — a claim
+        // about activity made from a file's size, printed over a log whose only line was a test's
+        // (measured 2026-09-19). Reworded as the owner ruled, 2026-09-19.
+        ok(`the client door's access log has entries: ${wrote}`);
       } else {
         // NOT-YET-WRITTEN IS NOT UNWRITABLE. A door nobody has called through has no log, and saying it
         // is broken would be the same lie as calling an unreachable unit inactive.
@@ -3338,8 +3344,22 @@ export async function runCheck() {
         sock.once("error", (e) => done(e.code === "ECONNREFUSED" ? false : null));
       });
     } catch { /* stays null — nobody could ask */ }
+    // WHOSE LISTENER. Only this install's own evidence counts: its unit running (which binds this very
+    // port), or a live start of this install whose record names the port. Anything else on the port is
+    // somebody's process, and on a shared box usually another account's door.
+    let doorOwnListener = null;
+    if (doorListening === true) {
+      if (doorActive === true) doorOwnListener = true;
+      else {
+        try {
+          const { clientDoorPort: portOf } = await import(pathToFileURL(join(REPO, "shared", "client-door.mjs")).href);
+          const { readRunning } = await import(pathToFileURL(join(REPO, "shared", "running-start.mjs")).href);
+          if (readRunning().some((r) => r?.ports?.client === portOf(doorEnv))) doorOwnListener = true;
+        } catch { /* stays null — an unread record is not a claim either way */ }
+      }
+    }
     const door = doorState({ env: doorEnv, unitDir, exists: existsSync, active: doorActive,
-      listening: doorListening, activeState: doorActiveState, subState: doorSubState });
+      listening: doorListening, ownListener: doorOwnListener, activeState: doorActiveState, subState: doorSubState });
     // EVERY COMMAND THROUGH `invoke`. Doctor's own guard runs every command doctor
     // prints from a directory that is not the install; a literal `clearotron start` in that text is
     // `command not found` for a reader with no shim, and the guard caught exactly that the moment this
@@ -4266,7 +4286,7 @@ try {
   // Enter yield the empty string, `present("")` is false, and askValue loops with "A value is needed
   // here." — so a reader taking the header at its word ("Enter takes the default in brackets") on the
   // one prompt that advertises empty as an answer could not leave it. Driven on the merged tree:
-  // 60 enters, killed at the cap, every cycle this prompt. Same defect class as 's
+  // 60 enters, killed at the cap, every cycle this prompt. Same defect class as the
   // engine-menu loop, arriving one commit after it was fixed, in a prompt this branch's own sibling
   // added.
   //

package/bin/passphrase.mjs

@@ -32,6 +32,7 @@ import { defaultInstallBase, establishCredential, installCredential, readLocalCr
 // rather than hardcoded. A hardcoded `npx ` tells a global installer their install is somehow lesser;
 // a hardcoded bare name sends an npx reader to `command not found`.
 import { invocationPrefix } from "../shared/invocation.mjs";
+import { BRAND } from "../shared/brand.mjs";
 
 const P = invocationPrefix();
 const USAGE = `  ${P}clearotron passphrase — report or reset the portal's local sign-in
@@ -117,8 +118,9 @@ catch (e) {
   process.exit(1);
 }
 
-console.log(`\n  A NEW passphrase has been minted for ${email}.`);
-console.log(`  The previous one no longer works.\n`);
+// THE OWNER'S WORDS, 2026-09-19: what the value is for comes before it, and names the one user it signs in.
+console.log(`\n  New passphrase for this ${BRAND.name}'s one user, ${email}. Paste it on the portal's sign-in page:\n`);
 console.log(`  PASSPHRASE: ${minted.passphrase}\n`);
+console.log(`  The previous one no longer works.`);
 console.log(`  Write it down now. It is stored only as a digest, so this line is the only copy that will`);
 console.log(`  ever exist — re-run this command if you lose it.\n`);

package/bin/start.mjs

@@ -121,7 +121,7 @@ import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "
 // — the door --background now INSTALLS, and the one authority for the settings
 // it refuses to start without. (Until 2026-09-03 this import read "the one unit --background may
 // tolerate and never manage"; settled point 2 superseded that.)
-import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort, demoTokenSecret, demoTokenSecretPath, keyIssueCommand } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
+import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort, demoTokenSecret, demoTokenSecretPath, keyIssueCommand, demoConnectCommand } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
 import { createServer } from "node:net";
 import { listenErrorMessage, nextFreePort } from "../shared/listen.mjs";
 import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
@@ -805,6 +805,10 @@ export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsTok
       // DNS-rebinding protection is keyed off this list being non-empty, so it is derived from the same
       // port the listener is given rather than left to whoever remembers.
       TRADEMARK_MCP_ALLOWED_HOSTS: `${host}:${ports.mcp},localhost:${ports.mcp}`,
+      // WHERE THE OTHER DOOR IS, so a key refused here is told where it belongs (shared/scope.mjs
+      // otherDoor). Read by nothing else in this process.
+      CLIENT_MCP_HTTP_HOST: host,
+      CLIENT_MCP_HTTP_PORT: String(ports.client),
     },
     // The worker needs the install's PATHS and nothing else — no ports, no secrets, no door config. It
     // talks to the queue and the pool, not to either listener.
@@ -830,6 +834,9 @@ export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsTok
       // written in one place and an allow-list in another drift into a door that starts and turns every
       // request away, which reads as a dead door rather than as a misconfiguration.
       CLIENT_MCP_ALLOWED_HOSTS: `${host}:${ports.client},localhost:${ports.client}`,
+      // The staff door's place, for the mirror refusal (shared/scope.mjs otherDoor). Read by nothing else here.
+      TRADEMARK_MCP_HTTP_HOST: host,
+      TRADEMARK_MCP_HTTP_PORT: String(ports.mcp),
       CLIENT_MCP_ACCOUNT_ACCESS: String(clientFence ?? "1"),
       // TOKEN-ONLY, AND WITHOUT IT THE DOOR DOES NOT START. Found by driving it rather than by reading
       // the diff: with this unset the door demands an OIDC audience plus a Cloudflare Access team or
@@ -1603,9 +1610,12 @@ if (isMain) {
     // — `clearotron demo` hands over to this — so fixing the player alone left the defect where it was.
     // ONE SAMPLE AT A TIME: one whose files cannot be read is left out and named below, and the others
     // seed. Copied in one call, a single unreadable file emptied the whole archive.
-    const { publishContainer, seedDemoRuns } = await import("../driver/demo-container.mjs");
+    const { publishContainer, seedDemoRuns, releaseDemoCopies } = await import("../driver/demo-container.mjs");
     const container = publishContainer(join(REPO, "demo"), { repoRoot: REPO });
-    const seed = await seedPool({ pool: paths.pool, examplesDir: container.dir, republish: republishRun });
+    let seed;
+    // THE COPY GOES AS SOON AS THE POOL IS SEEDED FROM IT, and on the way out if seeding throws.
+    try { seed = await seedPool({ pool: paths.pool, examplesDir: container.dir, republish: republishRun }); }
+    finally { releaseDemoCopies(); }
     // AND AS RUNS, so the assistant this demo's connect line wires has them to list, brief and open. Under
     // the demo's own workspace only: nothing of it reaches an install started afterwards. Their report
     // links are stamped with this portal's address, the one the Open line prints.
@@ -2421,7 +2431,8 @@ if (isMain) {
   // The output used to name neither as a door, so an owner watching one of them start concluded MCP had
   // not come up. Both are printed with who each is for, because "MCP is running" is ambiguous on a box
   // that has two of them and the ambiguity is what cost the leg.
-  say(`  Engine door  http://${HOST}:${ports.mcp}/mcp   — the portal's Start button calls this. Staff.`);
+  // THE CLIENT DOOR LEADS (owner, 2026-09-19). It is the one an assistant uses, and with the engine door
+  // printed first a demo's reader handed the staff address to their assistant, which refused its key.
   // THE SYNCHRONOUS TRUTH, NOT THE ASYNC FLAG ( — F26, review finding).
   //
   // `rec.alive` is flipped by the child's exit handler, which is async: reading it here asks "has the
@@ -2440,11 +2451,12 @@ if (isMain) {
     if (adoptedClientDoor)
       say(`               Already running as ${CLIENT_DOOR_UNIT}; this start kept it, so existing keys still work.`);
     else
-      say(`               It refuses every caller until a key is issued: ${keyIssueCommand({ prefix: invocationPrefix(), demo: DEMO, user, base: paths.base, defaultBase: join(homedir(), "trademark") })}`);
+      say(`               It refuses every caller until a key is issued: ${DEMO ? demoConnectCommand({ prefix: invocationPrefix(), base: paths.base }) : keyIssueCommand({ prefix: invocationPrefix(), demo: DEMO, user, base: paths.base, defaultBase: join(homedir(), "trademark") })}`);
   } else {
     say(`  Client door  NOT RUNNING on ${HOST}:${ports.client} — its output above says why. The portal and`);
     say("               the engine door are unaffected; a client assistant cannot connect until it is up.");
   }
+  say(`  Engine door  http://${HOST}:${ports.mcp}/mcp   — the portal's Start button calls this. Staff.`);
   say("");
   // ── WHAT `status` AND `stop` READ ABOUT THIS START ───────────────────────────────────────────────
   //
@@ -2556,7 +2568,7 @@ if (isMain) {
   // THE HEADINGS COME WITH THE PAIR, from the composer. Nothing is written here: the page prints these
   // same two words above these same two commands, and a second author is how the two surfaces drift.
   if (connect.variants) {
-    for (const v of connect.variants) { say(`    ${v.heading}`); say(`      ${v.text}`); say(""); }
+    for (const v of connect.variants) { say(`    ${v.heading}`); say(`      ${v.text}`); if (v.hint) say(`      ${v.hint}`); say(""); }
   } else {
     say(`    ${connect.command}`);
     say("");

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "aa58558b3b09fbf5b1c83010291d340167d438d8",
-  "version": "0.3.2-beta.11"
+  "commit": "f107c38f60f6cd5536cd30edb3d2b3ad8a1d1d97",
+  "version": "0.3.2-beta.13"
 }

package/docs/CLIENT-MCP.md

@@ -46,10 +46,10 @@ uses). Enrolment is therefore the portal's: no second credential to mint, rotate
 access revokes this with it. **Off unless `CLIENT_MCP_ACCOUNT_ACCESS=1`.**
 
 **Who turns that on. The installer, since 2026-09-03** — ruling, settled
-point 2. `render-units.mjs --apply` and `npx clearotron start --background` both write the settings this
+point 2. `render-units.mjs --apply` and `clearotron start --background` both write the settings this
 door refuses to start without and then place and enable `clearotron-client-mcp.service`. The settings
 come from one authority, `enablePlan` in `shared/client-door.mjs`, which is also what
-`npx clearotron connect` calls.
+`clearotron connect` calls.
 
 **This supersedes the 2026-08-31 ruling** *"On demand is fine"*, under which nothing at install and no
 rebuild's enable list could start this unit, because starting it WAS the consent that opened
@@ -57,10 +57,10 @@ access for each company's people. The owner changed the posture knowingly: **the
 gate, not whether a process runs.** A door with no key issued refuses everything, which is the same
 protection by a mechanism that does not depend on a reader finding a verb.
 
-**`npx clearotron disconnect` therefore revokes a person, not a service** (Q3). It writes the caller's key
+**`clearotron disconnect` therefore revokes a person, not a service** (Q3). It writes the caller's key
 ids to the denylist and strikes them from the record; it does not stop the unit and does not touch
 `CLIENT_MCP_ACCOUNT_ACCESS`, which is the whole install's setting. Cutting everyone off is
-`npx clearotron disconnect --everyone`, which states how many keys and how many people that is before
+`clearotron disconnect --everyone`, which states how many keys and how many people that is before
 acting — and does not stop the service either.
 
 An `account` principal reaches **eighteen** tools, for its own companies only — everything carrying
@@ -117,8 +117,8 @@ Four things about it are worth knowing before you offer it:
 - **The caller cannot choose the model.** The tier is cost and method both, and it is the one argument on
   the one tool that spends. Express the change with `instructions`.
 - **Nothing bounds the spend, by ruling.** `start_run` is stamped `clientPrincipal: true` at the
-  chokepoint so `runCaps.dailyRuns` bites it; a what-if job carries no such stamp, because the owner
-  ruled spend controls out ("ignore the call spend"). Every experiment records what it spent; no door
+  chokepoint so `runCaps.dailyRuns` bites it; a what-if job carries no such stamp, because spend controls
+  were deliberately left out of it. Every experiment records what it spent; no door
   refuses the next one. Concurrency IS bounded — `CLEAROTRON_WHATIF_MAX_CONCURRENT`, default 1 — because
   letting a free experiment occupy the box while a paid clearance waits is a different question from
   spend, and the ruling did not touch it.

package/docs/DELIVERY.md

@@ -284,12 +284,12 @@ So the checks that run are exactly those whose whole input is model-authored tex
 **permission-prose**, **scope-numbers-in-prose**, **counting-consistency**,
 **wipo-designation-language**, **prescription-prose**. Every other clearance check is listed in the
 receipt under `notApplicable` with the reason its input does not exist here
-(`KNOCKOUT_ABSENT_BY_DESIGN` in `driver/predelivery-lint.mjs`). That is a third state (/),
+(`KNOCKOUT_ABSENT_BY_DESIGN` in `driver/predelivery-lint.mjs`). That is a third state,
 and it is the point: a check that cannot apply is recorded as absent, never as a silent pass, and
 never as a `pass:false` that would project to the lawyer as a defect.
 
-**Why the lane cannot simply skip the lint.** The lint receipt IS the workbook's QC record
-(/), so a lane that writes no`_driver/predelivery-lint.json` produces an *empty* QC record
+**Why the lane cannot simply skip the lint.** The lint receipt IS the workbook's QC record,
+so a lane that writes no`_driver/predelivery-lint.json` produces an *empty* QC record
 rather than a deliberately-absent one — and an empty record reads as "not evaluated", never
 "passed". And since recorded defects reach the reviewing lawyer only through the projected
 machine-check sheet on the audit workbook, a lane with nothing to project is a lane whose

package/docs/ONBOARDING.md

@@ -21,7 +21,7 @@ installer.
 ## The command
 
 ```
-npx clearotron brandowner add <key> --name "<legal name>" [options]
+clearotron brandowner add <key> --name "<legal name>" [options]
 ```
 
 `<key>` is the bundle's filename and its identity everywhere else. It is validated on the way in, so a

package/docs/PORTAL.md

@@ -99,7 +99,7 @@ There were two ways in and only one of them proved anything: the auth-proxy edge
 and handed every caller the same synthetic address. **Both switches are deleted**, along with
 `PORTAL_DEV_EMAIL`. Local mode replaces them with a real sign-in.
 
-**Use `npx clearotron start`.** It is the documented way to run this product on one machine
+**Use `clearotron start`.** It is the documented way to run this product on one machine
 ([INSTALL.md](../INSTALL.md) §6) and it assembles everything below for you: the portal, the MCP face the Start button
 calls, a minted ops key, the grants file, the saved-search store and the data-plane paths — one command,
 one URL, `Ctrl-C` stops both processes. Nothing here needs an `*_AUTH_DISABLED` variable, and the
@@ -143,7 +143,7 @@ its dev bypass to provide that**:`TRADEMARK_MCP_AUTH_MODE=token` runs it with a
 access key and no auth proxy — loopback only, and refused outright alongside
 `TRADEMARK_MCP_AUTH_DISABLED`, which authenticates nobody. Mint the key with
 `mint-token.mjs --scope ops --sub portal --verbs start_run,stop_run --accounts foxglade`, or let
-`npx clearotron start` mint one in memory at every start and never write it down.
+`clearotron start` mint one in memory at every start and never write it down.
 
 ## Putting your own login provider in front
 
@@ -177,7 +177,7 @@ the model.
 1. Put the proxy in front of the portal's port and make it require sign-in. The portal must not be
    reachable except through it — an origin anyone can reach directly is an origin with no door.
 2. Set `PORTAL_AUTH_MODE=auth-proxy` and the four values above in `.env`.
-3. `npx clearotron doctor` — the **Portal door** section reports which door is configured and which of
+3. `clearotron doctor` — the **Portal door** section reports which door is configured and which of
    the four values are present, by name. It never prints their values.
 4. Sign in through the proxy once and confirm the portal shows your address rather than a passphrase
    box.

package/docs/RELEASES.md

@@ -16,7 +16,7 @@ npm install -g clearotron@beta     # newest — cut when there is something wort
 | | `latest` (stable) | `beta` |
 |---|---|---|
 | **Version looks like** | `0.2.0` | `0.2.1-beta.4` |
-| **Cut when** | a beta has passed a full clearance run and a from-scratch install by somebody who has never seen the product, and the owner says go | when a change lands that is worth testing, or while a stable is being prepared |
+| **Cut when** | a beta has passed a full clearance run and a from-scratch install by somebody who has never seen the product, and the maintainers decide to ship it | when a change lands that is worth testing, or while a stable is being prepared |
 | **Promises** | it installed and ran a real clearance end to end before it was published | it built, and the automated suite passed |
 | **Use it if** | you are running this for real work | you want a fix that landed today, or you are helping test |
 

package/docs/SECURITY.md

@@ -123,7 +123,7 @@ what the mechanism guarantees.*
 - One OPERATOR issuance path: `mint-token.mjs` (prints once, stores nothing; `sub` names the
   principal in every audit line; the `jti` printed at mint time is the revocation handle). Two
   automatic minters sit beside it on the same `mintToken`: the clearance publisher mints the report
-  link's run-bound `user` token at publish, and `npx clearotron start` mints the portal's verb-scoped,
+  link's run-bound `user` token at publish, and `clearotron start` mints the portal's verb-scoped,
   company-capped ops token in memory at every start. Neither prints, and neither is written down.
 - **Revocation**: denylist file checked on every verification; missing file = nothing revoked (the
   denylist can never take all auth down). **Rotation**: two-secret window, flag-day-free.

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

@@ -176,11 +176,11 @@ timeout shot, warm patch, backoff), the lane-wedge re-dispatch, and the rate-lim
 |---|---|---|
 | `CLEAROTRON_AI` | `anthropic-agent` (default) \| `openai-agent` | Compute engine (a registered provider adapter). `anthropic-agent` = `claude -p`; `openai-agent` = `codex exec` (both off-gateway, same normalized contract). An **unregistered** value — a typo, or the gateway-runtime adapter removed in the extraction — **fails loud**: no silent wrong-provider run. Production default is unchanged. |
 | `CLEAROTRON_AI_BILLING` | `subscription` (default) \| `api-key` \| `cloud` | Billing mode for the selected engine. ONE variable for both, and only the LIVE engine's setting is read — it fills each engine's billing knob, and the engine that is not selected is never consulted. **`anthropic-agent`:** subscription **deletes `ANTHROPIC_API_KEY` from the child env** so `claude -p` uses OAuth subscription credentials (a present key would override them); `api-key` keeps the key — the scale setting and standing fallback; **`cloud`** bills Claude per use through the reader's own cloud account, named by the Claude program's own switch — `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` or `CLAUDE_CODE_USE_BEDROCK`, or `ANTHROPIC_BASE_URL` alone for a gateway (see the credentials table below) — and deletes `ANTHROPIC_API_KEY` as subscription does. **`openai-agent`:** subscription seeds `auth.json` into the per-run `CODEX_HOME` from `CLEAROTRON_OPENAI_AUTH_FILE` (default `~/.codex/auth.json`) and strips API keys; `api-key` keeps `CODEX_API_KEY`; `cloud` is refused. **Fail-loud, never a guess, never the subscription in its place:** `api-key` with no `ANTHROPIC_API_KEY` / `CODEX_API_KEY` throws; on `anthropic-agent`, `cloud` with two switches on, or with none and no `ANTHROPIC_BASE_URL`, throws, and so does a switch left on under `subscription` or `api-key`, because the program bills that cloud whatever this says; a value that is none of the three throws on both engines. `clearotron start` and `clearotron doctor` report each refusal against the settings the services read, naming a value that is not a billing mode by its setting and never quoting it, and the runner refuses the search when it is ordered, before anything is spent. The resolved mode is stamped on every stage telemetry row (`engine`, `authMode`, `apiBilled`, and `cloud`, null when no cloud bills), and the attempt row also carries `providerReported`, the program's own word for who served the turn. |
-| `CLEAROTRON_CLAUDE_PATH` · `CLEAROTRON_CODEX_PATH` | `claude` / `codex` on `PATH`, then the copy Clearotron installed | The engine binary to spawn, ONE PER ENGINE: `CLEAROTRON_CLAUDE_PATH` under `anthropic-agent`, `CLEAROTRON_CODEX_PATH` under `openai-agent`. Only the live engine's is read, and a machine that runs both sets both — they were one variable until it met a machine needing two different paths. A path set here must be **absolute**: stage subprocesses run with cwd set to the run directory, so a relative path does not resolve there, and `npx clearotron doctor` refuses one. **Unset**, or set to the bare word `claude` / `codex` (which means the same), the engine uses the program on `PATH` when the machine has one, and otherwise the copy Clearotron installed in `~/.local/share/clearotron/engines`: `clearotron install` offers to put the chosen engine's program there (`@anthropic-ai/claude-code` or `@openai/codex`, this platform's build only), and `clearotron update` refreshes it. Nothing is bundled into the package. A value naming anything else is used as given and never falls back. `clearotron doctor` says which copy it found, and its version when npm installed that copy. |
-| `CLEAROTRON_OPENAI_AUTH_FILE` | `~/.codex/auth.json` | The credentials file seeded into the per-run `CODEX_HOME` under subscription billing. Was exempted from the August 2026 rename as an `openai-agent` internal rather than an install-surface name; the owner's 2026-09-04 ruling **reversed that exemption** and renamed the whole namespace, so it carries the house prefix like everything else. One spelling, no exceptions. |
+| `CLEAROTRON_CLAUDE_PATH` · `CLEAROTRON_CODEX_PATH` | `claude` / `codex` on `PATH`, then the copy Clearotron installed | The engine binary to spawn, ONE PER ENGINE: `CLEAROTRON_CLAUDE_PATH` under `anthropic-agent`, `CLEAROTRON_CODEX_PATH` under `openai-agent`. Only the live engine's is read, and a machine that runs both sets both — they were one variable until it met a machine needing two different paths. A path set here must be **absolute**: stage subprocesses run with cwd set to the run directory, so a relative path does not resolve there, and `clearotron doctor` refuses one. **Unset**, or set to the bare word `claude` / `codex` (which means the same), the engine uses the program on `PATH` when the machine has one, and otherwise the copy Clearotron installed in `~/.local/share/clearotron/engines`: `clearotron install` offers to put the chosen engine's program there (`@anthropic-ai/claude-code` or `@openai/codex`, this platform's build only), and `clearotron update` refreshes it. Nothing is bundled into the package. A value naming anything else is used as given and never falls back. `clearotron doctor` says which copy it found, and its version when npm installed that copy. |
+| `CLEAROTRON_OPENAI_AUTH_FILE` | `~/.codex/auth.json` | The credentials file seeded into the per-run `CODEX_HOME` under subscription billing. Was exempted from the August 2026 rename as an `openai-agent` internal rather than an install-surface name; a decision of 2026-09-04 **reversed that exemption** and renamed the whole namespace, so it carries the house prefix like everything else. One spelling, no exceptions. |
 | `CLEAROTRON_OPENAI_MODEL_JUDGMENT` / `CLEAROTRON_OPENAI_MODEL_SWEEP` / `CLEAROTRON_OPENAI_MODEL_CHEAP` | `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`. | Maps the driver's abstract `opus`/`sonnet`/`haiku` tiers onto the codex ladder, the way the anthropic engine maps onto its own (ruling 2026-09-02, superseding the single-model mapping). A tier that cannot hold its stage contract announces itself at that stage — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` in `_driver/<stage>.jsonl` — not at delivery. |
 | ↳ why they are three, and what the old measurement still says | superseded 2026-09-02, not erased | The three defaulted to `sol` alone on a MEASUREMENT, never a placeholder: on 2026-08-11/12, with `SWEEP=gpt-5.6-terra` / `CHEAP=gpt-5.6-luna`, every codex clearance died on structural-output gates — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` — over 2 scenarios × 3 stage families, **byte-identically on retry**, so no retry budget rescued it. That measurement stands for the code and the codex CLI **of that date**, and it is why the judgment tier keeps `sol`. Three weeks of stage-contract work and several codex minor versions sit between it and the 2026-09-02 ruling that split the three. **The symptom to match against this cause is unchanged**: those same three gates, as a fail row in`_driver/<stage>.jsonl`, inside the first few dispatches of a clearance and identical on every retry — a model incapable of a contract is not flaky at it. It reads as an engine bug when the only fault is this configuration. A cheap-tier experiment still belongs in the three constants in `driver/engine/openai-agent.mjs` where a reviewer sees it, not in an untraceable env line. |
-| `CLEAROTRON_DATABASE` | **REQUIRED — no default.** `corsearch` \| `clarivate` \| `signa` \| `euipo` \| `uspto-local` \| `free-tier` | Active register provider — one per run, set in the environment the deploy carries, in every environment including production. There is **no default**: unset resolves to `null` and every use of it throws, so a run refuses at start rather than calling a vendor nobody chose ( — the removed`corsearch` fallback named a vendor the deployment did not choose). Three are paid global sweeps; `euipo` (EU) and `uspto-local` (US) are free single-office sources, and `free-tier` composes those two as one register. Choosing a free value makes every territory outside its coverage a disclosed *deferred* row. Unknown ids throw loudly, and the gather layer throws at stage time for any provider without a built MCP server. |
+| `CLEAROTRON_DATABASE` | **REQUIRED — no default.** `corsearch` \| `clarivate` \| `signa` \| `euipo` \| `uspto-local` \| `free-tier` | Active register provider — one per run, set in the environment the deploy carries, in every environment including production. There is **no default**: unset resolves to `null` and every use of it throws, so a run refuses at start rather than calling a vendor nobody chose (the removed `corsearch` fallback named a vendor the deployment did not choose). Three are paid global sweeps; `euipo` (EU) and `uspto-local` (US) are free single-office sources, and `free-tier` composes those two as one register. Choosing a free value makes every territory outside its coverage a disclosed *deferred* row. Unknown ids throw loudly, and the gather layer throws at stage time for any provider without a built MCP server. |
 | `CLEAROTRON_CODEX_SANDBOX_BYPASS` | unset | `1` runs `codex exec` with its own sandbox helper bypassed, for hosts where that helper cannot spawn. It removes a defence: with it set, the run dir is writable by the seat and only the deny-hook stands between a stage and `_driver/`. Set it because the host forces it, never for convenience. |
 
 ## Environment variable reference
@@ -225,7 +225,7 @@ deployment may override (verify live values per deployment).
 | `CLEAROTRON_RUN_LOCK_POLL_MS` | 15000 | Run-slot acquire poll cadence. |
 | `CLEAROTRON_ADMISSION_BUDGET_MS` | 7200000 (2 h) | Runner stops claiming new jobs after this per activation; leftovers re-trigger a fresh activation. |
 | `CLEAROTRON_QUEUE_SCAN_MS` | 10000 (min 1000) | Mid-drain re-scan for newly arrived jobs. |
-| `CLEAROTRON_WHATIF_MAX_CONCURRENT` | 1 (min 1) | How many queued what-ifs the runner drains at once. Deliberately NOT a run-slot: an experiment that took one from `CLEAROTRON_MAX_CONCURRENT_RUNS` could block an admitted paid clearance rather than merely share the box with it. This is a concurrency bound and not a spend control — the owner ruled spend controls out when he opened what-if to each company's people (2026-08-27), and nothing here refuses the next experiment. |
+| `CLEAROTRON_WHATIF_MAX_CONCURRENT` | 1 (min 1) | How many queued what-ifs the runner drains at once. Deliberately NOT a run-slot: an experiment that took one from `CLEAROTRON_MAX_CONCURRENT_RUNS` could block an admitted paid clearance rather than merely share the box with it. This is a concurrency bound and not a spend control — spend controls were deliberately left out when what-if opened to each company's people (2026-08-27), and nothing here refuses the next experiment. |
 | `CLEAROTRON_STOP_GRACE_MS` | 60000 | Grace after first SIGTERM before exit(1). |
 | `CLEAROTRON_MAX_CLAIM_AGE_MS` | 172800000 (48 h; 0 disables) | Hard ceiling on a claim's age (from the `.pid` sidecar mtime) — beyond it, re-claim regardless of liveness. |
 | `CLEAROTRON_KNOCKOUT_VARIANT_CAP` | unset (⇒ the lane's own cap) | Ceiling on variants a knockout screens per name. Set only to bound an unusually wide batch; absent means the lane decides. |