@codedology/code-forge 0.7.7 → 0.9.0

package/src/review/open-findings.mjs

@@ -0,0 +1,59 @@
+/**
+ * The open review findings of a block (B64a `code-forge status`, B64b done file): the number of
+ * distinct (file, finding) pairs the block gate (`checkBlockReviews`) would refuse today, each
+ * reviewed file at the content hash of its last review row. Shared by `src/cli/status.mjs` and
+ * `src/cli/block.mjs`, so the done file and `status` count the same way.
+ */
+import { KEY_BYTES, loadKey } from '../state/signer.mjs';
+import { checkBlockReviews, reviewedFiles } from './gate-check.mjs';
+
+/** The refusal codes that name one open review finding. */
+const FINDING_CODES = new Set(['not_approved', 'late_unruled', 'review_cap', 'autopilot_waiver_invalid']);
+
+/**
+ * The open review findings of one block: the gate's own check over the files the block's review
+ * rows name, each at the content hash it was last reviewed at.
+ * @param {{block: string, runId: string, mine: Array<Record<string, any>>, rows: Array<Record<string, any>>, key: Buffer}} opts
+ *   `mine`: the block's rows of the run; `rows`: every row of the project (waivers, rulings).
+ * @returns {number}
+ */
+export function openFindingsOf({ block, runId, mine, rows, key }) {
+  /** @type {Map<string, string>} each reviewed file -> the content hash of its last review row */
+  const hashes = new Map();
+  for (const r of mine) {
+    if (typeof r.content_hash !== 'string') continue;
+    const [file] = reviewedFiles([r], block); // a review row naming a repo path, else none
+    if (file !== undefined) hashes.set(file, r.content_hash);
+  }
+  const files = reviewedFiles(mine, block).map((file) => ({ file, content_hash: hashes.get(file) ?? '' }));
+  if (files.length === 0 && !mine.some((r) => r.event === 'review.late_finding')) return 0;
+  const { refusals } = checkBlockReviews({ block, runId, files, rows, key, proofFiles: [], highPaths: [] });
+  const pairs = new Set(refusals.filter((r) => FINDING_CODES.has(r.code) && typeof r.finding === 'string').map((r) => `${r.file}\0${r.finding}`));
+  return pairs.size;
+}
+
+/**
+ * The run key for counting findings: read only; with no key a zero key stands in, so no signed
+ * waiver or approval verifies (fail closed).
+ * @param {Record<string, any>} record @returns {Promise<Buffer>}
+ */
+export async function findingsKey(record) {
+  try {
+    return await loadKey(record.run_id);
+  } catch {
+    return Buffer.alloc(KEY_BYTES);
+  }
+}
+
+/**
+ * B64b: the open findings `status` shows for ONE block — the same count (`openFindingsOf`, the
+ * same key rule), for the block-end done file.
+ * @param {Record<string, any>} record @param {Array<Record<string, any>>} rows - the project's rows.
+ * @param {string} block
+ * @returns {Promise<number>}
+ */
+export async function blockOpenFindings(record, rows, block) {
+  const runId = String(record.run_id);
+  const mine = rows.filter((r) => r?.run === runId && r.block === block);
+  return openFindingsOf({ block, runId, mine, rows, key: await findingsKey(record) });
+}

package/src/review/reopen.mjs

@@ -0,0 +1,258 @@
+/**
+ * B72 (issues #12, #15): `block reopen <id> --file <path> --run <r> --reason <text>` — the human
+ * restarts the review of a file the fix loop STOPPED (any reason: `review_cap`,
+ * `l3_patch_exhausted`, `split_required`, …) or whose state is LOST (B68). Only a stopped file
+ * needs content that differs from what its stop reviewed; a lost file restarts on its current
+ * content.
+ *
+ * Human-only like `block waive`: the verb is on `CODER_ONLY_FORBIDDEN` (`src/util/forbidden.mjs`)
+ * and its row is signed with the run key, `by: human` (`block waive` has no other in-verb guard,
+ * so neither has this). The verb (`reopenFile`) refuses, writing no row, with a stable code:
+ *  - `usage` (exit 2) — no `--file`, no `--reason`, or a path that is not a normalised
+ *    repo-root-relative path;
+ *  - `unknown_block` — the run does not know the block (the code `block waive` uses);
+ *  - `reopen-block-not-open` — the block is not open (stopped or closed);
+ *  - `reopen-not-owned` — the block does not own the file;
+ *  - `reopen-tampered` — the file's state does not verify (an integrity failure stays a security
+ *    event; the owner's exit is `block close --no-require-reviews`);
+ *  - `reopen-not-stopped` — no state, or a state that is open or complete;
+ *  - `reopen-same-content` — a stopped file whose current content is the content its stop
+ *    reviewed (no free re-roll: the human waives the findings instead), or a stop whose content
+ *    is unknown;
+ *  - `reopen-already-recorded` — a verified human row already names the file's latest anchor seq
+ *    for other content (run `review-file`, or the content changed since that reopen);
+ *  - `reopen-write-failed` — the signed row was not written.
+ * Accepted, it first drops the done marker of the current content's ticket (C11, `io.clearDone`),
+ * then writes ONE signed `review.reopened {block, file, from: stopped|lost, stop_reason, at_seq,
+ * from_hash, to_hash, reason, by: human}` row (`at_seq` = the file's latest anchor seq). There is
+ * at most one verified human row per `at_seq`: a retry on the same content finds it and writes
+ * none.
+ *
+ * The content a stop reviewed (`stopContentHash`) is the stopped state's `stop_content_hash`,
+ * which the worker sets on every stop (`src/worker/engine.mjs`) and which is signed through the
+ * anchor. A state from before B72 has none: then the latest verified `review.cap` row of THIS
+ * stop counts — written after the file's latest verified `review.reopened` row, with the state's
+ * round and stop reason — else the content is unknown and the reopen is refused.
+ *
+ * The worker (`fixLoopRound`) asks `reopenRowFor`: a verified human row of this run for the block
+ * and file whose `at_seq` is the file's latest anchor seq starts a new state (round 1, a FULL
+ * review, `reviewed_content` null, the level from the run record, `l3_rung_used` kept). The new
+ * state saves at `at_seq + 1`, so a row works once. For `stopped` the content must still differ
+ * from the stop's content; else the stop repeats.
+ *
+ * This file imports nothing from `src/worker/`: the fix-loop state is read through `io`.
+ */
+import path from 'node:path';
+import { StateError } from '../state/paths.mjs';
+import { verifyRow } from '../state/signer.mjs';
+
+export const REOPENED_EVENT = 'review.reopened';
+
+/** A code a refusal may name: an errno (`EACCES`), a StateError code (`ledger-locked`), a name. */
+const CAUSE_CODE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+
+/**
+ * B79: the code a failed write names — the error's `code`, else its `name`, when it has the form
+ * {@link CAUSE_CODE}, else `unknown` (a thrown `undefined` or `null` too). Called only for a
+ * write that threw; one that wrote nothing is named `no-write` by its caller. Never the message:
+ * it may hold a path or a value.
+ * @param {unknown} err @returns {string}
+ */
+function causeCode(err) {
+  if (err === null || err === undefined) return 'unknown';
+  const e = /** @type {{code?: unknown, name?: unknown}} */ (err);
+  if (typeof e.code === 'string' && CAUSE_CODE.test(e.code)) return e.code;
+  if (typeof e.name === 'string' && CAUSE_CODE.test(e.name)) return e.name;
+  return 'unknown';
+}
+
+/**
+ * Whether a row's MAC verifies with the run key (a throw is a no).
+ * @param {Record<string, any>} row @param {Buffer} key
+ */
+function verified(row, key) {
+  try {
+    return verifyRow(row, key).ok === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The content hash the stop of a stopped state reviewed, or null when it is unknown: the state's
+ * `stop_content_hash`; for a state from before B72, the latest verified `review.cap` row of this
+ * run for the block and file that belongs to this stop (after the file's latest verified
+ * `review.reopened` row, with the state's round and stop reason).
+ * @param {Record<string, any> | null} state
+ * @param {ReadonlyArray<Record<string, any>>} rows
+ * @param {{runId: string, block: string, file: string, key: Buffer}} at
+ * @returns {string | null}
+ */
+export function stopContentHash(state, rows, { runId, block, file, key }) {
+  if (state?.status !== 'stopped') return null;
+  if (typeof state.stop_content_hash === 'string' && state.stop_content_hash.length > 0) return state.stop_content_hash;
+  const mine = (/** @type {Record<string, any>} */ r) => r?.run === runId && r.block === block && r.file === file && verified(r, key);
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const r = rows[i];
+    if (r?.event === REOPENED_EVENT && mine(r)) return null;
+    if (r?.event !== 'review.cap' || !mine(r)) continue;
+    if (typeof r.content_hash !== 'string' || r.round !== state.round || r.reason !== state.next?.reason) return null;
+    return r.content_hash;
+  }
+  return null;
+}
+
+/**
+ * The block checks every reopen runs first, before any config, key or ledger read: the run must
+ * know the block (`unknown_block`, the code `block waive` uses) and the block must be open.
+ * @param {Record<string, any>} record @param {string} runId @param {string} id
+ * @returns {Record<string, any>} the block's entry.
+ * @throws {StateError} `unknown_block` or `reopen-block-not-open`.
+ */
+export function openBlockEntry(record, runId, id) {
+  const entry = record.blocks?.[id];
+  if (!entry) throw new StateError('unknown_block', `block ${id} is not in run ${runId}`);
+  if (entry.status !== 'open') throw new StateError('reopen-block-not-open', `reopen-block-not-open: block ${id} is not open in run ${runId}; nothing was recorded`);
+  return entry;
+}
+
+/**
+ * The latest verified human `review.reopened` row of this run for the block and file whose
+ * `at_seq` is `seq`, or null.
+ * @param {ReadonlyArray<Record<string, any>>} rows
+ * @param {{runId: string, block: string, file: string, key: Buffer, seq: number}} at
+ * @returns {Record<string, any> | null}
+ */
+function latestRowAt(rows, { runId, block, file, key, seq }) {
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const r = rows[i];
+    if (r?.event !== REOPENED_EVENT || r.run !== runId || r.block !== block || r.file !== file) continue;
+    if (r.by !== 'human' || r.at_seq !== seq || !verified(r, key)) continue;
+    return r;
+  }
+  return null;
+}
+
+/**
+ * Worker side: the `review.reopened` row that restarts this file now, or null. Only a row whose MAC
+ * verifies with the run key, of this run, block and file, `by: human`, and whose `at_seq` is the
+ * file's latest anchor seq counts (the latest such row). A `lost` state needs `from: lost`; a
+ * stopped state needs `from: stopped` AND current content that is neither the row's `from_hash`
+ * nor the content the stop reviewed (`stopContentHash`; unknown ⇒ no restart).
+ * @param {ReadonlyArray<Record<string, any>>} rows
+ * @param {{runId: string, block: string, file: string, key: Buffer, status: string, state: Record<string, any> | null, seq: number, contentHash: string}} at
+ * @returns {Record<string, any> | null}
+ */
+export function reopenRowFor(rows, { runId, block, file, key, status, state, seq, contentHash }) {
+  const row = latestRowAt(rows, { runId, block, file, key, seq });
+  if (row === null) return null;
+  if (status === 'lost') return row.from === 'lost' ? row : null;
+  if ((status === 'ok' || status === 'restored') && state?.status === 'stopped' && row.from === 'stopped') {
+    const stopHash = stopContentHash(state, rows, { runId, block, file, key });
+    if (stopHash === null || contentHash === stopHash || contentHash === row.from_hash) return null;
+    return row;
+  }
+  return null;
+}
+
+/**
+ * The verb (`block reopen`): check, drop the done marker (`io.clearDone`), then write the signed
+ * row — or return the verified human row an earlier try wrote for the same `at_seq` and `to_hash`
+ * (at most one row per `at_seq`: one for other content is refused `reopen-already-recorded`).
+ * @param {{
+ *   runId: string, id: string, file: unknown, reason: unknown,
+ *   record: Record<string, any>, rows: ReadonlyArray<Record<string, any>>, key: Buffer,
+ *   writeRow: (row: Record<string, any>) => Promise<unknown>,
+ *   writeSigned: (runId: string, writeRow: (row: Record<string, any>) => Promise<unknown>, row: Record<string, any>) => Promise<unknown>,
+ *   io: {
+ *     owns: (owned: ReadonlyArray<string>, file: string, kinds?: Readonly<Record<string, string>>) => boolean,
+ *     loadState: (where: Record<string, any>) => {status: string, state: Record<string, any> | null, seq: number},
+ *     contentHash: (file: string) => string,
+ *     clearDone: (file: string) => boolean,
+ *   },
+ * }} opts
+ * @returns {Promise<{row: Record<string, any>, cleared: boolean, existing: boolean}>}
+ * @throws {StateError} `usage` or a refusal code (see the module doc).
+ */
+export async function reopenFile({ runId, id, file, reason, record, rows, key, writeRow, writeSigned, io }) {
+  if (typeof file !== 'string' || file.length === 0) throw new StateError('usage', 'block reopen needs --file <path>');
+  if (typeof reason !== 'string' || reason.trim().length === 0) throw new StateError('usage', 'block reopen needs --reason');
+  if (path.isAbsolute(file) || file.split('/').includes('..') || file.startsWith('./') || path.posix.normalize(file) !== file) {
+    throw new StateError('usage', '--file must be repo-root-relative');
+  }
+  const entry = openBlockEntry(record, runId, id);
+  const owned = Array.isArray(entry.owned_files) ? entry.owned_files : [];
+  if (!io.owns(owned, file, entry.owned_kinds)) throw new StateError('reopen-not-owned', `reopen-not-owned: block ${id} does not own ${file}; nothing was recorded`);
+
+  const runRows = rows.filter((r) => r?.run === runId);
+  const loaded = io.loadState({ runId, block: id, file, key, rows: runRows });
+  if (loaded.status === 'tampered') {
+    throw new StateError('reopen-tampered', `reopen-tampered: the review state of ${file} does not verify (a security event, not a stop); the owner's way out is block close --no-require-reviews; nothing was recorded`);
+  }
+  const current = io.contentHash(file);
+  /** @type {'stopped' | 'lost'} */
+  let from;
+  /** @type {string | null} */
+  let stopReason = null;
+  /** @type {string | null} */
+  let fromHash = null;
+  if (loaded.status === 'lost') {
+    from = 'lost';
+  } else if ((loaded.status === 'ok' || loaded.status === 'restored') && loaded.state?.status === 'stopped') {
+    from = 'stopped';
+    stopReason = typeof loaded.state.next?.reason === 'string' ? loaded.state.next.reason : 'stopped';
+    fromHash = stopContentHash(loaded.state, runRows, { runId, block: id, file, key });
+    if (fromHash === null) {
+      throw new StateError('reopen-same-content', `reopen-same-content: the content the stop of ${file} reviewed is unknown, so a change cannot be shown; waive its findings instead (block waive); nothing was recorded`);
+    }
+    if (fromHash === current) {
+      throw new StateError('reopen-same-content', `reopen-same-content: ${file} still has the content its stop (${stopReason}) reviewed; change the file first, or waive its findings (block waive); nothing was recorded`);
+    }
+  } else {
+    const what = loaded.status === 'none' || loaded.state === null ? 'has no review state' : `is ${loaded.state.status}`;
+    throw new StateError('reopen-not-stopped', `reopen-not-stopped: ${file} ${what}; only a stopped or lost file is reopened; nothing was recorded`);
+  }
+  if (!Number.isInteger(loaded.seq) || loaded.seq < 0) {
+    throw new StateError('reopen-tampered', `reopen-tampered: the review state of ${file} has no valid anchor seq; nothing was recorded`);
+  }
+  // one verified human row per at_seq: the same content reuses it, other content is refused
+  const earlier = latestRowAt(runRows, { runId, block: id, file, key, seq: loaded.seq });
+  if (earlier !== null && earlier.to_hash !== current) {
+    throw new StateError('reopen-already-recorded', `reopen-already-recorded: ${file} was already reopened at state seq ${loaded.seq} for other content; run review-file, or the content changed since the reopen; nothing was recorded`);
+  }
+  // C11: the cached result of the current content's ticket would repeat the stop — dropped FIRST,
+  // so a failed row write leaves at worst a re-run that returns the same stop, never a row with a
+  // stale marker
+  const cleared = io.clearDone(file);
+  if (earlier !== null) return { row: earlier, cleared, existing: true };
+  const row = { event: REOPENED_EVENT, block: id, file, from, stop_reason: stopReason, at_seq: loaded.seq, from_hash: fromHash, to_hash: current, reason: reason.trim(), by: 'human' };
+  /** @type {Record<string, any> | null} */
+  let written = null;
+  let signedOut = null;
+  /** @type {unknown} */
+  let failure = null;
+  // a thrown `undefined` (or null) is still a throw: `threw`, not the value, says the write threw
+  let threw = false;
+  try {
+    signedOut = await writeSigned(runId, async (signed) => {
+      const result = await writeRow(signed);
+      // the ledger's appendRow resolves with the row it wrote; nothing (or false) is no write
+      if (result === null || result === undefined || result === false) return result;
+      written = signed;
+      return result;
+    }, row);
+  } catch (err) {
+    written = null;
+    failure = err;
+    threw = true;
+  }
+  if (written === null || signedOut === null || signedOut === undefined || signedOut === false) {
+    // B79: the cause is kept (`cause`) and named by its code only — never a path, key or config value
+    const refused = new StateError('reopen-write-failed', `reopen-write-failed: the signed review.reopened row for ${file} was not written (${threw ? causeCode(failure) : 'no-write'}); run block reopen again`);
+    // StateError takes (code, message) only (src/state/paths.mjs is not this block's): `cause` is
+    // set here, non-enumerable like a native one, so a serializer never emits the cause's path
+    if (threw) Object.defineProperty(refused, 'cause', { value: failure, enumerable: false, configurable: true, writable: true });
+    throw refused;
+  }
+  return { row: written, cleared, existing: false };
+}

package/src/review/stop-exits.mjs

@@ -0,0 +1,15 @@
+/**
+ * B73 (issue #12): the ways out of a file the fix loop stopped (`review_cap`,
+ * `l3_patch_exhausted`, `split_required`), in this order — `block reopen` after a fix,
+ * `block waive` for each open finding, `review-file --answers` for a fix made in another owned
+ * file, or re-decompose the block. `review-file`'s `stopped` answer carries them as `exits`; the
+ * gate appends {@link stopExitsLine} to its `review_cap` and `unreviewed` detail for a stopped
+ * file. A `tampered` review state is not a stop (it is refused; the owner's way out is
+ * `block close --no-require-reviews`) and never gets them.
+ */
+
+/** @type {ReadonlyArray<string>} */
+export const STOP_EXITS = Object.freeze(['block reopen', 'block waive', 'review-file --answers', 're-decompose']);
+
+/** The one short line the gate appends to a stopped file's detail. */
+export const stopExitsLine = `exits: ${STOP_EXITS.join(', ')}`;

package/src/state/block-end.mjs

@@ -0,0 +1,290 @@
+/**
+ * B64b (issue #13): the block-end signal — a done file and the owner's `hooks.on_block_end` hook.
+ *
+ * A block ends where `src/state/block.mjs` sets its status to `closed` or `stopped`: `closeBlock`
+ * closing it, `closeBlock` stopping it (a pinned worker event or `ledger.tamper`), and `stopBlock`
+ * (`block stop`). After each end — its ledger rows written and the run lock released — the CLI
+ * (`src/cli/block.mjs`):
+ *
+ * 1. writes `<runs>/<run>/blocks/<id>.done.json` ({@link doneFilePath}) atomically (a temp file in
+ *    the same directory, then a rename; a second end overwrites it) with {@link doneFileContent}:
+ *    the block, the run, its status, the end's event and reason, the HEAD commit of the block's
+ *    tree, the block's own spend and its open findings, and the time. Never transcript text, diff
+ *    text or secrets. A failed write changes nothing but one stderr warning line.
+ * 2. runs `hooks.on_block_end` (`blockEndHook` in `config-snapshot.mjs`, from the run-start
+ *    config snapshot only — the key is immutable) once, outside the run lock: argv only (no
+ *    shell), cwd the repository top, stdin closed, stdout and stderr discarded, the parent env plus
+ *    `CODE_FORGE_RUN`, `CODE_FORGE_BLOCK`, `CODE_FORGE_BLOCK_STATUS` and `CODE_FORGE_DONE_FILE`;
+ *    its process group is killed at `timeout_s`. One signed `hook.ran` row records it (under the run lock). A hook
+ *    that fails, is missing, times out or crashes changes nothing but one stderr warning line.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { runSpend } from '../ledger/spend.mjs';
+import { readAllRows } from '../ledger/write.mjs';
+import { exec } from '../util/exec.mjs';
+import { assertRunId, runsDir } from './paths.mjs';
+import { withRunLock, writeSigned } from './run.mjs';
+
+// B64b: the hook's config reader lives next to `externalReviewer` (read by `state/block.mjs` too)
+export { HOOK_TIMEOUT_DEFAULT_S, HOOK_TIMEOUT_MAX_S, HOOK_TIMEOUT_MIN_S, blockEndHook } from './config-snapshot.mjs';
+
+/**
+ * The block's done file: `<runs>/<run>/blocks/<id>.done.json` (the run's own directory under the
+ * runs dir, next to the run record — never in the source tree).
+ * @param {string} runId @param {string} id
+ * @returns {string} an absolute path
+ */
+export function doneFilePath(runId, id) {
+  return path.resolve(runsDir(), assertRunId(runId), 'blocks', `${safeId(id)}.done.json`);
+}
+
+/** @param {string} id @returns {string} the id, refused when it could leave the blocks dir. */
+function safeId(id) {
+  if (typeof id !== 'string' || id.length === 0 || id.includes('/') || id.includes('\\') || id === '.' || id === '..' || id.includes('\0')) {
+    throw new TypeError(`block id ${JSON.stringify(id)} cannot name a done file`);
+  }
+  return id;
+}
+
+/**
+ * The done file's content, keys in this order. Pure.
+ * @param {{
+ *   block: string, runId: string, status: 'closed' | 'stopped', event: string, reason?: string | null,
+ *   commit: string | null, spend: {usd: number, unknown: number} | null, findings: number | null, at: Date,
+ * }} facts
+ * @returns {{block: string, run_id: string, status: string, event: string, reason: string | null, commit: string | null,
+ *   spent_usd: number | null, unknown_usd_sessions: number | null, findings: number | null, at: string}}
+ */
+export function doneFileContent({ block, runId, status, event, reason = null, commit, spend, findings, at }) {
+  return {
+    block,
+    run_id: runId,
+    status,
+    event,
+    reason: typeof reason === 'string' ? reason : null,
+    commit: typeof commit === 'string' && commit.length > 0 ? commit : null,
+    // a non-finite spend or a non-integer count is unknown (null) — the keys are never dropped
+    spent_usd: spend && Number.isFinite(spend.usd) ? spend.usd : null,
+    unknown_usd_sessions: spend && Number.isInteger(spend.unknown) ? spend.unknown : null,
+    findings: Number.isInteger(findings) ? findings : null,
+    at: at.toISOString(),
+  };
+}
+
+/** @param {string} cwd @returns {Promise<string | null>} HEAD of `cwd`'s repository, or null. */
+async function headCommit(cwd) {
+  try {
+    const env = {};
+    for (const [name, value] of Object.entries(process.env)) if (!name.startsWith('GIT_')) env[name] = value;
+    const res = await exec(['git', 'rev-parse', '--verify', 'HEAD'], {
+      cwd,
+      env: { ...env, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null', GIT_TERMINAL_PROMPT: '0' },
+      timeoutMs: 10000,
+    });
+    const sha = res.stdout.trim();
+    return res.result === 'ok' && /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the block's done file after an end (its ledger rows are already written). Never throws: a
+ * failure prints `warning: done file not written: <reason>` on stderr and returns null.
+ * @param {{
+ *   record: Record<string, any>, id: string, status: 'closed' | 'stopped', event: string, reason?: string | null,
+ *   openFindings: (rows: Record<string, any>[]) => Promise<number>, err: (s: string) => unknown, now?: Date,
+ * }} opts - `record` is the run record read before the end (its `workspace` and the block's
+ *   `worktree` do not change at an end); `openFindings` counts the block's open findings exactly
+ *   as `code-forge status` does.
+ * @returns {Promise<string | null>} the done file's absolute path, or null when it was not written.
+ */
+export async function writeDoneFile({ record, id, status, event, reason = null, openFindings, err, now = new Date() }) {
+  const runId = String(record?.run_id);
+  try {
+    const file = doneFilePath(runId, id);
+    /** @type {Record<string, any>[] | null} */
+    let rows = null;
+    try {
+      rows = await readAllRows(record.project);
+    } catch {
+      rows = null;
+    }
+    const spend = rows === null ? null : runSpend(rows.filter((r) => r?.block === id), runId);
+    // like the spend: unknown (null) when the rows cannot be read or the count fails — never a 0
+    /** @type {number | null} */
+    let findings = null;
+    if (rows !== null) {
+      try {
+        const n = await openFindings(rows);
+        findings = Number.isInteger(n) && n >= 0 ? n : null;
+      } catch {
+        findings = null;
+      }
+    }
+    const tree = record.blocks?.[id]?.worktree?.path;
+    const commit = await headCommit(typeof tree === 'string' && tree.length > 0 ? tree : record.workspace);
+    const content = doneFileContent({ block: id, runId, status, event, reason, commit, spend, findings, at: now });
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+      await writeFile(tmp, `${JSON.stringify(content)}\n`, { mode: 0o600 });
+      await rename(tmp, file);
+    } catch (thrown) {
+      await rm(tmp, { force: true }).catch(() => {});
+      throw thrown;
+    }
+    return file;
+  } catch (thrown) {
+    err(`warning: done file not written: ${reasonOf(thrown)}\n`);
+    return null;
+  }
+}
+
+/** @param {unknown} thrown @returns {string} a one-line reason (an error code or message). */
+function reasonOf(thrown) {
+  const any = /** @type {any} */ (thrown);
+  const text = typeof any?.code === 'string' ? any.code : typeof any?.message === 'string' ? any.message : String(thrown);
+  return text.split('\n')[0];
+}
+
+/**
+ * @typedef {{exit: number | null, signal: string | null, timedOut: boolean, notFound: boolean, error: string | null}} SpawnResult
+ */
+
+/** @param {unknown} thrown @returns {string} the error's code (`EACCES`, …), else `UNKNOWN` — never its message. */
+function errorCode(thrown) {
+  const code = /** @type {any} */ (thrown)?.code;
+  return typeof code === 'string' && /^[A-Z0-9_]{1,32}$/.test(code) ? code : 'UNKNOWN';
+}
+
+/**
+ * The warning's tail for a hook that did not exit 0 (ruling round 2 (b)), or null for a clean exit:
+ * `exit N`, `timed out`, `not found`, `signal <NAME>` or `failed to start (<code>)`.
+ * @param {SpawnResult} ran @returns {string | null}
+ */
+export function hookWarning(ran) {
+  if (ran.timedOut) return 'timed out';
+  if (ran.notFound) return 'not found';
+  if (ran.error !== null) return `failed to start (${ran.error})`;
+  if (typeof ran.exit === 'number') return ran.exit === 0 ? null : `exit ${ran.exit}`;
+  if (typeof ran.signal === 'string') return `signal ${ran.signal}`;
+  return 'failed to start (UNKNOWN)';
+}
+
+/**
+ * Spawn the hook: no shell, stdin closed, stdout and stderr discarded, its own process group,
+ * killed (the whole group) at the timeout.
+ * @param {string[]} argv @param {{cwd: string, env: NodeJS.ProcessEnv, timeoutMs: number}} opts
+ * `notFound` is an ENOENT for `argv[0]` itself; every other spawn error (a missing cwd included —
+ * Node names `argv[0]` in that ENOENT too, so the cwd is checked first) is `error`, its code.
+ * @returns {Promise<SpawnResult>}
+ */
+async function spawnHook(argv, { cwd, env, timeoutMs }) {
+  try {
+    if (!(await stat(cwd)).isDirectory()) return { exit: null, signal: null, timedOut: false, notFound: false, error: 'ENOTDIR' };
+  } catch (thrown) {
+    return { exit: null, signal: null, timedOut: false, notFound: false, error: errorCode(thrown) };
+  }
+  return new Promise((resolve) => {
+    let timedOut = false;
+    let settled = false;
+    /** @type {NodeJS.Timeout | undefined} */
+    let timer;
+    const done = (/** @type {SpawnResult} */ r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(r);
+    };
+    const failed = (/** @type {unknown} */ thrown) => {
+      const any = /** @type {any} */ (thrown);
+      const notFound = any?.code === 'ENOENT' && (any?.path === undefined || any.path === argv[0]);
+      done({ exit: null, signal: null, timedOut: false, notFound, error: notFound ? null : errorCode(thrown) });
+    };
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), { cwd, env, shell: false, detached: true, stdio: ['ignore', 'ignore', 'ignore'] });
+    } catch (thrown) {
+      failed(thrown);
+      return;
+    }
+    const pid = child.pid;
+    child.on('error', failed);
+    child.on('close', (code, signal) => done({ exit: code, signal: signal ?? null, timedOut, notFound: false, error: null }));
+    timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        if (typeof pid === 'number' && pid > 1) process.kill(-pid, 'SIGKILL');
+        else child.kill('SIGKILL');
+      } catch {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          // already gone
+        }
+      }
+    }, timeoutMs);
+  });
+}
+
+/**
+ * Run `hooks.on_block_end` once for an end, outside the run lock, then write one signed `hook.ran`
+ * row under it (also when the hook failed, timed out or was not found). Never throws, never prints
+ * on stdout; a hook that did not exit 0 prints one `warning: on_block_end hook <tail>` line on
+ * stderr ({@link hookWarning}). `doneFile` is the empty string when the done file was not written.
+ * @param {{
+ *   hook: {argv: string[], timeoutS: number}, runId: string, id: string, status: string, doneFile: string,
+ *   repoTop: string, writeRow: (row: Record<string, any>) => Promise<unknown>, err: (s: string) => unknown,
+ * }} opts
+ * @returns {Promise<Record<string, any> | null>} the row written (unsigned fields), or null when none was.
+ */
+export async function runBlockEndHook({ hook, runId, id, status, doneFile, repoTop, writeRow, err }) {
+  const env = {
+    ...process.env,
+    CODE_FORGE_RUN: runId,
+    CODE_FORGE_BLOCK: id,
+    CODE_FORGE_BLOCK_STATUS: status,
+    CODE_FORGE_DONE_FILE: doneFile,
+  };
+  const started = process.hrtime.bigint();
+  /** @type {SpawnResult} */
+  let ran;
+  // "failed to start" covers the spawn only; a later failure gets neutral wording below
+  try {
+    ran = await spawnHook(hook.argv, { cwd: repoTop, env, timeoutMs: hook.timeoutS * 1000 });
+  } catch (thrown) {
+    ran = { exit: null, signal: null, timedOut: false, notFound: false, error: errorCode(thrown) };
+  }
+  try {
+    const durationMs = Math.round(Number(process.hrtime.bigint() - started) / 1e6);
+    const warning = hookWarning(ran);
+    if (warning !== null) err(`warning: on_block_end hook ${warning}\n`);
+    const row = {
+      event: 'hook.ran',
+      block: id,
+      hook: 'on_block_end',
+      argv0: path.basename(hook.argv[0]),
+      exit: ran.exit,
+      signal: ran.signal,
+      timed_out: ran.timedOut,
+      duration_ms: durationMs,
+    };
+    try {
+      // clause 2: the hook.ran row is appended UNDER the run lock (writeSigned alone takes no lock)
+      await withRunLock(runId, () => writeSigned(runId, writeRow, row));
+    } catch (thrown) {
+      // an error code only, never raw message text
+      err(`warning: on_block_end hook row not written (${errorCode(thrown)})\n`);
+      return null;
+    }
+    return row;
+  } catch (thrown) {
+    err(`warning: on_block_end hook not recorded (${errorCode(thrown)})\n`);
+    return null;
+  }
+}