@zhushanwen/subagent-core 0.5.1 → 0.6.0

package/src/execution/notifier.ts

@@ -1,6 +1,7 @@
 // src/execution/notifier.ts
 //
-// Background 完成回注主对话。sync 不用（调用方还在 await，结果直接返回）。
+// Background 完成回注主对话。collect:"sync" 的批通知不经单条 notify() 生命周期，
+// 由 collect-coordinator 合批后调本文件 notifyBatch 投递（成员结果不直接返回调用方）。
 //
 // 职责（U2 后）：
 //   - buildLlmContent：格式化通知文案（本文件唯一逻辑职责）
@@ -9,6 +10,7 @@
 //     notify-ledger.ts）；未装配时退回投递内核路径（createDelivery 经通知域窄端口
 //     NotifyDomainPorts 注入——core 依赖闭包不含 session-delivery，见 core/notify-ports.ts；
 //     合并窗口 / 去重 / 退避 / flush 委托内核，旧装配 / 无 ledger 测试兼容）
+//   - notifyBatch / buildBatchLlmContent / computeBatchBudget：sync 批通知三件套（U3/U4）
 //
 // 投递通道（D5 单通道化）：ledger 路径经 courier 在 settled 边沿直达
 // pi.sendMessage({triggerTurn:true})；内核路径的 port.send 同样只传
@@ -17,6 +19,8 @@
 // 设计 D5 实测证伪）；busy 场景由 ledger（settled 边沿 + isIdle 二次复查）或内核
 // settled 订阅驱动在空闲边沿投递。
 
+import { createHash } from "node:crypto";
+
 import { getLogger } from "../core/logger.ts";
 import { getNotifyDomainPorts, type DeliveryHandle, type DeliveryPort } from "../core/notify-ports.ts";
 
@@ -104,6 +108,169 @@ export interface NotifierHost {
   onAgentSettled?(handler: () => void): void;
 }
 
+/** sync 批通知幂等键前缀（subagent-sync-collect 设计 §3.1.3 批身份）。 */
+const BATCH_NOTIFY_ID_PREFIX = "sync-batch:";
+
+/**
+ * sync 批通知 notifyId：`sync-batch:<sha1(sorted member ids)>`。
+ *
+ * 成员集身份（D2 隐式批）：字典序排序后 sha1——同成员集不同登记顺序同 hash（重启
+ * 重建批 / E1 补发凭此与账本原条目对齐，幂等去重）；不同成员集必异 hash（跨批不互吞）。
+ * 成员 id 为 sa-xxx 格式无分隔歧义，join(",") 仅作边界防御。
+ */
+export function buildBatchNotifyId(memberIds: readonly string[]): string {
+  const digest = createHash("sha1")
+    .update([...memberIds].sort().join(","))
+    .digest("hex");
+  return `${BATCH_NOTIFY_ID_PREFIX}${digest}`;
+}
+
+// ─── U4 预算截断 + 指针（设计 §3.1.2 两段式预算，确定性统一收紧）───
+
+/** sync 批预算参数（config collectSync 节语义）。U4 以设计默认值锁规格；
+ * config 热读（flush 时读值）需 service 传参接线，不在本函数内自行读 config。 */
+export interface BatchBudgetParams {
+  /** 单条目正文上限（第一段截断）。 */
+  perItemChars: number;
+  /** 全批正文中量预算（第二段收紧触发阈值）。 */
+  totalChars: number;
+}
+
+/** 设计默认预算（§3.1.3 config 示例值）。 */
+const DEFAULT_BATCH_BUDGET: BatchBudgetParams = { perItemChars: 4000, totalChars: 24000 };
+
+/** 预算计划（computeBatchBudget 输出，纯数据）。 */
+export interface BatchBudgetPlan {
+  /** ② 总量再压缩是否触发（Σ per-item 截断后正文 > totalChars）。 */
+  tightened: boolean;
+  /** 每条目正文有效上限：未收紧 = perItemChars（兼作第一段截断上限）；纯清单退化 = 0。 */
+  effectivePerItem: number;
+  /** 纯清单退化（floor(totalChars/n) < 200 → 条目只剩头行 + 指针行，正文 0 字符）。 */
+  listOnly: boolean;
+}
+
+/** 绝对下限（设计 §3.1.2）：预算折算低于它时放弃正文，条目退化为「头行 + 指针行」。 */
+const LIST_ONLY_FLOOR = 200;
+
+/**
+ * 两段式批预算计划（纯函数，规格测试 collect-budget.test.ts 锁定）。
+ *
+ * ① per-item：每条目正文 ≤ perItemChars；② 总量：Σ(截断后) > totalChars 时
+ * effectivePerItem = clamp(floor(totalChars / n), 200, perItemChars) 统一收紧
+ * （n = 成员数）。刻意放弃按剩余预算的瀑布分配（非确定、依赖条目顺序），
+ * 统一收紧换确定性；收紧后 Σ ≤ n × floor(totalChars/n) ≤ totalChars 恒回到预算内。
+ * 未触发收紧时 effectivePerItem = perItemChars（同时承担第一段截断上限）。
+ */
+export function computeBatchBudget(
+  bodyLengths: readonly number[],
+  perItemChars: number,
+  totalChars: number,
+): BatchBudgetPlan {
+  const n = bodyLengths.length;
+  const sumAfterPerItem = bodyLengths.reduce((sum, len) => sum + Math.min(len, perItemChars), 0);
+  if (n === 0 || sumAfterPerItem <= totalChars) {
+    return { tightened: false, effectivePerItem: perItemChars, listOnly: false };
+  }
+  const tight = Math.floor(totalChars / n);
+  if (tight < LIST_ONLY_FLOOR) {
+    return { tightened: true, effectivePerItem: 0, listOnly: true };
+  }
+  return { tightened: true, effectivePerItem: Math.min(tight, perItemChars), listOnly: false };
+}
+
+/** 千位分隔（对齐设计样例 11,234；手写正则零 ICU 依赖）。 */
+function formatChars(n: number): string {
+  return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+/**
+ * session_read result action 的默认单条字符上限（adversarial-review-fixes §3.4 C3）。
+ * 对齐 extensions/universal/session-reader/src/result-action.ts 的 RESULT_DEFAULT_LIMIT
+ * （8000）——extension 与 runtime 包无共享常量处、反向 import 会建立 subagent-core 对
+ * extension 的依赖，故本地常量 + 注释锚定；两侧改动须同步。
+ */
+const SESSION_READ_DEFAULT_LIMIT = 8000;
+
+/** 截断指针行（设计 §3.1.2 样例）：主 agent 据此按需 session_read 取回全文。
+ *  [S8 code-simplify 口径注] 本函数的 X（total - kept）= **丢弃**字符数；而
+ *  session-reader result-action.ts formatResultTruncation 同模板的 X = **保留**
+ *  字符数（limit）——同模板异语义，统一字符串 = 行为变更，勿顺手改口径。
+ *  [C3 limit 随附] perItemLimit = 该成员实际截断预算（effectivePerItem）：预算超过
+ *  session_read 默认 limit(8000) 时附 "limit":N——模型照抄指针行 JSON 调用才能取到
+ *  ≥ 默认值的有效正文（否则默认 8000 反而少于通知里已见的 kept，触发第二层截断）；
+ *  ≤8000 不附（默认已覆盖，避免噪音）。 */
+function buildTruncationPointer(id: string, kept: number, total: number, perItemLimit: number): string {
+  const limitPart = perItemLimit > SESSION_READ_DEFAULT_LIMIT ? `,"limit":${perItemLimit}` : "";
+  return `[truncated ${formatChars(total - kept)} of ${formatChars(total)} chars — full result: session_read {"action":"result","session":"${id}"${limitPart}}]`;
+}
+
+/** closed 成员 outcome 兑底物化（与下方 notify() 投影边界同款）；running 原样透传。 */
+function withMaterializedOutcome(record: BgNotifyRecord): BgNotifyRecord {
+  return record.status === "closed"
+    ? { ...record, outcome: record.outcome ?? deriveOutcome(record.closedReason, record.error) }
+    : record;
+}
+
+/**
+ * sync 批通知文案（U3 批形态 + U4 两段式预算截断）。
+ *
+ * 形态（设计 §3.1.1 交互样例）：批头行 `Subagent batch completed: N finished,
+ * M failed, K cancelled.` + 各成员条目（buildLlmContent 同语义）以 "\n\n---\n\"
+ * \n" join（分隔符对齐 ledger mergeItems / 内核合批——TUI/LLM 两消费方同构）。
+ * 批头计数口径 = 成员 outcome 三态（completed→finished）；closed 成员 outcome 缺省
+ * 时按单一权威 deriveOutcome 兑底（与 notify() 投影边界同款，幂等无害）。
+ *
+ * [U4 预算截断] 仅对展示结果正文的条目（closed+completed / running）生效；
+ * failed/cancelled 条目无 result 可取回（指针无意义）不计正文预算、原样输出。
+ * totalChars 口径（§3.1.2）：仅计条目正文（截断后）之和，批头/头行/指针行/
+ * 分隔符等包装开销为有界常量不入预算。未触预算时输出与 U3 基线逐字节一致。
+ * budget 缺省 = 设计默认值；config 热读接线由 flush 调用方传入。
+ */
+export function buildBatchLlmContent(
+  records: readonly BgNotifyRecord[],
+  budget: BatchBudgetParams = DEFAULT_BATCH_BUDGET,
+): string {
+  // 入口一次物化（S1，code-simplify）：closed 成员 outcome 兑底仅此一处，bodies/计数/
+  // 条目全部读物化结果——「单一权威 deriveOutcome」从注释承诺变构造事实。幂等纯函数，
+  // 与原四处各自推导逐字节等价；running 原样透传零拷贝。
+  const mat = records.map(withMaterializedOutcome);
+  let finished = 0;
+  let failed = 0;
+  let cancelled = 0;
+  // 各条目参与预算的正文（§3.1.2 口径）；null = 该条目不展示 result 正文。
+  const bodies = mat.map((record): string | null => {
+    if (record.status === "closed" && record.outcome !== "completed") return null;
+    return record.result ?? "(empty)";
+  });
+  const plan = computeBatchBudget(
+    bodies.map((body) => body?.length ?? 0),
+    budget.perItemChars,
+    budget.totalChars,
+  );
+  const items = mat.map((record, i) => {
+    if (record.status === "closed") {
+      const outcome = record.outcome;
+      if (outcome === "completed") finished += 1;
+      else if (outcome === "failed") failed += 1;
+      else if (outcome === "cancelled") cancelled += 1;
+    }
+    const body = bodies[i];
+    if (body === null || body.length <= plan.effectivePerItem) {
+      // 未触预算（含 failed/cancelled 条目）：U3 基线字节不变。
+      return buildLlmContent(record);
+    }
+    // 截断：正文保留前 limit 字符 + 省略号，尾接指针行（kept=0 纯清单时省略号一并省略）。
+    const kept = body.slice(0, plan.effectivePerItem);
+    const truncated = buildLlmContent({ ...record, result: plan.listOnly ? "" : `${kept}…` });
+    // 纯清单时 result 置空会在 buildLlmContent 内残留头行尾换行（"Result:\n" + ""），
+    // 收掉该空行让条目严格为「头行 + 指针行」两行形态（设计 §3.1.2 纯清单退化）。
+    const stripped = plan.listOnly ? truncated.replace(/\n$/, "") : truncated;
+    return `${stripped}\n${buildTruncationPointer(record.id, kept.length, body.length, plan.effectivePerItem)}`;
+  });
+  const header = `Subagent batch completed: ${finished} finished, ${failed} failed, ${cancelled} cancelled.`;
+  return [header, ...items].join("\n\n---\n\n");
+}
+
 /**
  * 将 BgNotifyRecord 格式化为 LLM 可读的 notification content。
  *
@@ -164,6 +331,13 @@ function buildLlmContent(record: BgNotifyRecord): string {
 export interface BgNotifier {
   /** 入队一条完成通知（去重 + 合批窗口合并）。dispose 后短路。 */
   notify(record: BgNotifyRecord): void;
+  /**
+   * sync 批通知（subagent-sync-collect U3）：成员集 → 单条批投递。幂等键
+   * `sync-batch:<sha1(sorted ids)>`，走与 notify 同一写账→settled 边沿投递链（单
+   * entry）。返回 false = 幂等拒绝（同成员集批已在账/已销账）或空批 / dispose 后——
+   * 调用方（service flushBatch 接线）据此决定 batchFinalized 落标。
+   */
+  notifyBatch(records: readonly BgNotifyRecord[], budget?: BatchBudgetParams): boolean;
   /** 立即 flush（session_shutdown 调用，防丢失）。 */
   flushPendingNotifications(): void;
   /** session 结束：清队列，dispose 内核 handle。 */
@@ -292,6 +466,37 @@ export function createNotifier(host: NotifierHost): BgNotifier {
   };
   let handle: DeliveryHandle = createHandle();
 
+  /** 四步投递链尾部共用段（S2，code-simplify）：notify 单条与 notifyBatch 逐行同构
+   *  的收尾——原两份手写拷贝使注释宣称的「同一四步链」无结构强制，现单点实现。
+   *  ledger 在 → ①写账（拒绝 = false，幂等去重：同 notifyId 已在账/已销账）→
+   *  ②attemptDeliver（settled 边沿 + isIdle 二次复查，③④销账/重放在 ledger 内）；
+   *  ledger 缺（旧装配 / 部分测试，含 jiti 单例分裂的失效形态）→ 内核路径降级 +
+   *  降级留痕 warn（C-ext-06 配套，不改变向后兼容行为）。返回 false 仅 notifyBatch
+   *  消费（调用方跳过落标）；notify 忽略（fire-and-forget）。闭包读 let handle：
+   *  revive 重建后自然指向新 handle。 */
+  function deliverViaLedgerOrKernel(notifyId: string, content: string, details: object): boolean {
+    const ledger = getBoundNotifyLedger();
+    if (ledger) {
+      if (!ledger.record(notifyId, content, details)) return false;
+      ledger.attemptDeliver();
+      return true;
+    }
+    notifyLogger.warn("notify ledger not bound, falling back to delivery kernel path (at-most-once)", {
+      notifyId,
+    });
+    handle.send({
+      payload: {
+        kind: "custom",
+        customType: NOTIFY_CUSTOM_TYPE,
+        content,
+        display: true,
+        details,
+      },
+      dedupeKey: notifyId,
+    });
+    return true;
+  }
+
   return {
     notify(record: BgNotifyRecord): void {
       if (disposed) return;
@@ -314,31 +519,35 @@ export function createNotifier(host: NotifierHost): BgNotifier {
       // 投递尝试）→ ②courier 边沿投递（settled 边沿 + 120s 看门狗 + isIdle 二次
       // 复查）→ ③回执销账 / ④重放幂等均在 ledger 内。record 返回 false = 同
       // notifyId 已在账或已销账（幂等去重，含重启恢复后的已送达账号零重发）。
-      const ledger = getBoundNotifyLedger();
-      if (ledger) {
-        if (!ledger.record(notifyId, content, payload)) return;
-        ledger.attemptDeliver();
-        return;
-      }
+      // 无 ledger 装配时内核路径降级 + 降级留痕（C-ext-06 配套，见 helper 注释）。
+      // 单条通知为 fire-and-forget，返回值忽略。
+      deliverViaLedgerOrKernel(notifyId, content, payload);
+    },
 
-      // 无 ledger 装配（旧装配 / 部分测试）：内核路径——合批窗口 / settled 边沿 /
-      // dedupe（按 notifyId，key 规则与旧 dedupeKey 一致：id 或 id:round）不变。
-      // [C-ext-06 配套] 降级留痕：bind 缺失（含 jiti 单例分裂致跨模块读不到绑定的
-      // 失效形态）本是无声分岔，U2 at-least-once 在此退化为内核路径——warn 一条
-      // 供诊断检索，不改变向后兼容行为。
-      notifyLogger.warn("notify ledger not bound, falling back to delivery kernel path (at-most-once)", {
-        notifyId,
-      });
-      handle.send({
-        payload: {
-          kind: "custom",
-          customType: NOTIFY_CUSTOM_TYPE,
-          content,
-          display: true,
-          details: payload,
-        },
-        dedupeKey: notifyId,
-      });
+    notifyBatch(records: readonly BgNotifyRecord[], budget?: BatchBudgetParams): boolean {
+      if (disposed || records.length === 0) return false;
+
+      // 投影边界物化（与 notify 同款）：closed 成员补 outcome——批头计数与成员条目
+      // 单一来源。消源自入参浅拷贝，不改写协调器缓冲持有的快照对象。
+      const payloads = records.map((record) =>
+        record.status === "closed"
+          ? { ...record, outcome: record.outcome ?? deriveOutcome(record.closedReason, record.error) }
+          : { ...record },
+      );
+      const batchNotifyId = buildBatchNotifyId(payloads.map((p) => p.id));
+      // budget（可选）= service flushBatch/E1 补发接线传入的 config 热读值（U4 deviation #8
+      // 由 U5 接线）；undefined → buildBatchLlmContent 参数缺省 = 设计默认值（4000/24000）。
+      // 账本重放走写入时已定格的 content，预算在写账时刻生效（“flush 时热读”语义）。
+      const content = buildBatchLlmContent(payloads, budget);
+      // details 形态 = ledger mergeItems 批量分支（{batch:true, items}——bg-notify-render
+      // extractBatch 已支持，⛔1 核对）+ 顶层 notifyId：collectDeliveredNotifyIds 的回执
+      // 匹配键认 details.notifyId / details.items[].notifyId，批身份键必须顶层可达，
+      // 否则批 entry 永不销账、重投至放弃。顶层 notifyId 键对 extractBatch 透明（多键无感）。
+      const details = { batch: true as const, notifyId: batchNotifyId, items: payloads };
+
+      // 与 notify 同一四步链（deliverViaLedgerOrKernel，S2 提取）：返回 false = 同成
+      // 员集批已在账（E1 重建重发 / 重复 flush）→ 调用方跳过落标。
+      return deliverViaLedgerOrKernel(batchNotifyId, content, details);
     },
 
     flushPendingNotifications(): void {

package/src/execution/notify-host.ts

@@ -8,7 +8,7 @@ import { displayAgentName } from "../shared/agent-ref.ts";
 import { snapshot } from "./execution-record.ts";
 import { hasIdleTimer } from "./lifecycle-manager.ts";
 import { hasLiveProcessHandle, isIdle, isResumable } from "./lifecycle-predicates.ts";
-import type { BgNotifier, NotifierHost } from "./notifier.ts";
+import type { BgNotifier, BatchBudgetParams, NotifierHost } from "./notifier.ts";
 import { createNotifier } from "./notifier.ts";
 import type { BgNotifyRecord } from "./notifier.ts";
 import type { ExecutionRecord, RecordSnapshot } from "./types.ts";
@@ -50,6 +50,14 @@ export interface NotifyHost {
   emitPendingRegister(id: string, name?: string): void;
   /** pending-notifications 注销（原模块函数 emitPendingUnregister）。 */
   emitPendingUnregister(id: string, reason: string): void;
+  /** [sync-collect U2 合并] record → BgNotifyRecord 映射——collectCoordinator 的
+   *  toNotifyRecord/notifyAsync 依赖注入消费（守卫放行逻辑单一权威在本文件）。 */
+  toNotifyRecord(record: ExecutionRecord): BgNotifyRecord | undefined;
+  /** [sync-collect 合并] 单条直发——collectCoordinator notifyAsync 与 E9 dispose
+   *  转换路径消费（已越过 toNotifyRecord 守卫的成品通知）。 */
+  notify(record: BgNotifyRecord): void;
+  /** [sync-collect 合并] sync 批投递——collectCoordinator flushBatch 与 E1 补发消费。 */
+  notifyBatch(records: readonly BgNotifyRecord[], budget?: BatchBudgetParams): boolean;
   /** dispose 的逆操作（initSession 复活，原 notifier.revive 委托）。 */
   revive(): void;
   /** dispose 前冲刷待发通知（原 notifier.flushPendingNotifications 委托）。 */
@@ -197,6 +205,18 @@ export function createNotifyHost(deps: NotifyHostDeps): NotifyHost {
       emitPendingUnregister(deps.getPi(), id, reason);
     },
 
+    toNotifyRecord(record: ExecutionRecord): BgNotifyRecord | undefined {
+      return toNotifyRecord(record);
+    },
+
+    notify(record: BgNotifyRecord): void {
+      notifier.notify(record);
+    },
+
+    notifyBatch(records: readonly BgNotifyRecord[], budget?: BatchBudgetParams): boolean {
+      return notifier.notifyBatch(records, budget);
+    },
+
     revive(): void {
       notifier.revive();
     },

package/src/execution/record-entry.ts

@@ -97,6 +97,18 @@ export interface SubagentRecordEntryData {
    * 透传不枚举内部键（zcode = { sessionId, dbPath }）；缺省 = pi（存量 entry 零迁移）。
    */
   engineHandle?: { sessionRef: Record<string, string>; 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 源）。
@@ -134,5 +146,9 @@ export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEnt
     engine: record.engine,
     engineFallback: record.engineFallback,
     engineHandle: record.engineHandle,
+    // 同步收集两字段（U1 foundation）：undefined 经 JSON.stringify 自然缺省，
+    // 旧记录/旧 entry 序列化产物字节不变（零迁移）。
+    collectMode: record.collectMode,
+    batchFinalized: record.batchFinalized,
   };
 }

package/src/execution/record-store.ts

@@ -259,40 +259,103 @@ function collectLastRecordEntries(content: string): Map<string, Record<string, u
   return lastById;
 }
 
+/** entry data 字段的安全 string 读取（非 string → undefined）。 */
+function entryStr(d: Record<string, unknown>, k: string): string | undefined {
+  return typeof d[k] === "string" ? (d[k] as string) : undefined;
+}
+
+/** entry data 字段的安全 number 读取（非 number → undefined）。 */
+function entryNum(d: Record<string, unknown>, k: string): number | undefined {
+  return typeof d[k] === "number" ? (d[k] as number) : undefined;
+}
+
+/** 终态域投影：status 只认 "closed" 字面量（其余含缺省 → "running"，旧调用方行为不变）；
+ *  closedReason 经枚举守卫（非法/缺省 → undefined）。 */
+function readEntryTerminalFields(
+  d: Record<string, unknown>,
+): Pick<SubagentRecord, "status" | "closedReason"> {
+  const closedReason = entryStr(d, "closedReason");
+  return {
+    status: d.status === "closed" ? "closed" : "running",
+    closedReason: isValidClosedReason(closedReason) ? closedReason : undefined,
+  };
+}
+
+/** 批收集域投影（U5 E1）：仅显式字面量收敛，缺省 undefined（JSON 序列化自然缺省）。 */
+function readEntryBatchFields(
+  d: Record<string, unknown>,
+): Pick<SubagentRecord, "collectMode" | "batchFinalized" | "resumable"> {
+  return {
+    collectMode: d.collectMode === "sync" ? "sync" : undefined,
+    batchFinalized: d.batchFinalized === true ? true : undefined,
+    resumable: d.resumable === true ? true : undefined,
+  };
+}
+
+/** engine 域投影：engineFallback/engineHandle 经运行时 guard（未知 JSON 不裸收）。 */
+function readEntryEngineFields(
+  d: Record<string, unknown>,
+): Pick<SubagentRecord, "engine" | "engineFallback" | "engineHandle"> {
+  return {
+    engine: entryStr(d, "engine"),
+    engineFallback: isEngineFallbackShape(d.engineFallback) ? d.engineFallback : undefined,
+    engineHandle: isEngineHandleShape(d.engineHandle) ? d.engineHandle : undefined,
+  };
+}
+
 /** entry data 即 SubagentRecord v1 快照——带运行时 guard 重建（taste/no-unsafe-cast）。
- *  损坏 entry（agent/task/startedAt 任一缺失）返回 null，由调用方跳过。 */
+ *  损坏 entry（agent/task/startedAt 任一缺失）返回 null，由调用方跳过。
+ *  [U5 E1] 投影白名单扩展（设计 §3.1.3「标记读取通路」）：collectMode/batchFinalized
+ *  + 终态五字段 status/endedAt/closedReason/result/error——原实现硬编码
+ *  status:"running" 且不投影终态，E1 重建成员恒被视为 running，「全员终态→补发」
+ *  判定永假、补发内容缺失，整条补发路径成死代码。status 守卫只认 "closed" 字面量
+ *  （其余含缺省 → "running"，旧调用方 recoverEntryOnlyOrphans 行为不变——其候选
+ *  守卫已滤非 running 末条）；closedReason 经 isValidClosedReason 枚举守卫。
+ *  [v2 D3] 再补 resumable/sessionFile 两投影：成功成员崩溃时末条恒为轮终
+ *  running+resumable entry（SP-5 有意语义），不投影 resumable 则 E1 无法与协调器
+ *  hasRunningSync 同构豁免（§2.3 断链 3）；sessionFile 原硬编码 undefined，导致
+ *  E1 落标路径重建快照丢失反查索引锚（断链 1 前置依赖）。recoverEntryOnlyOrphans
+ *  的候选判定（isEntryOrphanCandidate）只认 status==="running"，两新字段不参与
+ *  判定（P-rebuild 探针守卫面）。
+ *  [E1 恢复批语义修复] 再补 patchFile 投影：entry data 携带该字段
+ *  （toSubagentRecordEntry 落盘含 patchFile）但原投影丢弃 → E1 补发记录丢失
+ *  worktree patch 的 git-apply 回收指针（正常 flush 路径经 toNotifyRecord 特意
+ *  携带，notify-host.ts patchFile 透传）。undefined 经 JSON.stringify 自然缺省，
+ *  无 patchFile 的存量 entry 序列化字节不变（落标出口经 toSubagentRecordEntry
+ *  按名重投影，重建对象字段顺序不影响序列化字节形态）。
+ *  字段顺序 = 对象字面量原序（终态/批收集/engine 域以 spread 在原位置展开），
+ *  entry 序列化字节形态不变。 */
 function rebuildEntryRecord(id: string, d: Record<string, unknown>): SubagentRecord | null {
-  const str = (k: string): string | undefined => (typeof d[k] === "string" ? (d[k] as string) : undefined);
-  const num = (k: string): number | undefined => (typeof d[k] === "number" ? (d[k] as number) : undefined);
-  const agent = str("agent");
-  const task = str("task");
-  const startedAt = num("startedAt");
+  const agent = entryStr(d, "agent");
+  const task = entryStr(d, "task");
+  const startedAt = entryNum(d, "startedAt");
   if (agent === undefined || task === undefined || startedAt === undefined) return null; // 损坏 entry：跳过
   return {
     id,
     agent,
     task,
-    slug: str("slug") ?? "",
-    status: "running",
+    slug: entryStr(d, "slug") ?? "",
+    ...readEntryTerminalFields(d),
     mode: "background",
     startedAt,
-    rootSessionId: str("rootSessionId"),
-    parentRecordId: str("parentRecordId"),
-    depth: num("depth") ?? 0,
-    endedAt: undefined,
-    turns: num("turns") ?? 0,
-    totalTokens: num("totalTokens") ?? 0,
-    model: str("model") ?? "",
-    thinkingLevel: str("thinkingLevel"),
+    rootSessionId: entryStr(d, "rootSessionId"),
+    parentRecordId: entryStr(d, "parentRecordId"),
+    depth: entryNum(d, "depth") ?? 0,
+    endedAt: entryNum(d, "endedAt"),
+    turns: entryNum(d, "turns") ?? 0,
+    totalTokens: entryNum(d, "totalTokens") ?? 0,
+    model: entryStr(d, "model") ?? "",
+    thinkingLevel: entryStr(d, "thinkingLevel"),
     eventLog: [],
     displayItems: [],
-    sessionFile: undefined,
+    result: entryStr(d, "result"),
+    error: entryStr(d, "error"),
+    sessionFile: entryStr(d, "sessionFile"),
+    patchFile: entryStr(d, "patchFile"),
     chatMode: d.chatMode === true,
-    round: num("round"),
-    engine: str("engine"),
-    engineFallback:
-      isEngineFallbackShape(d.engineFallback) ? d.engineFallback : undefined,
-    engineHandle: isEngineHandleShape(d.engineHandle) ? d.engineHandle : undefined,
+    round: entryNum(d, "round"),
+    ...readEntryEngineFields(d),
+    ...readEntryBatchFields(d),
   };
 }
 
@@ -645,35 +708,53 @@ export 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 {
+    const lastById = new Map(this.scanLastRecordEntries(mainSessionFile).map((r) => [r.id, r]));
     for (const rec of this.reconstructAll(rootSessionFilter)) {
       // 分支 4 命中集 = running 且无活进程实例（分支 3 带 externalInstance，分支 1/2 已 closed）。
       if (rec.status !== "running" || rec.externalInstance !== undefined) continue;
       if (this.orphanJudged.has(rec.id)) continue;
       this.orphanJudged.add(rec.id);
-      this.finalizeOrphanRecord(rec);
+      this.finalizeOrphanRecord(rec, lastById.get(rec.id));
     }
   }
 
   /**
    * 单孤儿 record 的终态判定与落 entry（residual-fixes §5.2 三判据 + chat 分流）。
    * 防重锚（orphanJudged 标记）已由调用方完成。
+   *
+   * [v2 D3] 覆写前 merge（lastEntry = 主 session 同 id 末条 entry 重建，调用方构建）：
+   * 覆写是状态迁移不是信息重建，迁移不应丢末条既有信息。三个落 entry 分支（chatMode
+   * 分流 / IO 保守 / 终态覆写）统一基于 merge 后的 rec，同款口径。
    */
-  private finalizeOrphanRecord(rec: SubagentRecord): void {
-    if (rec.chatMode === true) {
+  private finalizeOrphanRecord(rec: SubagentRecord, lastEntry?: SubagentRecord): void {
+    // 仅补 undefined/空值字段、不覆盖已有值——覆写自带的 status/closedReason/endedAt/
+    // error 不在 merge 字段集，天然不受影响。批域字段（collectMode/batchFinalized）对
+    // 非 sync 成员恒 no-op（末条 entry collectMode undefined → 无值可补）；result/model
+    // 的修补对 async/chat 成员同样生效——拉齐 light 重建丢 result/model 与 full 重建的
+    // 既有形态不一致（v2 D3 影响面诚实口径），不触碰任何通知文案（golden 不锁 entry 字节）。
+    const rec0 = lastEntry === undefined ? rec : RecordStore.mergeOrphanLastEntry(rec, lastEntry);
+    if (rec0.chatMode === true) {
       // chat 会话跨重启等续聊：保留 running（可续聊），仅落执行态信号。
-      this.reportSubagentRecord({ ...rec, resumable: true });
+      this.reportSubagentRecord({ ...rec0, resumable: true });
       return;
     }
-    const sessionFile = rec.sessionFile;
+    const sessionFile = rec0.sessionFile;
     if (sessionFile === undefined) return; // 无子文件锚（目录扫描源不可达，防御）
     const lastLine = readLastJsonlLine(sessionFile);
     if (!lastLine.ok) {
       // IO 错误可能暂时——判终态不可逆，保守落 resumable 等重开重判。
-      this.reportSubagentRecord({ ...rec, resumable: true });
+      this.reportSubagentRecord({ ...rec0, resumable: true });
       return;
     }
     let parseOk = false;
@@ -689,7 +770,7 @@ export class RecordStore {
     // 把正常完成的记录误标成断联。
     writeFinalized(sessionFile, "gc");
     this.reportSubagentRecord({
-      ...rec,
+      ...rec0,
       status: "closed",
       closedReason: "gc",
       endedAt: Date.now(),
@@ -697,6 +778,25 @@ export class RecordStore {
     });
   }
 
+  /** [v2 D3] 孤儿覆写 merge 字段集：末条 entry 的批域标记 + 轮终正文/模型，仅补 rec 侧
+   *  undefined/空值（model 的空值形态是 ""——light 重建无 model_change entry 时起步
+   *  空串），不覆盖已有值。merge 后写 entry 经 reportSubagentRecord →
+   *  toSubagentRecordEntry 序列化，undefined 字段自然缺省（不引入显式 null）。 */
+  private static mergeOrphanLastEntry(rec: SubagentRecord, last: SubagentRecord): SubagentRecord {
+    const pickStr = (cur: string | undefined, src: string | undefined): string | undefined =>
+      cur !== undefined && cur !== "" ? cur : src;
+    return {
+      ...rec,
+      collectMode: rec.collectMode ?? last.collectMode,
+      batchFinalized: rec.batchFinalized ?? last.batchFinalized,
+      result: pickStr(rec.result, last.result),
+      // 类型收尾：两侧实参恒 string（rec.model 类型非可选；last.model 重建投影自带
+      // `?? ""`），pickStr 签名宽返回 string|undefined —— `?? ""` 运行时不可达，
+      // 仅满足 model 非可选类型，空串回退语义不变（cur 空 → src，src 也空 → ""）。
+      model: pickStr(rec.model, last.model) ?? "",
+    };
+  }
+
   /**
    * [E2E 实测缺口] entry-born 孤儿恢复：register entry 已落主 session、但子 session 文件
    * 从未创建（父进程死在 spawn 窗口期——register 写点与子进程首笔写入之间的窗口；外部
@@ -762,6 +862,32 @@ export class RecordStore {
     });
   }
 
+  /**
+   * [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[] {
+    if (mainSessionFile === undefined) return [];
+    let content: string;
+    try {
+      content = fs.readFileSync(mainSessionFile, "utf-8");
+    } catch {
+      return []; // 与 recoverEntryOnlyOrphans 同判：best-effort 恢复，不可读静默跳过
+    }
+    const out: SubagentRecord[] = [];
+    for (const [id, d] of collectLastRecordEntries(content)) {
+      const rec = rebuildEntryRecord(id, d);
+      if (rec !== null) out.push(rec);
+    }
+    return out;
+  }
+
   /** 订阅变更。返回取消订阅函数。 */
   onChange(listener: ChangeListener): () => void {
     this.listeners.add(listener);
@@ -1320,6 +1446,11 @@ export class RecordStore {
       engineFallback: r.engineFallback,
       // U2：engineHandle 经 entry 持久化（register/archive 双写点均经本投影），无则 undefined 自然省略
       engineHandle: r.engineHandle,
+      // [U5 修复 U2 披露的投影缺口] 同步收集两字段随本投影持久化（register entry /
+      // archive entry 双写点）——原缺失时闭合判定 flushBatch 重建、E1 重建扫描等消费方
+      // 读不到原始值。undefined 经 JSON.stringify 自然缺省，旧 entry 零迁移。
+      collectMode: r.collectMode,
+      batchFinalized: r.batchFinalized,
     };
   }
 }