@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/execution/finalize-record.ts

@@ -1,251 +0,0 @@
-// src/execution/finalize-record.ts
-//
-// 时序收尾逻辑（从 subagent-service.ts 提取，降低主文件行数 < 1000 上限）。
-//
-// D-017 时序：collectPatch → completeRecord → archive → cleanup(finalized+worktree+
-// aliveMarker+pending注销) → manifest(最后 best-effort)。
-//
-// [Critical #1 / PR #85] cleanup 全部在 manifest 写之前执行——manifest 是诊断辅助
-//（orphan recovery），写失败仅记录不阻断。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup，
-// 导致磁盘满/权限错时 worktree 泄漏 + finalized marker 不写 + alive marker 残留 +
-// pending 记账错乱。现 manifest 写移到 Step 4（最后），best-effort（console.error +
-// appendEntry，不 throw）。
-//
-// B9 兜底：completeRecord/archive 抛错→后续 cleanup/manifest 仍执行。
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import { removeAliveMarker } from "./alive-store.ts";
-import { bestEffort } from "./best-effort.ts";
-import { completeRecord } from "./execution-record.ts";
-import { writeFinalized } from "./finalized-marker.ts";
-import type { ManifestStore } from "./manifest-store.ts";
-import type { ModelConfigService } from "./model-config-service.ts";
-import { getSubagentSessionDir } from "./path-encoding.ts";
-import type { RecordStore } from "./record-store.ts";
-import { writeCancelledTombstone } from "./tombstone-store.ts";
-import type { AgentResult, ClosedReason, ExecutionRecord } from "./types.ts";
-import type { WorktreeManager } from "./worktree-manager.ts";
-
-const logger = getLogger("subagents");
-
-/** doFinalizeRecord 的依赖（从 SubagentService 注入，避免 this 绑定 + 解耦可测试）。 */
-export interface FinalizeDeps {
-  manifestStore: ManifestStore;
-  worktreeManager: WorktreeManager;
-  store: RecordStore;
-  modelService: ModelConfigService;
-  /** Pi ExtensionAPI（仅用 appendEntry 记录 manifest 写失败事件）。null 在 dispose 后。 */
-  pi: { appendEntry?: (type: string, data: unknown) => void } | null;
-  /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
-  emitUnregister(id: string, status: string): void;
-  // [review 修复] 已删除 redeliverPending 回调（MF-1 消费确认制补投）：pendingMessages
-  // 三段消费链随 deliverToRunning 一并移除（无生产调用方，死机制）。
-}
-
-/**
- * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
- *
- * [Critical #1] Step 3 cleanup 全部在 Step 4 manifest 之前——manifest 写失败仅 console.error +
- * appendEntry，不 throw 不跳过 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord
- * 补字段），manifestToSubagent 投影真实值而非硬编码空串。
- */
-export async function doFinalizeRecord(
-  deps: FinalizeDeps,
-  record: ExecutionRecord,
-  result: AgentResult,
-  status: "closed",
-  closedReason?: ClosedReason,
-): Promise<void> {
-  // ── Step 0: collectPatch（best-effort）──
-  // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
-  //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
-  if (record.worktreeHandle) {
-    try {
-      const sessionsDir = getSubagentSessionDir(
-        deps.modelService.getAgentDir(),
-        record.worktreeHandle.mainCwd,
-      );
-      fs.mkdirSync(sessionsDir, { recursive: true });
-      const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
-      const patch = await deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
-      if (patch.written) record.patchFile = patchFile;
-    } catch (pe: unknown) {
-      bestEffort(pe, "collectPatch (finalizeRecord Step0)");
-    }
-  }
-
-  // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
-  try {
-    completeRecord(record, result, status, closedReason);
-  } catch (err) {
-    bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
-  }
-
-  // ── Step 2: archive（B9: 抛错→后续仍执行）──
-  try {
-    deps.store.archive(record);
-  } catch (err) {
-    bestEffort(err, "store.archive (finalizeRecord B9)", "error");
-  }
-
-  // ── Step 3: finalized + cleanup + aliveMarker + pending注销（全部先执行，幂等）──
-  // [Critical] 清理必须在 manifest 写入之前：worktree cleanup / finalized marker / aliveMarker
-  //   都是幂等且不可跳过的副作用。绝不能因 manifest 写失败而跳过 worktree cleanup
-  //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
-  if (record.sessionFile) {
-    try {
-      // MF-1 fix / v4 B-1: cancelled（closedReason='cancelled'）写 tombstone 而非 finalized，防重建丢失 cancelled
-      if (closedReason === "cancelled") {
-        writeCancelledTombstone(record.sessionFile, {
-          id: record.id,
-          status: "cancelled",
-          agent: record.agent,
-          startedAt: record.startedAt,
-          endedAt: record.endedAt ?? Date.now(),
-        });
-      } else {
-        writeFinalized(record.sessionFile);
-      }
-    } catch (err) {
-      bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
-    }
-  }
-  if (record.worktreeHandle) {
-    try {
-      await deps.worktreeManager.cleanup(record.worktreeHandle);
-    } catch (err) {
-      bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
-    }
-  }
-  if (record.sessionFile) {
-    try {
-      removeAliveMarker(record.sessionFile);
-    } catch (err) {
-      bestEffort(err, "removeAliveMarker (finalizeRecord Step3)");
-    }
-  }
-
-  // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
-  deps.emitUnregister(record.id, status);
-
-  // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
-  // [Critical #1] manifest 是诊断辅助（orphan recovery），不是正确性依赖。写失败时
-  //   仅记录（console.error + appendEntry），绝不让 manifest 写失败跳过上面的 worktree
-  //   cleanup 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup。
-  //   task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord 补字段），
-  //   manifestToSubagent 投影时用真实值而非硬编码空串。
-  try {
-    await deps.manifestStore.writeManifest({
-      id: record.id,
-      rootSessionId: record.rootSessionId ?? "",
-      parentRecordId: record.parentRecordId,
-      agentName: record.agent,
-      // v4 B-1: manifest status 统一为 closed（cancelled 折入 closed，区分靠 tombstone sidecar）
-      status: "closed",
-      createdAt: record.startedAt,
-      completedAt: record.endedAt ?? Date.now(),
-      sessionFile: record.sessionFile,
-      task: record.task,
-      slug: record.slug,
-      model: record.model,
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    logger.error(`[subagent] manifest 写入失败 (record=${record.id}): ${msg}`);
-    deps.pi?.appendEntry?.("subagent:manifest-write-failed", {
-      id: record.id,
-      error: msg,
-    });
-  }
-}
-
-/**
- * 对话模式轮次完成收尾：record 进 idle 态（非终态化，等待续聊）。
- *
- * 与 doFinalizeRecord 的关键区别（M2-A idle 语义）：
- *   - 不调 completeRecord（record 不冻结，保留 turns[] 等运行时状态供续聊累积）
- *   - 不调 store.archive（record 留内存，getMutable 可查、list 可见）
- *   - 不 cleanup worktree（保留对话模式工作目录）
- *   - 不写 manifest（idle 非终态，manifest 是终态诊断辅助）
- *   - 删 .alive marker（进程已 SIGTERM 回收，不再是活进程）
- *   - emitUnregister（进程已死，从 pending 活跃后代差集移除；record 留内存不 archive）
- *
- * MF-2：设 record.result = result.text（否则 notifier idle 回复正文恒为 "(empty)"，
- *   G1/G2 多轮回复送达不成立）。失败轮次（result.success=false，MF-6 回退 idle 路径）
- *   的 result.text 可能为空，用 result.error 兜底让 notify 可读。
- *
- * 状态：record.status = "idle"（覆盖 tryTransition 设的 done/failed），record.round += 1。
- * 各步骤 best-effort 互不阻断（参照 doFinalizeRecord 的 bestEffort 用法）。
- *
- * @param deps 与 doFinalizeRecord 同源（从 SubagentService 注入）
- * @param result 本轮 AgentResult（MF-2：result.text 写入 record.result 供 notifier idle 回复）
- */
-export async function doFinalizeRoundToIdle(
-  deps: FinalizeDeps,
-  record: ExecutionRecord,
-  result: AgentResult,
-): Promise<void> {
-  // MF-2：设 record.result 供 notifier idle 回复正文（否则恒 "(empty)"，G1/G2 不成立）。
-  // MF-6 兜底：失败轮次（success=false）的 result.text 可能为空，用 error 让 notify 可读。
-  // [R2-1] 轮终写点恒写非空：one-shot 空文本成功完成（collectResult getFullText 返回 ""、
-  // success=true、真实可达，本写点被 subagent-service runAndFinalize 的成功分支共用）首轮
-  // result 前值 undefined，兜底补 "(empty)" 占位——措辞与 notifier buildLlmContent 的
-  // `record.result ?? "(empty)"` 兜底同款，通知文案逐字节不变（[增量 G2] G4 取舍保持）。
-  // 轮终信号优先：record.result 非 undefined 是 renderer hasRunning 排除「轮终
-  // running-resumable」的判据（shared SubagentRecord.result 契约），保持 undefined 会让
-  // 完成注入后末位 turn 永久「工作中」。续轮（前值存在）沿用前值：one-shot 无增量语义，
-  // record.result = 该 subagent 最终输出。chatMode 空增量轮 → 固定占位
-  // "(no output this round)"（D5：增量语义下沿用旧 record.result = 上一轮增量，本轮通知
-  // 正文 = 上一轮内容，父 agent 误读为原样重复回复）。
-  let nextResult: string | undefined;
-  if (result.text) {
-    nextResult = result.text;
-  } else if (result.error) {
-    nextResult = `round did not complete: ${result.error}`;
-  } else if (record.chatMode) {
-    nextResult = "(no output this round)";
-  } else {
-    nextResult = record.result ?? "(empty)";
-  }
-  record.result = nextResult;
-
-  // 删 .alive marker（进程已 SIGTERM 回收）。
-  // sessionFile 窗口期可能 undefined（极少——对话模式轮次完成意味着 session 已跑过），
-  // 缺失时跳过但仍设内存 idle（重启后磁盘重建会落到 crashed，边界可接受）。
-  if (record.sessionFile) {
-    try {
-      removeAliveMarker(record.sessionFile);
-    } catch (err) {
-      bestEffort(err, "removeAliveMarker (doFinalizeRoundToIdle)");
-    }
-  }
-
-  // pending-notifications：进程已死，从活跃后代差集移除（record 留内存不 archive，
-  // v4 B-1：record 现为 running-resumable，但 pending 注册的是进程活跃性，进程死了需注销）。
-  deps.emitUnregister(record.id, "running");
-
-  // 状态机（v4 B-1）：record 保持 running（旧 idle 折入 running，覆盖 tryTransition 设的 closed，
-  // 可冷路径 resume），轮次计数 +1。idleSince 时间戳独立保留供 GC 判据。
-  // [S10] closedReason 同步清除：调用方（runAndFinalize catch / MF-6 分支）先 tryTransition
-  // 设了 closed+closedReason 再回退 running——不清则 "gc"/"cancelled" 残留在 running record 上，
-  // 泄漏进 list 投影与后续 notify 载荷（toNotifyRecord 透传 record.closedReason），让一个
-  // 活跃 record 看起来像已被某原因关闭过。
-  record.status = "running";
-  record.closedReason = undefined;
-  record.round = (record.round ?? 0) + 1;
-  record.idleSince = Date.now();
-  // 执行态信号（residual-fixes）：轮终回 running-resumable = 无活进程驱动（idle timer
-  // 回收/保活等待续聊），GUI 侧据此判 waiting（非 streaming）。冷路径续轮（进程启动）清除。
-  record.resumable = true;
-
-  // W16 [D4]：轮终回 running-resumable 是类外状态写点（record 留内存不走 archive），
-  // 显式上报迁移——entry 携带新 round 与本轮 result，pi 文件的重建源不滞后。
-  deps.store.reportRecordTransition(record);
-
-  // [review 修复] 已删除残留 pendingMessages 的 redeliverPending 补投段（MF-1 消费
-  // 确认安全网）：三段消费链随 deliverToRunning 一并移除，本段不可达。
-}

package/src/execution/finalized-marker.ts

@@ -1,51 +0,0 @@
-// src/runtime/execution/finalized-marker.ts
-//
-// Finalized 状态的 sidecar 持久化。
-//
-// 背景：subagent 执行完成（done/failed）后，session.jsonl 的最终写入可能因进程
-// 异常终止而丢失。`.finalized` sidecar 标记该 session 已正常结束，collectRecords
-// 重建时可用它区分「正常结束但文件截断」与「执行中断」。
-//
-// 设计：对称 cancelled sidecar（tombstone-store.ts）。`.finalized` 为空文件，
-// 存在性即信号（done/failed 的细分仍靠 recon.stopReason 推断）。与 `.cancelled`
-// 互斥——一个 session 要么 finalized 要么 cancelled，不可能两者兼有。
-//
-// best-effort：写 IO 错静默，不阻断主流程。
-
-import * as fs from "node:fs";
-
-// ============================================================
-// 公开函数
-// ============================================================
-
-/**
- * 在 session.jsonl 旁写 `.finalized` sidecar（空文件）。
- * best-effort：任何 I/O 错误静默（finalize 标记是次要信号，status 已在内存 record 上设好）。
- *
- * 与 `.cancelled` 互斥（BC-4）：写前删除 `.cancelled`（如存在），确保不会两者共存。
- */
-export function writeFinalized(sessionFile: string): void {
-  try {
-    // BC-4 互斥：清理可能存在的 .cancelled。force:true 静默 ENOENT——
-    // 未 cancel 过的 session（done/failed/aborted）本就无 .cancelled，属正常路径。
-    // 此前用 unlinkSync+bestEffort 记 console.debug，取消嵌套链条时每层 ENOENT 刷屏。
-    fs.rmSync(`${sessionFile}.cancelled`, { force: true });
-    fs.writeFileSync(`${sessionFile}.finalized`, "", "utf-8");
-  } catch (_e) {
-    void _e; // 静默：写失败不阻断 finalize 主流程。
-  }
-}
-
-/**
- * 读 session.jsonl 旁的 `.finalized` sidecar。
- * 返回 true：sidecar 存在（内容不校验，存在性即信号）。
- * 返回 false：sidecar 不存在 / 读取失败。
- */
-export function readFinalized(sessionFile: string): boolean {
-  try {
-    fs.accessSync(`${sessionFile}.finalized`);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/execution/get-state-handshake.ts

@@ -1,104 +0,0 @@
-// src/execution/get-state-handshake.ts
-//
-// FR-4: get_state RPC 握手逻辑。
-//
-// 从 session-runner.ts 提取（保持文件 < 1000 行）。职责单一：通过 get_state RPC
-// 查询子进程 sessionFile/sessionId，带超时重试。session-runner spawn 后无条件调用。
-//
-// 设计要点：
-//   - 重试节奏：单次超时 GET_STATE_TIMEOUT_MS（2s）后，等 GET_STATE_RETRY_INTERVAL_MS（500ms）
-//     再发起下一次 get_state，最多 GET_STATE_MAX_RETRIES（3）次。修复点：旧实现超时后
-//     立即递归 tryOnce()，GET_STATE_RETRY_INTERVAL_MS 声明了却从未使用（eslint error 阻断），
-//     现在让常量名与行为一致——重试前真的等间隔。
-//   - 加速路径：sessionFile 一旦拿到立即 resolve（不等剩余重试）。
-//   - 全部超时：resolve 空对象（调用方走兜底查找）。
-
-import type { ChildProcess } from "node:child_process";
-
-import { sendGetStateCommand } from "./stdin-writer.ts";
-
-/** FR-4: get_state RPC 握手最大重试次数。 */
-const GET_STATE_MAX_RETRIES = 3;
-/** FR-4: get_state RPC 握手重试间隔（ms）——单次超时后等待此间隔再重试。 */
-const GET_STATE_RETRY_INTERVAL_MS = 500;
-/** FR-4: get_state RPC 握手单次超时（ms）。 */
-const GET_STATE_TIMEOUT_MS = 2000;
-
-/** get_state 握手结果。 */
-export interface GetStateResult {
-  sessionFile?: string;
-  sessionId?: string;
-}
-
-/**
- * FR-4: 通过 get_state RPC 查询子进程获取 sessionFile/sessionId。
- *
- * 当 stdout header 未获取到 sessionFile 时，尝试通过 get_state RPC 查询。
- * 最多重试 GET_STATE_MAX_RETRIES 次，单次超时 GET_STATE_TIMEOUT_MS 后等待
- * GET_STATE_RETRY_INTERVAL_MS 再发起下一次重试。
- *
- * @param child 子进程（stdin 写入 get_state 命令）
- * @param addResponseListener 注册 response 监听器的函数（stdout pump 中调用）
- * @returns 握手结果（可能为空——所有重试均超时/失败）
- */
-export function performGetStateHandshake(
-  child: ChildProcess,
-  addResponseListener: (id: string, resolver: (data: unknown) => void) => void,
-): Promise<GetStateResult> {
-  return new Promise<GetStateResult>((resolve) => {
-    const collected: GetStateResult = {};
-    let attempts = 0;
-    let resolved = false;
-
-    function tryOnce(): void {
-      if (resolved) return;
-      attempts++;
-      const reqId = sendGetStateCommand(child);
-
-      // [#15] 本次 tryOnce 私有的 timer（2s 超时 + 超时后派生的 retry）。
-      // 关键：response 回调通过闭包引用的是"本次 tryOnce 对应的 timer"，而非某个
-      // 外层共享变量——即便后续 tryOnce(#2) 重新发起请求，旧 reqId 的迟到 response 回调
-      // 闭包仍指向它自己那次 tryOnce 的 timer，不会误清新 reqId 的 timer。retry 句柄也
-      // 一并捕获，response 到达时同步取消"已在排队但尚未触发的下一次重试"。
-      let pendingRetry: ReturnType<typeof setTimeout> | undefined;
-      const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
-        pendingRetry = undefined;
-        // 单次超时：等待间隔后重试，或放弃
-        if (attempts < GET_STATE_MAX_RETRIES && !resolved) {
-          // [Bug fix] 旧实现直接 tryOnce() 立即重试，GET_STATE_RETRY_INTERVAL_MS 声明却
-          // 从未使用（eslint error 阻断 commit）。现在重试前等待间隔，让常量名与行为一致。
-          pendingRetry = setTimeout(() => tryOnce(), GET_STATE_RETRY_INTERVAL_MS);
-          pendingRetry.unref();
-        } else if (!resolved) {
-          resolved = true;
-          resolve(collected);
-        }
-      }, GET_STATE_TIMEOUT_MS);
-      timer.unref();
-
-      addResponseListener(reqId, (data: unknown) => {
-        if (resolved) return;
-        // [#15] 闭包清理本次 tryOnce 的 timer（2s 超时 + 排队中的 retry），不碰其他 reqId 的 timer。
-        clearTimeout(timer);
-        if (pendingRetry) clearTimeout(pendingRetry);
-        if (data && typeof data === "object") {
-          const d = data as Record<string, unknown>;
-          if (typeof d.sessionFile === "string" && d.sessionFile.length > 0) {
-            collected.sessionFile = d.sessionFile;
-          }
-          if (typeof d.sessionId === "string" && d.sessionId.length > 0) {
-            collected.sessionId = d.sessionId;
-          }
-        }
-        // sessionFile 已获取——立即 resolve（无需更多重试）
-        if (collected.sessionFile) {
-          resolved = true;
-          resolve(collected);
-        }
-        // 否则等待超时重试
-      });
-    }
-
-    tryOnce();
-  });
-}

package/src/execution/host-mode.ts

@@ -1,56 +0,0 @@
-// src/execution/host-mode.ts
-//
-// 主进程运行模式分类工具。
-//
-// 将 Pi 的 ExtensionMode（"tui"|"rpc"|"json"|"print"）聚合为业务语义的
-// HostMode（"tui"|"gui"|"headless"），供 session-runner 的 W4 提示词守卫、
-// handler 工厂分流、stdio 选择等消费点统一调用。
-//
-// 判定依据见 AGENTS.md「运行时环境区分」章节 +
-// docs/extensions/pi-tui-development-guide.md 第四部分第 8 节。
-// ExtensionMode 来自 Pi 源码 packages/coding-agent/src/core/extensions/types.ts:299
-// （dist 中 core/extensions/types.d.ts:207）。
-//
-// 设计动机（.fix-plans/00-master-summary.md §一冲突 4）：
-//   - 把散落多处的 `ctx.mode === "tui" || ctx.mode === "rpc"` 字面量比较
-//     集中到单一修改点，未来 Pi 新增 mode 值时只改本文件。
-//   - 业务语义命名（"gui"/"headless"）比原始枚举值更清晰表达意图。
-
-// ExtensionMode 在 Pi SDK 的 core/extensions/types.d.ts 中定义为
-// `"tui" | "rpc" | "json" | "print"`（ExtensionContext.mode 的类型），但未从包根
-// 导出。这里定义与 SDK 同构的本地别名（ctx.mode 的字面量联合），由同包其他模块复用，
-// 避免依赖未导出的内部类型。
-export type ExtensionMode = "tui" | "rpc" | "json" | "print";
-
-/** 主进程运行模式分类。基于 ExtensionMode 聚合为业务语义。
- *  - "tui"：纯 Pi TUI，ctx.ui.custom 可用，用户在终端交互
- *  - "gui"：xyz-agent GUI，通过 rpc sidecar 通道与前端 Vue 组件交互
- *  - "headless"：无交互 UI 通道（json/print 输出模式，或 mode 未穿透） */
-export type HostMode = "tui" | "gui" | "headless";
-
-/** 从 ExtensionContext.mode 解析主进程模式分类。
- *  - "tui" → tui（纯 Pi TUI，ctx.ui.custom 可用）
- *  - "rpc" → gui（xyz-agent GUI，sidecar 通道可用）
- *  - "json"/"print"/undefined → headless（无交互通道）
- *
- *  undefined 归入 headless 是向后兼容：mode 未穿透 SessionRunnerContext 时
- *  按「无 UI」保守处理，避免误注入依赖 UI 的逻辑。 */
-export function resolveHostMode(mode: ExtensionMode | undefined): HostMode {
-  if (mode === "tui") return "tui";
-  if (mode === "rpc") return "gui";
-  return "headless"; // json/print/undefined
-}
-
-/** 主进程是否会响应子进程的 ask_user（UI 透传）。
- *  tui + gui 都会（冲突 3 裁决：TUI 必须注入 handler；GUI 透传所有 UI），
- *  headless 不会（无 UI 通道，注入 W4 提示词会误导 LLM）。 */
-export function willRespondToAskUser(mode: ExtensionMode | undefined): boolean {
-  const host = resolveHostMode(mode);
-  return host === "tui" || host === "gui";
-}
-
-/** 主进程是否有交互 UI 通道（TUI 组件 / GUI sidecar）。
- *  非 headless 即有。用于 stdio 选择等不区分 tui/gui 的决策点。 */
-export function hasInteractiveUI(mode: ExtensionMode | undefined): boolean {
-  return resolveHostMode(mode) !== "headless";
-}

package/src/execution/idle-gc.ts

@@ -1,47 +0,0 @@
-/**
- * SP-4 idle record GC：30 天 TTL 定时归档，防 idle record 永久驻留内存。
- * 从 subagent-service.ts 抽出（文件超 max-lines；逻辑自包含：interval + TTL 扫描）。
- * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
- */
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-import { bestEffort } from "./best-effort.ts";
-import { isResumable } from "./lifecycle-predicates.ts";
-import type { RecordStore } from "./record-store.ts";
-
-const logger = getLogger("subagents");
-
-/** GC 扫描间隔：1 小时。 */
-// eslint-disable-next-line no-magic-numbers -- 60*60*1000 = 1h 的毫秒换算常数
-const GC_INTERVAL_MS = 60 * 60 * 1000;
-/** idle record TTL：30 天（超龄归档）。 */
-// eslint-disable-next-line no-magic-numbers -- 30*24*60*60*1000 = 30d 的毫秒换算常数
-const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-/** 毫秒/天（GC 日志的 d 换算）。 */
-// eslint-disable-next-line no-magic-numbers -- 24*60*60*1000 = 1d 的毫秒换算常数
-const MS_PER_DAY = 24 * 60 * 60 * 1000;
-
-/**
- * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
- * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
- * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
- */
-export function startIdleGc(store: RecordStore): () => void {
-  const timer = setInterval(() => {
-    const now = Date.now();
-    for (const record of store.listAllActive()) {
-      if (isResumable(record) && record.idleSince) {
-        const age = now - record.idleSince;
-        if (age > IDLE_TTL_MS) {
-          logger.warn(`[subagents] GC: archiving idle record ${record.id} (idle for ${Math.round(age / MS_PER_DAY)}d)`);
-          try {
-            store.archive(record);
-          } catch (err) {
-            bestEffort(err, `GC archive record ${record.id}`);
-          }
-        }
-      }
-    }
-  }, GC_INTERVAL_MS);
-  timer.unref?.();
-  return () => clearInterval(timer);
-}