@zhushanwen/subagent-core 0.5.1 → 0.6.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 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-Dv4QhSJ_.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-Dv4QhSJ_.cjs';
+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 { Worker } from 'node:worker_threads';
 export { ZCODE_FALLBACK_DEFAULT_MODEL } from './execution/engine/engines/zcode/constants.cjs';
 import '@xyz-agent/extension-protocol';
@@ -633,15 +633,31 @@ declare class RecordStore {
      * - 文件不可读（IO 错误，可能暂时）→ 不判终态，落 resumable entry（防御性路径，
      *   IO 恢复后重开可重判）。
      *
+     * [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 保持首参）：既有调用面只传过滤参。
+     *
      * 防重：orphanJudged 实例级缓存（resumable 形态无 sidecar 锚，同进程重复调用跳过；
      * 终态形态双重防护 = sidecar + 缓存）。调用方：index.ts session_start 恢复段（一次）。
      */
-    recoverOrphanRecords(rootSessionFilter?: string): void;
+    recoverOrphanRecords(rootSessionFilter?: string, mainSessionFile?: string): void;
     /**
      * 单孤儿 record 的终态判定与落 entry（residual-fixes §5.2 三判据 + chat 分流）。
      * 防重锚（orphanJudged 标记）已由调用方完成。
+     *
+     * [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 写点与子进程首笔写入之间的窗口；外部
@@ -663,6 +679,17 @@ declare class RecordStore {
     /** 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 后短路。
@@ -2013,8 +2040,25 @@ declare class SubagentService {
     /** [D4-①] 通知簇 host 面（notifyComplete/notifyClosed/pending 注册注销 + notifier
      *  实例封装，原私有通知簇四方法与模块函数的搬移落点——notify-host.ts）。
      *  deps 惰性求值（pi/session 级状态运行时可变），行为与原 constructor 内
-     *  createNotifier(this.piAdapter()) 逐字节等价。session_start revive，shutdown dispose。 */
+     *  createNotifier(this.piAdapter()) 逐字节等价。session_start revive，shutdown dispose。
+     *  [sync-collect 合并] toNotifyRecord/notify/notifyBatch 随批路由需要由 host 导出
+     *  （collectCoordinator 闭包与 E9/E1 直发路径消费，见 notify-host.ts 接口注释）。 */
     private readonly notifyHost;
+    /** collectCoordinator（subagent-sync-collect U2）：sync 批缓冲 + 闭合检测 + flush 分流。 */
+    private readonly collectCoordinator;
+    /** [E9] dispose 时已转 async 写账的成员 id（revive 后 flushBatch 防御过滤用）。
+     *  背景：dispose 后同进程 revive（/resume /fork /new）时协调器内部缓冲仍持有已转换
+     *  成员快照（协调器无 drain API，U5 领地不含 collect-coordinator.ts）——若后续新
+     *  sync 成员触发闭合，陈旧快照会随批重投（新成员集新 hash，账本跨键不拦）→ 双重
+     *  通知。flushBatch 闭包按本集过滤，陈旧成员零重投。id 唯一 per spawn，无误伤面。 */
+    private readonly e9ConvertedIds;
+    /** [v2 D4] E1 等待分支的 settled 有界重扫状态（null = 未注册）。disposed 后保持
+     *  非 null——同 session 内不再重复注册（补发完成/达限后 settled 边沿已无事可做，
+     *  单注册即单重扫）；initSession（revive）置 null 允许新 session 重新注册。
+     *  pi.on 无 off（见 armSettledRescan）：旧 handler 闭包捕获旧 state，未 disposed 时
+     *  遇 settled 边沿仍会执行，扫描 this.mainSessionFile 当前值（handler 不绑定注册时
+     *  的文件域）；dispose 的惰化处置见 dispose()。 */
+    private settledRescanState;
     /** [MF#4][MF#2] fork 深度按 async 调用链传递（AsyncLocalStorage），替代共享可变计数器。
      *  主 session=0；fork 进入子 session 期间推进为子深度，供嵌套 fork 经 ALS 读到自身深度作为
      *  parentForkDepth。并发 background fork 各自独立调用链，不再互相压低深度值。
@@ -2049,6 +2093,11 @@ declare class SubagentService {
      *  纯委托同上。PiEngineService 适配器不经此——引擎边界走 piEngineServiceAdapter）。 */
     readonly chatActions: SubagentChatActions;
     private readonly manifestStore;
+    /**
+     * [D6 #7a] records 目录（与 manifestStore 同源同一推导）——屏障失败 warn 带 manifest
+     * 文件路径用（ManifestStore.dir 私有，此处不破封装另存同源值；漂移由构造点同语句保证不发生）。
+     */
+    private readonly recordsDir;
     /**
      * [T1/PS-9] subagent sessionDir（getSubagentSessionDir 推导，与 store 同源同一 rootCwd）。
      * 传给 doFinalizeRecord 的 FinalizeDeps.sessionDir——record.sessionFile 缺失时 finalize
@@ -2088,6 +2137,8 @@ declare class SubagentService {
     /** 孤儿终态恢复委托（RecordStore.recoverOrphanRecords 的唯一调用入口，维持 store
      *  private 封装——与 recoverManifestTmpFiles 同模式；[D4] public 面收窄：唯一调用方
      *  是 initSession，转 private）。判定语义见 store 侧注释。
+     *  mainSessionFile 随调用透传（v2 D3 覆写 merge 数据源：主文件末条 entry 的批域
+     *  标记与轮终 result/model；initSession 先赋值后恢复，时序就绪）。
      *  随后跑 entry-born 孤儿恢复（无子文件锚的 register-only record，spawn 窗口期死亡，
      *  E2E 实测缺口）——主 session 文件经 getMainSessionFile 注入（构造期可空）。 */
     private recoverOrphanRecords;
@@ -2139,6 +2190,107 @@ declare class SubagentService {
      * listener 仍然存活。若 pending-notifications 先于本扩展执行 session_shutdown（后注册
      * 先执行的语义下会如此），listener 已注销，unregister 事件被静默丢弃。这是可接受的
      * 退化——进程退出后两侧状态本就不保证一致，下次 session_start 的 crash recovery 会修正。 */
+    /** [U4 deviation #8 接线] collectSync 预算热读（flush 时读值，与 getCollectSyncDefault
+     *  同款访问链 modelService.getGlobalConfig().collectSync）。节缺失/读失败 → undefined
+     *  → notifyBatch 落 buildBatchLlmContent 设计默认值（4000/24000，E5 不炸启动）。
+     *  sanitizeCollectSync 保证节存在时两字段必有合法正整数。 */
+    private getCollectSyncBudget;
+    /** [E9 专用] batchFinalized 落标 + manifest fire-and-forget 写（设计 §3.1.5 E9）。
+     *  批通知路径（flush/E1）已改走「manifest 屏障 → 写账 → 纯落标」序列（「通知可达
+     *  ⇒ 索引就位」的构造性保证，见 flushBatch 闭包 / runSyncCollectRecoveryScan），
+     *  不再经本 helper；仅 E9 转换的成员保持原形态——其走 async 单条通知（全文注入、
+     *  无指针行消费），manifest 无时序要求，落标后 fire-and-forget 补写（list 后手动
+     *  反查的顺带索引）。
+     *  路径 = getFullRecord 冷路径重建 → appendBatchFinalizedEntry 纯落标 → fire
+     *  manifest。getFullRecord 不可达（子 session 文件缺失/已 GC）→ 跳过该成员
+     *  （详见 flushBatch 闭包注释）。 */
+    private markMembersBatchFinalized;
+    /** batchFinalized 落标唯一出口（appendEntry 公共末步，纯落标）：显式覆写
+     *  collectMode/batchFinalized → reportSubagentRecord。覆写动机：recordToSubagent
+     *  投影已含两字段（U5 修复），但 getFullRecord 冷路径含 sidecar/manifest 重建分支
+     *  （非 entry 源），显式赋值防非 entry 源重建时丢标记。
+     *
+     *  [v2 D1 断链 1] 落标即「离开批 = 通知已/即将送达 = 指针行即将被消费」——成功
+     *  成员走 SP-5 改道 doFinalizeRoundToIdle（不写 manifest），批路径不补写则
+     *  records/<sa-id>.json 永不产生、session-reader 反查 0 命中。manifest 写点已从
+     *  本出口的 fire-and-forget 前移至各调用方：批通知路径（flush/E1）在写账前屏障
+     *  await 全部落盘（「通知可达 ⇒ 索引就位」的构造性保证）；E9 保持落标后
+     *  fire-and-forget（async 单条通知无指针行消费，无时序要求）。
+     *  rec 两来源（flush 的 getFullRecord 内存全量 / E1 的 rebuildEntryRecord 重建
+     *  快照）必需字段恒齐备（id/agentName←agent/rootSessionId/createdAt←startedAt），
+     *  task/slug/parentRecordId 等可选 undefined 自然缺省。 */
+    private appendBatchFinalizedEntry;
+    /** 批成员 manifest（sa- id → sessionFile 反查索引）写的唯一投影点（D2 字段投影 +
+     *  status 如实投影：成功成员此刻 record 实态 running+resumable → "running"，后续
+     *  message upgrade 走完整 finalize 时 Step 4 原子覆盖为 "closed"）。
+     *  返回原始 promise 不吞错——失败语义由调用方定：批通知路径经
+     *  writeSyncBatchManifestBarrier 的 allSettled（debug 不阻断写账）；E9 经
+     *  fire-and-forget catch（debug 不阻断落标）。 */
+    private writeBatchMemberManifest;
+    /** [时序屏障] 批通知路径（flush/E1）专用：成员 manifest 并行写 + await 全部完成
+     *  （allSettled）后才允许写账投递——「通知可达 ⇒ 索引就位」的构造性保证。写失败
+     *  不阻断（best-effort 语义与 doFinalizeRecord Step 4 一致：反查索引缺失只影响指针行
+     *  反查，session-reader 错误文案已指引绝对路径兜底，不构成写账失败）；warn 留痕
+     *  （D6 #7a / SC-1：屏障失败意味着该成员指针行反查索引缺失，debug 级在排障时不可见）。 */
+    private writeSyncBatchManifestBarrier;
+    /** [E9] dispose 时批未闭合：缓冲中已终态未通知成员逐条转 async 语义写账（放弃攒批）
+     *  + 落 batchFinalized 标记（E1 重建扫描据此排除，防双重通知），交由既有 shutdown
+     *  flush / resume 重放兑底；仍在跑的成员走现有退出路径（disposeAllRecords 关闭，
+     *  与 async 一致）。写账用 notifier.notify 现有通路（ledger.record + attemptDeliver）。
+     *  源序：写账先于落标——写账后崩溃 → E1 重建收该成员，但 async notifyId 与批 hash
+     *  跨键不拦的重发属设计披露的 E9 残余窗（at-least-once 良性，PS-17 同族，v1 接受）。 */
+    private convertPendingSyncBufferToAsync;
+    /**
+     * [E1] sync 批崩溃恢复钩子（设计 §3.1.5 E1，index.ts session_start 恢复编排处调用，
+     * 须晚于 initSession——孤儿终态恢复先行收敛 running 成员，「全员终态」判定才可达）：
+     *
+     *  - 扫描主 session 文件每 id 末条 subagent-record entry（store.scanLastRecordEntries，
+     *    collectLastRecordEntries 同构 + 投影扩展含 collectMode/batchFinalized + 终态五
+     *    字段；禁走 collectRecords light 路径——主 session 落标 entry 对它不可见）；
+     *  - 只收 collectMode=sync 且无 batchFinalized 的成员（排除已通过批 flush 或 E9
+     *    转换离场的，防双重通知），按 rootSessionId 过滤当前根；
+     *  - 全员终态且账本无同成员集批记录 → manifest 屏障（await 落盘，「通知可达 ⇒
+     *    索引就位」构造性保证，与 flushBatch 同款）→ notifyBatch 补发（内容 = 末条
+     *    entry 终态快照；账本 record 同 hash 幂等拒绝 = 已投递/已在账，两种结局都算
+     *    「已处理」）；
+     *  - 仍有 running → 本次不动，注册 settled 有界重扫（D4，见 armSettledRescan）——
+     *    成员延迟终态（主 agent 冷路径 resume → 正常流落 entry）由 settled 边沿驱动
+     *    重扫收敛，不再依赖「下次 session_start」作唯一再驱动（v2 §2.4 断链 4）；
+     *    running 口径与协调器同构
+     *    （resumable 豁免，v2 D3——覆写不可达的防御分支残余不被误判「仍在跑」）；
+     *  - 补发尝试后统一补 batchFinalized 标记（账本拒绝也算已投递；直接用末条重建快照
+     *    落标不经 getFullRecord——子文件缺失/已 GC 时标记仍可落盘，窗口自愈不依赖二次
+     *    重启；补标自身崩溃重入幂等收敛，末条 entry last-writer-wins）。
+     *
+     *  async 化（时序屏障修复）：返回 Promise 但**内部自捕获不外抛**——宿主 index.ts
+     *  session_start 以同步 try/catch 调用（其 catch 兑现不到 promise 内的异常），
+     *  自捕获维持同款 warn 容错语义，浮动调用零适配、不产生 unhandled rejection。
+     *
+     *  [U8 拆批修复] 与协调器合批排程无交集：E1 只在 session_start 编排处运行（此前
+     *  dispose 已取消挂起排程），补发直走 notifier.notifyBatch 不经协调器；异常时序
+     *  相撞由账本 sync-batch:<hash> 幂等拒绝兜底。
+     */
+    recoverSyncCollectBatch(): Promise<void>;
+    /** [E1/D4] 单次「扫描→判定→可达则补发+落标」，E1 首扫与 settled 重扫共用同一实现
+     *  （防两处复制粘贴分岔）。三态返回：idle（无 sync 候选——已全部落标/E9 转换/异根，
+     *  无事可等）/ waiting（仍有 running 成员，本次不动）/ dispatched（全员终态，已补发
+     *  +统一落标）。async：补发前有 manifest 屏障 await（见函数头 E1 注释）。 */
+    /** 返回 outcome + waitingIds（达限 warn 需滞留成员 id，D6 #7b——仅 waiting 态非空）。 */
+    private runSyncCollectRecoveryScan;
+    /** [v2 D4] 注册 agent_settled 有界重扫（幂等：settledRescanState 非 null 不叠加注册
+     *  ——E1 现仅 session_start 单调用点，守卫是防第二入口引入时的注册叠加断言面）。
+     *  每次 settled 边沿重跑同一 E1 扫描（runSyncCollectRecoveryScan）：dispatched
+     *  （补发+落标完成，scan 的 warn 已留痕）或 idle（候选已被其他通路落标）→ disposed；
+     *  累计 SETTLED_RESCAN_LIMIT 次仍在等 → disposed + warn 留痕（D6 #7b / SC-2：达限
+     *  放弃重扫意味着滞留成员的批通知要等下次 session_start 才收敛，含滞留 id 的 warn
+     *  是唯一线索，debug 级排障不可见；后续事件零处理，下次 session_start 再收敛）。
+     *  pi.on 无 off（0.84.4 实装）——disposed 标志包装兑现退订（scheduler extension
+     *  index.ts subscribeSettled 同款先例）。P-settled 定谳（0.84.4 dist 实装证据）：
+     *  pi.on 为 per-extension 列表分发——loader.js `on()` 把 handler push 进
+     *  extension.handlers.get(event) 数组（非覆盖），runner.js `emit()` 对全部
+     *  extension 的全部 handler 逐一 await；故本注册与 ledger host 经
+     *  piAdapter.onAgentSettled 注册的 settled 分发互不干扰，无需降级并入 host 链。 */
+    private armSettledRescan;
     dispose(): void;
     /**
      * [T4④ / PS-5] shutdown flush 被门拦时把未投递 pending 复写落盘（供重启 replay）。
@@ -2332,6 +2484,17 @@ declare class SubagentService {
      *  [perf] 磁盘源为 light（头部 identity + 状态，无 eventLog/result/turns 等重数据）
      *  ——列表/补全/hasRunning 够用；详情场景调 getFullRecord(id) 懒加载补齐。 */
     private collectRecords;
+    /**
+     * collectSync.default 当前生效值（subagent-sync-collect U2，偏差#3 接线：
+     * startHandler 缺省 collect 解析用）。
+     * config 未配/读失败 → DEFAULT_COLLECT_SYNC.default 兜底（E5 不炸启动）。
+     * 新 session 生效语义与 engine 配置一致（globalConfig 由 ModelConfigService
+     * reloadGlobalConfig 刷新）。
+     */
+    /** collectSync 节单读取点（S9，code-simplify）：「读节」一处，「投影成 default 或
+     *  budget」各自 accessor 负责（getCollectSyncDefault / getCollectSyncBudget）。 */
+    private collectSyncSection;
+    getCollectSyncDefault(): "async" | "sync";
     /** [perf] 单 record 详情懒加载（全量：eventLog/displayItems/result/turns/tokens）。
      *  内存 running record 直接投影；磁盘 record 全量重建（per-file 缓存，stat 戳校验）。
      *  返回 undefined：id 不存在于内存与磁盘。 */
@@ -3826,6 +3989,18 @@ interface SubagentRecordEntryData {
         journalPath?: string;
         poolKey: string;
     };
+    /**
+     * 同步收集模式标记（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+     * undefined = async（缺省语义，旧 entry 零迁移——undefined 经 JSON.stringify 自然缺省）。
+     * 消费方：U5 rebuildEntryRecord 投影扩展 + E1 重建扫描。
+     */
+    collectMode?: "sync";
+    /**
+     * 离开批终局标记（subagent-sync-collect 设计 §3.1.3，U1 foundation）。两出口统一
+     * 落标（批闭合 flush / E9 dispose 转换，均 appendEntry 持久化）。undefined =
+     * 未离开批 / 旧 entry 零迁移。消费方：U5 E1 重建扫描只收无标记成员（防双重通知）。
+     */
+    batchFinalized?: boolean;
 }
 /** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。
  *
@@ -4035,6 +4210,14 @@ interface StartHandlerInput {
     idleTimeoutMs?: number;
     /** 执行引擎（三层路由第一层：本参数 > agent frontmatter engine > config defaultEngine）。 */
     engine?: string;
+    /**
+     * 同步收集模式（subagent-sync-collect U1 foundation）。undefined = config
+     * collectSync.default（缺省 "async"）。schema 层枚举限 "async"|"sync"；运行时
+     * 宽收 string 与 engine 字段同风格（pi 工具框架把 schema Static 解析为 string；
+     * 非法值 ≠ "sync" 按 async 处理，E4 守卫用精确 "sync" 判定）。透传
+     * service.execute（ExecuteOptions.collect；record.collectMode 落点归 U2 接线）。
+     */
+    collect?: string;
 }
 /** start 领域对象（宿主 adapter 包成 bg 工具结果）。 */
 type StartHandlerResult = {
@@ -6152,6 +6335,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.5.1";
+declare const CORE_PACKAGE_VERSION = "0.6.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 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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-Dv4QhSJ_.js';
-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-Dv4QhSJ_.js';
+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.js';
+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.js';
 import { Worker } from 'node:worker_threads';
 export { ZCODE_FALLBACK_DEFAULT_MODEL } from './execution/engine/engines/zcode/constants.js';
 import '@xyz-agent/extension-protocol';
@@ -633,15 +633,31 @@ declare class RecordStore {
      * - 文件不可读（IO 错误，可能暂时）→ 不判终态，落 resumable entry（防御性路径，
      *   IO 恢复后重开可重判）。
      *
+     * [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 保持首参）：既有调用面只传过滤参。
+     *
      * 防重：orphanJudged 实例级缓存（resumable 形态无 sidecar 锚，同进程重复调用跳过；
      * 终态形态双重防护 = sidecar + 缓存）。调用方：index.ts session_start 恢复段（一次）。
      */
-    recoverOrphanRecords(rootSessionFilter?: string): void;
+    recoverOrphanRecords(rootSessionFilter?: string, mainSessionFile?: string): void;
     /**
      * 单孤儿 record 的终态判定与落 entry（residual-fixes §5.2 三判据 + chat 分流）。
      * 防重锚（orphanJudged 标记）已由调用方完成。
+     *
+     * [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 写点与子进程首笔写入之间的窗口；外部
@@ -663,6 +679,17 @@ declare class RecordStore {
     /** 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 后短路。
@@ -2013,8 +2040,25 @@ declare class SubagentService {
     /** [D4-①] 通知簇 host 面（notifyComplete/notifyClosed/pending 注册注销 + notifier
      *  实例封装，原私有通知簇四方法与模块函数的搬移落点——notify-host.ts）。
      *  deps 惰性求值（pi/session 级状态运行时可变），行为与原 constructor 内
-     *  createNotifier(this.piAdapter()) 逐字节等价。session_start revive，shutdown dispose。 */
+     *  createNotifier(this.piAdapter()) 逐字节等价。session_start revive，shutdown dispose。
+     *  [sync-collect 合并] toNotifyRecord/notify/notifyBatch 随批路由需要由 host 导出
+     *  （collectCoordinator 闭包与 E9/E1 直发路径消费，见 notify-host.ts 接口注释）。 */
     private readonly notifyHost;
+    /** collectCoordinator（subagent-sync-collect U2）：sync 批缓冲 + 闭合检测 + flush 分流。 */
+    private readonly collectCoordinator;
+    /** [E9] dispose 时已转 async 写账的成员 id（revive 后 flushBatch 防御过滤用）。
+     *  背景：dispose 后同进程 revive（/resume /fork /new）时协调器内部缓冲仍持有已转换
+     *  成员快照（协调器无 drain API，U5 领地不含 collect-coordinator.ts）——若后续新
+     *  sync 成员触发闭合，陈旧快照会随批重投（新成员集新 hash，账本跨键不拦）→ 双重
+     *  通知。flushBatch 闭包按本集过滤，陈旧成员零重投。id 唯一 per spawn，无误伤面。 */
+    private readonly e9ConvertedIds;
+    /** [v2 D4] E1 等待分支的 settled 有界重扫状态（null = 未注册）。disposed 后保持
+     *  非 null——同 session 内不再重复注册（补发完成/达限后 settled 边沿已无事可做，
+     *  单注册即单重扫）；initSession（revive）置 null 允许新 session 重新注册。
+     *  pi.on 无 off（见 armSettledRescan）：旧 handler 闭包捕获旧 state，未 disposed 时
+     *  遇 settled 边沿仍会执行，扫描 this.mainSessionFile 当前值（handler 不绑定注册时
+     *  的文件域）；dispose 的惰化处置见 dispose()。 */
+    private settledRescanState;
     /** [MF#4][MF#2] fork 深度按 async 调用链传递（AsyncLocalStorage），替代共享可变计数器。
      *  主 session=0；fork 进入子 session 期间推进为子深度，供嵌套 fork 经 ALS 读到自身深度作为
      *  parentForkDepth。并发 background fork 各自独立调用链，不再互相压低深度值。
@@ -2049,6 +2093,11 @@ declare class SubagentService {
      *  纯委托同上。PiEngineService 适配器不经此——引擎边界走 piEngineServiceAdapter）。 */
     readonly chatActions: SubagentChatActions;
     private readonly manifestStore;
+    /**
+     * [D6 #7a] records 目录（与 manifestStore 同源同一推导）——屏障失败 warn 带 manifest
+     * 文件路径用（ManifestStore.dir 私有，此处不破封装另存同源值；漂移由构造点同语句保证不发生）。
+     */
+    private readonly recordsDir;
     /**
      * [T1/PS-9] subagent sessionDir（getSubagentSessionDir 推导，与 store 同源同一 rootCwd）。
      * 传给 doFinalizeRecord 的 FinalizeDeps.sessionDir——record.sessionFile 缺失时 finalize
@@ -2088,6 +2137,8 @@ declare class SubagentService {
     /** 孤儿终态恢复委托（RecordStore.recoverOrphanRecords 的唯一调用入口，维持 store
      *  private 封装——与 recoverManifestTmpFiles 同模式；[D4] public 面收窄：唯一调用方
      *  是 initSession，转 private）。判定语义见 store 侧注释。
+     *  mainSessionFile 随调用透传（v2 D3 覆写 merge 数据源：主文件末条 entry 的批域
+     *  标记与轮终 result/model；initSession 先赋值后恢复，时序就绪）。
      *  随后跑 entry-born 孤儿恢复（无子文件锚的 register-only record，spawn 窗口期死亡，
      *  E2E 实测缺口）——主 session 文件经 getMainSessionFile 注入（构造期可空）。 */
     private recoverOrphanRecords;
@@ -2139,6 +2190,107 @@ declare class SubagentService {
      * listener 仍然存活。若 pending-notifications 先于本扩展执行 session_shutdown（后注册
      * 先执行的语义下会如此），listener 已注销，unregister 事件被静默丢弃。这是可接受的
      * 退化——进程退出后两侧状态本就不保证一致，下次 session_start 的 crash recovery 会修正。 */
+    /** [U4 deviation #8 接线] collectSync 预算热读（flush 时读值，与 getCollectSyncDefault
+     *  同款访问链 modelService.getGlobalConfig().collectSync）。节缺失/读失败 → undefined
+     *  → notifyBatch 落 buildBatchLlmContent 设计默认值（4000/24000，E5 不炸启动）。
+     *  sanitizeCollectSync 保证节存在时两字段必有合法正整数。 */
+    private getCollectSyncBudget;
+    /** [E9 专用] batchFinalized 落标 + manifest fire-and-forget 写（设计 §3.1.5 E9）。
+     *  批通知路径（flush/E1）已改走「manifest 屏障 → 写账 → 纯落标」序列（「通知可达
+     *  ⇒ 索引就位」的构造性保证，见 flushBatch 闭包 / runSyncCollectRecoveryScan），
+     *  不再经本 helper；仅 E9 转换的成员保持原形态——其走 async 单条通知（全文注入、
+     *  无指针行消费），manifest 无时序要求，落标后 fire-and-forget 补写（list 后手动
+     *  反查的顺带索引）。
+     *  路径 = getFullRecord 冷路径重建 → appendBatchFinalizedEntry 纯落标 → fire
+     *  manifest。getFullRecord 不可达（子 session 文件缺失/已 GC）→ 跳过该成员
+     *  （详见 flushBatch 闭包注释）。 */
+    private markMembersBatchFinalized;
+    /** batchFinalized 落标唯一出口（appendEntry 公共末步，纯落标）：显式覆写
+     *  collectMode/batchFinalized → reportSubagentRecord。覆写动机：recordToSubagent
+     *  投影已含两字段（U5 修复），但 getFullRecord 冷路径含 sidecar/manifest 重建分支
+     *  （非 entry 源），显式赋值防非 entry 源重建时丢标记。
+     *
+     *  [v2 D1 断链 1] 落标即「离开批 = 通知已/即将送达 = 指针行即将被消费」——成功
+     *  成员走 SP-5 改道 doFinalizeRoundToIdle（不写 manifest），批路径不补写则
+     *  records/<sa-id>.json 永不产生、session-reader 反查 0 命中。manifest 写点已从
+     *  本出口的 fire-and-forget 前移至各调用方：批通知路径（flush/E1）在写账前屏障
+     *  await 全部落盘（「通知可达 ⇒ 索引就位」的构造性保证）；E9 保持落标后
+     *  fire-and-forget（async 单条通知无指针行消费，无时序要求）。
+     *  rec 两来源（flush 的 getFullRecord 内存全量 / E1 的 rebuildEntryRecord 重建
+     *  快照）必需字段恒齐备（id/agentName←agent/rootSessionId/createdAt←startedAt），
+     *  task/slug/parentRecordId 等可选 undefined 自然缺省。 */
+    private appendBatchFinalizedEntry;
+    /** 批成员 manifest（sa- id → sessionFile 反查索引）写的唯一投影点（D2 字段投影 +
+     *  status 如实投影：成功成员此刻 record 实态 running+resumable → "running"，后续
+     *  message upgrade 走完整 finalize 时 Step 4 原子覆盖为 "closed"）。
+     *  返回原始 promise 不吞错——失败语义由调用方定：批通知路径经
+     *  writeSyncBatchManifestBarrier 的 allSettled（debug 不阻断写账）；E9 经
+     *  fire-and-forget catch（debug 不阻断落标）。 */
+    private writeBatchMemberManifest;
+    /** [时序屏障] 批通知路径（flush/E1）专用：成员 manifest 并行写 + await 全部完成
+     *  （allSettled）后才允许写账投递——「通知可达 ⇒ 索引就位」的构造性保证。写失败
+     *  不阻断（best-effort 语义与 doFinalizeRecord Step 4 一致：反查索引缺失只影响指针行
+     *  反查，session-reader 错误文案已指引绝对路径兜底，不构成写账失败）；warn 留痕
+     *  （D6 #7a / SC-1：屏障失败意味着该成员指针行反查索引缺失，debug 级在排障时不可见）。 */
+    private writeSyncBatchManifestBarrier;
+    /** [E9] dispose 时批未闭合：缓冲中已终态未通知成员逐条转 async 语义写账（放弃攒批）
+     *  + 落 batchFinalized 标记（E1 重建扫描据此排除，防双重通知），交由既有 shutdown
+     *  flush / resume 重放兑底；仍在跑的成员走现有退出路径（disposeAllRecords 关闭，
+     *  与 async 一致）。写账用 notifier.notify 现有通路（ledger.record + attemptDeliver）。
+     *  源序：写账先于落标——写账后崩溃 → E1 重建收该成员，但 async notifyId 与批 hash
+     *  跨键不拦的重发属设计披露的 E9 残余窗（at-least-once 良性，PS-17 同族，v1 接受）。 */
+    private convertPendingSyncBufferToAsync;
+    /**
+     * [E1] sync 批崩溃恢复钩子（设计 §3.1.5 E1，index.ts session_start 恢复编排处调用，
+     * 须晚于 initSession——孤儿终态恢复先行收敛 running 成员，「全员终态」判定才可达）：
+     *
+     *  - 扫描主 session 文件每 id 末条 subagent-record entry（store.scanLastRecordEntries，
+     *    collectLastRecordEntries 同构 + 投影扩展含 collectMode/batchFinalized + 终态五
+     *    字段；禁走 collectRecords light 路径——主 session 落标 entry 对它不可见）；
+     *  - 只收 collectMode=sync 且无 batchFinalized 的成员（排除已通过批 flush 或 E9
+     *    转换离场的，防双重通知），按 rootSessionId 过滤当前根；
+     *  - 全员终态且账本无同成员集批记录 → manifest 屏障（await 落盘，「通知可达 ⇒
+     *    索引就位」构造性保证，与 flushBatch 同款）→ notifyBatch 补发（内容 = 末条
+     *    entry 终态快照；账本 record 同 hash 幂等拒绝 = 已投递/已在账，两种结局都算
+     *    「已处理」）；
+     *  - 仍有 running → 本次不动，注册 settled 有界重扫（D4，见 armSettledRescan）——
+     *    成员延迟终态（主 agent 冷路径 resume → 正常流落 entry）由 settled 边沿驱动
+     *    重扫收敛，不再依赖「下次 session_start」作唯一再驱动（v2 §2.4 断链 4）；
+     *    running 口径与协调器同构
+     *    （resumable 豁免，v2 D3——覆写不可达的防御分支残余不被误判「仍在跑」）；
+     *  - 补发尝试后统一补 batchFinalized 标记（账本拒绝也算已投递；直接用末条重建快照
+     *    落标不经 getFullRecord——子文件缺失/已 GC 时标记仍可落盘，窗口自愈不依赖二次
+     *    重启；补标自身崩溃重入幂等收敛，末条 entry last-writer-wins）。
+     *
+     *  async 化（时序屏障修复）：返回 Promise 但**内部自捕获不外抛**——宿主 index.ts
+     *  session_start 以同步 try/catch 调用（其 catch 兑现不到 promise 内的异常），
+     *  自捕获维持同款 warn 容错语义，浮动调用零适配、不产生 unhandled rejection。
+     *
+     *  [U8 拆批修复] 与协调器合批排程无交集：E1 只在 session_start 编排处运行（此前
+     *  dispose 已取消挂起排程），补发直走 notifier.notifyBatch 不经协调器；异常时序
+     *  相撞由账本 sync-batch:<hash> 幂等拒绝兜底。
+     */
+    recoverSyncCollectBatch(): Promise<void>;
+    /** [E1/D4] 单次「扫描→判定→可达则补发+落标」，E1 首扫与 settled 重扫共用同一实现
+     *  （防两处复制粘贴分岔）。三态返回：idle（无 sync 候选——已全部落标/E9 转换/异根，
+     *  无事可等）/ waiting（仍有 running 成员，本次不动）/ dispatched（全员终态，已补发
+     *  +统一落标）。async：补发前有 manifest 屏障 await（见函数头 E1 注释）。 */
+    /** 返回 outcome + waitingIds（达限 warn 需滞留成员 id，D6 #7b——仅 waiting 态非空）。 */
+    private runSyncCollectRecoveryScan;
+    /** [v2 D4] 注册 agent_settled 有界重扫（幂等：settledRescanState 非 null 不叠加注册
+     *  ——E1 现仅 session_start 单调用点，守卫是防第二入口引入时的注册叠加断言面）。
+     *  每次 settled 边沿重跑同一 E1 扫描（runSyncCollectRecoveryScan）：dispatched
+     *  （补发+落标完成，scan 的 warn 已留痕）或 idle（候选已被其他通路落标）→ disposed；
+     *  累计 SETTLED_RESCAN_LIMIT 次仍在等 → disposed + warn 留痕（D6 #7b / SC-2：达限
+     *  放弃重扫意味着滞留成员的批通知要等下次 session_start 才收敛，含滞留 id 的 warn
+     *  是唯一线索，debug 级排障不可见；后续事件零处理，下次 session_start 再收敛）。
+     *  pi.on 无 off（0.84.4 实装）——disposed 标志包装兑现退订（scheduler extension
+     *  index.ts subscribeSettled 同款先例）。P-settled 定谳（0.84.4 dist 实装证据）：
+     *  pi.on 为 per-extension 列表分发——loader.js `on()` 把 handler push 进
+     *  extension.handlers.get(event) 数组（非覆盖），runner.js `emit()` 对全部
+     *  extension 的全部 handler 逐一 await；故本注册与 ledger host 经
+     *  piAdapter.onAgentSettled 注册的 settled 分发互不干扰，无需降级并入 host 链。 */
+    private armSettledRescan;
     dispose(): void;
     /**
      * [T4④ / PS-5] shutdown flush 被门拦时把未投递 pending 复写落盘（供重启 replay）。
@@ -2332,6 +2484,17 @@ declare class SubagentService {
      *  [perf] 磁盘源为 light（头部 identity + 状态，无 eventLog/result/turns 等重数据）
      *  ——列表/补全/hasRunning 够用；详情场景调 getFullRecord(id) 懒加载补齐。 */
     private collectRecords;
+    /**
+     * collectSync.default 当前生效值（subagent-sync-collect U2，偏差#3 接线：
+     * startHandler 缺省 collect 解析用）。
+     * config 未配/读失败 → DEFAULT_COLLECT_SYNC.default 兜底（E5 不炸启动）。
+     * 新 session 生效语义与 engine 配置一致（globalConfig 由 ModelConfigService
+     * reloadGlobalConfig 刷新）。
+     */
+    /** collectSync 节单读取点（S9，code-simplify）：「读节」一处，「投影成 default 或
+     *  budget」各自 accessor 负责（getCollectSyncDefault / getCollectSyncBudget）。 */
+    private collectSyncSection;
+    getCollectSyncDefault(): "async" | "sync";
     /** [perf] 单 record 详情懒加载（全量：eventLog/displayItems/result/turns/tokens）。
      *  内存 running record 直接投影；磁盘 record 全量重建（per-file 缓存，stat 戳校验）。
      *  返回 undefined：id 不存在于内存与磁盘。 */
@@ -3826,6 +3989,18 @@ interface SubagentRecordEntryData {
         journalPath?: string;
         poolKey: string;
     };
+    /**
+     * 同步收集模式标记（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+     * undefined = async（缺省语义，旧 entry 零迁移——undefined 经 JSON.stringify 自然缺省）。
+     * 消费方：U5 rebuildEntryRecord 投影扩展 + E1 重建扫描。
+     */
+    collectMode?: "sync";
+    /**
+     * 离开批终局标记（subagent-sync-collect 设计 §3.1.3，U1 foundation）。两出口统一
+     * 落标（批闭合 flush / E9 dispose 转换，均 appendEntry 持久化）。undefined =
+     * 未离开批 / 旧 entry 零迁移。消费方：U5 E1 重建扫描只收无标记成员（防双重通知）。
+     */
+    batchFinalized?: boolean;
 }
 /** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。
  *
@@ -4035,6 +4210,14 @@ interface StartHandlerInput {
     idleTimeoutMs?: number;
     /** 执行引擎（三层路由第一层：本参数 > agent frontmatter engine > config defaultEngine）。 */
     engine?: string;
+    /**
+     * 同步收集模式（subagent-sync-collect U1 foundation）。undefined = config
+     * collectSync.default（缺省 "async"）。schema 层枚举限 "async"|"sync"；运行时
+     * 宽收 string 与 engine 字段同风格（pi 工具框架把 schema Static 解析为 string；
+     * 非法值 ≠ "sync" 按 async 处理，E4 守卫用精确 "sync" 判定）。透传
+     * service.execute（ExecuteOptions.collect；record.collectMode 落点归 U2 接线）。
+     */
+    collect?: string;
 }
 /** start 领域对象（宿主 adapter 包成 bg 工具结果）。 */
 type StartHandlerResult = {
@@ -6152,6 +6335,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.5.1";
+declare const CORE_PACKAGE_VERSION = "0.6.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 };