@a2f0/agent-tool 0.1.44 → 0.1.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "packageManager": "bun@1.4.4",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",

package/src/commands/group.ts

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, writeFileSync } from "node:fs";
+import { constants } from "node:os";
 import path from "node:path";
-import { runCommand, type RunReceipt } from "./run";
+import { FORWARDED_SIGNALS, runCommand, type RunReceipt } from "./run";
 import { assert, git, head, oid, option, output } from "../workflows/core";
 import { gitEnvironment } from "../git/environment";
 
@@ -60,6 +61,7 @@ export type GroupEvent =
   | { type: "stepStarted"; index: number }
   | { type: "stepFinished"; index: number; receipt: RunReceipt }
   | { type: "failed"; error: string }
+  | { type: "interrupted"; signal: NodeJS.Signals }
   | { type: "finished"; passed: boolean; endedAt: string; durationMs: number }
   | { type: "settled"; after: SourceState }
   | { type: "settleFailed"; error: string };
@@ -69,7 +71,11 @@ export type GroupEvent =
  * ignored: a step starts only from pending, finishes only while running, and
  * nothing but the final source read changes a finished group. A failure while
  * a step runs (its runner could not start) finishes that step as failed with
- * no receipt, so a finished report never shows a step still running.
+ * no receipt, so a finished report never shows a step still running. An
+ * interruption counts only while the group runs: it records its signal as the
+ * error (unless one is already recorded), lets the running step finish with its
+ * receipt, and keeps the group from passing. A finished group ignores it, so
+ * its report and exit status stand.
  */
 export function groupTransition(record: GroupRecord, event: GroupEvent): GroupRecord {
   const step = (index: number, next: GroupStep) => ({ ...record, steps: record.steps.map((item, at) => at === index ? next : item) });
@@ -85,8 +91,10 @@ export function groupTransition(record: GroupRecord, event: GroupEvent): GroupRe
     case "failed":
       if (record.status !== "running") return record;
       return { ...record, steps: record.steps.map(item => item.status === "running" ? { label: item.label, status: "failed", receipt: null } : item), error: event.error };
+    case "interrupted":
+      return record.status === "running" && record.error === null ? { ...record, error: `Interrupted by ${event.signal}.` } : record;
     case "finished":
-      return record.status === "running" ? { ...record, status: event.passed ? "passed" : "failed", endedAt: event.endedAt, durationMs: event.durationMs } : record;
+      return record.status === "running" ? { ...record, status: event.passed && record.error === null ? "passed" : "failed", endedAt: event.endedAt, durationMs: event.durationMs } : record;
     case "settled":
       return record.status !== "running" && record.after === null ? { ...record, after: event.after } : record;
     case "settleFailed":
@@ -108,21 +116,53 @@ export async function runGroup(args: string[]): Promise<number> {
   const started = performance.now();
   let record: GroupRecord = { schemaVersion: 1, id, label: plan.label, startedAt: new Date().toISOString(), endedAt: null, durationMs: 0, status: "running", before, after: null, steps: plan.steps.map(step => ({ label: step.label, status: "pending", receipt: null })), error: null };
   const send = (event: GroupEvent) => { record = groupTransition(record, event); };
-  save(report, record);
+  // A signal must not end the process before the report is finished: the step's runner forwards it
+  // to the step and returns, the group stops, and the signal is raised again once the report is saved.
+  // Only a running group is interrupted; a signal handled after it finished changes nothing.
+  const interrupt: { signal: NodeJS.Signals | null } = { signal: null };
+  const handlers = FORWARDED_SIGNALS.map(value => [value, () => {
+    if (record.status !== "running") return;
+    interrupt.signal ??= value;
+    send({ type: "interrupted", signal: value });
+  }] as const);
+  for (const [value, handler] of handlers) process.on(value, handler);
+  // Handlers run only between tasks, and a signal still queued when they are removed is lost.
+  // Fingerprinting and saving are synchronous, so yield to let a pending signal apply first.
+  const handleSignals = () => new Promise(resolve => setImmediate(resolve));
   let code = 0;
   try {
-    for (const [index, step] of plan.steps.entries()) {
-      send({ type: "stepStarted", index }); save(report, record);
-      code = await runCommand(["--label", step.label, "--", ...step.command], receipt => { send({ type: "stepFinished", index, receipt }); save(report, record); }, { quiet: true, reraiseChildSignal: false });
-      const after = sourceState();
-      assert(JSON.stringify(after) === JSON.stringify(before), "Source state changed during validation; results do not establish the current checkout.");
-      if (code !== 0) break;
-    }
-  } catch (error) { code = 1; send({ type: "failed", error: (error as Error).message }); }
-  send({ type: "finished", passed: code === 0, endedAt: new Date().toISOString(), durationMs: Math.round(performance.now() - started) });
-  try { send({ type: "settled", after: sourceState() }); } catch (error) { code = 1; send({ type: "settleFailed", error: (error as Error).message }); }
-  save(report, record);
-  output({ ...record, report }); return code;
+    save(report, record);
+    try {
+      for (const [index, step] of plan.steps.entries()) {
+        await handleSignals();
+        if (interrupt.signal) break;
+        send({ type: "stepStarted", index }); save(report, record);
+        code = await runCommand(["--label", step.label, "--", ...step.command], receipt => { send({ type: "stepFinished", index, receipt }); save(report, record); }, { quiet: true, reraiseChildSignal: false, reraiseInterrupt: false });
+        const after = sourceState();
+        assert(JSON.stringify(after) === JSON.stringify(before), "Source state changed during validation; results do not establish the current checkout.");
+        if (code !== 0) break;
+      }
+    } catch (error) { code = 1; send({ type: "failed", error: (error as Error).message }); }
+    const endedAt = new Date().toISOString(), durationMs = Math.round(performance.now() - started);
+    let settle: GroupEvent;
+    try { settle = { type: "settled", after: sourceState() }; } catch (error) { code = 1; settle = { type: "settleFailed", error: (error as Error).message }; }
+    await handleSignals();
+    send({ type: "finished", passed: code === 0, endedAt, durationMs }); send(settle);
+    save(report, record);
+    output({ ...record, report });
+    // Signals that arrived while publishing reach the handlers, which ignore them now.
+    await handleSignals();
+  } finally {
+    for (const [value, handler] of handlers) process.removeListener(value, handler);
+  }
+  const { signal } = interrupt;
+  if (signal) {
+    // Preserve signal termination for calling shells and supervisors, as `run` does.
+    process.kill(process.pid, signal);
+    await new Promise(resolve => setTimeout(resolve, 100));
+    return 128 + (constants.signals[signal] ?? 0);
+  }
+  return code;
 }
 
 export function listRuns(args: string[]): number {

package/src/commands/run.ts

@@ -4,12 +4,16 @@ import { constants } from "node:os";
 import { DEFAULT_LIMITS, outputLimit, plainText, printLogTail } from "./output";
 import { createLog } from "./logFile";
 
-const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
+export const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
 
 export interface RunReceipt { status: string; label?: string; exitCode: number; signal: string | null; durationMs: number; outputBytes: number; log: string; leftoverProcessGroup?: number }
 
-/** Run directly into a private file: child output never accumulates in memory. */
-export async function runCommand(args: string[], record?: (receipt: RunReceipt) => void, options: { quiet?: boolean; reraiseChildSignal?: boolean } = {}): Promise<number> {
+/**
+ * Run directly into a private file: child output never accumulates in memory.
+ * A caller that must record the interruption before exiting passes
+ * `reraiseInterrupt: false` and re-raises the signal itself.
+ */
+export async function runCommand(args: string[], record?: (receipt: RunReceipt) => void, options: { quiet?: boolean; reraiseChildSignal?: boolean; reraiseInterrupt?: boolean } = {}): Promise<number> {
   const limits = { ...DEFAULT_LIMITS };
   let label: string | undefined;
   while (args[0] !== "--" && args.length) {
@@ -99,7 +103,7 @@ export async function runCommand(args: string[], record?: (receipt: RunReceipt)
   }
   // Preserve signal termination for calling shells/supervisors, after the receipt.
   if (signal) {
-    if (interrupted || options.reraiseChildSignal !== false) {
+    if (interrupted ? options.reraiseInterrupt !== false : options.reraiseChildSignal !== false) {
       process.kill(process.pid, signal);
       // Let the runtime deliver its signal before main sets process.exitCode
       // can turn signal termination into an ordinary numeric exit under load.

package/src/harnesses.ts

@@ -12,7 +12,7 @@ export interface Harness {
   skillDirectory: string;
   defaultEffort: ReviewEffort;
   accessNote: string;
-  review: (prompt: string, effort: ReviewEffort, snapshotRoot: string) => number;
+  review: (prompt: string, effort: ReviewEffort, snapshotRoot: string) => Promise<number>;
 }
 
 /** Harness-specific discovery and invocation stay behind this small boundary. */
@@ -29,7 +29,7 @@ export function harnessNamed(name: string): Harness {
 }
 
 /** An explicit local base enables review without GitHub or network access. */
-export function review(rootDir: string, name: string, effortArg?: string, base?: string): number {
+export function review(rootDir: string, name: string, effortArg?: string, base?: string): Promise<number> {
   const harness = harnessNamed(name);
   const effort = resolveReviewEffort(effortArg, harness.defaultEffort);
   const context: PrContext = base === undefined ? resolveReviewContext() : {
@@ -39,8 +39,8 @@ export function review(rootDir: string, name: string, effortArg?: string, base?:
     title: "",
     baseRef: run("git", ["rev-parse", "--verify", "--end-of-options", `${base}^{commit}`]),
   };
-  return withPinnedReviewInput(rootDir, context, input => {
-    const exitCode = harness.review(buildReviewPrompt({
+  return withPinnedReviewInput(rootDir, context, async input => {
+    const exitCode = await harness.review(buildReviewPrompt({
       context,
       diff: input.diff,
       reviewInstructions: input.reviewInstructions,

package/src/review/diagnostics.ts

@@ -4,12 +4,12 @@ import { DEFAULT_LIMITS, printLogTail } from "../commands/output";
 
 /** Reviewer stderr is a transcript, not the review. Keep it off the model's
  * context while retaining complete local evidence and bounded failure details. */
-export function withReviewDiagnostics<T extends { status: number | null; error?: Error }>(
-  reviewer: string, run: (fd: number) => T,
-): T {
+export async function withReviewDiagnostics<T extends { status: number | null; error?: Error }>(
+  reviewer: string, run: (fd: number) => T | Promise<T>,
+): Promise<T> {
   const { directory, log, fd } = createLog("agent-tool-review-log-");
   try {
-    const result = run(fd);
+    const result = await run(fd);
     const outputBytes = fstatSync(fd).size;
     if (outputBytes > 0) {
       writeSync(2, `${JSON.stringify({ reviewer, outputBytes, log })}\n`);

package/src/review/pinnedReviewInput.ts

@@ -3,6 +3,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 
 import { type PrContext } from "../git/prContext";
 import { readReviewInstructions } from "./reviewPrompt";
+import { withReviewInterrupts } from "./reviewerProcess";
 import { withReviewSnapshot } from "./reviewSnapshot";
 
 interface PinnedReviewInput {
@@ -61,12 +62,24 @@ function ensureChanges(
   }
 }
 
-/** Resolve refs once, then derive every review artifact from those commit IDs. */
+/**
+ * Resolve refs once, then derive every review artifact from those commit IDs.
+ * An interruption stops the reviewer and removes the snapshot before the
+ * signal ends the process.
+ */
 export function withPinnedReviewInput<T>(
   rootDir: string,
   context: PrContext,
-  callback: (input: PinnedReviewInput) => T,
-): T {
+  callback: (input: PinnedReviewInput) => T | Promise<T>,
+): Promise<T> {
+  return withReviewInterrupts(() => pinnedReviewInput(rootDir, context, callback));
+}
+
+async function pinnedReviewInput<T>(
+  rootDir: string,
+  context: PrContext,
+  callback: (input: PinnedReviewInput) => T | Promise<T>,
+): Promise<T> {
   const baseCommit = resolveCommit(rootDir, context.baseRef);
   const headCommit = resolveCommit(rootDir, "HEAD");
   ensureChanges(rootDir, baseCommit, headCommit);

package/src/review/reviewSnapshot.ts

@@ -48,11 +48,11 @@ function removeSnapshot(tempRoot: string, repositoryRoot: string): void {
  * Run a callback against immutable raw blobs from an exact commit.
  * Working-tree edits, untracked files, and `.git` metadata never enter it.
  */
-export function withReviewSnapshot<T>(
+export async function withReviewSnapshot<T>(
   rootDir: string,
   commit: string,
-  callback: (repositoryRoot: string) => T,
-): T {
+  callback: (repositoryRoot: string) => T | Promise<T>,
+): Promise<T> {
   const tempRoot = mkdtempSync(path.join(tmpdir(), "agent-tool-review-"));
   const repositoryRoot = path.join(tempRoot, "repository");
   mkdirSync(repositoryRoot);
@@ -60,7 +60,7 @@ export function withReviewSnapshot<T>(
   try {
     materializeRawGitTree(rootDir, commit, repositoryRoot);
     makeTreeReadOnly(repositoryRoot);
-    return callback(repositoryRoot);
+    return await callback(repositoryRoot);
   } finally {
     removeSnapshot(tempRoot, repositoryRoot);
   }

package/src/review/reviewerProcess.ts

@@ -0,0 +1,162 @@
+import { type ChildProcess, spawn } from "node:child_process";
+
+import { FORWARDED_SIGNALS } from "../commands/run";
+import type { ReviewerEnv } from "./runReview";
+
+/** How long a reviewer asked to stop may take before it is killed. */
+export const STOP_GRACE_MS = 5000;
+/** How long to wait for a reviewer's stdout to close after it exits, in case a descendant holds it. */
+const CLOSE_GRACE_MS = 2000;
+
+/** One reviewer run, shaped like `spawnSync`'s result so `spawnExitCode` reads either. */
+export interface ReviewerResult {
+  readonly status: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly stdout: string;
+  readonly error?: Error;
+}
+
+/** A started reviewer, as the interruption handler sees it. */
+interface Reviewer { stop(signal: NodeJS.Signals): void }
+
+interface ReviewScope {
+  signal: NodeJS.Signals | null;
+  readonly reviewers: Set<Reviewer>;
+}
+
+let scope: ReviewScope | null = null;
+
+/** Signal handlers run only between tasks; let one that is already pending run first. */
+const handlePendingSignals = () => new Promise(resolve => setImmediate(resolve));
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+// Each reviewer leads its own process group, so stopping it reaches every descendant that stays
+// in the group (a CLI wrapper's native binary, a shell's children), as `agent-tool run` does.
+const grouped = process.platform !== "win32";
+
+function signalGroup(child: ChildProcess, signal: NodeJS.Signals | 0): boolean {
+  if (!child.pid) return false;
+  try {
+    if (grouped) process.kill(-child.pid, signal);
+    else if (signal) child.kill(signal);
+    else return child.exitCode === null && child.signalCode === null;
+    return true;
+  } catch (error) {
+    // EPERM: the group still exists, now holding a process this user cannot signal.
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Runs review work so that SIGINT, SIGTERM, and SIGHUP stop it instead of
+ * ending agent-tool at once: the running reviewer is stopped (and killed after
+ * a grace period), no further attempt starts, the work's own cleanup runs (the
+ * snapshot and temporary directories), and only then is the signal raised
+ * again, so callers still see termination by that signal.
+ */
+export async function withReviewInterrupts<T>(work: () => Promise<T>): Promise<T> {
+  if (scope) return work();
+  const current: ReviewScope = { signal: null, reviewers: new Set() };
+  const handlers = FORWARDED_SIGNALS.map(value => [value, () => {
+    current.signal ??= value;
+    for (const reviewer of current.reviewers) reviewer.stop(value);
+  }] as const);
+  scope = current;
+  for (const [value, handler] of handlers) process.on(value, handler);
+  try {
+    return await work();
+  } finally {
+    // Cleanup is synchronous; a signal that arrived during it is still pending.
+    await handlePendingSignals();
+    for (const [value, handler] of handlers) process.removeListener(value, handler);
+    scope = null;
+    if (current.signal) {
+      process.kill(process.pid, current.signal);
+      // Let the runtime deliver the signal before the caller sets an exit code.
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  }
+}
+
+/**
+ * Run a reviewer CLI without blocking the event loop, so an interruption can
+ * stop it. The prompt goes to stdin, stdout is captured up to `maxBuffer`, and
+ * stderr goes to the `stderr` descriptor. Past `timeoutMs` or `maxBuffer` the
+ * reviewer is stopped, and the result carries an `ETIMEDOUT` or `ENOBUFS`
+ * error as `spawnSync` reports them. A stopped reviewer's process group gets
+ * the signal, then SIGKILL after `STOP_GRACE_MS`; the run settles only once
+ * that group is gone, and a group the reviewer left behind when it exited is
+ * stopped the same way. Inside an interrupted `withReviewInterrupts`, no
+ * reviewer starts.
+ */
+export async function spawnReviewer(
+  command: string,
+  args: string[],
+  options: { input: string; cwd: string; env: ReviewerEnv; timeoutMs: number; maxBuffer: number; stderr: number },
+): Promise<ReviewerResult> {
+  const owner = scope;
+  if (owner) await handlePendingSignals();
+  if (owner?.signal) {
+    return { status: null, signal: null, stdout: "", error: new Error(`review interrupted by ${owner.signal}`) };
+  }
+  let child: ChildProcess;
+  try {
+    child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ["pipe", "pipe", options.stderr], detached: grouped });
+  } catch (spawnError) {
+    return { status: null, signal: null, stdout: "", error: spawnError as Error };
+  }
+  const chunks: Buffer[] = [];
+  let size = 0;
+  let error: Error | undefined;
+  let killAt: number | null = null;
+  const reviewer: Reviewer = {
+    stop(signal) {
+      signalGroup(child, signal);
+      killAt ??= Date.now() + STOP_GRACE_MS;
+    },
+  };
+  const fail = (code: string, message: string) => {
+    error ??= Object.assign(new Error(message), { code });
+    reviewer.stop("SIGTERM");
+  };
+  owner?.reviewers.add(reviewer);
+  const timer = setTimeout(() => fail("ETIMEDOUT", `${command} timed out after ${options.timeoutMs} ms`), options.timeoutMs);
+  // While stopping, escalate to SIGKILL at the deadline even if the reviewer has not exited yet.
+  const escalation = setInterval(() => { if (killAt !== null && Date.now() >= killAt) signalGroup(child, "SIGKILL"); }, 50);
+  try {
+    child.stdout!.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > options.maxBuffer) fail("ENOBUFS", `${command} wrote more than ${options.maxBuffer} bytes to stdout`);
+      else chunks.push(chunk);
+    });
+    const closed = new Promise<void>(resolve => child.stdout!.once("close", () => resolve()));
+    // A reviewer may exit without reading the whole prompt.
+    child.stdin!.on("error", () => {});
+    child.stdin!.end(options.input);
+    const exit = await new Promise<{ status: number | null; signal: NodeJS.Signals | null }>(resolve => {
+      child.once("error", spawnError => {
+        error ??= spawnError;
+        if (child.pid === undefined) resolve({ status: null, signal: null });
+      });
+      child.once("exit", (status, signal) => resolve({ status, signal }));
+    });
+    if (child.pid !== undefined) {
+      // The review is over once its process group is: stop whatever the reviewer left in it.
+      if (signalGroup(child, 0)) reviewer.stop("SIGTERM");
+      while (signalGroup(child, 0)) {
+        if (killAt !== null && Date.now() >= killAt + STOP_GRACE_MS) break;
+        await sleep(25);
+      }
+      // A descendant outside the group may still hold stdout; do not wait on it forever.
+      let grace: ReturnType<typeof setTimeout> | undefined;
+      await Promise.race([closed, new Promise(resolve => { grace = setTimeout(resolve, CLOSE_GRACE_MS); })]);
+      clearTimeout(grace);
+      child.stdout?.destroy();
+    }
+    return { status: exit.status, signal: exit.signal, stdout: Buffer.concat(chunks).toString("utf8"), ...(error ? { error } : {}) };
+  } finally {
+    clearTimeout(timer);
+    clearInterval(escalation);
+    owner?.reviewers.delete(reviewer);
+  }
+}

package/src/review/runReview.ts

@@ -37,13 +37,13 @@ export const MAX_REVIEW_ATTEMPTS = 2;
  * line with them while the in-memory check below still saw a complete review
  * and exited 0.
  */
-export function relayReviewWithRetry(
+export async function relayReviewWithRetry(
   command: string,
-  runAttempt: () => ReviewAttempt,
-): number {
+  runAttempt: () => ReviewAttempt | Promise<ReviewAttempt>,
+): Promise<number> {
   let last: ReviewAttempt = { exitCode: 1, review: "" };
   for (let attempt = 1; attempt <= MAX_REVIEW_ATTEMPTS; attempt += 1) {
-    last = runAttempt();
+    last = await runAttempt();
     if (last.exitCode !== 0) {
       writeSync(1, last.review);
       return last.exitCode;

package/src/review/solicitClaudeCodeReview.ts

@@ -1,6 +1,5 @@
 import { reviewExecutable } from "./executable";
 import { loadConfig } from "../config";
-import { spawnSync } from "node:child_process";
 import path from "node:path";
 
 import {
@@ -17,6 +16,7 @@ import {
 import { buildReviewPrompt, CLAUDE_ACCESS_NOTE } from "./reviewPrompt";
 import { type ReviewerEnv, relayReviewWithRetry } from "./runReview";
 import { withReviewDiagnostics } from "./diagnostics";
+import { spawnReviewer } from "./reviewerProcess";
 
 /**
  * Tools the reviewer gets. Read-only, and deliberately not empty: the diff alone
@@ -77,30 +77,29 @@ export function buildClaudeReviewArgs(
  * that failure is stochastic — so a caller's fallback chain treats a degenerate
  * review the same as a crashed one.
  */
-export function spawnClaudeReview(
+export async function spawnClaudeReview(
   prompt: string,
   effort: ReviewEffort,
   snapshotRoot: string,
   env: ReviewerEnv = process.env,
-): number {
+): Promise<number> {
   const executable = reviewExecutable("claude", env);
   if (executable === undefined) {
     process.stderr.write("Claude executable unavailable outside the repository.\n");
     return 1;
   }
-  return relayReviewWithRetry("claude", () => {
+  return await relayReviewWithRetry("claude", async () => {
     // Captured rather than inherited: a review has to be read to be judged, and
     // `claude` exits 0 whether it reviewed the diff or merely said it would.
     // `--print` emits the review in one final block, so nothing streams anyway.
-    const result = withReviewDiagnostics("claude", fd => spawnSync(
+    const result = await withReviewDiagnostics("claude", fd => spawnReviewer(
       executable,
       buildClaudeReviewArgs(effort, snapshotRoot, loadConfig().review.claudeModel),
       {
-        stdio: ["pipe", "pipe", fd],
+        stderr: fd,
         input: prompt,
-        encoding: "utf8",
         maxBuffer: MAX_BUFFER_BYTES,
-          timeout: loadConfig().review.timeoutMs,
+        timeoutMs: loadConfig().review.timeoutMs,
         cwd: snapshotRoot,
         // Passed explicitly so `claude` resolves against this PATH rather than
         // the one the runtime snapshotted at startup.
@@ -124,7 +123,7 @@ export function spawnClaudeReview(
 export function solicitClaudeCodeReview(
   rootDir: string,
   effortArg?: string,
-): number {
+): Promise<number> {
   const effort = resolveReviewEffort(effortArg, DEFAULT_CLAUDE_EFFORT);
   const context = resolveReviewContext();
   return withPinnedReviewInput(rootDir, context, (input) => {

package/src/review/solicitCodexReview.ts

@@ -1,6 +1,5 @@
 import { reviewExecutable } from "./executable";
 import { loadConfig } from "../config";
-import { spawnSync } from "node:child_process";
 import {
   mkdtempSync,
   readFileSync,
@@ -23,6 +22,7 @@ import {
 import { buildReviewPrompt, CODEX_ACCESS_NOTE } from "./reviewPrompt";
 import { type ReviewerEnv, relayReviewWithRetry } from "./runReview";
 import { withReviewDiagnostics } from "./diagnostics";
+import { spawnReviewer } from "./reviewerProcess";
 
 /**
  * Build the `codex exec` argv. `exec`, not `review`: `codex review` writes its
@@ -123,12 +123,12 @@ function readLastMessage(lastMessageFile: string): string {
  * Degenerate exit-0 output is retried once via
  * the shared gate, same as the Claude path.
  */
-export function spawnCodexReview(
+export async function spawnCodexReview(
   prompt: string,
   effort: ReviewEffort,
   snapshotRoot: string,
   env: ReviewerEnv = process.env,
-): number {
+): Promise<number> {
   const codexExecutable = reviewExecutable("codex", env);
   if (codexExecutable === undefined) {
     process.stderr.write("Codex executable unavailable outside the repository.\n");
@@ -138,12 +138,12 @@ export function spawnCodexReview(
   const codexRuntimeRoot = path.dirname(codexExecutable);
   let attempt = 0;
   try {
-    return relayReviewWithRetry("codex", () => {
+    return await relayReviewWithRetry("codex", async () => {
       // A fresh file per attempt, so a retry that crashes before writing can
       // never be read as the previous attempt's stale message.
       attempt += 1;
       const lastMessageFile = path.join(outDir, `review-${attempt}.md`);
-      const result = withReviewDiagnostics("codex", fd => spawnSync(
+      const result = await withReviewDiagnostics("codex", fd => spawnReviewer(
         codexExecutable,
         buildCodexReviewArgs(
           effort,
@@ -153,11 +153,10 @@ export function spawnCodexReview(
           loadConfig().review.codexModel,
         ),
         {
-          stdio: ["pipe", "pipe", fd],
+          stderr: fd,
           input: prompt,
-          encoding: "utf8",
           maxBuffer: MAX_BUFFER_BYTES,
-          timeout: loadConfig().review.timeoutMs,
+          timeoutMs: loadConfig().review.timeoutMs,
           // Codex loads project AGENTS.md from its cwd. Keep cwd neutral and
           // grant read-only access to the reviewed repository explicitly.
           cwd: outDir,
@@ -181,7 +180,7 @@ export function spawnCodexReview(
 export function solicitCodexReview(
   rootDir: string,
   effortArg?: string,
-): number {
+): Promise<number> {
   const effort = resolveReviewEffort(effortArg, DEFAULT_CODEX_EFFORT);
   const context = resolveReviewContext();
   return withPinnedReviewInput(rootDir, context, (input) => {

package/src/review/solicitOpencodeReview.ts

@@ -1,6 +1,5 @@
 import { reviewExecutable } from "./executable";
 import { loadConfig, DEFAULT_CONFIG } from "../config";
-import { spawnSync } from "node:child_process";
 import { mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -19,6 +18,7 @@ import {
 import { buildReviewPrompt, OPENCODE_ACCESS_NOTE } from "./reviewPrompt";
 import { type ReviewerEnv, relayReviewWithRetry } from "./runReview";
 import { withReviewDiagnostics } from "./diagnostics";
+import { spawnReviewer } from "./reviewerProcess";
 
 /**
  * The model every opencode review runs under. Pinned so the review never
@@ -150,12 +150,12 @@ export function buildOpencodeReviewArgs(variant: string, model = OPENCODE_MODEL)
  * needs still resolves. Global config still loads, but the inline config's
  * agent-scoped deny rules take precedence over whatever it sets.
  */
-export function spawnOpencodeReview(
+export async function spawnOpencodeReview(
   prompt: string,
   effort: ReviewEffort,
   snapshotRoot: string,
   env: ReviewerEnv = process.env,
-): number {
+): Promise<number> {
   const executable = reviewExecutable("opencode", env);
   if (executable === undefined) {
     process.stderr.write("OpenCode executable unavailable outside the repository.\n");
@@ -164,16 +164,15 @@ export function spawnOpencodeReview(
   const model = loadConfig().review.opencodeModel;
   const outDir = mkdtempSync(path.join(tmpdir(), "agent-tool-opencode-"));
   try {
-    return relayReviewWithRetry("opencode", () => {
-      const result = withReviewDiagnostics("opencode", fd => spawnSync(
+    return await relayReviewWithRetry("opencode", async () => {
+      const result = await withReviewDiagnostics("opencode", fd => spawnReviewer(
         executable,
         buildOpencodeReviewArgs(resolveOpencodeVariant(effort, loadConfig().review.opencodeVariants), model),
         {
-          stdio: ["pipe", "pipe", fd],
+          stderr: fd,
           input: prompt,
-          encoding: "utf8",
           maxBuffer: MAX_BUFFER_BYTES,
-          timeout: loadConfig().review.timeoutMs,
+          timeoutMs: loadConfig().review.timeoutMs,
           // Neutral cwd: opencode would otherwise load the snapshot's
           // branch-controlled config and instructions into the reviewer.
           cwd: outDir,
@@ -206,7 +205,7 @@ export function spawnOpencodeReview(
 export function solicitOpencodeReview(
   rootDir: string,
   effortArg?: string,
-): number {
+): Promise<number> {
   const effort = resolveReviewEffort(effortArg, DEFAULT_OPENCODE_EFFORT);
   const context = resolveReviewContext();
   return withPinnedReviewInput(rootDir, context, (input) => {

package/src/runAgentToolAction.ts

@@ -17,9 +17,9 @@ export interface AgentToolActions {
   readonly solicitClaudeCodeReview: (
     rootDir: string,
     effort?: string,
-  ) => number;
-  readonly solicitCodexReview: (rootDir: string, effort?: string) => number;
-  readonly solicitOpencodeReview: (rootDir: string, effort?: string) => number;
+  ) => number | Promise<number>;
+  readonly solicitCodexReview: (rootDir: string, effort?: string) => number | Promise<number>;
+  readonly solicitOpencodeReview: (rootDir: string, effort?: string) => number | Promise<number>;
   readonly squashMerge: (
     rootDir: string,
     subject?: string,
@@ -56,7 +56,7 @@ export function runAgentToolAction(
   rootDir: string,
   args: readonly string[],
   actions: AgentToolActions = defaultActions,
-): number {
+): number | Promise<number> {
   const [action, ...positionals] = args;
   const [first, second, third] = positionals;
   switch (action) {