@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/execution/dialog-queue.ts

@@ -20,8 +20,70 @@
 //   直接调 handler（见 ui-request-handler-factory.ts），不经过本队列。enqueue 内仍防御性兼容
 //   fire-and-forget（万一调用方未判）：直接调 handler 返回，不入队串行。调用方不应依赖此防御。
 
+import { getLogger } from "../core/logger.ts";
+import { MAX_TIMER_DELAY_MS } from "../shared/timer-delay.ts";
+
 import { isDialogMethod } from "./ui-interaction-model.ts";
 
+const logger = getLogger("subagents");
+
+// ── dialog 超时上界（LC-3 / T2⑦，设计 docs/design/subagent-core-unbounded-wait-audit.md）──
+
+/** 分钟/秒/毫秒换算常数（与 lifecycle-manager.ts 同款命名）。 */
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+
+/** dialog 默认超时上界（30 分钟）：请求方未传 timeout 时的回收层兜底。
+ *
+ * 30 分钟是裁决值（产品语义：ask_user 挂起 30 分钟无响应视为放弃），不随 P-T2
+ * （keep-alive 分布，等后代）标定——那是无关总体。请求方需要更长等待时在协议
+ * request 上显式传 timeout（毫秒，pi ExtensionUIDialogOptions.timeout 同义）覆盖。
+ *
+ * 「等用户无限久」改为默认有界是有意的行为变更：LC-3 的两种形态（host UI promise
+ * 挂死 / 用户永不回答）原都会把 L2 processing 永久占死 → 所有子进程 ask_user 全局
+ * 死锁 + 该 child L1 队列 head-of-line 阻塞。 */
+const DEFAULT_DIALOG_TIMEOUT_MINUTES = 30;
+export const DEFAULT_DIALOG_TIMEOUT_MS =
+  DEFAULT_DIALOG_TIMEOUT_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+/**
+ * 解析一个 dialog 项的队列级上界：请求方传了合法正数 timeout 用之，否则挂默认上界。
+ * 非法值（<=0 / NaN / ±Infinity）回落默认——不因脏参数把上界拆掉（拆掉即回到 LC-3 无界）。
+ *
+ * 这里 clamp 到 MAX_TIMER_DELAY_MS 而非 fail-fast（timer-delay.ts 的 assertSafeTimerDelay
+ * 惯例是配置入口 fail-fast）：timeout 是 per-request 运行时传值，fail-fast 会把整个
+ * dialog 处理路径炸成 cancelled（伤害正常请求）；超大 timeout 的调用方意图是「近乎不限时」，
+ * clamp 到 2^31-1（约 24.8 天）是该意图在 setTimeout 域内的安全语义近似——不 clamp 会被
+ * Node 塌缩为 1ms 立即触发（语义反转：刚入队就超时）。
+ */
+function resolveDialogTimeoutMs(timeout: number | undefined): number {
+  const resolved = isValidDialogTimeout(timeout) ? timeout : DEFAULT_DIALOG_TIMEOUT_MS;
+  return Math.min(resolved, MAX_TIMER_DELAY_MS);
+}
+
+/**
+ * dialog req.timeout 合法域判定（单一权威源，A2-3）：合法正数（finite 且 > 0）才参与
+ * 超时语义——队列层据此决定上界取值（非法回落 DEFAULT_DIALOG_TIMEOUT_MS），
+ * factory 层据此决定是否透传 SDK 第三参（非法不透传，数组为空，由队列层默认上界兜底）。
+ * 两处共用本函数，禁止各写一份判定（此前两处不一致：SDK 层把 0/负数/NaN 原样透传，
+ * 队列层判非法回落默认）。
+ */
+export function isValidDialogTimeout(timeout: number | undefined): timeout is number {
+  return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0;
+}
+
+/** 超时 settle 的日志消息（恢复指引 + 已等待时长，父进程日志是完整错误消息的承载面——
+ * pi 协议 RpcExtensionUIResponse 是封闭联合（value/confirmed/cancelled），错误文本
+ * 无法进 stdin 响应体，子 agent 侧收到的是 cancelled 语义）。 */
+function dialogTimeoutLogMessage(req: UiRequest, waitedMs: number): string {
+  return (
+    `[subagents] dialog timed out after ${waitedMs}ms without response ` +
+    `(id=${req.id}, method=${req.method}) — settled as cancelled. ` +
+    "Recovery: the requesting agent can continue and re-issue the question (重新发起提问); " +
+    "to wait longer, pass an explicit timeout (ms) on the request."
+  );
+}
+
 // ── 类型定义（本模块是 UiRequest/UiResponse/UiRequestHandler 的规范来源） ──
 // session-runner.ts 和 ui-channels.ts 复用这些类型（session-runner 再导出供测试 import）。
 
@@ -118,6 +180,11 @@ interface QueueItem {
   childPid: number | undefined;
   /** 是否已 settle（防 handler 完成 / rejectChildDialogs 重复 resolve）。 */
   settled: boolean;
+  /** 队列级超时 timer 句柄（processNext 使 item 成为 current 时挂上）。
+   *  settleItem 统一 clearTimeout——handler 永挂时 processNext 的 await 永不 resume，
+   *  其内联 clearTimeout 不可达，reject/rejectAll 抢先 settle 的路径只能靠这里清理
+   *  （A2-2：否则 timer armed 到期触发虚假「dialog timed out」warn + 句柄滞留）。 */
+  timeoutTimer?: ReturnType<typeof setTimeout>;
 }
 
 /**
@@ -137,6 +204,10 @@ interface QueueItem {
  *   - FIFO 串行：前一个 handler settle 后才处理下一个
  *   - SR-4：rejectChildDialogs(child) 把该 child 的 pending 全部 resolve 为 {cancelled:true}
  *   - handler 抛错兜底：catch → {cancelled:true} → 继续下一个（队列不卡死）
+ *   - 超时上界（LC-3/T2⑦）：每个 dialog 项必有上界——req.timeout 显式传值优先，
+ *     未传挂 DEFAULT_DIALOG_TIMEOUT_MS（30min，裁决值）；到点 settle {cancelled:true}
+ *     并 warn（恢复指引见 dialogTimeoutLogMessage），L2 processing 释放、队列继续推进。
+ *     「等用户无限久」改为默认有界是有意的行为变更。
  *   - 调用方约定只对 dialog 类调 enqueue；fire-and-forget 由调用方直接调 handler 不入队
  *（enqueue 内仍防御性兼容 fire-and-forget，但不保证行为）
  *
@@ -201,18 +272,26 @@ export class DialogGlobalQueue {
   }
 
   /**
-   * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll 都通过本方法，
-   * settled 标志保证只 settle 一次（防竞争）。
+   * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll / 超时 timer
+   * 都通过本方法，settled 标志保证只 settle 一次（防竞争）。
    *
    * #19 单一推进点：本方法 settle Promise + 清状态后，**唯一**调 processNext 推进队列。
    * processNext 尾部不再调 processNext（旧代码双重推进，虽靠 processing 标志幂等，但语义混乱）。
    * 为什么推进必须在 settleItem 而非 processNext 尾部：rejectChildDialogs 取消一个永不 settle
    * 的 current（handler 等用户输入卡死）时，processNext 的 `await item.handler` 永不 resume，
    * 尾部不会执行；只有 settleItem 里的 processNext 才能打破死锁，推进下一个。
+   *
+   * [A2-2] 超时 timer 清理也统一收口在这里：任何路径抢先 settle（reject/rejectAll/超时
+   * 自身）都必须撤下 armed timer——handler 永挂时 processNext 内联的 clearTimeout 不可达，
+   * 不在这里清则 timer 到期触发虚假「dialog timed out」warn 且句柄滞留至超时点。
    */
   private settleItem(item: QueueItem, resp: UiResponse): void {
     if (item.settled) return;
     item.settled = true;
+    if (item.timeoutTimer) {
+      clearTimeout(item.timeoutTimer);
+      item.timeoutTimer = undefined;
+    }
     item.resolve(resp);
     // 若是正在处理的项，清空 current/processing 并推进队列（唯一推进点）。
     // 非当前项（队列中被 reject）只 settle Promise，不影响 current/推进。
@@ -263,6 +342,14 @@ export class DialogGlobalQueue {
    *
    * handler 抛错兜底（TC-E4 case 3）：catch → settle {cancelled:true} → 继续。
    * 不能让一个失败卡死队列（processing 永远 true）。
+   *
+   * LC-3/T2⑦ 超时上界：`await item.handler` 原本无上界——host UI promise 挂死或用户
+   * 永不回答时 processing 恒 true（全局 dialog 死锁）。现在每项挂队列级 timer：
+   * req.timeout（请求方显式传值）优先，未传/非法挂 DEFAULT_DIALOG_TIMEOUT_MS。
+   * 到点 settle {cancelled:true}（完整错误消息落父进程日志，含恢复指引与等待时长），
+   * settleItem 的 settled 标志保证与 handler 完成 / rejectChildDialogs 三方竞态下
+   * 恰 settle 一次。timer 回调闭包捕获 item（非读 this.current）：迟到触发时
+   * settled 标志已置位，直接 noop，不误伤后继项。
    */
   private async processNext(): Promise<void> {
     if (this.processing) return;
@@ -270,12 +357,23 @@ export class DialogGlobalQueue {
     this.processing = true;
     const item = this.queue.shift()!;
     this.current = item;
+    const timeoutMs = resolveDialogTimeoutMs(item.req.timeout);
+    const timer = setTimeout(() => {
+      // [A2-2] 已被抢先 settle（正常 settle 时 timer 已被 settleItem 清除，这里是防御性
+      // 兜底）：静默返回，不发虚假「dialog timed out」warn、不重复 settle。
+      if (item.settled) return;
+      logger.warn(dialogTimeoutLogMessage(item.req, timeoutMs));
+      this.settleItem(item, { cancelled: true });
+    }, timeoutMs);
+    item.timeoutTimer = timer;
     try {
       const resp = await item.handler(item.req);
-      // handler 完成：settle（若已被 rejectChildDialogs 抢先 settle 则 noop）。
+      clearTimeout(timer);
+      // handler 完成：settle（若已被超时 timer / rejectChildDialogs 抢先 settle 则 noop）。
       // settleItem 内会清 current/processing 并推进队列（#19 单一推进点）。
       this.settleItem(item, resp);
     } catch {
+      clearTimeout(timer);
       // handler 抛错兜底：回 cancelled，不向上抛（队列不能卡死）
       this.settleItem(item, { cancelled: true });
     }

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

@@ -1,6 +1,12 @@
 // contract.abort.test.ts —— conformance C4（abort 行为）：运行中 cancel → 宿主合成
 // 终态（exitCode=null）、无悬挂 promise（run 正常 resolve、exited 收口）、错误事件
 // 先于终态 emit（不变量 5 的事件面）。fake launcher 注入（不依赖真机）。
+//
+// [R6] 双模式口径：spawn 钉扎用例（deps.launch 驱动——launch 是 spawn 路径专属 dep，
+// 钉 XYZ_ZCODE_MODE=spawn 使 fixture 生效，必要性核验成立）+ app-server 常驻用例
+// （fake-appserver.mjs 挂起场景，stop 链优先于杀链——D3）。两形态各自覆盖：
+// capabilities.interrupt 维持 kill-only 声明（D5——改链路先于改声明，stop 链路经
+// conformance 真机验证后再评估升 native）。
 
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
@@ -8,12 +14,13 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { PassThrough } from "node:stream";
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { RunContext } from "../../port.ts";
 import type { AgentEvent, AgentTaskSpec } from "../../types.ts";
 import { ZcodeEngine, type ZcodeEngineDeps } from "../../engines/zcode/zcode-engine.ts";
 import type { ZcodeLaunchedProcess } from "../../engines/zcode/launcher.ts";
+import { makeAppserverHarness, sentMethodNames } from "./zcode-appserver-harness.ts";
 
 const PROVIDER = "provider-x";
 
@@ -79,7 +86,7 @@ describe("conformance C4：abort 行为（运行中 cancel → 合成终态、
     const engine = new ZcodeEngine({
       engineDataDir: () => dataDir,
       sources: { v2ConfigPath: v2Path },
-      processEnv: { PATH: "/usr/bin" },
+      processEnv: { PATH: "/usr/bin", XYZ_ZCODE_MODE: "spawn" },
       launch: fake.launch,
     });
 
@@ -106,4 +113,44 @@ describe("conformance C4：abort 行为（运行中 cancel → 合成终态、
     expect(fake.proc()?.killedByUs()).toBe(true);
     expect(handle.data.engineId).toBe("zcode");
   }, 15_000);
+
+  // [R6] app-server 常驻形态：abort 走 D3 链（stop → grace → killChain）。挂起场景
+  // （只推 state.updated，turn 永不落定）+ stopBehavior 缺省 terminal = stop 优雅
+  // 生效路径——不杀共享进程，run 正常 resolve（C4 的常驻通道面）。
+  it("app-server 模式：abort → stop 帧先发 → 优雅收口（run resolve、exitCode=null、error 事件先于终态、kill-only 声明维持）", async () => {
+    const h = makeAppserverHarness({ hangOnly: true });
+    try {
+      // capabilities.interrupt 维持 kill-only（D5——升级序里 interrupt 不动）
+      expect(h.engine.capabilities().interrupt).toBe("kill-only");
+
+      const controller = new AbortController();
+      const events: AgentEvent[] = [];
+      const runP = h.engine.run(
+        { task: "hang", slug: "abort-appserver", model: "conformance-provider/m1", cwd: h.workspace },
+        { taskId: "sa-c4-appserver", poolKey: "", signal: controller.signal, onEvent: (e) => events.push(e) },
+      );
+      // 推进到 send 已达（create+send 帧落 fake 流水）再 abort——abort 先于 create 会
+      // 走 pre-aborted 短路面，覆盖不到 stop 链
+      await vi.waitFor(
+        () => expect(sentMethodNames(h.stateFile)).toContain("session/send"),
+        { timeout: 5_000 },
+      );
+      controller.abort();
+      const { outcome } = await runP; // 必须正常 resolve（stop 优雅收口，不悬挂）
+
+      expect(outcome.exitCode).toBeNull();
+      expect(outcome.error).toContain("session/stop");
+      // 错误事件先于终态 emit（不变量 5 的事件面——journal 可重放出失败事实）。abort
+      // 终态不合成 turn_end（与 spawn 钉扎用例同语义：只断言 error 事件到达，且其后
+      // 无任何非 error 事件流出）
+      const errorIdx = events.findIndex((e) => e.type === "error");
+      expect(errorIdx).toBeGreaterThanOrEqual(0);
+      expect(events.slice(errorIdx + 1).every((e) => e.type === "error")).toBe(true);
+      // D3 序：stop 帧先于任何杀链动作（优雅路径下进程未被杀）
+      const methods = sentMethodNames(h.stateFile);
+      expect(methods.indexOf("session/stop")).toBeGreaterThan(methods.indexOf("session/send"));
+    } finally {
+      await h.dispose();
+    }
+  }, 20_000);
 });

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

@@ -2,12 +2,23 @@
 // （A12「套件有牙」：故意破坏一个不变量的样本必须被断言器检出——用「注入坏
 // parser」的形态：wrap 真实 synthesizeCoarseEvents 抽掉 message_end，断言套件转红；
 // 若断言器检不出破坏则本元测试失败）。
+//
+// [R6] 双模式口径：zcode 引擎 conformance 覆盖两种通道形态——spawn 钉扎（golden
+// stdout 语料 + coarse 合成，下方原有用例）与 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 { ZCODE_APPSERVER_GOLDEN, ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
+import { ZCODE_APPSERVER_POOL_KEY } from "../../engines/zcode/constants.ts";
 import { parseZcodeTerminal, synthesizeCoarseEvents } from "../../engines/zcode/parser.ts";
+import {
+  goldenReadFullText,
+  makeAppserverHarness,
+} from "./zcode-appserver-harness.ts";
 import {
   assertAgentEventInvariants,
   checkAgentEventInvariants,
@@ -99,3 +110,78 @@ describe("conformance 负例自证（A12：套件有牙）", () => {
     expect(findings.some((f) => f.invariant === "2")).toBe(true);
   });
 });
+
+// ============================================================
+// [R6] C3 app-server 口径：fake 常驻引擎全链（eventGranularity=stream 形态）
+// —— spawn 钉扎用例见上方 coarse describe，两形态各自覆盖不合并（D2 降级链保留
+// 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(
+        { task: "做点什么", slug: "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(
+        { task: "做点什么", slug: "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 锚定常驻 HOME（poolKey=home-appserver，①级读取钥匙随 handle 走）", async () => {
+    const h = makeAppserverHarness();
+    try {
+      const { handle, outcome } = await h.engine.run(
+        { task: "做点什么", slug: "c3-anchor", model: "conformance-provider/m1", cwd: h.workspace },
+        { taskId: "sa-c3-anchor", poolKey: "" },
+      );
+      expect(handle.data.poolKey).toBe(ZCODE_APPSERVER_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

@@ -66,6 +66,32 @@ 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 面）：
+  // XYZ_ZCODE_MODE=appserver 定向（不探不降）跑最小任务——C2 outcome + C3 stream
+  // 不变量（app-server 设计 §3.4 不变量 1）。更深断言（schema/abort/进程锚定）由
+  // engines/zcode/__tests__/zcode-engine.live.test.ts 的 [R6] app-server 段承载。
+  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",
+      processEnv: { ...process.env, XYZ_ZCODE_MODE: "appserver" },
+    });
+    const events: AgentEvent[] = [];
+    const { outcome } = await engine.run(
+      { task: "Reply with the single word: ok", slug: "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 通道，手动门内的手动门）──

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

@@ -3,6 +3,11 @@
 // zcode-golden-spawn.json 的 stdoutRaw）——parser 对实录样本回归 + coarse 事件合成
 // 不变量断言 + 双副本 diff 校验（fixture 与 golden-sample.ts 内嵌副本一致，防漂移：
 // 更新样本必须同步两处，探针的干跑校验消费内嵌副本，两处不一致 = 探针在测旧契约）。
+//
+// [R6] 双语料并存：① spawn stdout（上方，spawn 降级路径 + probe 干跑的回归语料——
+// 生产消费方存在故保留，去留决策见 impl-plan R6 偏差登记）② app-server 帧序列
+// （下方新增，常驻通道主力语料——双副本 diff 自 session-channel 测试接管到 conformance
+// 回放层，帧形态不变量在此断言；A8「golden 帧序列语料 diff 通过」的本仓段）。
 
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -10,7 +15,7 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it } from "vitest";
 
-import { ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
+import { ZCODE_APPSERVER_GOLDEN, ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
 import {
   mapZcodeOutcomeUsage,
   parseZcodeTerminal,
@@ -32,6 +37,14 @@ interface ZcodeGoldenFile {
 
 const fixture = JSON.parse(readFileSync(fixturePath, "utf8")) as ZcodeGoldenFile;
 
+// [R6] app-server 帧序列语料 fixture（采集 SSOT——双副本 diff 的另一副本）
+const appserverFixturePath = join(dirname(fixturePath), "zcode-golden-appserver.json");
+interface AppServerGoldenFile {
+  _meta: Record<string, unknown>;
+  frames: { createResponse: string; pushStream: string[]; terminal: string[]; readResponse: string };
+}
+const appserverFixture = JSON.parse(readFileSync(appserverFixturePath, "utf8")) as AppServerGoldenFile;
+
 describe("zcode golden 回放（conformance C3，免 LLM/免二进制）", () => {
   it("双副本 diff：golden-sample.ts 内嵌副本 === fixture stdoutRaw（防漂移，A12）", () => {
     expect(ZCODE_GOLDEN_STDOUT).toBe(fixture.stdoutRaw);
@@ -77,3 +90,72 @@ describe("zcode golden 回放（conformance C3，免 LLM/免二进制）", () =>
     });
   });
 });
+
+// ============================================================
+// [R6] app-server 帧序列语料回放（常驻通道主力语料，conformance 层接管双副本 diff）
+// ============================================================
+
+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);
+  });
+
+  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("推送流帧形态：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);
+
+    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("终态权威帧：turn.terminal 存在且先于收尾帧；usage 与 spawn golden 同值（漂移对照锚点）", () => {
+    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);
+
+    const spawnUsage = parseZcodeTerminal(ZCODE_GOLDEN_STDOUT);
+    if (!spawnUsage.ok) throw new Error("spawn golden 样本解析失败");
+    expect(terminal[closingFrameIdx]?.params?.payload?.usage).toEqual({
+      inputTokens: spawnUsage.payload.usage.input,
+      outputTokens: spawnUsage.payload.usage.output,
+    });
+  });
+});

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

@@ -0,0 +1,131 @@
+// 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 的常驻引擎（XYZ_ZCODE_MODE=appserver 定向——不探不降）。 */
+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 ?? "",
+      // 定向 appserver（R5 D2①）：不探不降——conformance 测常驻路径本体，缺省路径的
+      // 探针门控/降级链归 zcode-engine-degrade.test.ts
+      XYZ_ZCODE_MODE: "appserver",
+      FAKE_STATE_FILE: stateFile,
+      FAKE_SESSION_SCENARIO: scenarioFile,
+    },
+  });
+  return {
+    engine,
+    stateFile,
+    workspace,
+    dataDir,
+    dispose: () =>
+      engine.dispose().finally(() => {
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+      }),
+  };
+}
+
+/** 读 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["frame"])
+    .filter((f): f is Record<string, unknown> => typeof f === "object" && f !== null && typeof f["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("");
+}