@zhushanwen/subagent-core 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-core",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Cross-host shared subagent execution layer and workflow orchestration core (dual-form npm package: TS source for workspace, dist ESM+CJS for npm)",
   "type": "module",
   "license": "MIT",
@@ -84,7 +84,7 @@
     "ajv": "^8.20.0",
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.8.1"
+    "@xyz-agent/extension-protocol": "0.8.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

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

@@ -145,7 +145,7 @@ model: x/y`);
 describe("AgentRegistry.loadByPath", () => {
   let ws: string;
   beforeEach(() => { ws = tmpWorkspace(); });
-  afterEach(() => { fs.rmSync(ws, { recursive: true, force: true }); });
+  afterEach(() => { fs.rmSync(ws, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 }); });
 
   it("按绝对路径加载 agent：frontmatter + body → AgentConfig", () => {
     const file = writeAgent(path.join(ws, ".pi", "agents"), "worker", `---

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

@@ -23,7 +23,7 @@ describe("alive-store", () => {
 
   afterEach(() => {
     if (tmpDir) {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
+      fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 

package/src/execution/__tests__/collect-budget.test.ts

@@ -0,0 +1,291 @@
+// src/execution/__tests__/collect-budget.test.ts
+//
+// U4 预算截断 + 指针 纯函数规格锁（subagent-sync-collect 设计 §3.1.2）：
+//
+//   两段式预算（确定性，无瀑布分配）：
+//     ① per-item 截断：每条目正文 ≤ perItemChars（默认 4000）；
+//     ② 总量再压缩：Σ(截断后正文) > totalChars（默认 24000）时统一收紧
+//        effectivePerItem = clamp(floor(totalChars / n), 200, perItemChars)；
+//        floor < 200（n > totalChars/200）→ 纯清单退化（头行 + 指针行，正文 0）。
+//
+//   指针行：[truncated {omitted} of {total} chars — full result: session_read
+//   {"action":"result","session":"{id}"}]（omitted = total − kept；千位分隔）。
+//   [D6 #9] fixture id 统一 `sa-` 前缀——与产线 record id（`sa-<uuid>`，
+//   subprocess-agent-runner.ts / subagent-service.ts 同款）同形，session_read 指针行
+//   断言的是产线真实可达的 id 形态。
+//   [C3 limit 随附] 该成员预算（effectivePerItem）> session_read 默认 8000 时 JSON 附
+//   "limit":N（N = effectivePerItem）；≤8000 不附（默认已覆盖）。
+//
+//   totalChars 口径：仅计条目正文（截断后）之和；批头/头行/指针行/分隔符等
+//   包装开销有界常量不入预算。
+//
+// 纯内存零 IO；不依赖产线 mock（只 import 两个纯函数 + BgNotifyRecord 类型）。
+
+import { describe, expect, it } from "vitest";
+import type { BgNotifyRecord } from "../notifier.ts";
+import { buildBatchLlmContent, computeBatchBudget } from "../notifier.ts";
+
+// ─── fixture ──
+
+/** 成功完成的批成员；result = ch 重复 bodyLen 次（缺省 7 字符，永不触预算）。 */
+function member(id: string, over: Partial<BgNotifyRecord> = {}): BgNotifyRecord {
+  return {
+    id,
+    status: "closed",
+    outcome: "completed",
+    agent: `worker-${id}`,
+    result: `result of ${id}`,
+    startedAt: 1000,
+    endedAt: 2000,
+    ...over,
+  };
+}
+
+function filled(id: string, bodyLen: number, ch = "A"): BgNotifyRecord {
+  return member(id, { result: ch.repeat(bodyLen) });
+}
+
+/** 设计默认预算（config 热读接线前 U4 以默认常量锁规格）。 */
+const PER_ITEM = 4000;
+const TOTAL = 24000;
+
+/** 期望指针行（千位分隔与设计样例 11,234 对齐）。perItemLimit > 8000 时附 "limit":N（C3）。 */
+function pointer(id: string, kept: number, total: number, perItemLimit: number): string {
+  const fmt = (n: number) => n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  const limitPart = perItemLimit > 8000 ? `,"limit":${perItemLimit}` : "";
+  return `[truncated ${fmt(total - kept)} of ${fmt(total)} chars — full result: session_read {"action":"result","session":"${id}"${limitPart}}]`;
+}
+
+/** 期望条目：Result: 头行 + kept 正文 + （截断时）… + 指针行。 */
+function expectedEntry(
+  rec: { id: string; agent: string },
+  fullBody: string,
+  kept: number,
+  perItemLimit: number,
+): string {
+  const head = `Subagent "${rec.agent}" (${rec.id}) completed. Result:\n`;
+  if (fullBody.length <= kept) return head + fullBody;
+  return `${head}${fullBody.slice(0, kept)}…\n${pointer(rec.id, kept, fullBody.length, perItemLimit)}`;
+}
+
+// ─── computeBatchBudget 纯函数公式 ──
+
+describe("computeBatchBudget（两段式预算公式）", () => {
+  it("7 成员各 6000：effectivePerItem = clamp(floor(24000/7)=3428, 200, 4000) = 3428", () => {
+    const plan = computeBatchBudget(Array.from({ length: 7 }, () => 6000), PER_ITEM, TOTAL);
+    expect(plan.tightened).toBe(true);
+    expect(plan.listOnly).toBe(false);
+    expect(plan.effectivePerItem).toBe(3428);
+  });
+
+  it("6 成员各 3000（Σ=18000 ≤ totalChars）：不触发第二段收紧", () => {
+    const plan = computeBatchBudget(Array.from({ length: 6 }, () => 3000), PER_ITEM, TOTAL);
+    expect(plan.tightened).toBe(false);
+    expect(plan.listOnly).toBe(false);
+    expect(plan.effectivePerItem).toBe(PER_ITEM);
+  });
+
+  it("n > totalChars/200（n=125 → floor=192 < 200）：纯清单退化 effectivePerItem = 0", () => {
+    expect(TOTAL / 200).toBe(120);
+    const plan = computeBatchBudget(Array.from({ length: 125 }, () => 1000), PER_ITEM, TOTAL);
+    expect(plan.tightened).toBe(true);
+    expect(plan.listOnly).toBe(true);
+    expect(plan.effectivePerItem).toBe(0);
+  });
+
+  it("边界 n=120（floor(24000/120)=200 恰达下限）：不退化，effectivePerItem = 200", () => {
+    const plan = computeBatchBudget(Array.from({ length: 120 }, () => 1000), PER_ITEM, TOTAL);
+    expect(plan.listOnly).toBe(false);
+    expect(plan.effectivePerItem).toBe(200);
+  });
+
+  it("口径：bodyLengths 仅收正文长度，Σ 恰等于 totalChars（=24000）不算超、不收紧", () => {
+    const plan = computeBatchBudget(Array.from({ length: 6 }, () => 4000), PER_ITEM, TOTAL);
+    expect(plan.tightened).toBe(false);
+  });
+});
+
+// ─── buildBatchLlmContent 组装链 ──
+
+describe("buildBatchLlmContent 预算截断组装（设计 §3.1.2）", () => {
+  it("7 成员各 6000：每条收紧至 3428 字符 + 指针行，总量回到预算内", () => {
+    const records = Array.from({ length: 7 }, (_, i) => filled(`sa-${i}`, 6000));
+    const content = buildBatchLlmContent(records);
+    const parts = content.split("\n\n---\n\n");
+
+    expect(parts[0]).toBe("Subagent batch completed: 7 finished, 0 failed, 0 cancelled.");
+    expect(parts).toHaveLength(8);
+    for (let i = 0; i < 7; i++) {
+      expect(parts[i + 1]).toBe(expectedEntry(records[i], "A".repeat(6000), 3428, 3428));
+      expect(parts[i + 1]).toContain(
+        pointer(`sa-${i}`, 3428, 6000, 3428), // omitted = 6000 − 3428 = 2,572
+      );
+    }
+  });
+
+  it("6 成员各 3000（Σ=18000）：不触发第二段——每条全量在场、零指针行", () => {
+    const records = Array.from({ length: 6 }, (_, i) => filled(`sa-${i}`, 3000));
+    const content = buildBatchLlmContent(records);
+    const parts = content.split("\n\n---\n\n");
+
+    expect(parts[0]).toBe("Subagent batch completed: 6 finished, 0 failed, 0 cancelled.");
+    expect(content).not.toContain("[truncated");
+    for (let i = 0; i < 6; i++) {
+      expect(parts[i + 1]).toBe(expectedEntry(records[i], "A".repeat(3000), 3000, PER_ITEM));
+    }
+  });
+
+  it("n=125：纯清单退化——每条只剩头行 + 指针行，正文零残留", () => {
+    const records = Array.from({ length: 125 }, (_, i) => filled(`sa-${i}`, 1000, "B"));
+    const content = buildBatchLlmContent(records);
+    const parts = content.split("\n\n---\n\n");
+
+    expect(parts[0]).toBe("Subagent batch completed: 125 finished, 0 failed, 0 cancelled.");
+    expect(parts).toHaveLength(126);
+    for (let i = 0; i < 125; i++) {
+      // 头行 + 指针行紧邻（kept=0 → 无正文、无省略号）
+      expect(parts[i + 1]).toBe(
+        `Subagent "worker-sa-${i}" (sa-${i}) completed. Result:\n${pointer(`sa-${i}`, 0, 1000, 0)}`,
+      );
+    }
+    // 正文零残留（kept=0）
+    expect(content).not.toContain("BBBB");
+    expect(content).not.toContain("…");
+  });
+
+  it("指针行格式（第一段 per-item 截断同样接指针）：omitted = total − kept", () => {
+    // 2 成员各 5000：Σ=8000 ≤ 24000 不收紧，per-item 截 4000
+    const records = [filled("sa-aaa", 5000), filled("sa-bbb", 5000)];
+    const parts = buildBatchLlmContent(records).split("\n\n---\n\n");
+    for (const rec of records) {
+      expect(parts).toContain(expectedEntry(rec, "A".repeat(5000), PER_ITEM, PER_ITEM));
+    }
+    expect(parts[1]).toContain(pointer("sa-aaa", 4000, 5000, PER_ITEM)); // 1,000 of 5,000
+  });
+
+  it("长短参差（1 短 500 + 6 长 6000）：统一收紧 3428，短条目足额保留——非瀑布分配", () => {
+    // Σ(per-item 后) = 500 + 6×4000 = 24500 > 24000 → 触发收紧
+    const shortOne = filled("sa-short", 500, "S");
+    const longs = Array.from({ length: 6 }, (_, i) => filled(`sa-long-${i}`, 6000));
+    const records = [shortOne, ...longs];
+    const content = buildBatchLlmContent(records);
+    const parts = content.split("\n\n---\n\n");
+
+    expect(parts[0]).toBe("Subagent batch completed: 7 finished, 0 failed, 0 cancelled.");
+    // 短条目：500 < 3428 足额全文，无截断
+    expect(parts[1]).toBe(expectedEntry(shortOne, "S".repeat(500), 500, 3428));
+    expect(parts[1]).not.toContain("[truncated");
+    // 长条目：统一收紧到同一 effectivePerItem = 3428
+    for (let i = 0; i < 6; i++) {
+      expect(parts[i + 2]).toBe(expectedEntry(longs[i], "A".repeat(6000), 3428, 3428));
+    }
+  });
+
+  it("确定性：同输入同输出；打乱条目顺序不改变各条目自身截断结果", () => {
+    const records = [
+      filled("sa-a", 6000),
+      filled("sa-b", 500), // 短
+      filled("sa-c", 6000),
+      filled("sa-d", 6000),
+      filled("sa-e", 3000),
+      filled("sa-f", 6000),
+      filled("sa-g", 6000),
+    ];
+    const run1 = buildBatchLlmContent(records);
+    const run2 = buildBatchLlmContent(records);
+    expect(run1).toBe(run2); // 同输入同输出
+
+    const entryOf = (content: string, id: string): string =>
+      content.split("\n\n---\n\n").find((p) => p.includes(`(${id})`)) ?? "";
+    const reversed = buildBatchLlmContent([...records].reverse());
+    for (const rec of records) {
+      // 统一收紧与顺序无关：每条目内容在两种排布下逐字节一致
+      expect(entryOf(reversed, rec.id)).toBe(entryOf(run1, rec.id));
+    }
+  });
+
+  it("totalChars 口径：仅计条目正文之和——Σ=23898 < 24000 时包装开销（批头/头行/指针行/分隔符）不触发收紧", () => {
+    // 整条通知实际字节数 ≈ 23898 + 批头 ~60 + 头行 7×~45 + 分隔符 ~80 > 24000，
+    // 但预算判定只看正文和 → 不收紧
+    const records = Array.from({ length: 6 }, (_, i) => filled(`sa-${i}`, 3983));
+    const content = buildBatchLlmContent(records);
+    expect(content.length).toBeGreaterThan(TOTAL); // 整体确实超了 totalChars
+    expect(content).not.toContain("[truncated"); // 却不收紧
+    for (let i = 0; i < 6; i++) {
+      expect(content).toContain("A".repeat(3983)); // 全量正文在场
+    }
+  });
+
+  it("Σ=24000 恰好等于 totalChars：不算超（> 才收紧），6×4000 全量在场零指针行", () => {
+    const records = Array.from({ length: 6 }, (_, i) => filled(`sa-${i}`, 4000));
+    const content = buildBatchLlmContent(records);
+    expect(content).not.toContain("[truncated");
+    const parts = content.split("\n\n---\n\n");
+    for (let i = 0; i < 6; i++) {
+      expect(parts[i + 1]).toBe(expectedEntry(records[i], "A".repeat(4000), 4000, PER_ITEM));
+    }
+  });
+
+  it("失败成员不入正文预算：failed error 全文原样，且不计入 Σ——成功条目 kept=4000 而非收紧 3428", () => {
+    const failedOne = member("sa-bad", { outcome: "failed", error: "boom".repeat(2000) });
+    const longs = Array.from({ length: 6 }, (_, i) => filled(`sa-${i}`, 6000));
+    const records = [failedOne, ...longs];
+    // 成功正文 Σ(per-item 后) = 6×4000 = 24000 ≤ 24000 → 不收紧；若把 failed error
+    //（8000）计入 Σ = 32000 > 24000 → 会收紧至 3428。断言 kept=4000 即锁住口径。
+    const content = buildBatchLlmContent(records);
+    const parts = content.split("\n\n---\n\n");
+    expect(parts[0]).toBe("Subagent batch completed: 6 finished, 1 failed, 0 cancelled.");
+    // failed 条目：error 全文原样、无截断无指针
+    expect(content).toContain(`Subagent "worker-sa-bad" (sa-bad) failed: ${"boom".repeat(2000)}`);
+    const failedPart = parts.find((p) => p.includes("(sa-bad)")) ?? "";
+    expect(failedPart).not.toContain("[truncated");
+    // 成功条目：仅第一段 per-item 截断（kept=4000），未被第二段收紧
+    for (let i = 0; i < 6; i++) {
+      expect(parts).toContain(expectedEntry(longs[i], "A".repeat(6000), 4000, PER_ITEM));
+      expect(content).toContain(pointer(`sa-${i}`, 4000, 6000, PER_ITEM)); // 2,000 of 6,000
+    }
+    expect(content).not.toContain("2,572 of 6,000"); // 3428 收紧形态未出现
+  });
+
+  it("极短 result 的既有形态零回归：不触预算时输出与 U3 基线逐字节一致", () => {
+    const records = [member("sa-1"), member("sa-2")];
+    const content = buildBatchLlmContent(records);
+    expect(content).toBe(
+      [
+        "Subagent batch completed: 2 finished, 0 failed, 0 cancelled.",
+        'Subagent "worker-sa-1" (sa-1) completed. Result:\nresult of sa-1',
+        'Subagent "worker-sa-2" (sa-2) completed. Result:\nresult of sa-2',
+      ].join("\n\n---\n\n"),
+    );
+  });
+});
+
+// ─── C3 指针行 limit 随附（adversarial-review-fixes §3.4 C3）───
+
+describe("buildBatchLlmContent 指针行 limit 随附（C3：预算 > session_read 默认 8000 时附，≤ 不附）", () => {
+  it("perItemChars=12000（>8000）：指针行 JSON 附 \"limit\":12000——模型照抄即取回 ≥ 默认值的有效正文", () => {
+    // 2 成员各 15000：Σ=24000 ≤ totalChars=48000 不收紧 → effectivePerItem = 12000
+    const records = [filled("sa-big", 15000), filled("sa-big2", 15000)];
+    const content = buildBatchLlmContent(records, { perItemChars: 12000, totalChars: 48000 });
+    expect(content).toContain(
+      `[truncated 3,000 of 15,000 chars — full result: session_read {"action":"result","session":"sa-big","limit":12000}]`,
+    );
+    expect(content).toContain(`"session":"sa-big2","limit":12000`);
+  });
+
+  it("perItemChars=4000（默认，≤8000）：指针行无 limit 字段（默认已覆盖，避免噪音）", () => {
+    const records = [filled("sa-a", 5000)];
+    const content = buildBatchLlmContent(records);
+    expect(content).toContain(
+      `[truncated 1,000 of 5,000 chars — full result: session_read {"action":"result","session":"sa-a"}]`,
+    );
+    expect(content).not.toContain(`"limit"`);
+  });
+
+  it("收紧后 effectivePerItem=3428（≤8000）：同样不附 limit——判定看收紧后的实际预算", () => {
+    const records = Array.from({ length: 7 }, (_, i) => filled(`sa-${i}`, 6000));
+    const content = buildBatchLlmContent(records);
+    expect(content).toContain(`"session":"sa-0"}`);
+    expect(content).not.toContain(`"limit"`);
+  });
+});

package/src/execution/__tests__/collect-coordinator-service.test.ts

@@ -0,0 +1,327 @@
+// src/execution/__tests__/collect-coordinator-service.test.ts
+//
+// collectCoordinator 的 service 集成面（subagent-sync-collect U2）：
+//   1. 偏差#4 落点：execute({collect:"sync"}) 的 record 落 collectMode="sync"
+//      （观察者形态：subagent-record entry 落盘产物断言，非 mock record）；
+//   2. notifyComplete 统一路由：sync 成员终态 → 协调器缓冲 → 单成员闭合 → 降级
+//      flush → notifier.notify 收到该成员（观察点：替换 notifier.notify 为 spy，
+//      闭包经 this 运行时读取，替换生效）；
+//   3. async record（无 collect）直通同一 notifier.notify（现状路径字节不变）；
+//   4. 偏差#3 接线：getCollectSyncDefault 读真实 config（缺省 async / 配置 sync +
+//      reloadGlobalConfig 后生效）；
+//   5. flush 屏障时序：manifest 写完成先于 notifyBatch 写账（通知可达 ⇒ 索引就位
+//      的构造性保证，时序竞态修复）。
+//
+// mock 手法对齐 ended-message-and-fork-from.test.ts：mock session-runner（不 spawn
+// 真子进程）+ logger；record-store / config 走真实实现（tmpdir 自建自删，红线）。
+
+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, type Mock } from "vitest";
+
+const { loggerMock, runSpawnMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() },
+  /** runSpawn mock 实例提升：测试内直接引用控制 resolve 时序（不依赖 import 路径解析——
+   *  vi.mock 字符串与本文件既有写法保持一致，mock 实例经 hoisted 闭包共享）。 */
+  runSpawnMock: vi.fn(async () => ({
+    text: "ok",
+    turns: 1,
+    durationMs: 10,
+    success: true,
+    sessionId: "spawned",
+    toolCalls: [],
+  })),
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+// mock session-runner：execute 链经 kickOffBackground → runAndFinalize → runSpawn。
+// runSpawn 返回最小成功 AgentResult，后台收尾链完整走完（finalize + archive + notify）。
+// 路径必须命中生产 import 的真实模块——merge 后 session-runner 落位
+// src/execution/engine/engines/pi/session-runner.ts（subagent-service.ts 的 import 源），
+// 旧路径 "../session-runner.ts" 模块已不存在，拦截静默失效（真 runSpawn 被执行，
+// runSpawnMock.calls 恒 0 → 受控 promise 用例 until 超时）。
+vi.mock("../engine/engines/pi/session-runner.ts", () => ({
+  runSpawn: runSpawnMock,
+  killAllSpawnedChildren: vi.fn(),
+  killRecordChildWithEscalation: vi.fn(),
+  getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  spawnedChildren: new Map(),
+}));
+
+import { getSubagentSessionDir, getSubagentRecordsDir } from "../path-encoding.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelRegistryLike } from "../model-resolver.ts";
+import { SubagentService } from "../subagent-service.ts";
+
+const IDENTITY_ENV_KEYS = [
+  "PI_SUBAGENT_ROOT_SESSION_ID",
+  "PI_SUBAGENT_SELF_RECORD_ID",
+  "PI_SUBAGENT_DEPTH",
+  "PI_SUBAGENT_ROOT_CWD",
+  "PI_SUBAGENT_FORK_DEPTH",
+] as const;
+
+function makePi() {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+    on: vi.fn(),
+  };
+}
+
+interface NotifierSpy {
+  // Mock<T> 而非纯函数签名：测试断言消费 .mock.calls，需保留 mock 元数据
+  notify: Mock<(record: unknown) => void>;
+  /** U3：sync 批投递 spy。mock 返回 true（flushBatch 接线的落标 accepted 分支可达）。 */
+  notifyBatch: Mock<(records: unknown, budget?: unknown) => boolean>;
+}
+
+/** 替换 service 私有 notifier 为仅覆盖 notify/notifyBatch 的 spy（保留其余方法；
+ *  协调器 deps 闭包经 this 运行时读取，替换生效）。 */
+function spyNotifier(service: SubagentService): NotifierSpy {
+  // [D4-① 适配] notifier 实例已封装进 notifyHost（createNotifyHost），spy 改为包装
+  // host 的 notify/notifyBatch 出口（其余方法经 ...host 保留真实现）；协调器 deps
+  // 闭包经 this 运行时读取 service.notifyHost，字段替换即生效。
+  const host = (service as unknown as { notifyHost: object }).notifyHost;
+  const spy: NotifierSpy = { notify: vi.fn(), notifyBatch: vi.fn(() => true) };
+  (service as unknown as { notifyHost: unknown }).notifyHost = {
+    ...host,
+    notify: (record: unknown) => spy.notify(record),
+    notifyBatch: (records: unknown, budget?: unknown) => spy.notifyBatch(records, budget),
+  };
+  return spy;
+}
+
+/**
+ * 异步链等待：手写短轮询（真实 timers）。
+ * 为什么不用 vi.waitFor：vitest 4.1.8 本包环境下 vi.waitFor 对 falsy callback
+ * 立即 resolve 不轮询不超时（sanity 用例实证：waitFor(()=>false,{timeout:100})
+ * resolve(false) 而非 reject）——属测试基建缺陷，与被测链路无关，此处绕开。
+ */
+async function until(cond: () => boolean, timeoutMs = 3000): Promise<void> {
+  const start = Date.now();
+  while (!cond()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`collect-coordinator-service: condition not met within ${timeoutMs}ms`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+describe("collectCoordinator service integration (U2)", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let pi: ReturnType<typeof makePi>;
+
+  beforeEach(() => {
+    for (const k of IDENTITY_ENV_KEYS) delete process.env[k];
+    agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "core-collect-coord-"));
+    fs.mkdirSync(getSubagentSessionDir(agentDir, agentDir), { recursive: true });
+    pi = makePi();
+    service = makeService(pi);
+  });
+
+  afterEach(() => {
+    service.dispose();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  function makeService(piInstance: ReturnType<typeof makePi>): SubagentService {
+    const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+    const modelRegistry: ModelRegistryLike = {
+      getAvailable: () => [],
+      find: () => undefined,
+      hasConfiguredAuth: () => false,
+    };
+    modelService.initModel({
+      sessionId: "root-session-cur",
+      ctxModel: { id: "m", name: "M", provider: "p", reasoning: false },
+      modelRegistry,
+    });
+    const created = new SubagentService({ cwd: agentDir, modelService });
+    created.initSession({ pi: piInstance, sessionId: "root-session-cur" });
+    return created;
+  }
+
+  it("stamps collectMode on the in-memory record visible to the coordinator routing (偏差#4 落点)", async () => {
+    // 注：entry 落盘观察者断言（subagent-record entry 含 collectMode）依赖
+    // record-store.recordToSubagent 投影扩展——U5 领地（偏差登记）；本用例锁
+    // 内存 record 经协调器路由的可见行为：sync 成员终态 → 单成员闭合 → notifyBatch
+    // 批投递（下方用例），async 成员直通。本条记录 execute 链零异常完成。
+    const spy = spyNotifier(service);
+    const handle = await service.execute({ task: "collect me", slug: "collect-me", collect: "sync" });
+    await until(() => spy.notifyBatch.mock.calls.length > 0);
+    expect(handle.subagentId).toMatch(/^sa-/);
+  });
+
+  it("routes a finished sync member into a single-member batch (U3 接线：单成员闭合 → notifyBatch)", async () => {
+    const spy = spyNotifier(service);
+    const handle = await service.execute({ task: "collect me", slug: "collect-me", collect: "sync" });
+    await until(() => spy.notifyBatch.mock.calls.length > 0);
+    // U3 接线后：sync 成员走单条批投递（不再逐条降级 notify）
+    expect(spy.notify).not.toHaveBeenCalled();
+    const batches = spy.notifyBatch.mock.calls.map((c) => c[0] as { id: string }[]);
+    expect(batches).toHaveLength(1);
+    expect(batches[0]!.map((m) => m.id)).toEqual([handle.subagentId]);
+  });
+
+  it("flushBatch accepted=false（幂等拒绝）时不落标：零带 batchFinalized 的 entry", async () => {
+    const spy = spyNotifier(service);
+    spy.notifyBatch.mockReturnValue(false); // 模拟同成员集批已在账（E1 重建重发形态）
+    const handle = await service.execute({ task: "collect me", slug: "collect-me", collect: "sync" });
+    await until(() => spy.notifyBatch.mock.calls.length > 0);
+    expect(handle.subagentId).toMatch(/^sa-/);
+    // 落标出口①绑「写账成功」：accepted=false → 无带 batchFinalized 标记的 subagent-record
+    // entry（register/archive 常规 entry 经 recordToSubagent 投影携带 batchFinalized=
+    // undefined——未离场成员，非 true；U5 投影扩展后缺省键不落值，断言语义不变）
+    const recordEntries = pi.appendEntry.mock.calls
+      .filter((c) => c[0] === "subagent-record")
+      .map((c) => c[1] as Record<string, unknown>);
+    expect(recordEntries.length).toBeGreaterThan(0); // execute 链自身的 register/archive 在场
+    expect(recordEntries.some((d) => d["batchFinalized"] === true)).toBe(false);
+  });
+
+  it("routes an async member through the same notifyAsync path (现状直通)", async () => {
+    const spy = spyNotifier(service);
+    const handle = await service.execute({ task: "plain", slug: "plain" });
+    await until(() => spy.notify.mock.calls.length > 0);
+    const notified = spy.notify.mock.calls.map((c) => c[0] as { id: string });
+    expect(notified.some((n) => n.id === handle.subagentId)).toBe(true);
+  });
+
+  it("getCollectSyncDefault reads real config (偏差#3 接线)", () => {
+    // 无 config.json → 缺省 async
+    expect(service.getCollectSyncDefault()).toBe("async");
+    // 写入 collectSync.default=sync + reload → sync 生效
+    const configPath = path.join(agentDir, "subagents", "config.json");
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify({ version: 1, maxConcurrent: 6, collectSync: { default: "sync" } }),
+      "utf-8",
+    );
+    const modelService = (service as unknown as { modelService: ModelConfigService }).modelService;
+    modelService.reloadGlobalConfig();
+    expect(service.getCollectSyncDefault()).toBe("sync");
+    // E5 坏值回默认：非枚举 → async 兜底
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify({ version: 1, maxConcurrent: 6, collectSync: { default: "immediate" } }),
+      "utf-8",
+    );
+    modelService.reloadGlobalConfig();
+    expect(service.getCollectSyncDefault()).toBe("async");
+  });
+
+  /** 伪造子 session 文件（record-store.test.ts 同款：header + identity + subagent-record
+   *  entry）——落标通路 getFullRecord 冷路径重建的真实文件数据源（mock runSpawn 不产子文件）。 */
+  function writeChildSessionFile(recordId: string, agent: string, result: string): void {
+    const sessionsDir = getSubagentSessionDir(agentDir, agentDir);
+    const ts = new Date(1000).toISOString();
+    const header = JSON.stringify({
+      type: "session", version: 3, id: `sess-${recordId}`, timestamp: ts, cwd: agentDir,
+    });
+    const identity = JSON.stringify({
+      type: "custom", id: "id-1", parentId: null, timestamp: ts,
+      customType: "subagent-identity",
+      data: {
+        id: recordId, agent, mode: "background", task: "collect me", startedAt: 1000,
+        rootSessionId: "root-session-cur", depth: 0,
+      },
+    });
+    const recordEntry = JSON.stringify({
+      type: "custom", id: "id-2", parentId: "id-1", timestamp: ts,
+      customType: "subagent-record",
+      data: {
+        v: 1, id: recordId, agent, task: "collect me", slug: "collect-me",
+        status: "closed", mode: "background", startedAt: 1000,
+        rootSessionId: "root-session-cur", parentRecordId: undefined, depth: 0,
+        endedAt: 2000, turns: 1, totalTokens: 10, model: "prov/m1", thinkingLevel: undefined,
+        eventLog: [], displayItems: [], result,
+      },
+    });
+    fs.writeFileSync(path.join(sessionsDir, `${recordId}.jsonl`), `${header}\n${identity}\n${recordEntry}\n`, "utf-8");
+  }
+
+  const spawnOk = () => ({
+    text: "ok", turns: 1, durationMs: 10, success: true, sessionId: "spawned", toolCalls: [],
+  });
+
+  it("跨轮续累（D2 service 层）：两轮派 2 sync → 闭合时单批 2 成员", async () => {
+    let resolve1!: (v: ReturnType<typeof spawnOk>) => void;
+    let resolve2!: (v: ReturnType<typeof spawnOk>) => void;
+    runSpawnMock.mockImplementationOnce(() => new Promise((res) => { resolve1 = res; }));
+    runSpawnMock.mockImplementationOnce(() => new Promise((res) => { resolve2 = res; }));
+    const spy = spyNotifier(service);
+    const h1 = await service.execute({ task: "t1", slug: "one", collect: "sync" });
+    const h2 = await service.execute({ task: "t2", slug: "two", collect: "sync" });
+    // runSpawn 在 execute 返回后的异步链内才被调用——等两个受控 promise 都构造完
+    await until(() => runSpawnMock.mock.calls.length >= 2);
+
+    // 第一台终态：第二台仍 running → 缓冲不闭合（零投递）
+    resolve1(spawnOk());
+    await new Promise((resolve) => setTimeout(resolve, 50)); // microtask 链排空
+    expect(spy.notifyBatch.mock.calls).toHaveLength(0);
+
+    // 第二台终态：闭合 → 单批 2 成员（含第一台的快照，跨轮续累不丢）
+    resolve2(spawnOk());
+    await until(() => spy.notifyBatch.mock.calls.length > 0);
+    expect(spy.notifyBatch.mock.calls).toHaveLength(1);
+    const batch = spy.notifyBatch.mock.calls[0]![0] as { id: string }[];
+    expect(batch.map((m) => m.id).sort()).toEqual([h1.subagentId, h2.subagentId].sort());
+    expect(spy.notify).not.toHaveBeenCalled();
+  });
+
+  it("batchFinalized 落标（真文件通路）：闭合 flush 写账成功后末条 entry 带标记（E1 排除判据）", async () => {
+    let resolveSpawn!: (v: ReturnType<typeof spawnOk>) => void;
+    runSpawnMock.mockImplementationOnce(() => new Promise((res) => { resolveSpawn = res; }));
+    const spy = spyNotifier(service);
+    const handle = await service.execute({ task: "collect me", slug: "collect-me", collect: "sync" });
+    await until(() => runSpawnMock.mock.calls.length >= 1); // 受控 promise 已构造
+    // 子 session 文件在闭合判定/flush 前就位（真实生产链中 runSpawn 已写好 identity）
+    writeChildSessionFile(handle.subagentId, "/agents/worker.md", "ok");
+    resolveSpawn(spawnOk());
+    await until(() => spy.notifyBatch.mock.calls.length > 0);
+
+    // 观察者形态：主 session 落盘的末条 subagent-record entry 带 batchFinalized=true +
+    // collectMode=sync（reportSubagentRecord 直投影 SubagentRecord，不经 recordToSubagent）。
+    // status 不在此锁：one-shot 成功链走 SP-5 resumable 回退（record 留内存 running 态，
+    // 真实形态），E1 排除判据只依赖 collectMode+batchFinalized 两字段。
+    const marked = pi.appendEntry.mock.calls
+      .filter((c) => c[0] === "subagent-record")
+      .map((c) => c[1] as Record<string, unknown>)
+      .filter((d) => d["id"] === handle.subagentId && d["batchFinalized"] === true);
+    expect(marked).toHaveLength(1);
+    expect(marked[0]?.["collectMode"]).toBe("sync");
+    expect(marked[0]?.["result"]).toBe("ok");
+    expect(marked[0]?.["resumable"]).toBe(true); // SP-5 成功回退态（真链形态保真）
+  });
+
+  it("flush 屏障：manifest 写完成先于 notifyBatch 写账（通知可达 ⇒ 索引就位，构造性保证）", async () => {
+    // 时序竞态修复（v2 D1 修订）：批通知路径的 manifest 写从「写账后 fire-and-forget」
+    // 前移为「写账前 await 全部落盘」屏障——「通知可达 ⇒ 索引就位」从大概率成立升为
+    // 构造性保证（by construction）。断言打在 notifyBatch（写账入口）被调用的时刻：
+    // 磁盘上 records/<sa-id>.json 必已存在（修复前该时刻大概率 false，探针实测 mtime
+    // 相对 notify entry ±2/3ms 方向不定）。
+    let resolveSpawn!: (v: ReturnType<typeof spawnOk>) => void;
+    runSpawnMock.mockImplementationOnce(() => new Promise((res) => { resolveSpawn = res; }));
+    const spy = spyNotifier(service);
+    const handle = await service.execute({ task: "collect me", slug: "collect-me", collect: "sync" });
+    await until(() => runSpawnMock.mock.calls.length >= 1); // 受控 promise 已构造
+    writeChildSessionFile(handle.subagentId, "/agents/worker.md", "ok");
+    const manifestPath = path.join(getSubagentRecordsDir(agentDir, agentDir), `${handle.subagentId}.json`);
+    // 写账时刻钩子：mock 内联捕获 manifest 存在性（此刻即指针行消费可用性）
+    let manifestExistsAtLedgerWrite = false;
+    spy.notifyBatch.mockImplementation(() => {
+      manifestExistsAtLedgerWrite = fs.existsSync(manifestPath);
+      return true;
+    });
+    resolveSpawn(spawnOk());
+    await until(() => spy.notifyBatch.mock.calls.length > 0);
+    expect(manifestExistsAtLedgerWrite).toBe(true);
+  });
+});