clawt 3.4.2 → 3.4.4

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`,
   /** 分支名清理后为空 */
@@ -1229,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";
@@ -1294,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");
 }
@@ -1364,7 +1339,60 @@ function getValidateRunCommand() {
   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 validateWorkingDirClean() {
+  if (!isWorkingDirClean()) {
+    throw new ClawtError(MESSAGES.MAIN_WORKTREE_DIRTY);
+  }
+}
+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}`;
 }
@@ -3795,7 +3823,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`);
@@ -3845,9 +3873,10 @@ function registerCreateCommand(program2) {
   });
 }
 async function handleCreate(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
   await guardMainWorkBranch();
   await ensureOnMainWorkBranch();
+  validateWorkingDirClean();
   const count = Number(options.number);
   if (!Number.isInteger(count) || count <= 0) {
     throw new ClawtError(
@@ -3881,8 +3910,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();
@@ -3988,10 +4016,11 @@ function handleDryRunFromFile(options) {
   printDryRunPreview(branchNames, tasks, concurrency);
 }
 async function handleRun(options) {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
   if (!options.dryRun) {
     await guardMainWorkBranch();
     await ensureOnMainWorkBranch();
+    validateWorkingDirClean();
   }
   if (options.file && options.tasks) {
     throw new ClawtError(MESSAGES.FILE_AND_TASKS_CONFLICT);
@@ -4053,7 +4082,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();
@@ -4154,8 +4183,7 @@ 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();
@@ -4189,8 +4217,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();
@@ -4275,8 +4302,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();
@@ -4341,8 +4367,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);
@@ -4421,7 +4446,8 @@ 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);
@@ -4583,8 +4609,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)) {
@@ -4614,7 +4639,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();
@@ -5294,7 +5319,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(
@@ -5307,8 +5332,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 });
@@ -5326,9 +5354,7 @@ function registerHomeCommand(program2) {
   });
 }
 async function handleHome() {
-  validateMainWorktree();
-  requireProjectConfig();
-  guardMainWorkBranchExists();
+  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`,
   /** 分支名清理后为空 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "3.4.2",
+  "version": "3.4.4",
   "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,9 +4,10 @@ import { ClawtError } from '../errors/index.js';
 import { logger } from '../logger/index.js';
 import type { CreateOptions } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   createWorktrees,
   ensureOnMainWorkBranch,
+  validateWorkingDirClean,
   getValidateBranchName,
   printSuccess,
   printInfo,
@@ -34,12 +35,14 @@ 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();
 
+  validateWorkingDirClean();
+
   const count = Number(options.number);
 
   // 校验创建数量必须为正整数

package/src/commands/home.ts

@@ -1,8 +1,7 @@
 import type { Command } from 'commander';
 import { MESSAGES } from '../constants/index.js';
 import {
-  validateMainWorktree,
-  requireProjectConfig,
+  runPreChecks,
   ensureOnMainWorkBranch,
   getCurrentBranch,
   getMainWorkBranch,
@@ -28,9 +27,7 @@ export function registerHomeCommand(program: Command): void {
  * 执行 home 命令：切换回主工作分支
  */
 async function handleHome(): Promise<void> {
-  validateMainWorktree();
-  requireProjectConfig();
-  guardMainWorkBranchExists();
+  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,
@@ -136,7 +136,9 @@ 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();
 

package/src/commands/remove.ts

@@ -4,7 +4,7 @@ import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import type { RemoveOptions } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getProjectWorktreeDir,
   getProjectWorktrees,
@@ -23,7 +23,6 @@ import {
   resolveTargetWorktrees,
   getValidateBranchName,
   deleteValidateBranch,
-  requireProjectConfig,
   getCurrentBranch,
 } from '../utils/index.js';
 import type { WorktreeMultiResolveMessages } from '../utils/index.js';
@@ -56,8 +55,7 @@ export function registerRemoveCommand(program: Command): void {
  * @param {RemoveOptions} options - 命令选项
  */
 async function handleRemove(options: RemoveOptions): Promise<void> {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
 
   const projectName = getProjectName();
   logger.info(`remove 命令执行，项目: ${projectName}`);

package/src/commands/reset.ts

@@ -2,7 +2,7 @@ import type { Command } from 'commander';
 import { logger } from '../logger/index.js';
 import { MESSAGES } from '../constants/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getGitTopLevel,
   getConfigValue,
   isWorkingDirClean,
@@ -11,7 +11,6 @@ import {
   confirmDestructiveAction,
   printSuccess,
   printInfo,
-  requireProjectConfig,
 } from '../utils/index.js';
 
 /**
@@ -31,8 +30,7 @@ export function registerResetCommand(program: Command): void {
  * 执行 reset 命令：重置主 worktree 工作区和暂存区
  */
 async function handleReset(): Promise<void> {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
 
   const mainWorktreePath = getGitTopLevel();
   logger.info('reset 命令执行');

package/src/commands/resume.ts

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

package/src/commands/run.ts

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

package/src/commands/status.ts

@@ -4,7 +4,7 @@ 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 {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getCurrentBranch,
   isWorkingDirClean,
@@ -46,7 +46,7 @@ export function registerStatusCommand(program: Command): void {
  * @param {StatusOptions} options - 命令选项
  */
 async function handleStatus(options: StatusOptions): Promise<void> {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
 
   // 交互式面板模式
   if (options.interactive) {

package/src/commands/sync.ts

@@ -4,7 +4,7 @@ import { ClawtError } from '../errors/index.js';
 import { MESSAGES, AUTO_SAVE_COMMIT_MESSAGE } from '../constants/index.js';
 import type { SyncOptions } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getGitTopLevel,
   getProjectWorktrees,
   isWorkingDirClean,
@@ -16,7 +16,6 @@ import {
   printInfo,
   printWarning,
   resolveTargetWorktree,
-  requireProjectConfig,
   getMainWorkBranch,
   rebuildValidateBranch,
   getValidateBranchName,
@@ -128,8 +127,7 @@ export async function executeSyncForBranch(targetWorktreePath: string, branch: s
  * @param {SyncOptions} options - 命令选项
  */
 async function handleSync(options: SyncOptions): Promise<void> {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
   await guardMainWorkBranch();
 
   logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);

package/src/commands/validate.ts

@@ -4,7 +4,7 @@ import { MESSAGES } from '../constants/index.js';
 import type { ValidateOptions } from '../types/index.js';
 import { executeSyncForBranch } from './sync.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getGitTopLevel,
   getProjectWorktrees,
@@ -25,7 +25,6 @@ import {
   printWarning,
   printInfo,
   resolveTargetWorktree,
-  requireProjectConfig,
   ensureOnMainWorkBranch,
   handleDirtyWorkingDir,
   getValidateRunCommand,
@@ -98,9 +97,7 @@ async function handlePatchApplyFailure(targetWorktreePath: string, branchName: s
  * @param {ValidateOptions} options - 命令选项
  */
 async function handleValidateClean(options: ValidateOptions): Promise<void> {
-  validateMainWorktree();
-  // 显式前置校验：确保项目已初始化
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
 
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
@@ -264,8 +261,7 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     return;
   }
 
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
 
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();

package/src/constants/messages/common.ts

@@ -6,6 +6,8 @@ export const COMMON_MESSAGES = {
   GIT_NOT_INSTALLED: 'Git 未安装或不在 PATH 中，请先安装 Git',
   /** Claude Code CLI 未安装 */
   CLAUDE_NOT_INSTALLED: 'Claude Code CLI 未安装，请先安装：npm install -g @anthropic-ai/claude-code',
+  /** HEAD 不存在（仓库无任何 commit） */
+  HEAD_NOT_FOUND: '当前仓库尚未创建任何提交，请先执行 git commit 创建首次提交后再使用 clawt',
   /** 分支已存在 */
   BRANCH_EXISTS: (name: string) => `分支 ${name} 已存在，无法创建`,
   /** 分支名清理后为空 */

package/src/utils/index.ts

@@ -50,7 +50,7 @@ export {
   createBranch,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
-export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
+export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled, validateHeadExists, validateWorkingDirClean, runPreChecks } from './validation.js';
 export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWorktrees, getWorktreeStatus, createWorktreesByBranches } from './worktree.js';
 export { loadConfig, writeDefaultConfig, writeConfig, saveConfig, getConfigValue, ensureClawtDirs, parseConcurrency } from './config.js';
 export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime, formatDiskSize, formatLocalISOString } from './formatter.js';

package/src/utils/validation.ts

@@ -1,7 +1,20 @@
 import { MESSAGES } from '../constants/index.js';
 import { ClawtError } from '../errors/index.js';
 import { execCommand } from './shell.js';
-import { getGitCommonDir } from './git.js';
+import { getGitCommonDir, isWorkingDirClean } from './git.js';
+import { requireProjectConfig, guardMainWorkBranchExists } from './project-config.js';
+
+/** 统一前置校验选项 */
+interface PreCheckOptions {
+  /** 校验是否在主 worktree 根目录 */
+  mainWorktree?: boolean;
+  /** 校验 HEAD 是否存在（仓库有至少一次 commit） */
+  headExists?: boolean;
+  /** 校验项目是否已初始化（配置文件存在） */
+  projectConfig?: boolean;
+  /** 校验配置的主工作分支是否存在 */
+  branchExists?: boolean;
+}
 
 /**
  * 校验当前目录是否为主 worktree 的根目录
@@ -46,3 +59,51 @@ export function validateClaudeCodeInstalled(): void {
     throw new ClawtError(MESSAGES.CLAUDE_NOT_INSTALLED);
   }
 }
+
+/**
+ * 校验 HEAD 是否存在（仓库是否有至少一次 commit）
+ * git init 后未做任何 commit 时，HEAD 不指向有效引用
+ * @throws {ClawtError} HEAD 不存在时抛出
+ */
+export function validateHeadExists(): void {
+  try {
+    execCommand('git rev-parse --verify HEAD');
+  } catch {
+    throw new ClawtError(MESSAGES.HEAD_NOT_FOUND);
+  }
+}
+
+/**
+ * 校验主分支工作区和暂存区是否干净
+ * 当存在未提交的更改时抛出错误，防止基于脏状态创建 worktree
+ * @throws {ClawtError} 工作区或暂存区不干净时抛出
+ */
+export function validateWorkingDirClean(): void {
+  if (!isWorkingDirClean()) {
+    throw new ClawtError(MESSAGES.MAIN_WORKTREE_DIRTY);
+  }
+}
+
+/**
+ * 统一前置校验入口，按需执行各项校验
+ * @param {PreCheckOptions} options - 校验选项
+ * @param {boolean} [options.mainWorktree] - 校验是否在主 worktree 根目录
+ * @param {boolean} [options.headExists] - 校验 HEAD 是否存在
+ * @param {boolean} [options.projectConfig] - 校验项目是否已初始化
+ * @param {boolean} [options.branchExists] - 校验配置的主工作分支是否存在
+ * @throws {ClawtError} 任一校验未通过时抛出
+ */
+export function runPreChecks(options: PreCheckOptions): void {
+  if (options.mainWorktree) {
+    validateMainWorktree();
+  }
+  if (options.headExists) {
+    validateHeadExists();
+  }
+  if (options.projectConfig) {
+    requireProjectConfig();
+  }
+  if (options.branchExists) {
+    guardMainWorkBranchExists();
+  }
+}

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

@@ -29,7 +29,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   requireProjectConfig: vi.fn(),
   getProjectName: vi.fn().mockReturnValue('test-project'),
   getGitTopLevel: vi.fn().mockReturnValue('/repo'),

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

@@ -24,7 +24,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   createWorktrees: vi.fn(),
   getConfigValue: vi.fn().mockReturnValue(true),
   requireProjectConfig: vi.fn().mockReturnValue({ clawtMainWorkBranch: 'main' }),
@@ -38,14 +38,14 @@ vi.mock('../../../src/utils/index.js', () => ({
 }));
 
 import { registerCreateCommand } from '../../../src/commands/create.js';
-import { validateMainWorktree, createWorktrees, printSuccess } from '../../../src/utils/index.js';
+import { runPreChecks, createWorktrees, printSuccess } from '../../../src/utils/index.js';
 
-const mockedValidateMainWorktree = vi.mocked(validateMainWorktree);
+const mockedRunPreChecks = vi.mocked(runPreChecks);
 const mockedCreateWorktrees = vi.mocked(createWorktrees);
 const mockedPrintSuccess = vi.mocked(printSuccess);
 
 beforeEach(() => {
-  mockedValidateMainWorktree.mockReset();
+  mockedRunPreChecks.mockReset();
   mockedCreateWorktrees.mockReset();
   mockedPrintSuccess.mockReset();
 });
@@ -70,7 +70,7 @@ describe('handleCreate', () => {
     registerCreateCommand(program);
     await program.parseAsync(['create', '-b', 'feature'], { from: 'user' });
 
-    expect(mockedValidateMainWorktree).toHaveBeenCalled();
+    expect(mockedRunPreChecks).toHaveBeenCalled();
     expect(mockedCreateWorktrees).toHaveBeenCalledWith('feature', 1);
     expect(mockedPrintSuccess).toHaveBeenCalled();
   });

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

@@ -22,7 +22,8 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
+  validateHeadExists: vi.fn(),
   getCurrentBranch: vi.fn().mockReturnValue('main'),
   loadProjectConfig: vi.fn(),
   saveProjectConfig: vi.fn(),

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

@@ -13,7 +13,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   getProjectName: vi.fn(),
   getProjectWorktrees: vi.fn(),
   getWorktreeStatus: vi.fn(),
@@ -23,16 +23,16 @@ vi.mock('../../../src/utils/index.js', () => ({
 }));
 
 import { registerListCommand } from '../../../src/commands/list.js';
-import { validateMainWorktree, getProjectName, getProjectWorktrees, getWorktreeStatus, printInfo } from '../../../src/utils/index.js';
+import { runPreChecks, getProjectName, getProjectWorktrees, getWorktreeStatus, printInfo } from '../../../src/utils/index.js';
 
-const mockedValidateMainWorktree = vi.mocked(validateMainWorktree);
+const mockedRunPreChecks = vi.mocked(runPreChecks);
 const mockedGetProjectName = vi.mocked(getProjectName);
 const mockedGetProjectWorktrees = vi.mocked(getProjectWorktrees);
 const mockedGetWorktreeStatus = vi.mocked(getWorktreeStatus);
 const mockedPrintInfo = vi.mocked(printInfo);
 
 beforeEach(() => {
-  mockedValidateMainWorktree.mockReset();
+  mockedRunPreChecks.mockReset();
   mockedGetProjectName.mockReset();
   mockedGetProjectWorktrees.mockReset();
   mockedGetWorktreeStatus.mockReset();
@@ -58,7 +58,7 @@ describe('handleList', () => {
     registerListCommand(program);
     program.parse(['list'], { from: 'user' });
 
-    expect(mockedValidateMainWorktree).toHaveBeenCalled();
+    expect(mockedRunPreChecks).toHaveBeenCalled();
     expect(mockedPrintInfo).toHaveBeenCalled();
   });
 

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

@@ -40,7 +40,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   getProjectName: vi.fn(),
   getGitTopLevel: vi.fn(),
   getProjectWorktrees: vi.fn(),

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

@@ -33,7 +33,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   getProjectName: vi.fn(),
   getProjectWorktreeDir: vi.fn(),
   getProjectWorktrees: vi.fn(),
@@ -60,7 +60,7 @@ vi.mock('../../../src/utils/index.js', () => ({
 
 import { registerRemoveCommand } from '../../../src/commands/remove.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getProjectWorktrees,
   removeWorktreeByPath,
@@ -91,7 +91,7 @@ const mockedResolveTargetWorktrees = vi.mocked(resolveTargetWorktrees);
 const mockedGetCurrentBranch = vi.mocked(getCurrentBranch);
 
 beforeEach(() => {
-  vi.mocked(validateMainWorktree).mockReset();
+  vi.mocked(runPreChecks).mockReset();
   mockedGetProjectName.mockReturnValue('test-project');
   mockedGetProjectWorktrees.mockReset();
   mockedRemoveWorktreeByPath.mockReset();

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

@@ -14,7 +14,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   getGitTopLevel: vi.fn(),
   getConfigValue: vi.fn(),
   isWorkingDirClean: vi.fn(),

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

@@ -17,7 +17,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   validateClaudeCodeInstalled: vi.fn(),
   getProjectWorktrees: vi.fn(),
   launchInteractiveClaude: vi.fn(),
@@ -33,7 +33,7 @@ vi.mock('../../../src/utils/index.js', () => ({
 
 import { registerResumeCommand } from '../../../src/commands/resume.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   validateClaudeCodeInstalled,
   getProjectWorktrees,
   launchInteractiveClaude,
@@ -45,7 +45,7 @@ import {
   getConfigValue,
 } from '../../../src/utils/index.js';
 
-const mockedValidateMainWorktree = vi.mocked(validateMainWorktree);
+const mockedRunPreChecks = vi.mocked(runPreChecks);
 const mockedValidateClaudeCodeInstalled = vi.mocked(validateClaudeCodeInstalled);
 const mockedGetProjectWorktrees = vi.mocked(getProjectWorktrees);
 const mockedLaunchInteractiveClaude = vi.mocked(launchInteractiveClaude);
@@ -57,7 +57,7 @@ const mockedConfirmAction = vi.mocked(confirmAction);
 const mockedGetConfigValue = vi.mocked(getConfigValue);
 
 beforeEach(() => {
-  mockedValidateMainWorktree.mockReset();
+  mockedRunPreChecks.mockReset();
   mockedValidateClaudeCodeInstalled.mockReset();
   mockedGetProjectWorktrees.mockReset();
   mockedLaunchInteractiveClaude.mockReset();
@@ -90,7 +90,7 @@ describe('handleResume', () => {
     registerResumeCommand(program);
     await program.parseAsync(['resume', '-b', 'feature'], { from: 'user' });
 
-    expect(mockedValidateMainWorktree).toHaveBeenCalled();
+    expect(mockedRunPreChecks).toHaveBeenCalled();
     expect(mockedValidateClaudeCodeInstalled).toHaveBeenCalled();
     expect(mockedResolveTargetWorktrees).toHaveBeenCalled();
     expect(mockedPromptGroupedMultiSelectBranches).not.toHaveBeenCalled();

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

@@ -50,7 +50,7 @@ vi.mock('../../../src/utils/index.js', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../../../src/utils/index.js')>();
   return {
     ...actual,
-    validateMainWorktree: vi.fn(),
+    runPreChecks: vi.fn(),
     validateClaudeCodeInstalled: vi.fn(),
     createWorktrees: vi.fn(),
     sanitizeBranchName: vi.fn(),

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

@@ -30,7 +30,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   getProjectName: vi.fn(),
   getCurrentBranch: vi.fn(),
   isWorkingDirClean: vi.fn(),

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

@@ -31,7 +31,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   getGitTopLevel: vi.fn(),
   getProjectWorktrees: vi.fn(),
   isWorkingDirClean: vi.fn(),

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

@@ -57,7 +57,7 @@ vi.mock('enquirer', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   getProjectName: vi.fn(),
   getGitTopLevel: vi.fn(),
   getProjectWorktrees: vi.fn(),

package/tests/unit/utils/validation.test.ts

@@ -10,6 +10,12 @@ vi.mock('../../../src/utils/git.js', () => ({
   getGitCommonDir: vi.fn(),
 }));
 
+// mock project-config（runPreChecks 依赖 requireProjectConfig 和 guardMainWorkBranchExists）
+vi.mock('../../../src/utils/project-config.js', () => ({
+  requireProjectConfig: vi.fn(),
+  guardMainWorkBranchExists: vi.fn(),
+}));
+
 // mock logger
 vi.mock('../../../src/logger/index.js', () => ({
   logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
@@ -17,11 +23,14 @@ vi.mock('../../../src/logger/index.js', () => ({
 
 import { execCommand } from '../../../src/utils/shell.js';
 import { getGitCommonDir } from '../../../src/utils/git.js';
-import { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from '../../../src/utils/validation.js';
+import { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled, validateHeadExists, runPreChecks } from '../../../src/utils/validation.js';
+import { requireProjectConfig, guardMainWorkBranchExists } from '../../../src/utils/project-config.js';
 import { ClawtError } from '../../../src/errors/index.js';
 
 const mockedExecCommand = vi.mocked(execCommand);
 const mockedGetGitCommonDir = vi.mocked(getGitCommonDir);
+const mockedRequireProjectConfig = vi.mocked(requireProjectConfig);
+const mockedGuardMainWorkBranchExists = vi.mocked(guardMainWorkBranchExists);
 
 describe('validateMainWorktree', () => {
   it('.git 返回时正常通过', () => {
@@ -63,3 +72,36 @@ describe('validateClaudeCodeInstalled', () => {
     expect(() => validateClaudeCodeInstalled()).toThrow(ClawtError);
   });
 });
+
+describe('validateHeadExists', () => {
+  it('HEAD 存在时正常通过', () => {
+    mockedExecCommand.mockReturnValue('abc1234');
+    expect(() => validateHeadExists()).not.toThrow();
+  });
+
+  it('HEAD 不存在时抛出 ClawtError', () => {
+    mockedExecCommand.mockImplementation(() => { throw new Error('fatal: ambiguous argument HEAD'); });
+    expect(() => validateHeadExists()).toThrow(ClawtError);
+  });
+});
+
+describe('runPreChecks', () => {
+  it('按选项组合调用对应校验', () => {
+    mockedGetGitCommonDir.mockReturnValue('.git');
+    mockedExecCommand.mockReturnValue('abc1234');
+    mockedRequireProjectConfig.mockReturnValue({ clawtMainWorkBranch: 'main' });
+    mockedGuardMainWorkBranchExists.mockReturnValue(undefined);
+
+    expect(() => runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true, branchExists: true })).not.toThrow();
+  });
+
+  it('未设置的选项不触发校验', () => {
+    // 不设置任何选项，不应该调用任何校验函数
+    mockedGetGitCommonDir.mockImplementation(() => { throw new Error('should not be called'); });
+    mockedExecCommand.mockImplementation(() => { throw new Error('should not be called'); });
+    mockedRequireProjectConfig.mockImplementation(() => { throw new Error('should not be called'); });
+    mockedGuardMainWorkBranchExists.mockImplementation(() => { throw new Error('should not be called'); });
+
+    expect(() => runPreChecks({})).not.toThrow();
+  });
+});