clawt 3.1.3 → 3.2.0

package/src/commands/validate.ts

@@ -1,6 +1,5 @@
 import type { Command } from 'commander';
 import { logger } from '../logger/index.js';
-import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import type { ValidateOptions } from '../types/index.js';
 import { executeSyncForBranch } from './sync.js';
@@ -11,21 +10,10 @@ import {
   getProjectWorktrees,
   getConfigValue,
   isWorkingDirClean,
-  gitAddAll,
-  gitCommit,
-  gitRestoreStaged,
   gitResetHard,
   gitCleanForce,
-  gitDiffBinaryAgainstBranch,
-  gitApplyFromStdin,
-  gitApplyCachedFromStdin,
-  gitResetSoft,
-  gitWriteTree,
   gitReadTree,
   getHeadCommitHash,
-  getCommitTreeHash,
-  gitDiffTree,
-  gitApplyCachedCheck,
   hasLocalCommits,
   hasSnapshot,
   readSnapshot,
@@ -34,24 +22,21 @@ import {
   confirmDestructiveAction,
   confirmAction,
   printSuccess,
-  printError,
   printWarning,
   printInfo,
-  printSeparator,
   resolveTargetWorktree,
-  runCommandInherited,
-  parseParallelCommands,
-  runParallelCommands,
   requireProjectConfig,
-  getValidateBranchName,
-  gitCheckout,
   ensureOnMainWorkBranch,
-  checkBranchExists,
-  getCurrentBranch,
   handleDirtyWorkingDir,
   getValidateRunCommand,
+  executeRunCommand,
+  migrateChangesViaPatch,
+  computeCurrentTreeHash,
+  saveCurrentSnapshotTree,
+  loadOldSnapshotToStage,
+  switchToValidateBranch,
 } from '../utils/index.js';
-import type { WorktreeResolveMessages, ParallelCommandResult } from '../utils/index.js';
+import type { WorktreeResolveMessages } from '../utils/index.js';
 
 /** validate 命令的分支解析消息配置 */
 const VALIDATE_RESOLVE_MESSAGES: WorktreeResolveMessages = {
@@ -86,59 +71,6 @@ async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void>
   await handleDirtyWorkingDir(mainWorktreePath);
 }
 
-/**
- * 通过 patch 将目标分支的全量变更（已提交 + 未提交）迁移到主 worktree
- * 使用 git diff HEAD...branch --binary 获取变更，避免 stash 方式无法检测已提交 commit 的问题
- * @param {string} targetWorktreePath - 目标 worktree 路径
- * @param {string} mainWorktreePath - 主 worktree 路径
- * @param {string} branchName - 分支名
- * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
- * @returns {{ success: boolean }} patch 迁移结果
- */
-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);
-
-    // 应用 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 {
-    // 确保临时 commit 一定会被撤销，恢复目标 worktree 原状
-    // 每个操作独立 try-catch，避免前一个失败导致后续操作不执行
-    if (didTempCommit) {
-      try {
-        gitResetSoft(1, targetWorktreePath);
-      } catch (error) {
-        logger.error(`撤销临时 commit 失败: ${error}`);
-      }
-      try {
-        gitRestoreStaged(targetWorktreePath);
-      } catch (error) {
-        logger.error(`恢复暂存区失败: ${error}`);
-      }
-    }
-  }
-}
-
 /**
  * patch apply 失败后的交互处理：询问用户是否自动执行 sync
  * @param {string} targetWorktreePath - 目标 worktree 路径
@@ -161,24 +93,6 @@ async function handlePatchApplyFailure(targetWorktreePath: string, branchName: s
   // sync 冲突提示已在 executeSyncForBranch 内部输出（SYNC_CONFLICT），此处无需重复提示
 }
 
-/**
- * 保存当前主 worktree 工作目录变更为 git tree 对象快照
- * 操作序列：git add . → git write-tree → git restore --staged .
- * 同时保存当前 HEAD commit hash，用于增量 validate 时对齐基准
- * @param {string} mainWorktreePath - 主 worktree 路径
- * @param {string} projectName - 项目名
- * @param {string} branchName - 分支名
- * @returns {string} 生成的 tree hash
- */
-function saveCurrentSnapshotTree(mainWorktreePath: string, projectName: string, branchName: string): string {
-  gitAddAll(mainWorktreePath);
-  const treeHash = gitWriteTree(mainWorktreePath);
-  gitRestoreStaged(mainWorktreePath);
-  const headCommitHash = getHeadCommitHash(mainWorktreePath);
-  writeSnapshot(projectName, branchName, treeHash, headCommitHash);
-  return treeHash;
-}
-
 /**
  * 处理 --clean 选项：清理 validate 状态
  * @param {ValidateOptions} options - 命令选项
@@ -235,11 +149,7 @@ async function handleValidateClean(options: ValidateOptions): Promise<void> {
  */
 async function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): Promise<void> {
   // 切换主 worktree 到验证分支
-  const validateBranchName = getValidateBranchName(branchName);
-  if (!checkBranchExists(validateBranchName)) {
-    throw new ClawtError(MESSAGES.VALIDATE_BRANCH_NOT_FOUND(validateBranchName, branchName));
-  }
-  gitCheckout(validateBranchName, mainWorktreePath);
+  const validateBranchName = switchToValidateBranch(branchName, mainWorktreePath);
 
   // 通过 patch 迁移目标分支全量变更到主 worktree
   const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
@@ -267,8 +177,8 @@ async function handleFirstValidate(targetWorktreePath: string, mainWorktreePath:
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
 async function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): Promise<void> {
-  // 步骤 1：读取旧快照（tree hash + 当时的 HEAD commit hash）
-  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
+  // 步骤 1：读取旧快照（tree hash + 当时的 HEAD commit hash + 暂存区 tree hash）
+  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash, stagedTreeHash: oldStagedTreeHash } = readSnapshot(projectName, branchName);
 
   // 步骤 2：确保主 worktree 干净（调用方已通过 handleDirtyMainWorktree 处理）
   // 这里做兜底清理，防止 handleDirtyMainWorktree 之后仍有残留
@@ -278,14 +188,7 @@ async function handleIncrementalValidate(targetWorktreePath: string, mainWorktre
   }
 
   // 步骤 3：切换到验证分支（如果已在该分支上则跳过）
-  const validateBranchName = getValidateBranchName(branchName);
-  if (!checkBranchExists(validateBranchName)) {
-    throw new ClawtError(MESSAGES.VALIDATE_BRANCH_NOT_FOUND(validateBranchName, branchName));
-  }
-  const currentBranch = getCurrentBranch(mainWorktreePath);
-  if (currentBranch !== validateBranchName) {
-    gitCheckout(validateBranchName, mainWorktreePath);
-  }
+  const validateBranchName = switchToValidateBranch(branchName, mainWorktreePath);
 
   // 步骤 4：通过 patch 从目标分支获取最新全量变更
   const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
@@ -297,140 +200,45 @@ async function handleIncrementalValidate(targetWorktreePath: string, mainWorktre
     return;
   }
 
-  // 步骤 5：保存最新快照为 git tree 对象（同时记录当前 HEAD）
-  saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
+  // 步骤 5：计算当前变更的 tree hash，检测是否有新变更
+  const newTreeHash = computeCurrentTreeHash(mainWorktreePath);
+  const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
 
-  // 步骤 6：将旧变更状态载入暂存区
-  try {
-    const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
-
-    if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
-      // HEAD 发生了变化：
-      // 将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，
-      // 避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容
-      const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
-      const oldChangePatch = gitDiffTree(oldHeadTreeHash, oldTreeHash, mainWorktreePath);
-
-      if (oldChangePatch.length > 0 && gitApplyCachedCheck(oldChangePatch, mainWorktreePath)) {
-        // 无冲突：apply --cached 到当前 HEAD 暂存区
-        gitApplyCachedFromStdin(oldChangePatch, mainWorktreePath);
-      } else if (oldChangePatch.length > 0) {
-        // 有冲突：降级为全量模式（暂存区保持为空）
-        logger.warn('旧变更 patch 与当前 HEAD 冲突，降级为全量模式');
-        printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
-        printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
-        return;
+  // 检测目标 worktree 自上次 validate 以来是否有新变更
+  const hasNewChanges = newTreeHash !== oldTreeHash
+    || (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash);
+
+  if (!hasNewChanges) {
+    // 无新变更：不更新快照，恢复到上次 validate 结束时的完整状态
+    if (oldStagedTreeHash) {
+      try {
+        gitReadTree(oldStagedTreeHash, mainWorktreePath);
+      } catch (error) {
+        logger.warn(`恢复暂存区失败: ${error}`);
       }
-      // oldChangePatch 为空表示旧变更为空，暂存区保持干净即可
-    } else {
-      // HEAD 未变化（或旧版快照无 HEAD 信息）：直接 read-tree 旧快照
-      gitReadTree(oldTreeHash, mainWorktreePath);
     }
-  } catch (error) {
-    // 旧 tree 对象无法读取（可能被 git gc 回收），降级为全量模式
-    logger.warn(`增量 read-tree 失败: ${error}`);
-    printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
-    // 降级后暂存区保持为空，工作目录为最新全量变更，与首次 validate 一致
+    printInfo(MESSAGES.INCREMENTAL_VALIDATE_NO_CHANGES(branchName));
     printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
     return;
   }
 
-  // 结果：暂存区=上次快照，工作目录=最新全量变更
-  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
-}
-
-/**
- * 执行单个命令（同步方式，保持原有行为不变）
- * @param {string} command - 要执行的命令字符串
- * @param {string} mainWorktreePath - 主 worktree 路径
- */
-function executeSingleCommand(command: string, mainWorktreePath: string): void {
-  printInfo(MESSAGES.VALIDATE_RUN_START(command));
-  printSeparator();
-
-  const result = runCommandInherited(command, { cwd: mainWorktreePath });
+  // 有新变更：执行暂存区载入并记录 stagedTreeHash
 
-  printSeparator();
-
-  if (result.error) {
-    // 进程启动失败（如命令不存在）
-    printError(MESSAGES.VALIDATE_RUN_ERROR(command, result.error.message));
+  // 步骤 6：将旧变更状态载入暂存区
+  const stageResult = loadOldSnapshotToStage(oldTreeHash, oldHeadCommitHash, currentHeadCommitHash, mainWorktreePath);
+  if (!stageResult.success) {
+    printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+    // 降级后暂存区保持为空，工作目录为最新全量变更，与首次 validate 一致
+    writeSnapshot(projectName, branchName, newTreeHash, currentHeadCommitHash, '');
+    printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
     return;
   }
 
-  const exitCode = result.status ?? 1;
-  if (exitCode === 0) {
-    printSuccess(MESSAGES.VALIDATE_RUN_SUCCESS(command));
-  } else {
-    printError(MESSAGES.VALIDATE_RUN_FAILED(command, exitCode));
-  }
-}
-
-/**
- * 汇总输出并行命令的执行结果
- * @param {ParallelCommandResult[]} results - 各命令的执行结果数组
- */
-function reportParallelResults(results: ParallelCommandResult[]): void {
-  printSeparator();
-
-  const successCount = results.filter((r) => r.exitCode === 0 && !r.error).length;
-  const failedCount = results.length - successCount;
-
-  for (const result of results) {
-    if (result.error) {
-      printError(MESSAGES.VALIDATE_PARALLEL_CMD_ERROR(result.command, result.error));
-    } else if (result.exitCode === 0) {
-      printSuccess(MESSAGES.VALIDATE_PARALLEL_CMD_SUCCESS(result.command));
-    } else {
-      printError(MESSAGES.VALIDATE_PARALLEL_CMD_FAILED(result.command, result.exitCode));
-    }
-  }
-
-  if (failedCount === 0) {
-    printSuccess(MESSAGES.VALIDATE_PARALLEL_RUN_ALL_SUCCESS(results.length));
-  } else {
-    printError(MESSAGES.VALIDATE_PARALLEL_RUN_SUMMARY(successCount, failedCount));
-  }
-}
-
-/**
- * 并行执行多个命令并汇总结果
- * @param {string[]} commands - 要并行执行的命令数组
- * @param {string} mainWorktreePath - 主 worktree 路径
- */
-async function executeParallelCommands(commands: string[], mainWorktreePath: string): Promise<void> {
-  printInfo(MESSAGES.VALIDATE_PARALLEL_RUN_START(commands.length));
+  // 步骤 7：写入新快照（包含 stagedTreeHash 供下次无变更时恢复用）
+  writeSnapshot(projectName, branchName, newTreeHash, currentHeadCommitHash, stageResult.stagedTreeHash);
 
-  for (let i = 0; i < commands.length; i++) {
-    printInfo(MESSAGES.VALIDATE_PARALLEL_CMD_START(i + 1, commands.length, commands[i]));
-  }
-
-  printSeparator();
-
-  const results = await runParallelCommands(commands, { cwd: mainWorktreePath });
-
-  reportParallelResults(results);
-}
-
-/**
- * 在主 worktree 中执行用户指定的命令
- * 根据命令字符串中的 & 分隔符决定是单命令执行还是并行执行
- * 命令执行失败不影响 validate 本身的结果，仅输出提示
- * @param {string} command - 要执行的命令字符串
- * @param {string} mainWorktreePath - 主 worktree 路径
- */
-async function executeRunCommand(command: string, mainWorktreePath: string): Promise<void> {
-  printInfo('');
-
-  const commands = parseParallelCommands(command);
-
-  if (commands.length <= 1) {
-    // 单命令（包括含 && 的串行命令），走原有同步路径
-    executeSingleCommand(commands[0] || command, mainWorktreePath);
-  } else {
-    // 多命令，并行执行
-    await executeParallelCommands(commands, mainWorktreePath);
-  }
+  // 结果：暂存区=上次快照，工作目录=最新全量变更
+  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
 }
 
 /**

package/src/constants/messages/validate.ts

@@ -8,6 +8,9 @@ export const VALIDATE_MESSAGES = {
     `✓ 已将分支 ${branch} 的最新变更应用到主 worktree（增量模式）\n  暂存区 = 上次快照，工作目录 = 最新变更`,
   /** 增量 validate 降级为全量模式提示 */
   INCREMENTAL_VALIDATE_FALLBACK: '增量对比失败，已降级为全量模式',
+  /** 增量 validate 检测到目标 worktree 无新变更 */
+  INCREMENTAL_VALIDATE_NO_CHANGES: (branch: string) =>
+    `分支 ${branch} 自上次 validate 以来没有新的变更，已恢复到上次验证状态`,
   /** validate 状态已清理 */
   VALIDATE_CLEANED: (branch: string) => `✓ 分支 ${branch} 的 validate 状态已清理`,
   /** validate patch apply 失败，提示用户同步主分支 */

package/src/utils/index.ts

@@ -73,6 +73,8 @@ export { checkForUpdates } from './update-checker.js';
 export { getProjectConfigPath, loadProjectConfig, saveProjectConfig, requireProjectConfig, getMainWorkBranch, getValidateRunCommand } from './project-config.js';
 export { getValidateBranchName, createValidateBranch, deleteValidateBranch, rebuildValidateBranch, ensureOnMainWorkBranch, handleDirtyWorkingDir } from './validate-branch.js';
 export { safeStringify } from './json.js';
+export { executeRunCommand } from './validate-runner.js';
+export { migrateChangesViaPatch, computeCurrentTreeHash, saveCurrentSnapshotTree, loadOldSnapshotToStage, switchToValidateBranch } 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

@@ -0,0 +1,174 @@
+import { logger } from '../logger/index.js';
+import { ClawtError } from '../errors/index.js';
+import { MESSAGES } from '../constants/index.js';
+import {
+  gitAddAll,
+  gitCommit,
+  gitRestoreStaged,
+  gitDiffBinaryAgainstBranch,
+  gitApplyFromStdin,
+  gitApplyCachedFromStdin,
+  gitResetSoft,
+  gitWriteTree,
+  gitReadTree,
+  getCommitTreeHash,
+  gitDiffTree,
+  gitApplyCachedCheck,
+  getValidateBranchName,
+  checkBranchExists,
+  gitCheckout,
+  getCurrentBranch,
+  getHeadCommitHash,
+  writeSnapshot,
+  printWarning,
+} from './index.js';
+
+/**
+ * 通过 patch 将目标分支的全量变更（已提交 + 未提交）迁移到主 worktree
+ * 使用 git diff HEAD...branch --binary 获取变更，避免 stash 方式无法检测已提交 commit 的问题
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} branchName - 分支名
+ * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
+ * @returns {{ success: boolean }} patch 迁移结果
+ */
+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);
+
+    // 应用 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 {
+    // 确保临时 commit 一定会被撤销，恢复目标 worktree 原状
+    // 每个操作独立 try-catch，避免前一个失败导致后续操作不执行
+    if (didTempCommit) {
+      try {
+        gitResetSoft(1, targetWorktreePath);
+      } catch (error) {
+        logger.error(`撤销临时 commit 失败: ${error}`);
+      }
+      try {
+        gitRestoreStaged(targetWorktreePath);
+      } catch (error) {
+        logger.error(`恢复暂存区失败: ${error}`);
+      }
+    }
+  }
+}
+
+/**
+ * 计算当前主 worktree 工作目录变更的 git tree hash
+ * 操作序列：git add . → git write-tree → git restore --staged .
+ * 仅计算 tree hash，不写入快照文件
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @returns {string} 当前工作目录变更对应的 tree hash
+ */
+export function computeCurrentTreeHash(mainWorktreePath: string): string {
+  gitAddAll(mainWorktreePath);
+  const treeHash = gitWriteTree(mainWorktreePath);
+  gitRestoreStaged(mainWorktreePath);
+  return treeHash;
+}
+
+/**
+ * 保存当前主 worktree 工作目录变更为 git tree 对象快照
+ * 操作序列：git add . → git write-tree → git restore --staged .
+ * 同时保存当前 HEAD commit hash，用于增量 validate 时对齐基准
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @param {string} [stagedTreeHash=''] - validate 结束时暂存区对应的 tree hash
+ * @returns {string} 生成的 tree hash
+ */
+export function saveCurrentSnapshotTree(mainWorktreePath: string, projectName: string, branchName: string, stagedTreeHash = ''): string {
+  gitAddAll(mainWorktreePath);
+  const treeHash = gitWriteTree(mainWorktreePath);
+  gitRestoreStaged(mainWorktreePath);
+  const headCommitHash = getHeadCommitHash(mainWorktreePath);
+  writeSnapshot(projectName, branchName, treeHash, headCommitHash, stagedTreeHash);
+  return treeHash;
+}
+
+/**
+ * 将旧快照载入暂存区（从 handleIncrementalValidate 步骤 6 提取）
+ * 根据 HEAD 是否变化，选择不同的载入策略：
+ * - HEAD 变化：将旧变更 patch 重放到当前 HEAD 暂存区上
+ * - HEAD 未变化：直接 read-tree 旧快照
+ * @param {string} oldTreeHash - 旧快照的 tree hash
+ * @param {string} oldHeadCommitHash - 旧快照时的 HEAD commit hash
+ * @param {string} currentHeadCommitHash - 当前的 HEAD commit hash
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @returns {{ success: boolean; stagedTreeHash: string }} 载入结果
+ */
+export function loadOldSnapshotToStage(oldTreeHash: string, oldHeadCommitHash: string, currentHeadCommitHash: string, mainWorktreePath: string): { success: boolean; stagedTreeHash: string } {
+  try {
+    if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
+      // HEAD 发生了变化：
+      // 将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，
+      // 避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容
+      const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
+      const oldChangePatch = gitDiffTree(oldHeadTreeHash, oldTreeHash, mainWorktreePath);
+
+      if (oldChangePatch.length > 0 && gitApplyCachedCheck(oldChangePatch, mainWorktreePath)) {
+        // 无冲突：apply --cached 到当前 HEAD 暂存区
+        gitApplyCachedFromStdin(oldChangePatch, mainWorktreePath);
+        // 记录暂存区的 tree hash（gitWriteTree 不修改暂存区内容，仅生成 tree 对象）
+        const stagedTreeHash = gitWriteTree(mainWorktreePath);
+        return { success: true, stagedTreeHash };
+      } else if (oldChangePatch.length > 0) {
+        // 有冲突：降级为全量模式（暂存区保持为空）
+        logger.warn('旧变更 patch 与当前 HEAD 冲突，降级为全量模式');
+        return { success: false, stagedTreeHash: '' };
+      }
+      // oldChangePatch 为空表示旧变更为空，暂存区保持干净即可
+      return { success: true, stagedTreeHash: '' };
+    } else {
+      // HEAD 未变化（或旧版快照无 HEAD 信息）：直接 read-tree 旧快照
+      gitReadTree(oldTreeHash, mainWorktreePath);
+      return { success: true, stagedTreeHash: oldTreeHash };
+    }
+  } catch (error) {
+    // 旧 tree 对象无法读取（可能被 git gc 回收），降级为全量模式
+    logger.warn(`增量 read-tree 失败: ${error}`);
+    return { success: false, stagedTreeHash: '' };
+  }
+}
+
+/**
+ * 切换到验证分支（首次/增量 validate 共享逻辑）
+ * 校验验证分支是否存在，若当前不在该分支则执行 checkout
+ * @param {string} branchName - 原始分支名
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @returns {string} 验证分支名
+ */
+export function switchToValidateBranch(branchName: string, mainWorktreePath: string): string {
+  const validateBranchName = getValidateBranchName(branchName);
+  if (!checkBranchExists(validateBranchName)) {
+    throw new ClawtError(MESSAGES.VALIDATE_BRANCH_NOT_FOUND(validateBranchName, branchName));
+  }
+  const currentBranch = getCurrentBranch(mainWorktreePath);
+  if (currentBranch !== validateBranchName) {
+    gitCheckout(validateBranchName, mainWorktreePath);
+  }
+  return validateBranchName;
+}

package/src/utils/validate-runner.ts

@@ -0,0 +1,105 @@
+import { MESSAGES } from '../constants/index.js';
+import {
+  printInfo,
+  printSuccess,
+  printError,
+  printSeparator,
+  runCommandInherited,
+  parseParallelCommands,
+  runParallelCommands,
+} from './index.js';
+import type { ParallelCommandResult } from './index.js';
+
+/**
+ * 执行单个命令（同步方式，保持原有行为不变）
+ * @param {string} command - 要执行的命令字符串
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ */
+function executeSingleCommand(command: string, mainWorktreePath: string): void {
+  printInfo(MESSAGES.VALIDATE_RUN_START(command));
+  printSeparator();
+
+  const result = runCommandInherited(command, { cwd: mainWorktreePath });
+
+  printSeparator();
+
+  if (result.error) {
+    // 进程启动失败（如命令不存在）
+    printError(MESSAGES.VALIDATE_RUN_ERROR(command, result.error.message));
+    return;
+  }
+
+  const exitCode = result.status ?? 1;
+  if (exitCode === 0) {
+    printSuccess(MESSAGES.VALIDATE_RUN_SUCCESS(command));
+  } else {
+    printError(MESSAGES.VALIDATE_RUN_FAILED(command, exitCode));
+  }
+}
+
+/**
+ * 汇总输出并行命令的执行结果
+ * @param {ParallelCommandResult[]} results - 各命令的执行结果数组
+ */
+function reportParallelResults(results: ParallelCommandResult[]): void {
+  printSeparator();
+
+  const successCount = results.filter((r) => r.exitCode === 0 && !r.error).length;
+  const failedCount = results.length - successCount;
+
+  for (const result of results) {
+    if (result.error) {
+      printError(MESSAGES.VALIDATE_PARALLEL_CMD_ERROR(result.command, result.error));
+    } else if (result.exitCode === 0) {
+      printSuccess(MESSAGES.VALIDATE_PARALLEL_CMD_SUCCESS(result.command));
+    } else {
+      printError(MESSAGES.VALIDATE_PARALLEL_CMD_FAILED(result.command, result.exitCode));
+    }
+  }
+
+  if (failedCount === 0) {
+    printSuccess(MESSAGES.VALIDATE_PARALLEL_RUN_ALL_SUCCESS(results.length));
+  } else {
+    printError(MESSAGES.VALIDATE_PARALLEL_RUN_SUMMARY(successCount, failedCount));
+  }
+}
+
+/**
+ * 并行执行多个命令并汇总结果
+ * @param {string[]} commands - 要并行执行的命令数组
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ */
+async function executeParallelCommands(commands: string[], mainWorktreePath: string): Promise<void> {
+  printInfo(MESSAGES.VALIDATE_PARALLEL_RUN_START(commands.length));
+
+  for (let i = 0; i < commands.length; i++) {
+    printInfo(MESSAGES.VALIDATE_PARALLEL_CMD_START(i + 1, commands.length, commands[i]));
+  }
+
+  printSeparator();
+
+  const results = await runParallelCommands(commands, { cwd: mainWorktreePath });
+
+  reportParallelResults(results);
+}
+
+/**
+ * 在主 worktree 中执行用户指定的命令
+ * 根据命令字符串中的 & 分隔符决定是单命令执行还是并行执行
+ * 命令执行失败不影响 validate 本身的结果，仅输出提示
+ * @param {string} command - 要执行的命令字符串
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ */
+export async function executeRunCommand(command: string, mainWorktreePath: string): Promise<void> {
+  printInfo('');
+
+  const commands = parseParallelCommands(command);
+
+  if (commands.length <= 1) {
+    // 单命令（包括含 && 的串行命令），走原有同步路径
+    executeSingleCommand(commands[0] || command, mainWorktreePath);
+  } else {
+    // 多命令，并行执行
+    await executeParallelCommands(commands, mainWorktreePath);
+  }
+}