@zhushanwen/subagent-core 0.4.0 → 0.5.1

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();
+  });
+});

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

@@ -11,7 +11,8 @@
 //   T3.7  (正常): onEvent 桥接 AgentEvent 透传
 //   T3.17 (NFR): mergeTimeoutSignal listener 清理
 //   T3.18 (NFR): dispose 兜底覆盖（delegate 后子进程进 spawnedChildren）
-//   T3.19 (NFR): AgentCallOpts→ExecuteOptions 映射保真
+//   T3.19 (NFR): AgentCallOpts→ExecuteOptions 直出保真（D6 合流后映射在 PiEngine 边界，
+//                本组用例经真实 PiEngine 链路锁定 spawn 参数形态）
 
 import { mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -26,9 +27,10 @@ import { configureCore, resetCoreForTests } from "../../core/host-services.ts";
 
 import type { AgentCallOpts, AgentResult } from "../../orchestration/models/types.ts";
 import { ModelConfigService, setModelConfigService } from "../model-config-service.ts";
-import type { ModelRegistryLike } from "../model-resolver.ts";
+import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
 import { replayJournal } from "../engine/common/event-journal.ts";
 import type { SubprocessAgentRunnerDeps } from "../subprocess-agent-runner.ts";
+import type { SubagentService } from "../subagent-service.ts";
 import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
 
 // ── 测试辅助 ──
@@ -46,17 +48,17 @@ function makeMockResult(overrides: Partial<AgentResult> = {}): AgentResult {
   };
 }
 
-/** 创建 mock SubagentService（只实现 executeAndAwait） */
-function createMockService(impl?: typeof vi.fn) {
+/** 创建 mock SubagentService（只实现 executeAndAwait）。
+ *  [D4 聚合连带] SAR 构造器经 asEngineService 显式视图取 PiEngineService——fake 的
+ *  face 即自身，getter 直接返回 self。 */
+function createMockService(impl?: typeof vi.fn): SubagentService {
   const executeAndAwait = impl ?? vi.fn().mockResolvedValue(makeMockResult());
-  return { executeAndAwait } as unknown as {
-    executeAndAwait: (
-      opts: Record<string, unknown>,
-      signal?: AbortSignal,
-      onEvent?: (e: Record<string, unknown>) => void,
-      stream?: unknown,
-    ) => Promise<AgentResult>;
-  };
+  // partial mock（仅 executeAndAwait + asEngineService self-引用）——SAR 测试路径
+  // 不触达其余成员，经 unknown 双跳收敛到 SubagentService 视图
+  const partial: { executeAndAwait: typeof executeAndAwait; asEngineService?: unknown } = { executeAndAwait };
+  const service = partial as unknown as SubagentService;
+  partial.asEngineService = service;
+  return service;
 }
 
 function makeBaseOpts(): AgentCallOpts {
@@ -171,7 +173,7 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
           return Promise.resolve(makeMockResult());
         }),
       );
-      const ctxModel = { id: "ctx-model", provider: "test", input: [] };
+      const ctxModel: ModelInfo = { id: "ctx-model", name: "Ctx Model", provider: "test", reasoning: false };
       const deps: SubprocessAgentRunnerDeps = { subagentService: mockService, ctxModel };
       const sar = new SubprocessAgentRunner(deps);
 
@@ -189,7 +191,7 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
           return Promise.resolve(makeMockResult());
         }),
       );
-      const ctxModel = { id: "ctx-model", provider: "test", input: [] };
+      const ctxModel: ModelInfo = { id: "ctx-model", name: "Ctx Model", provider: "test", reasoning: false };
       const deps: SubprocessAgentRunnerDeps = { subagentService: mockService, ctxModel };
       const sar = new SubprocessAgentRunner(deps);
 
@@ -225,7 +227,7 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
         const svc = new ModelConfigService({ agentDir: join(tmpRoot, "agent"), cwd: tmpRoot });
         svc.initModel({ modelRegistry: { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => false }, sessionId: "cleanup" });
         setModelConfigService(svc);
-        rmSync(tmpRoot, { recursive: true, force: true });
+        rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
         tmpRoot = "";
       }
       if (prevDataDir === undefined) delete process.env["XYZ_AGENT_DATA_DIR"];
@@ -305,8 +307,8 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
           return Promise.resolve(makeMockResult());
         }),
       );
-      const oldModel = { id: "old-model", provider: "test", input: [] };
-      const newModel = { id: "new-model", provider: "test", input: [] };
+      const oldModel: ModelInfo = { id: "old-model", name: "Old Model", provider: "test", reasoning: false };
+      const newModel: ModelInfo = { id: "new-model", name: "New Model", provider: "test", reasoning: false };
       const deps: SubprocessAgentRunnerDeps = { subagentService: mockService, ctxModel: oldModel };
       const sar = new SubprocessAgentRunner(deps);
 
@@ -453,7 +455,7 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
       } finally {
         if (prevEnv === undefined) delete process.env.XYZ_AGENT_DATA_DIR;
         else process.env.XYZ_AGENT_DATA_DIR = prevEnv;
-        rmSync(dataDir, { recursive: true, force: true });
+        rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
       }
     });
   });
@@ -491,8 +493,8 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
   // ────────────────────────────────────────────────
   // T3.19: AgentCallOpts → ExecuteOptions 映射保真
   // ────────────────────────────────────────────────
-  describe("T3.19 映射保真", () => {
-    it("prompt → task, agent → agent, schemaEnv 透传", async () => {
+  describe("T3.19 直出保真（D6：映射点在 PiEngine.agentCallToExecuteOptions，SAR 直传零映射）", () => {
+    it("prompt → task, agent → agent, schemaEnv 透传（经 pi 边界直出）", async () => {
       let capturedOpts: Record<string, unknown> | undefined;
       const mockService = createMockService(
         vi.fn().mockImplementation((opts: Record<string, unknown>) => {

package/src/execution/__tests__/temp-prompt.test.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 
 import { describe, expect, it } from "vitest";
 
-import { cleanupTempPrompt, writePromptToTempFile } from "../temp-prompt.ts";
+import { cleanupTempPrompt, writePromptToTempFile } from "../engine/engines/pi/temp-prompt.ts";
 
 describe("writePromptToTempFile", () => {
   it("创建临时目录 + 写入 prompt 文件", async () => {

package/src/execution/__tests__/timeout-integration.test.ts

@@ -89,7 +89,7 @@ vi.mock("../alive-store.ts", () => ({
   writeAliveMarker: vi.fn(),
 }));
 
-vi.mock("../temp-prompt.ts", () => ({
+vi.mock("../engine/engines/pi/temp-prompt.ts", () => ({
   writePromptToTempFile: vi.fn(async (agent: string) => {
     const safeName = agent.replace(/[^\w.-]+/g, "_");
     return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
@@ -108,7 +108,7 @@ import {
   runSpawn,
   SPAWN_WATCHDOG_ENV,
   type SessionRunnerContext,
-} from "../session-runner.ts";
+} from "../engine/engines/pi/session-runner.ts";
 
 const mockSpawn = vi.mocked(spawn);
 const mockExistsSync = vi.mocked(fs.existsSync);
@@ -160,8 +160,9 @@ function makeRecord() {
   return createRecord("run-1", {
     agent: "general-purpose",
     model: "test-model",
-    mode: "sync",
+    mode: "background",
     task: "do something",
+    slug: "test",
     startedAt: 1_000_000,
     rootSessionId: "root-session",
     parentRecordId: undefined,
@@ -351,8 +352,8 @@ describe("timeoutMs / signal abort → child.kill 端到端路径", () => {
       expect(child.killSignal).toBe("SIGTERM");
 
       // 子进程响应 SIGTERM 退出：exitCode 143（SIGTERM 终止形态）+ exit + close。
-      // exit 事件触发升级 timer clear（killChildWithEscalation 内 once("exit") 挂钩）。
-      child.exitCode = 143;
+      // exit 事件触发升级 timer clear（公共 kill-chain 的 exit 等待 promise settle → timer clear）。
+      (child as unknown as { exitCode: number }).exitCode = 143;
       child.emit("exit", 143);
       child.stdout.end();
       child.emit("close", 143);

package/src/execution/__tests__/turn-limiter-semantics.test.ts

@@ -5,7 +5,7 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { createTurnLimiter } from "../turn-limiter.ts";
+import { createTurnLimiter } from "../engine/engines/pi/turn-limiter.ts";
 
 describe("SP-9: turn-limiter chatMode semantics (maxTurns reset per round)", () => {
   describe("TC-1: chatMode 多轮后 maxTurns 每轮 reset（不累计）", () => {