@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/execution/__tests__/delivery-methods.test.ts

@@ -0,0 +1,385 @@
+// src/execution/__tests__/delivery-methods.test.ts
+//
+// resumeRound + deliverMessage 单元测试（M2-B1 投递基础设施）。
+//
+// mock session-runner（runSpawn 受控 + killAllSpawnedChildren 空实现 + getChildByRecord/spawnedChildren
+// 真实 Map 语义），走 SubagentService 真实的 resumeRound/deliverMessage 逻辑：
+//   - resumeRound：idle→running→detached kickOff runSpawn 收到 resume 参数；chatMode+done 回 idle/round+1；
+//     非 idle / 无 sessionFile / 无 controller throw
+//   - deliverMessage：按进程死活分流（热路径 prompt+streamingBehavior / 冷路径 resume）
+//
+// stdin-writer 不 mock（端到端验证 deliverMessage→sendPromptCommand→child.stdin 字节）。
+// [review 修复] 已删除 deliverToRunning describe（busy follow_up/steer 投递）——随
+// deliverToRunning 方法一并移除（无生产调用方，pendingMessages 消费确认制死机制）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ChildProcess } from "node:child_process";
+import { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({ getLogger: () => loggerMock }));
+
+// mock session-runner：runSpawn 受控 + killAllSpawnedChildren 空实现；
+// getChildByRecord/spawnedChildren 提供真实 Map 语义（deliverToRunning 注册 mock child 用）。
+vi.mock("../session-runner.ts", () => {
+  const spawnedChildren = new Map<string, unknown>();
+  return {
+    runSpawn: vi.fn(),
+    killAllSpawnedChildren: vi.fn(),
+    spawnedChildren,
+    getChildByRecord: (id: string): unknown => spawnedChildren.get(id),
+  };
+});
+
+import { runSpawn, spawnedChildren, type SessionRunnerContext } from "../session-runner.ts";
+import * as lifecycle from "../lifecycle-manager.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo } from "../model-resolver.ts";
+import { SubagentService } from "../subagent-service.ts";
+import type { PiLike } from "../subagent-service.ts";
+import type { AgentResult, ExecutionRecord } from "../types.ts";
+
+const mockRunSpawn = vi.mocked(runSpawn);
+
+const STUB_MODEL: ModelInfo = { id: "test-model", name: "Test", provider: "test", reasoning: false };
+
+function makeTmpAgentDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "delivery-test-"));
+}
+
+function makePi(): PiLike & {
+  appendEntry: ReturnType<typeof vi.fn>;
+  events: { emit: ReturnType<typeof vi.fn> };
+  sendMessage: ReturnType<typeof vi.fn>;
+} {
+  return { appendEntry: vi.fn(), events: { emit: vi.fn() }, sendMessage: vi.fn() };
+}
+
+function makeResult(success: boolean): AgentResult {
+  return {
+    text: success ? "done" : "err",
+    turns: 1,
+    durationMs: 100,
+    success,
+    error: success ? undefined : "boom",
+    sessionId: "sess-1",
+    toolCalls: [],
+  };
+}
+
+/** chatMode idle record（第一轮已完成，等待续聊）。sessionFile 由调用方覆盖为 agentDir 下路径。 */
+function makeIdleRecord(id = "sa-chat"): ExecutionRecord {
+  const record = createRecord(id, {
+    agent: "general-purpose",
+    model: "test/test-model",
+    thinkingLevel: "low",
+    mode: "background",
+    task: "initial task",
+    slug: "chat",
+    startedAt: 1000,
+    rootSessionId: "root-session",
+    chatMode: true,
+  });
+  // v4 B-1：idle 折入 running。"等待续聊"态现为 status="running"（isIdle/isResumable 派生谓词区分）。
+  record.status = "running";
+  record.round = 1;
+  record.controller = new AbortController();
+  return record;
+}
+
+/** PassThrough child（可读出 stdin 字节验证 deliverToRunning 写入）。 */
+function makeStreamChild(): ChildProcess {
+  return { stdin: new PassThrough() } as unknown as ChildProcess;
+}
+
+function readStdinLines(child: ChildProcess): unknown[] {
+  const stream = child.stdin as unknown as PassThrough;
+  stream.pause();
+  const text = stream.read()?.toString() ?? "";
+  return text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    .map((l) => JSON.parse(l));
+}
+
+describe("resumeRound (M2-B1 idle 投递)", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let record: ExecutionRecord;
+
+  beforeEach(() => {
+    agentDir = makeTmpAgentDir();
+    const modelService = new ModelConfigService({ agentDir });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    service.initSession({ pi: makePi(), sessionId: "root-session" });
+    record = makeIdleRecord();
+    // sessionFile 用 agentDir 下路径（finalizeRoundToIdle 写 .idle sidecar 不留 /tmp 垃圾）
+    record.sessionFile = path.join(agentDir, "fake-session.jsonl");
+    mockRunSpawn.mockReset();
+  });
+
+  afterEach(() => {
+    service.dispose();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("resumeRound(running) → kickOff runSpawn 收到 resume 参数；chatMode+done 回 running/round+1", async () => {
+    mockRunSpawn.mockResolvedValueOnce(makeResult(true));
+    const beforeRound = record.round;
+
+    service.resumeRound(record, "next round msg");
+
+    // 同步：status 已手动设回 running（M2-A 边界，绕过 tryTransition）
+    expect(record.status).toBe("running");
+
+    // detached：等 runSpawn 被调
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+    const call = mockRunSpawn.mock.calls[0]!;
+    // [record, task, opts, ctx, resume]
+    expect(call[1]).toBe("next round msg");
+    expect(call[4]).toEqual({
+      sessionFile: record.sessionFile,
+      model: record.model, // 防漂移（P-10）：从 record identity 读
+      thinkingLevel: record.thinkingLevel,
+    });
+    expect((call[4] as { model: string }).model).toBe("test/test-model");
+
+    // 等 detached 完成：chatMode+done→running（v4 B-1 idle 折入 running，M2-A 分流），round 累加
+    await vi.waitFor(() => expect(record.status).toBe("running"));
+    expect(record.round).toBe(beforeRound! + 1);
+  });
+
+  it("终态 closed record → throw 行动语言（MF-4，仅 running 可续聊），不触发 kickOff", () => {
+    record.status = "closed";
+    // MF-4：行动语言（spec §3.1），不暴露 resume/controller 内部词汇
+    expect(() => service.resumeRound(record, "msg")).toThrow(/not ready for a new message/);
+    expect(mockRunSpawn).not.toHaveBeenCalled();
+  });
+
+  it("record 无 sessionFile → throw 行动语言（MF-4 canonical session unavailable），不触发 kickOff", () => {
+    record.sessionFile = undefined;
+    expect(() => service.resumeRound(record, "msg")).toThrow(/session unavailable/);
+    expect(mockRunSpawn).not.toHaveBeenCalled();
+  });
+
+  it("record 无 controller → throw 行动语言（MF-4），不触发 kickOff", () => {
+    record.controller = undefined;
+    expect(() => service.resumeRound(record, "msg")).toThrow(/not ready for a new message/);
+    expect(mockRunSpawn).not.toHaveBeenCalled();
+  });
+});
+
+// ============================================================
+// deliverMessage（V2 决策 3 chatMode 统一投递：按进程死活分流）
+// ============================================================
+
+describe("deliverMessage (V2 决策 3 chatMode 统一投递)", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let record: ExecutionRecord;
+
+  beforeEach(() => {
+    agentDir = makeTmpAgentDir();
+    const modelService = new ModelConfigService({ agentDir });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    service.initSession({ pi: makePi(), sessionId: "root-session" });
+    record = makeIdleRecord(); // chatMode:true, idle, round=1
+    // sessionFile：冷路径 resumeRound 需要（热路径不用，设了无害）
+    record.sessionFile = path.join(agentDir, "fake-session.jsonl");
+    spawnedChildren.clear();
+    mockRunSpawn.mockReset();
+    lifecycle._resetLifecycleState();
+  });
+
+  afterEach(() => {
+    service.dispose();
+    spawnedChildren.clear();
+    lifecycle._resetLifecycleState();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("热路径 interrupt=false：进程活 → prompt streamingBehavior:followUp + status=running + pid 记录", () => {
+    const child = makeStreamChild();
+    Object.assign(child, { pid: 12345 });
+    spawnedChildren.set(record.id, child);
+
+    service.deliverMessage(record, "after you finish", false);
+
+    const lines = readStdinLines(child);
+    expect(lines).toHaveLength(1);
+    // [验收 4] sendPromptCommand 收到的命令含 streamingBehavior 字段（followUp）
+    expect(lines[0]).toMatchObject({ type: "prompt", message: "after you finish", streamingBehavior: "followUp" });
+    expect(record.status).toBe("running");
+    expect(record.pid).toBe(12345);
+  });
+
+  it("热路径 interrupt=true：进程活 → prompt streamingBehavior:steer", () => {
+    const child = makeStreamChild();
+    spawnedChildren.set(record.id, child);
+
+    service.deliverMessage(record, "stop now", true);
+
+    const lines = readStdinLines(child);
+    expect(lines[0]).toMatchObject({ type: "prompt", message: "stop now", streamingBehavior: "steer" });
+    expect(record.status).toBe("running");
+  });
+
+  it("热路径 disarm idle timer：arm 后 deliverMessage → timer 清除（防 turn 期间误杀）", () => {
+    const child = makeStreamChild();
+    spawnedChildren.set(record.id, child);
+    // 先 arm idle timer（模拟 Step 4a agent_settled 后 armed）
+    lifecycle.armIdleTimer(record.id, () => {}, 10000);
+    expect(lifecycle.hasIdleTimer(record.id)).toBe(true);
+
+    service.deliverMessage(record, "msg", false);
+
+    // disarmIdleTimer 被调 → timer 清除（新 turn 不被 idle timer 误杀）
+    expect(lifecycle.hasIdleTimer(record.id)).toBe(false);
+  });
+
+  it("冷路径：进程死（无 child）→ resumeRound spawn（runSpawn 收到 resume 参数）", async () => {
+    mockRunSpawn.mockResolvedValueOnce(makeResult(true));
+    // spawnedChildren 无该 record → getChildByRecord 返回 undefined → 冷路径
+
+    service.deliverMessage(record, "resume msg", false);
+
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+    const call = mockRunSpawn.mock.calls[0]!;
+    expect(call[1]).toBe("resume msg");
+    expect(call[4]).toEqual({
+      sessionFile: record.sessionFile,
+      model: record.model,
+      thinkingLevel: record.thinkingLevel,
+    });
+  });
+
+  it("冷路径 child.killed=true → 走 resume（判活用 !child.killed）", async () => {
+    mockRunSpawn.mockResolvedValueOnce(makeResult(true));
+    const child = makeStreamChild();
+    Object.assign(child, { killed: true }); // 进程已 kill
+    spawnedChildren.set(record.id, child);
+
+    service.deliverMessage(record, "after kill", false);
+
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+  });
+
+  it("续聊后 agent_settled → onRoundSettled 设 running + round+1（v4 B-1 idle 折入 running，复用 Step 4a 链路）", () => {
+    // buildSessionRunnerContext 是 private，类型断言访问（测试专用）
+    const ctx = (service as unknown as { buildSessionRunnerContext(): SessionRunnerContext }).buildSessionRunnerContext();
+    record.status = "running"; // 模拟 deliverMessage 热路径设的新 turn 状态
+    const beforeRound = record.round;
+
+    // 模拟 session-runner 在 agent_settled 时调本回调（Step 4a 接入点）
+    ctx.onRoundSettled!(record);
+
+    expect(record.status).toBe("running");
+    expect(record.round).toBe(beforeRound! + 1);
+  });
+});
+
+// ============================================================
+// 冷路径并发守卫（review round2 MF1：同 turn 批量两条 message 双冷路径双 spawn）
+// ============================================================
+// 复现链（reviewer 探针实证）：pi 对同一条 assistant message 的 tool calls 顺序执行
+// （subagent tool sequential），tool1 的 deliverMessage 在冷路径 resumeRound 返回即
+// resolve——早于 runSpawn 完成 spawn 注册（session-runner spawnedChildren.set 前有
+// pool.acquire await / writePromptToTempFile 等多个异步点）；tool2 立即执行 →
+// getChildByRecord 仍 undefined → 再次冷路径。v4 两态收敛后 resumeRound 的
+// `status !== "running"` 守卫对 idle-resumable record 恒放行（idle 本来就是 running）、
+// `status = "running"` 是幂等写 → 两次 kickOff → runSpawn 被调 2 次 → 两个 pi 子进程
+// 以 --session 同一 JSONL 双写 + 第一个进程脱离 kill 记账成孤儿。
+describe("deliverMessage 冷路径并发守卫（review round2 MF1）", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let record: ExecutionRecord;
+
+  beforeEach(() => {
+    agentDir = makeTmpAgentDir();
+    const modelService = new ModelConfigService({ agentDir });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    service.initSession({ pi: makePi(), sessionId: "root-session" });
+    record = makeIdleRecord();
+    record.sessionFile = path.join(agentDir, "fake-session.jsonl");
+    spawnedChildren.clear();
+    mockRunSpawn.mockReset();
+    lifecycle._resetLifecycleState();
+  });
+
+  afterEach(() => {
+    service.dispose();
+    spawnedChildren.clear();
+    lifecycle._resetLifecycleState();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("同 record 连续两条 message 冷路径 → 第二条 throw 行动语言，runSpawn 仅 1 次", async () => {
+    // runSpawn 挂起不 resolve：模拟真实 spawn 异步窗口（pool.acquire 排队 + tempFile + spawn），
+    // 此窗口内 spawnedChildren 尚未注册 → 第二条 message 必再走冷路径。
+    let releaseFirst!: (r: AgentResult) => void;
+    mockRunSpawn.mockImplementationOnce(
+      () => new Promise<AgentResult>((res) => { releaseFirst = res; }),
+    );
+
+    // 第一条：正常冷路径 resume
+    await expect(service.deliverMessage(record, "first msg", false)).resolves.toBeUndefined();
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+
+    // 第二条：spawn 仍在途（getChildByRecord undefined）→ 再走冷路径。
+    // 修复前：resumeRound 守卫恒放行 → 第二次 kickOff → runSpawn 2 次（双 spawn 双写 session）。
+    // 修复后：in-flight 守卫 throw 行动语言（MF-4）。
+    await expect(service.deliverMessage(record, "second msg", false)).rejects.toThrow(
+      /already starting a new round/,
+    );
+    expect(mockRunSpawn).toHaveBeenCalledTimes(1);
+
+    // 轮次完成 → 守卫清除 → 后续冷路径可再 resume（守卫不得永久死锁 record）
+    releaseFirst(makeResult(true));
+    await vi.waitFor(() =>
+      expect((service as unknown as { resumesInFlight: Set<string> }).resumesInFlight.has(record.id)).toBe(false),
+    );
+    mockRunSpawn.mockResolvedValueOnce(makeResult(true));
+    await expect(service.deliverMessage(record, "third msg", false)).resolves.toBeUndefined();
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(2));
+    expect(mockRunSpawn.mock.calls[1]![1]).toBe("third msg");
+  });
+
+  it("守卫是 record 级：A 在途 resume 不拦截 B 的冷路径 message", async () => {
+    const recordB = makeIdleRecord("sa-chat-b");
+    recordB.sessionFile = path.join(agentDir, "fake-session-b.jsonl");
+    let releaseA!: (r: AgentResult) => void;
+    mockRunSpawn.mockImplementation(
+      () => new Promise<AgentResult>((res) => { releaseA = res; }),
+    );
+
+    await service.deliverMessage(record, "A msg", false);
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+
+    // B 的冷路径不受 A 在途影响
+    await expect(service.deliverMessage(recordB, "B msg", false)).resolves.toBeUndefined();
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(2));
+    expect(mockRunSpawn.mock.calls[1]![0]).toBe(recordB);
+
+    releaseA(makeResult(true));
+  });
+
+  it("resume 在途时直接调 resumeRound（不经 deliverMessage）同样被守卫拦截", () => {
+    // promise 同步创建：release 立即可用（runSpawn 在 pool.acquire 微任务后才被调）
+    let release!: (r: AgentResult) => void;
+    const gate = new Promise<AgentResult>((res) => { release = res; });
+    mockRunSpawn.mockImplementationOnce(() => gate);
+
+    service.resumeRound(record, "first");
+    expect(() => service.resumeRound(record, "second")).toThrow(/already starting a new round/);
+
+    release(makeResult(true));
+  });
+});

package/src/execution/__tests__/epipe-fallback.test.ts

@@ -0,0 +1,241 @@
+// src/execution/__tests__/epipe-fallback.test.ts
+//
+// deliverMessage EPIPE 兜底集成测试——热路径 stdin 写入 EPIPE 时自动转冷路径 resume + 消息重放。
+//
+// 场景覆盖：
+//   1. 首次 EPIPE → 自动转冷路径 resumeRound（runSpawn 收到 resume 参数 + 原消息）
+//   2. 连续 2 次 EPIPE → throw 含恢复指引（防无限循环）
+//   3. 热路径成功写入后清零 EPIPE 计数（正常路径不受影响）
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ChildProcess } from "node:child_process";
+import { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({ getLogger: () => loggerMock }));
+
+// mock session-runner：runSpawn 受控 + killAllSpawnedChildren 空实现；
+// getChildByRecord/spawnedChildren 提供真实 Map 语义。
+vi.mock("../session-runner.ts", () => {
+  const spawnedChildren = new Map<string, unknown>();
+  return {
+    runSpawn: vi.fn(),
+    killAllSpawnedChildren: vi.fn(),
+    spawnedChildren,
+    getChildByRecord: (id: string): unknown => spawnedChildren.get(id),
+  };
+});
+
+import { runSpawn, spawnedChildren } from "../session-runner.ts";
+import * as lifecycle from "../lifecycle-manager.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo } from "../model-resolver.ts";
+import { SubagentService } from "../subagent-service.ts";
+import type { PiLike } from "../subagent-service.ts";
+import type { AgentResult, ExecutionRecord } from "../types.ts";
+
+const mockRunSpawn = vi.mocked(runSpawn);
+
+function makeTmpAgentDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "epipe-test-"));
+}
+
+function makePi(): PiLike & {
+  appendEntry: ReturnType<typeof vi.fn>;
+  events: { emit: ReturnType<typeof vi.fn> };
+  sendMessage: ReturnType<typeof vi.fn>;
+} {
+  return { appendEntry: vi.fn(), events: { emit: vi.fn() }, sendMessage: vi.fn() };
+}
+
+function makeResult(success: boolean): AgentResult {
+  return {
+    text: success ? "done" : "err",
+    turns: 1,
+    durationMs: 100,
+    success,
+    error: success ? undefined : "boom",
+    sessionId: "sess-1",
+    toolCalls: [],
+  };
+}
+
+/** chatMode running-resumable record（第一轮已完成，等待续聊；v4 B-1 旧 idle 折入 running）。 */
+function makeIdleRecord(id = "sa-epipe"): ExecutionRecord {
+  const record = createRecord(id, {
+    agent: "general-purpose",
+    model: "test/test-model",
+    thinkingLevel: "low",
+    mode: "background",
+    task: "initial task",
+    slug: "epipe-chat",
+    startedAt: 1000,
+    rootSessionId: "root-session",
+    chatMode: true,
+  });
+  record.status = "running";
+  record.round = 1;
+  record.controller = new AbortController();
+  return record;
+}
+
+/**
+ * 构造 EPIPE child：stdin.write 抛 {code:'EPIPE'}，模拟子进程已退出但 close 事件尚未到达的窗口。
+ */
+function makeEpipeChild(): ChildProcess {
+  const fakeStdin = {
+    write: vi.fn(() => {
+      const err = Object.assign(new Error("write after end"), { code: "EPIPE" });
+      throw err;
+    }),
+    destroyed: false,
+  } as unknown as PassThrough;
+  return { stdin: fakeStdin, pid: 99999 } as unknown as ChildProcess;
+}
+
+/**
+ * 构造正常 child：PassThrough stdin（可正常写入）。
+ */
+function makeNormalChild(): ChildProcess {
+  return { stdin: new PassThrough(), pid: 88888 } as unknown as ChildProcess;
+}
+
+// ============================================================
+// deliverMessage EPIPE 兜底
+// ============================================================
+
+describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resume）", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let record: ExecutionRecord;
+
+  beforeEach(() => {
+    agentDir = makeTmpAgentDir();
+    const modelService = new ModelConfigService({ agentDir });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    service.initSession({ pi: makePi(), sessionId: "root-session" });
+    record = makeIdleRecord();
+    record.sessionFile = path.join(agentDir, "fake-session.jsonl");
+    spawnedChildren.clear();
+    mockRunSpawn.mockReset();
+    lifecycle._resetLifecycleState();
+    loggerMock.warn.mockClear();
+  });
+
+  afterEach(() => {
+    service.dispose();
+    spawnedChildren.clear();
+    lifecycle._resetLifecycleState();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("首次 EPIPE → 自动转冷路径 resumeRound + 原消息重放", async () => {
+    mockRunSpawn.mockResolvedValueOnce(makeResult(true));
+    // 注册 EPIPE child（热路径会命中但 stdin.write 抛 EPIPE）
+    spawnedChildren.set(record.id, makeEpipeChild());
+
+    // deliverMessage 不 throw（首次 EPIPE 走 resume 兜底）
+    await expect(service.deliverMessage(record, "msg after epipe", false)).resolves.toBeUndefined();
+
+    // spawnedChildren 中的死进程条目已清理（EPIPE catch 块 delete）
+    expect(spawnedChildren.has(record.id)).toBe(false);
+
+    // resumeRound 被触发（冷路径），runSpawn 收到 resume 参数 + 原消息
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+    const call = mockRunSpawn.mock.calls[0]!;
+    expect(call[1]).toBe("msg after epipe");
+    expect(call[4]).toEqual({
+      sessionFile: record.sessionFile,
+      model: record.model,
+      thinkingLevel: record.thinkingLevel,
+    });
+
+    // warn 日志包含 EPIPE 关键词
+    expect(loggerMock.warn).toHaveBeenCalled();
+    const warnCalls = loggerMock.warn.mock.calls;
+    const epipeWarn = warnCalls.find((c: unknown[]) =>
+      typeof c[0] === "string" && c[0].includes("EPIPE"),
+    );
+    expect(epipeWarn).toBeDefined();
+  });
+
+  it("连续 2 次 EPIPE → throw 含恢复指引（防无限循环）", async () => {
+    mockRunSpawn.mockResolvedValue(makeResult(true));
+    // 注册 EPIPE child
+    spawnedChildren.set(record.id, makeEpipeChild());
+
+    // 第 1 次：EPIPE → resume（不 throw）
+    await service.deliverMessage(record, "first epipe", false);
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+
+    // resume 完成后 record 回 running（v4 B-1：finalizeRoundToIdle 设 running，旧 idle 折入）
+    await vi.waitFor(() => expect(record.status).toBe("running"));
+
+    // 第 2 次：再次注入 EPIPE child + EPIPE
+    spawnedChildren.set(record.id, makeEpipeChild());
+
+    // 第 2 次 EPIPE → throw 含恢复指引（连续 2 次触发 exhaustion）
+    // 注意：第二 EPIPE 时 count 已为 2，catch 块立即 throw（不经过 resumeRound）。
+    let thrown: unknown;
+    try {
+      await service.deliverMessage(record, "second epipe", false);
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(Error);
+    expect((thrown as Error).message).toContain("EPIPE fallback exhausted");
+    expect((thrown as Error).message).toContain("2 consecutive EPIPE");
+    expect((thrown as Error).message).toContain("action:'close'");
+    expect((thrown as Error).message).toContain("action:'start'");
+  });
+
+  it("热路径成功写入后清零 EPIPE 计数（正常路径不受 EPIPE 计数影响）", async () => {
+    mockRunSpawn.mockResolvedValue(makeResult(true));
+
+    // 第 1 轮：EPIPE → resume
+    spawnedChildren.set(record.id, makeEpipeChild());
+    await service.deliverMessage(record, "epipe msg", false);
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+    await vi.waitFor(() => expect(record.status).toBe("running"));
+
+    // 第 2 轮：正常 child，成功写入（清零 EPIPE 计数）
+    spawnedChildren.set(record.id, makeNormalChild());
+    await service.deliverMessage(record, "normal msg", true);
+    // 不 throw，status=running（热路径成功）
+    expect(record.status).toBe("running");
+
+    // 第 3 轮：再次 EPIPE → 但因为第 2 轮清零了计数，这次是首次 EPIPE（不 throw）
+    // 需要先让 record 回 running（等待续聊态）
+    record.status = "running";
+    spawnedChildren.set(record.id, makeEpipeChild());
+    await expect(service.deliverMessage(record, "after reset", false)).resolves.toBeUndefined();
+  });
+
+  it("EPIPE 兜底与冷路径共用 in-flight 守卫：resume 在途时 EPIPE 兜底不再二次 spawn（review round2 MF1）", async () => {
+    // 冷路径发起 resume，runSpawn 挂起（spawn 异步窗口内）
+    let releaseFirst!: (r: AgentResult) => void;
+    mockRunSpawn.mockImplementationOnce(
+      () => new Promise<AgentResult>((res) => { releaseFirst = res; }),
+    );
+    await service.deliverMessage(record, "cold path first", false);
+    await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
+
+    // 注册 EPIPE child → deliverMessage 走热路径 → stdin EPIPE → 兜底调 resumeRound
+    // → in-flight 命中 → throw（不再走第二次 spawn。EPIPE 计数仍 +1 但未达阈值 2，
+    // exhaustion 分支不触发；throw 由兜底路径的 resumeRound 守卫抛出）
+    spawnedChildren.set(record.id, makeEpipeChild());
+    await expect(service.deliverMessage(record, "epipe during resume", false)).rejects.toThrow(
+      /already starting a new round/,
+    );
+    expect(mockRunSpawn).toHaveBeenCalledTimes(1);
+
+    releaseFirst(makeResult(true));
+  });
+});