@zhushanwen/subagent-core 0.2.0 → 0.4.0

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

@@ -0,0 +1,316 @@
+// src/execution/__tests__/subagent-service-recovery-bounds.test.ts
+//
+// [u-svc / T2] 服务侧回收上界与 kill 收敛：
+//   - T2④/LC-2：closeChatIdle / closeAfterRoundSettled / cancelBackground 三条裸 SIGTERM
+//     收敛到 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（进程不再裸奔）。
+//
+// mock 形态沿用 subagent-service-message-close.test.ts（真实 SubagentService + ServiceInternals
+// cast 暴露 store + mock session-runner/stdin-writer/logger）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+// killRecordChildWithEscalation 换 spy（收敛调用点断言）；spawnedChildren 用真 Map
+//（deliverMessage 热路径判定 / EPIPE 兜底按值删除的消费者）；getChildByRecord 从同
+// 一 Map 查（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)),
+  };
+});
+vi.mock("../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("../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 { createRecord } from "../execution-record.ts";
+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 { armIdleTimer, hasIdleTimer, _resetLifecycleState } from "../lifecycle-manager.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>;
+} {
+  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>;
+  };
+}
+
+function makeRecord(overrides: Partial<ExecutionRecord> & { id?: string } = {}): ExecutionRecord {
+  const { id = "sa-test", ...rest } = overrides;
+  const r = createRecord(id, {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "background",
+    task: "test",
+    slug: "test",
+    startedAt: 1000,
+    rootSessionId: "root-session",
+    chatMode: true,
+    controller: new AbortController(),
+  });
+  Object.assign(r, rest);
+  return r;
+}
+
+interface ServiceInternals {
+  store: RecordStore;
+}
+
+type MockPi = ReturnType<typeof makePi>;
+
+function setup(): { agentDir: string; service: SubagentService; store: RecordStore; pi: MockPi } {
+  const agentDir = makeTmpAgentDir();
+  const modelService = new ModelConfigService({ 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 };
+}
+
+/** bracket 调 private 方法（ServiceInternals cast 先例的扩展形态）。 */
+function privateFn<K extends string>(service: SubagentService, key: K): (...args: never[]) => unknown {
+  return (service as unknown as Record<string, (...args: never[]) => unknown>)[key];
+}
+
+describe("T2④ service-side kill convergence", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+  let pi: MockPi;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    killChildSpy.mockClear();
+    sendPromptCommandMock.mockReset();
+    ({ agentDir, service, store, pi } = setup());
+  });
+
+  afterEach(() => {
+    _resetLifecycleState();
+    _resetSettledWatchdogsForTest();
+    spawnedMap.clear();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("cancelBackground (via cancel) routes through killRecordChildWithEscalation", 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");
+  });
+
+  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);
+  });
+
+  it("closeAfterRoundSettled routes through killRecordChildWithEscalation", async () => {
+    const record = makeRecord({ id: "sa-close-round" });
+    await (
+      privateFn(service, "closeAfterRoundSettled") as (this: SubagentService, r: ExecutionRecord) => Promise<void>
+    ).call(service, record);
+    expect(killChildSpy).toHaveBeenCalledWith(record.id, "closeAfterRoundSettled");
+  });
+
+  it("disposeAllRecords applies all recovery surfaces: abort + escalation kill + disarm idle/settled timers", () => {
+    const running = makeRecord({ id: "sa-dispose-run" });
+    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, () => {});
+
+    const count = service.disposeAllRecords("parent-new");
+
+    expect(count).toBe(2);
+    // 回收面 i：controller.abort
+    expect(running.controller?.signal.aborted).toBe(true);
+    expect(idle.controller?.signal.aborted).toBe(true);
+    // 回收面 ii：kill 收敛到 escalation 入口
+    expect(killChildSpy).toHaveBeenCalledWith(running.id, "disposeAllRecords (parent-new)");
+    expect(killChildSpy).toHaveBeenCalledWith(idle.id, "disposeAllRecords (parent-new)");
+    // 回收面 iii：idle timer + settled watchdog 双 disarm
+    expect(hasIdleTimer(idle.id)).toBe(false);
+    expect(hasSettledWatchdog(idle.id)).toBe(false);
+    // record 终态化
+    expect(running.status).toBe("closed");
+    expect(idle.status).toBe("closed");
+    expect(running.closedReason).toBe("parent-new");
+  });
+});
+
+describe("T2③ hot-path settled watchdog", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+  let pi: MockPi;
+
+  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());
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    _resetLifecycleState();
+    _resetSettledWatchdogsForTest();
+    spawnedMap.clear();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  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);
+    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 () => {
+    // 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);
+    expect(hasSettledWatchdog(record.id)).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(SETTLED_WATCHDOG_TIMEOUT_MS + 1);
+
+    // kill 收敛入口被触发（onTimeout 第一步）
+    expect(killChildSpy).toHaveBeenCalledWith(record.id, "settled watchdog (hot path)");
+    // watchdog 到期自清（armedTimers 先删条目再执行回调）
+    expect(hasSettledWatchdog(record.id)).toBe(false);
+    // 该轮失败终态化（chatMode → MF-6 回退 resumable）+ 失败通知
+    expect(record.resumable).toBe(true);
+    expect(record.status).toBe("running");
+    expect(record.result).toContain("settled watchdog");
+    expect(record.result).toContain("Recovery");
+    expect(record.result).toContain("action:'list'");
+    // 失败通知送达（内核直发路径）
+    expect(pi.sendMessage).toHaveBeenCalled();
+    const notifyContent = (pi.sendMessage.mock.calls[0]?.[0] as { content?: string } | undefined)?.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 });
+  });
+
+  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(service.deliverMessage(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.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/);
+    expect(hasIdleTimer(record.id)).toBe(true);
+  });
+});

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 两条链路。
 //
@@ -102,7 +102,7 @@ import * as fs from "node:fs";
 
 import { createRecord } from "../execution-record.ts";
 import {
-  computeWatchdogMs,
+  maxTurnsToWatchdogMs,
   type RunOptions,
   resolveSpawnWatchdogMs,
   runSpawn,
@@ -270,8 +270,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 +282,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());
 
@@ -396,7 +396,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__/ui-request-handler-factory.test.ts

@@ -23,7 +23,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";
 
@@ -367,3 +367,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-queue.test.ts

@@ -131,3 +131,28 @@ describe("UI 请求队列", () => {
     expect(callOrder).toEqual(["Q1", "Q2"]);
   });
 });
+
+// ── LC-3/T2⑦ 验收⑤：timeout 字段透传链路（L1 队列 → handler 段）──
+// 下游段（handler → dialogQueue 消费）由 dialog-queue.test.ts / ui-request-handler-factory.test.ts 锁死。
+
+describe("UI 请求队列 — timeout 字段透传（LC-3/T2⑦）", () => {
+  it("ExtensionUiRequest.timeout 经 handleUiRequest 到达 uiRequestHandler 收到的 UiRequest", async () => {
+    const received: UiRequest[] = [];
+    const handler: UiRequestHandler = (req: UiRequest) => {
+      received.push(req);
+      return Promise.resolve<UiResponse>({ value: "ok" });
+    };
+
+    const child = makeFakeChild();
+    const ctx = { uiRequestHandler: handler } as Parameters<
+      typeof createUiRequestQueue
+    >[1];
+    const enqueue = createUiRequestQueue(child, ctx);
+
+    enqueue("r1", { ...makeSelectReq("Q1"), timeout: 5000 });
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(received).toHaveLength(1);
+    expect(received[0].timeout).toBe(5000);
+  });
+});