@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/dist/{types-DpUO16pj.d.ts → types-C3fE3R9x.d.ts}

@@ -1,3 +1,5 @@
+import { GuiRenderResult } from '@xyz-agent/extension-protocol';
+
 /**
  * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
  * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐。
@@ -49,6 +51,19 @@ interface ResolvedModel {
     thinkingLevel: string | undefined;
 }
 
+/**
+ * 未显式指定 agent 时的兜底名。
+ *
+ * 必须是真实存在、可被 agentRegistry 发现的 agent（用户 agentDir 内置的通用 agent）。
+ * Service 层（resolveIdentity）与 TUI 层（extractAgentName）共用此常量，保证
+ * 「调用时显示的名」与「实际加载的 agent.md」一致。
+ *
+ * [HISTORICAL] 旧实现两处各硬编码：service 用 "default"（虚构名），format 用
+ * "worker"（真实但不是兜底语义，worker agent 已在 2026-08 agent 重构中删除）。
+ * 导致不传 agent 时，block 标题显示 worker，但实际执行兜底逻辑不一致。统一为
+ * general-purpose 后名实相符。
+ */
+declare const DEFAULT_AGENT_NAME = "general-purpose";
 /**
  * 唯一执行状态。所有路径共用。v4 B-1 两态收敛：旧 idle 折入 running、
  * 旧 cancelled 折入 closed（closedReason='cancelled' 区分）。
@@ -86,6 +101,8 @@ type ClosedReason = 'parent-shutdown' | 'parent-fork' | 'parent-new' | 'user-clo
  */
 declare class ResurrectDeniedError extends Error {
 }
+/** ClosedReason 全枚举值（运行时守卫用——防御性解析外部输入时校验成员资格）。 */
+declare const CLOSED_REASONS: readonly ClosedReason[];
 /**
  * 终态三态对外语义（U3 C-outcome 一等披露）。
  *
@@ -279,6 +296,12 @@ interface AgentResult$1 {
     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;
@@ -306,6 +329,14 @@ interface AliveMarker {
     readonly id: string;
     readonly startedAt: number;
 }
+/** git diff patch 结果。 */
+interface PatchResult {
+    readonly patchFile: string;
+    readonly failed: boolean;
+    /** patch 是否实际写入 patchFile。true=diff 非空且写盘成功；false=空 diff 或写失败。
+     *  调用方据此回填 record.patchFile，避免悬空路径（`git apply` 不存在的文件）。 */
+    readonly written: boolean;
+}
 /** fork depth 超限错误。 */
 declare class ForkDepthExceededError extends Error {
     constructor(message: string);
@@ -390,6 +421,14 @@ interface ExecutionRecord {
         journalPath?: string;
         poolKey: string;
     };
+    /**
+     * 同步收集模式标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * 创建时确定不可变；undefined = async（缺省语义，旧记录零迁移）。持久化经
+     * subagent-record entry（record-entry.ts 序列化白名单，entry 唯一写点）。
+     * 消费方：U2 collectCoordinator 路由（sync→批缓冲）、U5 E1 重建投影。
+     * U2 接线点：service.createRecordForMode 从 ExecuteOptions.collect 读入 identity。
+     */
+    readonly collectMode?: "sync";
     status: ExecutionStatus;
     /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。表达「为什么关闭」。
      *  由 tryTransition(record, "closed", reason) 写入；投影层按需派生对外语义。
@@ -401,6 +440,13 @@ interface ExecutionRecord {
      * record 无此字段，投影层按 projectOutcome 兜底（closed-legacy 语义）。
      */
     outcome?: ExecutionOutcome;
+    /**
+     * 离开批的终局标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * 两出口统一落标：① 批闭合 flush 写账成功后；② E9 dispose 逐条转 async 写账后
+     * （均 appendEntry 持久化，U3/U5 写点）。undefined = 未离开批 / 旧记录零迁移。
+     * 消费方：U5 E1 重建扫描只收「collectMode=sync 且无本标记」的成员（防双重通知）。
+     */
+    batchFinalized?: boolean;
     /** 完整执行内容，按 turn 组织。createRecord 初始化为 [空 turn]。 */
     turns: Turn[];
     /** turn 计数（= turns.filter(closed).length，冗余存储供投影直接读）。 */
@@ -569,6 +615,17 @@ interface ExecuteOptions {
      * undefined/false = 一次性模式（默认，行为完全不变）。service.execute 透传到 createRecordForMode。
      */
     conversation?: boolean;
+    /**
+     * 同步收集模式（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * undefined = config collectSync.default（缺省 "async"，新 session 生效）。
+     * schema 层枚举限 "async"|"sync"；运行时宽收 string 与 engine 字段同风格
+     * （非法值 ≠ "sync" 按 async 处理）。
+     * "sync" + conversation:true 组合在 startHandler E4 校验即拒
+     * （immediate throw，不产生半启动 record）。
+     * U2 接线点：service.createRecordForMode 读入 createRecord identity.collectMode
+     * （U1 打通类型与 startHandler 透传，record 落点归 U2）。
+     */
+    collect?: string;
     /**
      * 空闲超时毫秒数（仅 conversation 模式有意义）。覆盖默认 5min idle timeout。
      * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
@@ -650,6 +707,16 @@ interface BgResponse {
      * 值语义由 U2（execution/notify-ledger.ts）兑现。
      */
     notifyContract: "ledger+at-least-once";
+    /**
+     * 同步收集登记回显段（subagent-sync-collect 设计 §3.1.1 交互样例，U1 foundation）。
+     * 仅 resolved 模式为 sync 时附带（async 响应字节零变化，G3）：mode = 生效模式；
+     * pendingSyncCount = 当前未闭合批的 sync 成员总数（含本条；跨轮派发续累不重置，
+     * 与 D2 隐式批一致）。
+     */
+    collect?: {
+        mode: "sync";
+        pendingSyncCount: number;
+    };
 }
 /** list 的内层响应（挂在 SubagentToolResult.listResponse）。 */
 interface ListResponse {
@@ -676,6 +743,55 @@ interface MessageResponse {
 interface CloseResponse {
     closed: true;
 }
+/**
+ * Tool 外层出参（renderResult + LLM content JSON 同源）。
+ * adapter 唯一产出：领域对象（bg/list/cancel/message/close 五选一）+ action/subagentId/sessionFile。
+ *
+ *   - background 启动 → bgResponse（subagentId 有值；sessionFile 窗口期可能 undefined）
+ *   - list → listResponse（最外层 subagentId/sessionFile 为 null，sessionFile 在各 item 内）
+ *   - cancel → cancelResponse（subagentId 有值；sessionFile 无意义，可为 null）
+ *   - message → messageResponse（subagentId 有值；sessionFile 无意义，可为 null）
+ *   - close → closeResponse（subagentId 有值；sessionFile 无意义，可为 null）
+ */
+type SubagentToolResult = {
+    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;
+} | {
+    action: "close";
+    subagentId: string;
+    sessionFile: null;
+    closeResponse: CloseResponse;
+    __gui__?: GuiRenderResult;
+} | {
+    action: "fork-from";
+    subagentId: string;
+    sessionFile: string | null;
+    forkFromResponse: ForkFromResponse;
+    __gui__?: GuiRenderResult;
+};
 /** fork-from 的内层响应：新 subagent id + 作为继承源的旧记录 session 文件。
  *  [v8.5 B] 断联恢复通道——新 subagent 以 --fork 方式继承旧会话历史，源文件只读
  *  不续写（pi fork 建 branched session，copy-on-write）。 */
@@ -696,6 +812,8 @@ 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 同值。 */
@@ -768,6 +886,30 @@ interface SubagentRecord {
         journalPath?: string;
         poolKey: string;
     };
+    /**
+     * 同步收集模式标记（与 ExecutionRecord.collectMode 同源投影/重建，U1 foundation）。
+     * 缺省（存量 record）= async 投影，消费方零迁移。
+     */
+    collectMode?: "sync";
+    /**
+     * 离开批终局标记（与 ExecutionRecord.batchFinalized 同源投影/重建，U1 foundation）。
+     * 缺省 = 未离开批；U5 E1 重建扫描据此排除已离场成员。
+     */
+    batchFinalized?: boolean;
+}
+/**
+ * 同步收集（sync collect）配置节类型（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+ * 权威默认值在 config.ts DEFAULT_COLLECT_SYNC；坏值 sanitize 回默认不炸启动（E5，
+ * 与 maxConcurrent 同判）。类型定义于 types.ts（避免 config → types 反向依赖成环），
+ * config.ts re-export。
+ */
+interface CollectSyncConfig {
+    /** start 未显式传 collect 时的缺省模式。新 session 生效（与 engine 配置时机一致）。 */
+    default: "async" | "sync";
+    /** 批通知单条目结果正文预算（字符）：超出截断并接 session_read 指针行。flush 时热读。 */
+    perItemChars: number;
+    /** 批通知结果正文总量预算（字符）：Σ 超限时统一收紧 effectivePerItem（U4 算法）。flush 时热读。 */
+    totalChars: number;
 }
 /**
  * 全局配置（~/.pi/agent/subagents/config.json）。
@@ -788,6 +930,11 @@ interface SubagentsGlobalConfig {
     engineRouting?: {
         strict: boolean;
     };
+    /**
+     * 同步收集配置节（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+     * 整节缺省 = DEFAULT_COLLECT_SYNC（config.ts）；逐字段 sanitize 回默认（E5）。
+     */
+    collectSync?: CollectSyncConfig;
 }
 /**
  * Record 的只读视图。store.snapshot() 返回。
@@ -844,7 +991,36 @@ type RunStatus = "running" | "done";
 /** 终态原因。done 时必有（WorkflowRun 不变式）。 */
 type DoneReason = "completed" | "failed" | "aborted" | "budget_limited" | "time_limited" | "invalid_args";
 /**
- * 单次 agent 调用的输入选项。
+ * slug 最大长度（D6 合流迁入本文件，原权威定义在已删除的 execution/execute-options-mapper.ts）。
+ * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/ "fix-subagent-wf-tools"（21）
+ * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
+ * 放本文件的原因：约束对象是 AgentCallOpts.description（slug 的源字段，见下方 slug 派生说明），
+ * 与字段同文件；worker-message-pump（live record slug 截断）与壳侧 tool schema maxLength 共享引用。
+ */
+declare const SLUG_MAX_LENGTH = 35;
+/**
+ * 单次 agent 调用的任务声明（D6 任务形状合流后的单一形状）。
+ *
+ * [D6 合流裁决] 本类型 = 原 AgentCallOpts（workflow 调用方声明，18 字段）与原
+ * AgentTaskSpec（engine 中立任务声明，已删除）的合流形态，从模型脚本 agent() API
+ * 到 EnginePort.run 直达 pi 边界一次映射——SAR 链路上的 ExecuteOptions/AgentTaskSpec
+ * 中间态消除（设计 docs/design/subagent-dual-track-convergence.md §3.3 D6 / 终态四）。
+ *
+ * 终态命名按变化轴裁定为 AgentCallOpts，理由：
+ *   - 字段演进的首要驱动轴是「调用方要表达的任务语义」（agent() API 是唯一生产写入方，
+ *     合流字段中 prompt/description/skill/skillPath/schemaEnv/thinkingLevel 等多数派
+ *     已是调用方命名）；
+ *   - 原 AgentTaskSpec 的中立重命名层（task/slug/effort/persona）与调用方命名是
+ *     形式同构、语义同构的假差异（prompt≡task、slug=description 截断、effort≡thinkingLevel、
+ *     persona≡skillPath+appendSystemPrompt 平铺），按「消假差异」原则并入调用方命名；
+ *   - 持久化兼容反向锁定 prompt 形态：jsonl run 快照的 AgentCall.opts 与 worker 消息
+ *     opts 均以 prompt 字段落盘，改名会破坏旧快照重水合。
+ *
+ * 引擎中立字段的并入方式（可选字段，原 AgentTaskSpec 独有字段去向）：
+ *   - graceTurns / conversation / idleTimeoutMs / denyTools / permissionMode：可选并入；
+ *   - persona.agentRef：裁撤（无生产写入方、无消费者——pi 走 agent 字段解析身份）；
+ *   - requires：裁撤（P4 形状预留、无生产写入方；且并入需 import EngineCapabilities
+ *     形成 orchestration↔engine 类型环）。将来能力依赖声明下钻时在本形状上加回。
  *
  * D-12 仅重组执行编排，AgentCallOpts 形状保持兼容。
  */
@@ -880,14 +1056,20 @@ interface AgentCallOpts {
     */
     timeoutMs?: number;
     /**
-    * Turn 上限（turn limiter 用）。
-    *
-    * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
-    * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
-    * session-runner.resolveSpawnWatchdogMs）。mapToExecuteOptions 原样透传到
-    * ExecuteOptions.maxTurns → 引擎 task-spec → runSpawn。
-    */
+     * Turn 上限（turn limiter 用）。
+     *
+     * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
+     * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
+     * session-runner.resolveSpawnWatchdogMs）。pi 边界直出为 ExecuteOptions.maxTurns
+     * → runSpawn（D6 合流后无中间映射层）。
+     */
     maxTurns?: number;
+    /**
+     * Turn limiter 的宽限轮数（原 AgentTaskSpec.graceTurns 并入）：超 maxTurns 后
+     * 允许继续的轮数（等待在途工具收尾）。pi 引擎消费；workflow agent() 无写入方，
+     * chat 域（ExecuteOptions.graceTurns 同名透传）经 host-task-spec 填充。
+     */
+    graceTurns?: number;
     /**
     * Skill name to load (e.g. "code-review"). Resolved to SKILL.md path
     * and injected via --skill flag in the subprocess.
@@ -908,18 +1090,18 @@ interface AgentCallOpts {
     */
     agent?: string;
     /**
-    * System prompt injection CONTENT (not file paths).
-    * Set by agent-opts-resolver: schema structured-output instruction string.
-    * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
-    * mapToExecuteOptions passes this through to ExecuteOptions.appendSystemPrompt
-    * (same name/semantics, transparent passthrough).
-    */
+     * System prompt injection CONTENT (not file paths).
+     * Set by agent-opts-resolver: schema structured-output instruction string.
+     * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
+     * pi 边界直出为 ExecuteOptions.appendSystemPrompt（同名同义透传，D6 合流后无中间映射层）。
+     */
     appendSystemPrompt?: string[];
     /**
-    * Schema JSON for PI_WORKFLOW_SCHEMA env var.
-    * Set by agent-opts-resolver when opts.schema is present; passed as env var
-    * to activate the structured-output tool + hook.
-    */
+     * Schema JSON for PI_WORKFLOW_SCHEMA env var.
+     * Set by agent-opts-resolver when opts.schema is present (值 = stringifySchemaCached
+     * compact，与 schema 派生等值); passed as env var to activate the structured-output
+     * tool + hook. pi 边界直出时 schema 派生优先、本字段兜底（解耦形态通道，生产不可达）。
+     */
     schemaEnv?: string;
     /**
     * Per-call 工作目录（ADR-029 决策 1）。传给 child_process.spawn 的 cwd option。
@@ -938,11 +1120,36 @@ interface AgentCallOpts {
      * agent() → execute-agent-call → SAR 路由层。
      */
     engine?: string;
-    /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
-    worktree?: boolean;
+    /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork.
+     * [D6 合流] 类型扩展为 boolean | WorktreeHandle（原 AgentTaskSpec.worktree 的超集）——
+     * WorktreeHandle 形态仅在 chat 域（复用外部已创建的 worktree）出现，workflow agent()
+     * 恒传 boolean。 */
+    worktree?: boolean | WorktreeHandle;
     /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.
-     * Worker-layer flag only — not forwarded to ExecuteOptions (mapToExecuteOptions drops it). */
+     * Worker-layer flag only — not consumed by any engine (dropped at the pi boundary). */
     returnMeta?: boolean;
+    /**
+     * 可持续对话模式（原 AgentTaskSpec.conversation 并入）：true = record 标记 chatMode，
+     * 轮次完成进 idle 态等待 message 续聊。chat 域（ExecuteOptions.conversation 同名）经
+     * host-task-spec 填充；workflow agent() 无写入方。
+     */
+    conversation?: boolean;
+    /**
+     * 空闲超时毫秒数（原 AgentTaskSpec.idleTimeoutMs 并入，仅 conversation 模式有意义）。
+     * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms；显式 0/负 = 禁用
+     * idle GC。chat 域经 host-task-spec 填充。
+     */
+    idleTimeoutMs?: number;
+    /**
+     * 工具 denylist（原 AgentTaskSpec.denyTools 并入，中立新增面）：各引擎做语法映射
+     * （zcode buildZcodeArgv 消费；pi 链路暂无对应面）。无 workflow 写入方，预留形状。
+     */
+    denyTools?: string[];
+    /**
+     * 中立权限模式（原 AgentTaskSpec.permissionMode 并入，预留形状）：映射按各引擎
+     * capabilities.permissionMode。无生产写入方/消费者。
+     */
+    permissionMode?: string;
 }
 /**
  * 单次 agent 调用的资源用量（FR-7 跨 turn 累积）。
@@ -965,6 +1172,23 @@ interface ToolCallEntry {
     /** Args preview string. */
     input: string;
 }
+/**
+ * 失败分诊结构化标签（D5-③，r1 MF4 钉正语义）。
+ *
+ * - stale_context：pi session context 被 compact/cancel/替换——重试无意义（同 call
+ *   再次失败），不重试。
+ * - schema_deterministic：确定性 schema 失败（SO tool 从未调用 / gate 终止 /
+ *   不可满足 schema）——同 schema 重试必同结果，不重试。
+ * - unknown：其余一切失败（瞬态 provider 错误、spawn 失败等）——**默认可重试**。
+ *
+ * **语义守恒（最高优先约束）**：unknown（含字段缺省）= 可重试——保持收敛前的
+ * 默认重试语义；仅 stale_context 与 schema_deterministic 两态维持不重试特判。
+ * 词表归属（产出侧单点识别）：stale_context / schema_deterministic 的识别词表
+ * （stale 词表与确定性 schema 失败标记前缀）保留在产出侧
+ * execution/engine/engines/pi/output-collector.ts 包内——词表漂移的失效模式是
+ * failureKind=unknown → 保守重试（安全默认），不再是静默漏诊。
+ */
+type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
 /**
  * 单次 agent 调用的结果（统一形态）。
  *
@@ -975,6 +1199,16 @@ interface AgentResult {
     /** Raw text output from the agent. */
     content: string;
     /**
+    * [D5-③] 失败分诊结构化标签（AgentFailureKind）。产出侧唯一识别点 =
+    * execution/engine/engines/pi/output-collector.ts（collectResult 对最终 error
+    * 分类后写入，经 agent-result-mapper / AgentOutcome 透传到本形态）；消费侧
+    * execute-agent-call 读本字段分诊，不再扫 error 文案子串。
+    *
+    * 仅在 error !== undefined 时有意义（成功时缺省）；缺省视为 unknown = 可重试
+    * （语义守恒，见 AgentFailureKind）。
+    */
+    failureKind?: AgentFailureKind;
+    /**
     * Parsed structured output.
     * Present when `schema` was provided and the output was valid JSON.
     * Source: tool_execution_end.result.details（validated data object）。
@@ -1069,95 +1303,6 @@ interface WorkerLogEntry {
     message: string;
 }
 
-/** 人设（persona）注入规格：原 skillPath + appendSystemPrompt 收拢进一个语义单元（D2）。 */
-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）。
- */
-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>;
-}
 /**
  * 一次引擎执行的终态。锚定 orchestration/models/types.ts 的 AgentResult（workflow
  * 引擎消费的那份——content/parsedOutput/usage/error）并追加引擎层字段；见文件头消歧说明。
@@ -1165,6 +1310,13 @@ interface AgentTaskSpec {
 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 路径公共层不做二次校验、不改写其结果）。
@@ -1289,6 +1441,15 @@ 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;
 }
 /** 引擎探针报告（probe() 返回）。探针在引擎 factory 初始化与版本变化检测时触发（P4 接线）。 */
 interface ProbeReport {
@@ -1311,9 +1472,16 @@ interface ProbeReport {
  * interact 的 action（D1 交互控制面）。pi 首期原生实现（现有 chatMode 行为直通）；
  * 声明 conversation unsupported 的引擎调用前拒绝（engine_capability_unsupported）。
  */
-type InteractAction = {
+type InteractAction = 
+/**
+ * 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?: {
@@ -1335,4 +1503,4 @@ type InteractResult = {
     message: string;
 };
 
-export { type AgentTaskSpec as A, type BgResponse as B, type ClosedReason as C, type DoneReason as D, type EngineCapabilities as E, type ForkFromResponse as F, type SubagentListItem as G, DirtyWorktreeError as H, type InteractAction as I, ForkDepthExceededError as J, type PersonaSpec as K, type ListResponse as L, type ModelInfo as M, type ReplayedTurn as N, ResurrectDeniedError as O, type ProbeReport as P, type RunStatus as R, type SessionView as S, type TracePatch as T, type WorkerLogEntry as W, type AgentEvent as a, type EngineHandleData as b, type EngineHandle as c, type AgentOutcome as d, type InteractResult as e, type AgentUsage as f, type AgentCallOpts as g, type AgentResult as h, type ExecutionTraceNode as i, type SubagentsGlobalConfig as j, type ModelRegistryLike as k, type AgentConfig as l, type ResolvedModel as m, type ExecutionRecord as n, type RecordSnapshot as o, type SubagentRecord as p, type ExecuteOptions as q, type ExecutionHandle as r, type ExecutionStatus as s, type ExecutionMode as t, type AgentEventLogEntry as u, type DisplayItem as v, type CancelResponse as w, type CloseResponse as x, type MessageResponse as y, type ExternalState as z };
+export { type SubagentToolResult as $, type AgentCallOpts as A, type DisplayItem as B, type ClosedReason as C, type DoneReason as D, type EngineCapabilities as E, type CancelResponse as F, type CloseResponse as G, type ForkFromResponse as H, type InteractAction as I, type MessageResponse as J, type BgResponse as K, type ListResponse as L, type ModelInfo as M, type ExternalState as N, type SubagentListItem as O, type ProbeReport as P, CLOSED_REASONS as Q, type RecordSnapshot as R, type SessionView as S, type ToolCall as T, DEFAULT_AGENT_NAME as U, DirtyWorktreeError as V, type WorktreeHandle as W, ForkDepthExceededError as X, type ReplayedTurn as Y, ResurrectDeniedError as Z, SLUG_MAX_LENGTH as _, type AgentEvent as a, type ToolCallEntry as a0, type EngineHandleData as b, type EngineHandle as c, type AgentOutcome as d, type InteractResult as e, type ExecutionRecord as f, type SubagentRecord as g, type ExecuteOptions as h, type AgentResult as i, type AgentConfig as j, type ResolvedModel as k, type AgentResult$1 as l, type ExecutionOutcome as m, type AgentEventLogEntry as n, type ExecutionStatus as o, type ProjectedOutcome as p, type SubagentsGlobalConfig as q, type ModelRegistryLike as r, type ExecutionHandle as s, type ExecutionMode as t, type PatchResult as u, type AgentUsage as v, type ExecutionTraceNode as w, type TracePatch as x, type RunStatus as y, type WorkerLogEntry as z };