@zhushanwen/pi-subagent-workflow 7.3.0 → 7.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "7.3.0",
+  "version": "7.3.2",
   "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__/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__/spawn-worktree-guidance.test.ts

@@ -0,0 +1,206 @@
+// src/execution/__tests__/spawn-worktree-guidance.test.ts
+//
+// worktree 模式认知纠正提示注入测试。
+//
+// 背景：worktree checkout 放 os.tmpdir()（路径形似临时沙箱），子 agent 无 worktree 语义
+// 提示时误判 cwd 为"空隔离目录"，主动 cd 别处放弃隔离（wave-agent 事故 session 019ff64c）。
+// 修复在 runSpawn 的 appendParts 注入 WORKTREE_GUIDANCE_PROMPT。
+//
+// 验证：
+//   - worktree 模式（opts.worktree 传入）→ appendSystemPrompt content 含 WORKTREE_GUIDANCE_PROMPT
+//   - 非 worktree 模式 → content 不含 worktree 提示
+//
+// 测试策略：mock writePromptToTempFile 捕获拼接后的 appendParts content（vi.hoisted 防
+// vi.mock hoisting 引用未初始化变量），断言含/不含 worktree 提示标识。
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// 捕获 writePromptToTempFile 的 content 参数（appendParts.join("\n\n")）。
+// vi.hoisted 保证变量在 vi.mock factory hoisting 前已声明可用。
+const captured = vi.hoisted(() => ({ content: "" }));
+
+// ── mock modules（与 session-runner-schema-env.test.ts 同模式）──
+
+vi.mock("node:child_process", async () => {
+  const { EventEmitter } = await import("node:events");
+  const { PassThrough } = await import("node:stream");
+
+  class FakeChild extends EventEmitter {
+    pid = 12345;
+    stdout = new PassThrough();
+    stderr = new PassThrough();
+    killed = false;
+    killSignal: string | undefined;
+    kill(sig?: string): boolean {
+      this.killed = true;
+      this.killSignal = sig;
+      return true;
+    }
+  }
+
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    execFileSync: vi.fn(() => ""),
+  };
+});
+
+vi.mock("node:fs", async () => {
+  const actual = await import("node:fs");
+  return {
+    default: {
+      ...actual,
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      appendFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+    },
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    promises: actual.promises,
+  };
+});
+
+vi.mock("../alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+}));
+
+vi.mock("../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string, content: string) => {
+    captured.content = content;
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { spawn } from "node:child_process";
+
+import { createRecord } from "../execution-record.ts";
+import { runSpawn, type RunOptions, type SessionRunnerContext } from "../session-runner.ts";
+
+const mockSpawn = vi.mocked(spawn);
+
+interface FakeChild {
+  pid: number;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  killed: boolean;
+  killSignal: string | undefined;
+  kill(sig?: string): boolean;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+function getLastSpawnedChild(): FakeChild {
+  const result = mockSpawn.mock.results.at(-1);
+  if (!result) throw new Error("spawn was not called yet");
+  return result.value as FakeChild;
+}
+
+async function waitForSpawn(timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (mockSpawn.mock.results.length === 0) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`spawn was not called within ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+function makeRecord() {
+  return createRecord("wt-guidance-1", {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "sync",
+    task: "test task",
+    startedAt: Date.now(),
+    rootSessionId: "s1",
+    parentRecordId: undefined,
+    depth: 0,
+  });
+}
+
+function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+  return {
+    resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
+    agentConfig: undefined,
+    appendSystemPrompt: undefined,
+    skillPath: undefined,
+    schema: undefined,
+    maxTurns: undefined,
+    graceTurns: undefined,
+    signal: undefined,
+    onEvent: undefined,
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+  return {
+    cwd: "/fake/cwd",
+    agentDir: "/fake/agent",
+    skillDirs: [],
+    mainCwd: "/fake/cwd",
+    sessionRootId: "root-session-test",
+    rootCwd: "/fake/cwd",
+    ...overrides,
+  };
+}
+
+describe("worktree guidance prompt injection", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    captured.content = "";
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("worktree 模式 → appendSystemPrompt content 含 worktree 认知纠正提示", async () => {
+    const record = makeRecord();
+    const opts = makeRunOpts({
+      worktree: {
+        path: "/tmp/pi-subagents/--fake--/pi-sub-sa-wt-guidance-1",
+        branch: "pi-sub-sa-wt-guidance-1",
+        baseCommit: "abc123",
+        mainCwd: "/fake/cwd",
+      },
+    });
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+
+    // content 含 WORKTREE_GUIDANCE_PROMPT 的标题
+    expect(captured.content).toContain("Git Worktree");
+    // 含关键纠正信息：cwd 含完整项目代码（非临时沙箱）
+    expect(captured.content).toContain("complete project source code");
+    // 含防 cd 别处的行为指引
+    expect(captured.content).toContain("Do NOT");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("非 worktree 模式 → content 不含 worktree 认知提示", async () => {
+    const record = makeRecord();
+    const opts = makeRunOpts(); // 不传 worktree
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+
+    expect(captured.content).not.toContain("Git Worktree");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+});

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/session-runner.ts

@@ -174,6 +174,30 @@ The \`ask_user\` tool is available in this session. When you call \`ask_user\`,
 - Use ask_user only when you genuinely cannot resolve ambiguity yourself (see tool description for guidelines)
 `.trim();
 
+/**
+ * worktree 模式注入子 agent 的认知纠正提示。
+ *
+ * 背景：worktree checkout 放在 os.tmpdir()（如 `/private/var/folders/.../pi-subagents/.../pi-sub-<id>`），
+ * 路径形似临时沙箱。子 agent system prompt 无任何 worktree 语义说明时，会误判 cwd 为
+ * "空隔离目录"，主动 cd 别处（如主 worktree）放弃隔离——实测见 wave-agent 事故
+ *（session 019ff64c T001 自述 cwd 是 pi 隔离目录，实际是合法 worktree checkout）。
+ *
+ * 此提示在 worktree 模式下注入，明确告知子 agent：cwd 是含完整项目代码的 git worktree，
+ * 直接在此工作即可，不要 cd 别处找"真正的项目"。
+ */
+export const WORKTREE_GUIDANCE_PROMPT = `
+## Working Directory Is a Git Worktree
+
+Your working directory (the "Working directory" in the environment block above) is a **dedicated git worktree** — an isolated checkout of the repository at HEAD, NOT a temporary sandbox. It contains the **complete project source code**.
+
+**You should:**
+- Work directly in your current cwd — it already has the full project (every file). Read project files via relative paths as usual.
+- To locate the shared repository root: \`git rev-parse --git-common-dir\`.
+- Your file changes are automatically captured as a patch when you finish — just do the work; no need to commit, push, or merge.
+
+**Do NOT** \`cd\` to another directory looking for "the real project" — your cwd IS the project. A path like \`/private/var/folders/.../pi-subagents/.../pi-sub-<id>\` is your worktree checkout, not an empty sandbox.
+`.trim();
+
 // ============================================================
 // 孤儿进程兜底（C1）
 // ============================================================
@@ -662,6 +686,11 @@ export async function runSpawn(
   if (opts.agentConfig?.tools?.includes("ask_user") && willRespondToAskUser(ctx.mode)) {
     appendParts.push(ASK_USER_RPC_PROMPT);
   }
+  // worktree 认知纠正：告知子 agent cwd 是 git worktree（非临时沙箱），含完整项目代码，
+  // 直接在此工作。防 wave-agent 类误判 cwd 为空隔离目录后 cd 主 worktree 放弃隔离。
+  if (opts.worktree) {
+    appendParts.push(WORKTREE_GUIDANCE_PROMPT);
+  }
   if (appendParts.length > 0) {
     tempPromptFile = await writePromptToTempFile(record.agent, appendParts.join("\n\n"));
   }
@@ -723,6 +752,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 +994,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) },
+      );
     }
   }
 }