@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/execution/engine/engines/zcode/appserver-launcher.ts

@@ -0,0 +1,167 @@
+// src/execution/engine/engines/zcode/appserver-launcher.ts
+//
+// app-server 启动 wrapper（2026-09 共享宿主 HOME 形态的凭据供数机制）。
+//
+// 为什么需要：CLI 形态的 zcode app-server 只从 `$HOME/.zcode/cli/config.json` 的
+// provider 字段读凭据（bundle 实测：路径硬编码，userConfigPath/modelConfig 参数仅对
+// GUI 同代码库内嵌调用方开放，env/argv/协议面无配置注入通道）；而 GUI 把凭据放
+// `~/.zcode/v2/config.json` 且从不写 cli/config.json——外部 spawn 的 app-server 在
+// 真实 HOME 下是「无源之水」（实测报 "Model provider ... is missing baseURL"）。
+//
+// 解法（fs 拦截 wrapper，用户拍板「包一层」）：spawn 的不是 zcode.cjs 而是本模块
+// 落盘的 launcher 脚本——它 patch fs.readFileSync/fsPromises.readFile/existsSync
+// （真实 bundle 的用户 config 读取是 existsSync 短路在前：文件不存在直接返回空
+// config，readFileSync 不被调用——GUI-only 登录宿主上不拦 existsSync = 注入整体
+// 不可见），把对 cli/config.json 精确路径的读取重定向为「真实文件 + v2 provider
+// 注入」的内存合并结果（同 id 时 v2 整条优先——v2 是权威凭据源，等价复刻 GUI
+// 直传 modelConfig），再以原 argv 启动 zcode.cjs。HOME 保持真实值（共享语义
+// 不变：db/plugins/MCP 全继承宿主 HOME）。
+//
+// 漂移面如实登记：zcode 升级若改变配置读取路径/方式，失败信号 = missing baseURL /
+// Model config is missing 明确报错（不静默坏）——与协议漂移直接报错的既有姿态同级。
+//
+// 源码以内嵌字符串形态进 dist bundle（vendored 面只拷 dist/，独立 .cjs 资产会被
+// vendor 脚本漏掉——字符串常量无此问题），运行时幂等落盘 engineDataDir。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { toErrorMessage } from "../../../../core/error-message.ts";
+
+/** wrapper 落盘文件名（engineDataDir/engines/zcode/ 下）。 */
+export const ZCODE_APPSERVER_LAUNCHER_NAME = "appserver-launcher.cjs";
+
+/**
+ * wrapper 源码（CJS；内容即版本——修改须同步本常量，落盘端按内容幂等覆盖）。
+ * env 契约：ZCODE_ENG_CLI_PATH（zcode.cjs 绝对路径，必填）、
+ * ZCODE_ENG_V2_CONFIG（v2 config 路径，缺省 ~/.zcode/v2/config.json）。
+ */
+export const APPSERVER_LAUNCHER_SOURCE = `'use strict';
+// zcode app-server fs 拦截 wrapper（由 subagent-core appserver-launcher 落盘生成）
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const CLI_PATH = process.env.ZCODE_ENG_CLI_PATH;
+const V2_PATH = process.env.ZCODE_ENG_V2_CONFIG || path.join(os.homedir(), '.zcode', 'v2', 'config.json');
+const CONFIG_PATH = path.join(os.homedir(), '.zcode', 'cli', 'config.json');
+// 与 constants.ts ZCODE_FALLBACK_DEFAULT_MODEL 双源（内嵌字符串无法 import）——改那边须同步此处
+const FALLBACK_MODEL_MAIN = 'builtin:bigmodel-coding-plan/GLM-5.3';
+
+// 合并形态：真实 cli config 原样（model/plugins/mcp/subagents 等 worker 继承面不变）
+// + v2 的 provider 字典注入，同 id 时 v2 条目整条优先——GUI 直传 modelConfig 时
+// v2 即权威源（进程外等价复刻）；cli config 不在 GUI 管理面、可能残留历史验证
+// 配置（2026-08-25 事故：残留旧 key 压过新凭据致 turn 0 401），故不取 real 优先。
+// 返回 null = 无可注入凭据（v2 无 provider 条目）——不 patch，让原生报错透出。
+// 读源经 readOrig 间接取：patch 前首调 = fs.readFileSync 本体；patch 后 = 原函数
+// （防 patch 后的递归自调用）。
+function injectedConfigText() {
+  const readOrig = fs.__origReadFileSync || fs.readFileSync;
+  let real = {};
+  try { real = JSON.parse(readOrig(CONFIG_PATH, 'utf8')); } catch { /* 无/损坏 → 空 */ }
+  let v2 = {};
+  try { v2 = JSON.parse(readOrig(V2_PATH, 'utf8')); }
+  catch (err) {
+    // ENOENT = 桌面端未登录（正常 no-patch，静默）；其他失败（JSON 损坏/权限）
+    // 出声——否则排障会被原生「请登录」报错误导，与真因（文件损坏）不符
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write('[zcode-launcher] v2 config 读取失败(' + ((err && err.code) || (err && err.message) || 'unknown') + '): ' + V2_PATH + '——凭据注入未生效\\n');
+    }
+    return null;
+  }
+  const v2Providers = v2.provider && typeof v2.provider === 'object' ? v2.provider : {};
+  const hasKey = (entry) => entry && typeof entry === 'object'
+    && entry.options && typeof entry.options.apiKey === 'string' && entry.options.apiKey !== '';
+  const injectable = {};
+  for (const [id, entry] of Object.entries(v2Providers)) {
+    if (hasKey(entry)) injectable[id] = entry;
+  }
+  if (Object.keys(injectable).length === 0) return null;
+  const merged = { ...real };
+  merged.provider = { ...(real.provider && typeof real.provider === 'object' ? real.provider : {}), ...injectable };
+  if (!merged.model || typeof merged.model !== 'object' || !merged.model.main) {
+    const main = (v2.model && v2.model.main) || FALLBACK_MODEL_MAIN;
+    merged.model = { ...(merged.model || {}), main };
+  }
+  return JSON.stringify(merged);
+}
+
+if (!CLI_PATH) {
+  process.stderr.write('[zcode-launcher] ZCODE_ENG_CLI_PATH 未设置，无法启动 app-server（该 env 由引擎自动设置；手工运行 wrapper 需显式传入）\\n');
+  process.exit(2);
+}
+
+const text = injectedConfigText();
+if (text !== null) {
+  // encoding 归一（Node 别名面）：'utf8'/'utf-8'/大小写变体统一按 string 返回——
+  // 真实 bundle 的 config 读取恰用 'utf-8' 形态，仅匹配 'utf8' 会错回 Buffer
+  // （当下游不只 JSON.parse 而做字符串运算时即 TypeError）
+  const shape = (args, value) => {
+    const enc = args[0];
+    const e = typeof enc === 'string' ? enc
+      : (enc && typeof enc === 'object' && typeof enc.encoding === 'string' ? enc.encoding : undefined);
+    if (e !== undefined && String(e).toLowerCase().replace(/-/g, '') === 'utf8') return value;
+    return Buffer.from(value);
+  };
+  fs.__origReadFileSync = fs.readFileSync;
+  fs.readFileSync = function (p, ...rest) {
+    if (typeof p === 'string' && p === CONFIG_PATH) {
+      const cur = injectedConfigText();
+      if (cur !== null) return shape(rest, cur);
+    }
+    return fs.__origReadFileSync.call(fs, p, ...rest);
+  };
+  fs.promises.__origReadFile = fs.promises.readFile;
+  fs.promises.readFile = function (p, ...rest) {
+    if (typeof p === 'string' && p === CONFIG_PATH) {
+      const cur = injectedConfigText();
+      if (cur !== null) return Promise.resolve(shape(rest, cur));
+    }
+    return fs.promises.__origReadFile.call(fs.promises, p, ...rest);
+  };
+  // existsSync 拦截：真实 bundle 的用户 config 读取（loadFileConfig）以 existsSync
+  // 为短路门——文件不存在时返回空 config 且 readFileSync 不被调用，GUI-only
+  // 登录宿主（cli/config.json 从未被 CLI 侧写过）上注入只挂在读取面 = 不可见
+  fs.__origExistsSync = fs.existsSync;
+  fs.existsSync = function (p) {
+    if (typeof p === 'string' && p === CONFIG_PATH) {
+      const cur = injectedConfigText();
+      if (cur !== null) return true;
+    }
+    return fs.__origExistsSync.call(fs, p);
+  };
+}
+
+// 以原 argv 形态启动 zcode.cjs（argv[0]=node, argv[1]=本 wrapper，argv[2]=app-server——
+// zcode.cjs 的 includes('app-server') 判定不受影响）。import() 兼容 CJS/ESM 入口。
+import(CLI_PATH).catch((err) => {
+  process.stderr.write('[zcode-launcher] zcode.cjs 加载失败: ' + (err && err.message || err) + '\\n');
+  process.exit(3);
+});
+`;
+
+/**
+ * 幂等落盘 launcher 脚本并返回其绝对路径（内容未变跳过写——mtime 免重写）。
+ * @param engineDataDir 引擎数据根（launcher 落 engineDataDir/engines/zcode/）
+ */
+export function ensureAppServerLauncher(engineDataDir: string): string {
+  const dir = path.join(engineDataDir, "engines", "zcode");
+  const file = path.join(dir, ZCODE_APPSERVER_LAUNCHER_NAME);
+  const existing = fs.existsSync(file) && fs.statSync(file).isFile()
+    ? fs.readFileSync(file, "utf8")
+    : undefined;
+  if (existing === APPSERVER_LAUNCHER_SOURCE) return file;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, APPSERVER_LAUNCHER_SOURCE);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    // 裸 errno（EACCES/ENOSPC）不含恢复动作——与 probe 失败的错误姿态对齐
+    const reason = toErrorMessage(err);
+    throw new Error(
+      `zcode app-server launcher 落盘失败: ${file}（${reason}）。恢复：检查引擎数据目录` +
+        ` 写权限与磁盘空间（engineDataDir 由宿主传入，路径见上）后重试。`,
+    );
+  }
+  return file;
+}

package/src/execution/engine/engines/zcode/connection.ts

@@ -47,6 +47,7 @@ import {
   ZCODE_APPSERVER_STDERR_TAIL_CHARS,
   ZCODE_KILL_GRACE_MS,
 } from "./constants.ts";
+import { toErrorMessage } from "../../../../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
@@ -108,7 +109,7 @@ function frameIdOf(frame: Record<string, unknown>): string | number | undefined
 
 /** 错误/日志出声用的 message 提取（非 Error 值不抛二次异常）。 */
 function errMessage(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
+  return toErrorMessage(err);
 }
 
 // ============================================================
@@ -117,16 +118,18 @@ function errMessage(err: unknown): string {
 
 /**
  * 组装 app-server 子进程 env：嵌套防护经公共 nesting-guard（注入统一
- * XYZ_AGENT_SUBAGENT=1 + 剥离引擎原生嵌套标记），HOME 最后落（隔离 HOME 是 provider
- * 配置与 db 的定位锚，基 env 同名键不许覆盖），遥测关闭（旧实现实证：隔离 HOME 内
- * 不写遥测标识）。与 launcher.buildZcodeEnv 同惯例，app-server 形态多一层
- * ZCODE_MODEL_TELEMETRY_ENABLED=false（设计 D10 启动基线）。
+ * XYZ_AGENT_SUBAGENT=1 + 剥离引擎原生嵌套标记），遥测关闭（旧实现实证）。
+ * 2026-09 起共享宿主 HOME——不再覆写 HOME：db/plugins/MCP 继承宿主 ~/.zcode/
+ * （引擎会话与 GUI 共写同一 SQLite，WAL 并发安全），HOME 依赖副作用（如 pnpm
+ * store 路径翻转）随之消失。凭据不在此层注入：CLI 形态 app-server 只从
+ * ~/.zcode/cli/config.json 读 provider（GUI 登录态在 v2/config.json），由
+ * launcherScript 指向的 fs 拦截 wrapper 把该读取重定向为「真实文件 + v2
+ * provider 注入」内存合并（同 id 时 v2 整条优先——见 appserver-launcher.ts）。
  */
-export function buildAppServerEnv(homeDir: string, baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+export function buildAppServerEnv(baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   return {
     ...buildNestedSpawnEnv(baseEnv),
     ZCODE_MODEL_TELEMETRY_ENABLED: "false",
-    HOME: homeDir,
   };
 }
 
@@ -142,6 +145,12 @@ export interface AppServerConnectionOptions {
   cwd: string;
   /** 完整子进程 env（buildAppServerEnv 产物或调用方自行组装）。 */
   env: NodeJS.ProcessEnv;
+  /**
+   * fs 拦截 wrapper 脚本路径（appserver-launcher.ts 落盘产物）。设置时 spawn 的
+   * script 换为本路径（cliPath 经 env ZCODE_ENG_CLI_PATH 传给 wrapper）——共享宿主
+   * HOME 形态的凭据供数机制；缺省 undefined = 直接 spawn cliPath（测试 fake 直连）。
+   */
+  launcherScript?: string;
   /**
    * stderr tee 落盘路径（append；引擎数据目录由 R4 注入，测试用 tmp 目录）。
    * 懒打开：首条 stderr 才建文件，无 stderr 的短命连接零文件；写失败静默降级
@@ -155,9 +164,10 @@ export interface AppServerConnectionOptions {
   /** 反向请求 handler 表（缺省 D9 常量表；测试注入故障 handler 用）。 */
   reverseHandlers?: Readonly<Record<string, (params: unknown) => unknown>>;
   /**
-   * [R4] 每代进程 spawn 成功后的同步回调（engine 写 pidfile / 采集 pid 的唯一时点）。
-   * 与 RunContext.onChildSpawned 无关：常驻进程不进宿主 spawnedChildren（D6——
-   * 其生命周期归引擎 dispose）。不抛保证：回调异常吞掉记 warn，不影响帧泵。
+   * [R4] 每代进程 spawn 成功后的同步回调。pidfile 机制删除后引擎侧不再传——现为
+   * 测试专有的代级观测面（采集 spawn 时序 / 子进程句柄）。与 RunContext.onChildSpawned
+   * 无关：常驻进程不进宿主 spawnedChildren（D6——其生命周期归引擎 dispose）。
+   * 不抛保证：回调异常吞掉记 warn，不影响帧泵。
    */
   onSpawned?: (child: ChildProcess) => void;
 }
@@ -192,6 +202,7 @@ export class AppServerConnection {
   private readonly requestTimeoutMs: number;
   private readonly reverseHandlers: Readonly<Record<string, (params: unknown) => unknown>>;
   private readonly onSpawned: ((child: ChildProcess) => void) | undefined;
+  private readonly launcherScript: string | undefined;
 
   /** 当前代子进程；null = 无活进程（未启动或已死，下次使用重建）。 */
   private child: ChildProcess | null = null;
@@ -217,6 +228,7 @@ export class AppServerConnection {
 
   constructor(opts: AppServerConnectionOptions) {
     this.cliPath = opts.cliPath;
+    this.launcherScript = opts.launcherScript;
     this.cwd = opts.cwd;
     this.env = opts.env;
     this.stderrLogPath = opts.stderrLogPath;
@@ -363,7 +375,8 @@ export class AppServerConnection {
     this.generation += 1;
     const gen = this.generation;
 
-    const child = spawn(this.nodeBin, [this.cliPath, "app-server", "--cwd", this.cwd], {
+    const script = this.launcherScript ?? this.cliPath;
+    const child = spawn(this.nodeBin, [script, "app-server", "--cwd", this.cwd], {
       env: this.env,
       stdio: ["pipe", "pipe", "pipe"],
     });

package/src/execution/engine/engines/zcode/constants.ts

@@ -1,14 +1,18 @@
 // src/execution/engine/engines/zcode/constants.ts
 //
 // ZcodeEngine 共享常量（P3）。独立成模块的原因：reader.ts 是双端复用的无状态模块
-// （设计 §3.3.7：runtime 侧也会 import），它需要的常量不能连带 launcher/preparer
-// 的模块级副作用（如 logger 初始化）一起加载——constants.ts 保持零 import 纯常量。
+// （设计 §3.3.7：runtime 侧也会 import），它需要的常量不能连带其他模块的模块级
+// 副作用（如 logger 初始化）一起加载——constants.ts 保持零 import 纯常量。
+//
+// 2026-09 重构（共享宿主 HOME）：删除 CLI spawn 降级链与 HOME 池化全部常量
+// （home-appserver 池/锁/pidfile/派生上限/凭据引导/probe 冒烟/漂移降级码）。
+// 引擎只走 app-server RPC，spawn env 不覆写 HOME（共享宿主 ~/.zcode/）。
 
 /** zcode 引擎的 registry key。 */
 export const ZCODE_ENGINE_ID = "zcode";
 
 /** zcode 适配器版本（handle.adapterVersion 数据源——golden 样本对齐排查锚点）。 */
-export const ZCODE_ADAPTER_VERSION = "1.0.0";
+export const ZCODE_ADAPTER_VERSION = "2.0.0";
 
 /**
  * zcode CLI 缺省路径（12.4MB node bundle，不在 PATH——2026-08-25 实测）。
@@ -18,23 +22,26 @@ export const ZCODE_CLI_DEFAULT_PATH = "/Applications/ZCode.app/Contents/Resource
 
 /**
  * 唯一凭据源 config（桌面端登录态，zsub V2_CONFIG_PATH 同构）。
- * 为什么绝不读 ~/.zcode/cli/config.json：它不在 ZCode GUI 管理面，可能残留历史
- * 验证配置（2026-08-25 事故：8/24 zsub 开发残留把默认模型劫持到失效 router 端点，
- * turn 0 即 401）；桌面端登录凭据落在 v2/config.json，是 zsub 生产验证过的凭据源。
+ * 为什么绝不读 ~/.zcode/cli/config.json 作为引擎侧凭据校验源：它不在 ZCode GUI
+ * 管理面，可能残留历史验证配置（2026-08-25 事故：8/24 zsub 开发残留把默认模型
+ * 劫持到失效 router 端点，turn 0 即 401）；桌面端登录凭据落在 v2/config.json，
+ * 是 zsub 生产验证过的凭据源。共享宿主 HOME 后引擎侧只读它做模型解析校验；
+ * app-server 进程侧 CLI 只认 ~/.zcode/cli/config.json（GUI 从不写该文件），由
+ * appserver-launcher 的 fs 拦截 wrapper 把对该文件的读取重定向为「真实文件 +
+ * v2 provider 注入」内存合并（同 id 时 v2 整条优先）——凭据实际供数仍以 v2 为
+ * 权威源，并非直接消费宿主 HOME 的原始 cli config。
  */
 export const ZCODE_V2_CONFIG_PATH_SUFFIX = [".zcode", "v2", "config.json"] as const;
 
-/** 池内 config.json 相对隔离 HOME 的位置（CLI 只读 $HOME/.zcode/cli/config.json）。 */
-export const ZCODE_POOL_CONFIG_SUFFIX = [".zcode", "cli", "config.json"] as const;
+/** zsub 同构的兜底缺省模型（v2 config 无 model.main 且 task 未指定时）。 */
+export const ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
 
 /**
- * 池内 db.sqlite 相对隔离 HOME 的位置（handle.sessionRef.dbPath 的值——相对池目录
- * 自描述，read 时经 resolvePoolDir + 该相对路径重定位，设计 §3.3.6）。
+ * 宿主 HOME 下 zcode 会话 db 的相对位置（共享 HOME 形态的 handle.sessionRef.dbPath
+ * 锚点——绝对路径 = join(os.homedir(), ...suffix)；runtime 读侧用它做精确白名单，
+ * 旧池时代 records 的相对 dbPath 仍按 poolKey 锚定兼容）。
  */
-export const ZCODE_POOL_DB_RELATIVE_PATH = ".zcode/cli/db/db.sqlite";
-
-/** zsub 同构的兜底缺省模型（v2 config 无 model.main 且 task 未指定时）。 */
-export const ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
+export const ZCODE_HOST_DB_SUFFIX = [".zcode", "cli", "db", "db.sqlite"] as const;
 
 /** 杀链 grace 窗口：SIGTERM 后等这么久再 SIGKILL（zsub 同构 5s；实测 SIGTERM→exit 仅 103ms）。 */
 export const ZCODE_KILL_GRACE_MS = 5_000;
@@ -44,7 +51,7 @@ export const ZCODE_ERROR_TAIL_CHARS = 2000;
 
 /**
  * [R2] app-server 控制面请求默认超时（ms）。依据：旧 zsw 实现 REQUEST_TIMEOUT_MS=15s
- * （60+ fake-server 用例 + 真机 e2e 验证值）；R5 probe 冒烟用独立更短预算，不走本值。
+ * （60+ fake-server 用例 + 真机 e2e 验证值）。
  */
 export const ZCODE_APPSERVER_REQUEST_TIMEOUT_MS = 15_000;
 
@@ -72,35 +79,70 @@ export const ZCODE_APPSERVER_TURN_READ_TIMEOUT_MS = 5_000;
 export const ZCODE_APPSERVER_TURN_CLOSE_TIMEOUT_MS = 1_500;
 
 /**
- * [R3] 一轮终态等待的缺省预算（ms）。终态双保险（turn.terminal 权威 + 收尾帧宽松
- * 匹配防洪堤）之后的最后一道：全漂移/进程假死时不挂死任务。R4 接线后任务级
- * timeout / abort 链可显式传入更贴任务的值。
+ * [R3 → superseded by P0-1] 旧「一轮终态等待」固定墙钟缺省值（ms）。**已被
+ * `ZCODE_TURN_IDLE_TIMEOUT_MS`（idle 主判定）+ `ZCODE_TURN_MAX_TIMEOUT_MS`
+ * （总上界兜底）两 timer 语义替换，session-channel 不再消费本值**——固定墙钟
+ * 「到点=不可推进」判定被 2026-09 T001 深诊击穿（21% 活跃任务被误杀，见设计
+ * timeout-zcode-turn-and-settled-watchdog.md §3.1/§4）。符号保留：audit/设计
+ * 文档（timeout-audit-2026-09.md 等）以本名记录事故成因，删除即产生悬空引用。
  */
 export const ZCODE_APPSERVER_TURN_DEFAULT_TIMEOUT_MS = 300_000;
 
 // ============================================================
-// [R4] app-server 常驻 HOME（D7）/ abort 链（D3）/ 孤儿自愈（D6③）
+// [P0-1 U1] turn 等待两 timer（idle 主判定 + 总上界回收兜底）
+// 设计权威源：docs/design/timeout-zcode-turn-and-settled-watchdog.md §6 D1/D2
 // ============================================================
 
+/** turn idle 主判定的 env 覆盖通道（>0 覆盖、≤0 关闭、非法值 warn+回落默认）。 */
+export const ZCODE_TURN_IDLE_TIMEOUT_ENV = "XYZ_ZCODE_TURN_IDLE_TIMEOUT_MS";
+
+/** turn 总上界的 env 覆盖通道（语义同上；0=关闭后 chatty-wedge 无自动回收）。 */
+export const ZCODE_TURN_MAX_TIMEOUT_ENV = "XYZ_ZCODE_TURN_MAX_TIMEOUT_MS";
+
 /**
- * [R4 D7] 常驻 HOME 的池 key（固定名）。锚定不变量 poolDir == HOME == db 所在目录：
- * HOME = resolvePoolDir(engineDataDir, 'zcode', 'home-appserver')，SQLite 落
- * HOME/.zcode/cli/db/db.sqlite，journal 同落该池目录。锁被活宿主持有时派生
- * `home-appserver-2`… 后缀目录，handle.poolKey 记实际目录名。
+ * [P0-1 D1] turn idle 主判定缺省阈值（ms）：该 turn 任何事件到达刷新计时，连续
+ * 静默达此值判「执行已不可推进」。活跃事件流零误杀（ADR-0047 逆否面）。默认
+ * 30min 为先验值，⛔P-Z1 门（事件流 inter-event gap 分布）标定前用此默认。
  */
-export const ZCODE_APPSERVER_POOL_KEY = "home-appserver";
+export const ZCODE_TURN_IDLE_TIMEOUT_MS = 1_800_000;
 
-/** [R4 D7] 目录锁文件名（HOME 内；O_EXCL 创建，内容 {pid}=持锁宿主进程 pid）。 */
-export const ZCODE_APPSERVER_LOCKFILE_NAME = "lockfile";
+/**
+ * [P0-1 D1] turn 总上界缺省值（ms）：从 openTurn 挂载起固定不刷新，兜 idle 覆盖
+ * 不了的 chatty-wedge（事件持续但终态永不到达）。对超上界的合法极长任务是显式
+ * 接受的残余误杀面（env 可调/可关 + 错误文案附自救指引）。默认 60min 为先验值
+ * （T001 34 任务最长 541s，先验远离 6.6×），⛔P-Z0 门（任务总时长分布）标定前
+ * 用此默认。
+ */
+export const ZCODE_TURN_MAX_TIMEOUT_MS = 3_600_000;
 
-/** [R4 D6③/D7] app-server 进程 pidfile 文件名（HOME 内；与 lockfile.pid 严格分离）。 */
-export const ZCODE_APPSERVER_PIDFILE_NAME = "appserver.pid";
+/** `parseZcodeTurnTimeoutEnv` 的解析结果（可判别联合——valid 分支 ms 必有）。 */
+export type ZcodeTurnTimeoutEnvParse =
+  | { state: "unset" }
+  | { state: "valid"; ms: number }
+  | { state: "invalid" };
 
-/** [R4 D7] 目录锁心跳间隔（ms）：仅刷新 lockfile mtime，不参与活持有否决。 */
-export const ZCODE_APPSERVER_LOCK_HEARTBEAT_MS = 30_000;
+/**
+ * 解析 turn 阈值 env 原始值（空串视同未设置，对齐 lifecycle-manager 先例的
+ * `if (!raw)` 口径）。**与 `XYZ_SUBAGENT_IDLE_TIMEOUT_MS` 先例的刻意分歧（设计
+ * D2/r3 SG-5 显式登记）**：先例 ≤0=非法回落且禁用后不认 env；本通道 ≤0=显式
+ * 关闭该 timer（规则 19 的 opt-out 出路），非法（非数字）才回落默认——调用方
+ * 必须对 invalid 与 ≤0 关闭分别 warn 留痕（生效行为可见，A10① 断言依据）。
+ */
+export function parseZcodeTurnTimeoutEnv(
+  raw: string | undefined
+): ZcodeTurnTimeoutEnvParse {
+  if (raw === undefined || raw === "") return { state: "unset" };
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return { state: "invalid" };
+  return { state: "valid", ms: parsed };
+}
 
-/** [R4 D7] 派生目录后缀上限（home-appserver-2 … -N）——极端并发场景防无限循环。 */
-export const ZCODE_APPSERVER_MAX_DERIVED_HOMES = 8;
+/**
+ * 共享宿主 HOME 语义下的 journal 分组 key（与 pi 引擎 PI_POOL_KEY='shared' 同构）：
+ * journal 落 engineDataDir/engines/zcode/shared/journal-<taskId>.jsonl。无隔离池、
+ * 无派生目录——key 是固定字面量，仅作 pool-manager 通用契约的分组锚点。
+ */
+export const ZCODE_SHARED_POOL_KEY = "shared";
 
 /**
  * [R4 D3] abort 链第一级：session/stop 的控制面超时（ms）。stop 失败/超时即落
@@ -114,59 +156,21 @@ export const ZCODE_APPSERVER_STOP_TIMEOUT_MS = 3_000;
  */
 export const ZCODE_APPSERVER_ABORT_GRACE_MS = 3_000;
 
-/** [R4 D6③] 孤儿回收的 SIGTERM→SIGKILL grace 窗口（ms）。 */
-export const ZCODE_APPSERVER_PIDFILE_GRACE_MS = 2_000;
-
-/**
- * [R4/R5] 执行模式定向 env（appserver | spawn）。定向时不探不降；缺省走 app-server
- * （R5 降级链在缺省路径插 probe 门控）。spawn 降级路径（D2 兜底）继续用
- * home-<provider>-<model> 池。
- */
-export const ZCODE_MODE_ENV_VAR = "XYZ_ZCODE_MODE";
-
 /**
  * [R4] app-server 内部错误码中「模型配置缺失」的归类判据（A.3：-32603 内部错误族，
  * 消息含 "Model config is missing"——错误规格表第 2 行：报 engine_credential_missing）。
  */
 export const ZCODE_APPSERVER_ERR_MODEL_CONFIG_MISSING = -32603;
 
-// ============================================================
-// [R5] 降级链（D2）/ probe 冒烟（D8）
-// ============================================================
-
-/**
- * [R5 D8] 协议冒烟探针的总预算（ms）：独立短命连接上 create 探针会话 → close →
- * shutdown 的全部时间窗。不发模型请求（无 session/send）、不产生费用。超预算按
- * 探针失败处理（错误规格表末行：结论 failed → 降级 spawn）。
- */
-export const ZCODE_APPSERVER_PROBE_BUDGET_MS = 10_000;
-
-/**
- * [R5 D2] 漂移类 RPC 错误码（错误规格表第 1 行：-32601 方法不存在 / -32602 参数
- * 变形）。运行中命中任一 → 归档 protocol-drift：首任务降级 spawn 重跑一次 + 后续
- * 任务直走 spawn（降级标志内存化，进程重启后重探重建）。-32004/-32010/-32603 不在
- * 此列（任务失败上报 / 凭据缺失归类，均不降级）。
- */
-const RPC_METHOD_NOT_FOUND = -32601;
-const RPC_INVALID_PARAMS = -32602;
-export const ZCODE_APPSERVER_DRIFT_RPC_CODES = [RPC_METHOD_NOT_FOUND, RPC_INVALID_PARAMS] as const;
-
 /**
  * [R5] app-server 内部错误码「会话忙」：send 时该会话已有轮在跑（busy 不排队不打断）。
  * 单会话一任务是结构保证，运行中命中即 bug（错误文案引导上报 sessionId 与 state 流水）。
  */
 export const ZCODE_APPSERVER_ERR_BUSY_SESSION = -32010;
 
-/**
- * [R5 D8] 探针连接的 env 标记：探针用独立短命连接（不污染主连接），但 env 与主连接
- * 同源（同一常驻 HOME）。此标记供 fake/诊断侧区分「探针进程」与「常驻进程」（测试
- * 断言探针帧序、故障注入只命中探针或只命中主连接的判据）。
- */
-export const ZCODE_APPSERVER_PROBE_CONN_ENV = "ZCODE_APPSERVER_PROBE_CONN";
-
 /**
  * [R5] 崩溃收割确认的兜底窗口（ms）：killChain 在 `exit` 事件 resolve，而连接
  * finalize（onClose → 在途 turn 崩溃收割）挂 `close` 事件——channel 退订前等 onClose
- * 触发，本窗口兜底防 `close` 永不到达时 dispose/teardown 挂死。
+ * 触发，本窗口兜底防 `close` 永不到达时 dispose 挂死。
  */
 export const ZCODE_APPSERVER_HARVEST_GRACE_MS = 1_000;

package/src/execution/engine/engines/zcode/golden-sample.ts

@@ -1,52 +1,14 @@
 // src/execution/engine/engines/zcode/golden-sample.ts
 //
-// golden 语料内嵌副本（双通道并存，R3 扩充）：
+// golden 语料内嵌副本（2026-09 收缩：CLI spawn 链删除后只剩 app-server 通道语料——
+// spawn 单 JSON 样本（ZCODE_GOLDEN_STDOUT）随 probe 干跑/spawn 回归一并删除）：
 //
-//   ① spawn 单 JSON（D7）：probe「干跑校验」的内嵌 golden 样本——zcode 无官方契约，
-//      探针必须做已知样本回归（对 embed 样本跑 parser，格式漂移在入口拦截而非运行中
-//      静默挂死）。来源：2026-08-25 验收前置门真机实录（zcode 0.16.5），完整原文与采集
-//      元数据见 __tests__/__fixtures__/zcode-golden-spawn.json。为什么不直接读 fixture
-//      文件：probe 在生产运行（npm 包安装形态）也要可用，__tests__ 不在稳定交付面内
-//      ——内嵌副本以代码为交付载体。spawn 降级路径（设计 D2 保留）持续消费本语料
-//      （zcode-engine probe 干跑 + conformance spawn 回归），故 R3 帧序列语料落地为
-//      并存新增而非删除替换——漂移防御的主力语料已切换到 ②（登记于 impl-plan 偏差表）。
-//
-//   ② app-server NDJSON 帧序列（R3，D8-②）：常驻通道的 golden 帧序列语料，四类样本
-//      （create 应答 / 推送流 / 终态帧 / read 应答，附录 A.2 任务生命周期帧序）。
-//      来源：按 A.2 协议权威 + 旧 zsw 实现真机抓包形态合成（非实录，fixture _meta
-//      如实标注）；真机冒烟后替换。双副本 diff 机制沿用 ① 的先例：fixture
-//      __tests__/__fixtures__/zcode-golden-appserver.json 是采集 SSOT，此处为运行时
-//      副本，更新样本需同步改两处（session-channel 测试 diff 校验；R6 conformance
-//      迁移后由 golden 回放层接管）。
-
-/** [①spawn] 实录 stdout 原文（单 JSON：sessionId/traceId/turnId/response/usage/eventCount/projection）。 */
-export const ZCODE_GOLDEN_STDOUT = `{
-  "sessionId": "sess_35852a0f-1302-4e20-9e48-87f47527abe3",
-  "traceId": "9fffaebd-749e-468b-af3f-2a89e3347785",
-  "turnId": "turn_99879260-1c9b-4e97-afe1-c2e7abeaf5b9",
-  "response": "ok",
-  "usage": {
-    "source": "provider",
-    "modelRequestCount": 1,
-    "inputTokens": 12599,
-    "outputTokens": 17,
-    "totalTokens": 12616,
-    "cacheReadTokens": 512,
-    "cacheWriteTokens": 0,
-    "reasoningTokens": 0,
-    "webFetchRequests": 0,
-    "webSearchRequests": 0
-  },
-  "eventCount": 17,
-  "projection": {
-    "status": "idle",
-    "turnCount": 1,
-    "totalTokenCount": 12616,
-    "contextUsed": 12616,
-    "contextWindow": 1000000
-  }
-}
-`;
+//   app-server NDJSON 帧序列（R3，D8-②）：常驻通道的 golden 帧序列语料，四类样本
+//   （create 应答 / 推送流 / 终态帧 / read 应答，附录 A.2 任务生命周期帧序）。
+//   来源：按 A.2 协议权威 + 旧 zsw 实现真机抓包形态合成（非实录，fixture _meta
+//   如实标注）；真机冒烟后替换。fixture __tests__/__fixtures__/zcode-golden-appserver.json
+//   是采集 SSOT，此处为运行时副本，更新样本需同步改两处（session-channel 测试
+//   diff 校验）。
 
 // ============================================================
 // [②app-server] NDJSON 帧序列语料（R3，附录 A.2 帧序逐字）