@zhushanwen/subagent-core 0.4.0 → 0.6.0

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

@@ -1,9 +1,10 @@
 // src/execution/__tests__/epipe-fallback.test.ts
 //
-// deliverMessage EPIPE 兜底集成测试——热路径 stdin 写入 EPIPE 时自动转冷路径 resume + 消息重放。
+// deliverChatMessage EPIPE 兜底集成测试——热路径 stdin 写入 EPIPE 时自动转冷路径续轮 + 消息重放
+//（D2 后投递协议知识在 PiEngine.deliverPrompt，编排层经 engine.interactRecord 进入）。
 //
 // 场景覆盖：
-//   1. 首次 EPIPE → 自动转冷路径 resumeRound（runSpawn 收到 resume 参数 + 原消息）
+//   1. 首次 EPIPE → 自动转冷路径续轮（runSpawn 收到 resume 参数 + 原消息）
 //   2. 连续 2 次 EPIPE → throw 含恢复指引（防无限循环）
 //   3. 热路径成功写入后清零 EPIPE 计数（正常路径不受影响）
 
@@ -22,7 +23,7 @@ vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
 // mock session-runner：runSpawn 受控 + killAllSpawnedChildren 空实现；
 // getChildByRecord/spawnedChildren 提供真实 Map 语义。
-vi.mock("../session-runner.ts", () => {
+vi.mock("../engine/engines/pi/session-runner.ts", () => {
   const spawnedChildren = new Map<string, unknown>();
   return {
     runSpawn: vi.fn(),
@@ -34,7 +35,7 @@ vi.mock("../session-runner.ts", () => {
   };
 });
 
-import { runSpawn, spawnedChildren } from "../session-runner.ts";
+import { runSpawn, spawnedChildren } from "../engine/engines/pi/session-runner.ts";
 import * as lifecycle from "../lifecycle-manager.ts";
 import { createRecord } from "../execution-record.ts";
 import { ModelConfigService } from "../model-config-service.ts";
@@ -50,11 +51,15 @@ function makeTmpAgentDir(): string {
 }
 
 function makePi(): PiLike & {
-  appendEntry: ReturnType<typeof vi.fn>;
-  events: { emit: ReturnType<typeof vi.fn> };
-  sendMessage: ReturnType<typeof vi.fn>;
+  appendEntry: ReturnType<typeof vi.fn<(customType: string, data?: unknown) => void>>;
+  events: { emit: ReturnType<typeof vi.fn<(channel: string, data: unknown) => void>> };
+  sendMessage: ReturnType<typeof vi.fn<(message: Parameters<PiLike["sendMessage"]>[0], options?: Parameters<PiLike["sendMessage"]>[1]) => void>>;
 } {
-  return { appendEntry: vi.fn(), events: { emit: vi.fn() }, sendMessage: vi.fn() };
+  return {
+    appendEntry: vi.fn((customType: string, data?: unknown) => {}),
+    events: { emit: vi.fn((channel: string, data: unknown) => {}) },
+    sendMessage: vi.fn(() => {}),
+  };
 }
 
 function makeResult(success: boolean): AgentResult {
@@ -110,17 +115,17 @@ function makeNormalChild(): ChildProcess {
 }
 
 // ============================================================
-// deliverMessage EPIPE 兜底
+// deliverChatMessage EPIPE 兜底
 // ============================================================
 
-describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resume）", () => {
+describe("deliverChatMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径续轮）", () => {
   let agentDir: string;
   let service: SubagentService;
   let record: ExecutionRecord;
 
   beforeEach(() => {
     agentDir = makeTmpAgentDir();
-    const modelService = new ModelConfigService({ agentDir });
+    const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
     service = new SubagentService({ cwd: agentDir, modelService });
     service.initSession({ pi: makePi(), sessionId: "root-session" });
     record = makeIdleRecord();
@@ -135,7 +140,7 @@ describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resu
     service.dispose();
     spawnedChildren.clear();
     lifecycle._resetLifecycleState();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("首次 EPIPE → 自动转冷路径 resumeRound + 原消息重放", async () => {
@@ -143,13 +148,13 @@ describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resu
     // 注册 EPIPE child（热路径会命中但 stdin.write 抛 EPIPE）
     spawnedChildren.set(record.id, makeEpipeChild());
 
-    // deliverMessage 不 throw（首次 EPIPE 走 resume 兜底）
-    await expect(service.deliverMessage(record, "msg after epipe", false)).resolves.toBeUndefined();
+    // 投递不 throw（首次 EPIPE 走续轮兜底）
+    await expect(service.chatActions.deliverChatMessage(record, "msg after epipe", false)).resolves.toBeUndefined();
 
     // spawnedChildren 中的死进程条目已清理（EPIPE catch 块 delete）
     expect(spawnedChildren.has(record.id)).toBe(false);
 
-    // resumeRound 被触发（冷路径），runSpawn 收到 resume 参数 + 原消息
+    // 冷路径续轮被触发，runSpawn 收到 resume 参数 + 原消息
     await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
     const call = mockRunSpawn.mock.calls[0]!;
     expect(call[1]).toBe("msg after epipe");
@@ -174,7 +179,7 @@ describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resu
     spawnedChildren.set(record.id, makeEpipeChild());
 
     // 第 1 次：EPIPE → resume（不 throw）
-    await service.deliverMessage(record, "first epipe", false);
+    await service.chatActions.deliverChatMessage(record, "first epipe", false);
     await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
 
     // resume 完成后 record 回 running（v4 B-1：finalizeRoundToIdle 设 running，旧 idle 折入）
@@ -184,10 +189,10 @@ describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resu
     spawnedChildren.set(record.id, makeEpipeChild());
 
     // 第 2 次 EPIPE → throw 含恢复指引（连续 2 次触发 exhaustion）
-    // 注意：第二 EPIPE 时 count 已为 2，catch 块立即 throw（不经过 resumeRound）。
+    // 注意：第二 EPIPE 时 count 已为 2，catch 块立即 throw（不经过续轮）。
     let thrown: unknown;
     try {
-      await service.deliverMessage(record, "second epipe", false);
+      await service.chatActions.deliverChatMessage(record, "second epipe", false);
     } catch (err) {
       thrown = err;
     }
@@ -203,13 +208,13 @@ describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resu
 
     // 第 1 轮：EPIPE → resume
     spawnedChildren.set(record.id, makeEpipeChild());
-    await service.deliverMessage(record, "epipe msg", false);
+    await service.chatActions.deliverChatMessage(record, "epipe msg", false);
     await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
     await vi.waitFor(() => expect(record.status).toBe("running"));
 
     // 第 2 轮：正常 child，成功写入（清零 EPIPE 计数）
     spawnedChildren.set(record.id, makeNormalChild());
-    await service.deliverMessage(record, "normal msg", true);
+    await service.chatActions.deliverChatMessage(record, "normal msg", true);
     // 不 throw，status=running（热路径成功）
     expect(record.status).toBe("running");
 
@@ -217,7 +222,7 @@ describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resu
     // 需要先让 record 回 running（等待续聊态）
     record.status = "running";
     spawnedChildren.set(record.id, makeEpipeChild());
-    await expect(service.deliverMessage(record, "after reset", false)).resolves.toBeUndefined();
+    await expect(service.chatActions.deliverChatMessage(record, "after reset", false)).resolves.toBeUndefined();
   });
 
   it("EPIPE 兜底与冷路径共用 in-flight 守卫：resume 在途时 EPIPE 兜底不再二次 spawn（review round2 MF1）", async () => {
@@ -226,14 +231,14 @@ describe("deliverMessage EPIPE 兜底（热路径 stdin EPIPE → 冷路径 resu
     mockRunSpawn.mockImplementationOnce(
       () => new Promise<AgentResult>((res) => { releaseFirst = res; }),
     );
-    await service.deliverMessage(record, "cold path first", false);
+    await service.chatActions.deliverChatMessage(record, "cold path first", false);
     await vi.waitFor(() => expect(mockRunSpawn).toHaveBeenCalledTimes(1));
 
-    // 注册 EPIPE child → deliverMessage 走热路径 → stdin EPIPE → 兜底调 resumeRound
+    // 注册 EPIPE child → 投递走热路径 → stdin EPIPE → 兜底调冷路径续轮
     // → in-flight 命中 → throw（不再走第二次 spawn。EPIPE 计数仍 +1 但未达阈值 2，
     // exhaustion 分支不触发；throw 由兜底路径的 resumeRound 守卫抛出）
     spawnedChildren.set(record.id, makeEpipeChild());
-    await expect(service.deliverMessage(record, "epipe during resume", false)).rejects.toThrow(
+    await expect(service.chatActions.deliverChatMessage(record, "epipe during resume", false)).rejects.toThrow(
       /already starting a new round/,
     );
     expect(mockRunSpawn).toHaveBeenCalledTimes(1);

package/src/execution/__tests__/execute-and-await-worktree.test.ts

@@ -8,101 +8,31 @@
 // ── mock 策略 ──
 //
 // 复用 execute-nesting.test.ts 的 spawn / node:fs / manifest-store / temp-prompt / alive-store
-// / finalized-marker mock 范式（见该文件头部详细注释）。本文件 **不驱动 FakeChild 完成**——
-// 被测的两个分支都在 runSpawn 之前抛/收尾（worktree create 在步骤 2.5，runSpawn 在步骤 5），
-// 因此 spawn 即使被调也无人驱动，测试在抛错后立即断言即可结束。
+// / finalized-marker mock 范式，已收敛到 ./helpers/subagent-service-mocks.ts 单源（四文件
+// 共享）。本文件 **不驱动 FakeChild 完成**——被测的两个分支都在 runSpawn 之前抛/收尾
+// （worktree create 在步骤 2.5，runSpawn 在步骤 5），因此 spawn 即使被调也无人驱动，
+// 测试在抛错后立即断言即可结束。
 //
 // worktreeManager 是 SubagentService 构造时 new 出的私有字段（WorktreeManager 实例，非模块）。
 // 测试 2 用 vi.spyOn(Reflect.get(service, "worktreeManager"), "create") 注入抛错，无需模块级 mock。
 
-import { PassThrough } from "node:stream";
-
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-// ── mock modules（与 execute-nesting.test.ts 同范式）──
-
-vi.mock("node:child_process", async () => {
-  const { EventEmitter } = await import("node:events");
-  const { PassThrough } = await import("node:stream");
-
-  class FakeChild extends EventEmitter {
-    pid = 12345;
-    stdout = new PassThrough();
-    stderr = new PassThrough();
-    killed = false;
-    killSignal: string | undefined;
-    kill(sig?: string): boolean {
-      this.killed = true;
-      this.killSignal = sig;
-      return true;
-    }
-  }
-
-  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", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../alive-store.ts")>();
-  return {
-    ...actual,
-    writeAliveMarker: vi.fn(),
-    removeAliveMarker: vi.fn(),
-  };
-});
-
-vi.mock("../finalized-marker.ts", () => ({
-  writeFinalized: vi.fn(),
-  readFinalized: vi.fn(() => false),
-}));
-
-vi.mock("../manifest-store.ts", () => {
-  class FakeManifestStore {
-    writeManifest = vi.fn(async () => {});
-    readManifest = vi.fn(async () => null);
-    listAllSync = vi.fn(() => []);
-    recoverTmpFiles = vi.fn(async () => []);
-  }
-  return { ManifestStore: FakeManifestStore };
-});
-
-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 {
+  aliveStoreModule,
+  childProcessModule,
+  finalizedMarkerModule,
+  fsSyncModule,
+  manifestStoreModule,
+  tempPromptModule,
+} from "./helpers/subagent-service-mocks.ts";
+
+vi.mock("node:child_process", () => childProcessModule());
+vi.mock("node:fs", async (importOriginal) => fsSyncModule(await importOriginal<typeof import("node:fs")>()));
+vi.mock("../alive-store.ts", async (importOriginal) => aliveStoreModule(await importOriginal<typeof import("../alive-store.ts")>()));
+vi.mock("../finalized-marker.ts", () => finalizedMarkerModule());
+vi.mock("../manifest-store.ts", () => manifestStoreModule());
+vi.mock("../engine/engines/pi/temp-prompt.ts", () => tempPromptModule());
 
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
@@ -127,7 +57,7 @@ interface SetupResult {
 
 function setup(): SetupResult {
   const agentDir = "/tmp/exec-await-worktree-it"; // fs 已 mock，路径不需真实存在
-  const modelService = new ModelConfigService({ agentDir });
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
   modelService.initModel({
     modelRegistry: makeEmptyRegistry(),
     sessionId: "exec-await-worktree-it",
@@ -219,7 +149,7 @@ describe("executeAndAwait worktree 失败收尾", () => {
     }) as Parameters<WorktreeManager["cleanup"]>[0];
     let resolveCreate!: (h: unknown) => void;
     vi.spyOn(worktreeManager, "create").mockImplementation(
-      () => new Promise((r) => { resolveCreate = r; }) as ReturnType<WorktreeManager["create"]>,
+      () => new Promise<unknown>((r) => { resolveCreate = r; }) as ReturnType<WorktreeManager["create"]>,
     );
     const cleanupSpy = vi.spyOn(worktreeManager, "cleanup").mockResolvedValue(undefined);
 

package/src/execution/__tests__/execute-nesting.test.ts

@@ -15,134 +15,36 @@
 //   因此本文件 mock 的是 node:child_process.spawn（返回 FakeChild），而非 getSdk/fakeSession
 //   （那是对 in-process run() 的旧 mock，在 spawn 改造后是死代码）。
 //
-//   mock 模式参考 run-spawn-integration.test.ts（该文件是 spawn 改造后的正确 mock 范式）：
-//     - node:child_process.spawn → FakeChild（EventEmitter + PassThrough），测试控制器
-//       emit stdout JSON 行（header + SdkEvent）/ stderr / close 时序。
-//     - node:child_process.execFile → err-first callback 默认兜底（buildEnvBlock 的 git
-//       branch 调用失败 → catch → branch=""，避免副作用）。
-//     - node:fs 同步方法 → mock（mkdirSync/existsSync/appendFileSync/writeFileSync/readdirSync），
-//       避免 sessionDir/sessionFile 触碰真实文件系统。
-//     - fs.promises.* → 保留真实实现（temp-prompt 整体被 mock，不触发真实 I/O）。
-//     - temp-prompt → mock（writePromptToTempFile 返回固定路径，消除 fake-timers flaky）。
-//     - alive-store.writeAliveMarker → mock（避免写 .alive sidecar）。
+//   mock 模块工厂已收敛 ./helpers/subagent-service-mocks.ts（四文件共享单源，含
+//   spawn → FakeChild / fs 同步方法 / temp-prompt / alive-store / finalized-marker /
+//   manifest-store 的完整桩形与动机注释）。
 //
 //   所有断言语义不变：它们测的是 SubagentService 的 **编排逻辑**
 //   （pool.acquire / execCtxAls 深度），这些逻辑
 //   无论事件来自 fakeSession.subscribe 还是 FakeChild.stdout 都一致。
 
-import type { PassThrough } from "node:stream";
-
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-// ── mock modules ──
-//
-// vitest 会把 vi.mock 提升到文件顶部（早于其他 import / 声明）。mock 工厂若要引用
-// FakeChild，需在工厂内部 import（async 工厂可用 await import），而非引用顶部
-// 顶层 import（它们在 vi.mock 执行时尚未绑定）。
-
-vi.mock("node:child_process", async () => {
-  const { EventEmitter } = await import("node:events");
-  const { PassThrough } = await import("node:stream");
-
-  // FakeChild：模拟 ChildProcess（EventEmitter + PassThrough streams）。
-  // 测试通过 lastSpawnedChild() 取回实例，控制 emit stdout JSON 行 / close 时序。
-  class FakeChild extends EventEmitter {
-    pid = 12345;
-    stdout = new PassThrough();
-    stderr = new PassThrough();
-    killed = false;
-    killSignal: string | undefined;
-    kill(sig?: string): boolean {
-      this.killed = true;
-      this.killSignal = sig;
-      return true;
-    }
-  }
-
-  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")),
-    ),
-  };
-});
-
-// node:fs：同步方法 mock（runSpawn 用到的全部），promises 保留真实实现（temp-prompt 用）。
-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(() => []),
-    },
-    // 具名导出与 default 保持一致
-    mkdirSync: vi.fn(),
-    existsSync: vi.fn(() => false),
-    appendFileSync: vi.fn(),
-    writeFileSync: vi.fn(),
-    readdirSync: vi.fn(() => []),
-    // promises 保留真实实现——temp-prompt 已被 mock（见下方 vi.mock），不再触发真实 I/O
-    promises: actual.promises,
-  };
-});
-
-// alive-store：mock writeAliveMarker（runSpawn 写 .alive sidecar）+ removeAliveMarker
-// （finalizeRecord 收尾删 .alive）。其余导出（readAliveMarker/isProcessAlive）保留真实实现
-// （worktree-manager/record-store 用，本组用例不涉及但保留以避免间接报错）。
-vi.mock("../alive-store.ts", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../alive-store.ts")>();
-  return {
-    ...actual,
-    writeAliveMarker: vi.fn(),
-    removeAliveMarker: vi.fn(),
-  };
-});
-
-// finalized-marker mock：避免真实 fs 写 sidecar（测试不关心 finalized 行为）
-vi.mock("../finalized-marker.ts", () => ({
-  writeFinalized: vi.fn(),
-  readFinalized: vi.fn(() => false),
-}));
-
-// manifest-store mock：writeManifest 用真实 fs.promises 写盘，但本文件 fs 同步方法已 mock
-// （目录从不真实创建）→ open/rename/unlink 全 ENOENT → bestEffort 异步 console.debug。
-// 这些延迟 console 通过 worker RPC（onUserConsoleLog）回流，与 vitest teardown 形成 race：
-// "Closing rpc while onUserConsoleLog was pending" → unhandled rejection / exit 1（flaky）。
-// 本组用例测编排逻辑（pool / depth / throttle），不测 manifest 持久化（有 manifest-store.test.ts
-// 独立覆盖）。故 mock 成 no-op，消除 teardown race 的根因——异步 console 输出。
-vi.mock("../manifest-store.ts", () => {
-  class FakeManifestStore {
-    writeManifest = vi.fn(async () => {});
-    readManifest = vi.fn(async () => null);
-    listAllSync = vi.fn(() => []);
-    recoverTmpFiles = vi.fn(async () => []);
-  }
-  return { ManifestStore: FakeManifestStore };
-});
-
-// temp-prompt：mock 掉真实 fs.promises I/O，消除 fake-timers 下的 flaky 竞态
-// （详见 run-spawn-integration.test.ts 同名 mock 的注释）。
-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 {
+  aliveStoreModule,
+  childProcessModule,
+  driveChildToCompletion,
+  finalizedMarkerModule,
+  fsSyncModule,
+  manifestStoreModule,
+  tempPromptModule,
+} from "./helpers/subagent-service-mocks.ts";
+
+vi.mock("node:child_process", () => childProcessModule());
+vi.mock("node:fs", async (importOriginal) => fsSyncModule(await importOriginal<typeof import("node:fs")>()));
+vi.mock("../alive-store.ts", async (importOriginal) => aliveStoreModule(await importOriginal<typeof import("../alive-store.ts")>()));
+vi.mock("../finalized-marker.ts", () => finalizedMarkerModule());
+vi.mock("../manifest-store.ts", () => manifestStoreModule());
+vi.mock("../engine/engines/pi/temp-prompt.ts", () => tempPromptModule());
 
 import { spawn } from "node:child_process";
 
-import { waitForSpawn } from "./helpers/spawn-mock.ts";
+import { waitForSpawn, lastSpawnedChild } from "./helpers/spawn-mock.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
 import { MAX_FORK_DEPTH } from "../session-context-resolver.ts";
@@ -150,63 +52,6 @@ import { SubagentService } from "../subagent-service.ts";
 
 const mockSpawn = vi.mocked(spawn);
 
-/**
- * spawn mock 返回的 fake child 类型。
- * 由于 FakeChild 定义在 vi.mock 工厂内部（作用域隔离），此处用结构子集类型描述，
- * 测试代码通过此类型访问 stdout/stderr/kill 等成员。
- */
-interface FakeChild {
-  pid: number;
-  stdout: PassThrough;
-  stderr: PassThrough;
-  killed: boolean;
-  killSignal: string | undefined;
-  kill(sig?: string): boolean;
-  emit(event: string, ...args: unknown[]): boolean;
-}
-
-/** 从最近一次 spawn 调用取回返回的 FakeChild（测试控制器）。 */
-function lastSpawnedChild(): FakeChild {
-  const result = mockSpawn.mock.results.at(-1);
-  if (!result) throw new Error("spawn was not called yet");
-  return result.value as FakeChild;
-}
-
-// ============================================================
-// 辅助：FakeChild stdout 驱动（替代旧 fakeSession.subscribe 的事件注入）
-// ============================================================
-
-/** 构造 session header 行（stdout 首行，runSpawn 据此回填 record.sessionFile）。 */
-function sessionHeader(id = "nest-session"): Record<string, unknown> {
-  return {
-    type: "session",
-    id,
-    timestamp: "2026-07-03T12-00-00-000Z",
-    cwd: "/tmp/test",
-  };
-}
-
-/** 向 stdout 写一行 JSON（自动补换行，runSpawn 按 \n split 行）。 */
-function emitStdoutLine(child: FakeChild, obj: Record<string, unknown>): void {
-  child.stdout.write(`${JSON.stringify(obj)}\n`);
-}
-
-/**
- * 驱动 FakeChild 完成 session：写 header + 可选事件 + close(0)。
- *
- * 这是「让 runSpawn 自然 resolve」的标准收尾路径。runSpawn 在 close 后判定 success
- * （exitCode=0 → success=true），并跑 identity 补写 + finalizeRecord。
- *
- * @param events  header 之后、close 之前 emit 的 SdkEvent 行（tool/message/turn 等）
- */
-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);
-}
-
 // ============================================================
 // 辅助：service 构造（与旧 setup 等价，但不再装配 fakeSdk）
 // ============================================================
@@ -225,7 +70,7 @@ interface SetupResult {
 
 function setup(): SetupResult {
   const agentDir = "/tmp/nest-it"; // fs 已 mock，路径不需真实存在
-  const modelService = new ModelConfigService({ agentDir });
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
   modelService.initModel({
     modelRegistry: makeEmptyRegistry(),
     sessionId: "nest-it",
@@ -242,7 +87,8 @@ function setup(): SetupResult {
 
 const ctxModel: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: false };
 
-/** execCtxAls.run 的 duck-type（绕过 import AsyncLocalStorage，足够本组用例）。 */
+/** [D3-⑤] execNesting（公共层 ExecutionNestingContext）.run 的 duck-type（绕过
+ * import AsyncLocalStorage，足够本组用例——私字段经 Reflect 取，机制与旧 execCtxAls 同构）。 */
 interface ExecCtxAls {
   run: <T>(store: { recordId: string | undefined; depth: number }, cb: () => T) => T;
 }
@@ -262,12 +108,12 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
     const pool = Reflect.get(service, "pool") as { acquire: ReturnType<typeof vi.fn>; release: ReturnType<typeof vi.fn> };
     const acquireSpy = vi.spyOn(pool, "acquire");
 
-    const execPromise = service.execute({ task: "bg in pool", ctxModel });
+    const execPromise = service.execute({ task: "bg in pool", slug: "test", ctxModel });
     // detached runAndFinalize → acquire。等 spawn 拿到 child 再驱动完成。
     await waitForSpawn(mockSpawn);
-    await driveChildToCompletion(lastSpawnedChild());
+    await driveChildToCompletion(lastSpawnedChild(mockSpawn));
 
-    // 等 detached promise 链跑完（kickOffBackground 的 .then notify）
+    // 等 detached promise 链跑完（kickOffChatRound 的 .then notify）
     await new Promise<void>((r) => setTimeout(r, 10));
 
     expect(acquireSpy).toHaveBeenCalled();
@@ -283,16 +129,16 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
   it("[D-033] execCtxAls depth=MAX 时 execute 抛错（nestingDepth=MAX+1 被拒）", async () => {
     const { service } = setup();
 
-    const execCtxAls = Reflect.get(service, "execCtxAls") as ExecCtxAls;
+    const execNesting = Reflect.get(service, "execNesting") as ExecCtxAls;
 
     await expect(
-      execCtxAls.run({ recordId: "parent", depth: MAX_FORK_DEPTH }, () =>
-        service.execute({ task: "too deep", ctxModel }),
+      execNesting.run({ recordId: "parent", depth: MAX_FORK_DEPTH }, () =>
+        service.execute({ task: "too deep", slug: "test", ctxModel }),
       ),
     ).rejects.toThrow(/nesting depth/);
 
     // 无副作用：guard 在 createRecordForMode 之前，record 未创建
-    expect(service.collectRecords(10)).toHaveLength(0);
+    expect(service.queries.collectRecords(10)).toHaveLength(0);
     // guard 在 spawn 之前——不应 spawn 任何子进程
     expect(mockSpawn).not.toHaveBeenCalled();
   });
@@ -300,13 +146,13 @@ describe("嵌套护栏 / 并发池 / 节流（D-030~D-033 回归锁）", () => {
   it("[D-033] execCtxAls depth=MAX-1 时 execute 不抛（nestingDepth=MAX 允许）", async () => {
     const { service } = setup();
 
-    const execCtxAls = Reflect.get(service, "execCtxAls") as ExecCtxAls;
+    const execNesting = Reflect.get(service, "execNesting") as ExecCtxAls;
 
-    const execPromise = execCtxAls.run({ recordId: "parent", depth: MAX_FORK_DEPTH - 1 }, () =>
-      service.execute({ task: "at limit", ctxModel }),
+    const execPromise = execNesting.run({ recordId: "parent", depth: MAX_FORK_DEPTH - 1 }, () =>
+      service.execute({ task: "at limit", slug: "test", ctxModel }),
     );
     await waitForSpawn(mockSpawn);
-    await driveChildToCompletion(lastSpawnedChild(), [
+    await driveChildToCompletion(lastSpawnedChild(mockSpawn), [
       { type: "turn_end" },
       { type: "message_end", message: { usage: { input: 1 } } },
     ]);