@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/engine/host-task-spec.ts

@@ -1,47 +1,43 @@
 // src/execution/engine/host-task-spec.ts
 //
-// ExecuteOptions → AgentTaskSpec 的宿主侧最小正向映射（U0：chat 工具域引擎分支）。
+// ExecuteOptions → AgentCallOpts 的宿主侧最小正向映射（U0：chat 工具域引擎分支）。
 //
-// 与 engines/pi/task-spec-mapper.ts 的关系：那是 pi 引擎方向的映射（taskSpecToExecuteOptions
-// 还原 + schemaEnv 内化派生等 pi 专有语义），归属 pi 引擎模块；本 mapper 服务宿主编排层
-// （subagent-service 引擎分支），不 import 任何具体引擎模块（registry.ts 依赖方向纪律：
-// 上层按中立类型组装声明，引擎细节归引擎）。字段映射是 ExecuteOptions → AgentTaskSpec
-// 的中立直译（task/slug/agent/model 原样；thinkingLevel → effort；skillPath +
-// appendSystemPrompt → persona；schema/maxTurns/graceTurns/worktree/cwd 原样透传）。
+// [D6 任务形状合流] 产出类型从原 AgentTaskSpec 改为合流形状 AgentCallOpts（单一任务
+// 形状，EnginePort.run 入参——原 AgentTaskSpec 已删除）。字段映射是 ExecuteOptions →
+// AgentCallOpts 的中立直译（prompt=task 正文、description=slug 短标签；agent/model/
+// thinkingLevel/skillPath/appendSystemPrompt/schema/maxTurns/graceTurns/worktree/cwd
+// 同名透传）。不 import 任何具体引擎模块（registry.ts 依赖方向纪律：上层按中立类型
+// 组装声明，引擎细节归引擎）。
 //
-// conversation/fork 在调用本 mapper 前已被 assertEngineParamSupport 预检拒绝（非 pi 引擎
-// unsupported），透传仅保持映射完整性——未来引擎支持时无需改本函数。
+// schemaEnv 不透传（与原 AgentTaskSpec 形态一致的字段面）：pi 边界直出时 schema 派生
+// 优先——透传会在 chat 域引入「opts.schemaEnv 原值 vs compact 派生值」的取值源变化，
+// 维持派生优先保证与合流前行为逐字节一致。
+//
+// conversation/fork 在调用本 mapper 前已被 capability-gate 预检拒绝（[D3-④]
+// capabilities 驱动的调用前拒绝，非 pi 引擎 unsupported），透传仅保持映射完整性——
+// 未来引擎支持时无需改本函数。
 
+import type { AgentCallOpts } from "../../orchestration/models/types.ts";
 import type { ExecuteOptions } from "../types.ts";
-import type { AgentTaskSpec, PersonaSpec } from "./types.ts";
 
-/** 纯函数：ExecuteOptions（chat 域执行选项）→ 引擎中立任务声明。无副作用、幂等。 */
-export function executeOptionsToEngineTaskSpec(opts: ExecuteOptions): AgentTaskSpec {
-  // persona 归并口径与 pi mapper 一致：skillPath / appendSystemPrompt 有其一即建，
-  // 避免空对象噪声（下游 spread 空数组与 undefined 均为 no-op）。
-  const persona: PersonaSpec | undefined =
-    opts.skillPath !== undefined || opts.appendSystemPrompt !== undefined
-      ? {
-          ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
-          ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
-        }
-      : undefined;
+/** 纯函数：ExecuteOptions（chat 域执行选项）→ 合流任务声明 AgentCallOpts。无副作用、幂等。 */
+export function executeOptionsToEngineTaskSpec(opts: ExecuteOptions): AgentCallOpts {
   return {
-    task: opts.task,
-    slug: opts.slug,
-    agent: opts.agent,
-    model: opts.model,
-    // pi 7 档 thinkingLevel 是引擎私有语义——中立层透传 effort 字符串，各引擎自行映射
-    effort: opts.thinkingLevel,
-    ...(persona !== undefined ? { persona } : {}),
-    schema: opts.schema,
-    maxTurns: opts.maxTurns,
-    graceTurns: opts.graceTurns,
-    fork: opts.fork,
-    worktree: opts.worktree,
-    cwd: opts.cwd,
-    conversation: opts.conversation,
-    idleTimeoutMs: opts.idleTimeoutMs,
+    prompt: opts.task,
+    ...(opts.slug !== undefined ? { description: opts.slug } : {}),
+    ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
+    ...(opts.model !== undefined ? { model: opts.model } : {}),
+    ...(opts.thinkingLevel !== undefined ? { thinkingLevel: opts.thinkingLevel } : {}),
+    ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
+    ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
+    ...(opts.schema !== undefined ? { schema: opts.schema } : {}),
+    ...(opts.maxTurns !== undefined ? { maxTurns: opts.maxTurns } : {}),
+    ...(opts.graceTurns !== undefined ? { graceTurns: opts.graceTurns } : {}),
+    ...(opts.fork !== undefined ? { fork: opts.fork } : {}),
+    ...(opts.worktree !== undefined ? { worktree: opts.worktree } : {}),
+    ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+    ...(opts.conversation !== undefined ? { conversation: opts.conversation } : {}),
+    ...(opts.idleTimeoutMs !== undefined ? { idleTimeoutMs: opts.idleTimeoutMs } : {}),
     // 运行期字段（signal/ctxModel）不入声明——归 RunContext（port.ts 删字段去向）。
   };
 }

package/src/execution/engine/model-validation.ts

@@ -0,0 +1,177 @@
+// src/execution/engine/model-validation.ts
+//
+// [u-h2] 引擎感知的派发期 model 校验入口 + 错误文案构造。设计权威源：
+// docs/design/timeout-audit-hygiene-batch.md §3.2（D2-1 路由先行 / D2-2 validateModel
+// 可选面 / D2-3「引擎与模型不配套」文案 / D2-4 pi 未命中跨引擎候选）。
+//
+// 背景（§2.2 双重错配）：model 校验曾固定用 pi registry 且时机在引擎路由之前——
+// zcode 合法模型被误导性拒绝（F2-A）、pi 模型过校验后到 zcode 执行期才炸（F2-B）。
+// 修复定案：校验源 = 目标引擎 registry（EnginePort.validateModel 可选面），时机 =
+// 路由之后的派发同步期（record 创建前，不产生孤儿 record）。
+//
+// 两个调用点共享本入口与错误文案（D2-2 调用点双路径覆盖）：
+//   ① chat 路径 subagent-service.executeViaEngine（非 pi 分支）；
+//   ② workflow 路径 subprocess-agent-runner.run（route.engine.run 之前，非 pi 分支）。
+
+import { stripThinkingSuffix } from "../../shared/model-ref.ts";
+import type { EnginePort } from "./port.ts";
+import { DEFAULT_ENGINE_ID } from "./registry.ts";
+import { toErrorMessage } from "../../core/error-message.ts";
+
+/** 错误消息中列出的目标引擎可用清单上限（防超长错误信息；与 shared/model-ref 同量级口径）。 */
+const ENGINE_MODEL_LIST_LIMIT = 20;
+
+// ============================================================
+// 场景 2：engine+model 不配套的结构化错误（D2-3）
+// ============================================================
+
+/**
+ * 「引擎与模型不配套」错误（设计 §3.2.1 场景 2）。code 沿用 §3.3.3 错误规格表的
+ * model_not_available（与 ZcodePrepareError 同码——同一失败域的早抛形态）。
+ */
+class EngineModelMismatchError extends Error {
+  readonly code = "model_not_available";
+  /** 恢复指引（错误 → 权威源 → 重试闭环；EngineError.recovery 同构字段）。 */
+  readonly recovery: string;
+
+  constructor(message: string, recovery: string) {
+    super(message);
+    this.name = "EngineModelMismatchError";
+    this.recovery = recovery;
+  }
+}
+
+/**
+ * 非 pi 引擎的派发同步期 model 校验（两路径统一入口）。
+ *
+ * - 引擎实现 validateModel：同步裁决（含 undefined = 查引擎缺省模型），返回 canonical
+ *   全名供 record.model 留痕；失败包装为 EngineModelMismatchError（场景 2 文案：
+ *   点破 registry 独立 + 目标引擎可用清单 + 按引擎区分的省略语义修正动作）。
+ * - 引擎未实现 validateModel：返回 modelRef 原样（透传给其 prepare 期校验兜底——
+ *   现状语义，未来引擎零强制接入）。
+ *
+ * @param engine   路由解析出的目标引擎
+ * @param modelRef 显式 model（调用参数或 agent .md frontmatter；undefined = 引擎缺省语义）
+ * @returns canonical ref（引擎裁决后全名）；未实现校验面时 = modelRef 原样
+ */
+export function validateModelForEngine(
+  engine: EnginePort,
+  modelRef: string | undefined,
+): string | undefined {
+  if (engine.id === DEFAULT_ENGINE_ID) return modelRef; // 防御：pi 不经此入口（走既有三层解析链）
+  if (typeof engine.validateModel !== "function") return modelRef;
+  try {
+    return engine.validateModel(modelRef).canonicalRef;
+  } catch (err) {
+    throw buildMismatchError(engine, modelRef, err);
+  }
+}
+
+/**
+ * 场景 2 文案构造（D2-3）：① 点破 registry 独立；② 列目标引擎可用清单（数据源
+ * listModels；引擎未实现时省略清单行，保留引擎原始错误作诊断行）；③ 👉 修正动作
+ * （清单重试 / 省略 model 用引擎缺省——pi 的「继承主 agent」语义对非 pi 引擎是错误
+ * 指引，此处按引擎缺省表述）。
+ */
+function buildMismatchError(engine: EnginePort, modelRef: string | undefined, cause: unknown): EngineModelMismatchError {
+  const ref = modelRef === undefined || modelRef.trim() === "" ? "(engine default)" : modelRef;
+  const lines = [
+    `model '${ref}' is not available on engine '${engine.id}'.`,
+    `Engine registries are independent — ids in <available_provider_models> (pi registry) do NOT apply to '${engine.id}' dispatches.`,
+  ];
+  const available = safeListModels(engine);
+  if (available.length > 0) {
+    lines.push(`${engine.id} models with configured credentials:`);
+    lines.push(`  ${available.slice(0, ENGINE_MODEL_LIST_LIMIT).join(", ")}${available.length > ENGINE_MODEL_LIST_LIMIT ? ", ..." : ""}`);
+  }
+  // 引擎缺省模型名（validateModel(undefined) 成功才给——失败时省略句不带具体名，
+  // 缺省本身也不可用属于凭据级故障，引擎原始错误行已覆盖诊断）。
+  const engineDefault = safeEngineDefault(engine);
+  lines.push(
+    `👉 Retry with one of the above (exact string), or omit \`model\` to use the '${engine.id}' engine default` +
+      (engineDefault !== undefined ? ` (${engineDefault})` : "") +
+      `.`,
+  );
+  // 引擎侧原始裁决失败原因（provider 未配凭据 / 模型未启用等）——诊断行，避免包装层吞掉细节。
+  lines.push(`Engine said: ${toErrorMessage(cause)}`);
+  const recovery =
+    `Retry with an exact model id from the '${engine.id}' list above, or omit the \`model\` param to use the '${engine.id}' engine default` +
+    (engineDefault !== undefined ? ` (${engineDefault})` : "") +
+    `.`;
+  return new EngineModelMismatchError(lines.join("\n"), recovery);
+}
+
+// ============================================================
+// 场景 3：pi registry 未命中的跨引擎纠错候选（D2-4）
+// ============================================================
+
+/** notFoundError 的结构化标记（shared/model-ref.ts 挂载；跨引擎反查的识别面）。 */
+interface RefNotFoundMarker {
+  refNotFound?: boolean;
+  refInput?: string;
+}
+
+/**
+ * pi registry 未命中时反查其他已注册引擎的 listModels（D2-4）：**唯一**引擎全等命中
+ * （strip thinking 后缀后与清单 id 全等——对齐零宽容原则，模糊匹配不参与建议）才追加
+ * 「该 id 属于引擎 X」候选段；多引擎命中/零命中原样返回（既有文案零回归——V2-4③）。
+ *
+ * @param err        resolveModel 抛出的错误（须带 refNotFound 标记才处理）
+ * @param engineIds  已注册引擎清单（registry.listEngines 快照）
+ * @param getEngineFn 引擎获取（registry.getEngine；测试注入）
+ * @returns 原错误（无可附候选）或追加候选段的新错误（不 mutate 原错误）
+ */
+export function withCrossEngineHint(
+  err: unknown,
+  engineIds: readonly string[],
+  getEngineFn: (id: string) => EnginePort | undefined,
+): unknown {
+  if (!(err instanceof Error)) return err;
+  const marker = err as Error & RefNotFoundMarker;
+  if (marker.refNotFound !== true || marker.refInput === undefined) return err;
+  const clean = stripThinkingSuffix(marker.refInput);
+
+  let matchedEngineId: string | undefined;
+  let matchCount = 0;
+  for (const id of engineIds) {
+    if (id === DEFAULT_ENGINE_ID) continue; // pi 是裁决源本身，不参与反查
+    const engine = getEngineFn(id);
+    if (engine === undefined) continue;
+    // 单引擎清单读取失败/无清单（safeListModels → []）不阻塞反查（可发现性降级语义）
+    if (safeListModels(engine).includes(clean)) {
+      matchCount++;
+      matchedEngineId ??= id;
+    }
+  }
+  if (matchCount !== 1 || matchedEngineId === undefined) return err;
+  return new Error(
+    `${err.message}\n` +
+      `This id matches the registry of engine '${matchedEngineId}'.\n` +
+      `👉 Retry with engine: '${matchedEngineId}', or use a pi model from <available_provider_models>, ` +
+      `or omit \`model\` to inherit the main agent model.`,
+  );
+}
+
+// ============================================================
+// 内部：引擎面的失败安全读取
+// ============================================================
+
+/** 引擎可用清单（listModels 失败安全——校验错误路径不再叠加清单读取故障；null 契约按零清单）。 */
+function safeListModels(engine: EnginePort): string[] {
+  if (typeof engine.listModels !== "function") return [];
+  try {
+    return engine.listModels()?.map((m) => m.id) ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** 引擎缺省模型（validateModel(undefined)；失败安全返回 undefined）。 */
+function safeEngineDefault(engine: EnginePort): string | undefined {
+  if (typeof engine.validateModel !== "function") return undefined;
+  try {
+    return engine.validateModel(undefined).canonicalRef;
+  } catch {
+    return undefined;
+  }
+}

package/src/execution/engine/port.ts

@@ -4,6 +4,15 @@
 // §3.3.5「EnginePort 完整签名」——本文件是可编码落地的契约层，后续 wave（公共降级层
 // P2 / zcode 引擎 P3 / 配置路由 P4）以本接口为实现契约，字段级变更须先改设计文档。
 //
+// 字段级扩展登记（接上文纪律——先改设计文档再扩接口）：
+//   - [R1 已实施 2026-08-30] EnginePort.dispose?()——引擎停机面。权威源：
+//     docs/design/zcode-engine-appserver-resident.md §3.3 D6 / §3.4 不变量 4。
+//   - [R4 已实施 2026-08-30] RunContext.onHandleReady——运行中句柄回填通道
+//     （同设计 §3.4 不变量 3：sessionRef 在 create 应答后经本回调送达编排层，
+//     与 onPoolResolved 分立两个时点）。
+//   - [u-h2 已实施 2026-09-05] EnginePort.validateModel?()——派发同步期 model 校验面。
+//     权威源：docs/design/timeout-audit-hygiene-batch.md §3.2 D2-2。
+//
 // 四个能力面（D1）：
 //   run        —— 主语义：一次性 fire-to-completion 任务执行；
 //   interact   —— 交互控制面（chatMode 的 message/close/cancel + idle，可选能力面，
@@ -14,14 +23,15 @@
 
 import type { ChildProcess } from "node:child_process";
 
+import type { AgentCallOpts } from "../../orchestration/models/types.ts";
 import type { ModelInfo } from "../model-resolver.ts";
 import type { SubagentStream } from "../stream-sink.ts";
 import type { AgentEvent } from "../types.ts";
 import type {
   AgentOutcome,
-  AgentTaskSpec,
   EngineCapabilities,
   EngineHandle,
+  EngineHandleData,
   InteractAction,
   InteractResult,
   ProbeReport,
@@ -33,9 +43,9 @@ import type {
 // ============================================================
 
 /**
- * run 的运行期上下文。任务声明（AgentTaskSpec）与运行期句柄分离——signal/ctxModel/
- * onComplete 从 ExecuteOptions 移出（设计 §3.3.5 删字段去向），因为它们是宿主注入的
- * 运行期对象，不属于跨引擎持久化的任务声明。
+ * run 的运行期上下文。任务声明（AgentCallOpts，D6 合流后的单一形状）与运行期句柄
+ * 分离——signal/ctxModel/onComplete 从 ExecuteOptions 移出（设计 §3.3.5 删字段去向），
+ * 因为它们是宿主注入的运行期对象，不属于跨引擎持久化的任务声明。
  *
  * 常驻进程友好（D1）：onEvent 回调式（而非迭代器式）+ AbortSignal——引擎内部换常驻
  * server 实现（未来 driver host）时接口不动。
@@ -49,7 +59,13 @@ export interface RunContext {
   signal?: AbortSignal;
   /** 事件流出口（host 消费后统一落 journal，D6 第②级）。 */
   onEvent?: (event: AgentEvent) => void;
-  /** model 解析第三层兼底（现有 D-008 语义不变）。 */
+  /**
+   * model 解析第三层兜底（现有 D-008 语义不变）——**pi 链路专属兜底**：经
+   * taskSpecToExecuteOptions → resolveModel 第三层消费（PiEngine 直通）。自带
+   * provider 体系与缺省模型的引擎（如 zcode：requested > 引擎缺省常量链）按自身
+   * 默认链解析，不消费本字段（zcode 侧在「ctx 有模型但被忽略」时出声留痕，
+   * zcode-engine.warnIgnoredCtxModel）。
+   */
   ctxModel?: ModelInfo;
   /**
    * text_delta streaming 通道（宿主侧 UI widget）。与 onEvent 平行的 text_delta 出口：
@@ -81,12 +97,27 @@ export interface RunContext {
    * 未来流式引擎需在事件出口前调用）。
    */
   onPoolResolved?: (poolKey: string) => void;
+  /**
+   * [R4 §3.4 不变量 3] 运行中句柄回填通道：引擎在「session/create 应答到达后」
+   * 立即回调（早于 run resolve——stream 引擎的 run 生命周期远长于会话建立）。
+   * 与 onPoolResolved 分立两个时点：poolKey 在 prepare 期（onPoolResolved，连接
+   * 建立前即可知），sessionRef 在 create 应答后（本回调）。编排层收到后立即回填
+   * record.engineHandle 并落 entry——运行中的 GUI 经 entry 重建 record 即拿到
+   * ①②级读取钥匙，不再等 run resolve 后的终态回填。可选回调：不支持运行中回填
+   * 的引擎（spawn 单轮、终态即回填）不调用，宿主语义不受影响。
+   */
+  onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
   /**
    * [U0 D10] 引擎 spawn 的子进程句柄注册钩子（宿主终止链记账）。引擎在 spawn 成功后
    * 同步回调（与 pi runSpawn 的 spawnedChildren.set 同构时机）；宿主据此把 child 注册进
    * session-runner 的 spawnedChildren Map（cancel SIGTERM / dispose 收割兜底 / killAll
    * 全量清理对非 pi 引擎 record 生效）。close/error 后由宿主按句守卫移除。可选：引擎
    * 内部不 spawn 进程（如未来常驻 driver host 实现）时不调用，宿主记账自然为空。
+   *
+   * 边界声明（R1 D6）：本钩子只用于 per-record 一次性 spawn（一任务一进程模态）。
+   * 引擎持有的常驻进程（跨任务共享，如 app-server 常驻连接）不经本钩子注册、不进
+   * spawnedChildren Map——其生命周期完全归引擎 dispose 管理（防 per-record 重复
+   * SIGTERM / 单任务 abort 误杀共享进程）。
    */
   onChildSpawned?: (child: ChildProcess) => void;
 }
@@ -129,8 +160,9 @@ export interface EnginePort {
   /** D7（factory 初始化 + 版本变化检测触发；opts.force 跳过缓存强探）。 */
   probe(opts?: { force?: boolean }): Promise<ProbeReport>;
 
-  /** D1 主语义：fire-to-completion。 */
-  run(task: AgentTaskSpec, ctx: RunContext): Promise<EngineRunResult>;
+  /** D1 主语义：fire-to-completion。[D6 合流] task = AgentCallOpts（单一任务形状，
+   *  原 AgentTaskSpec 已并入——字段裁定见 orchestration/models/types.ts）。 */
+  run(task: AgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
 
   /**
    * D1 可选面：交互控制面。pi 首期原生实现（现有 chatMode 行为直通）；不支持
@@ -150,4 +182,30 @@ export interface EnginePort {
    * 侧零改动。
    */
   listModels?(): Array<{ id: string; name?: string }> | null;
+
+  /**
+   * [u-h2 D2-2] 可选面：派发同步期 model 校验（引擎 registry 单源裁决）。实现引擎复用其
+   * prepare 期同一校验函数（zcode: resolveZcodeModelRef——同一函数两处消费，canonicalRef
+   * 归一化与短名缺省 provider 决策不产生双实现漂移）；校验失败同步 throw（编排层包装为
+   * 「引擎与模型不配套」错误，见 engine/model-validation.ts）。
+   *
+   * modelRef undefined = 查询引擎缺省模型（D2-1：主 agent 的 pi id 不透传给非 pi 引擎，
+   * 缺省语义归引擎——zcode 落 ZCODE_FALLBACK_DEFAULT_MODEL）。返回 canonical 全名供
+   * record.model 留痕。
+   *
+   * 未实现：model 透传，引擎自身 prepare 期校验兜底（现状语义）；pi 不实现（pi 链走
+   * 既有三层解析 + assertCanonicalModelRef 裁决，搬迁是大重构，设计 D2-2 被否②）。
+   */
+  validateModel?(modelRef: string | undefined): { canonicalRef: string };
+
+  /**
+   * [R1 D6] 可选停机面：释放引擎持有的常驻资源（如 app-server 常驻进程 / 长连接）。
+   * 幂等契约（§3.4 不变量 4）：重复调用无副作用；dispose 后首个 run 自动重建（与
+   * 「进程死后重建」同一代码路径）。可选成员保持向后兼容——无常驻资源的引擎（pi
+   * 现状 spawn 单轮）不必实现。等待策略（D6①「触发不等待」）：宿主收割入口
+   * （registry disposeEngines → killAllSpawnedChildren）只同步调用拿 Promise 不
+   * await，引擎实现须自行保证同步面（立即 fire close 帧 + 同步 SIGTERM）在返回
+   * Promise 前完成；grace→SIGKILL 升级序列属异步面（promise 段）。
+   */
+  dispose?(): Promise<void>;
 }

package/src/execution/engine/registry.ts

@@ -10,9 +10,15 @@
 //
 // 依赖方向（设计 §3.3.1 贯穿纪律④）：registry 只依赖 port.ts 的类型，不 import 任何
 // 具体引擎——注册由组合根（index.ts）或引擎自己的 registration 模块完成，防循环依赖。
+// （core/logger 是 facade 基础设施非引擎，dispose best-effort 记日志需要它，不违反本纪律。）
+
+import { getLogger } from "../../core/logger.ts";
 
 import type { EnginePort } from "./port.ts";
 
+// core log facade（execution 层统一 "subagents" component，模块顶层缓存惯例）。
+const logger = getLogger("subagents");
+
 /** 引擎工厂：惰性创建引擎实例（getEngine 首次取用时执行）。 */
 export type EngineFactory = () => EnginePort;
 
@@ -87,17 +93,64 @@ function getRegistrySlot(): EngineRegistrySlot {
   return slot;
 }
 
+/**
+ * [R1 D6] 触发引擎 dispose：同步调用拿 Promise 不 await（「触发不等待」，D6①——
+ * dispose 的同步面〔fire close 帧 + 同步 SIGTERM〕由引擎实现保证在返回 Promise 前
+ * 完成，registry 不等待异步段）。同步 throw 与异步 reject 均记日志吞掉，绝不外溢
+ * 阻断调用方——重注册替换（D6②）与宿主收割（D6③）都是 best-effort 面，且 reject
+ * 无人接会成为 unhandledRejection 崩宿主。两条 dispose 路径共用本函数。
+ */
+function triggerEngineDispose(engine: EnginePort, source: string): void {
+  if (typeof engine.dispose !== "function") return;
+  try {
+    engine.dispose().then(undefined, (err: unknown) => {
+      logger.warn(
+        `[engine-registry] engine '${engine.id}' dispose rejected (${source}, best-effort continue): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    });
+  } catch (err) {
+    logger.warn(
+      `[engine-registry] engine '${engine.id}' dispose threw synchronously (${source}, best-effort continue): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
 /**
  * 登记引擎工厂。重复注册同一 id = 覆盖（组合根可能多次执行，如每次 session_start 重跑
  * registerPiEngine——幂等覆盖保证不炸也不堆积），覆盖时丢弃缓存的旧单例，让下一次
  * getEngine 用新工厂重建。
+ *
+ * [R1 D6②] 覆盖前对已实例化的旧单例触发 dispose（防泄漏——旧实例可能持有常驻进程/
+ * 长连接）；触发不等待 + 失败不阻断（见 triggerEngineDispose），幂等覆盖语义不变。
  */
 export function registerEngine(id: string, factory: EngineFactory): void {
   const slot = getRegistrySlot();
+  const previous = slot.singletons.get(id);
+  if (previous) triggerEngineDispose(previous, `registerEngine('${id}') overwrite`);
   slot.factories.set(id, factory);
   slot.singletons.delete(id);
 }
 
+/**
+ * [R1 D6③] 对已实例化的引擎单例触发 dispose（触发不等待）。宿主唯一收割入口
+ * （session-runner killAllSpawnedChildren）在杀 per-record children 之前调用——
+ * 常驻进程的回收归引擎 dispose，本函数只负责按序触发。
+ *
+ * 只遍历 singletons：已实例化才可能持有常驻资源，绝不经 getEngine 实例化未用
+ * 引擎（停机路径反向创建资源违背停机语义）。dispose 后不删单例——幂等与
+ * 「dispose 后首个 run 自动重建」由引擎实现承诺（§3.4 不变量 4），registry
+ * 不越权管理引擎内部生命周期。
+ */
+export function disposeEngines(): void {
+  for (const engine of getRegistrySlot().singletons.values()) {
+    triggerEngineDispose(engine, "disposeEngines()");
+  }
+}
+
 /** 未注册 id 抛 EngineNotFoundError（含已注册清单与配置指引）。 */
 export function getEngine(id: string): EnginePort {
   const slot = getRegistrySlot();

package/src/execution/engine/routing.ts

@@ -150,7 +150,8 @@ export async function routeEngine(opts: EngineRouteOptions): Promise<EngineRoute
   }
   // 守卫 a/b（首期合流）：显式指定（调用参数或 step 级）= 能力依赖声明，静默换引擎
   // 违反意图——沙箱类任务被静默卸除安全能力正是要防的形态（D9① 原文）。守卫 b 的
-  // 独立载体（AgentTaskSpec.requires）下钻后在本分支前独立判定，首期显式 engine 即声明。
+  // 独立载体（合流形状 AgentCallOpts 上的能力依赖声明字段，requires 已随 D6 裁撤）
+  // 下钻后在本分支前独立判定，首期显式 engine 即声明。
   if (routing.source === "call") {
     throw probeFailedError(routing.engineId, report, "engine 来自调用参数显式指定（能力依赖声明）——不兜底");
   }
@@ -216,3 +217,76 @@ function describeRoutingSource(routing: EngineRoutingInput): string | undefined
   }
   return undefined;
 }
+
+// ============================================================
+// routeEngineForHost：宿主两调用点的统一编排（D3-② 路由单点）
+// ============================================================
+
+/** routeEngineForHost 的参数（宿主装配：本地 pi 引擎 + 路由三件注入）。 */
+export interface HostRouteOptions {
+  /** 三层路由输入（调用方装配：调用参数 / frontmatter / 全局默认）。 */
+  routing: EngineRoutingInput;
+  /**
+   * 守卫 c 判据：调用方显式指定的 model（与 routeEngine.taskModel 同口径——解析后的
+   * 兼底 model 恒非空会把一切兜底误判为 model 绑定命中，故只传显式值）。
+   */
+  taskModel?: string;
+  /** engineRouting.strict（config.json）：true = 一切 probe 失败直接报错。 */
+  strict: boolean;
+  /** 探针执行体（生产 = registry 引擎 .probe()；测试可注入）。 */
+  probe: (engineId: string) => Promise<ProbeReport>;
+  /**
+   * 本地 pi 引擎实例（chat 域 = Service 的 chatPiEngine；workflow 域 = SAR 的 per-session
+   * DI 实例）。pi 请求与「非 pi 兜底回 pi」两种形态都由它接管——不依赖 registry 全局
+   * 注册态（单测注入 mock 时全局单例不可见；生产环境两者是同一进程单例对象）。
+   */
+  piEngine: EnginePort;
+  /** 非 pi 引擎获取（缺省 registry.getEngine；测试注入）。 */
+  getEngineFn?: (engineId: string) => EnginePort;
+  /** 非 pi 注册表存在性检查（缺省 registry.hasEngine）。 */
+  hasEngineFn?: (engineId: string) => boolean;
+  /** 非 pi 注册表清单（缺省 registry.listEngines）。 */
+  listEnginesFn?: () => string[];
+}
+
+/**
+ * 宿主侧统一路由编排（D3-②：唯一实现，两调用点——SubagentService.execute 与
+ * SAR.run）。把原先散在两调用点的「pi 同步短路 + registry 注入（本地 pi 恒可用，
+ * engine_not_found 文案不把本地 pi 漏报成未注册）+ 兜底回 pi 时换本地实例」收敛到本函数。
+ *
+ * 返回值形态（时序契约）：pi 请求路径**同步返回** EngineRouteResult（非 Promise）——
+ * 不引入微任务边界，SAR 的「run 内首个 await 前已触达 executeAndAwait」缺省路径时序
+ * 与旧形态逐字节一致；非 pi 路径返回 Promise（probe 编排固有异步），调用方统一用
+ * `routed instanceof Promise ? await routed : routed` 消费（pi 路径零 await）。
+ */
+export function routeEngineForHost(opts: HostRouteOptions): EngineRouteResult | Promise<EngineRouteResult> {
+  const routing = resolveEngineRouting(opts.routing);
+
+  // pi 请求（缺省/显式 pi）：本地 DI 实例同步短路——pi 恒免探、无 fallback 可言，
+  // 不经 routeEngine 的 await/probe（「缺省路径行为零变化」A1 硬约束）。
+  if (routing.engineId === DEFAULT_ENGINE_ID) {
+    return {
+      engine: opts.piEngine,
+      engineId: DEFAULT_ENGINE_ID,
+      requestedEngineId: DEFAULT_ENGINE_ID,
+      source: routing.source,
+    };
+  }
+
+  return routeEngine({
+    routing: opts.routing,
+    taskModel: opts.taskModel,
+    strict: opts.strict,
+    probe: opts.probe,
+    // 本地 pi 恒可用（per-session DI 绑定）——get/has/list 注入同一口径：
+    // probe 失败兜底回 pi 时取本地实例接管，engine_not_found 文案不漏报本地 pi。
+    getEngineFn: (engineId) =>
+      engineId === DEFAULT_ENGINE_ID ? opts.piEngine : (opts.getEngineFn?.(engineId) ?? getEngine(engineId)),
+    hasEngineFn: (engineId) =>
+      engineId === DEFAULT_ENGINE_ID || (opts.hasEngineFn?.(engineId) ?? hasEngine(engineId)),
+    listEnginesFn: () => {
+      const listed = opts.listEnginesFn?.() ?? listEngines();
+      return listed.includes(DEFAULT_ENGINE_ID) ? listed : [DEFAULT_ENGINE_ID, ...listed];
+    },
+  });
+}