@codedology/code-forge 0.1.0

package/src/worker/loop.mjs

@@ -0,0 +1,392 @@
+/**
+ * The review worker (plan §4.8, §8.1, §8.2, §8.6; block B11).
+ *
+ * One long-lived process per run, started by the orchestrator (`forge run start`) OUTSIDE any
+ * coder sandbox. At start-up it:
+ *  - reads the run record (`~/.code-forge/runs/<run>.json`) and the project config;
+ *  - creates the run's temp root `<tmp.root>/<run-id>/` with ITSELF as the owner and makes it the
+ *    process's run root, so every session it spawns is registered in `<run-root>/pids/` and a
+ *    killed worker leaves one root that the next `run start` sweep reaps (§9.6, V12);
+ *  - loads the run's HMAC key and resolves the Jev key ONCE through B2's chain (§8.1) — both stay
+ *    in this process: the sessions it spawns get an env with no `CODE_FORGE_*`/`JEV_*` variable and
+ *    no variable whose value is one of those secrets (§8.2);
+ *  - announces itself in `<repo>/.code-forge/queue/worker.json` (what `review-file` checks).
+ * 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.
+ *
+ * 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
+ * re-pinned in the run record by the orchestrator (`repinWorker`, = `run start --reattach`).
+ */
+
+import { spawn as nodeSpawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 { readRun, reattachWorker } from '../state/run.mjs';
+import { loadKey, signRow } from '../state/signer.mjs';
+import { runRoot, setRunRoot } from '../util/tmp.mjs';
+import { reviewTicket } from './engine.mjs';
+import { announceWorker, 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;
+
+/**
+ * Provider-CLI auth variables a reviewer CLI may legitimately need (the reviewer runs on the
+ * provider's own account; §8.2 bars the Jev and signer keys, not the provider login).
+ */
+export const PROVIDER_AUTH_VARS = Object.freeze(['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'CODEX_API_KEY', 'XAI_API_KEY', 'GROK_API_KEY']);
+
+/** Names that look like a secret: `*_TOKEN`, `*_KEY`, `*_SECRET`, `*_PASSWORD` (any case). */
+export const SECRET_NAME = /(_TOKEN|_KEY|_SECRET|_PASSWORD)$/i;
+
+/**
+ * The env handed to every session the worker spawns: the worker's env minus code-forge's own and
+ * Jev variables, minus every secret-shaped name except the provider-CLI auth variables, and minus
+ * any variable whose value contains one of `secrets` (§8.2).
+ * @param {NodeJS.ProcessEnv} env @param {ReadonlyArray<string | null | undefined>} secrets
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function sessionEnv(env, secrets) {
+  const live = secrets.filter((s) => typeof s === 'string' && s.length >= 8);
+  /** @type {NodeJS.ProcessEnv} */
+  const out = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (/^(CODE_FORGE_|JEV_)/i.test(name)) continue;
+    if (SECRET_NAME.test(name) && !PROVIDER_AUTH_VARS.includes(name)) continue;
+    if (typeof value === 'string' && live.some((s) => value.includes(/** @type {string} */ (s)))) continue;
+    out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * Resolve the Jev key through B2's chain (env → store → 1Password). A missing key is not an error:
+ * System 1 then falls back (`system1.fallback`, B3). The value is registered for redaction by B2.
+ * @param {Record<string, any>} cfg
+ * @param {{store: import('../keys/store.mjs').KeyStore, env: NodeJS.ProcessEnv, opRead?: any}} deps
+ * @returns {Promise<string | null>}
+ */
+export async function resolveJevKey(cfg, { store, env, opRead }) {
+  const ref = cfg?.system1?.key ?? cfg?.keys?.[JEV_KEY_NAME];
+  const res = await resolveKey(JEV_KEY_NAME, { store, env, ref: typeof ref === 'string' ? ref : undefined, ...(opRead ? { opRead } : {}) });
+  return res.value;
+}
+
+/** The fix-loop fields of an engine outcome the result carries (B12c, §4.11). */
+const LOOP_FIELDS = Object.freeze(['round', 'kind', 'level', 'next', 'trigger', 'stopped', 'late']);
+
+/**
+ * @param {Record<string, any>} outcome @returns {Record<string, any>} the fix-loop fields present.
+ */
+export function loopResult(outcome) {
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const name of LOOP_FIELDS) if (outcome[name] !== undefined) out[name] = outcome[name];
+  return out;
+}
+
+/**
+ * @typedef {object} WorkerOpts
+ * @property {string} runId
+ * @property {string} repoRoot - realpath'd repository root.
+ * @property {Record<string, any>} cfg
+ * @property {string} runRootDir
+ * @property {string} slug - ledger project slug (the run record's `project`).
+ * @property {Buffer} key - the run's HMAC key.
+ * @property {number} [pollMs]
+ */
+
+/**
+ * @typedef {object} WorkerDeps
+ * @property {typeof reviewTicket} [review] - the engine hook (default `./engine.mjs`).
+ * @property {typeof spawnSession} [spawn]
+ * @property {import('../keys/store.mjs').KeyStore} [store] - default: B2's production store.
+ * @property {any} [opRead]
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {Partial<Record<'claude'|'codex'|'grok', string>>} [bins]
+ * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow] - default: B6 `appendRow`.
+ * @property {() => Promise<Array<Record<string, any>>>} [readRows] - the ledger rows the fix-loop
+ *   state is anchored in; default: B6 `readAllRows(slug)`.
+ * @property {{write: (s: string) => unknown}} [stderr]
+ * @property {import('../review/triage.mjs').JevAsk} [jev] - S1 for triage and the recheck (tests
+ *   inject a mock); default: `askJev` with the resolved Jev key, none without one.
+ */
+
+/**
+ * @param {WorkerOpts} opts @param {WorkerDeps} [deps]
+ */
+export async function createWorker(opts, deps = {}) {
+  const { runId, repoRoot, cfg, runRootDir, slug, key } = opts;
+  const env = deps.env ?? process.env;
+  const review = deps.review ?? reviewTicket;
+  const spawn = deps.spawn ?? spawnSession;
+  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;
+  let stopping = false;
+  /** @type {(() => void) | null} */
+  let wake = null;
+
+  /** @param {Record<string, any>} row */
+  const ledger = (row) => writeRow(signRow({ run: runId, ...row }, key));
+
+  /**
+   * @param {string} id
+   * @returns {Promise<Record<string, any> | null>} the signed result, or null when abandoned.
+   */
+  async function processTicket(id) {
+    /** @type {Record<string, any>} */
+    let result;
+    let ticket = null;
+    try {
+      ticket = readTicket(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 };
+        }
+      }
+    }
+    if (stopping) return null; // the session was killed by our own stop: leave the ticket queued
+    return complete(id, result);
+  }
+
+  /**
+   * 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>} result
+   */
+  async function complete(id, result) {
+    const signed = writeResult({ repoRoot, runId, ticket: id, result, key });
+    try {
+      await ledger({
+        event: 'review.result',
+        ticket: id,
+        block: result.block ?? null,
+        file: result.file ?? null,
+        content_hash: result.content_hash ?? null,
+        status: result.status,
+        ...(typeof result.trigger === 'string' ? { trigger: result.trigger } : {}),
+        ...(typeof result.stopped === 'string' ? { stopped: result.stopped } : {}),
+      });
+    } catch {
+      // the signed result file stands; the gate reads it (§4.6)
+    }
+    return signed;
+  }
+
+  /** Tickets this worker could not even record a failure for: skipped until a restart. */
+  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.
+   * @returns {Promise<number>} how many were completed.
+   */
+  async function drain() {
+    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);
+        }
+      }
+    }
+    return done;
+  }
+
+  /** Serve the queue until `stop()`. */
+  async function run() {
+    announceWorker(repoRoot, { pid: process.pid, run: runId });
+    try {
+      while (!stopping) {
+        try {
+          await drain();
+        } 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);
+          wake = () => {
+            clearTimeout(timer);
+            resolve(undefined);
+          };
+        });
+        wake = null;
+      }
+    } finally {
+      release();
+    }
+  }
+
+  /** Drain the queue once while announced, then release (`worker --once`). */
+  async function once() {
+    announceWorker(repoRoot, { pid: process.pid, run: runId });
+    try {
+      return await drain();
+    } finally {
+      stop();
+      release();
+    }
+  }
+
+  function stop() {
+    stopping = true;
+    wake?.();
+  }
+
+  /** Withdraw this process's announcement (`worker.json`) if it is still ours. */
+  function release() {
+    retractWorker(repoRoot, process.pid);
+  }
+
+  return { processTicket, drain, run, once, stop, release, jevKeyResolved: jevKey !== null, sessionEnv: childEnv };
+}
+
+/**
+ * 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.
+ * @param {{runId: string, cwd?: string, pollMs?: number}} opts @param {WorkerDeps} [deps]
+ */
+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');
+  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);
+  const key = await loadKey(opts.runId);
+  const worker = await createWorker({ runId: opts.runId, repoRoot, cfg, runRootDir, slug: record.project, key, pollMs: opts.pollMs }, deps);
+  return { ...worker, repoRoot, runRootDir };
+}
+
+/**
+ * `run start --reattach` for a restarted worker: re-pin the run record to the pid the queue
+ * announces, when that worker is alive and serves this run (the orchestrator runs this, never a
+ * coder — the record lives outside the workspace).
+ * `expectPid` (a `run start` that just launched a worker) pins ONLY that pid: an older or stale
+ * announcement naming another live pid is refused (`worker_mismatch`) instead of being pinned
+ * over the new worker.
+ * @param {{runId: string, repoRoot: string, writeRow?: (row: Record<string, any>) => Promise<unknown>, probe?: import('../state/run.mjs').StartTimeProbe, expectPid?: number}} opts
+ */
+export async function repinWorker({ runId, repoRoot, writeRow, probe, expectPid }) {
+  const live = liveWorker(repoRoot);
+  if (!live) throw new WorkerError('worker_down', 'no live worker serves this queue');
+  if (live.run !== runId) throw new WorkerError('other-run', `the live worker serves run ${live.run}`);
+  if (expectPid !== undefined && live.pid !== expectPid) {
+    throw new WorkerError('worker_mismatch', `the queue announces worker pid ${live.pid}, not the launched pid ${expectPid}`);
+  }
+  const { project } = await readRun(runId);
+  const write = writeRow ?? ((/** @type {Record<string, any>} */ row) => appendRow(row, { slug: project }));
+  return reattachWorker({ runId, workerPid: live.pid, writeRow: write, ...(probe ? { probe } : {}) });
+}
+
+/** The CLI entry the worker is launched from. */
+const BIN = fileURLToPath(new URL('../../bin/code-forge.mjs', import.meta.url));
+
+/**
+ * `run start`: launch `code-forge worker --run <id>` DETACHED in the workspace (the orchestrator's
+ * context, outside any coder sandbox; argv only, no shell) and wait until it announces itself in
+ * the queue. A worker that does not announce within `timeoutMs` is killed and the start refused.
+ * @param {{runId: string, workspace: string, env?: NodeJS.ProcessEnv, timeoutMs?: number}} opts
+ * @returns {Promise<{pid: number, repoRoot: string}>}
+ */
+export async function launchWorker({ runId, workspace, env = process.env, timeoutMs = 15000 }) {
+  const repoRoot = await repoRootOf(workspace);
+  const child = nodeSpawn(process.execPath, [BIN, 'worker', '--run', runId], { cwd: repoRoot, env, detached: true, stdio: 'ignore', shell: false });
+  child.on('error', () => {});
+  const pid = child.pid;
+  child.unref();
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (typeof pid === 'number' && liveWorker(repoRoot)?.pid === pid) return { pid, repoRoot };
+    if (child.exitCode !== null || child.signalCode !== null) break;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  if (typeof pid === 'number') {
+    try {
+      process.kill(-pid, 'SIGKILL');
+    } catch {
+      // already gone
+    }
+  }
+  throw new WorkerError('worker_down', 'the worker did not start (run `code-forge worker --run <id>` by hand to see why)');
+}

package/src/worker/queue.mjs

@@ -0,0 +1,186 @@
+/**
+ * The review queue on disk (plan §1.2, §4.8; block B11). Everything is a file inside the
+ * workspace, so a Codex `workspace-write` coder with no network can enqueue and poll:
+ *
+ *   <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/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`;
+ * the MAC makes an edit visible anyway (T1/T2). Writes are atomic (temp file + rename).
+ */
+
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, 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';
+import { assertRowPath, assertTicketId, contentHash, ticketId, WorkerError } from './ticket.mjs';
+
+export const WORKER_FILE = 'worker.json';
+
+/** @param {string} repoRoot */
+export const queueDir = (repoRoot) => path.join(repoRoot, '.code-forge', 'queue');
+/** @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) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  try {
+    writeFileSync(tmp, text, { mode: 0o644 });
+    renameSync(tmp, file);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+/** @param {string} file @returns {any} parsed JSON, or null when missing or unparseable. */
+function readJSON(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @typedef {{ticket: string, run: string, block: string, file: string, content_hash: string, enqueued_at: string}} Ticket
+ */
+
+/**
+ * Enqueue `file` (already repo-root-relative) for review. Idempotent by content hash: the same
+ * content returns the same ticket and never rewrites it.
+ * @param {{repoRoot: string, run: string, block: string, file: string, now?: Date}} opts
+ * @returns {{ticket: string, status: 'queued' | 'done', file: string, content_hash: string}}
+ */
+export function enqueue({ repoRoot, run, block, file, now = new Date() }) {
+  const rel = assertRowPath(file);
+  const content_hash = contentHash(repoRoot, rel);
+  const ticket = ticketId({ run, block, file: rel, content_hash });
+  const target = path.join(queueDir(repoRoot), `${ticket}.json`);
+  if (!existsSync(target)) {
+    /** @type {Ticket} */
+    const body = { ticket, run, block, file: rel, content_hash, enqueued_at: now.toISOString() };
+    writeAtomic(target, `${JSON.stringify(body)}\n`);
+  }
+  return { ticket, status: isDone(repoRoot, ticket) ? 'done' : 'queued', file: rel, content_hash };
+}
+
+/** @param {string} repoRoot @param {string} ticket */
+export function isDone(repoRoot, ticket) {
+  return existsSync(path.join(queueDir(repoRoot), `${assertTicketId(ticket)}.done`));
+}
+
+/**
+ * Tickets with no done marker, oldest first (enqueue time, then id). Unparseable files are
+ * skipped here and refused by the worker when it reads them.
+ * @param {string} repoRoot
+ * @returns {string[]} ticket ids
+ */
+export function pendingTickets(repoRoot) {
+  let names;
+  try {
+    names = readdirSync(queueDir(repoRoot));
+  } catch {
+    return [];
+  }
+  const ids = names.filter((n) => /^[0-9a-f]{24}\.json$/.test(n)).map((n) => n.slice(0, 24));
+  const pending = ids.filter((id) => !names.includes(`${id}.done`));
+  const at = (/** @type {string} */ id) => {
+    const t = readJSON(path.join(queueDir(repoRoot), `${id}.json`));
+    return typeof t?.enqueued_at === 'string' ? t.enqueued_at : '';
+  };
+  return pending.map((id) => ({ id, at: at(id) })).sort((a, b) => (a.at === b.at ? (a.id < b.id ? -1 : 1) : a.at < b.at ? -1 : 1)).map((e) => e.id);
+}
+
+/**
+ * Read and re-validate a ticket (coder-writable): its id must match its content.
+ * @param {string} repoRoot @param {string} id
+ * @returns {Ticket}
+ * @throws {WorkerError} `bad-ticket` / `bad-path`
+ */
+export function readTicket(repoRoot, id) {
+  const t = readJSON(path.join(queueDir(repoRoot), `${assertTicketId(id)}.json`));
+  if (!t || typeof t !== 'object') throw new WorkerError('bad-ticket', `ticket ${id} is not readable JSON`);
+  assertRowPath(t.file);
+  if (typeof t.run !== 'string' || typeof t.block !== 'string' || typeof t.content_hash !== 'string' || ticketId(t) !== id) {
+    throw new WorkerError('bad-ticket', `ticket ${id} does not match its id`);
+  }
+  return /** @type {Ticket} */ (t);
+}
+
+/**
+ * Sign `result` with the run key and write it to `reviews/<run>/<ticket>.json`, then the done
+ * marker. The result is written first, so a done marker always has its result.
+ * @param {{repoRoot: string, runId: string, ticket: string, result: Record<string, any>, key: Buffer}} opts
+ * @returns {Record<string, any>} the signed result
+ */
+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`);
+  return signed;
+}
+
+/**
+ * Read a result without verifying it (the coder's `--wait` cannot read the run key).
+ * @param {string} repoRoot @param {string} runId @param {string} ticket
+ * @returns {Record<string, any> | null}
+ */
+export function readResult(repoRoot, runId, ticket) {
+  return readJSON(path.join(reviewsDir(repoRoot, runId), `${assertTicketId(ticket)}.json`));
+}
+
+/**
+ * Verify a result's MAC with the run key (the orchestrator and the block gate do this; §8.6).
+ * @param {string} repoRoot @param {string} runId @param {string} ticket
+ * @returns {Promise<{ok: boolean, reason?: string, result?: Record<string, any>}>}
+ */
+export async function verifyResult(repoRoot, runId, ticket) {
+  const file = path.join(reviewsDir(repoRoot, runId), `${assertTicketId(ticket)}.json`);
+  if (!existsSync(file)) return { ok: false, reason: 'missing' };
+  const result = readJSON(file);
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return { ok: false, reason: 'unparseable' };
+  if (result.ticket !== ticket || result.run !== runId) return { ok: false, reason: 'mismatch' };
+  const check = verifyRow(result, await loadKey(runId));
+  return check.ok ? { ok: true, result } : { ok: false, reason: check.reason };
+}
+
+/**
+ * Announce the serving worker in the queue directory (what `review-file` checks for liveness).
+ * @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() };
+  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} */
+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;
+}
+
+/** 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 });
+}
+
+/**
+ * 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
+ */
+export function liveWorker(repoRoot) {
+  const w = readWorker(repoRoot);
+  if (!w || !isAlive(w.pid)) return null;
+  if (w.start_time !== UNKNOWN_START_TIME && readStartTime(w.pid) !== w.start_time) return null;
+  return w;
+}
+