@codedology/code-forge 0.3.2 → 0.5.0

package/src/worker/loop.mjs

@@ -14,9 +14,23 @@
  * Then it polls the queue, hands each ticket to the engine hook (`./engine.mjs`, B12a), signs the
  * outcome with the run key and writes it with its done marker and a signed ledger row.
  *
+ * Config (B35): the worker reviews each ticket with the run's config snapshot, read from the run
+ * record per ticket — the ticket's pin when `run reload` pinned it (it was queued before the
+ * reload), else the snapshot in force. So `run reload` reaches the worker without a restart, and a
+ * restarted worker boots on the snapshot, not on whatever the file says now. A record from before
+ * 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),
+ * 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.
+ *
  * Restart: tickets live on disk and are idempotent by content hash, so a new worker simply re-reads
- * every ticket without a done marker. A worker that is stopping abandons its in-flight ticket (no
- * done marker) instead of recording the killed session as a failure. The new worker's pid is
+ * every ticket without a done marker. A worker that is stopping waits for its in-flight tickets: one
+ * whose session the stop killed (an `unavailable` outcome) is abandoned (no done marker) instead of
+ * recorded as a failure; one that reached a real outcome is recorded. The new worker's pid is
  * re-pinned in the run record by the orchestrator (`repinWorker`, = `run start --reattach`).
  */
 
@@ -27,18 +41,46 @@ import { loadProjectConfig } from '../config/load.mjs';
 import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { spawnSession } from '../session/spawn.mjs';
+import { snapshotFor } from '../state/config-snapshot.mjs';
 import { readRun, reattachWorker } from '../state/run.mjs';
 import { loadKey, signRow } from '../state/signer.mjs';
+import { keyedLock } from '../util/locks.mjs';
 import { runRoot, setRunRoot } from '../util/tmp.mjs';
 import { reviewTicket } from './engine.mjs';
-import { announceWorker, liveWorker, pendingTickets, readTicket, retractWorker, writeResult } from './queue.mjs';
+import { announceWorker, beatWorker, HEARTBEAT_MS, liveWorker, pendingTickets, readTicket, retractWorker, writeResult } from './queue.mjs';
 import { contentHash, DELETED_HASH, repoRootOf, WorkerError } from './ticket.mjs';
 
 /** Name of the key the worker resolves for System 1 (`keys.jev` / `system1.key` reference). */
 export const JEV_KEY_NAME = 'jev';
 
 export const DEFAULT_POLL_MS = 250;
-export const DEFAULT_SESSION_TIMEOUT_S = 600;
+export const DEFAULT_SESSION_TIMEOUT_S = 300;
+
+/** B42: `review.parallel_tickets` when the config does not set a valid one. */
+export const DEFAULT_PARALLEL_TICKETS = 3;
+export const MAX_PARALLEL_TICKETS = 16;
+
+/**
+ * How many tickets the worker runs at once: `review.parallel_tickets` when it is an integer
+ * 1–16, else `DEFAULT_PARALLEL_TICKETS`.
+ * @param {Record<string, any> | null | undefined} cfg @returns {number}
+ */
+export function parallelTickets(cfg) {
+  const n = cfg?.review?.parallel_tickets;
+  return Number.isInteger(n) && n >= 1 && n <= MAX_PARALLEL_TICKETS ? n : DEFAULT_PARALLEL_TICKETS;
+}
+
+/**
+ * The key of the file lock a ticket takes (B42): one ticket per (block, file) at a time.
+ * @param {string} block @param {string} file @returns {string}
+ */
+export const fileLockKey = (block, file) => `${block}\0${file}`;
+
+/** B35: how long `configFor` waits before its one retry of a failed run-record read. */
+export const CONFIG_RETRY_MS = 200;
+
+/** The shortest heartbeat interval a worker accepts; anything else falls back to `HEARTBEAT_MS`. */
+export const MIN_HEARTBEAT_MS = 100;
 
 /**
  * Provider-CLI auth variables a reviewer CLI may legitimately need (the reviewer runs on the
@@ -104,12 +146,16 @@ export function loopResult(outcome) {
  * @property {string} slug - ledger project slug (the run record's `project`).
  * @property {Buffer} key - the run's HMAC key.
  * @property {number} [pollMs]
+ * @property {number} [heartbeatMs] - how often `heartbeat_at` is refreshed: an integer ≥ `MIN_HEARTBEAT_MS`,
+ *   else `HEARTBEAT_MS`.
  */
 
 /**
  * @typedef {object} WorkerDeps
  * @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 {typeof readTicket} [readTicket] - the ticket read (a test seam).
  * @property {import('../keys/store.mjs').KeyStore} [store] - default: B2's production store.
  * @property {any} [opRead]
  * @property {NodeJS.ProcessEnv} [env]
@@ -130,20 +176,95 @@ export async function createWorker(opts, deps = {}) {
   const env = deps.env ?? process.env;
   const review = deps.review ?? reviewTicket;
   const spawn = deps.spawn ?? spawnSession;
+  const loadRun = deps.readRun ?? readRun;
+  const loadTicket = deps.readTicket ?? readTicket;
   const writeRow = deps.writeRow ?? ((/** @type {Record<string, any>} */ row) => appendRow(row, { slug }));
   const readRows = deps.readRows ?? (() => readAllRows(slug));
   const store = deps.store ?? (await createDefaultKeyStore(env));
   const jevKey = await resolveJevKey(cfg, { store, env, opRead: deps.opRead });
   const childEnv = sessionEnv(env, [jevKey, key.toString('hex')]);
-  const timeoutS = Number.isInteger(cfg?.review?.session_timeout_s) && cfg.review.session_timeout_s > 0 ? cfg.review.session_timeout_s : DEFAULT_SESSION_TIMEOUT_S;
   const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+  const heartbeatMs = Number.isInteger(opts.heartbeatMs) && /** @type {number} */ (opts.heartbeatMs) >= MIN_HEARTBEAT_MS ? /** @type {number} */ (opts.heartbeatMs) : HEARTBEAT_MS;
   let stopping = false;
+  /** @type {ReturnType<typeof setInterval> | null} */
+  let heartbeat = null;
   /** @type {(() => void) | null} */
   let wake = null;
+  /** @type {(() => void) | null} wakes the pool's wait in `drain` (stop) */
+  let poolWake = null;
 
   /** @param {Record<string, any>} row */
   const ledger = (row) => writeRow(signRow({ run: runId, ...row }, key));
 
+  /**
+   * The config ticket `id` is reviewed with (B35): its snapshot from the run record, re-read per
+   * ticket; the boot `cfg` when the run has no record or the record has no snapshot.
+   * @param {string} id
+   * @returns {Promise<Record<string, any>>}
+   * @throws {Error} `config-snapshot` — a record that cannot be read, or a missing/altered snapshot.
+   */
+  async function configFor(id) {
+    // The Jev key and the run root were settled at boot from `cfg`; a reload can never change
+    // them, because `keys`, `system1.key` and `tmp.root` are fixed keys `run reload` refuses.
+    let record;
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        record = await loadRun(runId);
+        break;
+      } catch (err) {
+        if (/** @type {any} */ (err)?.code === 'no-run') return cfg;
+        // a transient read error (e.g. the record caught mid-replace) gets ONE retry
+        if (attempt >= 2) throw new Error('config-snapshot');
+        await new Promise((resolve) => setTimeout(resolve, CONFIG_RETRY_MS));
+      }
+    }
+    return snapshotFor(record, id)?.config ?? cfg;
+  }
+
+  /**
+   * One ticket through the engine hook with `tcfg` (the ticket's config snapshot): the unsigned result.
+   * @param {import('./queue.mjs').Ticket} ticket @param {Record<string, any>} base
+   * @param {Record<string, any>} tcfg
+   * @returns {Promise<Record<string, any>>}
+   */
+  async function reviewWith(ticket, base, tcfg) {
+    const timeoutS = Number.isInteger(tcfg?.review?.session_timeout_s) && tcfg.review.session_timeout_s > 0 ? tcfg.review.session_timeout_s : DEFAULT_SESSION_TIMEOUT_S;
+    /** @type {import('./engine.mjs').ReviewContext} */
+    const ctx = {
+      repoRoot,
+      runId,
+      runRootDir,
+      cfg: tcfg,
+      jevKey,
+      key, // signs the fix-loop state (B12c); the sessions never see it (`childEnv`)
+      readRows,
+      ...(deps.jev ? { jev: deps.jev } : {}),
+      // `sessionOpts.cfg` (a per-call config, e.g. the consensus second reviewer's level) wins
+      // over the ticket's; everything else the worker pins.
+      spawn: (sessionOpts) =>
+        spawn(
+          /** @type {any} */ ({ cfg: tcfg, ...sessionOpts, runRoot: runRootDir, run: runId, block: ticket.block, slug, timeoutMs: timeoutS * 1000 }),
+          { env: childEnv, ...(deps.bins ? { bins: deps.bins } : {}), ...(deps.stderr ? { stderr: deps.stderr } : {}) },
+        ),
+      writeRow: (row) => ledger({ ...row, block: ticket.block, file: ticket.file, content_hash: ticket.content_hash }),
+    };
+    try {
+      const outcome = await review(ticket, ctx);
+      return {
+        ...base,
+        status: outcome.status,
+        approved: outcome.approved === true,
+        engine: outcome.engine,
+        ...(typeof outcome.reason === 'string' ? { reason: outcome.reason } : {}),
+        ...(Array.isArray(outcome.findings) ? { findings: outcome.findings } : {}),
+        ...loopResult(outcome),
+        sessions: outcome.sessions,
+      };
+    } catch {
+      return { ...base, status: 'unavailable', reason: 'engine-error', approved: false };
+    }
+  }
+
   /**
    * @param {string} id
    * @returns {Promise<Record<string, any> | null>} the signed result, or null when abandoned.
@@ -153,68 +274,51 @@ export async function createWorker(opts, deps = {}) {
     let result;
     let ticket = null;
     try {
-      ticket = readTicket(repoRoot, id);
+      ticket = loadTicket(repoRoot, id);
     } catch (err) {
       result = { event: 'review.result', status: 'refused', reason: err instanceof WorkerError ? err.code : 'bad-ticket', approved: false };
     }
     if (ticket) {
-      const base = { event: 'review.result', block: ticket.block, file: ticket.file, content_hash: ticket.content_hash };
-      /** @type {string | null} */
-      let current = null;
-      try {
-        current = ticket.run === runId ? contentHash(repoRoot, ticket.file) : null;
-      } catch (err) {
-        result = { ...base, status: 'refused', reason: err instanceof WorkerError ? err.code : 'unreadable', approved: false };
-      }
-      if (result) {
-        // refused above: the path no longer passes the on-disk check, or the file cannot be read
-      } else if (ticket.run !== runId) {
-        result = { ...base, status: 'refused', reason: 'other-run', approved: false };
-      } else if (current === DELETED_HASH && ticket.content_hash !== DELETED_HASH) {
-        result = { ...base, status: 'stale', reason: 'missing-file', approved: false };
-      } else if (current !== ticket.content_hash) {
-        result = { ...base, status: 'stale', approved: false };
-      } else {
-        /** @type {import('./engine.mjs').ReviewContext} */
-        const ctx = {
-          repoRoot,
-          runId,
-          runRootDir,
-          cfg,
-          jevKey,
-          key, // signs the fix-loop state (B12c); the sessions never see it (`childEnv`)
-          readRows,
-          ...(deps.jev ? { jev: deps.jev } : {}),
-          // `sessionOpts.cfg` (a per-call config, e.g. the consensus second reviewer's level) wins
-          // over the worker's; everything else the worker pins.
-          spawn: (sessionOpts) =>
-            spawn(
-              /** @type {any} */ ({ cfg, ...sessionOpts, runRoot: runRootDir, run: runId, block: ticket.block, slug, timeoutMs: timeoutS * 1000 }),
-              { env: childEnv, ...(deps.bins ? { bins: deps.bins } : {}), ...(deps.stderr ? { stderr: deps.stderr } : {}) },
-            ),
-          writeRow: (row) => ledger({ ...row, block: ticket.block, file: ticket.file, content_hash: ticket.content_hash }),
-        };
-        try {
-          const outcome = await review(ticket, ctx);
-          result = {
-            ...base,
-            status: outcome.status,
-            approved: outcome.approved === true,
-            engine: outcome.engine,
-            ...(typeof outcome.reason === 'string' ? { reason: outcome.reason } : {}),
-            ...(Array.isArray(outcome.findings) ? { findings: outcome.findings } : {}),
-            ...loopResult(outcome),
-            sessions: outcome.sessions,
-          };
-        } catch {
-          result = { ...base, status: 'unavailable', reason: 'engine-error', approved: false };
-        }
-      }
+      // B42: never two tickets for the same (block, file) at once — its fix-loop state (`seq`) is
+      // 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));
     }
-    if (stopping) return null; // the session was killed by our own stop: leave the ticket queued
+    // 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
+    // that reached a real outcome while the pool drained is recorded as usual.
+    if (stopping && result.status === 'unavailable') return null;
     return complete(id, result);
   }
 
+  /**
+   * The unsigned result for a ticket that was read: refused / stale checks, then the review.
+   * @param {string} id @param {import('./queue.mjs').Ticket} ticket
+   * @returns {Promise<Record<string, any>>}
+   */
+  async function reviewOne(id, ticket) {
+    const base = { event: 'review.result', block: ticket.block, file: ticket.file, content_hash: ticket.content_hash };
+    /** @type {string | null} */
+    let current;
+    try {
+      current = ticket.run === runId ? contentHash(repoRoot, ticket.file) : null;
+    } catch (err) {
+      // the path no longer passes the on-disk check, or the file cannot be read
+      return { ...base, status: 'refused', reason: err instanceof WorkerError ? err.code : 'unreadable', approved: false };
+    }
+    if (ticket.run !== runId) return { ...base, status: 'refused', reason: 'other-run', approved: false };
+    if (current === DELETED_HASH && ticket.content_hash !== DELETED_HASH) return { ...base, status: 'stale', reason: 'missing-file', approved: false };
+    if (current !== ticket.content_hash) return { ...base, status: 'stale', approved: false };
+    let ticketCfg;
+    try {
+      ticketCfg = await configFor(id);
+    } catch {
+      return { ...base, status: 'unavailable', reason: 'config-snapshot', approved: false };
+    }
+    return reviewWith(ticket, base, ticketCfg);
+  }
+
   /**
    * Sign and write the result + done marker, then the signed ledger row. A ledger failure does not
    * undo the result: the done marker is what the queue reads.
@@ -243,33 +347,164 @@ export async function createWorker(opts, deps = {}) {
   const poisoned = new Set();
 
   /**
-   * Process every pending ticket once. An unexpected throw on one ticket becomes a signed
-   * `unavailable` result (reason `worker-error`) when that can still be written, and never stops
-   * the loop; a ticket whose failure cannot be written either is skipped for this worker's life.
+   * One ticket in a pool slot: never rejects. An unexpected throw becomes a signed `unavailable`
+   * result (reason `worker-error`) when that can still be written; a ticket whose failure cannot
+   * be written either is poisoned (skipped for this worker's life).
+   * @param {string} id @returns {Promise<number>} 1 when completed, else 0.
+   */
+  async function runOne(id) {
+    try {
+      return (await processTicket(id)) !== null ? 1 : 0;
+    } catch {
+      try {
+        await complete(id, { event: 'review.result', status: 'unavailable', reason: 'worker-error', approved: false });
+        return 1;
+      } catch {
+        poisoned.add(id);
+        return 0;
+      }
+    }
+  }
+
+  /**
+   * 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>}
+   */
+  async function poolSize() {
+    let current = cfg;
+    try {
+      current = await configFor('');
+    } catch {
+      // an unreadable record: the boot config's size (each ticket still fails closed on its own)
+    }
+    return parallelTickets(current);
+  }
+
+  /**
+   * 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.
+   * Dropped once the ticket is done.
+   * @type {Map<string, string>}
+   */
+  const fileKeys = new Map();
+
+  /**
+   * The (block, file) a pending ticket names, or null when it cannot be read (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}
+   */
+  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;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Serve every pending ticket (B42): up to `review.parallel_tickets` at once, 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)
+   * and starts once that one ends. Each ticket starts at most once per drain. On `stop()` no new
+   * ticket starts; the running ones are awaited before `drain` returns. The pool size (a run-record
+   * read) is read only when there is a pending ticket: an idle drain reads nothing but the queue.
    * @returns {Promise<number>} how many were completed.
    */
   async function drain() {
+    /** @type {number | null} */
+    let limit = null;
     let done = 0;
-    for (const id of pendingTickets(repoRoot)) {
-      if (stopping) break;
-      if (poisoned.has(id)) continue;
-      try {
-        if ((await processTicket(id)) !== null) done += 1;
-      } catch {
-        try {
-          await complete(id, { event: 'review.result', status: 'unavailable', reason: 'worker-error', approved: false });
-          done += 1;
-        } catch {
-          poisoned.add(id);
+    /** @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 {Set<string>} */
+    const started = new Set();
+    for (;;) {
+      if (!stopping) {
+        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
+          started.add(id);
+          if (fileKey !== null) busy.add(fileKey);
+          const slot = runOne(id)
+            .then((n) => {
+              done += n;
+            })
+            .finally(() => {
+              // the slot is freed on every exit path (`runOne` never rejects)
+              running.delete(id);
+              fileKeys.delete(id);
+              if (fileKey !== null) busy.delete(fileKey);
+            });
+          running.set(id, slot);
         }
       }
+      if (running.size === 0) break;
+      await nextEvent([...running.values()]);
     }
     return done;
   }
 
+  /**
+   * Resolve when one of `slots` settles, `pollMs` passes, or `stop()` is called.
+   * @param {Array<Promise<void>>} slots
+   */
+  async function nextEvent(slots) {
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let timer;
+    const tick = new Promise((resolve) => {
+      timer = setTimeout(resolve, pollMs);
+      poolWake = () => resolve(undefined);
+    });
+    try {
+      await Promise.race([...slots, tick]);
+    } finally {
+      clearTimeout(timer);
+      poolWake = null;
+    }
+  }
+
+  /**
+   * Announce this worker and keep its heartbeat beating on a timer of its own (B30), independent
+   * of the ticket being processed: a review session can run for minutes, and `review-file --wait`
+   * must still see the worker as live the whole time.
+   */
+  function announce() {
+    const self = announceWorker(repoRoot, { pid: process.pid, run: runId });
+    stopBeating();
+    const timer = setInterval(() => {
+      try {
+        // another worker announced itself over us: stop beating, never overwrite its file
+        if (!beatWorker(repoRoot, self)) stopBeating();
+      } catch {
+        // a missed beat (an fs error) is retried on the next tick; the poll loop goes on
+      }
+    }, heartbeatMs);
+    timer.unref();
+    heartbeat = timer;
+  }
+
+  function stopBeating() {
+    if (heartbeat !== null) clearInterval(heartbeat);
+    heartbeat = null;
+  }
+
   /** Serve the queue until `stop()`. */
   async function run() {
-    announceWorker(repoRoot, { pid: process.pid, run: runId });
+    announce();
     try {
       while (!stopping) {
         try {
@@ -294,7 +529,7 @@ export async function createWorker(opts, deps = {}) {
 
   /** Drain the queue once while announced, then release (`worker --once`). */
   async function once() {
-    announceWorker(repoRoot, { pid: process.pid, run: runId });
+    announce();
     try {
       return await drain();
     } finally {
@@ -303,13 +538,16 @@ export async function createWorker(opts, deps = {}) {
     }
   }
 
+  /** Stop taking tickets; the running ones are awaited (a killed one is abandoned, see `processTicket`). */
   function stop() {
     stopping = true;
     wake?.();
+    poolWake?.();
   }
 
   /** Withdraw this process's announcement (`worker.json`) if it is still ours. */
   function release() {
+    stopBeating();
     retractWorker(repoRoot, process.pid);
   }
 
@@ -325,11 +563,21 @@ export async function bootWorker(opts, deps = {}) {
   const record = await readRun(opts.runId);
   if (record.status !== 'active') throw new WorkerError('run-ended', `run ${opts.runId} has ended`);
   const repoRoot = await repoRootOf(path.resolve(opts.cwd ?? record.workspace));
-  const loaded = await loadProjectConfig(repoRoot);
-  if (!loaded.ok) throw new WorkerError('config', loaded.message ?? 'the project config cannot be loaded');
+  // B35: a run with a config snapshot boots on it (the snapshot in force, not on whatever the file
+  // says now); a run from before snapshots boots on the file, as before.
+  let cfg;
+  try {
+    cfg = snapshotFor(record, '')?.config;
+  } catch {
+    throw new WorkerError('config', `run ${opts.runId}: the config snapshot in the run record is missing or altered`);
+  }
+  if (!cfg) {
+    const loaded = await loadProjectConfig(repoRoot);
+    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 cfg = loaded.config;
   const tmpRoot = typeof cfg?.tmp?.root === 'string' ? cfg.tmp.root : undefined;
   const runRootDir = runRoot(opts.runId, { root: tmpRoot });
   setRunRoot(runRootDir);

package/src/worker/queue.mjs

@@ -4,7 +4,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}`
+ *   <repo>/.code-forge/queue/worker.json     the worker's announcement `{pid, start_time, run, started_at, heartbeat_at}`
  *   <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`;
@@ -20,6 +20,12 @@ import { assertRowPath, assertTicketId, contentHash, ticketId, WorkerError } fro
 
 export const WORKER_FILE = 'worker.json';
 
+/** How often a serving worker refreshes `heartbeat_at` (B30). */
+export const HEARTBEAT_MS = 5000;
+
+/** A heartbeat older than this is not fresh (twelve missed beats). */
+export const HEARTBEAT_STALE_MS = 60_000;
+
 /** @param {string} repoRoot */
 export const queueDir = (repoRoot) => path.join(repoRoot, '.code-forge', 'queue');
 /** @param {string} repoRoot @param {string} runId */
@@ -156,12 +162,60 @@ export async function verifyResult(repoRoot, runId, ticket) {
  * @param {string} repoRoot @param {{pid: number, run: string}} who
  */
 export function announceWorker(repoRoot, { pid, run }) {
-  const body = { pid, start_time: readStartTime(pid) ?? UNKNOWN_START_TIME, run, started_at: new Date().toISOString() };
+  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`);
   return body;
 }
 
-/** @param {string} repoRoot @returns {{pid: number, start_time: string, run: string} | null} */
+/**
+ * Refresh the announcement's `heartbeat_at` (B30) while it is still THIS worker's: the 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).
+ * 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.
+ * @param {string} repoRoot @param {{pid: number, start_time: string}} self - what `announceWorker` returned.
+ * @param {Date} [now]
+ * @returns {boolean} whether a beat was written.
+ */
+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))) {
+      rmSync(tmp, { force: true });
+      return false;
+    }
+    renameSync(tmp, file);
+    return true;
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+/** A heartbeat further than this in the future is not fresh (clock skew tolerance). */
+export const HEARTBEAT_FUTURE_MS = 5000;
+
+/**
+ * Whether the announcement's heartbeat is fresh: at most `HEARTBEAT_STALE_MS` old and at most
+ * `HEARTBEAT_FUTURE_MS` ahead of our clock (a heartbeat far in the future is forged or skewed).
+ * @param {{heartbeat_at?: unknown}} w @param {number} [nowMs]
+ */
+export function heartbeatFresh(w, nowMs = Date.now()) {
+  const at = typeof w?.heartbeat_at === 'string' ? Date.parse(w.heartbeat_at) : NaN;
+  if (!Number.isFinite(at)) return false;
+  const age = nowMs - at;
+  return age <= HEARTBEAT_STALE_MS && age >= -HEARTBEAT_FUTURE_MS;
+}
+
+/** @param {string} repoRoot @returns {{pid: number, start_time: string, run: string, heartbeat_at?: string} | null} */
 export function readWorker(repoRoot) {
   const w = readJSON(path.join(queueDir(repoRoot), WORKER_FILE));
   return w && Number.isInteger(w.pid) && w.pid > 1 && typeof w.run === 'string' ? w : null;
@@ -173,13 +227,20 @@ export function retractWorker(repoRoot, pid) {
 }
 
 /**
- * The live worker serving this queue, or null (`worker_down`): the announced pid must be alive
- * AND still have the announced start time (a recycled pid is not our worker).
- * @param {string} repoRoot
+ * The live worker serving this queue, or null (`worker_down`): the announced pid must be alive,
+ * AND either its heartbeat is fresh (B30: the worker itself wrote it within `HEARTBEAT_STALE_MS`)
+ * or it still has the announced start time (a recycled pid is not our worker). A fresh heartbeat
+ * wins over the start-time check: `ps` can fail or print another time zone's `lstart` inside a
+ * coder's sandbox, which made a live worker look down mid-review (issue #2).
+ * 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]
  */
-export function liveWorker(repoRoot) {
+export function liveWorker(repoRoot, opts = {}) {
   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;
 }