@duckmind/dm-linux-x64 0.65.5 → 0.65.6

package/extensions/dm-subagents/src/runs/shared/worktree.js

@@ -1,13 +1,134 @@
+import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
+import { runSetupCommand } from "./worktree-setup-command.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resolveAuthorityDecision } from "../../policy/authority.js";
 import { PROJECT_SUBAGENTS_RELATIVE_DIR } from "../../shared/artifacts.js";
 import { getAgentDir } from "../../shared/utils.js";
+export const DEFAULT_WORKTREE_PROVIDER = "auto";
+export const DEFAULT_WORKTREE_BASE_REF = "HEAD";
+export const DEFAULT_WORKTREE_BRANCH_PREFIX = "dm-subagents/";
+export const WORKTREE_AGENT_CWD_PLACEHOLDER = path.join(path.parse(process.cwd()).root, "__pi_subagents_worktree_cwd__");
+const WORKTREE_NAMING_COMPONENT_MAX_BYTES = 96;
+const WORKTREE_NAMING_LABEL_MAX_BYTES = 256;
+const WORKTREE_NAMING_BRANCH_MAX_BYTES = 256;
+const WORKTREE_COMMAND_OUTPUT_MAX_BYTES = 128 * 1024;
+const WORKTRUNK_COMMAND = process.platform === "win32" ? "git" : "wt";
+const WORKTRUNK_ARG_PREFIX = process.platform === "win32" ? ["wt"] : [];
+export const MACHINE_DIFF_OPTIONS = ["--no-color", "--no-ext-diff", "--no-textconv", "--default-prefix", "--line-prefix=", "--no-relative"];
+const MACHINE_PATCH_OPTIONS = [...MACHINE_DIFF_OPTIONS, "--binary"];
+const PATCH_VALIDATION_OPTIONS = ["apply", "--check", "--cached", "--reverse", "--binary", "--whitespace=nowarn"];
 const DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS = 30000;
-function runGit(cwd, args) {
-  const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8", windowsHide: true });
+
+export class WorktreeSetupError extends Error {
+  snapshot;
+  constructor(error, snapshot) {
+    super(`${error instanceof Error ? error.message : String(error)}${snapshot.unknown ? `; setup settlement unknown: ${snapshot.unknown}; manual reconciliation required` : ""}`, { cause: error });
+    this.name = "WorktreeSetupError";
+    this.snapshot = snapshot;
+  }
+}
+let worktreeTurn = Promise.resolve();
+let setupActive = false;
+let setupPoison;
+function assertWorktreeMutationAllowed() {
+  if (setupPoison)
+    throw new Error(`Worktree mutation blocked: ${setupPoison}`);
+  if (setupActive)
+    throw new Error("Worktree setup is active; finalization must await withWorktreeTransaction");
+}
+export async function withWorktreeTransaction(action) {
+  const previous = worktreeTurn;
+  let release;
+  worktreeTurn = new Promise((resolve) => {
+    release = resolve;
+  });
+  await previous;
+  try {
+    if (setupPoison)
+      throw new Error(`Worktree mutation blocked: ${setupPoison}`);
+    return await action();
+  } finally {
+    release();
+  }
+}
+
+class SetupTransaction {
+  progress;
+  options;
+  constructor(cwd, options) {
+    this.options = options;
+    this.progress = { setup: { cwd, baseCommit: "", worktrees: [] }, attempts: [], phase: "preflight" };
+  }
+  snapshot() {
+    return structuredClone(this.progress);
+  }
+  publish() {
+    this.options.onProgress?.(this.snapshot());
+  }
+  check() {
+    if (setupPoison)
+      throw new Error(setupPoison);
+    if (this.options.signal?.aborted)
+      throw new Error("Worktree setup aborted");
+    if (this.options.deadlineAt !== undefined && Date.now() >= this.options.deadlineAt)
+      throw new Error("Worktree setup deadline exceeded");
+  }
+  unknown(error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    this.progress.unknown ??= reason;
+    setupPoison ??= reason;
+  }
+  async command(command, args, options = {}) {
+    this.check();
+    this.progress.command = { command, args };
+    if (this.progress.phase === "allocation")
+      this.progress.attempts.at(-1).command = this.progress.command;
+    if (this.progress.phase === "hook")
+      this.progress.attempts.find((attempt) => attempt.path === options.cwd).hookCommand = this.progress.command;
+    const result = await runSetupCommand(command, args, {
+      ...options,
+      signal: this.options.signal,
+      deadlineAt: this.options.deadlineAt,
+      onSpawn: (process) => {
+        Object.assign(this.progress.command, process);
+        this.publish();
+      }
+    });
+    const { stdout: _stdout, stdoutBuffer: _stdoutBuffer, stderr: _stderr, ...metadata } = result;
+    this.progress.command.result = metadata;
+    if (result.processTree?.state === "unknown")
+      this.unknown(result.error ?? "Command tree settlement unverified");
+    this.publish();
+    if (result.error)
+      throw result.error;
+    return result;
+  }
+  async git(cwd, args, acceptedExitCodes) {
+    return this.command("git", ["-C", cwd, ...args], { acceptedExitCodes });
+  }
+  async gitChecked(cwd, args) {
+    const result = await this.git(cwd, args);
+    return result.stdout;
+  }
+  attempt(index, branch, worktreePath) {
+    this.check();
+    this.progress.phase = "allocation";
+    this.progress.command = undefined;
+    this.progress.attempts.push({ index, branch, path: worktreePath, validated: false });
+    this.publish();
+  }
+  validated(worktree) {
+    this.progress.phase = "validated";
+    Object.assign(this.progress.attempts.at(-1), { path: worktree.path, validated: true });
+    this.progress.setup.worktrees.push(worktree);
+    this.publish();
+  }
+}
+function runGit(cwd, args, env) {
+  const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8", windowsHide: true, shell: false, ...env ? { env: { ...process.env, ...env } } : {} });
   return {
     stdout: result.stdout ?? "",
     stderr: result.stderr ?? "",
@@ -23,14 +144,94 @@ function runGitChecked(cwd, args) {
   }
   return result.stdout;
 }
-function resolveRepoState(cwd) {
-  const cwdRelative = resolveRepoCwdRelative(cwd);
-  const toplevel = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
-  const status = runGitChecked(toplevel, ["status", "--porcelain", "--", `:!${PROJECT_SUBAGENTS_RELATIVE_DIR}`]);
+export function validateWorktreePatch(worktreePath, patchPath) {
+  const result = runGit(worktreePath, [...PATCH_VALIDATION_OPTIONS, patchPath]);
+  if (result.status === 0)
+    return;
+  return result.stderr.trim() || result.stdout.trim() || `git -C ${worktreePath} apply --check failed`;
+}
+function currentWorktreePatch(worktreePath, baseCommit) {
+  assertWorktreeMutationAllowed();
+  let tempDir;
+  try {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "dm-worktree-index-"));
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+  const env = { GIT_INDEX_FILE: path.join(tempDir, "index") };
+  try {
+    const readTree = runGit(worktreePath, ["read-tree", "HEAD"], env);
+    if (readTree.status !== 0)
+      return { error: readTree.stderr.trim() || readTree.stdout.trim() || "git read-tree failed" };
+    const add = runGit(worktreePath, ["add", "-A"], env);
+    if (add.status !== 0)
+      return { error: add.stderr.trim() || add.stdout.trim() || "git add failed" };
+    const diff = runGit(worktreePath, ["diff", "--cached", ...MACHINE_PATCH_OPTIONS, baseCommit], env);
+    if (diff.status !== 0)
+      return { error: diff.stderr.trim() || diff.stdout.trim() || "git diff failed" };
+    return { patch: diff.stdout };
+  } finally {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {}
+  }
+}
+export function validateWorktreePatchRepresentsCurrentWorktree(worktreePath, baseCommit, patchPath) {
+  const validationError = validateWorktreePatch(worktreePath, patchPath);
+  if (validationError)
+    return validationError;
+  let capturedPatch;
+  try {
+    capturedPatch = fs.readFileSync(patchPath, "utf-8");
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  const current = currentWorktreePatch(worktreePath, baseCommit);
+  if ("error" in current)
+    return current.error || "failed to capture current worktree patch";
+  if (capturedPatch !== current.patch)
+    return "captured handoff patch does not match current worktree changes";
+  return;
+}
+async function probeWorktreeSource(tx, cwd) {
+  const repoCheck = await tx.git(cwd, ["rev-parse", "--is-inside-work-tree"], [0, 128]);
+  if (repoCheck.status !== 0 || repoCheck.stdout.trim() !== "true")
+    throw new Error("worktree isolation requires a git repository");
+  const toplevel = (await tx.gitChecked(cwd, ["rev-parse", "--show-toplevel"])).trim();
+  const status = await tx.gitChecked(toplevel, ["status", "--porcelain", "--", `:!${PROJECT_SUBAGENTS_RELATIVE_DIR}`]);
   if (status.trim().length > 0) {
     throw new Error("worktree isolation requires a clean git working tree. Commit or stash changes first.");
   }
-  const baseCommit = runGitChecked(toplevel, ["rev-parse", "HEAD"]).trim();
+  return toplevel;
+}
+export async function preflightWorktreeSource(cwd, options = {}) {
+  const git = async (cwd, args, acceptedExitCodes = [0]) => {
+    const result = await runSetupCommand("git", ["-C", cwd, ...args], { ...options, acceptedExitCodes });
+    if (result.error)
+      throw result.error;
+    if (result.outputIncomplete || result.status === null || !acceptedExitCodes.includes(result.status)) {
+      throw new Error(result.stderr.trim().slice(0, 2000) || "Worktree source probe failed");
+    }
+    return result;
+  };
+  await probeWorktreeSource({ git, gitChecked: async (cwd, args) => (await git(cwd, args)).stdout }, cwd);
+}
+async function resolveRepoState(tx, cwd, requestedBaseRef) {
+  const toplevel = await probeWorktreeSource(tx, cwd);
+  const rawPrefix = (await tx.gitChecked(cwd, ["rev-parse", "--show-prefix"])).trim();
+  const cwdRelative = rawPrefix ? path.normalize(rawPrefix.replace(/[\\/]+$/, "")) : "";
+  const baseRef = normalizeWorktreeBaseRef(requestedBaseRef) ?? DEFAULT_WORKTREE_BASE_REF;
+  let baseCommit;
+  try {
+    const base = await tx.git(toplevel, ["rev-parse", "--verify", "--end-of-options", `${baseRef}^{commit}`], [0, 128]);
+    if (base.status !== 0)
+      throw new Error(base.stderr.trim() || "ref not found");
+    baseCommit = base.stdout.trim();
+  } catch (error) {
+    throw new Error(`baseRef '${baseRef}' could not be resolved to a commit: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
+  }
+  if (!baseCommit)
+    throw new Error(`baseRef '${baseRef}' could not be resolved to a commit`);
   return { toplevel, cwdRelative, baseCommit };
 }
 function normalizeComparableCwd(cwd) {
@@ -39,7 +240,13 @@ function normalizeComparableCwd(cwd) {
   const missingSegments = [];
   while (true) {
     try {
-      return path.join(fs.realpathSync(existing), ...missingSegments.reverse());
+      let realpath;
+      try {
+        realpath = fs.realpathSync.native(existing);
+      } catch {
+        realpath = fs.realpathSync(existing);
+      }
+      return path.join(realpath, ...missingSegments.reverse());
     } catch {
       const parent = path.dirname(existing);
       if (parent === existing)
@@ -68,33 +275,263 @@ export function formatWorktreeTaskCwdConflict(conflict, sharedCwd) {
 function safePatchAgentName(agent) {
   return agent.replace(/[^\w.-]/g, "_");
 }
-function buildWorktreeBranch(runId, index) {
-  return `dm-parallel-${runId}-${index}`;
+function shortWorktreeHash(value) {
+  return createHash("sha256").update(value, "utf-8").digest("hex").slice(0, 8);
 }
-function resolveWorktreeBaseDir(configuredBaseDir, repoRoot) {
+function truncateUtf8(value, maxBytes) {
+  const bytes = Buffer.from(value, "utf-8");
+  if (bytes.length <= maxBytes)
+    return value;
+  let end = maxBytes;
+  while (end > 0 && (bytes[end] & 192) === 128)
+    end -= 1;
+  return bytes.subarray(0, end).toString("utf-8");
+}
+export function sanitizeWorktreePathComponent(value, maxBytes = WORKTREE_NAMING_COMPONENT_MAX_BYTES) {
+  const raw = value.trim();
+  let normalized = raw.replace(/[\\/\s]+/g, "-").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-+/g, "-").replace(/^[._-]+|[._-]+$/g, "");
+  if (!normalized)
+    return "task";
+  const changed = normalized !== raw;
+  if (changed || Buffer.byteLength(normalized, "utf-8") > maxBytes) {
+    const suffix = `-${shortWorktreeHash(raw || "task")}`;
+    const prefix = truncateUtf8(normalized, Math.max(1, maxBytes - Buffer.byteLength(suffix, "utf-8"))).replace(/[._-]+$/g, "");
+    normalized = `${prefix || "task"}${suffix}`;
+  }
+  return truncateUtf8(normalized, maxBytes).replace(/^[._-]+|[._-]+$/g, "") || "task";
+}
+function validGitRef(ref) {
+  if (!ref || ref === "@" || Buffer.byteLength(ref, "utf-8") > 1024 || ref.startsWith("/") || ref.endsWith("/") || ref.includes("//") || ref.includes("..") || ref.includes("@{"))
+    return false;
+  if (/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(ref))
+    return false;
+  if (/[[\]\\~^:?*\u0000-\u0020\u007f]/u.test(ref) || ref.endsWith(".") || ref.endsWith(".lock"))
+    return false;
+  return ref.split("/").every((component) => component.length > 0 && component !== "." && component !== ".." && !component.startsWith(".") && !component.endsWith(".") && !component.endsWith(".lock"));
+}
+export function normalizeWorktreeBaseRef(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || !validGitRef(value))
+    throw new Error("baseRef must be a valid Git ref: use HEAD or a supported named ref (for example, refs/heads/main). Full 40/64-character commit IDs and revision expressions are unsupported.");
+  return value;
+}
+export function normalizeWorktreeBranchPrefix(value) {
+  const raw = value === undefined ? DEFAULT_WORKTREE_BRANCH_PREFIX : value.trim();
+  if (!raw)
+    throw new Error("worktree branch prefix cannot be empty");
+  if (raw.includes("\\") || /[\u0000-\u001f\u007f\s]/u.test(raw) || raw.startsWith("/") || raw.includes("//") || raw.includes("..") || raw.includes("@{")) {
+    throw new Error("worktree branch prefix contains invalid Git ref characters");
+  }
+  const withoutTrailingSlash = raw.replace(/\/+$/u, "");
+  if (!withoutTrailingSlash || withoutTrailingSlash.startsWith("-") || withoutTrailingSlash.split("/").some((component) => component === "." || component === ".." || component.startsWith("."))) {
+    throw new Error("worktree branch prefix contains an invalid Git ref component");
+  }
+  const prefix = `${withoutTrailingSlash}/`;
+  if (!validGitRef(`${prefix}task`))
+    throw new Error("worktree branch prefix is not a valid Git ref namespace");
+  return prefix;
+}
+function runShortId(runId) {
+  const base = runId.replace(/-s\d+$/u, "");
+  const normalized = sanitizeWorktreePathComponent(base || runId, 16);
+  return normalized.length > 12 ? normalized.slice(0, 12) : normalized;
+}
+function nonNegativeNamingIndex(value, label, fallback) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 0)
+    throw new Error(`${label} must be a non-negative integer`);
+  return resolved;
+}
+export function buildWorktreeNaming(input) {
+  if (!input.runId.trim())
+    throw new Error("worktree run id cannot be empty");
+  const index = nonNegativeNamingIndex(input.index, "worktree index", 0);
+  const stepIndex = nonNegativeNamingIndex(input.stepIndex, "worktree step index", Number(input.runId.match(/-s(\d+)$/u)?.[1] ?? 0));
+  const taskIndex = nonNegativeNamingIndex(input.taskIndex, "worktree task index", index);
+  const label = input.laneKey?.trim() || input.workflowKey?.trim() || input.outputName?.trim() || input.taskKey?.trim() || input.label?.trim() || (input.agent?.trim() && input.task?.trim() ? `${input.agent.trim()}-${input.task.trim()}` : undefined) || input.agent?.trim() || "task";
+  const branchPrefix = normalizeWorktreeBranchPrefix(input.branchPrefix);
+  const labelComponent = sanitizeWorktreePathComponent(label);
+  const pathComponentBase = `${labelComponent}-${runShortId(input.runId)}-s${stepIndex}-t${taskIndex}`;
+  const sanitizedPathComponent = validGitRef(`${branchPrefix}${pathComponentBase}`) ? pathComponentBase : sanitizeWorktreePathComponent(pathComponentBase, WORKTREE_NAMING_COMPONENT_MAX_BYTES);
+  let requestedBranch = `${branchPrefix}${sanitizedPathComponent}`;
+  if (!validGitRef(requestedBranch) || Buffer.byteLength(requestedBranch, "utf-8") > WORKTREE_NAMING_BRANCH_MAX_BYTES) {
+    const suffix = `-${shortWorktreeHash(pathComponentBase)}`;
+    const available = Math.max(1, WORKTREE_NAMING_BRANCH_MAX_BYTES - Buffer.byteLength(branchPrefix, "utf-8") - Buffer.byteLength(suffix, "utf-8"));
+    requestedBranch = `${branchPrefix}${truncateUtf8(pathComponentBase, available).replace(/[._-]+$/g, "")}${suffix}`;
+  }
+  if (!validGitRef(requestedBranch) || Buffer.byteLength(requestedBranch, "utf-8") > WORKTREE_NAMING_BRANCH_MAX_BYTES)
+    throw new Error(`generated worktree branch is not a valid Git ref: ${requestedBranch}`);
+  const metadataLabel = truncateUtf8(label.replace(/[\u0000-\u001f\u007f]+/gu, " ").replace(/\s+/gu, " ").trim() || "task", WORKTREE_NAMING_LABEL_MAX_BYTES);
+  return {
+    requestedBranch,
+    branchPrefix,
+    label: metadataLabel,
+    sanitizedPathComponent: requestedBranch.slice(branchPrefix.length)
+  };
+}
+function hasConfiguredWorktreeBaseDir(baseDir) {
+  return baseDir !== undefined ? true : (process.env.DM_SUBAGENTS_WORKTREE_DIR?.trim().length ?? 0) > 0;
+}
+function isInsidePiExtensionsDirectory(targetPath) {
+  const extensionsDir = normalizeComparableCwd(path.join(getAgentDir(), "extensions"));
+  return isPathInside(extensionsDir, normalizeComparableCwd(targetPath));
+}
+function runWorktrunk(args, cwd) {
+  try {
+    const result = spawnSync(WORKTRUNK_COMMAND, [...WORKTRUNK_ARG_PREFIX, ...args], {
+      cwd,
+      encoding: "utf-8",
+      windowsHide: true,
+      shell: false,
+      maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES
+    });
+    const stdout = result.stdout ?? "";
+    const stderr = result.stderr ?? "";
+    if (Buffer.byteLength(stdout, "utf-8") > WORKTREE_COMMAND_OUTPUT_MAX_BYTES)
+      throw new Error("Worktrunk stdout exceeds the output limit");
+    return { stdout, stderr, status: result.status, ...result.error ? { error: result.error } : {} };
+  } catch (error) {
+    return { stdout: "", stderr: "", status: null, error: error instanceof Error ? error : new Error(String(error)) };
+  }
+}
+function probeWorktrunk() {
+  const result = runWorktrunk(["--version"]);
+  if (result.status !== 0)
+    return { available: false, reason: result.error?.message || result.stderr.trim() || "Worktrunk is unavailable" };
+  const version = result.stdout.trim().match(/\b(?:wt\s+)?v?(\d+\.\d+(?:\.\d+)?)\b/i)?.[1];
+  if (!version)
+    return { available: false, reason: "Worktrunk returned an invalid version" };
+  const help = runWorktrunk(["switch", "--help"]);
+  if (help.status !== 0)
+    return { available: false, reason: help.error?.message || help.stderr.trim() || "Worktrunk switch capability is unavailable" };
+  const helpText = `${help.stdout}
+${help.stderr}`;
+  const requiredCapabilities = ["--create", "--base", "--no-cd", "--no-hooks", "--format"];
+  const missing = requiredCapabilities.filter((flag) => !helpText.includes(flag));
+  if (missing.length > 0)
+    return { available: false, reason: `Worktrunk switch is missing required capabilities: ${missing.join(", ")}` };
+  return { available: true };
+}
+export function resolveWorktreeProvider(requested, baseDir) {
+  const selection = requested ?? DEFAULT_WORKTREE_PROVIDER;
+  if (selection !== "auto" && selection !== "native" && selection !== "worktrunk")
+    throw new Error(`worktree provider must be "auto", "native", or "worktrunk"`);
+  if (selection === "native")
+    return "native";
+  if (hasConfiguredWorktreeBaseDir(baseDir)) {
+    if (selection === "worktrunk")
+      throw new Error("worktreeProvider='worktrunk' cannot be combined with worktreeBaseDir or DM_SUBAGENTS_WORKTREE_DIR");
+    return "native";
+  }
+  const capability = probeWorktrunk();
+  if (capability.available)
+    return "worktrunk";
+  if (selection === "worktrunk")
+    throw new Error(`Worktrunk provider is unavailable: ${capability.reason ?? "unknown capability failure"}`);
+  return "native";
+}
+async function resolveSetupProvider(tx, requested, baseDir, repoRoot) {
+  const selection = requested ?? DEFAULT_WORKTREE_PROVIDER;
+  if (selection !== "auto" && selection !== "native" && selection !== "worktrunk")
+    throw new Error('worktree provider must be "auto", "native", or "worktrunk"');
+  if (selection === "native")
+    return "native";
+  if (hasConfiguredWorktreeBaseDir(baseDir)) {
+    if (selection === "worktrunk")
+      throw new Error("worktreeProvider='worktrunk' cannot be combined with worktreeBaseDir or DM_SUBAGENTS_WORKTREE_DIR");
+    return "native";
+  }
+  if (selection === "auto" && isInsidePiExtensionsDirectory(repoRoot))
+    return "native";
+  let reason;
+  try {
+    const probeExitCodes = Array.from({ length: 256 }, (_, code) => code);
+    const version = await tx.command(WORKTRUNK_COMMAND, [...WORKTRUNK_ARG_PREFIX, "--version"], { maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES, acceptedExitCodes: probeExitCodes });
+    if (version.status !== 0 || !/\b(?:wt\s+)?v?(\d+\.\d+(?:\.\d+)?)\b/i.test(version.stdout.trim()))
+      reason = "Worktrunk is unavailable or returned an invalid version";
+    else {
+      const help = await tx.command(WORKTRUNK_COMMAND, [...WORKTRUNK_ARG_PREFIX, "switch", "--help"], { maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES, acceptedExitCodes: probeExitCodes });
+      const missing = ["--create", "--base", "--no-cd", "--no-hooks", "--format"].filter((flag) => !`${help.stdout}
+${help.stderr}`.includes(flag));
+      if (help.status !== 0 || missing.length)
+        reason = `Worktrunk switch capability unavailable: ${missing.join(", ")}`;
+    }
+  } catch (error) {
+    if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT")
+      throw error;
+    reason = error.message;
+  }
+  if (!reason)
+    return "worktrunk";
+  if (selection === "worktrunk")
+    throw new Error(`Worktrunk provider is unavailable: ${reason}`);
+  return "native";
+}
+export function shouldDeferWorktreeCwd(requested, baseDir) {
+  return (requested ?? DEFAULT_WORKTREE_PROVIDER) !== "native" && !hasConfiguredWorktreeBaseDir(baseDir);
+}
+function resolveWorktreeDedicatedRoot(configuredBaseDir, repoRoot, relocateExtensionRepo = true) {
   const rawBaseDir = configuredBaseDir ?? process.env.DM_SUBAGENTS_WORKTREE_DIR;
-  if (rawBaseDir === undefined)
-    return os.tmpdir();
-  const trimmed = rawBaseDir.trim();
-  if (!trimmed)
-    throw new Error("worktree base directory cannot be empty");
-  const expanded = trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(2)) : trimmed;
-  const resolved = path.isAbsolute(expanded) ? expanded : path.resolve(repoRoot, expanded);
+  let expanded;
+  if (rawBaseDir === undefined || configuredBaseDir === undefined && !rawBaseDir.trim()) {
+    expanded = relocateExtensionRepo && isInsidePiExtensionsDirectory(repoRoot) ? path.join(getAgentDir(), "worktrees") : path.join(path.dirname(repoRoot), "worktrees");
+  } else {
+    const trimmed = rawBaseDir.trim();
+    if (!trimmed)
+      throw new Error("worktree base directory cannot be empty");
+    const candidate = trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(2)) : trimmed;
+    expanded = path.isAbsolute(candidate) ? candidate : path.resolve(repoRoot, candidate);
+  }
   const extensionsDir = normalizeComparableCwd(path.join(getAgentDir(), "extensions"));
-  const relativeToExtensions = path.relative(extensionsDir, normalizeComparableCwd(resolved));
-  if (!relativeToExtensions || !relativeToExtensions.startsWith(`..${path.sep}`) && relativeToExtensions !== ".." && !path.isAbsolute(relativeToExtensions)) {
+  if (isPathInside(extensionsDir, normalizeComparableCwd(expanded))) {
     throw new Error(`worktree base directory cannot be inside DM extensions directory: ${extensionsDir}. Choose a directory outside it.`);
   }
+  return expanded;
+}
+function buildNativeProjectPath(dedicatedRoot, repoRoot) {
+  return path.join(dedicatedRoot, path.basename(repoRoot));
+}
+function ensureProjectWorktreeDir(dedicatedRoot, repoRoot) {
   try {
-    fs.mkdirSync(resolved, { recursive: true });
+    fs.mkdirSync(buildNativeProjectPath(dedicatedRoot, repoRoot), { recursive: true });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`failed to create worktree base directory ${resolved}: ${message}`);
+    throw new Error(`failed to create worktree base directory ${dedicatedRoot}: ${message}`);
   }
-  return resolved;
 }
-function buildWorktreePath(baseDir, runId, index) {
-  return path.join(baseDir, `dm-worktree-${runId}-${index}`);
+function buildNativeWorktreePath(dedicatedRoot, repoRoot, runId, index) {
+  return path.join(buildNativeProjectPath(dedicatedRoot, repoRoot), `dm-worktree-${sanitizeWorktreePathComponent(runId, 120)}-${index}`);
+}
+function isPathInside(parent, child) {
+  const relative = path.relative(parent, child);
+  if (!relative || relative === ".")
+    return true;
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function isStrictChildPath(parent, child) {
+  const relative = path.relative(parent, child);
+  return Boolean(relative) && relative !== "." && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function assertSafeWorktreeLocation(worktreePath, repoRoot, dedicatedRoot) {
+  const resolvedLeaf = normalizeComparableCwd(worktreePath);
+  const resolvedRepoRoot = normalizeComparableCwd(repoRoot);
+  const projectDir = normalizeComparableCwd(buildNativeProjectPath(dedicatedRoot, repoRoot));
+  const repoParent = normalizeComparableCwd(path.dirname(resolvedRepoRoot));
+  const leafParent = normalizeComparableCwd(path.dirname(resolvedLeaf));
+  const extensionsDir = normalizeComparableCwd(path.join(getAgentDir(), "extensions"));
+  if (isPathInside(extensionsDir, projectDir) || isPathInside(extensionsDir, resolvedLeaf)) {
+    throw new Error(`worktree path cannot be inside DM extensions directory: ${extensionsDir}. Choose a directory outside it.`);
+  }
+  if (isPathInside(resolvedRepoRoot, resolvedLeaf)) {
+    throw new Error(`worktree path would land inside the repository checkout: ${resolvedLeaf}`);
+  }
+  if (leafParent === repoParent) {
+    throw new Error(`worktree path would be a direct child of the repository parent: ${resolvedLeaf}`);
+  }
+  if (!isStrictChildPath(projectDir, resolvedLeaf)) {
+    throw new Error(`worktree path must be a strict child of the project worktree directory ${projectDir}: ${resolvedLeaf}`);
+  }
 }
 function resolveRepoCwdRelative(cwd) {
   const repoCheck = runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
@@ -108,19 +545,45 @@ function resolveRepoCwdRelative(cwd) {
 export function resolveExpectedWorktreeAgentCwd(cwd, runId, index, baseDir) {
   const cwdRelative = resolveRepoCwdRelative(cwd);
   const repoRoot = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
-  const worktreePath = buildWorktreePath(resolveWorktreeBaseDir(baseDir, repoRoot), runId, index);
+  const dedicatedRoot = resolveWorktreeDedicatedRoot(baseDir, repoRoot);
+  const worktreePath = buildNativeWorktreePath(dedicatedRoot, repoRoot, runId, index);
+  assertSafeWorktreeLocation(worktreePath, repoRoot, dedicatedRoot);
   return cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath;
 }
 function linkNodeModulesIfPresent(toplevel, worktreePath) {
   const nodeModulesPath = path.join(toplevel, "node_modules");
   const nodeModulesLinkPath = path.join(worktreePath, "node_modules");
-  if (!fs.existsSync(nodeModulesPath) || fs.existsSync(nodeModulesLinkPath))
-    return false;
+  const hasDirectoryEntry = (candidate) => {
+    try {
+      fs.lstatSync(candidate);
+      return true;
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT")
+        return false;
+      throw error;
+    }
+  };
   try {
-    fs.symlinkSync(nodeModulesPath, nodeModulesLinkPath);
+    if (hasDirectoryEntry(nodeModulesLinkPath))
+      return false;
+    let sourceRealPath;
+    try {
+      if (!fs.statSync(nodeModulesPath).isDirectory())
+        throw new Error("source node_modules is not a directory");
+      sourceRealPath = fs.realpathSync.native(nodeModulesPath);
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT")
+        return false;
+      throw error;
+    }
+    fs.symlinkSync(nodeModulesPath, nodeModulesLinkPath, process.platform === "win32" ? "junction" : "dir");
+    if (!fs.lstatSync(nodeModulesLinkPath).isSymbolicLink() || fs.realpathSync.native(nodeModulesLinkPath) !== sourceRealPath) {
+      throw new Error("created link does not resolve to the source node_modules");
+    }
     return true;
-  } catch {
-    return false;
+  } catch (error) {
+    const code = error instanceof Error && "code" in error && typeof error.code === "string" ? `${error.code}: ` : "";
+    throw new Error(`failed to link node_modules from ${nodeModulesPath} to ${nodeModulesLinkPath}: ${code}${error instanceof Error ? error.message : String(error)}`, { cause: error });
   }
 }
 function parseHookTimeout(timeoutMs) {
@@ -174,10 +637,6 @@ function normalizeSyntheticPath(worktreePath, rawPath) {
   }
   return path.normalize(relative);
 }
-function hasTrackedEntries(worktreePath, relativePath) {
-  const result = runGit(worktreePath, ["ls-files", "--", relativePath]);
-  return result.status === 0 && result.stdout.trim().length > 0;
-}
 function parseWorktreeSetupHookOutput(rawStdout) {
   const trimmed = rawStdout.trim();
   if (!trimmed) {
@@ -195,90 +654,166 @@ function parseWorktreeSetupHookOutput(rawStdout) {
   }
   return parsed;
 }
-function runWorktreeSetupHook(hook, input) {
-  const result = spawnSync(hook.hookPath, [], {
-    windowsHide: true,
-    cwd: input.worktreePath,
-    encoding: "utf-8",
-    input: JSON.stringify(input),
-    timeout: hook.timeoutMs,
-    shell: false
-  });
-  if (result.error) {
-    const code = "code" in result.error ? result.error.code : undefined;
-    if (code === "ETIMEDOUT") {
-      throw new Error(`worktree setup hook timed out after ${hook.timeoutMs}ms`);
-    }
-    throw new Error(`worktree setup hook failed: ${result.error.message}`);
-  }
-  if (result.status !== 0) {
-    const details = result.stderr.trim() || result.stdout.trim() || "no output";
-    throw new Error(`worktree setup hook failed with exit code ${result.status}: ${details}`);
-  }
-  const output = parseWorktreeSetupHookOutput(result.stdout);
-  if (output.syntheticPaths === undefined)
-    return [];
-  if (!Array.isArray(output.syntheticPaths)) {
-    throw new Error("worktree setup hook output field 'syntheticPaths' must be an array of relative paths");
+async function runWorktreeSetupHook(tx, hook, input) {
+  tx.progress.phase = "hook";
+  let result;
+  try {
+    result = await tx.command(hook.hookPath, [], {
+      cwd: input.worktreePath,
+      input: JSON.stringify(input),
+      hookTimeoutMs: hook.timeoutMs
+    });
+  } catch (error) {
+    throw new Error(`worktree setup hook failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
   }
-  const uniquePaths = new Set;
-  for (const candidate of output.syntheticPaths) {
-    if (typeof candidate !== "string") {
-      throw new Error("worktree setup hook output field 'syntheticPaths' must contain only strings");
+  tx.progress.phase = "hook-validation";
+  try {
+    const output = parseWorktreeSetupHookOutput(result.stdout);
+    if (output.syntheticPaths === undefined)
+      return [];
+    if (!Array.isArray(output.syntheticPaths)) {
+      throw new Error("worktree setup hook output field 'syntheticPaths' must be an array of relative paths");
     }
-    const normalizedPath = normalizeSyntheticPath(input.worktreePath, candidate);
-    if (hasTrackedEntries(input.worktreePath, normalizedPath)) {
-      throw new Error(`worktree setup hook cannot mark tracked paths as synthetic: ${normalizedPath}`);
+    const uniquePaths = new Set;
+    for (const candidate of output.syntheticPaths) {
+      if (typeof candidate !== "string")
+        throw new Error("worktree setup hook output field 'syntheticPaths' must contain only strings");
+      const normalizedPath = normalizeSyntheticPath(input.worktreePath, candidate);
+      if ((await tx.gitChecked(input.worktreePath, ["ls-files", "--", normalizedPath])).trim()) {
+        throw new Error(`worktree setup hook cannot mark tracked paths as synthetic: ${normalizedPath}`);
+      }
+      uniquePaths.add(normalizedPath);
     }
-    uniquePaths.add(normalizedPath);
+    return [...uniquePaths];
+  } catch (error) {
+    tx.unknown(error);
+    throw error;
   }
-  return [...uniquePaths];
 }
-function createSingleWorktree(toplevel, cwdRelative, runId, index, baseCommit, setupHook, agent, baseDir) {
-  const branch = buildWorktreeBranch(runId, index);
-  const worktreePath = buildWorktreePath(baseDir, runId, index);
-  const add = runGit(toplevel, ["worktree", "add", worktreePath, "-b", branch, "HEAD"]);
-  if (add.status !== 0) {
-    const message = add.stderr.trim() || add.stdout.trim() || `failed to create worktree ${worktreePath}`;
-    throw new Error(message);
+async function finalizeCreatedWorktree(tx, toplevel, cwdRelative, runId, baseCommit, setupHook, agent, worktree) {
+  const agentCwd = cwdRelative ? path.join(worktree.path, cwdRelative) : worktree.path;
+  tx.check();
+  const nodeModulesLinked = linkNodeModulesIfPresent(toplevel, worktree.path);
+  const syntheticPaths = nodeModulesLinked ? ["node_modules"] : [];
+  if (setupHook) {
+    const hookSyntheticPaths = await runWorktreeSetupHook(tx, setupHook, {
+      version: 1,
+      repoRoot: toplevel,
+      worktreePath: worktree.path,
+      agentCwd,
+      branch: worktree.branch,
+      index: worktree.index,
+      runId,
+      baseCommit,
+      agent
+    });
+    syntheticPaths.push(...hookSyntheticPaths);
   }
-  const agentCwd = cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath;
+  return { ...worktree, agentCwd, nodeModulesLinked, syntheticPaths };
+}
+async function createNativeWorktree(tx, toplevel, cwdRelative, runId, index, baseCommit, setupHook, agent, dedicatedRoot, labels, tasks, branchPrefix) {
+  const naming = buildWorktreeNaming({ runId, index, agent, label: labels?.[index], task: tasks?.[index], branchPrefix });
+  const worktreePath = buildNativeWorktreePath(dedicatedRoot, toplevel, runId, index);
+  assertSafeWorktreeLocation(worktreePath, toplevel, dedicatedRoot);
+  const branch = await tx.git(toplevel, ["show-ref", "--verify", "--quiet", `refs/heads/${naming.requestedBranch}`], [0, 1]);
+  let pathExists = false;
   try {
-    const nodeModulesLinked = linkNodeModulesIfPresent(toplevel, worktreePath);
-    const syntheticPaths = nodeModulesLinked ? ["node_modules"] : [];
-    if (setupHook) {
-      const hookSyntheticPaths = runWorktreeSetupHook(setupHook, {
-        version: 1,
-        repoRoot: toplevel,
-        worktreePath,
-        agentCwd,
-        branch,
-        index,
-        runId,
-        baseCommit,
-        agent
-      });
-      syntheticPaths.push(...hookSyntheticPaths);
+    fs.lstatSync(worktreePath);
+    pathExists = true;
+  } catch (error) {
+    if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT")
+      throw error;
+  }
+  if (branch.status !== 1 || pathExists)
+    throw new Error(`worktree path or branch already exists: ${worktreePath}, ${naming.requestedBranch}`);
+  tx.attempt(index, naming.requestedBranch, worktreePath);
+  ensureProjectWorktreeDir(dedicatedRoot, toplevel);
+  await tx.git(toplevel, ["worktree", "add", worktreePath, "-b", naming.requestedBranch, baseCommit]);
+  const worktree = {
+    path: worktreePath,
+    agentCwd: worktreePath,
+    branch: naming.requestedBranch,
+    index,
+    nodeModulesLinked: false,
+    syntheticPaths: [],
+    provider: "native",
+    naming
+  };
+  tx.validated(worktree);
+  return finalizeCreatedWorktree(tx, toplevel, cwdRelative, runId, baseCommit, setupHook, agent, worktree);
+}
+function parseWorktrunkSwitchOutput(rawStdout) {
+  if (Buffer.byteLength(rawStdout, "utf-8") > WORKTREE_COMMAND_OUTPUT_MAX_BYTES)
+    throw new Error("Worktrunk provisioning output exceeds the output limit");
+  const trimmed = rawStdout.trim();
+  if (!trimmed)
+    throw new Error("Worktrunk provisioning returned empty stdout; expected JSON object");
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (error) {
+    throw new Error(`Worktrunk provisioning returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error("Worktrunk provisioning stdout must be a JSON object");
+  return parsed;
+}
+async function createWorktrunkWorktree(tx, toplevel, cwdRelative, runId, index, baseCommit, agents, labels, tasks, branchPrefix) {
+  const naming = buildWorktreeNaming({ runId, index, agent: agents?.[index], label: labels?.[index], task: tasks?.[index], branchPrefix });
+  const args = ["-C", toplevel, "switch", "--create", naming.requestedBranch, "--base", baseCommit, "--no-cd", "--no-hooks", "--format", "json"];
+  tx.attempt(index, naming.requestedBranch);
+  const result = await tx.command(WORKTRUNK_COMMAND, [...WORKTRUNK_ARG_PREFIX, ...args], { cwd: toplevel, maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES });
+  tx.progress.phase = "validation";
+  try {
+    const output = parseWorktrunkSwitchOutput(result.stdout);
+    if (output.action !== "created" || output.created_branch !== true || output.branch !== naming.requestedBranch || output.base_branch !== baseCommit) {
+      throw new Error("Worktrunk provisioning returned inconsistent creation metadata");
     }
-    return {
+    if (typeof output.path !== "string" || !path.isAbsolute(output.path))
+      throw new Error("Worktrunk provisioning returned a non-absolute worktree path");
+    const worktreePathCandidate = path.resolve(output.path);
+    let stat;
+    try {
+      stat = fs.lstatSync(worktreePathCandidate);
+    } catch (error) {
+      throw new Error(`Worktrunk provisioning returned a missing worktree path: ${worktreePathCandidate}`, { cause: error instanceof Error ? error : undefined });
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+      throw new Error("Worktrunk provisioning returned a path that is not a real directory");
+    const worktreePath = normalizeComparableCwd(worktreePathCandidate);
+    if (worktreePath === normalizeComparableCwd(toplevel))
+      throw new Error("Worktrunk provisioning returned the source checkout path");
+    const sourceCommonDirRaw = (await tx.gitChecked(toplevel, ["rev-parse", "--git-common-dir"])).trim();
+    const returnedCommonDirRaw = (await tx.gitChecked(worktreePath, ["rev-parse", "--git-common-dir"])).trim();
+    const sourceCommonDir = normalizeComparableCwd(path.isAbsolute(sourceCommonDirRaw) ? sourceCommonDirRaw : path.resolve(toplevel, sourceCommonDirRaw));
+    const returnedCommonDir = normalizeComparableCwd(path.isAbsolute(returnedCommonDirRaw) ? returnedCommonDirRaw : path.resolve(worktreePath, returnedCommonDirRaw));
+    if (returnedCommonDir !== sourceCommonDir)
+      throw new Error("Worktrunk provisioning returned a worktree for a different repository");
+    const returnedBranch = (await tx.gitChecked(worktreePath, ["symbolic-ref", "--quiet", "--short", "HEAD"])).trim();
+    if (returnedBranch !== naming.requestedBranch)
+      throw new Error("Worktrunk provisioning returned a worktree on a different branch");
+    const returnedHead = (await tx.gitChecked(worktreePath, ["rev-parse", "HEAD"])).trim();
+    if (returnedHead !== baseCommit)
+      throw new Error("Worktrunk provisioning returned a worktree at a different base commit");
+    const worktree = {
       path: worktreePath,
-      agentCwd,
-      branch,
+      agentCwd: cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath,
+      branch: naming.requestedBranch,
       index,
-      nodeModulesLinked,
-      syntheticPaths
+      nodeModulesLinked: false,
+      syntheticPaths: [],
+      provider: "worktrunk",
+      naming
     };
+    tx.validated(worktree);
+    return worktree;
   } catch (error) {
-    try {
-      runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]);
-    } catch {}
-    try {
-      runGitChecked(toplevel, ["branch", "-D", branch]);
-    } catch {}
+    tx.unknown(error);
     throw error;
   }
 }
 function removeSyntheticPath(worktree, syntheticPath) {
+  assertWorktreeMutationAllowed();
   const resolved = path.resolve(worktree.path, syntheticPath);
   const relative = path.relative(worktree.path, resolved);
   if (!relative || relative === "." || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
@@ -348,13 +883,16 @@ function parseNumstat(numstat) {
 function captureWorktreeDiff(setup, worktree, agent, patchPath) {
   removeSyntheticPathsBeforeDiff(worktree);
   runGitChecked(worktree.path, ["add", "-A"]);
-  const diffStat = runGitChecked(worktree.path, ["diff", "--cached", "--stat", setup.baseCommit]).trim();
-  const patch = runGitChecked(worktree.path, ["diff", "--cached", setup.baseCommit]);
-  const numstat = runGitChecked(worktree.path, ["diff", "--cached", "--numstat", setup.baseCommit]);
+  const diffStat = runGitChecked(worktree.path, ["diff", "--cached", ...MACHINE_DIFF_OPTIONS, "--stat", setup.baseCommit]).trim();
+  const patch = runGitChecked(worktree.path, ["diff", "--cached", ...MACHINE_PATCH_OPTIONS, setup.baseCommit]);
+  const numstat = runGitChecked(worktree.path, ["diff", "--cached", ...MACHINE_DIFF_OPTIONS, "--numstat", setup.baseCommit]);
   fs.writeFileSync(patchPath, patch, "utf-8");
   if (!patch.trim()) {
     return emptyDiff(worktree.index, agent, worktree.branch, patchPath);
   }
+  const validationError = validateWorktreePatch(worktree.path, patchPath);
+  if (validationError)
+    throw new Error(`captured worktree patch is not machine-applyable: ${validationError}`);
   const parsed = parseNumstat(numstat);
   return {
     index: worktree.index,
@@ -394,6 +932,8 @@ function cleanupSingleWorktree(setup, worktree, intent) {
       index: worktree.index,
       path: worktree.path,
       branch: worktree.branch,
+      ...worktree.provider ? { provider: worktree.provider } : {},
+      ...worktree.naming ? { naming: worktree.naming } : {},
       worktreeRemoved: false,
       branchRemoved: false,
       preserved: true,
@@ -407,13 +947,15 @@ function cleanupSingleWorktree(setup, worktree, intent) {
       errors.push(`synthetic path cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
     }
     const status = runGit(worktree.path, ["status", "--porcelain"]);
-    const baseDiff = runGit(worktree.path, ["diff", "--quiet", setup.baseCommit, "--"]);
+    const baseDiff = runGit(worktree.path, ["diff", "--quiet", ...MACHINE_DIFF_OPTIONS, setup.baseCommit, "--"]);
     if (status.status !== 0 || baseDiff.status !== 0 && baseDiff.status !== 1) {
       const reason = status.status !== 0 ? status.stderr.trim() || status.stdout.trim() || "git status failed" : baseDiff.stderr.trim() || baseDiff.stdout.trim() || "git diff check failed";
       return {
         index: worktree.index,
         path: worktree.path,
         branch: worktree.branch,
+        ...worktree.provider ? { provider: worktree.provider } : {},
+        ...worktree.naming ? { naming: worktree.naming } : {},
         worktreeRemoved: false,
         branchRemoved: false,
         preserved: true,
@@ -424,13 +966,26 @@ function cleanupSingleWorktree(setup, worktree, intent) {
     const hasWork = status.stdout.trim().length > 0 || baseDiff.status === 1;
     if (hasWork && intent.kind === "preserve") {
       const captured = (intent.capturedDiffs ?? setup.capturedDiffs)?.find((diff) => diff.index === worktree.index);
-      const patchCaptured = captured !== undefined && captured.error === undefined && fs.existsSync(captured.patchPath) && fs.statSync(captured.patchPath).size > 0 && handoffRecordsPatch(intent.handoffManifestPath, captured.patchPath);
+      let patchValidationError;
+      let patchCaptured = false;
+      if (captured !== undefined && captured.error === undefined && fs.existsSync(captured.patchPath) && handoffRecordsPatch(intent.handoffManifestPath, captured.patchPath)) {
+        try {
+          if (fs.statSync(captured.patchPath).size > 0) {
+            patchValidationError = validateWorktreePatchRepresentsCurrentWorktree(worktree.path, setup.baseCommit, captured.patchPath);
+            patchCaptured = patchValidationError === undefined;
+          }
+        } catch (error) {
+          patchValidationError = error instanceof Error ? error.message : String(error);
+        }
+      }
       if (!patchCaptured) {
-        const reason = "worktree contains changes that are not represented by a captured handoff patch";
+        const reason = patchValidationError ? `captured handoff patch failed validation: ${patchValidationError}` : "worktree contains changes that are not represented by a captured handoff patch";
         return {
           index: worktree.index,
           path: worktree.path,
           branch: worktree.branch,
+          ...worktree.provider ? { provider: worktree.provider } : {},
+          ...worktree.naming ? { naming: worktree.naming } : {},
           worktreeRemoved: false,
           branchRemoved: false,
           preserved: true,
@@ -448,6 +1003,8 @@ function cleanupSingleWorktree(setup, worktree, intent) {
           index: worktree.index,
           path: worktree.path,
           branch: worktree.branch,
+          ...worktree.provider ? { provider: worktree.provider } : {},
+          ...worktree.naming ? { naming: worktree.naming } : {},
           worktreeRemoved: false,
           branchRemoved: false,
           preserved: true,
@@ -475,6 +1032,8 @@ function cleanupSingleWorktree(setup, worktree, intent) {
     index: worktree.index,
     path: worktree.path,
     branch: worktree.branch,
+    ...worktree.provider ? { provider: worktree.provider } : {},
+    ...worktree.naming ? { naming: worktree.naming } : {},
     worktreeRemoved,
     branchRemoved,
     ...errors.length ? { errors } : {}
@@ -483,46 +1042,159 @@ function cleanupSingleWorktree(setup, worktree, intent) {
 function hasWorktreeChanges(diff) {
   return diff.filesChanged > 0 || diff.insertions > 0 || diff.deletions > 0 || diff.diffStat.trim().length > 0;
 }
-export function createWorktrees(cwd, runId, count, options) {
-  const repo = resolveRepoState(cwd);
-  const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
-  const baseDir = resolveWorktreeBaseDir(options?.baseDir, repo.toplevel);
-  const plannedSetup = {
-    cwd: repo.toplevel,
-    baseCommit: repo.baseCommit,
-    worktrees: Array.from({ length: count }, (_, index) => {
-      const worktreePath = buildWorktreePath(baseDir, runId, index);
-      return {
-        path: worktreePath,
-        agentCwd: repo.cwdRelative ? path.join(worktreePath, repo.cwdRelative) : worktreePath,
-        branch: buildWorktreeBranch(runId, index),
-        index,
-        nodeModulesLinked: false,
-        syntheticPaths: []
-      };
-    })
+async function compensateSetup(tx) {
+  const { setup, attempts } = tx.progress;
+  const report = { state: "partial", tasks: [], pruned: false, errors: [] };
+  tx.progress.cleanup = report;
+  tx.progress.phase = "rollback";
+  const git = async (args, acceptedExitCodes = [0]) => {
+    if (setupPoison)
+      throw new Error(setupPoison);
+    tx.progress.command = { command: "git", args: ["-C", setup.cwd, ...args] };
+    const result = await runSetupCommand("git", tx.progress.command.args, {
+      deadlineAt: tx.options.deadlineAt,
+      acceptedExitCodes,
+      onSpawn: (process) => {
+        Object.assign(tx.progress.command, process);
+        tx.publish();
+      }
+    });
+    const { stdout: _stdout, stdoutBuffer: _stdoutBuffer, stderr: _stderr, ...metadata } = result;
+    tx.progress.command.result = metadata;
+    if (result.processTree?.state === "unknown")
+      tx.unknown(result.error ?? "Rollback command settlement unverified");
+    tx.publish();
+    if (result.error || result.status === null || !acceptedExitCodes.includes(result.status))
+      throw result.error ?? new Error(result.stderr.trim() || "Rollback command failed");
+    return result;
   };
-  options?.beforeCreate?.(plannedSetup);
-  const worktrees = [];
+  for (const attempt of [...attempts].reverse()) {
+    if (!attempt.path) {
+      tx.unknown(`Allocation path unconfirmed for branch ${attempt.branch}`);
+      report.errors.push(tx.progress.unknown);
+      continue;
+    }
+    const known = setup.worktrees.find((worktree) => worktree.index === attempt.index);
+    const task = {
+      index: attempt.index,
+      path: attempt.path,
+      branch: attempt.branch,
+      provider: known?.provider ?? "native",
+      naming: known?.naming,
+      worktreeRemoved: false,
+      branchRemoved: false
+    };
+    report.tasks.push(task);
+    try {
+      if (normalizeComparableCwd(attempt.path) === normalizeComparableCwd(setup.cwd))
+        throw new Error("Refusing source-checkout removal");
+      if (attempt.validated) {
+        await git(["worktree", "remove", "--force", attempt.path]);
+        task.worktreeRemoved = true;
+      } else {
+        const listed = (await git(["worktree", "list", "--porcelain"])).stdout;
+        const entry = listed.split(`
+
+`).find((block) => block.split(`
+`).includes(`worktree ${attempt.path}`));
+        if (entry) {
+          if (!entry.split(`
+`).includes(`branch refs/heads/${attempt.branch}`)) {
+            tx.unknown("Partial allocation ownership mismatch");
+            throw new Error(tx.progress.unknown);
+          }
+          await git(["worktree", "remove", "--force", attempt.path]);
+        } else if (fs.existsSync(attempt.path)) {
+          tx.unknown("Unregistered partial allocation retained");
+          throw new Error(tx.progress.unknown);
+        }
+        task.worktreeRemoved = true;
+      }
+      const branch = await git(["show-ref", "--verify", "--quiet", `refs/heads/${attempt.branch}`], [0, 1]);
+      if (branch.status === 0)
+        await git(["branch", "-D", attempt.branch]);
+      task.branchRemoved = true;
+    } catch (error) {
+      task.preserved = true;
+      task.errors = [error instanceof Error ? error.message : String(error)];
+    }
+  }
   try {
-    for (let index = 0;index < count; index++) {
-      worktrees.push(createSingleWorktree(repo.toplevel, repo.cwdRelative, runId, index, repo.baseCommit, setupHook, options?.agents?.[index], baseDir));
+    if (attempts.length > 0) {
+      await git(["worktree", "prune"]);
+      report.pruned = true;
+    }
+  } catch (error) {
+    report.errors.push(error instanceof Error ? error.message : String(error));
+  }
+  if (tx.progress.unknown)
+    report.errors.push(tx.progress.unknown);
+  report.tasks.sort((a, b) => a.index - b.index);
+  if (!setupPoison && (report.pruned || attempts.length === 0) && report.tasks.every((task) => task.worktreeRemoved && task.branchRemoved) && !report.errors.length)
+    report.state = "complete";
+  return report;
+}
+async function allocateWorktrees(tx, cwd, runId, count) {
+  const options = tx.options;
+  tx.check();
+  if (!Number.isSafeInteger(count) || count < 0)
+    throw new Error("worktree count must be a non-negative integer");
+  const repo = await resolveRepoState(tx, cwd, options?.baseRef);
+  tx.progress.setup.cwd = repo.toplevel;
+  tx.progress.setup.baseCommit = repo.baseCommit;
+  const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
+  const provider = await resolveSetupProvider(tx, options?.provider, options?.baseDir, repo.toplevel);
+  const branchPrefix = normalizeWorktreeBranchPrefix(options?.branchPrefix);
+  const dedicatedRoot = provider === "native" ? resolveWorktreeDedicatedRoot(options?.baseDir, repo.toplevel, (options?.provider ?? DEFAULT_WORKTREE_PROVIDER) === "auto") : undefined;
+  const worktrees = tx.progress.setup.worktrees;
+  try {
+    if (provider === "native") {
+      for (let index = 0;index < count; index++) {
+        worktrees[index] = await createNativeWorktree(tx, repo.toplevel, repo.cwdRelative, runId, index, repo.baseCommit, setupHook, options?.agents?.[index], dedicatedRoot, options?.labels, options?.tasks, branchPrefix);
+      }
+    } else {
+      for (let index = 0;index < count; index++) {
+        await createWorktrunkWorktree(tx, repo.toplevel, repo.cwdRelative, runId, index, repo.baseCommit, options?.agents, options?.labels, options?.tasks, branchPrefix);
+      }
+      for (let index = 0;index < worktrees.length; index++) {
+        worktrees[index] = await finalizeCreatedWorktree(tx, repo.toplevel, repo.cwdRelative, runId, repo.baseCommit, setupHook, options?.agents?.[index], worktrees[index]);
+      }
     }
+    tx.check();
+    tx.progress.phase = "ready";
+    tx.publish();
+    tx.check();
+    return tx.progress.setup;
   } catch (error) {
-    cleanupWorktrees({
-      cwd: repo.toplevel,
-      worktrees,
-      baseCommit: repo.baseCommit
-    }, { kind: "setup-rollback" });
+    await compensateSetup(tx);
     throw error;
   }
-  return {
-    cwd: repo.toplevel,
-    worktrees,
-    baseCommit: repo.baseCommit
-  };
+}
+export async function createWorktrees(cwd, runId, count, options = {}) {
+  const tx = new SetupTransaction(cwd, options);
+  try {
+    return await withWorktreeTransaction(async () => {
+      setupActive = true;
+      try {
+        return await allocateWorktrees(tx, cwd, runId, count);
+      } finally {
+        setupActive = false;
+      }
+    });
+  } catch (error) {
+    if (setupPoison)
+      tx.progress.unknown ??= setupPoison;
+    tx.progress.cleanup ??= { state: tx.progress.unknown ? "partial" : "complete", tasks: [], pruned: false, errors: tx.progress.unknown ? [tx.progress.unknown] : [] };
+    try {
+      tx.publish();
+    } catch (publicationError) {
+      tx.progress.cleanup?.errors?.push(`Recovery publication failed: ${String(publicationError)}`);
+    }
+    throw new WorktreeSetupError(error, tx.snapshot());
+  }
 }
 export function diffWorktrees(setup, agents, diffsDir) {
+  assertWorktreeMutationAllowed();
   try {
     fs.mkdirSync(diffsDir, { recursive: true });
   } catch {
@@ -544,6 +1216,7 @@ export function diffWorktrees(setup, agents, diffsDir) {
   return diffs;
 }
 export function cleanupWorktrees(setup, intent = { kind: "preserve", ...setup.capturedDiffs ? { capturedDiffs: setup.capturedDiffs } : {} }) {
+  assertWorktreeMutationAllowed();
   const tasks = [];
   for (let index = setup.worktrees.length - 1;index >= 0; index--) {
     tasks.push(cleanupSingleWorktree(setup, setup.worktrees[index], intent));