@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/{spawn-event-adapter.ts → engine/engines/pi/spawn-event-adapter.ts}

@@ -1,4 +1,4 @@
-// src/core/spawn-event-adapter.ts
+// src/execution/engine/engines/pi/spawn-event-adapter.ts
 //
 // pi 子进程 stdout JSON 事件流的解析器。Core 叶子原语（仅依赖 types.ts）。
 //
@@ -20,7 +20,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import type { SdkEvent } from "./types.ts";
+import type { SdkEvent } from "../../../types.ts";
+import { toErrorMessage } from "../../../../core/error-message.ts";
 
 /** pi stdout header 行（session 元信息）。type 固定为 "session"。 */
 export interface SpawnSessionHeader {
@@ -158,6 +159,56 @@ function isExtensionUiRequest(obj: unknown): obj is ExtensionUiRequestEnvelope {
   );
 }
 
+/** 必填 string 字段提取：类型不符降级空串（字段容错——仍归类已知 method，不丢 method 信息）。 */
+function reqStr(r: Record<string, unknown>, key: string): string {
+  const v = r[key];
+  return typeof v === "string" ? v : "";
+}
+
+/** string[] 字段提取：数组剔除非字符串元素；非数组降级 onMissing（options 传 []，
+ *  widgetLines 传 undefined——两者对缺失值的载荷语义不同：前者恒挂键，后者键挂值 undefined）。 */
+function strArrayField<T extends string[] | undefined>(
+  r: Record<string, unknown>,
+  key: string,
+  onMissing: T,
+): string[] | T {
+  const v = r[key];
+  return Array.isArray(v)
+    ? v.filter((x): x is string => typeof x === "string")
+    : onMissing;
+}
+
+/** timeout 条件展开：非 number 不挂键（timeout?: number 的字段省略语义）。 */
+function optTimeout(r: Record<string, unknown>): { timeout?: number } {
+  return typeof r.timeout === "number" ? { timeout: r.timeout } : {};
+}
+
+/** placeholder 条件展开：非 string 不挂键。 */
+function optPlaceholder(r: Record<string, unknown>): { placeholder?: string } {
+  return typeof r.placeholder === "string" ? { placeholder: r.placeholder } : {};
+}
+
+/** prefill 条件展开：非 string 不挂键。 */
+function optPrefill(r: Record<string, unknown>): { prefill?: string } {
+  return typeof r.prefill === "string" ? { prefill: r.prefill } : {};
+}
+
+/** notifyType 条件展开：仅接受三种已知枚举值，其余不挂键。 */
+function optNotifyType(
+  r: Record<string, unknown>
+): { notifyType?: "info" | "warning" | "error" } {
+  const v = r.notifyType;
+  return v === "info" || v === "warning" || v === "error" ? { notifyType: v } : {};
+}
+
+/** widgetPlacement 条件展开：仅接受两种已知枚举值，其余不挂键。 */
+function optWidgetPlacement(
+  r: Record<string, unknown>
+): { widgetPlacement?: "aboveEditor" | "belowEditor" } {
+  const v = r.widgetPlacement;
+  return v === "aboveEditor" || v === "belowEditor" ? { widgetPlacement: v } : {};
+}
+
 /**
  * 从已通过 isExtensionUiRequest 守卫的 envelope 构造 ExtensionUiRequest 变体。
  *
@@ -166,6 +217,7 @@ function isExtensionUiRequest(obj: unknown): obj is ExtensionUiRequestEnvelope {
  *
  * 字段类型容错：协议字段类型不符（如 options 非数组）时，该字段降级为空数组/undefined
  *（数组类字段做元素类型过滤，剔除非字符串元素），仍归类为已知 method（不丢 method 信息）。
+ * 字段级提取/条件展开由上方字段 helper 承担，本函数只做 method 分发。
  */
 function buildExtensionUiRequest(env: ExtensionUiRequestEnvelope): ExtensionUiRequest {
   const r: Record<string, unknown> = env;
@@ -173,69 +225,58 @@ function buildExtensionUiRequest(env: ExtensionUiRequestEnvelope): ExtensionUiRe
     case "select":
       return {
         method: "select",
-        title: typeof r.title === "string" ? r.title : "",
-        options: Array.isArray(r.options)
-          ? r.options.filter((x): x is string => typeof x === "string")
-          : [],
-        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+        title: reqStr(r, "title"),
+        options: strArrayField(r, "options", []),
+        ...optTimeout(r),
       };
     case "confirm":
       return {
         method: "confirm",
-        title: typeof r.title === "string" ? r.title : "",
-        message: typeof r.message === "string" ? r.message : "",
-        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+        title: reqStr(r, "title"),
+        message: reqStr(r, "message"),
+        ...optTimeout(r),
       };
     case "input":
       return {
         method: "input",
-        title: typeof r.title === "string" ? r.title : "",
-        ...(typeof r.placeholder === "string" ? { placeholder: r.placeholder } : {}),
-        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+        title: reqStr(r, "title"),
+        ...optPlaceholder(r),
+        ...optTimeout(r),
       };
     case "editor":
       return {
         method: "editor",
-        title: typeof r.title === "string" ? r.title : "",
-        ...(typeof r.prefill === "string" ? { prefill: r.prefill } : {}),
+        title: reqStr(r, "title"),
+        ...optPrefill(r),
       };
     case "notify":
       return {
         method: "notify",
-        message: typeof r.message === "string" ? r.message : "",
-        ...(r.notifyType === "info" || r.notifyType === "warning" || r.notifyType === "error"
-          ? { notifyType: r.notifyType }
-          : {}),
+        message: reqStr(r, "message"),
+        ...optNotifyType(r),
       };
     case "setStatus":
       return {
         method: "setStatus",
-        statusKey: typeof r.statusKey === "string" ? r.statusKey : "",
+        statusKey: reqStr(r, "statusKey"),
         statusText: typeof r.statusText === "string" ? r.statusText : undefined,
       };
-    case "setWidget": {
-      const placement = r.widgetPlacement;
-      const widgetLines = Array.isArray(r.widgetLines)
-        ? r.widgetLines.filter((x): x is string => typeof x === "string")
-        : undefined;
+    case "setWidget":
       return {
         method: "setWidget",
-        widgetKey: typeof r.widgetKey === "string" ? r.widgetKey : "",
-        widgetLines,
-        ...(placement === "aboveEditor" || placement === "belowEditor"
-          ? { widgetPlacement: placement }
-          : {}),
+        widgetKey: reqStr(r, "widgetKey"),
+        widgetLines: strArrayField(r, "widgetLines", undefined),
+        ...optWidgetPlacement(r),
       };
-    }
     case "setTitle":
       return {
         method: "setTitle",
-        title: typeof r.title === "string" ? r.title : "",
+        title: reqStr(r, "title"),
       };
     case "set_editor_text":
       return {
         method: "set_editor_text",
-        text: typeof r.text === "string" ? r.text : "",
+        text: reqStr(r, "text"),
       };
     default:
       // 未知 method：保留全部原始字段，避免协议演进时丢信息
@@ -273,7 +314,7 @@ export function parseSpawnLine(line: string): ParsedSpawnLine | null {
     return {
       kind: "invalid",
       raw: trimmed,
-      error: err instanceof Error ? err.message : String(err),
+      error: toErrorMessage(err),
     };
   }
 

package/src/execution/{stdin-writer.ts → engine/engines/pi/stdin-writer.ts}

@@ -1,4 +1,4 @@
-// src/execution/stdin-writer.ts
+// src/execution/engine/engines/pi/stdin-writer.ts
 //
 // 向 rpc 子进程 stdin 写入命令的 helper 集合。
 //
@@ -10,9 +10,10 @@
 import type { ChildProcess } from "node:child_process";
 import * as crypto from "node:crypto";
 
-import { getLogger } from "../core/logger.ts";
+import { getLogger } from "../../../../core/logger.ts";
 
-import type { UiResponse } from "./dialog-queue.ts";
+import type { UiResponse } from "../../../dialog-queue.ts";
+import { toErrorMessage } from "../../../../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
@@ -25,7 +26,7 @@ const logger = getLogger("subagents");
  * 是 stdin 域中立模块，epipe 计数属 stdin 错误域，职责合理。
  *
  * 错误处理两半面共用本计数器（合并计数，防 spawn→EPIPE→resume 死循环）：
- *   ① 同步 write 抛错（writeStdinLine throw → deliverMessage catch 递增）
+ *   ① 同步 write 抛错（writeStdinLine throw → PiEngine.deliverPrompt catch 递增）
  *   ② 异步 stream 'error' event（session-runner.ts child.stdin.on('error') 递增）
  */
 const epipeConsecutiveFailures = new Map<string, number>();
@@ -79,7 +80,7 @@ export function respond(child: ChildProcess, id: string, out: UiResponse, signal
   } catch (err) {
     // [R2] out.value 含循环引用/BigInt 等不可序列化结构——降级 cancelled，避免父进程崩溃。
     logger.warn(`[subagents] JSON.stringify failed for ui response ${id}, degrading to cancelled`, {
-      detail: err instanceof Error ? err.message : String(err),
+      detail: toErrorMessage(err),
     });
     line = JSON.stringify({ type: "extension_ui_response", id, cancelled: true });
   }
@@ -158,7 +159,7 @@ export function sendGetStateCommand(child: ChildProcess): string {
  *
  * [R1] write 返回 false 时记 warn（不阻塞，内核缓冲会随后排空）。
  * [R3] write 抛 EPIPE / ERR_STREAM_DESTROYED 时 throw 含 EPIPE 关键词的 Error，
- *      让上层（deliverMessage）能捕获并自动转冷路径 resume。
+ *      让上层（PiEngine.deliverPrompt）能捕获并自动转冷路径 resume。
  * stdin 已关闭/销毁时跳过——respond 已检查 signal，sendPromptCommand 已检查 destroyed。
  *
  * @param child 子进程
@@ -173,11 +174,11 @@ function writeStdinLine(child: ChildProcess, line: string, warnTag: string): voi
     if (!ok) logger.warn(`[subagents] stdin backpressure on ${warnTag}`);
   } catch (err) {
     // [R3] EPIPE / ERR_STREAM_DESTROYED：stdin 管道已断，子进程已退出或 stdin 被销毁。
-    // [v4 A-1] 错误处理两半面：① 同步 write 抛错（本 catch）——上层 deliverMessage 捕获后
+    // [v4 A-1] 错误处理两半面：① 同步 write 抛错（本 catch）——上层（PiEngine.deliverPrompt）捕获后
     //   调 recordEpipeFailure 递增计数；② 异步 stream 'error' event（session-runner.ts 的
     //   child.stdin.on('error') listener）。两者共用本模块 export 的 recordEpipeFailure
     //   helper 合并计数（防 spawn→EPIPE→resume 死循环）。
-    // throw 让上层（deliverMessage）捕获并自动转冷路径 resume + 消息重放。
+    // throw 让上层（PiEngine.deliverPrompt）捕获并自动转冷路径 resume + 消息重放。
     if (
       err !== null &&
       typeof err === "object" &&
@@ -192,7 +193,7 @@ function writeStdinLine(child: ChildProcess, line: string, warnTag: string): voi
     }
     // 非 EPIPE 错误（不应发生，但兜底降级为 warn 不崩溃）
     logger.warn(`[subagents] unexpected stdin write error on ${warnTag}`, {
-      detail: err instanceof Error ? err.message : String(err),
+      detail: toErrorMessage(err),
     });
   }
 }

package/src/execution/{temp-prompt.ts → engine/engines/pi/temp-prompt.ts}

@@ -1,4 +1,4 @@
-// src/core/temp-prompt.ts
+// src/execution/engine/engines/pi/temp-prompt.ts
 //
 // 将 agent systemPrompt 写入临时文件，供 pi CLI --append-system-prompt 使用。
 // Core 叶子原语（node 内置 + 同目录 bestEffort 清理 helper）。注意 bestEffort
@@ -14,7 +14,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { bestEffort } from "./best-effort.ts";
+import { bestEffort } from "../../../best-effort.ts";
 
 /** 临时 prompt 文件创建结果。dir 供调用方清理。 */
 export interface TempPromptFile {

package/src/execution/{turn-limiter.ts → engine/engines/pi/turn-limiter.ts}

@@ -1,4 +1,4 @@
-// src/core/turn-limiter.ts
+// src/execution/engine/engines/pi/turn-limiter.ts
 //
 // soft/hard turn 限制器。maxTurns 到达 → steer 提醒收尾；
 // graceTurns 后仍不结束 → abort。

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

@@ -0,0 +1,301 @@
+/**
+ * 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}
+ *     crashAfterSendMs?: number        [P0-1 U4] send 应答后 N ms 自杀 exit(1)（连接
+ *                                      崩溃收割注入——onClose → failAllTurns 在途
+ *                                      turn 收割；进程死 → 下次 request 惰性重建
+ *                                      boot 新代重读 scenario，重试轮/下一任务形态
+ *                                      切换经测试侧 rewriteScenario）
+ *     rebootSendPushes?: [frame, ...]  [P0-1 U4] 非首代进程（本 fake 启动时 state 流水
+ *                                      已有 boot 记录——崩溃/杀链后的重建代）的 send
+ *                                      推送序列，替代 sendPushes：崩溃后惰性重建的
+ *                                      重试轮拿到不同行为（如完整终态流）——首轮挂起
+ *                                      + 重试轮成功的静态注入通道（同任务重试轮无法
+ *                                      经测试侧 rewriteScenario 插手，run 整体 await）
+ *     readError?:   {code,message,data} read 应答 error 帧（read 兜底降级链断言）
+ *     readResult?:  object             覆盖 read 应答
+ *     stopBehavior?: 'terminal'|'none'|'hang'
+ *                                      session/stop 的行为（R4 abort 链断言面）：
+ *                                      'terminal'（缺省）= stop 时推送该会话的
+ *                                      turn.terminal 终态帧（stop 优雅生效——不杀
+ *                                      进程的 abort 路径）；'none' = 只应答不推终态
+ *                                      （grace 窗口耗尽 → killChain 兜底路径）；
+ *                                      'hang' = 连应答都不给（P0-1 U2 超时入口态③——
+ *                                      控制面假死注入，stop 3s 超时 → 连接级失败判据）
+ *     stopError?:   {code,message,data} stop 应答 error 帧（P0-1 U2 超时入口态②——
+ *                                      协议性 error（如会话已回收）注入，断言不升级杀链）
+ *   }
+ *
+ * 多会话支持（R4 引擎接线 / RA3 双会话地基）：
+ *   FAKE_STAMP_SESSION=1   session/send 的推送帧回放时把 params.sessionId 统一改写
+ *                          为「当前 send 的目标会话」，telemetry 帧（无 sid）补记
+ *                          sessionId——并发两会话各自收到归因正确的推送流，不串线。
+ *                          （缺省关：R2/R3 单会话用例的字节级行为不变。）
+ *   session/stop           应答 {stopped:true}；按 scenario.stopBehavior 决定是否
+ *                          推送终态帧（见上）。stopTerminal 推送同样受 STAMP 改写。
+ */
+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';
+
+// 会话场景（R3）：启动时读取一次（env 固化语义与其他 FAKE_ 开关一致）
+let SCENARIO = null;
+if (process.env.FAKE_SESSION_SCENARIO) {
+  try {
+    SCENARIO = JSON.parse(fs.readFileSync(process.env.FAKE_SESSION_SCENARIO, 'utf8'));
+  } catch (err) {
+    log('scenario-load-failed', { message: String(err && err.message) });
+  }
+}
+
+// [P0-1 U4] 本进程代数（state 流水已有 boot 记录数 + 1）：崩溃/杀链后的惰性重建代
+// ≥2——rebootSendPushes 仅对重建代生效（重试轮拿到与首轮不同的推送序列）
+let BOOT_GEN = 1;
+if (STATE_FILE && SCENARIO && SCENARIO.rebootSendPushes) {
+  try {
+    const priorBoots = fs
+      .readFileSync(STATE_FILE, 'utf8')
+      .split('\n')
+      .filter((l) => l.includes('"ev":"boot"')).length;
+    BOOT_GEN = priorBoots + 1;
+  } catch { /* 流水读失败按首代处理 */ }
+}
+
+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,
+});
+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': {
+      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 时按目标会话归因改写）；重建代走 rebootSendPushes
+      // （U4：重试轮的不同行为通道）
+      const pushes =
+        BOOT_GEN > 1 && SCENARIO && SCENARIO.rebootSendPushes
+          ? SCENARIO.rebootSendPushes
+          : SCENARIO && SCENARIO.sendPushes;
+      pushFrames(pushes, String(params.sessionId || ''));
+      // [P0-1 U4] 崩溃收割注入：应答后 N ms 自杀（onClose → failAllTurns 在途 turn
+      // 收割的确定性触发面；exit(1) 非零码与 test/suicide 同形态）
+      const crashAfterSendMs = SCENARIO && SCENARIO.crashAfterSendMs;
+      if (typeof crashAfterSendMs === 'number' && crashAfterSendMs >= 0) {
+        setTimeout(() => {
+          log('crash-injected', { afterMs: crashAfterSendMs });
+          process.exit(1);
+        }, crashAfterSendMs).unref();
+      }
+      return reply(id, (SCENARIO && SCENARIO.sendResult) || { accepted: true });
+    }
+    case 'session/stop': {
+      // [R4] abort 链断言面：缺省推终态（stop 优雅生效）；stopBehavior:'none' 只应答；
+      // stopError 注入协议性 error 应答帧（P0-1 U2 态②——不升级杀链判据）；
+      // stopBehavior:'hang' 永不应答（态③——stop 3s 超时 = 连接级失败判据）
+      const behavior = (SCENARIO && SCENARIO.stopBehavior) || 'terminal';
+      if (behavior === 'hang') return;
+      if (SCENARIO && SCENARIO.stopError) {
+        return replyErr(id, SCENARIO.stopError.code, SCENARIO.stopError.message, SCENARIO.stopError.data);
+      }
+      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}}]}]}"
+  }
+}