@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/execution/__tests__/subagent-service-message-close.test.ts

@@ -13,8 +13,9 @@ import type { ChildProcess } from "node:child_process";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 // mock logger（doFinalizeRecord manifest 写入降级路径用）
-const { loggerMock } = vi.hoisted(() => ({
+const { loggerMock, killEscalationSpy } = vi.hoisted(() => ({
   loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+  killEscalationSpy: vi.fn(),
 }));
 vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
@@ -23,6 +24,9 @@ vi.mock("../session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  killRecordChildWithEscalation: killEscalationSpy,
+  spawnedChildren: new Map(),
 }));
 
 import { createRecord, updateFromEvent } from "../execution-record.ts";
@@ -32,6 +36,9 @@ import { SubagentService } from "../subagent-service.ts";
 import type { PiLike } from "../subagent-service.ts";
 import type { ExecutionRecord } from "../types.ts";
 import { getChildByRecord } from "../session-runner.ts";
+
+// [T2④] kill 收敛入口 spy（工厂引用，断言服务侧三条路径收敛到它）
+const killRecordChildWithEscalationMock = killEscalationSpy;
 import {
   armIdleTimer,
   disarmIdleTimer,
@@ -207,9 +214,8 @@ describe("closeSubagent 行为分流", () => {
     // 旧代码 Path A 走 else 置 closeAfterRound，但 chatMode 轮完成恒经 agent_settled →
     // onRoundSettled → runAndFinalize early return（isIdle 恒 true），标志无人消费，
     // tool 却返回 {closed:true}（谎报）。
-    const killFn = vi.fn(() => true);
-    const child = { killed: false, kill: killFn } as unknown as ChildProcess;
-    vi.mocked(getChildByRecord).mockReturnValueOnce(child);
+    // [T2④] closeChatIdle 的 kill 收敛到 killRecordChildWithEscalation（recordId 入口），
+    // 不再读 child 句柄——无 child mock（Once mock 不被消费会泄漏劫持后续用例）
     const record = makeRecord({ status: "running", round: 1 });
     record.sessionFile = path.join(agentDir, "path-a.jsonl");
     store.register(record);
@@ -226,7 +232,8 @@ describe("closeSubagent 行为分流", () => {
     expect(record.status).toBe("closed");
     expect(record.closedReason).toBe("user-close");
     expect(store.getMutable(record.id)).toBeUndefined(); // archived
-    expect(killFn).toHaveBeenCalledWith("SIGTERM"); // 保活进程回收
+    // [T2④] kill 收敛到 killRecordChildWithEscalation（SIGTERM + 30s SIGKILL 升级）
+    expect(killRecordChildWithEscalationMock).toHaveBeenCalledWith(record.id, "closeChatIdle");
     expect(hasIdleTimer(record.id)).toBe(false); // timer disarmed
   });
 
@@ -253,9 +260,8 @@ describe("closeSubagent 行为分流", () => {
   it("[M6] running + force:true + 活进程（热路径轮中）→ cancelBackground 显式 SIGTERM + disarm idle timer", async () => {
     // chatMode 首轮 agent_settled 后 runSpawn 提前 resolveRun(0) 返回，
     // abort→kill listener 已被 removeEventListener——热路径轮中 cancel 只能靠显式 kill。
-    const killFn = vi.fn(() => true);
-    const child = { killed: false, kill: killFn } as unknown as ChildProcess;
-    vi.mocked(getChildByRecord).mockReturnValueOnce(child);
+    // [T2④] cancelBackground 的 kill 收敛到 killRecordChildWithEscalation（recordId 入口），
+    // 不再读 child 句柄
     const record = makeRecord({ status: "running", sessionFile: path.join(agentDir, "hot.jsonl") });
     record.controller = new AbortController();
     store.register(record);
@@ -268,7 +274,8 @@ describe("closeSubagent 行为分流", () => {
       disarmIdleTimer(record.id); // 断言失败路径的兜底清理
     }
 
-    expect(killFn).toHaveBeenCalledWith("SIGTERM"); // 子进程收到 kill
+    // [T2④] kill 收敛到 killRecordChildWithEscalation（SIGTERM + 升级）
+    expect(killRecordChildWithEscalationMock).toHaveBeenCalledWith(record.id, "cancelBackground");
     expect(record.status).toBe("closed");
     expect(record.closedReason).toBe("cancelled");
     expect(hasIdleTimer(record.id)).toBe(false); // timer disarmed
@@ -276,6 +283,59 @@ describe("closeSubagent 行为分流", () => {
   });
 });
 
+// ============================================================
+// [A2-1] cancel 迟到：record 已终态（detached 已 finalize）→ CAS 拒绝
+// ============================================================
+
+describe("cancelBackground CAS 抢锁（A2-1）——cancel 迟到不覆写已完成 record", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+  let pi: MockPi;
+
+  beforeEach(() => {
+    ({ agentDir, service, store, pi } = setup());
+  });
+
+  afterEach(() => {
+    service.dispose();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("record 已 closed 未 archive（doFinalizeRecord Step 0 await 窗口形态）→ cancel 返回 false，不覆写终态/不写 tombstone/不 notify/不 archive", () => {
+    const sessionFile = path.join(agentDir, "late-cancel.jsonl");
+    const record = makeRecord({ status: "closed", sessionFile });
+    // 模拟 detached 已 finalize 的终态快照（closedReason=gc 正常完成，非 cancelled）
+    record.closedReason = "gc";
+    record.endedAt = 5555;
+    record.result = "detached final result";
+    store.register(record); // 未 archive：恰好处于 finalize await 窗口（收尾后段才 archive）
+
+    const cancelled = service.cancel(record.id);
+
+    expect(cancelled).toBe(false); // CAS 没抢到——不谎报 true
+    expect(record.status).toBe("closed");
+    expect(record.closedReason).toBe("gc"); // 不被 completeRecord 改写为 cancelled
+    expect(record.endedAt).toBe(5555); // finalize 冻结的终态值不被重写
+    expect(record.result).toBe("detached final result"); // 不被空 cancelled result 覆写
+    // 不写 cancelled tombstone（与 finalized marker 双标 = record 双重终态化）
+    expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(false);
+    expect(store.getMutable(record.id)).toBe(record); // 不 archive（record 留内存）
+    expect(pi.sendMessage).not.toHaveBeenCalled(); // 不重复 notify（detached finalize 已发）
+  });
+
+  it("record running → cancel 返回 true 且终态化（CAS 正常路径不回归）", () => {
+    const sessionFile = path.join(agentDir, "cancel-ok.jsonl");
+    const record = makeRecord({ status: "running", sessionFile });
+    store.register(record);
+
+    expect(service.cancel(record.id)).toBe(true);
+    expect(record.status).toBe("closed");
+    expect(record.closedReason).toBe("cancelled");
+    expect(store.getMutable(record.id)).toBeUndefined(); // archived
+  });
+});
+
 // ============================================================
 // [M5] closeAfterRound 消费点：onRoundSettled（chatMode 热路径轮完成）
 // ============================================================
@@ -325,7 +385,8 @@ describe("[M5] closeAfterRound 消费点挂 onRoundSettled（chatMode 轮完成
     expect(record.closeAfterRound).toBeUndefined(); // 标志已消费
     expect(record.status).toBe("closed");
     expect(record.closedReason).toBe("user-close");
-    expect(killFn).toHaveBeenCalledWith("SIGTERM"); // 保活进程回收
+    // [T2④] kill 收敛到 killRecordChildWithEscalation（SIGTERM + 升级）
+    expect(killRecordChildWithEscalationMock).toHaveBeenCalledWith(record.id, "closeAfterRoundSettled");
     expect(hasIdleTimer(record.id)).toBe(false);
   });
 

package/src/execution/__tests__/subagent-service-multiproc-guard.test.ts

@@ -0,0 +1,174 @@
+// src/execution/__tests__/subagent-service-multiproc-guard.test.ts
+//
+// [u-svc / T5] 多进程共享文件守卫（subagent-service 侧两项）：
+//   - T5①/PS-8：子进程 initSession 跳过 recoverOrphanRecords（env PI_SUBAGENT_SELF_RECORD_ID
+//     判子进程身份）——恢复机制假设「单扫描者」，env 贯穿让每个子进程都成了扫描者，
+//     兄弟记录 marker 缺失/超软超时被无关进程盖终态 sidecar；
+//   - T5③/PS-7b：running 候选冷查补 findForeignLiveInstance 探针守卫——异进程活实例在册
+//     时拒绝 resurrect + resume spawn（防双写者窗口）。
+//
+// mock 形态沿用 subagent-service-message-close.test.ts；alive-store mock（findForeignLiveInstance
+// 换 spy 控制探针命中）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+const { killChildSpy, foreignLiveSpy } = vi.hoisted(() => ({
+  killChildSpy: vi.fn(),
+  foreignLiveSpy: vi.fn<() => { pid: number; id: string; startedAt: number } | undefined>(),
+}));
+vi.mock("../alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+  removeAliveMarker: vi.fn(),
+  readAliveMarker: vi.fn(() => undefined),
+  isProcessAlive: vi.fn(() => false),
+  ALIVE_SOFT_TIMEOUT_MS: 3_600_000,
+  findForeignLiveInstance: foreignLiveSpy,
+}));
+
+vi.mock("../session-runner.ts", () => ({
+  runSpawn: vi.fn(),
+  killAllSpawnedChildren: vi.fn(),
+  getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  spawnedChildren: new Map(),
+  killRecordChildWithEscalation: killChildSpy,
+}));
+
+import { ModelConfigService } from "../model-config-service.ts";
+import type { RecordStore } from "../record-store.ts";
+import { SubagentService } from "../subagent-service.ts";
+import { ResurrectDeniedError } from "../types.ts";
+import type { PiLike } from "../subagent-service.ts";
+
+function makeTmpAgentDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "svc-multiproc-"));
+}
+
+function makePi(): PiLike {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  } as unknown as PiLike;
+}
+
+function setup(): { agentDir: string; service: SubagentService; store: RecordStore } {
+  const agentDir = makeTmpAgentDir();
+  const modelService = new ModelConfigService({ agentDir });
+  const service = new SubagentService({ cwd: agentDir, modelService });
+  service.initSession({ pi: makePi(), sessionId: "root-session" });
+  const store = (service as unknown as { store: RecordStore }).store;
+  return { agentDir, service, store };
+}
+
+describe("T5① child process skips orphan recovery scan", () => {
+  let agentDir: string;
+
+  /** 构造 service 并在其 store 上挂 spy 后再 initSession（spy 必须先于触发点）。 */
+  const makeServiceWithRecoverySpies = (): {
+    service: SubagentService;
+    recover: ReturnType<typeof vi.spyOn>;
+    entryOnly: ReturnType<typeof vi.spyOn>;
+  } => {
+    const modelService = new ModelConfigService({ agentDir });
+    const svc = new SubagentService({ cwd: agentDir, modelService });
+    const store = (svc as unknown as { store: RecordStore }).store;
+    const recover = vi.spyOn(store, "recoverOrphanRecords").mockImplementation(() => {});
+    const entryOnly = vi.spyOn(store, "recoverEntryOnlyOrphans").mockImplementation(() => {});
+    return { service: svc, recover, entryOnly };
+  };
+
+  beforeEach(() => {
+    vi.stubEnv("PI_SUBAGENT_SELF_RECORD_ID", "");
+    agentDir = makeTmpAgentDir();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("root process (no self-record env) runs the orphan recovery scan", () => {
+    const { service: root, recover, entryOnly } = makeServiceWithRecoverySpies();
+    root.initSession({ pi: makePi(), sessionId: "root-session-2" });
+    expect(recover).toHaveBeenCalledTimes(1);
+    expect(entryOnly).toHaveBeenCalledTimes(1);
+  });
+
+  it("child process (PI_SUBAGENT_SELF_RECORD_ID set) skips the scan entirely", () => {
+    vi.stubEnv("PI_SUBAGENT_SELF_RECORD_ID", "sa-child-self");
+    const { service: child, recover, entryOnly } = makeServiceWithRecoverySpies();
+    child.initSession({ pi: makePi(), sessionId: "child-session" });
+    expect(recover).not.toHaveBeenCalled();
+    expect(entryOnly).not.toHaveBeenCalled();
+  });
+});
+
+describe("T5③ cold-lookup running candidate foreign-instance guard", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+
+  beforeEach(() => {
+    foreignLiveSpy.mockReset();
+    foreignLiveSpy.mockReturnValue(undefined);
+    ({ agentDir, service, store } = setup());
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  const stubColdCandidate = (record: {
+    id: string;
+    status: "running";
+    sessionFile: string;
+    rootSessionId: string;
+    parentRecordId?: string;
+  }): void => {
+    vi.spyOn(store, "findLightById").mockReturnValue(undefined);
+    vi.spyOn(store, "collectRecords").mockReturnValue([record] as never);
+  };
+
+  it("denies resurrection with ResurrectDeniedError when a foreign live instance holds the session", () => {
+    stubColdCandidate({
+      id: "sa-foreign",
+      status: "running",
+      sessionFile: "/tmp/fake-session.jsonl",
+      rootSessionId: "root-session",
+    });
+    foreignLiveSpy.mockReturnValue({ pid: 4242, id: "sa-foreign", startedAt: Date.now() });
+
+    expect(() => service.getRecordForAction("sa-foreign")).toThrow(ResurrectDeniedError);
+    try {
+      service.getRecordForAction("sa-foreign");
+    } catch (err) {
+      expect((err as Error).message).toContain("4242");
+      expect((err as Error).message).toContain("double-write");
+      expect((err as Error).message).toContain("Recovery");
+    }
+    expect(foreignLiveSpy).toHaveBeenCalledWith("/tmp/fake-session.jsonl");
+  });
+
+  it("allows cold lookup when no foreign live instance (marker dead/stale)", () => {
+    stubColdCandidate({
+      id: "sa-cold",
+      status: "running",
+      sessionFile: "/tmp/fake-session-2.jsonl",
+      rootSessionId: "root-session",
+    });
+    const found = service.getRecordForAction("sa-cold");
+    expect(found.id).toBe("sa-cold");
+  });
+});

package/src/execution/__tests__/subagent-service-notify-gate.test.ts

@@ -0,0 +1,266 @@
+// src/execution/__tests__/subagent-service-notify-gate.test.ts
+//
+// [u-svc / T4] 通知可靠性（subagent-service 侧三措施）：
+//   - T4①/PS-2：kickOffBackground.then notify 门按 closedReason 白名单放行——
+//     parent-new/parent-fork 不注入（可能已切换的）新 session（A-6 决策落实）；
+//   - T4②/PS-4：idleTimeoutMs 非法值（>2^31-1 / 非有限值）在 spawn 入口同步 fail-fast，
+//     错误含合法范围（不静默 clamp、不静默不挂）；
+//   - T4④/PS-5：shutdown flush 被 isIdle 门拦时，未投递 pending 复写落盘（ledger entry
+//     通道，notifyId 幂等）供重启 replay——修复「flush 后 dispose 防丢失」注释承诺差距。
+//
+// mock 形态沿用 subagent-service-message-close.test.ts；notify-ledger 用真模块
+//（bindNotifyLedgerHost + fake host 构造 pending）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+const { killChildSpy } = vi.hoisted(() => ({ killChildSpy: vi.fn() }));
+vi.mock("../session-runner.ts", () => ({
+  runSpawn: vi.fn(),
+  killAllSpawnedChildren: vi.fn(),
+  getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  spawnedChildren: new Map(),
+  killRecordChildWithEscalation: killChildSpy,
+}));
+
+import { bindNotifyLedgerHost, NOTIFY_LEDGER_CUSTOM_TYPE, _resetNotifyLedgerForTest } from "../notify-ledger.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import type { RecordStore } from "../record-store.ts";
+import { notifyGateAllowsDelivery, SubagentService } from "../subagent-service.ts";
+import type { PiLike } from "../subagent-service.ts";
+import { MAX_TIMER_DELAY_MS } from "../../shared/timer-delay.ts";
+import type { ExecutionRecord } from "../types.ts";
+
+function makeTmpAgentDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "svc-notify-gate-"));
+}
+
+function makePi(): PiLike & {
+  appendEntry: ReturnType<typeof vi.fn>;
+  events: { emit: ReturnType<typeof vi.fn> };
+  sendMessage: ReturnType<typeof vi.fn>;
+  on?: ReturnType<typeof vi.fn>;
+} {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  } as unknown as PiLike & {
+    appendEntry: ReturnType<typeof vi.fn>;
+    events: { emit: ReturnType<typeof vi.fn> };
+    sendMessage: ReturnType<typeof vi.fn>;
+    on?: ReturnType<typeof vi.fn>;
+  };
+}
+
+interface ServiceInternals {
+  store: RecordStore;
+}
+
+type MockPi = ReturnType<typeof makePi>;
+
+function setup(initOverrides: Partial<{ isIdle: () => boolean }> = {}): {
+  agentDir: string;
+  service: SubagentService;
+  store: RecordStore;
+  pi: MockPi;
+} {
+  const agentDir = makeTmpAgentDir();
+  const modelService = new ModelConfigService({ agentDir });
+  const service = new SubagentService({ cwd: agentDir, modelService });
+  const pi = makePi();
+  service.initSession({ pi, sessionId: "root-session", isIdle: initOverrides.isIdle });
+  const store = (service as unknown as ServiceInternals).store;
+  return { agentDir, service, store, pi };
+}
+
+describe("T4① notify gate closedReason whitelist", () => {
+  it("blocks cancelled, parent-new, parent-fork; allows real closures and undefined (CAS-winner path)", () => {
+    expect(notifyGateAllowsDelivery("cancelled")).toBe(false);
+    expect(notifyGateAllowsDelivery("parent-new")).toBe(false);
+    expect(notifyGateAllowsDelivery("parent-fork")).toBe(false);
+    expect(notifyGateAllowsDelivery("user-close")).toBe(true);
+    expect(notifyGateAllowsDelivery("gc")).toBe(true);
+    expect(notifyGateAllowsDelivery("parent-shutdown")).toBe(true);
+    expect(notifyGateAllowsDelivery(undefined)).toBe(true);
+  });
+
+  it("kickOffBackground.then does not inject parent-new closed records into the session", async () => {
+    const { agentDir, service, pi } = setup();
+    const record = createRecord("sa-gate-new", {
+      agent: "general-purpose",
+      model: "test/model",
+      mode: "background",
+      task: "test",
+      startedAt: 1000,
+      rootSessionId: "root-session",
+      controller: new AbortController(),
+    });
+    // 模拟 disposeAllRecords 先行编排性关闭后，迟到的 kickOffBackground.then 回注
+    record.closedReason = "parent-new";
+    const stub = vi.fn().mockResolvedValue({
+      text: "",
+      turns: 0,
+      durationMs: 1,
+      success: false,
+      error: "closed due to parent-new",
+      sessionId: record.id,
+      toolCalls: [],
+    });
+    (service as unknown as Record<string, unknown>).runAndFinalize = stub;
+    const kickOffBackground = (
+      service as unknown as Record<string, (...args: unknown[]) => void>
+    )["kickOffBackground"];
+    kickOffBackground.call(service, record, { task: "t" }, {}, {}, undefined, 1000, undefined);
+    await vi.waitFor(() => expect(stub).toHaveBeenCalled());
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(pi.sendMessage).not.toHaveBeenCalled();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("kickOffBackground.then still notifies for real failure closures (gc)", async () => {
+    const { agentDir, service, pi } = setup();
+    const record = createRecord("sa-gate-gc", {
+      agent: "general-purpose",
+      model: "test/model",
+      mode: "background",
+      task: "test",
+      startedAt: 1000,
+      rootSessionId: "root-session",
+      controller: new AbortController(),
+    });
+    record.closedReason = "gc";
+    (service as unknown as Record<string, unknown>).runAndFinalize = vi.fn().mockResolvedValue({});
+    const kickOffBackground = (
+      service as unknown as Record<string, (...args: unknown[]) => void>
+    )["kickOffBackground"];
+    kickOffBackground.call(service, record, { task: "t" }, {}, {}, undefined, 1000, undefined);
+    await vi.waitFor(() => expect(pi.sendMessage).toHaveBeenCalled());
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+});
+
+describe("T4② idleTimeoutMs entry fail-fast", () => {
+  let agentDir: string;
+  let service: SubagentService;
+
+  beforeEach(() => {
+    ({ agentDir, service } = setup());
+  });
+
+  afterEach(() => {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("execute rejects idleTimeoutMs above the setTimeout limit with the valid range in the message", async () => {
+    await expect(service.execute({ task: "x", idleTimeoutMs: MAX_TIMER_DELAY_MS + 1 })).rejects.toThrow(
+      new RegExp(`${MAX_TIMER_DELAY_MS}`),
+    );
+    await expect(service.execute({ task: "x", idleTimeoutMs: 3_000_000_000 })).rejects.toThrow(/2\^31-1/);
+  });
+
+  it("execute rejects non-finite idleTimeoutMs", async () => {
+    await expect(service.execute({ task: "x", idleTimeoutMs: Number.NaN })).rejects.toThrow(/not a finite number/);
+  });
+
+  it("rejects before any record is created (no side effects)", async () => {
+    const internals = service as unknown as ServiceInternals;
+    await expect(service.executeAndAwait({ task: "x", idleTimeoutMs: 3_000_000_000 })).rejects.toThrow();
+    expect(internals.store.listRunning()).toHaveLength(0);
+  });
+
+  it("accepts valid values (0 = explicit disable, positive within limit)", async () => {
+    // 校验通过后执行链继续（runSpawn 被 mock，返回 undefined result 会在后续流程抛错/
+    // 返回——但绝不能是 idleTimeoutMs 校验错误）
+    await expect(service.execute({ task: "x", idleTimeoutMs: 0 })).rejects.not.toThrow(/idleTimeoutMs/);
+  });
+});
+
+describe("T4④ shutdown flush blocked → pending persisted for replay", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let pi: MockPi;
+
+  beforeEach(() => {
+    _resetNotifyLedgerForTest();
+    ({ agentDir, service, pi } = setup({ isIdle: () => false }));
+  });
+
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  it("persists undelivered pending notifications as ledger entries on dispose when main agent is busy", () => {
+    // 绑定真 ledger 并制造一条未投递 pending（isIdle=false → attemptDeliver 挂回 pending）
+    const ledger = bindNotifyLedgerHost({
+      appendLedgerEntry: (customType, data) => pi.appendEntry(customType, data),
+      readSessionEntries: () => [],
+      isIdle: () => false,
+      onAgentSettled: () => {},
+      sendDelivery: (message) => pi.sendMessage(message as never),
+    });
+    const recorded = ledger.record("notify-1", "Subagent x completed", { id: "sa-x", agent: "x" });
+    expect(recorded).toBe(true);
+    expect(ledger.pendingEntries()).toHaveLength(1);
+
+    service.dispose();
+
+    // 复写落盘：NOTIFY_LEDGER_CUSTOM_TYPE entry 携带 notifyId（幂等键）+ v1 schema
+    const replayEntries = pi.appendEntry.mock.calls.filter(
+      (c) => c[0] === NOTIFY_LEDGER_CUSTOM_TYPE && (c[1] as { notifyId?: string })?.notifyId === "notify-1",
+    );
+    expect(replayEntries.length).toBeGreaterThanOrEqual(2); // record 原账 + dispose 复写
+    expect(replayEntries[0]?.[1]).toMatchObject({ v: 1, notifyId: "notify-1" });
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("persisted to ledger for replay"),
+      expect.objectContaining({ count: 1 }),
+    );
+    // 重启 replay 可重放：新 ledger 实例扫账面（含复写 entry）应入账该 pending
+    const host2 = {
+      appendLedgerEntry: vi.fn(),
+      readSessionEntries: () =>
+        pi.appendEntry.mock.calls
+          .filter((c) => c[0] === NOTIFY_LEDGER_CUSTOM_TYPE)
+          .map((c) => ({ type: "custom", customType: c[0], data: c[1] })),
+      isIdle: () => false,
+      onAgentSettled: () => {},
+      sendDelivery: vi.fn(),
+    };
+    const ledger2 = bindNotifyLedgerHost(host2);
+    expect(ledger2.recoverFromSession()).toBe(1);
+  });
+
+  it("does not rewrite when main agent is idle (flush already delivered)", () => {
+    const ledger = bindNotifyLedgerHost({
+      appendLedgerEntry: (customType, data) => pi.appendEntry(customType, data),
+      readSessionEntries: () => [],
+      isIdle: () => false,
+      onAgentSettled: () => {},
+      sendDelivery: (message) => pi.sendMessage(message as never),
+    });
+    ledger.record("notify-2", "content", { id: "sa-y" });
+    pi.appendEntry.mockClear();
+
+    // idle service：flush 投出（无门拦），dispose 无复写动作
+    const idleService = new SubagentService({
+      cwd: agentDir,
+      modelService: new ModelConfigService({ agentDir }),
+    });
+    const piIdle = makePi();
+    idleService.initSession({ pi: piIdle, sessionId: "root-session", isIdle: () => true });
+    idleService.dispose();
+    expect(piIdle.appendEntry).not.toHaveBeenCalled();
+  });
+});

package/src/execution/__tests__/subagent-service-parent-guard.test.ts

@@ -30,6 +30,9 @@ vi.mock("../session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  killRecordChildWithEscalation: vi.fn(),
+  spawnedChildren: new Map(),
 }));
 
 import { createRecord } from "../execution-record.ts";