clawt 3.10.3 → 3.10.5

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.3",
+  "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';