@zhushanwen/subagent-core 0.2.0

package/src/execution/engine/engines/zcode/__tests__/preparer.test.ts

@@ -0,0 +1,228 @@
+// preparer.test.ts —— 池目录 SSOT / 原子写 / mtime 免重写 / 无 plugins 块 / 凭据与模型
+// 前置错误（验收 3）。凭据源 = v2 config 单源（2026-08-25 拍板：不读
+// ~/.zcode/cli/config.json——GUI 不管理该文件，可能残留历史验证配置）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { resolvePoolDir } from "../../../paths.ts";
+import {
+  ZcodePrepareError,
+  computeZcodePoolKey,
+  listZcodeModels,
+  prepareZcodeHome,
+  resolveZcodeModelRef,
+} from "../preparer.ts";
+
+let tmpRoot: string;
+let dataDir: string;
+let v2Path: string;
+
+function writeJson(p: string, v: unknown): void {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(v, null, 2));
+}
+
+const PROVIDER_A = "builtin:bigmodel-coding-plan";
+const PROVIDER_B = "e512d53e-test-provider";
+
+function seedSources(): void {
+  writeJson(v2Path, {
+    provider: {
+      [PROVIDER_A]: { options: { apiKey: "key-a", baseURL: "https://a.example" }, models: { "GLM-5.3": {}, "GLM-5.2": {} } },
+      [PROVIDER_B]: { name: "test-router", options: { apiKey: "key-b", baseURL: "https://b.example" }, models: { "mimo-v2.5-pro": {} } },
+      "no-key-provider": { options: { baseURL: "https://x.example" }, models: { "M1": {} } },
+    },
+  });
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-preparer-"));
+  dataDir = path.join(tmpRoot, "data");
+  v2Path = path.join(tmpRoot, "v2-config.json");
+  seedSources();
+});
+
+describe("resolveZcodeModelRef（v2 单源）", () => {
+  it("显式全名解析 + 规范化", () => {
+    expect(resolveZcodeModelRef(`${PROVIDER_B}/mimo-v2.5-pro`, { v2ConfigPath: v2Path })).toBe(
+      `${PROVIDER_B}/mimo-v2.5-pro`,
+    );
+  });
+
+  it("短名按默认 provider（builtin:bigmodel-coding-plan）解析", () => {
+    expect(resolveZcodeModelRef("GLM-5.3", { v2ConfigPath: v2Path })).toBe(
+      `${PROVIDER_A}/GLM-5.3`,
+    );
+  });
+
+  it("未指定时落官方兜底（不受任何本机 CLI 配置影响）", () => {
+    expect(resolveZcodeModelRef(undefined, { v2ConfigPath: v2Path })).toBe(
+      `${PROVIDER_A}/GLM-5.3`,
+    );
+  });
+
+  it("未知模型 → model_not_available（列该 provider 可用模型）", () => {
+    try {
+      resolveZcodeModelRef(`${PROVIDER_A}/nope`, { v2ConfigPath: v2Path });
+      expect.unreachable("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(ZcodePrepareError);
+      const e = err as ZcodePrepareError;
+      expect(e.code).toBe("model_not_available");
+      expect(e.message).toContain("GLM-5.3, GLM-5.2");
+    }
+  });
+
+  it("未知 provider → model_not_available（列带凭据 provider）", () => {
+    try {
+      resolveZcodeModelRef("ghost/m", { v2ConfigPath: v2Path });
+      expect.unreachable("should throw");
+    } catch (err) {
+      expect((err as ZcodePrepareError).code).toBe("model_not_available");
+      expect((err as ZcodePrepareError).message).toContain(PROVIDER_A);
+      expect((err as ZcodePrepareError).message).toContain(PROVIDER_B);
+    }
+  });
+
+  it("provider 存在但无 apiKey → engine_credential_missing", () => {
+    try {
+      resolveZcodeModelRef("no-key-provider/M1", { v2ConfigPath: v2Path });
+      expect.unreachable("should throw");
+    } catch (err) {
+      expect((err as ZcodePrepareError).code).toBe("engine_credential_missing");
+    }
+  });
+
+  it("v2 无任何带 apiKey 的 provider → engine_credential_missing（指向配置说明）", () => {
+    writeJson(v2Path, { provider: {} });
+    try {
+      resolveZcodeModelRef(undefined, { v2ConfigPath: v2Path });
+      expect.unreachable("should throw");
+    } catch (err) {
+      const e = err as ZcodePrepareError;
+      expect(e.code).toBe("engine_credential_missing");
+      expect(e.message).toContain("ZCode 桌面端");
+      expect(e.message).toContain("docs/research/agent-engine-zcode.md");
+    }
+  });
+});
+
+describe("listZcodeModels（U7 可发现性）", () => {
+  it("聚合 v2 带凭据 provider × models（含 name 拼接），无凭据/空清单过滤", () => {
+    const models = listZcodeModels({ v2ConfigPath: v2Path });
+    const ids = models.map((m) => m.id);
+    expect(ids).toContain(`${PROVIDER_A}/GLM-5.3`);
+    expect(ids).toContain(`${PROVIDER_A}/GLM-5.2`);
+    expect(ids).toContain(`${PROVIDER_B}/mimo-v2.5-pro`);
+    // 无凭据 provider 不进清单
+    expect(ids.some((id) => id.startsWith("no-key-provider/"))).toBe(false);
+    // name = "<provider.name> · <model>"（v2 有 name 字段时）
+    const withName = models.find((m) => m.id === `${PROVIDER_B}/mimo-v2.5-pro`);
+    expect(withName?.name).toBe("test-router · mimo-v2.5-pro");
+  });
+
+  it("v2 不可读 → 空清单（fail-safe）", () => {
+    expect(listZcodeModels({ v2ConfigPath: path.join(tmpRoot, "absent.json") })).toEqual([]);
+  });
+});
+
+describe("computeZcodePoolKey", () => {
+  it("provider 特殊字符安全化 + model 短名保留点号（zsub homePoolDir 同构）", () => {
+    expect(computeZcodePoolKey("builtin:bigmodel-coding-plan/GLM-5.3")).toBe(
+      "home-builtin-bigmodel-coding-plan-GLM-5.3",
+    );
+    expect(computeZcodePoolKey("router/mimo-v2.5-pro")).toBe("home-router-mimo-v2.5-pro");
+  });
+});
+
+describe("prepareZcodeHome（验收 3）", () => {
+  it("池目录 = resolvePoolDir SSOT，config.json 原子写且无 plugins 块", () => {
+    const prepared = prepareZcodeHome({
+      engineDataDir: dataDir,
+      modelRef: `${PROVIDER_A}/GLM-5.3`,
+      sources: { v2ConfigPath: v2Path },
+    });
+    expect(prepared.wroteConfig).toBe(true);
+    // 池目录必须与 paths.ts SSOT 同源（禁自拼）
+    expect(prepared.homeDir).toBe(resolvePoolDir(dataDir, "zcode", prepared.poolKey));
+    expect(prepared.poolKey).toBe("home-builtin-bigmodel-coding-plan-GLM-5.3");
+
+    const written = JSON.parse(fs.readFileSync(prepared.configPath, "utf8")) as Record<string, unknown>;
+    expect(written["model"]).toEqual({ main: `${PROVIDER_A}/GLM-5.3` });
+    expect(Object.keys(written["provider"] as Record<string, unknown>)).toEqual([PROVIDER_A]);
+    // 第二重门禁：刻意不写 plugins 块（防递归 + 不加载宿主插件）
+    expect("plugins" in written).toBe(false);
+    // 原子写：无 tmp 残留
+    const leftovers = fs.readdirSync(path.dirname(prepared.configPath)).filter((f) => f.includes(".tmp-"));
+    expect(leftovers).toEqual([]);
+    // 只写目标 provider（每池单 provider 单模型，凭据落盘面最小）
+    const providerEntry = (written["provider"] as Record<string, { options?: { apiKey?: string } }>)[PROVIDER_A]!;
+    expect(providerEntry.options?.apiKey).toBe("key-a");
+  });
+
+  it("mtime 比对免重写：源未变时第二次 prepare 零写入", () => {
+    const opts = {
+      engineDataDir: dataDir,
+      modelRef: `${PROVIDER_A}/GLM-5.3`,
+      sources: { v2ConfigPath: v2Path },
+    };
+    const first = prepareZcodeHome(opts);
+    expect(first.wroteConfig).toBe(true);
+    const statAfterFirst = fs.statSync(first.configPath);
+    const second = prepareZcodeHome(opts);
+    expect(second.wroteConfig).toBe(false);
+    expect(fs.statSync(second.configPath).mtimeMs).toBe(statAfterFirst.mtimeMs);
+  });
+
+  it("源 config 变新（mtime 推进）触发重写（凭据刷新传播）", async () => {
+    const opts = {
+      engineDataDir: dataDir,
+      modelRef: `${PROVIDER_A}/GLM-5.3`,
+      sources: { v2ConfigPath: v2Path },
+    };
+    prepareZcodeHome(opts);
+    // 源 mtime 推到未来（模拟桌面端刷新 apiKey）
+    const future = new Date(Date.now() + 10_000);
+    fs.utimesSync(v2Path, future, future);
+    const again = prepareZcodeHome(opts);
+    expect(again.wroteConfig).toBe(true);
+  });
+
+  it("池 config 损坏（torn write 形态）时重建", () => {
+    const opts = {
+      engineDataDir: dataDir,
+      modelRef: `${PROVIDER_A}/GLM-5.3`,
+      sources: { v2ConfigPath: v2Path },
+    };
+    const first = prepareZcodeHome(opts);
+    fs.writeFileSync(first.configPath, "{ torn", "utf8");
+    const again = prepareZcodeHome(opts);
+    expect(again.wroteConfig).toBe(true);
+    expect(() => JSON.parse(fs.readFileSync(again.configPath, "utf8"))).not.toThrow();
+  });
+
+  it("v2 注册表内非默认 provider（如自定义 UUID provider）也能建池", () => {
+    const prepared = prepareZcodeHome({
+      engineDataDir: dataDir,
+      modelRef: `${PROVIDER_B}/mimo-v2.5-pro`,
+      sources: { v2ConfigPath: v2Path },
+    });
+    const written = JSON.parse(fs.readFileSync(prepared.configPath, "utf8")) as {
+      provider: Record<string, { options?: { apiKey?: string } }>;
+    };
+    expect(written.provider[PROVIDER_B]!.options?.apiKey).toBe("key-b");
+  });
+
+  it("模型引用在 v2 不存在 → model_not_available", () => {
+    try {
+      prepareZcodeHome({ engineDataDir: dataDir, modelRef: "ghost/m", sources: { v2ConfigPath: v2Path } });
+      expect.unreachable("should throw");
+    } catch (err) {
+      expect((err as ZcodePrepareError).code).toBe("model_not_available");
+    }
+  });
+});

package/src/execution/engine/engines/zcode/__tests__/reader.test.ts

@@ -0,0 +1,210 @@
+// reader.test.ts —— sqlite 只读 SessionView（验收 4 的 mock 半边：真实 node:sqlite 建库
+// → turns/usage/toolCalls 派生；db 缺失/表漂移 → 结构化错误供降级）。真机半边（实录池
+// 内 db）在 zcode-engine.live.test.ts。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { readZcodeSessionView, ZcodeReaderError } from "../reader.ts";
+
+let tmpDir: string;
+let dbPath: string;
+
+// 建出与 zcode 0.16.5 同形的三表最小 schema（列裁剪到 reader 消费面）
+async function createDb(file: string): Promise<void> {
+  const { DatabaseSync } = (await import("node:sqlite")) as { DatabaseSync: new (p: string) => unknown };
+  type Db = {
+    exec: (s: string) => void;
+    prepare: (s: string) => { run: (...a: unknown[]) => void };
+    close: () => void;
+  };
+  const db = new DatabaseSync(file) as unknown as Db;
+  db.exec(
+    "CREATE TABLE session (id TEXT PRIMARY KEY, time_created INTEGER);" +
+      "CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT, sequence INTEGER, data TEXT);" +
+      "CREATE TABLE part (id TEXT PRIMARY KEY, message_id TEXT, session_id TEXT, sequence INTEGER, data TEXT);",
+  );
+  const insertMessage = db.prepare("INSERT INTO message (id, session_id, sequence, data) VALUES (?, ?, ?, ?)");
+  const insertPart = db.prepare("INSERT INTO part (id, message_id, session_id, sequence, data) VALUES (?, ?, ?, ?, ?)");
+
+  // session 1（目标）：user prompt + assistant 两轮（text/reasoning/tool/step-finish×2）
+  db.prepare("INSERT INTO session (id, time_created) VALUES (?, ?)").run("sess_target", 2000);
+  insertMessage.run("msg_user", "sess_target", 0, JSON.stringify({ role: "user" }));
+  insertPart.run("part_user_text", "msg_user", "sess_target", 0, JSON.stringify({ type: "text", text: "the task" }));
+
+  insertMessage.run("msg_asst", "sess_target", 1, JSON.stringify({ role: "assistant" }));
+  insertPart.run("p0", "msg_asst", "sess_target", 0, JSON.stringify({ type: "step-start" }));
+  insertPart.run("p1", "msg_asst", "sess_target", 1, JSON.stringify({ type: "reasoning", text: "thinking hard" }));
+  insertPart.run(
+    "p2",
+    "msg_asst",
+    "sess_target",
+    2,
+    JSON.stringify({
+      type: "tool",
+      tool: "Bash",
+      state: JSON.stringify({ status: "completed", input: { command: "ls" }, output: "file-a\nfile-b" }),
+    }),
+  );
+  insertPart.run(
+    "p3",
+    "msg_asst",
+    "sess_target",
+    3,
+    JSON.stringify({
+      type: "step-finish",
+      reason: "stop",
+      cost: 0,
+      tokens: { total: 110, input: 100, output: 10, reasoning: 0, cache: { read: 5, write: 0 } },
+    }),
+  );
+  // 第二轮（同 assistant message 内第二个 step 段）
+  insertPart.run("p4", "msg_asst", "sess_target", 4, JSON.stringify({ type: "text", text: "final answer" }));
+  insertPart.run(
+    "p5",
+    "msg_asst",
+    "sess_target",
+    5,
+    JSON.stringify({
+      type: "step-finish",
+      reason: "stop",
+      cost: 0.5,
+      tokens: { total: 60, input: 50, output: 10, reasoning: 0, cache: { read: 0, write: 0 } },
+    }),
+  );
+
+  // session 2（更早）：验证「缺省取最新」与定向读取互不干扰
+  db.prepare("INSERT INTO session (id, time_created) VALUES (?, ?)").run("sess_older", 1000);
+  insertMessage.run("msg_old", "sess_older", 0, JSON.stringify({ role: "assistant" }));
+  insertPart.run("part_old", "msg_old", "sess_older", 0, JSON.stringify({ type: "text", text: "old turn" }));
+  insertPart.run(
+    "part_old2",
+    "msg_old",
+    "sess_older",
+    1,
+    JSON.stringify({ type: "step-finish", tokens: { input: 1, output: 1, cache: {} } }),
+  );
+  db.close();
+}
+
+beforeAll(async () => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-reader-"));
+  dbPath = path.join(tmpDir, "db.sqlite");
+  await createDb(dbPath);
+});
+
+describe("readZcodeSessionView：native 读取", () => {
+  it("turns 派生：两轮闭合、text/thinking/toolCalls/usage 齐备（验收 4）", async () => {
+    const view = await readZcodeSessionView(dbPath, "sess_target");
+    expect(view.engineId).toBe("zcode");
+    expect(view.source).toBe("native");
+    expect(view.sessionId).toBe("sess_target");
+    expect(view.turns).toHaveLength(2);
+
+    const [t1, t2] = view.turns!;
+    expect(t1!.text).toBe("");
+    expect(t1!.thinking).toBe("thinking hard");
+    expect(t1!.toolCalls).toHaveLength(1);
+    expect(t1!.toolCalls[0]!.toolName).toBe("Bash");
+    expect(t1!.toolCalls[0]!.args).toEqual({ command: "ls" });
+    expect(t1!.toolCalls[0]!.result).toEqual({ content: ["file-a\nfile-b"] });
+    expect(t1!.toolCalls[0]!.isError).toBeUndefined(); // status completed
+    expect(t1!.closed).toBe(true);
+
+    expect(t2!.text).toBe("final answer");
+    expect(t2!.closed).toBe(true);
+
+    // usage 聚合 = 两轮 usageDelta 之和（cost 累计第二段的 0.5）
+    expect(view.usage).toEqual({ input: 150, output: 20, cacheRead: 5, cacheWrite: 0, cost: 0.5, total: 175 });
+  });
+
+  it("缺省 sessionId 取池内最新 session（time_created DESC）", async () => {
+    const view = await readZcodeSessionView(dbPath);
+    expect(view.sessionId).toBe("sess_target");
+  });
+
+  it("tool 状态非 completed 标 isError", async () => {
+    // 单独建一个带失败工具调用的 session，避免污染上面的聚合断言
+    const failDb = path.join(tmpDir, "fail.sqlite");
+    await createDb(failDb);
+    const { DatabaseSync } = (await import("node:sqlite")) as { DatabaseSync: new (p: string) => unknown };
+    type Db = { prepare: (s: string) => { run: (...a: unknown[]) => void }; close: () => void };
+    const db = new DatabaseSync(failDb) as unknown as Db;
+    db.prepare("INSERT INTO session (id, time_created) VALUES (?, ?)").run("sess_fail", 3000);
+    db
+      .prepare("INSERT INTO message (id, session_id, sequence, data) VALUES (?, ?, ?, ?)")
+      .run("msg_f", "sess_fail", 0, JSON.stringify({ role: "assistant" }));
+    db
+      .prepare("INSERT INTO part (id, message_id, session_id, sequence, data) VALUES (?, ?, ?, ?, ?)")
+      .run(
+        "pf",
+        "msg_f",
+        "sess_fail",
+        0,
+        JSON.stringify({
+          type: "tool",
+          tool: "Edit",
+          state: JSON.stringify({ status: "error", input: { file: "a" }, output: "conflict" }),
+        }),
+      );
+    db.close();
+    const view = await readZcodeSessionView(failDb, "sess_fail");
+    expect(view.turns[0]!.toolCalls[0]!.isError).toBe(true);
+  });
+});
+
+describe("readZcodeSessionView：结构化错误（供降级②③级，验收 4 负例）", () => {
+  beforeEach(() => {
+    // 无共享状态需重置；保留钩子位置说明负例组意图
+  });
+
+  it("db 文件缺失 → engine_session_read_failed（detail 含路径）", async () => {
+    const missing = path.join(tmpDir, "nope.sqlite");
+    try {
+      await readZcodeSessionView(missing, "sess_x");
+      expect.unreachable("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(ZcodeReaderError);
+      const e = err as ZcodeReaderError;
+      expect(e.code).toBe("engine_session_read_failed");
+      expect(e.detail).toContain(missing);
+      expect(e.message).toContain("降级");
+    }
+  });
+
+  it("表结构漂移（缺 part 表）→ 结构化错误含漂移提示", async () => {
+    const drifted = path.join(tmpDir, "drifted.sqlite");
+    const { DatabaseSync } = (await import("node:sqlite")) as { DatabaseSync: new (p: string) => unknown };
+    type Db = { exec: (s: string) => void; close: () => void };
+    const db = new DatabaseSync(drifted) as unknown as Db;
+    // 只建 session/message（zcode 升级把 part 改名的形态）；塞一行 session 让定位
+    // 通过、失败必然发生在 part 查询（表缺失）
+    db.exec(
+      "CREATE TABLE session (id TEXT PRIMARY KEY, time_created INTEGER);" +
+        "CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT, sequence INTEGER, data TEXT);" +
+        "INSERT INTO session (id, time_created) VALUES ('sess_d', 1);",
+    );
+    db.close();
+    try {
+      await readZcodeSessionView(drifted);
+      expect.unreachable("should throw");
+    } catch (err) {
+      const e = err as ZcodeReaderError;
+      expect(e.code).toBe("engine_session_read_failed");
+      expect(e.message).toContain("漂移");
+      expect(e.message).toContain("golden");
+    }
+  });
+
+  it("session 不存在 → 结构化错误（不静默空视图）", async () => {
+    try {
+      await readZcodeSessionView(dbPath, "sess_ghost");
+      expect.unreachable("should throw");
+    } catch (err) {
+      expect((err as ZcodeReaderError).detail).toContain("sess_ghost");
+    }
+  });
+});

package/src/execution/engine/engines/zcode/__tests__/registration.test.ts

@@ -0,0 +1,71 @@
+// registration.test.ts —— 注册表接线（验收 6）：'zcode' 可经 getEngine 获取、幂等
+// 覆盖、engineDataDir 默认走 common/data-dir SSOT。clearEngines 隔离全局注册表状态。
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// u0-data-discovery 注入化后 data-dir 回退值来自 HostServices.dataRoot() 端口——
+// 用例内 configureCore 假宿主控制端口态，afterEach reset 防跨用例泄漏
+import { configureCore, resetCoreForTests } from "../../../../../core/host-services.ts";
+
+import { clearEngines, getEngine, hasEngine, listEngines } from "../../../registry.ts";
+import { createZcodeEngine, registerZcodeEngine } from "../registration.ts";
+
+const FAKE_DATA_ROOT = "/fake-registration-data-root";
+
+afterEach(() => {
+  clearEngines();
+  resetCoreForTests();
+  vi.restoreAllMocks();
+});
+
+describe("registerZcodeEngine", () => {
+  it("登记后 getEngine('zcode') 可用，id/capabilities 正确", () => {
+    registerZcodeEngine(() => "/tmp/data");
+    expect(hasEngine("zcode")).toBe(true);
+    expect(listEngines()).toContain("zcode");
+    const engine = getEngine("zcode");
+    expect(engine.id).toBe("zcode");
+    expect(engine.capabilities().schemaEnforcement).toBe("emulated");
+  });
+
+  it("幂等：重复注册覆盖不堆积（listEngines 单条）", () => {
+    registerZcodeEngine(() => "/tmp/data");
+    registerZcodeEngine(() => "/tmp/data2");
+    expect(listEngines().filter((id) => id === "zcode")).toHaveLength(1);
+    // 覆盖后单例按新工厂重建（engineDataDir 已换）
+    expect(hasEngine("zcode")).toBe(true);
+  });
+
+  it("createZcodeEngine DI 工厂：deps 直达引擎", () => {
+    const engine = createZcodeEngine({ engineDataDir: () => "/tmp/x" });
+    expect(engine.id).toBe("zcode");
+  });
+});
+
+describe("engineDataDir 默认通道（common/data-dir SSOT）", () => {
+  it("缺省经 getEngineDataDir 解析：env 优先，缺失回落宿主数据根（warn 一次）", async () => {
+    // warn 断言走 getEngineDataDir 自带的 DI warn 参数——缺省 warn 通道是
+    // core logger facade（configureCore 后经 pi-host 桥接落文件，不经
+    // console.warn），spy console 永远收不到且会让 logger 落文件产生测试副作用。
+    const { getEngineDataDir, resetDataDirWarnForTests } = await import("../../../common/data-dir.ts");
+    const warns: string[] = [];
+    const prev = process.env["XYZ_AGENT_DATA_DIR"];
+    delete process.env["XYZ_AGENT_DATA_DIR"];
+    try {
+      resetCoreForTests();
+      configureCore({ dataRoot: () => FAKE_DATA_ROOT, log: () => {} });
+      resetDataDirWarnForTests();
+      // 回退分支：无 env → HostServices.dataRoot()（假宿主值）+ warn 一次
+      expect(getEngineDataDir(process.env, (m) => warns.push(m))).toBe(FAKE_DATA_ROOT);
+      expect(warns).toHaveLength(1);
+      expect(warns[0]).toContain("XYZ_AGENT_DATA_DIR");
+      // env 分支：显式注入即取 env 值（透传链证据见 common/data-dir.ts 文件头）
+      process.env["XYZ_AGENT_DATA_DIR"] = "/from-host";
+      expect(getEngineDataDir(process.env, (m) => warns.push(m))).toBe("/from-host");
+      expect(warns).toHaveLength(1);
+    } finally {
+      if (prev !== undefined) process.env["XYZ_AGENT_DATA_DIR"] = prev;
+      else delete process.env["XYZ_AGENT_DATA_DIR"];
+    }
+  });
+});

package/src/execution/engine/engines/zcode/__tests__/zcode-engine.live.test.ts

@@ -0,0 +1,127 @@
+// zcode-engine.live.test.ts —— 端到端真机门（验收 5）：真实 zcode CLI + 真实凭据 +
+// 真实 LLM 调用。手动门（设计 §3.3.8 conformance run 层同构）：默认 skip，跑法：
+//
+//   cd extensions/universal/subagent-workflow
+//   ENGINE_CONFORMANCE_LIVE=1 ZCODE_E2E_MODEL='<provider/model>' pnpm vitest run src/execution/engine/engines/zcode/__tests__/zcode-engine.live.test.ts
+//
+// ZCODE_E2E_MODEL 缺省值是采集 golden 样本的本机 provider（v2 config 实测带 apiKey、
+// 公网可达）；换机器跑时用 env 覆盖为本机可用模型。池数据落 /tmp（跑完由本文件
+// afterAll 清理），不污染真实 ~/.zcode。
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { resolvePoolDir } from "../../../paths.ts";
+import { ZcodeEngine } from "../zcode-engine.ts";
+
+const LIVE = process.env["ENGINE_CONFORMANCE_LIVE"] === "1";
+const E2E_MODEL = process.env["ZCODE_E2E_MODEL"] ?? "e512d53e-0bfc-4915-9081-860d4aa13cd0/mimo-v2.5-pro";
+const DATA_ROOT = path.join(fs.realpathSync(os.tmpdir()), "zcode-p3-e2e-data");
+const WORK_CWD = path.join(fs.realpathSync(os.tmpdir()), "zcode-p3-e2e-cwd");
+
+describe.skipIf(!LIVE)("ZcodeEngine 端到端真机（真实 LLM 调用）", () => {
+  let engine: ZcodeEngine;
+
+  beforeAll(() => {
+    fs.mkdirSync(WORK_CWD, { recursive: true });
+    engine = new ZcodeEngine({ engineDataDir: () => DATA_ROOT });
+  });
+
+  afterAll(() => {
+    // 用完清理：池数据 + 任务 cwd（保持 /tmp 干净，实录/验证不留残留）
+    for (const dir of [DATA_ROOT, WORK_CWD]) {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // 尽力清理
+      }
+    }
+  });
+
+  it("probe：二进制/版本/golden 三项全过", async () => {
+    const report = await engine.probe();
+    expect(report.ok).toBe(true);
+    expect(report.engineVersion).toMatch(/^0\.\d+\.\d+$/);
+  }, 60_000);
+
+  it("run：schema 任务全链成功（隔离 HOME 新 session + outcome + read①级）", async () => {
+    const { handle, outcome } = await engine.run(
+      {
+        task: 'Verify this arithmetic check: 2 + 2 = 4. If it is correct the verdict must be "ok", otherwise "bad".',
+        slug: "e2e-schema",
+        model: E2E_MODEL,
+        cwd: WORK_CWD,
+        schema: {
+          type: "object",
+          properties: { verdict: { type: "string", enum: ["ok", "bad"] } },
+          required: ["verdict"],
+          additionalProperties: false,
+        },
+      },
+      { taskId: "sa-live-schema", poolKey: "" },
+    );
+
+    // outcome 正确
+    expect(outcome.error).toBeUndefined();
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.content).toContain('"verdict"');
+    expect(outcome.usage).toBeDefined();
+    expect(outcome.usage!.input).toBeGreaterThan(0);
+    expect(outcome.sessionId).toMatch(/^sess_/);
+    // schema 仿真（D4 emulated 侧）：公共层三级容错提取 + ajv 校验产出 parsedOutput
+    expect(outcome.parsedOutput).toEqual({ verdict: "ok" });
+
+    // 隔离 HOME 有新 session（db.sqlite 落池内，非真实 ~/.zcode）——路径经 resolvePoolDir
+    // SSOT（poolKey 里的 '.' 会被 sanitizeSeg 编码为 '-'，手工 join 会拼错目录）
+    const dbPath = path.join(resolvePoolDir(DATA_ROOT, "zcode", handle.data.poolKey), ".zcode", "cli", "db", "db.sqlite");
+    expect(fs.existsSync(dbPath)).toBe(true);
+    expect(fs.statSync(dbPath).size).toBeGreaterThan(0);
+
+    // read(handle) 第①级可读：turns 非空（验收 5 的 read 断言）
+    const view = await engine.read(handle);
+    expect(view.source).toBe("native");
+    expect(view.sessionId).toBe(outcome.sessionId);
+    expect(view.turns.length).toBeGreaterThanOrEqual(1);
+    expect(view.turns[0]!.text).toContain("verdict");
+  }, 300_000);
+
+  it("abort：长任务中途取消 → 杀链合成终态、无僵尸进程", async () => {
+    const controller = new AbortController();
+    const runPromise = engine.run(
+      {
+        task:
+          "Write an extremely detailed 5000-word technical essay about distributed systems consistency models. Do not stop early.",
+        slug: "e2e-abort",
+        model: E2E_MODEL,
+        cwd: WORK_CWD,
+      },
+      { taskId: "sa-live-abort", poolKey: "", signal: controller.signal },
+    );
+    // 等 spawn 发生（prompt 已进 argv），再中途 abort
+    await new Promise((r) => setTimeout(r, 4_000));
+    controller.abort();
+    const { outcome } = await runPromise;
+
+    expect(outcome.exitCode).toBeNull();
+    expect(outcome.error).toContain("SIGTERM");
+    // 无僵尸进程：--cwd 指向本测试专用 tmp 目录的 zcode 进程应已消失
+    const leftovers = listZcodeProcessesForCwd(WORK_CWD);
+    expect(leftovers).toEqual([]);
+  }, 120_000);
+});
+
+/** 扫系统进程表：--cwd 锚定到指定目录的 zcode CLI 进程（僵尸检测）。 */
+function listZcodeProcessesForCwd(cwd: string): string[] {
+  try {
+    const out = execFileSync("ps", ["-eo", "command"], { encoding: "utf8" });
+    return out
+      .split("\n")
+      .filter((line) => line.includes("zcode.cjs") && line.includes(`--cwd ${cwd}`));
+  } catch {
+    return [];
+  }
+}