@zhushanwen/pi-subagent-workflow 0.1.0 → 0.3.0

package/src/execution/__tests__/run-spawn-integration.test.ts

@@ -14,36 +14,22 @@
 //   - fs.promises.* → 保留真实实现（temp-prompt 整体被 mock，不触发真实 I/O）。
 //   - temp-prompt → mock（writePromptToTempFile 返回固定路径，消除 fake-timers flaky）。
 //   - alive-store.writeAliveMarker → mock（避免写 .alive sidecar）。
+//
+// mock 工厂 + FakeChild class + 工具函数（lastSpawnedChild/waitForSpawn/emitStdoutLine/
+// sessionHeader/makeRecord/makeOpts/makeCtx）抽到 helpers/spawn-mock.ts，与
+// run-spawn-edges.test.ts / run-spawn-rpc-mode.test.ts 三文件共享。vi.mock 工厂内用
+// `await import("./helpers/spawn-mock.ts")` 取回 FakeChild（绕开 vitest 的 hoisting 限制——
+// 工厂函数体不能引用顶层 import 变量，但 async 工厂内的 await import 是运行时求值）。
 
-import type { PassThrough } from "node:stream";
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-// ── mock modules ──
-//
-// vitest 会把 vi.mock 提升到文件顶部（早于其他 import / 声明）。mock 工厂若要引用
-// FakeChild，需在工厂内部 import（async 工厂可用 await import），而非引用顶部
-// 顶层 import（它们在 vi.mock 执行时尚未绑定）。
+// ── mock modules（工厂体共享自 helpers/spawn-mock.ts；vi.mock 必须各文件独立声明）──
 
 vi.mock("node:child_process", async () => {
-  const { EventEmitter } = await import("node:events");
-  const { PassThrough } = await import("node:stream");
-
-  // FakeChild：模拟 ChildProcess（EventEmitter + PassThrough streams）。
-  // 测试通过 mockSpawn.mock.results.at(-1).value 取回实例，控制 emit data/close/error 时序。
-  class FakeChild extends EventEmitter {
-    pid = 12345;
-    stdout = new PassThrough();
-    stderr = new PassThrough();
-    killed = false;
-    killSignal: string | undefined;
-    kill(sig?: string): boolean {
-      this.killed = true;
-      this.killSignal = sig;
-      return true;
-    }
-  }
-
+  const { FakeChild } = await import("./helpers/spawn-mock.ts");
   return {
     spawn: vi.fn(() => new FakeChild()),
     execFileSync: vi.fn(() => ""), // buildEnvBlock 的 git branch 调用，返回空避免副作用
@@ -62,13 +48,11 @@ vi.mock("node:fs", async () => {
       writeFileSync: vi.fn(),
       readdirSync: vi.fn(() => []),
     },
-    // 具名导出与 default 保持一致
     mkdirSync: vi.fn(),
     existsSync: vi.fn(() => false),
     appendFileSync: vi.fn(),
     writeFileSync: vi.fn(),
     readdirSync: vi.fn(() => []),
-    // promises 保留真实实现——temp-prompt 已被 mock（见下方 vi.mock），不再触发真实 I/O
     promises: actual.promises,
   };
 });
@@ -80,9 +64,7 @@ vi.mock("../alive-store.ts", () => ({
 // temp-prompt：mock 掉真实 fs.promises I/O（mkdtemp/writeFile/rm）。
 // 原先保留真实实现导致 fake-timers 测试偶发 flaky——writePromptToTempFile 的真实异步
 // I/O 在 CI 慢机器上无法在 advanceTimersByTimeAsync 的有限步数内 resolve，spawn 永不触发。
-// runSpawn 只消费返回的 filePath 字符串（传给 --append-system-prompt），无需真实文件。
 vi.mock("../temp-prompt.ts", () => ({
-  // 文件名规则与真实实现对齐（safeName：非 \w.- 替换为 _），保持 spawn args 断言稳定
   writePromptToTempFile: vi.fn(async (agent: string) => {
     const safeName = agent.replace(/[^\w.-]+/g, "_");
     return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
@@ -90,11 +72,18 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { execFileSync, spawn } from "node:child_process";
-import * as fs from "node:fs";
-
-import { createRecord } from "../execution-record.ts";
-import { type RunOptions, runSpawn, type SessionRunnerContext } from "../session-runner.ts";
+import { runSpawn } from "../session-runner.ts";
+import {
+  emitStdoutLine,
+  type FakeChild,
+  lastSpawnedChild as lastSpawnedChildOf,
+  makeCtx,
+  makeOpts,
+  makeRecord,
+  mockSessionFileExists as mockSessionFileExistsOf,
+  sessionHeader,
+  waitForSpawn as waitForSpawnOf,
+} from "./helpers/spawn-mock.ts";
 
 const mockSpawn = vi.mocked(spawn);
 const mockExec = vi.mocked(execFileSync);
@@ -102,124 +91,10 @@ const mockExistsSync = vi.mocked(fs.existsSync);
 const mockAppendFileSync = vi.mocked(fs.appendFileSync);
 const mockMkdirSync = vi.mocked(fs.mkdirSync);
 
-/**
- * spawn mock 返回的 fake child 类型。
- * 由于 FakeChild 定义在 vi.mock 工厂内部（作用域隔离），此处用结构子集类型描述，
- * 测试代码通过此类型访问 stdout/stderr/kill 等成员。
- */
-interface FakeChild {
-  pid: number;
-  stdout: PassThrough;
-  stderr: PassThrough;
-  killed: boolean;
-  killSignal: string | undefined;
-  kill(sig?: string): boolean;
-  emit(event: string, ...args: unknown[]): boolean;
-}
-
-/** 从最近一次 spawn 调用取回返回的 FakeChild（测试控制器）。 */
-function lastSpawnedChild(): FakeChild {
-  const result = mockSpawn.mock.results.at(-1);
-  if (!result) throw new Error("spawn was not called yet");
-  return result.value as FakeChild;
-}
-
-/**
- * 等待 runSpawn 内部调到 spawn（拿到 child 控制器）。
- *
- * runSpawn 是 async，spawn 在 mkdirSync + writePromptToTempFile 之后才调（均有微任务/
- * I/O 延迟）。用 setInterval 轮询 mockSpawn.mock.results，比 vi.waitFor 在该 vitest 版本
- * 下更可靠（vi.waitFor 偶发过早 resolve 导致后续读取竞态）。
- */
-async function waitForSpawn(timeoutMs = 1000): Promise<void> {
-  const start = Date.now();
-  while (mockSpawn.mock.results.length === 0) {
-    if (Date.now() - start > timeoutMs) {
-      throw new Error(`spawn was not called within ${timeoutMs}ms`);
-    }
-    await new Promise((r) => setTimeout(r, 5));
-  }
-}
-
-// ============================================================
-// 辅助：向 stdout 写一行（自动补换行，runSpawn 按 \n split 行）
-// ============================================================
-
-function emitStdoutLine(child: FakeChild, obj: Record<string, unknown>): void {
-  child.stdout.write(`${JSON.stringify(obj)}\n`);
-}
-
-/** 构造 session header 行（stdout 首行）。 */
-function sessionHeader(id = "sess-abc"): Record<string, unknown> {
-  return {
-    type: "session",
-    id,
-    timestamp: "2026-07-03T12-00-00-000Z",
-    cwd: "/tmp/test",
-  };
-}
-
-// ============================================================
-// 辅助：构造最小合法的 record / opts / ctx
-// ============================================================
-
-function makeRecord() {
-  return createRecord("run-1", {
-    agent: "general-purpose",
-    model: "test-model",
-    mode: "sync",
-    task: "do something",
-    startedAt: 1_000_000,
-    rootSessionId: "root-session",
-    parentRecordId: undefined,
-    depth: 0,
-  });
-}
-
-function makeOpts(overrides: Partial<RunOptions> = {}): RunOptions {
-  return {
-    resolved: {
-      model: {
-        id: "test-model",
-        name: "Test Model",
-        provider: "test",
-        reasoning: false,
-      },
-      thinkingLevel: undefined,
-    },
-    agentConfig: undefined,
-    appendSystemPrompt: undefined,
-    skillPath: undefined,
-    schema: undefined,
-    maxTurns: undefined,
-    graceTurns: undefined,
-    signal: undefined,
-    onEvent: undefined,
-    ...overrides,
-  };
-}
-
-function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
-  return {
-    cwd: "/tmp/test",
-    agentDir: "/tmp/test/agents",
-    skillDirs: [],
-    mainCwd: "/tmp/test",
-    mainSessionFile: undefined,
-    ...overrides,
-  };
-}
-
-/**
- * 让 sessionFile 存在校验通过——
- * runSpawn 在进程退出后用 existsSync(record.sessionFile) 判断是否补写 identity。
- * 默认 mock existsSync 返回 false（兜底查找），此 helper 在指定路径返回 true。
- */
-function mockSessionFileExists(sessionFilePath: string): void {
-  mockExistsSync.mockImplementation((p: unknown) => {
-    return String(p) === sessionFilePath;
-  });
-}
+// 绑定到本文件 mockSpawn 的 lastSpawnedChild/waitForSpawn（需读 mockSpawn.mock.results）
+const lastSpawnedChild = (): FakeChild => lastSpawnedChildOf(mockSpawn);
+const waitForSpawn = (timeoutMs = 1000): Promise<void> => waitForSpawnOf(mockSpawn, timeoutMs);
+const mockSessionFileExists = (p: string): void => mockSessionFileExistsOf(mockExistsSync, p);
 
 // ============================================================
 // 测试
@@ -892,6 +767,65 @@ describe("runSpawn", () => {
     });
   });
 
+  // ── 15. stdin prompt 注入 ──
+  //
+  // [RPC prompt 修复] pi runRpcMode 只通过 stdin RpcCommand 驱动——positional task arg
+  // / -p flag 在 rpc mode 下被 resolveAppMode 无视。runSpawn 必须在 spawn 后主动写
+  // {type:"prompt",message:<task>} 到 child.stdin，否则子进程阻塞、totalTokens 恒 0。
+  // sendPromptCommand 在 spawn + setEncoding 后同步执行，waitForSpawn 拿到 child 时
+  // 命令已在 stdin 缓冲。PassThrough.write 无 reader 时缓冲全部数据，可事后读出断言。
+  describe("stdin prompt 注入", () => {
+    it("spawn 后向 stdin 写一行 {type:prompt} 且 message 含 task 文本", async () => {
+      const record = makeRecord();
+      const taskText = "Task: hello-prompt-injection";
+      const promise = runSpawn(record, taskText, makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // sendPromptCommand 已同步执行——PassThrough 缓冲了写入的命令，读出来断言。
+      // pause() 让 PassThrough 切到暂停模式（默认 flow 模式下数据缓冲在内部），
+      // 然后 read() 取出全部已缓冲内容。
+      child.stdin.pause();
+      const buffered = child.stdin.read()?.toString() ?? "";
+
+      // 收尾：让 runSpawn resolve（避免悬挂）
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+      await promise;
+
+      // 断言：缓冲含合法 JSON，type=prompt，message 含 task 文本
+      const lines = buffered.trim().split("\n");
+      expect(lines.length).toBeGreaterThanOrEqual(1);
+      const cmd = JSON.parse(lines[0]!) as { type: string; message: string; id?: string };
+      expect(cmd.type).toBe("prompt");
+      expect(cmd.message).toBe(taskText);
+      expect(typeof cmd.id).toBe("string");
+    });
+
+    it("child.stdin.destroyed → sendPromptCommand 不抛错（guard 生效）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: destroyed-stdin", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // destroy stdin 模拟子进程已关闭输入通道；sendPromptCommand 在 spawn 时已执行过一次
+      //（stdin 当时未 destroyed），这里仅验证后续不抛。此用例主要保护 guard 逻辑——
+      // 收尾正常 close 即证明无异常抛出中断 runSpawn。
+      child.stdin.destroy();
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+
+      const result = await promise;
+      expect(result.success).toBe(true);
+    });
+  });
+
   // 注：C1（orphan 进程兜底）与 M8（stdout 边界）describe 块已移至 run-spawn-edges.test.ts，
   // 拆分以保持本文件 < 1000 行（pre-commit hook 限制）。两文件各自独立声明文件级 mock。
 });

package/src/execution/__tests__/run-spawn-rpc-mode.test.ts

@@ -0,0 +1,193 @@
+// src/__tests__/run-spawn-rpc-mode.test.ts
+//
+// runSpawn 的 RPC mode 集成测试（从 run-spawn-integration.test.ts 拆出，保持该文件 < 1000 行）。
+//
+// 本文件覆盖 FR-4: RPC mode（pi --mode rpc）无 header 场景——record.sessionFile 无法靠
+// stdout header 推导，必须通过 get_state RPC 握手回填。验证修复后的握手逻辑。
+//
+// mock 工厂 + FakeChild + 工具函数共享自 helpers/spawn-mock.ts（详见该文件头注释）。
+// vi.mock 必须各文件独立声明（文件作用域），工厂内用 `await import` 取回 FakeChild。
+
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("node:child_process", async () => {
+  const { FakeChild } = await import("./helpers/spawn-mock.ts");
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    execFileSync: vi.fn(() => ""),
+  };
+});
+
+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(),
+}));
+
+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 } from "../session-runner.ts";
+import {
+  emitStdoutLine,
+  type FakeChild,
+  lastSpawnedChild as lastSpawnedChildOf,
+  makeCtx,
+  makeOpts,
+  makeRecord,
+  mockSessionFileExists as mockSessionFileExistsOf,
+  waitForSpawn as waitForSpawnOf,
+} from "./helpers/spawn-mock.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockExec = vi.mocked(execFileSync);
+const mockExistsSync = vi.mocked(fs.existsSync);
+const mockAppendFileSync = vi.mocked(fs.appendFileSync);
+
+// 绑定到本文件 mockSpawn/mockExistsSync 的 helper（需读 mock 状态）
+const lastSpawnedChild = (): FakeChild => lastSpawnedChildOf(mockSpawn);
+const waitForSpawn = (timeoutMs = 1000): Promise<void> => waitForSpawnOf(mockSpawn, timeoutMs);
+const mockSessionFileExists = (p: string): void => mockSessionFileExistsOf(mockExistsSync, p);
+
+// ============================================================
+// 测试
+// ============================================================
+
+describe("runSpawn", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockExec.mockReturnValue("");
+    mockExistsSync.mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // ── FR-4: RPC mode 无 header（get_state 握手回填 sessionFile）──
+  //
+  // RPC mode（pi --mode rpc）不向 stdout 输出 header 行，record.sessionFile 无法靠
+  // header 推导，必须通过 get_state RPC 握手回填。json mode 测试 emit sessionHeader()
+  // 模拟 header；本组测试不 emit header，靠 get_state response 回填，验证修复后的握手逻辑
+  //（握手移出 header 块、spawn 后无条件启动、close handler 主动 settle 不阻塞）。
+  describe("RPC mode 无 header（FR-4 get_state 握手）", () => {
+    /**
+     * 捕获握手发出的 get_state 命令并 emit 对应 response。
+     *
+     * 握手在 spawn 后发 get_state 到 child.stdin（id 随机）。测试监听 stdin 捕获 id，
+     * emit get_state response 到 stdout，经 stdout pump 匹配 get_stateListeners 触发
+     * finishHandshake 回填 record.sessionFile。
+     */
+    function captureAndRespondGetState(
+      child: FakeChild,
+      sessionFile: string,
+      sessionId = "rpc-sess",
+    ): void {
+      child.stdin.on("data", (data: Buffer | string) => {
+        const text = typeof data === "string" ? data : data.toString();
+        for (const line of text.split("\n")) {
+          if (!line.trim()) continue;
+          try {
+            const cmd = JSON.parse(line) as { type?: string; id?: string };
+            if (cmd.type === "get_state" && cmd.id) {
+              emitStdoutLine(child, {
+                type: "response",
+                command: "get_state",
+                success: true,
+                id: cmd.id,
+                data: { sessionFile, sessionId },
+              });
+            }
+          } catch {
+            // 非 JSON 行（prompt 命令等）忽略
+          }
+        }
+      });
+    }
+
+    it("无 header + get_state response 回填 sessionFile → identity 写入成功", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: rpc-no-header", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      const expectedSessionFile =
+        "/tmp/test/agents/subagents/--tmp-test--/sessions/rpc-session.jsonl";
+      // 进程退出后 existsSync(record.sessionFile) 校验通过 → 补写 identity
+      mockSessionFileExists(expectedSessionFile);
+      captureAndRespondGetState(child, expectedSessionFile);
+
+      // 等待 stdin listener 触发 + response 经 stdout pump 处理 → finishHandshake 回填。
+      // PassThrough attach data listener 后在 nextTick flush 缓冲，setTimeout(20) 足够覆盖。
+      await new Promise((r) => setTimeout(r, 20));
+
+      // RPC mode：只 emit 事件，不 emit header
+      emitStdoutLine(child, { type: "turn_end" });
+      child.stdout.end();
+      child.emit("close", 0);
+
+      const result = await promise;
+
+      expect(result.success).toBe(true);
+      expect(record.sessionFile).toBe(expectedSessionFile);
+      expect(result.sessionFile).toBe(expectedSessionFile);
+      // identity 经握手回填的 sessionFile 写入（不再依赖 sessionHeader 条件）
+      expect(mockAppendFileSync).toHaveBeenCalledWith(
+        expectedSessionFile,
+        expect.stringContaining('"customType":"subagent-identity"'),
+        "utf-8",
+      );
+    });
+
+    it("无 header + get_state 无响应 → close 主动 settle 不阻塞，identity 不写入", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: rpc-no-response", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // 消费 stdin 避免背压；不 emit get_state response（模拟握手超时/失败）
+      child.stdin.on("data", () => {});
+
+      emitStdoutLine(child, { type: "turn_end" });
+      child.stdout.end();
+      child.emit("close", 0);
+
+      const result = await promise;
+
+      // close handler 主动 settle，不等握手内部 6s 超时 → 测试不超时（5s 默认上限）
+      expect(result.success).toBe(true);
+      // 握手未完成 → sessionFile 未回填
+      expect(record.sessionFile).toBeUndefined();
+      // identity 不写入
+      expect(mockAppendFileSync).not.toHaveBeenCalled();
+    });
+  });
+});

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

@@ -174,13 +174,14 @@ describe("subagent tool contract [MANDATORY]", () => {
       mode: "background",
       subagentId: "bg-test",
       sessionFile: "/test/session.jsonl",
+      details: { slug: "test-slug" },
     });
     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" } },
+      { action: "start", startParam: { task: "test task", slug: "test-slug" } },
       undefined,
       undefined,
       ctx,
@@ -188,7 +189,7 @@ describe("subagent tool contract [MANDATORY]", () => {
 
     expect(mockServiceExecute).toHaveBeenCalledTimes(1);
     expect(mockServiceExecute).toHaveBeenCalledWith(
-      expect.objectContaining({ ctxModel }),
+      expect.objectContaining({ ctxModel, slug: "test-slug" }),
     );
   });
 
@@ -212,6 +213,7 @@ describe("subagent tool contract [MANDATORY]", () => {
       mode: "background",
       subagentId: "bg-fork-wt",
       sessionFile: "/test/session.jsonl",
+      details: { slug: "iso-work" },
     });
 
     await capturedExecute!(
@@ -220,6 +222,7 @@ describe("subagent tool contract [MANDATORY]", () => {
         action: "start",
         startParam: {
           task: "isolated work",
+          slug: "iso-work",
           fork: true,
           worktree: true,
           cwd: "/x",

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

@@ -244,4 +244,50 @@ describe("maybeCleanupExpiredSessionFiles", () => {
     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);
+  });
 });

package/src/execution/__tests__/session-reconstructor.test.ts

@@ -167,6 +167,26 @@ describe("reconstructFromFile", () => {
       expect(rec!.rootSessionId).toBeUndefined();
     });
 
+    it("读出 identity 里的 slug", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", slug: "extract-urls", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.slug).toBe("extract-urls");
+    });
+
+    it("旧文件 identity 无 slug → 兜底空串（向后兼容）", () => {
+      writeJsonl([
+        headerLine(),
+        identityEntry({ id: "bg-1", agent: "w", mode: "background", task: "t", startedAt: 100 }),
+        assistantEntry([{ type: "text", text: "ok" }]),
+      ]);
+      const rec = reconstructFromFile(filePath);
+      expect(rec!.slug).toBe("");
+    });
+
     it("读出 identity 里的 parentRecordId/depth（递归层级）", () => {
       writeJsonl([
         headerLine(),

package/src/execution/__tests__/session-start-reaper.test.ts

@@ -58,10 +58,12 @@ vi.mock("../session-file-gc.ts", () => ({
 }));
 
 // mock subagent-service：避免真正构造 SubagentService（它依赖 ModelConfigService 等）
-const { mockInitModel, mockInitSession, mockSetModelConfigService, mockSetSubagentService, capturedConstructorArg } =
+const { mockInitModel, mockInitSession, mockSetUiRequestHandler, mockSetModelConfigService, mockSetSubagentService, capturedConstructorArg } =
   vi.hoisted(() => ({
     mockInitModel: vi.fn(),
     mockInitSession: vi.fn(),
+    // W3: index.ts session_start 注入 UI handler 时调用
+    mockSetUiRequestHandler: vi.fn(),
     mockSetModelConfigService: vi.fn(),
     mockSetSubagentService: vi.fn(),
     capturedConstructorArg: { current: undefined as unknown },
@@ -80,6 +82,8 @@ vi.mock("../model-config-service.ts", () => ({
 vi.mock("../subagent-service.ts", () => ({
   SubagentService: class {
     initSession = mockInitSession;
+    // W3: index.ts session_start 注入 UI handler 时调用
+    setUiRequestHandler = mockSetUiRequestHandler;
     constructor(init: unknown) {
       capturedConstructorArg.current = init;
     }
@@ -136,6 +140,8 @@ function createMockPi(overrides: Record<string, unknown> = {}): {
 function createMockCtx(overrides: Record<string, unknown> = {}): Record<string, unknown> {
   return {
     cwd: "/home/user/project",
+    // [Wave1 #21] mode 必填（与 SDK ExtensionContext 契约一致）；默认 tui。
+    mode: "tui",
     modelRegistry: { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => false },
     model: undefined,
     sessionManager: {