@codedology/code-forge 0.12.0 → 0.13.0

package/src/cli/block.mjs

@@ -193,6 +193,7 @@
  * through `closeBlock`'s `extraChecks`.
  */
 
+import { statSync } from 'node:fs';
 import { readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { parse as parseYAML } from 'yaml';
@@ -201,6 +202,7 @@ import { fallbackLane } from '../decide/fallback-rules.mjs';
 import { laneFacts } from '../decide/lane-facts.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { attemptBlock, claimPath, closeBlock, openBlock, rebaseBlock, repoTop, stopBlock } from '../state/block.mjs';
+import { lastGate } from '../state/brief-status.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
 import { configInForce, externalReviewer, requireCoderTests } from '../state/config-snapshot.mjs';
 import { StateError } from '../state/paths.mjs';
@@ -288,6 +290,24 @@ const USAGE =
   '       every block verb takes --json: one JSON line on stdout ({"block","event",…}) instead of the text\n';
 
 const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive', 'reopen'];
+
+/** Refuse likely shell quoting slips before any row is written.
+ * @param {string} workspace @param {string[]} entries @param {string} label
+ */
+function checkWhitespacePaths(workspace, entries, label) {
+  for (const entry of entries) {
+    if (!/\s/u.test(entry)) continue;
+    let stat;
+    try {
+      stat = statSync(path.join(workspace, entry));
+    } catch {
+      // A missing or unreadable path cannot establish a literal whitespace-containing name.
+    }
+    if (!stat?.isFile() && !stat?.isDirectory()) {
+      throw new StateError(label === 'owned files' ? 'bad-owned' : 'bad-tests', `${label}: invalid path ${JSON.stringify(entry)}: contains whitespace but names no existing file or directory`);
+    }
+  }
+}
 const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript', 'kind', 'report'];
 
 /**
@@ -345,6 +365,10 @@ 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);
+    if (sub === 'open') {
+      checkWhitespacePaths(record.workspace, /** @type {string[]} */ (flags.owned), 'owned files');
+      if (Array.isArray(flags.tests)) checkWhitespacePaths(record.workspace, flags.tests, 'test files');
+    }
     // B80: waive and reopen are the human's — asked at a terminal before anything is written (not
     // even the autopilot expiry rows below); no terminal is exit 2, a "no" is exit 1
     if (sub === 'waive' || sub === 'reopen') {
@@ -761,6 +785,9 @@ export async function runBlock(args, deps = {}) {
         // 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) {
+          if (configInForce(record)?.gates?.test != null && lastGate(rows.filter((row) => row.block === id)).result !== 'pass') {
+            err(`WARN block ${id}: no green gates run for this block; run gates run --run ${runId} --block ${id} before close\n`);
+          }
           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) {

package/src/cli/context.mjs

@@ -16,7 +16,8 @@
  * `<block>.md`. A row that cannot be appended removes only the temp file, so an earlier pack stays
  * as it was and nothing was written. A rename that fails after the row was appended says so.
  *
- * Exit codes: 0 written, 1 refused (no `context` key, a rules or lessons file missing or outside
+ * With no `context` key, the pack holds only the block header and built-in proof rule (300 lines).
+ * Exit codes: 0 written, 1 refused (a rules or lessons file missing or outside
  * the repository, a bad `context` value, a control character, an unknown run or block, a file or
  * ledger write that fails), 2 usage. Never runs any command it lists.
  */
@@ -94,7 +95,7 @@ export async function runContext(args, deps = {}) {
     if (!loaded.ok) throw new ContextError('bad-config', loaded.message);
     const live = /** @type {Record<string, any>} */ (loaded.config);
     const settings = contextSettings(live);
-    if (settings === null) throw new ContextError('no-context', 'the config has no context key: add context (rules, lessons, commands, max_lines) to .code-forge.yml');
+    if (settings === null && Object.hasOwn(live, 'context')) throw new ContextError('bad-context', 'context must be a mapping');
     const sources = readSources(repoRoot, settings);
     const { text, lines, cut } = assemblePack({
       settings,

package/src/cli/review-file.mjs

@@ -69,7 +69,7 @@
 
 import { readFileSync, realpathSync, rmSync } from 'node:fs';
 import path from 'node:path';
-import { answersTicketId, assertAnswers, blockTickets, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
+import { answersTicketId, assertAnswers, blockTickets, deliverBlockFindings, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
 import { assertBlockId, assertInsideRoot, assertTicketId, contentHash, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
 import { blockFileSet, namedOnHash } from '../review/gate-check.mjs';
 import { STOP_EXITS } from '../review/stop-exits.mjs';
@@ -391,21 +391,22 @@ async function waitBlockScope(repoRoot, cwd, run, block) {
 }
 
 /** A block wait reads only the marker, never review results or the signing key.
- * @param {string} repoRoot @param {string} ticket @returns {boolean}
+ * @param {string} repoRoot @param {string} ticket @returns {Record<string, any> | null}
  */
-function blockTicketDone(repoRoot, ticket) {
+function blockTicketMarker(repoRoot, ticket) {
   try {
     const marker = JSON.parse(readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`), 'utf8'));
-    if (marker?.ticket === ticket && typeof marker.status === 'string' && marker.status.length > 0) return true;
+    if (marker?.ticket === ticket && typeof marker.status === 'string' && marker.status.length > 0) return marker;
   } catch (err) {
-    if (err.code === 'ENOENT') return false;
+    if (err.code === 'ENOENT') return null;
   }
   throw new WorkerError('result-unreadable', 'a ticket completion marker cannot be read');
 }
 
 /**
- * Join current-content tickets only. Re-scan on every poll, including before returning done,
- * so a file edited while waiting gets a new ticket. The worker alone finishes old tickets.
+ * A block wait reads only completion/delivery markers, never review results or the signing key.
+ * Re-scan current content on every poll. Deliver unseen findings of the newest earlier ticket
+ * before rechecking a blind edit; the next join queues the fix. Stopped files stay finished.
  * @param {{repoRoot: string, cwd: string, block: string, run: string, maxMs: number, pollMs: number, say: (obj: Record<string, any>) => unknown}} opts
  */
 async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say }) {
@@ -413,6 +414,7 @@ async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say }) {
   const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree: realpathSync(tree) };
   const deadline = Date.now() + maxMs;
   let downPolls = 0;
+  const deliveredHere = new Set();
   for (;;) {
     const worker = liveWorker(repoRoot);
     const live = worker?.run === run;
@@ -424,17 +426,28 @@ async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say }) {
       const { ticket } = resolveTicket(opts);
       const previous = tickets.filter((t) => t.file === file);
       let present = previous.find((t) => t.ticket === ticket);
+      if (!present && previous.length > 0) {
+        const newest = previous[previous.length - 1];
+        const marker = blockTicketMarker(repoRoot, newest.ticket);
+        if (marker?.status === 'stopped') return { file, ticket: newest.ticket, status: 'done' };
+        if (marker?.status === 'reviewed' && marker.open_findings === true && live) {
+          if (deliveredHere.has(newest.ticket) || deliverBlockFindings({ repoRoot, block, file, ticket: newest.ticket })) {
+            deliveredHere.add(newest.ticket);
+            return { file, ticket: newest.ticket, status: 'findings' };
+          }
+        }
+      }
       if (!present && previous.length > 0 && live) {
         enqueue(opts);
         present = { ...previous[previous.length - 1], ticket };
       }
-      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : blockTicketDone(repoRoot, ticket) ? 'done' : 'pending' };
+      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : blockTicketMarker(repoRoot, ticket) ? 'done' : 'pending' };
     });
     if (downPolls >= 2) {
       say({ block, files, done: false, status: 'worker_down' });
       return 3;
     }
-    if (live && files.every((f) => f.status === 'done')) {
+    if (live && files.every((f) => f.status === 'done' || f.status === 'findings')) {
       say({ block, files, done: true });
       return 0;
     }

package/src/cli/review.mjs

@@ -48,7 +48,7 @@ import { semaphore } from '../util/locks.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { isAlive, listEntries, readStartTime, UNKNOWN_START_TIME } from '../util/reaper.mjs';
 import { pidsDir, runRoot, setRunRoot, tmpBase } from '../util/tmp.mjs';
-import { readWorker } from '../worker/queue.mjs';
+import { liveWorker } from '../worker/queue.mjs';
 import { gitChildEnv, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
 
 const BIN = fileURLToPath(new URL('../../bin/code-forge.mjs', import.meta.url));
@@ -288,7 +288,7 @@ async function runWorkers(repoRoot, runId) {
   } catch {
     // no record: nothing pinned
   }
-  const w = readWorker(repoRoot);
+  const w = liveWorker(repoRoot);
   if (w?.run === runId && !found.some((f) => f.pid === w.pid)) {
     found.push({ pid: w.pid, same: async () => w.start_time === UNKNOWN_START_TIME || readStartTime(w.pid) === w.start_time });
   }

package/src/context/pack.mjs

@@ -59,7 +59,7 @@ export const DIGEST_LESSONS_HEADING = '### lessons';
  * A refusal with a stable `code`. Thrown here: `bad-context` (a bad `context` value),
  * `control-character` (in a path or a header value), `outside`, `missing` (ENOENT), `unreadable`
  * (any other lstat or read error, with its code), `not-file`. Thrown by `src/cli/context.mjs`:
- * `no-block`, `bad-config`, `no-context`, `no-run-root`, `write-failed`.
+ * `no-block`, `bad-config`, `no-run-root`, `write-failed`.
  */
 export class ContextError extends Error {
   /** @param {string} code @param {string} message */
@@ -216,11 +216,12 @@ function readLines(repoRoot, rel, key) {
 
 /**
  * Every rules file and the lessons file, read. A missing or outside file is a refusal.
- * @param {string} repoRoot @param {ContextSettings} settings
+ * @param {string} repoRoot @param {ContextSettings | null} settings
  * @returns {{rules: Array<{path: string, lines: string[]}>, lessons: {path: string, lines: string[]} | null}}
  * @throws {ContextError}
  */
 export function readSources(repoRoot, settings) {
+  if (settings === null) return { rules: [], lessons: null };
   const rules = settings.rules.map((rel) => ({ path: rel, lines: readLines(repoRoot, rel, 'context.rules') }));
   const lessons = settings.lessons === null ? null : { path: settings.lessons, lines: readLines(repoRoot, settings.lessons, 'context.lessons') };
   return { rules, lessons };
@@ -249,7 +250,8 @@ export const argvText = (argv) => argv.map(argvToken).join(' ');
 
 /**
  * Build the pack text for a block (pure over what it is given).
- * @param {{settings: ContextSettings, sources: ReturnType<typeof readSources>, block: PackBlock}} opts
+ * Missing settings give a header and proof rule only, with the default line cap.
+ * @param {{settings: ContextSettings | null, sources: ReturnType<typeof readSources>, block: PackBlock}} opts
  * @returns {{text: string, lines: number, cut: number}} `cut`: the lines dropped.
  * @throws {ContextError} `control-character` when a header value holds one.
  */
@@ -267,11 +269,13 @@ export function assemblePack({ settings, sources, block }) {
     for (const f of block.tests) header.push(`- ${f}`);
   }
   if (block.worktree) header.push(`worktree: ${block.worktree.path}`, `branch: ${block.worktree.branch}`);
-  header.push('## commands (never run by code-forge)');
-  const keys = COMMAND_KEYS.filter((k) => Object.hasOwn(settings.commands, k));
-  if (keys.length === 0) header.push('(none)');
-  // a command line can name a secret (a token in an argv): it is redacted as rules and lessons are
-  for (const k of keys) header.push(`${k}: ${redact(argvText(settings.commands[k]))}`);
+  if (settings !== null) {
+    header.push('## commands (never run by code-forge)');
+    const keys = COMMAND_KEYS.filter((k) => Object.hasOwn(settings.commands, k));
+    if (keys.length === 0) header.push('(none)');
+    // a command line can name a secret (a token in an argv): it is redacted as rules and lessons are
+    for (const k of keys) header.push(`${k}: ${redact(argvText(settings.commands[k]))}`);
+  }
 
   header.push(...splitLines(PROOF_RULE));
 
@@ -282,7 +286,7 @@ export function assemblePack({ settings, sources, block }) {
   const total = () => header.length + sections.reduce((n, s) => n + 1 + s.body.length + (s.dropped > 0 ? 1 : 0), 0);
   // cut order: the lessons first, then the rules from the last file backwards
   for (const s of [...sections].reverse()) {
-    let excess = total() - settings.maxLines;
+    let excess = total() - (settings?.maxLines ?? DEFAULT_MAX_LINES);
     if (excess <= 0) break;
     // the marker takes one line: a section is only cut when that leaves it shorter
     if (s.body.length < 2) continue;

package/src/doctor/index.mjs

@@ -13,7 +13,7 @@ import path from 'node:path';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { newRunId } from '../state/paths.mjs';
 import { runRoot } from '../util/tmp.mjs';
-import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkReviewState, checkTmp, checkTools } from './local.mjs';
+import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkLocks, checkReviewConcurrency, checkReviewState, checkTmp, checkTools } from './local.mjs';
 import { checkCoderSandbox, configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
 import { row } from './rows.mjs';
 import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
@@ -67,6 +67,7 @@ export async function runDoctor(opts = {}, deps = {}) {
   };
   rows.push(...(await checkTools(toolOpts)));
   rows.push(...(await checkLedger()));
+  rows.push(...(await checkLocks()));
   rows.push(...checkTmp(cfg));
   rows.push(...(await checkReviewState(cfg)));
   rows.push(checkReviewConcurrency(cfg));

package/src/doctor/local.mjs

@@ -25,13 +25,32 @@ import { assertRunId, runsDir } from '../state/paths.mjs';
 import { readRun } from '../state/run.mjs';
 import { loadKey } from '../state/signer.mjs';
 import { listEntries } from '../util/reaper.mjs';
+import { listBadLocks } from '../util/file-locks.mjs';
 import { ownerState, runRootPath, tmpBase } from '../util/tmp.mjs';
 import { parallelTickets } from '../worker/loop.mjs';
+import { workerRegistry } from '../worker/queue.mjs';
+import { mainRootOf } from '../worker/ticket.mjs';
 import { missingStateFiles } from '../worker/review-state.mjs';
 import { row } from './rows.mjs';
 
 /** @typedef {import('./rows.mjs').Row} Row */
 
+/** @param {string} [cwd] @returns {Promise<Row[]>} */
+export async function checkLocks(cwd = process.cwd()) {
+  try {
+    const paths = listBadLocks();
+    const rows = paths.length === 0
+      ? [row('locks', 'OK', 'locks', 'no unreadable or malformed locks')]
+      : paths.map((file) => row('locks', 'WARN', 'locks', file));
+    let repoRoot = cwd;
+    try { repoRoot = await mainRootOf(cwd); } catch { /* non-repository doctor */ }
+    rows.push(...workerRegistry(repoRoot).filter((entry) => entry.worker === null).map((entry) => row('worker-registry', 'WARN', 'worker registry', entry.file)));
+    return rows;
+  } catch (err) {
+    return [row('locks', 'WARN', 'locks', `could not list locks (${err?.code ?? 'error'})`)];
+  }
+}
+
 /** The ids of the `--quick` rows, in print order. */
 export const QUICK_IDS = Object.freeze(['config', 'links', 'keys']);
 

package/src/doctor/worker-probe.mjs

@@ -11,8 +11,9 @@
  * MAC is tamper evidence within ordinary tool use, never a boundary against a same-user process.
  */
 
-import { copyFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { copyFileSync, mkdirSync, readdirSync, rmSync, symlinkSync } from 'node:fs';
 import path from 'node:path';
+import { commandOnPath } from '../install/detect.mjs';
 import { runsDir } from '../state/paths.mjs';
 import { startRun } from '../state/run.mjs';
 import { loadKey, signRow, verifyRow } from '../state/signer.mjs';
@@ -94,7 +95,19 @@ export async function probeWorkerAndSigner(ctx) {
     const signerOk = verifyRow(signed, key).ok && verifyRow(flipped, key).reason === 'mismatch';
     rows.push(row('signer-key', signerOk ? 'OK' : 'FAIL', 'signer key', signerOk ? 'generated; a signed row verifies, a changed one is refused' : 'sign/verify round trip failed'));
 
-    const started = await launchWorker({ runId, workspace: repo, env });
+    // The boot lock needs ps even with a restricted provider PATH. Expose just that utility.
+    let workerEnv = env;
+    if (!await commandOnPath('ps', { pathEnv: env.PATH ?? '' })) {
+      const tools = path.join(repo, 'worker-tools');
+      for (const systemDir of ['/bin', '/usr/bin']) {
+        if (!await commandOnPath('ps', { pathEnv: systemDir })) continue;
+        mkdirSync(tools, { mode: 0o700 });
+        symlinkSync(path.join(systemDir, 'ps'), path.join(tools, 'ps'));
+        workerEnv = { ...env, PATH: [env.PATH, tools].filter(Boolean).join(path.delimiter) };
+        break;
+      }
+    }
+    const started = await launchWorker({ runId, workspace: repo, env: workerEnv });
     pid = started.pid;
     registerPid(pidsDir(ctx.runRootDir), pid, 'code-forge worker'); // a killed doctor's worker is reaped by the next sweep
     const announced = liveWorker(started.repoRoot)?.pid === pid;

package/src/ledger/spend.mjs

@@ -12,7 +12,7 @@
  */
 
 import { logWarning } from '../util/error-log.mjs';
-import { keyedLock } from '../util/locks.mjs';
+import { withLock } from '../util/file-locks.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { estimateCostUsd } from './prices.mjs';
 
@@ -199,7 +199,7 @@ export const SPEND_UNREADABLE_MESSAGE = "budget.usd is set but the run's spend c
  * Several sessions of one run can start at once (B40 slots, B42 ticket pool). The ledger only
  * learns a session's cost when its row is written, so a plain "spent < budget" check lets every
  * session that starts before the first row lands go through. Instead the check AND a reservation
- * of the session's estimated cost happen under ONE in-process lock per run (`withBudgetLock`):
+ * of the session's estimated cost happen under ONE cross-process lock per run (`withBudgetLock`):
  *
  *   spent ≥ budget, or spent + reserved + estimate > budget ⇒ refused (the B33 message, unchanged)
  *
@@ -275,7 +275,7 @@ export function reserveBudget(run, usd) {
  */
 export function withBudgetLock(run, fn) {
   lockCalls += 1;
-  return keyedLock(`budget:${run}`, fn);
+  return withLock(`budget:${run}`, fn);
 }
 
 /** Test spy: how many times {@link withBudgetLock} was entered since the last reset. */

package/src/proof/lock.mjs

@@ -150,7 +150,11 @@ export async function runGatesGuarded({ runId, blockId, gates, cwd, timeoutMs, t
     blockId,
     fn: async () => {
       // Plain gates without --changed need no scope or baseline.
-      if (!hasScopeItem(gates) && !changed) return runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
+      if (!hasScopeItem(gates) && !changed) {
+        const record = await readRun(runId);
+        const ran = await runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
+        return { ...ran, ledger_slug: slug ?? record.project };
+      }
       // the slot checked the block is open; it may still be gone by the time it is read again
       const record = await readRun(runId);
       const block = record.blocks?.[blockId];

package/src/review/gate-check.mjs

@@ -16,7 +16,7 @@
  *    session really reviewed these bytes; a repeated stop or an `unavailable` result never counts),
  *    the latest refusal row for the hash is signed, carries `content_hash` (a hash-less one does
  *    not qualify, though it still refuses) and names at least one finding, and every finding it
- *    names and every open id of the file's `review.cap` rows is cleared by a waiver the gate
+ *    names and every open id of the file's unsuperseded `review.cap` rows is cleared by a waiver the gate
  *    accepts (the same rule as below: a critical only by `by: human`). Such a file is never
  *    approved; the close writes one signed `gate.review_waived_all` row for it ({@link reviewGateCheck});
  *  - `unsigned`:   the file's approvals for that hash exist but none carries a valid MAC;
@@ -43,7 +43,8 @@
  *  - `review_cap`: a file stopped at `review_cap` has an open finding with no signed
  *    `review.waived {by: human}` row — unless a signed approval of the file's current hash comes
  *    AFTER the cap row (ledger order) and no later refusal row made it stale (the human fixed it
- *    by hand and it was reviewed); a finding already refused as `not_approved` for that file is
+ *    by hand and it was reviewed), or a verified human reopen after the cap is followed by a
+ *    signed review round of the current bytes; a finding already refused as `not_approved` for that file is
  *    not repeated. B73: this detail, and an `unreviewed` detail for a file with a cap row, ends
  *    with the stop's ways out (`exits: block reopen, block waive, review-file --answers,
  *    re-decompose`, `stop-exits.mjs`);
@@ -137,7 +138,7 @@ export function checkBlockReviews({ block, runId, files, rows, key, transcript =
   /** @type {Map<string, string>} */
   const current = new Map();
   for (const f of [...proofFiles, ...files]) current.set(f.file, f.content_hash);
-  const { mine, latestOf, signedOf, matches, waiverOf, waiverFor, waivedAllOf, recordedRefusalSeverity } = reviewRules({ block, runId, rows, key, resultFiles, current });
+  const { mine, latestOf, signedOf, matches, waiverOf, waiverFor, waivedAllOf, recordedRefusalSeverity, supersededCap } = reviewRules({ block, runId, rows, key, resultFiles, current });
   /** @type {Refusal[]} */
   const refusals = [];
   const approvedFor = (/** @type {string} */ file, /** @type {string} */ hash) => mine.filter((r) => r.event === 'review.approved' && r.file === file && r.content_hash === hash);
@@ -216,6 +217,7 @@ export function checkBlockReviews({ block, runId, files, rows, key, transcript =
   }
 
   for (const cap of mine.filter((r) => r.event === 'review.cap')) {
+    if (supersededCap(cap)) continue;
     const hash = hashOf.get(cap.file);
     // honoured unless a signed approval of the current content comes AFTER the cap and is not stale
     if (hash !== undefined) {
@@ -260,6 +262,16 @@ function reviewRules({ block, runId, rows, key, resultFiles = {}, current, verif
   // namedOnHash}), which has no key and can only refuse; it then reads no autopilot waiver
   const ok = verify ?? ((/** @type {Record<string, any>} */ r) => verified(r, key));
   const mine = rows.filter((r) => r?.block === block && (runId === undefined || r.run === undefined || r.run === runId));
+  /** A human reopen followed by a real review of the current bytes clears older cap ids.
+   * @param {Record<string, any>} cap @returns {boolean}
+   */
+  const supersededCap = (cap) => {
+    const hash = current.get(cap.file);
+    if (hash === undefined) return false;
+    const at = mine.indexOf(cap);
+    return mine.some((r, i) => i > at && r.event === 'review.reopened' && r.run === runId && r.file === cap.file && r.by === 'human' && ok(r)
+      && mine.some((round, j) => j > i && round.event === 'review.round' && round.run === runId && round.file === cap.file && round.content_hash === hash && ok(round)));
+  };
   /**
    * B52: the index of the last signed approval and the latest refusal AFTER it for (file, hash);
    * `denial` is null when that approval stands (or there is none — `unreviewed` / `unsigned` say
@@ -380,7 +392,7 @@ function reviewRules({ block, runId, rows, key, resultFiles = {}, current, verif
   };
 
   /**
-   * B79: the ids every signed `review.cap` row for (file, hash) names. A cap row records no
+   * B79: the ids every unsuperseded signed `review.cap` row for (file, hash) names. A cap row records no
    * severity, so the rules read each of these ids at {@link recordedRefusalSeverity} — also when
    * that cap row is the latest refusal (its own null never stands for them).
    * @param {string} file @param {string} hash @returns {Set<string>}
@@ -390,6 +402,7 @@ function reviewRules({ block, runId, rows, key, resultFiles = {}, current, verif
     const ids = new Set();
     for (const cap of mine) {
       if (cap.event !== 'review.cap' || cap.file !== file || cap.content_hash !== hash || !Array.isArray(cap.open) || !ok(cap)) continue;
+      if (supersededCap(cap)) continue;
       for (const id of cap.open) if (typeof id === 'string' && id.length > 0) ids.add(id);
     }
     return ids;
@@ -400,7 +413,7 @@ function reviewRules({ block, runId, rows, key, resultFiles = {}, current, verif
    * or null when no such review qualifies. All of: a signed `review.round` row for (file, hash) — a
    * session reviewed these bytes; the latest refusal row for (file, hash) is signed, carries
    * `content_hash: hash` (a hash-less one never qualifies) and names at least one finding. The ids
-   * are every finding it names and every open id of the file's `review.cap` rows. Severities: an id
+   * are every finding it names and every open id of the file's unsuperseded `review.cap` rows. Severities: an id
    * a signed `review.cap` row at (file, hash) names ({@link capIdsAt}) — also when that cap row is
    * the latest refusal — and any other open cap id use {@link recordedRefusalSeverity}, whose
    * `unknown` (no signed refusal at `hash` records one) is the human's alone and never answered.
@@ -417,6 +430,7 @@ function reviewRules({ block, runId, rows, key, resultFiles = {}, current, verif
     const named = new Map(latest.open.map((f) => [f.id, f.severity]));
     for (const id of capIdsAt(file, hash)) named.set(id, recordedRefusalSeverity(file, hash, id));
     for (const cap of mine.filter((r) => r.event === 'review.cap' && r.file === file)) {
+      if (supersededCap(cap)) continue;
       if (!Array.isArray(cap.open) || !cap.open.every((/** @type {unknown} */ id) => typeof id === 'string' && id.length > 0)) return null;
       for (const id of cap.open) if (!named.has(id)) named.set(id, recordedRefusalSeverity(file, hash, id));
     }
@@ -477,7 +491,7 @@ function reviewRules({ block, runId, rows, key, resultFiles = {}, current, verif
     return new Map([...named].filter(([id, severity]) => id !== PROOF_FINDING && answerableSeverity(severity) && waiverOf(file, id, severity, ticket).by === null));
   };
 
-  return { mine, latestOf, signedOf, matches, waiverOf, waiverFor, waivedAllOf, openAt, answerRows, recordedRefusalSeverity };
+  return { mine, latestOf, signedOf, matches, waiverOf, waiverFor, waivedAllOf, openAt, answerRows, recordedRefusalSeverity, supersededCap };
 }
 
 /**
@@ -1045,7 +1059,18 @@ export function reviewGateCheck(load, { onWaivedAll } = {}) {
       onWaivedAll?.(result.waivedAll);
       return { ok: true };
     }
-    return { ok: false, reason: result.refusals.map((r) => `${r.code}${r.file ? ` ${r.file}` : ''}${r.finding ? ` ${r.finding}` : ''}`).join('; ') };
+    const reasons = [];
+    const transcriptIds = new Set();
+    for (const r of result.refusals) {
+      const hit = r.code === 'rule_break' && /^transcript line \d+: (.+)$/.exec(r.detail);
+      if (hit) {
+        if (transcriptIds.has(hit[1])) continue;
+        transcriptIds.add(hit[1]);
+        if (transcriptIds.size <= 5) reasons.push(`rule_break ${r.detail}`);
+      } else reasons.push(`${r.code}${r.file ? ` ${r.file}` : ''}${r.finding ? ` ${r.finding}` : ''}`);
+    }
+    if (transcriptIds.size > 5) reasons.push(`+${transcriptIds.size - 5} more rule_break`);
+    return { ok: false, reason: reasons.join('; ') };
   };
 }
 

package/src/review/schema-fallback.mjs

@@ -59,7 +59,7 @@
  * Concurrency: the worker never runs two tickets for one (block, file) at once (its file lock,
  * `worker/loop.mjs`), and round 1, its retry, every recheck and the patch_check of a file are all
  * tickets for that file, so one packet's history is read and written by one ticket at a time. The
- * read-history → write-mark section here also runs under an in-process lock per (packet hash,
+ * read-history → write-mark section here also runs under a cross-process lock per (packet hash,
  * level, role), so even the same file in two blocks cannot take a packet's one try twice.
  *
  * No ledger writer (`writeRow` absent) ⇒ nothing is logged and nothing is tried. The helpers never
@@ -71,7 +71,7 @@ import { createHash } from 'node:crypto';
 import { closedBookRefused, openBookCodexAllowed } from '../config/closed-book.mjs';
 import { resolveLevel } from '../config/known-ids.mjs';
 import { logWarning } from '../util/error-log.mjs';
-import { keyedLock } from '../util/locks.mjs';
+import { withLock } from '../util/file-locks.mjs';
 import { schemaErrorsOf } from './validate-review.mjs';
 
 /** Broken results (B91: schema misses and timeouts) of the level's own ladder on one packet before the second level is tried. */
@@ -291,7 +291,7 @@ export async function afterSchemaMiss({ res, session, packetText, cfg, allowed,
   /** @type {{cfg: Record<string, any>, to: {level: string, provider: string, model: string}} | null} */
   let go = null;
   try {
-    go = await keyedLock(`schema-fallback\0${hash}\0${session.level}\0${session.role}`, async () => {
+    go = await withLock(`schema-fallback\0${hash}\0${session.level}\0${session.role}`, async () => {
       // the history is read BEFORE a schema miss is logged: failures = signed earlier misses + this
       // one. A timeout's note is already in it (B91): it is the miss in hand, never added twice.
       let seen = null;

package/src/util/file-locks.mjs

@@ -0,0 +1,118 @@
+/** Cross-process locks, with FIFO serialization inside this process. */
+import { createHash } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { processStartTime } from '../state/run.mjs';
+import { keyedLock } from './locks.mjs';
+
+/** @typedef {{probe?: typeof processStartTime, alive?: (pid: number) => boolean, afterRead?: () => Promise<unknown>, pollMs?: number}} LockOpts */
+/** @typedef {{ok: true, release: () => void} | {ok: false, result: 'held'}} LockResult */
+/** @type {{ok: false, result: 'held'}} */
+const HELD = { ok: false, result: 'held' };
+const locksDir = () => path.join(os.homedir(), '.code-forge', 'locks');
+/** @param {string} key */
+const lockPath = (key) => path.join(locksDir(), `${createHash('sha256').update(key).digest('hex')}.lock`);
+/** @type {Promise<string | null> | undefined} */
+let selfStart;
+
+/** @param {number} pid */
+function alive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (err) { return err.code !== 'ESRCH'; }
+}
+
+/** @param {Buffer} bytes @returns {{key: string, pid: number, start: string} | null} */
+function ownerOf(bytes) {
+  try {
+    const owner = JSON.parse(bytes.toString('utf8'));
+    return owner && typeof owner.key === 'string' && Number.isInteger(owner.pid) && owner.pid > 1 && typeof owner.start === 'string' ? owner : null;
+  } catch { return null; }
+}
+
+/** Exclusive creation; release synchronously removes only this owner's bytes.
+ * @param {string} file @param {Buffer} bytes @returns {LockResult}
+ */
+function create(file, bytes) {
+  let fd;
+  try { fd = openSync(file, 'wx', 0o600); }
+  catch (err) { if (err.code === 'EEXIST') return HELD; throw err; }
+  try { writeFileSync(fd, bytes); }
+  finally { closeSync(fd); }
+  let released = false;
+  return { ok: true, release() {
+    if (released) return;
+    released = true;
+    try { if (readFileSync(file).equals(bytes)) unlinkSync(file); }
+    catch { /* missing, unreadable or replaced: leave it alone */ }
+  } };
+}
+
+/** Take a key or fail closed. A proven dead owner permits one guarded break attempt.
+ * @param {string} key @param {LockOpts} [opts] @returns {Promise<LockResult>}
+ */
+export async function tryLock(key, opts = {}) {
+  const probe = opts.probe ?? processStartTime;
+  const start = await (selfStart ??= processStartTime(process.pid));
+  if (typeof start !== 'string') throw new Error('cannot determine lock owner process start time');
+  const file = lockPath(key);
+  const bytes = Buffer.from(JSON.stringify({ key, pid: process.pid, start }));
+  mkdirSync(locksDir(), { recursive: true, mode: 0o700 });
+  const initial = create(file, bytes);
+  if (initial.ok) return initial;
+  let seen;
+  try { seen = readFileSync(file); }
+  catch { return HELD; }
+  await opts.afterRead?.();
+  const owner = ownerOf(seen);
+  if (owner === null || owner.key !== key) return HELD;
+  let dead = !(opts.alive ?? alive)(owner.pid);
+  if (!dead) {
+    const actual = await probe(owner.pid);
+    dead = actual !== null && actual !== owner.start;
+  }
+  if (!dead) return HELD;
+
+  // Only unchanged dead-owner bytes may be removed under the per-key break mutex.
+  const mutex = `${file}.break`;
+  let guard;
+  try { guard = openSync(mutex, 'wx', 0o600); }
+  catch { return HELD; }
+  try {
+    writeFileSync(guard, bytes);
+    try { if (!readFileSync(file).equals(seen)) return HELD; }
+    catch { return HELD; }
+    unlinkSync(file);
+    return create(file, bytes);
+  } finally {
+    closeSync(guard);
+    unlinkSync(mutex);
+  }
+}
+
+/** @template T @param {string} key @param {() => T | Promise<T>} fn @param {LockOpts} [opts] @returns {Promise<T>} */
+export function withLock(key, fn, opts = {}) {
+  return keyedLock(key, async () => {
+    let lock = await tryLock(key, opts);
+    while (!lock.ok) {
+      await new Promise((resolve) => setTimeout(resolve, opts.pollMs ?? 25));
+      lock = await tryLock(key, opts);
+    }
+    try { return await fn(); }
+    finally { lock.release(); }
+  });
+}
+
+/** @returns {string[]} paths of unreadable/malformed locks or dead-owner break mutexes. */
+export function listBadLocks() {
+  let names;
+  try { names = readdirSync(locksDir()); }
+  catch (err) { if (err.code === 'ENOENT') return []; throw err; }
+  return names.filter((name) => name.endsWith('.lock') || name.endsWith('.lock.break')).sort().map((name) => path.join(locksDir(), name)).filter((file) => {
+    try {
+      const owner = ownerOf(readFileSync(file));
+      return owner === null || (file.endsWith('.lock.break') && !alive(owner.pid));
+    }
+    catch { return true; }
+  });
+}