@zhushanwen/subagent-core 0.5.1 → 0.6.0

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

@@ -0,0 +1,371 @@
+// src/execution/__tests__/collect-coordinator.test.ts
+//
+// collectCoordinator 单测（subagent-sync-collect U2）：全依赖注入，fake flush 断言
+//   1. async 路由字节不变语义：notifyAsync 直通同一 record，协调器零改写（G3/A5）；
+//   2. sync 登记 + 闭合检测：缓冲非空 && 无非终态 sync（⛔3 非终态口径，池排队恒
+//      running 自动等待）→ flushBatch 收全部快照、缓冲清空；
+//   3. 跨轮续累（D2 隐式批）：分两轮派 2+1 sync 仍同一 pending 集（单批三成员）；
+//   4. cancel / watchdog（orphan 类）终态入 pending（设计 E3/E6）。
+//
+// [U8 拆批修复] 闭合满足 → setTimeout(0) 同宏任务去抖合批 flush（非立即）——背靠背
+//   route（终态已落 store、notifyComplete 尚在 finalize 链间隙）一并入批；武装后
+//   flush 异步到期，断言投递面/缓冲清空前须 await settleFlush() 开窗。
+//
+// 纯注入测试：无文件 IO、无真实 service——service 集成面见 collect-coordinator-service.test.ts。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { COLLECT_SCAN_LIMIT, CollectCoordinator } from "../collect-coordinator.ts";
+import type { CollectCoordinatorDeps } from "../collect-coordinator.ts";
+import type { BgNotifyRecord } from "../notifier.ts";
+import type { ExecutionRecord, SubagentRecord } from "../types.ts";
+
+// ── stub 工厂 ──
+
+function makeRec(over: Partial<ExecutionRecord> = {}): ExecutionRecord {
+  return {
+    id: "sa-1",
+    agent: "/home/u/agents/worker.md",
+    model: "prov/m1",
+    thinkingLevel: undefined,
+    mode: "background",
+    task: "t",
+    slug: "worker",
+    startedAt: 1000,
+    rootSessionId: "root-A",
+    parentRecordId: undefined,
+    depth: 0,
+    status: "closed",
+    turns: [],
+    turnCount: 1,
+    totalTokens: 10,
+    lastError: undefined,
+    endedAt: 2000,
+    result: "done",
+    error: undefined,
+    agentResult: undefined,
+    controller: undefined,
+    ...over,
+  } as ExecutionRecord;
+}
+
+function makeSnapshot(id: string, over: Partial<BgNotifyRecord> = {}): BgNotifyRecord {
+  return {
+    id,
+    status: "closed",
+    agent: "/home/u/agents/worker.md",
+    model: "prov/m1",
+    result: `result of ${id}`,
+    startedAt: 1000,
+    endedAt: 2000,
+    ...over,
+  };
+}
+
+/** store 枚举 stub：listRecords 返回的 SubagentRecord 形态（协调器闭合判定输入）。 */
+function makeStoreRec(over: Partial<SubagentRecord> = {}): SubagentRecord {
+  return {
+    id: "sa-1",
+    agent: "/home/u/agents/worker.md",
+    task: "t",
+    slug: "worker",
+    status: "closed",
+    mode: "background",
+    startedAt: 1000,
+    rootSessionId: "root-A",
+    parentRecordId: undefined,
+    depth: 0,
+    endedAt: 2000,
+    turns: 1,
+    totalTokens: 10,
+    model: "prov/m1",
+    thinkingLevel: undefined,
+    eventLog: [],
+    displayItems: [],
+    ...over,
+  } as SubagentRecord;
+}
+
+interface Harness {
+  coordinator: CollectCoordinator;
+  notifyAsync: ReturnType<typeof vi.fn>;
+  toNotifyRecord: ReturnType<typeof vi.fn>;
+  listRecords: ReturnType<typeof vi.fn>;
+  flushBatch: ReturnType<typeof vi.fn>;
+}
+
+function makeHarness(storeRecords: SubagentRecord[] = []): Harness {
+  const notifyAsync = vi.fn();
+  // toNotifyRecord stub：从 record 透传终态语义字段（closedReason/error/result），
+  // 与 service.toNotifyRecord 的投影语义对齐。
+  const toNotifyRecord = vi.fn((record: ExecutionRecord) =>
+    makeSnapshot(record.id, {
+      closedReason: record.closedReason,
+      error: record.error,
+      result: record.result,
+    }),
+  );
+  const listRecords = vi.fn(() => storeRecords);
+  const flushBatch = vi.fn();
+  const coordinator = new CollectCoordinator({
+    notifyAsync,
+    toNotifyRecord,
+    listRecords,
+    flushBatch,
+  } satisfies CollectCoordinatorDeps);
+  return { coordinator, notifyAsync, toNotifyRecord, listRecords, flushBatch };
+}
+
+/** [U8 拆批修复] 闭合合批排程窗口等待：flush 排程 = setTimeout(0)（Node 1ms clamp），
+ *  10ms 真实定时器保证窗口已开（本包 vitest 真实 timers 环境）。 */
+async function settleFlush(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 10));
+}
+
+// ============================================================
+// async 路由（字节不变语义）
+// ============================================================
+
+describe("CollectCoordinator async routing", () => {
+  it("routes records without collectMode straight to notifyAsync (直通同一 record)", () => {
+    const h = makeHarness();
+    const record = makeRec({ id: "sa-async" });
+    expect(h.coordinator.route(record)).toBe("async");
+    expect(h.notifyAsync).toHaveBeenCalledTimes(1);
+    expect(h.notifyAsync).toHaveBeenCalledWith(record);
+    expect(h.flushBatch).not.toHaveBeenCalled();
+    expect(h.coordinator.pendingCount).toBe(0);
+  });
+
+  it("routes chatMode records async (对话回流不入批，D8)", () => {
+    const h = makeHarness();
+    const record = makeRec({ id: "sa-chat", chatMode: true });
+    expect(h.coordinator.route(record)).toBe("async");
+    expect(h.notifyAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it("scan limit is 1000 (与 service 冷路径同量级)", () => {
+    expect(COLLECT_SCAN_LIMIT).toBe(1000);
+  });
+});
+
+// ============================================================
+// sync 登记 + 闭合检测
+// ============================================================
+
+describe("CollectCoordinator sync buffering + closure", () => {
+  it("buffers a finished sync member while another sync member is still running", () => {
+    // store：sa-2 仍在跑（非终态）→ sa-1 终态入缓冲不闭合
+    const h = makeHarness([
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+      makeStoreRec({ id: "sa-2", collectMode: "sync", status: "running" }),
+    ]);
+    const result = h.coordinator.route(makeRec({ id: "sa-1", collectMode: "sync" }));
+    expect(result).toBe("sync-buffered");
+    expect(h.coordinator.pendingCount).toBe(1);
+    expect(h.flushBatch).not.toHaveBeenCalled();
+  });
+
+  it("flushes the whole buffer when the last running sync member finishes", async () => {
+    // 时序：sa-1 先终态（sa-2 仍 running → 入缓冲）；sa-2 最后终态（store 全 closed）
+    // → 闭合 flush 两成员。
+    let sa2Running = true;
+    const storeRecords = (): SubagentRecord[] => [
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+      makeStoreRec({ id: "sa-2", collectMode: "sync", status: sa2Running ? "running" : "closed" }),
+    ];
+    const h = makeHarness();
+    (h as { listRecords: ReturnType<typeof vi.fn> }).listRecords.mockImplementation(storeRecords);
+    expect(h.coordinator.route(makeRec({ id: "sa-1", collectMode: "sync" }))).toBe("sync-buffered");
+    sa2Running = false;
+    expect(h.coordinator.route(makeRec({ id: "sa-2", collectMode: "sync" }))).toBe("sync-flushed");
+    await settleFlush();
+    expect(h.flushBatch).toHaveBeenCalledTimes(1);
+    const members = h.flushBatch.mock.calls[0]?.[0] as BgNotifyRecord[];
+    expect(members.map((m) => m.id)).toEqual(["sa-1", "sa-2"]);
+    expect(h.coordinator.pendingCount).toBe(0);
+  });
+
+  it("a lone sync member flushes via the coalescing window (单成员即闭合)", async () => {
+    const h = makeHarness([
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+    ]);
+    const result = h.coordinator.route(makeRec({ id: "sa-1", collectMode: "sync" }));
+    expect(result).toBe("sync-flushed");
+    await settleFlush();
+    expect(h.flushBatch).toHaveBeenCalledTimes(1);
+  });
+
+  it("back-to-back routes in one macrotask coalesce into ONE flush (U8 拆批盲窗回归)", async () => {
+    // 盲窗精确形态：A/B 均已 archive（listAllActive 扫描恒空——终态已落 store 但
+    // B 的 notifyComplete 尚在 finalize 链间隙）。修复前：route(A) 闭合立即 flush([A])，
+    // route(B) 再 flush([B]) → 两条单成员批；修复后：同宏任务去抖窗口把 B 并入，
+    // 单批两成员一次投递。
+    const h = makeHarness([]); // store 空 = 双成员均已 archive（盲窗扫描视图）
+    expect(h.coordinator.route(makeRec({ id: "sa-a", collectMode: "sync" }))).toBe("sync-flushed");
+    expect(h.coordinator.route(makeRec({ id: "sa-b", collectMode: "sync" }))).toBe("sync-flushed");
+    await settleFlush();
+    expect(h.flushBatch).toHaveBeenCalledTimes(1);
+    const members = h.flushBatch.mock.calls[0]?.[0] as BgNotifyRecord[];
+    expect(members.map((m) => m.id)).toEqual(["sa-a", "sa-b"]);
+    expect(h.coordinator.pendingCount).toBe(0);
+  });
+
+  it("cancelScheduledFlush drops the pending window and keeps the buffer (E9 dispose 语义)", async () => {
+    // dispose 到来时挂起排程取消、缓冲原样保留（convertPendingSyncBufferToAsync
+    // 仍读得到全部成员转 async）——service 侧 E9 交互的单元级前置。
+    const h = makeHarness([
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+    ]);
+    expect(h.coordinator.route(makeRec({ id: "sa-1", collectMode: "sync" }))).toBe("sync-flushed");
+    h.coordinator.cancelScheduledFlush();
+    await settleFlush();
+    expect(h.flushBatch).not.toHaveBeenCalled();
+    expect(h.coordinator.pendingCount).toBe(1);
+    expect(h.coordinator.pendingMembers().map((m) => m.id)).toEqual(["sa-1"]);
+  });
+
+  it("pool-queued sync members (status=running) block closure (⛔3 非终态口径)", () => {
+    // sa-2 在池排队：store.register 起即 status=running（无独立排队态）→ 阻止闭合
+    const h = makeHarness([
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+      makeStoreRec({ id: "sa-2", collectMode: "sync", status: "running" }),
+    ]);
+    const result = h.coordinator.route(makeRec({ id: "sa-1", collectMode: "sync" }));
+    expect(result).toBe("sync-buffered");
+    expect(h.flushBatch).not.toHaveBeenCalled();
+  });
+
+  it("batchFinalized members do not block closure (已离场成员)", async () => {
+    const h = makeHarness([
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+      makeStoreRec({ id: "sa-2", collectMode: "sync", status: "closed", batchFinalized: true }),
+    ]);
+    const result = h.coordinator.route(makeRec({ id: "sa-1", collectMode: "sync" }));
+    expect(result).toBe("sync-flushed");
+    await settleFlush();
+    expect(h.flushBatch).toHaveBeenCalledTimes(1);
+  });
+
+  it("async records never block sync closure (混派正交，A8 前置)", async () => {
+    const h = makeHarness([
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+      makeStoreRec({ id: "sa-async", status: "running" }), // 无 collectMode：async 在跑
+    ]);
+    const result = h.coordinator.route(makeRec({ id: "sa-1", collectMode: "sync" }));
+    expect(result).toBe("sync-flushed");
+    await settleFlush();
+    expect(h.flushBatch).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips buffering when toNotifyRecord returns undefined (gate 未过，与 async 静默跳过对称)", () => {
+    const notifyAsync = vi.fn();
+    const toNotifyRecord = vi.fn(() => undefined);
+    const listRecords = vi.fn(() => [] as SubagentRecord[]);
+    const flushBatch = vi.fn();
+    const coordinator = new CollectCoordinator({ notifyAsync, toNotifyRecord, listRecords, flushBatch });
+    const result = coordinator.route(makeRec({ id: "sa-x", collectMode: "sync" }));
+    expect(result).toBe("sync-skipped");
+    expect(coordinator.pendingCount).toBe(0);
+    expect(flushBatch).not.toHaveBeenCalled();
+  });
+});
+
+// ============================================================
+// 跨轮续累（D2 隐式批：2+1 同一 pending 集）
+// ============================================================
+
+describe("CollectCoordinator cross-turn accumulation (D2)", () => {
+  it("accumulates 2+1 sync starts across two turns into ONE flush batch", async () => {
+    // round1 派 A、B；round2 派 C。终态时序：A → C → B（B 最后闭合）。
+    // store 枚举由「谁还活着」驱动：闭合只看非终态 sync 是否清零。
+    let running = new Set(["sa-b"]);
+    const storeRecords = (): SubagentRecord[] =>
+      [...running].map((id) => makeStoreRec({ id, collectMode: "sync", status: "running" }));
+    const notifyAsync = vi.fn();
+    const toNotifyRecord = vi.fn((record: ExecutionRecord) => makeSnapshot(record.id));
+    const listRecords = vi.fn(() => storeRecords());
+    const flushBatch = vi.fn();
+    const coordinator = new CollectCoordinator({ notifyAsync, toNotifyRecord, listRecords, flushBatch });
+
+    // round1：A 终态（B 仍在跑）→ 缓冲 [A]
+    expect(coordinator.route(makeRec({ id: "sa-a", collectMode: "sync" }))).toBe("sync-buffered");
+    expect(coordinator.pendingMembers().map((m) => m.id)).toEqual(["sa-a"]);
+
+    // round2：派 C（跨轮续累——同一 pending 集）；C 终态（B 仍在跑）→ 缓冲 [A, C]
+    expect(coordinator.route(makeRec({ id: "sa-c", collectMode: "sync" }))).toBe("sync-buffered");
+    expect(coordinator.pendingMembers().map((m) => m.id)).toEqual(["sa-a", "sa-c"]);
+
+    // B 终态（先从 running 集移除 = 终态落 store）→ 闭合：单批三成员（2+1 同一批）
+    running.delete("sa-b");
+    expect(coordinator.route(makeRec({ id: "sa-b", collectMode: "sync" }))).toBe("sync-flushed");
+    await settleFlush();
+    expect(flushBatch).toHaveBeenCalledTimes(1);
+    const members = flushBatch.mock.calls[0]?.[0] as BgNotifyRecord[];
+    expect(members.map((m) => m.id).sort()).toEqual(["sa-a", "sa-b", "sa-c"]);
+    expect(coordinator.pendingCount).toBe(0);
+  });
+
+  it("starts a fresh batch after a flush (闭合后新派开新批)", async () => {
+    // sa-2 在跑（阻止闭合）：sa-1 终态入缓冲；sa-2 终态闭合后，新派 sa-3 终态开新批。
+    const store: SubagentRecord[] = [
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+      makeStoreRec({ id: "sa-2", collectMode: "sync", status: "running" }),
+    ];
+    const h = makeHarness();
+    (h as { listRecords: ReturnType<typeof vi.fn> }).listRecords.mockImplementation(() => store);
+    expect(h.coordinator.route(makeRec({ id: "sa-1", collectMode: "sync" }))).toBe("sync-buffered");
+    store[1] = makeStoreRec({ id: "sa-2", collectMode: "sync", status: "closed" });
+    expect(h.coordinator.route(makeRec({ id: "sa-2", collectMode: "sync" }))).toBe("sync-flushed");
+    await settleFlush(); // 第一批投出（合批窗口开）
+    // 闭合后新 sync 终态 → 新批缓冲（不复活旧成员）：store 无 running sync → 但
+    // 缓冲非空在先入时判定，route(sa-3) 时缓冲空 + 无 running → 闭合开新批排程
+    expect(h.coordinator.route(makeRec({ id: "sa-3", collectMode: "sync" }))).toBe("sync-flushed");
+    await settleFlush();
+    expect(h.coordinator.pendingMembers().map((m) => m.id)).toEqual([]);
+    expect(h.flushBatch).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ============================================================
+// cancel / watchdog（orphan 类）终态入 pending（E3/E6）
+// ============================================================
+
+describe("CollectCoordinator cancel/watchdog terminal states enter the batch", () => {
+  it("routes a cancelled sync member into the buffer (E6：cancel 计入批)", async () => {
+    const h = makeHarness([
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+    ]);
+    const record = makeRec({
+      id: "sa-1",
+      collectMode: "sync",
+      status: "closed",
+      closedReason: "cancelled",
+      result: "",
+      error: "cancelled by user",
+    });
+    expect(h.coordinator.route(record)).toBe("sync-flushed");
+    await settleFlush();
+    const members = h.flushBatch.mock.calls[0]?.[0] as BgNotifyRecord[];
+    expect(members).toHaveLength(1);
+    expect(members[0]?.closedReason).toBe("cancelled");
+  });
+
+  it("routes a watchdog/gc-failed sync member into the buffer (E3：orphan 类终态计入批)", async () => {
+    const h = makeHarness([
+      makeStoreRec({ id: "sa-1", collectMode: "sync", status: "closed" }),
+    ]);
+    const record = makeRec({
+      id: "sa-1",
+      collectMode: "sync",
+      status: "closed",
+      closedReason: "gc",
+      result: "",
+      error: "settled watchdog timeout",
+    });
+    expect(h.coordinator.route(record)).toBe("sync-flushed");
+    await settleFlush();
+    const members = h.flushBatch.mock.calls[0]?.[0] as BgNotifyRecord[];
+    expect(members[0]?.error).toBe("settled watchdog timeout");
+  });
+});

package/src/execution/__tests__/collect-mixed-dispatch.test.ts

@@ -0,0 +1,262 @@
+// src/execution/__tests__/collect-mixed-dispatch.test.ts
+//
+// A8 混派正交 service 级 e2e（subagent-sync-collect U8；设计 §4 A8 验收行 /
+// §3.1.4 数据流）：**同轮** 2 个 collect:"sync" + 1 个 async（不传 collect）全部经
+// SubagentService.execute 真链（mock 仅 session-runner 的 runSpawn——时序受控终态，
+// 与 collect-coordinator-service.test.ts 同手法）。
+//
+// 与协调器层既有覆盖（collect-coordinator.test.ts "async records never block sync
+// closure" / notify-batch.test.ts "混派正交"）的差异：那两层 stub 了 notifyAsync /
+// toNotifyRecord / listRecords；本文件走 service.execute 全链（record 落 collectMode →
+// kickOffBackground → runAndFinalize → notifyComplete → 协调器真路由 → notifier 真
+// spy），锁「同轮混派」在真实投递接线下的两个方向：
+//   1. async 成员先终态：立即走 notify 直通（不被 sync 批扣留），批零投递；
+//      随后 sync 成员逐个终态 → 恰 1 次 notifyBatch、成员恰为 2 个 sync id；
+//   2. sync 批先闭合（async 仍在跑）：两个 sync 背靠背紧窗口终态（U8 拆批盲窗的
+//      精确复现形态）→ 去抖合批单批 flush 不等 async；随后 async 终态才收到
+//      自己的单条 notify。
+//
+// 三视角（TEST-STRATEGY §3）：
+//   - 使用者黑盒：派发方可见形态 = async 通知即时到达、sync 结果合并为单条批；
+//   - 构建者白盒：协调器路由去向 + notifier spy 调用面；
+//   - 观察者形态：pi.appendEntry 落盘的 subagent-record entry（collectMode 标记）。
+
+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() },
+  runSpawnMock: vi.fn(async () => ({
+    text: "ok",
+    turns: 1,
+    durationMs: 10,
+    success: true,
+    sessionId: "spawned",
+    toolCalls: [],
+  })),
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+// mock 路径自检（impl-plan 偏差 #6 教训）：从 __tests__ 解析必须命中生产 import 的
+// 真实模块——merge 后 session-runner 落位 src/execution/engine/engines/pi/session-runner.ts
+//（subagent-service.ts 的 import 源），旧路径 "../session-runner.ts" 模块已不存在，
+// 拦截静默失效（真 runSpawn 被执行，runSpawnMock.calls 恒 0 → 受控 promise 用例超时）。
+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 } 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>;
+  notifyBatch: Mock<(records: unknown, budget?: unknown) => boolean>;
+}
+
+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;
+}
+
+/** 手写短轮询（本包 vitest 4.1.8 环境 vi.waitFor 失效——impl-plan §7 环境注意）。 */
+async function until(cond: () => boolean, timeoutMs = 3000): Promise<void> {
+  const start = Date.now();
+  while (!cond()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`collect-mixed-dispatch: condition not met within ${timeoutMs}ms`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+const spawnOk = () => ({
+  text: "ok",
+  turns: 1,
+  durationMs: 10,
+  success: true,
+  sessionId: "spawned",
+  toolCalls: [],
+});
+
+/** 受控 runSpawn：每次调用挂起返回 resolver，测试按成员序号放行终态。
+ *  resolver 在 runSpawn 实际调用时（execute 异步链内）才构造——release 函数按
+ *  索引延迟取用，不能在挂起注册时立刻闭包捕获（彼时尚为 undefined）。 */
+function controlledSpawns(n: number): Array<(v?: ReturnType<typeof spawnOk>) => void> {
+  const resolvers: Array<(v: ReturnType<typeof spawnOk>) => void> = [];
+  for (let i = 0; i < n; i += 1) {
+    runSpawnMock.mockImplementationOnce(
+      () =>
+        new Promise((res) => {
+          resolvers[i] = res;
+        }),
+    );
+  }
+  return Array.from({ length: n }, (_, i) => (v?: ReturnType<typeof spawnOk>) =>
+    resolvers[i]!(v ?? spawnOk()),
+  );
+}
+
+describe("A8 混派正交 service e2e（同轮 2 sync + 1 async，U8）", () => {
+  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-mixed-dispatch-"));
+    fs.mkdirSync(getSubagentSessionDir(agentDir, agentDir), { recursive: true });
+    pi = makePi();
+    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,
+    });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    service.initSession({ pi, sessionId: "root-session-cur" });
+  });
+
+  afterEach(() => {
+    service.dispose();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("async 先终态：即时直通 notify（不被 sync 批扣留）→ sync 逐个终态 → 恰 1 批 2 成员", async () => {
+    const spy = spyNotifier(service);
+    // 同轮三连派发：2 sync + 1 async（派发顺序 sync, sync, async——同一条消息内的
+    // 混派形态；runSpawn 调用序与 execute 序一致）
+    const [doneSync1, doneSync2, doneAsync] = controlledSpawns(3);
+    const hSync1 = await service.execute({ task: "s1", slug: "sync-one", collect: "sync" });
+    const hSync2 = await service.execute({ task: "s2", slug: "sync-two", collect: "sync" });
+    const hAsync = await service.execute({ task: "a1", slug: "async-one" });
+    await until(() => runSpawnMock.mock.calls.length >= 3); // 三个受控 promise 均已构造
+
+    // async 成员先终态：立即单条 notify（现状路径），批零投递、零扣留
+    doneAsync();
+    await until(() => spy.notify.mock.calls.length > 0);
+    expect(spy.notifyBatch).not.toHaveBeenCalled();
+    expect(spy.notify.mock.calls).toHaveLength(1);
+    expect((spy.notify.mock.calls[0]![0] as { id: string }).id).toBe(hAsync.subagentId);
+
+    // sync-1 终态：sync-2 仍 running → 缓冲不闭合（async 通知不重复）
+    doneSync1();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(spy.notifyBatch).not.toHaveBeenCalled();
+    expect(spy.notify.mock.calls).toHaveLength(1);
+
+    // sync-2 终态：闭合 → 恰 1 次批投递，成员恰为 2 个 sync id（async 不入批）
+    doneSync2();
+    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([hSync1.subagentId, hSync2.subagentId].sort());
+    // async 通知面恒 1（批闭合不重发 async）
+    expect(spy.notify.mock.calls).toHaveLength(1);
+  });
+
+  it("sync 批先闭合（async 仍在跑）：背靠背紧窗口合批单批；async 随后独立单条 notify", async () => {
+    const spy = spyNotifier(service);
+    const [doneSync1, doneSync2, doneAsync] = controlledSpawns(3);
+    const hSync1 = await service.execute({ task: "s1", slug: "sync-one", collect: "sync" });
+    const hSync2 = await service.execute({ task: "s2", slug: "sync-two", collect: "sync" });
+    const hAsync = await service.execute({ task: "a1", slug: "async-one" });
+    await until(() => runSpawnMock.mock.calls.length >= 3);
+
+    // 两个 sync 同步段背靠背终态（窄于 finalize 链宽度——U8 拆批盲窗的精确复现形态：
+    // 先 archive 的成员 route 时，后者的 notifyComplete 尚在 finalize 链间隙，闭合
+    // 扫描看不见）。协调器去抖合批窗口把间隙内 route 的成员并入同一批：修复前此处
+    // 产出 [["sa-1"],["sa-2"]] 两条单成员批，修复后稳定单批（50ms 错峰 workaround
+    // 已移除——本用例即拆批盲窗的回归守卫）。
+    doneSync1();
+    doneSync2();
+    await until(() => spy.notifyBatch.mock.calls.length > 0);
+    expect(spy.notifyBatch).toHaveBeenCalledTimes(1);
+    const batch = spy.notifyBatch.mock.calls[0]![0] as { id: string }[];
+    expect(batch.map((m) => m.id).sort()).toEqual([hSync1.subagentId, hSync2.subagentId].sort());
+    // async 未终态：批闭合不产生 async 通知
+    expect(spy.notify).not.toHaveBeenCalled();
+
+    // async 随后终态：独立单条 notify（与批互不串扰）
+    doneAsync();
+    await until(() => spy.notify.mock.calls.length > 0);
+    expect(spy.notify.mock.calls).toHaveLength(1);
+    expect((spy.notify.mock.calls[0]![0] as { id: string }).id).toBe(hAsync.subagentId);
+    expect(spy.notifyBatch).not.toHaveBeenCalledTimes(2);
+  });
+
+  it("观察者形态：同轮混派三 record 的落盘 entry 各自携带正确 collectMode", async () => {
+    const spy = spyNotifier(service);
+    const [, , doneAsync] = controlledSpawns(3);
+    const hSync1 = await service.execute({ task: "s1", slug: "sync-one", collect: "sync" });
+    const hSync2 = await service.execute({ task: "s2", slug: "sync-two", collect: "sync" });
+    const hAsync = await service.execute({ task: "a1", slug: "async-one" });
+    await until(() => runSpawnMock.mock.calls.length >= 3);
+    doneAsync();
+    await until(() => spy.notify.mock.calls.length > 0);
+    // 批不必闭合即可断言落盘（register 期 entry 即带 collectMode）：
+    // sync 成员 entry 带 collectMode:"sync"，async 成员 entry 无该键（缺省 async）
+    const entriesBy = (id: string) =>
+      pi.appendEntry.mock.calls
+        .filter((c) => c[0] === "subagent-record")
+        .map((c) => c[1] as Record<string, unknown>)
+        .filter((d) => d["id"] === id);
+    expect(entriesBy(hSync1.subagentId).some((d) => d["collectMode"] === "sync")).toBe(true);
+    expect(entriesBy(hSync2.subagentId).some((d) => d["collectMode"] === "sync")).toBe(true);
+    expect(
+      entriesBy(hAsync.subagentId).every((d) => !("collectMode" in d) || d["collectMode"] === undefined),
+    ).toBe(true);
+  });
+});
+
+// 【已知盲窗·已修复（U8 授权修复轮）】背靠背拆批竞态（机理回顾：runAndFinalize 的
+// completeRecord+archive 先于 .then 链 notifyComplete，成员 B 已终态归档但未路由时
+// A 的闭合检测看不到 B → flush([A])，随后 B route 再 flush([B])）已在
+// collect-coordinator.ts 落地修复：闭合首次满足不立即 flush，改 setTimeout(0)
+// 同宏任务去抖合批——排程窗口内新 route（finalize 链间隙的成员）并入缓冲后一并
+// flush；触发时重验闭合条件（窗口内新 running 反转则留缓冲等其终态重排程）。
+// E9 交互：dispose 经 convertPendingSyncBufferToAsync 先 cancelScheduledFlush
+//（取消而非同步 flush——放任触发会与逐条转 async 写账双通道并发 → 双投递），缓冲
+// 原样保留供转换；E1 无交集（session_start 时点排程必已被取消，补发直走 notifyBatch，
+// 账本 sync-batch:<hash> 幂等兑底）。上方第二用例已改回背靠背紧窗口断言作回归守卫。