@zhushanwen/subagent-core 0.4.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

@@ -10,6 +10,8 @@
 //   - [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 任务执行；
@@ -21,12 +23,12 @@
 
 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,
@@ -41,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）时接口不动。
@@ -158,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 行为直通）；不支持
@@ -180,6 +183,21 @@ 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 自动重建（与

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];
+    },
+  });
+}

package/src/execution/engine/types.ts

@@ -6,12 +6,13 @@
 // 为什么单独一层：执行层现有四个核心类型（ExecuteOptions/AgentEvent/AgentResult/AgentRunner
 // port）的中立是「碰巧的，不是设计的」——thinkingLevel 是 pi 7 档枚举、skillPath 假设引擎有
 // --skill flag、conversation/idleTimeoutMs 是 pi chatMode 专属形态（设计 §2.1）。本文件把
-// 「agent 调用」的引擎无关语义显式化为 AgentTaskSpec / AgentOutcome 等类型，EnginePort
-// （port.ts）与其下各引擎适配器都以本层为唯一契约点。
+// 「agent 调用」的引擎无关语义显式化为 AgentOutcome 等类型，EnginePort（port.ts）与其下
+// 各引擎适配器都以本层为唯一契约点。
 //
-// 泛化原则（D2）：从现有类型泛化，不另起炉灶——字段与 execution/types.ts 的
-// ExecuteOptions、orchestration/models/types.ts 的 AgentResult 逐一锚定，标注「泛化」的
-// 条目语义有变，标注「新增」为引擎层新引入。
+// [D6 任务形状合流] 原本层的任务声明类型 AgentTaskSpec/PersonaSpec 已并入
+// orchestration/models/types.ts 的 AgentCallOpts（单一任务形状，SAR 直产、pi 边界一次
+// 直出——docs/design/subagent-dual-track-convergence.md §3.3 D6）。本文件不再定义任务
+// 声明；EnginePort.run 的入参即 AgentCallOpts（字段裁定与裁撤记录见其类型注释）。
 //
 // AgentResult 消歧（设计 §2.1/§3.3.5）：仓内有两个同名 AgentResult——
 //   ① orchestration 层 workflow 消费的那份（orchestration/models/types.ts，主字段
@@ -21,8 +22,8 @@
 //      ——record 内部投影，保持原名不动。
 // 引擎层终态命名 AgentOutcome，与两者不同名，消除「同名不同义」。
 
-import type { AgentUsage, ToolCallEntry } from "../../orchestration/models/types.ts";
-import type { AgentUsageTotal, ToolCall, WorktreeHandle } from "../types.ts";
+import type { AgentFailureKind, AgentUsage, ToolCallEntry } from "../../orchestration/models/types.ts";
+import type { AgentUsageTotal, ToolCall } from "../types.ts";
 
 // AgentEvent 8 种事件原样保留，唯一权威定义仍是 execution/types.ts——引擎层 re-export
 // 不复制第二份（设计 §3.3.5）；经 shared/agent-event.ts 的既有出口转发，维持「shared/
@@ -30,101 +31,6 @@ import type { AgentUsageTotal, ToolCall, WorktreeHandle } from "../types.ts";
 // 一次 turn_end）由 conformance 套件断言（P4），不在类型层编码。
 export type { AgentEvent } from "../../shared/agent-event.ts";
 
-// ============================================================
-// AgentTaskSpec（= 现有 ExecuteOptions 泛化，D2）
-// ============================================================
-
-/** 人设（persona）注入规格：原 skillPath + appendSystemPrompt 收拢进一个语义单元（D2）。 */
-export interface PersonaSpec {
-  /**
-   * agent 名/路径。与 AgentTaskSpec.agent 的分工：agent 是 resolveIdentity 的身份解析
-   * 键（模型/系统提示等身份语义）；agentRef 是 persona 注入通道的定位符——引擎按
-   * capabilities.personaInjection 决定注入通道（file/flag/prompt）时用它定位人设。
-   * pi 引擎不消费此字段（身份解析走 spec.agent），留给 flag/file 通道的引擎。
-   */
-  agentRef?: string;
-  /**
-   * 原 ExecuteOptions.skillPath。公共 persona 路由三策略（file/flag/prompt）的分流
-   * 载体（D4）——超长 prompt 时优先 file/flag 通道分流的落点。
-   */
-  skillPath?: string;
-  /** 追加系统提示内容数组（原样透传；schema 仿真段由公共降级层拼装后放入，P2）。 */
-  appendSystemPrompt?: string[];
-}
-
-/**
- * 引擎无关的 agent 任务声明（= ExecuteOptions 泛化，字段逐条锚定设计 §3.3.5）。
- *
- * 与 ExecuteOptions 的差异（泛化点）：
- *   - thinkingLevel（pi 7 档枚举语义）→ effort?: string，各引擎自行映射或忽略；
- *   - skillPath + appendSystemPrompt → persona（PersonaSpec）；
- *   - conversation/idleTimeoutMs 保留原名透传——属 interact 交互控制面的 task 标志（D1），
- *     不是 pi 专有语义的泄漏，而是「任务声明里声明交互模式」的中立表达；
- *   - 删字段去向：signal/ctxModel/onComplete 是运行期句柄，移入 RunContext（port.ts）；
- *     schemaEnv 内化到 PiEngine（从 task.schema 派生，见 engines/pi/task-spec-mapper.ts）。
- *
- * 新增（为后续 wave 预留形状，P1 无生产写入方）：
- *   - denyTools：中立工具 denylist（附录 A 该行的载体）；
- *   - permissionMode：中立权限模式（映射按 capabilities.permissionMode）。
- */
-export interface AgentTaskSpec {
-  /** 原样（ExecuteOptions.task）。 */
-  task: string;
-  /** 原样（ExecuteOptions.slug，≤35 字符）。 */
-  slug: string;
-  /** 原样（ExecuteOptions.agent，resolveIdentity 的 agent ref）。 */
-  agent?: string;
-  /** 原样（ExecuteOptions.model；在引擎 provider 体系内解释，D9②）。 */
-  model?: string;
-  /**
-   * 泛化：原 ExecuteOptions.thinkingLevel。引擎无关的推理投入档位字符串——
-   * pi 引擎把它原值映射回 thinkingLevel 7 档；其他引擎自行映射（CC 5 档）或忽略
-   * （kimi ❌）。不定义联合枚举：档位集合是引擎私有语义，中立层只透传字符串。
-   */
-  effort?: string;
-  /** 泛化：原 skillPath + appendSystemPrompt 收拢（D2）。 */
-  persona?: PersonaSpec;
-  /**
-   * 原样（ExecuteOptions.schema）。native/emulated 分流依据（D4 硬边界）：pi 的
-   * PI_WORKFLOW_SCHEMA env 注入链路按 native 直传，公共仿真层只服务 emulated 引擎。
-   */
-  schema?: Record<string, unknown>;
-  /**
-   * 原样（ExecuteOptions.maxTurns）。pi 引擎专属（turn limiter + spawn watchdog
-   * 估算依赖 pi 的 turn_end 事件流）；其他引擎 prepare 期显式拒绝（U4，同 fork 模式）。
-   * 显式 0 压过 SPAWN_WATCHDOG_ENV 兑底（SP-6 参数 > env，U5）；undefined 未传才由
-   * env 兑底。
-   */
-  maxTurns?: number;
-  /** 原样（ExecuteOptions.graceTurns）。 */
-  graceTurns?: number;
-  /** 原样（ExecuteOptions.fork）。pi 专属；其他引擎 prepare 期按 capabilities 拒绝。 */
-  fork?: boolean;
-  /**
-   * 原样（ExecuteOptions.worktree）。公共层职责（worktree-manager），非引擎职责——
-   * 引擎只把它当 spawn cwd 的来源之一。
-   */
-  worktree?: boolean | WorktreeHandle;
-  /** 原样（ExecuteOptions.cwd）。 */
-  cwd?: string;
-  /** 原样（ExecuteOptions.conversation，interact 控制面的 task 标志，D1）。 */
-  conversation?: boolean;
-  /** 原样（ExecuteOptions.idleTimeoutMs，同上）。 */
-  idleTimeoutMs?: number;
-  /** 新增：中立工具 denylist。各引擎做语法映射（附录 A「工具 denylist」行的载体）。 */
-  denyTools?: string[];
-  /** 新增：中立权限模式。映射按 capabilities.permissionMode（kimi fixed auto = ignored）。 */
-  permissionMode?: string;
-  /**
-   * [P4 形状预留，D9① 守卫 b 的独立载体] 任务对引擎能力的显式依赖声明。
-   * 首期无生产写入方：守卫 b 与守卫 a 合流（显式 engine 即能力依赖声明）——调用方
-   * 按引擎 id 表达依赖。下钻时机（AgentTaskSpec 泛化成熟后）：调用方改按能力表达
-   * （如 requires: { sandbox: 'native' }），路由层将本字段与各引擎 capabilities()
-   * 对照，无引擎满足时报 engine_capability_unsupported（调用前拒绝，D11 处置三级）。
-   */
-  requires?: Partial<EngineCapabilities>;
-}
-
 // ============================================================
 // AgentOutcome（锚定 orchestration 层 AgentResult，§3.3.5）
 // ============================================================
@@ -136,6 +42,13 @@ export interface AgentTaskSpec {
 export interface AgentOutcome {
   /** 原样（AgentResult.content）。 */
   content: string;
+  /**
+   * 原样（AgentResult.failureKind，D5-③ 失败分诊结构化标签）。产出侧唯一识别点 =
+   * engines/pi/output-collector（collectResult 分类写入）；缺省 = unknown = 可重试
+   * （消费侧 executeAgentCall 只读字段分诊，不扫 error 文案）。非 pi 引擎不产出，
+   * 恒缺省（unknown 语义）。
+   */
+  failureKind?: AgentFailureKind;
   /**
    * 原样（AgentResult.parsedOutput）。native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：
    * native 路径公共层不做二次校验、不改写其结果）。
@@ -274,6 +187,15 @@ export interface EngineCapabilities {
   interrupt: "native" | "kill-only";
   /** kimi headless 固定 auto = ignored；GUI 据此隐藏/提示。 */
   permissionMode: "native" | "fixed" | "ignored";
+  /**
+   * [D3-④ r3 裁定] maxTurns 轮数上限的执行能力位（pi = true：turn limiter + spawn
+   * watchdog 估算兑现；zcode = false：无 turn_end 语义，静默丢弃会造成「传了上限却
+   * 失控」假象）。调用前预检（common/capability-gate）按本位拦「声明不支持的能力」
+   * ——pi 不拦 maxTurns（已支持能力，由 turn-limiter 执行）、zcode 同步拒绝。
+   * 现状 11 个能力位无可承载 maxTurns 的语义位（fork 拦截可借 session 分叉通道族判，
+   * maxTurns 无可借位），故扩位而非保留引擎内硬编码 shape 检查。
+   */
+  maxTurns: boolean;
 }
 
 // ============================================================
@@ -296,7 +218,12 @@ export interface ProbeReport {
  * 声明 conversation unsupported 的引擎调用前拒绝（engine_capability_unsupported）。
  */
 export type InteractAction =
-  | { kind: "message"; payload: string }
+  /**
+   * interrupt：true = steer（抢占）/ false|缺省 = followUp（排队）——pi streamingBehavior
+   * 语义的中立承载（D1 §3.3.5「后续 wave 如需抢占语义再扩展 InteractAction」的兑现，
+   * chat 域投递经 engine.interact 接通时落地；不支持抢占的引擎忽略）。
+   */
+  | { kind: "message"; payload: string; interrupt?: boolean }
   | { kind: "close"; payload?: { force: boolean } }
   | { kind: "cancel" };