clearotron 0.3.2 → 0.3.3-beta.1

package/driver/coverage-union.mjs

@@ -102,10 +102,10 @@ export function unionCoverageForm(prior, submitted, input, { parkedIds = null }
   let settled = 0, carried = 0, parked = 0;
   for (const row of form.rows) {
     const p = findPrior(row), s = findSubmitted(row);
-    const sOk = s && rowIsSettled(s, row), pOk = p && rowIsSettled(p, row);
+    const sOk = s && rowIsSettled(s, row), pOk = p && rowIsSettled(p, row), dOk = rowIsSettled(row, row);
     let fields;
     if (sOk) fields = seatFields(s);
-    else if (pOk) fields = seatFields(p);
+    else if (pOk) fields = seatFields(p); else if (dOk) fields = seatFields(row);   // a judgment the driver row arrived with (a family the reading turn withheld)
     else {
       const sf = seatFields(s ?? {}), pf = seatFields(p ?? {});
       fields = { status: sf.status || pf.status, reason: sf.reason || pf.reason };

package/driver/crowd-context.mjs

@@ -36,6 +36,7 @@
 // and the axis bands are never touched — this pass mutates no existing artifact.
 
 import { NON_MATERIAL_AXES } from "./coverage-ledger.mjs";
+import { containsFormSubstitution } from "./register-plan.mjs";
 
 // ── caps — these bound SPEND, never sufficiency ─────────────────────────────────────────────────────
 // Each cap limits how many provider calls / how many fetched records one evidence pass may buy. They
@@ -180,14 +181,22 @@ export function selectCrowdSlices(ledgerRows, planContext = {}) {
 // the counts describe the SAME crowd the ledger row is about. An owner-scoped slice carries its
 // `owner` onto EVERY minted entry for the same reason — un-owned counts would describe the wider
 // formative crowd while claiming to describe the owner's slice.
-export function mintSliceCountEntries(slice, i, { maxTerms = CROWD_MAX_TERMS_PER_SLICE } = {}) {
+//
+// A TERM SHORTER THAN THE REGISTER'S CONTAINS FLOOR is counted on the exact form instead, the same
+// rule the frozen plan's goods-narrowed questions and saturation probes follow: a register that
+// refuses the contains form for a term that short answers no count at all, so the crowd this pass
+// exists to describe would read "count unavailable". Same classes, same two counts per term, and the
+// entry carries `contains_substituted` so the figure is never taken for a containing count.
+export function mintSliceCountEntries(slice, i, { maxTerms = CROWD_MAX_TERMS_PER_SLICE, capabilities = null } = {}) {
   const terms = slice.terms.slice(0, maxTerms);
   const base = { axis: CROWD_CONTEXT_AXIS, regions: slice.regions ?? [], expected_kind: "count",
     ...(typeof slice.owner === "string" && slice.owner ? { owner: slice.owner } : {}) };
   const out = [];
   terms.forEach((t, j) => {
-    out.push({ ...base, qid: `crowdctx:s${i}-t${j}-${slug(t)}-all`, predicate: "default", term: t, nice_classes: [] });
-    out.push({ ...base, qid: `crowdctx:s${i}-t${j}-${slug(t)}-cls`, predicate: "default", term: t, nice_classes: slice.nice_classes ?? [] });
+    const sub = containsFormSubstitution(t, capabilities);
+    const form = sub ? { predicate: "exact", contains_substituted: sub } : { predicate: "default" };
+    out.push({ ...base, qid: `crowdctx:s${i}-t${j}-${slug(t)}-all`, ...form, term: t, nice_classes: [] });
+    out.push({ ...base, qid: `crowdctx:s${i}-t${j}-${slug(t)}-cls`, ...form, term: t, nice_classes: slice.nice_classes ?? [] });
   });
   out.push({
     ...base, qid: `crowdctx:s${i}-exact-count`, predicate: "exact",
@@ -325,10 +334,12 @@ const compactRecord = (r) => ({
  * @param opts.executor     INJECTED: async (entries) => band blocks (tests stub it; the pipeline passes
  *                          the planExec-lane adapter). Null/absent ⇒ no lane ⇒ null (logged, non-fatal).
  * @param opts.caps         { maxSlices?, maxTermsPerSlice?, enumCap? } — spend bounds only.
+ * @param opts.capabilities the active register's declared capabilities, read for the contains floor
+ *                          only (containsMinLength). Absent ⇒ every term is counted on the contains form.
  * @param opts.note / opts.log  observability hooks (default no-ops; pipeline wires note()/runLog).
  * @returns { json, md, stats } | null
  */
-export async function buildCrowdContext({ ledger, planContext = {}, executor, caps = {}, note = () => {}, log = () => {} } = {}) {
+export async function buildCrowdContext({ ledger, planContext = {}, executor, caps = {}, capabilities = null, note = () => {}, log = () => {} } = {}) {
   const maxSlices = caps.maxSlices ?? CROWD_MAX_SLICES;
   const maxTermsPerSlice = caps.maxTermsPerSlice ?? CROWD_MAX_TERMS_PER_SLICE;
   const enumCap = caps.enumCap ?? CROWD_ENUM_CAP;
@@ -344,7 +355,7 @@ export async function buildCrowdContext({ ledger, planContext = {}, executor, ca
   if (selected.length > slices.length) note(`crowd-context: ${selected.length} qualifying slice(s), gathering the first ${slices.length} (spend cap — the rest keep their ledger disclosure unchanged)`);
   try {
     // ── phase 1: one batched executor call for every count probe ─────────────────────────────────
-    const countEntries = slices.flatMap((s, i) => mintSliceCountEntries(s, i, { maxTerms: maxTermsPerSlice }));
+    const countEntries = slices.flatMap((s, i) => mintSliceCountEntries(s, i, { maxTerms: maxTermsPerSlice, capabilities }));
     const byQid = new Map((await executor(countEntries) ?? []).filter((b) => b && b.qid).map((b) => [b.qid, b]));
     // ── phase 2: enumerate each exact subset the count proved tractable (0 < hits ≤ cap) ─────────
     // A verified-zero count needs no call (enumerating an empty subset returns the empty subset);
@@ -366,7 +377,9 @@ export async function buildCrowdContext({ ledger, planContext = {}, executor, ca
         const all = byQid.get(`crowdctx:s${i}-t${j}-${slug(t)}-all`);
         const cls = byQid.get(`crowdctx:s${i}-t${j}-${slug(t)}-cls`);
         const bad = !all || all.error || !cls || cls.error;
-        return { term: t, all_classes: Number(all?.total_hits) || 0, in_scope: Number(cls?.total_hits) || 0, ...(bad ? { error: true } : {}) };
+        const sub = containsFormSubstitution(t, capabilities);
+        return { term: t, all_classes: Number(all?.total_hits) || 0, in_scope: Number(cls?.total_hits) || 0,
+          ...(bad ? { error: true } : {}), ...(sub ? { contains_substituted: sub } : {}) };
       });
       const c = byQid.get(`crowdctx:s${i}-exact-count`);
       const hits = Number(c?.total_hits) || 0;

package/driver/dev-portal.mjs

@@ -145,7 +145,7 @@ function scanRuns(workspaceRoot) {
       const s = JSON.parse(readFileSync(join(dir, "status.json"), "utf8"));
       out.push({ runId: s.runId ?? `${slug}-${runName}`, slug: s.slug ?? slug, codename: s.codename ?? null,
         agent: s.agent ?? null, state: s.state ?? null, stepN: s.stepN ?? null, stepLabel: s.stepLabel ?? null,
-        stepTotal: s.stepTotal ?? null, verdict: s.verdict ?? null, sendPending: s.sendPending ?? null,
+        stepTotal: s.stepTotal ?? null, signoff: s.review?.signoff ?? s.verdict ?? null, tier: s.tier ?? null, sendPending: s.sendPending ?? null,
         markName: s.markName ?? null, updatedAt: s.updatedAt ?? null, archived });
     } catch { /* not a run dir / unreadable status — skip */ }
   };
@@ -293,8 +293,8 @@ $("#f").addEventListener("submit",async(e)=>{e.preventDefault();const fd=new For
  const r=await fetch("/dev/enqueue",{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify(b)});
  $("#fout").textContent=JSON.stringify(await r.json(),null,2);loadRuns();});
 async function loadRuns(){const r=await(await fetch("/dev/runs")).json();
- $("#runs").innerHTML=r.length?"<table><tr><th>run</th><th>state</th><th>step</th><th>verdict</th><th>updated</th></tr>"+r.map(x=>
-  '<tr><td>'+(x.markName??x.slug)+' · '+(x.codename??"?")+'</td><td class="'+(x.state==="delivered"?"ok":x.state==="failed"?"err":"warn")+'">'+(x.state??"?")+(x.sendPending?" (sendPending)":"")+'</td><td>'+(x.stepLabel??"")+'</td><td>'+(x.verdict??"")+'</td><td>'+(x.updatedAt??"").slice(0,19)+'</td></tr>').join("")+"</table>":"no runs yet";}
+ $("#runs").innerHTML=r.length?"<table><tr><th>run</th><th>state</th><th>step</th><th>sign-off</th><th>updated</th></tr>"+r.map(x=>
+  '<tr><td>'+(x.markName??x.slug)+' · '+(x.codename??"?")+'</td><td class="'+(x.state==="delivered"?"ok":x.state==="failed"?"err":"warn")+'">'+(x.state??"?")+(x.sendPending?" (sendPending)":"")+'</td><td>'+(x.stepLabel??"")+'</td><td>'+(x.signoff??"")+'</td><td>'+(x.updatedAt??"").slice(0,19)+'</td></tr>').join("")+"</table>":"no runs yet";}
 async function loadOutbox(){const r=await(await fetch("/dev/outbox")).json();
  $("#outbox").innerHTML=r.length?r.map(x=>'<details><summary>'+x.file+' <span class="warn">'+(x.packet?.kind??(x.legacyAgent?"delivered (legacy)":"?"))+'</span></summary><pre>'+JSON.stringify(x.packet??{legacyAgent:x.legacyAgent},null,2)+'</pre></details>').join(""):"outbox empty";}
 // ── Searches panel (Phase 3a): registry levels + saved recipes via the /recipes/* proxy. EVERY

package/driver/drainer-identity.mjs

@@ -190,7 +190,7 @@ export function drainerVerdict({ stamp, headCommit, isAlive, processes, ppidOf =
   }
 
   if (!head) {
-    return { state: "fail", message: `drainer pid ${pid} is alive on ${short(held)}${via}, but the checkout's own HEAD `
+    return { state: "skip", blocked: true, message: `drainer pid ${pid} is alive on ${short(held)}${via}, but the checkout's own HEAD `
       + `could not be read, so the two could not be compared.${strayNote}` };
   }
 

package/driver/driver.config.mjs

@@ -656,10 +656,29 @@ export const config = {
 // stage definition and the id stamped on a token-rollup row are the same fact rather than two spellings
 // of it. resolveModel below is the only reader that matters; an engine with its own resolveModelId
 // overrides it, and anything already in catalog form passes through untouched.
+// ── A TIER IS WHAT WAS ASKED FOR, SO A TIER IS WHAT IS RECORDED ─────────────────────────────────────
+//
+// These three named a VERSION — `anthropic/claude-opus-5` — and nothing ever asked for one. A stage
+// names a tier, the tier goes to the program as the vendor's own alias, and the vendor answers with its
+// newest model of that tier. The version written here was a claim about a request nobody made, and it
+// was wrong the day a newer model shipped: a delivered run served throughout by the generation after
+// Opus 5 recorded, on every attempt row, a request for Opus 5, and its token line accounted under the
+// name of a model that did not run. Measured on that run, 2026-09-22.
+//
+// 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.
 export const MODELS = {
-  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",
@@ -675,11 +694,17 @@ export const MODELS = {
 //
 // A BARE Anthropic id (dated or not — "claude-haiku-4-5-20251001", "claude-opus-5") normalises to the
 // catalog form too. The direct-API lanes (jx completions/judge/nativeread, driver.config JX_PROVIDERS)
-// name their model that way because that is what the Messages API takes, so without this the same model
-// lands in a token rollup under two keys — "anthropic/claude-haiku-4-5" from the gateway's alias rows and
-// "claude-haiku-4-5-20251001" from the jx rows — and a per-model total is silently split. The date suffix
-// is dropped because the catalog ids carry none; anything that does not look like a bare claude id is
-// returned untouched, so a genuinely unknown model still keys as-is rather than being guessed at.
+// name their model that way because that is what the Messages API takes, so without this one model named
+// in two spellings — dated and undated — would key apart in a rollup. The date suffix is dropped;
+// anything that does not look like a bare claude id is returned untouched, so a genuinely unknown model
+// still keys as-is rather than being guessed at.
+//
+// WHAT THIS NO LONGER DOES, SAID PLAINLY BECAUSE THE PARAGRAPH ABOVE USED TO CLAIM IT. It used to unite
+// a stage's rows with those lanes' rows, because the tier resolved to a versioned id and so did they.
+// The tiers now resolve to a tier (MODELS), and these lanes still name a version, so the same model
+// reached both ways keys in two places. That split was ruled on and accepted (see MODELS) — it is not
+// an oversight here, and closing it by collapsing a version to its tier would throw away the one thing
+// these rows can still say about which model was asked for.
 export function resolveModel(model) {
   if (!model) return model;
   if (MODELS[model]) return MODELS[model];
@@ -1976,7 +2001,12 @@ export const ENGINE_BINARIES = {
     // 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",
+    // 2.1.280 is the floor because it is the oldest release that can run the current generation of this
+    // vendor's top tier: below it the API refuses the model id outright ("version 2.1.280 or newer is
+    // required"), and the tier alias quietly goes on serving the previous generation. Measured 2026-09-22
+    // on 2.1.263 — the alias returned the older model and the pinned id was refused — so a floor that
+    // only asks for a program that starts is a floor that passes a machine this engine cannot run on.
+    package: "@anthropic-ai/claude-code", floor: "2.1.280",
     // 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
@@ -2047,6 +2077,47 @@ export function enginesFolder({ env = process.env, home = homedir() } = {}) {
   return String(env[ENGINES_DIR_ENV] ?? "").trim() || join(home, ".local", "share", "clearotron", "engines");
 }
 
+/**
+ * Is the copy of an engine's program on this machine older than the version this build asks for?
+ *
+ * THE FLOOR GOVERNED ONE ROUTE OF TWO. Setup passes it to npm, so a program it installs cannot land
+ * under it; a copy already on the machine wins over the installed one by design, and nothing compared
+ * its version to anything. The two routes are not equally common — most machines have their own copy —
+ * so the check that existed covered the case that mostly does not arise.
+ *
+ * What that costs is not a crash. The program carries its own list of the models it accepts, so one
+ * below the floor refuses the model a tier names and serves the previous generation instead: the run
+ * completes, the report is delivered, and the only sign is a model id in the record that nobody chose.
+ * Measured 2026-09-22 on 2.1.263, where the current top tier's id came back a 400 and the tier alias
+ * answered with the generation before it.
+ *
+ * THREE-VALUED, AND THE THIRD VALUE IS THE POINT. `null` means "these two cannot be compared" — no
+ * floor declared, nothing read from the copy, or a version this cannot parse — and it is never "fine".
+ * A caller must say it could not look rather than print a pass, which is the absence-read-as-a-pass
+ * class that the rest of this file keeps naming. Only a version that parses and sorts below the floor
+ * comes back `true`.
+ *
+ * PURE, both arguments injected, so a test drives an old version and a current one without a program.
+ *
+ * @param {string|null|undefined} version  what the copy reports, e.g. "2.1.273"
+ * @param {string|null|undefined} floor    the engine's declared floor, e.g. "2.1.280"
+ * @returns {boolean|null} true = older than the floor; false = at it or newer; null = not comparable
+ */
+export function olderThanFloor(version, floor) {
+  const parts = (v) => {
+    const m = /^\s*v?(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(v ?? ""));
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : null;
+  };
+  const [got, want] = [parts(version), parts(floor)];
+  if (!got || !want) return null;
+  // Part by part, never as text: "2.1.99" sorts above "2.1.280" as a string, and that comparison would
+  // read a machine two hundred releases behind as being ahead of the floor.
+  for (let i = 0; i < 3; i++) {
+    if (got[i] !== want[i]) return got[i] < want[i];
+  }
+  return false;
+}
+
 /** 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}`];

package/driver/engine/CONTRACT.md

@@ -153,8 +153,9 @@ and could not be: the telemetry logged the alias that was ASKED FOR, so an arm r
 gemini and ran sonnet. Both tiers are gone — the failover chain was deleted in and both stages
 declare an anthropic tier in `STAGES` — and every engine's model map now **refuses** an alias it cannot
 run (`claudeModel`, `openaiModel`). On the anthropic engine a tier goes as the vendor's alias, a catalog
-id in the table (`anthropic/claude-opus-5`) goes as itself, a bare or dated `claude-*` id goes as its
-family's alias, and anything else throws. To hold a tier on one model, set the vendor's own
+id naming a family and a version (`anthropic/claude-opus-5-5`, `claude-haiku-4-5-20251001`) goes as
+that model so a pin holds, a `claude-*` id naming a family with no version goes as its family's alias
+because the CLI has no model by that name, and anything else throws. To hold a tier on one model, set the vendor's own
 `ANTHROPIC_DEFAULT_OPUS_MODEL` / `_SONNET_MODEL` / `_HAIKU_MODEL`, or `ANTHROPIC_DEFAULT_FABLE_MODEL` for
 `fable`, which no stage asks for unless an override names it, as `CLEAROTRON_SYNTHESIS_MODEL=fable` does; each
 reaches the CLI through the stage's environment.

package/driver/engine/anthropic-agent.mjs

@@ -156,11 +156,17 @@ const engineMaxBufferChars = () => Math.max(1024, Number(process.env.CLEAROTRON_
 // An alias with no claude equivalent now FAILS LOUD, exactly as `openaiModel` has always done for a
 // non-GPT id. That is the issue's requirement in one line: an unhonoured model override is an error,
 // not a substitution.
-const CLAUDE_MODEL = {
-  opus: "opus", sonnet: "sonnet", haiku: "haiku", fable: "fable",
-  "anthropic/claude-opus-5": "claude-opus-5", "anthropic/claude-sonnet-5": "claude-sonnet-5",
-  "anthropic/claude-sonnet-4-6": "sonnet", "anthropic/claude-haiku-4-5": "haiku",
-};
+// THE CATALOG IDS ARE NOT LISTED HERE ANY MORE, and removing them is what makes one rule cover every
+// id. Four sat here and two of them disagreed with the other two: `anthropic/claude-opus-5` and
+// `anthropic/claude-sonnet-5` went over as those models, while `anthropic/claude-sonnet-4-6` and
+// `anthropic/claude-haiku-4-5` went over as their tier's alias. A caller naming an exact model got it
+// or lost it depending on which of the four they happened to name, and nothing said which.
+//
+// The rule below now answers all four the same way, and no run changes: a stage names its TIER, and the
+// tier words above are still the whole of what a run passes. These ids reach this function only when a
+// caller names one — an override or an experiment arm — and there, being given the model you named is
+// the behaviour the rest of this function already promises.
+const CLAUDE_MODEL = { opus: "opus", sonnet: "sonnet", haiku: "haiku", fable: "fable" };
 export function claudeModel(model) {
   if (!model) return undefined;
   if (CLAUDE_MODEL[model]) return CLAUDE_MODEL[model];
@@ -168,8 +174,29 @@ export function claudeModel(model) {
   // that is a NAMING form of a model claude can actually run, not a substitution of a different one.
   // The family must be named IN the id: a `claude-*` id whose family this build does not recognise
   // throws too, rather than riding the old else-arm into sonnet.
-  const fam = /opus/i.test(model) ? "opus" : /haiku/i.test(model) ? "haiku" : /sonnet/i.test(model) ? "sonnet" : null;
-  if (fam && /^(?:anthropic\/)?claude-/i.test(model)) return fam;
+  // FABLE IS READ HERE TOO, and its absence was a live defect rather than a gap in readiness: the bare
+  // `fable` alias is in the table above, so `CLEAROTRON_SYNTHESIS_MODEL=fable` worked and hid it, while
+  // the pinned id every vendor page names — `claude-fable-5-1` — threw on its way to a program that runs
+  // it. Measured 2026-09-22: the program accepts that id and reports serving `claude-fable-5-1`.
+  const fam = /opus/i.test(model) ? "opus" : /haiku/i.test(model) ? "haiku" : /sonnet/i.test(model) ? "sonnet"
+    : /fable/i.test(model) ? "fable" : null;
+  if (fam && /^(?:anthropic\/)?claude-/i.test(model)) {
+    const bare = String(model).replace(/^anthropic\//i, "").toLowerCase();
+    // A CONCRETE ID GOES TO THE PROGRAM AS ITSELF, AND THAT IS WHAT MAKES A PIN A PIN. It used to come
+    // back as the bare family alias, so a caller who named an exact model got whichever model the tier
+    // pointed at — the same model on the day it was written, a different one the day a newer one
+    // shipped, and nothing to read in between. A silent un-pinning is the substitution this function
+    // exists to refuse, in the one form it still allowed.
+    //
+    // A FAMILY WITH NO VERSION IS THE TIER, not a model: `claude-opus` is what an operator types for a
+    // deployment of that tier, and the program has no model by that name. It keeps following the family.
+    //
+    // Measured against the program rather than assumed (2026-09-22): it accepts `claude-sonnet-5`,
+    // `claude-haiku-4-5-20251001` and `claude-fable-5-1` and reports serving each of them, so passing an
+    // exact id through costs nothing that the alias was buying. Where a caller names an id the program
+    // does not know, it says so and the turn fails loudly — which is the honest end of a bad pin.
+    return /^claude-(?:[a-z]+-\d|\d)/.test(bare) ? bare : fam;
+  }
   throw new Error(`anthropic-agent: no claude model mapped for "${model}" — this engine runs claude only. Pass opus/sonnet/haiku/fable or a concrete claude-* id. (It used to substitute sonnet silently and log the alias you asked for: #238 corruption 3.)`);
 }
 

package/driver/engine/mcp/clarivate-server.mjs

@@ -33,6 +33,7 @@ import {
   CAPABILITIES, doSearch, doRecordFetch, doImageFetch, doBatchScreen, doEnumerate, doExecutePlan, DEFAULT_BASE,
 } from "../../../providers/clarivate/src/core.js";
 import { proposeSupplemental } from "./supplemental.mjs";
+import { narrowingFields } from "./proposal-fields.mjs";
 
 const API_KEY = process.env.CLARIVATE_API_KEY || "";
 const BASE = process.env.CLARIVATE_API_BASE || DEFAULT_BASE;
@@ -136,8 +137,9 @@ serve({
           romanization: { type: "string", description: "The Latin-script form of a NON-LATIN term — plain ASCII letters/digits, syllable-separated by single spaces, no tone marks or diacritics (华威豹 → \"HUA WEI BAO\", ティキスラッシュ → \"TIKI SURASSHU\"). MANDATORY beside a non-Latin term: without it this register cannot answer the characters and the slice defers. Single-term proposals only (never an OR-stack, never predicate:owner), and never on a term that is already Latin." },
           owner: { type: "string", description: "OPTIONAL owner scope field on a MARK-TEXT proposal: the query is the owner×term intersection (the owner's filings within the term band). Not allowed on predicate:owner (there the owner name IS the term)." },
           nice_classes: { type: "array", items: {} },
-          regions: { type: "array", items: { type: "string" },
-            description: "OPTIONAL. Omit to inherit the frozen plan's regions (the matter's territorial scope) — this provider REQUIRES at least one office on every request, so an omitted list is backfilled from the plan, never treated as a worldwide sweep. Supply it only to search a NARROWER set than the matter's scope." },
+          // The narrowing fields every register serves (proposal-fields.mjs); this register's two facts ride in.
+          ...narrowingFields({ regions: "OPTIONAL. Omit to inherit the frozen plan's regions (the matter's territorial scope) — this provider REQUIRES at least one office on every request, so an omitted list is backfilled from the plan, never treated as a worldwide sweep. Supply it only to search a NARROWER set than the matter's scope.",
+            goodsNote: "One office in this provider's vocabulary refuses the field and fails the whole call, so it is left out of that office's request and recorded as asked-without-goods rather than dropped in silence." }),
           rationale: { type: "string" },
           term_literal: { type: "boolean", description: "TRUE only when the term genuinely IS the mark verbatim (a multi-word slogan mark, a mark carrying an anchored star) — it bypasses the term-shape lint. Never use it to push a label through." },
         } } },

package/driver/engine/mcp/corsearch-server.mjs

@@ -9,6 +9,7 @@
 import { serve } from "./stdio-server.mjs";
 import { CAPABILITIES, doSearch, doRecordFetch, doImageFetch, doExpandPhoneme, doBatchScreen, doEnumerate, doExecutePlan } from "../../../providers/corsearch/src/core.js";
 import { proposeSupplemental } from "./supplemental.mjs";
+import { narrowingFields } from "./proposal-fields.mjs";
 
 const COOKIE = process.env.CORSEARCH_SESSION_KEY || "";
 const tctx = (kind) => ({
@@ -118,7 +119,8 @@ serve({
           term: { type: "string" }, terms: { type: "array", items: { type: "string" } },
           romanization: { type: "string", description: "OPTIONAL on this provider (its index holds the characters and answers them directly), but STATE IT anyway for a non-Latin term — the plan is provider-neutral and the entry carries both forms for whichever register expresses it. Latin-script form only: plain ASCII letters/digits, syllable-separated by single spaces, no tone marks or diacritics. Single-term proposals only; never on an already-Latin term." },
           owner: { type: "string", description: "OPTIONAL owner scope field on a MARK-TEXT proposal: the query is the owner×term intersection (the owner's filings within the term band). Not allowed on predicate:owner (there the owner name IS the term)." },
-          nice_classes: { type: "array", items: {} }, regions: { type: "array", items: { type: "string" }, description: "UPPERCASE 2-letter region codes, e.g. ['US','EU','CH'] — never spelled-out names (recognized display names are normalized; unknown values are rejected)" },
+          nice_classes: { type: "array", items: {} },
+          ...narrowingFields(),   // the narrowing fields every register serves (proposal-fields.mjs)
           rationale: { type: "string" },
           term_literal: { type: "boolean", description: "TRUE only when the term genuinely IS the mark verbatim (a multi-word slogan mark, a mark carrying an anchored star) — it bypasses the term-shape lint. Never use it to push a label through." },
         } } },

package/driver/engine/mcp/coverage-server.mjs

@@ -55,7 +55,7 @@ serve({
         description: `Up to ${MAX_ROWS_PER_CALL} rows per call. Send more in a further call; the answer tells you what is left.`,
         items: { type: "object", properties: {
           row_id: { type: "string", description: "A driver row's id, exactly as the dispatch's obligations block lists it. Omit on a seat row you are adding — the driver mints seat row ids." },
-          status: { type: "string", description: "EXACTLY one bare token of confirmed-clean / coverage-limited / deferred. Qualifiers go in the reason." },
+          status: { type: "string", description: "EXACTLY one bare token of confirmed-clean / coverage-limited / deferred / withheld-by-judgment. Qualifiers go in the reason." },
           reason: { type: "string", description: "The sentence the lawyer reads — say what was searched and what was not, in a lawyer's words, never the engine's." },
           kind: { type: "string", description: "\"seat\" on a row you add for a coverage unit the plan does not contain. Never anything else." },
           axis: { type: "string", description: "Seat rows only: EXACTLY one bare token of the closed register-axis vocabulary the dispatch lists." },

package/driver/engine/mcp/dispositions-server.mjs

@@ -56,6 +56,9 @@ import { validateGridSpec } from "../../../providers/perplexity/src/core.js";
 // the disk work and disposition-call.mjs owns the decision. One direction of import, no second opinion.
 import { recordDispositions } from "../../disposition-tool.mjs";
 import { MAX_ROWS_PER_CALL } from "../../disposition-call.mjs";
+// The lane's second statement, and a different one: which coverage units were searched to what end. Its
+// own module and its own file, never a row in the disposition form — see record_coverage_status below.
+import { recordCoverageStatus, COMMON_LAW_COVERAGE_STATUSES } from "../../common-law-coverage-status.mjs";
 
 // ── B — THE TYPED DISPOSITION TRANSPORT ─────────────────────────────────────────────────────────────
 //
@@ -68,15 +71,21 @@ import { MAX_ROWS_PER_CALL } from "../../disposition-call.mjs";
 // THE SPEC PATH IS THE SEAT'S ONLY PATH ARGUMENT, and it is the same driver-written file the grid tool
 // was given. That rule: the path is the DRIVER'S, taken from the spec it wrote. Two derivations of one
 // filename is the drift that cost weeks.
-async function record_dispositions(params) {
-  const { grid_spec_path, rows } = params ?? {};
+function specFrom(params) {
+  const { grid_spec_path } = params ?? {};
   if (!grid_spec_path)
-    return { isError: true, text: "ERROR: grid_spec_path is required — it is the same driver-written spec path the grid tool was given. Do not compose a path." };
+    return { error: "ERROR: grid_spec_path is required — it is the same driver-written spec path the grid tool was given. Do not compose a path." };
   let spec;
   try { spec = validateGridSpec(JSON.parse(readFileSync(grid_spec_path, "utf8"))); }
-  catch (err) { return { isError: true, text: `ERROR: grid_spec_path unreadable/invalid (${err.message}). The driver writes this file; do not hand-author it.` }; }
+  catch (err) { return { error: `ERROR: grid_spec_path unreadable/invalid (${err.message}). The driver writes this file; do not hand-author it.` }; }
   if (!/\/studio\/(?:prelim|clearance)-search\//.test(spec.output_path))   // either spelling: an install keeps the studio segment it has
-    return { isError: true, text: `ERROR: grid spec.output_path must be within a studio/clearance-search run dir; got ${spec.output_path}` };
+    return { error: `ERROR: grid spec.output_path must be within a studio/clearance-search run dir; got ${spec.output_path}` };
+  return { spec };
+}
+
+async function record_dispositions(params) {
+  const { spec, error } = specFrom(params);
+  if (error) return { isError: true, text: error };
   // NEVER THROWN PAST THIS POINT. An exception surfaces to the seat as a tool error naming no row, which
   // tells it nothing about what to fix — the failure mode this transport exists to end.
   try {
@@ -97,6 +106,23 @@ async function record_dispositions(params) {
   }
 }
 
+// ── THE COVERAGE STATUS, THE LANE'S SECOND TOOL ON ITS OWN KEY ───────────────────────────────────────
+//
+// A sibling of record_dispositions, not a field on it. A meaning ruling is addressed by an obligation's
+// number; a coverage status by a coverage unit. `record_coverage` and `record_register_digest` stay two
+// tools for the same reason. The key is still granted by exactly one lane's group list, so no other seat
+// gains a writer. Both tools resolve the spec through specFrom() above, one resolution for both.
+async function record_coverage_status(params) {
+  const { spec, error } = specFrom(params);
+  if (error) return { isError: true, text: error };
+  try {
+    const r = recordCoverageStatus(spec, params);
+    return { isError: !r.ok, text: r.text };
+  } catch (e) {
+    return { isError: true, 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.` };
+  }
+}
+
 serve({
   name: "dispositions", version: "0.1.0",
   tools: [{
@@ -135,5 +161,21 @@ serve({
     } },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: record_dispositions,
+  }, {
+    name: "record_coverage_status",
+    description: "Record the status of each row of your coverage ledger. Send VALUES, not a file: one entry per ledger row, and the driver writes the record. Entries that validate are kept even when others in the same call are refused, and a later entry for the same unit replaces the earlier one.",
+    inputSchema: { type: "object", required: ["grid_spec_path", "rows"], properties: {
+      grid_spec_path: { type: "string", description: "Absolute path to the driver-written grid spec — the same one the grid tool was given." },
+      rows: {
+        type: "array",
+        description: "One entry per coverage ledger row.",
+        items: { type: "object", required: ["unit", "status"], properties: {
+          unit: { type: "string", description: "The coverage unit, exactly as your ledger row names it." },
+          status: { type: "string", enum: [...COMMON_LAW_COVERAGE_STATUSES], description: `EXACTLY one bare token of ${COMMON_LAW_COVERAGE_STATUSES.join(" / ")}. Qualifiers go in the ledger row.` },
+        } },
+      },
+    } },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: record_coverage_status,
   }],
 });

package/driver/engine/mcp/euipo-server.mjs

@@ -33,6 +33,7 @@ import {
   doEnumerate, doExecutePlan,
 } from "../../../providers/euipo/src/core.js";
 import { proposeSupplemental } from "./supplemental.mjs";
+import { narrowingFields } from "./proposal-fields.mjs";
 
 // The core resolves credentials from the environment; AUTH stays an object so a future knob (a pinned
 // environment, a second subscription) does not change every call site.
@@ -154,6 +155,7 @@ serve({
           romanization: { type: "string", description: "The Latin-script form of a NON-LATIN term. On THIS source it is NOT used to rescue the slice — nativeScriptIndex is true, so the characters are sent as themselves and the romanisation is carried for the reader only." },
           owner: { type: "string", description: "OPTIONAL owner scope field on a MARK-TEXT proposal: the owner×term intersection. Not allowed on predicate:owner (there the owner name IS the term)." },
           nice_classes: { type: "array", items: {} },
+          ...narrowingFields(),   // the narrowing fields every register serves (proposal-fields.mjs)
           rationale: { type: "string" },
           term_literal: { type: "boolean", description: "TRUE only when the term genuinely IS the mark verbatim (a multi-word slogan mark, a mark carrying an anchored star) — it bypasses the term-shape lint. Never use it to push a label through." },
         } } },

package/driver/engine/mcp/free-tier-server.mjs

@@ -34,6 +34,7 @@ import {
   CAPABILITIES, doSearch, doRecordFetch, doBatchScreen, doImageFetch, doEnumerate, doExecutePlan,
 } from "../../../providers/free-tier/src/core.js";
 import { proposeSupplemental } from "./supplemental.mjs";
+import { narrowingFields } from "./proposal-fields.mjs";
 
 // NULL, and it is not a placeholder. Each member core resolves its OWN credentials from the environment
 // — EUIPO its OAuth pair, the index its file path — so there is no single auth object a composite could
@@ -167,6 +168,7 @@ serve({
           romanization: { type: "string" },
           owner: { type: "string" },
           nice_classes: { type: "array", items: {} },
+          ...narrowingFields(),   // the narrowing fields every register serves (proposal-fields.mjs)
           rationale: { type: "string" },
           term_literal: { type: "boolean" },
         } } },

package/driver/engine/mcp/gather-config.mjs

@@ -678,7 +678,13 @@ const LOCAL = {
   // `mcp__dispositions__record_dispositions`). That is a real argv-surface change on four stages, so it
   // ships status:merged-awaiting-e2e — the byte pins in recording-grant-preservation.test.mjs move with
   // it and no live run has exercised the new name.
-  dispositions: { script: "dispositions-server.mjs", tools: ["record_dispositions"] },
+  //
+  // ── AND ITS SECOND TOOL, `record_coverage_status` — an allowlist growing by one token on an
+  // ALREADY-TOOLED key that exactly one lane holds, so no other seat gains a writer and no argv-surface
+  // transition fires. It is not a field on `record_dispositions`: a meaning ruling and a coverage status are
+  // two statements, addressed two ways, as `record_coverage` and `record_register_digest` are. Ordered by
+  // driver/skills/clearance-common-law/SKILL.md beside the coverage ledger.
+  dispositions: { script: "dispositions-server.mjs", tools: ["record_dispositions", "record_coverage_status"] },
   // ── UNIT-NOTE: the register unit's audit note, and the first own-key transport that MOVES an artifact ─
   //
   // `coverage`'s and `declination`'s shape, chosen for a reason those two did not have. Those stages keep
@@ -700,7 +706,7 @@ const LOCAL = {
   // ONE TOOL ON ITS OWN KEY, not on `register` — that key is the funnel's and a record tool added to it
   // would be enumerated into every register-unit seat's grant AND every other holder's. Same rule the
   // three entries above follow.
-  "unit-note": { script: "unit-note-server.mjs", tools: ["record_unit_note"] },
+  "unit-note": { script: "unit-note-server.mjs", tools: ["record_unit_note", "record_withheld_families"] },
   // ── RECORDING — DERIVED from the registry above, one entry per stage, in registry order ──────────
   //
   // These rows were hand-written here until the collapse. They are LAST in this object on purpose:

package/driver/engine/mcp/probe-server.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// 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
+// engine/mcp/probe-server.mjs — the one tool the engine probe asks the engine to call.
+//
+// A turn with no tools proves the credential and the model, and nothing about whether the engine can use
+// the tools every search stage is given. On some hosts codex's own sandbox refuses every tool call while
+// the turn reports success, and a probe with no tool passed there. So the probe hands the engine this
+// server, asks it to call `ping` once, and passes only when the reply carries what `ping` returned.
+//
+// WHAT IT RETURNS IS THE PROOF. Its one argument is a random word the probe mints for each
+// turn and gives only to this process, so a reply that carries it cannot be the model guessing. It touches
+// no file, no network and no run.
+//
+// IT IS DECLARED AS THE REGISTER SEARCH IS DECLARED, NOT AS WHAT IT DOES. codex decides from a tool's
+// annotations whether a call needs approval, and `codex exec` refuses every call that does ("MCP tool call
+// requires approval, but approval policy is never") unless its sandbox is bypassed. A read-only tool never
+// needs approval, so a read-only `ping` passed on hosts where `register_execute_plan` — marked not
+// read-only and open-world on every register server — was refused on every call and no search could run.
+// The probe exists to answer for the tools a search calls, so its tool carries that tool's annotations,
+// and a test keeps the two equal. The rule, in codex's own source, identical from 0.150.1 to 0.156.1:
+// read-only → no approval; otherwise approval when destructive, or open-world, or either left unmarked.
+import { serve } from "./stdio-server.mjs";
+
+serve({
+  name: "probe", version: "0.1.0",
+  tools: [{
+    name: "ping",
+    description: "Return the word this check is waiting for.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async () => {
+      const word = String(process.argv[2] ?? "").trim();
+      return word ? word : { isError: true, text: "ping: this server was started without a word to return" };
+    },
+  }],
+});

package/driver/engine/mcp/proposal-fields.mjs

@@ -0,0 +1,45 @@
+// 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
+// proposal-fields.mjs — the narrowing fields of `register_propose_supplemental`, ONE definition for every
+// register's server.
+//
+// The reading turn narrows a crowded identical question through this tool: by goods words, by market
+// (`regions`), and it names the crowd it replaces (`narrows`). The shared mint (supplemental.mjs) has
+// handled all three for every register, but only the Clarivate server declared them, and Corsearch
+// declared `regions` alone. A model reads the schema it is served, so on Signa the reading turn could
+// narrow only by class. The product is register-agnostic: every server now spreads these same
+// properties into its proposal schema, and what differs by register is a capability fact the server
+// passes in, never a missing field.
+//
+// The words are the shipped words, moved rather than rewritten: the goods and `narrows` text is what the
+// Clarivate server already served, and each server keeps the `regions` sentence it (or its sibling
+// register) already carried. A register that cannot search goods text, or cannot offer alternatives in
+// one goods clause, is handled in the mint, the same way the compiler handles it.
+
+const GOODS_WORDS = "OPTIONAL goods narrowing on a MARK-TEXT proposal: the same question, limited to filings whose "
+  + "goods and services description carries one of these words. This is the FIRST move when the identical mark comes "
+  + "back as a count instead of a list — the words are the ones the variants stage already wrote for this matter, the "
+  + "client's own wording plus the synonyms. Single words or short phrases as a specification would write them, no "
+  + "wildcards. Not allowed on predicate:owner.";
+
+const NARROWS = "OPTIONAL: the qid of the CROWDED question this proposal replaces. Put it on a narrowing — the same "
+  + "question limited by goods, by market, by the dominant word or to one class — so the record shows the crowd and the "
+  + "question that answered it side by side, each with its own count. A narrowing that does not name what it replaced "
+  + "leaves the crowd looking unanswered.";
+
+/** The `regions` sentence a register whose requests need no office carries (shipped on Corsearch). */
+export const REGIONS_CODES = "UPPERCASE 2-letter region codes, e.g. ['US','EU','CH'] — never spelled-out names "
+  + "(recognized display names are normalized; unknown values are rejected)";
+
+/**
+ * The three narrowing properties, for a proposal item's `properties`.
+ * @param opts.regions   the register's `regions` description (REGIONS_CODES unless the register states more)
+ * @param opts.goodsNote a sentence appended to the goods description, for a register fact the model must know
+ */
+export function narrowingFields({ regions = REGIONS_CODES, goodsNote = "" } = {}) {
+  return {
+    goods_words: { type: "array", items: { type: "string" }, description: goodsNote ? `${GOODS_WORDS} ${goodsNote}` : GOODS_WORDS },
+    regions: { type: "array", items: { type: "string" }, description: regions },
+    narrows: { type: "string", description: NARROWS },
+  };
+}