@zhushanwen/subagent-core 0.2.0 → 0.5.1

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 = {
@@ -352,6 +402,12 @@ export type RecordStorePi = {
  * 读时从 sessions/*.jsonl 重建（[perf] light 头部扫描 + per-file 缓存）。
  *
  * 任何 mutate → notifyChange()（仅通知监听器；磁盘缓存靠 stat 戳自校验，不清空）。
+ *
+ * record 状态查询面（U10① D6）：按状态枚举 listRunning/collectRecords(statusFilter)、
+ * 按 id 查询 getMutable/findLightById/getFullRecord——方法签名即导出形态，本类零改动。
+ *
+ * @experimental execution 运行时面（设计 docs/design/subagent-core-sink-design.md §3.3 D6）：
+ * 一个 minor 周期内允许签名微调，稳定后转常规 semver 承诺。
  */
 export class RecordStore {
   private readonly records = new Map<string, ExecutionRecord>();
@@ -698,11 +754,11 @@ export class RecordStore {
       ...(chatMode
         ? { resumable: true }
         : {
-            status: "closed" as const,
-            closedReason: "gc" as const,
-            endedAt: Date.now(),
-            error: "orphan recovery: no child session file (spawn interrupted or file removed externally)",
-          }),
+          status: "closed" as const,
+          closedReason: "gc" as const,
+          endedAt: Date.now(),
+          error: "orphan recovery: no child session file (spawn interrupted or file removed externally)",
+        }),
     });
   }
 
@@ -740,9 +796,19 @@ export class RecordStore {
     this.indexHigherVersion = false;
   }
 
-  /** /resume /fork /new 后复活（dispose 的逆操作）。 */
+  /**
+   * /resume /fork /new 后复活（dispose 的逆操作）。
+   *
+   * [PS-10/T6④] 同步复位 orphanJudged 防重缓存：resumable 形态（IO-error 保守分支 /
+   * chatMode 分流）没有 .finalized sidecar 锚，重判资格完全由本缓存承载——dispose 时
+   * 有 clear（session 结束），但 revive 此前不复位，导致「同进程内曾经的 IO 失败记录
+   * 永久停留 resumable」，与本文件 recoverOrphanRecords 注释承诺的「IO 恢复后重开可重判」
+   * 不符。/new 复活正是「重开」语义：IO 已恢复的记录下次 recoverOrphanRecords 重新判定
+   * 收敛终态；仍不可读的记录重判再落一次 resumable entry（幂等，末条语义不变）。
+   */
   revive(): void {
     this._disposed = false;
+    this.orphanJudged.clear();
   }
 
   // ── 内部 ──────────────────────────────────────────────────
@@ -849,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）。
@@ -869,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
@@ -971,7 +1005,10 @@ export class RecordStore {
       })
       .catch((err: unknown) => {
         this.indexDirty = true; // 失败恢复 dirty，下轮过窗重试
-        logger.debug("[subagents] sessions-index write failed", {
+        // [PS-14/T7③] 升 warn：索引反复写失败（权限/磁盘满）曾仅 debug 级，排障时
+        // 无线索。失败会跨轮重试（dirty 恢复），warn 每次过窗写失败都会出现——
+        // 正是「反复写失败需要可见」的信号面。
+        logger.warn("[subagents] sessions-index write failed", {
           detail: { dir: encDir, error: err instanceof Error ? err.message : String(err) },
         });
       });
@@ -1070,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,
@@ -1171,14 +1236,9 @@ export class RecordStore {
     return rec;
   }
 
-  /** 从缓存与索引移除某文件（文件删除时；负缓存条目无 id，仅删缓存项）。 */
-  private dropFileCache(file: string): void {
-    const entry = this.fileCache.get(file);
-    if (entry) {
-      if (!entry.negative) this.idToFile.delete(entry.light.id);
-      this.fileCache.delete(file);
-    }
-  }
+  // [PS-15/T7⑤] 「从缓存与索引移除单文件」的旧私有方法已整体删除：全仓无调用方
+  // 的死代码（设计 §4.3 PS-15 实锤，顺手清理，无行为影响）。「文件删除时移除缓存」
+  // 的职责实际由 reconstructAll 的消失文件修剪路径承担。
 
   /** 排序比较器：status priority（running<failed<cancelled<done）+ startedAt desc。 */
   private static compareRecords(a: SubagentRecord, b: SubagentRecord): number {

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

package/src/execution/session-file-gc.ts

@@ -2,11 +2,19 @@
 //
 // 概率性清理过期 subagent session 文件（TTL 30 天）。
 // session_start 时调用，best-effort（失败不影响启动）。
+//
+// [D8 池引用计数接线] 同概率门内追加引擎池 TTL 兜底（cleanupExpiredPoolRefs）：
+// journal / refs.json 条目按同 30 天 mtime 回收。record 主数据（主 session 文件里
+// 的 subagent-record entry）由 pi 侧管理，其删除对 core 无触发点——done record 的
+// journal 没有精确回收锚，只能靠此兜底；workflow 域（taskId 占位无 record 生命周期
+// 锚）同样依赖它（D8 分域口径「journal 依赖 30 天 TTL 自然回收」的落地）。
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { isProcessAlive, readAliveMarker } from "./alive-store.ts";
+import { getEngineDataDir } from "./engine/common/data-dir.ts";
+import { cleanupExpiredPoolRefs } from "./engine/common/pool-manager.ts";
 
 /** 30 天 TTL（毫秒）。 */
 const TTL_DAYS = 30;
@@ -29,21 +37,105 @@ const SUBAGENTS_DIR = "subagents";
  *   1. 概率性触发（CLEANUP_PROBABILITY）
  *   2. 递归扫描 <agentDir>/subagents 下所有 .jsonl 文件
  *   3. mtime 超 TTL → unlink
+ *   4. [D8] 引擎池 TTL 兜底：journal / refs 条目超龄回收（见文件头注释）
  */
 export function maybeCleanupExpiredSessionFiles(agentDir: string, cwd: string): void {
   void cwd;
   try {
     if (Math.random() >= CLEANUP_PROBABILITY) return;
     const dir = path.join(agentDir, SUBAGENTS_DIR);
-    if (!fs.existsSync(dir)) return;
-    const now = Date.now();
-    walkAndClean(dir, now);
+    if (fs.existsSync(dir)) {
+      walkAndClean(dir, Date.now());
+    }
+    cleanupEnginePoolsBestEffort();
   } catch (_e) {
     // best-effort：任何异常不阻断 session_start
     void _e;
   }
 }
 
+/** 引擎池 TTL 兜底（dataDir 解析失败 = 未配置宿主服务，best-effort 吞掉）。 */
+function cleanupEnginePoolsBestEffort(): void {
+  try {
+    cleanupExpiredPoolRefs(getEngineDataDir(), TTL_MS);
+  } catch (_e) {
+    void _e;
+  }
+}
+
+/** 孤儿 sidecar 名判定：.cancelled/.finalized/.alive，以及 [MF#2] patch 回传
+ *  （<branch>.patch 按 branch 命名，与 .jsonl basename 无关联，删除 .jsonl 时无法同删；
+ *  作为孤儿按 TTL 清理，避免永久堆积）。 */
+function isOrphanSidecarName(name: string): boolean {
+  return (
+    name.endsWith(".cancelled") ||
+    name.endsWith(".finalized") ||
+    name.endsWith(".alive") ||
+    name.endsWith(".patch")
+  );
+}
+
+/** stat 超 TTL 即 unlink（manifest .json 与孤儿 sidecar 共用原语）。失败静默（文件可能已被删除）。 */
+function unlinkIfExpired(full: string, now: number): void {
+  try {
+    const stat = fs.statSync(full);
+    if (now - stat.mtimeMs > TTL_MS) {
+      fs.unlinkSync(full);
+    }
+  } catch (_e) {
+    // 文件可能已被删除，忽略
+    void _e;
+  }
+}
+
+/** .jsonl 超 TTL 清理：.alive 探活保护（活进程的 session 不删，D-024 安全网）+
+ *  同名 sidecar 一起清理。失败静默（文件可能已被删除）。 */
+function cleanExpiredJsonl(full: string, now: number): void {
+  try {
+    const stat = fs.statSync(full);
+    if (now - stat.mtimeMs > TTL_MS) {
+      // .alive 探活：活进程的 session 不删（D-024 安全网）。
+      const aliveMarker = readAliveMarker(full);
+      if (aliveMarker !== undefined && isProcessAlive(aliveMarker.pid)) {
+        return; // 活进程 → 跳过，不清理
+      }
+      fs.unlinkSync(full);
+      // 同名 sidecar 一起清理。
+      for (const ext of [".cancelled", ".finalized", ".alive"]) {
+        try { fs.unlinkSync(`${full}${ext}`); } catch (_e) { void _e; /* sidecar 可能不存在 */ }
+      }
+    }
+  } catch (_e) {
+    // 文件可能已被删除，忽略
+    void _e;
+  }
+}
+
+/** 单条 dirent 分发。分支判断顺序与 fs 副作用时序保持与原实现一致：
+ *  目录递归 →（records 内）manifest .json → .jsonl → 孤儿 sidecar。 */
+function cleanDirent(dir: string, entry: fs.Dirent, now: number, allowManifestJson: boolean): void {
+  const full = path.join(dir, entry.name);
+  if (entry.isDirectory()) {
+    // 只在进入名为 records 的子目录时打开 manifest .json 清理。
+    // records 在 <enc>/records/ 下递归自动覆盖；其他位置（如 subagents/worktrees.json）
+    // 不能匹配 .json——否则会误删 worktree reaper 依赖的状态文件。
+    walkAndClean(full, now, entry.name === "records");
+  } else if (
+    allowManifestJson &&
+    entry.name.endsWith(".json") &&
+    // 跳过 .tmp.：recoverTmpFiles（session_start）同步处理 tmp，GC 不重复。
+    // 不校验内容——30 天 mtime 已是强 orphan 信号，扩展名 + 文件名足够。
+    !entry.name.includes(".tmp.")
+  ) {
+    unlinkIfExpired(full, now);
+  } else if (entry.name.endsWith(".jsonl")) {
+    cleanExpiredJsonl(full, now);
+  } else if (isOrphanSidecarName(entry.name)) {
+    // 孤儿 sidecar（兄弟 .jsonl 已被外部删除）：按同 TTL 清理。
+    unlinkIfExpired(full, now);
+  }
+}
+
 /** 递归扫描目录，unlink 超 TTL 的 .jsonl 文件及其 .cancelled sidecar。
  *  [F2] 进入名为 records 的子目录时，额外清理超 TTL 的 manifest .json（跳过 .tmp.——
  *  recoverTmpFiles 同步处理）。allowManifestJson 仅由父调用按目录名开启，其他位置
@@ -57,64 +149,6 @@ function walkAndClean(dir: string, now: number, allowManifestJson = false): void
     return;
   }
   for (const entry of entries) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      // 只在进入名为 records 的子目录时打开 manifest .json 清理。
-      // records 在 <enc>/records/ 下递归自动覆盖；其他位置（如 subagents/worktrees.json）
-      // 不能匹配 .json——否则会误删 worktree reaper 依赖的状态文件。
-      walkAndClean(full, now, entry.name === "records");
-    } else if (
-      allowManifestJson &&
-      entry.name.endsWith(".json") &&
-      // 跳过 .tmp.：recoverTmpFiles（session_start）同步处理 tmp，GC 不重复。
-      // 不校验内容——30 天 mtime 已是强 orphan 信号，扩展名 + 文件名足够。
-      !entry.name.includes(".tmp.")
-    ) {
-      try {
-        const stat = fs.statSync(full);
-        if (now - stat.mtimeMs > TTL_MS) {
-          fs.unlinkSync(full);
-        }
-      } catch (_e) {
-        // 文件可能已被删除，忽略
-        void _e;
-      }
-    } else if (entry.name.endsWith(".jsonl")) {
-      try {
-        const stat = fs.statSync(full);
-        if (now - stat.mtimeMs > TTL_MS) {
-          // .alive 探活：活进程的 session 不删（D-024 安全网）。
-          const aliveMarker = readAliveMarker(full);
-          if (aliveMarker !== undefined && isProcessAlive(aliveMarker.pid)) {
-            continue; // 活进程 → 跳过，不清理
-          }
-          fs.unlinkSync(full);
-          // 同名 sidecar 一起清理。
-          for (const ext of [".cancelled", ".finalized", ".alive"]) {
-            try { fs.unlinkSync(`${full}${ext}`); } catch (_e) { void _e; /* sidecar 可能不存在 */ }
-          }
-        }
-      } catch (_e) {
-        // 文件可能已被删除，忽略
-        void _e;
-      }
-    } else if (
-      entry.name.endsWith(".cancelled") ||
-      entry.name.endsWith(".finalized") ||
-      entry.name.endsWith(".alive") ||
-      // [MF#2] patch 回传（<branch>.patch）按 branch 命名，与 .jsonl basename 无关联，
-      // 删除 .jsonl 时无法同删；作为孤儿按 TTL 清理，避免永久堆积。
-      entry.name.endsWith(".patch")
-    ) {
-      // 孤儿 sidecar（兄弟 .jsonl 已被外部删除）：按同 TTL 清理。
-      try {
-        const stat = fs.statSync(full);
-        if (now - stat.mtimeMs > TTL_MS) {
-          fs.unlinkSync(full);
-        }
-      } catch (_e) {
-        void _e;
-      }
-    }
+    cleanDirent(dir, entry, now, allowManifestJson);
   }
 }