@codedology/code-forge 0.8.0 → 0.9.0

package/skill/templates/coder-brief.md

@@ -15,7 +15,7 @@
 
 ## The file loop
 
-After you finish each file in `owned_files` (tests written and green) run `forge review-file <path> --block <id> --run <r>`; before the next file run `forge review-file --wait <ticket> [--max 90s]` and act on the packet. A `worker_down` answer ⇒ print `===BLOCK <id> FAILED: worker down===` (never approval).
+After you finish each file in `owned_files` (tests written and green) run `forge review-file <path> --block <id> --run <r>`; before the next file run `forge review-file --wait <ticket> [--max 90s]` and act on the packet. A finding whose fix belongs in another owned file (a missing test, say) is fixed there and sent with `forge review-file <that file> --block <id> --run <r> --answers <ids> --of <source>`. A `worker_down` answer ⇒ print `===BLOCK <id> FAILED: worker down===` (never approval).
 
 ## Final report — FAILED unless it lists the ticket ids
 
@@ -42,7 +42,7 @@ Or `===BLOCK <id> FAILED: <reason>===`.
 
 ## Fix-round brief (round ≥ 2, or a respawn after a climb)
 
-The open findings by id, the fix history, the files they sit in. Fix only those hunks, then run `forge review-file <path> --block <id> --run <r>` and `--wait` on **every file the round changed** — a fix the reviewer never saw is not a fix. The final report follows the same rule: one `reviewed <path> ticket <ticket-id>` line per file changed in the round, or the round counts as FAILED. Re-run the block's test command after the fixes and print a fresh `TESTS <command> exit=<n>` line just before the round's sentinel: a TESTS line from an earlier report does not count.
+The open findings by id, the fix history, the files they sit in. Fix only those hunks, then run `forge review-file <path> --block <id> --run <r>` and `--wait` on **every file the round changed** — a fix the reviewer never saw is not a fix. A fix made in another owned file is sent with `--answers <ids> --of <source>` (The file loop). The final report follows the same rule: one `reviewed <path> ticket <ticket-id>` line per file changed in the round, or the round counts as FAILED. Re-run the block's test command after the fixes and print a fresh `TESTS <command> exit=<n>` line just before the round's sentinel: a TESTS line from an earlier report does not count.
 
 ## Context pack
 

package/src/cli/block.mjs

@@ -1,5 +1,5 @@
 /**
- * `code-forge block open|attempt|rebase|claim|close|stop` (plan §4.9). The skill calls
+ * `code-forge block open|attempt|rebase|claim|close|stop|waive|reopen` (plan §4.9). The skill calls
  * `block open` before every spawn in every engine; it prints the brief pointer (≤ 200 bytes).
  *
  *   block open <id> --run <r> [--level L<n>] --owned <paths…> --acceptance <file>
@@ -11,6 +11,7 @@
  *   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)
+ *   block reopen <id> --run <r> --file <path> --reason <text>   (human-only, B72)
  *
  * 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,
@@ -77,6 +78,19 @@
  * else still refuses — `unowned_change`, `unproven`, `no_changes`, the transcript grep and
  * `closeBlock`'s own rows. With `--no-require-reviews` the human path runs exactly as without the key.
  *
+ * B70 (issue #9 a): a file with no approval for its current hash whose real review (a signed
+ * `review.round` at that hash) left findings that are all waived — `block waive`, or an autopilot
+ * waiver its grant covered for a non-critical — passes as `reviewed_by_waiver`, never approved
+ * (`checkBlockReviews`). When the block closes, one signed `gate.review_waived_all {file,
+ * content_hash, findings, by}` row per such file is written just before `block.close` (after any
+ * other close row); a refused close writes none. The close prints `block <id>: <file>
+ * reviewed_by_waiver (<ids>; by <who>)` before the closed line, and `--json` adds
+ * `reviewed_by_waiver: [{file, content_hash, status, findings, by}]` (only when there is one).
+ * B71: a finding a signed `review.answered` row clears (another owned file resolved it, judged by
+ * a reviewer) counts like a waived one, listed under `answered` next to `findings` in the close
+ * row and the `--json` entry; the line then reads `(<ids>; by <who>; answered <ids>)`, or
+ * `(answered <ids>)` when nothing was waived (`by` is then null).
+ *
  * B63b: `context.require_coder_tests: true` in the run's config snapshot (immutable like
  * `review.external`; the live config is never read for it) adds one check after the report check:
  * `--report` must be given and readable, its last sentinel for the block must be COMPLETE, and a
@@ -128,6 +142,20 @@
  * before anything is asked or written. The ledger, the signed result files and the high paths stay
  * in the main tree. Nothing is checked out, pushed or merged.
  *
+ * B72 (issues #12, #15): `block reopen <id> --run <r> --file <path> --reason <text>` is the
+ * human's restart of a file whose review STOPPED or whose state is LOST (`review/reopen.mjs`):
+ * coder-forbidden like `block waive`. The done marker of the current content's ticket is removed
+ * (the ticket of the block's worktree when it has one), then one signed `review.reopened {block,
+ * file, from, stop_reason, at_seq, from_hash, to_hash, reason, by: human}` row is written, so the
+ * next `review-file` runs a full round 1. Refused (exit 1, no row): `unknown_block` and
+ * `reopen-block-not-open` (checked before anything is read), a `worktree-*` code (the block's tree
+ * cannot be read), `reopen-config` (the run's config snapshot or `tmp.root` cannot be read),
+ * `reopen-not-owned`, `reopen-tampered`, `reopen-not-stopped`, `reopen-same-content`,
+ * `reopen-already-recorded`, `reopen-write-failed`; a missing `--file` or `--reason` is a usage
+ * error (exit 2). It prints `block <id> reopened <file> (from
+ * <from>[ <stop reason>]; by: human)`; `--json`: `{"block", "event": "reopened", "file", "from",
+ * "stop_reason", "at_seq", "from_hash", "to_hash", "ticket_cleared", "by"}`.
+ *
  * `--acceptance` is a YAML/JSON list of `{clause, tests: [test ids…]}`. `block close` runs B8's
  * rows of the gate (worker pin, MACs, orphans); the gate rows owned by later blocks join it
  * through `closeBlock`'s `extraChecks`.
@@ -154,19 +182,78 @@ 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 { gitChildEnv } from '../worker/ticket.mjs';
+import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
+import { clearDone } from '../worker/queue.mjs';
+import { loadState } from '../worker/review-state.mjs';
+import { openBlockEntry, reopenFile } from '../review/reopen.mjs';
+import { runRootPath } from '../util/tmp.mjs';
 import { missingReviewTickets, parseSentinel } from '../engines/sentinel.mjs';
 import { blockEndHook, runBlockEndHook, writeDoneFile } from '../state/block-end.mjs';
 import { blockOpenFindings } from '../review/open-findings.mjs';
 import { hookForbidden, scanTranscript } from '../util/forbidden.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
+ * @returns {Promise<{row: Record<string, any>, cleared: boolean}>}
+ */
+async function reopenBlockFile({ runId, id, file, reason, record, writeRow }) {
+  // 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));
+  const mainTop = await real(await repoTop(record.workspace));
+  const wt = await blockTree(record.workspace, entry).catch((thrown) => {
+    if (typeof thrown?.code === 'string' && thrown.code.startsWith('worktree-')) throw new StateError(thrown.code, `block ${id}: ${thrown.message}, so the file's content cannot be read; nothing was recorded`);
+    throw thrown;
+  });
+  const contentRoot = wt === null ? mainTop : wt.top;
+  const wsPrefix = path.relative(mainTop, await real(record.workspace)).split(path.sep).join('/');
+  // the state is read where the worker keeps it: an unreadable snapshot or tmp.root is refused,
+  // never guessed (a wrong root would read as "no state"); only an absent tmp.root (undefined or
+  // null) means the default root, any other non-string is refused (B79)
+  /** @type {string} */
+  let runRootDir;
+  try {
+    const root = configInForce(record)?.tmp?.root;
+    if (root !== undefined && root !== null && typeof root !== 'string') throw new TypeError('tmp.root is not a string');
+    runRootDir = runRootPath(runId, typeof root === 'string' ? { root } : {});
+  } catch {
+    throw new StateError('reopen-config', `reopen-config: the run's config snapshot or its tmp.root cannot be read, so the review state of ${file} cannot be found; nothing was recorded`);
+  }
+  const key = await loadKey(runId);
+  const rows = await readAllRows(record.project);
+  const tree = contentRoot === mainTop ? {} : { tree: contentRoot };
+  const { row, cleared } = await reopenFile({
+    runId,
+    id,
+    file,
+    reason,
+    record,
+    rows,
+    key,
+    writeRow,
+    writeSigned,
+    io: {
+      owns: ownsAt(wsPrefix),
+      loadState: (where) => loadState({ .../** @type {any} */ (where), runRootDir, contentRoot, migrate: false }),
+      contentHash: (f) => contentHash(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,
+    },
+  });
+  return { row, cleared };
+}
+
 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' +
   '       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'];
+const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive', 'reopen'];
 const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript', 'kind', 'report'];
 
 /**
@@ -214,8 +301,10 @@ export async function runBlock(args, deps = {}) {
     }
     if (sub !== 'close' && flags['remove-worktree'] === true) throw new StateError('usage', '--remove-worktree is a block close flag');
     if (sub === 'claim' && (!extra || positionals.length !== 2)) throw new StateError('usage', 'block claim needs exactly one path');
-    if ((sub === 'stop' || sub === 'waive') && typeof flags.reason !== 'string') throw new StateError('usage', `block ${sub} needs --reason`);
+    if ((sub === 'stop' || sub === 'waive' || sub === 'reopen') && typeof flags.reason !== 'string') throw new StateError('usage', `block ${sub} needs --reason`);
     if (sub === 'waive' && (!extra || positionals.length !== 2)) throw new StateError('usage', 'block waive needs exactly one finding id');
+    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)');
     const record = await readRun(runId);
     const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
@@ -367,6 +456,14 @@ export async function runBlock(args, deps = {}) {
       if (json) emit({ block: id, event: 'waived', finding: extra, file: flags.file, by: 'human' });
       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;
+    }
     if (sub === 'close') {
       const entry = record.blocks?.[id];
       if (!entry) throw new StateError('unknown_block', `block ${id} is not in run ${runId}`);
@@ -430,6 +527,22 @@ export async function runBlock(args, deps = {}) {
           const fileSet = await blockFileSet({ repoRoot: top, base, owned: entry.owned_files, matchOwned: isMine, changed: [...new Set([...changed, ...reviewed])].sort() });
           return { top, mainTop, where, inTree, wsPrefix, owns, changed, fileSet, reviewed };
         })());
+      // B58: the config waiver row is written by `closeBlock` under the run lock, just before
+      // `block.close` and only when every other check passed — never by a refused close
+      /** @type {Record<string, any>[]} */
+      const closeRows = external === null ? [] : [{ event: 'gate.reviews_waived', block: id, by: 'config', reviewer: external }];
+      /** @type {import('../review/gate-check.mjs').WaivedAll[]} */
+      let waivedAll = [];
+      // 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)
+      const onWaivedAll = (/** @type {import('../review/gate-check.mjs').WaivedAll[]} */ files) => {
+        // idempotent: the waived rows are rebuilt from the final list, never appended per call
+        // (closeBlock reads closeRows only after every extra check passed)
+        waivedAll = files;
+        const others = closeRows.filter((r) => r.event !== 'gate.review_waived_all');
+        closeRows.splice(0, closeRows.length, ...others, ...files.map((f) => ({ event: 'gate.review_waived_all', block: id, file: f.file, content_hash: f.content_hash, findings: f.findings, by: f.by, ...(f.answered?.length ? { answered: f.answered } : {}) })));
+      };
       const reviews = reviewGateCheck(async () => {
         const transcript = await findTranscript(record, id, typeof flags.transcript === 'string' ? flags.transcript : null);
         if (transcript === null) {
@@ -479,7 +592,7 @@ export async function runBlock(args, deps = {}) {
           proofFiles: fileSet,
           highPaths,
         };
-      });
+      }, { onWaivedAll });
       // B36: the coder's report names a review-file ticket for every changed file, or it is FAILED
       const report = async () => {
         if (typeof flags.report !== 'string' || reviewsWaived || external !== null) return { ok: true };
@@ -493,10 +606,6 @@ export async function runBlock(args, deps = {}) {
         const missing = missingReviewTickets(text, fileSet.map((f) => f.file));
         return missing.length === 0 ? { ok: true } : { ok: false, reason: `coder report FAILED: no review-file ticket id for ${missing.join(', ')}` };
       };
-      // B58: the config waiver row is written by `closeBlock` under the run lock, just before
-      // `block.close` and only when every other check passed — never by a refused close
-      /** @type {Record<string, any>[]} */
-      const closeRows = external === null ? [] : [{ event: 'gate.reviews_waived', block: id, by: 'config', reviewer: external }];
       /** @type {Array<() => Promise<{ok: boolean, reason?: string}>>} */
       const extraChecks = [reviews, report];
       // B63b: `context.require_coder_tests` in the run's config snapshot (never the live config)
@@ -530,10 +639,28 @@ export async function runBlock(args, deps = {}) {
       // does — also when a later step (the output, `--remove-worktree`) throws; it never changes
       // the exit code or stdout (`runHook` never throws)
       try {
+        // B70: each file that passed as reviewed_by_waiver is named before the closed line
+        // B71: an answered finding is named as answered; a file with only answered findings has no `by`
+        if (result.ok) {
+          for (const f of waivedAll) {
+            const parts = f.findings.length > 0 ? [`${f.findings.join(', ')}; by ${f.by}`] : [];
+            if (f.answered?.length) parts.push(`answered ${f.answered.join(', ')}`);
+            say(`block ${id}: ${f.file} reviewed_by_waiver (${parts.join('; ')})\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)
         if (json && !result.ok) emit({ block: id, ok: false, reason: result.reason ?? null, ...(end?.json ?? {}) });
-        const closedJson = { block: id, event: result.status, status: result.status, reason: result.reason ?? null, close_event: result.event ?? null, ...(end?.json ?? {}) };
+        const closedJson = {
+          block: id,
+          event: result.status,
+          status: result.status,
+          reason: result.reason ?? null,
+          close_event: result.event ?? null,
+          ...(end?.json ?? {}),
+          // B70: only when a file passed as reviewed_by_waiver (otherwise the output is unchanged)
+          ...(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 } : {}) })) } : {}),
+        };
         if (!result.ok || !removeTree) {
           if (json && result.ok) emit(closedJson);
           return result.ok ? 0 : 1;

package/src/cli/review-file.mjs

@@ -5,12 +5,17 @@
  *   review-file --wait <ticket> [--max <90s>]      poll; prints {ticket, status: done, result} or
  *                                                  {ticket, status: pending, reason: wait_timeout}
  *                                                  when --max elapses (the review is still running)
+ *   review-file <answering file> --block <id> --answers <ids> --of <source> [--run <id>]
+ *                                                  B71: enqueue an answers ticket; prints {ticket,
+ *                                                  status, kind: answers, file: source, by_file, answers}
+ *   review-file <path> --block <id> --fresh        B75: re-run a cached result that never counted
  *
  * The same content enqueued again after an `unavailable` result is a fresh attempt (`retry: true`),
  * not the old result.
  * A done result that is not approved and carries open findings adds `fix_list` (what the coder
  * fixes before re-running `review-file <path>`, which is then a round-2 recheck of the fix hunks,
- * §4.11); a result the loop stopped adds `stop` with the reason (`review_cap`, …) — the coder
+ * §4.11); a result the loop stopped adds `stop` with the reason (`review_cap`, …) and (B73)
+ * `exits: ["block reopen", "block waive", "review-file --answers", "re-decompose"]` — the coder
  * stops and reports; only the orchestrator and the human act on it. A `split_required` result
  * (the packet is over `review.budgets.full_in`) adds `stop: split_required` with `tokens_in` and
  * `budget` (always; null when unknown) and a Markdown `section` — never for another result (B54); a Markdown file gets there only when one of its sections alone is too large.
@@ -22,6 +27,15 @@
  * `===BLOCK <id> FAILED: worker down===`. While waiting, `worker_down` needs the worker to look
  * down on two polls in a row, and a worker whose pid is alive with a fresh heartbeat is never down
  * (`liveWorker`, B30). Output is one JSON line on stdout.
+ * B75: `--fresh` drops the cached done marker of the file's current content and queues the ticket
+ * again ONLY when that result never counted as a review: `stale`, `unavailable`, or `refused` with
+ * `other-run`, `context-unreadable` or a `worktree-*` reason (an allow-list, fail closed). Any
+ * other cached result — a round ran (findings, approved, stopped), `review-state-lost`, an answers
+ * result, an unknown status or reason, an unreadable marker — is refused `fresh-needs-reopen`
+ * (exit 1, `exits: [block reopen, block waive]`, the marker kept byte-for-byte); a
+ * `review-state-tampered` one is refused `fresh-tampered` (names only `block close
+ * --no-require-reviews`). No cached result: a normal enqueue. A coder may run it; it never
+ * re-rolls a counted round and writes no ledger row.
  * Exit codes: 0 queued/done/pending, 1 bad-path or another refusal, 2 usage, 3 worker_down.
  *
  * B62b: the queue and the worker are always the MAIN tree's (`mainRootOf`), also when the coder
@@ -35,19 +49,38 @@
  * from, which is the block's tree when the coder works there. A record naming a worktree that is
  * gone or malformed is refused (exit 1, `reason: worktree-missing|worktree-malformed|…`), and
  * nothing is queued.
+ *
+ * B71: `--answers <id,id,…> --of <source>` (1 to 10 finding ids, comma-separated) asks the worker
+ * whether the change in the positional file (the answering file) resolves those open findings of
+ * `<source>`. It is refused before anything is queued — exit 2 `usage` for a missing `--of`, no
+ * ids, more than 10 ids or a malformed id; exit 1 `answers-same-file` when both name one file,
+ * `answers-not-owned` when the run record says the block does not own both, `answers-not-open`
+ * when an id is not open on the source at its current hash (not named by the latest refusal or
+ * cap row there, or already waived or answered; these two pre-checks read what this process can read, unverified, and are skipped when the run
+ * record cannot be opened here). The worker checks all of it again with the signed rows; that check
+ * is the one that counts. Its done result has `status: answers` and the coder-facing `answers:
+ * [{id, verdict: resolved|not_resolved, reason}]` instead of a fix list; a resolved id is a signed
+ * `review.answered` row the close counts until either file changes. The answering file still
+ * needs its own review.
  */
 
 import { readFileSync, realpathSync, rmSync } from 'node:fs';
 import path from 'node:path';
-import { enqueue, isDone, liveWorker, queueDir } from '../worker/queue.mjs';
-import { assertBlockId, assertInsideRoot, assertTicketId, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
+import { answersTicketId, assertAnswers, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
+import { assertBlockId, assertInsideRoot, assertTicketId, contentHash, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
+import { namedOnHash } from '../review/gate-check.mjs';
+import { STOP_EXITS } from '../review/stop-exits.mjs';
+import { ownsFile } from '../state/registry.mjs';
+import { readAllRows } from '../ledger/write.mjs';
 import { parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
 import { readRun } from '../state/run.mjs';
 import { blockTree } from '../proof/worktree.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
-const USAGE = 'usage: code-forge review-file <path> --block <id> [--run <id>] | review-file --wait <ticket> [--max <seconds>s]\n';
+const USAGE =
+  'usage: code-forge review-file <path> --block <id> [--run <id>] [--fresh] | review-file --wait <ticket> [--max <seconds>s]\n' +
+  '       code-forge review-file <answering file> --block <id> --answers <id,id,…> --of <source> [--run <id>]\n';
 
 export const DEFAULT_WAIT_MS = 90_000;
 const POLL_MS = 200;
@@ -69,15 +102,132 @@ export function parseMax(raw) {
  */
 function doneResult(repoRoot, ticket) {
   try {
-    const marker = JSON.parse(readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`), 'utf8'));
-    const rel = typeof marker.result === 'string' ? marker.result : '';
+    return resultOfMarker(repoRoot, readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} repoRoot @param {string} text - a done marker's text
+ * @returns {Record<string, any> | null} the worker's result it names (unverified), or null.
+ */
+function resultOfMarker(repoRoot, text) {
+  try {
+    const marker = JSON.parse(text);
+    const rel = typeof marker?.result === 'string' ? marker.result : '';
     if (!rel.startsWith(`.code-forge${path.sep}reviews${path.sep}`) || rel.split(path.sep).includes('..')) return null;
-    return JSON.parse(readFileSync(path.join(repoRoot, rel), 'utf8'));
+    const result = JSON.parse(readFileSync(path.join(repoRoot, rel), 'utf8'));
+    return result !== null && typeof result === 'object' && !Array.isArray(result) ? result : null;
   } catch {
     return null;
   }
 }
 
+/** B75: the refused reasons that are not a verdict on the content (`--fresh` re-runs them). */
+const FRESH_REFUSED = new Set(['other-run', 'context-unreadable']);
+
+/**
+ * B75: may `--fresh` drop this cached result? An allow-list, fail closed: `rerun` only for a
+ * result that never counted as a review — `stale`, `unavailable`, or `refused` with a reason that
+ * is not a verdict (`other-run`, `context-unreadable`, `worktree-*`) — whose marker names the same
+ * status. `tampered` for `refused review-state-tampered`; `counted` for everything else (a round
+ * ran, `review-state-lost`, an answers result, an unknown status or reason, an unreadable marker or
+ * result).
+ * @param {string} text - the done marker's text @param {Record<string, any> | null} result
+ * @returns {'rerun' | 'tampered' | 'counted'}
+ */
+export function freshVerdict(text, result) {
+  let marker;
+  try {
+    marker = JSON.parse(text);
+  } catch {
+    return 'counted';
+  }
+  if (result === null || marker === null || typeof marker !== 'object' || marker.status !== result.status) return 'counted';
+  if (result.status === 'stale' || result.status === 'unavailable') return 'rerun';
+  if (result.status !== 'refused' || typeof result.reason !== 'string') return 'counted';
+  if (result.reason === 'review-state-tampered') return 'tampered';
+  return FRESH_REFUSED.has(result.reason) || result.reason.startsWith('worktree-') ? 'rerun' : 'counted';
+}
+
+/** B75: how many times --fresh classifies a marker that changed under its claim. */
+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']);
+
+/**
+ * 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).
+ * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf}} opts
+ * @returns {number} the exit code.
+ */
+function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf }) {
+  const { ticket } = resolveTicket({ repoRoot, run, block, file, tree: where.tree ?? null });
+  const markerPath = path.join(queueDir(repoRoot), `${ticket}.done`);
+  /** @type {'rerun' | 'tampered' | 'counted'} */
+  let verdict = 'counted';
+  // a marker that changed under the claim is classified again; bounded, then refused (fail closed)
+  for (let attempt = 0; attempt < FRESH_ATTEMPTS; attempt += 1) {
+    /** @type {Buffer | null} */
+    let bytes;
+    try {
+      bytes = readFileSync(markerPath);
+    } catch (err) {
+      // 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;
+    }
+    // classified IN PLACE: a refusal never moves, renames or touches the marker
+    const text = bytes.toString('utf8');
+    verdict = freshVerdict(text, resultOfMarker(repoRoot, text));
+    if (verdict !== 'rerun') break;
+    /** @type {unknown} */
+    let outcome;
+    try {
+      outcome = dropDone(repoRoot, ticket, bytes);
+    } catch (err) {
+      // a named refusal passes through; any other throw is named here, never echoed
+      if (err instanceof WorkerError) throw err;
+      throw new WorkerError('fresh-claim-failed', `the claim of the cached result of ${file} failed; nothing was queued`);
+    }
+    if (outcome === 'changed') {
+      verdict = 'counted';
+      continue;
+    }
+    // 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
+    const queued = enqueue({ repoRoot, run, block, file, ...where });
+    say(outcome === 'dropped' ? { ...queued, fresh: true } : queued);
+    return 0;
+  }
+  if (verdict === 'tampered') {
+    say({ status: 'refused', reason: 'fresh-tampered', ticket, file, exits: ['block close --no-require-reviews'], message: `fresh-tampered: the cached result of ${file} is review-state-tampered (a security event, not a stop); only the owner's block close --no-require-reviews gets past it; the cached result was kept` });
+    return 1;
+  }
+  say({
+    status: 'refused',
+    reason: 'fresh-needs-reopen',
+    ticket,
+    file,
+    exits: [...FRESH_EXITS],
+    message: `fresh-needs-reopen: the cached result of ${file} counts as a review (or cannot be read, or kept changing under the claim); --fresh re-runs only stale, unavailable or refused other-run/worktree-*/context-unreadable results; the human's ways out are block reopen and block waive; the cached result was kept`,
+  });
+  return 1;
+}
+
 /**
  * B62b: where the block `block` of run `runId` keeps its content, from the run record (read from
  * the user's state dir, `~/.code-forge/runs`, whatever the current directory): `{top}` with the
@@ -112,7 +262,63 @@ async function blockTreeOf(runId, block) {
 }
 
 /**
- * The coder-facing summary of a done result: the fix list and the stop reason, when any.
+ * B71: the coder-side pre-checks of an answers ticket (fast refusal only): with a run record this
+ * process can open, the block must own both files and every id must be open on the source's
+ * current hash — named by the latest refusal or cap row there, not waived or answered yet — read by
+ * the close's rules over unverified rows ({@link namedOnHash}). A record or ledger that
+ * cannot be read here skips the check it needs: the worker re-checks everything with signed rows.
+ * The rows of the ticket this request gets do not close an id (the retry of an attempt whose
+ * ledger write failed part way). `treeName`: the ticket's tree (null in the main tree).
+ * @param {{runId: string, block: string, file: string, byFile: string, tree: string, answers: string[], treeName: string | null}} opts
+ * @throws {WorkerError} `answers-not-owned`, `answers-not-open`
+ */
+async function answersPrecheck({ runId, block, file, byFile, tree, answers, treeName }) {
+  let record;
+  try {
+    record = await readRun(runId);
+  } catch {
+    return;
+  }
+  const entry = record?.blocks?.[block];
+  if (!entry || typeof entry !== 'object') return;
+  const owned = Array.isArray(entry.owned_files) ? entry.owned_files : [];
+  if (!ownsFile(owned, file, entry.owned_kinds) || !ownsFile(owned, byFile, entry.owned_kinds)) {
+    throw new WorkerError('answers-not-owned', `block ${block} does not own both ${byFile} and ${file}; nothing was queued`);
+  }
+  let rows;
+  try {
+    rows = await readAllRows(record.project);
+  } catch {
+    return;
+  }
+  const hash = contentHash(tree, file);
+  const current = new Map([
+    [file, hash],
+    [byFile, contentHash(tree, byFile)],
+  ]);
+  const by_hash = /** @type {string} */ (current.get(byFile));
+  const ticket = answersTicketId({ run: runId, block, file, content_hash: hash, by_file: byFile, by_hash, answers, tree: treeName });
+  const named = namedOnHash({ block, runId, rows, file, hash, current, ticket });
+  const missing = answers.filter((id) => !named.has(id));
+  if (missing.length > 0) throw new WorkerError('answers-not-open', `${missing.join(', ')} is not an open finding of ${file} at its current content; nothing was queued`);
+}
+
+/**
+ * B71: the `--answers` list: comma-separated finding ids, 1 to {@link MAX_ANSWERS}.
+ * @param {unknown} raw @returns {string[]}
+ * @throws {WorkerError} `usage`
+ */
+function answersOf(raw) {
+  if (typeof raw !== 'string') throw new WorkerError('usage', '--answers needs finding ids');
+  const ids = raw.split(',');
+  if (ids.length > MAX_ANSWERS) throw new WorkerError('usage', `--answers takes at most ${MAX_ANSWERS} finding ids`);
+  if (new Set(ids).size !== ids.length) throw new WorkerError('usage', '--answers names a finding id twice');
+  return assertAnswers(ids);
+}
+
+/**
+ * The coder-facing summary of a done result: the fix list and the stop reason, when any. B71: an
+ * answers result gives `answers: [{id, verdict, reason}]` instead.
  * @param {Record<string, any> | null} result
  * @returns {Record<string, any>}
  */
@@ -120,6 +326,10 @@ export function fixList(result) {
   if (!result || result.approved === true) return {};
   /** @type {Record<string, any>} */
   const out = {};
+  if (result.kind === 'answers' || result.status === 'answers') {
+    if (Array.isArray(result.findings)) out.answers = result.findings.map((/** @type {Record<string, any>} */ f) => ({ id: f?.id ?? null, verdict: f?.verdict ?? 'not_resolved', reason: f?.reason ?? '' }));
+    return out;
+  }
   if (Array.isArray(result.findings) && result.findings.length > 0) {
     out.fix_list = result.findings.map((/** @type {Record<string, any>} */ f) => ({
       id: f?.id ?? null,
@@ -129,8 +339,11 @@ export function fixList(result) {
       fix: f?.fix ?? '',
     }));
   }
-  if (typeof result.stopped === 'string') out.stop = result.stopped;
-  else if (result.status === 'split_required') out.stop = 'split_required';
+  if (typeof result.stopped === 'string') {
+    out.stop = result.stopped;
+    // B73: a stopped file names its ways out (never a refused or tampered state: no `stopped`)
+    out.exits = [...STOP_EXITS];
+  } else if (result.status === 'split_required') out.stop = 'split_required';
   // B54: a split_required stop (only) says how large the packet was, the budget, and the section
   if (out.stop === 'split_required') {
     const fin = (/** @type {unknown} */ v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
@@ -141,7 +354,7 @@ export function fixList(result) {
 
 /**
  * @param {string[]} args
- * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string, pollMs?: number}} [deps]
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string, pollMs?: number, dropDone?: typeof dropDoneIf}} [deps] - `dropDone`: B75's claim, for tests.
  * @returns {Promise<number>}
  */
 export async function runReviewFile(args, deps = {}) {
@@ -150,12 +363,12 @@ export async function runReviewFile(args, deps = {}) {
   const say = (/** @type {Record<string, any>} */ obj) => writeSafe(stdout, `${JSON.stringify(obj)}\n`);
   const cwd = deps.cwd ?? process.cwd();
   try {
-    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'max'] });
+    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'max', 'answers', 'of'], booleans: ['fresh'] });
     // the queue and the worker: the main tree, also from inside a block's worktree
     const repoRoot = await mainRootOf(cwd);
 
     if (typeof flags.wait === 'string') {
-      if (positionals.length > 0 || flags.block !== undefined) throw new WorkerError('usage', '--wait takes only a ticket and --max');
+      if (positionals.length > 0 || flags.block !== undefined || flags.answers !== undefined || flags.of !== undefined || flags.fresh === true) throw new WorkerError('usage', '--wait takes only a ticket and --max');
       const ticket = assertTicketId(flags.wait);
       const maxMs = flags.max === undefined ? DEFAULT_WAIT_MS : parseMax(flags.max);
       const deadline = Date.now() + maxMs;
@@ -181,6 +394,8 @@ export async function runReviewFile(args, deps = {}) {
 
     if (positionals.length !== 1 || typeof flags.block !== 'string' || flags.max !== undefined) throw new WorkerError('usage', 'give one path and --block');
     const block = assertBlockId(flags.block);
+    if (flags.fresh === true && (flags.answers !== undefined || flags.of !== undefined)) throw new WorkerError('usage', '--fresh takes no --answers or --of');
+    if (flags.answers !== undefined || flags.of !== undefined) return await enqueueAnswersTicket({ flags, answering: positionals[0], block, cwd, repoRoot, say });
     const file = normalizeRequestPath(positionals[0], cwd, await repoRootOf(cwd));
     const worker = liveWorker(repoRoot);
     if (!worker || (typeof flags.run === 'string' && flags.run !== worker.run)) {
@@ -193,6 +408,7 @@ export async function runReviewFile(args, deps = {}) {
     const tree = recorded === null ? await repoRootOf(cwd) : (recorded.top ?? repoRoot);
     assertInsideRoot(tree, file); // the path, re-checked in the tree its content is read from
     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 === 'unavailable') {
       // `unavailable` is never approval AND never final: drop the done marker so the worker runs
@@ -214,6 +430,41 @@ export async function runReviewFile(args, deps = {}) {
   }
 }
 
+/**
+ * B71: `review-file <answering file> --block <id> --answers <ids> --of <source>`.
+ * @param {{flags: Record<string, any>, answering: string, block: string, cwd: string, repoRoot: string, say: (obj: Record<string, any>) => unknown}} opts
+ * @returns {Promise<number>}
+ * @throws {WorkerError}
+ */
+async function enqueueAnswersTicket({ flags, answering, block, cwd, repoRoot, say }) {
+  if (typeof flags.of !== 'string' || flags.of.length === 0) throw new WorkerError('usage', '--answers needs --of <source>');
+  const answers = answersOf(flags.answers);
+  const top = await repoRootOf(cwd);
+  const byFile = normalizeRequestPath(answering, cwd, top);
+  const file = normalizeRequestPath(flags.of, cwd, top);
+  if (byFile === file) throw new WorkerError('answers-same-file', `${file} cannot answer its own findings: give the file that resolves them`);
+  const worker = liveWorker(repoRoot);
+  if (!worker || (typeof flags.run === 'string' && flags.run !== worker.run)) {
+    say({ status: 'worker_down', file });
+    return 3;
+  }
+  const recorded = await blockTreeOf(worker.run, block);
+  const tree = recorded === null ? top : (recorded.top ?? repoRoot);
+  assertInsideRoot(tree, file);
+  assertInsideRoot(tree, byFile);
+  const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree };
+  await answersPrecheck({ runId: worker.run, block, file, byFile, tree, answers, treeName: where.tree === undefined ? null : realpathSync(tree) });
+  const opts = { repoRoot, run: worker.run, block, file, byFile, answers, ...where };
+  const queued = enqueueAnswers(opts);
+  if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'unavailable') {
+    rmSync(path.join(queueDir(repoRoot), `${queued.ticket}.done`), { force: true });
+    say({ ...enqueueAnswers(opts), kind: 'answers', retry: true });
+    return 0;
+  }
+  say({ ...queued, kind: 'answers' });
+  return 0;
+}
+
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function run(args) {
   return runReviewFile(args);