@zhushanwen/subagent-core 0.6.0 → 0.7.1

package/src/execution/__tests__/chat-round-first-round-watchdog.test.ts

@@ -0,0 +1,255 @@
+// src/execution/__tests__/chat-round-first-round-watchdog.test.ts
+//
+// [F-2 修复] 首轮/冷续轮 settled-watchdog arm 重接 + [F-5 修复] chat 轮路由终态化注销。
+//
+// 背景：armMidRoundNoProgress 此前唯一调用点在 deliverChatMessage（热路径续聊轮）；
+// kickOffChatRound（spawn 首轮 + 冷续 resume 轮）内无任何 arm——被删的 inproc
+// stdout-pump 是首轮唯一中段守护，协议化后引擎侧 spawn-runner 仅 turn 计数无墙钟，
+// 首轮 wedged（LC-1 场景①：无事件行输出）无任何熔断。修复 = run 派发前补 arm
+//（refresh 源 = runId 键 ctx.onEvent 事件行 + ctx.onRoundLifecycle settled 交棒——
+// 引擎侧 spawn-runner 对 text_delta 同时走 onEvent 与 onDelta，刷新面与热路径等效）。
+//
+// [F-5] chat 轮路由（chatRoundRoutes）此前仅 cancelBackground 注销；finalize 链终态化
+// （closeChatIdle / closeAfterRoundSettled / finalizeRecord）不注销 → 路由闭包持
+// record/stream/守护引用泄漏。修复 = doFinalizeRecord 的 onFinalized 钩子单一汇聚点。
+//
+// 替身形态与 subagent-service-recovery-bounds.test.ts 同源（fake-engine-port 协议 seam）。
+
+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";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+const { killChildSpy } = vi.hoisted(() => ({ killChildSpy: vi.fn() }));
+vi.mock("../engine/host/spawned-children.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../engine/host/spawned-children.ts")>();
+  return { ...actual, killRecordChildWithEscalation: killChildSpy };
+});
+
+import { clearEngines } from "../engine/registry.ts";
+import { registerFakePiEngine, type FakePiEnginePort } from "./helpers/fake-engine-port.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
+import type { RecordStore } from "../record-store.ts";
+import { SubagentService } from "../subagent-service.ts";
+import type { PiLike } from "../subagent-service.ts";
+import {
+  getSettledWatchdogPhase,
+  hasSettledWatchdog,
+  SETTLED_MID_ROUND_NO_PROGRESS_MS,
+  SETTLED_WATCHDOG_TIMEOUT_MS,
+  _resetSettledWatchdogsForTest,
+} from "../settled-watchdog.ts";
+import { _resetLifecycleState } from "../lifecycle-manager.ts";
+import { _resetCoreSpawnedChildrenMirrorForTest } from "../engine/host/spawned-children.ts";
+import type { ExecutionRecord } from "../types.ts";
+
+function makePi(): PiLike {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  } as unknown as PiLike;
+}
+
+interface ServiceInternals {
+  store: RecordStore;
+}
+
+const CTX_MODEL: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: false };
+
+function makeEmptyRegistry(): ModelRegistryLike {
+  return { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => true };
+}
+
+function setup(): { agentDir: string; service: SubagentService; store: RecordStore; pi: PiLike; fake: FakePiEnginePort } {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "chat-round-watchdog-"));
+  clearEngines();
+  const fake = registerFakePiEngine();
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+  modelService.initModel({ modelRegistry: makeEmptyRegistry(), sessionId: "root-session", ctxModel: CTX_MODEL });
+  const service = new SubagentService({ cwd: agentDir, modelService });
+  const pi = makePi();
+  service.initSession({ pi, sessionId: "root-session" });
+  const store = (service as unknown as ServiceInternals).store;
+  return { agentDir, service, store, pi, fake };
+}
+
+/** 模拟 kickOffChatRound 的路由注册面（Service map + fake 引擎两端同挂）。 */
+function registerRoute(service: SubagentService, fake: FakePiEnginePort, recordId: string): void {
+  const unregister = fake.registerChatRoundRoute(recordId, {
+    onStreamDelta: () => {},
+    onRoundLifecycle: () => {},
+  });
+  (
+    service as unknown as { chatRoundRoutes: Map<string, () => void> }
+  ).chatRoundRoutes.set(recordId, unregister);
+}
+
+function makeChatRecord(id: string): ExecutionRecord {
+  return createRecord(id, {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "background",
+    task: "test",
+    slug: "test",
+    startedAt: 1000,
+    rootSessionId: "root-session",
+    chatMode: true,
+    controller: new AbortController(),
+  });
+}
+
+describe("[F-2] 首轮/冷续轮 settled-watchdog arm（kickOffChatRound run 派发点）", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+  let pi: PiLike;
+  let fake: FakePiEnginePort;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    killChildSpy.mockClear();
+    ({ agentDir, service, store, pi, fake } = setup());
+  });
+
+  afterEach(() => {
+    service.dispose();
+    clearEngines();
+    vi.useRealTimers();
+    _resetLifecycleState();
+    _resetSettledWatchdogsForTest();
+    _resetCoreSpawnedChildrenMirrorForTest();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("首轮 run 派发后中段守护 armed（修复前首轮无任何守护）", async () => {
+    const handle = await service.execute({ task: "first round", slug: "t", ctxModel: CTX_MODEL, conversation: true });
+    expect(fake.runs).toHaveLength(1);
+    expect(hasSettledWatchdog(handle.subagentId)).toBe(true);
+    expect(getSettledWatchdogPhase(handle.subagentId)).toBe("mid-round");
+  });
+
+  it("冷续轮进行中无产出 → 中段守护按既有超时语义触发：kill + 引擎 cancel + 回退 idle-resumable（fake timers）", async () => {
+    // fake timers 必须先于 arm 生效（useFakeTimers 不接管已存在的真实 timer）
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const record = makeChatRecord("sa-first");
+    record.sessionFile = path.join(agentDir, "prior-session.jsonl");
+    fs.writeFileSync(record.sessionFile, "{}\n", "utf-8");
+    store.register(record);
+    await (
+      service as unknown as { resumeColdRound: (r: ExecutionRecord, t: string) => void }
+    ).resumeColdRound(record, "cold resume text");
+    expect(fake.runs).toHaveLength(1); // 冷续轮 run 已派发
+    expect(hasSettledWatchdog(record.id)).toBe(true);
+
+    // 冷续轮全程静默（无协议事件行）满中段窗长
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS + 1);
+
+    expect(killChildSpy).toHaveBeenCalledWith(record.id, "settled watchdog (hot path)");
+    expect(hasSettledWatchdog(record.id)).toBe(false); // 到期自清
+    // chatMode MF-6：回退 idle-resumable（不销毁对话）
+    expect(record.resumable).toBe(true);
+    expect(record.status).toBe("running");
+    expect(record.result).toContain("settled watchdog");
+    expect(record.result).toContain("Recovery");
+    // 引擎侧终止意图（协议 interact cancel）
+    const cancel = fake.interacts.find((c) => c.action.kind === "cancel");
+    expect(cancel).toBeDefined();
+    void pi;
+  });
+
+  it("中段事件行（text_delta 经 onEvent）刷新静默计时：半窗 + 刷新 + 半窗不触发，再满窗才触发", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const handle = await service.execute({ task: "streaming round", slug: "t", ctxModel: CTX_MODEL, conversation: true });
+    const run = fake.runs[0]!;
+
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS / 2);
+    // 首轮 runId 键协议事件行到达（text_delta——引擎侧同时走 onEvent 通道）
+    run.emitEvent({ type: "text_delta", delta: "chunk" });
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS / 2 + 1);
+    expect(hasSettledWatchdog(handle.subagentId)).toBe(true); // 刷新后未到期
+    expect(killChildSpy).not.toHaveBeenCalled();
+
+    // 刷新后再满整个静默窗才触发
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS + 1);
+    expect(killChildSpy).toHaveBeenCalledWith(handle.subagentId, "settled watchdog (hot path)");
+  });
+
+  it("首轮 settled 相位交棒：中段窗内相位到达 → 切收尾段（中段窗不再触发，收尾段硬顶触发）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const handle = await service.execute({ task: "stuck after settle", slug: "t", ctxModel: CTX_MODEL, conversation: true });
+    const run = fake.runs[0]!;
+
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS / 2);
+    // 首轮 runId 键 roundLifecycle settled 相位（W3 报告称已接——本用例核实链路生效）
+    run.emitLifecycle({ phase: "settled", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 } });
+    expect(getSettledWatchdogPhase(handle.subagentId)).toBe("settled"); // 已交棒收尾段
+
+    // 中段不再计时（交棒清掉，不继承——30min 静默判据对收尾段失效）；收尾段未满（<600s）不触发
+    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS - 1);
+    expect(killChildSpy).not.toHaveBeenCalled();
+    expect(hasSettledWatchdog(handle.subagentId)).toBe(true); // 收尾段仍在计时
+
+    // 收尾段硬顶（600s 默认）到期触发
+    await vi.advanceTimersByTimeAsync(2);
+    expect(killChildSpy).toHaveBeenCalledWith(handle.subagentId, "settled watchdog (hot path)");
+  });
+});
+
+describe("[F-5] chat 轮路由终态化注销（doFinalizeRecord onFinalized 汇聚点）", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+  let fake: FakePiEnginePort;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    killChildSpy.mockClear();
+    ({ agentDir, service, store, fake } = setup());
+  });
+
+  afterEach(() => {
+    service.dispose();
+    clearEngines();
+    _resetLifecycleState();
+    _resetSettledWatchdogsForTest();
+    _resetCoreSpawnedChildrenMirrorForTest();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("closeChatIdle 终态化路径注销 chat 轮路由（修复前仅 cancelBackground 注销 → 泄漏）", async () => {
+    const record = makeChatRecord("sa-route-leak");
+    store.register(record);
+    // 模拟首轮已注册的 recordId 键路由（kickOffChatRound 注册面：Service map + fake 引擎两端）
+    registerRoute(service, fake, record.id);
+    // Path A：idle timer armed（进程保活等待续聊）→ closeSubagent(false) 走 closeChatIdle
+    const { armIdleTimer } = (await import("../lifecycle-manager.ts")) as typeof import("../lifecycle-manager.ts");
+    armIdleTimer(record.id, () => {}, 60_000);
+
+    await service.chatActions.closeSubagent(record, false);
+
+    expect(fake.chatRouteUnregisters).toContain(record.id);
+  });
+
+  it("closeAfterRoundSettled（优雅关闭消费）路径注销 chat 轮路由", async () => {
+    const record = makeChatRecord("sa-route-close-round");
+    store.register(record);
+    registerRoute(service, fake, record.id);
+    record.closeAfterRound = true;
+
+    await (
+      service as unknown as { closeAfterRoundSettled: (r: ExecutionRecord) => Promise<void> }
+    ).closeAfterRoundSettled(record);
+
+    expect(fake.chatRouteUnregisters).toContain(record.id);
+    expect(record.status).toBe("closed");
+  });
+});

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

@@ -12,8 +12,9 @@
 //   5. flush 屏障时序：manifest 写完成先于 notifyBatch 写账（通知可达 ⇒ 索引就位
 //      的构造性保证，时序竞态修复）。
 //
-// mock 手法对齐 ended-message-and-fork-from.test.ts：mock session-runner（不 spawn
-// 真子进程）+ logger；record-store / config 走真实实现（tmpdir 自建自删，红线）。
+// mock 手法对齐 ended-message-and-fork-from.test.ts：[W3 改写] 替身从
+// vi.mock session-runner（不 spawn 真子进程）改为协议 seam（registerFakePiEngine 替身，
+// 测试显式 settle 应答）+ logger；record-store / config 走真实实现（tmpdir 自建自删，红线）。
 
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -21,35 +22,16 @@ import * as path from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 
-const { loggerMock, runSpawnMock } = vi.hoisted(() => ({
+const { loggerMock } = 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(),
-}));
+// [W3] execute 链经 executeViaEngine → kickOffChatRound → engine.run（协议替身）。
+// 替身 run 挂起不自动 settle：测试取 fake.runs.at(-1) 显式 settle（受控时序——
+// 原 runSpawnMock 的 resolve 时序控制等价面）。
+import { clearEngines } from "../engine/registry.ts";
+import { registerFakePiEngine, type FakePiEnginePort } from "./helpers/fake-engine-port.ts";
 
 import { getSubagentSessionDir, getSubagentRecordsDir } from "../path-encoding.ts";
 import { ModelConfigService } from "../model-config-service.ts";
@@ -116,9 +98,12 @@ describe("collectCoordinator service integration (U2)", () => {
   let agentDir: string;
   let service: SubagentService;
   let pi: ReturnType<typeof makePi>;
+  let fake: FakePiEnginePort;
 
   beforeEach(() => {
     for (const k of IDENTITY_ENV_KEYS) delete process.env[k];
+    clearEngines();
+    fake = registerFakePiEngine();
     agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "core-collect-coord-"));
     fs.mkdirSync(getSubagentSessionDir(agentDir, agentDir), { recursive: true });
     pi = makePi();
@@ -127,6 +112,7 @@ describe("collectCoordinator service integration (U2)", () => {
 
   afterEach(() => {
     service.dispose();
+    clearEngines();
     fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
@@ -154,6 +140,8 @@ describe("collectCoordinator service integration (U2)", () => {
     // 批投递（下方用例），async 成员直通。本条记录 execute 链零异常完成。
     const spy = spyNotifier(service);
     const handle = await service.execute({ task: "collect me", slug: "collect-me", collect: "sync" });
+    await until(() => fake.runs.length >= 1);
+    await settleLast();
     await until(() => spy.notifyBatch.mock.calls.length > 0);
     expect(handle.subagentId).toMatch(/^sa-/);
   });
@@ -161,6 +149,8 @@ describe("collectCoordinator service integration (U2)", () => {
   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(() => fake.runs.length >= 1);
+    await settleLast();
     await until(() => spy.notifyBatch.mock.calls.length > 0);
     // U3 接线后：sync 成员走单条批投递（不再逐条降级 notify）
     expect(spy.notify).not.toHaveBeenCalled();
@@ -173,6 +163,8 @@ describe("collectCoordinator service integration (U2)", () => {
     const spy = spyNotifier(service);
     spy.notifyBatch.mockReturnValue(false); // 模拟同成员集批已在账（E1 重建重发形态）
     const handle = await service.execute({ task: "collect me", slug: "collect-me", collect: "sync" });
+    await until(() => fake.runs.length >= 1);
+    await settleLast();
     await until(() => spy.notifyBatch.mock.calls.length > 0);
     expect(handle.subagentId).toMatch(/^sa-/);
     // 落标出口①绑「写账成功」：accepted=false → 无带 batchFinalized 标记的 subagent-record
@@ -188,6 +180,8 @@ describe("collectCoordinator service integration (U2)", () => {
   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(() => fake.runs.length >= 1);
+    await settleLast();
     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);
@@ -247,28 +241,27 @@ describe("collectCoordinator service integration (U2)", () => {
     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: [],
-  });
+  /** 受控替身 settle：等替身 run 到位（execute 返回后的异步链内发起），按需 settle。
+   *  原 runSpawnMock 受控 promise 的等价面（content "ok" 对齐原 AgentResult.text）。 */
+  const settleLast = async (): Promise<void> => {
+    await until(() => fake.runs.length >= 1);
+    fake.runs[fake.runs.length - 1]!.settle({ content: "ok" });
+  };
 
   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);
+    // engine.run 在 execute 返回后的异步链内才被发起——等两个替身 run 都到位
+    await until(() => fake.runs.length >= 2);
 
     // 第一台终态：第二台仍 running → 缓冲不闭合（零投递）
-    resolve1(spawnOk());
+    fake.runs[0]!.settle({ content: "ok" });
     await new Promise((resolve) => setTimeout(resolve, 50)); // microtask 链排空
     expect(spy.notifyBatch.mock.calls).toHaveLength(0);
 
     // 第二台终态：闭合 → 单批 2 成员（含第一台的快照，跨轮续累不丢）
-    resolve2(spawnOk());
+    fake.runs[1]!.settle({ content: "ok" });
     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 }[];
@@ -277,14 +270,12 @@ describe("collectCoordinator service integration (U2)", () => {
   });
 
   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）
+    await until(() => fake.runs.length >= 1); // 替身 run 已到位
+    // 子 session 文件在闭合判定/flush 前就位（真实生产链中引擎轮次已写好 identity）
     writeChildSessionFile(handle.subagentId, "/agents/worker.md", "ok");
-    resolveSpawn(spawnOk());
+    await settleLast();
     await until(() => spy.notifyBatch.mock.calls.length > 0);
 
     // 观察者形态：主 session 落盘的末条 subagent-record entry 带 batchFinalized=true +
@@ -307,11 +298,9 @@ describe("collectCoordinator service integration (U2)", () => {
     // 构造性保证（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 已构造
+    await until(() => fake.runs.length >= 1); // 替身 run 已到位
     writeChildSessionFile(handle.subagentId, "/agents/worker.md", "ok");
     const manifestPath = path.join(getSubagentRecordsDir(agentDir, agentDir), `${handle.subagentId}.json`);
     // 写账时刻钩子：mock 内联捕获 manifest 存在性（此刻即指针行消费可用性）
@@ -320,7 +309,7 @@ describe("collectCoordinator service integration (U2)", () => {
       manifestExistsAtLedgerWrite = fs.existsSync(manifestPath);
       return true;
     });
-    resolveSpawn(spawnOk());
+    await settleLast();
     await until(() => spy.notifyBatch.mock.calls.length > 0);
     expect(manifestExistsAtLedgerWrite).toBe(true);
   });

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

@@ -27,32 +27,15 @@ import * as path from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 
-const { loggerMock, runSpawnMock } = vi.hoisted(() => ({
+const { loggerMock } = 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(),
-}));
-
+// [W3 改写] 替身从 vi.mock session-runner 的受控 runSpawn 改为协议 seam 的受控
+// engine.run（registerFakePiEngine 替身 + 显式 settle）。
+import { registerFakePiEngine, type FakePiEnginePort } from "./helpers/fake-engine-port.ts";
+import { clearEngines } from "../engine/registry.ts";
 import { getSubagentSessionDir } from "../path-encoding.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelRegistryLike } from "../model-resolver.ts";
@@ -106,31 +89,10 @@ async function until(cond: () => boolean, timeoutMs = 3000): Promise<void> {
   }
 }
 
-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()),
-  );
+/** 受控替身 run：等 n 个替身 run 到位（execute 异步链内发起），按索引放行 settle。
+ *  与原受控 runSpawn 的 resolver 形态同构（索引 = execute 派发序）。 */
+function makeRelease(fk: FakePiEnginePort, n: number): Array<() => void> {
+  return Array.from({ length: n }, (_, i) => () => fk.runs[i]!.settle({ content: "ok" }));
 }
 
 describe("A8 混派正交 service e2e（同轮 2 sync + 1 async，U8）", () => {
@@ -138,8 +100,12 @@ describe("A8 混派正交 service e2e（同轮 2 sync + 1 async，U8）", () =>
   let service: SubagentService;
   let pi: ReturnType<typeof makePi>;
 
+  let fake: FakePiEnginePort;
+
   beforeEach(() => {
     for (const k of IDENTITY_ENV_KEYS) delete process.env[k];
+    clearEngines();
+    fake = registerFakePiEngine();
     agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "core-mixed-dispatch-"));
     fs.mkdirSync(getSubagentSessionDir(agentDir, agentDir), { recursive: true });
     pi = makePi();
@@ -160,6 +126,7 @@ describe("A8 混派正交 service e2e（同轮 2 sync + 1 async，U8）", () =>
 
   afterEach(() => {
     service.dispose();
+    clearEngines();
     fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
@@ -167,11 +134,11 @@ describe("A8 混派正交 service e2e（同轮 2 sync + 1 async，U8）", () =>
     const spy = spyNotifier(service);
     // 同轮三连派发：2 sync + 1 async（派发顺序 sync, sync, async——同一条消息内的
     // 混派形态；runSpawn 调用序与 execute 序一致）
-    const [doneSync1, doneSync2, doneAsync] = controlledSpawns(3);
+    const [doneSync1, doneSync2, doneAsync] = makeRelease(fake, 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 均已构造
+    await until(() => fake.runs.length >= 3); // 三个替身 run 均已到位
 
     // async 成员先终态：立即单条 notify（现状路径），批零投递、零扣留
     doneAsync();
@@ -198,11 +165,11 @@ describe("A8 混派正交 service e2e（同轮 2 sync + 1 async，U8）", () =>
 
   it("sync 批先闭合（async 仍在跑）：背靠背紧窗口合批单批；async 随后独立单条 notify", async () => {
     const spy = spyNotifier(service);
-    const [doneSync1, doneSync2, doneAsync] = controlledSpawns(3);
+    const [doneSync1, doneSync2, doneAsync] = makeRelease(fake, 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);
+    await until(() => fake.runs.length >= 3);
 
     // 两个 sync 同步段背靠背终态（窄于 finalize 链宽度——U8 拆批盲窗的精确复现形态：
     // 先 archive 的成员 route 时，后者的 notifyComplete 尚在 finalize 链间隙，闭合
@@ -228,11 +195,11 @@ describe("A8 混派正交 service e2e（同轮 2 sync + 1 async，U8）", () =>
 
   it("观察者形态：同轮混派三 record 的落盘 entry 各自携带正确 collectMode", async () => {
     const spy = spyNotifier(service);
-    const [, , doneAsync] = controlledSpawns(3);
+    const [, , doneAsync] = makeRelease(fake, 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);
+    await until(() => fake.runs.length >= 3);
     doneAsync();
     await until(() => spy.notify.mock.calls.length > 0);
     // 批不必闭合即可断言落盘（register 期 entry 即带 collectMode）：