@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/helpers/subagent-service-mocks.ts

@@ -0,0 +1,137 @@
+// src/execution/__tests__/helpers/subagent-service-mocks.ts
+//
+// SubagentService 编排层测试（execute-and-await-worktree / execute-nesting /
+// nested-visibility-env-propagation / recursive-visibility-baseline 四文件）共享的
+// spawn 链 mock 模块工厂。原四文件各自内联 ~85 行逐字重复的 vi.mock 工厂体（fallow
+// duplication 告警），收敛到本 module 单源——桩形变更改此文件，全量消费方同步生效。
+//
+// 消费方式（与 __tests__/helpers/system-page-mount.ts、spawn-mock.ts 同款先例）：
+// vi.mock 调用留在测试文件（mock 注册是文件作用域），import 本 module 的语句写在
+// vi.mock 调用之前（工厂执行发生在被测模块链请求被 mock 模块时，届时本 module 已加载）。
+//
+// node:fs / ../alive-store.ts 两个工厂需要真实模块做基底（...actual 展开）：真实实现
+// 经工厂的 importOriginal 参数由测试文件传入——本 module 不能顶层静态 import 它们
+// （测试文件的 vi.mock 注册先于一切 import，本 module 属其依赖图，静态 import 会拿到
+// mock 版自身 → 展开循环）。
+//
+// FakeChild 复用 ./spawn-mock.ts 的 class（结构超集：多 stdin / exitCode / signalCode
+// 字段，四文件原内联 FakeChild 只访问 stdout/stderr/kill/emit，行为等价）。
+
+import { vi } from "vitest";
+
+
+
+import { FakeChild, emitStdoutLine, sessionHeader } from "./spawn-mock.ts";
+
+/**
+ * node:child_process mock 模块。
+ * spawn → FakeChild（测试经 mockSpawn.mock.results 取回控制器）；
+ * execFile → err-first 兜底（buildEnvBlock 的 git branch 调用失败 → catch → branch=""）。
+ */
+export function childProcessModule() {
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    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 模块：同步方法 mock（runSpawn 用到的全部），promises 保留真实实现
+ * （temp-prompt 已整体 mock，不触发真实 I/O）。default 与顶层具名是两套独立 vi.fn
+ * 实例（与收敛前四文件内联形态同构）。
+ */
+// 显式返回类型（typeof import 表达式可命名）——否则推导的返回类型引用 fs 内部
+// 未导出的 ReadStreamOptions/WriteStreamOptions，触发 TS4058 可命名性检查
+export function fsSyncModule(
+  actual: typeof import("node:fs"),
+): {
+  /** 真实 fs + 同步 mock 的合并视图（vi.mock 工厂消费面宽松） */
+  default: unknown;
+  promises: typeof import("node:fs")["promises"];
+  mkdirSync: ReturnType<typeof vi.fn>;
+  existsSync: ReturnType<typeof vi.fn>;
+  appendFileSync: ReturnType<typeof vi.fn>;
+  writeFileSync: ReturnType<typeof vi.fn>;
+  readdirSync: ReturnType<typeof vi.fn>;
+} {
+  const syncMocks = () => ({
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+  });
+  return {
+    default: { ...actual, ...syncMocks() },
+    ...syncMocks(),
+    promises: actual.promises,
+  };
+}
+
+/**
+ * ../alive-store.ts mock 模块：writeAliveMarker（runSpawn 写 .alive sidecar）+
+ * removeAliveMarker（finalizeRecord 收尾删 .alive）mock；其余导出保留真实实现
+ * （worktree-manager / record-store 消费，本组用例不涉及但保留以避免间接报错）。
+ */
+export function aliveStoreModule(actual: typeof import("../../alive-store.ts")) {
+  return {
+    ...actual,
+    writeAliveMarker: vi.fn(),
+    removeAliveMarker: vi.fn(),
+  };
+}
+
+/** ../finalized-marker.ts mock 模块（避免真实 fs 写 sidecar）。 */
+export function finalizedMarkerModule() {
+  return {
+    writeFinalized: vi.fn(),
+    readFinalized: vi.fn(() => false),
+  };
+}
+
+/**
+ * ../manifest-store.ts mock 模块。vi.fn 包裹构造器（普通 function，箭头函数不能被 new）：
+ * 构造参数 recordsDir 可从 mock.calls 断言（[MF-3] 目录统一验证用）。
+ * no-op 化的根因：writeManifest 真实链路的异步 console 经 worker RPC 回流，与 vitest
+ * teardown 形成 race（unhandled rejection / exit 1）——本组用例测编排逻辑不测持久化。
+ */
+export function manifestStoreModule() {
+  class FakeManifestStore {
+    writeManifest = vi.fn(async () => {});
+    readManifest = vi.fn(async () => null);
+    listAllSync = vi.fn(() => []);
+    recoverTmpFiles = vi.fn(async () => []);
+  }
+  return { ManifestStore: vi.fn(function (_recordsDir: string) { return new FakeManifestStore(); }) };
+}
+
+/** ../engine/engines/pi/temp-prompt.ts mock 模块（固定路径，消除 fake-timers 下 flaky 竞态）。 */
+export function tempPromptModule() {
+  return {
+    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 () => {}),
+  };
+}
+
+/**
+ * 驱动 FakeChild 完成 session：写 header + 可选事件 + close(0)。
+ * runSpawn 在 close 后判定 success（exitCode=0），并跑 identity 补写 + finalizeRecord
+ * ——「让 runSpawn 自然 resolve」的标准收尾路径。
+ */
+export async function driveChildToCompletion(child: FakeChild, events: Record<string, unknown>[] = []): Promise<void> {
+  emitStdoutLine(child, sessionHeader());
+  for (const e of events) emitStdoutLine(child, e);
+  child.stdout.end();
+  child.stderr.end();
+  child.emit("close", 0);
+}

package/src/execution/__tests__/keep-alive-no-progress.test.ts

@@ -0,0 +1,280 @@
+// src/execution/__tests__/keep-alive-no-progress.test.ts
+//
+// [T2-① / P-T2 降级路径 B] keep-alive 裸缺省无进展检测上界。
+//
+// 设计：docs/design/subagent-core-unbounded-wait-audit.md §7.2 T2-① + impl-plan §5
+// P-T2 裁决（probe/p-t2-report.md）：历史 89 样本 96.6% keep-alive 窗口 >30min、
+// 长尾 95.5h 合法（parent-shutdown 收敛）——固定 30min 上限被数据否定，按设计降级
+// 路径 B 落地为无进展检测语义：
+//   - 裸缺省（无 maxTurns 无 env）：keep-alive 期间任何子进程 stdout 活动刷新计时，
+//     连续静默达 KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS（30min）且 fire 时惰性复核无存活
+//     后代（A1-2）才处置；
+//   - 显式 maxTurns / env：行为不变（既有固定时长等待，不挂无进展 timer——opt-out
+//     语义保留，A1-1：显式 maxTurns<=0 与 fail-fast 降级也不挂）。
+//
+// mock 布局与 run-spawn-edges.test.ts 一致（FakeChild + mock session-pending）。
+// mock 工厂与 loggerMock 单源收敛 helpers/spawn-mock.ts；vi.mocked 取回与
+// spawn/keep-alive 前奏收敛 helpers/session-runner-mocks.ts（分工见后者头注释）。
+
+import { describe, expect, it, vi } from "vitest";
+
+// [A1-2③] Mock 共享 logger：复核失败的 warn 留痕可被断言（对齐 run-spawn-edges 模式）。
+vi.mock("../../core/logger.ts", async () =>
+  (await import("./helpers/spawn-mock.ts")).coreLoggerModule());
+
+vi.mock("node:child_process", async () =>
+  (await import("./helpers/spawn-mock.ts")).childProcessModule());
+vi.mock("node:fs", async () => (await import("./helpers/spawn-mock.ts")).fsModule());
+vi.mock("../alive-store.ts", async () =>
+  (await import("./helpers/spawn-mock.ts")).aliveStoreModule());
+
+// keep-alive 判定：本文件统一 count>0（有活跃后代 → keep-alive 分支）。
+vi.mock("../session-pending.ts", async () =>
+  (await import("./helpers/spawn-mock.ts")).sessionPendingModule());
+
+vi.mock("../engine/engines/pi/temp-prompt.ts", async () =>
+  (await import("./helpers/spawn-mock.ts")).tempPromptModule());
+
+import {
+  KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS,
+  maxTurnsToWatchdogMs,
+  SPAWN_WATCHDOG_ENV,
+} from "../engine/engines/pi/session-runner.ts";
+import {
+  emitStdoutLine,
+  type FakeChild,
+  lastSpawnedChild as lastSpawnedChildOf,
+  loggerMock,
+  makeOpts,
+  waitForSpawn as waitForSpawnOf,
+} from "./helpers/spawn-mock.ts";
+import { keepAliveTestHooks, spawnAndReachKeepAlive, takeSessionRunnerMocks } from "./helpers/session-runner-mocks.ts";
+
+const {
+  mockSpawn,
+  mockPending,
+  mockListPending,
+  mockReadAliveMarker,
+  mockWriteAliveMarker,
+  mockIsProcessAlive,
+  mockReaddirSync,
+} = takeSessionRunnerMocks();
+
+/** A1-2 复核用例的后代 pid（存/死两形态，对齐 descendant-sweep.test.ts 数值风格）。 */
+const LIVE_DESCENDANT_PID = 424_242;
+const DEAD_DESCENDANT_PID = 999_999;
+
+const lastSpawnedChild = (): FakeChild => lastSpawnedChildOf(mockSpawn);
+const waitForSpawn = (timeoutMs = 1000): Promise<void> => waitForSpawnOf(mockSpawn, timeoutMs);
+
+/** A1-2 复核用例的差集后代装配：pending 项 + session 文件名 + marker + pid 存活形态。 */
+function mockDescendant(sessionId: string, pid: number, alive: boolean): void {
+  mockListPending.mockReturnValue({
+    items: [{ id: "bg-1", sessionId, type: "session" }],
+  });
+  mockReaddirSync.mockReturnValue([`20260901T000000-000_${sessionId}.jsonl`]);
+  mockReadAliveMarker.mockImplementation((f: unknown) =>
+    String(f).endsWith(`_${sessionId}.jsonl`)
+      ? { pid, id: sessionId, startedAt: 0 }
+      : undefined,
+  );
+  mockIsProcessAlive.mockImplementation((p: number) => (p === pid ? alive : false));
+}
+
+describe("[T2-①] keep-alive 裸缺省无进展检测上界（P-T2 降级路径 B）", () => {
+  keepAliveTestHooks(mockPending);
+
+  it("裸缺省：agent_end keep-alive 挂无进展 timer，连续静默 30min 触发 SIGTERM 处置", async () => {
+    const { child, finish } = await spawnAndReachKeepAlive();
+
+    // keep-alive 落位：进程保活
+    expect(child.killed).toBe(false);
+
+    // 静默 30min-1ms：未达阈值，不处置
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS - 1);
+    expect(child.killed).toBe(false);
+
+    // 连续静默达 30min：处置（SIGTERM，升级由 killChildWithEscalation 承接）
+    await vi.advanceTimersByTimeAsync(1);
+    expect(child.killed).toBe(true);
+    expect(child.killSignal).toBe("SIGTERM");
+
+    const result = await finish();
+    expect(result.success).toBe(true); // 信号终止视为正常完成（既有语义，T2-③ 形态除外）
+  });
+
+  it("裸缺省：keep-alive 期间 stdout 活动刷新计时——持续输出的层主不被时长上限误杀", async () => {
+    const { child, finish } = await spawnAndReachKeepAlive();
+    expect(child.killed).toBe(false);
+
+    // 静默 29min 后子进程产生一次输出（任意行）：静默计时被刷新
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS - 60_000);
+    emitStdoutLine(child, { type: "turn_end" });
+    await new Promise((r) => setImmediate(r));
+    expect(child.killed).toBe(false);
+
+    // 再静默 29min（相对上次活动 <30min）：若无刷新语义此刻已累计 58min 会被误杀
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS - 60_000);
+    expect(child.killed).toBe(false);
+
+    // 刷新后再静默满 30min：连续静默达阈值，处置
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(child.killed).toBe(true);
+    expect(child.killSignal).toBe("SIGTERM");
+
+    await finish();
+  });
+
+  it("显式 maxTurns：行为不变——无进展 timer 不挂，30min 静默点不处置，动态超时到期才 kill", async () => {
+    const maxTurns = 20; // maxTurnsToWatchdogMs(20) = 100min
+    const { child, finish } = await spawnAndReachKeepAlive(makeOpts({ maxTurns }));
+
+    // 关键反证断言：裸缺省阈值（30min）处连续静默也不 kill——无进展 timer 未挂载
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS);
+    expect(child.killed).toBe(false);
+
+    // 既有 MF-4 动态超时行为不变：100min 到期才 kill
+    await vi.advanceTimersByTimeAsync(maxTurnsToWatchdogMs(maxTurns) - KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS - 1);
+    expect(child.killed).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(child.killed).toBe(true);
+    expect(child.killSignal).toBe("SIGTERM");
+
+    await finish();
+  });
+
+  it("显式 env 兑底：行为不变——按 env 绝对时限固定等待，不挂无进展 timer", async () => {
+    vi.stubEnv(SPAWN_WATCHDOG_ENV, "600000"); // 10min（< 30min 静默阈值，反证无进展 timer 未挂）
+    const { child, finish } = await spawnAndReachKeepAlive();
+
+    await vi.advanceTimersByTimeAsync(600_000);
+    expect(child.killed).toBe(true);
+    expect(child.killSignal).toBe("SIGTERM");
+
+    await finish();
+  });
+
+  it("keep-alive 结束（后代全部完成 → final kill）即撤无进展 timer，无残留误杀", async () => {
+    // 先走 keep-alive（count>0）挂无进展 timer，再被唤醒重评估为 count=0 → final kill
+    mockPending
+      .mockReturnValueOnce({ count: 1, recentUnregister: false })
+      .mockReturnValueOnce({ count: 0, recentUnregister: false });
+    const { child, promise } = await spawnAndReachKeepAlive(undefined, "Task: keep-then-final");
+    expect(child.killed).toBe(false);
+
+    // 第二次 agent_end：后代已完成 → final kill（keep-alive 结束，无进展 timer 同撤）
+    emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+    await new Promise((r) => setImmediate(r));
+    expect(child.killed).toBe(true);
+
+    // 反证 timer 已撤：advance 30min 不再有任何残留 kill 副作用（进程已 close 收尾）
+    // 真实 ChildProcess 语义：被 SIGTERM 杀死 → 先 exit(null,'SIGTERM') 再 close。只发
+    // close 不发 exit 时 killChain 升级窗口不结算（waitForExit 挂 exit 事件），下方
+    // advance 30min+ 会越过 30s grace 误触发 SIGKILL 升级——补 exit 忠实模拟进程已死。
+    child.signalCode = "SIGTERM";
+    child.emit("exit", null, "SIGTERM");
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 143);
+    const result = await promise;
+    expect(result.success).toBe(true);
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS + 60_000);
+    expect(child.killSignal).toBe("SIGTERM"); // 仅 final kill 一次，无二次信号
+  });
+
+  // ── [A1-1] 挂载面收窄：只有裸缺省（maxTurns 未传且 env 未设）挂无进展 timer ──
+
+  it("A1-1: 显式 maxTurns:0（显式不限时）→ 不挂无进展 timer，静默超阈值不处置", async () => {
+    const { child, finish } = await spawnAndReachKeepAlive(makeOpts({ maxTurns: 0 }));
+    expect(child.killed).toBe(false);
+
+    // 无进展阈值（30min）处静默不 kill：timer 未挂（旧实现 keepAliveMs === undefined
+    // 即挂 timer，30min 处会误 kill——本断言守护挂载面收窄）
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS);
+    expect(child.killed).toBe(false);
+
+    // 显式 opt-out 旧语义 = 等待后代不限时：远超阈值仍无任何 timer 处置
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS * 3);
+    expect(child.killed).toBe(false);
+
+    await finish();
+  });
+
+  it("A1-1: env 已设 + maxTurns:0（参数显式压过 env，U5）→ 同样不挂无进展 timer", async () => {
+    vi.stubEnv(SPAWN_WATCHDOG_ENV, "600000"); // 10min
+    const { child, finish } = await spawnAndReachKeepAlive(makeOpts({ maxTurns: 0 }));
+
+    // 同时越过 env 时限（10min）与无进展阈值（30min）仍不 kill：显式 maxTurns<=0
+    // 压过 env（U5），env 固定 watchdog 与无进展 timer 均未挂
+    await vi.advanceTimersByTimeAsync(Math.max(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS, 600_000) + 60_000);
+    expect(child.killed).toBe(false);
+
+    await finish();
+  });
+
+  // ── [A1-2] fire 惰性复核：stdout 静默 ≠ 无进展，存活后代是刷新信号源的另一半 ──
+
+  it("A1-2①: fire 复核有存活活跃后代 → 视为有进展重挂（30min 固定复核节奏），不处置层主", async () => {
+    // 后代 pending 差集非空 + pid 存活（与 descendant sweep 同源判据）
+    mockDescendant("ka-desc-sess", LIVE_DESCENDANT_PID, true);
+
+    const { child, finish } = await spawnAndReachKeepAlive();
+    expect(child.killed).toBe(false);
+
+    // [A1-2 补修] 清掉 agent_end 处置写点的心跳基线：只统计 fire 重挂分支随行的心跳
+    mockWriteAliveMarker.mockClear();
+
+    // 第 1 次连续静默 30min fire：复核发现存活后代 → 重挂不处置
+    //（「直接后代跑 >30min、层主静默」的合法形态，P-T2 数据 85/89 parent-shutdown）
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS);
+    expect(child.killed).toBe(false);
+
+    // 第 2 个 30min 再 fire（固定复核节奏直到后代死光）：后代仍活 → 仍不处置
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS);
+    expect(child.killed).toBe(false);
+
+    // [A1-2 补修] 每次复核重挂随行一次心跳：合法化形态「层主静默 + 后代长跑数小时」
+    // 期间层主无 agent_end（原心跳写点不再触达），重挂分支是唯一心跳源——缺失则
+    // marker 超 1h 软超时判陈旧 → 透明重生放行双写 / 孤儿恢复误终态活 record
+    expect(mockWriteAliveMarker).toHaveBeenCalledTimes(2);
+    // 心跳写点 = 层主 sessionFile + 子进程 pid（marker 软超时基准刷新语义）
+    expect(mockWriteAliveMarker).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ pid: child.pid }),
+    );
+
+    await finish();
+  });
+
+  it("A1-2②: fire 复核后代差集非空但 pid 全部已死 → 真静默，执行处置", async () => {
+    mockDescendant("ka-dead-sess", DEAD_DESCENDANT_PID, false); // 差集非空但 pid 全部已死
+
+    const { child, finish } = await spawnAndReachKeepAlive();
+
+    // fire：差集非空但无任何存活 pid → 真静默 → 处置（SIGTERM + sweep 标志承接）
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS);
+    expect(child.killed).toBe(true);
+    expect(child.killSignal).toBe("SIGTERM");
+
+    await finish();
+  });
+
+  it("A1-2③: fire 复核失败（sessionFile 读不出）→ 按无后代处置 + warn 留痕", async () => {
+    mockListPending.mockReturnValue({
+      items: [],
+      error: "session file unreadable: ENOENT",
+    });
+
+    const { child, finish } = await spawnAndReachKeepAlive();
+
+    await vi.advanceTimersByTimeAsync(KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS);
+    expect(child.killed).toBe(true);
+    expect(child.killSignal).toBe("SIGTERM");
+    // 复核失败 warn 留痕（与既有保守分支一致的可观测性）
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("re-check failed (treating as no live descendants)"),
+    );
+
+    await finish();
+  });
+});

package/src/execution/__tests__/kill-all-escalation.test.ts

@@ -0,0 +1,196 @@
+// src/execution/__tests__/kill-all-escalation.test.ts
+//
+// [T2-⑤ / LC-2] killAllSpawnedChildren 的跳过条件收敛：「killed 且已确认死亡才跳过」。
+//
+// 设计：docs/design/subagent-core-unbounded-wait-audit.md §7.2 T2-⑤。旧实现按
+// child.killed 跳过——killed=true 只表示「发过 kill 请求」≠「已死」，SIGTERM 被无视
+// 的进程（卡死在不可中断 native 调用）会脱离最后一次回收窗口泄漏。新规则：
+//   - 已确认死亡（exitCode/signalCode 任一非 null）→ 跳过；
+//   - killed 但未确认死亡 → 补 escalation 检查：直接 SIGKILL（dispose 是最后兜底，
+//     没有 30s 升级窗口可等）；
+//   - 未 killed 且未确认死亡 → 发调用方指定 signal（既有行为）。
+
+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()),
+    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, recentUnregister: false })),
+  prunePendingCursor: vi.fn(),
+  listActivePendingFromSessionFile: vi.fn(() => ({ items: [] })),
+}));
+vi.mock("../engine/engines/pi/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 { killAllSpawnedChildren, runSpawn, spawnedChildren } from "../engine/engines/pi/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 lastSpawnedChild = (): FakeChild => lastSpawnedChildOf(mockSpawn);
+const waitForSpawn = (timeoutMs = 1000): Promise<void> => waitForSpawnOf(mockSpawn, timeoutMs);
+
+describe("[T2-⑤ / LC-2] killAllSpawnedChildren 跳过条件收敛", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    killAllSpawnedChildren(); // 清可能残留的 Map 条目（前序用例/文件）
+    spawnedChildren.clear();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("killed 但未 close（SIGTERM 发过、进程未确认死亡）→ 不跳过，补 SIGKILL 升级", async () => {
+    const record = makeRecord("esc-1");
+    const promise = runSpawn(record, "Task: esc", makeOpts(), makeCtx());
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    // 模拟 SIGTERM 已发但进程仍在（LC-2 缺陷形态：killed=发过请求≠已死）
+    child.killed = true;
+    child.killSignal = "SIGTERM";
+    expect(child.exitCode).toBeNull();
+    expect(child.signalCode).toBeNull();
+
+    const n = killAllSpawnedChildren();
+    expect(n).toBe(1);
+    // 补 escalation：dispose 是最后兜底，直接 SIGKILL（不再赌 SIGTERM 生效）
+    expect(child.killSignal).toBe("SIGKILL");
+
+    // 收尾：emit close 让 runSpawn resolve
+    emitStdoutLine(child, { type: "session", id: "s", timestamp: "t", cwd: "/tmp" });
+    child.stdout.end();
+    child.emit("close", 137);
+    const result = await promise;
+    expect(result.success).toBe(true);
+  });
+
+  it("killed 且已确认死亡（signalCode 非 null）→ 跳过", async () => {
+    const record = makeRecord("esc-2");
+    const promise = runSpawn(record, "Task: dead-skip", makeOpts(), makeCtx());
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    // SIGTERM 已发（经 child.kill 记录信号）且进程已确认死亡（内核回收完成、
+    // close 事件尚未回调的窗口）
+    child.kill("SIGTERM");
+    child.signalCode = "SIGTERM";
+
+    const n = killAllSpawnedChildren();
+    expect(n).toBe(0); // 跳过，不重复发信号
+    expect(child.killSignal).toBe("SIGTERM"); // 保持原信号（未被改写为 SIGKILL）
+
+    child.stdout.end();
+    child.emit("close", 143);
+    await promise;
+  });
+
+  it("未 killed 且未确认死亡 → 发调用方 signal（既有行为不变）", async () => {
+    const record = makeRecord("esc-3");
+    const promise = runSpawn(record, "Task: alive", makeOpts(), makeCtx());
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+    expect(child.killed).toBe(false);
+
+    const n = killAllSpawnedChildren("SIGTERM");
+    expect(n).toBe(1);
+    expect(child.killed).toBe(true);
+    expect(child.killSignal).toBe("SIGTERM");
+
+    child.stdout.end();
+    child.emit("close", 143);
+    await promise;
+  });
+
+  it("未 killed 但已确认死亡（自然退出、close 未到）→ 跳过不补信号", async () => {
+    const record = makeRecord("esc-4");
+    const promise = runSpawn(record, "Task: natural", makeOpts(), makeCtx());
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+    child.exitCode = 0; // 自然退出
+
+    const n = killAllSpawnedChildren();
+    expect(n).toBe(0);
+    expect(child.killed).toBe(false);
+
+    child.stdout.end();
+    child.emit("close", 0);
+    await promise;
+  });
+
+  it("混合形态：各分支独立判定（killed-not-dead 升级 / alive 首杀 / dead 跳过）", async () => {
+    const mk = async (id: string): Promise<{ child: FakeChild; promise: Promise<unknown> }> => {
+      const promise = runSpawn(makeRecord(id), `Task: ${id}`, makeOpts(), makeCtx());
+      await waitForSpawn();
+      return { child: lastSpawnedChild(), promise };
+    };
+
+    const a = await mk("mix-a");
+    a.child.killed = true; // killed-not-dead → SIGKILL
+    const b = await mk("mix-b"); // alive → SIGTERM
+    const c = await mk("mix-c");
+    c.child.signalCode = "SIGKILL"; // dead → skip
+
+    const n = killAllSpawnedChildren();
+    expect(n).toBe(2);
+    expect(a.child.killSignal).toBe("SIGKILL");
+    expect(b.child.killSignal).toBe("SIGTERM");
+    expect(c.child.killSignal).toBeUndefined();
+
+    for (const { child, promise } of [a, b, c]) {
+      child.stdout.end();
+      child.emit("close", 143);
+      await promise;
+    }
+  });
+});