@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/recursive-visibility-baseline.test.ts

@@ -16,102 +16,32 @@
 //   4. forkDepth 基线：env PI_SUBAGENT_FORK_DEPTH → fork spawn env 递增
 //
 // mock 策略与 execute-nesting.test.ts 一致（spawn → FakeChild，fs 同步方法 mock，
-// temp-prompt / alive-store / finalized-marker / manifest-store mock）。
-
-import type { PassThrough } from "node:stream";
+// temp-prompt / alive-store / finalized-marker / manifest-store mock；已收敛
+// ./helpers/subagent-service-mocks.ts 四文件共享单源）。
 
 import { afterEach, beforeEach, 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 用 execFile 异步取 git branch：默认 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")),
-    ),
-  };
-});
+import {
+  aliveStoreModule,
+  childProcessModule,
+  finalizedMarkerModule,
+  fsSyncModule,
+  manifestStoreModule,
+  tempPromptModule,
+} from "./helpers/subagent-service-mocks.ts";
 
-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 () => []);
-  }
-  // vi.fn 包裹：构造参数（recordsDir）可从 mock.calls 断言（[MF-3] 目录统一验证）。
-  // 注意用普通 function（箭头函数不能被 new 调用）。
-  return { ManifestStore: vi.fn(function (_recordsDir: string) { return new FakeManifestStore(); }) };
-});
+// ── mock modules（同 execute-nesting.test.ts）──
 
-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 () => {}),
-}));
+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 { ManifestStore } from "../manifest-store.ts";
@@ -128,43 +58,10 @@ const ENV_DEPTH = "PI_SUBAGENT_DEPTH";
 const ENV_ROOT_CWD = "PI_SUBAGENT_ROOT_CWD";
 const ENV_FORK_DEPTH = "PI_SUBAGENT_FORK_DEPTH";
 
-interface FakeChild {
-  pid: number;
-  stdout: PassThrough;
-  stderr: PassThrough;
-  killed: boolean;
-  killSignal: string | undefined;
-  kill(sig?: string): boolean;
-  emit(event: string, ...args: unknown[]): boolean;
-}
-
-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;
-}
-
 function getLastSpawnEnv(): Record<string, string | undefined> {
   return (mockSpawn.mock.calls.at(-1)?.[2]?.env as Record<string, string | undefined>) ?? {};
 }
 
-function sessionHeader(id = "baseline-session"): Record<string, unknown> {
-  return { type: "session", id, timestamp: "2026-08-11T00-00-00-000Z", cwd: "/tmp/test" };
-}
-
-function emitStdoutLine(child: FakeChild, obj: Record<string, unknown>): void {
-  child.stdout.write(`${JSON.stringify(obj)}\n`);
-}
-
-/** 驱动 FakeChild 完成：header + 可选事件 + close(0)（runSpawn 自然 resolve）。 */
-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 构造 ──
 
 function makeEmptyRegistry(): ModelRegistryLike {
@@ -177,7 +74,7 @@ function makePi() {
 
 function setup(env: Record<string, string>): { service: SubagentService; store: RecordStore } {
   const agentDir = "/tmp/baseline-it";
-  const modelService = new ModelConfigService({ agentDir });
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
   modelService.initModel({
     modelRegistry: makeEmptyRegistry(),
     sessionId: "baseline-it",
@@ -227,7 +124,7 @@ describe("进程级基线兜底（ALS 断裂修复，pi 事件回调模型）",
     const { service, store } = setup({});
 
     // 不在 execCtxAls.run 内调用（模拟 ALS 断裂：事件回调上下文读不到 store）
-    const handle = await service.execute({ task: "child of parent", ctxModel });
+    const handle = await service.execute({ task: "child of parent", slug: "test", ctxModel });
 
     const rec = store.collectRecords(10, "all", "root-main").find((r) => r.id === handle.subagentId);
     expect(rec).toBeDefined();
@@ -239,7 +136,7 @@ describe("进程级基线兜底（ALS 断裂修复，pi 事件回调模型）",
     // 旧实现传 this.sessionId（子进程自己的 session id ≠ ROOT）→ 子进程内列表恒空。
     // 子进程的本进程 sessionId 是 "baseline-it"（initSession 注入），而 record 归属
     // root-main（env 贯穿的真 ROOT）——能查到即证明过滤用的是 sessionRootId。
-    const viaService = service.collectRecords(10);
+    const viaService = service.queries.collectRecords(10);
     expect(viaService.map((r) => r.id)).toContain(handle.subagentId);
     expect(viaService[0]!.rootSessionId).toBe("root-main");
   });
@@ -247,7 +144,7 @@ describe("进程级基线兜底（ALS 断裂修复，pi 事件回调模型）",
   it("[顶层] 无 env（根进程）：parentRecordId undefined / depth 0", async () => {
     const { service, store } = setup({});
 
-    const handle = await service.execute({ task: "top level", ctxModel });
+    const handle = await service.execute({ task: "top level", slug: "test", ctxModel });
 
     const rec = store.collectRecords(10, "all", "baseline-it").find((r) => r.id === handle.subagentId);
     expect(rec).toBeDefined();
@@ -261,10 +158,10 @@ describe("进程级基线兜底（ALS 断裂修复，pi 事件回调模型）",
     process.env[ENV_DEPTH] = "0";
 
     const { service, store } = setup({});
-    const execCtxAls = Reflect.get(service, "execCtxAls") as ExecCtxAls;
+    const execNesting = Reflect.get(service, "execNesting") as ExecCtxAls;
 
-    const handle = await execCtxAls.run({ recordId: "sa-inline-parent", depth: 3 }, () =>
-      service.execute({ task: "inline nested", ctxModel }),
+    const handle = await execNesting.run({ recordId: "sa-inline-parent", depth: 3 }, () =>
+      service.execute({ task: "inline nested", slug: "test", ctxModel }),
     );
 
     const rec = store.collectRecords(10, "all", "root-main").find((r) => r.id === handle.subagentId);
@@ -281,14 +178,14 @@ describe("进程级基线兜底（ALS 断裂修复，pi 事件回调模型）",
 
     const { service } = setup({});
 
-    const execPromise = service.execute({ task: "fork child", ctxModel, fork: true });
+    const execPromise = service.execute({ task: "fork child", slug: "test", ctxModel, fork: true });
     await waitForSpawn(mockSpawn);
     const childEnv = getLastSpawnEnv();
 
     // 742 行 parentDepth = forkDepthAls.getStore() ?? forkDepthBaseline —— ALS 断裂时基线=1，+1 → 2
     expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBe("2");
 
-    const child = lastSpawnedChild();
+    const child = lastSpawnedChild(mockSpawn);
     child.emit("close", 0);
     await execPromise;
   });
@@ -303,7 +200,7 @@ describe("进程级基线兜底（ALS 断裂修复，pi 事件回调模型）",
     // MAX_FORK_DEPTH 至少 > 5 才不会被误拒；这里验证基线参与计数的方式是
     // 用直接深度断言——execute 不抛错说明 nestingDepth=6 未超限，护栏不误伤。
     // （MAX_FORK_DEPTH 具体值由 session-context-resolver 定义，这里不硬编码。）
-    await expect(service.execute({ task: "deep but allowed", ctxModel })).resolves.toBeDefined();
+    await expect(service.execute({ task: "deep but allowed", slug: "test", ctxModel })).resolves.toBeDefined();
   });
 
   it("[MF-3 回归] 有 ENV_ROOT_CWD（worktree 子进程）：sessions 与 records 两套目录统一编码在 ROOT cwd 段", () => {
@@ -314,7 +211,7 @@ describe("进程级基线兜底（ALS 断裂修复，pi 事件回调模型）",
 
     const agentDir = "/tmp/baseline-it";
     const checkoutPath = "/var/folders/worktree/pi-subagents/--root-project--/branch";
-    const modelService = new ModelConfigService({ agentDir });
+    const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
     modelService.initModel({
       modelRegistry: makeEmptyRegistry(),
       sessionId: "baseline-it",

package/src/execution/__tests__/recursive-visibility-env.test.ts

@@ -7,150 +7,46 @@
 //
 // 这是场景 1（端到端三层嵌套全树可见）的「env 传递机制」确定性验证——不依赖 LLM 配合，
 // mock spawn 拦截 childEnv 直接断言。端到端可见性由场景 1（真实 pi CLI + recursive-worker agent）覆盖。
-
-import type { PassThrough } from "node:stream";
+//
+// mock 块与 fixture 收敛 __tests__/helpers/spawn-mock.ts（vi.mock 工厂 await import 转发，
+// 单源共享）；vi.mocked 取回与收尾装配来自 helpers/session-runner-mocks.ts。
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { getSubagentSessionDir } from "../path-encoding.ts";
 
-// ── mock modules（同 session-runner-schema-env.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();
-    stdin = new PassThrough(); // runSpawn 注册 stdin EPIPE handler（session-runner），FakeChild 必须提供
-    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 用 execFile 异步取 git branch：默认 err-first 兜底（catch → branch=""），
-    // 形态同 worktree-manager.test.ts 的 setupExecFile
-    execFile: vi.fn(
-      (
-        _cmd: string,
-        _args: readonly string[],
-        _opts: unknown,
-        cb: (err: Error | null, stdout?: string, stderr?: string) => void,
-      ) => cb(new Error("execFile not configured in this test")),
-    ),
-  };
-});
-
-vi.mock("node:fs", async () => {
-  const actual = await import("node:fs");
-  return {
-    default: {
-      ...actual,
-      mkdirSync: vi.fn(),
-      existsSync: vi.fn(() => false),
-      appendFileSync: vi.fn(),
-      writeFileSync: vi.fn(),
-      readdirSync: vi.fn(() => []),
-    },
-    mkdirSync: vi.fn(),
-    existsSync: vi.fn(() => false),
-    appendFileSync: vi.fn(),
-    writeFileSync: vi.fn(),
-    readdirSync: vi.fn(() => []),
-    promises: actual.promises,
-  };
-});
-
-vi.mock("../alive-store.ts", () => ({
-  writeAliveMarker: vi.fn(),
-}));
-
-vi.mock("../temp-prompt.ts", () => ({
-  writePromptToTempFile: vi.fn(async (agent: string) => {
-    const safeName = agent.replace(/[^\w.-]+/g, "_");
-    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
-  }),
-  cleanupTempPrompt: vi.fn(async () => {}),
-}));
-
-import { spawn } from "node:child_process";
-import * as fs from "node:fs";
-
-import { waitForSpawn } from "./helpers/spawn-mock.ts";
-import { createRecord } from "../execution-record.ts";
-import { type RunOptions, runSpawn, type SessionRunnerContext } from "../session-runner.ts";
-
-const mockSpawn = vi.mocked(spawn);
-const mockExistsSync = vi.mocked(fs.existsSync);
-
-interface FakeChild {
-  pid: number;
-  stdout: PassThrough;
-  stderr: PassThrough;
-  killed: boolean;
-  killSignal: string | undefined;
-  kill(sig?: string): boolean;
-  emit(event: string, ...args: unknown[]): boolean;
-}
-
-function getLastSpawnedChild(): FakeChild {
-  const result = mockSpawn.mock.results.at(-1);
-  if (!result) throw new Error("spawn was not called yet");
-  return result.value as FakeChild;
-}
-
-function getLastSpawnEnv(): Record<string, string | undefined> {
-  return (mockSpawn.mock.calls.at(-1)?.[2]?.env as Record<string, string | undefined>) ?? {};
-}
-
-// ── fixture ──
-
-function makeRecord(overrides: { id?: string; depth?: number } = {}) {
-  return createRecord(overrides.id ?? "sa-test-record", {
-    agent: "general-purpose",
-    model: "test/model",
-    mode: "background",
-    task: "test task",
-    startedAt: Date.now(),
-    rootSessionId: "should-be-overridden-by-sessionRootId-source",
-    parentRecordId: undefined,
-    depth: overrides.depth ?? 0,
-  });
-}
-
-function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
-  return {
-    resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
-    agentConfig: undefined,
-    appendSystemPrompt: undefined,
-    skillPath: undefined,
-    schema: undefined,
-    maxTurns: undefined,
-    graceTurns: undefined,
-    signal: undefined,
-    onEvent: undefined,
-    ...overrides,
-  };
-}
-
-function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
-  return {
-    cwd: "/fake/cwd",
-    agentDir: "/fake/agent",
-    skillDirs: [],
-    mainCwd: "/fake/cwd",
-    sessionRootId: "root-main-session",
-    rootCwd: "/fake/cwd",
-    ...overrides,
-  };
+// ── mock modules（同 session-runner-schema-env.test.ts 模式，工厂单源在 spawn-mock.ts）──
+
+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());
+vi.mock("../engine/engines/pi/temp-prompt.ts", async () =>
+  (await import("./helpers/spawn-mock.ts")).tempPromptModule());
+
+import { runSpawn } from "../engine/engines/pi/session-runner.ts";
+import {
+  getLastSpawnEnv,
+  makeRunOpts,
+  makeVisibilityCtx,
+  makeVisibilityRecord,
+  waitForSpawn,
+} from "./helpers/spawn-mock.ts";
+import { closeLastChildAndAwait, takeSessionRunnerMocks } from "./helpers/session-runner-mocks.ts";
+
+const { mockSpawn, mockExistsSync } = takeSessionRunnerMocks();
+
+/** runSpawn 前奏装配：启动、等 spawn 落位、取回 childEnv（断言留在各用例）。 */
+async function spawnAndCaptureEnv(
+  record: ReturnType<typeof makeVisibilityRecord>,
+  task: string,
+  opts: ReturnType<typeof makeRunOpts>,
+  ctx: ReturnType<typeof makeVisibilityCtx>,
+): Promise<{ resultPromise: Promise<unknown>; childEnv: Record<string, string | undefined> }> {
+  const resultPromise = runSpawn(record, task, opts, ctx);
+  await waitForSpawn(mockSpawn);
+  return { resultPromise, childEnv: getLastSpawnEnv(mockSpawn) };
 }
 
 // ── runSpawn childEnv 身份 env 注入（场景 1b）──
@@ -166,13 +62,11 @@ describe("runSpawn 跨进程身份 env 注入（递归可见性场景 1b）", ()
   });
 
   it("非 fork（fork=false/undefined）：无条件注入 4 个身份 env（决策 2）", async () => {
-    const record = makeRecord({ id: "sa-aaa", depth: 0 });
-    const ctx = makeCtx({ sessionRootId: "root-main" });
+    const record = makeVisibilityRecord({ id: "sa-aaa", depth: 0 });
+    const ctx = makeVisibilityCtx({ sessionRootId: "root-main" });
     const opts = makeRunOpts({ fork: false });
 
-    const resultPromise = runSpawn(record, "test task", opts, ctx);
-    await waitForSpawn(mockSpawn);
-    const childEnv = getLastSpawnEnv();
+    const { resultPromise, childEnv } = await spawnAndCaptureEnv(record, "test task", opts, ctx);
 
     expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-main");
     expect(childEnv.PI_SUBAGENT_SELF_RECORD_ID).toBe("sa-aaa");
@@ -182,19 +76,15 @@ describe("runSpawn 跨进程身份 env 注入（递归可见性场景 1b）", ()
     // fork=false 不注入 fork depth env（与既有行为一致，本测试不改变它）
     expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBeUndefined();
 
-    const child = getLastSpawnedChild();
-    child.emit("close", 0);
-    await resultPromise;
+    await closeLastChildAndAwait(resultPromise);
   });
 
   it("fork=true：4 个身份 env 与 fork depth env 共存（决策 2 无条件注入不依赖 fork）", async () => {
-    const record = makeRecord({ id: "sa-bbb", depth: 2 });
-    const ctx = makeCtx({ sessionRootId: "root-main" });
+    const record = makeVisibilityRecord({ id: "sa-bbb", depth: 2 });
+    const ctx = makeVisibilityCtx({ sessionRootId: "root-main" });
     const opts = makeRunOpts({ fork: true, parentForkDepth: 1 });
 
-    const resultPromise = runSpawn(record, "test task", opts, ctx);
-    await waitForSpawn(mockSpawn);
-    const childEnv = getLastSpawnEnv();
+    const { resultPromise, childEnv } = await spawnAndCaptureEnv(record, "test task", opts, ctx);
 
     // 身份 env 无条件存在（决策 2）
     expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-main");
@@ -204,46 +94,36 @@ describe("runSpawn 跨进程身份 env 注入（递归可见性场景 1b）", ()
     // fork depth env 同时存在（fork=true + parentForkDepth=1 → 2）
     expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBe("2");
 
-    const child = getLastSpawnedChild();
-    child.emit("close", 0);
-    await resultPromise;
+    await closeLastChildAndAwait(resultPromise);
   });
 
   it("深层 record（depth=3）：DEPTH env = String(record.depth)，正确贯穿嵌套层级", async () => {
-    const record = makeRecord({ id: "sa-deep", depth: 3 });
-    const ctx = makeCtx({ sessionRootId: "root-topmost" });
+    const record = makeVisibilityRecord({ id: "sa-deep", depth: 3 });
+    const ctx = makeVisibilityCtx({ sessionRootId: "root-topmost" });
 
-    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
-    await waitForSpawn(mockSpawn);
-    const childEnv = getLastSpawnEnv();
+    const { resultPromise, childEnv } = await spawnAndCaptureEnv(record, "test task", makeRunOpts(), ctx);
 
     expect(childEnv.PI_SUBAGENT_DEPTH).toBe("3");
     expect(childEnv.PI_SUBAGENT_SELF_RECORD_ID).toBe("sa-deep");
     expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-topmost");
 
-    const child = getLastSpawnedChild();
-    child.emit("close", 0);
-    await resultPromise;
+    await closeLastChildAndAwait(resultPromise);
   });
 
   it("ROOT_SESSION_ID 恒等于 ctx.sessionRootId（贯穿真 ROOT，非 record.rootSessionId）", async () => {
     // record.rootSessionId 是 createRecord 时写入的值（可能来自旧逻辑），但 env 注入用的是
     // ctx.sessionRootId（经 buildSessionRunnerContext 从 this.sessionRootId 透传，贯穿真 ROOT）。
     // 这保证深层 subagent 的子进程仍归顶层 ROOT（设计决策 1/3）。
-    const record = makeRecord({ id: "sa-ccc" }); // record.rootSessionId = fixture 默认值
-    const ctx = makeCtx({ sessionRootId: "real-root-session" });
+    const record = makeVisibilityRecord({ id: "sa-ccc" }); // record.rootSessionId = fixture 默认值
+    const ctx = makeVisibilityCtx({ sessionRootId: "real-root-session" });
 
-    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
-    await waitForSpawn(mockSpawn);
-    const childEnv = getLastSpawnEnv();
+    const { resultPromise, childEnv } = await spawnAndCaptureEnv(record, "test task", makeRunOpts(), ctx);
 
     // env 用 ctx.sessionRootId，不是 record.rootSessionId
     expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("real-root-session");
     expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).not.toBe(record.rootSessionId);
 
-    const child = getLastSpawnedChild();
-    child.emit("close", 0);
-    await resultPromise;
+    await closeLastChildAndAwait(resultPromise);
   });
 
   it("[MF-3 回归] worktree 模式（mainCwd=checkout ≠ rootCwd）：sessionDir 用 ROOT cwd 编码，深层 record 落盘到 ROOT 可扫描段", async () => {
@@ -252,12 +132,10 @@ describe("runSpawn 跨进程身份 env 注入（递归可见性场景 1b）", ()
     const rootCwd = "/root/project";
     const checkoutPath = "/var/folders/worktree/pi-subagents/--root-project--/branch";
     const agentDir = "/fake/agent";
-    const record = makeRecord({ id: "sa-deep", depth: 2 });
-    const ctx = makeCtx({ cwd: checkoutPath, mainCwd: checkoutPath, rootCwd, agentDir });
+    const record = makeVisibilityRecord({ id: "sa-deep", depth: 2 });
+    const ctx = makeVisibilityCtx({ cwd: checkoutPath, mainCwd: checkoutPath, rootCwd, agentDir });
 
-    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
-    await waitForSpawn(mockSpawn);
-    const childEnv = getLastSpawnEnv();
+    const { resultPromise, childEnv } = await spawnAndCaptureEnv(record, "test task", makeRunOpts(), ctx);
     const spawnArgs = mockSpawn.mock.calls.at(-1)?.[1] as string[];
 
     // 第 4 个 env 贯穿 ROOT cwd
@@ -266,8 +144,6 @@ describe("runSpawn 跨进程身份 env 注入（递归可见性场景 1b）", ()
     expect(spawnArgs).toContain(getSubagentSessionDir(agentDir, rootCwd));
     expect(spawnArgs).not.toContain(getSubagentSessionDir(agentDir, checkoutPath));
 
-    const child = getLastSpawnedChild();
-    child.emit("close", 0);
-    await resultPromise;
+    await closeLastChildAndAwait(resultPromise);
   });
 });

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

@@ -6,8 +6,8 @@
 
 import { describe, expect, it } from "vitest";
 
-import { buildSpawnArgs } from "../session-runner.ts";
-import { parseSpawnLine } from "../spawn-event-adapter.ts";
+import { buildSpawnArgs } from "../engine/engines/pi/session-runner.ts";
+import { parseSpawnLine } from "../engine/engines/pi/spawn-event-adapter.ts";
 
 describe("buildSpawnArgs - RPC mode", () => {
   const baseParams = {