clawt 3.4.1 → 3.4.3

package/README.md

@@ -17,24 +17,33 @@ npm i -g clawt
 ## 快速开始
 
 ```bash
-# 1. 在项目根目录（包含 .git 的目录）下初始化
+# 1. 在项目根目录（包含 .git 的目录）下初始化，确认主工作分支
 clawt init
 
-# 2. 并行执行 3 个任务，每个任务在独立的 worktree 中运行
-clawt run -b <branch-1>
-clawt run -b <branch-2>
-clawt run -b <branch-3>
+# 2. 并行执行任务，每个任务在独立的 worktree 中运行
+clawt run -b feat-login
+clawt run -b feat-search
+clawt run -b fix-bug
 
-# 3. 查看所有 worktree 状态
-clawt status
-
-# 4. 验证某个分支的变更（在主 worktree 中测试）
-clawt validate -b branch-1
-
-# 5. 确认无误后合并到主分支
-clawt merge -b branch-1 -m "feat: 实现xxx功能"
+# 3. 打开交互式面板，实时查看所有任务状态，一站式完成后续操作
+clawt status -i
 ```
 
+`clawt status -i` 提供实时刷新的 TUI 面板，用方向键选中 worktree 后可直接按快捷键操作：
+
+| 快捷键 | 操作 | 等同命令 |
+| ------ | ---- | -------- |
+| `v` | 验证分支变更 | `clawt validate -b <branch>` |
+| `m` | 合并到主分支 | `clawt merge -b <branch>` |
+| `r` | 恢复 Claude Code 会话 | `clawt resume -b <branch>` |
+| `s` | 同步主分支代码 | `clawt sync -b <branch>` |
+| `d` | 删除 worktree | `clawt remove -b <branch>` |
+| `q` | 退出面板 | — |
+  
+示例：  
+![](https://p3.ssl.qhimg.com/d/inn/8a3779be2486/upload_screenshot_1772675658.png)
+> 所有操作也可通过独立命令执行，详见下方「命令一览」。
+
 ## 命令一览
 
 > 除 `config`、`alias`、`projects`、`completion` 外，其余命令需在**主 worktree 的仓库根目录**下执行。`-b` 参数支持模糊匹配。大部分操作命令（`run`、`create`、`validate`、`merge` 等）需要先执行 `clawt init`。

package/dist/index.js

@@ -30,6 +30,8 @@ var COMMON_MESSAGES = {
   GIT_NOT_INSTALLED: "Git \u672A\u5B89\u88C5\u6216\u4E0D\u5728 PATH \u4E2D\uFF0C\u8BF7\u5148\u5B89\u88C5 Git",
   /** Claude Code CLI 未安装 */
   CLAUDE_NOT_INSTALLED: "Claude Code CLI \u672A\u5B89\u88C5\uFF0C\u8BF7\u5148\u5B89\u88C5\uFF1Anpm install -g @anthropic-ai/claude-code",
+  /** HEAD 不存在（仓库无任何 commit） */
+  HEAD_NOT_FOUND: "\u5F53\u524D\u4ED3\u5E93\u5C1A\u672A\u521B\u5EFA\u4EFB\u4F55\u63D0\u4EA4\uFF0C\u8BF7\u5148\u6267\u884C git commit \u521B\u5EFA\u9996\u6B21\u63D0\u4EA4\u540E\u518D\u4F7F\u7528 clawt",
   /** 分支已存在 */
   BRANCH_EXISTS: (name) => `\u5206\u652F ${name} \u5DF2\u5B58\u5728\uFF0C\u65E0\u6CD5\u521B\u5EFA`,
   /** 分支名清理后为空 */
@@ -59,7 +61,11 @@ var COMMON_MESSAGES = {
   /** 分隔线 */
   SEPARATOR: "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
   /** 粗分隔线 */
-  DOUBLE_SEPARATOR: "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550"
+  DOUBLE_SEPARATOR: "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  /** 守卫检测：配置的主工作分支已不存在 */
+  GUARD_BRANCH_NOT_EXISTS: (branchName) => `\u914D\u7F6E\u7684\u4E3B\u5DE5\u4F5C\u5206\u652F ${branchName} \u5DF2\u4E0D\u5B58\u5728\uFF0C\u8BF7\u6267\u884C clawt init \u91CD\u65B0\u8BBE\u7F6E\u4E3B\u5DE5\u4F5C\u5206\u652F`,
+  /** 守卫检测：当前分支与配置的主工作分支不一致 */
+  GUARD_BRANCH_MISMATCH: (configuredBranch, currentBranch) => `\u5F53\u524D\u5206\u652F ${currentBranch} \u4E0E\u914D\u7F6E\u7684\u4E3B\u5DE5\u4F5C\u5206\u652F ${configuredBranch} \u4E0D\u4E00\u81F4\uFF0C\u5982\u9700\u66F4\u65B0\u8BF7\u6267\u884C clawt init`
 };
 
 // src/constants/messages/run.ts
@@ -371,7 +377,13 @@ var STATUS_MESSAGES = {
   /** status 上次验证时间标签 */
   STATUS_LAST_VALIDATED: (relativeTime) => `\u4E0A\u6B21\u9A8C\u8BC1: ${relativeTime}`,
   /** status 未验证警示 */
-  STATUS_NOT_VALIDATED: "\u2717 \u672A\u9A8C\u8BC1"
+  STATUS_NOT_VALIDATED: "\u2717 \u672A\u9A8C\u8BC1",
+  /** status 配置的主工作分支（正常状态） */
+  STATUS_CONFIGURED_BRANCH: (branchName) => `\u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}`,
+  /** status 配置的主工作分支已不存在 */
+  STATUS_CONFIGURED_BRANCH_DELETED: (branchName) => `\u2717 \u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}\uFF08\u5DF2\u4E0D\u5B58\u5728\uFF0C\u8BF7\u6267\u884C clawt init \u91CD\u65B0\u8BBE\u7F6E\uFF09`,
+  /** status 当前分支与配置的主工作分支不一致 */
+  STATUS_CONFIGURED_BRANCH_MISMATCH: (branchName) => `\u26A0 \u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}\uFF08\u5F53\u524D\u5206\u652F\u4E0D\u4E00\u81F4\uFF0C\u5982\u9700\u66F4\u65B0\u8BF7\u6267\u884C clawt init\uFF09`
 };
 
 // src/constants/messages/alias.ts
@@ -529,7 +541,7 @@ var PANEL_SHORTCUT_KEYS = {
   QUIT: "q"
 };
 var PANEL_DATE_SEPARATOR_PREFIX = "\u2550\u2550\u2550\u2550";
-var PANEL_FIXED_ROWS = 4;
+var PANEL_FIXED_ROWS = 5;
 
 // src/constants/messages/interactive-panel.ts
 var SHORTCUT_LABELS = {
@@ -556,6 +568,10 @@ var PANEL_NO_WORKTREES = "(\u65E0\u6D3B\u8DC3 worktree)";
 var PANEL_PRESS_ENTER_TO_RETURN = chalk.gray("\n\u6309 Enter \u8FD4\u56DE\u9762\u677F...");
 var PANEL_NOT_TTY = "\u4EA4\u4E92\u5F0F\u9762\u677F\u9700\u8981 TTY \u7EC8\u7AEF\u73AF\u5883\uFF0C\u8BF7\u76F4\u63A5\u5728\u7EC8\u7AEF\u4E2D\u8FD0\u884C clawt status -i";
 var PANEL_TITLE = (projectName) => chalk.bold.cyan(`\u9879\u76EE\u72B6\u6001\u603B\u89C8: ${projectName}`);
+var PANEL_CONFIGURED_BRANCH = (branchName) => chalk.gray(`\u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}`);
+var PANEL_CONFIGURED_BRANCH_DELETED = (branchName) => chalk.red(`\u2717 \u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}\uFF08\u5DF2\u4E0D\u5B58\u5728\uFF09`);
+var PANEL_CONFIGURED_BRANCH_MISMATCH = (branchName) => chalk.yellow(`\u26A0 \u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}\uFF08\u4E0D\u4E00\u81F4\uFF09`);
+var PANEL_NOT_INITIALIZED = chalk.gray("\u672A\u521D\u59CB\u5316\uFF08\u6267\u884C clawt init \u8BBE\u7F6E\u4E3B\u5DE5\u4F5C\u5206\u652F\uFF09");
 
 // src/constants/messages/index.ts
 var MESSAGES = {
@@ -1215,31 +1231,9 @@ function validateBranchesNotExist(branchNames) {
   }
 }
 
-// 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);
-  }
-}
-
-// src/utils/worktree.ts
-import { join as join4 } from "path";
-import { existsSync as existsSync4, readdirSync as readdirSync2 } from "fs";
+// src/utils/project-config.ts
+import { existsSync as existsSync3, readFileSync, writeFileSync } from "fs";
+import { join as join3 } from "path";
 
 // src/utils/fs.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, rmdirSync, statSync } from "fs";
@@ -1280,12 +1274,7 @@ function calculateDirSize(dirPath) {
   return totalSize;
 }
 
-// src/utils/validate-branch.ts
-import Enquirer from "enquirer";
-
 // src/utils/project-config.ts
-import { existsSync as existsSync3, readFileSync, writeFileSync } from "fs";
-import { join as join3 } from "path";
 function getProjectConfigPath(projectName) {
   return join3(PROJECTS_CONFIG_DIR, projectName, "config.json");
 }
@@ -1325,12 +1314,80 @@ function getMainWorkBranch() {
   const config2 = requireProjectConfig();
   return config2.clawtMainWorkBranch;
 }
+function guardMainWorkBranchExists(cwd) {
+  const config2 = requireProjectConfig();
+  const mainBranch = config2.clawtMainWorkBranch;
+  if (!checkBranchExists(mainBranch, 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) {
   return `${VALIDATE_BRANCH_PREFIX}${branchName}`;
 }
@@ -3178,6 +3235,7 @@ function buildSeparatorWithHint(cols, hint) {
 function buildPanelFrame(statusResult, selectedIndex, scrollOffset, rows, cols, countdown) {
   const lines = [];
   lines.push(PANEL_TITLE(statusResult.main.projectName));
+  lines.push(renderConfiguredBranchLine(statusResult.main));
   lines.push(renderSnapshotSummary(statusResult.snapshots.total, statusResult.snapshots.orphaned));
   const visibleRows = calculateVisibleRows(rows);
   if (statusResult.worktrees.length === 0) {
@@ -3301,6 +3359,18 @@ function formatChangeStatusLabel(status) {
       return chalk9.gray(MESSAGES.STATUS_CHANGE_CLEAN);
   }
 }
+function renderConfiguredBranchLine(main2) {
+  if (main2.configuredMainBranch === null) {
+    return PANEL_NOT_INITIALIZED;
+  }
+  if (main2.configuredBranchExists === false) {
+    return PANEL_CONFIGURED_BRANCH_DELETED(main2.configuredMainBranch);
+  }
+  if (main2.branch !== main2.configuredMainBranch && !main2.branch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+    return PANEL_CONFIGURED_BRANCH_MISMATCH(main2.configuredMainBranch);
+  }
+  return PANEL_CONFIGURED_BRANCH(main2.configuredMainBranch);
+}
 function renderSnapshotSummary(total, orphaned) {
   return PANEL_SNAPSHOT_SUMMARY(total, orphaned);
 }
@@ -3748,7 +3818,7 @@ function registerListCommand(program2) {
   });
 }
 function handleList(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true });
   const projectName = getProjectName();
   const worktrees = getProjectWorktrees();
   logger.info(`list \u547D\u4EE4\u6267\u884C\uFF0C\u9879\u76EE: ${projectName}\uFF0C\u5171 ${worktrees.length} \u4E2A worktree`);
@@ -3798,7 +3868,8 @@ function registerCreateCommand(program2) {
   });
 }
 async function handleCreate(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
+  await guardMainWorkBranch();
   await ensureOnMainWorkBranch();
   const count = Number(options.number);
   if (!Number.isInteger(count) || count <= 0) {
@@ -3833,8 +3904,7 @@ function registerRemoveCommand(program2) {
   });
 }
 async function handleRemove(options) {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
   const projectName = getProjectName();
   logger.info(`remove \u547D\u4EE4\u6267\u884C\uFF0C\u9879\u76EE: ${projectName}`);
   const allWorktrees = getProjectWorktrees();
@@ -3940,8 +4010,9 @@ function handleDryRunFromFile(options) {
   printDryRunPreview(branchNames, tasks, concurrency);
 }
 async function handleRun(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
   if (!options.dryRun) {
+    await guardMainWorkBranch();
     await ensureOnMainWorkBranch();
   }
   if (options.file && options.tasks) {
@@ -4004,7 +4075,7 @@ function registerResumeCommand(program2) {
   });
 }
 async function handleResume(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
   validateClaudeCodeInstalled();
   logger.info(`resume \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F\u8FC7\u6EE4: ${options.branch ?? "(\u65E0)"}`);
   const worktrees = getProjectWorktrees();
@@ -4105,8 +4176,8 @@ async function executeSyncForBranch(targetWorktreePath, branch) {
   return { success: true, hasConflict: false };
 }
 async function handleSync(options) {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await guardMainWorkBranch();
   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);
@@ -4139,8 +4210,7 @@ async function handlePatchApplyFailure(targetWorktreePath, branchName) {
   const syncResult = await executeSyncForBranch(targetWorktreePath, branchName);
 }
 async function handleValidateClean(options) {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
   const worktrees = getProjectWorktrees();
@@ -4225,8 +4295,7 @@ async function handleValidate(options) {
     await handleValidateClean(options);
     return;
   }
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
   const worktrees = getProjectWorktrees();
@@ -4291,8 +4360,7 @@ function computeIncrementalPatch(snapshotTreeHash, mainWorktreePath) {
   return { patch, currentTreeHash };
 }
 async function handleCoverValidate() {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
   const currentBranch = getCurrentBranch(mainWorktreePath);
@@ -4371,7 +4439,9 @@ function cleanupWorktreeAndBranch(worktreePath, branchName) {
   printSuccess(MESSAGES.WORKTREE_CLEANED(branchName));
 }
 async function handleMerge(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
+  await guardMainWorkBranch();
+  await guardMainWorkBranch();
   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)"}`);
@@ -4532,8 +4602,7 @@ function registerResetCommand(program2) {
   });
 }
 async function handleReset() {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
   const mainWorktreePath = getGitTopLevel();
   logger.info("reset \u547D\u4EE4\u6267\u884C");
   if (!isWorkingDirClean(mainWorktreePath)) {
@@ -4563,7 +4632,7 @@ function registerStatusCommand(program2) {
   });
 }
 async function handleStatus(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
   if (options.interactive) {
     const panel = new InteractivePanel(collectStatus);
     await panel.start();
@@ -4581,10 +4650,15 @@ function collectStatus() {
   const projectName = getProjectName();
   const currentBranch = getCurrentBranch();
   const isClean = isWorkingDirClean();
+  const projectConfig = loadProjectConfig();
+  const configuredMainBranch = projectConfig?.clawtMainWorkBranch || null;
+  const configuredBranchExists = configuredMainBranch ? checkBranchExists(configuredMainBranch) : null;
   const main2 = {
     branch: currentBranch,
     isClean,
-    projectName
+    projectName,
+    configuredMainBranch,
+    configuredBranchExists
   };
   const worktrees = getProjectWorktrees();
   const worktreeStatuses = worktrees.map((wt) => collectWorktreeDetailedStatus(wt, projectName));
@@ -4694,6 +4768,15 @@ function printMainSection(main2) {
   } else {
     printInfo(`    \u72B6\u6001: ${chalk11.yellow("\u2717 \u6709\u672A\u63D0\u4EA4\u4FEE\u6539")}`);
   }
+  if (main2.configuredMainBranch !== null) {
+    if (main2.configuredBranchExists === false) {
+      printInfo(`    ${chalk11.red(MESSAGES.STATUS_CONFIGURED_BRANCH_DELETED(main2.configuredMainBranch))}`);
+    } else if (main2.branch !== main2.configuredMainBranch && !main2.branch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+      printInfo(`    ${chalk11.yellow(MESSAGES.STATUS_CONFIGURED_BRANCH_MISMATCH(main2.configuredMainBranch))}`);
+    } else {
+      printInfo(`    ${chalk11.gray(MESSAGES.STATUS_CONFIGURED_BRANCH(main2.configuredMainBranch))}`);
+    }
+  }
   printInfo("");
 }
 function printWorktreesSection(worktrees, total) {
@@ -5229,7 +5312,7 @@ function registerInitCommand(program2) {
   );
 }
 async function handleInitShow() {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, projectConfig: 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(
@@ -5242,8 +5325,11 @@ async function handleInitShow() {
   printSuccess(MESSAGES.INIT_SET_SUCCESS(key, String(newValue)));
 }
 async function handleInit(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true });
   const existingConfig = loadProjectConfig();
+  if (!options.branch) {
+    validateHeadExists();
+  }
   const branchName = options.branch || getCurrentBranch();
   logger.info(`init \u547D\u4EE4\u6267\u884C\uFF0C\u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}`);
   saveProjectConfig({ clawtMainWorkBranch: branchName });
@@ -5261,8 +5347,7 @@ function registerHomeCommand(program2) {
   });
 }
 async function handleHome() {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true, branchExists: true });
   const mainBranch = getMainWorkBranch();
   const currentBranch = getCurrentBranch();
   if (currentBranch === mainBranch) {

package/dist/postinstall.js

@@ -21,6 +21,8 @@ var COMMON_MESSAGES = {
   GIT_NOT_INSTALLED: "Git \u672A\u5B89\u88C5\u6216\u4E0D\u5728 PATH \u4E2D\uFF0C\u8BF7\u5148\u5B89\u88C5 Git",
   /** Claude Code CLI 未安装 */
   CLAUDE_NOT_INSTALLED: "Claude Code CLI \u672A\u5B89\u88C5\uFF0C\u8BF7\u5148\u5B89\u88C5\uFF1Anpm install -g @anthropic-ai/claude-code",
+  /** HEAD 不存在（仓库无任何 commit） */
+  HEAD_NOT_FOUND: "\u5F53\u524D\u4ED3\u5E93\u5C1A\u672A\u521B\u5EFA\u4EFB\u4F55\u63D0\u4EA4\uFF0C\u8BF7\u5148\u6267\u884C git commit \u521B\u5EFA\u9996\u6B21\u63D0\u4EA4\u540E\u518D\u4F7F\u7528 clawt",
   /** 分支已存在 */
   BRANCH_EXISTS: (name) => `\u5206\u652F ${name} \u5DF2\u5B58\u5728\uFF0C\u65E0\u6CD5\u521B\u5EFA`,
   /** 分支名清理后为空 */
@@ -50,7 +52,11 @@ var COMMON_MESSAGES = {
   /** 分隔线 */
   SEPARATOR: "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
   /** 粗分隔线 */
-  DOUBLE_SEPARATOR: "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550"
+  DOUBLE_SEPARATOR: "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  /** 守卫检测：配置的主工作分支已不存在 */
+  GUARD_BRANCH_NOT_EXISTS: (branchName) => `\u914D\u7F6E\u7684\u4E3B\u5DE5\u4F5C\u5206\u652F ${branchName} \u5DF2\u4E0D\u5B58\u5728\uFF0C\u8BF7\u6267\u884C clawt init \u91CD\u65B0\u8BBE\u7F6E\u4E3B\u5DE5\u4F5C\u5206\u652F`,
+  /** 守卫检测：当前分支与配置的主工作分支不一致 */
+  GUARD_BRANCH_MISMATCH: (configuredBranch, currentBranch) => `\u5F53\u524D\u5206\u652F ${currentBranch} \u4E0E\u914D\u7F6E\u7684\u4E3B\u5DE5\u4F5C\u5206\u652F ${configuredBranch} \u4E0D\u4E00\u81F4\uFF0C\u5982\u9700\u66F4\u65B0\u8BF7\u6267\u884C clawt init`
 };
 
 // src/constants/messages/run.ts
@@ -361,7 +367,13 @@ var STATUS_MESSAGES = {
   /** status 上次验证时间标签 */
   STATUS_LAST_VALIDATED: (relativeTime) => `\u4E0A\u6B21\u9A8C\u8BC1: ${relativeTime}`,
   /** status 未验证警示 */
-  STATUS_NOT_VALIDATED: "\u2717 \u672A\u9A8C\u8BC1"
+  STATUS_NOT_VALIDATED: "\u2717 \u672A\u9A8C\u8BC1",
+  /** status 配置的主工作分支（正常状态） */
+  STATUS_CONFIGURED_BRANCH: (branchName) => `\u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}`,
+  /** status 配置的主工作分支已不存在 */
+  STATUS_CONFIGURED_BRANCH_DELETED: (branchName) => `\u2717 \u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}\uFF08\u5DF2\u4E0D\u5B58\u5728\uFF0C\u8BF7\u6267\u884C clawt init \u91CD\u65B0\u8BBE\u7F6E\uFF09`,
+  /** status 当前分支与配置的主工作分支不一致 */
+  STATUS_CONFIGURED_BRANCH_MISMATCH: (branchName) => `\u26A0 \u4E3B\u5DE5\u4F5C\u5206\u652F: ${branchName}\uFF08\u5F53\u524D\u5206\u652F\u4E0D\u4E00\u81F4\uFF0C\u5982\u9700\u66F4\u65B0\u8BF7\u6267\u884C clawt init\uFF09`
 };
 
 // src/constants/messages/alias.ts
@@ -513,6 +525,7 @@ var PANEL_FOOTER_SHORTCUTS = Object.entries(SHORTCUT_LABELS).map(([key, label])
 var PANEL_OVERFLOW_DOWN_HINT = chalk.gray("\u2193 \u66F4\u591A worktree...");
 var PANEL_OVERFLOW_UP_HINT = chalk.gray("\u2191 \u66F4\u591A worktree...");
 var PANEL_PRESS_ENTER_TO_RETURN = chalk.gray("\n\u6309 Enter \u8FD4\u56DE\u9762\u677F...");
+var PANEL_NOT_INITIALIZED = chalk.gray("\u672A\u521D\u59CB\u5316\uFF08\u6267\u884C clawt init \u8BBE\u7F6E\u4E3B\u5DE5\u4F5C\u5206\u652F\uFF09");
 
 // src/constants/messages/index.ts
 var MESSAGES = {

package/package.json

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

package/src/commands/cover-validate.ts

@@ -3,8 +3,7 @@ import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES, VALIDATE_BRANCH_PREFIX } from '../constants/index.js';
 import {
-  validateMainWorktree,
-  requireProjectConfig,
+  runPreChecks,
   getProjectName,
   getGitTopLevel,
   getCurrentBranch,
@@ -98,8 +97,7 @@ export function computeIncrementalPatch(snapshotTreeHash: string, mainWorktreePa
  */
 async function handleCoverValidate(): Promise<void> {
   // 步骤 1：前置校验
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
   const currentBranch = getCurrentBranch(mainWorktreePath);

package/src/commands/create.ts

@@ -4,13 +4,14 @@ import { ClawtError } from '../errors/index.js';
 import { logger } from '../logger/index.js';
 import type { CreateOptions } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   createWorktrees,
   ensureOnMainWorkBranch,
   getValidateBranchName,
   printSuccess,
   printInfo,
   printSeparator,
+  guardMainWorkBranch,
 } from '../utils/index.js';
 
 /**
@@ -33,7 +34,9 @@ export function registerCreateCommand(program: Command): void {
  * @param {CreateOptions} options - 命令选项
  */
 async function handleCreate(options: CreateOptions): Promise<void> {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
+
+  await guardMainWorkBranch();
 
   await ensureOnMainWorkBranch();
 

package/src/commands/home.ts

@@ -1,13 +1,13 @@
 import type { Command } from 'commander';
 import { MESSAGES } from '../constants/index.js';
 import {
-  validateMainWorktree,
-  requireProjectConfig,
+  runPreChecks,
   ensureOnMainWorkBranch,
   getCurrentBranch,
   getMainWorkBranch,
   printSuccess,
   printInfo,
+  guardMainWorkBranchExists,
 } from '../utils/index.js';
 
 /**
@@ -27,8 +27,7 @@ export function registerHomeCommand(program: Command): void {
  * 执行 home 命令：切换回主工作分支
  */
 async function handleHome(): Promise<void> {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true, branchExists: true });
 
   const mainBranch = getMainWorkBranch();
   const currentBranch = getCurrentBranch();

package/src/commands/init.ts

@@ -4,7 +4,8 @@ import { logger } from '../logger/index.js';
 import { MESSAGES, PROJECT_CONFIG_DEFINITIONS } from '../constants/index.js';
 import type { InitOptions, ProjectConfig } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
+  validateHeadExists,
   getCurrentBranch,
   loadProjectConfig,
   saveProjectConfig,
@@ -40,7 +41,7 @@ export function registerInitCommand(program: Command): void {
  * 处理 init show 子命令：交互式面板展示和修改项目配置
  */
 async function handleInitShow(): Promise<void> {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, projectConfig: true });
   const config = requireProjectConfig();
 
   logger.info('init show 命令执行，进入交互式项目配置');
@@ -66,11 +67,14 @@ async function handleInitShow(): Promise<void> {
  * @param {InitOptions} options - 命令选项
  */
 async function handleInit(options: InitOptions): Promise<void> {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true });
 
   const existingConfig = loadProjectConfig();
 
   // 确定分支名：优先使用 -b 参数，否则使用当前分支
+  if (!options.branch) {
+    validateHeadExists();
+  }
   const branchName = options.branch || getCurrentBranch();
 
   logger.info(`init 命令执行，主工作分支: ${branchName}`);

package/src/commands/list.ts

@@ -4,7 +4,7 @@ import { MESSAGES } from '../constants/index.js';
 import { logger } from '../logger/index.js';
 import type { ListOptions } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getProjectWorktrees,
   getWorktreeStatus,
@@ -33,7 +33,7 @@ export function registerListCommand(program: Command): void {
  * @param {ListOptions} options - 命令选项
  */
 function handleList(options: ListOptions): void {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true });
 
   const projectName = getProjectName();
   const worktrees = getProjectWorktrees();

package/src/commands/merge.ts

@@ -4,7 +4,7 @@ import { ClawtError } from '../errors/index.js';
 import { MESSAGES, AUTO_SAVE_COMMIT_MESSAGE } from '../constants/index.js';
 import type { MergeOptions } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getGitTopLevel,
   getProjectWorktrees,
@@ -33,6 +33,7 @@ import {
   resolveTargetWorktree,
   getMainWorkBranch,
   ensureOnMainWorkBranch,
+  guardMainWorkBranch,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages } from '../utils/index.js';
 
@@ -135,7 +136,11 @@ function cleanupWorktreeAndBranch(worktreePath: string, branchName: string): voi
  * @param {MergeOptions} options - 命令选项
  */
 async function handleMerge(options: MergeOptions): Promise<void> {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
+
+  await guardMainWorkBranch();
+
+  await guardMainWorkBranch();
 
   const mainWorktreePath = getGitTopLevel();