@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/src/execution/engine/__tests__/conformance/__fixtures__/pi-golden-events.json

@@ -0,0 +1,28 @@
+{
+  "_meta": {
+    "engineId": "pi",
+    "description": "pi 引擎 golden 事件序列（统一 AgentEvent 形态——spawn-event-adapter/session-runner 翻译后的 onEvent 出口序列，即 journal 落盘形态）",
+    "source": "从 spawn-event-adapter.test.ts / session-runner 事件形状构造的典型流式序列：bash 工具调用（含 pendingTools 配对）→ 双段 text_delta → message_end（完整 usage）→ turn_end。字段形状与 handleSdkEvent 翻译产物逐一锚定（tool_start.toolName/args、tool_end.result/isError、text_delta.delta、message_end.usage 四项 token、turn_end）",
+    "recordedAt": "2026-08-25",
+    "usageMapping": "message_end.usage = pi SDK message.usage（input/output/cacheRead/cacheWrite 四项 + cost.total 投影为 cost）"
+  },
+  "events": [
+    { "type": "tool_start", "toolName": "bash", "args": { "command": "ls -la /tmp/probe" } },
+    {
+      "type": "tool_end",
+      "toolName": "bash",
+      "args": { "command": "ls -la /tmp/probe" },
+      "result": { "output": "total 0\ndrwxr-xr-x  2 user  staff  64 Aug 25 10:00:00 ." },
+      "isError": false
+    },
+    { "type": "thinking_delta", "delta": "目录为空，无需进一步检查。" },
+    { "type": "text_delta", "delta": "Probe directory is empty. " },
+    { "type": "text_delta", "delta": "Nothing to clean up." },
+    {
+      "type": "message_end",
+      "usage": { "input": 12599, "output": 17, "cacheRead": 512, "cacheWrite": 0, "cost": 0.0001 }
+    },
+    { "type": "turn_end" }
+  ],
+  "content": "Probe directory is empty. Nothing to clean up."
+}

package/src/execution/engine/__tests__/conformance/agent-event-invariants.ts

@@ -0,0 +1,141 @@
+// agent-event-invariants.ts —— AgentEvent 产出不变量断言器（conformance C3 的实现体）。
+//
+// 设计权威源：docs/architecture/subagent-engine-abstraction.md §3.3.7「AgentEvent 产出
+// 不变量」五条（全部引擎必须满足）。任何 adapter 的 conformance 套件（golden 回放层 /
+// 合成样本）都经本断言器校验——负例守护（A12「套件有牙」）靠注入坏序列证明它转红。
+//
+// 为什么独立成模块（非内联在测试文件）：pi/zcode 两套 golden 回放 + 负例元测试共用
+// 同一断言逻辑；断言规则漂移会同步影响所有引擎的 conformance，单点维护。
+
+import type { AgentEvent, AgentUsage } from "../../../types.ts";
+
+/** 单条不变量违例。invariant 是规则编号（"1"/"2a"...），detail 是定位信息。 */
+export interface InvariantFinding {
+  invariant: string;
+  detail: string;
+}
+
+/** 断言选项。granularity 决定不变量 3 走流式（byte 级拼接）还是 coarse 口径。 */
+export interface InvariantOptions {
+  granularity: "stream" | "coarse";
+  /** 流式引擎的终态 content（不变量 3a：text_delta 拼接 === content，byte 级）。 */
+  content?: string;
+}
+
+/** 五条不变量的纯校验（不 throw，返回违例清单——元测试要拿清单做反证）。 */
+export function checkAgentEventInvariants(
+  events: readonly AgentEvent[],
+  opts: InvariantOptions,
+): InvariantFinding[] {
+  const findings: InvariantFinding[] = [];
+  if (events.length === 0) {
+    return [{ invariant: "0", detail: "事件序列为空——至少需要 turn_end 终态" }];
+  }
+
+  // 不变量 1：终态序唯一——最后一个非 error 事件必是 turn_end；message_end（若出现）
+  // 必在其前（turn_end 之后不允许任何非 error 事件）
+  const nonError = events.filter((e) => e.type !== "error");
+  const last = nonError[nonError.length - 1];
+  if (last === undefined || last.type !== "turn_end") {
+    findings.push({
+      invariant: "1",
+      detail: `最后一个非 error 事件是 ${String(last?.type ?? "(none)")}，必须唯一且为 turn_end`,
+    });
+  }
+  const lastTurnEndIdx = findLastIndex(events, (e) => e.type === "turn_end");
+  if (lastTurnEndIdx >= 0) {
+    for (let i = lastTurnEndIdx + 1; i < events.length; i++) {
+      const ev = events[i];
+      if (ev !== undefined && ev.type !== "error") {
+        findings.push({ invariant: "1", detail: `turn_end 之后出现非 error 事件 ${ev.type}（idx ${i}）` });
+      }
+    }
+  }
+  const lastMessageEndIdx = findLastIndex(events, (e) => e.type === "message_end");
+  if (lastMessageEndIdx >= 0 && lastTurnEndIdx >= 0 && lastMessageEndIdx > lastTurnEndIdx) {
+    findings.push({ invariant: "1", detail: "message_end 出现在 turn_end 之后（必须在其前）" });
+  }
+
+  // 不变量 2：message_end.usage 出现时为完整 AgentUsage 形状——给不出完整 usage 时
+  // 显式缺省整个字段，不给残缺对象（NaN/缺键 = 残缺）
+  events.forEach((ev, idx) => {
+    if (ev.type !== "message_end") return;
+    if (ev.usage === undefined) return; // 显式缺省 = 合法
+    if (!isCompleteUsage(ev.usage)) {
+      findings.push({ invariant: "2", detail: `message_end(idx ${idx}).usage 残缺（四项 token 必须全为有限数）` });
+    }
+  });
+
+  // 不变量 3a（流式）：全部 text_delta 拼接 === content（byte 级）
+  if (opts.granularity === "stream") {
+    if (opts.content === undefined) {
+      findings.push({ invariant: "3a", detail: "流式口径必须提供 content 供拼接比对" });
+    } else {
+      const joined = events.filter((e) => e.type === "text_delta").map((e) => (e as { delta: string }).delta).join("");
+      if (Buffer.from(joined, "utf8").toString("hex") !== Buffer.from(opts.content, "utf8").toString("hex")) {
+        findings.push({ invariant: "3a", detail: "text_delta 拼接与 content 不一致（byte 级比对失败）" });
+      }
+    }
+  } else {
+    // 不变量 3b（coarse）：turn_end 前至少一个 message_end
+    if (lastTurnEndIdx < 0 || !events.slice(0, lastTurnEndIdx).some((e) => e.type === "message_end")) {
+      findings.push({ invariant: "3b", detail: "coarse 引擎 turn_end 前必须至少一个 message_end" });
+    }
+  }
+
+  // 不变量 4：tool_start/tool_end 按名配对——终态前未配对的 tool_start 必须有配对
+  // tool_end（isError 可）或后续 error 事件兜底
+  const openTools: Array<{ toolName: string; idx: number }> = [];
+  let errorSeen = false;
+  events.forEach((ev, idx) => {
+    if (ev.type === "error") {
+      errorSeen = true;
+      return;
+    }
+    if (ev.type === "tool_start") {
+      openTools.push({ toolName: ev.toolName, idx });
+      return;
+    }
+    if (ev.type === "tool_end") {
+      const at = openTools.findIndex((t) => t.toolName === ev.toolName);
+      if (at >= 0) openTools.splice(at, 1);
+      return;
+    }
+  });
+  for (const t of openTools) {
+    if (!errorSeen) {
+      findings.push({
+        invariant: "4",
+        detail: `tool_start(${t.toolName}, idx ${t.idx}) 终态前未配对（无 tool_end 也无 error 兜底）`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/** 断言形态（conformance 用例直接消费——违例 throw，测试转红）。 */
+export function assertAgentEventInvariants(events: readonly AgentEvent[], opts: InvariantOptions): void {
+  const findings = checkAgentEventInvariants(events, opts);
+  if (findings.length > 0) {
+    const lines = findings.map((f) => `  [不变量 ${f.invariant}] ${f.detail}`).join("\n");
+    throw new Error(`AgentEvent 不变量违例（§3.3.7 五条）：\n${lines}`);
+  }
+}
+
+/** AgentUsage 完整形状判定（四项 token 有限数；cost 可选）。 */
+function isCompleteUsage(u: AgentUsage): boolean {
+  return (
+    Number.isFinite(u.input) && Number.isFinite(u.output) &&
+    Number.isFinite(u.cacheRead) && Number.isFinite(u.cacheWrite)
+  );
+}
+
+/** Array.prototype.findLastIndex 的 ES2022 前兼容（node 18+ 有原生，防御口径手写）。 */
+function findLastIndex<T>(arr: readonly T[], pred: (v: T) => boolean): number {
+  for (let i = arr.length - 1; i >= 0; i--) {
+    const v = arr[i];
+    if (v !== undefined && pred(v)) return i;
+  }
+  return -1;
+}

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

@@ -0,0 +1,109 @@
+// contract.abort.test.ts —— conformance C4（abort 行为）：运行中 cancel → 宿主合成
+// 终态（exitCode=null）、无悬挂 promise（run 正常 resolve、exited 收口）、错误事件
+// 先于终态 emit（不变量 5 的事件面）。fake launcher 注入（不依赖真机）。
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { RunContext } from "../../port.ts";
+import type { AgentEvent, AgentTaskSpec } from "../../types.ts";
+import { ZcodeEngine, type ZcodeEngineDeps } from "../../engines/zcode/zcode-engine.ts";
+import type { ZcodeLaunchedProcess } from "../../engines/zcode/launcher.ts";
+
+const PROVIDER = "provider-x";
+
+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));
+}
+
+/** 长驻 fake 进程：stdout 永不结束（模拟运行中），abort 由测试主动触发。 */
+function makeHangingLaunch(): {
+  launch: ZcodeEngineDeps["launch"];
+  proc: () => ZcodeLaunchedProcess | undefined;
+  triggerAbort: () => void;
+} {
+  let launched: ZcodeLaunchedProcess | undefined;
+  const stdout = new PassThrough();
+  const stderr = new PassThrough();
+  let killTriggered = false;
+  let resolveExited: (v: { code: number | null; signal: string | undefined }) => void = () => {};
+  const exited = new Promise<{ code: number | null; signal: string | undefined }>((resolve) => {
+    resolveExited = resolve;
+  });
+  const launch = (): ZcodeLaunchedProcess => {
+    launched = {
+      // D10 记账形态：child = 立即退出的真实 node 短进程（本用例不消费记账面）
+      child: spawn(process.execPath, ["-e", ""]),
+      pid: 4242,
+      stdout,
+      stderr,
+      abort: async () => {
+        killTriggered = true;
+        // 杀链语义：进程被信号杀死（code=null）——微任务后 settle 模拟 kill 时序
+        setTimeout(() => resolveExited({ code: null, signal: "SIGTERM" }), 5);
+      },
+      exited,
+      killedByUs: () => killTriggered,
+    };
+    return launched;
+  };
+  return { launch, proc: () => launched, triggerAbort: () => resolveExited({ code: null, signal: "SIGTERM" }) };
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "c4-abort-"));
+  dataDir = path.join(tmpRoot, "data");
+  v2Path = path.join(tmpRoot, "v2.json");
+  writeJson(v2Path, {
+    provider: { [PROVIDER]: { options: { apiKey: "k" }, models: { m1: {} } } },
+  });
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("conformance C4：abort 行为（运行中 cancel → 合成终态、无悬挂）", () => {
+  it("abort → run 正常 resolve（不悬挂）：exitCode=null + error 事件合成 + killedByUs", async () => {
+    const fake = makeHangingLaunch();
+    const engine = new ZcodeEngine({
+      engineDataDir: () => dataDir,
+      sources: { v2ConfigPath: v2Path },
+      processEnv: { PATH: "/usr/bin" },
+      launch: fake.launch,
+    });
+
+    const controller = new AbortController();
+    const events: AgentEvent[] = [];
+    const ctx: RunContext = {
+      taskId: "sa-c4",
+      poolKey: "",
+      signal: controller.signal,
+      onEvent: (ev) => events.push(ev),
+    };
+    const task: AgentTaskSpec = { task: "hang", slug: "abort", model: `${PROVIDER}/m1` };
+
+    const runP = engine.run(task, ctx);
+    // run 进行中触发 abort（等待 spawn 完成——微任务两拍让 launch 已执行）
+    await new Promise((r) => setTimeout(r, 20));
+    controller.abort();
+    const { handle, outcome } = await runP; // 必须正常 resolve（杀链合成终态，不悬挂）
+
+    expect(outcome.exitCode).toBeNull();
+    expect(outcome.error).toContain("中止");
+    // 终态前 error 事件已 emit（不变量 5 的事件面——journal 可重放出失败事实）
+    expect(events.some((e) => e.type === "error")).toBe(true);
+    expect(fake.proc()?.killedByUs()).toBe(true);
+    expect(handle.data.engineId).toBe("zcode");
+  }, 15_000);
+});

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

@@ -0,0 +1,101 @@
+// contract.agent-events.test.ts —— conformance C3（AgentEvent 不变量）+ 负例自证
+// （A12「套件有牙」：故意破坏一个不变量的样本必须被断言器检出——用「注入坏
+// parser」的形态：wrap 真实 synthesizeCoarseEvents 抽掉 message_end，断言套件转红；
+// 若断言器检不出破坏则本元测试失败）。
+
+import { describe, expect, it } from "vitest";
+
+import type { AgentEvent } from "../../../types.ts";
+import { ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
+import { parseZcodeTerminal, synthesizeCoarseEvents } from "../../engines/zcode/parser.ts";
+import {
+  assertAgentEventInvariants,
+  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" });
+  });
+
+  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" });
+    expect(findings.some((f) => f.invariant === "1")).toBe(true);
+  });
+
+  it("不变量 2：message_end.usage 残缺对象（NaN token）被判违例", () => {
+    const events: AgentEvent[] = [
+      { type: "message_end", usage: { input: Number.NaN, output: 1, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "2")).toBe(true);
+  });
+
+  it("不变量 2 正例：usage 显式缺省整个字段 = 合法（不给残缺）", () => {
+    const events: AgentEvent[] = [{ type: "message_end" }, { type: "turn_end" }];
+    expect(checkAgentEventInvariants(events, { granularity: "coarse" })).toEqual([]);
+  });
+
+  it("不变量 3a：流式 text_delta 拼接 ≠ content 判违例（byte 级）", () => {
+    const events: AgentEvent[] = [
+      { type: "text_delta", delta: "abc" },
+      { type: "message_end", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(events, { granularity: "stream", content: "abd" });
+    expect(findings.some((f) => f.invariant === "3a")).toBe(true);
+  });
+
+  it("不变量 3b：coarse 序列缺 message_end（turn_end 裸终态）判违例", () => {
+    const events: AgentEvent[] = [{ type: "turn_end" }];
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "3b")).toBe(true);
+  });
+
+  it("不变量 4：未配对 tool_start 且无 error 兜底判违例；error 兜底合法", () => {
+    const unpaired: AgentEvent[] = [
+      { type: "tool_start", toolName: "bash" },
+      { type: "turn_end" },
+    ];
+    expect(checkAgentEventInvariants(unpaired, { granularity: "coarse" }).some((f) => f.invariant === "4")).toBe(true);
+
+    const withError: AgentEvent[] = [
+      { type: "tool_start", toolName: "bash" },
+      { type: "error", message: "boom" },
+      { type: "turn_end" },
+    ];
+    expect(checkAgentEventInvariants(withError, { granularity: "coarse" }).some((f) => f.invariant === "4")).toBe(false);
+  });
+});
+
+describe("conformance 负例自证（A12：套件有牙）", () => {
+  it("注入坏 parser（抽掉 message_end 的合成器）：断言器必须检出（不变量 3b 转红）", () => {
+    // 坏 parser 形态：zcode 新版本漂移后合成器丢 message_end——不变量 3b 应抓到
+    const badParser = (): AgentEvent[] => [{ type: "turn_end" }];
+    const events = badParser();
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings.some((f) => f.invariant === "3b")).toBe(true);
+    // 断言形态同步转红（conformance 用例消费的入口）
+    expect(() => assertAgentEventInvariants(events, { granularity: "coarse" })).toThrowError(/不变量/);
+  });
+
+  it("注入坏 parser（usage 半映射）：断言器必须检出（不变量 2 转红）", () => {
+    // 坏 parser 形态：新版本 usage 字段改名，数值映射 Number(undefined) → NaN 渗入
+    const badParser = (): AgentEvent[] => [
+      { type: "message_end", usage: { input: Number.NaN, output: 2, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(badParser(), { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "2")).toBe(true);
+  });
+});

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([]);
+  });
+});