@zhushanwen/pi-subagent-workflow 8.0.0 → 8.1.0

package/src/execution/__tests__/record-store.test.ts

@@ -18,11 +18,12 @@ import * as path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { writeAliveMarker } from "../alive-store.ts";
-import { createRecord } from "../execution-record.ts";
+import { completeRecord, createRecord, tryTransition } from "../execution-record.ts";
 import { writeFinalized } from "../finalized-marker.ts";
 import type { ManifestRecord } from "../manifest-store.ts";
 import { ManifestStore } from "../manifest-store.ts";
 import { getSubagentRecordsDir, getSubagentSessionDir } from "../path-encoding.ts";
+import { SUBAGENT_RECORD_CUSTOM_TYPE } from "../record-entry.ts";
 import type { StatusFilter } from "../record-store.ts";
 import { RecordStore } from "../record-store.ts";
 import { writeCancelledTombstone } from "../tombstone-store.ts";
@@ -37,6 +38,8 @@ function makeRecord(over: Partial<ExecutionRecord> = {}): ExecutionRecord {
     task: "t",
     startedAt: 1000,
     rootSessionId: "sess-current",
+    // 对齐生产 register 路径（subagent-service createRecord：one-shot 显式 false）
+    chatMode: false,
   });
   return { ...base, ...over };
 }
@@ -47,7 +50,7 @@ function makeRecord(over: Partial<ExecutionRecord> = {}): ExecutionRecord {
  */
 function writeSessionJsonl(
   filePath: string,
-  identity: { id: string; agent: string; mode: "sync" | "background"; task: string; startedAt: number; rootSessionId?: string; parentRecordId?: string; depth?: number; lastTs?: number },
+  identity: { id: string; agent: string; mode: "sync" | "background"; task: string; startedAt: number; rootSessionId?: string; parentRecordId?: string; depth?: number; lastTs?: number; chatMode?: boolean },
   assistantText = "result text",
 ): void {
   const lastTs = identity.lastTs ?? identity.startedAt + 1000;
@@ -64,6 +67,7 @@ function writeSessionJsonl(
   if (identity.rootSessionId !== undefined) identityData.rootSessionId = identity.rootSessionId;
   if (identity.parentRecordId !== undefined) identityData.parentRecordId = identity.parentRecordId;
   if (identity.depth !== undefined) identityData.depth = identity.depth;
+  if (identity.chatMode !== undefined) identityData.chatMode = identity.chatMode;
   const identityEntry = JSON.stringify({
     type: "custom",
     id: "id-1",
@@ -772,4 +776,282 @@ describe("RecordStore", () => {
       expect(found?.closedReason).toBe("cancelled");
     });
   });
+
+  // ============================================================
+  // 孤儿终态恢复（residual-fixes）：分支 4 兜底 record 的判定与落盘
+  // ============================================================
+  describe("recoverOrphanRecords 孤儿终态恢复", () => {
+    /** 带真实磁盘 fixture + appendEntry 捕获的 store。 */
+    function makeRecoveryStore(): { store: RecordStore; appended: Array<{ customType: string; data: Record<string, unknown> }> } {
+      const appended: Array<{ customType: string; data: Record<string, unknown> }> = [];
+      const store = new RecordStore(tmpDir, undefined, {
+        appendEntry: (customType: string, data: unknown) => {
+          appended.push({ customType, data: data as Record<string, unknown> });
+        },
+      } as never);
+      return { store, appended };
+    }
+
+    it("末行完整 → closed 终态 entry + .finalized sidecar（防重锚）", () => {
+      const sessionFile = path.join(tmpDir, "orphan-done.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-orphan-1", agent: "worker", mode: "background", task: "orphan done",
+        startedAt: 1000, rootSessionId: "sess-orphan",
+      });
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-orphan-1");
+      expect(entry?.customType).toBe("subagent-record");
+      expect(entry?.data.status).toBe("closed");
+      expect(entry?.data.closedReason).toBe("gc");
+      expect(entry?.data.endedAt).toEqual(expect.any(Number));
+      expect(entry?.data.error).toBeUndefined();
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+      // 防重：sidecar 使下次重建走分支 2（closed），不再进判定
+      const again = [...appended];
+      store.recoverOrphanRecords("sess-orphan");
+      expect(appended.length).toBe(again.length);
+      const found = store.collectRecords(100, "all", "sess-orphan").find((r) => r.id === "sa-orphan-1");
+      expect(found?.status).toBe("closed");
+    });
+
+    it("末行截断 → closed + error（保守方向）", () => {
+      const sessionFile = path.join(tmpDir, "orphan-truncated.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-orphan-2", agent: "worker", mode: "background", task: "orphan truncated",
+        startedAt: 2000, rootSessionId: "sess-orphan",
+      });
+      // 制造截断：append 半行 JSON（无换行结尾）
+      fs.appendFileSync(sessionFile, '{"type":"message","id":"msg-2","pare', "utf-8");
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-orphan-2");
+      expect(entry?.data.status).toBe("closed");
+      expect(entry?.data.error).toContain("truncated");
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+    });
+
+    it("末行 >64KB 完整 JSON → 不误判截断，判 done（V1 探针实测回归）", () => {
+      const sessionFile = path.join(tmpDir, "orphan-longline.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-orphan-5", agent: "worker", mode: "background", task: "orphan long line",
+        startedAt: 5000, rootSessionId: "sess-orphan",
+      });
+      // 真实库实测形态：末行为超长完整 entry（subagent-identity 的 task 内嵌大 payload，
+      // 28/4822 个文件末行 65KB-776KB）——固定 64KB 尾窗曾把这类行从中间切开误判截断。
+      const bigEntry = JSON.stringify({
+        type: "custom", id: "id-big", parentId: null,
+        timestamp: new Date(5000).toISOString(), customType: "subagent-identity",
+        data: { id: "sa-orphan-5", agent: "worker", mode: "background", task: "x".repeat(70 * 1024), startedAt: 5000 },
+      });
+      fs.appendFileSync(sessionFile, bigEntry + "\n", "utf-8");
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-orphan-5");
+      expect(entry?.data.status).toBe("closed");
+      expect(entry?.data.error).toBeUndefined();
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+    });
+
+    it("chatMode 孤儿 → 不终态化，落 resumable entry（可续聊产品语义）", () => {
+      const sessionFile = path.join(tmpDir, "orphan-chat.jsonl");
+      writeSessionJsonl(sessionFile, {
+        id: "sa-orphan-3", agent: "worker", mode: "background", task: "orphan chat",
+        startedAt: 3000, rootSessionId: "sess-orphan", chatMode: true,
+      });
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-orphan-3");
+      expect(entry?.data.status).toBe("running");
+      expect(entry?.data.resumable).toBe(true);
+      expect(entry?.data.chatMode).toBe(true);
+      // chat 分流不写终态 sidecar
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(false);
+      // orphanJudged 缓存：同 store 重复调用不重复 append
+      const count = appended.length;
+      store.recoverOrphanRecords("sess-orphan");
+      expect(appended.length).toBe(count);
+    });
+
+    it("非分支 4 record（closed / 活进程）不进判定", () => {
+      const closedFile = path.join(tmpDir, "orphan-closed.jsonl");
+      writeSessionJsonl(closedFile, {
+        id: "sa-orphan-4", agent: "worker", mode: "background", task: "already closed",
+        startedAt: 4000, rootSessionId: "sess-orphan",
+      });
+      writeFinalized(closedFile);
+      const { store, appended } = makeRecoveryStore();
+      store.recoverOrphanRecords("sess-orphan");
+      expect(appended.find((c) => c.data.id === "sa-orphan-4")).toBeUndefined();
+    });
+
+    /** 写主 session fixture（含指定 subagent-record entry 序列）。 */
+    function writeMainSession(entries: Array<Record<string, unknown>>): string {
+      const mainFile = path.join(tmpDir, "main-session.jsonl");
+      const lines = entries.map((d) => JSON.stringify({ type: "custom", id: `e-${Math.random()}`, parentId: null, customType: "subagent-record", data: d }));
+      fs.writeFileSync(mainFile, lines.join("\n") + "\n", "utf-8");
+      return mainFile;
+    }
+
+    it("entry-born 孤儿（无子文件，spawn 窗口期死亡）→ closed+gc+error（E2E 实测回归）", () => {
+      const mainFile = writeMainSession([
+        { v: 1, id: "sa-entryonly-1", agent: "worker", task: "spawn interrupted", slug: "s", status: "running", mode: "background", startedAt: 6000, rootSessionId: "sess-orphan", depth: 0, turns: 0, totalTokens: 0, model: "m", eventLog: [], displayItems: [] },
+      ]);
+      const { store, appended } = makeRecoveryStore();
+      store.recoverEntryOnlyOrphans(mainFile, "sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-entryonly-1");
+      expect(entry?.data.status).toBe("closed");
+      expect(entry?.data.closedReason).toBe("gc");
+      expect(entry?.data.error).toContain("no child session file");
+      // 防重：orphanJudged 缓存拦截二次判定
+      const count = appended.length;
+      store.recoverEntryOnlyOrphans(mainFile, "sess-orphan");
+      expect(appended.length).toBe(count);
+    });
+
+    it("entry-born chatMode 孤儿 → 不终态化，落 resumable entry", () => {
+      const mainFile = writeMainSession([
+        { v: 1, id: "sa-entryonly-2", agent: "worker", task: "chat spawn interrupted", slug: "s", status: "running", mode: "background", startedAt: 7000, rootSessionId: "sess-orphan", depth: 0, turns: 0, totalTokens: 0, model: "m", eventLog: [], displayItems: [], chatMode: true },
+      ]);
+      const { store, appended } = makeRecoveryStore();
+      store.recoverEntryOnlyOrphans(mainFile, "sess-orphan");
+
+      const entry = appended.find((c) => c.data.id === "sa-entryonly-2");
+      expect(entry?.data.status).toBe("running");
+      expect(entry?.data.resumable).toBe(true);
+      expect(entry?.data.error).toBeUndefined();
+    });
+
+    it("有子文件锚 / 末条已终态 / 他 session 的 entry-born id 不进判定", () => {
+      const anchoredFile = path.join(tmpDir, "orphan-anchored.jsonl");
+      writeSessionJsonl(anchoredFile, {
+        id: "sa-anchored", agent: "worker", mode: "background", task: "has file",
+        startedAt: 8000, rootSessionId: "sess-orphan",
+      });
+      const mainFile = writeMainSession([
+        { v: 1, id: "sa-anchored", agent: "worker", task: "has file", slug: "s", status: "running", mode: "background", startedAt: 8000, rootSessionId: "sess-orphan", depth: 0, turns: 0, totalTokens: 0, model: "m", eventLog: [], displayItems: [] },
+        { v: 1, id: "sa-settled", agent: "worker", task: "settled", slug: "s", status: "closed", mode: "background", startedAt: 8100, rootSessionId: "sess-orphan", depth: 0, turns: 1, totalTokens: 0, model: "m", eventLog: [], displayItems: [] },
+        { v: 1, id: "sa-foreign", agent: "worker", task: "other session", slug: "s", status: "running", mode: "background", startedAt: 8200, rootSessionId: "sess-other", depth: 0, turns: 0, totalTokens: 0, model: "m", eventLog: [], displayItems: [] },
+      ]);
+      const { store, appended } = makeRecoveryStore();
+      store.recoverEntryOnlyOrphans(mainFile, "sess-orphan");
+      expect(appended.find((c) => c.data.id === "sa-anchored")).toBeUndefined();
+      expect(appended.find((c) => c.data.id === "sa-settled")).toBeUndefined();
+      expect(appended.find((c) => c.data.id === "sa-foreign")).toBeUndefined();
+    });
+  });
+
+  // ============================================================
+  // W16 [D4]：subagent-record 自描述 appendEntry 上报（状态迁移点）
+  // ============================================================
+  describe("W16 subagent-record 自描述 appendEntry 上报", () => {
+    /** appendEntry 捕获（RecordStorePi 最小实现）。 */
+    interface AppendedCall {
+      customType: string;
+      data: unknown;
+    }
+
+    /** 构造带 appendEntry 捕获的 store（pi 注入通道，对齐生产 setPi 后形态）。 */
+    function makeStoreWithPi(): { store: RecordStore; appended: AppendedCall[] } {
+      const appended: AppendedCall[] = [];
+      const store = new RecordStore(tmpDir, undefined, {
+        appendEntry: (customType: string, data: unknown) => {
+          appended.push({ customType, data });
+        },
+      });
+      return { store, appended };
+    }
+
+    /** unknown → 对象的运行时 guard（taste/no-unsafe-cast：断言前先收窄）。 */
+    function asEntryData(d: unknown): Record<string, unknown> {
+      if (typeof d !== "object" || d === null) throw new Error("entry data is not an object");
+      return d as Record<string, unknown>;
+    }
+
+    it("register：append subagent-record entry，data = v1 + SubagentRecord 完整快照 schema", () => {
+      const { store, appended } = makeStoreWithPi();
+      store.register(makeRecord());
+
+      expect(appended).toHaveLength(1);
+      // 写点字面量与 record-entry.ts 常量等值（钉住双源一致性）
+      expect(appended[0]?.customType).toBe(SUBAGENT_RECORD_CUSTOM_TYPE);
+      // [E2E 实测教训] 必须先 JSON 序列化再断言：appendEntry 捕获的是内存对象，
+      // undefined 值的键名仍在（旧 27-key 断言因此漏检 recordToSubagent 丢
+      // chatMode 的 bug）；真实 JSONL 会丢 undefined 值键，此处对齐生产行为。
+      const data = asEntryData(JSON.parse(JSON.stringify(appended[0]?.data)));
+      // register 时点序列化存活字段（undefined 值字段按生产序列化丢弃）：
+      // chatMode 必须显式在场（one-shot=false）——renderer isDone 判据依赖它。
+      expect(Object.keys(data).sort()).toEqual([
+        "agent", "chatMode", "depth", "displayItems", "eventLog",
+        "id", "mode", "model", "rootSessionId", "round", "startedAt",
+        "status", "task", "totalTokens", "turns", "v", "worktree",
+      ]);
+      expect(data).toMatchObject({
+        v: 1,
+        id: "r1",
+        agent: "worker",
+        task: "t",
+        status: "running",
+        mode: "sync",
+        startedAt: 1000,
+        rootSessionId: "sess-current",
+        chatMode: false,
+        turns: 0,
+        totalTokens: 0,
+        model: "m",
+        eventLog: [],
+        displayItems: [],
+      });
+    });
+
+    it("archive：append 终态完整快照（result/endedAt/closedReason）；one-shot 生命周期共 2 次 append", () => {
+      const { store, appended } = makeStoreWithPi();
+      const r = makeRecord();
+      store.register(r);
+      // 模拟正常终态路径：tryTransition CAS → completeRecord 冻结 → archive（D-017 时序）
+      tryTransition(r, "closed", "gc");
+      completeRecord(r, { text: "task done", turns: 1, durationMs: 500, success: true, sessionId: "r1", toolCalls: [] }, "closed", "gc");
+      store.archive(r);
+
+      // 探针基线（单测级）：one-shot 生命周期 = register + archive = 2 次 append
+      expect(appended).toHaveLength(2);
+      const data = asEntryData(appended[1]?.data);
+      expect(data).toMatchObject({
+        v: 1,
+        id: "r1",
+        status: "closed",
+        closedReason: "gc",
+        result: "task done",
+        endedAt: expect.any(Number) as number,
+      });
+    });
+
+    it("reportRecordTransition：类外恢复写点上报（chatMode 续轮 round 携带）", () => {
+      const { store, appended } = makeStoreWithPi();
+      const r = makeRecord({ chatMode: true, round: 1 });
+      store.reportRecordTransition(r);
+
+      expect(appended).toHaveLength(1);
+      expect(appended[0]?.customType).toBe(SUBAGENT_RECORD_CUSTOM_TYPE);
+      expect(asEntryData(appended[0]?.data)).toMatchObject({
+        v: 1,
+        id: "r1",
+        status: "running",
+        round: 1,
+      });
+    });
+
+    it("pi 未注入（session_start 前）：三写点均安全降级不抛错", () => {
+      const store = new RecordStore(tmpDir);
+      const r = makeRecord();
+      expect(() => store.register(r)).not.toThrow();
+      expect(() => store.archive(r)).not.toThrow();
+      expect(() => store.reportRecordTransition(r)).not.toThrow();
+    });
+  });
 });

package/src/execution/__tests__/spawn-args.test.ts

@@ -194,18 +194,18 @@ describe("buildSpawnArgs", () => {
   it("noContextFiles 镜像：主进程 argv 含 --no-context-files → 子进程 args 含该 flag", () => {
     // 端到端链路断言：主 pi 进程以 --no-context-files 启动（用户 opt-out context files）
     // → mirrorMainProcessFlags 解析 → buildSpawnArgs 产出同 flag 给每个 subagent。
-    // 缺此镜像时，--extension 镜像带入的 xyz-system-prompt-extension.js 检查子进程
+    // 缺此镜像时，--extension 镜像带入的 @zhushanwen/pi-system-prompt 检查子进程
     // 自己的 argv（无 flag）→ 全局 AGENTS.md 注入在 subagent system prompt 照常生效，
     // 用户 opt-out 被绕过。
     const mainArgv = [
       "bun", "/pi", "--mode", "rpc", "--no-context-files",
-      "--extension", "/path/xyz-system-prompt-extension.js",
+      "--extension", "/staged/@zhushanwen/pi-system-prompt/index.js",
     ];
     const args = buildSpawnArgs({ ...baseParams, mirrorFlags: mirrorMainProcessFlags(mainArgv) });
     expect(args).toContain("--no-context-files");
     // extension 镜像照常（两者共存才构成完整契约）
     const extIdx = args.indexOf("--extension");
-    expect(args[extIdx + 1]).toBe("/path/xyz-system-prompt-extension.js");
+    expect(args[extIdx + 1]).toBe("/staged/@zhushanwen/pi-system-prompt/index.js");
   });
 
   it("noContextFiles 不镜像：主进程 argv 不含 flag → 子进程 args 不含（默认行为不变）", () => {
@@ -293,11 +293,11 @@ describe("mirrorMainProcessFlags", () => {
   it("--no-context-files 长形式解析 → noContextFiles: true", () => {
     const r = mirrorMainProcessFlags([
       "bun", "/pi", "--mode", "rpc", "--no-context-files",
-      "--extension", "/path/xyz-system-prompt-extension.js",
+      "--extension", "/staged/@zhushanwen/pi-system-prompt/index.js",
     ]);
     expect(r.noContextFiles).toBe(true);
     // 与 extension 镜像共存（实际 xyz-agent 启动形态：两 flag 同时出现）
-    expect(r.extensionPaths).toEqual(["/path/xyz-system-prompt-extension.js"]);
+    expect(r.extensionPaths).toEqual(["/staged/@zhushanwen/pi-system-prompt/index.js"]);
     expect(r.noExtensions).toBe(false);
     expect(r.approve).toBe(false);
   });

package/src/execution/__tests__/subagent-service-message-close.test.ts

@@ -595,4 +595,35 @@ describe("[C-4] onRoundSettled 轮次增量 + [C-1] close 终态通知", () => {
     expect(record.status).toBe("closed");
     expect(pi.sendMessage).not.toHaveBeenCalled();
   });
+
+  it("[W16 P-1 回归] close 终态 subagent-record entry 的 result == 轮终真实值（closeChatIdle 不抹空）", async () => {
+    // 完整生命周期：register（entry: running）→ 轮终（record.result = 轮终真实值）→
+    // idle close（archive 落 close 终态 entry——D4 重建源）。
+    // 缺陷形态（verifier W16 实测复现）：closeChatIdle 合成 text:"" 经 completeRecord
+    // 覆盖 record.result → close entry 的 result=''（轮终 'ok' 被抹空），W18 消费后
+    // 重开 session result 回退空串。修复：doneResult.text 沿用 record.result。
+    const record = makeRecord({ id: "sa-close-entry-result", status: "running" });
+    record.sessionFile = path.join(agentDir, "close-entry-result.jsonl");
+    store.register(record);
+    armIdleTimer(record.id, () => {});
+    try {
+      updateFromEvent(record, { type: "text_delta", delta: "ok" });
+      updateFromEvent(record, { type: "turn_end" });
+      settleRound(record); // 轮终：onRoundSettled 写 record.result = "ok"
+      expect(record.result).toBe("ok"); // 前提锚点：轮终真实值在位
+      await service.closeSubagent(record, false); // idle close → completeRecord + archive
+    } finally {
+      disarmIdleTimer(record.id);
+    }
+
+    // appendEntry 序列中的 subagent-record 快照：register（running）→ close（closed）。
+    const snapshots = pi.appendEntry.mock.calls
+      .filter(([type]) => type === "subagent-record")
+      .map(([, data]) => data as { status: string; result?: string });
+    expect(snapshots.length).toBeGreaterThanOrEqual(2);
+    const closeEntry = snapshots[snapshots.length - 1]!;
+    expect(closeEntry.status).toBe("closed");
+    // 修复断言：close 终态 entry 保持轮终真实值（缺陷形态为 ''）
+    expect(closeEntry.result).toBe("ok");
+  });
 });

package/src/execution/__tests__/worktree-manager.test.ts

@@ -520,9 +520,16 @@ describe("WorktreeManager", () => {
     });
 
     it("pid 活的条目不删（绝不删活进程）", async () => {
-      setupExecFile();
-      injectEntry({ branch: "pi-sub-alive", pid: 22222 });
+      // 物理面也 mock 存在（branch --list 返回该分支 + checkout 目录在）——
+      // D5b 对账的两个方向（清孤儿 / 清幻影条目）都必须不动活条目。
+      setupExecFile((args: readonly string[]) => {
+        if (args[0] === "branch" && args[1] === "--list") return { stdout: "pi-sub-alive\n" };
+        return { stdout: "" };
+      });
+      const checkout = path.join(os.tmpdir(), "pi-sub-orphan1");
+      injectEntry({ branch: "pi-sub-alive", pid: 22222, checkout });
       mockIsProcessAlive.mockReturnValue(true); // pid 活
+      mockExistsSync.mockImplementation((p: unknown) => String(p) === checkout);
 
       await mgr.scan();
 

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

@@ -139,7 +139,10 @@ afterEach(async () => {
 
 // ── 用例 ──
 
-describe("worktree pid 注册链路（真实 spawn 集成）", () => {
+// [HISTORICAL] 2026-08-20 PR #185：真实 spawn node 子进程 + 真实 git worktree + 注册表
+// 文件锁集成用例显式超时——整包满并行 + 系统余载下真实子进程链路超 vitest 默认 5s
+// testTimeout（对齐本包 worktree-registry D5a / process-shutdown-hook 口径）。
+describe("worktree pid 注册链路（真实 spawn 集成）", { timeout: 30_000 }, () => {
   it("正向：spawn 返回后注册表 pid 同步补全，活 worktree 超宽限不被 scan 误清", async () => {
     // 0. 长驻脚本（子进程 90s 内不退出，模拟长跑子 agent）
     scriptHolder.script = LONG_RUNNING_SCRIPT;    // 1. 真实创建 worktree（pid=0 占位）

package/src/execution/__tests__/worktree-reconcile.integration.test.ts

@@ -0,0 +1,181 @@
+// src/__tests__/worktree-reconcile.integration.test.ts
+//
+// D5b 对账双向 diff 集成测试：真实 git repo + 真实 tmpdir（不 mock fs/execFile）。
+//
+// 隔离手段：TMPDIR env 重定向到测试私有目录——WorktreeManager 的物理面扫描
+// 根 = os.tmpdir()/pi-subagents（跟随 TMPDIR），避免扫到本机其他进程的真实残留。
+//
+// 覆盖四个收敛方向（判据见 worktree-manager.ts reconcileWithPhysical）：
+//   1. 物理有 + 注册无 + 无活 pid + 超 grace → 清分支与目录
+//   2. 物理有 + 注册无 + 恰好 1 活 pid + 1 残留 → 补写回注册表（自愈）
+//   3. 注册有（pid 活）+ 物理无 → 移除幻影条目
+//   4. 多活 pid / 多残留（对应歧义）→ 跳过不动（宁延迟勿误删）
+
+import { execFileSync, spawn } 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 } from "vitest";
+
+import { encodeCwd } from "../path-encoding.ts";
+import { WorktreeRegistry } from "../worktree-registry.ts";
+import { WorktreeManager } from "../worktree-manager.ts";
+
+/** 原始 TMPDIR（beforeEach 重定向、afterEach 还原）。 */
+const ORIG_TMPDIR = os.tmpdir();
+
+/** git 辅助：repo 内执行（输出 trim）。 */
+function git(repo: string, ...args: string[]): string {
+	return execFileSync("git", ["-C", repo, ...args], { encoding: "utf-8" }).trim();
+}
+
+// [HISTORICAL] 2026-08-20 PR #185：真实 git 子进程 + 注册表文件锁集成用例显式超时——
+// 每用例多次 git init/worktree add/branch -D 真实子进程调用，整包满并行 + 系统余载下
+// 超 vitest 默认 5s testTimeout（对齐本包 worktree-registry D5a / process-shutdown-hook 口径）。
+describe("WorktreeManager.scan 物理面对账（D5b）", { timeout: 30_000 }, () => {
+	let baseDir: string;
+	let agentDir: string;
+	let repo: string;
+	let enc: string;
+	let registry: WorktreeRegistry;
+	let mgr: WorktreeManager;
+	/** 真实系统 tmp 下的测试根（TMPDIR 重定向目标）。 */
+	let outerDir: string;
+
+	beforeEach(() => {
+		outerDir = fs.mkdtempSync(path.join(ORIG_TMPDIR, "wt-reconcile-it-"));
+		// 物理面扫描根重定向：os.tmpdir() 跟随 TMPDIR env（darwin/linux 均如此）
+		process.env.TMPDIR = outerDir;
+		baseDir = outerDir;
+
+		agentDir = path.join(baseDir, "agent");
+		repo = path.join(baseDir, "repo");
+		fs.mkdirSync(repo, { recursive: true });
+		git(repo, "init", "-q");
+		git(repo, "config", "user.email", "test@test.local");
+		git(repo, "config", "user.name", "test");
+		fs.writeFileSync(path.join(repo, "a.txt"), "init\n", "utf-8");
+		git(repo, "add", "-A");
+		git(repo, "commit", "-q", "-m", "init");
+
+		enc = encodeCwd(repo);
+		registry = new WorktreeRegistry(agentDir);
+		mgr = new WorktreeManager(agentDir);
+	});
+
+	afterEach(() => {
+		process.env.TMPDIR = ORIG_TMPDIR;
+		fs.rmSync(outerDir, { recursive: true, force: true });
+	});
+
+	/** 建一个物理 worktree（按 create() 的真实路径布局，绕过 WorktreeManager.create 的脏树校验）。 */
+	function makePhysicalWorktree(branch: string): string {
+		const checkout = path.join(baseDir, "pi-subagents", enc, branch);
+		git(repo, "worktree", "add", "-q", "-b", branch, checkout, "HEAD");
+		return checkout;
+	}
+
+	/** 在 <agentDir>/subagents/<enc>/sessions/ 下写一个 .alive marker。 */
+	function writeAliveMarker(sessionId: string, pid: number): void {
+		const sessions = path.join(agentDir, "subagents", enc, "sessions");
+		fs.mkdirSync(sessions, { recursive: true });
+		fs.writeFileSync(
+			path.join(sessions, `${sessionId}.jsonl.alive`),
+			JSON.stringify({ pid, id: sessionId, startedAt: Date.now() }),
+			"utf-8",
+		);
+	}
+
+	/** 把目录 mtime 设到 grace 之前（对账判据的 createdAt 近似）。 */
+function ageBeyondGrace(dir: string): void {
+		const past = new Date(Date.now() - 120_000);
+		fs.utimesSync(dir, past, past);
+	}
+
+	it("物理有 + 注册无 + 无活 pid + 超 grace → 清分支与目录", async () => {
+		const checkout = makePhysicalWorktree("pi-sub-t1");
+		ageBeyondGrace(checkout);
+
+		await mgr.scan();
+
+		expect(fs.existsSync(checkout)).toBe(false);
+		expect(git(repo, "branch", "--list", "pi-sub-*")).toBe("");
+		expect(registry.load()).toEqual([]);
+	});
+
+	it("物理有 + 注册无 + 未超 grace（create 窗口）→ 跳过不删", async () => {
+		const checkout = makePhysicalWorktree("pi-sub-t2");
+		// mtime 保持「现在」——另一进程 worktree add 完成到 registry.add 落盘之间的窗口
+
+		await mgr.scan();
+
+		expect(fs.existsSync(checkout)).toBe(true);
+		expect(git(repo, "branch", "--list", "pi-sub-t2")).not.toBe("");
+	});
+
+	it("物理有 + 注册无 + 恰好 1 活 pid + 1 残留 → 补写回注册表（自愈）", async () => {
+		const checkout = makePhysicalWorktree("pi-sub-t3");
+		// 活 pid 用本测试进程（isProcessAlive 真实调用必活）
+		writeAliveMarker("s-t3", process.pid);
+
+		await mgr.scan();
+
+		const entries = registry.load();
+		expect(entries).toHaveLength(1);
+		expect(entries[0].branch).toBe("pi-sub-t3");
+		expect(entries[0].pid).toBe(process.pid);
+		expect(entries[0].checkout).toBe(checkout);
+		// 物理资源未被删（自愈而非只删）
+		expect(fs.existsSync(checkout)).toBe(true);
+	});
+
+	it("注册有（pid 活）+ 物理无 → 移除幻影条目", async () => {
+		// pid 活（本进程）使阶段一孤儿清理跳过，隔离方向一的独立语义
+		await registry.add({
+			repo,
+			branch: "pi-sub-ghost",
+			checkout: path.join(baseDir, "pi-subagents", enc, "pi-sub-ghost"),
+			pid: process.pid,
+			createdAt: Date.now(),
+		});
+
+		await mgr.scan();
+
+		expect(registry.load()).toEqual([]);
+	});
+
+	it("多残留 + 多活 pid（对应歧义）→ 跳过不动", async () => {
+		const c1 = makePhysicalWorktree("pi-sub-m1");
+		const c2 = makePhysicalWorktree("pi-sub-m2");
+		ageBeyondGrace(c1);
+		ageBeyondGrace(c2);
+		// 第二个「活 pid」用真实 sleep 子进程（与 process.pid 不同值）
+		const sleeper = spawn("sleep", ["60"]);
+		try {
+			expect(sleeper.pid).toBeTruthy();
+			writeAliveMarker("s-m1", process.pid);
+			writeAliveMarker("s-m2", sleeper.pid as number);
+
+			await mgr.scan();
+
+			// 歧义 → 本周期全部跳过（宁延迟勿误删），下周期活 pid 消失后收敛
+			expect(fs.existsSync(c1)).toBe(true);
+			expect(fs.existsSync(c2)).toBe(true);
+			expect(registry.load()).toEqual([]);
+		} finally {
+			sleeper.kill("SIGKILL");
+		}
+	});
+
+	it("幂等：连续两次 scan 结果一致（无重复动作）", async () => {
+		const checkout = makePhysicalWorktree("pi-sub-idem");
+		ageBeyondGrace(checkout);
+
+		await mgr.scan();
+		await mgr.scan();
+
+		expect(fs.existsSync(checkout)).toBe(false);
+		expect(git(repo, "branch", "--list", "pi-sub-*")).toBe("");
+	});
+});