clearotron 0.3.0-beta.8 → 0.3.0-beta.9

package/bin/key.mjs

@@ -29,7 +29,9 @@
 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 { existsSync, readFileSync } from "node:fs";
-import { defaultGrantsPath } from "./start.mjs";
+import { defaultGrantsPath, installPaths } from "./start.mjs";
+import { demoTokenSecretPath } 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";
 
 const argv = process.argv.slice(2);
@@ -44,6 +46,7 @@ const USAGE = `usage: ${p}clearotron key issue <email> [options]
 
     --accounts a,b     cap the key to these account keys as well (omit = whatever their grant allows)
     --ttl-days <n>     how long it is valid (default 90)
+    --base <dir>       the install or demo to issue for, when it is not the one set up in ~/trademark
 
 The token is printed ONCE on stdout and stored nowhere — possession is the credential. Everything
 else goes to stderr, including the jti that revokes it.`;
@@ -65,6 +68,17 @@ const email = positional[0];
 if (!email) die(`who is the key for? Give the person's email.\n\n${USAGE}`);
 if (!email.includes("@")) die(`"${email}" is not an email address — the subject of an account key is the identity their assistant presents, and the grants file is keyed on it.`);
 
+// `--base` NAMES THE INSTALL, as it does for `start` and `passphrase`: its guest list, and — for a demo,
+// which keeps its signing secret in its own base rather than in any settings file — that secret. Without
+// it the verb read the install's settings and refused to issue a key for a running demo.
+const baseAt = rest.indexOf("--base");
+const base = baseAt >= 0 ? rest[baseAt + 1] : null;
+if (baseAt >= 0 && (!base || base.startsWith("--"))) die(`--base needs a directory.\n\n${USAGE}`);
+if (base) {
+  const secretFile = demoTokenSecretPath(base);
+  if (existsSync(secretFile)) process.env.TRADEMARK_MCP_TOKEN_SECRET = readFileSync(secretFile, "utf8").trim();
+}
+
 const ttlDays = Number(flag("--ttl-days") ?? 90);
 const accounts = flag("--accounts") ? flag("--accounts").split(",").map((s) => s.trim()).filter(Boolean) : null;
 
@@ -93,15 +107,19 @@ for (const line of minted.notes) console.error(line);
 // inert. STDERR, so the token stays alone on stdout and `key issue ... > token.txt` keeps working —
 // that split is deliberate and this must not undo it.
 try {
-  const rosterPath = defaultGrantsPath();
+  const rosterPath = base ? installPaths(base).grants : defaultGrantsPath();
   if (!existsSync(rosterPath)) {
     console.error(`\nNOTE: no guest list at ${rosterPath} yet, so nothing grants ${email} anything and this key will be refused at the door. \`clearotron start\` writes the list; then: clearotron grant add ${email} --tenant <name> --accounts <brand-owner-key>`);
   } else {
+    // THE DOOR'S OWN RESOLVER DECIDES, not a second reading of the file. This walked `tenants[].users`
+    // alone, and the demo's guest list grants its account through the top-level `people` map — so the
+    // demo's own key came with a note saying the door would refuse it, over a key the door accepts
+    // (driven 2026-09-11). One reader for one question.
     const roster = JSON.parse(readFileSync(rosterPath, "utf8"));
-    const tenants = roster?.tenants && typeof roster.tenants === "object" ? roster.tenants : {};
-    const listed = Object.values(tenants).some((t) => t?.users && Object.prototype.hasOwnProperty.call(t.users, email));
+    const person = resolvePerson(email, roster);
+    const listed = Boolean(person && (person.everything || person.accounts?.length || person.organisations?.length));
     if (!listed)
-      console.error(`\nNOTE: ${email} is on no tenant in ${rosterPath}, so this key resolves to no accounts and the door will refuse it. Grant them access with: clearotron grant add ${email} --tenant <name> --accounts <brand-owner-key>`);
+      console.error(`\nNOTE: ${email} is granted nothing in ${rosterPath}, so this key resolves to no accounts and the door will refuse it. Grant them access with: clearotron grant add ${email} --tenant <name> --accounts <brand-owner-key>`);
   }
 } catch (e) {
   // A ROSTER THIS COMMAND CANNOT READ IS NOT A ROSTER SAYING THE SUBJECT IS ABSENT. Said as what it is,

package/bin/onboard.mjs

@@ -1503,6 +1503,9 @@ export async function runCheck() {
     } else if (form.form === "shim-path") {
       warn(`${form.dir} is not on this shell's PATH, so the bare \`clearotron\` will not resolve here`);
       info(`add it with: export PATH="${form.dir}:$PATH"  — or open a new login shell`);
+    } else if (form.form === "npx-pinned") {
+      info(`this is running from npm's npx cache, so the commands below name this version through npx (\`${form.prefix.trim()}\`), `
+        + `which works from any directory and after npm cleans its cache; \`${invoke("install")}\` puts \`clearotron\` on your PATH`);
     } else if (form.shimKind === "ours-other-install") {
       warn(`${form.shim} is a shim for a DIFFERENT install (${form.otherInstall})`);
       info(`re-run \`${invoke("install")}\` to point the bare name at this one`);

package/bin/start.mjs

@@ -118,15 +118,16 @@ 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 } 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 } 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, unlinkSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { invocationPrefix, invoke, reachableCommand } from "../shared/invocation.mjs";   // — the banner names the verb
-import { unitEnvPath } from "../shared/env-local.mjs";   // — the file the units read, named once
+import { unitEnvPath, activeEnvPath } from "../shared/env-local.mjs";   // — the file the units read, named once
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // ONE KEY=value reader, in a leaf: render-units is a COMMAND, and importing it from here closed a cycle
 import { homedir, userInfo } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { usageBlock } from "../shared/usage-block.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
@@ -142,6 +143,7 @@ import { addressRefusal } from "../shared/staff-domain.mjs";
 import { withPerson, withOrganisation, withCompany } from "../shared/grants-edit.mjs";
 import { assertGrantsShape, resolvePerson } from "../shared/scope.mjs";
 import { backgroundManager } from "../shared/os-advice.mjs";
+import { recordRunning } from "../shared/running-start.mjs";
 import { frontingVariablesSet } from "../shared/install-auth.mjs";   // — one owner for what counts as a proxy in front of a door
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -909,6 +911,11 @@ if (isMain) {
   // Decided before any path is, because in a demo every path below is the demo's own. The posture
   // itself is described at the DEMO block further down.
   const DEMO = argv.includes("--demo");
+  // A DEMO HAS NO BACKGROUND FORM, and asking for one is refused before anything is written. The
+  // background path installs units that run the reader's own install, so `--demo --background` would set
+  // up an empty install in their home and call it the demo.
+  if (DEMO && wantBackground)
+    fatal("the demo has no background form — it runs as long as its terminal does. `--background` starts your own install as services, not the demo.");
   // The same base `npm run setup` writes under, so whichever of the two a reader ran first, the other
   // finds the same install rather than a second one beside it.
   // Whatever the environment already says wins over the base-derived default, for every path — a reader
@@ -916,6 +923,35 @@ if (isMain) {
   // which `startPaths` says why. One author, because `doctor` asks the same function what the services
   // were handed.
   const paths = startPaths({ env: process.env, base: flag("--base", join(homedir(), DEMO ? "trademark-demo" : "trademark")), demo: DEMO });
+  // ── NOTHING OF THE DEMO LANDS IN AN INSTALL, AND THAT IS CHECKED BEFORE ANYTHING IS WRITTEN ───────
+  //
+  // The demo keeps its signing secret in its base and `key issue --base` reads it from there, so a demo
+  // pointed at an install's directory would leave a secret where that install's own key command looks:
+  // every key issued afterwards would be signed with the demo's while the install's door verified with
+  // its own — a key that looks issued and is refused, with nothing said either way. The settings are
+  // READ here and never applied; a demo still takes nothing from them.
+  if (DEMO) {
+    const base = resolve(paths.base);
+    const inside = (p) => { const v = String(p ?? "").trim(); if (!v) return false; const r = resolve(v); return r === base || r.startsWith(base + sep); };
+    let settings = {};
+    try { settings = parseEnvFile(readFileSync(activeEnvPath(), "utf8")); } catch { /* no settings in force: nothing of an install to collide with */ }
+    const found = [];
+    if (inside(settings.CLEAROTRON_REPORTS_DIR)) found.push(`an install keeps its reports in ${settings.CLEAROTRON_REPORTS_DIR}`);
+    if (inside(settings.RECIPE_REPO_ROOT)) found.push(`an install keeps its saved searches in ${settings.RECIPE_REPO_ROOT}`);
+    if (inside(settings.CLEAROTRON_WORK_DIR)) found.push(`an install works in ${settings.CLEAROTRON_WORK_DIR}`);
+    if (existsSync(join(paths.base, ".env"))) found.push(`it holds a settings file, ${join(paths.base, ".env")}`);
+    if (!found.length && base === resolve(join(homedir(), "trademark"))) found.push("it is the directory an install is set up in by default");
+    // AN INSTALL NOBODY CONFIGURED still answers. `start --base <dir>` writes a guest list on every start
+    // and no settings at all, so an install somewhere of its own passes every check above. A guest list
+    // with no demo secret beside it is somebody's install; a demo's own base has both.
+    if (!found.length && existsSync(paths.grants) && !existsSync(demoTokenSecretPath(paths.base)))
+      found.push(`it holds a guest list, ${paths.grants}, and no demo of its own`);
+    if (found.length)
+      fatal(`--demo cannot run in ${paths.base}: ${found.join("; ")}.\n`
+        + "  The demo keeps its own data, and its own signing secret, in its base. Leaving those in an\n"
+        + "  install's directory would make keys issued for that install refuse at its door.\n"
+        + "  Run the demo without --base, or give it a directory of its own.");
+  }
   // ── THIS INSTALL'S FIRST START, read before this start writes either file that answers it ────────────
   //
   // The grants file and the config store's repository are both written further down, on every start
@@ -1171,7 +1207,15 @@ if (isMain) {
     return v;
   };
   const portalSecret = secretFor("PORTAL_SECRET");
-  const tokenSecret = secretFor("TRADEMARK_MCP_TOKEN_SECRET");
+  // A DEMO'S SIGNING SECRET IS KEPT IN ITS OWN BASE, so the key command it prints can sign for it; see
+  // `demoTokenSecret`. Every other secret a demo uses stays in memory.
+  const tokenSecret = DEMO
+    ? demoTokenSecret(paths.base, {
+      read: (f) => readFileSync(f, "utf8"),
+      write: (f, text) => { mkdirSync(dirname(f), { recursive: true }); writeSecretFile(f, text); },
+      mint: () => randomBytes(32).toString("base64url"),
+    })
+    : secretFor("TRADEMARK_MCP_TOKEN_SECRET");
   if (!process.env.PORTAL_LOCAL_USER) generated.PORTAL_LOCAL_USER = user;
   const stores = DEMO ? {} : storesForOtherReaders(paths);
 
@@ -2176,12 +2220,26 @@ 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: ${invocationPrefix()}clearotron key issue <email>`);
+      say(`               It refuses every caller until a key is issued: ${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("");
+  // ── WHAT `status` AND `stop` READ ABOUT THIS START ───────────────────────────────────────────────
+  //
+  // Both verbs knew only about background units, so with this start serving, `status` described units
+  // nobody installed and `stop` said nothing was running (measured on a published beta, 2026-09-11). The
+  // record is the address this banner just printed. It goes on every exit — Ctrl-C, a fatal refusal, a
+  // crash — and a start killed outright leaves a record whose process is gone, which the readers ignore.
+  try {
+    const forget = recordRunning({ pid: process.pid, demo: DEMO, base: paths.base, url: envs.url, host: HOST,
+      ports: { portal: ports.portal, mcp: ports.mcp, client: doorRunning ? ports.client : null },
+      startedAt: new Date().toISOString() });
+    process.on("exit", forget);
+  } catch (e) {
+    say(`  (\`status\` will not see this start: its record could not be written — ${String(e?.message ?? e)})`);
+  }
   // — THE BANNER TOLD THE SAME STORY ON EVERY START, and it was only true of the first.
   //
   // "printed once, above" describes what a FIRST start does. On every start after it the passphrase was
@@ -2273,17 +2331,35 @@ if (isMain) {
   // cannot succeed and given a service manager that is not on the machine and cannot be put there.
   // Reported from a real run. Same rule as the engine refusal above: do not name a route this platform
   // does not have.
-  const manager = backgroundManager();
-  if (manager) {
-    say(`  To get your prompt back instead, stop this and run  ${invoke("start")} --background`);
-    say(`  — same product, managed by ${manager}, and it survives logout.`);
-  } else {
-    say("  There is no background form on this platform: the product runs as long as this window does.");
-    say("  Leave it open and use a second terminal for the commands above.");
-  }
+  for (const line of backgroundOfferLines({ demo: DEMO, manager: backgroundManager(), start: invoke("start") })) say(line);
   say("");
 }
 
+/**
+ * The closing offer of a foreground start: how to get the prompt back, where there is a way.
+ *
+ * NOT IN A DEMO. The offer ran `start --background`, which set up a new, empty install in the reader's
+ * home — not the demo, its samples or its sign-in — and then failed where the user's systemd was not
+ * reachable (measured on a published beta, 2026-09-11). A demo has no background form, so it is not
+ * offered one. Where the offer stands, it names what it needs BEFORE the reader stops what is running.
+ * PURE.
+ */
+export function backgroundOfferLines({ demo = false, manager = null, start = "clearotron start" } = {}) {
+  if (demo) return [
+    "  The demo has no background form: it runs as long as this window does. Leave it open and use a",
+    "  second terminal for the commands above.",
+  ];
+  if (!manager) return [
+    "  There is no background form on this platform: the product runs as long as this window does.",
+    "  Leave it open and use a second terminal for the commands above.",
+  ];
+  return [
+    `  To get your prompt back instead, stop this and run  ${start} --background`,
+    `  — same product, managed by ${manager}, and it survives logout. It needs ${manager}'s user manager`,
+    "  reachable from this session; where it is not, that command says so and changes nothing you use.",
+  ];
+}
+
 /**
  * What a reader is told when a child this install cannot run without exits.
  *

package/bin/status.mjs

@@ -18,6 +18,7 @@ import { BACKGROUND_UNITS, resolvePorts } from "./start.mjs";
 import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // ONE KEY=value reader — what systemd actually reads
 import { CLIENT_DOOR_UNIT, clientDoorPort } from "../shared/client-door.mjs";
 import { invoke } from "../shared/invocation.mjs";
+import { readRunning, probe } from "../shared/running-start.mjs";
 import { configStaleness, stalenessWarning, parseSystemdTimestamp } from "../driver/config-staleness.mjs";   // — F48
 
 const UNIT_DIR = join(homedir(), ".config", "systemd", "user");
@@ -57,15 +58,34 @@ const startedEpochMs = (u) => {
     return parseSystemdTimestamp(line?.slice("ActiveEnterTimestamp=".length));
   } catch { return null; }
 };say("");
+// ── A FOREGROUND START ANSWERS HERE TOO ─────────────────────────────────────────────────────────────
+//
+// The README starts the product in a terminal, and this verb answered only for background units: with
+// everything up it printed a sentence about units the reader never installed (measured on a published
+// beta, 2026-09-11). The record gives the address `start` printed; the portal itself says whether it is up.
+const running = readRunning();
+for (const r of running) {
+  const what = r.demo ? "The demo" : "The product";
+  // The portal's liveness route, which answers without a session: the address itself asks for a sign-in
+  // and read as "not answering" over a portal that was up (driven 2026-09-11).
+  if (await probe(new URL("/portal/health", r.url).href)) say(`  ${what} is up, in the foreground — a terminal holds \`start\` (pid ${r.pid}); Ctrl-C there stops it.`);
+  else say(`  ${what} was started in the foreground (pid ${r.pid}), but its portal at ${r.url} is not answering.`);
+  say(`    Open         ${r.url}`);
+  say(`    Engine door  http://${r.host}:${r.ports.mcp}/mcp`);
+  if (r.ports.client) say(`    Client door  http://${r.host}:${r.ports.client}/mcp`);
+  say("");
+}
 let installed = 0;
 for (const u of BACKGROUND_UNITS) {
   if (!existsSync(join(UNIT_DIR, u))) continue;
   installed++;
   say(`  ${u.padEnd(34)} ${state(u)}`);
 }
-if (!installed) {
-  say("  No background units are installed — this box runs the product only while a terminal holds");
-  say(`  \`clearotron start\`. \`clearotron start --background\` is the form that survives the terminal.`);
+if (!installed && running.length) {
+  say("  No background units are installed.");
+} else if (!installed) {
+  say("  The product is not running: no terminal holds `start`, and no background units are installed.");
+  say(`  \`${invoke("start")}\` runs it in a terminal; \`${invoke("start")} --background\` runs it as services that survive logout.`);
 } else {
   // The ports come from the same resolver start uses, RESOLVED OVER THE UNITS' OWN FILE: the running
   // services read %h/.env via systemd, and this CLI's shell env may know nothing of it — the first

package/bin/stop.mjs

@@ -23,6 +23,7 @@ import { systemdSaid, looksLikeBusFailure, busRemedy, CAPTURE_STDERR } from "../
 import { BACKGROUND_UNITS } from "./start.mjs";
 import { CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
 import { invoke } from "../shared/invocation.mjs";
+import { readRunning } from "../shared/running-start.mjs";
 
 const UNIT_DIR = join(homedir(), ".config", "systemd", "user");
 const say = (s = "") => console.log(s);
@@ -91,17 +92,31 @@ for (const u of BACKGROUND_UNITS) {
 }
 // THE COMMENT HERE ALREADY NAMED THE CAUSE AND SHRUGGED AT IT. If there is no user bus, the disables
 // above did not happen either — so this is where that is said.
-try {
-  execFileSync("systemctl", ["--user", "daemon-reload"], CAPTURE_STDERR);
-} catch (e) {
-  const said = systemdSaid(e);
-  err(`  could not ask systemd to reload its units — ${said}`);
-  if (looksLikeBusFailure(said)) err(`\n${busRemedy()}\n`);
+// ONLY WHEN THERE WAS SOMETHING TO RELOAD. On a box with no unit installed the reload has nothing to do,
+// and asking anyway printed a bus error and `su` advice to a reader whose product was running in a
+// terminal — a WSL distribution without systemd meets exactly that (measured 2026-09-11).
+if (found) {
+  try {
+    execFileSync("systemctl", ["--user", "daemon-reload"], CAPTURE_STDERR);
+  } catch (e) {
+    const said = systemdSaid(e);
+    err(`  could not ask systemd to reload its units — ${said}`);
+    if (looksLikeBusFailure(said)) err(`\n${busRemedy()}\n`);
+  }
 }
 
 if (!found) {
-  say("  Nothing was running in the background — no pinned unit is installed on this box.");
-  say("  Nothing to do, and nothing was changed.");
+  // A FOREGROUND START IS NOT "NOTHING RUNNING". It is not this verb's to stop — its terminal holds it —
+  // but saying nothing was running while it served is the answer that sent a reader looking elsewhere.
+  const foreground = readRunning();
+  if (foreground.length) {
+    say("  No background product is installed, but the product is running in the foreground:");
+    for (const r of foreground) say(`    ${r.demo ? "the demo" : "the product"} at ${r.url} (pid ${r.pid})`);
+    say("  Ctrl-C in the terminal that holds it stops it. This verb stops only what `start --background` installed.");
+  } else {
+    say("  Nothing was running in the background — no pinned unit is installed on this box.");
+    say("  Nothing to do, and nothing was changed.");
+  }
 } else if (failures.length) {
   // THE SENTENCE THAT WAS WRONG. "The background product is stopped and the box runs nothing again" was
   // printed unconditionally — including on the run where four services stayed up. A reader who is told

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "6c0b09af72bcc7b6e57f5aa268ffb29361d1eaab",
-  "version": "0.3.0-beta.8"
+  "commit": "8f26558701f6930799f7d8f724ab2ea91e302103",
+  "version": "0.3.0-beta.9"
 }

package/driver/CHANGELOG.md

@@ -1,5 +1,15 @@
 # clearotron-driver
 
+## 0.3.0-beta.9
+
+### Patch Changes
+
+- 86061f4: Fixed: Commands printed while running from npx name the published version, so they still work after npm cleans its cache.
+- ab9dc2d: Fixed: When the engine cannot answer "Describe it", the page names the check that finds out why. It says "just now" only for a usage limit.
+- ab9dc2d: Fixed: `clearotron status` says whether a product started in a terminal is up, and on which addresses. `clearotron stop` says how to stop it.
+- ab9dc2d: Fixed: The demo no longer offers `start --background`, which set up an empty install in your home instead of running the demo.
+- ab9dc2d: Fixed: The key command the demo prints issues a key the demo's client door accepts, run exactly as printed.
+
 ## 0.3.0-beta.8
 
 ### Patch Changes

package/driver/compose-read.mjs

@@ -325,7 +325,26 @@ export function jsonFromTurnText(text) {
   return null;
 }
 
-export function makeComposeReader({ turn, now = () => new Date() } = {}) {
+/**
+ * What the page says when the engine did not answer a read.
+ *
+ * "JUST NOW" ONLY WHERE IT IS TRUE. Every failed turn said the reader "could not reach the engine just
+ * now", and on a fresh install whose engine was not signed in that sent a stranger to press the button
+ * again, forever: the failure was the sign-in, which no retry changes (measured on a published beta,
+ * 2026-09-11). A rate limit is the one failure known to pass, so it alone says so, with its reset time
+ * when the engine gave one. Everything else names the check that finds the cause — `checkCommand`, in the
+ * reader's own invocation and with no machine path, because the page is not a place to print one.
+ */
+export function engineFailureMessage(t, { checkCommand = "clearotron doctor --probe-engine" } = {}) {
+  if (t?.rateLimited) {
+    const at = t.resetsAt ? new Date(t.resetsAt) : null;
+    const when = at && !Number.isNaN(at.getTime()) ? ` It resets at ${at.toISOString().slice(11, 16)} UTC.` : "";
+    return `The engine is at its usage limit just now.${when} Try again then, or set the search up below.`;
+  }
+  return `The request could not be read: the engine did not answer it. \`${checkCommand}\` finds out why — set the search up below meanwhile.`;
+}
+
+export function makeComposeReader({ turn, now = () => new Date(), checkCommand } = {}) {
   if (typeof turn !== "function") return null;
   return async function read(brief) {
     const text = String(brief ?? "").trim();
@@ -361,7 +380,7 @@ export function makeComposeReader({ turn, now = () => new Date() } = {}) {
         + `${JSON.stringify(READ_SCHEMA)}\n\nThe brief:\n${text}`,
     });
     if (!t?.ok) {
-      return { ok: false, error: "engine", message: "The reader could not reach the engine just now — set the search up below.",
+      return { ok: false, error: "engine", message: engineFailureMessage(t, { ...(checkCommand ? { checkCommand } : {}) }),
         cause: t?.cause ?? "the engine turn did not complete", vendor: t?.vendor ?? null, authMode: t?.authMode ?? null,
         engine: t?.engine ?? null, model: t?.model ?? null };
     }

package/driver/engine/jx-turn.mjs

@@ -94,7 +94,10 @@ export function readJxTuple(tuple, { vendor, authMode, engine }) {
   if (tuple?.killed || tuple?.signals?.stalled)
     return { ok: false, cause: "the engine turn was killed before it answered (stall or wall)", truncationObservable: observable, ...base };
   if (tuple?.signals?.rateLimited)
-    return { ok: false, cause: "the engine turn was rate-limited", truncationObservable: observable, ...base };
+    // FLAGGED, not only described: a rate limit is the one failure a caller may call passing, and it
+    // needs to know that without parsing this sentence. `resetsAt` is the adapter's, when it read one.
+    return { ok: false, cause: "the engine turn was rate-limited", rateLimited: true, resetsAt: tuple?.signals?.resetsAt ?? null,
+      truncationObservable: observable, ...base };
   if (tuple?.code !== 0 || tuple?.json?.status !== "ok")
     return { ok: false, cause: `the engine turn did not complete cleanly (code ${tuple?.code ?? "?"}, status ${tuple?.json?.status ?? "none"})`,
       truncationObservable: observable, ...base };

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.8",
+  "version": "0.3.0-beta.9",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/portal-service.mjs

@@ -1590,7 +1590,10 @@ export function makePortalService({
           // A provider outage is not a portal fault and must not read as one. The composer shows the
           // sentence and keeps every field the user already typed — the brief is still in the box.
           audit({ event: "compose-read", by: principal.email, ok: false, error: String(e?.message ?? e) });
-          return { status: 502, json: { code: "read_failed", error: "The reader is not answering just now — set the search up below." } };
+          // NOT "just now": a throw says nothing about whether it will pass, and that wording sent a reader
+          // back to the button for a failure no retry fixes. It names the check instead.
+          return { status: 502, json: { code: "read_failed",
+            error: `The request could not be read: the reader failed. \`${browserCommand("doctor --probe-engine")}\` finds out why — set the search up below meanwhile.` } };
         }
         // Length, never content. A brief is client material — whose mark, for whose product, before
         // whose deadline — and an audit log is a different disclosure surface from a run store.
@@ -4711,7 +4714,8 @@ const PORT = PORT_CHOICE.port;
         return null;
       }
       log(`brief reading ON — engine=${runner.engine} billing=${runner.authMode} model=${model}`);
-      return makeComposeReader({ turn: runner.turn });
+      // The check a failed read points at, as a reader types it, with no path of this machine in it.
+      return makeComposeReader({ turn: runner.turn, checkCommand: browserCommand("doctor --probe-engine") });
     } catch (e) {
       // A missing dependency or a bad key shape must not stop the portal booting: everything else on
       // this service is the load-bearing product, and the composer degrades to exactly what it did

package/driver/suite-census.json

@@ -141,6 +141,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-command-printed-from-npx-outlives-the-cache.test.mjs": {
+          "tests": 3,
+          "asserts": 14,
+          "skips": 0,
+          "todos": 0
+        },
         "a-company-can-be-given-a-framework-after-it-exists.test.mjs": {
           "tests": 8,
           "asserts": 19,
@@ -375,6 +381,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-key-the-demo-prints-signs-for-that-demo.test.mjs": {
+          "tests": 5,
+          "asserts": 30,
+          "skips": 0,
+          "todos": 0
+        },
         "a-killed-browser-takes-its-children.test.mjs": {
           "tests": 2,
           "asserts": 4,
@@ -543,6 +555,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-read-the-engine-could-not-answer-names-the-check.test.mjs": {
+          "tests": 4,
+          "asserts": 14,
+          "skips": 0,
+          "todos": 0
+        },
         "a-real-dispatch-records-the-tool-that-served-it.test.mjs": {
           "tests": 1,
           "asserts": 5,
@@ -3095,7 +3113,7 @@
         },
         "portal-service.test.mjs": {
           "tests": 124,
-          "asserts": 671,
+          "asserts": 673,
           "skips": 1,
           "todos": 0
         },
@@ -4221,6 +4239,12 @@
           "skips": 0,
           "todos": 0
         },
+        "status-and-stop-see-a-foreground-start.test.mjs": {
+          "tests": 6,
+          "asserts": 25,
+          "skips": 0,
+          "todos": 0
+        },
         "status-says-when-a-service-predates-its-config.test.mjs": {
           "tests": 7,
           "asserts": 24,
@@ -4515,6 +4539,12 @@
           "skips": 0,
           "todos": 0
         },
+        "the-demo-offers-no-background-form.test.mjs": {
+          "tests": 4,
+          "asserts": 14,
+          "skips": 0,
+          "todos": 0
+        },
         "the-door-answers-the-address-it-advertises.test.mjs": {
           "tests": 9,
           "asserts": 37,

package/driver/systemd/render-units.mjs

@@ -112,19 +112,13 @@ export function unitsNeedingRender(root = ROOT) {
 // through `envFrom`, so a name that later gains an old spelling in the alias table keeps resolving —
 // a literal `process.env.X` here would be a spelling, and a spelling goes stale in silence.
 //
-// A `KEY=value` parser and nothing more: this reads the same file systemd's EnvironmentFile= reads, and
-// systemd does no shell expansion there either. Quotes are stripped because operators write them.
-export function parseEnvFile(text) {
-  const out = {};
-  for (const line of String(text ?? "").split("\n")) {
-    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
-    if (!m) continue;
-    let v = m[2].trim();
-    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
-    out[m[1]] = v;
-  }
-  return out;
-}
+// A `KEY=value` parser and nothing more, and it lives in `shared/env-file-merge.mjs` — a file that
+// imports nothing. THIS module is a command too: its `--apply` path awaits at the top level and imports
+// `bin/start.mjs` from inside that await, so anything that took the parser from here put a CLI in its
+// import path, and `start.mjs` doing so closed a cycle that stopped 21 install arms at once. Re-exported
+// so every reader here keeps one reader and one spelling.
+export { parseEnvFile } from "../../shared/env-file-merge.mjs";
+import { parseEnvFile } from "../../shared/env-file-merge.mjs";
 
 export function resolveValues(names, { env = process.env, envFile = null } = {}) {
   const fileVals = envFile && existsSync(envFile) ? parseEnvFile(readFileSync(envFile, "utf8")) : {};

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-artifacts-mcp
 
+## 0.3.0-beta.9
+
+No changes in this release.
+
 ## 0.3.0-beta.8
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.0-beta.8",
+  "version": "0.3.0-beta.9",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "MCP server to interrogate clearotron trademark-clearance runs — list/read artifacts, trace the full decision flow, telemetry/cost, coverage, single-run search, and a gated single-step what-if. Imports the clearotron-driver read-only; touches no driver/template/deploy files.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clearotron",
   "type": "module",
-  "version": "0.3.0-beta.8",
+  "version": "0.3.0-beta.9",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.8",
+  "version": "0.3.0-beta.9",
   "license": "AGPL-3.0-only",
   "description": "The unified trademark portal UI. One address, one login: who you are decides what you see. Built as a static bundle, served by driver/portal-service.mjs — the browser never reaches profile-service or recipe-service.",
   "engines": {

package/providers/oauth-mcp-bridge/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.0-beta.9
+
+No changes in this release.
+
 ## 0.3.0-beta.8
 
 No changes in this release.

package/providers/oauth-mcp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.3.0-beta.8",
+  "version": "0.3.0-beta.9",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "OAuth 2.1 MCP stdio bridge used by the engine's case-law gather stage (courtlistener / legaldatahunter).",

package/shared/client-door.mjs

@@ -102,6 +102,45 @@ export function denylistFor({ paths, demo = false, env = {}, home }) {
   return paths.denylist ?? denylistPathFor(env, home);
 }
 
+/**
+ * THE DEMO'S SIGNING SECRET, KEPT IN THE DEMO'S OWN BASE.
+ *
+ * The demo generated its signing secret per run and held it in memory only, so the key command its
+ * terminal printed could never sign a key its door would accept: run from a second terminal, as printed,
+ * it read the install's settings and refused (measured on a published beta, 2026-09-11). The secret now
+ * lives beside the demo's revocation list, mode 600, so `key issue --base <demo base>` reads the one the
+ * door was given, and removing the demo is still removing one directory.
+ */
+export const demoTokenSecretPath = (base) => join(base, "token-secret");
+
+/**
+ * The secret a demo's door signs with: the one its base already holds, or a new one written there.
+ * `io` is `{ read, write, mint }`; a read that finds nothing is the first start.
+ */
+export function demoTokenSecret(base, io) {
+  const path = demoTokenSecretPath(base);
+  let held = "";
+  try { held = String(io.read(path) ?? "").trim(); } catch { /* not yet written */ }
+  if (held) return held;
+  const fresh = io.mint();
+  io.write(path, `${fresh}\n`);
+  return fresh;
+}
+
+/**
+ * The key command a start prints beside its client door — runnable exactly as printed.
+ *
+ * A demo's door admits the demo's own account, so the command names it rather than a placeholder a reader
+ * cannot type, and it names the demo's base so the verb reads that demo's secret and guest list. An
+ * install moved with `--base` is named too, for its guest list; the default install needs neither.
+ */
+export function keyIssueCommand({ prefix = "", demo = false, user = null, base = null, defaultBase = null } = {}) {
+  const q = (d) => (/\s/.test(d) ? `"${d}"` : d);
+  const who = demo && user ? user : "<email>";
+  const where = base && (demo || base !== defaultBase) ? ` --base ${q(base)}` : "";
+  return `${prefix}clearotron key issue ${who}${where}`;
+}
+
 /**
  * Create the denylist if it is absent, so the door is born consulting a file that exists.
  *

package/shared/env-file-merge.mjs

@@ -34,6 +34,30 @@
  *                             like an engine fault. Names here must be values this code MINTS; putting
  *                             a credential a reader supplied in this list would delete their work.
  */
+// ── THE ONE `KEY=value` READER, AND IT LIVES IN A LEAF ────────────────────────────────────────────
+//
+// This reads the same file systemd's EnvironmentFile= reads, and systemd does no shell expansion there
+// either. Quotes are stripped because operators write them.
+//
+// IT USED TO LIVE IN `driver/systemd/render-units.mjs`, which is a COMMAND as well as a module, and its
+// `--apply` path awaits at the top level and imports `bin/start.mjs` from inside that await. So a reader
+// that took the parser from there put the command's own module in its import path: `start.mjs` importing
+// it closed a cycle, the CLI's top-level await never settled, and 21 install arms died at once with
+// "Detected unsettled top-level await" and nothing naming the cause (measured 2026-09-12). The parser has
+// no business depending on any of that — it is eleven lines of string handling — so it sits here, in a
+// file that imports nothing, and `render-units.mjs` re-exports it so its readers keep one reader.
+export function parseEnvFile(text) {
+  const out = {};
+  for (const line of String(text ?? "").split("\n")) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let v = m[2].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    out[m[1]] = v;
+  }
+  return out;
+}
+
 export function mergeEnvFile(text, additions, { by = "`npm start` (bin/start.mjs)", notes = {}, refresh = [] } = {}) {
   const body = typeof text === "string" ? text : "";
   const present = new Set();

package/shared/invocation.mjs

@@ -205,6 +205,24 @@ export function invocationForm(env = process.env, io = FS, installDir = INSTALL_
     // right there and naming it in full is true from any directory.
     return { form: "shim-path", prefix: `${globalDir}${sep}`, shim: globalExe, dir: globalDir, onPath, shadowedBy, staleInterpreter: null, via: "global" };
   }
+  // ── FROM NPX'S CACHE, THE PUBLISHED VERSION, NOT THE CACHE ──────────────────────────────────────────
+  //
+  // `in-place` below names the directory this install runs from, and under npx that is npm's cache:
+  // `cd <npm's cache> && npx clearotron …`. npm deletes that directory when it cleans its cache, so every
+  // command a verb printed there stopped working before its reader typed it (a packaged-install drive of
+  // `doctor`, 2026-09-11, found thirteen). `npx -p clearotron@<version>` fetches this same version from any
+  // directory. It is the decision `browserCommand` makes for a page, `npx clearotron@<version> <verb>`,
+  // spelled for a PREFIX, which the word `clearotron` follows. Asked after a shim of ours and a global
+  // install, which are stronger evidence than the cache path; a version that cannot be read falls through
+  // to `in-place` rather than naming a guess.
+  const npxVersion = npxVersionOf(installDir, io.read ?? readFileSync);
+  if (npxVersion) {
+    return {
+      form: "npx-pinned", prefix: `npx -p clearotron@${npxVersion} `, shim: path, dir,
+      onPath: false, shadowedBy: null, shimKind: shim.kind, otherInstall: shim.installDir,
+      staleInterpreter: shim.interpreterMissing === true ? shim.interpreter : null,
+    };
+  }
   // ✕ A BROKEN SHIM MUST NOT BE THE FORM WE HAND BACK, however well it identifies itself. Driven and
   // caught: doctor reported the stale interpreter and then told the reader to run `clearotron install`
   // to fix it — through the very shim it had just called broken. The advice for repairing a route

package/shared/running-start.mjs

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// running-start.mjs — which foreground `clearotron start` processes are serving on this machine, and where.
+//
+// `status` promises "is the product up, and on which ports", and knew only about background units. With
+// the product running the way the README starts it — `clearotron start` in a terminal — it printed a
+// sentence about units the reader never installed, and `stop` said nothing was running while the portal
+// answered 200 (measured on a published beta, 2026-09-11). A foreground start now leaves one small record
+// here while it serves, and both verbs read it.
+//
+// THE RECORD IS AN ADDRESS, NEVER PROOF OF LIFE. A start killed outright leaves its record behind, so a
+// record whose process is gone is read as absent, and `status` asks the portal itself before saying the
+// product is up. Three answers, all honest: up; started but not answering; not running.
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Where the records live: one file per serving process, beside the settings and the revocation list.
+ *
+ * `~/.config/clearotron` is this product's per-user directory and the only one it reads. An XDG state
+ * directory would be the tidier home for this, and it would be a NEW environment variable read by product
+ * code — a thing this repo documents in two contract files and classifies in another repo. Not worth a
+ * paired change for a file the reader never opens.
+ */
+export function runningDir({ home = homedir() } = {}) {
+  return join(home, ".config", "clearotron", "running");
+}
+
+/** Is this process alive? EPERM means it exists and belongs to somebody else, which is alive. */
+export function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e?.code === "EPERM"; }
+}
+
+/**
+ * Record one serving start. Returns the function that removes the record; calling it twice is harmless,
+ * so the caller can hang it on both its own shutdown and the process's `exit`.
+ */
+export function recordRunning(rec, { dir = runningDir() } = {}) {
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${rec.pid}.json`);
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(rec, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, file);
+  let gone = false;
+  return () => {
+    if (gone) return;
+    gone = true;
+    try { rmSync(file, { force: true }); } catch { /* already gone */ }
+  };
+}
+
+/** Every record whose process is alive, oldest pid first. Reads; removes nothing. */
+export function readRunning({ dir = runningDir(), alive = pidAlive } = {}) {
+  let names;
+  try { names = readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const name of names.filter((n) => /^\d+\.json$/.test(n))) {
+    let rec;
+    try { rec = JSON.parse(readFileSync(join(dir, name), "utf8")); } catch { continue; }
+    if (!Number.isInteger(rec?.pid) || typeof rec?.url !== "string" || !rec?.ports) continue;
+    if (!alive(rec.pid)) continue;   // a start that did not exit cleanly: its record says nothing now
+    out.push(rec);
+  }
+  return out.sort((a, b) => a.pid - b.pid);
+}
+
+/** Does the portal at `url` answer? A timeout or a refusal is "no", never "unknown dressed as yes". */
+export async function probe(url, { timeoutMs = 2000 } = {}) {
+  try { return (await fetch(url, { signal: AbortSignal.timeout(timeoutMs) })).ok; } catch { return false; }
+}