@zhushanwen/subagent-core 0.4.0 → 0.6.0

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

@@ -5,9 +5,12 @@
 //     收敛到 killRecordChildWithEscalation（spy 断言调用点与参数）；
 //   - T2⑥/PS-1：disposeAllRecords 补三回收面（controller.abort + kill + disarm idle timer
 //     + disarm settled watchdog）；
-//   - T2③/LC-1：deliverMessage 热路径 armSettledWatchdog（挂载 + 到期 onTimeout 处置：
-//     kill + 失败终态化 + error 含 'settled watchdog' 标记与恢复指引）；
-//   - T2⑧/PS-3：deliverMessage 非 EPIPE 失败 re-arm idle timer（进程不再裸奔）。
+//   - 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——编排层无法区分错误类别）。
 //
 // mock 形态沿用 subagent-service-message-close.test.ts（真实 SubagentService + ServiceInternals
 // cast 暴露 store + mock session-runner/stdin-writer/logger）。
@@ -24,8 +27,8 @@ const { loggerMock } = vi.hoisted(() => ({
 vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
 // killRecordChildWithEscalation 换 spy（收敛调用点断言）；spawnedChildren 用真 Map
-//（deliverMessage 热路径判定 / EPIPE 兜底按值删除的消费者）；getChildByRecord 从同
-// 一 Map 查（mock 工厂与测试共享同一实例）。
+//（热路径投递判定 / EPIPE 兜底按值删除的消费者）；getChildByRecord 从同一 Map 查
+//（mock 工厂与测试共享同一实例）。D2 后模块物理下沉 engines/pi/（mock 路径随迁）。
 const { killChildSpy, spawnedMap, getChildByRecordMock } = vi.hoisted(() => {
   const map = new Map<string, unknown>();
   return {
@@ -34,7 +37,7 @@ const { killChildSpy, spawnedMap, getChildByRecordMock } = vi.hoisted(() => {
     getChildByRecordMock: vi.fn((recordId: string) => map.get(recordId)),
   };
 });
-vi.mock("../session-runner.ts", () => ({
+vi.mock("../engine/engines/pi/session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: getChildByRecordMock,
@@ -45,7 +48,7 @@ vi.mock("../session-runner.ts", () => ({
 
 // sendPromptCommand 换 spy（控制热路径写成功 / 抛非 EPIPE 错误）。
 const { sendPromptCommandMock } = vi.hoisted(() => ({ sendPromptCommandMock: vi.fn() }));
-vi.mock("../stdin-writer.ts", () => ({
+vi.mock("../engine/engines/pi/stdin-writer.ts", () => ({
   sendPromptCommand: sendPromptCommandMock,
   clearEpipeFailure: vi.fn(),
   recordEpipeFailure: vi.fn(() => 1),
@@ -59,7 +62,7 @@ import { ModelConfigService } from "../model-config-service.ts";
 import type { RecordStore } from "../record-store.ts";
 import { SubagentService } from "../subagent-service.ts";
 import type { PiLike } from "../subagent-service.ts";
-import { armSettledWatchdog, hasSettledWatchdog, SETTLED_WATCHDOG_TIMEOUT_MS, _resetSettledWatchdogsForTest } from "../settled-watchdog.ts";
+import { armSettledWatchdog, hasSettledWatchdog, SETTLED_MID_ROUND_NO_PROGRESS_MS, _resetSettledWatchdogsForTest } from "../settled-watchdog.ts";
 import { armIdleTimer, hasIdleTimer, _resetLifecycleState } from "../lifecycle-manager.ts";
 import type { ExecutionRecord } from "../types.ts";
 
@@ -108,7 +111,7 @@ type MockPi = ReturnType<typeof makePi>;
 
 function setup(): { agentDir: string; service: SubagentService; store: RecordStore; pi: MockPi } {
   const agentDir = makeTmpAgentDir();
-  const modelService = new ModelConfigService({ agentDir });
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
   const service = new SubagentService({ cwd: agentDir, modelService });
   const pi = makePi();
   service.initSession({ pi, sessionId: "root-session" });
@@ -121,6 +124,26 @@ function privateFn<K extends string>(service: SubagentService, key: K): (...args
   return (service as unknown as Record<string, (...args: never[]) => unknown>)[key];
 }
 
+/**
+ * message 投递入口（D2 后形态：编排层私有 deliverChatMessage → PiEngine.interactRecord
+ * → deliverPrompt；旧直调形态 deliverMessage 已随协议知识下沉删除）。
+ */
+async function deliverChat(
+  service: SubagentService,
+  record: ExecutionRecord,
+  text: string,
+  interrupt: boolean,
+): Promise<void> {
+  return (
+    privateFn(service, "deliverChatMessage") as (
+      this: SubagentService,
+      r: ExecutionRecord,
+      t: string,
+      i: boolean,
+    ) => Promise<void>
+  ).call(service, record, text, interrupt);
+}
+
 describe("T2④ service-side kill convergence", () => {
   let agentDir: string;
   let service: SubagentService;
@@ -138,7 +161,7 @@ describe("T2④ service-side kill convergence", () => {
     _resetLifecycleState();
     _resetSettledWatchdogsForTest();
     spawnedMap.clear();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("cancelBackground (via cancel) routes through killRecordChildWithEscalation", async () => {
@@ -156,7 +179,7 @@ describe("T2④ service-side kill convergence", () => {
     spawnedMap.set(record.id, new FakeChild());
     armIdleTimer(record.id, () => {}); // Path A：idle timer armed（进程保活）
     armSettledWatchdog(record.id, () => {});
-    await service.closeSubagent(record, false);
+    await service["closeSubagent"](record, false);
     expect(killChildSpy).toHaveBeenCalledWith(record.id, "closeChatIdle");
     expect(hasIdleTimer(record.id)).toBe(false);
     expect(hasSettledWatchdog(record.id)).toBe(false);
@@ -223,28 +246,30 @@ describe("T2③ hot-path settled watchdog", () => {
     _resetLifecycleState();
     _resetSettledWatchdogsForTest();
     spawnedMap.clear();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    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 service.deliverMessage(record, "hello", false);
+    await deliverChat(service, record, "hello", false);
     expect(sendPromptCommandMock).toHaveBeenCalledTimes(1);
     expect(hasSettledWatchdog(record.id)).toBe(true);
   });
 
-  it("onTimeout: kills the child, fails the round, error carries 'settled watchdog' marker and recovery hint", async () => {
+  it("onMidTimeout: kills the child, 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 service.deliverMessage(record, "hello", false);
+    await deliverChat(service, record, "hello", false);
     expect(hasSettledWatchdog(record.id)).toBe(true);
 
-    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS + 1);
+    // [D9 两段式] 热路径 prompt 发出后挂中段：静默满中段窗长触发（本测试 mock 了
+    // session-runner，无 stdout pump 驱动事件刷新/交棒，中段静默形态直达）
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS + 1);
 
     // kill 收敛入口被触发（onTimeout 第一步）
     expect(killChildSpy).toHaveBeenCalledWith(record.id, "settled watchdog (hot path)");
@@ -278,7 +303,7 @@ describe("T2⑧ non-EPIPE hot-path failure re-arms idle timer", () => {
     _resetLifecycleState();
     _resetSettledWatchdogsForTest();
     spawnedMap.clear();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    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 () => {
@@ -289,7 +314,7 @@ describe("T2⑧ non-EPIPE hot-path failure re-arms idle timer", () => {
       throw new Error("write after end: ERR_STREAM_DESTROYED");
     });
 
-    await expect(service.deliverMessage(record, "hello", false)).rejects.toThrow(/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);
@@ -303,14 +328,14 @@ describe("T2⑧ non-EPIPE hot-path failure re-arms idle timer", () => {
     const record = makeRecord({ id: "sa-nonpipe-bad" });
     // 直接注入非法值模拟「入口校验前已存在的 record」/ 回归形态：re-arm 首选值非法 →
     // 降级挂 DEFAULT（防御性兜底可见，不静默不挂）
-    record.idleTimeoutMs = 3_000_000_000;
+    (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(service.deliverMessage(record, "hello", false)).rejects.toThrow(/ERR_STREAM_DESTROYED/);
+    await expect(deliverChat(service, record, "hello", false)).rejects.toThrow(/ERR_STREAM_DESTROYED/);
     expect(hasIdleTimer(record.id)).toBe(true);
   });
 });

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

@@ -36,18 +36,18 @@ function makeTmpAgentDir(): string {
 }
 
 function makeModelService(agentDir: string): ModelConfigService {
-  return new ModelConfigService({ agentDir });
+  return new ModelConfigService({ agentDir, cwd: agentDir });
 }
 
 function makePi(): PiLike & {
-  appendEntry: ReturnType<typeof vi.fn>;
-  events: { emit: ReturnType<typeof vi.fn> };
-  sendMessage: ReturnType<typeof vi.fn>;
+  appendEntry: ReturnType<typeof vi.fn<(customType: string, data?: unknown) => void>>;
+  events: { emit: ReturnType<typeof vi.fn<(channel: string, data: unknown) => void>> };
+  sendMessage: ReturnType<typeof vi.fn<(message: Parameters<PiLike["sendMessage"]>[0], options?: Parameters<PiLike["sendMessage"]>[1]) => void>>;
 } {
   return {
-    appendEntry: vi.fn(),
-    events: { emit: vi.fn() },
-    sendMessage: vi.fn(),
+    appendEntry: vi.fn((customType: string, data?: unknown) => {}),
+    events: { emit: vi.fn((channel: string, data: unknown) => {}) },
+    sendMessage: vi.fn(() => {}),
   };
 }
 
@@ -61,7 +61,7 @@ describe("SubagentService", () => {
   });
 
   afterEach(() => {
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   // ============================================================
@@ -75,7 +75,7 @@ describe("SubagentService", () => {
 
     it("未 initSession 时 findRecord/cancel 抛 'pi not injected'", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
-      expect(() => service.findRecord("any")).toThrow(/pi not injected/);
+      expect(() => service.queries.findRecord("any")).toThrow(/pi not injected/);
       expect(() => service.cancel("any")).toThrow(/pi not injected/);
     });
 
@@ -83,7 +83,7 @@ describe("SubagentService", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
       // findRecord 现在能过 assertReady,但 record 不存在 → 返回 undefined
-      expect(service.findRecord("missing")).toBeUndefined();
+      expect(service.queries.findRecord("missing")).toBeUndefined();
     });
 
     it("dispose 后 findRecord 抛含 'disposed' 且带恢复指引", () => {
@@ -92,8 +92,8 @@ describe("SubagentService", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
       service.dispose();
-      expect(() => service.findRecord("any")).toThrow(/disposed/);
-      expect(() => service.findRecord("any")).toThrow(/session ended|session_start|new session/i);
+      expect(() => service.queries.findRecord("any")).toThrow(/disposed/);
+      expect(() => service.queries.findRecord("any")).toThrow(/session ended|session_start|new session/i);
     });
 
     it("dispose 幂等(多次调用不抛)", () => {
@@ -113,7 +113,7 @@ describe("SubagentService", () => {
       // revive
       service.initSession({ pi: makePi(), sessionId: "s2" });
       // 现在 assertReady 又通过(findRecord 返回 undefined 而非 disposed)
-      expect(service.findRecord("any")).toBeUndefined();
+      expect(service.queries.findRecord("any")).toBeUndefined();
     });
   });
 
@@ -125,7 +125,7 @@ describe("SubagentService", () => {
     it("findRecord 不存在的 id 返回 undefined", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
-      expect(service.findRecord("nonexistent-id")).toBeUndefined();
+      expect(service.queries.findRecord("nonexistent-id")).toBeUndefined();
     });
 
     it("cancel 不存在的 id 返回 false(不抛错,boolean 契约不变)", () => {
@@ -140,16 +140,13 @@ describe("SubagentService", () => {
   // ============================================================
 
   describe("状态查询", () => {
-    it("listRunning 初始为空数组", () => {
-      const service = new SubagentService({ cwd: agentDir, modelService });
-      service.initSession({ pi: makePi(), sessionId: "s1" });
-      expect(service.listRunning()).toEqual([]);
-    });
+    // [D4] listRunning 已从 Service 删除（零生产调用方）——初始空态语义由
+    // collectRecords 用例与 store 层 listRunning 测试覆盖。
 
     it("collectRecords 返回数组(空 sessions 目录时为空)", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
-      const records = service.collectRecords(100);
+      const records = service.queries.collectRecords(100);
       expect(Array.isArray(records)).toBe(true);
     });
 
@@ -157,7 +154,7 @@ describe("SubagentService", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
       const listener = vi.fn();
-      const unsubscribe = service.onChange(listener);
+      const unsubscribe = service.queries.onChange(listener);
       expect(typeof unsubscribe).toBe("function");
       expect(() => unsubscribe()).not.toThrow();
     });
@@ -218,6 +215,7 @@ describe("SubagentService", () => {
         agent: "general-purpose",
         model: "test/model",
         mode: "background",
+        slug: "t",
         task: "long task",
         startedAt: 1_000_000,
         rootSessionId: "s1",
@@ -233,8 +231,9 @@ describe("SubagentService", () => {
       const record = createRecord(id, {
         agent: "general-purpose",
         model: "test/model",
-        mode: "sync",
+        mode: "background",
         task: "sync task",
+        slug: "test",
         startedAt: 1_000_000,
         rootSessionId: "s1",
         // sync 不传 controller → controller === undefined
@@ -250,13 +249,14 @@ describe("SubagentService", () => {
         agent: "general-purpose",
         model: "test/model",
         mode: "background",
+        slug: "t",
         task: "done task",
         startedAt: 1_000_000,
         rootSessionId: "s1",
         controller,
       });
       // 直接改 status 模拟终态（不走 CAS——测试不关心状态机，只关心 dispose 的 abort 过滤）
-      record.status = "done";
+      record.status = "closed";
       getStore(service).register(record);
       return record;
     }
@@ -362,7 +362,8 @@ describe("SubagentService", () => {
 
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
-      service.setUiRequestHandler(staleHandler);
+      // [D4-④] setUiRequestHandler 已删——handler 注入走 initSession 参数（唯一入口）
+      service.initSession({ pi: makePi(), sessionId: "s1", uiRequestHandler: staleHandler });
 
       service.dispose();
 
@@ -427,6 +428,7 @@ describe("SubagentService", () => {
       try {
         await service.execute({
           task: "worktree without fork (decoupled)",
+          slug: "test",
           worktree: true,
           fork: false,
           ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
@@ -443,6 +445,7 @@ describe("SubagentService", () => {
       try {
         await service.execute({
           task: "worktree with fork",
+          slug: "test",
           worktree: true,
           fork: true,
           ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
@@ -460,6 +463,7 @@ describe("SubagentService", () => {
       try {
         await service.execute({
           task: "default path",
+          slug: "test",
           worktree: false,
           fork: false,
           ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
@@ -473,7 +477,7 @@ describe("SubagentService", () => {
     // ============================================================
     // create-await 竞态守卫（Phase 2）：create 的 await 窗口内 dispose/cancel
     // 可把 record CAS 成 closed——守卫须主动 cleanup + early-failed 返回，不 kickOff。
-    // 实现约束固化：「赋值 record.worktreeHandle → 终态检查 → kickOffBackground」
+    // 实现约束固化：「赋值 record.worktreeHandle → 终态检查 → 轮次 kick-off」
     // 必须同一同步段（中间禁止 await），本用例即该不变量的回归锚点。
     // ============================================================
     it("守卫：create await 窗口内 dispose 抢先 → cleanup 被调 + early-failed 返回（不 kickOff）", async () => {
@@ -487,12 +491,13 @@ describe("SubagentService", () => {
       }) as Parameters<WorktreeManager["cleanup"]>[0];
       let resolveCreate!: (h: unknown) => void;
       vi.spyOn(wtm, "create").mockImplementation(
-        () => new Promise((r) => { resolveCreate = r; }) as ReturnType<WorktreeManager["create"]>,
+        () => new Promise<unknown>((r) => { resolveCreate = r; }) as ReturnType<WorktreeManager["create"]>,
       );
       const cleanupSpy = vi.spyOn(wtm, "cleanup").mockResolvedValue(undefined);
 
       const execP = service.execute({
         task: "guard test",
+        slug: "test",
         worktree: true,
         fork: false,
         ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
@@ -529,7 +534,7 @@ describe("SubagentService", () => {
   //
   // [未覆盖路径] 需 mock spawn 才能跑完 runSpawn 的路径，本文件约定不 mock spawn
   // （见文件头——execute 集成测试在 execute-nesting.test.ts / run-spawn-integration.test.ts）：
-  //   - finalizeRecord status="done"（sync/background 正常完成 → unregister(done)）
+  //   - finalizeRecord status="closed"（background 正常完成 → unregister(closed)）
   //   - finalizeRecord status="cancelled" 经 runAndFinalize 路径（cancel 抢先 CAS 时
   //     runAndFinalize 侧 tryTransition 失败跳过 finalizeRecord，由 cancelBackground 侧 emit——
   //     本块 cancel 用例覆盖的即此后端 emit）
@@ -572,6 +577,7 @@ describe("SubagentService", () => {
         agent: "general-purpose",
         model: "test/model",
         mode: "background",
+        slug: "t",
         task: "cancel target",
         startedAt: 1_000_000,
         rootSessionId: "s1",
@@ -588,12 +594,13 @@ describe("SubagentService", () => {
 
       const handle = await service.execute({
         task: "wt fail bg",
+        slug: "test",
         worktree: true,
         fork: true,
         ctxModel,
       });
 
-      // worktree create 抛错在 kickOffBackground 之前（execute 同步 catch），返回 background 形状
+      // worktree create 抛错在轮次 kick-off 之前（executeViaEngine 同步 catch），返回 background 形状
       expect(handle.mode).toBe("background");
 
       // createRecordForMode 生成的 subagentId 带 sa- 前缀（sa-<uuid>）
@@ -670,7 +677,7 @@ describe("SubagentService", () => {
       injectRunningBackground(service, "bg-running-1");
       injectRunningBackground(service, "bg-running-2");
       const terminal = injectRunningBackground(service, "bg-done");
-      terminal.status = "done"; // 模拟终态，dispose 不应为其 emit
+      terminal.status = "closed"; // 模拟终态，dispose 不应为其 emit
 
       service.dispose();
 
@@ -704,7 +711,7 @@ describe("ModelConfigService ctxModel 缓存", () => {
     agentDir = makeTmpAgentDir();
   });
   afterEach(() => {
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** 最小 mock registry:空可用列表(ctxModel 路径不需要 lookup)。 */

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

@@ -15,11 +15,11 @@ 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 } from "../engine/port.ts";
+import type { RunContext, EnginePort } from "../engine/port.ts";
 import { clearEngines, registerEngine } from "../engine/registry.ts";
-import type { EnginePort, ProbeReport } from "../engine/types.ts";
+import type { ProbeReport } from "../engine/types.ts";
 import { ModelConfigService, setModelConfigService } from "../model-config-service.ts";
-import { getChildByRecord } from "../session-runner.ts";
+import { getChildByRecord } from "../engine/engines/pi/session-runner.ts";
 import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
 import type { SubagentService } from "../subagent-service.ts";
 import type { ExecuteOptions } from "../types.ts";
@@ -31,7 +31,10 @@ interface FakeEngineCalls {
   runs: Array<{ taskSpec: unknown; ctx: RunContext }>;
 }
 
-function makeFakeZcodeEngine(probeOk: boolean): { engine: EnginePort; calls: FakeEngineCalls } {
+/** fake zcode 引擎的池 key 缺省值（机制跟随性用例：任意 key 落对应目录）。 */
+const FAKE_POOL_KEY = "home-test-provider-m1";
+
+function makeFakeZcodeEngine(probeOk: boolean, poolKey: string = FAKE_POOL_KEY): { engine: EnginePort; calls: FakeEngineCalls } {
   const calls: FakeEngineCalls = { probed: 0, runs: [] };
   const engine: EnginePort = {
     id: "zcode",
@@ -46,6 +49,7 @@ function makeFakeZcodeEngine(probeOk: boolean): { engine: EnginePort; calls: Fak
       resume: "cold",
       interrupt: "kill-only",
       permissionMode: "native",
+      maxTurns: false,
     }),
     probe: () => {
       calls.probed++;
@@ -62,11 +66,11 @@ function makeFakeZcodeEngine(probeOk: boolean): { engine: EnginePort; calls: Fak
     run: (taskSpec, ctx) => {
       calls.runs.push({ taskSpec, ctx });
       // 对齐点③模拟：prepare 期声明池 key → 事件 emit（zcode coarse 形态：终态后合成）
-      ctx.onPoolResolved?.("home-test-provider-m1");
+      ctx.onPoolResolved?.(poolKey);
       ctx.onEvent?.({ type: "message_end", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 } });
       ctx.onEvent?.({ type: "turn_end" });
       return Promise.resolve({
-        handle: { data: { v: 1, engineId: "zcode", sessionRef: {}, poolKey: "home-test-provider-m1", adapterVersion: "t" } },
+        handle: { data: { v: 1, engineId: "zcode", sessionRef: {}, poolKey, adapterVersion: "t" } },
         outcome: { engineId: "zcode", content: "from-zcode" },
       });
     },
@@ -84,7 +88,10 @@ function makeMockPiService() {
     executeOpts.push(opts);
     return { content: "from-pi", durationMs: 1, toolCalls: [] };
   });
-  const service = { executeAndAwait } as unknown as SubagentService;
+  // [D4 聚合连带] SAR 构造器经 asEngineService 显式视图取 PiEngineService——fake 的
+  // face 即自身，getter 直接返回 self。
+  const service = { executeAndAwait } as unknown as SubagentService & { asEngineService: unknown };
+  (service as { asEngineService: unknown }).asEngineService = service;
   return { service, executeOpts, executeAndAwait };
 }
 
@@ -134,7 +141,7 @@ afterEach(() => {
   if (prevDataDirEnv === undefined) delete process.env["XYZ_AGENT_DATA_DIR"];
   else process.env["XYZ_AGENT_DATA_DIR"] = prevDataDirEnv;
   clearEngines();
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 describe("SAR 路由集成（P4 验收 1/2/3）", () => {
@@ -163,13 +170,31 @@ describe("SAR 路由集成（P4 验收 1/2/3）", () => {
     expect(result.content).toBe("from-zcode");
     expect(calls.runs).toHaveLength(1);
     expect(pi.executeAndAwait).not.toHaveBeenCalled();
-    // 对齐点③断言：journal 落在引擎声明的池 key 目录（非 pi 'shared' 占位路径）
-    const poolDir = path.join(tmpRoot, "engine-data", "engines", "zcode", "home-test-provider-m1");
+    // 机制跟随性断言：journal 落在引擎声明的池 key 目录（任意 key 落对应目录——
+    // 真实 zcode 引擎 poolKey 恒 'shared'，对齐真实行为的断言见下一用例）
+    const poolDir = path.join(tmpRoot, "engine-data", "engines", "zcode", FAKE_POOL_KEY);
     const journals = fs.existsSync(poolDir) ? fs.readdirSync(poolDir) : [];
     expect(journals).toHaveLength(1);
     expect(journals[0]).toMatch(/^journal-sa-.+\.jsonl$/);
-    const sharedDir = path.join(tmpRoot, "engine-data", "engines", "zcode", "shared");
-    expect(fs.existsSync(sharedDir)).toBe(false); // 占位 poolKey 未产生错位落盘
+  });
+
+  it("journal 落盘对齐真实行为：poolKey 'shared' → engines/zcode/shared/journal-<taskId>.jsonl", async () => {
+    // 生产 zcode 引擎 poolKey 恒 'shared'（ZCODE_SHARED_POOL_KEY）——fake 以同 key
+    // 声明，断言 journal 精确落 shared 池目录（旧池化时代「shared 目录不存在」的
+    // 反向锚定已随池化删除，此处锚定现行正向语义）
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService();
+    const { engine, calls } = makeFakeZcodeEngine(true, "shared");
+    registerEngine("zcode", () => engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    await sar.run(makeOpts({ agent: agentRef }), new AbortController().signal);
+
+    const taskId = calls.runs[0]?.ctx.taskId;
+    expect(taskId).toMatch(/^sa-/);
+    const sharedPoolDir = path.join(tmpRoot, "engine-data", "engines", "zcode", "shared");
+    expect(fs.readdirSync(sharedPoolDir)).toEqual([`journal-${taskId}.jsonl`]);
   });
 
   it("调用参数 engine 覆盖 frontmatter（三层优先级落到 run，A7）", async () => {
@@ -307,4 +332,55 @@ describe("SAR 路由集成（P4 验收 1/2/3）", () => {
     await new Promise<void>((resolve) => child.once("close", () => resolve()));
     expect(getChildByRecord(ctx.taskId)).toBeUndefined();
   });
+
+  // ── [D3-④] SAR 路径预检（capabilities 驱动；唯一有意行为变化 = zcode+worktree）──
+
+  it("[D3-④] zcode + worktree:true → engine_capability_unsupported（workflow 域漏拦缺口修复），无 engine.run、无 journal 产物", async () => {
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService();
+    const { engine, calls } = makeFakeZcodeEngine(true);
+    registerEngine("zcode", () => engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts({ agent: agentRef, worktree: true }), new AbortController().signal);
+
+    expect(result.error).toContain("engine_capability_unsupported");
+    expect(result.error).toContain("worktree");
+    // 无进程创建 + 无 journal 落盘（拒绝在 wiring/run 之前）
+    expect(calls.runs).toHaveLength(0);
+    expect(pi.executeAndAwait).not.toHaveBeenCalled();
+    const enginesRoot = path.join(tmpRoot, "engine-data", "engines");
+    expect(fs.existsSync(enginesRoot) ? fs.readdirSync(enginesRoot) : []).toEqual([]);
+  });
+
+  it("[D3-④] zcode + maxTurns / fork → engine_capability_unsupported（现状行为保持的正向守护）", async () => {
+    const agentRef = writeAgentMd("reviewer", "name: reviewer\ndescription: d\nengine: zcode");
+    installModelService();
+    const { engine, calls } = makeFakeZcodeEngine(true);
+    registerEngine("zcode", () => engine);
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const maxTurnsResult = await sar.run(makeOpts({ agent: agentRef, maxTurns: 5 }), new AbortController().signal);
+    expect(maxTurnsResult.error).toContain("engine_capability_unsupported");
+    expect(maxTurnsResult.error).toContain("maxTurns");
+    expect(maxTurnsResult.error).toContain("capabilities.maxTurns = false");
+
+    const forkResult = await sar.run(makeOpts({ agent: agentRef, fork: true }), new AbortController().signal);
+    expect(forkResult.error).toContain("engine_capability_unsupported");
+    expect(forkResult.error).toContain("fork");
+    expect(calls.runs).toHaveLength(0);
+  });
+
+  it("[V4⑤ 反向] pi + maxTurns → 直通不拦（pi 既有合法能力零回归），executeAndAwait 收到 maxTurns", async () => {
+    installModelService();
+    const pi = makeMockPiService();
+    const sar = new SubprocessAgentRunner({ subagentService: pi.service });
+
+    const result = await sar.run(makeOpts({ maxTurns: 3 }), new AbortController().signal);
+
+    expect(result.content).toBe("from-pi");
+    expect(pi.executeOpts[0]?.maxTurns).toBe(3);
+  });
 });

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

@@ -0,0 +1,75 @@
+// src/execution/__tests__/subprocess-agent-runner-timeout.test.ts
+//
+// [D6 合流迁移] mergeTimeoutSignal（D-A9：per-call timeoutMs 合并进 AbortSignal）的
+// 行为测试——原定义在已删除的 execution/execute-options-mapper.ts（测试随迁），函数
+// 现居 subprocess-agent-runner.ts（唯一消费点，运行期件随消费方落位）。
+// 原用例编号（execute-options-mapper.test.ts 的 mergeTimeoutSignal describe，7 用例）
+// 与行为语义逐条保持。
+//
+// 接线测试（timeoutMs → engine 收到 merged signal → abort 收口）在
+// subprocess-agent-runner.test.ts 的 T3.6（经真实 PiEngine 链路），本文件锁纯函数行为。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { mergeTimeoutSignal } from "../subprocess-agent-runner.ts";
+
+describe("mergeTimeoutSignal (D-A9)", () => {
+  it("T3.6 timeoutMs===undefined → 原样返回 external signal", () => {
+    const ctrl = new AbortController();
+    const result = mergeTimeoutSignal(ctrl.signal, undefined);
+    expect(result).toBe(ctrl.signal);
+  });
+
+  it("T3.6 timeoutMs<=0 → 原样返回 external signal", () => {
+    const ctrl = new AbortController();
+    const result = mergeTimeoutSignal(ctrl.signal, 0);
+    expect(result).toBe(ctrl.signal);
+  });
+
+  it("T3.6 timeoutMs>0 → 返回新 signal（合并外部+超时两路）", () => {
+    const ctrl = new AbortController();
+    const result = mergeTimeoutSignal(ctrl.signal, 50);
+    expect(result).not.toBe(ctrl.signal);
+    expect(result.aborted).toBe(false);
+  });
+
+  it("T3.6 timeoutMs 到期 → merged signal abort", () => {
+    vi.useFakeTimers();
+    const ctrl = new AbortController();
+    const merged = mergeTimeoutSignal(ctrl.signal, 50);
+
+    expect(merged.aborted).toBe(false);
+    vi.advanceTimersByTime(51);
+    expect(merged.aborted).toBe(true);
+    vi.useRealTimers();
+  });
+
+  it("T3.6 外部 signal abort → merged signal abort", () => {
+    const ctrl = new AbortController();
+    const merged = mergeTimeoutSignal(ctrl.signal, 5000);
+    ctrl.abort();
+    expect(merged.aborted).toBe(true);
+  });
+
+  it("T3.6 外部 signal 已 abort → 返回已 abort 的 signal", () => {
+    const ctrl = new AbortController();
+    ctrl.abort();
+    const merged = mergeTimeoutSignal(ctrl.signal, 5000);
+    expect(merged.aborted).toBe(true);
+  });
+
+  it("T3.17 NFR: merged signal abort → timeout timer 清理", () => {
+    vi.useFakeTimers();
+    const ctrl = new AbortController();
+    const merged = mergeTimeoutSignal(ctrl.signal, 50);
+
+    ctrl.abort(); // 外部 abort → merged 也 abort
+    expect(merged.aborted).toBe(true);
+
+    // 推进时间，不应再有副作用
+    vi.advanceTimersByTime(100);
+    // timer 应被清理（通过 abort event listener）
+    // 无异常 = timer 已正确清理
+    vi.useRealTimers();
+  });
+});