pi-workflow-engine 0.8.0 → 0.10.0

package/.pi/extensions/pi-workflow-engine/src/process-runner.ts

@@ -0,0 +1,96 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+
+export interface BoundedProcessOptions {
+  readonly file: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxBufferBytes?: number;
+  readonly killGraceMs?: number;
+  readonly abortError: string;
+  readonly timeoutError: string;
+  readonly maxBufferError?: string;
+  readonly exitError: (stderr: string, code: number | null, signal: NodeJS.Signals | null) => string;
+}
+
+export interface BoundedProcessResult {
+  readonly ok: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly durationMs: number;
+  readonly bytes: number;
+  readonly error?: string;
+}
+
+export async function runBoundedProcess(options: BoundedProcessOptions): Promise<BoundedProcessResult> {
+  const start = performance.now();
+  let stdout = "";
+  let stderr = "";
+  let bytes = 0;
+  let error: string | undefined;
+  const child = spawn(options.file, [...options.args], {
+    cwd: options.cwd,
+    env: options.env ?? process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  return await new Promise<BoundedProcessResult>((resolve) => {
+    let settled = false;
+    let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+    const killGraceMs = Math.max(1, options.killGraceMs ?? 100);
+    const finish = (ok: boolean, finishError?: string) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({ ok, stdout, stderr, durationMs: performance.now() - start, bytes, error: finishError });
+    };
+    const kill = (message: string) => {
+      error = error ?? message;
+      child.kill("SIGTERM");
+      forceKillTimer ??= setTimeout(() => {
+        child.kill("SIGKILL");
+        finish(false, error);
+      }, killGraceMs);
+    };
+    const onAbort = () => kill(options.abortError);
+    const timeout = setTimeout(() => kill(options.timeoutError), options.timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timeout);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+
+    if (options.signal?.aborted) {
+      kill(options.abortError);
+    } else {
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+    }
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      bytes += chunk.length;
+      if (options.maxBufferBytes !== undefined && bytes > options.maxBufferBytes) {
+        kill(options.maxBufferError ?? `process output exceeded ${options.maxBufferBytes} bytes`);
+        return;
+      }
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", (spawnError) => finish(false, spawnError.message));
+    child.on("close", (code, signal) => {
+      if (error) {
+        finish(false, error);
+        return;
+      }
+      if (code === 0) {
+        finish(true);
+        return;
+      }
+      finish(false, options.exitError(stderr, code, signal));
+    });
+  });
+}

package/.pi/extensions/pi-workflow-engine/src/types.ts

@@ -1,5 +1,6 @@
 import type { Static, TSchema } from "typebox";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { WorkflowBudget } from "./budget.ts";
 import type { Pipeline } from "./concurrency.ts";
 import type { PerfSink, PerfSnapshot } from "./perf.ts";
 import type { WorkflowProgressSnapshot } from "./progress.ts";
@@ -23,11 +24,23 @@ export interface WorkflowRunStats {
   [key: string]: string | number;
 }
 
+export interface WorkflowRunMetadata {
+  readonly runId: string;
+  readonly resumedFromRunId?: string;
+  readonly journalPath: string;
+}
+
 export interface WorkflowRunOptions {
   inspect?: boolean;
   perf?: boolean;
   concurrency?: number;
   parallelSubmissionLimit?: number;
+  /** Output-token ceiling for the whole run. Omit for no limit (budget.total === null). */
+  budget?: number;
+  /** Internal/test override for the generated run id. Omit to generate a new id. */
+  runId?: string;
+  /** Replay completed agent results from this prior run id when prompt/options hashes still match. */
+  resumeFromRunId?: string;
   resultViewer?: "open" | "skip";
   /** Additional abort signal to compose with the host context signal. */
   signal?: AbortSignal;
@@ -39,6 +52,8 @@ export interface WorkflowRunOptions {
   onPerfSnapshot?: (snapshot: PerfSnapshot) => void;
   /** Called with the final workflow subagent usage snapshot. */
   onUsageSnapshot?: (snapshot: WorkflowUsageSnapshot) => void;
+  /** Called once run identity and journal paths are known. */
+  onRunMetadata?: (metadata: WorkflowRunMetadata) => void;
   /** Called with the live progress source while a workflow is running, then undefined when it ends. */
   onProgressSource?: (source: WorkflowProgressSource | undefined) => void;
   /** Called with the final completed progress snapshot after live workflow UI teardown. */
@@ -52,6 +67,14 @@ export interface WorkflowProgressSource {
 /** Options for a single `agent()` call. */
 export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
 
+export type AgentToolHint = "search";
+
+export interface IsolatedAgentResult<T> {
+  readonly result: T;
+  readonly patch: string;
+  readonly changed: boolean;
+}
+
 export type WorkflowProgressEvent =
   | { type: "counter"; key: string; label: string; value: number }
   | { type: "counter_delta"; key: string; label: string; delta: number }
@@ -77,8 +100,28 @@ export interface AgentOptions<S extends TSchema = TSchema> {
   model?: string;
   /** Reasoning effort for this agent. */
   thinkingLevel?: ThinkingLevel;
-  /** Allowlist of built-in tool names the agent may use (e.g. ["read", "bash"]). */
+  /**
+   * Stable identity hint for resume replay. Use this for repeated logical calls
+   * with identical prompts/options, e.g. `${stage}:${item.id}`.
+   */
+  cacheKey?: string;
+  /** Run this agent in a disposable git worktree and return its patch with the result. */
+  isolation?: "worktree";
+  /** Allowlist of concrete tool names the agent may use (e.g. ["read", "bash"]). */
   tools?: string[];
+  /**
+   * Dynamically include installed tools matching semantic categories. Currently
+   * "search" matches grep/find/code-search style tools such as ast-grep,
+   * mgrep, ffgrep, fffind, ripgrep wrappers, and pi's built-in grep/find/ls.
+   */
+  toolHints?: readonly AgentToolHint[];
+  /**
+   * Skill names to expose to this subagent. Subagents receive no skills by default.
+   * When omitted, clear prompt text such as `/skill:name`, `include skill name`, or
+   * `use the name skill` is treated as a natural-language opt-in. Pass [] to suppress
+   * prompt inference for prompts that mention skills only as subject matter.
+   */
+  skills?: readonly string[];
   /** typebox schema. When set, the agent is forced to return matching structured data. */
   schema?: S;
 }
@@ -88,6 +131,13 @@ export interface AgentOptions<S extends TSchema = TSchema> {
  * exports `meta` plus a default `async (api: WorkflowApi) => result`.
  */
 export interface WorkflowApi {
+  /** Run a schema subagent in a disposable worktree and return its structured result plus patch. */
+  agent<S extends TSchema>(
+    prompt: string,
+    opts: AgentOptions<S> & { schema: S; isolation: "worktree" },
+  ): Promise<IsolatedAgentResult<Static<S> | null>>;
+  /** Run a text subagent in a disposable worktree and return its final text plus patch. */
+  agent(prompt: string, opts: AgentOptions & { isolation: "worktree" }): Promise<IsolatedAgentResult<string>>;
   /** Run a subagent and return its validated structured output (null if it never produced one). */
   agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S> | null>;
   /** Run a subagent and return its final assistant text. */
@@ -99,9 +149,15 @@ export interface WorkflowApi {
    * a missing sub-workflow gracefully.
    */
   workflow(ref: WorkflowRef, args?: string): Promise<unknown>;
-  /** Run every thunk concurrently and wait for all (a barrier). */
-  parallel<T>(thunks: Array<() => Promise<T>>): Promise<T[]>;
-  /** Run each item through all stages independently — no barrier between stages. */
+  /**
+   * Run every thunk concurrently and wait for all (a barrier). Recoverable thunk
+   * failures become null slots; filter nulls before consuming survivors.
+   */
+  parallel<T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+  /**
+   * Run each item through all stages independently — no barrier between stages.
+   * A recoverable stage failure drops that item to null and skips its later stages.
+   */
   pipeline: Pipeline;
   /** Start a new phase; subsequent agents group under it in the progress tree. */
   phase(title: string): void;
@@ -113,6 +169,12 @@ export interface WorkflowApi {
   args: string;
   /** Working directory of the host session (typically the repo root). */
   cwd: string;
+  /**
+   * Token budget for the run. `budget.total` is the output-token ceiling (null when unset),
+   * `spent()`/`remaining()` are live. Guard loops with `while (budget.total && budget.remaining() > N)`;
+   * `agent()` throws `WorkflowBudgetExceededError` once the ceiling is reached.
+   */
+  budget: WorkflowBudget;
   /** Abort signal for the run, propagated from the host. */
   signal: AbortSignal | undefined;
 }

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-result-renderer.ts

@@ -19,6 +19,8 @@ export interface WorkflowResultEnvelope {
   completedAt: number;
   usage?: WorkflowUsageSnapshot;
   perf?: WorkflowPerfDetails;
+  runId?: string;
+  resumedFromRunId?: string;
 }
 
 export interface AdvisoryWorkflowResult extends AdvisoryReport {
@@ -61,27 +63,61 @@ export function isAdvisoryReport(value: unknown): value is AdvisoryWorkflowResul
   return true;
 }
 
-export function renderWorkflowResult(name: string, result: unknown, expanded: boolean, theme: Theme, usage?: unknown): Component {
+export interface WorkflowRunDisplayMetadata {
+  readonly runId?: string;
+  readonly resumedFromRunId?: string;
+}
+
+export interface WorkflowDetailLineInput {
+  readonly usage?: unknown;
+  readonly perf?: WorkflowPerfDetails;
+  readonly metadata?: WorkflowRunDisplayMetadata;
+}
+
+export function renderWorkflowResult(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): Component {
   const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
-  box.addChild(new Text(renderWorkflowResultText(name, result, expanded, theme, usage), 0, 0));
+  box.addChild(new Text(renderWorkflowResultText(name, result, expanded, theme, usage, metadata, perf), 0, 0));
   return box;
 }
 
-export function renderWorkflowResultText(name: string, result: unknown, expanded: boolean, theme: Theme, usage?: unknown): string {
+export function renderWorkflowResultText(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
   if (isAdvisoryReport(result)) {
-    return renderAdvisoryResult(name, result, expanded, theme, usage);
+    return renderAdvisoryResult(name, result, expanded, theme, usage, metadata, perf);
   }
-  return renderGenericWorkflowResult(name, result, expanded, theme, usage);
-}
-
-function renderAdvisoryResult(name: string, result: AdvisoryWorkflowResult, expanded: boolean, theme: Theme, usage?: unknown): string {
+  return renderGenericWorkflowResult(name, result, expanded, theme, usage, metadata, perf);
+}
+
+function renderAdvisoryResult(
+  name: string,
+  result: AdvisoryWorkflowResult,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
   const icon = theme.fg("success", "✓");
   const title = theme.fg("accent", theme.bold(`Workflow: ${name}`));
   const lines = [`${icon} ${title}`, theme.fg("muted", result.summary)];
   const stats = statsLine(result.stats, theme);
   if (stats) lines.push(stats);
-  const usageLine = formatWorkflowUsageLine(usage);
-  if (usageLine) lines.push(theme.fg("dim", usageLine));
+  pushWorkflowDetailLines(lines, theme, { usage, metadata, perf });
 
   if (result.findings.length === 0) {
     lines.push(theme.fg("success", "No findings."));
@@ -108,17 +144,49 @@ function renderNextSteps(nextSteps: string[], lines: string[], theme: Theme): vo
   }
 }
 
-function renderGenericWorkflowResult(name: string, result: unknown, expanded: boolean, theme: Theme, usage?: unknown): string {
+function renderGenericWorkflowResult(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
   const lines = [`${theme.fg("success", "✓")} ${theme.fg("accent", theme.bold(`Workflow: ${name}`))}`];
   const summary = extractSummary(result);
   if (summary) lines.push(theme.fg("muted", summary));
-  const usageLine = formatWorkflowUsageLine(usage);
-  if (usageLine) lines.push(theme.fg("dim", usageLine));
+  pushWorkflowDetailLines(lines, theme, { usage, metadata, perf });
   if (expanded) lines.push(theme.fg("dim", safeJson(result)));
   else if (!summary) lines.push(theme.fg("dim", "Result available in expanded view."));
   return lines.join("\n");
 }
 
+function pushWorkflowDetailLines(lines: string[], theme: Theme, input: WorkflowDetailLineInput): void {
+  for (const line of formatWorkflowDetailLines(input)) {
+    lines.push(theme.fg("dim", line));
+  }
+}
+
+export function formatWorkflowDetailLines(input: WorkflowDetailLineInput): string[] {
+  return [
+    formatWorkflowRunLine(input.metadata),
+    formatWorkflowUsageLine(input.usage),
+    formatWorkflowPerfLine(input.perf),
+  ].filter((line): line is string => line !== undefined);
+}
+
+export function formatWorkflowRunLine(metadata: WorkflowRunDisplayMetadata | undefined): string | undefined {
+  if (!metadata?.runId) return undefined;
+  return metadata.resumedFromRunId ? `Run: ${metadata.runId} (resumed from ${metadata.resumedFromRunId})` : `Run: ${metadata.runId}`;
+}
+
+export function formatWorkflowPerfLine(perf: WorkflowPerfDetails | undefined): string | undefined {
+  if (!perf) return undefined;
+  const parts = perf.aggregates.slice(0, 4).map((aggregate) => `${aggregate.name} ${Math.round(aggregate.total)}ms`);
+  return parts.length > 0 ? `Perf: ${parts.join(" · ")}` : "Perf: no samples";
+}
+
 function statsLine(stats: Record<string, string | number> | undefined, theme: Theme): string | undefined {
   if (!stats) return undefined;
   const ordered = ["files", "candidates", "dropped", "verified", "kept"];

package/.pi/extensions/pi-workflow-engine/src/workflow-advisory-utils.ts

@@ -1,4 +1,5 @@
 import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, type AdvisoryCandidate, type AdvisoryFinding, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
+import { compactResults } from "./concurrency.ts";
 import type { AgentOptions, WorkflowApi, WorkflowProgressEvent } from "./types.ts";
 
 export interface AdvisoryLens {
@@ -20,7 +21,11 @@ export interface LensVerificationPipelineResult<Verified> {
   refuted: number;
 }
 
-const DEFAULT_ADVISORY_TOOLS = ["read", "bash"];
+/** Default concrete read/inspect tools for advisory workflows. */
+export const DEFAULT_ADVISORY_TOOLS: NonNullable<AgentOptions["tools"]> = ["read", "bash", "grep", "find", "ls"];
+
+/** Dynamically include installed grep/find/search-like extension tools. */
+export const DEFAULT_ADVISORY_TOOL_HINTS: NonNullable<AgentOptions["toolHints"]> = ["search"];
 
 export type AdvisorySchedulingMode = "pipeline" | "finder-barrier";
 
@@ -29,6 +34,7 @@ export interface LensVerificationPipelineOptions<Lens extends AdvisoryLens, Veri
   lenses: readonly Lens[];
   perLens: number;
   tools?: AgentOptions["tools"];
+  toolHints?: AgentOptions["toolHints"];
   finderPhase?: string;
   verifierPhase?: string;
   schedulingMode?: AdvisorySchedulingMode;
@@ -60,6 +66,7 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
     lenses,
     perLens,
     tools = DEFAULT_ADVISORY_TOOLS,
+    toolHints = DEFAULT_ADVISORY_TOOL_HINTS,
     finderPhase = "Find",
     verifierPhase = "Verify",
     schedulingMode = "pipeline",
@@ -77,6 +84,7 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
       phase: finderPhase,
       label: `find:${lens.label}`,
       tools,
+      toolHints,
       thinkingLevel: "low",
       schema: AdvisoryCandidatesSchema,
     });
@@ -113,6 +121,7 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
       phase: verifierPhase,
       label: `verify:${location.file.split("/").pop() ?? location.file}`,
       tools,
+      toolHints,
       thinkingLevel: "low",
       schema: AdvisoryVerdictSchema,
     });
@@ -125,9 +134,9 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
 
   if (schedulingMode === "finder-barrier") {
     const found = await api.parallel(lenses.map((lens) => async () => findForLens(lens)));
-    const novel = found.flatMap(dedupeFound);
+    const novel = compactResults(found).flatMap(dedupeFound);
     const verdicts = await api.parallel(novel.map((entry) => async () => verifyCandidate(entry)));
-    return { verified: verdicts.filter((value): value is Verified => value !== null), rawCandidates, dropped, refuted };
+    return { verified: compactResults(verdicts), rawCandidates, dropped, refuted };
   }
 
   const perLensVerified = await api.pipeline(
@@ -136,11 +145,11 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
     async (found) => {
       const novel = dedupeFound(found);
       const verdicts = await api.parallel(novel.map((entry) => async () => verifyCandidate(entry)));
-      return verdicts.filter((value): value is Verified => value !== null);
+      return compactResults(verdicts);
     },
   );
 
-  return { verified: perLensVerified.flat(), rawCandidates, dropped, refuted };
+  return { verified: compactResults(perLensVerified).flat(), rawCandidates, dropped, refuted };
 }
 
 function candidatesNovelToRun(candidates: readonly AdvisoryCandidate[], seen: Set<string>): AdvisoryCandidate[] {

package/.pi/extensions/pi-workflow-engine/src/worktree.ts

@@ -0,0 +1,238 @@
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runBoundedProcess } from "./process-runner.ts";
+
+export interface WorktreeGitCommandOptions {
+  readonly cwd: string;
+  readonly args: readonly string[];
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxBufferBytes?: number;
+}
+
+export interface WorktreeGitCommandResult {
+  readonly ok: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly error?: string;
+}
+
+export interface WorktreeGitRunner {
+  runGit(options: WorktreeGitCommandOptions): Promise<WorktreeGitCommandResult>;
+}
+
+export interface WorktreeRef {
+  readonly path: string;
+}
+
+export interface WorktreeAddFailure {
+  readonly path: string;
+  readonly error: string;
+  readonly cleanup?: WorktreeGitCommandResult;
+}
+
+export interface GitWorktreeProbe {
+  readonly ok: boolean;
+  readonly inside: boolean;
+  readonly error?: string;
+}
+
+export interface WorktreeRemovalOutcome extends WorktreeGitCommandResult {
+  readonly path: string;
+}
+
+export interface WorktreePatch {
+  readonly patch: string;
+  readonly changed: boolean;
+}
+
+export interface WorktreeRegistryOptions {
+  readonly repoCwd: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly patchCapture?: WorktreePatchCapture;
+  readonly timeoutMs?: number;
+}
+
+export type WorktreePatchCapture = (options: {
+  readonly worktreePath: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}) => Promise<WorktreePatch | { readonly error: string }>;
+
+const DEFAULT_WORKTREE_TIMEOUT_MS = 30_000;
+const WORKTREE_DIFF_MAX_BYTES = 16 << 20;
+let pathCounter = 0;
+
+export class WorktreeRegistry {
+  private readonly paths = new Set<string>();
+  private readonly runner: WorktreeGitRunner;
+  private readonly patchCapture: WorktreePatchCapture;
+  private readonly timeoutMs: number;
+
+  constructor(private readonly repoCwd: string, options: Omit<WorktreeRegistryOptions, "repoCwd"> = {}) {
+    this.runner = options.runner ?? spawnGitRunner;
+    this.patchCapture = options.patchCapture ?? captureWorktreePatch;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
+  }
+
+  get size(): number {
+    return this.paths.size;
+  }
+
+  register(path: string): void {
+    this.paths.add(path);
+  }
+
+  async probe(signal?: AbortSignal): Promise<GitWorktreeProbe> {
+    return await isGitWorktree({ repoCwd: this.repoCwd, runner: this.runner, signal, timeoutMs: this.timeoutMs });
+  }
+
+  async add(signal?: AbortSignal): Promise<WorktreeRef | WorktreeAddFailure> {
+    const added = await addWorktree({ repoCwd: this.repoCwd, runner: this.runner, signal, timeoutMs: this.timeoutMs });
+    this.register(added.path);
+    if ("error" in added) {
+      const cleanup = await this.remove(added.path);
+      return { ...added, cleanup };
+    }
+    return added;
+  }
+
+  async capturePatch(path: string, signal?: AbortSignal): Promise<WorktreePatch | { readonly error: string }> {
+    return await this.patchCapture({ worktreePath: path, runner: this.runner, signal, timeoutMs: this.timeoutMs });
+  }
+
+  async remove(path: string): Promise<WorktreeGitCommandResult> {
+    const result = await removeWorktree({ repoCwd: this.repoCwd, path, runner: this.runner, timeoutMs: this.timeoutMs }).catch((error: unknown) => ({
+      ok: false,
+      stdout: "",
+      stderr: "",
+      error: formatError(error),
+    }));
+    if (result.ok) this.paths.delete(path);
+    return result;
+  }
+
+  async removeAll(): Promise<readonly WorktreeRemovalOutcome[]> {
+    return await Promise.all(
+      [...this.paths].map(async (path) => ({
+        path,
+        ...(await this.remove(path)),
+      })),
+    );
+  }
+}
+
+export function createWorktreePath(baseDir = tmpdir()): string {
+  pathCounter += 1;
+  return join(baseDir, `pi-workflow-${process.pid}-${pathCounter}-${randomUUID()}`);
+}
+
+export async function isGitWorktree(options: {
+  readonly repoCwd: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}): Promise<GitWorktreeProbe> {
+  const result = await (options.runner ?? spawnGitRunner)
+    .runGit({
+      cwd: options.repoCwd,
+      args: ["rev-parse", "--is-inside-work-tree"],
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+  if (!result.ok) return { ok: false, inside: false, error: result.error ?? (result.stderr.trim() || "git worktree probe failed") };
+  return { ok: true, inside: result.stdout.trim() === "true" };
+}
+
+export async function addWorktree(options: {
+  readonly repoCwd: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+  readonly baseDir?: string;
+}): Promise<WorktreeRef | WorktreeAddFailure> {
+  const path = createWorktreePath(options.baseDir);
+  const result = await (options.runner ?? spawnGitRunner)
+    .runGit({
+      cwd: options.repoCwd,
+      args: ["worktree", "add", "--detach", path, "HEAD"],
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+  if (!result.ok) return { path, error: result.error ?? (result.stderr.trim() || "git worktree add failed") };
+  return { path };
+}
+
+export async function removeWorktree(options: {
+  readonly repoCwd: string;
+  readonly path: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly timeoutMs?: number;
+}): Promise<WorktreeGitCommandResult> {
+  return await (options.runner ?? spawnGitRunner).runGit({
+    cwd: options.repoCwd,
+    args: ["worktree", "remove", "--force", options.path],
+    timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
+  });
+}
+
+export async function captureWorktreePatch(options: {
+  readonly worktreePath: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}): Promise<WorktreePatch | { readonly error: string }> {
+  const runner = options.runner ?? spawnGitRunner;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
+  const intentToAdd = await runner
+    .runGit({
+      cwd: options.worktreePath,
+      args: ["add", "-N", "."],
+      signal: options.signal,
+      timeoutMs,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+  if (!intentToAdd.ok) return { error: intentToAdd.error ?? (intentToAdd.stderr.trim() || "git add -N failed before patch capture") };
+
+  const diff = await runner
+    .runGit({
+      cwd: options.worktreePath,
+      args: ["diff", "--no-color", "HEAD"],
+      signal: options.signal,
+      timeoutMs,
+      maxBufferBytes: WORKTREE_DIFF_MAX_BYTES,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+  if (!diff.ok) return { error: diff.error ?? (diff.stderr.trim() || "worktree diff capture failed") };
+  return { patch: diff.stdout, changed: diff.stdout.trim().length > 0 };
+}
+
+export const spawnGitRunner: WorktreeGitRunner = {
+  async runGit(options) {
+    return await runGitCommand(options);
+  },
+};
+
+async function runGitCommand(options: WorktreeGitCommandOptions): Promise<WorktreeGitCommandResult> {
+  return await runBoundedProcess({
+    file: "git",
+    args: options.args,
+    cwd: options.cwd,
+    env: { ...process.env, GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" },
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+    maxBufferBytes: options.maxBufferBytes,
+    abortError: "git worktree command aborted",
+    timeoutError: `git worktree command timed out after ${options.timeoutMs}ms`,
+    maxBufferError: options.maxBufferBytes === undefined ? undefined : `git worktree command exceeded ${options.maxBufferBytes} bytes`,
+    exitError: (stderr, code, signal) => stderr.trim() || `git exited with code ${code ?? `signal ${signal ?? "unknown"}`}`,
+  });
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}