pi-workflow-engine 0.10.2 → 0.11.0

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

@@ -0,0 +1,121 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedWorkflowRunOptions } from "./options.ts";
+import type { PerfAggregate, PerfSink, PerfSnapshot } from "./perf.ts";
+import type { WorkflowProgressSnapshot } from "./progress.ts";
+import type {
+  LoadedWorkflow,
+  WorkflowProgressSource,
+  WorkflowRef,
+  WorkflowRunMetadata,
+} from "./types.ts";
+import type { WorkflowUsageSnapshot } from "./usage.ts";
+
+export interface WorkflowPerfDetails {
+  readonly enabled: boolean;
+  readonly startedAt: number;
+  readonly aggregates: readonly PerfAggregate[];
+}
+
+export interface WorkflowResultEnvelope {
+  readonly name: string;
+  readonly result: unknown;
+  readonly completedAt: number;
+  readonly usage?: WorkflowUsageSnapshot;
+  readonly perf?: WorkflowPerfDetails;
+  readonly runId?: string;
+  readonly resumedFromRunId?: string;
+}
+
+export type ResolvedWorkflowRunner = (
+  ctx: ExtensionContext,
+  mod: LoadedWorkflow,
+  args: string,
+  options: ResolvedWorkflowRunOptions,
+) => Promise<unknown>;
+
+export interface WorkflowExecutionInput {
+  readonly ctx: ExtensionContext;
+  readonly name: string;
+  readonly mod: LoadedWorkflow;
+  readonly args: string;
+  readonly options: ResolvedWorkflowRunOptions;
+  readonly perfRecorder?: PerfSink;
+  readonly runResolvedWorkflow: ResolvedWorkflowRunner;
+  readonly resolveWorkflow: (ref: WorkflowRef) => Promise<LoadedWorkflow>;
+  readonly onProgressSource?: (source: WorkflowProgressSource | undefined) => void | Promise<void>;
+  readonly onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void | Promise<void>;
+}
+
+export interface WorkflowExecution {
+  readonly metadata?: WorkflowRunMetadata;
+  readonly envelope: WorkflowResultEnvelope;
+}
+
+/** Shared command/tool execution path. The engine remains lazy-loaded by the caller. */
+export async function executeWorkflowInvocation(input: WorkflowExecutionInput): Promise<WorkflowExecution> {
+  let perfSnapshot: PerfSnapshot | undefined;
+  let usageSnapshot: WorkflowUsageSnapshot | undefined;
+  let runMetadata: WorkflowRunMetadata | undefined;
+  const { options } = input;
+  const runOptions: ResolvedWorkflowRunOptions = {
+    ...options,
+    perfRecorder: input.perfRecorder,
+    resolveWorkflow: input.resolveWorkflow,
+    onProgressSource(source) {
+      return notifyLifecycleObservers(
+        () => input.onProgressSource?.(source),
+        () => options.onProgressSource?.(source),
+      );
+    },
+    onPerfSnapshot(snapshot) {
+      perfSnapshot = snapshot;
+      return notifyLifecycleObservers(() => options.onPerfSnapshot?.(snapshot));
+    },
+    onUsageSnapshot(snapshot) {
+      usageSnapshot = snapshot;
+      return notifyLifecycleObservers(() => options.onUsageSnapshot?.(snapshot));
+    },
+    onRunMetadata(metadata) {
+      runMetadata = metadata;
+      return notifyLifecycleObservers(() => options.onRunMetadata?.(metadata));
+    },
+    onProgressSnapshot(snapshot) {
+      return notifyLifecycleObservers(
+        () => input.onProgressSnapshot?.(snapshot),
+        () => options.onProgressSnapshot?.(snapshot),
+      );
+    },
+  };
+  const result = await input.runResolvedWorkflow(input.ctx, input.mod, input.args, runOptions);
+  const perf = compactPerfSnapshot(perfSnapshot);
+  return {
+    metadata: runMetadata,
+    envelope: {
+      name: input.name,
+      result,
+      completedAt: Date.now(),
+      usage: usageSnapshot,
+      perf,
+      runId: runMetadata?.runId,
+      resumedFromRunId: runMetadata?.resumedFromRunId,
+    },
+  };
+}
+
+function compactPerfSnapshot(snapshot: PerfSnapshot | undefined): WorkflowPerfDetails | undefined {
+  if (!snapshot?.enabled) return undefined;
+  return { enabled: true, startedAt: snapshot.startedAt, aggregates: snapshot.aggregates };
+}
+
+async function notifyLifecycleObservers(...observers: ReadonlyArray<() => void | Promise<void>>): Promise<void> {
+  const failures: unknown[] = [];
+  for (const observer of observers) {
+    try {
+      await observer();
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) throw new AggregateError(failures, "Workflow lifecycle observers failed");
+}

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

@@ -1,4 +1,10 @@
-import type { WorkflowMeta, WorkflowModule } from "./types.ts";
+import type {
+  LoadedWorkflow,
+  WorkflowMeta,
+  WorkflowModule,
+  WorkflowSourceIdentity,
+} from "./types.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
 
 type WorkflowMetaCandidate = {
   readonly name?: unknown;
@@ -30,6 +36,18 @@ export function parseWorkflowModule(value: unknown): { module: WorkflowModule }
   return { module: { meta: parsedMeta.meta, default: candidate.default } };
 }
 
+/** Attach engine-owned source provenance after an authored module has been validated. */
+export function loadWorkflow(
+  module: WorkflowModule,
+  source: WorkflowSourceIdentity,
+  isolatedWorktreeBaseline?: WorktreeBaseline,
+): LoadedWorkflow {
+  const loaded = { meta: module.meta, default: module.default, source };
+  return isolatedWorktreeBaseline === undefined
+    ? loaded
+    : { ...loaded, isolatedWorktreeBaseline };
+}
+
 function parseWorkflowMetaObject(meta: WorkflowMetaCandidate): { meta: WorkflowMeta } | { reason: string } {
   if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
 

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

@@ -1,8 +1,9 @@
-import type { WorkflowModule } from "./types.ts";
+import { fileURLToPath } from "node:url";
 import * as codeReview from "../workflows/code-review.ts";
 import * as refactorScout from "../workflows/refactor-scout.ts";
 import * as diagnose from "../workflows/diagnose.ts";
 import * as perfReview from "../workflows/perf-review.ts";
+import type { WorkflowModule } from "./types.ts";
 
 /**
  * Workflows statically imported by the extension. These are loaded through pi's own
@@ -18,6 +19,30 @@ import * as perfReview from "../workflows/perf-review.ts";
  * dynamically imported built-ins. Startup optimizations should happen at the extension
  * entrypoint/discovery boundary first.
  */
-export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, refactorScout, diagnose, perfReview];
-export const BUILTIN_WORKFLOW_FILES = new Set(["code-review.ts", "refactor-scout.ts", "diagnose.ts", "perf-review.ts"]);
+export const BUILTIN_SOURCE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+export interface BuiltinWorkflowDefinition {
+  readonly module: WorkflowModule;
+  readonly filename: string;
+  readonly path: string;
+  readonly root: string;
+}
+
+export const BUILTIN_WORKFLOW_DEFINITIONS: readonly BuiltinWorkflowDefinition[] = [
+  defineBuiltinWorkflow(codeReview, "code-review.ts"),
+  defineBuiltinWorkflow(refactorScout, "refactor-scout.ts"),
+  defineBuiltinWorkflow(diagnose, "diagnose.ts"),
+  defineBuiltinWorkflow(perfReview, "perf-review.ts"),
+];
+export const BUILTIN_WORKFLOWS = BUILTIN_WORKFLOW_DEFINITIONS.map(({ module }) => module);
+export const BUILTIN_WORKFLOW_FILES = new Set(BUILTIN_WORKFLOW_DEFINITIONS.map(({ filename }) => filename));
 export const BUILTIN_WORKFLOW_NAMES = BUILTIN_WORKFLOWS.map((mod) => mod.meta.name);
+
+function defineBuiltinWorkflow(module: WorkflowModule, filename: string): BuiltinWorkflowDefinition {
+  return {
+    module: { meta: module.meta, default: module.default },
+    filename,
+    path: fileURLToPath(new URL(`../workflows/${filename}`, import.meta.url)),
+    root: BUILTIN_SOURCE_ROOT,
+  };
+}

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

@@ -1,12 +1,15 @@
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
-import { cp, mkdir, rm } from "node:fs/promises";
-import { join, resolve, sep } from "node:path";
+import { cp, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { runBoundedProcess } from "./process-runner.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 
 export interface WorktreeGitCommandOptions {
   readonly cwd: string;
   readonly args: readonly string[];
+  readonly env?: NodeJS.ProcessEnv;
+  readonly stdin?: string;
   readonly signal?: AbortSignal;
   readonly timeoutMs: number;
   readonly maxBufferBytes?: number;
@@ -25,9 +28,17 @@ export interface WorktreeGitRunner {
 
 export interface WorktreeRef {
   readonly path: string;
+  /** Exact post-setup commit used as the immutable base for every result patch. */
+  readonly baselineOid: string;
   readonly snapshot?: boolean;
 }
 
+/** Immutable commit plus an optional patch used to reconstruct a reviewed snapshot. */
+export interface WorktreeBaseline {
+  readonly ref: string;
+  readonly patch?: string;
+}
+
 export interface WorktreeAddFailure {
   readonly path: string;
   readonly error: string;
@@ -45,6 +56,21 @@ export interface WorktreeRemovalOutcome extends WorktreeGitCommandResult {
   readonly path: string;
 }
 
+export class WorktreeCleanupError extends AggregateError {
+  readonly outcomes: readonly WorktreeRemovalOutcome[];
+
+  constructor(outcomes: readonly WorktreeRemovalOutcome[]) {
+    const failures = outcomes.filter((outcome) => !outcome.ok);
+    const details = failures.map((failure) => `${failure.path} (${worktreeRemovalError(failure)})`);
+    super(
+      failures.map((failure) => new Error(`Failed to remove isolated worktree ${failure.path}: ${worktreeRemovalError(failure)}`)),
+      `Failed to remove ${failures.length} isolated worktree${failures.length === 1 ? "" : "s"}: ${details.join(", ")}`,
+    );
+    this.name = "WorktreeCleanupError";
+    this.outcomes = outcomes;
+  }
+}
+
 export interface WorktreePatch {
   readonly patch: string;
   readonly changed: boolean;
@@ -59,6 +85,7 @@ export interface WorktreeRegistryOptions {
 
 export type WorktreePatchCapture = (options: {
   readonly worktreePath: string;
+  readonly baselineOid: string;
   readonly runner?: WorktreeGitRunner;
   readonly signal?: AbortSignal;
   readonly timeoutMs?: number;
@@ -66,11 +93,20 @@ export type WorktreePatchCapture = (options: {
 
 const DEFAULT_WORKTREE_TIMEOUT_MS = 30_000;
 const WORKTREE_DIFF_MAX_BYTES = 16 << 20;
+const SYNTHETIC_COMMIT_ENV: NodeJS.ProcessEnv = {
+  GIT_AUTHOR_NAME: "pi-workflow",
+  GIT_AUTHOR_EMAIL: "pi-workflow@example.invalid",
+  GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z",
+  GIT_COMMITTER_NAME: "pi-workflow",
+  GIT_COMMITTER_EMAIL: "pi-workflow@example.invalid",
+  GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z",
+};
 let pathCounter = 0;
 
 export class WorktreeRegistry {
   private readonly paths = new Set<string>();
   private readonly snapshots = new Set<string>();
+  private readonly removals = new Map<string, Promise<WorktreeGitCommandResult>>();
   private readonly runner: WorktreeGitRunner;
   private readonly patchCapture: WorktreePatchCapture;
   private readonly timeoutMs: number;
@@ -93,8 +129,8 @@ export class WorktreeRegistry {
     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 });
+  async add(signal?: AbortSignal, baseline?: WorktreeBaseline): Promise<WorktreeRef | WorktreeAddFailure> {
+    const added = await addWorktree({ repoCwd: this.repoCwd, runner: this.runner, signal, timeoutMs: this.timeoutMs, baseline });
     this.register(added.path);
     if (added.snapshot === true) this.snapshots.add(added.path);
     if ("error" in added) {
@@ -104,16 +140,62 @@ export class WorktreeRegistry {
     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 capturePatch(
+    path: string,
+    baselineOid: string,
+    signal?: AbortSignal,
+  ): Promise<WorktreePatch | { readonly error: string }> {
+    return await this.patchCapture({
+      worktreePath: path,
+      baselineOid,
+      runner: this.runner,
+      signal,
+      timeoutMs: this.timeoutMs,
+    });
+  }
+
+  async validatePatch(path: string, candidate: WorktreePatch, signal?: AbortSignal): Promise<WorktreeGitCommandResult> {
+    return await validateWorktreePatch({
+      worktreePath: path,
+      candidate,
+      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, snapshot: this.snapshots.has(path) }).catch((error: unknown) => ({
+    const pending = this.removals.get(path);
+    if (pending) return await pending;
+
+    const removal = this.removeOnce(path).finally(() => this.removals.delete(path));
+    this.removals.set(path, removal);
+    return await removal;
+  }
+
+  async removeAll(): Promise<readonly WorktreeRemovalOutcome[]> {
+    const outcomes = await Promise.all(
+      [...this.paths].map(async (path) => ({
+        path,
+        ...(await this.remove(path)),
+      })),
+    );
+    if (outcomes.some((outcome) => !outcome.ok)) throw new WorktreeCleanupError(outcomes);
+    return outcomes;
+  }
+
+  private async removeOnce(path: string): Promise<WorktreeGitCommandResult> {
+    const result = await removeWorktree({
+      repoCwd: this.repoCwd,
+      path,
+      runner: this.runner,
+      timeoutMs: this.timeoutMs,
+      snapshot: this.snapshots.has(path),
+    }).catch((error: unknown) => ({
       ok: false,
       stdout: "",
       stderr: "",
-      error: formatError(error),
+      error: unknownErrorMessage(error),
     }));
     if (result.ok) {
       this.paths.delete(path);
@@ -121,15 +203,6 @@ export class WorktreeRegistry {
     }
     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 {
@@ -150,7 +223,7 @@ export async function isGitWorktree(options: {
       signal: options.signal,
       timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(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" };
 }
@@ -161,26 +234,101 @@ export async function addWorktree(options: {
   readonly signal?: AbortSignal;
   readonly timeoutMs?: number;
   readonly baseDir?: string;
+  readonly baseline?: WorktreeBaseline;
 }): Promise<WorktreeRef | WorktreeAddFailure> {
   const path = createWorktreePath(options.baseDir);
-  const result = await (options.runner ?? spawnGitRunner)
+  const ref = options.baseline?.ref ?? "HEAD";
+  const runner = options.runner ?? spawnGitRunner;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
+  const result = await runner
     .runGit({
       cwd: options.repoCwd,
-      args: ["worktree", "add", "--detach", path, "HEAD"],
+      args: ["worktree", "add", "--detach", path, ref],
       signal: options.signal,
-      timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
+      timeoutMs,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
-  if (result.ok) return { path };
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
+  if (result.ok) {
+    const patch = options.baseline?.patch;
+    if (patch !== undefined && patch.trim().length > 0) {
+      const prepared = await prepareWorktreeBaseline({
+        path,
+        patch,
+        runner,
+        signal: options.signal,
+        timeoutMs,
+      }).catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
+      if (!prepared.ok) return { path, error: prepared.error ?? (prepared.stderr.trim() || "failed to prepare worktree baseline") };
+    }
+    return await finalizeWorktreeRef({ path, runner, signal: options.signal, timeoutMs });
+  }
 
   const message = result.error ?? (result.stderr.trim() || "git worktree add failed");
   if (!isInvalidHeadError(message)) return { path, error: message };
 
   const snapshotError = await createUnbornRepoSnapshot({ repoCwd: options.repoCwd, path, timeoutMs: options.timeoutMs, signal: options.signal })
     .then(() => undefined)
-    .catch((error: unknown) => formatError(error));
+    .catch((error: unknown) => unknownErrorMessage(error));
   if (snapshotError !== undefined) return { path, snapshot: true, error: `git worktree add failed (${message}); unborn-repo snapshot fallback failed: ${snapshotError}` };
-  return { path, snapshot: true };
+  return await finalizeWorktreeRef({ path, snapshot: true, runner, signal: options.signal, timeoutMs });
+}
+
+async function finalizeWorktreeRef(options: {
+  readonly path: string;
+  readonly snapshot?: boolean;
+  readonly runner: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+}): Promise<WorktreeRef | WorktreeAddFailure> {
+  const resolved = await options.runner
+    .runGit({
+      cwd: options.path,
+      args: ["rev-parse", "--verify", "HEAD^{commit}"],
+      signal: options.signal,
+      timeoutMs: options.timeoutMs,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
+  if (!resolved.ok) {
+    return {
+      path: options.path,
+      snapshot: options.snapshot,
+      error: resolved.error ?? (resolved.stderr.trim() || "failed to resolve isolated worktree baseline"),
+    };
+  }
+  const baselineOid = resolved.stdout.trim();
+  if (!isGitObjectId(baselineOid)) {
+    return { path: options.path, snapshot: options.snapshot, error: "isolated worktree baseline is not a commit OID" };
+  }
+  return { path: options.path, baselineOid, snapshot: options.snapshot };
+}
+
+async function prepareWorktreeBaseline(options: {
+  readonly path: string;
+  readonly patch: string;
+  readonly runner: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+}): Promise<WorktreeGitCommandResult> {
+  const applied = await options.runner.runGit({
+    cwd: options.path,
+    args: ["apply", "--index", "--binary", "--whitespace=nowarn", "-"],
+    stdin: options.patch,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+  });
+  if (!applied.ok) return applied;
+  const hooksPath = await mkdtemp(join(tmpdir(), "pi-workflow-empty-hooks-"));
+  try {
+    return await options.runner.runGit({
+      cwd: options.path,
+      args: syntheticCommitArgs(hooksPath, "pi workflow reviewed snapshot"),
+      env: SYNTHETIC_COMMIT_ENV,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs,
+    });
+  } finally {
+    await rm(hooksPath, { recursive: true, force: true });
+  }
 }
 
 export async function removeWorktree(options: {
@@ -203,10 +351,12 @@ export async function removeWorktree(options: {
 
 export async function captureWorktreePatch(options: {
   readonly worktreePath: string;
+  readonly baselineOid: string;
   readonly runner?: WorktreeGitRunner;
   readonly signal?: AbortSignal;
   readonly timeoutMs?: number;
 }): Promise<WorktreePatch | { readonly error: string }> {
+  if (!isGitObjectId(options.baselineOid)) return { error: "worktree patch baseline is not a commit OID" };
   const runner = options.runner ?? spawnGitRunner;
   const timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
   const intentToAdd = await runner
@@ -216,54 +366,144 @@ export async function captureWorktreePatch(options: {
       signal: options.signal,
       timeoutMs,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(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"],
+      args: ["diff", "--binary", "--full-index", "--no-ext-diff", "--no-color", options.baselineOid, "--"],
       signal: options.signal,
       timeoutMs,
       maxBufferBytes: WORKTREE_DIFF_MAX_BYTES,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(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 async function validateWorktreePatch(options: {
+  readonly worktreePath: string;
+  readonly candidate: WorktreePatch;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}): Promise<WorktreeGitCommandResult> {
+  const hasPatch = options.candidate.patch.trim().length > 0;
+  if (options.candidate.changed !== hasPatch) {
+    return invalidPatchResult("cached worktree patch changed flag does not match patch content");
+  }
+  if (!hasPatch) return { ok: true, stdout: "", stderr: "" };
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
+  return await (options.runner ?? spawnGitRunner)
+    .runGit({
+      cwd: options.worktreePath,
+      args: ["apply", "--check", "--binary", "-"],
+      stdin: options.candidate.patch,
+      signal: options.signal,
+      timeoutMs,
+    })
+    .catch((error: unknown) => invalidPatchResult(unknownErrorMessage(error)));
+}
+
+function invalidPatchResult(error: string): WorktreeGitCommandResult {
+  return { ok: false, stdout: "", stderr: "", error };
+}
+
 async function createUnbornRepoSnapshot(options: {
   readonly repoCwd: string;
   readonly path: string;
   readonly signal?: AbortSignal;
   readonly timeoutMs?: number;
 }): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
+  const rootProbe = await runGitCommand({
+    cwd: options.repoCwd,
+    args: ["rev-parse", "--show-toplevel"],
+    signal: options.signal,
+    timeoutMs,
+  });
+  if (!rootProbe.ok) {
+    throw new Error(rootProbe.error ?? (rootProbe.stderr.trim() || "failed to resolve unborn repository root"));
+  }
+  const sourceRoot = parseGitTopLevel(rootProbe.stdout, options.repoCwd);
+  if (!sourceRoot) throw new Error("unborn repository root probe returned an invalid path");
+
   const targetRoot = resolve(options.path);
   await rm(options.path, { recursive: true, force: true });
   await mkdir(options.path, { recursive: true });
-  await cp(options.repoCwd, options.path, {
+  await cp(sourceRoot, options.path, {
     recursive: true,
     force: true,
     filter: (source) => {
       const resolvedSource = resolve(source);
       if (resolvedSource === targetRoot || resolvedSource.startsWith(`${targetRoot}${sep}`)) return false;
-      return !resolvedSource.split(/[\\/]/).includes(".git");
+      return !isExcludedSnapshotPath(sourceRoot, resolvedSource);
     },
   });
-  await runGitCommand({ cwd: options.path, args: ["init"], signal: options.signal, timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS });
-  await runGitCommand({ cwd: options.path, args: ["add", "-A"], signal: options.signal, timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS });
-  await runGitCommand({
-    cwd: options.path,
-    args: ["-c", "user.name=pi-workflow", "-c", "user.email=pi-workflow@example.invalid", "commit", "--allow-empty", "-m", "pi workflow baseline"],
-    signal: options.signal,
-    timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
-  });
+  await requireGitCommand({ cwd: options.path, args: ["init"], signal: options.signal, timeoutMs });
+  await requireGitCommand({ cwd: options.path, args: ["add", "-A"], signal: options.signal, timeoutMs });
+  const hooksPath = await mkdtemp(join(tmpdir(), "pi-workflow-empty-hooks-"));
+  try {
+    await requireGitCommand({
+      cwd: options.path,
+      args: syntheticCommitArgs(hooksPath, "pi workflow baseline"),
+      env: SYNTHETIC_COMMIT_ENV,
+      signal: options.signal,
+      timeoutMs,
+    });
+  } finally {
+    await rm(hooksPath, { recursive: true, force: true });
+  }
+  await requireGitCommand({ cwd: options.path, args: ["clean", "-ffdx"], signal: options.signal, timeoutMs });
+}
+
+function syntheticCommitArgs(hooksPath: string, message: string): readonly string[] {
+  return [
+    "-c",
+    `core.hooksPath=${hooksPath}`,
+    "-c",
+    "commit.gpgSign=false",
+    "commit",
+    "--allow-empty",
+    "--no-verify",
+    "--no-gpg-sign",
+    "-m",
+    message,
+  ];
+}
+
+async function requireGitCommand(options: WorktreeGitCommandOptions): Promise<void> {
+  const result = await runGitCommand(options);
+  if (!result.ok) throw new Error(result.error ?? (result.stderr.trim() || "git command failed"));
+}
+
+function parseGitTopLevel(output: string, cwd: string): string | undefined {
+  const withoutLf = output.endsWith("\n") ? output.slice(0, -1) : output;
+  const value = withoutLf.endsWith("\r") ? withoutLf.slice(0, -1) : withoutLf;
+  if (value.length === 0 || value.includes("\n") || value.includes("\0")) return undefined;
+  const root = resolve(cwd, value);
+  const cwdFromRoot = relative(root, resolve(cwd));
+  return isAbsolute(cwdFromRoot) || cwdFromRoot === ".." || cwdFromRoot.startsWith(`..${sep}`) ? undefined : root;
+}
+
+function isExcludedSnapshotPath(sourceRoot: string, source: string): boolean {
+  const path = relative(sourceRoot, source);
+  if (path.length === 0) return false;
+  const segments = path.split(sep);
+  if (segments.includes(".git")) return true;
+  return segments.some((segment, index) => segment === ".pi" && segments[index + 1] === ".workflow-runs");
 }
 
 function isInvalidHeadError(message: string): boolean {
   return /invalid reference:\s*HEAD/i.test(message) || /ambiguous argument ['"]?HEAD/i.test(message) || /unknown revision or path.*HEAD/i.test(message);
 }
 
+function isGitObjectId(value: string): boolean {
+  return /^[0-9a-f]{40,64}$/i.test(value);
+}
+
 export const spawnGitRunner: WorktreeGitRunner = {
   async runGit(options) {
     return await runGitCommand(options);
@@ -271,7 +511,7 @@ export const spawnGitRunner: WorktreeGitRunner = {
 };
 
 async function runGitCommand(options: WorktreeGitCommandOptions): Promise<WorktreeGitCommandResult> {
-  const env = { ...process.env };
+  const env = { ...process.env, ...options.env };
   delete env.GIT_EXTERNAL_DIFF;
   delete env.GIT_DIFF_OPTS;
   return await runBoundedProcess({
@@ -279,6 +519,7 @@ async function runGitCommand(options: WorktreeGitCommandOptions): Promise<Worktr
     args: options.args,
     cwd: options.cwd,
     env,
+    stdin: options.stdin,
     signal: options.signal,
     timeoutMs: options.timeoutMs,
     maxBufferBytes: options.maxBufferBytes,
@@ -289,6 +530,6 @@ async function runGitCommand(options: WorktreeGitCommandOptions): Promise<Worktr
   });
 }
 
-function formatError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function worktreeRemovalError(outcome: WorktreeRemovalOutcome): string {
+  return outcome.error ?? (outcome.stderr.trim() || "unknown error");
 }