clawt 3.4.0 → 3.4.2

package/README.md

@@ -17,26 +17,36 @@ npm i -g clawt
 ## 快速开始
 
 ```bash
-# 1. 在项目根目录（包含 .git 的目录）下执行
-# 2. 并行执行 3 个任务，每个任务在独立的 worktree 中运行
-clawt run -b <branch-1>
-clawt run -b <branch-2>
-clawt run -b <branch-3>
+# 1. 在项目根目录（包含 .git 的目录）下初始化，确认主工作分支
+clawt init
 
-# 3. 查看所有 worktree 状态
-clawt status
-
-# 4. 验证某个分支的变更（在主 worktree 中测试）
-clawt validate -b branch-1
-
-# 5. 确认无误后合并到主分支
-clawt merge -b branch-1 -m "feat: 实现xxx功能"
+# 2. 并行执行任务，每个任务在独立的 worktree 中运行
+clawt run -b feat-login
+clawt run -b feat-search
+clawt run -b fix-bug
 
+# 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)
+> 所有操作也可通过独立命令执行，详见下方「命令一览」。
+
 ## 命令一览
 
-> 所有命令必须在**主 worktree 的仓库根目录**下执行。`-b` 参数支持模糊匹配。
+> 除 `config`、`alias`、`projects`、`completion` 外，其余命令需在**主 worktree 的仓库根目录**下执行。`-b` 参数支持模糊匹配。大部分操作命令（`run`、`create`、`validate`、`merge` 等）需要先执行 `clawt init`。
 
 ### `clawt init` — 初始化项目级配置
 

package/dist/index.js

@@ -59,7 +59,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 +375,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 +539,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 +566,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 = {
@@ -593,7 +607,7 @@ var VALID_TERMINAL_APPS = ["auto", "iterm2", "terminal"];
 var ITERM2_APP_PATH = "/Applications/iTerm.app";
 
 // src/constants/config.ts
-var APPEND_SYSTEM_PROMPT = "After the code execution is completed, it is prohibited to build the project for verification.";
+var APPEND_SYSTEM_PROMPT = "Currently, you are in the git worktree directory. There are no dependencies. To save disk space and improve the speed of task completion, installing dependencies is prohibited.";
 var CONFIG_DEFINITIONS = {
   autoDeleteBranch: {
     defaultValue: false,
@@ -1325,6 +1339,26 @@ 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;
@@ -3178,6 +3212,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 +3336,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);
 }
@@ -3799,6 +3846,7 @@ function registerCreateCommand(program2) {
 }
 async function handleCreate(options) {
   validateMainWorktree();
+  await guardMainWorkBranch();
   await ensureOnMainWorkBranch();
   const count = Number(options.number);
   if (!Number.isInteger(count) || count <= 0) {
@@ -3942,6 +3990,7 @@ function handleDryRunFromFile(options) {
 async function handleRun(options) {
   validateMainWorktree();
   if (!options.dryRun) {
+    await guardMainWorkBranch();
     await ensureOnMainWorkBranch();
   }
   if (options.file && options.tasks) {
@@ -4107,6 +4156,7 @@ async function executeSyncForBranch(targetWorktreePath, branch) {
 async function handleSync(options) {
   validateMainWorktree();
   requireProjectConfig();
+  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);
@@ -4372,6 +4422,7 @@ function cleanupWorktreeAndBranch(worktreePath, branchName) {
 }
 async function handleMerge(options) {
   validateMainWorktree();
+  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)"}`);
@@ -4581,10 +4632,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 +4750,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) {
@@ -5263,6 +5328,7 @@ function registerHomeCommand(program2) {
 async function handleHome() {
   validateMainWorktree();
   requireProjectConfig();
+  guardMainWorkBranchExists();
   const mainBranch = getMainWorkBranch();
   const currentBranch = getCurrentBranch();
   if (currentBranch === mainBranch) {

package/dist/postinstall.js

@@ -50,7 +50,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 +365,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 +523,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.0",
+  "version": "3.4.2",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/create.ts

@@ -11,6 +11,7 @@ import {
   printSuccess,
   printInfo,
   printSeparator,
+  guardMainWorkBranch,
 } from '../utils/index.js';
 
 /**
@@ -35,6 +36,8 @@ export function registerCreateCommand(program: Command): void {
 async function handleCreate(options: CreateOptions): Promise<void> {
   validateMainWorktree();
 
+  await guardMainWorkBranch();
+
   await ensureOnMainWorkBranch();
 
   const count = Number(options.number);

package/src/commands/home.ts

@@ -8,6 +8,7 @@ import {
   getMainWorkBranch,
   printSuccess,
   printInfo,
+  guardMainWorkBranchExists,
 } from '../utils/index.js';
 
 /**
@@ -29,6 +30,7 @@ export function registerHomeCommand(program: Command): void {
 async function handleHome(): Promise<void> {
   validateMainWorktree();
   requireProjectConfig();
+  guardMainWorkBranchExists();
 
   const mainBranch = getMainWorkBranch();
   const currentBranch = getCurrentBranch();

package/src/commands/merge.ts

@@ -33,6 +33,7 @@ import {
   resolveTargetWorktree,
   getMainWorkBranch,
   ensureOnMainWorkBranch,
+  guardMainWorkBranch,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages } from '../utils/index.js';
 
@@ -137,6 +138,8 @@ function cleanupWorktreeAndBranch(worktreePath: string, branchName: string): voi
 async function handleMerge(options: MergeOptions): Promise<void> {
   validateMainWorktree();
 
+  await guardMainWorkBranch();
+
   const mainWorktreePath = getGitTopLevel();
 
   // 确保当前在主工作分支上

package/src/commands/run.ts

@@ -20,6 +20,7 @@ import {
   executeBatchTasks,
   printDryRunPreview,
   ensureOnMainWorkBranch,
+  guardMainWorkBranch,
 } from '../utils/index.js';
 
 /**
@@ -123,6 +124,7 @@ async function handleRun(options: RunOptions): Promise<void> {
 
   // dry-run 模式跳过项目配置前置校验
   if (!options.dryRun) {
+    await guardMainWorkBranch();
     await ensureOnMainWorkBranch();
   }
 

package/src/commands/status.ts

@@ -1,6 +1,6 @@
 import type { Command } from 'commander';
 import chalk from 'chalk';
-import { MESSAGES } from '../constants/index.js';
+import { MESSAGES, VALIDATE_BRANCH_PREFIX } from '../constants/index.js';
 import { logger } from '../logger/index.js';
 import type { StatusOptions, WorktreeDetailedStatus, MainWorktreeStatus, SnapshotSummary, StatusResult, WorktreeInfo } from '../types/index.js';
 import {
@@ -22,6 +22,8 @@ import {
   printDoubleSeparator,
   printSeparator,
   InteractivePanel,
+  loadProjectConfig,
+  checkBranchExists,
 } from '../utils/index.js';
 
 /**
@@ -74,11 +76,18 @@ export function collectStatus(): StatusResult {
   const currentBranch = getCurrentBranch();
   const isClean = isWorkingDirClean();
 
+  // 配置分支信息收集
+  const projectConfig = loadProjectConfig();
+  const configuredMainBranch = projectConfig?.clawtMainWorkBranch || null;
+  const configuredBranchExists = configuredMainBranch ? checkBranchExists(configuredMainBranch) : null;
+
   // 主 worktree 状态
   const main: MainWorktreeStatus = {
     branch: currentBranch,
     isClean,
     projectName,
+    configuredMainBranch,
+    configuredBranchExists,
   };
 
   // 各 worktree 详细状态
@@ -265,6 +274,18 @@ function printMainSection(main: MainWorktreeStatus): void {
   } else {
     printInfo(`    状态: ${chalk.yellow('✗ 有未提交修改')}`);
   }
+
+  // 配置分支信息展示
+  if (main.configuredMainBranch !== null) {
+    if (main.configuredBranchExists === false) {
+      printInfo(`    ${chalk.red(MESSAGES.STATUS_CONFIGURED_BRANCH_DELETED(main.configuredMainBranch))}`);
+    } else if (main.branch !== main.configuredMainBranch && !main.branch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+      printInfo(`    ${chalk.yellow(MESSAGES.STATUS_CONFIGURED_BRANCH_MISMATCH(main.configuredMainBranch))}`);
+    } else {
+      printInfo(`    ${chalk.gray(MESSAGES.STATUS_CONFIGURED_BRANCH(main.configuredMainBranch))}`);
+    }
+  }
+
   printInfo('');
 }
 

package/src/commands/sync.ts

@@ -20,6 +20,7 @@ import {
   getMainWorkBranch,
   rebuildValidateBranch,
   getValidateBranchName,
+  guardMainWorkBranch,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages } from '../utils/index.js';
 
@@ -129,6 +130,7 @@ export async function executeSyncForBranch(targetWorktreePath: string, branch: s
 async function handleSync(options: SyncOptions): Promise<void> {
   validateMainWorktree();
   requireProjectConfig();
+  await guardMainWorkBranch();
 
   logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);
 

package/src/constants/config.ts

@@ -3,7 +3,7 @@ import { VALID_TERMINAL_APPS } from './terminal.js';
 
 /** Claude Code 系统约束提示 */
 export const APPEND_SYSTEM_PROMPT =
-  'After the code execution is completed, it is prohibited to build the project for verification.';
+  'Currently, you are in the git worktree directory. There are no dependencies. To save disk space and improve the speed of task completion, installing dependencies is prohibited.';
 
 /**
  * 配置项完整定义（单一数据源）

package/src/constants/interactive-panel.ts

@@ -40,5 +40,5 @@ export const PANEL_SHORTCUT_KEYS = {
 /** 日期分隔线前缀 */
 export const PANEL_DATE_SEPARATOR_PREFIX = '════';
 
-/** 固定占用行数（顶部分隔线 + 快照摘要 + 底部分隔线 + 底栏） */
-export const PANEL_FIXED_ROWS = 4;
+/** 固定占用行数（配置分支信息 + 快照摘要 + 顶部分隔线 + 底部分隔线 + 底栏） */
+export const PANEL_FIXED_ROWS = 5;

package/src/constants/messages/common.ts

@@ -38,4 +38,10 @@ export const COMMON_MESSAGES = {
   SEPARATOR: '────────────────────────────────────────',
   /** 粗分隔线 */
   DOUBLE_SEPARATOR: '════════════════════════════════════════',
+  /** 守卫检测：配置的主工作分支已不存在 */
+  GUARD_BRANCH_NOT_EXISTS: (branchName: string) =>
+    `配置的主工作分支 ${branchName} 已不存在，请执行 clawt init 重新设置主工作分支`,
+  /** 守卫检测：当前分支与配置的主工作分支不一致 */
+  GUARD_BRANCH_MISMATCH: (configuredBranch: string, currentBranch: string) =>
+    `当前分支 ${currentBranch} 与配置的主工作分支 ${configuredBranch} 不一致，如需更新请执行 clawt init`,
 } as const;

package/src/constants/messages/index.ts

@@ -16,11 +16,11 @@ import { UPDATE_MESSAGES, UPDATE_COMMANDS } from './update.js';
 import { INIT_MESSAGES } from './init.js';
 import { COVER_VALIDATE_MESSAGES } from './cover-validate.js';
 import { HOME_MESSAGES } from './home.js';
-import { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES as PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE } from './interactive-panel.js';
+import { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES as PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE, PANEL_CONFIGURED_BRANCH, PANEL_CONFIGURED_BRANCH_DELETED, PANEL_CONFIGURED_BRANCH_MISMATCH, PANEL_NOT_INITIALIZED } from './interactive-panel.js';
 
 export { CONFIG_ALIAS_DISABLED_HINT };
 export { UPDATE_MESSAGES, UPDATE_COMMANDS };
-export { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE };
+export { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE, PANEL_CONFIGURED_BRANCH, PANEL_CONFIGURED_BRANCH_DELETED, PANEL_CONFIGURED_BRANCH_MISMATCH, PANEL_NOT_INITIALIZED };
 
 /**
  * 提示消息模板

package/src/constants/messages/interactive-panel.ts

@@ -59,3 +59,30 @@ export const PANEL_NOT_TTY = '交互式面板需要 TTY 终端环境，请直接
  * @returns {string} 格式化的标题
  */
 export const PANEL_TITLE = (projectName: string): string => chalk.bold.cyan(`项目状态总览: ${projectName}`);
+
+/**
+ * 面板配置分支信息（正常）
+ * @param {string} branchName - 分支名
+ * @returns {string} 格式化的分支信息
+ */
+export const PANEL_CONFIGURED_BRANCH = (branchName: string): string =>
+  chalk.gray(`主工作分支: ${branchName}`);
+
+/**
+ * 面板配置分支信息（分支已删除）
+ * @param {string} branchName - 分支名
+ * @returns {string} 格式化的分支信息
+ */
+export const PANEL_CONFIGURED_BRANCH_DELETED = (branchName: string): string =>
+  chalk.red(`✗ 主工作分支: ${branchName}（已不存在）`);
+
+/**
+ * 面板配置分支信息（分支不一致）
+ * @param {string} branchName - 分支名
+ * @returns {string} 格式化的分支信息
+ */
+export const PANEL_CONFIGURED_BRANCH_MISMATCH = (branchName: string): string =>
+  chalk.yellow(`⚠ 主工作分支: ${branchName}（不一致）`);
+
+/** 面板配置分支信息（未初始化） */
+export const PANEL_NOT_INITIALIZED = chalk.gray('未初始化（执行 clawt init 设置主工作分支）');

package/src/constants/messages/status.ts

@@ -30,4 +30,13 @@ export const STATUS_MESSAGES = {
   STATUS_LAST_VALIDATED: (relativeTime: string) => `上次验证: ${relativeTime}`,
   /** status 未验证警示 */
   STATUS_NOT_VALIDATED: '✗ 未验证',
+  /** status 配置的主工作分支（正常状态） */
+  STATUS_CONFIGURED_BRANCH: (branchName: string) =>
+    `主工作分支: ${branchName}`,
+  /** status 配置的主工作分支已不存在 */
+  STATUS_CONFIGURED_BRANCH_DELETED: (branchName: string) =>
+    `✗ 主工作分支: ${branchName}（已不存在，请执行 clawt init 重新设置）`,
+  /** status 当前分支与配置的主工作分支不一致 */
+  STATUS_CONFIGURED_BRANCH_MISMATCH: (branchName: string) =>
+    `⚠ 主工作分支: ${branchName}（当前分支不一致，如需更新请执行 clawt init）`,
 } as const;

package/src/types/status.ts

@@ -28,6 +28,10 @@ export interface MainWorktreeStatus {
   isClean: boolean;
   /** 项目名 */
   projectName: string;
+  /** 配置的主工作分支名（项目未初始化时为 null） */
+  configuredMainBranch: string | null;
+  /** 配置的主工作分支是否存在（项目未初始化时为 null） */
+  configuredBranchExists: boolean | null;
 }
 
 /** validate 快照信息 */

package/src/utils/index.ts

@@ -70,7 +70,7 @@ export { truncateTaskDesc, printDryRunPreview } from './dry-run.js';
 export { applyAliases } from './alias.js';
 export { isValidConfigKey, getValidConfigKeys, parseConfigValue, promptConfigValue, formatConfigValue, interactiveConfigEditor } from './config-strategy.js';
 export { checkForUpdates } from './update-checker.js';
-export { getProjectConfigPath, loadProjectConfig, saveProjectConfig, requireProjectConfig, getMainWorkBranch, getValidateRunCommand } from './project-config.js';
+export { getProjectConfigPath, loadProjectConfig, saveProjectConfig, requireProjectConfig, getMainWorkBranch, guardMainWorkBranchExists, guardMainWorkBranch, 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';

package/src/utils/interactive-panel-render.ts

@@ -7,6 +7,7 @@ import {
   PANEL_DATE_SEPARATOR_PREFIX,
   PANEL_FIXED_ROWS,
   UNKNOWN_DATE_GROUP,
+  VALIDATE_BRANCH_PREFIX,
 } from '../constants/index.js';
 import {
   PANEL_FOOTER_SHORTCUTS,
@@ -16,8 +17,12 @@ import {
   PANEL_SNAPSHOT_SUMMARY,
   PANEL_NO_WORKTREES_MSG,
   PANEL_TITLE,
+  PANEL_CONFIGURED_BRANCH,
+  PANEL_CONFIGURED_BRANCH_DELETED,
+  PANEL_CONFIGURED_BRANCH_MISMATCH,
+  PANEL_NOT_INITIALIZED,
 } from '../constants/messages/index.js';
-import type { StatusResult, WorktreeDetailedStatus } from '../types/index.js';
+import type { StatusResult, WorktreeDetailedStatus, MainWorktreeStatus } from '../types/index.js';
 import { formatRelativeTime, groupWorktreesByDate, formatRelativeDate } from './index.js';
 
 /** 面板行类型 */
@@ -73,6 +78,9 @@ export function buildPanelFrame(
   // 标题行
   lines.push(PANEL_TITLE(statusResult.main.projectName));
 
+  // 配置分支信息行
+  lines.push(renderConfiguredBranchLine(statusResult.main));
+
   // 快照摘要行
   lines.push(renderSnapshotSummary(statusResult.snapshots.total, statusResult.snapshots.orphaned));
 
@@ -283,6 +291,24 @@ function formatChangeStatusLabel(status: WorktreeDetailedStatus['changeStatus'])
   }
 }
 
+/**
+ * 渲染配置的主工作分支信息行（面板模式）
+ * @param {MainWorktreeStatus} main - 主 worktree 状态
+ * @returns {string} 格式化的配置分支信息
+ */
+function renderConfiguredBranchLine(main: MainWorktreeStatus): string {
+  if (main.configuredMainBranch === null) {
+    return PANEL_NOT_INITIALIZED;
+  }
+  if (main.configuredBranchExists === false) {
+    return PANEL_CONFIGURED_BRANCH_DELETED(main.configuredMainBranch);
+  }
+  if (main.branch !== main.configuredMainBranch && !main.branch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+    return PANEL_CONFIGURED_BRANCH_MISMATCH(main.configuredMainBranch);
+  }
+  return PANEL_CONFIGURED_BRANCH(main.configuredMainBranch);
+}
+
 /**
  * 渲染快照摘要行
  * @param {number} total - 快照总数
@@ -309,7 +335,7 @@ export function renderFooter(countdown: number): string {
  * @returns {number} 滚动区域总行数
  */
 export function calculateVisibleRows(terminalRows: number): number {
-  // 固定行：标题(1) + 快照摘要 + 顶部分隔线 + 底部分隔线 + 底栏（后四项 = PANEL_FIXED_ROWS）
+  // 固定行：标题(1) + 配置分支信息 + 快照摘要 + 顶部分隔线 + 底部分隔线 + 底栏（后五项 = PANEL_FIXED_ROWS）
   const fixedRows = PANEL_FIXED_ROWS + 1;
   return Math.max(terminalRows - fixedRows, 3);
 }

package/src/utils/project-config.ts

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { PROJECTS_CONFIG_DIR, MESSAGES } from '../constants/index.js';
+import { PROJECTS_CONFIG_DIR, MESSAGES, VALIDATE_BRANCH_PREFIX } from '../constants/index.js';
 import { ClawtError } from '../errors/index.js';
 import { logger } from '../logger/index.js';
-import { getProjectName } from './git.js';
+import { getProjectName, checkBranchExists, getCurrentBranch } from './git.js';
 import { ensureDir } from './fs.js';
+import { printWarning, confirmAction } from './formatter.js';
 import type { ProjectConfig } from '../types/index.js';
 
 /**
@@ -76,6 +77,42 @@ export function getMainWorkBranch(): string {
   return config.clawtMainWorkBranch;
 }
 
+/**
+ * 守卫检测：仅验证配置中的主工作分支是否存在
+ * 分支不存在 → 抛出 ClawtError（致命错误）
+ * 适用于不需要分支一致性检测的场景（如 home 命令）
+ * @param {string} [cwd] - 工作目录
+ */
+export function guardMainWorkBranchExists(cwd?: string): void {
+  const config = requireProjectConfig();
+  const mainBranch = config.clawtMainWorkBranch;
+
+  if (!checkBranchExists(mainBranch, cwd)) {
+    throw new ClawtError(MESSAGES.GUARD_BRANCH_NOT_EXISTS(mainBranch));
+  }
+}
+
+/**
+ * 守卫检测：验证配置中的主工作分支是否有效
+ * 分支不存在 → 抛出 ClawtError（致命错误）
+ * 当前分支与配置分支不一致且非验证分支 → 警告并交互确认是否继续
+ * @param {string} [cwd] - 工作目录
+ */
+export async function guardMainWorkBranch(cwd?: string): Promise<void> {
+  guardMainWorkBranchExists(cwd);
+
+  const config = requireProjectConfig();
+  const mainBranch = config.clawtMainWorkBranch;
+  const currentBranch = getCurrentBranch(cwd);
+  if (currentBranch !== mainBranch && !currentBranch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+    printWarning(MESSAGES.GUARD_BRANCH_MISMATCH(mainBranch, currentBranch));
+    const confirmed = await confirmAction('是否继续执行？');
+    if (!confirmed) {
+      throw new ClawtError(MESSAGES.DESTRUCTIVE_OP_CANCELLED);
+    }
+  }
+}
+
 /**
  * 从项目配置中获取 validate 成功后自动执行的命令
  * @returns {string | undefined} 配置的命令字符串，未配置时返回 undefined

package/tests/unit/commands/cover-validate.test.ts

@@ -48,6 +48,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   printInfo: vi.fn(),
   isWorkingDirClean: vi.fn().mockReturnValue(false),
   confirmAction: vi.fn().mockResolvedValue(true),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerCoverValidateCommand, extractTargetBranchName, findTargetWorktreePath, computeIncrementalPatch } from '../../../src/commands/cover-validate.js';

package/tests/unit/commands/create.test.ts

@@ -33,6 +33,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   printSuccess: vi.fn(),
   printInfo: vi.fn(),
   printSeparator: vi.fn(),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerCreateCommand } from '../../../src/commands/create.js';

package/tests/unit/commands/init.test.ts

@@ -31,6 +31,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   printInfo: vi.fn(),
   safeStringify: vi.fn((value: unknown, indent: number = 2) => JSON.stringify(value, null, indent)),
   interactiveConfigEditor: vi.fn(),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerInitCommand } from '../../../src/commands/init.js';

package/tests/unit/commands/merge.test.ts

@@ -71,6 +71,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   requireProjectConfig: vi.fn().mockReturnValue({ clawtMainWorkBranch: 'main' }),
   getMainWorkBranch: vi.fn().mockReturnValue('main'),
   ensureOnMainWorkBranch: vi.fn(),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerMergeCommand } from '../../../src/commands/merge.js';

package/tests/unit/commands/remove.test.ts

@@ -54,6 +54,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   getValidateBranchName: vi.fn((name: string) => `clawt-validate-${name}`),
   deleteValidateBranch: vi.fn(),
   getCurrentBranch: vi.fn(),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerRemoveCommand } from '../../../src/commands/remove.js';

package/tests/unit/commands/reset.test.ts

@@ -25,6 +25,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   printInfo: vi.fn(),
   requireProjectConfig: vi.fn().mockReturnValue({ clawtMainWorkBranch: 'main' }),
   switchBackIfOnValidateBranch: vi.fn(),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerResetCommand } from '../../../src/commands/reset.js';

package/tests/unit/commands/run.test.ts

@@ -73,6 +73,8 @@ vi.mock('../../../src/utils/index.js', async (importOriginal) => {
     printDryRunPreview: vi.fn(),
     requireProjectConfig: vi.fn().mockReturnValue({ clawtMainWorkBranch: 'main' }),
     ensureOnMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+    guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+    guardMainWorkBranchExists: vi.fn(),
   };
 });
 

package/tests/unit/commands/status.test.ts

@@ -22,7 +22,11 @@ vi.mock('../../../src/constants/index.js', () => ({
     STATUS_NO_DIVERGED_COMMITS: '尚无分叉提交',
     STATUS_LAST_VALIDATED: (relativeTime: string) => `上次验证: ${relativeTime}`,
     STATUS_NOT_VALIDATED: '✗ 未验证',
+    STATUS_CONFIGURED_BRANCH: (branchName: string) => `主工作分支: ${branchName}`,
+    STATUS_CONFIGURED_BRANCH_DELETED: (branchName: string) => `✗ 主工作分支: ${branchName}（已不存在）`,
+    STATUS_CONFIGURED_BRANCH_MISMATCH: (branchName: string) => `⚠ 主工作分支: ${branchName}（当前分支不一致）`,
   },
+  VALIDATE_BRANCH_PREFIX: 'clawt-validate-',
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
@@ -43,6 +47,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   printInfo: vi.fn(),
   printDoubleSeparator: vi.fn(),
   printSeparator: vi.fn(),
+  loadProjectConfig: vi.fn().mockReturnValue(null),
+  checkBranchExists: vi.fn().mockReturnValue(true),
 }));
 
 import { registerStatusCommand } from '../../../src/commands/status.js';

package/tests/unit/commands/sync.test.ts

@@ -48,6 +48,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   getMainWorkBranch: vi.fn().mockReturnValue('main'),
   rebuildValidateBranch: vi.fn(),
   getValidateBranchName: vi.fn((name: string) => `clawt-validate-${name}`),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerSyncCommand } from '../../../src/commands/sync.js';

package/tests/unit/commands/validate.test.ts

@@ -92,6 +92,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   switchToValidateBranch: vi.fn((name: string) => `clawt-validate-${name}`),
   // validate-runner.ts 抽离的函数
   executeRunCommand: vi.fn(),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerValidateCommand } from '../../../src/commands/validate.js';