clawt 3.10.4 → 3.10.5

package/dist/index.js

@@ -819,6 +819,33 @@ var VALIDATE_MESSAGES_I18N = {
     "zh-CN": (branch) => `\u53D8\u66F4\u8FC1\u79FB\u5931\u8D25\uFF1A\u76EE\u6807\u5206\u652F\u4E0E\u4E3B\u5206\u652F\u5DEE\u5F02\u8FC7\u5927
   \u8BF7\u5148\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
   },
+  /** validate 检测到被 .gitignore 忽略的残留文件冲突 */
+  VALIDATE_IGNORED_FILES_CONFLICT: {
+    en: (files, cleanCommands) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map((f) => `  - ${f}`).join("\n");
+      const more = files.length > maxDisplay ? `
+  ...(${files.length} files total)` : "";
+      const cmds = cleanCommands.map((c) => `  ${c}`).join("\n");
+      return `Ignored files left in main worktree are blocking patch apply:
+${displayed}${more}
+
+Please clean up manually and retry:
+${cmds}`;
+    },
+    "zh-CN": (files, cleanCommands) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map((f) => `  - ${f}`).join("\n");
+      const more = files.length > maxDisplay ? `
+  ...\uFF08\u5171 ${files.length} \u4E2A\u6587\u4EF6\uFF09` : "";
+      const cmds = cleanCommands.map((c) => `  ${c}`).join("\n");
+      return `\u68C0\u6D4B\u5230\u88AB .gitignore \u5FFD\u7565\u7684\u6587\u4EF6\u6B8B\u7559\u5728\u4E3B worktree \u4E2D\uFF0C\u5BFC\u81F4\u53D8\u66F4\u65E0\u6CD5\u5E94\u7528\uFF1A
+${displayed}${more}
+
+\u8BF7\u624B\u52A8\u6E05\u7406\u540E\u91CD\u8BD5\uFF1A
+${cmds}`;
+    }
+  },
   /** validate 无可用 worktree */
   VALIDATE_NO_WORKTREES: {
     en: "No worktrees available, please create one with clawt run or clawt create first",
@@ -2817,6 +2844,19 @@ function gitMergeContinue(cwd) {
 function buildAutoSaveCommitMessage(mainBranch, branch) {
   return `${AUTO_SAVE_COMMIT_MESSAGE_PREFIX} ${mainBranch} into ${branch}`;
 }
+function gitCheckIgnored(paths, cwd) {
+  if (paths.length === 0) return [];
+  try {
+    const output = execFileSync2("git", ["check-ignore", "--", ...paths], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return output.trim().split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
 
 // src/utils/git-branch.ts
 function checkBranchExists(branchName, cwd) {
@@ -5093,6 +5133,17 @@ async function executeRunCommand(command, mainWorktreePath) {
 }
 
 // src/utils/validate-core.ts
+import { existsSync as existsSync10 } from "fs";
+import { join as join10 } from "path";
+function buildCleanCommands(files) {
+  const dirs = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const lastSlash = file.lastIndexOf("/");
+    const dir = lastSlash > 0 ? file.substring(0, lastSlash) : ".";
+    dirs.add(dir);
+  }
+  return Array.from(dirs).map((dir) => `git clean -fdx ${dir}/`);
+}
 function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted) {
   let didTempCommit = false;
   try {
@@ -5101,6 +5152,13 @@ function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName
       gitCommit("clawt:temp-commit-for-validate", targetWorktreePath);
       didTempCommit = true;
     }
+    const ignoredFiles = detectIgnoredFilesInPatch(branchName, mainWorktreePath);
+    if (ignoredFiles.length > 0) {
+      const cleanCommands = buildCleanCommands(ignoredFiles);
+      logger.warn(`\u68C0\u6D4B\u5230 ${ignoredFiles.length} \u4E2A\u88AB\u5FFD\u7565\u7684\u6B8B\u7559\u6587\u4EF6\u51B2\u7A81`);
+      printWarning(MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT(ignoredFiles, cleanCommands));
+      return { success: false };
+    }
     const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
     if (patch.length > 0) {
       try {
@@ -5175,6 +5233,16 @@ function switchToValidateBranch(branchName, mainWorktreePath) {
   }
   return validateBranchName;
 }
+function detectIgnoredFilesInPatch(branchName, mainWorktreePath) {
+  try {
+    const output = execCommand(`git diff --name-only HEAD...${branchName}`, { cwd: mainWorktreePath });
+    const patchFiles = output.split("\n").filter(Boolean);
+    if (patchFiles.length === 0) return [];
+    return gitCheckIgnored(patchFiles, mainWorktreePath).filter((file) => existsSync10(join10(mainWorktreePath, file)));
+  } catch {
+    return [];
+  }
+}
 
 // src/utils/interactive-panel.ts
 import { createInterface as createInterface2 } from "readline";
@@ -5967,9 +6035,9 @@ async function handleMergeConflict(currentBranch, incomingBranch, cwd, autoFlag)
 }
 
 // src/hooks/post-create.ts
-import { existsSync as existsSync10, accessSync, chmodSync, constants as fsConstants } from "fs";
+import { existsSync as existsSync11, accessSync, chmodSync, constants as fsConstants } from "fs";
 import { spawn as spawn2 } from "child_process";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 var POST_CREATE_SCRIPT_RELATIVE_PATH = ".clawt/postCreate.sh";
 function isExecutable(filePath) {
   try {
@@ -6001,8 +6069,8 @@ function resolvePostCreateHook() {
     }
   }
   const mainWorktreePath = getMainWorktreePath();
-  const scriptPath = join10(mainWorktreePath, POST_CREATE_SCRIPT_RELATIVE_PATH);
-  if (existsSync10(scriptPath)) {
+  const scriptPath = join11(mainWorktreePath, POST_CREATE_SCRIPT_RELATIVE_PATH);
+  if (existsSync11(scriptPath)) {
     if (!isExecutable(scriptPath)) {
       autoFixExecutablePermission(scriptPath);
     }
@@ -7263,8 +7331,8 @@ function registerAliasCommand(program2) {
 }
 
 // src/commands/projects.ts
-import { existsSync as existsSync11, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync12, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
+import { join as join12 } from "path";
 import chalk13 from "chalk";
 function registerProjectsCommand(program2) {
   program2.command("projects [name]").description(getCurrentLanguage() === "en" ? "Show worktree overview across projects, or view details for a specific project" : "\u5C55\u793A\u6240\u6709\u9879\u76EE\u7684 worktree \u6982\u89C8\uFF0C\u6216\u67E5\u770B\u6307\u5B9A\u9879\u76EE\u7684 worktree \u8BE6\u60C5").option("--json", getCurrentLanguage() === "en" ? "Output in JSON format" : "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((name, options) => {
@@ -7288,8 +7356,8 @@ function handleProjectsOverview(json) {
   printProjectsOverviewAsText(result);
 }
 function handleProjectDetail(name, json) {
-  const projectDir = join11(WORKTREES_DIR, name);
-  if (!existsSync11(projectDir)) {
+  const projectDir = join12(WORKTREES_DIR, name);
+  if (!existsSync12(projectDir)) {
     printError(MESSAGES.PROJECTS_NOT_FOUND(name));
     process.exit(1);
   }
@@ -7302,7 +7370,7 @@ function handleProjectDetail(name, json) {
   printProjectDetailAsText(result);
 }
 function collectProjectsOverview() {
-  if (!existsSync11(WORKTREES_DIR)) {
+  if (!existsSync12(WORKTREES_DIR)) {
     return { projects: [], totalProjects: 0, totalDiskUsage: 0 };
   }
   const entries = readdirSync6(WORKTREES_DIR, { withFileTypes: true });
@@ -7311,7 +7379,7 @@ function collectProjectsOverview() {
     if (!entry.isDirectory()) {
       continue;
     }
-    const projectDir = join11(WORKTREES_DIR, entry.name);
+    const projectDir = join12(WORKTREES_DIR, entry.name);
     const overview = collectSingleProjectOverview(entry.name, projectDir);
     projects.push(overview);
   }
@@ -7328,7 +7396,7 @@ function collectSingleProjectOverview(name, projectDir) {
   const worktreeDirs = subEntries.filter((e) => e.isDirectory());
   const worktreeCount = worktreeDirs.length;
   const diskUsage = calculateDirSize(projectDir);
-  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join11(projectDir, e.name)));
+  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join12(projectDir, e.name)));
   return {
     name,
     worktreeCount,
@@ -7343,7 +7411,7 @@ function collectProjectDetail(name, projectDir) {
     if (!entry.isDirectory()) {
       continue;
     }
-    const wtPath = join11(projectDir, entry.name);
+    const wtPath = join12(projectDir, entry.name);
     const detail = collectSingleWorktreeDetail(entry.name, wtPath);
     worktrees.push(detail);
   }
@@ -7443,7 +7511,7 @@ function printWorktreeDetailItem(wt) {
 }
 
 // src/commands/completion.ts
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync13 } from "fs";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync14 } from "fs";
 import { resolve as resolve3 } from "path";
 import { homedir as homedir2 } from "os";
 
@@ -7494,14 +7562,14 @@ compdef _clawt_completion clawt
 }
 
 // src/utils/completion-engine.ts
-import { existsSync as existsSync12, readdirSync as readdirSync7, statSync as statSync5 } from "fs";
-import { join as join12, dirname, basename as basename2 } from "path";
+import { existsSync as existsSync13, readdirSync as readdirSync7, statSync as statSync5 } from "fs";
+import { join as join13, dirname, basename as basename2 } from "path";
 function completeFilePath(partial) {
   const cwd = process.cwd();
   const hasDir = partial.includes("/");
-  const searchDir = hasDir ? join12(cwd, dirname(partial)) : cwd;
+  const searchDir = hasDir ? join13(cwd, dirname(partial)) : cwd;
   const prefix = hasDir ? basename2(partial) : partial;
-  if (!existsSync12(searchDir)) {
+  if (!existsSync13(searchDir)) {
     return [];
   }
   const entries = readdirSync7(searchDir);
@@ -7510,7 +7578,7 @@ function completeFilePath(partial) {
   for (const entry of entries) {
     if (!entry.startsWith(prefix)) continue;
     if (entry.startsWith(".")) continue;
-    const fullPath = join12(searchDir, entry);
+    const fullPath = join13(searchDir, entry);
     try {
       const stat = statSync5(fullPath);
       if (stat.isDirectory()) {
@@ -7599,7 +7667,7 @@ function generateCompletions(program2, args) {
 
 // src/commands/completion.ts
 function appendToFile(filePath, content) {
-  if (existsSync13(filePath)) {
+  if (existsSync14(filePath)) {
     const current = readFileSync6(filePath, "utf-8");
     if (current.includes("clawt completion")) {
       printInfo(MESSAGES.COMPLETION_INSTALL_EXISTS + ": " + filePath);
@@ -7739,19 +7807,19 @@ async function handleHome() {
 }
 
 // src/commands/tasks.ts
-import { resolve as resolve4, dirname as dirname2, join as join13 } from "path";
-import { existsSync as existsSync14, writeFileSync as writeFileSync6 } from "fs";
+import { resolve as resolve4, dirname as dirname2, join as join14 } from "path";
+import { existsSync as existsSync15, writeFileSync as writeFileSync6 } from "fs";
 function registerTasksCommand(program2) {
   const taskCmd = program2.command("tasks").description(getCurrentLanguage() === "en" ? "Task file management" : "\u4EFB\u52A1\u6587\u4EF6\u7BA1\u7406");
   taskCmd.command("init").description(getCurrentLanguage() === "en" ? "Generate task template file" : "\u751F\u6210\u4EFB\u52A1\u6A21\u677F\u6587\u4EF6").argument("[path]", getCurrentLanguage() === "en" ? "Output file path" : "\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84").action(async (path2) => {
-    const filePath = path2 ?? join13(TASK_TEMPLATE_OUTPUT_DIR, generateTaskFilename(TASK_TEMPLATE_FILENAME_PREFIX));
+    const filePath = path2 ?? join14(TASK_TEMPLATE_OUTPUT_DIR, generateTaskFilename(TASK_TEMPLATE_FILENAME_PREFIX));
     await handleTasksInit(filePath);
   });
 }
 async function handleTasksInit(filePath) {
   const absolutePath = resolve4(filePath);
   logger.info(`tasks init \u547D\u4EE4\u6267\u884C\uFF0C\u76EE\u6807\u6587\u4EF6: ${absolutePath}`);
-  if (existsSync14(absolutePath)) {
+  if (existsSync15(absolutePath)) {
     throw new ClawtError(MESSAGES.TASK_INIT_FILE_EXISTS(filePath));
   }
   ensureDir(dirname2(absolutePath));

package/dist/postinstall.js

@@ -726,6 +726,33 @@ var VALIDATE_MESSAGES_I18N = {
     "zh-CN": (branch) => `\u53D8\u66F4\u8FC1\u79FB\u5931\u8D25\uFF1A\u76EE\u6807\u5206\u652F\u4E0E\u4E3B\u5206\u652F\u5DEE\u5F02\u8FC7\u5927
   \u8BF7\u5148\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
   },
+  /** validate 检测到被 .gitignore 忽略的残留文件冲突 */
+  VALIDATE_IGNORED_FILES_CONFLICT: {
+    en: (files, cleanCommands) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map((f) => `  - ${f}`).join("\n");
+      const more = files.length > maxDisplay ? `
+  ...(${files.length} files total)` : "";
+      const cmds = cleanCommands.map((c) => `  ${c}`).join("\n");
+      return `Ignored files left in main worktree are blocking patch apply:
+${displayed}${more}
+
+Please clean up manually and retry:
+${cmds}`;
+    },
+    "zh-CN": (files, cleanCommands) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map((f) => `  - ${f}`).join("\n");
+      const more = files.length > maxDisplay ? `
+  ...\uFF08\u5171 ${files.length} \u4E2A\u6587\u4EF6\uFF09` : "";
+      const cmds = cleanCommands.map((c) => `  ${c}`).join("\n");
+      return `\u68C0\u6D4B\u5230\u88AB .gitignore \u5FFD\u7565\u7684\u6587\u4EF6\u6B8B\u7559\u5728\u4E3B worktree \u4E2D\uFF0C\u5BFC\u81F4\u53D8\u66F4\u65E0\u6CD5\u5E94\u7528\uFF1A
+${displayed}${more}
+
+\u8BF7\u624B\u52A8\u6E05\u7406\u540E\u91CD\u8BD5\uFF1A
+${cmds}`;
+    }
+  },
   /** validate 无可用 worktree */
   VALIDATE_NO_WORKTREES: {
     en: "No worktrees available, please create one with clawt run or clawt create first",

package/docs/superpowers/findings/2026-06-01-sync-validate-diverged-findings.md

@@ -0,0 +1,203 @@
+# sync 后 validate 仍然失败 — 调查记录
+
+**日期：** 2026-06-01
+
+---
+
+## 现象描述
+
+用户在交互式面板（`clawt status`）中对目标分支执行 validate，patch apply 失败，提示：
+
+```
+⚠ Change migration failed: target branch has diverged too far from main
+  Please run clawt sync -b <target-branch> first, then retry
+```
+
+用户选择自动 sync（或手动执行 `clawt sync -b <target-branch>`），sync 成功：
+
+```
+✓ Synced latest code from <main-branch> to <target-branch>
+Validation branch clawt-validate-<target-branch> has been rebuilt
+```
+
+但再次执行 validate 时，仍然报同样的错误。
+
+---
+
+## 调查过程
+
+### 第一步：确认分支状态
+
+- 主工作分支：HEAD 指向最新 commit
+- 验证分支：与主分支 HEAD 一致（sync 后已重建）
+- 目标分支：包含多次 merge commit，已合并主分支最新代码
+
+**结论：** sync 已成功，验证分支已正确重建，分支状态本身没有问题。
+
+### 第二步：模拟 patch apply
+
+执行三点 diff 并尝试 apply：
+
+```bash
+git diff clawt-validate-<target-branch>...<target-branch> --binary | git apply --check -
+```
+
+输出：
+
+```
+错误：<ignored-dir>/findings/some-findings.md：已经存在于工作区中
+错误：<ignored-dir>/plans/some-plan.md：已经存在于工作区中
+...（共 N 个文件）
+```
+
+**关键发现：** patch 失败的原因不是分支差异过大，而是目标分支中跟踪的某些文件在主 worktree 工作目录中已经物理存在。
+
+### 第三步：追溯文件来源
+
+检查主 worktree 工作目录：
+
+```bash
+ls <ignored-dir>/findings/
+# some-findings.md  ← 物理存在
+# ...（共多个文件）
+```
+
+检查 `git status`：
+
+```
+无文件要提交，干净的工作区
+```
+
+**为什么这些文件物理存在但 git status 不显示？**
+
+检查 `.gitignore`：
+
+```bash
+cat .gitignore | grep <ignored-dir>
+# <ignored-dir>/   ← 被忽略！
+```
+
+**结论：** 该目录在主分支的 `.gitignore` 中，这些文件是**被忽略的未跟踪文件**，`git status` 不会显示它们。
+
+### 第四步：追溯文件如何进入主 worktree
+
+这些文件是由**之前的 validate 操作**创建的：
+
+1. validate 通过 `git diff HEAD...branch --binary | git apply -` 将目标分支的变更（包括被忽略目录下的文件）应用到主 worktree 工作目录
+2. 目标分支跟踪了这些文件（尽管 `.gitignore` 中有该目录，但 AI Agent 在 worktree 中用 `git add -f` 强制添加了它们）
+3. validate 完成后，这些文件作为**未跟踪文件**留在主 worktree 工作目录中
+
+### 第五步：追溯为什么清理无效
+
+validate 的清理逻辑（`handleIncrementalValidate` 步骤 2 和 `handleDirtyWorkingDir` 的 reset 选项）使用：
+
+```bash
+git reset --hard    # 只影响已跟踪文件
+git clean -fd       # 删除未跟踪文件，但**不删除被忽略的文件**
+```
+
+`git clean -fd` 的行为：
+- 删除未跟踪且未被忽略的文件 ✓
+- **跳过**在 `.gitignore` 中的文件 ✗
+
+要删除被忽略的文件，需要 `git clean -fdx`（`-x` 表示包括被忽略的文件）。
+
+### 第六步：确认 sync 为什么不解决问题
+
+`executeSyncForBranch` 的操作：
+1. 检查目标 worktree 未提交变更 → 自动 commit
+2. 在目标 worktree 中 `git merge <main-branch>`
+3. 重建验证分支
+
+**sync 完全不清理主 worktree 的工作目录**，因此那些被忽略的残留文件仍然存在。
+
+---
+
+## 根本原因
+
+**完整因果链：**
+
+```
+上游 commit 将某目录加入 .gitignore 并从 git 跟踪中移除
+    ↓
+目标分支仍然跟踪着自己新增的文件（AI Agent 用 git add -f 强制提交）
+    ↓
+validate 通过 patch apply 将这些文件创建到主 worktree 工作目录
+    ↓
+validate 结束后的清理（git clean -fd）无法删除这些文件（因为在 .gitignore 中）
+    ↓
+文件作为"被忽略的未跟踪文件"永久残留在主 worktree
+    ↓
+下次 validate 的 patch apply 试图创建同名文件 → "已经存在于工作区中" → 失败
+    ↓
+auto-sync 不清理主 worktree 工作目录 → 问题持续存在（死循环）
+```
+
+**核心矛盾：**
+
+- 被忽略目录在主分支 `.gitignore` 中 → `git clean -fd` 不删除
+- 被忽略目录在目标分支被跟踪 → patch 包含这些文件 → apply 时与物理存在的文件冲突
+
+---
+
+## 影响范围
+
+此 bug 在以下条件同时满足时触发：
+
+1. 目标分支跟踪了某些在 `.gitignore` 中的文件（通常是 AI Agent 用 `git add -f` 强制添加）
+2. 主分支的 `.gitignore` 包含对应路径
+3. 至少执行过一次 validate（使文件通过 patch 进入主 worktree）
+4. 后续再次执行 validate（patch apply 因文件已存在而失败）
+
+---
+
+## 技术决策记录
+
+| 假设 | 验证结果 |
+|------|----------|
+| 分支确实 diverged（差异过大） | ❌ 排除：三点 diff 正常，merge-base 正确 |
+| 验证分支未正确重建 | ❌ 排除：验证分支与主分支 HEAD 一致 |
+| sync 未成功执行 | ❌ 排除：sync 成功，目标分支已合并主分支 |
+| patch 内容与主分支冲突 | ❌ 排除：不是内容冲突，是文件已存在 |
+| **被忽略文件残留导致 patch apply 失败** | ✅ 确认：`git apply --check` 明确报 "已经存在于工作区中" |
+
+---
+
+## Brainstorming 决策（2026-06-01）
+
+### 方案评估
+
+| 方案 | 安全性 | 便利性 | 误删风险 | 代码复杂度 |
+|------|--------|--------|----------|------------|
+| A：检测 + 提示用户手动清理 | 高 | 低 | 无 | 低 |
+| B：检测 + 自动清理后继续 | 中 | 高 | 有 | 略高 |
+
+### 最终决策
+
+**选择方案 A（检测 + 提示用户手动清理）**
+
+理由：
+1. 这类冲突本质上是项目 `.gitignore` 配置与分支跟踪状态不一致导致的，属于需要用户知情的项目级决策
+2. 不应该由工具静默处理，用户需要知道哪些文件被清理了
+3. 实现简单，风险为零
+
+### 实现方案
+
+1. 新增 `gitCheckIgnored(paths, cwd)` — 批量检测文件是否被 `.gitignore` 忽略
+2. 新增 `detectIgnoredFilesInPatch(branchName, mainWorktreePath)` — 检测 patch 中的幽灵文件
+3. 修改 `migrateChangesViaPatch` — apply 前调用检测函数，有冲突则输出提示并返回失败
+4. 新增消息常量 `VALIDATE_IGNORED_FILES_CONFLICT`（双语）
+
+### 提示格式
+
+```
+⚠ 检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：
+  - <ignored-dir>/findings/some-findings.md
+  - <ignored-dir>/plans/some-plan.md
+  ...（共 N 个文件）
+
+请手动清理后重试：
+  git clean -fdx <ignored-dir>/
+```
+
+清理命令按冲突文件的直接父目录去重生成。

package/docs/superpowers/plans/2026-06-01-validate-ignored-files-conflict.md

@@ -0,0 +1,412 @@
+# validate 被忽略文件冲突检测 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在 validate 的 patch apply 之前检测被 `.gitignore` 忽略的残留文件（幽灵文件），输出清晰的错误提示和清理命令，替代当前误导性的 "diverged too far" 信息。
+
+**Architecture:** 在 `migrateChangesViaPatch` 中，`git apply` 之前新增检测步骤：通过 `git diff --name-only` 获取 patch 文件列表 → `git check-ignore` 筛选被忽略的文件 → `fs.existsSync` 确认物理存在 → 有冲突则输出提示并返回失败。
+
+**Tech Stack:** TypeScript, Node.js, Git CLI (`git check-ignore`, `git diff --name-only`), Vitest
+
+---
+
+### Task 1: 新增 `gitCheckIgnored` 函数
+
+**Files:**
+- Modify: `src/utils/git-core.ts`
+- Test: `tests/unit/utils/git-core.test.ts`（新建）
+
+- [ ] **Step 1: 编写 `gitCheckIgnored` 的失败测试**
+
+```typescript
+// tests/unit/utils/git-core.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { gitCheckIgnored } from '../../../src/utils/git-core.js';
+
+// mock execSync
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+  execFileSync: vi.fn(),
+}));
+
+import { execSync } from 'node:child_process';
+const mockExecSync = vi.mocked(execSync);
+
+describe('gitCheckIgnored', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('空数组输入时返回空数组', () => {
+    const result = gitCheckIgnored([]);
+    expect(result).toEqual([]);
+    expect(mockExecSync).not.toHaveBeenCalled();
+  });
+
+  it('全部被忽略时返回全部路径', () => {
+    mockExecSync.mockReturnValue('docs/superpowers/a.md\ndocs/superpowers/b.md\n');
+    const result = gitCheckIgnored(['docs/superpowers/a.md', 'docs/superpowers/b.md']);
+    expect(result).toEqual(['docs/superpowers/a.md', 'docs/superpowers/b.md']);
+  });
+
+  it('全部不被忽略时返回空数组', () => {
+    // git check-ignore 无匹配时退出码为 1，execSync 抛出异常
+    mockExecSync.mockImplementation(() => { throw new Error('exit code 1'); });
+    const result = gitCheckIgnored(['src/index.ts']);
+    expect(result).toEqual([]);
+  });
+
+  it('混合场景时仅返回被忽略的路径', () => {
+    mockExecSync.mockReturnValue('docs/superpowers/a.md\n');
+    const result = gitCheckIgnored(['docs/superpowers/a.md', 'src/index.ts']);
+    expect(result).toEqual(['docs/superpowers/a.md']);
+  });
+});
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `npx vitest run tests/unit/utils/git-core.test.ts`
+Expected: FAIL — `gitCheckIgnored` 未定义
+
+- [ ] **Step 3: 实现 `gitCheckIgnored`**
+
+在 `src/utils/git-core.ts` 中新增：
+
+```typescript
+/**
+ * 批量检测文件是否被 .gitignore 忽略
+ * 使用 git check-ignore 命令，退出码 1 表示无匹配（非错误）
+ * @param {string[]} paths - 要检测的文件路径列表
+ * @param {string} [cwd] - 工作目录
+ * @returns {string[]} 被忽略的文件路径列表
+ */
+export function gitCheckIgnored(paths: string[], cwd?: string): string[] {
+  if (paths.length === 0) return [];
+
+  try {
+    const output = execSync(`git check-ignore ${paths.map(p => `"${p}"`).join(' ')}`, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output.trim().split('\n').filter(Boolean);
+  } catch {
+    // git check-ignore 退出码 1 表示无匹配文件，属于正常情况
+    return [];
+  }
+}
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `npx vitest run tests/unit/utils/git-core.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 在 `src/utils/index.ts` 中导出**
+
+在 `src/utils/index.ts` 的 git-core 导出块中添加 `gitCheckIgnored`：
+
+```typescript
+// 在现有的 git-core 导出列表中添加 gitCheckIgnored
+```
+
+具体位置：在 `export { ... } from './git.js'` 块中添加 `gitCheckIgnored`（因为 `git.ts` 通过 `export * from './git-core.js'` 重导出）。
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/utils/git-core.ts src/utils/index.ts tests/unit/utils/git-core.test.ts
+git commit -m "feat: add gitCheckIgnored for batch gitignore detection"
+```
+
+---
+
+### Task 2: 新增 `detectIgnoredFilesInPatch` 函数
+
+**Files:**
+- Modify: `src/utils/validate-core.ts`
+- Test: `tests/unit/utils/validate-core.test.ts`（新建）
+
+- [ ] **Step 1: 编写 `detectIgnoredFilesInPatch` 的失败测试**
+
+```typescript
+// tests/unit/utils/validate-core.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../../src/utils/git-core.js', async () => {
+  const actual = await vi.importActual('../../../src/utils/git-core.js');
+  return { ...actual, gitCheckIgnored: vi.fn(), execSync: vi.fn() };
+});
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+}));
+
+import { detectIgnoredFilesInPatch } from '../../../src/utils/validate-core.js';
+import { gitCheckIgnored } from '../../../src/utils/git-core.js';
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+
+const mockGitCheckIgnored = vi.mocked(gitCheckIgnored);
+const mockExistsSync = vi.mocked(existsSync);
+const mockExecSync = vi.mocked(execSync);
+
+describe('detectIgnoredFilesInPatch', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('无幽灵文件时返回空数组', () => {
+    mockExecSync.mockReturnValue('src/a.ts\nsrc/b.ts\n');
+    mockGitCheckIgnored.mockReturnValue([]);
+    const result = detectIgnoredFilesInPatch('feature', '/main');
+    expect(result).toEqual([]);
+  });
+
+  it('检测到幽灵文件时返回文件列表', () => {
+    mockExecSync.mockReturnValue('docs/superpowers/a.md\nsrc/b.ts\n');
+    mockGitCheckIgnored.mockReturnValue(['docs/superpowers/a.md']);
+    mockExistsSync.mockImplementation((p: string) => p === '/main/docs/superpowers/a.md');
+    const result = detectIgnoredFilesInPatch('feature', '/main');
+    expect(result).toEqual(['docs/superpowers/a.md']);
+  });
+
+  it('被忽略但物理不存在的文件不包含在结果中', () => {
+    mockExecSync.mockReturnValue('docs/superpowers/a.md\n');
+    mockGitCheckIgnored.mockReturnValue(['docs/superpowers/a.md']);
+    mockExistsSync.mockReturnValue(false);
+    const result = detectIgnoredFilesInPatch('feature', '/main');
+    expect(result).toEqual([]);
+  });
+
+  it('git diff --name-only 失败时返回空数组（降级）', () => {
+    mockExecSync.mockImplementation(() => { throw new Error('fatal'); });
+    const result = detectIgnoredFilesInPatch('feature', '/main');
+    expect(result).toEqual([]);
+  });
+});
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `npx vitest run tests/unit/utils/validate-core.test.ts`
+Expected: FAIL — `detectIgnoredFilesInPatch` 未定义
+
+- [ ] **Step 3: 实现 `detectIgnoredFilesInPatch`**
+
+在 `src/utils/validate-core.ts` 中新增：
+
+```typescript
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { EXEC_MAX_BUFFER } from '../constants/index.js';
+
+/**
+ * 检测 patch 中被 .gitignore 忽略且物理存在于主 worktree 的文件（幽灵文件）
+ * 这些文件会导致 git apply 失败（"已经存在于工作区中"）
+ * @param {string} branchName - 目标分支名
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @returns {string[]} 幽灵文件的相对路径列表
+ */
+export function detectIgnoredFilesInPatch(branchName: string, mainWorktreePath: string): string[] {
+  let patchFiles: string[];
+  try {
+    const output = execSync(`git diff --name-only HEAD...${branchName}`, {
+      cwd: mainWorktreePath,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: EXEC_MAX_BUFFER,
+    });
+    patchFiles = output.trim().split('\n').filter(Boolean);
+  } catch {
+    // diff 失败时跳过检测，降级为当前行为（让 apply 自行报错）
+    return [];
+  }
+
+  if (patchFiles.length === 0) return [];
+
+  const ignoredFiles = gitCheckIgnored(patchFiles, mainWorktreePath);
+  if (ignoredFiles.length === 0) return [];
+
+  // 仅保留物理存在的文件（幽灵文件）
+  return ignoredFiles.filter(file => existsSync(join(mainWorktreePath, file)));
+}
+```
+
+注意：需要在文件顶部的 import 中添加 `gitCheckIgnored`（从 `./index.js` 导入）和 `EXEC_MAX_BUFFER`（从 `../constants/index.js` 导入）。
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `npx vitest run tests/unit/utils/validate-core.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 在 `src/utils/index.ts` 中导出**
+
+在 `src/utils/index.ts` 的 validate-core 导出行中添加 `detectIgnoredFilesInPatch`：
+
+```typescript
+export { migrateChangesViaPatch, computeCurrentTreeHash, saveCurrentSnapshotTree, loadOldSnapshotToStage, switchToValidateBranch, detectIgnoredFilesInPatch } from './validate-core.js';
+```
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/utils/validate-core.ts src/utils/index.ts tests/unit/utils/validate-core.test.ts
+git commit -m "feat: add detectIgnoredFilesInPatch for ghost file detection"
+```
+
+---
+
+### Task 3: 新增消息常量 `VALIDATE_IGNORED_FILES_CONFLICT`
+
+**Files:**
+- Modify: `src/constants/messages/validate.ts`
+
+- [ ] **Step 1: 添加双语消息常量**
+
+在 `src/constants/messages/validate.ts` 的 `VALIDATE_MESSAGES_I18N` 对象中，在 `VALIDATE_PATCH_APPLY_FAILED` 之后添加：
+
+```typescript
+  /** validate 检测到被 .gitignore 忽略的残留文件冲突 */
+  VALIDATE_IGNORED_FILES_CONFLICT: {
+    en: (files: string[], cleanCommands: string[]) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map(f => `  - ${f}`).join('\n');
+      const more = files.length > maxDisplay ? `\n  ...(${files.length} files total)` : '';
+      const cmds = cleanCommands.map(c => `  ${c}`).join('\n');
+      return `Ignored files left in main worktree are blocking patch apply:\n${displayed}${more}\n\nPlease clean up manually and retry:\n${cmds}`;
+    },
+    'zh-CN': (files: string[], cleanCommands: string[]) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map(f => `  - ${f}`).join('\n');
+      const more = files.length > maxDisplay ? `\n  ...（共 ${files.length} 个文件）` : '';
+      const cmds = cleanCommands.map(c => `  ${c}`).join('\n');
+      return `检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：\n${displayed}${more}\n\n请手动清理后重试：\n${cmds}`;
+    },
+  },
+```
+
+- [ ] **Step 2: 提交**
+
+```bash
+git add src/constants/messages/validate.ts
+git commit -m "feat: add VALIDATE_IGNORED_FILES_CONFLICT message constant"
+```
+
+---
+
+### Task 4: 修改 `migrateChangesViaPatch` 集成检测逻辑
+
+**Files:**
+- Modify: `src/utils/validate-core.ts`
+
+- [ ] **Step 1: 修改 `migrateChangesViaPatch`**
+
+在 `migrateChangesViaPatch` 函数中，`gitApplyFromStdin` 调用之前，添加幽灵文件检测逻辑：
+
+```typescript
+export function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: string, branchName: string, hasUncommitted: boolean): { success: boolean } {
+  let didTempCommit = false;
+
+  try {
+    // 如果有未提交修改，先做临时 commit 以便 diff 能捕获全部变更
+    if (hasUncommitted) {
+      gitAddAll(targetWorktreePath);
+      gitCommit('clawt:temp-commit-for-validate', targetWorktreePath);
+      didTempCommit = true;
+    }
+
+    // 在主 worktree 执行三点 diff，获取目标分支自分叉点以来的全量变更
+    const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
+
+    // 检测被 .gitignore 忽略的残留文件（幽灵文件），在 apply 之前拦截
+    const ignoredFiles = detectIgnoredFilesInPatch(branchName, mainWorktreePath);
+    if (ignoredFiles.length > 0) {
+      const cleanCommands = buildCleanCommands(ignoredFiles);
+      logger.warn(`检测到 ${ignoredFiles.length} 个被忽略的残留文件冲突`);
+      printWarning(MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT(ignoredFiles, cleanCommands));
+      return { success: false };
+    }
+
+    // 应用 patch 到主 worktree 工作目录
+    if (patch.length > 0) {
+      try {
+        gitApplyFromStdin(patch, mainWorktreePath);
+      } catch (error) {
+        logger.warn(`patch apply 失败: ${error}`);
+        printWarning(MESSAGES.VALIDATE_PATCH_APPLY_FAILED(branchName));
+        return { success: false };
+      }
+    }
+
+    return { success: true };
+  } finally {
+    // ...（finally 块保持不变）
+  }
+}
+```
+
+- [ ] **Step 2: 实现 `buildCleanCommands` 辅助函数**
+
+在 `src/utils/validate-core.ts` 中新增（不导出，仅内部使用）：
+
+```typescript
+/**
+ * 根据冲突文件列表生成 git clean 清理命令
+ * 按直接父目录去重，生成针对性的清理命令
+ * @param {string[]} files - 冲突文件的相对路径列表
+ * @returns {string[]} 清理命令列表
+ */
+function buildCleanCommands(files: string[]): string[] {
+  const dirs = new Set<string>();
+  for (const file of files) {
+    const lastSlash = file.lastIndexOf('/');
+    const dir = lastSlash > 0 ? file.substring(0, lastSlash) : '.';
+    dirs.add(dir);
+  }
+  return Array.from(dirs).map(dir => `git clean -fdx ${dir}/`);
+}
+```
+
+- [ ] **Step 3: 确保 import 完整**
+
+在 `src/utils/validate-core.ts` 顶部确认以下 import 存在：
+- `MESSAGES` 从 `'../constants/index.js'`（已有）
+- `printWarning` 从 `'./index.js'`（已有）
+- `detectIgnoredFilesInPatch` 在同文件中定义，无需额外 import
+- `buildCleanCommands` 在同文件中定义，无需额外 import
+
+- [ ] **Step 4: 运行全部测试确认无回归**
+
+Run: `npx vitest run`
+Expected: 全部 PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/utils/validate-core.ts
+git commit -m "feat: integrate ghost file detection into migrateChangesViaPatch"
+```
+
+---
+
+### Task 5: 集成验证
+
+- [ ] **Step 1: 构建项目确认无编译错误**
+
+Run: `npm run build`
+Expected: 构建成功
+
+- [ ] **Step 2: 运行全部测试**
+
+Run: `npm test`
+Expected: 全部 PASS
+
+- [ ] **Step 3: 提交全部变更（如有遗漏）**
+
+```bash
+git add -A
+git commit -m "feat: detect ignored ghost files before patch apply in validate"
+```

package/docs/superpowers/specs/2026-06-01-validate-ignored-files-conflict-design.md

@@ -0,0 +1,76 @@
+# validate 被忽略文件冲突检测 — 设计文档
+
+## 问题
+
+当目标分支跟踪了某些在 `.gitignore` 中的文件（如 AI Agent 用 `git add -f` 强制提交），validate 通过 `git apply` 将这些文件创建到主 worktree 工作目录后，`git clean -fd` 无法清理它们（因为被 `.gitignore` 忽略）。后续 validate 的 patch apply 因文件已存在而失败，且 sync 无法打破这个死循环。
+
+## 修复目标
+
+在 `migrateChangesViaPatch` 中，`git apply` 之前检测被 `.gitignore` 忽略且物理存在于主 worktree 工作目录的文件（"幽灵文件"），若检测到冲突则输出清晰的错误提示和可执行的清理命令，而非当前的误导性信息 "diverged too far from main"。
+
+## 验收标准
+
+1. 检测到幽灵文件时，输出文件列表和 `git clean -fdx <dir>` 清理命令
+2. 未检测到幽灵文件时，行为与当前完全一致（无回归）
+3. 提示信息为双语（中英）
+4. 有单元测试覆盖检测逻辑
+
+## 架构
+
+### 检测流程
+
+```
+migrateChangesViaPatch()
+  ├── gitDiffBinaryAgainstBranch()  → 获取 patch
+  ├── detectIgnoredFilesInPatch()   → 新增：检测幽灵文件
+  │     ├── git diff --name-only HEAD...branch  → 获取 patch 涉及的文件列表
+  │     ├── git check-ignore <files>            → 筛选被忽略的文件
+  │     └── fs.existsSync                       → 筛选物理存在的文件
+  ├── 有冲突 → printWarning + return { success: false }
+  └── 无冲突 → gitApplyFromStdin()  → 正常 apply
+```
+
+### 新增函数
+
+| 函数 | 文件 | 职责 |
+|------|------|------|
+| `gitCheckIgnored(paths, cwd)` | `src/utils/git-core.ts` | 批量检测文件是否被 `.gitignore` 忽略 |
+| `detectIgnoredFilesInPatch(branchName, mainWorktreePath)` | `src/utils/validate-core.ts` | 检测 patch 中的幽灵文件列表 |
+
+### 修改函数
+
+| 函数 | 文件 | 变更 |
+|------|------|------|
+| `migrateChangesViaPatch` | `src/utils/validate-core.ts` | apply 前调用检测函数 |
+
+### 新增消息常量
+
+| 常量 | 文件 | 用途 |
+|------|------|------|
+| `VALIDATE_IGNORED_FILES_CONFLICT` | `src/constants/messages/validate.ts` | 幽灵文件冲突提示（含文件列表和清理命令） |
+
+### 提示格式
+
+```
+⚠ 检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：
+  - docs/superpowers/findings/2026-05-30-chat-message-block-findings.md
+  - docs/superpowers/plans/2026-05-30-chat-message-block.md
+  ...（共 18 个文件）
+
+请手动清理后重试：
+  git clean -fdx docs/superpowers/
+```
+
+清理命令按冲突文件的直接父目录去重生成。
+
+## 错误处理
+
+- `git check-ignore` 无匹配时退出码为 1（非错误），需 catch 后返回空数组
+- `git diff --name-only` 失败时不阻断流程，跳过检测继续 apply（降级为当前行为）
+- 检测函数本身的异常不应阻断 validate 流程
+
+## 回归测试要求
+
+- 无幽灵文件时：validate 正常通过（现有测试覆盖）
+- 有幽灵文件时：validate 返回 `{ success: false }` 并输出提示
+- `gitCheckIgnored` 单元测试：空输入、全部忽略、全部不忽略、混合场景

package/docs/validate.md

@@ -158,9 +158,44 @@ git restore --staged .
 > 此步骤结束后，目标 worktree 的代码保持原样，主 worktree 工作目录包含目标分支的全量变更。
 > 如果 patch apply 失败（兜底场景），`migrateChangesViaPatch` 返回 `{ success: false }`，进入自动 sync 交互流程（见下文 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)）。
 
+###### 幽灵文件检测（patch apply 前置拦截）
+
+在执行昂贵的 `git diff --binary` 之前，`migrateChangesViaPatch` 会先进行轻量级的**幽灵文件检测**，提前拦截一类常见的 patch apply 失败场景。
+
+**背景：** AI Agent（如 Claude Code）在 worktree 中工作时，可能会创建被 `.gitignore` 忽略的文件（如 `node_modules/` 下的依赖、构建产物等）。这些文件不受 git 跟踪，但当目标分支的 patch 中包含同名文件时，`git apply` 会因为"文件已存在于工作区中"而失败。由于这些文件被 `.gitignore` 忽略，`git clean -fd` 无法清理它们（需要 `git clean -fdx`），用户往往难以自行发现和定位。
+
+**检测流程：**
+
+1. **获取 patch 涉及的文件列表**：通过 `git diff --name-only HEAD...<branchName>` 轻量获取目标分支变更涉及的所有文件路径（不含二进制内容，远比 `--binary` 便宜）
+2. **筛选被 `.gitignore` 忽略的文件**：调用 `gitCheckIgnored()`（`src/utils/git-core.ts`），通过 `git check-ignore` 批量检测哪些文件被忽略规则匹配
+3. **确认文件物理存在**：对被忽略的文件进一步检查其是否真实存在于主 worktree 文件系统中（`existsSync`），只有同时满足"被忽略"和"物理存在"两个条件的才是幽灵文件
+4. **拦截并提示**：如果检测到幽灵文件，生成针对性的 `git clean -fdx` 清理命令（按直接父目录去重，通过 `buildCleanCommands()` 生成），输出清晰的错误提示后返回 `{ success: false }`
+
+**错误提示示例：**
+
+```
+检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：
+  - dist/bundle.js
+  - node_modules/.cache/temp.json
+
+请手动清理后重试：
+  git clean -fdx dist/
+  git clean -fdx node_modules/.cache/
+```
+
+> 幽灵文件检测失败后，同样进入 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)（询问用户是否执行 sync），但用户通常应根据提示先手动清理幽灵文件再重试 validate。
+> 如果 `git diff --name-only` 执行失败（如分支不存在），检测会静默跳过（降级为原有行为，让后续 apply 自行报错）。
+
+**实现要点：**
+
+- `detectIgnoredFilesInPatch(branchName, mainWorktreePath)`（`src/utils/validate-core.ts`）：检测 patch 中的幽灵文件，返回幽灵文件的相对路径列表
+- `gitCheckIgnored(paths, cwd)`（`src/utils/git-core.ts`）：封装 `git check-ignore` 命令，批量检测文件是否被忽略，退出码 1（无匹配）视为正常情况返回空数组
+- `buildCleanCommands(files)`（`src/utils/validate-core.ts`）：根据冲突文件列表，按直接父目录去重生成 `git clean -fdx <dir>/` 命令
+- 消息常量：`MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT`（`src/constants/messages/validate.ts`）：双语提示，最多展示 10 个文件路径，超出部分显示总数
+
 ##### patch apply 失败后的自动 sync 流程
 
-当 patch apply 失败时，validate 不再直接退出，而是先通过 `ensureOnMainWorkBranch()` 确保主 worktree 切回主工作分支，然后通过 `handlePatchApplyFailure()` 函数进入交互流程：
+当 patch 迁移失败时（包括 patch apply 冲突和幽灵文件检测拦截两种情况），validate 不再直接退出，而是先通过 `ensureOnMainWorkBranch()` 确保主 worktree 切回主工作分支，然后通过 `handlePatchApplyFailure()` 函数进入交互流程：
 
 1. **询问用户**：提示 `是否立即执行 sync 同步主分支到 <branchName>？`
 2. **用户拒绝** → 输出提示 `请手动执行 clawt sync -b <branchName> 同步主分支后重试`，退出
@@ -170,10 +205,12 @@ git restore --staged .
 
 **实现要点：**
 
-- `migrateChangesViaPatch()`（`src/utils/validate-core.ts`）返回 `{ success: boolean }`，patch apply 失败时返回 `{ success: false }` 而非抛出异常
+- `migrateChangesViaPatch()`（`src/utils/validate-core.ts`）返回 `{ success: boolean }`，patch apply 失败或幽灵文件检测拦截时返回 `{ success: false }` 而非抛出异常
+- `detectIgnoredFilesInPatch(branchName, mainWorktreePath)`（`src/utils/validate-core.ts`）：幽灵文件检测函数，在 patch apply 之前调用，返回被 `.gitignore` 忽略且物理存在的文件列表
+- `gitCheckIgnored(paths, cwd)`（`src/utils/git-core.ts`）：封装 `git check-ignore`，批量检测文件是否被忽略规则匹配
 - `handleFirstValidate()` 和 `handleIncrementalValidate()` 为 `async` 函数，支持交互式确认
-- `handlePatchApplyFailure()`（`src/commands/validate.ts`）为异步函数，负责 patch 失败后的交互逻辑
-- 消息常量：`MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC`、`MESSAGES.VALIDATE_AUTO_SYNC_START`、`MESSAGES.VALIDATE_AUTO_SYNC_DECLINED`（`src/constants/messages/validate.ts`）
+- `handlePatchApplyFailure()`（`src/commands/validate.ts`）为异步函数，负责 patch 迁移失败后的交互逻辑（含幽灵文件冲突和 patch apply 冲突两种场景）
+- 消息常量：`MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC`、`MESSAGES.VALIDATE_AUTO_SYNC_START`、`MESSAGES.VALIDATE_AUTO_SYNC_DECLINED`、`MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT`（`src/constants/messages/validate.ts`）
 
 ##### 步骤 5：保存快照为 git tree 对象
 
@@ -323,7 +360,7 @@ git checkout clawt-validate-<branchName>
 
 ##### 步骤 4：从目标分支获取最新全量变更
 
-通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 4）。如果 patch apply 失败，同样进入自动 sync 交互流程（见首次 validate 的 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)），validate 流程提前结束。
+通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 4，包含幽灵文件前置检测）。如果幽灵文件检测拦截或 patch apply 失败，同样进入自动 sync 交互流程（见首次 validate 的 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)），validate 流程提前结束。
 
 ##### 步骤 5：检测是否有新变更
 

package/package.json

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

package/src/constants/messages/validate.ts

@@ -40,6 +40,23 @@ const VALIDATE_MESSAGES_I18N = {
     'zh-CN': (branch: string) =>
       `变更迁移失败：目标分支与主分支差异过大\n  请先执行 clawt sync -b ${branch} 同步主分支后重试`,
   },
+  /** validate 检测到被 .gitignore 忽略的残留文件冲突 */
+  VALIDATE_IGNORED_FILES_CONFLICT: {
+    en: (files: string[], cleanCommands: string[]) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map(f => `  - ${f}`).join('\n');
+      const more = files.length > maxDisplay ? `\n  ...(${files.length} files total)` : '';
+      const cmds = cleanCommands.map(c => `  ${c}`).join('\n');
+      return `Ignored files left in main worktree are blocking patch apply:\n${displayed}${more}\n\nPlease clean up manually and retry:\n${cmds}`;
+    },
+    'zh-CN': (files: string[], cleanCommands: string[]) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map(f => `  - ${f}`).join('\n');
+      const more = files.length > maxDisplay ? `\n  ...（共 ${files.length} 个文件）` : '';
+      const cmds = cleanCommands.map(c => `  ${c}`).join('\n');
+      return `检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：\n${displayed}${more}\n\n请手动清理后重试：\n${cmds}`;
+    },
+  },
   /** validate 无可用 worktree */
   VALIDATE_NO_WORKTREES: {
     en: 'No worktrees available, please create one with clawt run or clawt create first',

package/src/utils/git-core.ts

@@ -498,3 +498,26 @@ export function gitMergeAbort(cwd?: string): void {
 export function buildAutoSaveCommitMessage(mainBranch: string, branch: string): string {
   return `${AUTO_SAVE_COMMIT_MESSAGE_PREFIX} ${mainBranch} into ${branch}`;
 }
+
+/**
+ * 批量检测文件是否被 .gitignore 忽略
+ * 使用 git check-ignore 命令，退出码 1 表示无匹配（非错误）
+ * @param {string[]} paths - 要检测的文件路径列表
+ * @param {string} [cwd] - 工作目录
+ * @returns {string[]} 被忽略的文件路径列表
+ */
+export function gitCheckIgnored(paths: string[], cwd?: string): string[] {
+  if (paths.length === 0) return [];
+
+  try {
+    const output = execFileSync('git', ['check-ignore', '--', ...paths], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output.trim().split('\n').filter(Boolean);
+  } catch {
+    // git check-ignore 退出码 1 表示无匹配文件，属于正常情况
+    return [];
+  }
+}

package/src/utils/index.ts

@@ -63,6 +63,7 @@ export {
   gitMergeAbort,
   buildAutoSaveCommitMessage,
   throwIfGitIndexLockError,
+  gitCheckIgnored,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled, validateHeadExists, validateWorkingDirClean, runPreChecks } from './validation.js';
@@ -92,7 +93,7 @@ export { getValidateBranchName, createValidateBranch, deleteValidateBranch, rebu
 export { safeStringify } from './json.js';
 export { isNonInteractive, setNonInteractive } from './interactive.js';
 export { executeRunCommand } from './validate-runner.js';
-export { migrateChangesViaPatch, computeCurrentTreeHash, saveCurrentSnapshotTree, loadOldSnapshotToStage, switchToValidateBranch } from './validate-core.js';
+export { migrateChangesViaPatch, computeCurrentTreeHash, saveCurrentSnapshotTree, loadOldSnapshotToStage, switchToValidateBranch, detectIgnoredFilesInPatch } from './validate-core.js';
 export { InteractivePanel } from './interactive-panel.js';
 export { buildPanelFrame, buildGroupedWorktreeLines, buildDisplayOrder, renderDateSeparator, renderWorktreeBlock, renderSnapshotSummary, renderFooter, calculateVisibleRows } from './interactive-panel-render.js';
 export type { PanelLine } from './interactive-panel-render.js';

package/src/utils/validate-core.ts

@@ -2,6 +2,8 @@ import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import { getCurrentLanguage } from './i18n.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import {
   gitAddAll,
   gitCommit,
@@ -22,8 +24,26 @@ import {
   getHeadCommitHash,
   writeSnapshot,
   printWarning,
+  gitCheckIgnored,
+  execCommand,
 } from './index.js';
 
+/**
+ * 根据冲突文件列表生成 git clean 清理命令
+ * 按直接父目录去重，生成针对性的清理命令
+ * @param {string[]} files - 冲突文件的相对路径列表
+ * @returns {string[]} 清理命令列表
+ */
+function buildCleanCommands(files: string[]): string[] {
+  const dirs = new Set<string>();
+  for (const file of files) {
+    const lastSlash = file.lastIndexOf('/');
+    const dir = lastSlash > 0 ? file.substring(0, lastSlash) : '.';
+    dirs.add(dir);
+  }
+  return Array.from(dirs).map(dir => `git clean -fdx ${dir}/`);
+}
+
 /**
  * 通过 patch 将目标分支的全量变更（已提交 + 未提交）迁移到主 worktree
  * 使用 git diff HEAD...branch --binary 获取变更，避免 stash 方式无法检测已提交 commit 的问题
@@ -44,6 +64,16 @@ export function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreeP
       didTempCommit = true;
     }
 
+    // 先执行轻量检测：检测被 .gitignore 忽略的残留文件（幽灵文件），在 apply 之前拦截
+    // 使用 --name-only 远比 --binary 便宜，检测到冲突时可跳过昂贵的 binary diff
+    const ignoredFiles = detectIgnoredFilesInPatch(branchName, mainWorktreePath);
+    if (ignoredFiles.length > 0) {
+      const cleanCommands = buildCleanCommands(ignoredFiles);
+      logger.warn(`检测到 ${ignoredFiles.length} 个被忽略的残留文件冲突`);
+      printWarning(MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT(ignoredFiles, cleanCommands));
+      return { success: false };
+    }
+
     // 在主 worktree 执行三点 diff，获取目标分支自分叉点以来的全量变更
     const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
 
@@ -173,3 +203,25 @@ export function switchToValidateBranch(branchName: string, mainWorktreePath: str
   }
   return validateBranchName;
 }
+
+/**
+ * 检测 patch 中被 .gitignore 忽略且物理存在于主 worktree 的文件（幽灵文件）
+ * 这些文件会导致 git apply 失败（"已经存在于工作区中"）
+ * @param {string} branchName - 目标分支名
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @returns {string[]} 幽灵文件的相对路径列表
+ */
+export function detectIgnoredFilesInPatch(branchName: string, mainWorktreePath: string): string[] {
+  try {
+    const output = execCommand(`git diff --name-only HEAD...${branchName}`, { cwd: mainWorktreePath });
+    const patchFiles = output.split('\n').filter(Boolean);
+    if (patchFiles.length === 0) return [];
+
+    // 筛选被 .gitignore 忽略且物理存在的文件（幽灵文件）
+    return gitCheckIgnored(patchFiles, mainWorktreePath)
+      .filter(file => existsSync(join(mainWorktreePath, file)));
+  } catch {
+    // diff 失败时跳过检测，降级为当前行为（让 apply 自行报错）
+    return [];
+  }
+}

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

@@ -0,0 +1,43 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { gitCheckIgnored } from '../../../src/utils/git-core.js';
+
+// mock child_process
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+  execFileSync: vi.fn(),
+  exec: vi.fn(),
+}));
+
+import { execFileSync } from 'node:child_process';
+const mockExecFileSync = vi.mocked(execFileSync);
+
+describe('gitCheckIgnored', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('空数组输入时返回空数组', () => {
+    const result = gitCheckIgnored([]);
+    expect(result).toEqual([]);
+    expect(mockExecFileSync).not.toHaveBeenCalled();
+  });
+
+  it('全部被忽略时返回全部路径', () => {
+    mockExecFileSync.mockReturnValue('docs/superpowers/a.md\ndocs/superpowers/b.md\n');
+    const result = gitCheckIgnored(['docs/superpowers/a.md', 'docs/superpowers/b.md']);
+    expect(result).toEqual(['docs/superpowers/a.md', 'docs/superpowers/b.md']);
+  });
+
+  it('全部不被忽略时返回空数组', () => {
+    // git check-ignore 无匹配时退出码为 1，execFileSync 抛出异常
+    mockExecFileSync.mockImplementation(() => { throw new Error('exit code 1'); });
+    const result = gitCheckIgnored(['src/index.ts']);
+    expect(result).toEqual([]);
+  });
+
+  it('混合场景时仅返回被忽略的路径', () => {
+    mockExecFileSync.mockReturnValue('docs/superpowers/a.md\n');
+    const result = gitCheckIgnored(['docs/superpowers/a.md', 'src/index.ts']);
+    expect(result).toEqual(['docs/superpowers/a.md']);
+  });
+});

package/tests/unit/utils/validate-core.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../../src/utils/git-core.js', async () => {
+  const actual = await vi.importActual('../../../src/utils/git-core.js');
+  return { ...actual, gitCheckIgnored: vi.fn() };
+});
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  mkdirSync: vi.fn(),
+}));
+
+vi.mock('../../../src/utils/shell.js', async () => {
+  const actual = await vi.importActual('../../../src/utils/shell.js');
+  return { ...actual, execCommand: vi.fn() };
+});
+
+import { detectIgnoredFilesInPatch } from '../../../src/utils/validate-core.js';
+import { gitCheckIgnored } from '../../../src/utils/git-core.js';
+import { existsSync } from 'node:fs';
+import { execCommand } from '../../../src/utils/shell.js';
+
+const mockGitCheckIgnored = vi.mocked(gitCheckIgnored);
+const mockExistsSync = vi.mocked(existsSync);
+const mockExecCommand = vi.mocked(execCommand);
+
+describe('detectIgnoredFilesInPatch', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('无幽灵文件时返回空数组', () => {
+    mockExecCommand.mockReturnValue('src/a.ts\nsrc/b.ts');
+    mockGitCheckIgnored.mockReturnValue([]);
+    const result = detectIgnoredFilesInPatch('feature', '/main');
+    expect(result).toEqual([]);
+  });
+
+  it('检测到幽灵文件时返回文件列表', () => {
+    mockExecCommand.mockReturnValue('docs/superpowers/a.md\nsrc/b.ts');
+    mockGitCheckIgnored.mockReturnValue(['docs/superpowers/a.md']);
+    mockExistsSync.mockImplementation((p: string) => p === '/main/docs/superpowers/a.md');
+    const result = detectIgnoredFilesInPatch('feature', '/main');
+    expect(result).toEqual(['docs/superpowers/a.md']);
+  });
+
+  it('被忽略但物理不存在的文件不包含在结果中', () => {
+    mockExecCommand.mockReturnValue('docs/superpowers/a.md');
+    mockGitCheckIgnored.mockReturnValue(['docs/superpowers/a.md']);
+    mockExistsSync.mockReturnValue(false);
+    const result = detectIgnoredFilesInPatch('feature', '/main');
+    expect(result).toEqual([]);
+  });
+
+  it('git diff --name-only 失败时返回空数组（降级）', () => {
+    mockExecCommand.mockImplementation(() => { throw new Error('fatal'); });
+    const result = detectIgnoredFilesInPatch('feature', '/main');
+    expect(result).toEqual([]);
+  });
+});