@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/execution/idle-gc.ts

@@ -4,9 +4,12 @@
  * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
  */
 import { getLogger } from "../core/logger.ts";
+import { getEngineDataDir } from "./engine/common/data-dir.ts";
+import { releasePoolRef } from "./engine/common/pool-manager.ts";
 import { bestEffort } from "./best-effort.ts";
 import { isResumable } from "./lifecycle-predicates.ts";
 import type { RecordStore } from "./record-store.ts";
+import type { ExecutionRecord } from "./types.ts";
 
 const logger = getLogger("subagents");
 
@@ -24,6 +27,15 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
  * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
  * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
  * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
+ *
+ * [D8 池引用计数接线] 归档时同步释放该 record 的引擎池引用（releasePoolRef：
+ * journal 跟随 record 删除 + refs 移除 + 归零删池内原生状态）。锚点选在 30 天 TTL
+ * 而非 dispose/archive 类时机，依据：idle record 30 天后引擎侧不会再有活动（archive
+ * 后 message 续聊走 fork-from/新 start，不触原引擎），且与 pi 域 session 文件 30 天
+ * TTL（session-file-gc 同期删①级读源）形成两引擎对称衰减；disposeAllRecords/close
+ * 类时机 record 数据仍保留（可 resurrect / GUI 历史重建可见），journal（②级数据源）
+ * 不能删——那是 record 主数据死亡（主 session 文件被 pi 侧删除，core 无触发点）才有
+ * 的处置，由 cleanupExpiredPoolRefs 的 TTL 兜底覆盖。
  */
 export function startIdleGc(store: RecordStore): () => void {
   const timer = setInterval(() => {
@@ -38,6 +50,7 @@ export function startIdleGc(store: RecordStore): () => void {
           } catch (err) {
             bestEffort(err, `GC archive record ${record.id}`);
           }
+          releaseEnginePoolRef(record);
         }
       }
     }
@@ -45,3 +58,18 @@ export function startIdleGc(store: RecordStore): () => void {
   timer.unref?.();
   return () => clearInterval(timer);
 }
+
+/**
+ * 释放 record 的引擎池引用（best-effort）。无 engineHandle（存量 record / 非引擎
+ * 路径）时 no-op；engine 缺省投影 'pi'（与读侧存量 entry 零迁移口径一致）。
+ */
+function releaseEnginePoolRef(record: ExecutionRecord): void {
+  const poolKey = record.engineHandle?.poolKey;
+  if (poolKey === undefined) return;
+  const engineId = record.engine ?? "pi";
+  try {
+    releasePoolRef(getEngineDataDir(), engineId, poolKey, record.id);
+  } catch (err) {
+    bestEffort(err, `GC release pool ref for record ${record.id}`);
+  }
+}

package/src/execution/lifecycle-predicates.ts

@@ -20,7 +20,7 @@
 // 故 isIdle 在这两个检查点恒为 true——notify 守卫与 early-return 判据可靠。
 
 import { hasIdleTimer } from "./lifecycle-manager.ts";
-import { getChildByRecord } from "./session-runner.ts";
+import { getChildByRecord } from "./engine/engines/pi/session-runner.ts";
 import type { ExecutionRecord } from "./types.ts";
 
 /**

package/src/execution/notify-host.ts

@@ -0,0 +1,212 @@
+// [D4-① 通知簇职责轴] background 完成通知的 host 面——原 SubagentService 私有通知簇
+// （notifyComplete / notifyClosed / piAdapter / toNotifyRecord / emitPendingRegister /
+// emitPendingUnregister + notifier 实例持有）整体搬移至此（行为逐字节等价：搬移 +
+// 依赖注入，不重写逻辑）。变化轴：改通知文案 / dedup 身份 / 放行守卫 / pending 注册
+// 注销协议，只改本文件；Service 只保留编排与依赖注入（getPi / listRunning / isIdle）。
+
+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 { createNotifier } from "./notifier.ts";
+import type { BgNotifyRecord } from "./notifier.ts";
+import type { ExecutionRecord, RecordSnapshot } from "./types.ts";
+
+/** Pi ExtensionAPI 的最小接口（duck-typed）——原定义于 subagent-service.ts，随通知簇
+ *  （piAdapter / emitPending* 的依赖）搬移至此并导出（Service 的 session 注入参数仍引用）。
+ *  subagent-service 直接调 pi.sendMessage 发 background 完成通知（BgNotifier 滑动窗口合并），
+ *  不委托 pending-notifications EventBus 中继——后者只管 registry 不参与通知发送。 */
+export interface PiLike {
+  appendEntry(customType: string, data?: unknown): void;
+  events: { emit(channel: string, data: unknown): void };
+  sendMessage(
+    message: { customType: string; content: string; display: boolean; details?: unknown },
+    options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }, // g4-allow: 类型注解——PiLike 接口形状（pi.sendMessage 签面子集），非投递调用
+  ): void;
+  /** 订阅 pi 事件（D8：notifier 的 settled 边沿订阅用 'agent_settled'）。
+   *  pi 0.84.1 的 on 返回 void 且无 off——退订语义由调用侧 disposed 标志包装兑现。
+   *  可选：旧测试 mock pi 可能未实现 on，缺省时 notifier 退化为内核退避路径。 */
+  on?(event: "agent_settled", handler: () => void): void;
+}
+
+/** NotifyHost 的依赖注入（Service 侧供给，全部惰性求值——pi/session 级状态运行时可变）。 */
+export interface NotifyHostDeps {
+  /** 当前 pi session handle（session_start 注入 / shutdown 置 null）。 */
+  getPi: () => PiLike | null;
+  /** store 的 running record 快照（piAdapter.hasRunningBackground 用）。 */
+  listRunning: () => RecordSnapshot[];
+  /** 主 agent isIdle 查询（ctx.isIdle，initSession 注入；未注入时 undefined）。 */
+  getIsIdle: () => (() => boolean) | undefined;
+}
+
+/** 通知簇 host 面（Service 经此消费；notifier 实例封装在内部不外露）。 */
+export interface NotifyHost {
+  /** background 完成回注（原 Service.notifyComplete）。 */
+  notifyComplete(record: ExecutionRecord): void;
+  /** [C-1] chatMode close 终态通知（原 Service.notifyClosed）。 */
+  notifyClosed(record: ExecutionRecord, emptyBody?: boolean): void;
+  /** pending-notifications 注册（原模块函数 emitPendingRegister，pi 经 deps 取）。 */
+  emitPendingRegister(id: string, name?: string): void;
+  /** pending-notifications 注销（原模块函数 emitPendingUnregister）。 */
+  emitPendingUnregister(id: string, reason: string): void;
+  /** dispose 的逆操作（initSession 复活，原 notifier.revive 委托）。 */
+  revive(): void;
+  /** dispose 前冲刷待发通知（原 notifier.flushPendingNotifications 委托）。 */
+  flushPendingNotifications(): void;
+  /** 丢弃 pending 通知（原 notifier.dispose 委托）。 */
+  dispose(): void;
+}
+
+/** pending-notifications 注册/注销 helper（避免重复代码）。
+ *  name 是 GUI pending 通知的显示名——取 basename 短名（displayAgentName），
+ *  完整路径仍走 record.agent（env 注入 / 持久化）。 */
+function emitPendingRegister(pi: PiLike | null, id: string, name?: string): void {
+  pi?.events.emit("pending:register", {
+    id,
+    type: "subagent",
+    name: name ? displayAgentName(name) : id,
+  });
+}
+
+function emitPendingUnregister(
+  pi: PiLike | null,
+  id: string,
+  reason: string,
+): void {
+  pi?.events.emit("pending:unregister", {
+    id,
+    reason,
+  });
+}
+
+/** 通知簇工厂：notifier 实例随本函数创建并封装（原 Service 构造器
+ *  `createNotifier(this.piAdapter())` 的等价形态）。 */
+export function createNotifyHost(deps: NotifyHostDeps): NotifyHost {
+  /** notifier 的 NotifierHost 适配器（绑定到 pi.sendMessage + store 查询）。 */
+  const piAdapter = (): NotifierHost => {
+    return {
+      sendMessage: (message, options) => {
+        deps.getPi()?.sendMessage(message, options);
+      },
+      hasRunningBackground: () => {
+        // [M3] 「在跑的 background 工作」= 有活进程且非等待续聊（idle timer armed）。
+        // v4 B-1 把旧 idle 折入 running 且 record 留 store：轮次完成的 chatMode record
+        // （timer armed、无在跑轮）与 one-shot 完成后等待 message 升级的 record 都不再计入。
+        // 旧判定 `mode === "background"` 对这两类恒 true → 轮次完成通知恒挂 60s 合并窗口
+        // （notifier MERGE_WINDOW_MS），主 agent 的续聊回复固定延迟 60s 送达，持续对话（G1）失效。
+        return deps.listRunning().some(
+          (r) => r.mode === "background" && hasLiveProcessHandle(r.id) && !hasIdleTimer(r.id),
+        );
+      },
+      isIdle: () => deps.getIsIdle()?.() ?? true,
+      // [must-fix #4 / D8] settled 边沿订阅，与 isIdle 同源（session_start 注入的 pi）。
+      // 只注入原生订阅能力；disposed 标志包装（退订语义）在 notifier 的 port 装配完成。
+      onAgentSettled: (handler) => { deps.getPi()?.on?.("agent_settled", handler); },
+    };
+  };
+
+  const notifier: BgNotifier = createNotifier(piAdapter());
+
+  /** record → BgNotifyRecord（notifier.notify 入参映射，内部不外露）。
+   *  v4 B-1：守卫放行 closed（终态，含 cancelled）、isIdle（对话模式轮次完成，notify 主 agent G1）
+   *  或 isResumable（running + 无活进程——SP-5 one-shot 成功完成 / MF-6 失败轮回退）。
+   *  正在执行（running + 活进程 + 非 timer-armed）返回 undefined（调用方 notifyComplete 跳过）。
+   *  SP-1: closed 统一终态，closedReason 由 BgNotifyRecord 携带。 */
+  const toNotifyRecord = (record: ExecutionRecord): BgNotifyRecord | undefined => {
+    const snap = snapshot(record);
+    const s = snap.status;
+    // [N1] isResumable 放行：SP-5 one-shot 成功完成后 finalizeRoundToIdle 把 record 回退
+    // running-resumable——进程已死且永不 arm idle timer（armIdleTimer 只在 agent_settled 的
+    // chatMode 分支调用），旧守卫（closed / isIdle only）对其恒拒绝 → 完成通知静默丢失，
+    // 而 one-shot 失败走 finalizeRecord 保持 closed 反而通知——与 tool 契约「runs once,
+    // notifies on completion」完全倒置。isResumable = running + 无活进程，恰为该完成态；
+    // 在跑轮的 record 有活进程，不会被误放行。
+    if (s !== "closed" && !isIdle(record) && !isResumable(record)) return undefined;
+    // closed → BgNotifyRecord.closed（cancelled 区分靠 closedReason）；chatMode 的 isIdle/
+    // isResumable（轮次完成或 MF-6 失败轮回退，对话可续）→ running（轮次完成）。
+    // isResumable 且非 chatMode（SP-5 one-shot 成功完成）→ closed：对主 agent 的语义是
+    // completed（非对话轮次），且只有 closed 分支文案携带 worktree patchFile 的 git apply
+    // 提示——one-shot worktree 模式的改动回收依赖该提示（running 分支文案不含 patchFile）。
+    const notifyStatus: BgNotifyRecord["status"] =
+      s === "closed" || !record.chatMode ? "closed" : "running";
+    return {
+      id: snap.id,
+      status: notifyStatus,
+      agent: snap.agent,
+      model: snap.model,
+      result: snap.result,
+      error: snap.error,
+      startedAt: snap.startedAt,
+      endedAt: snap.endedAt,
+      patchFile: record.patchFile,
+      // round 透传给 notifier 的 dedup key（对话模式按轮次去重，G1 决策 9）。
+      round: record.round,
+      // SP-1: closedReason 透传给 notifier（L2 原因，供通知文案按需展示）。
+      closedReason: record.closedReason,
+      // [wave2] chatMode 条件透传 sessionFile：通知末尾追加 Full transcript 指针行
+      //（增量语义的全文恢复通道，见 notifier.buildLlmContent）。one-shot（chatMode
+      // falsy）不透传——通知输出逐字节不变（G4），该条件由 message-close 测试的
+      // 必选用例锁死（漏加条件时 notifier 单测不红——notifier 层只见最终字段）。
+      sessionFile: record.chatMode ? record.sessionFile : undefined,
+    };
+  };
+
+  return {
+    /** background 完成回注（record → BgNotifyRecord 映射 + notifier.notify）。
+     *  正在执行（running + 活进程 + 非 timer-armed）静默跳过——notify 只对 closed（终态）、
+     *  isIdle（chatMode 轮次完成）或 isResumable（SP-5 one-shot 成功完成 / MF-6 失败轮回退）有意义。
+     *  SP-1: closed 统一终态（done/failed/crashed 合并），closedReason 携带 L2 原因。 */
+    notifyComplete(record: ExecutionRecord): void {
+      const notify = toNotifyRecord(record);
+      if (notify) notifier.notify(notify);
+    },
+
+    /** [C-1] chatMode close 终态通知（设计 D2：正文空/本轮增量 + sessionFile 指针行）。
+     *
+     *  与 notifyComplete 的差异只在 dedup 身份与轮次统计：终态通知必须与最后一轮的轮次通知
+     *  区分（轮次通知 key=`id:round`），否则同 key 被 60s dedup 吞——close 后父 agent 永远
+     *  收不到带指针行的终态通知（审查 C-1）。故 round 置 undefined（key 回退为裸 id），
+     *  轮数改经 totalRounds 进文案 "completed after N rounds."（C-2）。
+     *
+     *  仅 chatMode close 语义调用（closeChatIdle / closeAfterRoundSettled 终态化成功后）。
+     *  one-shot 显式拒绝（G4：one-shot close 路径现状无终态通知，字节不变）；cancel 走
+     *  cancelBackground 自己的 notifyComplete，不经本方法。幂等性：两条 close 路径均由
+     *  closeSubagent 的 status 分流守卫（closed 后幂等 no-op）/ CAS 抢锁保证只执行一次，
+     *  本方法自身不重复发送；迟到的轮次收尾 .then 通知与轮次通知同 key=`id:round`，
+     *  60s 窗内仍被吞，不构成第三条。 */
+    /** @param emptyBody true = 终态通知正文置空串（D2 路径②）。W16 P-1 修复后
+     *  closeChatIdle 的 doneResult.text 改用 record.result 保真（close 终态
+     *  subagent-record entry 的 result 不抹空轮终真实值），「正文空」不再由合成空
+     *  text 的副作用承载，改为显式参数——持久化 result 与通知正文两个关注点解耦。 */
+    notifyClosed(record: ExecutionRecord, emptyBody = false): void {
+      if (!record.chatMode) return;
+      const notify = toNotifyRecord(record);
+      if (!notify) return;
+      notify.round = undefined;
+      if (emptyBody) notify.result = "";
+      if (record.round != null) notify.totalRounds = record.round;
+      notifier.notify(notify);
+    },
+
+    emitPendingRegister(id: string, name?: string): void {
+      emitPendingRegister(deps.getPi(), id, name);
+    },
+
+    emitPendingUnregister(id: string, reason: string): void {
+      emitPendingUnregister(deps.getPi(), id, reason);
+    },
+
+    revive(): void {
+      notifier.revive();
+    },
+
+    flushPendingNotifications(): void {
+      notifier.flushPendingNotifications();
+    },
+
+    dispose(): void {
+      notifier.dispose();
+    },
+  };
+}

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;
@@ -335,6 +350,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 = {
@@ -865,18 +915,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 +932,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 +1107,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,

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);
+    }
+  };
+}