@zhushanwen/pi-subagent-workflow 7.2.0 → 7.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "7.2.0",
+  "version": "7.3.1",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",

package/src/execution/__tests__/manifest-parentid.test.ts

@@ -0,0 +1,117 @@
+// ManifestStore — parentRecordId 落盘测试（M3a）。
+//
+// 验证 M3a 三条契约：
+// 1. 新 record 落盘含 parentRecordId（depth>=1 subagent 读回直接父 record id）
+// 2. 旧 manifest JSON（无 parentRecordId 字段）readManifest 仍有效（向后兼容）
+// 3. isValidManifest 校验不改（5 必填不变，parentRecordId optional）
+//
+// isValidManifest 私有未 export——通过 readManifest 等价验证：readManifest 内部
+// `isValidManifest(parsed) ? parsed : null`，非 null ⟺ 校验通过。不 export 私有函数
+// 避免扩大公共 API 表面（M3a C1 约束：不改 isValidManifest，仅 2 行代码改动）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ManifestStore, type ManifestRecord } from "../manifest-store.ts";
+
+/** 构造最小合法 ManifestRecord（5 必填），optional 字段按 overrides 传入。 */
+function makeBaseManifest(overrides: Partial<ManifestRecord> = {}): ManifestRecord {
+  return {
+    id: "rec-test",
+    rootSessionId: "session-main",
+    agentName: "worker",
+    status: "completed",
+    createdAt: 1000,
+    ...overrides,
+  };
+}
+
+describe("ManifestStore — parentRecordId 落盘 (M3a)", () => {
+  let tmpDir: string;
+  let store: ManifestStore;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "manifest-parentid-"));
+    store = new ManifestStore(tmpDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // ── TC-m3a-new-record-parentid ──
+  it("新 record 落盘含 parentRecordId（depth>=1 读回直接父 record id）", async () => {
+    const record = makeBaseManifest({
+      id: "rec-child",
+      parentRecordId: "sa-parent-1",
+    });
+    await store.writeManifest(record);
+
+    const readBack = await store.readManifest("rec-child");
+    expect(readBack).not.toBeNull();
+    expect(readBack?.parentRecordId).toBe("sa-parent-1");
+  });
+
+  it("顶层 record（parentRecordId 缺失）落盘读回仍 undefined", async () => {
+    // 顶层 subagent parentRecordId=undefined（父是 main，main 无 record）
+    const record = makeBaseManifest({ id: "rec-top" });
+    await store.writeManifest(record);
+
+    const readBack = await store.readManifest("rec-top");
+    expect(readBack).not.toBeNull();
+    expect(readBack?.parentRecordId).toBeUndefined();
+  });
+
+  // ── TC-m3a-old-manifest-compat ──
+  it("旧 manifest JSON（无 parentRecordId）readManifest 返有效（isValidManifest 通过）", async () => {
+    // 手写旧版本格式 manifest（无 parentRecordId 字段），模拟旧 subagent-workflow 写的磁盘文件
+    const oldManifest = {
+      id: "rec-old",
+      rootSessionId: "session-main",
+      agentName: "worker",
+      status: "completed",
+      createdAt: 2000,
+      // 无 parentRecordId —— 旧版本写的
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, "rec-old.json"),
+      JSON.stringify(oldManifest),
+      "utf-8",
+    );
+
+    const readBack = await store.readManifest("rec-old");
+    // readManifest 内 isValidManifest(parsed) ? parsed : null —— 非 null 即 5 必填校验通过
+    expect(readBack).not.toBeNull();
+    expect(readBack?.id).toBe("rec-old");
+    expect(readBack?.parentRecordId).toBeUndefined();
+  });
+
+  // ── TC-m3a-isvalidmanifest-unchanged ──
+  it("isValidManifest 不改：含/不含 parentRecordId 均通过（5 必填不变）", async () => {
+    // isValidManifest 私有，通过 readManifest 等价验证（非 null ⟺ 校验通过）。
+    // 含 parentRecordId —— 新格式
+    const withParent = makeBaseManifest({
+      id: "rec-with-parent",
+      parentRecordId: "sa-x",
+    });
+    await store.writeManifest(withParent);
+    expect(await store.readManifest("rec-with-parent")).not.toBeNull();
+
+    // 不含 parentRecordId —— 仅 5 必填（旧格式 / 顶层 record）
+    const minimal = {
+      id: "rec-minimal",
+      rootSessionId: "session-main",
+      agentName: "worker",
+      status: "completed",
+      createdAt: 3000,
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, "rec-minimal.json"),
+      JSON.stringify(minimal),
+      "utf-8",
+    );
+    expect(await store.readManifest("rec-minimal")).not.toBeNull();
+  });
+});

package/src/execution/__tests__/run-spawn-integration.test.ts

@@ -384,6 +384,24 @@ describe("runSpawn", () => {
       expect(result.error).toContain("spawn ENOENT");
       expect(record.lastError).toContain("spawn ENOENT");
     });
+
+    it("[worktree-reaper-fix] ENOENT error 消息拼 spawnCwd（避免误诊 node 被卸载）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: enoent-cwd", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // ENOENT 且带 code（Node spawn 失败的真实形态）——error handler 必须拼 spawnCwd
+      const err = Object.assign(new Error("spawn ENOENT"), { code: "ENOENT" });
+      child.emit("error", err);
+
+      const result = await promise;
+
+      expect(result.success).toBe(false);
+      // makeCtx().cwd = "/tmp/test"，无 worktree 时 spawnCwd = ctx.cwd
+      expect(record.lastError).toContain("/tmp/test");
+    });
   });
 
   // ── 7. identity 补写 ──

package/src/execution/__tests__/worktree-pid-registration.integration.test.ts

@@ -0,0 +1,225 @@
+// src/execution/__tests__/worktree-pid-registration.integration.test.ts
+//
+// [worktree-reaper-fix] 端到端集成测试：验证 worktree pid 注册链路（接线层）。
+//
+// 背景：2026-08-11 生产事故——reaper 误清活 worktree。根因：pid 补全代码唯一生产调用点
+// 挂在 session-runner 的 header 分支（RPC mode 永不触发），注册表 pid 恒为 0，超
+// SPAWN_GRACE_MS(60s) 后任意 session_start 触发的 scan() 必然误删活 worktree。
+// 修复：spawn() 返回后同步补 pid。
+//
+// 为什么用真实 spawn（而非现有 run-spawn-* 的 FakeChild mock）：
+//   现有测试全 mock registerPid（session-start-reaper/crash-recovery/index-session-start/
+//   stream-sink-guard），验证的是「mock 了补全回调后的 reaper 行为」，从未验证
+//   「真实调用链中补全回调是否被调用」——接线错误零检测能力（结构性盲区）。
+//   本测试走真实链路：真实 git repo + 真实 worktree 创建 + 真实 spawn node 子进程 +
+//   真实注册表文件，仅 mock ./pi-invocation.ts（把 pi 二进制替换为 node -e 脚本）。
+//
+// mock 最小化原则：
+//   - node:child_process 不 mock（真实 spawn / execFileSync git）
+//   - node:fs 不 mock（真实目录/文件：worktree checkout、注册表 JSON）
+//   - alive-store 不 mock（真实 process.kill(pid, 0) 探活）
+//   - 仅 vi.mock("./pi-invocation.ts")：getPiInvocation 返回 node -e 脚本
+//   - fake timers 仅 toFake: ["Date"]：推进注册表宽限判定用，不干扰真实 I/O 事件
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// vi.hoisted：vi.mock 工厂体内不能引用顶层 let/const（提升限制），脚本字符串必须放这。
+// scriptHolder 是可变对象：getPiInvocation 每次调用时读它（工厂函数体在运行时执行），
+// 用例内可切换长驻/短命脚本。
+const { scriptHolder, LONG_RUNNING_SCRIPT, SHORT_LIVED_SCRIPT } = vi.hoisted(() => {
+  const scriptHolder: { script: string } = { script: "process.exit(0)" };
+  return {
+    scriptHolder,
+    // 长驻脚本：90s 后退出（测试在 61s scan 时它必须还活着，验证「活 worktree 不被清」）
+    LONG_RUNNING_SCRIPT:
+      "setTimeout(() => process.exit(0), 90000);",
+    // 短命脚本：立即退出（模拟快速完成的子 agent，验证「真孤儿被回收」）
+    SHORT_LIVED_SCRIPT: "process.exit(0)",
+  };
+});
+
+vi.mock("./pi-invocation.ts", () => ({
+  getPiInvocation: (userArgs: string[]) => ({
+    command: process.execPath,
+    args: ["-e", scriptHolder.script, ...userArgs],
+  }),
+}));
+
+import { WorktreeManager } from "../worktree-manager.ts";
+import { WorktreeRegistry, SPAWN_GRACE_MS } from "../worktree-registry.ts";
+import { runSpawn } from "../session-runner.ts";
+import type { WorktreeHandle } from "../types.ts";
+import { makeCtx, makeOpts, makeRecord } from "./helpers/spawn-mock.ts";
+
+// ── 测试夹具：临时 git repo + 临时 agentDir（避免污染 ~/.pi/agent）──
+
+let tmpRoot: string;
+let repoDir: string;
+let agentDir: string;
+let wtm: WorktreeManager;
+let registry: WorktreeRegistry;
+let handle: WorktreeHandle | undefined;
+let spawnedPid: number | undefined;
+
+function git(args: string[], cwd: string): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
+/** 初始化临时 git repo（至少一个 commit，worktreeManager.create 需要 clean tree + HEAD）。 */
+function initRepo(): void {
+  repoDir = path.join(tmpRoot, "repo");
+  fs.mkdirSync(repoDir, { recursive: true });
+  git(["init", "-b", "main"], repoDir);
+  git(["config", "user.email", "test@test.local"], repoDir);
+  git(["config", "user.name", "test"], repoDir);
+  git(["commit", "--allow-empty", "-m", "init"], repoDir);
+}
+
+/** 从注册表文件读指定 branch 的条目（真实文件，轮询用）。 */
+function readEntry(branch: string): { pid: number; createdAt: number } | undefined {
+  return registry.load().find((e) => e.branch === branch);
+}
+
+/** 轮询注册表直到 pid 补全（真实 fs 读 + 真实 setTimeout 轮询）。 */
+async function waitForPid(branch: string, timeoutMs = 5000): Promise<number> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const entry = readEntry(branch);
+    if (entry && entry.pid !== 0) return entry.pid;
+    await new Promise((r) => setTimeout(r, 20));
+  }
+  throw new Error(`pid not registered within ${timeoutMs}ms (branch=${branch})`);
+}
+
+/** 清理：kill 子进程 + worktree cleanup + 删除临时目录。 */
+function cleanup(): void {
+  if (spawnedPid) {
+    try {
+      process.kill(spawnedPid, "SIGKILL");
+    } catch {
+      // 已退出
+    }
+    spawnedPid = undefined;
+  }
+  if (handle) {
+    try {
+      wtm.cleanup(handle);
+    } catch (err) {
+      // best-effort：git worktree remove 失败不阻断测试清理
+      // eslint-disable-next-line no-console
+      console.warn("worktree cleanup failed in test teardown", err);
+    }
+    handle = undefined;
+  }
+  try {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "wt-reaper-it-"));
+  agentDir = path.join(tmpRoot, "agent");
+  initRepo();
+  wtm = new WorktreeManager(agentDir);
+  registry = new WorktreeRegistry(agentDir);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  cleanup();
+});
+
+// ── 用例 ──
+
+describe("worktree pid 注册链路（真实 spawn 集成）", () => {
+  it("正向：spawn 返回后注册表 pid 同步补全，活 worktree 超宽限不被 scan 误清", async () => {
+    // 0. 长驻脚本（子进程 90s 内不退出，模拟长跑子 agent）
+    scriptHolder.script = LONG_RUNNING_SCRIPT;    // 1. 真实创建 worktree（pid=0 占位）
+    handle = wtm.create(repoDir, "rec-1");
+    expect(readEntry(handle.branch)).toMatchObject({ pid: 0 });
+
+    // 2. runSpawn 挂后台（不 await——长驻子进程 close 不触发，await 会挂死），
+    //    ctx.onWorktreePid 接真实 registerPid（模拟 subagent-service 接线）
+    const ctx = makeCtx({
+      agentDir,
+      cwd: repoDir,
+      mainCwd: repoDir,
+      rootCwd: repoDir,
+      onWorktreePid: (branch: string, pid: number) => wtm.registerPid(branch, pid),
+    });
+    const runPromise = runSpawn(
+      makeRecord(),
+      "test task",
+      makeOpts({ worktree: handle }),
+      ctx,
+    );
+
+    // 3. 断言 spawn 后 pid 已补全（真实注册表文件轮询）——修复前此步超时红
+    spawnedPid = await waitForPid(handle.branch);
+    expect(spawnedPid).toBeGreaterThan(0);
+
+    // 4. 推进时钟超 SPAWN_GRACE_MS（仅 fake Date，不干扰真实 I/O）
+    vi.useFakeTimers({ toFake: ["Date"] });
+    vi.setSystemTime(Date.now() + SPAWN_GRACE_MS + 1000);
+
+    // 5. scan()：活 worktree 必须不被清（修复前：pid=0 超宽限 → 误删 → 红）
+    wtm.scan();
+    expect(fs.existsSync(handle.path)).toBe(true);
+
+    // 6. 收尾：真实时钟恢复 + kill 子进程让 runPromise settle
+    vi.useRealTimers();
+    try {
+      process.kill(spawnedPid, "SIGTERM");
+    } catch {
+      // 已退出
+    }
+    await runPromise;
+
+    // 7. 反向：进程死后 scan 回收真孤儿
+    wtm.scan();
+    expect(fs.existsSync(handle.path)).toBe(false);
+    const entryAfter = readEntry(handle.branch);
+    expect(entryAfter).toBeUndefined();
+  }, 15000);
+
+  it("反向：短命子进程退出后，pid>0 且进程死 → scan 立即回收", async () => {
+    // 0. 短命脚本（子进程立即退出，模拟快速完成的子 agent）
+    scriptHolder.script = SHORT_LIVED_SCRIPT;
+    // 1. 真实创建 worktree
+    handle = wtm.create(repoDir, "rec-2");
+
+    // 2. 短命脚本子进程：spawn 后同步补 pid（修复前 pid=0，且未超宽限 → 不回收 → 红）
+    const ctx = makeCtx({
+      agentDir,
+      cwd: repoDir,
+      mainCwd: repoDir,
+      rootCwd: repoDir,
+      onWorktreePid: (branch: string, pid: number) => wtm.registerPid(branch, pid),
+    });
+    const result = await runSpawn(
+      makeRecord(),
+      "test task",
+      makeOpts({ worktree: handle }),
+      ctx,
+    );
+    expect(result.status).not.toBe("error"); // 进程正常退出（exit 0），非 spawn 失败
+
+    // 3. pid 已补全（短命进程退出后 pid 仍有效，registerPid 同步执行不受退出影响）
+    const entry = readEntry(handle.branch);
+    expect(entry).toBeDefined();
+    expect(entry!.pid).toBeGreaterThan(0);
+    spawnedPid = entry!.pid;
+
+    // 4. scan：pid>0 且进程死 → 立即判孤儿回收（无需等宽限）
+    wtm.scan();
+    expect(fs.existsSync(handle.path)).toBe(false);
+    expect(readEntry(handle.branch)).toBeUndefined();
+  }, 15000);
+});

package/src/execution/finalize-record.ts

@@ -144,6 +144,7 @@ export async function doFinalizeRecord(
     await deps.manifestStore.writeManifest({
       id: record.id,
       rootSessionId: record.rootSessionId ?? "",
+      parentRecordId: record.parentRecordId,
       agentName: record.agent,
       status: status === "done" ? "completed" : status,
       createdAt: record.startedAt,

package/src/execution/manifest-store.ts

@@ -7,6 +7,8 @@ import { bestEffort } from "./best-effort.ts";
 export interface ManifestRecord {
   id: string;
   rootSessionId: string;
+  /** 直接父 subagent record ID（层级树构建用）。顶层 record 缺失（undefined）。M3a 补字段。 */
+  parentRecordId?: string;
   agentName: string;
   /**
    * 终态枚举：finalizeRecord 写 running/completed/failed/cancelled 四态；cancelled 不再
@@ -25,6 +27,9 @@ export interface ManifestRecord {
   model?: string;
 }
 
+/** JSON.stringify 缩进空格数（no-magic-numbers 合规）。 */
+const MANIFEST_INDENT_SPACES = 2;
+
 /** 合法 manifest status 集合（4 态；运行时守卫用，磁盘文件可能陈旧/损坏）。crashed 不在其中。 */
 const VALID_MANIFEST_STATUSES: ReadonlySet<string> = new Set([
   "running",
@@ -69,7 +74,7 @@ export class ManifestStore {
   async writeManifest(record: ManifestRecord): Promise<void> {
     const filePath = path.join(this.dir, `${record.id}.json`);
     const tmpPath = `${filePath}.tmp.${process.pid}`;
-    const content = JSON.stringify(record, null, 2);
+    const content = JSON.stringify(record, null, MANIFEST_INDENT_SPACES);
 
     let renamed = false;
     try {

package/src/execution/session-runner.ts

@@ -723,6 +723,14 @@ export async function runSpawn(
       env: childEnv,
     });
     proc = child;
+    // [worktree-reaper-fix] 同步补全注册表 pid：spawn 返回后 child.pid 立即可得（Node.js
+    // 同步属性），无需等任何 stdout 事件。原补全点挂在 header 分支（下方 stdout handler 内），
+    // 而 RPC mode（buildSpawnArgs 固定 --mode rpc）不输出 header 行——pid 恒为 0，超
+    // SPAWN_GRACE_MS 后被 reaper 当孤儿误删活 worktree（2026-08-11 cw 递归编排整树失活事故）。
+    // header 分支调用保留：json mode 回切时仍能补全，updatePid 同 branch 覆盖写幂等，无副作用。
+    if (opts.worktree && child.pid) {
+      ctx.onWorktreePid?.(opts.worktree.branch, child.pid);
+    }
     // [C1] track 子进程供 dispose 兜底 kill（sync + background 均注册——sync 无 controller，
     // abortRunningControllers 跳过它，靠本 Set 兜底）。close/error 后移除（已退出无需再 kill）。
     spawnedChildren.add(child);
@@ -957,8 +965,13 @@ export async function runSpawn(
       });
       child.on("error", (err: Error) => {
         // spawn 本身失败（command not found 等）
+        // [worktree-reaper-fix] 拼 spawnCwd 进错误消息：ENOENT 的 err.message 只含 command 名，
+        // 无 cwd 线索（worktree 被 reaper 误删后 cwd 指向虚空）会导致误诊——2026-08-11 事故
+        // AI 误判"node 被卸载"的直接原因。
         spawnedChildren.delete(child);
-        record.lastError = err.message;
+        const errno = err as NodeJS.ErrnoException;
+        const cwdHint = errno.code === "ENOENT" ? ` (cwd: ${spawnCwd})` : "";
+        record.lastError = `${err.message}${cwdHint}`;
         resolve(SIGNAL_EXIT_CODE_THRESHOLD); // 非零退出
       });
     });

package/src/execution/worktree-manager.ts

@@ -24,9 +24,12 @@ import { encodeCwd } from "./path-encoding.ts";
 import type { PatchResult,WorktreeHandle } from "./types.ts";
 import { DirtyWorktreeError } from "./types.ts";
 import { bestEffort } from "./best-effort.ts";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { isProcessAlive } from "./alive-store.ts";
 import { SPAWN_GRACE_MS,type WorktreeEntry,WorktreeRegistry } from "./worktree-registry.ts";
 
+const logger = getLogger("subagents");
+
 // recordId 白名单：字母数字下划线短横线
 const SAFE_ID_RE = /^[\w-]+$/;
 
@@ -80,7 +83,7 @@ export class WorktreeManager {
       cwd: mainCwd,
     });
 
-    // 注册到全局表（pid=0 占位）。session-runner first header 时补 pid。
+    // 注册到全局表（pid=0 占位）。runSpawn 在 spawn() 返回后同步补 pid。
     // 放在 worktree add 成功后、symlink 前——确保只有真正创建了 worktree 才登记。
     this.registry.add({
       repo: mainCwd,
@@ -124,8 +127,8 @@ export class WorktreeManager {
   }
 
   /**
-   * 注册子进程 pid（session-runner first header 时调）。
-   * create 时 pid 未知写 0 占位，子进程 spawn 拿到 pid 后由此补全。
+   * 注册子进程 pid（runSpawn spawn() 返回后同步调）。
+   * create 时 pid 未知写 0 占位，子进程 spawn 返回后（child.pid 同步可得）由此补全。
    * reaper 据 pid 死活判孤儿，pid=0 条目用 SPAWN_GRACE 宽限。
    */
   registerPid(branch: string, pid: number): void {
@@ -227,7 +230,17 @@ export class WorktreeManager {
   private isOrphan(entry: WorktreeEntry, now: number): boolean {
     if (entry.pid === 0) {
       // create→spawn 窗口：超过宽限期仍未补 pid = create 后崩溃
-      return now - entry.createdAt > SPAWN_GRACE_MS;
+      const expired = now - entry.createdAt > SPAWN_GRACE_MS;
+      if (expired) {
+        // [worktree-reaper-fix] pid=0 超宽限 = create 后 spawn 前崩溃（或补全链路再次断链）。
+        // 正常路径 spawn 返回后 pid 已同步补全，此处不应命中活 worktree；命中即诊断信号，
+        // 与 updatePid 写盘失败的 warn 日志呼应（补全失败可观测闭环）。
+        logger.warn(
+          "[worktree] orphan reaper: pid=0 entry exceeded SPAWN_GRACE_MS, treating as orphan",
+          { branch: entry.branch, checkout: entry.checkout, createdAt: entry.createdAt, now },
+        );
+      }
+      return expired;
     }
     return !isProcessAlive(entry.pid);
   }

package/src/execution/worktree-registry.ts

@@ -21,6 +21,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { bestEffort } from "./best-effort.ts";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("subagents");
 
 /** create→spawn 宽限期（ms）：pid=0 条目超过此阈值判 create 后崩溃。 */
 export const SPAWN_GRACE_MS = 60_000;
@@ -84,7 +87,7 @@ export class WorktreeRegistry {
   }
 
   /**
-   * 更新 pid（session-runner first header 时调）。
+   * 更新 pid（runSpawn spawn() 返回后同步调）。
    * branch 不存在则忽略（create 后崩溃 + reaper 已清的竞态）。
    */
   updatePid(branch: string, pid: number): void {
@@ -92,7 +95,7 @@ export class WorktreeRegistry {
     const idx = entries.findIndex((e) => e.branch === branch);
     if (idx >= 0) {
       entries[idx] = { ...entries[idx], pid };
-      this.save(entries);
+      this.save(entries, { branch, pid });
     }
   }
 
@@ -130,8 +133,9 @@ export class WorktreeRegistry {
    * 原子写入全部条目。
    * best-effort：写入失败不阻断主流程（create/cleanup 的 git 操作已执行，
    * 注册表与 git 状态的短暂不一致靠下次 reaper 对账收敛）。
+   * 写盘失败时 warn 日志（updatePid 路径带 branch/pid，补全失败可观测闭环）。
    */
-  private save(entries: WorktreeEntry[]): void {
+  private save(entries: WorktreeEntry[], context?: { branch: string; pid: number }): void {
     try {
       fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
       const tmp = `${this.filePath}.tmp`;
@@ -139,6 +143,12 @@ export class WorktreeRegistry {
       fs.renameSync(tmp, this.filePath);
     } catch (err) {
       bestEffort(err, "worktree registry save");
+      // [worktree-reaper-fix] 补全写盘失败静默吞错时，条目 pid 恒 0、60s 后被 reaper 误删
+      // 活 worktree 且无诊断线索。此 warn 与 reaper scan 的 pid=0 warn 呼应，形成闭环。
+      logger.warn(
+        "[worktree] registry save failed; pid may stay 0 and be reaped by orphan reaper",
+        { ...(context ?? {}), err: err instanceof Error ? err.message : String(err) },
+      );
     }
   }
 }