@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

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

@@ -8,7 +8,9 @@
 // 接线层级：
 //   [跨模块 port] implements AgentRunner（orchestration/models/ports.ts）
 //   [模块内直调] mapToExecuteOptions + mergeTimeoutSignal（execute-options-mapper）
-//   [模块内直调] this.subagentService.executeAndAwait
+//   [P4 路由层]  engine/routing.ts routeEngine（三层优先级 + probe + fallback 三守卫，D9）
+//   [引擎层]     EnginePort.run（pi = 本地 DI 绑定实例；非 pi = registry.getEngine 动态获取）
+//   [模块内直调] this.subagentService.executeAndAwait（PiEngine 内部委托目标）
 //
 // 设计基线：
 //   D-A2（映射归 adapter）/ D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
@@ -17,8 +19,20 @@
 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 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 { 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 type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
 import type { ExecuteOptions } from "./types.ts";
@@ -51,14 +65,27 @@ export interface SubprocessAgentRunnerDeps {
  *   - result 形状不变（workflow AgentResult: content/parsedOutput/usage/error/toolCalls）
  *   - 不 reject——失败信息入 result.error（与 executeAgentCall 契约一致）
  *   - timeoutMs 合并 signal（D-A9）；onEvent 桥接 AgentEvent→workflow liveRecord（D-A8）
+ *
+ * [P1 引擎接线] 执行经 EnginePort。pi 引擎绑定本 SAR 的服务引用（per-session DI——
+ * 单测注入 mock 时全局单例不可见；生产环境两者是同一进程单例对象），行为零变化；
+ * 非 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 契约一致。
  */
 export class SubprocessAgentRunner implements AgentRunner {
   private readonly subagentService: SubagentService;
   private ctxModel: ModelInfo | undefined;
+  /** pi 引擎（per-session DI 绑定，缺省执行路径——见类注释）。 */
+  private readonly piEngine: EnginePort;
 
   constructor(deps: SubprocessAgentRunnerDeps) {
     this.subagentService = deps.subagentService;
     this.ctxModel = deps.ctxModel;
+    this.piEngine = createPiEngine(() => this.subagentService);
   }
 
   /**
@@ -72,13 +99,16 @@ export class SubprocessAgentRunner implements AgentRunner {
   }
 
   /**
-   * 执行单次 agent 调用：委托 SubagentService.executeAndAwait。
+   * 执行单次 agent 调用：路由（P4）→ EnginePort.run → PiEngine 委托
+   * SubagentService.executeAndAwait。
    *
    * 接线链路：
-   *   mergeTimeoutSignal → mapToExecuteOptions →
-   *   this.subagentService.executeAndAwait → 返回 AgentResult
+   *   routeEngine（三层 + probe + 守卫）→ mergeTimeoutSignal → mapToExecuteOptions →
+   *   AgentTaskSpec → engine.run（PiEngine：spec → ExecuteOptions 还原 + engine 留痕）→
+   *   executeAndAwait → AgentOutcome → AgentResult
    *
    * 错误处理：不 reject。
+   *   - 路由失败（未注册 id / probe 失败 + 守卫或 strict）→ AgentResult.error（错误码前缀）
    *   - executeAndAwait 内部失败 → 返回 AgentResult(success:false) → 已映射 error 字段
    *   - executeAndAwait throw（嵌套超限 BC-12）→ catch → AgentResult.error
    *   - spawn 级失败已由 runSpawn 内部收口为 failed AgentResult（不逃逸）
@@ -91,22 +121,118 @@ 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;
+    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()]),
+        });
+      }
+    } catch (err) {
+      // buildRoutingInput 的 agent 解析期校验（未注册 frontmatter engine）与路由失败
+      // （probe + strict/守卫）一并在此收口——「不 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 返回后回填）。
+    //
+    // 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 自描述定位不受影响）。
+    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);
+    };
+
     try {
-      // ── D-A9: timeoutMs 合并 signal ──
+      // ── [U1 D2] RunContext.modelRef 接入：ctxModel 继承路径的孪生守卫 ──
+      // ctxModel 是运行时已验证的 ModelInfo（豁免 registry 存在性复查），但继承产出的
+      // canonical 串与显式入参走同一个 pi pattern 引擎，孪生守卫同等适用（modelRefFromVerified）。
+      // 守卫在 engine.run 之前同步拒绝：含孪生 registry 下不产生任何 record/spawn，
+      // 失败走下方 catch → errorResult（错误文案含恢复指引）。
+      // RunContext 类型本身定义在 engine/port.ts（跨模块 port，不在本单元领地），
+      // 故接入点为构造 runCtx 前的守卫调用；pi 链路下游 resolveModel 的 ctxModel 分支
+      // 有同一守卫（model-resolver.ts），两处共用同一入口函数。
+      if (this.ctxModel) {
+        const modelService = getModelConfigService();
+        if (modelService) modelRefFromVerified(this.ctxModel, modelService.getModelRegistry());
+      }
+
+      // ── 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);
 
-      // ── D-A8: onEvent 桥接 ──
-      // executeAndAwait 发强类型 AgentEvent（session-runner handleSdkEvent 出口）。
-      // workflow 的 onEvent 闭包（error-recovery.ts dispatchAgentCall）类型已升级为
-      // (event: AgentEvent) => updateFromEvent(liveRecord, event)（D-005）。
-      // SAR 直接透传 onEvent——类型对齐后零桥接开销。
-      const bridgedOnEvent = onEvent;
-
-      // ── 核心委托 ──
-      return await this.subagentService.executeAndAwait(mappedOpts, mergedSignal, bridgedOnEvent, stream);
+      // ── P1/P4 引擎接线：EnginePort.run ──
+      const runCtx: RunContext = {
+        taskId,
+        poolKey: PI_POOL_KEY,
+        signal: mergedSignal,
+        onEvent: journalingOnEvent,
+        ctxModel: this.ctxModel,
+        ...(route.engineFallback !== undefined ? { engineFallback: route.engineFallback } : {}),
+        onPoolResolved: retargetJournal,
+        // [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 } : {}),
+      };
+      const { handle, outcome } = await route.engine.run(
+        // 泛化为中立声明（PiEngine 内部再还原回 ExecuteOptions——往返保真，
+        // 由 engines/pi/__tests__/task-spec-mapper.test.ts 逐字段锁定）
+        executeOptionsToTaskSpec(mappedOpts),
+        runCtx,
+      );
+      // handle.journalPath 回填（§3.3.6：read ②级的自描述定位符——运行期落盘路径
+      // 权威在 writer，handle 记录最终路径供跨重启 read 消费）
+      backfillJournalPath(handle, journal.path);
+      return outcomeToRunnerResult(outcome);
     } catch (err) {
       // executeAndAwait throw（嵌套超限 ForkDepthExceededError，BC-12）或未预期异常 → 不 reject，入 error。
       const message = err instanceof Error ? err.message : String(err);
@@ -116,6 +242,76 @@ export class SubprocessAgentRunner implements AgentRunner {
         error: message,
         toolCalls: [],
       };
+    } finally {
+      // run 终态后 flush + fsync 一次（§3.3.6 写入纪律）；写失败已由 writer 内部
+      // warn + failed 收口，close 不抛（journal 是②级尽力而为数据源）
+      await journal.close();
     }
   }
+
+  // ── 内部 ──
+
+  /**
+   * 引擎获取：pi 走 per-session DI 绑定（mock 语义 + 生产同单例，P1 行为零变化）；
+   * 非 pi 经 registry.getEngine 动态获取（P4：引擎身份归属注册表，未注册 id 抛
+   * EngineNotFoundError——路由期已前置校验，这里是防御性兜底）。
+   */
+  private engineFor(engineId: string): EnginePort {
+    if (engineId === "pi") return this.piEngine;
+    return getEngine(engineId);
+  }
+
+  /**
+   * 三层路由输入装配（D9）：调用参数（opts.engine，workflow step 级透传）> agent
+   * frontmatter（ModelConfigService.getAgentConfig——loadByPath mtime 缓存，幂等）>
+   * 全局默认（config.json defaultEngine）。单例未就绪（session_start 前/测试 mock）
+   * 时各层缺省——落内置 'pi'。
+   */
+  private buildRoutingInput(opts: AgentCallOpts): EngineRoutingInput {
+    const service = getModelConfigService();
+    const agentEngine =
+      opts.agent !== undefined && opts.agent !== "" ? service?.getAgentConfig(opts.agent)?.engine : undefined;
+    const globalDefault = service?.getGlobalConfig().defaultEngine;
+    return {
+      ...(opts.engine !== undefined && opts.engine !== "" ? { callEngine: opts.engine } : {}),
+      ...(agentEngine !== undefined && agentEngine !== "" ? { agentEngine } : {}),
+      ...(globalDefault !== undefined && globalDefault !== "" ? { globalDefaultEngine: globalDefault } : {}),
+    };
+  }
+}
+
+/** 路由期错误 → 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),
+    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 投影
+ * 通道在后续 wave 接线，workflow 引擎不消费）。其余字段由 PiEngine 从 executeAndAwait
+ * 的返回值逐字段映射而来，字段全集完整性由 pi-engine 单测锁定（缺字段会在该处转红，
+ * 不会静默丢失）。
+ */
+function outcomeToRunnerResult(outcome: AgentOutcome): AgentResult {
+  return {
+    content: outcome.content,
+    parsedOutput: outcome.parsedOutput,
+    usage: outcome.usage,
+    durationMs: outcome.durationMs,
+    error: outcome.error,
+    sessionId: outcome.sessionId,
+    sessionFile: outcome.sessionFile,
+    worktreePath: outcome.worktreePath,
+    toolCalls: outcome.toolCalls,
+  };
 }

package/src/execution/types.ts

@@ -61,6 +61,37 @@ export type ExecutionStatus = "running" | "closed";
  */
 export type ClosedReason = 'parent-shutdown' | 'parent-fork' | 'parent-new' | 'user-close' | 'cancelled' | 'gc';
 
+/** ClosedReason 全枚举值（运行时守卫用——防御性解析外部输入时校验成员资格）。 */
+export const CLOSED_REASONS: readonly ClosedReason[] = [
+  'parent-shutdown',
+  'parent-fork',
+  'parent-new',
+  'user-close',
+  'cancelled',
+  'gc',
+];
+
+/**
+ * 终态三态对外语义（U3 C-outcome 一等披露）。
+ *
+ * 由 completeRecord 唯一写入点按 deriveOutcome 一次计算（判定顺序：cancelled 优先
+ * → error 非空 → completed），消费方（project/list/notify 文案/渲染器）只读本字段，
+ * 不再各自手写成败推导 switch（三处同构 switch 已随 U3 收敛删除）。
+ *
+ * [D6 显式取舍] parent-shutdown/parent-fork/parent-new 合成关闭（subagent-service
+ * disposeAllRecords 合成 result 恒写 error:"closed due to ..."）落 "failed"——语义为
+ * 「父进程关闭时子 agent 未完成即失败」，选定行为而非疏漏，勿当 bug 改回 cancelled。
+ */
+export type ExecutionOutcome = "completed" | "failed" | "cancelled";
+
+/**
+ * 对外投影的 outcome 联合：含历史 record（outcome 字段诞生前的存量数据）兼容态。
+ * 投影层（projectOutcome 唯一出口）对无 outcome 字段的 closed record 按
+ * deriveOutcome(closedReason, error) 兜底派生；"closed-legacy" 预留给连派生输入都
+ * 不足以判读的存量形态，消费方必须处理该成员（不得因未知值崩溃）。
+ */
+export type ProjectedOutcome = ExecutionOutcome | "closed-legacy";
+
 /**
  * 对外四态（设计决策 10 细则 3）：内部 ExecutionStatus（v4 B-1 两态）收敛为 agent
  * 可理解的状态语义。真实映射只有两条：
@@ -88,6 +119,15 @@ export type ExecutionMode = "background";
  *
  * 设计：AgentEvent 携带 updateFromEvent 收口进 record 所需的**全部数据**——
  * tool_end 带 result（供 turn.toolCalls 存完整 ToolCall），无需翻译层旁路累积。
+ *
+ * ACP 词汇对照（D11 注记级校准，零行为变更；新引擎实现者按本表对齐语义，
+ * 详见 docs/architecture/subagent-engine-gui-visibility.md §3.3 D11）：
+ *   text_delta / thinking_delta ↔ ACP content blocks（text / thinking）
+ *   tool_start / tool_end      ↔ ACP tool_call / tool_call_update
+ *   turn_end / message_end     ↔ ACP prompt turn 终态（stop_reason + usage）
+ *   compaction                 ↔ ACP session/compaction
+ * 本协议以 pi 为语义锚点（D3）——命名不迁移，对照表仅保证未来 AcpEngine 适配器
+ * 与跨引擎 trace 映射的翻译成本最低。
  */
 export type AgentEvent =
   | { type: "tool_start"; toolName: string; args?: unknown }
@@ -384,6 +424,23 @@ export interface ExecutionRecord {
    * 向后兼容：旧 record 无此字段，按默认值处理。
    */
   readonly idleTimeoutMs?: number;
+  /**
+   * 实际执行引擎 id（P4 路由留痕，D9①）。创建时确定不可变；缺省（存量 record）
+   * = pi 投影（消费方零迁移）。持久化经 subagent-record entry。
+   */
+  readonly engine?: string;
+  /**
+   * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源；
+   * 缺省 = 无 fallback。持久化经 subagent-record entry。
+   */
+  readonly engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U2：非 pi run resolve 后回填、终态迁移落 entry 前——run 前
+   * 缺省不可用）。sessionRef 整体透传（失败终态 sessionId 缺失时仍回填已有部分，
+   * 读侧①级降②级的防御形态）；journalPath 为 retarget 后实际落盘路径。pi 分支不
+   * 回填（sessionFile 即定位符）。持久化经 subagent-record entry。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 
   // ── 状态（实时更新）──
   status: ExecutionStatus;
@@ -391,6 +448,12 @@ export interface ExecutionRecord {
    *  由 tryTransition(record, "closed", reason) 写入；投影层按需派生对外语义。
    *  向后兼容：旧 record 无此字段，按 gc 处理（通用完成/失败）。 */
   closedReason?: ClosedReason;
+  /**
+   * 终态三态对外语义（U3 C-outcome）。completeRecord 唯一写入点按 deriveOutcome
+   * 一次计算，消费方只读本字段不再自行推导。向后兼容：旧 record / 磁盘重建
+   * record 无此字段，投影层按 projectOutcome 兜底（closed-legacy 语义）。
+   */
+  outcome?: ExecutionOutcome;
   /** 完整执行内容，按 turn 组织。createRecord 初始化为 [空 turn]。 */
   turns: Turn[];
   /** turn 计数（= turns.filter(closed).length，冗余存储供投影直接读）。 */
@@ -494,6 +557,11 @@ export interface ExecutionRecord {
  */
 export interface SubagentToolDetails {
   status: ExecutionStatus;
+  /**
+   * 终态三态对外语义（U3 C-outcome，projectOutcome 唯一出口）。running → undefined；
+   * 历史数据无 outcome 字段时兜底派生（见 ProjectedOutcome）。
+   */
+  outcome?: ProjectedOutcome;
   mode: ExecutionMode;
   agent: string;
   model: string;
@@ -538,6 +606,10 @@ export interface ExecuteOptions {
   schema?: Record<string, unknown>;
   /** D-A6 bridge: workflow schemaEnv 经 ExecuteOptions 透传到 runSpawn childEnv。 */
   schemaEnv?: string;
+  /**
+   * Turn 上限 limiter。显式 0/负 = 显式不限：压过 SPAWN_WATCHDOG_ENV 兑底不挂
+   * watchdog（SP-6 参数 > env，U5）；undefined 未传才由 env 兑底。
+   */
   maxTurns?: number;
   graceTurns?: number;
   /** sync 模式来自 Pi tool 框架；background 模式 hub 忽略，自建 controller。 */
@@ -561,8 +633,19 @@ export interface ExecuteOptions {
   /**
    * 空闲超时毫秒数（仅 conversation 模式有意义）。覆盖默认 5min idle timeout。
    * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
+   * 显式传 0/负数 = 禁用 idle GC（不挂 timer；旧实现 0 会落成 setTimeout(0) 立即 kill）。
    */
   idleTimeoutMs?: number;
+  /**
+   * 实际执行引擎 id（P4 路由留痕）：pi 引擎由 PiEngine.run 在还原 opts 时写入；
+   * 缺省（历史调用方不设）= pi 投影。createRecordForMode 读入 record identity。
+   */
+  engine?: string;
+  /**
+   * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎时由路由层写入）。
+   * from = 请求引擎 id，reason 恒 'engine_probe_failed'（GUI 警告条数据源）。
+   */
+  engineFallback?: { from: string; reason: string };
   // 注：fork 深度不从外部传入（曾暴露 parentForkDepth，改用 ALS 后 execute 内部从调用链派生，
   // 公开字段成为死字段误导调用方，已移除）。深度限制检查见 session-runner.ts 内部 RunOptions.parentForkDepth
   // （与历史残留的 types.ts RunOptions 同名不同 interface——后者已删除）。
@@ -607,10 +690,13 @@ export interface SubagentListItem {
   /** 可冷路径 resume（running 且无活进程句柄）。[v4 A-6] B-1「可续聊」对外表达，
    *  agent 据 list 判断哪些 running subagent 实际可续聊（vs 正在忙）。 */
   resumable?: boolean;
-  /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。[v4 A-6] SP-4 级联关闭告知
-   *  替代——砍 before_agent_start 注入通道后，被级联关闭的 record 经 list
-   *  （includeFinished:true）可查，closedReason 显示 'parent-fork'/'parent-new' 等。 */
-  closedReason?: ClosedReason;
+  /**
+   * 终态三态对外语义（U3 C-outcome 一等披露，projectOutcome 唯一出口）：
+   * completed / failed / cancelled，历史 record 无 outcome 字段时兜底派生，
+   * 不可判读的存量形态为 "closed-legacy"。GUI pane / agent 据此判读成败，
+   * 无需翻 error 字段原文（S5）。
+   */
+  outcome?: ProjectedOutcome;
 }
 
 /** background 启动的内层响应（挂在 SubagentToolResult.bgResponse）。 */
@@ -619,6 +705,19 @@ export interface BgResponse {
   mode: "background";
   /** 启动提示文案（"detached, will notify on completion"）。 */
   message: string;
+  /**
+   * 终态三态语义（U3 C-outcome 对外 JSON 契约完备位）。start 时点 record 尚未终态，
+   * 恒 undefined（JSON.stringify 落键省略）；终态成败语义经 list items[].outcome
+   * 披露。旧字段 status/mode/message 原样保留（向后兼容）。
+   */
+  outcome?: ProjectedOutcome;
+  /**
+   * 通知投递契约回显位（U1 预置，U2 通知账本的契约声明）。恒值
+   * "ledger+at-least-once"：主 agent 在当前 run 结束或有限延迟内收到完成通知，
+   * 送达保证为 at-least-once + notifyId 幂等可识别。字段与填充由 U1 负责，
+   * 值语义由 U2（execution/notify-ledger.ts）兑现。
+   */
+  notifyContract: "ledger+at-least-once";
 }
 
 /** list 的内层响应（挂在 SubagentToolResult.listResponse）。 */
@@ -661,7 +760,7 @@ export interface CloseResponse {
  *   - close → closeResponse（subagentId 有值；sessionFile 无意义，可为 null）
  */
 export type SubagentToolResult =
-  | { action: "start"; subagentId: string; sessionFile: string | null; slug: string; bgResponse: BgResponse; __gui__?: GuiRenderResult }
+  | { action: "start"; subagentId: string; sessionFile: string | null; slug: string; /** registry 全等回显（U1）：放行即与 registry 条目全等，"provider/id" 形态。 */ model: string; bgResponse: BgResponse; __gui__?: GuiRenderResult }
   | { action: "list"; subagentId: null; sessionFile: null; listResponse: ListResponse; __gui__?: GuiRenderResult }
   | { action: "cancel"; subagentId: string; sessionFile: null; cancelResponse: CancelResponse; __gui__?: GuiRenderResult }
   | { action: "message"; subagentId: string; sessionFile: null; messageResponse: MessageResponse; __gui__?: GuiRenderResult }
@@ -731,6 +830,19 @@ export interface SubagentRecord {
   externalInstance?: AliveMarker;
   /** fork 模式下的 worktree handle。 */
   worktreeHandle?: WorktreeHandle;
+  /**
+   * 实际执行引擎 id（P4 路由留痕）。缺省 = pi 投影（存量 record 零迁移）；
+   * GUI 警告条/引擎标记的数据源之一。
+   */
+  engine?: string;
+  /** 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源。 */
+  engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U1：EngineHandleData 的持久化消费面子集，引擎无关——
+   * sessionRef 整体透传不枚举内部键）。read 降级链①②级的数据源（runtime
+   * subagent-engine-history）；缺省 = pi（走 JSONL 直读链）。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 }
 
 // ============================================================
@@ -747,6 +859,13 @@ export interface SubagentRecord {
 export interface SubagentsGlobalConfig {
   version: number;
   maxConcurrent: number;
+  /**
+   * 全局默认执行引擎（D9 三层优先级的最底层：调用参数 > agent frontmatter > 本值）。
+   * 缺省 'pi'（P4 路由层 DEFAULT_ENGINE_ID）。加载期只做类型校验，注册表校验归路由层。
+   */
+  defaultEngine?: string;
+  /** 引擎路由策略（D9①）：strict=true 时一切 probe 失败直接报错（不 fallback）。 */
+  engineRouting?: { strict: boolean };
 }
 
 // ============================================================

package/src/execution/ui-request-queue.ts

@@ -55,10 +55,20 @@ export function createUiRequestQueue(
     if (processing || queue.length === 0 || closed) return;
     processing = true;
     const { id, request, signal } = queue.shift()!;
-    handleUiRequest(child, id, request, ctx, signal).finally(() => {
-      processing = false;
-      processNext();
-    });
+    // [F2] .catch 在 .finally 之前：handleUiRequest 是 async 函数，任何同步异常（parseChannel
+    // 解析 throw / respond → writeStdinLine 的 EPIPE 同步 throw / catch 分支内 respond 再次
+    // throw）都会变成 rejection。旧链只有 .finally——rejection 穿透后无人接 →
+    // unhandledRejection（Node 15+ 默认 mode=throw）可崩父进程。记 error 后吞掉，
+    // .finally 照常释放 processing 推进队列（单个请求失败不阻塞后续 UI 请求）。
+    handleUiRequest(child, id, request, ctx, signal)
+      .catch((err: unknown) => {
+        const m = err instanceof Error ? err.message : String(err);
+        logger.error(`[subagents] ui request ${id} (${request.method}) failed unexpectedly: ${m}`);
+      })
+      .finally(() => {
+        processing = false;
+        processNext();
+      });
   }
 
   // [R3] 子进程退出时 abort 所有 pending handler，队列不再阻塞