@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/gc-timer.test.ts

@@ -26,14 +26,25 @@ vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
 // mock session-runner：runSpawn/killAllSpawnedChildren 占位（import 链需要），
 // getChildByRecord 默认返回 undefined（无活进程 → isResumable=true），用例内按需覆盖。
-vi.mock("../session-runner.ts", () => ({
+vi.mock("../engine/engines/pi/session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  killRecordChildWithEscalation: vi.fn(),
   spawnedChildren: new Map(),
 }));
 
-import { getChildByRecord } from "../session-runner.ts";
+// [D8] idle-gc 归档时释放引擎池引用（releasePoolRef 经 getEngineDataDir 解析
+// dataDir）——测试钉到模块级 holder（vi.mock factory 闭包只能引用模块级变量），
+// beforeEach 刷新为当前 tmp agentDir，防触碰真实数据目录。
+let gcDataDirHolder = "";
+vi.mock("../engine/common/data-dir.ts", () => ({
+  getEngineDataDir: () => gcDataDirHolder,
+}));
+
+import { acquirePool } from "../engine/common/pool-manager.ts";
+import { getChildByRecord } from "../engine/engines/pi/session-runner.ts";
 import { createRecord } from "../execution-record.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import { RecordStore } from "../record-store.ts";
@@ -95,6 +106,7 @@ describe("[M8] idle record GC 定时器（startGcTimer）", () => {
   beforeEach(() => {
     vi.useFakeTimers();
     agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "gc-timer-"));
+    gcDataDirHolder = agentDir;
     const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
     service = new SubagentService({ cwd: agentDir, modelService });
     service.initSession({ pi: makePi(), sessionId: "root-session" });
@@ -181,4 +193,47 @@ describe("[M8] idle record GC 定时器（startGcTimer）", () => {
 
     expect(store.getMutable("sa-after-dispose")).toBeDefined();
   });
+
+  it("[D8] 归档超 TTL record 时释放引擎池引用：journal 跟随删除、refs 移除、归零删池原生状态", () => {
+    // 建池（engine 缺省投影 'pi' + poolKey 'shared'——与 runEngineTask 回填形态一致）
+    const poolDir = acquirePool(agentDir, "pi", "shared", "sa-pool-1");
+    fs.mkdirSync(path.join(poolDir, "native-state"), { recursive: true });
+    fs.writeFileSync(path.join(poolDir, "native-state", "db.sqlite"), "x");
+    fs.writeFileSync(path.join(poolDir, "journal-sa-pool-1.jsonl"), "{}\n");
+    fs.writeFileSync(path.join(poolDir, "journal-sa-pool-2.jsonl"), "{}\n"); // 他人 journal（refs 无条目）
+
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    const record = makeIdleRecord("sa-pool-1", fireAt - IDLE_TTL_MS - 1);
+    record.engineHandle = { sessionRef: {}, poolKey: "shared" };
+    store.register(record);
+
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+
+    expect(store.getMutable("sa-pool-1")).toBeUndefined(); // 已归档
+    // release 语义：自己的 journal 删、他人 journal 保留、归零删原生状态、目录保留（剩 journal）
+    expect(fs.existsSync(path.join(poolDir, "journal-sa-pool-1.jsonl"))).toBe(false);
+    expect(fs.existsSync(path.join(poolDir, "journal-sa-pool-2.jsonl"))).toBe(true);
+    expect(fs.existsSync(path.join(poolDir, "native-state"))).toBe(false);
+    expect(fs.existsSync(poolDir)).toBe(true);
+    // refs 归零后随池清理（无残留幻影引用）
+    const refsPath = path.join(poolDir, "refs.json");
+    if (fs.existsSync(refsPath)) {
+      expect(Object.keys((JSON.parse(fs.readFileSync(refsPath, "utf8")) as { refs: object }).refs)).toEqual([]);
+    }
+  });
+
+  it("[D8] 无 engineHandle 的 record 归档不触碰引擎池（存量 record 零影响）", () => {
+    const poolDir = acquirePool(agentDir, "pi", "shared", "sa-plain");
+    fs.writeFileSync(path.join(poolDir, "journal-sa-plain.jsonl"), "{}\n");
+
+    const fireAt = Date.now() + GC_INTERVAL_MS;
+    store.register(makeIdleRecord("sa-plain", fireAt - IDLE_TTL_MS - 1)); // 无 engineHandle
+
+    service.startGcTimer();
+    vi.advanceTimersByTime(GC_INTERVAL_MS);
+
+    expect(store.getMutable("sa-plain")).toBeUndefined(); // 正常归档
+    expect(fs.existsSync(path.join(poolDir, "journal-sa-plain.jsonl"))).toBe(true); // 池/journal 不动
+  });
 });

package/src/execution/__tests__/get-record-for-action-restart.test.ts

@@ -27,10 +27,12 @@ vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
 // mock session-runner：import 链需要（getRecordForAction 本身不调 spawn，仅守卫读
 // hasLiveProcessHandle——默认无活进程，与跨重启场景一致）。
-vi.mock("../session-runner.ts", () => ({
+vi.mock("../engine/engines/pi/session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  killRecordChildWithEscalation: vi.fn(),
   spawnedChildren: new Map(),
 }));
 
@@ -167,7 +169,7 @@ describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）",
     const file = writeSessionJsonl(sessionsDir, { id: "sa-restart-1", rootSessionId: "root-session" });
     expect(store.getMutable("sa-restart-1")).toBeUndefined(); // 前置：内存确无
 
-    const record = service.getRecordForAction("sa-restart-1");
+    const record = service.chatActions.getRecordForAction("sa-restart-1");
 
     // [v4 A-3] 无条件 chatMode=true（跨重启恢复入口）
     expect(record.chatMode).toBe(true);
@@ -184,7 +186,7 @@ describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）",
     expect(record.status).toBe("running");
     // register 生效：进内存，二次调用走内存命中（同一引用）
     expect(store.getMutable("sa-restart-1")).toBe(record);
-    expect(service.getRecordForAction("sa-restart-1")).toBe(record);
+    expect(service.chatActions.getRecordForAction("sa-restart-1")).toBe(record);
   });
 
   it("rootSessionId 校验仍生效：异树 record（other-session）→ throw not found or not owned", () => {
@@ -192,7 +194,7 @@ describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）",
     // 但后置校验 record.rootSessionId !== this.sessionRootId 必须拦截
     writeSessionJsonl(sessionsDir, { id: "sa-foreign", rootSessionId: "other-session" });
 
-    expect(() => service.getRecordForAction("sa-foreign")).toThrow(/not found or not owned/);
+    expect(() => service.chatActions.getRecordForAction("sa-foreign")).toThrow(/not found or not owned/);
   });
 
   it("直接父校验仍生效：孙级 record（parentRecordId=sa-parent）→ 主进程 throw direct parent", () => {
@@ -204,14 +206,14 @@ describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）",
     });
 
     // 重建后 parentRecordId=sa-parent ≠ 主进程 baseline(undefined) → cross-layer 守卫拦截
-    expect(() => service.getRecordForAction("sa-grand")).toThrow(/direct parent/);
+    expect(() => service.chatActions.getRecordForAction("sa-grand")).toThrow(/direct parent/);
   });
 
   it(".finalized sidecar（closed 终态）不重建 → throw not found or not owned", () => {
     const file = writeSessionJsonl(sessionsDir, { id: "sa-fin", rootSessionId: "root-session" });
     writeFinalized(file); // sidecar 矩阵分支 2 → status=closed → find(status==="running") miss
 
-    expect(() => service.getRecordForAction("sa-fin")).toThrow(/not found or not owned/);
+    expect(() => service.chatActions.getRecordForAction("sa-fin")).toThrow(/not found or not owned/);
     expect(store.getMutable("sa-fin")).toBeUndefined(); // 未重建注册
   });
 
@@ -228,14 +230,14 @@ describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）",
       worktree: true,
     });
 
-    const record = service.getRecordForAction("sa-wt");
+    const record = service.chatActions.getRecordForAction("sa-wt");
     // hadWorktree 从磁盘 identity entry 的 worktree 标志恢复
     expect(record.hadWorktree).toBe(true);
     // handle 无法恢复（不可序列化）
     expect(record.worktreeHandle).toBeUndefined();
 
-    // 冷路径续聊（无活进程）→ resumeRound 守卫拒绝，不 spawn 回落主 repo
-    await expect(service.deliverMessage(record, "resume after restart", false)).rejects.toThrow(
+    // 冷路径续聊（无活进程）→ 续轮守卫拒绝，不 spawn 回落主 repo
+    await expect(service.chatActions.deliverChatMessage(record, "resume after restart", false)).rejects.toThrow(
       /worktree isolation.*lost when the parent process restarted/,
     );
   });
@@ -244,11 +246,11 @@ describe("[M10] getRecordForAction 跨重启磁盘重建（S3 回归场景）",
     // identity entry 无 worktree 字段（旧文件）→ found.worktree undefined → hadWorktree false
     writeSessionJsonl(sessionsDir, { id: "sa-nowt", rootSessionId: "root-session" });
 
-    const record = service.getRecordForAction("sa-nowt");
+    const record = service.chatActions.getRecordForAction("sa-nowt");
     expect(record.hadWorktree).toBe(false);
 
-    // deliverMessage 冷路径不被 worktree 守卫拦截（resume 正常发起；后续 spawn 编排
+    // 冷路径续聊不被 worktree 守卫拦截（resume 正常发起；后续 spawn 编排
     // 超出本用例关注点——runSpawn 在本文件是 no-op mock）
-    await expect(service.deliverMessage(record, "resume normal", false)).resolves.toBeUndefined();
+    await expect(service.chatActions.deliverChatMessage(record, "resume normal", false)).resolves.toBeUndefined();
   });
 });

package/src/execution/__tests__/get-state-handshake.test.ts

@@ -0,0 +1,127 @@
+// src/execution/__tests__/get-state-handshake.test.ts
+//
+// [T1/RC-1] requestGetStateOnce 单测：agent_end 决策点惰性回补用的单次 get_state 请求辅助。
+//
+// 契约锚点（与 performGetStateHandshake 共用消息构造 sendGetStateCommand + 字段提取
+// extractGetStateFields，但不做重试循环）：
+//   1. response 到达 → resolve 提取后的 GetStateResult（无条件 finish，单次语义无重试）；
+//   2. 超时 → resolve 空对象（调用方走保守分支）；
+//   3. stdin 同步写失败（EPIPE 形态）→ resolve 空对象、永不 reject（fire-and-forget 契约）；
+//   4. 自清理：finish 后从监听表注销本请求 resolver（消费注册器返回的注销函数）；
+//      注册器不返回注销函数时退化为 no-op（与握手同形态）。
+//
+// performGetStateHandshake 既有行为由 run-spawn-rpc-mode.test.ts 集成覆盖，此处不重复。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { requestGetStateOnce } from "../engine/engines/pi/get-state-handshake.ts";
+import type { ChildProcess } from "node:child_process";
+
+/** 最小 FakeChild：只需 stdin.write 行为（成功 / 可注入同步 throw）。 */
+function makeFakeStdin(behavior?: { throwOnWrite?: Error }): { child: ChildProcess; writes: string[] } {
+  const writes: string[] = [];
+  const child = {
+    stdin: {
+      write(line: string): boolean {
+        if (behavior?.throwOnWrite) throw behavior.throwOnWrite;
+        writes.push(line);
+        return true;
+      },
+    },
+  } as unknown as ChildProcess;
+  return { child, writes };
+}
+
+/** 可控的监听表：模拟 stdout pump 的 get_stateListeners（注册返回注销函数）。 */
+function makeListenerRegistry() {
+  const resolvers = new Map<string, (data: unknown) => void>();
+  const removed: string[] = [];
+  const add = (id: string, resolver: (data: unknown) => void) => {
+    resolvers.set(id, resolver);
+    return () => {
+      if (resolvers.get(id) === resolver) resolvers.delete(id);
+      removed.push(id);
+    };
+  };
+  return { resolvers, removed, add };
+}
+
+describe("requestGetStateOnce（[T1/RC-1] 惰性回补单次请求）", () => {
+  it("response 到达 → resolve 提取的 sessionFile/sessionId，并从监听表注销", async () => {
+    const { child, writes } = makeFakeStdin();
+    const reg = makeListenerRegistry();
+
+    const promise = requestGetStateOnce(child, reg.add, 1000);
+    // 消息构造：单行 JSON {id, type:"get_state"}（与 performGetStateHandshake 同一 sendGetStateCommand）
+    expect(writes).toHaveLength(1);
+    const sent = JSON.parse(writes[0]!) as { id: string; type: string };
+    expect(sent.type).toBe("get_state");
+    expect(reg.resolvers.has(sent.id)).toBe(true);
+
+    // response 到达（含空串 sessionFile 应被过滤的字段形态覆盖提取规则）
+    reg.resolvers.get(sent.id)?.({
+      sessionFile: "/tmp/sessions/abc.jsonl",
+      sessionId: "sess-1",
+    });
+
+    await expect(promise).resolves.toEqual({
+      sessionFile: "/tmp/sessions/abc.jsonl",
+      sessionId: "sess-1",
+    });
+    // 自清理：finish 后从监听表移除本请求 resolver
+    expect(reg.resolvers.has(sent.id)).toBe(false);
+    expect(reg.removed).toEqual([sent.id]);
+  });
+
+  it("response 只含部分字段（仅 sessionId）→ resolve 已提取部分（单次语义：到达即 finish，不等重试）", async () => {
+    const { child } = makeFakeStdin();
+    const reg = makeListenerRegistry();
+
+    const promise = requestGetStateOnce(child, reg.add, 1000);
+    const id = reg.resolvers.keys().next().value as string;
+    reg.resolvers.get(id)?.({ sessionId: "only-id" });
+
+    await expect(promise).resolves.toEqual({ sessionId: "only-id" });
+  });
+
+  it("超时无 response → resolve 空对象（不 reject，不调注销前的 resolver）", async () => {
+    vi.useFakeTimers();
+    try {
+      const { child } = makeFakeStdin();
+      const reg = makeListenerRegistry();
+
+      const promise = requestGetStateOnce(child, reg.add, 1000);
+      await vi.advanceTimersByTimeAsync(1000);
+
+      await expect(promise).resolves.toEqual({});
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("stdin 同步写失败（EPIPE code，writeStdinLine rethrow 路径）→ 立即 resolve 空对象、永不 reject", async () => {
+    // writeStdinLine 只对 code 为 EPIPE / ERR_STREAM_DESTROYED 的错误 rethrow（[R3]），
+    // requestGetStateOnce 的 catch 捕获后按「回补失败」resolve 空对象（同超时语义）。
+    const epipeErr = Object.assign(new Error("write after end"), { code: "EPIPE" });
+    const { child } = makeFakeStdin({ throwOnWrite: epipeErr });
+    const reg = makeListenerRegistry();
+
+    await expect(requestGetStateOnce(child, reg.add, 1000)).resolves.toEqual({});
+    // 写失败路径不注册监听（未发出请求）
+    expect(reg.resolvers.size).toBe(0);
+  });
+
+  it("注册器不返回注销函数（void 形态，对齐旧握手调用方）→ 正常 resolve 不抛", async () => {
+    const { child } = makeFakeStdin();
+    const resolvers = new Map<string, (data: unknown) => void>();
+    const addVoid = (id: string, resolver: (data: unknown) => void): void => {
+      resolvers.set(id, resolver);
+    };
+
+    const promise = requestGetStateOnce(child, addVoid, 1000);
+    const id = resolvers.keys().next().value as string;
+    resolvers.get(id)?.({ sessionFile: "/tmp/x.jsonl" });
+
+    await expect(promise).resolves.toEqual({ sessionFile: "/tmp/x.jsonl" });
+  });
+});

package/src/execution/__tests__/helpers/mock-extension-api.ts

@@ -21,7 +21,7 @@ export function mockExtensionApi(
   const noop = (): void => { /* test mock: method not invoked by this test */ };
   // Proxy<T> 泛型参数决定返回类型——直接声明为 ExtensionAPI，
   // TS 接受（Proxy handler 对 target 的类型不约束 T）。
-  return new Proxy<ExtensionAPI>(overrides as ExtensionAPI, {
+  return new Proxy<ExtensionAPI>(overrides as unknown as ExtensionAPI, {
     get(target, prop: string | symbol): unknown {
       if (prop in target) return target[prop as keyof ExtensionAPI];
       return noop;

package/src/execution/__tests__/helpers/session-runner-mocks.ts

@@ -0,0 +1,113 @@
+// src/execution/__tests__/helpers/session-runner-mocks.ts
+//
+// session-runner 系测试（keep-alive-no-progress / recursive-visibility-env 等）的
+// 测试文件侧装配：vi.mocked 取回 + spawn/keep-alive 前奏 + 子进程收尾。
+//
+// 与 spawn-mock.ts 的分工（依赖约束，勿混淆）：
+//   - spawn-mock.ts 会被各 vi.mock 工厂 `await import()`（求值时机 = 被 mock 模块首次
+//     请求），故它禁止值依赖 session-runner / alive-store / session-pending——否则形成
+//     「mock 工厂 → helper → session-runner → node:child_process（mock 求值中）」循环。
+//     mock 模块工厂 + FakeChild + 纯 fixture 都在 spawn-mock.ts。
+//   - 本文件只被测试文件顶层静态 import（vi.mock 已 hoist 注册完毕、mock 工厂已可安全
+//     执行），故可值依赖 session-runner / alive-store / session-pending 做 vi.mocked 取回
+//     与 runSpawn 前奏封装。
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { afterEach, beforeEach, vi } from "vitest";
+
+import { runSpawn, SPAWN_WATCHDOG_ENV } from "../../engine/engines/pi/session-runner.ts";
+import {
+  listActivePendingFromSessionFile,
+  readActivePendingFromSessionFile,
+} from "../../session-pending.ts";
+import { isProcessAlive, readAliveMarker, writeAliveMarker } from "../../alive-store.ts";
+import {
+  emitStdoutLine,
+  lastSpawnedChild,
+  makeCtx,
+  makeOpts,
+  makeRecord,
+  waitForSpawn,
+  type FakeChild,
+} from "./spawn-mock.ts";
+
+/** keep-alive 用例的 session header 行（stdout 首行）。 */
+function sessionHeaderLine(): Record<string, unknown> {
+  return { type: "session", id: "sess-ka", timestamp: "2026-09-01T00:00:00.000Z", cwd: "/tmp/test" };
+}
+
+/** vi.mocked 取回超集（各测试文件按需解构；与各 vi.mock 工厂返回同一 mock 实例）。 */
+export function takeSessionRunnerMocks() {
+  return {
+    mockSpawn: vi.mocked(spawn),
+    mockExistsSync: vi.mocked(fs.existsSync),
+    mockReaddirSync: vi.mocked(fs.readdirSync as (path: fs.PathLike) => string[]),
+    mockPending: vi.mocked(readActivePendingFromSessionFile),
+    mockListPending: vi.mocked(listActivePendingFromSessionFile),
+    mockReadAliveMarker: vi.mocked(readAliveMarker),
+    mockWriteAliveMarker: vi.mocked(writeAliveMarker),
+    mockIsProcessAlive: vi.mocked(isProcessAlive),
+  };
+}
+
+/**
+ * 非 chatMode 层主 + fake timers + agent_end keep-alive 落位的公共前奏。
+ *
+ * 返回 promise（runSpawn 原始 promise，供手动 exit/close 收尾的用例）与 finish
+ * （标准 close 收尾）两种取用形态。
+ */
+export async function spawnAndReachKeepAlive(
+  opts = makeOpts(),
+  task = "Task: keep-alive no-progress",
+): Promise<{
+  child: FakeChild;
+  promise: Promise<Awaited<ReturnType<typeof runSpawn>>>;
+  finish: (code?: number) => Promise<Awaited<ReturnType<typeof runSpawn>>>;
+}> {
+  const record = makeRecord();
+  const promise = runSpawn(record, task, opts, makeCtx());
+  await waitForSpawn(vi.mocked(spawn));
+  const child = lastSpawnedChild(vi.mocked(spawn));
+  // 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,
+    promise,
+    finish: (code = 143) => {
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", code);
+      return promise as Promise<Awaited<ReturnType<typeof runSpawn>>>;
+    },
+  };
+}
+
+/** 让最近 spawn 的 FakeChild 发 close(0) 并等 runSpawn 收尾（env 注入用例的标准收尾装配）。 */
+export async function closeLastChildAndAwait<T>(promise: Promise<T>): Promise<T> {
+  const child = lastSpawnedChild(vi.mocked(spawn));
+  child.emit("close", 0);
+  return promise;
+}
+
+/** keep-alive 系测试的统一 hooks：清 mock + stub 空 watchdog env + 统一恢复（在 describe 内调用）。 */
+export function keepAliveTestHooks(
+  mockPending: ReturnType<typeof takeSessionRunnerMocks>["mockPending"],
+): void {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubEnv(SPAWN_WATCHDOG_ENV, "");
+    mockPending.mockReturnValue({ count: 1, recentUnregister: false });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+    vi.useRealTimers();
+  });
+}

package/src/execution/__tests__/helpers/spawn-mock.ts

@@ -47,7 +47,7 @@
 //     };
 //   });
 //   vi.mock("../alive-store.ts", () => ({ writeAliveMarker: vi.fn() }));
-//   vi.mock("../temp-prompt.ts", () => ({
+//   vi.mock("../engine/engines/pi/temp-prompt.ts", () => ({
 //     writePromptToTempFile: vi.fn(async (agent: string) => {
 //       const safeName = agent.replace(/[^\w.-]+/g, "_");
 //       return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
@@ -60,8 +60,10 @@ import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
 
+import { vi } from "vitest";
+
 import { createRecord } from "../../execution-record.ts";
-import type { RunOptions, SessionRunnerContext } from "../../session-runner.ts";
+import type { RunOptions, SessionRunnerContext } from "../../engine/engines/pi/session-runner.ts";
 
 /** FakeChild 的假 pid（满足 ChildProcess.pid 形状，无真实进程语义）。 */
 const FAKE_PID = 12345;
@@ -194,8 +196,9 @@ export function makeRecord(id = "run-1") {
   return createRecord(id, {
     agent: "general-purpose",
     model: "test-model",
-    mode: "sync",
+    mode: "background",
     task: "do something",
+    slug: "spawn-mock",
     startedAt: 1_000_000,
     rootSessionId: "root-session",
     parentRecordId: undefined,
@@ -240,3 +243,147 @@ export function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionR
     ...overrides,
   };
 }
+
+// ── mock 模块工厂（session-runner 系测试共享，从 keep-alive-no-progress /
+// recursive-visibility-env 的逐字重复 mock 块收敛为单源）──
+//
+// 使用模式（vi.mock 工厂内 await import 本文件，免疫 hoist 时序）：
+//   vi.mock("node:child_process", async () =>
+//     (await import("./helpers/spawn-mock.ts")).childProcessModule());
+//
+// 本段保持「无 session-runner / alive-store / session-pending 值依赖」——本文件会被
+// 各 vi.mock 工厂 await import（求值时机 = 被 mock 模块首次请求），若再值依赖
+// session-runner 会构成「mock 工厂 → 本文件 → session-runner → node:child_process
+// （mock 求值中）」循环。需要值依赖这些模块的测试文件侧装配放
+// session-runner-mocks.ts（只被测试文件顶层静态 import）。
+
+/** 共享 logger mock 单例（复核失败 warn 留痕断言用；vi.clearAllMocks 统一重置）。 */
+export const loggerMock = { debug: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+/** "../../core/logger.ts" mock 工厂。 */
+export function coreLoggerModule() {
+  return { getLogger: () => loggerMock };
+}
+
+/** "node:child_process" mock 工厂（spawn 返回 FakeChild + execFile err-first 兜底）。 */
+export function childProcessModule() {
+  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")),
+    ),
+  };
+}
+
+/** "node:fs" mock 工厂（fs 侧写方法 vi.fn 化，promises 保留 actual）。 */
+export async function fsModule(): Promise<Record<string, unknown>> {
+  const actual = await vi.importActual<typeof import("node:fs")>("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,
+  };
+}
+
+/** "../alive-store.ts" mock 工厂（keep-alive 系超集：marker 读写 + pid 存活判定兜底）。 */
+export function aliveStoreModule() {
+  return {
+    writeAliveMarker: vi.fn(),
+    // [T5②] keep-alive 心跳刷新读取现有 marker id（缺失兜底 record.id）
+    readAliveMarker: vi.fn(() => undefined),
+    isProcessAlive: vi.fn(() => false),
+  };
+}
+
+/** "../session-pending.ts" mock 工厂（keep-alive 判定统一 count>0：有活跃后代 → keep-alive 分支）。 */
+export function sessionPendingModule() {
+  return {
+    readActivePendingFromSessionFile: vi.fn(() => ({ count: 1, recentUnregister: false })),
+    prunePendingCursor: vi.fn(),
+    listActivePendingFromSessionFile: vi.fn(() => ({ items: [] })),
+  };
+}
+
+/** "../engine/engines/pi/temp-prompt.ts" mock 工厂（prompt 落 /tmp/fake-<agent>，收尾 no-op）。 */
+export function tempPromptModule() {
+  return {
+    writePromptToTempFile: vi.fn(async (agent: string) => {
+      const safeName = agent.replace(/[^\w.-]+/g, "_");
+      return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+    }),
+    cleanupTempPrompt: vi.fn(async () => {}),
+  };
+}
+
+// ── recursive-visibility / schema-env 族 fixture（env 断言族专用，与上方 makeRecord 系
+// 默认值不同：/fake/* 路径 + test/model 形态参与 PI_SUBAGENT_* 断言，逐字保留原值）──
+
+/** 构造 env 注入断言族的 ExecutionRecord（可 override id/depth）。 */
+export function makeVisibilityRecord(overrides: { id?: string; depth?: number } = {}) {
+  return createRecord(overrides.id ?? "sa-test-record", {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "background",
+    slug: "t",
+    task: "test task",
+    startedAt: Date.now(),
+    rootSessionId: "should-be-overridden-by-sessionRootId-source",
+    parentRecordId: undefined,
+    depth: overrides.depth ?? 0,
+  });
+}
+
+/** 构造 env 注入断言族的 RunOptions（可 override 关键字段）。 */
+export function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+  return {
+    resolved: { model: { provider: "test", id: "model", name: "Model", reasoning: false }, thinkingLevel: undefined },
+    agentConfig: undefined,
+    appendSystemPrompt: undefined,
+    skillPath: undefined,
+    schema: undefined,
+    maxTurns: undefined,
+    graceTurns: undefined,
+    signal: undefined,
+    onEvent: undefined,
+    ...overrides,
+  };
+}
+
+/** 构造 env 注入断言族的 SessionRunnerContext（可 override 关键字段）。 */
+export function makeVisibilityCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+  return {
+    cwd: "/fake/cwd",
+    agentDir: "/fake/agent",
+    skillDirs: [],
+    mainCwd: "/fake/cwd",
+    sessionRootId: "root-main-session",
+    rootCwd: "/fake/cwd",
+    ...overrides,
+  };
+}
+
+/** 取最近一次 spawn 调用传入的 env（跨进程身份注入断言用）。 */
+export function getLastSpawnEnv<T extends { mock: { calls: unknown[][] } }>(
+  mockSpawn: T,
+): Record<string, string | undefined> {
+  const opts = mockSpawn.mock.calls.at(-1)?.[2] as { env?: Record<string, string | undefined> } | undefined;
+  return opts?.env ?? {};
+}