chainlesschain 0.162.185 → 0.162.187

package/src/harness/worktree-isolator.js

@@ -7,8 +7,17 @@
  * Feature-flag gated: WORKTREE_ISOLATION
  */
 
-import { existsSync, rmSync, symlinkSync, mkdirSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import {
+  existsSync,
+  lstatSync,
+  realpathSync,
+  rmdirSync,
+  symlinkSync,
+  unlinkSync,
+  mkdirSync,
+  rmSync,
+} from "node:fs";
+import { resolve, dirname, relative, isAbsolute, basename } from "node:path";
 import {
   isGitRepo,
   gitExec,
@@ -24,6 +33,347 @@ import {
 
 const WORKTREE_DIR = ".worktrees";
 
+function normalizeFilesystemPath(value) {
+  const absolute = resolve(value);
+  return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+}
+
+function nativeRealpath(value) {
+  return realpathSync.native ? realpathSync.native(value) : realpathSync(value);
+}
+
+/**
+ * Resolve filesystem aliases without requiring the complete target to exist.
+ * `realpathSync()` alone cannot validate a not-yet-created worktree, while a
+ * lexical `resolve()` treats macOS' `/var` and `/private/var` (or a repository
+ * directory symlink) as different locations. Resolve the deepest existing
+ * prefix physically, then append only the still-missing path segments.
+ */
+function canonicalExistingPrefixPath(value) {
+  let cursor = resolve(value);
+  const missing = [];
+
+  for (;;) {
+    try {
+      return resolve(nativeRealpath(cursor), ...missing);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      const parent = dirname(cursor);
+      if (parent === cursor) throw error;
+      missing.unshift(basename(cursor));
+      cursor = parent;
+    }
+  }
+}
+
+function sameFilesystemPath(left, right) {
+  return (
+    normalizeFilesystemPath(canonicalExistingPrefixPath(left)) ===
+    normalizeFilesystemPath(canonicalExistingPrefixPath(right))
+  );
+}
+
+function assertNotSymlink(target, label) {
+  let stat;
+  try {
+    stat = lstatSync(target);
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(`${label} must not be a symbolic link or junction`);
+  }
+}
+
+function gitRepositoryIdentity(repoDir) {
+  const [topLevel, commonDir, ...unexpected] = gitExecArgs(
+    ["rev-parse", "--show-toplevel", "--git-common-dir"],
+    repoDir,
+  ).split(/\r?\n/);
+  if (!topLevel || !commonDir || unexpected.length > 0) {
+    throw new Error("unable to determine git repository identity");
+  }
+  const absoluteCommonDir = isAbsolute(commonDir)
+    ? commonDir
+    : resolve(repoDir, commonDir);
+  return {
+    topLevel,
+    topLevelIdentity: normalizeFilesystemPath(
+      canonicalExistingPrefixPath(topLevel),
+    ),
+    commonDirIdentity: normalizeFilesystemPath(
+      canonicalExistingPrefixPath(absoluteCommonDir),
+    ),
+  };
+}
+
+function assertSameGitRepository(repoDir, expectedCommonDir, expectedRoot) {
+  const identity = gitRepositoryIdentity(repoDir);
+  if (
+    identity.commonDirIdentity !== expectedCommonDir ||
+    identity.topLevelIdentity !== expectedRoot
+  ) {
+    throw new Error("worktree does not belong to the expected git repository");
+  }
+}
+
+function parseRegisteredWorktrees(output) {
+  const worktrees = [];
+  let current = {};
+
+  for (const line of output.split(/\r?\n/)) {
+    if (line.startsWith("worktree ")) {
+      if (current.path) worktrees.push(current);
+      current = { path: line.slice(9) };
+    } else if (line.startsWith("HEAD ")) {
+      current.head = line.slice(5);
+    } else if (line.startsWith("branch ")) {
+      current.branch = line.slice(7).replace("refs/heads/", "");
+    } else if (line === "bare") {
+      current.bare = true;
+    } else if (line === "detached") {
+      current.detached = true;
+    } else if (line === "locked") {
+      current.locked = true;
+    } else if (line.startsWith("locked ")) {
+      current.locked = true;
+      current.lockReason = line.slice(7);
+    } else if (line === "prunable") {
+      current.prunable = true;
+    } else if (line.startsWith("prunable ")) {
+      current.prunable = true;
+      current.prunableReason = line.slice(9);
+    }
+  }
+  if (current.path) worktrees.push(current);
+  return worktrees;
+}
+
+function readRegisteredWorktrees(repoDir) {
+  return parseRegisteredWorktrees(
+    gitExec("worktree list --porcelain", repoDir),
+  );
+}
+
+function repositoryManagementContext(repoDir) {
+  const repository = gitRepositoryIdentity(repoDir);
+  const registeredWorktrees = readRegisteredWorktrees(repoDir);
+  const invocationRegistered = registeredWorktrees.some((worktree) => {
+    if (worktree.bare || !worktree.path) return false;
+    try {
+      return (
+        normalizeFilesystemPath(canonicalExistingPrefixPath(worktree.path)) ===
+        repository.topLevelIdentity
+      );
+    } catch {
+      return false;
+    }
+  });
+  if (!invocationRegistered) {
+    throw new Error("repository checkout is not a registered git worktree");
+  }
+
+  // Git lists the primary checkout first. It is the sole management anchor:
+  // calls made from a linked worktree still create a sibling below the primary
+  // checkout's `.worktrees`, never below an arbitrary externally-located
+  // registered checkout.
+  const primary = registeredWorktrees[0];
+  if (!primary || primary.bare || !primary.path || !existsSync(primary.path)) {
+    throw new Error("primary git worktree is unavailable");
+  }
+  const primaryPath = canonicalExistingPrefixPath(primary.path);
+  const primaryIdentity = normalizeFilesystemPath(primaryPath);
+  assertSameGitRepository(
+    primary.path,
+    repository.commonDirIdentity,
+    primaryIdentity,
+  );
+
+  return {
+    repository,
+    registeredWorktrees,
+    primaryPath,
+    primaryIdentity,
+    managedRoot: resolve(primaryPath, WORKTREE_DIR),
+  };
+}
+
+function assertPhysicalDescendant(target, root, label) {
+  const fromRoot = relative(realpathSync(root), realpathSync(target));
+  if (
+    fromRoot === "" ||
+    isAbsolute(fromRoot) ||
+    fromRoot === ".." ||
+    fromRoot.startsWith(`..${pathSeparator()}`)
+  ) {
+    throw new Error(`${label} escapes its physical root`);
+  }
+}
+
+function assertNoSymlinkAncestors(root, target, label) {
+  const rootPath = resolve(root);
+  const targetPath = resolve(target);
+  const fromRoot = relative(rootPath, targetPath);
+  if (
+    isAbsolute(fromRoot) ||
+    fromRoot === ".." ||
+    fromRoot.startsWith(`..${pathSeparator()}`)
+  ) {
+    throw new Error(`${label} escapes its root`);
+  }
+  assertNotSymlink(rootPath, `${label} root`);
+  let cursor = rootPath;
+  for (const segment of fromRoot.split(/[\\/]/).filter(Boolean)) {
+    cursor = resolve(cursor, segment);
+    assertNotSymlink(cursor, label);
+  }
+}
+
+export function managedWorktreePath(repoDir, branchName) {
+  assertSafeGitRef(branchName, "branch name");
+  const { managedRoot } = repositoryManagementContext(repoDir);
+  return resolve(managedRoot, branchName.replace(/\//g, "-"));
+}
+
+/**
+ * Validate a path before it reaches Git cleanup or recursive filesystem
+ * removal. Managed worktrees are direct children of `<repo>/.worktrees` and,
+ * when a branch is known, have exactly the deterministic path created for it.
+ */
+export function assertManagedWorktreePath(
+  repoDir,
+  worktreePath,
+  { branchName = null } = {},
+) {
+  if (
+    typeof repoDir !== "string" ||
+    repoDir.length === 0 ||
+    typeof worktreePath !== "string" ||
+    worktreePath.length === 0 ||
+    worktreePath.includes("\0")
+  ) {
+    throw new TypeError("managed worktree path must be a non-empty string");
+  }
+  if (branchName != null) {
+    assertSafeGitRef(branchName, "branch name");
+  }
+
+  const context = repositoryManagementContext(repoDir);
+  const candidate = resolve(worktreePath);
+  const candidatePath = canonicalExistingPrefixPath(candidate);
+  const candidateIdentity = normalizeFilesystemPath(candidatePath);
+  const registered = context.registeredWorktrees.find((worktree) => {
+    try {
+      return sameFilesystemPath(worktree.path, candidatePath);
+    } catch {
+      return false;
+    }
+  });
+  const managedRootPath = canonicalExistingPrefixPath(context.managedRoot);
+  const managedRootIdentity = normalizeFilesystemPath(managedRootPath);
+  if (
+    candidateIdentity === context.primaryIdentity ||
+    candidateIdentity === context.repository.topLevelIdentity ||
+    normalizeFilesystemPath(dirname(candidateIdentity)) !==
+      normalizeFilesystemPath(managedRootIdentity)
+  ) {
+    throw new Error("refusing unmanaged worktree path");
+  }
+
+  if (registered && branchName && registered.branch !== branchName) {
+    throw new Error(
+      "registered worktree branch does not match cleanup request",
+    );
+  }
+  const effectiveBranch = branchName || registered?.branch || null;
+  if (effectiveBranch != null) {
+    assertSafeGitRef(effectiveBranch, "branch name");
+  }
+  if (
+    effectiveBranch != null &&
+    !sameFilesystemPath(
+      candidatePath,
+      resolve(managedRootPath, effectiveBranch.replace(/\//g, "-")),
+    )
+  ) {
+    throw new Error("managed worktree path does not match its branch");
+  }
+
+  if (registered && existsSync(candidatePath)) {
+    assertSameGitRepository(
+      candidatePath,
+      context.repository.commonDirIdentity,
+      candidateIdentity,
+    );
+  }
+
+  assertNotSymlink(context.managedRoot, "managed worktree root");
+  assertNotSymlink(candidate, "managed worktree");
+  assertNotSymlink(candidatePath, "managed worktree");
+  return candidatePath;
+}
+
+function pathSeparator() {
+  return process.platform === "win32" ? "\\" : "/";
+}
+
+function validateDependencySource(repoDir, entry) {
+  if (!existsSync(entry.source)) return false;
+  assertNoSymlinkAncestors(repoDir, entry.source, "dependency source");
+  if (!lstatSync(entry.source).isDirectory()) {
+    throw new Error(`dependency source is not a directory: ${entry.name}`);
+  }
+  assertPhysicalDescendant(entry.source, repoDir, "dependency source");
+  return true;
+}
+
+/**
+ * Remove only dependency links that this module previously planned and
+ * verified. Ordinary directories are never removed: if a link was replaced
+ * after creation, cleanup fails closed and leaves the worktree for inspection.
+ */
+export function removeManagedDependencyLinks(
+  repoDir,
+  worktreePath,
+  directories = [],
+) {
+  const plan = planSymlinkDirectories(directories, {
+    repoDir,
+    worktreePath,
+  });
+  const removed = [];
+  for (const entry of plan) {
+    let stat;
+    try {
+      stat = lstatSync(entry.dest);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+    assertNoSymlinkAncestors(
+      worktreePath,
+      dirname(entry.dest),
+      "dependency destination",
+    );
+    if (!stat.isSymbolicLink()) {
+      throw new Error(
+        `managed dependency link was replaced by a real path: ${entry.name}`,
+      );
+    }
+    if (
+      !validateDependencySource(repoDir, entry) ||
+      !sameFilesystemPath(realpathSync(entry.dest), realpathSync(entry.source))
+    ) {
+      throw new Error(`managed dependency link target changed: ${entry.name}`);
+    }
+    if (process.platform === "win32") rmdirSync(entry.dest);
+    else unlinkSync(entry.dest);
+    removed.push(entry.name);
+  }
+  return removed;
+}
+
 export function createWorktree(repoDir, branchName, baseBranch, options = {}) {
   assertSafeGitRef(branchName, "branch name");
   if (baseBranch) assertSafeGitRef(baseBranch, "base branch");
@@ -31,83 +381,323 @@ export function createWorktree(repoDir, branchName, baseBranch, options = {}) {
     throw new Error("Not a git repository");
   }
 
-  const worktreePath = resolve(
+  const worktreePath = assertManagedWorktreePath(
     repoDir,
-    WORKTREE_DIR,
-    branchName.replace(/\//g, "-"),
+    managedWorktreePath(repoDir, branchName),
+    { branchName },
   );
 
   if (existsSync(worktreePath)) {
     throw new Error(`Worktree already exists: ${worktreePath}`);
   }
 
-  const base = baseBranch || "HEAD";
-  gitExec(`worktree add "${worktreePath}" -b "${branchName}" ${base}`, repoDir);
-
-  const result = { path: worktreePath, branch: branchName };
-
-  // Sparse checkout: only materialize the packages this task needs. For a
-  // large monorepo this cuts worktree creation time and disk. Cone mode wants
-  // directory paths — our sparsePaths are package dirs. Fail-closed on unsafe
-  // paths (normalizeSparsePaths drops them); empty/absent → full checkout,
-  // byte-identical to the no-sparse path.
+  // Validate all task-controlled configuration before creating a branch. A bad
+  // plan must not leave an untracked worktree behind.
   const sparsePaths = normalizeSparsePaths(options.sparsePaths);
   if (sparsePaths) {
-    for (const p of sparsePaths) assertSafeGitPath(p, "sparse path");
-    gitExecArgs(["sparse-checkout", "set", ...sparsePaths], worktreePath);
-    result.sparsePaths = sparsePaths;
+    for (const item of sparsePaths) {
+      assertSafeGitPath(item, "sparse path");
+    }
   }
+  const symlinkPlan =
+    options.symlinkDirectories == null
+      ? []
+      : planSymlinkDirectories(options.symlinkDirectories, {
+          repoDir,
+          worktreePath,
+        });
+  const availableSymlinkPlan = symlinkPlan.filter((entry) =>
+    validateDependencySource(repoDir, entry),
+  );
+
+  const base = baseBranch || "HEAD";
+  gitExecArgs(
+    ["worktree", "add", worktreePath, "-b", branchName, base],
+    repoDir,
+  );
+
+  const result = { path: worktreePath, branch: branchName };
+  let createdBranchOid = null;
 
-  // Dependency reuse: link explicitly-approved directories (e.g. node_modules)
-  // from the main checkout into the worktree so the task does not reinstall.
-  // planSymlinkDirectories throws (fail-closed) on any junction/symlink escape.
-  if (options.symlinkDirectories != null) {
-    const plan = planSymlinkDirectories(options.symlinkDirectories, {
+  try {
+    createdBranchOid = gitExecArgs(
+      ["rev-parse", "--verify", `refs/heads/${branchName}^{commit}`],
       repoDir,
-      worktreePath,
-    });
-    const linked = [];
-    for (const { name, source, dest } of plan) {
-      if (!existsSync(source)) continue; // approved but absent — nothing to reuse
-      if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
-      mkdirSync(dirname(dest), { recursive: true });
-      // 'junction' on Windows needs no admin and works for directories;
-      // 'dir' elsewhere. Both resolve to an absolute source we validated.
-      symlinkSync(
-        source,
-        dest,
-        process.platform === "win32" ? "junction" : "dir",
+    )
+      .trim()
+      .toLowerCase();
+    assertManagedWorktreePath(repoDir, worktreePath, { branchName });
+    // Sparse checkout: only materialize the packages this task needs. For a
+    // large monorepo this cuts worktree creation time and disk. Cone mode wants
+    // directory paths — our sparsePaths are package dirs. Fail-closed on unsafe
+    // paths (normalizeSparsePaths drops them); empty/absent → full checkout,
+    // byte-identical to the no-sparse path.
+    if (sparsePaths) {
+      gitExecArgs(["sparse-checkout", "set", ...sparsePaths], worktreePath);
+      result.sparsePaths = sparsePaths;
+    }
+
+    // Dependency reuse: link explicitly-approved directories (e.g. node_modules)
+    // from the main checkout into the worktree so the task does not reinstall.
+    // planSymlinkDirectories throws (fail-closed) on any junction/symlink escape.
+    if (availableSymlinkPlan.length > 0) {
+      const linked = [];
+      for (const { name, source, dest } of availableSymlinkPlan) {
+        assertNoSymlinkAncestors(
+          worktreePath,
+          dirname(dest),
+          "dependency destination",
+        );
+        assertNotSymlink(dest, "dependency destination");
+        if (existsSync(dest)) {
+          throw new Error(
+            `dependency destination already exists; refusing replacement: ${name}`,
+          );
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        // 'junction' on Windows needs no admin and works for directories;
+        // 'dir' elsewhere. Both resolve to an absolute source we validated.
+        symlinkSync(
+          source,
+          dest,
+          process.platform === "win32" ? "junction" : "dir",
+        );
+        // Register immediately after creation. If verification below fails,
+        // rollback must know a reparse point exists and must never send an
+        // unrecorded junction into force-removal.
+        linked.push(name);
+        result.symlinkedDirectories = [...linked];
+        if (
+          !lstatSync(dest).isSymbolicLink() ||
+          !sameFilesystemPath(realpathSync(dest), realpathSync(source))
+        ) {
+          throw new Error(`dependency link verification failed: ${name}`);
+        }
+        assertManagedWorktreePath(repoDir, worktreePath, { branchName });
+      }
+    }
+  } catch (error) {
+    try {
+      removeManagedDependencyLinks(
+        repoDir,
+        worktreePath,
+        result.symlinkedDirectories || [],
       );
-      linked.push(name);
+      removeWorktree(repoDir, worktreePath, {
+        deleteBranch: true,
+        branchName,
+        ...(createdBranchOid ? { expectedBranchOid: createdBranchOid } : {}),
+        force: true,
+      });
+    } catch (cleanupError) {
+      error.cleanupError =
+        cleanupError instanceof Error
+          ? cleanupError.message
+          : String(cleanupError);
+      error.retainedWorktree = { path: worktreePath, branch: branchName };
     }
-    if (linked.length > 0) result.symlinkedDirectories = linked;
+    throw error;
   }
 
   return result;
 }
 
+function findRegisteredWorktreeByPath(worktrees, worktreePath) {
+  return (
+    worktrees.find((worktree) =>
+      sameFilesystemPath(worktree.path, worktreePath),
+    ) || null
+  );
+}
+
+function validateWorktreeRemovalTarget(repoDir, worktreePath, branchName) {
+  const validatedPath = assertManagedWorktreePath(repoDir, worktreePath, {
+    branchName,
+  });
+  const registered = findRegisteredWorktreeByPath(
+    readRegisteredWorktrees(repoDir),
+    validatedPath,
+  );
+  if (existsSync(validatedPath) && !registered) {
+    throw new Error("refusing to remove an unregistered worktree path");
+  }
+  if (registered?.locked) {
+    const reason = registered.lockReason ? `: ${registered.lockReason}` : "";
+    throw new Error(`refusing to remove a locked worktree${reason}`);
+  }
+  if (registered && branchName && registered.branch !== branchName) {
+    throw new Error(
+      "registered worktree branch does not match cleanup request",
+    );
+  }
+  return { validatedPath, registered };
+}
+
+function assertWorktreeCleanForRemoval(worktreePath) {
+  const status = gitExecArgs(
+    [
+      "status",
+      "--porcelain=v1",
+      "--untracked-files=all",
+      "--ignored=matching",
+      "--ignore-submodules=none",
+    ],
+    worktreePath,
+  );
+  if (status.trim() !== "") {
+    throw new Error(
+      "refusing to remove a worktree with tracked, untracked, or ignored files",
+    );
+  }
+}
+
+function readLocalBranchOid(repoDir, branch) {
+  assertSafeGitRef(branch, "branch name");
+  const ref = `refs/heads/${branch}`;
+  const output = gitExecArgs(
+    ["for-each-ref", "--format=%(refname) %(objectname)", ref],
+    repoDir,
+  ).trim();
+  if (output === "") return null;
+  const prefix = `${ref} `;
+  const exactMatches = output
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith(prefix));
+  if (
+    exactMatches.length !== 1 ||
+    !/^[a-f0-9]{40,64}$/i.test(exactMatches[0].slice(prefix.length))
+  ) {
+    if (exactMatches.length === 0) return null;
+    throw new Error(`unable to verify worktree branch: ${branch}`);
+  }
+  return exactMatches[0].slice(prefix.length).toLowerCase();
+}
+
 export function removeWorktree(repoDir, worktreePath, options = {}) {
   const deleteBranch = options.deleteBranch !== false;
+  const force = options.force === true;
+  const expectedBranchOid =
+    options.expectedBranchOid == null
+      ? null
+      : String(options.expectedBranchOid).toLowerCase();
+  if (
+    expectedBranchOid != null &&
+    !/^[a-f0-9]{40,64}$/i.test(expectedBranchOid)
+  ) {
+    throw new TypeError("expected worktree branch OID is invalid");
+  }
+  const initialTarget = validateWorktreeRemovalTarget(
+    repoDir,
+    worktreePath,
+    options.branchName || null,
+  );
+  const validatedPath = initialTarget.validatedPath;
+  const registered = initialTarget.registered;
+  const initiallySettled = registered == null && !existsSync(validatedPath);
+  if (!force && existsSync(validatedPath)) {
+    assertWorktreeCleanForRemoval(validatedPath);
+  }
 
-  let branch = null;
+  let branch =
+    registered?.branch ||
+    (deleteBranch && expectedBranchOid && options.branchName
+      ? options.branchName
+      : null);
   if (deleteBranch) {
     try {
-      branch = gitExecArgs(
-        ["rev-parse", "--abbrev-ref", "HEAD"],
-        worktreePath,
-      ).trim();
+      branch =
+        branch ||
+        gitExecArgs(
+          ["rev-parse", "--abbrev-ref", "HEAD"],
+          validatedPath,
+        ).trim();
     } catch (_e) {
       // Can't determine branch, skip branch deletion.
     }
   }
+  let removalBranchOid = expectedBranchOid;
+  if (branch && (deleteBranch || removalBranchOid != null)) {
+    const currentBranchOid = readLocalBranchOid(repoDir, branch);
+    if (currentBranchOid == null) {
+      if (initiallySettled) return;
+      throw new Error(`Failed to verify worktree branch: ${branch}`);
+    }
+    removalBranchOid = removalBranchOid || currentBranchOid;
+    if (currentBranchOid !== removalBranchOid) {
+      throw new Error(
+        `refusing to remove worktree after branch moved: ${branch}`,
+      );
+    }
+  }
 
-  try {
-    gitExec(`worktree remove "${worktreePath}" --force`, repoDir);
-  } catch (_e) {
-    if (existsSync(worktreePath)) {
-      rmSync(worktreePath, { recursive: true, force: true });
+  // Missing + unregistered is the idempotent recovery state after a crash
+  // between physical removal and snapshot settlement.
+  if (registered || existsSync(validatedPath)) {
+    if (!force && existsSync(validatedPath)) {
+      assertWorktreeCleanForRemoval(validatedPath);
+    }
+    if (branch && removalBranchOid) {
+      const currentBranchOid = readLocalBranchOid(repoDir, branch);
+      if (currentBranchOid == null) {
+        throw new Error(`Failed to verify worktree branch: ${branch}`);
+      }
+      if (currentBranchOid !== removalBranchOid) {
+        throw new Error(
+          `refusing to remove worktree after branch moved: ${branch}`,
+        );
+      }
+    }
+
+    // Re-read every path/registry/branch/lock authority as the final operation
+    // before deletion. In particular, persisted metadata is not deletion
+    // authority if it disappeared from Git's registry, became locked, or
+    // stopped identifying the same common repository.
+    const currentTarget = validateWorktreeRemovalTarget(
+      repoDir,
+      validatedPath,
+      options.branchName || registered?.branch || null,
+    );
+    const currentPath = currentTarget.validatedPath;
+    if (currentTarget.registered || existsSync(currentPath)) {
+      try {
+        if (process.platform === "win32") {
+          // Git for Windows follows directory junctions during
+          // `worktree remove --force`. Node 22's rmSync unlinks reparse points
+          // without traversing their targets, so remove the already-canonical,
+          // physically-verified checkout and then settle only stale, unlocked
+          // registry metadata. Exact-path verification below remains
+          // authoritative.
+          if (existsSync(currentPath)) {
+            rmSync(currentPath, {
+              recursive: true,
+              force: true,
+              maxRetries: 2,
+              retryDelay: 100,
+            });
+          }
+          gitExecArgs(["worktree", "prune", "--expire", "now"], repoDir);
+        } else {
+          gitExecArgs(
+            ["worktree", "remove", currentPath, ...(force ? ["--force"] : [])],
+            repoDir,
+          );
+        }
+      } catch (error) {
+        throw new Error(`Failed to remove managed worktree: ${validatedPath}`, {
+          cause: error,
+        });
+      }
+
+      const remaining = findRegisteredWorktreeByPath(
+        readRegisteredWorktrees(repoDir),
+        currentPath,
+      );
+      if (remaining || existsSync(currentPath)) {
+        throw new Error(
+          `Failed to verify managed worktree removal: ${validatedPath}`,
+        );
+      }
     }
-    gitExec("worktree prune", repoDir);
   }
 
   if (
@@ -118,9 +708,24 @@ export function removeWorktree(repoDir, worktreePath, options = {}) {
     !branch.startsWith("master")
   ) {
     try {
-      gitExec(`branch -D "${branch}"`, repoDir);
-    } catch (_e) {
-      // Branch might already be deleted.
+      assertSafeGitRef(branch, "branch name");
+      const currentBranchOid = readLocalBranchOid(repoDir, branch);
+      if (currentBranchOid == null) return;
+      if (removalBranchOid && currentBranchOid !== removalBranchOid) {
+        throw new Error(`worktree branch moved during removal: ${branch}`);
+      }
+      gitExecArgs(["branch", "-D", branch], repoDir);
+    } catch (error) {
+      try {
+        if (readLocalBranchOid(repoDir, branch) == null) return;
+      } catch (probeError) {
+        throw new Error(`Failed to verify worktree branch: ${branch}`, {
+          cause: probeError,
+        });
+      }
+      throw new Error(`Failed to delete worktree branch: ${branch}`, {
+        cause: error,
+      });
     }
   }
 }
@@ -129,25 +734,7 @@ export function listWorktrees(repoDir) {
   if (!isGitRepo(repoDir)) return [];
 
   try {
-    const output = gitExec("worktree list --porcelain", repoDir);
-    const worktrees = [];
-    let current = {};
-
-    for (const line of output.split("\n")) {
-      if (line.startsWith("worktree ")) {
-        if (current.path) worktrees.push(current);
-        current = { path: line.slice(9) };
-      } else if (line.startsWith("HEAD ")) {
-        current.head = line.slice(5);
-      } else if (line.startsWith("branch ")) {
-        current.branch = line.slice(7).replace("refs/heads/", "");
-      } else if (line === "bare") {
-        current.bare = true;
-      }
-    }
-    if (current.path) worktrees.push(current);
-
-    return worktrees;
+    return readRegisteredWorktrees(repoDir);
   } catch (_e) {
     return [];
   }
@@ -157,7 +744,7 @@ export function pruneWorktrees(repoDir) {
   if (!isGitRepo(repoDir)) return 0;
 
   const before = listWorktrees(repoDir).length;
-  gitExec("worktree prune", repoDir);
+  gitExecArgs(["worktree", "prune"], repoDir);
   const after = listWorktrees(repoDir).length;
   return before - after;
 }
@@ -167,12 +754,8 @@ export async function isolateTask(repoDir, taskId, fn, options = {}) {
   // options (large-monorepo): { sparsePaths, symlinkDirectories } forwarded to
   // createWorktree so an isolated task only materializes the packages it needs
   // and reuses approved dep dirs. Empty/absent → full checkout (byte-identical).
-  const { path: worktreePath } = createWorktree(
-    repoDir,
-    branchName,
-    undefined,
-    options || {},
-  );
+  const created = createWorktree(repoDir, branchName, undefined, options || {});
+  const worktreePath = created.path;
 
   try {
     const result = await fn(worktreePath);
@@ -187,8 +770,14 @@ export async function isolateTask(repoDir, taskId, fn, options = {}) {
   } finally {
     try {
       const hasCommits = _hasBranchCommits(repoDir, branchName);
+      removeManagedDependencyLinks(
+        repoDir,
+        worktreePath,
+        created.symlinkedDirectories || [],
+      );
       removeWorktree(repoDir, worktreePath, {
         deleteBranch: !hasCommits,
+        force: false,
       });
     } catch (_e) {
       // Best-effort cleanup.
@@ -290,7 +879,10 @@ export function cleanupAgentWorktrees(repoDir, options = {}) {
         if (!decision.safeToRemove) continue; // keep work we cannot safely lose
       }
       try {
-        removeWorktree(repoDir, wt.path, { deleteBranch: true });
+        removeWorktree(repoDir, wt.path, {
+          deleteBranch: true,
+          force,
+        });
         cleaned++;
       } catch (_e) {
         // Skip if cleanup fails.