clearotron 0.3.2 → 0.3.3-beta.0

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.
     //

package/driver/envelope-settle.mjs

@@ -36,6 +36,7 @@
 
 import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { isCapabilityGapReason } from "./coverage-ledger.mjs";
+import { fullyDeferredAxes } from "./register-plan.mjs";
 
 export const SETTLE_SCHEMA_VERSION = 1;
 
@@ -52,22 +53,28 @@ export const SETTLE_SCHEMA_VERSION = 1;
  *   receipt is final. So `suspect` catches a MIS-STAMPED deferral — an executor bug flagging a transient as
  *   deterministic — and exists so that shape gets one attempt instead of silently becoming permanent.
  *
- * PURE.
+ * STICKY — a qid this run has already accepted as a capability gap, under any plan version, is accepted
+ * again whatever its current reason text says (stickyGaps below). PURE.
  */
-export function partitionReceiptDeferrals(plan, receipt) {
+export function partitionReceiptDeferrals(plan, receipt, { sticky = new Set() } = {}) {
   const axisOf = new Map((plan?.entries ?? []).map((e) => [String(e?.qid ?? ""), String(e?.axis ?? "").toLowerCase()]));
   // An axis the frozen plan says is deferred end to end is accepted whatever its per-qid reason text says:
   // there is no slice of it left for a dispatch to reach.
-  const fullyDeferred = new Set((receipt?.skeleton ?? [])
-    .filter((s) => s?.state === "deferred")
-    .map((s) => String(s?.axis ?? "").toLowerCase()));
+  //
+  // THE PLAN SAYS SO, NOT THE COVERAGE SKELETON. This read the skeleton's `deferred` state, which
+  // deriveCoverageSkeleton sets for an axis carrying ANY deferred qid and nothing missing, and at the
+  // fan-in nothing is missing. So every deferral on every axis was accepted: a provider hard error was
+  // logged "ACCEPTED as provider capability gaps … never retried", skipped the one bounded attempt the
+  // hard-error path is designed to get, and was then re-opened by the envelope, which reads the reason.
+  // fullyDeferredAxes asks the plan: every entry on the axis `unsupported`.
+  const fullyDeferred = new Set(fullyDeferredAxes(plan).map((a) => String(a.axis ?? "").toLowerCase()));
   const accepted = [], suspect = [];
   for (const d of receipt?.deferred ?? []) {
     const qid = String(d?.qid ?? "");
     const axis = axisOf.get(qid) ?? "";
     const reason = String(d?.reason ?? "");
     const row = { qid, axis, reason };
-    (isCapabilityGapReason(reason) || fullyDeferred.has(axis) ? accepted : suspect).push(row);
+    (isCapabilityGapReason(reason) || fullyDeferred.has(axis) || sticky.has(qid) ? accepted : suspect).push(row);
   }
   return { accepted, suspect };
 }
@@ -129,7 +136,7 @@ const shallowRow = (d) => ({ qid: String(d?.qid ?? ""), reason: String(d?.reason
  * the one case the file exists to make durable. `supersede()` builds the entry; it is deliberately a
  * summary rather than a full copy, because the qid-level truth is always re-derivable from the receipt.
  */
-export function buildDecisionDoc({ planVersion, deferredTotal, accepted, closed, closeFailed, decidedAt, history = [] }) {
+export function buildDecisionDoc({ planVersion, deferredTotal, accepted, closed, closeFailed, decidedAt, history = [], stickyGaps = [], settleTried = [] }) {
   return {
     schema_version: SETTLE_SCHEMA_VERSION,
     plan_version: planVersion ?? null,
@@ -138,10 +145,60 @@ export function buildDecisionDoc({ planVersion, deferredTotal, accepted, closed,
     accepted: accepted ?? [],
     closed: closed ?? [],
     close_failed: closeFailed ?? [],
+    sticky_gaps: stickyGaps ?? [],
+    settle_tried: settleTried ?? [],
     history: history ?? [],
   };
 }
 
+// ── A CAPABILITY GAP IS DECIDED ONCE PER RUN, NOT ONCE PER PLAN VERSION ────────────────────────────────
+//
+// The live `accepted[]` is rebuilt from the current receipt on every settle, and a settle happens again
+// whenever the plan version moves — every supplemental fold bumps it. So an acceptance lasted exactly as
+// long as the version it was made under. On a production run on 2026-09-22 one slice the provider refused
+// was accepted ("never retried"), re-opened, re-proposed, re-executed and accepted again, several times
+// in one run, each pass paying the provider for an answer that could not change.
+//
+// `sticky_gaps` is the run's memory of them: every qid accepted with a reason that states a capability gap
+// (isCapabilityGapReason), with the reason and the plan version it was first accepted under. It is carried
+// forward on every settle and never dropped: not when the plan version moves, not when the receipt stops
+// listing the qid. Only a REASON-MATCHED gap enters it. An axis-level acceptance (the skeleton branch in
+// partitionReceiptDeferrals) and every suspect or close_failed row stay out, so a deferral a later attempt
+// could close keeps today's behaviour.
+export function stickyGapsAfter(prior, accepted, planVersion) {
+  const out = new Map((prior?.sticky_gaps ?? []).map((g) => [String(g?.qid ?? ""), g]));
+  for (const a of accepted ?? []) {
+    const qid = String(a?.qid ?? "");
+    if (!qid || out.has(qid) || !isCapabilityGapReason(a?.reason)) continue;
+    out.set(qid, { qid, axis: String(a?.axis ?? ""), reason: String(a?.reason ?? "").slice(0, 400), since_plan_version: planVersion ?? null });
+  }
+  out.delete("");
+  return [...out.values()];
+}
+
+// ── A SUSPECT DEFERRAL GETS ITS ONE ATTEMPT ONCE PER RUN ─────────────────────────────────────────────
+//
+// The settle step spends one executor attempt on a suspect deferral: a hard error the run could not
+// classify as permanent, on the chance the provider has recovered. Every supplemental fold bumps the plan
+// version and re-settles, and the repair ledger's budget is keyed on the plan version, so "one attempt"
+// was one per plan version. `settle_tried` records each qid the settle step has sent, carried forward like
+// `sticky_gaps`; a suspect already in it is recorded close_failed without another call.
+export function settleTriedAfter(prior, dispatched, planVersion) {
+  const out = new Map((prior?.settle_tried ?? []).map((t) => [String(t?.qid ?? ""), t]));
+  for (const d of dispatched ?? []) {
+    const qid = String(d?.qid ?? "");
+    if (!qid || out.has(qid)) continue;
+    out.set(qid, { qid, axis: String(d?.axis ?? ""), plan_version: planVersion ?? null, outcome: String(d?.outcome ?? "").slice(0, 160) });
+  }
+  out.delete("");
+  return [...out.values()];
+}
+
+/** The run's sticky capability gaps, by qid → row. Absent or unreadable decision ⇒ none. */
+export function readStickyGaps(P) {
+  return new Map((readEnvelopeDecision(P)?.sticky_gaps ?? []).map((g) => [String(g?.qid ?? ""), g]).filter(([q]) => q));
+}
+
 /** One history entry per superseded decision. Returns the prior history with the old decision appended. */
 export function supersede(prior, source) {
   if (!prior) return [];
@@ -167,30 +224,42 @@ export function supersede(prior, source) {
  */
 export async function settleReceipt({ P, plan, receipt, dispatch = null, rejoin = null, now = null }) {
   const deferred = receipt?.deferred ?? [];
-  let { accepted, suspect } = partitionReceiptDeferrals(plan, receipt);
+  const prior = readEnvelopeDecision(P);
+  const sticky = new Set((prior?.sticky_gaps ?? []).map((g) => String(g?.qid ?? "")));
+  let { accepted, suspect } = partitionReceiptDeferrals(plan, receipt, { sticky });
   const closed = [], closeFailed = [];
+  const tried = new Map((prior?.settle_tried ?? []).map((t) => [String(t?.qid ?? ""), t]));
+  for (const s of suspect.filter((x) => tried.has(x.qid)))
+    closeFailed.push({ qid: s.qid, axis: s.axis, outcome: `already tried once this run (${String(tried.get(s.qid)?.outcome ?? "").slice(0, 100)}) — not sent again` });
+  suspect = suspect.filter((x) => !tried.has(x.qid));
+  const dispatched = [];
   if (suspect.length && dispatch && rejoin) {
     const byAxis = new Map();
     for (const s of suspect) { if (!byAxis.has(s.axis)) byAxis.set(s.axis, []); byAxis.get(s.axis).push(s.qid); }
     for (const [axis, qids] of byAxis) { if (axis) await dispatch(axis, qids); }
     const after = await rejoin();
     const stillDeferred = new Map((after?.deferred ?? []).map((d) => [String(d.qid), String(d.reason ?? "")]));
-    const re = partitionReceiptDeferrals(plan, after);
+    const re = partitionReceiptDeferrals(plan, after, { sticky });
     accepted = re.accepted;
     for (const s of suspect) {
-      if (!stillDeferred.has(s.qid)) closed.push({ qid: s.qid, axis: s.axis, outcome: "ok" });
-      else if (!re.accepted.some((a) => a.qid === s.qid))
-        closeFailed.push({ qid: s.qid, axis: s.axis, outcome: `still deferred: ${stillDeferred.get(s.qid).slice(0, 140)}` });
+      // Only a qid that was actually sent (dispatch skips one with no axis) counts as tried.
+      if (!stillDeferred.has(s.qid)) { closed.push({ qid: s.qid, axis: s.axis, outcome: "ok" }); if (s.axis) dispatched.push({ ...s, outcome: "ok" }); }
+      else if (!re.accepted.some((a) => a.qid === s.qid)) {
+        const outcome = `still deferred: ${stillDeferred.get(s.qid).slice(0, 140)}`;
+        closeFailed.push({ qid: s.qid, axis: s.axis, outcome });
+        if (s.axis) dispatched.push({ ...s, outcome });
+      }
     }
   } else if (suspect.length) {
     for (const s of suspect) closeFailed.push({ qid: s.qid, axis: s.axis, outcome: "no executor lane at this seam" });
   }
-  const prior = readEnvelopeDecision(P);
   return writeEnvelopeDecision(P, buildDecisionDoc({
     planVersion: receipt?.plan_version, deferredTotal: deferred.length,
     accepted: accepted.map((a) => ({ ...a, decision: "accepted-capability-gap" })),
     closed, closeFailed, decidedAt: now ?? new Date().toISOString(),
     history: supersede(prior, prior ? "re-settled" : null),
+    stickyGaps: stickyGapsAfter(prior, accepted, receipt?.plan_version),
+    settleTried: settleTriedAfter(prior, dispatched, receipt?.plan_version),
   }));
 }
 

package/driver/findings-model.mjs

@@ -335,14 +335,14 @@ export function isUnconditionalProceed(rec) {
 
 /**
  * Deterministically BIND a recommendation line to the verdict: on a CONDITIONAL verdict an
- * unconditional "proceed" is rewritten to carry the conditions; on BLOCKING any recommendation is
- * replaced (a BLOCKING run does not reach delivery post- — belt-and-braces for legacy paths).
+ * unconditional "proceed" is rewritten to carry the conditions. BLOCKING is the reviewer's sign-off on
+ * the draft, not a hold: a BLOCKING run delivers, so its recommendation stands as the report wrote it.
  * Code derives the bound from the model's OWN verdict + reasons; it never invents a verdict. PURE.
  */
 export function bindRecommendation(rec, verdict, reasons = [], { maxReasons, maxLen } = {}) {
   const r = String(rec ?? "").trim();
   const v = String(verdict || "").toUpperCase();
-  if (v === "BLOCKING") return "On hold — the reviewing lawyer's open questions must be resolved before any recommendation.";
+  // BLOCKING returns the recommendation as written: nothing holds delivery on it, so "on hold" was untrue (ruled 2026-09-22).
   if (v !== "CONDITIONAL" || !r || !isUnconditionalProceed(r)) return r;
   const conds = (reasons ?? []).filter(Boolean);
   if (!conds.length) return r;
@@ -600,7 +600,7 @@ export function riskStatement({ tier, verdict, reasons, basis, clauses } = {}) {
   // CLEAR, so long as it is clear on register findings ALONE).
   const registerOnly = basis === "register-only";
   const basisNote = registerOnly ? " Register findings only — no common-law or marketplace search was run." : "";
-  if (v === "BLOCKING") return `On hold — the reviewing lawyer's open questions must be resolved before any recommendation.${basisNote}`;
+  if (v === "BLOCKING") return `${t}${basisNote ? `.${basisNote}` : ""}`;   // the reviewer's sign-off is not the clearance's answer and nothing is held on it: the band stands alone, as below
   if (v === "CONDITIONAL") {
     // A clause stored as explicit null is a condition ruled to the run record alone: it is not the lede,
     // it is not counted, and its reason is never the fallback text. `undefined` (legacy/short) is not null.

package/driver/gateway.mjs

@@ -225,6 +225,8 @@ export function toolWrittenArtifact(p) {
     ?? null;
 }
 import { buildGatherMcpConfig, allowedToolsFor, toolGroupsForStage, recordAxisFor, seatWritesForGroups } from "./engine/mcp/gather-config.mjs";
+import { everyToolCallRefused } from "./engine/tool-refusal.mjs";   // one definition, shared with the engine probe
+export { everyToolCallRefused };
 // The profiles STORE root, for the write boundary only — read from the module that owns it, never
 // re-derived from CLEAROTRON_CUSTOMERS_DIR here. Acyclic: profiles.mjs imports node builtins + config.
 import { unitRefusalsFor } from "./register-unit-record.mjs";
@@ -1528,6 +1530,11 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
     // appear: a postponed run resumes on its own, and a signed-out one cannot. The sentence rides after
     // the colon, as `model_mismatch:` carries its detail, so no run-level classifier needs a new token.
     else if (turn.signals?.signedOut && fail) fail = `engine_signed_out: ${turn.signals.signedOut}`;
+    // AND ONE WHOSE TOOLS WERE ALL REFUSED IS NAMED, not left as the missing file the refusal caused. The
+    // turn reported success and the stage failed for want of what its tools would have produced; a
+    // `missing_file` reads as a model that did not write, and sends the reader to the wrong place. The
+    // sentence says what fixes this host. After the sign-in, which is the more basic fault when both appear.
+    else if (turn.signals?.toolsRefused && fail) fail = `engine_tools_refused: ${turn.signals.toolsRefused}`;
     // A6 (addendum 2026-07-30): stop_reason max_tokens with ZERO usable output is a DETECTED FAULT with a
     // name — never a silent paid retry. The turn ran to its output-token ceiling and the artifact never
     // landed (a content fail on a "successful" turn), or the turn itself died at the ceiling (transport
@@ -2027,6 +2034,15 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
       note(`[${name}] the engine's sign-in could not be refreshed — breaking the ladder (a retry re-sends the same credential)`);
       break;
     }
+    // EVERY TOOL CALL THE TURN MADE WAS REFUSED. On some hosts codex's own sandbox refuses the stage's
+    // tool servers while the turn reports success, and the stage then fails for want of what the tools
+    // would have produced. The next attempt spawns the same sandbox and is refused the same way, so a
+    // retry re-buys the refusal: measured at three paid attempts per stage on a production run before the
+    // identical-failure break stopped it. Break on the first. A turn where any call completed is not this.
+    if (everyToolCallRefused(turn)) {
+      note(`[${name}] every tool call this turn made was refused (${turn.mcpToolCallsRefused}) — breaking the ladder (a retry is refused the same way)`);
+      break;
+    }
     // D3: overload (529 / status_overloaded) — stop the ladder here: an in-ladder re-attempt hammers an
     // API that just said it is overloaded, seconds apart, on the SAME model. Breaking hands the failure
     // to the existing machinery: the chain cascades models (FALLBACK_ELIGIBLE) and an exhausted chain
@@ -2816,7 +2832,7 @@ export function correctionHint(lastFail, { gridLedgerName = "common-law-grid.jso
       `The driver computed every obligation and every identifier in it — the coverage unit, the query id, the hit ` +
       `count, the unaccounted classes and terms, each deferred slice's own receipt reason. Record the named row(s) ` +
       `through the \`record_coverage\` tool — {"row_id","status","reason"} per row, never by writing or editing any ` +
-      `file: "status" EXACTLY one bare token of confirmed-clean / coverage-limited / deferred, "reason" the sentence ` +
+      `file: "status" EXACTLY one bare token of confirmed-clean / coverage-limited / deferred / withheld-by-judgment, "reason" the sentence ` +
       `the lawyer reads (qualifiers go in the reason, never in the status). ` +
       `A row marked "open" cannot be confirmed-clean, and its own "open_because" says which of the two kinds ` +
       `it is. A NEVER-SEARCHED slice — the active register provider cannot express it, so nothing can make it run — is ` +
@@ -2983,7 +2999,7 @@ export function correctionHint(lastFail, { gridLedgerName = "common-law-grid.jso
     // run the driver stamped as form-required, and the stamp is conditional. On an unstamped run
     // validators.registerFindings demands the table exactly as it did before and emits this label,
     // so dropping the arm left the one lane that can still fire it with a generic hint.
-    hint = "the file has a findings heading plus a Coverage ledger with a status row (confirmed-clean / coverage-limited / deferred)";
+    hint = "the file has a findings heading plus a Coverage ledger with a status row (confirmed-clean / coverage-limited / deferred)" + (/common-law-findings/.test(lastFail) ? ", or each ledger row's status is recorded by calling `record_coverage_status` with `grid_spec_path`, the same spec path the grid tool was given" : "");
   } else if (/negative-results|coverage-ledger|audit-trail|findings-heading/.test(lastFail)) {
     hint = "the findings file carries ALL required sections: a findings heading, the Negative results matrix " +
       "(every variant × platform row), the Coverage ledger with a status row, and the Audit trail call log";

package/driver/manager-groups-verdict.mjs

@@ -47,7 +47,7 @@ export function managerGroupsVerdict({ idGroups, managerGroups, user, uid, why =
   // was not established", and saying so is the whole point — the deployment that HAD this fault also
   // had a check that reported nothing wrong.
   if (!Array.isArray(idGroups) || !idGroups.length) {
-    return { state: "skip", message: `could not read the groups of ${user}${why ? ` — ${why}` : ""}. Not checked, not passed.` };
+    return { state: "skip", blocked: true, message: `could not read the groups of ${user}${why ? ` — ${why}` : ""}. Not checked, not passed.` };
   }
   if (!Array.isArray(managerGroups)) {
     return { state: "skip", message: `no readable systemd --user manager for ${user}${why ? ` — ${why}` : ""}. `

package/driver/matter-frame-record.mjs

@@ -195,22 +195,39 @@ export const refuseUndeclared = (params) => refuseUndeclaredShared(params, DECLA
  * The Nice classes the frame judged necessary beyond the instructed ones, as strings. IMPURE (reads
  * the run's own accepted call).
  *
- * THE PLAN COMPILE UNIONS THIS WITH THE INSTRUCTED CLASSES so every variant axis carries both. Before
- * it existed the axes carried the instructed classes alone and a class the frame had identified reached
- * the sweep only if something proposed it as supplemental work — where it competed for capped slots
- * with model-minted extras. A cap was deciding coverage the frame had already judged necessary, and on
- * the run this came from the delivered report said two such classes were "covered for the name and open
- * for its variants" while the reviewing lawyer's scope included one of them throughout.
+ * THE PLAN COMPILE DOES NOT READ THIS. It takes `frameIdentifiedClassRows` below, where each added
+ * class keeps its reason and costs one identical-mark question rather than riding every entry (decision
+ * 18). The one caller left is the house-element check, which unions this list with the instructed
+ * classes because the client's own filings are best looked for across the widest class set.
  *
  * EMPTY IS THE ORDINARY ANSWER and must stay cheap: no frame yet, a legacy or replayed run whose
  * accepted call predates the field, a frame that identified nothing — all of them return `[]`, the
- * union is a no-op, and the plan is exactly what it was.
+ * union is a no-op, and the check looks in the instructed classes alone.
  */
 export function frameIdentifiedClasses(runDir) {
   const rows = lastAcceptedMatterFrame(runDir)?.identified_classes;
   return (Array.isArray(rows) ? rows : []).map((r) => String(r?.class ?? "").trim()).filter(Boolean);
 }
 
+/**
+ * The same rows WITH THEIR REASONS, for the register plan (decision 18). IMPURE, like its sibling.
+ *
+ * The reason is why the class is here and it is half the row: the bound on this widening is that a
+ * class is added only for goods the CLIENT'S OWN business plainly reaches, and a class carrying no
+ * stated reason cannot be checked against that by anyone. The plan compiler drops such a row rather
+ * than searching it, so the reason is load-bearing and not documentation.
+ *
+ * Kept beside `frameIdentifiedClasses` rather than replacing it: the other caller verifies a proposed
+ * house element against an owner-scoped lookup, where the widest class set is the right one to look in
+ * and a reason would mean nothing.
+ */
+export function frameIdentifiedClassRows(runDir) {
+  const rows = lastAcceptedMatterFrame(runDir)?.identified_classes;
+  return (Array.isArray(rows) ? rows : [])
+    .map((r) => ({ class: String(r?.class ?? "").trim(), reason: String(r?.reason ?? "").trim() }))
+    .filter((r) => r.class);
+}
+
 /**
  * The forms of the name this run's client ratified, as strings. IMPURE (reads the run's own accepted
  * call). Empty or one form is the ordinary answer.

package/driver/named-band.mjs

@@ -137,7 +137,7 @@ export function parseNamedBand(raw) {
         // byte-identical to a slice the plan deliberately counted without fetching. Measured on a real
         // run: four capability-gap blocks carried `error:true, deferred:true` into this function and
         // reached record-carry.json with both fields gone and a sentence claiming the run "has a hit
-        // COUNT for this slice". register-plan.mjs:1835 validatePlanFeasibility already enforces the same rule one layer up
+        // COUNT for this slice". register-plan.mjs validatePlanFeasibility already enforces the same rule one layer up
         // ("a transient must not ship indistinguishable from a sanctioned descriptor") — it reads the
         // RAW blocks, which is why it could. Every consumer that reads THIS projection could not.
         // Conditional like the four keys above, so old bands carry neither key and nothing shifts.