clearotron 0.3.0-beta.5 → 0.3.0-beta.7

package/.env.example

@@ -399,6 +399,15 @@ CLEAROTRON_DEMO=
 # effect: deployment
 # CLEAROTRON_INVOKED_AS=
 
+# Marks an install that has already moved itself out of npm's npx cache. `npx clearotron install` first
+# installs the same version under ~/.local and then runs that copy's install, with this set to 1, so the
+# copy does not try to move itself a second time. Unset, an install running from npx's cache moves.
+# Set by bin/onboard.mjs on the one process it starts, never by an operator, so the row is left
+# commented. It is listed for the reason CLEAROTRON_DEMO is: the catalogue is about what an operator can
+# FIND. Read by bin/onboard.mjs.
+# effect: deployment
+# CLEAROTRON_RELOCATED=
+
 # How many client what-ifs the runner drains at once (default 1). A what-if re-runs ONE stage of a run
 # that already exists, in a sandbox, at a client's request — the owner opened it to clients on
 # 2026-08-27 and ruled SPEND controls out with it ("ignore the call spend"). This is not one.
@@ -552,8 +561,9 @@ CLEAROTRON_DEMO_PROFILES=
 # Your organisation's name. `npm run setup` asks for it (and, on a local install, not for a sign-in
 # address) and writes it here, quoted, so a name holding a `#` survives. The first `clearotron start` files it as the first
 # organisation in the grants file (CLEAROTRON_ACCESS_FILE) when that file holds none; from then on the
-# grants file holds the name, renaming is an edit there, and this is not read. Unset or empty, no
-# organisation is invented. `clearotron start --organisation <name>` supplies it for one start, and a
-# demo never reads it. Read by bin/start.mjs.
+# grants file holds the name and renaming is an edit there. The portal also reads it, to name the
+# organisation on its top bar and on its sign-in refusal page. Unset or empty, no organisation is
+# invented. `clearotron start --organisation <name>` supplies it for one start, and a demo never reads
+# it. Read by bin/start.mjs and shared/brand.mjs.
 # effect: deployment
 CLEAROTRON_ORGANISATION_NAME=

package/INSTALL.md

@@ -64,6 +64,15 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
   npx clearotron install
   ```
 
+  Run from `npx`, the install first installs Clearotron under `~/.local`, as `npm install -g --prefix
+  ~/.local` would, and finishes from there. That way the `clearotron` command and your assistant's connection
+  do not point into npm's temporary cache, which npm replaces on an update and deletes when it cleans up.
+  Later, the `update` command updates that copy in place.
+
+  On WSL, a program on the Windows side can hold a port that WSL reports as free, and the browser reaches
+  it first. VS Code's Remote-SSH port forwarding is the common case. If the page that opens is not this
+  install's sign-in, run the same command again with `--port 28802`, or any free number.
+
   A *hosted* deployment needs Linux for one further thing, the systemd outbox trigger —
   [driver/systemd/README.md](driver/systemd/README.md).
 - **A reasoning CLI on your `PATH`, signed in.** This is the prerequisite people miss. Every stage runs
@@ -754,6 +763,8 @@ Use the demo to see what this system produces. Use `npx clearotron start` to run
 - Creates `~/trademark/` — `pool/`, `workspace/`, `queue/`, `outbox/`, `locks/`, an empty grants file,
   and a small git repository for saved searches. Same base directory `npx clearotron install` uses, so whichever
   of the two you ran first, the other finds the same install. Move it with `npx clearotron start --base <dir>`.
+  That does not move anything the env file already names: the saved-search lines above, and the data
+  directories `npx clearotron install` wrote, keep pointing at the old place until you edit them.
 - Mints your sign-in passphrase and **prints it once**. Write it down. It is stored as a scrypt digest in
   `~/trademark/portal-local-credential.json`, nothing can read it back, and no later start reprints it. To
   get a new one, run `clearotron passphrase --reset`. An install that has been signing in with

package/bin/connect.mjs

@@ -47,6 +47,7 @@ import { execFileSync } from "node:child_process";
 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 } from "../shared/wsl.mjs";
 import { defaultDenylistPath, clientDoorAddress, clientDoorPort, clientDoorState, enablePlan, applyEnablePlan, describeChange, recordConnectKey, CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
 import { mintToken, tokenId, resolvePerson, loadGrants } from "../shared/scope.mjs";
 import { envFrom } from "../shared/env-aliases.mjs";
@@ -205,7 +206,8 @@ function deploymentHas(env = process.env) {
   return {
     // EVERY SHAPE, RESOLVED ONCE. A row picks its own; nothing here knows a client's name.
     stdioRoutes: Object.fromEntries(Object.keys(STDIO_SHAPES).map((shape) =>
-      [shape, stdioConnectFor(shape, { workDir: env.CLEAROTRON_WORK_DIR || null })])),
+      [shape, stdioConnectFor(shape, { workDir: env.CLEAROTRON_WORK_DIR || null, reportsDir: env.CLEAROTRON_REPORTS_DIR || null })])),
+    wsl: isWsl({ env }),
     // WHERE THE DOOR BINDS — not an address handed to any assistant. It is the loopback address the
     // unit listens on, and `enablePlan` needs it to write the unit. It used to be passed to the
     // resolver as `localAddress` and served to Cowork as somewhere to connect, which is the false

package/bin/onboard.mjs

@@ -68,6 +68,8 @@ import { nodeFloorVerdict } from "../shared/node-floor.mjs";   // — the floor
 import { invocationForm } from "../shared/invocation.mjs";   // — and WHY that form
 import { standFrom } from "../shared/invocation.mjs";   // is this tree one npm replaces?
 import { installShim } from "../shared/verb-shim.mjs";   // — the verb goes on PATH
+import { relocationPlan } from "../shared/permanent-install.mjs";   // — and the program out of npx's cache
+import { isWsl } from "../shared/wsl.mjs";   // — one answer to "is this WSL", shared with the connect lines
 import { styleFor, banner } from "../shared/tty-style.mjs";   // — weight where the meaning is
 import { bracketAsciiCells, BRAND } from "../shared/brand.mjs";      // F18 — the mark, from the geometry the SVG already uses
 // THE REFUSALS ABOUT THE SIGN-IN ADDRESS ITSELF, shared with `bin/start.mjs`. Two copies would be a
@@ -703,23 +705,8 @@ export function resolveEngineBin(bin, { env = process.env, wsl = null, onWindows
 /** A path on a Windows drive as WSL mounts it. */
 export const ON_A_WINDOWS_DRIVE = /^\/mnt\/[a-z]\//i;
 
-/**
- * Whether this is a Linux running under Windows.
- *
- * BOTH SIGNALS INJECTABLE, for the reason `platformEngineRefusal` gives: the readers this protects
- * are the ones who cannot run this suite to find out, so a Linux runner has to be able to drive both
- * answers rather than read the source and agree with it.
- *
- * A READ THAT FAILS ANSWERS "NOT WSL", and that is the direction that changes nothing: it leaves the
- * resolution exactly as it was before this existed. Claiming WSL on a could-not-read would start
- * refusing candidates under /mnt on an ordinary Linux box with an ordinary mount.
- */
-export function isWsl({ env = process.env, procVersion = null } = {}) {
-  if (String(env.WSL_DISTRO_NAME ?? "").trim()) return true;
-  if (String(env.WSL_INTEROP ?? "").trim()) return true;
-  const v = procVersion ?? (() => { try { return readFileSync("/proc/version", "utf8"); } catch { return ""; } })();
-  return /microsoft|wsl/i.test(v);
-}
+/** Whether this is a Linux running under Windows: the one answer, from shared/wsl.mjs. */
+export { isWsl };
 
 /**
  * What to say about candidates passed over because they sit on a Windows drive — or `null` when none
@@ -1860,7 +1847,7 @@ export async function runCheck() {
         try { loadRecipes({ dir: recipesDir, force: true }); } catch (e) { unreadable = String(e?.message ?? e).split("\n")[0]; }
         if (unreadable) {
           warn(`saved searches cannot be read from ${recipesDir}: ${unreadable}. Every company's saved searches fail `
-            + "to load, in the portal and the connector, until that file is fixed");
+            + "to load, in the portal and the connector, until it is fixed");
         } else ok(`saved searches are read from ${recipesDir}${handedBy}, and saves are committed in ${reach.repo}`);
       }
     }
@@ -2933,6 +2920,39 @@ if (!input.isTTY) {
   process.exit(2);
 }
 
+// ── OUT OF NPX'S CACHE, BEFORE ANYTHING IS WRITTEN ─────────────────────────────────────────────────────
+//
+// Run from npx, this program lives in npm's cache, and everything below would be wired to a directory npm
+// deletes: the launcher, and the connect line an assistant is registered with. So the install first puts
+// this same version somewhere permanent (shared/permanent-install.mjs) and runs itself from there. Nothing
+// has been written yet, so a failure here costs nothing, and it stops rather than carrying on: an install
+// finished from the cache is the defect, not a fallback.
+const move = relocationPlan();
+if (move && !move.skip && process.env.CLEAROTRON_RELOCATED !== "1") {
+  say(`\n  This is running from npm's temporary npx cache. Installing clearotron ${move.version} to ${move.prefix}`);
+  say("  first, so the launcher and your assistants keep working after npm cleans that cache or you update.\n");
+  // The npm that launched this, when npm says which: no second npm is guessed at.
+  const npmCli = process.env.npm_execpath;
+  const r = npmCli && existsSync(npmCli)
+    ? spawnSync(process.execPath, [npmCli, ...move.npmArgs], { stdio: "inherit" })
+    : spawnSync("npm", move.npmArgs, { stdio: "inherit" });
+  if (r.status !== 0 || !existsSync(move.entry)) {
+    console.error(`\n  Could not install clearotron to ${move.prefix}${r.error ? ` (${r.error.message})` : ""}. Nothing was installed, and nothing of yours was changed.`);
+    console.error(`  Run \`npm install --global --prefix ${move.prefix} clearotron@${move.version}\`, then \`${join(move.prefix, "bin", "clearotron")} install\`.\n`);
+    process.exit(1);
+  }
+  // THE REST OF THE INSTALL RUNS FROM THE PERMANENT COPY, with npm's marks of an npx arrival taken off, so
+  // it prints the commands of the install it now is.
+  const env = { ...process.env, CLEAROTRON_RELOCATED: "1" };
+  for (const k of ["npm_command", "npm_lifecycle_event", "npm_execpath"]) delete env[k];
+  const moved = spawnSync(process.execPath, [move.entry, "install", ...process.argv.slice(2)], { stdio: "inherit", env });
+  process.exit(moved.status ?? 1);
+}
+if (move?.skip) {
+  console.error(`\n  Note: this is running from npm's temporary npx cache and cannot be moved out of it here (${move.skip}).`);
+  console.error("  It will stop working when npm cleans that cache. `npm install -g clearotron` installs it permanently.\n");
+}
+
 // A credential typed at a prompt is echoed by the terminal and then sits in scrollback, in tmux history,
 // in whatever the reader pastes into a bug report. So the echo is muted while a secret is being typed:
 // the output stream readline writes through drops everything while `muted` is set.

package/bin/start.mjs

@@ -111,6 +111,7 @@ async function runTables() {
 import { spawn, spawnSync, execFileSync } from "node:child_process";
 import { storeInRepo, storeOutsideRepoMessage, storeCommitRefusal } from "../shared/store-in-repo.mjs";   //
 import { stdioConnectOffer } from "../shared/stdio-connect.mjs";
+import { demoProgramPlan } from "../shared/permanent-install.mjs";   // — a demo from npx keeps its own copy
 import { mergeEnvFile } from "../shared/env-file-merge.mjs";
 import { mcpOriginFor } from "../shared/lane-address.mjs";   // — one author for the origin
 import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "../shared/server-units.mjs";   // — one authority, two callers
@@ -300,6 +301,22 @@ export function resolvePorts(env = {}) {
     client: one("CLIENT_MCP_HTTP_PORT", clientDoorPort({})) };
 }
 
+/**
+ * WHAT TO DO WHEN THE PAGE THAT OPENS IS NOT OURS. Printed under every "Open" line.
+ *
+ * A port can be free where this runs and taken where the browser runs: on WSL, a Windows-side listener
+ * (VS Code's Remote-SSH forwarding is the one measured, 2026-09-11) answers 127.0.0.1 before WSL does. The
+ * doors bind cleanly, the in-use detection has nothing to see, and the browser shows somebody else's page
+ * with nothing on this screen saying so. `--port` already moves all three doors; the reader has to be told
+ * about it at the moment the address is handed over, which is here.
+ */
+export function foreignPageHint(verb) {
+  return [
+    "If the page that opens is not this install's sign-in, another program on this machine holds that",
+    `port from outside this environment. Run \`${invoke(verb)} --port 28802\` (or any free number) instead.`,
+  ];
+}
+
 /**
  * Apply `--port <n>` to the three doors.
  *
@@ -740,6 +757,10 @@ export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsTok
       // already wrong for a process that is not the portal.
       ...(demo ? {
         CLEAROTRON_DEMO: "1",
+        // A DEMO NAMES NO ORGANISATION. The portal reads this to name the one running the install, on its
+        // top bar and its sign-in refusal page, and an exported value is the reader's real organisation.
+        // The portal's alone: no door names an organisation, and the doors stay as a live install's.
+        CLEAROTRON_ORGANISATION_NAME: "",
         // AND THE SIGN-IN CREDENTIAL LIVES IN THE DEMO'S OWN BASE. Without this it defaults to
         // ~/.cordillera/portal-local-credential.json — shared with every install on the box — and the
         // demo then inherits a digest minted for somebody else's address: the portal prints "the
@@ -1370,8 +1391,13 @@ if (isMain) {
     // SEEDED FROM A COPY, for the reason the player publishes from one: republishing writes a receipt
     // into the run directory it reads, and `demo/` is tracked. This is the path a reader actually takes
     // — `clearotron demo` hands over to this — so fixing the player alone left the defect where it was.
-    const { publishSource } = await import("../driver/demo-container.mjs");
+    const { publishSource, seedDemoRuns } = await import("../driver/demo-container.mjs");
     const seed = await seedPool({ pool: paths.pool, examplesDir: publishSource(join(REPO, "demo"), { repoRoot: REPO }), republish: republishRun });
+    // 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.
+    const runs = seedDemoRuns({ workspace: paths.workspace, examplesDir: join(REPO, "demo"), portalOrigin: `http://${HOST}:${ports.portal}` });
+    if (runs.seeded.length) say(`  runs           ${runs.seeded.length} sample run(s) your assistant can list, brief and open`);
     // WHAT WAS ALREADY THERE IS SAID TOO. This branch used to run only when the pool
     // was empty; it now tops a stale pool up to the package's set, so "seeded 1" on an upgrade is a fact
     // about what was MISSING and says nothing on its own about how many are now listed.
@@ -1431,6 +1457,33 @@ if (isMain) {
   // the file the verb resets is the file the portal reads. A demo keeps its own, by layout (childEnv).
   const { installCredential } = await import("../driver/portal-local-auth.mjs");
   const signIn = DEMO ? null : installCredential({ base: paths.base, env: process.env, firstStart: firstStartOfThisInstall });
+  // ── A DEMO RUN FROM NPX KEEPS ITS OWN COPY OF THE PROGRAM ───────────────────────────────────────────
+  //
+  // Its connect line launched the connector from npm's cache, which npm deletes when it cleans up, so an
+  // assistant registered with it lost the demo without a word (measured on a published beta, 2026-09-11).
+  // The same version goes into `<base>/program` (shared/permanent-install.mjs), BEFORE the services start
+  // so the portal's connect rows name it too, and only when it is not there already. It never stops the
+  // demo: if npm fails, the demo runs as before and says the line will not survive a cache clean.
+  let demoProgramRoot = null;
+  if (DEMO) {
+    const plan = demoProgramPlan({ base: paths.base });
+    if (plan?.current) demoProgramRoot = plan.root;
+    else if (plan && !plan.skip) {
+      say(`  program        copying clearotron ${plan.version} into ${plan.prefix}, so your assistant's connection survives npm cleaning its cache`);
+      // The npm that launched this, when npm says which: no second npm is guessed at.
+      const npmCli = process.env.npm_execpath;
+      const r = npmCli && existsSync(npmCli)
+        ? spawnSync(process.execPath, [npmCli, ...plan.npmArgs], { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 180_000 })
+        : spawnSync("npm", plan.npmArgs, { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 180_000 });
+      if (r.status === 0 && existsSync(join(plan.root, "mcp-server", "server.mjs"))) demoProgramRoot = plan.root;
+      else {
+        const why = r.error ? r.error.message : String(r.stderr ?? "").trim().split("\n").pop() || `npm exited ${r.status}`;
+        say(`  program        could not be copied (${why}). The connect line below runs from npm's temporary cache,`);
+        say("                 so it stops working when npm cleans that cache; start the demo again to retry.");
+      }
+    }
+  }
+
   const envs = childEnv({ ports, paths, user, portalSecret, tokenSecret, opsToken,
     localWorker: wantWorker, demo: DEMO, clientFence: declaredFence || null,
     credential: signIn && signIn.source !== "shared" ? signIn.path : null });
@@ -1879,6 +1932,7 @@ if (isMain) {
     }
     say("");
     say(`  Open:            ${envs.url}`);
+    for (const line of foreignPageHint(DEMO ? "demo" : "start")) say(`                   ${line}`);
     say("  This SURVIVES the terminal — close the window, the product keeps running.");
     say(`  Stop it:         ${invoke("stop")}   (stops and removes the units; issued connect keys survive — \`${invoke("disconnect")}\` revokes those)`);
     say(`  Is it up?        ${invoke("status")}`);
@@ -2112,6 +2166,7 @@ if (isMain) {
 
   say("");
   say(`  Open   ${envs.url}`);
+  for (const line of foreignPageHint(DEMO ? "demo" : "start")) say(`         ${line}`);
   say("");
   // ── TWO DOORS, TWO AUDIENCES, BOTH NAMED ( — F26) ─────────────────────────
   //
@@ -2209,7 +2264,10 @@ if (isMain) {
   //
   // The string comes from the ONE composer, not from a literal here: three surfaces state this route
   // and a line of instruction with more than one author drifts silently.
-  const connect = stdioConnectOffer({ workDir: process.env.CLEAROTRON_WORK_DIR || null });
+  // THE WORKSPACE AND POOL THE SERVICES WERE HANDED, not this process's environment: a demo reads no env
+  // file, so its own line named no workspace and the connector fell back to the real install's.
+  // A demo run from npx names its own copy of the program, which a cache clean does not remove.
+  const connect = stdioConnectOffer({ workDir: paths.workspace, reportsDir: paths.pool, ...(demoProgramRoot ? { installRoot: demoProgramRoot } : {}) });
   say("  Connect your assistant to this install — one line, no address and no sign-in:");
   say("");
   say(`    ${connect.command}`);

package/bin/update.mjs

@@ -59,6 +59,8 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-p
 import { readEnvFile } from "./onboard.mjs";
 import { invoke, invocationPrefix } from "../shared/invocation.mjs";   // — name a command the reader can actually type
 import { rebuildIfStale } from "../shared/bundle-rebuild.mjs";   // a pull cannot update an untracked bundle
+import { packagedUpdate } from "../shared/permanent-install.mjs";   // — a packaged install updates at its own prefix
+import { installShim, inspectShim, shimPath } from "../shared/verb-shim.mjs";   // — npm's link replaces the launcher
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 const ENV_PATH = envLocalPath({ repoRoot: REPO });   // resolved, never composed: one resolver, so moving this file later is one line
@@ -246,13 +248,22 @@ export async function update(argv = process.argv.slice(2)) {
   // not succeed` — true, useless, and pointing at the wrong thing entirely. `update` is the verb a
   // stranger reaches for, so the one install we expect most people to have must not be answered with
   // a git error about a directory that was never a repository.
+  //
+  // A PACKAGED INSTALL NOW UPDATES ITSELF, the way it was installed: npm, at the prefix it lives under, on
+  // the channel it came from (shared/permanent-install.mjs). It runs AFTER the live-run refusal below,
+  // because npm replaces the program's files as surely as `npm ci` does. Only a layout that cannot be
+  // named is still refused.
+  let packaged = null;
   if (!isGitCheckout()) {
-    console.error("\n  This install is not a git checkout, so there is nothing to pull.");
-    console.error("  It was installed from a package rather than cloned, which is the ordinary way.");
-    console.error("\n  Update it the way it was installed:\n");
-    console.error("      npm install -g clearotron@latest\n");
-    console.error("  Nothing was touched.");
-    return 4;
+    packaged = packagedUpdate();
+    if (!packaged) {
+      console.error("\n  This install is not a git checkout, so there is nothing to pull.");
+      console.error("  It was installed from a package rather than cloned, which is the ordinary way.");
+      console.error("\n  Update it the way it was installed:\n");
+      console.error("      npm install -g clearotron@latest\n");
+      console.error("  Nothing was touched.");
+      return 4;
+    }
   }
 
   // ── AND THE SECOND REFUSAL: NOT OVER A LIVE RUN ──────────────────────────────────────────────
@@ -289,6 +300,27 @@ export async function update(argv = process.argv.slice(2)) {
     return 4;
   }
 
+  if (packaged) {
+    if (packaged.current) {
+      say(`\n  This install is ${packaged.installed}, and nothing newer is published (${packaged.tag}: ${packaged.version}). Nothing was touched.\n`);
+      return 0;
+    }
+    if (packaged.unread) say(`\n  npm did not say which versions are published, so this follows the ${packaged.tag} channel.`);
+    say(`\n  Updating this install at ${packaged.prefix} from ${packaged.installed ?? "an unreadable version"} to clearotron@${packaged.spec}.`);
+    const rc = runInCheckout("npm", packaged.npmArgs);
+    if (rc !== 0) return rc;
+    // npm puts its own link back at `<prefix>/bin/clearotron` on every install, over the launcher the
+    // install wrote, and that link runs whichever `node` is first on PATH. Put the launcher back, but only
+    // over npm's link or our own: anything else there was not ours before this update either.
+    const kind = inspectShim(shimPath()).kind;
+    if (kind === "npm-link" || kind === "ours" || kind === "ours-other-install") {
+      const shim = installShim();
+      if (!shim.ok) console.error(`\n  The update worked, but the launcher at ${shim.path ?? "~/.local/bin/clearotron"} could not be written back: ${shim.detail}.`);
+    }
+    say("\n  Updated. An assistant starts the new version the next time it launches Clearotron; restart the services for the portal.\n");
+    return 0;
+  }
+
   say("\n  Configuration store is outside the checkout. Updating the product.");
   for (const e of entries) say(`    ${e.name}=${e.value} (${e.from})`);
   if (!entries.length) {

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "a9ac3366ee814b9faf6a5d23fe7d0c8f3a5c0d3f",
-  "version": "0.3.0-beta.5"
+  "commit": "263794e3f7267c8ed0c25d9906efbb1694883674",
+  "version": "0.3.0-beta.7"
 }

package/demo/full-country-search/run/status.json

@@ -27,7 +27,7 @@
   "stepTotal": 9,
   "lastStage": "publish",
   "verdict": "CONDITIONAL",
-  "url": "https://test-trademark.cordillera.ch/tmpdemo2014fullcountrysearch-venqori-2026-09-03-sample-capture/report.html",
+  "url": "/portal/report/tmpdemo2014fullcountrysearch-venqori-2026-09-03-sample-capture/",
   "failedStage": null,
   "reason": null,
   "deliveredAt": "2026-09-03T18:06:17.281Z",

package/demo/global-preliminary-search/run/status.json

@@ -27,7 +27,7 @@
   "stepTotal": 9,
   "lastStage": "publish",
   "verdict": "CONDITIONAL",
-  "url": "https://test-trademark.cordillera.ch/tmpdemo2014globalpreliminarysearch-venqori-2026-09-02-sample-capture/report.html",
+  "url": "/portal/report/tmpdemo2014globalpreliminarysearch-venqori-2026-09-02-sample-capture/",
   "failedStage": null,
   "reason": null,
   "deliveredAt": "2026-09-02T17:33:15.625Z",

package/demo/knockout-search/run/email-body.md

@@ -1,3 +1,3 @@
-<p style="font-family:Calibri,sans-serif;font-size:11pt">Knockout trademark review — DEMO-2014-knockout-search: <b>1 mark</b>, worst band <b style="color:#2f55a4">Low</b>. <a href="https://test-trademark.cordillera.ch/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/report.html">Open the full report</a> · <a href="https://test-trademark.cordillera.ch/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/audit.xlsx">audit workbook</a>.</p>
+<p style="font-family:Calibri,sans-serif;font-size:11pt">Knockout trademark review — DEMO-2014-knockout-search: <b>1 mark</b>, worst band <b style="color:#2f55a4">Low</b>. <a href="/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/">Open the full report</a> · <a href="/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/audit.xlsx">audit workbook</a>.</p>
 <ul style="font-family:Calibri,sans-serif;font-size:11pt"><li><b>VENQORI</b>: <b style="color:#2f55a4">Low</b> — Classes 9, 42, 41 — Register filings (classes 9, 42, 41): 0 identical, 0 containing, 0 on close variations.</li></ul>
 <p style="font-family:Calibri,sans-serif;font-size:11pt"><i>Ratings reflect our common law assessment. Register analysis may adjust ratings in either direction.</i></p>

package/demo/knockout-search/run/status.json

@@ -33,7 +33,7 @@
   "stepN": 6,
   "stepTotal": 6,
   "verdict": "Low",
-  "url": "https://test-trademark.cordillera.ch/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/report.html",
+  "url": "/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/",
   "failedStage": null,
   "reason": null,
   "deliveredAt": "2026-09-02T21:46:53.238Z",
@@ -254,7 +254,7 @@
   "reports": [
     {
       "mark": "VENQORI",
-      "url": "https://test-trademark.cordillera.ch/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/report.html"
+      "url": "/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/"
     }
   ],
   "sendPending": true,

package/demo/multi-country-focus-search/run/status.json

@@ -27,7 +27,7 @@
   "stepTotal": 9,
   "lastStage": "publish",
   "verdict": "CONDITIONAL",
-  "url": "https://test-trademark.cordillera.ch/tmpdemo2014multicountryfocussearch-venqori-2026-09-02-sample-capture/report.html",
+  "url": "/portal/report/tmpdemo2014multicountryfocussearch-venqori-2026-09-02-sample-capture/",
   "failedStage": null,
   "reason": null,
   "deliveredAt": "2026-09-02T19:51:48.801Z",

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

@@ -285,12 +285,13 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | `CLEAROTRON_DEMO` | unset | `1` puts this install in the DEMO posture. **Ordering is real**: the four products are listed and orderable, the form, the plan and the confirmation are the product's own, and the confirmation resolves to a finished report that already exists rather than dispatching — no engine turn, no register call, no queue entry, no run directory (ruling 2026-08-31, superseding the greyed-control ruling of the same day). A product the demo carries no finished report for refuses and names which one. It also re-aims two boot warnings written for an operator of a real deployment at the visitor who is not one, from one place (`driver/demo-posture.mjs`). **Set by `npx clearotron demo`, not by an operator** — it is passed explicitly to the two processes that have a reason to know (the portal and the MCP door; the worker is not told, because a demo never queues anything for it to drain), and those run with `CLEAROTRON_NO_ENV_FILE=1`, so a stray `.env` can neither put a live install into demo mode nor take a demo out of one. Anything but the literal `1` is not a demo. Replaces `PORTAL_DEMO`, which named only one of the processes that has to know. |
 | `CLEAROTRON_TEST_FIXTURE_PROFILES` | unset | `1` makes the profile loader return the three suite fixtures, which are refused from every roster otherwise. Set by `scripts/test-run.mjs`, never by an operator; an explicit `includeTestFixtures` argument beats it. Effect class `harness`; the full contract is its row in `.env.example`. |
 | `CLEAROTRON_DEMO_PROFILES` | unset | `1` makes the profile loader return the bundled demo account, which a fresh install does not resolve (ruling 2026-09-08). Set by `clearotron demo`, `start --demo` and the suite runner, never by an operator. The gate is on the bundled layer, so a deployment's own configured store keeps its `demoData` accounts either way. Effect class `harness`; the full contract is its row in `.env.example`. |
-| `CLEAROTRON_ORGANISATION_NAME` | unset | Your organisation's name, written quoted by `npx clearotron install`, which asks for it and not for a sign-in address. The first `clearotron start` files it as the first organisation in the grants file (`CLEAROTRON_ACCESS_FILE`) when that file holds none; from then on the grants file holds the name, renaming is an edit there, and this is not read. Unset ⇒ no organisation is invented. `clearotron start --organisation <name>` supplies it for one start, and a demo never reads it. Effect class `deployment`; the full contract is its row in `.env.example`. |
+| `CLEAROTRON_ORGANISATION_NAME` | unset | Your organisation's name, written quoted by `npx clearotron install`, which asks for it and not for a sign-in address. The first `clearotron start` files it as the first organisation in the grants file (`CLEAROTRON_ACCESS_FILE`) when that file holds none; from then on the grants file holds the name and renaming is an edit there. The portal also reads it, to name the organisation on its top bar and on its sign-in refusal page. Unset ⇒ no organisation is invented. `clearotron start --organisation <name>` supplies it for one start, and a demo never reads it. Effect class `deployment`; the full contract is its row in `.env.example`. |
 | `PORTAL_LOCAL_CREDENTIAL` | `~/.cordillera/portal-local-credential.json` | Where local sign-in keeps its passphrase DIGEST. `clearotron start` points it inside the install's own base directory for a new install, so it mints its own passphrase instead of adopting a digest another install left; an install that has been signing in with the shared file keeps it. `npx clearotron demo` always points it inside the demo's own base directory and mints a new passphrase there on every start, so a demo never inherits a digest minted for another address, and removing the demo stays one `rm -rf`. |
 | `PORTAL_LOCAL_PASSPHRASE` | unset | **NEVER set this in a file.** An internal one-shot handoff, not an operator control: on a first FOREGROUND start the supervisor mints the passphrase and hands it to the portal it spawns *at the spawn call*, so the closing summary can print the value beside the address rather than sending a first-time reader back into eleven startup log lines for the one value in this product that cannot be read back. It is deliberately absent from the composed child environments, because that composition is what `--background` writes into the units' env file — a passphrase there would be a permanent plaintext copy on disk and the product's own sentence, "it is stored only as a digest", would stop being true. Setting it in any env file recreates exactly that. Lost passphrase: `clearotron passphrase --reset`. |
 | `PORTAL_URL` | `http://127.0.0.1:18802`, or built from `PORTAL_SERVICE_HOST`/`PORTAL_SERVICE_PORT` | Where the deploy tick's live-surface check expects to reach the portal. |
 | `PORTAL_OPS_TOKEN_FILE` | `~/.config/systemd/user/trademark-portal.service.d/secrets.conf` | The systemd drop-in the live-surface check reads `PORTAL_OPS_TOKEN` out of. It reads the FILE rather than the environment so a check run by hand sees the same token the service does. |
 | `CLEAROTRON_INVOKED_AS` | unset (⇒ the verb's own `argv[1]`) | How the reader typed the command, so every command a verb prints for them to type next is spelled the way they type it: `clearotron …` after a global install, `npx clearotron …` otherwise. The dispatcher runs each verb as a process of its own, whose `argv[1]` is always `bin/<verb>.mjs`, so `bin/clearotron.mjs` passes its own `argv[1]` down in this name. **Set by the dispatcher, never by an operator.** Effect class `deployment`; the full contract is its row in `.env.example`. |
+| `CLEAROTRON_RELOCATED` | unset (⇒ an install running from npx's cache moves itself to `~/.local` first) | Marks an install that has already made that move. `npx clearotron install` installs the same version under `~/.local`, then runs that copy's install with this set to `1`, so the copy does not try to move itself again. **Set by the install on the one process it starts, never by an operator.** Effect class `deployment`; the full contract is its row in `.env.example`. |
 | `CLEAROTRON_REQUIRE_EXPLICIT_PORTS` | unset | `1` makes a service that would listen on a built-in default port refuse to start instead of warning. For a box that runs more than one instance, where one instance's default is another's port on the day that other instance is down. Unset, a service on a default port still says so as it starts. Effect class `deployment`. |
 | `CLEAROTRON_UPDATER_STAMP` | `_updater-identity.json` beside the update script, in the directory the updater runs from | The full path of the file in which the updater that deploys this box records which copy of itself ran. The updater writes it and deploy health reads it under this one name, so a box that moves the stamp sets it once for both. On a box with no updater unit, setting it says an updater exists elsewhere and is to be judged. Effect class `deployment`. |
 | `CLEAROTRON_CUT_REF` | `HEAD` | Which ref the cut decision reads the version from. **Read only by the release workflow, never set on a deployment.** The jobs that ask about `main` set it to `origin/main` explicitly, because their checkout is pinned to the run's own ref and `HEAD` there is that ref rather than the branch they are deciding about. A job that asks the wrong subject gets a confident wrong answer. |

package/driver/CHANGELOG.md

@@ -1,5 +1,30 @@
 # clearotron-driver
 
+## 0.3.0-beta.7
+
+### Patch Changes
+
+- c5744bf: Fixed: A demo started with npx keeps its assistant connection working after npm cleans its cache.
+- c5744bf: Fixed: An assistant connected to the demo now opens each sample report on the demo's own portal, not on another server.
+- c5744bf: Fixed: The portal names the organisation setup recorded, and the product keeps its own name beside it.
+
+## 0.3.0-beta.6
+
+### Patch Changes
+
+- 2ca849d: Fixed: When codex's sign-in can no longer be refreshed, the search stops and says to run `codex login`. It used to retry with a bare exit code.
+- a81279f: Fixed: When the portal address opens someone else's page, for example a port forwarded from outside WSL, Clearotron now says so and points you to `--port`.
+- a81279f: Fixed: The sign-in page clears a session left by another Clearotron on the same address and says so. A refusal that is not about the passphrase now says what it is about.
+- f133f7d: Fixed: A passphrase pasted with a space or line break at either end now signs in, instead of being refused as wrong.
+- 2ca849d: Fixed: A manager who does not run the installation no longer sees server file paths when a new company cannot be recorded or filed.
+- a81279f: Fixed: The local sign-in page no longer invites the browser to fill in a saved password from another install.
+- a81279f: Fixed: `npx clearotron install` now installs Clearotron permanently under `~/.local` before setting up. The `clearotron` command and your assistants' connections keep working after npm cleans its cache.
+- 2ca849d: Fixed: When the saved-search store exists but cannot be read, the connector and `clearotron doctor` now say so, instead of reporting no saved searches.
+- a81279f: Fixed: On WSL, the "on this computer" connect steps now say to run them inside WSL. The Claude Code line registers Clearotron for every project and works in Windows PowerShell.
+- a81279f: New: An assistant connected to `clearotron demo` can now list, brief and open the demo's four sample runs. They stay inside the demo's own folder.
+- a81279f: Fixed: The sign-in page's reset line now runs for a demo started with npx, and resets that demo's own passphrase.
+- a81279f: New: `clearotron update` now updates an npm-installed copy itself, and a beta install moves on to the release once it is published.
+
 ## 0.3.0-beta.5
 
 ### Patch Changes

package/driver/contract-e3-backlog.mjs

@@ -221,7 +221,7 @@ export const E3_BACKLOG = [
     where: "driver/skills/prelim-common-law/SKILL.md:192 (restated at driver/skills/prelim-search/synthesis-rules.md:394)",
     surface: "skill-file",
     evidence: "A clean PR/connotation row MUST cite its search — add a `**Connotation-search source:** <URL | \"perplexity_research — no result\">` line.",
-    reparsedBy: "driver/connotation-search.mjs — validators.commonLaw rejects a clean claim with no such line (connotation_search_missing); the hint is re-dictated at driver/gateway.mjs:1824",
+    reparsedBy: "driver/connotation-search.mjs — validators.commonLaw rejects a clean claim with no such line (connotation_search_missing); the hint is re-dictated by correctionHint() in gateway.mjs",
     removedByMove: "NOTHING ON THE #850 PLAN REMOVES THIS",
   },
   {

package/driver/demo-container.mjs

@@ -23,9 +23,9 @@
 // stage apart. This module is the single answer. `cut/` cannot import it (that directory does not travel
 // and this one does), so the pack gate restates the disjunction and its own test pins the two together.
 
-import { cpSync, existsSync, mkdtempSync, readdirSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 
 /** The entry file each lane's publisher reads as its source, in the order a child is probed for one. */
 export const ENTRY_FILES = Object.freeze(["report.md", "knockout-findings.json"]);
@@ -78,3 +78,66 @@ export function publishSource(dir, { repoRoot, tmp = tmpdir() } = {}) {
   cpSync(here, copy, { recursive: true });
   return copy;
 }
+
+/**
+ * THE DEMO'S SAMPLE RUNS, WHERE AN ASSISTANT LOOKS FOR RUNS.
+ *
+ * The demo published its samples as reports and made no run directory, so the connector its own connect
+ * line wires listed nothing: an assistant, one of the demo's three faces, had nothing to explore. Each
+ * sample's finished `run/` is copied to the layout the connector walks, under the DEMO'S OWN workspace:
+ * `<workspace>/workspace-<agent>/studio/prelim-search/<slug>/<date>-<codename>/`. Nothing is written
+ * anywhere else, so a real install started afterwards sees none of it (the demo is its own install).
+ *
+ * Copied, never linked: a connector reading a run may write beside it, and `demo/` is tracked. A run
+ * already in place is not copied again, so a visitor's second start changes nothing but its links.
+ *
+ * ITS REPORT LINKS POINT AT THIS DEMO'S PORTAL. Each sample's `status.json` carried the report URL it was
+ * stamped with where it was captured, a test instance's address, and the connector hands a run's `url` to
+ * the assistant as-is, so an assistant asked to open a demo report sent the person to that host (measured
+ * on a published beta, 2026-09-11). The tracked samples now carry the portal's own route,
+ * `/portal/report/<runId>/`, with no host, and each copy here is stamped with `portalOrigin`, the demo
+ * portal's address. Stamped on EVERY start, the copies already in place included: `--port` moves the
+ * portal, and a copy laid down by an earlier version still carries the old host.
+ */
+export function seedDemoRuns({ workspace, examplesDir, portalOrigin = null }) {
+  const seeded = [], already = [];
+  for (const name of demoChildren(examplesDir)) {
+    const run = join(examplesDir, name, "run");
+    let s;
+    try { s = JSON.parse(readFileSync(join(run, "status.json"), "utf8")); } catch { continue; }
+    if (!s?.slug || !s?.codename || !s?.date) continue;
+    const dir = join(workspace, `workspace-${s.agent || "clawdi"}`, "studio", "prelim-search", s.slug, `${s.date}-${s.codename}`);
+    if (existsSync(join(dir, "status.json"))) already.push(s.runId);
+    else {
+      mkdirSync(dirname(dir), { recursive: true });
+      cpSync(run, dir, { recursive: true });
+      seeded.push(s.runId);
+    }
+    if (portalOrigin) stampReportLinks(join(dir, "status.json"), portalOrigin);
+  }
+  return { seeded, already };
+}
+
+/** The portal route that serves a run's report: the one `scanAccountRuns` hands the portal's own list. */
+export const reportRoute = (runId) => `/portal/report/${encodeURIComponent(runId)}/`;
+
+/**
+ * Point a seeded run's report links at `origin`. A link already on the portal's route keeps its path; any
+ * other (the host an older sample carried) becomes the run's own route. Written only when something moved.
+ */
+export function stampReportLinks(statusFile, origin) {
+  let s;
+  try { s = JSON.parse(readFileSync(statusFile, "utf8")); } catch { return false; }
+  if (!s?.runId) return false;
+  const base = String(origin).replace(/\/+$/, "");
+  const local = (url) => {
+    const path = String(url ?? "").replace(/^https?:\/\/[^/]+/, "");
+    return `${base}${path.startsWith("/portal/report/") ? path : reportRoute(s.runId)}`;
+  };
+  const next = { ...s, url: local(s.url) };
+  if (Array.isArray(s.reports)) next.reports = s.reports.map((r) => (r && typeof r === "object" ? { ...r, url: local(r.url) } : r));
+  const text = `${JSON.stringify(next, null, 2)}\n`;
+  if (text === `${JSON.stringify(s, null, 2)}\n`) return false;
+  writeFileSync(statusFile, text);
+  return true;
+}

package/driver/engine/openai-agent.mjs

@@ -412,6 +412,10 @@ export function readServedModel(codexHome, sinceMs = 0) {
 // that cannot recur. This alternation is still a list of prose a vendor may change without notice,
 // which is exactly why `rateLimitBasis: "text-match"` stays on the record.
 const RATE_LIMIT_RE = /\b429\b|rate.?limit|usage limit|quota|too many requests|insufficient_quota/i;
+// A SIGN-IN THAT CAN NO LONGER BE REFRESHED, in codex's own words (measured on a live install, 2026-09-11).
+// Narrow on purpose: a register provider's 401 or 403 can land in a stage's stderr too, and reading that as
+// the operator's codex login having expired would send them to sign in again for nothing.
+const REFRESH_FAILED_RE = /refresh token (?:has|was) already been used|access token could not be refreshed|failed to refresh token/i;
 
 // A retry hint, WHEN THE MESSAGE HAPPENS TO CARRY ONE. Two anchored shapes and nothing clever: an
 // explicit timestamp, or a relative delay with a unit. Anything else yields undefined and the driver
@@ -484,6 +488,7 @@ function settleTuple({ r, ev, resumeRef }) {
   // backoff (CLEAROTRON_RATE_LIMIT_DEFAULT_BACKOFF_MS), exactly as the anthropic no-reset 429 path does.
   const rateLimitText = `${ev.turnFailed || ""}\n${ev.streamError || ""}\n${r.stderr || ""}`;
   const rateLimited = !killed && RATE_LIMIT_RE.test(rateLimitText);
+  const signedOut = !killed && REFRESH_FAILED_RE.test(rateLimitText);
   const resetsAt = rateLimited ? parseResetHint(rateLimitText) : undefined;
   return {
     code: killed ? 137 : (failed ? (r.rawCode || 1) : 0),
@@ -521,6 +526,9 @@ function settleTuple({ r, ev, resumeRef }) {
       // receives and is not this adapter's call — but nothing downstream can any longer fail to know.
       mcpRefused: mcpToolGauge(ev).mcpToolCallsRefused > 0 || undefined,
       rateLimited: rateLimited || undefined,
+      // The engine's sign-in could not be refreshed: what the operator runs to fix it. The gateway names the
+      // stage's failure with it.
+      signedOut: signedOut ? "codex sign-in expired — run `codex login`, then start the search again" : undefined,
       rateLimitBasis: rateLimited ? "text-match" : undefined,
       // resetsAtBasis (2026-08-20): same honesty as rateLimitBasis one line up, for the reset
       // CLOCK rather than the classification. codex states its reset as human prose with NO timezone

package/driver/enqueue-schema.mjs

@@ -456,7 +456,9 @@ export function validateJob(job, { atClaim = false } = {}) {
       if (projectKey) consulted.push(`the project ${JSON.stringify(projectKey)}`);
       // The saved search is a rung above the project. `clarify` means the selector itself is wrong, which
       // the recipeKey/product checks further down report properly — here it just means no scope to read.
-      const resolved = resolveSearchPolicy(job, { profile, recipes: loadRecipes({ force: true, proseGuard: recipeProseGuard }) });
+      // The store is read only for a job that names a saved search, as every other door reads it: one that
+      // cannot be read must not refuse a job that never asked for anything in it.
+      const resolved = resolveSearchPolicy(job, { profile, recipes: job.recipeKey ? loadRecipes({ force: true, proseGuard: recipeProseGuard }) : null });
       if (job.recipeKey) consulted.push(`the saved search ${JSON.stringify(String(job.recipeKey))}`);
       const scope = resolveEffectiveScope(job, profile, resolved?.clarify ? null : resolved);
       inherited = Array.isArray(scope?.classes) ? scope.classes : [];