clawt 3.9.11 → 3.9.12

package/README.md

@@ -159,6 +159,8 @@ clawt validate -b <branch> -r "pnpm test & pnpm build"  # Run multiple commands
 
 Supports incremental mode: when re-validating the same branch, you can view incremental diffs between validations via `git diff`.
 
+Automatically removes external symlinks (e.g., `node_modules` links to the main worktree) before detecting changes — these symlinks, typically created by AI Agents, can cause patch apply failures.
+
 When patch apply fails (target branch diverges too much from main), it automatically prompts whether to run `sync` to synchronize the main branch to the target worktree — no manual action needed.
 
 The `-r, --run` option auto-executes a specified command in the main worktree after successful validation (e.g., tests, builds). Command failure does not affect the validation result. Without `-r`, it automatically reads from the project's `validateRunCommand` config (configurable via `clawt init show`). Use `&` to separate multiple commands for parallel execution:

package/README.zh-CN.md

@@ -159,6 +159,8 @@ clawt validate -b <branch> -r "pnpm test & pnpm build"  # 并行执行多个命
 
 支持增量模式：再次 validate 同一分支时，可通过 `git diff` 查看两次之间的增量差异。
 
+执行前会自动清理目标 worktree 中指向外部的软链接（如 AI Agent 创建的 `node_modules` 链接），这些软链接会导致 patch apply 失败。
+
 当 patch apply 失败（目标分支与主分支差异过大）时，会自动询问是否执行 `sync` 同步主分支到目标 worktree，无需手动操作。
 
 `-r, --run` 选项可在 validate 成功后自动在主 worktree 中执行指定命令（如测试、构建等），命令执行失败不影响 validate 结果。不传 `-r` 时会自动从项目配置的 `validateRunCommand` 读取（可通过 `clawt init show` 设置）。支持用 `&` 分隔多个命令并行执行：

package/dist/index.js

@@ -269,6 +269,8 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   VALIDATE_RUN_ERROR_COPIED: "\u2702 \u9519\u8BEF\u4FE1\u606F\u5DF2\u590D\u5236\u5230\u526A\u8D34\u677F",
   /** 剪贴板复制失败提示 */
   VALIDATE_RUN_ERROR_COPY_FAILED: "\u26A0 \u9519\u8BEF\u4FE1\u606F\u590D\u5236\u5230\u526A\u8D34\u677F\u5931\u8D25",
+  /** 检测到外部软链接警告 */
+  VALIDATE_EXTERNAL_SYMLINKS_FOUND: (count) => `\u26A0 \u68C0\u6D4B\u5230 ${count} \u4E2A\u6307\u5411 worktree \u5916\u90E8\u7684\u8F6F\u94FE\u63A5\uFF08\u53EF\u80FD\u7531 AI Agent \u521B\u5EFA\uFF09\uFF0C\u5DF2\u81EA\u52A8\u79FB\u9664`,
   /** 单命令（含 && 链）剪贴板错误格式 */
   VALIDATE_CLIPBOARD_SINGLE_ERROR: (command, stderr) => `${command} \u6307\u4EE4\u6267\u884C\u51FA\u9519\uFF0C\u9519\u8BEF\u4FE1\u606F\uFF1A
 ${stderr}`,
@@ -1166,7 +1168,7 @@ function parseParallelCommands(commandString) {
   return parts.map((part) => part.replace(new RegExp(placeholder, "g"), "&&").trim()).filter((part) => part.length > 0);
 }
 function spawnWithStderrCapture(command, options) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const child = spawn(command, {
       cwd: options?.cwd,
       stdio: ["inherit", "inherit", "pipe"],
@@ -1178,14 +1180,14 @@ function spawnWithStderrCapture(command, options) {
       stderrChunks.push(chunk);
     });
     child.on("error", (err) => {
-      resolve4({
+      resolve5({
         exitCode: 1,
         error: err.message,
         stderr: Buffer.concat(stderrChunks).toString("utf-8")
       });
     });
     child.on("close", (code) => {
-      resolve4({
+      resolve5({
         exitCode: code ?? 1,
         stderr: Buffer.concat(stderrChunks).toString("utf-8")
       });
@@ -1526,14 +1528,14 @@ function confirmAction(question, nonInteractiveDefault = true) {
   if (isNonInteractive()) {
     return Promise.resolve(nonInteractiveDefault);
   }
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const rl = createInterface({
       input: process.stdin,
       output: process.stdout
     });
     rl.question(`${question} (y/N) `, (answer) => {
       rl.close();
-      resolve4(answer.toLowerCase() === "y");
+      resolve5(answer.toLowerCase() === "y");
     });
   });
 }
@@ -2124,6 +2126,42 @@ function getWorktreeStatus(worktree) {
   }
 }
 
+// src/utils/symlink-guard.ts
+import { readdirSync as readdirSync3, lstatSync, unlinkSync, readlinkSync } from "fs";
+import { join as join6, relative, isAbsolute as isAbsolute2, resolve } from "path";
+function isExternalSymlink(linkPath, worktreeRoot) {
+  try {
+    const target = readlinkSync(linkPath);
+    const resolvedTarget = isAbsolute2(target) ? target : resolve(worktreeRoot, target);
+    const relativePath = relative(worktreeRoot, resolvedTarget);
+    return relativePath.startsWith("..") || isAbsolute2(relativePath);
+  } catch {
+    return false;
+  }
+}
+function removeExternalSymlinks(dir) {
+  const removed = [];
+  try {
+    const entries = readdirSync3(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isSymbolicLink()) continue;
+      const fullPath = join6(dir, entry.name);
+      if (!isExternalSymlink(fullPath, dir)) continue;
+      try {
+        const stat = lstatSync(fullPath);
+        if (!stat.isSymbolicLink()) continue;
+        unlinkSync(fullPath);
+        removed.push(fullPath);
+        logger.info(`\u5DF2\u79FB\u9664\u5916\u90E8\u8F6F\u94FE\u63A5: ${fullPath}`);
+      } catch (error) {
+        logger.warn(`\u79FB\u9664\u5916\u90E8\u8F6F\u94FE\u63A5\u5931\u8D25: ${fullPath} - ${error}`);
+      }
+    }
+  } catch {
+  }
+  return removed;
+}
+
 // src/utils/prompt.ts
 import Enquirer2 from "enquirer";
 async function promptCommitMessage(promptMessage, nonInteractiveErrorMessage) {
@@ -2142,8 +2180,8 @@ async function promptCommitMessage(promptMessage, nonInteractiveErrorMessage) {
 
 // src/utils/claude.ts
 import { spawnSync as spawnSync3 } from "child_process";
-import { existsSync as existsSync7, readdirSync as readdirSync3 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync7, readdirSync as readdirSync4 } from "fs";
+import { join as join7 } from "path";
 
 // src/utils/terminal.ts
 import { execFileSync as execFileSync3 } from "child_process";
@@ -2287,11 +2325,11 @@ function encodeClaudeProjectPath(absolutePath) {
 }
 function hasClaudeSessionHistory(worktreePath) {
   const encodedName = encodeClaudeProjectPath(worktreePath);
-  const projectDir = join6(CLAUDE_PROJECTS_DIR, encodedName);
+  const projectDir = join7(CLAUDE_PROJECTS_DIR, encodedName);
   if (!existsSync7(projectDir)) {
     return false;
   }
-  const entries = readdirSync3(projectDir);
+  const entries = readdirSync4(projectDir);
   return entries.some((entry) => entry.endsWith(".jsonl"));
 }
 function launchInteractiveClaude(worktree, options = {}) {
@@ -2341,16 +2379,16 @@ function launchInteractiveClaudeInNewTerminal(worktree, hasPreviousSession) {
 }
 
 // src/utils/validate-snapshot.ts
-import { join as join7 } from "path";
-import { existsSync as existsSync8, readFileSync as readFileSync3, writeFileSync as writeFileSync3, unlinkSync, readdirSync as readdirSync4, rmdirSync as rmdirSync2, statSync as statSync2 } from "fs";
+import { join as join8 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync3, writeFileSync as writeFileSync3, unlinkSync as unlinkSync2, readdirSync as readdirSync5, rmdirSync as rmdirSync2, statSync as statSync2 } from "fs";
 function getSnapshotPath(projectName, branchName) {
-  return join7(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.tree`);
+  return join8(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.tree`);
 }
 function getSnapshotHeadPath(projectName, branchName) {
-  return join7(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
+  return join8(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
 }
 function getSnapshotStagedPath(projectName, branchName) {
-  return join7(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.staged`);
+  return join8(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.staged`);
 }
 function hasSnapshot(projectName, branchName) {
   return existsSync8(getSnapshotPath(projectName, branchName));
@@ -2372,7 +2410,7 @@ function readSnapshot(projectName, branchName) {
   return { treeHash, headCommitHash, stagedTreeHash };
 }
 function writeSnapshot(projectName, branchName, treeHash, headCommitHash, stagedTreeHash) {
-  const snapshotDir = join7(VALIDATE_SNAPSHOTS_DIR, projectName);
+  const snapshotDir = join8(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
   if (treeHash !== void 0) {
     writeFileSync3(getSnapshotPath(projectName, branchName), treeHash, "utf-8");
@@ -2390,34 +2428,34 @@ function removeSnapshot(projectName, branchName) {
   const headPath = getSnapshotHeadPath(projectName, branchName);
   const stagedPath = getSnapshotStagedPath(projectName, branchName);
   if (existsSync8(snapshotPath)) {
-    unlinkSync(snapshotPath);
+    unlinkSync2(snapshotPath);
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${snapshotPath}`);
   }
   if (existsSync8(headPath)) {
-    unlinkSync(headPath);
+    unlinkSync2(headPath);
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${headPath}`);
   }
   if (existsSync8(stagedPath)) {
-    unlinkSync(stagedPath);
+    unlinkSync2(stagedPath);
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${stagedPath}`);
   }
 }
 function getProjectSnapshotBranches(projectName) {
-  const projectDir = join7(VALIDATE_SNAPSHOTS_DIR, projectName);
+  const projectDir = join8(VALIDATE_SNAPSHOTS_DIR, projectName);
   if (!existsSync8(projectDir)) {
     return [];
   }
-  const files = readdirSync4(projectDir);
+  const files = readdirSync5(projectDir);
   return files.filter((f) => f.endsWith(".tree")).map((f) => f.replace(/\.tree$/, ""));
 }
 function removeProjectSnapshots(projectName) {
-  const projectDir = join7(VALIDATE_SNAPSHOTS_DIR, projectName);
+  const projectDir = join8(VALIDATE_SNAPSHOTS_DIR, projectName);
   if (!existsSync8(projectDir)) {
     return;
   }
-  const files = readdirSync4(projectDir);
+  const files = readdirSync5(projectDir);
   for (const file of files) {
-    unlinkSync(join7(projectDir, file));
+    unlinkSync2(join8(projectDir, file));
   }
   try {
     rmdirSync2(projectDir);
@@ -2944,7 +2982,7 @@ var ProgressRenderer = class {
 };
 
 // src/utils/task-file.ts
-import { resolve } from "path";
+import { resolve as resolve2 } from "path";
 import { existsSync as existsSync9, readFileSync as readFileSync4 } from "fs";
 var TASK_BLOCK_REGEX = /<!-- CLAWT-TASKS:START -->([\s\S]*?)<!-- CLAWT-TASKS:END -->/g;
 var BRANCH_LINE_REGEX = /^#\s*branch:\s*(.+)$/;
@@ -2990,7 +3028,7 @@ function parseTaskFile(content, options) {
   return entries;
 }
 function loadTaskFile(filePath, options) {
-  const absolutePath = resolve(filePath);
+  const absolutePath = resolve2(filePath);
   if (!existsSync9(absolutePath)) {
     throw new ClawtError(MESSAGES.TASK_FILE_NOT_FOUND(absolutePath));
   }
@@ -3123,7 +3161,7 @@ function executeClaudeTask(worktree, task, onActivity, continueSession) {
       stdio: ["ignore", "pipe", "pipe"]
     }
   );
-  const promise = new Promise((resolve4) => {
+  const promise = new Promise((resolve5) => {
     let stderr = "";
     let finalResult = null;
     const lineBuffer = createLineBuffer();
@@ -3159,7 +3197,7 @@ function executeClaudeTask(worktree, task, onActivity, continueSession) {
       if (finalResult) {
         success = !finalResult.is_error;
       }
-      resolve4({
+      resolve5({
         task,
         branch: worktree.branch,
         worktreePath: worktree.path,
@@ -3169,7 +3207,7 @@ function executeClaudeTask(worktree, task, onActivity, continueSession) {
       });
     });
     child.on("error", (err) => {
-      resolve4({
+      resolve5({
         task,
         branch: worktree.branch,
         worktreePath: worktree.path,
@@ -3228,7 +3266,7 @@ async function executeWithConcurrency(worktrees, tasks, concurrency, renderer, s
   const results = new Array(total);
   let nextIndex = 0;
   let completedCount = 0;
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     function launchNext() {
       if (nextIndex >= total || isInterrupted()) return;
       const index = nextIndex;
@@ -3249,7 +3287,7 @@ async function executeWithConcurrency(worktrees, tasks, concurrency, renderer, s
         }
         launchNext();
         if (completedCount === total) {
-          resolve4(results);
+          resolve5(results);
         }
       });
     }
@@ -3309,11 +3347,11 @@ async function executeBatchTasks(worktrees, tasks, concurrency, continueFlags) {
     printWarning(MESSAGES.INTERRUPTED);
     killAllChildProcesses(childProcesses);
     await Promise.allSettled(childProcesses.map(
-      (cp) => new Promise((resolve4) => {
+      (cp) => new Promise((resolve5) => {
         if (cp.exitCode !== null) {
-          resolve4();
+          resolve5();
         } else {
-          cp.on("close", () => resolve4());
+          cp.on("close", () => resolve5());
         }
       })
     ));
@@ -3339,7 +3377,7 @@ async function executeBatchTasks(worktrees, tasks, concurrency, continueFlags) {
 
 // src/utils/dry-run.ts
 import chalk6 from "chalk";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 var DRY_RUN_TASK_DESC_MAX_LENGTH = 80;
 function truncateTaskDesc(task) {
   const oneLine = task.replace(/\n/g, " ").trim();
@@ -3367,7 +3405,7 @@ function printDryRunPreview(branchNames, tasks, concurrency) {
   let hasConflict = false;
   for (let i = 0; i < branchNames.length; i++) {
     const branch = branchNames[i];
-    const worktreePath = join8(projectDir, branch);
+    const worktreePath = join9(projectDir, branch);
     const exists = checkBranchExists(branch);
     if (exists) hasConflict = true;
     const indexLabel = `[${i + 1}/${branchNames.length}]`;
@@ -3559,7 +3597,7 @@ function isNewerVersion(latest, current) {
   return false;
 }
 function fetchLatestVersion() {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const req = request(NPM_REGISTRY_URL, { timeout: NPM_REGISTRY_TIMEOUT_MS }, (res) => {
       let data = "";
       res.on("data", (chunk) => {
@@ -3568,16 +3606,16 @@ function fetchLatestVersion() {
       res.on("end", () => {
         try {
           const parsed = JSON.parse(data);
-          resolve4(parsed.version ?? null);
+          resolve5(parsed.version ?? null);
         } catch {
-          resolve4(null);
+          resolve5(null);
         }
       });
     });
-    req.on("error", () => resolve4(null));
+    req.on("error", () => resolve5(null));
     req.on("timeout", () => {
       req.destroy();
-      resolve4(null);
+      resolve5(null);
     });
     req.end();
   });
@@ -4230,8 +4268,8 @@ var InteractivePanel = class {
       return;
     }
     this.stateManager.updateData(await this.collectStatusFn());
-    return new Promise((resolve4) => {
-      this.resolveStart = resolve4;
+    return new Promise((resolve5) => {
+      this.resolveStart = resolve5;
       this.initTerminal();
       this.keyboardController.start();
       this.startAutoRefresh();
@@ -4508,14 +4546,14 @@ var InteractivePanel = class {
    * @returns {Promise<void>} 用户按回车时 resolve
    */
   waitForEnter() {
-    return new Promise((resolve4) => {
+    return new Promise((resolve5) => {
       const rl = createInterface2({
         input: process.stdin,
         output: process.stdout
       });
       rl.once("line", () => {
         rl.close();
-        resolve4();
+        resolve5();
       });
     });
   }
@@ -4608,7 +4646,7 @@ async function handleMergeConflict(currentBranch, incomingBranch, cwd, autoFlag)
 // src/hooks/post-create.ts
 import { existsSync as existsSync10, accessSync, chmodSync, constants as fsConstants } from "fs";
 import { spawn as spawn2 } from "child_process";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 var POST_CREATE_SCRIPT_RELATIVE_PATH = ".clawt/postCreate.sh";
 function isExecutable(filePath) {
   try {
@@ -4640,7 +4678,7 @@ function resolvePostCreateHook() {
     }
   }
   const mainWorktreePath = getMainWorktreePath();
-  const scriptPath = join9(mainWorktreePath, POST_CREATE_SCRIPT_RELATIVE_PATH);
+  const scriptPath = join10(mainWorktreePath, POST_CREATE_SCRIPT_RELATIVE_PATH);
   if (existsSync10(scriptPath)) {
     if (!isExecutable(scriptPath)) {
       autoFixExecutablePermission(scriptPath);
@@ -4653,7 +4691,7 @@ function getSourceLabel(hook) {
   return hook.source === "projectConfig" ? "\u9879\u76EE\u914D\u7F6E (postCreate)" : ".clawt/postCreate.sh";
 }
 function executeOneHook(worktree, hook) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const result = {
       worktreePath: worktree.path,
       branch: worktree.branch,
@@ -4670,7 +4708,7 @@ function executeOneHook(worktree, hook) {
         result.success = false;
         result.error = err.message;
         logger.error(`postCreate hook \u5F02\u5E38: ${hook.command} @ ${worktree.path}: ${result.error}`);
-        resolve4(result);
+        resolve5(result);
       });
       child.on("close", (code) => {
         if (code !== null && code !== 0) {
@@ -4680,13 +4718,13 @@ function executeOneHook(worktree, hook) {
         } else {
           logger.info(`postCreate hook \u6210\u529F: ${hook.command} @ ${worktree.path}`);
         }
-        resolve4(result);
+        resolve5(result);
       });
     } catch (err) {
       result.success = false;
       result.error = err instanceof Error ? err.message : String(err);
       logger.error(`postCreate hook \u542F\u52A8\u5931\u8D25: ${hook.command} @ ${worktree.path}: ${result.error}`);
-      resolve4(result);
+      resolve5(result);
     }
   });
 }
@@ -5249,6 +5287,10 @@ async function handleValidate(options) {
   const branchName = worktree.branch;
   const targetWorktreePath = worktree.path;
   logger.info(`validate \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${branchName}`);
+  const removedSymlinks = removeExternalSymlinks(targetWorktreePath);
+  if (removedSymlinks.length > 0) {
+    printWarning(MESSAGES.VALIDATE_EXTERNAL_SYMLINKS_FOUND(removedSymlinks.length));
+  }
   const hasUncommitted = !isWorkingDirClean(targetWorktreePath);
   const hasCommitted = hasLocalCommits(branchName, mainWorktreePath);
   if (!hasUncommitted && !hasCommitted) {
@@ -5882,8 +5924,8 @@ function registerAliasCommand(program2) {
 }
 
 // src/commands/projects.ts
-import { existsSync as existsSync11, readdirSync as readdirSync5, statSync as statSync4 } from "fs";
-import { join as join10 } from "path";
+import { existsSync as existsSync11, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
+import { join as join11 } from "path";
 import chalk13 from "chalk";
 function registerProjectsCommand(program2) {
   program2.command("projects [name]").description("\u5C55\u793A\u6240\u6709\u9879\u76EE\u7684 worktree \u6982\u89C8\uFF0C\u6216\u67E5\u770B\u6307\u5B9A\u9879\u76EE\u7684 worktree \u8BE6\u60C5").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((name, options) => {
@@ -5907,7 +5949,7 @@ function handleProjectsOverview(json) {
   printProjectsOverviewAsText(result);
 }
 function handleProjectDetail(name, json) {
-  const projectDir = join10(WORKTREES_DIR, name);
+  const projectDir = join11(WORKTREES_DIR, name);
   if (!existsSync11(projectDir)) {
     printError(MESSAGES.PROJECTS_NOT_FOUND(name));
     process.exit(1);
@@ -5924,13 +5966,13 @@ function collectProjectsOverview() {
   if (!existsSync11(WORKTREES_DIR)) {
     return { projects: [], totalProjects: 0, totalDiskUsage: 0 };
   }
-  const entries = readdirSync5(WORKTREES_DIR, { withFileTypes: true });
+  const entries = readdirSync6(WORKTREES_DIR, { withFileTypes: true });
   const projects = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) {
       continue;
     }
-    const projectDir = join10(WORKTREES_DIR, entry.name);
+    const projectDir = join11(WORKTREES_DIR, entry.name);
     const overview = collectSingleProjectOverview(entry.name, projectDir);
     projects.push(overview);
   }
@@ -5943,11 +5985,11 @@ function collectProjectsOverview() {
   };
 }
 function collectSingleProjectOverview(name, projectDir) {
-  const subEntries = readdirSync5(projectDir, { withFileTypes: true });
+  const subEntries = readdirSync6(projectDir, { withFileTypes: true });
   const worktreeDirs = subEntries.filter((e) => e.isDirectory());
   const worktreeCount = worktreeDirs.length;
   const diskUsage = calculateDirSize(projectDir);
-  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join10(projectDir, e.name)));
+  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join11(projectDir, e.name)));
   return {
     name,
     worktreeCount,
@@ -5956,13 +5998,13 @@ function collectSingleProjectOverview(name, projectDir) {
   };
 }
 function collectProjectDetail(name, projectDir) {
-  const subEntries = readdirSync5(projectDir, { withFileTypes: true });
+  const subEntries = readdirSync6(projectDir, { withFileTypes: true });
   const worktrees = [];
   for (const entry of subEntries) {
     if (!entry.isDirectory()) {
       continue;
     }
-    const wtPath = join10(projectDir, entry.name);
+    const wtPath = join11(projectDir, entry.name);
     const detail = collectSingleWorktreeDetail(entry.name, wtPath);
     worktrees.push(detail);
   }
@@ -6062,7 +6104,7 @@ function printWorktreeDetailItem(wt) {
 
 // src/commands/completion.ts
 import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync13 } from "fs";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 import { homedir as homedir2 } from "os";
 
 // src/utils/completion-scripts.ts
@@ -6112,23 +6154,23 @@ compdef _clawt_completion clawt
 }
 
 // src/utils/completion-engine.ts
-import { existsSync as existsSync12, readdirSync as readdirSync6, statSync as statSync5 } from "fs";
-import { join as join11, dirname, basename as basename2 } from "path";
+import { existsSync as existsSync12, readdirSync as readdirSync7, statSync as statSync5 } from "fs";
+import { join as join12, dirname, basename as basename2 } from "path";
 function completeFilePath(partial) {
   const cwd = process.cwd();
   const hasDir = partial.includes("/");
-  const searchDir = hasDir ? join11(cwd, dirname(partial)) : cwd;
+  const searchDir = hasDir ? join12(cwd, dirname(partial)) : cwd;
   const prefix = hasDir ? basename2(partial) : partial;
   if (!existsSync12(searchDir)) {
     return [];
   }
-  const entries = readdirSync6(searchDir);
+  const entries = readdirSync7(searchDir);
   const results = [];
   const dirPrefix = hasDir ? dirname(partial) + "/" : "";
   for (const entry of entries) {
     if (!entry.startsWith(prefix)) continue;
     if (entry.startsWith(".")) continue;
-    const fullPath = join11(searchDir, entry);
+    const fullPath = join12(searchDir, entry);
     try {
       const stat = statSync5(fullPath);
       if (stat.isDirectory()) {
@@ -6234,14 +6276,14 @@ function installCompletions() {
   const home = homedir2();
   try {
     if (shell.includes("zsh")) {
-      const rcPath = resolve2(home, ".zshrc");
+      const rcPath = resolve3(home, ".zshrc");
       const script = `
 # clawt completion
 source <(clawt completion zsh)
 `;
       appendToFile(rcPath, script);
     } else if (shell.includes("bash")) {
-      const rcPath = resolve2(home, ".bashrc");
+      const rcPath = resolve3(home, ".bashrc");
       const script = `
 # clawt completion
 eval "$(clawt completion bash)"
@@ -6251,7 +6293,7 @@ eval "$(clawt completion bash)"
       printWarning(MESSAGES.COMPLETION_INSTALL_UNKNOWN_SHELL);
     }
   } catch (error) {
-    const filePath = shell.includes("zsh") ? resolve2(home, ".zshrc") : resolve2(home, ".bashrc");
+    const filePath = shell.includes("zsh") ? resolve3(home, ".zshrc") : resolve3(home, ".bashrc");
     printError(MESSAGES.COMPLETION_INSTALL_WRITE_ERROR(filePath));
   }
 }
@@ -6353,17 +6395,17 @@ async function handleHome() {
 }
 
 // src/commands/tasks.ts
-import { resolve as resolve3, dirname as dirname2, join as join12 } from "path";
+import { resolve as resolve4, dirname as dirname2, join as join13 } from "path";
 import { existsSync as existsSync14, writeFileSync as writeFileSync6 } from "fs";
 function registerTasksCommand(program2) {
   const taskCmd = program2.command("tasks").description("\u4EFB\u52A1\u6587\u4EF6\u7BA1\u7406");
   taskCmd.command("init").description("\u751F\u6210\u4EFB\u52A1\u6A21\u677F\u6587\u4EF6").argument("[path]", "\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84").action(async (path2) => {
-    const filePath = path2 ?? join12(TASK_TEMPLATE_OUTPUT_DIR, generateTaskFilename(TASK_TEMPLATE_FILENAME_PREFIX));
+    const filePath = path2 ?? join13(TASK_TEMPLATE_OUTPUT_DIR, generateTaskFilename(TASK_TEMPLATE_FILENAME_PREFIX));
     await handleTasksInit(filePath);
   });
 }
 async function handleTasksInit(filePath) {
-  const absolutePath = resolve3(filePath);
+  const absolutePath = resolve4(filePath);
   logger.info(`tasks init \u547D\u4EE4\u6267\u884C\uFF0C\u76EE\u6807\u6587\u4EF6: ${absolutePath}`);
   if (existsSync14(absolutePath)) {
     throw new ClawtError(MESSAGES.TASK_INIT_FILE_EXISTS(filePath));

package/dist/postinstall.js

@@ -260,6 +260,8 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   VALIDATE_RUN_ERROR_COPIED: "\u2702 \u9519\u8BEF\u4FE1\u606F\u5DF2\u590D\u5236\u5230\u526A\u8D34\u677F",
   /** 剪贴板复制失败提示 */
   VALIDATE_RUN_ERROR_COPY_FAILED: "\u26A0 \u9519\u8BEF\u4FE1\u606F\u590D\u5236\u5230\u526A\u8D34\u677F\u5931\u8D25",
+  /** 检测到外部软链接警告 */
+  VALIDATE_EXTERNAL_SYMLINKS_FOUND: (count) => `\u26A0 \u68C0\u6D4B\u5230 ${count} \u4E2A\u6307\u5411 worktree \u5916\u90E8\u7684\u8F6F\u94FE\u63A5\uFF08\u53EF\u80FD\u7531 AI Agent \u521B\u5EFA\uFF09\uFF0C\u5DF2\u81EA\u52A8\u79FB\u9664`,
   /** 单命令（含 && 链）剪贴板错误格式 */
   VALIDATE_CLIPBOARD_SINGLE_ERROR: (command, stderr) => `${command} \u6307\u4EE4\u6267\u884C\u51FA\u9519\uFF0C\u9519\u8BEF\u4FE1\u606F\uFF1A
 ${stderr}`,

package/docs/validate.md

@@ -66,6 +66,21 @@ validate 命令引入了**快照（snapshot）机制**来支持增量对比。
      - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
   3. **无匹配** → 报错退出，并列出所有可用分支名
 
+##### 步骤 0.5：清理外部软链接
+
+在变更检测之前，自动扫描目标 worktree 根目录，移除指向 worktree 外部路径的软链接。
+
+**背景：** AI Agent（如 Claude Code）在 worktree 中执行任务时，可能会通过软链接（如 `node_modules → /path/to/main-worktree/node_modules`）引用主 worktree 或其他外部路径的依赖目录。这些指向外部的软链接会导致 `git diff` 和 `git apply` 的行为异常，进而使 patch apply 失败。validate 命令在变更检测前自动清理这些软链接，确保后续 patch 流程正常执行。
+
+**实现要点：**
+
+- `removeExternalSymlinks(dir)`（`src/utils/symlink-guard.ts`）：扫描目录中所有软链接，判断其目标路径是否在 worktree 根目录之外（通过 `path.relative` 判断是否以 `..` 开头），移除外部软链接并返回被移除的路径列表
+- 内部辅助函数 `isExternalSymlink(linkPath, worktreeRoot)` 判断软链接目标是否指向外部：先解析软链接目标（绝对路径直接使用，相对路径基于 worktreeRoot 解析），再通过 `relative` 判断目标是否在 worktree 之外
+- 安全措施：删除前通过 `lstatSync` 再次确认目标仍是软链接（而非已被替换的普通文件），缩小 TOCTOU 口
+- 不可读目录或删除失败时静默处理（仅输出 warn 日志），不中断 validate 流程
+- 如果移除了外部软链接，输出警告提示：`⚠ 检测到 N 个指向 worktree 外部的软链接（可能由 AI Agent 创建），已自动移除`
+- 消息常量：`MESSAGES.VALIDATE_EXTERNAL_SYMLINKS_FOUND`（`src/constants/messages/validate.ts`）
+
 ##### 步骤 1：检测目标分支变更
 
 统一检测目标 worktree 的未提交修改和已提交 commit：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "3.9.11",
+  "version": "3.9.12",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/validate.ts

@@ -34,6 +34,7 @@ import {
   saveCurrentSnapshotTree,
   loadOldSnapshotToStage,
   switchToValidateBranch,
+  removeExternalSymlinks,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages } from '../utils/index.js';
 
@@ -274,6 +275,12 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
 
   logger.info(`validate 命令执行，分支: ${branchName}`);
 
+  // 通常由 AI Agent 创建的指向外部的软链接会导致 patch apply 失败
+  const removedSymlinks = removeExternalSymlinks(targetWorktreePath);
+  if (removedSymlinks.length > 0) {
+    printWarning(MESSAGES.VALIDATE_EXTERNAL_SYMLINKS_FOUND(removedSymlinks.length));
+  }
+
   // 统一检测未提交修改 + 已提交 commit
   const hasUncommitted = !isWorkingDirClean(targetWorktreePath);
   const hasCommitted = hasLocalCommits(branchName, mainWorktreePath);

package/src/constants/messages/validate.ts

@@ -75,6 +75,9 @@ export const VALIDATE_MESSAGES = {
   VALIDATE_RUN_ERROR_COPIED: '✂ 错误信息已复制到剪贴板',
   /** 剪贴板复制失败提示 */
   VALIDATE_RUN_ERROR_COPY_FAILED: '⚠ 错误信息复制到剪贴板失败',
+  /** 检测到外部软链接警告 */
+  VALIDATE_EXTERNAL_SYMLINKS_FOUND: (count: number) =>
+    `⚠ 检测到 ${count} 个指向 worktree 外部的软链接（可能由 AI Agent 创建），已自动移除`,
   /** 单命令（含 && 链）剪贴板错误格式 */
   VALIDATE_CLIPBOARD_SINGLE_ERROR: (command: string, stderr: string) =>
     `${command} 指令执行出错，错误信息：\n${stderr}`,

package/src/utils/index.ts

@@ -71,6 +71,7 @@ export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWor
 export { loadConfig, writeDefaultConfig, writeConfig, saveConfig, getConfigValue, ensureClawtDirs, parseConcurrency } from './config.js';
 export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime, formatDiskSize, formatLocalISOString, generateTaskFilename } from './formatter.js';
 export { ensureDir, removeEmptyDir, calculateDirSize } from './fs.js';
+export { removeExternalSymlinks } from './symlink-guard.js';
 export { multilineInput, promptCommitMessage } from './prompt.js';
 export { launchInteractiveClaude, hasClaudeSessionHistory, launchInteractiveClaudeInNewTerminal } from './claude.js';
 export { getSnapshotPath, hasSnapshot, getSnapshotModifiedTime, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots, getProjectSnapshotBranches } from './validate-snapshot.js';

package/src/utils/symlink-guard.ts

@@ -0,0 +1,61 @@
+import { readdirSync, lstatSync, unlinkSync, readlinkSync } from 'node:fs';
+import { join, relative, isAbsolute, resolve } from 'node:path';
+import { logger } from '../logger/index.js';
+
+/**
+ * 检测路径是否为指向 worktree 外部的外部软链接
+ * @param {string} linkPath - 软链接的绝对路径
+ * @param {string} worktreeRoot - worktree 根目录的绝对路径
+ * @returns {boolean} 是否为外部软链接
+ */
+function isExternalSymlink(linkPath: string, worktreeRoot: string): boolean {
+  try {
+    const target = readlinkSync(linkPath);
+    // 顶层软链接的相对路径基于 worktreeRoot 解析
+    const resolvedTarget = isAbsolute(target)
+      ? target
+      : resolve(worktreeRoot, target);
+
+    const relativePath = relative(worktreeRoot, resolvedTarget);
+    return relativePath.startsWith('..') || isAbsolute(relativePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 移除目录中指向外部路径的软链接
+ * 同一循环内边扫描边删除，缩小 TOCTOU 窗口；
+ * 删除前用 lstatSync 确认目标仍是软链接，避免误删已被替换的普通文件
+ * @param {string} dir - 要清理的目录绝对路径
+ * @returns {string[]} 被移除的软链接路径列表
+ */
+export function removeExternalSymlinks(dir: string): string[] {
+  const removed: string[] = [];
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isSymbolicLink()) continue;
+
+      const fullPath = join(dir, entry.name);
+      if (!isExternalSymlink(fullPath, dir)) continue;
+
+      try {
+        // lstatSync 不跟随软链接，确认删除前仍是软链接而非被替换的普通文件
+        const stat = lstatSync(fullPath);
+        if (!stat.isSymbolicLink()) continue;
+
+        unlinkSync(fullPath);
+        removed.push(fullPath);
+        logger.info(`已移除外部软链接: ${fullPath}`);
+      } catch (error) {
+        logger.warn(`移除外部软链接失败: ${fullPath} - ${error}`);
+      }
+    }
+  } catch {
+    // 目录不可读时静默返回
+  }
+
+  return removed;
+}

package/tests/unit/commands/validate.test.ts

@@ -46,6 +46,7 @@ vi.mock('../../../src/constants/index.js', () => ({
     VALIDATE_CONFIRM_AUTO_SYNC: (branch: string) => `是否自动 sync ${branch}`,
     VALIDATE_AUTO_SYNC_DECLINED: (branch: string) => `已跳过 ${branch} 的自动 sync`,
     VALIDATE_AUTO_SYNC_START: (branch: string) => `正在自动 sync ${branch}`,
+    VALIDATE_EXTERNAL_SYMLINKS_FOUND: (count: number) => `检测到 ${count} 个外部软链接`,
   },
 }));
 
@@ -94,6 +95,7 @@ vi.mock('../../../src/utils/index.js', () => ({
   executeRunCommand: vi.fn(),
   guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
   guardMainWorkBranchExists: vi.fn(),
+  removeExternalSymlinks: vi.fn().mockReturnValue([]),
 }));
 
 import { registerValidateCommand } from '../../../src/commands/validate.js';

package/tests/unit/utils/claude.test.ts

@@ -7,6 +7,10 @@ vi.mock('../../../src/logger/index.js', () => ({
 
 // mock node:child_process
 vi.mock('node:child_process', () => ({
+  exec: vi.fn(),
+  execSync: vi.fn(),
+  execFileSync: vi.fn(),
+  spawn: vi.fn(),
   spawnSync: vi.fn(),
 }));
 
@@ -21,6 +25,11 @@ vi.mock('../../../src/utils/config.js', () => ({
   getConfigValue: vi.fn(),
 }));
 
+// mock project-config（避免 resolveClaudeCodeCommand 调用 getGitTopLevel/execSync）
+vi.mock('../../../src/utils/project-config.js', () => ({
+  resolveClaudeCodeCommand: vi.fn(),
+}));
+
 // mock formatter
 vi.mock('../../../src/utils/formatter.js', () => ({
   printInfo: vi.fn(),
@@ -31,12 +40,14 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync } from 'node:fs';
 import { launchInteractiveClaude, hasClaudeSessionHistory, buildClaudeCommand } from '../../../src/utils/claude.js';
 import { getConfigValue } from '../../../src/utils/config.js';
+import { resolveClaudeCodeCommand } from '../../../src/utils/project-config.js';
 import { printInfo, printWarning } from '../../../src/utils/formatter.js';
 import { ClawtError } from '../../../src/errors/index.js';
 import { createWorktreeInfo } from '../../helpers/fixtures.js';
 
 const mockedSpawnSync = vi.mocked(spawnSync);
 const mockedGetConfigValue = vi.mocked(getConfigValue);
+const mockedResolveClaudeCodeCommand = vi.mocked(resolveClaudeCodeCommand);
 const mockedPrintInfo = vi.mocked(printInfo);
 const mockedPrintWarning = vi.mocked(printWarning);
 const mockedExistsSync = vi.mocked(existsSync);
@@ -86,7 +97,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('正常启动 Claude Code（退出码为 0）', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: 0,
@@ -100,7 +111,7 @@ describe('launchInteractiveClaude', () => {
 
     launchInteractiveClaude(worktree);
 
-    expect(mockedGetConfigValue).toHaveBeenCalledWith('claudeCodeCommand');
+    expect(mockedResolveClaudeCodeCommand).toHaveBeenCalled();
     expect(mockedSpawnSync).toHaveBeenCalledWith(
       'claude',
       expect.any(Array),
@@ -112,7 +123,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('输出分支和路径信息', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: 0,
@@ -131,7 +142,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('支持带参数的命令（如 npx claude）', () => {
-    mockedGetConfigValue.mockReturnValue('npx claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('npx claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: 0,
@@ -153,7 +164,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('spawnSync 返回 error 时抛出 ClawtError', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: null,
@@ -170,7 +181,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('非零退出码时调用 printWarning', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: 1,
@@ -188,7 +199,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('退出码为 null 时不调用 printWarning', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: null,
@@ -206,7 +217,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('退出码为 0 时不调用 printWarning', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: 0,
@@ -224,7 +235,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('autoContinue 启用且有会话历史时追加 --continue 参数', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(true);
     mockedReaddirSync.mockReturnValue(['session-abc.jsonl'] as unknown as ReturnType<typeof readdirSync>);
     mockedSpawnSync.mockReturnValue({
@@ -245,7 +256,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('autoContinue 启用但无会话历史时不追加 --continue 参数', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: 0,
@@ -265,7 +276,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('不传 autoContinue 时即使有会话历史也不追加 --continue', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(true);
     mockedReaddirSync.mockReturnValue(['session-abc.jsonl'] as unknown as ReturnType<typeof readdirSync>);
     mockedSpawnSync.mockReturnValue({
@@ -285,7 +296,7 @@ describe('launchInteractiveClaude', () => {
   });
 
   it('不包含 --append-system-prompt 参数', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     mockedExistsSync.mockReturnValue(false);
     mockedSpawnSync.mockReturnValue({
       status: 0,
@@ -311,7 +322,7 @@ describe('buildClaudeCommand', () => {
   });
 
   it('生成包含 cd 和 claude 命令的字符串', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
 
     const cmd = buildClaudeCommand(worktree, false);
 
@@ -320,7 +331,7 @@ describe('buildClaudeCommand', () => {
   });
 
   it('hasPreviousSession 为 true 时包含 --continue', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
 
     const cmd = buildClaudeCommand(worktree, true);
 
@@ -328,7 +339,7 @@ describe('buildClaudeCommand', () => {
   });
 
   it('hasPreviousSession 为 false 时不包含 --continue', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
 
     const cmd = buildClaudeCommand(worktree, false);
 
@@ -336,7 +347,7 @@ describe('buildClaudeCommand', () => {
   });
 
   it('不包含 --append-system-prompt 参数', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
 
     const cmd = buildClaudeCommand(worktree, false);
 
@@ -344,7 +355,7 @@ describe('buildClaudeCommand', () => {
   });
 
   it('路径中的单引号被正确转义', () => {
-    mockedGetConfigValue.mockReturnValue('claude');
+    mockedResolveClaudeCodeCommand.mockReturnValue('claude');
     const wtWithQuote = createWorktreeInfo({
       path: "/tmp/test's-worktree",
       branch: 'feat',

package/tests/unit/utils/conflict-resolver.test.ts

@@ -18,7 +18,11 @@ vi.mock('../../../src/errors/index.js', () => ({
 
 // mock node:child_process
 vi.mock('node:child_process', () => ({
+  exec: vi.fn(),
+  execSync: vi.fn(),
   execFileSync: vi.fn(),
+  spawn: vi.fn(),
+  spawnSync: vi.fn(),
 }));
 
 // mock constants（使用与 src/constants/messages/merge.ts 一致的消息文本）

package/tests/unit/utils/git-lock.test.ts

@@ -236,9 +236,9 @@ describe('waitForGitIndexLockRetrySync', () => {
     waitForGitIndexLockRetrySync();
     const elapsed = Date.now() - startTime;
 
-    // 延迟时间应该接近 150ms（允许 50ms 误差）
-    expect(elapsed).toBeGreaterThanOrEqual(100);
-    expect(elapsed).toBeLessThanOrEqual(300);
+    // 延迟时间应该接近 1000ms（允许 500ms 误差，兼容 CI 环境的调度延迟）
+    expect(elapsed).toBeGreaterThanOrEqual(500);
+    expect(elapsed).toBeLessThanOrEqual(2000);
 
     stderrWriteSpy.mockRestore();
   });

package/tests/unit/utils/shell.test.ts

@@ -2,9 +2,11 @@ import { describe, it, expect, vi } from 'vitest';
 
 // mock node:child_process
 vi.mock('node:child_process', () => ({
+  exec: vi.fn(),
   execSync: vi.fn(),
   execFileSync: vi.fn(),
   spawn: vi.fn(),
+  spawnSync: vi.fn(),
 }));
 
 // mock logger

package/tests/unit/utils/symlink-guard.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, symlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { removeExternalSymlinks } from '../../../src/utils/symlink-guard.js';
+
+/** 创建临时测试目录的唯一路径 */
+function createTestDir(prefix: string): string {
+  return join(tmpdir(), `clawt-test-symlink-${prefix}-${Date.now()}`);
+}
+
+describe('symlink-guard', () => {
+  let worktreeDir: string;
+  let externalDir: string;
+
+  beforeEach(() => {
+    worktreeDir = createTestDir('worktree');
+    externalDir = createTestDir('external');
+    mkdirSync(worktreeDir, { recursive: true });
+    mkdirSync(externalDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(worktreeDir, { recursive: true, force: true });
+    rmSync(externalDir, { recursive: true, force: true });
+  });
+
+  describe('removeExternalSymlinks', () => {
+    it('应移除外部软链接并返回被移除的路径列表', () => {
+      mkdirSync(join(externalDir, 'node_modules_real'), { recursive: true });
+      symlinkSync(join(externalDir, 'node_modules_real'), join(worktreeDir, 'node_modules'));
+
+      const removed = removeExternalSymlinks(worktreeDir);
+      expect(removed).toHaveLength(1);
+      expect(existsSync(join(worktreeDir, 'node_modules'))).toBe(false);
+    });
+
+    it('不应移除内部软链接', () => {
+      mkdirSync(join(worktreeDir, 'target'), { recursive: true });
+      symlinkSync(join(worktreeDir, 'target'), join(worktreeDir, 'link'));
+
+      const removed = removeExternalSymlinks(worktreeDir);
+      expect(removed).toHaveLength(0);
+      expect(existsSync(join(worktreeDir, 'link'))).toBe(true);
+    });
+
+    it('应处理无软链接的目录', () => {
+      const removed = removeExternalSymlinks(worktreeDir);
+      expect(removed).toHaveLength(0);
+    });
+
+    it('应处理不存在的目录', () => {
+      const removed = removeExternalSymlinks('/nonexistent/path/12345');
+      expect(removed).toHaveLength(0);
+    });
+
+    it('应移除多个外部软链接', () => {
+      mkdirSync(join(externalDir, 'target1'), { recursive: true });
+      mkdirSync(join(externalDir, 'target2'), { recursive: true });
+
+      symlinkSync(join(externalDir, 'target1'), join(worktreeDir, 'node_modules'));
+      symlinkSync(join(externalDir, 'target2'), join(worktreeDir, '.venv'));
+
+      const removed = removeExternalSymlinks(worktreeDir);
+      expect(removed).toHaveLength(2);
+      expect(existsSync(join(worktreeDir, 'node_modules'))).toBe(false);
+      expect(existsSync(join(worktreeDir, '.venv'))).toBe(false);
+    });
+  });
+});