@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/engine/engines/pi/__tests__/pi-engine.test.ts

@@ -1,13 +1,17 @@
 // src/execution/engine/engines/pi/__tests__/pi-engine.test.ts
 //
-// PiEngine 适配层测试（P1 回填）：capabilities 链路接通口径（D3）、run 委托与
-// 中立声明→ExecuteOptions 映射、interact 三 action 直通、read 三级降级、probe 形状
-// （C1：ok=false 时 error.recovery 非空）。fake PiEngineService 注入，不 spawn 真进程。
+// PiEngine 引擎边界测试（D2 后形态）：capabilities 链路接通口径（D3）、run 双分支
+//（chat ticket 交接 / workflow executeAndAwait 委托）与中立声明→ExecuteOptions 映射、
+// interact message 原生协议（stdin 直写 + 冷路径续轮回调；D2 协议知识下沉）、close/cancel
+// 直通、read 三级降级、probe 形状（C1）。fake PiEngineService 注入，不 spawn 真进程。
 
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
+import type { ChildProcess } from "node:child_process";
+import { PassThrough } from "node:stream";
+
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { createRecord } from "../../../../execution-record.ts";
@@ -15,11 +19,15 @@ import type { ExecuteOptions, SubagentRecord } from "../../../../types.ts";
 import { IDENTITY_CUSTOM_TYPE } from "../../../../session-reconstructor.ts";
 import { SubagentStream } from "../../../../stream-sink.ts";
 import type { RunContext } from "../../../port.ts";
-import type { AgentTaskSpec, EngineHandle } from "../../../types.ts";
+import type { AgentEvent, EngineHandle } from "../../../types.ts";
+import type { AgentCallOpts } from "../../../../../orchestration/models/types.ts";
+import { spawnedChildren } from "../session-runner.ts";
+import { resetAllEpipeFailures } from "../stdin-writer.ts";
 import {
   PI_ADAPTER_VERSION,
   PI_ENGINE_ID,
   PiEngine,
+  type ChatRoundTicket,
   type PiEngineService,
 } from "../pi-engine.ts";
 
@@ -28,12 +36,13 @@ import {
 interface ServiceCalls {
   executeOpts?: ExecuteOptions;
   signal?: AbortSignal;
-  onEvent?: (event: unknown) => void;
+  onEvent?: (event: AgentEvent) => void;
   stream?: unknown;
-  deliverMessage?: { recordId: string; text: string; interrupt: boolean };
+  resumeChatRound?: { recordId: string; text: string };
   close?: { recordId: string; force: boolean };
   cancelId?: string;
   getRecordId?: string;
+  reportedTransitionIds?: string[];
 }
 
 /** 构造最小完整 SubagentRecord（collectRecords 返回项——resolveRecordId 只读 id/sessionFile）。 */
@@ -66,9 +75,9 @@ function makeFakeService(overrides?: {
   recordsById?: Map<string, ReturnType<typeof createRecord>>;
   listed?: Array<{ id: string; sessionFile?: string }>;
   cancelResult?: boolean;
-  deliverReject?: Error;
+  resumeReject?: Error;
 }): { service: PiEngineService; calls: ServiceCalls } {
-  const calls: ServiceCalls = {};
+  const calls: ServiceCalls = { reportedTransitionIds: [] };
   const record = createRecord("sa-fake", {
     agent: "reviewer",
     model: "p/m",
@@ -106,9 +115,12 @@ function makeFakeService(overrides?: {
       }
       return record;
     },
-    deliverMessage: async (rec, text, interrupt) => {
-      calls.deliverMessage = { recordId: rec.id, text, interrupt };
-      if (overrides?.deliverReject) throw overrides.deliverReject;
+    resumeChatRound: (rec, text) => {
+      calls.resumeChatRound = { recordId: rec.id, text };
+      if (overrides?.resumeReject) throw overrides.resumeReject;
+    },
+    reportRecordTransition: (rec) => {
+      calls.reportedTransitionIds?.push(rec.id);
     },
     closeSubagent: async (rec, force) => {
       calls.close = { recordId: rec.id, force };
@@ -123,15 +135,16 @@ function makeFakeService(overrides?: {
   return { service, calls };
 }
 
-/** 全字段任务声明（覆盖全部泛化点）。 */
-function makeSpec(): AgentTaskSpec {
+/** 全字段任务声明（D6 合流形状 AgentCallOpts，覆盖全部直出映射点）。 */
+function makeSpec(): AgentCallOpts {
   return {
-    task: "do the thing",
-    slug: "do-thing",
+    prompt: "do the thing",
+    description: "do-thing",
     agent: "reviewer",
     model: "zai-coding-cn/glm-5.2",
-    effort: "high",
-    persona: { skillPath: "/skills/r/SKILL.md", appendSystemPrompt: ["extra"] },
+    thinkingLevel: "high",
+    skillPath: "/skills/r/SKILL.md",
+    appendSystemPrompt: ["extra"],
     schema: { type: "object", properties: { ok: { type: "boolean" } } },
     maxTurns: 5,
     graceTurns: 2,
@@ -168,6 +181,7 @@ describe("PiEngine.capabilities（D3 链路接通口径）", () => {
       resume: "native", // 同进程 idle 复用 + --session 冷续写
       interrupt: "kill-only", // 现链路 abort = SIGTERM，rpc abort 未接通
       permissionMode: "native", // argv-mirror 镜像主进程 flag
+      maxTurns: true, // [D3-④] turn limiter 兑现
     });
   });
 });
@@ -175,7 +189,7 @@ describe("PiEngine.capabilities（D3 链路接通口径）", () => {
 // ── run ──
 
 describe("PiEngine.run", () => {
-  it("中立声明 → ExecuteOptions 映射 + signal/onEvent/stream/ctxModel 直通（行为零变化）", async () => {
+  it("[D6 一次直出] 合流声明 AgentCallOpts → ExecuteOptions + signal/onEvent/stream/ctxModel 直通（行为零变化）", async () => {
     const { service, calls } = makeFakeService();
     const engine = new PiEngine({ getService: () => service });
     const spec = makeSpec();
@@ -239,35 +253,167 @@ describe("PiEngine.run", () => {
       executeResult: { content: "x", sessionFile: "/tmp/s.jsonl", sessionId: "sess-1", toolCalls: [] },
     });
     const engine = new PiEngine({ getService: () => service });
-    const r1 = await engine.run({ task: "t", slug: "s" }, makeRunCtx({ poolKey: "agent-reviewer" }));
+    const r1 = await engine.run({ prompt: "t" }, makeRunCtx({ poolKey: "agent-reviewer" }));
     expect(r1.handle.data.sessionRef).toEqual({ sessionFile: "/tmp/s.jsonl" });
     expect(r1.handle.data.poolKey).toBe("agent-reviewer");
     expect(r1.outcome.sessionId).toBe("sess-1");
-    const r2 = await engine.run({ task: "t", slug: "s" }, makeRunCtx({ poolKey: "" }));
+    const r2 = await engine.run({ prompt: "t" }, makeRunCtx({ poolKey: "" }));
     expect(r2.handle.data.poolKey).toBe("shared");
   });
 
+  it("[D2 chat 分支] ctx.taskId 命中交接包 → runChatRound 执行 + handle/outcome 形态（chat 编排不消费，形态完备）", async () => {
+    const ticketCalls: string[] = [];
+    const record = createRecord("sa-chat-ticket", {
+      agent: "reviewer", model: "p/m", thinkingLevel: "high", mode: "background",
+      task: "t", slug: "s", startedAt: 1, controller: new AbortController(),
+    });
+    const chatTicket: ChatRoundTicket = {
+      record,
+      opts: { task: "chat task", slug: "s" },
+      identity: { agent: "reviewer", agentConfig: undefined, resolved: { model: { id: "m", name: "M", provider: "p", reasoning: false }, thinkingLevel: "high" } },
+      ctx: { cwd: "/w" } as ChatRoundTicket["ctx"],
+      signal: undefined,
+      priority: 1000,
+    };
+    const service: PiEngineService = {
+      executeAndAwait: async () => { throw new Error("workflow branch must not run"); },
+      getRecordForAction: () => { throw new Error("unused"); },
+      closeSubagent: async () => {},
+      cancel: () => true,
+      collectRecords: () => [],
+      takeChatRound: (taskId) => {
+        ticketCalls.push(taskId);
+        return taskId === "sa-chat-ticket" ? chatTicket : undefined;
+      },
+      runChatRound: async (t) => ({
+        text: "chat done", turns: 2, durationMs: 7, success: true,
+        sessionId: t.record.id, toolCalls: [],
+      }),
+    };
+    const engine = new PiEngine({ getService: () => service });
+    const { handle, outcome } = await engine.run({ prompt: "t" }, makeRunCtx({ taskId: "sa-chat-ticket" }));
+    expect(ticketCalls).toEqual(["sa-chat-ticket"]);
+    expect(handle.data.sessionRef).toEqual({ recordId: "sa-chat-ticket" });
+    expect(handle.data.poolKey).toBe("shared");
+    expect(outcome).toMatchObject({ content: "chat done", engineId: "pi", sessionId: "sa-chat-ticket" });
+    // 非 chat taskId（workflow 域）→ 交接 miss → executeAndAwait 分支（此处 throw 证明未误入）
+    await expect(engine.run({ prompt: "t" }, makeRunCtx({ taskId: "sa-workflow" }))).rejects.toThrow(
+      "workflow branch must not run",
+    );
+  });
+
+  it("[D6/u-3b 硬验收] chat pi fork-from 零回归：ticket.opts.forkFromSessionFile 经 run chat 分支 lossless 送达 runChatRound", async () => {
+    // 链路（合流前后均不经任务声明）：壳 fork-from action → ExecuteOptions.forkFromSessionFile
+    // → kickOffChatRound 挂 ticket → 本分支 → runChatRound(ticket) → runAndFinalize →
+    // runSpawn（fork-from 源优先于 fork 推导）。本用例锁定合流后 ticket 交接不丢该字段。
+    const record = createRecord("sa-forkfrom", {
+      agent: "reviewer", model: "p/m", thinkingLevel: "high", mode: "background",
+      task: "t", slug: "s", startedAt: 1, controller: new AbortController(),
+    });
+    const ticketOpts: ExecuteOptions = { task: "continue", slug: "s", forkFromSessionFile: "/sessions/parent.jsonl" };
+    const chatTicket: ChatRoundTicket = {
+      record,
+      opts: ticketOpts,
+      identity: { agent: "reviewer", agentConfig: undefined, resolved: { model: { id: "m", name: "M", provider: "p", reasoning: false }, thinkingLevel: "high" } },
+      ctx: { cwd: "/w" } as ChatRoundTicket["ctx"],
+      signal: undefined,
+      priority: 1000,
+    };
+    let received: ChatRoundTicket | undefined;
+    const service: PiEngineService = {
+      executeAndAwait: async () => { throw new Error("workflow branch must not run"); },
+      getRecordForAction: () => { throw new Error("unused"); },
+      closeSubagent: async () => {},
+      cancel: () => true,
+      collectRecords: () => [],
+      takeChatRound: (taskId) => (taskId === "sa-forkfrom" ? chatTicket : undefined),
+      runChatRound: async (t) => {
+        received = t;
+        return { content: "ok", text: "ok", sessionId: "sess-1", turns: 1, durationMs: 1, success: true, toolCalls: [] };
+      },
+    };
+    const engine = new PiEngine({ getService: () => service });
+    await engine.run({ prompt: "t" }, makeRunCtx({ taskId: "sa-forkfrom" }));
+    // lossless 断言：runChatRound 收到同一 ticket 对象，opts 引用与 forkFromSessionFile 原值逐字节保持
+    expect(received).toBe(chatTicket);
+    expect(received?.opts).toBe(ticketOpts);
+    expect(received?.opts.forkFromSessionFile).toBe("/sessions/parent.jsonl");
+  });
+
   it("服务不可用（prepare 期）→ reject 且不产生 handle", async () => {
     const engine = new PiEngine({ getService: () => null });
-    await expect(engine.run({ task: "t", slug: "s" }, makeRunCtx())).rejects.toThrow(/SubagentService unavailable/);
+    await expect(engine.run({ prompt: "t" }, makeRunCtx())).rejects.toThrow(/SubagentService unavailable/);
   });
 
   it("executeAndAwait throw（嵌套超限等创建期异常）→ 向上传播（SAR catch 兜底不变）", async () => {
     const { service } = makeFakeService({ executeReject: new Error("nesting depth exceeded") });
     const engine = new PiEngine({ getService: () => service });
-    await expect(engine.run({ task: "t", slug: "s" }, makeRunCtx())).rejects.toThrow("nesting depth exceeded");
+    await expect(engine.run({ prompt: "t" }, makeRunCtx())).rejects.toThrow("nesting depth exceeded");
   });
 });
 
 // ── interact ──
 
-describe("PiEngine.interact（chatMode 交互面直通）", () => {
-  it("message → deliverMessage(record, text, false)（interrupt 中立 action 未携带，P1 恒 followUp）", async () => {
+describe("PiEngine.interact（chatMode 交互面：message 原生协议 + close/cancel 直通）", () => {
+  // [D2] message 分支原生实现（PiEngine.deliverPrompt）：热路径经真实 session-runner
+  // spawnedChildren Map + 真实 stdin-writer（不 mock——端到端验证协议字节）。
+  let hotChildren: Map<string, unknown>;
+  beforeEach(() => {
+    hotChildren = spawnedChildren as unknown as Map<string, unknown>;
+    hotChildren.clear();
+  });
+  afterEach(() => {
+    hotChildren.clear();
+    resetAllEpipeFailures();
+  });
+
+  function makeHotChild(): { child: ChildProcess; stdin: PassThrough } {
+    // exitCode/signalCode 缺省 null（[race-F5] 写后死检测的判据，undefined 会被误判已死）
+    const stdin = new PassThrough();
+    const child = { stdin, pid: 4242, exitCode: null, signalCode: null, killed: false } as unknown as ChildProcess;
+    return { child, stdin };
+  }
+
+  function readStdinLines(stdin: PassThrough): Array<Record<string, unknown>> {
+    stdin.pause();
+    // PassThrough.read() 类型 any——显式标注 string，下游 split/map 参数可推导
+    const text: string = stdin.read()?.toString() ?? "";
+    return text
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0)
+      .map((l) => JSON.parse(l) as Record<string, unknown>);
+  }
+
+  it("message 热路径（进程活）：sendPromptCommand 直写 stdin，interrupt → streamingBehavior（steer/followUp）+ record 迁移上报", async () => {
+    const { service, calls } = makeFakeService();
+    const engine = new PiEngine({ getService: () => service });
+    const { child, stdin } = makeHotChild();
+    hotChildren.set("sa-fake", child);
+
+    const res = await engine.interact(makeHandle({ recordId: "sa-fake" }), { kind: "message", payload: "next round", interrupt: true });
+    expect(res).toEqual({ ok: true, delivered: true });
+
+    const lines = readStdinLines(stdin);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatchObject({ type: "prompt", message: "next round", streamingBehavior: "steer" });
+
+    // 无 interrupt → followUp；record 迁移经 reportRecordTransition 上报（轮始信号清除后）
+    const { stdin: stdin2 } = makeHotChild();
+    hotChildren.set("sa-fake", { stdin: stdin2, pid: 4243, exitCode: null, signalCode: null, killed: false } as unknown as ChildProcess);
+    await engine.interact(makeHandle({ recordId: "sa-fake" }), { kind: "message", payload: "queued" });
+    const lines2 = readStdinLines(stdin2);
+    expect(lines2[0]).toMatchObject({ type: "prompt", message: "queued", streamingBehavior: "followUp" });
+    expect(calls.reportedTransitionIds).toEqual(["sa-fake", "sa-fake"]);
+  });
+
+  it("message 冷路径（进程死）：resumeChatRound 编排回调（重开 session 续聊）", async () => {
     const { service, calls } = makeFakeService();
     const engine = new PiEngine({ getService: () => service });
-    const res = await engine.interact(makeHandle({ recordId: "sa-fake" }), { kind: "message", payload: "next round" });
+    // spawnedChildren 无该 record → getChildByRecord undefined → 冷路径
+    const res = await engine.interact(makeHandle({ recordId: "sa-fake" }), { kind: "message", payload: "resume msg" });
     expect(res).toEqual({ ok: true, delivered: true });
-    expect(calls.deliverMessage).toEqual({ recordId: "sa-fake", text: "next round", interrupt: false });
+    expect(calls.resumeChatRound).toEqual({ recordId: "sa-fake", text: "resume msg" });
   });
 
   it("close → closeSubagent(record, force)；payload 缺省 force=false", async () => {
@@ -318,7 +464,7 @@ describe("PiEngine.interact（chatMode 交互面直通）", () => {
 
   it("交互面 throw → engine_interact_failed（message 文案透传行动语言）", async () => {
     const { service } = makeFakeService({
-      deliverReject: new Error("subagent sa-fake is not ready for a new message"),
+      resumeReject: new Error("subagent sa-fake is not ready for a new message"),
     });
     const engine = new PiEngine({ getService: () => service });
     const res = await engine.interact(makeHandle({ recordId: "sa-fake" }), { kind: "message", payload: "hi" });
@@ -346,7 +492,7 @@ describe("PiEngine.read（D6 降级链）", () => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-engine-read-"));
   });
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("无 sessionRef → outcome-only（turns 空）", async () => {

package/src/execution/engine/engines/pi/__tests__/spawn-opts-direct.test.ts

@@ -0,0 +1,257 @@
+// src/execution/engine/engines/pi/__tests__/spawn-opts-direct.test.ts
+//
+// [D6 任务形状合流 / 实施期门⑤ ⛔ 硬门产物] pi 边界一次直出映射
+// （agentCallToExecuteOptions：AgentCallOpts → ExecuteOptions）的字段完整性对照表
+// 与逐字段断言。本文件取代已删除的两个往返保真测试：
+//   - execution/__tests__/execute-options-mapper.test.ts（mapToExecuteOptions，18 用例）
+//   - engines/pi/__tests__/task-spec-mapper.test.ts（spec 往返保真，12 用例）
+//
+// ════════════════════════════════════════════════════════════════════════
+// 字段完整性对照表（从两个被删 mapper 的现有测试提取字段全集，逐字段核对）
+// ════════════════════════════════════════════════════════════════════════
+//
+// 合流前链路（三形态两映射）：
+//   AgentCallOpts --mapToExecuteOptions--> ExecuteOptions
+//     --executeOptionsToTaskSpec--> AgentTaskSpec --taskSpecToExecuteOptions--> ExecuteOptions
+// 合流后（单一形状一次直出）：
+//   AgentCallOpts --agentCallToExecuteOptions--> ExecuteOptions
+//
+// ┌────────────────────┬──────────────────────────────────────┬────────────────────────────────────┬──────────────┐
+// │ ExecuteOptions 字段 │ 合流前（两级链的合成语义）             │ 合流后（一次直出）                   │ 断言用例      │
+// ├────────────────────┼──────────────────────────────────────┼────────────────────────────────────┼──────────────┤
+// │ task               │ prompt→opts.task→spec.task（恒等往返）│ prompt 直取                          │ D-01         │
+// │ slug               │ description??agent??"workflow-agent"  │ 同规则内联（截断 SLUG_MAX_LENGTH=35）│ D-02..D-05   │
+// │                    │ 截断（mapToExecuteOptions）            │                                      │              │
+// │ agent              │ spec.agent ?? persona.agentRef        │ agent 直取（agentRef 无写入方，裁撤） │ D-06         │
+// │ model              │ 透传（显式 override，不与 ctxModel 混）│ 同                                   │ D-07         │
+// │ thinkingLevel      │ spec.effort 恒等映射回                 │ thinkingLevel 直取（恒等层删除）      │ D-08         │
+// │ skillPath          │ persona.skillPath 收拢/还原（恒等）    │ skillPath 直取（平铺保留）           │ D-09         │
+// │ appendSystemPrompt │ persona.appendSystemPrompt 收拢/还原   │ appendSystemPrompt 直取              │ D-10         │
+// │ schema             │ 透传                                  │ 同                                   │ D-11         │
+// │ schemaEnv          │ spec.schema 派生优先（stringifyCached  │ schema 派生优先；无 schema 时         │ D-12..D-14   │
+// │                    │ compact，与 resolver 同函数同缓存）+   │ schemaEnv 兜底（原 ctx.schemaEnv      │              │
+// │                    │ ctx.schemaEnv 兜底（源 = opts.schemaEnv）│ 通道的合流等价）；均无 → undefined   │              │
+// │ maxTurns           │ 透传（预算语义：undefined = 不限）      │ 同                                   │ D-15         │
+// │ graceTurns         │ 透传（spec 字段）                      │ 同（合流形状可选字段）                │ D-16         │
+// │ ctxModel           │ RunContext.ctxModel 回填               │ 第 2 参直取（运行期件，不入声明）     │ D-17         │
+// │ fork               │ 透传                                  │ 同                                   │ D-18         │
+// │ worktree           │ 透传（boolean | WorktreeHandle 三态）  │ 同                                   │ D-19         │
+// │ cwd                │ 透传                                  │ 同                                   │ D-20         │
+// │ conversation       │ 透传（interact 控制面 task 标志）      │ 同                                   │ D-21         │
+// │ idleTimeoutMs      │ 透传（同上）                           │ 同                                   │ D-22         │
+// │ engine/engineFallback│ PiEngine.run 调用方追加（D9① 留痕）  │ 同（不在本函数，pi-engine.test 覆盖） │ pi-engine.test│
+// │ signal/onComplete  │ 不入 opts（port 设计删字段去向）       │ 同（RunContext/编排侧各归其位）       │ D-23         │
+// └────────────────────┴──────────────────────────────────────┴────────────────────────────────────┴──────────────┘
+//
+// 调用方扩展字段（引擎不消费，不入 spawn 参数）：scene / timeoutMs（SAR mergeTimeoutSignal
+// 合并进 signal）/ skill（resolver 解析为 skillPath）/ engine（SAR 路由层）/ returnMeta
+// （worker 层）——不入本映射即正确（D-24 断言不泄漏）。
+// 已裁撤字段（D6 登记于 AgentCallOpts 类型注释）：persona.agentRef、requires。
+//
+// 全字段直出快照断言（D-00）+ 逐字段用例双保险：快照锁全集、用例锁语义边界。
+
+import { describe, expect, it } from "vitest";
+
+import type { AgentCallOpts } from "../../../../../orchestration/models/types.ts";
+import { SLUG_MAX_LENGTH } from "../../../../../orchestration/models/types.ts";
+import type { ModelInfo } from "../../../../model-resolver.ts";
+import type { ExecuteOptions } from "../../../../types.ts";
+import { agentCallToExecuteOptions } from "../pi-engine.ts";
+
+/** 全字段样例（覆盖对照表全部直出映射点）。 */
+function makeFullCall(): AgentCallOpts {
+  return {
+    prompt: "review the diff",
+    description: "review-diff",
+    agent: "/agents/reviewer.md",
+    model: "zai-coding-cn/glm-5.2",
+    thinkingLevel: "high",
+    skillPath: "/skills/code-review/SKILL.md",
+    appendSystemPrompt: ["extra system prompt line"],
+    schema: { type: "object", properties: { verdict: { type: "string" } }, required: ["verdict"] },
+    maxTurns: 20,
+    graceTurns: 3,
+    fork: true,
+    worktree: true,
+    cwd: "/repo/worktree-x",
+    conversation: true,
+    idleTimeoutMs: 600_000,
+  };
+}
+
+describe("agentCallToExecuteOptions（D6 一次直出：AgentCallOpts → pi spawn 编排参数）", () => {
+  it("D-00 全字段直出快照（与合流前两级链的合成结果逐字段一致——原往返保真测试的直出等价物）", () => {
+    const result = agentCallToExecuteOptions(makeFullCall());
+    const expected: ExecuteOptions = {
+      task: "review the diff",
+      slug: "review-diff",
+      agent: "/agents/reviewer.md",
+      model: "zai-coding-cn/glm-5.2",
+      thinkingLevel: "high",
+      skillPath: "/skills/code-review/SKILL.md",
+      appendSystemPrompt: ["extra system prompt line"],
+      schema: { type: "object", properties: { verdict: { type: "string" } }, required: ["verdict"] },
+      schemaEnv: JSON.stringify({ type: "object", properties: { verdict: { type: "string" } }, required: ["verdict"] }),
+      maxTurns: 20,
+      graceTurns: 3,
+      ctxModel: undefined,
+      fork: true,
+      worktree: true,
+      cwd: "/repo/worktree-x",
+      conversation: true,
+      idleTimeoutMs: 600_000,
+    };
+    expect(result).toEqual(expected);
+  });
+
+  // ── task / slug（D-01..D-05）──
+
+  it("D-01 prompt → task", () => {
+    expect(agentCallToExecuteOptions({ prompt: "do the thing" }).task).toBe("do the thing");
+  });
+
+  it("D-02 description → slug", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", description: "fix-login" }).slug).toBe("fix-login");
+  });
+
+  it("D-03 description 缺失 → 回落 agent 名（保证 slug 非空）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", agent: "worker" }).slug).toBe("worker");
+  });
+
+  it("D-04 description 与 agent 均缺失 → 回落 'workflow-agent'", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t" }).slug).toBe("workflow-agent");
+  });
+
+  it("D-05 slug 截断：description > SLUG_MAX_LENGTH(35) 截到 35；= 35 不截（边界）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", description: "a".repeat(36) }).slug).toBe("a".repeat(35));
+    expect(agentCallToExecuteOptions({ prompt: "t", description: "a".repeat(35) }).slug).toBe("a".repeat(35));
+    expect(SLUG_MAX_LENGTH).toBe(35);
+  });
+
+  // ── 身份 / 模型 / 推理档位（D-06..D-08）──
+
+  it("D-06 agent 直取（原 persona.agentRef 兜底随 PersonaSpec 裁撤——无生产写入方）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", agent: "/a.md" }).agent).toBe("/a.md");
+    expect(agentCallToExecuteOptions({ prompt: "t" }).agent).toBeUndefined();
+  });
+
+  it("D-07 model：显式 override 透传；缺省 undefined（不与 ctxModel 混合）", () => {
+    const ctxModel: ModelInfo = { id: "ctx-model", name: "Ctx", provider: "test", reasoning: false };
+    expect(agentCallToExecuteOptions({ prompt: "t", model: "explicit-model" }, ctxModel).model).toBe("explicit-model");
+    expect(agentCallToExecuteOptions({ prompt: "t" }, ctxModel).model).toBeUndefined();
+  });
+
+  it("D-08 thinkingLevel 直取（原 effort 恒等映射层删除，含 7 档外的缺省）", () => {
+    for (const level of ["off", "low", "medium", "high", "max", undefined]) {
+      expect(agentCallToExecuteOptions({ prompt: "t", thinkingLevel: level }).thinkingLevel).toBe(level);
+    }
+  });
+
+  // ── persona 平铺字段（D-09..D-10）──
+
+  it("D-09 skillPath 直取（原 persona 收拢/还原恒等）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", skillPath: "/s" }).skillPath).toBe("/s");
+    expect(agentCallToExecuteOptions({ prompt: "t" }).skillPath).toBeUndefined();
+  });
+
+  it("D-10 appendSystemPrompt 直取（含空数组归一语义：空数组保持空数组——下游 spread no-op 等价）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", appendSystemPrompt: ["l1", "l2"] }).appendSystemPrompt).toEqual(["l1", "l2"]);
+    expect(agentCallToExecuteOptions({ prompt: "t", appendSystemPrompt: [] }).appendSystemPrompt).toEqual([]);
+    expect(agentCallToExecuteOptions({ prompt: "t" }).appendSystemPrompt).toBeUndefined();
+  });
+
+  // ── schema / schemaEnv（D-11..D-14）──
+
+  it("D-11 schema 透传为原始对象引用", () => {
+    const schema = { type: "object" };
+    expect(agentCallToExecuteOptions({ prompt: "t", schema }).schema).toBe(schema);
+  });
+
+  it("D-12 schemaEnv 派生：与 agent-opts-resolver 同函数（stringifySchemaCached compact），逐字节等值", () => {
+    const schema = { type: "object", properties: { a: { type: "number" } } };
+    expect(agentCallToExecuteOptions({ prompt: "t", schema }).schemaEnv).toBe(JSON.stringify(schema));
+  });
+
+  it("D-13 派生优先：schema 存在时 opts.schemaEnv（stale 值）被忽略", () => {
+    const schema = { type: "object" };
+    expect(agentCallToExecuteOptions({ prompt: "t", schema, schemaEnv: "STALE" }).schemaEnv).toBe(JSON.stringify(schema));
+  });
+
+  it("D-14 schemaEnv 兜底/缺省：无 schema 时用 opts.schemaEnv（解耦形态，原 ctx 兜底通道等价）；均无 → undefined（BC-6：childEnv 不注入）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", schemaEnv: '{"type":"object"}' }).schemaEnv).toBe('{"type":"object"}');
+    expect(agentCallToExecuteOptions({ prompt: "t" }).schemaEnv).toBeUndefined();
+  });
+
+  // ── 轮数 / 运行期 / 隔离（D-15..D-20）──
+
+  it("D-15 maxTurns 透传（undefined = 不限，不挂 turns 估算 watchdog）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", maxTurns: 20 }).maxTurns).toBe(20);
+    expect(agentCallToExecuteOptions({ prompt: "t" }).maxTurns).toBeUndefined();
+  });
+
+  it("D-16 graceTurns 透传（合流形状可选字段，chat 域经 host-task-spec 填充）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", graceTurns: 3 }).graceTurns).toBe(3);
+    expect(agentCallToExecuteOptions({ prompt: "t" }).graceTurns).toBeUndefined();
+  });
+
+  it("D-17 ctxModel 从第 2 参回填（运行期件不入任务声明——D-008 兼底链路）", () => {
+    const ctxModel: ModelInfo = { id: "mimo-v2.5-pro", name: "MiMo", provider: "router-openai", reasoning: false };
+    expect(agentCallToExecuteOptions({ prompt: "t" }, ctxModel).ctxModel).toBe(ctxModel);
+    expect(agentCallToExecuteOptions({ prompt: "t" }).ctxModel).toBeUndefined();
+  });
+
+  it("D-18 fork 透传", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", fork: true }).fork).toBe(true);
+  });
+
+  it("D-19 worktree 三态（true/false/WorktreeHandle）直出保持", () => {
+    const handle = { path: "/wt", branch: "b", baseCommit: "c", mainCwd: "/repo" };
+    for (const wt of [true, false, handle] as const) {
+      expect(agentCallToExecuteOptions({ prompt: "t", worktree: wt }).worktree).toBe(wt);
+    }
+  });
+
+  it("D-20 cwd 透传", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", cwd: "/work" }).cwd).toBe("/work");
+  });
+
+  // ── 交互控制面（D-21..D-22）──
+
+  it("D-21 conversation 透传（interact 控制面的 task 标志）", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", conversation: true }).conversation).toBe(true);
+  });
+
+  it("D-22 idleTimeoutMs 透传", () => {
+    expect(agentCallToExecuteOptions({ prompt: "t", idleTimeoutMs: 12345 }).idleTimeoutMs).toBe(12345);
+  });
+
+  // ── 声明边界（D-23..D-24）──
+
+  it("D-23 运行期字段不入直出产物：signal/onComplete/engine/engineFallback 不由本函数产出（engine 由 run 调用方追加）", () => {
+    const result = agentCallToExecuteOptions(makeFullCall()) as unknown as Record<string, unknown>;
+    expect("signal" in result).toBe(false);
+    expect("onComplete" in result).toBe(false);
+    expect("engine" in result).toBe(false);
+    expect("engineFallback" in result).toBe(false);
+  });
+
+  it("D-24 调用方扩展字段不泄漏进 spawn 参数：scene/timeoutMs/skill/engine/returnMeta/denyTools/permissionMode", () => {
+    const result = agentCallToExecuteOptions({
+      prompt: "t",
+      scene: "coding",
+      timeoutMs: 5000,
+      skill: "code-review",
+      engine: "pi",
+      returnMeta: true,
+      denyTools: ["bash"],
+      permissionMode: "yolo",
+    }) as unknown as Record<string, unknown>;
+    expect("scene" in result).toBe(false);
+    expect("timeoutMs" in result).toBe(false);
+    expect("skill" in result).toBe(false);
+    expect("engine" in result).toBe(false);
+    expect("returnMeta" in result).toBe(false);
+    expect("denyTools" in result).toBe(false);
+    expect("permissionMode" in result).toBe(false);
+  });
+});