clearotron 0.3.0-beta.5 → 0.3.0-beta.6

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.

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

@@ -300,6 +300,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.
  *
@@ -1370,8 +1386,12 @@ 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.
+    const runs = seedDemoRuns({ workspace: paths.workspace, examplesDir: join(REPO, "demo") });
+    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.
@@ -1879,6 +1899,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 +2133,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 +2231,9 @@ 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.
+  const connect = stdioConnectOffer({ workDir: paths.workspace, reportsDir: paths.pool });
   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": "d96db92fd1989500c9b107df8e7f7a8b7f715500",
+  "version": "0.3.0-beta.6"
 }

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

@@ -291,6 +291,7 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | `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,22 @@
 # clearotron-driver
 
+## 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 } 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,31 @@ 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 left alone, so a visitor's second start changes nothing.
+ */
+export function seedDemoRuns({ workspace, examplesDir }) {
+  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); continue; }
+    mkdirSync(dirname(dir), { recursive: true });
+    cpSync(run, dir, { recursive: true });
+    seeded.push(s.runId);
+  }
+  return { seeded, already };
+}

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 : [];

package/driver/gateway.mjs

@@ -1511,6 +1511,12 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
     // Guarded on `fail`: a turn whose finished, validated artifact was just accepted (the exit-1 rescue above)
     // stays accepted — the NEXT stage's first turn hits the same cap at 0 tokens spent and postpones cleanly.
     if (turn.signals?.rateLimited && fail) fail = "rate_limited";
+    // AN ENGINE WHOSE SIGN-IN EXPIRED IS NAMED, not left as `nonzero_exit_1`. codex fails its refresh in
+    // seconds with a bare exit code while `codex login status` still reports the user signed in, so the
+    // one thing that fixes it has to be in the failure itself. AFTER the rate limit, which wins when both
+    // appear: a postponed run resumes on its own, and a signed-out one cannot. The sentence rides after
+    // the colon, as `model_mismatch:` carries its detail, so no run-level classifier needs a new token.
+    else if (turn.signals?.signedOut && fail) fail = `engine_signed_out: ${turn.signals.signedOut}`;
     // A6 (addendum 2026-07-30): stop_reason max_tokens with ZERO usable output is a DETECTED FAULT with a
     // name — never a silent paid retry. The turn ran to its output-token ceiling and the artifact never
     // landed (a content fail on a "successful" turn), or the turn itself died at the ceiling (transport
@@ -2002,6 +2008,12 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
       note(`[${name}] model mismatch is deterministic — breaking the ladder (a retry re-buys the same wrong model)`);
       break;
     }
+    // A sign-in that could not be refreshed refuses every attempt the same way: the next one sends the
+    // same credential and gets the same 401, seconds apart. Break, and let the stage fail with it named.
+    if (fail.startsWith("engine_signed_out:")) {
+      note(`[${name}] the engine's sign-in could not be refreshed — breaking the ladder (a retry re-sends the same credential)`);
+      break;
+    }
     // D3: overload (529 / status_overloaded) — stop the ladder here: an in-ladder re-attempt hammers an
     // API that just said it is overloaded, seconds apart, on the SAME model. Breaking hands the failure
     // to the existing machinery: the chain cascades models (FALLBACK_ELIGIBLE) and an exhausted chain

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.5",
+  "version": "0.3.0-beta.6",
   "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-local-auth.mjs

@@ -45,7 +45,7 @@
 // need the prefix — one side of a pair is enough to separate the pair.
 import { randomBytes, scryptSync, timingSafeEqual, createHmac } from "node:crypto";
 import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative, isAbsolute, sep } from "node:path";
 import { homedir } from "node:os";
 import { envPrefix } from "../shared/os-advice.mjs";
 
@@ -187,6 +187,30 @@ export function passphraseResetCommand({ prefix = "", credentialPath = null, env
   return `${prefix.slice(0, at)}${envPrefix("PORTAL_LOCAL_CREDENTIAL", path)}${prefix.slice(at)}clearotron passphrase --reset`;
 }
 
+/**
+ * The recovery line the SIGN-IN PAGE shows: one that resets the credential this portal reads, and that
+ * names no path on this machine.
+ *
+ * The page is read by somebody who is not signed in, so `passphraseResetCommand`'s line, with its
+ * `cd <install> && ` and its absolute `--base`, would show the server's home directory and account to
+ * anyone who loads it. So the install is named from `$HOME`, which POSIX shells and PowerShell both
+ * expand, and a demo run from npx's cache is reached as `npx clearotron@<version>`, which runs from any
+ * directory. The bare `clearotron passphrase --reset` this replaced reset the shared default, not a
+ * demo's own credential, and did not run at all where `clearotron` is not on the PATH (measured
+ * 2026-09-11 on a published beta).
+ */
+export function signInResetCommand({ credentialPath = null, home = null, npxVersion = null } = {}) {
+  const verb = `${npxVersion ? `npx clearotron@${npxVersion}` : "clearotron"} passphrase --reset`;
+  if (!credentialPath || basename(credentialPath) !== INSTALL_CREDENTIAL_FILE) return verb;
+  const h = home ?? homedir();
+  const dir = dirname(credentialPath);
+  if (dir === defaultInstallBase({ home: h })) return verb;
+  const rel = relative(h, dir);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) return `${verb} --base <this install's folder>`;
+  const at = `$HOME/${rel.split(sep).join("/")}`;
+  return `${verb} --base ${/\s/.test(at) ? `"${at}"` : at}`;
+}
+
 /**
  * The name an install's own credential has inside the install's directory: the shared default's name,
  * so the two are one kind of file in two places.
@@ -287,7 +311,8 @@ export function establishCredential({ path, email, passphrase = null }) {
   // 18 bytes → 24 base64url characters, no padding and no ambiguous punctuation: readable off a
   // terminal, typeable into a browser, and 144 bits of entropy so a generated one is never the weak
   // half of this design.
-  const secret = generated ? newPassphrase() : String(passphrase);
+  // Trimmed for the reason checkPassphrase trims: surrounding whitespace is never part of a passphrase.
+  const secret = generated ? newPassphrase() : String(passphrase).trim();
   if (!secret) throw new Error("establishCredential: an empty passphrase is not a credential");
   const salt = randomBytes(16).toString("base64url");
   const rec = {
@@ -319,7 +344,14 @@ export function establishCredential({ path, email, passphrase = null }) {
  */
 export function checkPassphrase(record, passphrase) {
   if (!record || typeof record.salt !== "string" || typeof record.hash !== "string") return false;
-  if (typeof passphrase !== "string" || !passphrase) return false;
+  if (typeof passphrase !== "string") return false;
+  // SURROUNDING WHITESPACE IS NOT PART OF A PASSPHRASE. A value copied from a terminal or a chat carries a
+  // trailing space or line break, and the digest of `pass ` is not the digest of `pass`, so a correct
+  // passphrase was refused as wrong (measured 2026-09-11 on a published beta). Every passphrase is minted
+  // trimmed (establishCredential, below), and a generated one has no whitespace at all, so trimming here
+  // refuses nothing that matched before. Whitespace INSIDE a passphrase is kept.
+  passphrase = passphrase.trim();
+  if (!passphrase) return false;
   if (record.algo !== ALGO) return false;
   let got;
   try { got = derive(passphrase, record.salt); } catch { return false; }