@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/src/execution/__tests__/execution-record.test.ts

@@ -20,7 +20,8 @@ import {
   tryTransition,
   updateFromEvent,
 } from "../execution-record.ts";
-import type { AgentResult, ExecutionRecord, Turn } from "../types.ts";
+import type { AgentResult, ExecutionRecord, SubagentRecord, Turn } from "../types.ts";
+import { toSubagentRecordEntry } from "../record-entry.ts";
 
 // ── 常量（与源码 module-private 值对齐，测试用字面量）──
 const TURN_SUMMARY_MAX = 80;
@@ -1156,3 +1157,128 @@ describe("tool_end running index [perf]", () => {
     expect(record.turns[1]!.toolCalls[0]).toMatchObject({ toolName: "write", result: "w-done", _status: "done" });
   });
 });
+
+// ============================================================
+// P4 引擎留痕字段（engine / engineFallback，D9①）
+// ============================================================
+
+describe("createRecord 引擎留痕字段（P4）", () => {
+  it("identity 带 engine/engineFallback 时进 record，JSON 序列化保留（持久化语义）", () => {
+    const record = createRecord("sa-engine-1", {
+      agent: "reviewer",
+      model: "p/m",
+      mode: "background",
+      task: "t",
+      slug: "s",
+      startedAt: 1,
+      engine: "pi",
+      engineFallback: { from: "zcode", reason: "engine_probe_failed" },
+    });
+    expect(record.engine).toBe("pi");
+    expect(record.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+    const serialized = JSON.parse(JSON.stringify(record)) as Record<string, unknown>;
+    expect(serialized["engine"]).toBe("pi");
+    expect(serialized["engineFallback"]).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("不传时两字段缺省（存量 record 消费方零影响——序列化后无键产生）", () => {
+    const record = createRecord("sa-engine-2", {
+      agent: "worker",
+      model: "p/m",
+      mode: "background",
+      task: "t",
+      slug: "s",
+      startedAt: 1,
+    });
+    expect(record.engine).toBeUndefined();
+    expect(record.engineFallback).toBeUndefined();
+    const serialized = JSON.parse(JSON.stringify(record)) as Record<string, unknown>;
+    expect("engine" in serialized).toBe(false);
+    expect("engineFallback" in serialized).toBe(false);
+  });
+
+  it("SubagentRecord → entry 投影保留两字段（record-entry 持久化链）", () => {
+    const base: SubagentRecord = {
+      id: "sa-engine-3",
+      agent: "reviewer",
+      task: "t",
+      slug: "s",
+      status: "running",
+      mode: "background",
+      startedAt: 1,
+      rootSessionId: undefined,
+      parentRecordId: undefined,
+      depth: 0,
+      endedAt: undefined,
+      turns: 0,
+      totalTokens: 0,
+      model: "p/m",
+      thinkingLevel: undefined,
+      eventLog: [],
+      displayItems: [],
+    };
+    const entry = toSubagentRecordEntry({ ...base, engine: "pi", engineFallback: { from: "zcode", reason: "engine_probe_failed" } });
+    expect(entry.engine).toBe("pi");
+    expect(entry.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+    // 存量 record（无字段）投影后同样缺省——消费方按 pi 投影，零迁移
+    expect(toSubagentRecordEntry(base).engine).toBeUndefined();
+  });
+});
+
+// ============================================================
+// U1 engine 三字段 entry 往返（engineHandle 贯通）
+// ============================================================
+describe("SubagentRecord ↔ subagent-record entry 往返（U1 engineHandle）", () => {
+  const base: SubagentRecord = {
+    id: "sa-engine-4",
+    agent: "reviewer",
+    task: "t",
+    slug: "s",
+    status: "running",
+    mode: "background",
+    startedAt: 1,
+    rootSessionId: undefined,
+    parentRecordId: undefined,
+    depth: 0,
+    endedAt: undefined,
+    turns: 0,
+    totalTokens: 0,
+    model: "p/m",
+    thinkingLevel: undefined,
+    eventLog: [],
+    displayItems: [],
+  };
+  const handle = { sessionRef: { sessionId: "s-1", dbPath: "pool/zcode.db" }, journalPath: "/abs/journal.jsonl", poolKey: "p1" };
+
+  it("record 含三字段 → entry JSON → 解析回 deep equal（sessionRef 键不枚举整体透传）", () => {
+    const entry = toSubagentRecordEntry({ ...base, engine: "zcode", engineFallback: { from: "zcode", reason: "engine_probe_failed" }, engineHandle: handle });
+    const roundTripped = JSON.parse(JSON.stringify(entry));
+    expect(roundTripped).toEqual({
+      v: 1,
+      id: "sa-engine-4",
+      agent: "reviewer",
+      task: "t",
+      slug: "s",
+      status: "running",
+      mode: "background",
+      startedAt: 1,
+      depth: 0,
+      turns: 0,
+      totalTokens: 0,
+      model: "p/m",
+      eventLog: [],
+      displayItems: [],
+      engine: "zcode",
+      engineFallback: { from: "zcode", reason: "engine_probe_failed" },
+      engineHandle: handle,
+    });
+    expect(toSubagentRecordEntry({ ...base, engineHandle: handle }).engineHandle).toEqual(handle);
+  });
+
+  it("record 无三字段 → entry JSON 不含对应键（undefined 经 JSON.stringify 自然省略，存量零迁移）", () => {
+    const serialized = JSON.parse(JSON.stringify(toSubagentRecordEntry(base))) as Record<string, unknown>;
+    expect("engine" in serialized).toBe(false);
+    expect("engineFallback" in serialized).toBe(false);
+    expect("engineHandle" in serialized).toBe(false);
+  });
+});

package/src/execution/__tests__/pi-invocation.test.ts

@@ -3,9 +3,10 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { afterEach,describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 
 import { getPiInvocation } from "../pi-invocation.ts";
+import { RELAY_ENV_NODE, RELAY_ENV_SCRIPT, RELAY_ENV_SOCKET } from "../relay-env.ts";
 
 describe("getPiInvocation", () => {
   const originalArgv = process.argv;
@@ -71,3 +72,63 @@ describe("getPiInvocation", () => {
     expect(result.args).toEqual([]);
   });
 });
+
+describe("getPiInvocation relay 分支（E 方案 §5.1）", () => {
+  const originalArgv = process.argv;
+  const originalExecPath = process.execPath;
+  const RELAY_ENVS = [RELAY_ENV_SOCKET, RELAY_ENV_NODE, RELAY_ENV_SCRIPT] as const;
+  /** 三 env 齐备的基准值（改 argv/execPath 隔离直连分支，只测 relay 判定本身）。 */
+  const RELAY_FULL: Record<string, string> = {
+    [RELAY_ENV_SOCKET]: "/tmp/relay-test.sock",
+    [RELAY_ENV_NODE]: "/usr/bin/relay-node",
+    [RELAY_ENV_SCRIPT]: "/opt/relay/relay.mjs",
+  };
+
+  afterEach(() => {
+    Object.defineProperty(process, "argv", { value: originalArgv, configurable: true });
+    Object.defineProperty(process, "execPath", { value: originalExecPath, configurable: true });
+    for (const key of RELAY_ENVS) delete process.env[key];
+  });
+
+  /** 形态 1：三 env 齐备 + 默认 opts → relay invocation（command=NODE、args[0]=SCRIPT）。 */
+  it("三 env 齐备（无 opts）→ 代理形态 <NODE> <SCRIPT> <userArgs>", () => {
+    Object.assign(process.env, RELAY_FULL);
+    const result = getPiInvocation(["--mode", "rpc"]);
+    expect(result.command).toBe(RELAY_FULL[RELAY_ENV_NODE]);
+    expect(result.args).toEqual([RELAY_FULL[RELAY_ENV_SCRIPT], "--mode", "rpc"]);
+  });
+
+  /** 形态 1 变体：opts.relay === true 显式开启，行为与缺省一致。 */
+  it("三 env 齐备 + opts.relay=true → 同缺省（显式开启非必填）", () => {
+    Object.assign(process.env, RELAY_FULL);
+    const result = getPiInvocation(["--mode", "rpc"], { relay: true });
+    expect(result.command).toBe(RELAY_FULL[RELAY_ENV_NODE]);
+    expect(result.args[0]).toBe(RELAY_FULL[RELAY_ENV_SCRIPT]);
+  });
+
+  /** 形态 2：三缺一逐个枚举 → 回落现状直连（全有或全无，E-TUI 零回归）。 */
+  it("三缺一（逐个枚举）→ 现状直连分支", () => {
+    // 直连分支落到「node + 不存在脚本 → pi-in-PATH」可稳定断言（不依赖测试机 execPath 形态）
+    Object.defineProperty(process, "argv", { value: ["node", "/nonexistent"], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/node", configurable: true });
+    for (const missing of RELAY_ENVS) {
+      const partial = { ...RELAY_FULL };
+      delete partial[missing];
+      for (const key of RELAY_ENVS) delete process.env[key];
+      Object.assign(process.env, partial);
+      const result = getPiInvocation(["--mode", "rpc"]);
+      expect(result.command).toBe("pi"); // 分支 3：通用 runtime + 脚本不存在 → PATH
+      expect(result.args).toEqual(["--mode", "rpc"]);
+    }
+  });
+
+  /** 形态 3：probe 排除——显式 relay:false 时即便三 env 齐备也直连。 */
+  it("relay:false 强制直连（probe 语义：探 pi 本体，不探 runtime 健康）", () => {
+    Object.assign(process.env, RELAY_FULL);
+    Object.defineProperty(process, "argv", { value: ["node", "/nonexistent"], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/node", configurable: true });
+    const result = getPiInvocation(["--version"], { relay: false });
+    expect(result.command).toBe("pi");
+    expect(result.args).toEqual(["--version"]);
+  });
+});

package/src/execution/__tests__/relay-agent.test.ts

@@ -0,0 +1,448 @@
+// src/execution/__tests__/relay-agent.test.ts
+//
+// relay.mjs 代理 CLI 协议行为集成测试（E-1 验收）——本地环回 socket + 伪 runtime
+// （net.createServer 模拟 runtime 侧行为），spawn 真实代理进程逐条断言：
+//   1. 启动自检：归属 env（SESSION_ID/RECORD_ID）缺失 / socket env 缺失 → 退出码 13
+//   2. socket 不可达（重试一次后仍失败）→ 退出码 11 + stderr 含路径与恢复指引
+//   3. 握手帧字段完整（v/kind/mainSessionId/recordId/argv/env/cwd）
+//   4. down/up/up-stderr 字节往返保真（中文/换行/空字节的二进制 buffer）
+//   5. exit 帧退出码传播 / 退出前 stdout 已 flush
+//   6. exit 帧 signal 传播（spawn 方观察到 (code=null, signal)）
+//   7. socket 断 → 退出码 12（崩溃矩阵②的 extension 侧感知机制）
+//   8. reject version → 退出码 10 + 重装指引；reject 其他 reason → 12
+//   9. 背压：1MB 随机字节经代理双向环回（stdin→down→server→up→stdout）收齐无丢字节
+
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import * as crypto from "node:crypto";
+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 { afterEach, describe, expect, it } from "vitest";
+
+import {
+  RELAY_ENV_NODE,
+  RELAY_ENV_RECORD_ID,
+  RELAY_ENV_SCRIPT,
+  RELAY_ENV_SESSION_ID,
+  RELAY_ENV_SOCKET,
+  RELAY_EXIT_CODES,
+  RELAY_PROTOCOL_VERSION,
+} from "../relay-env.ts";
+
+/** 被测脚本：包根 relay/relay.mjs（与 src/ 平行的零依赖脚本，不参与 TS 编译）。 */
+const RELAY_SCRIPT_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../../relay/relay.mjs",
+);
+
+/** 协议帧（代理 ↔ runtime JSONL）。字段全部可选除 kind——按 kind 分支后逐字段断言。 */
+interface RelayFrame {
+  kind: string;
+  v?: unknown;
+  dir?: unknown;
+  b64?: unknown;
+  code?: unknown;
+  signal?: unknown;
+  reason?: unknown;
+  supported?: unknown;
+  mainSessionId?: unknown;
+  recordId?: unknown;
+  argv?: unknown;
+  env?: unknown;
+  cwd?: unknown;
+}
+
+/** JSON.parse + 运行时守卫（禁裸 as）：非对象或无 string kind 视为不可解析。 */
+function parseFrame(line: string): RelayFrame | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const kind = (parsed as Record<string, unknown>).kind;
+  if (typeof kind !== "string") return null;
+  return { ...(parsed as Record<string, unknown>), kind };
+}
+
+interface FakeRuntime {
+  socketPath: string;
+  server: net.Server;
+  conn: net.Socket | null;
+  /** 第一帧 handshake（默认 respond 逻辑 accept 后 resolve；自定义 respond 也 resolve）。 */
+  handshakePromise: Promise<RelayFrame>;
+  /** 收到的全部 down 帧解码后的字节块。 */
+  downChunks: Buffer[];
+  downTotal: () => number;
+  send: (frame: Record<string, unknown>) => boolean;
+  destroyConn: () => void;
+  close: () => Promise<void>;
+}
+
+/** 默认 runtime 行为：收 handshake → 回 accept。 */
+function defaultRespond(_handshake: RelayFrame, rt: FakeRuntime): void {
+  rt.send({ v: RELAY_PROTOCOL_VERSION, kind: "accept" });
+}
+
+function startFakeRuntime(
+  socketPath: string,
+  respond: (handshake: RelayFrame, rt: FakeRuntime) => void = defaultRespond,
+): Promise<FakeRuntime> {
+  // handshake 的 settle 状态（resolve 回调 + 已收到帧），供「仅首个 handshake 帧响应」判定
+  const handshakeState: { resolve: ((f: RelayFrame) => void) | null; frame: RelayFrame | null } = {
+    resolve: null,
+    frame: null,
+  };
+  const handshakePromise = new Promise<RelayFrame>((resolve) => {
+    handshakeState.resolve = resolve;
+  });
+  let connRef: net.Socket | null = null;
+  const downChunks: Buffer[] = [];
+  const server = net.createServer((conn) => {
+    connRef = conn;
+    let lineBuf = "";
+    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()) continue;
+        const frame = parseFrame(line);
+        if (!frame) continue;
+        if (frame.kind === "handshake") {
+          // 仅首个 handshake 帧响应 + settle（单连接单握手是协议形态）
+          if (handshakeState.frame === null) {
+            handshakeState.frame = frame;
+            respond(frame, rt);
+            handshakeState.resolve?.(frame);
+          }
+          continue;
+        }
+        if (frame.kind === "data" && frame.dir === "down" && typeof frame.b64 === "string") {
+          downChunks.push(Buffer.from(frame.b64, "base64"));
+        }
+      }
+    });
+  });
+  const rt: FakeRuntime = {
+    socketPath,
+    server,
+    get conn() {
+      return connRef;
+    },
+    downChunks,
+    downTotal: () => downChunks.reduce((sum, c) => sum + c.length, 0),
+    send: (frame) => {
+      if (!connRef || connRef.destroyed) throw new Error("fake runtime: no live connection");
+      return connRef.write(JSON.stringify(frame) + "\n");
+    },
+    destroyConn: () => {
+      connRef?.destroy();
+    },
+    handshakePromise,
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      }),
+  };
+  return new Promise<FakeRuntime>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      activeServers.push(server);
+      resolve(rt);
+    });
+  });
+}
+
+interface SpawnOpts {
+  /** undefined = 不注入该 env（测缺失路径）。 */
+  socketPath?: string;
+  sessionId?: string;
+  recordId?: string;
+  argv?: string[];
+}
+
+/**
+ * spawn 代理进程（node 直跑 relay.mjs，env 精确控制 5 个 relay 变量）。
+ * stdout/stderr 收集器随 spawn 立即挂上——对齐真实契约（extension 的 stdout pump
+ * 从 spawn 起消费；若测试侧不读，代理的 stdout 背压会正确地暂停 socket，测试卡死）。
+ */
+interface CollectedChild {
+  child: ChildProcessWithoutNullStreams;
+  stdoutChunks: Buffer[];
+  stderrChunks: Buffer[];
+}
+
+function spawnRelay(opts: SpawnOpts): CollectedChild {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  delete env[RELAY_ENV_SOCKET];
+  delete env[RELAY_ENV_NODE];
+  delete env[RELAY_ENV_SCRIPT];
+  delete env[RELAY_ENV_SESSION_ID];
+  delete env[RELAY_ENV_RECORD_ID];
+  if (opts.socketPath !== undefined) env[RELAY_ENV_SOCKET] = opts.socketPath;
+  if (opts.sessionId !== undefined) env[RELAY_ENV_SESSION_ID] = opts.sessionId;
+  if (opts.recordId !== undefined) env[RELAY_ENV_RECORD_ID] = opts.recordId;
+  const child = spawn(process.execPath, [RELAY_SCRIPT_PATH, ...(opts.argv ?? ["--mode", "rpc"])], {
+    env,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  const collected: CollectedChild = {
+    child,
+    stdoutChunks: [],
+    stderrChunks: [],
+  };
+  child.stdout.on("data", (c: Buffer) => collected.stdoutChunks.push(c));
+  child.stderr.on("data", (c: Buffer) => collected.stderrChunks.push(c));
+  activeChildren.push(child);
+  return collected;
+}
+
+interface ExitResult {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  stderr: string;
+  stdout: Buffer;
+}
+
+/** 等 child close，输出取自 spawn 时挂起的收集器（close 时数据已齐）。 */
+function waitForExit({ child, stdoutChunks, stderrChunks }: CollectedChild): Promise<ExitResult> {
+  return new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", (code, signal) => {
+      resolve({
+        code,
+        signal,
+        stdout: Buffer.concat(stdoutChunks),
+        stderr: Buffer.concat(stderrChunks).toString("utf8"),
+      });
+    });
+  });
+}
+
+/** 轮询等待条件成立（25ms 间隔；超时抛错）。 */
+async function pollUntil(predicate: () => boolean, timeoutMs: number, what: string): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) throw new Error(`timeout waiting for ${what}`);
+    await new Promise((r) => setTimeout(r, 25));
+  }
+}
+
+/** 分块发送大 up 帧（64KB/帧 + socket drain 等待，驱动代理侧 socket→stdout 背压路径）。 */
+async function sendLargeUp(rt: FakeRuntime, data: Buffer): Promise<void> {
+  const CHUNK = 64 * 1024;
+  for (let i = 0; i < data.length; i += CHUNK) {
+    const frame = {
+      v: RELAY_PROTOCOL_VERSION,
+      kind: "data",
+      dir: "up",
+      b64: data.subarray(i, i + CHUNK).toString("base64"),
+    };
+    if (!rt.send(frame)) {
+      await new Promise<void>((resolve) => {
+        const c = rt.conn;
+        if (!c) return resolve();
+        c.once("drain", () => resolve());
+      });
+    }
+  }
+}
+
+const activeServers: net.Server[] = [];
+const activeChildren: ChildProcessWithoutNullStreams[] = [];
+const activeTmpDirs: string[] = [];
+
+function makeSocketPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "relay-agent-test-"));
+  activeTmpDirs.push(dir);
+  return path.join(dir, "relay.sock");
+}
+
+afterEach(async () => {
+  for (const child of activeChildren) {
+    if (!child.killed) child.kill("SIGKILL");
+  }
+  activeChildren.length = 0;
+  await Promise.all(
+    activeServers.map(
+      (s) => new Promise<void>((resolve) => s.close(() => resolve())),
+    ),
+  );
+  activeServers.length = 0;
+  for (const dir of activeTmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+  activeTmpDirs.length = 0;
+});
+
+describe("relay agent CLI (relay.mjs)", () => {
+  it("identity env missing → exit 13 + stderr names the env vars", { timeout: 10_000 }, async () => {
+    const child = spawnRelay({});
+    const res = await waitForExit(child);
+    expect(res.code).toBe(RELAY_EXIT_CODES.MISSING_IDENTITY);
+    expect(res.stderr).toContain(RELAY_ENV_SESSION_ID);
+    expect(res.stderr).toContain(RELAY_ENV_RECORD_ID);
+  });
+
+  it("socket env missing (identity present) → exit 13", { timeout: 10_000 }, async () => {
+    const child = spawnRelay({ sessionId: "sess-1", recordId: "rec-1" });
+    const res = await waitForExit(child);
+    expect(res.code).toBe(RELAY_EXIT_CODES.MISSING_IDENTITY);
+    expect(res.stderr).toContain(RELAY_ENV_SOCKET);
+  });
+
+  it("socket unreachable → retry once then exit 11 with path + recovery hint", { timeout: 15_000 }, async () => {
+    const socketPath = path.join(makeSocketPath(), "never-listening.sock");
+    const child = spawnRelay({ socketPath, sessionId: "sess-1", recordId: "rec-1" });
+    const res = await waitForExit(child);
+    expect(res.code).toBe(RELAY_EXIT_CODES.SOCKET_UNREACHABLE);
+    expect(res.stderr).toContain(socketPath);
+    expect(res.stderr).toContain("重试任务");
+    expect(res.stderr).toContain("重启 xyz-agent");
+  });
+
+  it("handshake frame carries full spawn spec (v/kind/mainSessionId/recordId/argv/env/cwd)", { timeout: 15_000 }, async () => {
+    const socketPath = makeSocketPath();
+    const rt = await startFakeRuntime(socketPath);
+    const argv = ["--mode", "rpc", "--model", "test/model"];
+    const child = spawnRelay({ socketPath, sessionId: "sess-42", recordId: "rec-99", argv });
+    const hs = await rt.handshakePromise;
+    expect(hs.kind).toBe("handshake");
+    expect(hs.v).toBe(RELAY_PROTOCOL_VERSION);
+    expect(hs.mainSessionId).toBe("sess-42");
+    expect(hs.recordId).toBe("rec-99");
+    expect(hs.argv).toEqual(argv);
+    expect(hs.cwd).toBe(process.cwd());
+    // env 全量转发：含注入的归属 env 与 socket env（runtime spawn 真实 pi 原样使用）
+    expect(hs.env).toBeTypeOf("object");
+    expect(hs.env).toHaveProperty(RELAY_ENV_SESSION_ID, "sess-42");
+    expect(hs.env).toHaveProperty(RELAY_ENV_RECORD_ID, "rec-99");
+    expect(hs.env).toHaveProperty(RELAY_ENV_SOCKET, socketPath);
+    // 收尾：默认 respond 已 accept，发 exit 让子进程退出
+    rt.send({ kind: "exit", code: 0 });
+    const res = await waitForExit(child);
+    expect(res.code).toBe(0);
+  });
+
+  it("byte roundtrip fidelity: down/up/up-stderr with CJK, newlines, NUL bytes", { timeout: 15_000 }, async () => {
+    const socketPath = makeSocketPath();
+    const rt = await startFakeRuntime(socketPath);
+    const child = spawnRelay({ socketPath, sessionId: "s", recordId: "r" });
+    await rt.handshakePromise;
+
+    // 下行字节：JSON 命令行 + 中文 + 换行（挑战 JSONL 行协议）+ 空字节（挑战文本假设）
+    const downBytes = Buffer.concat([
+      Buffer.from('{"type":"prompt","message":"你好，世界\n', "utf8"),
+      Buffer.from([0x00, 0x01, 0xff, 0xfe]),
+      Buffer.from('第二行"}\n', "utf8"),
+    ]);
+    child.child.stdin.write(downBytes);
+    await pollUntil(() => rt.downTotal() === downBytes.length, 5_000, "down bytes");
+    expect(Buffer.concat(rt.downChunks)).toEqual(downBytes);
+
+    // 上行 stdout / stderr 字节保真
+    const upBytes = Buffer.concat([
+      Buffer.from("stdout 流式输出\nline2\0", "utf8"),
+      crypto.randomBytes(64),
+    ]);
+    const upStderrBytes = Buffer.concat([
+      Buffer.from("stderr 诊断\n\0字节", "utf8"),
+      crypto.randomBytes(32),
+    ]);
+    rt.send({ v: RELAY_PROTOCOL_VERSION, kind: "data", dir: "up", b64: upBytes.toString("base64") });
+    rt.send({
+      v: RELAY_PROTOCOL_VERSION,
+      kind: "data",
+      dir: "up-stderr",
+      b64: upStderrBytes.toString("base64"),
+    });
+    rt.send({ kind: "exit", code: 3 });
+    const res = await waitForExit(child);
+    expect(res.stdout).toEqual(upBytes);
+    expect(res.stderr).toEqual(upStderrBytes.toString("utf8"));
+    expect(res.code).toBe(3);
+  });
+
+  it("exit frame code propagation flushes stdout first", { timeout: 10_000 }, async () => {
+    const socketPath = makeSocketPath();
+    const rt = await startFakeRuntime(socketPath);
+    const child = spawnRelay({ socketPath, sessionId: "s", recordId: "r" });
+    await rt.handshakePromise;
+    const upBytes = Buffer.from("final bytes before exit\n", "utf8");
+    rt.send({ v: RELAY_PROTOCOL_VERSION, kind: "data", dir: "up", b64: upBytes.toString("base64") });
+    rt.send({ kind: "exit", code: 7 });
+    const res = await waitForExit(child);
+    expect(res.code).toBe(7);
+    expect(res.stdout).toEqual(upBytes);
+  });
+
+  it("exit frame signal propagation → close(null, SIGTERM)", { timeout: 10_000 }, async () => {
+    const socketPath = makeSocketPath();
+    const rt = await startFakeRuntime(socketPath);
+    const child = spawnRelay({ socketPath, sessionId: "s", recordId: "r" });
+    await rt.handshakePromise;
+    rt.send({ kind: "exit", signal: "SIGTERM" });
+    const res = await waitForExit(child);
+    expect(res.signal).toBe("SIGTERM");
+    expect(res.code).toBeNull();
+  });
+
+  it("socket closed by runtime → exit 12", { timeout: 10_000 }, async () => {
+    const socketPath = makeSocketPath();
+    const rt = await startFakeRuntime(socketPath);
+    const child = spawnRelay({ socketPath, sessionId: "s", recordId: "r" });
+    await rt.handshakePromise;
+    rt.destroyConn();
+    const res = await waitForExit(child);
+    expect(res.code).toBe(RELAY_EXIT_CODES.SOCKET_CLOSED);
+    expect(res.stderr).toContain("closed");
+  });
+
+  it("reject reason=version → exit 10 + reinstall recovery hint", { timeout: 10_000 }, async () => {
+    const socketPath = makeSocketPath();
+    const rt = await startFakeRuntime(socketPath, (_hs, r) => {
+      r.send({ kind: "reject", reason: "version", supported: [RELAY_PROTOCOL_VERSION] });
+    });
+    const child = spawnRelay({ socketPath, sessionId: "s", recordId: "r" });
+    const res = await waitForExit(child);
+    expect(res.code).toBe(RELAY_EXIT_CODES.VERSION_MISMATCH);
+    expect(res.stderr).toContain("version mismatch");
+    expect(res.stderr).toContain("重装应用");
+  });
+
+  it("reject with non-version reason → exit 12", { timeout: 10_000 }, async () => {
+    const socketPath = makeSocketPath();
+    const rt = await startFakeRuntime(socketPath, (_hs, r) => {
+      r.send({ kind: "reject", reason: "handshake_invalid" });
+    });
+    const child = spawnRelay({ socketPath, sessionId: "s", recordId: "r" });
+    const res = await waitForExit(child);
+    expect(res.code).toBe(RELAY_EXIT_CODES.SOCKET_CLOSED);
+    expect(res.stderr).toContain("handshake_invalid");
+  });
+
+  it("backpressure: 1MB random bytes survive full down→up roundtrip", { timeout: 60_000 }, async () => {
+    const socketPath = makeSocketPath();
+    const rt = await startFakeRuntime(socketPath);
+    const child = spawnRelay({ socketPath, sessionId: "s", recordId: "r" });
+    await rt.handshakePromise;
+
+    const payload = crypto.randomBytes(1024 * 1024);
+    child.child.stdin.write(payload);
+    await pollUntil(() => rt.downTotal() === payload.length, 30_000, "1MB down bytes");
+    const receivedDown = Buffer.concat(rt.downChunks);
+    expect(receivedDown).toEqual(payload);
+
+    // 同一 payload 分 64KB up 帧回发（驱动代理 socket→stdout 背压 + 行缓冲路径）
+    await sendLargeUp(rt, receivedDown);
+    rt.send({ kind: "exit", code: 0 });
+    const res = await waitForExit(child);
+    expect(res.code).toBe(0);
+    expect(res.stdout).toEqual(payload);
+  });
+});