clawt 3.9.4 → 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
@@ -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) {

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/package.json

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

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/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();
+  });
+});