@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/__tests__/execute-nesting.test.ts

@@ -32,7 +32,6 @@ import {
   finalizedMarkerModule,
   fsSyncModule,
   manifestStoreModule,
-  tempPromptModule,
 } from "./helpers/subagent-service-mocks.ts";
 
 vi.mock("node:child_process", () => childProcessModule());
@@ -40,11 +39,11 @@ vi.mock("node:fs", async (importOriginal) => fsSyncModule(await importOriginal<t
 vi.mock("../alive-store.ts", async (importOriginal) => aliveStoreModule(await importOriginal<typeof import("../alive-store.ts")>()));
 vi.mock("../finalized-marker.ts", () => finalizedMarkerModule());
 vi.mock("../manifest-store.ts", () => manifestStoreModule());
-vi.mock("../engine/engines/pi/temp-prompt.ts", () => tempPromptModule());
 
 import { spawn } from "node:child_process";
 
-import { waitForSpawn, lastSpawnedChild } from "./helpers/spawn-mock.ts";
+import { registerFakePiEngine, type FakePiEnginePort } from "./helpers/fake-engine-port.ts";
+import { clearEngines } from "../engine/registry.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
 import { MAX_FORK_DEPTH } from "../session-context-resolver.ts";
@@ -85,6 +84,15 @@ function setup(): SetupResult {
   return { service };
 }
 
+/** [W3] 协议替身注册 + 受控 settle（原 driveChildToCompletion 的等价驱动面）：
+ *  execute 发起的 engine.run 由测试显式应答（轮终语义对齐 driveChild 的 close(0)）。 */
+function setupWithFakeEngine(): SetupResult & { fake: FakePiEnginePort } {
+  const base = setup();
+  clearEngines();
+  const fake = registerFakePiEngine();
+  return { ...base, fake };
+}
+
 const ctxModel: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: false };
 
 /** [D3-⑤] execNesting（公共层 ExecutionNestingContext）.run 的 duck-type（绕过
@@ -103,15 +111,15 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
   // ============================================================
 
   it("[D-032] background execute 调 pool.acquire（进池限流）", async () => {
-    const { service } = setup();
+    const { service, fake } = setupWithFakeEngine();
 
     const pool = Reflect.get(service, "pool") as { acquire: ReturnType<typeof vi.fn>; release: ReturnType<typeof vi.fn> };
     const acquireSpy = vi.spyOn(pool, "acquire");
 
     const execPromise = service.execute({ task: "bg in pool", slug: "test", ctxModel });
-    // detached runAndFinalize → acquire。等 spawn 拿到 child 再驱动完成。
-    await waitForSpawn(mockSpawn);
-    await driveChildToCompletion(lastSpawnedChild(mockSpawn));
+    // detached kickOffChatRound → acquire。等替身 run 到位再驱动应答。
+    await vi.waitFor(() => expect(fake.runs.length).toBe(1));
+    fake.runs[0]!.settle({ content: "ok" });
 
     // 等 detached promise 链跑完（kickOffChatRound 的 .then notify）
     await new Promise<void>((r) => setTimeout(r, 10));
@@ -120,6 +128,7 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
     // background execute 立即返回 handle（不等完成）
     const handle = await execPromise;
     expect(handle.mode).toBe("background");
+    clearEngines();
   });
 
   // ============================================================
@@ -144,21 +153,19 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
   });
 
   it("[D-033] execCtxAls depth=MAX-1 时 execute 不抛（nestingDepth=MAX 允许）", async () => {
-    const { service } = setup();
+    const { service, fake } = setupWithFakeEngine();
 
     const execNesting = Reflect.get(service, "execNesting") as ExecCtxAls;
 
     const execPromise = execNesting.run({ recordId: "parent", depth: MAX_FORK_DEPTH - 1 }, () =>
       service.execute({ task: "at limit", slug: "test", ctxModel }),
     );
-    await waitForSpawn(mockSpawn);
-    await driveChildToCompletion(lastSpawnedChild(mockSpawn), [
-      { type: "turn_end" },
-      { type: "message_end", message: { usage: { input: 1 } } },
-    ]);
+    await vi.waitFor(() => expect(fake.runs.length).toBe(1));
+    fake.runs[0]!.settle({ content: "ok" });
     const result = await execPromise;
 
     expect(result.mode).toBe("background");
+    clearEngines();
   });
 
   // ============================================================

package/src/execution/__tests__/explicit-agent-ref-guard.test.ts

@@ -7,46 +7,31 @@
 // 错误含 <available_subagents> 恢复指引，对齐 workflow name not found 反馈风格）。
 //
 // 本文件锁住：
-//   1. 裸名/相对路径 agent ref → execute 同步 reject（Invalid agent ref），无 spawn、
-//      无子 session、record 不落盘（buildSpawnArgs/spawn/appendEntry 零触达）
+//   1. 裸名/相对路径 agent ref → execute 同步 reject（Invalid agent ref），无引擎
+//      派发、无子 session、record 不落盘（engine.run/appendEntry 零触达）
 //   2. 绝对路径但文件不存在 → reject（not found or unreadable）
 //   3. 对照：不传 agent（默认 general-purpose）与合法绝对路径 ref 均不误伤
 //
+// [W3 改写] 原 vi.mock(inproc pi 引擎目录/session-runner)（buildSpawnArgs spy）随删件消亡
+// ——「spawn 链路零触达」的结构性证据改经协议替身（engine.run 零调用）+ appendEntry
+// 零触达承载；守卫位于同步裁决期、引擎派发前置的结构不变。
+//
 // harness 复用 start-sync-model-guard.test.ts（真实 SubagentService + tmpdir +
-// mock spawn），保证守卫位于同步裁决期、spawn 前置的结构性证据可断言。
+// 协议替身），保证守卫位于同步裁决期、引擎派发前置的结构性证据可断言。
 
-import { 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, vi } from "vitest";
 
-vi.mock("node:child_process", async () => {
-  const actual = await import("node:child_process");
-  return {
-    ...actual,
-    spawn: vi.fn(() => {
-      throw new Error("spawn must not be called on agent-ref rejection");
-    }),
-  };
-});
-
-// buildSpawnArgs 包装为 spy（保留真实实现）——「显式 ref 拒单不触达 spawn 参数组装」的承重断言。
-vi.mock("../engine/engines/pi/session-runner.ts", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../engine/engines/pi/session-runner.ts")>();
-  return { ...actual, buildSpawnArgs: vi.fn(actual.buildSpawnArgs) };
-});
-
+import { registerFakePiEngine, type FakePiEnginePort } from "./helpers/fake-engine-port.ts";
+import { clearEngines } from "../engine/registry.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
-import { buildSpawnArgs } from "../engine/engines/pi/session-runner.ts";
 import type { PiLike } from "../subagent-service.ts";
 import { SubagentService } from "../subagent-service.ts";
 
-const mockSpawn = vi.mocked(spawn);
-const mockBuildSpawnArgs = vi.mocked(buildSpawnArgs);
-
 // ── 工具（start-sync-model-guard 同款）──
 
 function makeModel(over: Partial<ModelInfo> = {}): ModelInfo {
@@ -79,9 +64,12 @@ describe("显式 agent ref 失败报错（非静默降级 general-purpose）", (
   let tmpDir: string;
   let service: SubagentService;
   let pi: PiLike;
+  let fake: FakePiEnginePort;
 
   beforeEach(() => {
     vi.clearAllMocks();
+    clearEngines();
+    fake = registerFakePiEngine();
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sw-agent-ref-guard-"));
     const modelService = new ModelConfigService({ agentDir: tmpDir, cwd: tmpDir });
     modelService.initModel({
@@ -95,20 +83,20 @@ describe("显式 agent ref 失败报错（非静默降级 general-purpose）", (
 
   afterEach(() => {
     vi.restoreAllMocks();
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    clearEngines();
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
-  // ── 拒绝路径：显式 ref 失败 → 同步 reject + spawn 链路零触达 ──
+  // ── 拒绝路径：显式 ref 失败 → 同步 reject + 引擎派发零触达 ──
 
   it("裸名 agent ref（'worker'）→ execute 同步 reject（Invalid agent ref + 恢复指引）", async () => {
     await expect(
       service.execute({ task: "probe task", slug: "ref-guard", agent: "worker" }),
     ).rejects.toThrow(/Invalid agent ref: worker.*<available_subagents>/s);
 
-    // spawn 链路零触达 + record 未创建——非静默降级的结构性证据：
-    // 旧行为（静默 undefined）会继续走 record 创建（appendEntry 被调）后启动子进程。
-    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
-    expect(mockSpawn).not.toHaveBeenCalled();
+    // 引擎派发零触达 + record 未创建——非静默降级的结构性证据：
+    // 旧行为（静默 undefined）会继续走 record 创建（appendEntry 被调）后派发引擎。
+    expect(fake.runs.length).toBe(0);
     expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
@@ -117,7 +105,7 @@ describe("显式 agent ref 失败报错（非静默降级 general-purpose）", (
       service.execute({ task: "probe task", slug: "ref-guard", agent: "./agents/worker.md" }),
     ).rejects.toThrow(/Invalid agent ref/);
 
-    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
+    expect(fake.runs.length).toBe(0);
     expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
@@ -127,8 +115,7 @@ describe("显式 agent ref 失败报错（非静默降级 general-purpose）", (
       service.execute({ task: "probe task", slug: "ref-guard", agent: missing }),
     ).rejects.toThrow(/not found or unreadable.*<available_subagents>/s);
 
-    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
-    expect(mockSpawn).not.toHaveBeenCalled();
+    expect(fake.runs.length).toBe(0);
     expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
@@ -140,7 +127,7 @@ describe("显式 agent ref 失败报错（非静默降级 general-purpose）", (
       slug: "ref-default-ok",
       ctxModel: makeModel(),
     });
-    // 默认语义下 identity 解析必须放行（execute 可能因 mock 环境子进程收尾而 reject，
+    // 默认语义下 identity 解析必须放行（execute 可能因 mock 环境引擎收尾而 reject，
     // 但错误不能是 agent ref 拒绝）；record 已创建（appendEntry 发生）。
     try {
       await promise;

package/src/execution/__tests__/finalized-marker.test.ts

@@ -20,7 +20,7 @@ describe("finalized-marker", () => {
     sessionFile = path.join(tmpDir, "2026-01-01_uuid.jsonl");
   });
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   describe("write → read 往返", () => {

package/src/execution/__tests__/gc-timer.test.ts

@@ -1,3 +1,6 @@
+// [W3 改写] 原 vi.mock(inproc pi 引擎目录/session-runner)（runSpawn 占位 + getChildByRecord
+// 活进程判定）随 inproc pi 引擎目录 删除消亡——「有活进程」形态改经 core 侧 spawnedChildren
+// 镜像注入（host/spawned-children.ts，isResumable 的 hasLiveProcessHandle 唯一读点）。
 // src/execution/__tests__/gc-timer.test.ts
 //
 // [M8] idle record GC 定时器测试（subagent-service.ts startGcTimer，L485-507）。
@@ -12,7 +15,6 @@
 // session-runner（import 链依赖 + isResumable 的 hasLiveProcessHandle 查询点）与 logger。
 // timer 全部 vi.useFakeTimers，不真实等待。
 
-import type { ChildProcess } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -24,17 +26,6 @@ const { loggerMock } = vi.hoisted(() => ({
 }));
 vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
-// mock session-runner：runSpawn/killAllSpawnedChildren 占位（import 链需要），
-// getChildByRecord 默认返回 undefined（无活进程 → isResumable=true），用例内按需覆盖。
-vi.mock("../engine/engines/pi/session-runner.ts", () => ({
-  runSpawn: vi.fn(),
-  killAllSpawnedChildren: vi.fn(),
-  getChildByRecord: vi.fn(() => undefined),
-  registerSpawnedChildForRecord: vi.fn(),
-  killRecordChildWithEscalation: vi.fn(),
-  spawnedChildren: new Map(),
-}));
-
 // [D8] idle-gc 归档时释放引擎池引用（releasePoolRef 经 getEngineDataDir 解析
 // dataDir）——测试钉到模块级 holder（vi.mock factory 闭包只能引用模块级变量），
 // beforeEach 刷新为当前 tmp agentDir，防触碰真实数据目录。
@@ -44,15 +35,13 @@ vi.mock("../engine/common/data-dir.ts", () => ({
 }));
 
 import { acquirePool } from "../engine/common/pool-manager.ts";
-import { getChildByRecord } from "../engine/engines/pi/session-runner.ts";
+import { coreSpawnedChildrenMirror, _resetCoreSpawnedChildrenMirrorForTest } from "../engine/host/spawned-children.ts";
 import { createRecord } from "../execution-record.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import { RecordStore } from "../record-store.ts";
 import { SubagentService } from "../subagent-service.ts";
 import type { ExecutionRecord } from "../types.ts";
 
-const mockGetChildByRecord = vi.mocked(getChildByRecord);
-
 /** 与 startGcTimer 内部常量一致（1h 扫描 / 30 天 TTL）。 */
 const GC_INTERVAL_MS = 60 * 60 * 1000;
 const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
@@ -111,15 +100,14 @@ describe("[M8] idle record GC 定时器（startGcTimer）", () => {
     service = new SubagentService({ cwd: agentDir, modelService });
     service.initSession({ pi: makePi(), sessionId: "root-session" });
     store = (service as unknown as ServiceInternals).store;
-    mockGetChildByRecord.mockReset();
     // 默认无活进程（isResumable=true）——Path B：进程已回收、可冷路径 resume 的等待续聊态
-    mockGetChildByRecord.mockImplementation(() => undefined);
+    _resetCoreSpawnedChildrenMirrorForTest();
     loggerMock.warn.mockClear();
   });
 
   afterEach(() => {
     service.dispose();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     vi.useRealTimers();
   });
 
@@ -144,12 +132,9 @@ describe("[M8] idle record GC 定时器（startGcTimer）", () => {
 
   it("有活进程的 record 不归档（isResumable=false，即使 idleSince 超 TTL）", () => {
     const fireAt = Date.now() + GC_INTERVAL_MS;
-    // Path A：进程保活等待续聊（idle timer armed、child 未 kill）——归档会让活进程失管
+    // Path A：进程保活等待续聊（idle timer armed、镜像登记活句柄）——归档会让活进程失管
     store.register(makeIdleRecord("sa-live", fireAt - IDLE_TTL_MS - 1));
-    mockGetChildByRecord.mockImplementation(
-      (id: string): ChildProcess | undefined =>
-        id === "sa-live" ? ({ killed: false } as unknown as ChildProcess) : undefined,
-    );
+    coreSpawnedChildrenMirror().register("sa-live", { pid: 4242, killed: false });
 
     service.startGcTimer();
     vi.advanceTimersByTime(GC_INTERVAL_MS);

package/src/execution/__tests__/get-record-for-action-restart.test.ts

@@ -25,18 +25,13 @@ const { loggerMock } = vi.hoisted(() => ({
 }));
 vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
-// mock session-runner：import 链需要（getRecordForAction 本身不调 spawn，仅守卫读
-// hasLiveProcessHandle——默认无活进程，与跨重启场景一致）。
-vi.mock("../engine/engines/pi/session-runner.ts", () => ({
-  runSpawn: vi.fn(),
-  killAllSpawnedChildren: vi.fn(),
-  getChildByRecord: vi.fn(() => undefined),
-  registerSpawnedChildForRecord: vi.fn(),
-  killRecordChildWithEscalation: vi.fn(),
-  spawnedChildren: new Map(),
-}));
+// [W3 改写] 原 vi.mock(inproc pi 引擎目录/session-runner) 随删件消亡——deliverChatMessage 走
+// 协议 seam（registerFakePiEngine 替身；跨重启无活进程 = 引擎冷路径拒绝，续聊落
+// resumeColdRound 守卫链）。
 
 import { writeFinalized } from "../finalized-marker.ts";
+import { registerFakePiEngine } from "./helpers/fake-engine-port.ts";
+import { clearEngines } from "../engine/registry.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import { getSubagentSessionDir } from "../path-encoding.ts";
 import { RecordStore } from "../record-store.ts";
@@ -224,6 +219,14 @@ describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）",
   // 不可序列化、重建后恒缺失，若无守卫 → 冷路径 resume 的 spawn cwd 静默回落主 repo
   //（隔离失效，正是 worktree 要防的并发写冲突场景）。
   it("[review round2] worktree record 跨重启重建 → hadWorktree 标记 + 续聊被拒（行动语言）", async () => {
+    clearEngines();
+    const fake = registerFakePiEngine();
+    // 跨重启无活进程 → 引擎冷路径拒绝 → 续聊落 resumeColdRound 守卫链
+    fake.interactMessageResult = {
+      ok: false,
+      code: "engine_session_not_resumable",
+      message: "no live process (cold path)",
+    };
     writeSessionJsonl(sessionsDir, {
       id: "sa-wt",
       rootSessionId: "root-session",
@@ -243,6 +246,13 @@ describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）",
   });
 
   it("[review round2] 非 worktree record 跨重启重建 → 续聊不受 worktree 守卫拦截（向后兼容）", async () => {
+    clearEngines();
+    const fake = registerFakePiEngine();
+    fake.interactMessageResult = {
+      ok: false,
+      code: "engine_session_not_resumable",
+      message: "no live process (cold path)",
+    };
     // identity entry 无 worktree 字段（旧文件）→ found.worktree undefined → hadWorktree false
     writeSessionJsonl(sessionsDir, { id: "sa-nowt", rootSessionId: "root-session" });
 

package/src/execution/__tests__/helpers/fake-engine-port.ts

@@ -0,0 +1,187 @@
+// src/execution/__tests__/helpers/fake-engine-port.ts
+//
+// [W3 chat 域收口] SubagentService 编排层测试共享的 pi EnginePort 替身。
+//
+// 背景：chat 域执行链路自 W3 起经协议客户端（registry 'pi' 的 cli 形态 port——
+// RemoteEngine）发往 pi-subagent-cli 引擎进程；原 inproc 链路的测试替身
+//（vi.mock session-runner / FakeChild stdout pump）随 inproc pi 引擎目录 删除消亡。
+// 本 helper 是协议 seam 的替身单源：测试经 registerEngine("pi", fake) 注入，
+// 拿到 fake 实例后驱动 run/interact/roundLifecycle，断言协议交互。
+//
+// 消费方式（与 spawn-mock.ts 同款先例）：
+//   const fake = registerFakePiEngine();
+//   await service.execute({ task: "...", conversation: true });
+//   fake.runs[0].settle({ content: "round text" });   // 模拟首轮 agent_settled 应答
+//   fake.interacts[0]                                  // interact 受理断言
+//
+// 形态对照（协议语义，见 pi-subagent-cli chat-session.ts）：
+//   - run 应答时点 = 首轮 agent_settled（outcome = 本轮内容非会话终态）；
+//   - interact message 受理 = { ok: true, delivered: true }；冷路径 = engine_session_not_resumable；
+//   - interact cancel = { ok: true, delivered: true }（引擎侧 SIGTERM → settle → 杀链）；
+//   - roundLifecycle 相位由测试显式驱动（idle 帧先于 run 应答帧）。
+
+import type { EnginePort, EngineRunResult, RunContext, ChatRoundRoute } from "../../../execution/engine/port.ts";
+import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
+import type {
+  AgentOutcome,
+  EngineCapabilities,
+  EngineHandle,
+  InteractAction,
+  InteractResult,
+  ProbeReport,
+  SessionView,
+} from "../../../execution/engine/types.ts";
+import { registerEngine } from "../../../execution/engine/registry.ts";
+
+/** 一次 run 调用的捕获（task + ctx + 结算控制面）。 */
+export class FakeRun {
+  readonly task: AgentCallOpts;
+  readonly ctx: RunContext;
+  private resolve!: (r: EngineRunResult) => void;
+  private reject!: (err: unknown) => void;
+  readonly promise: Promise<EngineRunResult>;
+
+  constructor(task: AgentCallOpts, ctx: RunContext) {
+    this.task = task;
+    this.ctx = ctx;
+    this.promise = new Promise<EngineRunResult>((res, rej) => {
+      this.resolve = res;
+      this.reject = rej;
+    });
+  }
+
+  /** 模拟 run 正常应答（首轮 agent_settled 口径；outcome 缺省 = 成功空轮）。 */
+  settle(outcome: Partial<AgentOutcome> = {}): void {
+    this.resolve({
+      handle: {
+        data: {
+          v: 1,
+          engineId: "pi",
+          sessionRef: { recordId: this.ctx.taskId },
+          poolKey: "shared",
+          adapterVersion: "fake-engine-port",
+        },
+      },
+      outcome: {
+        content: "",
+        engineId: "pi",
+        ...outcome,
+      },
+    });
+  }
+
+  /** 模拟 run 期失败（prepare 期 reject / 引擎进程死亡）。 */
+  fail(err: unknown): void {
+    this.reject(err);
+  }
+
+  /** 模拟引擎反向事件通知（协议 event 通知形态）。 */
+  emitEvent(event: unknown): void {
+    this.ctx.onEvent?.(event as never);
+  }
+
+  /** 模拟 host/streamDelta（runId 键——首轮）。 */
+  emitDelta(delta: string): void {
+    this.ctx.stream?.onDelta(delta);
+  }
+
+  /** 模拟 host/roundLifecycle（runId 键——首轮）。 */
+  emitLifecycle(phase: Record<string, unknown>): void {
+    this.ctx.onRoundLifecycle?.({ runId: this.ctx.taskId, ...phase } as never);
+  }
+
+  /** 模拟 host/handleReady（运行中句柄回填）。 */
+  emitHandleReady(sessionRef: Record<string, string>, poolKey = "shared"): void {
+    this.ctx.onHandleReady?.({ sessionRef, poolKey });
+  }
+}
+
+/** 一次 interact 调用的捕获（action 原样记录，供断言）。 */
+export interface FakeInteractCall {
+  handle: EngineHandle;
+  action: InteractAction;
+  result: InteractResult | Promise<InteractResult>;
+}
+
+export class FakePiEnginePort implements EnginePort {
+  readonly id = "pi";
+
+  /** run 调用捕获（按序）。 */
+  readonly runs: FakeRun[] = [];
+  /** interact 调用捕获（按序；result = 受理时返回值）。 */
+  readonly interacts: FakeInteractCall[] = [];
+  /** recordId 键路由注册捕获（recordId → 注销函数）。 */
+  readonly chatRoutes = new Map<string, ChatRoundRoute>();
+  readonly chatRouteUnregisters: string[] = [];
+
+  /** interact message 的应答形态（默认受理；测试改写为冷路径拒绝等）。 */
+  interactMessageResult: InteractResult = { ok: true, delivered: true };
+  /** interact cancel / close 的应答形态。 */
+  interactControlResult: InteractResult = { ok: true, delivered: true };
+
+  capabilities(): EngineCapabilities {
+    // 与 pi-subagent-cli manifest 逐位一致（gate 同步面放行 pi 全参数——V4⑤ 反向守护）。
+    return {
+      schemaEnforcement: "native",
+      steer: "unsupported",
+      conversation: "native",
+      personaInjection: "flag",
+      eventGranularity: "stream",
+      sandbox: "emulated",
+      sessionRead: "full",
+      resume: "native",
+      interrupt: "kill-only",
+      permissionMode: "native",
+      maxTurns: true,
+    };
+  }
+
+  async probe(): Promise<ProbeReport> {
+    return { ok: true, engineVersion: "fake-1", checks: [{ name: "invocation", ok: true, detail: "fake" }] };
+  }
+
+  run(task: AgentCallOpts, ctx: RunContext): Promise<EngineRunResult> {
+    const captured = new FakeRun(task, ctx);
+    this.runs.push(captured);
+    return captured.promise;
+  }
+
+  async interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult> {
+    const result = action.kind === "message" ? this.interactMessageResult : this.interactControlResult;
+    this.interacts.push({ handle, action, result });
+    return result;
+  }
+
+  async read(handle: EngineHandle): Promise<SessionView> {
+    return { engineId: "pi", turns: [], source: "outcome-only" };
+  }
+
+  registerChatRoundRoute(recordId: string, route: ChatRoundRoute): () => void {
+    this.chatRoutes.set(recordId, route);
+    return () => {
+      if (this.chatRoutes.get(recordId) === route) {
+        this.chatRoutes.delete(recordId);
+        this.chatRouteUnregisters.push(recordId);
+      }
+    };
+  }
+
+  // ── 测试驱动面（recordId 键路由——interact 续聊轮的协议回流）──
+
+  /** 向指定 record 的 chat 路由发 recordId 键 delta。 */
+  emitRecordDelta(recordId: string, delta: string): void {
+    void this.chatRoutes.get(recordId)?.onStreamDelta?.(delta);
+  }
+
+  /** 向指定 record 的 chat 路由发 recordId 键 roundLifecycle 相位。 */
+  emitRecordLifecycle(recordId: string, phase: Record<string, unknown>): void {
+    void this.chatRoutes.get(recordId)?.onRoundLifecycle?.({ recordId, ...phase } as never);
+  }
+}
+
+/** 注册替身 pi 引擎进 registry（覆盖同 id 既有注册——测试隔离自负责清理）。 */
+export function registerFakePiEngine(): FakePiEnginePort {
+  const fake = new FakePiEnginePort();
+  registerEngine("pi", () => fake);
+  return fake;
+}

package/src/execution/__tests__/helpers/spawn-mock.ts

@@ -47,7 +47,7 @@
 //     };
 //   });
 //   vi.mock("../alive-store.ts", () => ({ writeAliveMarker: vi.fn() }));
-//   vi.mock("../engine/engines/pi/temp-prompt.ts", () => ({
+//   vi.mock("../engine/inproc temp-prompt（已删）", () => ({
 //     writePromptToTempFile: vi.fn(async (agent: string) => {
 //       const safeName = agent.replace(/[^\w.-]+/g, "_");
 //       return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
@@ -63,7 +63,11 @@ import { PassThrough } from "node:stream";
 import { vi } from "vitest";
 
 import { createRecord } from "../../execution-record.ts";
-import type { RunOptions, SessionRunnerContext } from "../../engine/engines/pi/session-runner.ts";
+
+// [W3 改写] RunOptions / SessionRunnerContext 类型源（inproc session-runner（已删））
+// 随删件消亡——makeOpts/makeCtx 改用结构化最小类型（消费方为 keep-alive 系历史
+// fixture 形态；引擎侧等价类型在 pi-subagent-cli）。core 侧剩余消费面为
+// recursive-visibility-baseline 的 spawn 断言工具（waitForSpawn/lastSpawnedChild）。
 
 /** FakeChild 的假 pid（满足 ChildProcess.pid 形状，无真实进程语义）。 */
 const FAKE_PID = 12345;
@@ -82,7 +86,7 @@ const SPAWN_POLL_INTERVAL_MS = 5;
  * 导出 class（而非只在工厂内部定义）是为了：
  *   1. vi.mock 工厂内 `await import("./helpers/spawn-mock.ts")` 后 `new FakeChild()` 与
  *      测试侧 `instanceof FakeChild` / 类型断言用同一个 class。
- *   2. C13 e2e 测试可直接 `new FakeChild()` 手动构造 child 喂给 ui-request-queue（不经 spawn）。
+ *   2. C13 e2e 测试可直接 `new FakeChild()` 手动构造 child 喂给 inproc UI 请求队列（已删）（不经 spawn）。
  */
 export class FakeChild extends EventEmitter {
   pid = FAKE_PID;
@@ -206,8 +210,21 @@ export function makeRecord(id = "run-1") {
   });
 }
 
+/** RunOptions 的结构化最小形态（原 inproc pi 引擎目录 RunOptions 同构；测试 fixture 用）。 */
+export interface RunOptionsLike {
+  resolved: { model: { id: string; name: string; provider: string; reasoning: boolean }; thinkingLevel: string | undefined };
+  agentConfig: undefined;
+  appendSystemPrompt?: string[];
+  skillPath?: string;
+  schema?: Record<string, unknown>;
+  maxTurns?: number;
+  graceTurns?: number;
+  signal?: AbortSignal;
+  onEvent?: ((event: unknown) => void) | undefined;
+}
+
 /** 构造最小合法的 RunOptions（runSpawn 入参，可 override 关键字段）。 */
-export function makeOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+export function makeOpts(overrides: Partial<RunOptionsLike> = {}): RunOptionsLike {
   return {
     resolved: {
       model: {
@@ -230,8 +247,19 @@ export function makeOpts(overrides: Partial<RunOptions> = {}): RunOptions {
   };
 }
 
+/** SessionRunnerContext 的结构化最小形态（core 侧消费字段面）。 */
+export interface SessionRunnerContextLike {
+  cwd: string;
+  agentDir: string;
+  skillDirs: string[];
+  mainCwd: string;
+  mainSessionFile?: string;
+  sessionRootId: string;
+  rootCwd: string;
+}
+
 /** 构造最小合法的 SessionRunnerContext（runSpawn 入参，可 override 关键字段）。 */
-export function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+export function makeCtx(overrides: Partial<SessionRunnerContextLike> = {}): SessionRunnerContextLike {
   return {
     cwd: "/tmp/test",
     agentDir: "/tmp/test/agents",
@@ -318,11 +346,10 @@ export function sessionPendingModule() {
   return {
     readActivePendingFromSessionFile: vi.fn(() => ({ count: 1, recentUnregister: false })),
     prunePendingCursor: vi.fn(),
-    listActivePendingFromSessionFile: vi.fn(() => ({ items: [] })),
   };
 }
 
-/** "../engine/engines/pi/temp-prompt.ts" mock 工厂（prompt 落 /tmp/fake-<agent>，收尾 no-op）。 */
+/** "../engine/inproc temp-prompt（已删）" mock 工厂（prompt 落 /tmp/fake-<agent>，收尾 no-op）。 */
 export function tempPromptModule() {
   return {
     writePromptToTempFile: vi.fn(async (agent: string) => {
@@ -352,7 +379,7 @@ export function makeVisibilityRecord(overrides: { id?: string; depth?: number }
 }
 
 /** 构造 env 注入断言族的 RunOptions（可 override 关键字段）。 */
-export function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+export function makeRunOpts(overrides: Partial<RunOptionsLike> = {}): RunOptionsLike {
   return {
     resolved: { model: { provider: "test", id: "model", name: "Model", reasoning: false }, thinkingLevel: undefined },
     agentConfig: undefined,
@@ -368,7 +395,7 @@ export function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
 }
 
 /** 构造 env 注入断言族的 SessionRunnerContext（可 override 关键字段）。 */
-export function makeVisibilityCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+export function makeVisibilityCtx(overrides: Partial<SessionRunnerContextLike> = {}): SessionRunnerContextLike {
   return {
     cwd: "/fake/cwd",
     agentDir: "/fake/agent",

package/src/execution/__tests__/helpers/subagent-service-mocks.ts

@@ -112,7 +112,7 @@ export function manifestStoreModule() {
   return { ManifestStore: vi.fn(function (_recordsDir: string) { return new FakeManifestStore(); }) };
 }
 
-/** ../engine/engines/pi/temp-prompt.ts mock 模块（固定路径，消除 fake-timers 下 flaky 竞态）。 */
+/** temp-prompt mock 模块（固定路径，消除 fake-timers 下 flaky 竞态）。[W3] 被 mock 的 inproc temp-prompt 模块已删——本工厂仅余存量测试文件引用。 */
 export function tempPromptModule() {
   return {
     writePromptToTempFile: vi.fn(async (agent: string) => {