@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/execution/engine/__tests__/registry.test.ts

@@ -2,13 +2,15 @@
 //
 // registry 专属测试（P1 验收 4）：注册/获取/listEngines/hasEngine/
 // 未注册 id 报 engine_not_found（错误文案含已注册清单——错误规格表第 1 行契约）。
+// [R1 D6] 追加：重注册先 dispose 旧单例（D6②）+ disposeEngines 收割遍历（D6③）。
 
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { EnginePort, RunContext } from "../port.ts";
 import {
   clearEngines,
   DEFAULT_ENGINE_ID,
+  disposeEngines,
   EngineNotFoundError,
   getEngine,
   hasEngine,
@@ -117,4 +119,91 @@ describe("engine registry", () => {
   it("DEFAULT_ENGINE_ID 缺省为 'pi'（D9：回填期零风险默认）", () => {
     expect(DEFAULT_ENGINE_ID).toBe("pi");
   });
+
+  // ── [R1 D6②] 重注册同名：先 dispose 已实例化的旧单例（防常驻资源泄漏）──
+
+  it("重注册同名：已实例化的旧单例 dispose 被调用一次，新工厂实例生效", () => {
+    const dispose = vi.fn(() => Promise.resolve());
+    registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+    getEngine("fake"); // 实例化旧引擎（未实例化 = 无常驻资源可回收）
+    registerEngine("fake", () => makeFakeEngine("fake-v2"));
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(getEngine("fake").id).toBe("fake-v2");
+  });
+
+  it("重注册同名：旧实例 dispose 同步 throw 不阻断替换（best-effort）", () => {
+    const dispose = vi.fn(() => {
+      throw new Error("dispose boom");
+    });
+    registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+    getEngine("fake");
+    expect(() => registerEngine("fake", () => makeFakeEngine("fake-v2"))).not.toThrow();
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(getEngine("fake").id).toBe("fake-v2");
+  });
+
+  it("重注册同名：旧实例 dispose 异步 reject 不阻断替换、不产生 unhandledRejection", async () => {
+    const dispose = vi.fn(() => Promise.reject(new Error("dispose async boom")));
+    registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+    getEngine("fake");
+    expect(() => registerEngine("fake", () => makeFakeEngine("fake-v2"))).not.toThrow();
+    expect(getEngine("fake").id).toBe("fake-v2");
+    // flush macrotask：reject 必须已被 registry 侧 catch 吞掉——否则 vitest 以
+    // unhandledRejection 判本文件失败，用例即失效
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  });
+
+  it("重注册同名：旧引擎仅注册工厂未实例化时不触发 dispose（惰性单例无资源）", () => {
+    const dispose = vi.fn(() => Promise.resolve());
+    registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+    // 不 getEngine——singletons 无记录
+    registerEngine("fake", () => makeFakeEngine("fake-v2"));
+    expect(dispose).not.toHaveBeenCalled();
+  });
+
+  it("重注册同名：旧实例未实现 dispose（可选成员）时直接替换不抛", () => {
+    registerEngine("fake", () => makeFakeEngine("fake"));
+    getEngine("fake");
+    expect(() => registerEngine("fake", () => makeFakeEngine("fake-v2"))).not.toThrow();
+  });
+
+  // ── [R1 D6③] disposeEngines：宿主收割（killAllSpawnedChildren）前的触发遍历 ──
+
+  describe("disposeEngines（D6③）", () => {
+    it("只对已实例化的引擎触发 dispose（绝不实例化未用引擎）", () => {
+      const instantiated = vi.fn(() => Promise.resolve());
+      const neverInstantiated = vi.fn(() => Promise.resolve());
+      registerEngine("used", () => ({ ...makeFakeEngine("used"), dispose: instantiated }));
+      registerEngine("unused", () => ({ ...makeFakeEngine("unused"), dispose: neverInstantiated }));
+      getEngine("used");
+      disposeEngines();
+      expect(instantiated).toHaveBeenCalledTimes(1);
+      expect(neverInstantiated).not.toHaveBeenCalled();
+    });
+
+    it("未实现 dispose 的引擎（可选面）跳过不抛", () => {
+      registerEngine("plain", () => makeFakeEngine("plain"));
+      getEngine("plain");
+      expect(() => disposeEngines()).not.toThrow();
+    });
+
+    it("dispose 幂等（实现承诺）：disposeEngines 重复调用不抛、逐次触发", async () => {
+      const dispose = vi.fn(() => Promise.resolve());
+      registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+      getEngine("fake");
+      expect(() => disposeEngines()).not.toThrow();
+      expect(() => disposeEngines()).not.toThrow();
+      // 幂等语义由引擎实现承诺（不变量 4），本断言只验证 registry 重复触发不抛
+      expect(dispose).toHaveBeenCalledTimes(2);
+      await new Promise<void>((resolve) => setImmediate(resolve));
+    });
+
+    it("dispose 后单例保留（run 自动重建归引擎承诺，registry 不删——不变量 4 边界）", () => {
+      const dispose = vi.fn(() => Promise.resolve());
+      registerEngine("fake", () => ({ ...makeFakeEngine("fake"), dispose }));
+      const engine = getEngine("fake");
+      disposeEngines();
+      expect(getEngine("fake")).toBe(engine);
+    });
+  });
 });

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

@@ -15,6 +15,10 @@ import * as path from "node:path";
 import { SUBAGENTS_ENGINES_FILENAME, type SubagentEnginesFile } from "@xyz-agent/extension-protocol";
 
 import { listEngines } from "./registry.ts";
+import { writeAtomicFileSync } from "../../shared/atomic-write.ts";
+
+/** engines.json 落盘缩进（与 subagent-core 其他 JSON store 的 JSON_INDENT 约定一致）。 */
+const JSON_INDENT = 2;
 
 /** engines.json 绝对路径（与 config.json 同目录；config.ts 的 getGlobalConfigPath 同构）。 */
 export function getEnginesFilePath(agentDir: string): string {
@@ -25,14 +29,15 @@ export function getEnginesFilePath(agentDir: string): string {
  * 把注册表引擎列表同步到 engines.json（session_start 时调用）。
  *
  * 幂等：内容与现文件一致时零写入（mtime 不动——读侧无谓失效）；写入走 tmp+rename
- * 原子替换（与池 config 同防线）。fail-safe：任何 IO 异常吞掉（可发现性降级不阻塞
+ * 原子替换（shared/atomic-write 统一原语，U6b 迁移——与池 config 同防线）。
+ * fail-safe：任何 IO 异常吞掉（可发现性降级不阻塞
  * session 启动——GUI 兜底显示 ['pi']）。
  */
 export function syncEnginesFile(agentDir: string): void {
   try {
     const filePath = getEnginesFilePath(agentDir);
     const payload: SubagentEnginesFile = { v: 1, engines: listEngines(), updatedAt: Date.now() };
-    const serialized = JSON.stringify(payload, null, 2);
+    const serialized = JSON.stringify(payload, null, JSON_INDENT);
     try {
       const existing = fs.readFileSync(filePath, "utf8");
       const parsed = JSON.parse(existing) as Partial<SubagentEnginesFile>;
@@ -44,22 +49,13 @@ export function syncEnginesFile(agentDir: string): void {
       ) {
         return;
       }
-    } catch {
+    } catch (err) {
       // 现文件缺失/损坏 → 走写入
+      void err;
     }
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-    try {
-      fs.writeFileSync(tmp, serialized, "utf8");
-      fs.renameSync(tmp, filePath);
-    } finally {
-      try {
-        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
-      } catch {
-        // rename 失败路径的残留清理 best-effort
-      }
-    }
-  } catch {
+    writeAtomicFileSync(filePath, serialized);
+  } catch (err) {
     // 吞掉：见文件头 fail-safe 说明
+    void err;
   }
 }

package/src/execution/engine/engines/pi/task-spec-mapper.ts

@@ -29,9 +29,9 @@ export function executeOptionsToTaskSpec(opts: ExecuteOptions): AgentTaskSpec {
   const persona: PersonaSpec | undefined =
     opts.skillPath !== undefined || opts.appendSystemPrompt !== undefined
       ? {
-          ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
-          ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
-        }
+        ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
+        ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
+      }
       : undefined;
   return {
     task: opts.task,

package/src/execution/engine/engines/zcode/__tests__/__fixtures__/fake-appserver.mjs

@@ -0,0 +1,274 @@
+/**
+ * fake app-server（R2 连接层测试专用，绝不 spawn 真 zcode.cjs）。
+ *
+ * 移植改造自 zsw 仓 84b63a0^ z-subagent-workflow/fixtures/fake-appserver.js 的测试
+ * 模式（该仓只读参照），vitest 子进程形态（ESM——本仓 eslint 禁 require，CJS 形态
+ * 被 no-require-imports 拦截）：启动方式与真协议对齐——由被测 AppServerConnection
+ * 以 `node <本文件> app-server --cwd <dir>` spawn（argv 解析后记录进流水，不消费）。
+ * stdio NDJSON，帧形态对齐设计附录 A.1（无 jsonrpc 字段）。
+ *
+ * 测试断言面 = FAKE_STATE_FILE 事件流水（append JSONL）：
+ *   boot / env / recv（收到的每个客户端帧）/ reverse-answer（反向请求收到的我方应答）
+ * / unparseable-from-client。env 开关随 spawn env 固化：
+ *   FAKE_STATE_FILE     流水文件路径（未设则不记流水）
+ *   FAKE_STDERR=1       启动时往 stderr 写两行（tee 落盘断言取证）
+ *   FAKE_EXTRA_KEYS=1   我方应答/推送帧携带未知键（客户端宽容解析断言）
+ *   FAKE_PROTOCOL_PUSH=1 协议自报走 {method:'protocol'} 推送形态（缺省走 A.1 首帧
+ *                        {protocol:{...}} 形态）
+ *
+ * 内置方法（可编程注入四帧型的全部形态）：
+ *   test/echo            应答 {id, result: params}（原样回显——并发 id 关联断言依据）
+ *   test/delay-echo      delayMs 后应答回显（制造在途请求）
+ *   test/fail            应答 {id, error:{code,message,data}}（params 指定）
+ *   test/push            先推一帧 {method: pushMethod, params: pushParams} 再应答
+ *   test/reverse         发一个反向请求（method=params.reverseMethod）并等客户端
+ *                        应答，流水记录后回 {id, result:{answered:true}}
+ *   test/malformed-first 先写一行非 JSON 再正常应答（坏行跳过不断流断言）
+ *   test/suicide         stderr 写 600 字符噪声 + 标记后 exit(1)（崩溃收割断言）
+ *   session/create       真实协议语义（A.2）：先发反向请求 session/requestRuntime
+ *                        Preferences 并等客户端应答（D9 常量表断言依据），流水记录
+ *                        后回 {session:{sessionId}}
+ *   session/subscribe    应答 {subscribed:true}（R3；真实应答形状未知——会话层不校验）
+ *   session/send         按 FAKE_SESSION_SCENARIO 推送帧序列后应答（缺省 {accepted:true}）
+ *   session/read         按 FAKE_SESSION_SCENARIO 应答（缺省 {messages:[]}）
+ *   session/close        应答 {closed:true}
+ *   其余方法             应答 -32601（method not found）
+ *
+ * 会话场景注入（R3 会话层测试；不设 = 各方法走缺省行为，R2 连接层测试不受影响）：
+ *   FAKE_SESSION_SCENARIO=<path> 启动时读取一次的 JSON 文件：
+ *   {
+ *     createResult?: object            覆盖 create 应答（golden create 应答注入）
+ *     createError?: {code,message,data} create 应答 error 帧（-32602/-32601 注入）
+ *     sendError?:   {code,message,data} send 应答 error 帧（-32010/-32602 注入）
+ *     sendPushes?:  [frame, ...]       send 应答前逐帧推送（推送流 + 终态帧全显式
+ *                                      逐字回放，不经 withExtra 改写）
+ *     sendResult?:  object             缺省 {accepted:true}
+ *     readError?:   {code,message,data} read 应答 error 帧（read 兜底降级链断言）
+ *     readResult?:  object             覆盖 read 应答
+ *     stopBehavior?: 'terminal'|'none'  session/stop 的行为（R4 abort 链断言面）：
+ *                                      'terminal'（缺省）= stop 时推送该会话的
+ *                                      turn.terminal 终态帧（stop 优雅生效——不杀
+ *                                      进程的 abort 路径）；'none' = 只应答不推终态
+ *                                      （grace 窗口耗尽 → killChain 兜底路径）
+ *   }
+ *
+ * 多会话支持（R4 引擎接线 / RA3 双会话地基）：
+ *   FAKE_STAMP_SESSION=1   session/send 的推送帧回放时把 params.sessionId 统一改写
+ *                          为「当前 send 的目标会话」，telemetry 帧（无 sid）补记
+ *                          sessionId——并发两会话各自收到归因正确的推送流，不串线。
+ *                          （缺省关：R2/R3 单会话用例的字节级行为不变。）
+ *   session/stop           应答 {stopped:true}；按 scenario.stopBehavior 决定是否
+ *                          推送终态帧（见上）。stopTerminal 推送同样受 STAMP 改写。
+ *
+ * 探针连接支持（R5 降级链——D8 冒烟探针 / D2 门控断言面）：
+ *   ZCODE_APPSERVER_PROBE_CONN=1  本进程是探针连接（引擎 runAppServerSmokeProbe 叠加
+ *                          的 env 标记）：scenario 只读 FAKE_PROBE_SCENARIO（常驻
+ *                          主连接的 FAKE_SESSION_SCENARIO 不作用于探针——故障注入可
+ *                          只命中主连接或只命中探针）；env 快照记 probe 标志。
+ *   FAKE_PROBE_SCENARIO=<path>    仅探针进程消费的 JSON：
+ *     { createError?: {code,message,data} }  探针 create 应答 error 帧（探针失败注入）
+ *     { hangCreate?: true }                   create 永不应答（预算超时注入）
+ */
+import fs from 'node:fs';
+import readline from 'node:readline';
+
+const STATE_FILE = process.env.FAKE_STATE_FILE;
+const EXTRA_KEYS = process.env.FAKE_EXTRA_KEYS === '1';
+const PROTOCOL_AS_PUSH = process.env.FAKE_PROTOCOL_PUSH === '1';
+// [R4] 多会话推送改写开关（见文件头注释）
+const STAMP_SESSION = process.env.FAKE_STAMP_SESSION === '1';
+// [R5] 探针连接判定（引擎探针在 env 叠 ZCODE_APPSERVER_PROBE_CONN=1——见 appserver-probe.ts）
+const IS_PROBE = process.env.ZCODE_APPSERVER_PROBE_CONN === '1';
+
+// 会话场景（R3/R5）：启动时读取一次（env 固化语义与其他 FAKE_ 开关一致）。探针进程
+// 只读 FAKE_PROBE_SCENARIO（与主连接的故障注入互不串扰）
+let SCENARIO = null;
+if (process.env.FAKE_SESSION_SCENARIO && !IS_PROBE) {
+  try {
+    SCENARIO = JSON.parse(fs.readFileSync(process.env.FAKE_SESSION_SCENARIO, 'utf8'));
+  } catch (err) {
+    log('scenario-load-failed', { message: String(err && err.message) });
+  }
+}
+if (process.env.FAKE_PROBE_SCENARIO && IS_PROBE) {
+  try {
+    SCENARIO = JSON.parse(fs.readFileSync(process.env.FAKE_PROBE_SCENARIO, 'utf8'));
+  } catch (err) {
+    log('scenario-load-failed', { message: String(err && err.message) });
+  }
+}
+
+let seq = 0;
+function log(ev, data = {}) {
+  if (!STATE_FILE) return;
+  try {
+    fs.appendFileSync(STATE_FILE, JSON.stringify({ seq: ++seq, ev, ...data }) + '\n');
+  } catch { /* 流水写失败不影响协议行为 */ }
+}
+
+const out = (frame) => process.stdout.write(`${JSON.stringify(frame)}\n`);
+const withExtra = (frame) => (EXTRA_KEYS ? { ...frame, unknownServerKey: 'lenient' } : frame);
+const reply = (id, result) => out(withExtra({ id, result }));
+const replyErr = (id, code, message, data) =>
+  out({ id, error: { code, message, ...(data !== undefined ? { data } : {}) } });
+
+// 协议自报（A.1：首帧 {protocol:{...}}；推送形态显式开关——两种到达形态都要被忽略）
+if (PROTOCOL_AS_PUSH) out({ method: 'protocol', params: { name: 'ZCode Protocol', version: 1 } });
+else out({ protocol: { name: 'ZCode Protocol', version: 1 } });
+
+// SIGTERM 优雅窗口：默认终止会丢弃「已写入管道但尚未读到」的帧——延迟退出让
+// stdin 排空后收尾（dispose 的 close-帧-先于-SIGTERM 顺序在本侧可观测：
+// killChain 的 grace 远大于本窗口，不会升级 SIGKILL）
+process.on('SIGTERM', () => {
+  setTimeout(() => process.exit(0), 100);
+});
+
+// env 快照 + boot 流水（惰性启动 / argv 形态 / env 惯例断言的数据源）
+log('env', {
+  pid: process.pid,
+  home: process.env.HOME,
+  telemetry: process.env.ZCODE_MODEL_TELEMETRY_ENABLED,
+  nested: process.env.ZSW_NESTED,
+  unifiedNested: process.env.XYZ_AGENT_SUBAGENT,
+  probe: process.env.ZCODE_APPSERVER_PROBE_CONN,
+});
+log('boot', { pid: process.pid, argv: process.argv.slice(2) });
+if (process.env.FAKE_STDERR === '1') {
+  process.stderr.write('fake-appserver stderr line A\nfake-appserver stderr line B\n');
+}
+
+// 反向请求记账：id -> 客户端应答到达时 resolve
+let reqSeq = 0;
+const pendingReverse = new Map();
+
+function sendReverse(method, params) {
+  return new Promise((resolve) => {
+    const id = `srv-${++reqSeq}`;
+    pendingReverse.set(id, resolve);
+    out({ id, method, ...(params !== undefined ? { params } : {}) });
+  });
+}
+
+function onClientAnswer(frame) {
+  const settle = pendingReverse.get(frame.id);
+  if (settle) {
+    pendingReverse.delete(frame.id);
+    settle({ id: frame.id, result: frame.result, error: frame.error });
+  }
+}
+
+// 推送帧回放（scenario 帧即 golden 语料/注入形态本身，不走 withExtra）。STAMP_SESSION
+// 开启时统一改写/补记 params.sessionId 为目标会话（RA3 双会话地基：并发两会话各自
+// 收到归因正确的推送流——真服务端推送本就按会话归因，telemetry 帧不带 sid 属协议
+// 实测形态，stamp 是 fake 侧的确定性等价物）。
+function pushFrames(frames, targetSessionId) {
+  for (const frame of frames || []) {
+    if (!STAMP_SESSION || !targetSessionId) {
+      out(frame);
+      continue;
+    }
+    const stamped = JSON.parse(JSON.stringify(frame));
+    if (stamped && typeof stamped.params === 'object' && stamped.params !== null) {
+      stamped.params.sessionId = targetSessionId;
+    }
+    out(stamped);
+  }
+}
+
+// [R4] stop 触发的终态推送（stopBehavior 缺省 'terminal'——abort 优雅生效路径）
+const TURN_TERMINAL_FRAME = {
+  method: 'v4/telemetry/event',
+  params: { kind: 'turn.terminal', status: 'success' },
+};
+
+async function handleRequest(f) {
+  const { id, method } = f;
+  const params = f.params ?? {};
+  switch (method) {
+    case 'test/echo':
+      return reply(id, params);
+    case 'test/delay-echo': {
+      const delay = Number(params.delayMs) || 50;
+      setTimeout(() => reply(id, params), delay);
+      return;
+    }
+    case 'test/fail':
+      return replyErr(id, Number(params.code) || -32603, String(params.message || 'fake failure'), params.data);
+    case 'test/push': {
+      const pushMethod = String(params.pushMethod || 'test/notification');
+      out(withExtra({ method: pushMethod, ...(params.pushParams !== undefined ? { params: params.pushParams } : {}) }));
+      return reply(id, { pushed: true });
+    }
+    case 'test/reverse': {
+      const answer = await sendReverse(String(params.reverseMethod || 'permission/request'), params.reverseParams);
+      log('reverse-answer', { requested: params.reverseMethod, answer });
+      return reply(id, { answered: true });
+    }
+    case 'test/malformed-first':
+      process.stdout.write('this is not json {{{\n');
+      return reply(id, { survived: true });
+    case 'test/suicide':
+      process.stderr.write('A'.repeat(600) + 'CRASH-MARK-TAIL');
+      process.exit(1);
+      return; // 不可达（exit 先行），保持 switch 完整
+    case 'session/create': {
+      // [R5] 探针预算超时注入：hangCreate 时永不应答（探针 deadline 收割判据）
+      if (SCENARIO && SCENARIO.hangCreate) return;
+      if (SCENARIO && SCENARIO.createError) {
+        return replyErr(id, SCENARIO.createError.code, SCENARIO.createError.message, SCENARIO.createError.data);
+      }
+      const answer = await sendReverse('session/requestRuntimePreferences');
+      log('reverse-answer', { requested: 'session/requestRuntimePreferences', answer });
+      if (SCENARIO && SCENARIO.createResult) return reply(id, SCENARIO.createResult);
+      return reply(id, { session: { sessionId: `sess_${id}` } });
+    }
+    case 'session/subscribe':
+      return reply(id, (SCENARIO && SCENARIO.subscribeResult) || { subscribed: true });
+    case 'session/send': {
+      if (SCENARIO && SCENARIO.sendError) {
+        return replyErr(id, SCENARIO.sendError.code, SCENARIO.sendError.message, SCENARIO.sendError.data);
+      }
+      // 推送帧逐字回放（STAMP_SESSION 时按目标会话归因改写）
+      pushFrames(SCENARIO && SCENARIO.sendPushes, String(params.sessionId || ''));
+      return reply(id, (SCENARIO && SCENARIO.sendResult) || { accepted: true });
+    }
+    case 'session/stop': {
+      // [R4] abort 链断言面：缺省推终态（stop 优雅生效）；stopBehavior:'none' 只应答
+      const behavior = (SCENARIO && SCENARIO.stopBehavior) || 'terminal';
+      if (behavior === 'terminal') {
+        pushFrames([TURN_TERMINAL_FRAME], String(params.sessionId || ''));
+      }
+      return reply(id, { stopped: true });
+    }
+    case 'session/read': {
+      if (SCENARIO && SCENARIO.readError) {
+        return replyErr(id, SCENARIO.readError.code, SCENARIO.readError.message, SCENARIO.readError.data);
+      }
+      return reply(id, (SCENARIO && SCENARIO.readResult) || { messages: [] });
+    }
+    case 'session/close':
+      return reply(id, { closed: true });
+    default:
+      return replyErr(id, -32601, `method not found: ${method}`);
+  }
+}
+
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', (line) => {
+  const text = String(line).trim();
+  if (!text) return;
+  let f;
+  try {
+    f = JSON.parse(text);
+  } catch {
+    log('unparseable-from-client', { line: text.slice(0, 100) });
+    return;
+  }
+  log('recv', { frame: f });
+  if (f && f.id != null && typeof f.method === 'string') {
+    void handleRequest(f);
+    return;
+  }
+  if (f && f.id != null) onClientAnswer(f); // 我方反向请求的客户端应答
+});
+rl.on('close', () => process.exit(0));

package/src/execution/engine/engines/zcode/__tests__/__fixtures__/zcode-golden-appserver.json

@@ -0,0 +1,36 @@
+{
+  "_meta": {
+    "description": "zcode app-server 常驻通道 golden 帧序列语料（R3）。四类样本：create 应答 / 推送流 / 终态帧 / read 应答（NDJSON 逐行，附录 A.2 任务生命周期帧序）",
+    "source": "synthesized-from-A2-protocol-authority",
+    "synthesisNote": "非真机实录——按设计附录 A.2（协议权威，zcode.cjs 0.16.5 二进制字符串级验证命中）+ 旧 zsw 实现真机抓包形态（zsw 仓 84b63a0^ runner-appserver.js 实测注释）合成。真机冒烟（RA 跨仓段）后应替换为实录并同步双副本。telemetry 帧不带 sessionId（A.2 未标）——归因走唯一在途兜底；session/event 帧带 sessionId",
+    "engineVersion": "0.16.5 (app-server)",
+    "protocolVersion": 1,
+    "recordedAt": "2026-08-30",
+    "invariants": {
+      "textIdentity": "pushStream 中 payload.delta 拼接 === terminal 收尾帧 payload.response === readResponse 最后 assistant 消息 text parts 拼接（'你好，任务完成'）——不变量 1 双来源",
+      "usage": "收尾帧 usage {inputTokens:12599, outputTokens:17} 与 spawn golden（zcode-golden-spawn.json）同值——漂移对照锚点"
+    },
+    "frames": {
+      "createResponse": "session/create 应答帧（NDJSON 单行）。projection.sessionId 恒 \"unknown\"（勿用），权威位置 session.sessionId",
+      "pushStream": "推送流帧（A.2 ④ 逐行）：state.updated 进入 running / v4 telemetry stream.chunk（无文本，chunkLength 遥测）/ session/event payload.delta（实时文本增量）",
+      "terminal": "终态帧（A.2 ⑤ 逐行）：v4 telemetry turn.terminal（终态权威，status 枚举）+ session/event 收尾帧（全文 + usage）",
+      "readResponse": "session/read 应答帧（NDJSON 单行，A.2 ⑥）：messages[].info.role + parts[]（text 全文 / step-finish tokens——tokens 结构属 A.5 未确认项，宽容解析）"
+    }
+  },
+  "frames": {
+    "createResponse": "{\"session\":{\"sessionId\":\"sess_golden_r3_01\"},\"projection\":{\"sessionId\":\"unknown\",\"status\":\"idle\",\"turnCount\":0,\"totalTokenCount\":0,\"contextUsed\":0,\"contextWindow\":1000000}}",
+    "pushStream": [
+      "{\"method\":\"state.updated\",\"params\":{\"sessionId\":\"sess_golden_r3_01\",\"patch\":{\"status\":\"running\"},\"reason\":\"prompt_started\"}}",
+      "{\"method\":\"v4/telemetry/event\",\"params\":{\"kind\":\"stream.chunk\",\"channel\":\"text\",\"chunkLength\":6,\"firstChunk\":true,\"assistantMessageId\":\"msg_golden_r3_01\"}}",
+      "{\"method\":\"session/event\",\"params\":{\"sessionId\":\"sess_golden_r3_01\",\"payload\":{\"delta\":\"你好\",\"assistantMessageId\":\"msg_golden_r3_01\"}}}",
+      "{\"method\":\"v4/telemetry/event\",\"params\":{\"kind\":\"stream.chunk\",\"channel\":\"text\",\"chunkLength\":1,\"firstChunk\":false,\"assistantMessageId\":\"msg_golden_r3_01\"}}",
+      "{\"method\":\"session/event\",\"params\":{\"sessionId\":\"sess_golden_r3_01\",\"payload\":{\"delta\":\"，\",\"assistantMessageId\":\"msg_golden_r3_01\"}}}",
+      "{\"method\":\"session/event\",\"params\":{\"sessionId\":\"sess_golden_r3_01\",\"payload\":{\"delta\":\"任务完成\",\"assistantMessageId\":\"msg_golden_r3_01\"}}}"
+    ],
+    "terminal": [
+      "{\"method\":\"v4/telemetry/event\",\"params\":{\"kind\":\"turn.terminal\",\"status\":\"success\"}}",
+      "{\"method\":\"session/event\",\"params\":{\"sessionId\":\"sess_golden_r3_01\",\"payload\":{\"response\":\"你好，任务完成\",\"usage\":{\"inputTokens\":12599,\"outputTokens\":17}}}}"
+    ],
+    "readResponse": "{\"messages\":[{\"info\":{\"role\":\"user\"},\"parts\":[{\"type\":\"text\",\"text\":\"做点什么\"}]},{\"info\":{\"role\":\"assistant\"},\"parts\":[{\"type\":\"text\",\"text\":\"你好\"},{\"type\":\"text\",\"text\":\"，任务完成\"},{\"type\":\"step-finish\",\"tokens\":{\"input\":12599,\"output\":17,\"reasoning\":0,\"cache\":512,\"total\":12616}}]}]}"
+  }
+}