@codedology/code-forge 0.8.0 → 0.10.0

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>
@@ -10,7 +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 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,
@@ -21,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
@@ -77,6 +79,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 +143,36 @@
  * 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"}`.
+ *
+ * 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`.
@@ -146,7 +191,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';
@@ -154,19 +199,79 @@ 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 { checkFileForm, checkFindingId } from '../review/verb-forms.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'];
 
 /**
@@ -178,7 +283,8 @@ const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', '
  *   removeBlockTree?: typeof removeBlockTree,
  * }} [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.
  * @returns {Promise<number>}
  */
@@ -214,11 +320,26 @@ 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 });
+    // 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.
@@ -367,6 +488,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 +559,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 +624,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 +638,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 +671,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;
@@ -606,31 +765,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;
   }