@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

package/src/execution/__tests__/finalize-record.test.ts

@@ -25,7 +25,7 @@ vi.mock("@zhushanwen/pi-extension-logger", () => ({
   getLogger: () => loggerMock,
 }));
 
-import { doFinalizeRecord } from "../finalize-record.ts";
+import { doFinalizeRecord, doFinalizeRoundToIdle } from "../finalize-record.ts";
 import { ManifestStore } from "../manifest-store.ts";
 import type { AgentResult, ExecutionRecord } from "../types.ts";
 
@@ -86,38 +86,37 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     return {
       manifestStore,
       worktreeManager: {} as never,
-      store: { archive: vi.fn() } as never,
+      store: { archive: vi.fn(), reportRecordTransition: vi.fn() } as never,
       modelService: {} as never,
       pi: { appendEntry: vi.fn() },
-      clearThrottle: vi.fn(),
       emitUnregister: vi.fn(),
     };
   }
 
-  it("status=cancelled → manifest 写 cancelled（不再归并 failed）", async () => {
+  it("status=closed + cancelled reason → manifest 写 closed（v4 B-1：cancelled 折入 closed）", async () => {
     const record = makeMinimalRecord({ id: "rec-cancelled" });
-    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "cancelled");
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "cancelled");
 
     const manifest = await manifestStore.readManifest("rec-cancelled");
     expect(manifest).not.toBeNull();
-    // 关键断言：cancelled 直接透传,不是 "failed"
-    expect(manifest?.status).toBe("cancelled");
+    // 关键断言：v4 B-1 manifest status 恒写 closed（cancelled 区分靠 tombstone sidecar）
+    expect(manifest?.status).toBe("closed");
   });
 
-  it("status=done → manifest 写 completed", async () => {
+  it("status=closed + user-close → manifest 写 closed", async () => {
     const record = makeMinimalRecord({ id: "rec-done" });
-    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "done");
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "user-close");
 
     const manifest = await manifestStore.readManifest("rec-done");
-    expect(manifest?.status).toBe("completed");
+    expect(manifest?.status).toBe("closed");
   });
 
-  it("status=failed → manifest 写 failed", async () => {
+  it("status=closed + gc → manifest 写 closed", async () => {
     const record = makeMinimalRecord({ id: "rec-failed" });
-    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "failed");
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "gc");
 
     const manifest = await manifestStore.readManifest("rec-failed");
-    expect(manifest?.status).toBe("failed");
+    expect(manifest?.status).toBe("closed");
   });
 
   it("manifest write 抛错时 cleanup-first 顺序仍执行（Step 3 before Step 4 throw）", async () => {
@@ -148,7 +147,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
 
     // ── 核心 claim 1：不抛错（cleanup-first → manifest write 失败不 throw）──
     await expect(
-      doFinalizeRecord(deps, record, makeMinimalResult(), "done"),
+      doFinalizeRecord(deps, record, makeMinimalResult(), "closed"),
     ).resolves.toBeUndefined();
 
     // ── 核心 claim 2：Step 3 cleanup 先执行 —— finalized marker 真实写入 ──
@@ -158,7 +157,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
 
     // ── 核心 claim 4：pending-notifications 注销仍触发（emitUnregister）──
-    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-cleanup-first", "done");
+    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-cleanup-first", "closed");
 
     // ── 核心 claim 5：manifest 写失败被 logger.error 记录（含 record id + error）──
     expect(loggerMock.error).toHaveBeenCalledWith(expect.stringContaining("manifest 写入失败"));
@@ -184,3 +183,186 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     loggerMock.error.mockClear();
   });
 });
+
+// ============================================================
+// doFinalizeRoundToIdle — chatMode 轮次完成进 idle（M2-A）
+// ============================================================
+
+describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () => {
+  let tmpDir: string;
+  let manifestStore: ManifestStore;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "finalize-idle-test-"));
+    manifestStore = new ManifestStore(tmpDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  /** 构造 FinalizeDeps：worktreeManager.cleanup / store.archive 为 vi.fn 以断言「不调」。 */
+  function makeDeps() {
+    return {
+      manifestStore,
+      worktreeManager: { cleanup: vi.fn(), collectPatch: vi.fn() } as never,
+      store: { archive: vi.fn(), reportRecordTransition: vi.fn() } as never,
+      modelService: {} as never,
+      pi: { appendEntry: vi.fn() } as never,
+      emitUnregister: vi.fn(),
+    };
+  }
+
+  it("record 带 sessionFile → 删 .alive + record.status=running + round 0→1", async () => {
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    // 预写 .alive marker（验证 doFinalizeRoundToIdle 删除它——进程已回收）
+    fs.writeFileSync(
+      `${sessionFile}.alive`,
+      `${JSON.stringify({ pid: 99999, id: "rec-idle", startedAt: 1000 })}\n`,
+      "utf-8",
+    );
+    const record = makeMinimalRecord({ id: "rec-idle", sessionFile, chatMode: true, round: 0 });
+    // tryTransition 已把 status 设为 done，模拟 runAndFinalize 调用前的状态
+    record.status = "closed";
+
+    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+
+    // 状态机（v4 B-1：旧 idle 折入 running，finalizeRoundToIdle 设 running）
+    expect(record.status).toBe("running");
+    expect(record.round).toBe(1);
+    // .alive marker 被删（进程已 SIGTERM 回收）
+    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
+  });
+
+  it("W16: 轮终上报 reportRecordTransition（record-store 类外恢复写点迁移落 entry）", async () => {
+    const deps = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-report", chatMode: true, round: 2 });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
+    expect(deps.store.reportRecordTransition).toHaveBeenCalledTimes(1);
+    // 上报发生在 round 推进之后（entry 携带新轮计数，重建源不滞后）
+    expect(record.round).toBe(3);
+    expect(record.status).toBe("running");
+  });
+
+  it("record.round 已为 N → round 变 N+1", async () => {
+    const record = makeMinimalRecord({ id: "rec-round", round: 3 });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    expect(record.round).toBe(4);
+    expect(record.status).toBe("running");
+  });
+
+  it("不调 store.archive（record 留内存，getMutable 仍可查）", async () => {
+    const deps = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-noarchive" });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
+    expect(deps.store.archive).not.toHaveBeenCalled();
+  });
+
+  it("不 cleanup worktree（即使 record 带 worktreeHandle——保留对话模式工作目录）", async () => {
+    const deps = makeDeps();
+    const record = makeMinimalRecord({
+      id: "rec-noworktree",
+      worktreeHandle: { path: "/tmp/x", branch: "b", baseCommit: "c", mainCwd: "/tmp" } as never,
+    });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
+    expect(deps.worktreeManager.cleanup).not.toHaveBeenCalled();
+  });
+
+  it("emitUnregister 被调（status=running，进程已死从 pending 活跃差集移除）", async () => {
+    const deps = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-emit" });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
+    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-emit", "running");
+  });
+
+  it("不调 completeRecord：record 不冻结（endedAt / agentResult 仍 undefined）", async () => {
+    const record = makeMinimalRecord({ id: "rec-nofreeze" });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    expect(record.endedAt).toBeUndefined();
+    expect(record.agentResult).toBeUndefined();
+  });
+
+  it("不写 manifest（idle 非终态，manifest 是终态诊断辅助）", async () => {
+    const record = makeMinimalRecord({ id: "rec-nomanifest" });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(makeDeps(), record, makeMinimalResult());
+    const manifest = await manifestStore.readManifest("rec-nomanifest");
+    expect(manifest).toBeNull();
+  });
+
+  it("MF-2: record.result 设为 result.text（否则 notifier idle 回复恒为 (empty)，G1/G2 不成立）", async () => {
+    const record = makeMinimalRecord({ id: "rec-result" });
+    record.status = "closed";
+    const result = makeMinimalResult();
+    result.text = "review done, found 3 issues";
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // MF-2：record.result 被 result.text 填充，notifier idle 分支读取后携带回复正文
+    expect(record.result).toBe("review done, found 3 issues");
+  });
+
+  it("MF-2 兑底：失败轮次 result.text 为空时用 result.error 填 record.result（MF-6 回退 idle 路径）", async () => {
+    const record = makeMinimalRecord({ id: "rec-result-err" });
+    record.status = "closed";
+    const result = makeMinimalResult();
+    result.text = "";
+    result.success = false;
+    result.error = "spawn timeout";
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // 失败轮次的 notify 需可读：result.text 空 → 兑底用 error
+    expect(record.result).toBe("round did not complete: spawn timeout");
+  });
+
+  it("C1TC10: chatMode 空增量轮占位——record.result 固定 (no output this round)，不含上一轮文本（D5）", async () => {
+    const record = makeMinimalRecord({ id: "rec-increment-empty", chatMode: true });
+    record.status = "closed";
+    // 预置上一轮通知文本（模拟增量语义前的 record.result 残留）
+    record.result = "PREV-ROUND-TEXT";
+    const result = makeMinimalResult();
+    result.text = "";
+    result.success = true;
+    result.error = undefined;
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // 空增量轮通知不含上一轮文本：沿用旧值会让父 agent 误读为原样重复回复（D5 判定）
+    expect(record.result).toBe("(no output this round)");
+    expect(record.result).not.toContain("PREV-ROUND-TEXT");
+  });
+
+  it("C1TC11 [R2-1]: one-shot 首轮空文本成功完成 → record.result 补占位「(empty)」（非 undefined）", async () => {
+    const record = makeMinimalRecord({ id: "rec-oneshot-empty", chatMode: false });
+    record.status = "closed";
+    // one-shot 成功空文本完成路径（collectResult getFullText 返回 ""、success=true）：
+    // result 前值 undefined
+    record.result = undefined;
+    const result = makeMinimalResult();
+    result.text = "";
+    result.success = true;
+    result.error = undefined;
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // [R2-1] 轮终信号优先：占位非 undefined 是 renderer hasRunning 排除轮终 running 的
+    // 判据——保持 undefined 会让完成注入后末位 turn 永久「工作中」
+    expect(record.result).toBe("(empty)");
+    // notifier buildLlmContent 的 record.result ?? "(empty)" 兜底同款措辞：
+    // 通知文案逐字节产出 "completed. Result:\n(empty)"（G4 保持）
+    expect(record.result ?? "(empty)").toBe("(empty)");
+  });
+
+  it("C1TC11b [R2-1]: one-shot 续轮空文本 → 沿用前值（one-shot 无增量语义，不覆盖为占位）", async () => {
+    const record = makeMinimalRecord({ id: "rec-oneshot-cont", chatMode: false });
+    record.status = "closed";
+    // 上一轮真实产出（续轮 record.result 前值）
+    record.result = "first round output";
+    const result = makeMinimalResult();
+    result.text = "";
+    result.success = true;
+    result.error = undefined;
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // one-shot record.result = 该 subagent 最终输出：空文本续轮沿用前值，不被 "(empty)" 覆盖
+    expect(record.result).toBe("first round output");
+  });
+});

package/src/execution/__tests__/format.test.ts

@@ -70,15 +70,11 @@ describe("statusGlyph", () => {
   });
 
   it("done → checkmark, success", () => {
-    expect(statusGlyph("done")).toEqual({ icon: "✓", color: "success" });
+    expect(statusGlyph("closed")).toEqual({ icon: "✓", color: "success" });
   });
 
-  it("failed → cross, error", () => {
-    expect(statusGlyph("failed")).toEqual({ icon: "✗", color: "error" });
-  });
-
-  it("cancelled → square, muted", () => {
-    expect(statusGlyph("cancelled")).toEqual({ icon: "■", color: "muted" });
+  it("closed → checkmark, success", () => {
+    expect(statusGlyph("closed")).toEqual({ icon: "✓", color: "success" });
   });
 });
 
@@ -260,6 +256,134 @@ describe("truncLine", () => {
   });
 });
 
+// ============================================================
+// truncLine — legacy 对拍（indexOf 化重构的逐字节等价锚定）
+// ============================================================
+
+/**
+ * 旧实现参照：改造前的 per-char 版本，逐字取自 git 历史（093e28fe3~1 的
+ * format.ts truncLine）。现行实现（indexOf("\\x1b") 段跳过）必须与其逐字节
+ * 等价——本函数即对拍 oracle，与 helpers-bounded-serialize.test.ts 的
+ * legacySerialize 同形态（参照物随测试落盘，防「验证只存在于改造当时」）。
+ */
+const legacySegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+function legacyTruncLine(text: string, maxWidth: number): string {
+  if (maxWidth <= 0) return "";
+  const flat = text.replace(/[\r\n]+/g, " ");
+  if (visibleWidth(flat) <= maxWidth) return flat;
+
+  const targetWidth = Math.max(0, maxWidth - 1);
+  let result = "";
+  let currentWidth = 0;
+  let activeStyles: string[] = [];
+  let i = 0;
+
+  while (i < flat.length) {
+    // 捕获 ANSI SGR 序列
+    const ansiMatch = flat.slice(i).match(/^\x1b\[[0-9;]*m/);
+    if (ansiMatch) {
+      const code = ansiMatch[0];
+      result += code;
+
+      if (code === "\x1b[0m" || code === "\x1b[m") {
+        activeStyles = []; // reset → 清空栈
+      } else {
+        activeStyles.push(code);
+      }
+      i += code.length;
+      continue;
+    }
+
+    // 找到下一段纯文本(非 ANSI)的边界
+    let end = i;
+    while (end < flat.length && !flat.slice(end).match(/^\x1b\[[0-9;]*m/)) {
+      end++;
+    }
+
+    // 按 grapheme 迭代这段文本,累加到 targetWidth
+    const textPortion = flat.slice(i, end);
+    for (const seg of legacySegmenter.segment(textPortion)) {
+      const grapheme = seg.segment;
+      const graphemeWidth = visibleWidth(grapheme);
+
+      if (currentWidth + graphemeWidth > targetWidth) {
+        return result + activeStyles.join("") + "…" + (activeStyles.length ? "\x1b[0m" : "");
+      }
+
+      result += grapheme;
+      currentWidth += graphemeWidth;
+    }
+    i = end;
+  }
+
+  // 理论上 visibleWidth 检查已提前返回,此行兜底
+  return result + activeStyles.join("") + "…" + (activeStyles.length ? "\x1b[0m" : "");
+}
+
+/** 确定性 PRNG（mulberry32）：fuzz 用例固定 seed 生成，失败可按 case 编号 + seed 复现。 */
+function mulberry32(seed: number): () => number {
+  let s = seed | 0;
+  return () => {
+    s = (s + 0x6d2b79f5) | 0;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** 定向混排片段池：ASCII / CJK / emoji（含肤色修饰与 ZWJ 组合）/ SGR / 非 SGR ESC（OSC、CSI-K、裸 ESC）/ 换行。 */
+const FUZZ_PIECES = [
+  "plain", " ", "a", "0", "MiXeD-Case_123",
+  "你好世界", "汉字宽度测试", "日本語テキスト",
+  "😀", "😁😂🤣", "👍🏽", "👨‍👩‍👧‍👦", "é", "é",
+  "\x1b[31m", "\x1b[0m", "\x1b[m", "\x1b[1;32m", "\x1b[38;5;196m",
+  "\x1b[K", "\x1b]0;title\x07", "\x1bZ", "\x1b",
+  "\n", "\r\n",
+];
+
+function genFuzzText(rand: () => number): string {
+  const pieceCount = Math.floor(rand() * 40);
+  let out = "";
+  for (let p = 0; p < pieceCount; p++) {
+    out += FUZZ_PIECES[Math.floor(rand() * FUZZ_PIECES.length)];
+  }
+  return out;
+}
+
+describe("truncLine — legacy 对拍（per-char 参照逐字节等价）", () => {
+  it("定向 fuzz：300 随机 ESC/SGR/CJK/emoji 混排用例（固定 seed 可复现）与旧实现逐字节一致", () => {
+    const rand = mulberry32(20260815);
+    let truncated = 0;
+    for (let i = 0; i < 300; i++) {
+      const text = genFuzzText(rand);
+      const maxWidth = Math.floor(rand() * 61); // 0..60，含 0/1 边界
+      const actual = truncLine(text, maxWidth);
+      expect(
+        actual,
+        `case #${i} text=${JSON.stringify(text)} maxWidth=${maxWidth}`,
+      ).toBe(legacyTruncLine(text, maxWidth));
+      if (actual.endsWith("…")) truncated++;
+    }
+    // 前置有效性：fuzz 确实命中了截断路径（否则对拍只测了「宽度内原样返回」早退分支）
+    expect(truncated).toBeGreaterThan(100);
+  });
+
+  it("手工对抗用例：SGR 重叠 / OSC 内截断 / CSI-K 混排 / 串尾裸 ESC", () => {
+    const cases: Array<[string, number]> = [
+      ["\x1b[31m红\x1b[32m绿\x1b[1;4m加粗下划线尾巴超宽截断点", 9],
+      ["AB\x1b]0;title\x07CDEFGHIJKLMNOP", 10],
+      ["\x1b[31mred\x1b[K\x1b[32mgreen tail past width", 10],
+      ["text almost at width limit\x1b", 22],
+      ["before \x1bZ after bare esc tail", 12],
+      ["\x1b[m你\x1b[0m好\x1b[38;5;196m世👨‍👩‍👧‍👦界".repeat(3), 14],
+    ];
+    for (const [text, maxWidth] of cases) {
+      expect(truncLine(text, maxWidth)).toBe(legacyTruncLine(text, maxWidth));
+    }
+  });
+});
+
 // ============================================================
 // wrapText
 // ============================================================

package/src/execution/__tests__/gc-timer.test.ts

@@ -0,0 +1,184 @@
+// src/execution/__tests__/gc-timer.test.ts
+//
+// [M8] idle record GC 定时器测试（subagent-service.ts startGcTimer，L485-507）。
+//
+// 背景：GC 定时器（1h interval 扫描 + isResumable && idleSince 30 天 TTL + store.archive）
+// 此前零测试覆盖——所有相关测试把 startGcTimer mock 成 no-op（index-session-start /
+// crash-recovery / stream-sink-guard / session-start-reaper / index-session-start-identity）。
+// 误判 isResumable/idleSince 会把可续聊 record 从内存错误归档（用户数据路径），
+// 或永不触发（内存驻留失效）——两个方向都无回归拦截。
+//
+// 本文件用真实 SubagentService + 真实 startGcTimer（不 mock GC 逻辑本身），仅 mock
+// session-runner（import 链依赖 + isResumable 的 hasLiveProcessHandle 查询点）与 logger。
+// timer 全部 vi.useFakeTimers，不真实等待。
+
+import type { ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({ getLogger: () => loggerMock }));
+
+// mock session-runner：runSpawn/killAllSpawnedChildren 占位（import 链需要），
+// getChildByRecord 默认返回 undefined（无活进程 → isResumable=true），用例内按需覆盖。
+vi.mock("../session-runner.ts", () => ({
+  runSpawn: vi.fn(),
+  killAllSpawnedChildren: vi.fn(),
+  getChildByRecord: vi.fn(() => undefined),
+  spawnedChildren: new Map(),
+}));
+
+import { getChildByRecord } from "../session-runner.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import { RecordStore } from "../record-store.ts";
+import { SubagentService } from "../subagent-service.ts";
+import type { ExecutionRecord } from "../types.ts";
+
+const mockGetChildByRecord = vi.mocked(getChildByRecord);
+
+/** 与 startGcTimer 内部常量一致（1h 扫描 / 30 天 TTL）。 */
+const GC_INTERVAL_MS = 60 * 60 * 1000;
+const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** initSession 注入的最小 pi duck-type（同 subagent-service PiLike 形状，结构匹配即可）。 */
+interface PiStub {
+  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" },
+  ): void;
+}
+
+function makePi(): PiStub {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  };
+}
+
+/** 构造 running + 无活进程 + 指定 idleSince 的 record（GC 扫描的目标态）。
+ *  listAllActive 只返回 status==="running"（createRecord 初始即 running）。 */
+function makeIdleRecord(id: string, idleSince: number): ExecutionRecord {
+  const record = createRecord(id, {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "background",
+    task: "test",
+    slug: "test",
+    startedAt: idleSince,
+    rootSessionId: "root-session",
+    chatMode: true,
+    controller: new AbortController(),
+  });
+  record.idleSince = idleSince;
+  return record;
+}
+
+/** 暴露私有字段供测试读取 store。 */
+interface ServiceInternals {
+  store: RecordStore;
+}
+
+describe("[M8] idle record GC 定时器（startGcTimer）", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "gc-timer-"));
+    const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    service.initSession({ pi: makePi(), sessionId: "root-session" });
+    store = (service as unknown as ServiceInternals).store;
+    mockGetChildByRecord.mockReset();
+    // 默认无活进程（isResumable=true）——Path B：进程已回收、可冷路径 resume 的等待续聊态
+    mockGetChildByRecord.mockImplementation(() => undefined);
+    loggerMock.warn.mockClear();
+  });
+
+  afterEach(() => {
+    service.dispose();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+    vi.useRealTimers();
+  });
+
+  it("TTL 边界：超 1ms 归档、差 1ms 不归档（同一轮扫描）", () => {
+    // idleSince 相对 interval 首次触发时刻（fake clock + 1h）构造：
+    //   over  = fireAt - TTL - 1 → 扫描时 age = TTL + 1 > TTL → archive
+    //   under = fireAt - TTL + 1 → 扫描时 age = TTL - 1 ≤ TTL → 留内存
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    store.register(makeIdleRecord("sa-over", fireAt - IDLE_TTL_MS - 1));
+    store.register(makeIdleRecord("sa-under", fireAt - IDLE_TTL_MS + 1));
+
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+
+    expect(store.getMutable("sa-over")).toBeUndefined(); // archive 从内存移除
+    expect(store.getMutable("sa-under")).toBeDefined(); // 未超 TTL 留内存
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("GC: archiving idle record sa-over"),
+    );
+  });
+
+  it("有活进程的 record 不归档（isResumable=false，即使 idleSince 超 TTL）", () => {
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    // Path A：进程保活等待续聊（idle timer armed、child 未 kill）——归档会让活进程失管
+    store.register(makeIdleRecord("sa-live", fireAt - IDLE_TTL_MS - 1));
+    mockGetChildByRecord.mockImplementation(
+      (id: string): ChildProcess | undefined =>
+        id === "sa-live" ? ({ killed: false } as unknown as ChildProcess) : undefined,
+    );
+
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+
+    expect(store.getMutable("sa-live")).toBeDefined(); // 有活进程 → 不归档
+    expect(loggerMock.warn).not.toHaveBeenCalled();
+  });
+
+  it("每小时重复扫描：上一轮差 1ms 的 record 下一轮超龄被归档", () => {
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    store.register(makeIdleRecord("sa-late", fireAt - IDLE_TTL_MS + 1));
+
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+    expect(store.getMutable("sa-late")).toBeDefined(); // 第一轮：age = TTL - 1，未到
+
+    vi.advanceTimersByTime(GC_INTERVAL_MS); // 第二轮：age = TTL + 1h - 1 > TTL
+    expect(store.getMutable("sa-late")).toBeUndefined();
+  });
+
+  it("startGcTimer 幂等：重复调用不产生第二个 interval", () => {
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    store.register(makeIdleRecord("sa-over", fireAt - IDLE_TTL_MS - 1));
+
+    service.startGcTimer();
+    service.startGcTimer(); // 已有 timer 直接 return（防重复 interval）
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+
+    // 同一 record 一轮只扫一次（重复 interval 会对同一 record 产生第二条 GC warn）
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("dispose 后 interval 停止：超 TTL record 不再被归档", () => {
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS); // 第一轮正常触发
+    service.dispose(); // stopGcTimer + disposeAllRecords
+
+    // dispose 后塞入超 TTL record，interval 已停 → 无论推进多久都不归档
+    store.register(makeIdleRecord("sa-after-dispose", Date.now() - IDLE_TTL_MS - 1));
+    vi.advanceTimersByTime(GC_INTERVAL_MS * 10);
+
+    expect(store.getMutable("sa-after-dispose")).toBeDefined();
+  });
+});