@zhushanwen/subagent-core 0.2.0 → 0.5.1

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

@@ -5,37 +5,44 @@
 // 从"自己 spawn pi"改为"委托 SubagentService.executeAndAwait"。
 // MF-3: 从 orchestration/infra 迁入 execution，同层委托 SubagentService。
 //
+// [D6 任务形状合流] AgentCallOpts 已是 EnginePort.run 的单一任务形状——本类直传 opts
+// 给 engine.run（无 ExecuteOptions/AgentTaskSpec 中间态映射）；pi 边界的一次直出在
+// PiEngine.agentCallToExecuteOptions。mergeTimeoutSignal（原 execute-options-mapper
+// 的运行期件，D-A9）随 mapper 删除迁入本文件（唯一消费点）。
+//
 // 接线层级：
 //   [跨模块 port] implements AgentRunner（orchestration/models/ports.ts）
-//   [模块内直调] mapToExecuteOptions + mergeTimeoutSignal（execute-options-mapper）
-//   [P4 路由层]  engine/routing.ts routeEngine（三层优先级 + probe + fallback 三守卫，D9）
+//   [模块内直调] mergeTimeoutSignal（本文件，D-A9）
+//   [P4 路由层]  engine/routing.ts routeEngineForHost（D3-② 路由单点：三层优先级 +
+//                pi 同步短路 + probe + fallback 三守卫，D9）
+//   [公共预检]   engine/common/capability-gate（D3-④：capabilities 驱动的调用前拒绝）
 //   [引擎层]     EnginePort.run（pi = 本地 DI 绑定实例；非 pi = registry.getEngine 动态获取）
+//   [公共 journal] engine/common/journal-wiring（D3-③：writer + retarget + 回填单实现）
 //   [模块内直调] this.subagentService.executeAndAwait（PiEngine 内部委托目标）
 //
 // 设计基线：
-//   D-A2（映射归 adapter）/ D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
+//   D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
 //   D-008（model 填底，不调 resolveModel）/ BC-9（timeoutMs 行为）/ BC-10（live-record 进度）
 
 import type { AgentRunner } from "../orchestration/models/ports.ts";
 import type { AgentCallOpts, AgentResult } from "../orchestration/models/types.ts";
 import type { AgentEvent } from "../shared/agent-event.ts";
-import { getEngineDataDir } from "./engine/common/data-dir.ts";
-import { JournalWriter } from "./engine/common/event-journal.ts";
-import { createPiEngine, PI_POOL_KEY } from "./engine/engines/pi/registration.ts";
-import { executeOptionsToTaskSpec } from "./engine/engines/pi/task-spec-mapper.ts";
-import { resolveJournalPath } from "./engine/paths.ts";
+import { assertTaskShapeSupported } from "./engine/common/capability-gate.ts";
+import { HOST_TIMEOUT_ABORT_REASON } from "./engine/common/kill-chain.ts";
+import { JOURNAL_INITIAL_POOL_KEY, wireEventJournal } from "./engine/common/journal-wiring.ts";
+import { createPiEngine } from "./engine/engines/pi/registration.ts";
 import type { EnginePort, RunContext } from "./engine/port.ts";
-import { routeEngine, resolveEngineRouting, type EngineRouteResult, type EngineRoutingInput } from "./engine/routing.ts";
-import { getEngine, hasEngine, listEngines } from "./engine/registry.ts";
-import type { AgentOutcome, EngineHandle } from "./engine/types.ts";
-import { mapToExecuteOptions, mergeTimeoutSignal } from "./execute-options-mapper.ts";
+import { validateModelForEngine } from "./engine/model-validation.ts";
+import { routeEngineForHost, type EngineRouteResult, type EngineRoutingInput } from "./engine/routing.ts";
+import { getEngine } from "./engine/registry.ts";
+import type { AgentOutcome } from "./engine/types.ts";
 import { getModelConfigService } from "./model-config-service.ts";
 import type { ModelInfo } from "./model-resolver.ts";
 import { modelRefFromVerified } from "../shared/model-ref";
-import { registerSpawnedChildForRecord } from "./session-runner.ts";
+import { registerSpawnedChildForRecord } from "./engine/engines/pi/session-runner.ts";
 import type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
-import type { ExecuteOptions } from "./types.ts";
+import { toErrorMessage } from "../core/error-message.ts";
 
 // ── 构造依赖（per-session 注入）──
 
@@ -71,10 +78,12 @@ export interface SubprocessAgentRunnerDeps {
  * 非 pi 引擎（P4 路由可达：frontmatter/调用参数/全局默认指定）经 registry.getEngine
  * 动态获取——「引擎身份」的归属边界在注册表，SAR 不感知具体引擎实现。
  *
- * [P4 配置路由] 每次运行经 engine/routing.ts 解析三层优先级（调用参数 opts.engine >
- * agent frontmatter engine > 全局默认 'pi'）+ probe + fallback 三守卫（D9）。路由失败
- * （engine_not_found / engine_probe_failed / model_not_available）不 reject，入
- * result.error——与 executeAgentCall 契约一致。
+ * [P4 配置路由] 每次运行经 engine/routing.ts 的 routeEngineForHost（D3-② 路由单点：
+ * 唯一实现承载三层优先级（调用参数 opts.engine > agent frontmatter engine > 全局默认
+ * 'pi'）+ pi 同步短路 + registry 注入 + probe/fallback 三守卫，D9；本类与
+ * SubagentService.execute 是其仅有的两调用点）。路由失败（engine_not_found /
+ * engine_probe_failed / model_not_available）与预检命中（engine_capability_unsupported，
+ * D3-④）不 reject，入 result.error——与 executeAgentCall 契约一致。
  */
 export class SubprocessAgentRunner implements AgentRunner {
   private readonly subagentService: SubagentService;
@@ -85,7 +94,8 @@ export class SubprocessAgentRunner implements AgentRunner {
   constructor(deps: SubprocessAgentRunnerDeps) {
     this.subagentService = deps.subagentService;
     this.ctxModel = deps.ctxModel;
-    this.piEngine = createPiEngine(() => this.subagentService);
+    // [D4 聚合连带] 经 asEngineService 显式视图适配（原结构化直绑依赖查询面 public）。
+    this.piEngine = createPiEngine(() => this.subagentService.asEngineService);
   }
 
   /**
@@ -99,16 +109,21 @@ export class SubprocessAgentRunner implements AgentRunner {
   }
 
   /**
-   * 执行单次 agent 调用：路由（P4）→ EnginePort.run → PiEngine 委托
+   * 执行单次 agent 调用：路由（P4）→ 预检（D3-④）→ EnginePort.run → PiEngine 委托
    * SubagentService.executeAndAwait。
    *
    * 接线链路：
-   *   routeEngine（三层 + probe + 守卫）→ mergeTimeoutSignal → mapToExecuteOptions →
-   *   AgentTaskSpec → engine.run（PiEngine：spec → ExecuteOptions 还原 + engine 留痕）→
-   *   executeAndAwait → AgentOutcome → AgentResult
+   *   routeEngineForHost（D3-② 路由单点：三层 + pi 同步短路 + probe + 守卫）→
+   *   assertTaskShapeSupported（D3-④ 预检 capabilities 化）→ mergeTimeoutSignal →
+   *   engine.run(opts 直传——D6 合流：AgentCallOpts 即 EnginePort 任务形状，零映射；
+   *   PiEngine 内一次直出 ExecuteOptions + engine 留痕) → executeAndAwait →
+   *   AgentOutcome → AgentResult
    *
    * 错误处理：不 reject。
    *   - 路由失败（未注册 id / probe 失败 + 守卫或 strict）→ AgentResult.error（错误码前缀）
+   *   - 预检命中（capabilities 不支持的任务形状参数）→ AgentResult.error
+   *     （engine_capability_unsupported——[D3-④] workflow 域 zcode+worktree 由漏拦变
+   *     拦截，本单元唯一有意行为变化；拒绝在 journal/run 之前，无进程无 journal 产物）
    *   - executeAndAwait 内部失败 → 返回 AgentResult(success:false) → 已映射 error 字段
    *   - executeAndAwait throw（嵌套超限 BC-12）→ catch → AgentResult.error
    *   - spawn 级失败已由 runSpawn 内部收口为 failed AgentResult（不逃逸）
@@ -121,69 +136,57 @@ export class SubprocessAgentRunner implements AgentRunner {
   ): Promise<AgentResult> {
     const startedAt = Date.now();
 
-    // ── P4 路由：三层优先级 + probe + fallback 三守卫（D9①/D7）──
-    // 路由在最前——引擎身份决定 journal 路径与后续一切执行面；失败（未注册 id /
-    // probe 失败 + strict/守卫）按「不 reject」契约转 result.error。
-    // pi 快路径同步短路（不经 routeEngine 的 await）：pi 恒免探、无 fallback 可言、
-    // engineFor('pi') 本地 DI 绑定恒可用——不引入微任务边界，缺省路径时序与 P1 接线
-    // 前完全一致（下游依赖「run 内首个 await 前已触达 executeAndAwait」的时序契约）。
-    let routingInput: EngineRoutingInput;
+    // ── P4 路由（D3-② 单点：routeEngineForHost）+ D3-④ 预检 ──
+    // 路由在最前——引擎身份决定 journal 路径与后续一切执行面。pi 快路径同步短路
+    //（routed 非 Promise，零微任务——缺省路径时序与 P1 接线前完全一致，下游依赖
+    // 「run 内首个 await 前已触达 executeAndAwait」的时序契约）。路由失败（未注册
+    // id / probe 失败 + strict/守卫）与预检命中（capabilities 驱动，含 worktree——
+    // workflow 域漏拦缺口修复）一并按「不 reject」契约转 result.error。
     let route: EngineRouteResult;
     try {
-      routingInput = this.buildRoutingInput(opts);
-      const routing = resolveEngineRouting(routingInput);
-      if (routing.engineId === "pi") {
-        route = {
-          engine: this.piEngine,
-          engineId: "pi",
-          requestedEngineId: "pi",
-          source: routing.source,
-        };
-      } else {
-        route = await routeEngine({
-          routing: routingInput,
-          taskModel: opts.model,
-          strict: getModelConfigService()?.getGlobalConfig().engineRouting?.strict === true,
-          probe: (engineId) => this.engineFor(engineId).probe(),
-          getEngineFn: (engineId) => this.engineFor(engineId),
-          // pi 经本地 DI 绑定恒可用（不依赖 registry 全局注册态——SAR 持有服务引用），
-          // has/list 注入同一口径，engine_not_found 文案不会把本地 pi 漏报成未注册
-          hasEngineFn: (engineId) => engineId === "pi" || hasEngine(engineId),
-          listEnginesFn: () => (hasEngine("pi") ? listEngines() : ["pi", ...listEngines()]),
-        });
+      const routed = routeEngineForHost({
+        routing: this.buildRoutingInput(opts),
+        taskModel: opts.model,
+        strict: getModelConfigService()?.getGlobalConfig().engineRouting?.strict === true,
+        probe: (engineId) => this.engineFor(engineId).probe(),
+        piEngine: this.piEngine,
+      });
+      route = routed instanceof Promise ? await routed : routed;
+      // [D3-④] SAR 路径预检调用点（run 前同模块调用；唯一实现 = common/capability-gate）。
+      // pi 全参数放行（V4⑤ 反向守护）；zcode 拦 fork/conversation/maxTurns/worktree。
+      // [D6 合流] opts（AgentCallOpts）直传预检——TaskShapeForGate 是结构子集，
+      // conversation/fork/worktree/maxTurns 均在合流形状字段表内。
+      assertTaskShapeSupported(route.engineId, route.engine.capabilities(), opts);
+      // [u-h2 D2-2 调用点②] workflow 域非 pi 引擎的派发同步期 model 校验——与 chat
+      // 路径（subagent-service.executeViaEngine）共享同一入口 validateModelForEngine
+      // 与同一错误文案（V2-4④：agent({engine:'zcode', model:<pi id>}) 同步期报
+      // 「引擎与模型不配套」，不再落 engine.run 的 prepare 期晚炸）。校验对象是显式
+      // opts.model（frontmatter model 的解析归 pi 链，workflow 域非 pi 路径现状不消费
+      // ——维持现状语义不扩散）。「不 reject」契约：throw 由本 try 的 catch 收口
+      // errorResult，不进入 journal 创建与 engine.run（零 record/spawn 副作用）。
+      if (route.engineId !== "pi") {
+        validateModelForEngine(route.engine, opts.model);
       }
     } catch (err) {
-      // buildRoutingInput 的 agent 解析期校验（未注册 frontmatter engine）与路由失败
-      // （probe + strict/守卫）一并在此收口——「不 reject」契约
+      // buildRoutingInput 的 agent 解析期校验（未注册 frontmatter engine）、路由失败
+      //（probe + strict/守卫）与预检拒绝（engine_capability_unsupported）一并在此
+      // 收口——「不 reject」契约
       return errorResult(err, startedAt);
     }
 
     // ── P2 event journal 接线（设计 D6 第②级；对齐点③：路径权威 = 引擎池 key）──
-    // host 在 onEvent 回调内统一落盘（全引擎免费获得②级数据源）。初始 poolKey 用 pi
-    // 缺省占位（pi 恒 'shared'）；非池化稳定引擎（zcode）在 prepare 期经
-    // RunContext.onPoolResolved 声明实际池 key → writer.retarget——保证 journal 落盘
-    // 路径与 handle.poolKey 同源（handle.journalPath 由本方法 run 返回后回填）。
+    // [D3-③] writer + retarget + 回填收敛 common/journal-wiring（与 chat 域同一实现）：
+    // 初始 poolKey 占位 'shared'（pi 恒终值）；非池化稳定引擎（zcode）在 prepare 期经
+    // RunContext.onPoolResolved 声明实际池 key → retarget——保证 journal 落盘路径与
+    // handle.poolKey 同源（handle.journalPath 由本方法 run 返回后回填）。
     //
     // taskId 为宿主侧任务标识（journal 文件名与池引用计数 key）——executeAndAwait
     // 不外露内部 record id（取真实 id 需 hook record store 且改 createRecordForMode
     // 签名，影响面大；P4 决策：保留占位，`sa-` 前缀与 record id 同构。影响面：record
-    // GC 时无法按 taskId 联动删 journal（journal 依赖 30 天 TTL 自然回收），read ②级
-    // 经 handle.journalPath 自描述定位不受影响）。
+    // GC 时无法按 taskId 联动删 journal（journal 依赖 TTL 兜底回收，见 D8 分域裁决），
+    // read ②级经 handle.journalPath 自描述定位不受影响）。
     const taskId = `sa-${crypto.randomUUID()}`;
-    const journal = new JournalWriter({
-      path: resolveJournalPath(getEngineDataDir(), route.engineId, PI_POOL_KEY, taskId),
-      taskId,
-      engineId: route.engineId,
-    });
-    const retargetJournal = (poolKey: string): void => {
-      journal.retarget(resolveJournalPath(getEngineDataDir(), route.engineId, poolKey, taskId));
-    };
-    // 包装：先写 journal 再转发原 onEvent（原 onEvent 未传时也恒传包装版——
-    // 下游 onEvent 通道是事件生成后的纯转发，无行为分支，仅多一次入队）
-    const journalingOnEvent = (event: AgentEvent): void => {
-      journal.append(event);
-      onEvent?.(event);
-    };
+    const journal = wireEventJournal({ engineId: route.engineId, taskId, forwardEvents: onEvent });
 
     try {
       // ── [U1 D2] RunContext.modelRef 接入：ctxModel 继承路径的孪生守卫 ──
@@ -202,40 +205,39 @@ export class SubprocessAgentRunner implements AgentRunner {
       // ── D-A9: timeoutMs 合并 signal（超时 abort 带 HOST_TIMEOUT_ABORT_REASON 标记）──
       const mergedSignal = mergeTimeoutSignal(signal, opts.timeoutMs);
 
-      // ── D-A2 + D-008: AgentCallOpts → ExecuteOptions 映射 ──
-      const mappedOpts: ExecuteOptions = mapToExecuteOptions(opts, this.ctxModel);
-
       // ── P1/P4 引擎接线：EnginePort.run ──
       const runCtx: RunContext = {
         taskId,
-        poolKey: PI_POOL_KEY,
+        poolKey: JOURNAL_INITIAL_POOL_KEY,
         signal: mergedSignal,
-        onEvent: journalingOnEvent,
+        onEvent: journal.onEvent,
         ctxModel: this.ctxModel,
         ...(route.engineFallback !== undefined ? { engineFallback: route.engineFallback } : {}),
-        onPoolResolved: retargetJournal,
+        onPoolResolved: journal.onPoolResolved,
         // [U0 D10] 终止链路径①：引擎 spawn 的子进程注册进 session-runner 的
         // spawnedChildren 记账（dispose killAll 收割兜底对 workflow 域引擎任务生效）；
         // taskId（'sa-' 前缀）即记账 key，与 chat 域 kickOffEngineRun 的 record.id 同构
         onChildSpawned: (child) => registerSpawnedChildForRecord(taskId, child),
         ...(stream !== undefined ? { stream } : {}),
-        // 解耦形态（有 schemaEnv 无 schema）的兜底通道——耦合形态下引擎从 task.schema
-        // 派生等值，此值被忽略（见 RunContext.schemaEnv 注释）
-        ...(mappedOpts.schemaEnv !== undefined ? { schemaEnv: mappedOpts.schemaEnv } : {}),
+        // [D6 合流] 解耦形态（有 schemaEnv 无 schema）不再经 RunContext.schemaEnv
+        // 兜底通道——schemaEnv 已在合流形状 AgentCallOpts.schemaEnv 内，pi 直出
+        // （agentCallToExecuteOptions）以「schema 派生优先、schemaEnv 兜底」取值，
+        // 与原 ctx 兜底链路逐字节等值。
       };
       const { handle, outcome } = await route.engine.run(
-        // 泛化为中立声明（PiEngine 内部再还原回 ExecuteOptions——往返保真，
-        // 由 engines/pi/__tests__/task-spec-mapper.test.ts 逐字段锁定）
-        executeOptionsToTaskSpec(mappedOpts),
+        // [D6 合流] opts 直传——AgentCallOpts 即 EnginePort 任务形状（缺省路径零映射；
+        // pi 边界一次直出由 PiEngine.agentCallToExecuteOptions 承担，逐字段等值由
+        // engines/pi/__tests__/spawn-opts-direct.test.ts 对照表锁定）
+        opts,
         runCtx,
       );
       // handle.journalPath 回填（§3.3.6：read ②级的自描述定位符——运行期落盘路径
       // 权威在 writer，handle 记录最终路径供跨重启 read 消费）
-      backfillJournalPath(handle, journal.path);
+      journal.backfillHandle(handle);
       return outcomeToRunnerResult(outcome);
     } catch (err) {
       // executeAndAwait throw（嵌套超限 ForkDepthExceededError，BC-12）或未预期异常 → 不 reject，入 error。
-      const message = err instanceof Error ? err.message : String(err);
+      const message = toErrorMessage(err);
       return {
         content: "",
         durationMs: Date.now() - startedAt,
@@ -252,9 +254,11 @@ export class SubprocessAgentRunner implements AgentRunner {
   // ── 内部 ──
 
   /**
-   * 引擎获取：pi 走 per-session DI 绑定（mock 语义 + 生产同单例，P1 行为零变化）；
-   * 非 pi 经 registry.getEngine 动态获取（P4：引擎身份归属注册表，未注册 id 抛
-   * EngineNotFoundError——路由期已前置校验，这里是防御性兜底）。
+   * 引擎获取（routeEngineForHost 的 probe 注入体）：pi 走 per-session DI 绑定（mock
+   * 语义 + 生产同单例，P1 行为零变化）；非 pi 经 registry.getEngine 动态获取（P4：
+   * 引擎身份归属注册表，未注册 id 抛 EngineNotFoundError——路由期已前置校验，这里
+   * 是防御性兜底）。[D3-②] get/has/list 的路由期注入已由 routeEngineForHost 内部
+   * 承载（本地 pi 恒可用口径），本方法只剩 probe 一个消费点（pi 请求同步短路恒免探）。
    */
   private engineFor(engineId: string): EnginePort {
     if (engineId === "pi") return this.piEngine;
@@ -280,21 +284,16 @@ export class SubprocessAgentRunner implements AgentRunner {
   }
 }
 
-/** 路由期错误 → AgentResult.error（错误码前缀格式保留——engine_not_found 等）。 */
+/** 路由期/预检错误 → AgentResult.error（错误码前缀格式保留——engine_not_found 等）。 */
 function errorResult(err: unknown, startedAt: number): AgentResult {
   return {
     content: "",
     durationMs: Date.now() - startedAt,
-    error: err instanceof Error ? err.message : String(err),
+    error: toErrorMessage(err),
     toolCalls: [],
   };
 }
 
-/** handle.journalPath 回填（一次写者：SAR 是 handle 的首个消费者）。 */
-function backfillJournalPath(handle: EngineHandle, journalPath: string): void {
-  handle.data.journalPath = journalPath;
-}
-
 /**
  * AgentOutcome → workflow AgentResult：剥离引擎层新增字段（engineId/engineFallback/
  * exitCode——engineFallback 经 record（pi 路径）/outcome（zcode 路径）留痕，GUI 投影
@@ -305,6 +304,9 @@ function backfillJournalPath(handle: EngineHandle, journalPath: string): void {
 function outcomeToRunnerResult(outcome: AgentOutcome): AgentResult {
   return {
     content: outcome.content,
+    // [D5-③] 失败分诊标签透传（pi 引擎产出；zcode 不产 failureKind，缺省 =
+    // unknown = 可重试）。成功路径 undefined 不落键。
+    ...(outcome.failureKind !== undefined ? { failureKind: outcome.failureKind } : {}),
     parsedOutput: outcome.parsedOutput,
     usage: outcome.usage,
     durationMs: outcome.durationMs,
@@ -315,3 +317,48 @@ function outcomeToRunnerResult(outcome: AgentOutcome): AgentResult {
     toolCalls: outcome.toolCalls,
   };
 }
+
+/**
+ * D-A9: per-call timeoutMs 合并进 AbortSignal（[D6 合流迁入]——原定义在已删除的
+ * execution/execute-options-mapper.ts，本类是唯一消费点，运行期件随消费方落位）。
+ *
+ * 墙钟 timeoutMs（per-call）+ 外部 signal（run 级 abort）都生效。
+ * 缺此合并则 agent({timeoutMs:5000}) 静默无效（BC-9）。
+ *
+ * @param signal    外部 signal（workflow run 级 controller.signal）
+ * @param timeoutMs per-call 墙钟超时；undefined/<=0 → 不设超时，原样返回 signal
+ * @returns 合并后的 signal（timeoutMs 或外部 signal 任一 abort 都触发）
+ */
+export function mergeTimeoutSignal(
+  signal: AbortSignal,
+  timeoutMs?: number,
+): AbortSignal {
+  if (!timeoutMs || timeoutMs <= 0) {
+    return signal;
+  }
+
+  const controller = new AbortController();
+  // 超时 abort 带 reason 标记（对齐点④）：引擎合成终态时判别「宿主超时」
+  // （engine_timeout 公共合成）vs「外部 cancel」（中止标记）——pi 链路不读 reason，
+  // 行为不变。外部 signal abort 不带标记（用户/编排层 cancel 语义）。
+  const timer = setTimeout(() => controller.abort(HOST_TIMEOUT_ABORT_REASON), timeoutMs);
+  timer.unref();
+
+  const onExternalAbort = (): void => controller.abort();
+  if (signal.aborted) {
+    controller.abort();
+  } else {
+    signal.addEventListener("abort", onExternalAbort, { once: true });
+  }
+
+  controller.signal.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(timer);
+      if (!signal.aborted) signal.removeEventListener("abort", onExternalAbort);
+    },
+    { once: true },
+  );
+
+  return controller.signal;
+}

package/src/execution/types.ts

@@ -9,6 +9,7 @@
 
 import type { GuiRenderResult } from "@xyz-agent/extension-protocol";
 
+import type { AgentFailureKind } from "../orchestration/models/types.ts";
 import type { ModelInfo, ModelRegistryLike } from "./model-resolver.ts";
 
 // ============================================================
@@ -318,6 +319,12 @@ export interface AgentResult {
   durationMs: number;
   success: boolean;
   error?: string;
+  /**
+   * [D5-③] 失败分诊结构化标签（类型 SSOT 在 orchestration/models/types.ts 的
+   * AgentFailureKind——消费语义「unknown=可重试」与其文档同源）。collectResult 对
+   * 最终 error 分类后写入；缺省 = unknown（可重试）。type-only 引用零运行时依赖。
+   */
+  failureKind?: AgentFailureKind;
   sessionId: string;
   toolCalls: ToolCall[];
   usage?: AgentUsageTotal;
@@ -831,6 +838,8 @@ export interface SubagentRecord {
   status: ExecutionStatus;
   /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。SP-1 新增。 */
   closedReason?: ClosedReason;
+  /** 终态三态对外语义（U3 C-outcome）。磁盘重建源一等直读；无字段的存量兜底走 projectOutcome。 */
+  outcome?: ExecutionOutcome;
   mode: ExecutionMode;
   startedAt: number;
   /** 根 Pi session ID（session 隔离过滤用）。递归链上所有层 record 同值。 */

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

@@ -20,7 +20,13 @@
 
 import { getLogger } from "../core/logger.ts";
 
-import { DialogGlobalQueue, type UiRequest, type UiRequestHandler, type UiResponse } from "./dialog-queue.ts";
+import {
+  DialogGlobalQueue,
+  isValidDialogTimeout,
+  type UiRequest,
+  type UiRequestHandler,
+  type UiResponse,
+} from "./dialog-queue.ts";
 import { type HostMode, resolveHostMode } from "./host-mode.ts";
 import type { UiChannelRegistry } from "./ui-channels.ts";
 import { isDialogMethod } from "./ui-interaction-model.ts";
@@ -157,87 +163,132 @@ function coerceUiResponse(raw: unknown, reqId: string): UiResponse {
  *    input(title: string, placeholder?: string, opts?): Promise<string | undefined>
  *    editor(title: string, prefill?: string): Promise<string | undefined>
  *  注意：SDK 是位置参数（非对象参数）；返回 undefined 表示用户取消。
+ *  opts 为 ExtensionUIDialogOptions（signal?/timeout?，timeout 毫秒，SDK auto-dismiss
+ *  带倒计时展示）——LC-3/T2⑦ 协同：请求方显式传 timeout 时透传给 SDK，SDK 层超时
+ *  （正常路径，用户可见倒计时）先于队列级兜底 settle；队列级上界（dialog-queue，
+ *  未传挂 30min 默认）兜住 SDK timeout 未生效的形态（host 实现不完整 / channel handler
+ *  路径不经 SDK）。两层取先到，settle 恰一次由 DialogGlobalQueue 的 settled 标志保证。
+ *  editor 的 SDK 签名无 opts，不透传（其上界只由队列级兜底承担）。
  *
  *  Stage 4 风险点：TUI 下 ask_user channel 未注册时，select 会以普通列表渲染
  *  （title 可能含 marker）。channel 注册后由 createRealHandler 优先走 channel handler，
  *  不进这里。editor 不可用/抛错时降级 cancelled + warn，不卡队列。 */
+/** select/confirm/input 的 SDK 第三参（opts）：请求方传了**合法** timeout（>0 且有限，
+ *  判定源 = dialog-queue 的 isValidDialogTimeout，与队列层上界同一权威）才透传——
+ *  未传或非法（0/负数/NaN/±Infinity）时不加第三参，参数个数与旧调用完全一致（严格
+ *  additive）。非法值透传会让 SDK 收到语义反转的 opts（<=0 可能立即 auto-dismiss），
+ *  且与队列层「非法回落默认上界」的判定不一致（A2-3）；不透传时数组为空，SDK 无界
+ *  由队列层默认上界（30min）兜底。
+ *  返回元组联合以支持 spread 到固定签名（TS2556）。 */
+function sdkTimeoutArg(req: UiRequest): [] | [{ timeout: number }] {
+  return isValidDialogTimeout(req.timeout) ? [{ timeout: req.timeout }] : [];
+}
+
+/** 各 method 的默认转发器（表驱动分发；dialog 类 await SDK，fire-and-forget 类同步调用后回 ack）。
+ *  落空（未知 method）语义留在 defaultDialogForward，与原 default 分支逐字节一致。 */
+type DialogMethodForwarder = (req: UiRequest, ui: HostUIChannel) => Promise<UiResponse>;
+
+async function forwardSelect(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  const selected = await ui.select(req.title ?? "", req.options ?? [], ...sdkTimeoutArg(req));
+  return selected === undefined ? { cancelled: true } : { value: selected };
+}
+
+async function forwardConfirm(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  // SDK confirm 必传 message（req.message 缺失时降级空串，不报错阻塞）
+  const confirmed = await ui.confirm(req.title ?? "", req.message ?? "", ...sdkTimeoutArg(req));
+  return { confirmed };
+}
+
+async function forwardInput(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  const text = await ui.input(req.title ?? "", req.placeholder, ...sdkTimeoutArg(req));
+  return text === undefined ? { cancelled: true } : { value: text };
+}
+
+async function forwardEditor(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  // SDK editor 必填，但部分 host 运行时未实现——try/catch 降级 cancelled + warn（不卡队列）。
+  // 不用 typeof 守卫：editor 在类型上必填，typeof 检查会被 TS2367 拒（条件永假）。
+  try {
+    const text = await ui.editor(req.title ?? "", req.prefill);
+    return text === undefined ? { cancelled: true } : { value: text };
+  } catch (err) {
+    logger.warn(
+      "[subagents] ctx.ui.editor unavailable/threw, returning cancelled",
+      { detail: { id: req.id, error: err instanceof Error ? err.message : String(err) } },
+    );
+    return { cancelled: true };
+  }
+}
+
+// ── fire-and-forget 类（§3.2 映射表：GUI 模式下由 createUiRequestHandlerForMode 直接转发）
+// 子进程 rpc-mode 发出的 fire-and-forget method，channel miss 后落到此处。
+// 全部回 {ack:true}（fire-and-forget 语义：子进程不等响应）。
+
+async function forwardNotify(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  // notifyType 运行时收窄：UiRequest.notifyType 是宽 string，ctx.ui.notify 要字面量联合。
+  // 非法值 fallback "info"（pi 侧也会静默降级 info，此处显式 fallback 避免类型不安全）。
+  const rawType = req.notifyType;
+  const notifyType = rawType === "info" || rawType === "warning" || rawType === "error"
+    ? rawType
+    : "info";
+  ui.notify(req.message ?? "", notifyType);
+  return { ack: true };
+}
+
+async function forwardSetStatus(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  ui.setStatus(req.statusKey ?? "", req.statusText);
+  return { ack: true };
+}
+
+async function forwardSetWidget(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  // setWidget channel-miss 语义（§3.2 D1）：
+  //   req.channel === "gui_widget"（带 marker 但 channel 未注册）→ 不转发（marker 行无渲染意义）
+  //   req.channel === undefined（普通 widget）→ 转发文本行到主 agent
+  // channel 命中 registry 时由 createRealHandler 优先走 channel handler，不进这里。
+  if (req.channel === "gui_widget") {
+    return { ack: true };
+  }
+  ui.setWidget(req.widgetKey ?? "", req.widgetLines, { placement: req.widgetPlacement });
+  return { ack: true };
+}
+
+async function forwardSetTitle(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  ui.setTitle(req.title ?? "");
+  return { ack: true };
+}
+
+async function forwardSetEditorText(req: UiRequest, ui: HostUIChannel): Promise<UiResponse> {
+  ui.setEditorText(req.text ?? "");
+  return { ack: true };
+}
+
+/** method → 转发器路由表（key 与原 switch case 标签一一对应；值可选表达落空语义）。 */
+const DIALOG_METHOD_FORWARDERS: Readonly<
+  Record<string, DialogMethodForwarder | undefined>
+> = {
+  select: forwardSelect,
+  confirm: forwardConfirm,
+  input: forwardInput,
+  editor: forwardEditor,
+  notify: forwardNotify,
+  setStatus: forwardSetStatus,
+  setWidget: forwardSetWidget,
+  setTitle: forwardSetTitle,
+  set_editor_text: forwardSetEditorText,
+};
+
 async function defaultDialogForward(
   req: UiRequest,
   ctx: HostUIContext,
 ): Promise<UiResponse> {
-  const ui = ctx.ui;
-  switch (req.method) {
-    case "select": {
-      const selected = await ui.select(req.title ?? "", req.options ?? []);
-      return selected === undefined ? { cancelled: true } : { value: selected };
-    }
-    case "confirm": {
-      // SDK confirm 必传 message（req.message 缺失时降级空串，不报错阻塞）
-      const confirmed = await ui.confirm(req.title ?? "", req.message ?? "");
-      return { confirmed };
-    }
-    case "input": {
-      const text = await ui.input(req.title ?? "", req.placeholder);
-      return text === undefined ? { cancelled: true } : { value: text };
-    }
-    case "editor": {
-      // SDK editor 必填，但部分 host 运行时未实现——try/catch 降级 cancelled + warn（不卡队列）。
-      // 不用 typeof 守卫：editor 在类型上必填，typeof 检查会被 TS2367 拒（条件永假）。
-      try {
-        const text = await ui.editor(req.title ?? "", req.prefill);
-        return text === undefined ? { cancelled: true } : { value: text };
-      } catch (err) {
-        logger.warn(
-          "[subagents] ctx.ui.editor unavailable/threw, returning cancelled",
-          { detail: { id: req.id, error: err instanceof Error ? err.message : String(err) } },
-        );
-        return { cancelled: true };
-      }
-    }
-    // ── fire-and-forget 类（§3.2 映射表：GUI 模式下由 createUiRequestHandlerForMode 直接转发）
-    // 子进程 rpc-mode 发出的 fire-and-forget method，channel miss 后落到此处。
-    // 全部回 {ack:true}（fire-and-forget 语义：子进程不等响应）。
-    case "notify": {
-      // notifyType 运行时收窄：UiRequest.notifyType 是宽 string，ctx.ui.notify 要字面量联合。
-      // 非法值 fallback "info"（pi 侧也会静默降级 info，此处显式 fallback 避免类型不安全）。
-      const rawType = req.notifyType;
-      const notifyType = rawType === "info" || rawType === "warning" || rawType === "error"
-        ? rawType
-        : "info";
-      ui.notify(req.message ?? "", notifyType);
-      return { ack: true };
-    }
-    case "setStatus": {
-      ui.setStatus(req.statusKey ?? "", req.statusText);
-      return { ack: true };
-    }
-    case "setWidget": {
-      // setWidget channel-miss 语义（§3.2 D1）：
-      //   req.channel === "gui_widget"（带 marker 但 channel 未注册）→ 不转发（marker 行无渲染意义）
-      //   req.channel === undefined（普通 widget）→ 转发文本行到主 agent
-      // channel 命中 registry 时由 createRealHandler 优先走 channel handler，不进这里。
-      if (req.channel === "gui_widget") {
-        return { ack: true };
-      }
-      ui.setWidget(req.widgetKey ?? "", req.widgetLines, { placement: req.widgetPlacement });
-      return { ack: true };
-    }
-    case "setTitle": {
-      ui.setTitle(req.title ?? "");
-      return { ack: true };
-    }
-    case "set_editor_text": {
-      ui.setEditorText(req.text ?? "");
-      return { ack: true };
-    }
-    default: {
-      // 未知 method（非 dialog 非 fire-and-forget）——保留 warn（协议演进信号，P3 限流兜底），
-      // 回 ack（落到 default 的一定不是 dialog，fire-and-forget 正确应答是 ack，与 TUI 分支先例一致）。
-      logger.warn(
-        "[subagents] defaultDialogForward: unknown method",
-        { detail: { method: req.method, id: req.id } },
-      );
-      return { ack: true };
-    }
+  const forwarder = DIALOG_METHOD_FORWARDERS[req.method];
+  if (!forwarder) {
+    // 未知 method（非 dialog 非 fire-and-forget）——保留 warn（协议演进信号，P3 限流兜底），
+    // 回 ack（落到 default 的一定不是 dialog，fire-and-forget 正确应答是 ack，与 TUI 分支先例一致）。
+    logger.warn(
+      "[subagents] defaultDialogForward: unknown method",
+      { detail: { method: req.method, id: req.id } },
+    );
+    return { ack: true };
   }
+  return forwarder(req, ctx.ui);
 }