@zhushanwen/subagent-core 0.7.1 → 0.9.0

package/dist/engine-discovery-scan-ocpM8FmI.d.ts

@@ -1,1608 +0,0 @@
-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 对齐。
- */
-interface ModelRegistryLike {
-    /** 返回所有已配置鉴权的可用模型。 */
-    getAvailable(): ModelInfo[];
-    /** 按 (provider, modelId) 查找。 */
-    find(provider: string, modelId: string): ModelInfo | undefined;
-    /** 校验模型鉴权是否就绪。 */
-    hasConfiguredAuth(model: unknown): boolean;
-}
-/**
- * 模型信息（registry 返回元素 / ctx.model 鸭子类型兼容）。
- * ctx.model（SDK Model<Api>）是此类型的超集，运行时直接当 ModelInfo 用。
- */
-interface ModelInfo {
-    id: string;
-    name: string;
-    provider: string;
-    reasoning: boolean;
-    thinkingLevelMap?: Record<string, unknown>;
-    contextWindow?: number;
-}
-/** agent .md frontmatter 解析结果。 */
-interface AgentConfig {
-    /** agent 名（文件名 basename）。 */
-    name: string;
-    /** system prompt（markdown 正文）。 */
-    systemPrompt: string;
-    /** tool allowlist（三层过滤之一）。 */
-    tools?: string[];
-    /** 默认模型 override（"provider/modelId"）。agent 作者显式指定。 */
-    model?: string;
-    /** 默认 thinkingLevel override。 */
-    thinkingLevel?: string;
-    /** 默认 background 模式（true 时无显式 wait 走 background）。 */
-    defaultBackground?: boolean;
-    /**
-     * 执行引擎 id（agent .md frontmatter engine 字段，D9 per-agent 主通道）。
-     * 解析期已对注册表校验（未注册 id 在 agent-registry 抛 EngineNotFoundError）；
-     * 执行侧（P4 路由层）按 调用参数 > 本字段 > 全局默认 三层取值。
-     */
-    engine?: string;
-}
-/** 解析结果（model 实例 + 生效的 thinkingLevel）。 */
-interface ResolvedModel {
-    model: ModelInfo;
-    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' 区分）。
- *
- * running = 活跃态。含两种子态（由派生谓词区分，见 lifecycle-predicates.ts）：
- *   - 对话模式等待续聊（旧 idle）：进程可能保活（isIdle=hasIdleTimer）或已回收
- *     待冷路径 resume（isResumable=running && 无活进程句柄）。
- *   - 正在执行（有活进程句柄）。
- *
- * closed = 统一终态（done/failed/crashed/cancelled 合并）。具体关闭原因由
- * {@link ClosedReason} 子枚举表达（如 user-close / gc / cancelled / parent-shutdown）。
- * ExecutionRecord.closedReason 携带 L2 原因，投影层按需派生对外语义（error / ended）。
- */
-type ExecutionStatus = "running" | "closed";
-/**
- * closed 终态的 L2 关闭原因子枚举。
- *
- * 与 ExecutionStatus="closed" 配合使用，表达「为什么关闭」：
- *   parent-shutdown  — 父进程 session_shutdown 时回收子进程
- *   parent-fork     — 父进程 fork 新 session 时清理旧子进程
- *   parent-new      — 父进程创建新 subagent 时清理旧子进程
- *   user-close      — 用户手动 close action（含对话模式 close）
- *   cancelled       — 用户取消（close(force:true) / cancelBackground）
- *   gc              — 通用完成/失败（一次执行自然结束、超时、错误等无专属 reason 的终态）
- *   disconnected    — .finalized sidecar 存在但无 reason 内容（磁盘重建兜底）：
- *                     正常结束但死因不可考——旧格式 sidecar（v8.5 前写入的是空文件）、
- *                     或外部工具手工创建。替代旧的误导性 "gc" 兜底（自然完成 vs 断联
- *                     不分），message/fork-from 据此给出可行动指引。
- */
-type ClosedReason = 'parent-shutdown' | 'parent-fork' | 'parent-new' | 'user-close' | 'cancelled' | 'gc' | 'disconnected';
-/**
- * [v8.5 D] 透明重生守卫拒绝专用错误：messageHandler 的 endedMessageGuard 必须原样
- * 透传本类错误（自带完整行动语言），不得按 A1 分流规则改写——否则 worktree/异进程
- * 占用文案会被「fork-from 指引」覆盖，误导 agent 走已被判死的通道。
- */
-declare class ResurrectDeniedError extends Error {
-}
-/** ClosedReason 全枚举值（运行时守卫用——防御性解析外部输入时校验成员资格）。 */
-declare const CLOSED_REASONS: readonly ClosedReason[];
-/**
- * 终态三态对外语义（U3 C-outcome 一等披露）。
- *
- * 由 completeRecord 唯一写入点按 deriveOutcome 一次计算（判定顺序：cancelled 优先
- * → error 非空 → completed），消费方（project/list/notify 文案/渲染器）只读本字段，
- * 不再各自手写成败推导 switch（三处同构 switch 已随 U3 收敛删除）。
- *
- * [D6 显式取舍] parent-shutdown/parent-fork/parent-new 合成关闭（subagent-service
- * disposeAllRecords 合成 result 恒写 error:"closed due to ..."）落 "failed"——语义为
- * 「父进程关闭时子 agent 未完成即失败」，选定行为而非疏漏，勿当 bug 改回 cancelled。
- */
-type ExecutionOutcome = "completed" | "failed" | "cancelled";
-/**
- * 对外投影的 outcome 联合：含历史 record（outcome 字段诞生前的存量数据）兼容态。
- * 投影层（projectOutcome 唯一出口）对无 outcome 字段的 closed record 按
- * deriveOutcome(closedReason, error) 兜底派生；"closed-legacy" 预留给连派生输入都
- * 不足以判读的存量形态，消费方必须处理该成员（不得因未知值崩溃）。
- */
-type ProjectedOutcome = ExecutionOutcome | "closed-legacy";
-/**
- * 对外四态（设计决策 10 细则 3）：内部 ExecutionStatus（v4 B-1 两态）收敛为 agent
- * 可理解的状态语义。真实映射只有两条：
- *   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";
-
-/**
- * eventLog 条目（getEventLog 派生产出的元素）。所有字段 readonly。
- *
- * text_output / thinking 类型已移除——它们是 100 字切片的碎片副产物，
- * 现在完整内容收口在 record.turns[] 里，eventLog 只承载离散语义事件
- * （tool 调用 / turn 边界 / error）。
- */
-interface AgentEventLogEntry {
-    readonly type: "tool_start" | "tool_end" | "turn_end" | "error";
-    readonly label: string;
-    /** 事件发生的墙钟时间戳（Date.now()，ms）。由 getEventLog 从 turns[] 派生时记录。 */
-    readonly ts: number;
-    readonly status?: "running" | "done" | "failed";
-}
-/**
- * [STEP3] displayItem：从 turns[] 派生的展示项（对齐 nicobailon getDisplayItems）。
- *
- * 与 eventLog 的区别：eventLog 承载离散语义事件（tool_start/tool_end/turn_end），
- * displayItem 承载「可渲染单元」（toolCall 含完整 name+args 供 formatToolCall 格式化；
- * text 含 assistant 正文）。renderResult compact 分支改用 displayItems 后，
- * 行格式与 nicobailon 完全一致（→ formatToolCall）。
- */
-interface DisplayItem {
-    readonly type: "toolCall" | "text";
-    /** toolCall：tool 名称（bash/read/edit...）；text：无。 */
-    readonly name?: string;
-    /** toolCall：tool 原始 args（供 formatToolCall 提取路径/命令）；text：无。 */
-    readonly args?: Record<string, unknown>;
-    /** toolCall：执行状态（running 时无✓/✗标记）；text：正文文本。 */
-    readonly status?: "running" | "done" | "failed";
-    /** text：assistant 正文（compact 时取首行/截断）。 */
-    readonly text?: string;
-}
-/** 一次 session 执行的完整结果。collectResult 产出，写入 Record.outcome。 */
-interface AgentResult {
-    text: string;
-    turns: number;
-    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;
-    /** /resume /fork 可恢复的 session 文件名（不含目录）。 */
-    sessionFile?: string;
-    /** schema 模式下，structured-output tool 的 result.details（已通过 schema 校验）。 */
-    parsedOutput?: unknown;
-}
-
-/** alive marker：子进程存活标记，用于心跳检测和 crash 推断。 */
-interface AliveMarker {
-    readonly pid: number;
-    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);
-}
-/** worktree 有未提交变更错误。 */
-declare class DirtyWorktreeError extends Error {
-    constructor(message: string);
-}
-/**
- * 所有执行路径的唯一状态源。
- *
- * 收口设计：一次执行的完整内容（text/thinking/toolCalls/usage）按 turn 收口在
- * `turns: Turn[]` 里。eventLog / currentActivity / result 文本均从 turns[] 派生
- * （getEventLog / getCurrentActivity / getFullText），不再独立存储切片或缓冲。
- *
- * 生命周期：createRecord() 创建 → updateFromEvent() 实时更新（累积进 turns）→
- *           completeRecord() 冻结 → archive 立即移出内存（读时从 session.jsonl 重建）。
- *
- * TUI 永远拿 RecordSnapshot（.slice() 快照），不直接持此可变对象。
- */
-interface ExecutionRecord {
-    /** 唯一 ID（sync: "run-N"，bg: "bg-N-xxx"）。 */
-    readonly id: string;
-    readonly agent: string;
-    readonly model: string;
-    readonly thinkingLevel: string | undefined;
-    readonly mode: ExecutionMode;
-    readonly task: string;
-    /**
-     * 人类可读的短标签（≤35 字符），简述本次 subagent「在做什么」。
-     * 区别于 agent（类型名）/ task（完整 prompt）。旧持久化 record 反序列化时缺失兜底空串。
-     */
-    readonly slug: string;
-    readonly startedAt: number;
-    /** 根 Pi session ID（session 隔离过滤用）。递归链上所有层 record 同值。 */
-    readonly rootSessionId: string | undefined;
-    /** 直接父 subagent record ID（层级树构建用）。顶层 record 为 undefined。 */
-    readonly parentRecordId: string | undefined;
-    /** subagent 递归深度。顶层（主 session 直接创建）=0，每层嵌套 +1。 */
-    readonly depth: number;
-    /**
-     * 对话模式标志（可持续对话 subagent）。true = 轮次完成进 idle 态（保留 record +
-     * worktree）等待续聊，而非一次性终态化。
-     * undefined/false = 一次性模式（默认，行为完全不变）。
-     * 向后兼容：旧 record / 旧 session 文件无此字段，按一次性模式处理。
-     */
-    readonly chatMode?: boolean;
-    /**
-     * 执行态信号（residual-fixes 设计）：true = 该 record 无活进程驱动（轮终 idle /
-     * 重建孤儿兜底），处于「可续聊/等续聊」态——不是后台真在跑。轮终迁移
-     * （doFinalizeRoundToIdle）置 true，冷路径续轮（进程启动）清除；GUI 侧
-     * streaming/waiting 细分与 hasRunning 判据消费。缺省 falsy = 有进程或旧数据。
-     */
-    resumable?: boolean;
-    /**
-     * 空闲超时毫秒数（仅 chatMode 有意义）。覆盖默认 5min idle timeout。
-     * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
-     * 向后兼容：旧 record 无此字段，按默认值处理。
-     */
-    readonly idleTimeoutMs?: number;
-    /**
-     * 实际执行引擎 id（P4 路由留痕，D9①）。创建时确定不可变；缺省（存量 record）
-     * = pi 投影（消费方零迁移）。持久化经 subagent-record entry。
-     */
-    readonly engine?: string;
-    /**
-     * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源；
-     * 缺省 = 无 fallback。持久化经 subagent-record entry。
-     */
-    readonly engineFallback?: {
-        from: string;
-        reason: string;
-    };
-    /**
-     * 引擎自描述定位符（U2：非 pi run resolve 后回填、终态迁移落 entry 前——run 前
-     * 缺省不可用）。sessionRef 整体透传（失败终态 sessionId 缺失时仍回填已有部分，
-     * 读侧①级降②级的防御形态）；journalPath 为 retarget 后实际落盘路径。pi 分支不
-     * 回填（sessionFile 即定位符）。持久化经 subagent-record entry。
-     */
-    engineHandle?: {
-        sessionRef: Record<string, string>;
-        journalPath?: string;
-        poolKey: string;
-    };
-    /**
-     * 同步收集模式标记（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) 写入；投影层按需派生对外语义。
-     *  向后兼容：旧 record 无此字段，按 gc 处理（通用完成/失败）。 */
-    closedReason?: ClosedReason;
-    /**
-     * 终态三态对外语义（U3 C-outcome）。completeRecord 唯一写入点按 deriveOutcome
-     * 一次计算，消费方只读本字段不再自行推导。向后兼容：旧 record / 磁盘重建
-     * 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，冗余存储供投影直接读）。 */
-    turnCount: number;
-    totalTokens: number;
-    /** 运行期最近一次 error 事件的消息（getEventLog 派生 error 条目用）。 */
-    lastError: string | undefined;
-    /**
-     * 对话轮次计数（仅 chatMode 有意义）。首轮运行时 = 0；每完成一轮（finalizeRoundToIdle
-     * 进 idle）+1。undefined 时视为 0。非 chatMode 不自增。
-     */
-    round?: number;
-    /**
-     * [增量通知] 当前轮次增量的 turns[] 起始下标（仅 chatMode 有意义；内存态记账，D4 不持久化）。
-     *
-     * - 生命周期：undefined 视为 0（首轮增量 = 全量，与改造前首轮通知逐字节一致，向后兼容旧
-     *   record）；唯一写点 onRoundSettled 第 5 步（notify 之后推进），唯一读点同回调第 2 步
-     *   （`getFullTextFrom(record, record.roundBaseTurnIndex ?? 0)`）。非 chatMode 恒
-     *   undefined（onRoundSettled 是 session-runner chatMode 分支专属回调）。
-     * - D1 滞后空 turn 防丢文本（防御性）：pi 当前事件序下该形态不可达——带 usage 的
-     *   message_end 恒先于 turn_end（@earendil-works/pi-agent-core dist/agent-loop.js
-     *   :240/:253/:547 三处 message_end emit 均在 :131 正常路径 turn_end 之前），settle 时
-     *   turn 全闭合。防 pi 未来事件序变化：若 settle 时刻末 turn 是滞后 message_end 开出的
-     *   空 turn（execution-record.ts message_end 分支经 currentTurn，需同时过两层 usage 守卫：
-     *   session-runner.ts 转发层 `if (msg?.usage)`（bare message_end 不转发）+ execution-record.ts
-     *   累积层 `if (event.usage)`（bare message_end 不开 turn）），推进公式
-     *   nextRoundBaseTurnIndex 把它留在下一轮增量内（新轮首个 text_delta 经 currentTurn 复用该
-     *   空 turn，复用累积被 slice 覆盖）；直用 turns.length 推进会把下轮首段文本挤出 slice
-     *   范围静默丢失。
-     * - D4 不持久化：磁盘重建走 createRecord（turns 仅为初始 [emptyTurn()]），base=0 对空 turn
-     *   的增量派生等价为空、天然产出仅新轮增量，持久化是死数据。故不写 manifest、不参与重建。
-     * - pi 内部序锚定依据（R1 mitigation）：@earendil-works/pi-agent-core 0.84.2
-     *   dist/agent-loop.js :108-111（error/aborted stopReason 也先 emit turn_end 再 agent_end）
-     *   与 :131（正常路径 turn_end 收尾）；agent_settled 在 agent_end 之后 emit，故未闭合
-     *   turn 只可能来自滞后事件。pi 升级若改变 turn_end/agent_end 时序，onRoundSettled 推进前
-     *   的观测哨（末 turn 未闭合且 text 非空 → logger.warn）会留痕。
-     */
-    roundBaseTurnIndex?: number;
-    /**
-     * record 进入 idle 态的时间戳（ms）。finalizeRoundToIdle 设值；GC 定时器据此计算
-     * 剩余 TTL。undefined = 非 idle 态（running/closed/cancelled）或旧 record 缺失字段。
-     */
-    idleSince?: number;
-    /**
-     * close 优雅关闭标志（M2-B3）。chatMode record 运行中调 `close {force:false}` 时置 true；
-     * runAndFinalize 的 done 分流检查此标志——true 则终态化为 done（而非进 idle），并清标志。
-     * undefined/false = 正常 idle 分流（对话模式轮次完成进 idle 等续聊）。
-     * 仅 chatMode + running 时有意义；force:true（立即终止）不走此标志。
-     */
-    closeAfterRound?: boolean;
-    endedAt: number | undefined;
-    result: string | undefined;
-    error: string | undefined;
-    /** 完整 AgentResult（含 usage/toolCalls，完成时填）。 */
-    agentResult: AgentResult | undefined;
-    /** session jsonl 文件名。session 创建成功后由 session-runner.run() 回填（窗口期内 undefined）。 */
-    sessionFile?: string;
-    /**
-     * [V2 决策 3] 子进程 pid（spawn 后由 session-runner 回填到内存 record）。
-     *
-     * 用于 lifecycle-manager 孤儿扫描（V2 §5.2 职责 4：父进程重启时按持久化 pid 扫收
-     * 上次崩溃遗留的孤儿）。本字段仅在内存记账，持久化留 Step 5（record
-     * 文件写入 pid + 启动时 scanOrphanProcesses 消费）。undefined = 尚未 spawn / 已退出。
-     * 向后兼容：旧 record 无此字段，按无 pid 处理（孤儿扫描跳过）。
-     */
-    pid?: number;
-    /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
-    patchFile?: string;
-    /** worktree 隔离时的 handle（仅 worktree:true 时存在；fork alone 无此字段）。 */
-    worktreeHandle?: WorktreeHandle;
-    /**
-     * [review round2] 该 record 创建时启用了 worktree 隔离（跨重启磁盘重建时从 session
-     * entry 的 worktree 标志恢复）。handle 本体不可序列化——跨重启后 worktreeHandle 恒
-     * undefined，续聊（冷路径 resume）须拒绝（防 cwd 静默回落主 repo 破坏隔离）。仅内存
-     * record 使用，与持久化无关；execute() 新建 record 不设（有真 handle 时无意义）。
-     */
-    hadWorktree?: boolean;
-    controller: AbortController | undefined;
-}
-/**
- * Tool 返回的 details（内层扁平结构）。
- * 由 project(record) 唯一产出——sync/bg 两路径字段一致。
- * 含 mode + sessionFile（供外层 SubagentToolResult 分组 + spinner 判断）。
- *
- * 分层（spec FR-3）：此为**内层**，不感知 action/外层分组。
- * 外层 SubagentToolResult 由 adapter 包裹产出（加 action/subagentId/sessionFile + 分组）。
- */
-interface SubagentToolDetails {
-    status: ExecutionStatus;
-    /**
-     * 终态三态对外语义（U3 C-outcome，projectOutcome 唯一出口）。running → undefined；
-     * 历史数据无 outcome 字段时兜底派生（见 ProjectedOutcome）。
-     */
-    outcome?: ProjectedOutcome;
-    mode: ExecutionMode;
-    agent: string;
-    model: string;
-    thinkingLevel: string | undefined;
-    /** 短标签（≤35 字符），来自 record.slug。旧 record 反序列化时为空串。 */
-    slug: string;
-    turns: number;
-    totalTokens: number;
-    elapsedSeconds: number;
-    eventLog: AgentEventLogEntry[];
-    /** [STEP3] 从 turns[] 派生的展示项（对齐 nicobailon getDisplayItems）。 */
-    displayItems: DisplayItem[];
-    result?: string;
-    error?: string;
-    /** running 时的当前活动行（tool/thinking/text 优先级）。 */
-    currentActivity?: {
-        type: "tool" | "text" | "thinking";
-        label: string;
-    };
-    /** schema 模式下，structured-output tool 的 result.details（对齐 workflow agent-pool）。 */
-    parsedOutput?: unknown;
-    /** session jsonl 文件名（不含目录）。窗口期内可能 undefined（session 尚未创建成功）。 */
-    sessionFile?: string;
-    /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
-    patchFile?: string;
-}
-/** Hub.execute 的入参（sync/bg 共用）。mode 由 Hub 内部判定，不暴露给调用方。 */
-interface ExecuteOptions {
-    task: string;
-    /**
-     * 短标签（≤35 字符），简述本次执行用途，展示在 TUI。必填。
-     * workflow 内 agent() 调用时从 AgentCallOpts.description 透传而来。
-     */
-    slug: string;
-    agent?: string;
-    model?: string;
-    thinkingLevel?: string;
-    skillPath?: string;
-    appendSystemPrompt?: string[];
-    schema?: Record<string, unknown>;
-    /** D-A6 bridge: workflow schemaEnv 经 ExecuteOptions 透传到 runSpawn childEnv。 */
-    schemaEnv?: string;
-    /**
-     * Turn 上限 limiter。显式 0/负 = 显式不限：压过 SPAWN_WATCHDOG_ENV 兑底不挂
-     * watchdog（SP-6 参数 > env，U5）；undefined 未传才由 env 兑底。
-     */
-    maxTurns?: number;
-    graceTurns?: number;
-    /** sync 模式来自 Pi tool 框架；background 模式 hub 忽略，自建 controller。 */
-    signal?: AbortSignal;
-    /** 主 agent 当前模型（模型解析第三层兼底）。execute 调用方从 ctx.model 传入。 */
-    ctxModel?: ModelInfo;
-    /** background 完成回调（sync 不调）。 */
-    onComplete?: (record: RecordSnapshot) => void;
-    /** 是否继承父会话上下文（fork 模式，只继承上下文）。 */
-    fork?: boolean;
-    /**
-     * [v8.5 B] fork-from 显式指定继承源 session 文件（非主 session）。
-     * 与 fork:true 的区别：fork:true 用主 session 作 --fork 源；本字段用任意已有
-     * session 文件（断联 subagent 接续场景）作源。优先级高于 fork；传了本字段时
-     * fork 取值不影响 spawn 参数。仅 pi 引擎支持（同 fork）。仅 background tool
-     * 层 fork-from action 使用；workflow / executeAndAwait 不消费。
-     */
-    forkFromSessionFile?: string;
-    /** 文件系统隔离：true=创建新 git worktree，WorktreeHandle=复用外部已创建的；undefined=不隔离（parent cwd）。 */
-    worktree?: boolean | WorktreeHandle;
-    /** 覆盖执行 cwd（默认 mainCwd）。 */
-    cwd?: string;
-    /**
-     * 可持续对话模式（决策 8：独立 chatMode 标志，不扩展 ExecutionMode）。
-     * true = record 标记 chatMode，轮次完成进 idle 态（保留 record + worktree，等待 message 续聊）；
-     * 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。
-     * 显式传 0/负数 = 禁用 idle GC（不挂 timer；旧实现 0 会落成 setTimeout(0) 立即 kill）。
-     */
-    idleTimeoutMs?: number;
-    /**
-     * 实际执行引擎 id（P4 路由留痕）：pi 引擎由 PiEngine.run 在还原 opts 时写入；
-     * 缺省（历史调用方不设）= pi 投影。createRecordForMode 读入 record identity。
-     */
-    engine?: string;
-    /**
-     * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎时由路由层写入）。
-     * from = 请求引擎 id，reason 恒 'engine_probe_failed'（GUI 警告条数据源）。
-     */
-    engineFallback?: {
-        from: string;
-        reason: string;
-    };
-}
-/**
- * execute 返回值。
- *   background: { mode:"background", subagentId, sessionFile, details } —— 立即返回。
- *            subagentId 供后续 cancel/list 用；sessionFile 窗口期可能 undefined。
- */
-type ExecutionHandle = {
-    mode: "background";
-    subagentId: string;
-    sessionFile: string | undefined;
-    details: SubagentToolDetails;
-};
-/** list 的 item 结构。 */
-interface SubagentListItem {
-    subagentId: string;
-    agent: string;
-    /** 短标签（≤35 字符），来自 record.slug。旧 record 反序列化时为空串。 */
-    slug: string;
-    /** 对外四态（决策 10 细则 3，主字段）。由 mapExternalState(status) 派生。 */
-    state: ExternalState;
-    /** 原始内部状态（调试用，供 details 展示）。 */
-    status: ExecutionStatus;
-    mode: ExecutionMode;
-    /** 运行秒数（running 态实时计算，终态 endedAt-startedAt）。 */
-    duration: number;
-    model: string;
-    totalTokens: number;
-    /** session jsonl 文件名（窗口期内可能 undefined）。 */
-    sessionFile?: string;
-    /** 直接父 subagent record ID（顶层 record 为 undefined）。[v4 A-6] 从
-     *  record.parentRecordId 派生，配合 A-5 直接父守卫（message/close 仅作用于直接子）。 */
-    parent?: string;
-    /** 可冷路径 resume（running 且无活进程句柄）。[v4 A-6] B-1「可续聊」对外表达，
-     *  agent 据 list 判断哪些 running subagent 实际可续聊（vs 正在忙）。 */
-    resumable?: boolean;
-    /**
-     * 终态三态对外语义（U3 C-outcome 一等披露，projectOutcome 唯一出口）：
-     * completed / failed / cancelled，历史 record 无 outcome 字段时兜底派生，
-     * 不可判读的存量形态为 "closed-legacy"。GUI pane / agent 据此判读成败，
-     * 无需翻 error 字段原文（S5）。
-     */
-    outcome?: ProjectedOutcome;
-}
-/** background 启动的内层响应（挂在 SubagentToolResult.bgResponse）。 */
-interface BgResponse {
-    status: "running";
-    mode: "background";
-    /** 启动提示文案（"detached, will notify on completion"）。 */
-    message: string;
-    /**
-     * 终态三态语义（U3 C-outcome 对外 JSON 契约完备位）。start 时点 record 尚未终态，
-     * 恒 undefined（JSON.stringify 落键省略）；终态成败语义经 list items[].outcome
-     * 披露。旧字段 status/mode/message 原样保留（向后兼容）。
-     */
-    outcome?: ProjectedOutcome;
-    /**
-     * 通知投递契约回显位（U1 预置，U2 通知账本的契约声明）。恒值
-     * "ledger+at-least-once"：主 agent 在当前 run 结束或有限延迟内收到完成通知，
-     * 送达保证为 at-least-once + notifyId 幂等可识别。字段与填充由 U1 负责，
-     * 值语义由 U2（execution/notify-ledger.ts）兑现。
-     */
-    notifyContract: "ledger+at-least-once";
-    /**
-     * 同步收集登记回显段（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 {
-    /** items 中 status==="running" 的计数（受 limit 截断如实反映，非全局总数）。 */
-    running: number;
-    items: SubagentListItem[];
-}
-/** cancel 的内层响应（挂在 SubagentToolResult.cancelResponse）。 */
-interface CancelResponse {
-    cancelled: true;
-}
-/**
- * message 的内层响应（挂在 SubagentToolResult.messageResponse，决策 10 瘦身）。
- *
- * [R1 删除记录] 旧 PendingMessage（在途消息缓存条目，消费确认制，设计决策 6 状态×
- * interrupt 映射）已随 deliverToRunning 一并删除——SP-5 upgrade 后无生产调用方，
- * 配套三段消费链（push / message_start shift / redeliverPending 补投）全部不可达。
- * 详见 subagent-service.ts 的删除记录注释。
- */
-interface MessageResponse {
-    delivered: true;
-}
-/** close 的内层响应（挂在 SubagentToolResult.closeResponse，决策 10 瘦身）。 */
-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）。 */
-interface ForkFromResponse {
-    /** 新 subagent record id（接续对话用 action:'message'）。 */
-    newSubagentId: string;
-    /** 作为继承源的旧 subagent session jsonl 绝对路径。 */
-    sourceSessionFile: string;
-}
-/** /subagents list 左列展示单元。来自内存(running) 或 session.jsonl 重建(终态)。 */
-interface SubagentRecord {
-    id: string;
-    agent: string;
-    /** 任务提示词（详情面板置顶展示）。磁盘/内存源均有。 */
-    task: string;
-    /** 短标签（≤35 字符）。磁盘重建源旧文件可能缺失→兜底空串。 */
-    slug: string;
-    status: ExecutionStatus;
-    /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。SP-1 新增。 */
-    closedReason?: ClosedReason;
-    /** 终态三态对外语义（U3 C-outcome）。磁盘重建源一等直读；无字段的存量兜底走 projectOutcome。 */
-    outcome?: ExecutionOutcome;
-    mode: ExecutionMode;
-    startedAt: number;
-    /** 根 Pi session ID（session 隔离过滤用）。递归链上所有层 record 同值。 */
-    rootSessionId: string | undefined;
-    /** 直接父 subagent record ID（层级树构建用）。顶层 record 为 undefined。 */
-    parentRecordId: string | undefined;
-    /** subagent 递归深度。顶层 =0，每层嵌套 +1。 */
-    depth: number;
-    endedAt: number | undefined;
-    turns: number;
-    totalTokens: number;
-    model: string;
-    thinkingLevel: string | undefined;
-    eventLog: AgentEventLogEntry[];
-    /** [STEP3] 从 turns[] 派生的展示项（对齐 nicobailon getDisplayItems）。 */
-    displayItems: DisplayItem[];
-    /** running 时的当前活动行（仅内存源；磁盘重建无此数据）。streaming 可观测性用。 */
-    currentActivity?: {
-        type: "tool" | "text" | "thinking";
-        label: string;
-    };
-    result?: string;
-    error?: string;
-    sessionFile?: string;
-    /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
-    patchFile?: string;
-    /**
-     * [review round2] 创建时启用 worktree 隔离（磁盘重建源从 session entry 恢复；内存源由
-     * recordToSubagent 从 worktreeHandle 投影）。getRecordForAction 跨重启重建时据此拒绝续聊。
-     */
-    worktree?: boolean;
-    /**
-     * 对话轮次计数（仅 chatMode idle record 有意义）。round 仅在内存维护（doFinalizeRoundToIdle
-     * 递增），跨重启不恢复（round 无磁盘持久化）；非对话模式 / 非 idle record 为 undefined。内存源由 recordToSubagent 从
-     * ExecutionRecord.round 投影。
-     */
-    round?: number;
-    /**
-     * 对话模式标志（与 ExecutionRecord.chatMode 同义；投影给 GUI 侧 streaming/waiting/done
-     * 细分判据——one-shot 轮终（chatMode 非 true + result 有值）显示完成态，chat 轮终显示
-     * 等续聊。内存源由 recordToSubagent 投影，磁盘源经 subagent-record entry 重建）。
-     */
-    chatMode?: boolean;
-    /**
-     * 执行态信号（与 ExecutionRecord.resumable 同义）：true = 无活进程驱动的 running
-     * （轮终 idle / 重建孤儿兜底），GUI 侧据此排除「真在跑」判定。
-     */
-    resumable?: boolean;
-    /** 外部 Pi 实例（进程隔离模式下由外部启动的子进程）。 */
-    externalInstance?: AliveMarker;
-    /** fork 模式下的 worktree handle。 */
-    worktreeHandle?: WorktreeHandle;
-    /**
-     * 实际执行引擎 id（P4 路由留痕）。缺省 = pi 投影（存量 record 零迁移）；
-     * GUI 警告条/引擎标记的数据源之一。
-     */
-    engine?: string;
-    /** 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源。 */
-    engineFallback?: {
-        from: string;
-        reason: string;
-    };
-    /**
-     * 引擎自描述定位符（U1：EngineHandleData 的持久化消费面子集，引擎无关——
-     * sessionRef 整体透传不枚举内部键）。read 降级链①②级的数据源（runtime
-     * subagent-engine-history）；缺省 = pi（走 JSONL 直读链）。
-     */
-    engineHandle?: {
-        sessionRef: Record<string, string>;
-        journalPath?: string;
-        poolKey: string;
-    };
-    /**
-     * 同步收集模式标记（与 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）。
- *
- * 模型解析已退化为「主 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;
-}
-
-/**
- * 引擎会话句柄（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 EngineHandle {
-    /** 持久化数据。上层不得解构其内部字段（见契约三条）。 */
-    readonly data: EngineHandleData;
-}
-
-/**
- * subagent text_delta streaming sink。
- *
- * background subagent 执行期间，session-runner 的 agentEvent 出口把每个 text_delta
- * 传到 SubagentStream.onDelta。本模块做 100ms 时间窗合并后，通过 StreamSink.setWidget
- * 转发到 RPC stdout（经 ctx.ui.setWidget → extension_ui_request 通道）。
- *
- * 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
- */
-
-/** 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;
-}
-/**
- * subagent text_delta streaming 生命周期对象。
- *
- * 创建后：
- * - `onDelta(delta)`：session-runner 每次 text_delta 调
- * - `dispose()`：subagent 终态时调，清除 widget + 清 timer
- *
- * buffer/timer 状态全部内聚在此对象，调用方不需要关心合并逻辑。
- */
-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;
-}
-
-/**
- * run 的运行期上下文。任务声明（AgentCallOpts，D6 合流后的单一形状）与运行期句柄
- * 分离——signal/ctxModel/onComplete 从 ExecuteOptions 移出（设计 §3.3.5 删字段去向），
- * 因为它们是宿主注入的运行期对象，不属于跨引擎持久化的任务声明。
- *
- * 常驻进程友好（D1）：onEvent 回调式（而非迭代器式）+ AbortSignal——引擎内部换常驻
- * server 实现（未来 driver host）时接口不动。
- */
-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;
-    /**
-     * text_delta streaming 通道（宿主侧 UI widget）。与 onEvent 平行的 text_delta 出口：
-     * background 路径 onEvent=undefined 但流式仍需送达（双通道互斥设计，见 session-runner
-     * agentEvent 出口注释）。pi 回填期承载 AgentRunner port 的 stream 透传（行为零变化），
-     * 语义上是宿主设施而非引擎专有——未来引擎的 text_delta 同样可走此通道。
-     */
-    stream?: SubagentStream;
-    /**
-     * [P1 pi 回填透传] 调用方已持有的 schema 激活预编码值（AgentCallOpts.schemaEnv 直传
-     * 形态）。生产路径中 resolveAgentOpts 恒耦合产出 schema+schemaEnv（值 = JSON.stringify
-     * (schema)），引擎从 task.schema 派生即可逐字节等值；解耦形态（有 schemaEnv 无
-     * schema）生产不可达、仅见于直构调用，派生无源——本字段是其唯一透交通道。
-     * 引擎在 task.schema 存在时忽略此值（派生优先，设计 §3.3.5 删字段去向）。
-     */
-    schemaEnv?: string;
-    /**
-     * [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;
-}
-/**
- * [W3 v1.x] chat 轮次反向通道路由（recordId 键）——interact 续聊轮的 streamDelta /
- * roundLifecycle 分发目标（协议关联键裁定 D1-A：续聊轮无独立 runId）。与 run 作用域
- * RunRoute 同构的薄消费面；注册/注销时机归宿主 chat 编排（轮开始注册、record 终态注销）。
- */
-interface ChatRoundRoute {
-    onStreamDelta?: (delta: string) => void | Promise<void>;
-    onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void | Promise<void>;
-}
-/**
- * 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 EngineRunResult {
-    handle: EngineHandle;
-    outcome: AgentOutcome;
-}
-/**
- * subagent 执行引擎的唯一契约点（D1）。实现方：PiEngine（回填）/ ZcodeEngine（P3）/
- * 未来各引擎适配器。上层（工具面/workflow 引擎/GUI）只消费中立类型，不感知引擎。
- *
- * 贯穿纪律（设计 §3.3.1）：宿主编排——引擎只当单 agent 执行器，六家原生多 agent 机制
- * 一律禁用不依赖。
- */
-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（同步拒绝、不创建进程）。
-     */
-    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 终态时宿主调用）。
-     */
-    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;
-    };
-    /**
-     * [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;
-/**
- * 引擎包 manifest 注册期快照（session_start 扫描所得，非握手缓存——设计 §3.3「同步
- * 成员清单」单一同步源原则）。descriptor 携带，cli 形态 port（RemoteEngine）的同步
- * 成员（capabilities/listModels/validateModel）直读本快照。
- *
- * 与 client/remote-engine.ts 的 RemoteEngineManifestSnapshot 是结构闭包（后者多出
- * core 中立类型包装；漂移由 protocol-closure 同族结构互证断言守卫）。
- */
-interface EngineManifestSnapshot {
-    /** manifest `capabilities`（同步能力位权威，注册期读，无缓存）。 */
-    capabilities: EngineCapabilities;
-    /**
-     * manifest `modelCatalog` 三态（W4 §2.4：缺省 = 不注入保持 undefined；null 合法等价
-     * 省略；`models: []` 仅作者显式声明）。解析器不得把省略填成 `[]`——否则「无枚举面」
-     * 语义不可达。
-     */
-    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 代理形态：缺包/坏包的失败推迟到首次协议调用）。
-     */
-    portFactory: EngineFactory;
-    /** manifest 快照余项（modelCatalog/displayName；capabilities 已提升为直读字段）。 */
-    manifest?: Omit<EngineManifestSnapshot, "capabilities">;
-}
-/**
- * 缺省引擎 id（D4 重定义：**配置的缺省引擎 id**——config defaultEngine 未配置时的
- * 归一名，不再表达「内置 pi 永久兜底」）。配置值不在已发现清单 → warn + 回落第一个
- * 可用引擎（manifest displayName 稳定序，D4）；全不可用 → 派发期 engine_not_found
- * （「未发现任何引擎包」+ 安装指引）。
- */
-declare const DEFAULT_ENGINE_ID = "pi";
-/**
- * defaultEngine 缺省归一（单一权威源）：空白 / undefined 归一到缺省引擎（'pi'）。
- * 引擎感知检测 diff 与状态段渲染必须对同一读取结果给出同一引擎 id——若两处各自
- * 内联归一，一致性只靠注释人工耦合，漂移即两处说谎；故收敛到本函数供各处调用。
- * sanitize 保证透传值非空，但可能带首尾空格，故 trim 后再判。
- */
-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;
-}
-/**
- * 检查单个候选包目录（读 package.json → manifest 字段级解析 → bin 可执行验证）。
- * 三态：ok（装载）/ skip（必需字段缺失/不可解析——warn 跳过该包）/ unusable
- * （protocol 不兼容、bin 不可执行——标记不可用，不进清单）。
- */
-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[];
-/**
- * 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 缺席。
- */
-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;
-}
-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;
-/**
- * 扫描 + 装载：descriptor 经 registerEngineDescriptor 进注册表（幂等覆盖——重复扫描
- * 安全）。装载覆盖既有注册（含过渡期 inproc pi/zcode——auto 模式下 cli descriptor
- * 胜出即设计 D3 语义）时 debug 留痕。
- */
-declare function discoverAndRegisterEngines(opts: DiscoverEnginesOptions): DiscoveryScanResult;
-/**
- * 历史发现装载的引擎 id 快照（投影源计算消费面，见 engine-discovery.ts）。
- */
-declare function loadedDiscoveryIds(): string[];
-/**
- * hasEngine 的补扫面（§3.4 发现时机：快照未命中触发一次同步补扫，只读 manifest
- * 不握手）。消费方 = agent 解析期/路由期的存在性校验接线（宿主侧注入 hasEngineFn
- * 时用本函数替代裸 hasEngine）——「装了包 → 下次解析即可用」。
- */
-declare function ensureEngineDiscovered(id: string, opts: DiscoverEnginesOptions): boolean;
-
-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 };