@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,197 @@
+// model-prompt.test.ts —— [U7] 引擎模型段注入的开关语义（defaultEngine）与段格式；
+// [engine-awareness U2] 恒在状态段三形态（zcode/pi/ghost）+ 清单段双降级文案
+// （未实现/null → 与主体系一致声明；空清单/异常 → 无凭据提示行）+ 渲染确定性（D7）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { EnginePort } from "../port.ts";
+import { clearEngines, registerEngine } from "../registry.ts";
+import { buildEngineModelsPromptAppend, buildSubagentEngineSection } from "../model-prompt.ts";
+
+/** 最小 fake 引擎：仅 id + 可选 listModels（其余面 run/read 走不到，测试只触碰注入链）。 */
+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" }),
+    run: async () => {
+      throw new Error("not used in this test");
+    },
+    interact: async () => {
+      throw new Error("not used in this test");
+    },
+    read: async () => ({ engineId: id, turns: [], source: "outcome-only" }),
+    ...(models !== null ? { listModels: () => models } : {}),
+  };
+}
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "model-prompt-"));
+  clearEngines();
+});
+
+afterEach(() => {
+  clearEngines();
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("buildEngineModelsPromptAppend（defaultEngine 开关语义）", () => {
+  it("defaultEngine 缺省 / 'pi' → 不注入（pi 段由核心提供）", () => {
+    registerEngine("zcode", () => fakeEngine("zcode", [{ id: "p/m1" }]));
+    expect(buildEngineModelsPromptAppend(undefined)).toBe("");
+    expect(buildEngineModelsPromptAppend("pi")).toBe("");
+    expect(buildEngineModelsPromptAppend("  ")).toBe("");
+  });
+
+  it("defaultEngine=zcode 且引擎实现 listModels → 注入段（含分界说明与模型 id）", () => {
+    registerEngine("zcode", () =>
+      fakeEngine("zcode", [
+        { id: "builtin:bigmodel-coding-plan/GLM-5.3", name: "Z.ai - Coding Plan · GLM-5.3" },
+        { id: "e512/mimo-v2.5-pro" },
+      ]),
+    );
+    const append = buildEngineModelsPromptAppend("zcode");
+    expect(append).toContain("<available_zcode_models>");
+    expect(append).toContain("</available_zcode_models>");
+    expect(append).toContain("<id>builtin:bigmodel-coding-plan/GLM-5.3</id>");
+    expect(append).toContain("<name>Z.ai - Coding Plan · GLM-5.3</name>");
+    expect(append).toContain("<id>e512/mimo-v2.5-pro</id>");
+    // 分界语义：pi 段的 id 不适用于本引擎
+    expect(append).toContain("do NOT apply to engine 'zcode'");
+  });
+
+  it("引擎未实现 listModels → 「与主 agent 模型体系一致」声明段（port 契约：未实现 ≠ 无模型）", () => {
+    // fakeEngine(id, null) = 不带 listModels 方法（未实现形态）
+    registerEngine("bare", () => fakeEngine("bare", null));
+    expect(buildEngineModelsPromptAppend("bare")).toBe(
+      [
+        "<available_bare_models>",
+        "engine 'bare' uses the same model registry as the main agent — use ids from <available_provider_models> above",
+        "</available_bare_models>",
+      ].join("\n"),
+    );
+    // 文案语义守卫：指向上方核心段、不含 ZCode desktop 指引（那是无凭据形态专属）
+    const append = buildEngineModelsPromptAppend("bare");
+    expect(append).toContain("use ids from <available_provider_models> above");
+    expect(append).not.toContain("ZCode desktop");
+  });
+
+  it("listModels 返回 null → 「与主 agent 模型体系一致」声明段；空清单 → 无凭据提示行段", () => {
+    // null：listModels 存在但显式返回 null——port 契约与「未实现」同语义（与主体系一致）
+    registerEngine("nul", () => ({ ...fakeEngine("nul", []), listModels: () => null }));
+    expect(buildEngineModelsPromptAppend("nul")).toBe(
+      [
+        "<available_nul_models>",
+        "engine 'nul' uses the same model registry as the main agent — use ids from <available_provider_models> above",
+        "</available_nul_models>",
+      ].join("\n"),
+    );
+    expect(buildEngineModelsPromptAppend("nul")).not.toContain("ZCode desktop");
+    // 空清单：引擎枚举面存在但当前无凭据模型——维持「无凭据 + ZCode desktop 指引」文案
+    registerEngine("empty", () => fakeEngine("empty", []));
+    expect(buildEngineModelsPromptAppend("empty")).toBe(
+      [
+        "<available_empty_models>",
+        "engine 'empty' has no credentialed models right now — configure the provider in ZCode desktop first",
+        "</available_empty_models>",
+      ].join("\n"),
+    );
+    expect(buildEngineModelsPromptAppend("empty")).toContain("<available_empty_models>");
+  });
+
+  it("未注册引擎 → 清单段不注入（警告归状态段负责，避免双份）", () => {
+    registerEngine("zcode", () => fakeEngine("zcode", [{ id: "p/m1" }]));
+    expect(buildEngineModelsPromptAppend("ghost")).toBe("");
+  });
+
+  it("listModels 抛异常 → fail-safe 输出提示行段不向外抛", () => {
+    const throwing: EnginePort = {
+      ...fakeEngine("boom", null),
+      listModels: () => {
+        throw new Error("v2 config broken");
+      },
+    };
+    registerEngine("boom", () => throwing);
+    const append = buildEngineModelsPromptAppend("boom");
+    expect(append).toContain("<available_boom_models>");
+    expect(append).toContain(
+      "engine 'boom' has no credentialed models right now — configure the provider in ZCode desktop first",
+    );
+  });
+});
+
+describe("buildSubagentEngineSection（恒在状态段三形态，§3.1 逐字基准）", () => {
+  it("defaultEngine=zcode（已注册非 pi）→ 声明 + 指向下方清单段 + AGENTS.md 冲突裁决 bullet", () => {
+    registerEngine("zcode", () => fakeEngine("zcode", [{ id: "p/m1" }]));
+    // 逐字基准：设计 §3.1 Turn 1 样例（含 AGENTS.md bullet 的 em dash 与换行拆分）
+    expect(buildSubagentEngineSection("zcode")).toBe(
+      [
+        "<current_subagent_engine>",
+        "Default engine for subagent dispatches when neither the call's `engine` param",
+        "nor an agent .md `engine` frontmatter overrides: zcode",
+        "- Model ids for zcode dispatches are listed in <available_zcode_models> below.",
+        "  Ids in <available_provider_models> do NOT apply to zcode dispatches.",
+        "- Omit `model` to use the engine default.",
+        "- If AGENTS.md or other standing guidance names model ids from the pi registry",
+        "  (e.g. zai-coding-cn/*), those ids apply to pi-engine dispatches ONLY — when",
+        "  the current engine is not pi, use only ids from the engine section below.",
+        "</current_subagent_engine>",
+      ].join("\n"),
+    );
+  });
+
+  it("defaultEngine=pi / 缺省 / 空白 → 声明 pi + 指向上方核心段（无冲突 bullet）", () => {
+    // pi 形态不依赖注册表（缺省形态注册表为空也成立）
+    const expected = [
+      "<current_subagent_engine>",
+      "Default engine for subagent dispatches when neither the call's `engine` param",
+      "nor an agent .md `engine` frontmatter overrides: pi",
+      "- Model ids for pi dispatches are the ids in <available_provider_models> above.",
+      "- Omit `model` to use the engine default.",
+      "</current_subagent_engine>",
+    ].join("\n");
+    expect(buildSubagentEngineSection("pi")).toBe(expected);
+    expect(buildSubagentEngineSection(undefined)).toBe(expected);
+    expect(buildSubagentEngineSection("  ")).toBe(expected);
+  });
+
+  it("defaultEngine=未注册引擎（ghost）→ 显示配置值 + 未注册警告行（失败路径表逐字）", () => {
+    // 注册表里有其他引擎也不能让 ghost 误判为已注册
+    registerEngine("zcode", () => fakeEngine("zcode", [{ id: "p/m1" }]));
+    expect(buildSubagentEngineSection("ghost")).toBe(
+      [
+        "<current_subagent_engine>",
+        "Default engine for subagent dispatches when neither the call's `engine` param",
+        "nor an agent .md `engine` frontmatter overrides: ghost",
+        "- engine 'ghost' is not registered — dispatches will fail at routing; fix subagents/config.json",
+        "</current_subagent_engine>",
+      ].join("\n"),
+    );
+  });
+
+  it("渲染确定性（D7）：同输入两次调用输出逐字节相等", () => {
+    registerEngine("zcode", () => fakeEngine("zcode", [{ id: "a/m1" }, { id: "b/m2" }]));
+    const inputs: Array<string | undefined> = ["zcode", "pi", "ghost", undefined];
+    for (const input of inputs) {
+      // 字符串 toBe = 逐 UTF-16 码元值比较，即「同输入恒同输出」的字节稳定契约
+      expect(buildSubagentEngineSection(input)).toBe(buildSubagentEngineSection(input));
+      // 独立两次取值再比一次，排除实现内共享可变状态的可能
+      const first = buildSubagentEngineSection(input);
+      const second = buildSubagentEngineSection(input);
+      expect(second).toBe(first);
+    }
+    expect(buildEngineModelsPromptAppend("zcode")).toBe(buildEngineModelsPromptAppend("zcode"));
+    expect(buildEngineModelsPromptAppend("pi")).toBe(buildEngineModelsPromptAppend("pi"));
+    // 新降级形态（U2 修订）确定性：「与主体系一致」声明段同输入恒同输出
+    registerEngine("shared", () => fakeEngine("shared", null));
+    registerEngine("nulled", () => ({ ...fakeEngine("nulled", []), listModels: () => null }));
+    expect(buildEngineModelsPromptAppend("shared")).toBe(buildEngineModelsPromptAppend("shared"));
+    expect(buildEngineModelsPromptAppend("nulled")).toBe(buildEngineModelsPromptAppend("nulled"));
+  });
+});

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

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  resolveEngineDir,
+  resolveEnginesRoot,
+  resolveJournalPath,
+  resolvePoolDir,
+  sanitizeSeg,
+} from '../paths.js';
+
+describe('engine paths SSOT', () => {
+  it('engines 根锚定 dataDir 顶层', () => {
+    expect(resolveEnginesRoot('/data')).toBe('/data/engines');
+  });
+
+  it('池目录 = engines/<engineId>/<poolKey>', () => {
+    expect(resolvePoolDir('/data', 'zcode', 'home-reviewer')).toBe('/data/engines/zcode/home-reviewer');
+    expect(resolveEngineDir('/data', 'zcode')).toBe('/data/engines/zcode');
+  });
+
+  it('journal 路径带 taskId 文件名', () => {
+    expect(resolveJournalPath('/data', 'zcode', 'pool1', 'sa-123')).toBe(
+      '/data/engines/zcode/pool1/journal-sa-123.jsonl',
+    );
+  });
+
+  it('路径段安全编码：穿越/分隔符/空白折叠为连字符', () => {
+    expect(sanitizeSeg('a/b\\c')).toBe('a-b-c');
+    expect(sanitizeSeg('..')).toBe('default');
+    expect(sanitizeSeg('  ')).toBe('default');
+    expect(sanitizeSeg('home-reviewer')).toBe('home-reviewer');
+    expect(sanitizeSeg('中文名')).toBe('default');
+    expect(sanitizeSeg('x'.repeat(200))).toHaveLength(80);
+  });
+
+  it('engineId 也走安全编码，防注入路径段', () => {
+    expect(resolvePoolDir('/data', '../../etc', 'p')).toBe('/data/engines/etc/p');
+  });
+});

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

@@ -0,0 +1,120 @@
+// src/execution/engine/__tests__/registry.test.ts
+//
+// registry 专属测试（P1 验收 4）：注册/获取/listEngines/hasEngine/
+// 未注册 id 报 engine_not_found（错误文案含已注册清单——错误规格表第 1 行契约）。
+
+import { beforeEach, describe, expect, it } from "vitest";
+
+import type { EnginePort, RunContext } from "../port.ts";
+import {
+  clearEngines,
+  DEFAULT_ENGINE_ID,
+  EngineNotFoundError,
+  getEngine,
+  hasEngine,
+  listEngines,
+  registerEngine,
+} from "../registry.ts";
+import type { AgentTaskSpec, SessionView } from "../types.ts";
+
+/** 最小可运行假引擎（完整实现 EnginePort 五面——不 cast，防接口漂移失检）。 */
+function makeFakeEngine(id: string): EnginePort {
+  return {
+    id,
+    capabilities: () => ({
+      schemaEnforcement: "native",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "unsupported",
+      interrupt: "kill-only",
+      permissionMode: "fixed",
+    }),
+    probe: () =>
+      Promise.resolve({ ok: true, engineVersion: "0.0.0-test", checks: [{ name: "stub", ok: true }] }),
+    run: (_task: AgentTaskSpec, _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> =>
+      Promise.resolve({ engineId: id, turns: [], source: "outcome-only" }),
+  };
+}
+
+describe("engine registry", () => {
+  beforeEach(() => {
+    // 测试隔离：registry 是进程级全局状态，防用例间工厂/单例泄漏串扰
+    clearEngines();
+  });
+
+  it("registerEngine + getEngine：按 id 取回引擎实例", () => {
+    registerEngine("fake", () => makeFakeEngine("fake"));
+    const engine = getEngine("fake");
+    expect(engine.id).toBe("fake");
+  });
+
+  it("getEngine 惰性单例：同一 id 重复获取返回同一实例（§3.3.1 registry 持 per-engine 单例）", () => {
+    let created = 0;
+    registerEngine("fake", () => {
+      created++;
+      return makeFakeEngine("fake");
+    });
+    const a = getEngine("fake");
+    const b = getEngine("fake");
+    expect(a).toBe(b);
+    expect(created).toBe(1);
+  });
+
+  it("registerEngine 覆盖同 id：丢弃旧单例，下次 getEngine 用新工厂重建（幂等重注册）", () => {
+    registerEngine("fake", () => makeFakeEngine("fake"));
+    const first = getEngine("fake");
+    registerEngine("fake", () => makeFakeEngine("fake-v2"));
+    const second = getEngine("fake");
+    expect(second).not.toBe(first);
+    expect(second.id).toBe("fake-v2");
+  });
+
+  it("listEngines 返回注册序清单，hasEngine 判注册态（不触发工厂副作用）", () => {
+    let created = 0;
+    registerEngine("alpha", () => {
+      created++;
+      return makeFakeEngine("alpha");
+    });
+    registerEngine("beta", () => makeFakeEngine("beta"));
+    expect(listEngines()).toEqual(["alpha", "beta"]);
+    expect(hasEngine("alpha")).toBe(true);
+    expect(hasEngine("gamma")).toBe(false);
+    // hasEngine 不取实例——工厂未执行
+    expect(created).toBe(0);
+  });
+
+  it("未注册 id → EngineNotFoundError（code=engine_not_found，文案含已注册清单）", () => {
+    registerEngine("pi", () => makeFakeEngine("pi"));
+    let caught: unknown;
+    try {
+      getEngine("zcode");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(EngineNotFoundError);
+    if (!(caught instanceof EngineNotFoundError)) throw new Error("unreachable");
+    expect(caught.code).toBe("engine_not_found");
+    expect(caught.engineId).toBe("zcode");
+    // 错误规格表第 1 行契约：指向注册表清单 + 配置文件路径
+    expect(caught.message).toContain("engine_not_found");
+    expect(caught.message).toContain("'zcode'");
+    expect(caught.message).toContain("pi");
+    expect(caught.message).toContain("frontmatter");
+  });
+
+  it("空注册表时未注册 id 错误不崩（清单为 none）", () => {
+    expect(() => getEngine("anything")).toThrow(EngineNotFoundError);
+    expect(() => getEngine("anything")).toThrow(/\(none\)/);
+  });
+
+  it("DEFAULT_ENGINE_ID 缺省为 'pi'（D9：回填期零风险默认）", () => {
+    expect(DEFAULT_ENGINE_ID).toBe("pi");
+  });
+});

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

@@ -0,0 +1,231 @@
+// routing.test.ts —— P4 配置路由三层 + probe fallback 三守卫 + strict（验收 1/2 的
+// 单测面）。fake probe/getEngine 注入（不依赖真机引擎与真实探针）。
+
+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";
+
+/** 最小可运行假引擎（probe 结果可注入）。 */
+function makeFakeEngine(id: string, probeOk: boolean): EnginePort {
+  return {
+    id,
+    capabilities: () => ({
+      schemaEnforcement: "emulated",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "cold",
+      interrupt: "kill-only",
+      permissionMode: "native",
+    }),
+    probe: () =>
+      Promise.resolve(
+        probeOk
+          ? { ok: true, engineVersion: "1.0.0", checks: [{ name: "stub", ok: true }] }
+          : {
+              ok: false,
+              engineVersion: "",
+              checks: [{ name: "binary", ok: false, detail: "missing" }],
+              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")),
+    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" }),
+  };
+}
+
+/** routeEngine 的装配器：注册 {pi:ok, zcode:probeOk} 两引擎。 */
+function makeRoute(overrides?: {
+  zcodeProbeOk?: boolean;
+  strict?: boolean;
+  routing?: Partial<EngineRouteOptions["routing"]>;
+  taskModel?: string;
+  /** 额外注册第三引擎（probe ok）——fallback 目标为「非 pi 的其他全局默认」用例。 */
+  globalEngine?: string;
+}) {
+  const engines = new Map<string, EnginePort>();
+  engines.set(DEFAULT_ENGINE_ID, makeFakeEngine("pi", true));
+  engines.set("zcode", makeFakeEngine("zcode", overrides?.zcodeProbeOk ?? true));
+  if (overrides?.globalEngine !== undefined) {
+    engines.set(overrides.globalEngine, makeFakeEngine(overrides.globalEngine, true));
+  }
+  const probeCalls: string[] = [];
+  const opts: EngineRouteOptions = {
+    routing: overrides?.routing ?? {},
+    taskModel: overrides?.taskModel,
+    strict: overrides?.strict ?? false,
+    probe: (id) => {
+      probeCalls.push(id);
+      return engines.get(id)!.probe();
+    },
+    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()],
+  };
+  return { opts, probeCalls, engines };
+}
+
+// ── 三层优先级（验收 1）──
+
+describe("resolveEngineRouting：三层优先级", () => {
+  it("无任何指定 → 全局缺省 'pi'", () => {
+    expect(resolveEngineRouting({})).toEqual({ engineId: "pi", source: "default" });
+  });
+
+  it("全局默认引擎指定（config defaultEngine=zcode）→ zcode", () => {
+    expect(resolveEngineRouting({ globalDefaultEngine: "zcode" })).toEqual({ engineId: "zcode", source: "default" });
+  });
+
+  it("frontmatter 指定 > 全局默认", () => {
+    expect(resolveEngineRouting({ agentEngine: "zcode", globalDefaultEngine: "pi" })).toEqual({
+      engineId: "zcode",
+      source: "frontmatter",
+    });
+  });
+
+  it("调用参数 > frontmatter > 全局默认（三层全设时调用参数胜）", () => {
+    expect(
+      resolveEngineRouting({ callEngine: "pi", agentEngine: "zcode", globalDefaultEngine: "zcode" }),
+    ).toEqual({ engineId: "pi", source: "call" });
+  });
+
+  it("空串视为未指定（AgentCallOpts.engine='' 落下一层）", () => {
+    expect(resolveEngineRouting({ callEngine: "", agentEngine: "zcode" })).toEqual({
+      engineId: "zcode",
+      source: "frontmatter",
+    });
+  });
+});
+
+describe("routeEngine：路由 + 探针 + 守卫编排（验收 1/2）", () => {
+  it("缺省 pi：免探（零行为变化口径）直接返回引擎", async () => {
+    const { opts, probeCalls, engines } = makeRoute();
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("pi"));
+    expect(result.engineId).toBe("pi");
+    expect(result.engineFallback).toBeUndefined();
+    expect(probeCalls).toEqual([]); // pi 缺省路径不探（D7 轻量口径）
+  });
+
+  it("frontmatter 指定 zcode + probe ok：返回 zcode 引擎，无 fallback", async () => {
+    const { opts, probeCalls, engines } = makeRoute({ routing: { agentEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("zcode"));
+    expect(result.engineId).toBe("zcode");
+    expect(result.engineFallback).toBeUndefined();
+    expect(probeCalls).toEqual(["zcode"]);
+  });
+
+  it("调用参数指定 zcode：覆盖 frontmatter 的 pi（透传链 A7）", async () => {
+    const { opts } = makeRoute({ routing: { callEngine: "zcode", agentEngine: "pi" } });
+    const result = await routeEngine(opts);
+    expect(result.engineId).toBe("zcode");
+    expect(result.source).toBe("call");
+  });
+
+  it("未注册 id（调用参数层）：engine_not_found，文案含注册清单（前置暴露）", async () => {
+    const { opts } = makeRoute({ routing: { callEngine: "nonexistent" } });
+    await expect(routeEngine(opts)).rejects.toThrowError(EngineNotFoundError);
+    await expect(routeEngine(opts)).rejects.toThrowError(/Registered engines: pi, zcode/);
+  });
+
+  // ── fallback 与三守卫（验收 2）──
+
+  it("frontmatter 指定 zcode + probe 失败 → 路由回 pi + engineFallback 留痕（A9①）", async () => {
+    const { opts, engines } = makeRoute({ zcodeProbeOk: false, routing: { agentEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("pi"));
+    expect(result.engineId).toBe("pi");
+    expect(result.requestedEngineId).toBe("zcode");
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("守卫 a：调用参数显式指定 + probe 失败 → 不兜底，报 engine_probe_failed", async () => {
+    const { opts } = makeRoute({ zcodeProbeOk: false, routing: { callEngine: "zcode" } });
+    const err = await routeEngine(opts).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(EngineError);
+    expect((err as EngineError).code).toBe("engine_probe_failed");
+    expect((err as EngineError).message).toContain("调用参数显式指定");
+    expect((err as EngineError).recovery).toContain("retry the probe");
+  });
+
+  it("守卫 b（首期与 a 合流）：AgentTaskSpec.requires 形状预留存在且不参与首期判定", async () => {
+    // 形状预留的类型面由 typecheck 守护；行为面：frontmatter 指定（非 call）+ 无 model
+    // → 仍走 fallback（守卫 b 独立生效留给 requires 下钻，见 types.ts 注释）
+    const { opts } = makeRoute({ zcodeProbeOk: false, routing: { agentEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engineFallback).toBeDefined();
+  });
+
+  it("守卫 c：显式 model + probe 失败 → 不换引擎，报 model_not_available", async () => {
+    const { opts } = makeRoute({
+      zcodeProbeOk: false,
+      routing: { agentEngine: "zcode" },
+      taskModel: "builtin:bigmodel-coding-plan/GLM-5.3",
+    });
+    const err = await routeEngine(opts).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(EngineError);
+    expect((err as EngineError).code).toBe("model_not_available");
+    expect((err as EngineError).message).toContain("GLM-5.3");
+  });
+
+  it("守卫 c 不误伤：无显式 model 时 probe 失败正常 fallback", async () => {
+    const { opts } = makeRoute({ zcodeProbeOk: false, routing: { agentEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engineId).toBe("pi");
+  });
+
+  it("strict=true：frontmatter 层 probe 失败也直接报 engine_probe_failed（A5）", async () => {
+    const { opts } = makeRoute({ zcodeProbeOk: false, strict: true, routing: { agentEngine: "zcode" } });
+    const err = await routeEngine(opts).catch((e: unknown) => e);
+    expect((err as EngineError).code).toBe("engine_probe_failed");
+    expect((err as EngineError).message).toContain("strict");
+  });
+
+  it("全局默认引擎自身 probe 失败（defaultEngine=zcode）：fallback 回内置 pi", async () => {
+    const { opts } = makeRoute({ zcodeProbeOk: false, routing: { globalDefaultEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engineId).toBe("pi");
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("frontmatter zcode + config 默认同为 zcode + probe 失败：fallback 回 pi（不回退同一坏引擎）", async () => {
+    // review MF3 回归：全局默认 === 请求引擎时，fallback 目标不得 = 刚 probe 失败的
+    // 引擎（from==to 原地重试坏引擎 + 误导留痕）——回内置缺省 pi
+    const { opts, engines } = makeRoute({
+      zcodeProbeOk: false,
+      routing: { agentEngine: "zcode", globalDefaultEngine: "zcode" },
+    });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("pi"));
+    expect(result.engineId).toBe("pi");
+    expect(result.requestedEngineId).toBe("zcode");
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("frontmatter zcode + config 默认为其他引擎：probe 失败回全局默认（既有行为不回归）", async () => {
+    // 全局默认 ≠ 请求引擎且非 pi：fallback 目标仍是全局默认（相等比较只拦截 from==to 形态）
+    const { opts, engines } = makeRoute({
+      zcodeProbeOk: false,
+      globalEngine: "claude",
+      routing: { agentEngine: "zcode", globalDefaultEngine: "claude" },
+    });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("claude"));
+    expect(result.engineId).toBe("claude");
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+});

package/src/execution/engine/common/data-dir.ts

@@ -0,0 +1,66 @@
+// src/execution/engine/common/data-dir.ts
+//
+// 引擎数据目录解析（P2）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D5/D6——engines 根锚定 getDataDir()
+// 顶层（journal / 隔离池的父目录），extension 写侧与 runtime 校验侧同源推导。
+//
+// 通道调查结论（2026-08-25，P2 实测证据链）：
+//   - runtime spawn pi 主会话时 RpcClient.buildSafeEnv 从 runtime process.env 继承
+//     XYZ_ 前缀白名单变量（rpc-client.ts:14-30），且显式设置 PI_CODING_AGENT_DIR；
+//   - dev 模式 Electron main 设置 XYZ_AGENT_DATA_DIR（apps/electron/main/main.ts:122），
+//     经 process-control.ts:262 透传给 runtime → 透传链成立；
+//   - prod 默认路径（~/.xyz-agent 缺省）下 runtime 进程 env 中**没有**该变量
+//     （shared getDataDir 缺省时不写 env）→ 透传链断——已在 runtime 侧
+//     process-manager.ts spawn env 补注入 XYZ_AGENT_DATA_DIR 修复（跨包改动）。
+//
+// 回退语义与分段归属（u0-data-discovery，设计 D2 计划期细化③）：缺 env 时回退宿主
+// 数据根（getHostServices().dataRoot()——pi 壳返回 getAgentDir()，尊重
+// PI_CODING_AGENT_DIR 实例隔离，独立 pi 用户直跑 extension 的场景不漂目录）并 warn
+// 一次——不留静默漂移（journal 落点变化必须可观测）。本文件保留 env 优先段与
+// warn-once 语义，壳不重复实现；未 configureCore 即消费 dataRoot 抛
+// core_host_not_configured（显式报错取代缺省静默漂目录）。
+
+import { getHostServices } from "../../../core/host-services.ts";
+import { getLogger } from "../../../core/logger.ts";
+
+const logger = getLogger("subagents");
+
+/** xyz-agent 数据目录 env 名（与 packages/shared/src/paths.ts 的 SSOT 变量同名）。 */
+export const XYZ_DATA_DIR_ENV = "XYZ_AGENT_DATA_DIR";
+
+/** 测试隔离专用：重置 warn-once 标记（生产禁用）。 */
+let warned = false;
+export function resetDataDirWarnForTests(): void {
+  warned = false;
+}
+
+/**
+ * 解析引擎数据目录（journal 落盘 / 隔离池的根）：
+ *   1. process.env.XYZ_AGENT_DATA_DIR（xyz-agent 宿主注入，权威通道）；
+ *   2. 缺失 → 宿主数据根（getHostServices().dataRoot()）+ warn 一次。
+ * 每次调用重新解析（env 读取是零成本操作，不缓存路径防测试/宿主切换时读到旧值）。
+ */
+export function getEngineDataDir(
+  env: NodeJS.ProcessEnv = process.env,
+  warn: (msg: string) => void = defaultWarn,
+): string {
+  const fromEnv = env[XYZ_DATA_DIR_ENV]?.trim();
+  if (fromEnv !== undefined && fromEnv !== "") return fromEnv;
+
+  // warn 文案与 fallback 值逐字保留现语义（零行为变化）：pi 壳 dataRoot() 现取
+  // getAgentDir()，落点与改造前一致；zsw 壳接入后此处自动跟随其数据根。
+  const fallback = getHostServices().dataRoot();
+  if (!warned) {
+    warned = true;
+    warn(
+      `[engine-data-dir] ${XYZ_DATA_DIR_ENV} is not set; engine journal/pool fall back to the pi agent dir ` +
+        `(${fallback}). The xyz-agent host normally injects this env — if you are running inside xyz-agent, ` +
+        `check the runtime spawn env; standalone pi installs intentionally use the pi agent dir.`,
+    );
+  }
+  return fallback;
+}
+
+function defaultWarn(msg: string): void {
+  logger.warn(msg);
+}