@zhushanwen/subagent-core 0.2.0

package/src/execution/engine/__tests__/conformance/contract.probe.test.ts

@@ -0,0 +1,77 @@
+// contract.probe.test.ts —— conformance C1（probe 形状）：ProbeReport 字段完整；
+// ok=false 时 error.recovery 非空（§3.3.5——恢复指引是错误闭环「错误→权威源→重试」
+// 的载体，空指引 = 拦截了但不知道怎么修）。pi/zcode 双引擎都过（任何 adapter 必过）。
+//
+// fake 注入（不依赖真机）：pi 用 probeVersion fake + 不可解析 invocation 场景；
+// zcode 用不存在的 cliPath 构造 binary check 失败。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { PiEngine } from "../../engines/pi/pi-engine.ts";
+import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
+import type { ProbeReport } from "../../types.ts";
+
+function assertProbeShape(report: ProbeReport): void {
+  expect(typeof report.ok).toBe("boolean");
+  expect(typeof report.engineVersion).toBe("string");
+  expect(Array.isArray(report.checks)).toBe(true);
+  expect(report.checks.length).toBeGreaterThan(0);
+  for (const c of report.checks) {
+    expect(typeof c.name).toBe("string");
+    expect(typeof c.ok).toBe("boolean");
+  }
+  if (!report.ok) {
+    expect(report.error).toBeDefined();
+    expect(report.error?.code).toBe("engine_probe_failed");
+    // 恢复指引非空且指向动作（C1 断言核心——空指引直接 fail）
+    expect(report.error?.recovery).toBeTruthy();
+    expect(report.error?.recovery.length).toBeGreaterThan(20);
+  }
+}
+
+describe("conformance C1：probe 形状（ProbeReport 字段完整 + 失败含恢复指引）", () => {
+  it("pi：成功路径形状（fake 版本探测，不 spawn 真进程）", async () => {
+    const engine = new PiEngine({ getService: () => null, probeVersion: async () => "0.84.1" });
+    const report = await engine.probe();
+    assertProbeShape(report);
+    expect(report.ok).toBe(true);
+    expect(report.engineVersion).toBe("0.84.1");
+  });
+
+  it("pi：失败路径（invocation 不可解析）——error.recovery 非空", async () => {
+    const engine = new PiEngine({
+      getService: () => null,
+      probeVersion: async () => undefined,
+    });
+    // PATH 无 pi 时 invocation check 失败；有 pi 时版本 fake 失败——两形态都走断言器
+    const report = await engine.probe({ force: true });
+    assertProbeShape(report);
+  });
+
+  it("zcode：成功路径形状（存在的 cliPath + fake 版本探测）", async () => {
+    const engine = new ZcodeEngine({
+      engineDataDir: () => fs.mkdtempSync(path.join(os.tmpdir(), "probe-zcode-")),
+      cliPath: fileURLToPath(import.meta.url),
+      probeVersion: async () => "0.16.5",
+    });
+    const report = await engine.probe();
+    assertProbeShape(report);
+    expect(report.ok).toBe(true);
+  });
+
+  it("zcode：失败路径（二进制不存在）——error.recovery 非空且含重探指引", async () => {
+    const engine = new ZcodeEngine({
+      engineDataDir: () => fs.mkdtempSync(path.join(os.tmpdir(), "probe-zcode-")),
+      cliPath: "/nonexistent/zcode.cjs",
+    });
+    const report = await engine.probe();
+    assertProbeShape(report);
+    expect(report.ok).toBe(false);
+    expect(report.error?.recovery).toContain("--version");
+  });
+});

package/src/execution/engine/__tests__/conformance/contract.read-degradation.test.ts

@@ -0,0 +1,104 @@
+// contract.read-degradation.test.ts —— conformance C5（read 降级链）：三级都不 throw、
+// 坏 handle → 结构化降级（outcome-only）非崩溃、②级 journal 重放与 live 一致
+// （重放等价性，§3.3.6——journal 重放与 live 通路共用同一 reducer 的断言面）。
+//
+// fake 注入：zcode 用坏 dbPath（①级失败）+ 临时 journal 文件（②级命中）；pi 用
+// 不存在的 sessionFile（①级失败）+ journal（②级）。
+
+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 { eventsToSessionView } from "../../common/journal-replay.ts";
+import { JournalWriter } from "../../common/event-journal.ts";
+import { PiEngine } from "../../engines/pi/pi-engine.ts";
+import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
+import type { AgentEvent, EngineHandle } from "../../types.ts";
+
+function makeHandle(engineId: string, sessionRef: Record<string, string>, journalPath?: string): EngineHandle {
+  return {
+    data: {
+      v: 1,
+      engineId,
+      sessionRef,
+      poolKey: "shared",
+      ...(journalPath !== undefined ? { journalPath } : {}),
+      adapterVersion: "1.0.0-test",
+    },
+  };
+}
+
+/** live 通路形态的事件序列（与 golden 回放同源——重放等价性的比对基准）。 */
+const liveEvents: AgentEvent[] = [
+  { type: "text_delta", delta: "part one. " },
+  { type: "text_delta", delta: "part two." },
+  { type: "message_end", usage: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0 } },
+  { type: "turn_end" },
+];
+
+describe("conformance C5：read 降级链（三级都不 throw）", () => {
+  let dataDir: string;
+  beforeEach(() => {
+    dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "c5-read-"));
+  });
+  afterEach(() => {
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it("重放等价性：journal 重放 turns 与 live 累积一致（共用 updateFromEvent reducer）", () => {
+    const live = eventsToSessionView(liveEvents, "pi", "sess-x");
+    expect(live.source).toBe("journal");
+    expect(live.turns).toHaveLength(1);
+    expect(live.turns[0]?.text).toBe("part one. part two.");
+    expect(live.usage?.total).toBe(15);
+  });
+
+  it("zcode：①级坏 handle（dbPath 指向不存在文件）→ ②级 journal 命中（source=journal）", async () => {
+    const journalPath = path.join(dataDir, "journal-sa-c5.jsonl");
+    const writer = new JournalWriter({ path: journalPath, taskId: "sa-c5", engineId: "zcode" });
+    for (const ev of liveEvents) writer.append(ev);
+    await writer.close();
+
+    const engine = new ZcodeEngine({ engineDataDir: () => dataDir });
+    const handle = makeHandle("zcode", { sessionId: "sess-c5", dbPath: ".zcode/cli/db/db.sqlite" }, journalPath);
+    const view = await engine.read(handle); // ①级 db 不存在 → catch → ②级重放
+    expect(view.source).toBe("journal");
+    expect(view.engineId).toBe("zcode");
+    expect(view.turns[0]?.text).toBe("part one. part two.");
+  });
+
+  it("zcode：②级也不可达（无 journalPath）→ ③级 outcome-only，不 throw", async () => {
+    const engine = new ZcodeEngine({ engineDataDir: () => dataDir });
+    const handle = makeHandle("zcode", { sessionId: "sess-c5", dbPath: ".zcode/cli/db/db.sqlite" });
+    const view = await engine.read(handle);
+    expect(view.source).toBe("outcome-only");
+    expect(view.turns).toEqual([]);
+  });
+
+  it("zcode：跨引擎 handle（engineId 不符）→ 结构化 outcome-only，不 throw", async () => {
+    const engine = new ZcodeEngine({ engineDataDir: () => dataDir });
+    const view = await engine.read(makeHandle("pi", {}));
+    expect(view.source).toBe("outcome-only");
+  });
+
+  it("pi：①级坏 handle（sessionFile 不存在）→ ②级 journal 命中；②级缺省 → ③级", async () => {
+    const engine = new PiEngine({ getService: () => null });
+
+    const journalPath = path.join(dataDir, "journal-sa-pi-c5.jsonl");
+    const writer = new JournalWriter({ path: journalPath, taskId: "sa-pi-c5", engineId: "pi" });
+    for (const ev of liveEvents) writer.append(ev);
+    await writer.close();
+
+    const viaJournal = await engine.read(
+      makeHandle("pi", { sessionFile: "/nonexistent/session.jsonl" }, journalPath),
+    );
+    expect(viaJournal.source).toBe("journal");
+    expect(viaJournal.turns[0]?.text).toBe("part one. part two.");
+
+    const outcomeOnly = await engine.read(makeHandle("pi", { sessionFile: "/nonexistent/session.jsonl" }));
+    expect(outcomeOnly.source).toBe("outcome-only");
+    expect(outcomeOnly.turns).toEqual([]);
+  });
+});

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

@@ -0,0 +1,201 @@
+// engine-conformance.live.test.ts —— conformance run 层（真实 spawn 简单任务，C2/C4
+// 真机面）。手动门（设计 §3.3.8：run 层需已装引擎 + 有效凭据，不进默认 CI）：
+//
+//   cd extensions/universal/subagent-workflow
+//   ENGINE_CONFORMANCE_LIVE=1 pnpm vitest run src/execution/engine/__tests__/conformance/engine-conformance.live.test.ts
+//
+// pi 部分复用 PiEngine 的服务面注入（真实 executeAndAwait 需要完整 SubagentService 装配，
+// live 场景从进程单例取——未初始化时该用例 skip 并说明）；zcode 部分与 P3 的
+// zcode-engine.live.test.ts 互补（后者已覆盖 schema 全链，此处只跑 conformance 最小面）。
+//
+// relay 变体（E 方案 §2.3）= 同一契约 × 不同 spawn 通道：测试内起伪 runtime（net server，
+// 按 E-2 协议收握手回 accept / down 帧转写真实 pi stdin / pi stdout 回发 up 帧 / exit 帧收尾），
+// 经 PiEngine 真实 run 全链断言 C2+C3。前置 = SubagentService 已装配（真实会话进程内），
+// 且需真实模型凭据（最小任务由 LLM 完成）——纯 CI/无凭据环境必然 skip，属预期。
+
+import { spawn as childSpawn, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+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 { RunContext } from "../../port.ts";
+import type { AgentEvent } from "../../../types.ts";
+import type { AgentTaskSpec } from "../../types.ts";
+import { getPiInvocation } from "../../../pi-invocation.ts";
+import {
+  RELAY_ENV_NODE,
+  RELAY_ENV_RECORD_ID,
+  RELAY_ENV_SCRIPT,
+  RELAY_ENV_SESSION_ID,
+  RELAY_ENV_SOCKET,
+  RELAY_PROTOCOL_VERSION,
+  isRelayActive,
+} from "../../../relay-env.ts";
+import { assertAgentEventInvariants } from "./agent-event-invariants.ts";
+
+const LIVE = process.env["ENGINE_CONFORMANCE_LIVE"] === "1";
+
+describe.skipIf(!LIVE)("conformance run 层（真实 spawn，手动门）", () => {
+  it("pi：简单任务全链（C2：outcome 无 error、content 非空、engineId=pi）", async (testCtx) => {
+    const service = getSubagentService();
+    if (service === null) {
+      // 服务装配是 pi live 的前置（完整 SubagentService + modelRegistry 注入）——
+      // live 门内说明跳过原因而非静默 pass（失败要出声）
+      testCtx.skip("SubagentService 未装配（需在真实会话进程内运行）");
+      return;
+    }
+    const engine = createPiEngine(() => service);
+    const task: AgentTaskSpec = { task: "Reply with the single word: ok", slug: "live-c2" };
+    const ctx: RunContext = { taskId: "sa-live-pi-c2", poolKey: "shared" };
+    const { outcome } = await engine.run(task, ctx);
+    expect(outcome.error).toBeUndefined();
+    expect(outcome.content.trim().length).toBeGreaterThan(0);
+    expect(outcome.engineId).toBe("pi");
+  }, 120_000);
+
+  it("zcode：probe 真机（C1 live 面：三项 check 全过）", async () => {
+    const engine = new ZcodeEngine({ engineDataDir: () => "/tmp/zcode-conformance-live" });
+    const report = await engine.probe();
+    expect(report.ok).toBe(true);
+    expect(report.engineVersion).toMatch(/^0\.\d+\.\d+$/);
+  }, 60_000);
+});
+
+// ── relay 变体（E 方案 §2.3：同一契约 × 不同 spawn 通道，手动门内的手动门）──
+//
+// 前置：①ENGINE_CONFORMANCE_LIVE=1（套件级门）；②SubagentService 已装配（真实会话
+// 进程内跑——vitest 裸进程恒 null → skip 说明，与上方 pi live 用例同形态）；③真实模型
+// 凭据（最小任务由 LLM 完成）。relay 三 env 由测试自构（socket 指向测试内伪 runtime，
+// 执行器 = 本进程 node，脚本 = 包根 relay/relay.mjs），不依赖外部注入。
+
+describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手动门）", () => {
+  /** 伪 runtime：按 E-2 协议扮演 runtime 侧——握手 accept + spawn 真实 pi + 双向转发 + exit 传播。 */
+  function startFakeRuntime(socketPath: string): Promise<net.Server> {
+    return new Promise((resolve, reject) => {
+      const server = net.createServer((conn) => {
+        let lineBuf = "";
+        let pi: ChildProcess | null = null;
+        const send = (frame: Record<string, unknown>): void => {
+          conn.write(`${JSON.stringify(frame)}\n`);
+        };
+        const handleLine = (line: string): void => {
+          let frame: Record<string, unknown>;
+          try {
+            const parsed: unknown = JSON.parse(line);
+            if (typeof parsed !== "object" || parsed === null) return;
+            frame = parsed as Record<string, unknown>;
+          } catch {
+            return;
+          }
+          if (frame.kind === "handshake" && pi === null) {
+            // 按 E-2 协议回 accept，随后按握手帧 spawn 真实 pi（直连——本进程 env 已带
+            // relay 三 env，必须 relay:false 防二次代理死循环）；env 剥离 relay 五键
+            //（对齐 E-2 registry 剥离逻辑，防孙进程嵌套 relay 时旧值误导）。
+            send({ v: RELAY_PROTOCOL_VERSION, kind: "accept" });
+            const argv = Array.isArray(frame.argv) ? (frame.argv as string[]) : [];
+            const invocation = getPiInvocation(argv, { relay: false });
+            const env: NodeJS.ProcessEnv = { ...(frame.env as NodeJS.ProcessEnv) };
+            for (const key of [RELAY_ENV_SOCKET, RELAY_ENV_NODE, RELAY_ENV_SCRIPT, RELAY_ENV_SESSION_ID, RELAY_ENV_RECORD_ID]) {
+              delete env[key];
+            }
+            pi = childSpawn(invocation.command, invocation.args, {
+              env,
+              cwd: typeof frame.cwd === "string" ? frame.cwd : undefined,
+              stdio: ["pipe", "pipe", "pipe"],
+            });
+            pi.stdout?.on("data", (c: Buffer) => {
+              send({ v: RELAY_PROTOCOL_VERSION, kind: "data", dir: "up", b64: c.toString("base64") });
+            });
+            pi.stderr?.on("data", (c: Buffer) => {
+              send({ v: RELAY_PROTOCOL_VERSION, kind: "data", dir: "up-stderr", b64: c.toString("base64") });
+            });
+            pi.on("close", (code, signal) => {
+              send(signal !== null ? { kind: "exit", signal } : { kind: "exit", code: code ?? 1 });
+            });
+            return;
+          }
+          if (frame.kind === "data" && frame.dir === "down" && typeof frame.b64 === "string") {
+            pi?.stdin?.write(Buffer.from(frame.b64, "base64"));
+          }
+        };
+        conn.setEncoding("utf8");
+        conn.on("data", (chunk: string) => {
+          lineBuf += chunk;
+          let nl: number;
+          while ((nl = lineBuf.indexOf("\n")) >= 0) {
+            const line = lineBuf.slice(0, nl);
+            lineBuf = lineBuf.slice(nl + 1);
+            if (line.trim()) handleLine(line);
+          }
+        });
+        // 断连即杀（对齐 E-2 registry 语义）——防代理死/测试收尾后真实 pi 变孤儿
+        conn.on("close", () => {
+          if (pi !== null && !pi.killed) pi.kill("SIGTERM");
+        });
+      });
+      server.once("error", reject);
+      server.listen(socketPath, () => resolve(server));
+    });
+  }
+
+  it("pi × relay：伪 runtime 环回全链（C2 outcome 无 error + C3 事件不变量经代理转发全等）", { timeout: 180_000 }, async (testCtx) => {
+    const service = getSubagentService();
+    if (service === null) {
+      testCtx.skip(
+        "SubagentService 未装配（需在真实会话进程内运行，如 pi --extension 挂载本包后触发）" +
+          "——relay 变体与直连 live 用例共享该前置；纯 vitest 进程恒 skip，全链真机另由 " +
+          "packages/runtime relay-integration.test.ts（已存在）+ §9 人工验收承载",
+      );
+      return;
+    }
+
+    // 测试自构 relay env：socket 指向伪 runtime，执行器 = 本进程 node，脚本 = 包根 relay.mjs
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "relay-conformance-live-"));
+    const socketPath = path.join(tmpDir, "relay.sock");
+    const server = await startFakeRuntime(socketPath);
+    const savedEnv: Record<string, string | undefined> = {};
+    const restoreKeys = [RELAY_ENV_SOCKET, RELAY_ENV_NODE, RELAY_ENV_SCRIPT];
+    for (const key of restoreKeys) savedEnv[key] = process.env[key];
+    process.env[RELAY_ENV_SOCKET] = socketPath;
+    process.env[RELAY_ENV_NODE] = process.execPath;
+    process.env[RELAY_ENV_SCRIPT] = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "../../../../../relay/relay.mjs",
+    );
+    if (!isRelayActive(process.env)) {
+      throw new Error("relay env 自构后仍不激活——前置断言失败");
+    }
+
+    try {
+      const engine = createPiEngine(() => service);
+      const events: AgentEvent[] = [];
+      const task: AgentTaskSpec = { task: "Reply with the single word: ok", slug: "live-relay-c2" };
+      const ctx: RunContext = {
+        taskId: "sa-live-pi-relay",
+        poolKey: "shared",
+        onEvent: (event) => events.push(event),
+      };
+      const { outcome } = await engine.run(task, ctx);
+      // C2：outcome 无 error + engineId 仍为 pi（relay 是 spawn 通道不是引擎身份）
+      expect(outcome.error).toBeUndefined();
+      expect(outcome.content.trim().length).toBeGreaterThan(0);
+      expect(outcome.engineId).toBe("pi");
+      // C3：事件不变量五条对「经代理转发的子进程 stdout」逐一成立（同一 parser 消费同一字节流）
+      assertAgentEventInvariants(events, { granularity: "stream", content: outcome.content });
+    } finally {
+      for (const key of restoreKeys) {
+        if (savedEnv[key] === undefined) delete process.env[key];
+        else process.env[key] = savedEnv[key];
+      }
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -0,0 +1,76 @@
+// golden-replay.pi.test.ts —— pi 引擎 golden 回放层（conformance 免 LLM 默认 CI 层，
+// 设计 §3.3.8 两层结构的第一层）。锚定物 = 统一 AgentEvent 序列（onEvent 出口 / journal
+// 落盘形态）——pi 的完整翻译链（parseSpawnLine → handleSdkEvent）闭包在 session-runner
+// 的 spawn 状态里，conformance 以「翻译产物」为契约锚点（journal/record 消费的正是它）。
+//
+// 覆盖：C3 不变量（流式口径）+ journal 往返保真（replayJournal === golden 序列）+
+// parseSpawnLine 对实录行形态的回归（pi parser 的纯函数面）。
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+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 { assertAgentEventInvariants } from "./agent-event-invariants.ts";
+
+interface PiGoldenFile {
+  events: AgentEvent[];
+  content: string;
+}
+
+const fixturePath = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__", "pi-golden-events.json");
+const golden = JSON.parse(readFileSync(fixturePath, "utf8")) as PiGoldenFile;
+
+describe("pi golden 回放（conformance C3/C5-journal，免 LLM）", () => {
+  it("golden 事件序列满足全部产出不变量（流式口径：text_delta 拼接 === content）", () => {
+    assertAgentEventInvariants(golden.events, { granularity: "stream", content: golden.content });
+  });
+
+  it("journal 往返保真：golden 序列经 JournalWriter 落盘后 replayJournal 逐事件相等", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-golden-journal-"));
+    const writer = new JournalWriter({
+      path: join(dir, "journal-sa-pi-golden.jsonl"),
+      taskId: "sa-pi-golden",
+      engineId: "pi",
+    });
+    try {
+      for (const ev of golden.events) writer.append(ev);
+      await writer.close();
+      const replayed = replayJournal(writer.path);
+      // 深比较（含 undefined 键缺省语义——JSON 序列化后 undefined 字段自然消失，两侧同构）
+      expect(replayed).toEqual(golden.events);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("parseSpawnLine 回归：实录行形态（header/事件行）识别不漂移", () => {
+    const header = parseSpawnLine(
+      JSON.stringify({ type: "session", id: "sess-pi-golden", timestamp: "2026-08-25T01:00:00.000Z", cwd: "/tmp" }),
+    );
+    expect(header?.kind).toBe("header");
+
+    const toolLine = parseSpawnLine(
+      JSON.stringify({ type: "tool_execution_start", toolName: "bash", toolCallId: "c1", args: { command: "ls" } }),
+    );
+    expect(toolLine?.kind).toBe("event");
+    if (toolLine?.kind === "event") expect(toolLine.event.type).toBe("tool_execution_start");
+
+    const msgEnd = parseSpawnLine(
+      JSON.stringify({
+        type: "message_end",
+        message: { role: "assistant", usage: { input: 100, output: 50, cacheRead: 0, cacheWrite: 0 } },
+      }),
+    );
+    expect(msgEnd?.kind).toBe("event");
+    if (msgEnd?.kind === "event") expect(msgEnd.event.type).toBe("message_end");
+
+    const turnEnd = parseSpawnLine(JSON.stringify({ type: "turn_end" }));
+    expect(turnEnd?.kind).toBe("event");
+  });
+});

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

@@ -0,0 +1,79 @@
+// 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 内嵌副本一致，防漂移：
+// 更新样本必须同步两处，探针的干跑校验消费内嵌副本，两处不一致 = 探针在测旧契约）。
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { 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";
+
+// conformance 目录（engine/__tests__/conformance）→ engine 根的相对定位
+const fixturePath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..", "..", // conformance → __tests__ → engine
+  "engines", "zcode", "__tests__", "__fixtures__", "zcode-golden-spawn.json",
+);
+
+interface ZcodeGoldenFile {
+  _meta: { engineVersion: string; exitCode: number };
+  stdoutRaw: string;
+}
+
+const fixture = JSON.parse(readFileSync(fixturePath, "utf8")) as ZcodeGoldenFile;
+
+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,
+    });
+  });
+});

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

@@ -0,0 +1,87 @@
+// engine-discovery.test.ts —— [U7] registry → engines.json 同步（幂等/原子/兜底）。
+
+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 { SubagentEnginesFile } from "@xyz-agent/extension-protocol";
+
+import { getEnginesFilePath, syncEnginesFile } from "../engine-discovery.ts";
+import type { EnginePort } from "../port.ts";
+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" }),
+    run: async () => {
+      throw new Error("unused");
+    },
+    interact: async () => {
+      throw new Error("unused");
+    },
+    read: async () => ({ engineId: id, turns: [], source: "outcome-only" }),
+  };
+}
+
+let tmpRoot: string;
+let agentDir: string;
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "engine-discovery-"));
+  agentDir = path.join(tmpRoot, "agent");
+  clearEngines();
+});
+
+afterEach(() => {
+  clearEngines();
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("syncEnginesFile", () => {
+  it("注册表引擎列表落盘（v=1 + 注册序）", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    registerEngine("zcode", () => stubEngine("zcode"));
+    syncEnginesFile(agentDir);
+    const file = JSON.parse(fs.readFileSync(getEnginesFilePath(agentDir), "utf8")) as SubagentEnginesFile;
+    expect(file.v).toBe(1);
+    expect(file.engines).toEqual(["pi", "zcode"]);
+    expect(typeof file.updatedAt).toBe("number");
+  });
+
+  it("幂等：引擎清单未变时第二次零写（mtime 不动）", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    syncEnginesFile(agentDir);
+    const p = getEnginesFilePath(agentDir);
+    const statAfterFirst = fs.statSync(p);
+    syncEnginesFile(agentDir);
+    expect(fs.statSync(p).mtimeMs).toBe(statAfterFirst.mtimeMs);
+  });
+
+  it("新增引擎注册后内容变化触发重写", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    syncEnginesFile(agentDir);
+    registerEngine("acp", () => stubEngine("acp"));
+    syncEnginesFile(agentDir);
+    const file = JSON.parse(fs.readFileSync(getEnginesFilePath(agentDir), "utf8")) as SubagentEnginesFile;
+    expect(file.engines).toEqual(["pi", "acp"]);
+  });
+
+  it("现文件损坏（torn write 形态）时重建", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    const p = getEnginesFilePath(agentDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, "{ torn", "utf8");
+    syncEnginesFile(agentDir);
+    expect(() => JSON.parse(fs.readFileSync(p, "utf8"))).not.toThrow();
+  });
+
+  it("agentDir 不存在时建目录写入；IO 异常吞掉不抛（fail-safe）", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    expect(() => syncEnginesFile(agentDir)).not.toThrow();
+    expect(fs.existsSync(getEnginesFilePath(agentDir))).toBe(true);
+  });
+});