clearotron 0.3.0-beta.4 → 0.3.0-beta.6

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

@@ -22,7 +22,8 @@
 // CLEAROTRON_CODEX_SANDBOX_BYPASS=1 swaps that `--sandbox workspace-write` for
 // `--dangerously-bypass-approvals-and-sandbox` — see buildCodexArgs below for why.
 
-import { mkdtempSync, writeFileSync, copyFileSync, existsSync, rmSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { mkdtempSync, writeFileSync, copyFileSync, existsSync, rmSync, readFileSync, readdirSync, statSync, symlinkSync, lstatSync, realpathSync } from "node:fs";
+import { writeSecretFile } from "../../shared/secret-file.mjs";   // the rotated login goes back the way every credential is written
 import { tmpdir, homedir } from "node:os";
 import { join } from "node:path";
 import { runStreamingChild, absolutizeSkillRefs, WRITE_DISCIPLINE, buildEnvelope, resolveSpawnCwd } from "./common.mjs";
@@ -174,6 +175,49 @@ export function spawnEnv(base = process.env, codexHome) {
 
 const authFilePath = (env = process.env) => env.CLEAROTRON_OPENAI_AUTH_FILE || join(homedir(), ".codex", "auth.json");
 
+// ── THE LOGIN IS THE MASTER'S, NOT A COPY'S ─────────────────────────────────────────────────────────
+//
+// codex refreshes its access token inside a turn and rotates the refresh token as it does, and the
+// provider accepts each refresh token once. The stage home used to be seeded with a COPY of the master
+// login and deleted when its ladder settled, so the rotated token was deleted with it. The master kept a
+// token the provider had already consumed, and every later stage on every run failed its refresh with a
+// 401 until a person signed in again. The engine's only report was an exit code.
+//
+// So the stage home LINKS to the master: a refresh codex writes in place lands where the next stage
+// reads, including a ladder running beside this one. If codex replaces the link with a file of its own,
+// `returnAuth` writes that file back.
+
+/** Point `<codexHome>/auth.json` at the master login. Returns what the master held, for `returnAuth`. */
+function seedAuth(masterPath, codexHome) {
+  const seat = join(codexHome, "auth.json");
+  // A LINK LEFT BY THIS LADDER'S PREVIOUS TURN is removed first: copying the master onto a link to
+  // itself would truncate the one file the login lives in.
+  rmSync(seat, { force: true });
+  symlinkSync(masterPath, seat);
+  return readFileSync(masterPath, "utf8");
+}
+
+/**
+ * After a turn: a login codex rewrote as its own file goes back to the master.
+ *
+ * ONLY WHILE THE MASTER STILL HOLDS WHAT THIS TURN WAS SEEDED WITH. A master that moved meanwhile was
+ * rotated by another ladder, and the provider accepts one refresh per token, so of two rotations from
+ * one seed only one can be live. Writing ours over theirs could put back the spent one.
+ */
+export function returnAuth(masterPath, codexHome, seeded) {   // @internal
+  const seat = join(codexHome, "auth.json");
+  let st;
+  try { st = lstatSync(seat); } catch { return false; }
+  if (st.isSymbolicLink() || !st.isFile()) return false;   // written through the link, or not there
+  const now = readFileSync(seat, "utf8");
+  if (now === seeded) return false;
+  let master;
+  try { master = readFileSync(masterPath, "utf8"); } catch { return false; }
+  if (master !== seeded) return false;
+  writeSecretFile(masterPath, now);
+  return true;
+}
+
 // Build the codex argv. Prompt rides STDIN via the `-` placeholder (no MAX_ARG_STRLEN ceiling on a 150KB
 // register prompt). Global flags precede the `resume` subcommand (flag-corpus ordering). config.toml
 // (mcp_servers + developer_instructions) rides CODEX_HOME, not argv.
@@ -368,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
@@ -440,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),
@@ -477,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
@@ -530,6 +582,7 @@ export const openaiAgentEngine = {
     const ownHome = !providedHome;
     try { codexHome = providedHome ?? mkdtempSync(join(tmpdir(), "codex-home-")); }
     catch (e) { return errResult(t0, e, resumeRef); }
+    let authMaster = null, seeded = null;
     try {
       // Auth toggle (may throw loud on api-key-without-key — a config error, not a retryable failure).
       const { env, mode } = spawnEnv(process.env, codexHome);
@@ -537,7 +590,9 @@ export const openaiAgentEngine = {
         const af = authFilePath(process.env);
         if (!existsSync(af))
           throw new Error(`CLEAROTRON_AI_BILLING=subscription but no auth.json at ${af} — run \`codex login\` (or set CLEAROTRON_OPENAI_AUTH_FILE — NOT an aliased name, and deliberately left as it is), or use CLEAROTRON_AI_BILLING=api-key + CODEX_API_KEY.`);
-        copyFileSync(af, join(codexHome, "auth.json"));
+        // The REAL path, so a master that is itself a link is written where its login actually lives.
+        authMaster = realpathSync(af);
+        seeded = seedAuth(authMaster, codexHome);
       }
       // Per-run config.toml: the gather MCP servers (translated from the claude-shaped mcpConfig, so
       // gather-config.mjs is untouched) + developer_instructions = WRITE_DISCIPLINE (codex's
@@ -574,6 +629,9 @@ export const openaiAgentEngine = {
       if (!ev.model) ev.model = readServedModel(codexHome, spawnedAtMs);
       return settleTuple({ r, ev, resumeRef });
     } finally {
+      // BEFORE the home can be deleted, here or by the ladder that owns it. A failed write-back leaves the
+      // turn's result as it was; the next turn is seeded from the master either way.
+      try { if (authMaster) returnAuth(authMaster, codexHome, seeded); } catch { /* the master is unchanged */ }
       try { if (ownHome && codexHome) rmSync(codexHome, { recursive: true, force: true }); } catch { /* best-effort cleanup */ }
     }
   },

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.4",
+  "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; }

package/driver/portal-service.mjs

@@ -40,6 +40,8 @@ import { customerStoreDir, customerStoreLine } from "../shared/customer-store.mj
 import { clientFailureNote } from "../shared/client-failure-note.mjs";   // — one sentence, three surfaces
 import { bareInvocation, invocationPrefix, installRoute } from "../shared/invocation.mjs";   // — and why this one surface is by NAME
 import { stdioConnectOffer, stdioConnectFor, STDIO_SHAPES } from "../shared/stdio-connect.mjs";   // — ONE author for the connect route
+import { isWsl } from "../shared/wsl.mjs";   // — on WSL, the connect lines say where they run
+import { inNpxCache, ownVersion } from "../shared/permanent-install.mjs";   // — a demo from npx is reset through npx
 import { connectOffers, offersForWire } from "../shared/connect-clients.mjs";                 // — ONE table, resolved server-side
 
 /**
@@ -112,7 +114,7 @@ import { makePrincipal, assertPrincipal, genericOrgOf, mayReadRun, reachCovers,
 // makePrincipal and assertPrincipal exactly as a Cloudflare-verified address does.
 import { readLocalCredential, establishCredential, checkPassphrase, mintSession, verifySession,
   makeAttemptLimiter, credentialPathFor,
-  localCredentialHandoff, firstRunCredentialLines, passphraseResetCommand } from "./portal-local-auth.mjs";   
+  localCredentialHandoff, firstRunCredentialLines, passphraseResetCommand, signInResetCommand } from "./portal-local-auth.mjs";   
 import { appendFlag, feedbackDir, MAX_WHY, VERDICTS } from "./feedback-store.mjs";
 import { loadRecipes, PRODUCT_POLICIES, policyFor, countJobMarks, kebabCollisions,
   gateResolvedPolicy, productAvailability, UNAVAILABLE_NOTE, coverageDisclosure, reportIdentityFor } from "./search-policy.mjs";
@@ -1197,8 +1199,16 @@ export function makePortalService({
   const usedJtis = new Map();
   const sweepJtis = (now = Date.now()) => { for (const [k, exp] of usedJtis) if (exp < now) usedJtis.delete(k); };
 
-  const searchesFor = (account) => {
-    const recipes = loadRecipesImpl({});
+  const searchesFor = (account, principal) => {
+    // A SAVED-SEARCH STORE THAT CANNOT BE READ COSTS THE SAVED SEARCHES, NOT THE MENU. Every product is
+    // still offered; the list comes back empty with a sentence saying why, and only a person who sees
+    // everything is shown the store's own error, which names a server path.
+    let recipes = new Map(), recipesNote = null;
+    try { recipes = loadRecipesImpl({}); }
+    catch (e) {
+      const cause = seesEverything(principal) ? ` (${String(e?.message ?? e).split("\n")[0].slice(0, 300)})` : "";
+      recipesNote = `Saved searches could not be read on this installation, so none are listed${cause}.`;
+    }
     const built = readBuilt();
     const canCount = readCanCount();
     const territories = readTerritories();
@@ -1264,6 +1274,7 @@ export function makePortalService({
       recipes: [...recipes.entries()]
         .filter(([k, r]) => k.startsWith(`${account}/`) && !r.archived)
         .map(([k, r]) => ({ slug: k.split("/")[1], label: r.label, base: r.base, version: r.version ?? null, nativeLanguage: r.nativeLanguage === true })),
+      recipesNote,
       // ── — THE MARK-NAME BUDGET, SENT RATHER THAN DUPLICATED ──────────────
       //
       // The owner typed a product description into the mark-name field and the product accepted it,
@@ -1547,7 +1558,7 @@ export function makePortalService({
       if (parts[1] === "api" && parts[2] === "searches" && method === "GET") {
         const account = assertPrincipal(principal, { account: query.account ?? null });
         if (!account) return { status: 400, json: { error: "name an account (?account=)" } };
-        return { status: 200, json: { account, ...searchesFor(account) } };
+        return { status: 200, json: { account, ...searchesFor(account, principal) } };
       }
       // /portal/api/compose/read — turn a pasted brief into a filled-in composer.
       //
@@ -2305,7 +2316,7 @@ export function makePortalService({
         // COMPOSED IN ONE PLACE and handed over as a string. The browser cannot know this install's
         // path, so the three surfaces stating this route cannot drift apart even if someone tries.
         const stdio = seesEverything(principal)
-          ? stdioConnectOffer({ workDir: process.env.CLEAROTRON_WORK_DIR || null })
+          ? stdioConnectOffer({ workDir: process.env.CLEAROTRON_WORK_DIR || null, reportsDir: process.env.CLEAROTRON_REPORTS_DIR || null })
           : null;
 
         // ── THE PAGE IS HANDED ANSWERS, NOT FACTS TO REASON FROM ─────────────
@@ -2330,8 +2341,9 @@ export function makePortalService({
         const offers = connectOffers({
           stdioRoutes: stdio
             ? Object.fromEntries(Object.keys(STDIO_SHAPES).map((shape) =>
-                [shape, stdioConnectFor(shape, { workDir: process.env.CLEAROTRON_WORK_DIR || null })]))
+                [shape, stdioConnectFor(shape, { workDir: process.env.CLEAROTRON_WORK_DIR || null, reportsDir: process.env.CLEAROTRON_REPORTS_DIR || null })]))
             : {},
+          wsl: isWsl(),
           // ONE ADDRESS, and it is the publicly reachable one ( §5). The
           // `localAddress` and `clientDoorStanding` inputs are gone with the axis that read them: no
           // surface serves a loopback address to anybody, and the door's running-or-not stopped being
@@ -3364,6 +3376,21 @@ async function readJsonBody(req, limitBytes = 131072) {
 }
 
 
+/**
+ * The instance a refusal page names: its organisation when one is configured, otherwise the host of the
+ * sign-in service it sends people to (the OIDC issuer, or the Access team's own domain, derived as the
+ * verifier derives it). `null` when neither is set. Read from the environment at call time.
+ */
+function instanceIdentity(env = process.env) {
+  if (ORGANISATION_NAME) return `This is ${ORGANISATION_NAME}'s ${BRAND.name} portal`;
+  const issuer = String(env.PORTAL_OIDC_ISSUER ?? "").trim();
+  const team = String(env.CF_ACCESS_TEAM ?? "").trim();
+  let host = null;
+  try { host = issuer ? new URL(issuer).host : null; } catch { host = null; }
+  if (!host && team) host = `${team}.cloudflareaccess.com`;
+  return host ? `This ${BRAND.name} portal signs people in through ${host}` : null;
+}
+
 /**
  * The sign-in refusal page.
  *
@@ -3384,6 +3411,12 @@ async function readJsonBody(req, limitBytes = 131072) {
  */
 export function denialPage(status, message) {
   const esc = (t) => String(t).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+  // WHICH INSTANCE THIS IS. Reached through a forwarded port, this page read as a local demo refusing its own
+  // user (measured 2026-09-11, a VS Code Remote-SSH forward on WSL); named, a person can tell it is not
+  // theirs. Named by the organisation when one is set, otherwise by the sign-in service the browser is sent
+  // to, which is public by nature: never by this server's own hostname. No advice about ports: the people
+  // who normally see this page are a hosted instance's own clients, with nothing local to move.
+  const who = instanceIdentity();
   // The upstream message names the address and the reason. That is useful to the person reading it and
   // to whoever they forward it to — but it is a DIAGNOSTIC, so it sits below the fold of the sentence
   // that actually tells them what to do.
@@ -3424,6 +3457,7 @@ ${DOOR_THEME_INIT}
   <a class="btn primary" href="/portal/sign-out">Sign in as someone else</a>
   <a class="btn" href="/portal">Try again</a>
 </div>
+${who ? `<p style="margin-top:20px;font-size:14px">${esc(who)}.</p>` : ""}
 <code>${esc(message)}</code>
 </div></body></html>`;
 }
@@ -3473,7 +3507,8 @@ const escHtml = (t) => String(t).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<"
 //
 // The dark ground moved with that change: the block this page used to carry had guessed #17150f/#ece5d8,
 // and brand pack §01 fixes dark at #0f0e0c near-black + #f0e8d8 parchment. The pack wins.
-export function loginPage({ email, error = null, signedIn = false }) {
+export function loginPage({ email, error = null, signedIn = false, discarded = false, resetCommand = null }) {
+  const reset = resetCommand || `${bareInvocation("passphrase")} --reset`;
   const title = signedIn ? "Signed in" : "Sign in";
   const lockup = `<span class="lockup"><span class="mark">${bracketMark(20, "currentColor", PALETTE.crimson)}</span>`
     + `<span class="word">${escHtml(BRAND.name.toLowerCase())}</span></span>`;
@@ -3517,16 +3552,24 @@ ${signedIn
 <div><a href="/portal">Go to the portal</a></div>
 <form method="post" action="/portal/logout"><button type="submit">Sign out</button></form>`
     : `<p>${escHtml(BRAND.name)} portal, as <span class="who">${escHtml(email)}</span>.</p>
+${discarded ? `<p class="hint">A session this portal did not start, from another ${escHtml(BRAND.name)} on this address or an expired one, was set aside. Sign in below.</p>` : ""}
 ${error ? `<p class="err">${escHtml(error)}</p>` : ""}
 <form method="post" action="/portal/login">
   <label for="passphrase">Passphrase</label>
-  <input id="passphrase" name="passphrase" type="password" autocomplete="current-password" autofocus>
+  <input id="passphrase" name="passphrase" type="password" autocomplete="new-password" autofocus>
   <button type="submit">Sign in</button>
 </form>
-<p class="hint">Lost the passphrase? Run <code>${escHtml(bareInvocation("passphrase"))} --reset</code> on the machine
+<p class="hint">Lost the passphrase? Run <code>${escHtml(reset)}</code> on the machine
 running this portal. It mints a new one and prints it once.</p>`}
 </div></body></html>`;
 }
+// THE FIELD DOES NOT INVITE THE BROWSER'S SAVED PASSWORDS. Every local install and demo answers on
+// 127.0.0.1, so a browser that saved one install's passphrase fills it into the next install's page, and
+// the person is told a passphrase they never typed is wrong (read from the handler, 2026-09-11: the POST
+// compares only what the browser sent). `new-password` is the value browsers honour on a password field;
+// `off` is ignored there. The refusal says to check the field, for a browser that fills it regardless.
+const WRONG_PASSPHRASE = "That passphrase is not correct. If your browser filled the field in, clear it and type the passphrase yourself.";
+
 // The cookie the local session rides in. HttpOnly (no script needs it and nothing in the SPA reads it),
 // SameSite=Strict (there is no cross-site flow to preserve — every portal navigation is same-origin),
 // Path=/ so a report under /portal/report/… carries it too.
@@ -3608,6 +3651,9 @@ class LocalAuthError extends Error {
  * cases the right answer is "sign in again", not "resolve this name through the roster and see what it
  * gets" — which is what accepting the token's own `sub` would do.
  */
+/** Whether this request carries a session cookie at all, readable or not. */
+const hasSessionCookie = (req) => !!parseCookies(req.headers?.cookie)[SESSION_COOKIE];
+
 function localSessionIdentity(req, localAuth) {
   const token = parseCookies(req.headers?.cookie)[SESSION_COOKIE];
   if (!token) return null;
@@ -3788,17 +3834,25 @@ export function makeHttpHandler({ verify, limiter, service, log = () => {}, devI
           res.writeHead(302, { location: to, "cache-control": "no-store", "content-length": 0, ...extra });
           return res.end();
         };
+        // A SESSION COOKIE THIS PORTAL CANNOT READ IS CLEARED, AND SAID. Cookies ignore ports, so a browser
+        // that visited another Clearotron on this address (an earlier demo, another instance) brings that
+        // cookie here, where it verifies as nothing. Cleared, the next sign-in starts clean; and the page
+        // says an old session was set aside, rather than leave a person to guess what changed.
+        const who = localSessionIdentity(req, localAuth);
+        const stale = !who && hasSessionCookie(req);
+        const setAside = stale ? { "set-cookie": clearSessionCookie({ secure }) } : {};
         if (url.pathname === "/portal/login" && req.method === "GET")
-          return page(200, loginPage({ email: localAuth.email, signedIn: !!localSessionIdentity(req, localAuth) }));
+          return page(200, loginPage({ email: localAuth.email, resetCommand: localAuth.resetCommand, signedIn: !!who, discarded: stale }), setAside);
         if (url.pathname === "/portal/login" && req.method === "POST") {
           // Keyed on the peer address, counted by localAuth.attempts (portal-local-auth.mjs:
           // makeAttemptLimiter — a fixed window, NOT the 120/min token bucket the API routes share).
           // On a loopback install every attempt keys to 127.0.0.1, so the window is global; that is the
           // right answer for one user on one machine and is written down in the limiter's own comment.
           if (!localAuth.attempts.take(req.socket?.remoteAddress ?? "unknown"))
-            return page(429, loginPage({ email: localAuth.email, error: "Too many attempts. Wait a few minutes and try again." }));
+            return page(429, loginPage({ email: localAuth.email, resetCommand: localAuth.resetCommand, error: "Too many attempts. Wait a few minutes and try again." }));
           let form;
-          try { form = await readFormBody(req); } catch { return page(400, loginPage({ email: localAuth.email, error: "That passphrase is not correct." })); }
+          // A form that could not be read says nothing about the passphrase, so it is not answered as one.
+          try { form = await readFormBody(req); } catch { return page(400, loginPage({ email: localAuth.email, resetCommand: localAuth.resetCommand, error: "The sign-in form could not be read. Reload this page and try again." }), setAside); }
           let record;
           try {
             record = localAuth.credential();
@@ -3806,14 +3860,19 @@ export function makeHttpHandler({ verify, limiter, service, log = () => {}, devI
             // A credential file that has gone corrupt since boot. The operator gets the reason on
             // stderr; the browser gets a sentence with no filesystem in it.
             log(`local sign-in unavailable: ${String(e?.message ?? e)}`);
-            return page(500, loginPage({ email: localAuth.email, error: "Sign-in is not available. The terminal that started the portal says why." }));
+            return page(500, loginPage({ email: localAuth.email, resetCommand: localAuth.resetCommand, error: "Sign-in is not available. The terminal that started the portal says why." }));
+          }
+          // A REFUSAL FOR ANY REASON BUT THE PASSPHRASE SAYS ITS REASON. "That passphrase is not correct."
+          // sent a person to reset a passphrase that was never wrong. An install with no credential has no
+          // passphrase to be right or wrong about, so saying so gives a caller nothing to guess against.
+          if (!record) {
+            log("local sign-in attempted but no credential is configured — stop the portal and start it again to mint one");
+            return page(401, loginPage({ email: localAuth.email, resetCommand: localAuth.resetCommand, error: "No passphrase is set for this install yet. Stop the portal and start it again to create one." }), setAside);
           }
-          if (!record) log("local sign-in attempted but no credential is configured — stop the portal and start it again to mint one");
-          // ONE SENTENCE FOR EVERY FAILURE. A wrong passphrase, an absent credential and an
-          // unparseable form all answer "That passphrase is not correct." at 401: anything more
-          // specific tells an unauthenticated caller which half of the credential they got right.
+          // ONE SENTENCE FOR A WRONG PASSPHRASE, and nothing more specific: which half of a credential was
+          // right is exactly what an unauthenticated caller must not learn.
           if (!checkPassphrase(record, form.get("passphrase") ?? ""))
-            return page(401, loginPage({ email: localAuth.email, error: "That passphrase is not correct." }));
+            return page(401, loginPage({ email: localAuth.email, resetCommand: localAuth.resetCommand, error: WRONG_PASSPHRASE }), setAside);
           const token = mintSession({ email: localAuth.email, secret: localAuth.secret, ttlSec: localAuth.ttlSec });
           return redirect("/portal", { "set-cookie": setSessionCookie(token, { secure, maxAgeSec: localAuth.ttlSec }) });
         }
@@ -4777,6 +4836,9 @@ const PORT = PORT_CHOICE.port;
       // than a stale copy held in memory.
       credential: () => readLocalCredential(credentialPath),
       attempts: makeAttemptLimiter({ max: 10, windowMs: 5 * 60 * 1000 }),
+      // The sign-in page's recovery line. It resets the file this portal reads, and names no path on this
+      // machine, because the page is read before anyone has signed in (signInResetCommand says how).
+      resetCommand: signInResetCommand({ credentialPath, npxVersion: inNpxCache() ? ownVersion() : null }),
     };
   })();
 

package/driver/portal-upstream.mjs

@@ -420,17 +420,36 @@ export function makeUpstream({ callUpstream, callRecipes = null, recipesOff = nu
       const draft = {};
       for (const k of CREATABLE_FIELDS) if (body[k] !== undefined) draft[k] = body[k];
       const r = await call("POST", "/profiles", draft, principal);
+      // A STORE THAT CANNOT RECORD THE COMPANY is answered with its path and the git commands that fix it.
+      // That sentence is for whoever runs the installation. A manager who holds an organisation cannot act
+      // on it and must not be shown the server's paths, so they are told what to do instead.
+      if (r.status === 409 && String(r.json?.code ?? "").startsWith("store_") && !seesEverything(principal))
+        return { status: 409, json: { code: r.json.code, error: STORE_REFUSAL_FOR_MANAGERS } };
+      // AND A CREATE THE STORE COULD NOT UNDO answers 500 with git's last word and the file it left behind,
+      // either of which can name a server path. Same reader, same rule.
+      if (r.status === 500 && !seesEverything(principal))
+        return { status: 500, json: { ...(r.json?.key ? { key: r.json.key } : {}), error: STORE_FAULT_FOR_MANAGERS } };
       if (r.status !== 201 || org == null || !fileCompany) return r;
       const key = r.json?.key ?? r.json?.profile?.key ?? draft.key;
       try { await fileCompany({ tenant: org, account: key }); }
       catch (e) {
-        return { status: 500, json: { error: `The company was created, but it could not be filed under its organisation (${String(e?.message ?? e).slice(0, 200)}). A person with access to everything can see it and file it.`, key } };
+        // The cause is the grants file's own error, which names its path: said to staff only.
+        const cause = seesEverything(principal) ? ` (${String(e?.message ?? e).slice(0, 200)})` : "";
+        return { status: 500, json: { error: `The company was created, but it could not be filed under its organisation${cause}. A person with access to everything can see it and file it.`, key } };
       }
       return { ...r, json: { ...r.json, tenant: org } };
     },
   };
 }
 
+/** The store refusal as a manager who does not run the installation reads it: no path, no command. */
+export const STORE_REFUSAL_FOR_MANAGERS = "No company was created: this installation cannot save new companies yet, "
+  + "and nothing was changed. Ask whoever runs it to fix the company store.";
+
+/** A create the store could not undo, as that manager reads it: what happened and who acts, no path. */
+export const STORE_FAULT_FOR_MANAGERS = "The company could not be recorded, and part of it may still be on the server. "
+  + "Tell whoever runs this installation before trying again.";
+
 /**
  * What a browser may state when creating a company.
  *

package/driver/search-policy.mjs

@@ -1078,11 +1078,16 @@ export function loadRecipes({ dir = process.env.CLEAROTRON_RECIPES_DIR || null,
   const recipes = new Map();
   retiredBaseSkips.length = 0;
   let customers = [];
+  // ABSENT IS EMPTY; UNREADABLE IS AN ERROR. Only a store that is not there is a store with nothing in it.
+  // One that is there and refuses to be read (permissions, a failing disk) used to come back empty too, and
+  // every door then told its reader the company had no saved searches, while the doors that say "could not
+  // be read" never fired, because they fire on a throw.
+  const absent = (e) => e?.code === "ENOENT" || e?.code === "ENOTDIR";
   try { customers = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name); }
-  catch { recipeCache = { dir, recipes }; return recipes; }   // no recipe store ⇒ empty (not an error)
+  catch (e) { if (!absent(e)) throw e; recipeCache = { dir, recipes }; return recipes; }   // no recipe store ⇒ empty (not an error)
   for (const customer of customers) {
     let files = [];
-    try { files = readdirSync(join(dir, customer)).filter((f) => f.endsWith(".json")); } catch { continue; }
+    try { files = readdirSync(join(dir, customer)).filter((f) => f.endsWith(".json")); } catch (e) { if (!absent(e)) throw e; continue; }
     for (const f of files) {
       const slug = f.replace(/\.json$/, "");
       const r = JSON.parse(readFileSync(join(dir, customer, f), "utf8"));   // parse error = loud (config bug)