@zhushanwen/subagent-core 0.6.0 → 0.7.1

package/dist/{types-C3fE3R9x.d.cts → engine-discovery-scan-ocpM8FmI.d.cts}

@@ -1,5 +1,317 @@
+import { WorktreeHandle, AgentFailureKind, AgentOutcomeUsage, ToolCallEntry, Turn, ToolCall, AgentUsageTotal, EngineHandleData, EngineCapabilities, ProbeReport, AgentEvent, ResumeAnchor, HostRoundLifecycleParams, AgentOutcome, InteractAction, InteractResult, SessionView, ModelCatalogEntry } from '@zhushanwen/subagent-engine-sdk';
+import { ChildProcess } from 'node:child_process';
 import { GuiRenderResult } from '@xyz-agent/extension-protocol';
 
+/**
+ * Workflow Extension — Engine 共享类型
+ *
+ * Engine 层全局基础类型。零 infra 依赖——不 import 任何 infra 文件，
+ * 可独立编译测试（D-12 三层架构，AC-1）。
+ *
+ * 核心内容：
+ * - 状态机：RunStatus = "running" | "done"（2 态，一次性生命周期，FR-3）
+ * + DoneReason（completed/failed/aborted/budget_limited/time_limited）
+ * - AgentCallOpts / AgentResult（单次 agent 调用的输入/输出，宿主面 SSOT 留守本地）
+ * + AgentUsage / ToolCallEntry / AgentFailureKind（自 SDK re-export，S4 簇 3 收编）
+ * - ExecutionTraceNode / TracePatch / ToolCallEntry / WorkerLogEntry（trace 数据）
+ *
+ * 层归属：Engine（数据结构 + 不变式守卫）。
+ */
+
+/**
+ * 状态机：2 态（D-12 / FR-3，一次性生命周期——run 不可挂起）。
+ *
+ * running → done
+ *
+ * `done` 是唯一终态，具体原因由 DoneReason 区分。
+ */
+type RunStatus = "running" | "done";
+/** 终态原因。done 时必有（WorkflowRun 不变式）。 */
+type DoneReason = "completed" | "failed" | "aborted" | "budget_limited" | "time_limited" | "invalid_args";
+/**
+ * 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 形状保持兼容。
+ */
+interface AgentCallOpts {
+    /** The task prompt to send to the agent. */
+    prompt: string;
+    /**
+    * Optional JSON schema for structured output.
+    * When provided, the schema is passed via PI_WORKFLOW_SCHEMA env to the subprocess,
+    * which activates the structured-output tool + turn_end hook.
+    * The tool's execute validates model output against the schema.
+    * On success, `parsedOutput` on the result is set to `tool_execution_end.result.details`
+    * (the validated, parsed data object — not the raw tool call args).
+    */
+    schema?: Record<string, unknown>;
+    /**
+    * Model to use (e.g. "router-openai/glm-5.1").
+    * When omitted, pi's default model is used.
+    */
+    model?: string;
+    /**
+    * Thinking level override (e.g. "high", "medium", "low").
+    * M2: Added to align with subagent path's ExecuteOptions.thinkingLevel.
+    * When omitted, agent .md frontmatter thinkingLevel is used (via resolveIdentity/getAgentConfig).
+    */
+    thinkingLevel?: string;
+    /** Scene name passed through to the worker for model-selection hints. */
+    scene?: string;
+    /**
+    * Wall-clock timeout in milliseconds. When > 0, aborts the subprocess
+    * if it runs longer than this, regardless of external signal.
+    * Per-call，归 AgentCall 实体（G-027）。
+    */
+    timeoutMs?: number;
+    /**
+     * 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.
+    */
+    skill?: string;
+    /**
+    * Resolved absolute path to the skill directory or SKILL.md file.
+    * Set by agent-opts-resolver when opts.skill is present.
+    */
+    skillPath?: string;
+    /** Human-readable description for logging and debugging. */
+    description?: string;
+    /**
+    * Agent ref (absolute .md path). Resolved by resolveIdentity via getAgentConfig,
+    * which injects the agent's systemPrompt/model/tools/thinkingLevel. Not handled by
+    * resolveAgentOpts (single-responsibility: agent ref ownership belongs to resolveIdentity,
+    * M2 fix — previously overlapped causing double-injection + model-tier confusion).
+    */
+    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).
+     * pi 边界直出为 ExecuteOptions.appendSystemPrompt（同名同义透传，D6 合流后无中间映射层）。
+     */
+    appendSystemPrompt?: string[];
+    /**
+     * 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。
+    *
+    * 用于 worktree 隔离：传入 worktree 绝对路径，spawn 的 pi 子进程绑定到该目录，
+    * 其内部的 createAgentSession/ResourceLoader/bash 工具都在该目录运行。
+    * undefined 时 spawn 继承 workflow 进程的 cwd（向后兼容）。
+    */
+    cwd?: string;
+    /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
+    fork?: boolean;
+    /**
+     * fork-from 显式分叉源 session 文件（fork-from 断联恢复通道的唯一 lossless 载体）。
+     * 来源 = ExecuteOptions.forkFromSessionFile（host-task-spec 映射时的唯一改名点——
+     * 本形状起与 SDK 协议字段、引擎侧 SpawnRunParams.forkSource 三层同名，降低跨层
+     * 双名漂移面）。区别于 fork:true（主 session 作分叉源）：本字段点名任意已有
+     * session 文件。chat 域唯一写入方 = fork-from action。
+     */
+    forkSource?: string;
+    /**
+     * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
+     * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
+     * engine——环境差异由 frontmatter/全局默认承载）；透传链 worker-script-builder
+     * agent() → execute-agent-call → SAR 路由层。
+     */
+    engine?: string;
+    /** 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 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 调用的结果（统一形态）。
+ *
+ * Engine 直接消费 SubprocessAgentRunner 返回值；callCache replay 时 worker
+ * 取 parsedOutput ?? content（见 worker-script-builder.ts 消息处理）。
+ */
+interface AgentResult$1 {
+    /** Raw text output from the agent. */
+    content: string;
+    /**
+    * [D5-③] 失败分诊结构化标签（AgentFailureKind）。产出侧唯一识别点 =
+    * execution/engine/inproc 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）。
+    */
+    parsedOutput?: unknown;
+    /** Token and cost usage accumulated across all assistant turns. */
+    usage?: AgentOutcomeUsage;
+    /** Wall-clock duration in milliseconds. */
+    durationMs?: number;
+    /** True when the pi process exited with code 0. */
+    error?: string;
+    /**
+    * Pi session ID for the subagent process (uuidv7).
+    * Present when pi emits a session header (default in --mode json).
+    * Can be used to locate the session JSONL file for post-run inspection (G-017)。
+    */
+    sessionId?: string;
+    /**
+    * Session JSONL 绝对路径（不含目录的文件名在 subagents 侧 AgentResult.sessionFile）。
+    * 由 mapToWorkflowAgentResult 从 subagents AgentResult 透传——让 workflow 编排层
+    * 继承 subagent 执行管道产出的 session 文件路径，overlay/GUI 可直接定位。
+    * 窗口期内可能 undefined（session 尚未创建成功）。
+    */
+    sessionFile?: string;
+    /**
+    * Absolute path of the git worktree used for filesystem isolation (set when
+    * worktree isolation is active). Injected by executeAndAwait from record.worktreeHandle.path.
+    *
+    * ⚠️ Diagnostic only, may not exist: executeAndAwait's finalizeRecord cleans up the
+    * worktree (git worktree remove --force) before returning, so by the time this field
+    * reaches the caller the directory has typically been deleted. Use it only for log/trace
+    * correlation (e.g. attributing a session jsonl to its worktree origin) — never as a cwd
+    * for a subsequent agent or filesystem operation (would ENOENT).
+    */
+    worktreePath?: string;
+    /** All tool calls collected from JSONL stream (FR-7). */
+    toolCalls?: ToolCallEntry[];
+}
+/**
+ * 执行追踪节点（事件流 D-10 单一来源）。
+ */
+interface ExecutionTraceNode {
+    stepIndex: number;
+    agent: string;
+    task: string;
+    model: string;
+    status: "pending" | "running" | "completed" | "failed";
+    /** Phase name for TUI grouping. Set from explicit opts.phase or global _currentPhase. */
+    phase?: string;
+    startedAt?: string;
+    completedAt?: string;
+    result?: AgentResult$1;
+    error?: string;
+    /**
+    * Pi session ID (uuidv7) for the subagent process.
+    * Used to locate the session JSONL for post-run inspection.
+    */
+    sessionId?: string;
+    /**
+    * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
+    * 持久化到快照（serializeRun），跨 session 重水合后保留。
+    */
+    sessionFile?: string;
+    /**
+    * Live 执行进度对象（running 时存在，done 时由 dispatchAgentCall 清除）。
+    *
+    * 挂在 node 上（D-10 单源延伸：AgentCall.traceNode 与 Trace.nodes 共享同一引用）。
+    * TUI 通过 trace.toArray() 读 node.live，派生 getEventLog/getCurrentActivity 实时展示。
+    * 不持久化（序列化时 strip；重跑时由 dispatchAgentCall 重建）。
+    */
+    live?: ExecutionRecord;
+}
+/**
+ * Trace.update 用的 patch（字段全可选）。
+ *
+ * 不变式：只改单个 node 的 status/result/error/completedAt/sessionId。
+ * callId 不存在时 update 为 no-op（D-10）。
+ */
+interface TracePatch {
+    status?: "pending" | "running" | "completed" | "failed";
+    result?: AgentResult$1;
+    error?: string;
+    completedAt?: string;
+    sessionId?: string;
+    sessionFile?: string;
+}
+/**
+ * Worker console.* 捕获条目（run 级诊断，仅展示在 TUI widget，不泄漏到 input area）。
+ */
+interface WorkerLogEntry {
+    level: "log" | "warn" | "error" | "info";
+    message: string;
+}
+
 /**
  * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
  * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐。
@@ -128,75 +440,17 @@ type ProjectedOutcome = ExecutionOutcome | "closed-legacy";
  *   running → active / closed → ended（closed 统一终态，含 cancelled）。
  * mapExternalState 不消费 ClosedReason——closed 恒映射 ended。
  *
- * waiting / error 是历史多态映射（idle→waiting / failed+crashed→error）的遗留声明：
- * 对外四态联合契约不变，但当前状态机不产生这两个值。
- *
- * 原始 ExecutionStatus 进 list item 的 status 字段供调试；state 是对外主字段。
- * 映射实现见 subagent-actions.ts mapExternalState——未来内部加态必须扩展该处，
- * 漏加会在 default 分支编译报错，不影响对外契约。
- */
-type ExternalState = "active" | "waiting" | "ended" | "error";
-/** 执行模式。background = 调用方立即拿 handle 返回，子 agent 在 detached promise 里跑。 */
-type ExecutionMode = "background";
-/**
- * Pi session.subscribe 上报的事件。Runtime 把它喂给 updateFromEvent。
- *
- * 设计：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 映射的翻译成本最低。
- */
-type AgentEvent = {
-    type: "tool_start";
-    toolName: string;
-    args?: unknown;
-} | {
-    type: "tool_end";
-    toolName: string;
-    args?: unknown;
-    result?: ToolCallResult;
-    isError?: boolean;
-} | {
-    type: "text_delta";
-    delta: string;
-} | {
-    type: "thinking_delta";
-    delta: string;
-} | {
-    type: "turn_end";
-    summary?: string;
-} | {
-    type: "message_end";
-    usage?: AgentUsage$1;
-    error?: string;
-} | {
-    type: "compaction";
-} | {
-    type: "error";
-    message: string;
-};
-/** token 用量（message_end 时由 Core 累加进 record.totalTokens）。 */
-interface AgentUsage$1 {
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    /** 本 message 的成本（USD，来自 SDK usage.cost.total）。可选——无成本数据时缺省。 */
-    cost?: number;
-}
-interface AgentUsageTotal extends AgentUsage$1 {
-    /** 上述四项之和。投影时不再手工求和。 */
-    total: number;
-    /** 累计成本（USD，来自 SdkEvent.message.usage.cost.total 求和）。无成本数据时为 0。 */
-    cost: number;
-}
+ * waiting / error 是历史多态映射（idle→waiting / failed+crashed→error）的遗留声明：
+ * 对外四态联合契约不变，但当前状态机不产生这两个值。
+ *
+ * 原始 ExecutionStatus 进 list item 的 status 字段供调试；state 是对外主字段。
+ * 映射实现见 subagent-actions.ts mapExternalState——未来内部加态必须扩展该处，
+ * 漏加会在 default 分支编译报错，不影响对外契约。
+ */
+type ExternalState = "active" | "waiting" | "ended" | "error";
+/** 执行模式。background = 调用方立即拿 handle 返回，子 agent 在 detached promise 里跑。 */
+type ExecutionMode = "background";
+
 /**
  * eventLog 条目（getEventLog 派生产出的元素）。所有字段 readonly。
  *
@@ -230,67 +484,8 @@ interface DisplayItem {
     /** text：assistant 正文（compact 时取首行/截断）。 */
     readonly text?: string;
 }
-/** tool 调用结果（tool_execution_end 时累积，含 structured-output 的 details）。 */
-interface ToolCallResult {
-    content?: unknown[];
-    details?: unknown;
-}
-/**
- * tool 调用（导出的纯净数据形状，不含内部状态）。
- *
- *   tool_start 到达但 tool_end 未到时，调用为进行中；一旦 tool_end 到达，
- *   result/isError 填充完成。对外投影（AgentResult.toolCalls / getAllToolCalls）
- *   一律返回此类型——**不泄漏 running/done/failed 内部状态机**。
- *
- * 进行中状态由 execution-record 内部的 `InternalToolCall`（= ToolCall + _status）承载，
- * 只存在于 record.turns[].toolCalls，跨边界导出时由 getAllToolCalls strip _status。
- */
-interface ToolCall {
-    toolName: string;
-    args?: unknown;
-    result?: ToolCallResult;
-    isError?: boolean;
-}
-/**
- * 内部 ToolCall：在 ToolCall 基础上追加 _status 进行中状态标记与 startedTs 时间戳。
- *
- *   running = tool_start 已收到但 tool_end 未到；
- *   done/failed = tool_end 已到。
- *
- * 仅存在于 ExecutionRecord.turns[].toolCalls（Core 内部可变状态）。
- * 跨边界导出（getAllToolCalls → AgentResult.toolCalls / 持久化）由 getAllToolCalls
- * 映射回 ToolCall（丢弃 _status / startedTs），保证导出形状清洁。
- */
-interface InternalToolCall extends ToolCall {
-    _status: "running" | "done" | "failed";
-    /** tool_start 到达时的墙钟时间戳（Date.now()，ms）。getEventLog 派生 tool 条目 ts 用。 */
-    startedTs: number;
-}
-/**
- * 一个 turn 的完整内容（ExecutionRecord.turns[] 的元素）。
- *
- * 收口设计：text/thinking 流式累积**完整内容**（非 100 字切片），
- * toolCalls 存完整 ToolCall（含 result + _status 内部状态）。turn_end 到达后 closed=true，
- * 下次 text/thinking/tool 时开新 turn。
- *
- * eventLog / currentActivity / result 均从 turns[] 派生，不再独立存储。
- */
-interface Turn {
-    /** 本 turn assistant 正文（text_delta 流式累积，完整）。 */
-    text: string;
-    /** 本 turn 推理（thinking_delta 流式累积，完整）。 */
-    thinking: string;
-    /** 本 turn 工具调用（InternalToolCall：含完整 result + _status 进行中标记）。 */
-    toolCalls: InternalToolCall[];
-    /** 本 turn message_end 的 token 增量（聚合得 totalUsage）。 */
-    usageDelta?: AgentUsage$1;
-    /** turn_end 是否已到达。false=正在进行；true=已闭合，下次内容开新 turn。 */
-    closed: boolean;
-    /** turn_end 到达时的墙钟时间戳（Date.now()，ms）。getEventLog 派生 turn_end 条目 ts 用。 */
-    closedTs?: number;
-}
 /** 一次 session 执行的完整结果。collectResult 产出，写入 Record.outcome。 */
-interface AgentResult$1 {
+interface AgentResult {
     text: string;
     turns: number;
     durationMs: number;
@@ -310,19 +505,7 @@ interface AgentResult$1 {
     /** schema 模式下，structured-output tool 的 result.details（已通过 schema 校验）。 */
     parsedOutput?: unknown;
 }
-/**
- * worktree handle 值对象。仅 worktree:true 时持有——worktree 是独立维度，
- * 需显式开启，fork alone 不创建 worktree。
- * Object.freeze 守卫保证不可变。
- */
-interface WorktreeHandle {
-    /** checkout 目录（子 agent 工作目录，tmpdir 下）。 */
-    readonly path: string;
-    readonly branch: string;
-    readonly baseCommit: string;
-    /** 主仓库根目录（cleanup/scan 需要，不再靠路径反推）。 */
-    readonly mainCwd: string;
-}
+
 /** alive marker：子进程存活标记，用于心跳检测和 crash 推断。 */
 interface AliveMarker {
     readonly pid: number;
@@ -501,7 +684,7 @@ interface ExecutionRecord {
     result: string | undefined;
     error: string | undefined;
     /** 完整 AgentResult（含 usage/toolCalls，完成时填）。 */
-    agentResult: AgentResult$1 | undefined;
+    agentResult: AgentResult | undefined;
     /** session jsonl 文件名。session 创建成功后由 session-runner.run() 回填（窗口期内 undefined）。 */
     sessionFile?: string;
     /**
@@ -917,590 +1100,509 @@ interface CollectSyncConfig {
  * 模型解析已退化为「主 agent model 优先，仅 override 时查 registry」——
  * 不再有 category/fallback/yolo 字段。config.json 只保留 maxConcurrent
  * （pool 大小）。旧 config.json 中的 categories/fallback 等字段读取时忽略。
- */
-interface SubagentsGlobalConfig {
-    version: number;
-    maxConcurrent: number;
-    /**
-     * 全局默认执行引擎（D9 三层优先级的最底层：调用参数 > agent frontmatter > 本值）。
-     * 缺省 'pi'（P4 路由层 DEFAULT_ENGINE_ID）。加载期只做类型校验，注册表校验归路由层。
-     */
-    defaultEngine?: string;
-    /** 引擎路由策略（D9①）：strict=true 时一切 probe 失败直接报错（不 fallback）。 */
-    engineRouting?: {
-        strict: boolean;
-    };
-    /**
-     * 同步收集配置节（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
-     * 整节缺省 = DEFAULT_COLLECT_SYNC（config.ts）；逐字段 sanitize 回默认（E5）。
-     */
-    collectSync?: CollectSyncConfig;
-}
-/**
- * Record 的只读视图。store.snapshot() 返回。
- * TUI 拿到此类型，保证不会回写 Core 状态。
- *
- * 不含 eventLog——snapshot 的消费点（cancel 判 mode/status、hasRunning 判 mode、
- * toNotifyRecord 取 result/error）均不读 eventLog。需要 eventLog 的场景用 project()
- * 投影的 SubagentToolDetails。需要完整内容用 record.turns[]（Core 内部）。
- */
-interface RecordSnapshot {
-    readonly id: string;
-    readonly agent: string;
-    readonly model: string;
-    readonly thinkingLevel: string | undefined;
-    readonly mode: ExecutionMode;
-    readonly task: string;
-    /** 短标签（≤35 字符）。来自 record.slug。 */
-    readonly slug: string;
-    readonly status: ExecutionStatus;
-    /** 对话模式标志（与 ExecutionRecord.chatMode 同源）。cancel 别名判定用。 */
-    readonly chatMode?: boolean;
-    readonly turns: number;
-    readonly totalTokens: number;
-    readonly startedAt: number;
-    readonly endedAt: number | undefined;
-    readonly result: string | undefined;
-    readonly error: string | undefined;
-    readonly sessionFile: string | undefined;
-}
-
-/**
- * Workflow Extension — Engine 共享类型
- *
- * Engine 层全局基础类型。零 infra 依赖——不 import 任何 infra 文件，
- * 可独立编译测试（D-12 三层架构，AC-1）。
- *
- * 核心内容：
- * - 状态机：RunStatus = "running" | "done"（2 态，一次性生命周期，FR-3）
- * + DoneReason（completed/failed/aborted/budget_limited/time_limited）
- * - AgentCallOpts / AgentResult / AgentUsage（单次 agent 调用的输入/输出）
- * - ExecutionTraceNode / TracePatch / ToolCallEntry / WorkerLogEntry（trace 数据）
- *
- * 层归属：Engine（数据结构 + 不变式守卫）。
- */
-
-/**
- * 状态机：2 态（D-12 / FR-3，一次性生命周期——run 不可挂起）。
- *
- * running → done
- *
- * `done` 是唯一终态，具体原因由 DoneReason 区分。
- */
-type RunStatus = "running" | "done";
-/** 终态原因。done 时必有（WorkflowRun 不变式）。 */
-type DoneReason = "completed" | "failed" | "aborted" | "budget_limited" | "time_limited" | "invalid_args";
-/**
- * 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 形状保持兼容。
- */
-interface AgentCallOpts {
-    /** The task prompt to send to the agent. */
-    prompt: string;
-    /**
-    * Optional JSON schema for structured output.
-    * When provided, the schema is passed via PI_WORKFLOW_SCHEMA env to the subprocess,
-    * which activates the structured-output tool + turn_end hook.
-    * The tool's execute validates model output against the schema.
-    * On success, `parsedOutput` on the result is set to `tool_execution_end.result.details`
-    * (the validated, parsed data object — not the raw tool call args).
-    */
-    schema?: Record<string, unknown>;
-    /**
-    * Model to use (e.g. "router-openai/glm-5.1").
-    * When omitted, pi's default model is used.
-    */
-    model?: string;
-    /**
-    * Thinking level override (e.g. "high", "medium", "low").
-    * M2: Added to align with subagent path's ExecuteOptions.thinkingLevel.
-    * When omitted, agent .md frontmatter thinkingLevel is used (via resolveIdentity/getAgentConfig).
-    */
-    thinkingLevel?: string;
-    /** Scene name passed through to the worker for model-selection hints. */
-    scene?: string;
-    /**
-    * Wall-clock timeout in milliseconds. When > 0, aborts the subprocess
-    * if it runs longer than this, regardless of external signal.
-    * Per-call，归 AgentCall 实体（G-027）。
-    */
-    timeoutMs?: number;
-    /**
-     * 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.
-    */
-    skill?: string;
-    /**
-    * Resolved absolute path to the skill directory or SKILL.md file.
-    * Set by agent-opts-resolver when opts.skill is present.
-    */
-    skillPath?: string;
-    /** Human-readable description for logging and debugging. */
-    description?: string;
-    /**
-    * Agent ref (absolute .md path). Resolved by resolveIdentity via getAgentConfig,
-    * which injects the agent's systemPrompt/model/tools/thinkingLevel. Not handled by
-    * resolveAgentOpts (single-responsibility: agent ref ownership belongs to resolveIdentity,
-    * M2 fix — previously overlapped causing double-injection + model-tier confusion).
-    */
-    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).
-     * pi 边界直出为 ExecuteOptions.appendSystemPrompt（同名同义透传，D6 合流后无中间映射层）。
-     */
-    appendSystemPrompt?: string[];
-    /**
-     * 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。
-    *
-    * 用于 worktree 隔离：传入 worktree 绝对路径，spawn 的 pi 子进程绑定到该目录，
-    * 其内部的 createAgentSession/ResourceLoader/bash 工具都在该目录运行。
-    * undefined 时 spawn 继承 workflow 进程的 cwd（向后兼容）。
-    */
-    cwd?: string;
-    /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
-    fork?: boolean;
-    /**
-     * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
-     * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
-     * engine——环境差异由 frontmatter/全局默认承载）；透传链 worker-script-builder
-     * agent() → execute-agent-call → SAR 路由层。
-     */
-    engine?: string;
-    /** 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 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;
+ */
+interface SubagentsGlobalConfig {
+    version: number;
+    maxConcurrent: number;
     /**
-     * 工具 denylist（原 AgentTaskSpec.denyTools 并入，中立新增面）：各引擎做语法映射
-     * （zcode buildZcodeArgv 消费；pi 链路暂无对应面）。无 workflow 写入方，预留形状。
+     * 全局默认执行引擎（D9 三层优先级的最底层：调用参数 > agent frontmatter > 本值）。
+     * 缺省 'pi'（P4 路由层 DEFAULT_ENGINE_ID）。加载期只做类型校验，注册表校验归路由层。
      */
-    denyTools?: string[];
+    defaultEngine?: string;
+    /** 引擎路由策略（D9①）：strict=true 时一切 probe 失败直接报错（不 fallback）。 */
+    engineRouting?: {
+        strict: boolean;
+    };
     /**
-     * 中立权限模式（原 AgentTaskSpec.permissionMode 并入，预留形状）：映射按各引擎
-     * capabilities.permissionMode。无生产写入方/消费者。
+     * 同步收集配置节（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+     * 整节缺省 = DEFAULT_COLLECT_SYNC（config.ts）；逐字段 sanitize 回默认（E5）。
      */
-    permissionMode?: string;
+    collectSync?: CollectSyncConfig;
 }
 /**
- * 单次 agent 调用的资源用量（FR-7 跨 turn 累积）。
+ * Record 的只读视图。store.snapshot() 返回。
+ * TUI 拿到此类型，保证不会回写 Core 状态。
+ *
+ * 不含 eventLog——snapshot 的消费点（cancel 判 mode/status、hasRunning 判 mode、
+ * toNotifyRecord 取 result/error）均不读 eventLog。需要 eventLog 的场景用 project()
+ * 投影的 SubagentToolDetails。需要完整内容用 record.turns[]（Core 内部）。
  */
-interface AgentUsage {
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    cost: number;
-    contextTokens: number;
-    turns: number;
+interface RecordSnapshot {
+    readonly id: string;
+    readonly agent: string;
+    readonly model: string;
+    readonly thinkingLevel: string | undefined;
+    readonly mode: ExecutionMode;
+    readonly task: string;
+    /** 短标签（≤35 字符）。来自 record.slug。 */
+    readonly slug: string;
+    readonly status: ExecutionStatus;
+    /** 对话模式标志（与 ExecutionRecord.chatMode 同源）。cancel 别名判定用。 */
+    readonly chatMode?: boolean;
+    readonly turns: number;
+    readonly totalTokens: number;
+    readonly startedAt: number;
+    readonly endedAt: number | undefined;
+    readonly result: string | undefined;
+    readonly error: string | undefined;
+    readonly sessionFile: string | undefined;
 }
+
 /**
- * 单次 tool 调用记录（FR-7 从 agent JSONL 流采）。
+ * 引擎会话句柄（run 返回、interact/read 入参）。
+ *
+ * 契约三条（D1）：不透明（上层不解构——唯一例外是 record 持久化层序列化 data 字段与
+ * read 降级链）、可持久化（data 是纯 JSON，主会话 reload 后 read/interact 仍可用）、
+ * 自描述（data 含 engineId + 引擎 session 定位符 + pool key + adapter 版本）。
+ *
+ * 对进程已死的 handle 调 interact 必须返回 engine_session_not_resumable（指向 cold
+ * resume 路径），而非笼统失败——由各引擎 interact 实现保证。
  */
-interface ToolCallEntry {
-    /** Tool name. */
-    name: string;
-    /** Args preview string. */
-    input: string;
+interface EngineHandle {
+    /** 持久化数据。上层不得解构其内部字段（见契约三条）。 */
+    readonly data: EngineHandleData;
 }
+
 /**
- * 失败分诊结构化标签（D5-③，r1 MF4 钉正语义）。
+ * subagent text_delta streaming sink。
  *
- * - stale_context：pi session context 被 compact/cancel/替换——重试无意义（同 call
- *   再次失败），不重试。
- * - schema_deterministic：确定性 schema 失败（SO tool 从未调用 / gate 终止 /
- *   不可满足 schema）——同 schema 重试必同结果，不重试。
- * - unknown：其余一切失败（瞬态 provider 错误、spawn 失败等）——**默认可重试**。
+ * background subagent 执行期间，session-runner 的 agentEvent 出口把每个 text_delta
+ * 传到 SubagentStream.onDelta。本模块做 100ms 时间窗合并后，通过 StreamSink.setWidget
+ * 转发到 RPC stdout（经 ctx.ui.setWidget → extension_ui_request 通道）。
  *
- * **语义守恒（最高优先约束）**：unknown（含字段缺省）= 可重试——保持收敛前的
- * 默认重试语义；仅 stale_context 与 schema_deterministic 两态维持不重试特判。
- * 词表归属（产出侧单点识别）：stale_context / schema_deterministic 的识别词表
- * （stale 词表与确定性 schema 失败标记前缀）保留在产出侧
- * execution/engine/engines/pi/output-collector.ts 包内——词表漂移的失效模式是
- * failureKind=unknown → 保守重试（安全默认），不再是静默漏诊。
+ * SubagentStream 是一个生命周期对象——内聚 buffer/timer 状态 + onDelta/dispose 方法。
+ * 调用方（subagent-service）创建后只需在 text_delta 时调 onDelta、终态时调 dispose，
+ * 不需要拆散 push/clear 两个函数跨层透传。
+ *
+ * 设计要点：
+ * - leading edge：第一个 delta 立即 flush（前端尽快看到开始）
+ * - trailing edge：后续 delta 追加 buffer，timer 到期后 flush
+ * - 每次 flush 把 buffer 的累积文本 split("\n") 截尾 MAX_WIDGET_LINES 行传给 setWidget
+ * - dispose 清除 widget + 清 timer
  */
-type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
+
+/** UI streaming sink 的最小接口（ctx.ui.setWidget 的 duck-typed 子集）。
+ *
+ * 当前只有一个 adapter（index.ts session_start 包装 ctx.ui.setWidget）。
+ * 保留接口而非裸函数类型，因为 StreamSink 的语义是「UI sink 契约」——
+ * 测试 mock 和未来可能的第二 sink（如写文件）都走此契约。 */
+interface StreamSink {
+    setWidget(key: string, lines: string[] | undefined): void;
+}
 /**
- * 单次 agent 调用的结果（统一形态）。
+ * subagent text_delta streaming 生命周期对象。
  *
- * Engine 直接消费 SubprocessAgentRunner 返回值；callCache replay 时 worker
- * 取 parsedOutput ?? content（见 worker-script-builder.ts 消息处理）。
+ * 创建后：
+ * - `onDelta(delta)`：session-runner 每次 text_delta 调
+ * - `dispose()`：subagent 终态时调，清除 widget + 清 timer
+ *
+ * buffer/timer 状态全部内聚在此对象，调用方不需要关心合并逻辑。
  */
-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）。
-    */
-    parsedOutput?: unknown;
-    /** Token and cost usage accumulated across all assistant turns. */
-    usage?: AgentUsage;
-    /** Wall-clock duration in milliseconds. */
-    durationMs?: number;
-    /** True when the pi process exited with code 0. */
-    error?: string;
-    /**
-    * Pi session ID for the subagent process (uuidv7).
-    * Present when pi emits a session header (default in --mode json).
-    * Can be used to locate the session JSONL file for post-run inspection (G-017)。
-    */
-    sessionId?: string;
-    /**
-    * Session JSONL 绝对路径（不含目录的文件名在 subagents 侧 AgentResult.sessionFile）。
-    * 由 mapToWorkflowAgentResult 从 subagents AgentResult 透传——让 workflow 编排层
-    * 继承 subagent 执行管道产出的 session 文件路径，overlay/GUI 可直接定位。
-    * 窗口期内可能 undefined（session 尚未创建成功）。
-    */
-    sessionFile?: string;
-    /**
-    * Absolute path of the git worktree used for filesystem isolation (set when
-    * worktree isolation is active). Injected by executeAndAwait from record.worktreeHandle.path.
-    *
-    * ⚠️ Diagnostic only, may not exist: executeAndAwait's finalizeRecord cleans up the
-    * worktree (git worktree remove --force) before returning, so by the time this field
-    * reaches the caller the directory has typically been deleted. Use it only for log/trace
-    * correlation (e.g. attributing a session jsonl to its worktree origin) — never as a cwd
-    * for a subsequent agent or filesystem operation (would ENOENT).
-    */
-    worktreePath?: string;
-    /** All tool calls collected from JSONL stream (FR-7). */
-    toolCalls?: ToolCallEntry[];
+declare class SubagentStream {
+    private readonly widgetKey;
+    private readonly sink;
+    private buffer;
+    private timer;
+    private hasFlushed;
+    private disposed;
+    constructor(recordId: string, sink: StreamSink);
+    /** 接收一个 text_delta 增量。空串静默丢弃（不消耗 leading edge）。 */
+    onDelta(delta: string): void;
+    /** 终态清理：清除 widget + 清 timer（幂等）。 */
+    dispose(): void;
+    private flush;
 }
+
 /**
- * 执行追踪节点（事件流 D-10 单一来源）。
+ * run 的运行期上下文。任务声明（AgentCallOpts，D6 合流后的单一形状）与运行期句柄
+ * 分离——signal/ctxModel/onComplete 从 ExecuteOptions 移出（设计 §3.3.5 删字段去向），
+ * 因为它们是宿主注入的运行期对象，不属于跨引擎持久化的任务声明。
+ *
+ * 常驻进程友好（D1）：onEvent 回调式（而非迭代器式）+ AbortSignal——引擎内部换常驻
+ * server 实现（未来 driver host）时接口不动。
  */
-interface ExecutionTraceNode {
-    stepIndex: number;
-    agent: string;
-    task: string;
-    model: string;
-    status: "pending" | "running" | "completed" | "failed";
-    /** Phase name for TUI grouping. Set from explicit opts.phase or global _currentPhase. */
-    phase?: string;
-    startedAt?: string;
-    completedAt?: string;
-    result?: AgentResult;
-    error?: string;
+interface RunContext {
+    /** = record.id（bg-N-xxx / run-N）——journal 文件名与池引用计数 key（P2 消费）。 */
+    taskId: string;
+    /** D5 隔离池（宿主分配，设计 §3.3.9；pi 无池化恒 'shared'）。 */
+    poolKey: string;
+    /** abort 分级入口（D1：引擎原生中断 → 公共杀链兜底）。 */
+    signal?: AbortSignal;
+    /** 事件流出口（host 消费后统一落 journal，D6 第②级）。 */
+    onEvent?: (event: AgentEvent) => void;
+    /**
+     * model 解析第三层兜底（现有 D-008 语义不变）——**pi 链路专属兜底**：经
+     * taskSpecToExecuteOptions → resolveModel 第三层消费（PiEngine 直通）。自带
+     * provider 体系与缺省模型的引擎（如 zcode：requested > 引擎缺省常量链）按自身
+     * 默认链解析，不消费本字段（zcode 侧在「ctx 有模型但被忽略」时出声留痕，
+     * zcode-engine.warnIgnoredCtxModel）。
+     */
+    ctxModel?: ModelInfo;
     /**
-    * Pi session ID (uuidv7) for the subagent process.
-    * Used to locate the session JSONL for post-run inspection.
-    */
-    sessionId?: string;
+     * text_delta streaming 通道（宿主侧 UI widget）。与 onEvent 平行的 text_delta 出口：
+     * background 路径 onEvent=undefined 但流式仍需送达（双通道互斥设计，见 session-runner
+     * agentEvent 出口注释）。pi 回填期承载 AgentRunner port 的 stream 透传（行为零变化），
+     * 语义上是宿主设施而非引擎专有——未来引擎的 text_delta 同样可走此通道。
+     */
+    stream?: SubagentStream;
     /**
-    * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
-    * 持久化到快照（serializeRun），跨 session 重水合后保留。
-    */
-    sessionFile?: string;
+     * [P1 pi 回填透传] 调用方已持有的 schema 激活预编码值（AgentCallOpts.schemaEnv 直传
+     * 形态）。生产路径中 resolveAgentOpts 恒耦合产出 schema+schemaEnv（值 = JSON.stringify
+     * (schema)），引擎从 task.schema 派生即可逐字节等值；解耦形态（有 schemaEnv 无
+     * schema）生产不可达、仅见于直构调用，派生无源——本字段是其唯一透交通道。
+     * 引擎在 task.schema 存在时忽略此值（派生优先，设计 §3.3.5 删字段去向）。
+     */
+    schemaEnv?: string;
     /**
-    * Live 执行进度对象（running 时存在，done 时由 dispatchAgentCall 清除）。
-    *
-    * 挂在 node 上（D-10 单源延伸：AgentCall.traceNode 与 Trace.nodes 共享同一引用）。
-    * TUI 通过 trace.toArray() 读 node.live，派生 getEventLog/getCurrentActivity 实时展示。
-    * 不持久化（序列化时 strip；重跑时由 dispatchAgentCall 重建）。
-    */
-    live?: ExecutionRecord;
+     * [P4 D9①] 引擎 fallback 留痕（probe 失败路由回默认引擎）。路由层（routing.ts）
+     * 产出，引擎投影到 outcome.engineFallback（zcode 等无 record 通路的引擎以此留痕；
+     * pi 引擎另经 ExecuteOptions 投影进 record）。
+     */
+    engineFallback?: {
+        from: string;
+        reason: string;
+    };
+    /**
+     * [P4 对齐点③] 引擎声明实际隔离池 key（journal 落盘路径权威）。宿主创建 journal
+     * writer 时只能用缺省占位 poolKey（pi 恒 'shared'），非池化稳定的引擎（zcode 按
+     * provider+model 池化）在 prepare 期确定 poolKey 后回调本方法重定向 writer——
+     * 保证 journal 落盘路径与 handle.poolKey 同源（单一权威，不再两边推导）。
+     * 契约：必须在首个事件 emit 之前调用（zcode coarse 事件在终态后合成，天然满足；
+     * 未来流式引擎需在事件出口前调用）。
+     */
+    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;
+    /**
+     * [W3 v1.x] chat 会话形态参数（协议 run.params.chat 的 RunContext 承载位）：
+     *   - recordId：core 预建 record 的关联键（引擎据此上报首轮 runId 键之外的反向
+       *     载荷与 interact 定位）——task.conversation === true 的 chat 轮必传；
+     *   - resume：冷续锚点（重开已 idle 的 session 续聊；pi 消费 sessionRef.sessionFile
+       *     ——对照协议化设计前 SpawnResumeOpts.sessionFile 的锚点面）。
+     * 类型权威 = SDK RunChatParams（remote-engine 直传，结构互证由 implements 关系
+     * 在 typecheck 期承载）。非 chat 轮不传，wire 上不出现该键。
+     */
+    chat?: {
+        recordId: string;
+        resume?: ResumeAnchor;
+    };
+    /**
+     * [W3 v1.x] host/roundLifecycle 轮次生命周期消费口（第 9 反向通道，settled/idle/
+     * failed 三相位；关联键 runId|recordId 互斥）。首轮（run 会话形态）经 run 作用域
+     * 路由到达（runId 键）；续聊轮（interact）无 runId——经 EnginePort
+     * registerChatRoundRoute 的 recordId 键路由到达（见下）。消费语义（arm/disarm/
+     * settled 交棒）归宿主编排层（settled-watchdog 协议事件面接线，W4 三入口）。
+     */
+    onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void;
 }
 /**
- * Trace.update 用的 patch（字段全可选）。
- *
- * 不变式：只改单个 node 的 status/result/error/completedAt/sessionId。
- * callId 不存在时 update 为 no-op（D-10）。
+ * [W3 v1.x] chat 轮次反向通道路由（recordId 键）——interact 续聊轮的 streamDelta /
+ * roundLifecycle 分发目标（协议关联键裁定 D1-A：续聊轮无独立 runId）。与 run 作用域
+ * RunRoute 同构的薄消费面；注册/注销时机归宿主 chat 编排（轮开始注册、record 终态注销）。
  */
-interface TracePatch {
-    status?: "pending" | "running" | "completed" | "failed";
-    result?: AgentResult;
-    error?: string;
-    completedAt?: string;
-    sessionId?: string;
-    sessionFile?: string;
+interface ChatRoundRoute {
+    onStreamDelta?: (delta: string) => void | Promise<void>;
+    onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void | Promise<void>;
 }
 /**
- * Worker console.* 捕获条目（run 级诊断，仅展示在 TUI widget，不泄漏到 input area）。
+ * run 的返回：终态 + 可持久化 handle。
+ *
+ * handle 语义（设计 §3.3.5 run 错误语义三条）：prepare 期错误（credential_missing /
+ * model_not_available / prompt_too_large）在进程创建前 reject、不产生 handle；运行中
+ * 失败不 reject——合成 error outcome + 正常 handle 返回（record 必须收尾）；abort 走
+ * 完杀链后同前（exitCode=null + error 含杀链标记）。
  */
-interface WorkerLogEntry {
-    level: "log" | "warn" | "error" | "info";
-    message: string;
+interface EngineRunResult {
+    handle: EngineHandle;
+    outcome: AgentOutcome;
 }
-
 /**
- * 一次引擎执行的终态。锚定 orchestration/models/types.ts 的 AgentResult（workflow
- * 引擎消费的那份——content/parsedOutput/usage/error）并追加引擎层字段；见文件头消歧说明。
+ * subagent 执行引擎的唯一契约点（D1）。实现方：PiEngine（回填）/ ZcodeEngine（P3）/
+ * 未来各引擎适配器。上层（工具面/workflow 引擎/GUI）只消费中立类型，不感知引擎。
+ *
+ * 贯穿纪律（设计 §3.3.1）：宿主编排——引擎只当单 agent 执行器，六家原生多 agent 机制
+ * 一律禁用不依赖。
  */
-interface AgentOutcome {
-    /** 原样（AgentResult.content）。 */
-    content: string;
-    /**
-     * 原样（AgentResult.failureKind，D5-③ 失败分诊结构化标签）。产出侧唯一识别点 =
-     * engines/pi/output-collector（collectResult 分类写入）；缺省 = unknown = 可重试
-     * （消费侧 executeAgentCall 只读字段分诊，不扫 error 文案）。非 pi 引擎不产出，
-     * 恒缺省（unknown 语义）。
+interface EnginePort {
+    /** 注册表 key（'pi' | 'zcode' | ...）。 */
+    readonly id: string;
+    /** D3（同步无副作用——调用前拒绝的判据）。 */
+    capabilities(): EngineCapabilities;
+    /** D7（factory 初始化 + 版本变化检测触发；opts.force 跳过缓存强探）。 */
+    probe(opts?: {
+        force?: boolean;
+    }): Promise<ProbeReport>;
+    /** D1 主语义：fire-to-completion。[D6 合流] task = AgentCallOpts（单一任务形状，
+     *  原 AgentTaskSpec 已并入——字段裁定见 orchestration/models/types.ts）。 */
+    run(task: AgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
+    /**
+     * D1 可选面：交互控制面。pi 首期原生实现（现有 chatMode 行为直通）；不支持
+     * conversation 的引擎返回 engine_capability_unsupported（同步拒绝、不创建进程）。
      */
-    failureKind?: AgentFailureKind;
-    /**
-     * 原样（AgentResult.parsedOutput）。native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：
-     * native 路径公共层不做二次校验、不改写其结果）。
+    interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult>;
+    /** D6 三级降级链：①引擎原生读取 → ②宿主 event journal（P2）→ ③outcome-only。 */
+    read(handle: EngineHandle): Promise<SessionView>;
+    /**
+     * [W3 v1.x] 可选面：chat 轮次反向通道路由注册（recordId 键）。interact 续聊轮的
+     * streamDelta / roundLifecycle 按 recordId 关联（无 runId，D1-A），引擎进程发射后
+     * 经协议客户端分发到本路由。与 validateModel/listModels 同款的 additively-optional
+     * 演进：宿主 feature-detect（`typeof registerChatRoundRoute === "function"`），
+     * 未实现的引擎（不支持 chat 域或旧客户端）续聊轮 delta/生命周期静默不可达——
+     * conversation gate 已在派发前拦住无 chat 能力的引擎，本缺省只在「能力声明与
+     * 客户端实现错位」的诊断形态出现。返回注销函数（record 终态时宿主调用）。
      */
-    parsedOutput?: unknown;
-    /** 原样（AgentResult.usage，orchestration 版 AgentUsage：含 contextTokens/turns）。 */
-    usage?: AgentUsage;
-    /** 原样（AgentResult.durationMs）。 */
-    durationMs?: number;
-    /** 原样（AgentResult.error，错误码前缀格式见设计 §3.3.3 错误规格表）。 */
-    error?: string;
-    /** 原样（AgentResult.sessionId，引擎语义 session id）。 */
-    sessionId?: string;
-    /** 原样（AgentResult.sessionFile）。 */
-    sessionFile?: string;
-    /** 原样（AgentResult.worktreePath，仅诊断——目录可能已被 finalize 清理）。 */
-    worktreePath?: string;
-    /** 原样（AgentResult.toolCalls，ToolCallEntry[]）。 */
-    toolCalls?: ToolCallEntry[];
-    /** 新增：实际执行引擎（fallback 后可能 ≠ 请求值，D9①）。 */
-    engineId: string;
-    /** 新增：fallback 留痕（record 同步投影，GUI 警告条数据源）。P1 恒缺省（无 fallback 路由）。 */
-    engineFallback?: {
-        from: string;
-        reason: string;
+    registerChatRoundRoute?(recordId: string, route: ChatRoundRoute): () => void;
+    /**
+     * [U7] 可选面：模型可发现性——引擎自带 provider/model 体系时（如 zcode 的 v2 桌面
+     * 登录态），列出当前环境实际可用的模型清单（带凭据校验），供 system prompt 引擎段
+     * 与 GUI 引擎选择器消费。省略/返回 null = 「与主 agent 模型体系一致」（pi 的语义：
+     * system prompt 已有 <available_provider_models> 段，无需引擎再列）。
+     * engine-neutral：未来引擎（AcpEngine 等）实现本方法即自动获得注入与展示，宿主
+     * 侧零改动。
+     */
+    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 ref 供
+     * record.model 留痕。[W3 契约变更④] 协议化后 canonicalRef 允许**无斜杠**形态
+     * （引擎原样返回的 ref）——core 侧按 provider=""/id=ref/整串进 name 拆分留痕
+     * （splitEngineModelRef 单一权威），不落 "<ref>/" 畸形。
+     *
+     * 未实现：model 透传，引擎自身 prepare 期校验兜底（现状语义）；pi 不实现（pi 链走
+     * 既有三层解析 + assertCanonicalModelRef 裁决，搬迁是大重构，设计 D2-2 被否②）。
+     */
+    validateModel?(modelRef: string | undefined): {
+        canonicalRef: string;
     };
-    /** 新增：null = 被信号杀死（杀链/abort 合成终态的判据）。P1 pi 链路不暴露 exit code，恒缺省。 */
-    exitCode?: number | null;
+    /**
+     * [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>;
 }
+
+/** 引擎工厂：惰性创建引擎实例（getEngine 首次取用时执行）。 */
+type EngineFactory = () => EnginePort;
 /**
- * EngineHandle 的持久化形态（设计 §3.3.6，JSON v1）。
- * 内存态 EngineHandle = 本数据 + 引擎运行时引用（各引擎自持）。
+ * 引擎包 manifest 注册期快照（session_start 扫描所得，非握手缓存——设计 §3.3「同步
+ * 成员清单」单一同步源原则）。descriptor 携带，cli 形态 port（RemoteEngine）的同步
+ * 成员（capabilities/listModels/validateModel）直读本快照。
+ *
+ * 与 client/remote-engine.ts 的 RemoteEngineManifestSnapshot 是结构闭包（后者多出
+ * core 中立类型包装；漂移由 protocol-closure 同族结构互证断言守卫）。
  */
-interface EngineHandleData {
-    v: 1;
-    /** 引擎 id（'pi' | 'zcode' | ...，registry key）。 */
-    engineId: string;
+interface EngineManifestSnapshot {
+    /** manifest `capabilities`（同步能力位权威，注册期读，无缓存）。 */
+    capabilities: EngineCapabilities;
     /**
-     * 引擎自定义键值（定位符）。pi = { recordId?, sessionFile? }——recordId 是
-     * interact 控制面的 key（subagent record id），sessionFile 是 read 第①级（JSONL
-     * 直读）的定位符；zcode = { sessionId, dbPath }。
+     * manifest `modelCatalog` 三态（W4 §2.4：缺省 = 不注入保持 undefined；null 合法等价
+     * 省略；`models: []` 仅作者显式声明）。解析器不得把省略填成 `[]`——否则「无枚举面」
+     * 语义不可达。
      */
-    sessionRef: Record<string, string>;
-    /** 隔离池定位（设计 §3.3.9）。pi 无池化（PI_CODING_AGENT_DIR 全局一份）恒 'shared'。 */
-    poolKey: string;
-    /**
-     * journal 绝对路径（read 第②级数据源；runtime 读前校验前缀白名单）。
-     * P2 event journal 落地后由宿主回填；P1 无 journal 写入者，缺省 undefined——
-     * read 降级链第②级不可达，直接走 ①/③。
+    modelCatalog?: {
+        dynamic: boolean;
+        models: ModelCatalogEntry[];
+    } | null;
+    /** manifest `displayName`（可选，缺省 = id；D4 缺省引擎回落序的排序键）。 */
+    displayName?: string;
+}
+/** cli 形态 descriptor（目标形态）：引擎 CLI 启动参数 + manifest 快照 + port 装配器。 */
+interface CliEngineDescriptor {
+    kind: "cli";
+    /** 引擎 CLI 命令（发现器解析后的绝对路径/可执行名；不依赖 PATH）。 */
+    command: string;
+    /** 引擎 CLI 参数（不含 command 本身）。 */
+    args: readonly string[];
+    /** manifest `capabilities`（同步能力位权威——gate 同步消费，无缓存）。 */
+    capabilities: EngineCapabilities;
+    /**
+     * cli 形态 EnginePort 实例装配器（core 侧接线通道，非 manifest 面）。生产 = W4
+     * 发现器装载 descriptor 时装配（W2 `RemoteEngine` + `EngineClient` + 宿主侧参数
+     * dataDir/hostKind/engineConfig 等——registry 不越权猜宿主形态）。必须构造同步、
+     * 不 throw（§3.5.3 代理形态：缺包/坏包的失败推迟到首次协议调用）。
      */
-    journalPath?: string;
-    /** probe 实测版本（漂移排查锚点）。 */
-    engineVersion?: string;
-    /** 适配器版本（golden 样本对齐排查）。 */
-    adapterVersion: string;
+    portFactory: EngineFactory;
+    /** manifest 快照余项（modelCatalog/displayName；capabilities 已提升为直读字段）。 */
+    manifest?: Omit<EngineManifestSnapshot, "capabilities">;
 }
 /**
- * 引擎会话句柄（run 返回、interact/read 入参）。
- *
- * 契约三条（D1）：不透明（上层不解构——唯一例外是 record 持久化层序列化 data 字段与
- * read 降级链）、可持久化（data 是纯 JSON，主会话 reload 后 read/interact 仍可用）、
- * 自描述（data 含 engineId + 引擎 session 定位符 + pool key + adapter 版本）。
- *
- * 对进程已死的 handle 调 interact 必须返回 engine_session_not_resumable（指向 cold
- * resume 路径），而非笼统失败——由各引擎 interact 实现保证。
+ * 缺省引擎 id（D4 重定义：**配置的缺省引擎 id**——config defaultEngine 未配置时的
+ * 归一名，不再表达「内置 pi 永久兜底」）。配置值不在已发现清单 → warn + 回落第一个
+ * 可用引擎（manifest displayName 稳定序，D4）；全不可用 → 派发期 engine_not_found
+ * （「未发现任何引擎包」+ 安装指引）。
  */
-interface EngineHandle {
-    /** 持久化数据。上层不得解构其内部字段（见契约三条）。 */
-    readonly data: EngineHandleData;
-}
+declare const DEFAULT_ENGINE_ID = "pi";
 /**
- * read(handle) 的返回：turns[] 派生数据。与 Turn 同构但无内部态（_status/startedTs
- * 剥离，closed 恒 true）。
+ * defaultEngine 缺省归一（单一权威源）：空白 / undefined 归一到缺省引擎（'pi'）。
+ * 引擎感知检测 diff 与状态段渲染必须对同一读取结果给出同一引擎 id——若两处各自
+ * 内联归一，一致性只靠注释人工耦合，漂移即两处说谎；故收敛到本函数供各处调用。
+ * sanitize 保证透传值非空，但可能带首尾空格，故 trim 后再判。
  */
-interface ReplayedTurn {
-    text: string;
-    thinking: string;
-    /** 导出的纯净形状（execution 层 ToolCall，无 _status）。 */
-    toolCalls: ToolCall[];
-    closed: true;
+declare function normalizeEngineId(engine: string | undefined): string;
+
+/** 单个引擎包的检查产物。 */
+type PackageInspection = {
+    status: "ok";
+    entry: DiscoveredEngine;
+} | {
+    status: "skip";
+    reason: string;
+} | {
+    status: "unusable";
+    id: string | undefined;
+    reason: string;
+};
+/** 发现成功的引擎条目（装载序；同 id 后者覆盖前者）。 */
+interface DiscoveredEngine {
+    id: string;
+    /** 发现源标签（env 名 / 宿主根 source / node-modules / config.json）。 */
+    source: string;
+    /** L3 显式 config（initialize.engineConfig 透传；L1/L2 manifest 发现无此项）。 */
+    engineConfig?: Record<string, string>;
+    descriptor: CliEngineDescriptor;
 }
 /**
- * session 历史的引擎中立视图。降级链三级（D6）：①引擎原生读取（pi JSONL / zcode
- * sqlite）→ ②宿主 event journal 重放（P2）→ ③outcome-only。source 字段是 GUI 降级
- * 标记数据源（A8）。
+ * 检查单个候选包目录（读 package.json → manifest 字段级解析 → bin 可执行验证）。
+ * 三态：ok（装载）/ skip（必需字段缺失/不可解析——warn 跳过该包）/ unusable
+ * （protocol 不兼容、bin 不可执行——标记不可用，不进清单）。
  */
-interface SessionView {
-    engineId: string;
-    sessionId?: string;
-    /** turns[] 派生数据（重放/重建产物）。 */
-    turns: ReplayedTurn[];
-    /** 各 turn usageDelta 聚合（execution 层 AgentUsageTotal）。 */
-    usage?: AgentUsageTotal;
-    source: "native" | "journal" | "outcome-only";
-}
+declare function inspectEnginePackage(pkgDir: string, source: string, hostKind: string, env: NodeJS.ProcessEnv): PackageInspection;
+
+/** L1 引擎发现根 env（设计 §3.4；值形态 = path.delimiter 分隔的绝对路径列表）。 */
+declare const ENGINE_ROOTS_ENV = "XYZ_AGENT_ENGINE_ROOTS";
+/** L1 env 根解析：path.delimiter 分隔；空段跳过；非绝对路径丢弃 + warn；去重（大小写敏感）。 */
+declare function parseEngineRootsEnv(env: NodeJS.ProcessEnv): string[];
 /**
- * 引擎能力声明（设计 D3 原样落地）。三级：native / emulated / unsupported。
- *
- * 易错点（D3）：声明的是**本仓 subagent 链路实际接通的能力**，不是引擎 RPC 层的理论
- * 能力——pi 的 RPC 有 steer 但现有 spawn 链路未接通（session-runner steer no-op），
- * 故 PiEngine 声明 unsupported，接通后再升级。上层据声明选择策略（schema 为 emulated
- * 时自动走公共降级层；steer/conversation unsupported 时 UI 隐藏对应入口），而非
- * try-catch 运行时试错。
+ * L2 根推导：宿主进程入口（process.argv[1]）所在目录逐级上溯的 node_modules——与
+ * createRequire(<宿主入口>) 的 require.resolve 候选目录链同构（「宿主 node_modules
+ * require.resolve」的扫描化：零枚举发现要求扫目录而非 resolve 具体包名）。打包态
+ * （staged 扩展 / Bun standalone 无 node_modules 结构）与 zsw vendor 态自然为空——
+ * 规格明确两态 L2 无效。argv[1] 不可得（嵌入式 / worker）→ L2 缺席。
  */
-interface EngineCapabilities {
-    /** native: --json-schema/--output-schema/env 注入（pi = PI_WORKFLOW_SCHEMA 链路）。 */
-    schemaEnforcement: "native" | "emulated";
-    /** 注意区分「引擎 RPC 层有此能力」与「subagent 链路已接通」。 */
-    steer: "native" | "emulated" | "unsupported";
-    /** interact 控制面（message/close/cancel + idle）。 */
-    conversation: "native" | "unsupported";
-    /** 决定 persona 路由策略（公共降级层按此选择 file/flag/prompt 通道）。 */
-    personaInjection: "file" | "flag" | "prompt";
-    /** 粗粒度引擎：GUI 显示降级为阶段态。 */
-    eventGranularity: "stream" | "coarse";
-    /** emulated = worktree 隔离（无 OS sandbox 的引擎用文件写维度隔离补齐）。 */
-    sandbox: "native" | "emulated" | "none";
-    /** 重建历史的能力（read 降级链第①级的保真度上限）。 */
-    sessionRead: "full" | "partial" | "outcome-only";
-    resume: "native" | "cold" | "unsupported";
-    /** 优雅中断 or 只能杀进程（公共杀链兜底，见 D1 abort 分级）。 */
-    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;
+declare function deriveNodeModuleRoots(argvEntry?: string | undefined): string[];
+
+/** 日志级别。对齐 @zhushanwen/pi-extension-logger 的 LogLevel（三值，无 info）。 */
+type LogLevel = "debug" | "warn" | "error";
+/** core logger 接口。与 pi-extension-logger 的 ExtensionLogger 结构兼容——
+ *  u0-log 批次替换是纯 import 源替换，调用面（方法名/参数序）逐文件等价。 */
+interface CoreLogger {
+    debug(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    error(msg: string, data?: unknown): void;
 }
-/** 引擎探针报告（probe() 返回）。探针在引擎 factory 初始化与版本变化检测时触发（P4 接线）。 */
-interface ProbeReport {
-    ok: boolean;
-    /** 实测版本（handle.engineVersion 数据源）。探测不到时为空串。 */
-    engineVersion: string;
-    /** 二进制存在/版本解析/干跑回归逐项。 */
-    checks: Array<{
-        name: string;
-        ok: boolean;
-        detail?: string;
-    }>;
-    /** engine_probe_failed 的恢复指引（设计 §3.3.3 终态四样例；ok=false 时必填）。 */
-    error?: {
-        code: string;
-        recovery: string;
+declare function getLogger(component: string): CoreLogger;
+
+/** 发现根条目：dir 为扫描根路径；source 是宿主提供的语义标签（遮蔽报告透传用）。
+ *  source 不枚举封闭集——core 只透传不解释（宿主如 pi 壳用 user-pi/npm/npm-dev）。 */
+interface DiscoveryRoot {
+    dir: string;
+    source: string;
+}
+interface HostServices {
+    /** 数据根目录：引擎隔离池 / journal / record 派生存放的锚点。
+     *  pi 壳返回 getAgentDir()（独立 pi 用户 journal 不漂目录）；zsw 壳返回 zsw 数据根。 */
+    dataRoot(): string;
+    /** 结构化日志：对齐现 getLogger 调用面（level/component/message/data）。缺省 sink 按级分化：
+     *  warn/error 走 console、debug no-op（对齐 pi-extension-logger 语义，见 NULL_HOST.log）。 */
+    log(level: LogLevel, component: string, message: string, data?: unknown): void;
+    /** agent/skill/workflow/引擎包 资源发现根（可选端口，缺席 = 调用方降级）。宿主只提供根列表
+     *  （按优先级低→高）；扫描 / 同名遮蔽（last-writer-wins）/ 遮蔽报告语义归 core 统一。
+     *
+     *  engines kind（W4，设计 §3.4 L1 第二通道）：引擎包发现根——dir 下一级（及 org 分组
+     *  二级）子项 = 候选引擎包目录，命中 package.json `xyz-agent.subagentEngine` manifest
+     *  即发现。打包态主通道是 env `XYZ_AGENT_ENGINE_ROOTS`（W9 注入），此端口承载宿主
+     *  自身模块域（如 pi 宿主包 node_modules 的引擎包 dependencies 安装位）。 */
+    discoveryRoots?(): {
+        agents?: DiscoveryRoot[];
+        skills?: DiscoveryRoot[];
+        workflows?: DiscoveryRoot[];
+        engines?: DiscoveryRoot[];
     };
 }
+/** core 缺省数据根（~/.subagent-core，homedir 推导——禁止写死绝对路径，排查规则）。
+ *  供无自有数据根的轻宿主显式采用；core 自身不静默兜底到该值。 */
+declare const DEFAULT_DATA_ROOT: string;
+declare function configureCore(host: HostServices): void;
+declare function getHostServices(): HostServices;
+
+/** 扫描结果（诊断面：skip/unusable 逐包留痕原因，对应 A12 负面场景）。 */
+interface DiscoveryScanResult {
+    discovered: DiscoveredEngine[];
+    skipped: Array<{
+        pkgDir: string;
+        reason: string;
+    }>;
+    unusable: Array<{
+        pkgDir: string;
+        id: string | undefined;
+        reason: string;
+    }>;
+}
+interface DiscoverEnginesOptions {
+    /** 宿主种类（EngineClient pidfile 实例维度命名段：pi 壳 'pi'、runtime 'runtime'）。 */
+    hostKind: string;
+    /** L3 显式配置目录（<dir>/subagents/config.json 的 engines 段）。缺省 = 无 L3。 */
+    agentDir?: string;
+    /** 引擎数据根（EngineClient dataDir；缺省 portFactory 执行期 getEngineDataDir 解析）。 */
+    dataDir?: string;
+    /** env 覆盖（L1 根读取；缺省 process.env——测试注入隔离宿主 env）。 */
+    env?: NodeJS.ProcessEnv;
+    /** L2 覆盖（测试注入；缺省 = 宿主入口上溯 node_modules 链）。 */
+    nodeModuleRoots?: string[];
+    /** 附加发现根（调用方/测试追加的 L1 根，语义同 HostServices.engines）。 */
+    extraRoots?: DiscoveryRoot[];
+}
+/** 纯扫描（不装载注册表）。装载序 = L1 env → L1 宿主/附加根 → L2 → L3（后者覆盖前者）。 */
+declare function scanEngines(opts: DiscoverEnginesOptions): DiscoveryScanResult;
 /**
- * interact 的 action（D1 交互控制面）。pi 首期原生实现（现有 chatMode 行为直通）；
- * 声明 conversation unsupported 的引擎调用前拒绝（engine_capability_unsupported）。
+ * 扫描 + 装载：descriptor 经 registerEngineDescriptor 进注册表（幂等覆盖——重复扫描
+ * 安全）。装载覆盖既有注册（含过渡期 inproc pi/zcode——auto 模式下 cli descriptor
+ * 胜出即设计 D3 语义）时 debug 留痕。
  */
-type InteractAction = 
+declare function discoverAndRegisterEngines(opts: DiscoverEnginesOptions): DiscoveryScanResult;
 /**
- * interrupt：true = steer（抢占）/ false|缺省 = followUp（排队）——pi streamingBehavior
- * 语义的中立承载（D1 §3.3.5「后续 wave 如需抢占语义再扩展 InteractAction」的兑现，
- * chat 域投递经 engine.interact 接通时落地；不支持抢占的引擎忽略）。
+ * 历史发现装载的引擎 id 快照（投影源计算消费面，见 engine-discovery.ts）。
  */
-{
-    kind: "message";
-    payload: string;
-    interrupt?: boolean;
-} | {
-    kind: "close";
-    payload?: {
-        force: boolean;
-    };
-} | {
-    kind: "cancel";
-};
+declare function loadedDiscoveryIds(): string[];
 /**
- * interact 的结果。失败码取自设计 §3.3.3：engine_session_not_resumable（死 handle）/
- * engine_capability_unsupported（能力声明拒绝）等。
+ * hasEngine 的补扫面（§3.4 发现时机：快照未命中触发一次同步补扫，只读 manifest
+ * 不握手）。消费方 = agent 解析期/路由期的存在性校验接线（宿主侧注入 hasEngineFn
+ * 时用本函数替代裸 hasEngine）——「装了包 → 下次解析即可用」。
  */
-type InteractResult = {
-    ok: true;
-    delivered: true;
-} | {
-    ok: false;
-    code: string;
-    message: string;
-};
+declare function ensureEngineDiscovered(id: string, opts: DiscoverEnginesOptions): boolean;
 
-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 };
+export { type SubagentToolResult as $, type AgentEventLogEntry as A, type BgResponse as B, type ClosedReason as C, type DiscoverEnginesOptions as D, type EnginePort as E, type ForkFromResponse as F, CLOSED_REASONS as G, type CoreLogger as H, DEFAULT_AGENT_NAME as I, DEFAULT_DATA_ROOT as J, DEFAULT_ENGINE_ID as K, type ListResponse as L, type ModelRegistryLike as M, DirtyWorktreeError as N, type EngineHandle as O, type ProjectedOutcome as P, type EngineRunResult as Q, type RecordSnapshot as R, type SubagentRecord as S, type TracePatch as T, ForkDepthExceededError as U, type HostServices as V, type WorkerLogEntry as W, type LogLevel as X, ResurrectDeniedError as Y, type RunContext as Z, SLUG_MAX_LENGTH as _, type ExecutionRecord as a, configureCore as a0, getHostServices as a1, getLogger as a2, normalizeEngineId as a3, type DiscoveredEngine as a4, type DiscoveryScanResult as a5, ENGINE_ROOTS_ENV as a6, type PackageInspection as a7, deriveNodeModuleRoots as a8, discoverAndRegisterEngines as a9, ensureEngineDiscovered as aa, inspectEnginePackage as ab, loadedDiscoveryIds as ac, parseEngineRootsEnv as ad, scanEngines as ae, type ExecutionOutcome as b, type ExecutionStatus as c, type ExecuteOptions as d, SubagentStream as e, type AgentResult$1 as f, type AgentResult as g, type SubagentsGlobalConfig as h, type ModelInfo as i, type AgentConfig as j, type ResolvedModel as k, type StreamSink as l, type ExecutionHandle as m, type ExecutionMode as n, type PatchResult as o, type AgentCallOpts as p, type ExecutionTraceNode as q, type RunStatus as r, type DoneReason as s, type DisplayItem as t, type CancelResponse as u, type CloseResponse as v, type MessageResponse as w, type ExternalState as x, type SubagentListItem as y, type DiscoveryRoot as z };