@zhushanwen/subagent-core 0.2.0 → 0.5.1

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

@@ -3,7 +3,7 @@
 // timeoutMs / signal abort → child.kill 端到端路径测试。
 //
 // 背景：session-runner.ts 无独立 timeoutMs 字段——超时机制是 watchdog（基于
-// computeWatchdogMs(opts.maxTurns) 动态计算的下限 30min timer，兜底 SIGTERM）；
+// maxTurnsToWatchdogMs(opts.maxTurns) 动态计算的下限 30min timer，兜底 SIGTERM）；
 // 外部取消通过 opts.signal (AbortSignal) 传播：onAbort → child.kill("SIGTERM")。
 // 故「timeout 端到端路径」实际是 watchdog timer + signal abort → child.kill 两条链路。
 //
@@ -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` };
@@ -102,13 +102,13 @@ import * as fs from "node:fs";
 
 import { createRecord } from "../execution-record.ts";
 import {
-  computeWatchdogMs,
+  maxTurnsToWatchdogMs,
   type RunOptions,
   resolveSpawnWatchdogMs,
   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,
@@ -270,8 +271,8 @@ describe("timeoutMs / signal abort → child.kill 端到端路径", () => {
 
   // ── 1. watchdog 到期 → child.kill ──
   //
-  // [R1] watchdog = setTimeout(() => child.kill("SIGTERM"), computeWatchdogMs(maxTurns))。
-  // computeWatchdogMs 下限 30min（SPAWN_WATCHDOG_FLOOR_MS），maxTurns=6 → max(30min, 30min)=30min。
+  // [R1] watchdog = setTimeout(() => child.kill("SIGTERM"), maxTurnsToWatchdogMs(maxTurns))。
+  // maxTurnsToWatchdogMs 下限 30min（SPAWN_WATCHDOG_FLOOR_MS），maxTurns=6 → max(30min, 30min)=30min。
   // 子进程卡死（turn_end 永不触发）时 limiter 失效，watchdog 兜底 kill 防资源泄漏。
   describe("watchdog 到期 → signal abort → child.kill", () => {
     beforeEach(() => {
@@ -282,9 +283,9 @@ describe("timeoutMs / signal abort → child.kill 端到端路径", () => {
       vi.useRealTimers();
     });
 
-    it("watchdog 到期（超过 computeWatchdogMs 阈值）→ child.kill(SIGTERM) 被调用", async () => {
+    it("watchdog 到期（超过 maxTurnsToWatchdogMs 阈值）→ child.kill(SIGTERM) 被调用", async () => {
       const record = makeRecord();
-      // maxTurns=6 → computeWatchdogMs = max(30min, 6*5min) = 30min
+      // maxTurns=6 → maxTurnsToWatchdogMs = max(30min, 6*5min) = 30min
       // 不 await：runSpawn 内部 await 子进程 close，watchdog kill 后还需 emit close 才 resolve
       const promise = runSpawn(record, "Task: hang", makeOpts({ maxTurns: 6 }), makeCtx());
 
@@ -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);
@@ -396,7 +397,7 @@ describe("timeoutMs / signal abort → child.kill 端到端路径", () => {
       expect(resolveSpawnWatchdogMs(0)).toBeUndefined();
       expect(resolveSpawnWatchdogMs(-5)).toBeUndefined();
       // maxTurns 有效（>0）→ turns 估算优先于 env 兑底
-      expect(resolveSpawnWatchdogMs(6)).toBe(computeWatchdogMs(6));
+      expect(resolveSpawnWatchdogMs(6)).toBe(maxTurnsToWatchdogMs(6));
       vi.stubEnv(SPAWN_WATCHDOG_ENV, "abc");
       expect(resolveSpawnWatchdogMs(undefined)).toBeUndefined();
       vi.stubEnv(SPAWN_WATCHDOG_ENV, "-1");

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（不累计）", () => {

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

@@ -1,7 +1,7 @@
 // src/__tests__/turn-limiter.test.ts
 import { describe, expect, it, vi } from "vitest";
 
-import { createTurnLimiter } from "../turn-limiter.ts";
+import { createTurnLimiter } from "../engine/engines/pi/turn-limiter.ts";
 
 describe("createTurnLimiter", () => {
   it("does nothing before maxTurns", () => {

package/src/execution/__tests__/ui-request-handler-factory.test.ts

@@ -9,7 +9,10 @@
 // realHandler 路由：channel 命中 → channelHandler（经 coerceUiResponse 形变）；未命中 → defaultDialogForward（dialog 转发结果，fire-and-forget 转发 ctx.ui.* 后回 ack，未知 method warn + ack）。
 // 测接口契约，不测实现细节。
 
-import type { ExtensionContext, ExtensionMode } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+
+// ExtensionMode 未从 pi 包根 re-export（实装 0.84.4 核对），从权威 ExtensionContext 派生
+type ExtensionMode = ExtensionContext["mode"];
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const { loggerMock } = vi.hoisted(() => ({
@@ -23,7 +26,7 @@ vi.mock("../../core/logger.ts", () => ({
   getLogger: () => loggerMock,
 }));
 
-import { DialogGlobalQueue, type UiRequest } from "../dialog-queue.ts";
+import { DEFAULT_DIALOG_TIMEOUT_MS, DialogGlobalQueue, type UiRequest } from "../dialog-queue.ts";
 import { type ChannelHandler,createUiChannelRegistry } from "../ui-channels.ts";
 import { createUiRequestHandlerForMode } from "../ui-request-handler-factory.ts";
 
@@ -39,14 +42,17 @@ function makeCtx(mode: ExtensionMode): ExtensionContext {
     },
     modelRegistry: undefined,
     model: undefined,
-  } as ExtensionContext;
+  } as unknown as ExtensionContext;
 }
 
 /** 带 mock ctx.ui 的 ExtensionContext（GUI fire-and-forget 转发测试用）。
  *  dialog method（select/confirm/input/editor）返回 undefined/true/"" 兜底，
  *  fire-and-forget method（notify/setStatus/setWidget/setTitle/setEditorText）是 void spy。 */
-function makeCtxWithUi(mode: ExtensionMode = "rpc"): ExtensionContext & { ui: Record<string, ReturnType<typeof vi.fn>> } {
-  const ui: Record<string, ReturnType<typeof vi.fn>> = {
+// ui 成员 = 真实签名 & vi.fn 能力（映射交叉）：调用点走真实签名，mock 打点方法可达
+type MockedUi = { [K in keyof ExtensionUIContext]: ExtensionUIContext[K] & ReturnType<typeof vi.fn> };
+
+function makeCtxWithUi(mode: ExtensionMode = "rpc"): Omit<ExtensionContext, "ui"> & { ui: MockedUi } {
+  const ui = {
     select: vi.fn(async () => undefined),
     confirm: vi.fn(async () => true),
     input: vi.fn(async () => ""),
@@ -67,8 +73,8 @@ function makeCtxWithUi(mode: ExtensionMode = "rpc"): ExtensionContext & { ui: Re
     },
     modelRegistry: undefined,
     model: undefined,
-    ui,
-  } as unknown as ExtensionContext & { ui: Record<string, ReturnType<typeof vi.fn>> };
+    ui: ui as unknown as MockedUi,
+  } as unknown as Omit<ExtensionContext, "ui"> & { ui: MockedUi };
 }
 
 function dialogReq(id: string, channel?: string): UiRequest {
@@ -367,3 +373,97 @@ describe("createUiRequestHandlerForMode — TUI 零回归", () => {
     }
   });
 });
+
+// ── LC-3/T2⑦：dialog timeout 协同（SDK 层超时先到 / 队列级上界兜底，settle 恰一次）──
+
+describe("createUiRequestHandlerForMode — dialog timeout 协同（LC-3/T2⑦）", () => {
+  it("请求方传 timeout → select/confirm/input 透传 SDK 第三参 {timeout}；未传不加第三参（参数个数不变）", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = createUiRequestHandlerForMode(ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+
+    await handler({ method: "select", id: "t1", title: "Choose", options: ["a"], timeout: 1234 });
+    expect(ctx.ui.select).toHaveBeenCalledWith("Choose", ["a"], { timeout: 1234 });
+
+    await handler({ method: "confirm", id: "t2", title: "Sure?", message: "Go?", timeout: 456 });
+    expect(ctx.ui.confirm).toHaveBeenCalledWith("Sure?", "Go?", { timeout: 456 });
+
+    await handler({ method: "input", id: "t3", title: "In", placeholder: "p", timeout: 78 });
+    expect(ctx.ui.input).toHaveBeenCalledWith("In", "p", { timeout: 78 });
+
+    // 未传 timeout：不加第三参（调用面严格 additive，与既有 (e) 零回归断言同形态）
+    await handler({ method: "input", id: "t4", title: "In2", placeholder: "p2" });
+    expect(ctx.ui.input).toHaveBeenCalledWith("In2", "p2");
+  });
+
+  it("全链路：req.timeout 经 L2 队列按传值超时 settle（host ctx.ui promise 挂死形态）", async () => {
+    const ctx = makeCtxWithUi();
+    // host UI promise 挂死：SDK 自身永不返回，唯一回收通道是队列级上界
+    ctx.ui.select.mockReturnValue(new Promise(() => {}));
+    const handler = createUiRequestHandlerForMode(ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+
+    const p = handler({ method: "select", id: "t1", title: "q", options: ["a"], timeout: 1234 });
+
+    await vi.advanceTimersByTimeAsync(1233);
+    let settled = false;
+    void p.then(() => {
+      settled = true;
+    });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(settled).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await expect(p).resolves.toEqual({ cancelled: true });
+  });
+
+  it("未传 timeout → 队列级默认上界（30min）兜底 settle，SDK opts 不出现", async () => {
+    const ctx = makeCtxWithUi();
+    ctx.ui.select.mockReturnValue(new Promise(() => {}));
+    const handler = createUiRequestHandlerForMode(ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+
+    const p = handler({ method: "select", id: "t1", title: "q", options: ["a"] });
+    expect(ctx.ui.select).toHaveBeenCalledWith("q", ["a"]);
+
+    await vi.advanceTimersByTimeAsync(DEFAULT_DIALOG_TIMEOUT_MS);
+    await expect(p).resolves.toEqual({ cancelled: true });
+  });
+
+  it("竞态恰一次：SDK 层超时先到（auto-dismiss）→ handler 先 settle，队列级 timer 兜底不二 settle", async () => {
+    const ctx = makeCtxWithUi();
+    // SDK timeout 生效形态：500ms 后 auto-dismiss（resolve undefined = 取消）
+    ctx.ui.select.mockImplementation(
+      () => new Promise<string | undefined>((resolve) => setTimeout(() => resolve(undefined), 500)),
+    );
+    const handler = createUiRequestHandlerForMode(ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+
+    const p = handler({ method: "select", id: "t1", title: "q", options: ["a"], timeout: 1000 });
+
+    // SDK 先到（500ms）：handler settle，此时队列级 timer（1000ms）尚未触发
+    await vi.advanceTimersByTimeAsync(500);
+    await expect(p).resolves.toEqual({ cancelled: true });
+
+    // 越过队列级超时点：timer 已随 handler 完成清除，无第二次 settle、无队列超时日志
+    await vi.advanceTimersByTimeAsync(2000);
+    await expect(p).resolves.toEqual({ cancelled: true });
+    expect(loggerMock.warn).not.toHaveBeenCalled();
+  });
+
+  // [A2-3] 非法 timeout 与队列层判定对齐：不透传 SDK 第三参（语义反转的 opts
+  // （<=0 可能立即 auto-dismiss）不进 SDK），由队列层默认上界兜底 settle。
+  it.each([-1, 0, Number.NaN])(
+    "timeout 非法（%p）→ SDK 不收第三参（参数个数 2），队列层按默认上界 settle（A2-3）",
+    async (badTimeout) => {
+      const ctx = makeCtxWithUi();
+      ctx.ui.select.mockReturnValue(new Promise(() => {})); // host UI 挂死，暴露队列层兜底
+      const handler = createUiRequestHandlerForMode(ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+
+      const p = handler({ method: "select", id: "t1", title: "q", options: ["a"], timeout: badTimeout });
+      // 第三参不出现：toHaveBeenCalledWith 逐参精确匹配，两参断言即锁死参数个数为 2
+      expect(ctx.ui.select).toHaveBeenCalledWith("q", ["a"]);
+      expect(ctx.ui.select).toHaveBeenCalledTimes(1);
+
+      // 队列层把非法值回落默认上界（30min）：到点 settle cancelled
+      await vi.advanceTimersByTimeAsync(DEFAULT_DIALOG_TIMEOUT_MS);
+      await expect(p).resolves.toEqual({ cancelled: true });
+    },
+  );
+});

package/src/execution/__tests__/ui-request-handler.test.ts

@@ -18,8 +18,8 @@ import { PassThrough } from "node:stream";
 
 import { describe, expect, it, vi } from "vitest";
 
-import { ASK_USER_RPC_PROMPT } from "../session-runner.ts";
-import { parseSpawnLine } from "../spawn-event-adapter.ts";
+import { ASK_USER_RPC_PROMPT } from "../engine/engines/pi/session-runner.ts";
+import { parseSpawnLine } from "../engine/engines/pi/spawn-event-adapter.ts";
 import { parseChannel } from "../ui-channels.ts";
 import { createUiRequestQueue, type UiRequest, type UiRequestHandler } from "../ui-request-queue.ts";
 
@@ -69,7 +69,8 @@ describe("parseSpawnLine — ask_user 请求解析（Pi 原生格式）", () =>
   it("request.title === ASK_USER_MARKER（NUL 前缀 marker 原样保留，由 parseChannel 提取）", () => {
     const result = parseSpawnLine(askUserLine("ui-req-001"));
     if (result?.kind !== "extension_ui_request") return;
-    expect(result.request.title).toBe(ASK_USER_MARKER);
+    if (result.request.method !== "select") return expect.fail("request.method 应为 select");
+    expect((result.request as { title?: string }).title).toBe(ASK_USER_MARKER);
   });
 
   it("id 被正确提取（用于 response 关联）", () => {