clearotron 0.3.2 → 0.3.3-beta.0

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.2",
+  "version": "0.3.3-beta.0",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/partial-payload-baseline.json

@@ -27,6 +27,14 @@
       "tool": "record_dispositions",
       "why": "no fixture yet; accumulating semantics claimed in the tool description ('Everything already recorded is kept') and not yet planted"
     },
+    {
+      "tool": "record_coverage_status",
+      "why": "both declared fields are required, so a call has no top-level key to omit; its accumulation by unit (a later call keeps the units it omits) is pinned in a-common-law-coverage-status-is-read-as-data.test.mjs"
+    },
+    {
+      "tool": "record_withheld_families",
+      "why": "its one declared field is required, so a call has no top-level key to omit; its accumulation by qid (a later call keeps the families it omits) is pinned in every-waiting-family-is-asked-or-withheld.test.mjs"
+    },
     {
       "tool": "record_unit_note",
       "why": "no fixture yet; every field optional, which is the exposed shape — this row is the highest-priority one to close"
@@ -61,11 +69,12 @@
     {
       "tool": "record_clearance_variants",
       "fields": [
+        "goods_words",
         "incumbent_classes",
-        "watchlist_owners",
-        "search_floor"
+        "search_floor",
+        "watchlist_owners"
       ],
-      "why": "a partial silently empties the register-axis search floor, narrowing the run's own definition of coverage"
+      "why": "a partial silently empties the register-axis search floor, narrowing the run's own definition of coverage. `goods_words` joins them for the same reason and one worse: an emptied goods list reads as \"this matter named no goods\" rather than as a partial call, so the crowded sweep it exists to narrow goes back to returning more filings than anyone can read, and nothing says why. The MERGE preserves all four (mergeClearanceVariantsCall, keep-if-absent) — these rows record that the ACCEPTOR alone does not."
     },
     {
       "tool": "record_blind_frame",

package/driver/pipeline.mjs

@@ -10,6 +10,7 @@ import { readFileSync, existsSync, mkdirSync, writeFileSync, renameSync, copyFil
 import { createHash } from "node:crypto";
 import { join, dirname, basename, resolve } from "node:path";   // resolve: the resume line must work from any cwd
 import { driverDir, driverRel, ensureDriverDir } from "../shared/driver-dir.mjs";   // — one definition of where `_driver/` is
+import { goodsOf } from "./queue-markers.mjs";   // — one reading of "does this job name goods", shared with the intake gate
 import { terminalClampDecision, orderClausesForLede, clientConditions, clauseForDefect } from "./terminal-clamp.mjs";   // — deliver and clamp, never withhold
 import { recordSpan } from "./attributed-span.mjs";   // — driver work the decomposition can attribute
 import { fileURLToPath } from "node:url";
@@ -39,8 +40,8 @@ import { parseVerdict, countCitedDefects, parseCorrectionKinds, parseCorrections
 import { readAcceptedFlags } from "./narrative-refutation-record.mjs";   // T3b — the typed flags, not the re-parse
 import { evidenceClaimViolations, evidenceClaimTable } from "./evidence-claim-invariant.mjs";   //
 import { buildCorrectionsApplied, correctionsWorklist, correctionsAppliedTable, correctionScope, scopeDrift, unresolvedFlags, reportLines, linesOf, REPORT_LINE_KEY, REPORT_LINE_LABEL } from "./corrections-feedforward.mjs";
-import { parseCoverageLedgerJson, parseCoverageLedgerFull, deriveCoverageStatus, classTokensFromScopeText, coerceToolAbsenceDeferred, applyTaintDeferred, decideRegisterGap, splitDeferredByCloseability, coverageLedgerTableRows, coverageUnitLabel, NON_MATERIAL_AXES, COVERAGE_STATUSES } from "./coverage-ledger.mjs";
-import { receiptSettled, readEnvelopeDecision, settleReceipt, settledDeferralsSection } from "./envelope-settle.mjs";
+import { parseCoverageLedgerJson, parseCoverageLedgerFull, deriveCoverageStatus, classTokensFromScopeText, coerceToolAbsenceDeferred, applyTaintDeferred, decideRegisterGap, splitDeferredByCloseability, formRowUnitKey, coverageLedgerTableRows, coverageUnitLabel, NON_MATERIAL_AXES, COVERAGE_STATUSES } from "./coverage-ledger.mjs";
+import { receiptSettled, readEnvelopeDecision, settleReceipt, settledDeferralsSection, readStickyGaps } from "./envelope-settle.mjs";
 import { readRegisterTaint, readActiveTaintAxes } from "./register-taint.mjs";
 import { parseNamedBand, mergeNamedBands, findCollapsedBands, quarantineUnknownStates, taintQuarantineCleanBlocks, bandRecords } from "./named-band.mjs";
 import { recordOriginsFor } from "./record-origins.mjs";
@@ -97,7 +98,7 @@ import { publishReport, composeEmailHtml, deliverySubject } from "./publish/inde
 import { parseCaseLawProfiles, joinCaseLawProfiles } from "./publish/parse.mjs";
 import { buildAuditMd, parseSpineFindingBlocks } from "./publish/audit-from-spine.mjs";
 import { deriveRegisterPresence } from "./publish/register-presence.mjs";   // — the audit stores every live in-scope record
-import { lastAcceptedMatterFrame, frameIdentifiedClasses, frameHouseElementCandidate } from "./matter-frame-record.mjs";   // — the frame's inferred scope, when nothing was instructed; and the classes it judged necessary beyond the instructed ones, which the plan compile unions in
+import { lastAcceptedMatterFrame, frameIdentifiedClasses, frameIdentifiedClassRows, frameHouseElementCandidate } from "./matter-frame-record.mjs";   // — the frame's inferred scope, when nothing was instructed; and the classes it judged necessary beyond the instructed ones, each with its reason, which the plan compile gives one identical-mark question apiece (decision 18)
 import { romanizedTermsFromPlan, mintSupplementalQid } from "./register-plan.mjs";
 import { excludeHouseElement, verifyHouseElementOwnership, resolveRegions as resolvePlanRegions, HOUSE_ELEMENT_RECEIPT } from "./register-plan.mjs";   // 647 — the client's own element leaves the conflict analysis only on a verified receipt
 import { resolveRecordExecutor } from "./register-records.mjs";   // — the stamp the late lanes never met
@@ -463,8 +464,35 @@ export function readPlanExecution(ctx) {   // @internal
   const p = ctx?.paths?.planExecution;
   try { return p && existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : null; } catch { return null; }
 }
+/**
+ * A qid this run has accepted as a capability gap (envelope-settle.mjs stickyGapsAfter) leaves `missing`
+ * for `deferred`, with the reason it was accepted under, so no re-join can put it back on the ladder.
+ * Returns the join unchanged when nothing is held. PURE.
+ */
+export function holdStickyGapsIn(join, sticky) {   // @internal
+  const held = (join?.missing ?? []).filter((q) => sticky?.has(q));
+  if (!held.length) return join;
+  return { ...join, missing: join.missing.filter((q) => !sticky.has(q)),
+    deferred: [...(join.deferred ?? []), ...held.map((q) => ({ qid: q, reason: String(sticky.get(q)?.reason ?? "").slice(0, 300) }))] };
+}
+
+/**
+ * The coverage units of this run's sticky capability gaps, as ledgerUnitKey()s, found through the coverage
+ * form's own deferred rows (the driver writes each with its qid). The envelope, the escalation and the
+ * skeptic's ledger split then hold those rows whatever reason the seat wrote for them. A run with no form,
+ * or no sticky gap, holds nothing extra, exactly as before.
+ */
+export function stickyGapUnits(P) {   // @internal
+  const sticky = readStickyGaps(P);
+  if (!sticky.size) return new Set();
+  const stamp = coverageFormStamp(P.runDir);
+  const rows = stamp.required ? (readCoverageForm(P.runDir, stamp.formName).rows ?? []) : [];
+  return new Set(rows.filter((r) => r?.kind === "deferred" && sticky.has(String(r.qid ?? ""))).map(formRowUnitKey));
+}
+
 export function writePlanExecutionReceipt(ctx, joinRes) {   // @internal
   const P = ctx.paths;
+  joinRes = holdStickyGapsIn(joinRes, readStickyGaps(P));
   // — the ONE place the receipt is written is the one place this decision is taken. The
   // reclassification is keyed off the receipt already on disk (ladderExhaustedQids), so every writer
   // agrees without any of them knowing about it: the fan-in, the envelope's re-join after its close
@@ -2384,7 +2412,12 @@ function attachRegisterPlan(ctx, { frozenOnly = false } = {}) {
       // for the documented normal case. Harmless on corsearch (an absent region clause is a worldwide
       // sweep); fatal on a provider whose regions[] is mandatory, where every entry then errored on its
       // count probe and the whole plan joined MISSING at fan-in (review finding 11).
-      job: { jobKey: ctx.run.slug, classes: [...new Set([...inScopeClassList(ctx.job, ctx.profile).map(String), ...frameIdentifiedClasses(P.runDir)])], jurisdictions: registerJurisdictions(ctx.job, ctx.profile) },
+      // DECISION 18: the frame's added classes are no longer UNIONED into the plan's class scope. They
+      // ride one identical-mark entry each instead, which is what an added class is supposed to cost —
+      // unioning put every added class on every variant and every family. The instructed scope is what
+      // it always was, and `addedClasses` only ever appends.
+      job: { jobKey: ctx.run.slug, classes: inScopeClassList(ctx.job, ctx.profile).map(String), jurisdictions: registerJurisdictions(ctx.job, ctx.profile) },
+      addedClasses: frameIdentifiedClassRows(P.runDir),
       form, skillVersion: "clearance-register@spec48",
       // — WHICH ELEMENT THE EXCLUSION TOOK OUT, so the compile can make its form band unreachable
       // rather than merely unasked-for. Null unless the ownership receipt verified, which is the same
@@ -6219,10 +6252,11 @@ export function skepticDeferralExtra(ctx) {   // @internal
     const gapAxes = capabilityGapAxes(ctx.registerPlan, receipt);
     const fullyDeferred = new Set((ctx.registerPlan ? fullyDeferredAxes(ctx.registerPlan) : []).map((a) => String(a.axis).toLowerCase()));
     const axes = [...new Set(rows.map((r) => String(r.axis ?? "").toLowerCase()).filter(Boolean))];
+    const heldUnits = stickyGapUnits(P);
     const ledgerLines = coverageLedgerTableRows(rows);
     const held = [], closeable = [];
     for (const a of axes) {
-      const s = splitDeferredByCloseability(rows, a, gapAxes, { fullyDeferred: fullyDeferred.has(a) });
+      const s = splitDeferredByCloseability(rows, a, gapAxes, { fullyDeferred: fullyDeferred.has(a), heldUnits });
       for (const r of s.held) held.push(`${a} / ${r.unit} — ${String(r.reason ?? "").replace(/\s+/g, " ").slice(0, 160)}`);
       for (const r of s.closeable) closeable.push(`${a} / ${r.unit} — ${String(r.reason ?? "").replace(/\s+/g, " ").slice(0, 160)}`);
     }
@@ -6230,6 +6264,16 @@ export function skepticDeferralExtra(ctx) {   // @internal
     const deferredQids = deferredList.slice(0, 24)
       .map((d) => `- ${d.qid} — ${String(d.reason ?? "").replace(/\s+/g, " ").slice(0, 200)}`);
     const more = deferredList.length > 24 ? [`- …and ${deferredList.length - 24} more (read ${P.planExecution} for the rest)`] : [];
+    // THE CLASSES THE FRAME ADDED, AND WHAT EACH RETURNED. This block names what was refused and what is
+    // open, and nothing that ran, so a class the frame added beyond the instructed ones — asked and
+    // answered with its records listed — was absent from it, and the skeptic reported it as never swept.
+    const addedClassRows = (ctx.registerPlan?.entries ?? []).filter((e) => e?.added_class_reason).map((e) => {
+      const ran = (receipt?.executed ?? []).find((x) => x.qid === e.qid);
+      const answer = ran ? `${ran.state}${Number.isFinite(ran.records) ? `, ${ran.records} records` : ""}`
+        : (receipt?.deferred ?? []).some((d) => d.qid === e.qid) ? "refused (listed above)"
+        : (receipt?.missing ?? []).includes(e.qid) ? "not run (missing)" : "not in the receipt";
+      return `- ${e.qid} (class ${(e.nice_classes ?? []).join(", ")}) — ${answer}`;
+    });
     const ownerNegative = ownerScreenNegative(readOwnerScreen(P));
     return lines(
       `COVERAGE + EXECUTION, DRIVER-COMPUTED — do NOT re-derive any of this from the findings prose. These rows come from ${P.registerCoverageLedger} and ${P.planExecution}, the machine artifacts the driver wrote; both are also yours to read directly, but the answer to "what is still open, and can a re-run close it" is already below.`,
@@ -6240,6 +6284,7 @@ export function skepticDeferralExtra(ctx) {   // @internal
       deferredQids.length
         ? lines(`Plan-execution receipt — queries the ACTIVE PROVIDER REFUSED deterministically (${deferredList.length} of ${(receipt.executed?.length ?? 0) + deferredList.length + (receipt.missing?.length ?? 0)} planned), with the mechanical reason per query:`, ...deferredQids, ...more)
         : "Plan-execution receipt: no query was deterministically refused by the provider this run.",
+      addedClassRows.length ? lines("", "Classes the frame added beyond the instructed ones — each question, and what it returned:", ...addedClassRows) : "",
       "",
       closeable.length
         ? `CLOSEABLE floor obligations (a warm re-run reaches these — escalate them if they are material): ${closeable.join("; ")}.`
@@ -6401,7 +6446,7 @@ function plainRegisterExtra(ctx) {
   }
 }
 
-// ── THE RECEIPT, AND THE THREE CLASSES, STATED ONCE ────────────────────────────────────────────────
+// ── THE RECEIPT, AND THE GRADED CLASSES, STATED ONCE ────────────────────────────────────────────────
 //
 //. The receipt this block tabulates is the answer to "did that search run", and until now exactly
 // one stage got it: the REVIEWER. `synthesis` — the stage that writes the claim the reviewer then
@@ -6419,7 +6464,7 @@ function plainRegisterExtra(ctx) {
 // out twice, once per seat, is the shape — one rule in two places, drifting from the day the second
 // copy is typed — and the classes are the part that must never drift, because class (1) is the blocking
 // condition.
-// THE HEAD AND THE THREE CLASSES ARE NOT DECLARED HERE. They live in register-plan.mjs, beside the
+// THE HEAD AND THE GRADED CLASSES ARE NOT DECLARED HERE. They live in register-plan.mjs, beside the
 // derivation that assigns the states, because the gateway's corrective hint is a THIRD reader of the
 // same grading and `pipeline.mjs` imports `gateway.mjs` — so a constant declared here could never
 // reach it.
@@ -6447,8 +6492,13 @@ function planAuditExtra(ctx, { stage = "narrative-refutation" } = {}) {
       `- executed: ${exec.executed.length} entr${exec.executed.length === 1 ? "y" : "ies"} (${crowds.length} crowd/incomplete${crowds.length ? `: ${crowds.slice(0, 4).map((x) => x.qid).join("; ")}` : ""})`,
       `- missing (no band block): ${exec.missing.length}${exec.missing.length ? ` — ${exec.missing.slice(0, 4).join("; ")}` : ""}`,
       `- skipped (crowd-gated fringe): ${exec.skipped.length}`,
+      // The families waiting for the reading turn, and those it asked. Without these lines the table's
+      // own buckets summed to the whole plan less the waiting families, and a reviewer read it as
+      // "no family waiting" while the receipt held 156.
+      `- awaiting the reading turn's ask: ${exec.awaiting?.length ?? 0}`,
+      exec.asked?.length ? `- asked by the reading turn (a waiting family's question, asked by another entry): ${exec.asked.length}` : "",
       exec.unplanned?.length ? `- unplanned qid-stamped blocks: ${exec.unplanned.length}` : "",
-      ...(exec.skeleton ?? []).map((s) => `- axis ${s.axis}: ${s.state} (${s.executed}/${s.entries} executed, ${s.crowds} crowd)`),
+      ...(exec.skeleton ?? []).map((s) => `- axis ${s.axis}: ${s.state} (${s.executed}/${s.entries} executed, ${s.crowds} crowd${s.awaiting ? `, ${s.awaiting} awaiting` : ""})`),
     ];
   } catch (e) { rows = [`- (receipt table unavailable — read + audit the receipt file directly: ${P.planExecution})`]; note(`plan-audit receipt table (non-fatal): ${e.message}`); }
   return lines(
@@ -6716,7 +6766,7 @@ export function readFindingsForReport(P) {
 // The matter's FULL in-scope Nice-class set (incl. services 42/44) — declared classes (top-level OR per-mark)
 // else the profile defaults. The dangerous-band floor + its coverage gate must span ALL of these, never a
 // goods-only subset (the VELTRIPHEN services-class miss). Strings, deduped.
-function inScopeClassList(job, profile) {
+export function inScopeClassList(job, profile) {   // @internal — also read by scripts/register-plan-shape.mjs, which must resolve scope exactly as the run did
   const fromMarks = Array.isArray(job?.marks) ? job.marks.flatMap((m) => (Array.isArray(m?.classes) ? m.classes : [])) : [];
   const declared = [...(Array.isArray(job?.classes) ? job.classes : []), ...fromMarks];
   return [...new Set((declared.length ? declared : (profile?.defaultClasses ?? [])).map(String))];
@@ -7035,7 +7085,14 @@ export function coverageRowAreaLabel(axis, unit) {   // @internal
 export function coverageJudgmentRows(ledgerRows, planExecution) {   // @internal
   const open = [];
   for (const r of ledgerRows ?? []) {
-    if (!r || String(r.status ?? "").toLowerCase() === "confirmed-clean") continue;
+    // `withheld-by-judgment` joins `confirmed-clean` in NOT reaching the reader, and for the opposite
+    // reason. A clean row has nothing to disclose. A withheld one has something to say, and it is
+    // ruled to belong in the run record and the coverage ledger only: nothing is added to the report
+    // (owner, 2026-09-18). A family the reading turn chose not to open, having read the identical question as
+    // a list and found what it needed, is not a gap in the client's search — it is where the work was
+    // spent — and a row saying otherwise would read to a lawyer as an incomplete job.
+    const status = String(r?.status ?? "").toLowerCase();
+    if (!r || status === "confirmed-clean" || status === "withheld-by-judgment") continue;
     const reason = String(r.reason ?? "").replace(/\s+/g, " ").trim().slice(0, 160);
     const axis = String(r.axis ?? "").toLowerCase();
     open.push({ axis, area: coverageRowArea(axis, r.unit), areaLabel: coverageRowAreaLabel(axis, r.unit),
@@ -8455,6 +8512,42 @@ function postponeRun(e, run, meta = {}) {
   return { ok: false, postponed: true, resetsAt, codename, fromStage: e.stage, runDir: run?.runDir ?? null };
 }
 
+/**
+ * The instructed scope a job asks for — what the MATTER named, before any model ran.
+ *
+ * Pulled out of the run so it can be driven straight from a job, because the defect it closes lived
+ * exactly in the seam between the intake gate and this object: the gate counts a job as carrying a
+ * goods description under EITHER spelling, and this stamped only the current one. A job written the
+ * older way passed the gate and landed `goods: null` — the scope file saying the matter named no
+ * goods while the request plainly did — and every reader that asks what the matter covers reads this
+ * file. Nothing said so, because nothing compared the two sites.
+ *
+ * PURE: a job in, a plain object out, no IO.
+ */
+export function instructedScopeOf(job) {
+  const markNames = Array.isArray(job?.marks)
+    ? job.marks.map((m) => (typeof m === "string" ? m : m?.name)).filter(Boolean)
+    : (job?.markName ?? job?.name ?? null);
+  return {
+    marks: markNames,
+    classes: job?.classes ?? null,
+    jurisdictions: job?.jurisdictions ?? null,
+    // THE GATE'S OWN READING, imported rather than restated. A run's job is folded onto one field at
+    // assembly, so this is normally reading what is already there; it stays for a job handed to this
+    // function directly, and because the gate and the scope disagreeing is the defect it closes.
+    goods: goodsOf(job),
+    customer: job?.customer ?? null,
+    // the geography stamp (enqueue-schema.mjs, "the GEOGRAPHY STAMP": {mode, origin}) — copied
+    // VERBATIM, never recomputed: foldRecipeScope mutates job.jurisdictions on later passes (and
+    // re-stamps origin "saved-search" when it does), so by read time the stamp is the only surviving
+    // record of where the territories came from. Without it here, the frame reconstructs that
+    // provenance from the request prose — a reconstruction validators.matterContext cannot check.
+    // null = the job predates the stamp ("unrecorded", effective-scope.mjs) — an explicit state,
+    // never a missing key.
+    geography: job?.geography ?? null,
+  };
+}
+
 async function pipelineInner(job, opts = {}) {
   assertTierSanity();
   // The engine binary, first and UNCONDITIONALLY — before the register preflight, which two lanes skip.
@@ -8872,24 +8965,7 @@ async function pipelineInner(job, opts = {}) {
   // frame validator compares against THIS file, never against the frame's own paraphrase) —
   // paraphrase drift between the request and the frame is a defect, not a style choice.
   try {
-    const markNames = Array.isArray(job.marks)
-      ? job.marks.map((m) => (typeof m === "string" ? m : m?.name)).filter(Boolean)
-      : (job.markName ?? job.name ?? null);
-    writeFileSync(P.instructedScope, JSON.stringify({
-      marks: markNames,
-      classes: job.classes ?? null,
-      jurisdictions: job.jurisdictions ?? null,
-      goods: job.goods ?? null,
-      customer: job.customer ?? null,
-      // the geography stamp (enqueue-schema.mjs, "the GEOGRAPHY STAMP": {mode, origin}) — copied
-      // VERBATIM, never recomputed: foldRecipeScope mutates job.jurisdictions on later passes (and
-      // re-stamps origin "saved-search" when it does), so by read time the stamp is the only
-      // surviving record of where the territories came from. Without it here, the frame reconstructs
-      // that provenance from the request prose — a reconstruction validators.matterContext cannot
-      // check. null = the job predates the stamp ("unrecorded", effective-scope.mjs) — an explicit
-      // state, never a missing key.
-      geography: job.geography ?? null,
-    }, null, 2) + "\n");
+    writeFileSync(P.instructedScope, JSON.stringify(instructedScopeOf(job), null, 2) + "\n");
   } catch (e) { note(`instructed-scope write failed (non-fatal): ${e.message}`); }
   // THE STORED DEFAULTS THE ENGINE CANNOT SEARCH — recorded by the run, not only by the plan preview.
   //
@@ -9820,6 +9896,19 @@ async function pipelineInner(job, opts = {}) {
     const fanInRepairs = [];
     const dispatchPlanQids = async (a, qids, repairId, max = 1) => {
       if (!planExec || !ctx.registerPlan) return null;
+      // A qid this run has accepted as a capability gap is never sent to the provider again, under any plan
+      // version (envelope-settle.mjs stickyGapsAfter). A whole-axis dispatch becomes the axis's other qids;
+      // the executor's qid-ownership merge keeps the gap's own block as it stands.
+      const sticky = readStickyGaps(P);
+      if (sticky.size) {
+        const wanted = qids?.length ? qids : (ctx.registerPlan.entries ?? []).filter((e) => e.axis === a).map((e) => e.qid);
+        const held = wanted.filter((q) => sticky.has(q));
+        if (held.length) {
+          runLog(run.runDir, { event: "plan-qids-sticky-gap", axis: a, qids: held, action: repairId });
+          qids = wanted.filter((q) => !sticky.has(q));
+          if (!qids.length) return null;
+        }
+      }
       if (!repairLedger.canAttempt(repairId, a, { max, epoch: repairEpoch })) return null;
       note(`register-unit ${a}: ${repairId} — direct executor dispatch (code, no agent turn) for ${qids?.length ?? "all"} dictated slice(s)`);
       let outcome;
@@ -10280,7 +10369,15 @@ async function pipelineInner(job, opts = {}) {
         // been a log line. Settling here is idempotent and makes the decision durable.
         if (!receiptSettled(P, priorReceipt).settled) await settleEnvelopeAtReceipt("receipt-reuse");
       } else {
-      let joinRes = joinPlanToBands(ctx.registerPlan, readBands());
+      // A qid this run has accepted as a capability gap does not ride the ladder again. It leaves `missing`
+      // for `deferred` with the reason it was accepted under, before any dispatch or followup reads the
+      // join, so neither the direct executor nor the plan-join followup re-dictates it.
+      const holdStickyGaps = (j) => {
+        const held = holdStickyGapsIn(j, readStickyGaps(P));
+        if (held !== j) runLog(run.runDir, { event: "plan-qids-sticky-gap", qids: j.missing.filter((q) => !held.missing.includes(q)), action: "held-from-missing" });
+        return held;
+      };
+      let joinRes = holdStickyGaps(joinPlanToBands(ctx.registerPlan, readBands()));
       const missingEntriesByAxis = () => {
         const byQid = new Map(ctx.registerPlan.entries.map((e) => [e.qid, e]));
         const m = new Map();
@@ -10302,7 +10399,7 @@ async function pipelineInner(job, opts = {}) {
           runLog(run.runDir, { event: "plan-qids-missing", axis: a, qids, action: "plan-direct-execute" });
           await dispatchPlanQids(a, qids, "plan-direct-execute", 2);
         }
-        joinRes = joinPlanToBands(ctx.registerPlan, readBands());
+        joinRes = holdStickyGaps(joinPlanToBands(ctx.registerPlan, readBands()));
         if (!joinRes.missing.length) deriveNamedBand(ctx);   // dispatch landed blocks — re-merge so Layer B reads them
       }
       if (joinRes.missing.length) {
@@ -10327,7 +10424,7 @@ async function pipelineInner(job, opts = {}) {
           const wf = await stage("register-unit", { ...ctx, axis: a }, { force: true, followup, sessionKey: unitKey[a], trigger: "plan-join" });
           if (!wf.ok) note(`register-unit ${a}: warm plan-join followup failed (${wf.fail}) — the plan-unexecuted StageFailure below holds the line`);
         }
-        joinRes = joinPlanToBands(ctx.registerPlan, readBands());
+        joinRes = holdStickyGaps(joinPlanToBands(ctx.registerPlan, readBands()));
         deriveNamedBand(ctx);   // the followup appended band blocks — re-merge so Layer B reads them
       }
       const skeleton = writeExecution(joinRes);
@@ -10402,6 +10499,7 @@ async function pipelineInner(job, opts = {}) {
           { failClass, repairs: fanInRepairs, quantity: joinRes.missing.length });
       }
       runLog(run.runDir, { event: "plan-execution", executed: joinRes.executed.length, skipped: joinRes.skipped.length, unplanned: joinRes.unplanned.length,
+        awaiting: joinRes.awaiting?.length ?? 0, asked: joinRes.asked?.length ?? 0,
         axes: skeleton.map((s) => `${s.axis}:${s.state}`) });
       // Decide the deferrals now — before placement-inquiry, which on the evidence run started one second
       // after this point on inputs the run had just recorded as unfinished.
@@ -11610,7 +11708,7 @@ async function pipelineInner(job, opts = {}) {
       // that designates no floor.
       if (owned.length > 0 && !floorBreachAxes.has(a.toLowerCase())) {
         const split = splitDeferredByCloseability(ledger, a, escalationGapAxes,
-          { fullyDeferred: escalationFullyDeferred.has(a.toLowerCase()) });
+          { fullyDeferred: escalationFullyDeferred.has(a.toLowerCase()), heldUnits: stickyGapUnits(P) });
         const openNonDeferred = owned.some((r) => r.status !== "deferred" && r.status !== "coverage-limited");
         if (split.held.length > 0 && split.closeable.length === 0 && !openNonDeferred) {
           note(`escalation skipped ${a} — capability-gap deferral: the active register provider cannot express those slices, so a re-run re-derives the same refusal (the gap stays open and disclosed)`);
@@ -11686,7 +11784,7 @@ async function pipelineInner(job, opts = {}) {
         // while ALSO carrying held rows — and the resumed unit must not be left to think those are
         // work it failed to do. Name them, exactly as the envelope's close followup does.
         const escHeld = splitDeferredByCloseability(ledger, a, escalationGapAxes,
-          { fullyDeferred: escalationFullyDeferred.has(a.toLowerCase()) }).held;
+          { fullyDeferred: escalationFullyDeferred.has(a.toLowerCase()), heldUnits: stickyGapUnits(P) }).held;
         if (escHeld.length) {
           followup += `\n\nNOT YOURS TO CLOSE — the active register provider cannot express these slices at all, so no re-run can reach them. Leave these Coverage-ledger rows exactly as they are (\`deferred\`, same reason), and do not restate them as searched or clean:\n${escHeld.map((r) => `| ${r.unit} | deferred | ${r.reason} |`).join("\n")}`;
         }
@@ -11762,8 +11860,9 @@ async function pipelineInner(job, opts = {}) {
       // time, still deferred, still an open floor, still disclosed.
       const gapAxes = capabilityGapAxes(ctx.registerPlan, readPlanExecution(ctx));
       const fullyDeferred = new Set((ctx.registerPlan ? fullyDeferredAxes(ctx.registerPlan) : []).map((a) => String(a.axis).toLowerCase()));
+      const stickyUnitsNow = stickyGapUnits(P);   // a gap this run already accepted is held whatever its row's reason says
       const closeabilityByAxis = new Map(deferredAxes.map((a) => [a,
-        splitDeferredByCloseability(ledgerNow, a, gapAxes, { fullyDeferred: fullyDeferred.has(String(a).toLowerCase()) })]));
+        splitDeferredByCloseability(ledgerNow, a, gapAxes, { fullyDeferred: fullyDeferred.has(String(a).toLowerCase()), heldUnits: stickyUnitsNow })]));
       const heldAxes = deferredAxes.filter((a) => {
         const s = closeabilityByAxis.get(a);
         // The `!hasBreach &&` term is retired with the ⭐ floor: it kept an axis carrying a
@@ -11805,6 +11904,10 @@ async function pipelineInner(job, opts = {}) {
             ? `\n\nThese rows on this axis are NOT yours to close and must stay exactly as they are — the active register provider cannot express those slices at all, so no re-run can reach them. Leave them \`deferred\`, keep their reason, and do not restate them as searched or clean:\n${split.held.map((r) => `| ${r.unit} | deferred | ${r.reason} |`).join("\n")}`
             : "";
           note(`envelope: closing deferred coverage on ${a} (deadline permits — ${decision.reason})`);
+          // What the re-opened unit is asked to close, and what it is told to leave: the record of the split
+          // this close acted on, so a gap handed back as work is visible in the run's own log.
+          runLog(run.runDir, { event: "envelope-close-rows", axis: a,
+            closeable: split.closeable.map((r) => String(r.unit ?? "")), held: split.held.map((r) => String(r.unit ?? "")) });
           const followup = repairFollowup("register-unit:envelope-close", { paths: P, axis: a, rows: rows + heldRows,
             supplementalLane: !!ctx.registerPlan?.contract?.supplemental_lane });
           const r = await stage("register-unit", { ...ctx, axis: a }, { force: true, followup, sessionKey: unitKey[a], trigger: "envelope" });
@@ -12241,6 +12344,7 @@ async function pipelineInner(job, opts = {}) {
           ledger: loadCoverageLedger(run.runDir).rows,   // fresh read — post-reopen/re-digest, same source as every gate
           planContext: { entries: ctx.registerPlan.entries ?? [], niceClasses: ctx.registerPlan.nice_classes ?? [], regions: ctx.registerPlan.regions ?? [] },
           executor: ccExecutor,
+          capabilities: registerCapabilities(),   // the contains floor, read the way the plan compile reads it
           note: (m) => note(m),
           log: (row) => runLog(run.runDir, row),   // the orchestrator's own crowd-context-failed row lands in run.jsonl
         });
@@ -15295,7 +15399,7 @@ async function pipelineInner(job, opts = {}) {
     {
       const mark = job.markName ?? job.name ?? job.ref ?? "the matter";
       const ref = job.ref ? ` (${job.ref})` : "";
-      const vtag = verdict ? ` — verdict ${verdict}` : "";
+      const vtag = emailVerdictOpts.tier ? ` Overall risk: ${emailVerdictOpts.tier}.` : "";   // the rating, never the reviewer's sign-off word (ruled 2026-09-22)
       // self-contained packet (the email body HTML is embedded so the courier needs no path resolution
       // across the archive move). The courier sends EXACTLY this — same subject, text and recipient the
       // deleted send stages composed, now composed in code.
@@ -15317,7 +15421,7 @@ async function pipelineInner(job, opts = {}) {
         // stated reason when no number is held. It used to go to AGENT_WHATSAPP[agent], which is the
         // operator on every run because every user shares one agent id.
         ...whatsappRouting(job, agent),
-        whatsappText: `✅ Clearotron search for ${mark}${ref}${vtag} is done. Report: ${published.url}`,
+        whatsappText: `✅ Clearotron search for ${mark}${ref} is done.${vtag} Report: ${published.url}`,
         url: published.url, verdict, markName: job.markName ?? job.name ?? null,
       };
       // A NEW send supersedes any previous one: .sent is PER-SEND idempotence, not per-run-lifetime.
@@ -15364,7 +15468,7 @@ async function pipelineInner(job, opts = {}) {
     // .published + .delivered on disk must never read "7/9" on any status surface (nothing runs after
     // the packet, so no stage transition would ever finish the display sequence). finalStepFields ⇒ 9/9.
     const deliveredAt = new Date().toISOString();
-    writeRunStatus(ctx, { state: "delivered", verdict, statement: emailVerdictOpts.statement ?? undefined, url: published.url, deliveredAt, sendPending: true, ...finalStepFields() });
+    writeRunStatus(ctx, { state: "delivered", verdict, statement: emailVerdictOpts.statement ?? undefined, caption: published.caption ?? undefined, url: published.url, deliveredAt, sendPending: true, ...finalStepFields() });
     // — THE POOL COPY LEARNS ITS OWN TERMINAL STATE, HERE AND NOWHERE ELSE.
     // `meta.json` cannot carry this: it is composed inside publish, before this line runs, so the state
     // did not exist yet when it was written. This is the one moment where the terminal state and the

package/driver/publish/index.mjs

@@ -14,7 +14,7 @@ import { parseReport, parseAudit, parseSections, parseBlocks, stripInternal, par
 import { renderHtml, parseActionBuckets, actYouConditions } from './render.mjs';
 import { buildAudit } from './xlsx.mjs';
 import { parseFindingsJson, parseFindingsJsonLenient, deriveDisplayVerdict, joinFindingToBlock, CLIENT_TIER_BY_COMPOSITE, projectCoverageJudgment } from '../findings-model.mjs';
-import { readStore, requiredAbsent, nonClosingAbsences } from './publish-inputs.mjs';   // — and why an absence did not close
+import { readStore, requiredAbsent, nonClosingAbsences } from './publish-inputs.mjs'; import { coverageFormStamp, readCoverageForm } from '../coverage-form-io.mjs'; import { coverageUnitLabel } from '../coverage-ledger.mjs';   // — and why an absence did not close
 import { clearanceReportData } from './report-data.mjs';
 import { searchDepthRecord, planTerritoriesOf } from './search-depth.mjs'; import { bandRecords } from '../named-band.mjs';   // how much was read to reach the answer, as counts and tokens
 import { parseFrameworkManifest } from '../framework.mjs';
@@ -251,11 +251,11 @@ function indexRows(runs, { reportFile, linkPrefix = '', showAudit = true, client
       <td>${anonMark(r.title, { key: ck, run: r.runId })}</td>
       <td>${anonClient(r.client, ck)}</td>
       <td><span class="b b-${attrValue(r.badge)}">${esc(r.overall)}</span>${qcFailed ? ' <span class="hold" title="machine QC checks failed — see the audit workbook">⚠ QC</span>' : ''}${!client && !qcFailed && r.clientGate?.inputsAbsent?.length ? ` <span class="disc" title="${escAttr(`published without ${r.clientGate.inputsAbsent.join(', ')} — each declared optional, so the release stands; the report was built without it`)}">◦ built without an input</span>` : ''}${
-        // spec 64 — the stance clause of THE one risk statement beside the (labelled) band pill, so the
-        // index can never show a bare severity word that reads as the whole answer. The tier word leads
-        // the statement; the pill already shows it, so the cell carries the clause after the first " — ".
-        // Legacy meta.json (no statement) renders this cell byte-identically.
-        r.statement ? `<span class="stmt" title="${escAttr(r.statement)}">${esc(String(r.statement).split(' — ').slice(1).join(' — ') || r.statement)}</span>` : ''}</td>
+        // The report's own conclusion beside the band pill (ruled 2026-09-22: the report is the master),
+        // never a second summary. A meta.json written before the caption was kept shows the pill alone:
+        // its stored statement could say "on hold", which was never true. The pill carries the rating,
+        // the single headline on this short surface.
+        r.caption ? `<span class="stmt" title="${escAttr(r.caption)}">${esc(r.caption)}</span>` : ''}</td>
       <td>${runCell}</td>${showAudit ? `
       <td>${r.auditFile ? `<a ${runAttrs} href="${linkPrefix}${attrValue(r.runId)}/${attrValue(r.auditFile)}">audit.xlsx</a>` : '—'}</td>` : ''}
     </tr>`;
@@ -872,6 +872,15 @@ export async function publishReport({ runId, codename, reportMd, auditMd, findin
     } catch { /* the workbook row is the record that matters; this line is the second copy */ }
   }
 
+  // ── THE WAITING FAMILIES THE READING TURN WITHHELD (withheld-families.mjs) ───────────────────────
+  //
+  // Ruled 2026-09-22: a family the reading turn chose not to ask is recorded with its reason in the run's
+  // record and in the audit workbook, and NOT in the report. The coverage form keeps these rows out of
+  // the ledger the report is built from, so this sheet is their one reader-facing place. Same builder,
+  // same four columns and the same state as the probes above; the area is the driver's own label and the
+  // words are the reading turn's reason.
+  const withheldFamilies = withheldFamilyRows(runDir ?? dirname(reportMd));
+
   // doc 50 — the run's FROZEN framework manifest (band vocabulary). Present on band-doctrine runs;
   // absent on every archived run (they render byte-identically on the legacy paths).
   let framework = null;
@@ -1134,7 +1143,7 @@ export async function publishReport({ runId, codename, reportMd, auditMd, findin
       // the same rule (the workbook's own BANNED gate had already started firing on the raw detail —
       // advisory, so CI stayed green). reviewReceipts.lint keeps its raw detail for the internal
       // readers above (fetchState reads registry-record-coverage's URIs out of it).
-      counts = await buildAudit({ droppedConditions, undispatchedProbes, findings, coverage, contextNotes, coverageJudgment, markAssessment, corrections: correctionsDoc, fetchState, verdict: verdictInfo, jurisdiction, commonLawJoinedTerms, registerOnly, clientGate, lintFailures: deliveryFlagLines(reviewReceipts.lint), productName, registerPublishesRecordPages: runOrigins == null ? null : runOrigins.length > 0, recordLinks: officeLinks?.byUri ?? null }, auditParsed, join(poolRunDir, auditFile), fm.title, fm);
+      counts = await buildAudit({ droppedConditions, undispatchedProbes, withheldFamilies, findings, coverage, contextNotes, coverageJudgment, markAssessment, corrections: correctionsDoc, fetchState, verdict: verdictInfo, jurisdiction, commonLawJoinedTerms, registerOnly, clientGate, lintFailures: deliveryFlagLines(reviewReceipts.lint), productName, registerPublishesRecordPages: runOrigins == null ? null : runOrigins.length > 0, recordLinks: officeLinks?.byUri ?? null }, auditParsed, join(poolRunDir, auditFile), fm.title, fm);
       grpRead(join(poolRunDir, auditFile), 0o640);
       if (counts?.gateViolations?.length) console.warn(`[audit-workbook] advisory: ${counts.gateViolations.join(' | ')}`);
     } catch (e) {
@@ -1342,6 +1351,7 @@ export async function publishReport({ runId, codename, reportMd, auditMd, findin
     // writer). Absent on legacy runs — regenIndex re-reads every historical meta.json, so consumers
     // null-guard and old rows render byte-identically.
     statement: verdictInfo?.statement ?? undefined,
+    caption: fm.overall_caption || undefined,   // the report's own conclusion, which the run list quotes
     verdict: verdictInfo?.verdict ?? undefined,
     // doc 50 — which framework rated this run (custom vs Generic default) + its ladder, for the archive
     // card, the email table sort/colour and the per-customer index; absent on archived runs forever.
@@ -1369,7 +1379,8 @@ export async function publishReport({ runId, codename, reportMd, auditMd, findin
   // `<origin>/<runId>/report.html` — where the documents sit on disk, which is not an application route.
   // Composed rather than spelled here so the report link is built the same way the audit link always was.
   const url = reportRouteFor(poolUrl, runId);
-  return { runId, auditFile, counts, total, url, poolRunDir, auditError, findingsError, customerKey: customerKey || 'generic', clientGate };
+  return { runId, auditFile, counts, total, url, poolRunDir, auditError, findingsError, customerKey: customerKey || 'generic', clientGate,
+    caption: fm.overall_caption || null };   // the report's own conclusion, for the run record's short surfaces
 }
 
 // Compose the notification email body — MARKDOWN (the mail tool renders markdown→HTML; raw HTML gets escaped).
@@ -1739,17 +1750,13 @@ export function composeEmailHtml(reportMdPath, url, auditFile, names = [], deliv
   // the engine clamp reasons (opts.conditions = verdict.json reasons). Machinery-only clamps (no client
   // item authored) degrade to one generic plain line — never raw engine jargon, never truncated mid-sentence.
   const emailConditions = opts?.verdict === 'CONDITIONAL' ? actYouConditions(parseActionBuckets(secs['Actions']).you) : [];
-  // THE BANNER SPEAKS THE RUN'S OWN SENTENCE. It used to print the delivery gate's word — "Delivered as
-  // BLOCKING" — which is engine vocabulary and, beside a Medium rating on the report, reads as a
-  // contradiction the reader cannot resolve (measured 2026-09-20). The statement is composed once by the
-  // sidecar writer and is what the report and the index already show; a run recorded before statements
-  // were persisted keeps the old line, which is all such a run has.
-  const bound = String(opts?.statement ?? '').trim();
-  const boundHead = bound
-    ? esc(bound)
-    : `Delivered as ${esc(opts?.verdict ?? '')}${opts?.verdict === 'CONDITIONAL' ? ' — subject to:' : '.'}`;
-  const verdictBound = (opts?.verdict && opts.verdict !== 'CLEAR')
-    ? `<p style="margin:0 0 8px;padding:8px 10px;background:#fdeeee;border:1px solid #c98a86;color:#6e1512"><b>${boundHead}</b>${opts.verdict === 'CONDITIONAL' ? `<br>${(emailConditions.length ? emailConditions : ['the open items set out in the report, before relying on a clean result']).map((r) => `• ${cell(String(r))}`).join('<br>')}` : ''}</p>`
+  // THE REPORT IS THE MASTER (ruled 2026-09-22). The banner used to print a second summary composed
+  // beside the report — "On hold — …" on a run the report called conditional, although nothing is ever
+  // held — and before that the delivery gate's word. It now quotes the report: the rating, then the
+  // report's own conclusion (below), and where the report names what only the client can close, those
+  // items under the report's own heading. Nothing here composes a sentence of its own.
+  const verdictBound = opts?.verdict === 'CONDITIONAL'
+    ? `<p style="margin:0 0 8px;padding:8px 10px;background:#fdeeee;border:1px solid #c98a86;color:#6e1512"><b>Only you can close these</b><br>${(emailConditions.length ? emailConditions : ['the open items set out in the report, before relying on a clean result']).map((r) => `• ${cell(String(r))}`).join('<br>')}</p>`
     : '';
 
   const reviewHeadline = `<div style="${FONT};font-size:11pt;color:#1a1a2e;margin:0 0 14px">`
@@ -1757,12 +1764,11 @@ export function composeEmailHtml(reportMdPath, url, auditFile, names = [], deliv
     + verdictBound
     + `<p style="margin:0 0 8px"><b>${[opts?.productName ? esc(String(opts.productName)) : '', esc(fm.title || '')].filter(Boolean).join(' — ')} (${esc(fm.matter || '')})</b></p>`
     // T2 (H5): the derived tier (verdict sidecar, passed by the driver) outranks the
-    // model-authored fm label — one authority on every surface.
-    // spec 64: with a composed statement the headline reads band + stance as ONE sentence ("High —
-    // conditional on: …"); legacy (no statement) keeps the labelled tier line byte-identically.
-    + (opts?.statement
-      ? `<p style="margin:0 0 6px"><b>${esc(opts.statement)}</b> ${cell(fm.overall_caption || '')}</p>`
-      : ((opts?.tier ?? fm.overall_label) ? `<p style="margin:0 0 6px"><b>Overall risk: ${esc(opts?.tier ?? fm.overall_label)}.</b> ${cell(fm.overall_caption || '')}</p>` : ''))
+    // model-authored fm label — one authority on every surface. The rating leads, then the report's own
+    // conclusion verbatim (ruling 244); with no rating recorded, the conclusion stands alone.
+    + ((opts?.tier ?? fm.overall_label)
+      ? `<p style="margin:0 0 6px"><b>Overall risk: ${esc(opts?.tier ?? fm.overall_label)}.</b> ${cell(fm.overall_caption || '')}</p>`
+      : (fm.overall_caption ? `<p style="margin:0 0 6px">${cell(fm.overall_caption)}</p>` : ''))
     + reportLink
     + (fm.handling_note ? `<p style="margin:0 0 8px;color:#7a2b12"><b>Handling note:</b> ${cell(fm.handling_note)}</p>` : '')
     // T9 (K3): methodology identity — which profile/framework rated this run (+ verifiable sha).
@@ -1811,3 +1817,12 @@ function officeLinksFor(findings, recordsByUri, runOrigins) {
   if (links) console.log(`[record-links] ${links.summary}`);
   return links;
 }
+
+/** The coverage form's family rows judged withheld, as audit-workbook coverage rows. Never throws. */
+export function withheldFamilyRows(runDir) {
+  try {
+    const { rows } = readCoverageForm(runDir, coverageFormStamp(runDir).formName);
+    return (rows ?? []).filter((r) => r?.kind === 'family' && r.status === 'withheld-by-judgment' && r.reason)
+      .map((r) => ({ area: coverageUnitLabel(r.unit), state: 'not-searched', note: String(r.reason) }));
+  } catch { return []; }
+}

package/driver/publish/xlsx.mjs

@@ -302,7 +302,7 @@ export function searchRows(auditParsed, { findings = [], joinedTerms = null, reg
     const byTerm = new Map();
     for (const n of cl) {
       const key = (n.search_term || '').trim();
-      if (!byTerm.has(key)) { byTerm.set(key, { plats: new Set(), results: new Set(), notes: [], gaps: new Set() }); order.push(key); }
+      if (!byTerm.has(key)) { byTerm.set(key, { plats: new Set(), results: new Set(), notes: [], gaps: new Set(), gapReasons: new Map() }); order.push(key); }
       const g = byTerm.get(key);
       if (n.platform) g.plats.add(n.platform);
       if (n.result) g.results.add(n.result);
@@ -310,7 +310,17 @@ export function searchRows(auditParsed, { findings = [], joinedTerms = null, reg
       // — the surfaces that could NOT be searched are counted separately from the ones that came back
       // empty. The dedup unions results across platforms, so one gapped surface among many used to vanish
       // entirely into a term-level "0 — clean".
-      if (notSearched(n, n.result, n.notes)) g.gaps.add(n.platform || '?');
+      // — THE REGISTER'S OWN WORDS, KEPT. A surface that could not be searched arrives here with the
+      // reason it gave (`audit-from-spine` puts the gap's `error` into `notes`), and this row used to
+      // record only that it was a gap. So a query a provider REFUSED — "content policy (HTTP 400)" —
+      // and one that was simply never run rendered as the same sentence, and the reason was in the
+      // workbook's hand the whole time. `audit.md` kept it; this file dropped it.
+      if (notSearched(n, n.result, n.notes)) {
+        const surface = n.platform || '?';
+        g.gaps.add(surface);
+        const said = plainNote(n.notes || '').trim();
+        if (said) g.gapReasons.set(surface, said);
+      }
     }
     push({ 'Search term / variant': COMMON_LAW_SECTION, Scope: '', Result: '', Outcome: '', Note: '', _section: true });
     for (const term of order) {
@@ -329,7 +339,19 @@ export function searchRows(auditParsed, { findings = [], joinedTerms = null, reg
       // searched at all. The gap count is carried beside the hit flag, never folded into it.
       const gaps = [...g.gaps];
       const ran = Math.max(0, n - gaps.length);
-      const gapNote = gaps.length ? ` ${gaps.length} surface${gaps.length === 1 ? '' : 's'} could not be searched (${gaps.slice(0, 4).join(', ')}${gaps.length > 4 ? ', …' : ''}) — this term is NOT closed across them.` : '';
+      // A REFUSAL AND A DROP ARE DIFFERENT FACTS, and only one of them is about the register. Where the
+      // surface said why, its words are quoted; where nothing was recorded, the row says that instead of
+      // implying a reason it does not have. A reader deciding whether to re-run needs to know which:
+      // a content-policy refusal will refuse again, a query that never ran may simply run.
+      const said = gaps.map((s) => [s, g.gapReasons.get(s)]).filter(([, r]) => r);
+      const silent = gaps.filter((s) => !g.gapReasons.has(s));
+      const reasonNote = said.length
+        ? ` The surface${said.length === 1 ? '' : 's'} gave a reason: ${said.map(([s, r]) => `${s} — ${r}`).join('; ')}.`
+        : '';
+      const silentNote = silent.length && said.length
+        ? ` ${silent.length} recorded no reason (${silent.slice(0, 4).join(', ')}${silent.length > 4 ? ', …' : ''}).`
+        : silent.length ? ' No reason was recorded for any of them.' : '';
+      const gapNote = gaps.length ? ` ${gaps.length} surface${gaps.length === 1 ? '' : 's'} could not be searched (${gaps.slice(0, 4).join(', ')}${gaps.length > 4 ? ', …' : ''}) — this term is NOT closed across them.${reasonNote}${silentNote}` : '';
       const outcome = anyHit ? (joined ? '→ Findings' : 'Reviewed — not carried as a conflict')
         : gaps.length && !ran ? NOT_SEARCHED_OUTCOME          // nothing ran at all: never a closure claim
           : gaps.length ? 'No conflict — partial'             // some ran clean, some never ran: say both
@@ -637,7 +659,7 @@ export async function buildAudit(contract, auditParsed, outPath, mark = '', fm =
   // shape and not a new sheet, and the words are the run receipt's own.
   addSheet(wb, 'Coverage & gaps', COVERAGE_COLS,
     [...coverageRows(coverage), ...coverageRows(contract?.droppedConditions || []),
-     ...coverageRows(contract?.undispatchedProbes || [])], (row, _d, kept) => {
+     ...coverageRows(contract?.undispatchedProbes || []), ...coverageRows(contract?.withheldFamilies || [])], (row, _d, kept) => {
     if (!kept.has('State')) return;
     const st = row.getCell('State'); const f = STATE_FILL[String(st.value).trim()];
     if (f) { st.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF' + f } }; st.font = { bold: true }; }