@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,933 @@
+// src/__tests__/run-spawn-integration.test.ts
+//
+// runSpawn 集成测试（spawn 改造核心函数）。
+//
+// runSpawn 负责 spawn pi 子进程、pump stdout JSON 事件流、signal/maxTurns 终止、
+// identity 补写、exitCode 判定。此前完全无集成测试——本文件覆盖审查发现的关键路径。
+//
+// mock 策略（参考 worktree-manager.test.ts 的 mock 模式）：
+//   - node:child_process.spawn → 返回 FakeChild（EventEmitter + PassThrough），
+//     测试用控制器 emit data/close/error 控制时序。
+//   - node:child_process.execFile → err-first callback 默认兜底（buildEnvBlock 的 git
+//     branch 调用失败 → catch → branch=""）。
+//   - node:fs 同步方法 → mock（mkdirSync/existsSync/appendFileSync/writeFileSync 等），
+//     避免 sessionDir/sessionFile 触碰真实文件系统。
+//   - 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 { spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── mock modules（工厂体共享自 helpers/spawn-mock.ts；vi.mock 必须各文件独立声明）──
+
+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")),
+    ),
+  };
+});
+
+// node:fs：同步方法 mock（runSpawn 用到的全部），promises 保留真实实现（temp-prompt 用）。
+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(),
+}));
+
+// temp-prompt：mock 掉真实 fs.promises I/O（mkdtemp/writeFile/rm）。
+// 原先保留真实实现导致 fake-timers 测试偶发 flaky——writePromptToTempFile 的真实异步
+// I/O 在 CI 慢机器上无法在 advanceTimersByTimeAsync 的有限步数内 resolve，spawn 永不触发。
+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,
+  sessionHeader,
+  waitForSpawn as waitForSpawnOf,
+} from "./helpers/spawn-mock.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockExistsSync = vi.mocked(fs.existsSync);
+const mockAppendFileSync = vi.mocked(fs.appendFileSync);
+const mockMkdirSync = vi.mocked(fs.mkdirSync);
+
+// 绑定到本文件 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);
+
+// ============================================================
+// 测试
+// ============================================================
+
+describe("runSpawn", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // existsSync 默认 false（sessionFile 不存在兜底路径）
+    mockExistsSync.mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // ── 1. 正常路径（happy path）──
+  describe("正常路径", () => {
+    it("header + turn_end 事件 + close(0) → success=true，record.sessionFile 被设置，turnCount 正确", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: hello", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      const expectedSessionFile =
+        "/tmp/test/agents/subagents/--tmp-test--/sessions/2026-07-03T12-00-00-000Z_sess-abc.jsonl";
+      // 进程退出后 existsSync(record.sessionFile) 校验通过 → 补写 identity
+      mockSessionFileExists(expectedSessionFile);
+
+      // emit stdout：header + 2 个 turn_end
+      emitStdoutLine(child, sessionHeader("sess-abc"));
+      emitStdoutLine(child, { type: "turn_end" });
+      emitStdoutLine(child, { type: "turn_end" });
+      child.stdout.end();
+      child.emit("close", 0);
+
+      const result = await promise;
+
+      expect(result.success).toBe(true);
+      expect(result.turns).toBe(2); // 2 个 turn_end
+      expect(record.turnCount).toBe(2);
+      // record.sessionFile 由 header 推导路径回填
+      expect(record.sessionFile).toBe(expectedSessionFile);
+      expect(result.sessionFile).toBe(expectedSessionFile);
+      // sessionId 来自 header.id
+      expect(result.sessionId).toBe("sess-abc");
+    });
+
+    it("collectResult 文本/toolCalls 从 record 派生（text_delta + tool 调用累积进 turns）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: write", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+      mockSessionFileExists(
+        "/tmp/test/agents/subagents/--tmp-test--/sessions/2026-07-03T12-00-00-000Z_sess-x.jsonl",
+      );
+
+      emitStdoutLine(child, sessionHeader("sess-x"));
+      emitStdoutLine(child, { type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "Hello " } });
+      emitStdoutLine(child, { type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "world" } });
+      emitStdoutLine(child, { type: "tool_execution_start", toolCallId: "t1", toolName: "bash", args: { command: "ls" } });
+      emitStdoutLine(child, { type: "tool_execution_end", toolCallId: "t1", toolName: "bash", result: { details: "file.txt" } });
+      emitStdoutLine(child, { type: "turn_end" });
+      child.stdout.end();
+      child.emit("close", 0);
+
+      const result = await promise;
+
+      expect(result.success).toBe(true);
+      expect(result.text).toBe("Hello world");
+      expect(result.toolCalls).toHaveLength(1);
+      expect(result.toolCalls[0]!.toolName).toBe("bash");
+      expect(result.toolCalls[0]!.result?.details).toBe("file.txt");
+    });
+  });
+
+  // ── 2. signal abort → child.kill（cancel 路径）──
+  describe("signal abort", () => {
+    it("abort signal 触发后 child.kill(SIGTERM) 被调用，success=false", async () => {
+      const controller = new AbortController();
+      const record = makeRecord();
+      const promise = runSpawn(
+        record,
+        "Task: long",
+        makeOpts({ signal: controller.signal }),
+        makeCtx(),
+      );
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // abort 必须在 spawn 之后（addEventListener 已注册）。
+      // 用 queueMicrotask 延迟到当前微任务清空后触发，确保 listener 已挂载。
+      queueMicrotask(() => controller.abort());
+
+      // emit header + close（被 kill 后子进程退出，signal 终止 exitCode>=128 或 null）
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 143); // SIGTERM = 128+15
+
+      const result = await promise;
+
+      expect(child.killed).toBe(true);
+      expect(child.killSignal).toBe("SIGTERM");
+      // signal.aborted 路径：success=false，但 error 为 undefined（取消不算 error）
+      expect(result.success).toBe(false);
+      expect(result.error).toBeUndefined();
+    });
+  });
+
+  // ── 3. maxTurns → limiter.abort → proc.kill ──
+  describe("maxTurns 限制", () => {
+    it("maxTurns=1, graceTurns=0 → 超出 turn 后 child.kill 被调用，success=true（达限视为正常完成）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(
+        record,
+        "Task: bounded",
+        makeOpts({ maxTurns: 1, graceTurns: 0 }),
+        makeCtx(),
+      );
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      // 第 1 个 turn_end：turn=1 >= maxTurns=1 → steer（noop）
+      emitStdoutLine(child, { type: "turn_end" });
+      // 第 2 个 turn_end：turn=2 >= maxTurns(1)+graceTurns(0)=1 → abort → proc.kill
+      emitStdoutLine(child, { type: "turn_end" });
+      child.stdout.end();
+      // 被 kill 后信号终止（exitCode>=128），视为正常完成
+      child.emit("close", 143);
+
+      const result = await promise;
+
+      expect(child.killed).toBe(true);
+      expect(child.killSignal).toBe("SIGTERM");
+      // maxTurns kill 视为正常完成（exitCode>=128 走信号终止分支 → success=true）
+      expect(result.success).toBe(true);
+    });
+
+    it("maxTurns=2, graceTurns=2 → steer 后需 graceTurns 到达才 kill（第 4 turn 才 abort）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(
+        record,
+        "Task: grace",
+        makeOpts({ maxTurns: 2, graceTurns: 2 }),
+        makeCtx(),
+      );
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // emit header + 4 个 turn_end。limiter 逻辑（maxTurns=2, graceTurns=2）：
+      //   turn=1: 1<2，无动作
+      //   turn=2: 2>=limit → steer（仅一次）
+      //   turn=3: 3<limit+grace(4)，仍在宽限内
+      //   turn=4: 4>=4 → abort → proc.kill(SIGTERM)
+      // 注：PassThrough 流加 data 监听器后，缓冲块逐个在后续微任务中 flush，close 前 await
+      // 较长时间窗（20ms）确保全部 turn_end 已被 data 处理器消费（含 limiter.abort → kill）。
+      emitStdoutLine(child, sessionHeader());
+      emitStdoutLine(child, { type: "turn_end" }); // turn=1
+      emitStdoutLine(child, { type: "turn_end" }); // turn=2: steer
+      emitStdoutLine(child, { type: "turn_end" }); // turn=3: 宽限内
+      emitStdoutLine(child, { type: "turn_end" }); // turn=4: abort → kill
+      child.stdout.end();
+      await new Promise((r) => setTimeout(r, 20));
+      child.emit("close", 143);
+
+      const result = await promise;
+
+      // 第 4 个 turn_end 触发 abort → child.kill(SIGTERM)
+      expect(child.killed).toBe(true);
+      expect(child.killSignal).toBe("SIGTERM");
+      expect(record.turnCount).toBe(4);
+      // exitCode>=128（信号终止）→ success=true（达限视为正常完成）
+      expect(result.success).toBe(true);
+    });
+  });
+
+  // ── 4. 子进程非零退出（exitCode < 128）──
+  describe("非零退出码", () => {
+    it("close(1) + stderr 内容 → success=false，error 含 stderr", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: fail", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      child.stderr.write("Error: something went wrong\n");
+      child.stderr.end();
+      child.stdout.end();
+      child.emit("close", 1);
+
+      const result = await promise;
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("something went wrong");
+    });
+
+    it("close(1) 无 stderr → error 含 exit code 信息", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: fail", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 1);
+
+      const result = await promise;
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("exited with code 1");
+    });
+  });
+
+  // ── 5. 子进程被信号终止（exitCode = null 或 >= 128）──
+  describe("信号终止", () => {
+    it("close(null) → success=true（信号终止视为正常，非 aborted）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: sig", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", null);
+
+      const result = await promise;
+
+      expect(result.success).toBe(true);
+    });
+
+    it("close(143)（SIGTERM，>=128）无 signal → success=true", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: sig143", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 143);
+
+      const result = await promise;
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  // ── 6. spawn 本身失败（error 事件，如 ENOENT）──
+  describe("spawn error 事件", () => {
+    it("child.emit('error') → success=false，error 含错误信息，record.lastError 被设置", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: enoent", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // spawn error 事件（command not found 等）——runSpawn 的 error handler resolve(128)
+      child.emit("error", new Error("spawn ENOENT"));
+
+      const result = await promise;
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("spawn ENOENT");
+      expect(record.lastError).toContain("spawn ENOENT");
+    });
+
+    it("[worktree-reaper-fix] ENOENT error 消息拼 spawnCwd（避免误诊 node 被卸载）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: enoent-cwd", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // ENOENT 且带 code（Node spawn 失败的真实形态）——error handler 必须拼 spawnCwd
+      const err = Object.assign(new Error("spawn ENOENT"), { code: "ENOENT" });
+      child.emit("error", err);
+
+      const result = await promise;
+
+      expect(result.success).toBe(false);
+      // makeCtx().cwd = "/tmp/test"，无 worktree 时 spawnCwd = ctx.cwd
+      expect(record.lastError).toContain("/tmp/test");
+    });
+  });
+
+  // ── 7. identity 写入职责（M4 / V2 决策 5：迁移到子进程 session_start）──
+  describe("identity 写入职责", () => {
+    it("正常 close 后 session-runner 不再 fs 补写 identity（M4 迁移到子进程 session_start）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: identity", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      const sessionFile =
+        "/tmp/test/agents/subagents/--tmp-test--/sessions/2026-07-03T12-00-00-000Z_sess-id.jsonl";
+      mockSessionFileExists(sessionFile);
+
+      emitStdoutLine(child, sessionHeader("sess-id"));
+      emitStdoutLine(child, { type: "turn_end" });
+      child.stdout.end();
+      child.emit("close", 0);
+
+      await promise;
+
+      // [M4 / V2 决策 5] identity 不再由 session-runner fs.appendFileSync 补写——
+      // 改由子进程 session_start hook 用 pi.appendEntry 写（pi 自动生成 id/parentId，
+      // 修复旧 fs 补写缺 id/parentId 污染 _buildIndex 的 bug）。identity 写入由
+      // index-session-start-identity.test.ts 覆盖；此处守护 session-runner 不再 fs 写。
+      expect(mockAppendFileSync).not.toHaveBeenCalled();
+    });
+
+    it("sessionFile 不存在（existsSync=false）→ 不补写 identity（不调 appendFileSync）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: nofile", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // existsSync 全返回 false（默认）→ record.sessionFile 经兜底查找仍不存在
+      emitStdoutLine(child, sessionHeader("sess-none"));
+      child.stdout.end();
+      child.emit("close", 0);
+
+      await promise;
+
+      expect(mockAppendFileSync).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── 8. fork depth 环境变量传递 ──
+  describe("fork depth 环境变量", () => {
+    it("fork=true, parentForkDepth=2 → spawn env 含 PI_SUBAGENT_FORK_DEPTH=3", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(
+        record,
+        "Task: fork",
+        makeOpts({ fork: true, parentForkDepth: 2 }),
+        makeCtx({ mainSessionFile: "/tmp/main.jsonl" }),
+      );
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+
+      await promise;
+
+      // spawn 第 3 参数是 options（含 env）
+      const spawnOpts = mockSpawn.mock.calls[0]?.[2] as { env: Record<string, string> };
+      expect(spawnOpts.env.PI_SUBAGENT_FORK_DEPTH).toBe("3");
+    });
+
+    it("fork=false → spawn env 不含 PI_SUBAGENT_FORK_DEPTH", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: nofork", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+
+      await promise;
+
+      const spawnOpts = mockSpawn.mock.calls[0]?.[2] as { env: Record<string, string | undefined> };
+      expect(spawnOpts.env.PI_SUBAGENT_FORK_DEPTH).toBeUndefined();
+    });
+
+    it("spawn 参数含 --session-dir 且 cwd 来自 ctx.cwd", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: args", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+
+      await promise;
+
+      // spawn(command, args, opts)：args 是数组，应含 --session-dir
+      const args = mockSpawn.mock.calls[0]?.[1] as string[];
+      const sessionDirIdx = args.indexOf("--session-dir");
+      expect(sessionDirIdx).toBeGreaterThanOrEqual(0);
+      expect(args[sessionDirIdx + 1]).toContain("--tmp-test--");
+      // spawn opts.cwd 来自 ctx.cwd（无 worktree 时）
+      const spawnOpts = mockSpawn.mock.calls[0]?.[2] as { cwd: string };
+      expect(spawnOpts.cwd).toBe("/tmp/test");
+    });
+  });
+
+  // ── 9. onEvent 回调 ──
+  describe("onEvent 回调", () => {
+    it("stdout 事件经 handleSdkEvent 翻译后回调 opts.onEvent", async () => {
+      const onEvent = vi.fn();
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: events", makeOpts({ onEvent }), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      emitStdoutLine(child, { type: "turn_end" });
+      child.stdout.end();
+      child.emit("close", 0);
+
+      await promise;
+
+      // onEvent 至少被 turn_end 调过一次（onEvent 签名是单参数 event）
+      const turnEndCalls = onEvent.mock.calls.filter(([ev]) => (ev as { type: string }).type === "turn_end");
+      expect(turnEndCalls.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  // ── 10. sessionDir 创建 ──
+  describe("sessionDir 创建", () => {
+    it("mkdirSync 以 recursive 创建 sessionDir", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: mkdir", makeOpts(), makeCtx());
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+
+      await promise;
+
+      expect(mockMkdirSync).toHaveBeenCalledWith(
+        "/tmp/test/agents/subagents/--tmp-test--/sessions",
+        { recursive: true },
+      );
+    });
+  });
+
+  // ── 11. 临时 prompt 文件清理 ──
+  describe("临时 prompt 文件清理", () => {
+    it("有 appendSystemPrompt → 创建临时文件并在 finally 清理（spawn 退出后目录消失）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(
+        record,
+        "Task: cleanup",
+        makeOpts({ appendSystemPrompt: ["extra instructions"] }),
+        makeCtx(),
+      );
+
+      // 等待 spawn 被调用拿到 child
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+
+      await promise;
+
+      // temp-prompt 已 mock（见文件顶部 vi.mock），返回固定文件名；
+      // 验证 spawn args 含 --append-system-prompt（说明临时文件路径被传给子进程）
+      const args = mockSpawn.mock.calls[0]?.[1] as string[];
+      const appendIdx = args.indexOf("--append-system-prompt");
+      expect(appendIdx).toBeGreaterThanOrEqual(0);
+      expect(args[appendIdx + 1]).toMatch(/prompt-general-purpose\.md$/);
+    });
+  });
+
+  // ── 12. watchdog 超时兜底（R1）──
+  //
+  // [R0/R1] SPAWN_WATCHDOG_MS = 30 * 60 * 1000（session-runner.ts 顶部）。
+  // 子进程卡死在单 tool 内（turn_end 永不触发）时 limiter 失效，watchdog timer 兜底 SIGTERM，
+  // 防止 background 槽位/资源泄漏。timer 加了 .unref()（不阻止 Node 退出）。
+  //
+  // fake timers 方案 A：describe 块内 beforeEach useFakeTimers、afterEach useRealTimers。
+  // 难点：waitForSpawn 内部用 `await new Promise(r => setTimeout(r, 5))` 轮询，fake timers 下
+  // 该 setTimeout 不会自动触发——改用 vi.advanceTimersByTimeAsync 推进时间，它会同步 flush
+  // 已到期的 timer + 让挂起的真实 I/O（writePromptToTempFile 的 fs.promises）resolve。
+  // 关键验证：unref 的 timer 在 fake timers 下仍能被 advanceTimersByTime 触发（vitest fake
+  // timers 忽略 unref）。
+  describe("watchdog 超时兜底 (R1)", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    /**
+     * fake timers 下推进时间直到 spawn 被调用（替代 waitForSpawn，返回 child 控制器）。
+     *
+     * [快照语义] 同 helpers/spawn-mock.ts 的 waitForSpawn：记调用时 baseline，等待其后的
+     * **新** spawn——支持同一测试/文件内多次 runSpawn。
+     *
+     * runSpawn 在 mkdirSync + writePromptToTempFile（真实 fs.promises I/O）之后才调 spawn。
+     * 每次推进 10ms 让轮询 setTimeout 触发；同时 advanceTimersByTimeAsync flush 已 resolve
+     * 的 I/O promise，使 runSpawn 继续走到 spawn。
+     */
+    async function waitForSpawnFake(timeoutSteps = 200): Promise<FakeChild> {
+      const baseline = mockSpawn.mock.results.length;
+      for (let i = 0; i < timeoutSteps; i++) {
+        if (mockSpawn.mock.results.length > baseline) break;
+        await vi.advanceTimersByTimeAsync(10);
+      }
+      if (mockSpawn.mock.results.length <= baseline) {
+        throw new Error("spawn was not called (fake timers did not progress to spawn)");
+      }
+      return lastSpawnedChild();
+    }
+
+    it("watchdog 超时（>30min）→ child.kill(SIGTERM) 被调用", async () => {
+      const record = makeRecord();
+      // 不 await——runSpawn 内部 await 子进程 close，watchdog 触发 kill 后还需 emit close 才 resolve
+      // [M-1] maxTurns=6 使 computeWatchdogMs 返回下限 30min（max(30min, 6*5min) = 30min）
+      const promise = runSpawn(record, "Task: hang", makeOpts({ maxTurns: 6 }), makeCtx());
+
+      const child = await waitForSpawnFake();
+
+      // spawn 后 child.killed 应为 false（watchdog 尚未触发）
+      expect(child.killed).toBe(false);
+
+      // 推进时间越过 watchdog 阈值（30 * 60 * 1000 + 100ms 余量）
+      await vi.advanceTimersByTimeAsync(30 * 60 * 1000 + 100);
+
+      // watchdog 触发 child.kill("SIGTERM")
+      expect(child.killed).toBe(true);
+      expect(child.killSignal).toBe("SIGTERM");
+
+      // 收尾：emit close 让 runSpawn 的 await promise resolve（避免悬挂）
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 143); // SIGTERM = 128+15
+
+      const result = await promise;
+      // 信号终止（>=128）视为正常完成
+      expect(result.success).toBe(true);
+    });
+
+    it("正常 close(0) → clearTimeout 生效，watchdog 不触发 kill", async () => {
+      const record = makeRecord();
+      // [M-1] maxTurns=6 使 watchdog=30min（与上面 watchdog 触发测试同基准）
+      const promise = runSpawn(record, "Task: quick", makeOpts({ maxTurns: 6 }), makeCtx());
+
+      const child = await waitForSpawnFake();
+
+      // 正常完成：emit header + close(0)
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.emit("close", 0);
+
+      const result = await promise;
+      expect(result.success).toBe(true);
+
+      // close 后 runSpawn 已 clearTimeout(watchdog)；推进 30+ 分钟验证 watchdog 未触发 kill
+      await vi.advanceTimersByTimeAsync(30 * 60 * 1000 + 100);
+
+      expect(child.killed).toBe(false);
+      expect(child.killSignal).toBeUndefined();
+    });
+  });
+
+  // ── 13. stderr 截断防 OOM（R2）──
+  //
+  // [R2] stderrBuffer = (stderrBuffer + data).slice(-STDERR_MAX_CHARS)（STDERR_MAX_CHARS=64*1024）。
+  // 失控子进程打满 stderr 会耗尽父进程内存；保留尾部 64KB 用于 error 诊断。
+  describe("stderr 截断防 OOM (R2)", () => {
+    it("stderr > 64KB → error 中的 stderr 内容是尾部 64KB（尾部标记保留，头部标记被截断）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: noisy stderr", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // 头部标记（应被截断）：足够长的前缀让 64KB 窗口推过它
+      const HEAD_MARKER = "HEAD_MARKER_HEAD_MARKER";
+      child.stderr.write(HEAD_MARKER);
+      // 填充 > 64KB 的噪声（用 "x" 重复），把头部标记推出 64KB 尾部窗口
+      child.stderr.write("x".repeat(70 * 1024));
+      // 尾部标记（应在截断后仍保留）
+      child.stderr.write("TAIL_MARKER_TAIL_MARKER");
+
+      emitStdoutLine(child, sessionHeader());
+      child.stderr.end();
+      child.stdout.end();
+      child.emit("close", 1); // 非零退出 → error 含 stderr
+
+      const result = await promise;
+
+      // 非零退出码 → success=false
+      expect(result.success).toBe(false);
+      // error 含尾部标记（证明保留了尾部 64KB）
+      expect(result.error).toContain("TAIL_MARKER_TAIL_MARKER");
+      // error 不含头部标记（证明头部被截断丢弃）
+      expect(result.error).not.toContain(HEAD_MARKER);
+    });
+  });
+
+  // ── 14. UTF-8 编码跨 chunk 安全（R3）──
+  //
+  // [R3] child.stdout.setEncoding("utf8") 让流按字符边界切分，避免多字节 UTF-8
+  //（CJK/emoji）跨 chunk 时 toString() 产生 U+FFFD 替换符导致 JSON.parse 失败。
+  //
+  // 测法选择：用流状态（readableEncoding）验证 setEncoding("utf8") 被 runSpawn 调用过。
+  // 为什么不用 spy：runSpawn 在 spawn() 返回后同步调用 setEncoding，而 waitForSpawn 拿到
+  // child 时调用已完成，无法事后挂 spy 捕获。readableEncoding 是 PassThrough(Readable) 暴露的
+  // 只读属性，setEncoding("utf8") 后值变为 "utf8"，是"编码确实被设置"的可靠证据。
+  // 端到端分片写多字节字符无法真正模拟"字节边界切断"（PassThrough + setEncoding 已在更高层
+  // 合并），故补一个"分片写入仍能解析"的用例佐证行缓冲健壮性。
+  describe("UTF-8 编码跨 chunk 安全 (R3)", () => {
+    it("runSpawn 对 child.stdout 和 child.stderr 调用 setEncoding('utf8')（readableEncoding 验证）", async () => {
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: utf8", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // spawn 后 runSpawn 已同步调用 setEncoding("utf8")：readableEncoding 反映该调用结果
+      expect(child.stdout.readableEncoding).toBe("utf8");
+      expect(child.stderr.readableEncoding).toBe("utf8");
+
+      emitStdoutLine(child, sessionHeader());
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+
+      const result = await promise;
+      expect(result.success).toBe(true);
+    });
+
+    it("stdout 多次分片写入同一 JSON 行仍能正确解析 turn_end（行缓冲合并）", async () => {
+      // 端到端验证：数据分两次 write，runSpawn 的行缓冲（stdoutBuffer += data）合并后解析。
+      // 此用例验证"分片写入仍能解析"，setEncoding("utf8") 已由上一用例覆盖。
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task: split", makeOpts(), makeCtx());
+
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+
+      // header 完整一行
+      emitStdoutLine(child, sessionHeader());
+      // turn_end 拆成两半写入（跨 chunk 模拟）
+      child.stdout.write('{"type":"turn_e');
+      child.stdout.write('nd"}\n');
+      child.stdout.end();
+      child.emit("close", 0);
+
+      const result = await promise;
+
+      expect(result.success).toBe(true);
+      expect(record.turnCount).toBe(1); // 拆开的 turn_end 仍被解析为 1 次
+    });
+  });
+
+  // ── 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。
+
+  // ============================================================
+  // E2E：runSpawn 从主进程 process.argv 镜像 extension/approve flag 到子进程
+  // 验证完整链路：runSpawn 真实执行 → 读 process.argv → buildSpawnArgs 拼参 →
+  // spawn 收到的 args 含镜像 flag。spawn 被 mock（FakeChild），但 runSpawn 体内逻辑
+  // 全真实跑，process.argv 用真实进程变量（测试中临时覆写 + 还原）。
+  // ============================================================
+  describe("E2E: 镜像主进程 argv flag 到子进程 spawn args", () => {
+    const originalArgv = process.argv;
+
+    afterEach(() => {
+      process.argv = originalArgv;
+    });
+
+    it("主进程 argv 含 --extension/--no-extensions/--approve → 子进程 spawn args 全部镜像", async () => {
+      // 模拟主 pi 进程启动参数（xyz-agent runtime 启动 pi 的真实形态）
+      process.argv = [
+        "bun", "/path/to/pi",
+        "--mode", "rpc",
+        "--no-extensions",
+        "--approve",
+        "--extension", "/exts/goal",
+        "--extension", "/exts/todo",
+        "--session-dir", "/sessions",
+      ];
+
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task", makeOpts(), makeCtx());
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+      mockSessionFileExists(
+        "/tmp/test/agents/subagents/--tmp-test--/sessions/2026-07-03T12-00-00-000Z_sess-mirror.jsonl",
+      );
+      emitStdoutLine(child, sessionHeader("sess-mirror"));
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+      await promise;
+
+      // 断言 spawn 收到的调用参数含全部镜像 flag
+      const spawnCall = mockSpawn.mock.calls[0];
+      // spawn(command, args, options) → args 是第二个参数
+      const spawnArgs = spawnCall[1] as string[];
+
+      expect(spawnArgs).toContain("--no-extensions");
+      expect(spawnArgs).toContain("--approve");
+      // 两个 extension 路径都镜像，顺序保留
+      const extIdxs = spawnArgs
+        .map((a, i) => (a === "--extension" ? i : -1))
+        .filter((i) => i >= 0);
+      expect(extIdxs).toHaveLength(2);
+      expect(spawnArgs[extIdxs[0] + 1]).toBe("/exts/goal");
+      expect(spawnArgs[extIdxs[1] + 1]).toBe("/exts/todo");
+    });
+
+    it("主进程 argv 无目标 flag → 子进程 spawn args 不含镜像 flag（向后兼容）", async () => {
+      // 模拟纯 pi CLI 直接跑（无 extension/approve 配置）
+      process.argv = ["bun", "/path/to/pi", "--mode", "rpc"];
+
+      const record = makeRecord();
+      const promise = runSpawn(record, "Task", makeOpts(), makeCtx());
+      await waitForSpawn();
+      const child = lastSpawnedChild();
+      mockSessionFileExists(
+        "/tmp/test/agents/subagents/--tmp-test--/sessions/2026-07-03T12-00-00-000Zsess-noflag.jsonl",
+      );
+      emitStdoutLine(child, sessionHeader("sess-noflag"));
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0);
+      await promise;
+
+      const spawnCall = mockSpawn.mock.calls[0];
+      const spawnArgs = spawnCall[1] as string[];
+
+      expect(spawnArgs).not.toContain("--no-extensions");
+      expect(spawnArgs).not.toContain("--approve");
+      expect(spawnArgs).not.toContain("--extension");
+    });
+  });
+});