@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/__tests__/run-and-finalize-anchoring.test.ts

@@ -0,0 +1,387 @@
+// src/execution/__tests__/run-and-finalize-anchoring.test.ts
+//
+// runAndFinalize 特征锚定基线（第二批复杂度债务 U04：锚定测试先行）。
+//
+// 既有 run-and-finalize-chatmode.test.ts 覆盖 settle 阶段的 chatMode × closeAfterRound
+// 分流；本文件补直接分支缺口，重构前后行为逐字节对照（错误文案 / 终态写盘 / 事件顺序）：
+//   G1  pooled acquire 成功 → acquire → runSpawn → release 调用次序 + 轮次回退事件(running)
+//   G2  排队 acquire 被中止（signal.aborted）→ finalizeAborted（"cancelled by user"）
+//   G3  acquire 非中止失败 → finalizeFailed 合成 "aborted" 文案（原始错误被吞——现状怪癖锚定）
+//   G4  非 chatMode + runSpawn 抛错 → finalizeFailed：closed/gc + archive + manifest 落盘
+//   G5  chatMode + runSpawn 抛错 → MF-6 回退：record.result="round did not complete: <msg>"
+//   G6  chatMode + 抛错 + CAS 输（record 已 closed）→ 不回退、不 archive、原样返回合成 result
+//   G7  chatMode + idle timer armed → early return：settle 不执行（round/closeAfterRound 不动）
+//   G8  settle 阶段 CAS 输（record 已 closed）→ 跳过收尾、closeAfterRound 不消费
+//   G9  非 chatMode + 失败 result → else 分支：closed/gc + archive + manifest 落盘 + endedAt
+//   G10 运行中 abort → closedReason="cancelled" 终态化，result 原样返回（不改写为 cancelled 形态）
+//
+// harness 与 run-and-finalize-chatmode.test.ts 同形态：mock session-runner.runSpawn，
+// 走 SubagentService 真实 runAndFinalize 分流逻辑，断言「最终可观察状态」。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// mock logger（doFinalizeRecord 的 manifest 写入降级路径用 logger.error）
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), error: vi.fn(), warn: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+// mock session-runner：runSpawn 受控返回 result / 抛错，killAllSpawnedChildren 空实现。
+// 注意：必须在 import SubagentService 之前 mock（vi.mock 提升到顶部）。
+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 { runSpawn } from "../engine/engines/pi/session-runner.ts";
+import type { SessionRunnerContext } from "../engine/engines/pi/session-runner.ts";
+import { armIdleTimer, disarmIdleTimer } from "../lifecycle-manager.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo } from "../model-resolver.ts";
+import { getSubagentRecordsDir } from "../path-encoding.ts";
+import { RecordStore } from "../record-store.ts";
+import type { ConcurrencyPool } from "../concurrency-pool.ts";
+import { SubagentService } from "../subagent-service.ts";
+import type { PiLike } from "../subagent-service.ts";
+import type {
+  AgentResult,
+  ExecutionRecord,
+  ExecuteOptions,
+} from "../types.ts";
+
+const mockRunSpawn = vi.mocked(runSpawn);
+
+// ── 最小合法 ModelInfo（resolveModel 未注入 registry 会抛错，故 stub；runSpawn 被 mock 不消费）──
+const STUB_MODEL: ModelInfo = {
+  id: "test-model",
+  name: "Test",
+  provider: "test",
+  reasoning: false,
+};
+
+function makeTmpAgentDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "raf-anchor-test-"));
+}
+
+function makePi(): PiLike & {
+  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((customType: string, data?: unknown) => {}),
+    events: { emit: vi.fn((channel: string, data: unknown) => {}) },
+    sendMessage: vi.fn(() => {}),
+  };
+}
+
+function makeResult(success: boolean): AgentResult {
+  return {
+    text: success ? "done" : "err",
+    turns: 1,
+    durationMs: 100,
+    success,
+    error: success ? undefined : "boom",
+    sessionId: "sess-1",
+    toolCalls: [],
+  };
+}
+
+function makeRecord(chatMode: boolean, id: string): ExecutionRecord {
+  return createRecord(id, {
+    agent: "general-purpose",
+    model: "test-model",
+    mode: "background",
+    task: "do something",
+    slug: "test",
+    startedAt: 1000,
+    rootSessionId: "root-session",
+    chatMode,
+  });
+}
+
+/** 暴露 runAndFinalize + store + pool 的私有访问接口（测试专用 cast）。 */
+interface ServiceInternals {
+  store: RecordStore;
+  pool: ConcurrencyPool;
+  runAndFinalize: (
+    record: ExecutionRecord,
+    opts: ExecuteOptions,
+    ctx: SessionRunnerContext,
+    identity: {
+      agent: string;
+      agentConfig: unknown;
+      resolved: { model: ModelInfo; thinkingLevel: string | undefined };
+    },
+    signal: AbortSignal | undefined,
+    priority: number,
+  ) => Promise<AgentResult>;
+}
+
+describe("runAndFinalize 特征锚定基线（U04 重构前后行为对照）", () => {
+  let agentDir: string;
+  let modelService: ModelConfigService;
+  let service: SubagentService;
+  let internals: ServiceInternals;
+  let pi: ReturnType<typeof makePi>;
+  let armedTimerRecordIds: string[];
+
+  beforeEach(() => {
+    // rootCwd 推导基线：PI_SUBAGENT_ROOT_CWD 若被宿主 env 污染会改写 recordsDir 编码段，
+    // manifest 落盘断言（G4/G9）依赖「rootCwd = init.cwd」的未设基线。
+    delete process.env.PI_SUBAGENT_ROOT_CWD;
+    agentDir = makeTmpAgentDir();
+    modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+    service = new SubagentService({ cwd: agentDir, modelService });
+    pi = makePi();
+    service.initSession({ pi, sessionId: "root-session" });
+    internals = service as unknown as ServiceInternals;
+    armedTimerRecordIds = [];
+    mockRunSpawn.mockReset();
+  });
+
+  afterEach(() => {
+    for (const id of armedTimerRecordIds) disarmIdleTimer(id);
+    service.dispose();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  /** 直接调私有 runAndFinalize（mock runSpawn 后走完整分流逻辑）。 */
+  async function callRunAndFinalize(
+    record: ExecutionRecord,
+    mockImpl: () => void,
+    signal?: AbortSignal,
+  ): Promise<AgentResult> {
+    mockImpl();
+    const opts: ExecuteOptions = { task: "do something", slug: "test" };
+    const ctx: SessionRunnerContext = {
+      cwd: agentDir,
+      agentDir,
+      skillDirs: [],
+      mainCwd: agentDir,
+      sessionRootId: "s-root",
+      rootCwd: agentDir,
+    };
+    const identity = {
+      agent: "general-purpose",
+      agentConfig: undefined,
+      resolved: { model: STUB_MODEL, thinkingLevel: undefined },
+    };
+    return internals.runAndFinalize(record, opts, ctx, identity, signal, 0);
+  }
+
+  function manifestPath(recordId: string): string {
+    return path.join(getSubagentRecordsDir(agentDir, agentDir), `${recordId}.json`);
+  }
+
+  it("G1: pooled acquire 成功 → acquire → runSpawn → release 次序锚定 + 轮次回退事件(running)", async () => {
+    const record = makeRecord(false, "sa-anchor-g1");
+    internals.store.register(record);
+    const pool = internals.pool;
+    const acquireSpy = vi.spyOn(pool, "acquire");
+    const releaseSpy = vi.spyOn(pool, "release");
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockResolvedValueOnce(makeResult(true)));
+
+    expect(result.text).toBe("done");
+    // 事件顺序：acquire 先于 runSpawn，release（finally 收口）最后。
+    expect(acquireSpy).toHaveBeenCalledTimes(1);
+    expect(mockRunSpawn).toHaveBeenCalledTimes(1);
+    expect(releaseSpy).toHaveBeenCalledTimes(1);
+    const order = acquireSpy.mock.invocationCallOrder[0];
+    const spawnOrder = mockRunSpawn.mock.invocationCallOrder[0];
+    const releaseOrder = releaseSpy.mock.invocationCallOrder[0];
+    expect(order).toBeLessThan(spawnOrder);
+    expect(spawnOrder).toBeLessThan(releaseOrder);
+    // one-shot 成功无 closeAfterRound → finalizeRoundToIdle：留内存 + 进程死注销事件(running)。
+    expect(record.status).toBe("running");
+    expect(internals.store.getMutable(record.id)).toBe(record);
+    expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", { id: record.id, reason: "running" });
+  });
+
+  it("G2: 排队 acquire 被中止（signal.aborted）→ finalizeAborted：'cancelled by user' + closed/cancelled + archive", async () => {
+    const record = makeRecord(false, "sa-anchor-g2");
+    internals.store.register(record);
+    const releaseSpy = vi.spyOn(internals.pool, "release");
+    const controller = new AbortController();
+    controller.abort(); // pre-aborted：signal.aborted = true
+    // 真实 ConcurrencyPool.acquire 对 pre-aborted signal 并不保证 reject——
+    // 显式 mock 排队中止（acquire reject + signal.aborted）以触发 catch 的 S1 分支。
+    vi.spyOn(internals.pool, "acquire").mockRejectedValueOnce(new Error("AbortError: queued acquire aborted"));
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockResolvedValueOnce(makeResult(true)), controller.signal);
+
+    // 错误路径文案逐字节：S1 对齐已运行被 abort 的 cancel 语义。
+    expect(result.error).toBe("cancelled by user");
+    expect(result.success).toBe(false);
+    // 终态：closed + cancelled + archive（写盘收尾走完），runSpawn 未触达。
+    expect(record.status).toBe("closed");
+    expect(record.closedReason).toBe("cancelled");
+    expect(record.endedAt).toBeDefined();
+    expect(internals.store.getMutable(record.id)).toBeUndefined();
+    expect(mockRunSpawn).not.toHaveBeenCalled();
+    // acquire 失败早退（try/finally 之前）→ 池槽不归还（acquired=false 语义）。
+    expect(releaseSpy).not.toHaveBeenCalled();
+    expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", { id: record.id, reason: "closed" });
+  });
+
+  it("G3: acquire 非中止失败 → finalizeFailed 合成 'aborted' 文案（原始错误被吞——现状怪癖锚定）", async () => {
+    const record = makeRecord(false, "sa-anchor-g3");
+    internals.store.register(record);
+    const releaseSpy = vi.spyOn(internals.pool, "release");
+    vi.spyOn(internals.pool, "acquire").mockRejectedValueOnce(new Error("pool exploded"));
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockResolvedValueOnce(makeResult(true)));
+
+    // 现状：catch 吞掉原始错误，统一合成 new Error("aborted") → toErrorMessage = "aborted"。
+    // "pool exploded" 不透传——重构必须保持该文案（行为逐字节不变）。
+    expect(result.error).toBe("aborted");
+    expect(result.success).toBe(false);
+    expect(record.status).toBe("closed");
+    expect(record.closedReason).toBe("gc");
+    expect(internals.store.getMutable(record.id)).toBeUndefined();
+    expect(mockRunSpawn).not.toHaveBeenCalled();
+    expect(releaseSpy).not.toHaveBeenCalled();
+  });
+
+  it("G4: 非 chatMode + runSpawn 抛错 → finalizeFailed：error 透传 + closed/gc + archive + manifest 落盘", async () => {
+    const record = makeRecord(false, "sa-anchor-g4");
+    internals.store.register(record);
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockRejectedValueOnce(new Error("spawn exploded")));
+
+    // 错误文案：toErrorMessage(Error) → .message 逐字节透传。
+    expect(result.error).toBe("spawn exploded");
+    expect(result.success).toBe(false);
+    // 终态写盘：closed + gc + archive + manifest json 落盘。
+    expect(record.status).toBe("closed");
+    expect(record.closedReason).toBe("gc");
+    expect(record.endedAt).toBeDefined();
+    expect(internals.store.getMutable(record.id)).toBeUndefined();
+    expect(fs.existsSync(manifestPath(record.id))).toBe(true);
+    expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", { id: record.id, reason: "closed" });
+  });
+
+  it("G5: chatMode + runSpawn 抛错 → MF-6 回退：'round did not complete: <msg>' + running + round+1 + 留内存", async () => {
+    const record = makeRecord(true, "sa-anchor-g5");
+    internals.store.register(record);
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockRejectedValueOnce(new Error("spawn creation failed")));
+
+    // 合成 failed result 错误文案透传（swallow，不 re-throw）。
+    expect(result.error).toBe("spawn creation failed");
+    // MF-6：不销毁对话——finalizeRoundToIdle 回退 running-resumable（留内存可重试 message/close）。
+    expect(record.status).toBe("running");
+    expect(record.closedReason).toBeUndefined(); // [S10] 不残留 gc
+    expect(record.round).toBe(1);
+    expect(internals.store.getMutable(record.id)).toBe(record);
+    // MF-2 写点：失败轮 error 优先 → record.result 固定前缀文案（notify 正文逐字节）。
+    expect(record.result).toBe("round did not complete: spawn creation failed");
+    // 事件：进程死注销 reason=running（非 closed——record 留内存非终态）。
+    expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", { id: record.id, reason: "running" });
+  });
+
+  it("G6: chatMode + 抛错 + CAS 输（record 已 closed）→ 不回退不 archive，原样返回合成 result", async () => {
+    const record = makeRecord(true, "sa-anchor-g6");
+    record.status = "closed"; // cancel/收尾抢先：tryTransition(closed, gc) 必败
+    internals.store.register(record);
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockRejectedValueOnce(new Error("spawn creation failed")));
+
+    expect(result.error).toBe("spawn creation failed");
+    // CAS 输：无任何收尾副作用——状态/轮次不动、留内存、无注销事件。
+    expect(record.status).toBe("closed");
+    expect(record.round).toBe(0);
+    expect(internals.store.getMutable(record.id)).toBe(record);
+    expect(pi.events.emit).not.toHaveBeenCalled();
+  });
+
+  it("G7: chatMode + idle timer armed → early return：settle 不执行（round/closeAfterRound 不动）", async () => {
+    const record = makeRecord(true, "sa-anchor-g7");
+    record.status = "running";
+    record.round = 1;
+    internals.store.register(record);
+    // V2 决策 2/3 形态：onRoundSettled 已 arm idle timer（agent_settled 提前闭环）。
+    armIdleTimer(record.id, () => {}, 60_000);
+    armedTimerRecordIds.push(record.id);
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockResolvedValueOnce(makeResult(true)));
+
+    // early return：原样返回 runSpawn result，settle 阶段未执行。
+    expect(result.text).toBe("done");
+    expect(record.status).toBe("running");
+    expect(record.round).toBe(1); // 未 +1（round+1 归 onRoundSettled，非本函数）
+    expect(record.closeAfterRound).toBeUndefined();
+    expect(internals.store.getMutable(record.id)).toBe(record);
+    expect(pi.events.emit).not.toHaveBeenCalled();
+  });
+
+  it("G8: settle 阶段 CAS 输（record 已 closed）→ 跳过收尾、closeAfterRound 不消费", async () => {
+    const record = makeRecord(false, "sa-anchor-g8");
+    record.status = "closed"; // cancel 抢先（A2-1 形态）
+    record.closeAfterRound = true;
+    internals.store.register(record);
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockResolvedValueOnce(makeResult(true)));
+
+    // 原样返回（不改写为 cancelled 形态）；收尾全跳过。
+    expect(result.text).toBe("done");
+    expect(result.success).toBe(true);
+    expect(record.status).toBe("closed");
+    expect(record.closeAfterRound).toBe(true); // 标志不被本路径消费
+    expect(record.endedAt).toBeUndefined();
+    expect(internals.store.getMutable(record.id)).toBe(record);
+    expect(pi.events.emit).not.toHaveBeenCalled();
+  });
+
+  it("G9: 非 chatMode + 失败 result → else 分支：closed/gc + archive + manifest 落盘 + endedAt", async () => {
+    const record = makeRecord(false, "sa-anchor-g9");
+    internals.store.register(record);
+
+    const result = await callRunAndFinalize(record, () => mockRunSpawn.mockResolvedValueOnce(makeResult(false)));
+
+    // 失败 result 原样返回（错误文案不经本函数改写）。
+    expect(result.success).toBe(false);
+    expect(result.error).toBe("boom");
+    // 非 chatMode 失败 = 一次性销毁（archive + manifest 落盘）。
+    expect(record.status).toBe("closed");
+    expect(record.closedReason).toBe("gc");
+    expect(record.endedAt).toBeDefined();
+    expect(internals.store.getMutable(record.id)).toBeUndefined();
+    expect(fs.existsSync(manifestPath(record.id))).toBe(true);
+    expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", { id: record.id, reason: "closed" });
+  });
+
+  it("G10: 运行中 abort → closedReason='cancelled' 终态化，result 原样返回（不改写）", async () => {
+    const record = makeRecord(false, "sa-anchor-g10");
+    internals.store.register(record);
+    const controller = new AbortController();
+    // acquire（signal 未中止 → 放行）后、runSpawn resolve 前中止。
+    mockRunSpawn.mockImplementationOnce(async () => {
+      await new Promise((r) => { setTimeout(r, 15); });
+      return makeResult(true);
+    });
+    setTimeout(() => controller.abort(), 5);
+
+    const result = await callRunAndFinalize(record, () => {}, controller.signal);
+
+    // result 原样返回（success true 不被改写为 cancelled 形态——现状锚定）。
+    expect(result.success).toBe(true);
+    expect(result.text).toBe("done");
+    // 终态：closed + cancelled（abort 折入 closed）+ archive。
+    expect(record.status).toBe("closed");
+    expect(record.closedReason).toBe("cancelled");
+    expect(record.endedAt).toBeDefined();
+    expect(internals.store.getMutable(record.id)).toBeUndefined();
+    expect(pi.events.emit).toHaveBeenCalledWith("pending:unregister", { id: record.id, reason: "closed" });
+  });
+});

package/src/execution/__tests__/run-and-finalize-chatmode.test.ts

@@ -25,7 +25,7 @@ vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
 // mock session-runner：runSpawn 受控返回 result，killAllSpawnedChildren 空实现。
 // 注意：必须在 import SubagentService 之前 mock（vi.mock 提升到顶部）。
-vi.mock("../session-runner.ts", () => ({
+vi.mock("../engine/engines/pi/session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: vi.fn(() => undefined),
@@ -34,8 +34,8 @@ vi.mock("../session-runner.ts", () => ({
   spawnedChildren: new Map(),
 }));
 
-import { runSpawn } from "../session-runner.ts";
-import type { SessionRunnerContext } from "../session-runner.ts";
+import { runSpawn } from "../engine/engines/pi/session-runner.ts";
+import type { SessionRunnerContext } from "../engine/engines/pi/session-runner.ts";
 import { createRecord } from "../execution-record.ts";
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo } from "../model-resolver.ts";
@@ -63,11 +63,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 {
@@ -120,7 +124,7 @@ describe("runAndFinalize chatMode idle 分流 (M2-A)", () => {
 
   beforeEach(() => {
     agentDir = makeTmpAgentDir();
-    modelService = new ModelConfigService({ agentDir });
+    modelService = new ModelConfigService({ agentDir, cwd: agentDir });
     service = new SubagentService({ cwd: agentDir, modelService });
     service.initSession({ pi: makePi(), sessionId: "root-session" });
     internals = service as unknown as ServiceInternals;
@@ -129,7 +133,7 @@ describe("runAndFinalize chatMode idle 分流 (M2-A)", () => {
 
   afterEach(() => {
     service.dispose();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** 直接调私有 runAndFinalize（mock runSpawn 后走完整分流逻辑）。 */
@@ -141,6 +145,8 @@ describe("runAndFinalize chatMode idle 分流 (M2-A)", () => {
       agentDir,
       skillDirs: [],
       mainCwd: agentDir,
+      sessionRootId: "s-root",
+      rootCwd: agentDir,
     };
     const identity = {
       agent: "general-purpose",

package/src/execution/__tests__/run-spawn-chatmode-settled.test.ts

@@ -63,7 +63,7 @@ vi.mock("../session-pending.ts", () => ({
   prunePendingCursor: 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` };
@@ -71,8 +71,8 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { runSpawn } from "../session-runner.ts";
-import type { SessionRunnerContext } from "../session-runner.ts";
+import { runSpawn } from "../engine/engines/pi/session-runner.ts";
+import type { SessionRunnerContext } from "../engine/engines/pi/session-runner.ts";
 import {
   DEFAULT_IDLE_TIMEOUT_MS,
   hasIdleTimer,
@@ -101,7 +101,7 @@ function makeChatModeRecord(id = "sa-chat"): ExecutionRecord {
   return createRecord(id, {
     agent: "general-purpose",
     model: "test-model",
-    mode: "sync",
+    mode: "background",
     task: "chat task",
     slug: "chat",
     startedAt: 1_000_000,

package/src/execution/__tests__/run-spawn-edges.test.ts

@@ -78,7 +78,7 @@ vi.mock("../session-pending.ts", () => ({
   prunePendingCursor: 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` };
@@ -86,7 +86,7 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS, killAllSpawnedChildren, runSpawn, spawnedChildren, WAKEUP_GRACE_MS, maxTurnsToWatchdogMs, SPAWN_WATCHDOG_ENV } from "../session-runner.ts";
+import { KEEP_ALIVE_NO_PROGRESS_TIMEOUT_MS, killAllSpawnedChildren, runSpawn, spawnedChildren, WAKEUP_GRACE_MS, maxTurnsToWatchdogMs, SPAWN_WATCHDOG_ENV } from "../engine/engines/pi/session-runner.ts";
 import { writeAliveMarker } from "../alive-store.ts";
 import { getSubagentSessionDir } from "../path-encoding.ts";
 import { readActivePendingFromSessionFile } from "../session-pending.ts";
@@ -566,7 +566,7 @@ describe("runSpawn", () => {
     it("MF-4: agent_end（count>0）→ 等待超时 = maxTurnsToWatchdogMs(maxTurns)（动态，非固定 2h）", async () => {
       const maxTurns = 20;
       const expected = maxTurnsToWatchdogMs(maxTurns);
-      mockPending.mockReturnValue({ count: 2 });
+      mockPending.mockReturnValue({ count: 2, recentUnregister: false });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: slow-desc", makeOpts({ maxTurns }), makeCtx());
 
@@ -610,7 +610,7 @@ describe("runSpawn", () => {
       // hermetic：确保兑底 env 未设（若外层 shell 误设会让「裸缺省」断言失效）
       const prevWatchdogEnv = process.env[SPAWN_WATCHDOG_ENV];
       delete process.env[SPAWN_WATCHDOG_ENV];
-      mockPending.mockReturnValue({ count: 2 });
+      mockPending.mockReturnValue({ count: 2, recentUnregister: false });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: slow-desc-no-turns", makeOpts(), makeCtx());
 
@@ -670,7 +670,7 @@ describe("runSpawn", () => {
     it("S-9: agent_end（count=0 + error）→ 保守不 kill + watchdog re-arm 到动态超时", async () => {
       const maxTurns = 20;
       const expected = maxTurnsToWatchdogMs(maxTurns);
-      mockPending.mockReturnValue({ count: 0, error: "session file unreadable: EACCES" });
+      mockPending.mockReturnValue({ count: 0, recentUnregister: false, error: "session file unreadable: EACCES" });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: unreadable", makeOpts({ maxTurns }), makeCtx());
 
@@ -706,7 +706,7 @@ describe("runSpawn", () => {
     });
 
     it("agent_end（willRetry=false，无活跃后代）→ child.kill(SIGTERM) 被调用，close 后 success=true", async () => {
-      mockPending.mockReturnValue({ count: 0 });
+      mockPending.mockReturnValue({ count: 0, recentUnregister: false });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: done", makeOpts(), makeCtx());
 
@@ -731,9 +731,9 @@ describe("runSpawn", () => {
 
     it("agent_end（willRetry=false，有活跃后代）→ 不 kill，进程保持 idle 等 steer 唤醒；后代完成后 kill", async () => {
       // 第一次 agent_end：有活跃后代（count=1）→ 不 kill
-      mockPending.mockReturnValueOnce({ count: 1 });
+      mockPending.mockReturnValueOnce({ count: 1, recentUnregister: false });
       // 第二次 agent_end：后代已 unregister（count=0）→ kill
-      mockPending.mockReturnValueOnce({ count: 0 });
+      mockPending.mockReturnValueOnce({ count: 0, recentUnregister: false });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: orchestrate", makeOpts(), makeCtx());
 
@@ -760,7 +760,7 @@ describe("runSpawn", () => {
     });
 
     it("agent_end（willRetry=true）→ child.kill 不被调用（agent 会重试，等下一个 agent_end）", async () => {
-      mockPending.mockReturnValue({ count: 0 });
+      mockPending.mockReturnValue({ count: 0, recentUnregister: false });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: retry", makeOpts(), makeCtx());
 
@@ -789,7 +789,7 @@ describe("runSpawn", () => {
     });
 
     it("agent_end 后的后续 event 仍被 handleSdkEvent 处理（kill 不阻塞 event pump）", async () => {
-      mockPending.mockReturnValue({ count: 0 });
+      mockPending.mockReturnValue({ count: 0, recentUnregister: false });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: flush", makeOpts(), makeCtx());
 
@@ -829,7 +829,9 @@ describe("runSpawn", () => {
   describe("[T1] agent_end 惰性回补 + LC-4 收尾反查", () => {
     const mockPending = vi.mocked(readActivePendingFromSessionFile);
     const mockWriteAliveMarker = vi.mocked(writeAliveMarker);
-    const mockReaddirSync = vi.mocked(fs.readdirSync);
+    // 被测链路（finalize-record 兜底反查）调用无 options 的 string[] 重载；
+    // vi.mocked 直接包 fs.readdirSync 会推导到 withFileTypes 重载（Dirent[]），显式绑定
+    const mockReaddirSync = vi.mocked(fs.readdirSync as (path: fs.PathLike) => string[]);
 
     /** 统计 stdin 收到的 get_state 请求数（握手 1 次 + agent_end 惰性回补 1 次）。 */
     function countGetStateRequests(child: FakeChild): { seen: number } {
@@ -892,7 +894,7 @@ describe("runSpawn", () => {
     // ① 握手失败（sessionFile 空）→ agent_end 惰性 get_state 回填 → 正常三分支（final kill）
     it("① 握手失败 sessionFile 缺失 → agent_end 惰性 get_state 回填 → 无后代走 final kill（非保守不杀）", async () => {
       // 回补成功后判定：无活跃后代 → final kill 分支（若仍走保守分支则不会 kill，断言失败）
-      mockPending.mockReturnValue({ count: 0 });
+      mockPending.mockReturnValue({ count: 0, recentUnregister: false });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: lazy-backfill", makeOpts(), makeCtx());
 
@@ -935,7 +937,7 @@ describe("runSpawn", () => {
     // ② 回补超时/失败 → 仍走保守分支（行为不劣化）
     it("② 回补无响应超时 → record.sessionFile 仍缺失 → 保守不杀（不劣化为 final kill）", async () => {
       // mock 判定：sessionFile 缺失形态返回 error（真实现语义，见 session-pending.ts:85）
-      mockPending.mockReturnValue({ count: 0, error: "no sessionFile (handshake not settled)" });
+      mockPending.mockReturnValue({ count: 0, recentUnregister: false, error: "no sessionFile (handshake not settled)" });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: lazy-timeout", makeOpts(), makeCtx());
 
@@ -982,7 +984,7 @@ describe("runSpawn", () => {
     // 且顺带覆盖惰性回补的 sessionId 补入 handshakeResult 分支（close 收尾 lookupId 源）。
     it("③ LC-4: 惰性回补只回 sessionId（sessionFile 仍无）→ close 收尾 sessionDir 反查修正 record.sessionFile", async () => {
       // sessionFile 缺失 → 决策点惰性回补；回补判定保守（error → 不杀）
-      mockPending.mockReturnValue({ count: 0, error: "no sessionFile (handshake not settled)" });
+      mockPending.mockReturnValue({ count: 0, recentUnregister: false, error: "no sessionFile (handshake not settled)" });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: lc4-lookup", makeOpts(), makeCtx());
 
@@ -1031,7 +1033,7 @@ describe("runSpawn", () => {
     it("④ A1-3: 回补等待窗口内 kill → close → continuation 不触达三分支（不 touch marker / 不挂 timer）", async () => {
       // 若守卫缺失（回归），continuation 会以 count=1 走 keep-alive 分支：
       // touchAliveMarkerForHeartbeat 写 marker + 裸缺省 arm 无进展 timer（30min 后 kill）
-      mockPending.mockReturnValue({ count: 1 });
+      mockPending.mockReturnValue({ count: 1, recentUnregister: false });
       const record = makeRecord();
       const promise = runSpawn(record, "Task: lazy-race-close", makeOpts(), makeCtx());
 

package/src/execution/__tests__/run-spawn-integration.test.ts

@@ -73,7 +73,7 @@ vi.mock("../alive-store.ts", () => ({
 // temp-prompt：mock 掉真实 fs.promises I/O（mkdtemp/writeFile/rm）。
 // 原先保留真实实现导致 fake-timers 测试偶发 flaky——writePromptToTempFile 的真实异步
 // I/O 在 CI 慢机器上无法在 advanceTimersByTimeAsync 的有限步数内 resolve，spawn 永不触发。
-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` };
@@ -81,7 +81,7 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { runSpawn } from "../session-runner.ts";
+import { runSpawn } from "../engine/engines/pi/session-runner.ts";
 import {
   emitStdoutLine,
   type FakeChild,

package/src/execution/__tests__/run-spawn-resume.test.ts

@@ -53,7 +53,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` };
@@ -61,7 +61,7 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { getChildByRecord, runSpawn, spawnedChildren } from "../session-runner.ts";
+import { getChildByRecord, runSpawn, spawnedChildren } from "../engine/engines/pi/session-runner.ts";
 import {
   emitStdoutLine,
   type FakeChild,

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

@@ -53,7 +53,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` };
@@ -61,7 +61,7 @@ vi.mock("../temp-prompt.ts", () => ({
   cleanupTempPrompt: vi.fn(async () => {}),
 }));
 
-import { runSpawn } from "../session-runner.ts";
+import { runSpawn } from "../engine/engines/pi/session-runner.ts";
 import {
   emitStdoutLine,
   type FakeChild,