clearotron 0.3.0-beta.7 → 0.3.0-beta.9

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": "263794e3f7267c8ed0c25d9906efbb1694883674",
-  "version": "0.3.0-beta.7"
+  "commit": "8f26558701f6930799f7d8f724ab2ea91e302103",
+  "version": "0.3.0-beta.9"
 }

package/driver/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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
+
+- 9181d6a: Fixed: Commands the install, start and the New company screen print now run as printed, from any directory and after npm cleans its cache.
+- 0d75b4a: Fixed: A demo started with npx prints commands that keep working after npm cleans its cache.
+- 9181d6a: Fixed: Doctor, run before the first start, describes the local sign-in that start brings up, and drops checkout-only warnings on a packaged install.
+- 91888b2: Fixed: The package no longer names the hosted service's own hostnames; a deployment names its own.
+- 9181d6a: Fixed: The README installs with `npx clearotron install`, which needs no root, and no longer says the demo opens a browser.
+
 ## 0.3.0-beta.7
 
 ### 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.7",
+  "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

@@ -38,10 +38,9 @@ import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { storeInRepo, storeOutsideRepoMessage, makeCommittableAudit, resolveStoreRepoRoot, makeStoreCommit } from "../shared/store-in-repo.mjs";   //,
 import { customerStoreDir, customerStoreLine } from "../shared/customer-store.mjs";   // — one store for the surface and the runs
 import { clientFailureNote } from "../shared/client-failure-note.mjs";   // — one sentence, three surfaces
-import { bareInvocation, invocationPrefix, installRoute } from "../shared/invocation.mjs";   // — and why this one surface is by NAME
+import { bareInvocation, browserCommand, invocationPrefix, installRoute, npxVersionOf } from "../shared/invocation.mjs";   // — and why this one surface is by NAME
 import { stdioConnectOffer, stdioConnectFor, STDIO_SHAPES } from "../shared/stdio-connect.mjs";   // — ONE author for the connect route
 import { isWsl } from "../shared/wsl.mjs";   // — on WSL, the connect lines say where they run
-import { inNpxCache, ownVersion } from "../shared/permanent-install.mjs";   // — a demo from npx is reset through npx
 import { connectOffers, offersForWire } from "../shared/connect-clients.mjs";                 // — ONE table, resolved server-side
 
 /**
@@ -1534,6 +1533,10 @@ export function makePortalService({
           // half its readers. A WORD, never a command line and never a prefix: `invocationForm` can
           // answer with this machine's absolute path, and this value is rendered in a browser.
           setupRoute: installRoute(),
+          // THE COMMAND THAT FILES AN ORGANISATION, for the screen that cannot create a company without one.
+          // `browserCommand`'s rule: no path on this machine, and from npx's cache the published version
+          // rather than a bare name that reader does not have.
+          organisationCommand: browserCommand('start --organisation "<name>"'),
           // — a button that always fails must not render as available. The reason is
           // operator-shaped and staff-only; a client reads the generic sentence the button carries.
           controls: { stop: { available: stopControl.available !== false,
@@ -1587,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.
@@ -4708,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
@@ -4838,7 +4845,7 @@ const PORT = PORT_CHOICE.port;
       attempts: makeAttemptLimiter({ max: 10, windowMs: 5 * 60 * 1000 }),
       // The sign-in page's recovery line. It resets the file this portal reads, and names no path on this
       // machine, because the page is read before anyone has signed in (signInResetCommand says how).
-      resetCommand: signInResetCommand({ credentialPath, npxVersion: inNpxCache() ? ownVersion() : null }),
+      resetCommand: signInResetCommand({ credentialPath, npxVersion: npxVersionOf() }),
     };
   })();
 

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,
@@ -970,9 +988,9 @@
           "todos": 0
         },
         "an-install-from-npx-moves-out-of-the-cache.test.mjs": {
-          "tests": 11,
-          "asserts": 61,
-          "skips": 6,
+          "tests": 13,
+          "asserts": 78,
+          "skips": 7,
           "todos": 0
         },
         "an-mcp-route-says-which-challenge-it-answers-with.test.mjs": {
@@ -2747,7 +2765,7 @@
         },
         "no-internal-hostname-ships-in-the-package.test.mjs": {
           "tests": 1,
-          "asserts": 3,
+          "asserts": 4,
           "skips": 0,
           "todos": 0
         },
@@ -3095,7 +3113,7 @@
         },
         "portal-service.test.mjs": {
           "tests": 124,
-          "asserts": 670,
+          "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,
@@ -4587,6 +4617,12 @@
           "skips": 0,
           "todos": 0
         },
+        "the-first-hour-reads-true.test.mjs": {
+          "tests": 8,
+          "asserts": 41,
+          "skips": 0,
+          "todos": 0
+        },
         "the-fold-receipt-names-the-model.test.mjs": {
           "tests": 5,
           "asserts": 11,

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,13 @@
 # trademark-artifacts-mcp
 
+## 0.3.0-beta.9
+
+No changes in this release.
+
+## 0.3.0-beta.8
+
+No changes in this release.
+
 ## 0.3.0-beta.7
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.0-beta.7",
+  "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.7",
+  "version": "0.3.0-beta.9",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/dist/assets/{index-DBUVdQT-.js → index-qes7gLpM.js}

@@ -10508,6 +10508,7 @@ var api = {
 		}),
 		accountOrgs: Object.fromEntries(Object.entries(asRecord(b["accountOrgs"])).filter(([, v]) => typeof v === "string" && v)),
 		genericOrgs: asArray(b["genericOrgs"]).filter((o) => typeof o === "string" && o.length > 0),
+		organisationCommand: asString(b["organisationCommand"]) || "clearotron start --organisation \"<name>\"",
 		email: asString(b["email"]) ?? "",
 		accounts: asArray(b["accounts"]).filter((a) => typeof a === "string"),
 		allAccounts: b["accounts"] === "*",
@@ -19106,7 +19107,7 @@ function NewCompany({ ctx }) {
 		if (!raw.trim()) return [];
 		return parseLines(raw, spec.commaSeparated ?? false).filter((e) => !spec.item.ok(e));
 	});
-	const unmet = !typedName ? "Needs a name." : !key ? "Needs a key — type one below." : !orgChosen ? orgsHeld.length === 0 ? "No organisation is filed on this install yet. File one with: clearotron start --organisation \"<name>\"" : "Choose the organisation it belongs to." : refusedEntries.length ? `${refusedEntries.join(", ")} cannot be searched — fix or remove ${refusedEntries.length === 1 ? "it" : "them"}.` : null;
+	const unmet = !typedName ? "Needs a name." : !key ? "Needs a key — type one below." : !orgChosen ? orgsHeld.length === 0 ? `No organisation is filed on this install yet. File one with: ${ctx.me.organisationCommand}` : "Choose the organisation it belongs to." : refusedEntries.length ? `${refusedEntries.join(", ")} cannot be searched — fix or remove ${refusedEntries.length === 1 ? "it" : "them"}.` : null;
 	async function create() {
 		if (unmet || busy) return;
 		setBusy(true);

package/portal-ui/dist/index.html

@@ -49,7 +49,7 @@
     -->
     <link rel="preconnect" href="https://api.fontshare.com" crossorigin />
     <link href="https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700,900&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/portal/assets/index-DBUVdQT-.js"></script>
+    <script type="module" crossorigin src="/portal/assets/index-qes7gLpM.js"></script>
     <link rel="stylesheet" crossorigin href="/portal/assets/index-Cv-E_agg.css">
   </head>
   <body>

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.7",
+  "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,13 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.0-beta.9
+
+No changes in this release.
+
+## 0.3.0-beta.8
+
+No changes in this release.
+
 ## 0.3.0-beta.7
 
 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.7",
+  "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/access-audience.mjs

@@ -135,13 +135,14 @@ export function readAudience({ location = "", status = null, error = null, wwwAu
   if (error) return { kind: "unreachable", why: String(error?.message ?? error).slice(0, 200) };
   // ── THREE DOORS, NOT ONE ────────────────────────────────────────────────────────────────────────
   //
-  // This returned `not-fronted` for every response with no redirect, and measured against production's
-  // four configured hostnames that one label covered three materially different states:
+  // This returned `not-fronted` for every response with no redirect, and measured against a production
+  // deployment's four configured hostnames that one label covered three materially different states
+  // (the hosts are written here as placeholders; a deployment names its own):
   //
-  //   trademark.cordillera.ch        302  redirect present  → audience read, kid agrees
-  //   mcp.cordillera.ch/mcp          401  no redirect       → not-fronted   ← FALSE, it IS fronted
-  //   clients-mcp.cordillera.ch/mcp  401  no redirect       → not-fronted   ← FALSE, it IS fronted
-  //   agent-mcp.cordillera.ch/mcp    502  no redirect       → not-fronted   ← an origin fault
+  //   portal.example.com             302  redirect present  → audience read, kid agrees
+  //   mcp.example.com/mcp            401  no redirect       → not-fronted   ← FALSE, it IS fronted
+  //   clients-mcp.example.com/mcp    401  no redirect       → not-fronted   ← FALSE, it IS fronted
+  //   agent-mcp.example.com/mcp      502  no redirect       → not-fronted   ← an origin fault
   //
   // None of these was a false pass — every one returned ok:false, which is the property that matters
   // most and is untouched. It was a WRONG DIAGNOSIS on a safe failure, and the cost is a reader's hour

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

@@ -36,8 +36,8 @@
 // below is not a resolver check: the shim is read and must NAME THIS INSTALL, and a `clearotron` found
 // earlier on PATH demotes the bare form rather than confirming it. Identity, not availability. A later
 // sweep tempted to simplify this into `command -v` would be reintroducing the defect, not tidying it.
-import { existsSync } from "node:fs";
-import { basename, sep } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join, sep } from "node:path";
 import { INSTALL_DIR, inspectShim, pathPosition, shimDir, shimPath } from "./verb-shim.mjs";
 import { chdirPrefix } from "./os-advice.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
@@ -272,6 +290,25 @@ export function invocationPrefix(argv1 = process.argv[1] ?? "", env = process.en
 export const invoke = (verb, argv1 = process.argv[1] ?? "", env = process.env, io = FS, installDir = INSTALL_DIR) =>
   `${invocationPrefix(argv1, env, io, installDir)}clearotron ${verb}`;
 
+/** This install's version when it runs from npx's cache, read off its own manifest; `null` anywhere else. */
+export function npxVersionOf(installDir = INSTALL_DIR, read = readFileSync) {
+  if (!/[\\/]_npx[\\/]/.test(String(installDir ?? ""))) return null;
+  try { return JSON.parse(read(join(installDir, "package.json"), "utf8")).version ?? null; } catch { return null; }
+}
+
+/**
+ * A command the reader can type from any directory that still runs after npm cleans its cache.
+ *
+ * `invoke` answers how this install is reached NOW. From npx's cache that is `cd <the cache> && npx
+ * clearotron …`, which stops working once npm cleans the cache, and a remedy is typed later, often after
+ * that. So from npx's cache this names the published version, `npx clearotron@<version> …`, which npm
+ * fetches again wherever it is typed. Everywhere else it is `invoke`'s answer.
+ */
+export function reachableCommand(verb, { argv1 = process.argv[1] ?? "", env = process.env, io = FS, installDir = INSTALL_DIR, read = readFileSync } = {}) {
+  const version = npxVersionOf(installDir, read);
+  return version ? `npx clearotron@${version} ${verb}` : invoke(verb, argv1, env, io, installDir);
+}
+
 /**
  * The verb by NAME ONLY — no prefix, no path, no `npx`.
  *
@@ -292,6 +329,16 @@ export const invoke = (verb, argv1 = process.argv[1] ?? "", env = process.env, i
  */
 export const bareInvocation = (verb) => `clearotron ${verb}`;
 
+/**
+ * A command for a page rendered in a browser: `bareInvocation`'s rule, never a path on this machine, with
+ * one exception. Run from npx's cache the bare name is one the reader does not have, so the published
+ * version is named instead, `npx clearotron@<version> …`, which runs anywhere and names no path.
+ */
+export const browserCommand = (verb, installDir = INSTALL_DIR, read = readFileSync) => {
+  const version = npxVersionOf(installDir, read);
+  return version ? `npx clearotron@${version} ${verb}` : bareInvocation(verb);
+};
+
 /**
  * Refuse a prompt when there is nobody to answer it.
  *