@codedology/code-forge 0.11.0 → 0.13.0

package/src/worker/queue.mjs

@@ -5,6 +5,7 @@
  *   <repo>/.code-forge/queue/<ticket>.json   the ticket (written by `review-file`, idempotent)
  *   <repo>/.code-forge/queue/<ticket>.done   the worker's done marker `{ticket, status, result}`
  *   <repo>/.code-forge/queue/worker.json     the worker's announcement `{pid, start_time, run, started_at, heartbeat_at}`
+ *   <repo>/.code-forge/workers/<pid>-<start_time>.json   each worker's private registry entry
  *   <repo>/.code-forge/reviews/<run>/<ticket>.json   the SIGNED result (run key HMAC, §8.6)
  *
  * The forbidden list (§8.4 ★) denies a coder any write under `reviews/` and to `queue/*.done`;
@@ -28,7 +29,7 @@
  */
 
 import { createHash, randomBytes } from 'node:crypto';
-import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { loadKey, signRow, verifyRow } from '../state/signer.mjs';
 import { isAlive, readStartTime, UNKNOWN_START_TIME } from '../util/reaper.mjs';
@@ -44,15 +45,19 @@ export const HEARTBEAT_STALE_MS = 60_000;
 
 /** @param {string} repoRoot */
 export const queueDir = (repoRoot) => path.join(repoRoot, '.code-forge', 'queue');
+/** @param {string} repoRoot */
+const workersDir = (repoRoot) => path.join(repoRoot, '.code-forge', 'workers');
+/** @param {string} repoRoot @param {{pid: number, start_time: string}} self */
+const workerPath = (repoRoot, self) => path.join(workersDir(repoRoot), `${self.pid}-${self.start_time}.json`);
 /** @param {string} repoRoot @param {string} runId */
 export const reviewsDir = (repoRoot, runId) => path.join(repoRoot, '.code-forge', 'reviews', runId);
 
-/** @param {string} file @param {string} text */
-function writeAtomic(file, text) {
+/** @param {string} file @param {string} text @param {number} [mode] */
+function writeAtomic(file, text, mode = 0o644) {
   mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
   try {
-    writeFileSync(tmp, text, { mode: 0o644 });
+    writeFileSync(tmp, text, { mode });
     renameSync(tmp, file);
   } catch (err) {
     rmSync(tmp, { force: true });
@@ -102,17 +107,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 +413,55 @@ 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));
+}
+
+/**
+ * Atomically record the join's findings handoff once. Read only this marker, never a result.
+ * @param {{repoRoot: string, block: string, file: string, ticket: string}} opts
+ * @returns {boolean} true only for the join that first delivered the findings.
+ */
+export function deliverBlockFindings({ repoRoot, block, file, ticket }) {
+  const marker = path.join(queueDir(repoRoot), `${assertTicketId(ticket)}.delivered`);
+  const expected = { block, file, ticket };
+  const delivered = () => {
+    try {
+      const seen = JSON.parse(readFileSync(marker, 'utf8'));
+      if (seen?.block === block && seen.file === file && seen.ticket === ticket) return true;
+    } catch (err) {
+      if (err.code === 'ENOENT') return false;
+    }
+    throw new WorkerError('result-unreadable', 'a findings delivery marker cannot be read');
+  };
+  if (delivered()) return false;
+  const tmp = `${marker}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(expected)}\n`, { flag: 'wx' });
+    try { linkSync(tmp, marker); } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      if (delivered()) return false;
+      throw new WorkerError('result-unreadable', 'a findings delivery marker disappeared');
+    }
+    return true;
+  } finally { rmSync(tmp, { force: true }); }
+}
+
 /**
  * Read and re-validate a ticket (coder-writable): its id must match its content.
  * @param {string} repoRoot @param {string} id
@@ -410,7 +503,8 @@ export function writeResult({ repoRoot, runId, ticket, result, key }) {
   const signed = signRow({ ...result, run: runId, ticket: assertTicketId(ticket) }, key);
   const file = path.join(reviewsDir(repoRoot, runId), `${ticket}.json`);
   writeAtomic(file, `${JSON.stringify(signed)}\n`);
-  writeAtomic(path.join(queueDir(repoRoot), `${ticket}.done`), `${JSON.stringify({ ticket, status: signed.status, result: path.relative(repoRoot, file) })}\n`);
+  const openFindings = signed.status === 'reviewed' && signed.approved !== true && Array.isArray(signed.findings) && signed.findings.length > 0;
+  writeAtomic(path.join(queueDir(repoRoot), `${ticket}.done`), `${JSON.stringify({ ticket, status: signed.status, ...(openFindings ? { open_findings: true } : {}), result: path.relative(repoRoot, file) })}\n`);
   return signed;
 }
 
@@ -439,20 +533,25 @@ export async function verifyResult(repoRoot, runId, ticket) {
 }
 
 /**
- * Announce the serving worker in the queue directory (what `review-file` checks for liveness).
+ * Announce the serving worker in the private registry and legacy queue file.
  * @param {string} repoRoot @param {{pid: number, run: string}} who
  */
 export function announceWorker(repoRoot, { pid, run }) {
   const now = new Date().toISOString();
   const body = { pid, start_time: readStartTime(pid) ?? UNKNOWN_START_TIME, run, started_at: now, heartbeat_at: now };
-  writeAtomic(path.join(queueDir(repoRoot), WORKER_FILE), `${JSON.stringify(body)}\n`);
+  mkdirSync(workersDir(repoRoot), { recursive: true, mode: 0o700 });
+  chmodSync(workersDir(repoRoot), 0o700);
+  writeAtomic(workerPath(repoRoot, body), `${JSON.stringify(body)}\n`, 0o600);
+  const legacy = readWorker(repoRoot);
+  if (!legacy || !workerLive(legacy)) writeAtomic(path.join(queueDir(repoRoot), WORKER_FILE), `${JSON.stringify(body)}\n`);
   return body;
 }
 
 /**
- * Refresh the announcement's `heartbeat_at` (B30) while it is still THIS worker's: the file is
+ * Refresh both announcements' `heartbeat_at` (B30) while each is still THIS worker's: each file is
  * re-read right before the write and must name the same `pid` AND `start_time` the worker
- * announced. Another worker's announcement is never overwritten (the caller stops beating).
+ * announced. Another worker's announcement is never overwritten. A worker keeps beating its
+ * registry entry even when another worker owns worker.json.
  * The beat is written to a temp file, the announcement re-read and compared once more, and only
  * then renamed over it. The worker calls this from a timer of its own, so it keeps beating while
  * a long review session is awaited.
@@ -462,23 +561,23 @@ export function announceWorker(repoRoot, { pid, run }) {
  */
 export function beatWorker(repoRoot, self, now = new Date()) {
   const mine = (/** @type {Record<string, any> | null} */ w) => w?.pid === self.pid && w.start_time === self.start_time;
-  const w = readWorker(repoRoot);
-  if (!mine(w)) return false;
-  const file = path.join(queueDir(repoRoot), WORKER_FILE);
-  const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
-  try {
-    writeFileSync(tmp, `${JSON.stringify({ ...w, heartbeat_at: now.toISOString() })}\n`, { mode: 0o644 });
-    // re-read right before the rename: an announcement that changed meanwhile is never replaced
-    if (!mine(readWorker(repoRoot))) {
+  let written = false;
+  const registryFile = workerPath(repoRoot, self);
+  for (const file of [registryFile, path.join(queueDir(repoRoot), WORKER_FILE)]) {
+    const w = readJSON(file);
+    if (!mine(w)) continue;
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+      writeFileSync(tmp, `${JSON.stringify({ ...w, heartbeat_at: now.toISOString() })}\n`, { mode: file === registryFile ? 0o600 : 0o644 });
+      // Re-read before rename; another owner's announcement is never replaced.
+      if (!mine(readJSON(file))) continue;
+      renameSync(tmp, file);
+      written = true;
+    } finally {
       rmSync(tmp, { force: true });
-      return false;
     }
-    renameSync(tmp, file);
-    return true;
-  } catch (err) {
-    rmSync(tmp, { force: true });
-    throw err;
   }
+  return written;
 }
 
 /** A heartbeat further than this in the future is not fresh (clock skew tolerance). */
@@ -502,9 +601,59 @@ export function readWorker(repoRoot) {
   return w && Number.isInteger(w.pid) && w.pid > 1 && typeof w.run === 'string' ? w : null;
 }
 
-/** Remove the announcement if it is still `pid`'s. @param {string} repoRoot @param {number} pid */
-export function retractWorker(repoRoot, pid) {
-  if (readWorker(repoRoot)?.pid === pid) rmSync(path.join(queueDir(repoRoot), WORKER_FILE), { force: true });
+/** Remove only this owner's announcements. @param {string} repoRoot @param {number} pid @param {string} [startTime] */
+export function retractWorker(repoRoot, pid, startTime) {
+  const mine = (w) => w?.pid === pid && (startTime === undefined || w.start_time === startTime);
+  for (const entry of workerRegistry(repoRoot)) {
+    if (mine(entry.worker)) rmSync(entry.file, { force: true });
+  }
+  if (mine(readWorker(repoRoot))) rmSync(path.join(queueDir(repoRoot), WORKER_FILE), { force: true });
+}
+
+/** @typedef {{pid: number, start_time: string, run: string, started_at: string, heartbeat_at: string}} WorkerAnnouncement */
+
+/** Bad entries remain occupied until a human fixes them. @param {any} w @returns {w is WorkerAnnouncement} */
+function workerShape(w) {
+  return w && Number.isInteger(w.pid) && w.pid > 1 && typeof w.start_time === 'string' && w.start_time.length > 0
+    && !/[\\/]/.test(w.start_time) && typeof w.run === 'string' && w.run.length > 0
+    && typeof w.started_at === 'string' && Number.isFinite(Date.parse(w.started_at))
+    && typeof w.heartbeat_at === 'string' && Number.isFinite(Date.parse(w.heartbeat_at));
+}
+
+/** @param {{pid: number, start_time: string, heartbeat_at?: string}} w @param {number} [nowMs] */
+function workerLive(w, nowMs) {
+  if (!isAlive(w.pid)) return false;
+  if (heartbeatFresh(w, nowMs)) return true;
+  return w.start_time === UNKNOWN_START_TIME || readStartTime(w.pid) === w.start_time;
+}
+
+/** @param {{pid: number, start_time: string, heartbeat_at?: string}} w @param {number} [nowMs] */
+function workerLiveAtBoot(w, nowMs) {
+  if (!isAlive(w.pid)) return false;
+  const startTime = readStartTime(w.pid);
+  // Boot trusts orchestrator ps; sandbox readers let fresh heartbeats mask unreliable ps.
+  if (startTime !== null && w.start_time !== UNKNOWN_START_TIME) return startTime === w.start_time;
+  return heartbeatFresh(w, nowMs) || w.start_time === UNKNOWN_START_TIME;
+}
+
+/** Read all entries, keeping unreadable/bad entries occupied. Only proven stale owners may be pruned.
+ * @param {string} repoRoot @param {{prune?: boolean, nowMs?: number}} [opts]
+ * @returns {Array<{file: string, worker: WorkerAnnouncement | null, live: boolean}>}
+ */
+export function workerRegistry(repoRoot, opts = {}) {
+  let names;
+  try { names = readdirSync(workersDir(repoRoot)); }
+  catch (err) { if (err.code === 'ENOENT') return []; throw err; }
+  const entries = [];
+  for (const name of names.sort().filter((n) => n.endsWith('.json'))) {
+    const file = path.join(workersDir(repoRoot), name);
+    const w = readJSON(file);
+    const worker = workerShape(w) && name === `${w.pid}-${w.start_time}.json` ? w : null;
+    const live = worker === null || (opts.prune ? workerLiveAtBoot(worker, opts.nowMs) : workerLive(worker, opts.nowMs));
+    if (!live && opts.prune) rmSync(file, { force: true });
+    else entries.push({ file, worker, live });
+  }
+  return entries;
 }
 
 /**
@@ -516,13 +665,14 @@ export function retractWorker(repoRoot, pid) {
  * Accepted trade-off: a worker that is SIGKILLed (no retraction) leaves a heartbeat that stays
  * fresh for up to `HEARTBEAT_STALE_MS` (60 s); if the OS reuses its pid inside that window, the
  * queue reads as served until the heartbeat goes stale. A clean stop retracts the file at once.
- * @param {string} repoRoot @param {{nowMs?: number}} [opts]
+ * Registry entries take precedence; worker.json supports workers from older versions.
+ * @param {string} repoRoot @param {{nowMs?: number, pid?: number, registeredOnly?: boolean}} [opts]
  */
 export function liveWorker(repoRoot, opts = {}) {
+  const entry = workerRegistry(repoRoot, opts).find((e) => e.live && e.worker && (opts.pid === undefined || e.worker.pid === opts.pid));
+  if (entry) return entry.worker;
+  if (opts.registeredOnly) return null;
   const w = readWorker(repoRoot);
-  if (!w || !isAlive(w.pid)) return null;
-  if (heartbeatFresh(w, opts.nowMs)) return w;
-  if (w.start_time !== UNKNOWN_START_TIME && readStartTime(w.pid) !== w.start_time) return null;
-  return w;
+  return w && (opts.pid === undefined || w.pid === opts.pid) && workerLive(w, opts.nowMs) ? w : null;
 }
 

package/src/worker/watch.mjs

@@ -0,0 +1,115 @@
+/** 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 held = earlier.some((old) => old.file === file);
+        if (!held) enqueueHash({ repoRoot, run: runId, block, file, content_hash, tree });
+        for (const old of earlier) {
+          if (old.file === file && old.content_hash !== content_hash && !running.has(old.ticket) && !isDone(repoRoot, old.ticket)) supersedeTicket(repoRoot, old.ticket);
+        }
+        if (held) await writeRow({ event: 'watch.held', block, file, content_hash });
+      }
+      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');
+    }
+  }
+}