clawt 3.4.3 → 3.4.5

package/dist/index.js

@@ -535,6 +535,8 @@ var PANEL_SHORTCUT_KEYS = {
   RESUME: "r",
   /** 同步 */
   SYNC: "s",
+  /** 覆盖 */
+  COVER: "c",
   /** 手动刷新 */
   REFRESH: "f",
   /** 退出 */
@@ -550,6 +552,7 @@ var SHORTCUT_LABELS = {
   DELETE: "\u5220\u9664",
   RESUME: "\u6062\u590D",
   SYNC: "\u540C\u6B65",
+  COVER: "\u8986\u76D6",
   REFRESH: "\u5237\u65B0",
   QUIT: "\u9000\u51FA"
 };
@@ -748,6 +751,32 @@ var GROUP_SEPARATOR_LABEL = (dateLabel, relativeTime) => `\u2550\u2550\u2550\u25
 var UNKNOWN_DATE_GROUP = "\u672A\u77E5\u65E5\u671F";
 var UNKNOWN_DATE_SEPARATOR_LABEL = `\u2550\u2550\u2550\u2550 ${chalk2.bold.hex("#FF8C00")("\u672A\u77E5\u65E5\u671F")} \u2550\u2550\u2550\u2550`;
 
+// src/constants/pre-checks.ts
+var PRE_CHECK_CREATE = {
+  requireMainWorktree: true,
+  requireHead: true,
+  ensureOnClawtMainWorkBranch: true,
+  requireCleanWorkingDir: true
+};
+var PRE_CHECK_RUN = { ...PRE_CHECK_CREATE };
+var PRE_CHECK_DRY_RUN = { requireMainWorktree: true, requireHead: true };
+var PRE_CHECK_MERGE = {
+  requireMainWorktree: true,
+  requireHead: true,
+  ensureOnClawtMainWorkBranch: true
+};
+var PRE_CHECK_SYNC = {
+  requireMainWorktree: true,
+  requireHead: true,
+  requireProjectConfig: true,
+  ensureOnClawtMainWorkBranch: true
+};
+var PRE_CHECK_RESUME = {
+  requireMainWorktree: true,
+  requireHead: true,
+  requireClaudeCode: true
+};
+
 // src/errors/index.ts
 var ClawtError = class extends Error {
   /** 退出码 */
@@ -1063,17 +1092,6 @@ function gitApplyCachedCheck(patchContent, cwd) {
     return false;
   }
 }
-function getBranchCreatedAt(branchName, cwd) {
-  try {
-    const output = execCommand(`git reflog show ${branchName} --format=%cI`, { cwd });
-    if (!output.trim()) return null;
-    const lines = output.trim().split("\n");
-    const lastLine = lines[lines.length - 1];
-    return lastLine || null;
-  } catch {
-    return null;
-  }
-}
 function gitCheckout(branchName, cwd) {
   execCommand(`git checkout ${branchName}`, { cwd });
 }
@@ -1321,71 +1339,11 @@ function guardMainWorkBranchExists(cwd) {
     throw new ClawtError(MESSAGES.GUARD_BRANCH_NOT_EXISTS(mainBranch));
   }
 }
-async function guardMainWorkBranch(cwd) {
-  guardMainWorkBranchExists(cwd);
-  const config2 = requireProjectConfig();
-  const mainBranch = config2.clawtMainWorkBranch;
-  const currentBranch = getCurrentBranch(cwd);
-  if (currentBranch !== mainBranch && !currentBranch.startsWith(VALIDATE_BRANCH_PREFIX)) {
-    printWarning(MESSAGES.GUARD_BRANCH_MISMATCH(mainBranch, currentBranch));
-    const confirmed = await confirmAction("\u662F\u5426\u7EE7\u7EED\u6267\u884C\uFF1F");
-    if (!confirmed) {
-      throw new ClawtError(MESSAGES.DESTRUCTIVE_OP_CANCELLED);
-    }
-  }
-}
 function getValidateRunCommand() {
   const config2 = loadProjectConfig();
   return config2?.validateRunCommand || void 0;
 }
 
-// src/utils/validation.ts
-function validateMainWorktree() {
-  try {
-    const gitCommonDir = getGitCommonDir();
-    if (gitCommonDir !== ".git") {
-      throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
-    }
-  } catch (error) {
-    if (error instanceof ClawtError) {
-      throw error;
-    }
-    throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
-  }
-}
-function validateClaudeCodeInstalled() {
-  try {
-    execCommand("claude --version");
-  } catch {
-    throw new ClawtError(MESSAGES.CLAUDE_NOT_INSTALLED);
-  }
-}
-function validateHeadExists() {
-  try {
-    execCommand("git rev-parse --verify HEAD");
-  } catch {
-    throw new ClawtError(MESSAGES.HEAD_NOT_FOUND);
-  }
-}
-function runPreChecks(options) {
-  if (options.mainWorktree) {
-    validateMainWorktree();
-  }
-  if (options.headExists) {
-    validateHeadExists();
-  }
-  if (options.projectConfig) {
-    requireProjectConfig();
-  }
-  if (options.branchExists) {
-    guardMainWorkBranchExists();
-  }
-}
-
-// src/utils/worktree.ts
-import { join as join4 } from "path";
-import { existsSync as existsSync4, readdirSync as readdirSync2 } from "fs";
-
 // src/utils/validate-branch.ts
 import Enquirer from "enquirer";
 function getValidateBranchName(branchName) {
@@ -1476,6 +1434,11 @@ async function ensureOnMainWorkBranch(cwd) {
     gitCheckout(mainBranch, cwd);
     return;
   }
+  printWarning(MESSAGES.GUARD_BRANCH_MISMATCH(mainBranch, currentBranch));
+  const confirmed = await confirmAction("\u662F\u5426\u7EE7\u7EED\u6267\u884C\uFF1F");
+  if (!confirmed) {
+    throw new ClawtError(MESSAGES.DESTRUCTIVE_OP_CANCELLED);
+  }
   logger.info(`\u5F53\u524D\u5728\u5206\u652F ${currentBranch} \u4E0A\uFF0C\u9700\u5207\u6362\u5230\u4E3B\u5DE5\u4F5C\u5206\u652F ${mainBranch}`);
   if (!isWorkingDirClean(cwd)) {
     await handleDirtyWorkingDir(cwd);
@@ -1483,7 +1446,66 @@ async function ensureOnMainWorkBranch(cwd) {
   gitCheckout(mainBranch, cwd);
 }
 
+// src/utils/validation.ts
+function validateMainWorktree() {
+  try {
+    const gitCommonDir = getGitCommonDir();
+    if (gitCommonDir !== ".git") {
+      throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
+    }
+  } catch (error) {
+    if (error instanceof ClawtError) {
+      throw error;
+    }
+    throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
+  }
+}
+function validateClaudeCodeInstalled() {
+  try {
+    execCommand("claude --version");
+  } catch {
+    throw new ClawtError(MESSAGES.CLAUDE_NOT_INSTALLED);
+  }
+}
+function validateHeadExists() {
+  try {
+    execCommand("git rev-parse --verify HEAD");
+  } catch {
+    throw new ClawtError(MESSAGES.HEAD_NOT_FOUND);
+  }
+}
+function validateWorkingDirClean() {
+  if (!isWorkingDirClean()) {
+    throw new ClawtError(MESSAGES.MAIN_WORKTREE_DIRTY);
+  }
+}
+async function runPreChecks(options) {
+  if (options.requireMainWorktree) {
+    validateMainWorktree();
+  }
+  if (options.requireHead) {
+    validateHeadExists();
+  }
+  if (options.requireProjectConfig) {
+    requireProjectConfig();
+  }
+  if (options.requireMainBranchExists) {
+    guardMainWorkBranchExists();
+  }
+  if (options.ensureOnClawtMainWorkBranch) {
+    await ensureOnMainWorkBranch();
+  }
+  if (options.requireCleanWorkingDir) {
+    validateWorkingDirClean();
+  }
+  if (options.requireClaudeCode) {
+    validateClaudeCodeInstalled();
+  }
+}
+
 // src/utils/worktree.ts
+import { join as join4 } from "path";
+import { existsSync as existsSync4, readdirSync as readdirSync2 } from "fs";
 function getProjectWorktreeDir() {
   const projectName = getProjectName();
   return join4(WORKTREES_DIR, projectName);
@@ -1963,6 +1985,14 @@ function getWorktreeCreatedDate(dirPath) {
     return null;
   }
 }
+function getWorktreeCreatedTime(dirPath) {
+  try {
+    const stat = statSync3(dirPath);
+    return stat.birthtime.toISOString();
+  } catch {
+    return null;
+  }
+}
 function formatRelativeDate(dateStr) {
   const today = formatLocalDate(/* @__PURE__ */ new Date());
   const todayMs = new Date(today).getTime();
@@ -3580,6 +3610,10 @@ var InteractivePanel = class {
       this.executeOperation(() => this.handleSync());
       return;
     }
+    if (key === PANEL_SHORTCUT_KEYS.COVER) {
+      this.executeOperation(() => this.handleCover());
+      return;
+    }
   }
   /**
    * 向上导航，选中显示顺序中的上一个 worktree
@@ -3792,6 +3826,13 @@ var InteractivePanel = class {
     const branch = this.getSelectedBranch();
     runCommandInherited(`clawt sync -b ${branch}`);
   }
+  /**
+   * 执行覆盖操作
+   * cover 命令从主 worktree 当前所在的验证分支名自动推导目标分支
+   */
+  handleCover() {
+    runCommandInherited("clawt cover");
+  }
   /**
    * 等待用户按回车键
    * @returns {Promise<void>} 用户按回车时 resolve
@@ -3813,12 +3854,12 @@ var InteractivePanel = class {
 // src/commands/list.ts
 import chalk10 from "chalk";
 function registerListCommand(program2) {
-  program2.command("list").description("\u5217\u51FA\u5F53\u524D\u9879\u76EE\u6240\u6709 worktree\uFF08\u652F\u6301 --json \u683C\u5F0F\u8F93\u51FA\uFF09").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((options) => {
-    handleList(options);
+  program2.command("list").description("\u5217\u51FA\u5F53\u524D\u9879\u76EE\u6240\u6709 worktree\uFF08\u652F\u6301 --json \u683C\u5F0F\u8F93\u51FA\uFF09").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action(async (options) => {
+    await handleList(options);
   });
 }
-function handleList(options) {
-  runPreChecks({ mainWorktree: true });
+async function handleList(options) {
+  await runPreChecks({ requireMainWorktree: true });
   const projectName = getProjectName();
   const worktrees = getProjectWorktrees();
   logger.info(`list \u547D\u4EE4\u6267\u884C\uFF0C\u9879\u76EE: ${projectName}\uFF0C\u5171 ${worktrees.length} \u4E2A worktree`);
@@ -3868,9 +3909,7 @@ function registerCreateCommand(program2) {
   });
 }
 async function handleCreate(options) {
-  runPreChecks({ mainWorktree: true, headExists: true });
-  await guardMainWorkBranch();
-  await ensureOnMainWorkBranch();
+  await runPreChecks(PRE_CHECK_CREATE);
   const count = Number(options.number);
   if (!Number.isInteger(count) || count <= 0) {
     throw new ClawtError(
@@ -3904,7 +3943,7 @@ function registerRemoveCommand(program2) {
   });
 }
 async function handleRemove(options) {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true });
   const projectName = getProjectName();
   logger.info(`remove \u547D\u4EE4\u6267\u884C\uFF0C\u9879\u76EE: ${projectName}`);
   const allWorktrees = getProjectWorktrees();
@@ -4010,11 +4049,8 @@ function handleDryRunFromFile(options) {
   printDryRunPreview(branchNames, tasks, concurrency);
 }
 async function handleRun(options) {
-  runPreChecks({ mainWorktree: true, headExists: true });
-  if (!options.dryRun) {
-    await guardMainWorkBranch();
-    await ensureOnMainWorkBranch();
-  }
+  const preChecks = options.dryRun ? PRE_CHECK_DRY_RUN : PRE_CHECK_RUN;
+  await runPreChecks(preChecks);
   if (options.file && options.tasks) {
     throw new ClawtError(MESSAGES.FILE_AND_TASKS_CONFLICT);
   }
@@ -4075,8 +4111,7 @@ function registerResumeCommand(program2) {
   });
 }
 async function handleResume(options) {
-  runPreChecks({ mainWorktree: true, headExists: true });
-  validateClaudeCodeInstalled();
+  await runPreChecks(PRE_CHECK_RESUME);
   logger.info(`resume \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F\u8FC7\u6EE4: ${options.branch ?? "(\u65E0)"}`);
   const worktrees = getProjectWorktrees();
   let targetWorktrees;
@@ -4176,8 +4211,7 @@ async function executeSyncForBranch(targetWorktreePath, branch) {
   return { success: true, hasConflict: false };
 }
 async function handleSync(options) {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
-  await guardMainWorkBranch();
+  await runPreChecks(PRE_CHECK_SYNC);
   logger.info(`sync \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch ?? "(\u672A\u6307\u5B9A)"}`);
   const worktrees = getProjectWorktrees();
   const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
@@ -4210,7 +4244,7 @@ async function handlePatchApplyFailure(targetWorktreePath, branchName) {
   const syncResult = await executeSyncForBranch(targetWorktreePath, branchName);
 }
 async function handleValidateClean(options) {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true });
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
   const worktrees = getProjectWorktrees();
@@ -4295,7 +4329,7 @@ async function handleValidate(options) {
     await handleValidateClean(options);
     return;
   }
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true });
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
   const worktrees = getProjectWorktrees();
@@ -4360,7 +4394,7 @@ function computeIncrementalPatch(snapshotTreeHash, mainWorktreePath) {
   return { patch, currentTreeHash };
 }
 async function handleCoverValidate() {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true });
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
   const currentBranch = getCurrentBranch(mainWorktreePath);
@@ -4439,11 +4473,8 @@ function cleanupWorktreeAndBranch(worktreePath, branchName) {
   printSuccess(MESSAGES.WORKTREE_CLEANED(branchName));
 }
 async function handleMerge(options) {
-  runPreChecks({ mainWorktree: true, headExists: true });
-  await guardMainWorkBranch();
-  await guardMainWorkBranch();
+  await runPreChecks(PRE_CHECK_MERGE);
   const mainWorktreePath = getGitTopLevel();
-  await ensureOnMainWorkBranch(mainWorktreePath);
   logger.info(`merge \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch ?? "(\u672A\u6307\u5B9A)"}\uFF0C\u63D0\u4EA4\u4FE1\u606F: ${options.message ?? "(\u672A\u63D0\u4F9B)"}`);
   const worktrees = getProjectWorktrees();
   const worktree = await resolveTargetWorktree(worktrees, MERGE_RESOLVE_MESSAGES, options.branch);
@@ -4602,7 +4633,7 @@ function registerResetCommand(program2) {
   });
 }
 async function handleReset() {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true });
   const mainWorktreePath = getGitTopLevel();
   logger.info("reset \u547D\u4EE4\u6267\u884C");
   if (!isWorkingDirClean(mainWorktreePath)) {
@@ -4632,7 +4663,7 @@ function registerStatusCommand(program2) {
   });
 }
 async function handleStatus(options) {
-  runPreChecks({ mainWorktree: true, headExists: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true });
   if (options.interactive) {
     const panel = new InteractivePanel(collectStatus);
     await panel.start();
@@ -4674,7 +4705,7 @@ function collectWorktreeDetailedStatus(worktree, projectName) {
   const changeStatus = detectChangeStatus(worktree);
   const { commitsAhead, commitsBehind } = countCommitDivergence(worktree.branch);
   const { insertions, deletions } = countDiffStat(worktree.path);
-  const createdAt = resolveBranchCreatedAt(worktree.branch);
+  const createdAt = getWorktreeCreatedTime(worktree.path);
   return {
     path: worktree.path,
     branch: worktree.branch,
@@ -4720,13 +4751,6 @@ function countDiffStat(worktreePath) {
     return { insertions: 0, deletions: 0 };
   }
 }
-function resolveBranchCreatedAt(branchName) {
-  try {
-    return getBranchCreatedAt(branchName);
-  } catch {
-    return null;
-  }
-}
 function resolveSnapshotTime(projectName, branchName) {
   try {
     return getSnapshotModifiedTime(projectName, branchName);
@@ -5312,7 +5336,7 @@ function registerInitCommand(program2) {
   );
 }
 async function handleInitShow() {
-  runPreChecks({ mainWorktree: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireProjectConfig: true });
   const config2 = requireProjectConfig();
   logger.info("init show \u547D\u4EE4\u6267\u884C\uFF0C\u8FDB\u5165\u4EA4\u4E92\u5F0F\u9879\u76EE\u914D\u7F6E");
   const { key, newValue } = await interactiveConfigEditor(
@@ -5325,7 +5349,7 @@ async function handleInitShow() {
   printSuccess(MESSAGES.INIT_SET_SUCCESS(key, String(newValue)));
 }
 async function handleInit(options) {
-  runPreChecks({ mainWorktree: true });
+  await runPreChecks({ requireMainWorktree: true });
   const existingConfig = loadProjectConfig();
   if (!options.branch) {
     validateHeadExists();
@@ -5347,7 +5371,7 @@ function registerHomeCommand(program2) {
   });
 }
 async function handleHome() {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true, branchExists: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true, requireMainBranchExists: true });
   const mainBranch = getMainWorkBranch();
   const currentBranch = getCurrentBranch();
   if (currentBranch === mainBranch) {

package/dist/postinstall.js

@@ -505,6 +505,8 @@ var PANEL_SHORTCUT_KEYS = {
   RESUME: "r",
   /** 同步 */
   SYNC: "s",
+  /** 覆盖 */
+  COVER: "c",
   /** 手动刷新 */
   REFRESH: "f",
   /** 退出 */
@@ -518,6 +520,7 @@ var SHORTCUT_LABELS = {
   DELETE: "\u5220\u9664",
   RESUME: "\u6062\u590D",
   SYNC: "\u540C\u6B65",
+  COVER: "\u8986\u76D6",
   REFRESH: "\u5237\u65B0",
   QUIT: "\u9000\u51FA"
 };
@@ -639,6 +642,15 @@ var UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 import chalk2 from "chalk";
 var UNKNOWN_DATE_SEPARATOR_LABEL = `\u2550\u2550\u2550\u2550 ${chalk2.bold.hex("#FF8C00")("\u672A\u77E5\u65E5\u671F")} \u2550\u2550\u2550\u2550`;
 
+// src/constants/pre-checks.ts
+var PRE_CHECK_CREATE = {
+  requireMainWorktree: true,
+  requireHead: true,
+  ensureOnClawtMainWorkBranch: true,
+  requireCleanWorkingDir: true
+};
+var PRE_CHECK_RUN = { ...PRE_CHECK_CREATE };
+
 // scripts/postinstall.ts
 function ensureDirectory(dirPath) {
   if (!existsSync(dirPath)) {

package/package.json

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

package/src/commands/cover-validate.ts

@@ -97,7 +97,7 @@ export function computeIncrementalPatch(snapshotTreeHash: string, mainWorktreePa
  */
 async function handleCoverValidate(): Promise<void> {
   // 步骤 1：前置校验
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true });
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
   const currentBranch = getCurrentBranch(mainWorktreePath);

package/src/commands/create.ts

@@ -3,15 +3,14 @@ import { MESSAGES, EXIT_CODES } from '../constants/index.js';
 import { ClawtError } from '../errors/index.js';
 import { logger } from '../logger/index.js';
 import type { CreateOptions } from '../types/index.js';
+import { PRE_CHECK_CREATE } from '../constants/index.js';
 import {
   runPreChecks,
   createWorktrees,
-  ensureOnMainWorkBranch,
   getValidateBranchName,
   printSuccess,
   printInfo,
   printSeparator,
-  guardMainWorkBranch,
 } from '../utils/index.js';
 
 /**
@@ -34,11 +33,7 @@ export function registerCreateCommand(program: Command): void {
  * @param {CreateOptions} options - 命令选项
  */
 async function handleCreate(options: CreateOptions): Promise<void> {
-  runPreChecks({ mainWorktree: true, headExists: true });
-
-  await guardMainWorkBranch();
-
-  await ensureOnMainWorkBranch();
+  await runPreChecks(PRE_CHECK_CREATE);
 
   const count = Number(options.number);
 

package/src/commands/home.ts

@@ -27,7 +27,7 @@ export function registerHomeCommand(program: Command): void {
  * 执行 home 命令：切换回主工作分支
  */
 async function handleHome(): Promise<void> {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true, branchExists: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true, requireMainBranchExists: true });
 
   const mainBranch = getMainWorkBranch();
   const currentBranch = getCurrentBranch();

package/src/commands/init.ts

@@ -41,7 +41,7 @@ export function registerInitCommand(program: Command): void {
  * 处理 init show 子命令：交互式面板展示和修改项目配置
  */
 async function handleInitShow(): Promise<void> {
-  runPreChecks({ mainWorktree: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireProjectConfig: true });
   const config = requireProjectConfig();
 
   logger.info('init show 命令执行，进入交互式项目配置');
@@ -67,7 +67,7 @@ async function handleInitShow(): Promise<void> {
  * @param {InitOptions} options - 命令选项
  */
 async function handleInit(options: InitOptions): Promise<void> {
-  runPreChecks({ mainWorktree: true });
+  await runPreChecks({ requireMainWorktree: true });
 
   const existingConfig = loadProjectConfig();
 

package/src/commands/list.ts

@@ -23,8 +23,8 @@ export function registerListCommand(program: Command): void {
     .command('list')
     .description('列出当前项目所有 worktree（支持 --json 格式输出）')
     .option('--json', '以 JSON 格式输出')
-    .action((options: ListOptions) => {
-      handleList(options);
+    .action(async (options: ListOptions) => {
+      await handleList(options);
     });
 }
 
@@ -32,8 +32,8 @@ export function registerListCommand(program: Command): void {
  * 执行 list 命令的核心逻辑
  * @param {ListOptions} options - 命令选项
  */
-function handleList(options: ListOptions): void {
-  runPreChecks({ mainWorktree: true });
+async function handleList(options: ListOptions): Promise<void> {
+  await runPreChecks({ requireMainWorktree: true });
 
   const projectName = getProjectName();
   const worktrees = getProjectWorktrees();

package/src/commands/merge.ts

@@ -3,6 +3,7 @@ import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES, AUTO_SAVE_COMMIT_MESSAGE } from '../constants/index.js';
 import type { MergeOptions } from '../types/index.js';
+import { PRE_CHECK_MERGE } from '../constants/index.js';
 import {
   runPreChecks,
   getProjectName,
@@ -32,8 +33,6 @@ import {
   gitCheckout,
   resolveTargetWorktree,
   getMainWorkBranch,
-  ensureOnMainWorkBranch,
-  guardMainWorkBranch,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages } from '../utils/index.js';
 
@@ -136,17 +135,10 @@ function cleanupWorktreeAndBranch(worktreePath: string, branchName: string): voi
  * @param {MergeOptions} options - 命令选项
  */
 async function handleMerge(options: MergeOptions): Promise<void> {
-  runPreChecks({ mainWorktree: true, headExists: true });
-
-  await guardMainWorkBranch();
-
-  await guardMainWorkBranch();
+  await runPreChecks(PRE_CHECK_MERGE);
 
   const mainWorktreePath = getGitTopLevel();
 
-  // 确保当前在主工作分支上
-  await ensureOnMainWorkBranch(mainWorktreePath);
-
   logger.info(`merge 命令执行，分支: ${options.branch ?? '(未指定)'}，提交信息: ${options.message ?? '(未提供)'}`);
 
   // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）

package/src/commands/remove.ts

@@ -55,7 +55,7 @@ export function registerRemoveCommand(program: Command): void {
  * @param {RemoveOptions} options - 命令选项
  */
 async function handleRemove(options: RemoveOptions): Promise<void> {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true });
 
   const projectName = getProjectName();
   logger.info(`remove 命令执行，项目: ${projectName}`);

package/src/commands/reset.ts

@@ -30,7 +30,7 @@ export function registerResetCommand(program: Command): void {
  * 执行 reset 命令：重置主 worktree 工作区和暂存区
  */
 async function handleReset(): Promise<void> {
-  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await runPreChecks({ requireMainWorktree: true, requireHead: true, requireProjectConfig: true });
 
   const mainWorktreePath = getGitTopLevel();
   logger.info('reset 命令执行');

package/src/commands/resume.ts

@@ -3,9 +3,9 @@ import { logger } from '../logger/index.js';
 import { MESSAGES } from '../constants/index.js';
 import type { ResumeOptions } from '../types/index.js';
 import type { WorktreeInfo } from '../types/index.js';
+import { PRE_CHECK_RESUME } from '../constants/index.js';
 import {
   runPreChecks,
-  validateClaudeCodeInstalled,
   getProjectWorktrees,
   launchInteractiveClaude,
   launchInteractiveClaudeInNewTerminal,
@@ -47,8 +47,7 @@ export function registerResumeCommand(program: Command): void {
  * @param {ResumeOptions} options - 命令选项
  */
 async function handleResume(options: ResumeOptions): Promise<void> {
-  runPreChecks({ mainWorktree: true, headExists: true });
-  validateClaudeCodeInstalled();
+  await runPreChecks(PRE_CHECK_RESUME);
 
   logger.info(`resume 命令执行，分支过滤: ${options.branch ?? '(无)'}`);
   const worktrees = getProjectWorktrees();

package/src/commands/run.ts

@@ -3,6 +3,7 @@ import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import type { RunOptions, WorktreeInfo } from '../types/index.js';
+import { PRE_CHECK_DRY_RUN, PRE_CHECK_RUN } from '../constants/index.js';
 import {
   runPreChecks,
   validateClaudeCodeInstalled,
@@ -19,8 +20,6 @@ import {
   parseTasksFromOptions,
   executeBatchTasks,
   printDryRunPreview,
-  ensureOnMainWorkBranch,
-  guardMainWorkBranch,
 } from '../utils/index.js';
 
 /**
@@ -120,13 +119,8 @@ function handleDryRunFromFile(options: RunOptions): void {
  * @param {RunOptions} options - 命令选项
  */
 async function handleRun(options: RunOptions): Promise<void> {
-  runPreChecks({ mainWorktree: true, headExists: true });
-
-  // dry-run 模式跳过项目配置前置校验
-  if (!options.dryRun) {
-    await guardMainWorkBranch();
-    await ensureOnMainWorkBranch();
-  }
+  const preChecks = options.dryRun ? PRE_CHECK_DRY_RUN : PRE_CHECK_RUN;
+  await runPreChecks(preChecks);
 
   // 互斥校验：--file 和 --tasks 不能同时使用
   if (options.file && options.tasks) {