clearotron 0.3.2 → 0.3.3-beta.1

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

@@ -497,6 +497,19 @@ serve({
         },
         watchlist_owners: { type: "array", items: { type: "string" },
           description: "Real register owners the plan compiles owner lanes from — never sectors or descriptions." },
+        goods_words: { type: "array", items: { type: "string" },
+          description:
+            "The words the register search is narrowed to: the client's own goods and services wording " +
+            "first, then the words other filings use for the same goods that it does not already " +
+            "contain. Single words or short phrases as a specification would write them, no wildcards, " +
+            "at most 24. Each is matched against the goods and services description of registered " +
+            "marks, so use words a specification would contain; a word broader than the goods widens " +
+            "the search instead of narrowing it. The register cannot read the words and, or, not, adj " +
+            "or near inside an item — an item containing one is searched without it. Send an EMPTY " +
+            "LIST when you have considered the goods and no word is worth narrowing by; omit the " +
+            "field only when the matter states no goods at all. Those are different answers and the " +
+            "run records which one you gave.",
+        },
         scope_ledger: {
           type: "array",
           description:
@@ -826,6 +839,23 @@ serve({
             },
           },
         },
+        // THE SAME DEFECT TWICE MORE, and the same fix. The dispatch asks for both of these in its own
+        // imperative, the acceptor validates and records them, and the plan compile reads the classes —
+        // and until now neither was a property here, so a frame following its schema could send neither.
+        // A real run's frame carried no added class although the goods reached one. Shape only: the
+        // dispatch already says what to send and why, so no sentence the model reads is added here.
+        identified_classes: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["class", "reason"],
+            properties: {
+              class: { type: "integer", minimum: 1, maximum: 45 },
+              reason: { type: "string" },
+            },
+          },
+        },
+        ratified_forms: { type: "array", items: { type: "string" } },
         // OFFERED HERE, OR NEVER SENT. The acceptor took this field for a beta and the plan acted on it,
         // and no frame ever proposed one, because the schema a model is given did not offer it. Worded as
         // the owner approved it; it is model-facing prose, so its wording is his.

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

@@ -11,6 +11,7 @@
 import { serve } from "./stdio-server.mjs";
 import { doSearch, doRecordFetch, doEnumerate, doExecutePlan, DEFAULT_BASE } from "../../../providers/signa/src/core.js";
 import { proposeSupplemental } from "./supplemental.mjs";
+import { narrowingFields } from "./proposal-fields.mjs";
 import { CAPABILITIES } from "../../../providers/signa/src/capabilities.js";
 
 const API_KEY = process.env.SIGNA_API_KEY || "";
@@ -101,6 +102,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, served by filters.owner_name in the same request. 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/supplemental.mjs

@@ -30,7 +30,7 @@
 import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { driverDir } from "../../../shared/driver-dir.mjs";   //
-import { PLAN_PREDICATES, PLAN_MAX_OR_WIDTH, PLAN_MAX_NAME_LENGTH, fingerprint, ownerIntersectionGap, resolveRegions, houseElementOf, withoutHouseElementTerms } from "../../register-plan.mjs";
+import { PLAN_PREDICATES, PLAN_MAX_OR_WIDTH, PLAN_MAX_NAME_LENGTH, fingerprint, ownerIntersectionGap, goodsTextGap, resolveRegions, houseElementOf, withoutHouseElementTerms, containsFormSubstitution } from "../../register-plan.mjs";
 import { entryTermIssues } from "../../../providers/_shared/term-shape.mjs";
 import { isNonLatinTerm, romanizationRefusal, romanizationSpellings, nativeScriptIndexGap } from "../../../providers/_shared/script-form.mjs";
 
@@ -64,13 +64,37 @@ export function mintSupplementalEntries(axis, proposals, { existingQids = new Se
   // first, non-priority ones keep their relative order behind them. The cap VALUES are unchanged
   // (no count threshold moves), and with no priorityClasses the order is byte-identical to before.
   const prio = new Set((priorityClasses ?? []).map((c) => String(c).trim()).filter(Boolean));
-  const indexed = (proposals ?? []).map((p, i) => ({ p: p ?? {}, i }));
+  // ONE QUESTION PER GOODS WORD where the register cannot offer alternatives in one goods clause — the
+  // compiler's own rule for such a register (register-plan.mjs, goodsTextListOr). Joined, the words would
+  // be intersected and the answer would narrow as the list grew; the connector refuses that shape
+  // outright. Each word keeps the proposal's index, so a refusal still names the proposal it came from.
+  const perWord = capabilities?.goodsTextSearch === true && capabilities?.goodsTextListOr === false;
+  // ONE QUESTION PER NAME where the register has no OR at all (maxOrWidth 1) — the compiler's own width
+  // for such a register. A batch of names went out as windows of one name each under ONE question, and
+  // the enumerate kernel stopped the whole batch at the first name that crowded or failed, so every name
+  // after it was never sent. Split, each name is its own question: its own count, its own crowd decision
+  // and its own receipt row. The names of one batch still spend ONE slot of the per-call and per-axis
+  // caps between them, as the batch did; `split_of` names the batch so the next call counts it once.
+  const perName = Number(capabilities?.maxOrWidth) === 1;
+  const indexed = (proposals ?? []).flatMap((p, i) => {
+    const names = perName && Array.isArray(p?.terms) ? p.terms.map((t) => String(t ?? "").trim()).filter(Boolean) : [];
+    const splitOf = names.length > 1 && names.length <= PLAN_MAX_OR_WIDTH
+      ? fingerprint({ axis, predicate: String(p?.predicate ?? "default"), names: [...names].sort(), i }) : null;
+    const byName = splitOf ? names.map((t) => { const { terms: _batch, ...rest } = p; return { ...rest, term: t }; }) : [p ?? {}];
+    return byName.flatMap((q) => {
+      const words = perWord && Array.isArray(q?.goods_words) ? q.goods_words.map((w) => String(w ?? "").trim()).filter(Boolean) : [];
+      return words.length > 1
+        ? words.map((w, k) => ({ p: { ...q, goods_words: [w] }, i, slot: `${i}:${k}`, splitOf }))
+        : [{ p: q, i, slot: `${i}:0`, splitOf }];
+    });
+  });
+  const slots = new Set();
   const ordered = prio.size
     ? [...indexed.filter(({ p }) => inPriority(p, prio)), ...indexed.filter(({ p }) => !inPriority(p, prio))]
     : indexed;
-  for (const { p, i } of ordered) {
+  for (const { p, i, slot, splitOf } of ordered) {
     const issue = (msg) => rejected.push({ index: i, issue: msg, proposal: compactProposal(p) });
-    if (minted.length >= perCall) { issue(`per-call cap ${perCall} reached`); continue; }
+    if (!slots.has(slot) && slots.size >= perCall) { issue(`per-call cap ${perCall} reached`); continue; }
     const predicate = String(p.predicate ?? "default");
     if (!PLAN_PREDICATES.includes(predicate)) { issue(`unknown predicate "${predicate.slice(0, 20)}" (one of: ${PLAN_PREDICATES.join(", ")})`); continue; }
     const terms = Array.isArray(p.terms) ? p.terms.map((t) => String(t ?? "").trim()).filter(Boolean) : null;
@@ -107,6 +131,15 @@ export function mintSupplementalEntries(axis, proposals, { existingQids = new Se
       if (!isNonLatinTerm(term)) { issue(`a romanization belongs ONLY on a non-Latin term — "${term.slice(0, 40)}" is already Latin script, so this romanization transliterates a DIFFERENT string; drop it or fix the term`); continue; }
       romanizedTerms = romanizationSpellings(romanRaw);
     }
+    // THE GOODS NARROWING, validated where every other field is. Whole words or short phrases as a
+    // specification writes them; a wildcard is a hard refusal on this field at the register, and an
+    // operator word inside an item is stripped downstream by the shared reader, so nothing here needs
+    // to invent a second rule for either.
+    const goodsWords = (Array.isArray(p.goods_words) ? p.goods_words : (typeof p.goods_words === "string" ? [p.goods_words] : []))
+      .map((w) => String(w ?? "").trim()).filter(Boolean);
+    if (p.goods_words != null && !goodsWords.length) { issue("goods_words, when present, must carry at least one word"); continue; }
+    if (goodsWords.some((w) => /[*?]/.test(w))) { issue("a goods word carries a wildcard, which this register refuses on that field"); continue; }
+    if (goodsWords.length && predicate === "owner") { issue("goods_words narrows a MARK-TEXT question; on predicate:owner the owner name is the term"); continue; }
     const term_literal = p.term_literal === true;
     // A1 — the same term-shape/term-predicate lint the plan freeze enforces, at the PROPOSAL seam:
     // the model gets the reason IN-TURN (rejected[]) and can re-propose the mark-shaped term — a
@@ -205,6 +238,19 @@ export function mintSupplementalEntries(axis, proposals, { existingQids = new Se
         for (const r of covered) regions.push(r);
       }
     }
+    // A CONTAINS-FORM PROPOSAL ON A TERM SHORTER THAN THE REGISTER'S FLOOR is asked on the exact form,
+    // the rule the compiler applies to its own goods-narrowed questions and saturation probes: the
+    // register refuses the contains form for a term that short, so the question as proposed would come
+    // back as an error rather than an answer. Same classes, goods words and scope, one entry for one,
+    // and the entry says so. Decided BEFORE the fingerprint, so the qid names the question actually
+    // asked. A stack is switched only when every member is below the floor; a mixed stack keeps the
+    // form the model chose, and its short members are refused and disclosed on their own.
+    let askedPredicate = predicate;
+    let substituted = null;
+    if (predicate === "default") {
+      const subs = (terms ?? [term]).map((t) => containsFormSubstitution(t, capabilities));
+      if (subs.length && subs.every(Boolean)) { askedPredicate = "exact"; substituted = subs[0]; }
+    }
     const anchor = terms ? terms[0] : term;
     // The fingerprint (⇒ the qid) deliberately EXCLUDES the romanization: the qid names the QUESTION
     // (which term, which predicate, which scope) and the romanisation is carriage, not a different
@@ -212,37 +258,68 @@ export function mintSupplementalEntries(axis, proposals, { existingQids = new Se
     // with the Latin form added — the exact wedge shape the regions inheritance above exists to kill.
     // Instead a re-proposal that adds a romanisation to a stored bare qid ENRICHES it (below), the
     // same field-level, never-term-changing merge extendRegisterPlan applies to the dictated plan.
-    const fp = String(fingerprint({ predicate, term: term || null, terms: terms || null, nice_classes: nice, regions, ...(owner ? { owner } : {}) })).replace(/^fnv1a:/, "");
-    const qid = `supp:${axis}:${predicate}:${slug(anchor)}:${fp.slice(0, 8)}`;
+    // …and it deliberately INCLUDES the goods narrowing, for the opposite reason. A goods-limited
+    // re-ask of a crowded question is the same term, predicate, classes and scope — it differs only by
+    // what the filings must cover. Excluded, it would mint the crowd's own qid and be read as a
+    // re-proposal of the question it exists to replace, so the first move against a crowd would
+    // silently become no move at all.
+    const fp = String(fingerprint({ predicate: askedPredicate, term: term || null, terms: terms || null, nice_classes: nice, regions,
+      ...(owner ? { owner } : {}), ...(goodsWords.length ? { goods: [...goodsWords].sort() } : {}) })).replace(/^fnv1a:/, "");
+    const qid = `supp:${axis}:${askedPredicate}:${slug(anchor)}:${fp.slice(0, 8)}`;
     if (existingQids.has(qid) || minted.some((e) => e.qid === qid)) {
       reused.push(qid);
       if (romanizedTerms && existingQids.has(qid)) enriched.push({ qid, term, romanizedTerms });
       continue;
     }
-    if (budget <= 0) { issue(`per-axis cap ${axisMax} reached — assess whether an existing supplemental already covers this`); continue; }
-    budget -= 1;
+    if (!slots.has(slot)) {
+      if (budget <= 0) { issue(`per-axis cap ${axisMax} reached — assess whether an existing supplemental already covers this`); continue; }
+      budget -= 1;
+    }
+    slots.add(slot);
     const entry = {
-      qid, axis, predicate,
+      qid, axis, predicate: askedPredicate,
+      ...(substituted ? { contains_substituted: substituted } : {}),
       ...(terms ? { terms } : { term }),
       ...(romanizedTerms ? { romanizedTerms } : {}),
       ...(owner ? { owner } : {}),
+      // Carried as `goods_text`, the field the plan and every connector already speak — the tool calls
+      // it `goods_words` because that is what the manual and the manifest call it to the model.
+      ...(goodsWords.length ? { goods_text: goodsWords } : {}),
+      // What this question REPLACED. The ledger shows the crowd and its narrowing together, each with
+      // its own count, so a crowd never reads as a question nobody answered.
+      ...(typeof p.narrows === "string" && p.narrows.trim() ? { narrows: p.narrows.trim().slice(0, 200) } : {}),
       ...(term_literal ? { term_literal: true } : {}),
       nice_classes: nice, regions,
       expected_kind: "enumerate",
       origin: "supplemental",
+      ...(splitOf ? { split_of: splitOf } : {}),
       ...(typeof p.rationale === "string" && p.rationale.trim() ? { rationale: p.rationale.trim().slice(0, 200) } : {}),
     };
     // F1 — an owner×term slice on a provider that cannot intersect them is minted as an UNSUPPORTED
     // entry (→ the executor's deferred lane → a disclosed coverage row), exactly like a missing
     // predicate at compile time. Never rejected (the gap belongs on the record) and never silently
     // widened into an owner-less sweep.
-    const ownerGap = ownerIntersectionGap(entry, capabilities);
-    if (ownerGap) { entry.unsupported = true; entry.unsupported_reason = ownerGap; }
+    // …and a goods narrowing on a register that cannot search goods text is the same kind of gap, with
+    // the compiler's own reason (goodsTextGap): recorded, never run on the class alone, which would ask the
+    // crowd the narrowing exists to cut.
+    const gap = ownerIntersectionGap(entry, capabilities) ?? goodsTextGap(entry, capabilities);
+    if (gap) { entry.unsupported = true; entry.unsupported_reason = gap; }
     minted.push(entry);
   }
   return { minted, reused, rejected, enriched, narrowed };
 }
 
+/** The per-axis cap's count of what is already on file: the names of one split batch are one slot. PURE. */
+export function supplementalSlots(entries) {
+  const batches = new Set();
+  let n = 0;
+  for (const e of (entries ?? [])) {
+    if (e?.split_of) { if (!batches.has(e.split_of)) { batches.add(e.split_of); n += 1; } }
+    else n += 1;
+  }
+  return n;
+}
+
 /**
  * Append mint-rejection rows to a supplemental-plan doc's `rejected[]` (append-only, beside
  * entries[] — one sidecar per axis holds BOTH what folded into the plan and what died at the seam,
@@ -326,7 +403,7 @@ export async function proposeSupplemental(params, tctx, deps) {
     return { type: "text", text: JSON.stringify({ minted: [], reused: [], rejected: [], excluded_house_element: excludedHouse, executed: false }, null, 2) };
   const existingQids = new Set(supp.entries.map((e) => e.qid));
   const { minted, reused, rejected, enriched, narrowed } = mintSupplementalEntries(axis, offered,
-    { existingQids, perCall, axisMax, existingCount: supp.entries.length, capabilities: deps.capabilities ?? null, priorityClasses: planClasses });
+    { existingQids, perCall, axisMax, existingCount: supplementalSlots(supp.entries), capabilities: deps.capabilities ?? null, priorityClasses: planClasses });
 
   // Field-level romanisation enrichment of a REUSED qid (2026-07-30 review round): the natural retry —
   // a bare non-Latin proposal deferred at the wire, the model re-proposes it WITH the romanisation —

package/driver/engine/mcp/unit-note-server.mjs

@@ -40,6 +40,7 @@
 // for it and this tool never guesses one.
 import { serve } from "./stdio-server.mjs";
 import { recordUnitNote } from "../../register-unit-record.mjs";
+import { recordWithheldFamilies, WITHHELD_REASON_MAX } from "../../withheld-families.mjs";
 
 async function record_unit_note(params) {
   const runDir = String(process.env.CLEAROTRON_BAND_RUN_DIR ?? "");
@@ -66,6 +67,38 @@ async function record_unit_note(params) {
   }
 }
 
+// ── THE FAMILIES THE READING TURN LEAVES UNASKED (withheld-families.mjs) ───────────────────────────
+//
+// Same server, same binding: the axis is the one the driver fanned this seat out for, and a payload
+// naming another is refused. What it records is a judgment only this turn can make — which waiting
+// families were not worth asking, and why — so it lives beside the turn's note rather than on the
+// digest's coverage tool, which never saw the families.
+async function record_withheld_families(params) {
+  const runDir = String(process.env.CLEAROTRON_BAND_RUN_DIR ?? "");
+  if (!runDir) return { isError: true, text: "ERROR: this server was started without a run — the driver wires it per run; there is no parameter for it and this tool never guesses one." };
+  const bound = String(process.env.CLEAROTRON_RECORD_AXIS ?? "").trim();
+  if (!bound) return { isError: true, text: "ERROR: this server was started without a bound axis — the driver binds the axis it fanned out for." };
+  const named = String(params?.axis ?? "").trim();
+  if (named && named !== bound)
+    return { isError: true, text: `ERROR: unit_axis_not_yours:${named} — you are the seat for axis "${bound}". Send "${bound}" or omit the field.` };
+  try {
+    const r = recordWithheldFamilies(runDir, { axis: bound, families: params?.families });
+    if (r.refused) return { isError: true, text: `REFUSED: ${r.refused}` };
+    if (r.write_failed) return { isError: true, text: `ERROR: the driver could not store this record (${r.write_failed}). This is a driver fault — do not re-type it.` };
+    const refused = r.rejected.map((x) => `- ${x.qid || "(no qid)"}: ${x.issue}`);
+    const left = r.still_to_judge;
+    return { isError: !r.recorded.length && refused.length > 0, text: [
+      `Recorded ${r.recorded.length} famil${r.recorded.length === 1 ? "y" : "ies"} as withheld-by-judgment on axis "${r.axis}".`,
+      ...(refused.length ? ["Refused:", ...refused] : []),
+      left.length
+        ? `Still to judge on this axis — waiting, not asked, no reason recorded (${left.length}): ${left.slice(0, 40).join(", ")}${left.length > 40 ? ", …" : ""}`
+        : "Every waiting family on this axis is now asked or recorded.",
+    ].join("\n") };
+  } 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 — do not re-type it.` };
+  }
+}
+
 serve({
   name: "unit-note", version: "0.1.0",
   tools: [{
@@ -84,5 +117,22 @@ serve({
     } },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: record_unit_note,
+  }, {
+    name: "record_withheld_families",
+    description:
+      "Record the WAITING families on this axis that you decided NOT to ask, each with your reason. A family you " +
+      "do not ask was never searched: it is recorded withheld-by-judgment, and the reason goes into the run's " +
+      "record and the audit workbook, never into the report. Every waiting family must end this run either asked " +
+      "or recorded here — one nobody judged holds up delivery. One reason may cover several families. The answer " +
+      "lists the waiting families on this axis that are still neither asked nor recorded.",
+    inputSchema: { type: "object", required: ["families"], properties: {
+      families: { type: "array", items: { type: "object", required: ["qids", "reason"], properties: {
+        qids: { type: "array", items: { type: "string" }, description: "The qids of waiting families on this axis, exactly as the dispatch lists them." },
+        reason: { type: "string", description: `Why these were not asked, in a lawyer's words (at most ${WITHHELD_REASON_MAX} characters). The audit workbook prints it.` },
+      } } },
+      axis: { type: "string", description: "Optional, and checked rather than trusted: the driver binds the axis it dispatched you for." },
+    } },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: record_withheld_families,
   }],
 });

package/driver/engine/mcp/uspto-local-server.mjs

@@ -36,6 +36,7 @@ import {
   CAPABILITIES, DEFAULT_DB_ENV, doSearch, doRecordFetch, doBatchScreen, doEnumerate, doExecutePlan,
 } from "../../../providers/uspto-local/src/core.js";
 import { proposeSupplemental } from "./supplemental.mjs";
+import { narrowingFields } from "./proposal-fields.mjs";
 
 const DB_PATH = process.env[DEFAULT_DB_ENV] || "";
 // The auth object IS the index path — see the core's header. Passed as an object rather than a bare
@@ -139,6 +140,7 @@ 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. On THIS source it does not rescue the slice: nativeScriptIndex is undeclared, so a non-Latin term defers and is disclosed rather than being answered by its romanisation." },
           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: {} },
+          ...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/openai-agent.mjs

@@ -23,6 +23,7 @@
 // `--dangerously-bypass-approvals-and-sandbox` — see buildCodexArgs below for why.
 
 import { mkdtempSync, writeFileSync, copyFileSync, existsSync, rmSync, readFileSync, readdirSync, statSync, symlinkSync, lstatSync, realpathSync } from "node:fs";
+import { everyToolCallRefused } from "./tool-refusal.mjs";
 import { writeSecretFile } from "../../shared/secret-file.mjs";   // the rotated login goes back the way every credential is written
 import { tmpdir, homedir } from "node:os";
 import { join } from "node:path";
@@ -531,6 +532,12 @@ function settleTuple({ r, ev, resumeRef }) {
       // The engine's sign-in could not be refreshed: what the operator runs to fix it. The gateway names the
       // stage's failure with it.
       signedOut: signedOut ? "codex sign-in expired — run `codex login`, then start the search again" : undefined,
+      // Every tool call refused and none completed: codex's own sandbox on this host, and what fixes it. The
+      // turn is still `ok` here; when the stage then fails, the gateway names its failure with this, as it
+      // names a sign-in, instead of the missing file the refusal left behind.
+      toolsRefused: everyToolCallRefused(mcpToolGauge(ev))
+        ? "codex refused every tool call this search needs — set CLEAROTRON_CODEX_SANDBOX_BYPASS=1 in this install's environment file, or use the Anthropic engine, then start the search again"
+        : undefined,
       rateLimitBasis: rateLimited ? "text-match" : undefined,
       // resetsAtBasis (2026-08-20): same honesty as rateLimitBasis one line up, for the reset
       // CLOCK rather than the classification. codex states its reset as human prose with NO timezone

package/driver/engine/probe.mjs

@@ -15,11 +15,20 @@
 //
 // THE CHEAPEST TURN THAT PROVES THE WHOLE PATH
 //
-// One `haiku`-tier turn at `low` effort on a six-word prompt, with no MCP config, no allowed tools, no
-// skills dir and no run dir — the smallest argv either adapter can build. It exercises every link a
-// stage uses: binary → spawn → billing mode → credential → model access → a completed turn parsed by
-// the adapter's own settle path. And it is far lighter than the thing it protects: one register-sweep
-// stage prompt inlines 150 KB of plan and runs for minutes.
+// One `haiku`-tier turn at `low` effort, asked to call one tool, with no skills dir and no run dir. The
+// tool is `ping` on engine/mcp/probe-server.mjs, handed over exactly as a stage hands over its own.
+//
+// WHY IT CALLS A TOOL. It used to call none, and a turn with no tools proves nothing about the tools every
+// search stage is given. On some hosts codex's own sandbox refuses every tool call while the turn reports
+// success; the probe passed there, and every search then failed after real spend. So the probe now passes
+// only when the reply carries the word `ping` returned, a random word minted for this turn and given to
+// that server alone, so the model cannot supply it. Every call refused is a configuration fault, refused at
+// the door; no call and no word shows nothing either way, and warns.
+//
+// It exercises every link a stage uses: binary → spawn → billing mode → credential → model access → a tool
+// call through the stage's own tool path → a completed turn parsed by the adapter's own settle path. And
+// it is far lighter than the thing it protects: one register-sweep stage prompt inlines 150 KB of plan and
+// runs for minutes.
 //
 // WHAT IT DOES NOT PROVE, said out loud. It exercises the CHEAP tier. Both tiers ride one credential on
 // a subscription, so AUTH is proven for all of them; a per-tier model entitlement or a per-tier quota is
@@ -56,9 +65,28 @@
 
 import { ENGINE_BINARIES, DEFAULT_ENGINE_ID, engineAdapterSpecifier, resolveEngineProgram } from "../driver.config.mjs";
 import { resolveAuthMode, CLOUD_SETTINGS, CLOUD_CREDENTIAL_CHECK } from "./auth.mjs";
+import { everyToolCallRefused } from "./tool-refusal.mjs";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+/** One tool call and one word back: short enough to be free in practice, and it needs a working tool path. */
+export const PROBE_PROMPT = "Call the ping tool once, then reply with exactly the word it returned.";
+/** The server and tool the probe hands the engine, named as a stage names its own (`mcp__<server>__<tool>`). */
+export const PROBE_SERVER = "probe";
+export const PROBE_TOOL = "ping";
+const PROBE_SERVER_PATH = fileURLToPath(new URL("./mcp/probe-server.mjs", import.meta.url));
+
+/** The tool config for one probe turn, in the shape both adapters take from a stage. */
+export function probeToolConfig(sentinel) {
+  return {
+    mcpConfig: JSON.stringify({ mcpServers: { [PROBE_SERVER]: {
+      command: process.execPath, args: [PROBE_SERVER_PATH, String(sentinel)], env: {} } } }),
+    allowedTools: `mcp__${PROBE_SERVER}__${PROBE_TOOL}`,
+  };
+}
 
-/** Six words. Short enough to be free in practice, and it still requires a real completed turn. */
-export const PROBE_PROMPT = "Reply with the single word: ok.";
+/** A word no model would produce unprompted, fresh per turn. */
+export const mintProbeSentinel = () => `probe-${randomBytes(4).toString("hex")}`;
 /** The CHEAP rung of the driver's tier vocabulary on BOTH adapters (engine/CONTRACT.md §3). */
 export const PROBE_MODEL = "haiku";
 /** The floor rung of both EFFORT tables. There is nothing below `low` on anthropic. */
@@ -159,7 +187,7 @@ const capitalised = (s) => s.charAt(0).toUpperCase() + s.slice(1);
  * (`{ source, path }`); both only shape the advice, never the mode, so the run door refuses exactly what it
  * refused before. Absent, the advice is the subscription's, naming the bare program word.
  */
-export function classifyProbe({ engine, tuple = null, error = null, timeoutSec = PROBE_TIMEOUT_SEC, auth = null, program = null } = {}) {
+export function classifyProbe({ engine, tuple = null, error = null, timeoutSec = PROBE_TIMEOUT_SEC, auth = null, program = null, expect = null } = {}) {
   const id = String(engine ?? "").trim().toLowerCase();
   const v = (mode, basis, headline, fix, extra = {}) =>
     ({ ok: false, engine: id, mode, basis, headline, fix, detail: null, ...extra });
@@ -197,6 +225,21 @@ export function classifyProbe({ engine, tuple = null, error = null, timeoutSec =
   // which pipe this happened to look at.
   const detail = tail(tuple.stderr) ?? tail(tuple.stdout);
 
+  // THE TOOL, ON A TURN THAT COMPLETED. `expect` is the word the probe's tool returns, and only a probe that
+  // handed the engine a tool passes one; without it a completed turn proves what it always proved. With
+  // it, three outcomes, never two. Every call refused is this machine's configuration, read off the
+  // adapter's own gauge, and the run door refuses on it. The word in the reply is the pass. Neither is a
+  // turn that shows nothing about the tools either way: not a pass, and not this box's fault to refuse on.
+  if (tuple.code === 0 && expect != null) {
+    if (everyToolCallRefused(tuple))
+      return v("tools-refused", "tool-gauge", `${id} refused every tool call it was given`, toolsRefusedFix(id),
+        { detail: tail(tuple.mcpToolCallRefusals?.[0]?.message) });
+    if (!String(tuple.stdout ?? "").includes(String(expect)))
+      return v("tools-unproven", "no-tool-answer", `${id} did not return the word its probe tool gives`,
+        "Nothing here shows that the tools a search needs work on this machine. Run this again; if it repeats, a search is likely to fail the same way.",
+        { detail: tail(tuple.stdout) });
+  }
+
   // A completed turn names what served it, the model and the provider as the program reported them, and
   // null where it named neither, so a proof says which model and whose account it proved.
   if (tuple.code === 0) return { ok: true, engine: id, mode: "ok", basis: "completed-turn", headline: `${id} completed a turn`, fix: null, detail: null,
@@ -234,7 +277,7 @@ export function classifyProbe({ engine, tuple = null, error = null, timeoutSec =
     return v("tier-unavailable", "text-match", `${id} cannot reach the model it was asked for`, tierFix(id, text), { detail });
 
   if (tuple.killed || s.stalled || s.hardWall)
-    return v("timed-out", "watchdog", `${id} started but did not finish a six-word turn in ${timeoutSec}s`,
+    return v("timed-out", "watchdog", `${id} started but did not finish its probe turn in ${timeoutSec}s`,
       "The binary runs and the turn produces nothing. Run the CLI by hand once and see what it is waiting for — an unanswered login prompt and a wedged MCP server both look like this.", { detail });
 
   // The anthropic adapter's own diagnosis: the CLI exited without emitting a single stream event, i.e.
@@ -250,6 +293,14 @@ export function classifyProbe({ engine, tuple = null, error = null, timeoutSec =
     "The engine's stderr below is the whole story; a turn that starts and fails is not a configuration this check can name.", { detail });
 }
 
+/** What fixes a host that refuses every tool call. On codex it is its own sandbox, and the setting is named. */
+function toolsRefusedFix(engine) {
+  if (engine === "openai-agent")
+    return "Every search stage calls tools, so no search can finish here. codex's own sandbox refuses them on this machine: "
+      + "set CLEAROTRON_CODEX_SANDBOX_BYPASS=1 in this install's environment file, or use the Anthropic engine, then run this again.";
+  return "Every search stage calls tools, so no search can finish here. The engine's stderr below is the place to start.";
+}
+
 /** The one place the tier doctrine is POINTED AT rather than re-authored. */
 function tierFix(engine, msg) {
   if (engine === "openai-agent")
@@ -290,7 +341,7 @@ export function probeFailureText(verdict) {
 // classify is by definition one the door cannot claim to understand — and the cost of being wrong runs
 // the other way here: refusing wrongly kills a run that would have worked, proceeding wrongly costs the
 // stages before a failure the engine was going to produce anyway.
-const CONFIGURATION_MODES = new Set(["unknown-engine", "auth-misconfigured", "signed-out", "tier-unavailable", "cannot-spawn"]);
+const CONFIGURATION_MODES = new Set(["unknown-engine", "auth-misconfigured", "signed-out", "tier-unavailable", "cannot-spawn", "tools-refused"]);
 
 // …and a mode alone is not enough, because `basis` says HOW WELL the mode is known and the ladder already
 // makes that distinction for its own reasons. `startup-class` is an INFERENCE FROM SILENCE — the CLI died
@@ -299,7 +350,8 @@ const CONFIGURATION_MODES = new Set(["unknown-engine", "auth-misconfigured", "si
 // hosted runner where a hermetic PATH left `env` unable to resolve node, and the probe "correctly reported
 // a startup-class engine death" on a machine whose engine was fine. Refusing a production run on that
 // inference manufactures the outage it was written to prevent, so it warns instead.
-const NAMED_BASES = new Set(["config", "text-match", "spawn-error"]);
+// `tool-gauge` is named, not inferred: the adapter counted each refused call off the engine's own stream.
+const NAMED_BASES = new Set(["config", "text-match", "spawn-error", "tool-gauge"]);
 
 /**
  * "ok" | "configuration" | "weather" — PURE, and the whole of the door's judgment.
@@ -465,8 +517,9 @@ export async function probeEngineTurn({
     // the environment back whatever it does. A resolver that cannot answer leaves the bare word.
     if (knownProgram?.path) program = { source: knownProgram.source ?? null, path: knownProgram.path };
     else try { const r = resolveEngineProgram(id); program = r.resolved ? { source: r.source, path: r.resolved } : null; } catch { /* the bare word */ }
-    const tuple = await turn({ message: PROBE_PROMPT, model: PROBE_MODEL, thinking: PROBE_THINKING, timeoutSec, stallSec });
-    return classifyProbe({ engine: id, tuple, timeoutSec, auth, program });
+    const sentinel = mintProbeSentinel();
+    const tuple = await turn({ message: PROBE_PROMPT, model: PROBE_MODEL, thinking: PROBE_THINKING, timeoutSec, stallSec, ...probeToolConfig(sentinel) });
+    return classifyProbe({ engine: id, tuple, timeoutSec, auth, program, expect: sentinel });
   } catch (e) {
     return classifyProbe({ engine: id, error: e, timeoutSec, auth, program });
   } finally {
@@ -479,7 +532,7 @@ export async function probeEngineTurn({
  *
  * The choice, stated so nobody has to re-decide it. The register-credential precedent refuses because a
  * run whose work is impossible must say so before it costs anything, and the reasoning transfers exactly:
- * every one of the fourteen stages spawns the engine, so an engine that cannot complete a six-word turn
+ * every one of the fourteen stages spawns the engine, so an engine that cannot complete its probe turn
  * cannot complete any of them. A warning would let the run build its directory, freeze its profile and
  * write its status sidecar, then die at stage one leaving a resumable-looking husk and a failure wearing
  * the shape of a model fault — which is the precise outcome preflightEngineBinary exists to prevent, and

package/driver/engine/tool-refusal.mjs

@@ -0,0 +1,16 @@
+// 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/tool-refusal.mjs — one definition of "this turn's every tool call was refused", for the two
+// places that act on it: the gateway, which stops a stage's retries and names the failure, and the engine
+// probe, which refuses a host where it happens before a search is paid for. Two copies would drift.
+
+/**
+ * Every tool call the turn made was refused, and none completed. Read off the adapter's own gauge
+ * (`mcpToolCalls` / `mcpToolCallsRefused`), which counts a refusal only when the call never reached its
+ * server — a tool that ran and errored is not one. One refused call beside a completed one is a model
+ * asking for something it may not have, not a host that refuses tools, so it does not count. An engine
+ * that keeps no gauge reports nothing, and nothing is not a refusal. Pure.
+ */
+export function everyToolCallRefused(turn) {
+  return Number(turn?.mcpToolCallsRefused ?? 0) > 0 && Number(turn?.mcpToolCalls ?? 0) === 0;
+}

package/driver/enqueue-schema.mjs

@@ -28,7 +28,7 @@ import { productName, productSpec, checkProductScope, checkNativeLanguage, unkno
 import { partitionTerritories } from "./territory-tiers.mjs";
 // — the sidecar field map, from the module that OWNS it. The check below asks whether the prose a
 // manifest declared actually arrived, and a local copy of that list is how the two would drift apart.
-import { PROSE_PARTS } from "./queue-markers.mjs";
+import { PROSE_PARTS, goodsOf } from "./queue-markers.mjs";
 
 // ── per-run scope limits ──────────────────────────────────────────────────────────────────────────────
 // Caps, not policy. They exist so one malformed request cannot mint an unbounded search: every extra
@@ -422,7 +422,7 @@ export function validateJob(job, { atClaim = false } = {}) {
   }
   // §B2: classes OR a goods description — either suffices; both absent ⇒ the subject can't be scoped.
   const hasClasses = requestNamesClasses(job);
-  const hasGoods = Boolean(job.goods || job.use);
+  const hasGoods = goodsOf(job) !== null;   // — the spellings live in queue-markers.mjs, with the fold that keeps every reader on one answer
   if (!hasClasses && !hasGoods) {
     // — THE GATE HAS TO ASK WHAT THE RUN WOULD ASK, not what the request typed.
     //