clawt 3.9.3 → 3.9.5

package/dist/index.js

@@ -73,7 +73,9 @@ var COMMON_MESSAGES = {
   \u539F\u56E0\uFF1A\u9501\u6587\u4EF6\u5DF2\u5B58\u5728\uFF08\u53EF\u80FD\u662F\u4E0A\u6B21 git \u64CD\u4F5C\u5F02\u5E38\u4E2D\u65AD\u6B8B\u7559\uFF09
   \u9501\u6587\u4EF6\u8DEF\u5F84\uFF1A${lockFilePath}
   \u4FEE\u590D\u65B9\u6CD5\uFF1A\u786E\u8BA4\u6CA1\u6709\u5176\u4ED6 git \u64CD\u4F5C\u5728\u8FDB\u884C\u540E\uFF0C\u6267\u884C\u4EE5\u4E0B\u547D\u4EE4\u5220\u9664\u9501\u6587\u4EF6\uFF1A
-  rm ${lockFilePath}`
+  rm ${lockFilePath}`,
+  /** Git index.lock 重试中（简短提示） */
+  GIT_INDEX_LOCK_RETRYING: "Git index \u88AB\u9501\u5B9A\uFF0C\u6B63\u5728\u91CD\u8BD5..."
 };
 
 // src/constants/messages/run.ts
@@ -655,7 +657,7 @@ var PANEL_NOT_TTY = "\u4EA4\u4E92\u5F0F\u9762\u677F\u9700\u8981 TTY \u7EC8\u7AEF
 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_CONFIGURED_BRANCH_MISMATCH = (branchName) => chalk.red(`\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");
 var PANEL_UNKNOWN_DATE = "\u672A\u77E5\u65E5\u671F";
 var PANEL_SYNCED_WITH_MAIN = "\u4E0E\u4E3B\u5206\u652F\u540C\u6B65";
@@ -798,6 +800,12 @@ var PROJECT_CONFIG_DESCRIPTIONS = deriveConfigDescriptions2(PROJECT_CONFIG_DEFIN
 // src/constants/git.ts
 var AUTO_SAVE_COMMIT_MESSAGE_PREFIX = "clawt: auto-save before merging";
 var EXEC_MAX_BUFFER = 200 * 1024 * 1024;
+var GIT_INDEX_LOCK_RETRY = {
+  /** 重试次数（用户反馈"重试一下就可以了"，单次重试足够） */
+  MAX_RETRIES: 1,
+  /** 重试延迟毫秒数（让锁文件有时间被释放） */
+  DELAY_MS: 150
+};
 
 // src/constants/logger.ts
 var DEBUG_TIMESTAMP_FORMAT = "HH:mm:ss.SSS";
@@ -1043,6 +1051,20 @@ function throwIfGitIndexLockError(error, cwd) {
     throw new ClawtError(MESSAGES.GIT_INDEX_LOCKED(lockFilePath));
   }
 }
+function sleepSync(ms) {
+  const sharedBuffer = new SharedArrayBuffer(4);
+  const int32 = new Int32Array(sharedBuffer);
+  Atomics.wait(int32, 0, 0, ms);
+}
+function shouldRetryGitIndexLockError(error, retryCount) {
+  const errorMessage = extractFullErrorMessage(error);
+  return isGitIndexLockError(errorMessage) && retryCount < GIT_INDEX_LOCK_RETRY.MAX_RETRIES;
+}
+function waitForGitIndexLockRetrySync() {
+  process.stderr.write(`${MESSAGES.GIT_INDEX_LOCK_RETRYING}
+`);
+  sleepSync(GIT_INDEX_LOCK_RETRY.DELAY_MS);
+}
 
 // src/utils/shell.ts
 function getEnvWithoutNestedSessionFlag() {
@@ -1051,17 +1073,26 @@ function getEnvWithoutNestedSessionFlag() {
 }
 function execCommand(command, options) {
   logger.debug(`\u6267\u884C\u547D\u4EE4: ${command}${options?.cwd ? ` (cwd: ${options.cwd})` : ""}`);
-  try {
-    const result = execSync2(command, {
-      cwd: options?.cwd,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      maxBuffer: EXEC_MAX_BUFFER
-    });
-    return result.trim();
-  } catch (error) {
-    throwIfGitIndexLockError(error, options?.cwd);
-    throw error;
+  let retryCount = 0;
+  while (true) {
+    try {
+      const result = execSync2(command, {
+        cwd: options?.cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        maxBuffer: EXEC_MAX_BUFFER
+      });
+      return result.trim();
+    } catch (error) {
+      if (shouldRetryGitIndexLockError(error, retryCount)) {
+        retryCount++;
+        logger.debug(`\u68C0\u6D4B\u5230 index.lock \u9519\u8BEF\uFF0C\u7B2C ${retryCount} \u6B21\u91CD\u8BD5`);
+        waitForGitIndexLockRetrySync();
+        continue;
+      }
+      throwIfGitIndexLockError(error, options?.cwd);
+      throw error;
+    }
   }
 }
 function spawnProcess(command, args, options) {
@@ -1081,18 +1112,27 @@ function killAllChildProcesses(children) {
 }
 function execCommandWithInput(command, args, options) {
   logger.debug(`\u6267\u884C\u547D\u4EE4(stdin): ${command} ${args.join(" ")}${options.cwd ? ` (cwd: ${options.cwd})` : ""}`);
-  try {
-    const result = execFileSync(command, args, {
-      cwd: options.cwd,
-      input: options.input,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      maxBuffer: EXEC_MAX_BUFFER
-    });
-    return result.trim();
-  } catch (error) {
-    throwIfGitIndexLockError(error, options.cwd);
-    throw error;
+  let retryCount = 0;
+  while (true) {
+    try {
+      const result = execFileSync(command, args, {
+        cwd: options.cwd,
+        input: options.input,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        maxBuffer: EXEC_MAX_BUFFER
+      });
+      return result.trim();
+    } catch (error) {
+      if (shouldRetryGitIndexLockError(error, retryCount)) {
+        retryCount++;
+        logger.debug(`\u68C0\u6D4B\u5230 index.lock \u9519\u8BEF\uFF0C\u7B2C ${retryCount} \u6B21\u91CD\u8BD5`);
+        waitForGitIndexLockRetrySync();
+        continue;
+      }
+      throwIfGitIndexLockError(error, options.cwd);
+      throw error;
+    }
   }
 }
 function runCommandInherited(command, options) {
@@ -5597,7 +5637,7 @@ function printMainSection(main2) {
     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))}`);
+      printInfo(`    ${chalk11.red(MESSAGES.STATUS_CONFIGURED_BRANCH_MISMATCH(main2.configuredMainBranch))}`);
     } else {
       printInfo(`    ${chalk11.gray(MESSAGES.STATUS_CONFIGURED_BRANCH(main2.configuredMainBranch))}`);
     }

package/dist/postinstall.js

@@ -64,7 +64,9 @@ var COMMON_MESSAGES = {
   \u539F\u56E0\uFF1A\u9501\u6587\u4EF6\u5DF2\u5B58\u5728\uFF08\u53EF\u80FD\u662F\u4E0A\u6B21 git \u64CD\u4F5C\u5F02\u5E38\u4E2D\u65AD\u6B8B\u7559\uFF09
   \u9501\u6587\u4EF6\u8DEF\u5F84\uFF1A${lockFilePath}
   \u4FEE\u590D\u65B9\u6CD5\uFF1A\u786E\u8BA4\u6CA1\u6709\u5176\u4ED6 git \u64CD\u4F5C\u5728\u8FDB\u884C\u540E\uFF0C\u6267\u884C\u4EE5\u4E0B\u547D\u4EE4\u5220\u9664\u9501\u6587\u4EF6\uFF1A
-  rm ${lockFilePath}`
+  rm ${lockFilePath}`,
+  /** Git index.lock 重试中（简短提示） */
+  GIT_INDEX_LOCK_RETRYING: "Git index \u88AB\u9501\u5B9A\uFF0C\u6B63\u5728\u91CD\u8BD5..."
 };
 
 // src/constants/messages/run.ts

package/docs/spec.md

@@ -384,6 +384,7 @@ async function interactiveConfigEditor<T extends object>(
 | Worktree 路径已存在               | 输出错误提示，退出 (exit code 1)                            |
 | Git 命令执行失败                  | 捕获 stderr，记录日志，输出错误提示，退出 (exit code 1)      |
 | 目标 worktree 不存在              | 输出错误提示（列出可用 worktree），退出 (exit code 1)        |
+| Git index.lock 被锁定             | 自动重试 1 次（延迟 150ms），重试失败则输出错误提示和修复方法 |
 
 ### 7.2 退出码
 

package/docs/status.md

@@ -50,7 +50,7 @@ clawt status [--json] [-i | --interactive]
 
 主 Worktree 区块会显示配置的主工作分支信息，根据状态有以下三种展示：
 - **正常**（灰色）：`主工作分支: <branchName>`
-- **当前分支不一致**（黄色）：`⚠ 主工作分支: <branchName>（当前分支不一致，如需更新请执行 clawt init）`
+- **当前分支不一致**（红色）：`⚠ 主工作分支: <branchName>（当前分支不一致，如需更新请执行 clawt init）`
 - **分支已不存在**（红色）：`✗ 主工作分支: <branchName>（已不存在，请执行 clawt init 重新设置）`
 
 注意：当项目未初始化（`configuredMainBranch` 为 null）时不展示配置分支信息；当主 worktree 当前处于验证分支（`VALIDATE_BRANCH_PREFIX` 前缀）时不显示不一致警告。
@@ -184,7 +184,7 @@ clawt status [--json] [-i | --interactive]
   - `STATUS_SNAPSHOT_ORPHANED(count)`：孤立快照警告（接受数量参数）
   - `STATUS_CONFIGURED_BRANCH(branchName)`：配置的主工作分支（正常状态，灰色）
   - `STATUS_CONFIGURED_BRANCH_DELETED(branchName)`：配置的主工作分支已不存在（红色）
-  - `STATUS_CONFIGURED_BRANCH_MISMATCH(branchName)`：当前分支与配置不一致（黄色）
+  - `STATUS_CONFIGURED_BRANCH_MISMATCH(branchName)`：当前分支与配置不一致（红色）
 - `getWorktreeCreatedTime()` 工具函数（在 `src/utils/worktree-matcher.ts`），通过 `fs.statSync().birthtime` 获取 worktree 目录的创建时间，返回 ISO 8601 格式字符串或 null
 - `getSnapshotModifiedTime()` 工具函数（在 `src/utils/validate-snapshot.ts`），通过 `fs.statSync` 获取快照文件的修改时间（mtime），返回 UTC 时区的 ISO 8601 格式字符串（`toISOString()` 格式）或 null
 - `formatRelativeTime()` 格式化函数（在 `src/utils/formatter.ts`），将 ISO 8601 日期字符串转换为中文相对时间描述（如"3 天前"、"2 小时前"、"刚刚"），无效日期时返回 null
@@ -241,7 +241,7 @@ clawt status [--json] [-i | --interactive]
 2. **配置分支信息行**：显示配置的主工作分支状态，有以下四种情况：
    - 正常（灰色）：`主工作分支: <branchName>`
    - 分支已删除（红色）：`✗ 主工作分支: <branchName>（已不存在）`
-   - 分支不一致（黄色）：`⚠ 主工作分支: <branchName>（不一致）`
+   - 分支不一致（红色）：`⚠ 主工作分支: <branchName>（不一致）`
    - 未初始化（灰色）：`未初始化（执行 clawt init 设置主工作分支）`
 3. **工作区 diff 信息行**：显示主工作分支的工作区 diff 统计，有变更时格式为 `工作区: +N -M`（新增行数绿色，删除行数红色），无变更时显示 `工作区: 无变更`（绿色）
 4. **顶部分隔线**：当存在向上溢出时，分隔线中间嵌入 `↑ 更多 worktree...` 提示
@@ -338,7 +338,7 @@ Worktree 按创建日期分组（复用 `groupWorktreesByDate()`），每组前
   - `PANEL_TITLE(projectName)`：面板标题
   - `PANEL_CONFIGURED_BRANCH(branchName)`：配置分支信息（正常状态，灰色）
   - `PANEL_CONFIGURED_BRANCH_DELETED(branchName)`：配置分支信息（分支已删除，红色）
-  - `PANEL_CONFIGURED_BRANCH_MISMATCH(branchName)`：配置分支信息（分支不一致，黄色）
+  - `PANEL_CONFIGURED_BRANCH_MISMATCH(branchName)`：配置分支信息（分支不一致，红色）
   - `PANEL_NOT_INITIALIZED`：未初始化提示（灰色）
 - `PanelLine` 接口（`src/utils/interactive-panel-render.ts`）：面板行类型定义，包含 `type`（`'separator'` | `'worktree-content'`）、`text`、可选 `worktreeIndex`
 - `collectStatus()` 函数已改为导出（`export`），以便 `InteractivePanel` 作为数据收集函数引用

package/package.json

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

package/src/commands/status.ts

@@ -272,7 +272,7 @@ function printMainSection(main: MainWorktreeStatus): void {
     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))}`);
+      printInfo(`    ${chalk.red(MESSAGES.STATUS_CONFIGURED_BRANCH_MISMATCH(main.configuredMainBranch))}`);
     } else {
       printInfo(`    ${chalk.gray(MESSAGES.STATUS_CONFIGURED_BRANCH(main.configuredMainBranch))}`);
     }

package/src/constants/git.ts

@@ -3,3 +3,14 @@ export const AUTO_SAVE_COMMIT_MESSAGE_PREFIX = 'clawt: auto-save before merging'
 
 /** execSync 最大缓冲区大小（200MB），防止大分支 diff 时触发 ENOBUFS 错误 */
 export const EXEC_MAX_BUFFER = 200 * 1024 * 1024;
+
+/**
+ * Git index.lock 错误重试配置
+ * 当检测到 index.lock 错误时自动重试，避免因短暂竞争导致用户操作失败
+ */
+export const GIT_INDEX_LOCK_RETRY = {
+  /** 重试次数（用户反馈"重试一下就可以了"，单次重试足够） */
+  MAX_RETRIES: 1,
+  /** 重试延迟毫秒数（让锁文件有时间被释放） */
+  DELAY_MS: 150,
+} as const;

package/src/constants/messages/common.ts

@@ -55,4 +55,6 @@ export const COMMON_MESSAGES = {
     `  锁文件路径：${lockFilePath}\n` +
     `  修复方法：确认没有其他 git 操作在进行后，执行以下命令删除锁文件：\n` +
     `  rm ${lockFilePath}`,
+  /** Git index.lock 重试中（简短提示） */
+  GIT_INDEX_LOCK_RETRYING: 'Git index 被锁定，正在重试...',
 } as const;

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

@@ -83,7 +83,7 @@ export const PANEL_CONFIGURED_BRANCH_DELETED = (branchName: string): string =>
  * @returns {string} 格式化的分支信息
  */
 export const PANEL_CONFIGURED_BRANCH_MISMATCH = (branchName: string): string =>
-  chalk.yellow(`⚠ 主工作分支: ${branchName}（不一致）`);
+  chalk.red(`⚠ 主工作分支: ${branchName}（不一致）`);
 
 /** 面板配置分支信息（未初始化） */
 export const PANEL_NOT_INITIALIZED = chalk.gray('未初始化（执行 clawt init 设置主工作分支）');

package/src/utils/git-lock.ts

@@ -3,6 +3,7 @@ import { execSync } from 'node:child_process';
 import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
+import { GIT_INDEX_LOCK_RETRY } from '../constants/git.js';
 
 /**
  * index.lock 错误的关键词匹配模式
@@ -38,7 +39,7 @@ export function isGitIndexLockError(errorMessage: string): boolean {
  * @param {unknown} error - 捕获的错误对象
  * @returns {string} 合并后的错误消息
  */
-function extractFullErrorMessage(error: unknown): string {
+export function extractFullErrorMessage(error: unknown): string {
   if (!(error instanceof Error)) return String(error);
   const stderr = (error as { stderr?: string | Buffer }).stderr;
   const stderrStr = stderr ? String(stderr) : '';
@@ -94,3 +95,34 @@ export function throwIfGitIndexLockError(error: unknown, cwd?: string): void {
     throw new ClawtError(MESSAGES.GIT_INDEX_LOCKED(lockFilePath));
   }
 }
+
+/**
+ * 同步延迟函数（使用 Atomics.wait 实现真正的阻塞等待）
+ * 相比 busy-wait，不消耗 CPU 资源
+ * @param {number} ms - 延迟毫秒数
+ */
+function sleepSync(ms: number): void {
+  const sharedBuffer = new SharedArrayBuffer(4);
+  const int32 = new Int32Array(sharedBuffer);
+  Atomics.wait(int32, 0, 0, ms);
+}
+
+/**
+ * 检测是否应该重试 Git index.lock 错误
+ * @param {unknown} error - 捕获的错误对象
+ * @param {number} retryCount - 当前已重试次数
+ * @returns {boolean} 是否应重试（是 lock 错误且未超过重试上限）
+ */
+export function shouldRetryGitIndexLockError(error: unknown, retryCount: number): boolean {
+  const errorMessage = extractFullErrorMessage(error);
+  return isGitIndexLockError(errorMessage) && retryCount < GIT_INDEX_LOCK_RETRY.MAX_RETRIES;
+}
+
+/**
+ * 等待 index.lock 重试延迟（同步版本）
+ * 打印提示信息并等待指定时间
+ */
+export function waitForGitIndexLockRetrySync(): void {
+  process.stderr.write(`${MESSAGES.GIT_INDEX_LOCK_RETRYING}\n`);
+  sleepSync(GIT_INDEX_LOCK_RETRY.DELAY_MS);
+}

package/src/utils/shell.ts

@@ -2,7 +2,7 @@ import { execSync, execFileSync, spawn, spawnSync, type ChildProcess, type Spawn
 import { logger } from '../logger/index.js';
 import { EXEC_MAX_BUFFER } from '../constants/git.js';
 import { CLAUDE_CODE_ENTRYPOINT_VALUE } from '../constants/index.js';
-import { throwIfGitIndexLockError } from './git-lock.js';
+import { throwIfGitIndexLockError, shouldRetryGitIndexLockError, waitForGitIndexLockRetrySync } from './git-lock.js';
 
 /**
  * 获取移除了 CLAUDECODE 嵌套会话标记的环境变量副本，并注入 CLAUDE_CODE_ENTRYPOINT 标识
@@ -45,26 +45,39 @@ export interface ParallelCommandResultWithStderr extends ParallelCommandResult {
 
 /**
  * 同步执行 shell 命令并返回 stdout
+ * 当检测到 Git index.lock 错误时，会自动重试一次
  * @param {string} command - 要执行的命令
  * @param {object} options - 可选配置
  * @param {string} options.cwd - 工作目录
  * @returns {string} 命令的标准输出（已 trim）
- * @throws {ClawtError} 检测到 index.lock 错误时抛出中文友好提示
+ * @throws {ClawtError} 检测到 index.lock 错误且重试失败时抛出中文友好提示
  * @throws {Error} 其他命令执行失败时抛出
  */
 export function execCommand(command: string, options?: { cwd?: string }): string {
   logger.debug(`执行命令: ${command}${options?.cwd ? ` (cwd: ${options.cwd})` : ''}`);
-  try {
-    const result = execSync(command, {
-      cwd: options?.cwd,
-      encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      maxBuffer: EXEC_MAX_BUFFER,
-    });
-    return result.trim();
-  } catch (error) {
-    throwIfGitIndexLockError(error, options?.cwd);
-    throw error;
+
+  let retryCount = 0;
+
+  while (true) {
+    try {
+      const result = execSync(command, {
+        cwd: options?.cwd,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        maxBuffer: EXEC_MAX_BUFFER,
+      });
+      return result.trim();
+    } catch (error) {
+      if (shouldRetryGitIndexLockError(error, retryCount)) {
+        retryCount++;
+        logger.debug(`检测到 index.lock 错误，第 ${retryCount} 次重试`);
+        waitForGitIndexLockRetrySync();
+        continue;
+      }
+
+      throwIfGitIndexLockError(error, options?.cwd);
+      throw error;
+    }
   }
 }
 
@@ -104,29 +117,42 @@ export function killAllChildProcesses(children: ChildProcess[]): void {
 
 /**
  * 同步执行命令，通过 stdin 传入数据
+ * 当检测到 Git index.lock 错误时，会自动重试一次
  * @param {string} command - 要执行的命令
  * @param {string[]} args - 命令参数
  * @param {object} options - 配置
  * @param {Buffer} options.input - 通过 stdin 传入的数据（Buffer 格式，保留二进制完整性）
  * @param {string} [options.cwd] - 工作目录
  * @returns {string} 命令的标准输出（已 trim）
- * @throws {ClawtError} 检测到 index.lock 错误时抛出中文友好提示
+ * @throws {ClawtError} 检测到 index.lock 错误且重试失败时抛出中文友好提示
  * @throws {Error} 其他命令执行失败时抛出
  */
 export function execCommandWithInput(command: string, args: string[], options: { input: Buffer; cwd?: string }): string {
   logger.debug(`执行命令(stdin): ${command} ${args.join(' ')}${options.cwd ? ` (cwd: ${options.cwd})` : ''}`);
-  try {
-    const result = execFileSync(command, args, {
-      cwd: options.cwd,
-      input: options.input,
-      encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      maxBuffer: EXEC_MAX_BUFFER,
-    });
-    return result.trim();
-  } catch (error) {
-    throwIfGitIndexLockError(error, options.cwd);
-    throw error;
+
+  let retryCount = 0;
+
+  while (true) {
+    try {
+      const result = execFileSync(command, args, {
+        cwd: options.cwd,
+        input: options.input,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        maxBuffer: EXEC_MAX_BUFFER,
+      });
+      return result.trim();
+    } catch (error) {
+      if (shouldRetryGitIndexLockError(error, retryCount)) {
+        retryCount++;
+        logger.debug(`检测到 index.lock 错误，第 ${retryCount} 次重试`);
+        waitForGitIndexLockRetrySync();
+        continue;
+      }
+
+      throwIfGitIndexLockError(error, options.cwd);
+      throw error;
+    }
   }
 }
 

package/tests/unit/utils/git-lock.test.ts

@@ -24,11 +24,19 @@ vi.mock('../../../src/errors/index.js', () => ({
 vi.mock('../../../src/constants/index.js', () => ({
   MESSAGES: {
     GIT_INDEX_LOCKED: (lockFilePath: string) => `Git index 被锁定，锁文件路径：${lockFilePath}`,
+    GIT_INDEX_LOCK_RETRYING: 'Git index 被锁定，正在重试...',
   },
 }));
 
 import { execSync } from 'node:child_process';
-import { isGitIndexLockError, findGitIndexLockPath, throwIfGitIndexLockError } from '../../../src/utils/git-lock.js';
+import {
+  isGitIndexLockError,
+  findGitIndexLockPath,
+  throwIfGitIndexLockError,
+  shouldRetryGitIndexLockError,
+  waitForGitIndexLockRetrySync,
+  extractFullErrorMessage,
+} from '../../../src/utils/git-lock.js';
 
 const mockedExecSync = vi.mocked(execSync);
 
@@ -159,3 +167,79 @@ describe('throwIfGitIndexLockError', () => {
     expect(() => throwIfGitIndexLockError(error)).not.toThrow();
   });
 });
+
+describe('extractFullErrorMessage', () => {
+  it('从 Error 对象提取 message', () => {
+    const error = new Error('test error');
+    expect(extractFullErrorMessage(error)).toBe('test error');
+  });
+
+  it('合并 message 和 stderr', () => {
+    const error = new Error('Command failed');
+    (error as any).stderr = 'fatal: Unable to write index.';
+    expect(extractFullErrorMessage(error)).toBe('Command failed\nfatal: Unable to write index.');
+  });
+
+  it('处理 Buffer 类型的 stderr', () => {
+    const error = new Error('Command failed');
+    (error as any).stderr = Buffer.from('fatal: Unable to write index.');
+    expect(extractFullErrorMessage(error)).toBe('Command failed\nfatal: Unable to write index.');
+  });
+
+  it('非 Error 对象返回 String 转换结果', () => {
+    expect(extractFullErrorMessage('string error')).toBe('string error');
+    expect(extractFullErrorMessage(123)).toBe('123');
+  });
+});
+
+describe('shouldRetryGitIndexLockError', () => {
+  it('index.lock 错误且未达到重试上限时返回 true', () => {
+    const error = new Error("fatal: Unable to create '/repo/.git/index.lock': File exists.");
+    expect(shouldRetryGitIndexLockError(error, 0)).toBe(true);
+  });
+
+  it('index.lock 错误但已达到重试上限时返回 false', () => {
+    const error = new Error("fatal: Unable to create '/repo/.git/index.lock': File exists.");
+    // MAX_RETRIES 默认为 1，所以 retryCount = 1 时不应再重试
+    expect(shouldRetryGitIndexLockError(error, 1)).toBe(false);
+  });
+
+  it('非 index.lock 错误返回 false', () => {
+    const error = new Error('Command failed: git merge feature');
+    expect(shouldRetryGitIndexLockError(error, 0)).toBe(false);
+  });
+
+  it('从 stderr 检测 index.lock 错误', () => {
+    const error = new Error('Command failed');
+    (error as any).stderr = "fatal: Unable to create '/repo/.git/index.lock': File exists.";
+    expect(shouldRetryGitIndexLockError(error, 0)).toBe(true);
+  });
+});
+
+describe('waitForGitIndexLockRetrySync', () => {
+  it('向 stderr 输出重试提示', () => {
+    const stderrWriteSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
+    // 执行函数（会有短暂延迟）
+    waitForGitIndexLockRetrySync();
+
+    // 验证输出了重试提示
+    expect(stderrWriteSpy).toHaveBeenCalledWith('Git index 被锁定，正在重试...\n');
+
+    stderrWriteSpy.mockRestore();
+  });
+
+  it('执行时间接近配置的延迟时间', () => {
+    const stderrWriteSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
+    const startTime = Date.now();
+    waitForGitIndexLockRetrySync();
+    const elapsed = Date.now() - startTime;
+
+    // 延迟时间应该接近 150ms（允许 50ms 误差）
+    expect(elapsed).toBeGreaterThanOrEqual(100);
+    expect(elapsed).toBeLessThanOrEqual(300);
+
+    stderrWriteSpy.mockRestore();
+  });
+});