@zhushanwen/subagent-core 0.2.0 → 0.4.0

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

@@ -0,0 +1,378 @@
+// 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）。
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// [A1-2③] Mock 共享 logger：复核失败的 warn 留痕可被断言（对齐 run-spawn-edges 模式）。
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({
+  getLogger: () => loggerMock,
+}));
+
+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(),
+  // [T5②] keep-alive 心跳刷新读取现有 marker id（缺失兜底 record.id）
+  readAliveMarker: vi.fn(() => undefined),
+  isProcessAlive: vi.fn(() => false),
+}));
+
+// keep-alive 判定：本文件统一 count>0（有活跃后代 → keep-alive 分支）。
+vi.mock("../session-pending.ts", () => ({
+  readActivePendingFromSessionFile: vi.fn(() => ({ count: 1, recentUnregister: false })),
+  prunePendingCursor: vi.fn(),
+  listActivePendingFromSessionFile: vi.fn(() => ({ items: [] })),
+}));
+
+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 {
+  KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS,
+  maxTurnsToWatchdogMs,
+  runSpawn,
+  SPAWN_WATCHDOG_ENV,
+} from "../session-runner.ts";
+import { listActivePendingFromSessionFile, readActivePendingFromSessionFile } from "../session-pending.ts";
+import { isProcessAlive, readAliveMarker, writeAliveMarker } from "../alive-store.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 mockPending = vi.mocked(readActivePendingFromSessionFile);
+const mockListPending = vi.mocked(listActivePendingFromSessionFile);
+const mockReadAliveMarker = vi.mocked(readAliveMarker);
+const mockWriteAliveMarker = vi.mocked(writeAliveMarker);
+const mockIsProcessAlive = vi.mocked(isProcessAlive);
+const mockReaddirSync = vi.mocked(fs.readdirSync);
+
+/** 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);
+
+/** 非 chatMode 层主 + fake timers + agent_end keep-alive 落位的公共前奏。 */
+async function spawnAndReachKeepAlive(opts = makeOpts()): Promise<{
+  child: FakeChild;
+  finish: (code?: number) => Promise<Awaited<ReturnType<typeof runSpawn>>>;
+}> {
+  const record = makeRecord();
+  const promise = runSpawn(record, "Task: keep-alive no-progress", opts, makeCtx());
+  await waitForSpawn();
+  const child = lastSpawnedChild();
+  // fake timers 必须在 emit agent_end 之前启用（keep-alive timer 新建于 agent_end
+  // 处理器内；不 fake setImmediate——stream flush 靠真实事件循环交付，见 MF-3 先例）。
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
+  emitStdoutLine(child, sessionHeaderLine());
+  emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+  await new Promise((r) => setImmediate(r));
+  return {
+    child,
+    finish: (code = 143) => {
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", code);
+      return promise as Promise<Awaited<ReturnType<typeof runSpawn>>>;
+    },
+  };
+}
+
+function sessionHeaderLine(): Record<string, unknown> {
+  return { type: "session", id: "sess-ka", timestamp: "2026-09-01T00:00:00.000Z", cwd: "/tmp/test" };
+}
+
+describe("[T2-①] keep-alive 裸缺省无进展检测上界（P-T2 降级路径 B）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubEnv(SPAWN_WATCHDOG_ENV, "");
+    mockPending.mockReturnValue({ count: 1, recentUnregister: false });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+    vi.useRealTimers();
+  });
+
+  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 record = makeRecord();
+    const promise = runSpawn(record, "Task: keep-then-final", makeOpts(), makeCtx());
+    await waitForSpawn();
+    const child = lastSpawnedChild();
+
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
+    emitStdoutLine(child, sessionHeaderLine());
+    // 第一次 agent_end：keep-alive（挂无进展 timer）
+    emitStdoutLine(child, { type: "agent_end", messages: [], willRetry: false });
+    await new Promise((r) => setImmediate(r));
+    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 收尾）
+    child.stdout.end();
+    child.stderr.end();
+    child.emit("close", 143);
+    const result = (await promise) as Awaited<ReturnType<typeof runSpawn>>;
+    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 同源判据）
+    mockListPending.mockReturnValue({
+      items: [{ id: "bg-1", sessionId: "ka-desc-sess", type: "session" }],
+    });
+    mockReaddirSync.mockReturnValue(["20260901T000000-000_ka-desc-sess.jsonl"]);
+    mockReadAliveMarker.mockImplementation((f: unknown) =>
+      String(f).endsWith("_ka-desc-sess.jsonl")
+        ? { pid: LIVE_DESCENDANT_PID, id: "ka-desc-sess", startedAt: 0 }
+        : undefined,
+    );
+    mockIsProcessAlive.mockImplementation((pid: number) => pid === LIVE_DESCENDANT_PID);
+
+    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 () => {
+    mockListPending.mockReturnValue({
+      items: [{ id: "bg-1", sessionId: "ka-dead-sess", type: "session" }],
+    });
+    mockReaddirSync.mockReturnValue(["20260901T000000-000_ka-dead-sess.jsonl"]);
+    mockReadAliveMarker.mockImplementation((f: unknown) =>
+      String(f).endsWith("_ka-dead-sess.jsonl")
+        ? { pid: DEAD_DESCENDANT_PID, id: "ka-dead-sess", startedAt: 0 }
+        : undefined,
+    );
+    mockIsProcessAlive.mockReturnValue(false); // 全部已死
+
+    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("../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 "../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;
+    }
+  });
+});

package/src/execution/__tests__/lifecycle-manager-idle-timer-identity.test.ts

@@ -0,0 +1,117 @@
+// src/execution/__tests__/lifecycle-manager-idle-timer-identity.test.ts
+//
+// [LC-5/T6①] armIdleTimer 超时回调身份比对（按值守卫，对齐 session-runner
+// removeChildRegistration 先例）。
+//
+// 覆盖（设计 §4.3 LC-5 + §11-2）：
+//   1. 「旧 timer 已到期、回调迟到执行」与「同 recordId re-arm」精确交错 → 守卫不误删
+//      新条目（旧代码此处误删 = 新 timer 脱管、disarm 失效 → turn 中途误杀）。
+//   2. 无交错时旧 timer 到点删除自己的条目 + 后续 re-arm 正常（既有语义不回归）。
+//   3. fake timers 下「re-arm 发生在旧 timer 到期回调处置中」的同轮交错端到端：
+//      新 timer 存活、到点正常触发、Map 清理干净。
+//
+// 交错构造说明（§11-2 勘误锚点）：sinon fake clock 的同步 tick 模型在「时间推进」的
+// 同一同步流程内立即执行到期回调，不存在「已到期、回调已入队、尚未执行」的中间态
+// 暴露给 clearTimeout——纯 fake timers 无法表达 Node 真实窗口（fire 后回调入
+// macrotask 队列，clearTimeout 不可撤销）。用例 1/2 以手动排程 fake（stub setTimeout
+// 捕获回调、测试显式控制 fire 时机）精确复现该中间态；用例 3 补真实 clock 语义下的
+// 同轮交错端到端回归。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  _resetLifecycleState,
+  armIdleTimer,
+  disarmIdleTimer,
+  hasIdleTimer,
+} from "../lifecycle-manager.ts";
+
+/** 手动排程 fake 捕获的到期回调（fire = 模拟 timer 到点，时机由用例显式控制）。 */
+let scheduled: Array<{ fire: () => void; timer: object }>;
+
+beforeEach(() => {
+  _resetLifecycleState();
+  scheduled = [];
+  // 手动排程模型：setTimeout 只登记不排程；clearTimeout no-op（「已入队回调不可撤销」
+  // 的真实语义由用例不 fire 被撤销者来表达）。
+  vi.stubGlobal(
+    "setTimeout",
+    (cb: () => void, _delay?: number) => {
+      void _delay;
+      const timer: object = {};
+      scheduled.push({ fire: cb, timer });
+      return Object.assign(timer, { unref() {} });
+    },
+  );
+  vi.stubGlobal("clearTimeout", (_t?: unknown) => {
+    void _t;
+  });
+});
+
+afterEach(() => {
+  _resetLifecycleState();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("[LC-5] armIdleTimer 超时回调身份比对", () => {
+  it("旧 timer 到点回调迟到执行（re-arm 已覆盖条目）→ 守卫不误删新条目，disarm 仍有效", () => {
+    const onTimeoutA = vi.fn();
+    const onTimeoutB = vi.fn();
+
+    armIdleTimer("sa-x", onTimeoutA, 1000); // timerA 入手 排程表，Map: timerA
+    // re-arm（agent_settled 刷新）：disarm 旧 timer（真实 Node 中 clearTimeout 对已
+    // 入队回调无效）→ timerB 入表，Map: timerB。此后 timerA 的回调才迟到执行。
+    armIdleTimer("sa-x", onTimeoutB, 1000);
+    expect(hasIdleTimer("sa-x")).toBe(true);
+
+    scheduled[0]?.fire(); // 旧 timerA 回调迟到执行
+
+    expect(onTimeoutA).toHaveBeenCalledTimes(1); // 旧超时回调本身照常触发
+    expect(hasIdleTimer("sa-x")).toBe(true); // [核心] 新条目未被误删（旧代码此处 false = 脱管）
+
+    disarmIdleTimer("sa-x"); // B 未脱管：disarm 有效
+    expect(hasIdleTimer("sa-x")).toBe(false);
+    expect(onTimeoutB).not.toHaveBeenCalled();
+  });
+
+  it("无交错：旧 timer 到点删除自己的条目（守卫不改变既有语义），后续 re-arm 正常", () => {
+    const onTimeoutA = vi.fn();
+    const onTimeoutB = vi.fn();
+
+    armIdleTimer("sa-y", onTimeoutA, 1000);
+    expect(hasIdleTimer("sa-y")).toBe(true);
+
+    scheduled[0]?.fire(); // 正常到点：Map 中是自己 → delete → 回调
+
+    expect(onTimeoutA).toHaveBeenCalledTimes(1);
+    expect(hasIdleTimer("sa-y")).toBe(false); // 旧条目删除正常（不残留失效 entry）
+
+    armIdleTimer("sa-y", onTimeoutB, 1000); // 后续 re-arm 正常
+    expect(hasIdleTimer("sa-y")).toBe(true);
+    scheduled[1]?.fire();
+    expect(onTimeoutB).toHaveBeenCalledTimes(1);
+    expect(hasIdleTimer("sa-y")).toBe(false);
+  });
+
+  it("fake timers 同轮交错：re-arm 发生在旧 timer 到期回调处置中 → 新 timer 存活到点触发", () => {
+    vi.useFakeTimers();
+    const onTimeoutB = vi.fn();
+    const onTimeoutA = vi.fn(() => {
+      // 到期回调处置中同步 re-arm（同轮交错的 fake-timer 可达形态）
+      armIdleTimer("sa-z", onTimeoutB, 1000);
+    });
+
+    armIdleTimer("sa-z", onTimeoutA, 1000);
+    vi.advanceTimersByTime(1000); // A 到点：删自己 → onTimeoutA → re-arm B
+
+    expect(onTimeoutA).toHaveBeenCalledTimes(1);
+    expect(hasIdleTimer("sa-z")).toBe(true); // B armed，交错不丢 timer
+
+    vi.advanceTimersByTime(999);
+    expect(onTimeoutB).not.toHaveBeenCalled(); // B 从 arm 时刻重新计时
+    vi.advanceTimersByTime(1);
+    expect(onTimeoutB).toHaveBeenCalledTimes(1); // B 存活到点正常触发
+    expect(hasIdleTimer("sa-z")).toBe(false); // 触发后 Map 清理干净
+  });
+});