@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

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

@@ -0,0 +1,342 @@
+// contract.relay.test.ts —— conformance relay 变体（E 方案 §2.3，默认 CI 层，免 LLM）。
+//
+// 断言口径：同一契约，spawn 通道不同——relay 是 pi 引擎的进程拓扑变体，不是引擎身份：
+//   1. 协议常量镜像一致性：relay.mjs（零依赖脚本不能 import workspace 包，只能内嵌
+//      镜像）与 relay-env.ts SSOT 逐字对齐——改名/改值双侧不同步即此处转红（§10-5）。
+//   2. pi-invocation 通道契约：三 env 齐备 → 代理形态；任一缺失 → 直连（全有或全无，
+//      E-TUI 零回归）；relay:false 强制直连（probe 语义）。
+//   3. buildChildEnv 归属契约：激活时写入 tee 帧路由键（SESSION_ID/RECORD_ID），未激活
+//      不写（继承值保持，无 relay 环境不携带误导性 env）。
+//
+// 真机全链（经代理 spawn 真实 pi）是 live 手动门：engine-conformance.live.test.ts 的
+// relay describe（ENGINE_CONFORMANCE_LIVE=1 + relay env 齐备），不在本文件。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── runSpawn 集成段 mock（与 session-runner-schema-env.test.ts 同模式）──
+
+vi.mock("node:child_process", async () => {
+  const { EventEmitter } = await import("node:events");
+  const { PassThrough } = await import("node:stream");
+
+  class FakeChild extends EventEmitter {
+    pid = 12345;
+    stdout = new PassThrough();
+    stdin = new PassThrough();
+    stderr = new PassThrough();
+    killed = false;
+    killSignal: string | undefined;
+    kill(sig?: string): boolean {
+      this.killed = true;
+      this.killSignal = sig;
+      return true;
+    }
+  }
+
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: readonly string[],
+        _opts: unknown,
+        cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+      ) => cb(new Error("execFile not configured in this test")),
+    ),
+  };
+});
+
+vi.mock("node:fs", async () => {
+  const actual = await import("node:fs");
+  return {
+    default: {
+      ...actual,
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      appendFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+    },
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    // 镜像段（C-镜像 describe）读 relay.mjs 源文本走真实实现——session-runner 只消费
+    // 上面被替换的几个方法，透传 readFileSync 不影响 runSpawn 集成段的 mock 语义。
+    readFileSync: actual.readFileSync,
+    promises: actual.promises,
+  };
+});
+
+vi.mock("../../../alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+}));
+
+vi.mock("../../../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string) => {
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { spawn } from "node:child_process";
+
+import {
+  RELAY_ENV_NODE,
+  RELAY_ENV_RECORD_ID,
+  RELAY_ENV_SCRIPT,
+  RELAY_ENV_SESSION_ID,
+  RELAY_ENV_SOCKET,
+  RELAY_EXIT_CODES,
+  RELAY_PROTOCOL_VERSION,
+  isRelayActive,
+} from "../../../relay-env.ts";
+import { getPiInvocation } from "../../../pi-invocation.ts";
+import { runSpawn, type RunOptions, type SessionRunnerContext } from "../../../session-runner.ts";
+import { createRecord } from "../../../execution-record.ts";
+import { waitForSpawn } from "../../../__tests__/helpers/spawn-mock.ts";
+
+const mockSpawn = vi.mocked(spawn);
+
+/** 被锁定的代理脚本：包根 relay/relay.mjs（与 src/ 平行的零依赖脚本）。 */
+const RELAY_SCRIPT_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../../../../relay/relay.mjs",
+);
+
+/** relay 激活三 env 齐备的基准值。 */
+const RELAY_FULL: Record<string, string> = {
+  [RELAY_ENV_SOCKET]: "/tmp/contract-relay.sock",
+  [RELAY_ENV_NODE]: "/usr/bin/contract-relay-node",
+  [RELAY_ENV_SCRIPT]: "/opt/contract-relay/relay.mjs",
+};
+
+const RELAY_ENV_KEYS = [RELAY_ENV_SOCKET, RELAY_ENV_NODE, RELAY_ENV_SCRIPT] as const;
+
+function setRelayEnv(env: Record<string, string> | undefined): void {
+  for (const key of [...RELAY_ENV_KEYS, RELAY_ENV_SESSION_ID, RELAY_ENV_RECORD_ID]) {
+    delete process.env[key];
+  }
+  if (env !== undefined) Object.assign(process.env, env);
+}
+
+// ── 1. 协议常量镜像一致性（relay-env.ts SSOT ↔ relay.mjs 内嵌镜像）──
+
+describe("relay 变体 C-镜像：relay.mjs 内嵌常量与 relay-env.ts SSOT 一致", () => {
+  const source = fs.readFileSync(RELAY_SCRIPT_PATH, "utf8");
+
+  /** 字符串常量：`const NAME = "value"` 形式逐字对齐（值来自 SSOT 导出，漂移即红）。 */
+  const stringVars: Array<[string, string]> = [
+    ["RELAY_ENV_SOCKET", RELAY_ENV_SOCKET],
+    ["RELAY_ENV_SESSION_ID", RELAY_ENV_SESSION_ID],
+    ["RELAY_ENV_RECORD_ID", RELAY_ENV_RECORD_ID],
+  ];
+
+  it.each(stringVars)("镜像字符串常量 %s 与 SSOT 逐字一致", (name, value) => {
+    expect(source).toMatch(new RegExp(`${name}\\s*=\\s*["']${value}["']`));
+  });
+
+  it("镜像协议版本 RELAY_PROTOCOL_VERSION 与 SSOT 一致", () => {
+    expect(source).toMatch(new RegExp(`RELAY_PROTOCOL_VERSION\\s*=\\s*${RELAY_PROTOCOL_VERSION}\\b`));
+  });
+
+  it("镜像退出码 RELAY_EXIT_CODES 四值与 SSOT 一致", () => {
+    const pairs: Array<[keyof typeof RELAY_EXIT_CODES, number]> = [
+      ["VERSION_MISMATCH", RELAY_EXIT_CODES.VERSION_MISMATCH],
+      ["SOCKET_UNREACHABLE", RELAY_EXIT_CODES.SOCKET_UNREACHABLE],
+      ["SOCKET_CLOSED", RELAY_EXIT_CODES.SOCKET_CLOSED],
+      ["MISSING_IDENTITY", RELAY_EXIT_CODES.MISSING_IDENTITY],
+    ];
+    for (const [key, value] of pairs) {
+      expect(source).toMatch(new RegExp(`${key}:\\s*${value}\\b`));
+    }
+  });
+
+  it("镜像面不自作主张扩充：NODE/SCRIPT 不在镜像表（代理零消费，见 relay.mjs 头注）", () => {
+    // 若未来有人在 relay.mjs 加镜像而忘记消费，契约面应当显式扩表——此处断言现状
+    // 「镜像常量恰好是代理实际消费的三个 env 名」防镜像面无界生长。
+    expect(source).toMatch(/const RELAY_ENV_SOCKET/);
+    expect(source).not.toMatch(/const RELAY_ENV_NODE\b/);
+    expect(source).not.toMatch(/const RELAY_ENV_SCRIPT\b/);
+  });
+});
+
+// ── 2. pi-invocation 通道契约（spawn 目标切换：全有或全无 + probe 排除）──
+
+describe("relay 变体 C-通道：getPiInvocation 三分支契约", () => {
+  const originalArgv = process.argv;
+  const originalExecPath = process.execPath;
+
+  beforeEach(() => {
+    // 落到「node + 不存在脚本 → pi-in-PATH」稳定断言直连形态
+    Object.defineProperty(process, "argv", { value: ["node", "/nonexistent"], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/node", configurable: true });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process, "argv", { value: originalArgv, configurable: true });
+    Object.defineProperty(process, "execPath", { value: originalExecPath, configurable: true });
+    setRelayEnv(undefined);
+  });
+
+  it("三 env 齐备 → 代理形态（command=NODE、args[0]=SCRIPT，userArgs 原样后置）", () => {
+    setRelayEnv(RELAY_FULL);
+    const result = getPiInvocation(["--mode", "rpc", "--session-dir", "/x"]);
+    expect(result.command).toBe(RELAY_FULL[RELAY_ENV_NODE]);
+    expect(result.args).toEqual([
+      RELAY_FULL[RELAY_ENV_SCRIPT],
+      "--mode",
+      "rpc",
+      "--session-dir",
+      "/x",
+    ]);
+  });
+
+  it.each([...RELAY_ENV_KEYS])("env 缺失 %s → 回落直连（全有或全无，E-TUI 零回归）", (missing) => {
+    const partial = { ...RELAY_FULL };
+    delete partial[missing];
+    setRelayEnv(partial);
+    const result = getPiInvocation(["--mode", "rpc"]);
+    expect(result.command).toBe("pi");
+    expect(result.args).toEqual(["--mode", "rpc"]);
+  });
+
+  it("relay:false → 直连（probe 探 pi 本体可解析性，不经 relay）", () => {
+    setRelayEnv(RELAY_FULL);
+    const result = getPiInvocation(["--version"], { relay: false });
+    expect(result.command).toBe("pi");
+    expect(result.args).toEqual(["--version"]);
+  });
+});
+
+// ── 3. buildChildEnv 归属契约（runSpawn 集成，mock spawn 捕获 childEnv）──
+
+describe("relay 变体 C-归属：buildChildEnv 激活写入 / 未激活不写", () => {
+  interface FakeChild {
+    pid: number;
+    stdout: PassThrough;
+    stderr: PassThrough;
+    killed: boolean;
+    emit(event: string, ...args: unknown[]): boolean;
+  }
+
+  function makeRecord(): ReturnType<typeof createRecord> {
+    return createRecord("relay-env-record-1", {
+      agent: "general-purpose",
+      model: "test/model",
+      mode: "sync",
+      task: "test task",
+      startedAt: Date.now(),
+      rootSessionId: "s1",
+      parentRecordId: undefined,
+      depth: 0,
+    });
+  }
+
+  function makeRunOpts(): RunOptions {
+    return {
+      resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
+      agentConfig: undefined,
+      appendSystemPrompt: undefined,
+      skillPath: undefined,
+      schema: undefined,
+      maxTurns: undefined,
+      graceTurns: undefined,
+      signal: undefined,
+      onEvent: undefined,
+    };
+  }
+
+  function makeCtx(): SessionRunnerContext {
+    return {
+      cwd: "/fake/cwd",
+      agentDir: "/fake/agent",
+      skillDirs: [],
+      mainCwd: "/fake/cwd",
+      sessionRootId: "relay-root-session",
+      rootCwd: "/fake/cwd",
+    };
+  }
+
+  function getLastSpawnEnv(): Record<string, string | undefined> {
+    return (mockSpawn.mock.calls.at(-1)?.[2]?.env as Record<string, string | undefined>) ?? {};
+  }
+
+  function getLastSpawnedChild(): FakeChild {
+    const result = mockSpawn.mock.results.at(-1);
+    if (!result) throw new Error("spawn was not called yet");
+    return result.value as FakeChild;
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setRelayEnv(undefined);
+  });
+
+  afterEach(() => {
+    setRelayEnv(undefined);
+    vi.restoreAllMocks();
+  });
+
+  it("激活：childEnv 写入归属键（SESSION_ID=ctx.sessionRootId、RECORD_ID=record.id）", async () => {
+    setRelayEnv(RELAY_FULL);
+    const record = makeRecord();
+    const ctx = makeCtx();
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn(mockSpawn);
+    const childEnv = getLastSpawnEnv();
+    expect(childEnv[RELAY_ENV_SESSION_ID]).toBe(ctx.sessionRootId);
+    expect(childEnv[RELAY_ENV_RECORD_ID]).toBe(record.id);
+    // 顺带契约：激活时 spawn 目标即代理（command=NODE、args[0]=SCRIPT）
+    expect(mockSpawn.mock.calls.at(-1)?.[0]).toBe(RELAY_FULL[RELAY_ENV_NODE]);
+    expect(mockSpawn.mock.calls.at(-1)?.[1]?.[0]).toBe(RELAY_FULL[RELAY_ENV_SCRIPT]);
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("未激活：不写入归属键（继承 process.env 原值，无 relay 环境零噪声）", async () => {
+    setRelayEnv(undefined);
+    const record = makeRecord();
+    const ctx = makeCtx();
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn(mockSpawn);
+    const childEnv = getLastSpawnEnv();
+    // 「不写」的精确语义 = 继承值保持（本用例前置已删，故 undefined），而非写 record 值
+    expect(childEnv[RELAY_ENV_SESSION_ID]).toBe(process.env[RELAY_ENV_SESSION_ID]);
+    expect(childEnv[RELAY_ENV_RECORD_ID]).toBe(process.env[RELAY_ENV_RECORD_ID]);
+    expect(childEnv[RELAY_ENV_SESSION_ID]).not.toBe(ctx.sessionRootId);
+    expect(childEnv[RELAY_ENV_RECORD_ID]).not.toBe(record.id);
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("未激活但环境残留归属值：继承值保持不被覆盖（无害性锁定）", async () => {
+    // 场景：孙进程链上 runtime 已剥离三激活 env（relay-registry 剥离逻辑），但主进程 env
+    // 残留旧归属值——buildChildEnv 未激活不写 = 不覆盖继承值（设计 §5.2-2 语义）。
+    setRelayEnv({ [RELAY_ENV_SESSION_ID]: "stale-inherited-sid", [RELAY_ENV_RECORD_ID]: "stale-inherited-rid" });
+    expect(isRelayActive(process.env)).toBe(false);
+    const record = makeRecord();
+    const ctx = makeCtx();
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn(mockSpawn);
+    const childEnv = getLastSpawnEnv();
+    expect(childEnv[RELAY_ENV_SESSION_ID]).toBe("stale-inherited-sid");
+    expect(childEnv[RELAY_ENV_RECORD_ID]).toBe("stale-inherited-rid");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+});

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");
+  });
+});