@codedology/code-forge 0.10.0 → 0.12.0

package/src/worker/engine.mjs

@@ -42,7 +42,7 @@
  * second `schema` miss — this round's first try after the earlier ticket's — is tried once on
  * `review.second_levels.<level>` when one is configured.
  * B56: every round gets ONE memoised reader of the block's OTHER changed files' diffs
- * (`blockPeerDiffs`: listed and read at most once per ticket) so the review can name code moved
+ * (the ticket's `fileContext`: listed once, diffs read lazily at most once per ticket) so the review can name code moved
  * between them in a `## moved code` packet section (round 1, rechecks and patch check alike).
  * The review NEVER approves an empty or failed session: that is `unavailable` (§4.2 stub guard).
  * A throw inside the round is `unavailable` too, with the state saved as `next: retry` (see
@@ -169,14 +169,14 @@ import { assertTicketId, contentHash, readRegularFileNoFollow, WorkerError } fro
  * `tree` (B62b) is the recorded `worktree` `{path, branch, base_sha}`, null when the block has
  * none; `base` is then the tree's `base_sha`. A recorded worktree that `worktreeRecord` refuses
  * (path, branch, hex base_sha) throws `worktree-malformed`.
- * @returns {Promise<{base: string | null, level: string, owned: string[], ownedKinds: Record<string, string>, acceptance?: unknown, kind: string | null, tree: WorktreeEntry | null, workspace: string | null}>}
+ * @returns {Promise<{base: string | null, level: string, owned: string[], ownedKinds: Record<string, string>, testFiles: string[], acceptance?: unknown, kind: string | null, tree: WorktreeEntry | null, workspace: string | null}>}
  */
 export async function blockEntryFor(runId, block) {
   let record;
   try {
     record = await readRun(runId);
   } catch (err) {
-    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], ownedKinds: {}, acceptance: undefined, kind: null, tree: null, workspace: null };
+    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], ownedKinds: {}, testFiles: [], acceptance: undefined, kind: null, tree: null, workspace: null };
     throw new Error('run-record-unreadable');
   }
   if (!record || typeof record !== 'object' || !record.blocks || typeof record.blocks !== 'object') throw new Error('run-record-unreadable');
@@ -187,6 +187,7 @@ export async function blockEntryFor(runId, block) {
   const owned = Array.isArray(entry.owned_files) ? entry.owned_files.filter((f) => typeof f === 'string') : [];
   const kinds = entry.owned_kinds;
   const ownedKinds = kinds && typeof kinds === 'object' && !Array.isArray(kinds) ? kinds : {};
+  const testFiles = Array.isArray(entry.test_files) ? entry.test_files.filter((f) => typeof f === 'string' && !/[*?\[\]{}]/.test(f) && ownsFile(owned, f, ownedKinds)) : [];
   /** @type {WorktreeEntry | null} */
   let tree = null;
   if (entry.worktree !== undefined && entry.worktree !== null) {
@@ -196,10 +197,11 @@ export async function blockEntryFor(runId, block) {
       throw new Error('worktree-malformed');
     }
   }
-  return { base: tree ? tree.base_sha : sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, ownedKinds, acceptance: entry.acceptance, kind: blockKind({ owned, declared: entry.kind }), tree, workspace: typeof record.workspace === 'string' ? record.workspace : null };
+  return { base: tree ? tree.base_sha : sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, ownedKinds, testFiles, acceptance: entry.acceptance, kind: blockKind({ owned, declared: entry.kind }), tree, workspace: typeof record.workspace === 'string' ? record.workspace : null };
 }
 
 /** @typedef {{path: string, branch: string, base_sha: string}} WorktreeEntry */
+/** @typedef {{peers: string[], changedFiles: string[], ownedFiles: string[], testFiles: string[]}} FileContext */
 
 /** The refusals of {@link blockTree} a ticket answers with, as its `reason`. */
 const TREE_CODES = new Set(['worktree-malformed', 'worktree-missing', 'worktree-not-dir', 'worktree-branch-mismatch', 'worktree-workspace-missing', 'worktree-foreign', 'git-failed']);
@@ -373,7 +375,28 @@ export async function reviewTicket(ticket, ctx) {
     }
   }
   const factsExcerpt = factsFor(entry, ctx.cfg);
-  const peerDiffs = blockPeerDiffs(contentRoot, { base: entry.base, owned: entry.owned, ownedKinds: entry.ownedKinds, file: ticket.file });
+  // Resolve concrete paths in this block's tree; neither globs nor another block's tests
+  // authorize an untracked attachment. Read lazily so a stopped ticket needs no file listing.
+  /** @type {Promise<FileContext> | undefined} */
+  let contextOnce;
+  /** @type {() => Promise<import('../review/moved.mjs').PeerDiff[]>} */
+  let readDiffs = () => Promise.resolve([]);
+  const fileContext = () => contextOnce ??= (async () => {
+    try {
+      // Read the listing directly: blockPeers' [] fallback would hide a git failure and
+      // still authorize explicit tests. Context and peer diffs must fail soft together.
+      const peers = entry.base === null || entry.owned.length === 0 ? [] : (await computeFileSet({ cwd: contentRoot, base: entry.base })).all.filter((f) => f !== ticket.file && ownsFile(entry.owned, f, entry.ownedKinds));
+      readDiffs = peerDiffReader({ repoRoot: contentRoot, base: entry.base, file: ticket.file, peers });
+      const changedFiles = [...peers, ticket.file].filter((f) => ownsFile(entry.owned, f, entry.ownedKinds));
+      return { peers, changedFiles, ownedFiles: [...new Set([...changedFiles, ...entry.testFiles])], testFiles: entry.testFiles };
+    } catch {
+      return { peers: [], changedFiles: [], ownedFiles: [], testFiles: [] };
+    }
+  })();
+  const peerDiffs = async () => {
+    await fileContext();
+    return readDiffs();
+  };
   try {
     // B63a: the `context` rules and lessons, read from the MAIN tree (`ctx.repoRoot`, never the
     // block's worktree) with the config in force for this ticket; '' without a `context` key, so
@@ -390,11 +413,11 @@ export async function reviewTicket(ticket, ctx) {
     const digest = rulesDigest === '' ? {} : { rulesDigest };
     if (!ctx.key) {
       return await reviewFile(
-        { repoRoot: contentRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, kind: entry.kind, workDir, factsExcerpt, ...digest, peerDiffs },
+        { repoRoot: contentRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, kind: entry.kind, workDir, factsExcerpt, ...digest, peerDiffs, ...(await fileContext()) },
         { spawn: ctx.spawn, ...(ctx.writeRow ? { writeRow: ctx.writeRow } : {}) },
       );
     }
-    return await fixLoopRound(ticket, tctx, { base: entry.base, level: entry.level, owned: entry.owned, ownedKinds: entry.ownedKinds, blockKindOf: entry.kind, key: ctx.key, workDir, factsExcerpt, rulesDigest, peerDiffs });
+    return await fixLoopRound(ticket, tctx, { base: entry.base, level: entry.level, owned: entry.owned, ownedKinds: entry.ownedKinds, blockKindOf: entry.kind, key: ctx.key, workDir, factsExcerpt, rulesDigest, peerDiffs, fileContext });
   } finally {
     rmSync(workDir, { recursive: true, force: true });
   }
@@ -506,10 +529,10 @@ export function mayTakeRung(state, kind, cfg, rungUsed) {
  * first full round, or any round once the rung is gone) runs outside the block lock, in parallel
  * with the block's other files.
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
- * @param {{base: string | null, level: string, owned: string[], ownedKinds?: Record<string, string>, blockKindOf: string, key: Buffer, workDir: string, factsExcerpt: string, rulesDigest?: string, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>}} opts
+ * @param {{base: string | null, level: string, owned: string[], ownedKinds?: Record<string, string>, blockKindOf: string, key: Buffer, workDir: string, factsExcerpt: string, rulesDigest?: string, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>, fileContext: () => Promise<FileContext>}} opts
  * @returns {Promise<ReviewOutcome>}
  */
-async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, blockKindOf, key, workDir, factsExcerpt, rulesDigest = '', peerDiffs }) {
+async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, blockKindOf, key, workDir, factsExcerpt, rulesDigest = '', peerDiffs, fileContext }) {
   if (!ctx.readRows || !ctx.writeRow) return { status: 'unavailable', reason: 'no-ledger', approved: false, engine: 'adaptive', sessions: [] };
   const readRows = ctx.readRows;
   /** @type {{outcome: ReviewOutcome} | {round: () => Promise<ReviewOutcome>}} */
@@ -572,7 +595,7 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, block
       state.l3_rung_used = true; // the orchestrator ran the block's one L3 patch before this ticket
     }
     const fixed = state;
-    const round = () => playRound(ticket, ctx, { state: fixed, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest, extraRounds, peerDiffs });
+    const round = () => playRound(ticket, ctx, { state: fixed, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest, extraRounds, peerDiffs, fileContext });
     // a round that could take the rung keeps the block lock until its state is saved
     if (mayTakeRung(fixed, kind, ctx.cfg, rungUsed)) return { outcome: await round() };
     return { round };
@@ -583,10 +606,10 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, block
 /**
  * Run the prepared round and save the file's state: the ticket's outcome.
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
- * @param {{state: import('../review/fixloop.mjs').FileState, kind: 'full' | 'recheck' | 'patch_check', where: import('./review-state.mjs').Where, seq: number, base: string | null, blockKindOf: string, workDir: string, factsExcerpt: string, rulesDigest?: string, extraRounds?: number, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>}} opts
+ * @param {{state: import('../review/fixloop.mjs').FileState, kind: 'full' | 'recheck' | 'patch_check', where: import('./review-state.mjs').Where, seq: number, base: string | null, blockKindOf: string, workDir: string, factsExcerpt: string, rulesDigest?: string, extraRounds?: number, peerDiffs?: () => Promise<import('../review/moved.mjs').PeerDiff[]>, fileContext: () => Promise<FileContext>}} opts
  * @returns {Promise<ReviewOutcome>}
  */
-async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest = '', extraRounds = 0, peerDiffs }) {
+async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKindOf, workDir, factsExcerpt, rulesDigest = '', extraRounds = 0, peerDiffs, fileContext }) {
   /** @type {Record<string, any> | null} */
   let engineOutcome = null;
   let approvalWritten = false;
@@ -626,6 +649,7 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
     const schemaHistory = ctx.readRows
       ? ledgerSchemaHistory({ readRows: ctx.readRows, verify: (row) => verifyRow(row, where.key).ok, runId: ctx.runId, file: ticket.file, contentHash: ticket.content_hash })
       : undefined;
+    const files = await fileContext();
     await runRound(
       state,
       {
@@ -637,16 +661,20 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
         factsExcerpt,
         ...(rulesDigest !== '' ? { rulesDigest } : {}),
         extraRounds,
+        ...files,
         ...(peerDiffs ? { peerDiffs } : {}),
         ...(jev ? { jev } : {}),
         ...(schemaHistory ? { schemaHistory } : {}),
         review: async () => {
-          engineOutcome = await reviewFile({ repoRoot: ctx.contentRoot ?? ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, kind: blockKindOf, workDir, factsExcerpt, ...(rulesDigest !== '' ? { rulesDigest } : {}), ...(peerDiffs ? { peerDiffs } : {}) }, { spawn: ctx.spawn, writeRow, ...(schemaHistory ? { schemaHistory } : {}) });
+          engineOutcome = await reviewFile({ repoRoot: ctx.contentRoot ?? ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, kind: blockKindOf, workDir, factsExcerpt, ...files, ...(rulesDigest !== '' ? { rulesDigest } : {}), ...(peerDiffs ? { peerDiffs } : {}) }, { spawn: ctx.spawn, writeRow, ...(schemaHistory ? { schemaHistory } : {}) });
           return engineOutcome;
         },
         spawn: async (opts) => {
           const res = await ctx.spawn(opts);
-          rechecks.push({ lens: opts?.rowExtra?.lens ?? null, role: opts?.role ?? null, level: opts?.level ?? null, provider: res?.provider ?? null, model: res?.model ?? null });
+          rechecks.push({ lens: opts?.rowExtra?.lens ?? null, role: opts?.role ?? null, level: opts?.level ?? null, provider: res?.provider ?? null, model: res?.model ?? null,
+            status: res?.status ?? null, tokens_in: res?.usage?.tokens_in ?? res?.row?.tokens_in ?? null, tokens_out: res?.usage?.tokens_out ?? res?.row?.tokens_out ?? null,
+            ...(typeof res?.status === 'string' && res.status !== 'ok' ? { reason: res.reason ?? res.status } : {}),
+          });
           return res;
         },
       },
@@ -689,7 +717,7 @@ async function playRound(ticket, ctx, { state, kind, where, seq, base, blockKind
     return { ...head, status: 'reviewed', approved: true, findings: [] };
   }
   if (status === 'stopped') return { ...head, status: 'stopped', stopped: next?.reason ?? 'stopped', ...stopSize(state), approved: false, findings: state.open };
-  return { ...head, status: 'reviewed', approved: false, reason: 'findings-open', findings: state.open };
+  return { ...head, status: 'reviewed', approved: false, reason: next?.reason === 'no-fix-hunks' ? 'no-fix-hunks' : 'findings-open', findings: state.open };
 }
 
 /**

package/src/worker/loop.mjs

@@ -35,6 +35,8 @@
  */
 
 import { spawn as nodeSpawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { expiryChecks } from '../autopilot/limits.mjs';
@@ -43,6 +45,7 @@ import { cacheHoursFrom, createDefaultKeyStore, resolveKey } from '../keys/store
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { spawnSession } from '../session/spawn.mjs';
 import { snapshotFor } from '../state/config-snapshot.mjs';
+import { runRecordPath } from '../state/paths.mjs';
 import { readRun, reattachWorker } from '../state/run.mjs';
 import { loadKey, signRow } from '../state/signer.mjs';
 import { logWarning } from '../util/error-log.mjs';
@@ -54,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';
@@ -220,6 +224,7 @@ export function recordedVerdict(result) {
  * @property {string} slug - ledger project slug (the run record's `project`).
  * @property {Buffer} key - the run's HMAC key.
  * @property {number} [pollMs]
+ * @property {string} [guardRunRecordPath] - booted workers stop when this authoritative record disappears.
  * @property {number} [heartbeatMs] - how often `heartbeat_at` is refreshed: an integer ≥ `MIN_HEARTBEAT_MS`,
  *   else `HEARTBEAT_MS`.
  */
@@ -230,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]
@@ -277,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
@@ -598,7 +608,28 @@ export async function createWorker(opts, deps = {}) {
     /** @type {Set<string>} */
     const started = new Set();
     for (;;) {
+      // One cheap stat per scheduler tick, including while tickets are in flight. Removing a
+      // test HOME (or the run record) stops new tickets; an open real run remains untouched.
+      if (!stopping && opts.guardRunRecordPath) {
+        try {
+          statSync(opts.guardRunRecordPath);
+        } catch (err) {
+          if (err.code === 'ENOENT' || err.code === 'ENOTDIR') {
+            stop();
+            // The error log lives under HOME: never write it when HOME itself is gone, or the
+            // log write would create the removed HOME again.
+            if (existsSync(os.homedir())) await logWarning({ warning: 'worker_orphan_stop', message: `run record missing: ${opts.guardRunRecordPath}` }).catch(() => null);
+          }
+        }
+      }
       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();
@@ -606,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) => {
@@ -614,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);
             });
@@ -719,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 };
 }
 
 /**
@@ -750,7 +783,7 @@ export async function bootWorker(opts, deps = {}) {
   const runRootDir = runRoot(opts.runId, { root: tmpRoot });
   setRunRoot(runRootDir);
   const key = await loadKey(opts.runId);
-  const worker = await createWorker({ runId: opts.runId, repoRoot, cfg, runRootDir, slug: record.project, key, pollMs: opts.pollMs }, deps);
+  const worker = await createWorker({ runId: opts.runId, repoRoot, cfg, runRootDir, slug: record.project, key, pollMs: opts.pollMs, guardRunRecordPath: runRecordPath(opts.runId) }, deps);
   return { ...worker, repoRoot, runRootDir };
 }
 

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