clearotron 0.3.2-beta.7 → 0.3.2-beta.9

package/driver/driver.config.mjs

@@ -1,20 +1,21 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
-// Central paths + tunables for the prelim-search deterministic driver.
+// Central paths + tunables for the clearance-search deterministic driver.
 //
 // The driver runs as an ordinary UNIX service account (launched by systemd), NOT as an LLM agent.
 // The agent exec-deny is a gateway agent-tool restriction; it does not apply to this OS process.
 // Every value is env-overridable so the identical code runs from a developer's shell and from the
 // systemd unit on a deployed host.
 
-import { join, dirname, isAbsolute } from "node:path";
+import { join, dirname, basename, isAbsolute, delimiter } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { readdirSync, existsSync, accessSync, statSync, statfsSync, constants as FS } from "node:fs";
+import { readdirSync, existsSync, accessSync, statSync, statfsSync, readFileSync, realpathSync, openSync, readSync, closeSync, constants as FS } from "node:fs";
 import { homedir } from "node:os";
+import { isWsl } from "../shared/wsl.mjs";   // — the one answer to "is this Linux under Windows", which decides the /mnt/<drive> skip
 import { envFrom } from "../shared/env-aliases.mjs";   // — an operator-facing name is the one an operator sets, and it has to work where they set it; — envFrom is the resolver that reads every spelling of it
 import { invoke } from "../shared/invocation.mjs";   // — name a command the reader can actually type
 import { envFileRead } from "../shared/env-local.mjs";   // — WHICH file to set it in, measured; null for a service that read none
-import { numericSetting, resolveNumericSetting } from "./numeric-setting.mjs";   // — a number, or a refusal that names the variable; never NaN
+import { numericSetting, resolveNumericSetting } from "./numeric-setting.mjs"; import { STUDIO_SEGMENTS, STUDIO_SEGMENT_RE, studioSegmentFor } from "../shared/pre-rename-spellings.mjs"; export { STUDIO_SEGMENTS, STUDIO_SEGMENT_RE, studioSegmentFor };   // the studio segment an install keeps its runs under   // — a number, or a refusal that names the variable; never NaN
 
 const { X_OK } = FS;
 
@@ -110,6 +111,23 @@ export const envGateOn = (name) => {
 // so import-time captures silently pinned every test to the FIRST test's env (workspace root, pool,
 // retries) — the root of the intermittent cross-test contamination flake. Getters make "set env, then
 // run" mean what it says, in tests and in prod alike.
+// The four skill folders the identifier rename moved. A store outside the product may still hold them,
+// and a profile may still name them, under the old spelling.
+const RENAMED_SKILL_DIRS = Object.freeze([
+  ["clearance-search", "prelim-search"], ["clearance-register", "prelim-register"],
+  ["clearance-common-law", "prelim-common-law"], ["clearance-variants", "prelim-variants"],
+]);
+/** `[rel, the same path under the folder's other spelling | null]`. PURE. */
+export function skillSpellings(rel) {
+  const m = /^skills\/([a-z-]+)(\/.*)?$/.exec(String(rel ?? ""));
+  if (!m) return [rel, null];
+  for (const [now, before] of RENAMED_SKILL_DIRS) {
+    if (m[1] === now) return [rel, `skills/${before}${m[2] ?? ""}`];
+    if (m[1] === before) return [rel, `skills/${now}${m[2] ?? ""}`];
+  }
+  return [rel, null];
+}
+
 export const config = {
   // / — A BLANK VALUE IS NOT A CONFIGURED VALUE. `process.env.X || default` treats "   " as
   // configured, because a whitespace-only string is TRUTHY in JavaScript — so a variable set to spaces
@@ -211,21 +229,8 @@ export const config = {
    * still fails loudly against the canonical location rather than silently against the overlay.
    */
   resolveSkillPath(relFromSkillsRoot) {
-    const rel = String(relFromSkillsRoot ?? "").replace(/^\/+/, "");
-    const overlay = this.skillsOverlayDir;
-    if (overlay) {
-      // FAIL LOUD ON AN UNREADABLE OVERLAY. existsSync() answers false for a permission error just as it
-      // does for a missing file, so a config store the process cannot read would silently resolve EVERY
-      // file to the repo — swapping a customer's own risk framework for the Generic default with nothing
-      // in the log to say so. A configured-but-unreadable overlay is a deploy defect, not a fallback.
-      if (!existsSync(overlay))
-        throw new Error(`skills_overlay_unreadable:${overlay} (CLEAROTRON_INSTRUCTIONS_DIR names it, set by the operator or derived by the portal from PROFILE_REPO_ROOT, but this process cannot see it — customer-specific skills would silently fall back to the repo defaults)`);
-      const p = join(dirname(overlay), rel);
-      if (existsSync(p)) return p;
-    }
-    return join(dirname(this.skillsBaseDir), rel);
+    return this.resolveSkillPathReport(relFromSkillsRoot).path;
   },
-
   /**
    * WHICH LAYER ANSWERED, as a fact rather than a path — `resolveSkillPath` with its reasoning shown.
    *
@@ -251,13 +256,24 @@ export const config = {
    */
   resolveSkillPathReport(relFromSkillsRoot) {
     const rel = String(relFromSkillsRoot ?? "").replace(/^\/+/, "");
-    const basePath = join(dirname(this.skillsBaseDir), rel);
+    // EITHER SPELLING OF A RENAMED SKILL FOLDER, in either direction. A store that has not moved its
+    // folders still holds `skills/prelim-search/…`, and a profile written before the rename still NAMES
+    // it; the product ships only the new names. Tried in the overlay first — a client's own doctrine must
+    // never be silently replaced by ours because a folder name changed — and the base answers only under
+    // the name it ships.
+    const [asNamed, other] = skillSpellings(rel);
+    const shipped = rel === asNamed && other && /^skills\/prelim-/.test(asNamed) ? other : asNamed;
+    const basePath = join(dirname(this.skillsBaseDir), shipped);
     const overlay = this.skillsOverlayDir;
     if (!overlay) return { path: basePath, rel, layer: existsSync(basePath) ? "base-only" : "missing", overlayPath: null, basePath };
     if (!existsSync(overlay))
       throw new Error(`skills_overlay_unreadable:${overlay} (CLEAROTRON_INSTRUCTIONS_DIR names it, set by the operator or derived by the portal from PROFILE_REPO_ROOT, but this process cannot see it — customer-specific skills would silently fall back to the repo defaults)`);
-    const overlayPath = join(dirname(overlay), rel);
+    const overlayPath = join(dirname(overlay), asNamed);
     if (existsSync(overlayPath)) return { path: overlayPath, rel, layer: "overlay", overlayPath, basePath };
+    if (other) {
+      const otherPath = join(dirname(overlay), other);
+      if (existsSync(otherPath)) return { path: otherPath, rel, layer: "overlay", overlayPath: otherPath, basePath };
+    }
     return { path: basePath, rel, layer: existsSync(basePath) ? "base" : "missing", overlayPath, basePath };
   },
 
@@ -275,7 +291,7 @@ export const config = {
     return roots;
   },
 
-  // The base that a profile's "skills/prelim-search/<file>.md" path is relative to — i.e. the PARENT
+  // The base that a profile's "skills/clearance-search/<file>.md" path is relative to — i.e. the PARENT
   // of skillsDir. Everything the DRIVER reads itself (framework manifests, band-meaning extraction)
   // must join against this, exactly as the agent resolves the same relative paths against the
   // skillsDir it is handed (gateway.mjs engineSkillsDir).
@@ -304,15 +320,17 @@ export const config = {
   },
   // Escaped prefix for the reverse regexes below (a custom prefix may carry regex metachars).
   get workspacePrefixRe() { return this.workspacePrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); },
-  // `prelim-search` IS NOT A PRODUCT NAME HERE and does not follow the product rename. It is a
-  // directory segment on disk, and every archived run — its slug dirs, its `archive/`, its matter
-  // ledger — was written under it. Renaming the segment does not move those runs; it points the
-  // reader somewhere empty, and an empty directory reads as "no runs" rather than as an error.
-  // The rule the tree already enforces elsewhere: a token that is read back out of an archive keeps
-  // its old spelling, or the code refuses its own archive. Thirteen sites compute this segment and
-  // all thirteen stay.
+  // THE STUDIO SEGMENT IS NOT A PRODUCT NAME and does not follow the product rename. It is a directory
+  // segment on disk, and every archived run — its slug dirs, its `archive/`, its queue, its matter ledger —
+  // was written under it. Renaming it does not move those runs; it points the reader somewhere empty, and
+  // an empty directory reads as "no runs" rather than as an error. The identifier rename rewrote this
+  // comment together with the thirteen sites it protected, and an upgraded install lost sight of its whole
+  // archive. So an install keeps the segment it has: `prelim-search` wherever that directory exists, and
+  // `clearance-search` only for an install that has no other. Every site asks `studioSegmentFor`.
+  studioSegment(workspaceDir) { return studioSegmentFor(workspaceDir); },
   studioRootForAgent(agentId) {
-    return join(this.workspaceRoot, this.workspaceDirName(agentId), "studio", "prelim-search");
+    const ws = join(this.workspaceRoot, this.workspaceDirName(agentId));
+    return join(ws, "studio", studioSegmentFor(ws));
   },
   queueDirForAgent(agentId) {
     return join(this.studioRootForAgent(agentId), "queue");
@@ -320,9 +338,10 @@ export const config = {
   archiveRootForAgent(agentId) {
     return join(this.studioRootForAgent(agentId), "archive");
   },
-  // …/<prefix><id>/studio/prelim-search/queue → "<id>"; null if the path isn't an agent queue dir.
+  // …/<prefix><id>/studio/<segment>/queue → "<id>"; null if the path isn't an agent queue dir. Either
+  // spelling of the segment, because an install keeps the one it has.
   agentIdFromQueueDir(qdir) {
-    const m = new RegExp(`(?:^|/)${this.workspacePrefixRe}([^/]+)/studio/prelim-search/queue/?$`).exec(qdir);
+    const m = new RegExp(`(?:^|/)${this.workspacePrefixRe}([^/]+)/studio/${STUDIO_SEGMENT_RE}/queue/?$`).exec(qdir);
     return m ? m[1] : null;
   },
   // Every agent workspace's clearotron queue. The systemd `.path` watches these and the runner drains ALL of
@@ -342,14 +361,18 @@ export const config = {
     try {
       for (const name of readdirSync(root)) {
         if (this.agentIdFromWorkspaceName(name) == null) continue;
-        const q = join(root, name, "studio", "prelim-search", "queue");
-        if (existsSync(q)) dirs.push(q);
+        // BOTH spellings are drained where both exist: a job queued under either is a job somebody is
+        // waiting on, and an unwatched queue looks exactly like an empty one.
+        for (const seg of STUDIO_SEGMENTS) {
+          const q = join(root, name, "studio", seg, "queue");
+          if (existsSync(q)) dirs.push(q);
+        }
       }
     } catch { /* workspaceRoot may not exist in some test envs — fall through to the canonical queue */ }
     // THE ONE AGENT NAME NO CONFIGURATION REMOVES, and it is deliberate. row 5.
     //
     // `this.queueDir` is `queueDirForAgent("clawdi")` — a LITERAL, not `defaultAgent` — so every
-    // deployment, however configured, watches `<workspacePrefix>clawdi/studio/prelim-search/queue`.
+    // deployment, however configured, watches `<workspacePrefix>clawdi/studio/clearance-search/queue`.
     // Setting CLEAROTRON_DEFAULT_AGENT does not remove it (prod runs `ops`, dev runs `dev`, and both still
     // watch this); nor does CLEAROTRON_WORKSPACE_PREFIX. An installer who copies `.env.example` gets a
     // neutral default agent AND this directory.
@@ -539,7 +562,7 @@ export const config = {
   // directory, so renaming the default moves the install to an empty one and nothing migrates. Here
   // the orphaned files are run-slot locks, so a live run's slot goes unseen and the global cap is
   // silently exceeded rather than enforced. Ruling.
-  get runLockDir() { return this.envValue("CLEAROTRON_RUN_LOCK_DIR") || join(this.workspaceRoot, "prelim-run-locks"); },
+  get runLockDir() { return this.envValue("CLEAROTRON_RUN_LOCK_DIR") || [join(this.workspaceRoot, "prelim-run-locks"), join(this.workspaceRoot, "clearance-run-locks")].find((d, i) => i === 1 || existsSync(d)); },   // the name the install already has wins
 
   // Delivery outbox (Workstream B). On a handoff-mode finish the driver drops <runId>.pending here (naming
   // the forwarder agent); the systemd-user prelim-outbox.path unit fires an INSTANT clearotron-deliver wake off
@@ -551,7 +574,31 @@ export const config = {
   // directory, so renaming the default moves the install to an empty one and nothing migrates. Here
   // the orphaned files are requester-facing events — delivered, run-failed, intake-rejected — so the
   // visible failure is a requester never told their run finished. Ruling.
-  get outboxDir() { return this.envValue("CLEAROTRON_OUTBOX_DIR") || join(this.workspaceRoot, "prelim-outbox"); },
+  get outboxDir() { return this.envValue("CLEAROTRON_OUTBOX_DIR") || join(this.workspaceRoot, "clearance-outbox"); },
+
+  // ── THE DIRECTORY THIS DEFAULT USED TO NAME, AND WHY IT IS STILL READ ──────────────────────────────
+  //
+  // This default was `clearance-outbox` until the identifier was renamed. A deployment that never pinned
+  // `CLEAROTRON_OUTBOX_DIR` has its `<runId>.pending` markers sitting in the old directory, and moving
+  // the default without reading the old one orphans every one of them. That failure is silent and it is
+  // the expensive kind: a marker is a report a client is OWED, an unread outbox is indistinguishable
+  // from nothing to send, and the run that produced it has already recorded itself as delivered-pending.
+  //
+  // NULL WHEN THE VARIABLE IS SET, because then the operator named the directory and there is no old
+  // default in play. Writers use `outboxDir` alone; only readers consult this, which is the same posture
+  // the run records take — new work uses the new name, old work is still understood.
+  //
+  // THE OLD SPELLING IS THE WHOLE POINT OF THIS ACCESSOR, and a sweep took it. The identifier rename
+  // moved the directory from `prelim-outbox` to `clearance-outbox`, and the follow-up that renamed the
+  // directory's 85 occurrences rewrote this literal along with them — leaving the accessor that exists to
+  // name the OLD directory naming the new one. Both getters then answered the same path: the drain read
+  // the new directory twice, never read the old one, and every marker under it was listed TWICE. So a box
+  // that never pinned the variable got exactly the failure the block above describes — orphaned markers,
+  // silently — plus duplicate work on the ones it could see. It is written once, here, and pinned by a
+  // test that asserts the two are different.
+  get legacyOutboxDir() {
+    return this.envValue("CLEAROTRON_OUTBOX_DIR") ? null : join(this.workspaceRoot, "prelim-outbox");
+  },
 
   // ── Delivery/comms (Phase 2, standalone product) ─────────────────────────────────────────────────
   // THERE IS ONE MODE AND IT IS NOT A SETTING. The driver SENDS NOTHING: every requester-facing event
@@ -569,7 +616,7 @@ export const config = {
   // LOCATION (see studioRootForAgent / agentIdFromQueueDir above).
   //
   // THE DEFAULT IS PART OF A PATH, so changing it moves where an install looks for its own runs:
-  // every run dir is `<workspaceRoot>/workspace-<agent>/studio/prelim-search/…`. An install created
+  // every run dir is `<workspaceRoot>/workspace-<agent>/studio/clearance-search/…`. An install created
   // before this default changed keeps its runs under the old id and must pin it — both spellings,
   // because the gather servers read their own variable:
   //
@@ -616,12 +663,12 @@ export const MODELS = {
   gemini: "google/gemini-3.1-pro-preview",
   "gemini-flash": "google/gemini-3-flash-preview",
   "deepseek-v4-pro": "together/deepseek-ai/DeepSeek-V4-Pro",
-  // azure = the proven-working Azure GPT-5.4 (api: openai-completions). It REPLACED the dead
-  // azure-openai-pro/gpt-5.4-pro (api: azure-openai-responses), which rejected every payload at the
-  // provider level — "provider rejected the request schema or tool payload" — and was retired
-  // 2026-06-08 (live-probed both: 5.4-pro exit 1, 5.4 completions clean). Env-overridable for dev/prod
-  // parity; default is the rendered $AZURE_OPENAI_DEPLOYMENT catalog id.
-  azure: process.env.CLEAROTRON_AZURE_MODEL || "azure-openai/gpt-5.4",
+  // azure = a legacy catalogue entry for an Azure GPT deployment. NO STAGE NAMES IT AND NO ENGINE RUNS IT:
+  // the Claude adapter refuses the alias and the codex adapter maps no tier onto it. So its target is a
+  // constant. The setting that used to override it was retired on 2026-09-15 and nothing reads it any
+  // more; the configuration reference lists it under the settings that do nothing. It is named only
+  // there, in prose, because a name written in a source file here counts as a name this build reads.
+  azure: "azure-openai/gpt-5.4",
 };
 
 // alias → full id; a value that's already a full provider/model id (contains "/") passes through.
@@ -659,6 +706,13 @@ export function resolveModel(model) {
  * never a default. A null on either side makes the comparison UNKNOWN, and an unknown must never be
  * recorded as a match — that is the absence-read-as-a-pass class this whole issue is about.
  */
+// FABLE IS NOT A FAMILY HERE, ON PURPOSE. Nobody has seen what the wire reports for a fable turn, so an id
+// naming fable stays unknown and its comparison can never manufacture a mismatch. Placing it was tried
+// (2026-09-15) and refused turns that had always run: a fable request served by claude-sonnet-5, by
+// claude-opus-5, by a deployment named after another tier or by a GPT id, an opus request served as
+// claude-fable-5-1, and any tier served under a name beginning with the word. It was taken out again the
+// same day. The report's model line still names Fable: servedModels (tokens.mjs) reads a fable request's tier
+// itself, where only the report sees it, and never through this comparison.
 const MODEL_FAMILY_RE = /(?:^|\/)(?:claude-)?(opus|sonnet|haiku)(?:[-.]|$)/i;
 
 // — THE OPENAI SIDE, added when the codex path could first answer "what ran".
@@ -931,7 +985,7 @@ export const PROVIDERS = {
     id: "corsearch",
     label: "Corsearch",
     credEnv: "CORSEARCH_SESSION_KEY",
-    skillDoc: "skills/prelim-register/providers/corsearch.md",
+    skillDoc: "skills/clearance-register/providers/corsearch.md",
     hasPublicRecordUrl: true,
     // WP-receipts W2: the public per-record origin (publicRecordOrigin + /mark/<jur>/<id> is a working
     // link) — replaces the fragile resolved-link-origin inference at render for receipt-carrying runs.
@@ -1005,7 +1059,7 @@ export const PROVIDERS = {
     id: "clarivate",
     label: "Clarivate Compumark",
     credEnv: "CLARIVATE_API_KEY",
-    skillDoc: "skills/prelim-register/providers/clarivate.md",
+    skillDoc: "skills/clearance-register/providers/clarivate.md",
     hasPublicRecordUrl: false, // Compumark Content has no public record URL — cite the office register
     //, ruling 2026-08-20 — WHAT A CARD SHOWS WHERE A LINK CANNOT GO. A UI exists for this
     // provider and we do not know its per-record URL, so the card says so and says it is unfinished.
@@ -1147,7 +1201,7 @@ export const PROVIDERS = {
     id: "signa",
     label: "Signa",
     credEnv: "SIGNA_API_KEY",
-    skillDoc: "skills/prelim-register/providers/signa.md",
+    skillDoc: "skills/clearance-register/providers/signa.md",
     hasPublicRecordUrl: false, // Signa exposes no per-record public URL — cite the office register
     //, ruling 2026-08-20 — no register UI exists to link to at all, so the card points at
     // the artifact that DOES carry the record: the audit workbook. Naming it is the whole of this
@@ -1202,8 +1256,12 @@ export const PROVIDERS = {
         // on the search response, so this no longer has to answer `present` and nothing else. It is
         // still null whenever the vendor would only approximate it — and null there means UNKNOWN,
         // which is the whole reason the field may never be filled in with a figure from anywhere else.
+        // `floor` rides beside `approximate` because the two are one fact: the register answered, and the
+        // answer is "more than this". Without the number the disclosure is not usable — "approximate"
+        // alone says no more than "unknown" does, which is the state this replaces.
         return { ok: true, total: Number.isFinite(p.total_hits) ? p.total_hits : null,
-          approximate: p.total_approximate === true, present: p.present === true, note: p.note };
+          approximate: p.total_approximate === true, floor: Number.isFinite(p.total_floor) ? p.total_floor : null,
+          present: p.present === true, note: p.note };
       } catch (e) { return { ok: false, cause: `countHits threw: ${e.message}` }; }
     },
     // `reason`, not `cause`, on every refusal: the listing reads `reason` (register-records.mjs), so a
@@ -1293,7 +1351,7 @@ export const PROVIDERS = {
     // list — without this, an instance holding the id and no secret passes preflight and dies on the
     // first token request, after model spend and reported as a provider fault.
     credEnvAlso: ["EUIPO_CLIENT_SECRET"],
-    skillDoc: "skills/prelim-register/providers/euipo.md",
+    skillDoc: "skills/clearance-register/providers/euipo.md",
     hasPublicRecordUrl: true,
     publicRecordOrigin: "https://euipo.europa.eu",
     async recordFetch(uri, { agentId, sessionKey, recordLog = null }) {
@@ -1359,7 +1417,7 @@ export const PROVIDERS = {
     id: "uspto-local",
     label: "USPTO (local index)",
     credEnv: "USPTO_LOCAL_DB",
-    skillDoc: "skills/prelim-register/providers/uspto-local.md",
+    skillDoc: "skills/clearance-register/providers/uspto-local.md",
     hasPublicRecordUrl: true,
     // TSDR publishes a page per serial, so a finding can cite an address the reader can open. The
     // record ref is /mark/us/<serial>, and the core builds the full statusSearch link on the record.
@@ -1463,7 +1521,7 @@ export const PROVIDERS = {
     label: "Free tier (EUIPO + USPTO local index)",
     credEnv: "EUIPO_CLIENT_ID",
     credEnvAlso: ["EUIPO_CLIENT_SECRET"],
-    skillDoc: "skills/prelim-register/providers/free-tier.md",
+    skillDoc: "skills/clearance-register/providers/free-tier.md",
     hasPublicRecordUrl: true,
     // NULL, deliberately: the two members have DIFFERENT public origins (euipo.europa.eu and the USPTO),
     // so a single origin string here would stamp one office's host onto the other's citations. The
@@ -1813,7 +1871,7 @@ export function preflightCredentials(env = process.env) {
 // paid for. This door is that same failure, moved in front of the spend.
 //
 // GATED ON THE COMPONENT, NEVER ON THE PIPELINE. `pipeline === "clearance"` is the wrong predicate and
-// fails in the expensive direction: `prelim-register-only` is a clearance that carries
+// fails in the expensive direction: `clearance-register-only` is a clearance that carries
 // `commonLawGrid: false`, searches no unregistered-use half by design, and would be refused for a
 // credential its lane never reads. The component IS the question — search-policy.mjs calls it "the
 // clearance's unregistered-use half" in as many words.
@@ -1910,26 +1968,32 @@ export const ENGINE_BINARIES = {
     // `vendor` is the one word a person needs — the staff config page answers "which engine is
     // running the searches", and `label` below is the MECHANISM, which is what took off that page.
     vendor: "Anthropic",
+    // `product` is the name a reader knows the program by, beside the vendor in setup's engine question
+    // ("Claude, by Anthropic"). Not `fallback`, which is the command word and lower-case.
+    product: "Claude",
     env: "CLEAROTRON_CLAUDE_PATH", fallback: "claude",
+    // The npm package that carries this program, and the oldest version setup installs: "this version or
+    // newer", with no ceiling. Setup installs it into the engines folder (enginesFolder, below the table)
+    // when the reader picks this engine, and the resolver uses it only when the machine has no copy of its
+    // own. The package's own `bin` field names the program, so no path inside it is written down here.
+    package: "@anthropic-ai/claude-code", floor: "2.1.270",
+    // WHAT THE INSTALL TAKES ON DISK, in MB, which setup states before it asks to install. MEASURED, not
+    // declared by the vendor: the engines folder after a fresh install of this package into an empty
+    // folder, on npm 10.9.8 and on 11.19.1, 2026-09-14. A later release can be larger or smaller, so setup
+    // says "about". Re-measure when the floor moves.
+    installMB: 214,
+    // The licence setup states wherever it tells a reader what they are about to install or use, as the
+    // vendor's package declares it: "SEE LICENSE IN README.md", Anthropic's own terms.
+    licence: "proprietary third-party software",
     label: "Anthropic — each stage runs as a headless `claude -p` turn",
     module: "engine/anthropic-agent.mjs", adapter: "anthropicAgentEngine",
     signIn: "run `claude` once in a terminal and complete the sign-in",
     authEnv: "CLEAROTRON_AI_BILLING", apiKeyEnv: "ANTHROPIC_API_KEY",
     subscriptionHow: "sign in once with `claude`",
-    // — HERE RATHER THAN IN THE WIZARD, for the same reason `authEnv` is: this table is what the
-    // wizard and the run-door preflight both read, and an install command living in the wizard would be
-    // a second place an engine is described. Verified against the registry 2026-08-24: 2.1.241.
-    //
-    // npm, NOT the vendor's shell installer. `curl … | bash` is the other documented route for this CLI
-    // and the wizard will not run one: a command this product executes on someone's box has to be one
-    // they can read in full before they answer, and a piped remote script is not.
-    install: "npm install -g @anthropic-ai/claude-code",
-    // — THE NO-ROOT ROUTE, NAMED AND NEVER EXECUTED. The stance above holds: this
-    // product does not run a piped remote script. But on a box whose npm prefix needs root, the npm
-    // route CANNOT work as this user, and offering only it was a dead end the owner hit. The wizard
-    // prints this for the reader to run BY THEIR OWN HAND in another terminal — their shell, their
-    // eyes, their decision — and says where it lands so the path answer afterwards is not a guess.
-    installNoRoot: { cmd: "curl -fsSL https://claude.ai/install.sh | bash", lands: "~/.local/bin" },
+    // `install`, the command that puts this program in the engines folder, is written in below the table
+    // from `package` and `floor`, so the command a reader is shown and the one setup runs cannot drift.
+    // npm, NOT the vendor's shell installer: a command this product executes on someone's box has to be
+    // one they can read in full before they answer, and a piped remote script is not.
     // — the documented headless ending. `claude setup-token` walks the sign-in and
     // prints a long-lived token; the stage subprocess env is a spread of the driver's — spawnEnv
     // strips ONLY the API key under subscription — so a token in the env file reaches the CLI
@@ -1940,23 +2004,66 @@ export const ENGINE_BINARIES = {
   },
   "openai-agent": {
     vendor: "OpenAI",
+    product: "Codex",
     env: "CLEAROTRON_CODEX_PATH", fallback: "codex",
+    package: "@openai/codex", floor: "0.154.0",
+    installMB: 324,   // measured the same way and on the same day as Claude's, above
+    licence: "third-party software under the Apache-2.0 licence",   // the package's own "license" field
     label: "OpenAI — each stage runs as a headless `codex exec` turn",
     module: "engine/openai-agent.mjs", adapter: "openaiAgentEngine",
     signIn: "run `codex login`",
     authEnv: "CLEAROTRON_AI_BILLING", apiKeyEnv: "CODEX_API_KEY",
     subscriptionHow: "sign in once with `codex login` — the adapter reads ~/.codex/auth.json and refuses before spending if it is absent",
-    // Verified against the registry 2026-08-24: 0.149.1.
-    install: "npm install -g @openai/codex",
-    // — no vendor shell installer exists for this CLI; the no-root answer on a
-    // root-only prefix is npm's own prefix move, which the wizard names the same way.
-    installNoRoot: null,
     // — codex's headless ending writes its own ~/.codex/auth.json; there is no
     // token to capture into an env file, and inventing one would be a route nobody has driven.
     headless: { cmd: "codex login --device-auth", tokenEnv: null },
   },
 };
 
+// ── WHERE SETUP INSTALLS AN ENGINE'S PROGRAM, AND THE COMMAND THAT DOES IT ─────────────────────────────
+//
+// Nothing is bundled into the package. Setup installs the ONE program the reader's engine runs, when they
+// say yes, as an ordinary npm project in a folder Clearotron owns under their home directory: npm then
+// fetches that platform's binary and nothing else, and needs no root. The folder is not on PATH, so a copy
+// the machine installs itself is found first (resolveEngineProgram). `clearotron update` runs the same
+// install again, which moves the program to the newest its vendor publishes: measured on npm 10.9.8 and
+// 11.19.1, re-running an install with a `>=` range over an older copy moves it to the newest, where
+// `npm update` would stop at the caret npm writes into the folder's package.json.
+
+/** Where to install, and look for, the engine programs instead of the default folder. An EMPTY directory means none. */
+export const ENGINES_DIR_ENV = "CLEAROTRON_ENGINES_DIR";
+
+/** The default engines folder as a reader types it. */
+const ENGINES_FOLDER_TYPED = "~/.local/share/clearotron/engines";
+
+/**
+ * The folder setup installs engine programs into and the resolver's last step reads: ENGINES_DIR_ENV from
+ * this process when set, otherwise `~/.local/share/clearotron/engines`. Under the home directory rather
+ * than the install's own tree, because an update replaces that tree, and because every service runs as a
+ * user unit under the same home as the setup that installed it. XDG_DATA_HOME is not consulted: a shell's
+ * value does not reach the services, and the two would then look in different folders.
+ */
+export function enginesFolder({ env = process.env, home = homedir() } = {}) {
+  return String(env[ENGINES_DIR_ENV] ?? "").trim() || join(home, ".local", "share", "clearotron", "engines");
+}
+
+/** The npm arguments that install, or refresh, an engine's program in `dir`: "this version or newer". */
+export function engineInstallArgs(spec, dir = enginesFolder()) {
+  return ["install", "--prefix", dir, "--no-fund", "--no-audit", `${spec.package}@>=${spec.floor}`];
+}
+
+/** A shell word as a reader pastes it: quoted when it must be, because a bare `>=` is a redirection. */
+const shellWord = (w) => (/^[\w@%+=:,./~-]+$/.test(w) ? w : `'${String(w).replace(/'/g, "'\\''")}'`);
+
+/** The same install as a command a reader can paste. The default folder is written the way they type it. */
+export function engineInstallCommand(spec, dir = ENGINES_FOLDER_TYPED) {
+  return ["npm", ...engineInstallArgs(spec, dir)].map(shellWord).join(" ");
+}
+
+// The printable command each engine carries, for the readers that show one without a folder to hand (the
+// portal's engine page, doctor's way out of demo mode), made from the same parts as the install setup runs.
+for (const spec of Object.values(ENGINE_BINARIES)) spec.install = engineInstallCommand(spec);
+
 /** The production default, in ONE place rather than a literal repeated at every reader. */
 export const DEFAULT_ENGINE_ID = "anthropic-agent";
 
@@ -1971,48 +2078,190 @@ export function engineAdapterSpecifier(engine) {
   return spec ? pathToFileURL(join(DRIVER_DIR, spec.module)).href : null;
 }
 
-/** Resolve `name` the way spawn(2) would, or null. No separator ⇒ a PATH walk; otherwise the path itself. */
-function resolveExecutable(name, env) {
-  const executable = (p) => { try { return statSync(p).isFile() && (accessSync(p, X_OK), true); } catch { return null; } };
-  if (name.includes("/")) return executable(name) ? name : null;
-  for (const dir of String(env.PATH ?? "").split(":")) {
-    if (!dir) continue;
-    const p = join(dir, name);
-    if (executable(p)) return p;
+// ── WHERE AN ENGINE'S PROGRAM IS FOUND: ONE PLACE, AND EVERY READER ASKS IT ─────────────────────────────
+//
+// The run door, the inventory the portal reads, the wizard, doctor and both adapters all ask this one
+// function. Before it there were four answers: this file's PATH walk, the wizard's own walk (the only one
+// that passed over a Windows copy under WSL), and each adapter handing spawn(2) a bare word so the OS made
+// its own choice. They agreed only while every copy lived on PATH.
+//
+// THE ORDER, and why the machine's own copy wins:
+//   1. The explicit setting (`CLEAROTRON_CLAUDE_PATH` / `CLEAROTRON_CODEX_PATH`). A value that is set and
+//      unusable is REPORTED, never overruled: the reader stated it, and quietly resolving somewhere else
+//      would run a program nobody chose. The engine's own fallback word (`claude`, `codex`) is the default
+//      spelled out, which is how the shipped example files write it, so it means exactly what unset means.
+//   2. The program on PATH: the machine's own install, which keeps updating itself.
+//   3. The copy setup installed in the engines folder (enginesFolder, above), only when the machine has
+//      none. That folder is not on PATH. If a reader puts its node_modules/.bin there, a PATH hit that IS
+//      that copy is passed over in step 2 and taken for what it is in step 3, so it is never reported, or
+//      written into a settings file, as the machine's own.
+//
+// FILESYSTEM ONLY, like the rest of this door (see the header above ENGINE_BINARIES): nothing is spawned.
+
+/** A path on a Windows drive as WSL mounts it. */
+export const ON_A_WINDOWS_DRIVE = /^\/mnt\/[a-z]\//i;
+
+const isExecFile = (p) => { try { return statSync(p).isFile() && (accessSync(p, X_OK), true); } catch { return false; } };
+const realOrNull = (p) => { try { return realpathSync(p); } catch { return null; } };
+const readPackage = (dir) => { try { return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")); } catch { return null; } };
+
+/**
+ * Whether the kernel runs this file ITSELF: a native executable (ELF, Mach-O, a Windows PE) or a `#!` script.
+ *
+ * Asked only of a file inside the vendor's own package, for one measured reason. The Claude package ships
+ * `bin/claude.exe` as a 500-byte shell placeholder and puts the real program over it in its install step.
+ * With `--ignore-scripts`, or with the platform's native package missing, the placeholder stays. It is a
+ * regular file with the execute bit, so the executable check accepts it, and spawn runs it through `sh`:
+ * it prints "claude native binary not installed" and exits 1, at every stage. It has neither `#!` nor a
+ * binary header, so this refuses it at the door instead. A file anywhere else is judged as before; a
+ * reader's own wrapper script is not ours to second-guess.
+ */
+function runsDirectly(file) {
+  const head = Buffer.alloc(4);
+  let fd = null, n = 0;
+  try { fd = openSync(file, "r"); n = readSync(fd, head, 0, 4, 0); }
+  catch { return false; }
+  finally { if (fd !== null) { try { closeSync(fd); } catch { /* nothing left to release */ } } }
+  if (n >= 2 && head[0] === 0x23 && head[1] === 0x21) return true;                  // #!
+  if (n >= 2 && head[0] === 0x4d && head[1] === 0x5a) return true;                  // MZ
+  if (n < 4) return false;
+  const word = head.readUInt32BE(0);
+  return word === 0x7f454c46                                                         // ELF
+    || [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe].includes(word);  // Mach-O, thin and universal
+}
+
+/** The npm package a file belongs to: the nearest package.json within a few levels of its real path. */
+function owningPackage(file) {
+  let d = dirname(realOrNull(file) ?? file);
+  for (let i = 0; i < 4; i++) {
+    const pkg = readPackage(d);
+    if (pkg) return { name: pkg.name ?? null, version: pkg.version ?? null };
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
   }
   return null;
 }
 
+/** The directory the installed copy of `spec.package` lives in under the engines folder `root`, or null. */
+function installedPackageDir(spec, root) {
+  if (!spec.package || !root) return null;
+  const dir = join(root, "node_modules", ...spec.package.split("/"));
+  return existsSync(join(dir, "package.json")) ? dir : null;
+}
+
+/** The program that installed copy declares for this engine, by the package's own `bin` field, or null. */
+function installedProgram(spec, root) {
+  const dir = installedPackageDir(spec, root);
+  if (!dir) return null;
+  const pkg = readPackage(dir);
+  const rel = typeof pkg?.bin === "string" ? pkg.bin : pkg?.bin?.[spec.fallback];
+  return rel ? join(dir, rel) : null;
+}
+
+/** Can this candidate be spawned as the engine? `{ok: true, version}` or `{ok: false, why}`. */
+function engineCandidate(p, spec) {
+  if (!isExecFile(p)) return { ok: false, why: "not an executable file (it is missing, is a directory, or lacks the execute bit for this user)" };
+  const own = owningPackage(p);
+  const vendor = Boolean(spec.package) && own?.name === spec.package;
+  if (vendor && !runsDirectly(p)) {
+    return { ok: false, why: `the placeholder ${spec.package} leaves when its install step did not run (npm was given `
+      + "--ignore-scripts, or the platform's native package is missing), so every stage would print an error and "
+      + "exit. Reinstall without --ignore-scripts" };
+  }
+  return { ok: true, version: vendor ? own.version : null };
+}
+
+/**
+ * Find the program an engine spawns. Never throws: refusing is the caller's decision (preflightEngineBinary).
+ *
+ * Returns `{engine, binEnv, bin, explicit, relative, resolved, source, version, windowsShim, skipped, rejected}`.
+ * `resolved` is an absolute path or null. `source` is "explicit" | "path" | "installed" | null. `version` is
+ * read from the copy's own package.json when npm installed it, and null otherwise, because nothing is
+ * spawned to ask. `skipped` lists Windows copies passed over under WSL; `rejected` lists candidates that
+ * could not run, each with its reason and the step that found it (`source`).
+ *
+ * `enginesDir`: undefined reads the engines folder (enginesFolder: ENGINES_DIR_ENV from THIS process, then
+ * the default under the home directory); a directory looks there; null looks nowhere. It is read from the
+ * process rather than from `env` because it describes this user's install, not the configuration being
+ * asked about: doctor asks about the units' environment from a shell, and the folder is the same either
+ * way, because the services run as user units under the same home. `wsl` and `onWindowsDrive` are
+ * injectable for the reason shared/wsl.mjs gives.
+ */
+export function resolveEngineProgram(engine, { env = process.env, enginesDir = undefined, wsl = null, onWindowsDrive = null } = {}) {
+  const id = String(engine ?? "").trim().toLowerCase();
+  const spec = ENGINE_BINARIES[id];
+  const out = { engine: id, binEnv: spec?.env ?? null, bin: null, explicit: false, relative: false,
+    resolved: null, source: null, version: null, windowsShim: false, skipped: [], rejected: [] };
+  if (!spec) return out;
+  const set = String(envFrom(env, spec.env) ?? "").trim();
+  out.explicit = Boolean(set) && set !== spec.fallback;
+  out.bin = out.explicit ? set : spec.fallback;
+  const underWsl = wsl ?? isWsl({ env });
+  const onDrive = onWindowsDrive ?? ((p) => ON_A_WINDOWS_DRIVE.test(p));
+  const take = (p, source) => {
+    const c = engineCandidate(p, spec);
+    if (!c.ok) { out.rejected.push({ path: p, why: c.why, source }); return false; }
+    Object.assign(out, { resolved: p, source, version: c.version });
+    return true;
+  };
+
+  if (out.explicit && out.bin.includes("/")) {
+    if (!isAbsolute(out.bin)) { out.relative = true; return out; }
+    out.windowsShim = underWsl && onDrive(out.bin);
+    take(out.bin, "explicit");
+    return out;
+  }
+
+  // THE PATH WALK splits on the platform's own delimiter. This file's walk used to split on ":", which
+  // tears a Windows PATH at every drive letter; the wizard's walk already used the delimiter.
+  const installed = out.explicit ? null : installedProgram(spec, enginesDir !== undefined ? enginesDir : enginesFolder());
+  const installedReal = installed ? realOrNull(installed) : null;
+  for (const dir of String(env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    const p = join(dir, out.bin);
+    if (!isExecFile(p)) continue;
+    // UNDER WSL THE WINDOWS PATH IS APPENDED TO THIS ONE, so `claude` on a fresh WSL2 Ubuntu resolves to the
+    // Windows build before any Linux install. It is executable, and it fails the proof turn as "not signed
+    // in" because the credential it looks for is the Linux one. Passed over, and named for the caller to say.
+    if (underWsl && onDrive(p)) { out.skipped.push(p); continue; }
+    if (installedReal && realOrNull(p) === installedReal) continue;
+    if (take(p, out.explicit ? "explicit" : "path")) return out;
+  }
+  if (installed) take(installed, "installed");
+  return out;
+}
+
 /**
- * Refuse a run whose engine binary is missing, unexecutable, or written as a relative path.
+ * Refuse a run whose engine program cannot be found or run, or is written as a relative path.
  *
  * Throws, like preflightCredentials, and is called at the same door — pipelineInner, before the run
- * context is built. Returns {engine, binEnv, bin, resolved} when the binary is usable.
+ * context is built. Returns {engine, binEnv, bin, resolved, source, version} when the program is usable:
+ * the answer of resolveEngineProgram above, which every other reader asks too.
  *
  * An UNKNOWN CLEAROTRON_AI returns without checking rather than throwing a second, differently-worded
  * version of gateway.selectEngine's error. One definition of "that is not an engine", and it is the
  * registry's.
  */
-export function preflightEngineBinary(env = process.env, { platform = process.platform } = {}) {
+export function preflightEngineBinary(env = process.env, { platform = process.platform, enginesDir = undefined, wsl = null, onWindowsDrive = null } = {}) {
   // item 3 — NATIVE WINDOWS REFUSES BY NAME, BEFORE ANYTHING READS PATH.
   //
-  // INSTALL.md promises a native-Windows run "refuses at preflight" and names the reason. Nothing
-  // implemented it, so what a Windows user actually got was the PATH resolver below — which splits on
-  // ":" and therefore tears `C:\Users\…` in half at the drive letter. The refusal then told them their
-  // `claude.cmd` was "not on PATH as an executable file" and printed a PATH that had been mangled on the
-  // way to saying so. A true statement about a false premise, and a wild-goose chase for the reader.
+  // INSTALL.md promises a native-Windows run "refuses at preflight". Nothing implemented it, so what a
+  // Windows user actually got was a PATH walk that split on ":", tore `C:\Users\…` in half at the drive
+  // letter, and reported their `claude.cmd` as "not on PATH". The walk now splits on the platform's own
+  // delimiter, and the refusal stands anyway, because its real grounds were never the lookup: a stage runs
+  // as its own process group and is stopped by signalling that group, an immediate stop identifies the
+  // process from /proc or ps, and the write-boundary hook is quoted for a POSIX shell. Native Windows has
+  // none of that, and where the program is found changes none of it.
   //
-  // This fires FIRST for that reason: any message mentioning PATH on win32 is misleading whatever else
-  // it says, because the value it quotes has already been destroyed by the split.
+  // This fires FIRST so that no message about a PATH reaches a reader whose platform is the answer.
   //
   // `platform` is injectable so the refusal is testable off win32 — the population this protects is the
   // one that cannot run this suite to find out.
   if (platform === "win32") {
-    throw new Error("[preflight] this engine does not run on native Windows. Stage subprocesses are spawned "
-      + "with POSIX path and process semantics, and the PATH resolution below splits on \":\", which cuts a "
-      + "Windows path at its drive letter — so any message it produced about your engine binary would be "
-      + "about a mangled path. Run it under WSL2, or in the devcontainer (.devcontainer/), where the "
-      + "documented install path applies unchanged (#1149 item 3).");
+    throw new Error("[preflight] this engine does not run on native Windows. Each stage runs as its own process "
+      + "group and is stopped by signalling that group, which native Windows cannot do, so a stopped stage would "
+      + "leave the tools it started still running. Run it under WSL2, or in the devcontainer (.devcontainer/), "
+      + "where the documented install path applies unchanged.");
   }
   const engine = (env.CLEAROTRON_AI || DEFAULT_ENGINE_ID).trim().toLowerCase();
   const spec = ENGINE_BINARIES[engine];
@@ -2033,24 +2282,38 @@ export function preflightEngineBinary(env = process.env, { platform = process.pl
   // `envFrom` is therefore BELT-AND-BRACES, not the repair: it makes this site correct on its own terms
   // rather than correct because something upstream normalised the environment first — a coupling
   // nothing at this site declares and nothing here could notice breaking.
-  const bin = String(envFrom(env, spec.env) ?? "").trim() || spec.fallback;
-  const where = `${spec.env}${envFrom(env, spec.env) ? "" : ` (unset — defaulting to "${spec.fallback}")`}`;
-
-  if (bin.includes("/") && !isAbsolute(bin)) {
+  const r = resolveEngineProgram(engine, { env, enginesDir, wsl, onWindowsDrive });   // injectable for the reason it gives
+  const bin = r.bin;
+  const setTo = String(envFrom(env, spec.env) ?? "").trim();
+  const where = `${spec.env}${r.explicit ? "" : setTo
+    ? ` (set to its default "${spec.fallback}": the one on PATH, then the copy Clearotron installed)`
+    : ` (unset — defaulting to "${spec.fallback}" on PATH, then the copy Clearotron installed)`}`;
+
+  if (r.relative) {
     throw new Error(`[preflight] ${where} is the RELATIVE path "${bin}", which cannot work: the engine is `
       + "spawned with the RUN DIRECTORY as its cwd (#524), not the repo, so a relative command is looked "
       + `for inside the run. Give an absolute path — e.g. ${join(REPO_ROOT, bin)} — or a bare name on PATH.`);
   }
 
-  const resolved = resolveExecutable(bin, env);
-  if (!resolved) {
+  if (!r.resolved) {
+    const passedOver = r.rejected.map((x) => `${x.path} is ${x.why}`).join("; ");
+    // "None installed" only when none was. An installed copy that cannot run is named in the passed-over
+    // list with its reason, and the claim beside it would send the reader to install it again.
+    const installedRefused = r.rejected.some((x) => x.source === "installed");
+    // Under WSL the Windows copies on the appended PATH were passed over on purpose, and the reader's own
+    // `which` still prints them, so the refusal names them and says why.
+    const windows = r.skipped.length
+      ? `. Passed over because they sit on a Windows drive, and a Windows build cannot run a stage here: ${r.skipped.join(", ")}` : "";
     throw new Error(`[preflight] the ${engine} engine cannot run: ${where} names "${bin}", which is `
       + (bin.includes("/")
-        ? "not an executable file (it is missing, is a directory, or lacks the execute bit for this user)"
-        : `not on PATH as an executable file (PATH=${env.PATH || "(empty)"})`)
+        ? (r.rejected[0]?.why ?? "not an executable file (it is missing, is a directory, or lacks the execute bit for this user)")
+        : `not on PATH as an executable file (PATH=${env.PATH || "(empty)"})`
+          + (r.explicit || installedRefused ? "" : ", and Clearotron has not installed one")
+          + (passedOver ? `. Passed over: ${passedOver}` : "")
+          + windows)
       + ". Every stage of a run spawns it, so the run is refused now rather than at the first stage.");
   }
-  return { engine, binEnv: spec.env, bin, resolved };
+  return { engine, binEnv: spec.env, bin, resolved: r.resolved, source: r.source, version: r.version };
 }
 
 // Report which deployment hostnames are unset, so the runner can say so out loud at activation.
@@ -2119,7 +2382,7 @@ export function preflightDeploymentUrls(env = process.env) {
 const RUN_FREE_BYTES_FLOOR = 500e6;
 
 /** Nearest ancestor of `p` that exists. statfs needs a real path, and on a first run NONE of
- *  …/workspace-<agent>/studio/prelim-search exists yet — measuring the leaf would throw ENOENT and land
+ *  …/workspace-<agent>/studio/clearance-search exists yet — measuring the leaf would throw ENOENT and land
  *  in the unmeasurable branch, which would disable this check on exactly the fresh installs it is for. */
 function nearestExistingDir(p) {
   let dir = p;
@@ -2161,7 +2424,7 @@ export function freeSpacePlan({ freeBytes, needBytes, path }) {
  * shape of run that can proceed without one, so there is no exemption to write.
  *
  * MEASURES THE FILESYSTEM THAT WILL HOLD THE BYTES, which is the workspace root's, not `/` and not the
- * repo's. Run directories live under config.studioRoot (…/workspace-<agent>/studio/prelim-search); the
+ * repo's. Run directories live under config.studioRoot (…/workspace-<agent>/studio/clearance-search); the
  * published report goes to poolRoot and the packet to outboxDir, which on a laptop are different
  * filesystems again. A check aimed at the wrong mount passes while the right one is full, which is the
  * silent-pass this exists to prevent — so the path is taken from the caller's studioRoot when the runner