@codedology/code-forge 0.9.0 → 0.11.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)
- *   block reopen <id> --run <r> --file <path> --reason <text>   (human-only, B72)
+ *   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)
  *
  * 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,
@@ -22,7 +22,8 @@
  * `--remove-worktree`). On
  * failure the exit code and stderr are unchanged and stdout stays empty, except a close the gate
  * refused (`closeBlock` said no), which also prints `{"block", "ok": false, "reason"}`. A usage
- * error, a thrown refusal, a cancelled `--no-require-reviews` and a failed `--remove-worktree`
+ * error, a thrown refusal, a cancelled `--no-require-reviews`, `block waive` or `block reopen` (or
+ * one with no terminal, B80) and a failed `--remove-worktree`
  * print nothing on stdout. Without `--json` every output is byte-identical to before.
  *
  * B64b block end: a close that closes or stops the block and `block stop` write
@@ -69,6 +70,21 @@
  * FAILED: no review-file ticket id for <files>` (skipped under `--no-require-reviews`, the human's
  * way out). It runs after the review rows and reuses their file set (listed once).
  *
+ * B96 (E1): the tool builds the close report. After the review gate passed, the close prints
+ * `reviewed <path> ticket <id>` for every file the gate accepted, sorted by path, before the
+ * `reviewed_by_waiver` lines and the closed line; the id is the queue's ticket for that file at the
+ * hash the gate accepted (`resolveTicket`: the tree of a worktree block is part of it). `--json`
+ * and the done file get `reviewed: [{file, ticket, via}]` (`via`: approved, waiver or answered —
+ * the gate's own verdict, `review/reviewed-lines.mjs`), only when there is a line. So `--report`
+ * needs no ticket line: a missing hand line refuses only for a file the tool has no line for, and a
+ * hand line that names another ticket prints `WARN report ticket mismatch <path>` on stderr while
+ * the close goes on (D1). A gate-accepted file with no ticket prints `WARN no ticket for <path>`
+ * (`WARN bad ticket for <path>` when the ticket is not 24 lowercase hex) and has no line; lines that
+ * cannot be built at all give no line and `WARN reviewed lines unavailable: <message>` — then
+ * `--report` needs a hand line for every file the gate accepted, as before B96. All four warnings
+ * are held and print only when the block closes. A waived or external-review close is unchanged:
+ * no line, no key.
+ *
  * B58 (issue #11): `review.external.required: true` in the run's config snapshot (the owner set it
  * before `run start`; `run reload` refuses to change it) is the owner's non-interactive way out
  * when an outside reviewer reviews the block: the per-file review checks and the `--report` ticket
@@ -156,6 +172,22 @@
  * <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
+ * 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
+ * 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
+ * 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.
+ *
  * `--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`.
@@ -174,7 +206,7 @@ import { configInForce, externalReviewer, requireCoderTests } from '../state/con
 import { StateError } from '../state/paths.mjs';
 import { readRun, writeSigned } from '../state/run.mjs';
 import { loadKey, verifyRow } from '../state/signer.mjs';
-import { blockFileSet, changedFiles, ownsAt, resultFilesFor, reviewedFiles, reviewGateCheck, unownedChanges, waiveFinding } from '../review/gate-check.mjs';
+import { PROOF_FINDING, blockFileSet, changedFiles, openFindings, ownsAt, resultFilesFor, reviewedFiles, reviewGateCheck, unownedChanges, waiveFinding } from '../review/gate-check.mjs';
 import { checkExpiry } from '../autopilot/grant.mjs';
 import { redact, writeSafe } from '../util/redact.mjs';
 import { blockTree, prepareWorktree, removeWorktree, worktreeSettings } from '../proof/worktree.mjs';
@@ -183,11 +215,13 @@ 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 { clearDone } from '../worker/queue.mjs';
+import { clearDone, resolveTicket } from '../worker/queue.mjs';
 import { loadState } from '../worker/review-state.mjs';
 import { 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';
+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';
@@ -263,10 +297,14 @@ const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', '
  *   isTTY?: boolean, stdinIsTTY?: boolean, stdoutIsTTY?: boolean,
  *   ui?: {confirm: (o: {message: string, initialValue?: boolean}) => Promise<unknown>, isCancel: (v: unknown) => boolean},
  *   removeBlockTree?: typeof removeBlockTree,
+ *   resolveTicket?: typeof resolveTicket, reviewedLines?: typeof reviewedLines,
  * }} [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`): B52's confirmation of `--no-require-reviews`, which needs both to be TTYs.
+ *   `@clack/prompts`): the human's confirmation (B52 `--no-require-reviews`, B80 `block waive` and
+ *   `block reopen`), which needs both to be TTYs.
  *   `removeBlockTree` (B64b, tests only): the `--remove-worktree` step, default the real one.
+ *   `resolveTicket` / `reviewedLines` (B96, tests only): the queue's ticket rule and the reviewed
+ *   lines builder of the close, default the real ones.
  * @returns {Promise<number>}
  */
 export async function runBlock(args, deps = {}) {
@@ -307,12 +345,26 @@ export async function runBlock(args, deps = {}) {
     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 });
+    // 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') {
+      const asked = await confirmHumanVerb(sub, runId, id, { finding: extra, file: /** @type {string} */ (flags.file) }, 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;
+      }
+    }
+    const writeRow =(/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
     // 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.
     const hook = blockEndHook(record);
-    const ended = async (/** @type {'closed' | 'stopped'} */ status, /** @type {string} */ event, /** @type {string | null} */ reason) => {
+    // B96: `reviewed` (the close's tool lines) joins the done file only when there is one
+    const ended = async (/** @type {'closed' | 'stopped'} */ status, /** @type {string} */ event, /** @type {string | null} */ reason, /** @type {import('../review/reviewed-lines.mjs').ReviewedLine[]} */ reviewed = []) => {
       // ruling (e): `ended` never throws — any failure here is the done-file warning and a null
       // `doneFile`, so the caller's try/finally still reaches the hook
       /** @type {string | null} */
@@ -326,6 +378,7 @@ export async function runBlock(args, deps = {}) {
           reason: typeof reason === 'string' ? redact(reason) : null,
           openFindings: (rows) => blockOpenFindings(record, rows, id),
           err,
+          ...(reviewed.length > 0 ? { reviewed } : {}),
         });
       } catch (thrown) {
         const code = /** @type {any} */ (thrown)?.code;
@@ -536,6 +589,9 @@ export async function runBlock(args, deps = {}) {
       // 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)
+      // B96: whether the review gate passed — set from the gate's own result (below), so the files
+      // it checked are the ones it accepted and the tool can give their reviewed lines
+      let reviewsPassed = false;
       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)
@@ -543,7 +599,7 @@ export async function runBlock(args, deps = {}) {
         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 gate = reviewGateCheck(async () => {
         const transcript = await findTranscript(record, id, typeof flags.transcript === 'string' ? flags.transcript : null);
         if (transcript === null) {
           await writeSigned(runId, writeRow, { event: 'gate.transcript_missing', block: id });
@@ -593,7 +649,63 @@ export async function runBlock(args, deps = {}) {
           highPaths,
         };
       }, { onWaivedAll });
-      // B36: the coder's report names a review-file ticket for every changed file, or it is FAILED
+      // 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.
+      const reviews = async () => {
+        const result = await gate();
+        reviewsPassed = result.ok;
+        return result;
+      };
+      // B96: the stderr warnings of the reviewed lines (`WARN no ticket for <path>`, `WARN bad
+      // ticket for <path>`, `WARN reviewed lines unavailable: <message>`, `WARN report ticket
+      // mismatch <path>`): kept here and printed only when the block closes, before the reviewed
+      // lines — a refused close prints none
+      /** @type {string[]} */
+      const lineWarnings = [];
+      // B96: the tool's reviewed lines — one per file the review gate accepted, with the queue's
+      // ticket for that file at the hash the gate accepted (`resolveTicket`, the queue's own rule:
+      // the same path check, tree resolution and ticket id); a file whose content moved since the
+      // gate hashed it, or whose ticket cannot be given, has no line (fail closed, `WARN no ticket
+      // for <path>`), and so has a file whose ticket is not 24 lowercase hex (`WARN bad ticket for
+      // <path>`). None when the reviews were waived (the human flag or `review.external`) or the
+      // gate has not passed — and that empty answer is never memoised: the lines are built once,
+      // from the gate's pass (its file set and hashes, its waivedAll). It never throws: an error
+      // gives no lines and one held `WARN reviewed lines unavailable: <message>`, so the done file
+      // and the on_block_end hook of a closed block always follow.
+      /** @type {Promise<import('../review/reviewed-lines.mjs').ReviewedLine[]> | undefined} */
+      let linesOnce;
+      const toolLines = async () => {
+        if (!reviewsPassed || reviewsWaived || external !== null) return [];
+        linesOnce ??= (async () => {
+          try {
+            const { mainTop, top, inTree, fileSet } = await tree();
+            const resolve = deps.resolveTicket ?? resolveTicket;
+            const ticketOf = (/** @type {{file: string, content_hash: string}} */ f) => {
+              try {
+                const t = resolve({ repoRoot: mainTop, run: runId, block: id, file: f.file, tree: inTree ? top : null });
+                return t.content_hash === f.content_hash ? t.ticket : null;
+              } catch {
+                return null;
+              }
+            };
+            return await (deps.reviewedLines ?? reviewedLines)({
+              files: fileSet,
+              waivedAll,
+              ticketOf,
+              onNoTicket: (file) => lineWarnings.push(`WARN no ticket for ${file}\n`),
+              onBadTicket: (file) => lineWarnings.push(`WARN bad ticket for ${file}\n`),
+            });
+          } catch (thrown) {
+            lineWarnings.push(`WARN reviewed lines unavailable: ${thrown instanceof Error ? thrown.message : String(thrown)}\n`);
+            return [];
+          }
+        })();
+        return linesOnce;
+      };
+      // B36 → B96: the coder's report. The tool gives the reviewed lines, so a missing hand line is
+      // a refusal only for a file the tool has no line for; a hand line that names another ticket
+      // is a warning and the close goes on (D1: the tool lines are the record)
       const report = async () => {
         if (typeof flags.report !== 'string' || reviewsWaived || external !== null) return { ok: true };
         let text;
@@ -603,8 +715,12 @@ export async function runBlock(args, deps = {}) {
           return { ok: false, reason: 'coder report FAILED: --report cannot be read' };
         }
         const { fileSet } = await tree();
-        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(', ')}` };
+        const lines = await toolLines();
+        const given = new Set(lines.map((l) => l.file));
+        const missing = missingReviewTickets(text, fileSet.map((f) => f.file)).filter((f) => !given.has(f));
+        if (missing.length > 0) return { ok: false, reason: `coder report FAILED: no review-file ticket id for ${missing.join(', ')}` };
+        for (const file of reportMismatches(text, lines)) lineWarnings.push(`WARN report ticket mismatch ${file}\n`);
+        return { ok: true };
       };
       /** @type {Array<() => Promise<{ok: boolean, reason?: string}>>} */
       const extraChecks = [reviews, report];
@@ -634,14 +750,19 @@ export async function runBlock(args, deps = {}) {
       const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks, closeRows });
       // 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
-      const end = result.status === 'closed' || result.status === 'stopped' ? await ended(result.status, result.event ?? (result.status === 'stopped' ? 'block.stop' : 'block.close'), result.reason ?? null) : null;
+      // B96: the tool's reviewed lines of a block that closed (also kept in its done file)
+      const reviewedJson = result.ok ? await toolLines() : [];
+      const end = result.status === 'closed' || result.status === 'stopped' ? await ended(result.status, result.event ?? (result.status === 'stopped' ? 'block.stop' : 'block.close'), result.reason ?? null, reviewedJson) : null;
       // B64b ruling (e): the hook runs exactly once for this end, after everything else the verb
       // does — also when a later step (the output, `--remove-worktree`) throws; it never changes
       // the exit code or stdout (`runHook` never throws)
       try {
+        // B96: the reviewed lines (sorted by path) come first, then the reviewed_by_waiver lines
         // 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 w of lineWarnings) err(w);
+          for (const l of reviewedJson) say(`reviewed ${l.file} ticket ${l.ticket}\n`);
           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(', ')}`);
@@ -660,6 +781,8 @@ export async function runBlock(args, deps = {}) {
           ...(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 } : {}) })) } : {}),
+          // B96: only when the tool gave reviewed lines (a waived or external close is unchanged)
+          ...(reviewedJson.length > 0 ? { reviewed: reviewedJson } : {}),
         };
         if (!result.ok || !removeTree) {
           if (json && result.ok) emit(closedJson);
@@ -733,31 +856,139 @@ async function coderTests(reportFlag, id) {
 export const NO_REVIEWS_NO_TTY = '--no-require-reviews needs the human at a terminal to confirm; the block stays open (there is no --yes)';
 
 /**
- * B52: `--no-require-reviews` lifts every per-file review check, so it is the human's alone — the
- * same rule as `autopilot approve`: a flag can be passed by any process (the orchestrator, a
- * script, the delegate's tooling), so the human confirms at a terminal and there is NO `--yes`.
- * No terminal — stdin AND stdout must both be TTYs (a piped stdout means nobody may see the
- * question) — ⇒ `usage` (exit 2); an active autopilot grant on the run ⇒ `autopilot-active`
- * (exit 1; the owner stops the grant first) — nothing is written either way. `deps.stdinIsTTY` /
- * `deps.stdoutIsTTY` inject each side; `deps.isTTY` injects both at once.
- * @param {string} runId @param {string} id
- * @param {{isTTY?: boolean, stdinIsTTY?: boolean, stdoutIsTTY?: boolean, ui?: {confirm: (o: {message: string, initialValue?: boolean}) => Promise<unknown>, isCancel: (v: unknown) => boolean}, now?: () => Date}} deps
- * @returns {Promise<'confirmed' | 'cancelled'>}
- * @throws {StateError} `usage`, `autopilot-active`
+ * B80: the refusal when `block waive` or `block reopen` has no terminal to ask the human at.
+ * @param {'waive' | 'reopen'} verb @returns {string}
  */
-async function confirmNoReviews(runId, id, deps) {
+export const humanVerbNoTTY = (verb) => `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
+ */
+
+/**
+ * The ONE human confirm of the `block` verb (B52 `--no-require-reviews`, B80 `block waive` and
+ * `block reopen`): a flag or a verb can be run by any process (the orchestrator, a script, a
+ * coder), so the human answers a yes/no question at a terminal and there is NO `--yes`. No
+ * terminal — stdin AND stdout must both be TTYs (a piped stdout means nobody may see the
+ * question) — is `no-tty`, decided before anything is read or asked. `before` runs between the
+ * terminal check and the question (a refusal it throws means the human is never asked).
+ * `deps.stdinIsTTY` / `deps.stdoutIsTTY` inject each side, `deps.isTTY` both at once, `deps.ui`
+ * the prompt (default `@clack/prompts`). A "no" or a cancel (Ctrl-C) is `cancelled`.
+ * @param {ConfirmDeps} deps @param {string} message
+ * @param {() => Promise<unknown> | unknown} [before]
+ * @returns {Promise<'no-tty' | 'confirmed' | 'cancelled'>}
+ */
+async function confirmAtTerminal(deps, message, before) {
   const stdinTTY = deps.stdinIsTTY ?? deps.isTTY ?? process.stdin.isTTY === true;
   const stdoutTTY = deps.stdoutIsTTY ?? deps.isTTY ?? process.stdout.isTTY === true;
-  if (!(stdinTTY && stdoutTTY)) throw new StateError('usage', NO_REVIEWS_NO_TTY);
-  const grant = await checkExpiry(runId, (deps.now ?? (() => new Date()))());
-  if (grant.state === 'active') {
-    throw new StateError('autopilot-active', `--no-require-reviews is refused while an autopilot grant is active on run ${runId} (stop it first: code-forge autopilot stop --run ${runId})`);
-  }
+  if (!(stdinTTY && stdoutTTY)) return 'no-tty';
+  if (before) await before();
   const ui = deps.ui ?? /** @type {any} */ (await import('@clack/prompts'));
-  const go = await ui.confirm({ message: `Close block ${id} of run ${runId} WITHOUT the per-file review checks? Only the owner may say yes.`, initialValue: false });
+  const go = await ui.confirm({ message, initialValue: false });
   return ui.isCancel(go) || go !== true ? 'cancelled' : 'confirmed';
 }
 
+/**
+ * B52: `--no-require-reviews` lifts every per-file review check, so it is the human's alone — the
+ * same rule as `autopilot approve` (`confirmAtTerminal`). No terminal ⇒ `usage` (exit 2); an
+ * active autopilot grant on the run ⇒ `autopilot-active` (exit 1; the owner stops the grant
+ * first) — nothing is written either way.
+ * @param {string} runId @param {string} id @param {ConfirmDeps} deps
+ * @returns {Promise<'confirmed' | 'cancelled'>}
+ * @throws {StateError} `usage`, `autopilot-active`
+ */
+async function confirmNoReviews(runId, id, deps) {
+  const asked = await confirmAtTerminal(deps, `Close block ${id} of run ${runId} WITHOUT the per-file review checks? Only the owner may say yes.`, async () => {
+    const grant = await checkExpiry(runId, (deps.now ?? (() => new Date()))());
+    if (grant.state === 'active') {
+      throw new StateError('autopilot-active', `--no-require-reviews is refused while an autopilot grant is active on run ${runId} (stop it first: code-forge autopilot stop --run ${runId})`);
+    }
+  });
+  if (asked === 'no-tty') throw new StateError('usage', NO_REVIEWS_NO_TTY);
+  return asked;
+}
+
+/**
+ * B80: `block waive` and `block reopen` are the human's alone (D1 = a): the human confirms at a
+ * terminal through `confirmAtTerminal`, exactly like `--no-require-reviews`, but an active
+ * 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
+ * @returns {Promise<'no-tty' | 'confirmed' | 'cancelled'>}
+ */
+function confirmHumanVerb(verb, runId, id, what, record, deps) {
+  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.`;
+  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);
+  });
+}
+
+/**
+ * Does the block own `file`, by the rule both verbs use (`ownsAt` with the workspace's prefix
+ * inside its repo)?
+ * @param {Record<string, any>} record @param {Record<string, any>} entry @param {string} file
+ * @returns {Promise<boolean>}
+ */
+async function blockOwnsFile(record, entry, file) {
+  const real = async (/** @type {string} */ p) => realpath(p).catch(() => path.resolve(p));
+  const mainTop = await real(await repoTop(record.workspace));
+  const wsPrefix = path.relative(mainTop, await real(record.workspace)).split(path.sep).join('/');
+  const owned = Array.isArray(entry.owned_files) ? entry.owned_files : [];
+  return ownsAt(wsPrefix)(owned, file, entry.owned_kinds);
+}
+
+/**
+ * B80: the checks a reopen must pass BEFORE the human is asked, in `reopenFile`'s order: the
+ * `--file` form (`checkFileForm`, the reopen rule: `usage`), the block (`openBlockEntry`:
+ * `unknown_block`, `reopen-block-not-open`) and ownership (`reopen-not-owned`, the same message).
+ * The state checks that read the key and the ledger stay the verb's.
+ * @param {Record<string, any>} record @param {string} runId @param {string} id @param {string} file
+ * @returns {Promise<void>}
+ * @throws {StateError}
+ */
+async function reopenPrecheck(record, runId, id, file) {
+  checkFileForm(file, { normalized: true });
+  const entry = openBlockEntry(record, runId, id);
+  if (!(await blockOwnsFile(record, entry, file))) throw new StateError('reopen-not-owned', `reopen-not-owned: block ${id} does not own ${file}; nothing was recorded`);
+}
+
+/**
+ * B80: the checks a waive must pass BEFORE the human is asked, so the human is never asked about a
+ * waive the verb would refuse, in `waiveFinding`'s order: the finding id and `--file` have the
+ * forms `waiveFinding` takes (`checkFindingId`, `checkFileForm`: `usage`, the same helpers); the
+ * block is in the run (`unknown_block`); the block owns the file
+ * (`waive-not-owned`, the reopen's ownership rule through `ownsAt`); and, except for the proof
+ * finding (`proof`, which no review row names), a review row of this run and block for the file
+ * names the id (`waive-unknown-finding`): `review.triage` / `review.late_finding` `finding`, a
+ * `review.result` `open` id (as the gate reads it, `openFindings`) or a `review.cap` `open` id.
+ * @param {Record<string, any>} record @param {string} runId @param {string} id
+ * @param {string} finding @param {string} file
+ * @returns {Promise<void>}
+ * @throws {StateError}
+ */
+async function waivePrecheck(record, runId, id, finding, file) {
+  checkFindingId(finding);
+  checkFileForm(file, { normalized: false });
+  const entry = record.blocks?.[id];
+  if (!entry) throw new StateError('unknown_block', `block ${id} is not in run ${runId}`);
+  if (!(await blockOwnsFile(record, entry, file))) throw new StateError('waive-not-owned', `waive-not-owned: block ${id} does not own ${file}; nothing was recorded`);
+  if (finding === PROOF_FINDING) return;
+  const named = (await readAllRows(record.project)).some((r) => {
+    if (r?.run !== runId || r.block !== id || r.file !== file) return false;
+    if (r.event === 'review.triage' || r.event === 'review.late_finding') return r.finding === finding;
+    if (r.event === 'review.result') return Array.isArray(r.open) && openFindings(r.open).some((o) => o.id === finding);
+    if (r.event === 'review.cap') return Array.isArray(r.open) && r.open.includes(finding);
+    return false;
+  });
+  if (!named) throw new StateError('waive-unknown-finding', `waive-unknown-finding: no review row of block ${id} names finding ${finding} in ${file}; nothing was recorded`);
+}
+
 /**
  * B59: the rules lane for a brief-mode block — `fallbackLane` over the facts of its owned entries,
  * the `--lines` estimate and the snapshot's `proof.tiers.high.paths` (none for a record from

package/src/cli/jev.mjs

@@ -23,11 +23,17 @@
  * subfolder thus writes to the project's ledger. An unknown flag is a usage error.
  *
  * Resolves the Jev key through B2's chain (`resolveKey`, earlier batch — the seam rule allows a
- * Wave 1 module to import a block in an earlier batch statically), asks Jev, runs the answer
+ * Wave 1 module to import a block in an earlier batch statically) with the project's
+ * `keys.cache_hours` (B84; an invalid value warns once and uses 8 h), asks Jev, runs the answer
  * through `thresholds.decide()`, and appends one `{event: 'decision', ...}` row through B6's
  * writer (also an earlier batch) — the shape `ledger/calibration.mjs` already expects:
  * `decision_id`, `question`, `confidence` (plan §6.3's calibration buckets read exactly these).
  *
+ * B85: when no key resolved because the cached one expired and 1Password did not answer, and the
+ * reference is `op://…`, the generic "no Jev key resolved" line is replaced by one re-link line
+ * naming the expired time and the exact `code-forge keys set jev --op <ref>` command (the
+ * 1Password reasons still print first; same text with or without a TTY).
+ *
  * Never prints the key: it only ever reaches the `Authorization` header inside `askJev`, and
  * `resolveKey` has already registered it with `redact()` before this module sees it.
  */
@@ -40,7 +46,7 @@ import { buildQuestionPayload, isKnownQuestion, isQuestionDisabled } from '../de
 import { askJev as realAskJev } from '../decide/jev-client.mjs';
 import { decide } from '../decide/thresholds.mjs';
 import { resolveDispatchQuestionsByRules } from '../decide/fallback-rules.mjs';
-import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
+import { cacheHoursFrom, createDefaultKeyStore, isTime, resolveKey, shellWord } from '../keys/store.mjs';
 import { appendRow as realAppendRow } from '../ledger/write.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
@@ -113,6 +119,7 @@ function badRuleFacts(state) {
  * @param {object} deps
  * @param {import('../keys/store.mjs').KeyStore} [deps.store]
  * @param {typeof loadConfigFile} [deps.loadConfig]
+ * @param {typeof import('../keys/onepassword.mjs').opRead} [deps.opRead] - the 1Password reader (tests inject a fake).
  * @param {typeof realAskJev} [deps.askJev]
  * @param {typeof realAppendRow} [deps.appendRow]
  * @param {{write: (s: string) => unknown}} [deps.stdout]
@@ -126,6 +133,7 @@ export async function runJev(args, deps = {}) {
   const {
     store,
     loadConfig = loadConfigFile,
+    opRead,
     askJev: ask = realAskJev,
     appendRow: write = realAppendRow,
     stdout = process.stdout,
@@ -218,9 +226,14 @@ export async function runJev(args, deps = {}) {
 
   const keyStore = store ?? (await createDefaultKeyStore(env));
   const keyRef = keyRefFlag.value ?? cfg?.keys?.jev;
+  // B84: the project's cache time; an invalid one warns once and falls back to the default
+  const cache = cacheHoursFrom(cfg);
+  if (cache.problem !== null) {
+    err(`WARN jev ask: ${cache.problem}; caching for the default ${cache.hours} h\n`);
+  }
   let resolved;
   try {
-    resolved = await resolveKey('jev', { store: keyStore, ref: keyRef, env, now: now() });
+    resolved = await resolveKey('jev', { store: keyStore, ref: keyRef, env, now: now(), cacheHours: cache.hours, ...(opRead ? { opRead } : {}) });
   } catch (thrown) {
     err(`jev ask: ${thrown?.message ?? String(thrown)}\n`);
     return 2;
@@ -229,6 +242,12 @@ export async function runJev(args, deps = {}) {
     for (const reason of resolved.errors) {
       err(`jev ask: ${reason}\n`);
     }
+    // `expired` is the dropped entry's exp in ms; anything that is not a valid time gives the
+    // generic line
+    if (isTime(resolved.expired) && typeof keyRef === 'string' && keyRef.startsWith('op://')) {
+      err(`jev ask: the cached jev key expired at ${new Date(resolved.expired).toISOString()} and 1Password did not answer; re-link: code-forge keys set jev --op ${shellWord(keyRef)}\n`);
+      return 1;
+    }
     err('jev ask: no Jev key resolved (set one with "code-forge keys set jev")\n');
     return 1;
   }