clearotron 0.3.0-beta.4 → 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
@@ -749,9 +758,13 @@ Use the demo to see what this system produces. Use `npx clearotron start` to run
 
 - Generates `PORTAL_SECRET` and `TRADEMARK_MCP_TOKEN_SECRET` and **appends** them to `~/.config/clearotron/.env` at
   mode 600. Append, never rewrite: that file also holds the credentials `npx clearotron install` collected.
+  It also records where saved searches are kept, `CLEAROTRON_RECIPES_DIR` and `RECIPE_REPO_ROOT`, so
+  `clearotron doctor` and a connected assistant read the same saved searches as the portal.
 - 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
@@ -99,7 +101,15 @@ import { entrypointOf } from "../driver/systemd/install-census.mjs";         //
 import { overlayReport, renderOverlayReport } from "../shared/doctrine-overlay.mjs";   // — the doctor reports the overlay
 import { whereSavesGo, storeCommitRefusal, storeInRepo, storeOutsideRepoMessage, resolveStoreRepoRoot } from "../shared/store-in-repo.mjs";   // — doctor says where a portal save goes once it is committed, and why saved searches are off
 import { engineInventory, engineMode, ENGINE_MODES } from "../driver/config-inventory.mjs";   //
-import { probeEngineTurn, probeFailureText, PROBE_MODEL, PROBE_TIMEOUT_SEC, engineEnvKeys } from "../driver/engine/probe.mjs";
+import { probeEngineTurn, probeFailureText, PROBE_TIMEOUT_SEC, engineEnvKeys } from "../driver/engine/probe.mjs";
+
+// THE PROVING SENTENCES NAME NO MODEL. They printed the driver's tier word, which is an Anthropic model's
+// name, on both engines, so a codex user was told setup was about to spend on a model family they do not
+// use. "Its cheapest model" is true of either engine and brands neither.
+export const probingLine = (engineId) =>
+  `Probing ${engineId} with one turn on its cheapest model (this SPENDS; ${PROBE_TIMEOUT_SEC}s ceiling)…`;
+export const proveQuestion = ({ engineId, lane }) =>
+  `Prove ${engineId} on the ${lane} lane now with one turn on its cheapest model (a few tokens, ${PROBE_TIMEOUT_SEC}s ceiling)?`;
 import { runRequiredNames, missingRequirements, REGISTER_ENV, ENGINE_ENV } from "../driver/run-requirements.mjs";   // the order-time gate's own question, asked here rather than restated
 import { pinEnv, envFrom } from "../shared/env-aliases.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
@@ -695,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
@@ -1206,7 +1201,7 @@ export async function runCheck() {
   // deliberate — a second reader would drift from this one exactly as the composer and the checker did
   // in F41, and the drift is invisible because both sides keep passing their own arms.
   const unitDir = join(homedir(), ".config", "systemd", "user");
-  const { BACKGROUND_UNITS } = await import(pathToFileURL(join(REPO, "bin", "start.mjs")).href);
+  const { BACKGROUND_UNITS, startPaths } = await import(pathToFileURL(join(REPO, "bin", "start.mjs")).href);
   const hosted = BACKGROUND_UNITS.some((u) => existsSync(join(unitDir, u)));
   const unitEnv = hosted
     ? unitEnvironment({
@@ -1440,7 +1435,7 @@ export async function runCheck() {
     } else if (!bin.executable || bin.relative) {
       info("not probed — there is no usable binary to probe. Fix the line above first.");
     } else {
-      say(`\n  Probing ${engineId} with one ${PROBE_MODEL}-tier turn (this SPENDS; ${PROBE_TIMEOUT_SEC}s ceiling)…`);
+      say(`\n  ${probingLine(engineId)}`);
       // The engine as a RUN would see it: environment first, .env behind it. Only the engine-selection
       // keys — the probe must bill exactly the way this box bills and moves no other variable.
       const probeEnv = { ...process.env };
@@ -1628,6 +1623,13 @@ export async function runCheck() {
         // because a reader debugging `clearotron run` by hand IS this process.
         info(`this command's own process ${where} — a CLI is not started by the units' EnvironmentFile, so `
           + "that differs by design and is not what a run uses");
+      } else if (!hosted && svcCustomers?.from === serviceEnvLabel) {
+        // NAMED IN THE ENV FILE ALONE, ON AN INSTALL WITH NO UNITS. `clearotron start` loads that file and
+        // its services inherit the store; this command does not load it, so its own process fell back to
+        // the bundled roster and printed that as the answer, one line below a ✓ for the same variable.
+        ok(`the services resolve profiles from ${svcCustomers.v} (${svcCustomers.from})`);
+        info(`this command's own process ${where} — it does not load ${serviceEnvFile}, so that differs by `
+          + `design and is not what \`${invoke("start")}\` hands the services`);
       } else {
         if (r.situation === "overlay" && !r.findings.length) ok(`${where} — the configured store`);
         else if (r.situation === "bundled-fallback") info(`${where} — THE BUNDLED DEMO ROSTER, because CLEAROTRON_CUSTOMERS_DIR is unset. Legitimate on a generic-defaults install; a fallback either way, and it is what a misconfigured deployment also looks like`);
@@ -1638,7 +1640,8 @@ export async function runCheck() {
         info(`the units are installed but their environment could not be read (${unitEnv?.why ?? "no reason given"}) — `
           + "what the services resolve is not judged here, and the line above is this process's own answer");
       info("what a RUN used is its own `profile-store` journal line — this command reports what the "
-        + (hosted ? "units' file says, which the running services read at their own start" : "environment you are typing in says"));
+        + (hosted ? "units' file says, which the running services read at their own start"
+          : `environment you are typing in and your environment file say, which \`${invoke("start")}\` reads at its own start`));
       // ── AND WHO IS ACTUALLY IN IT ─────────────────────────────────────────
       //
       // The line above names the STORE. An operator who has just configured one wants to know their
@@ -1807,16 +1810,32 @@ export async function runCheck() {
   // be read, the lines above already said so and nothing is judged here. A store that is configured but
   // holds a file that cannot be read fails every company's saved searches, in the portal and the
   // connector alike, so that is read here too.
+  //
+  // WITH NO UNITS, THE SERVICES ARE `clearotron start`'s CHILDREN, and it hands every one of them a store
+  // whether or not the env file names it. So "off" is only ever true of a hosted box. This read the env
+  // file alone, and on a local install started before `start` wrote the store there, it told a portal
+  // that was listing saved searches that they were off.
   if (!hosted || serviceKnown) {
-    const recipesSet = hosted ? effectiveForService("CLEAROTRON_RECIPES_DIR") : effective("CLEAROTRON_RECIPES_DIR");
+    // Layered as effectiveForService layers it — this command's environment over the services' file — so
+    // the repository root is read from the same place the store directory is.
+    let storeEnv = { ...(serviceFileEnv ?? {}), ...process.env };
+    let recipesSet = effectiveForService("CLEAROTRON_RECIPES_DIR");
+    let handedBy = "";
+    if (!hosted && !recipesSet?.v) {
+      const handed = startPaths({ env: storeEnv });
+      recipesSet = { v: handed.recipes, from: "clearotron start", name: "CLEAROTRON_RECIPES_DIR" };
+      storeEnv = { ...storeEnv, RECIPE_REPO_ROOT: handed.configStore };
+      handedBy = ` — where \`${invoke("start")}\` puts them`;
+    }
     const recipesDir = recipesSet?.v || null;
     if (!recipesDir) {
       info("saved searches are off: CLEAROTRON_RECIPES_DIR is not set, so Custom searches in the portal and the "
         + "connector offer none. Name a directory inside a git repository to switch them on");
+    } else if (handedBy && !existsSync(join(storeEnv.RECIPE_REPO_ROOT, ".git"))) {
+      // NOT CREATED YET IS NOT UNREADABLE. The store does not exist until the first start makes it, and
+      // reading it now would report a missing directory as a broken one.
+      info(`saved searches switch on at the first \`${invoke("start")}\`, which creates their store in ${recipesDir}`);
     } else {
-      // Layered as effectiveForService layers it — this command's environment over the services' file — so
-      // the repository root is read from the same place the store directory above was.
-      const storeEnv = { ...(serviceFileEnv ?? {}), ...process.env };
       const resolved = resolveStoreRepoRoot({ names: ["RECIPE_REPO_ROOT", "PROFILE_REPO_ROOT"], fallback: REPO, env: storeEnv });
       const reach = storeInRepo(recipesDir, resolved.root);
       if (!reach.ok) {
@@ -1828,8 +1847,8 @@ 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");
-        } else ok(`saved searches are read from ${recipesDir}, and saves are committed in ${reach.repo}`);
+            + "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}`);
       }
     }
   }
@@ -2901,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.
@@ -3281,7 +3333,7 @@ try {
     // skipping it costs an hour later.
     info("A file that exists is not an engine that works — so setup tries one before writing anything.");
     info("It takes a few seconds here. Skipped, a broken engine surfaces an hour into a real search.");
-    if (!await confirm(`Prove ${pick.id} on the ${authPick.id} lane now with one ${PROBE_MODEL}-tier turn (a few tokens, ${PROBE_TIMEOUT_SEC}s ceiling)?`, true)) {
+    if (!await confirm(proveQuestion({ engineId: pick.id, lane: authPick.id }), true)) {
       info("Not proven, so not written. Pick again — the last row configures no engine at all.");
       continue;
     }

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.
  *
@@ -355,6 +371,50 @@ export function defaultGrantsPath({ env = process.env, demo = false } = {}) {
   return installPaths(join(homedir(), demo ? "trademark-demo" : "trademark")).grants;
 }
 
+/**
+ * The paths `clearotron start` hands its services: the install's layout under `base`, with whatever the
+ * environment already names winning over the layout's default, as `start` has always applied it.
+ *
+ * EXPORTED FOR THE ONE OTHER READER THAT MUST AGREE WITH IT. On an install with no background units,
+ * `clearotron doctor` has no unit file to read the services' environment from: the services are this
+ * command's children and get the saved-search store from here. An install started before the store was
+ * written to the env file has no line there to read, so doctor asks this function for it, and the
+ * answer it prints and the one the services were given have one author.
+ *
+ * NOT IN A DEMO. Nothing the environment says about an install is the demo's: with the reader's settings
+ * in force, 0.3.0-beta.1's demo seeded its example reports into their real archive.
+ */
+export function startPaths({ env = process.env, base = join(homedir(), "trademark"), demo = false } = {}) {
+  const paths = installPaths(base);
+  if (demo) return paths;
+  for (const [k, name] of [["pool", "CLEAROTRON_REPORTS_DIR"], ["workspace", "CLEAROTRON_WORK_DIR"], ["queue", "CLEAROTRON_QUEUE_DIR"],
+    ["outbox", "CLEAROTRON_OUTBOX_DIR"], ["locks", "CLEAROTRON_RUN_LOCK_DIR"], ["grants", "CLEAROTRON_ACCESS_FILE"],
+    ["recipes", "CLEAROTRON_RECIPES_DIR"]]) if (env[name]) paths[k] = env[name];
+  if (env.RECIPE_REPO_ROOT) paths.configStore = env.RECIPE_REPO_ROOT;
+  if (env.PORTAL_AUDIT) paths.audit = env.PORTAL_AUDIT;
+  return paths;
+}
+
+/**
+ * The saved-search store, as the env file must record it for every reader OUTSIDE this command's tree.
+ *
+ * The services are handed the store by `childEnv`. A connector an assistant launches, `clearotron doctor`
+ * and every other hand-run command are not this command's children: they read the env file, and the
+ * file never named the store. So on a local install the portal listed a company's saved searches, the
+ * connected assistant was told there were none, and doctor said saved searches were off. Written
+ * add-only beside the secrets, as `npx clearotron install` writes the reports and work directories: a
+ * line an operator wrote wins.
+ */
+export function storesForOtherReaders(paths) {
+  return { CLEAROTRON_RECIPES_DIR: paths.recipes, RECIPE_REPO_ROOT: paths.configStore };
+}
+
+// Written above each line, so a reader who moves the install sees that these two move with it.
+const STORE_NOTES = {
+  CLEAROTRON_RECIPES_DIR: "Where saved searches are kept. `clearotron start` created it; edit both lines if you move the install.",
+  RECIPE_REPO_ROOT: "The git repository saved searches are committed in, which holds the directory above.",
+};
+
 /** Everything this install keeps on disk, under one base directory. */
 export function installPaths(base) {
   return {
@@ -846,20 +906,11 @@ if (isMain) {
   const DEMO = argv.includes("--demo");
   // The same base `npm run setup` writes under, so whichever of the two a reader ran first, the other
   // finds the same install rather than a second one beside it.
-  const paths = installPaths(flag("--base", join(homedir(), DEMO ? "trademark-demo" : "trademark")));
   // Whatever the environment already says wins over the base-derived default, for every path — a reader
-  // who ran `npm run setup` has these in .env already and this must not move their data.
-  //
-  // NOT IN A DEMO. Nothing the environment says about an install is the demo's: with the reader's
-  // settings in force, 0.3.0-beta.1's demo seeded its example reports into their real archive. Not read,
-  // rather than deleted from the environment, so a real start cannot be reached by this branch at all.
-  if (!DEMO) {
-    for (const [k, name] of [["pool", "CLEAROTRON_REPORTS_DIR"], ["workspace", "CLEAROTRON_WORK_DIR"], ["queue", "CLEAROTRON_QUEUE_DIR"],
-      ["outbox", "CLEAROTRON_OUTBOX_DIR"], ["locks", "CLEAROTRON_RUN_LOCK_DIR"], ["grants", "CLEAROTRON_ACCESS_FILE"],
-      ["recipes", "CLEAROTRON_RECIPES_DIR"]]) if (process.env[name]) paths[k] = process.env[name];
-    if (process.env.RECIPE_REPO_ROOT) paths.configStore = process.env.RECIPE_REPO_ROOT;
-    if (process.env.PORTAL_AUDIT) paths.audit = process.env.PORTAL_AUDIT;
-  }
+  // who ran `npm run setup` has these in .env already and this must not move their data. Not in a demo,
+  // which `startPaths` says why. One author, because `doctor` asks the same function what the services
+  // were handed.
+  const paths = startPaths({ env: process.env, base: flag("--base", join(homedir(), DEMO ? "trademark-demo" : "trademark")), demo: DEMO });
   // ── THIS INSTALL'S FIRST START, read before this start writes either file that answers it ────────────
   //
   // The grants file and the config store's repository are both written further down, on every start
@@ -1117,14 +1168,19 @@ if (isMain) {
   const portalSecret = secretFor("PORTAL_SECRET");
   const tokenSecret = secretFor("TRADEMARK_MCP_TOKEN_SECRET");
   if (!process.env.PORTAL_LOCAL_USER) generated.PORTAL_LOCAL_USER = user;
+  const stores = DEMO ? {} : storesForOtherReaders(paths);
 
   // A DEMO WRITES NO SECRETS AND NO ADDRESS. They are generated per run and live in memory only, which
   // is the same posture the ops key already has here — and it is what makes "removing the demo is one
   // directory" true rather than nearly true.
-  if (Object.keys(generated).length && !DEMO) {
+  //
+  // THE STORES ARE WRITTEN EVEN WHEN NO SECRET IS. An install whose secrets are already in the file is
+  // exactly the install whose connector and doctor could not see its saved searches, and a gate on the
+  // secrets alone would never reach it.
+  if ((Object.keys(generated).length || Object.keys(stores).length) && !DEMO) {
     let existing = "";
     try { existing = readFileSync(ENV_PATH, "utf8"); } catch (e) { if (e.code !== "ENOENT") fatal(`${ENV_PATH} exists but could not be read (${e.code}).`); }
-    const merged = mergeEnvFile(existing, generated);
+    const merged = mergeEnvFile(existing, { ...generated, ...stores }, { notes: STORE_NOTES });
     if (merged.added.length) {
       // ONE WRITER FOR EVERY FILE THAT HOLDS CREDENTIALS, and it creates the directory. This site had its
       // own copy of the write and did not learn what the wizard's copy learned when `.env` moved under
@@ -1135,7 +1191,7 @@ if (isMain) {
       } catch (e) {
         fatal(`could not write ${ENV_PATH} (${String(e?.message ?? e)}).`);
       }
-      // NAMES only. This file is where the credentials are.
+      // NAMES only. Some of what this file holds is credentials.
       say(`  wrote          ${merged.added.join(", ")} to ${ENV_PATH} (mode 600)`);
     }
   }
@@ -1330,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.
@@ -1839,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")}`);
@@ -2072,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) ─────────────────────────
   //
@@ -2169,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": "0fb023f5822c9458f9c63bf993876c3a3a8053e3",
-  "version": "0.3.0-beta.4"
+  "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,31 @@
 # 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
+
+- 5f7e295: Fixed: A Clearotron install signed in to OpenAI's `codex` with a subscription keeps working after codex refreshes its login. Before, every search after the first refresh failed within seconds until you signed in again.
+- 2878809: Fixed: When the company store cannot record a new company, the New company page now says why and what fixes it, instead of "Try again shortly". Someone who does not run the installation is told to ask whoever does.
+- e7cd9e1: Fixed: On an install run with `clearotron start`, a connected assistant now lists the same saved searches as the portal, including Generic's. `clearotron doctor` no longer says working saved searches are off, and it names one place profiles come from.
+- e7cd9e1: Fixed: When setup offers to try your engine, it no longer names an Anthropic model to someone who chose OpenAI's `codex`.
+
 ## 0.3.0-beta.4
 
 ### Minor Changes
@@ -23,9 +49,9 @@
 - a782aad: Fixed: Creating a company is refused, with nothing left behind, when the configuration store cannot record it. The company used to be created anyway, with no record of who made it or when, and its organisation was given access to it.
   
   A store with no git identity is the usual cause on a new machine, and the refusal names the command that fixes it. Setup and `clearotron start` now check a store they adopt for this straight away.
-- d1ef225: Fixed: A stage stopped at its time limit now records the output it actually produced. It used to record a small fraction, so a stage that was working read as one that had stalled.
+- d1ef225: Fixed: A search step stopped at its time limit now records the output it actually produced. It used to record a small fraction, so a step that was working read as one that had stalled.
   
-  The token totals `clearotron tokens` reports for runs with a stopped stage now include that output.
+  The token totals `clearotron tokens` reports for runs with a stopped step now include that output.
 - 0ff42d1: Fixed: `clearotron doctor` now says when saved searches are switched off and why, and when a saved search file cannot be read.
   
   An assistant asking for saved searches is told when they could not be read, instead of being told there are none.
@@ -79,11 +105,11 @@
   
   Fixed: A search now records any of your default territories that the engine cannot search, in the record of that search. A mistyped default no longer narrows a search silently.
 - eacfce4: Fixed: An assistant connected to a local install now sees the saved searches the portal shows, and can plan a run from one of them. Before, outside the demo, only the portal was told where saved searches are kept, so an assistant was told the install had none.
-- 34cc1c7: For operators: A health check that could not look now fails instead of reporting success. Two halves of the unit check can go quiet. One goes quiet when the installation does not say which installation it is; the other when the walk over the unit files does not finish. Both used to note that they had not run and then pass.
+- 34cc1c7: For operators: A deployment health check that could not finish now fails instead of reporting success. Two parts of the service check could skip themselves. One skipped when the installation did not say which installation it is; the other when the scan of the service files did not finish. Both used to note that they had not run and then pass.
   
   For operators: Set `CLEAROTRON_BOX` to `prod` or `test`. Those are the only two values the check accepts; anything else, including any other name, reads as unnamed and fails. The failure names the setting and says what went unchecked.
   
-  For operators: The half that goes quiet is the one that notices a service that has stopped and stayed stopped. The other half lists what is running, so it cannot see something that is no longer there. While that half is suppressed, a service can disappear without the check saying anything.
+  For operators: The part that could skip itself is the one that notices a service that has stopped and stayed stopped. The other part lists what is running, so it cannot see something that is no longer there. While the first part is skipped, a service can disappear without the check saying anything.
 - b45a5cf: Fixed: `clearotron doctor` now reports everything a search would be refused for, checked against the environment the search will run in. So an installation it passes is one that can run a search.
   
   Fixed: A token set in the installation's own configuration file now reaches the engine check. A headless server set up the documented way proves its engine instead of reporting it signed out.
@@ -128,7 +154,7 @@
   Fixed: When a feature is switched off on your installation, the screen says so and what to change. It used to suggest trying again shortly.
   
   Fixed: The link to the risk-framework guide opens in a new tab and goes straight to the section on writing your own. It also appears on the Company profile screen.
-- ad088d6: Fixed: The audit workbook's "What was searched" sheet is now in plain words. Its Result and Note columns carry the search log's own notes. Engine vocabulary could reach them: a receipt "deferred", a full web address, a bare HTTP code. Those words are now replaced as the workbook is built, a republished report included. A search recorded as not run still reads as not searched. Search terms and names stay exactly as written, because they record what was searched.
+- ad088d6: Fixed: The audit workbook's "What was searched" sheet is now in plain words. Its Result and Note columns carry the search log's own notes. Internal terms could reach them: a status such as "deferred", a full web address, a bare HTTP code. Those words are now replaced as the workbook is built, a republished report included. A search recorded as not run still reads as not searched. Search terms and names stay exactly as written, because they record what was searched.
 - ff16a3b: For operators: The deployment health check now reports whether the component that updates an installation is itself up to date. It was the one part of a deployment the check could not identify. An installation kept current by an out-of-date updater could report healthy while serving stale code.
   
   For operators: An updater that cannot be identified is now reported as a failure rather than passed over. A copy old enough to predate this reporting writes nothing at all. That silence is the case worth knowing about, so it is treated as a finding.
@@ -158,7 +184,7 @@
   
   The product now says company throughout. It used to say brand owner, account, client and customer for the same thing. The firm running the installation is named separately, in the top bar.
   
-  Companies created through the settings page were saved without a risk framework. Their matters were then rated under the house default, with nothing on screen saying so. Every company created now carries one, and says which.
+  Companies created through the settings page were saved without a risk framework. Their matters were then rated under the default risk framework, with nothing on screen saying so. Every company created now carries one, and says which.
 - f75266d: New: The setup wizard now asks for the organisation's name after the sign-in address, and the person who installs starts with access to everything.
   
   `clearotron grant add` sets a person's two permissions with `--run` and `--manage`; with neither, the person can look and start nothing.
@@ -180,18 +206,18 @@
   
   Getting the deck's shape wrong used to fail quietly. The profile screen showed the framework's title and your band colours, and silently omitted the box saying what the bands mean. The new command answers that question directly, using the screen's own read of the deck.
   
-  Fixed: a framework served from the product's own files, while you have a configuration store set, now says so.
+  Fixed: When you have a configuration store set and a risk framework comes from the product's own files instead, the product now says so.
   
   Your store is looked in first, and the product's files answer when it is silent. The product ships decks under names you may also have chosen. So a deck that went missing from your store was replaced by ours rather than reported absent. Same band words, different rubric, nothing raised anywhere. The profile screen now writes one line naming what happened, and the new command reports it.
   
-  Fixed: the house triage ladder's profile page explains its bands again.
+  Fixed: The built-in triage framework's profile page explains its bands again.
   
   Its band sections stated their meanings as plain paragraphs, which the screen does not read. Every company without a framework of its own saw band colours and no explanation. The wording is unchanged.
-- cfb9a9f: Fixed: `clearotron doctor` now says which companies your portal's trigger key can start.
+- cfb9a9f: Fixed: `clearotron doctor` now lists the companies your portal's key may start runs for.
   
   The key carries a list of the companies it may start runs for. A company added after the key was minted is outside it. Doctor reported the key's expiry and never its coverage. So the one command whose job is to tell you what a machine is configured for said nothing about it.
   
-  It reads the roster the services read, not the one a command-line process resolves, and it says which. Those two can disagree, and when they do the difference is the whole answer.
+  It reads the company list the background services read, not the one a command run in a terminal would find, and it says which. The two can differ, and when they do, that difference is the answer.
   
   The line is a note, not a failure. Your portal takes a fresh credential at the start of every call, so a company outside the key is not normally refused. It is refused when the portal cannot take a fresh one, and the line says so and gives you the command to widen the key.
 - ba2899b: Fixed: On reports searched through Signa, each register finding now links to the office's own page for that record, where the office publishes one. Singapore publishes no such page, so its registrations are cited by number, and the report says why. A number that an office's page cannot take is cited the same way.