@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/runs/shared/workflow-policy.ts

@@ -1,125 +1,260 @@
-import type { DynamicParallelStep } from "../../shared/settings.ts";
-import type { ArtifactPaths, ChainOutputMap } from "../../shared/types.ts";
+import { errorMessage } from "../../shared/unknown.ts";
+import type { DynamicParallelStep } from "../../shared/types/workflow.ts";
+import type {
+  AcceptanceLedger,
+  ArtifactPaths,
+  ChainOutputMap,
+  ChainOutputMapEntry,
+  ReadonlyInput,
+} from "../../shared/types.ts";
 import { outputEntryFromResult } from "./chain-outputs.ts";
-import { collectDynamicResults, validateDynamicCollection, type DynamicCollectedResult, type DynamicMaterializedItem } from "./dynamic-fanout.ts";
-import { aggregateParallelOutputs, FAIL_FAST_REASON, mapConcurrent, type ParallelTaskResult } from "./parallel-utils.ts";
+import {
+  collectDynamicResults,
+  validateDynamicCollection,
+  type DynamicCollectedResult,
+  type DynamicMaterializedItem,
+} from "./dynamic-fanout.ts";
+import {
+  aggregateParallelOutputs,
+  FAIL_FAST_REASON,
+  mapConcurrent,
+  type ParallelTaskResult,
+} from "./parallel-utils.ts";
 
 export interface WorkflowOutcome extends ParallelTaskResult {
-	interrupted?: boolean;
-	detached?: boolean;
-	timedOut?: boolean;
-	acceptance?: import("../../shared/types.ts").AcceptanceLedger;
-	structuredOutput?: unknown;
-	artifactPaths?: ArtifactPaths;
-	savedOutputPath?: string;
+  interrupted?: boolean;
+  detached?: boolean;
+  timedOut?: boolean;
+  acceptance?: AcceptanceLedger;
+  structuredOutput?: unknown;
+  artifactPaths?: ArtifactPaths;
+  savedOutputPath?: string;
 }
-
-export type ParallelStopReason = "cancelled" | "interrupted" | "fail-fast" | "detached" | "timed-out";
-
-type ChildOutcome = Pick<WorkflowOutcome, "exitCode" | "interrupted" | "detached" | "timedOut" | "acceptance">;
+export type ParallelStopReason =
+  | "cancelled"
+  | "interrupted"
+  | "fail-fast"
+  | "detached"
+  | "timed-out";
+type ChildOutcome = ReadonlyInput<
+  Pick<WorkflowOutcome, "exitCode" | "interrupted" | "detached" | "timedOut" | "acceptance">
+>;
 type WorkflowStepStatus = "completed" | "failed" | "blocked" | "paused" | "detached" | "timed-out";
 
 export function workflowChildSucceeded(result: ChildOutcome): boolean {
-	return result.exitCode === 0 && !result.interrupted && !result.detached && !result.timedOut && result.acceptance?.status !== "blocked";
+  return (
+    result.exitCode === 0 &&
+    result.interrupted !== true &&
+    result.detached !== true &&
+    result.timedOut !== true &&
+    result.acceptance?.status !== "blocked"
+  );
+}
+
+function queuedStopReason(
+  signal: AbortSignal | undefined,
+  interruptSignal: AbortSignal | undefined,
+  stopped: ParallelStopReason | undefined,
+): ParallelStopReason | undefined {
+  if (signal?.aborted === true) {
+    return "cancelled";
+  }
+  return interruptSignal?.aborted === true ? "interrupted" : stopped;
+}
+
+function resultStopReason(result: ChildOutcome, failFast: boolean): ParallelStopReason | undefined {
+  if (result.detached === true) {
+    return "detached";
+  }
+  if (result.timedOut === true) {
+    return "timed-out";
+  }
+  if (
+    failFast &&
+    result.interrupted !== true &&
+    !childBlocked(result) &&
+    !workflowChildSucceeded(result)
+  ) {
+    return "fail-fast";
+  }
+  return undefined;
 }
 
 export async function runParallelTasks<T, R extends ChildOutcome>(input: {
-	tasks: T[];
-	concurrency: number;
-	failFast?: boolean;
-	signal?: AbortSignal;
-	interruptSignal?: AbortSignal;
-	runTask: (task: T, index: number, failFastSignal: AbortSignal) => Promise<R>;
-	stoppedTask: (task: T, index: number, reason: ParallelStopReason) => R;
+  readonly tasks: readonly ReadonlyInput<T>[];
+  readonly concurrency: number;
+  readonly failFast?: boolean;
+  readonly signal?: AbortSignal;
+  readonly interruptSignal?: AbortSignal;
+  readonly runTask: (
+    task: ReadonlyInput<T>,
+    index: number,
+    failFastSignal: AbortSignal,
+  ) => Promise<R>;
+  readonly stoppedTask: (task: ReadonlyInput<T>, index: number, reason: ParallelStopReason) => R;
 }): Promise<R[]> {
-	const failFast = new AbortController();
-	let stopped: ParallelStopReason | undefined;
-	return mapConcurrent(input.tasks, input.concurrency, async (task, index) => {
-		const reason = input.signal?.aborted ? "cancelled" : input.interruptSignal?.aborted ? "interrupted" : stopped;
-		if (reason) return input.stoppedTask(task, index, reason);
-		const result = await input.runTask(task, index, failFast.signal);
-		// A selected-child stop must not skip independent siblings; whole-group stops use interruptSignal.
-		if (result.detached) stopped ??= "detached";
-		else if (result.timedOut) stopped ??= "timed-out";
-		else if (input.failFast && !result.interrupted && !(result.exitCode === 0 && result.acceptance?.status === "blocked") && !workflowChildSucceeded(result)) {
-			stopped ??= "fail-fast";
-			failFast.abort(FAIL_FAST_REASON);
-		}
-		return result;
-	});
+  const failFast = new AbortController();
+  let stopped: ParallelStopReason | undefined;
+  return mapConcurrent(input.tasks, input.concurrency, async (task, index) => {
+    const reason = queuedStopReason(input.signal, input.interruptSignal, stopped);
+    if (reason !== undefined) {
+      return input.stoppedTask(task, index, reason);
+    }
+    const result = await input.runTask(task, index, failFast.signal);
+    // A selected-child stop must not skip independent siblings; whole-group stops use interruptSignal.
+    const nextStop = resultStopReason(result, input.failFast === true);
+    stopped ??= nextStop;
+    if (nextStop === "fail-fast") {
+      failFast.abort(FAIL_FAST_REASON);
+    }
+    return result;
+  });
+}
+
+function childBlocked(result: ChildOutcome): boolean {
+  return result.exitCode === 0 && result.acceptance?.status === "blocked";
+}
+interface StepInput {
+  readonly stepIndex: number;
+  readonly stepCount: number;
+  readonly results: readonly ReadonlyInput<WorkflowOutcome>[];
+  readonly outputNames?: readonly (string | undefined)[];
+  readonly previousOutput: string;
+  readonly parallel?: boolean;
+  readonly dynamic?: {
+    readonly step: ReadonlyInput<DynamicParallelStep>;
+    readonly items: readonly DynamicMaterializedItem[];
+  };
+}
+interface StepResult {
+  advance: boolean;
+  complete: boolean;
+  status: WorkflowStepStatus;
+  failedIndices: number[];
+  timedOutIndex: number;
+  interruptedIndex: number;
+  detachedIndex: number;
+  outputs: ChainOutputMap;
+  previousOutput: string;
+  collection?: DynamicCollectedResult[];
+  error?: string;
+}
+
+function summarizeStep(
+  results: readonly ReadonlyInput<WorkflowOutcome>[],
+): Pick<
+  StepResult,
+  "status" | "failedIndices" | "timedOutIndex" | "interruptedIndex" | "detachedIndex"
+> {
+  const timedOutIndex = results.findIndex((result) => result.timedOut === true);
+  const interruptedIndex = results.findIndex((result) => result.interrupted === true);
+  const detachedIndex = results.findIndex((result) => result.detached === true);
+  const failedIndices = results.flatMap((result, index) =>
+    !workflowChildSucceeded(result) &&
+    result.timedOut !== true &&
+    result.interrupted !== true &&
+    result.detached !== true &&
+    !childBlocked(result)
+      ? [index]
+      : [],
+  );
+  let status: WorkflowStepStatus = "completed";
+  if (failedIndices.length > 0) {
+    status = "failed";
+  } else if (timedOutIndex >= 0) {
+    status = "timed-out";
+  } else if (results.some(childBlocked)) {
+    status = "blocked";
+  } else if (interruptedIndex >= 0) {
+    status = "paused";
+  } else if (detachedIndex >= 0) {
+    status = "detached";
+  }
+  return { status, failedIndices, timedOutIndex, interruptedIndex, detachedIndex };
 }
 
-export function completeWorkflowStep(input: {
-	stepIndex: number;
-	stepCount: number;
-	results: WorkflowOutcome[];
-	outputNames?: Array<string | undefined>;
-	previousOutput: string;
-	parallel?: boolean;
-	dynamic?: { step: DynamicParallelStep; items: DynamicMaterializedItem[] };
-}): {
-	advance: boolean;
-	complete: boolean;
-	status: WorkflowStepStatus;
-	failedIndices: number[];
-	timedOutIndex: number;
-	interruptedIndex: number;
-	detachedIndex: number;
-	outputs: ChainOutputMap;
-	previousOutput: string;
-	collection?: DynamicCollectedResult[];
-	error?: string;
+function collectStepOutput(input: StepInput): {
+  outputs: ChainOutputMap;
+  previousOutput: string;
+  collection?: DynamicCollectedResult[];
 } {
-	const outputs: ChainOutputMap = {};
-	const failedIndices: number[] = [];
-	const timedOutIndex = input.results.findIndex((result) => result.timedOut);
-	const interruptedIndex = input.results.findIndex((result) => result.interrupted);
-	const detachedIndex = input.results.findIndex((result) => result.detached);
-	const blocked = input.results.some((result) => result.exitCode === 0 && result.acceptance?.status === "blocked");
-	for (const [index, result] of input.results.entries()) {
-		if (workflowChildSucceeded(result)) {
-			const name = input.outputNames?.[index];
-			if (name) outputs[name] = outputEntryFromResult(result, input.stepIndex);
-		} else if (!result.timedOut && !result.interrupted && !result.detached && !(result.exitCode === 0 && result.acceptance?.status === "blocked")) {
-			failedIndices.push(index);
-		}
-	}
-	let status: WorkflowStepStatus = failedIndices.length > 0 ? "failed"
-		: timedOutIndex >= 0 ? "timed-out"
-		: blocked ? "blocked"
-		: interruptedIndex >= 0 ? "paused"
-		: detachedIndex >= 0 ? "detached" : "completed";
-	let error: string | undefined;
-	let collection: DynamicCollectedResult[] | undefined;
-	let previousOutput = input.previousOutput;
-	if (status === "completed" && input.dynamic) {
-		const { step, items } = input.dynamic;
-		try {
-			if (items.length !== input.results.length) throw new Error("Dynamic fanout did not complete every child.");
-			collection = collectDynamicResults(step, items, input.results);
-			validateDynamicCollection(step.collect.outputSchema, collection);
-			outputs[step.collect.as] = { text: JSON.stringify(collection), structured: collection, agent: step.parallel.agent, stepIndex: input.stepIndex };
-			previousOutput = items.length === 0 ? "Dynamic fanout produced 0 results." : aggregateParallelOutputs(input.results,
-				(index, agent) => `=== Dynamic Item ${index + 1} (${agent}, key ${items[index]?.key ?? index}) ===`);
-		} catch (cause) {
-			error = cause instanceof Error ? cause.message : String(cause);
-			status = "failed";
-		}
-	} else if (status === "completed") {
-		previousOutput = input.parallel ? aggregateParallelOutputs(input.results) : input.results[0]?.output ?? input.previousOutput;
-	}
-	const advance = status === "completed";
-	return {
-		advance,
-		complete: advance && input.stepIndex + 1 === input.stepCount,
-		status,
-		failedIndices,
-		timedOutIndex,
-		interruptedIndex,
-		detachedIndex,
-		outputs,
-		previousOutput,
-		collection,
-		error,
-	};
+  if (!input.dynamic) {
+    return {
+      outputs: {},
+      previousOutput:
+        input.parallel === true
+          ? aggregateParallelOutputs(input.results)
+          : (input.results[0]?.output ?? input.previousOutput),
+    };
+  }
+  const { step, items } = input.dynamic;
+  if (items.length !== input.results.length) {
+    throw new Error("Dynamic fanout did not complete every child.");
+  }
+  const collection = collectDynamicResults(step, items, input.results);
+  validateDynamicCollection(step.collect.outputSchema, collection);
+  const outputs: ChainOutputMap = {
+    [step.collect.as]: {
+      text: JSON.stringify(collection),
+      structured: collection,
+      agent: step.parallel.agent,
+      stepIndex: input.stepIndex,
+    },
+  };
+  const previousOutput =
+    items.length === 0
+      ? "Dynamic fanout produced 0 results."
+      : aggregateParallelOutputs(
+          input.results,
+          (index, agent) =>
+            `=== Dynamic Item ${index + 1} (${agent}, key ${items[index]?.key ?? index}) ===`,
+        );
+  return { outputs, previousOutput, collection };
+}
+
+function successfulNamedOutputs(input: StepInput): Record<string, ChainOutputMapEntry> {
+  const outputs: Record<string, ChainOutputMapEntry> = {};
+  for (const [index, result] of input.results.entries()) {
+    const name = input.outputNames?.[index];
+    if (workflowChildSucceeded(result) && name !== undefined && name.length > 0) {
+      Object.defineProperty(outputs, name, {
+        value: outputEntryFromResult(result, input.stepIndex),
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+    }
+  }
+  return outputs;
+}
+
+export function completeWorkflowStep(input: StepInput): StepResult {
+  const summary = summarizeStep(input.results);
+  let outputs = successfulNamedOutputs(input);
+  let status = summary.status;
+  let previousOutput = input.previousOutput;
+  let collection: DynamicCollectedResult[] | undefined;
+  let error: string | undefined;
+  if (status === "completed") {
+    try {
+      const collected = collectStepOutput(input);
+      outputs = { ...outputs, ...collected.outputs };
+      previousOutput = collected.previousOutput;
+      collection = collected.collection;
+    } catch (cause) {
+      error = errorMessage(cause);
+      status = "failed";
+    }
+  }
+  const advance = status === "completed";
+  return {
+    ...summary,
+    status,
+    advance,
+    complete: advance && input.stepIndex + 1 === input.stepCount,
+    outputs,
+    previousOutput,
+    collection,
+    error,
+  };
 }

package/src/runs/shared/worktree-contract.ts

@@ -0,0 +1,29 @@
+export interface WorktreeInfo {
+  readonly path: string;
+  readonly agentCwd: string;
+  readonly branch: string;
+  readonly index: number;
+  readonly syntheticPaths: readonly string[];
+}
+
+/** The run owns these resources; capture failure can forbid their cleanup. */
+export interface WorktreeSetup {
+  readonly cwd: string;
+  readonly worktrees: readonly WorktreeInfo[];
+  readonly baseCommit: string;
+  preserveOnCleanup?: boolean;
+  preservationReason?: string;
+}
+
+export interface WorktreeDiff {
+  readonly index: number;
+  readonly agent: string;
+  readonly branch: string;
+  readonly diffStat: string;
+  readonly filesChanged: number;
+  readonly insertions: number;
+  readonly deletions: number;
+  readonly patchPath: string;
+  readonly worktreePath?: string;
+  readonly captureError?: string;
+}

package/src/runs/shared/worktree-hook.ts

@@ -0,0 +1,181 @@
+import { errorMessage, isRecord, isUnknownArray } from "../../shared/unknown.ts";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { runSetupCommand } from "./worktree-process.ts";
+
+export const DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS = 30_000;
+export interface WorktreeSetupHookConfig {
+  readonly hookPath: string;
+  readonly timeoutMs?: number;
+}
+export interface ResolvedWorktreeSetupHook {
+  readonly hookPath: string;
+  readonly timeoutMs: number;
+}
+export interface WorktreeSetupHookInput {
+  readonly version: 1;
+  readonly repoRoot: string;
+  readonly worktreePath: string;
+  readonly agentCwd: string;
+  readonly branch: string;
+  readonly index: number;
+  readonly runId: string;
+  readonly baseCommit: string;
+  readonly agent?: string;
+}
+
+function parseHookTimeout(timeoutMs: number | undefined): number {
+  if (timeoutMs === undefined) {
+    return DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS;
+  }
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("worktree setup hook timeout must be an integer greater than 0");
+  }
+  return timeoutMs;
+}
+
+export function resolveWorktreeSetupHook(
+  repoRoot: string,
+  config: WorktreeSetupHookConfig | undefined,
+): ResolvedWorktreeSetupHook | undefined {
+  if (!config) {
+    return undefined;
+  }
+  const hookPath = config.hookPath.trim();
+  if (hookPath.length === 0) {
+    throw new Error("worktree setup hook path cannot be empty");
+  }
+  const expandedHookPath = hookPath.startsWith("~/")
+    ? path.join(os.homedir(), hookPath.slice(2))
+    : hookPath;
+  let resolvedPath: string;
+  if (path.isAbsolute(expandedHookPath)) {
+    resolvedPath = expandedHookPath;
+  } else if (expandedHookPath.includes("/") || expandedHookPath.includes("\\")) {
+    resolvedPath = path.resolve(repoRoot, expandedHookPath);
+  } else {
+    throw new Error("worktree setup hook must be an absolute path or a repo-relative path");
+  }
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`worktree setup hook not found: ${resolvedPath}`);
+  }
+  if (fs.statSync(resolvedPath).isDirectory()) {
+    throw new Error(`worktree setup hook must be a file, got directory: ${resolvedPath}`);
+  }
+  return { hookPath: resolvedPath, timeoutMs: parseHookTimeout(config.timeoutMs) };
+}
+
+function normalizeSyntheticPath(worktreePath: string, rawPath: string): string {
+  const trimmed = rawPath.trim();
+  if (trimmed.length === 0) {
+    throw new Error("synthetic path cannot be empty");
+  }
+  if (path.isAbsolute(trimmed)) {
+    throw new Error(`synthetic path must be relative: ${rawPath}`);
+  }
+  const relative = path.relative(worktreePath, path.resolve(worktreePath, trimmed));
+  if (relative.length === 0 || relative === ".") {
+    throw new Error(`synthetic path cannot target the worktree root: ${rawPath}`);
+  }
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`synthetic path escapes the worktree root: ${rawPath}`);
+  }
+  return path.normalize(relative);
+}
+
+function requirePathStrings(paths: unknown): readonly string[] {
+  if (!isUnknownArray(paths)) {
+    throw new Error(
+      "worktree setup hook output field 'syntheticPaths' must be an array of relative paths",
+    );
+  }
+  const result: string[] = [];
+  for (const candidate of paths) {
+    if (typeof candidate !== "string") {
+      throw new Error(
+        "worktree setup hook output field 'syntheticPaths' must contain only strings",
+      );
+    }
+    result.push(candidate);
+  }
+  return result;
+}
+
+function parseSyntheticPaths(rawStdout: string): readonly string[] {
+  const trimmed = rawStdout.trim();
+  if (trimmed.length === 0) {
+    throw new Error("worktree setup hook returned empty stdout; expected JSON object");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (error) {
+    const message = errorMessage(error);
+    throw new Error(`worktree setup hook returned invalid JSON: ${message}`, { cause: error });
+  }
+  if (!isRecord(parsed)) {
+    throw new Error("worktree setup hook stdout must be a JSON object");
+  }
+  if (!("syntheticPaths" in parsed) || parsed.syntheticPaths === undefined) {
+    return [];
+  }
+  return requirePathStrings(parsed.syntheticPaths);
+}
+
+/** Validates hook-declared scratch paths against Git before granting cleanup authority. */
+async function validateSyntheticPaths(
+  input: WorktreeSetupHookInput,
+  paths: readonly string[],
+  signal?: AbortSignal,
+): Promise<string[]> {
+  const uniquePaths = new Set<string>();
+  for (const candidate of paths) {
+    const normalizedPath = normalizeSyntheticPath(input.worktreePath, candidate);
+    // Keep Git queries ordered and stop before granting authority to another path on cancellation.
+    // oxlint-disable-next-line no-await-in-loop
+    const result = await runSetupCommand({
+      command: "git",
+      args: ["-C", input.worktreePath, "ls-files", "--", normalizedPath],
+      cwd: input.worktreePath,
+      signal,
+    });
+    if (result.status === 0 && result.stdout.trim().length > 0) {
+      throw new Error(
+        `worktree setup hook cannot mark tracked paths as synthetic: ${normalizedPath}`,
+      );
+    }
+    uniquePaths.add(normalizedPath);
+  }
+  return [...uniquePaths];
+}
+
+export async function runWorktreeSetupHook(
+  hook: ResolvedWorktreeSetupHook,
+  input: WorktreeSetupHookInput,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  let result;
+  try {
+    result = await runSetupCommand({
+      command: hook.hookPath,
+      args: [],
+      cwd: input.worktreePath,
+      signal,
+      input: JSON.stringify(input),
+      timeoutMs: hook.timeoutMs,
+    });
+  } catch (error) {
+    signal?.throwIfAborted();
+    const message = errorMessage(error);
+    throw new Error(`worktree setup hook failed: ${message}`, { cause: error });
+  }
+  if (result.status !== 0) {
+    const details =
+      [result.stderr.trim(), result.stdout.trim()].find((text) => text.length > 0) ?? "no output";
+    throw new Error(
+      `worktree setup hook failed with exit code ${String(result.status)}: ${details}`,
+    );
+  }
+  return validateSyntheticPaths(input, parseSyntheticPaths(result.stdout), signal);
+}

package/src/runs/shared/worktree-location.ts

@@ -0,0 +1,61 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { TEMP_ROOT_DIR } from "../../shared/types.ts";
+import { runGit, runGitChecked } from "./worktree-process.ts";
+
+interface WorktreeTaskCwdConflict {
+  readonly index: number;
+  readonly agent: string;
+  readonly cwd: string;
+}
+function normalizeComparableCwd(cwd: string): string {
+  const resolved = path.resolve(cwd);
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  } // Missing paths are still compared as absolute paths.
+}
+
+export function findWorktreeTaskCwdConflict(
+  tasks: readonly { readonly agent: string; readonly cwd?: string }[],
+  sharedCwd: string,
+): WorktreeTaskCwdConflict | undefined {
+  const normalizedSharedCwd = normalizeComparableCwd(sharedCwd);
+  for (const [index, task] of tasks.entries()) {
+    if (task.cwd === undefined || task.cwd.length === 0) {
+      continue;
+    }
+    const taskCwd = path.isAbsolute(task.cwd) ? task.cwd : path.resolve(sharedCwd, task.cwd);
+    if (normalizeComparableCwd(taskCwd) === normalizedSharedCwd) {
+      continue;
+    }
+    return { index, agent: task.agent, cwd: task.cwd };
+  }
+  return undefined;
+}
+
+export function formatWorktreeTaskCwdConflict(
+  conflict: WorktreeTaskCwdConflict,
+  sharedCwd: string,
+): string {
+  return `worktree isolation uses the shared cwd (${sharedCwd}); task ${conflict.index + 1} (${conflict.agent}) sets cwd to ${conflict.cwd}. Remove task-level cwd overrides or disable worktree.`;
+}
+export function buildWorktreeBranch(runId: string, index: number): string {
+  return `pi-parallel-${runId}-${index}`;
+}
+export function buildWorktreePath(runId: string, index: number): string {
+  return path.join(TEMP_ROOT_DIR, "worktrees", `pi-worktree-${runId}-${index}`);
+}
+
+export function resolveExpectedWorktreeAgentCwd(cwd: string, runId: string, index: number): string {
+  const repoCheck = runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (repoCheck.status !== 0 || repoCheck.stdout.trim() !== "true") {
+    throw new Error("worktree isolation requires a git repository");
+  }
+  const rawPrefix = runGitChecked(cwd, ["rev-parse", "--show-prefix"]).trim();
+  const normalized = rawPrefix.length > 0 ? path.normalize(rawPrefix.replace(/[\\/]+$/, "")) : "";
+  const cwdRelative = normalized === "." ? "" : normalized;
+  const worktreePath = buildWorktreePath(runId, index);
+  return cwdRelative.length > 0 ? path.join(worktreePath, cwdRelative) : worktreePath;
+}

package/src/runs/shared/worktree-preservation.ts

@@ -0,0 +1,10 @@
+import type { WorktreeSetup } from "./worktree-contract.ts";
+
+/** Resource owner mutation: failed patch capture must prohibit destructive cleanup. */
+export function markWorktreesForPreservation(setup: WorktreeSetup, reason: string): void {
+  setup.preserveOnCleanup = true;
+  setup.preservationReason =
+    (setup.preservationReason ?? "").length > 0
+      ? `${setup.preservationReason ?? ""}; ${reason}`
+      : reason;
+}