@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

package/src/execution/__tests__/run-spawn-chatmode-settled.test.ts

@@ -0,0 +1,253 @@
+// src/execution/__tests__/run-spawn-chatmode-settled.test.ts
+//
+// [V2 模块 3] chatMode agent_settled 信号换挂单测（Step 3）。
+//
+// 验证 session-runner 的 V2 改动（5 处）：
+//   ① chatMode record agent_end 不触发 SIGTERM（进程保活，等 agent_settled）
+//   ② chatMode record agent_settled 触发 armIdleTimer（fake timer + 超时后 kill）
+//   ③ chatMode agent_settled 调 ctx.onRoundSettled（挂载点，mock 断言被调）
+//   ④ 非 chatMode agent_settled 不 armIdleTimer、不调 onRoundSettled
+//
+// mock 结构与 run-spawn-edges.test.ts 一致（FakeChild + session-pending 受控 count=0）。
+// lifecycle-manager 用真实模块（hasIdleTimer / _resetLifecycleState 可观测 + 隔离）。
+
+import { 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()),
+    // 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(),
+}));
+
+// chatMode 测试不依赖后代判定（chatMode agent_end 早返回跳过 readActivePending），统一 count=0。
+// 非 chatMode 用例 ④ 的 agent_end 走正常 kill 分支（count=0 → SIGTERM）。
+vi.mock("../session-pending.ts", () => ({
+  readActivePendingFromSessionFile: vi.fn(() => ({ count: 0 })),
+}));
+
+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 type { SessionRunnerContext } from "../session-runner.ts";
+import {
+  DEFAULT_IDLE_TIMEOUT_MS,
+  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（spawn-mock.makeRecord 默认非 chatMode，此处显式开启）。 */
+function makeChatModeRecord(id = "sa-chat"): 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,
+  });
+}
+
+describe("[V2 模块 3] chatMode agent_settled 信号换挂", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // lifecycle-manager 是模块级单例（idleTimers Map 跨用例共享），每用例前清空防泄漏。
+    _resetLifecycleState();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+    _resetLifecycleState();
+  });
+
+  it("① chatMode agent_end → 不触发 SIGTERM（进程保活，等 agent_settled）", async () => {
+    const record = makeChatModeRecord("sa-chat-end");
+    const promise = runSpawn(record, "Task: chatmode-end", makeOpts(), makeCtx());
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    emitStdoutLine(child, sessionHeader());
+    emitStdoutLine(child, { type: "agent_end", willRetry: false });
+    // 让事件 pump 处理 agent_end（stream flush 异步）
+    await new Promise((r) => setTimeout(r, 20));
+
+    // [V2 决策 1] chatMode agent_end 不 kill——进程不因轮次死，等 agent_settled。
+    expect(child.killed).toBe(false);
+    // agent_end 不 arm idle timer（arm 点是 agent_settled，不是 agent_end）
+    expect(hasIdleTimer(record.id)).toBe(false);
+
+    // 收尾：手动 close 让 runSpawn resolve（模拟后续 idle timer 超时 kill / 外部终止）
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 143);
+    const result = await promise;
+    expect(result.success).toBe(true);
+  });
+
+  it("② chatMode agent_settled → armIdleTimer，idle 超时后 SIGTERM kill", async () => {
+    const record = makeChatModeRecord("sa-chat-settled");
+    const promise = runSpawn(record, "Task: chatmode-settled", makeOpts(), makeCtx());
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    // 必须在 emit agent_settled 前启用 fake timers——armIdleTimer 内 setTimeout 在 agent_settled
+    // 处理器里新建，新建时已是 fake timer 才可 advance。不 fake setImmediate：stream flush 靠
+    // 真实事件循环。对齐 run-spawn-edges MF-3/MF-4 模式。
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
+    try {
+      emitStdoutLine(child, sessionHeader());
+      emitStdoutLine(child, { type: "agent_end", willRetry: false });
+      await new Promise((r) => setImmediate(r));
+      emitStdoutLine(child, { type: "agent_settled" });
+      await new Promise((r) => setImmediate(r));
+
+      // agent_settled → arm idle timer（DEFAULT_IDLE_TIMEOUT_MS = 5min）
+      expect(hasIdleTimer(record.id)).toBe(true);
+      // 进程仍存活（idle timer 未到期）
+      expect(child.killed).toBe(false);
+
+      // 未到 idle timeout（5min - 1ms）：不 kill
+      await vi.advanceTimersByTimeAsync(DEFAULT_IDLE_TIMEOUT_MS - 1);
+      expect(child.killed).toBe(false);
+
+      // idle timeout 到期：onTimeout → child.kill("SIGTERM")（复用现有 kill 路径）
+      await vi.advanceTimersByTimeAsync(1);
+      expect(child.killed).toBe(true);
+      expect(child.killSignal).toBe("SIGTERM");
+      // timer 触发后从 Map 移除（armIdleTimer 内 setTimeout 回调 idleTimers.delete）
+      expect(hasIdleTimer(record.id)).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+
+    // 收尾：close 让 runSpawn resolve
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 143);
+    const result = await promise;
+    expect(result.success).toBe(true);
+  });
+
+  it("③ chatMode agent_settled → 调 ctx.onRoundSettled（Step 3 挂载点，回调被调 1 次）", async () => {
+    const record = makeChatModeRecord("sa-chat-cb");
+    const onRoundSettled = vi.fn();
+    const ctx: SessionRunnerContext = makeCtx({ onRoundSettled });
+    const promise = runSpawn(record, "Task: chatmode-cb", makeOpts(), ctx);
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    emitStdoutLine(child, sessionHeader());
+    emitStdoutLine(child, { type: "agent_end", willRetry: false });
+    await new Promise((r) => setTimeout(r, 10));
+    emitStdoutLine(child, { type: "agent_settled" });
+    await new Promise((r) => setTimeout(r, 10));
+
+    // agent_settled → onRoundSettled 被调，入参是当前 record
+    expect(onRoundSettled).toHaveBeenCalledTimes(1);
+    expect(onRoundSettled).toHaveBeenCalledWith(record);
+
+    // 收尾：手动 close（idle timer 仍 armed，由 afterEach _resetLifecycleState 清理）
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 143);
+    const result = await promise;
+    expect(result.success).toBe(true);
+  });
+
+  it("④ 非 chatMode agent_settled → 不 armIdleTimer、不调 onRoundSettled", async () => {
+    // makeRecord 默认非 chatMode（createRecord 未传 chatMode）
+    const record = makeRecord("sa-nonchat-settled");
+    const onRoundSettled = vi.fn();
+    const ctx: SessionRunnerContext = makeCtx({ onRoundSettled });
+    const promise = runSpawn(record, "Task: nonchat-settled", makeOpts(), ctx);
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    emitStdoutLine(child, sessionHeader());
+    // 直接 emit agent_settled（非 chatMode：handler 应忽略，不 arm、不调回调）
+    emitStdoutLine(child, { type: "agent_settled" });
+    await new Promise((r) => setTimeout(r, 20));
+
+    expect(hasIdleTimer(record.id)).toBe(false);
+    expect(onRoundSettled).not.toHaveBeenCalled();
+
+    // 收尾：emit agent_end 走正常 kill 分支（count=0 → SIGTERM）→ close resolve
+    emitStdoutLine(child, { type: "agent_end", willRetry: false });
+    await new Promise((r) => setTimeout(r, 10));
+    expect(child.killed).toBe(true); // 非 chatMode agent_end → kill（现有行为，V2 不动）
+
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 143);
+    const result = await promise;
+    expect(result.success).toBe(true);
+  });
+});

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

@@ -11,7 +11,7 @@
 // mock 工厂 + FakeChild + 工具函数共享自 helpers/spawn-mock.ts（详见该文件头注释）。
 // vi.mock 必须各文件独立声明（文件作用域），工厂内用 `await import` 取回 FakeChild。
 
-import { execFileSync, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -20,7 +20,15 @@ vi.mock("node:child_process", async () => {
   const { FakeChild } = await import("./helpers/spawn-mock.ts");
   return {
     spawn: vi.fn(() => new FakeChild()),
-    execFileSync: vi.fn(() => ""),
+    // 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")),
+    ),
   };
 });
 
@@ -75,7 +83,6 @@ import {
 } from "./helpers/spawn-mock.ts";
 
 const mockSpawn = vi.mocked(spawn);
-const mockExec = vi.mocked(execFileSync);
 const mockExistsSync = vi.mocked(fs.existsSync);
 
 // 绑定到本文件 mockSpawn 的 lastSpawnedChild/waitForSpawn（需读 mockSpawn.mock.results）
@@ -89,8 +96,6 @@ const waitForSpawn = (timeoutMs = 1000): Promise<void> => waitForSpawnOf(mockSpa
 describe("runSpawn", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    // execFileSync 默认返回空串（git branch 兜底）
-    mockExec.mockReturnValue("");
     // existsSync 默认 false（sessionFile 不存在兜底路径）
     mockExistsSync.mockReturnValue(false);
   });
@@ -159,23 +164,15 @@ describe("runSpawn", () => {
 
     it("多个未退出 child（sync + bg）→ killAllSpawnedChildren 全部 kill", async () => {
       // spawn 两个 child（模拟 sync + background 并发），都未退出。
-      // 注意：waitForSpawn 等待 results.length===0→非0 转换，只适用于首次 spawn。
-      // 第二次 spawn 需等待 results.length 递增到 2，否则 lastSpawnedChild 取回的是 c1。
-      const beforeCount = mockSpawn.mock.results.length;
-
-      const rec1 = makeRecord();
+      const rec1 = makeRecord("spawn-c1");
       const p1 = runSpawn(rec1, "Task: c1", makeOpts(), makeCtx());
       await waitForSpawn();
       const c1 = lastSpawnedChild();
 
-      const rec2 = makeRecord();
+      const rec2 = makeRecord("spawn-c2");
       const p2 = runSpawn(rec2, "Task: c2", makeOpts(), makeCtx());
-      // 等待第二次 spawn：results.length 从 beforeCount+1 涨到 beforeCount+2
-      const start = Date.now();
-      while (mockSpawn.mock.results.length < beforeCount + 2) {
-        if (Date.now() - start > 1000) throw new Error("second spawn not called");
-        await new Promise((r) => setTimeout(r, 5));
-      }
+      // waitForSpawn 是快照语义（记 baseline 等新 spawn），天然支持二次等待
+      await waitForSpawn();
       const c2 = lastSpawnedChild();
 
       // c1 和 c2 是不同实例
@@ -211,19 +208,15 @@ describe("runSpawn", () => {
       expect(spawnedChildren.size).toBe(0);
 
       // spawn 两个未 close 的 child（模拟 close 事件漏触发的极端累积场景）
-      const rec1 = makeRecord();
+      const rec1 = makeRecord("clear-c1");
       const p1 = runSpawn(rec1, "Task: clear-1", makeOpts(), makeCtx());
       await waitForSpawn();
       const c1 = lastSpawnedChild();
 
-      const beforeCount = mockSpawn.mock.results.length;
-      const rec2 = makeRecord();
+      const rec2 = makeRecord("clear-c2");
       const p2 = runSpawn(rec2, "Task: clear-2", makeOpts(), makeCtx());
-      const start = Date.now();
-      while (mockSpawn.mock.results.length < beforeCount + 1) {
-        if (Date.now() - start > 1000) throw new Error("second spawn not called");
-        await new Promise((r) => setTimeout(r, 5));
-      }
+      // 快照语义二次等待：等 rec2 的 runSpawn 调到 spawn
+      await waitForSpawn();
       const c2 = lastSpawnedChild();
 
       // 两个 child 都在 Set 中

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

@@ -8,7 +8,8 @@
 // mock 策略（参考 worktree-manager.test.ts 的 mock 模式）：
 //   - node:child_process.spawn → 返回 FakeChild（EventEmitter + PassThrough），
 //     测试用控制器 emit data/close/error 控制时序。
-//   - node:child_process.execFileSync → 返回空串（buildEnvBlock 的 git branch 调用避免副作用）。
+//   - 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）。
@@ -21,7 +22,7 @@
 // `await import("./helpers/spawn-mock.ts")` 取回 FakeChild（绕开 vitest 的 hoisting 限制——
 // 工厂函数体不能引用顶层 import 变量，但 async 工厂内的 await import 是运行时求值）。
 
-import { execFileSync, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -32,7 +33,15 @@ vi.mock("node:child_process", async () => {
   const { FakeChild } = await import("./helpers/spawn-mock.ts");
   return {
     spawn: vi.fn(() => new FakeChild()),
-    execFileSync: vi.fn(() => ""), // buildEnvBlock 的 git branch 调用，返回空避免副作用
+    // 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")),
+    ),
   };
 });
 
@@ -86,7 +95,6 @@ import {
 } 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);
 const mockMkdirSync = vi.mocked(fs.mkdirSync);
@@ -103,8 +111,6 @@ const mockSessionFileExists = (p: string): void => mockSessionFileExistsOf(mockE
 describe("runSpawn", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    // execFileSync 默认返回空串（git branch 兜底）
-    mockExec.mockReturnValue("");
     // existsSync 默认 false（sessionFile 不存在兜底路径）
     mockExistsSync.mockReturnValue(false);
   });
@@ -404,9 +410,9 @@ describe("runSpawn", () => {
     });
   });
 
-  // ── 7. identity 补写 ──
-  describe("identity 补写", () => {
-    it("正常 close 后 appendFileSync 写入 IDENTITY_CUSTOM_TYPE custom entry", async () => {
+  // ── 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());
 
@@ -425,17 +431,11 @@ describe("runSpawn", () => {
 
       await promise;
 
-      // appendFileSync 被调用写 identity custom entry
-      expect(mockAppendFileSync).toHaveBeenCalledWith(
-        sessionFile,
-        expect.stringContaining('"customType":"subagent-identity"'),
-        "utf-8",
-      );
-      // 写入内容含 record.id / agent
-      const written = mockAppendFileSync.mock.calls[0]?.[1] as string;
-      expect(written).toContain(record.id);
-      expect(written).toContain(record.agent);
-      expect(written).toContain('"type":"custom"');
+      // [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 () => {
@@ -625,18 +625,22 @@ describe("runSpawn", () => {
     });
 
     /**
-     * fake timers 下推进时间直到 spawn 被调用（替代 waitForSpawn）。
+     * fake timers 下推进时间直到 spawn 被调用（替代 waitForSpawn，返回 child 控制器）。
+     *
+     * [快照语义] 同 helpers/spawn-mock.ts 的 waitForSpawn：记调用时 baseline，等待其后的
+     * **新** spawn——支持同一测试/文件内多次 runSpawn。
      *
      * runSpawn 在 mkdirSync + writePromptToTempFile（真实 fs.promises I/O）之后才调 spawn。
-     * 每次推进 10ms 让 waitForSpawn 轮询的 setTimeout(r,5) 触发；同时 advanceTimersByTimeAsync
-     * flush 已 resolve 的 I/O promise，使 runSpawn 继续走到 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 > 0) break;
+        if (mockSpawn.mock.results.length > baseline) break;
         await vi.advanceTimersByTimeAsync(10);
       }
-      if (mockSpawn.mock.results.length === 0) {
+      if (mockSpawn.mock.results.length <= baseline) {
         throw new Error("spawn was not called (fake timers did not progress to spawn)");
       }
       return lastSpawnedChild();