clearotron 0.4.0-beta.0 → 0.4.0-beta.2

package/driver/driver.config.mjs

@@ -7,13 +7,14 @@
 // 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, basename, isAbsolute, delimiter } from "node:path";
+import { join, dirname, basename, isAbsolute, win32 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 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 { sepClass, notSepClass, hasSep } from "../shared/path-seps.mjs";   // a Windows path is built with "\"
 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"; 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
 
@@ -50,8 +51,9 @@ const home = () => homedir();
 // CLEAROTRON_SKILLS_STORE_STRICT (skills-store-provenance.mjs). There was a fourth, CLEAROTRON_SELFTEST_PATHS_ONLY,
 // and it died with driver/selftest.mjs. The first two are here because they LIED, the third because it was written
 // after this note and a new gate has no excuse to spell itself a fifth way. Roughly
-// FIVE gates are still inline `!== "0"`: CLEAROTRON_BAND_TRUTH_GATE, CLEAROTRON_REGISTER_GAP_CLAMP,
-// CLEAROTRON_RECALL_TRIPWIRE, CLEAROTRON_WARM_RETRY, CLEAROTRON_SATPROBE_CODESIDE. Those are CORRECT — `0`
+// FOUR gates are still inline `!== "0"`: CLEAROTRON_BAND_TRUTH_GATE, CLEAROTRON_REGISTER_GAP_CLAMP,
+// CLEAROTRON_WARM_RETRY, CLEAROTRON_SATPROBE_CODESIDE. (CLEAROTRON_RECALL_TRIPWIRE was a fifth, and went
+// with the recall store on 2026-09-24.) Those are CORRECT — `0`
 // disables each, which is what they document — they simply do not accept `off`/`false`/`no`.
 //
 // IT WAS TEN. Three went with their knobs: CLEAROTRON_TAINT_CHAIN, CLEAROTRON_XCHECK and
@@ -60,9 +62,10 @@ const home = () => homedir();
 // rollback. The ones that remain stay because the test corpus sets them, and two of them are how a
 // hermetic suite keeps from dialling a real provider.
 //
-// CLEAROTRON_RECALL_PROBES was nearly a fourth and is the cautionary one: five test files disable it with
-// `||=`, and the census that cleared it for deletion looked for a plain `=` after the name. Deleting
-// it armed the probes in all five. A measurement that cannot see a form reports clean.
+// CLEAROTRON_RECALL_PROBES (also gone with the recall store) was nearly a fourth and is the cautionary
+// one: five test files disabled it with `||=`, and the census that cleared it for deletion looked for a
+// plain `=` after the name. Deleting it armed the probes in all five. A measurement that cannot see a form
+// reports clean.
 //
 // Anyone extending the accessors to the rest must update the note in .env.example's conventions header
 // in the same change — a header that claims more coverage than the code has is the defect this whole
@@ -304,8 +307,8 @@ export const config = {
 
   // ── Per-agent paths ───────────────────────────────────────────────────────
   // A clearotron job is enqueued into the FORWARDING agent's OWN workspace queue (that agent's `write` tool
-  // is sandboxed there), and we run the whole pipeline as that same agent so the reply tool
-  // (`clawdi_send_<user>`), the run-dir, and the agent's memory all line up. The queue LOCATION therefore
+  // is sandboxed there), and we run the whole pipeline as that same agent so the reply tool,
+  // the run-dir, and the agent's memory all line up. The queue LOCATION therefore
   // encodes the agent identity — the driver derives {agentId, studioRoot} from where it claimed the job,
   // so there is no forwarder→agent map to keep in sync. Delivery is still centralized (poolRoot below).
   // The per-agent directory prefix under workspaceRoot. Inherited as a bare `workspace-` layout; now ONE
@@ -339,9 +342,10 @@ export const config = {
     return join(this.studioRootForAgent(agentId), "archive");
   },
   // …/<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/${STUDIO_SEGMENT_RE}/queue/?$`).exec(qdir);
+  // spelling of the segment, because an install keeps the one it has, and either separator on Windows.
+  agentIdFromQueueDir(qdir, { platform = process.platform } = {}) {
+    const [S, N] = [sepClass(platform), notSepClass(platform)];
+    const m = new RegExp(`(?:^|${S})${this.workspacePrefixRe}(${N}+)${S}studio${S}${STUDIO_SEGMENT_RE}${S}queue${S}?$`).exec(qdir);
     return m ? m[1] : null;
   },
   // Every agent workspace's clearotron queue. The systemd `.path` watches these and the runner drains ALL of
@@ -369,38 +373,45 @@ export const config = {
         }
       }
     } 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.
+    // THE INSTALL'S OWN QUEUE IS ALWAYS WATCHED, AND IT USED TO BE ONE PARTICULAR AGENT'S. `this.queueDir`
+    // was `queueDirForAgent("<the old default>")` — a LITERAL, not `defaultAgent` — so every deployment,
+    // however configured, watched that one directory as well as its own. It was back-compat for a real
+    // legacy queue, and its own note said removing it was a SEQUENCED MIGRATION rather than an edit:
+    // drain that queue, or name it explicitly with CLEAROTRON_QUEUE_DIR, and only then drop the literal.
     //
-    // `this.queueDir` is `queueDirForAgent("clawdi")` — a LITERAL, not `defaultAgent` — so every
-    // 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.
+    // BOTH PRECONDITIONS WERE MEASURED BEFORE IT WENT (2026-09-27). Every install that runs a clearance
+    // unit sets CLEAROTRON_QUEUE_DIR, and holds nothing in that legacy directory. One retired deployment
+    // still has 23 files there; classified against this product's own live-marker rule, NONE is live —
+    // ten results, ten done markers and three hand-made probe files, newest a month old — that deployment
+    // runs no clearance unit, and the path resolved per-install anyway, so no other deployment could ever
+    // have reached it.
     //
-    // WHY IT STAYS. It is back-compat for a real legacy queue that still holds work. Dropping the
-    // literal stops the deployment that owns that queue draining it — silently, because an unwatched
-    // queue looks exactly like an empty one. Removing it is therefore a SEQUENCED MIGRATION (drain the
-    // legacy queue, or name it explicitly via CLEAROTRON_QUEUE_DIR, then drop this), not an edit: it needs
-    // the box, and no repository-only change can do it safely.
-    //
-    // Written down because a sweep of this platform name will find it again and read it as residue.
-    // It is not residue; it is the one instance whose removal has a cost outside this repository.
+    // What remains is the honest version of what the literal was for: the queue of the agent this
+    // install actually runs as, appended so a deployment whose own queue is not among the scanned
+    // workspaces still drains it.
     const canonical = this.queueDir;
     if (!dirs.includes(canonical)) dirs.push(canonical);
     return [...new Set(dirs)];                  // CLEAROTRON_QUEUE_DIR may equal a scanned workspace queue
   },
 
-  // Back-compat defaults for the legacy agent (selftest / docs / CLI without a derived agent), pinned
-  // for the reason written at `queueDirs` above. Per-run code uses the *ForAgent helpers above with the
-  // agent derived from the claimed queue dir.
+  // Defaults for a caller with no derived agent (selftest, docs, a CLI invocation): the agent this
+  // install runs as, which is what CLEAROTRON_DEFAULT_AGENT says and `localagent` when it says nothing.
+  // They named one particular agent as a literal until 2026-09-27; see `queueDirs` above for what that
+  // was for and what was measured before it went. Per-run code uses the *ForAgent helpers with the agent
+  // derived from the claimed queue dir, and is unaffected either way.
+  //
+  // THIS MOVES NO PATH ON A DEPLOYMENT THAT SETS ITS OWN AGENT, which is the point: the two installs
+  // whose default agent is the id this replaced resolve to exactly the directories they resolved to
+  // before, because that is what their own configuration says. An install that sets nothing moves to its
+  // own default, where its runs already are.
   get studioRoot() {
-    return this.studioRootForAgent("clawdi");
+    return this.studioRootForAgent(this.defaultAgent);
   },
   get queueDir() {
-    return this.queueDirForAgent("clawdi");
+    return this.queueDirForAgent(this.defaultAgent);
   },
   get archiveRoot() {
-    return this.archiveRootForAgent("clawdi");
+    return this.archiveRootForAgent(this.defaultAgent);
   },
 
   // Delivery pool: the deterministic publish step writes report.html + audit.xlsx here; Caddy serves it
@@ -617,20 +628,20 @@ export const config = {
   //
   // 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/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:
-  //
-  //     CLEAROTRON_DEFAULT_AGENT=clawdi
-  //     CLEAROTRON_GATHER_AGENT=clawdi
+  // before this default changed keeps its runs under the id it was created with, and must set both
+  // CLEAROTRON_DEFAULT_AGENT and CLEAROTRON_GATHER_AGENT to that id — both, because the gather servers
+  // read their own variable. Unpinned, such an install starts a fresh empty workspace and its existing
+  // runs read as absent rather than as an error.
   //
-  // Unpinned, such an install starts a fresh empty workspace and its existing runs read as absent
-  // rather than as an error. Said again where upgrades are described (INSTALL.md, ops runbook).
+  // THE ID IS NO LONGER WRITTEN DOWN ANYWHERE FOR THEM (ruling 563, 2026-09-27): what this tree knows is
+  // that the id is a path segment, not which id any particular install was created with. An operator who
+  // needs it reads the name of the workspace directory their runs are in. The release note for that
+  // ruling carries the instruction; this comment carries the reason.
   //
-  // THE ID IS ALSO A KEY, not only a path segment. `AGENT_WHATSAPP` in stages.mjs is keyed by agent
-  // id, so the demo roster has to carry this value or the reference deployment resolves no operator
-  // number and the hole reads as "no copy configured" rather than as a miss. Both ids are in that
-  // roster for the same reason the pin above exists. (The roster stays one line: 32 backlog rows
-  // cite line numbers in stages.mjs, so a comment added there repoints all of them.)
+  // THE ID IS ALSO A KEY, not only a path segment. `AGENT_WHATSAPP` in stages.mjs is keyed by agent id,
+  // so a deployment whose agent is not in that roster resolves no operator number and the hole reads as
+  // "no copy configured" rather than as a miss. (The roster stays one line: 32 backlog rows cite line
+  // numbers in stages.mjs, so a comment added there repoints all of them.)
   get defaultAgent() { return process.env.CLEAROTRON_DEFAULT_AGENT || "localagent"; },
 
   // Per-stage retry budget (fresh session key per retry).
@@ -668,13 +679,12 @@ export const config = {
 // Owner's ruling, 2026-09-23: record the tier. What a run asked for is a tier, what it was served is
 // recorded separately and already is, and the report names the model that ran — none of that moves.
 //
-// WHAT IT COSTS, RULED ON AND ACCEPTED RATHER THAN DISCOVERED LATER. Per-model totals are keyed on what
-// was ASKED for, and the direct-API lanes must name a version because they call the API rather than the
-// program — the API takes model ids, not tier words. So one model reached by both routes now lands in
-// two buckets: `anthropic/claude-haiku` from a stage, `anthropic/claude-haiku-4-5` from those lanes.
-// That is a real split in a per-model total and it was accepted with the ruling: the two are genuinely
-// different requests, and keying the totals on what actually SERVED each turn is the change that would
-// fix it properly, which is larger than this and not what was ruled.
+// WHAT IT COSTS, RULED ON AND ACCEPTED RATHER THAN DISCOVERED LATER. A stage's rows are keyed on the
+// tier it asked for, and a native-language lane's rows on the model that served them (`modelKey` in
+// tokens.mjs). So one model reached both ways lands in two buckets: `anthropic/claude-haiku` from a
+// stage, `anthropic/claude-haiku-4-5` from a native-language lane. That is a real split in a per-model
+// total and it was accepted with the ruling; keying every row on what served it is the change that
+// would close it, which is larger than this and not what was ruled.
 export const MODELS = {
   haiku: "anthropic/claude-haiku",
   sonnet: "anthropic/claude-sonnet",
@@ -1319,7 +1329,15 @@ export const PROVIDERS = {
         // The office's own numbers come off the full record Signa returns on search, through the
         // provider's own normaliser, so publish can address the office's page for each filing
         // (publish/office-record-links.mjs) instead of showing the handle.
-        return { ok: true, records: (Array.isArray(p.results) ? p.results : []).map((row) => {
+        //
+        // THE TOTAL RIDES THE SAME ANSWER and is carried, not dropped: `include_total` puts the register's
+        // own count for this exact question on every search, so the listing of a term already holds the
+        // figure the count lane would ask for separately. An approximation stays one: no number in
+        // `total`, the floor beside it — the count lane's rule, unchanged.
+        return { ok: true,
+          total: Number.isFinite(p.total_hits) ? p.total_hits : null,
+          ...(p.total_approximate === true ? { approximate: true, floor: Number.isFinite(p.total_floor) ? p.total_floor : null } : {}),
+          records: (Array.isArray(p.results) ? p.results : []).map((row) => {
           const rec = row?.raw && typeof row.raw === "object" ? core.normalizeRecord(row.raw, row.office || null) : null;
           return {
             record_id: row?.record_id ?? null,
@@ -1660,12 +1678,16 @@ export function activeProvider(env = null) {
 
 
 // ── Research providers (Phase 2a, knockout lane) — the same lazy-import + cred-guard idiom as
-// PROVIDERS, for CODE-side research calls (no model in the data path). The knockout sweep's live
-// executor; tests inject their own, the dev instance uses CLEAROTRON_KNOCKOUT_SWEEP_FIXTURES. Knobs:
-//   PERPLEXITY_API_KEY                — required for live sweeps (absent ⇒ every call degrades, loud)
-//   CLEAROTRON_KNOCKOUT_PRESET            — perplexity preset (default "pro-search"; "deep-research" = deeper/costlier)
-//   CLEAROTRON_KNOCKOUT_SWEEP_FIXTURES    — dir of <mark-kebab>.md canned payloads ($0 dev/e2e)
+// PROVIDERS, for CODE-side research calls (no model in the data path). The knockout's live executors:
+// `grid` runs one mark's web search as a dictated grid, `research` asks one question (the owner lookups).
+// Tests inject their own, the dev instance uses CLEAROTRON_KNOCKOUT_SWEEP_FIXTURES. Knobs:
+//   PERPLEXITY_API_KEY                — required for live calls (absent ⇒ the web half is skipped, loud)
+//   CLEAROTRON_KNOCKOUT_SWEEP_FIXTURES    — dir of canned answers ($0 dev/e2e): <mark-kebab>.grid.json, the
+//                                           grid program's printed ledger for a mark, and <mark-kebab>.md,
+//                                           the answer to a question asked about that mark
 //   CLEAROTRON_KNOCKOUT_MODEL             — LLM override for the frame/assess turns (default opus)
+// The preset and the reasoning setting are not knobs: they are pinned in stages-knockout.mjs, so no
+// environment can quietly move them.
 export const RESEARCH_PROVIDERS = {
   perplexity: {
     // The vendor's own name, for the staff config page's provider inventory (config-inventory.mjs).
@@ -1689,8 +1711,11 @@ export const RESEARCH_PROVIDERS = {
         const body = core.buildRequestBody({ task, preset });
         const data = await core.callAgentAPI(process.env.PERPLEXITY_API_KEY, body, { retries: core.retriesForPreset(preset) });
         const text = core.formatResponse(data, preset);
-        if (!text || !String(text).trim()) return { ok: false, cause: "empty research response" };
-        return { ok: true, text: String(text), bytes: Buffer.byteLength(String(text)), tookMs: Date.now() - started };
+        // The searches behind the answer, kept for the caller to write into the run: the answer alone
+        // cannot say which pages were retrieved.
+        const raw = core.rawResultItems(data);
+        if (!text || !String(text).trim()) return { ok: false, cause: "empty research response", raw };
+        return { ok: true, text: String(text), bytes: Buffer.byteLength(String(text)), tookMs: Date.now() - started, raw };
       } catch (e) {
         // OUTAGE-SHAPED OR NOT — the caller cannot tell from prose, so say it here.
         //
@@ -1716,6 +1741,38 @@ export const RESEARCH_PROVIDERS = {
         };
       }
     },
+    /**
+     * ONE DICTATED GRID, THROUGH THE CLEARANCE GRID'S OWN FUNCTIONS: the program task built from the spec,
+     * the sandbox call, and the capture that reconciles what the program printed against every cell the
+     * spec asked for. Nothing is summarised; the ledger is what came back.
+     *
+     * The outage rule is `research`'s, for the same reason: 429 and 5xx park, anything else is loud.
+     */
+    async grid(spec, { preset = "pro-search", reasoning = null } = {}) {
+      if (!process.env.PERPLEXITY_API_KEY) return { ok: false, cause: "PERPLEXITY_API_KEY absent from driver env" };
+      let core;
+      try { core = await import("../providers/perplexity/src/core.js"); }
+      catch (e) { return { ok: false, cause: `perplexity core unavailable: ${e.message}` }; }
+      const started = Date.now();
+      try {
+        const body = core.buildRequestBody({ task: core.buildGridProgramTask(spec), preset, enableSandbox: true, reasoning });
+        const data = await core.callAgentAPI(process.env.PERPLEXITY_API_KEY, body, { retries: core.retriesForPreset(preset) });
+        const raw = core.rawResultItems(data);
+        const cap = core.captureGridFromResponse(data, spec);
+        if (!cap.ok) return { ok: false, cause: `grid: ${String(cap.error ?? "capture failed").slice(0, 200)}`, raw, tookMs: Date.now() - started };
+        return { ok: true, ledgerJson: cap.ledgerJson, present: cap.present, requested: cap.requested, missing: cap.missing.length,
+          bytes: Buffer.byteLength(cap.ledgerJson), tookMs: Date.now() - started, raw };
+      } catch (e) {
+        const status = Number.isInteger(e?.status) ? e.status : null;
+        return {
+          ok: false,
+          cause: `grid call threw: ${String(e?.message ?? e).slice(0, 200)}`,
+          status,
+          outage: status === 429 || (status >= 500 && status <= 599),
+          tookMs: Date.now() - started,
+        };
+      }
+    },
   },
 };
 
@@ -2024,9 +2081,10 @@ export const ENGINE_BINARIES = {
     // 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
-    // untouched, and that inheritance is the whole mechanism (armed in engine.anthropic.test.mjs). The wizard
+    // prints a long-lived token; the stage subprocess env is a list (engine/engine-env.mjs) that carries the
+    // vendor's own `CLAUDE_*` names — the API key is the one name it keeps only under `api-key` — so a token
+    // in the env file reaches the CLI untouched, and that is the whole mechanism (armed in
+    // engine.anthropic.test.mjs). The wizard
     // captures it by paste: the vendor's stream layout is not ours to guess at, and a paste works
     // whatever it prints where.
     headless: { cmd: "claude setup-token", tokenEnv: "CLAUDE_CODE_OAUTH_TOKEN" },
@@ -2171,7 +2229,17 @@ export function engineAdapterSpecifier(engine) {
 /** 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; } };
+// ON WINDOWS THE EXECUTE BIT DOES NOT EXIST: `X_OK` there answers whether the file exists, so npm's
+// extensionless `claude` shim, a shell script Windows cannot start, passed this check and the spawn failed
+// with ENOENT (seen on a real Windows run, 2026-09-09). There a program is what Windows starts itself, an
+// `.exe` or `.com`, or a JavaScript file, which runs through the Node running now (engine/engine-spawn.mjs).
+const WINDOWS_PROGRAM = /\.(?:exe|com|[cm]?js)$/i;
+const isExecFile = (p, platform = process.platform) => {
+  try {
+    if (!statSync(p).isFile()) return false;
+    return platform === "win32" ? WINDOWS_PROGRAM.test(p) : (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; } };
 
@@ -2229,9 +2297,52 @@ function installedProgram(spec, root) {
   return rel ? join(dir, rel) : null;
 }
 
+/**
+ * PATH as Windows spells it. Windows names are not case-sensitive, and Node copies the environment with
+ * the case the system gave it, which is `Path`. A lookup of `PATH` alone reads nothing there.
+ */
+function pathOf(env, platform) {
+  if (platform !== "win32") return env.PATH;
+  const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH");
+  return key ? env[key] : undefined;
+}
+
+/**
+ * The program a PATH directory holds under `name` on Windows, or null.
+ *
+ * WINDOWS FINDS A PROGRAM BY ITS EXTENSION, in the order PATHEXT lists them, so `claude` is `claude.exe`
+ * or `claude.cmd` and never the extensionless file. An `.exe` or `.com` is the program itself: the
+ * vendor's own installer puts `claude.exe` on PATH. A `.cmd` or `.bat` is npm's shim for a global
+ * install, and Node refuses to start a batch file without a shell. So the shim is read as what it stands
+ * for: the vendor's package in `node_modules` beside it, and the program that package's `bin` names. A
+ * name that already ends in one of those extensions, as a setting of `claude.exe` does, is looked for as
+ * written, as Windows looks for it.
+ */
+function windowsProgramIn(dir, name, spec, env) {
+  const key = Object.keys(env).find((k) => k.toUpperCase() === "PATHEXT");
+  const exts = String((key && env[key]) || ".COM;.EXE;.BAT;.CMD").split(";").map((x) => x.trim().toLowerCase())
+    .filter((x) => [".com", ".exe", ".bat", ".cmd"].includes(x));
+  const own = /\.(?:com|exe|bat|cmd)$/i.exec(name)?.[0]?.toLowerCase();
+  const tries = own ? [[name, own]] : exts.map((ext) => [`${name}${ext}`, ext]);
+  for (const [file, ext] of tries) {
+    const p = join(dir, file);
+    let found = false;
+    try { found = statSync(p).isFile(); } catch { /* not here */ }
+    if (!found) continue;
+    if (ext === ".exe" || ext === ".com") return p;
+    return installedProgram(spec, dir);
+  }
+  return 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)" };
+/** Why a candidate the lookup cannot start is refused, in the platform's own terms: Windows has no execute bit. */
+const notStartable = (platform) => platform === "win32"
+  ? "not a program Windows can start (it is missing, is a folder, or is not an .exe file)"
+  : "not an executable file (it is missing, is a directory, or lacks the execute bit for this user)";
+
+function engineCandidate(p, spec, platform = process.platform) {
+  if (!isExecFile(p, platform)) return { ok: false, why: notStartable(platform) };
   const own = owningPackage(p);
   const vendor = Boolean(spec.package) && own?.name === spec.package;
   if (vendor && !runsDirectly(p)) {
@@ -2258,7 +2369,8 @@ function engineCandidate(p, spec) {
  * 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 } = {}) {
+export function resolveEngineProgram(engine, { env = process.env, enginesDir = undefined, wsl = null, onWindowsDrive = null,
+  platform = process.platform } = {}) {
   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,
@@ -2270,14 +2382,14 @@ export function resolveEngineProgram(engine, { env = process.env, enginesDir = u
   const underWsl = wsl ?? isWsl({ env });
   const onDrive = onWindowsDrive ?? ((p) => ON_A_WINDOWS_DRIVE.test(p));
   const take = (p, source) => {
-    const c = engineCandidate(p, spec);
+    const c = engineCandidate(p, spec, platform);
     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; }
+  if (out.explicit && hasSep(out.bin, platform)) {
+    if (!(platform === "win32" ? win32.isAbsolute(out.bin) : isAbsolute(out.bin))) { out.relative = true; return out; }
     out.windowsShim = underWsl && onDrive(out.bin);
     take(out.bin, "explicit");
     return out;
@@ -2287,9 +2399,9 @@ export function resolveEngineProgram(engine, { env = process.env, enginesDir = u
   // 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;
+  for (const dir of String(pathOf(env, platform) ?? "").split(platform === "win32" ? ";" : ":").filter(Boolean)) {
+    const p = platform === "win32" ? windowsProgramIn(dir, out.bin, spec, env) : join(dir, out.bin);
+    if (!p || !isExecFile(p, platform)) 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.
@@ -2313,26 +2425,11 @@ export function resolveEngineProgram(engine, { env = process.env, enginesDir = u
  * registry's.
  */
 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". 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 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. 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.");
-  }
+  // NATIVE WINDOWS RUNS. This door refused it by name, on three grounds, and each now has a Windows
+  // answer: a stage is stopped as a process tree rather than a group (engine/engine-spawn.mjs), the
+  // immediate stop reads start times through PowerShell (claim-liveness.mjs), and the write-boundary hook
+  // runs with no shell (anthropic-agent.mjs, writeBoundarySettings). `platform` stays a parameter, because
+  // the lookup below answers by it.
   const engine = (env.CLEAROTRON_AI || DEFAULT_ENGINE_ID).trim().toLowerCase();
   const spec = ENGINE_BINARIES[engine];
   if (!spec) return { engine, binEnv: null, bin: null, resolved: null };   // selectEngine owns this refusal
@@ -2352,7 +2449,7 @@ 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 r = resolveEngineProgram(engine, { env, enginesDir, wsl, onWindowsDrive });   // injectable for the reason it gives
+  const r = resolveEngineProgram(engine, { env, enginesDir, wsl, onWindowsDrive, platform });   // 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
@@ -2361,7 +2458,7 @@ export function preflightEngineBinary(env = process.env, { platform = process.pl
 
   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 "
+      + "spawned with the RUN DIRECTORY as its cwd, 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.`);
   }
 
@@ -2375,9 +2472,9 @@ export function preflightEngineBinary(env = process.env, { platform = process.pl
     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("/")
-        ? (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)"})`
+      + (hasSep(bin, platform)
+        ? (r.rejected[0]?.why ?? notStartable(platform))
+        : `not on PATH as an executable file (PATH=${pathOf(env, platform) || "(empty)"})`
           + (r.explicit || installedRefused ? "" : ", and Clearotron has not installed one")
           + (passedOver ? `. Passed over: ${passedOver}` : "")
           + windows)

package/driver/e2e/README.md

@@ -37,7 +37,7 @@ other, which is the only proof available where no gold set exists.
 
 A knockout scenario graded against a similar-marks sheet scores a **structural zero**. Knockout answers
 one narrow question — how many register filings exist for the exact mark and its close variations in the
-named classes — and never retrieves similar marks, so a lawyer's list of TIKI PUNCH and TIKI TROPICS is
+named classes — and never retrieves similar marks, so a lawyer's list of WAVO PUNCH and WAVO TROPICS is
 unreachable by construction. R3 and R4 scored 0/8 and 0/9 on both free-tier and clarivate on the same
 day with the same engine, which measured the pairing rather than the engine.
 

package/driver/effective-scope.mjs

@@ -90,7 +90,7 @@ export const jobJurisdictions = (job) =>
 /**
  * — WHAT THE ACCOUNT'S DEFAULT TERRITORIES MAY SAY TO THE MATTER FRAME.
  *
- * Returns 0 or 1 prompt lines, spread into the frame's message by stages.mjs.
+ * Returns 0 to 2 prompt lines, spread into the frame's message by stages.mjs.
  *
  * THE RULE IS THE LADDER'S RULE, which is why it lives beside the ladder rather than in the prompt: a
  * default FILLS AN ABSENT SCOPE and never widens a stated one. `resolveTerritories` below has always
@@ -139,9 +139,65 @@ export function defaultTerritoryState(profile) {
   return { kept, unrecognized: dropped };
 }
 
+/**
+ * THE MAJOR MARKETS: where a crowded result is narrowed when neither the order nor the account names a
+ * market and the customer's field and brand point nowhere in particular. One list, and the manuals that
+ * name the major markets name these (ruled 2026-09-26: a generic customer narrows by the order's classes
+ * and the major markets). Codes as the territory vocabulary writes them, so GB is the UK.
+ */
+export const MAJOR_MARKETS = Object.freeze(["US", "EU", "GB", "CN", "JP"]);
+
+/**
+ * WHERE A CROWDED RESULT IS NARROWED BY MARKET, in the ruled order (2026-09-26), as far as the driver can
+ * know it. An order with a territorial scope (its own countries, or the account's defaults filling an
+ * absent one) narrows within that scope, one market at a time: nothing outside it was ordered. A worldwide
+ * order, or one with no territory at all, narrows to the customer's priority markets (the account's
+ * defaults); else to the markets the customer's field and brand point to, which is the reading step's
+ * judgment; else to the major markets.
+ * `{ scope, priorities, major }` — arrays of codes; `scope` empty means worldwide. PURE.
+ */
+export function narrowingMarkets(job, profile) {
+  const { jurisdictions, geographyMode } = resolveTerritories(job, profile);
+  const scope = geographyMode === "worldwide" ? [] : jurisdictions.map((t) => String(t).trim()).filter(Boolean);
+  if (scope.length) return { scope, priorities: [], major: [] };
+  return { scope: [], priorities: defaultTerritoryState(profile).kept, major: [...MAJOR_MARKETS] };
+}
+
+/**
+ * THE NARROWING ORDER, as the register reading step is told it (ruled 2026-09-26): goods and class
+ * first, then the markets in turn, with the markets the driver knows filled in. One line. PURE.
+ */
+export function narrowingOrderLine(job, profile, inScopeClasses = null) {
+  const { scope, priorities, major } = narrowingMarkets(job, profile);
+  const markets = scope.length
+    ? `one question per market of the order's scope (${scope.join(", ")}); nothing outside it was ordered`
+    : `one question per market: ${[
+      priorities.length ? `the customer's priority markets (${priorities.join(", ")})` : "",
+      "the markets the customer's field and brand point to (judge them from the matter frame)",
+      `the major markets (${major.join(", ")})`,
+    ].filter(Boolean).join(", else ")}`;
+  return `NARROWING A CROWD, in this order: first the goods and the classes, the client's goods words in `
+    + `${inScopeClasses ? `the order's classes [${inScopeClasses}]` : "the order's classes"}, then the classes the crowding owners `
+    + `file in; still a crowd, then the markets, ${markets}. From the narrowed lists, read what a lawyer would raise. `
+    + `What was counted and not read stays on its coverage row with its count: set aside, never clean.`;
+}
+
 export function defaultJurisdictionsLine(job, profile) {
-  if (jobJurisdictions(job).length) return [];
   const { kept } = defaultTerritoryState(profile);
+  // THE ORDER'S SCOPE IN ONE LINE, and the account's defaults as the customer's PRIORITIES, never as the
+  // scope (ruled 2026-09-26). The ladder's first rung, which this line had never heard of: measured
+  // 2026-09-25, a worldwide search under an account with seven default territories was told "the request
+  // names none — apply these", framed as those seven, and its crowded identical-mark question was read
+  // in those seven only.
+  if (job?.geography?.mode === "worldwide") {
+    return [
+      "Order scope: worldwide (AUTHORITATIVE — every register question is asked worldwide; do NOT narrow the scope, and exclude no market for lying outside the customer's priority markets).",
+      ...(kept.length ? [`Customer priority markets (the account's default territories — where a crowded result is narrowed first; never the scope of this order): ${kept.join(", ")}.`] : []),
+    ];
+  }
+  // A named order's own countries are its scope and the first markets a crowd narrows to, so no default
+  // appears anywhere in its prompt.
+  if (jobJurisdictions(job).length) return [];
   return kept.length
     ? [`Customer-default jurisdictions that materially matter (the request names none — apply these): ${kept.join(", ")}.`]
     : [];