@zhushanwen/pi-subagent-workflow 0.1.0

package/src/execution/__tests__/sdk-contract.test.ts

@@ -0,0 +1,272 @@
+// src/__tests__/sdk-contract.test.ts
+//
+// SDK 契约测试：验证扩展对 Pi SDK 的消费符合 [MANDATORY] checklist。
+// 关闭 CI sdk-contract-audit job 的前向引用（该 job 直接跑此文件）。
+//
+// 核心断言（[MANDATORY] checklist）：
+//   1. registerSubagentsCommand 注册名为 "subagents" 的命令，handler 是 (args, ctx)
+//   2. registerSubagentTool 注册名为 "subagent" 的工具，schema 存在
+//   3. pending:unregister 事件携带 result/error/patchFile 时消费侧 sendMessage（T2 后替代 notifier）
+//   4. session_start handler 类型签名 (event, ctx) → 编译期保证（stub 精确类型）
+//
+// 不导入 index.ts（它经 getAgentDir 值导入触发 alias 解析失败——alias 指向
+// .d.ts-only stub）。改测叶子注册函数。session_start 的
+// (event, ctx) 双参数契约由 tsconfig 的精确 stub 类型在编译期强制（见
+// shared/types/mariozechner/index.d.ts 注释：modelRegistry/cwd/ui 不在 event 上）。
+
+import { describe, expect, it, vi } from "vitest";
+
+// registerSubagentTool 经 subagent-tool.ts 值导入 StringEnum（pi-ai）+ Type（typebox）。
+// shared/types stub 是 .d.ts（仅类型），pnpm optional-peer-dep 插件拦截值导入 → vi.mock 兜底。
+vi.mock("@mariozechner/pi-ai", () => ({
+  StringEnum: (values: string[]) => ({ type: "string", enum: values }),
+}));
+vi.mock("@earendil-works/pi-ai", () => ({
+  StringEnum: (values: string[]) => ({ type: "string", enum: values }),
+}));
+vi.mock("@sinclair/typebox", () => ({
+  Type: {
+    Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
+    Optional: (schema: unknown) => ({ ...schema as object, optional: true }),
+    String: () => ({ type: "string" }),
+    Boolean: () => ({ type: "boolean" }),
+    Number: () => ({ type: "number" }),
+    Array: (items: unknown) => ({ type: "array", items }),
+    Record: (key: unknown, value: unknown) => ({ type: "object", additionalProperties: value, key }),
+    Unknown: () => ({ type: "unknown" }),
+    Union: (members: unknown[]) => ({ type: "union", members }),
+    Literal: (value: unknown) => ({ type: "literal", value }),
+  },
+}));
+
+// Mock getSubagentService：execute plumb-through 契约测试需要拦截 service.execute 调用。
+const { mockServiceExecute } = vi.hoisted(() => ({
+  mockServiceExecute: vi.fn(),
+}));
+vi.mock("../subagent-service.ts", () => ({
+  getSubagentService: () => ({ execute: mockServiceExecute }),
+}));
+
+import { registerWorkflowsCommand } from "../../interface/commands.ts";
+import { registerSubagentTool } from "../../interface/subagent-tool.ts";
+import { registerSubagentsCommand } from "../../interface/subagents.ts";
+import type { LauncherDeps } from "../../orchestration/launcher.ts";
+import { mockExtensionApi } from "./helpers/mock-extension-api.ts";
+
+/**
+ * 构造最小 LauncherDeps mock（契约测试只捕获 handler，从不调用它，
+ * 故 deps 字段全为占位 no-op 即可——registerWorkflowsCommand 注册时不读 deps，
+ * 仅存入 handler 闭包）。
+ *
+ * 用 `as unknown as LauncherDeps` 与 orchestration/__tests__ 同模式（该类型字段多，
+ * 全字段构造冗余；占位足够此处断言注册名 + handler arity 的需要）。
+ */
+function makeLauncherDepsStub(): LauncherDeps {
+  return {
+    registry: { get: vi.fn() },
+    runs: new Map(),
+    store: { save: vi.fn(), loadAll: vi.fn(async () => []) },
+    workerHost: { start: vi.fn() },
+    runner: { run: vi.fn() },
+    log: vi.fn(),
+    eventBus: { emit: vi.fn() },
+  } as unknown as LauncherDeps;
+}
+
+// ============================================================
+// /subagents command 契约
+// ============================================================
+describe("/subagents command contract [MANDATORY]", () => {
+  it("registers a command named 'subagents'", () => {
+    let registeredName: string | undefined;
+    const pi = mockExtensionApi({
+      registerCommand: (name: string) => { registeredName = name; },
+    });
+    registerSubagentsCommand(pi);
+    expect(registeredName).toBe("subagents");
+  });
+
+  it("handler accepts (args, ctx) — two parameters", () => {
+    let capturedHandler: ((...args: unknown[]) => unknown) | undefined;
+    const pi = mockExtensionApi({
+      registerCommand: (_name: string, command: { handler: (...args: unknown[]) => unknown }) => {
+        capturedHandler = command.handler;
+      },
+    });
+    registerSubagentsCommand(pi);
+    expect(capturedHandler).toBeDefined();
+    // function.length 反映必填参数数（ctx 至少是第 2 个）
+    expect(capturedHandler!.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+// ============================================================
+// /workflows command 契约 [MANDATORY]
+// ============================================================
+//
+// registerWorkflowsCommand(api, getRuns, deps) 注册名为 "workflows" 的命令，
+// handler 是 (args, ctx)。与 /subagents 同构的注册契约——此处锁住注册名 + handler arity，
+// 防止重构时改名或丢参数导致 /workflows 命令失效。
+describe("/workflows command contract [MANDATORY]", () => {
+  it("registers a command named 'workflows'", () => {
+    let registeredName: string | undefined;
+    const pi = mockExtensionApi({
+      registerCommand: (name: string) => { registeredName = name; },
+    });
+    // getRuns / deps 契约测试不调用 handler，传最小合法值即可
+    registerWorkflowsCommand(pi, () => new Map(), makeLauncherDepsStub());
+    expect(registeredName).toBe("workflows");
+  });
+
+  it("handler accepts (args, ctx) — two parameters", () => {
+    let capturedHandler: ((...args: unknown[]) => unknown) | undefined;
+    const pi = mockExtensionApi({
+      registerCommand: (_name: string, command: { handler: (...args: unknown[]) => unknown }) => {
+        capturedHandler = command.handler;
+      },
+    });
+    registerWorkflowsCommand(pi, () => new Map(), makeLauncherDepsStub());
+    expect(capturedHandler).toBeDefined();
+    // function.length 反映必填参数数（args + ctx = 2）
+    expect(capturedHandler!.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+// ============================================================
+// subagent tool 契约
+// ============================================================
+describe("subagent tool contract [MANDATORY]", () => {
+  it("registers a tool named 'subagent' with a parameters schema", () => {
+    let registeredTool: { name: string; parameters: unknown } | undefined;
+    const pi = mockExtensionApi({
+      registerTool: (tool: unknown) => { registeredTool = tool as { name: string; parameters: unknown }; },
+    });
+    registerSubagentTool(pi);
+    expect(registeredTool?.name).toBe("subagent");
+    expect(registeredTool?.parameters).toBeDefined();
+  });
+
+  it("tool has execute, renderCall, renderResult callbacks", () => {
+    let registeredTool: Record<string, unknown> | undefined;
+    const pi = mockExtensionApi({
+      registerTool: (tool: unknown) => { registeredTool = tool as Record<string, unknown>; },
+    });
+    registerSubagentTool(pi);
+    expect(typeof registeredTool?.execute).toBe("function");
+  });
+
+  // SDK 契约：ToolDefinition.execute 是 5 参数 (toolCallId, params, signal, onUpdate, ctx)。
+  // ctx 是第 5 个参数，runtime 通过 wrapToolDefinition(ctxFactory) 注入。
+  // 此测试验证 ctx.model 被 plumb 到 service.execute 的 ctxModel 参数。
+  // 回归保护：subagent-tool.ts execute 把 _ctx?.model 传给 startHandler 的第 5 参 ctxModel。
+  it("execute passes ctx.model as ctxModel (SDK 5-param contract)", async () => {
+    let capturedExecute: ((...args: never[]) => Promise<unknown>) | undefined;
+    const pi = mockExtensionApi({
+      registerTool: (tool: unknown) => {
+        capturedExecute = (tool as { execute: (...args: never[]) => Promise<unknown> }).execute;
+      },
+    });
+    registerSubagentTool(pi);
+    expect(capturedExecute).toBeDefined();
+
+    mockServiceExecute.mockReset();
+    mockServiceExecute.mockResolvedValue({
+      mode: "background",
+      subagentId: "bg-test",
+      sessionFile: "/test/session.jsonl",
+    });
+    const ctxModel = { id: "test-model", name: "Test", provider: "test", reasoning: false };
+    const ctx = { model: ctxModel } as object;
+
+    await capturedExecute!(
+      "call-1",
+      { action: "start", startParam: { task: "test task" } },
+      undefined,
+      undefined,
+      ctx,
+    );
+
+    expect(mockServiceExecute).toHaveBeenCalledTimes(1);
+    expect(mockServiceExecute).toHaveBeenCalledWith(
+      expect.objectContaining({ ctxModel }),
+    );
+  });
+
+  // [MF#5] fork/worktree/cwd 参数传递链路契约（acceptance #8）：
+  // tool execute → startHandler(service, startParam) → service.execute({fork, worktree, cwd, ...})。
+  // 回归保护：subagent-actions.ts startHandler L152-166 把 input.fork/worktree/cwd 透传给
+  // service.execute。若任一字段在 handler 内漏传（如重构改名/删行），子 agent 静默丢失隔离模式。
+  // 此测试锁住「startParam.fork/worktree/cwd → service.execute 同名参数」端到端透传。
+  it("execute plumbs startParam.fork/worktree/cwd to service.execute (chain contract)", async () => {
+    let capturedExecute: ((...args: never[]) => Promise<unknown>) | undefined;
+    const pi = mockExtensionApi({
+      registerTool: (tool: unknown) => {
+        capturedExecute = (tool as { execute: (...args: never[]) => Promise<unknown> }).execute;
+      },
+    });
+    registerSubagentTool(pi);
+    expect(capturedExecute).toBeDefined();
+
+    mockServiceExecute.mockReset();
+    mockServiceExecute.mockResolvedValue({
+      mode: "background",
+      subagentId: "bg-fork-wt",
+      sessionFile: "/test/session.jsonl",
+    });
+
+    await capturedExecute!(
+      "call-fork-wt",
+      {
+        action: "start",
+        startParam: {
+          task: "isolated work",
+          fork: true,
+          worktree: true,
+          cwd: "/x",
+        },
+      },
+      undefined,
+      undefined,
+      undefined,
+    );
+
+    // service.execute 收到完整的 fork/worktree/cwd 三参数透传
+    expect(mockServiceExecute).toHaveBeenCalledTimes(1);
+    expect(mockServiceExecute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fork: true,
+        worktree: true,
+        cwd: "/x",
+      }),
+    );
+  });
+
+  // sync 路径已删除（T2 Wave 0）。background 的 content JSON 只含 bgResponse
+  // （status/mode/message），不含 record 派生投影——投影发生在 notifier 注入的完成消息。
+});
+
+// ============================================================
+// pending:unregister 事件契约 [MANDATORY]（T2 后 notifier 职责转移至此）
+// ============================================================
+//
+// T2 后 background 完成通知改由 pending-notifications 扩展消费 pending:unregister
+// 事件后调 pi.sendMessage。subagent-service 的 emitPendingUnregister 在终态路径
+// 携带 result/error/patchFile，消费侧据此构造 customType:"subagent-bg-notify" 消息
+// 并以 triggerTurn:true + deliverAs:"followUp" 注入。
+//
+// 此处的契约由 pending-notifications 的单元测试覆盖（断言 sendMessage 调用参数），
+// 本套件不再直接测试 BgNotifier（已删除）。
+
+// ============================================================
+// session_start handler 双参数契约 — 编译期保证
+// ============================================================
+describe("session_start handler signature (compile-time guarantee)", () => {
+  it("ExtensionHandler<SessionStartEvent> is (event, ctx) two-param — enforced by stub type", () => {
+    // 此测试是编译期断言：shared/types/mariozechner/index.d.ts:111 声明
+    //   ExtensionHandler<E, R> = (event: E, ctx: ExtensionContext) => Promise<R|void> | R | void;
+    // 且 SessionStartEvent 注释明确 modelRegistry/cwd/ui 不在 event 上（在 ctx）。
+    // index.ts:66 `pi.on("session_start", (_event, ctx) => {...})` 通过此类型检查即证明契约。
+    // tsc --noEmit 零错误 = 此契约成立。此 it() 占位让套件非空（实际断言在编译期）。
+    expect(true).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,247 @@
+// 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);
+  });
+});