@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/subagent-service-recovery-bounds.test.ts

@@ -0,0 +1,341 @@
+// src/execution/__tests__/subagent-service-recovery-bounds.test.ts
+//
+// [u-svc / T2] 服务侧回收上界与 kill 收敛：
+//   - T2④/LC-2：closeChatIdle / closeAfterRoundSettled / cancelBackground 三条裸 SIGTERM
+//     收敛到 killRecordChildWithEscalation（spy 断言调用点与参数）；
+//   - T2⑥/PS-1：disposeAllRecords 补三回收面（controller.abort + kill + disarm idle timer
+//     + disarm settled watchdog）；
+//   - T2③/LC-1 + D9：热路径投递 armMidRoundNoProgress（挂载点 D2 下沉后在编排层
+//     deliverChatMessage 的 interact 返回点；挂载中段无进展检测 + 到期 onMidTimeout/
+//     onSettleTimeout 处置：kill + 失败终态化 + error 含 'settled watchdog' 标记与恢复
+//     指引；agent_end 交棒收尾段的接线在 session-runner stdout pump，两路径共用）；
+//   - T2⑧/PS-3：非 EPIPE 热路径写失败 re-arm idle timer（进程不再裸奔；挂载位 D2
+//     下沉后在 PiEngine.deliverPrompt 的非 EPIPE catch——编排层无法区分错误类别）。
+//
+// mock 形态沿用 subagent-service-message-close.test.ts（真实 SubagentService + ServiceInternals
+// cast 暴露 store + mock session-runner/stdin-writer/logger）。
+
+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";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+// killRecordChildWithEscalation 换 spy（收敛调用点断言）；spawnedChildren 用真 Map
+//（热路径投递判定 / EPIPE 兜底按值删除的消费者）；getChildByRecord 从同一 Map 查
+//（mock 工厂与测试共享同一实例）。D2 后模块物理下沉 engines/pi/（mock 路径随迁）。
+const { killChildSpy, spawnedMap, getChildByRecordMock } = vi.hoisted(() => {
+  const map = new Map<string, unknown>();
+  return {
+    killChildSpy: vi.fn(),
+    spawnedMap: map,
+    getChildByRecordMock: vi.fn((recordId: string) => map.get(recordId)),
+  };
+});
+vi.mock("../engine/engines/pi/session-runner.ts", () => ({
+  runSpawn: vi.fn(),
+  killAllSpawnedChildren: vi.fn(),
+  getChildByRecord: getChildByRecordMock,
+  registerSpawnedChildForRecord: vi.fn(),
+  spawnedChildren: spawnedMap,
+  killRecordChildWithEscalation: killChildSpy,
+}));
+
+// sendPromptCommand 换 spy（控制热路径写成功 / 抛非 EPIPE 错误）。
+const { sendPromptCommandMock } = vi.hoisted(() => ({ sendPromptCommandMock: vi.fn() }));
+vi.mock("../engine/engines/pi/stdin-writer.ts", () => ({
+  sendPromptCommand: sendPromptCommandMock,
+  clearEpipeFailure: vi.fn(),
+  recordEpipeFailure: vi.fn(() => 1),
+  resetAllEpipeFailures: vi.fn(),
+  EPIPE_FAILURE_THRESHOLD: 3,
+}));
+
+import { FakeChild } from "./helpers/spawn-mock.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import type { RecordStore } from "../record-store.ts";
+import { SubagentService } from "../subagent-service.ts";
+import type { PiLike } from "../subagent-service.ts";
+import { armSettledWatchdog, hasSettledWatchdog, SETTLED_MID_ROUND_NO_PROGRESS_MS, _resetSettledWatchdogsForTest } from "../settled-watchdog.ts";
+import { armIdleTimer, hasIdleTimer, _resetLifecycleState } from "../lifecycle-manager.ts";
+import type { ExecutionRecord } from "../types.ts";
+
+function makeTmpAgentDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "svc-recovery-bounds-"));
+}
+
+function makePi(): PiLike & {
+  appendEntry: ReturnType<typeof vi.fn>;
+  events: { emit: ReturnType<typeof vi.fn> };
+  sendMessage: ReturnType<typeof vi.fn>;
+} {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  } as unknown as PiLike & {
+    appendEntry: ReturnType<typeof vi.fn>;
+    events: { emit: ReturnType<typeof vi.fn> };
+    sendMessage: ReturnType<typeof vi.fn>;
+  };
+}
+
+function makeRecord(overrides: Partial<ExecutionRecord> & { id?: string } = {}): ExecutionRecord {
+  const { id = "sa-test", ...rest } = overrides;
+  const r = createRecord(id, {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "background",
+    task: "test",
+    slug: "test",
+    startedAt: 1000,
+    rootSessionId: "root-session",
+    chatMode: true,
+    controller: new AbortController(),
+  });
+  Object.assign(r, rest);
+  return r;
+}
+
+interface ServiceInternals {
+  store: RecordStore;
+}
+
+type MockPi = ReturnType<typeof makePi>;
+
+function setup(): { agentDir: string; service: SubagentService; store: RecordStore; pi: MockPi } {
+  const agentDir = makeTmpAgentDir();
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+  const service = new SubagentService({ cwd: agentDir, modelService });
+  const pi = makePi();
+  service.initSession({ pi, sessionId: "root-session" });
+  const store = (service as unknown as ServiceInternals).store;
+  return { agentDir, service, store, pi };
+}
+
+/** bracket 调 private 方法（ServiceInternals cast 先例的扩展形态）。 */
+function privateFn<K extends string>(service: SubagentService, key: K): (...args: never[]) => unknown {
+  return (service as unknown as Record<string, (...args: never[]) => unknown>)[key];
+}
+
+/**
+ * message 投递入口（D2 后形态：编排层私有 deliverChatMessage → PiEngine.interactRecord
+ * → deliverPrompt；旧直调形态 deliverMessage 已随协议知识下沉删除）。
+ */
+async function deliverChat(
+  service: SubagentService,
+  record: ExecutionRecord,
+  text: string,
+  interrupt: boolean,
+): Promise<void> {
+  return (
+    privateFn(service, "deliverChatMessage") as (
+      this: SubagentService,
+      r: ExecutionRecord,
+      t: string,
+      i: boolean,
+    ) => Promise<void>
+  ).call(service, record, text, interrupt);
+}
+
+describe("T2④ service-side kill convergence", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+  let pi: MockPi;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    killChildSpy.mockClear();
+    sendPromptCommandMock.mockReset();
+    ({ agentDir, service, store, pi } = setup());
+  });
+
+  afterEach(() => {
+    _resetLifecycleState();
+    _resetSettledWatchdogsForTest();
+    spawnedMap.clear();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("cancelBackground (via cancel) routes through killRecordChildWithEscalation", async () => {
+    const record = makeRecord({ id: "sa-cancel" });
+    store.register(record);
+    spawnedMap.set(record.id, new FakeChild());
+    const ok = service.cancel(record.id);
+    expect(ok).toBe(true);
+    expect(killChildSpy).toHaveBeenCalledWith(record.id, "cancelBackground");
+  });
+
+  it("closeChatIdle (via closeSubagent force:false on idle) routes through killRecordChildWithEscalation and disarms timers", async () => {
+    const record = makeRecord({ id: "sa-close-idle" });
+    store.register(record);
+    spawnedMap.set(record.id, new FakeChild());
+    armIdleTimer(record.id, () => {}); // Path A：idle timer armed（进程保活）
+    armSettledWatchdog(record.id, () => {});
+    await service["closeSubagent"](record, false);
+    expect(killChildSpy).toHaveBeenCalledWith(record.id, "closeChatIdle");
+    expect(hasIdleTimer(record.id)).toBe(false);
+    expect(hasSettledWatchdog(record.id)).toBe(false);
+  });
+
+  it("closeAfterRoundSettled routes through killRecordChildWithEscalation", async () => {
+    const record = makeRecord({ id: "sa-close-round" });
+    await (
+      privateFn(service, "closeAfterRoundSettled") as (this: SubagentService, r: ExecutionRecord) => Promise<void>
+    ).call(service, record);
+    expect(killChildSpy).toHaveBeenCalledWith(record.id, "closeAfterRoundSettled");
+  });
+
+  it("disposeAllRecords applies all recovery surfaces: abort + escalation kill + disarm idle/settled timers", () => {
+    const running = makeRecord({ id: "sa-dispose-run" });
+    const idle = makeRecord({ id: "sa-dispose-idle" });
+    store.register(running);
+    store.register(idle);
+    spawnedMap.set(running.id, new FakeChild());
+    armIdleTimer(idle.id, () => {});
+    armSettledWatchdog(idle.id, () => {});
+
+    const count = service.disposeAllRecords("parent-new");
+
+    expect(count).toBe(2);
+    // 回收面 i：controller.abort
+    expect(running.controller?.signal.aborted).toBe(true);
+    expect(idle.controller?.signal.aborted).toBe(true);
+    // 回收面 ii：kill 收敛到 escalation 入口
+    expect(killChildSpy).toHaveBeenCalledWith(running.id, "disposeAllRecords (parent-new)");
+    expect(killChildSpy).toHaveBeenCalledWith(idle.id, "disposeAllRecords (parent-new)");
+    // 回收面 iii：idle timer + settled watchdog 双 disarm
+    expect(hasIdleTimer(idle.id)).toBe(false);
+    expect(hasSettledWatchdog(idle.id)).toBe(false);
+    // record 终态化
+    expect(running.status).toBe("closed");
+    expect(idle.status).toBe("closed");
+    expect(running.closedReason).toBe("parent-new");
+  });
+});
+
+describe("T2③ hot-path settled watchdog", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+  let pi: MockPi;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    killChildSpy.mockClear();
+    // 模拟真 kill 的语义面（置 killed 标记）：isResumable 判定（无活进程）与失败通知
+    // 放行依赖它——真实 kill 后 close 事件把句柄移出 spawnedChildren，语义相同。
+    killChildSpy.mockImplementation((recordId: string) => {
+      const c = spawnedMap.get(recordId) as FakeChild | undefined;
+      if (c) c.killed = true;
+    });
+    sendPromptCommandMock.mockReset();
+    sendPromptCommandMock.mockImplementation(() => {});
+    ({ agentDir, service, store, pi } = setup());
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    _resetLifecycleState();
+    _resetSettledWatchdogsForTest();
+    spawnedMap.clear();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("arms the settled watchdog after a successful hot-path prompt", async () => {
+    const record = makeRecord({ id: "sa-hot-arm" });
+    store.register(record);
+    spawnedMap.set(record.id, new FakeChild());
+    await deliverChat(service, record, "hello", false);
+    expect(sendPromptCommandMock).toHaveBeenCalledTimes(1);
+    expect(hasSettledWatchdog(record.id)).toBe(true);
+  });
+
+  it("onMidTimeout: kills the child, fails the round, error carries 'settled watchdog' marker and recovery hint", async () => {
+    // fake timers 必须先于 arm 生效（useFakeTimers 不接管已存在的真实 timer）
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const record = makeRecord({ id: "sa-hot-timeout" });
+    store.register(record);
+    spawnedMap.set(record.id, new FakeChild());
+    await deliverChat(service, record, "hello", false);
+    expect(hasSettledWatchdog(record.id)).toBe(true);
+
+    // [D9 两段式] 热路径 prompt 发出后挂中段：静默满中段窗长触发（本测试 mock 了
+    // session-runner，无 stdout pump 驱动事件刷新/交棒，中段静默形态直达）
+    await vi.advanceTimersByTimeAsync(SETTLED_MID_ROUND_NO_PROGRESS_MS + 1);
+
+    // kill 收敛入口被触发（onTimeout 第一步）
+    expect(killChildSpy).toHaveBeenCalledWith(record.id, "settled watchdog (hot path)");
+    // watchdog 到期自清（armedTimers 先删条目再执行回调）
+    expect(hasSettledWatchdog(record.id)).toBe(false);
+    // 该轮失败终态化（chatMode → MF-6 回退 resumable）+ 失败通知
+    expect(record.resumable).toBe(true);
+    expect(record.status).toBe("running");
+    expect(record.result).toContain("settled watchdog");
+    expect(record.result).toContain("Recovery");
+    expect(record.result).toContain("action:'list'");
+    // 失败通知送达（内核直发路径）
+    expect(pi.sendMessage).toHaveBeenCalled();
+    const notifyContent = (pi.sendMessage.mock.calls[0]?.[0] as { content?: string } | undefined)?.content ?? "";
+    expect(notifyContent).toContain("settled watchdog");
+  });
+});
+
+describe("T2⑧ non-EPIPE hot-path failure re-arms idle timer", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let store: RecordStore;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    killChildSpy.mockClear();
+    ({ agentDir, service, store } = setup());
+  });
+
+  afterEach(() => {
+    _resetLifecycleState();
+    _resetSettledWatchdogsForTest();
+    spawnedMap.clear();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("re-arms the idle timer (default duration) and rethrows on non-EPIPE write failure", async () => {
+    const record = makeRecord({ id: "sa-nonpipe" });
+    store.register(record);
+    spawnedMap.set(record.id, new FakeChild());
+    sendPromptCommandMock.mockImplementation(() => {
+      throw new Error("write after end: ERR_STREAM_DESTROYED");
+    });
+
+    await expect(deliverChat(service, record, "hello", false)).rejects.toThrow(/ERR_STREAM_DESTROYED/);
+
+    // 防泄漏前提恢复：入口 disarm 过的 idle timer 被 re-arm（进程不再裸奔）
+    expect(hasIdleTimer(record.id)).toBe(true);
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("idle timer re-armed"),
+      expect.objectContaining({ detail: expect.stringContaining("ERR_STREAM_DESTROYED") }),
+    );
+  });
+
+  it("falls back to DEFAULT idle duration (visible) when record.idleTimeoutMs is invalid", async () => {
+    const record = makeRecord({ id: "sa-nonpipe-bad" });
+    // 直接注入非法值模拟「入口校验前已存在的 record」/ 回归形态：re-arm 首选值非法 →
+    // 降级挂 DEFAULT（防御性兜底可见，不静默不挂）
+    (record as { idleTimeoutMs: number }).idleTimeoutMs = 3_000_000_000;
+    store.register(record);
+    spawnedMap.set(record.id, new FakeChild());
+    sendPromptCommandMock.mockImplementation(() => {
+      throw new Error("ERR_STREAM_DESTROYED");
+    });
+
+    await expect(deliverChat(service, record, "hello", false)).rejects.toThrow(/ERR_STREAM_DESTROYED/);
+    expect(hasIdleTimer(record.id)).toBe(true);
+  });
+});

package/src/execution/__tests__/subagent-service.test.ts

@@ -36,18 +36,18 @@ function makeTmpAgentDir(): string {
 }
 
 function makeModelService(agentDir: string): ModelConfigService {
-  return new ModelConfigService({ agentDir });
+  return new ModelConfigService({ agentDir, cwd: agentDir });
 }
 
 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(),
+    appendEntry: vi.fn((customType: string, data?: unknown) => {}),
+    events: { emit: vi.fn((channel: string, data: unknown) => {}) },
+    sendMessage: vi.fn(() => {}),
   };
 }
 
@@ -61,7 +61,7 @@ describe("SubagentService", () => {
   });
 
   afterEach(() => {
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   // ============================================================
@@ -75,7 +75,7 @@ describe("SubagentService", () => {
 
     it("未 initSession 时 findRecord/cancel 抛 'pi not injected'", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
-      expect(() => service.findRecord("any")).toThrow(/pi not injected/);
+      expect(() => service.queries.findRecord("any")).toThrow(/pi not injected/);
       expect(() => service.cancel("any")).toThrow(/pi not injected/);
     });
 
@@ -83,7 +83,7 @@ describe("SubagentService", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
       // findRecord 现在能过 assertReady,但 record 不存在 → 返回 undefined
-      expect(service.findRecord("missing")).toBeUndefined();
+      expect(service.queries.findRecord("missing")).toBeUndefined();
     });
 
     it("dispose 后 findRecord 抛含 'disposed' 且带恢复指引", () => {
@@ -92,8 +92,8 @@ describe("SubagentService", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
       service.dispose();
-      expect(() => service.findRecord("any")).toThrow(/disposed/);
-      expect(() => service.findRecord("any")).toThrow(/session ended|session_start|new session/i);
+      expect(() => service.queries.findRecord("any")).toThrow(/disposed/);
+      expect(() => service.queries.findRecord("any")).toThrow(/session ended|session_start|new session/i);
     });
 
     it("dispose 幂等(多次调用不抛)", () => {
@@ -113,7 +113,7 @@ describe("SubagentService", () => {
       // revive
       service.initSession({ pi: makePi(), sessionId: "s2" });
       // 现在 assertReady 又通过(findRecord 返回 undefined 而非 disposed)
-      expect(service.findRecord("any")).toBeUndefined();
+      expect(service.queries.findRecord("any")).toBeUndefined();
     });
   });
 
@@ -125,7 +125,7 @@ describe("SubagentService", () => {
     it("findRecord 不存在的 id 返回 undefined", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
-      expect(service.findRecord("nonexistent-id")).toBeUndefined();
+      expect(service.queries.findRecord("nonexistent-id")).toBeUndefined();
     });
 
     it("cancel 不存在的 id 返回 false(不抛错,boolean 契约不变)", () => {
@@ -140,16 +140,13 @@ describe("SubagentService", () => {
   // ============================================================
 
   describe("状态查询", () => {
-    it("listRunning 初始为空数组", () => {
-      const service = new SubagentService({ cwd: agentDir, modelService });
-      service.initSession({ pi: makePi(), sessionId: "s1" });
-      expect(service.listRunning()).toEqual([]);
-    });
+    // [D4] listRunning 已从 Service 删除（零生产调用方）——初始空态语义由
+    // collectRecords 用例与 store 层 listRunning 测试覆盖。
 
     it("collectRecords 返回数组(空 sessions 目录时为空)", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
-      const records = service.collectRecords(100);
+      const records = service.queries.collectRecords(100);
       expect(Array.isArray(records)).toBe(true);
     });
 
@@ -157,7 +154,7 @@ describe("SubagentService", () => {
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
       const listener = vi.fn();
-      const unsubscribe = service.onChange(listener);
+      const unsubscribe = service.queries.onChange(listener);
       expect(typeof unsubscribe).toBe("function");
       expect(() => unsubscribe()).not.toThrow();
     });
@@ -218,6 +215,7 @@ describe("SubagentService", () => {
         agent: "general-purpose",
         model: "test/model",
         mode: "background",
+        slug: "t",
         task: "long task",
         startedAt: 1_000_000,
         rootSessionId: "s1",
@@ -233,8 +231,9 @@ describe("SubagentService", () => {
       const record = createRecord(id, {
         agent: "general-purpose",
         model: "test/model",
-        mode: "sync",
+        mode: "background",
         task: "sync task",
+        slug: "test",
         startedAt: 1_000_000,
         rootSessionId: "s1",
         // sync 不传 controller → controller === undefined
@@ -250,13 +249,14 @@ describe("SubagentService", () => {
         agent: "general-purpose",
         model: "test/model",
         mode: "background",
+        slug: "t",
         task: "done task",
         startedAt: 1_000_000,
         rootSessionId: "s1",
         controller,
       });
       // 直接改 status 模拟终态（不走 CAS——测试不关心状态机，只关心 dispose 的 abort 过滤）
-      record.status = "done";
+      record.status = "closed";
       getStore(service).register(record);
       return record;
     }
@@ -362,7 +362,8 @@ describe("SubagentService", () => {
 
       const service = new SubagentService({ cwd: agentDir, modelService });
       service.initSession({ pi: makePi(), sessionId: "s1" });
-      service.setUiRequestHandler(staleHandler);
+      // [D4-④] setUiRequestHandler 已删——handler 注入走 initSession 参数（唯一入口）
+      service.initSession({ pi: makePi(), sessionId: "s1", uiRequestHandler: staleHandler });
 
       service.dispose();
 
@@ -427,6 +428,7 @@ describe("SubagentService", () => {
       try {
         await service.execute({
           task: "worktree without fork (decoupled)",
+          slug: "test",
           worktree: true,
           fork: false,
           ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
@@ -443,6 +445,7 @@ describe("SubagentService", () => {
       try {
         await service.execute({
           task: "worktree with fork",
+          slug: "test",
           worktree: true,
           fork: true,
           ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
@@ -460,6 +463,7 @@ describe("SubagentService", () => {
       try {
         await service.execute({
           task: "default path",
+          slug: "test",
           worktree: false,
           fork: false,
           ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
@@ -473,7 +477,7 @@ describe("SubagentService", () => {
     // ============================================================
     // create-await 竞态守卫（Phase 2）：create 的 await 窗口内 dispose/cancel
     // 可把 record CAS 成 closed——守卫须主动 cleanup + early-failed 返回，不 kickOff。
-    // 实现约束固化：「赋值 record.worktreeHandle → 终态检查 → kickOffBackground」
+    // 实现约束固化：「赋值 record.worktreeHandle → 终态检查 → 轮次 kick-off」
     // 必须同一同步段（中间禁止 await），本用例即该不变量的回归锚点。
     // ============================================================
     it("守卫：create await 窗口内 dispose 抢先 → cleanup 被调 + early-failed 返回（不 kickOff）", async () => {
@@ -487,12 +491,13 @@ describe("SubagentService", () => {
       }) as Parameters<WorktreeManager["cleanup"]>[0];
       let resolveCreate!: (h: unknown) => void;
       vi.spyOn(wtm, "create").mockImplementation(
-        () => new Promise((r) => { resolveCreate = r; }) as ReturnType<WorktreeManager["create"]>,
+        () => new Promise<unknown>((r) => { resolveCreate = r; }) as ReturnType<WorktreeManager["create"]>,
       );
       const cleanupSpy = vi.spyOn(wtm, "cleanup").mockResolvedValue(undefined);
 
       const execP = service.execute({
         task: "guard test",
+        slug: "test",
         worktree: true,
         fork: false,
         ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
@@ -529,7 +534,7 @@ describe("SubagentService", () => {
   //
   // [未覆盖路径] 需 mock spawn 才能跑完 runSpawn 的路径，本文件约定不 mock spawn
   // （见文件头——execute 集成测试在 execute-nesting.test.ts / run-spawn-integration.test.ts）：
-  //   - finalizeRecord status="done"（sync/background 正常完成 → unregister(done)）
+  //   - finalizeRecord status="closed"（background 正常完成 → unregister(closed)）
   //   - finalizeRecord status="cancelled" 经 runAndFinalize 路径（cancel 抢先 CAS 时
   //     runAndFinalize 侧 tryTransition 失败跳过 finalizeRecord，由 cancelBackground 侧 emit——
   //     本块 cancel 用例覆盖的即此后端 emit）
@@ -572,6 +577,7 @@ describe("SubagentService", () => {
         agent: "general-purpose",
         model: "test/model",
         mode: "background",
+        slug: "t",
         task: "cancel target",
         startedAt: 1_000_000,
         rootSessionId: "s1",
@@ -588,12 +594,13 @@ describe("SubagentService", () => {
 
       const handle = await service.execute({
         task: "wt fail bg",
+        slug: "test",
         worktree: true,
         fork: true,
         ctxModel,
       });
 
-      // worktree create 抛错在 kickOffBackground 之前（execute 同步 catch），返回 background 形状
+      // worktree create 抛错在轮次 kick-off 之前（executeViaEngine 同步 catch），返回 background 形状
       expect(handle.mode).toBe("background");
 
       // createRecordForMode 生成的 subagentId 带 sa- 前缀（sa-<uuid>）
@@ -670,7 +677,7 @@ describe("SubagentService", () => {
       injectRunningBackground(service, "bg-running-1");
       injectRunningBackground(service, "bg-running-2");
       const terminal = injectRunningBackground(service, "bg-done");
-      terminal.status = "done"; // 模拟终态，dispose 不应为其 emit
+      terminal.status = "closed"; // 模拟终态，dispose 不应为其 emit
 
       service.dispose();
 
@@ -704,7 +711,7 @@ describe("ModelConfigService ctxModel 缓存", () => {
     agentDir = makeTmpAgentDir();
   });
   afterEach(() => {
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** 最小 mock registry:空可用列表(ctxModel 路径不需要 lookup)。 */