@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,229 @@
+// 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 / spawnSync 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 { spawnSync } 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 {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+  return (r.stdout ?? "").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 + 删除临时目录。 */
+async function cleanup(): Promise<void> {
+  if (spawnedPid) {
+    try {
+      process.kill(spawnedPid, "SIGKILL");
+    } catch {
+      // 已退出
+    }
+    spawnedPid = undefined;
+  }
+  if (handle) {
+    try {
+      await wtm.cleanup(handle);
+    } catch (err) {
+      // best-effort：git worktree remove 失败不阻断测试清理
+      // eslint-disable-next-line no-console -- 测试 teardown 兜底留痕（清理失败不阻断后续 rmSync），非产品日志面
+      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(async () => {
+  vi.useRealTimers();
+  await cleanup();
+});
+
+// ── 用例 ──
+
+// [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 占位）
+    handle = await 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 超宽限 → 误删 → 红）
+    await 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 回收真孤儿
+    await 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 = await 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 且进程死 → 立即判孤儿回收（无需等宽限）
+    await wtm.scan();
+    expect(fs.existsSync(handle.path)).toBe(false);
+    expect(readEntry(handle.branch)).toBeUndefined();
+  }, 15000);
+});

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

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

@@ -0,0 +1,199 @@
+// src/__tests__/worktree-registry.test.ts
+//
+// WorktreeRegistry 单元测试。
+// 用真实 tmpdir 做文件 IO（不 mock fs），验证：
+//   - add/updatePid/remove/load 语义
+//   - 同 branch 覆盖（去重）
+//   - 文件不存在 / 损坏 / IO 错误的降级
+//   - 原子写（.tmp → rename）
+
+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 { SPAWN_GRACE_MS, type WorktreeEntry,WorktreeRegistry } from "../worktree-registry.ts";
+
+const REPO_A = "/home/user/repo-a";
+const REPO_B = "/home/user/repo-b";
+
+function makeEntry(overrides: Partial<WorktreeEntry> = {}): WorktreeEntry {
+  return {
+    repo: REPO_A,
+    branch: "pi-sub-bg-1",
+    checkout: path.join(os.tmpdir(), "pi-sub-bg-1"),
+    pid: 0,
+    createdAt: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("WorktreeRegistry", () => {
+  let tmpAgentDir: string;
+  let registry: WorktreeRegistry;
+  let registryFile: string;
+
+  beforeEach(() => {
+    tmpAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "wt-registry-test-"));
+    registry = new WorktreeRegistry(tmpAgentDir);
+    registryFile = path.join(tmpAgentDir, "subagents", "worktrees.json");
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpAgentDir, { recursive: true, force: true });
+  });
+
+  describe("add + load", () => {
+    it("add 后 load 能读到", async () => {
+      const entry = makeEntry();
+      await registry.add(entry);
+      const loaded = registry.load();
+      expect(loaded).toHaveLength(1);
+      expect(loaded[0]).toEqual(entry);
+    });
+
+    it("多条目跨 repo 共存", async () => {
+      const entryA = makeEntry({ repo: REPO_A, branch: "pi-sub-bg-1" });
+      const entryB = makeEntry({ repo: REPO_B, branch: "pi-sub-bg-2" });
+      await registry.add(entryA);
+      await registry.add(entryB);
+      const loaded = registry.load();
+      expect(loaded).toHaveLength(2);
+    });
+
+    it("同 branch add 覆盖（去重）", async () => {
+      const entry = makeEntry({ pid: 0 });
+      await registry.add(entry);
+      // 同 branch 再次 add（覆盖）
+      const updated = makeEntry({ pid: 999 });
+      await registry.add(updated);
+      const loaded = registry.load();
+      expect(loaded).toHaveLength(1);
+      expect(loaded[0].pid).toBe(999);
+    });
+  });
+
+  describe("updatePid", () => {
+    it("补全 pid（create 占位 → first header 补全）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1", pid: 0 }));
+      await registry.updatePid("pi-sub-bg-1", 12345);
+      const loaded = registry.load();
+      expect(loaded[0].pid).toBe(12345);
+    });
+
+    it("branch 不存在时忽略（幂等）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.updatePid("pi-sub-nonexistent", 12345);
+      const loaded = registry.load();
+      expect(loaded).toHaveLength(1);
+      expect(loaded[0].pid).toBe(0); // 原条目未变
+    });
+
+    it("update 不改变其他字段", async () => {
+      const entry = makeEntry({ branch: "pi-sub-bg-1", repo: REPO_A, checkout: "/tmp/x" });
+      await registry.add(entry);
+      await registry.updatePid("pi-sub-bg-1", 999);
+      const loaded = registry.load();
+      expect(loaded[0].repo).toBe(REPO_A);
+      expect(loaded[0].checkout).toBe("/tmp/x");
+      expect(loaded[0].branch).toBe("pi-sub-bg-1");
+    });
+  });
+
+  describe("remove", () => {
+    it("移除指定 branch", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.add(makeEntry({ branch: "pi-sub-bg-2" }));
+      await registry.remove("pi-sub-bg-1");
+      const loaded = registry.load();
+      expect(loaded).toHaveLength(1);
+      expect(loaded[0].branch).toBe("pi-sub-bg-2");
+    });
+
+    it("branch 不存在时忽略（幂等）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.remove("pi-sub-nonexistent");
+      expect(registry.load()).toHaveLength(1);
+    });
+
+    it("空注册表 remove 不报错", async () => {
+      await expect(registry.remove("pi-sub-anything")).resolves.not.toThrow();
+    });
+  });
+
+  describe("降级与健壮性", () => {
+    it("文件不存在时 load 返回空数组", async () => {
+      expect(registry.load()).toEqual([]);
+    });
+
+    it("损坏 JSON 时 load 返回空数组", async () => {
+      fs.mkdirSync(path.dirname(registryFile), { recursive: true });
+      fs.writeFileSync(registryFile, "{ not valid json }}}", "utf-8");
+      expect(registry.load()).toEqual([]);
+    });
+
+    it("entries 字段缺失时 load 返回空数组", async () => {
+      fs.mkdirSync(path.dirname(registryFile), { recursive: true });
+      fs.writeFileSync(registryFile, '{"other": 123}', "utf-8");
+      expect(registry.load()).toEqual([]);
+    });
+
+    it("save 创建不存在的父目录", async () => {
+      // registryFile 在 tmpAgentDir/subagents/ 下，subagents 目录不存在
+      expect(fs.existsSync(path.dirname(registryFile))).toBe(false);
+      await registry.add(makeEntry());
+      expect(fs.existsSync(registryFile)).toBe(true);
+    });
+
+    it("save 后无残留 .tmp 文件（原子写）", async () => {
+      await registry.add(makeEntry());
+      const tmpFile = `${registryFile}.tmp`;
+      expect(fs.existsSync(tmpFile)).toBe(false);
+    });
+  });
+
+  describe("SPAWN_GRACE_MS 常量", () => {
+    it("值为 60s", async () => {
+      expect(SPAWN_GRACE_MS).toBe(60_000);
+    });
+  });
+
+  describe("D5a 锁互斥（两写方并发不丢条目）", () => {
+    // [HISTORICAL] 2026-08-20 PR #185：真实 proper-lockfile 文件锁 RMW 用例显式超时——
+    // 单跑 >1s，整包满并行 + 系统余载下 100/31 次持锁 load→mutate→save 超过 vitest
+    // 默认 5s testTimeout（隔离跑通过，纯环境饿死），对齐本包 record-store-index 口径。
+    it("两个 registry 实例（模拟两 pi 进程写方）并发各 add 50 条，零丢失", { timeout: 30_000 }, async () => {
+      // 失败模式 G 的复现形态：无锁时两实例 load→mutate→save 交错，后写者覆盖
+      // 先写者 → 条目丢失。锁内 RMW 应保证 100 条全部落盘。
+      const r1 = new WorktreeRegistry(tmpAgentDir);
+      const r2 = new WorktreeRegistry(tmpAgentDir);
+      const tasks: Promise<void>[] = [];
+      for (let i = 0; i < 50; i++) {
+        tasks.push(r1.add(makeEntry({ branch: `pi-sub-w1-${i}` })));
+        tasks.push(r2.add(makeEntry({ branch: `pi-sub-w2-${i}` })));
+      }
+      await Promise.all(tasks);
+      const loaded = r1.load();
+      expect(loaded).toHaveLength(100);
+      // 两写方的条目都在（非「后写者全量覆盖」形态）
+      expect(loaded.filter((e) => e.branch.startsWith("pi-sub-w1-"))).toHaveLength(50);
+      expect(loaded.filter((e) => e.branch.startsWith("pi-sub-w2-"))).toHaveLength(50);
+    });
+
+    it("并发 add + remove 交错：remove 只删自己的 branch", { timeout: 30_000 }, async () => {
+      const r1 = new WorktreeRegistry(tmpAgentDir);
+      const r2 = new WorktreeRegistry(tmpAgentDir);
+      await r1.add(makeEntry({ branch: "pi-sub-keep" }));
+      const tasks: Promise<void>[] = [];
+      for (let i = 0; i < 30; i++) {
+        tasks.push(r2.add(makeEntry({ branch: `pi-sub-n-${i}` })));
+      }
+      tasks.push(r1.remove("pi-sub-keep"));
+      await Promise.all(tasks);
+      const loaded = r1.load();
+      expect(loaded).toHaveLength(30);
+      expect(loaded.find((e) => e.branch === "pi-sub-keep")).toBeUndefined();
+    });
+  });
+});