@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/__tests__/finalize-record.test.ts

@@ -26,7 +26,8 @@ vi.mock("../../core/logger.ts", () => ({
 
 import { doFinalizeRecord, doFinalizeRoundToIdle } from "../finalize-record.ts";
 import { ManifestStore } from "../manifest-store.ts";
-import type { AgentResult, ExecutionRecord } from "../types.ts";
+import { getSubagentSessionDir } from "../path-encoding.ts";
+import type { AgentResult, ExecutionRecord, WorktreeHandle } from "../types.ts";
 
 function makeMinimalRecord(overrides: Partial<ExecutionRecord> = {}): ExecutionRecord {
   return {
@@ -36,7 +37,6 @@ function makeMinimalRecord(overrides: Partial<ExecutionRecord> = {}): ExecutionR
     thinkingLevel: undefined,
     mode: "background",
     task: "test",
-    slug: "test",
     startedAt: 1000,
     rootSessionId: "session-main",
     parentRecordId: undefined,
@@ -77,19 +77,19 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
   });
 
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** 构造最小 FinalizeDeps：record 无 sessionFile/worktreeHandle,跳过 Step 0/3 文件操作。 */
-  function makeDeps() {
+  function makeDeps(): Parameters<typeof doFinalizeRecord>[0] {
     return {
       manifestStore,
-      worktreeManager: {} as never,
-      store: { archive: vi.fn(), reportRecordTransition: vi.fn() } as never,
-      modelService: {} as never,
+      worktreeManager: {},
+      store: { archive: vi.fn(), reportRecordTransition: vi.fn() },
+      modelService: {},
       pi: { appendEntry: vi.fn() },
       emitUnregister: vi.fn(),
-    };
+    } as unknown as Parameters<typeof doFinalizeRecord>[0];
   }
 
   it("status=closed + cancelled reason → manifest 写 closed（v4 B-1：cancelled 折入 closed）", async () => {
@@ -165,7 +165,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     expect(errMsg).toContain("disk full");
 
     // ── 核心 claim 6：pi.appendEntry 记录 "subagent:manifest-write-failed" 事件 ──
-    expect(deps.pi.appendEntry).toHaveBeenCalledWith(
+    expect(deps.pi!.appendEntry).toHaveBeenCalledWith(
       "subagent:manifest-write-failed",
       expect.objectContaining({ id: "rec-cleanup-first", error: "disk full" }),
     );
@@ -198,7 +198,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     });
 
     afterEach(() => {
-      fs.rmSync(sessionDir, { recursive: true, force: true });
+      fs.rmSync(sessionDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     });
 
     /** 在 sessionDir 写入带 identity 的 session 文件（1 行 identity entry，位于头部）。 */
@@ -271,6 +271,162 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
       loggerMock.error.mockClear();
     });
   });
+
+  // ── Step 3a 判别 wiring：closedReason → tombstone vs finalized（MF-1 fix / v4 B-1）──
+  //
+  // record 带 sessionFile 直接命中 writeFinalizedOrTombstone 的核心判别分支：
+  //   cancelled → writeCancelledTombstone（防重建丢失 cancelled 语义）
+  //   其余 reason → writeFinalized（真实 reason 进 sidecar 内容，磁盘重建还原 closedReason）
+  // 两路 sidecar 互斥（BC-4）：断言「写了哪个 + 没写哪个」双向锁定。
+  describe("writeFinalizedOrTombstone 判别 wiring（closedReason → tombstone vs finalized）", () => {
+    it("closedReason=cancelled → tombstone sidecar 携带 id/status/agent/startedAt/endedAt 且不写 .finalized", async () => {
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      const record = makeMinimalRecord({
+        id: "rec-wire-cancelled",
+        sessionFile,
+        // 预设 endedAt 会被 Step 1 completeRecord 冻结值覆盖（见下方 endedAt 断言注释）
+        endedAt: 5678,
+      });
+
+      await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", "cancelled");
+
+      // tombstone 写出且内容为完整 CancelledTombstone（经 readCancelledTombstone 形态校验的
+      // 字段逐项断言，不用 objectContaining 放宽——重建链路靠这些字段还原）
+      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(true);
+      const tomb = JSON.parse(fs.readFileSync(`${sessionFile}.cancelled`, "utf-8")) as {
+        id: string;
+        status: string;
+        agent: string;
+        startedAt: number;
+        endedAt: number;
+      };
+      expect(tomb.id).toBe("rec-wire-cancelled");
+      expect(tomb.status).toBe("cancelled");
+      expect(tomb.agent).toBe("worker");
+      expect(tomb.startedAt).toBe(1000);
+      // endedAt 来自 completeRecord 冻结后的 record.endedAt（Step 1 先于 Step 3a，
+      // record 预设的 endedAt 会被冻结值覆盖）——tombstone 携带真实收尾时间戳
+      expect(tomb.endedAt).toBe(record.endedAt);
+      expect(typeof tomb.endedAt).toBe("number");
+      // 互斥：cancelled 路径绝不写 finalized（否则重建判「正常结束」，cancelled 语义丢失）
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(false);
+    });
+
+    it.each(["user-close", "gc"] as const)(
+      "closedReason=%s → .finalized 内容携带真实 reason 且不写 tombstone",
+      async (reason) => {
+        const sessionFile = path.join(tmpDir, "session.jsonl");
+        const record = makeMinimalRecord({ id: `rec-wire-${reason}`, sessionFile });
+
+        await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "closed", reason);
+
+        // finalized sidecar 写出且内容 = 真实 reason（磁盘重建用它还原 closedReason，
+        // 不再一律硬编码 gc）
+        expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+        expect(fs.readFileSync(`${sessionFile}.finalized`, "utf-8")).toBe(reason);
+        // 互斥：非 cancelled 路径不写 tombstone
+        expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(false);
+      },
+    );
+  });
+
+  // ── Step 0 collectPatch wiring：worktreeHandle 置位 → patch 收集 + patchFile 回填 ──
+  //
+  // [MF#3] patchFile 必须写到 worktree 之外（sessionsDir/<branch>.patch），避免被
+  // cleanup 删除；仅 patch.written=true（diff 非空且写盘成功）才回填 record.patchFile，
+  // 避免悬空路径让 `git apply` 打不存在的文件。
+  describe("collectPatchIfWorktree wiring（worktreeHandle 置位 + patch.written 回填）", () => {
+    // agentDir 是真实写目标：finalize-record Step 0 对 sessionsDir 做 mkdirSync(recursive)，
+    // 会在 agentDir 下创建整棵 subagents/<enc>/sessions 树。必须 mkdtemp 自建 + afterEach
+    // 清理（测试红线），禁止硬编码真实 /tmp 路径。mainCwd / handle.path 仅作编码键与
+    // startsWith 断言，源码不落盘，保持字面量即可。
+    let agentDir: string;
+
+    beforeEach(() => {
+      agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "collect-patch-agent-"));
+    });
+
+    afterEach(() => {
+      fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+    });
+
+    const mainCwd = "/tmp/collect-patch-main-repo";
+    const branch = "subagent-b1";
+    const handle: WorktreeHandle = {
+      path: "/tmp/collect-patch-checkout",
+      branch,
+      baseCommit: "abc123",
+      mainCwd,
+    };
+
+    function makeWorktreeDeps(
+      collectPatch: ReturnType<typeof vi.fn>,
+    ): ReturnType<typeof makeDeps> & { agentDir: string } {
+      // 覆写 worktreeManager / modelService 为 stub（与外层 makeDeps 同款 unknown 断言——
+      // FinalizeDeps 的 ModelConfigService/WorktreeManager 是宽接口，stub 只需覆盖本次路径）
+      return {
+        ...makeDeps(),
+        modelService: { getAgentDir: () => agentDir },
+        worktreeManager: { collectPatch, cleanup: vi.fn() },
+        agentDir,
+      } as unknown as ReturnType<typeof makeDeps> & { agentDir: string };
+    }
+
+    it("patch.written=true → collectPatch 收到 handle + sessionsDir/<branch>.patch，record.patchFile 回填", async () => {
+      const { agentDir, ...deps } = makeWorktreeDeps(vi.fn().mockResolvedValue({
+        patchFile: "/ignored/collector-picked-path.patch",
+        failed: false,
+        written: true,
+      }));
+      const sessionsDir = getSubagentSessionDir(agentDir, mainCwd);
+      const expectedPatchFile = path.join(sessionsDir, `${branch}.patch`);
+      const record = makeMinimalRecord({ id: "rec-patch", worktreeHandle: handle });
+
+      await doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc");
+
+      // collectPatch 被调用，patchFile 由 finalize-record 拼装（sessionsDir/<branch>.patch）
+      expect(deps.worktreeManager.collectPatch).toHaveBeenCalledTimes(1);
+      expect(deps.worktreeManager.collectPatch).toHaveBeenCalledWith(handle, expectedPatchFile);
+      // sessionsDir 已 mkdir（recursive）——patchFile 的父目录真实存在
+      expect(fs.existsSync(sessionsDir)).toBe(true);
+      // [MF#3] patchFile 落在 worktree 之外（不会被 Step 3 cleanup 连带删除）
+      expect(expectedPatchFile.startsWith(handle.path)).toBe(false);
+      // patch.written=true → record.patchFile 回填为 finalize-record 拼装的路径
+      expect(record.patchFile).toBe(expectedPatchFile);
+    });
+
+    it("patch.written=false（空 diff / 写失败）→ record.patchFile 不回填（避免悬空路径）", async () => {
+      const { agentDir, ...deps } = makeWorktreeDeps(vi.fn().mockResolvedValue({
+        patchFile: "/ignored/never-written.patch",
+        failed: false,
+        written: false,
+      }));
+      const record = makeMinimalRecord({ id: "rec-patch-empty", worktreeHandle: handle });
+
+      await doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc");
+
+      expect(deps.worktreeManager.collectPatch).toHaveBeenCalledTimes(1);
+      expect(record.patchFile).toBeUndefined();
+    });
+
+    it("collectPatch 抛错 → best-effort 不阻断 finalize 链（manifest 照写、cleanup 照执行）", async () => {
+      const { agentDir, ...deps } = makeWorktreeDeps(vi.fn().mockRejectedValue(new Error("git died")));
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      const record = makeMinimalRecord({ id: "rec-patch-err", sessionFile, worktreeHandle: handle });
+
+      await expect(
+        doFinalizeRecord(deps, record, makeMinimalResult(), "closed", "gc"),
+      ).resolves.toBeUndefined();
+
+      // Step 0 失败不影响后续步骤：finalized sidecar 与 manifest 照常落地
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+      const manifest = await manifestStore.readManifest("rec-patch-err");
+      expect(manifest?.status).toBe("closed");
+      expect(deps.worktreeManager.cleanup).toHaveBeenCalledTimes(1);
+      expect(record.patchFile).toBeUndefined();
+      loggerMock.error.mockClear();
+    });
+  });
 });
 
 // ============================================================
@@ -287,19 +443,19 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
   });
 
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** 构造 FinalizeDeps：worktreeManager.cleanup / store.archive 为 vi.fn 以断言「不调」。 */
-  function makeDeps() {
+  function makeDeps(): Parameters<typeof doFinalizeRoundToIdle>[0] {
     return {
       manifestStore,
-      worktreeManager: { cleanup: vi.fn(), collectPatch: vi.fn() } as never,
-      store: { archive: vi.fn(), reportRecordTransition: vi.fn() } as never,
-      modelService: {} as never,
-      pi: { appendEntry: vi.fn() } as never,
+      worktreeManager: { cleanup: vi.fn(), collectPatch: vi.fn() },
+      store: { archive: vi.fn(), reportRecordTransition: vi.fn() },
+      modelService: {},
+      pi: { appendEntry: vi.fn() },
       emitUnregister: vi.fn(),
-    };
+    } as unknown as Parameters<typeof doFinalizeRoundToIdle>[0];
   }
 
   it("record 带 sessionFile → 删 .alive + record.status=running + round 0→1", async () => {

package/src/execution/__tests__/finalized-marker.test.ts

@@ -20,7 +20,7 @@ describe("finalized-marker", () => {
     sessionFile = path.join(tmpDir, "2026-01-01_uuid.jsonl");
   });
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   describe("write → read 往返", () => {

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

@@ -26,7 +26,7 @@ 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),
@@ -35,7 +35,16 @@ vi.mock("../session-runner.ts", () => ({
   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";
@@ -97,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" });
@@ -109,7 +119,7 @@ describe("[M8] idle record GC 定时器（startGcTimer）", () => {
 
   afterEach(() => {
     service.dispose();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     vi.useRealTimers();
   });
 
@@ -183,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,7 +27,7 @@ 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),
@@ -169,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);
@@ -186,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", () => {
@@ -194,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", () => {
@@ -206,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(); // 未重建注册
   });
 
@@ -230,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/,
     );
   });
@@ -246,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

@@ -14,7 +14,7 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { requestGetStateOnce } from "../get-state-handshake.ts";
+import { requestGetStateOnce } from "../engine/engines/pi/get-state-handshake.ts";
 import type { ChildProcess } from "node:child_process";
 
 /** 最小 FakeChild：只需 stdin.write 行为（成功 / 可注入同步 throw）。 */

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();
+  });
+}