@codedology/code-forge 0.11.0 → 0.13.0

package/src/proof/lock.mjs

@@ -16,7 +16,8 @@
  * with `isolation: lock` through the B6 writer.
  */
 
-import { hasTestFilesItem, testScope } from '../gates/expand.mjs';
+import { changedScope, fileBaseline, hasScopeItem, testScope } from '../gates/expand.mjs';
+import { readAllRows } from '../ledger/write.mjs';
 import { ownedFileCount } from '../gates/owned-count.mjs';
 import { runGates } from '../gates/run.mjs';
 import { StateError } from '../state/paths.mjs';
@@ -139,23 +140,39 @@ export async function withGateSlot({ runId, blockId, fn, pid = process.pid }) {
  * run record once the slot is taken). The full suite runs instead when the block owns more than
  * `threshold` (`gates.full_suite_threshold_files`) files, or when no test file is known. The
  * owned files are counted by `ownedFileCount` over the tracked and new (not ignored) files at
- * `cwd`. Gates with no `{test_files}` item run exactly as before B60: the run record is not read
- * and nothing is counted.
- * @param {{runId: string, blockId: string, gates: Parameters<typeof runGates>[0], cwd: string, timeoutMs?: number, threshold?: number}} opts
+ * `cwd`. Plain gates without --changed retain the old path. B99 records bounded owned hashes
+ * after green scoped runs; --changed uses the last green record and B97's stem pairs.
+ * @param {{runId: string, blockId: string, gates: Parameters<typeof runGates>[0], cwd: string, timeoutMs?: number, threshold?: number, changed?: boolean, slug?: string}} opts
  */
-export async function runGatesGuarded({ runId, blockId, gates, cwd, timeoutMs, threshold }) {
+export async function runGatesGuarded({ runId, blockId, gates, cwd, timeoutMs, threshold, changed = false, slug }) {
   return withGateSlot({
     runId,
     blockId,
     fn: async () => {
-      // plain gates (no `{test_files}` item) run exactly as before B60: no scope is worked out
-      if (!hasTestFilesItem(gates)) return runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
+      // Plain gates without --changed need no scope or baseline.
+      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 block = (await readRun(runId)).blocks?.[blockId];
+      const record = await readRun(runId);
+      const block = record.blocks?.[blockId];
       if (!block) throw new StateError('no-block', `block ${blockId} is not in run ${runId}`);
       const ownedFiles = await ownedFileCount(cwd, block.owned_files, block.owned_kinds);
-      const scope = testScope({ testFiles: block.test_files, owned: block.owned_files, ownedFiles, ...(threshold === undefined ? {} : { threshold }) });
-      return runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}), scope });
+      const fallback = testScope({ testFiles: block.test_files, owned: block.owned_files, ownedFiles, ...(threshold === undefined ? {} : { threshold }) });
+      const current = await fileBaseline(cwd, block.owned_files, block.owned_kinds);
+      let baseline;
+      if (changed) {
+        const rows = await readAllRows(slug ?? record.project);
+        baseline = rows.filter((row) => row.event === 'gate.done' && row.run === runId && row.block === blockId && row.all_ok === true && row.worktree === block.worktree?.path).at(-1)?.files;
+      }
+      const scope = changed ? changedScope({ baseline, current, fallback, owned: block.owned_files, kinds: block.owned_kinds, ...(threshold === undefined ? {} : { threshold }) }) : fallback;
+      const ran = await runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}), scope });
+      // A command that changed an input did not measure the resulting bytes. Do not baseline it.
+      const after = ran.allOk && current ? await fileBaseline(cwd, block.owned_files, block.owned_kinds) : null;
+      const files = after && JSON.stringify(current?.files) === JSON.stringify(after.files) ? after.files : undefined;
+      return { ...ran, ledger_slug: slug ?? record.project, ...(files ? { files } : {}), ...(changed ? { changed_scope: scope } : {}) };
     },
   });
 }

package/src/proof/rule.mjs

@@ -0,0 +1,9 @@
+/** The built-in proof rule carried by every coder context pack. */
+export const PROOF_RULE = [
+  "## proof rule (code-forge)",
+  "- Red→green: each new or changed test must FAIL on the old code first (red), then PASS on the new code (green). A red caused by an import, compile or crash error proves nothing; the red must be an assertion failure. `code-forge proof red-green` does this with the block's base code.",
+  "- No hand mutations. Do not break the code on purpose to test the tests. Red→green is the proof.",
+  "- One exact test per acceptance clause, plus one negative or boundary test where the clause can fail. Assertions say which element and how many, never only \"it exists\".",
+  "- Proof scales with risk: a light-tier file needs red→green per new test; a high-tier file must have it at the gate. Do not add tests, mutants, layers, options or abstractions that the acceptance does not ask for.",
+  "- A weak assertion is fixed by a stronger assertion, not by more tests or mutants.",
+].join('\n');

package/src/proof/tiers.mjs

@@ -5,9 +5,8 @@
  *   high  ⇐ risk ≥ 2, or the path matches `proof.tiers.high.paths`, or `security_sensitive`
  *   light ⇐ everything else (the review-depth band `1 ≤ risk < 2` does NOT raise the proof tier)
  *
- * The light tier's proof is red→green (B10b). The high tier's extra proof — tool-made mutants on
- * changed lines — is held on Q16 (block B10c), so `proofRequirements('high')` reports it as
- * `held` and the gate enforces red→green only until Ricardo answers. Pure: no I/O.
+ * The light tier needs red→green per new or changed test. The high tier must have red→green
+ * at the gate. Mutation testing was cut by the owner (Q16). Pure: no I/O.
  */
 
 import { ownsFile } from '../state/registry.mjs';
@@ -50,14 +49,3 @@ export function blockTier(fileTiers) {
   if (!Array.isArray(fileTiers)) throw new TypeError('blockTier: fileTiers must be an array');
   return fileTiers.some((t) => t?.tier === 'high') ? 'high' : 'light';
 }
-
-/**
- * What the gate requires for a tier. `mutants: 'held'` = the high tier's mutation proof is
- * specified but not enforced until Q16 is answered (B10c).
- * @param {Tier} tier
- * @returns {{red_green: true, mutants: 'none' | 'held'}}
- */
-export function proofRequirements(tier) {
-  if (!TIERS.includes(tier)) throw new TypeError(`proofRequirements: tier must be one of ${TIERS.join(', ')}`);
-  return { red_green: true, mutants: tier === 'high' ? 'held' : 'none' };
-}

package/src/review/fixloop.mjs

@@ -126,6 +126,7 @@ import { afterSchemaMiss, logSecondLevelMiss, packetHash } from './schema-fallba
  * @property {string | null} reviewed_content - the content the last counted round reviewed.
  * @property {boolean} l3_rung_used - the block's L3 rung (rule 5 or 6) was used — once per block.
  * @property {'open' | 'complete' | 'stopped'} status
+ * @property {string} [stop_content_hash] - bytes reviewed by a stop (absent in legacy states).
  * @property {NextStep | null} next
  * @property {{context_mode: string, context_lines: number} | null} [last_packet] - the last recheck round's context: one packet's, or over a Markdown recheck's section packets the summed lines and the one mode they share, else `mixed` (B54).
  * @property {'full' | 'recheck' | 'patch_check' | null} [pending_kind] - the round to re-run after a `retry`.
@@ -620,11 +621,11 @@ function retry(state, kind, reason) {
  * not written, the open set stays as it was, and the gate-relevant `review.cap` row goes through
  * the must-write path — a failed write is a `retry`, never a silent stop.
  * @param {FileState} state @param {LoopDeps} deps
- * @param {'full' | 'recheck' | 'patch_check'} kind @param {string} file
+ * @param {'full' | 'recheck' | 'patch_check'} kind @param {string} file @param {string} contentHash
  * @param {{status: string, tokensIn?: number, budget?: number, section?: string | null}} packet - the non-ok packet (a Markdown section names its heading).
  * @returns {Promise<FileState>}
  */
-async function stopBeforeRound(state, deps, kind, file, packet) {
+async function stopBeforeRound(state, deps, kind, file, contentHash, packet) {
   const reason = packet.status;
   const size =
     typeof packet.tokensIn === 'number' && typeof packet.budget === 'number'
@@ -633,6 +634,7 @@ async function stopBeforeRound(state, deps, kind, file, packet) {
   const row = { event: 'review.cap', file, round: state.round, reason, open: state.open.map((f) => f.id), ...size };
   if (!(await mustNote(deps, row))) return retry(state, kind, 'ledger_write_failed');
   state.status = 'stopped';
+  state.stop_content_hash = contentHash;
   state.next = { action: 'stop', reason, ...size };
   state.pending_kind = null;
   return state;
@@ -703,7 +705,7 @@ export async function runRound(state, deps, opts = {}) {
           // a Markdown file whose packet is `split_required`, rechecked section by section (B54);
           // any other status stops as it always did
           const packed = whole.status === 'split_required' && isMarkdownFile(current.rel) ? packRecheck(diff, pending, whole.budget, moves) : null;
-          if (!packed || packed.status !== 'ok') return stopBeforeRound(state, deps, kind, current.rel, packed ?? whole);
+          if (!packed || packed.status !== 'ok') return stopBeforeRound(state, deps, kind, current.rel, current.hash, packed ?? whole);
           parts = packed.sections.map((sec) => ({ index: sec.index, heading: sec.headings[0], diff: sec.diff, open: sec.open, keys: sec.keys }));
         }
         // EVERY packet is built and held to the budget BEFORE any session runs: a section over it
@@ -718,9 +720,9 @@ export async function runRound(state, deps, opts = {}) {
           const moved = movedText(moves, diff.content, part.keys);
           const packet = buildRecheckPacket({ diff: part.diff, open: part.open, cfg: deps.cfg, contextMode, rulesDigest: deps.rulesDigest, factsExcerpt: deps.factsExcerpt, moved, paired });
           // a packet that fails to build stops with ITS status (and size, when it has one)
-          if (packet.status !== 'ok') return stopBeforeRound(state, deps, kind, current.rel, { ...packet, section: part.heading });
+          if (packet.status !== 'ok') return stopBeforeRound(state, deps, kind, current.rel, current.hash, { ...packet, section: part.heading });
           const size = recheckTokens(part.diff, part.open, moved);
-          if (size > whole.budget) return stopBeforeRound(state, deps, kind, current.rel, { status: 'split_required', tokensIn: size, budget: whole.budget, section: part.heading });
+          if (size > whole.budget) return stopBeforeRound(state, deps, kind, current.rel, current.hash, { status: 'split_required', tokensIn: size, budget: whole.budget, section: part.heading });
           built.push(packet);
         }
         /** @type {Set<Finding>} the pending findings a session that LISTED them resolved */
@@ -804,7 +806,10 @@ export async function runRound(state, deps, opts = {}) {
     const after = new Set(draft.open.map((f) => f.id));
     const closedIds = new Set(state.open.map((f) => f.id).filter((id) => !after.has(id))).size;
     draft.next = decideNext(draft, openBefore, s, kind, closedIds);
-    if (draft.next.action === 'stop') draft.status = 'stopped';
+    if (draft.next.action === 'stop') {
+      draft.status = 'stopped';
+      draft.stop_content_hash = current.hash;
+    }
   }
   const rows = [...lateRows, roundRow];
   if (draft.status === 'stopped') rows.push({ event: 'review.cap', file: current.rel, round: draft.round, reason: draft.next.reason, open: draft.open.map((f) => f.id) });

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,11 +43,12 @@
  *  - `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`);
- *  - `unproven`:   a changed owned file of tier `high` (B20, Ricardo 2026-09-25) has no covering
+ *  - `unproven`:   a changed owned file of tier `high` (B20, the owner 2026-09-25) has no covering
  *    red→green proof (`checkBlockProof`, below). Light-tier files need no proof row.
  * B71 (answers): a finding is also cleared — wherever a waiver clears it, by the one rule set
  * ({@link reviewRules}: `waiverOf`, so `reviewed_by_waiver` reads "waived or answered") — by a
@@ -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 };
 }
 
 /**
@@ -803,7 +817,7 @@ export function closeTier({ file, rows, key, highPaths }) {
 }
 
 /**
- * B20 (Ricardo 2026-09-25): every changed owned file of tier `high` needs a covering red→green
+ * B20 (the owner 2026-09-25): every changed owned file of tier `high` needs a covering red→green
  * proof, checked PER FILE. A file is covered by a `proof` row of this run and block (`rows` must
  * already be the block's rows) with `step: 'red-green'`, `proven: true`, `red_kind: 'assertion'`,
  * whose MAC verifies and whose `covers` list (written by `proof red-green`: the sources the
@@ -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/lenses/A.md

@@ -11,6 +11,10 @@ You work blind: you do not see the other reviewer's answer.
 - State: ordering, concurrency, partial writes, values that can be stale.
 - Arithmetic and units: rounding, overflow, bytes versus characters, time zones.
 
+Never ask for hand mutations or for tests beyond the acceptance clauses.
+The fix for a weak assertion is a stronger assertion.
+Code or tests beyond what the change needs (unused options, extra layers, speculative generality) is at most a `nit` unless it hides a bug.
+
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.

package/src/review/lenses/B.md

@@ -12,6 +12,10 @@ You work blind: you do not see the other reviewer's answer.
   that can escape a root (`..`, absolute, symlinks); missing authorization; unsafe defaults.
 - Facts: a flag, path or API the change relies on that the facts excerpt contradicts.
 
+Never ask for hand mutations or for tests beyond the acceptance clauses.
+The fix for a weak assertion is a stronger assertion.
+Code or tests beyond what the change needs (unused options, extra layers, speculative generality) is at most a `nit` unless it hides a bug.
+
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.

package/src/review/lenses/full.md

@@ -12,6 +12,10 @@ You are a code reviewer doing a FULL review of one changed file.
 
 Report each real defect once, at the lines where it lives.
 
+Never ask for hand mutations or for tests beyond the acceptance clauses.
+The fix for a weak assertion is a stronger assertion.
+Code or tests beyond what the change needs (unused options, extra layers, speculative generality) is at most a `nit` unless it hides a bug.
+
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.

package/src/review/lenses/judge.md

@@ -13,6 +13,10 @@ their two answers, the list of hunk headers, and the diff only when the packet i
 - Your `findings` list is final: nothing you drop is fixed, everything you keep is.
 - `passed` is true only when you keep no `critical` and no `warning`.
 
+Never ask for hand mutations or for tests beyond the acceptance clauses.
+The fix for a weak assertion is a stronger assertion.
+Code or tests beyond what the change needs (unused options, extra layers, speculative generality) is at most a `nit` unless it hides a bug.
+
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.

package/src/review/lenses/quick.md

@@ -10,6 +10,10 @@ You are a code reviewer doing a QUICK pass on one small, low-risk change.
 
 Skip style, naming and structure unless it hides a bug. Keep `findings` short.
 
+Never ask for hand mutations or for tests beyond the acceptance clauses.
+The fix for a weak assertion is a stronger assertion.
+Code or tests beyond what the change needs (unused options, extra layers, speculative generality) is at most a `nit` unless it hides a bug.
+
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.

package/src/review/lenses/recheck.md

@@ -15,6 +15,10 @@ that changed since that round, each with a window of the current file around it.
 - `passed` is true only when every open finding is resolved and you raised no new `critical`
   or `warning`.
 
+Never ask for hand mutations or for tests beyond the acceptance clauses.
+The fix for a weak assertion is a stronger assertion.
+Code or tests beyond what the change needs (unused options, extra layers, speculative generality) is at most a `nit` unless it hides a bug.
+
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.

package/src/review/paired.mjs

@@ -17,6 +17,7 @@ function identity(file) {
     if (stem.endsWith('_test')) { test = true; stem = stem.slice(0, -5); }
   } else if (ext === '.py') {
     if (stem.startsWith('test_')) { test = true; stem = stem.slice(5); }
+    else if (stem.endsWith('_test')) { test = true; stem = stem.slice(0, -5); }
   } else if (ext === '.swift') {
     if (stem.endsWith('Tests')) { test = true; stem = stem.slice(0, -5); }
   } else return null;

package/src/review/reopen.mjs

@@ -18,7 +18,7 @@
  *  - `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;
+ *    is unknown and the current hash already has a verified review round;
  *  - `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.
@@ -32,7 +32,8 @@
  * 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.
+ * round and stop reason — else the content is unknown. B114: unknown content can restart only
+ * when no verified review.round of this run/block/file names the current hash (from_hash: null).
  *
  * 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
@@ -102,6 +103,15 @@ export function stopContentHash(state, rows, { runId, block, file, key }) {
   return null;
 }
 
+/**
+ * A legacy stop with unknown content can restart only on bytes with no verified round here.
+ * @param {ReadonlyArray<Record<string, any>>} rows
+ * @param {{runId: string, block: string, file: string, key: Buffer, contentHash: string}} at
+ */
+function hasReviewedHash(rows, { runId, block, file, key, contentHash }) {
+  return rows.some((r) => r?.event === 'review.round' && r.run === runId && r.block === block && r.file === file && r.content_hash === contentHash && verified(r, key));
+}
+
 /**
  * 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.
@@ -138,7 +148,8 @@ function latestRowAt(rows, { runId, block, file, key, seq }) {
  * 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).
+ * nor the content the stop reviewed (`stopContentHash`). Unknown content requires a null
+ * from_hash, the row's to_hash equal to current content, and no verified round at that hash.
  * @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}
@@ -149,7 +160,8 @@ export function reopenRowFor(rows, { runId, block, file, key, status, state, seq
   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;
+    if (contentHash === stopHash || contentHash === row.from_hash) return null;
+    if (stopHash === null && (row.from_hash !== null || row.to_hash !== contentHash || hasReviewedHash(rows, { runId, block, file, key, contentHash }))) return null;
     return row;
   }
   return null;
@@ -200,8 +212,8 @@ export async function reopenFile({ runId, id, file, reason, record, rows, key, w
     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 === null && hasReviewedHash(runRows, { runId, block: id, file, key, contentHash: current })) {
+      throw new StateError('reopen-same-content', `reopen-same-content: the content the stop of ${file} reviewed is unknown and its current content has already been reviewed; change the file and run block reopen, or the owner can run block close --no-require-reviews; 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`);

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/exec.mjs

@@ -139,6 +139,7 @@ function untrackChild(pid) {
  * @param {object} [opts]
  * @param {string} [opts.cwd]
  * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {BufferEncoding} [opts.stdoutEncoding] - stdout encoding (default UTF-8); base64 preserves binary git blobs.
  * @param {number} [opts.timeoutMs] - Kill the child (and its process group) if it runs longer
  *   than this. Must be a finite number > 0 when given.
  * @param {number[]} [opts.okExitCodes] - Exit codes treated as `result: "ok"` (default `[0]`).
@@ -212,7 +213,7 @@ export function exec(argv, opts = {}) {
       child.kill(signal);
     };
 
-    const stdoutText = () => Buffer.concat(stdoutChunks).toString('utf8');
+    const stdoutText = () => Buffer.concat(stdoutChunks).toString(opts.stdoutEncoding ?? 'utf8');
     const stderrText = () => Buffer.concat(stderrChunks).toString('utf8');
 
     /** @param {ExecResult} result */

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; }
+  });
+}