@codedology/code-forge 0.5.1 → 0.6.0

package/src/doctor/probes.mjs

@@ -2,7 +2,9 @@
  * Doctor rows that run the provider CLIs (plan §2.3, §0.6; block B13b):
  *  - per CLI: present + version + `--help` flag probe (B4 `probeHelpText`; a missing flag FAILs);
  *  - one real call per role builder (coder, reviewer, s2 with the compiled S2 schema, facts) through
- *    B9a `spawnSession` — an HTTP 402 is `ping=skipped(402)` WARN, never FAIL (§0.6.1);
+ *    B9a `spawnSession` — an HTTP 402 is `ping=skipped(402)` WARN, never FAIL (§0.6.1); when the
+ *    config has an `autopilot` section (B46), one `delegate` ping per delegate level (L2, L3) with
+ *    the delegate schema — an openai level FAILs unrun whatever `review.allow_open_book_codex` says;
  *  - the isolation probe (O4, §0.6.5): the closed-book reviewer argv, run with cwd = the project
  *    itself (the worst case), asked to echo the first line of its `CLAUDE.md`/`AGENTS.md` — the
  *    line appearing in its answer FAILs; the CLI rejecting the closed-book flag combination FAILs;
@@ -33,6 +35,8 @@ import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { commandOnPath } from '../install/detect.mjs';
 import { classifyUnavailable, readAnswer, spawnSession } from '../session/spawn.mjs';
 import { S2_SCHEMA } from '../session/s2.mjs';
+import { DELEGATE_SCHEMA } from '../autopilot/delegate.mjs';
+import { DELEGATE_LEVELS } from '../autopilot/scopes.mjs';
 import { runsDir } from '../state/paths.mjs';
 import { exec } from '../util/exec.mjs';
 import { gitChildEnv } from '../worker/ticket.mjs';
@@ -48,6 +52,23 @@ export const PING_ROLES = Object.freeze([
   { role: 's2', level: 'L3' },
 ]);
 
+/**
+ * B46: the delegate pings, one per level a grant may name — run only when the config has an
+ * `autopilot` section (a project that never uses autopilot pays for no extra call).
+ * @param {Record<string, any>} cfg @returns {Array<{role: string, level: string, id: string}>}
+ */
+export function delegatePings(cfg) {
+  const on = cfg?.autopilot !== null && typeof cfg?.autopilot === 'object';
+  return on ? DELEGATE_LEVELS.map((level) => ({ role: 'delegate', level, id: `ping.delegate.${level}` })) : [];
+}
+
+/** What each schema'd ping is told to answer, so a working CLI matches the schema. */
+const PING_ANSWER = Object.freeze({
+  s2: 'Answer with decision "proceed", confidence 1, reason "ping", overrule false, ask_human false, human_question null.\n',
+  delegate: 'Answer with decision "proceed", within_scope true, confidence 1, reason "ping", escalate false.\n',
+});
+const PING_SCHEMA = Object.freeze({ s2: S2_SCHEMA, delegate: DELEGATE_SCHEMA });
+
 const LEVELS = Object.freeze(['L0', 'L1', 'L2', 'L3']);
 const PROBE_TIMEOUT_MS = 180000;
 const PROBE_BUDGET_USD = 0.5;
@@ -196,28 +217,30 @@ function levelName(cfg, level) {
  */
 export async function pingRoles(ctx, missingProviders) {
   const rows = [];
-  for (const { role, level } of PING_ROLES) {
-    const label = `ping ${role} (${levelName(ctx.cfg, level)})`;
+  const pings = [...PING_ROLES.map((p) => ({ ...p, id: `ping.${p.role}` })), ...delegatePings(ctx.cfg)];
+  for (const { role, level, id } of pings) {
+    const label = role === 'delegate' ? `ping delegate ${level} (${levelName(ctx.cfg, level)})` : `ping ${role} (${levelName(ctx.cfg, level)})`;
     const provider = ctx.cfg.levels?.[level]?.provider ?? ctx.cfg.provider;
     if (missingProviders.has(provider)) {
-      rows.push(row(`ping.${role}`, 'FAIL', label, 'ping=skipped(cli-missing)'));
+      rows.push(row(id, 'FAIL', label, 'ping=skipped(cli-missing)'));
       continue;
     }
     if (closedBookRefused(resolvedProvider(ctx.cfg, /** @type {'L0'|'L1'|'L2'|'L3'} */ (level)), role, openBookCodexAllowed(ctx.cfg))) {
-      rows.push(row(`ping.${role}`, 'FAIL', label, CODEX_CLOSED_BOOK_REFUSAL)); // B32: the spawner would refuse it
+      rows.push(row(id, 'FAIL', label, CODEX_CLOSED_BOOK_REFUSAL)); // B32/B46: the spawner would refuse it
       continue;
     }
+    const schemaRole = /** @type {'s2' | 'delegate' | null} */ (role === 's2' || role === 'delegate' ? role : null);
     const res = await session(ctx, {
       role,
       level,
-      prompt: role === 's2' ? `${PING_TEXT}Answer with decision "proceed", confidence 1, reason "ping", overrule false, ask_human false, human_question null.\n` : PING_TEXT,
-      ...(role === 's2' ? { schema: S2_SCHEMA } : {}),
+      prompt: schemaRole ? `${PING_TEXT}${PING_ANSWER[schemaRole]}` : PING_TEXT,
+      ...(schemaRole ? { schema: PING_SCHEMA[schemaRole] } : {}),
       ...(role === 'coder' ? { cwd: await tempRepo(ctx) } : {}),
     });
-    if (skipped402(res)) rows.push(row(`ping.${role}`, 'WARN', label, 'ping=skipped(402)'));
-    else if (res.status === 'ok') rows.push(row(`ping.${role}`, 'OK', label, 'ping=ok'));
-    else if (res.status === 'invalid-output') rows.push(row(`ping.${role}`, 'WARN', label, 'ping=answered (schema mismatch)'));
-    else rows.push(row(`ping.${role}`, 'FAIL', label, `ping=${res.status}(${res.reason ?? 'unknown'})`));
+    if (skipped402(res)) rows.push(row(id, 'WARN', label, 'ping=skipped(402)'));
+    else if (res.status === 'ok') rows.push(row(id, 'OK', label, 'ping=ok'));
+    else if (res.status === 'invalid-output') rows.push(row(id, 'WARN', label, 'ping=answered (schema mismatch)'));
+    else rows.push(row(id, 'FAIL', label, `ping=${res.status}(${res.reason ?? 'unknown'})`));
   }
   return rows;
 }

package/src/engines/builders/claude.mjs

@@ -57,7 +57,7 @@ export const CLI = 'claude';
 
 /**
  * @typedef {object} ClaudeBuildParams
- * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} role
  * @property {string} model - the resolved model id (already picked by `resolveLevel`, B1).
  * @property {string} [effort] - one of `PROVIDER_EFFORTS.anthropic` (`../efforts.mjs`) when given.
  * @property {string} promptPath - the brief file (coder: passed as a pointer) or the packet file
@@ -86,7 +86,7 @@ export const CLI = 'claude';
 /**
  * @typedef {object} BuiltClosedBook
  * @property {"claude"} cli
- * @property {"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} role
  * @property {string[]} argv - no prompt positional.
  * @property {string} cwd
  * @property {string} stdinFile - the packet file the spawner pipes to stdin.
@@ -190,7 +190,7 @@ function buildClosedBookArgv(params) {
   assertValidBudget(maxBudgetUsd, 'buildClaudeArgv');
   // The dispatch in `buildClaudeArgv` never reaches this branch with role 'coder' — a runtime
   // invariant the parameter type alone cannot prove, so the narrowing is explicit.
-  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
+  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} */ (params.role);
   const isFacts = role === 'facts';
   if (isFacts && !hasAnyRenderedRule(renderedForbidden)) {
     throw new Error('buildClaudeArgv: facts role requires a non-empty forbidden-list render (got 0 usable rules)');

package/src/engines/builders/codex.mjs

@@ -65,7 +65,7 @@ import { CODEX_RULES_FILE_NAME, defaultCodexHome, isInside, prepareCodexHome } f
 import { hasAnyRenderedRule } from '../render-rules.mjs';
 import { assertEffortForProvider, PROVIDER_EFFORTS } from '../efforts.mjs';
 import { assertBaseParams } from './validate-params.mjs';
-import { CODEX_CLOSED_BOOK_REFUSAL, isNoToolRole } from '../../config/closed-book.mjs';
+import { CODEX_CLOSED_BOOK_REFUSAL, isNeverOpenBookRole, isNoToolRole } from '../../config/closed-book.mjs';
 
 export const CLI = 'codex';
 
@@ -104,7 +104,7 @@ export const VALID_EFFORTS = PROVIDER_EFFORTS.openai;
 
 /**
  * @typedef {object} CodexBuildParams
- * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} role
  * @property {string} model
  * @property {string} [effort] - one of {@link VALID_EFFORTS} when given.
  * @property {string} promptPath - the brief file (coder: passed as a pointer) or the packet file
@@ -217,14 +217,14 @@ function buildCoderArgv(params) {
 
 /**
  * @param {CodexBuildParams} params
- * @returns {{cli: "codex", role: "reviewer"|"judge"|"s2"|"author"|"facts", argv: string[], cwd: string, outPath: string, stdinFile: string}}
+ * @returns {{cli: "codex", role: "reviewer"|"judge"|"s2"|"author"|"facts"|"delegate", argv: string[], cwd: string, outPath: string, stdinFile: string}}
  */
 function buildClosedBookArgv(params) {
   const { model, effort, promptPath, cwd, schemaPath } = params;
   assertValidEffort(effort);
   // See `builders/claude.mjs`'s identical cast: the dispatch below never reaches this branch with
   // role 'coder'; a no-tools role reaches it only with `allowOpenBook: true` (B32).
-  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
+  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} */ (params.role);
   const outPath = effectiveOutPath(params.outPath, role);
   const argv = ['codex', 'exec', '-m', model];
   if (effort) argv.push('-c', `model_reasoning_effort=${effort}`);
@@ -248,9 +248,10 @@ function buildClosedBookArgv(params) {
  */
 export function buildCodexArgv(params) {
   assertBaseParams('buildCodexArgv', params);
-  if (isNoToolRole(params.role) && params.allowOpenBook !== true) {
+  if (isNoToolRole(params.role) && (params.allowOpenBook !== true || isNeverOpenBookRole(params.role))) {
     // B32: no Codex flag removes the shell, so a no-tools role is built only when the caller
     // passes `allowOpenBook: true` (the config's `review.allow_open_book_codex` opt-in).
+    // B46: the autopilot delegate is never built on Codex, opt-in or not.
     throw Object.assign(new Error(CODEX_CLOSED_BOOK_REFUSAL), { code: 'closed-book' });
   }
   return params.role === 'coder' ? buildCoderArgv(params) : buildClosedBookArgv(params);

package/src/engines/builders/grok.mjs

@@ -56,7 +56,7 @@ export const GROK_ALL_BUILTIN_TOOLS = Object.freeze(['Bash', 'Read', 'Write', 'E
 
 /**
  * @typedef {object} GrokBuildParams
- * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} role
  * @property {string} model
  * @property {string} [effort] - a non-empty string when given.
  * @property {string} promptPath - `--prompt-file` value (brief for coder, packet for closed-book).
@@ -100,14 +100,14 @@ function buildCoderArgv(params) {
 
 /**
  * @param {GrokBuildParams} params
- * @returns {{cli: "grok", role: "reviewer"|"judge"|"s2"|"author"|"facts", argv: string[], cwd: string}}
+ * @returns {{cli: "grok", role: "reviewer"|"judge"|"s2"|"author"|"facts"|"delegate", argv: string[], cwd: string}}
  */
 function buildClosedBookArgv(params) {
   const { model, effort, promptPath, cwd, schema, systemPromptText } = params;
   assertValidEffort(effort);
   // See `builders/claude.mjs`'s identical cast: the dispatch below never reaches this branch
   // with role 'coder', but that is a runtime invariant, not provable from the parameter type.
-  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
+  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate"} */ (params.role);
   const argv = ['grok', '--prompt-file', promptPath, '-m', model];
   if (effort) argv.push('--reasoning-effort', effort);
   if (schema !== undefined) argv.push('--json-schema', JSON.stringify(schema));

package/src/engines/builders/validate-params.mjs

@@ -7,10 +7,10 @@
  */
 
 /**
- * The six roles the plan's engine adapters section (§5.2) declares.
- * @type {ReadonlyArray<"coder"|"reviewer"|"judge"|"s2"|"author"|"facts">}
+ * The six roles the plan's engine adapters section (§5.2) declares, plus the autopilot `delegate` (B46, closed-book).
+ * @type {ReadonlyArray<"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"|"delegate">}
  */
-export const VALID_ROLES = Object.freeze(/** @type {const} */ (['coder', 'reviewer', 'judge', 's2', 'author', 'facts']));
+export const VALID_ROLES = Object.freeze(/** @type {const} */ (['coder', 'reviewer', 'judge', 's2', 'author', 'facts', 'delegate']));
 
 /**
  * @param {string} builderName - for the thrown message, e.g. `"buildClaudeArgv"`.

package/src/ledger/report.mjs

@@ -24,6 +24,8 @@ const ROLE_BUCKET = Object.freeze({
   reviewer: 'reviewUsd',
   judge: 'reviewUsd',
   s2: 's1s2Usd',
+  // B46: the autopilot delegate answers one owner-level question per session, like S2
+  delegate: 's1s2Usd',
   facts: 'factsUsd',
 });
 

package/src/review/fixloop.mjs

@@ -33,6 +33,12 @@
  *     new_in_hunks, late, open_after, tokens_in, tokens_out}`; a converged file gets
  *     `review.approved {file, content_hash, round}` (the worker signs every row it writes).
  *
+ * Autopilot extra round (B47): `deps.extraRounds` (from {@link extraRoundsFor}: one per signed
+ * `autopilot.extra_round` row for the file, one per grant) raises the file's cap by that many
+ * rounds — the cap checks here and rule 6 in `escalationAfterAttempt` both use the raised cap. A
+ * file already stopped at `review_cap` is reopened for its extra round by
+ * {@link reopenForExtraRound} (the worker calls it before the round).
+ *
  * Over budget (B12a follow-up, decided here): a recheck packet over `review.budgets.full_in`
  * falls to `contextMode: 'minimal'` (± `min_context_lines` around the SAME fix hunks) exactly as
  * `assemblePacket` does for any packet. The budget is a hard ceiling on what one session reads;
@@ -54,6 +60,8 @@ import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import { escalationAfterAttempt, heavyRound, reviewRoundStalled } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
+import { verifyRow } from '../state/signer.mjs';
+import { decisionProblem, grantCoverProblem } from './gate-check.mjs';
 import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
 import { parseDiff } from './context.mjs';
 import { assemblePacket, assertPacketPath, readFileDiff } from './packet.mjs';
@@ -103,6 +111,7 @@ import { spawnWithTimeoutRetry } from './session-retry.mjs';
  * @property {(req: {file: string, level: 'L3', open: Finding[]}) => Promise<unknown>} [patch] - the L3 patch rung (≤ 80 lines, owned files only).
  * @property {string | null} [base] - the block base (only for `recheck_scope: file`).
  * @property {string} [rulesDigest] @property {string} [factsExcerpt]
+ * @property {number} [extraRounds] - B47: rounds past `review.max_rounds_per_file` granted by autopilot (`extraRoundsFor`).
  */
 
 /** @param {LoopDeps} deps @param {Record<string, any>} row */
@@ -114,13 +123,68 @@ async function note(deps, row) {
   }
 }
 
-/** @param {Record<string, any> | undefined} cfg */
-function settings(cfg) {
+/** @param {unknown} v @param {number} d @returns {number} `v` when a non-negative integer, else `d`. */
+const int = (v, d) => (Number.isInteger(v) && /** @type {number} */ (v) >= 0 ? /** @type {number} */ (v) : d);
+
+/**
+ * The file's round cap: `review.max_rounds_per_file` (default 4) plus the autopilot extra rounds.
+ * @param {Record<string, any> | undefined} cfg @param {number} [extraRounds]
+ * @returns {number}
+ */
+export function roundCap(cfg, extraRounds = 0) {
+  return int(cfg?.review?.max_rounds_per_file, 4) + int(extraRounds, 0);
+}
+
+/**
+ * B47: the extra rounds autopilot granted the file — the number of distinct grants with an
+ * `autopilot.extra_round` row of this run for this block and file that holds up as the gate's
+ * waiver check does: its MAC verifies, its grant covered `round:extra` at its `ts`
+ * (`grantCoverProblem`) and its `decision_id` names the delegate's acted decision for that block
+ * and file (`decisionProblem`). A row that fails any check, or whose check throws, counts for nothing.
+ * @param {Array<Record<string, any>>} rows @param {{runId: string, block: string, file: string, key: Buffer}} where
+ * @returns {number}
+ */
+export function extraRoundsFor(rows, { runId, block, file, key }) {
+  const runRows = rows.filter((r) => r?.run === runId);
+  const grants = new Set();
+  for (const r of runRows) {
+    if (r?.event !== 'autopilot.extra_round' || r.block !== block || r.file !== file || typeof r.grant_id !== 'string') continue;
+    try {
+      if (!verifyRow(r, key).ok) continue;
+      const at = typeof r.ts === 'string' ? Date.parse(r.ts) : Number.NaN;
+      if (!Number.isFinite(at)) continue;
+      if (grantCoverProblem(runRows, { grantId: r.grant_id, scope: 'round:extra', at, key, endRows: rows }) !== null) continue;
+      if (decisionProblem(runRows, { decisionId: r.decision_id, grantId: r.grant_id, scope: 'round:extra', subject: { block, file }, decision: 'allow', at, key }) !== null) continue;
+      grants.add(r.grant_id);
+    } catch {
+      // a row the checks cannot read gives no round (fail closed)
+    }
+  }
+  return grants.size;
+}
+
+/**
+ * B47: reopen a file stopped at `review_cap` when its raised cap leaves a round: the state goes
+ * back to `open` with `next: fix` at its level (`trigger: autopilot_extra_round`); the next round
+ * is a recheck. Any other state is left as it is.
+ * @param {FileState} state @param {number} extraRounds @param {Record<string, any> | undefined} cfg
+ * @returns {boolean} whether the state was reopened.
+ */
+export function reopenForExtraRound(state, extraRounds, cfg) {
+  if (state.status !== 'stopped' || state.next?.reason !== 'review_cap') return false;
+  if (state.round >= roundCap(cfg, extraRounds)) return false;
+  state.status = 'open';
+  state.next = { action: 'fix', level: state.level, trigger: 'autopilot_extra_round' };
+  state.pending_kind = null;
+  return true;
+}
+
+/** @param {Record<string, any> | undefined} cfg @param {number} [extraRounds] */
+function settings(cfg, extraRounds = 0) {
   const r = cfg?.review ?? {};
   const e = cfg?.escalation ?? {};
-  const int = (/** @type {unknown} */ v, /** @type {number} */ d) => (Number.isInteger(v) && /** @type {number} */ (v) >= 0 ? /** @type {number} */ (v) : d);
   return {
-    maxRounds: int(r.max_rounds_per_file, 4),
+    maxRounds: roundCap(cfg, extraRounds),
     scope: r.recheck_scope === 'file' ? 'file' : 'fix_hunks',
     late: r.late_findings === 'block' ? 'block' : 'sweep',
     perLevel: int(e.review_rounds_per_level, 2),
@@ -332,7 +396,7 @@ async function stopBeforeRound(state, deps, kind, file, reason) {
  * @returns {Promise<FileState>}
  */
 export async function runRound(state, deps, opts = {}) {
-  const s = settings(deps.cfg);
+  const s = settings(deps.cfg, deps.extraRounds);
   const kind = opts.kind ?? (state.round === 0 ? 'full' : 'recheck');
   const current = readCurrent(deps.repoRoot, state.file);
   const openBefore = state.open.length;

package/src/review/gate-check.mjs

@@ -17,6 +17,18 @@
  * (`file` + `finding`; a finding id is scoped to one file, so a waiver of `F1` in `a.mjs` never
  * clears `F1` in `b.mjs`); a late finding counts whether or not it is signed (fail closed).
  *
+ * B47 (autopilot): a `review.waived {by: autopilot}` row (written by `autopilot waive`) clears a
+ * finding ONLY when {@link autopilotWaiverProblem} finds nothing wrong with it: its MAC verifies;
+ * the finding is not `proof`; the finding's severity recorded in the block's signed review rows
+ * (`review.triage`, `review.late_finding`; {@link recordedSeverity}) is `warning` or `nit` and
+ * equals the waiver's `severity`; a signed `autopilot.grant` row of this run with the waiver's
+ * `grant_id` exists, its window (`ts` ≤ waiver `ts` < `until`) holds the waiver, and its scopes
+ * include `waive:<severity>`; no `autopilot.stop` / `autopilot.expire` row for that grant is
+ * dated at or before the waiver (or undated); and its `decision_id` names a signed, acted
+ * `autopilot.decision` of the same grant, scope, block, file and finding made at most 30 min
+ * before it ({@link decisionProblem}). Otherwise the waiver is ignored and the finding is refused as
+ * `autopilot_waiver_invalid` (the detail says why). `by: human` waivers are unchanged.
+ *
  * `block waive <id> <finding> --file <path> --reason <text>` (`waiveFinding`) writes a signed
  * `review.waived` row with `by: human`. The orchestrator runs it only after the human said so in chat; the brief
  * never mentions it; for a coder the argv is forbidden (`mergeForbidden()` always carries B12b's
@@ -34,7 +46,7 @@ import { tierFor } from '../proof/tiers.mjs';
 import { DELETED_HASH, contentHash, gitChildEnv } from '../worker/ticket.mjs';
 
 /**
- * @typedef {{code: 'unreviewed' | 'unsigned' | 'rule_break' | 'late_unruled' | 'review_cap' | 'unproven', file?: string, finding?: string, detail?: string}} Refusal
+ * @typedef {{code: 'unreviewed' | 'unsigned' | 'rule_break' | 'late_unruled' | 'review_cap' | 'unproven' | 'autopilot_waiver_invalid', file?: string, finding?: string, detail?: string}} Refusal
  */
 
 /** @param {Record<string, any>} row @param {Buffer} key */
@@ -76,28 +88,166 @@ export function checkBlockReviews({ block, runId, files, rows, key, transcript =
 
   const signedOf = (/** @type {string} */ event) => mine.filter((r) => r.event === event && verified(r, key));
   const waivers = signedOf('review.waived').filter((r) => r.by === 'human');
+  const autopilotWaivers = mine.filter((r) => r.event === 'review.waived' && r.by === 'autopilot');
+  const runRows = rows.filter((r) => r?.run === runId);
   const rulings = signedOf('review.late_ruling');
   const matches = (/** @type {Record<string, any>} */ r, /** @type {string} */ file, /** @type {string} */ finding) => r.finding === finding && r.file === file;
-  const waived = (/** @type {string} */ file, /** @type {string} */ finding) => waivers.some((r) => matches(r, file, finding));
+  /**
+   * Whether the finding is waived: a signed human waiver, or an autopilot waiver its grant covered.
+   * `invalid`: why the autopilot waivers naming it do not count (null when none names it).
+   * @param {string} file @param {string} finding @returns {{waived: boolean, invalid: string | null}}
+   */
+  const waiverFor = (file, finding) => {
+    if (waivers.some((r) => matches(r, file, finding))) return { waived: true, invalid: null };
+    const named = autopilotWaivers.filter((r) => matches(r, file, finding));
+    if (named.length === 0) return { waived: false, invalid: null };
+    const problems = named.map((w) => autopilotWaiverProblem(w, { blockRows: mine, runRows, allRows: rows, key }));
+    if (problems.some((p) => p === null)) return { waived: true, invalid: null };
+    return { waived: false, invalid: /** @type {string} */ (problems[0]) };
+  };
+  /** @param {Refusal} refusal @param {string} finding @param {string | null} invalid @returns {Refusal} */
+  const orInvalid = (refusal, finding, invalid) =>
+    invalid === null ? refusal : { code: 'autopilot_waiver_invalid', file: refusal.file, finding, detail: `the autopilot waiver of ${finding} in ${refusal.file} does not count: ${invalid}` };
 
   for (const late of mine.filter((r) => r.event === 'review.late_finding')) {
-    if (rulings.some((r) => matches(r, late.file, late.finding)) || waived(late.file, late.finding)) continue;
-    refusals.push({ code: 'late_unruled', file: late.file, finding: late.finding, detail: `late finding ${late.finding} in ${late.file} has no ruling` });
+    if (rulings.some((r) => matches(r, late.file, late.finding))) continue;
+    const w = waiverFor(late.file, late.finding);
+    if (w.waived) continue;
+    refusals.push(orInvalid({ code: 'late_unruled', file: late.file, finding: late.finding, detail: `late finding ${late.finding} in ${late.file} has no ruling` }, late.finding, w.invalid));
   }
 
   for (const cap of mine.filter((r) => r.event === 'review.cap')) {
     const hash = hashOf.get(cap.file);
     if (hash !== undefined && approvedFor(cap.file, hash).some((r) => verified(r, key))) continue;
     for (const finding of Array.isArray(cap.open) ? cap.open : []) {
-      if (!waived(cap.file, finding)) refusals.push({ code: 'review_cap', file: cap.file, finding, detail: `${cap.file} stopped at review_cap; finding ${finding} is open and not waived` });
+      const w = waiverFor(cap.file, finding);
+      if (!w.waived) refusals.push(orInvalid({ code: 'review_cap', file: cap.file, finding, detail: `${cap.file} stopped at review_cap; finding ${finding} is open and not waived` }, finding, w.invalid));
     }
   }
   for (const r of checkBlockProof({ runId, files: proofFiles, rows: mine, key, highPaths })) {
-    if (!waived(/** @type {string} */ (r.file), PROOF_FINDING)) refusals.push(r);
+    const w = waiverFor(/** @type {string} */ (r.file), PROOF_FINDING);
+    if (!w.waived) refusals.push(orInvalid(r, PROOF_FINDING, w.invalid));
   }
   return { ok: refusals.length === 0, refusals };
 }
 
+/** The finding severities autopilot may waive (B47); anything else is never delegated. */
+export const DELEGABLE_SEVERITIES = Object.freeze(['warning', 'nit']);
+
+/** Severity order for {@link recordedSeverity}: the worst recorded one wins. */
+const SEVERITY_RANK = Object.freeze({ nit: 0, warning: 1, critical: 2, blocker: 3 });
+
+/**
+ * The severity the block's signed review rows record for one finding of one file (B47): every
+ * `review.triage` and `review.late_finding` row with that `block`, `file` and `finding`; the worst
+ * one wins. Fails closed: no row ⇒ `not-recorded`; any such row whose MAC does not verify ⇒
+ * `unverified`; a severity outside critical/blocker/warning/nit ⇒ `unknown` — each with
+ * `severity: null`.
+ * @param {Array<Record<string, any>>} rows - rows of ONE run (other runs filtered out by the caller).
+ * @param {{block: string, file: string, finding: string, key: Buffer}} where
+ * @returns {{severity: string, why: null} | {severity: null, why: 'not-recorded' | 'unverified' | 'unknown'}}
+ */
+export function recordedSeverity(rows, { block, file, finding, key }) {
+  const named = rows.filter((r) => (r?.event === 'review.triage' || r?.event === 'review.late_finding') && r.block === block && r.file === file && r.finding === finding);
+  if (named.length === 0) return { severity: null, why: 'not-recorded' };
+  if (named.some((r) => !verified(r, key))) return { severity: null, why: 'unverified' };
+  /** @type {Record<string, number>} */
+  const rank = SEVERITY_RANK;
+  let worst = '';
+  for (const r of named) {
+    if (typeof r.severity !== 'string' || !Object.hasOwn(rank, r.severity)) return { severity: null, why: 'unknown' };
+    if (worst === '' || rank[r.severity] > rank[worst]) worst = r.severity;
+  }
+  return { severity: worst, why: null };
+}
+
+/**
+ * Why a `review.waived {by: autopilot}` row does NOT clear its finding, or null when it does (the
+ * rules are in the module doc). `blockRows`: the block's rows of this run (the review rows the
+ * severity is read from); `runRows`: every row of this run (grant, stop and expire rows carry no
+ * block); `allRows`: every row given (stop and expire rows are matched by grant id across all of
+ * them, whatever their `run`). A stop or expire row counts whether or not it is signed (fail closed).
+ * @param {Record<string, any>} waiver
+ * @param {{blockRows: Array<Record<string, any>>, runRows: Array<Record<string, any>>, allRows?: Array<Record<string, any>>, key: Buffer}} ctx
+ * @returns {string | null}
+ */
+export function autopilotWaiverProblem(waiver, { blockRows, runRows, allRows = runRows, key }) {
+  if (!verified(waiver, key)) return 'the waiver has no valid MAC';
+  if (waiver.finding === PROOF_FINDING) return 'proof is never delegated';
+  const recorded = recordedSeverity(blockRows, { block: waiver.block, file: waiver.file, finding: waiver.finding, key });
+  if (recorded.severity === null) return `the finding's severity is ${recorded.why}; critical findings are never delegated`;
+  if (!DELEGABLE_SEVERITIES.includes(recorded.severity)) return `the finding is ${recorded.severity}; critical findings are never delegated`;
+  if (waiver.severity !== recorded.severity) return `the waiver says ${String(waiver.severity)} but the finding is recorded as ${recorded.severity}`;
+  const at = typeof waiver.ts === 'string' ? Date.parse(waiver.ts) : Number.NaN;
+  if (!Number.isFinite(at)) return 'the waiver has no time';
+  const scope = `waive:${recorded.severity}`;
+  return (
+    grantCoverProblem(runRows, { grantId: waiver.grant_id, scope, at, key, what: 'the waiver', endRows: allRows }) ??
+    decisionProblem(runRows, { decisionId: waiver.decision_id, grantId: waiver.grant_id, scope, subject: { block: waiver.block, file: waiver.file, finding: waiver.finding }, decision: 'waive', at, key })
+  );
+}
+
+/** A delegate decision allows an action for at most this long after it was made (B47). */
+export const DECISION_MAX_AGE_MS = 30 * 60 * 1000;
+
+/**
+ * Why grant `grantId` did NOT cover `scope` at time `at` (epoch ms), or null when it did (B47;
+ * shared by the waiver check and the fix loop's extra rounds): a signed `autopilot.grant` row of
+ * the run with that id, whose window (`ts` ≤ at < `until`) holds `at`, whose scopes include the
+ * scope and whose deny list does not, and no `autopilot.stop` / `autopilot.expire` row for it at
+ * or before `at`. A stop or expire row counts whether or not it is signed, and one with a missing
+ * or unparsable `ts` counts as having stopped the grant (fail closed). Stop and expire rows are
+ * looked for in `endRows` (default `runRows`) by grant id alone, whatever their `run`.
+ * @param {Array<Record<string, any>>} runRows - every row of the run.
+ * @param {{grantId: unknown, scope: string, at: number, key: Buffer, what?: string, endRows?: Array<Record<string, any>>}} q - `what` names the action in the message.
+ * @returns {string | null}
+ */
+export function grantCoverProblem(runRows, { grantId, scope, at, key, what = 'the action', endRows = runRows }) {
+  const id = grantId;
+  const grant = runRows.find((r) => r?.event === 'autopilot.grant' && typeof id === 'string' && r.grant_id === id && verified(r, key));
+  if (!grant) return `no signed autopilot.grant row for grant ${String(id)} in this run`;
+  const from = Date.parse(grant.ts);
+  const until = Date.parse(grant.until);
+  if (!(Number.isFinite(from) && Number.isFinite(until) && at >= from && at < until)) return `${what} is outside grant ${id}'s window`;
+  if (!Array.isArray(grant.scopes) || !grant.scopes.includes(scope) || (Array.isArray(grant.deny) && grant.deny.includes(scope))) return `grant ${id} does not allow ${scope}`;
+  const ended = endRows.find((r) => {
+    if ((r?.event !== 'autopilot.stop' && r?.event !== 'autopilot.expire') || r.grant_id !== id) return false;
+    const ts = typeof r.ts === 'string' ? Date.parse(r.ts) : Number.NaN;
+    return !Number.isFinite(ts) || ts <= at;
+  });
+  if (ended) return `grant ${id} was ${ended.event === 'autopilot.stop' ? 'stopped' : 'expired'} before ${what}`;
+  return null;
+}
+
+/**
+ * Why decision `decisionId` does NOT allow the action, or null when it does (B47): a signed
+ * `autopilot.decision` row of the run with that `decision_id`, `acted: true`, the same grant and
+ * scope, the fixed option word the action needs as its `decision` (`waive` for a waiver, `allow`
+ * for an extra round, the level itself — `L0`/`L1`/`L2` — for a coder level; so an acted "fix" or
+ * "deny" never authorises anything), a `subject` naming the same block (and file / finding when
+ * the action has them), made at or before `at` and at most {@link DECISION_MAX_AGE_MS} before it.
+ * @param {Array<Record<string, any>>} runRows
+ * @param {{decisionId: unknown, grantId: unknown, scope: string, subject: {block: string, file?: string, finding?: string}, decision: string, at: number, key: Buffer}} q
+ * @returns {string | null}
+ */
+export function decisionProblem(runRows, { decisionId, grantId, scope, subject, decision, at, key }) {
+  if (typeof decisionId !== 'string' || decisionId.length === 0) return 'no delegate decision named';
+  const row = runRows.find((r) => r?.event === 'autopilot.decision' && r.decision_id === decisionId);
+  if (!row) return `no autopilot.decision row ${decisionId} in this run`;
+  if (!verified(row, key)) return `decision ${decisionId} has no valid MAC`;
+  if (row.acted !== true) return `decision ${decisionId} did not act (it went to the owner)`;
+  if (row.grant_id !== grantId) return `decision ${decisionId} is under another grant`;
+  if (row.scope !== scope) return `decision ${decisionId} is for ${String(row.scope)}, not ${scope}`;
+  if (row.decision !== decision) return `decision ${decisionId} decided ${JSON.stringify(row.decision)}, not ${JSON.stringify(decision)}`;
+  const named = row.subject && typeof row.subject === 'object' ? row.subject : {};
+  for (const k of /** @type {Array<'block' | 'file' | 'finding'>} */ (['block', 'file', 'finding'])) {
+    if (subject[k] !== undefined && named[k] !== subject[k]) return `decision ${decisionId} is about another ${k}`;
+  }
+  const ts = typeof row.ts === 'string' ? Date.parse(row.ts) : Number.NaN;
+  if (!Number.isFinite(ts) || ts > at || at - ts > DECISION_MAX_AGE_MS) return `decision ${decisionId} is older than 30 min (or not yet made)`;
+  return null;
+}
+
 /** The finding id a human waives to clear an `unproven` file: `block waive <id> proof --file <path>`. */
 export const PROOF_FINDING = 'proof';