@zhushanwen/subagent-core 0.2.0

package/src/execution/__tests__/run-spawn-stdout-callback-throw.test.ts

@@ -0,0 +1,199 @@
+// src/execution/__tests__/run-spawn-stdout-callback-throw.test.ts
+//
+// [F-R2] stdout data 同步回调链内 fail-fast throw 不逃逸（不升级为 uncaughtException 崩宿主）。
+//
+// 背景：session-runner 的两处 timer 安全校验调用位于 child.stdout.on("data") 同步回调链内：
+//   ① agent_end keep-alive 分支的 resolveSpawnWatchdogMs（→ assertSafeTimerDelay fail-fast）
+//   ② chatMode agent_settled 分支的 armIdleTimer（→ assertSafeTimerDelay fail-fast）
+// 旧实现任一处 throw 都会逃出事件回调 = Node uncaughtException 崩宿主进程。
+// 修复：调用点包 try/catch 降级（不挂 timer），错误经 bestEffort("error") 可见。
+//
+// mock 结构与 run-spawn-chatmode-settled.test.ts 一致（FakeChild + lifecycle-manager 真实模块）。
+// logger 整体 mock（loggerMock spy）断言错误可见——「fail-fast 语义保留（错误可见、行为明确）
+// 但不升级为进程崩溃」。
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// logger mock：bestEffort / session-runner 共享同一 loggerMock（断言错误可见性）。
+// vi.hoisted：vi.mock 工厂被提升到顶层 const 之前执行，loggerMock 必须经 vi.hoisted 创建。
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+vi.mock("node:child_process", async () => {
+  const { FakeChild } = await import("./helpers/spawn-mock.ts");
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    // buildEnvBlock 的 git branch 调用（execFile 异步）：默认 err-first 兜底 → catch → branch=""
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: readonly string[],
+        _opts: unknown,
+        cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+      ) => cb(new Error("execFile not configured in this test")),
+    ),
+  };
+});
+
+vi.mock("node:fs", async () => {
+  const actual = await import("node:fs");
+  return {
+    default: {
+      ...actual,
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      appendFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+    },
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    promises: actual.promises,
+  };
+});
+
+vi.mock("../alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+}));
+
+// 场景 ① 依赖 keep-alive 分支命中：count=1（有活跃后代 → 不 kill → 重挂 watchdog）
+vi.mock("../session-pending.ts", () => ({
+  readActivePendingFromSessionFile: vi.fn(() => ({ count: 1 })),
+}));
+
+vi.mock("../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string) => {
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { runSpawn, SPAWN_WATCHDOG_ENV } from "../session-runner.ts";
+import type { SessionRunnerContext } from "../session-runner.ts";
+import { hasIdleTimer, _resetLifecycleState } from "../lifecycle-manager.ts";
+import { createRecord } from "../execution-record.ts";
+import type { ExecutionRecord } from "../types.ts";
+import {
+  emitStdoutLine,
+  type FakeChild,
+  lastSpawnedChild as lastSpawnedChildOf,
+  makeCtx,
+  makeOpts,
+  makeRecord,
+  sessionHeader,
+  waitForSpawn as waitForSpawnOf,
+} from "./helpers/spawn-mock.ts";
+
+const mockSpawn = vi.mocked(spawn);
+
+const lastSpawnedChild = (): FakeChild => lastSpawnedChildOf(mockSpawn);
+const waitForSpawn = (timeoutMs = 1000): Promise<void> => waitForSpawnOf(mockSpawn, timeoutMs);
+
+/** 构造 chatMode record（idleTimeoutMs 设为超出 setTimeout 安全域的值 → assertSafeTimerDelay throw）。 */
+function makeChatModeRecord(id = "sa-f2-idle"): ExecutionRecord {
+  return createRecord(id, {
+    agent: "general-purpose",
+    model: "test-model",
+    mode: "sync",
+    task: "chat task",
+    slug: "chat",
+    startedAt: 1_000_000,
+    rootSessionId: "root-session",
+    parentRecordId: undefined,
+    depth: 0,
+    chatMode: true,
+    // > 2^31-1：Node setTimeout 溢出域，assertSafeTimerDelay fail-fast
+    idleTimeoutMs: Number.MAX_SAFE_INTEGER,
+  });
+}
+
+describe("[F-R2] stdout 回调链内 fail-fast throw 不逃逸", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    _resetLifecycleState();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    _resetLifecycleState();
+  });
+
+  it("① agent_end keep-alive 分支 resolveSpawnWatchdogMs throw → 降级不 re-arm，run 正常收尾，error 可见", async () => {
+    const record = makeRecord();
+    const promise = runSpawn(record, "Task: keepalive", makeOpts(), makeCtx());
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    emitStdoutLine(child, sessionHeader("sess-fr2a"));
+    // 初始 watchdog 解析在 spawn 后同步块内已完成（env 未设 → 不挂）。
+    // 此刻设非法 env：agent_end keep-alive 分支再读 env → assertSafeTimerDelay throw。
+    process.env[SPAWN_WATCHDOG_ENV] = String(Number.MAX_SAFE_INTEGER);
+    try {
+      emitStdoutLine(child, { type: "agent_end", willRetry: false });
+      // 给 stream flush 留一个 tick（对齐 chatmode 测试模式）：throw 若逃逸回调，
+      // vitest 会以 unhandled error 判本测试失败——能走到断言即「未崩宿主」。
+      await new Promise((r) => setTimeout(r, 20));
+
+      // 降级语义：不 re-arm（无 timer 可直接观察的是——子进程未被 kill、run 未被中断）
+      expect(child.killed).toBe(false);
+
+      // 错误可见（fail-fast 语义保留）：bestEffort("error") 经 logger.error 落日志
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        expect.stringContaining("resolveSpawnWatchdogMs"),
+        expect.objectContaining({ detail: expect.stringContaining("exceeds the Node setTimeout limit") }),
+      );
+
+      // 收尾：run 正常完成（未被回调异常打断）
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+      const result = await promise;
+      expect(result.success).toBe(true);
+    } finally {
+      delete process.env[SPAWN_WATCHDOG_ENV];
+    }
+  });
+
+  it("② chatMode agent_settled armIdleTimer throw → 降级不挂 idle timer，onRoundSettled 照常、提前 resolve", async () => {
+    const record = makeChatModeRecord("sa-f2-idle");
+    const onRoundSettled = vi.fn();
+    const ctx: Partial<SessionRunnerContext> = { onRoundSettled };
+    const promise = runSpawn(record, "Task: idle", makeOpts(), makeCtx(ctx as SessionRunnerContext));
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    emitStdoutLine(child, sessionHeader("sess-fr2b"));
+    emitStdoutLine(child, { type: "agent_settled" });
+    await new Promise((r) => setTimeout(r, 20));
+
+    // 降级语义：idle timer 未挂（throw 发生在 arm 入口校验，先于 setTimeout）
+    expect(hasIdleTimer(record.id)).toBe(false);
+    expect(child.killed).toBe(false);
+
+    // catch 后续语句照常执行：本轮完成通知不因 GC timer 故障丢失
+    expect(onRoundSettled).toHaveBeenCalledTimes(1);
+
+    // 错误可见
+    expect(loggerMock.error).toHaveBeenCalledWith(
+      expect.stringContaining("armIdleTimer"),
+      expect.objectContaining({ detail: expect.stringContaining("exceeds the Node setTimeout limit") }),
+    );
+
+    // 收尾：chatMode 首轮 agent_settled 已 resolveRun(0)，close 后 runSpawn 正常返回
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 0);
+    const result = await promise;
+    expect(result.success).toBe(true);
+  });
+});

package/src/execution/__tests__/session-context-resolver.test.ts

@@ -0,0 +1,167 @@
+// src/__tests__/session-context-resolver.test.ts
+//
+// 覆盖 resolveSessionContext 全部 5 种输入组合 + ForkDepthExceededError 边界。
+import * as path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { encodeCwd } from "../path-encoding.ts";
+import { resolveSessionContext } from "../session-context-resolver.ts";
+import { ForkDepthExceededError } from "../types.ts";
+
+const AGENT_DIR = "/home/user/.pi/agent";
+const MAIN_CWD = "/home/user/project";
+const SESSION_FILE = "session-abc.jsonl";
+
+function expectedSessionDir(mainCwd: string): string {
+  // [MF#1] 既有布局：subagents/<enc>/sessions/
+  return path.join(AGENT_DIR, "subagents", encodeCwd(mainCwd), "sessions");
+}
+
+describe("resolveSessionContext", () => {
+  // ── 边界 1: fork=false, worktree=false ──
+  it("fork=false, worktree=false → shouldFork=false, effectiveCwd=mainCwd", () => {
+    const result = resolveSessionContext({
+      fork: false,
+      worktree: false,
+      mainCwd: MAIN_CWD,
+      agentDir: AGENT_DIR,
+    });
+    expect(result.shouldFork).toBe(false);
+    expect(result.forkSource).toBeUndefined();
+    expect(result.effectiveCwd).toBe(MAIN_CWD);
+    expect(result.sessionDir).toBe(expectedSessionDir(MAIN_CWD));
+  });
+
+  // ── 边界 2: fork=true, worktree=false ──
+  it("fork=true, worktree=false → shouldFork=true, forkSource=mainSessionFile", () => {
+    const result = resolveSessionContext({
+      fork: true,
+      worktree: false,
+      mainCwd: MAIN_CWD,
+      mainSessionFile: SESSION_FILE,
+      agentDir: AGENT_DIR,
+    });
+    expect(result.shouldFork).toBe(true);
+    expect(result.forkSource).toBe(SESSION_FILE);
+    expect(result.effectiveCwd).toBe(MAIN_CWD);
+    expect(result.sessionDir).toBe(expectedSessionDir(MAIN_CWD));
+  });
+
+  // ── 边界 3: fork=false, worktree=true ──
+  it("fork=false, worktreePath 提供 → effectiveCwd=worktreePath", () => {
+    const worktreePath = "/tmp/pi-sub-run-42";
+    const result = resolveSessionContext({
+      fork: false,
+      mainCwd: MAIN_CWD,
+      agentDir: AGENT_DIR,
+      worktreePath,
+    });
+    expect(result.shouldFork).toBe(false);
+    expect(result.forkSource).toBeUndefined();
+    expect(result.effectiveCwd).toBe(worktreePath);
+    expect(result.sessionDir).toBe(expectedSessionDir(MAIN_CWD));
+  });
+
+  // ── 边界 4: fork=true, worktree=true ──
+  it("fork=true, worktreePath 提供 → shouldFork=true + effectiveCwd=worktreePath", () => {
+    const worktreePath = "/tmp/pi-sub-bg-7-abc";
+    const result = resolveSessionContext({
+      fork: true,
+      mainCwd: MAIN_CWD,
+      mainSessionFile: SESSION_FILE,
+      agentDir: AGENT_DIR,
+      worktreePath,
+    });
+    expect(result.shouldFork).toBe(true);
+    expect(result.forkSource).toBe(SESSION_FILE);
+    expect(result.effectiveCwd).toBe(worktreePath);
+    expect(result.sessionDir).toBe(expectedSessionDir(MAIN_CWD));
+  });
+
+  // ── 边界 5: fork=true + parentForkDepth>=10 → 抛错 ──
+  it("fork=true + parentForkDepth=10 → throws ForkDepthExceededError", () => {
+    expect(() =>
+      resolveSessionContext({
+        fork: true,
+        mainCwd: MAIN_CWD,
+        mainSessionFile: SESSION_FILE,
+        parentForkDepth: 10,
+        agentDir: AGENT_DIR,
+      }),
+    ).toThrow(ForkDepthExceededError);
+  });
+
+  it("fork=true + parentForkDepth=15 → throws ForkDepthExceededError", () => {
+    expect(() =>
+      resolveSessionContext({
+        fork: true,
+        mainCwd: MAIN_CWD,
+        parentForkDepth: 15,
+        agentDir: AGENT_DIR,
+      }),
+    ).toThrow(ForkDepthExceededError);
+  });
+
+  // ── depth=9 不抛 ──
+  it("fork=true + parentForkDepth=9 → does NOT throw", () => {
+    const result = resolveSessionContext({
+      fork: true,
+      mainCwd: MAIN_CWD,
+      mainSessionFile: SESSION_FILE,
+      parentForkDepth: 9,
+      agentDir: AGENT_DIR,
+    });
+    expect(result.shouldFork).toBe(true);
+  });
+
+  // ── sessionDir 始终用 mainCwd 编码（非 effectiveCwd）──
+  it("sessionDir always encoded from mainCwd even when worktreePath overrides effectiveCwd", () => {
+    const mainCwd = "/Users/alice/code/my-app";
+    const result = resolveSessionContext({
+      fork: false,
+      mainCwd,
+      agentDir: AGENT_DIR,
+      worktreePath: "/tmp/pi-sub-run-1",
+    });
+    // effectiveCwd 是 worktree checkout，但 sessionDir 仍基于 mainCwd
+    expect(result.effectiveCwd).not.toBe(mainCwd);
+    expect(result.sessionDir).toBe(expectedSessionDir(mainCwd));
+  });
+
+  // ── [MF#5] fork=true 但主 session 文件不可用 → 抛错（不静默降级）──
+  it("fork=true + mainSessionFile 缺失 → throws（不静默降级到 from-scratch）", () => {
+    expect(() =>
+      resolveSessionContext({
+        fork: true,
+        mainCwd: MAIN_CWD,
+        // mainSessionFile 故意不传
+        agentDir: AGENT_DIR,
+      }),
+    ).toThrow(/main session file is unavailable/);
+  });
+
+  // ── 默认值：fork/worktree 未传 → undefined → false ──
+  it("fork/worktree omitted → shouldFork=false", () => {
+    const result = resolveSessionContext({
+      mainCwd: MAIN_CWD,
+      agentDir: AGENT_DIR,
+    });
+    expect(result.shouldFork).toBe(false);
+    expect(result.forkSource).toBeUndefined();
+    expect(result.effectiveCwd).toBe(MAIN_CWD);
+  });
+
+  // ── cwd 覆盖 mainCwd（worktree=false 时）──
+  it("explicit cwd overrides mainCwd when worktree=false", () => {
+    const customCwd = "/tmp/custom-cwd";
+    const result = resolveSessionContext({
+      mainCwd: MAIN_CWD,
+      cwd: customCwd,
+      agentDir: AGENT_DIR,
+    });
+    expect(result.effectiveCwd).toBe(customCwd);
+    // sessionDir 仍用 mainCwd
+    expect(result.sessionDir).toBe(expectedSessionDir(MAIN_CWD));
+  });
+});

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

@@ -0,0 +1,293 @@
+// src/__tests__/session-file-gc.test.ts
+//
+// 锁定 maybeCleanupExpiredSessionFiles 的 TTL 边界（数据安全风险）：
+//   - 概率门（CLEANUP_PROBABILITY = 1/20）
+//   - TTL 边界（mtimeMs 恰好 = now - TTL_MS）
+//   - 只删 .jsonl，不删 .txt 等
+//   - 递归 walk 子目录
+//   - best-effort 吞错（只读目录不外抛）
+//
+// 边界算错会误删未过期 session 文件或不清理——数据安全风险。
+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";
+
+import * as aliveStore from "../alive-store.ts";
+import { maybeCleanupExpiredSessionFiles } from "../session-file-gc.ts";
+
+// ============================================================
+// helpers
+// ============================================================
+
+let tmpAgentDir: string;
+
+beforeEach(() => {
+  tmpAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "subagents-gc-test-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpAgentDir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+/** 强制 Math.random 返回 0（< CLEANUP_PROBABILITY → 必触发清理）。 */
+function forceCleanupTrigger(): void {
+  vi.spyOn(Math, "random").mockReturnValue(0);
+}
+
+/** 强制 Math.random 返回 1（>= CLEANUP_PROBABILITY → 跳过清理）。 */
+function forceCleanupSkip(): void {
+  vi.spyOn(Math, "random").mockReturnValue(1);
+}
+
+/** 创建一个 .jsonl 文件，mtime 设为指定天数前。 */
+function createSessionFile(relPath: string, daysAgo: number): string {
+  const fullPath = path.join(tmpAgentDir, "subagents", relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, `{"id":"${relPath}"}\n`, "utf-8");
+  // 设置 mtime：daysAgo 天前
+  const targetTime = Date.now() / 1000 - daysAgo * 86400;
+  fs.utimesSync(fullPath, targetTime, targetTime);
+  return fullPath;
+}
+
+// ============================================================
+// maybeCleanupExpiredSessionFiles
+// ============================================================
+
+describe("maybeCleanupExpiredSessionFiles", () => {
+  it("skips cleanup when random >= CLEANUP_PROBABILITY (probability gate)", () => {
+    forceCleanupSkip();
+    const oldFile = createSessionFile("old.jsonl", 31); // 31 天前，超 TTL
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    // 概率门跳过 → 文件仍在
+    expect(fs.existsSync(oldFile)).toBe(true);
+  });
+
+  it("triggers cleanup when random < CLEANUP_PROBABILITY", () => {
+    forceCleanupTrigger();
+    const oldFile = createSessionFile("old.jsonl", 31);
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    expect(fs.existsSync(oldFile)).toBe(false);
+  });
+
+  it("deletes files older than 30 days (TTL)", () => {
+    forceCleanupTrigger();
+    const old = createSessionFile("old.jsonl", 31);
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    expect(fs.existsSync(old)).toBe(false);
+  });
+
+  it("preserves files younger than 30 days", () => {
+    forceCleanupTrigger();
+    const young = createSessionFile("young.jsonl", 29);
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    expect(fs.existsSync(young)).toBe(true);
+  });
+
+  it("does NOT delete non-.jsonl files even if old (e.g. .txt)", () => {
+    forceCleanupTrigger();
+    const oldTxt = createSessionFile("old.txt", 31);
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    // .txt 不在清理范围
+    expect(fs.existsSync(oldTxt)).toBe(true);
+  });
+
+  it("recursively walks subdirectories", () => {
+    forceCleanupTrigger();
+    // 子目录中的旧文件
+    const oldNested = createSessionFile(
+      path.join("encoded-cwd-1", "sessions", "sess-old.jsonl"),
+      31,
+    );
+    const youngNested = createSessionFile(
+      path.join("encoded-cwd-1", "sessions", "sess-young.jsonl"),
+      5,
+    );
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    expect(fs.existsSync(oldNested)).toBe(false);
+    expect(fs.existsSync(youngNested)).toBe(true);
+  });
+
+  it("no-op when subagents dir does not exist (no throw)", () => {
+    forceCleanupTrigger();
+    // tmpAgentDir 下没有 subagents/ 目录
+    expect(() => maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd")).not.toThrow();
+  });
+
+  it("best-effort: never throws when 'subagents' is a file not a dir (readdirSync ENOTDIR)", () => {
+    // ESM 不允许 spyOn 命名空间导出，改用真实错误场景：
+    // 创建一个名为 subagents 的普通文件（非目录），existsSync 返 true 但 readdirSync 抛 ENOTDIR
+    forceCleanupTrigger();
+    const fileNotDir = path.join(tmpAgentDir, "subagents");
+    fs.writeFileSync(fileNotDir, "not a directory", "utf-8");
+    // walkAndClean 内部 readdirSync 抛错 → 被其 try/catch 吞掉 → 不外抛
+    expect(() => maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd")).not.toThrow();
+  });
+
+  it("TTL boundary: file just under 30 days is NOT deleted (strict greater-than semantics)", () => {
+    // walkAndClean 条件: now - stat.mtimeMs > TTL_MS（严格大于）
+    // 设 mtime 为 30 天前减去 2 分钟 → now - mtimeMs = TTL_MS - 2min + ε < TTL_MS → 保留
+    // 用 2 分钟缓冲消除「设 mtime 与 Date.now() 调用之间的几 ms 时间差」造成的抖动
+    forceCleanupTrigger();
+    const boundary = createSessionFile("boundary.jsonl", 0);
+    // 覆盖 mtime 为「30 天 - 2 分钟」前
+    const targetTime = Date.now() / 1000 - (30 * 86400 - 120);
+    fs.utimesSync(boundary, targetTime, targetTime);
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    // 严格 < TTL_MS → 不删（边界保留）
+    expect(fs.existsSync(boundary)).toBe(true);
+  });
+
+  it("handles empty subagents dir (no files, no throw)", () => {
+    forceCleanupTrigger();
+    // 创建空 subagents 目录
+    fs.mkdirSync(path.join(tmpAgentDir, "subagents"), { recursive: true });
+    expect(() => maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd")).not.toThrow();
+  });
+
+  // ---- .finalized sidecar 清理 ----
+
+  it("deletes .finalized sidecar along with expired .jsonl", () => {
+    forceCleanupTrigger();
+    const jsonl = createSessionFile("sess-finalized.jsonl", 31);
+    const finalized = `${jsonl}.finalized`;
+    fs.writeFileSync(finalized, "", "utf-8");
+    const targetTime = Date.now() / 1000 - 31 * 86400;
+    fs.utimesSync(finalized, targetTime, targetTime);
+
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+
+    expect(fs.existsSync(jsonl)).toBe(false);
+    expect(fs.existsSync(finalized)).toBe(false);
+  });
+
+  it("cleans orphan .finalized sidecar when .jsonl already gone", () => {
+    forceCleanupTrigger();
+    const subagentsDir = path.join(tmpAgentDir, "subagents");
+    fs.mkdirSync(subagentsDir, { recursive: true });
+    const orphan = path.join(subagentsDir, "dead-session.jsonl.finalized");
+    fs.writeFileSync(orphan, "", "utf-8");
+    const targetTime = Date.now() / 1000 - 31 * 86400;
+    fs.utimesSync(orphan, targetTime, targetTime);
+
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+
+    expect(fs.existsSync(orphan)).toBe(false);
+  });
+
+  // ---- .alive sidecar + pid 探活 ----
+
+  it("preserves expired .jsonl when .alive sidecar indicates live process (D-024)", () => {
+    forceCleanupTrigger();
+    const jsonl = createSessionFile("sess-alive.jsonl", 31);
+    const alivePath = `${jsonl}.alive`;
+    fs.writeFileSync(alivePath, JSON.stringify({ pid: 1, id: "s1", startedAt: Date.now() }), "utf-8");
+
+    vi.spyOn(aliveStore, "readAliveMarker").mockReturnValue({ pid: 1, id: "s1", startedAt: Date.now() });
+    vi.spyOn(aliveStore, "isProcessAlive").mockReturnValue(true);
+
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+
+    expect(fs.existsSync(jsonl)).toBe(true);
+    expect(fs.existsSync(alivePath)).toBe(true);
+  });
+
+  it("deletes expired .jsonl + .alive when process is dead", () => {
+    forceCleanupTrigger();
+    const jsonl = createSessionFile("sess-dead.jsonl", 31);
+    const alivePath = `${jsonl}.alive`;
+    fs.writeFileSync(alivePath, JSON.stringify({ pid: 99999, id: "s2", startedAt: Date.now() }), "utf-8");
+
+    vi.spyOn(aliveStore, "readAliveMarker").mockReturnValue({ pid: 99999, id: "s2", startedAt: Date.now() });
+    vi.spyOn(aliveStore, "isProcessAlive").mockReturnValue(false);
+
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+
+    expect(fs.existsSync(jsonl)).toBe(false);
+    expect(fs.existsSync(alivePath)).toBe(false);
+  });
+
+  it("cleans orphan .alive sidecar when .jsonl already gone", () => {
+    forceCleanupTrigger();
+    const subagentsDir = path.join(tmpAgentDir, "subagents");
+    fs.mkdirSync(subagentsDir, { recursive: true });
+    const orphan = path.join(subagentsDir, "dead-session.jsonl.alive");
+    fs.writeFileSync(orphan, JSON.stringify({ pid: 99999, id: "s3", startedAt: Date.now() }), "utf-8");
+    const targetTime = Date.now() / 1000 - 31 * 86400;
+    fs.utimesSync(orphan, targetTime, targetTime);
+
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+
+    expect(fs.existsSync(orphan)).toBe(false);
+  });
+
+  it("deletes .jsonl + all sidecars (.cancelled, .finalized, .alive) together", () => {
+    forceCleanupTrigger();
+    const jsonl = createSessionFile("sess-all-sidecars.jsonl", 31);
+    const cancelled = `${jsonl}.cancelled`;
+    const finalized = `${jsonl}.finalized`;
+    const alive = `${jsonl}.alive`;
+    fs.writeFileSync(cancelled, "", "utf-8");
+    fs.writeFileSync(finalized, "", "utf-8");
+    fs.writeFileSync(alive, JSON.stringify({ pid: 99999, id: "s4", startedAt: Date.now() }), "utf-8");
+
+    vi.spyOn(aliveStore, "readAliveMarker").mockReturnValue({ pid: 99999, id: "s4", startedAt: Date.now() });
+    vi.spyOn(aliveStore, "isProcessAlive").mockReturnValue(false);
+
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+
+    expect(fs.existsSync(jsonl)).toBe(false);
+    expect(fs.existsSync(cancelled)).toBe(false);
+    expect(fs.existsSync(finalized)).toBe(false);
+    expect(fs.existsSync(alive)).toBe(false);
+  });
+
+  // ---- [F2] manifest .json 清理（仅 records 子目录内）----
+  // records 目录布局：subagents/<enc>/records/<id>.json（D-004 cwd 物理隔离）。
+  // allowManifestJson 仅在名为 records 的子目录内打开，防止误删 enc 外层的
+  // worktrees.json（worktree reaper 依赖的状态文件）。
+
+  it("[F2] deletes expired manifest .json inside records/ subdir", () => {
+    forceCleanupTrigger();
+    const manifest = createSessionFile(
+      path.join("--Users-x-proj--", "records", "rec-1.json"),
+      31,
+    );
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    expect(fs.existsSync(manifest)).toBe(false);
+  });
+
+  it("[F2] preserves manifest .json younger than TTL inside records/", () => {
+    forceCleanupTrigger();
+    const manifest = createSessionFile(
+      path.join("--Users-x-proj--", "records", "rec-young.json"),
+      5,
+    );
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    expect(fs.existsSync(manifest)).toBe(true);
+  });
+
+  it("[F2] CRITICAL: does NOT delete worktrees.json at subagents/ root (regression)", () => {
+    // 破坏性风险点：worktrees.json 在 agentDir/subagents/worktrees.json（enc 外层第一层）。
+    // 暴力匹配所有 .json 会误删 → worktree reaper 失效。allowManifestJson 只在名为 records
+    // 的子目录内打开，根层的 worktrees.json 必须保留。
+    forceCleanupTrigger();
+    const worktrees = createSessionFile("worktrees.json", 31);
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    expect(fs.existsSync(worktrees)).toBe(true);
+  });
+
+  it("[F2] preserves .json.tmp.* inside records/ (recoverTmpFiles owns them)", () => {
+    // 跳过 .tmp.：session_start 的 recoverTmpFiles 同步处理 tmp，GC 不重复。
+    forceCleanupTrigger();
+    const tmp = createSessionFile(
+      path.join("--Users-x-proj--", "records", "rec-2.json.tmp.123"),
+      31,
+    );
+    maybeCleanupExpiredSessionFiles(tmpAgentDir, "/cwd");
+    expect(fs.existsSync(tmp)).toBe(true);
+  });
+});