@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/execution/engine/__tests__/conformance/contract.agent-events.test.ts

@@ -1,20 +1,19 @@
 // contract.agent-events.test.ts —— conformance C3（AgentEvent 不变量）+ 负例自证
 // （A12「套件有牙」：故意破坏一个不变量的样本必须被断言器检出——用「注入坏
-// parser」的形态：wrap 真实 synthesizeCoarseEvents 抽掉 message_end，断言套件转红；
+// parser」的形态：构造抽掉 message_end / usage 半映射的坏样本流，断言套件转红；
 // 若断言器检不出破坏则本元测试失败）。
 //
-// [R6] 双模式口径：zcode 引擎 conformance 覆盖两种通道形态——spawn 钉扎（golden
-// stdout 语料 + coarse 合成，下方原有用例）与 app-server 常驻（fake 常驻引擎全链 +
-// stream 口径，文件末新增 describe；app-server 设计 §3.4 不变量 1：text_delta 拼接 ==
-// read 全文、终态唯一 turn.terminal 权威、message_end.usage 完整、tool 事件不合成
-// ——granularity 声明与实际流出一致）。
+// 2026-09 重构（共享宿主 HOME）：CLI spawn 链删除后引擎只剩 app-server 常驻链，
+// C3 的引擎全链覆盖只走 app-server 形态（fake 常驻引擎 + stream 口径，文件末
+// describe；app-server 设计 §3.4 不变量 1：text_delta 拼接 == read 全文、终态唯一
+// turn.terminal 权威、message_end.usage 完整、tool 事件不合成——granularity 声明
+// 与实际流出一致）。断言器行为正反例与负例自证均为手工构造样本，不依赖引擎实现。
 
 import { describe, expect, it } from "vitest";
 
 import type { AgentEvent } from "../../../types.ts";
-import { ZCODE_APPSERVER_GOLDEN, ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
-import { ZCODE_APPSERVER_POOL_KEY } from "../../engines/zcode/constants.ts";
-import { parseZcodeTerminal, synthesizeCoarseEvents } from "../../engines/zcode/parser.ts";
+import { ZCODE_APPSERVER_GOLDEN } from "../../engines/zcode/golden-sample.ts";
+import { ZCODE_SHARED_POOL_KEY } from "../../engines/zcode/constants.ts";
 import {
   goldenReadFullText,
   makeAppserverHarness,
@@ -24,18 +23,7 @@ import {
   checkAgentEventInvariants,
 } from "./agent-event-invariants.ts";
 
-/** golden 实录的 coarse 事件流（真实 parser + 真实合成器的产出）。 */
-function goldenCoarseEvents(): AgentEvent[] {
-  const terminal = parseZcodeTerminal(ZCODE_GOLDEN_STDOUT);
-  if (!terminal.ok) throw new Error("golden 样本解析失败");
-  return synthesizeCoarseEvents(terminal.payload.response, terminal.payload.usage);
-}
-
-describe("conformance C3：AgentEvent 不变量（真实 parser 产出全绿）", () => {
-  it("zcode golden 合成事件满足五条不变量（coarse 口径）", () => {
-    assertAgentEventInvariants(goldenCoarseEvents(), { granularity: "coarse" });
-  });
-
+describe("conformance C3：AgentEvent 不变量（断言器正反例，手工构造样本）", () => {
   it("不变量 1：终态唯一——turn_end 后不得再出现非 error 事件", () => {
     const events: AgentEvent[] = [{ type: "message_end" }, { type: "turn_end" }, { type: "text_delta", delta: "x" }];
     const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
@@ -113,8 +101,7 @@ describe("conformance 负例自证（A12：套件有牙）", () => {
 
 // ============================================================
 // [R6] C3 app-server 口径：fake 常驻引擎全链（eventGranularity=stream 形态）
-// —— spawn 钉扎用例见上方 coarse describe，两形态各自覆盖不合并（D2 降级链保留
-// spawn 路径，双通道都是生产可达形态）。
+// —— 2026-09 重构后唯一生产形态（CLI spawn 降级链已删，无钉扎/降级双通道）。
 // ============================================================
 
 describe("conformance C3：zcode app-server 常驻通道（stream 口径，fake 常驻全链）", () => {
@@ -123,7 +110,7 @@ describe("conformance C3：zcode app-server 常驻通道（stream 口径，fake
     try {
       const events: AgentEvent[] = [];
       const { outcome } = await h.engine.run(
-        { task: "做点什么", slug: "c3-appserver", model: "conformance-provider/m1", cwd: h.workspace },
+        { prompt: "做点什么", description: "c3-appserver", model: "conformance-provider/m1", cwd: h.workspace },
         { taskId: "sa-c3-appserver", poolKey: "", onEvent: (e) => events.push(e) },
       );
 
@@ -158,7 +145,7 @@ describe("conformance C3：zcode app-server 常驻通道（stream 口径，fake
     try {
       const events: AgentEvent[] = [];
       const { outcome } = await h.engine.run(
-        { task: "做点什么", slug: "c3-no-terminal", model: "conformance-provider/m1", cwd: h.workspace },
+        { prompt: "做点什么", description: "c3-no-terminal", model: "conformance-provider/m1", cwd: h.workspace },
         { taskId: "sa-c3-no-terminal", poolKey: "", onEvent: (e) => events.push(e) },
       );
       expect(outcome.error).toBeUndefined();
@@ -169,14 +156,14 @@ describe("conformance C3：zcode app-server 常驻通道（stream 口径，fake
     }
   }, 20_000);
 
-  it("handle 锚定常驻 HOME（poolKey=home-appserver，①级读取钥匙随 handle 走）", async () => {
+  it("handle 携带 shared poolKey（共享宿主 HOME 的 journal 分组锚点，①级读取钥匙随 handle 走）", async () => {
     const h = makeAppserverHarness();
     try {
       const { handle, outcome } = await h.engine.run(
-        { task: "做点什么", slug: "c3-anchor", model: "conformance-provider/m1", cwd: h.workspace },
+        { prompt: "做点什么", description: "c3-anchor", model: "conformance-provider/m1", cwd: h.workspace },
         { taskId: "sa-c3-anchor", poolKey: "" },
       );
-      expect(handle.data.poolKey).toBe(ZCODE_APPSERVER_POOL_KEY);
+      expect(handle.data.poolKey).toBe(ZCODE_SHARED_POOL_KEY);
       expect(handle.data.sessionRef["sessionId"]).toBe(outcome.sessionId);
       // golden 锚点：sessionId 来自 session.sessionId（projection.sessionId 恒 "unknown" 勿用）
       expect(JSON.parse(ZCODE_APPSERVER_GOLDEN.createResponse).session.sessionId).toBe("sess_golden_r3_01");

package/src/execution/engine/__tests__/conformance/engine-conformance.live.test.ts

@@ -25,10 +25,11 @@ import { describe, expect, it } from "vitest";
 import { getSubagentService } from "../../../subagent-service.ts";
 import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
 import { createPiEngine } from "../../engines/pi/registration.ts";
+import type { PiEngineService } from "../../engines/pi/pi-engine.ts";
 import type { RunContext } from "../../port.ts";
 import type { AgentEvent } from "../../../types.ts";
-import type { AgentTaskSpec } from "../../types.ts";
-import { getPiInvocation } from "../../../pi-invocation.ts";
+import type { AgentCallOpts } from "../../../../orchestration/models/types.ts";
+import { getPiInvocation } from "../../engines/pi/pi-invocation.ts";
 import {
   RELAY_ENV_NODE,
   RELAY_ENV_RECORD_ID,
@@ -51,8 +52,8 @@ describe.skipIf(!LIVE)("conformance run 层（真实 spawn，手动门）", () =
       testCtx.skip("SubagentService 未装配（需在真实会话进程内运行）");
       return;
     }
-    const engine = createPiEngine(() => service);
-    const task: AgentTaskSpec = { task: "Reply with the single word: ok", slug: "live-c2" };
+    const engine = createPiEngine(() => service as unknown as PiEngineService);
+    const task: AgentCallOpts = { prompt: "Reply with the single word: ok", description: "live-c2" };
     const ctx: RunContext = { taskId: "sa-live-pi-c2", poolKey: "shared" };
     const { outcome } = await engine.run(task, ctx);
     expect(outcome.error).toBeUndefined();
@@ -68,9 +69,9 @@ describe.skipIf(!LIVE)("conformance run 层（真实 spawn，手动门）", () =
   }, 60_000);
 
   // [R6] 常驻通道的 conformance run 层（RA8「C1-C8 适配后全绿」的 live 面）：
-  // XYZ_ZCODE_MODE=appserver 定向（不探不降）跑最小任务——C2 outcome + C3 stream
-  // 不变量（app-server 设计 §3.4 不变量 1）。更深断言（schema/abort/进程锚定）由
-  // engines/zcode/__tests__/zcode-engine.live.test.ts 的 [R6] app-server 段承载。
+  // 跑最小任务——C2 outcome + C3 stream 不变量（app-server 设计 §3.4 不变量 1）。
+  // 2026-09 起单一 app-server 形态即缺省路径（无模式钉扎 env）；更深断言（schema/
+  // abort/进程锚定）由 engines/zcode/__tests__/zcode-engine.live.test.ts 承载。
   it("zcode：app-server 常驻通道 run 全链（C2 outcome 无 error + C3 stream 事件不变量）", async (testCtx) => {
     const model = process.env["ZCODE_E2E_MODEL"];
     if (model === undefined || model === "") {
@@ -79,11 +80,10 @@ describe.skipIf(!LIVE)("conformance run 层（真实 spawn，手动门）", () =
     }
     const engine = new ZcodeEngine({
       engineDataDir: () => "/tmp/zcode-conformance-live-appserver",
-      processEnv: { ...process.env, XYZ_ZCODE_MODE: "appserver" },
     });
     const events: AgentEvent[] = [];
     const { outcome } = await engine.run(
-      { task: "Reply with the single word: ok", slug: "live-appserver-c2", model, cwd: "/tmp" },
+      { prompt: "Reply with the single word: ok", description: "live-appserver-c2", model, cwd: "/tmp" },
       { taskId: "sa-live-zcode-appserver", poolKey: "", onEvent: (e) => events.push(e) },
     );
     expect(outcome.error).toBeUndefined();
@@ -200,9 +200,9 @@ describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手
     }
 
     try {
-      const engine = createPiEngine(() => service);
+      const engine = createPiEngine(() => service as unknown as PiEngineService);
       const events: AgentEvent[] = [];
-      const task: AgentTaskSpec = { task: "Reply with the single word: ok", slug: "live-relay-c2" };
+      const task: AgentCallOpts = { prompt: "Reply with the single word: ok", description: "live-relay-c2" };
       const ctx: RunContext = {
         taskId: "sa-live-pi-relay",
         poolKey: "shared",
@@ -221,7 +221,7 @@ describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手
         else process.env[key] = savedEnv[key];
       }
       await new Promise<void>((resolve) => server.close(() => resolve()));
-      fs.rmSync(tmpDir, { recursive: true, force: true });
+      fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 });

package/src/execution/engine/__tests__/conformance/golden-replay.pi.test.ts

@@ -15,7 +15,7 @@ import { describe, expect, it } from "vitest";
 
 import type { AgentEvent } from "../../../types.ts";
 import { JournalWriter, replayJournal } from "../../common/event-journal.ts";
-import { parseSpawnLine } from "../../../spawn-event-adapter.ts";
+import { parseSpawnLine } from "../../engines/pi/spawn-event-adapter.ts";
 import { assertAgentEventInvariants } from "./agent-event-invariants.ts";
 
 interface PiGoldenFile {

package/src/execution/engine/__tests__/conformance/golden-replay.zcode.test.ts

@@ -1,13 +1,13 @@
-// golden-replay.zcode.test.ts —— zcode 引擎 golden 回放层（conformance 免 LLM 默认 CI
-// 层）。数据源 = P3 验收前置门的真机实录（engines/zcode/__tests__/__fixtures__/
-// zcode-golden-spawn.json 的 stdoutRaw）——parser 对实录样本回归 + coarse 事件合成
-// 不变量断言 + 双副本 diff 校验（fixture 与 golden-sample.ts 内嵌副本一致，防漂移：
-// 更新样本必须同步两处，探针的干跑校验消费内嵌副本，两处不一致 = 探针在测旧契约）。
+// golden-replay.zcode.test.ts —— zcode 引擎 golden 回放层（conformance 免 LLM 默认
+// CI 层）。语料 = app-server NDJSON 帧序列（附录 A.2 任务生命周期帧序；采集 SSOT
+// = engines/zcode/__tests__/__fixtures__/zcode-golden-appserver.json）——双副本 diff
+// 校验（fixture 与 golden-sample.ts 内嵌副本一致，防漂移：更新样本必须同步两处，
+// 探针的干跑校验消费内嵌副本，两处不一致 = 探针在测旧契约）+ 帧形态不变量断言
+// （A8「golden 帧序列语料 diff 通过」的本仓段）。
 //
-// [R6] 双语料并存：① spawn stdout（上方，spawn 降级路径 + probe 干跑的回归语料——
-// 生产消费方存在故保留，去留决策见 impl-plan R6 偏差登记）② app-server 帧序列
-// （下方新增，常驻通道主力语料——双副本 diff 自 session-channel 测试接管到 conformance
-// 回放层，帧形态不变量在此断言；A8「golden 帧序列语料 diff 通过」的本仓段）。
+// 2026-09 重构（共享宿主 HOME）：CLI spawn 链删除后 spawn stdout 语料（单 JSON
+// 样本及其 fixture）随 spawn 回归一并删除，本层仅保留 app-server 帧序列语料
+// （常驻通道唯一生产形态）。
 
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -15,86 +15,21 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it } from "vitest";
 
-import { ZCODE_APPSERVER_GOLDEN, ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
-import {
-  mapZcodeOutcomeUsage,
-  parseZcodeTerminal,
-  synthesizeCoarseEvents,
-} from "../../engines/zcode/parser.ts";
-import { assertAgentEventInvariants } from "./agent-event-invariants.ts";
+import { ZCODE_APPSERVER_GOLDEN } from "../../engines/zcode/golden-sample.ts";
 
 // conformance 目录（engine/__tests__/conformance）→ engine 根的相对定位
-const fixturePath = join(
+const appserverFixturePath = join(
   dirname(fileURLToPath(import.meta.url)),
   "..", "..", // conformance → __tests__ → engine
-  "engines", "zcode", "__tests__", "__fixtures__", "zcode-golden-spawn.json",
+  "engines", "zcode", "__tests__", "__fixtures__", "zcode-golden-appserver.json",
 );
 
-interface ZcodeGoldenFile {
-  _meta: { engineVersion: string; exitCode: number };
-  stdoutRaw: string;
-}
-
-const fixture = JSON.parse(readFileSync(fixturePath, "utf8")) as ZcodeGoldenFile;
-
-// [R6] app-server 帧序列语料 fixture（采集 SSOT——双副本 diff 的另一副本）
-const appserverFixturePath = join(dirname(fixturePath), "zcode-golden-appserver.json");
 interface AppServerGoldenFile {
   _meta: Record<string, unknown>;
   frames: { createResponse: string; pushStream: string[]; terminal: string[]; readResponse: string };
 }
 const appserverFixture = JSON.parse(readFileSync(appserverFixturePath, "utf8")) as AppServerGoldenFile;
 
-describe("zcode golden 回放（conformance C3，免 LLM/免二进制）", () => {
-  it("双副本 diff：golden-sample.ts 内嵌副本 === fixture stdoutRaw（防漂移，A12）", () => {
-    expect(ZCODE_GOLDEN_STDOUT).toBe(fixture.stdoutRaw);
-  });
-
-  it("parser 对实录样本回归：sessionId/response/usage 形状完整（探针干跑同源断言）", () => {
-    const terminal = parseZcodeTerminal(fixture.stdoutRaw);
-    expect(terminal.ok).toBe(true);
-    if (!terminal.ok) return;
-    expect(terminal.payload.sessionId).toMatch(/^sess_/);
-    expect(terminal.payload.response).toBe("ok");
-    expect(terminal.payload.usage).toEqual({ input: 12599, output: 17, cacheRead: 512, cacheWrite: 0 });
-    // 终态层 usage（orchestration 版）：cost 显式 0（无来源不给残缺）、contextTokens 取 projection
-    expect(terminal.payload.outcomeUsage).toEqual({
-      input: 12599,
-      output: 17,
-      cacheRead: 512,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 12616,
-      turns: 1,
-    });
-  });
-
-  it("coarse 事件合成满足产出不变量（turn_end 最后、其前必有 message_end、usage 完整）", () => {
-    const terminal = parseZcodeTerminal(fixture.stdoutRaw);
-    if (!terminal.ok) throw new Error("golden 样本解析失败（上一用例应已转红）");
-    const events = synthesizeCoarseEvents(terminal.payload.response, terminal.payload.usage);
-    assertAgentEventInvariants(events, { granularity: "coarse" });
-    expect(events.map((e) => e.type)).toEqual(["message_end", "turn_end"]);
-  });
-
-  it("usage 无来源样本：mapZcodeOutcomeUsage 显式缺省（不给残缺对象，不变量 2 的输入面）", () => {
-    expect(mapZcodeOutcomeUsage(undefined, undefined)).toBeUndefined();
-    expect(mapZcodeOutcomeUsage({ inputTokens: 1 }, undefined)).toEqual({
-      input: 1,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 0,
-      turns: 1,
-    });
-  });
-});
-
-// ============================================================
-// [R6] app-server 帧序列语料回放（常驻通道主力语料，conformance 层接管双副本 diff）
-// ============================================================
-
 describe("zcode app-server golden 回放（conformance C3 帧形态，免 LLM/免二进制）", () => {
   it("双副本 diff：golden-sample.ts 内嵌副本 === fixture frames（防漂移，A8 本仓段）", () => {
     expect(ZCODE_APPSERVER_GOLDEN.createResponse).toBe(appserverFixture.frames.createResponse);
@@ -141,7 +76,7 @@ describe("zcode app-server golden 回放（conformance C3 帧形态，免 LLM/
     expect(readText).toBe(deltaJoined); // text_delta 拼接 == 收尾帧 == read 全文
   });
 
-  it("终态权威帧：turn.terminal 存在且先于收尾帧；usage 与 spawn golden 同值（漂移对照锚点）", () => {
+  it("终态权威帧：turn.terminal 存在且先于收尾帧；usage 与 read step-finish tokens 同源（漂移对照锚点）", () => {
     const terminal = ZCODE_APPSERVER_GOLDEN.terminal.map((l) => JSON.parse(l) as {
       params?: { kind?: string; status?: string; payload?: { usage?: { inputTokens: number; outputTokens: number } } };
     });
@@ -151,11 +86,15 @@ describe("zcode app-server golden 回放（conformance C3 帧形态，免 LLM/
     expect(terminal[terminalFrameIdx]?.params?.status).toBe("success");
     expect(terminalFrameIdx).toBeLessThan(closingFrameIdx);
 
-    const spawnUsage = parseZcodeTerminal(ZCODE_GOLDEN_STDOUT);
-    if (!spawnUsage.ok) throw new Error("spawn golden 样本解析失败");
+    // usage 跨源对照锚点：收尾帧 usage == read 应答 step-finish tokens（同一轮真实
+    // 计费面，两源必须一致；旧 spawn golden 对照随语料删除）
+    const read = JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse) as {
+      messages: Array<{ info: { role: string }; parts: Array<{ type: string; tokens?: { input: number; output: number } }> }>;
+    };
+    const stepFinish = (read.messages.at(-1)?.parts ?? []).find((p) => p.type === "step-finish");
     expect(terminal[closingFrameIdx]?.params?.payload?.usage).toEqual({
-      inputTokens: spawnUsage.payload.usage.input,
-      outputTokens: spawnUsage.payload.usage.output,
+      inputTokens: stepFinish?.tokens?.input,
+      outputTokens: stepFinish?.tokens?.output,
     });
   });
 });

package/src/execution/engine/__tests__/conformance/zcode-appserver-harness.ts

@@ -38,7 +38,7 @@ export interface AppserverHarness {
   dispose(): Promise<void>;
 }
 
-/** 组装连到 fake-appserver 的常驻引擎（XYZ_ZCODE_MODE=appserver 定向——不探不降）。 */
+/** 组装连到 fake-appserver 的常驻引擎（单一 app-server 形态——2026-09 起无模式分派）。 */
 export function makeAppserverHarness(opts: AppserverHarnessOptions = {}): AppserverHarness {
   const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-conformance-appserver-"));
   const dataDir = path.join(tmpRoot, "data");
@@ -78,9 +78,6 @@ export function makeAppserverHarness(opts: AppserverHarnessOptions = {}): Appser
     sources: { v2ConfigPath: v2Path },
     processEnv: {
       PATH: process.env.PATH ?? "",
-      // 定向 appserver（R5 D2①）：不探不降——conformance 测常驻路径本体，缺省路径的
-      // 探针门控/降级链归 zcode-engine-degrade.test.ts
-      XYZ_ZCODE_MODE: "appserver",
       FAKE_STATE_FILE: stateFile,
       FAKE_SESSION_SCENARIO: scenarioFile,
     },
@@ -92,7 +89,7 @@ export function makeAppserverHarness(opts: AppserverHarnessOptions = {}): Appser
     dataDir,
     dispose: () =>
       engine.dispose().finally(() => {
-        fs.rmSync(tmpRoot, { recursive: true, force: true });
+        fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
       }),
   };
 }
@@ -114,8 +111,8 @@ export function readFakeState(file: string): Array<Record<string, unknown>> {
 /** fake 收到的客户端帧方法名序列（abort 链「stop 先于杀链」断言面）。 */
 export function sentMethodNames(stateFile: string): string[] {
   return readFakeState(stateFile)
-    .map((e) => e["frame"])
-    .filter((f): f is Record<string, unknown> => typeof f === "object" && f !== null && typeof f["method"] === "string")
+    .map((e) => (e as Record<string, unknown>)["frame"])
+    .filter((f): f is Record<string, unknown> => typeof f === "object" && f !== null && typeof (f as Record<string, unknown>)["method"] === "string")
     .map((f) => f["method"] as string);
 }
 

package/src/execution/engine/__tests__/engine-discovery.test.ts

@@ -15,8 +15,20 @@ import { clearEngines, registerEngine } from "../registry.ts";
 function stubEngine(id: string): EnginePort {
   return {
     id,
-    capabilities: () => ({ conversation: "unsupported", steer: "unsupported", sandbox: "none" }),
-    probe: async () => ({ ok: true, engineVersion: "test" }),
+    capabilities: () => ({
+      schemaEnforcement: "emulated",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "unsupported",
+      interrupt: "kill-only",
+      permissionMode: "ignored",
+      maxTurns: false,
+    }),
+    probe: async () => ({ ok: true, engineVersion: "test", checks: [] }),
     run: async () => {
       throw new Error("unused");
     },
@@ -38,7 +50,7 @@ beforeEach(() => {
 
 afterEach(() => {
   clearEngines();
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 describe("syncEnginesFile", () => {

package/src/execution/engine/__tests__/model-prompt.test.ts

@@ -16,8 +16,20 @@ import { buildEngineModelsPromptAppend, buildSubagentEngineSection } from "../mo
 function fakeEngine(id: string, models: Array<{ id: string; name?: string }> | null): EnginePort {
   return {
     id,
-    capabilities: () => ({ conversation: "unsupported", steer: "unsupported", sandbox: "none" }),
-    probe: async () => ({ ok: true, engineVersion: "test" }),
+    capabilities: () => ({
+      schemaEnforcement: "emulated",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "unsupported",
+      interrupt: "kill-only",
+      permissionMode: "ignored",
+      maxTurns: false,
+    }),
+    probe: async () => ({ ok: true, engineVersion: "test", checks: [] }),
     run: async () => {
       throw new Error("not used in this test");
     },
@@ -38,7 +50,7 @@ beforeEach(() => {
 
 afterEach(() => {
   clearEngines();
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 describe("buildEngineModelsPromptAppend（defaultEngine 开关语义）", () => {

package/src/execution/engine/__tests__/registry.test.ts

@@ -17,7 +17,8 @@ import {
   listEngines,
   registerEngine,
 } from "../registry.ts";
-import type { AgentTaskSpec, SessionView } from "../types.ts";
+import type { SessionView } from "../types.ts";
+import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
 
 /** 最小可运行假引擎（完整实现 EnginePort 五面——不 cast，防接口漂移失检）。 */
 function makeFakeEngine(id: string): EnginePort {
@@ -34,10 +35,11 @@ function makeFakeEngine(id: string): EnginePort {
       resume: "unsupported",
       interrupt: "kill-only",
       permissionMode: "fixed",
+      maxTurns: false,
     }),
     probe: () =>
       Promise.resolve({ ok: true, engineVersion: "0.0.0-test", checks: [{ name: "stub", ok: true }] }),
-    run: (_task: AgentTaskSpec, _ctx: RunContext) =>
+    run: (_task: AgentCallOpts, _ctx: RunContext) =>
       Promise.reject(new Error("fake engine: run not implemented")),
     interact: () => Promise.resolve({ ok: false, code: "engine_capability_unsupported", message: "stub" }),
     read: (_handle: Parameters<EnginePort["read"]>[0]): Promise<SessionView> =>

package/src/execution/engine/__tests__/routing.test.ts

@@ -6,8 +6,10 @@ import { describe, expect, it } from "vitest";
 import type { EnginePort, RunContext } from "../port.ts";
 import { DEFAULT_ENGINE_ID, EngineNotFoundError } from "../registry.ts";
 import { EngineError } from "../common/errors.ts";
-import type { AgentTaskSpec, ProbeReport, SessionView } from "../types.ts";
-import { resolveEngineRouting, routeEngine, type EngineRouteOptions } from "../routing.ts";
+import type { ProbeReport, SessionView } from "../types.ts";
+import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
+import { resolveEngineRouting, routeEngine, routeEngineForHost, type EngineRouteOptions, type HostRouteOptions } from "../routing.ts";
+import type { EngineRouteResult } from "../routing.ts";
 
 /** 最小可运行假引擎（probe 结果可注入）。 */
 function makeFakeEngine(id: string, probeOk: boolean): EnginePort {
@@ -24,6 +26,7 @@ function makeFakeEngine(id: string, probeOk: boolean): EnginePort {
       resume: "cold",
       interrupt: "kill-only",
       permissionMode: "native",
+      maxTurns: false,
     }),
     probe: () =>
       Promise.resolve(
@@ -36,7 +39,7 @@ function makeFakeEngine(id: string, probeOk: boolean): EnginePort {
               error: { code: "engine_probe_failed", recovery: "reinstall the engine binary and retry the probe" },
             } satisfies ProbeReport,
       ),
-    run: (_t: AgentTaskSpec, _c: RunContext) => Promise.reject(new Error("fake: run not implemented")),
+    run: (_t: AgentCallOpts, _c: RunContext) => Promise.reject(new Error("fake: run not implemented")),
     interact: () => Promise.resolve({ ok: false, code: "engine_capability_unsupported", message: "stub" }),
     read: (_h: Parameters<EnginePort["read"]>[0]): Promise<SessionView> =>
       Promise.resolve({ engineId: id, turns: [], source: "outcome-only" }),
@@ -162,9 +165,10 @@ describe("routeEngine：路由 + 探针 + 守卫编排（验收 1/2）", () => {
     expect((err as EngineError).recovery).toContain("retry the probe");
   });
 
-  it("守卫 b（首期与 a 合流）：AgentTaskSpec.requires 形状预留存在且不参与首期判定", async () => {
-    // 形状预留的类型面由 typecheck 守护；行为面：frontmatter 指定（非 call）+ 无 model
-    // → 仍走 fallback（守卫 b 独立生效留给 requires 下钻，见 types.ts 注释）
+  it("守卫 b（首期与 a 合流）：能力依赖声明无独立载体，frontmatter 指定（非 call）不阻断 fallback", async () => {
+    // [D6 合流] 原 AgentTaskSpec.requires 形状预留已随任务形状合流裁撤（无生产写入方，
+    // 见 AgentCallOpts 类型注释）；行为面保持：frontmatter 指定（非 call）+ 无 model
+    // → 仍走 fallback（能力依赖声明的独立载体留给将来下钻）
     const { opts } = makeRoute({ zcodeProbeOk: false, routing: { agentEngine: "zcode" } });
     const result = await routeEngine(opts);
     expect(result.engineFallback).toBeDefined();
@@ -229,3 +233,108 @@ describe("routeEngine：路由 + 探针 + 守卫编排（验收 1/2）", () => {
     expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
   });
 });
+
+// ============================================================
+// routeEngineForHost（D3-② 路由单点：宿主两调用点的统一编排）
+// ============================================================
+
+describe("routeEngineForHost：宿主统一路由（D3-②）", () => {
+  /** 本地 pi 引擎实例替身（chat 域 = chatPiEngine / workflow 域 = SAR per-session DI）。 */
+  function makeLocalPi(): EnginePort {
+    return makeFakeEngine("local-pi", true);
+  }
+
+  /** 装配 host 路由参数（registry 面复用 makeRoute 的注入件）。 */
+  function makeHostRoute(overrides?: Parameters<typeof makeRoute>[0]): {
+    hostOpts: HostRouteOptions;
+    probeCalls: string[];
+    engines: Map<string, EnginePort>;
+    piEngine: EnginePort;
+  } {
+    const { opts, probeCalls, engines } = makeRoute(overrides);
+    const piEngine = makeLocalPi();
+    const { routing, ...rest } = opts;
+    return { hostOpts: { ...rest, routing: routing ?? {}, piEngine }, probeCalls, engines, piEngine };
+  }
+
+  it("pi 请求（缺省）：同步短路——返回值不是 Promise（零微任务，缺省路径时序契约）且免探", () => {
+    const { hostOpts, piEngine, probeCalls } = makeHostRoute();
+    const routed = routeEngineForHost(hostOpts);
+    expect(routed).not.toBeInstanceOf(Promise);
+    const route = routed as EngineRouteResult;
+    expect(route.engine).toBe(piEngine); // 本地 pi 实例接管，不经 registry
+    expect(route.engineId).toBe("pi");
+    expect(route.source).toBe("default");
+    expect(probeCalls).toEqual([]); // pi 免探（D7 轻量口径，缺省路径零 probe 开销）
+  });
+
+  it("显式 engine='pi'：同步短路同形（call source 留痕）", () => {
+    const { hostOpts, piEngine } = makeHostRoute({ routing: { callEngine: "pi" } });
+    const routed = routeEngineForHost(hostOpts);
+    expect(routed).not.toBeInstanceOf(Promise);
+    const route = routed as EngineRouteResult;
+    expect(route.engine).toBe(piEngine);
+    expect(route.source).toBe("call");
+  });
+
+  it("非 pi 请求（frontmatter zcode + probe ok）：返回 Promise，resolve 经注入获取引擎", async () => {
+    const { hostOpts, engines } = makeHostRoute({ routing: { agentEngine: "zcode" } });
+    const routed = routeEngineForHost(hostOpts);
+    expect(routed).toBeInstanceOf(Promise);
+    const route = await routed;
+    expect(route.engine).toBe(engines.get("zcode"));
+    expect(route.engineId).toBe("zcode");
+  });
+
+  it("probe 失败兜底回 pi：本地 pi 实例接管（不依赖 registry 的 pi 注册态）+ fallback 留痕", async () => {
+    const { hostOpts, piEngine } = makeHostRoute({
+      zcodeProbeOk: false,
+      routing: { agentEngine: "zcode" },
+    });
+    const route = await routeEngineForHost(hostOpts);
+    expect(route.engine).toBe(piEngine);
+    expect(route.engineId).toBe("pi");
+    expect(route.requestedEngineId).toBe("zcode");
+    expect(route.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("registry 面未注册 pi：兜底/清单两口径都不把本地 pi 漏报（SAR 单测 mock 形态）", async () => {
+    // registry 面只含 zcode（probe 失败）——模拟「本地 pi 不在全局注册表」的注入形态
+    const engines = new Map<string, EnginePort>([["zcode", makeFakeEngine("zcode", false)]]);
+    const probeCalls: string[] = [];
+    const piEngine = makeLocalPi();
+    const mkOpts = (): HostRouteOptions => ({
+      routing: { agentEngine: "zcode" },
+      strict: false,
+      probe: (id) => {
+        probeCalls.push(id);
+        return engines.get(id)!.probe();
+      },
+      piEngine,
+      getEngineFn: (id) => {
+        const e = engines.get(id);
+        if (e === undefined) throw new EngineNotFoundError(id, [...engines.keys()]);
+        return e;
+      },
+      hasEngineFn: (id) => engines.has(id),
+      listEnginesFn: () => [...engines.keys()],
+    });
+    // probe 失败 + 无守卫 → 兜底回 pi：本地实例接管，不触 registry 的 pi 缺失
+    const route = await routeEngineForHost(mkOpts());
+    expect(route.engine).toBe(piEngine);
+    expect(route.engineId).toBe("pi");
+    expect(probeCalls).toEqual(["zcode"]);
+    // 未注册 id：engine_not_found 文案清单含 pi（本地 pi 恒可用，不漏报）
+    const ghostOpts: HostRouteOptions = {
+      ...mkOpts(),
+      routing: { callEngine: "ghost" },
+    };
+    const err = await Promise.resolve(routeEngineForHost(ghostOpts)).then(
+      (r: unknown) => r,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("engine_not_found");
+    expect((err as EngineNotFoundError).registered).toContain("pi");
+  });
+});