@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/__tests__/spawn-event-adapter.test.ts

@@ -9,7 +9,7 @@ import {
   deriveSessionFilePath,
   findSessionFileByHeaderId,
   parseSpawnLine,
-} from "../spawn-event-adapter.ts";
+} from "../engine/engines/pi/spawn-event-adapter.ts";
 
 describe("parseSpawnLine", () => {
   describe("空白行", () => {
@@ -150,14 +150,14 @@ describe("findSessionFileByHeaderId", () => {
     fs.writeFileSync(expectedFile, "{}");
     const result = findSessionFileByHeaderId(tmpDir, "sid-456");
     expect(result).toBe(expectedFile);
-    fs.rmSync(tmpDir, { recursive: true });
+    fs.rmSync(tmpDir, { recursive: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("无匹配返回 undefined", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "spawn-adapter-test-"));
     const result = findSessionFileByHeaderId(tmpDir, "nonexistent");
     expect(result).toBeUndefined();
-    fs.rmSync(tmpDir, { recursive: true });
+    fs.rmSync(tmpDir, { recursive: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("目录不存在返回 undefined（不抛错）", () => {

package/src/execution/__tests__/spawn-worktree-guidance.test.ts

@@ -71,7 +71,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, content: string) => {
     captured.content = content;
     const safeName = agent.replace(/[^\w.-]+/g, "_");
@@ -83,7 +83,7 @@ vi.mock("../temp-prompt.ts", () => ({
 import { spawn } from "node:child_process";
 
 import { createRecord } from "../execution-record.ts";
-import { runSpawn, type RunOptions, type SessionRunnerContext } from "../session-runner.ts";
+import { runSpawn, type RunOptions, type SessionRunnerContext } from "../engine/engines/pi/session-runner.ts";
 
 const mockSpawn = vi.mocked(spawn);
 
@@ -117,8 +117,9 @@ function makeRecord() {
   return createRecord("wt-guidance-1", {
     agent: "general-purpose",
     model: "test/model",
-    mode: "sync",
+    mode: "background",
     task: "test task",
+    slug: "test",
     startedAt: Date.now(),
     rootSessionId: "s1",
     parentRecordId: undefined,
@@ -128,7 +129,7 @@ function makeRecord() {
 
 function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
   return {
-    resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
+    resolved: { model: { provider: "test", id: "model", name: "Model", reasoning: false }, thinkingLevel: undefined },
     agentConfig: undefined,
     appendSystemPrompt: undefined,
     skillPath: undefined,

package/src/execution/__tests__/spawned-children.test.ts

@@ -29,7 +29,7 @@ vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
 import type { EnginePort } from "../engine/port.ts";
 import { clearEngines, getEngine, registerEngine } from "../engine/registry.ts";
-import { getChildByRecord, killAllSpawnedChildren, spawnedChildren } from "../session-runner.ts";
+import { getChildByRecord, killAllSpawnedChildren, spawnedChildren } from "../engine/engines/pi/session-runner.ts";
 
 /**
  * 假 child：只关心 killed 标记 + kill 调用（killAllSpawnedChildren 遍历用）。
@@ -63,6 +63,7 @@ function makeDisposingEngine(
       resume: "unsupported",
       interrupt: "kill-only",
       permissionMode: "fixed",
+      maxTurns: false,
     }),
     probe: () =>
       Promise.resolve({ ok: true, engineVersion: "0.0.0-test", checks: [{ name: "stub", ok: true }] }),

package/src/execution/__tests__/start-collect-guard.test.ts

@@ -0,0 +1,255 @@
+// src/execution/__tests__/start-collect-guard.test.ts
+//
+// startHandler 的 collect 语义（subagent-sync-collect U1 foundation）：
+//   1. E4 校验（设计 §3.1.5）：conversation:true + collect:"sync" → immediate throw，
+//      不产生半启动 record（execute 零调用）；文案指引「sync 仅支持 one-shot，
+//      去掉 conversation 或 collect」；
+//   2. 合法组合放行：collect 透传 service.execute（ExecuteOptions.collect）；
+//   3. start 响应 collect 段（设计 §3.1.1）：仅 resolved=sync 附段（async 响应字节
+//      零变化，G3）；pendingSyncCount = 未闭合批 sync 成员数（collectMode=sync 且无
+//      batchFinalized；U2 偏差#4 接线后 record 落 collectMode，枚举天然含本条，无 +1）。
+//
+// stub SubagentService 仅实现 handler 触达的方法子集（subagent-actions-core.test.ts
+// 同款形态）；真实 service 行为归属 subagent-service 各自测试。
+
+import { describe, expect, it, vi, type Mock } from "vitest";
+
+import { startHandler } from "../subagent-actions-core.ts";
+// SubagentService 的权威源是 subagent-service.ts（types.ts 只有 record/tool 契约）
+import type { SubagentService } from "../subagent-service.ts";
+import type { StatusFilter } from "../record-store.ts";
+import type {
+  ExecutionHandle,
+  SubagentRecord,
+  SubagentToolDetails,
+} from "../types.ts";
+
+function makeDetails(): SubagentToolDetails {
+  return {
+    status: "running",
+    mode: "background",
+    agent: "/home/u/agents/worker.md",
+    model: "prov/m1",
+    thinkingLevel: undefined,
+    slug: "src-slug",
+    turns: 0,
+    totalTokens: 0,
+    elapsedSeconds: 0,
+    eventLog: [],
+    displayItems: [],
+    result: undefined,
+    error: undefined,
+  } as SubagentToolDetails;
+}
+
+function makeHandle(): ExecutionHandle {
+  return { mode: "background", subagentId: "sa-new", sessionFile: undefined, details: makeDetails() };
+}
+
+/** collectRecords stub 数据行（只含 pendingSyncCount 口径判读所需字段）。 */
+function makeRec(over: Partial<SubagentRecord> = {}): SubagentRecord {
+  return {
+    id: "sa-1",
+    agent: "/home/u/agents/worker.md",
+    task: "t",
+    slug: "worker",
+    status: "running",
+    mode: "background",
+    startedAt: 1000,
+    rootSessionId: "root-A",
+    parentRecordId: undefined,
+    depth: 0,
+    endedAt: undefined,
+    turns: 1,
+    totalTokens: 42,
+    model: "prov/m1",
+    thinkingLevel: undefined,
+    eventLog: [],
+    displayItems: [],
+    ...over,
+  } as SubagentRecord;
+}
+
+// Mock<T> 具名签名 + Omit 类原生同名成员：ReturnType<typeof vi.fn>
+// （= Mock<Procedure | Constructable>）与类方法签名交叉会收窄 never
+type ServiceStub = Omit<SubagentService, "execute" | "collectRecords" | "getCollectSyncDefault"> & {
+  // 带首参形态：断言消费 execute.mock.calls[0][0]（ExecuteOptions），零参签名为空元组取不到
+  execute: Mock<(opts: Record<string, unknown>) => Promise<SubagentRecord>>;
+  collectRecords: Mock<(limit: number, statusFilter?: StatusFilter) => SubagentRecord[]>;
+  getCollectSyncDefault: Mock<() => "async" | "sync">;
+};
+
+/** startHandler 的测试包装：stub → SubagentService 断言收口一处（类私有成员不可结构模拟）。 */
+function sh(svc: ServiceStub, input: Record<string, unknown>, signal?: AbortSignal) {
+  return startHandler(
+    svc as unknown as SubagentService,
+    input as Parameters<typeof startHandler>[1],
+    signal ?? undefined,
+  );
+}
+
+function makeService(
+  collectRecordsReturn: SubagentRecord[] = [],
+  collectSyncDefault: "async" | "sync" = "async",
+): ServiceStub {
+  const execute = vi.fn(async (_opts: Record<string, unknown>) => makeHandle());
+  const collectRecords = vi.fn(() => collectRecordsReturn);
+  const getCollectSyncDefault = vi.fn(() => collectSyncDefault);
+  // [D4-① 适配] countPendingSyncRecords 经查询面聚合读 collectRecords（dev 重构后
+  // service.collectRecords 收窄 private，public 出口 = service.queries.collectRecords）。
+  return {
+    execute,
+    queries: { collectRecords },
+    collectRecords,
+    getCollectSyncDefault,
+  } as unknown as ServiceStub;
+}
+
+const BASE_INPUT = { task: "do things", slug: "do-things" };
+
+// ============================================================
+// E4：conversation + collect:"sync" 即拒
+// ============================================================
+
+describe("startHandler E4 guard (conversation + collect:sync)", () => {
+  it("throws immediately and never calls execute (不产生半启动 record)", async () => {
+    const service = makeService();
+    await expect(
+      sh(service, { ...BASE_INPUT, conversation: true, collect: "sync" }, undefined),
+    ).rejects.toThrow();
+    expect(service.execute).not.toHaveBeenCalled();
+  });
+
+  it("error copy carries the design guidance verbatim (文案锚定)", async () => {
+    const service = makeService();
+    const err = await sh(service,
+      { ...BASE_INPUT, conversation: true, collect: "sync" },
+      undefined,
+    ).catch((e: unknown) => e as Error);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toBe(
+      'collect:"sync" only supports one-shot subagents — it cannot be combined with conversation:true. ' +
+      'Remove either conversation or collect (use collect:"async", or omit it, for conversational subagents).',
+    );
+  });
+
+  it("allows conversation:true + collect:async (async 语义与 conversation 正交)", async () => {
+    const service = makeService();
+    const result = await sh(service,
+      { ...BASE_INPUT, conversation: true, collect: "async" },
+      undefined,
+    );
+    expect(result.subagentId).toBe("sa-new");
+    expect(service.execute).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows collect:sync alone (one-shot sync 是合法主场景)", async () => {
+    const service = makeService();
+    const result = await sh(service, { ...BASE_INPUT, collect: "sync" }, undefined);
+    expect(result.subagentId).toBe("sa-new");
+    expect(service.execute).toHaveBeenCalledTimes(1);
+  });
+
+  it("E4 also blocks conversation when config default is sync (偏差#3 接线：resolved 含 config 默认)", async () => {
+    const service = makeService([], "sync");
+    await expect(
+      sh(service, { ...BASE_INPUT, conversation: true }, undefined),
+    ).rejects.toThrow('collect:"sync" only supports one-shot subagents');
+    expect(service.execute).not.toHaveBeenCalled();
+  });
+
+  it("config default=sync applies when collect omitted (缺省读真实 config，U2 偏差#3)", async () => {
+    const service = makeService([], "sync");
+    const result = await sh(service, { ...BASE_INPUT }, undefined);
+    expect(result.response.collect).toBeDefined();
+    expect(service.getCollectSyncDefault).toHaveBeenCalledTimes(1);
+  });
+
+  it("reads config default via service accessor when collect omitted (async 默认零附段)", async () => {
+    const service = makeService([], "async");
+    const result = await sh(service, { ...BASE_INPUT }, undefined);
+    expect(result.response.collect).toBeUndefined();
+    expect(service.getCollectSyncDefault).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ============================================================
+// collect 透传 + 响应 collect 段
+// ============================================================
+
+describe("startHandler collect forwarding + response collect segment", () => {
+  it("forwards collect to service.execute via ExecuteOptions.collect", async () => {
+    const service = makeService();
+    await sh(service, { ...BASE_INPUT, collect: "sync" }, undefined);
+    const opts = service.execute.mock.calls[0]?.[0] as { collect?: string };
+    expect(opts.collect).toBe("sync");
+  });
+
+  it("omits collect in ExecuteOptions when not provided (resolved≠sync 时保持 undefined，async 缺省语义)", async () => {
+    const service = makeService();
+    await sh(service, { ...BASE_INPUT }, undefined);
+    const opts = service.execute.mock.calls[0]?.[0] as { collect?: string };
+    expect(opts.collect).toBeUndefined();
+  });
+
+  it("B1：config default=sync + 省略 collect → execute 收 collect:\"sync\"（缺省解析作用于 record 本体）", async () => {
+    // 修复前：execute 收原始 input.collect=undefined → createRecordForMode 只认
+    // ==="sync" → record 走 async 逐条通知而响应声称已入批（设计 §3.1.3/types.ts:689
+    // 承诺「缺省 = config 默认」作用于 record）。修复后 resolved=sync 落值。
+    const service = makeService([], "sync");
+    await sh(service, { ...BASE_INPUT }, undefined);
+    const opts = service.execute.mock.calls[0]?.[0] as { collect?: string };
+    expect(opts.collect).toBe("sync");
+  });
+
+  it("B1：config default=sync 时显式 collect:\"async\" 优先（execute 收 \"async\"）", async () => {
+    const service = makeService([], "sync");
+    await sh(service, { ...BASE_INPUT, collect: "async" }, undefined);
+    const opts = service.execute.mock.calls[0]?.[0] as { collect?: string };
+    expect(opts.collect).toBe("async");
+  });
+
+  it("attaches collect segment counting this very record from the enumeration (U2 偏差#4：无 +1 补偿)", async () => {
+    // 本条 record（id=sa-new）已由 createRecordForMode 落 collectMode 入枚举：
+    // stub 枚举返回本条 + 另一未闭合 sync → count=2（无 +1 补偿即含本条）
+    const service = makeService([
+      makeRec({ id: "sa-new", collectMode: "sync" }),
+      makeRec({ id: "sa-other", collectMode: "sync", status: "running" }),
+      makeRec({ id: "sa-gone", collectMode: "sync", batchFinalized: true }),
+    ]);
+    const result = await sh(service, { ...BASE_INPUT, collect: "sync" }, undefined);
+    expect(result.response.collect).toEqual({ mode: "sync", pendingSyncCount: 2 });
+  });
+
+  it("reports the enumeration verbatim when no sync records exist yet (如实反映，无补偿)", async () => {
+    const service = makeService([]);
+    const result = await sh(service, { ...BASE_INPUT, collect: "sync" }, undefined);
+    expect(result.response.collect).toEqual({ mode: "sync", pendingSyncCount: 0 });
+  });
+
+  it("counts pending unmarked sync members from the enumeration (跨轮续累口径)", async () => {
+    const service = makeService([
+      makeRec({ id: "sa-1", collectMode: "sync" }), // 未闭合（无 batchFinalized）→ 计入
+      makeRec({ id: "sa-2", collectMode: "sync", batchFinalized: true }), // 已离场 → 排除
+      makeRec({ id: "sa-3" }), // async → 排除
+      makeRec({ id: "sa-4", collectMode: "sync", batchFinalized: false }), // 显式 false → 计入
+    ]);
+    const result = await sh(service, { ...BASE_INPUT, collect: "sync" }, undefined);
+    expect(result.response.collect).toEqual({ mode: "sync", pendingSyncCount: 2 });
+  });
+
+  it("omits the collect segment for async starts (G3: async 响应字节零变化)", async () => {
+    for (const input of [{ ...BASE_INPUT }, { ...BASE_INPUT, collect: "async" as const }]) {
+      const service = makeService();
+      const result = await sh(service, input, undefined);
+      expect(result.response.collect).toBeUndefined();
+      // G3 字节锚：response 其余字段与既有形态全等
+      expect(result.response).toEqual({
+        status: "running",
+        mode: "background",
+        message: result.response.message,
+        notifyContract: "ledger+at-least-once",
+      });
+    }
+  });
+});

package/src/execution/__tests__/start-sync-model-guard.test.ts

@@ -30,14 +30,14 @@ vi.mock("node:child_process", async () => {
 });
 
 // buildSpawnArgs 包装为 spy（保留真实实现）——「非全等拒单不触达 spawn 参数组装」的承重断言。
-vi.mock("../session-runner.ts", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../session-runner.ts")>();
+vi.mock("../engine/engines/pi/session-runner.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../engine/engines/pi/session-runner.ts")>();
   return { ...actual, buildSpawnArgs: vi.fn(actual.buildSpawnArgs) };
 });
 
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
-import { buildSpawnArgs } from "../session-runner.ts";
+import { buildSpawnArgs } from "../engine/engines/pi/session-runner.ts";
 import type { PiLike } from "../subagent-service.ts";
 import { SubagentService } from "../subagent-service.ts";
 
@@ -93,7 +93,7 @@ describe("start 同步期裁决（U1 验收 3：非全等 → isError 且无 spa
 
   afterEach(() => {
     vi.restoreAllMocks();
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("小写变体入参 → execute 同步 reject（问句式报错），buildSpawnArgs/spawn/appendEntry 均未被调", async () => {
@@ -128,7 +128,7 @@ describe("start 同步期裁决（U1 验收 3：非全等 → isError 且无 spa
   });
 
   it("全等入参通过裁决（reject 不发生，放行链路触达 spawn 参数组装）——守卫零误伤对照", async () => {
-    // 放行路径会进入 kickOffBackground（detached）；execute resolve 即视为裁决放行。
+    // 放行路径会进入轮次 kick-off（detached）；execute resolve 即视为裁决放行。
     // spawn 本身由 FakeChild 缺失抛错收口——本断言只关心「越过了同步裁决」：
     // execute 不 reject，且 buildSpawnArgs 已被调（或即将被调的 record 已创建）。
     const promise = service.execute({

package/src/execution/__tests__/stdin-writer.test.ts

@@ -33,7 +33,7 @@ vi.mock("../../core/logger.ts", () => ({
   getLogger: () => loggerMock,
 }));
 
-import { respond, sendGetStateCommand, sendPromptCommand } from "../stdin-writer.ts";
+import { respond, sendGetStateCommand, sendPromptCommand } from "../engine/engines/pi/stdin-writer.ts";
 
 // ── helpers ──
 
@@ -362,8 +362,10 @@ describe("sendGetStateCommand", () => {
 describe("writeStdinLine 背压 — write 返回 false 时 warn 不 throw", () => {
   it("child.stdin.write 返回 false → warn 一次，函数正常返回（不 throw）", () => {
     // 构造 write 永远返回 false 的假 stream（模拟内核缓冲满/HWM 到达）
+    // 保留 vi.fn 引用（经 PassThrough 视图后 write 的 mock 面不可达）
+    const fakeWrite = vi.fn((_chunk: unknown) => false);
     const fakeStdin = {
-      write: vi.fn(() => false),
+      write: fakeWrite,
       destroyed: false,
     } as unknown as PassThrough;
     const child = { stdin: fakeStdin } as unknown as ChildProcess;
@@ -371,8 +373,8 @@ describe("writeStdinLine 背压 — write 返回 false 时 warn 不 throw", () =
     expect(() => respond(child, "req-backpressure", { value: "x" })).not.toThrow();
 
     // write 被调一次（写入 command 行）
-    expect(fakeStdin.write).toHaveBeenCalledTimes(1);
-    const writtenArg = fakeStdin.write.mock.calls[0]?.[0] as string;
+    expect(fakeWrite).toHaveBeenCalledTimes(1);
+    const writtenArg = fakeWrite.mock.calls[0]![0] as string;
     expect(writtenArg).toContain("extension_ui_response");
     expect(writtenArg).toContain("req-backpressure");
     expect(writtenArg.endsWith("\n")).toBe(true);

package/src/execution/__tests__/stream-sink-retirement.test.ts

@@ -3,7 +3,7 @@
 // widget 私货通道退役步骤 2（E 方案 §6.3）测试，两层：
 //   判定层：createBackgroundStream 真实函数（vi.importActual 绕过文件级 mock）——
 //   gui+relay 激活不创建；tui / relay 未激活 / headless 原样创建；sink=null 恒降级。
-//   接线层：SubagentService.execute（background → kickOffBackground 同步段）透传
+//   接线层：SubagentService.execute（background → kickOffChatRound 同步段）透传
 //   mode/streamSink 给工厂——mode 传错 = 判定失效，故接线面必须锁定。
 //
 // spawn 层 mock（FakeChild），与 nested-visibility-env-propagation.test.ts 同模式。
@@ -103,7 +103,7 @@ vi.mock("../manifest-store.ts", () => {
   return { ManifestStore: vi.fn(function (_recordsDir: string) { return new FakeManifestStore(); }) };
 });
 
-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` };
@@ -156,7 +156,7 @@ const ctxModel: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: fals
 
 function setupService(mode: ExtensionMode | undefined, sessionId = "retire-it"): SubagentService {
   const agentDir = "/tmp/stream-retire-it";
-  const modelService = new ModelConfigService({ agentDir });
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
   modelService.initModel({
     modelRegistry: makeEmptyRegistry(),
     sessionId,
@@ -176,7 +176,7 @@ function setupService(mode: ExtensionMode | undefined, sessionId = "retire-it"):
   return service;
 }
 
-/** 等 kickOffBackground 的 detached runAndFinalize 走到 spawn（stream 创建先于此）。 */
+/** 等 kickOffChatRound 的 detached 轮次执行走到 spawn（stream 创建先于此）。 */
 async function waitForSpawnCall(): Promise<void> {
   const baseline = mockSpawn.mock.calls.length;
   const deadline = Date.now() + 2000;
@@ -187,7 +187,7 @@ async function waitForSpawnCall(): Promise<void> {
 }
 
 async function executeBackground(service: SubagentService): Promise<void> {
-  await service.execute({ task: "retire test", ctxModel });
+  await service.execute({ task: "retire test", slug: "test", ctxModel });
   await waitForSpawnCall();
   // 推进 detached runSpawn 收尾（FakeChild close），防句柄悬挂干扰后续用例
   lastSpawnedChild().emit("close", 0);
@@ -234,7 +234,7 @@ describe("退役步骤 2 判定层：createBackgroundStream", () => {
 
 // ── 接线层：service → 工厂的参数透传（mode 传错 = 判定失效）──
 
-describe("退役步骤 2 接线层：kickOffBackground 透传 mode/sink 给工厂", () => {
+describe("退役步骤 2 接线层：kickOffChatRound 透传 mode/sink 给工厂", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     for (const key of RELAY_ENV_KEYS) delete process.env[key];

package/src/execution/__tests__/subagent-actions-core.test.ts

@@ -42,9 +42,9 @@ import type {
   ExecutionHandle,
   ExecutionRecord,
   SubagentRecord,
-  SubagentService,
   SubagentToolDetails,
 } from "../types.ts";
+import type { SubagentService } from "../subagent-service.ts";
 
 // ── 时钟固定（duration 快照确定性，见文件头）──
 const FROZEN_NOW = 1788189209000;
@@ -132,17 +132,41 @@ function makeRec(over: Partial<SubagentRecord> = {}): SubagentRecord {
 }
 
 function makeService(over: Record<string, unknown> = {}): SubagentService {
-  return {
+  // 聚合面形态对齐 subagent-service.ts D4：queries（读模型）与 chatActions（对话
+  // action 面）分组挂载，mock 按同构 key 装配（over 仍传平铺 key，最小化快照用例改动）。
+  const m = {
     execute: vi.fn(),
-    findRecord: vi.fn(() => undefined),
     cancel: vi.fn(() => false),
+    findRecord: vi.fn(() => undefined),
     collectRecords: vi.fn(() => [] as SubagentRecord[]),
     getFullRecord: vi.fn(() => undefined as SubagentRecord | undefined),
     lookupRecordAnyState: vi.fn(() => undefined as SubagentRecord | undefined),
     getRecordForAction: vi.fn(),
     closeSubagent: vi.fn(),
-    deliverMessage: vi.fn(),
+    deliverChatMessage: vi.fn(),
+    // [U2] startHandler 缺省 collect 解析读真实 config（偏差#3 接线）：stub 缺省 async
+    //（本文件不测 collect 语义，专项见 start-collect-guard.test.ts）。
+    getCollectSyncDefault: vi.fn(() => "async" as const),
     ...over,
+  };
+  return {
+    execute: m.execute,
+    cancel: m.cancel,
+    // [U2 偏差#3 接线] startHandler 经平铺访问器读 config 缺省 collect（真实 service
+    // 为平铺方法 subagent-service.ts:1786，非 queries 聚合面成员），stub 须同构挂载。
+    getCollectSyncDefault: m.getCollectSyncDefault,
+    queries: {
+      findRecord: m.findRecord,
+      lookupRecordAnyState: m.lookupRecordAnyState,
+      collectRecords: m.collectRecords,
+      getFullRecord: m.getFullRecord,
+      onChange: vi.fn(() => () => {}),
+    },
+    chatActions: {
+      getRecordForAction: m.getRecordForAction,
+      closeSubagent: m.closeSubagent,
+      deliverChatMessage: m.deliverChatMessage,
+    },
   } as unknown as SubagentService;
 }
 
@@ -290,7 +314,7 @@ describe("⛔4 startHandler（校验 + 启动，快照 = pi-sw 实测）", () =>
   });
 
   it("正常启动 → 领域对象全字段 + execute 参数（task/slug trim、拍平透传、ctxModel/signal）", async () => {
-    const execute = vi.fn(async (): Promise<ExecutionHandle> => ({
+    const execute = vi.fn(async (_opts: { task: string; slug?: string; agent?: string }): Promise<ExecutionHandle> => ({
       mode: "background",
       subagentId: "bg-9-abc",
       sessionFile: "sess-9.jsonl",
@@ -334,7 +358,7 @@ describe("⛔4 startHandler（校验 + 启动，快照 = pi-sw 实测）", () =>
       },
     });
     expect(execute).toHaveBeenCalledTimes(1);
-    expect(execute.mock.calls[0][0]).toEqual({
+    expect(execute.mock.calls[0]![0]).toEqual({
       task: "long task", // trim 生效
       slug: "long-running",
       agent: "/x/agent.md",
@@ -489,6 +513,8 @@ describe("⛔4 cancelHandler（守卫 + 归属判定 + CAS 失败映射，快照
     expect(
       await errOf(() =>
         cancelHandler(
+          // "sync" 是历史已裁撤值（ExecutionMode 现仅 "background"）——经 as never
+          // 注入非法值专测守卫分支，运行时守卫按 !== "background" 拦截
           makeService({ findRecord: vi.fn(() => makeRec({ id: "bg-1", mode: "sync" as never })) }),
           { subagentId: "bg-1" },
         ),
@@ -587,11 +613,11 @@ describe("⛔4 messageHandler（守卫 + upgrade + 投递，快照 = pi-sw 实
     });
   });
 
-  it("chatMode record → deliverMessage(text trim + interrupt) + 领域对象", async () => {
-    const deliverMessage = vi.fn(async () => {});
+  it("chatMode record → deliverChatMessage(text trim + interrupt) + 领域对象", async () => {
+    const deliverChatMessage = vi.fn(async () => {});
     const chatRecord = makeExecRecord({ id: "bg-1", chatMode: true, slug: "src-slug" });
     const r = await messageHandler(
-      makeService({ getRecordForAction: vi.fn(() => chatRecord), deliverMessage }),
+      makeService({ getRecordForAction: vi.fn(() => chatRecord), deliverChatMessage }),
       { subagentId: "bg-1", text: "  go on  ", interrupt: true },
     );
     expect(r).toEqual({
@@ -600,18 +626,18 @@ describe("⛔4 messageHandler（守卫 + upgrade + 投递，快照 = pi-sw 实
       slug: "src-slug",
       response: { delivered: true },
     });
-    expect(deliverMessage).toHaveBeenCalledWith(chatRecord, "go on", true);
+    expect(deliverChatMessage).toHaveBeenCalledWith(chatRecord, "go on", true);
   });
 
   it("one-shot upgrade：非 chatMode running record 收 message → 置位 chatMode 后投递", async () => {
-    const deliverMessage = vi.fn(async () => {});
+    const deliverChatMessage = vi.fn(async () => {});
     const upgradeRec = makeExecRecord({ id: "bg-1", chatMode: false, status: "running" });
     await messageHandler(
-      makeService({ getRecordForAction: vi.fn(() => upgradeRec), deliverMessage }),
+      makeService({ getRecordForAction: vi.fn(() => upgradeRec), deliverChatMessage }),
       { subagentId: "bg-1", text: "hi" },
     );
     expect(upgradeRec.chatMode).toBe(true);
-    expect(deliverMessage).toHaveBeenCalledWith(upgradeRec, "hi", false);
+    expect(deliverChatMessage).toHaveBeenCalledWith(upgradeRec, "hi", false);
   });
 
   it("getRecordForAction 拒绝 + 无终态快照 → 原错误透传（文案最准原则）", async () => {
@@ -774,7 +800,7 @@ describe("⛔4 closeHandler（force 语义透传，快照 = pi-sw 实测）", ()
 // forkFromHandler（守卫链 1–6）
 // ============================================================
 describe("⛔4 forkFromHandler（守卫链 + slug 派生 + prompt 包装，快照 = pi-sw 实测）", () => {
-  function makeForkService(source: SubagentRecord | undefined, execute = vi.fn(async (): Promise<ExecutionHandle> => ({
+  function makeForkService(source: SubagentRecord | undefined, execute = vi.fn(async (_opts: { task: string; slug?: string; agent?: string }): Promise<ExecutionHandle> => ({
     mode: "background",
     subagentId: "bg-new-1",
     sessionFile: "sess-new.jsonl",
@@ -899,7 +925,7 @@ describe("⛔4 forkFromHandler（守卫链 + slug 派生 + prompt 包装，快
   });
 
   it("正常：显式 prompt → wrapForkFromPrompt 包装 + slug 派生 'src-slug-resumed' + execute 参数", async () => {
-    const execute = vi.fn(async (): Promise<ExecutionHandle> => ({
+    const execute = vi.fn(async (_opts: { task: string; slug?: string; agent?: string }): Promise<ExecutionHandle> => ({
       mode: "background",
       subagentId: "bg-new-1",
       sessionFile: "sess-new.jsonl",
@@ -928,7 +954,7 @@ describe("⛔4 forkFromHandler（守卫链 + slug 派生 + prompt 包装，快
   });
 
   it("无 prompt → FORK_FROM_DEFAULT_PROMPT 逐字", async () => {
-    const execute = vi.fn(async (): Promise<ExecutionHandle> => ({
+    const execute = vi.fn(async (_opts: { task: string; slug?: string; agent?: string }): Promise<ExecutionHandle> => ({
       mode: "background",
       subagentId: "bg-new-2",
       sessionFile: "sess-new-2.jsonl",
@@ -955,7 +981,7 @@ describe("⛔4 forkFromHandler（守卫链 + slug 派生 + prompt 包装，快
   });
 
   it("slug 派生：34 字符源 slug 截 27 + '-resumed'；fallback 链 slug||agent||'resumed'", async () => {
-    const execute34 = vi.fn(async (): Promise<ExecutionHandle> => ({
+    const execute34 = vi.fn(async (_opts: { task: string; slug?: string; agent?: string }): Promise<ExecutionHandle> => ({
       mode: "background",
       subagentId: "bg-new-3",
       sessionFile: undefined,
@@ -965,9 +991,9 @@ describe("⛔4 forkFromHandler（守卫链 + slug 派生 + prompt 包装，快
       makeForkService(makeRec({ id: "bg-1", slug: "s".repeat(34), sessionFile: "sess-1.jsonl" }), execute34),
       { sourceSubagentId: "bg-1", prompt: "p" },
     );
-    expect(execute34.mock.calls[0][0].slug).toBe(`${"s".repeat(27)}-resumed`);
+    expect(execute34.mock.calls[0]![0].slug).toBe(`${"s".repeat(27)}-resumed`);
 
-    const executeAgent = vi.fn(async (): Promise<ExecutionHandle> => ({
+    const executeAgent = vi.fn(async (_opts: { task: string; slug?: string; agent?: string }): Promise<ExecutionHandle> => ({
       mode: "background",
       subagentId: "bg-new-4",
       sessionFile: undefined,
@@ -980,9 +1006,9 @@ describe("⛔4 forkFromHandler（守卫链 + slug 派生 + prompt 包装，快
       ),
       { sourceSubagentId: "bg-1", prompt: "p" },
     );
-    expect(executeAgent.mock.calls[0][0].slug).toBe("/home/u/agents/helper.md-resumed");
+    expect(executeAgent.mock.calls[0]![0].slug).toBe("/home/u/agents/helper.md-resumed");
 
-    const executeResumed = vi.fn(async (): Promise<ExecutionHandle> => ({
+    const executeResumed = vi.fn(async (_opts: { task: string; slug?: string; agent?: string }): Promise<ExecutionHandle> => ({
       mode: "background",
       subagentId: "bg-new-5",
       sessionFile: undefined,
@@ -992,6 +1018,6 @@ describe("⛔4 forkFromHandler（守卫链 + slug 派生 + prompt 包装，快
       makeForkService(makeRec({ id: "bg-1", slug: "", agent: "", sessionFile: "sess-1.jsonl" }), executeResumed),
       { sourceSubagentId: "bg-1", prompt: "p" },
     );
-    expect(executeResumed.mock.calls[0][0].slug).toBe("resumed-resumed");
+    expect(executeResumed.mock.calls[0]![0].slug).toBe("resumed-resumed");
   });
 });