@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/record-store.ts

@@ -159,6 +159,21 @@ interface NegativeFileEntry {
 /** fileCache 值类型：正常条目或负缓存条目。 */
 type FileCacheValue = FileCacheEntry | NegativeFileEntry;
 
+/** scanFile 单文件本轮 stat 戳集合（jsonl + 3 sidecar）。 */
+interface FileStamps {
+  jsonl: Stamp;
+  cancelled: Stamp | null;
+  finalized: Stamp | null;
+  alive: Stamp | null;
+}
+
+/** sidecar payload 读取结果（索引命中与探测重建两分支共享的读点）。 */
+interface SidecarPayloads {
+  tomb: CancelledTombstone | undefined;
+  aliveData: AliveMarker | undefined;
+  finalReason: string | undefined;
+}
+
 /** 孤儿判定的末行读取初始窗口（常规 entry 远小于此，避免全文件读）。 */
 // eslint-disable-next-line no-magic-numbers -- 64KB = 64 * 1024 bytes 字节换算常数
 const LAST_LINE_WINDOW_BYTES = 64 * 1024;
@@ -244,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),
   };
 }
 
@@ -335,6 +413,41 @@ function sameNullableStamp(a: Stamp | null, b: Stamp | null): boolean {
   return sameStamp(a, b);
 }
 
+/** 缓存条目与本轮 stat 戳全同（jsonl + 3 sidecar，null 语义对齐）→ 零读取复用。 */
+function isFreshCache(cached: FileCacheValue, stamps: FileStamps): boolean {
+  return (
+    sameStamp(cached.jsonl, stamps.jsonl) &&
+    sameNullableStamp(cached.cancelled, stamps.cancelled) &&
+    sameNullableStamp(cached.finalized, stamps.finalized) &&
+    sameNullableStamp(cached.alive, stamps.alive)
+  );
+}
+
+/**
+ * identity 三级定位——头部 64KB（首轮会话，~34%）→ 尾部 64KB（续聊场景最后一轮
+ * session_start 追加，~65%）→ 全文 fallback（~0.2%）。均不解析 message entries。
+ * size ≤ 头部读取上限时 head 读到的即全文，tail/anywhere 只会重复读同一份内容——
+ * 直接判负（head miss = 全文无 identity），省去同内容两连读。
+ */
+function detectIdentity(file: string, size: number): IdentityHeaderRecon | undefined {
+  return size <= IDENTITY_HEAD_BYTES
+    ? readIdentityHeader(file)
+    : readIdentityHeader(file) ?? readIdentityTail(file) ?? readIdentityAnywhere(file);
+}
+
+/**
+ * sidecar payload 读取（读顺序：tombstone → alive marker → finalized reason）。
+ * tombstone/alive 是活态数据，调用方沿用每轮重读语义；finalized reason 静态数据
+ * 仅在 sidecar 存在时读一次（文件小，成本可忽略）。
+ */
+function readSidecarPayloads(file: string, stamps: FileStamps): SidecarPayloads {
+  return {
+    tomb: stamps.cancelled !== null ? readCancelledTombstone(file) : undefined,
+    aliveData: stamps.alive !== null ? readAliveMarker(file) : undefined,
+    finalReason: stamps.finalized !== null ? readFinalizedReason(file) : undefined,
+  };
+}
+
 /** Pi ExtensionAPI 的最小子集（仅 collectRecords 跳过损坏 manifest 时上报用）。
  *  解构为局部类型，避免与 subagent-service 的 PiLike 循环依赖。 */
 export type RecordStorePi = {
@@ -595,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;
@@ -639,7 +770,7 @@ export class RecordStore {
     // 把正常完成的记录误标成断联。
     writeFinalized(sessionFile, "gc");
     this.reportSubagentRecord({
-      ...rec,
+      ...rec0,
       status: "closed",
       closedReason: "gc",
       endedAt: Date.now(),
@@ -647,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 写点与子进程首笔写入之间的窗口；外部
@@ -712,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);
@@ -865,18 +1041,15 @@ export class RecordStore {
       this.fileCache.delete(file);
       return null;
     }
-    const cancelled = statStamp(`${file}.cancelled`);
-    const finalized = statStamp(`${file}.finalized`);
-    const alive = statStamp(`${file}.alive`);
+    const stamps: FileStamps = {
+      jsonl,
+      cancelled: statStamp(`${file}.cancelled`),
+      finalized: statStamp(`${file}.finalized`),
+      alive: statStamp(`${file}.alive`),
+    };
 
     const cached = this.fileCache.get(file);
-    if (
-      cached !== undefined &&
-      sameStamp(cached.jsonl, jsonl) &&
-      sameNullableStamp(cached.cancelled, cancelled) &&
-      sameNullableStamp(cached.finalized, finalized) &&
-      sameNullableStamp(cached.alive, alive)
-    ) {
+    if (cached !== undefined && isFreshCache(cached, stamps)) {
       if (cached.negative) return null; // 负缓存命中：确认无 identity，零读取跳过
       // pid 探活结果不落盘（进程死亡无 IO）——分支 3 的 running 项每扫重查，
       // 保留原语义（旧实现每次 collectRecords 都重新 isProcessAlive）。
@@ -885,83 +1058,54 @@ export class RecordStore {
     }
 
     // [perf L-1] 磁盘索引查询（首扫惰性装载，miss/空索引时 get 恒 undefined = 无索引）。
-    // 条目戳匹配 jsonl 当前 stat → 零内容读取构造缓存条目。sidecar payload（tombstone/
-    // alive）是活态数据，沿用探测分支的每轮重读语义；finalized reason 静态数据仅在
-    // sidecar 存在时读一次（文件小，成本可忽略）。
-    if (this.indexEntries !== null) {
-      const hit = this.indexEntries.get(path.basename(file));
-      if (hit !== undefined && hit.mtimeMs === jsonl.mtimeMs && hit.size === jsonl.size) {
-        if (hit.negative === true) {
-          // 负条目命中：「确认无 identity」跨实例持久，零探测跳过（与下方负缓存同款形态）。
-          this.fileCache.set(file, { negative: true, jsonl, cancelled, finalized, alive });
-          return null;
-        }
-        const tomb = cancelled !== null ? readCancelledTombstone(file) : undefined;
-        const aliveData = alive !== null ? readAliveMarker(file) : undefined;
-        const finalReason = finalized !== null ? readFinalizedReason(file) : undefined;
-        const entry: FileCacheEntry = {
-          light: RecordStore.buildRecord(
-            { ...hit, forkDepth: undefined, sessionFile: file },
-            { tomb, finalized: finalized !== null, finalizedReason: finalReason, alive: aliveData, jsonlMtimeMs: jsonl.mtimeMs, now },
-          ),
-          full: undefined,
-          jsonl,
-          cancelled,
-          finalized,
-          alive,
-          tomb,
-          aliveData,
-          finalReason,
-        };
-        this.fileCache.set(file, entry);
-        this.idToFile.set(hit.id, file);
-        return entry;
-      }
-    }
+    // 条目戳匹配 jsonl 当前 stat → 零内容读取构造缓存条目。undefined = 未命中
+    // （落到下方探测），null = 负条目命中（零探测跳过）。
+    const fromIndex = this.buildEntryFromIndex(file, stamps, now);
+    if (fromIndex !== undefined) return fromIndex;
 
     // [perf L-1] 索引 miss/戳不匹配落到原三级探测：本轮探测结果必须进索引（含负探测）。
     // 覆盖两种形态：首扫（映像已装载但 miss/不匹配）与后续轮次（映像已释放，凡进重建分支必是戳变化）。
     this.indexDirty = true;
 
-    // 重建：identity 三级定位——头部 64KB（首轮会话，~34%）→ 尾部 64KB（续聊场景
-    // 最后一轮 session_start 追加，~65%）→ 全文 fallback（~0.2%）。均不解析 message entries。
-    // size ≤ 头部读取上限时 head 读到的即全文，tail/anywhere 只会重复读同一份内容——
-    // 直接判负（head miss = 全文无 identity），省去同内容两连读。
-    const header =
-      jsonl.size <= IDENTITY_HEAD_BYTES
-        ? readIdentityHeader(file)
-        : readIdentityHeader(file) ?? readIdentityTail(file) ?? readIdentityAnywhere(file);
+    const header = detectIdentity(file, jsonl.size);
     if (!header) {
       // 负缓存：确认无 identity。后续扫描 stat 命中直接跳过；戳变化（文件补写）自动重试。
-      this.fileCache.set(file, { negative: true, jsonl, cancelled, finalized, alive });
+      this.fileCache.set(file, { negative: true, ...stamps });
       return null;
     }
-    const tomb = cancelled !== null ? readCancelledTombstone(file) : undefined;
-    const aliveData = alive !== null ? readAliveMarker(file) : undefined;
-    const finalReason = finalized !== null ? readFinalizedReason(file) : undefined;
-    const entry: FileCacheEntry = {
-      light: RecordStore.buildRecord(header, {
-        tomb,
-        finalized: finalized !== null,
-        finalizedReason: finalReason,
-        alive: aliveData,
-        jsonlMtimeMs: jsonl.mtimeMs,
-        now,
-      }),
-      full: undefined,
-      jsonl,
-      cancelled,
-      finalized,
-      alive,
-      tomb,
-      aliveData,
-      finalReason,
-    };
+    const payloads = readSidecarPayloads(file, stamps);
+    const entry = RecordStore.buildFileCacheEntry(header, file, stamps, payloads, now);
     this.fileCache.set(file, entry);
     this.idToFile.set(header.id, file);
     return entry;
   }
 
+  /**
+   * [perf L-1] 磁盘索引查询（首扫惰性装载，miss/空索引时 get 恒 undefined = 无索引）。
+   * 条目戳匹配 jsonl 当前 stat → 零内容读取构造缓存条目。sidecar payload（tombstone/
+   * alive）是活态数据，沿用探测分支的每轮重读语义；finalized reason 静态数据仅在
+   * sidecar 存在时读一次（文件小，成本可忽略）。
+   *
+   * 返回 undefined = 索引未命中/戳不匹配（调用方落到原三级探测）；null = 负条目命中
+   * （「确认无 identity」跨实例持久，零探测跳过，与内存负缓存同款形态）。
+   */
+  private buildEntryFromIndex(file: string, stamps: FileStamps, now: number): FileCacheEntry | null | undefined {
+    if (this.indexEntries === null) return undefined;
+    const hit = this.indexEntries.get(path.basename(file));
+    if (hit === undefined || hit.mtimeMs !== stamps.jsonl.mtimeMs || hit.size !== stamps.jsonl.size) {
+      return undefined;
+    }
+    if (hit.negative === true) {
+      this.fileCache.set(file, { negative: true, ...stamps });
+      return null;
+    }
+    const payloads = readSidecarPayloads(file, stamps);
+    const entry = RecordStore.buildFileCacheEntry({ ...hit, forkDepth: undefined, sessionFile: file }, file, stamps, payloads, now);
+    this.fileCache.set(file, entry);
+    this.idToFile.set(hit.id, file);
+    return entry;
+  }
+
   /**
    * [perf L-1] 扫描尾索引落盘（节流）：释放映像 → dirty/高版本/60s 节流窗三重门 →
    * fire-and-forget saveIndex（fileCache 全量投影）。写决策与发起在同步栈（collectRecords
@@ -1089,6 +1233,34 @@ export class RecordStore {
     entry.light.externalInstance = live ? marker : undefined;
   }
 
+  /** identity 基底 + sidecar 状态矩阵 → 缓存条目（索引命中与探测重建两分支的公共装配点）。 */
+  private static buildFileCacheEntry(
+    base: IdentityHeaderRecon,
+    file: string,
+    stamps: FileStamps,
+    payloads: SidecarPayloads,
+    now: number,
+  ): FileCacheEntry {
+    return {
+      light: RecordStore.buildRecord(base, {
+        tomb: payloads.tomb,
+        finalized: stamps.finalized !== null,
+        finalizedReason: payloads.finalReason,
+        alive: payloads.aliveData,
+        jsonlMtimeMs: stamps.jsonl.mtimeMs,
+        now,
+      }),
+      full: undefined,
+      jsonl: stamps.jsonl,
+      cancelled: stamps.cancelled,
+      finalized: stamps.finalized,
+      alive: stamps.alive,
+      tomb: payloads.tomb,
+      aliveData: payloads.aliveData,
+      finalReason: payloads.finalReason,
+    };
+  }
+
   /** identity 基底（头部 light 或全量 recon）+ 四分支 sidecar 状态矩阵 → SubagentRecord。 */
   private static buildRecord(
     base: IdentityHeaderRecon | ReconstructedRecord,
@@ -1274,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,
     };
   }
 }

package/src/execution/round-settlement.ts

@@ -0,0 +1,93 @@
+// [D4-② 轮次结算职责轴] chatMode 轮次完成的业务闭包（原 SubagentService
+// buildSessionRunnerContext 内的 onRoundSettled 回调 ~95 行区域）整体搬移至此
+// （行为逐字节等价：搬移 + 依赖注入，不重写逻辑）。变化轴：改轮次增量派生 /
+// notify 时序 / base 推进 / closeAfterRound 消费语义，只改本文件；Service 经
+// buildSessionRunnerContext 注入三个依赖回调（notify / 持久化上报 / close 兑现）。
+
+import { getLogger } from "../core/logger.ts";
+
+import { getFullTextFrom, nextRoundBaseTurnIndex } from "./execution-record.ts";
+import type { ExecutionRecord } from "./types.ts";
+
+const logger = getLogger("subagents");
+
+/** 轮次结算的依赖注入（Service 侧供给）。 */
+export interface RoundSettlementDeps {
+  /** 本轮增量的通知投递（Service.notifyComplete——经 notifyHost）。 */
+  notifyComplete: (record: ExecutionRecord) => void;
+  /** 轮终迁移持久化上报（store.reportRecordTransition——live ≡ reload 等价性）。 */
+  reportRecordTransition: (record: ExecutionRecord) => void;
+  /** closeAfterRound 兑现（Service.closeAfterRoundSettled——chatMode 优雅关闭的终态化）。 */
+  closeAfterRoundSettled: (record: ExecutionRecord) => Promise<void>;
+}
+
+/** 构造 onRoundSettled 回调（session-runner agent_settled 时调用）。
+ *
+ * [V2 决策 2] chatMode 首轮闭环：session-runner 已 arm idle timer，
+ * isIdle=true 让 notify 守卫放行（时序：armIdleTimer → onRoundSettled）。
+ * 回调体原为 subagent-service.ts buildSessionRunnerContext 的内联闭包，D4-② 拆出。 */
+export function createRoundSettler(deps: RoundSettlementDeps): (record: ExecutionRecord) => void {
+  return (record) => {
+    // v4 B-1：status 保持 running（旧 idle 折入 running）；session-runner 已 arm idle timer，
+    // isIdle=true 让 notify 守卫放行（时序：armIdleTimer → onRoundSettled，见 session-runner.ts:670）。
+    // round 可能初始 undefined（与 notifier.ts `record.round ?? 0` 兜底一致），
+    // 首轮 0+1=1。round 是 notifier dedup key 的组成部分，递增后同 id 下一轮不被 60s dedup 吞。
+    record.round = (record.round ?? 0) + 1;
+    // [N2][增量] 轮次回复写点（增量语义）：roundText 自 roundBaseTurnIndex 起派生本轮增量
+    //（undefined 视为 0——首轮增量 = 全量，与改造前首轮逐字节一致）。成功轮次的 MF-2 原写点
+    //（doFinalizeRoundToIdle）不可达——agent_settled 恒 arm idle timer → runAndFinalize 恒
+    // early return。写入 record.result 后再 notify；本轮无非空增量且无 lastError（纯工具轮 /
+    // interrupt 抢占轮 / 模型空回复）时固定占位 "(no output this round)"（D5：增量语义下沿用
+    // 旧 record.result = 上一轮增量 → 本轮通知正文 = 上一轮内容，父 agent 误读为原样重复回复；
+    // lastError 兜底保留让失败轮通知可读）。后续 closeAfterRoundSettled 的合成 result 读
+    // record.result，同样携带本轮增量。
+    const roundText = getFullTextFrom(record, record.roundBaseTurnIndex ?? 0);
+    record.result = roundText ||
+      (record.lastError ? `round did not complete: ${record.lastError}` : "(no output this round)");
+    // 先送达本轮增量（notify），再推进 base / 消费 closeAfterRound——终态通知由
+    // closeAfterRoundSettled / closeChatIdle 的 notifyClosed 显式发出（dedup 身份为裸 id，
+    // 与本次 round notify 的 id:round key 区分），保证「本轮增量 + 终态通知」都送达；
+    // 轮次收尾 .then 的冷路径 notifyComplete 仍与本次 round notify 同 key 被 60s
+    // dedup 吞（不构成第三条）。
+    //
+    // 幂等性（覆盖面如实限定）：同步路径 at-least-once——notifyComplete（同步 void）抛错时
+    // 推进/消费被跳过 → base 不推进 → 增量未消费，下轮 roundText 必含本轮文本（重发载体为
+    // 后续轮次增量拼接）。轮次收尾 .then 的冷路径 notifyComplete 不构成重发通道
+    // （notifier dedup.set 与 pending.splice 均先于 sendMessage，同 key `${id}:${round}`——
+    // round 已递增——60s 窗内重入被吞）。异步 flush 窗口不保证：合并 timer armed（其他 busy
+    // background 在场）或 isIdle 退避期间 notify 的『成功』只是入队，实际 sendMessage 发生在
+    // base 推进之后的异步时机；该窗口进程崩溃或 sendMessage 失败 → 丢失不可重发（现状全量
+    // 重发的次轮自愈在增量语义下消失），wave1 期恢复通道仅父 agent 经 /subagents 详情读取
+    // record.result，wave2 指针行落地后补全。反序（先推进后 notify）在同步路径 notify 失败时
+    // 静默丢增量且无任何重算机会，故 notify 后推进是定案。重复发送由 notifier dedup key
+    // 60s 窗界定。
+    deps.notifyComplete(record);
+    // R1 观测哨（不变式违反形态）：推进前检查末 turn 未闭合且 text 非空——pi 现序下不可达
+    //（带 usage 的 message_end 恒先于 turn_end，settle 时 turn 全闭合，见 types.ts
+    // roundBaseTurnIndex 注释的行号锚定），ES1 单测自造事件序列锁不住 pi 层变化；pi 升级若
+    // 改变 turn_end/agent_end 时序，此哨兵留痕（该形态下公式仍把文本计入本轮，不丢数据）。
+    const lastTurn = record.turns[record.turns.length - 1];
+    if (lastTurn !== undefined && !lastTurn.closed && lastTurn.text.length > 0) {
+      logger.warn(
+        `[subagents] round settle with unclosed non-empty turn (record=${record.id}, turnIndex=${record.turns.length - 1}) — pi turn_end/agent_end ordering may have changed`,
+      );
+    }
+    // [增量] base 推进（notify 之后）：下一轮增量从本轮边界起。滞后空 turn 不计入边界
+    //（防御分支，留在下一轮增量内防丢文本——nextRoundBaseTurnIndex 注释）。
+    record.roundBaseTurnIndex = nextRoundBaseTurnIndex(record);
+    // 轮终迁移持久化（residual-fixes U3 补全）：热路径轮终不经 doFinalizeRoundToIdle
+    //（agent_settled 恒 arm idle timer → runAndFinalize 恒 early return，MF-2 原写点
+    // 不可达）——不 appendEntry 则 runtime/W18 派生缓存不失效，renderer 停留在
+    // register 快照（无 result），chat 等续聊的 waiting 形态显示不出来、spinner
+    // 卡死。显式上报：entry 携带本轮 result/round/chatMode（§5.4：result 有值 +
+    // chatMode=true → waiting）。closeAfterRound 的终态 entry 在此后追加，序不变。
+    deps.reportRecordTransition(record);
+    // [M5] closeAfterRound 消费点：chatMode 每轮完成的统一汇聚点（热路径轮不经
+    // runAndFinalize CAS 分支——agent_settled 恒 arm idle timer → runAndFinalize 恒
+    // early return，旧消费点对 chatMode 不可达，标志置了无人消费、tool 谎报 closed:true）。
+    if (record.closeAfterRound) {
+      record.closeAfterRound = undefined;
+      void deps.closeAfterRoundSettled(record);
+    }
+  };
+}