@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/execution/worktree-manager.ts

@@ -3,7 +3,9 @@
 // git worktree 生命周期管理：创建、清理、patch 回传、孤儿 reaper。
 //
 // 设计约束：
-//   - gitRun 是唯一 git 命令出口，统一超时/错误包装
+//   - gitRunAsync 是唯一 git 命令出口，统一超时/错误包装（旧同步 gitRun 已在 phase 2 删除）
+//   - gitRunAsync 输出保真（不 trim）：diff stdout 直接落盘为 patch，裁掉尾换行会让
+//     `git apply` 报 corrupt patch；需要干净文本的消费点（baseCommit/status 拼接）自行 trim
 //   - recordId 白名单 `^[\w-]+$` 防止路径注入
 //   - clean tree 前置校验防止创建脏 worktree
 //   - checkout 放 os.tmpdir()（脱离 .git/），兼容普通 repo 与 bare+worktree 结构
@@ -15,7 +17,7 @@
 // WorktreeRegistry（<agentDir>/subagents/worktrees.json）。判据从终态 marker
 // 状态机降为 pid 死活一条——进程崩溃无人写终态时也能正确回收。
 
-import { execFileSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -36,9 +38,47 @@ const SAFE_ID_RE = /^[\w-]+$/;
 // 默认 git 命令超时（ms）
 const GIT_TIMEOUT_MS = 30_000;
 
+/**
+ * gitRunAsync 的包装错误：message 格式与旧同步 gitRun 逐字一致（下游
+ * DirtyWorktreeError 判定与测试 toThrow 匹配零改动）；exitCode/stderr/timedOut
+ * 为新增诊断属性（探针 P-errshape 实测 Node 24：execFile 的 err.stderr 为
+ * undefined——stderr 在 callback 第三参；退出码在 err.code（数字））。
+ */
+export class GitRunError extends Error {
+  readonly exitCode?: number;
+  readonly stderr?: string;
+  readonly timedOut?: boolean;
+
+  constructor(
+    message: string,
+    props: { exitCode?: number; stderr?: string; timedOut?: boolean },
+  ) {
+    super(message);
+    this.name = "GitRunError";
+    this.exitCode = props.exitCode;
+    this.stderr = props.stderr;
+    this.timedOut = props.timedOut;
+  }
+}
+
+/**
+ * 写类 git 命令判定（per-repo mutex 串行对象）。读类（status/rev-parse/diff）
+ * 无副作用不加锁——并发读 git 自身安全，P-lock 实测冲突仅是写窗口假设。
+ */
+function isWriteCommand(args: string[]): boolean {
+  if (args[0] === "worktree") return args[1] === "add" || args[1] === "remove";
+  if (args[0] === "branch") return args[1] === "-D";
+  return args[0] === "add";
+}
+
 export class WorktreeManager {
   // 全局注册表：跨 repo 记录所有活 worktree，reaper 遍历此表判孤儿。
   private readonly registry: WorktreeRegistry;
+  // per-repo 写命令串行队列：value = 队尾（已吞 rejection 的）Promise。
+  // 入队形态 prev.catch(()=>{}).then(run)——后继只关心「自己已排队」，
+  // 不继承前驱错误（否则 1 个 worktree add 失败会传染同 repo 后续全部写命令，
+  // 替代旧同步版单线程天然全局串行的「各命令独立失败」语义）。
+  private readonly writeQueues = new Map<string, Promise<void>>();
 
   constructor(agentDir: string) {
     this.registry = new WorktreeRegistry(agentDir);
@@ -51,16 +91,33 @@ export class WorktreeManager {
    * @param recordId 执行记录 ID（必须匹配 `^[\w-]+$`）
    * @returns 冻结的 WorktreeHandle
    */
-  create(mainCwd: string, recordId: string): WorktreeHandle {
+  async create(mainCwd: string, recordId: string): Promise<WorktreeHandle> {
     if (!SAFE_ID_RE.test(recordId)) {
       throw new DirtyWorktreeError(
         `recordId contains unsafe characters: "${recordId}" (must match ^[\\w-]+$)`,
       );
     }
 
-    this.assertCleanTree(mainCwd);
+    // 脏树校验与 base commit 并行（读类无锁可并发）。allSettled 而非 all：
+    // status 先 reject 时 all 会短路，rev-parse 的后续 rejection 无人处理 →
+    // unhandledRejection。判定顺序固定：status 错误 → 脏树 → rev-parse 错误
+    // （脏树语义不变：仍先于 worktree add，rev-parse 结果在脏树时被丢弃）。
+    const [statusR, revR] = await Promise.allSettled([
+      this.gitRunAsync(["status", "--porcelain"], { cwd: mainCwd }),
+      this.gitRunAsync(["rev-parse", "HEAD"], { cwd: mainCwd }),
+    ]);
+    if (statusR.status === "rejected") throw statusR.reason;
+    // 消费点自行 trim：gitRunAsync 返回原始 stdout（保真），status 输出以 \n 结尾
+    const statusText = statusR.value.trim();
+    if (statusText.length > 0) {
+      throw new DirtyWorktreeError(
+        `Working tree is dirty in ${mainCwd}:\n${statusText}`,
+      );
+    }
+    if (revR.status === "rejected") throw revR.reason;
+    // 消费点自行 trim：rev-parse 输出 "hash\n"，不 trim 会把换行带进后续 git args
+    const baseCommit = revR.value.trim();
 
-    const baseCommit = this.gitRun(["rev-parse", "HEAD"], { cwd: mainCwd });
     const branch = `pi-sub-${recordId}`;
     // checkout 放 tmpdir，脱离 .git/ 目录结构。
     // 这样 git 自行把元数据注册到 <commonDir>/worktrees/<branch>/，
@@ -79,7 +136,7 @@ export class WorktreeManager {
       }
     }
 
-    this.gitRun(["worktree", "add", "-b", branch, worktreePath, "HEAD"], {
+    await this.gitRunAsync(["worktree", "add", "-b", branch, worktreePath, "HEAD"], {
       cwd: mainCwd,
     });
 
@@ -112,12 +169,12 @@ export class WorktreeManager {
     } catch (err) {
       // 回滚已创建的 worktree+分支+注册表条目，best-effort 吞清理异常（原始 err 仍外抛）
       try {
-        this.gitRun(["worktree", "remove", "--force", worktreePath], { cwd: mainCwd });
+        await this.gitRunAsync(["worktree", "remove", "--force", worktreePath], { cwd: mainCwd });
       } catch (cleanErr) {
         bestEffort(cleanErr, "worktree remove (create rollback MF#3)");
       }
       try {
-        this.gitRun(["branch", "-D", branch], { cwd: mainCwd });
+        await this.gitRunAsync(["branch", "-D", branch], { cwd: mainCwd });
       } catch (cleanErr) {
         bestEffort(cleanErr, "branch delete (create rollback MF#3)");
       }
@@ -130,9 +187,10 @@ export class WorktreeManager {
    * 注册子进程 pid（runSpawn spawn() 返回后同步调）。
    * create 时 pid 未知写 0 占位，子进程 spawn 返回后（child.pid 同步可得）由此补全。
    * reaper 据 pid 死活判孤儿，pid=0 条目用 SPAWN_GRACE 宽限。
+   * sessionFile 可选补全：传入时填入 registry entry（reaper 据 pid 死活判孤儿，不读本字段；保留供诊断）。
    */
-  registerPid(branch: string, pid: number): void {
-    this.registry.updatePid(branch, pid);
+  registerPid(branch: string, pid: number, sessionFile?: string): void {
+    this.registry.updatePid(branch, pid, sessionFile);
   }
 
   /**
@@ -142,9 +200,9 @@ export class WorktreeManager {
    *
    * @param handle 要清理的 worktree handle（含 mainCwd，不靠路径反推）
    */
-  cleanup(handle: WorktreeHandle): void {
+  async cleanup(handle: WorktreeHandle): Promise<void> {
     try {
-      this.gitRun(["worktree", "remove", "--force", handle.path], {
+      await this.gitRunAsync(["worktree", "remove", "--force", handle.path], {
         cwd: handle.mainCwd,
       });
     } catch (err) {
@@ -152,7 +210,7 @@ export class WorktreeManager {
     }
 
     try {
-      this.gitRun(["branch", "-D", handle.branch], {
+      await this.gitRunAsync(["branch", "-D", handle.branch], {
         cwd: handle.mainCwd,
       });
     } catch (err) {
@@ -176,15 +234,15 @@ export class WorktreeManager {
    *   written=true 仅当 diff 非空且写盘成功；空 diff 或写失败均 written=false，
    *   调用方据此回填 record.patchFile，避免悬空路径（`git apply` 不存在的文件）。
    */
-  collectPatch(handle: WorktreeHandle, patchFile: string): PatchResult {
+  async collectPatch(handle: WorktreeHandle, patchFile: string): Promise<PatchResult> {
     // git add -A：暂存全部改动（含未跟踪新文件），使后续 --cached diff 能捕获新建文件
     try {
-      this.gitRun(["add", "-A"], { cwd: handle.path });
+      await this.gitRunAsync(["add", "-A"], { cwd: handle.path });
     } catch (err) {
       // add 失败不致命：继续尝试 diff，最差得到部分 diff（仅已跟踪文件的改动）
       bestEffort(err, "git add -A (collectPatch)");
     }
-    const diff = this.gitRun(
+    const diff = await this.gitRunAsync(
       ["diff", "--cached", handle.baseCommit],
       { cwd: handle.path },
     );
@@ -214,19 +272,22 @@ export class WorktreeManager {
    *   pid == 0 且超 SPAWN_GRACE_MS      → 孤儿（create 后崩溃，pid 永未补全）
    *   pid == 0 且未超宽限               → 跳过（可能正在 spawn）
    */
-  scan(): void {
+  async scan(): Promise<void> {
     const entries = this.registry.load();
     const now = Date.now();
 
+    // 逐孤儿串行 await（保持 for 循环串行语义，防止一次 reaper 打出 N 个并发 git）
     for (const entry of entries) {
       if (!this.isOrphan(entry, now)) {
         continue;
       }
-      this.cleanupOrphan(entry);
+      await this.cleanupOrphan(entry);
     }
   }
 
-  /** pid 死活判孤儿。pid=0 走 SPAWN_GRACE 宽限。 */
+  /**
+   * 判孤儿：pid 死活为主判据。pid=0 走 SPAWN_GRACE 宽限（create→spawn 窗口）。
+   */
   private isOrphan(entry: WorktreeEntry, now: number): boolean {
     if (entry.pid === 0) {
       // create→spawn 窗口：超过宽限期仍未补 pid = create 后崩溃
@@ -246,14 +307,14 @@ export class WorktreeManager {
   }
 
   /** 清理单个孤儿条目：worktree remove + branch -D + 注册表移除，三步各自 best-effort。 */
-  private cleanupOrphan(entry: WorktreeEntry): void {
+  private async cleanupOrphan(entry: WorktreeEntry): Promise<void> {
     try {
-      this.gitRun(["worktree", "remove", "--force", entry.checkout], { cwd: entry.repo });
+      await this.gitRunAsync(["worktree", "remove", "--force", entry.checkout], { cwd: entry.repo });
     } catch (err) {
       bestEffort(err, "worktree remove (orphan reaper)");
     }
     try {
-      this.gitRun(["branch", "-D", entry.branch], { cwd: entry.repo });
+      await this.gitRunAsync(["branch", "-D", entry.branch], { cwd: entry.repo });
     } catch (err) {
       bestEffort(err, "branch delete (orphan reaper)");
     }
@@ -265,34 +326,52 @@ export class WorktreeManager {
   // ============================================================
 
   /**
-   * git 命令执行器。统一超时 + 错误包装。
+   * git 命令异步执行器。与 gitRun 同一超时/错误包装约定（message 格式逐字一致），
+   * 差异仅在错误属性形态（GitRunError 挂 exitCode/stderr/timedOut）。
+   * 写类命令经 per-repo mutex 串行（不依赖 git 锁实现细节 + 并发限流 + 行为确定性）。
+   *
+   * stdout 保真返回（不 trim）：collectPatch 把 diff 输出原样落盘为 patch 文件，
+   * 裁掉尾换行会产出 `git apply` 拒绝的 corrupt patch（2026-08-16 门 4 实测）。
+   * 需要干净文本的消费点（baseCommit / 脏树 status 拼接）自行 trim。
    */
-  private gitRun(args: string[], opts: { cwd: string; timeout?: number }): string {
-    try {
-      return execFileSync("git", args, {
-        cwd: opts.cwd,
-        timeout: opts.timeout ?? GIT_TIMEOUT_MS,
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"],
-      }).trim();
-    } catch (err: unknown) {
-      if (err instanceof Error) {
-        throw new Error(`git ${args[0]} failed: ${err.message}`);
-      }
-      throw new Error(`git ${args[0]} failed: unknown error`);
-    }
-  }
+  private async gitRunAsync(args: string[], opts: { cwd: string; timeout?: number }): Promise<string> {
+    const run = (): Promise<string> =>
+      new Promise((resolve, reject) => {
+        execFile(
+          "git",
+          args,
+          { cwd: opts.cwd, timeout: opts.timeout ?? GIT_TIMEOUT_MS, encoding: "utf-8" },
+          (err, stdout, stderr) => {
+            if (err) {
+              const execErr = err as Error & { code?: unknown; killed?: boolean; signal?: string };
+              reject(
+                new GitRunError(`git ${args[0]} failed: ${execErr.message}`, {
+                  // P-errshape 实测：execFile 退出码在 err.code（数字时）；超时 killed+SIGTERM
+                  exitCode: typeof execErr.code === "number" ? execErr.code : undefined,
+                  stderr: typeof stderr === "string" ? stderr : undefined,
+                  timedOut: execErr.killed === true && execErr.signal === "SIGTERM",
+                }),
+              );
+              return;
+            }
+            resolve(stdout);
+          },
+        );
+      });
 
-  /**
-   * 校验工作目录是 clean tree。
-   */
-  private assertCleanTree(cwd: string): void {
-    const status = this.gitRun(["status", "--porcelain"], { cwd });
-    if (status.length > 0) {
-      throw new DirtyWorktreeError(
-        `Working tree is dirty in ${cwd}:\n${status}`,
-      );
-    }
+    if (!isWriteCommand(args)) return run();
+    // per-repo 队列：吞前驱 rejection 后接续本命令；队尾比对自清理防 Map 泄漏
+    const repo = opts.cwd;
+    const prev = this.writeQueues.get(repo) ?? Promise.resolve();
+    const next = prev.catch(() => {}).then(run);
+    const tail: Promise<void> = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.writeQueues.set(repo, tail);
+    void tail.finally(() => {
+      if (this.writeQueues.get(repo) === tail) this.writeQueues.delete(repo);
+    });
+    return next;
   }
-
 }

package/src/execution/worktree-registry.ts

@@ -56,6 +56,12 @@ export interface WorktreeEntry {
   readonly pid: number;
   /** 创建时间戳（ms，SPAWN_GRACE 判据 + 调试用）。 */
   readonly createdAt: number;
+  /**
+   * 对应 subagent session jsonl 文件全路径（诊断/兼容字段，reaper 据 pid 死活判孤儿）。
+   * session-runner first header 拿到 pid 时补全（create 时 record.sessionFile 尚未确定）。
+   * 可选：旧 worktrees.json / 非 worktree 模式无此字段，向后兼容（undefined 时 reaper 走原 pid 判据）。
+   */
+  readonly sessionFile?: string;
 }
 
 /**
@@ -89,12 +95,17 @@ export class WorktreeRegistry {
   /**
    * 更新 pid（runSpawn spawn() 返回后同步调）。
    * branch 不存在则忽略（create 后崩溃 + reaper 已清的竞态）。
+   * sessionFile 可选补全：传入时填入 entry（reaper 据 pid 死活判孤儿，不读本字段）。
    */
-  updatePid(branch: string, pid: number): void {
+  updatePid(branch: string, pid: number, sessionFile?: string): void {
     const entries = this.load();
     const idx = entries.findIndex((e) => e.branch === branch);
     if (idx >= 0) {
-      entries[idx] = { ...entries[idx], pid };
+      entries[idx] = {
+        ...entries[idx],
+        pid,
+        ...(sessionFile !== undefined ? { sessionFile } : {}),
+      };
       this.save(entries, { branch, pid });
     }
   }