@jameslovespancakes/pi-plus 1.0.11 → 1.0.12

package/src/domains/workflows/runtime/budget.ts

@@ -0,0 +1,53 @@
+import type { WorkflowUsageSink } from "./usage.ts";
+
+/**
+ * Thrown by `agent()` when a run has consumed its token budget. Carries the
+ * configured ceiling and the output tokens spent so callers can report both.
+ */
+export class WorkflowBudgetExceededError extends Error {
+  constructor(
+    readonly total: number,
+    readonly spent: number,
+  ) {
+    super(`Workflow token budget exhausted: spent ${spent} output tokens of ${total}.`);
+    this.name = "WorkflowBudgetExceededError";
+  }
+}
+
+/**
+ * The budget handle exposed on `WorkflowApi`. Mirrors the built-in Workflow tool:
+ * `total` is the output-token ceiling (or `null` when unset), `spent()` is the
+ * output tokens consumed by recorded subagent attempts this run, and
+ * `remaining()` is the headroom left (`Infinity` when there is no ceiling).
+ *
+ * `spent()`/`remaining()` are LIVE — they re-read usage on every call so that
+ * `while (budget.total && budget.remaining() > N) { await agent(...) }` loops and
+ * `Math.floor(budget.total / N)` fleet-scaling see up-to-date numbers.
+ */
+export interface WorkflowBudget {
+  readonly total: number | null;
+  /** Output tokens consumed by recorded subagent attempts this run (sub-workflows included). */
+  spent(): number;
+  /** `total - spent()` clamped at 0, or `Infinity` when `total` is null. */
+  remaining(): number;
+}
+
+/** Refuse a new model turn after the run has consumed its output-token budget. */
+export function assertWorkflowBudgetAvailable(budget: WorkflowBudget): void {
+  if (budget.total !== null && budget.remaining() <= 0) {
+    throw new WorkflowBudgetExceededError(budget.total, budget.spent());
+  }
+}
+
+/**
+ * Build a budget backed by the run's usage sink. `spent()` reads
+ * `usage.snapshot().totals.output` — the same output-token sum surfaced in the
+ * usage line — so no separate token accounting is needed.
+ */
+export function createBudget(total: number | null, usage: WorkflowUsageSink): WorkflowBudget {
+  return {
+    total,
+    spent: () => usage.snapshot().totals.output,
+    remaining: () => (total === null ? Infinity : Math.max(0, total - usage.snapshot().totals.output)),
+  };
+}

package/src/domains/workflows/runtime/cancellation.ts

@@ -0,0 +1,87 @@
+export class WorkflowAbortError extends Error {
+  constructor(message = "Workflow aborted") {
+    super(message);
+    this.name = "WorkflowAbortError";
+  }
+}
+
+/** Abort reason used when a durable run can be resumed after its host session shuts down. */
+export class WorkflowPauseError extends WorkflowAbortError {
+  constructor(message = "Workflow paused because its host session shut down") {
+    super(message);
+    this.name = "WorkflowPauseError";
+  }
+}
+
+export function abortReason(signal: AbortSignal | undefined): Error {
+  const reason = signal?.reason;
+  if (safeInstanceOf(reason, Error)) return reason;
+  if (typeof reason === "string" && reason.length > 0) return new WorkflowAbortError(reason);
+  return new WorkflowAbortError();
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw abortReason(signal);
+}
+
+export function isFatalWorkflowError(error: unknown, signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return true;
+  if (safeInstanceOf(error, WorkflowAbortError)) return true;
+  if (typeof DOMException !== "undefined" && safeInstanceOf(error, DOMException)) {
+    try {
+      return error.name === "AbortError";
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+export function isWorkflowPauseError(error: unknown): error is WorkflowPauseError {
+  return safeInstanceOf(error, WorkflowPauseError);
+}
+
+export function linkAbortSignal(parent: AbortSignal | undefined, controller: AbortController): () => void {
+  if (!parent) return () => {};
+  if (parent.aborted) {
+    controller.abort(abortReason(parent));
+    return () => {};
+  }
+  const onAbort = () => controller.abort(abortReason(parent));
+  parent.addEventListener("abort", onAbort, { once: true });
+  return () => parent.removeEventListener("abort", onAbort);
+}
+
+export async function raceWithAbort<T>(operation: () => Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  throwIfAborted(signal);
+  if (!signal) return await operation();
+
+  return await new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const finish = (action: () => void) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      action();
+    };
+    const onAbort = () => finish(() => reject(abortReason(signal)));
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    void operation().then(
+      (value) => finish(() => resolve(value)),
+      (error: unknown) => finish(() => reject(error)),
+    );
+  });
+}
+
+function safeInstanceOf<T>(value: unknown, constructor: abstract new (...args: never[]) => T): value is T {
+  try {
+    return value instanceof constructor;
+  } catch {
+    return false;
+  }
+}

package/src/domains/workflows/runtime/command-completions.ts

@@ -0,0 +1,36 @@
+import { fuzzyFilter, type AutocompleteItem } from "@earendil-works/pi-tui";
+
+interface ArgumentCompletionCandidate {
+  readonly value: string;
+  readonly description?: string;
+}
+
+interface ArgumentPrefixParts {
+  readonly completed: readonly string[];
+  readonly current: string;
+  readonly base: string;
+}
+
+/** Split a slash-command argument prefix while retaining the text Pi will replace. */
+export function splitArgumentPrefix(argumentPrefix: string): ArgumentPrefixParts {
+  const match = /(\S*)$/.exec(argumentPrefix);
+  const current = match?.[1] ?? "";
+  const base = argumentPrefix.slice(0, argumentPrefix.length - current.length);
+  const completed = base.trim().split(/\s+/).filter(Boolean);
+  return { completed, current, base };
+}
+
+/** Complete the current argument and return full replacement values, as Pi expects. */
+export function completeCurrentArgument(
+  argumentPrefix: string,
+  candidates: readonly ArgumentCompletionCandidate[],
+): AutocompleteItem[] | null {
+  const { current, base } = splitArgumentPrefix(argumentPrefix);
+  const matches = fuzzyFilter([...candidates], current, (candidate) => candidate.value)
+    .map((candidate) => ({
+      value: `${base}${candidate.value}`,
+      label: candidate.value,
+      ...(candidate.description === undefined ? {} : { description: candidate.description }),
+    }));
+  return matches.length > 0 ? matches : null;
+}

package/src/domains/workflows/runtime/concurrency.ts

@@ -0,0 +1,403 @@
+import { performance } from "node:perf_hooks";
+import { abortReason, isFatalWorkflowError, throwIfAborted } from "./cancellation.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+/** Global agent semaphore. A null capacity is unlimited. */
+export class Semaphore {
+  private active = 0;
+  private readonly max: number | null;
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(max: number | null) {
+    if (max !== null && (!Number.isInteger(max) || max < 1)) {
+      throw new RangeError("Semaphore capacity must be a positive integer or null");
+    }
+    this.max = max;
+  }
+
+  async run<T>(fn: () => Promise<T>, options: { onQueueWaitMs?: (durationMs: number) => void; signal?: AbortSignal } = {}): Promise<T> {
+    throwIfAborted(options.signal);
+    const queuedAt = performance.now();
+    if (this.max !== null && this.active >= this.max) {
+      await this.waitForSlot(options.signal);
+    } else {
+      this.active++;
+    }
+    try {
+      options.onQueueWaitMs?.(performance.now() - queuedAt);
+      throwIfAborted(options.signal);
+      return await fn();
+    } finally {
+      // Transfer the reservation directly to the next waiter.
+      const next = this.waiters.shift();
+      if (next) next();
+      else this.active--;
+    }
+  }
+
+  private async waitForSlot(signal: AbortSignal | undefined): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      const cleanup = () => {
+        if (signal) signal.removeEventListener("abort", onAbort);
+      };
+      const waiter = () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve();
+      };
+      const onAbort = () => {
+        if (settled) return;
+        settled = true;
+        const index = this.waiters.indexOf(waiter);
+        if (index !== -1) this.waiters.splice(index, 1);
+        cleanup();
+        reject(abortReason(signal));
+      };
+      if (signal?.aborted) {
+        reject(abortReason(signal));
+        return;
+      }
+      this.waiters.push(waiter);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+}
+
+export interface ParallelOptions {
+  readonly signal?: AbortSignal;
+  readonly abortController?: AbortController;
+  readonly limit?: number;
+  /** Maximum time to drain already-started tasks after a fatal failure. */
+  readonly drainTimeoutMs?: number;
+}
+
+export interface ParallelSettledOptions {
+  readonly settled: true;
+}
+
+export interface ParallelSettledError {
+  readonly name?: string;
+  readonly message: string;
+  readonly code?: string;
+  readonly details?: Readonly<Record<string, string | number | boolean | null>>;
+}
+
+export type ParallelSettledResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: ParallelSettledError };
+
+export interface WorkflowParallel {
+  <T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+  <T>(thunks: Array<() => Promise<T>>, options: ParallelSettledOptions): Promise<Array<ParallelSettledResult<T>>>;
+}
+
+export interface PipelineOptions {
+  readonly signal?: AbortSignal;
+  readonly abortController?: AbortController;
+  /** Maximum time to drain already-started item chains after a fatal failure. */
+  readonly drainTimeoutMs?: number;
+}
+
+const DEFAULT_FATAL_DRAIN_TIMEOUT_MS = 1_000;
+
+export function compactResults<T>(values: ReadonlyArray<T | null | undefined>): T[] {
+  return values.filter((value): value is T => value != null);
+}
+
+/** Run every thunk concurrently and wait for all results; recoverable failures become null slots by default. */
+export function parallel<T>(
+  thunks: Array<() => Promise<T>>,
+  options: ParallelOptions & ParallelSettledOptions,
+): Promise<Array<ParallelSettledResult<T>>>;
+export function parallel<T>(thunks: Array<() => Promise<T>>, options?: ParallelOptions): Promise<Array<T | null>>;
+export async function parallel<T>(
+  thunks: Array<() => Promise<T>>,
+  options: ParallelOptions & Partial<ParallelSettledOptions> = {},
+): Promise<Array<T | null> | Array<ParallelSettledResult<T>>> {
+  if (options.settled) {
+    return await runParallel(
+      thunks,
+      options,
+      (value): ParallelSettledResult<T> => ({ ok: true, value }),
+      (error): ParallelSettledResult<T> => ({ ok: false, error: serializeParallelError(error) }),
+    );
+  }
+
+  return await runParallel(
+    thunks,
+    options,
+    (value): T | null => value,
+    (): T | null => null,
+  );
+}
+
+export function bindParallel(options: ParallelOptions): WorkflowParallel {
+  const executionOptions: ParallelOptions = {
+    signal: options.signal,
+    abortController: options.abortController,
+    limit: options.limit,
+    drainTimeoutMs: options.drainTimeoutMs,
+  };
+
+  function boundParallel<T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+  function boundParallel<T>(
+    thunks: Array<() => Promise<T>>,
+    workflowOptions: ParallelSettledOptions,
+  ): Promise<Array<ParallelSettledResult<T>>>;
+  async function boundParallel<T>(
+    thunks: Array<() => Promise<T>>,
+    workflowOptions?: ParallelSettledOptions,
+  ): Promise<Array<T | null> | Array<ParallelSettledResult<T>>> {
+    if (workflowOptions?.settled) {
+      return await parallel(thunks, { ...executionOptions, settled: true });
+    }
+    return await parallel(thunks, executionOptions);
+  }
+
+  return boundParallel;
+}
+
+async function runParallel<T, Result>(
+  thunks: Array<() => Promise<T>>,
+  options: ParallelOptions,
+  onSuccess: (value: T) => Result,
+  onFailure: (error: unknown) => Result,
+): Promise<Result[]> {
+  throwIfAborted(options.signal);
+  const results = Array.from<Result>({ length: thunks.length });
+  if (thunks.length === 0) return results;
+
+  const limit = normalizeLimit(options.limit, thunks.length);
+  return await new Promise<Result[]>((resolve, reject) => {
+    let terminal = false;
+    let nextIndex = 0;
+    let workersRemaining = limit;
+    let fatalFailure: { readonly error: unknown } | undefined;
+    let drainTimer: ReturnType<typeof setTimeout> | undefined;
+    const cleanup = () => {
+      options.signal?.removeEventListener("abort", onAbort);
+      if (drainTimer) clearTimeout(drainTimer);
+    };
+    const settle = (force = false) => {
+      if (terminal || (!force && workersRemaining > 0)) return;
+      terminal = true;
+      cleanup();
+      if (fatalFailure) reject(fatalFailure.error);
+      else resolve(results);
+    };
+    const recordFatalFailure = (error: unknown) => {
+      if (fatalFailure) return;
+      fatalFailure = { error };
+      options.abortController?.abort(error);
+      const timeoutMs = normalizeDrainTimeout(options.drainTimeoutMs);
+      drainTimer = setTimeout(() => settle(true), timeoutMs);
+    };
+    const completeWorker = () => {
+      workersRemaining--;
+      settle();
+    };
+    const onAbort = () => recordFatalFailure(abortReason(options.signal));
+    const runWorker = async () => {
+      while (true) {
+        if (fatalFailure) return;
+        throwIfAborted(options.signal);
+        const index = nextIndex++;
+        if (index >= thunks.length) return;
+        try {
+          const value = await thunks[index]();
+          if (fatalFailure) return;
+          results[index] = onSuccess(value);
+        } catch (error) {
+          if (fatalFailure) return;
+          if (isFatalWorkflowError(error, options.signal)) {
+            recordFatalFailure(error);
+            return;
+          }
+          results[index] = onFailure(error);
+        }
+      }
+    };
+
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted) onAbort();
+    for (let worker = 0; worker < limit; worker++) {
+      void runWorker().then(completeWorker, (error) => {
+        recordFatalFailure(error);
+        completeWorker();
+      });
+    }
+  });
+}
+
+function serializeParallelError(error: unknown): ParallelSettledError {
+  const message = readStringProperty(error, "message") ?? unknownErrorMessage(error);
+  const name = readStringProperty(error, "name");
+  const code = readStringProperty(error, "code");
+  const details = readSerializableDetails(error);
+  return {
+    ...(name && name.length > 0 ? { name } : {}),
+    message,
+    ...(code && code.length > 0 ? { code } : {}),
+    ...(details ? { details } : {}),
+  };
+}
+
+function readStringProperty(value: unknown, property: "message" | "name" | "code"): string | undefined {
+  const candidate = readProperty(value, property);
+  return typeof candidate === "string" ? candidate : undefined;
+}
+
+function readSerializableDetails(
+  value: unknown,
+): Readonly<Record<string, string | number | boolean | null>> | undefined {
+  const candidate = readProperty(value, "details");
+  if (typeof candidate !== "object" || candidate === null) return undefined;
+  try {
+    const details: Record<string, string | number | boolean | null> = {};
+    for (const [key, detail] of Object.entries(candidate)) {
+      if (
+        typeof detail === "string" ||
+        typeof detail === "boolean" ||
+        detail === null ||
+        (typeof detail === "number" && Number.isFinite(detail))
+      ) {
+        details[key] = detail;
+      }
+    }
+    return Object.keys(details).length > 0 ? details : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readProperty(value: unknown, property: string): unknown {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) return undefined;
+  try {
+    return Reflect.get(value, property);
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeLimit(limit: number | undefined, itemCount: number): number {
+  if (limit === undefined || !Number.isFinite(limit)) return Math.max(1, itemCount);
+  return Math.max(1, Math.min(itemCount, Math.trunc(limit)));
+}
+
+function normalizeDrainTimeout(timeoutMs: number | undefined): number {
+  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) return DEFAULT_FATAL_DRAIN_TIMEOUT_MS;
+  return Math.max(0, Math.trunc(timeoutMs));
+}
+
+/**
+ * Run each item through all stages independently. There is NO barrier between
+ * stages: item A can be in stage 3 while item B is still in stage 1. Actual agent
+ * concurrency is bounded by the run's Semaphore (inside each `agent()`), not here —
+ * so launching every item at once is safe.
+ *
+ * Each stage receives (previousResult, originalItem, index).
+ */
+export async function pipeline<Item, A>(
+  items: readonly Item[],
+  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+): Promise<Array<A | null>>;
+export async function pipeline<Item, A, B>(
+  items: readonly Item[],
+  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+  stage2: (prev: A, item: Item, index: number) => Promise<B>,
+): Promise<Array<B | null>>;
+export async function pipeline<Item, A, B, C>(
+  items: readonly Item[],
+  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+  stage2: (prev: A, item: Item, index: number) => Promise<B>,
+  stage3: (prev: B, item: Item, index: number) => Promise<C>,
+): Promise<Array<C | null>>;
+export async function pipeline<Item, A, B, C, D>(
+  items: readonly Item[],
+  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+  stage2: (prev: A, item: Item, index: number) => Promise<B>,
+  stage3: (prev: B, item: Item, index: number) => Promise<C>,
+  stage4: (prev: C, item: Item, index: number) => Promise<D>,
+): Promise<Array<D | null>>;
+export async function pipeline<Item, A, B, C, D, E>(
+  items: readonly Item[],
+  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+  stage2: (prev: A, item: Item, index: number) => Promise<B>,
+  stage3: (prev: B, item: Item, index: number) => Promise<C>,
+  stage4: (prev: C, item: Item, index: number) => Promise<D>,
+  stage5: (prev: D, item: Item, index: number) => Promise<E>,
+): Promise<Array<E | null>>;
+export async function pipeline(
+  items: readonly unknown[],
+  ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
+): Promise<Array<unknown | null>>;
+export async function pipeline(
+  items: readonly unknown[],
+  ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
+): Promise<Array<unknown | null>> {
+  return pipelineWithOptions(items, stages);
+}
+
+export function bindPipeline(options: PipelineOptions): Pipeline {
+  async function boundPipeline<Item, A>(
+    items: readonly Item[],
+    stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+  ): Promise<Array<A | null>>;
+  async function boundPipeline<Item, A, B>(
+    items: readonly Item[],
+    stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+    stage2: (prev: A, item: Item, index: number) => Promise<B>,
+  ): Promise<Array<B | null>>;
+  async function boundPipeline<Item, A, B, C>(
+    items: readonly Item[],
+    stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+    stage2: (prev: A, item: Item, index: number) => Promise<B>,
+    stage3: (prev: B, item: Item, index: number) => Promise<C>,
+  ): Promise<Array<C | null>>;
+  async function boundPipeline<Item, A, B, C, D>(
+    items: readonly Item[],
+    stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+    stage2: (prev: A, item: Item, index: number) => Promise<B>,
+    stage3: (prev: B, item: Item, index: number) => Promise<C>,
+    stage4: (prev: C, item: Item, index: number) => Promise<D>,
+  ): Promise<Array<D | null>>;
+  async function boundPipeline<Item, A, B, C, D, E>(
+    items: readonly Item[],
+    stage1: (prev: Item, item: Item, index: number) => Promise<A>,
+    stage2: (prev: A, item: Item, index: number) => Promise<B>,
+    stage3: (prev: B, item: Item, index: number) => Promise<C>,
+    stage4: (prev: C, item: Item, index: number) => Promise<D>,
+    stage5: (prev: D, item: Item, index: number) => Promise<E>,
+  ): Promise<Array<E | null>>;
+  async function boundPipeline(
+    items: readonly unknown[],
+    ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
+  ): Promise<Array<unknown | null>> {
+    return pipelineWithOptions(items, stages, options);
+  }
+  return boundPipeline;
+}
+
+export async function pipelineWithOptions(
+  items: readonly unknown[],
+  stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>,
+  options: PipelineOptions = {},
+): Promise<Array<unknown | null>> {
+  throwIfAborted(options.signal);
+  return await parallel(
+    items.map((item, index) => async () => {
+      throwIfAborted(options.signal);
+      let acc: unknown = item;
+      for (const stage of stages) {
+        throwIfAborted(options.signal);
+        acc = await stage(acc, item, index);
+      }
+      return acc;
+    }),
+    options,
+  );
+}
+
+export type Pipeline = typeof pipeline;

package/src/domains/workflows/runtime/debug.ts

@@ -0,0 +1,3 @@
+export function workflowDebug(message: string): void {
+  if (process.env.PI_WORKFLOW_DEBUG === "1") process.stderr.write(`[workflow] ${message}\n`);
+}

package/src/domains/workflows/runtime/diff-capture.ts

@@ -0,0 +1,81 @@
+import type { PerfSink } from "./perf.ts";
+import { runBoundedProcess, type BoundedProcessFailure } from "./process-runner.ts";
+import { parseAllowedDiffCommand, reviewDiffCommand, type ReviewDiffTarget } from "./review-diff-target.ts";
+
+export {
+  formatReviewDiffTarget,
+  GitReviewDiffTargetSchema,
+  isReviewDiffTarget,
+  parseAllowedDiffCommand,
+  PullRequestReviewDiffTargetSchema,
+  reviewDiffCommand,
+  ReviewDiffTargetSchema,
+  reviewGitDiffBaseline,
+  type GitDiffBaselineTarget,
+  type GitReviewDiffTarget,
+  type PullRequestReviewDiffTarget,
+  type ReviewDiffTarget,
+} from "./review-diff-target.ts";
+
+interface DiffCaptureResultBase {
+  readonly stdout: string;
+  readonly durationMs: number;
+  readonly bytes: number;
+}
+
+export type DiffCaptureResult =
+  | (DiffCaptureResultBase & { readonly ok: true; readonly error?: undefined; readonly failure?: undefined })
+  | (DiffCaptureResultBase & { readonly ok: false; readonly error: string; readonly failure: DiffCaptureFailure });
+
+export type DiffCaptureFailure = BoundedProcessFailure | { readonly kind: "invalid-target"; readonly message: string };
+
+export interface DiffCaptureOptions {
+  readonly cwd: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxBufferBytes: number;
+  readonly perf?: PerfSink;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly killGraceMs?: number;
+}
+
+export async function captureDiff(command: string, options: DiffCaptureOptions): Promise<DiffCaptureResult> {
+  const parsed = parseAllowedDiffCommand(command);
+  if ("error" in parsed) {
+    return {
+      ok: false,
+      stdout: "",
+      durationMs: 0,
+      bytes: 0,
+      error: parsed.error,
+      failure: { kind: "invalid-target", message: parsed.error },
+    };
+  }
+
+  return await captureDiffTarget(parsed, options);
+}
+
+export async function captureDiffTarget(target: ReviewDiffTarget, options: DiffCaptureOptions): Promise<DiffCaptureResult> {
+  const command = reviewDiffCommand(target);
+  const result = await runBoundedProcess({
+    file: command.file,
+    args: command.args,
+    cwd: options.cwd,
+    env: diffCaptureEnv(options.env),
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+    maxBufferBytes: options.maxBufferBytes,
+    killGraceMs: options.killGraceMs,
+    abortError: "diff capture aborted",
+    timeoutError: `diff capture timed out after ${options.timeoutMs}ms`,
+    maxBufferError: `diff capture exceeded ${options.maxBufferBytes} bytes`,
+    exitError: (stderr, code, signal) => stderr.trim() || `diff command exited with code ${code ?? `signal ${signal ?? "unknown"}`}`,
+  });
+  options.perf?.observe("diff.capture_ms", result.durationMs);
+  options.perf?.observe("diff.bytes", result.bytes);
+  return result;
+}
+
+function diffCaptureEnv(env: NodeJS.ProcessEnv | undefined): NodeJS.ProcessEnv {
+  return { ...(env ?? process.env), GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" };
+}