@codedology/code-forge 0.11.0 → 0.12.0

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

@@ -47,7 +47,7 @@
  *    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
@@ -803,7 +803,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

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/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/gate-token.mjs

@@ -6,3 +6,6 @@
 
 /** A gate argv item that is EXACTLY this string expands to the block's test files. */
 export const TEST_FILES_TOKEN = '{test_files}';
+
+/** A whole argv item for lint/format paths, never a command. */
+export const CHANGED_FILES_TOKEN = '{changed_files}';

package/src/worker/loop.mjs

@@ -57,6 +57,7 @@ import { countLines, RouteError, routeTicket } from '../review/route.mjs';
 import { canonicalPath, contentRootFor, reviewTicket } from './engine.mjs';
 import { announceWorker, beatWorker, HEARTBEAT_MS, liveWorker, pendingTickets, readTicket, retractWorker, writeResult } from './queue.mjs';
 import { DELETED_HASH, hashBytes, readRegularFileNoFollow, repoRootOf, WorkerError } from './ticket.mjs';
+import { watchTick } from './watch.mjs';
 
 /** Name of the key the worker resolves for System 1 (`keys.jev` / `system1.key` reference). */
 export const JEV_KEY_NAME = 'jev';
@@ -234,6 +235,8 @@ export function recordedVerdict(result) {
  * @property {typeof spawnSession} [spawn]
  * @property {typeof readRun} [readRun] - the run-record read behind the per-ticket config (a test seam).
  * @property {typeof readTicket} [readTicket] - the ticket read (a test seam).
+ * @property {typeof import('../util/exec.mjs').exec} [watchExec] - watch git exec seam.
+ * @property {Parameters<typeof watchTick>[0]['hooks']} [watchHooks] - deterministic watch races.
  * @property {import('../keys/store.mjs').KeyStore} [store] - default: B2's production store.
  * @property {any} [opRead]
  * @property {NodeJS.ProcessEnv} [env]
@@ -281,6 +284,9 @@ export async function createWorker(opts, deps = {}) {
 
   /** @param {Record<string, any>} row */
   const ledger = (row) => writeRow(signRow({ run: runId, ...row }, key));
+  // Shared across direct ticks and the scheduler, so running tickets are never superseded.
+  const activeTickets = new Set();
+  const tickWatch = () => watchTick({ repoRoot, runId, cfg, readRun: loadRun, writeRow: ledger, running: activeTickets, exec: deps.watchExec, hooks: deps.watchHooks });
 
   /**
    * The config ticket `id` is reviewed with (B35): its snapshot from the run record, re-read per
@@ -617,6 +623,13 @@ export async function createWorker(opts, deps = {}) {
         }
       }
       if (!stopping) {
+        try {
+          await tickWatch();
+        } catch (thrown) {
+          const text = `watch tick failed (${errorKind(thrown)})`;
+          writeSafe(warnStream, `worker: WARN ${text}\n`);
+          try { await logWarning({ warning: 'watch_tick_failed', message: text }); } catch { /* a log failure never stops dispatch */ }
+        }
         for (const id of pendingTickets(repoRoot)) {
           if (poisoned.has(id) || started.has(id)) continue;
           if (limit === null) limit = await poolSize();
@@ -624,6 +637,7 @@ export async function createWorker(opts, deps = {}) {
           const fileKey = fileKeyOf(id);
           if (fileKey !== null && busy.has(fileKey)) continue; // waits without a slot
           started.add(id);
+          activeTickets.add(id);
           if (fileKey !== null) busy.add(fileKey);
           const slot = runOne(id)
             .then((n) => {
@@ -632,6 +646,7 @@ export async function createWorker(opts, deps = {}) {
             .finally(() => {
               // the slot is freed on every exit path (`runOne` never rejects)
               running.delete(id);
+              activeTickets.delete(id);
               fileKeys.delete(id);
               if (fileKey !== null) busy.delete(fileKey);
             });
@@ -737,7 +752,7 @@ export async function createWorker(opts, deps = {}) {
     retractWorker(repoRoot, process.pid);
   }
 
-  return { processTicket, drain, run, once, stop, release, jevKeyResolved: jevKey !== null, sessionEnv: childEnv };
+  return { processTicket, drain, run, once, stop, release, watchTick: tickWatch, jevKeyResolved: jevKey !== null, sessionEnv: childEnv };
 }
 
 /**

package/src/worker/queue.mjs

@@ -102,17 +102,56 @@ export function resolveTicket({ repoRoot, run, block, file, tree = null }) {
  * @throws {WorkerError} `bad-path` for a relative `tree` or one that cannot be resolved.
  */
 export function enqueue({ repoRoot, run, block, file, tree = null, now = new Date() }) {
-  const { rel, root, content_hash, ticket } = resolveTicket({ repoRoot, run, block, file, tree });
+  const { content_hash } = resolveTicket({ repoRoot, run, block, file, tree });
+  return enqueueHash({ repoRoot, run, block, file, tree, content_hash, now });
+}
+
+/** Queue proven git-object content through the same identity as a manual review.
+ * @param {{repoRoot: string, run: string, block: string, file: string, content_hash: string, tree?: string | null, now?: Date}} opts
+ * @returns {{ticket: string, status: 'queued' | 'done', file: string, content_hash: string, tree?: string}}
+ */
+export function enqueueHash({ repoRoot, run, block, file, content_hash, tree = null, now = new Date() }) {
+  const rel = assertRowPath(file);
+  const root = tree === null ? null : realTree(tree);
+  const ticket = ticketId({ run, block, file: rel, content_hash, tree: root });
   const target = path.join(queueDir(repoRoot), `${ticket}.json`);
   const named = root === null ? {} : { tree: root };
   if (!existsSync(target)) {
     /** @type {Ticket} */
     const body = { ticket, run, block, file: rel, content_hash, enqueued_at: now.toISOString(), ...named };
-    writeAtomic(target, `${JSON.stringify(body)}\n`);
+    // Publish a complete immutable ticket without replacing a concurrent coder's ticket.
+    mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+      writeFileSync(tmp, `${JSON.stringify(body)}\n`, { mode: 0o644 });
+      try { linkSync(tmp, target); } catch (err) { if (err.code !== 'EEXIST') throw err; }
+    } finally { rmSync(tmp, { force: true }); }
   }
+  // Returning content is current again. Claim only a superseded marker's exact bytes;
+  // a real result that replaced it wins the comparison and is restored unchanged.
+  let seen;
+  let done;
+  try {
+    seen = readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`));
+    done = JSON.parse(seen.toString('utf8'));
+  } catch { /* missing or unreadable markers remain untouched */ }
+  if (seen && done?.status === 'refused' && done.reason === 'superseded' && !done.result) dropDoneIf(repoRoot, ticket, seen);
   return { ticket, status: isDone(repoRoot, ticket) ? 'done' : 'queued', file: rel, content_hash, ...named };
 }
 
+/** Finish only an unstarted, pending review. A superseded marker has no review result.
+ * @param {string} repoRoot @param {string} ticket
+ * @param {{write?: (file: string, text: string) => void, link?: (from: string, to: string) => void}} [io] - publication seams for tests.
+ */
+export function supersedeTicket(repoRoot, ticket, io = {}) {
+  const marker = path.join(queueDir(repoRoot), `${assertTicketId(ticket)}.done`);
+  const tmp = `${marker}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  try {
+    (io.write ?? ((file, text) => writeFileSync(file, text, { mode: 0o644 })))(tmp, `${JSON.stringify({ ticket, status: 'refused', reason: 'superseded' })}\n`);
+    try { (io.link ?? linkSync)(tmp, marker); } catch (err) { if (err.code !== 'EEXIST') throw err; }
+  } finally { rmSync(tmp, { force: true }); }
+}
+
 /** B71: the most finding ids one answers ticket may name. */
 export const MAX_ANSWERS = 10;
 
@@ -369,6 +408,25 @@ export function pendingTickets(repoRoot) {
   return pending.map((id) => ({ id, at: at(id) })).sort((a, b) => (a.at === b.at ? (a.id < b.id ? -1 : 1) : a.at < b.at ? -1 : 1)).map((e) => e.id);
 }
 
+/**
+ * Valid review tickets for one block and content tree, oldest first. Answers tickets cannot
+ * stand in for a file's own review. Unreadable tickets are refused, never silently omitted.
+ * @param {{repoRoot: string, run: string, block: string, tree?: string | null}} opts
+ * @returns {Ticket[]}
+ */
+export function blockTickets({ repoRoot, run, block, tree = null }) {
+  let names;
+  try {
+    names = readdirSync(queueDir(repoRoot));
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw new WorkerError('queue-unreadable', 'the review queue cannot be read');
+  }
+  const tickets = names.filter((n) => /^[0-9a-f]{24}\.json$/.test(n)).map((n) => readTicket(repoRoot, n.slice(0, 24)));
+  return tickets.filter((t) => !t.kind && t.run === run && t.block === block && (t.tree ?? null) === tree)
+    .sort((a, b) => a.enqueued_at.localeCompare(b.enqueued_at) || a.ticket.localeCompare(b.ticket));
+}
+
 /**
  * Read and re-validate a ticket (coder-writable): its id must match its content.
  * @param {string} repoRoot @param {string} id

package/src/worker/watch.mjs

@@ -0,0 +1,113 @@
+/** Opt-in commit watch. Read immutable git objects, never the coder's working bytes. */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { reviewFileLoop } from '../config/validate.mjs';
+import { snapshotFor } from '../state/config-snapshot.mjs';
+import { readRun } from '../state/run.mjs';
+import { ownsAt } from '../review/gate-check.mjs';
+import { exec } from '../util/exec.mjs';
+import { blockTickets, enqueueHash, isDone, queueDir, supersedeTicket } from './queue.mjs';
+import { assertRowPath, DELETED_HASH, gitChildEnv, hashBytes } from './ticket.mjs';
+
+const SHA = /^[0-9a-f]{40,64}$/;
+const BLOCK = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * One scheduler tick, also exposed directly for deterministic race tests.
+ * The boot config gates ALL watch work; absent/wait/overlap never reads the run or spawns git.
+ * @param {{repoRoot: string, runId: string, cfg: Record<string, any>, readRun?: typeof readRun,
+ *   writeRow: (row: Record<string, any>) => Promise<unknown>, exec?: typeof exec,
+ *   running?: ReadonlySet<string>, hooks?: {afterHead?: (head: string) => Promise<unknown>, beforeQueue?: () => Promise<unknown>}}} opts
+ */
+export async function watchTick({ repoRoot, runId, cfg, readRun: loadRun = readRun, writeRow, exec: execute = exec, running = new Set(), hooks = {} }) {
+  if (reviewFileLoop(cfg) !== 'watch') return;
+  const record = await loadRun(runId);
+  if (record.status !== 'active' || reviewFileLoop(snapshotFor(record, '')?.config ?? cfg) !== 'watch') return;
+  const env = gitChildEnv();
+  for (const [block, entry] of Object.entries(record.blocks ?? {})) {
+    if (entry.status !== 'open' || !BLOCK.test(block)) continue;
+    const stateFile = path.join(queueDir(repoRoot), 'watch', `${block}.json`);
+    let tree = null;
+    let root = repoRoot;
+    let state = {};
+    try { state = JSON.parse(readFileSync(stateFile, 'utf8')) ?? {}; } catch { /* restart at base */ }
+    const base = entry.base_sha;
+    /** @param {Record<string, any>} next */
+    const save = (next) => {
+      mkdirSync(path.dirname(stateFile), { recursive: true });
+      const tmp = `${stateFile}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+      try {
+        writeFileSync(tmp, `${JSON.stringify(next)}\n`, { mode: 0o600 });
+        renameSync(tmp, stateFile);
+        state = next;
+      } finally { rmSync(tmp, { force: true }); }
+    };
+    /** @param {string} reason */
+    const skip = async (reason) => {
+      const skipped = Array.isArray(state.skipped) ? state.skipped : [];
+      if (!skipped.includes(reason)) {
+        await writeRow({ event: 'watch.skipped', block, reason });
+        save({ ...state, skipped: [...skipped, reason] });
+      }
+    };
+    try {
+      if (entry.worktree) {
+        root = realpathSync(entry.worktree.path);
+        tree = root;
+      }
+      if (state.run !== runId || state.base !== base || state.tree !== tree) state = { run: runId, base, tree, skipped: [] };
+      /** @param {string[]} argv */
+      const git = (argv) => execute(['git', ...argv], { cwd: root, env, timeoutMs: 10000 });
+      const headResult = await git(['rev-parse', '--verify', 'HEAD^{commit}']);
+      const head = headResult.stdout.trim();
+      if (headResult.result !== 'ok' || !SHA.test(head)) { await skip('unreadable_head'); continue; }
+      const earlier = blockTickets({ repoRoot, run: runId, block, tree });
+      await hooks.afterHead?.(head);
+      if (typeof base !== 'string' || !SHA.test(base) || (await git(['merge-base', '--is-ancestor', base, head])).result !== 'ok') {
+        await skip('not_descendant'); continue;
+      }
+      const last = typeof state.sha === 'string' && SHA.test(state.sha) ? state.sha : base;
+      if (last !== base && (await git(['merge-base', '--is-ancestor', last, head])).result !== 'ok') {
+        await skip('rewound');
+        const { sha: _sha, ...restart } = state;
+        save(restart);
+        continue;
+      }
+      // A healthy tick ends the skip streak: no new commit here, or a queued commit below. An
+      // unreadable commit keeps the streak, so it writes one watch.skipped row, not one per tick.
+      if (last === head) { if (state.skipped?.length) save({ ...state, skipped: [] }); continue; }
+      const diff = await git(['diff', '--name-only', '-z', '--no-renames', last, head, '--']);
+      if (diff.result !== 'ok') { await skip('unreadable_head'); continue; }
+      const owns = ownsAt(tree ? '' : path.relative(repoRoot, record.workspace).split(path.sep).join('/'));
+      const files = diff.stdout.split('\0').filter(Boolean);
+      const owned = files.filter((file) => owns(entry.owned_files, file, entry.owned_kinds));
+      if (owned.length !== files.length) await skip('unowned_path');
+      // Stage every hash before publishing anything: an unreadable object queues nothing.
+      const hashes = [];
+      let unreadable = false;
+      for (const raw of owned) {
+        const file = assertRowPath(raw);
+        const listed = await git(['ls-tree', '-z', head, '--', file]);
+        if (listed.result !== 'ok') { unreadable = true; break; }
+        if (!listed.stdout) { hashes.push({ file, content_hash: DELETED_HASH }); continue; }
+        if (!/^100(?:644|755) blob /.test(listed.stdout)) { unreadable = true; break; }
+        const shown = await execute(['git', 'show', `${head}:${file}`], { cwd: root, env, timeoutMs: 10000, stdoutEncoding: 'base64' });
+        if (shown.result !== 'ok') { unreadable = true; break; }
+        hashes.push({ file, content_hash: hashBytes(Buffer.from(shown.stdout, 'base64')) });
+      }
+      if (unreadable) { await skip('unreadable_head'); continue; }
+      await hooks.beforeQueue?.();
+      for (const { file, content_hash } of hashes) {
+        const current = enqueueHash({ repoRoot, run: runId, block, file, content_hash, tree });
+        for (const old of earlier) {
+          if (old.file === file && old.ticket !== current.ticket && !running.has(old.ticket) && !isDone(repoRoot, old.ticket)) supersedeTicket(repoRoot, old.ticket);
+        }
+      }
+      save({ ...state, run: runId, base, tree, sha: head, skipped: [] });
+    } catch {
+      // A bad path, missing tree or failed git read is a skip, never a block failure.
+      await skip('unreadable_head');
+    }
+  }
+}