@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

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

@@ -0,0 +1,322 @@
+// src/__tests__/run-spawn-resume.test.ts
+//
+// runSpawn 的 resume 路径测试（M1 基建：重开已结束 session 继续对话）。
+//
+// 覆盖 M1 拆分 1：runSpawn 第 5 参数 resume（SpawnResumeOpts）→ buildSpawnArgs 追加
+// --session <file> + model/thinkingLevel 覆盖 + record.sessionFile 提前锁定（handshake 不覆盖）。
+//
+// mock 模式与 run-spawn-rpc-mode.test.ts 一致（vi.mock 必须各文件独立声明，工厂内用
+// `await import` 取回 FakeChild）。
+
+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(),
+}));
+
+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 { getChildByRecord, runSpawn, spawnedChildren } from "../session-runner.ts";
+import {
+  emitStdoutLine,
+  type FakeChild,
+  lastSpawnedChild as lastSpawnedChildOf,
+  makeCtx,
+  makeOpts,
+  makeRecord,
+  waitForSpawn as waitForSpawnOf,
+} from "./helpers/spawn-mock.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockExistsSync = vi.mocked(fs.existsSync);
+
+const lastSpawnedChild = (): FakeChild => lastSpawnedChildOf(mockSpawn);
+const waitForSpawn = (timeoutMs = 1000): Promise<void> => waitForSpawnOf(mockSpawn, timeoutMs);
+
+/**
+ * 取最近一次 spawn 调用收到的 args 数组。
+ *
+ * getPiInvocation 在测试环境（existsSync 全 mock 默认 false + node 通用运行时）走分支 3，
+ * invocation.args === buildSpawnArgs 的完整输出，故此处直接读 spawn 的第二参数。
+ */
+const lastSpawnArgs = (): string[] => {
+  const call = mockSpawn.mock.calls.at(-1);
+  if (!call) throw new Error("spawn was not called yet");
+  return call[1] as string[];
+};
+
+describe("runSpawn resume（M1 基建）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockExistsSync.mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("resume 全参数：--session + model(:thinkingLevel) 进 args，且覆盖 opts.resolved", async () => {
+    const record = makeRecord();
+    const resumeSessionFile = "/sessions/sub/resume-target.jsonl";
+    const promise = runSpawn(record, "继续上轮对话", makeOpts(), makeCtx(), {
+      sessionFile: resumeSessionFile,
+      model: "anthropic/claude-sonnet",
+      thinkingLevel: "high",
+    });
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    // resume.sessionFile 文件存在（resume 前提）→ 让 existsSync 对它返回 true，
+    // 避免进程退出后兜底查找报错 + identity 补写路径走通。
+    mockExistsSync.mockImplementation((p: unknown) => String(p) === resumeSessionFile);
+    // 消费 stdin（含 get_state 握手命令 + prompt 命令），避免背压
+    child.stdin.on("data", () => {});
+
+    emitStdoutLine(child, { type: "turn_end" });
+    child.stdout.end();
+    child.emit("close", 0);
+
+    await promise;
+
+    const args = lastSpawnArgs();
+    // --session <resumeSessionFile> 紧跟 --session-dir
+    const sessionIdx = args.indexOf("--session");
+    expect(sessionIdx).toBeGreaterThan(-1);
+    expect(args[sessionIdx + 1]).toBe(resumeSessionFile);
+    const sessionDirIdx = args.indexOf("--session-dir");
+    expect(sessionIdx).toBe(sessionDirIdx + 2);
+    // --model 用 resume.model（覆盖 opts.resolved 的 test/test-model），thinkingLevel 作后缀
+    const modelIdx = args.indexOf("--model");
+    expect(modelIdx).toBeGreaterThan(-1);
+    expect(args[modelIdx + 1]).toBe("anthropic/claude-sonnet:high");
+    // 不应出现 opts.resolved 的 model（证明 resume.model 覆盖生效）
+    expect(args).not.toContain("test/test-model");
+
+    // record.sessionFile 提前锁定为 resume 值
+    expect(record.sessionFile).toBe(resumeSessionFile);
+  });
+
+  it("resume 不传 model/thinkingLevel → --model 回退 opts.resolved", async () => {
+    const record = makeRecord();
+    const resumeSessionFile = "/sessions/sub/no-model.jsonl";
+    const promise = runSpawn(record, "继续", makeOpts(), makeCtx(), {
+      sessionFile: resumeSessionFile,
+    });
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    mockExistsSync.mockImplementation((p: unknown) => String(p) === resumeSessionFile);
+    child.stdin.on("data", () => {});
+
+    emitStdoutLine(child, { type: "turn_end" });
+    child.stdout.end();
+    child.emit("close", 0);
+
+    await promise;
+
+    const args = lastSpawnArgs();
+    // --session 仍追加
+    const sessionIdx = args.indexOf("--session");
+    expect(sessionIdx).toBeGreaterThan(-1);
+    expect(args[sessionIdx + 1]).toBe(resumeSessionFile);
+    // --model 回退 opts.resolved（test/test-model）
+    const modelIdx = args.indexOf("--model");
+    expect(modelIdx).toBeGreaterThan(-1);
+    expect(args[modelIdx + 1]).toBe("test/test-model");
+  });
+
+  it("resume 时 handshake 仍调但 sessionFile 不被 response 覆盖（提前锁定）", async () => {
+    const record = makeRecord();
+    const resumeSessionFile = "/sessions/sub/locked.jsonl";
+    const promise = runSpawn(record, "继续", makeOpts(), makeCtx(), {
+      sessionFile: resumeSessionFile,
+      model: "openai/gpt-4o",
+    });
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    mockExistsSync.mockImplementation((p: unknown) => String(p) === resumeSessionFile);
+
+    // 捕获握手发出的 get_state 命令（证明 handshake 仍调），并 emit 一个 sessionFile 不同的
+    // response（模拟 handshake 返回新文件路径）→ 验证 record.sessionFile 不被覆盖。
+    let getStateSeen = false;
+    const conflictingSessionFile = "/sessions/sub/SHOULD-NOT-OVERWRITE.jsonl";
+    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) {
+            getStateSeen = true;
+            emitStdoutLine(child, {
+              type: "response",
+              command: "get_state",
+              success: true,
+              id: cmd.id,
+              data: { sessionFile: conflictingSessionFile, sessionId: "rpc-sess" },
+            });
+          }
+        } catch {
+          // 非 JSON 行（prompt 命令等）忽略
+        }
+      }
+    });
+
+    // 等 stdin listener 触发 + response 经 stdout pump 处理 → finishHandshake 执行
+    await new Promise((r) => setTimeout(r, 20));
+
+    emitStdoutLine(child, { type: "turn_end" });
+    child.stdout.end();
+    child.emit("close", 0);
+
+    await promise;
+
+    // handshake 确实被调（get_state 命令已发出）
+    expect(getStateSeen).toBe(true);
+    // 但 record.sessionFile 仍是 resume 锁定值，未被 response 覆盖
+    expect(record.sessionFile).toBe(resumeSessionFile);
+    expect(record.sessionFile).not.toBe(conflictingSessionFile);
+  });
+});
+
+// ============================================================
+// [M4] spawnedChildren 记账竞态：旧 child close/error 晚于 resume spawn
+// ============================================================
+
+describe("[M4] spawnedChildren 记账竞态守卫（旧 child close 晚于 resume spawn）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockExistsSync.mockReturnValue(false);
+    spawnedChildren.clear();
+  });
+
+  afterEach(() => {
+    spawnedChildren.clear();
+    vi.restoreAllMocks();
+  });
+
+  /**
+   * 竞态时序（PR #173 review 组 D）：idle timer 对旧 child 发 SIGTERM（killed=true 但
+   * close 事件异步未到）→ deliverMessage 判 child.killed 走冷路径 resumeRound → 新 child
+   * spawn 并 set 覆盖注册 → 旧 child 的 close 事件此刻到达。守卫前：close handler 无条件
+   * delete(record.id) 误删新注册 → 新活进程脱离记账（killAllSpawnedChildren 漏杀 +
+   * 二次 resume 双写 session 文件）。守卫后：按句相等跳过删除。
+   */
+  it("旧 child close 晚于 resume spawn 到达：不误删新 child 注册（按值守卫）", async () => {
+    const record = makeRecord("m4-race-1");
+    // 首轮 runSpawn（注册 child1）
+    const p1 = runSpawn(record, "first round", makeOpts(), makeCtx());
+    await waitForSpawn();
+    const child1 = lastSpawnedChild();
+    child1.stdin.on("data", () => {});
+    expect(getChildByRecord(record.id)).toBe(child1);
+
+    // 模拟 idle timer SIGTERM：killed=true 但 close 事件**未派发**（异步窗口）
+    child1.kill("SIGTERM");
+
+    // 冷路径 resume：同 record 第二次 runSpawn，spawn child2 覆盖注册
+    const resumeFile = "/sessions/sub/m4-race.jsonl";
+    const p2 = runSpawn(record, "resume round", makeOpts(), makeCtx(), {
+      sessionFile: resumeFile,
+    });
+    await waitForSpawn();
+    const child2 = lastSpawnedChild();
+    child2.stdin.on("data", () => {});
+    expect(getChildByRecord(record.id)).toBe(child2);
+
+    // 旧 child1 的 close 事件此刻到达——守卫必须跳过删除
+    emitStdoutLine(child1, { type: "turn_end" });
+    child1.stdout.end();
+    child1.emit("close", 0);
+    await p1;
+
+    // 关键断言：新 child2 的注册未被旧 child 的迟到 close 误删
+    expect(getChildByRecord(record.id)).toBe(child2);
+
+    // child2 正常退出：close 后注册清理（守卫对当前句柄仍生效）
+    mockExistsSync.mockImplementation((p: unknown) => String(p) === resumeFile);
+    emitStdoutLine(child2, { type: "turn_end" });
+    child2.stdout.end();
+    child2.emit("close", 0);
+    await p2;
+    expect(getChildByRecord(record.id)).toBeUndefined();
+  });
+
+  it("旧 child spawn error 晚于 resume spawn 到达：同样不误删新 child 注册", async () => {
+    const record = makeRecord("m4-race-2");
+    const p1 = runSpawn(record, "first round", makeOpts(), makeCtx());
+    await waitForSpawn();
+    const child1 = lastSpawnedChild();
+    child1.stdin.on("data", () => {});
+
+    const p2 = runSpawn(record, "resume round", makeOpts(), makeCtx(), {
+      sessionFile: "/sessions/sub/m4-race-2.jsonl",
+    });
+    await waitForSpawn();
+    const child2 = lastSpawnedChild();
+    child2.stdin.on("data", () => {});
+    expect(getChildByRecord(record.id)).toBe(child2);
+
+    // 旧 child1 的 error 事件迟到（spawn 失败回调晚到）
+    child1.emit("error", new Error("spawn ENOENT (late)"));
+    await p1;
+
+    expect(getChildByRecord(record.id)).toBe(child2);
+
+    mockExistsSync.mockImplementation((p: unknown) => String(p) === "/sessions/sub/m4-race-2.jsonl");
+    emitStdoutLine(child2, { type: "turn_end" });
+    child2.stdout.end();
+    child2.emit("close", 0);
+    await p2;
+    expect(getChildByRecord(record.id)).toBeUndefined();
+  });
+});

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

@@ -8,7 +8,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";
@@ -17,7 +17,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")),
+    ),
   };
 });
 
@@ -66,7 +74,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);
 
@@ -82,7 +89,6 @@ const mockSessionFileExists = (p: string): void => mockSessionFileExistsOf(mockE
 describe("runSpawn", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mockExec.mockReturnValue("");
     mockExistsSync.mockReturnValue(false);
   });
 
@@ -131,7 +137,7 @@ describe("runSpawn", () => {
       });
     }
 
-    it("无 header + get_state response 回填 sessionFile → identity 写入成功", async () => {
+    it("无 header + get_state response 回填 sessionFile（identity 不再由 session-runner fs 写）", async () => {
       const record = makeRecord();
       const promise = runSpawn(record, "Task: rpc-no-header", makeOpts(), makeCtx());
 
@@ -158,12 +164,9 @@ describe("runSpawn", () => {
       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",
-      );
+      // [M4 / V2 决策 5] identity 不再由 session-runner fs 补写（迁移到子进程 session_start，
+      // 见 index-session-start-identity.test.ts）。此处仅守护 session-runner 不 fs 写 identity。
+      expect(mockAppendFileSync).not.toHaveBeenCalled();
     });
 
     it("无 header + get_state 无响应 → close 主动 settle 不阻塞，identity 不写入", async () => {

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

@@ -7,9 +7,9 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import { readActivePendingFromSessionFile } from "../session-pending.ts";
+import { readActivePendingFromSessionFile, clearPendingCursors } from "../session-pending.ts";
 
 function makeTmpSessionFile(lines: string[]): string {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "session-pending-test-"));
@@ -136,3 +136,62 @@ describe("readActivePendingFromSessionFile", () => {
     expect(readActivePendingFromSessionFile(file)).toEqual({ count: 1, recentUnregister: false });
   });
 });
+
+// [perf] 增量游标行为：同文件重复判定（层主被多个后代唤醒 N 次 → N 次 agent_end）
+// 只读上次 offset 之后的新增行，累计差集语义与全量读一致。
+describe("readActivePendingFromSessionFile — 增量游标 [perf]", () => {
+  let dir: string;
+  let file: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "session-pending-incr-"));
+    file = path.join(dir, "session.jsonl");
+    clearPendingCursors();
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("首次全量 + append 后增量：unregister 只抵消对应 id（与全量读一致）", () => {
+    fs.writeFileSync(file, mkRegister("d1") + "\n" + mkRegister("d2") + "\n");
+    expect(readActivePendingFromSessionFile(file).count).toBe(2);
+
+    fs.appendFileSync(file, mkUnregister("d1", "completed") + "\n");
+    const r = readActivePendingFromSessionFile(file);
+    expect(r.error).toBeUndefined();
+    expect(r.count).toBe(1);
+  });
+
+  it("EOF 半行（append 竞态）不入账，补全换行后入账", () => {
+    fs.writeFileSync(file, mkRegister("d1") + "\n");
+    expect(readActivePendingFromSessionFile(file).count).toBe(1);
+
+    // 半行：无尾换行 → offset 不推进该行
+    const full = mkUnregister("d1", "completed", new Date().toISOString());
+    fs.appendFileSync(file, full.slice(0, full.length - 4));
+    expect(readActivePendingFromSessionFile(file).count).toBe(1);
+
+    // 补全（剩余字符 + 换行）→ 消费
+    fs.appendFileSync(file, full.slice(-4) + "\n");
+    const r = readActivePendingFromSessionFile(file);
+    expect(r.count).toBe(0);
+    expect(r.recentUnregister).toBe(true);
+  });
+
+  it("文件 truncate/重建（size 回退）→ 重置游标从头全读", () => {
+    fs.writeFileSync(file, mkRegister("d1") + "\n" + mkRegister("d2") + "\n");
+    expect(readActivePendingFromSessionFile(file).count).toBe(2);
+
+    fs.writeFileSync(file, mkRegister("d3") + "\n");
+    expect(readActivePendingFromSessionFile(file).count).toBe(1);
+  });
+
+  it("clearPendingCursors 后重新全量（累计 entries 不残留旧账）", () => {
+    fs.writeFileSync(file, mkRegister("d1") + "\n");
+    expect(readActivePendingFromSessionFile(file).count).toBe(1);
+    clearPendingCursors();
+    fs.appendFileSync(file, mkRegister("d2") + "\n");
+    expect(readActivePendingFromSessionFile(file).count).toBe(2);
+  });
+});

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

@@ -102,7 +102,7 @@ describe("reconstructFromFile", () => {
       expect(rec!.agent).toBe("worker");
       expect(rec!.mode).toBe("background");
       expect(rec!.task).toBe("do it");
-      expect(rec!.status).toBe("done");
+      expect(rec!.status).toBe("closed");
       expect(rec!.turns).toHaveLength(1);
       expect(rec!.turns[0].text).toBe("hello world");
       expect(rec!.turnCount).toBe(1);
@@ -284,7 +284,7 @@ describe("reconstructFromFile", () => {
       const rec = reconstructFromFile(filePath);
       expect(rec!.lastError).toBe("API timeout");
       expect(rec!.error).toBe("API timeout");
-      expect(rec!.status).toBe("failed"); // error stopReason → failed
+      expect(rec!.status).toBe("closed"); // error stopReason → failed
     });
 
     it("stopReason=aborted 无 errorMessage → lastError = 'aborted'", () => {
@@ -295,7 +295,7 @@ describe("reconstructFromFile", () => {
       ]);
       const rec = reconstructFromFile(filePath);
       expect(rec!.lastError).toBe("aborted");
-      expect(rec!.status).toBe("failed");
+      expect(rec!.status).toBe("closed");
     });
 
     it("前序 error 但最后 stop → lastError 清除（镜像 turn_end 语义），status=done", () => {
@@ -309,7 +309,7 @@ describe("reconstructFromFile", () => {
       ]);
       const rec = reconstructFromFile(filePath);
       expect(rec!.lastError).toBeUndefined(); // 后续 stop 清除了 error
-      expect(rec!.status).toBe("done");
+      expect(rec!.status).toBe("closed");
       expect(rec!.result).toBe("oops\n\nrecovered");
     });
   });

package/src/execution/__tests__/session-runner-epipe.test.ts

@@ -0,0 +1,178 @@
+// src/execution/__tests__/session-runner-epipe.test.ts
+//
+// [v4 A-1] session-runner 异步 stdin 'error' listener 测试。
+//
+// 背景：writeStdinLine 的 try/catch 只覆盖同步 write 抛错；子进程退出后内核回写 EPIPE
+// 以异步 stream 'error' event 到达，若无 listener 会让 Node 抛 unhandled 'error' 崩主进程（P1）。
+// runSpawn 在 spawn 后、首次 stdin 写入前注册 child.stdin.on('error') handler，合并
+// 同步/异步 EPIPE 计数（共用 stdin-writer 的 recordEpipeFailure）。
+//
+// 验收：① listener 存在 ② error 触发后 spawnedChildren 不含该 recordId
+//      ③ recordEpipeFailure 计数累加（同步/异步合并）
+
+import { spawn } from "node:child_process";
+
+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() }));
+
+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 {
+  EPIPE_FAILURE_THRESHOLD,
+  recordEpipeFailure,
+  resetAllEpipeFailures,
+} from "../stdin-writer.ts";
+import { runSpawn, spawnedChildren } from "../session-runner.ts";
+import { _resetLifecycleState } from "../lifecycle-manager.ts";
+import {
+  FakeChild,
+  lastSpawnedChild as lastSpawnedChildOf,
+  makeCtx,
+  makeOpts,
+  makeRecord,
+  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);
+
+/** 构造 EPIPE errno 错误（模拟子进程退出后内核回写 EPIPE）。 */
+function epipeError(message = "write after end"): NodeJS.ErrnoException {
+  const err = new Error(message) as NodeJS.ErrnoException;
+  err.code = "EPIPE";
+  return err;
+}
+
+/** 手动 emit close 让 runSpawn 的 exitCode promise resolve（非 chatMode 默认 close resolve）。 */
+function settleRunSpawn(child: FakeChild): void {
+  child.stdout.end();
+  child.stderr.end();
+  child.emit("close", 0);
+}
+
+describe("[v4 A-1] session-runner 异步 stdin 'error' listener", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    _resetLifecycleState();
+    resetAllEpipeFailures();
+    spawnedChildren.clear();
+  });
+
+  afterEach(() => {
+    _resetLifecycleState();
+    resetAllEpipeFailures();
+    spawnedChildren.clear();
+  });
+
+  it("① spawn 后注册 child.stdin 'error' listener", async () => {
+    const record = makeRecord("sa-listener");
+    const promise = runSpawn(record, "Task: listener-exists", makeOpts(), makeCtx());
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    // listener 已注册——无 listener 时异步 EPIPE 会崩主进程（这是 A-1 修复的 P1）
+    expect(child.stdin.listenerCount("error")).toBeGreaterThan(0);
+
+    settleRunSpawn(child);
+    await promise;
+  });
+
+  it("②③ async stdin 'error' → 移出 spawnedChildren + recordEpipeFailure 计数递增", async () => {
+    const record = makeRecord("sa-async-epipe");
+    const promise = runSpawn(record, "Task: async-epipe", makeOpts(), makeCtx());
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    // runSpawn 已把 child 注册进 spawnedChildren
+    expect(spawnedChildren.has(record.id)).toBe(true);
+
+    // 发一次异步 stdin 'error'（count 0→1，未达阈值，handler 只 warn 不 throw）
+    child.stdin.emit("error", epipeError());
+
+    // ② spawnedChildren 已移除该 recordId（标记 dead）
+    expect(spawnedChildren.has(record.id)).toBe(false);
+
+    // ③ 计数累加：handler 调 recordEpipeFailure 设为 1；此处再调一次应返回 2
+    //    （若 handler 未运行，counter 仍为 0，本次调用只会返回 1）
+    expect(recordEpipeFailure(record.id)).toBe(2);
+
+    settleRunSpawn(child);
+    await promise;
+  });
+
+  it("③ 同步预置计数 + 异步 stdin 'error' 合并计数（handler 不 throw，防 listener 内 throw 崩进程）", async () => {
+    const record = makeRecord("sa-threshold");
+    const promise = runSpawn(record, "Task: threshold", makeOpts(), makeCtx());
+
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    // 预置 count=1（模拟 deliverMessage 同步路径已计 1 次失败——证明共用同一计数器）
+    expect(recordEpipeFailure(record.id)).toBe(1);
+
+    // [v4 A-1 裁决] async handler 内不 throw（stream 'error' listener 内 throw 会经 emit
+    // 传播为 uncaughtException 崩主进程，违背 A-1 防崩）——达阈值 throw 留同步路径。
+    // emit 不抛错：
+    expect(() => child.stdin.emit("error", epipeError())).not.toThrow();
+
+    // handler 调 recordEpipeFailure → count=2（达阈值但 async 不 throw）；此处再调返回 3
+    expect(recordEpipeFailure(record.id)).toBe(3);
+    expect(EPIPE_FAILURE_THRESHOLD).toBe(2);
+
+    // handler 已移出 spawnedChildren（标记 dead，下次 deliverMessage 检测走冷路径）
+    expect(spawnedChildren.has(record.id)).toBe(false);
+
+    settleRunSpawn(child);
+    await promise;
+  });
+});