clearotron 0.3.2 → 0.3.3-beta.1

package/CONTRIBUTING.md

@@ -208,6 +208,18 @@ read at all.
 
 Branch, commit, open a PR. One change per PR.
 
+**Keep regenerated demo evidence in its own commit.** `demo/` holds captured runs. Regenerating them
+rewrites hundreds of thousands of lines, and a source diff inside that is a diff nobody reads — one
+release branch was 2,490 files and 632,089 changed lines, almost all of it evidence. So a commit that
+touches `demo/` touches nothing else, and `demo/MANIFEST.json` records what produced it:
+
+```
+node scripts/demo-evidence.mjs --apply     # in the same commit that regenerates the evidence
+git diff origin/main... -- . ':!demo'      # read a branch WITHOUT the generated evidence
+```
+
+CI checks the first line for you.
+
 The commit **body** is what gets read — not the title. State what changed, why this approach and
 what you rejected, and how to verify it. "How to verify" should be a command someone else can run.
 

package/INSTALL.md

@@ -115,6 +115,13 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
   **Installed is not usable.** `npx clearotron install` proves the engine can complete a turn before it
   writes anything, and `clearotron doctor --probe-engine` re-proves it on a configured box. Both
   spend one cheap turn; plain `doctor` spends nothing.
+
+  **The check covers tools.** Every search stage calls tools. On some machines codex's own sandbox
+  refuses every one of those calls while the turn reports success, so the check asks the engine to call
+  one tool and passes only when that call comes back. If it reports that codex refused it, set
+  `CLEAROTRON_CODEX_SANDBOX_BYPASS=1` in the environment file, or use `anthropic-agent`. The setting turns
+  off codex's own sandbox, so its tool calls run with the permissions of the user Clearotron runs as, as
+  the Anthropic engine's do; set it only where the check reports the refusal.
 - **A register credential**, and **`PERPLEXITY_API_KEY`**. Both are required for a real run and both
   fail closed at preflight — before a stage has spent, never at the grid after. The one exception is a
   Knockout search, which runs keyless: it returns register filing counts and states on the report that
@@ -429,6 +436,7 @@ CLEAROTRON_AI_BILLING=subscription       # `subscription` (OAuth, default) | `ap
 # ANTHROPIC_DEFAULT_OPUS_MODEL=...       # optional: hold the opus tier at one model (and _SONNET_, _HAIKU_, _FABLE_)
 # CLEAROTRON_AI=openai-agent             # …or the second adapter: headless `codex exec`
 # CLEAROTRON_CODEX_PATH=                 # only to force one copy (default: `codex` on PATH, then the copy setup installed)
+# CLEAROTRON_CODEX_SANDBOX_BYPASS=1      # only where setup or doctor reports that codex refused every tool call
 
 # ── Where this install keeps its data ──────────────────────────────────
 # REQUIRED. CLEAROTRON_REPORTS_DIR has NO default: unset, a run refuses and names it.

package/bin/onboard.mjs

@@ -98,7 +98,7 @@ import {
 // REGISTER_PROVIDER frozen at first import) is the one `preflightCandidate` below already cache-busts
 // around, and it is cache-busted whether or not this static import happened first.
 import { config, ENGINE_BINARIES, DEFAULT_ENGINE_ID, RESEARCH_PROVIDERS, SERP_PROVIDERS, resolveEngineProgram, ON_A_WINDOWS_DRIVE,
-  enginesFolder, engineInstallArgs, engineInstallCommand } from "../driver/driver.config.mjs";
+  enginesFolder, engineInstallArgs, engineInstallCommand, olderThanFloor } from "../driver/driver.config.mjs";
 import { resolveAuthMode, CLOUD_SWITCH, CLOUD_SETTINGS, CLOUD_SECRETS, cloudsSwitchedOn } from "../driver/engine/auth.mjs";
 import { isInsideCheckout } from "../shared/inside-checkout.mjs";   // — one copy of the rule, and it is testable
 import { packagedBuild as sharedPackagedBuild } from "../shared/packaged-build.mjs";   // — one reader of build-info.json, reachable from the driver
@@ -1105,6 +1105,25 @@ function programProblem(bin, named) {
   return null;
 }
 
+// WHAT A COPY BELOW THE FLOOR DOES TO THE MODELS WAS MEASURED ON CLAUDE ALONE (2026-09-22): it refuses the
+// newest model of a tier and serves the one before. Codex's floor records no such measurement, so an old
+// Codex is named by its version, the floor and the fix, and nothing is said about which model it runs.
+export const floorRefusesNewestModel = (eng) => Boolean(eng?.package) && eng.package === ENGINE_BINARIES["anthropic-agent"]?.package;
+
+/**
+ * What doctor and setup say after the version of a copy below the floor: what it costs, where that was
+ * measured, and the fix. ONE COPY FOR BOTH SCREENS, so the two cannot drift apart again (ruling 285).
+ *
+ * The fix follows where the copy came from. A copy Clearotron installed moves with `update`. Any other
+ * copy wins over one setup installs, by design, so installing another does not replace it: the fix is
+ * to update it, or to name a newer one in the engine's setting.
+ */
+export function belowFloorTail(eng, bin) {
+  const cost = floorRefusesNewestModel(eng) ? `The newest ${eng.product} models need a newer version. Searches run on an older model instead, or stop at the first step if they name the newest one exactly. ` : "";
+  const fix = bin?.source === "installed" ? `Update it with \`${invoke("update")}\`.` : `Update it, or set ${eng.env} to a newer copy.`;
+  return cost + fix;
+}
+
 /**
  * What setup found of one engine's program, as its menu row says it; "" when nothing was looked for. A copy
  * that cannot run is a problem, not an absence, and installing another is not always the fix, so the row
@@ -1113,7 +1132,14 @@ function programProblem(bin, named) {
  */
 export function foundWords(eng, bin) {
   if (!bin) return "";
-  if (bin.executable && !bin.relative) return bin.version ? `found on this computer (version ${bin.version})` : "found on this computer";
+  if (bin.executable && !bin.relative) {
+    // A COPY THAT RUNS IS NOT NECESSARILY ONE THIS BUILD CAN USE. Below the floor the program refuses
+    // the newest model of a tier and serves the one before it, so the row cannot say "found" and leave
+    // it there; it says which problem, and choosing the engine shows the fix, as the other problems do.
+    if (olderThanFloor(bin.version, eng.floor) === true)
+      return `problem: the copy of ${eng.product} here is version ${bin.version}; Clearotron needs ${eng.floor} or newer — choose it to see the fix`;
+    return bin.version ? `found on this computer (version ${bin.version})` : "found on this computer";
+  }
   const p = programProblem(bin, bin.explicit);
   if (p?.kind === "incomplete") return `problem: the copy of ${eng.product} here is incomplete and won't run — choose it to see the fix`;
   if (p?.kind === "setting") return `problem: this computer is set to use a copy of ${eng.product} that isn't there — choose it to see the fix`;
@@ -1129,6 +1155,12 @@ export function foundWords(eng, bin) {
  */
 export function cannotRunLine(eng, bin, setting = "") {
   const set = namedSetting(eng, setting);
+  // ANSWERED BEFORE THE REST, because a copy below the floor RUNS: it is executable, nothing rejected
+  // it, and every clause below is about a copy that cannot start. Left to them it would fall through to
+  // the general clause and be described as unusable, which sends the reader to look for a broken
+  // install they do not have. The fix here is a version, not a repair.
+  if (bin?.executable && !bin?.relative && olderThanFloor(bin.version, eng.floor) === true)
+    return `${eng.product} on this computer is version ${bin.version}. Clearotron needs ${eng.floor} or newer. ${belowFloorTail(eng, bin)}`;
   const p = programProblem(bin, set);
   if (p?.kind === "incomplete") return `The copy of ${eng.product} at ${p.path} is incomplete: its installation stopped before the program was added. Setup can install a working copy.`;
   if (p?.kind === "setting") return `This computer is set to use ${eng.product} at ${set}, and nothing there can run. Setup can install ${eng.product} and use that instead.`;
@@ -1761,10 +1793,26 @@ export async function runCheck() {
     const bin = resolveEngineBin(binSetting, { engine: engineId });
     // WHICH COPY, AND ITS VERSION, because the machine's own install and the one Clearotron installed
     // are both legitimate and behave differently: the first updates itself, the second moves with
-    // `clearotron update`. The version comes from the copy's own package.json when npm installed it;
-    // doctor spawns nothing to ask (a vendor's own native installer leaves no package.json to read).
+    // `clearotron update`. The version comes from the copy's own package.json when npm installed it.
+    //
+    // AND IS ASKED FOR WHEN THERE IS NONE TO READ, which is the ordinary case for a copy the machine
+    // installed by another route — a vendor's native installer leaves no package.json. Doctor used to
+    // stop there and print "version not read", which was honest and made the floor comparison below
+    // unanswerable on the route most machines take: this command could not tell an operator whether
+    // their own copy was new enough for the models a run asks for, which is the whole of what it was
+    // asked to check.
+    //
+    // It is the same short call setup's engine menu already makes (menuVersion): `--version`, two
+    // seconds, no session and no network. That is within "calls nobody" — what that promises is no
+    // provider call and no spend, not that nothing on this machine may be asked its own version.
+    const versionOf = (b) => {
+      if (b.version) return b.version;
+      if (!b.executable || b.relative || !b.path) return null;
+      try { return menuVersion(b.path) ?? null; } catch { return null; }
+    };
+    const seen = versionOf(bin);
     const copyWords = (b) => `${b.source === "installed" ? "the copy Clearotron installed"
-      : b.source === "explicit" ? `set in ${engSpec.env}` : "on PATH"}${b.version ? `, version ${b.version}` : ", version not read"}`;
+      : b.source === "explicit" ? `set in ${engSpec.env}` : "on PATH"}${seen ? `, version ${seen}` : ", version not read"}`;
     // ── NATIVE WINDOWS IS ANSWERED HERE, BEFORE ANY PATH IS RESOLVED OR REPORTED ──────────────────
     //
     // `resolveEngineBin` tests a candidate with `accessSync(X_OK)` and `isFile()`. Windows has no
@@ -1786,7 +1834,24 @@ export async function runCheck() {
     // and needs no engine, which is why four reports published on that same Windows box.
     const platformRefusal = platformEngineRefusal();
     if (platformRefusal) problem(platformRefusal);
-    else if (bin.executable && !bin.relative) ok(`${bin.path} — ${copyWords(bin)}`);
+    // ── AND WHETHER THAT COPY IS NEW ENOUGH FOR THE MODELS IT WILL BE ASKED FOR ──────────────────
+    //
+    // The floor governed the copy setup INSTALLS and nothing else, and a copy already on the machine
+    // wins over that one — so the route most machines actually take was the unchecked one. A program
+    // below the floor does not fail: it refuses the newest model of a tier and serves the previous one,
+    // and the search still finishes and the report still arrives. This is the cheap place to learn it.
+    //
+    // Three outcomes, because the comparison is three-valued: older, not older, and could not be
+    // compared. The last is said rather than passed over — doctor's own contract is that a failure to
+    // look is not a clean result — and it is the ordinary state for a copy the machine installed by
+    // another route, where there is no package.json to read and doctor spawns nothing to ask.
+    else if (bin.executable && !bin.relative && olderThanFloor(seen, engSpec.floor) === true)
+      problem(`${bin.path} — ${copyWords(bin)}. Clearotron needs ${engSpec.floor} or newer. ${belowFloorTail(engSpec, bin)}`);
+    else if (bin.executable && !bin.relative) {
+      ok(`${bin.path} — ${copyWords(bin)}`);
+      if (olderThanFloor(seen, engSpec.floor) === null)
+        info(`  Its version could not be checked against the ${engSpec.floor} Clearotron needs.`);
+    }
     // A copy that is there and cannot run is a broken install, not an absence: the vendor's placeholder
     // left by an install that skipped its step, most often. Named with the reason and the fix.
     else if (!binSet && bin.rejected?.length) problem(`no usable \`${engSpec.fallback}\`: ${bin.rejected.map((x) => `${x.path} is ${x.why}`).join("; ")}`);
@@ -1923,7 +1988,16 @@ export async function runCheck() {
         } catch (e) { return { say: problem, text: billingRefusalWords(String(e?.message ?? e)) }; }
       };
       const here = billingOf(engineId, envForResolve);
-      here.say(here.text);
+      // A TICK IS A CLAIM ABOUT SOMETHING THAT RESOLVED. Measured on a clean container with no reasoning
+      // CLI and no settings file: the Engine block said demo mode, no program on PATH, nothing to probe —
+      // and this line still printed a green tick for a billing mode. `billingOf` answers from the default
+      // when nothing is set, and the default is not a fact about this machine.
+      //
+      // So where no engine program resolves, the same words are INFORMATION rather than a tick. Nothing
+      // is wrong, which is why it is not a warning either: the rest of that run reads honestly, and this
+      // was the only line claiming a verdict it had not reached.
+      const engineResolved = !!(bin?.path && bin.executable && !bin.relative);
+      (engineResolved || here.say === problem ? here.say : info)(here.text);
       // AND AS THE SERVICES READ IT, when this machine runs them and that reading differs. The line above is
       // this command's configuration; the services read their own file, and a start never replaces a line
       // in it. So a machine whose services pay through a cloud account printed "billing: subscription" here,
@@ -2126,7 +2200,7 @@ export async function runCheck() {
       // One run of this command reported the SAME variable as both set and unset, and concluded a
       // production box was a demo install:
       //
-      //   ✓ CLEAROTRON_CUSTOMERS_DIR=/home/clearotron/trademark/config/profiles (.env)
+      //   ✓ CLEAROTRON_CUSTOMERS_DIR=$HOME/trademark/config/profiles (.env)
       //   · profiles resolve from …/node_modules/clearotron/driver/profiles — THE BUNDLED DEMO ROSTER,
       //     because CLEAROTRON_CUSTOMERS_DIR is unset.
       //
@@ -3655,7 +3729,7 @@ const confirmOrKey = async (q, def = true, { key = true, what = "key" } = {}) =>
     if (["n", "no"].includes(a)) return { yes: false, value: null };
     if (key && looksLikeAKey(raw)) {
       info(`that looks like the ${what} itself, so it is taken as the answer. It was not shown.`);
-      info(`received — ${raw.length} characters, ending …${raw.slice(-4)}`);
+      info(`received — ${raw.length} characters`);
       return { yes: true, value: raw };
     }
     say("  Please answer y or n.");
@@ -3688,10 +3762,23 @@ const askValue = async (q, { def = "", secret = false, skippable = false, skippe
     const a = secret ? await askSecretRaw(prompt) : await askRaw(prompt);
     const v = a || def;
     if (present(v)) {
-      // A masked prompt CONFIRMS what it received: the reader cannot see what
-      // they typed, and a paste that half-landed looks identical to one that worked. Length and the
-      // last four characters are the vendor-dashboard convention for naming a key without showing it.
-      if (secret) info(`received — ${v.length} characters, ending …${v.slice(-4)}`);
+      // A masked prompt CONFIRMS what it received: the reader cannot see what they typed, and a paste
+      // that half-landed looks identical to one that worked. The LENGTH is that confirmation now, and
+      // the last four characters are gone.
+      //
+      // THE TAIL WAS FOUR LIVE CHARACTERS OF A KEY ON STDOUT, on every run. The vendor-dashboard
+      // convention it copied is a page you are already signed in to, read once; this is a line that
+      // outlives the moment in a script's output, a CI job, a tee'd install or an assistant's
+      // transcript — ours had to be masked by hand.
+      //
+      // NOT GATED ON A TERMINAL, which is what the passphrase does. That gate is right there and wrong
+      // here: the leak path this closes includes an assistant driving the terminal, and a session like
+      // that has a pty, so `isTTY` is true and the tail would still land in the transcript. A gate that
+      // passes in the case you are defending against is not a defence.
+      //
+      // Length alone still catches the paste this line exists to catch: a truncated paste is a
+      // different number of characters, and that is the failure the reader cannot otherwise see.
+      if (secret) info(`received — ${v.length} characters`);
       return v;
     }
     if (skippable) { if (skipped) info(skipped); return null; }
@@ -3892,6 +3979,15 @@ try {
       if (!bin.executable) { problem(`${bin.path ?? resolve(p)} is ${bin.rejected?.[0]?.why ?? "not an executable file"}.`); continue; }
     }
     ok(`found ${bin.path}${bin.source === "installed" ? `, the copy Clearotron installed${bin.version ? ` (${bin.version})` : ""}` : ""}`);
+    // THE MENU ROW SAID "choose it to see the fix", AND THIS IS WHERE IT IS SHOWN. A copy below the floor
+    // runs, so neither branch above is taken for it, and setup used to print "found" and carry on with the
+    // row's promise unkept. It still carries on — an operator may have a reason to sit below the floor — but
+    // not before saying so. The version is the one the menu already asked for (cached), or the package's.
+    {
+      let seenVersion = bin.version ?? null;
+      if (!seenVersion) { try { seenVersion = menuVersion(bin.path) ?? null; } catch { seenVersion = null; } }
+      if (olderThanFloor(seenVersion, eng.floor) === true) warn(cannotRunLine(eng, { ...bin, version: seenVersion }, process.env[eng.env]));
+    }
     // THE TERMS SENTENCE TRAVELS WITH THE PROGRAM, NOT WITH THE INSTALL OFFER. It was said only when this
     // step offered to install the CLI, and a copy Clearotron installed on an earlier run skips that offer, so it is
     // said here too. Using it, rather than installing it, is what accepts the vendor's terms.

package/bin/start.mjs

@@ -1583,7 +1583,7 @@ if (isMain) {
   // Owner, in session, on his first real start: "critical, it started and I still see a demo report in
   // the actual product. Should not be there — should ONLY be in demo. Proper product should have no
   // previous reports." Measured on that box: a fictional clearance sat in
-  // /home/clearotron/trademark/pool — the directory that install publishes REAL CLIENT MATTERS into,
+  // the installed pool directory — the one that install publishes REAL CLIENT MATTERS into,
   // written the moment `start` first ran.
   //
   // DORMANT, NOT DELETED, and that is the ruling's own shape rather than a softer reading of it. His

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "c338dded5d7432c6b4b196d023c0cec047eb94bc",
-  "version": "0.3.2"
+  "commit": "d571d0ee20d96c7ce7f9c2c5bee0404db3357467",
+  "version": "0.3.3-beta.1"
 }

package/demo/MANIFEST.json

@@ -0,0 +1,27 @@
+{
+  "note": "What produced the evidence under demo/. Re-recorded by scripts/demo-evidence.mjs --apply in the same commit that regenerates it.",
+  "generator": "scripts/freeze-example-run.mjs",
+  "recordedFromTree": "7b182e13a3d062a619f74b657b5c824df4deeb39",
+  "products": [
+    {
+      "product": "full-country-search",
+      "runId": "tmpdemo2014fullcountrysearch-venqori-2026-09-18-sample-capture",
+      "template": "clearance"
+    },
+    {
+      "product": "global-preliminary-search",
+      "runId": "tmpdemo2014globalpreliminarysearch-venqori-2026-09-18-sample-capture",
+      "template": "clearance"
+    },
+    {
+      "product": "knockout-search",
+      "runId": "tmpdemo2014knockoutsearch-venqori-2026-09-18-sample-capture",
+      "template": "knockout"
+    },
+    {
+      "product": "multi-country-focus-search",
+      "runId": "tmpdemo2014multicountryfocussearch-venqori-2026-09-18-sample-capture",
+      "template": "clearance"
+    }
+  ]
+}

package/docs/INTAKE.md

@@ -67,6 +67,14 @@ the default agent's workspace queue.
   - an unreadable `deadline` → treated as unset, so no envelope is applied (a date typo must not
     stop a runnable search; a bare `YYYY-MM-DD` is read as the END of that day, UTC)
   - `jurisdictions` naming the same territory twice → deduped, first spelling wins
+  - a goods description under the older spelling `use` → folded onto `goods` when the job is
+    assembled for a run
+
+**Which field name is read.** A goods description is accepted under `goods` or under the older
+spelling `use`, and `goods` is the field everything downstream reads. The older spelling is folded
+onto it once, when a job is assembled for its run; the queue file keeps whatever was filed. Send
+either, and send only one — where both are present, `goods` wins and `use` is ignored. A value that
+is blank or only whitespace counts as no description at all, under either name.
 
 Other consumed fields (see `EXAMPLE_JOB` in `enqueue-schema.mjs` for the full annotated shape):
 `forwarderEmail`, `forwarderDomain`, `provider`, `marks[] = [{ref,name,classes}]`, `customer`

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

@@ -124,14 +124,26 @@ through anything containing `/`):
 
 | Alias | Full catalog id |
 |---|---|
-| haiku | `anthropic/claude-haiku-4-5` |
-| sonnet | `anthropic/claude-sonnet-5` |
-| opus | `anthropic/claude-opus-5` |
+| haiku | `anthropic/claude-haiku` |
+| sonnet | `anthropic/claude-sonnet` |
+| opus | `anthropic/claude-opus` |
 | gemini | `google/gemini-3.1-pro-preview` |
 | gemini-flash | `google/gemini-3-flash-preview` |
 | deepseek-v4-pro | `together/deepseek-ai/DeepSeek-V4-Pro` |
 | azure | `azure-openai/gpt-5.4` |
 
+The three tiers record a **tier, not a version**, because a tier is what a run asks for: the tier goes
+to the program as the vendor's alias and the vendor answers with its newest model of that tier. This
+id is what a dispatch row and a token-rollup row carry as the model *asked for*; what actually served
+the turn is recorded beside it, and the report names that. A version here would be a claim about a
+request nobody made, and wrong the day a newer model of the tier shipped.
+
+One consequence, accepted when this was decided: per-model totals are keyed on what was asked for,
+and the native-language lanes call the API directly, where a model id is required and a tier word is
+not accepted. So one model reached by a stage and by those lanes appears under two keys —
+`anthropic/claude-haiku` and `anthropic/claude-haiku-4-5`. They are different requests, and the split
+says so.
+
 The bottom four are **legacy names that no stage declares and no engine can run** — they resolve at
 level 1 and then throw at level 2 (below). They are catalogue entries, not available tiers.
 
@@ -140,12 +152,18 @@ level 1 and then throw at level 2 (below). They are catalogue entries, not avail
 as aliases, so each tier follows the vendor's newest model; to hold one still, set
 `ANTHROPIC_DEFAULT_OPUS_MODEL` (or `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`,
 `ANTHROPIC_DEFAULT_FABLE_MODEL`).
-The catalog ids `anthropic/claude-opus-5` and `anthropic/claude-sonnet-5` are passed as those
-concrete models; `anthropic/claude-haiku-4-5` goes over as the `haiku` alias, so it follows the
-vendor the same way. A bare or dated Anthropic id (`claude-haiku-4-5-20251001`) still resolves to
-its family — that is a naming form of a model the CLI can run, not a substitution of a different
-one. Telemetry keeps the level-1 catalog id as the model asked for, and the attempt row records the
-id the program reports it served.
+An id that names a family and a version — `anthropic/claude-opus-5-5`, `claude-sonnet-5`, the dated
+`claude-haiku-4-5-20251001` — is passed to the CLI as that model, so naming an exact model runs it
+and keeps running it when a newer model of the tier ships. A family with no version
+(`anthropic/claude-opus`) is the tier, not a model: the CLI has no model by that name, so it follows
+the family like the bare alias. Telemetry keeps the level-1 catalog id as the model asked for, and
+the attempt row records the id the program reports it served.
+
+**The CLI must be new enough for the model.** Each release carries its own list of accepted models,
+and one that predates a model refuses it outright while the tier alias goes on serving the previous
+generation — a 400 at the first turn, or a run that quietly used an older model. Setup installs
+`2.1.280` or newer for this reason; a copy already on the machine is used as it is, so `doctor`'s
+version is the one to read before assuming which model a tier reaches.
 
 **Anything else throws.** There is no regex fall-through to sonnet and no cross-provider
 substitution: the `gemini`/`gemini-flash`/`deepseek-v4-pro`/`azure` mappings are gone with the
@@ -181,7 +199,7 @@ timeout shot, warm patch, backoff), the lane-wedge re-dispatch, and the rate-lim
 | `CLEAROTRON_OPENAI_MODEL_JUDGMENT` / `CLEAROTRON_OPENAI_MODEL_SWEEP` / `CLEAROTRON_OPENAI_MODEL_CHEAP` | `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`. | Maps the driver's abstract `opus`/`sonnet`/`haiku` tiers onto the codex ladder, the way the anthropic engine maps onto its own (ruling 2026-09-02, superseding the single-model mapping). A tier that cannot hold its stage contract announces itself at that stage — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` in `_driver/<stage>.jsonl` — not at delivery. |
 | ↳ why they are three, and what the old measurement still says | superseded 2026-09-02, not erased | The three defaulted to `sol` alone on a MEASUREMENT, never a placeholder: on 2026-08-11/12, with `SWEEP=gpt-5.6-terra` / `CHEAP=gpt-5.6-luna`, every codex clearance died on structural-output gates — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` — over 2 scenarios × 3 stage families, **byte-identically on retry**, so no retry budget rescued it. That measurement stands for the code and the codex CLI **of that date**, and it is why the judgment tier keeps `sol`. Three weeks of stage-contract work and several codex minor versions sit between it and the 2026-09-02 ruling that split the three. **The symptom to match against this cause is unchanged**: those same three gates, as a fail row in`_driver/<stage>.jsonl`, inside the first few dispatches of a clearance and identical on every retry — a model incapable of a contract is not flaky at it. It reads as an engine bug when the only fault is this configuration. A cheap-tier experiment still belongs in the three constants in `driver/engine/openai-agent.mjs` where a reviewer sees it, not in an untraceable env line. |
 | `CLEAROTRON_DATABASE` | **REQUIRED — no default.** `corsearch` \| `clarivate` \| `signa` \| `euipo` \| `uspto-local` \| `free-tier` | Active register provider — one per run, set in the environment the deploy carries, in every environment including production. There is **no default**: unset resolves to `null` and every use of it throws, so a run refuses at start rather than calling a vendor nobody chose (the removed `corsearch` fallback named a vendor the deployment did not choose). Three are paid global sweeps; `euipo` (EU) and `uspto-local` (US) are free single-office sources, and `free-tier` composes those two as one register. Choosing a free value makes every territory outside its coverage a disclosed *deferred* row. Unknown ids throw loudly, and the gather layer throws at stage time for any provider without a built MCP server. |
-| `CLEAROTRON_CODEX_SANDBOX_BYPASS` | unset | `1` runs `codex exec` with its own sandbox helper bypassed, for hosts where that helper cannot spawn. It removes a defence: with it set, the run dir is writable by the seat and only the deny-hook stands between a stage and `_driver/`. Set it because the host forces it, never for convenience. |
+| `CLEAROTRON_CODEX_SANDBOX_BYPASS` | unset | `1` runs `codex exec` with its own sandbox helper bypassed, for hosts where that helper cannot spawn or refuses every tool call (setup and `doctor --probe-engine` report the refusal). It removes a defence: with it set, the run dir is writable by the seat and only the deny-hook stands between a stage and `_driver/`. Set it because the host forces it, never for convenience. |
 
 ## Environment variable reference
 
@@ -360,7 +378,7 @@ cannot be read as one list.
 | `CLEAROTRON_DISPATCH_RECORD` | **on** | Write the verbatim message of every stage dispatch to `_driver/<stage>.attempt<N>[.repair<M>].dispatch.txt`, with `{file, sha, bytes, chars, kind}` on the attempt row. **Default ON** — `0`/`off`/`false`/`no` disarms it. Unlike `CLEAROTRON_DUMP_JSON` beside it, this is opt-OUT: the question it answers ("was the model given this?") is asked *after* the run that raised it, so a flag someone had to remember would be off on exactly the run that needed it. The files carry the company's identity verbatim and are deliberately not in the artifact table. |
 | `CLEAROTRON_GATHER_SESSION_KEY` / `CLEAROTRON_GATHER_AGENT` / `CLEAROTRON_GATHER_SESSION_ID` | set per stage | Telemetry attribution into the provider-call ledger (set by the gather config; not operator-set). |
 | `CLEAROTRON_RECORD_AXIS` | set per dispatch (unset ⇒ the stage is not fanned out) | Binds one fan-out turn of a recording stage to the single member it may write. `stageOnce` suffixes a fan-out stage's label with its axis, the gather config resolves `<stage>:<axis>` back to the base stage's tool group, and this carries the axis to the recording server. A call whose payload names a different member than the turn is bound to is REFUSED, so a seat cannot write into a sibling's file — without the binding every turn of the fan-out would record over member one. Set by the driver; not operator-set. |
-| `PORTAL_READ_MODEL` | `claude-sonnet-5` | The model the portal's own compose-read turn uses. Distinct from the pipeline's tiers: this is a portal surface, not a stage. |
+| `PORTAL_READ_MODEL` | `sonnet` | The model the portal's own compose-read turn uses. Distinct from the pipeline's tiers: this is a portal surface, not a stage. |
 | `CLEAROTRON_ORDER_PROBE_SEED` | unset | Seed for `scripts/band-shape-probe.mjs`, so an ordering probe can be replayed. A diagnostic script's knob, not a run's. |
 | `PROBE_TERM` | `DELTA` | The mark word `providers/uspto-local/bin/verify-index.mjs` searches when verifying a built local USPTO index. A diagnostic script's knob, not a run's. Change it when a row reports MEASURES NOTHING: that means the term had no exact hit, so the row's timing is not a result. |
 

package/driver/CHANGELOG.md

@@ -1,5 +1,54 @@
 # clearotron-driver
 
+## 0.3.3-beta.1
+
+### Patch Changes
+
+- Fixed: a run can name a Fable model by its published id, not only by the tier word, which used to fail outright.
+- Fixed: the portal's run list shows a run's rating, never the reviewer's sign-off word, while the run is still in progress.
+- Fixed: naming an exact Claude model now runs that model, instead of quietly following the tier to a newer one.
+- Fixed: a run now records the tier it asked for, not a model version nobody chose. The report still names the model that ran.
+- Fixed: setup and doctor now report a Claude program too old for the models a search asks for, instead of passing it as fine.
+- Fixed: setup installs a version of the Claude program new enough to run the current top-tier model, which older versions refuse.
+- Fixed: the assistant's run summary names the rating again, where it had printed "[object object]" in its place.
+
+## 0.3.3-beta.0
+
+### Patch Changes
+
+- Fixed: the coverage table names the goods words of a search narrowed by goods, so it no longer reads the same as the main search.
+- Fixed: a list of names searched on Signa is now searched one name at a time, so one crowded name no longer stops the rest.
+- Fixed: a register search the provider refuses as too wide is disclosed at once, with its size, instead of pausing the run to retry it.
+- Fixed: the audit workbook now says when a surface refused a search and why, instead of reading the same as one never run.
+- Fixed: the audit workbook now lists each wider register search the engine chose not to run, with the reason it gave.
+- Fixed: a register search that fails on a provider error is tried once more in the run before it is disclosed as not searched.
+- Fixed: A two-letter mark's register searches, including those narrowed by the client's goods, now run instead of failing where the register's substring search needs three characters.
+- For operators: the run record now distinguishes a question the search step never answered from one it answered with "nothing applies". They previously looked identical, so a step that could not answer looked like a matter with nothing to say.
+- Fixed: a long list of names searched on Clarivate is now split into searches it accepts, not one it refuses as too wide.
+- Fixed: on the OpenAI engine, setup and `doctor --probe-engine` now catch a machine where codex refuses every tool call, before any search is paid for.
+  
+  A search that meets it stops after one attempt and names the setting that fixes it.
+- Fixed: a common-law search no longer repeats a finished stage because its write-up lacked one exact status word.
+  
+  Each coverage status is now recorded as data rather than read from the wording.
+- New: a search whose identical-mark question returns a count rather than a list now narrows that question until the register gives a list, and reads it.
+  
+  It previously left that question unread and searched the wider families instead — compounds, foreign-script forms, neighbour lists — which is where the reading time went.
+  
+  New: the words a search is narrowed to can now be chosen while the search is running, not only when it is first planned.
+- Fixed: doctor no longer ticks a billing mode on a machine where no engine program resolves; it states it as information.
+- Fixed: the identical mark is now read first on every search, before any wider question is asked.
+  
+  New: a search can cover a further category the client's own goods reach, added with a stated reason.
+- Fixed: a search request that describes the goods using the older wording now records those goods. It previously recorded none, so nothing downstream could narrow by what the matter actually covers.
+- Fixed: a search can now be narrowed by what the goods are, which it could not be before. The step that chooses the search words had no way to hand them back, so every search ran without them.
+- Fixed: the worker now reports itself alive throughout a search, not only between searches. Its liveness file went stale for the whole of a long search. A check reading it would call a healthy search dead, and might stop it.
+- For operators: the published package now has a recorded size budget. Nothing about what ships changes; growth past a margin fails the build and names the largest files.
+- Fixed: setup confirms a pasted key by its length alone, so no part of a key reaches a captured install log.
+- Fixed: a territory name that no register can answer is now reported as an uncovered gap instead of being searched.
+- Fixed: the clearance list is now requested at the same time as your sign-in details, instead of waiting for them.
+- Fixed: the delivery email, run list and assistant now give the rating and the report's own conclusion. None of them says a matter is on hold.
+
 ## 0.3.2
 
 ### Patch Changes

package/driver/citation-census.json

@@ -1,5 +1,5 @@
 {
-  "citations": 489,
-  "files": 3945,
-  "checkable": 126
+  "citations": 465,
+  "files": 3308,
+  "checkable": 129
 }

package/driver/clearance-variants-record.mjs

@@ -141,6 +141,9 @@ export function renderClearanceVariants(model, scopeRows) {
 
   if (model.incumbent_classes?.length) out.push(`Incumbent classes: ${model.incumbent_classes.join(", ")}`, "");
   if (model.watchlist_owners?.length) out.push("### Watchlists", "", ...model.watchlist_owners.map((o) => `- ${o}`), "");
+  // The prose copy restates exactly what the structured sibling holds — a reader of the manifest must
+  // be able to see which words the register search was narrowed to without opening the JSON.
+  if (model.goods_words?.length) out.push("### Goods words the register search is narrowed to", "", ...model.goods_words.map((w) => `- ${w}`), "");
   // — the search floor, on the human surface because a reader auditing the run has to see what was
   // obliged as well as what was done. Rendered ONLY when designated: an empty section would read as a
   // floor of nothing rather than as no floor, and those are the two states this mechanism must keep apart.
@@ -168,7 +171,7 @@ export function renderClearanceVariants(model, scopeRows) {
  */
 /** The shape this tool declares, at every depth — what the ACCEPTOR enforces. */
 const DECLARED = Object.freeze({
-  "": ["mark", "dominant_element", "elements", "variants", "incumbent_classes", "search_floor", "watchlist_owners", "scope_ledger"],
+  "": ["mark", "dominant_element", "elements", "variants", "incumbent_classes", "search_floor", "watchlist_owners", "goods_words", "scope_ledger"],
   elements: ["value", "kind"],
   variants: ["value", "category", "rationale", "romanization"],
   scope_ledger: ["layer", "item", "status", "reason", "reopen_trigger"],
@@ -204,6 +207,10 @@ export function mergeClearanceVariantsCall(stored, received) {
     incumbent_classes: keepIfAbsent(received?.incumbent_classes, base.incumbent_classes),
     search_floor: keepIfAbsent(received?.search_floor, base.search_floor),
     watchlist_owners: keepIfAbsent(received?.watchlist_owners, base.watchlist_owners),
+    // Keep-if-absent for the same reason as its neighbours: a repair rung that asks the seat to
+    // correct one part, and a seat that sends only that part, would otherwise delete the goods words
+    // — and the loss reads as "this matter has none" rather than as a partial call.
+    goods_words: keepIfAbsent(received?.goods_words, base.goods_words),
   };
 }
 
@@ -216,6 +223,10 @@ export function acceptClearanceVariants(params) {
     variants: params?.variants,
     incumbent_classes: params?.incumbent_classes,
     watchlist_owners: params?.watchlist_owners,
+    // — the words the register search is narrowed to. Carried here because a typed call cannot hand
+    // back a key nothing in this chain declares: the tool's schema offers the slot, and this is what
+    // moves the answer from the call into the manifest the compiler reads.
+    goods_words: params?.goods_words,
     // — the search-floor axes. Validated by the model parser (closed against REGISTER_AXES), not
     // here, so there is ONE definition of what a floor may name.
     search_floor: params?.search_floor,

package/driver/common-law-coverage-status.mjs

@@ -0,0 +1,113 @@
+// 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
+// common-law-coverage-status.mjs — a common-law seat's coverage statuses, recorded as VALUES.
+//
+// ── WHY THIS EXISTS ────────────────────────────────────────────────────────────────────────────────
+//
+// The common-law gate refused a finished findings file unless one of three exact words appeared
+// somewhere in its prose (`no_coverage_status_row`). The research did not change the outcome; the model's
+// phrasing did. On the codex engine, 13 of 22 failed common-law attempts on the test box (16-22 September)
+// were that word, each one a full stage re-run. The register path had already solved the same problem:
+// its seat rules coverage through `record_coverage` and the driver writes the form.
+//
+// This is that shape for the common-law lane. The seat calls `record_coverage_status` (dispositions
+// server) with one {unit, status} entry per ledger row; this module validates each entry, folds it into
+// the half's accumulator and writes the file. The gate reads the file before it looks for the word.
+//
+// ── ONE TOOL, THE DRIVER WRITES THE FILE ─────────────────────────────────────────────────────────────
+//
+// The seat is never told a file name or a JSON shape. A model typing a structured document is how 74
+// correct meaning rulings were once voided by a quote character (dispositions-server.mjs states the
+// case), and the contract audit's E3 check refuses a literal skeleton in a manual for that reason. Here
+// the serialization is ours.
+//
+// ── ONE DERIVATION OF THE PATH ──────────────────────────────────────────────────────────────────────
+//
+// The writer names the file from the grid spec it was handed and the reader from the findings file it is
+// judging; both go through coverageStatusPath(). The findings name the writer derives is the one
+// stages.mjs's paths() dictates, and a test holds the two equal.
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { driverDir } from "../shared/driver-dir.mjs";
+
+/**
+ * The three statuses a common-law coverage ledger row may carry, as data and as prose alike. Not the
+ * register's COVERAGE_STATUSES: that list adds `withheld-by-judgment`, which is the register's reading turn
+ * and never a common-law status.
+ */
+export const COMMON_LAW_COVERAGE_STATUSES = Object.freeze(["confirmed-clean", "coverage-limited", "deferred"]);
+
+/** A findings file's statuses: `_driver/<findings name>.coverage-status.json`, driver-written, never the seat's. */
+export const coverageStatusPath = (findingsPath) =>
+  driverDir(dirname(String(findingsPath)), basename(String(findingsPath)).replace(/\.md$/, ".coverage-status.json"));
+
+/** The findings file a grid spec's seat writes: the half's, or the canonical file on an unsplit run. */
+export const findingsPathForSpec = (spec) =>
+  join(dirname(String(spec.output_path)), spec.half ? `common-law-findings.half-${spec.half}.md` : "common-law-findings.md");
+
+const readStatuses = (file) => {
+  let doc;
+  try { doc = JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+  const rows = doc?.coverage_status;
+  return rows && typeof rows === "object" && !Array.isArray(rows) ? rows : null;
+};
+
+/**
+ * Is this findings file's coverage status on record as data? At least one entry, every value one of
+ * COMMON_LAW_COVERAGE_STATUSES. Anything else — absent, unparseable, empty, a value outside the three — is
+ * NOT data, and the caller falls back to the prose word, so the file can never turn a passing document into
+ * a failing one.
+ *
+ * THE MERGED FILE IS THE HALVES. The driver writes `common-law-findings.md` by concatenating the halves'
+ * findings, so its statuses are theirs: a half that stated its status only as data leaves no word in the
+ * merge. For that file the halves' records answer too.
+ */
+export function coverageStatusAsData(findingsPath) {
+  if (!findingsPath) return false;
+  const p = String(findingsPath);
+  const valid = (file) => {
+    const rows = readStatuses(file);
+    const values = rows ? Object.values(rows) : [];
+    return values.length > 0 && values.every((v) => COMMON_LAW_COVERAGE_STATUSES.includes(String(v).trim().toLowerCase()));
+  };
+  if (valid(coverageStatusPath(p))) return true;
+  if (basename(p) !== "common-law-findings.md") return false;
+  const dir = driverDir(dirname(p));
+  let names = [];
+  try { names = readdirSync(dir); } catch { return false; }
+  return names.filter((n) => /^common-law-findings\.half-[a-z0-9]+\.coverage-status\.json$/.test(n))
+    .some((n) => valid(join(dir, n)));
+}
+
+/**
+ * Record one typed call. `spec` is the DRIVER-WRITTEN grid spec, the same file the grid tool was given, so
+ * the seat names no path of its own. Entries that validate are kept even when others in the same call are
+ * refused, and statuses accumulate: a later entry for the same unit replaces the earlier one.
+ */
+export function recordCoverageStatus(spec, received, { now = () => new Date().toISOString() } = {}) {
+  const rows = received?.rows;
+  if (!Array.isArray(rows) || rows.length === 0)
+    return { ok: false, text: "ERROR: rows is required — one entry per coverage ledger row, each {unit, status}." };
+  const accepted = [], refused = [];
+  rows.forEach((r, i) => {
+    const unit = String(r?.unit ?? "").trim();
+    const status = String(r?.status ?? "").trim().toLowerCase();
+    if (!unit) refused.push(`entry ${i + 1}: unit is empty — name the coverage unit exactly as your ledger row does`);
+    else if (!COMMON_LAW_COVERAGE_STATUSES.includes(status))
+      refused.push(`entry ${i + 1} (${unit.slice(0, 80)}): status "${String(r?.status ?? "").slice(0, 40)}" is not one of ${COMMON_LAW_COVERAGE_STATUSES.join(" / ")} — qualifiers belong in the ledger row, not here`);
+    else accepted.push([unit, status]);
+  });
+  const file = coverageStatusPath(findingsPathForSpec(spec));
+  if (accepted.length) {
+    const statuses = { ...(readStatuses(file) ?? {}), ...Object.fromEntries(accepted) };
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, JSON.stringify({ coverage_status: statuses, half: spec.half ?? null, recorded_at: now() }, null, 2) + "\n");
+    } catch (e) {
+      return { ok: false, text: `ERROR: the driver could not record this call (${String(e?.message ?? e).slice(0, 200)}). This is a driver fault, not a fault in your statuses — do not re-type them.` };
+    }
+  }
+  const lines = [`Recorded ${accepted.length} of ${rows.length}.`];
+  if (refused.length) lines.push("Refused — send these again, corrected:", ...refused.map((x) => `- ${x}`));
+  return { ok: refused.length === 0, text: lines.join("\n") };
+}

package/driver/config-inventory.mjs

@@ -71,7 +71,7 @@ const shown = (names) => names.map((n) => n);
  * and only one of them describes who gets the invoice.
  */
 export function engineInventory(env = process.env) {
-  // THE SAME EXPRESSION AS THE RUN DOOR, character for character (driver.config.mjs:1880,
+  // THE SAME EXPRESSION AS THE RUN DOOR, character for character (driver.config.mjs,
   // preflightEngineBinary). The obvious rewrite — `String(env.CLEAROTRON_AI ?? "").trim() || DEFAULT` —
   // reads better and disagrees on a whitespace-only value: it falls back to the default while the door
   // resolves `""` and refuses with "that is not an engine". The page would then name a known engine that