@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/__tests__/subagent-service-recovery-bounds.test.ts

@@ -1,19 +1,23 @@
 // src/execution/__tests__/subagent-service-recovery-bounds.test.ts
 //
 // [u-svc / T2] 服务侧回收上界与 kill 收敛：
-//   - T2④/LC-2：closeChatIdle / closeAfterRoundSettled / cancelBackground 三条裸 SIGTERM
-//     收敛到 killRecordChildWithEscalation（spy 断言调用点与参数）；
+//   - T2④/LC-2：closeChatIdle / closeAfterRoundSettled / cancelBackground 三条终止路径
+//     收敛到 killRecordChildWithEscalation（spy 断言调用点与参数）+ [W3] 引擎侧终止
+//     意图（协议 interact cancel/close fire-and-forget）；
 //   - T2⑥/PS-1：disposeAllRecords 补三回收面（controller.abort + kill + disarm idle timer
 //     + disarm settled watchdog）；
-//   - T2③/LC-1 + D9：热路径投递 armMidRoundNoProgress（挂载点 D2 下沉后在编排层
-//     deliverChatMessage 的 interact 返回点；挂载中段无进展检测 + 到期 onMidTimeout/
-//     onSettleTimeout 处置：kill + 失败终态化 + error 含 'settled watchdog' 标记与恢复
-//     指引；agent_end 交棒收尾段的接线在 session-runner stdout pump，两路径共用）；
-//   - T2⑧/PS-3：非 EPIPE 热路径写失败 re-arm idle timer（进程不再裸奔；挂载位 D2
-//     下沉后在 PiEngine.deliverPrompt 的非 EPIPE catch——编排层无法区分错误类别）。
+//   - T2③/LC-1 + D9：热路径投递 armMidRoundNoProgress（挂载点在编排层
+//     deliverChatMessage 的 interact 受理点；中段无进展检测 + 到期处置：kill + 失败
+//     终态化 + error 含 'settled watchdog' 标记与恢复指引）。
 //
-// mock 形态沿用 subagent-service-message-close.test.ts（真实 SubagentService + ServiceInternals
-// cast 暴露 store + mock session-runner/stdin-writer/logger）。
+// [W3 改写] 替身从 inproc session-runner/stdin-writer mock 改为协议 seam
+//（registerFakePiEngine）：投递 = engine.interact(message) 受理；终止意图 =
+// engine.interact(cancel/close)。T2⑧（非 EPIPE 写失败 re-arm idle timer）随
+// inproc pi 引擎目录 删除归 pi-subagent-cli 包内（写失败语义在引擎进程内，core 已无
+// 可泄漏的本地方案进程），core 侧不再可等价改写。
+//
+// mock 形态：真实 SubagentService + ServiceInternals cast 暴露 store + logger +
+// spawned-children 的 kill 入口换 spy（importOriginal 保留镜像真实现）。
 
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -26,37 +30,15 @@ const { loggerMock } = vi.hoisted(() => ({
 }));
 vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
-// killRecordChildWithEscalation 换 spy（收敛调用点断言）；spawnedChildren 用真 Map
-//（热路径投递判定 / EPIPE 兜底按值删除的消费者）；getChildByRecord 从同一 Map 查
-//（mock 工厂与测试共享同一实例）。D2 后模块物理下沉 engines/pi/（mock 路径随迁）。
-const { killChildSpy, spawnedMap, getChildByRecordMock } = vi.hoisted(() => {
-  const map = new Map<string, unknown>();
-  return {
-    killChildSpy: vi.fn(),
-    spawnedMap: map,
-    getChildByRecordMock: vi.fn((recordId: string) => map.get(recordId)),
-  };
+// killRecordChildWithEscalation 换 spy（收敛调用点断言）；镜像真实现保留。
+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 };
 });
-vi.mock("../engine/engines/pi/session-runner.ts", () => ({
-  runSpawn: vi.fn(),
-  killAllSpawnedChildren: vi.fn(),
-  getChildByRecord: getChildByRecordMock,
-  registerSpawnedChildForRecord: vi.fn(),
-  spawnedChildren: spawnedMap,
-  killRecordChildWithEscalation: killChildSpy,
-}));
-
-// sendPromptCommand 换 spy（控制热路径写成功 / 抛非 EPIPE 错误）。
-const { sendPromptCommandMock } = vi.hoisted(() => ({ sendPromptCommandMock: vi.fn() }));
-vi.mock("../engine/engines/pi/stdin-writer.ts", () => ({
-  sendPromptCommand: sendPromptCommandMock,
-  clearEpipeFailure: vi.fn(),
-  recordEpipeFailure: vi.fn(() => 1),
-  resetAllEpipeFailures: vi.fn(),
-  EPIPE_FAILURE_THRESHOLD: 3,
-}));
 
-import { FakeChild } from "./helpers/spawn-mock.ts";
+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 { RecordStore } from "../record-store.ts";
@@ -64,26 +46,19 @@ import { SubagentService } from "../subagent-service.ts";
 import type { PiLike } from "../subagent-service.ts";
 import { armSettledWatchdog, hasSettledWatchdog, SETTLED_MID_ROUND_NO_PROGRESS_MS, _resetSettledWatchdogsForTest } from "../settled-watchdog.ts";
 import { armIdleTimer, hasIdleTimer, _resetLifecycleState } from "../lifecycle-manager.ts";
+import { _resetCoreSpawnedChildrenMirrorForTest } from "../engine/host/spawned-children.ts";
 import type { ExecutionRecord } from "../types.ts";
 
 function makeTmpAgentDir(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), "svc-recovery-bounds-"));
 }
 
-function makePi(): PiLike & {
-  appendEntry: ReturnType<typeof vi.fn>;
-  events: { emit: ReturnType<typeof vi.fn> };
-  sendMessage: ReturnType<typeof vi.fn>;
-} {
+function makePi(): PiLike {
   return {
     appendEntry: vi.fn(),
     events: { emit: vi.fn() },
     sendMessage: vi.fn(),
-  } as unknown as PiLike & {
-    appendEntry: ReturnType<typeof vi.fn>;
-    events: { emit: ReturnType<typeof vi.fn> };
-    sendMessage: ReturnType<typeof vi.fn>;
-  };
+  } as unknown as PiLike;
 }
 
 function makeRecord(overrides: Partial<ExecutionRecord> & { id?: string } = {}): ExecutionRecord {
@@ -109,14 +84,16 @@ interface ServiceInternals {
 
 type MockPi = ReturnType<typeof makePi>;
 
-function setup(): { agentDir: string; service: SubagentService; store: RecordStore; pi: MockPi } {
+function setup(): { agentDir: string; service: SubagentService; store: RecordStore; pi: MockPi; fake: FakePiEnginePort } {
   const agentDir = makeTmpAgentDir();
+  clearEngines();
+  const fake = registerFakePiEngine();
   const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
   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 };
+  return { agentDir, service, store, pi, fake };
 }
 
 /** bracket 调 private 方法（ServiceInternals cast 先例的扩展形态）。 */
@@ -125,8 +102,8 @@ function privateFn<K extends string>(service: SubagentService, key: K): (...args
 }
 
 /**
- * message 投递入口（D2 后形态：编排层私有 deliverChatMessage → PiEngine.interactRecord
- * → deliverPrompt；旧直调形态 deliverMessage 已随协议知识下沉删除）。
+ * message 投递入口（[W3] 协议形态：编排层私有 deliverChatMessage → engine.interact(message)；
+ * 冷路径 = engine_session_not_resumable → run chat + resume）。
  */
 async function deliverChat(
   service: SubagentService,
@@ -149,40 +126,49 @@ describe("T2④ service-side kill convergence", () => {
   let service: SubagentService;
   let store: RecordStore;
   let pi: MockPi;
+  let fake: FakePiEnginePort;
 
   beforeEach(() => {
     vi.restoreAllMocks();
     killChildSpy.mockClear();
-    sendPromptCommandMock.mockReset();
-    ({ agentDir, service, store, pi } = setup());
+    ({ agentDir, service, store, pi, fake } = setup());
   });
 
   afterEach(() => {
+    service.dispose();
+    clearEngines();
     _resetLifecycleState();
     _resetSettledWatchdogsForTest();
-    spawnedMap.clear();
+    _resetCoreSpawnedChildrenMirrorForTest();
     fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
-  it("cancelBackground (via cancel) routes through killRecordChildWithEscalation", async () => {
+  it("cancelBackground (via cancel) routes through killRecordChildWithEscalation + 引擎侧 cancel", async () => {
     const record = makeRecord({ id: "sa-cancel" });
     store.register(record);
-    spawnedMap.set(record.id, new FakeChild());
     const ok = service.cancel(record.id);
     expect(ok).toBe(true);
     expect(killChildSpy).toHaveBeenCalledWith(record.id, "cancelBackground");
+    // [W3] 实际终止在引擎进程内：协议 interact cancel fire-and-forget
+    await vi.waitFor(() => {
+      expect(fake.interacts.some((c) => c.action.kind === "cancel")).toBe(true);
+    });
   });
 
   it("closeChatIdle (via closeSubagent force:false on idle) routes through killRecordChildWithEscalation and disarms timers", async () => {
     const record = makeRecord({ id: "sa-close-idle" });
     store.register(record);
-    spawnedMap.set(record.id, new FakeChild());
     armIdleTimer(record.id, () => {}); // Path A：idle timer armed（进程保活）
     armSettledWatchdog(record.id, () => {});
     await service["closeSubagent"](record, false);
     expect(killChildSpy).toHaveBeenCalledWith(record.id, "closeChatIdle");
     expect(hasIdleTimer(record.id)).toBe(false);
     expect(hasSettledWatchdog(record.id)).toBe(false);
+    // [W3] 引擎侧 close force（idle 进程回收）
+    await vi.waitFor(() => {
+      const close = fake.interacts.find((c) => c.action.kind === "close");
+      expect(close?.action).toMatchObject({ kind: "close", payload: { force: true } });
+    });
   });
 
   it("closeAfterRoundSettled routes through killRecordChildWithEscalation", async () => {
@@ -198,7 +184,6 @@ describe("T2④ service-side kill convergence", () => {
     const idle = makeRecord({ id: "sa-dispose-idle" });
     store.register(running);
     store.register(idle);
-    spawnedMap.set(running.id, new FakeChild());
     armIdleTimer(idle.id, () => {});
     armSettledWatchdog(idle.id, () => {});
 
@@ -226,49 +211,42 @@ describe("T2③ hot-path settled watchdog", () => {
   let service: SubagentService;
   let store: RecordStore;
   let pi: MockPi;
+  let fake: FakePiEnginePort;
 
   beforeEach(() => {
     vi.restoreAllMocks();
     killChildSpy.mockClear();
-    // 模拟真 kill 的语义面（置 killed 标记）：isResumable 判定（无活进程）与失败通知
-    // 放行依赖它——真实 kill 后 close 事件把句柄移出 spawnedChildren，语义相同。
-    killChildSpy.mockImplementation((recordId: string) => {
-      const c = spawnedMap.get(recordId) as FakeChild | undefined;
-      if (c) c.killed = true;
-    });
-    sendPromptCommandMock.mockReset();
-    sendPromptCommandMock.mockImplementation(() => {});
-    ({ agentDir, service, store, pi } = setup());
+    ({ agentDir, service, store, pi, fake } = setup());
   });
 
   afterEach(() => {
+    service.dispose();
+    clearEngines();
     vi.useRealTimers();
     _resetLifecycleState();
     _resetSettledWatchdogsForTest();
-    spawnedMap.clear();
+    _resetCoreSpawnedChildrenMirrorForTest();
     fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("arms the settled watchdog after a successful hot-path prompt", async () => {
     const record = makeRecord({ id: "sa-hot-arm" });
     store.register(record);
-    spawnedMap.set(record.id, new FakeChild());
     await deliverChat(service, record, "hello", false);
-    expect(sendPromptCommandMock).toHaveBeenCalledTimes(1);
+    expect(fake.interacts.length).toBe(1);
     expect(hasSettledWatchdog(record.id)).toBe(true);
   });
 
-  it("onMidTimeout: kills the child, fails the round, error carries 'settled watchdog' marker and recovery hint", async () => {
+  it("onMidTimeout: kills the child (engine cancel), fails the round, error carries 'settled watchdog' marker and recovery hint", async () => {
     // fake timers 必须先于 arm 生效（useFakeTimers 不接管已存在的真实 timer）
     vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
     const record = makeRecord({ id: "sa-hot-timeout" });
     store.register(record);
-    spawnedMap.set(record.id, new FakeChild());
     await deliverChat(service, record, "hello", false);
     expect(hasSettledWatchdog(record.id)).toBe(true);
 
-    // [D9 两段式] 热路径 prompt 发出后挂中段：静默满中段窗长触发（本测试 mock 了
-    // session-runner，无 stdout pump 驱动事件刷新/交棒，中段静默形态直达）
+    // [D9 两段式] 热路径 prompt 发出后挂中段：静默满中段窗长触发（本测试替身不驱动
+    // 协议事件，中段静默形态直达）
     await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS + 1);
 
     // kill 收敛入口被触发（onTimeout 第一步）
@@ -283,59 +261,11 @@ describe("T2③ hot-path settled watchdog", () => {
     expect(record.result).toContain("action:'list'");
     // 失败通知送达（内核直发路径）
     expect(pi.sendMessage).toHaveBeenCalled();
-    const notifyContent = (pi.sendMessage.mock.calls[0]?.[0] as { content?: string } | undefined)?.content ?? "";
+    const sendMessageCalls = (pi.sendMessage as unknown as ReturnType<typeof vi.fn>).mock.calls as Array<[{ content?: string }]>;
+    const notifyContent = sendMessageCalls[0]?.[0]?.content ?? "";
     expect(notifyContent).toContain("settled watchdog");
-  });
-});
-
-describe("T2⑧ non-EPIPE hot-path failure re-arms idle timer", () => {
-  let agentDir: string;
-  let service: SubagentService;
-  let store: RecordStore;
-
-  beforeEach(() => {
-    vi.restoreAllMocks();
-    killChildSpy.mockClear();
-    ({ agentDir, service, store } = setup());
-  });
-
-  afterEach(() => {
-    _resetLifecycleState();
-    _resetSettledWatchdogsForTest();
-    spawnedMap.clear();
-    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
-  });
-
-  it("re-arms the idle timer (default duration) and rethrows on non-EPIPE write failure", async () => {
-    const record = makeRecord({ id: "sa-nonpipe" });
-    store.register(record);
-    spawnedMap.set(record.id, new FakeChild());
-    sendPromptCommandMock.mockImplementation(() => {
-      throw new Error("write after end: ERR_STREAM_DESTROYED");
-    });
-
-    await expect(deliverChat(service, record, "hello", false)).rejects.toThrow(/ERR_STREAM_DESTROYED/);
-
-    // 防泄漏前提恢复：入口 disarm 过的 idle timer 被 re-arm（进程不再裸奔）
-    expect(hasIdleTimer(record.id)).toBe(true);
-    expect(loggerMock.warn).toHaveBeenCalledWith(
-      expect.stringContaining("idle timer re-armed"),
-      expect.objectContaining({ detail: expect.stringContaining("ERR_STREAM_DESTROYED") }),
-    );
-  });
-
-  it("falls back to DEFAULT idle duration (visible) when record.idleTimeoutMs is invalid", async () => {
-    const record = makeRecord({ id: "sa-nonpipe-bad" });
-    // 直接注入非法值模拟「入口校验前已存在的 record」/ 回归形态：re-arm 首选值非法 →
-    // 降级挂 DEFAULT（防御性兜底可见，不静默不挂）
-    (record as { idleTimeoutMs: number }).idleTimeoutMs = 3_000_000_000;
-    store.register(record);
-    spawnedMap.set(record.id, new FakeChild());
-    sendPromptCommandMock.mockImplementation(() => {
-      throw new Error("ERR_STREAM_DESTROYED");
-    });
-
-    await expect(deliverChat(service, record, "hello", false)).rejects.toThrow(/ERR_STREAM_DESTROYED/);
-    expect(hasIdleTimer(record.id)).toBe(true);
+    // [W3] 引擎侧终止意图（fire-and-forget；fake timers 下只断言受理动作已发出）
+    const cancel = fake.interacts.find((c) => c.action.kind === "cancel");
+    expect(cancel).toBeDefined();
   });
 });

package/src/execution/__tests__/subagent-service.test.ts

@@ -323,7 +323,7 @@ describe("SubagentService", () => {
   // [背景] Pi 单进程 session 串行接管。session A shutdown 发 SIGTERM 后、子进程彻底
   // close 前（graceful shutdown 窗口几十~几百 ms），子进程的 trailing extension_ui_request
   // 仍会被父进程 pump 解析，调到 A 的 handler 闭包（仍持有 A 的 ctx）。旧实现 dispose 不清
-  // uiRequestHandler，该闭包触发 ui-request-queue.ts catch 分支打 `[subagents] uiRequestHandler
+  // uiRequestHandler，该闭包触发 inproc UI 请求队列（已删） catch 分支打 `[subagents] uiRequestHandler
   // threw` 误导性 console.error。dispose 现注入 stub（始终返回 {cancelled:true}），让 trailing
   // ui_request 干净降级，不再走旧 handler 闭包。
   //
@@ -376,7 +376,7 @@ describe("SubagentService", () => {
 
       // 关键价值断言：无 "[subagents] uiRequestHandler threw" 误导性噪声
       // （旧实现 dispose 不清 handler 时，trailing ui_request 走 staleHandler 抛错 →
-      //   ui-request-queue.ts catch 打该日志。stub 覆盖后该路径不再触发。）
+      //   inproc UI 请求队列（已删） catch 打该日志。stub 覆盖后该路径不再触发。）
       const subagentsErrors = errorSpy.mock.calls.filter(
         (args: unknown[]) => typeof args[0] === "string" && args[0].includes("[subagents]"),
       );

package/src/execution/__tests__/subprocess-agent-runner-routing.test.ts

@@ -15,11 +15,16 @@ import * as path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { AgentCallOpts, AgentResult } from "../../orchestration/models/types.ts";
-import type { RunContext, EnginePort } from "../engine/port.ts";
+import type { EnginePort, RunContext } from "../engine/port.ts";
 import { clearEngines, registerEngine } from "../engine/registry.ts";
-import type { ProbeReport } from "../engine/types.ts";
+import type { AgentOutcome, EngineCapabilities, ProbeReport } from "../engine/types.ts";
 import { ModelConfigService, setModelConfigService } from "../model-config-service.ts";
-import { getChildByRecord } from "../engine/engines/pi/session-runner.ts";
+// W10（§2.10 ②）：子进程句柄断言改读 core 侧状态镜像（host/spawned-children——
+// 协议化后 spawnedChildren 持有方在引擎进程，core 消费镜像面；判据 pid 同构）。
+import {
+  coreSpawnedChildrenMirror,
+  _resetCoreSpawnedChildrenMirrorForTest,
+} from "../engine/host/spawned-children.ts";
 import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
 import type { SubagentService } from "../subagent-service.ts";
 import type { ExecuteOptions } from "../types.ts";
@@ -88,13 +93,86 @@ function makeMockPiService() {
     executeOpts.push(opts);
     return { content: "from-pi", durationMs: 1, toolCalls: [] };
   });
-  // [D4 聚合连带] SAR 构造器经 asEngineService 显式视图取 PiEngineService——fake 的
+  // [D4 聚合连带] SAR 构造器经 asEngineService 显式视图取引擎服务面——fake 的
   // face 即自身，getter 直接返回 self。
   const service = { executeAndAwait } as unknown as SubagentService & { asEngineService: unknown };
   (service as { asEngineService: unknown }).asEngineService = service;
+  // [W3] 登记当前 mock 服务——委托式替身 port 的工厂闭包按它路由（getEngine 惰性）。
+  currentPiService = service as unknown as SubagentService;
   return { service, executeOpts, executeAndAwait };
 }
 
+// ── [W3] 委托式替身 pi port（原 inproc PiEngine 的 workflow 分支形态）──
+// run() 还原引擎内 task→ExecuteOptions 映射（含 engine='pi' 留痕与 engineFallback
+// 透传——两断言的契约面）后委托 mock 服务的 executeAndAwait。
+
+let currentPiService: SubagentService | undefined;
+
+function piTaskToExecuteOptions(task: AgentCallOpts, ctx: RunContext): ExecuteOptions {
+  const rawSlug = task.description ?? task.agent ?? "workflow-agent";
+  return {
+    task: task.prompt,
+    slug: rawSlug.length > 35 ? rawSlug.slice(0, 35) : rawSlug,
+    agent: task.agent,
+    model: task.model,
+    thinkingLevel: task.thinkingLevel,
+    skillPath: task.skillPath,
+    appendSystemPrompt: task.appendSystemPrompt,
+    schema: task.schema,
+    schemaEnv: task.schemaEnv,
+    maxTurns: task.maxTurns,
+    graceTurns: task.graceTurns,
+    ctxModel: ctx.ctxModel,
+    fork: task.fork,
+    worktree: task.worktree,
+    cwd: task.cwd,
+    conversation: task.conversation,
+    idleTimeoutMs: task.idleTimeoutMs,
+    // P4 引擎留痕（D9①）：实际执行引擎 id 恒 pi（原 PiEngine.run workflow 分支同款）
+    engine: "pi",
+    ...(ctx.engineFallback !== undefined ? { engineFallback: ctx.engineFallback } : {}),
+  };
+}
+
+function makeDelegatingPiPort(getService: () => SubagentService | undefined): EnginePort {
+  return {
+    id: "pi",
+    capabilities: (): EngineCapabilities => ({
+      schemaEnforcement: "native",
+      steer: "unsupported",
+      conversation: "native",
+      personaInjection: "flag",
+      eventGranularity: "stream",
+      sandbox: "emulated",
+      sessionRead: "full",
+      resume: "native",
+      interrupt: "kill-only",
+      permissionMode: "native",
+      maxTurns: true,
+    }),
+    probe: async (): Promise<ProbeReport> => ({ ok: true, engineVersion: "fake", checks: [] }),
+    run: async (task, ctx) => {
+      const service = getService();
+      if (service === undefined) throw new Error("mock pi service not installed");
+      const result = await (service as unknown as {
+        executeAndAwait: (opts: ExecuteOptions, signal?: AbortSignal) => Promise<AgentResult>;
+      }).executeAndAwait(piTaskToExecuteOptions(task, ctx), ctx.signal);
+      const outcome: AgentOutcome = {
+        content: result.content,
+        durationMs: result.durationMs,
+        error: result.error,
+        engineId: "pi",
+      };
+      return {
+        handle: { data: { v: 1, engineId: "pi", sessionRef: {}, poolKey: "shared", adapterVersion: "fake-sar" } },
+        outcome,
+      };
+    },
+    interact: async () => ({ ok: false, code: "engine_interact_failed", message: "not supported in this test" }),
+    read: async () => ({ engineId: "pi", turns: [], source: "outcome-only" }),
+  };
+}
+
 // ── 环境 ──
 
 let tmpRoot: string;
@@ -128,6 +206,7 @@ function installModelService(cfg?: Record<string, unknown>): void {
 }
 
 beforeEach(() => {
+  _resetCoreSpawnedChildrenMirrorForTest();
   tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "sar-routing-"));
   agentDir = path.join(tmpRoot, "pi-agent");
   fs.mkdirSync(agentDir, { recursive: true });
@@ -135,6 +214,10 @@ beforeEach(() => {
   prevDataDirEnv = process.env["XYZ_AGENT_DATA_DIR"];
   process.env["XYZ_AGENT_DATA_DIR"] = path.join(tmpRoot, "engine-data");
   clearEngines();
+  currentPiService = undefined;
+  // [U-2 一致性修复 → W3] resolveHostPiEnginePort 对已注册 port 原样返回——登记
+  // 委托式替身 pi port（registry 命中即路由命中；mock 服务的 DI 语义保持不变）。
+  registerEngine("pi", () => makeDelegatingPiPort(() => currentPiService));
 });
 
 afterEach(() => {
@@ -327,10 +410,11 @@ describe("SAR 路由集成（P4 验收 1/2/3）", () => {
     // 引擎回调（真实引擎在 spawn 成功后同步调）→ 按 taskId（'sa-' 记账 key）注册可见
     const child = spawn(process.execPath, ["-e", ""]);
     ctx?.onChildSpawned?.(child);
-    expect(getChildByRecord(ctx.taskId)).toBe(child);
-    // 子进程退出（真实 close 事件）后记账按句移除——不残留死句柄
+    expect(coreSpawnedChildrenMirror().getChildByRecord(ctx.taskId)?.pid).toBe(child.pid);
+    // 按句移除断言（W10 注）：inproc 双模下子进程退出不回灌 host/childStateChanged
+    // （该通道是 cli 协议形态专属）——镜像移除断言由 protocol-blackbox 的
+    // childStateChanged 用例承载；此处等待 close 仅保证进程面收口不悬挂。
     await new Promise<void>((resolve) => child.once("close", () => resolve()));
-    expect(getChildByRecord(ctx.taskId)).toBeUndefined();
   });
 
   // ── [D3-④] SAR 路径预检（capabilities 驱动；唯一有意行为变化 = zcode+worktree）──
@@ -384,3 +468,21 @@ describe("SAR 路由集成（P4 验收 1/2/3）", () => {
     expect(pi.executeOpts[0]?.maxTurns).toBe(3);
   });
 });
+
+// [U-2 一致性修复] D4 错误契约：pi 未注册（引擎包未装/发现失败）时普通 run 路径
+// 不再静默直构 inproc——派发期显式 engine_not_found + 安装指引（与 zcode 对称）。
+describe("pi 未注册 → engine_not_found（D4 契约，U-2 修复锚定）", () => {
+  it("pi 不在 registry → run 结果 error 含 engine_not_found + 安装指引，不静默走 inproc", async () => {
+    clearEngines(); // 覆盖 beforeEach 的 inproc pi 登记——模拟发现失败/未装包
+    installModelService();
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts(), new AbortController().signal);
+
+    expect(result.error).toContain("engine_not_found");
+    expect(result.error).toContain("No engine packages were discovered");
+    expect(result.error).toMatch(/install an engine package/i);
+    expect(pi.executeAndAwait).not.toHaveBeenCalled();
+  });
+});