@codedology/code-forge 0.12.0 → 0.13.0

package/src/util/forbidden.mjs

@@ -790,6 +790,10 @@ export function renderForCodex(list = FORBIDDEN) {
  * `$ cat ~/.code-forge/runs/r.key`, `Write(.code-forge/reviews/x.json)`, a stream-json
  * `"name":"Write"` followed by the path — is found. It is a grep: a line that merely MENTIONS a
  * forbidden command is a hit too (fail closed; the block gate reports it as `rule_break`, B5).
+ * Codex `exec --json` logs (every non-empty line an object with a string `type`, first event
+ * `thread.started`) scan command_execution commands and file_change paths as writes. Other
+ * items scan whole, except agent_message and reasoning; a command_execution's aggregated_output
+ * is never scanned; non-item events are skipped. Any other log uses the plain-text grep above, unchanged.
  *
  * Linear in the line length: `contains` and `path` entries are evaluated ONCE per line over its
  * tokens (a `write` path entry hits when a write command starts before a token naming the path);
@@ -801,6 +805,17 @@ export function renderForCodex(list = FORBIDDEN) {
  * @returns {{id: string, line: number}[]}
  */
 export function scanTranscript(text, list = FORBIDDEN) {
+  const lines = String(text).split('\n');
+  /** @type {any[] | null} */
+  let events = null;
+  try {
+    const parsed = lines.map((line) => line.trim() === '' ? undefined : JSON.parse(line));
+    const nonEmpty = parsed.filter((event) => event !== undefined);
+    if (nonEmpty[0]?.type === 'thread.started' && nonEmpty.every((event) =>
+      event !== null && typeof event === 'object' && !Array.isArray(event) && typeof event.type === 'string')) events = parsed;
+  } catch {
+    // One bad JSONL line makes the entire transcript a plain-text, fail-closed grep.
+  }
   const commandEntries = list.filter((e) => e.kind === 'prefix' || e.kind === 'commandFlag' || e.kind === 'anyPrefix');
   const firstWords = new Set(['npx', 'bunx', 'pnpm', 'yarn', 'node']);
   for (const e of commandEntries) {
@@ -811,9 +826,21 @@ export function scanTranscript(text, list = FORBIDDEN) {
   const writeStarts = new Set([...WRITE_VERBS, ...WRAPPERS, 'sed', 'perl', 'git']);
   /** @type {{id: string, line: number}[]} */
   const hits = [];
-  String(text)
-    .split('\n')
+  lines
     .forEach((lineText, index) => {
+      if (events !== null) {
+        const event = events[index];
+        if (!event?.type.startsWith('item.') || !event.item) return;
+        const item = event.item;
+        if (item.type === 'agent_message' || item.type === 'reasoning') return;
+        // a command that is not a string is scanned with the rest of its item (fail closed), its output left out
+        if (item.type === 'command_execution') lineText = typeof item.command === 'string' ? item.command : JSON.stringify({ ...item, aggregated_output: undefined });
+        else if (item.type === 'file_change') {
+          lineText = (Array.isArray(item.changes) ? item.changes : [])
+            .filter((change) => typeof change?.path === 'string')
+            .map((change) => `Write(${JSON.stringify(change.path)})`).join(' ');
+        } else lineText = JSON.stringify(item);
+      }
       const tokens = lineText.split(/(>>?)|[\s'"`;|&(),{}[\]]+/).filter((t) => typeof t === 'string' && t.length > 0);
       const ids = new Set();
       let firstWrite = -1;

package/src/worker/engine.mjs

@@ -107,7 +107,7 @@ import { blockTree, worktreeRecord } from '../proof/worktree.mjs';
 import { ledgerSchemaHistory } from '../review/schema-fallback.mjs';
 import { verifyRow } from '../state/signer.mjs';
 import { redact } from '../util/redact.mjs';
-import { keyedLock } from '../util/locks.mjs';
+import { withLock } from '../util/file-locks.mjs';
 import { blockAnchors, blockRungUsed, loadState, RESTORED_EVENT, saveState } from './review-state.mjs';
 import { assertAnswers } from './queue.mjs';
 import { assertTicketId, contentHash, readRegularFileNoFollow, WorkerError } from './ticket.mjs';
@@ -536,7 +536,7 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, ownedKinds, block
   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>}} */
-  const prepared = await keyedLock(blockLockKey(ctx.runId, ticket.block), async () => {
+  const prepared = await withLock(blockLockKey(ctx.runId, ticket.block), async () => {
     let rows;
     try {
       rows = (await readRows()).filter((r) => r?.run === ctx.runId);

package/src/worker/loop.mjs

@@ -21,8 +21,9 @@
  * snapshots (or none) keeps the config the worker booted with.
  *
  * Ticket pool (B42): the worker runs up to `review.parallel_tickets` (default 3, 1–16) tickets at
- * once, oldest first; when one ends the next pending one starts. Two tickets for the same
- * (block, file) never overlap (a file lock; the later one stays pending without taking a slot),
+ * once, oldest first (or fewest running per block with `review.fair_share`); when one ends the
+ * next pending one starts. Two tickets for the same (block, file) never overlap (a file lock;
+ * the later one stays pending without taking a slot),
  * and the engine takes the block's budget row and L3 rung under a block lock (`engine.mjs`). A
  * throw in one ticket is that ticket's `unavailable` result and never stops the others. `stop()`
  * starts no new ticket and waits for the running ones. With 1 the worker runs exactly as before.
@@ -49,13 +50,13 @@ 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';
-import { keyedLock } from '../util/locks.mjs';
+import { withLock, tryLock } from '../util/file-locks.mjs';
 import { redact, writeSafe } from '../util/redact.mjs';
 import { runRoot, setRunRoot } from '../util/tmp.mjs';
 import { openFindings } from '../review/gate-check.mjs';
 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 { announceWorker, beatWorker, HEARTBEAT_MS, isDone, liveWorker, pendingTickets, readTicket, retractWorker, workerRegistry, writeResult } from './queue.mjs';
 import { DELETED_HASH, hashBytes, readRegularFileNoFollow, repoRootOf, WorkerError } from './ticket.mjs';
 import { watchTick } from './watch.mjs';
 
@@ -234,6 +235,7 @@ export function recordedVerdict(result) {
  * @property {typeof reviewTicket} [review] - the engine hook (default `./engine.mjs`).
  * @property {typeof spawnSession} [spawn]
  * @property {typeof readRun} [readRun] - the run-record read behind the per-ticket config (a test seam).
+ * @property {{beforeLock?: () => void, afterCount?: (count: number) => Promise<unknown>}} [hooks] - deterministic boot races.
  * @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.
@@ -277,6 +279,8 @@ export async function createWorker(opts, deps = {}) {
   let stopping = false;
   /** @type {ReturnType<typeof setInterval> | null} */
   let heartbeat = null;
+  /** @type {ReturnType<typeof announceWorker> | null} */
+  let self = null;
   /** @type {(() => void) | null} */
   let wake = null;
   /** @type {(() => void) | null} wakes the pool's wait in `drain` (stop) */
@@ -416,7 +420,7 @@ export async function createWorker(opts, deps = {}) {
       // read, advanced and saved by one ticket at a time; the later one waits here. The key
       // carries the run so two workers in one process (tests) never share a lock.
       const t = ticket;
-      result = await keyedLock(`${runId}\0${fileLockKey(t.block, t.file)}`, () => reviewOne(id, t));
+      result = await withLock(`${runId}\0${fileLockKey(t.block, t.file)}`, () => reviewOne(id, t));
     }
     // Stopping: a ticket whose session our own stop killed ends `unavailable` — leave it queued
     // (no done marker) for the next worker instead of recording the kill as a failure. A ticket
@@ -532,50 +536,50 @@ export async function createWorker(opts, deps = {}) {
   }
 
   /**
-   * B42: how many tickets run at once — `review.parallel_tickets` of the snapshot in force (so a
-   * `run reload` resizes the pool at the next drain), else of the boot config; anything but an
-   * integer 1–16 is the default.
-   * @returns {Promise<number>}
+   * Pool settings from the snapshot in force, else the boot config. A run reload applies at the
+   * next drain; anything but an integer 1–16 uses the default size.
+   * @returns {Promise<{limit: number, fairShare: boolean}>}
    */
-  async function poolSize() {
+  async function poolSettings() {
     let current = cfg;
     try {
       current = await configFor('');
     } catch {
-      // an unreadable record: the boot config's size (each ticket still fails closed on its own)
+      // an unreadable record: the boot settings (each ticket still fails closed on its own)
     }
-    return parallelTickets(current);
+    return { limit: parallelTickets(current), fairShare: current?.review?.fair_share === true };
   }
 
   /**
-   * The (block, file) key of each ticket read so far, by id: a written ticket never changes (its
-   * id is its content's hash), so it is read once for scheduling, however many wake-ups it waits.
+   * The block and (block, file) key of each ticket read so far, by id. A written ticket never
+   * changes (its id is its content's hash), so scheduling reads it once across wake-ups.
    * Dropped once the ticket is done.
-   * @type {Map<string, string>}
+   * @type {Map<string, {key: string, block: string}>}
    */
   const fileKeys = new Map();
 
   /**
-   * The (block, file) a pending ticket names, or null when it cannot be read (it is started
+   * The block and file-lock key a pending ticket names, or null when unreadable (it is started
    * anyway and refused by `processTicket`; a null is not cached). Only a scheduling hint:
    * `processTicket` takes the file lock on the ticket it actually read.
-   * @param {string} id @returns {string | null}
+   * @param {string} id @returns {{key: string, block: string} | null}
    */
   function fileKeyOf(id) {
     const known = fileKeys.get(id);
     if (known !== undefined) return known;
     try {
       const t = loadTicket(repoRoot, id);
-      const key = fileLockKey(t.block, t.file);
-      fileKeys.set(id, key);
-      return key;
+      const file = { key: fileLockKey(t.block, t.file), block: t.block };
+      fileKeys.set(id, file);
+      return file;
     } catch {
       return null;
     }
   }
 
   /**
-   * Serve every pending ticket (B42): up to `review.parallel_tickets` at once, oldest first; when
+   * Serve every pending ticket (B42): up to `review.parallel_tickets` at once, oldest first; with
+   * fair share, each slot goes to the block with fewest running tickets, ties oldest first. When
    * one finishes, the queue is re-read and the next pending ticket starts (no batch barrier; the
    * queue is also re-read every `pollMs` while tickets run, so a new ticket fills a free slot).
    * A ticket whose (block, file) is already running is left pending (it does not take a slot)
@@ -600,11 +604,14 @@ export async function createWorker(opts, deps = {}) {
     }
     /** @type {number | null} */
     let limit = null;
+    let fairShare = false;
     let done = 0;
     /** @type {Map<string, Promise<void>>} */
     const running = new Map();
     /** @type {Set<string>} the (block, file) keys of the running tickets */
     const busy = new Set();
+    /** @type {Map<string, number>} running tickets per block */
+    const runningByBlock = new Map();
     /** @type {Set<string>} */
     const started = new Set();
     for (;;) {
@@ -630,25 +637,54 @@ export async function createWorker(opts, deps = {}) {
           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();
-          if (running.size >= limit || stopping) break;
-          const fileKey = fileKeyOf(id);
-          if (fileKey !== null && busy.has(fileKey)) continue; // waits without a slot
+        const pending = pendingTickets(repoRoot).filter((id) => !poisoned.has(id) && !started.has(id));
+        if (pending.length > 0 && limit === null) ({ limit, fairShare } = await poolSettings());
+        // Cache even unreadable hints for this tick: ranking never reads a ticket twice.
+        /** @type {Map<string, ReturnType<typeof fileKeyOf>>} */
+        const hints = new Map();
+        while (pending.length > 0 && running.size < limit && !stopping) {
+          let next = -1;
+          let fewest = Infinity;
+          for (let i = 0; i < pending.length; i += 1) {
+            const id = pending[i];
+            if (!hints.has(id)) hints.set(id, fileKeyOf(id));
+            const file = hints.get(id);
+            if (file && busy.has(file.key)) continue; // waits without a slot
+            const count = fairShare && file ? runningByBlock.get(file.block) ?? 0 : 0;
+            if (count < fewest) {
+              next = i;
+              fewest = count;
+            }
+            if (count === 0) break; // best possible count; ties stay oldest first
+          }
+          if (next === -1) break;
+          const [id] = pending.splice(next, 1);
+          const claim = await tryLock(`ticket\0${runId}\0${id}`);
+          if (!claim.ok) continue; // another process owns it; no pool slot is taken
+          // Acquisition awaited a process probe: another worker may have completed this ticket
+          // since the pending snapshot, or stop() may have arrived while we waited.
+          if (stopping || isDone(repoRoot, id)) {
+            claim.release();
+            continue;
+          }
+          const file = hints.get(id);
+          const fileKey = file?.key ?? null;
           started.add(id);
           activeTickets.add(id);
           if (fileKey !== null) busy.add(fileKey);
+          if (file) runningByBlock.set(file.block, (runningByBlock.get(file.block) ?? 0) + 1);
           const slot = runOne(id)
             .then((n) => {
               done += n;
             })
             .finally(() => {
+              claim.release(); // the done marker is published before the claim is released
               // 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);
+              if (file) runningByBlock.set(file.block, runningByBlock.get(file.block) - 1);
             });
           running.set(id, slot);
         }
@@ -684,7 +720,8 @@ export async function createWorker(opts, deps = {}) {
    * must still see the worker as live the whole time.
    */
   function announce() {
-    const self = announceWorker(repoRoot, { pid: process.pid, run: runId });
+    if (self !== null) return; // boot already announced under the lock
+    self = announceWorker(repoRoot, { pid: process.pid, run: runId });
     stopBeating();
     const timer = setInterval(() => {
       try {
@@ -749,12 +786,16 @@ export async function createWorker(opts, deps = {}) {
   /** Withdraw this process's announcement (`worker.json`) if it is still ours. */
   function release() {
     stopBeating();
-    retractWorker(repoRoot, process.pid);
+    if (self !== null) retractWorker(repoRoot, self.pid, self.start_time);
+    self = null;
   }
 
-  return { processTicket, drain, run, once, stop, release, watchTick: tickWatch, jevKeyResolved: jevKey !== null, sessionEnv: childEnv };
+  return { processTicket, drain, run, once, stop, release, announce, watchTick: tickWatch, jevKeyResolved: jevKey !== null, sessionEnv: childEnv };
 }
 
+/** This block permits one registered worker per queue. */
+const WORKER_LIMIT = 1;
+
 /**
  * Start-up for the `worker` verb: run record, repo root, config, run temp root (owned by this
  * process), run key; refuses when another live worker already serves this queue.
@@ -777,13 +818,22 @@ export async function bootWorker(opts, deps = {}) {
     if (!loaded.ok) throw new WorkerError('config', loaded.message ?? 'the project config cannot be loaded');
     cfg = loaded.config;
   }
-  const other = liveWorker(repoRoot);
-  if (other && other.pid !== process.pid) throw new WorkerError('worker-running', `worker pid ${other.pid} already serves this queue`);
   const tmpRoot = typeof cfg?.tmp?.root === 'string' ? cfg.tmp.root : undefined;
   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, guardRunRecordPath: runRecordPath(opts.runId) }, deps);
+  deps.hooks?.beforeLock?.();
+  await withLock(`worker-boot:${repoRoot}`, async () => {
+    const entries = workerRegistry(repoRoot, { prune: true });
+    let count = entries.filter((entry) => entry.live).length;
+    // Older workers have only worker.json; do not boot over a live legacy owner.
+    const legacy = liveWorker(repoRoot);
+    if (legacy && !entries.some((entry) => entry.worker?.pid === legacy.pid && entry.worker.start_time === legacy.start_time)) count++;
+    await deps.hooks?.afterCount?.(count);
+    if (count >= WORKER_LIMIT) throw new WorkerError('worker-running', 'a live or unreadable worker entry already serves this queue');
+    worker.announce();
+  });
   return { ...worker, repoRoot, runRootDir };
 }
 
@@ -826,7 +876,7 @@ export async function launchWorker({ runId, workspace, env = process.env, timeou
   child.unref();
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    if (typeof pid === 'number' && liveWorker(repoRoot)?.pid === pid) return { pid, repoRoot };
+    if (typeof pid === 'number' && liveWorker(repoRoot, { pid, registeredOnly: true })) return { pid, repoRoot };
     if (child.exitCode !== null || child.signalCode !== null) break;
     await new Promise((resolve) => setTimeout(resolve, 50));
   }

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 });
@@ -427,6 +432,36 @@ export function blockTickets({ repoRoot, run, block, tree = null }) {
     .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
@@ -468,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;
 }
 
@@ -497,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.
@@ -520,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). */
@@ -560,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;
 }
 
 /**
@@ -574,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

@@ -99,10 +99,12 @@ export async function watchTick({ repoRoot, runId, cfg, readRun: loadRun = readR
       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 });
+        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.ticket !== current.ticket && !running.has(old.ticket) && !isDone(repoRoot, old.ticket)) supersedeTicket(repoRoot, old.ticket);
+          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 {