@codedology/code-forge 0.15.1 → 0.15.3

package/src/util/reaper.mjs

@@ -27,7 +27,8 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 
@@ -186,6 +187,220 @@ export function groupMembers(pgid) {
   return members;
 }
 
+/** @typedef {{uid:number,pid:number,ppid:number,state:string,rssMb:number,start_time:string,command:string}} ProcessInfo */
+
+/** Parse C-locale ps output; malformed rows supply no authority to signal.
+ * @param {string} text @returns {ProcessInfo[]}
+ */
+export function parseProcesses(text) {
+  return text.split('\n').flatMap((line) => {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\d+)\s+(\S+\s+\S+\s+\d+\s+\d+:\d+:\d+\s+\d{4})\s+(.+?)\s*$/.exec(line);
+    return m ? [{ uid: +m[1], pid: +m[2], ppid: +m[3], state: m[4], rssMb: +m[5] / 1024,
+      start_time: m[6].replace(/\s+/g, ' '), command: m[7] }] : [];
+  });
+}
+
+/** @returns {ProcessInfo[]} */
+export function readProcesses() {
+  try {
+    return parseProcesses(execFileSync(existsSync('/bin/ps') ? '/bin/ps' : 'ps',
+      ['-A', '-ww', '-o', 'uid=,pid=,ppid=,stat=,rss=,lstart=,command='], {
+        encoding: 'utf8', env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
+        timeout: 5000, maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'],
+      }));
+  } catch { return []; }
+}
+
+/** Current process, ancestors and zombies are never signal targets.
+ * @param {ProcessInfo[]} rows @returns {Set<number>}
+ */
+function protectedPids(rows) {
+  const blocked = new Set([1, process.pid, process.ppid]);
+  const byPid = new Map(rows.map((p) => [p.pid, p]));
+  let pid = process.ppid;
+  const visited = new Set();
+  while (pid > 1 && !visited.has(pid)) {
+    visited.add(pid);
+    blocked.add(pid);
+    pid = byPid.get(pid)?.ppid ?? 1;
+  }
+  for (const p of rows) if (p.state.startsWith('Z')) blocked.add(p.pid);
+  return blocked;
+}
+
+/** One synchronous identity/uid/state check immediately followed by a bare-pid signal.
+ * @param {number} pid @param {string} started @param {NodeJS.Signals} signal
+ * @returns {boolean}
+ */
+function signalMember(pid, started, signal) {
+  if (!started || started === UNKNOWN_START_TIME || !process.getuid) return false;
+  const rows = readProcesses();
+  const p = rows.find((r) => r.pid === pid);
+  if (!p || p.uid !== process.getuid() || protectedPids(rows).has(pid) || p.start_time !== started) return false;
+  try { process.kill(pid, signal); return true; } catch { return false; }
+}
+
+/** Stop a captured set, checking every member separately at both signals.
+ * @param {Map<number,string>} members @param {number} [graceMs]
+ * @returns {Promise<Map<number, 'SIGTERM'|'SIGKILL'>>}
+ */
+export async function stopMembers(members, graceMs = DEFAULT_GRACE_MS) {
+  const sent = new Map();
+  for (const [pid, started] of members) if (signalMember(pid, started, 'SIGTERM')) sent.set(pid, 'SIGTERM');
+  const deadline = Date.now() + graceMs;
+  while (sent.size && Date.now() < deadline) {
+    const live = readProcesses();
+    if (![...sent.keys()].some((pid) => live.some((p) => p.pid === pid && !p.state.startsWith('Z') && p.start_time === members.get(pid)))) break;
+    await sleep(POLL_MS);
+  }
+  for (const pid of sent.keys()) if (signalMember(pid, members.get(pid), 'SIGKILL')) sent.set(pid, 'SIGKILL');
+  // Delivery is not exit: wait for SIGKILL to take effect before exec can return to its caller.
+  const killedDeadline = Date.now() + Math.max(graceMs, 1000);
+  while (sent.size && Date.now() < killedDeadline) {
+    await sleep(POLL_MS);
+    const live = readProcesses();
+    if (![...sent.keys()].some((pid) => live.some((p) => p.pid === pid && !p.state.startsWith('Z') && p.start_time === members.get(pid)))) break;
+  }
+  return sent;
+}
+
+/** Read only ownership markers, never retain/print the rest of a child's environment.
+ * @param {ProcessInfo} p @returns {Record<string,string>|null}
+ */
+export function readProcessEnv(p) {
+  try {
+    let text;
+    if (process.platform === 'linux') text = readFileSync(`/proc/${p.pid}/environ`, 'utf8');
+    else if (process.platform === 'darwin') {
+      const out = execFileSync('/bin/ps', ['-E', '-ww', '-o', 'pid=,ppid=,lstart=,command=', '-p', String(p.pid)], {
+        encoding: 'utf8', timeout: 5000, maxBuffer: 8 * 1024 * 1024,
+        env: { ...process.env, LC_ALL: 'C', LANG: 'C' }, stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      const m = /^\s*(\d+)\s+(\d+)\s+(\S+\s+\S+\s+\d+\s+\d+:\d+:\d+\s+\d{4})\s+/.exec(out);
+      if (!m || +m[1] !== p.pid || +m[2] !== p.ppid || m[3].replace(/\s+/g, ' ') !== p.start_time) return null;
+      text = out.slice(m[0].length);
+      // ps appends the environment to argv. An ownership-looking argument is not an env
+      // marker: strip the independently observed command before parsing the environment.
+      if (!text.startsWith(`${p.command} `)) return null;
+      text = text.slice(p.command.length + 1);
+    } else return null;
+    /** @type {Record<string,string>} */
+    const markers = {};
+    for (const name of ['HOME', 'CODE_FORGE_OWNER_PID', 'CODE_FORGE_RUN_ID', 'CODE_FORGE_OWNER_START_TIME']) {
+      const match = process.platform === 'linux'
+        ? text.split('\0').find((entry) => entry.startsWith(`${name}=`))?.slice(name.length + 1)
+        : new RegExp(`(?:^|\\s)${name}=(.*?)(?=\\s+[A-Za-z_][A-Za-z0-9_]*=|$)`).exec(text)?.[1];
+      if (match !== undefined) markers[name] = match;
+    }
+    return markers;
+  } catch { return null; }
+}
+
+/**
+ * Inspect and optionally stop proven code-forge processes. Defaults are read-only.
+ * `psText`/readers are test seams; production always probes the OS and existing record reader.
+ * @param {{apply?:boolean, root?:string, runId?:string, orphansOnly?:boolean, zombies?:boolean,
+ * graceMs?:number, psText?:string, uid?:number,
+ * readEnv?:(p:ProcessInfo)=>Record<string,string>|null,
+ * readRun?:(id:string)=>Promise<Record<string,any>>}} [opts]
+ */
+export async function sweepProcesses(opts = {}) {
+  const rows = opts.psText === undefined ? readProcesses() : parseProcesses(opts.psText);
+  const uid = opts.uid ?? process.getuid?.();
+  const own = rows.filter((p) => p.uid === uid);
+  const blocked = protectedPids(rows);
+  const envFor = opts.readEnv ?? readProcessEnv;
+  const loadRun = opts.readRun ?? (await import('../state/run.mjs')).readRun;
+  const tmp = await import('./tmp.mjs');
+  /** @type {(ProcessInfo & {kind:'worker'|'orphan'|'registry',runId?:string,action?:string})[]} */
+  const items = [];
+  /** @type {{ppid:number,command:string,count:number,pids:number[]}[]} */
+  const zombies = [];
+  if (opts.zombies !== false && !opts.orphansOnly) {
+    for (const p of own.filter((p) => p.state.startsWith('Z'))) {
+      let group = zombies.find((g) => g.ppid === p.ppid);
+      if (!group) { group = { ppid: p.ppid, command: rows.find((r) => r.pid === p.ppid)?.command ?? '(unreadable)', count: 0, pids: [] }; zombies.push(group); }
+      group.count++; group.pids.push(p.pid);
+    }
+  }
+  for (const p of own) {
+    if (p.pid <= 1 || blocked.has(p.pid)) continue;
+    // Exactly node + a code-forge entry point + worker, never an argv substring in a shell/-e.
+    const worker = /^(?:\S*\/)?node(?:js)?\s+(?:\S*\/)?code-forge\.mjs\s+worker\s+--run(?:=|\s+)([a-z0-9][a-z0-9-]{0,63})(?:\s|$)/.exec(p.command);
+    if (worker && !opts.orphansOnly) {
+      // Run records only authorize worker cleanup inside their own code-forge home.
+      // Unreadable environments and workers from another HOME supply no such authority.
+      if (envFor(p)?.HOME !== os.homedir()) continue;
+      try {
+        const record = await loadRun(worker[1]);
+        if (typeof record.status === 'string' && !['open', 'running', 'active'].includes(record.status)) items.push({ ...p, kind: 'worker', runId: worker[1] });
+      } catch (err) {
+        if (err?.code === 'no-run') items.push({ ...p, kind: 'worker', runId: worker[1] });
+      }
+      // The run record is authoritative for workers, including when it cannot be read.
+      continue;
+    }
+    if (p.ppid !== 1 || items.some((item) => item.pid === p.pid)) continue;
+    const env = envFor(p);
+    const owner = env?.CODE_FORGE_OWNER_PID;
+    if (!owner || !/^[1-9]\d*$/.test(owner) || +owner <= 1 || (opts.runId && env.CODE_FORGE_RUN_ID !== opts.runId)) continue;
+    const liveOwner = rows.find((r) => r.pid === +owner);
+    const recorded = env.CODE_FORGE_OWNER_START_TIME;
+    // A missing row alone is not proof of death when ps was incomplete.
+    const dead = !liveOwner ? !isAlive(+owner) : liveOwner.state.startsWith('Z')
+      || !!recorded && recorded !== UNKNOWN_START_TIME && liveOwner.start_time !== recorded;
+    if (dead) items.push({ ...p, kind: 'orphan', ...(env.CODE_FORGE_RUN_ID ? { runId: env.CODE_FORGE_RUN_ID } : {}) });
+  }
+  const root = tmp.tmpBase(opts.root);
+  const registryRoots = [];
+  if (!opts.orphansOnly && tmp.untrustedReason(root) === null) {
+    for (const dir of readdirSync(root, { withFileTypes: true })) {
+      const full = path.join(root, dir.name);
+      if (!dir.isDirectory() || tmp.untrustedReason(full) !== null) continue;
+      const state = tmp.ownerState(full);
+      let reap = state === 'dead';
+      if (state === 'missing') {
+        // Mirror sweepRoots' ten-minute ownerless grace, including every registry mtime.
+        try {
+          const pids = path.join(full, 'pids');
+          const files = existsSync(pids) ? [pids, ...readdirSync(pids).map((name) => path.join(pids, name))] : [];
+          reap = [full, ...files].every((file) => Date.now() - lstatSync(file).mtimeMs > 600_000);
+        } catch { reap = false; }
+      }
+      if (!reap) continue;
+      registryRoots.push(full);
+      for (const entry of listEntries(path.join(full, 'pids'))) {
+        const p = own.find((p) => p.pid === entry.pid && p.start_time === entry.start_time);
+        if (!p || blocked.has(p.pid)) continue;
+        const members = new Map([[p.pid, p.start_time], ...groupMembers(p.pid)]);
+        for (const [pid, started] of members) {
+          const member = own.find((p) => p.pid === pid && p.start_time === started);
+          if (member && !blocked.has(pid) && !items.some((i) => i.pid === pid)) items.push({ ...member, kind: 'registry' });
+        }
+      }
+    }
+  }
+  // Memory across all code-forge trees, deduplicated. Unmarked descendants are children too.
+  const forge = new Set(own.filter((p) => /^(?:\S*\/)?node(?:js)?\s+(?:\S*\/)?code-forge\.mjs(?:\s|$)/.test(p.command) || p.pid === process.pid).map((p) => p.pid));
+  const tree = new Set(forge);
+  let size;
+  do { size = tree.size; for (const p of own) if (tree.has(p.ppid)) tree.add(p.pid); } while (tree.size !== size);
+  const sum = (/** @type {ProcessInfo[]} */ ps) => ps.reduce((n, p) => n + p.rssMb, 0);
+  const memory = { codeForgeMb: sum(own.filter((p) => forge.has(p.pid))), childrenMb: sum(own.filter((p) => tree.has(p.pid) && !forge.has(p.pid))), orphansMb: sum(items.filter((p) => p.kind === 'orphan')) };
+  if (opts.apply) {
+    for (const item of items.filter((p) => p.kind !== 'registry')) {
+      const stopped = await stopMembers(new Map([[item.pid, item.start_time]]), opts.graceMs);
+      item.action = stopped.has(item.pid) ? 'stopped' : 'skipped';
+    }
+    if (!opts.orphansOnly) await tmp.sweepRoots({ root, graceMs: opts.graceMs });
+    for (const item of items.filter((p) => p.kind === 'registry')) {
+      const started = readStartTime(item.pid);
+      item.action = !isAlive(item.pid) || (started !== null && started !== item.start_time) ? 'stopped' : 'skipped';
+    }
+  }
+  return { apply: opts.apply === true, items, registryRoots, zombies, totalRssMb: sum(items), memory };
+}
+
 /**
  * Send `signal` to `pid`'s group — only after a SYNCHRONOUS start-time match, with no await
  * between the check and the kill. Falls back to the bare pid only when the group does not exist
@@ -196,6 +411,19 @@ export function groupMembers(pgid) {
  * @returns {'sent'|'mismatch'|'eperm'|'gone'}
  */
 function signalIfOurs(pid, recorded, signal) {
+  const rows = readProcesses();
+  const blocked = protectedPids(rows);
+  const leader = rows.find((p) => p.pid === pid);
+  if (!process.getuid || !leader || leader.uid !== process.getuid() || blocked.has(pid)) return 'eperm';
+  const members = groupMembers(pid);
+  const safeGroup = [...members].every(([member, started]) => rows.some((p) => p.pid === member
+    && p.uid === process.getuid() && !blocked.has(member) && p.start_time === started));
+  if (!safeGroup) {
+    if (readStartTime(pid) !== recorded) return 'mismatch';
+    const sent = signalMember(pid, recorded, signal);
+    for (const [member, started] of members) signalMember(member, started, signal);
+    return sent ? 'sent' : 'eperm';
+  }
   if (readStartTime(pid) !== recorded) return 'mismatch';
   try {
     process.kill(-pid, signal);
@@ -234,10 +462,16 @@ export async function sweep(dir, opts = {}) {
   const { graceMs = DEFAULT_GRACE_MS } = opts;
   /** @type {SweepResult} */
   const result = { killed: [], mismatched: [], unknown: [], stale: [] };
+  const rows = readProcesses();
+  const blocked = protectedPids(rows);
 
   for (const entry of listEntries(dir)) {
     const { pid } = entry;
-    if (pid === process.pid) continue;
+    if (blocked.has(pid)) continue;
+    if (isAlive(pid) && !rows.some((p) => p.pid === pid && p.uid === process.getuid?.())) {
+      result.unknown.push(pid);
+      continue;
+    }
 
     if (!isAlive(pid)) {
       unregisterPid(dir, pid);
@@ -278,6 +512,7 @@ export async function sweep(dir, opts = {}) {
         continue;
       }
       await waitForDeath(pid, graceMs);
+      for (const [member, started] of members) signalMemberIfOurs(member, started);
       result.killed.push({ pid, signal: 'SIGKILL' });
     }
     unregisterPid(dir, pid);
@@ -291,10 +526,5 @@ export async function sweep(dir, opts = {}) {
  * @param {number} pid @param {string} started
  */
 function signalMemberIfOurs(pid, started) {
-  if (readStartTime(pid) !== started) return;
-  try {
-    process.kill(pid, 'SIGKILL');
-  } catch {
-    // gone between the check and the kill
-  }
+  signalMember(pid, started, 'SIGKILL');
 }

package/src/worker/engine.mjs

@@ -109,7 +109,7 @@ import { verifyRow } from '../state/signer.mjs';
 import { redact } from '../util/redact.mjs';
 import { withLock } from '../util/file-locks.mjs';
 import { blockAnchors, blockRungUsed, loadState, RESTORED_EVENT, saveState } from './review-state.mjs';
-import { assertAnswers, enqueueHash, isDone, writeResult } from './queue.mjs';
+import { assertAnswers, enqueueHash, isDone, reviewExclusionFor, writeResult } from './queue.mjs';
 import { assertTicketId, contentHash, readRegularFileNoFollow, WorkerError } from './ticket.mjs';
 
 /**
@@ -345,6 +345,9 @@ export function packetDirFor(runRootDir, id) {
  * @returns {Promise<ReviewOutcome>}
  */
 export async function reviewTicket(ticket, ctx) {
+  const excluded = (/** @type {string} */ file) => reviewExclusionFor(ctx.repoRoot, ctx.runId, file, ctx.cfg);
+  const rule = excluded(ticket.file) ?? (ticket.kind === 'answers' ? excluded(ticket.by_file) : null);
+  if (rule !== null) return { status: 'excluded', reason: `review.exclude ${rule}`, approved: false, engine: 'adaptive', sessions: [] };
   const workDir = packetDirFor(ctx.runRootDir, ticket.ticket);
   if (workDir === null) return { status: 'unavailable', reason: 'ticket-id-invalid', approved: false, engine: 'adaptive', sessions: [] };
   let entry;
@@ -390,7 +393,7 @@ export async function reviewTicket(ticket, ctx) {
     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));
+      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) && excluded(f) === null);
       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 };
@@ -444,7 +447,7 @@ async function lightRound(ticket, ctx, { entry, workDir, factsExcerpt, rulesDige
   const worker = { pid: process.pid, started_at: await processStartTime(process.pid) };
   return withLock(`light:${ctx.runId}\0${ticket.block}`, async () => {
     const root = ctx.contentRoot ?? ctx.repoRoot;
-    const files = (await computeFileSet({ cwd: root, base: entry.base ?? 'HEAD' })).all.filter((file) => ownsFile(entry.owned, file, entry.ownedKinds)).sort();
+    const files = (await computeFileSet({ cwd: root, base: entry.base ?? 'HEAD' })).all.filter((file) => ownsFile(entry.owned, file, entry.ownedKinds) && reviewExclusionFor(ctx.repoRoot, ctx.runId, file, ctx.cfg) === null).sort();
     const hashes = files.map((file) => ({ file, content_hash: contentHash(root, file) }));
     if (!hashes.some((f) => f.file === ticket.file && f.content_hash === ticket.content_hash)) return { status: 'stale', approved: false, engine: 'adaptive', sessions: [] };
     const signature = JSON.stringify([entry.base, hashes]);
@@ -473,6 +476,7 @@ async function lightRound(ticket, ctx, { entry, workDir, factsExcerpt, rulesDige
         if (approved) await writeRow({ event: 'review.approved', file, content_hash });
       }
       const queued = enqueueHash({ repoRoot: ctx.repoRoot, run: ctx.runId, block: ticket.block, file, content_hash, ...(ticket.tree ? { tree: ticket.tree } : {}) });
+      if (queued.status === 'excluded') continue;
       const open = approved ? [] : own;
       await writeRow({ event: 'review.result', ticket: queued.ticket, file, content_hash, status: outcome.status, approved, open, worker });
       writeResult({ repoRoot: ctx.repoRoot, runId: ctx.runId, ticket: queued.ticket, result: { ...outcome, block: ticket.block, file, content_hash, open, worker }, key });

package/src/worker/loop.mjs

@@ -36,7 +36,7 @@
  */
 
 import { spawn as nodeSpawn } from 'node:child_process';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, watch } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -53,11 +53,12 @@ import { loadKey, signRow } from '../state/signer.mjs';
 import { logWarning } from '../util/error-log.mjs';
 import { withLock, tryLock } from '../util/file-locks.mjs';
 import { redact, writeSafe } from '../util/redact.mjs';
+import { sweepProcesses } from '../util/reaper.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, isDone, liveWorker, pendingTickets, readTicket, retractWorker, workerRegistry, writeResult } from './queue.mjs';
+import { announceWorker, beatWorker, HEARTBEAT_MS, isDone, liveWorker, pendingTickets, queueDir, readTicket, retractWorker, workerRegistry, writeResult, writeTicketTimings } from './queue.mjs';
 import { DELETED_HASH, hashBytes, readRegularFileNoFollow, repoRootOf, WorkerError } from './ticket.mjs';
 import { watchTick } from './watch.mjs';
 
@@ -236,6 +237,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 {(ms: number) => Promise<unknown>} [sleep] - idle scheduler wait (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.
@@ -287,6 +289,7 @@ export async function createWorker(opts, deps = {}) {
   let wake = null;
   /** @type {(() => void) | null} wakes the pool's wait in `drain` (stop) */
   let poolWake = null;
+  let activity = 0;
 
   /** @param {Record<string, any>} row */
   const ledger = (row) => writeRow(signRow({ run: runId, ...row }, key));
@@ -407,14 +410,17 @@ export async function createWorker(opts, deps = {}) {
 
   /**
    * @param {string} id
+   * @param {{ticket: import('./queue.mjs').Ticket | null, queued_at: string | null, started_at: string}} [attempt]
    * @returns {Promise<Record<string, any> | null>} the signed result, or null when abandoned.
    */
-  async function processTicket(id) {
+  async function processTicket(id, attempt = { ticket: null, queued_at: null, started_at: new Date().toISOString() }) {
     /** @type {Record<string, any>} */
     let result;
     let ticket = null;
     try {
       ticket = loadTicket(repoRoot, id);
+      attempt.ticket = ticket;
+      attempt.queued_at = ticket.queued_at ?? ticket.enqueued_at ?? null;
     } catch (err) {
       result = { event: 'review.result', status: 'refused', reason: err instanceof WorkerError ? err.code : 'bad-ticket', approved: false };
     }
@@ -423,13 +429,17 @@ 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 withLock(`${runId}\0${fileLockKey(t.block, t.file)}`, () => reviewOne(id, t));
+      result = await withLock(`${runId}\0${fileLockKey(t.block, t.file)}`, () => {
+        attempt.started_at = new Date().toISOString();
+        writeTicketTimings(repoRoot, t, { queued_at: attempt.queued_at, started_at: attempt.started_at, finished_at: null, duration_ms: null });
+        return 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
     // that reached a real outcome while the pool drained is recorded as usual.
     if (stopping && result.status === 'unavailable') return null;
-    return complete(id, result);
+    return complete(id, result, attempt);
   }
 
   /**
@@ -485,10 +495,14 @@ export async function createWorker(opts, deps = {}) {
    * 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.
    * @param {string} id @param {Record<string, any>} outcome - recorded through {@link recordedVerdict}.
+   * @param {{ticket: import('./queue.mjs').Ticket | null, queued_at: string | null, started_at: string}} attempt
    */
-  async function complete(id, outcome) {
+  async function complete(id, outcome, attempt) {
+    const finished_at = new Date().toISOString();
+    const timings = { queued_at: attempt.queued_at, started_at: attempt.started_at, finished_at, duration_ms: Math.max(0, Date.parse(finished_at) - Date.parse(attempt.started_at)) };
+    if (attempt.ticket) writeTicketTimings(repoRoot, attempt.ticket, timings);
     /** @type {Record<string, any>} */
-    const result = { ...recordedVerdict(outcome), worker: identity };
+    const result = { ...(attempt.ticket ? { block: attempt.ticket.block, file: attempt.ticket.file, content_hash: attempt.ticket.content_hash } : {}), ...recordedVerdict(outcome), ...timings, worker: identity };
     const signed = writeResult({ repoRoot, runId, ticket: id, result, key });
     try {
       await ledger({
@@ -499,6 +513,7 @@ export async function createWorker(opts, deps = {}) {
         file: result.file ?? null,
         content_hash: result.content_hash ?? null,
         status: result.status,
+        ...timings,
         // B52: the gate reads the verdict from the ledger, never from the result file
         approved: result.approved,
         open: result.open,
@@ -525,13 +540,14 @@ export async function createWorker(opts, deps = {}) {
    * @param {string} id @returns {Promise<number>} 1 when completed, else 0.
    */
   async function runOne(id) {
+    const attempt = { ticket: /** @type {import('./queue.mjs').Ticket | null} */ (null), queued_at: /** @type {string | null} */ (null), started_at: new Date().toISOString() };
     try {
-      return (await processTicket(id)) !== null ? 1 : 0;
+      return (await processTicket(id, attempt)) !== null ? 1 : 0;
     } catch (err) {
       // B90: a failure a step names (StepError) keeps its step and original text, redacted
       const detail = err instanceof StepError ? { detail: redact(err.message) } : {};
       try {
-        await complete(id, { event: 'review.result', status: 'unavailable', reason: 'worker-error', ...detail, approved: false });
+        await complete(id, { event: 'review.result', status: 'unavailable', reason: 'worker-error', ...detail, approved: false }, attempt);
         return 1;
       } catch {
         poisoned.add(id);
@@ -557,7 +573,7 @@ export async function createWorker(opts, deps = {}) {
 
   /**
    * 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.
+   * changes its identity as lifecycle metadata advances, so scheduling reads it once across wake-ups.
    * Dropped once the ticket is done.
    * @type {Map<string, {key: string, block: string}>}
    */
@@ -643,6 +659,7 @@ export async function createWorker(opts, deps = {}) {
           try { await logWarning({ warning: 'watch_tick_failed', message: text }); } catch { /* a log failure never stops dispatch */ }
         }
         const pending = pendingTickets(repoRoot).filter((id) => !poisoned.has(id) && !started.has(id));
+        if (pending.length > 0 || running.size > 0) activity += 1;
         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>>} */
@@ -700,6 +717,13 @@ export async function createWorker(opts, deps = {}) {
     return done;
   }
 
+  /** Process inspection belongs to the worker lifecycle, outside ticket dispatch and draining. */
+  async function cleanOrphans() {
+    try {
+      await sweepProcesses({ apply: true, orphansOnly: true, runId, zombies: false });
+    } catch { /* process hygiene must never fail the worker */ }
+  }
+
   /**
    * Resolve when one of `slots` settles, `pollMs` passes, or `stop()` is called.
    * @param {Array<Promise<void>>} slots
@@ -748,24 +772,51 @@ export async function createWorker(opts, deps = {}) {
   /** Serve the queue until `stop()`. */
   async function run() {
     announce();
+    let interval = pollMs;
+    let polled = false;
+    /** @type {import('node:fs').FSWatcher | null} */
+    let queueWatch = null;
     try {
+      // Enqueue publishes a ticket by rename. Wake even during the longest idle back-off;
+      // heartbeat and temporary files do not wake an idle worker.
+      try {
+        queueWatch = watch(queueDir(repoRoot), (_event, file) => {
+          if (!file || !/^[a-f0-9]{24}\.json$/.test(String(file))) return;
+          activity += 1;
+          wake?.();
+          poolWake?.();
+        });
+        queueWatch.on('error', () => {
+          queueWatch?.close();
+          queueWatch = null;
+          wake?.();
+        });
+      } catch { /* without filesystem notifications, keep polling at the fast interval */ }
       while (!stopping) {
+        const before = activity;
         try {
-          await drain();
+          if (await drain() > 0) await cleanOrphans();
         } catch {
           // the queue directory itself failed to read: try again on the next poll
         }
         if (stopping) break;
-        await new Promise((resolve) => {
-          const timer = setTimeout(resolve, pollMs);
+        const unchanged = before === activity;
+        interval = polled && unchanged ? Math.min(5000, interval * 2) : pollMs;
+        if (queueWatch === null && !deps.sleep) interval = pollMs;
+        polled = true;
+        await new Promise((resolve, reject) => {
+          let timer;
           wake = () => {
             clearTimeout(timer);
             resolve(undefined);
           };
+          if (deps.sleep) deps.sleep(interval).then(resolve, reject);
+          else timer = setTimeout(resolve, interval);
         });
         wake = null;
       }
     } finally {
+      queueWatch?.close();
       release();
     }
   }
@@ -774,7 +825,9 @@ export async function createWorker(opts, deps = {}) {
   async function once() {
     announce();
     try {
-      return await drain();
+      const done = await drain();
+      if (done > 0) await cleanOrphans();
+      return done;
     } finally {
       stop();
       release();