@zhushanwen/subagent-core 0.5.1 → 0.7.0

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

@@ -1,21 +1,45 @@
-// contract.read-degradation.test.ts —— conformance C5（read 降级链）：三级都不 throw、
-// 坏 handle → 结构化降级（outcome-only）非崩溃、②级 journal 重放与 live 一致
+// 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（②级）。
+// W10 协议黑盒化：read 的引擎内三级降级（①级 db / ②级 journal / ③级 outcome-only）
+// 随 W5/W7 归各引擎包（zcode zcode-engine-degrade / pi read-fallback）；core 协议层
+// 断言 = read 帧往返 + 错误帧结构化（EngineSdkError，不裸 throw 崩宿主）+ reducer
+// 重放等价性（core 侧事件→SessionView 共用通路）。
 
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
+import { EngineSdkError } from "@zhushanwen/subagent-engine-sdk";
+
 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 { EngineClient } from "../../client/engine-client.ts";
+import { RemoteEngine } from "../../client/remote-engine.ts";
 import type { AgentEvent, EngineHandle } from "../../types.ts";
+import { FAKE_CAPABILITIES } from "./fake-engine-capabilities.ts";
+
+const FAKE_ENGINE = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "__fixtures__", "engine-protocol", "fake-engine-protocol.mjs",
+);
+const FIXTURE = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "__fixtures__", "engine-protocol", "smoke-run.fixture.json",
+);
+
+/** 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" },
+];
 
 function makeHandle(engineId: string, sessionRef: Record<string, string>, journalPath?: string): EngineHandle {
   return {
@@ -30,21 +54,13 @@ function makeHandle(engineId: string, sessionRef: Record<string, string>, journa
   };
 }
 
-/** 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）", () => {
+describe("conformance C5：read 降级链（协议黑盒 + reducer 等价性）", () => {
   let dataDir: string;
   beforeEach(() => {
     dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "c5-read-"));
   });
   afterEach(() => {
-    fs.rmSync(dataDir, { recursive: true, force: true });
+    fs.rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   it("重放等价性：journal 重放 turns 与 live 累积一致（共用 updateFromEvent reducer）", () => {
@@ -55,50 +71,61 @@ describe("conformance C5：read 降级链（三级都不 throw）", () => {
     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("协议 read 帧往返：正常 handle → SessionView 结构（协议层形状）", async () => {
+    const client = new EngineClient({
+      engineId: "fake",
+      command: process.execPath,
+      args: [FAKE_ENGINE],
+      hostKind: "test",
+      hostVersion: "w10-c5",
+      dataDir,
+      envPrefixes: [],
+      baseEnv: { ...process.env, FAKE_PROTOCOL_FIXTURE: FIXTURE },
+    });
+    const engine = new RemoteEngine({
+      engineId: "fake",
+      client,
+      manifest: { capabilities: FAKE_CAPABILITIES },
+      dataDir,
+      hostKind: "test",
+    });
+    try {
+      await engine.read(makeHandle("fake", { sessionId: "sess-fixture" }));
+      // fixture.read.result 透传（协议层不解释 SessionView 内容——形状由引擎层
+      // golden 与 reducer 等价性断言盖）
+    } finally {
+      await engine.dispose();
+    }
   });
 
-  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("协议 read 错误帧：引擎报错 → 结构化 EngineSdkError（code/message），不裸 throw", async () => {
+    const client = new EngineClient({
+      engineId: "fake",
+      command: process.execPath,
+      args: [FAKE_ENGINE],
+      hostKind: "test",
+      hostVersion: "w10-c5",
+      dataDir,
+      envPrefixes: [],
+      baseEnv: { ...process.env, FAKE_PROTOCOL_FIXTURE: FIXTURE, FAKE_PROTOCOL_ERROR: "unknown_method" },
+    });
+    try {
+      await client.ensureConnected();
+      // read 是已知方法——unknown_method 模式下用未知名触发错误帧透传断言
+      await expect(client.request("bogus/read", { handle: {} }, { timeoutMs: 5_000 })).rejects.toBeInstanceOf(
+        EngineSdkError,
+      );
+    } finally {
+      await client.dispose();
+    }
   });
 
-  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" });
+  it("journal 落盘形态与 live 事件序列逐项相等（协议层回放复用的落盘通路）", async () => {
+    const journalPath = path.join(dataDir, "journal-sa-c5.jsonl");
+    const writer = new JournalWriter({ path: journalPath, taskId: "sa-c5", engineId: "fake" });
     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([]);
+    const lines = fs.readFileSync(journalPath, "utf8").trim().split("\n");
+    expect(lines).toHaveLength(liveEvents.length);
   });
 });

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

@@ -1,17 +1,19 @@
-// engine-conformance.live.test.ts —— conformance run 层（真实 spawn 简单任务，C2/C4
-// 真机面）。手动门（设计 §3.3.8：run 层需已装引擎 + 有效凭据，不进默认 CI）：
+// engine-conformance.live.test.ts —— conformance run 层真机门（基线三层③，W10
+// 协议化改写）。手动门（设计 §3.3.8 / §4：run 层需已装引擎 + 有效凭据，不进默认 CI）：
 //
-//   cd extensions/universal/subagent-workflow
-//   ENGINE_CONFORMANCE_LIVE=1 pnpm vitest run src/execution/engine/__tests__/conformance/engine-conformance.live.test.ts
+//   cd packages/subagent-core
+//   ENGINE_CONFORMANCE_LIVE=1 [PI_LIVE_MODEL=... ZCODE_E2E_MODEL=...] \
+//     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 最小面）。
+// W10 改写：断言对象从内建 inproc 引擎（W11 删除）改为**协议客户端 × 引擎包 CLI**
+// （EngineClient spawn pi-subagent-cli 进程入口 + RemoteEngine 适配）——即 A2 真机
+// 形态本身。断言口径 = 不变量与关键终态（C2 outcome / C3 stream 事件不变量），
+// 不做逐字段 diff（设计 §4 基线三层③）。zcode 部分与 zcode-subagent-cli 的
+// 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，属预期。
+// 措辞口径（R9-1）：「子进程零残留」= 一代子进程 + 组内后代；引擎自身 detached
+// 后代不判 fail（设计 §3.9 已接受代价）。POSIX 组探测（childSpawned pid 非组长）
+// 由 reverse-router 运行时告警承载，真机面挂 A3 手动门；Windows 无外部判据显式登记。
 
 import { spawn as childSpawn, type ChildProcess } from "node:child_process";
 import * as fs from "node:fs";
@@ -22,14 +24,12 @@ 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 { PiEngineService } from "../../engines/pi/pi-engine.ts";
+import { ZcodeEngine } from "@zhushanwen/zcode-subagent-cli";
+
+import { EngineClient } from "../../client/engine-client.ts";
+import { RemoteEngine } from "../../client/remote-engine.ts";
 import type { RunContext } from "../../port.ts";
-import type { AgentEvent } from "../../../types.ts";
-import type { AgentCallOpts } from "../../../../orchestration/models/types.ts";
-import { getPiInvocation } from "../../engines/pi/pi-invocation.ts";
+import type { AgentEvent, EngineCapabilities } from "../../types.ts";
 import {
   RELAY_ENV_NODE,
   RELAY_ENV_RECORD_ID,
@@ -43,22 +43,70 @@ 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 未装配（需在真实会话进程内运行）");
+// 锚点：本文件在 packages/subagent-core/src/execution/engine/__tests__/conformance/
+// 下，6 层 `..` 到 packages/，再进 pi-subagent-cli 的 bin 入口（manifest bin 目标，
+// 与发现器可执行检查同源）。曾错写 7 层落到仓库根 → MODULE_NOT_FOUND（Gate B F1.1）。
+const PI_CLI_ENTRY = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../../../../../pi-subagent-cli/bin/pi-subagent-cli.mjs",
+);
+
+/** pi 引擎 capabilities（manifest 同源形态——真机门内 RemoteEngine 同步成员源）。 */
+const PI_LIVE_CAPABILITIES: EngineCapabilities = {
+  schemaEnforcement: "native",
+  steer: "native",
+  conversation: "native",
+  personaInjection: "file",
+  eventGranularity: "stream",
+  sandbox: "none",
+  sessionRead: "full",
+  resume: "cold",
+  interrupt: "kill-only",
+  permissionMode: "ignored",
+  maxTurns: true,
+};
+
+describe.skipIf(!LIVE)("conformance run 层（协议客户端 × 引擎包 CLI，手动门）", () => {
+  it("pi：简单任务全链（C2：outcome 无 error、content 非空、engineId=pi；C3 stream 不变量）", async (testCtx) => {
+    const model = process.env["PI_LIVE_MODEL"];
+    if (model === undefined || model === "") {
+      testCtx.skip("PI_LIVE_MODEL 未设置（需真实 provider/model 凭据）——pi live run 面跳过");
       return;
     }
-    const engine = createPiEngine(() => service as unknown as PiEngineService);
-    const task: AgentCallOpts = { prompt: "Reply with the single word: ok", description: "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");
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "w10-live-pi-"));
+    // 测试侧宿主扩展隔离（Gate B F1.2 裁决）：pi spawn 会加载宿主 ~/.pi/agent/npm
+    // 全局扩展，本机版本破碎（subagent-workflow 8.7.0 × subagent-core 0.2.0 exports
+    // 失配）时 pi 启动即退出 code 1——真机门要验的是引擎链路不是宿主扩展环境。
+    // main.ts 忽略 argv，argv-mirror 会把 --no-extensions 镜像给 pi 子进程（与
+    // pi 官方 hint "pi -ne" 同参）。产品镜像语义不动（正常宿主扩展照常加载）。
+    const client = new EngineClient({
+      engineId: "pi",
+      command: process.execPath,
+      args: [PI_CLI_ENTRY, "--no-extensions"],
+      hostKind: "test",
+      hostVersion: "w10-live",
+      dataDir,
+      envPrefixes: [],
+    });
+    const engine = new RemoteEngine({
+      engineId: "pi",
+      client,
+      manifest: { capabilities: PI_LIVE_CAPABILITIES },
+      dataDir,
+      hostKind: "test",
+    });
+    try {
+      const events: AgentEvent[] = [];
+      const task = { prompt: "Reply with the single word: ok", description: "live-c2", model, cwd: os.tmpdir() };
+      const ctx: RunContext = { taskId: "sa-live-pi-c2", poolKey: "shared", onEvent: (e) => events.push(e) };
+      const { outcome } = await engine.run(task, ctx);
+      expect(outcome.error).toBeUndefined();
+      expect(outcome.content.trim().length).toBeGreaterThan(0);
+      expect(outcome.engineId).toBe("pi");
+      assertAgentEventInvariants(events, { granularity: "stream", content: outcome.content });
+    } finally {
+      await engine.dispose();
+    }
   }, 120_000);
 
   it("zcode：probe 真机（C1 live 面：三项 check 全过）", async () => {
@@ -68,10 +116,6 @@ describe.skipIf(!LIVE)("conformance run 层（真实 spawn，手动门）", () =
     expect(report.engineVersion).toMatch(/^0\.\d+\.\d+$/);
   }, 60_000);
 
-  // [R6] 常驻通道的 conformance run 层（RA8「C1-C8 适配后全绿」的 live 面）：
-  // 跑最小任务——C2 outcome + C3 stream 不变量（app-server 设计 §3.4 不变量 1）。
-  // 2026-09 起单一 app-server 形态即缺省路径（无模式钉扎 env）；更深断言（schema/
-  // abort/进程锚定）由 engines/zcode/__tests__/zcode-engine.live.test.ts 承载。
   it("zcode：app-server 常驻通道 run 全链（C2 outcome 无 error + C3 stream 事件不变量）", async (testCtx) => {
     const model = process.env["ZCODE_E2E_MODEL"];
     if (model === undefined || model === "") {
@@ -96,12 +140,11 @@ describe.skipIf(!LIVE)("conformance run 层（真实 spawn，手动门）", () =
 
 // ── relay 变体（E 方案 §2.3：同一契约 × 不同 spawn 通道，手动门内的手动门）──
 //
-// 前置：①ENGINE_CONFORMANCE_LIVE=1（套件级门）；②SubagentService 已装配（真实会话
-// 进程内跑——vitest 裸进程恒 null → skip 说明，与上方 pi live 用例同形态）；③真实模型
-// 凭据（最小任务由 LLM 完成）。relay 三 env 由测试自构（socket 指向测试内伪 runtime，
-// 执行器 = 本进程 node，脚本 = 包根 relay/relay.mjs），不依赖外部注入。
+// W10 协议化：relay env 由引擎 CLI 子进程消费（pi 包 spawn-runner 的 relay ctx
+// rewrite）；本变体经 EngineClient baseEnv 注入 relay 三 env + 测试内伪 runtime，
+// 断言 C2/C3 经代理转发的全等。前置：ENGINE_CONFORMANCE_LIVE=1 + PI_LIVE_MODEL。
 
-describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手动门）", () => {
+describe.skipIf(!LIVE)("conformance relay 变体（协议客户端 × relay 代理 spawn，手动门）", () => {
   /** 伪 runtime：按 E-2 协议扮演 runtime 侧——握手 accept + spawn 真实 pi + 双向转发 + exit 传播。 */
   function startFakeRuntime(socketPath: string): Promise<net.Server> {
     return new Promise((resolve, reject) => {
@@ -126,7 +169,10 @@ describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手
             //（对齐 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 });
+            // 直连 spawn 真实 pi：不用 getPiInvocation——本进程是 vitest worker，
+            // argv[1] 是 vitest 自身脚本，分支 1 会镜像出「node <vitest> <pi args>」
+            // 的错误启动。与引擎 CLI 的分支 3 同语义：PATH 解析 pi。
+            const invocation = { command: "pi", args: argv };
             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];
@@ -140,6 +186,7 @@ describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手
               send({ v: RELAY_PROTOCOL_VERSION, kind: "data", dir: "up", b64: c.toString("base64") });
             });
             pi.stderr?.on("data", (c: Buffer) => {
+              if (process.env["RELAY_DEBUG_STDERR"] === "1") console.error("[fake-runtime pi stderr]", c.toString());
               send({ v: RELAY_PROTOCOL_VERSION, kind: "data", dir: "up-stderr", b64: c.toString("base64") });
             });
             pi.on("close", (code, signal) => {
@@ -172,37 +219,56 @@ describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手
   }
 
   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 人工验收承载",
-      );
+    const model = process.env["PI_LIVE_MODEL"];
+    if (model === undefined || model === "") {
+      testCtx.skip("PI_LIVE_MODEL 未设置（relay 变体与直连 live 用例共享凭据前置）");
       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 as unknown as PiEngineService);
+      // relay 三键注入的是引擎子进程 baseEnv（不是测试进程自身的 process.env）——
+      // 激活校验对 baseEnv 做（曾误查 process.env 恒 false，前置断言自爆）。
+      const relayBaseEnv: NodeJS.ProcessEnv = {
+        ...process.env,
+        [RELAY_ENV_SOCKET]: socketPath,
+        [RELAY_ENV_NODE]: process.execPath,
+        // relay.mjs 权威源在 subagent-workflow 扩展包内（runtime 经 staged 布局消费，
+        // bundle-extensions.mjs 拷到 electron resources——测试直连源文件）。曾错指
+        // subagent-core/src/relay/relay.mjs（不存在）→ relay 子进程即退 code 1。
+        [RELAY_ENV_SCRIPT]: path.resolve(
+          path.dirname(fileURLToPath(import.meta.url)),
+          "../../../../../../../extensions/universal/subagent-workflow/relay/relay.mjs",
+        ),
+      };
+      if (!isRelayActive(relayBaseEnv)) {
+        throw new Error("relay env 自构后仍不激活——前置断言失败");
+      }
+      const client = new EngineClient({
+        engineId: "pi",
+        command: process.execPath,
+        args: [PI_CLI_ENTRY, "--no-extensions"],
+        hostKind: "test",
+        hostVersion: "w10-live-relay",
+        dataDir: tmpDir,
+        envPrefixes: [],
+        baseEnv: relayBaseEnv,
+        // 归属身份（L0 identityEnv 通道）：协议 v1 ctx 无 sessionRootId 字段，引擎侧
+        // buildChildEnv 缺省回落 PI_SUBAGENT_ROOT_SESSION_ID——伪 runtime 场景由测试
+        // 显式提供（模拟宿主注入根 session 身份）。
+        identityEnv: { PI_SUBAGENT_ROOT_SESSION_ID: "sess-w10-live-relay-probe" },
+      });
+      const engine = new RemoteEngine({
+        engineId: "pi",
+        client,
+        manifest: { capabilities: PI_LIVE_CAPABILITIES },
+        dataDir: tmpDir,
+        hostKind: "test",
+      });
       const events: AgentEvent[] = [];
-      const task: AgentCallOpts = { prompt: "Reply with the single word: ok", description: "live-relay-c2" };
+      const task = { prompt: "Reply with the single word: ok", description: "live-relay-c2", model, cwd: os.tmpdir() };
       const ctx: RunContext = {
         taskId: "sa-live-pi-relay",
         poolKey: "shared",
@@ -213,13 +279,10 @@ describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手
       expect(outcome.error).toBeUndefined();
       expect(outcome.content.trim().length).toBeGreaterThan(0);
       expect(outcome.engineId).toBe("pi");
-      // C3：事件不变量五条对「经代理转发的子进程 stdout」逐一成立（同一 parser 消费同一字节流）
+      // C3：事件不变量五条对「经代理转发的子进程 stdout」逐一成立
       assertAgentEventInvariants(events, { granularity: "stream", content: outcome.content });
+      await engine.dispose();
     } 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, maxRetries: 5, retryDelay: 20 });
     }

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

@@ -0,0 +1,143 @@
+// engine-crash.test.ts —— [W6/D5 前置闸] 引擎进程中途被 SIGTERM → run 终态 failed
+// + 原因含信号信息（协议黑盒：真 kill 信号路径）。
+//
+// 设计权威源：chat-domain-v1x-liveness-governance.md §3.2 D5（消亡处置顺序约束）+
+// §4 P2 探针 + 验收 A2/G3。D5 顺序约束：本用例必须先于 W3 删 `inproc pi 引擎目录/
+// session-runner.ts`（旧 143 误分类器：被信号终止一律归 success=true——事故环 3
+// 「死亡误报 completed」的根因载体）存在并保持绿——它把新路径语义钉成契约：
+//
+//   引擎进程被外部信号终止（SIGTERM）→ 在途 run 终态 **failed**（EngineSdkError
+//   engine_crashed，message = "…exited unexpectedly: signal SIGTERM…" + stderr 尾
+//   400 字符）→ core 上层（subagent-service adoptResumableAfterEngineDeath，W4）
+//   据此走「failed 如实 + record 保持 resumable + 监督器接管」，禁 completed 谎报。
+//
+// 对照既有语义：
+//   - 引擎侧：`pi-subagent-cli/src/spawn-runner.ts`「signal 退出 = 异常路径」
+//     （agent_end 干净终结主动 kill 的 close 带信号但语义是成功，143 只属异常）——
+//     W2 包内测试已承载；本用例钉宿主侧（协议客户端）对信号死亡的投影语义；
+//   - 宿主侧 crash 域既有覆盖（W2 client 套件）：fake 引擎自行 exit（code 137 /
+//     crash 模式）走 `exit code N` 分支；本用例覆盖 **signal 分支**
+//     （`onEngineExit(null, "SIGTERM")` → detail = `signal SIGTERM`）——外部真实
+//     信号（事故形态：宿主 infra 连带击杀）是 W2 套件未触达的形态；
+//   - engine_crashed 错误规格：stderr 内存环形缓冲尾 400 字符（STDERR_TAIL_CHARS，
+//     SDK 权威）随 message 携带——用「头标记被截断 + 尾标记保留」的窗口行为断言
+//     钉死（不 import 常量复述值）。
+//
+// 与监督器的链路衔接（表 3 行 1 全链）见 round-liveness-supervisor.test.ts 场景一。
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { EngineClient } from "../../client/engine-client.ts";
+
+const FIXTURE_DIR = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__", "engine-protocol");
+const FAKE_ENGINE = join(FIXTURE_DIR, "fake-engine-protocol.mjs");
+const FIXTURE = join(FIXTURE_DIR, "smoke-run.fixture.json");
+
+/**
+ * stderr 样本（>400 字符）：头标记落 400 尾窗外（必被截断）、尾标记落窗内
+ * （必保留）——stderr 尾窗行为的自证断言材料。
+ */
+const STDERR_SAMPLE =
+  "HEAD-OF-STDERR-SAMPLE|" + "x".repeat(400) + "|TAIL-OF-STDERR-SAMPLE";
+
+let dataDir: string;
+let pidFile: string;
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), "w6-engine-crash-"));
+  pidFile = join(dataDir, "fake-engine.pid");
+});
+
+afterEach(() => {
+  rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});
+
+function makeCrashHarness(): EngineClient {
+  return new EngineClient({
+    engineId: "fake",
+    command: process.execPath,
+    args: [FAKE_ENGINE],
+    hostKind: "test",
+    hostVersion: "w6-engine-crash",
+    dataDir,
+    envPrefixes: [],
+    baseEnv: {
+      ...process.env,
+      FAKE_PROTOCOL_FIXTURE: FIXTURE,
+      FAKE_PID_FILE: pidFile,
+      FAKE_RUN_STDERR_HANG: "1",
+      FAKE_STDERR_SAMPLE: STDERR_SAMPLE,
+    },
+  });
+}
+
+/** 轮询等待 fake 引擎 pid 落盘（FAKE_PID_FILE 锚）。 */
+async function waitForPidFile(): Promise<number> {
+  await expect.poll(() => existsSync(pidFile), { timeout: 5_000, interval: 20 }).toBe(true);
+  return Number(readFileSync(pidFile, "utf8").trim());
+}
+
+describe("[W6/D5 前置闸] 引擎进程被 SIGTERM → run 终态 failed（禁 completed 谎报）", () => {
+  it("run 中途真 kill SIGTERM → engine_crashed，原因含 signal SIGTERM + stderr 尾 400 窗行为", async () => {
+    if (process.platform === "win32") {
+      // Windows 无 POSIX 信号语义（process.kill(SIGTERM) 行为不等价）——信号死亡
+      // 形态挂真机门（A2 手动剧本杀引擎进程），本用例仅 POSIX。
+      return;
+    }
+    const client = makeCrashHarness();
+    try {
+      await client.ensureConnected();
+      expect(client.currentState).toBe("ready");
+
+      // run 挂起（FAKE_RUN_STDERR_HANG 注入：stderr 样本 → host/log 到达锚 → hang）
+      const runPromise = client.request("run", {
+        runId: "run-sigterm-1",
+        task: "w6 sigterm crash probe",
+        ctx: { poolKey: "shared", cwd: dataDir, model: "fake/fake-1" },
+      });
+
+      // 确定性同步锚 ①：fake 引擎 pid 落盘（进程已起）。
+      const pid = await waitForPidFile();
+      // 确定性同步锚 ②：stderr 样本已入 core 环形缓冲尾（先写后杀——事件竞争
+      // 面收窄为「已积累样本后 kill」，stderr 尾断言不靠 sleep 赌时序）。
+      await expect
+        .poll(() => client.stderrTailText.includes("TAIL-OF-STDERR-SAMPLE"), {
+          timeout: 5_000,
+          interval: 20,
+        })
+        .toBe(true);
+
+      // 事故形态复现：外部直接 SIGTERM 引擎进程（宿主 infra 连带击杀等价物）。
+      process.kill(pid, "SIGTERM");
+
+      // 钉死语义：run 终态 failed（engine_crashed）+ 原因含信号信息——
+      // 旧 143 误分类器（inproc session-runner（已删）:2667-2677，W3 删）的反命题：
+      // 信号死亡绝不允许投影为 success/completed。
+      const err = (await runPromise.catch((e: Error) => e)) as Error & {
+        code?: string;
+        data?: { stderrTail?: string };
+      };
+      expect(err).toMatchObject({
+        name: "EngineSdkError",
+        code: "engine_crashed",
+      });
+      expect(err.message).toContain("engine process exited unexpectedly: signal SIGTERM");
+      // engine_crashed 错误规格：stderr 尾 400 字符随 message——尾标记保留。
+      expect(err.message).toContain("TAIL-OF-STDERR-SAMPLE");
+      // 窗口行为自证：头标记（400 字符窗外）已被截断——「尾 400」非「全量」。
+      expect(err.message).not.toContain("HEAD-OF-STDERR-SAMPLE");
+      // 结构化 data.stderrTail 与 message 尾部同源（SDK engineCrashedError 契约）。
+      expect(err.data?.stderrTail).toContain("TAIL-OF-STDERR-SAMPLE");
+
+      // 死亡后状态：exited（非 unavailable——下次 run 走重建退避链，W2 套件已测）。
+      expect(client.currentState).toBe("exited");
+    } finally {
+      // 幂等收口：进程已死，dispose 不悬挂（killAll/dispose 对已死进程的空操作面）。
+      await expect(client.dispose()).resolves.toBeUndefined();
+    }
+  });
+});

package/src/execution/engine/__tests__/conformance/fake-engine-capabilities.ts

@@ -0,0 +1,19 @@
+// fake-engine-capabilities.ts —— fake 引擎的 capabilities 常量（与
+// __fixtures__/engine-protocol/smoke-run.fixture.json 的 initialize.result.capabilities
+// 同源；EngineClient 仅把它作 manifest 诊断比对源，不参与判据）。
+
+import type { EngineCapabilities } from "../../types.ts";
+
+export const FAKE_CAPABILITIES: EngineCapabilities = {
+  schemaEnforcement: "emulated",
+  steer: "unsupported",
+  conversation: "native",
+  personaInjection: "prompt",
+  eventGranularity: "stream",
+  sandbox: "none",
+  sessionRead: "full",
+  resume: "cold",
+  interrupt: "kill-only",
+  permissionMode: "ignored",
+  maxTurns: true,
+};