@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -1,50 +1,15 @@
-import { ChildProcess } from 'node:child_process';
-import { E as EngineCapabilities, P as ProbeReport, A as AgentCallOpts, a as AgentEvent, M as ModelInfo, b as EngineHandleData, c as EngineHandle, d as AgentOutcome, I as InteractAction, e as InteractResult, S as SessionView, f as ExecutionRecord, R as RecordSnapshot, g as SubagentRecord, h as ExecuteOptions, i as AgentResult, j as AgentConfig, k as ResolvedModel, l as AgentResult$1, C as ClosedReason, m as ExecutionOutcome, T as ToolCall, n as AgentEventLogEntry, o as ExecutionStatus, p as ProjectedOutcome, q as SubagentsGlobalConfig, r as ModelRegistryLike, s as ExecutionHandle, t as ExecutionMode, W as WorktreeHandle, u as PatchResult, v as AgentUsage, w as ExecutionTraceNode, x as TracePatch, y as RunStatus, D as DoneReason, z as WorkerLogEntry, B as DisplayItem, F as CancelResponse, G as CloseResponse, H as ForkFromResponse, L as ListResponse, J as MessageResponse, K as BgResponse, N as ExternalState, O as SubagentListItem } from './types-C3fE3R9x.cjs';
-export { Q as CLOSED_REASONS, U as DEFAULT_AGENT_NAME, V as DirtyWorktreeError, X as ForkDepthExceededError, Y as ReplayedTurn, Z as ResurrectDeniedError, _ as SLUG_MAX_LENGTH, $ as SubagentToolResult, a0 as ToolCallEntry } from './types-C3fE3R9x.cjs';
+import { E as EnginePort, D as DiscoverEnginesOptions, a as ExecutionRecord, C as ClosedReason, b as ExecutionOutcome, A as AgentEventLogEntry, c as ExecutionStatus, P as ProjectedOutcome, R as RecordSnapshot, S as SubagentRecord, d as ExecuteOptions, e as SubagentStream, f as AgentResult, g as AgentResult$1, h as SubagentsGlobalConfig, M as ModelRegistryLike, i as ModelInfo, j as AgentConfig, k as ResolvedModel, l as StreamSink, m as ExecutionHandle, n as ExecutionMode, o as PatchResult, p as AgentCallOpts, q as ExecutionTraceNode, T as TracePatch, r as RunStatus, s as DoneReason, W as WorkerLogEntry, t as DisplayItem, u as CancelResponse, v as CloseResponse, F as ForkFromResponse, L as ListResponse, w as MessageResponse, B as BgResponse, x as ExternalState, y as SubagentListItem, z as DiscoveryRoot } from './engine-discovery-scan-ocpM8FmI.cjs';
+export { G as CLOSED_REASONS, H as CoreLogger, I as DEFAULT_AGENT_NAME, J as DEFAULT_DATA_ROOT, K as DEFAULT_ENGINE_ID, N as DirtyWorktreeError, O as EngineHandle, Q as EngineRunResult, U as ForkDepthExceededError, V as HostServices, X as LogLevel, Y as ResurrectDeniedError, Z as RunContext, _ as SLUG_MAX_LENGTH, $ as SubagentToolResult, a0 as configureCore, a1 as getHostServices, a2 as getLogger, a3 as normalizeEngineId } from './engine-discovery-scan-ocpM8FmI.cjs';
+import { ProbeReport, SessionView, ToolCall, UiRequest, UiRequestHandler, UiResponse, AgentEvent, UiChannelRegistry, WorktreeHandle, AgentOutcomeUsage } from '@zhushanwen/subagent-engine-sdk';
+export { AgentEvent, AgentOutcome, ChannelHandler, EngineCapabilities, EngineHandleData, InteractAction, InteractResult, ProbeReport, ReplayedTurn, SessionView, ToolCallEntry, UiChannelRegistry } from '@zhushanwen/subagent-engine-sdk';
 import { Worker } from 'node:worker_threads';
-export { ZCODE_FALLBACK_DEFAULT_MODEL } from './execution/engine/engines/zcode/constants.cjs';
+import 'node:child_process';
 import '@xyz-agent/extension-protocol';
 
 /** thinking level 支持顺序（低→高）。spawn 侧 `:level` 后缀仅接受本白名单值。 */
 declare const THINKING_ORDER: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 
-/** 日志级别。对齐 @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 统一。 */
-    discoveryRoots?(): {
-        agents?: DiscoveryRoot[];
-        skills?: DiscoveryRoot[];
-        workflows?: DiscoveryRoot[];
-    };
-}
-/** core 缺省数据根（~/.subagent-core，homedir 推导——禁止写死绝对路径，排查规则）。
- *  供无自有数据根的轻宿主显式采用；core 自身不静默兜底到该值。 */
-declare const DEFAULT_DATA_ROOT: string;
-declare function configureCore(host: HostServices): void;
-declare function getHostServices(): HostServices;
+type ExtensionMode = "tui" | "rpc" | "json" | "print";
 
 /** 投递意图（与 session-delivery 的 DeliveryIntent 字面量一致）。 */
 type DeliveryIntent = "interrupt-at-turn-boundary" | "after-run";
@@ -118,229 +83,33 @@ interface DeliveryHandle {
     /** 销毁（清队列 + 清 timer + 退订）。 */
     dispose(): void;
 }
+/** countActiveFromEntries 的过滤选项（[F1] 与 pending-notifications 的
+ *  CountActiveOptions 对齐的子集——core 契约面只暴露跨 session 基准一个字段）。 */
+interface CountActivePortOptions {
+    /**
+     * [W4 读侧过滤②] 跨 session 残留过滤基准：传入时端口实现按「register entry 的
+     * sessionId ≠ 基准 → 跳过」过滤——fork 继承的父级注册残留（翻 process 档后 U4
+     * 补注销不再中性化，永久留存于子 session 文件）不进差集。
+     * 缺省（undefined）= 不过滤（向后兼容：既有调用方零改动行为不变）。
+     */
+    currentSessionId?: string;
+}
 interface NotifyDomainPorts {
     /** pending 活跃计数（pi 会话 entries 中 register − unregister 差集的数值）。
      *  契约为 number 而非 pi 侧 CountActiveResult：core 消费面只读 count，契约面最窄；
-     *  pi 壳注入时拆 `countActiveFromEntries(entries).count`。 */
-    countActiveFromEntries?(entries: unknown[]): number;
+     *  pi 壳注入时拆 `countActiveFromEntries(entries).count`。
+     *  [F1] 第二参为可选过滤基准（CountActivePortOptions）——core 消费方（后代判定
+     *  读侧）持有「被读 entries 所属 session」概念时必须传入，使跨 session 残留不进
+     *  差集；与 pending-notifications 实装签名（entries, opts?) 对齐。 */
+    countActiveFromEntries?(entries: unknown[], opts?: CountActivePortOptions): number;
     /** 投递内核工厂。签名与 @xyz-agent/session-delivery 的 createDelivery 结构兼容，
      *  pi 壳直传其本体即可。缺席 = 消费方降级直发。 */
     createDelivery?(port: DeliveryPort, options?: DeliveryConfig): DeliveryHandle;
 }
 declare function configureNotifyDomain(ports: NotifyDomainPorts): void;
 
-type ExtensionMode = "tui" | "rpc" | "json" | "print";
-
-/**
- * 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;
-}
-/**
- * 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>;
-    /**
-     * [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 全名供
-     * record.model 留痕。
-     *
-     * 未实现：model 透传，引擎自身 prepare 期校验兜底（现状语义）；pi 不实现（pi 链走
-     * 既有三层解析 + assertCanonicalModelRef 裁决，搬迁是大重构，设计 D2-2 被否②）。
-     */
-    validateModel?(modelRef: string | undefined): {
-        canonicalRef: string;
-    };
-    /**
-     * [R1 D6] 可选停机面：释放引擎持有的常驻资源（如 app-server 常驻进程 / 长连接）。
-     * 幂等契约（§3.4 不变量 4）：重复调用无副作用；dispose 后首个 run 自动重建（与
-     * 「进程死后重建」同一代码路径）。可选成员保持向后兼容——无常驻资源的引擎（pi
-     * 现状 spawn 单轮）不必实现。等待策略（D6①「触发不等待」）：宿主收割入口
-     * （registry disposeEngines → killAllSpawnedChildren）只同步调用拿 Promise 不
-     * await，引擎实现须自行保证同步面（立即 fire close 帧 + 同步 SIGTERM）在返回
-     * Promise 前完成；grace→SIGKILL 升级序列属异步面（promise 段）。
-     */
-    dispose?(): Promise<void>;
-}
-
+/** 宿主接线：登记补扫发现参数（与发现扫描同源；重复登记覆盖，幂等）。 */
+declare function setEngineDiscoveryRescanOptions(opts: DiscoverEnginesOptions): void;
 /** 三层路由的输入（各层值由调用方装配；undefined = 该层不指定）。 */
 interface EngineRoutingInput {
     /** 第一层：调用参数 engine（workflow step 级 / AgentCallOpts.engine）。 */
@@ -376,6 +145,12 @@ interface EngineRouteOptions {
     hasEngineFn?: (engineId: string) => boolean;
     /** 注册表清单（缺省 registry.listEngines——engine_not_found 文案的数据源）。 */
     listEnginesFn?: () => string[];
+    /**
+     * 可用引擎清单（D4 回落目标序：manifest displayName 稳定序；缺省
+     * registry.listEnginesByDisplayName）。清单内 id 即视为可用（发现且已注册）——
+     * 调用方负责排序口径；routeEngine 按序取第一个 ≠ 请求引擎的 id 作回落目标。
+     */
+    listAvailableEnginesFn?: () => string[];
 }
 interface EngineRouteResult {
     engine: EnginePort;
@@ -395,1332 +170,875 @@ interface EngineRouteResult {
  * 路由 + 探针 + fallback 编排（SAR run 入口调用）。
  *
  * 失败形态（全部抛结构化错误，调用方转 AgentResult.error）：
- *   - 未注册 id（调用参数层漏网）：EngineNotFoundError（engine_not_found）
+ *   - 未注册 id（call/frontmatter 层）：EngineNotFoundError（engine_not_found）
+ *   - default 层缺省引擎不在清单且无任何可用引擎：EngineNotFoundError
+ *     （「未发现任何引擎包」+ 安装指引，D4）
  *   - strict 或守卫命中：EngineError(engine_probe_failed)
  *   - 守卫 c（显式 model + 将换引擎）：EngineError(model_not_available)
  */
 declare function routeEngine(opts: EngineRouteOptions): Promise<EngineRouteResult>;
 
 /**
- * 把注册表引擎列表同步到 engines.json（session_start 时调用）。
+ * 三级发现装载 + 把引擎清单同步到 engines.json（session_start 时调用）。
+ *
+ * 发现时机（W4 §2.4）：与 syncEnginesFile 同点——扩展组合根的模块加载点与
+ * session_start 兜底点即本函数既有调用点（调用方零改动），扫描一次 + 装载进注册表
+ * （装载结果即缓存）；只读 manifest 不握手（portFactory 惰性，扫描不 spawn 引擎）。
+ *
+ * 投影源（§3.4 投影面表「清单 = 已发现且可执行」）= 本次发现装载结果 ∪ inproc 过渡
+ * 注册快照（listEngines() 剔除历史发现装载的 id——registry 无撤销 API，引擎包卸载
+ * 后已装载 descriptor 会滞留，投影时经 loadedDiscoveryIds 排除即「卸载 → 下次扫描
+ * 自动消失」清理通道；A4 新引擎装包零改 core 出现在清单）。W11 删 inproc 后清单 =
+ * 纯发现结果（零命中 → 空清单，GUI 按既有语义给 engine_not_found + 安装指引）。
  *
  * 幂等：内容与现文件一致时零写入（mtime 不动——读侧无谓失效）；写入走 tmp+rename
  * 原子替换（shared/atomic-write 统一原语，U6b 迁移——与池 config 同防线）。
- * fail-safe：任何 IO 异常吞掉（可发现性降级不阻塞
- * session 启动——GUI 兜底显示 ['pi']）。
+ * fail-safe：发现与 IO 异常都吞掉（可发现性降级不阻塞 session 启动——GUI 兜底显示
+ * 既有清单）。
  */
 declare function syncEnginesFile(agentDir: string): void;
 
-interface ManifestRecord {
-    id: string;
-    rootSessionId: string;
-    /** 直接父 subagent record ID（层级树构建用）。顶层 record 缺失（undefined）。M3a 补字段。 */
-    parentRecordId?: string;
-    agentName: string;
-    /**
-     * 终态枚举：finalizeRecord 写 running/closed/cancelled 三态。
-     * SP-1 重构：旧 completed/failed 合并为 closed（L1 统一终态）。
-     * cancelled 保持独立（用户取消语义）。crashed 不进 manifest——
-     * crashed 是重启重建时靠 sidecar 四分支推断的派生态（见 record-store.ts reconstructAll）。
-     * 历史 "error"/"completed"/"failed" 值由读侧 mapManifestStatus 向后兼容映射。
-     */
-    status: "running" | "closed" | "cancelled";
-    createdAt: number;
-    completedAt?: number;
-    sessionFile?: string;
-    /** FR-7 补字段：manifest 写入时从 ExecutionRecord 抓取，供 manifestToSubagent 投影真实值。 */
-    task?: string;
-    slug?: string;
-    model?: string;
-}
-declare class ManifestStore {
-    private readonly dir;
-    /** [perf] per-file 缓存：file → { stamp, record }。record=null 表示「已解析但非法」（缓存
-     *  负结果避免反复 parse 损坏文件）。stat 戳变化（writeManifest tmp→rename 后 mtime/size 变）
-     *  自动失效；删除的文件在下次扫描时修剪。 */
-    private readonly cache;
-    constructor(dir: string);
-    /**
-     * 原子写：tmp → fsync → rename → fsync dir（shared/atomic-write 统一原语，
-     * U6b 迁移——原逐行实现与 writeAtomicFile 逐环等值）。真异步（fs.promises，
-     * 不阻塞 event loop）。
-     *
-     * 失败时原语尽力清理残留 tmp（debug 记录，不掩盖原错误）并原样上抛——
-     * 调用方（finalizeRecord）决定降级策略。
-     */
-    writeManifest(record: ManifestRecord): Promise<void>;
-    /**
-     * 按 id 读 manifest。文件不存在/JSON 损坏/schema 不合法均返回 null。
-     * 调用方需处理 null。
-     */
-    readManifest(id: string): Promise<ManifestRecord | null>;
-    /**
-     * 同步读取所有 manifest 记录（best-effort，损坏/非法文件跳过）。
-     * 供 RecordStore.collectRecords 投影 orphan 记录使用——替代对私有 dir 的反射访问。
-     * 仅返回通过 isValidManifest 校验的记录。
-     *
-     * [perf] per-file 缓存 + stat 戳校验：collectRecords 每次渲染都调本方法，旧实现每次
-     * 全量 readFileSync + JSON.parse 千级 manifest（实测 ~300ms/次）。命中缓存的文件零读取。
-     */
-    listAllSync(): readonly ManifestRecord[];
-    /**
-     * 启动时恢复 tmp 文件。
-     * 3 分支逻辑：
-     * 1. manifest 已存在 → 删 tmp（陈旧）
-     * 2. tmp 合法 + manifest 缺失 → rename tmp 为 manifest
-     * 3. tmp 非法 + manifest 缺失 → 删 tmp
-     *
-     * [T5④ / PS-13] per-file 容错：单个 tmp 文件操作失败（ENOENT——并发回收/外部清理
-     * 抢先、EACCES 等）只 warn + 跳过该文件，不再中断整轮——旧实现单文件 ENOENT 即抛，
-     * 剩余 tmp 本轮不再处理，自愈但不可见（残留顺延下次启动）。跳过数经 warn 汇总留痕，
-     * 调用方返回值形态不变（跳过者不计数）。
-     */
-    recoverTmpFiles(): Promise<{
-        deleted: number;
-        recovered: number;
-    }>;
-}
+/**
+ * 单 record 终止记账（镜像置死位）：实际终止在引擎进程内（协议 interact cancel /
+ * close 或 run 域 cancel 帧承载）；宿主侧调用点是终止意图的记账面，宿主进程组级
+ * 收割兜底 = EngineClient killAll（EnginePort.dispose / abort 杀链，见 remote-engine）。
+ */
+declare function killRecordChildWithEscalation(recordId: string, _source: string): void;
+/** 全量收割记账（dispose / parent-shutdown）：镜像整体置死。 */
+declare function killAllSpawnedChildren(_signal?: NodeJS.Signals): number;
 
-/** store 变更监听器（返回取消订阅函数）。 */
-type ChangeListener = () => void;
-/** status 过滤模式（collectRecords 的核心能力参数）。 */
-type StatusFilter = "running" | "all";
-/** Pi ExtensionAPI 的最小子集（仅 collectRecords 跳过损坏 manifest 时上报用）。
- *  解构为局部类型，避免与 subagent-service 的 PiLike 循环依赖。 */
-type RecordStorePi = {
-    appendEntry?: (customType: string, data: unknown) => void;
-} | null | undefined;
 /**
- * Record 容器。进程单例（随 SubagentService 重建）。
- *
- * 内存只留 running record——终态 record 在 archive 时立即移除，collectRecords
- * 读时从 sessions/*.jsonl 重建（[perf] light 头部扫描 + per-file 缓存）。
+ * D8 兼容 deps 形状（zsw runner-core.js:163 实测调用面 {engineDataDir, cliPath?}）。
+ * 与 engines/zcode ZcodeEngineDeps 结构兼容：zsw 传入对象可直接赋值；sources /
+ * probeVersion 为兼容残留字段——协议形态下不跨进程（忽略 + warn）。
+ */
+interface D8CompatZcodeEngineDeps {
+    /** 引擎数据根（→ 引擎子进程 env XYZ_AGENT_DATA_DIR，见设计 §3.6 注入矩阵）。 */
+    engineDataDir: () => string;
+    /** 引擎 CLI 入口覆盖（L3 等价；缺省 = vendored 相对定位）。 */
+    cliPath?: string;
+    /** 兼容残留：模型来源/凭据路径——不跨进程（不变量 5），忽略。 */
+    sources?: unknown;
+    /** 兼容残留：版本探测执行器——协议 probe 由引擎实现承担，忽略。 */
+    probeVersion?: unknown;
+    /** env 基底合并（buildEngineChildEnv baseEnv；缺省 {...process.env}）。 */
+    processEnv?: NodeJS.ProcessEnv;
+}
+/**
+ * [W11 收口] 旧 ZcodeEngineDeps 的兼容别名：barrel 原类型导出（zsw 调用面的 deps
+ * 形状契约）与 D8CompatZcodeEngineDeps 合并——结构同源（engineDataDir/cliPath/
+ * sources/probeVersion/processEnv），别名保留免 zsw 侧机械改名。
+ */
+type ZcodeEngineDeps = D8CompatZcodeEngineDeps;
+/**
+ * D8 薄壳：确保 id 'zcode' 的引擎 descriptor 已注册，engineDataDir 记入 descriptor。
  *
- * 任何 mutate → notifyChange()（仅通知监听器；磁盘缓存靠 stat 戳自校验，不清空）。
+ * 注册表已有 descriptor（W4 发现器先装载 / 重复调用）→ 直接保留——发现器 cli
+ * descriptor 携带完整 manifest 快照，权威高于薄壳构造。未注册 → vendored 定位构造
+ * cli descriptor（经 W4 inspectEnginePackage 全量 manifest 解析；engineDataDir 经
+ * 合成 env XYZ_AGENT_DATA_DIR 被 portFactory 捕获——「以显式值为准」）。[W11/DoD#5]
+ * 定位/解析失败保持未注册（inproc 回退已删，不变量 6「失败不静默」——派发期
+ * engine_not_found 显式报错 + 恢复指引；XYZ_ZCODE_CLI 覆盖通道由 createZcodeEngine
+ * 的 deps.cliPath 等价承载）。
+ */
+declare function registerZcodeEngine(engineDataDir?: () => string): void;
+/**
+ * D8 薄壳：deps → 协议客户端映射，返回 RemoteEngine('zcode')（implements EnginePort，
+ * 对 zsw 透传结构兼容）。构造同步、不 throw（§3.5.3 代理形态）——引擎包缺失时
+ * command = 期望路径，失败显式发生在首次协议调用（engine_crashed + 恢复指引）。
+ */
+declare function createZcodeEngine(deps: D8CompatZcodeEngineDeps): EnginePort;
+
+/** maxTurns → spawn watchdog 毫秒估算（floor 语义：maxTurns 小时取下限）。 */
+declare function maxTurnsToWatchdogMs(maxTurns: number): number;
+
+/**
+ * 恒在状态段 <current_subagent_engine>（设计 D6：pi 引擎也声明——AI 不需要
+ * 「从段缺失反推」当前引擎）。三种形态（§3.1 终态逐字基准 + 失败路径表）：
+ *   - 缺省 / pi：声明 pi + 指向上方核心段 <available_provider_models>（无冲突 bullet）；
+ *   - 非 pi 且已注册：指向下方该引擎清单段 + 「pi registry id 不适用」+ AGENTS.md
+ *     冲突裁决 bullet + 省略 model 用引擎默认；
+ *   - 未注册引擎（如配置手误 "ghost"）：如实显示配置值 + 警告行（派发将报
+ *     engine_not_found，指引修 subagents/config.json）——G4 诚实降级：不静默、不伪造。
  *
- * record 状态查询面（U10① D6）：按状态枚举 listRunning/collectRecords(statusFilter)、
- * 按 id 查询 getMutable/findLightById/getFullRecord——方法签名即导出形态，本类零改动。
+ * 字节稳定（D7）：纯字符串确定性拼装（无 localeCompare / 无随机序 / 无时间态）；
+ * 引擎注册与否经 hasEngine 只读判断（不取实例、不触发工厂副作用），同输入恒同输出。
+ */
+declare function buildSubagentEngineSection(defaultEngine: string | undefined): string;
+/**
+ * 依据全局 defaultEngine 生成追加段（不含前导换行）。
  *
- * @experimental execution 运行时面（设计 docs/design/subagent-core-sink-design.md §3.3 D6）：
- * 一个 minor 周期内允许签名微调，稳定后转常规 semver 承诺。
+ * 规则（设计 §3.1 失败路径表 + G4 + U2 一致性审查修订）：
+ *   - defaultEngine 为 pi / 缺省 → 不注入（pi 段已由核心提供）；
+ *   - 引擎未注册 → 不注入（状态段 <current_subagent_engine> 已有警告行，避免双份）；
+ *   - 已注册且 listModels 有清单 → 注入该引擎段（渲染不变）；
+ *   - 已注册但 listModels 未实现 / 返回 null → 「与主 agent 模型体系一致」声明段
+ *     （port 契约语义：引擎无自有 provider 枚举面，id 见上方核心段，见
+ *     buildCoreAlignedHint）；
+ *   - 已注册但空清单 / listModels 抛异常 → 「无凭据模型」提示行段（引擎 provider
+ *     体系存在但当前无可用模型，见 buildEmptyModelsHint；从「静默不注入」改为如实
+ *     声明——空清单返回空串会让 AI 误以为没有任何引擎清单可看）。
+ * fail-safe：listModels 异常同样落提示行段、不向外抛（注入失败不阻塞 agent loop——
+ * 与 system-prompt extension 的 before_agent_start 处置一致）。
  */
-declare class RecordStore {
-    private readonly sessionsDir;
-    private readonly manifestStore?;
-    private readonly records;
-    private readonly listeners;
-    private _disposed;
-    /** 孤儿终态恢复的已判定缓存（residual-fixes）：resumable 形态无 sidecar 锚，同进程重复调用跳过。 */
-    private orphanJudged;
-    /** Pi handle（用于 appendEntry 上报损坏 manifest）。构造时可空，setPi() 后续注入。
-     *  显式存为字段而非构造参数 readonly：setPi 需要写权限。 */
-    private pi;
-    /** [perf] per-file 缓存（key = sessionFile 绝对路径）。不再整体失效——stat 戳精准校验。
-     *  值含负缓存（确认无 identity 的文件），防每轮全文 fallback 重读。 */
-    private readonly fileCache;
-    /** record id → sessionFile 索引（getFullRecord 按 id 定位文件）。随 fileCache 同步维护。 */
-    private readonly idToFile;
-    /** [perf] sessionsDir 最近一次全量扫描的 mtime（快路径判变，见 reconstructAll）。
-     *  null = 未扫过 / 已 dispose。 */
-    private dirStamp;
-    /** [perf L-1] 首扫惰性装载的磁盘索引只读映像（key = jsonl basename）。
-     *  扫描尾（flushIndexAfterScan）与 readdir 失败路径释放——运行期索引不再被读（L1 接管）。 */
-    private indexEntries;
-    /** [perf L-1] 本轮起未落盘的探测标志：scanFile 走过探测分支即置位。发起写时消费
-     *  （置 false）、写失败恢复；未写路径不清位——未落盘的探测成果跨轮携带直至真正写入。 */
-    private indexDirty;
-    /** [perf L-1] 上次成功落盘墙钟（节流基准）。0 = 从未写过 → 首扫 dirty 必写；
-     *  仅成功分支推进（写失败不推进节流窗，下轮过窗重试）。 */
-    private lastIndexWriteAt;
-    /** [perf L-1] loadIndex 高版本标志的进程级持久态：true 时本进程所有后续扫描均不
-     *  落盘（防 v1/v2 last-writer-wins 覆盖振荡），直至下次 loadIndex 重新评估。 */
-    private indexHigherVersion;
-    constructor(sessionsDir: string, manifestStore?: ManifestStore | undefined, 
-    /** Pi 入口（注入 appendEntry 用于上报损坏 manifest）。
-     *  SubagentService 构造时 this.pi 尚未注入（session_start 之前），传 undefined 兜底；
-     *  后续通过 setPi() 注入（见下）。允许 null = 兼容 PiLike 字段类型。 */
-    pi?: RecordStorePi);
-    /** session_start 后由 SubagentService.initSession 调，注入真实 Pi handle。
-     *  设计为独立方法而非要求构造时必传——RecordStore 在 SubagentService 构造时即建
-     *  （与 sessionsDir/manifestStore 一同初始化），但 this.pi 此时尚未注入。
-     *  后续构造期外的 appendEntry 上报才有意义。 */
-    setPi(pi: RecordStorePi): void;
-    /** 注册新 record。触发 onChange。
-     *  W16 [D4]：record 诞生（→ running）即 append 自描述快照 entry——pi 文件是
-     *  扩展数据持久化权威，custom entry 不进 LLM context。 */
-    register(record: ExecutionRecord): void;
-    /**
-     * 归档：record 已被 completeRecord 设置了终态 status。
-     * 立即从内存移除（终态 record 下次读时从 session.jsonl 重建）。
-     * cancelled record 由调用方先写 tombstone（cancel 路径），此处只负责移除。
-     *
-     * W16 [D4]：终态冻结字段（result/endedAt/closedReason）在 completeRecord 已就绪，
-     * 此处 append 的快照即完整终态记录（所有终态路径的必经锚点）。
-     */
-    archive(record: ExecutionRecord): void;
-    /**
-     * W16 [D4]：类外状态写点上报（record-store 内的迁移点 register/archive 已内置）。
-     *
-     * 供 service 层直接改 record.status 的恢复写点调用（chatMode 续轮 idle→running
-     * 冷路径 resumeRound、轮终 finalizeRoundToIdle 回 running-resumable）——这些
-     * 写点绕过 register/archive，若不显式上报，pi 文件缺失该次迁移、重建源滞后。
-     * pi 未注入（session_start 前）时可选链静默降级，不阻断主流程。
-     */
-    reportRecordTransition(record: ExecutionRecord): void;
-    /** 按 id 查找。返回可变 record（仅 runtime 内部用）。 */
-    getMutable(id: string): ExecutionRecord | undefined;
-    /**
-     * abort 所有 running record 的 controller（background 子进程 SIGTERM）。
-     *
-     * 仅在 SubagentService.dispose（进程退出路径）调用。不做 CAS/tombstone——dispose
-     * 是终局，状态机收尾无意义；目的是让 background 子进程的 AbortSignal 触发 →
-     * runSpawn 的 signal listener → child.kill("SIGTERM")，防止主进程退出后子进程成孤儿。
-     *
-     * sync record 无 controller（undefined），跳过——sync 是阻塞调用，主进程不会先于
-     * sync subagent 退出（除非 SIGKILL/崩溃，此时任何清理都无效）。
-     *
-     * 返回被 abort 的 record 数（诊断用）。
-     */
-    abortRunningControllers(): number;
-    /** 列出所有 running record 的只读快照（widget 计数、诊断用）。 */
-    listRunning(): RecordSnapshot[];
-    /** SP-4: 列出所有活跃 record（running + idle）的可变引用。
-     *  供 SubagentService.disposeAllRecords 做级联关闭。 */
-    listAllActive(): ExecutionRecord[];
-    /**
-     * 合并内存(running) + 磁盘(sessions/*.jsonl 重建) → SubagentRecord[]。
-     *
-     *   ╔══════════════════════════════════════════════════════════════════╗
-     *   ║  1. 磁盘源：扫 sessionsDir 的 .jsonl，逐个 scanFile（[perf] 头部    ║
-     *   ║     identity 轻量重建 + stat 戳缓存命中零读取）。cancelled          ║
-     *   ║     tombstone override status。详情字段（eventLog/result/turns）    ║
-     *   ║     缺省，由 getFullRecord(id) 懒加载                              ║
-     *   ║  2. 内存源覆盖（同 id 内存优先——running record 更新鲜）          ║
-     *   ║  3. session 过滤：只留 rootSessionId === rootSessionFilter 的       ║
-     *   ║     record。rootSessionId 缺失（旧文件）的 record 一律排除        ║
-     *   ║     （无法判定归属，隔离优先）。rootSessionFilter 为 undefined       ║
-     *   ║     时不过滤（向后兼容）。                                          ║
-     *   ║  4. statusFilter："running" → 只留 running（内存源）；            ║
-     *   ║                   "all"（默认）→ 内存 + 磁盘                       ║
-     *   ║  5. 排序：STATUS_PRIORITY + startedAt desc                        ║
-     *   ║  6. slice(limit)                                                  ║
-     *   ╚══════════════════════════════════════════════════════════════════╝
+declare function buildEngineModelsPromptAppend(defaultEngine: string | undefined): string;
+
+/**
+ * record 携带的引擎 handle 消费面（EngineHandleData 的结构子集，双端契约不变）：
+ * journalPath 绝对路径；sessionRef 内 dbPath 相对池目录 / 绝对路径均可。
+ */
+interface EngineHandleView {
+    /** 引擎自定义定位符（zcode = { sessionId, dbPath }）。 */
+    sessionRef: Record<string, string>;
+    /** journal 绝对路径（②级数据源；读前校验 engines 根前缀白名单）。 */
+    journalPath?: string;
+    /** 隔离池定位（路径布局 SSOT：resolvePoolDir 消费）。 */
+    poolKey: string;
+}
+/**
+ * 历史读取输入的 record 快照（消费字段级子集，不绑定 runtime 的完整
+ * SubagentRecord 形状——core 不 import workspace private 类型）。
+ * engine / engineHandle 是不可信源（JSONL 文本派生），由 extractEngineId /
+ * parseEngineHandle 守卫式消费。
+ */
+interface SubagentRecordSnapshot {
+    subagentId: string;
+    task: string;
+    result?: string;
+    error?: string;
+    startedAt?: number;
+    endedAt?: number;
+    /** record.engine（'pi' | 'zcode' | ...，缺省 = pi 由 extractEngineId 归一）。 */
+    engine?: unknown;
+    /** record.engineHandle（parseEngineHandle 守卫消费）。 */
+    engineHandle?: unknown;
+}
+/** GUI 工具调用视图（结构兼容 shared ToolCall 的消费子集；id/时间戳为展示占位）。 */
+interface HistoryToolCallView {
+    id: string;
+    toolName: string;
+    input: unknown;
+    output?: string;
+    details?: Record<string, unknown>;
+    status: "completed" | "error";
+    startTime: number;
+    endTime: number;
+}
+/** GUI thinking 块视图（结构兼容 shared ThinkingBlock）。 */
+interface HistoryThinkingView {
+    id: string;
+    content: string;
+    collapsed: boolean;
+}
+/** GUI usage 视图（结构兼容 shared Usage）。 */
+interface HistoryUsageView {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** GUI 消息视图（结构兼容 shared Message 的消费子集——见文件头「为什么不 import shared」）。 */
+interface HistoryMessage {
+    id: string;
+    role: "user" | "assistant";
+    content: string;
+    status: "complete" | "error";
+    toolCalls?: HistoryToolCallView[];
+    thinking?: HistoryThinkingView[];
+    usage?: HistoryUsageView;
+    timestamp: number;
+    error?: string;
+}
+/**
+ * engineHandle 唯一守卫（D1 双守卫收敛点）。
+ * 语义取收敛前 extractor 侧的严格版（两份 guard 此前已在「sessionRef 含非 string 值」
+ * 维度分叉：extractor 整体拒绝、history 侧逐键过滤——收敛选整体拒绝，坏形状不进
+ * record，读侧按缺 handle 降级 outcome-only，两侧行为面等价落点都是降级）：
+ * - poolKey 缺失 / 非 string / 空串 → undefined（定位符不完整，读侧降③级）
+ * - sessionRef 非 plain object 或含非 string 值 → undefined（整体拒绝）
+ * - journalPath 可选 string（空串视为缺省）
+ */
+declare function parseEngineHandle(raw: unknown): EngineHandleView | undefined;
+
+/**
+ * 引擎原生 reader（①级）：handle + dataDir → SessionView。
+ * 返回 undefined = 本级不可达/失败（编排层降②级）；reader 内部自行留 debug 日志。
+ * 双端复用约束（设计 §3.3.7）：实现必须无状态纯函数、不 import 引擎运行时件。
+ *
+ * [W11/H1] 本模块零静态引擎依赖：①级 reader 全部经注入面注册——生产调用方 =
+ * runtime 协议客户端（W8 subagent-engine-history 把「协议 read」注册为引擎原生
+ * reader，引擎 id 动态、zcode sqlite 直读在引擎进程内完成）；注册表初始为空，
+ * 未注册引擎直接落②级 journal。
+ */
+type NativeSessionReader = (handle: EngineHandleView, dataDir: string) => Promise<SessionView | undefined>;
+/**
+ * 登记引擎原生 reader（W11/H1 后的唯①级接入点）。重复注册同 id = 覆盖
+ * （幂等，对齐 registerEngine 惯例）。生产调用方 = 宿主协议客户端接线
+ * （runtime subagent-engine-history 的 ensureProtocolReaderFor）。
+ */
+declare function registerNativeSessionReader(engineId: string, reader: NativeSessionReader): void;
+/**
+ * 非 pi record 的历史详情读取（三级降级主入口，D1 收敛后的唯一生产实现）。
+ *
+ * 降级顺序 ①→②→③ 逐级尝试，每级失败留 debug/warn 日志不抛崩溃（GUI 详情页
+ * 永不白屏报错，设计 A8）。engineId='pi' 返回 []（pi 的①级 = 调用方现有 JSONL
+ * 直读链，A1 守护）。未注册 reader 的引擎（W11 后 = 宿主未接线协议 reader 的
+ * 进程）跳过①级直落②级 journal——record 字段就够，详情页至少有摘要卡。
+ *
+ * @param record  record 快照（engine/engineHandle 为不可信源，内部守卫消费）
+ * @param dataDir xyz-agent 数据根（journal/dbPath 白名单经 paths.ts 布局 SSOT 推导）
+ */
+declare function readSubagentHistoryMessages(record: SubagentRecordSnapshot, dataDir: string): Promise<HistoryMessage[]>;
+
+/**
+ * 从 turns[] 末尾推导当前活动行（running 时）。
+ *
+ *   优先级：最后一个未闭合 turn 的末尾 running toolCall → thinking → text → undefined
+ *
+ * 仅 status==="running" 时返回；terminal 态返回 undefined。
+ *
+ * 注意：返回的 type 联合（"tool"|"text"|"thinking"）是手写的，未通过类型守卫从
+ * AgentEvent 派生——它映射的是累积的 turn 状态（InternalToolCall._status + turn.thinking/text），
+ * 而非单个事件。若未来新增 turn 内容模式（如 reasoning_summary），须同步扩展本函数，
+ * 否则会静默返回 undefined（活动行运行中途消失）。updateFromEvent 的 switch 有 never 穷尽
+ * 检查，但本函数没有，依赖人工同步。
+ */
+declare function getCurrentActivity(record: ExecutionRecord): {
+    type: "tool" | "text" | "thinking";
+    label: string;
+} | undefined;
+/**
+ * 聚合所有 turn 的 toolCalls（扁平化），并 strip InternalToolCall 的内部字段。
+ * 供 collectResult / schema enforcement 读，替代旧闭包 toolCalls 旁路。
+ *
+ * 返回 ToolCall[]（不含 _status / startedTs）——跨边界导出形状清洁，
+ * 避免内部状态机字段泄漏到 AgentResult.toolCalls / 持久化层。
+ */
+declare function getAllToolCalls(record: ExecutionRecord): ToolCall[];
+/**
+ * 聚合所有 turn 的 toolCalls 总数（免克隆计数）。
+ *
+ * getAllToolCalls 会 flatMap + strip 克隆出完整数组——只需计数的调用方（渲染签名
+ * 每 200ms tick 调用一次）用它是纯浪费；本函数 reduce 累加各 turn 的 length，零分配。
+ * 与 getAllToolCalls(...).length 恒等（同一 turns 源）。
+ */
+declare function countAllToolCalls(record: ExecutionRecord): number;
+/**
+ * closed 终态 → 三态 outcome 的唯一权威派生（D6 收敛：原 notifier/bg-notify-render/
+ * shared deriveClosedDisplay 三处手写同构 switch 的单一实现）。
+ *
+ * 判定顺序（顺序敏感，勿回退成「error 有值即 failed」的无视取消规则）：
+ *   1. closedReason === "cancelled" → "cancelled"（取消优先，不参与 error——abort 合成
+ *      result 可能携带 error，但用户取消语义优先）
+ *   2. error 非空（truthy，与旧三处同构的 `record.error &&` 判定逐字对齐——空串 error
+ *      不构成失败）→ "failed"
+ *   3. 其余 → "completed"
+ *
+ * [D6 待核项保真] 「failed 优先于 patchFile 提示」：失败轮也会写 patchFile
+ * （doFinalizeRecord Step 0 对 worktreeHandle 无条件 collectPatch），消费方必须先按
+ * outcome 分流再渲染 patch 提示——failed 分支不展示 patch/result。历史 bug：notifier
+ * 的 patchFile 分支曾遮蔽 gc+error 判定，失败终态被 LLM 告知 completed（M1 修复存档）。
+ *
+ * [D6 显式取舍] parent-shutdown/parent-fork/parent-new 合成关闭（subagent-service
+ * disposeAllRecords 合成 result 恒写 error:"closed due to ${reason}"）在本映射下落
+ * "failed"——语义为「父进程关闭时子 agent 未完成即失败」，选定行为而非疏漏，
+ * 勿当 bug 改回 cancelled 造成派生矛盾。
+ *
+ * 唯一写点 completeRecord 调用本函数冻结 record.outcome；通知 payload（notifier 投影
+ * 边界）与无 outcome 字段的存量/重建 record 由 projectOutcome 兜底复用本函数。
+ */
+declare function deriveOutcome(closedReason: ClosedReason | undefined, error: string | undefined | null): ExecutionOutcome;
+/**
+ * 投影层 outcome 唯一出口：running → undefined（终态语义不适用活跃态）；closed →
+ * 一等 outcome 字段直读优先，字段缺失（存量/磁盘重建 record——outcome 持久化不在
+ * U3 领地内）时回退 deriveOutcome(closedReason, error) 兜底——单一权威函数，
+ * 消费方零手写推导。返回值联合含 "closed-legacy" 预留态，消费方必须处理。
+ */
+declare function projectOutcome(record: {
+    status: ExecutionStatus;
+    outcome?: ExecutionOutcome;
+    closedReason?: ClosedReason;
+    error?: string;
+}): ProjectedOutcome | undefined;
+/** elapsedSeconds 唯一计算点（共享 helper，消除三处发散）。endedAt 缺失用 Date.now()。 */
+declare function computeElapsedSeconds(record: {
+    startedAt: number;
+    endedAt?: number;
+}): number;
+/**
+ * 投影到 live 进度快照。elapsedSeconds/currentActivity/eventLog 均现算派生。
+ * 供 WorkflowsView 在 agent 运行期间读取实时进度。
+ */
+declare function projectLiveProgress(record: ExecutionRecord): {
+    status: ExecutionRecord["status"];
+    turns: number;
+    totalTokens: number;
+    elapsedSeconds: number;
+    eventLog: AgentEventLogEntry[];
+    currentActivity: ReturnType<typeof getCurrentActivity>;
+    lastError: string | undefined;
+};
+
+/** 入队项的 child 引用形状（只取 pid 用于 rejectChildDialogs 匹配）。 */
+interface DialogChildRef {
+    pid: number;
+}
+/** enqueue 的可选项。child 用于 rejectChildDialogs 关联（child close 时批量 reject）。 */
+interface EnqueueOptions {
+    child?: DialogChildRef;
+}
+/**
+ * L2 跨子进程全局 dialog 串行队列（进程单例）。
+ *
+ * 用法（createUiRequestHandlerForMode 返回的总 handler 内）：
+ * ```ts
+ * const dialogQueue = new DialogGlobalQueue();
+ * return async (req: UiRequest) => {
+ *   // 调用方负责判断：dialog 入队，fire-and-forget 直接调 realHandler
+ *   if (isDialogMethod(req.method)) return dialogQueue.enqueue(req, realHandler);
+ *   return realHandler(req);
+ * };
+ * ```
+ *
+ * 语义保证：
+ *   - FIFO 串行：前一个 handler settle 后才处理下一个
+ *   - SR-4：rejectChildDialogs(child) 把该 child 的 pending 全部 resolve 为 {cancelled:true}
+ *   - handler 抛错兜底：catch → {cancelled:true} → 继续下一个（队列不卡死）
+ *   - 超时上界（LC-3/T2⑦）：每个 dialog 项必有上界——req.timeout 显式传值优先，
+ *     未传挂 DEFAULT_DIALOG_TIMEOUT_MS（30min，裁决值）；到点 settle {cancelled:true}
+ *     并 warn（恢复指引见 dialogTimeoutLogMessage），L2 processing 释放、队列继续推进。
+ *     「等用户无限久」改为默认有界是有意的行为变更。
+ *   - 调用方约定只对 dialog 类调 enqueue；fire-and-forget 由调用方直接调 handler 不入队
+ *（enqueue 内仍防御性兼容 fire-and-forget，但不保证行为）
+ *
+ * 线程模型：纯 Promise + 微任务驱动，无锁。Node 单线程 event loop 保证队列状态一致。
+ *
+ * 单 session 假设（M-2，与 index.ts lastSessionId 同源）：本队列是进程级单例（实例挂在
+ * globalThis[Symbol.for("@zhushanwen/pi-subagents.dialogQueue")]，见 getOrCreateDialogQueue）。
+ * rejectAll() 清空所有 pending dialog——无 per-session 隔离。Pi 当前架构保证单进程
+ * 单 session 串行（同进程不会并发多个 session），故 session_shutdown 调 rejectAll() 只会清掉
+ * 当前 session 的 pending。若未来 Pi 支持同进程多 session 并发，session A 退出会误清 session B
+ * 的 pending dialog——届时需改为 per-session 隔离（入队项 QueueItem 带 sessionId，rejectAll
+ * 改 rejectAllForSession(sessionId)，session_shutdown 只清当前 session）。
+ */
+declare class DialogGlobalQueue {
+    /** 等待处理的队列（FIFO）。正在处理的项从 queue shift 出后由 current 持有。 */
+    private queue;
+    /** 正在处理的项（handler 已调、未 settle）。用于 rejectChildDialogs 取消占位中的 dialog。 */
+    private current;
+    private processing;
+    /**
+     * 入队一个 UI 请求，返回 Promise<UiResponse>。
      *
-     * statusFilter="running" 时仍先取够多再过滤（防 limit 截断把 running 滤没），
-     * 与旧 listHandler 的防截断逻辑一致，下沉到此。
+     * 调用方约定：只对 dialog 类（isDialogMethod===true）调 enqueue。fire-and-forget 由
+     * 调用方（ui-request-handler-factory.ts）在 enqueue 前判 isDialogMethod 后直接调 handler，
+     * 不经过本队列。enqueue 内仍防御性兼容 fire-and-forget（万一调用方未判）：直接调 handler 返回，
+     * 不入队串行，但调用方不应依赖此防御行为。
      *
-     * session 隔离：同一 cwd 下多个 Pi session 共享 sessionsDir，靠 rootSessionId
-     * 区分。内存与磁盘源都按 rootSessionFilter 过滤后再 merge/sort/slice。
+     * dialog 项处理（TC-E4 case 1）：进队列 FIFO 串行，等前一个 settle 后才调 handler
+     *（争输入焦点，防并发弹窗）。
+     *
+     * handler 抛错兜底：catch → 回 {cancelled:true}（dialog 路径，队列不卡死）。
+     * SR-4：opts.child 用于 rejectChildDialogs 关联（dialog 项会被批量 reject，含 current）。
+     *
+     * @param req UI 请求（约定只传 dialog 类；fire-and-forget 防御性兼容）
+     * @param handler 真正执行请求的 handler（TUI/GUI 模式分流后的 realHandler）
+     * @param opts 可选 child 引用（用于 rejectChildDialogs 关联）
+     * @returns handler 的响应；dialog 抛错时回 {cancelled:true}；child close 时回 {cancelled:true}
      */
-    collectRecords(limit: number, statusFilter?: StatusFilter, rootSessionFilter?: string): SubagentRecord[];
+    enqueue(req: UiRequest, handler: UiRequestHandler, opts?: EnqueueOptions): Promise<UiResponse>;
     /**
-     * 重建 SubagentRecord 的自描述 entry 落盘入口（签名适配：reportRecordTransition 收
-     * ExecutionRecord，重建孤儿的数据源是 SubagentRecord——直接经 toSubagentRecordEntry
-     * 投影 appendEntry，绕过 recordToSubagent）。pi 未注入时可选链静默。
+     * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll / 超时 timer
+     * 都通过本方法，settled 标志保证只 settle 一次（防竞争）。
+     *
+     * #19 单一推进点：本方法 settle Promise + 清状态后，**唯一**调 processNext 推进队列。
+     * processNext 尾部不再调 processNext（旧代码双重推进，虽靠 processing 标志幂等，但语义混乱）。
+     * 为什么推进必须在 settleItem 而非 processNext 尾部：rejectChildDialogs 取消一个永不 settle
+     * 的 current（handler 等用户输入卡死）时，processNext 的 `await item.handler` 永不 resume，
+     * 尾部不会执行；只有 settleItem 里的 processNext 才能打破死锁，推进下一个。
+     *
+     * [A2-2] 超时 timer 清理也统一收口在这里：任何路径抢先 settle（reject/rejectAll/超时
+     * 自身）都必须撤下 armed timer——handler 永挂时 processNext 内联的 clearTimeout 不可达，
+     * 不在这里清则 timer 到期触发虚假「dialog timed out」warn 且句柄滞留至超时点。
      */
-    reportSubagentRecord(record: SubagentRecord): void;
+    private settleItem;
     /**
-     * 孤儿终态恢复：对重建矩阵分支 4 兜底（running 且无 externalInstance）的 record
-     * 判定真实终态并落 entry，消除「父扩展死后再无人写终态 → 侧栏永久 running」。
+     * SR-4：把指定 child 的所有 pending dialog resolve 为 {cancelled:true}。
      *
-     * 判定（residual-fixes §5.2 三判据 + chat 分流）：
-     * - chatMode = true → 不终态化（跨重启可续聊是产品语义，v4 B-1），落 resumable
-     *   entry 供侧栏 waiting 细分；
-     * - 子 JSONL 末行完整 JSON.parse → closed（closedReason=gc，与分支 2 重建映射一致；
-     *   done/failed 细分由 error 字段经 deriveClosedDisplay 派生）+ 写 .finalized sidecar
-     *   （防重锚——下次重建走分支 2 不再进判定）；
-     * - 末行截断 → closed + error（保守，错误方向安全）+ sidecar；
-     * - 文件不可读（IO 错误，可能暂时）→ 不判终态，落 resumable entry（防御性路径，
-     *   IO 恢复后重开可重判）。
+     * 触发场景：子进程 close（用户取消 / crash / 超时 kill）时，其 pending dialog 的 handler
+     * 可能永不 settle（等用户输入），导致 Promise 永挂 + 内存泄漏。本方法批量清理。
      *
-     * [v2 D3] mainSessionFile = 覆写 merge 数据源（主 session 每 id 末条 entry，与 E1
-     * 的 scanLastRecordEntries 同款通路）：崩溃前的批域标记（collectMode/batchFinalized）
-     * 与轮终 result/model 只活在主文件 entry——重建矩阵（buildRecord）的数据源
-     * （sidecar/子文件 identity）不含它们，覆写前不 merge 就会被抹掉（v2 §2.2 断链 2：
-     * E1 候选集恒空的真根因）。缺省（undefined）时 merge 无源，行为与旧版一致。
-     * 参数为追加式第二参（rootSessionFilter 保持首参）：既有调用面只传过滤参。
+     * 处理范围（TC-E4 case 2）：
+     *   - 正在处理中（current）的该 child 项：settle {cancelled:true}，解阻塞队列推进下一个
+     *     （关键：handler 可能永不 settle，必须由这里打破死锁）
+     *   - 队列中等待处理的该 child 项：settle {cancelled:true} 并移除
      *
-     * 防重：orphanJudged 实例级缓存（resumable 形态无 sidecar 锚，同进程重复调用跳过；
-     * 终态形态双重防护 = sidecar + 缓存）。调用方：index.ts session_start 恢复段（一次）。
+     * 不影响其他 child 的 pending dialog（TC-E4 case 2 子测试 2）。
      */
-    recoverOrphanRecords(rootSessionFilter?: string, mainSessionFile?: string): void;
+    rejectChildDialogs(child: DialogChildRef): void;
     /**
-     * 单孤儿 record 的终态判定与落 entry（residual-fixes §5.2 三判据 + chat 分流）。
-     * 防重锚（orphanJudged 标记）已由调用方完成。
+     * 处理队列下一项（FIFO）。
      *
-     * [v2 D3] 覆写前 merge（lastEntry = 主 session 同 id 末条 entry 重建，调用方构建）：
-     * 覆写是状态迁移不是信息重建，迁移不应丢末条既有信息。三个落 entry 分支（chatMode
-     * 分流 / IO 保守 / 终态覆写）统一基于 merge 后的 rec，同款口径。
-     */
-    private finalizeOrphanRecord;
-    /** [v2 D3] 孤儿覆写 merge 字段集：末条 entry 的批域标记 + 轮终正文/模型，仅补 rec 侧
-     *  undefined/空值（model 的空值形态是 ""——light 重建无 model_change entry 时起步
-     *  空串），不覆盖已有值。merge 后写 entry 经 reportSubagentRecord →
-     *  toSubagentRecordEntry 序列化，undefined 字段自然缺省（不引入显式 null）。 */
-    private static mergeOrphanLastEntry;
-    /**
-     * [E2E 实测缺口] entry-born 孤儿恢复：register entry 已落主 session、但子 session 文件
-     * 从未创建（父进程死在 spawn 窗口期——register 写点与子进程首笔写入之间的窗口；外部
-     * 删除子文件的已知边界同形）。目录扫描（reconstructAll）看不见这类 record（无文件即
-     * 无扫描集），recoverOrphanRecords 判不到，侧栏（runtime entry 扫描源）永久 spinner。
+     * processing 标志保证串行：handler 运行期间 processing=true，新的 processNext 调用直接返回；
+     * handler settle 后由 settleItem 清 processing=false 并推进下一项（#19 单一推进点）。
      *
-     * 判定：读主 session 的 subagent-record entry，取每 id 末条；末条 status=running 且
-     * 无子文件锚（不在 reconstructAll 结果中）且不在内存活 record（防误杀刚 register 的
-     * 在途 spawn）→ 按无文件判据收敛：chatMode=true → resumable（分流语义一致）；否则
-     * closed+gc+error（子文件由子进程创建，无文件 = 子进程从未开跑，error 方向安全）。
-     * 调用点：initSession 的 recoverOrphanRecords 之后（session_start，内存恒空）。
-     */
-    recoverEntryOnlyOrphans(mainSessionFile: string | undefined, rootSessionFilter?: string): void;
-    /**
-     * entry-born 孤儿候选判定（recoverEntryOnlyOrphans 的守卫链拆出）：末条 running、
-     * root session 匹配、无子文件锚、不在内存活 record（防误杀在途 spawn）、未判过。
-     */
-    private isEntryOrphanCandidate;
-    /** entry-born 孤儿按无文件判据收敛落 entry：chatMode → resumable（分流语义一致）；
-     *  否则 closed+gc+error（子文件由子进程创建，无文件 = 子进程从未开跑，error 方向安全）。 */
-    private finalizeEntryOnlyOrphan;
-    /**
-     * [E1/U5] sync 批崩溃恢复扫描：主 session 文件「每 id 末条 subagent-record entry」
-     * （collectLastRecordEntries + rebuildEntryRecord 组合通路，设计 §3.1.3「标记读取
-     * 通路」——batchFinalized 落标 entry 写主 session 文件，本扫描同文件域才可见；禁走
-     * collectRecords light 路径，它只读子文件 identity 头+sidecar，主 session 落标
-     * entry 不可见）。返回每 id 末条重建的完整 record（含 collectMode/batchFinalized /
-     * 终态五字段，损坏 entry 跳过）；调用方（service.recoverSyncCollectBatch 的 E1 过滤、
-     * recoverOrphanRecords 的覆写 merge）自行取舍。主文件不可读（含新 session 未 flush
-     * 的 ENOENT）→ 空数组静默。
-     */
-    scanLastRecordEntries(mainSessionFile: string | undefined): SubagentRecord[];
-    /** 订阅变更。返回取消订阅函数。 */
-    onChange(listener: ChangeListener): () => void;
-    /** 触发所有监听器（TUI widget/list requestRender）。dispose 后短路。
-     *  [perf] 不清空磁盘缓存：per-file stat 戳自校验（任何磁盘写入改变戳 → 单文件重建），
-     *  内存事件（register/archive）不改变磁盘文件——旧实现整体失效是全量重扫的根因。 */
-    notifyChange(): void;
-    /** session 结束清理。 */
-    dispose(): void;
-    /**
-     * /resume /fork /new 后复活（dispose 的逆操作）。
+     * handler 抛错兜底（TC-E4 case 3）：catch → settle {cancelled:true} → 继续。
+     * 不能让一个失败卡死队列（processing 永远 true）。
      *
-     * [PS-10/T6④] 同步复位 orphanJudged 防重缓存：resumable 形态（IO-error 保守分支 /
-     * chatMode 分流）没有 .finalized sidecar 锚，重判资格完全由本缓存承载——dispose 时
-     * 有 clear（session 结束），但 revive 此前不复位，导致「同进程内曾经的 IO 失败记录
-     * 永久停留 resumable」，与本文件 recoverOrphanRecords 注释承诺的「IO 恢复后重开可重判」
-     * 不符。/new 复活正是「重开」语义：IO 已恢复的记录下次 recoverOrphanRecords 重新判定
-     * 收敛终态；仍不可读的记录重判再落一次 resumable entry（幂等，末条语义不变）。
+     * LC-3/T2⑦ 超时上界：`await item.handler` 原本无上界——host UI promise 挂死或用户
+     * 永不回答时 processing 恒 true（全局 dialog 死锁）。现在每项挂队列级 timer：
+     * req.timeout（请求方显式传值）优先，未传/非法挂 DEFAULT_DIALOG_TIMEOUT_MS。
+     * 到点 settle {cancelled:true}（完整错误消息落父进程日志，含恢复指引与等待时长），
+     * settleItem 的 settled 标志保证与 handler 完成 / rejectChildDialogs 三方竞态下
+     * 恰 settle 一次。timer 回调闭包捕获 item（非读 this.current）：迟到触发时
+     * settled 标志已置位，直接 noop，不误伤后继项。
      */
-    revive(): void;
+    private processNext;
     /**
-     * 四分支 sidecar 矩阵重建（[perf] light 版）。
+     * #10：把所有 pending dialog（queue + current）全部 settle 为 {cancelled:true}，
+     * 并清空 queue/current/processing 状态。session_shutdown 调用，保证不留永挂 Promise。
      *
-     * 优先级：
-     *   1. .cancelled → closed（closedReason=cancelled）
-     *   2. .finalized → closed（closedReason=sidecar 内容 reason；空/旧格式 → disconnected）
-     *   3. .alive + pid 存活 + 未超软超时 → running, externalInstance=true
-     *   4. 兜底（无 marker、pid 死、超时）→ running（v4 B-1 可续聊语义）
+     * 约定签名：rejectAll(): void（无参，返 void）。Group C 的 index.ts session_shutdown 依赖此契约。
      *
-     * [perf]：逐文件 scanFile（stat 戳校验 + 头部 identity 轻量重建）。命中缓存的
-     * 文件零文件读取；变化的文件只重建自身，其余 N-1 个复用缓存。
+     * 幂等：依赖 settleItem 的 settled 标志——重复调用只会对已 settled 项 noop。
+     * 顺序敏感（#19 推进点在 settleItem）：必须先清空 queue 数组再 settle current，
+     * 否则 settleItem(current) 同步触发的 processNext 会从旧 queue 抢占下一项作为新 current，
+     * 避开本方法的 cancel 语义。清空后 processNext 看到空队列直接返回，新 current 不会被抢占。
      *
-     * session 隔离：rootSessionFilter 非空时，只保留 rootSessionId 匹配的 record。
-     * rootSessionId 缺失（旧文件，未带身份字段）一律排除（无法判定归属）。
-     */
-    private reconstructAll;
-    /**
-     * 扫描单文件：stat 戳（jsonl + 3 sidecar）校验，全同 → 复用缓存（零文件读取，
-     * 含负缓存直接返回 null）；否则重建 light。
-     * identity 定位两级：头部 64KB（首轮会话）→ 全文 fallback（续聊场景 identity
-     * append 在尾部）；两级都找不到 → 写负缓存（防每轮全文重读）。
-     * 返回 null：文件消失/读失败/无 identity → 跳过。
+     * 单 session 假设（M-2）：见类注释。本方法清空所有 pending 不分 session——依赖 Pi 单进程
+     * 单 session 串行保证。session_shutdown handler（index.ts）调用本方法时，进程内只会有当前
+     * session 的 pending dialog。多 session 并发场景的迁移策略（rejectAllForSession）见类注释。
      */
-    private scanFile;
+    rejectAll(): void;
+    /** 清空队列状态（仅在 rejectAll 之后调用）。pending Promise 必须先由 rejectAll settle。
+     *  不 settle Promise 的纯状态重置——单独调用会导致 Promise 永挂（footgun），故设为 private。
+     *  外部调用方应使用 rejectAll()（它 settle 所有 pending + 重置状态，是原子操作）。 */
+    private resetState;
+    /** 当前队列长度（测试/诊断用）。含等待处理项（不含 current）。 */
+    get size(): number;
+}
+
+interface ManifestRecord {
+    id: string;
+    rootSessionId: string;
+    /** 直接父 subagent record ID（层级树构建用）。顶层 record 缺失（undefined）。M3a 补字段。 */
+    parentRecordId?: string;
+    agentName: string;
     /**
-     * [perf L-1] 磁盘索引查询（首扫惰性装载，miss/空索引时 get 恒 undefined = 无索引）。
-     * 条目戳匹配 jsonl 当前 stat → 零内容读取构造缓存条目。sidecar payload（tombstone/
-     * alive）是活态数据，沿用探测分支的每轮重读语义；finalized reason 静态数据仅在
-     * sidecar 存在时读一次（文件小，成本可忽略）。
-     *
-     * 返回 undefined = 索引未命中/戳不匹配（调用方落到原三级探测）；null = 负条目命中
-     * （「确认无 identity」跨实例持久，零探测跳过，与内存负缓存同款形态）。
+     * 终态枚举：finalizeRecord 写 running/closed/cancelled 三态。
+     * SP-1 重构：旧 completed/failed 合并为 closed（L1 统一终态）。
+     * cancelled 保持独立（用户取消语义）。crashed 不进 manifest——
+     * crashed 是重启重建时靠 sidecar 四分支推断的派生态（见 record-store.ts reconstructAll）。
+     * 历史 "error"/"completed"/"failed" 值由读侧 mapManifestStatus 向后兼容映射。
      */
-    private buildEntryFromIndex;
+    status: "running" | "closed" | "cancelled";
+    createdAt: number;
+    completedAt?: number;
+    sessionFile?: string;
+    /** FR-7 补字段：manifest 写入时从 ExecutionRecord 抓取，供 manifestToSubagent 投影真实值。 */
+    task?: string;
+    slug?: string;
+    model?: string;
+}
+declare class ManifestStore {
+    private readonly dir;
+    /** [perf] per-file 缓存：file → { stamp, record }。record=null 表示「已解析但非法」（缓存
+     *  负结果避免反复 parse 损坏文件）。stat 戳变化（writeManifest tmp→rename 后 mtime/size 变）
+     *  自动失效；删除的文件在下次扫描时修剪。 */
+    private readonly cache;
+    constructor(dir: string);
     /**
-     * [perf L-1] 扫描尾索引落盘（节流）：释放映像 → dirty/高版本/60s 节流窗三重门 →
-     * fire-and-forget saveIndex（fileCache 全量投影）。写决策与发起在同步栈（collectRecords
-     * 返回后不会再有本轮写）；仅写完成的回调（推进节流窗）是异步的。所有 return 路径均
-     * 不清 dirty——未落盘的探测成果跨轮携带，直至真正写入。
+     * 原子写：tmp → fsync → rename → fsync dir（shared/atomic-write 统一原语，
+     * U6b 迁移——原逐行实现与 writeAtomicFile 逐环等值）。真异步（fs.promises，
+     * 不阻塞 event loop）。
      *
-     * 并发安全：节流基准只在写成功后推进，W1 在途时新一轮过窗扫描可再 dispatch W2（不做
-     * 进程内排队——fire-and-forget 语义保持）。安全性由 saveIndex 的 tmp 唯一性
-     * （pid+单调序号）保证：交错 rename 的终态必为某一次的完整快照（last-writer-wins，
-     * 陈旧快照胜出时下轮戳不匹配自愈），不依赖本方法串行化。
+     * 失败时原语尽力清理残留 tmp（debug 记录，不掩盖原错误）并原样上抛——
+     * 调用方（finalizeRecord）决定降级策略。
      */
-    private flushIndexAfterScan;
+    writeManifest(record: ManifestRecord): Promise<void>;
     /**
-     * [perf L-1] fileCache 全量投影 → 索引快照（basename → 正/负条目）。
-     * 投影式单一 SSOT：不维护第二份可变索引映像（防双轨漂移）；fileCache 已被
-     * reconstructAll 修剪掉消失文件（修剪时置 indexDirty），下次过窗写时快照清除
-     * 磁盘上的陈旧条目。
+     * 按 id 读 manifest。文件不存在/JSON 损坏/schema 不合法均返回 null。
+     * 调用方需处理 null。
      */
-    private projectIndexEntries;
+    readManifest(id: string): Promise<ManifestRecord | null>;
     /**
-     * [perf] byId 索引直查 light record（单文件 stat 校验，不触发 getFullRecord 的
-     * 全量重建）。idToFile 未热（进程重启后尚未扫描过）时返回 undefined，调用方
-     * 自行兜底全目录扫描——用于把「跨重启后每条 message 一次 collectRecords 全扫」
-     * 降为 O(1) 索引命中。
+     * 同步读取所有 manifest 记录（best-effort，损坏/非法文件跳过）。
+     * 供 RecordStore.collectRecords 投影 orphan 记录使用——替代对私有 dir 的反射访问。
+     * 仅返回通过 isValidManifest 校验的记录。
+     *
+     * [perf] per-file 缓存 + stat 戳校验：collectRecords 每次渲染都调本方法，旧实现每次
+     * 全量 readFileSync + JSON.parse 千级 manifest（实测 ~300ms/次）。命中缓存的文件零读取。
      */
-    findLightById(id: string): SubagentRecord | undefined;
+    listAllSync(): readonly ManifestRecord[];
     /**
-     * [perf] 单 record 详情懒加载：内存 running record 投影全量；磁盘 record 全量重建
-     * （reconstructFromFile）并套用同一 sidecar 状态矩阵。结果缓存在 FileCacheEntry.full，
-     * stat 戳变化时随 light 一起失效。列表 collectRecords 返回 light（无 eventLog/
-     * result/turns 等重数据），详情面板/工具 list 按需调本方法补齐。
+     * 启动时恢复 tmp 文件。
+     * 3 分支逻辑：
+     * 1. manifest 已存在 → 删 tmp（陈旧）
+     * 2. tmp 合法 + manifest 缺失 → rename tmp 为 manifest
+     * 3. tmp 非法 + manifest 缺失 → 删 tmp
      *
-     * 返回 undefined：id 不存在（内存与磁盘均无）。reconstructFromFile 失败（无
-     * assistant message 等）→ 返回 light（无详情可补，缓存哨兵防重复全文重读）。
+     * [T5④ / PS-13] per-file 容错：单个 tmp 文件操作失败（ENOENT——并发回收/外部清理
+     * 抢先、EACCES 等）只 warn + 跳过该文件，不再中断整轮——旧实现单文件 ENOENT 即抛，
+     * 剩余 tmp 本轮不再处理，自愈但不可见（残留顺延下次启动）。跳过数经 warn 汇总留痕，
+     * 调用方返回值形态不变（跳过者不计数）。
      */
-    getFullRecord(id: string): SubagentRecord | undefined;
-    /** alive 探活刷新（scanFile 缓存命中与 reconstructAll 快路径共用）：
-     *  分支 3 的 running + alive 条目每扫重查 pid（结果不落盘，进程死亡无 IO），
-     *  保留旧实现「每次 collectRecords 重新 isProcessAlive」的语义。 */
-    private static refreshAlive;
-    /** identity 基底 + sidecar 状态矩阵 → 缓存条目（索引命中与探测重建两分支的公共装配点）。 */
-    private static buildFileCacheEntry;
-    /** identity 基底（头部 light 或全量 recon）+ 四分支 sidecar 状态矩阵 → SubagentRecord。 */
-    private static buildRecord;
-    /** 排序比较器：status priority（running<failed<cancelled<done）+ startedAt desc。 */
-    private static compareRecords;
-    /** FR-8: 同步读取所有 manifest 记录（封装 ManifestStore.listAllSync，消除反射访问）。 */
-    private readManifestsSync;
-    /** FR-8: ManifestRecord → SubagentRecord（manifest 源投影）。
-     *  task/slug/model 从 manifest 真实值投影（配合 writeManifest 补字段），缺失兜底空串。
-     *  status 越界（mapManifestStatus 返回 null）时返回 null，由 collectRecords 跳过。 */
-    private static manifestToSubagent;
-    /** ExecutionRecord → SubagentRecord（内存源投影）。 */
-    private static recordToSubagent;
+    recoverTmpFiles(): Promise<{
+        deleted: number;
+        recovered: number;
+    }>;
 }
 
-/** Pi extension_ui_request 的方法枚举（dialog + fire-and-forget 两类）。
- *  dialog 类：select/confirm/input/editor（占输入焦点，等响应）。
- *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
- *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
-type UiMethod = "select" | "confirm" | "input" | "editor" | "notify" | "setStatus" | "setWidget" | "setTitle" | "set_editor_text" | (string & {});
-/** UI 请求（session-runner 构造后传给 handler）。
- *
- *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
- *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
- *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
- *
- *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
-interface UiRequest {
-    /** Pi rpc-types.ts 的 method（select/confirm/input/editor 为 dialog 类）。 */
-    method: UiMethod;
-    /** 请求 id（从 extension_ui_request envelope 顶层提取，用于 response 关联）。 */
-    id: string;
-    title?: string;
-    options?: string[];
-    message?: string;
-    placeholder?: string;
-    prefill?: string;
-    notifyType?: string;
-    statusKey?: string;
-    statusText?: string | undefined;
-    widgetKey?: string;
-    widgetLines?: string[] | undefined;
-    widgetPlacement?: "aboveEditor" | "belowEditor";
-    text?: string;
-    timeout?: number;
-    /** channel 名（从 method 对应字段的 NUL 前缀解析）。
-     *  select → 从 title 解析；setWidget → 从 widgetLines[0] 解析；其他 → undefined。
-     *  已知值："ask_user"（select）、"gui_widget"（setWidget）。handler 按 channel 分发。 */
-    channel?: string;
-    /** channel 解析后的结构化 payload（已 JSON.parse）。
-     *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
-    channelPayload?: unknown;
-    /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
-     *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
-     *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
-    _childPid?: number;
-}
-/** UI 响应（handler 返回，session-runner 按 shape 回写 stdin）。
- *  - {value}: select/input/editor 的答案
- *  - {confirmed}: confirm 的答案
- *  - {cancelled}: 取消（child close / handler 抛错 / 用户取消）
- *  - {ack}: fire-and-forget（当前不透传到 TUI，留作协议完整） */
-type UiResponse = {
-    value: string;
-} | {
-    confirmed: boolean;
-} | {
-    cancelled: true;
-} | {
-    ack: true;
-};
-/** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
- *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
- *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
-type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
-/** 入队项的 child 引用形状（只取 pid 用于 rejectChildDialogs 匹配）。 */
-interface DialogChildRef {
-    pid: number;
-}
-/** enqueue 的可选项。child 用于 rejectChildDialogs 关联（child close 时批量 reject）。 */
-interface EnqueueOptions {
-    child?: DialogChildRef;
-}
+/** store 变更监听器（返回取消订阅函数）。 */
+type ChangeListener = () => void;
+/** status 过滤模式（collectRecords 的核心能力参数）。 */
+type StatusFilter = "running" | "all";
+/** Pi ExtensionAPI 的最小子集（仅 collectRecords 跳过损坏 manifest 时上报用）。
+ *  解构为局部类型，避免与 subagent-service 的 PiLike 循环依赖。 */
+type RecordStorePi = {
+    appendEntry?: (customType: string, data: unknown) => void;
+} | null | undefined;
 /**
- * L2 跨子进程全局 dialog 串行队列（进程单例）。
+ * Record 容器。进程单例（随 SubagentService 重建）。
  *
- * 用法（createUiRequestHandlerForMode 返回的总 handler 内）：
- * ```ts
- * const dialogQueue = new DialogGlobalQueue();
- * return async (req: UiRequest) => {
- *   // 调用方负责判断：dialog 入队，fire-and-forget 直接调 realHandler
- *   if (isDialogMethod(req.method)) return dialogQueue.enqueue(req, realHandler);
- *   return realHandler(req);
- * };
- * ```
+ * 内存只留 running record——终态 record 在 archive 时立即移除，collectRecords
+ * 读时从 sessions/*.jsonl 重建（[perf] light 头部扫描 + per-file 缓存）。
  *
- * 语义保证：
- *   - FIFO 串行：前一个 handler settle 后才处理下一个
- *   - SR-4：rejectChildDialogs(child) 把该 child 的 pending 全部 resolve 为 {cancelled:true}
- *   - handler 抛错兜底：catch → {cancelled:true} → 继续下一个（队列不卡死）
- *   - 超时上界（LC-3/T2⑦）：每个 dialog 项必有上界——req.timeout 显式传值优先，
- *     未传挂 DEFAULT_DIALOG_TIMEOUT_MS（30min，裁决值）；到点 settle {cancelled:true}
- *     并 warn（恢复指引见 dialogTimeoutLogMessage），L2 processing 释放、队列继续推进。
- *     「等用户无限久」改为默认有界是有意的行为变更。
- *   - 调用方约定只对 dialog 类调 enqueue；fire-and-forget 由调用方直接调 handler 不入队
- *（enqueue 内仍防御性兼容 fire-and-forget，但不保证行为）
+ * 任何 mutate → notifyChange()（仅通知监听器；磁盘缓存靠 stat 戳自校验，不清空）。
  *
- * 线程模型：纯 Promise + 微任务驱动，无锁。Node 单线程 event loop 保证队列状态一致。
+ * record 状态查询面（U10① D6）：按状态枚举 listRunning/collectRecords(statusFilter)、
+ * 按 id 查询 getMutable/findLightById/getFullRecord——方法签名即导出形态，本类零改动。
  *
- * 单 session 假设（M-2，与 index.ts lastSessionId 同源）：本队列是进程级单例（实例挂在
- * globalThis[Symbol.for("@zhushanwen/pi-subagents.dialogQueue")]，见 getOrCreateDialogQueue）。
- * rejectAll() 清空所有 pending dialog——无 per-session 隔离。Pi 当前架构保证单进程
- * 单 session 串行（同进程不会并发多个 session），故 session_shutdown 调 rejectAll() 只会清掉
- * 当前 session 的 pending。若未来 Pi 支持同进程多 session 并发，session A 退出会误清 session B
- * 的 pending dialog——届时需改为 per-session 隔离（入队项 QueueItem 带 sessionId，rejectAll
- * 改 rejectAllForSession(sessionId)，session_shutdown 只清当前 session）。
+ * @experimental execution 运行时面（设计 docs/design/subagent-core-sink-design.md §3.3 D6）：
+ * 一个 minor 周期内允许签名微调，稳定后转常规 semver 承诺。
  */
-declare class DialogGlobalQueue {
-    /** 等待处理的队列（FIFO）。正在处理的项从 queue shift 出后由 current 持有。 */
-    private queue;
-    /** 正在处理的项（handler 已调、未 settle）。用于 rejectChildDialogs 取消占位中的 dialog。 */
-    private current;
-    private processing;
+declare class RecordStore {
+    private readonly sessionsDir;
+    private readonly manifestStore?;
+    private readonly records;
+    private readonly listeners;
+    private _disposed;
+    /** 孤儿终态恢复的已判定缓存（residual-fixes）：resumable 形态无 sidecar 锚，同进程重复调用跳过。 */
+    private orphanJudged;
+    /** Pi handle（用于 appendEntry 上报损坏 manifest）。构造时可空，setPi() 后续注入。
+     *  显式存为字段而非构造参数 readonly：setPi 需要写权限。 */
+    private pi;
+    /** [perf] per-file 缓存（key = sessionFile 绝对路径）。不再整体失效——stat 戳精准校验。
+     *  值含负缓存（确认无 identity 的文件），防每轮全文 fallback 重读。 */
+    private readonly fileCache;
+    /** record id → sessionFile 索引（getFullRecord 按 id 定位文件）。随 fileCache 同步维护。 */
+    private readonly idToFile;
+    /** [perf] sessionsDir 最近一次全量扫描的 mtime（快路径判变，见 reconstructAll）。
+     *  null = 未扫过 / 已 dispose。 */
+    private dirStamp;
+    /** [perf L-1] 首扫惰性装载的磁盘索引只读映像（key = jsonl basename）。
+     *  扫描尾（flushIndexAfterScan）与 readdir 失败路径释放——运行期索引不再被读（L1 接管）。 */
+    private indexEntries;
+    /** [perf L-1] 本轮起未落盘的探测标志：scanFile 走过探测分支即置位。发起写时消费
+     *  （置 false）、写失败恢复；未写路径不清位——未落盘的探测成果跨轮携带直至真正写入。 */
+    private indexDirty;
+    /** [perf L-1] 上次成功落盘墙钟（节流基准）。0 = 从未写过 → 首扫 dirty 必写；
+     *  仅成功分支推进（写失败不推进节流窗，下轮过窗重试）。 */
+    private lastIndexWriteAt;
+    /** [perf L-1] loadIndex 高版本标志的进程级持久态：true 时本进程所有后续扫描均不
+     *  落盘（防 v1/v2 last-writer-wins 覆盖振荡），直至下次 loadIndex 重新评估。 */
+    private indexHigherVersion;
+    constructor(sessionsDir: string, manifestStore?: ManifestStore | undefined, 
+    /** Pi 入口（注入 appendEntry 用于上报损坏 manifest）。
+     *  SubagentService 构造时 this.pi 尚未注入（session_start 之前），传 undefined 兜底；
+     *  后续通过 setPi() 注入（见下）。允许 null = 兼容 PiLike 字段类型。 */
+    pi?: RecordStorePi);
+    /** session_start 后由 SubagentService.initSession 调，注入真实 Pi handle。
+     *  设计为独立方法而非要求构造时必传——RecordStore 在 SubagentService 构造时即建
+     *  （与 sessionsDir/manifestStore 一同初始化），但 this.pi 此时尚未注入。
+     *  后续构造期外的 appendEntry 上报才有意义。 */
+    setPi(pi: RecordStorePi): void;
+    /** 注册新 record。触发 onChange。
+     *  W16 [D4]：record 诞生（→ running）即 append 自描述快照 entry——pi 文件是
+     *  扩展数据持久化权威，custom entry 不进 LLM context。 */
+    register(record: ExecutionRecord): void;
     /**
-     * 入队一个 UI 请求，返回 Promise<UiResponse>。
+     * 归档：record 已被 completeRecord 设置了终态 status。
+     * 立即从内存移除（终态 record 下次读时从 session.jsonl 重建）。
+     * cancelled record 由调用方先写 tombstone（cancel 路径），此处只负责移除。
      *
-     * 调用方约定：只对 dialog 类（isDialogMethod===true）调 enqueue。fire-and-forget 由
-     * 调用方（ui-request-handler-factory.ts）在 enqueue 前判 isDialogMethod 后直接调 handler，
-     * 不经过本队列。enqueue 内仍防御性兼容 fire-and-forget（万一调用方未判）：直接调 handler 返回，
-     * 不入队串行，但调用方不应依赖此防御行为。
+     * W16 [D4]：终态冻结字段（result/endedAt/closedReason）在 completeRecord 已就绪，
+     * 此处 append 的快照即完整终态记录（所有终态路径的必经锚点）。
+     */
+    archive(record: ExecutionRecord): void;
+    /**
+     * W16 [D4]：类外状态写点上报（record-store 内的迁移点 register/archive 已内置）。
      *
-     * dialog 项处理（TC-E4 case 1）：进队列 FIFO 串行，等前一个 settle 后才调 handler
-     *（争输入焦点，防并发弹窗）。
+     * 供 service 层直接改 record.status 的恢复写点调用（chatMode 续轮 idle→running
+     * 冷路径 resumeRound、轮终 finalizeRoundToIdle 回 running-resumable）——这些
+     * 写点绕过 register/archive，若不显式上报，pi 文件缺失该次迁移、重建源滞后。
+     * pi 未注入（session_start 前）时可选链静默降级，不阻断主流程。
+     */
+    reportRecordTransition(record: ExecutionRecord): void;
+    /** 按 id 查找。返回可变 record（仅 runtime 内部用）。 */
+    getMutable(id: string): ExecutionRecord | undefined;
+    /**
+     * abort 所有 running record 的 controller（background 子进程 SIGTERM）。
      *
-     * handler 抛错兜底：catch → 回 {cancelled:true}（dialog 路径，队列不卡死）。
-     * SR-4：opts.child 用于 rejectChildDialogs 关联（dialog 项会被批量 reject，含 current）。
+     * 仅在 SubagentService.dispose（进程退出路径）调用。不做 CAS/tombstone——dispose
+     * 是终局，状态机收尾无意义；目的是让 background 子进程的 AbortSignal 触发 →
+     * runSpawn 的 signal listener → child.kill("SIGTERM")，防止主进程退出后子进程成孤儿。
      *
-     * @param req UI 请求（约定只传 dialog 类；fire-and-forget 防御性兼容）
-     * @param handler 真正执行请求的 handler（TUI/GUI 模式分流后的 realHandler）
-     * @param opts 可选 child 引用（用于 rejectChildDialogs 关联）
-     * @returns handler 的响应；dialog 抛错时回 {cancelled:true}；child close 时回 {cancelled:true}
+     * sync record 无 controller（undefined），跳过——sync 是阻塞调用，主进程不会先于
+     * sync subagent 退出（除非 SIGKILL/崩溃，此时任何清理都无效）。
+     *
+     * 返回被 abort 的 record 数（诊断用）。
      */
-    enqueue(req: UiRequest, handler: UiRequestHandler, opts?: EnqueueOptions): Promise<UiResponse>;
+    abortRunningControllers(): number;
+    /** 列出所有 running record 的只读快照（widget 计数、诊断用）。 */
+    listRunning(): RecordSnapshot[];
+    /** SP-4: 列出所有活跃 record（running + idle）的可变引用。
+     *  供 SubagentService.disposeAllRecords 做级联关闭。 */
+    listAllActive(): ExecutionRecord[];
     /**
-     * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll / 超时 timer
-     * 都通过本方法，settled 标志保证只 settle 一次（防竞争）。
+     * 合并内存(running) + 磁盘(sessions/*.jsonl 重建) → SubagentRecord[]。
      *
-     * #19 单一推进点：本方法 settle Promise + 清状态后，**唯一**调 processNext 推进队列。
-     * processNext 尾部不再调 processNext（旧代码双重推进，虽靠 processing 标志幂等，但语义混乱）。
-     * 为什么推进必须在 settleItem 而非 processNext 尾部：rejectChildDialogs 取消一个永不 settle
-     * 的 current（handler 等用户输入卡死）时，processNext 的 `await item.handler` 永不 resume，
-     * 尾部不会执行；只有 settleItem 里的 processNext 才能打破死锁，推进下一个。
+     *   ╔══════════════════════════════════════════════════════════════════╗
+     *   ║  1. 磁盘源：扫 sessionsDir 的 .jsonl，逐个 scanFile（[perf] 头部    ║
+     *   ║     identity 轻量重建 + stat 戳缓存命中零读取）。cancelled          ║
+     *   ║     tombstone override status。详情字段（eventLog/result/turns）    ║
+     *   ║     缺省，由 getFullRecord(id) 懒加载                              ║
+     *   ║  2. 内存源覆盖（同 id 内存优先——running record 更新鲜）          ║
+     *   ║  3. session 过滤：只留 rootSessionId === rootSessionFilter 的       ║
+     *   ║     record。rootSessionId 缺失（旧文件）的 record 一律排除        ║
+     *   ║     （无法判定归属，隔离优先）。rootSessionFilter 为 undefined       ║
+     *   ║     时不过滤（向后兼容）。                                          ║
+     *   ║  4. statusFilter："running" → 只留 running（内存源）；            ║
+     *   ║                   "all"（默认）→ 内存 + 磁盘                       ║
+     *   ║  5. 排序：STATUS_PRIORITY + startedAt desc                        ║
+     *   ║  6. slice(limit)                                                  ║
+     *   ╚══════════════════════════════════════════════════════════════════╝
      *
-     * [A2-2] 超时 timer 清理也统一收口在这里：任何路径抢先 settle（reject/rejectAll/超时
-     * 自身）都必须撤下 armed timer——handler 永挂时 processNext 内联的 clearTimeout 不可达，
-     * 不在这里清则 timer 到期触发虚假「dialog timed out」warn 且句柄滞留至超时点。
+     * statusFilter="running" 时仍先取够多再过滤（防 limit 截断把 running 滤没），
+     * 与旧 listHandler 的防截断逻辑一致，下沉到此。
+     *
+     * session 隔离：同一 cwd 下多个 Pi session 共享 sessionsDir，靠 rootSessionId
+     * 区分。内存与磁盘源都按 rootSessionFilter 过滤后再 merge/sort/slice。
      */
-    private settleItem;
+    collectRecords(limit: number, statusFilter?: StatusFilter, rootSessionFilter?: string): SubagentRecord[];
     /**
-     * SR-4：把指定 child 的所有 pending dialog resolve 为 {cancelled:true}。
+     * 重建 SubagentRecord 的自描述 entry 落盘入口（签名适配：reportRecordTransition 收
+     * ExecutionRecord，重建孤儿的数据源是 SubagentRecord——直接经 toSubagentRecordEntry
+     * 投影 appendEntry，绕过 recordToSubagent）。pi 未注入时可选链静默。
+     */
+    reportSubagentRecord(record: SubagentRecord): void;
+    /**
+     * 孤儿终态恢复：对重建矩阵分支 4 兜底（running 且无 externalInstance）的 record
+     * 判定真实终态并落 entry，消除「父扩展死后再无人写终态 → 侧栏永久 running」。
      *
-     * 触发场景：子进程 close（用户取消 / crash / 超时 kill）时，其 pending dialog 的 handler
-     * 可能永不 settle（等用户输入），导致 Promise 永挂 + 内存泄漏。本方法批量清理。
+     * 判定（residual-fixes §5.2 三判据 + chat 分流）：
+     * - chatMode = true → 不终态化（跨重启可续聊是产品语义，v4 B-1），落 resumable
+     *   entry 供侧栏 waiting 细分；
+     * - 子 JSONL 末行完整 JSON.parse → closed（closedReason=gc，与分支 2 重建映射一致；
+     *   done/failed 细分由 error 字段经 deriveClosedDisplay 派生）+ 写 .finalized sidecar
+     *   （防重锚——下次重建走分支 2 不再进判定）；
+     * - 末行截断 → closed + error（保守，错误方向安全）+ sidecar；
+     * - 文件不可读（IO 错误，可能暂时）→ 不判终态，落 resumable entry（防御性路径，
+     *   IO 恢复后重开可重判）。
      *
-     * 处理范围（TC-E4 case 2）：
-     *   - 正在处理中（current）的该 child 项：settle {cancelled:true}，解阻塞队列推进下一个
-     *     （关键：handler 可能永不 settle，必须由这里打破死锁）
-     *   - 队列中等待处理的该 child 项：settle {cancelled:true} 并移除
+     * [v2 D3] mainSessionFile = 覆写 merge 数据源（主 session 每 id 末条 entry，与 E1
+     * 的 scanLastRecordEntries 同款通路）：崩溃前的批域标记（collectMode/batchFinalized）
+     * 与轮终 result/model 只活在主文件 entry——重建矩阵（buildRecord）的数据源
+     * （sidecar/子文件 identity）不含它们，覆写前不 merge 就会被抹掉（v2 §2.2 断链 2：
+     * E1 候选集恒空的真根因）。缺省（undefined）时 merge 无源，行为与旧版一致。
+     * 参数为追加式第二参（rootSessionFilter 保持首参）：既有调用面只传过滤参。
      *
-     * 不影响其他 child 的 pending dialog（TC-E4 case 2 子测试 2）。
+     * 防重：orphanJudged 实例级缓存（resumable 形态无 sidecar 锚，同进程重复调用跳过；
+     * 终态形态双重防护 = sidecar + 缓存）。调用方：index.ts session_start 恢复段（一次）。
      */
-    rejectChildDialogs(child: DialogChildRef): void;
+    recoverOrphanRecords(rootSessionFilter?: string, mainSessionFile?: string): void;
     /**
-     * 处理队列下一项（FIFO）。
-     *
-     * processing 标志保证串行：handler 运行期间 processing=true，新的 processNext 调用直接返回；
-     * handler settle 后由 settleItem 清 processing=false 并推进下一项（#19 单一推进点）。
-     *
-     * handler 抛错兜底（TC-E4 case 3）：catch → settle {cancelled:true} → 继续。
-     * 不能让一个失败卡死队列（processing 永远 true）。
+     * 单孤儿 record 的终态判定与落 entry（residual-fixes §5.2 三判据 + chat 分流）。
+     * 防重锚（orphanJudged 标记）已由调用方完成。
      *
-     * LC-3/T2⑦ 超时上界：`await item.handler` 原本无上界——host UI promise 挂死或用户
-     * 永不回答时 processing 恒 true（全局 dialog 死锁）。现在每项挂队列级 timer：
-     * req.timeout（请求方显式传值）优先，未传/非法挂 DEFAULT_DIALOG_TIMEOUT_MS。
-     * 到点 settle {cancelled:true}（完整错误消息落父进程日志，含恢复指引与等待时长），
-     * settleItem 的 settled 标志保证与 handler 完成 / rejectChildDialogs 三方竞态下
-     * 恰 settle 一次。timer 回调闭包捕获 item（非读 this.current）：迟到触发时
-     * settled 标志已置位，直接 noop，不误伤后继项。
+     * [v2 D3] 覆写前 merge（lastEntry = 主 session 同 id 末条 entry 重建，调用方构建）：
+     * 覆写是状态迁移不是信息重建，迁移不应丢末条既有信息。三个落 entry 分支（chatMode
+     * 分流 / IO 保守 / 终态覆写）统一基于 merge 后的 rec，同款口径。
      */
-    private processNext;
+    private finalizeOrphanRecord;
+    /** [v2 D3] 孤儿覆写 merge 字段集：末条 entry 的批域标记 + 轮终正文/模型，仅补 rec 侧
+     *  undefined/空值（model 的空值形态是 ""——light 重建无 model_change entry 时起步
+     *  空串），不覆盖已有值。merge 后写 entry 经 reportSubagentRecord →
+     *  toSubagentRecordEntry 序列化，undefined 字段自然缺省（不引入显式 null）。 */
+    private static mergeOrphanLastEntry;
     /**
-     * #10：把所有 pending dialog（queue + current）全部 settle 为 {cancelled:true}，
-     * 并清空 queue/current/processing 状态。session_shutdown 调用，保证不留永挂 Promise。
-     *
-     * 约定签名：rejectAll(): void（无参，返 void）。Group C 的 index.ts session_shutdown 依赖此契约。
-     *
-     * 幂等：依赖 settleItem 的 settled 标志——重复调用只会对已 settled 项 noop。
-     * 顺序敏感（#19 推进点在 settleItem）：必须先清空 queue 数组再 settle current，
-     * 否则 settleItem(current) 同步触发的 processNext 会从旧 queue 抢占下一项作为新 current，
-     * 避开本方法的 cancel 语义。清空后 processNext 看到空队列直接返回，新 current 不会被抢占。
+     * [E2E 实测缺口] entry-born 孤儿恢复：register entry 已落主 session、但子 session 文件
+     * 从未创建（父进程死在 spawn 窗口期——register 写点与子进程首笔写入之间的窗口；外部
+     * 删除子文件的已知边界同形）。目录扫描（reconstructAll）看不见这类 record（无文件即
+     * 无扫描集），recoverOrphanRecords 判不到，侧栏（runtime entry 扫描源）永久 spinner。
      *
-     * 单 session 假设（M-2）：见类注释。本方法清空所有 pending 不分 session——依赖 Pi 单进程
-     * 单 session 串行保证。session_shutdown handler（index.ts）调用本方法时，进程内只会有当前
-     * session 的 pending dialog。多 session 并发场景的迁移策略（rejectAllForSession）见类注释。
+     * 判定：读主 session 的 subagent-record entry，取每 id 末条；末条 status=running 且
+     * 无子文件锚（不在 reconstructAll 结果中）且不在内存活 record（防误杀刚 register 的
+     * 在途 spawn）→ 按无文件判据收敛：chatMode=true → resumable（分流语义一致）；否则
+     * closed+gc+error（子文件由子进程创建，无文件 = 子进程从未开跑，error 方向安全）。
+     * 调用点：initSession 的 recoverOrphanRecords 之后（session_start，内存恒空）。
      */
-    rejectAll(): void;
-    /** 清空队列状态（仅在 rejectAll 之后调用）。pending Promise 必须先由 rejectAll settle。
-     *  不 settle Promise 的纯状态重置——单独调用会导致 Promise 永挂（footgun），故设为 private。
-     *  外部调用方应使用 rejectAll()（它 settle 所有 pending + 重置状态，是原子操作）。 */
-    private resetState;
-    /** 当前队列长度（测试/诊断用）。含等待处理项（不含 current）。 */
-    get size(): number;
-}
-
-/**
- * [M-1] maxTurns → watchdog 毫秒换算（纯函数，可导出复用）。
- *
- * **换算语义（floor 文档化）**：`max(30min, maxTurns × 5min)`——按 maxTurns 线性估算，
- * 带 30 分钟下限（floor）。maxTurns 换算结果低于 30 分钟时（含 ≤6 的整数与小数，
- * 如 0.5）一律钳到 30 分钟：单 turn 约 5 分钟是经验值（复杂 tool + 长 LLM 响应约
- * 3-4 分钟，留 1-2 分钟余量），maxTurns 过小时不设 floor 会把 watchdog 紧到误杀。
- * - maxTurns=2 → 30min（floor 生效，非 2×5=10min——zsw 曾自实现无 floor 版本致该
- *   配置被 10min 误杀，见 sink 设计 §2.1 例 1；两宿主统一消费本函数即同语义）
- * - maxTurns=6 → 30min（恰为 floor 临界）
- * - maxTurns=20 → 100 分钟
- * - maxTurns=100 → 500 分钟（8 小时+，覆盖全量重构）
- *
- * 旧实现固定 30 分钟（SPAWN_WATCHDOG_MS），与 maxTurns 无关：maxTurns=100 的长任务
- * （全量重构/大规模迁移）正常需数小时，30 分钟到达即被误杀，limiter 机制形同虚设。
- *
- * [预算语义对齐 2026-08] maxTurns 未传/<=0 → 不挂 watchdog（不限）的挂载判定**不归本
- * 函数**——本函数只做换算，挂载判定单一入口是 resolveSpawnWatchdogMs（未传时走
- * SPAWN_WATCHDOG_ENV 兑底，显式 <=0 = 显式不限压过 env）。用户须知风险：watchdog 防
- * 的是 pi 子进程 hang 泄漏（卡死在单个 tool 内 turn_end 永不触发，limiter 失效），
- * 默认关闭意味着无 maxTurns 的 spawn 若 hang 将永不自动回收——须用 SPAWN_WATCHDOG_ENV
- * 显式兑底。
- *
- * [MF-4] 同时是 agent_end keep-alive 的「有活跃后代」等待超时（不 kill 分支），
- * 替代旧固定 2h（WAIT_DESCENDANT_TIMEOUT_MS，已删除）——wave 开发 >2h 不被误杀。
- * [export] 测试可观测（run-spawn-edges MF-4 用例断言 keep-alive 等待超时 = 动态值；
- * max-turns-to-watchdog-ms.test.ts 锚定 floor/边界换算）。
- *
- * @param maxTurns 调用方指定的 turn 上限；调用方保证 > 0（否则走 resolveSpawnWatchdogMs）
- */
-declare function maxTurnsToWatchdogMs(maxTurns: number): number;
-/**
- * kill 所有未退出的 spawned 子进程（dispose 兜底用）。
- *
- * [R1 D6③] 编排扩容：先触发 engine registry 各已实例化引擎的 dispose（常驻资源
- * 归引擎所有，见 EnginePort.dispose / registry.disposeEngines），再杀 per-record
- * children——顺序不可反（D6①：SIGTERM 先发会导致引擎侧 close 帧必丢）。dispose
- * 触发不等待：本函数保持同步契约（宿主调用点零改动，函数签名与导出名不变），
- * 引擎 dispose 的同步面（fire close 帧 + 同步 SIGTERM）由引擎实现保证，异步
- * promise 段（grace→SIGKILL）的 rejection 由 registry 侧 catch 吞掉，防
- * unhandledRejection 崩宿主。
- *
- * [R1 D6 注释契约] spawnedChildren Map 是 per-record 一次性 spawn 模态（一任务一
- * 进程，key=record.id）；引擎持有的常驻进程（跨任务共享）**不进本 Map**——其生命
- * 周期完全归引擎 dispose 管理（边界声明见 RunContext.onChildSpawned）。常驻进程的
- * 注册/回收问题在引擎层解决（R4），此处只立 Map 模态契约。
- *
- * 遍历 spawnedChildren Map 的 values()，对每个「未确认死亡」的子进程发信号。
- * 已退出的子进程在 close/error 事件时已从 Map 移除（按句守卫 removeChildRegistration——
- * Map 当前值仍是该 child 才删，防误删 resume spawn 的新注册），故 Map 中只剩「活着的」
- * 或「已被 kill 但 close 事件尚未回调的」。
- *
- * [T2-⑤ / LC-2] 死亡判定按 exitCode/signalCode 而非 killed 标记——killed=true 只表示
- * 「发过 kill 请求」，不等于「已死」：SIGTERM 可能被无视（卡死在不可中断 native 调用），
- * 旧实现按 killed 跳过会让这类进程脱离最后一次回收窗口。现规则：
- *   - 已确认死亡（exitCode/signalCode 任一非 null）→ 跳过（无论 killed 与否）；
- *   - killed 但未确认死亡（SIGTERM 已发、进程仍在）→ 直接升级 SIGKILL（dispose 是
- *     最后兜底，没有 30s 升级窗口可等——killAllSpawnedChildren 保持快速返回契约）；
- *   - 未 killed 且未确认死亡 → 发调用方指定 signal。
- *
- * 用于 SubagentService.dispose（进程退出路径）：覆盖 sync 子进程（controller 为 undefined，
- * abortRunningControllers 跳过它们）。background 子进程此时已被 abortRunningControllers 经
- * controller.abort 路径 kill，本函数对它们的再处理是 SIGKILL 升级检查（T2-⑤ 语义），
- * 对已死句柄 child.kill 返回 false 无害。
- *
- * 不 await 子进程退出（dispose 要快速返回）。
- *
- * @returns 被 kill 的子进程数（诊断用）
- */
-declare function killAllSpawnedChildren(signal?: NodeJS.Signals): number;
-/** SessionRunner 的依赖注入容器（由 Runtime 提供，解耦 Core 与 Pi SDK 实例）。 */
-interface SessionRunnerContext {
-    /** 进程当前工作目录（作为 spawn 子进程的 cwd 基准）。 */
-    cwd: string;
-    /** agent 配置目录（由 Pi 核心 getAgentDir() 决定，默认 ~/.pi/agent）。 */
-    agentDir: string;
-    /** 额外 skill 目录（ADR-031 废弃 discovery.json 后固定为空数组）。供子进程 --skill 注入。 */
-    skillDirs: string[];
-    /** 主 agent cwd（fork sessionDir 编码用）。fork 未开启时等于 cwd。 */
-    mainCwd: string;
-    /** 主 agent session 文件路径（fork 源）。fork 未开启时 undefined。 */
-    mainSessionFile?: string;
+    recoverEntryOnlyOrphans(mainSessionFile: string | undefined, rootSessionFilter?: string): void;
     /**
-     * worktree 子进程 pid 就绪回调（first header 时触发）。
-     * Runtime 层接线为 WorktreeManager.registerPid，用于注册表补全 pid。
-     * 解耦 Core 与 Runtime——session-runner 不直接依赖 WorktreeManager。
-     * [D5a] 返回 Promise（注册表 pid 补全走跨进程锁内 RMW）；实现方保证不 reject
-     * （WorktreeRegistry.mutate 内部降级兜底），本侧 fire-and-forget 安全。
+     * entry-born 孤儿候选判定（recoverEntryOnlyOrphans 的守卫链拆出）：末条 running、
+     * root session 匹配、无子文件锚、不在内存活 record（防误杀在途 spawn）、未判过。
      */
-    onWorktreePid?: (branch: string, pid: number, sessionFile?: string) => void | Promise<void>;
+    private isEntryOrphanCandidate;
+    /** entry-born 孤儿按无文件判据收敛落 entry：chatMode → resumable（分流语义一致）；
+     *  否则 closed+gc+error（子文件由子进程创建，无文件 = 子进程从未开跑，error 方向安全）。 */
+    private finalizeEntryOnlyOrphan;
     /**
-     * UI 请求处理回调。子进程发 extension_ui_request 时调用。
-     *
-     * 入参 UiRequest（method + channel/channelPayload + method 特定字段），
-     * 返回 UiResponse（{value}/{confirmed}/{cancelled}/{ack}）。
-     * 实现方按 req.channel 分发业务路由（ask_user → AskUserComponent）+
-     * 默认转发（ctx.ui.*），收到用户回答后 resolve。
-     *
-     * 未设置时不再静默忽略——console.warn 兜底（FR-9 可观测性），
-     * W3 接入 SubagentService.notifyMissingHandler 的 appendEntry。
+     * [E1/U5] sync 批崩溃恢复扫描：主 session 文件「每 id 末条 subagent-record entry」
+     * （collectLastRecordEntries + rebuildEntryRecord 组合通路，设计 §3.1.3「标记读取
+     * 通路」——batchFinalized 落标 entry 写主 session 文件，本扫描同文件域才可见；禁走
+     * collectRecords light 路径，它只读子文件 identity 头+sidecar，主 session 落标
+     * entry 不可见）。返回每 id 末条重建的完整 record（含 collectMode/batchFinalized /
+     * 终态五字段，损坏 entry 跳过）；调用方（service.recoverSyncCollectBatch 的 E1 过滤、
+     * recoverOrphanRecords 的覆写 merge）自行取舍。主文件不可读（含新 session 未 flush
+     * 的 ENOENT）→ 空数组静默。
      */
-    uiRequestHandler?: UiRequestHandler;
+    scanLastRecordEntries(mainSessionFile: string | undefined): SubagentRecord[];
+    /** 订阅变更。返回取消订阅函数。 */
+    onChange(listener: ChangeListener): () => void;
+    /** 触发所有监听器（TUI widget/list requestRender）。dispose 后短路。
+     *  [perf] 不清空磁盘缓存：per-file stat 戳自校验（任何磁盘写入改变戳 → 单文件重建），
+     *  内存事件（register/archive）不改变磁盘文件——旧实现整体失效是全量重扫的根因。 */
+    notifyChange(): void;
+    /** session 结束清理。 */
+    dispose(): void;
     /**
-     * L2 跨子进程全局 dialog 串行队列（进程单例，由 SubagentService 注入）。
+     * /resume /fork /new 后复活（dispose 的逆操作）。
      *
-     * SR-4：child close 时调 rejectChildDialogs 清理该 child 在 L2 的 pending dialog，
-     * 防 Promise 永挂（handler 等用户输入永不 settle）导致队列死锁（processing 永远 true，
-     * 其他子进程的 dialog 永久阻塞）。未注入（旧调用方/测试）时 onclose 只清 L1。
+     * [PS-10/T6④] 同步复位 orphanJudged 防重缓存：resumable 形态（IO-error 保守分支 /
+     * chatMode 分流）没有 .finalized sidecar 锚，重判资格完全由本缓存承载——dispose 时
+     * 有 clear（session 结束），但 revive 此前不复位，导致「同进程内曾经的 IO 失败记录
+     * 永久停留 resumable」，与本文件 recoverOrphanRecords 注释承诺的「IO 恢复后重开可重判」
+     * 不符。/new 复活正是「重开」语义：IO 已恢复的记录下次 recoverOrphanRecords 重新判定
+     * 收敛终态；仍不可读的记录重判再落一次 resumable entry（幂等，末条语义不变）。
      */
-    dialogQueue?: DialogGlobalQueue;
-    /** 主进程运行模式（W4 守卫：headless 不注入 ask_user RPC 提示词）。 */
-    mode?: ExtensionMode;
-    /** 所属根 session ID（跨进程身份贯穿用）。子进程的 record.rootSessionId 全指向真 ROOT，
-     *  使主进程 /subagents 能看到完整递归树。runSpawn 无条件注入为子进程 env（设计 recursive-subagent-visibility.md）。 */
-    sessionRootId: string;
-    /** [MF-3] 所属根进程 cwd（跨进程落盘目录编码键）。根进程=自身 cwd；worktree 模式下子进程
-     *  mainCwd=checkout 路径，rootCwd 贯穿真 ROOT——session 文件落盘统一用 ROOT cwd 编码，
-     *  主进程磁盘重建才能看到全树（设计 recursive-subagent-visibility.md）。 */
-    rootCwd: string;
-    /**
-     * [V2 模块 3] chatMode 本轮完成通知挂载点。
+    revive(): void;
+    /**
+     * 四分支 sidecar 矩阵重建（[perf] light 版）。
      *
-     * V2 决策：chatMode 进程长驻（agent_end 不 kill），「本轮完成」的真空闲边界是
-     * `agent_settled`（agent_end 之后、post-run 完成后 emit，见 pi `agent-session.js`
-     * `_runAgentPrompt` finally 块），而非 agent_end（agent_end 时 post-run 可能仍在跑）。
-     * session-runner 在 agent_settled 时调本回调，调用方（subagent-service）注入
-     * notifyComplete 通知父 agent。
+     * 优先级：
+     *   1. .cancelled → closed（closedReason=cancelled）
+     *   2. .finalized → closed（closedReason=sidecar 内容 reason；空/旧格式 → disconnected）
+     *   3. .alive + pid 存活 + 未超软超时 → running, externalInstance=true
+     *   4. 兜底（无 marker、pid 死、超时）→ running（v4 B-1 可续聊语义）
      *
-     * **本步只定义挂载点，不接线**：subagent-service 未改，回调未注入 = no-op。
-     * notify 端到端 + runSpawn resolve 语义重构留 Step 4（与统一投递 + subagent-service
-     * 一起系统处理）。非 chatMode 路径不触发 agent_settled handler，本字段无影响。
+     * [perf]：逐文件 scanFile（stat 戳校验 + 头部 identity 轻量重建）。命中缓存的
+     * 文件零文件读取；变化的文件只重建自身，其余 N-1 个复用缓存。
      *
-     * @param record 当前 ExecutionRecord（chatMode、已完成本轮）
+     * session 隔离：rootSessionFilter 非空时，只保留 rootSessionId 匹配的 record。
+     * rootSessionId 缺失（旧文件，未带身份字段）一律排除（无法判定归属）。
      */
-    onRoundSettled?: (record: ExecutionRecord) => void;
-}
-/**
- * resume spawn 选项——重开已结束的 session 文件继续对话（M1 基建）。
- *
- * resume 时 pi 子进程用 `--session <sessionFile> --mode rpc` 续写原文件（探针 P-1/P-8
- * 实测：路径不变、entry 续写、上下文保留）。runSpawn 收到此参数后：
- *   - buildSpawnArgs 追加 `--session <sessionFile>`
- *   - record.sessionFile 提前设为 resume.sessionFile（handshake 只验证 spawn 成功，不覆盖）
- *   - model/thinkingLevel 优先用此处的值（防多轮对话模型漂移，探针 P-10），否则回退 opts.resolved
- *
- * 注意：M1 只暴露能力，messageHandler（M2）才会真正调用。
- */
-interface SpawnResumeOpts {
-    /** resume 目标 session 文件绝对路径（pi `--session` 参数值）。 */
-    sessionFile: string;
+    private reconstructAll;
     /**
-     * resume 时覆盖的 model（`"provider/id"` 格式，防漂移，探针 P-10 证明必须传）；
-     * 不传则回退 opts.resolved。
+     * 扫描单文件：stat 戳（jsonl + 3 sidecar）校验，全同 → 复用缓存（零文件读取，
+     * 含负缓存直接返回 null）；否则重建 light。
+     * identity 定位两级：头部 64KB（首轮会话）→ 全文 fallback（续聊场景 identity
+     * append 在尾部）；两级都找不到 → 写负缓存（防每轮全文重读）。
+     * 返回 null：文件消失/读失败/无 identity → 跳过。
      */
-    model?: string;
-    /** resume 时覆盖的 thinkingLevel；不传则回退 opts.resolved。 */
-    thinkingLevel?: string;
-}
-declare function killRecordChildWithEscalation(recordId: string, source: string): void;
-
-/** chat 域轮次的身份快照（编排层 resolveIdentity 的产物形态——引擎侧透传给 launcher；
- *  身份解析产物是 host 编排件，不并入任务声明 AgentCallOpts，见 ChatRoundTicket 注释）。 */
-interface ChatRoundIdentity {
-    agent: string;
-    agentConfig: AgentConfig | undefined;
-    resolved: ResolvedModel;
-}
-/**
- * chat 域预备轮次交接包（D2 单轨）：编排层（executeViaEngine / 冷路径续轮）预建的
- * record/opts/identity/host 上下文经 run 的 ctx.taskId 交接给引擎。
- *
- * [u-3b D6 双形态消化评估结论：双形态保留（结构性裁决，非过渡态）]
- * run 的 task 形参（AgentCallOpts，任务声明）与 ticket 是两个变化轴的载体，不可合一：
- *   - task 形参 = 纯数据任务声明（跨引擎持久化语义，workflow 域由 SAR 直传）；
- *   - ticket = chat 域 host 编排交接件，主体是运行期对象与 Service 内部形态——
- *     ① ctx: SessionRunnerContext 回调簇 / signal / priority / stream 是运行期句柄
- *        （port 设计 §3.3.5 删字段去向：运行期对象不入任务声明）；
- *     ② record: ExecutionRecord 是 Service 内部 record 生命周期对象；
- *     ③ resume: SpawnResumeOpts 是 session-runner 私有 spawn 选项；
- *     ④ opts: ExecuteOptions 是 Service 内部编排形状（D6 明确保留的类型），且是
- *        forkFromSessionFile 的唯一 lossless 载体（该字段仅 pi chat 域消费，不入
- *        合流形状——chat pi fork-from 链路 = 壳 fork-from action → ExecuteOptions
- *        .forkFromSessionFile → 本 ticket → runChatRound → runAndFinalize → runSpawn，
- *        全程不经任务声明，由 pi-engine 测试锁定零回归）。
- * 把任一类塞进 AgentCallOpts 会让 engine 契约反向耦合 execution 内部类型。故 chat
- * 分支 ticket 优先消费（task 形参仅满足 port 签名），workflow 分支消费 task 形参——
- * 这是「编排交接」与「任务声明」的职责分界，不是待消除的中间态。
- */
-interface ChatRoundTicket {
-    record: ExecutionRecord;
-    opts: ExecuteOptions;
-    identity: ChatRoundIdentity;
-    ctx: SessionRunnerContext;
-    signal: AbortSignal | undefined;
-    priority: number;
-    stream?: SubagentStream;
-    /** resume 选项（冷路径续轮）：重开已 idle 的 session 续聊。undefined = 新 session。 */
-    resume?: SpawnResumeOpts;
-}
-/**
- * PiEngine 委托的编排服务面——SubagentService 的结构子集（鸭子类型：生产实现是
- * SubagentService 单例；测试可注入 fake，不必构造整个 Service）。
- * 为什么用结构接口而非直接 import SubagentService 类型：pi-engine 只依赖它实际消费的
- * 方法面，防 Service 内部演进（增删私有方法）连锁影响引擎适配层。
- *
- * chat 域轮次面（takeChatRound/runChatRound/resumeChatRound/reportRecordTransition）
- * 声明为可选项（u-2c 聚合后形态）：两处生产绑定（registration.ts / SAR）均绑
- * subagentService.asEngineService（= piEngineServiceAdapter），可选面实际恒被提供——
- * 并非「仅 chat 绑定的实例提供、SAR 的实例不提供」。两域分支改由 taskId 空间区分：
- * chat ticket 的 key 是 record.id（编排层预建时 set），SAR 的 taskId 是独立铸造的
- * `sa-<uuid>`（subprocess-agent-runner.ts），恒不在 ticket map 中 → run 的
- * takeChatRound 探测恒 miss → 恒走 executeAndAwait 分支。可选面保留 optional 的意义
- * 是测试可注入仅含 workflow 面的 fake；requireResumeFace / runChatTicket 的 throw
- * 分支在生产绑定（asEngineService 全量提供）下不可达，仅防 fake 绑定漏面时静默
- * 丢消息/丢轮次。
- */
-interface PiEngineService {
-    executeAndAwait(opts: ExecuteOptions, signal?: AbortSignal, onEvent?: (event: AgentEvent) => void, stream?: SubagentStream): Promise<AgentResult>;
-    getRecordForAction(id: string): ExecutionRecord;
-    closeSubagent(record: ExecutionRecord, force: boolean): Promise<void>;
-    cancel(id: string): boolean;
-    collectRecords(limit: number, statusFilter?: StatusFilter): SubagentRecord[];
-    /** chat 域轮次交接（run 的 chat 分支入口）：按 taskId 取走预备包（一次性消费）。 */
-    takeChatRound?(taskId: string): ChatRoundTicket | undefined;
-    /** 执行预备的 chat 轮次（编排归 Service：pool 槽 + runSpawn + 终态迁移）。 */
-    runChatRound?(ticket: ChatRoundTicket): Promise<AgentResult$1>;
-    /** 冷路径续轮（interact message 分支的编排回调：守卫 + record 迁移 + 预备轮次 kick-off）。 */
-    resumeChatRound?(record: ExecutionRecord, text: string): void;
-    /** record 状态迁移上报（热路径投递后让 runtime 派生缓存失效 / GUI 回流）。 */
-    reportRecordTransition?(record: ExecutionRecord): void;
-}
-
-/**
- * 把 'pi' 引擎登记进 registry（幂等——组合根可能多次执行，如每次 session_start）。
- * 工厂绑进程单例 getSubagentService：惰性求值，session_start 注入前调用 getEngine
- * 只会拿到引擎实例，真正 run 时才解析服务。
- */
-declare function registerPiEngine(): void;
-
-/** provider 注册表条目的最小消费面（凭据 + 模型清单校验）。 */
-interface ZcodeProviderEntry {
-    options?: {
-        apiKey?: unknown;
-    };
-    models?: Record<string, unknown>;
-    [k: string]: unknown;
-}
-/** [R4] 规范化全名 provider/model → create 参数的 per-session model 拆分（A.2 ① strict 对象）。 */
-declare function splitZcodeModelRef(modelRef: string): {
-    providerId: string;
-    modelId: string;
-};
-declare function hasApiKey(entry: ZcodeProviderEntry): boolean;
-interface ZcodeSourcePaths {
-    /** 桌面登录态 config（唯一凭据源）。缺省 ~/.zcode/v2/config.json。 */
-    v2ConfigPath?: string;
-}
-/**
- * 短名（无 provider 前缀）解析的默认 provider（zsub DEFAULT_PROVIDER_ID 同构）。
- * 导出（sink 设计 U1 模型切分四件之一）：barrel re-export 供第三宿主模型路由消费，
- * 实现体内聚本文件不挪。
- */
-declare const DEFAULT_PROVIDER_ID = "builtin:bigmodel-coding-plan";
-
-/** ZcodeEngine 构造依赖（全部可注入——测试不依赖真机 CLI/真凭据）。 */
-interface ZcodeEngineDeps {
+    private scanFile;
     /**
-     * 引擎数据目录（journal 分组根 <dir>/engines/zcode/shared/ 与 stderr 日志落点）。
-     * 来源通道（宿主 dataDir）见 registration.ts 缺省解析。
-     */
-    engineDataDir: () => string;
-    /** zcode CLI 路径；缺省 ZCODE_CLI_DEFAULT_PATH。 */
-    cliPath?: string;
-    /** 源 config 路径覆盖（测试注入临时源；缺省读 ~/.zcode）。 */
-    sources?: ZcodeSourcePaths;
-    /** 版本探测执行器（probe check "version"；测试注入 fake 防真实子进程）。 */
-    probeVersion?: (cliPath: string) => Promise<string | undefined>;
-    /** env 基底（测试注入；缺省 process.env——app-server env 组装经它）。 */
-    processEnv?: NodeJS.ProcessEnv;
-}
-/** zcode 引擎适配器。 */
-declare class ZcodeEngine implements EnginePort {
-    readonly id = "zcode";
-    private readonly deps;
-    private probeCache;
-    private appserverRuntime;
-    /**
-     * [P0-1 U4] 引擎停机标志（dispose 置位，不重置——dispose 后首个 run 走重建路径
-     * 不受影响）：瞬时重试判定据此排除 dispose 收割引发的崩溃形态——停机后的重试轮
-     * 会经 ensureAppServerRuntime 惰性重建进程（复活已停机引擎），违背 dispose 防泄漏
-     * 语义。
-     */
-    private disposed;
-    constructor(deps: ZcodeEngineDeps);
-    /**
-     * zcode 链路实际接通的能力（D3 链路口径。声明升级必须先改链路再改声明（C4 原则）。
-     */
-    capabilities(): EngineCapabilities;
-    /** 探针（D7）：二进制存在 + 版本解析（zcode 无公开契约，版本漂移的入口信号）。 */
-    probe(opts?: {
-        force?: boolean;
-    }): Promise<ProbeReport>;
-    /** check 1：二进制存在性（isFile 才算——同名目录不是可执行入口）。 */
-    private probeBinaryCheck;
-    /** check 2：`--version` 解析（probeVersion 可注入——测试 fake 防真实子进程）。 */
-    private probeVersionCheck;
-    /** 探针失败的恢复指引（§3.3.3 终态四：版本确认命令 + 探针重跑 + 调研文档路径）。 */
-    private probeFailureRecovery;
-    /** D1 主语义：唯一通道 = app-server 常驻连接（spawn 降级链已删除）。 */
-    run(task: AgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
-    /**
-     * 常驻路径主编排：模型解析（v2 单源校验）→ 惰性连接 + runTurn（事件时序前移：
-     * text_delta 流式、终态后 message_end/turn_end）→ schema 仿真重试 → outcome/handle。
-     * poolKey 固定 'shared'（共享宿主 HOME，无池），onPoolResolved 在 prepare 期、
-     * onHandleReady 在 create 应答后（§3.4 不变量 3）。
-     */
-    private runViaAppServer;
-    /** pre-aborted 短路收口：合成中止 outcome + 'shared' 锚定 handle。 */
-    private abortedAppServerRun;
-    /**
-     * 首轮执行 + 双重试编排（常驻路径）：
-     * - **schema 仿真重试**（既有语义）：parsed 但校验失败时重试一次（强化 JSON 输出
-     *   指令——与 structured-output 的重试语义对齐）。
-     * - **瞬时失败自动重试一次**（[P0-1 U4/D6]）：末次 attempt 为 timeout 类（idle/
-     *   ceiling）或连接崩溃类失败且非用户 abort → 用新会话重跑一次（attempt 本就每次
-     *   新建会话）。重试轮 prompt 用 basePrompt 原样重跑（失败形态非 schema），文案补
-     *   「已自动重试一次」句（retried 标记仅对真实发生的重试生效）。
-     *
-     * 两次重试一次封顶各自独立（D6 被否①：多次重试/指数退避不做——重跑一轮=整任务
-     * 重算，一次封顶）。组合序：瞬时重试在前、schema 重试在后——瞬时重试轮 parsed 且
-     * 校验失败时仍进 schema 重试（末次 attempt 语义，schema 重试编排保持现状不动）。
+     * [perf L-1] 磁盘索引查询（首扫惰性装载，miss/空索引时 get 恒 undefined = 无索引）。
+     * 条目戳匹配 jsonl 当前 stat → 零内容读取构造缓存条目。sidecar payload（tombstone/
+     * alive）是活态数据，沿用探测分支的每轮重读语义；finalized reason 静态数据仅在
+     * sidecar 存在时读一次（文件小，成本可忽略）。
      *
-     * 重试轮是独立会话的独立 LLM 调用：token 计入 outcome.usage 总量；事件面
-     * text_delta 按实际流出（含失败轮——journal 记录真实流水），message_end/turn_end
-     * 只在最终轮终态后合成（不变量 2/5）。
+     * 返回 undefined = 索引未命中/戳不匹配（调用方落到原三级探测）；null = 负条目命中
+     * （「确认无 identity」跨实例持久，零探测跳过，与内存负缓存同款形态）。
      */
-    private runAppServerAttemptsWithRetry;
-    /** 常驻路径的 handle 合成（poolKey 固定 'shared'；dbPath = 宿主 HOME 绝对路径）。 */
-    private appServerHandle;
+    private buildEntryFromIndex;
     /**
-     * 单轮常驻执行：runTurn 组合面 + D3 abort 链 + 事件前移（text_delta 实时流出；
-     * 终态数据经 read 兜底收口后才 resolve——不变量 1/2）。
+     * [perf L-1] 扫描尾索引落盘（节流）：释放映像 → dirty/高版本/60s 节流窗三重门 →
+     * fire-and-forget saveIndex（fileCache 全量投影）。写决策与发起在同步栈（collectRecords
+     * 返回后不会再有本轮写）；仅写完成的回调（推进节流窗）是异步的。所有 return 路径均
+     * 不清 dirty——未落盘的探测成果跨轮携带，直至真正写入。
      *
-     * @param opts turnTimeoutMs：显式总上界传参面（D2 内部传参点）——U4/D6 预算继承
-     *   向重试轮传剩余值；缺省不传（channel 走 env→默认，首轮行为）。
-     *   retried：瞬时重试轮标记——失败文案补「已自动重试一次」句（F-1/F-4）。
-     */
-    private attemptAppServerTurn;
-    /**
-     * killChain 后等待连接 finalize 实际完成（child 置空 + onClose 广播）再宣告链终局：
-     * shutdown resolve 于 `exit` 事件，而 finalize 挂 `close`（stdio 排空）——两者之间的
-     * 事件窗口内 conn.child 仍非 null，紧接的下一任务 request 会复用垂死进程（写入成功
-     * 但必败，走崩溃路径）而非触发重建。与 shutdownRuntimeAndDisposeChannel 的
-     * HARVEST_GRACE 同款 race 形态（close 永不到达不挂死）。超时入口的 await 链终局
-     * 语义（D6 重试时序依据）因此是「进程收割确认完成」而非「SIGTERM 已发出」。
-     */
-    private awaitConnFinalized;
-    /**
-     * D3 abort 链执行体（双入口分岔，P0-1 U2 参数化——设计
-     * timeout-zcode-turn-and-settled-watchdog.md §6 D3 v1.1）：
-     * - **用户取消入口**（`escalateOn: "turn-settled"`，现状语义零改动；fire-and-forget——
-     *   与 turn promise 并行推进）：stop 帧（超时 ZCODE_APPSERVER_STOP_TIMEOUT_MS）→
-     *   grace 窗口内 turn 落定即止（不杀共享进程）→ 超窗 killChain（conn.shutdown 全序：
-     *   SIGTERM→grace→SIGKILL）。turn 的最终落定由 attempt 主路径 await 收口，本链不
-     *   直接产出终态。abort 与 create 竞态（signal 先到、session 未建立）：等会话建立
-     *   （带上限）再发 stop——否则 stop 永远发不出，直接连坐杀共享进程。
-     * - **超时入口**（`escalateOn: "stop-outcome"`，channel 判死后由 catch await 链终局）：
-     *   turn 已 reject，对它 race 恒真不可用（v1 击穿点）——升级判据改挂在 **stop 应答
-     *   三态**：①成功应答 → 服务端接受停 turn，止损确认，链终止；②协议性 error 应答
-     *   （有 error 帧即控制面活的证据，多因 runTurn finally 的 closeSession 先行关会话，
-     *   健康形态竞态）→ 链终止**不升级**（止损由 close 回收 + 服务端自治承担；把
-     *   「stop 报错」一律升级会误杀健康共享进程并连坐并发任务）；③超时/写入失败/进程
-     *   死等连接级失败（控制面死）→ killChain 升级。判据实现依据：error 应答帧 reject
-     *   携带 number code（isAppServerRpcError）；连接级失败是无 code 的新 Error
-     *   （connection.request 三态 reject 形态）。返回值即止损路径（超时入口的 outcome
-     *   文案素材——D3 强制可观测面）。
-     */
-    private appServerAbortChain;
-    /**
-     * 惰性获取常驻运行时（D1：每引擎实例一条连接，全任务共享；连接自身的崩溃重建在
-     * connection 层内部完成——同一条代码路径，§3.4 不变量 4）。常驻进程不进宿主
-     * spawnedChildren、不调 onChildSpawned（D6——生命周期归 dispose）。进程级 --cwd
-     * 用引擎数据目录（连接跨任务共享的中性位置，工作区由 create 的
-     * workspace.workspacePath 按任务传递——D10 基线不预设任务级进程 cwd）。
-     * spawn 经 fs 拦截 wrapper（appserver-launcher：cli config 读取重定向为
-     * 「真实文件 + v2 provider 注入」——CLI 形态 app-server 在共享宿主 HOME 下的
-     * 唯一凭据供数通路，机制与漂移面见该文件头注）。
-     */
-    private ensureAppServerRuntime;
-    /**
-     * [R5 修复 R4 既有竞态] shutdown → 等崩溃收割实际发生 → channel 退订。killChain 在
-     * `exit` 事件 resolve，而连接 finalize（onClose → channel 的 failAllTurns）挂
-     * `close` 事件——两者之间有一个事件循环窗口：shutdown resolve 后立即退订，在途
-     * turn 会错过收割、挂到 turnTimeoutMs（300s）。退订前等 onClose 触发（本方法先于
-     * shutdown 订阅；channel 的订阅在构造期更早——其 failAllTurns 先于本 promise
-     * resolve 执行）；ZCODE_APPSERVER_HARVEST_GRACE_MS 兜底防 `close` 永不到达时挂死。
-     * [P0-1 U5/D7] grace race 输掉（close 迟到/永不到达——stdio 被孙进程持有排空不
-     * 尽等病态形态）时，channel.dispose() 内置的 dispose 收割（failAllTurns 先于退订，
-     * SessionChannel.dispose）兜底在途 turn——退化终点从「挂满 turn 自身 idle/总上界
-     * 预算」收敛为「grace 窗口内明确失败」（设计 §3.4 退化路径闭合）；race 窗口与
-     * awaitConnFinalized 同源同量级（ZCODE_APPSERVER_HARVEST_GRACE_MS）。正常 close
-     * 先到时 onClose 收割先行，dispose 收割幂等 no-op（零回归）。
-     */
-    private shutdownRuntimeAndDisposeChannel;
-    /**
-     * [R1 D6 主体] 引擎停机面：①fire 全部在途会话的 session/close 帧（不等待
-     * 应答——D6① 顺序规定：close 帧必须先于 SIGTERM，否则对面来不及处理即被杀）→
-     * ②同步 SIGTERM（conn.shutdown 调用内 killChain 前缀同步执行——同步面在返回
-     * Promise 前完成）→ ③grace → SIGKILL（异步面，Promise resolve 于进程退出）。
-     * 幂等：运行时字段取走即置空，二次调用零副作用；dispose 后首个 run 经
-     * ensureAppServerRuntime 自动重建（与崩溃重建同一代码路径，不变量 4）。
-     */
-    dispose(): Promise<void>;
-    /** 终态合成（extension-conventions 函数 80 行上限，从 run 提取）：aborted / run-failed / parsed 三分支。 */
-    private finalizeOutcome;
-    /** abort 合成终态：exitCode=null（record 正常收尾，不留僵尸）。 */
-    private applyAbortedOutcome;
-    /**
-     * run-failed 合成终态：错误信息由 buildAppServerRunFailedMessage 产出（已含恢复
-     * 指引）直接透传；附带的会话 id 落 outcome.sessionId（错误规格表 -32004 行「含会话
-     * id」——appServerHandle 据此写 handle.sessionRef，run-failed 不再恒缺）。
-     */
-    private applyRunFailedOutcome;
-    /** parsed 合成终态：content/sessionId/usage 落位 + schema 校验分流 + coarse 事件。 */
-    private applyParsedOutcome;
-    /**
-     * D1 可选面：zcode 首期不支持 conversation（capabilities 声明）——同步拒绝、
-     * 不创建进程，文案给可操作建议（A11）。
-     */
-    interact(_handle: EngineHandle, _action: InteractAction): Promise<InteractResult>;
-    /** [U7] 模型可发现性：v2 桌面登录态聚合（带凭据 provider × models），失败安全返回清单本身可能为空。 */
-    listModels(): Array<{
-        id: string;
-        name?: string;
-    }>;
+     * 并发安全：节流基准只在写成功后推进，W1 在途时新一轮过窗扫描可再 dispatch W2（不做
+     * 进程内排队——fire-and-forget 语义保持）。安全性由 saveIndex 的 tmp 唯一性
+     * （pid+单调序号）保证：交错 rename 的终态必为某一次的完整快照（last-writer-wins，
+     * 陈旧快照胜出时下轮戳不匹配自愈），不依赖本方法串行化。
+     */
+    private flushIndexAfterScan;
     /**
-     * [u-h2 D2-2] 派发同步期 model 校验：委托 resolveZcodeModelRef（与 run prepare 期
-     * 同一函数——canonicalRef 归一化、短名缺省 provider、凭据与清单校验单一权威，无双实现）。
-     * modelRef undefined = 返回引擎缺省模型 canonical 全名（ZCODE_FALLBACK_DEFAULT_MODEL，
-     * D2-1 ctxModel 不透传的承接面）。校验失败原样抛 ZcodePrepareError，由编排层
-     * （engine/model-validation.ts）包装成「引擎与模型不配套」文案。
+     * [perf L-1] fileCache 全量投影 → 索引快照（basename → 正/负条目）。
+     * 投影式单一 SSOT：不维护第二份可变索引映像（防双轨漂移）；fileCache 已被
+     * reconstructAll 修剪掉消失文件（修剪时置 indexDirty），下次过窗写时快照清除
+     * 磁盘上的陈旧条目。
      */
-    validateModel(modelRef: string | undefined): {
-        canonicalRef: string;
-    };
+    private projectIndexEntries;
     /**
-     * D6 read 三级降级：①sqlite 原生读取 → ②宿主 event journal 重放（对齐点①接线：
-     * replayJournalToSessionView 复用 live reducer，重放等价性见 §3.3.6）→ ③outcome-only。
-     * sessionId 缺失（解析失败的 run 无法定位 session）跳过①级；②级依赖
-     * handle.journalPath（宿主 run 后回填）。dbPath：新 handle 恒绝对路径（宿主
-     * ~/.zcode/cli/db/db.sqlite，tier1 精确匹配白名单见方法体）；旧 records（池时代）
-     * 的相对路径仍按 poolKey 锚定解析（read 兼容旧数据，池目录不存在时自然落②级
-     * journal 降级）。
-     */
-    read(handle: EngineHandle): Promise<SessionView>;
-    /**
-     * [RX2-F1] appserver 路径的非常见档位提示：thinkingLevel → thoughtLevel 恒等透传
-     * （F15a），全 7 档放行不拦截——但部分档位（off/minimal/medium/xhigh 等）不在部分
-     * 模型的合法值域内（如 GLM-5.3 仅接受 low/high/max），app-server 侧对不支持的档位
-     * warn-skip（会话照常但档位静默失效），调用方无从察觉。此处仅对
-     * COMMON_THOUGHT_LEVELS 之外的档位出声一行提示（措辞是「若不支持将被忽略/回落」的
-     * 或然警告，非无效断言）；是否真不支持由目标模型决定，core 不做权威校验（引擎层
-     * 不掌握各模型值域）。
-     */
-    private warnThoughtLevelUncommon;
-    /**
-     * [F16b] ctxModel 忽略留痕：ctxModel 是 pi 链路的第三层兜底（port.ts 契约——
-     * 依赖 pi resolveModel 链的引擎才消费它），zcode 自带 provider 体系与缺省模型
-     * （resolveZcodeModelRef：requested > ZCODE_FALLBACK_DEFAULT_MODEL），不消费
-     * ctxModel。「调用方给了 ctxModel 但 task.model 未显式指定」时出声一行，说明
-     * 实际落引擎缺省模型（含实际 model id）——防静默降档无据可查。只在「ctx 有模型
-     * 但被忽略」场景输出：显式 task.model 走正常解析链、ctx 本就无模型属预期缺省，
-     * 均不出声（避免噪音）。
-     */
-    private warnIgnoredCtxModel;
-    /**
-     * persona 拼接后的完整 prompt（personaInjection: 'prompt'——zcode 无 flag 通道）：
-     * appendSystemPrompt 段在前（人设/约束语境——D6 合流后 persona≡skillPath+
-     * appendSystemPrompt 平铺，由上游解析进 appendSystemPrompt），task 正文居中，
-     * schema 仿真段尾置（common/schema-emulation 公共层产出）。
-     */
-    private buildPrompt;
-}
-/**
- * prepare 期能力拒绝的历史载体（code 进 message 前缀，调用方可程序化分流）。
- *  [U10① D6] execution 运行时面错误族成员：export 供宿主 instanceof 分流。
- *  [D3-④ 合并注] 引擎内 shape 拒绝已上提 common/capability-gate（EngineError 承载），
- *  本引擎不再抛出；保留 export 维持错误族面兼容（execution-runtime-face.test 消费），
- *  待波 2 收口时随 export 面清理一并裁决。
- */
-declare class ZcodeTaskShapeError extends Error {
-    readonly code: string;
-    constructor(code: string, message: string);
-}
-
-/** 构造 ZcodeEngine（DI 工厂——测试/宿主注入 deps）。 */
-declare function createZcodeEngine(deps: ZcodeEngineDeps): ZcodeEngine;
-/**
- * 把 'zcode' 引擎登记进 registry（幂等——组合根可能多次执行，registerEngine 覆盖
- * 语义）。工厂惰性：登记不触发任何文件/进程探测，首次 getEngine 才建实例。
- */
-declare function registerZcodeEngine(engineDataDir?: () => string): void;
-
-/**
- * 缺省引擎 id（D9：缺省引擎 = 'pi'，回填期零风险默认）。
- * P1 无 per-agent/调用级 engine 字段（P4 配置路由引入三层优先级），一切执行恒走缺省。
- */
-declare const DEFAULT_ENGINE_ID = "pi";
-/**
- * defaultEngine 缺省归一（单一权威源）：空白 / undefined 归一到缺省引擎（'pi'）。
- * 引擎感知检测 diff 与状态段渲染必须对同一读取结果给出同一引擎 id——若两处各自
- * 内联归一，一致性只靠注释人工耦合，漂移即两处说谎；故收敛到本函数供各处调用。
- * sanitize 保证透传值非空，但可能带首尾空格，故 trim 后再判。
- */
-declare function normalizeEngineId(engine: string | undefined): string;
-
-/**
- * 恒在状态段 <current_subagent_engine>（设计 D6：pi 引擎也声明——AI 不需要
- * 「从段缺失反推」当前引擎）。三种形态（§3.1 终态逐字基准 + 失败路径表）：
- *   - 缺省 / pi：声明 pi + 指向上方核心段 <available_provider_models>（无冲突 bullet）；
- *   - 非 pi 且已注册：指向下方该引擎清单段 + 「pi registry id 不适用」+ AGENTS.md
- *     冲突裁决 bullet + 省略 model 用引擎默认；
- *   - 未注册引擎（如配置手误 "ghost"）：如实显示配置值 + 警告行（派发将报
- *     engine_not_found，指引修 subagents/config.json）——G4 诚实降级：不静默、不伪造。
- *
- * 字节稳定（D7）：纯字符串确定性拼装（无 localeCompare / 无随机序 / 无时间态）；
- * 引擎注册与否经 hasEngine 只读判断（不取实例、不触发工厂副作用），同输入恒同输出。
- */
-declare function buildSubagentEngineSection(defaultEngine: string | undefined): string;
-/**
- * 依据全局 defaultEngine 生成追加段（不含前导换行）。
- *
- * 规则（设计 §3.1 失败路径表 + G4 + U2 一致性审查修订）：
- *   - defaultEngine 为 pi / 缺省 → 不注入（pi 段已由核心提供）；
- *   - 引擎未注册 → 不注入（状态段 <current_subagent_engine> 已有警告行，避免双份）；
- *   - 已注册且 listModels 有清单 → 注入该引擎段（渲染不变）；
- *   - 已注册但 listModels 未实现 / 返回 null → 「与主 agent 模型体系一致」声明段
- *     （port 契约语义：引擎无自有 provider 枚举面，id 见上方核心段，见
- *     buildCoreAlignedHint）；
- *   - 已注册但空清单 / listModels 抛异常 → 「无凭据模型」提示行段（引擎 provider
- *     体系存在但当前无可用模型，见 buildEmptyModelsHint；从「静默不注入」改为如实
- *     声明——空清单返回空串会让 AI 误以为没有任何引擎清单可看）。
- * fail-safe：listModels 异常同样落提示行段、不向外抛（注入失败不阻塞 agent loop——
- * 与 system-prompt extension 的 before_agent_start 处置一致）。
- */
-declare function buildEngineModelsPromptAppend(defaultEngine: string | undefined): string;
+     * [perf] byId 索引直查 light record（单文件 stat 校验，不触发 getFullRecord 的
+     * 全量重建）。idToFile 未热（进程重启后尚未扫描过）时返回 undefined，调用方
+     * 自行兜底全目录扫描——用于把「跨重启后每条 message 一次 collectRecords 全扫」
+     * 降为 O(1) 索引命中。
+     */
+    findLightById(id: string): SubagentRecord | undefined;
+    /**
+     * [perf] 单 record 详情懒加载：内存 running record 投影全量；磁盘 record 全量重建
+     * （reconstructFromFile）并套用同一 sidecar 状态矩阵。结果缓存在 FileCacheEntry.full，
+     * stat 戳变化时随 light 一起失效。列表 collectRecords 返回 light（无 eventLog/
+     * result/turns 等重数据），详情面板/工具 list 按需调本方法补齐。
+     *
+     * 返回 undefined：id 不存在（内存与磁盘均无）。reconstructFromFile 失败（无
+     * assistant message 等）→ 返回 light（无详情可补，缓存哨兵防重复全文重读）。
+     */
+    getFullRecord(id: string): SubagentRecord | undefined;
+    /** alive 探活刷新（scanFile 缓存命中与 reconstructAll 快路径共用）：
+     *  分支 3 的 running + alive 条目每扫重查 pid（结果不落盘，进程死亡无 IO），
+     *  保留旧实现「每次 collectRecords 重新 isProcessAlive」的语义。 */
+    private static refreshAlive;
+    /** identity 基底 + sidecar 状态矩阵 → 缓存条目（索引命中与探测重建两分支的公共装配点）。 */
+    private static buildFileCacheEntry;
+    /** identity 基底（头部 light 或全量 recon）+ 四分支 sidecar 状态矩阵 → SubagentRecord。 */
+    private static buildRecord;
+    /** 排序比较器：status priority（running<failed<cancelled<done）+ startedAt desc。 */
+    private static compareRecords;
+    /** FR-8: 同步读取所有 manifest 记录（封装 ManifestStore.listAllSync，消除反射访问）。 */
+    private readManifestsSync;
+    /** FR-8: ManifestRecord → SubagentRecord（manifest 源投影）。
+     *  task/slug/model 从 manifest 真实值投影（配合 writeManifest 补字段），缺失兜底空串。
+     *  status 越界（mapManifestStatus 返回 null）时返回 null，由 collectRecords 跳过。 */
+    private static manifestToSubagent;
+    /** ExecutionRecord → SubagentRecord（内存源投影）。 */
+    private static recordToSubagent;
+}
 
 /**
- * record 携带的引擎 handle 消费面（EngineHandleData 的结构子集，双端契约不变）：
- * journalPath 绝对路径；sessionRef 内 dbPath 相对池目录 / 绝对路径均可。
+ * chat 域轮次交接包的 core 契约基座（设计 §3.8 D2「ChatRoundTicket → HostBridge」）。
+ * pi 专有扩展（identity / SessionRunnerContext / SpawnResumeOpts resume）在
+ * pi-engine.ChatRoundTicket extends 本接口（W7 随包迁移；过渡期 record/opts/signal/
+ * priority/stream 五字段的宿主编排语义在此单一权威）。
  */
-interface EngineHandleView {
-    /** 引擎自定义定位符（zcode = { sessionId, dbPath }）。 */
-    sessionRef: Record<string, string>;
-    /** journal 绝对路径（②级数据源；读前校验 engines 根前缀白名单）。 */
-    journalPath?: string;
-    /** 隔离池定位（路径布局 SSOT：resolvePoolDir 消费）。 */
-    poolKey: string;
+interface HostChatRoundTicket {
+    record: ExecutionRecord;
+    opts: ExecuteOptions;
+    signal: AbortSignal | undefined;
+    priority: number;
+    stream?: SubagentStream;
 }
 /**
- * 历史读取输入的 record 快照（消费字段级子集，不绑定 runtime 的完整
- * SubagentRecord 形状——core 不 import workspace private 类型）。
- * engine / engineHandle 是不可信源（JSONL 文本派生），由 extractEngineId /
- * parseEngineHandle 守卫式消费。
+ * HostBridge 的服务实现面（SubagentService 的结构子集，鸭子类型——与原 pi-engine 的
+ * PiEngineService 同一形态的协议化泛化：chat 域轮次面泛型参数化，pi 绑定 =
+ * HostBridgeServiceFace<ChatRoundTicket>，见 pi-host-binding.ts 的 re-export）。
+ * 为什么用结构接口而非 import SubagentService 类型：防 Service 内部演进连锁影响
+ * 契约面 + 测试可注入 fake（PiEngineService 的既有先例，语义照搬）。
  */
-interface SubagentRecordSnapshot {
-    subagentId: string;
-    task: string;
-    result?: string;
-    error?: string;
-    startedAt?: number;
-    endedAt?: number;
-    /** record.engine（'pi' | 'zcode' | ...，缺省 = pi 由 extractEngineId 归一）。 */
-    engine?: unknown;
-    /** record.engineHandle（parseEngineHandle 守卫消费）。 */
-    engineHandle?: unknown;
-}
-/** GUI 工具调用视图（结构兼容 shared ToolCall 的消费子集；id/时间戳为展示占位）。 */
-interface HistoryToolCallView {
-    id: string;
-    toolName: string;
-    input: unknown;
-    output?: string;
-    details?: Record<string, unknown>;
-    status: "completed" | "error";
-    startTime: number;
-    endTime: number;
-}
-/** GUI thinking 块视图（结构兼容 shared ThinkingBlock）。 */
-interface HistoryThinkingView {
-    id: string;
-    content: string;
-    collapsed: boolean;
-}
-/** GUI usage 视图（结构兼容 shared Usage）。 */
-interface HistoryUsageView {
-    inputTokens: number;
-    outputTokens: number;
-}
-/** GUI 消息视图（结构兼容 shared Message 的消费子集——见文件头「为什么不 import shared」）。 */
-interface HistoryMessage {
-    id: string;
-    role: "user" | "assistant";
-    content: string;
-    status: "complete" | "error";
-    toolCalls?: HistoryToolCallView[];
-    thinking?: HistoryThinkingView[];
-    usage?: HistoryUsageView;
-    timestamp: number;
-    error?: string;
+interface HostBridgeServiceFace<TTicket extends HostChatRoundTicket = HostChatRoundTicket> {
+    executeAndAwait(opts: ExecuteOptions, signal?: AbortSignal, onEvent?: (event: AgentEvent) => void, stream?: SubagentStream): Promise<AgentResult>;
+    getRecordForAction(id: string): ExecutionRecord;
+    closeSubagent(record: ExecutionRecord, force: boolean): Promise<void>;
+    cancel(id: string): boolean;
+    collectRecords(limit: number, statusFilter?: StatusFilter): SubagentRecord[];
+    /** chat 域轮次交接（run 的 chat 分支入口）：按 taskId 取走预备包（一次性消费）。 */
+    takeChatRound?(taskId: string): TTicket | undefined;
+    /** 执行预备的 chat 轮次（编排归 Service：pool 槽 + runSpawn + 终态迁移）。 */
+    runChatRound?(ticket: TTicket): Promise<AgentResult$1>;
+    /** 冷路径续轮（interact message 分支的编排回调：守卫 + record 迁移 + kick-off）。 */
+    resumeChatRound?(record: ExecutionRecord, text: string): void;
+    /** record 状态迁移上报（热路径投递后让 runtime 派生缓存失效 / GUI 回流）。 */
+    reportRecordTransition?(record: ExecutionRecord): void;
 }
-/**
- * engineHandle 唯一守卫（D1 双守卫收敛点）。
- * 语义取收敛前 extractor 侧的严格版（两份 guard 此前已在「sessionRef 含非 string 值」
- * 维度分叉：extractor 整体拒绝、history 侧逐键过滤——收敛选整体拒绝，坏形状不进
- * record，读侧按缺 handle 降级 outcome-only，两侧行为面等价落点都是降级）：
- * - poolKey 缺失 / 非 string / 空串 → undefined（定位符不完整，读侧降③级）
- * - sessionRef 非 plain object 或含非 string 值 → undefined（整体拒绝）
- * - journalPath 可选 string（空串视为缺省）
- */
-declare function parseEngineHandle(raw: unknown): EngineHandleView | undefined;
-
-/**
- * 非 pi record 的历史详情读取（三级降级主入口，D1 收敛后的唯一生产实现）。
- *
- * 降级顺序 ①→②→③ 逐级尝试，每级失败留 debug/warn 日志不抛崩溃（GUI 详情页
- * 永不白屏报错，设计 A8）。engineId='pi' 返回 []（pi 的①级 = 调用方现有 JSONL
- * 直读链，A1 守护）。未注册 reader 的引擎（未来）直接落③级——record 字段就够，
- * 详情页至少有摘要卡。
- *
- * @param record  record 快照（engine/engineHandle 为不可信源，内部守卫消费）
- * @param dataDir xyz-agent 数据根（journal/dbPath 白名单经 paths.ts 布局 SSOT 推导）
- */
-declare function readSubagentHistoryMessages(record: SubagentRecordSnapshot, dataDir: string): Promise<HistoryMessage[]>;
-
-/**
- * 从 turns[] 末尾推导当前活动行（running 时）。
- *
- *   优先级：最后一个未闭合 turn 的末尾 running toolCall → thinking → text → undefined
- *
- * 仅 status==="running" 时返回；terminal 态返回 undefined。
- *
- * 注意：返回的 type 联合（"tool"|"text"|"thinking"）是手写的，未通过类型守卫从
- * AgentEvent 派生——它映射的是累积的 turn 状态（InternalToolCall._status + turn.thinking/text），
- * 而非单个事件。若未来新增 turn 内容模式（如 reasoning_summary），须同步扩展本函数，
- * 否则会静默返回 undefined（活动行运行中途消失）。updateFromEvent 的 switch 有 never 穷尽
- * 检查，但本函数没有，依赖人工同步。
- */
-declare function getCurrentActivity(record: ExecutionRecord): {
-    type: "tool" | "text" | "thinking";
-    label: string;
-} | undefined;
-/**
- * 聚合所有 turn 的 toolCalls（扁平化），并 strip InternalToolCall 的内部字段。
- * 供 collectResult / schema enforcement 读，替代旧闭包 toolCalls 旁路。
- *
- * 返回 ToolCall[]（不含 _status / startedTs）——跨边界导出形状清洁，
- * 避免内部状态机字段泄漏到 AgentResult.toolCalls / 持久化层。
- */
-declare function getAllToolCalls(record: ExecutionRecord): ToolCall[];
-/**
- * 聚合所有 turn 的 toolCalls 总数（免克隆计数）。
- *
- * getAllToolCalls 会 flatMap + strip 克隆出完整数组——只需计数的调用方（渲染签名
- * 每 200ms tick 调用一次）用它是纯浪费；本函数 reduce 累加各 turn 的 length，零分配。
- * 与 getAllToolCalls(...).length 恒等（同一 turns 源）。
- */
-declare function countAllToolCalls(record: ExecutionRecord): number;
-/**
- * closed 终态 → 三态 outcome 的唯一权威派生（D6 收敛：原 notifier/bg-notify-render/
- * shared deriveClosedDisplay 三处手写同构 switch 的单一实现）。
- *
- * 判定顺序（顺序敏感，勿回退成「error 有值即 failed」的无视取消规则）：
- *   1. closedReason === "cancelled" → "cancelled"（取消优先，不参与 error——abort 合成
- *      result 可能携带 error，但用户取消语义优先）
- *   2. error 非空（truthy，与旧三处同构的 `record.error &&` 判定逐字对齐——空串 error
- *      不构成失败）→ "failed"
- *   3. 其余 → "completed"
- *
- * [D6 待核项保真] 「failed 优先于 patchFile 提示」：失败轮也会写 patchFile
- * （doFinalizeRecord Step 0 对 worktreeHandle 无条件 collectPatch），消费方必须先按
- * outcome 分流再渲染 patch 提示——failed 分支不展示 patch/result。历史 bug：notifier
- * 的 patchFile 分支曾遮蔽 gc+error 判定，失败终态被 LLM 告知 completed（M1 修复存档）。
- *
- * [D6 显式取舍] parent-shutdown/parent-fork/parent-new 合成关闭（subagent-service
- * disposeAllRecords 合成 result 恒写 error:"closed due to ${reason}"）在本映射下落
- * "failed"——语义为「父进程关闭时子 agent 未完成即失败」，选定行为而非疏漏，
- * 勿当 bug 改回 cancelled 造成派生矛盾。
- *
- * 唯一写点 completeRecord 调用本函数冻结 record.outcome；通知 payload（notifier 投影
- * 边界）与无 outcome 字段的存量/重建 record 由 projectOutcome 兜底复用本函数。
- */
-declare function deriveOutcome(closedReason: ClosedReason | undefined, error: string | undefined | null): ExecutionOutcome;
-/**
- * 投影层 outcome 唯一出口：running → undefined（终态语义不适用活跃态）；closed →
- * 一等 outcome 字段直读优先，字段缺失（存量/磁盘重建 record——outcome 持久化不在
- * U3 领地内）时回退 deriveOutcome(closedReason, error) 兜底——单一权威函数，
- * 消费方零手写推导。返回值联合含 "closed-legacy" 预留态，消费方必须处理。
- */
-declare function projectOutcome(record: {
-    status: ExecutionStatus;
-    outcome?: ExecutionOutcome;
-    closedReason?: ClosedReason;
-    error?: string;
-}): ProjectedOutcome | undefined;
-/** elapsedSeconds 唯一计算点（共享 helper，消除三处发散）。endedAt 缺失用 Date.now()。 */
-declare function computeElapsedSeconds(record: {
-    startedAt: number;
-    endedAt?: number;
-}): number;
-/**
- * 投影到 live 进度快照。elapsedSeconds/currentActivity/eventLog 均现算派生。
- * 供 WorkflowsView 在 agent 运行期间读取实时进度。
- */
-declare function projectLiveProgress(record: ExecutionRecord): {
-    status: ExecutionRecord["status"];
-    turns: number;
-    totalTokens: number;
-    elapsedSeconds: number;
-    eventLog: AgentEventLogEntry[];
-    currentActivity: ReturnType<typeof getCurrentActivity>;
-    lastError: string | undefined;
-};
 
 /** 三态读取结果（判别联合，调用方按 status 分派）。 */
 type GlobalConfigReadResult = 
@@ -2073,19 +1391,26 @@ declare class SubagentService {
      *  在子进程注册（session-runner spawnedChildren.set）之前，锁空洞由此守卫兜住；EPIPE
      *  兜底不持锁，同样被覆盖）。child 注册完成后投递走热路径，不经此守卫。 */
     private readonly resumesInFlight;
-    /** chat 域 pi 引擎实例（D2 单轨：chat 域执行/投递统一经 EnginePort）。per-service DI——
-     *  getService 经适配器绑本实例；registry 全局 'pi' 单例绑进程级 getSubagentService()，
-     *  直构 Service 的测试场景解析不到本实例。不能 import registration.ts（其 import 本文件
-     *  → 循环依赖），直接构造 PiEngine（pi-engine 不反向依赖本文件）。 */
-    private readonly chatPiEngine;
-    /** chat 域轮次交接包（executeViaEngine / 冷路径续轮挂载 → PiEngine.run 经 taskId 消费）。 */
-    private readonly chatRoundTickets;
-    /** [D4-②] 轮次结算回调（原 buildSessionRunnerContext 内的 onRoundSettled 业务闭包
-     *  搬移至 round-settlement.ts；deps 回调闭包惰性求值，session-runner agent_settled 时消费）。 */
-    private readonly settleRound;
+    /**
+     * [W3 chat 域收口] chat 轮次反向通道路由表（recordId 键）：首轮 run chat 注册、
+     * interact 续聊轮复用——host/streamDelta（recordId 分支）与 host/roundLifecycle
+     * （recordId 键）的分发目标（EngineClient.recordRoutes 经
+     * EnginePort.registerChatRoundRoute 注册）。record 终态化路径注销（[F-5 修复]
+     * 汇聚点 = doFinalizeRecord 的 onFinalized 钩子 + cancelBackground /
+     * disposeAllRecords 两处直连终态化路径显式注销）。
+     */
+    private readonly chatRoundRoutes;
     /** [D4-③] 冷路径复活依赖（原四件 private 方法的搬移落点——cold-resurrect.ts；
      *  deps 闭包惰性求值：sessionRootId / execNesting 基线运行时可变）。 */
     private readonly coldResurrectDeps;
+    /**
+     * [W4] 轮次活性监督器（D2「等待有主」权威层）：死亡事件纳管（run failed / 引擎
+     * exited → adoptOnProcessDeath）+ boot 分区重认领（initSession）+ 三态判定
+     * （record 级视图）+ 该放弃（终态化 failed + 注销 + 终止通知）。装配绑定面
+     * （deps/giveUp 编排/sweep 挂点）在 round-supervisor/service-binding.ts——变化轴
+     * 独立（通知文案 / 终态化编排 / store 读侧判据只动该文件），本字段只持实例。
+     */
+    private readonly roundSupervisor;
     /** [D4 查询面聚合] 读模型消费面（壳 interface/ 视图与 tool 查询经此访问；
      *  纯委托——方法本体保留 private 实现不重写，行为逐字节等价）。 */
     readonly queries: SubagentQueries;
@@ -2180,7 +1505,13 @@ declare class SubagentService {
     onParentNew(): number;
     /** SP-4: idle record GC（30 天 TTL，实现抽至 idle-gc.ts）。stop 函数（dispose 调）。 */
     private stopIdleGc;
-    /** 启动 idle record GC 定时器（session_start 调用，幂等）。 */
+    /** 启动 idle record GC 定时器（session_start 调用，幂等）。
+     *  [W4] WorkflowRun store（FileRunStore）同批纳入：running 且 startedAt 超 30 天
+     *  锚窗的 run 终态化归档（只终态化不补注销，见 idle-gc.ts 头注）。宿主未
+     *  configureCore 时 loadAll 抛错由 idle-gc 内部吞掉（单轮跳过）。
+     *  [F-1 修复] stateDir 与 pi 壳 JsonlRunStore 落盘布局同源
+     *  （resolvePiWorkflowStateDir → <sessionDir>/workflow-state/）——缺省 dataRoot 根
+     *  与 pi 生产落盘不相交，WorkflowRun GC 曾恒空转（W4 引入的装配错位）。 */
     startGcTimer(): void;
     /** 停止 idle record GC 定时器（dispose 调用）。 */
     private stopGcTimer;
@@ -2339,21 +1670,20 @@ declare class SubagentService {
      */
     private lookupRecordAnyState;
     /**
-     * [V2 决策 3] chatMode 统一投递入口（message action 的 Service 面）——经引擎交互面
-     * 执行（D2：PiEngine.interactRecord——port face interact 的 record 锚定形态，协议知识
-     * 在引擎边界，编排层不做 stdin 写入）。分流语义（按**进程死活**，
-     * 不按 record.status）与热/冷路径细节见 PiEngine.deliverPrompt：
-     *
-     *   热路径（进程活）：prompt + streamingBehavior——pi 权威裁决 busy/idle（F3/F4）。
-     *   冷路径（进程死）：冷路径续轮（resumeChatRound）重开 session + prompt（仅崩溃/
-     *     timeout kill/跨重启命中）。
+     * [V2 决策 3 → W3 协议形态] chatMode 统一投递入口（message action 的 Service 面）
+     * ——经协议 interact（message action）发往 pi-subagent-cli 引擎进程。协议知识
+     * （stdin prompt 命令 + streamingBehavior 映射 + EPIPE 兜底）在引擎进程内
+     * （chat-session.deliverMessage）；编排层按结构化结果分流：
      *
-     * 失败语义与直调形态一致：业务拒绝（not ready / EPIPE 兜底耗尽等，文案自带行动语言）
-     * 经 interact 结构化结果回传后原样 throw（错误文本逐字节保持）。
+     *   受理（引擎侧进程活）：prompt + streamingBehavior——pi 权威裁决 busy/idle。
+     *   冷路径（engine_session_not_resumable = 进程死/无活进程）：冷路径续轮
+     *     （resumeColdRound → run chat + resume 锚点接续，仅崩溃/timeout kill/跨重启命中）。
+     *   其他拒绝（EPIPE 兜底耗尽 / engine_interact_failed）：业务拒绝原样 throw
+     *     （文案自带行动语言——与 inproc 形态逐字节一致）。
      *
      * @param record 目标 record（chatMode，running 或 idle）
      * @param text 消息正文
-     * @param interrupt true=steer（抢占）/ false=followUp（排队），仅热路径 streamingBehavior 用
+     * @param interrupt true=steer（抢占）/ false=followUp（排队）
      */
     private deliverChatMessage;
     /**
@@ -2551,6 +1881,18 @@ declare class SubagentService {
      * 落 entry 前）→ 终态迁移。bg notify 归编排侧（与 pi 轮次收尾通知归编排对称）。
      */
     private runEngineTask;
+    /**
+     * [W4 表 3 行 1] 引擎/子进程死亡、宿主存活的 record 处置：run 终态如实记 failed
+     * 证据（record.error），record **保持 resumable**（session 文件在盘，逻辑任务可续
+     * ——冷路径 resume 可直接续写），交监督器接管（合并单条通知 + 三态判定）。禁止
+     * 两个事故方向：completed 谎报（G3）与 closed 直接终局（resume 可能性丢失，等待
+     * 无主——2026-09-08 事故环 2/3 的 core 侧形态）。
+     *
+     * 判据状态源钉死 record 级：写点只动 record 字段（resumable/result/error），
+     * 不清镜像不查引擎——引擎进程被动重建（ensureConnected 退避重填镜像）不翻转
+     * 本处置（纳管模型：死亡事件纳管、重建不解管）。
+     */
+    private adoptResumableAfterEngineDeath;
     /**
      * 分层并发配额：depth 越深可用配额越少（下限 1）。fork 深度护栏在池维度的投影，
      * 公式约定以 concurrency-pool.ts 注释为登记处、此处为唯一代码锚点。
@@ -2559,71 +1901,124 @@ declare class SubagentService {
     /**
      * engine.run resolve 的终态迁移：outcome.error → failed（success=false + error 文案）；
      * 否则 done（result=content）。CAS 抢锁（tryTransition）防与 cancelBackground 双收尾。
+     *
+     * [W4 表 3 行 1] 进程死亡分诊：outcome.error 存在且 **exitCode === null**（引擎侧
+     * 进程被信号终止/崩溃的合成 outcome 形态——RemoteEngine 运行中失败合成分支恒
+     * exitCode:null，引擎如实上报的 turn 失败带数值 exitCode；engine-client 注释同源
+     * 「exitCode null = 被信号杀死，杀链判据」）且宿主存活且非 conversation 形态 →
+     * record 保持 resumable 交监督器接管（如实 failed 证据 + 合并通知 + 三态判定），
+     * 不再 closed 终局。返回 true = 走了接管分支（调用方跳过 bg 完成回注）。
      */
     private finalizeEngineOutcome;
-    /** 共享的"干活 + 收尾"——sync 直接 await，background 在 detached 里调。 */
+    /**
+     * workflow 域"干活 + 收尾"（sync await；[W3] 执行叶 = 协议 engine.run——原 inproc
+     * runSpawn 链随 inproc pi 引擎目录 删除消亡，journal 接线 / record 终态迁移语义保持）。
+     * 编排分段保持「装配（池槽/worktree）→ 执行 → 回收（finally）→ 错误收口 → 终态收口」。
+     */
     private runAndFinalize;
+    /** engine.run taskSpec 装配单一来源（runAndFinalize 与 kickOffChatRound 共用）：
+     *  executeOptions 协议映射 + model = record 留痕词形（resolved 解析产物，
+     *  joinEngineModelRef 规范形）覆盖——原 identity.resolved 经 runSpawn --model
+     *  兜底的协议等价承载。 */
+    private taskSpecWithModel;
+    /**
+     * one-shot（非 chatMode）终态收口（原 settleOneShotOutcome 分支）：成功轮消费
+     * closeAfterRound 挂起标志；失败/取消一次性销毁。CAS 抢锁失败（cancel/dispose 抢先
+     * 终态化）静默跳过。runAndFinalize（workflow 域）与 kickOffChatRound 非 chatMode
+     * 分支共用。
+     */
+    private settleOneShotOutcome;
+    /** AgentOutcome → execution AgentResult 单一映射源（workflow run 域映射；
+     *  finalizeEngineOutcome 终态 result 复用此处构造——exitCode null = 被信号杀死的
+     *  合成终态，error 如实透传）。 */
+    private outcomeToAgentResult;
     /** [U04 提取·装配] 池槽获取：pooled（background）record 排队 acquire。成功返回 undefined
      *  继续执行；失败返回终态 result 供调用方 early-return（该路径在 try/finally 之前，
      *  不触发轮次资源回收——与原控制流逐字节一致）。 */
     private acquirePoolOrFinalize;
     /** [U04 提取·装配] 解析 worktree 参数：boolean → WorktreeHandle | undefined（true/undefined 由 run 内部处理）。 */
     private resolveWorktreeHandle;
-    /** [U04 提取·装配] [MF#4][MF#2] fork 深度护栏：ALS 传递深度（主 session 链无 store→0，fork 推进 +1）。 */
-    private resolveForkDepths;
-    /** [U04 提取·执行] runSpawn 的两层 ALS 包装（forkDepthAls 外层 + execNesting 内层）。 */
-    private runSpawnNested;
     /** [U04 提取·回收] 轮次资源回收（finally 语义，幂等）：池槽归还（仅 pooled 且 acquire
-     *  成功）、streaming widget 清除、在途 resume 守卫清除。 */
+     *  成功）、streaming widget 清除。 */
     private releaseRoundResources;
     /** [U04 提取·错误收口] MF-6（决策 6 spec §3.1）：chatMode（含 resume）spawn/创建失败
      *  不销毁对话——回退 idle（可恢复），让 agent 可重试 message 或 close。与一次性模式
      *  （finalizeFailed 终态销毁）区分。返回合成 failed result（swallow，不 re-throw）。 */
     private finalizeChatSpawnFailure;
-    /** [U04 提取·收口派生] closedReason 派生：aborted → cancelled；否则 success → user-close，!success → gc。 */
-    private deriveClosedReason;
-    /** [U04 提取·终态收口] CAS 抢锁：抢到则按 chatMode 分流完整收尾；没抢到（cancel 已先设
-     *  closed+cancelled）则跳过。 */
-    private settleFinalOutcome;
-    /** [U04 提取·终态收口] chatMode 轮次分流（原 A/B 分支，De Morgan 等价拆分）：
-     *  成功轮（!aborted && success）与失败/取消轮（其补集 !success || aborted）各自处理
-     *  closeAfterRound 挂起语义。 */
-    private settleChatRoundOutcome;
-    /** [U04 提取·终态收口] one-shot（非 chatMode）分流（原 C/D 分支）：成功轮消费
-     *  closeAfterRound 挂起标志；失败/取消一次性销毁。 */
-    private settleOneShotOutcome;
     /** [U04 提取·终态收口] closeAfterRound 挂起标志消费（原三处分支的公共收尾序列）：
      *  清标志 + 终态化 closed。reason：成功轮恒 user-close；失败/取消轮用派生值。 */
     private consumeCloseAfterRound;
     /**
-     * pi chat 域轮次的 detached 编排（D2 单轨——旧 pi 主路径绕过 EnginePort 的 detached
-     *  编排删除后的 EnginePort 化形态）：
-     * 预备轮次（record/opts/identity/host ctx/stream/resume）挂载交接 Map → engine.run 经
-     * ctx.taskId 消费（PiEngine chat 分支回调 runChatRound——即 runAndFinalize 链，含 pool
-     * 并发槽 acquire/release 与杀链，行为零变化）→ 完成回注 notify（cancel 抢先时跳过，
-     * 与旧 .then 语义一致）。
-     * stream 在挂载前同步创建（spawn 前置不变量，stream-sink 退役步骤 2 守护）。
+     * pi chat 域轮次的 detached 编排（[W3 协议形态]）：轮次经协议 run（会话形态
+     * chat{recordId, resume?}）发往 pi-subagent-cli 引擎进程——
+     *   - 应答时点 = 首轮 agent_settled（W2 契约：idle 帧先于应答帧；outcome = 本轮
+     *     内容非会话终态）→ 应答到达即本轮 settle（round+1 / 增量通知 / closeAfterRound
+     *     消费，见 settleChatRoundFromResponse）；
+     *   - 流式 delta / 轮次生命周期经 host/streamDelta + host/roundLifecycle 反向通道
+     *     回流：首轮 runId 键（RunContext.stream / onRoundLifecycle）、续聊轮 recordId
+     *     键（chatRoundRoutes 注册的 recordId 路由）；
+     *   - recordId 路由在本方法注册（首轮 + 冷续轮替换式重注册），record 终态化路径注销。
      * chat 域不接 event journal（pi 子代理 session JSONL 即原生数据源；与迁移前产物
      * 形态一致——journal 接线仅 workflow 域 SAR 与非 pi 引擎 chat 路径）。
      */
     private kickOffChatRound;
-    /** PiEngine 的编排服务适配器（chat 绑定）：闭包持有本实例的编排面——chat 轮次交接
-     *  由此成为 PiEngineService 的可选面（SAR 直绑 Service 的 workflow 实例不提供，
-     *  Service 公共接口不为引擎内部交接扩面）。 */
+    /**
+     * [W3] chat 轮次生命周期帧消费（host/roundLifecycle，runId 键首轮 / recordId 键续聊轮
+     * 经本方法收敛）。相位 → 宿主编排语义（W4 协议事件面三入口）：
+     *   - settled：轮收敛——settled-watchdog 中段让位收尾段（noteRoundSettledFromProtocol）；
+     *   - idle：轮收口进 idle 稳态——两段守护一并清（disarmRoundFromProtocol）+ 冷续锚点
+     *     回填（sessionFile/engineHandle，idle 帧先于 run 应答帧）+ **idle 定时器挂载**
+       *     （引擎不实现 idle 定时器——core arm，W2 交接契约）；
+     *   - failed：轮异常终止（engine_round_aborted / engine_round_crashed /
+     *     engine_round_epipe_exhausted）——record 如实标 failed（禁 completed 谎报），
+     *     chatMode 按 MF-6 回退可恢复（onChatRoundFailed）。
+     */
+    private handleChatRoundPhase;
+    /**
+     * [W3] idle 相位 = idle 定时器锚点（原 session-runner handleAgentSettledForChatMode
+     * 的 armIdleTimer 段）：挂载降级链（配置值 → DEFAULT 兜底 + warn）语义保持；超时
+     * 处置 = 引擎侧进程回收（协议 interact close force）——idle timer SIGTERM 的协议形态。
+     */
+    private armChatIdleTimer;
+    /** [W3] idle 帧锚点回填（冷续锚点 = 引擎侧会话滚动/compaction 后的最新定位）。 */
+    private backfillChatAnchor;
+    /**
+     * [W3] chat 轮 failed 相位分诊：错误如实落 record（失败相位错误码——engine_round_
+     * aborted（宿主 cancel/close）/ engine_round_crashed（子进程外部死亡）/
+     * engine_round_epipe_exhausted（EPIPE 兜底耗尽）），禁 completed 谎报。chatMode 按
+     * MF-6 不销毁对话——回退可恢复（finalizeRoundToIdle + 通知），冷续 run 接续；
+     * record 已终态（cancel/close 抢先）= 迟到帧，幂等跳过。
+     */
+    private onChatRoundFailed;
+    /**
+     * [W3] 首轮 run 应答到达（= 首轮 agent_settled，W2 契约）的本轮 settle：round+1 /
+     * 轮次增量通知 / base 推进 / reportRecordTransition / closeAfterRound 消费——语义
+     * 权威自持于此（原 round-settlement.ts createRoundSettler 已删，本闭包为其唯一后继），
+     * 唯一偏差 = 轮次文本源：协议形态下 live turns 留在引擎进程内，core 以应答
+     * outcome.content（W2「outcome = 本轮内容」）为增量权威，record.turns 派生不可用。
+     * idle 定时器挂载不在此处——idle 相位帧先于应答帧到达，armChatIdleTimer 已锚定。
+     */
+    private settleChatRoundFromResponse;
+    /** [W3] chat 域引擎终止意图（协议面）：cancel = interact cancel（引擎侧 SIGTERM →
+     *  settle 等待 → 杀链升级）；close = interact close force（立即杀链收割）。fire-and-forget
+     *  ——失败 best-effort 留证（宿主组级收割兜底 = EngineClient killAll，dispose 路径）。 */
+    private terminateChatSession;
+    /** chat record 的协议 interact handle（engineHandle 缺省时按 recordId 合成——
+     *  引擎侧 interact 定位键 = sessionRef.recordId；sessionFile 有值时一并携带）。 */
+    private chatHandleFor;
+    /** [W3] pi 引擎 port 解析（chat 域路由与终止面共用）：registry cli 形态 port，
+     *  未注册 = 不可用 stub（engine_not_found，见 pi-host-binding）。 */
+    private resolveChatEnginePort;
+    /** [W3] record 终态化路径的 chat 反向通道路由注销（幂等）。 */
+    private unregisterChatRoundRoute;
+    /** 引擎服务面适配器（HostBridgeServiceFace 结构视图）：闭包持有本实例的编排面。
+     *  [W3] chat 域轮次交接可选面（takeChatRound/runChatRound/resumeChatRound）随
+     *  inproc PiEngine 删除移除——引擎经协议 converse，不再回调宿主编排面。 */
     private piEngineServiceAdapter;
-    /** [D4 聚合连带] PiEngineService 的显式结构视图（registration / SAR 直绑消费）。
-     *  原两绑定点把 SubagentService 整体结构化兼容为 PiEngineService——依赖查询/交互
-     *  方法 public；聚合收窄后改经本视图显式适配（成员集合与原直绑等价，行为零差异）。
-     *  getter 形态：face 视图（惰性构造的适配对象）而非动作方法。 */
-    get asEngineService(): PiEngineService;
-    /** chat 域轮次交接的消费侧（PiEngine.run 回调）：一次性取走，防重复消费。私有名与
-     *  PiEngineService 可选面成员不同名（历史约束：D4 聚合前的结构化直绑时代，私有同名
-     *  成员会阻断 SubagentService 直绑；聚合后经 asEngineService 显式视图，约束已消失，
-     *  不同名保留为与 adapter 显式映射一致的命名纪律）。 */
-    private takeChatTicket;
-    /** PiEngine chat 分支的执行回调：原 runAndFinalize 直调链的 EnginePort 化落点
-     *  （编排归 Service——pool 槽 + runSpawn + 终态迁移，行为零变化）。 */
-    private runTicketRound;
+    /** [D4 聚合连带] 引擎服务面的显式结构视图（SAR 构造 resolveHostPiEnginePort 时
+     *  传入的 getService 兼容位消费——W3 后该面无引擎侧消费方，保留使 SAR 调用点
+     *  零改动，W8 收口时随签名一并清理）。getter 形态：face 视图（惰性构造）。 */
+    get asEngineService(): HostBridgeServiceFace;
     /**
      * 取消 background record。CAS 抢锁（tryTransition）——抢到则 notify + 写 tombstone；
      * 没抢到（detached 已 finalize，record 已终态）返回 false，不触碰任何收尾副作用。
@@ -2645,7 +2040,13 @@ declare class SubagentService {
     private finalizeRoundToIdle;
     /** run() 创建期异常的收尾（H1 修复）：createAndConfigureSession 失败会抛，本方法合成 failed
      *  AgentResult → CAS 抢锁 → finalizeRecord（与正常路径同形）。返回合成 result 供 runAndFinalize
-     *  继续返回（不 re-throw，swallow 策略）。 */
+     *  继续返回（不 re-throw，swallow 策略）。
+     *  [W3 契约变更⑤（run 期失败清理前置副作用）] kickOffEngineRun 前已建的 worktree
+     *  （executeViaEngine 创建点，record.worktreeHandle 已绑定）经本方法 → finalizeRecord
+     *  → doFinalizeRecord Step 3b cleanupWorktreeIfBound 清理（manifest 多声明 run 期
+     *  失败 / engine.run prepare 期 reject 共用本收尾链）；CAS 没抢锁（cancel 抢先终态）
+     *  时由 cancelBackground 的 worktree cleanup 覆盖。唯一前置副作用 = worktree（并发
+     *  池槽 acquire/release 在 kickOffEngineRun finally 内自回收，journal 是宿主数据不清理）。 */
     private finalizeFailed;
     /** S1: 排队中被 abort 走 cancelled 终态（对齐已运行被 abort 的 cancelBackground）。 */
     private finalizeAborted;
@@ -2671,8 +2072,6 @@ declare class SubagentService {
      * 由 lifecycle-manager 的 warn 回落承接）。execute/executeAndAwait 两入口共用。
      */
     private assertIdleTimeoutMsSafe;
-    /** 构造 SessionRunnerContext（spawn 模式：无需 SDK 实例）。 */
-    private buildSessionRunnerContext;
 }
 /** 获取进程单例。session_start 前为 null。 */
 declare function getSubagentService(): SubagentService | null;
@@ -2837,20 +2236,6 @@ type BestEffortLevel = "debug" | "error";
  */
 declare function bestEffort(err: unknown, context: string, level?: BestEffortLevel): void;
 
-/** channel handler 签名：接收 UiRequest，返回 UiResponse。
- *  具体类型定义在 session-runner.ts（W2 工作），此处用最小形状避免循环依赖。
- *  handler 实现方按 channel 注册，由 session-runner 按 req.channel 分派。 */
-type ChannelHandler = (req: unknown) => Promise<unknown>;
-/** channel 注册表接口。职责单一：只管业务路由，不管排队、不管透传判定。
- *  - register(channel, handler)：注册 channel 对应的 handler（同名覆盖）
- *  - resolve(channel)：取 channel 对应的 handler，未注册返回 undefined
- *  - list()：列举所有已注册 channel 名 */
-interface UiChannelRegistry {
-    register(channel: string, handler: ChannelHandler): void;
-    resolve(channel: string): ChannelHandler | undefined;
-    list(): string[];
-}
-
 /** 获取或创建进程级 channel registry（canonical 单例）。
  *
  *  **唯一创建点**：canonical UiChannelRegistry 实例仅由本函数创建。
@@ -3180,7 +2565,7 @@ declare class Budget {
    * 而非原始 token 数直接相加。retry 间的真实消耗如实记录，避免预算被低估。
    * 详见上方权重常量的口径说明。
    */
-    consume(usage: AgentUsage): void;
+    consume(usage: AgentOutcomeUsage): void;
     /** 累加调用计数（每次 agent dispatch 后调用；持久化快照同步）。 */
     incrementCallCount(): void;
     /**
@@ -4431,6 +3816,23 @@ interface CreateConcurrencyPoolOptions {
  */
 declare function createConcurrencyPool(options: CreateConcurrencyPoolOptions): ConcurrencyPool;
 
+/** provider 条目（v2 config.provider.<id>）的最小消费面（索引签名形态）。 */
+interface ZcodeProviderEntryLike {
+    options?: {
+        apiKey?: unknown;
+    };
+}
+/** 短名（无 provider 前缀）解析的默认 provider（zsub DEFAULT_PROVIDER_ID 同构）。 */
+declare const DEFAULT_PROVIDER_ID = "builtin:bigmodel-coding-plan";
+/** zsub 同构的兜底缺省模型（v2 config 无 model.main 且 task 未指定时）。 */
+declare const ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
+/** [R4] 规范化全名 provider/model → create 参数的 per-session model 拆分。 */
+declare function splitZcodeModelRef(modelRef: string): {
+    providerId: string;
+    modelId: string;
+};
+declare function hasApiKey(entry: ZcodeProviderEntryLike): boolean;
+
 /**
  * gitRun 的包装错误：message 格式与提取源 gitRunAsync 逐字一致；exitCode/stderr/
  * timedOut 为诊断属性（P-errshape 实测 Node 24：execFile 的 err.stderr 为
@@ -5618,7 +5020,38 @@ interface FileRunStoreOptions {
      * {@link DEFAULT_SAVE_MIN_INTERVAL_MS}。测试经此注入小窗口（fake timers 推进）。
      */
     saveMinIntervalMs?: number;
+    /**
+     * [F-1 修复] run 状态目录覆盖。缺省 = `<dataRoot>/workflow-state`（zcode 宿主布局，
+     * 见 stateDir()）；pi 宿主的读侧装配点（round-supervisor sweep / idle-gc）必须传
+     * resolvePiWorkflowStateDir()（execution/workflow-state-root.ts）——pi 宿主 run state
+     * 由 JsonlRunStore 落 `<sessionDir>/workflow-state/`，与缺省根不相交。
+     */
+    stateDir?: string;
+}
+/** pruneStateFilesBeyondCap 的宿主注入依赖（日志与错误字符串化——tag 前缀由注入方决定）。 */
+interface PruneStateDeps {
+    /** warn 通道（readdir / unlink 失败留证；清理是旁路维护，失败不抛） */
+    warn: (msg: string) => void;
+    /** debug 通道（成功裁剪记录） */
+    debug: (msg: string) => void;
+    /** error → 可读字符串（core 侧 err.message 兜底 String，宿主可用自有 error 工具） */
+    toMsg: (err: unknown) => string;
 }
+/**
+ * 把 state 目录裁剪到 cap 个最新 state 文件（mtime 升序删最旧，C1）。
+ *
+ * 语义（OR-5，两宿主单源）：
+ * - 只删目录内命中 {@link STATE_FILE_GLOB} 的文件；任何失败都不抛（清理是旁路
+ *   维护，不能拖垮持久化主链路）：readdir 失败静默放弃本轮（ENOENT = 从未持久化，
+ *   正常态），单个 unlink 失败（非 ENOENT）warn 留证后继续删其余——ENOENT 视为
+ *   并发删除竞态下的已达成目标，不告警；
+ * - stat 全集取 mtime，allSettled 部分降级——单文件 stat 失败（并发删除 ENOENT
+ *   等）静默跳过该文件，不阻断本轮裁剪。
+ *
+ * cap 解析（env 通道等）归调用方：FileRunStore 方法含 envName 通道超集；
+ * pi 宿主 jsonl-run-store 经 getEnvStateMaxRuns 解析后直传。
+ */
+declare function pruneStateFilesBeyondCap(stateDir: string, cap: number, deps: PruneStateDeps): Promise<void>;
 /**
  * RunStore port 的宿主无关文件实现（port 见 models/ports.ts）。
  *
@@ -5631,15 +5064,21 @@ interface FileRunStoreOptions {
  *   warn——单行损坏不拖垮整个 run 的恢复（与 pi 壳 kill-9 恢复同容忍度）。
  *   版本衔接（快照 codec 归 run-snapshot.ts 单源，D4）：存量无 v 行按当前版本
  *   宽容读、写入恒补 v、v 不匹配跳过 + warn（三裁决明细见 parseLine 注释）。
- * - stateFilePath：纯路径计算（<dataRoot>/workflow-state/<runId>.jsonl），不建目录。
+ * - stateFilePath：纯路径计算（<状态目录>/<runId>.jsonl），不建目录。状态目录 =
+ *   构造注入的 stateDir 覆盖，或缺省 <dataRoot>/workflow-state（pi 宿主读侧装配点
+ *   必须传 resolvePiWorkflowStateDir()——见 FileRunStoreOptions.stateDir 与
+ *   execution/workflow-state-root.ts 的同源布局论证）。
  *
  * 未 configureCore 即 save/loadAll 会抛 core_host_not_configured（dataRoot 端口
  * 语义，host-services.ts §3.4）——宿主壳必须在初始化最早期注入。
  */
 declare class FileRunStore implements RunStore {
-    /** run 状态目录绝对路径（dataRoot 每次现取——宿主覆盖配置即刻生效，对齐
-     *  data-dir.ts「不缓存路径防测试/宿主切换读到旧值」先例）。 */
+    /** run 状态目录绝对路径（显式覆盖优先——pi 宿主读侧装配点；缺省 dataRoot 每次现取
+     *  ——宿主覆盖配置即刻生效，对齐 data-dir.ts「不缓存路径防测试/宿主切换读到旧值」
+     *  先例）。 */
     private stateDir;
+    /** 显式状态目录覆盖（构造注入；见 FileRunStoreOptions.stateDir）。 */
+    private readonly stateDirOverride;
     /** save 节流最小间隔（ms），0 = 禁用。 */
     private readonly saveMinIntervalMs;
     /**
@@ -5665,6 +5104,29 @@ declare class FileRunStore implements RunStore {
      */
     save(run: WorkflowRun): Promise<void>;
     loadAll(): Promise<WorkflowRun[]>;
+    /**
+     * [W4 sweep 判据，F2] 按 runId 同步查 run 状态（注册对账 sweep 的 workflow 收口
+     * 判据）。同步形态：sweep 在 session_start 同步链内运行（runReconcileSweep 同步
+     * 契约），不能 await loadAll——对单 runId 做同步文件读（对齐 sweep 自身的 sync fs
+     * 读先例），逐行解析复用 parseLine（版本衔接 + 形状校验与 loadLatestValidLine
+     * 单源，同步只读不触碰 lastSavedAt 节流记账）。
+     *
+     * 判定（宁挂账不失明——误注销活跃 run 是事故方向，判据保守侧取「不可判定」）：
+     * - state 文件不存在 → missing（设计判据「已归档/不存在视同终态」——run 从未
+     *   落盘或已被清理，注册是死亡窗口残留）；
+     * - 末条有效快照 status = running → running（活跃，sweep 跳过）；
+     * - 末条有效快照 status ≠ running（done）→ terminal + reason（I2：done ⟹ reason
+     *   有值；reason 作 pending unregister 的 status 语义源）；
+     * - 文件存在但全部行损坏（无有效快照）→ running（读不出 ≠ 不存在，不补注销）。
+     */
+    findStateByIdSync(runId: string): {
+        kind: "running";
+    } | {
+        kind: "terminal";
+        reason: string | undefined;
+    } | {
+        kind: "missing";
+    };
     /** 单文件从尾向头取第一条有效快照行；整文件无有效行返回 undefined（warn）。 */
     private loadLatestValidLine;
     /**
@@ -5683,15 +5145,12 @@ declare class FileRunStore implements RunStore {
     private parseLine;
     /**
      * 把 workflow-state 目录裁剪到上限个最新 state 文件（mtime 升序删最旧，C1）。
-     *
-     * 语义对齐 pi jsonl-run-store.pruneStateFilesBeyondCap（逐段同构）：
-     * - 只删本目录内命中 {@link STATE_FILE_GLOB} 的文件；任何失败都不抛（清理是
-     *   旁路维护，不能拖垮持久化主链路）：readdir 失败静默放弃本轮（ENOENT =
-     *   从未持久化，正常态），单个 unlink 失败（非 ENOENT）warn 留证后继续删
-     *   其余——ENOENT 视为并发删除竞态下的已达成目标，不告警；
-     * - stat 全集取 mtime，allSettled 部分降级——单文件 stat 失败（并发删除
-     *   ENOENT 等）静默跳过该文件，不阻断本轮裁剪。
-     *
+   *
+   * 主体委托导出单源 {@link pruneStateFilesBeyondCap}（retention 语义两宿主单源，
+   * S4-A7；日志经 deps 注入本模块 logger + `[file-run-store]` tag，行为与收口前
+   * 逐字一致）。磁盘裁剪不动内存 runs Map（内存侧淘汰归
+   * lifecycle.evictDoneRunsBeyondCap，两域独立）。
+   *
    * 上限解析（envName 通道，OR-5 ⑥b 默认开；显式非法值 opt-out 对齐 pi 解析风格）：
    * - `envName` 提供 → env 通道：`process.env[envName]` 未设/空 → 按默认上限
    *   {@link DEFAULT_STATE_MAX_RUNS} 裁剪（**默认开**——OR-5 修复前的 opt-in
@@ -5701,14 +5160,11 @@ declare class FileRunStore implements RunStore {
    *   宿主如需自管保留可设足够大的正数值）；
    * - `envName` 缺省 → 无 env 通道，直接按 `max` 参数裁剪（上限 = max，调用方
    *   自管启用时机）。
-     *
-     * 本方法只做磁盘裁剪，不动内存 runs Map（内存侧淘汰归
-     * lifecycle.evictDoneRunsBeyondCap，两域独立）。
-     *
-     * @param max 上限（envName 缺省时生效；env 通道启用时被 env 值覆盖）
-     * @param envName opt-in 开关 + 上限覆盖 env 变量名（可选；pi 先例
-     *   `XYZ_SUBAGENT_STATE_MAX_RUNS`）
-     */
+   *
+   * @param max 上限（envName 缺省时生效；env 通道启用时被 env 值覆盖）
+   * @param envName opt-in 开关 + 上限覆盖 env 变量名（可选；pi 先例
+   *   `XYZ_SUBAGENT_STATE_MAX_RUNS`）
+   */
     pruneStateFilesBeyondCap(max: number, envName?: string): Promise<void>;
 }
 
@@ -6317,8 +5773,8 @@ declare function boundedPrettySerialize(value: unknown, budget: number): string;
  * @zhushanwen/subagent-core — 公共 API barrel（D5 定稿 + post-convergence B-2 扩面）
  *
  * 公共 API 面 = 本文件导出 + package.json exports 的语义子入口
- * （./engines/zcode/reader、./engines/zcode/constants、./engine/paths、./relay-env）
- * + ./workflows/* 资产子入口。exports 面即 semver 契约（D5）：收窄不放宽——
+ * （./engine/paths、./engine/engine-discovery-scan、./relay-env——[W11/H3] 引擎
+ * 子入口 ./engines/zcode/* 已随内建引擎删除）+ ./workflows/* 资产子入口。exports 面即 semver 契约（D5）：收窄不放宽——
  * 新增导出走 minor，本文件刻意不使用 `export *`，逐名列出以使 diff 可审。
  * 内部实现细节（error-recovery / execute-agent-call / worker-script-builder 等
  * engine 编排件）不经 barrel 导出；host-surface 扩面（zsw 回接 U0，2026-08-30）
@@ -6335,6 +5791,6 @@ declare function boundedPrettySerialize(value: unknown, budget: number): string;
  * docs/design/subagent-core-sink-design.md（sink 下沉收口扩面，2026-08-31）；
  * 宿主接入示例见包 README（§3.4 core_host_not_configured 恢复指引的落点）。
  */
-declare const CORE_PACKAGE_VERSION = "0.6.0";
+declare const CORE_PACKAGE_VERSION = "0.7.0";
 
-export { AGENT_REF_EXT, AgentCall, AgentCallOpts, type AgentEntry, AgentEvent, AgentEventLogEntry, AgentOutcome, type AgentProfile, AgentRegistry, AgentResult, type AgentRunner, type ArgKeySet, type ArgMetaOptions, type ArgMetaWarning, type AtomicTmpRef, type AtomicWriteFileOptions, type AtomicWriteOptions, BG_MESSAGE, BgResponse, Budget, CORE_PACKAGE_VERSION, type CachedWorkflowMeta, type CancelHandlerInput, type CancelHandlerResult, CancelResponse, type ChangeListener, type ChannelHandler, type CleanupStaleTmpOptions, type CleanupStaleTmpResult, type CleanupWorktreeOptions, type CloseHandlerInput, type CloseHandlerResult, CloseResponse, ClosedReason, type CollectWorktreePatchOptions, type ConcurrencyPool, type CoreLogger, type CreateConcurrencyPoolOptions, DEFAULT_DATA_ROOT, DEFAULT_ENGINE_ID, DEFAULT_LIST_LIMIT, DEFAULT_PROVIDER_ID, DEFAULT_SAVE_MIN_INTERVAL_MS, DEFAULT_STATE_MAX_RUNS, DEFAULT_WORKFLOW_SAVED_DIR, DEFAULT_WORKFLOW_TMP_DIR, DialogGlobalQueue, type DiscoveredResource, type DiscoveryRoot, DisplayItem, DoneReason, EngineCapabilities, EngineHandle, EngineHandleData, type EnginePort, type EngineRouteOptions, type EngineRouteResult, type EngineRouting, type EngineRoutingInput, type EngineRoutingSource, type EngineRunResult, ExecutionMode, ExecutionOutcome, ExecutionRecord, ExecutionStatus, ExecutionTraceNode, ExternalState, FORK_FROM_DEFAULT_PROMPT, FileRunStore, type FinalizeRunOptions, type ForkFromHandlerInput, type ForkFromHandlerResult, ForkFromResponse, type GenerateWorkflowScriptOptions, type GenerateWorkflowScriptResult, GitRunError, type GlobalConfigReadResult, type HostServices, IDENTITY_CUSTOM_TYPE, INDEX_FILENAME, InteractAction, InteractResult, type InvalidAgentRefMessageOptions, type LauncherDeps, type LifecycleDeps, type LintFinding, type LintResult, type ListFormatOptions, type ListHandlerInput, type ListHandlerResult, ListResponse, type ListWorktreePorcelainOptions, type LogLevel, MAX_LIST_LIMIT, MAX_RETAINED_DONE_RUNS, MAX_TIMER_DELAY_MS, type MessageHandlerInput, type MessageHandlerResult, MessageResponse, ModelConfigService, type ModelConfigServiceInit, type ModelEntry, ModelInfo, type ModelListFormatOptions, type ModelReasoningInfo, NOTIFY_CONTRACT, type NormalizeWorkflowRefOptions, type NormalizedArgs, type NormalizedWorkflowRef, type NotifyDomainPorts, type NotifyLedgerHost, type PatchBaselineAnchor, ProbeReport, type QueuePolicy, RecordStore, type RecordStorePi, type RecoverCrashedRunsHooks, type RecoverCrashedRunsResult, type ResourceKind, type ResourceSource, type RunContext, type RunSnapshot, type RunSpec, type RunState, RunStatus, type RunStore, SAFE_ID_RE, SNAPSHOT_VERSION, SUBAGENT_RECORD_CUSTOM_TYPE, type ScanConfig, SessionView, type StartHandlerInput, type StartHandlerResult, type StatusFilter, type SubagentIdentityData, SubagentListItem, SubagentRecord, type SubagentRecordEntryData, SubagentService, type SubagentServiceInit, SubagentStream, SubprocessAgentRunner, THINKING_ORDER, Trace, type UiChannelRegistry, WORKFLOW_REF_EXT, WORKFLOW_REF_RESERVED_NAMES, type WorkerHandlers, type WorkerHost, WorkerHostImpl, WorkerLogEntry, type WorkflowDirOptions, type WorkflowEntry, type WorkflowMeta, type WorkflowRefInvalidReason, WorkflowRun, type WorkflowRunMeta, type WorkflowRunResult, type WorkflowRunSummary, type WorkflowScanConfig, WorkflowScript, type WorkflowScriptRegistry, WorkflowScriptRegistryImpl, type WorkflowSource, WorktreeManager, type WorktreePatchResult, type ZcodeEngineDeps, ZcodeTaskShapeError, abortRun, argKeysFromMeta, assertSafeId, atomicTmpPathFor, bestEffort, bindNotifyLedgerHost, boundedPrettySerialize, buildEngineModelsPromptAppend, buildSubagentEngineSection, cancelHandler, cleanupStaleTmpFiles, cleanupWorktree, clearSkillPathCache, closeHandler, closeOutInFlightCalls, collectWorktreePatch, computeElapsedSeconds, configureCore, configureNotifyDomain, countAllToolCalls, createConcurrencyPool, createSubagentService, createUiRequestHandlerForMode, createZcodeEngine, deleteWorkflow, deriveOutcome, discoverAgents, discoverResources, discoverWorkflows, displayAgentName, endedMessageGuard, escapeXml, evictDoneRunsBeyondCap, executeNestedWorkflow, finalizeRun, findFlattenedArgKeys, findWorkspaceRoot, forkFromHandler, formatAgentList, formatModelList, formatWorkflowList, fromRunSnapshot, generateWorkflowScript, getAllToolCalls, getBoundNotifyLedger, getCachedFileContent, getCachedParsed, getHostServices, getLogger, getModelConfigService, getOrCreateChannelRegistry, getSubagentService, getWorkflow, getWorkflowByPath, gitRun, hasApiKey, invalidAgentRefMessage, invalidateCache, isProcessAlive, isResumable, isSafeId, isScriptRunning, isTreeDirty, killAllSpawnedChildren, killRecordChildWithEscalation, lintScript, listHandler, listStaleTmpFiles, listWorktreePorcelain, loadWorkflowScriptByPath, loadWorkflows, makeSerializeFailedResult, mapExternalState, maxTurnsToWatchdogMs, maybeCleanupExpiredSessionFiles, messageHandler, normalizeArgsByMeta, normalizeEngineId, normalizeRef, normalizeWorkflowRef, notifyGateAllowsDelivery, parseAgentProfile, parseAtomicTmpPath, parseEngineHandle, parseResourceMeta, parseResourceMetaDetailed, postBudgetUpdate, projectLiveProgress, projectOutcome, readGlobalConfig, readSubagentHistoryMessages, recordToListItem, recoverCrashedRuns, registerPiEngine, registerZcodeEngine, renderXmlSection, resetRebuildFailureInjectionForTest, routeEngine, runAndWait, runSummary, runWorkflow, saveWorkflow, scheduleTimeBudget, setModelConfigService, setSubagentService, sortByCodepoint, splitZcodeModelRef, startHandler, summarizeDescription, syncEnginesFile, terminateRunningRuns, toRunSnapshot, toSubagentRecordEntry, wrapForkFromPrompt, writeAtomicFile, writeAtomicFileSync };
+export { AGENT_REF_EXT, AgentCall, AgentCallOpts, type AgentEntry, AgentEventLogEntry, type AgentProfile, AgentRegistry, AgentResult, type AgentRunner, type ArgKeySet, type ArgMetaOptions, type ArgMetaWarning, type AtomicTmpRef, type AtomicWriteFileOptions, type AtomicWriteOptions, BG_MESSAGE, BgResponse, Budget, CORE_PACKAGE_VERSION, type CachedWorkflowMeta, type CancelHandlerInput, type CancelHandlerResult, CancelResponse, type ChangeListener, type CleanupStaleTmpOptions, type CleanupStaleTmpResult, type CleanupWorktreeOptions, type CloseHandlerInput, type CloseHandlerResult, CloseResponse, ClosedReason, type CollectWorktreePatchOptions, type ConcurrencyPool, type CreateConcurrencyPoolOptions, type D8CompatZcodeEngineDeps, DEFAULT_LIST_LIMIT, DEFAULT_PROVIDER_ID, DEFAULT_SAVE_MIN_INTERVAL_MS, DEFAULT_STATE_MAX_RUNS, DEFAULT_WORKFLOW_SAVED_DIR, DEFAULT_WORKFLOW_TMP_DIR, DialogGlobalQueue, type DiscoveredResource, DiscoveryRoot, DisplayItem, DoneReason, EnginePort, type EngineRouteOptions, type EngineRouteResult, type EngineRouting, type EngineRoutingInput, type EngineRoutingSource, ExecutionMode, ExecutionOutcome, ExecutionRecord, ExecutionStatus, ExecutionTraceNode, ExternalState, FORK_FROM_DEFAULT_PROMPT, FileRunStore, type FinalizeRunOptions, type ForkFromHandlerInput, type ForkFromHandlerResult, ForkFromResponse, type GenerateWorkflowScriptOptions, type GenerateWorkflowScriptResult, GitRunError, type GlobalConfigReadResult, IDENTITY_CUSTOM_TYPE, INDEX_FILENAME, type InvalidAgentRefMessageOptions, type LauncherDeps, type LifecycleDeps, type LintFinding, type LintResult, type ListFormatOptions, type ListHandlerInput, type ListHandlerResult, ListResponse, type ListWorktreePorcelainOptions, MAX_LIST_LIMIT, MAX_RETAINED_DONE_RUNS, MAX_TIMER_DELAY_MS, type MessageHandlerInput, type MessageHandlerResult, MessageResponse, ModelConfigService, type ModelConfigServiceInit, type ModelEntry, ModelInfo, type ModelListFormatOptions, type ModelReasoningInfo, NOTIFY_CONTRACT, type NormalizeWorkflowRefOptions, type NormalizedArgs, type NormalizedWorkflowRef, type NotifyDomainPorts, type NotifyLedgerHost, type PatchBaselineAnchor, type PruneStateDeps, type QueuePolicy, RecordStore, type RecordStorePi, type RecoverCrashedRunsHooks, type RecoverCrashedRunsResult, type ResourceKind, type ResourceSource, type RunSnapshot, type RunSpec, type RunState, RunStatus, type RunStore, SAFE_ID_RE, SNAPSHOT_VERSION, SUBAGENT_RECORD_CUSTOM_TYPE, type ScanConfig, type StartHandlerInput, type StartHandlerResult, type StatusFilter, type SubagentIdentityData, SubagentListItem, SubagentRecord, type SubagentRecordEntryData, SubagentService, type SubagentServiceInit, SubagentStream, SubprocessAgentRunner, THINKING_ORDER, Trace, WORKFLOW_REF_EXT, WORKFLOW_REF_RESERVED_NAMES, type WorkerHandlers, type WorkerHost, WorkerHostImpl, WorkerLogEntry, type WorkflowDirOptions, type WorkflowEntry, type WorkflowMeta, type WorkflowRefInvalidReason, WorkflowRun, type WorkflowRunMeta, type WorkflowRunResult, type WorkflowRunSummary, type WorkflowScanConfig, WorkflowScript, type WorkflowScriptRegistry, WorkflowScriptRegistryImpl, type WorkflowSource, WorktreeManager, type WorktreePatchResult, ZCODE_FALLBACK_DEFAULT_MODEL, type ZcodeEngineDeps, abortRun, argKeysFromMeta, assertSafeId, atomicTmpPathFor, bestEffort, bindNotifyLedgerHost, boundedPrettySerialize, buildEngineModelsPromptAppend, buildSubagentEngineSection, cancelHandler, cleanupStaleTmpFiles, cleanupWorktree, clearSkillPathCache, closeHandler, closeOutInFlightCalls, collectWorktreePatch, computeElapsedSeconds, configureNotifyDomain, countAllToolCalls, createConcurrencyPool, createSubagentService, createUiRequestHandlerForMode, createZcodeEngine, deleteWorkflow, deriveOutcome, discoverAgents, discoverResources, discoverWorkflows, displayAgentName, endedMessageGuard, escapeXml, evictDoneRunsBeyondCap, executeNestedWorkflow, finalizeRun, findFlattenedArgKeys, findWorkspaceRoot, forkFromHandler, formatAgentList, formatModelList, formatWorkflowList, fromRunSnapshot, generateWorkflowScript, getAllToolCalls, getBoundNotifyLedger, getCachedFileContent, getCachedParsed, getModelConfigService, getOrCreateChannelRegistry, getSubagentService, getWorkflow, getWorkflowByPath, gitRun, hasApiKey, invalidAgentRefMessage, invalidateCache, isProcessAlive, isResumable, isSafeId, isScriptRunning, isTreeDirty, killAllSpawnedChildren, killRecordChildWithEscalation, lintScript, listHandler, listStaleTmpFiles, listWorktreePorcelain, loadWorkflowScriptByPath, loadWorkflows, makeSerializeFailedResult, mapExternalState, maxTurnsToWatchdogMs, maybeCleanupExpiredSessionFiles, messageHandler, normalizeArgsByMeta, normalizeRef, normalizeWorkflowRef, notifyGateAllowsDelivery, parseAgentProfile, parseAtomicTmpPath, parseEngineHandle, parseResourceMeta, parseResourceMetaDetailed, postBudgetUpdate, projectLiveProgress, projectOutcome, pruneStateFilesBeyondCap, readGlobalConfig, readSubagentHistoryMessages, recordToListItem, recoverCrashedRuns, registerNativeSessionReader, registerZcodeEngine, renderXmlSection, resetRebuildFailureInjectionForTest, routeEngine, runAndWait, runSummary, runWorkflow, saveWorkflow, scheduleTimeBudget, setEngineDiscoveryRescanOptions, setModelConfigService, setSubagentService, sortByCodepoint, splitZcodeModelRef, startHandler, summarizeDescription, syncEnginesFile, terminateRunningRuns, toRunSnapshot, toSubagentRecordEntry, wrapForkFromPrompt, writeAtomicFile, writeAtomicFileSync };