@codedology/code-forge 0.15.2 → 0.15.4

package/src/worker/loop.mjs

@@ -20,7 +20,7 @@
  * 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
+ * Ticket pool (B42): the worker runs up to `review.parallel_tickets` (default 6, 1–16) tickets at
  * 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),
@@ -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';
@@ -45,19 +45,21 @@ import { loadProjectConfig } from '../config/load.mjs';
 import { reviewWorkers } from '../config/validate.mjs';
 import { cacheHoursFrom, createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
-import { spawnSession } from '../session/spawn.mjs';
+import { providerLimit, spawnSession } from '../session/spawn.mjs';
 import { snapshotFor } from '../state/config-snapshot.mjs';
 import { runRecordPath } from '../state/paths.mjs';
 import { processStartTime, readRun, reattachWorker } from '../state/run.mjs';
 import { loadKey, signRow } from '../state/signer.mjs';
 import { logWarning } from '../util/error-log.mjs';
 import { withLock, tryLock } from '../util/file-locks.mjs';
+import { startNativeDaemon } from '../util/native.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';
 
@@ -68,7 +70,8 @@ export const DEFAULT_POLL_MS = 250;
 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 DEFAULT_PARALLEL_TICKETS = 6;
+export const DEFAULT_PROVIDER_PARALLEL = 4;
 
 /** B48: the fixed text of a failed autopilot expiry check in a drain (stderr and the warning log). */
 export const EXPIRY_CHECK_FAILED = 'the autopilot expiry check failed in a worker drain; it runs again at the next drain';
@@ -236,6 +239,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.
@@ -279,6 +283,8 @@ export async function createWorker(opts, deps = {}) {
   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;
+  let stopDaemon = async () => {};
+  let daemonStarted = false;
   /** @type {ReturnType<typeof setInterval> | null} */
   let heartbeat = null;
   /** @type {ReturnType<typeof announceWorker> | null} */
@@ -287,6 +293,64 @@ 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;
+
+  // Sessions waiting for a provider retain their ticket's pool slot. Resolve the actual provider
+  // at spawn time, after routing and second-level overrides; admission hints never bypass caps.
+  let ticketLimit = parallelTickets(cfg);
+  let providerParallel = DEFAULT_PROVIDER_PARALLEL;
+  /** @type {Map<string, {active: number, pending: number}>} */
+  const ticketSessions = new Map();
+  /** @type {Map<string, number>} */
+  const providerActive = new Map();
+  /** @type {Array<{id: string, provider: string, start: () => void}>} */
+  const sessionQueue = [];
+
+  function dispatchSessions() {
+    for (let i = 0; i < sessionQueue.length;) {
+      const next = sessionQueue[i];
+      const state = ticketSessions.get(next.id);
+      const liveTickets = [...ticketSessions.values()].filter((s) => s.active > 0).length;
+      if ((providerActive.get(next.provider) ?? 0) >= providerParallel || (state.active === 0 && liveTickets >= ticketLimit)) {
+        i += 1;
+        continue;
+      }
+      sessionQueue.splice(i, 1);
+      state.pending -= 1;
+      state.active += 1;
+      providerActive.set(next.provider, (providerActive.get(next.provider) ?? 0) + 1);
+      next.start();
+    }
+  }
+
+  /** @param {string} id @param {Parameters<typeof spawnSession>[0]} opts @returns {ReturnType<typeof spawnSession>} */
+  function spawnPooled(id, opts) {
+    // Match the spawner's per-level override and top-level fallback; validation stays there.
+    const provider = opts.cfg?.levels?.[opts.level]?.provider ?? opts.cfg?.provider ?? 'unresolved';
+    const state = ticketSessions.get(id) ?? { active: 0, pending: 0 };
+    ticketSessions.set(id, state);
+    state.pending += 1;
+    // The spawner's existing per-attempt semaphores also cover fallback providers. Retain
+    // stricter provider_concurrency settings while applying this cap to fallback attempts.
+    const providerConcurrency = Object.fromEntries(['anthropic', 'openai', 'xai'].map((p) => [p, Math.min(providerParallel, providerLimit(opts.cfg, p))]));
+    const needsCap = Object.entries(providerConcurrency).some(([p, limit]) => limit < providerLimit(opts.cfg, p));
+    const sessionCfg = needsCap ? { ...opts.cfg, review: { ...opts.cfg.review, provider_concurrency: providerConcurrency } } : opts.cfg;
+    return new Promise((resolve, reject) => {
+      sessionQueue.push({ id, provider, start: () => {
+        Promise.resolve().then(() => spawn({ ...opts, cfg: sessionCfg },
+          { env: childEnv, ...(deps.bins ? { bins: deps.bins } : {}), ...(deps.stderr ? { stderr: deps.stderr } : {}) },
+        )).then(resolve, reject).finally(() => {
+          state.active -= 1;
+          providerActive.set(provider, providerActive.get(provider) - 1);
+          if (state.active === 0 && state.pending === 0) ticketSessions.delete(id);
+          dispatchSessions();
+          poolWake?.();
+        });
+      } });
+      dispatchSessions();
+      poolWake?.();
+    });
+  }
 
   /** @param {Record<string, any>} row */
   const ledger = (row) => writeRow(signRow({ run: runId, ...row }, key));
@@ -302,6 +366,11 @@ export async function createWorker(opts, deps = {}) {
    * @throws {Error} `config-snapshot` — a record that cannot be read, or a missing/altered snapshot.
    */
   async function configFor(id) {
+    return snapshotFor(await configRecord(), id)?.config ?? cfg;
+  }
+
+  /** Read once for pool admission hints; ticket processing still re-reads its own snapshot. */
+  async function configRecord() {
     // 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;
@@ -310,13 +379,13 @@ export async function createWorker(opts, deps = {}) {
         record = await loadRun(runId);
         break;
       } catch (err) {
-        if (/** @type {any} */ (err)?.code === 'no-run') return cfg;
+        if (/** @type {any} */ (err)?.code === 'no-run') return null;
         // 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;
+    return record;
   }
 
   /**
@@ -335,7 +404,9 @@ export async function createWorker(opts, deps = {}) {
     // A route list that cannot be used is `unavailable` — never a review on a model it did not name.
     let routed;
     try {
-      routed = routeTicket(snapshotCfg, { lines: size.lines, deleted: size.deleted, timeoutS: baseTimeoutS });
+      routed = routeTicket(snapshotCfg, { lines: size.lines, deleted: size.deleted, timeoutS: baseTimeoutS },
+        snapshotCfg.review?.adaptive?.enabled === false || !snapshotCfg.levels?.L2?.model
+          ? undefined : { rows: await readRows(), ticketId: id, runId });
     } catch (err) {
       // only a route list that cannot be used is `route-invalid`; anything else is a real failure
       // and goes to runOne (`worker-error`), named as a routing-step failure with its own text
@@ -379,9 +450,8 @@ export async function createWorker(opts, deps = {}) {
       // `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(
+        spawnPooled(id,
           /** @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 }),
       writeBlockRow: (row) => ledger({ ...row, block: ticket.block }),
@@ -407,14 +477,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 +496,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 +562,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 +580,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 +607,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);
@@ -543,21 +626,26 @@ export async function createWorker(opts, deps = {}) {
   /**
    * 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}>}
+   * @returns {Promise<{limit: number, fairShare: boolean, record: Record<string, any> | null}>}
    */
   async function poolSettings() {
     let current = cfg;
+    let record = null;
     try {
-      current = await configFor('');
+      record = await configRecord();
+      current = snapshotFor(record, '')?.config ?? cfg;
     } catch {
       // an unreadable record: the boot settings (each ticket still fails closed on its own)
     }
-    return { limit: parallelTickets(current), fairShare: current?.review?.fair_share === true };
+    ticketLimit = parallelTickets(current);
+    const cap = current?.review?.provider_parallel;
+    providerParallel = Number.isInteger(cap) && cap >= 1 && cap <= MAX_PARALLEL_TICKETS ? cap : DEFAULT_PROVIDER_PARALLEL;
+    return { limit: parallelTickets(current), fairShare: current?.review?.fair_share === true, record };
   }
 
   /**
    * 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}>}
    */
@@ -582,6 +670,27 @@ export async function createWorker(opts, deps = {}) {
     }
   }
 
+  /**
+   * The initial reviewer's provider is an admission hint, including snapshot and size routing.
+   * Unknown or invalid hints still enter the bounded pool so the normal checks can refuse them.
+   * Later sessions may use another provider; `spawnPooled` enforces their actual session caps.
+   * @param {string} id @param {Record<string, any> | null} record @returns {Promise<string | null>}
+   */
+  async function providerHint(id, record) {
+    try {
+      let current = snapshotFor(record, id)?.config ?? cfg;
+      if (current?.review?.routes?.length) {
+        const ticket = loadTicket(repoRoot, id);
+        const root = await contentRootFor(runId, ticket.block, repoRoot);
+        const bytes = readRegularFileNoFollow(root, ticket.file);
+        current = routeTicket(current, { lines: countLines(bytes), deleted: bytes === null, timeoutS: DEFAULT_SESSION_TIMEOUT_S }).cfg;
+      }
+      return current?.levels?.L2?.provider ?? current?.provider ?? null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * 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
@@ -609,6 +718,8 @@ export async function createWorker(opts, deps = {}) {
     }
     /** @type {number | null} */
     let limit = null;
+    /** @type {Record<string, any> | null} */
+    let record = null;
     let fairShare = false;
     let done = 0;
     /** @type {Map<string, Promise<void>>} */
@@ -617,6 +728,8 @@ export async function createWorker(opts, deps = {}) {
     const busy = new Set();
     /** @type {Map<string, number>} running tickets per block */
     const runningByBlock = new Map();
+    /** @type {Map<string, number>} reserve provider capacity while admitted tickets prepare */
+    const admittedByProvider = new Map();
     /** @type {Set<string>} */
     const started = new Set();
     for (;;) {
@@ -643,10 +756,13 @@ 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 && limit === null) ({ limit, fairShare } = await poolSettings());
+        if (pending.length > 0 || running.size > 0) activity += 1;
+        if (pending.length > 0 && limit === null) ({ limit, fairShare, record } = 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();
+        /** @type {Map<string, string | null>} */
+        const providers = new Map();
         while (pending.length > 0 && running.size < limit && !stopping) {
           let next = -1;
           let fewest = Infinity;
@@ -655,6 +771,9 @@ export async function createWorker(opts, deps = {}) {
             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
+            if (!providers.has(id)) providers.set(id, await providerHint(id, record));
+            const provider = providers.get(id);
+            if (provider && Math.max(admittedByProvider.get(provider) ?? 0, providerActive.get(provider) ?? 0) >= providerParallel) continue;
             const count = fairShare && file ? runningByBlock.get(file.block) ?? 0 : 0;
             if (count < fewest) {
               next = i;
@@ -674,10 +793,12 @@ export async function createWorker(opts, deps = {}) {
           }
           const file = hints.get(id);
           const fileKey = file?.key ?? null;
+          const provider = providers.get(id);
           started.add(id);
           activeTickets.add(id);
           if (fileKey !== null) busy.add(fileKey);
           if (file) runningByBlock.set(file.block, (runningByBlock.get(file.block) ?? 0) + 1);
+          if (provider) admittedByProvider.set(provider, (admittedByProvider.get(provider) ?? 0) + 1);
           const slot = runOne(id)
             .then((n) => {
               done += n;
@@ -690,6 +811,7 @@ export async function createWorker(opts, deps = {}) {
               fileKeys.delete(id);
               if (fileKey !== null) busy.delete(fileKey);
               if (file) runningByBlock.set(file.block, runningByBlock.get(file.block) - 1);
+              if (provider) admittedByProvider.set(provider, admittedByProvider.get(provider) - 1);
             });
           running.set(id, slot);
         }
@@ -700,6 +822,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
@@ -745,57 +874,99 @@ export async function createWorker(opts, deps = {}) {
     heartbeat = null;
   }
 
+  async function startDaemon() {
+    if (daemonStarted) return;
+    daemonStarted = true;
+    stopDaemon = await startNativeDaemon(runId, cfg, env);
+    if (stopping) await stopDaemon();
+  }
+
   /** 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 {
+      await startDaemon();
+      announce();
+      // 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();
+      await stopDaemon();
     }
   }
 
   /** Drain the queue once while announced, then release (`worker --once`). */
   async function once() {
-    announce();
     try {
-      return await drain();
+      await startDaemon();
+      announce();
+      const done = await drain();
+      if (done > 0) await cleanOrphans();
+      return done;
     } finally {
       stop();
       release();
+      await stopDaemon();
     }
   }
 
   /** Stop taking tickets; the running ones are awaited (a killed one is abandoned, see `processTicket`). */
   function stop() {
     stopping = true;
+    void stopDaemon();
     wake?.();
     poolWake?.();
   }
 
   /** Withdraw this process's announcement (`worker.json`) if it is still ours. */
   function release() {
+    void stopDaemon();
     stopBeating();
     if (self !== null) retractWorker(repoRoot, self.pid, self.start_time);
     self = null;
   }
 
-  return { processTicket, drain, run, once, stop, release, announce, watchTick: tickWatch, jevKeyResolved: jevKey !== null, sessionEnv: childEnv };
+  return { processTicket, drain, run, once, stop, release, announce, startDaemon, stopDaemon: () => stopDaemon(), watchTick: tickWatch, jevKeyResolved: jevKey !== null, sessionEnv: childEnv };
 }
 
 /**
@@ -837,7 +1008,17 @@ export async function bootWorker(opts, deps = {}) {
     if (entries.some((entry) => entry.live && !entry.worker) || (legacy && legacy.run !== opts.runId) || entries.some((entry) => entry.live && entry.worker?.run !== opts.runId) || count >= limit) {
       throw new WorkerError('worker-running', `review.workers limit ${limit}: a live or unreadable worker entry already serves this queue`);
     }
-    worker.announce();
+    // Startup must finish before worker.json signals readiness: an owner may
+    // remove HOME immediately after that announcement to stop an orphan worker.
+    try {
+      await worker.startDaemon();
+      worker.announce();
+    } catch (error) {
+      worker.stop();
+      worker.release();
+      await worker.stopDaemon();
+      throw error;
+    }
   });
   return { ...worker, repoRoot, runRootDir };
 }