@zhushanwen/subagent-core 0.2.0 → 0.5.1

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

@@ -1,30 +1,29 @@
 // contract.agent-events.test.ts —— conformance C3（AgentEvent 不变量）+ 负例自证
 // （A12「套件有牙」：故意破坏一个不变量的样本必须被断言器检出——用「注入坏
-// parser」的形态：wrap 真实 synthesizeCoarseEvents 抽掉 message_end，断言套件转红；
+// parser」的形态：构造抽掉 message_end / usage 半映射的坏样本流，断言套件转红；
 // 若断言器检不出破坏则本元测试失败）。
+//
+// 2026-09 重构（共享宿主 HOME）：CLI spawn 链删除后引擎只剩 app-server 常驻链，
+// C3 的引擎全链覆盖只走 app-server 形态（fake 常驻引擎 + stream 口径，文件末
+// describe；app-server 设计 §3.4 不变量 1：text_delta 拼接 == read 全文、终态唯一
+// turn.terminal 权威、message_end.usage 完整、tool 事件不合成——granularity 声明
+// 与实际流出一致）。断言器行为正反例与负例自证均为手工构造样本，不依赖引擎实现。
 
 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 { ZCODE_APPSERVER_GOLDEN } from "../../engines/zcode/golden-sample.ts";
+import { ZCODE_SHARED_POOL_KEY } from "../../engines/zcode/constants.ts";
+import {
+  goldenReadFullText,
+  makeAppserverHarness,
+} from "./zcode-appserver-harness.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" });
-  });
-
+describe("conformance C3：AgentEvent 不变量（断言器正反例，手工构造样本）", () => {
   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" });
@@ -99,3 +98,77 @@ describe("conformance 负例自证（A12：套件有牙）", () => {
     expect(findings.some((f) => f.invariant === "2")).toBe(true);
   });
 });
+
+// ============================================================
+// [R6] C3 app-server 口径：fake 常驻引擎全链（eventGranularity=stream 形态）
+// —— 2026-09 重构后唯一生产形态（CLI spawn 降级链已删，无钉扎/降级双通道）。
+// ============================================================
+
+describe("conformance C3：zcode app-server 常驻通道（stream 口径，fake 常驻全链）", () => {
+  it("text_delta 拼接 == read 全文（byte 级）+ 终态唯一 + message_end.usage 完整 + tool 事件不合成", async () => {
+    const h = makeAppserverHarness();
+    try {
+      const events: AgentEvent[] = [];
+      const { outcome } = await h.engine.run(
+        { prompt: "做点什么", description: "c3-appserver", model: "conformance-provider/m1", cwd: h.workspace },
+        { taskId: "sa-c3-appserver", poolKey: "", onEvent: (e) => events.push(e) },
+      );
+
+      // granularity 声明与实际流出一致：声明 stream，流出有 text_delta 实时形态
+      expect(h.engine.capabilities().eventGranularity).toBe("stream");
+      expect(events.some((e) => e.type === "text_delta")).toBe(true);
+
+      // 事件形态：三条 delta（golden pushStream）→ message_end(usage) → turn_end
+      expect(events.map((e) => e.type)).toEqual([
+        "text_delta", "text_delta", "text_delta", "message_end", "turn_end",
+      ]);
+      const messageEnd = events.find((e) => e.type === "message_end") as
+        | { usage?: { input: number; output: number; cacheRead: number; cacheWrite: number } }
+        | undefined;
+      expect(messageEnd?.usage).toEqual({ input: 12599, output: 17, cacheRead: 0, cacheWrite: 0 });
+
+      // tool 事件不合成：首期无逐工具推送帧，流出面不伪造 tool_start/tool_end
+      // （granularity 声明与实际流出一致即合法——app-server 设计 §3.4 不变量 1）
+      expect(events.some((e) => e.type === "tool_start" || e.type === "tool_end")).toBe(false);
+
+      // 不变量五条（stream 口径）：3a 的 content 用 read 全文（终态权威来源）
+      const readFullText = goldenReadFullText();
+      assertAgentEventInvariants(events, { granularity: "stream", content: readFullText });
+      expect(outcome.content).toBe(readFullText);
+    } finally {
+      await h.dispose();
+    }
+  }, 20_000);
+
+  it("终态权威 turn.terminal 缺失 → read 兜底收口，事件不变量仍全绿（宽松匹配防洪堤不破坏 C3）", async () => {
+    const h = makeAppserverHarness({ dropTurnTerminal: true });
+    try {
+      const events: AgentEvent[] = [];
+      const { outcome } = await h.engine.run(
+        { prompt: "做点什么", description: "c3-no-terminal", model: "conformance-provider/m1", cwd: h.workspace },
+        { taskId: "sa-c3-no-terminal", poolKey: "", onEvent: (e) => events.push(e) },
+      );
+      expect(outcome.error).toBeUndefined();
+      // 缺 turn.terminal 时收尾帧 + read 兜底仍产出完整终态（session-channel 宽松匹配）
+      assertAgentEventInvariants(events, { granularity: "stream", content: goldenReadFullText() });
+    } finally {
+      await h.dispose();
+    }
+  }, 20_000);
+
+  it("handle 携带 shared poolKey（共享宿主 HOME 的 journal 分组锚点，①级读取钥匙随 handle 走）", async () => {
+    const h = makeAppserverHarness();
+    try {
+      const { handle, outcome } = await h.engine.run(
+        { prompt: "做点什么", description: "c3-anchor", model: "conformance-provider/m1", cwd: h.workspace },
+        { taskId: "sa-c3-anchor", poolKey: "" },
+      );
+      expect(handle.data.poolKey).toBe(ZCODE_SHARED_POOL_KEY);
+      expect(handle.data.sessionRef["sessionId"]).toBe(outcome.sessionId);
+      // golden 锚点：sessionId 来自 session.sessionId（projection.sessionId 恒 "unknown" 勿用）
+      expect(JSON.parse(ZCODE_APPSERVER_GOLDEN.createResponse).session.sessionId).toBe("sess_golden_r3_01");
+    } finally {
+      await h.dispose();
+    }
+  }, 20_000);
+});

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

@@ -25,10 +25,11 @@ 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 type { RunContext } from "../../port.ts";
 import type { AgentEvent } from "../../../types.ts";
-import type { AgentTaskSpec } from "../../types.ts";
-import { getPiInvocation } from "../../../pi-invocation.ts";
+import type { AgentCallOpts } from "../../../../orchestration/models/types.ts";
+import { getPiInvocation } from "../../engines/pi/pi-invocation.ts";
 import {
   RELAY_ENV_NODE,
   RELAY_ENV_RECORD_ID,
@@ -51,8 +52,8 @@ describe.skipIf(!LIVE)("conformance run 层（真实 spawn，手动门）", () =
       testCtx.skip("SubagentService 未装配（需在真实会话进程内运行）");
       return;
     }
-    const engine = createPiEngine(() => service);
-    const task: AgentTaskSpec = { task: "Reply with the single word: ok", slug: "live-c2" };
+    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();
@@ -66,6 +67,31 @@ describe.skipIf(!LIVE)("conformance run 层（真实 spawn，手动门）", () =
     expect(report.ok).toBe(true);
     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 === "") {
+      testCtx.skip("ZCODE_E2E_MODEL 未设置（需真实 provider/model 凭据）——appserver live run 面跳过");
+      return;
+    }
+    const engine = new ZcodeEngine({
+      engineDataDir: () => "/tmp/zcode-conformance-live-appserver",
+    });
+    const events: AgentEvent[] = [];
+    const { outcome } = await engine.run(
+      { prompt: "Reply with the single word: ok", description: "live-appserver-c2", model, cwd: "/tmp" },
+      { taskId: "sa-live-zcode-appserver", poolKey: "", onEvent: (e) => events.push(e) },
+    );
+    expect(outcome.error).toBeUndefined();
+    expect(outcome.content.trim().length).toBeGreaterThan(0);
+    expect(outcome.sessionId).toMatch(/^sess_/);
+    assertAgentEventInvariants(events, { granularity: "stream", content: outcome.content });
+    await engine.dispose().catch(() => undefined);
+  }, 180_000);
 });
 
 // ── relay 变体（E 方案 §2.3：同一契约 × 不同 spawn 通道，手动门内的手动门）──
@@ -174,9 +200,9 @@ describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手
     }
 
     try {
-      const engine = createPiEngine(() => service);
+      const engine = createPiEngine(() => service as unknown as PiEngineService);
       const events: AgentEvent[] = [];
-      const task: AgentTaskSpec = { task: "Reply with the single word: ok", slug: "live-relay-c2" };
+      const task: AgentCallOpts = { prompt: "Reply with the single word: ok", description: "live-relay-c2" };
       const ctx: RunContext = {
         taskId: "sa-live-pi-relay",
         poolKey: "shared",
@@ -195,7 +221,7 @@ describe.skipIf(!LIVE)("conformance relay 变体（经代理 spawn 全链，手
         else process.env[key] = savedEnv[key];
       }
       await new Promise<void>((resolve) => server.close(() => resolve()));
-      fs.rmSync(tmpDir, { recursive: true, force: true });
+      fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 });

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

@@ -15,7 +15,7 @@ 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 { parseSpawnLine } from "../../engines/pi/spawn-event-adapter.ts";
 import { assertAgentEventInvariants } from "./agent-event-invariants.ts";
 
 interface PiGoldenFile {

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

@@ -1,8 +1,13 @@
-// golden-replay.zcode.test.ts —— zcode 引擎 golden 回放层（conformance 免 LLM 默认 CI
-// 层）。数据源 = P3 验收前置门的真机实录（engines/zcode/__tests__/__fixtures__/
-// zcode-golden-spawn.json 的 stdoutRaw）——parser 对实录样本回归 + coarse 事件合成
-// 不变量断言 + 双副本 diff 校验（fixture 与 golden-sample.ts 内嵌副本一致，防漂移：
-// 更新样本必须同步两处，探针的干跑校验消费内嵌副本，两处不一致 = 探针在测旧契约）。
+// golden-replay.zcode.test.ts —— zcode 引擎 golden 回放层（conformance 免 LLM 默认
+// CI 层）。语料 = app-server NDJSON 帧序列（附录 A.2 任务生命周期帧序；采集 SSOT
+// = engines/zcode/__tests__/__fixtures__/zcode-golden-appserver.json）——双副本 diff
+// 校验（fixture 与 golden-sample.ts 内嵌副本一致，防漂移：更新样本必须同步两处，
+// 探针的干跑校验消费内嵌副本，两处不一致 = 探针在测旧契约）+ 帧形态不变量断言
+// （A8「golden 帧序列语料 diff 通过」的本仓段）。
+//
+// 2026-09 重构（共享宿主 HOME）：CLI spawn 链删除后 spawn stdout 语料（单 JSON
+// 样本及其 fixture）随 spawn 回归一并删除，本层仅保留 app-server 帧序列语料
+// （常驻通道唯一生产形态）。
 
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -10,70 +15,86 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it } from "vitest";
 
-import { ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
-import {
-  mapZcodeOutcomeUsage,
-  parseZcodeTerminal,
-  synthesizeCoarseEvents,
-} from "../../engines/zcode/parser.ts";
-import { assertAgentEventInvariants } from "./agent-event-invariants.ts";
+import { ZCODE_APPSERVER_GOLDEN } from "../../engines/zcode/golden-sample.ts";
 
 // conformance 目录（engine/__tests__/conformance）→ engine 根的相对定位
-const fixturePath = join(
+const appserverFixturePath = join(
   dirname(fileURLToPath(import.meta.url)),
   "..", "..", // conformance → __tests__ → engine
-  "engines", "zcode", "__tests__", "__fixtures__", "zcode-golden-spawn.json",
+  "engines", "zcode", "__tests__", "__fixtures__", "zcode-golden-appserver.json",
 );
 
-interface ZcodeGoldenFile {
-  _meta: { engineVersion: string; exitCode: number };
-  stdoutRaw: string;
+interface AppServerGoldenFile {
+  _meta: Record<string, unknown>;
+  frames: { createResponse: string; pushStream: string[]; terminal: string[]; readResponse: string };
 }
+const appserverFixture = JSON.parse(readFileSync(appserverFixturePath, "utf8")) as AppServerGoldenFile;
 
-const fixture = JSON.parse(readFileSync(fixturePath, "utf8")) as ZcodeGoldenFile;
+describe("zcode app-server golden 回放（conformance C3 帧形态，免 LLM/免二进制）", () => {
+  it("双副本 diff：golden-sample.ts 内嵌副本 === fixture frames（防漂移，A8 本仓段）", () => {
+    expect(ZCODE_APPSERVER_GOLDEN.createResponse).toBe(appserverFixture.frames.createResponse);
+    expect(ZCODE_APPSERVER_GOLDEN.pushStream).toEqual(appserverFixture.frames.pushStream);
+    expect(ZCODE_APPSERVER_GOLDEN.terminal).toEqual(appserverFixture.frames.terminal);
+    expect(ZCODE_APPSERVER_GOLDEN.readResponse).toBe(appserverFixture.frames.readResponse);
+  });
 
-describe("zcode golden 回放（conformance C3，免 LLM/免二进制）", () => {
-  it("双副本 diff：golden-sample.ts 内嵌副本 === fixture stdoutRaw（防漂移，A12）", () => {
-    expect(ZCODE_GOLDEN_STDOUT).toBe(fixture.stdoutRaw);
+  it("create 应答形状：权威 sessionId 在 session.sessionId（projection.sessionId 恒 unknown 勿用）", () => {
+    const create = JSON.parse(ZCODE_APPSERVER_GOLDEN.createResponse) as {
+      session: { sessionId: string };
+      projection: { sessionId: string };
+    };
+    expect(create.session.sessionId).toMatch(/^sess_/);
+    expect(create.projection.sessionId).toBe("unknown");
   });
 
-  it("parser 对实录样本回归：sessionId/response/usage 形状完整（探针干跑同源断言）", () => {
-    const terminal = parseZcodeTerminal(fixture.stdoutRaw);
-    expect(terminal.ok).toBe(true);
-    if (!terminal.ok) return;
-    expect(terminal.payload.sessionId).toMatch(/^sess_/);
-    expect(terminal.payload.response).toBe("ok");
-    expect(terminal.payload.usage).toEqual({ input: 12599, output: 17, cacheRead: 512, cacheWrite: 0 });
-    // 终态层 usage（orchestration 版）：cost 显式 0（无来源不给残缺）、contextTokens 取 projection
-    expect(terminal.payload.outcomeUsage).toEqual({
-      input: 12599,
-      output: 17,
-      cacheRead: 512,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 12616,
-      turns: 1,
+  it("推送流帧形态：stream.chunk 无文本（文本在 session/event delta）——文本三源恒等（A8 不变量 1）", () => {
+    const pushes = ZCODE_APPSERVER_GOLDEN.pushStream.map((l) => JSON.parse(l) as {
+      method: string;
+      params?: { kind?: string; payload?: { delta?: string } };
     });
-  });
+    const chunks = pushes.filter((f) => f.params?.kind === "stream.chunk");
+    expect(chunks.length).toBeGreaterThan(0);
+    for (const c of chunks) expect(c.params?.payload?.delta).toBeUndefined();
+
+    const deltaJoined = pushes
+      .filter((f) => f.method === "session/event" && typeof f.params?.payload?.delta === "string")
+      .map((f) => f.params?.payload?.delta)
+      .join("");
+    const terminal = ZCODE_APPSERVER_GOLDEN.terminal.map((l) => JSON.parse(l) as {
+      params?: { kind?: string; payload?: { response?: string; usage?: { inputTokens: number; outputTokens: number } } };
+    });
+    const closing = terminal.find((f) => f.params?.payload?.response !== undefined);
+    expect(closing?.params?.payload?.response).toBe(deltaJoined);
 
-  it("coarse 事件合成满足产出不变量（turn_end 最后、其前必有 message_end、usage 完整）", () => {
-    const terminal = parseZcodeTerminal(fixture.stdoutRaw);
-    if (!terminal.ok) throw new Error("golden 样本解析失败（上一用例应已转红）");
-    const events = synthesizeCoarseEvents(terminal.payload.response, terminal.payload.usage);
-    assertAgentEventInvariants(events, { granularity: "coarse" });
-    expect(events.map((e) => e.type)).toEqual(["message_end", "turn_end"]);
+    const read = JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse) as {
+      messages: Array<{ info: { role: string }; parts: Array<{ type: string; text?: string }> }>;
+    };
+    const readText = (read.messages.at(-1)?.parts ?? [])
+      .filter((p) => p.type === "text")
+      .map((p) => p.text ?? "")
+      .join("");
+    expect(readText).toBe(deltaJoined); // text_delta 拼接 == 收尾帧 == read 全文
   });
 
-  it("usage 无来源样本：mapZcodeOutcomeUsage 显式缺省（不给残缺对象，不变量 2 的输入面）", () => {
-    expect(mapZcodeOutcomeUsage(undefined, undefined)).toBeUndefined();
-    expect(mapZcodeOutcomeUsage({ inputTokens: 1 }, undefined)).toEqual({
-      input: 1,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 0,
-      turns: 1,
+  it("终态权威帧：turn.terminal 存在且先于收尾帧；usage 与 read step-finish tokens 同源（漂移对照锚点）", () => {
+    const terminal = ZCODE_APPSERVER_GOLDEN.terminal.map((l) => JSON.parse(l) as {
+      params?: { kind?: string; status?: string; payload?: { usage?: { inputTokens: number; outputTokens: number } } };
+    });
+    const terminalFrameIdx = terminal.findIndex((f) => f.params?.kind === "turn.terminal");
+    const closingFrameIdx = terminal.findIndex((f) => f.params?.payload?.usage !== undefined);
+    expect(terminalFrameIdx).toBeGreaterThanOrEqual(0);
+    expect(terminal[terminalFrameIdx]?.params?.status).toBe("success");
+    expect(terminalFrameIdx).toBeLessThan(closingFrameIdx);
+
+    // usage 跨源对照锚点：收尾帧 usage == read 应答 step-finish tokens（同一轮真实
+    // 计费面，两源必须一致；旧 spawn golden 对照随语料删除）
+    const read = JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse) as {
+      messages: Array<{ info: { role: string }; parts: Array<{ type: string; tokens?: { input: number; output: number } }> }>;
+    };
+    const stepFinish = (read.messages.at(-1)?.parts ?? []).find((p) => p.type === "step-finish");
+    expect(terminal[closingFrameIdx]?.params?.payload?.usage).toEqual({
+      inputTokens: stepFinish?.tokens?.input,
+      outputTokens: stepFinish?.tokens?.output,
     });
   });
 });

package/src/execution/engine/__tests__/conformance/zcode-appserver-harness.ts

@@ -0,0 +1,128 @@
+// zcode-appserver-harness.ts —— conformance 层的 fake app-server 引擎组装器（R6）。
+//
+// 与 engines/zcode/__tests__/zcode-engine-appserver.test.ts 的 makeEngine 同模式
+// （scenario 文件随 env 固化进 fake 子进程），抽出为 conformance 专用副本而非跨测试
+// 目录 import 测试文件——conformance 套件自包含（A12：套件不依赖被测引擎自己的
+// 单测文件结构）。协议/断言面同源：fake-appserver.mjs + ZCODE_APPSERVER_GOLDEN。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ZCODE_APPSERVER_GOLDEN } from "../../engines/zcode/golden-sample.ts";
+import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
+
+const FAKE_CLI = fileURLToPath(
+  new URL("../../engines/zcode/__tests__/__fixtures__/fake-appserver.mjs", import.meta.url),
+);
+const PROVIDER = "conformance-provider";
+
+export interface AppserverHarnessOptions {
+  /** 覆盖 send 推送帧（缺省 = golden pushStream + 终态两帧；dropTurnTerminal 置真时去 turn.terminal）。 */
+  dropTurnTerminal?: boolean;
+  /** 覆盖 read 应答（read 是全文权威来源）。 */
+  readResult?: unknown;
+  /** session/stop 行为（fake scenario.stopBehavior；缺省 'terminal' = stop 优雅生效）。 */
+  stopBehavior?: "terminal" | "none";
+  /** 只保留 state.updated（挂起场景——turn 永不自然落定，abort 用例用）。 */
+  hangOnly?: boolean;
+}
+
+export interface AppserverHarness {
+  engine: ZcodeEngine;
+  /** fake 子进程的事件流水文件（帧序断言数据源）。 */
+  stateFile: string;
+  workspace: string;
+  dataDir: string;
+  dispose(): Promise<void>;
+}
+
+/** 组装连到 fake-appserver 的常驻引擎（单一 app-server 形态——2026-09 起无模式分派）。 */
+export function makeAppserverHarness(opts: AppserverHarnessOptions = {}): AppserverHarness {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-conformance-appserver-"));
+  const dataDir = path.join(tmpRoot, "data");
+  const stateFile = path.join(tmpRoot, "state.jsonl");
+  const scenarioFile = path.join(tmpRoot, "scenario.json");
+  const workspace = path.join(tmpRoot, "ws");
+  const v2Path = path.join(tmpRoot, "v2.json");
+
+  fs.mkdirSync(path.dirname(v2Path), { recursive: true });
+  fs.writeFileSync(
+    v2Path,
+    JSON.stringify({
+      provider: { [PROVIDER]: { options: { apiKey: "k", baseURL: "https://t.example" }, models: { m1: {} } } },
+    }),
+  );
+
+  const pushes = opts.hangOnly
+    ? [ZCODE_APPSERVER_GOLDEN.pushStream[0]].map((l) => JSON.parse(l) as unknown)
+    : [
+        ...ZCODE_APPSERVER_GOLDEN.pushStream,
+        ...(opts.dropTurnTerminal ? [] : [ZCODE_APPSERVER_GOLDEN.terminal[0]]),
+        ZCODE_APPSERVER_GOLDEN.terminal[1],
+      ].map((l) => JSON.parse(l) as unknown);
+  fs.writeFileSync(
+    scenarioFile,
+    JSON.stringify({
+      createResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.createResponse),
+      readResult: opts.readResult ?? JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse),
+      sendPushes: pushes,
+      ...(opts.stopBehavior !== undefined ? { stopBehavior: opts.stopBehavior } : {}),
+    }),
+  );
+
+  const engine = new ZcodeEngine({
+    engineDataDir: () => dataDir,
+    cliPath: FAKE_CLI,
+    sources: { v2ConfigPath: v2Path },
+    processEnv: {
+      PATH: process.env.PATH ?? "",
+      FAKE_STATE_FILE: stateFile,
+      FAKE_SESSION_SCENARIO: scenarioFile,
+    },
+  });
+  return {
+    engine,
+    stateFile,
+    workspace,
+    dataDir,
+    dispose: () =>
+      engine.dispose().finally(() => {
+        fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+      }),
+  };
+}
+
+/** 读 fake 流水（帧序断言用）。 */
+export function readFakeState(file: string): Array<Record<string, unknown>> {
+  try {
+    return fs
+      .readFileSync(file, "utf8")
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as Record<string, unknown>);
+  } catch {
+    return [];
+  }
+}
+
+/** fake 收到的客户端帧方法名序列（abort 链「stop 先于杀链」断言面）。 */
+export function sentMethodNames(stateFile: string): string[] {
+  return readFakeState(stateFile)
+    .map((e) => (e as Record<string, unknown>)["frame"])
+    .filter((f): f is Record<string, unknown> => typeof f === "object" && f !== null && typeof (f as Record<string, unknown>)["method"] === "string")
+    .map((f) => f["method"] as string);
+}
+
+/** golden read 应答里 assistant 消息的 text parts 拼接（read 全文——不变量 3a 的比对基准）。 */
+export function goldenReadFullText(): string {
+  const read = JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse) as {
+    messages: Array<{ info: { role: string }; parts: Array<{ type: string; text?: string }> }>;
+  };
+  return (read.messages.at(-1)?.parts ?? [])
+    .filter((p) => p.type === "text")
+    .map((p) => p.text ?? "")
+    .join("");
+}

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

@@ -15,8 +15,20 @@ import { clearEngines, registerEngine } from "../registry.ts";
 function stubEngine(id: string): EnginePort {
   return {
     id,
-    capabilities: () => ({ conversation: "unsupported", steer: "unsupported", sandbox: "none" }),
-    probe: async () => ({ ok: true, engineVersion: "test" }),
+    capabilities: () => ({
+      schemaEnforcement: "emulated",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "unsupported",
+      interrupt: "kill-only",
+      permissionMode: "ignored",
+      maxTurns: false,
+    }),
+    probe: async () => ({ ok: true, engineVersion: "test", checks: [] }),
     run: async () => {
       throw new Error("unused");
     },
@@ -38,7 +50,7 @@ beforeEach(() => {
 
 afterEach(() => {
   clearEngines();
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 describe("syncEnginesFile", () => {

package/src/execution/engine/__tests__/model-prompt.test.ts

@@ -16,8 +16,20 @@ import { buildEngineModelsPromptAppend, buildSubagentEngineSection } from "../mo
 function fakeEngine(id: string, models: Array<{ id: string; name?: string }> | null): EnginePort {
   return {
     id,
-    capabilities: () => ({ conversation: "unsupported", steer: "unsupported", sandbox: "none" }),
-    probe: async () => ({ ok: true, engineVersion: "test" }),
+    capabilities: () => ({
+      schemaEnforcement: "emulated",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "unsupported",
+      interrupt: "kill-only",
+      permissionMode: "ignored",
+      maxTurns: false,
+    }),
+    probe: async () => ({ ok: true, engineVersion: "test", checks: [] }),
     run: async () => {
       throw new Error("not used in this test");
     },
@@ -38,7 +50,7 @@ beforeEach(() => {
 
 afterEach(() => {
   clearEngines();
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 describe("buildEngineModelsPromptAppend（defaultEngine 开关语义）", () => {