@codedology/code-forge 0.13.0 → 0.14.0

package/src/cli/block.mjs

@@ -10,8 +10,8 @@
  *   block claim <id> <path> --run <r>
  *   block close <id> --run <r> [--worker-pid <pid>] [--remove-worktree]
  *   block stop <id> --run <r> --reason <text>
- *   block waive <id> <finding-id> --run <r> --file <path> --reason <text>   (human-only, §4.9; asks at a terminal, B80)
- *   block reopen <id> --run <r> --file <path> --reason <text>   (human-only, B72; asks at a terminal, B80)
+ *   block waive <id> <finding-id> --run <r> --file <path> --reason <text> [--yes]   (orchestrator --yes: evidence and a fresh judge)
+ *   block reopen <id> --run <r> --file <path> --reason <text> [--yes]   (B124c: evidence and a fresh judge for the agent path)
  *
  * B64a `--json` (every subcommand): on success stdout is exactly ONE JSON line instead of the
  * text — `{"block", "event", …}` with the facts the text prints (open: level, asked, source,
@@ -172,18 +172,17 @@
  * <from>[ <stop reason>]; by: human)`; `--json`: `{"block", "event": "reopened", "file", "from",
  * "stop_reason", "at_seq", "from_hash", "to_hash", "ticket_cleared", "by"}`.
  *
- * B80 (D1 = a): `block waive` and `block reopen` need the human at a terminal, through the same
+ * B80: without `--yes`, `block waive` and `block reopen` need the human at a terminal, through the same
  * confirm as `--no-require-reviews` (`confirmAtTerminal`). Right after the usage checks and the run
  * record read — before the autopilot expiry checks or anything else is written — stdin or stdout
- * not a TTY prints `block <verb> needs the human at a terminal to confirm; nothing was recorded
- * (there is no --yes)` (exit 2). At a terminal, what the verb would refuse is refused before the
+ * not a TTY prints `humanVerbNoTTY` (exit 2). At a terminal, what the verb would refuse is refused before the
  * question: a `--file` or finding id with a control character or of the wrong form (`usage`, exit
  * 2, `checkFileForm` / `checkFindingId` — the verbs' own checks), an unknown block, for reopen a
  * block that is not open or a file it does not own (`reopen-not-owned`), for waive a file the block
  * does not own (`waive-not-owned`) or a finding id no review row of the block names for the file
  * (`waive-unknown-finding`; `proof` is exempt) — exit 1. A "no" or a cancel prints `block <id>
  * <verb>: cancelled — nothing was recorded` (exit 1); a "yes" runs the verb exactly as before (the
- * same signed row). There is no `--yes` (an unknown flag, exit 2). An active autopilot grant
+ * same signed row). Only `block waive` accepts `--yes` (B124a, evidence and a fresh L3 judge). An active autopilot grant
  * changes nothing here — autopilot waives through its own path (`autopilot waive`, `by:
  * autopilot`). The prompt checks only that stdin and stdout are terminals; a pseudo-terminal
  * passes it, so it does not prove a human. The coder deny-list entries stay.
@@ -209,6 +208,7 @@ import { StateError } from '../state/paths.mjs';
 import { readRun, writeSigned } from '../state/run.mjs';
 import { loadKey, verifyRow } from '../state/signer.mjs';
 import { PROOF_FINDING, blockFileSet, changedFiles, openFindings, ownsAt, resultFilesFor, reviewedFiles, reviewGateCheck, unownedChanges, waiveFinding } from '../review/gate-check.mjs';
+import { agentWaivers, agentWaiversAcked, prepareAckWaivers, prepareUnwaive, waiveAsAgent } from '../review/agent-waiver.mjs';
 import { checkExpiry } from '../autopilot/grant.mjs';
 import { redact, writeSafe } from '../util/redact.mjs';
 import { blockTree, prepareWorktree, removeWorktree, worktreeSettings } from '../proof/worktree.mjs';
@@ -216,10 +216,10 @@ import { DEFAULT_CONFIG_FILENAME, loadProjectConfig } from '../config/load.mjs';
 import { validateConfig } from '../config/validate.mjs';
 import { migrateConfig } from '../config/migrate.mjs';
 import { exec } from '../util/exec.mjs';
-import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
+import { contentHash, gitChildEnv, readRegularFileNoFollow } from '../worker/ticket.mjs';
 import { clearDone, resolveTicket } from '../worker/queue.mjs';
 import { loadState } from '../worker/review-state.mjs';
-import { openBlockEntry, reopenFile } from '../review/reopen.mjs';
+import { agentReopens, openBlockEntry, reopenFile } from '../review/reopen.mjs';
 import { checkFileForm, checkFindingId } from '../review/verb-forms.mjs';
 import { runRootPath } from '../util/tmp.mjs';
 import { missingReviewTickets, parseSentinel } from '../engines/sentinel.mjs';
@@ -227,15 +227,20 @@ import { reportMismatches, reviewedLines } from '../review/reviewed-lines.mjs';
 import { blockEndHook, runBlockEndHook, writeDoneFile } from '../state/block-end.mjs';
 import { blockOpenFindings } from '../review/open-findings.mjs';
 import { hookForbidden, scanTranscript } from '../util/forbidden.mjs';
+import { prepareAcceptHit, writeAcceptedHit } from '../review/accept-hit.mjs';
 
 /**
  * B72: `block reopen` — the file's content is read where the block works (its worktree, else the
  * main tree), its state is read (never moved) from the code-forge home or the run's old temp root,
  * the checks, the done marker's removal and then the signed row are `reopenFile`'s.
- * @param {{runId: string, id: string, file: string, reason: string, record: Record<string, any>, writeRow: (row: Record<string, any>) => Promise<unknown>}} opts
+ * @param {{runId: string, id: string, file: string, reason: string, record: Record<string, any>, writeRow: (row: Record<string, any>) => Promise<unknown>, agent?: boolean, judge?: import('../review/agent-waiver.mjs').WaiverJudge}} opts
  * @returns {Promise<{row: Record<string, any>, cleared: boolean}>}
  */
-async function reopenBlockFile({ runId, id, file, reason, record, writeRow }) {
+async function reopenBlockFile({ runId, id, file, reason, record, writeRow, agent = false, judge }) {
+  if (agent) {
+    if (!reason.trim()) throw new StateError('usage', 'block reopen needs --reason');
+    checkFileForm(file, { normalized: true });
+  }
   // the stable block codes come first, before any tree, config, key or ledger read
   const entry = openBlockEntry(record, runId, id);
   const real = async (/** @type {string} */ p) => realpath(p).catch(() => path.resolve(p));
@@ -271,10 +276,12 @@ async function reopenBlockFile({ runId, id, file, reason, record, writeRow }) {
     key,
     writeRow,
     writeSigned,
+    ...(agent ? { agent: { root: contentRoot, judge } } : {}),
     io: {
       owns: ownsAt(wsPrefix),
       loadState: (where) => loadState({ .../** @type {any} */ (where), runRootDir, contentRoot, migrate: false }),
       contentHash: (f) => contentHash(contentRoot, f),
+      readFile: (f) => readRegularFileNoFollow(contentRoot, f),
       // C11 (synchronous): the cached result of the current content's ticket would repeat the stop
       clearDone: (f) => clearDone({ repoRoot: mainTop, run: runId, block: id, file: f, ...tree }).removed,
     },
@@ -285,11 +292,14 @@ async function reopenBlockFile({ runId, id, file, reason, record, writeRow }) {
 const USAGE =
   'usage: code-forge block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>] [--kind code|docs|contract] [--tests <paths…>]\n' +
   '       code-forge block attempt|rebase <id> --run <r> · block close <id> --run <r> [--transcript <file>] [--report <file>] [--no-require-reviews] [--remove-worktree] · block claim <id> <path> --run <r> · block stop <id> --run <r> --reason <text>\n' +
-  '       code-forge block waive <id> <finding-id> --run <r> --file <path> --reason <text>\n' +
-  '       code-forge block reopen <id> --run <r> --file <path> --reason <text>\n' +
+  '       code-forge block waive <id> <finding-id> --run <r> --file <path> --reason <text> [--yes]\n' +
+  '       code-forge block reopen <id> --run <r> --file <path> --reason <text> [--yes]\n' +
+  '       code-forge block accept-hit <id> --run <r> --rule <rule-id> --line <n> --transcript <path> --reason <text>\n' +
+  '       code-forge block unwaive <id> <finding-id> --run <r> --file <path> --reason <text>\n' +
+  '       code-forge block ack-waivers <id> --run <r>\n' +
   '       every block verb takes --json: one JSON line on stdout ({"block","event",…}) instead of the text\n';
 
-const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive', 'reopen'];
+const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive', 'reopen', 'accept-hit', 'unwaive', 'ack-waivers'];
 
 /** Refuse likely shell quoting slips before any row is written.
  * @param {string} workspace @param {string[]} entries @param {string} label
@@ -308,7 +318,7 @@ function checkWhitespacePaths(workspace, entries, label) {
     }
   }
 }
-const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript', 'kind', 'report'];
+const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript', 'kind', 'report', 'rule', 'line'];
 
 /**
  * @param {string[]} args
@@ -318,6 +328,8 @@ const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', '
  *   ui?: {confirm: (o: {message: string, initialValue?: boolean}) => Promise<unknown>, isCancel: (v: unknown) => boolean},
  *   removeBlockTree?: typeof removeBlockTree,
  *   resolveTicket?: typeof resolveTicket, reviewedLines?: typeof reviewedLines,
+ *   waiverJudge?: import('../review/agent-waiver.mjs').WaiverJudge,
+ *   extraTokens?: string[],
  * }} [deps] - `now` (B48): the clock of the autopilot expiry checks. `stdinIsTTY` / `stdoutIsTTY`
  *   (default `process.stdin.isTTY` / `process.stdout.isTTY`; `isTTY` sets both) and `ui` (default
  *   `@clack/prompts`): the human's confirmation (B52 `--no-require-reviews`, B80 `block waive` and
@@ -328,7 +340,7 @@ const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', '
  * @returns {Promise<number>}
  */
 export async function runBlock(args, deps = {}) {
-  const { stdout = process.stdout, stderr = process.stderr, probe } = deps;
+  const { stdout = process.stdout, stderr = process.stderr, probe, extraTokens = [] } = deps;
   const out = (/** @type {string} */ s) => writeSafe(stdout, s);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
   const [sub, ...rest] = args;
@@ -337,7 +349,7 @@ export async function runBlock(args, deps = {}) {
     return 2;
   }
   try {
-    const { flags, positionals } = parseFlags(rest, { values: FLAG_VALUES, multi: ['owned', 'tests'], booleans: ['no-require-reviews', 'remove-worktree', 'json'] });
+    const { flags, positionals } = parseFlags(rest, { values: FLAG_VALUES, multi: ['owned', 'tests'], booleans: ['no-require-reviews', 'remove-worktree', 'json', ...(['waive', 'reopen'].includes(sub) ? ['yes'] : [])] });
     // B64a: --json prints ONE JSON line on success instead of the text lines (`emit`, one object
     // per verb, built where the text is); without it every output is exactly as before (`say` is `out`)
     const json = flags.json === true;
@@ -364,14 +376,39 @@ export async function runBlock(args, deps = {}) {
     if (sub === 'reopen' && positionals.length !== 1) throw new StateError('usage', 'block reopen takes one block id (the file goes in --file)');
     if (sub === 'reopen' && typeof flags.file !== 'string') throw new StateError('usage', 'block reopen needs --file <path>');
     if (sub === 'waive' && typeof flags.file !== 'string') throw new StateError('usage', 'block waive needs --file <path> (a finding id is scoped to one file)');
+    if (sub === 'accept-hit') {
+      const { record, row } = await prepareAcceptHit({ runId, id, flags, positionals, extraTokens });
+      const asked = await confirmHumanVerb(sub, runId, id, { rule: row.rule, line: row.line, file: /** @type {string} */ (flags.transcript) }, record, deps);
+      if (asked === 'no-tty') { err(`${humanVerbNoTTY(sub)}\n`); return 2; }
+      if (asked === 'cancelled') { err(`block ${id} ${sub}: cancelled — nothing was recorded\n`); return 1; }
+      await writeAcceptedHit({ runId, row, writeRow: (signed) => appendRow(signed, { slug: record.project }) });
+      say(`block ${id} accepted ${row.rule} transcript line ${row.line} (by: human)\n`);
+      if (json) emit({ block: id, event: 'rule_break.accepted', rule: row.rule, line: row.line, reason: row.reason, by: 'human' });
+      return 0;
+    }
     const record = await readRun(runId);
+    if (sub === 'unwaive' || sub === 'ack-waivers') {
+      if (positionals.length !== (sub === 'unwaive' ? 2 : 1)) throw new StateError('usage', `block ${sub} takes ${sub === 'unwaive' ? 'one block id and one finding id' : 'one block id'}`);
+      const prepared = sub === 'unwaive'
+        ? { counted: [], row: await prepareUnwaive({ runId, id, finding: extra, file: /** @type {string} */ (flags.file), reason: /** @type {string} */ (flags.reason), record }) }
+        : await prepareAckWaivers(record, runId, id);
+      const asked = await confirmHumanVerb(sub, runId, id, { finding: extra, file: /** @type {string} */ (flags.file) }, record, deps, () => {
+        for (const w of prepared.counted) (json ? err : say)(`block ${id}: agent waiver ${w.file} ${w.finding} reason: ${w.reason}; verdict: ${w.verdict}\n`);
+      });
+      if (asked === 'no-tty') { err(`${humanVerbNoTTY(sub)}\n`); return 2; }
+      if (asked === 'cancelled') { err(`block ${id} ${sub}: cancelled — nothing was recorded\n`); return 1; }
+      await writeSigned(runId, (row) => appendRow(row, { slug: record.project }), prepared.row);
+      say(sub === 'unwaive' ? `block ${id} unwaived ${extra} in ${flags.file} (by: human)\n` : `block ${id} acknowledged ${prepared.counted.length} agent waiver(s) (by: human)\n`);
+      if (json) emit(prepared.row);
+      return 0;
+    }
     if (sub === 'open') {
       checkWhitespacePaths(record.workspace, /** @type {string[]} */ (flags.owned), 'owned files');
       if (Array.isArray(flags.tests)) checkWhitespacePaths(record.workspace, flags.tests, 'test files');
     }
     // B80: waive and reopen are the human's — asked at a terminal before anything is written (not
     // even the autopilot expiry rows below); no terminal is exit 2, a "no" is exit 1
-    if (sub === 'waive' || sub === 'reopen') {
+    if ((sub === 'waive' || sub === 'reopen') && flags.yes !== true) {
       const asked = await confirmHumanVerb(sub, runId, id, { finding: extra, file: /** @type {string} */ (flags.file) }, record, deps);
       if (asked === 'no-tty') {
         err(`${humanVerbNoTTY(sub)}\n`);
@@ -383,6 +420,22 @@ export async function runBlock(args, deps = {}) {
       }
     }
     const writeRow =(/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
+    const reopened = async (/** @type {boolean} */ agent) => {
+      const file = /** @type {string} */ (flags.file);
+      const { row, cleared } = await reopenBlockFile({ runId, id, file, reason: /** @type {string} */ (flags.reason), record, writeRow, agent, judge: deps.waiverJudge });
+      const fromText = row.stop_reason == null ? row.from : `${row.from} ${row.stop_reason}`;
+      say(`block ${id} reopened ${file} (from ${fromText}; by: ${row.by})\n`);
+      if (json) emit({ block: id, event: 'reopened', file, from: row.from, stop_reason: row.stop_reason, at_seq: row.at_seq, from_hash: row.from_hash, to_hash: row.to_hash, ticket_cleared: cleared, by: row.by });
+      return 0;
+    };
+    // Agent refusals precede even the lazy expiry checks: no rows on refusal.
+    if (sub === 'reopen' && flags.yes === true) return await reopened(true);
+    if (sub === 'waive' && flags.yes === true) {
+      await waiveAsAgent({ runId, id, finding: extra, file: /** @type {string} */ (flags.file), reason: /** @type {string} */ (flags.reason), record, writeRow, judge: deps.waiverJudge });
+      say(`block ${id} waived ${extra} in ${flags.file} (by: agent)\n`);
+      if (json) emit({ block: id, event: 'waived', finding: extra, file: flags.file, by: 'agent' });
+      return 0;
+    }
     // B64b: the block-end signal — after an end's rows (and outside the run lock) the done file,
     // then the owner's `hooks.on_block_end` from the run-start snapshot. Without the hook key the
     // done file is the only addition: no row, and every output stays exactly as before.
@@ -534,12 +587,7 @@ export async function runBlock(args, deps = {}) {
       return 0;
     }
     if (sub === 'reopen') {
-      const file = /** @type {string} */ (flags.file);
-      const { row, cleared } = await reopenBlockFile({ runId, id, file, reason: /** @type {string} */ (flags.reason), record, writeRow });
-      const fromText = row.stop_reason == null ? row.from : `${row.from} ${row.stop_reason}`;
-      say(`block ${id} reopened ${file} (from ${fromText}; by: human)\n`);
-      if (json) emit({ block: id, event: 'reopened', file, from: row.from, stop_reason: row.stop_reason, at_seq: row.at_seq, from_hash: row.from_hash, to_hash: row.to_hash, ticket_cleared: cleared, by: 'human' });
-      return 0;
+      return await reopened(false);
     }
     if (sub === 'close') {
       const entry = record.blocks?.[id];
@@ -610,6 +658,8 @@ export async function runBlock(args, deps = {}) {
       const closeRows = external === null ? [] : [{ event: 'gate.reviews_waived', block: id, by: 'config', reviewer: external }];
       /** @type {import('../review/gate-check.mjs').WaivedAll[]} */
       let waivedAll = [];
+      /** @type {import('../review/accept-hit.mjs').AcceptedHit[]} */
+      let acceptedHits = [];
       // B70: a file whose review left only waived findings passes as `reviewed_by_waiver`; its signed
       // `gate.review_waived_all` row joins the close rows (written just before `block.close`, only
       // when the block closes — a refused close writes none)
@@ -660,6 +710,7 @@ export async function runBlock(args, deps = {}) {
           rows,
           key,
           transcript,
+          extraTokens,
           // B52: a change no block of the run owns is refused — `--no-require-reviews` does not lift it
           unowned: scope?.unowned ?? [],
           // B52: an old ledger's review.result rows are judged by their signed result files
@@ -672,7 +723,7 @@ export async function runBlock(args, deps = {}) {
           proofFiles: fileSet,
           highPaths,
         };
-      }, { onWaivedAll });
+      }, { onWaivedAll, onAcceptedHits: (hits) => { acceptedHits = hits; } });
       // B96: `reviewsPassed` comes from the gate's own result, not from the onWaivedAll call. Each
       // extra check runs at most once per close (`closeBlock`'s one loop, src/state/block.mjs:562,
       // and `closeBlock` is called once below), so the gate's one pass is its final one.
@@ -748,6 +799,8 @@ export async function runBlock(args, deps = {}) {
       };
       /** @type {Array<() => Promise<{ok: boolean, reason?: string}>>} */
       const extraChecks = [reviews, report];
+      extraChecks.unshift(async () => agentWaiversAcked(record, rows, id, await loadKey(runId))
+        ? { ok: true } : { ok: false, reason: 'agent-waivers-not-acked' });
       // B63b: `context.require_coder_tests` in the run's config snapshot (never the live config)
       // needs the coder's green test run — waived reviews do not lift it. It runs FIRST: it only
       // reads the report, so a refusal here leaves no row (not even the human waiver row the review
@@ -772,6 +825,8 @@ export async function runBlock(args, deps = {}) {
         });
       }
       const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks, closeRows });
+      const agentRows = agentWaivers(rows, id, await loadKey(runId));
+      const reopenedRows = agentReopens(rows.filter((r) => r.run === runId), id, await loadKey(runId));
       // B64b: the block ended (closed, or stopped by a worker pin event or ledger.tamper) — its rows
       // are written and the run lock released; the done file is written before the tree is removed
       // B96: the tool's reviewed lines of a block that closed (also kept in its done file)
@@ -795,6 +850,9 @@ export async function runBlock(args, deps = {}) {
             if (f.answered?.length) parts.push(`answered ${f.answered.join(', ')}`);
             say(`block ${id}: ${f.file} reviewed_by_waiver (${parts.join('; ')})\n`);
           }
+          for (const w of agentRows) say(`block ${id}: agent waiver ${w.file} ${w.finding} reason: ${w.reason}; verdict: ${w.verdict}\n`);
+          for (const r of reopenedRows) say(`agent reopen ${r.file}: ${r.reason} (verdict: ${r.verdict?.verdict})\n`);
+          for (const hit of acceptedHits) say(`accepted rule_break ${hit.rule} transcript line ${hit.line}: ${hit.reason} (by: human)\n`);
         }
         (result.ok ? say : err)(`block ${id} ${result.status}${result.event ? ` (${result.event})` : ''}${result.reason ? `: ${result.reason}` : ''}\n`);
         // B64a: a refused close also names itself on stdout under --json (its stderr is unchanged)
@@ -810,6 +868,9 @@ export async function runBlock(args, deps = {}) {
           ...(result.ok && waivedAll.length > 0 ? { reviewed_by_waiver: waivedAll.map((f) => ({ file: f.file, content_hash: f.content_hash, status: f.status, findings: f.findings, by: f.by, ...(f.answered?.length ? { answered: f.answered } : {}) })) } : {}),
           // B96: only when the tool gave reviewed lines (a waived or external close is unchanged)
           ...(reviewedJson.length > 0 ? { reviewed: reviewedJson } : {}),
+          ...(agentRows.length > 0 ? { agent_waivers: agentRows } : {}),
+          ...(reopenedRows.length > 0 ? { agent_reopens: reopenedRows } : {}),
+          ...(acceptedHits.length > 0 ? { accepted_hits: acceptedHits } : {}),
         };
         if (!result.ok || !removeTree) {
           if (json && result.ok) emit(closedJson);
@@ -898,9 +959,12 @@ export const NO_REVIEWS_NO_TTY = '--no-require-reviews needs the human at a term
 
 /**
  * B80: the refusal when `block waive` or `block reopen` has no terminal to ask the human at.
- * @param {'waive' | 'reopen'} verb @returns {string}
+ * @param {'waive' | 'reopen' | 'accept-hit' | 'unwaive' | 'ack-waivers'} verb @returns {string}
  */
-export const humanVerbNoTTY = (verb) => `block ${verb} needs the human at a terminal to confirm; nothing was recorded (there is no --yes)`;
+export const humanVerbNoTTY = (verb) => verb === 'waive'
+  ? 'block waive needs the human at a terminal to confirm; nothing was recorded (--yes works only for a recorded warning or nit finding, with evidence)'
+  : verb === 'reopen' ? 'block reopen needs the human at a terminal to confirm; nothing was recorded (--yes works only with evidence and agreement from a fresh judge)'
+  : `block ${verb} needs the human at a terminal to confirm; nothing was recorded (there is no --yes)`;
 
 /**
  * @typedef {{isTTY?: boolean, stdinIsTTY?: boolean, stdoutIsTTY?: boolean, ui?: {confirm: (o: {message: string, initialValue?: boolean}) => Promise<unknown>, isCancel: (v: unknown) => boolean}, now?: () => Date}} ConfirmDeps
@@ -955,18 +1019,26 @@ async function confirmNoReviews(runId, id, deps) {
  * autopilot grant changes nothing (autopilot waives through its own path, `by: autopilot`). The
  * pre-checks (`reopenPrecheck`, `waivePrecheck`) run first, at a terminal, so the human is never
  * asked about a waive or reopen the verb would refuse that way.
- * @param {'waive' | 'reopen'} verb @param {string} runId @param {string} id
- * @param {{finding?: string, file: string}} what @param {Record<string, any>} record @param {ConfirmDeps} deps
+ * @param {'waive' | 'reopen' | 'accept-hit' | 'unwaive' | 'ack-waivers'} verb @param {string} runId @param {string} id
+ * @param {{finding?: string, file: string, rule?: string, line?: number}} what @param {Record<string, any>} record @param {ConfirmDeps} deps
+ * @param {() => void} [before]
  * @returns {Promise<'no-tty' | 'confirmed' | 'cancelled'>}
  */
-function confirmHumanVerb(verb, runId, id, what, record, deps) {
+function confirmHumanVerb(verb, runId, id, what, record, deps, before) {
   const message =
     verb === 'waive'
       ? `Waive finding ${what.finding} in ${what.file} of block ${id} (run ${runId})? Only the owner may say yes.`
-      : `Reopen the review of ${what.file} in block ${id} (run ${runId})? Only the owner may say yes.`;
+      : verb === 'unwaive'
+        ? `Undo agent waivers for finding ${what.finding} in ${what.file} of block ${id} (run ${runId})? Only the owner may say yes.`
+      : verb === 'ack-waivers'
+        ? `Acknowledge the listed agent waivers of block ${id} (run ${runId})? Only the owner may say yes.`
+      : verb === 'accept-hit'
+        ? `Accept false transcript hit ${what.rule} at line ${what.line} in ${what.file} of block ${id} (run ${runId})? Only the owner may say yes.`
+        : `Reopen the review of ${what.file} in block ${id} (run ${runId})? Only the owner may say yes.`;
   return confirmAtTerminal(deps, message, async () => {
     if (verb === 'reopen') await reopenPrecheck(record, runId, id, what.file);
-    else await waivePrecheck(record, runId, id, /** @type {string} */ (what.finding), what.file);
+    else if (verb === 'waive') await waivePrecheck(record, runId, id, /** @type {string} */ (what.finding), what.file);
+    before?.();
   });
 }
 

package/src/cli/report.mjs

@@ -1,6 +1,6 @@
 /**
  * `code-forge report [--slug <slug>] [--json] [--export <dir>]` (plan §6.2, R4). Terminal output
- * only, plus an optional `--export <dir>` that writes the same 14 sections as JSON files. The
+ * only, plus an optional `--export <dir>` that writes the same 15 sections as JSON files. The
  * terminal output ends with the spend per run (B33) and the mode of each run (B59: brief or plan);
  * both are text only, never in `--json` or `--export`. The 14th section, `outside_review` (B66), is
  * printed as text lines under its header (`outside review: none`, or one line per PR).
@@ -75,7 +75,7 @@ export async function runReport(args, deps = {}) {
 }
 
 /**
- * B33: the running spend per run (open blocks included), after the 14 sections. Unknown-price
+ * B33: the running spend per run (open blocks included), after the 15 sections. Unknown-price
  * sessions are named, never priced.
  * @param {ReturnType<typeof buildSpend>} spend @returns {string}
  */

package/src/cli/review-file.mjs

@@ -163,21 +163,15 @@ const FRESH_ATTEMPTS = 3;
 /** B75: the ways out a counted result names (human-only; a coder stops and reports). */
 export const FRESH_EXITS = Object.freeze(['block reopen', 'block waive']);
 
+/** The automatic retry allow-list excludes refused results, even those --fresh can rerun. */
+const RETRY_STATUSES = new Set(['stale', 'unavailable', 'split_required']);
+
 /**
- * B75: `review-file <path> --block <id> --fresh`. No done marker: a normal enqueue. The marker is
- * read and classified IN PLACE; only a cached result that never counted is then claimed by
- * `dropDoneIf` (rename, then a byte compare with what was classified) and the ticket queued again.
- * A marker that changed under the claim is restored (link only) and classified again, at most
- * {@link FRESH_ATTEMPTS} times. The queue has no lock: the rename claim is the exclusion, and a
- * crash between the drop and the enqueue leaves only a re-runnable pending ticket. Anything else is refused and the marker kept byte-for-byte:
- * `fresh-needs-reopen` (names `block reopen` and `block waive`) or `fresh-tampered` (names only
- * the owner's `block close --no-require-reviews`; reopen refuses a tampered state).
- * B110: a plain cached round-1 `split_required` uses the same claim, with `retry: true`.
- * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf, retry?: boolean}} opts
- * @returns {number} the exit code.
+ * Classify in place and use the same byte-checked claim for fresh and automatic retries.
+ * @param {{repoRoot: string, ticket: string, file: string, dropDone?: typeof dropDoneIf, once?: boolean, statuses?: Set<string>}} opts
+ * @returns {{verdict: 'rerun' | 'tampered' | 'counted', outcome: 'dropped' | 'gone' | 'kept'}}
  */
-function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf, retry = false }) {
-  const { ticket } = resolveTicket({ repoRoot, run, block, file, tree: where.tree ?? null });
+function dropFreshDone({ repoRoot, ticket, file, dropDone = dropDoneIf, once = false, statuses }) {
   const markerPath = path.join(queueDir(repoRoot), `${ticket}.done`);
   /** @type {'rerun' | 'tampered' | 'counted'} */
   let verdict = 'counted';
@@ -191,18 +185,17 @@ function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDo
       // no marker: a normal enqueue; a marker that exists but cannot be read is never dropped
       bytes = /** @type {{code?: unknown}} */ (err)?.code === 'ENOENT' ? null : Buffer.alloc(0);
     }
-    if (bytes === null) {
-      say(enqueue({ repoRoot, run, block, file, ...where }));
-      return 0;
-    }
+    if (bytes === null) return { verdict: 'counted', outcome: 'gone' };
     // classified IN PLACE: a refusal never moves, renames or touches the marker
     const text = bytes.toString('utf8');
-    verdict = freshVerdict(text, resultOfMarker(repoRoot, text));
+    const result = resultOfMarker(repoRoot, text);
+    verdict = freshVerdict(text, result);
+    if (statuses && !statuses.has(result?.status)) verdict = 'counted';
     if (verdict !== 'rerun') break;
     /** @type {unknown} */
     let outcome;
     try {
-      outcome = dropDone(repoRoot, ticket, bytes);
+      outcome = dropDone(repoRoot, ticket, bytes, once ? { once: true } : {});
     } catch (err) {
       // a named refusal passes through; any other throw is named here, never echoed
       if (err instanceof WorkerError) throw err;
@@ -212,10 +205,31 @@ function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDo
       verdict = 'counted';
       continue;
     }
+    if (outcome === 'kept') break;
     // an allow-list of outcomes: anything else is refused and nothing is queued
     if (outcome !== 'dropped' && outcome !== 'gone') throw new WorkerError('fresh-claim-unknown', `the claim of the cached result of ${file} gave an unknown outcome; nothing was queued`);
-    // dropped: queue it again now (a crash right here leaves a pending ticket with no marker, which
-    // the next review-file queues anyway); gone: another caller took the marker, a normal enqueue
+    return { verdict, outcome };
+  }
+  return { verdict, outcome: 'kept' };
+}
+
+/**
+ * B75: `review-file <path> --block <id> --fresh`. No done marker: a normal enqueue. The marker is
+ * read and classified IN PLACE; only a cached result that never counted is then claimed by
+ * `dropDoneIf` (rename, then a byte compare with what was classified) and the ticket queued again.
+ * A marker that changed under the claim is restored (link only) and classified again, at most
+ * {@link FRESH_ATTEMPTS} times. The queue has no lock: the rename claim is the exclusion, and a
+ * crash between the drop and the enqueue leaves only a re-runnable pending ticket. Anything else is refused and the marker kept byte-for-byte:
+ * `fresh-needs-reopen` (names `block reopen` and `block waive`) or `fresh-tampered` (names only
+ * the owner's `block close --no-require-reviews`; reopen refuses a tampered state).
+ * B110: a plain cached round-1 `split_required` uses the same claim, with `retry: true`.
+ * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf, retry?: boolean}} opts
+ * @returns {number} the exit code.
+ */
+function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf, retry = false }) {
+  const { ticket } = resolveTicket({ repoRoot, run, block, file, tree: where.tree ?? null });
+  const { verdict, outcome } = dropFreshDone({ repoRoot, ticket, file, dropDone });
+  if (outcome === 'dropped' || outcome === 'gone') {
     const queued = enqueue({ repoRoot, run, block, file, ...where });
     say(outcome === 'dropped' ? { ...queued, ...(retry ? { retry: true } : { fresh: true }) } : queued);
     return 0;
@@ -390,7 +404,7 @@ async function waitBlockScope(repoRoot, cwd, run, block) {
   throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
 }
 
-/** A block wait reads only the marker, never review results or the signing key.
+/** Read a completion marker without the signing key.
  * @param {string} repoRoot @param {string} ticket @returns {Record<string, any> | null}
  */
 function blockTicketMarker(repoRoot, ticket) {
@@ -404,12 +418,12 @@ function blockTicketMarker(repoRoot, ticket) {
 }
 
 /**
- * A block wait reads only completion/delivery markers, never review results or the signing key.
+ * A block wait uses unsigned results only to classify retries; it never reads the signing key.
  * Re-scan current content on every poll. Deliver unseen findings of the newest earlier ticket
  * before rechecking a blind edit; the next join queues the fix. Stopped files stay finished.
- * @param {{repoRoot: string, cwd: string, block: string, run: string, maxMs: number, pollMs: number, say: (obj: Record<string, any>) => unknown}} opts
+ * @param {{repoRoot: string, cwd: string, block: string, run: string, maxMs: number, pollMs: number, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf}} opts
  */
-async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say }) {
+async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say, dropDone = dropDoneIf }) {
   const { entry, tree } = await waitBlockScope(repoRoot, cwd, run, block);
   const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree: realpathSync(tree) };
   const deadline = Date.now() + maxMs;
@@ -441,7 +455,12 @@ async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say }) {
         enqueue(opts);
         present = { ...previous[previous.length - 1], ticket };
       }
-      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : blockTicketMarker(repoRoot, ticket) ? 'done' : 'pending' };
+      let marker = present ? blockTicketMarker(repoRoot, ticket) : null;
+      if (live && marker && RETRY_STATUSES.has(marker.status)) {
+        dropFreshDone({ repoRoot, ticket, file, dropDone, once: true, statuses: RETRY_STATUSES });
+        marker = blockTicketMarker(repoRoot, ticket);
+      }
+      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : marker ? 'done' : 'pending' };
     });
     if (downPolls >= 2) {
       say({ block, files, done: false, status: 'worker_down' });
@@ -478,7 +497,7 @@ export async function runReviewFile(args, deps = {}) {
       if (positionals.length > 0 || flags.block !== undefined || flags.wait !== undefined || flags.answers !== undefined || flags.of !== undefined || flags.fresh === true || typeof flags.run !== 'string') {
         throw new WorkerError('usage', '--wait-block takes a block, --run and --max only');
       }
-      return await waitBlock({ repoRoot, cwd, block: assertBlockId(flags['wait-block']), run: assertRunId(flags.run), maxMs: flags.max === undefined ? DEFAULT_WAIT_MS : parseMax(flags.max), pollMs: deps.pollMs ?? POLL_MS, say });
+      return await waitBlock({ repoRoot, cwd, block: assertBlockId(flags['wait-block']), run: assertRunId(flags.run), maxMs: flags.max === undefined ? DEFAULT_WAIT_MS : parseMax(flags.max), pollMs: deps.pollMs ?? POLL_MS, say, dropDone: deps.dropDone });
     }
 
     if (typeof flags.wait === 'string') {
@@ -524,16 +543,9 @@ export async function runReviewFile(args, deps = {}) {
     const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree };
     if (flags.fresh === true) return freshTicket({ repoRoot, run: worker.run, block, file, where, say, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
     const queued = enqueue({ repoRoot, run: worker.run, block, file, ...where });
-    if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'split_required') {
+    if (queued.status === 'done' && ['unavailable', 'split_required'].includes(doneResult(repoRoot, queued.ticket)?.status)) {
       return freshTicket({ repoRoot, run: worker.run, block, file, where, say, retry: true, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
     }
-    if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'unavailable') {
-      // `unavailable` is never approval AND never final: drop the done marker so the worker runs
-      // the ticket again (the fix loop re-runs its pending round); the signed result is replaced.
-      rmSync(path.join(queueDir(repoRoot), `${queued.ticket}.done`), { force: true });
-      say({ ...enqueue({ repoRoot, run: worker.run, block, file, ...where }), retry: true });
-      return 0;
-    }
     say(queued);
     return 0;
   } catch (err) {

package/src/ledger/export.mjs

@@ -1,5 +1,5 @@
 /**
- * `report --export <dir>` — writes one JSON file per report section (plan §6.2; 14 sections since B66).
+ * `report --export <dir>` — writes one JSON file per report section (plan §6.2; 15 sections since B124b).
  */
 
 import { mkdir, writeFile } from 'node:fs/promises';

package/src/ledger/report.mjs

@@ -1,5 +1,5 @@
 /**
- * `code-forge report` (plan §6.2, R4): builds the 14 report sections from a run's ledger rows.
+ * `code-forge report` (plan §6.2, R4): builds the 15 report sections from a run's ledger rows.
  * Pure data, no I/O — terminal rendering + `--export` live in `src/cli/report.mjs`.
  *
  * Shadow rows (`row.source === 'shadow'`) are excluded everywhere here (plan §6.3: shadow-sampled
@@ -262,8 +262,8 @@ const runStopCounts = (rows) => ({
   noEngineStops: rows.filter((r) => r.event === 'run.stop' && r.reason === 'no_engine').length,
 });
 
-/** The exact, ordered set of section keys `buildReport` produces (plan §6.2; B66 appended the
- * 14th, `outside_review` — append new sections, never reorder) —
+/** The exact, ordered set of section keys `buildReport` produces (plan §6.2; B66 appended
+ * `outside_review`, then B124b appended `agent_waivers` — append new sections, never reorder) —
  * exported so tests (and `--export`) can assert against ONE source of truth instead of a copy. */
 export const SECTION_NAMES = Object.freeze([
   'cost_per_block',
@@ -280,6 +280,7 @@ export const SECTION_NAMES = Object.freeze([
   'blocks_stopped_at_l3',
   'run_stop_counts',
   'outside_review',
+  'agent_waivers',
 ]);
 
 /**
@@ -307,6 +308,11 @@ export function buildReport(rows) {
     // B66: per PR, the outside review rounds next to the cost of its blocks — the SAME
     // `costPerBlock` entries the `cost_per_block` section shows
     outside_review: (/** @type {any[]} */ r) => buildOutsideReview(r, costs),
+    agent_waivers: (/** @type {any[]} */ r) => r.flatMap((row, i) => row.event === 'review.waived' && row.by === 'agent'
+      ? [{ block: row.block, file: row.file, finding: row.finding, severity: row.severity, reason: row.reason, verdict: row.verdict,
+        unwaived: r.slice(i + 1).some((undo) => undo.event === 'review.unwaived' && undo.by === 'human'
+          && undo.run === row.run && undo.block === row.block && undo.file === row.file && undo.finding === row.finding) }]
+      : []),
   };
   /** @type {Record<string, any>} */
   const sections = {};

package/src/review/accept-hit.mjs

@@ -0,0 +1,78 @@
+/** Human acceptance of one false transcript hit, bound to its rule and exact line bytes. */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { StateError } from '../state/paths.mjs';
+import { readRun, writeSigned } from '../state/run.mjs';
+import { verifyRow } from '../state/signer.mjs';
+import { mergeForbidden, scanTranscript } from '../util/forbidden.mjs';
+
+/** @typedef {{rule: string, line: number, reason: string}} AcceptedHit */
+
+/** @param {string} text */
+const lineHash = (text) => createHash('sha256').update(text).digest('hex');
+
+/** One refusal for every well-formed request that does not name an actual hit. */
+function noSuchHit() {
+  return new StateError('accept-hit-no-such-hit', 'accept-hit-no-such-hit: the named transcript hit was not found; nothing was recorded');
+}
+
+/**
+ * Validate forms before reading state, then find the exact pair before the terminal question.
+ * The close and this pre-check use the same merged forbidden list.
+ * @param {{runId: string, id: string, flags: Record<string, any>, positionals: string[], extraTokens?: string[]}} opts
+ */
+export async function prepareAcceptHit({ runId, id, flags, positionals, extraTokens = [] }) {
+  if (positionals.length !== 1) throw new StateError('usage', 'block accept-hit takes one block id');
+  for (const [name, value] of Object.entries({ block: id, run: runId, rule: flags.rule, line: flags.line, transcript: flags.transcript, reason: flags.reason })) {
+    // eslint-disable-next-line no-control-regex
+    if (typeof value === 'string' && /[\x00-\x1f\x7f]/.test(value)) throw new StateError('usage', `${name === 'block' ? 'block id' : `--${name}`} must not contain control characters`);
+  }
+  for (const name of ['rule', 'transcript', 'reason']) {
+    if (typeof flags[name] !== 'string' || flags[name].trim().length === 0) throw new StateError('usage', `--${name} is required`);
+  }
+  if (typeof flags.line !== 'string' || !/^-?\d+$/.test(flags.line) || !Number.isSafeInteger(Number(flags.line))) throw new StateError('usage', '--line must be an integer');
+  const line = Number(flags.line);
+  let record;
+  let text;
+  try {
+    record = await readRun(runId);
+    if (!record.blocks?.[id]) throw noSuchHit();
+    text = await readFile(flags.transcript, 'utf8');
+  } catch {
+    throw noSuchHit();
+  }
+  const lines = text.split('\n');
+  if (line < 1 || line > lines.length || !scanTranscript(text, mergeForbidden(extraTokens)).some((hit) => hit.id === flags.rule && hit.line === line)) throw noSuchHit();
+  return { record, row: { block: id, rule: /** @type {string} */ (flags.rule), line, line_sha256: lineHash(lines[line - 1]), reason: /** @type {string} */ (flags.reason.trim()), by: 'human' } };
+}
+
+/**
+ * Called only after terminal confirmation; exactly one signed row, through the waiver's writer.
+ * @param {{runId: string, row: Record<string, any>, writeRow: (row: Record<string, any>) => Promise<unknown>}} opts
+ */
+export async function writeAcceptedHit({ runId, row, writeRow }) {
+  await writeSigned(runId, writeRow, { event: 'rule_break.accepted', ...row });
+}
+
+/**
+ * Ledger rule_break rows are deliberately outside this transcript-only filter.
+ * Line numbers are for reporting; only rule and exact content bind the acceptance.
+ * @param {{block: string, runId: string, rows: Record<string, any>[], key: Buffer, transcript: string | null, extraTokens?: string[]}} opts
+ * @returns {{remaining: {id: string, line: number}[], accepted: AcceptedHit[]}}
+ */
+export function acceptedTranscriptHits({ block, runId, rows, key, transcript, extraTokens = [] }) {
+  if (typeof transcript !== 'string' || transcript.length === 0) return { remaining: [], accepted: [] };
+  const approvals = rows.filter((row) => row.event === 'rule_break.accepted' && row.run === runId && row.block === block && row.by === 'human' && typeof row.reason === 'string' && row.reason.trim().length > 0 && verifyRow(row, key).ok);
+  const lines = transcript.split('\n');
+  /** @type {{id: string, line: number}[]} */
+  const remaining = [];
+  /** @type {AcceptedHit[]} */
+  const accepted = [];
+  for (const hit of scanTranscript(transcript, mergeForbidden(extraTokens))) {
+    const hash = lineHash(lines[hit.line - 1]);
+    const approval = approvals.find((row) => row.rule === hit.id && row.line_sha256 === hash);
+    if (approval) accepted.push({ rule: hit.id, line: hit.line, reason: approval.reason });
+    else remaining.push(hit);
+  }
+  return { remaining, accepted };
+}