@zhushanwen/zcode-subagent-cli 0.1.1

package/dist/main.cjs

@@ -0,0 +1,2700 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/main.ts
+var import_subagent_engine_sdk13 = require("@zhushanwen/subagent-engine-sdk");
+
+// src/server.ts
+var import_subagent_engine_sdk12 = require("@zhushanwen/subagent-engine-sdk");
+
+// src/constants.ts
+var ZCODE_ENGINE_ID = "zcode";
+var ZCODE_ADAPTER_VERSION = "2.0.0";
+var ZCODE_CLI_DEFAULT_PATH = "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
+var ZCODE_V2_CONFIG_PATH_SUFFIX = [".zcode", "v2", "config.json"];
+var ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
+var ZCODE_HOST_DB_SUFFIX = [".zcode", "cli", "db", "db.sqlite"];
+var ZCODE_KILL_GRACE_MS = 5e3;
+var ZCODE_ERROR_TAIL_CHARS = 2e3;
+var ZCODE_APPSERVER_REQUEST_TIMEOUT_MS = 15e3;
+var ZCODE_APPSERVER_STDERR_TAIL_CHARS = 400;
+var ZCODE_APPSERVER_STDERR_TAIL_BUFFER_CHARS = 2048;
+var ZCODE_APPSERVER_TURN_READ_TIMEOUT_MS = 5e3;
+var ZCODE_APPSERVER_TURN_CLOSE_TIMEOUT_MS = 1500;
+var ZCODE_TURN_IDLE_TIMEOUT_ENV = "XYZ_ZCODE_TURN_IDLE_TIMEOUT_MS";
+var ZCODE_TURN_MAX_TIMEOUT_ENV = "XYZ_ZCODE_TURN_MAX_TIMEOUT_MS";
+var ZCODE_TURN_IDLE_TIMEOUT_MS = 18e5;
+var ZCODE_TURN_MAX_TIMEOUT_MS = 36e5;
+function parseZcodeTurnTimeoutEnv(raw) {
+  if (raw === void 0 || raw === "") return { state: "unset" };
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return { state: "invalid" };
+  return { state: "valid", ms: parsed };
+}
+var ZCODE_SHARED_POOL_KEY = "shared";
+var ZCODE_APPSERVER_STOP_TIMEOUT_MS = 3e3;
+var ZCODE_APPSERVER_ABORT_GRACE_MS = 3e3;
+var ZCODE_APPSERVER_ERR_MODEL_CONFIG_MISSING = -32603;
+var ZCODE_APPSERVER_ERR_BUSY_SESSION = -32010;
+var ZCODE_APPSERVER_HARVEST_GRACE_MS = 1e3;
+
+// src/registration.ts
+var import_subagent_engine_sdk10 = require("@zhushanwen/subagent-engine-sdk");
+
+// src/zcode-engine.ts
+var fs5 = __toESM(require("fs"), 1);
+var path4 = __toESM(require("path"), 1);
+var import_subagent_engine_sdk8 = require("@zhushanwen/subagent-engine-sdk");
+var import_subagent_engine_sdk9 = require("@zhushanwen/subagent-engine-sdk");
+
+// src/journal-io.ts
+var import_subagent_engine_sdk = require("@zhushanwen/subagent-engine-sdk");
+var import_subagent_engine_sdk2 = require("@zhushanwen/subagent-engine-sdk");
+function replayJournalToSessionView(handle, engineId) {
+  const journalPath = handle.data.journalPath;
+  if (journalPath === void 0) return void 0;
+  const events = (0, import_subagent_engine_sdk2.replayJournal)(journalPath);
+  if (events.length === 0) return void 0;
+  return (0, import_subagent_engine_sdk2.eventsToSessionView)(events, engineId, (0, import_subagent_engine_sdk2.sessionIdFromHandle)(handle.data));
+}
+
+// src/db-path.ts
+var os = __toESM(require("os"), 1);
+var path = __toESM(require("path"), 1);
+function zcodeSessionDbPath(engineDataDir) {
+  return path.join(engineDataDir, "engines", "zcode", "session-db", "db.sqlite");
+}
+function hostZcodeDbPath() {
+  return path.join(os.homedir(), ...ZCODE_HOST_DB_SUFFIX);
+}
+function zcodeDbPathAllowlist(dataDir) {
+  return [zcodeSessionDbPath(dataDir), hostZcodeDbPath()];
+}
+
+// src/parser.ts
+function finiteOr(v, fallback) {
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+function mapZcodeUsage(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const r = raw;
+  if (r.inputTokens === void 0 && r.outputTokens === void 0) return void 0;
+  return {
+    input: finiteOr(r.inputTokens, 0),
+    output: finiteOr(r.outputTokens, 0),
+    cacheRead: finiteOr(r.cacheReadTokens, 0),
+    cacheWrite: finiteOr(r.cacheWriteTokens, 0)
+  };
+}
+function mapZcodeOutcomeUsage(rawUsage, projection) {
+  const base = mapZcodeUsage(rawUsage);
+  if (base === void 0) return void 0;
+  const p = typeof projection === "object" && projection !== null ? projection : {};
+  const r = typeof rawUsage === "object" && rawUsage !== null ? rawUsage : {};
+  const contextTokens = firstFinite(p["contextUsed"], r.totalTokens, 0);
+  const turns = firstFinite(p["turnCount"], 1);
+  return { ...base, cost: 0, contextTokens, turns };
+}
+function firstFinite(...vals) {
+  for (const v of vals) {
+    const n = typeof v === "number" ? v : Number(v);
+    if (Number.isFinite(n)) return n;
+  }
+  return 0;
+}
+function synthesizeCoarseEvents(response, usage) {
+  return [
+    // usage 给不出完整形状时显式缺省整个字段，不给残缺对象（不变量 2）
+    { type: "message_end", ...usage !== void 0 ? { usage } : {} },
+    { type: "turn_end" }
+  ];
+}
+
+// src/preparer.ts
+var fs = __toESM(require("fs"), 1);
+var os2 = __toESM(require("os"), 1);
+var path2 = __toESM(require("path"), 1);
+var ZcodePrepareError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`[${code}] ${message}`);
+    this.name = "ZcodePrepareError";
+    this.code = code;
+  }
+};
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isProviderEntry(v) {
+  return isRecord(v);
+}
+function readSourceConfig(absPath) {
+  const empty = { providers: /* @__PURE__ */ new Map() };
+  let raw;
+  try {
+    raw = fs.readFileSync(absPath, "utf8");
+  } catch {
+    return empty;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return empty;
+  }
+  if (!isRecord(parsed)) return empty;
+  const conf = { providers: /* @__PURE__ */ new Map() };
+  const provider = parsed["provider"];
+  if (isRecord(provider)) {
+    for (const [id, entry] of Object.entries(provider)) {
+      if (isProviderEntry(entry)) conf.providers.set(id, entry);
+    }
+  }
+  return conf;
+}
+function modelShort(ref) {
+  return ref.slice(ref.lastIndexOf("/") + 1);
+}
+function providerOf(ref) {
+  return ref.slice(0, ref.lastIndexOf("/"));
+}
+function splitZcodeModelRef(modelRef) {
+  return { providerId: providerOf(modelRef), modelId: modelShort(modelRef) };
+}
+function hasApiKey(entry) {
+  const key = entry.options?.apiKey;
+  return typeof key === "string" && key !== "";
+}
+function defaultV2ConfigPath() {
+  return path2.join(os2.homedir(), ...ZCODE_V2_CONFIG_PATH_SUFFIX);
+}
+var DEFAULT_PROVIDER_ID = "builtin:bigmodel-coding-plan";
+function defaultProviderForShortName(merged, withKey) {
+  if (merged.has(DEFAULT_PROVIDER_ID)) return DEFAULT_PROVIDER_ID;
+  return withKey[0][0];
+}
+function resolveZcodeModelRef(requested, sources) {
+  const v2 = readSourceConfig(sources?.v2ConfigPath ?? defaultV2ConfigPath());
+  const merged = v2.providers;
+  const withKey = [...merged.entries()].filter(([, e]) => hasApiKey(e));
+  const wanted = requested?.trim() || void 0;
+  const target = wanted ?? ZCODE_FALLBACK_DEFAULT_MODEL;
+  if (withKey.length === 0) {
+    const hint = wanted ? `model="${wanted}" \u4E0D\u80FD\u6821\u9A8C` : `\u9ED8\u8BA4\u6A21\u578B "${target}" \u4E0D\u80FD\u6821\u9A8C`;
+    throw new ZcodePrepareError(
+      "engine_credential_missing",
+      `zcode \u5F15\u64CE\u627E\u4E0D\u5230\u4EFB\u4F55\u5E26 apiKey \u7684 provider\uFF08${hint}\uFF09\u3002\u5DF2\u8BFB\u6E90\uFF1A${sources?.v2ConfigPath ?? defaultV2ConfigPath()}\u3002\u6062\u590D\u6307\u5F15\uFF1A\u5148\u5728 ZCode \u684C\u9762\u7AEF\u767B\u5F55\u5E76\u914D\u7F6E provider\uFF08v2 config \u5185\u5B58\u5728\u542B apiKey \u7684\u6761\u76EE\uFF09\u540E\u91CD\u8BD5\uFF1B\u51ED\u636E\u914D\u7F6E\u8BF4\u660E\u89C1 docs/research/agent-engine-zcode.md\u3002`
+    );
+  }
+  const provider = target.includes("/") ? providerOf(target) : defaultProviderForShortName(merged, withKey);
+  const short = modelShort(target);
+  const entry = merged.get(provider);
+  if (!entry) {
+    const known = withKey.map(([id]) => id).join(", ");
+    throw new ZcodePrepareError(
+      "model_not_available",
+      `\u672A\u77E5 provider "${provider}"\uFF08\u5E26\u51ED\u636E\u7684 provider: ${known}\uFF09\u3002\u6062\u590D\u6307\u5F15\uFF1A\u6539\u7528\u4E0A\u8FF0 provider \u4E4B\u4E00\uFF08\u5168\u540D provider/model\uFF09\uFF0C\u6216\u5148\u5728 ZCode \u684C\u9762\u7AEF\u914D\u7F6E\u8BE5 provider \u540E\u91CD\u8BD5\u3002`
+    );
+  }
+  if (!hasApiKey(entry)) {
+    throw new ZcodePrepareError(
+      "engine_credential_missing",
+      `provider "${provider}" \u5B58\u5728\u4F46\u672A\u914D\u7F6E apiKey\u3002\u6062\u590D\u6307\u5F15\uFF1A\u5728 ZCode \u684C\u9762\u7AEF\u4E3A\u8BE5 provider \u767B\u5F55\u914D\u7F6E\u51ED\u636E\uFF0C\u6216\u6539\u7528\u5DF2\u914D\u51ED\u636E\u7684 provider\uFF08${withKey.map(([id]) => id).join(", ")}\uFF09\u540E\u91CD\u8BD5\u3002`
+    );
+  }
+  const models = Object.keys(entry.models ?? {});
+  if (models.length > 0 && !models.includes(short)) {
+    throw new ZcodePrepareError(
+      "model_not_available",
+      `\u672A\u77E5\u6A21\u578B "${short}"\uFF08provider ${provider} \u4E0B\u53EF\u7528: ${models.join(", ")}\uFF09\u3002\u6062\u590D\u6307\u5F15\uFF1A\u6539\u7528\u8BE5 provider \u4E0B\u7684\u6A21\u578B\uFF0C\u6216\u5148\u5728 ZCode \u684C\u9762\u7AEF\u542F\u7528\u76EE\u6807\u6A21\u578B\u540E\u91CD\u8BD5\u3002`
+    );
+  }
+  return `${provider}/${short}`;
+}
+function listZcodeModels(sources) {
+  const v2 = readSourceConfig(sources?.v2ConfigPath ?? defaultV2ConfigPath());
+  const out = [];
+  for (const [pid, entry] of v2.providers) {
+    if (!hasApiKey(entry)) continue;
+    const providerName = typeof entry["name"] === "string" && entry["name"].trim() !== "" ? entry["name"].trim() : void 0;
+    const models = Object.keys(entry.models ?? {});
+    for (const model of models) {
+      out.push({
+        id: `${pid}/${model}`,
+        ...providerName !== void 0 ? { name: `${providerName} \xB7 ${model}` } : {}
+      });
+    }
+  }
+  return out;
+}
+
+// src/appserver-launcher.ts
+var fs2 = __toESM(require("fs"), 1);
+var path3 = __toESM(require("path"), 1);
+
+// src/error-message.ts
+var import_subagent_engine_sdk3 = require("@zhushanwen/subagent-engine-sdk");
+
+// src/appserver-launcher.ts
+var ZCODE_APPSERVER_LAUNCHER_NAME = "appserver-launcher.cjs";
+var APPSERVER_LAUNCHER_SOURCE = `'use strict';
+// zcode app-server fs \u62E6\u622A wrapper\uFF08\u7531 zcode-subagent-cli appserver-launcher \u843D\u76D8\u751F\u6210\uFF09
+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');
+// \u4E0E constants.ts ZCODE_FALLBACK_DEFAULT_MODEL \u53CC\u6E90\uFF08\u5185\u5D4C\u5B57\u7B26\u4E32\u65E0\u6CD5 import\uFF09\u2014\u2014\u6539\u90A3\u8FB9\u987B\u540C\u6B65\u6B64\u5904
+const FALLBACK_MODEL_MAIN = 'builtin:bigmodel-coding-plan/GLM-5.3';
+
+// \u5408\u5E76\u5F62\u6001\uFF1A\u771F\u5B9E cli config \u539F\u6837\uFF08model/plugins/mcp/subagents \u7B49 worker \u7EE7\u627F\u9762\u4E0D\u53D8\uFF09
+// + v2 \u7684 provider \u5B57\u5178\u6CE8\u5165\uFF0C\u540C id \u65F6 v2 \u6761\u76EE\u6574\u6761\u4F18\u5148\u2014\u2014GUI \u76F4\u4F20 modelConfig \u65F6
+// v2 \u5373\u6743\u5A01\u6E90\uFF08\u8FDB\u7A0B\u5916\u7B49\u4EF7\u590D\u523B\uFF09\uFF1Bcli config \u4E0D\u5728 GUI \u7BA1\u7406\u9762\u3001\u53EF\u80FD\u6B8B\u7559\u5386\u53F2\u9A8C\u8BC1
+// \u914D\u7F6E\uFF082026-08-25 \u4E8B\u6545\uFF1A\u6B8B\u7559\u65E7 key \u538B\u8FC7\u65B0\u51ED\u636E\u81F4 turn 0 401\uFF09\uFF0C\u6545\u4E0D\u53D6 real \u4F18\u5148\u3002
+// \u8FD4\u56DE null = \u65E0\u53EF\u6CE8\u5165\u51ED\u636E\uFF08v2 \u65E0 provider \u6761\u76EE\uFF09\u2014\u2014\u4E0D patch\uFF0C\u8BA9\u539F\u751F\u62A5\u9519\u900F\u51FA\u3002
+// \u8BFB\u6E90\u7ECF readOrig \u95F4\u63A5\u53D6\uFF1Apatch \u524D\u9996\u8C03 = fs.readFileSync \u672C\u4F53\uFF1Bpatch \u540E = \u539F\u51FD\u6570
+// \uFF08\u9632 patch \u540E\u7684\u9012\u5F52\u81EA\u8C03\u7528\uFF09\u3002
+function injectedConfigText() {
+  const readOrig = fs.__origReadFileSync || fs.readFileSync;
+  let real = {};
+  try { real = JSON.parse(readOrig(CONFIG_PATH, 'utf8')); } catch { /* \u65E0/\u635F\u574F \u2192 \u7A7A */ }
+  let v2 = {};
+  try { v2 = JSON.parse(readOrig(V2_PATH, 'utf8')); }
+  catch (err) {
+    // ENOENT = \u684C\u9762\u7AEF\u672A\u767B\u5F55\uFF08\u6B63\u5E38 no-patch\uFF0C\u9759\u9ED8\uFF09\uFF1B\u5176\u4ED6\u5931\u8D25\uFF08JSON \u635F\u574F/\u6743\u9650\uFF09
+    // \u51FA\u58F0\u2014\u2014\u5426\u5219\u6392\u969C\u4F1A\u88AB\u539F\u751F\u300C\u8BF7\u767B\u5F55\u300D\u62A5\u9519\u8BEF\u5BFC\uFF0C\u4E0E\u771F\u56E0\uFF08\u6587\u4EF6\u635F\u574F\uFF09\u4E0D\u7B26
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write('[zcode-launcher] v2 config \u8BFB\u53D6\u5931\u8D25(' + ((err && err.code) || (err && err.message) || 'unknown') + '): ' + V2_PATH + '\u2014\u2014\u51ED\u636E\u6CE8\u5165\u672A\u751F\u6548\\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 \u672A\u8BBE\u7F6E\uFF0C\u65E0\u6CD5\u542F\u52A8 app-server\uFF08\u8BE5 env \u7531\u5F15\u64CE\u81EA\u52A8\u8BBE\u7F6E\uFF1B\u624B\u5DE5\u8FD0\u884C wrapper \u9700\u663E\u5F0F\u4F20\u5165\uFF09\\n');
+  process.exit(2);
+}
+
+const text = injectedConfigText();
+if (text !== null) {
+  // encoding \u5F52\u4E00\uFF08Node \u522B\u540D\u9762\uFF09\uFF1A'utf8'/'utf-8'/\u5927\u5C0F\u5199\u53D8\u4F53\u7EDF\u4E00\u6309 string \u8FD4\u56DE\u2014\u2014
+  // \u771F\u5B9E bundle \u7684 config \u8BFB\u53D6\u6070\u7528 'utf-8' \u5F62\u6001\uFF0C\u4EC5\u5339\u914D 'utf8' \u4F1A\u9519\u56DE Buffer
+  // \uFF08\u5F53\u4E0B\u6E38\u4E0D\u53EA JSON.parse \u800C\u505A\u5B57\u7B26\u4E32\u8FD0\u7B97\u65F6\u5373 TypeError\uFF09
+  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 \u62E6\u622A\uFF1A\u771F\u5B9E bundle \u7684\u7528\u6237 config \u8BFB\u53D6\uFF08loadFileConfig\uFF09\u4EE5 existsSync
+  // \u4E3A\u77ED\u8DEF\u95E8\u2014\u2014\u6587\u4EF6\u4E0D\u5B58\u5728\u65F6\u8FD4\u56DE\u7A7A config \u4E14 readFileSync \u4E0D\u88AB\u8C03\u7528\uFF0CGUI-only
+  // \u767B\u5F55\u5BBF\u4E3B\uFF08cli/config.json \u4ECE\u672A\u88AB CLI \u4FA7\u5199\u8FC7\uFF09\u4E0A\u6CE8\u5165\u53EA\u6302\u5728\u8BFB\u53D6\u9762 = \u4E0D\u53EF\u89C1
+  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);
+  };
+}
+
+// \u4EE5\u539F argv \u5F62\u6001\u542F\u52A8 zcode.cjs\uFF08argv[0]=node, argv[1]=\u672C wrapper\uFF0Cargv[2]=app-server\u2014\u2014
+// zcode.cjs \u7684 includes('app-server') \u5224\u5B9A\u4E0D\u53D7\u5F71\u54CD\uFF09\u3002import() \u517C\u5BB9 CJS/ESM \u5165\u53E3\u3002
+import(CLI_PATH).catch((err) => {
+  process.stderr.write('[zcode-launcher] zcode.cjs \u52A0\u8F7D\u5931\u8D25: ' + (err && err.message || err) + '\\n');
+  process.exit(3);
+});
+`;
+function ensureAppServerLauncher(engineDataDir) {
+  const dir = path3.join(engineDataDir, "engines", "zcode");
+  const file = path3.join(dir, ZCODE_APPSERVER_LAUNCHER_NAME);
+  const existing = fs2.existsSync(file) && fs2.statSync(file).isFile() ? fs2.readFileSync(file, "utf8") : void 0;
+  if (existing === APPSERVER_LAUNCHER_SOURCE) return file;
+  try {
+    fs2.mkdirSync(dir, { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs2.writeFileSync(tmp, APPSERVER_LAUNCHER_SOURCE);
+    fs2.renameSync(tmp, file);
+  } catch (err) {
+    const reason = (0, import_subagent_engine_sdk3.toErrorMessage)(err);
+    throw new Error(
+      `zcode app-server launcher \u843D\u76D8\u5931\u8D25: ${file}\uFF08${reason}\uFF09\u3002\u6062\u590D\uFF1A\u68C0\u67E5\u5F15\u64CE\u6570\u636E\u76EE\u5F55 \u5199\u6743\u9650\u4E0E\u78C1\u76D8\u7A7A\u95F4\uFF08engineDataDir \u7531\u5BBF\u4E3B\u4F20\u5165\uFF0C\u8DEF\u5F84\u89C1\u4E0A\uFF09\u540E\u91CD\u8BD5\u3002`
+    );
+  }
+  return file;
+}
+
+// src/reader.ts
+var fs3 = __toESM(require("fs"), 1);
+var ZcodeReaderError = class extends Error {
+  code;
+  /** 原始失败细节（缺文件/表漂移/运行时不支持）。 */
+  detail;
+  constructor(detail, hint) {
+    super(
+      `[engine_session_read_failed] zcode \u539F\u751F session \u8BFB\u53D6\u5931\u8D25\uFF1A${detail}\u3002` + (hint ?? "\u8C03\u7528\u65B9\u5E94\u964D\u7EA7\u5230\u7B2C\u2461\u7EA7\uFF08\u5BBF\u4E3B event journal\uFF09\u6216\u7B2C\u2462\u7EA7\uFF08outcome-only\uFF09\u3002")
+    );
+    this.name = "ZcodeReaderError";
+    this.code = "engine_session_read_failed";
+    this.detail = detail;
+  }
+};
+function parseJsonField(raw, ctx) {
+  try {
+    const v = JSON.parse(raw);
+    return typeof v === "object" && v !== null && !Array.isArray(v) ? v : void 0;
+  } catch (err) {
+    throw new ZcodeReaderError(
+      `${ctx} \u884C data \u4E0D\u662F\u5408\u6CD5 JSON\uFF08${err instanceof Error ? err.message : String(err)}\uFF09`,
+      "db \u5185\u5BB9\u635F\u574F\u6216\u7248\u672C\u4E0D\u517C\u5BB9\u2014\u2014\u8C03\u7528\u65B9\u5E94\u964D\u7EA7\u5230\u7B2C\u2461\u7EA7\uFF08\u5BBF\u4E3B event journal\uFF09\u3002"
+    );
+  }
+}
+function finiteOr2(v, fallback) {
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+function usageFromStepFinish(part) {
+  const tokens = part.tokens;
+  if (typeof tokens !== "object" || tokens === null) return void 0;
+  const t = tokens;
+  const cache = typeof t.cache === "object" && t.cache !== null ? t.cache : {};
+  if (t.input === void 0 && t.output === void 0) return void 0;
+  return {
+    input: finiteOr2(t.input, 0),
+    output: finiteOr2(t.output, 0),
+    cacheRead: finiteOr2(cache.read, 0),
+    cacheWrite: finiteOr2(cache.write, 0)
+  };
+}
+function toolFromPart(part) {
+  const toolName = typeof part.tool === "string" ? part.tool : "unknown";
+  let state;
+  if (typeof part.state === "string") {
+    try {
+      const v = JSON.parse(part.state);
+      state = typeof v === "object" && v !== null ? v : void 0;
+    } catch {
+      state = void 0;
+    }
+  }
+  const status = typeof state?.status === "string" ? state.status : "unknown";
+  const output = state?.output;
+  return {
+    toolName,
+    ...state?.input !== void 0 ? { args: state.input } : {},
+    // 输出形态（实测）：string（内容）或 object（结构化）——分别映射到 pi ToolCallResult
+    // 的 content[] / details，不发明第二形状
+    ...typeof output === "string" ? { result: { content: [output] } } : {},
+    ...typeof output === "object" && output !== null ? { result: { details: output } } : {},
+    ...status !== "completed" ? { isError: true } : {}
+  };
+}
+var TotalsAcc = class {
+  input = 0;
+  output = 0;
+  cacheRead = 0;
+  cacheWrite = 0;
+  cost = 0;
+  has = false;
+  add(u) {
+    this.has = true;
+    this.input += u.input;
+    this.output += u.output;
+    this.cacheRead += u.cacheRead;
+    this.cacheWrite += u.cacheWrite;
+    this.cost += u.cost ?? 0;
+  }
+  toTotal() {
+    if (!this.has) return void 0;
+    return {
+      input: this.input,
+      output: this.output,
+      cacheRead: this.cacheRead,
+      cacheWrite: this.cacheWrite,
+      cost: this.cost,
+      total: this.input + this.output + this.cacheRead + this.cacheWrite
+    };
+  }
+};
+function closeTurn(acc, turns, totals) {
+  if (acc === null) return;
+  turns.push({ text: acc.text, thinking: acc.thinking, toolCalls: acc.toolCalls, closed: true });
+  if (acc.usageDelta !== void 0) totals.add(acc.usageDelta);
+}
+function rowToMessageRow(v) {
+  if (typeof v === "object" && v !== null && "id" in v && "data" in v) {
+    const r = v;
+    if (typeof r.id === "string" && typeof r.data === "string") return { id: r.id, data: r.data };
+  }
+  throw new ZcodeReaderError("message \u884C\u5F62\u72B6\u5F02\u5E38\uFF08id/data \u5217\u7F3A\u5931\u6216\u7C7B\u578B\u6F02\u79FB\uFF09");
+}
+function rowToPartRow(v) {
+  if (typeof v === "object" && v !== null && "data" in v) {
+    const r = v;
+    if (typeof r.data === "string") return { data: r.data };
+  }
+  throw new ZcodeReaderError("part \u884C\u5F62\u72B6\u5F02\u5E38\uFF08data \u5217\u7F3A\u5931\u6216\u7C7B\u578B\u6F02\u79FB\uFF09");
+}
+function resolveSessionId(db, sessionId) {
+  if (sessionId !== void 0) {
+    const hit = db.prepare("SELECT id FROM session WHERE id = ?").get(sessionId);
+    if (hit === void 0) {
+      throw new ZcodeReaderError(
+        `session \u4E0D\u5B58\u5728\uFF1A${sessionId}`,
+        "sessionId \u53EF\u80FD\u6765\u81EA\u5DF2\u6E05\u7406\u7684\u6C60\u2014\u2014\u964D\u7EA7\u5230 outcome-only\u3002"
+      );
+    }
+    return sessionId;
+  }
+  const latest = db.prepare("SELECT id FROM session ORDER BY time_created DESC LIMIT 1").get();
+  if (latest === void 0 || typeof latest.id !== "string") {
+    throw new ZcodeReaderError("db \u5185\u65E0\u4EFB\u4F55 session \u884C");
+  }
+  return latest.id;
+}
+function loadGroupedParts(db, sessionId) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const raw of db.prepare(
+    "SELECT part.message_id AS mid, part.data AS data FROM part JOIN message ON part.message_id = message.id WHERE part.session_id = ? ORDER BY message.sequence, part.sequence"
+  ).all(sessionId)) {
+    if (typeof raw !== "object" || raw === null || !("mid" in raw)) continue;
+    const mid = String(raw.mid);
+    const arr = grouped.get(mid) ?? [];
+    arr.push(rowToPartRow(raw));
+    grouped.set(mid, arr);
+  }
+  return grouped;
+}
+function appendPartText(current, part) {
+  return current === "" ? String(part.text ?? "") : current + "\n" + String(part.text ?? "");
+}
+function applyPartToTurn(part, acc, turns, totals) {
+  switch (part.type) {
+    case "text":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.text = appendPartText(acc.text, part);
+      return acc;
+    case "reasoning":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.thinking = appendPartText(acc.thinking, part);
+      return acc;
+    case "tool":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.toolCalls.push(toolFromPart(part));
+      return acc;
+    case "step-finish": {
+      const u = usageFromStepFinish(part);
+      const cost = finiteOr2(part.cost, 0);
+      if (acc === null) acc = { text: "", thinking: "", toolCalls: [] };
+      if (u !== void 0) acc.usageDelta = cost > 0 ? { ...u, cost } : u;
+      closeTurn(acc, turns, totals);
+      return null;
+    }
+    default:
+      return acc;
+  }
+}
+function collectTurns(messages, grouped, totals) {
+  const turns = [];
+  for (const msg of messages) {
+    const parsedMsg = parseJsonField(msg.data, "message");
+    if (parsedMsg?.role !== "assistant") continue;
+    let acc = null;
+    for (const partRow of grouped.get(msg.id) ?? []) {
+      const part = parseJsonField(partRow.data, "part");
+      if (part === void 0) continue;
+      acc = applyPartToTurn(part, acc, turns, totals);
+    }
+    closeTurn(acc, turns, totals);
+  }
+  return turns;
+}
+function buildView(db, sessionId) {
+  const messages = db.prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY sequence").all(sessionId).map(rowToMessageRow);
+  const totals = new TotalsAcc();
+  const turns = collectTurns(messages, loadGroupedParts(db, sessionId), totals);
+  const usageTotal = totals.toTotal();
+  return {
+    engineId: ZCODE_ENGINE_ID,
+    sessionId,
+    ...usageTotal !== void 0 ? { usage: usageTotal } : {},
+    turns,
+    source: "native"
+  };
+}
+async function readZcodeSessionView(dbPath, sessionId) {
+  if (!fs3.existsSync(dbPath)) {
+    throw new ZcodeReaderError(`db \u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${dbPath}`);
+  }
+  const sqliteModuleId = "node:sqlite";
+  const sqliteMod = await import(sqliteModuleId).catch(() => void 0);
+  const DatabaseSyncCtor = sqliteMod?.DatabaseSync;
+  if (typeof DatabaseSyncCtor !== "function") {
+    throw new ZcodeReaderError(
+      "\u5F53\u524D node \u8FD0\u884C\u65F6\u4E0D\u652F\u6301 node:sqlite\uFF08\u9700 >=22.13\uFF09",
+      "\u5347\u7EA7 node \u6216\u6539\u7528\u7B2C\u2461\u7EA7\uFF08\u5BBF\u4E3B event journal\uFF09\u8BFB\u53D6\u3002"
+    );
+  }
+  const open = DatabaseSyncCtor;
+  let db;
+  try {
+    db = new open(dbPath, { readOnly: true });
+    return buildView(db, resolveSessionId(db, sessionId));
+  } catch (err) {
+    if (err instanceof ZcodeReaderError) throw err;
+    throw new ZcodeReaderError(
+      `sqlite \u67E5\u8BE2\u5931\u8D25\uFF08${err instanceof Error ? err.message : String(err)}\uFF09`,
+      "\u7591\u4F3C\u8868\u7ED3\u6784\u6F02\u79FB\uFF08zcode schema_migration \u5347\u7EA7\uFF09\u2014\u2014\u8C03\u7528\u65B9\u5E94\u964D\u7EA7\u5230\u7B2C\u2461\u7EA7\uFF1B\u5E76\u628A\u65B0 schema \u6837\u672C\u8865\u5F55\u8FDB golden \u5E93\u540E\u66F4\u65B0 reader\u3002"
+    );
+  } finally {
+    try {
+      db?.close();
+    } catch (err) {
+      void err;
+    }
+  }
+}
+
+// src/connection.ts
+var fs4 = __toESM(require("fs"), 1);
+var import_node_path = require("path");
+var import_node_os = require("os");
+var import_subagent_engine_sdk6 = require("@zhushanwen/subagent-engine-sdk");
+
+// src/logs/stderr-rotation.ts
+var import_subagent_engine_sdk4 = require("@zhushanwen/subagent-engine-sdk");
+var import_subagent_engine_sdk5 = require("@zhushanwen/subagent-engine-sdk");
+var ZCODE_STDERR_LOG_PREFIX = "zcode-appserver-stderr-";
+function stderrLogPathFor(engineDataDir, pid) {
+  return (0, import_subagent_engine_sdk4.stderrLogPathFor)(engineDataDir, pid, ZCODE_STDERR_LOG_PREFIX);
+}
+function cleanupSiblingStderrLogs(logPath, env, now) {
+  return (0, import_subagent_engine_sdk4.cleanupSiblingStderrLogs)(logPath, env, ZCODE_STDERR_LOG_PREFIX, now);
+}
+
+// src/connection.ts
+var logger = (0, import_subagent_engine_sdk6.getLogger)("subagents");
+var RAW_FRAME_LOG_CHARS = 200;
+var RUNTIME_PREFERENCES = Object.freeze({
+  nativeSearchEnhancementsEnabled: true,
+  memoryEnabled: false,
+  askUserQuestionAutoResolutionEnabled: true,
+  modelContextBudgetStrategy: "preflight-v1"
+});
+var DEFAULT_REVERSE_HANDLERS = {
+  "session/requestRuntimePreferences": () => RUNTIME_PREFERENCES
+};
+function isAppServerRpcError(err) {
+  return err instanceof Error && typeof err.code === "number";
+}
+function isRecord2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function frameIdOf(frame) {
+  const id = frame.id;
+  return typeof id === "string" || typeof id === "number" ? id : void 0;
+}
+function errMessage(err) {
+  return (0, import_subagent_engine_sdk3.toErrorMessage)(err);
+}
+function buildAppServerEnv(baseEnv = process.env) {
+  return {
+    ...(0, import_subagent_engine_sdk6.buildNestedSpawnEnv)(baseEnv),
+    ZCODE_MODEL_TELEMETRY_ENABLED: "false"
+  };
+}
+var AppServerConnection = class {
+  cliPath;
+  dataDir;
+  cwd;
+  env;
+  stderrLogPath;
+  stderrLogPathResolver;
+  /** 当前代 tee 流实际写入的路径（append/轮转/cleanup 共用）。 */
+  activeStderrLogPath = null;
+  nodeBin;
+  requestTimeoutMs;
+  reverseHandlers;
+  onSpawned;
+  launcherScript;
+  /** 当前代子进程；null = 无活进程（未启动或已死，下次使用重建）。 */
+  child = null;
+  pending = /* @__PURE__ */ new Map();
+  /** 请求 id 自增序（每代重置——新进程无历史 pending，id 空间互不冲突）。 */
+  reqSeq = 0;
+  /** stderr 滚动缓冲（代级：崩溃诊断用）。 */
+  stderrTail = "";
+  stderrStream = null;
+  stderrStreamFailed = false;
+  /**
+   * 本代我方杀链 promise（close/shutdown 共用）。入口顺序不破「shutdown resolve 于
+   * 进程退出」契约：close 先行发起时 shutdown await 同一 promise 而非直接 return。
+   * killChain 永不 reject（内部 raceTimeout 吞 reject）——close 的 fire-and-forget
+   * 无 unhandled rejection 面。
+   */
+  killChainPromise;
+  generation = 0;
+  pushHandlers = /* @__PURE__ */ new Map();
+  /** [R4] 连接级崩溃通知面（onClose 订阅者集合；与 pushHandlers 同构的 refCount 形态）。 */
+  closeHandlers = /* @__PURE__ */ new Set();
+  capturedProtocolInfo = null;
+  constructor(opts) {
+    this.cliPath = opts.cliPath;
+    this.launcherScript = opts.launcherScript;
+    this.dataDir = opts.dataDir;
+    this.cwd = opts.cwd;
+    this.env = opts.env;
+    this.stderrLogPath = opts.stderrLogPath;
+    this.stderrLogPathResolver = opts.stderrLogPathResolver ?? (() => this.stderrLogPath);
+    this.nodeBin = opts.nodeBin ?? "node";
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? ZCODE_APPSERVER_REQUEST_TIMEOUT_MS;
+    this.reverseHandlers = opts.reverseHandlers ?? DEFAULT_REVERSE_HANDLERS;
+    this.onSpawned = opts.onSpawned;
+  }
+  /** 当前代进程 pid（未启动/已死为 undefined）。 */
+  get pid() {
+    return this.child?.pid;
+  }
+  /** 当前代是否有活进程（关闭原语与重建测试的观测面）。 */
+  get alive() {
+    return this.child !== null;
+  }
+  /** 协议自报信息（A.1 首帧 {protocol:{...}} 或 {method:'protocol'} 推送形态；未收到为 null）。 */
+  get protocolInfo() {
+    return this.capturedProtocolInfo;
+  }
+  /**
+   * 订阅服务端推送（按 method）。handler 异常由本模块吞掉并 warn（不拖死帧泵）。
+   *
+   * @returns 退订函数
+   */
+  onNotification(method, handler) {
+    let set = this.pushHandlers.get(method);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.pushHandlers.set(method, set);
+    }
+    set.add(handler);
+    return () => {
+      set?.delete(handler);
+      if (set && set.size === 0) this.pushHandlers.delete(method);
+    };
+  }
+  /**
+   * [R4] 订阅连接崩溃/关闭通知：当前代进程退出（崩溃、spawn 失败、我方杀链收尾）时
+   * 回调一次（reason 含 stderr 尾部——失败路径 2 的错误素材）。时序保证：在途
+   * pending 全部 reject **之后**触发（订阅方可安全假定「在途请求已死」）。仅在
+   * 「有进程死亡」时触发——从未启动过的连接不通知。
+   *
+   * @returns 退订函数
+   */
+  onClose(handler) {
+    this.closeHandlers.add(handler);
+    return () => {
+      this.closeHandlers.delete(handler);
+    };
+  }
+  /**
+   * [R4] 发一个客户端请求帧但不等待应答（fire-and-forget）。dispose 编排用：
+   * 停机时 session/close 帧「发出即算」不阻塞在应答上（对面进程可能正被并发收割，
+   * 等应答会让 dispose 挂到请求超时）。不登记 pending——迟到应答按无匹配 id 忽略。
+   */
+  post(method, params) {
+    this.ensureStarted();
+    return this.writeFrame({ id: ++this.reqSeq, method, params });
+  }
+  /**
+   * 发一个客户端请求并等应答。惰性启动（首次调用 spawn）；error 应答帧转 reject
+   * （code/data 挂到 Error 上，-32602 的 zod 诊断随 data 带出便于逆向 schema）。
+   * 出站帧精确键集 {id, method, params}——无 jsonrpc 字段（A.1）。
+   */
+  request(method, params, opts) {
+    this.ensureStarted();
+    if (this.child === null) {
+      return Promise.reject(new Error("app-server \u8FDE\u63A5\u4E0D\u53EF\u7528\uFF08\u8FDB\u7A0B\u672A\u542F\u52A8\u6216\u5DF2\u9000\u51FA\uFF09"));
+    }
+    const timeoutMs = opts?.timeoutMs ?? this.requestTimeoutMs;
+    const id = ++this.reqSeq;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`\u8BF7\u6C42 ${method} \u8D85\u65F6\uFF08${timeoutMs}ms\uFF09`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        // 泛型 T 是调用方对线上 unknown 结果的视图声明，连接层不做运行时校验
+        // （协议层保持透明，结构校验归会话层/消费方）。
+        resolve,
+        reject,
+        timer,
+        method
+      });
+      if (!this.writeFrame({ id, method, params })) {
+        this.pending.delete(id);
+        clearTimeout(timer);
+        reject(new Error(`\u8BF7\u6C42 ${method} \u5199\u5165\u5931\u8D25\uFF08app-server \u8FDB\u7A0B\u4E0D\u53EF\u5199\uFF09`));
+      }
+    });
+  }
+  /**
+   * 同步关闭面（R4 dispose 编排的原语）：立即发 SIGTERM（同步系统调用，返回前信号
+   * 已发出），grace→SIGKILL 升级由杀链 promise 跟进（fire-and-forget）。幂等；对未启动
+   * 连接是零成本 no-op。close 之后调 shutdown 会 await 同一杀链再 resolve（见
+   * killChainPromise 字段注释）。
+   */
+  close() {
+    const child = this.child;
+    if (child === null || this.killChainPromise !== void 0) return;
+    this.killChainPromise = (0, import_subagent_engine_sdk6.killChain)(child, { graceMs: ZCODE_KILL_GRACE_MS });
+  }
+  /**
+   * 异步完整关闭面：SIGTERM → grace → SIGKILL 杀链走完（含收尸），resolve 于进程
+   * 退出。幂等：与 close 共享同一杀链 promise——close 先行时 await 它再 resolve，
+   * 不另起杀链（graceMs 取首次发起值）。之后首个 request() 自动重建（与崩溃重建
+   * 同路径，§3.4 不变量 4）。
+   */
+  async shutdown(opts) {
+    if (this.killChainPromise === void 0) {
+      const child = this.child;
+      if (child === null) return;
+      this.killChainPromise = (0, import_subagent_engine_sdk6.killChain)(child, { graceMs: opts?.graceMs ?? ZCODE_KILL_GRACE_MS });
+    }
+    await this.killChainPromise;
+  }
+  // ============================================================
+  // 进程生命周期（代管理）
+  // ============================================================
+  ensureStarted() {
+    if (this.child !== null) return;
+    this.spawnGeneration();
+  }
+  spawnGeneration() {
+    this.pending = /* @__PURE__ */ new Map();
+    this.reqSeq = 0;
+    this.stderrTail = "";
+    this.killChainPromise = void 0;
+    this.generation += 1;
+    const gen = this.generation;
+    const script = this.launcherScript ?? this.cliPath;
+    const child = (0, import_subagent_engine_sdk6.spawnEngineChild)({
+      command: this.nodeBin,
+      args: [script, "app-server", "--cwd", this.cwd],
+      env: (0, import_subagent_engine_sdk6.buildEngineChildEnv)(this.env, {
+        // L0 XYZ_AGENT_DATA_DIR 缺省链：显式传参 > 宿主注入 env > tmpdir 占位
+        //（app-server 不消费该键，占位仅满足 L0 必注入契约；生产调用方
+        // zcode-engine.ensureAppServerRuntime 恒传 engineDataDir）。
+        dataDir: this.dataDir ?? process.env["XYZ_AGENT_DATA_DIR"] ?? (0, import_node_os.tmpdir)(),
+        envPrefixes: ["ZCODE_"]
+      }),
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    this.child = child;
+    if (this.onSpawned !== void 0) {
+      try {
+        this.onSpawned(child);
+      } catch (err) {
+        logger.warn(`onSpawned \u56DE\u8C03\u5F02\u5E38\uFF08\u5FFD\u7565\uFF09: ${errMessage(err)}`);
+      }
+    }
+    let finalized = false;
+    const finalize = (reason) => {
+      if (finalized || this.generation !== gen) return;
+      finalized = true;
+      this.closeStderrStream();
+      this.child = null;
+      const err = new Error(`app-server ${reason}`);
+      for (const entry of this.pending.values()) {
+        clearTimeout(entry.timer);
+        entry.reject(err);
+      }
+      this.pending.clear();
+      for (const fn of [...this.closeHandlers]) {
+        try {
+          fn(reason);
+        } catch (err2) {
+          logger.warn(`close handler \u5F02\u5E38: ${errMessage(err2)}`);
+        }
+      }
+    };
+    (0, import_subagent_engine_sdk6.pumpNdjsonLines)(child.stdout, (line) => this.handleLine(line));
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      this.stderrTail = (this.stderrTail + chunk).slice(-ZCODE_APPSERVER_STDERR_TAIL_BUFFER_CHARS);
+      this.appendStderrLog(chunk);
+    });
+    child.stdin?.on("error", () => {
+    });
+    child.once("close", (code, signal) => {
+      finalize(
+        `\u8FDB\u7A0B\u9000\u51FA\uFF08code=${code} signal=${signal ?? "none"}\uFF09stderr \u5C3E\u90E8: ${this.stderrTail.slice(-ZCODE_APPSERVER_STDERR_TAIL_CHARS)}`
+      );
+    });
+    child.once("error", (err) => finalize(`spawn \u5931\u8D25: ${err.message}`));
+  }
+  // ============================================================
+  // 帧分发（A.1 四帧型；宽容解析，坏行跳过不断流）
+  // ============================================================
+  handleLine(line) {
+    const text = line.trim();
+    if (!text) return;
+    let frame;
+    try {
+      frame = JSON.parse(text);
+    } catch {
+      logger.warn(`\u65E0\u6CD5\u89E3\u6790\u7684\u534F\u8BAE\u884C\uFF08\u5FFD\u7565\uFF09: ${text.slice(0, RAW_FRAME_LOG_CHARS)}`);
+      return;
+    }
+    this.handleFrame(frame, text);
+  }
+  handleFrame(frame, rawText) {
+    if (!isRecord2(frame)) {
+      logger.warn(`\u975E\u5BF9\u8C61\u534F\u8BAE\u5E27\uFF08\u5FFD\u7565\uFF09: ${rawText.slice(0, RAW_FRAME_LOG_CHARS)}`);
+      return;
+    }
+    if (isRecord2(frame.protocol)) this.capturedProtocolInfo = frame.protocol;
+    if (typeof frame.method === "string") {
+      const reverseId = frameIdOf(frame);
+      if (reverseId !== void 0) {
+        this.answerReverse(reverseId, frame.method, frame.params);
+      } else {
+        this.dispatchPush(frame.method, frame.params);
+      }
+      return;
+    }
+    if (frame.id !== void 0 && frame.id !== null) {
+      if (typeof frame.id !== "number") {
+        logger.warn(`\u5E94\u7B54 id \u975E\u6570\u5B57\uFF08\u5FFD\u7565\uFF09: ${rawText.slice(0, RAW_FRAME_LOG_CHARS)}`);
+        return;
+      }
+      this.settlePending(frame.id, frame);
+      return;
+    }
+    if (isRecord2(frame.protocol)) return;
+    logger.warn(`\u65E0\u6CD5\u5F52\u7C7B\u7684\u534F\u8BAE\u5E27\uFF08\u5FFD\u7565\uFF09: ${rawText.slice(0, RAW_FRAME_LOG_CHARS)}`);
+  }
+  settlePending(id, frame) {
+    const entry = this.pending.get(id);
+    if (!entry) {
+      logger.warn(`\u54CD\u5E94\u65E0\u5339\u914D\u8BF7\u6C42 id=${id}\uFF08\u5FFD\u7565\uFF09`);
+      return;
+    }
+    this.pending.delete(id);
+    clearTimeout(entry.timer);
+    if (frame.error !== void 0) {
+      const e = isRecord2(frame.error) ? frame.error : {};
+      const code = typeof e.code === "number" ? e.code : void 0;
+      const message = typeof e.message === "string" ? e.message : JSON.stringify(e.message ?? e);
+      const dataSlice = e.data === void 0 ? "" : `\uFF1Bdata: ${JSON.stringify(e.data).slice(0, ZCODE_APPSERVER_STDERR_TAIL_CHARS)}`;
+      const err = new Error(`${entry.method} \u5931\u8D25: [${code ?? "?"}] ${message}${dataSlice}`);
+      err.code = code;
+      err.data = e.data;
+      entry.reject(err);
+      return;
+    }
+    entry.resolve(frame.result);
+  }
+  dispatchPush(method, params) {
+    if (method === "protocol") this.capturedProtocolInfo = isRecord2(params) ? params : null;
+    const set = this.pushHandlers.get(method);
+    if (!set) return;
+    for (const fn of set) {
+      try {
+        fn(params);
+      } catch (err) {
+        logger.warn(`push handler \u5F02\u5E38\uFF08${method}\uFF09: ${errMessage(err)}`);
+      }
+    }
+  }
+  // ============================================================
+  // 反向请求应答（D9）
+  // ============================================================
+  answerReverse(id, method, params) {
+    const handler = this.reverseHandlers[method];
+    if (!handler) {
+      logger.warn(`\u672A\u77E5\u53CD\u5411\u8BF7\u6C42 ${method}\uFF08id=${id}\uFF09\uFF1A\u56DE\u7A7A result\uFF08\u4E0D\u7B54\u4F1A 15s \u8D85\u65F6\u65AD\u8FDE\uFF0C\u65E7\u5B9E\u6D4B -32022\uFF09`);
+      this.writeFrame({ id, result: {} });
+      return;
+    }
+    Promise.resolve().then(() => handler(params)).then((result) => this.writeFrame({ id, result: result ?? {} })).catch((err) => {
+      logger.warn(`\u53CD\u5411\u8BF7\u6C42 ${method} handler \u5F02\u5E38: ${errMessage(err)}`);
+      this.writeFrame({ id, error: { code: -32e3, message: errMessage(err) } });
+    });
+  }
+  // ============================================================
+  // 写帧 / stderr tee
+  // ============================================================
+  /** 写一帧（JSON + 换行）。返回 false = 进程不可写（调用方决定如何失败）。 */
+  writeFrame(frame) {
+    const child = this.child;
+    if (child === null || child.stdin === null) return false;
+    try {
+      child.stdin.write(`${JSON.stringify(frame)}
+`);
+      return true;
+    } catch (err) {
+      logger.warn(`\u5199\u5165 app-server \u5931\u8D25: ${errMessage(err)}`);
+      return false;
+    }
+  }
+  /** stderr 实时 append 落盘（懒打开 + 尺寸轮转 + 过期清理；失败静默——取证面不
+   * 能拖垮主通道）。 */
+  appendStderrLog(chunk) {
+    if (this.stderrStreamFailed) return;
+    if (this.stderrStream === null) {
+      const target = this.stderrLogPathResolver(this.child?.pid);
+      try {
+        fs4.mkdirSync((0, import_node_path.dirname)(target), { recursive: true });
+        this.activeStderrLogPath = target;
+        this.stderrStream = fs4.createWriteStream(target, { flags: "a" });
+        this.stderrStream.on("error", () => {
+          this.stderrStreamFailed = true;
+        });
+        cleanupSiblingStderrLogs(target, process.env);
+      } catch {
+        this.stderrStreamFailed = true;
+        return;
+      }
+    }
+    this.stderrStream.write(chunk);
+    if (this.activeStderrLogPath !== null) {
+      const params = (0, import_subagent_engine_sdk5.stderrRotationParams)(process.env);
+      if ((0, import_subagent_engine_sdk5.rotateStderrLogIfNeeded)(this.activeStderrLogPath, params)) {
+        this.closeStderrStream();
+      }
+    }
+  }
+  /** 代收尾时关闭 tee 流（下一代懒重开；W11 起路径按新一代 pid 解析）。 */
+  closeStderrStream() {
+    if (this.stderrStream !== null) {
+      const stream = this.stderrStream;
+      this.stderrStream = null;
+      this.activeStderrLogPath = null;
+      stream.end();
+    }
+  }
+};
+
+// src/session-channel.ts
+var import_node_crypto = require("crypto");
+var import_subagent_engine_sdk7 = require("@zhushanwen/subagent-engine-sdk");
+var logger2 = (0, import_subagent_engine_sdk7.getLogger)("subagents");
+var SUBSCRIBE_DELIVERY_KIND = "desktop-continuous";
+var WORKSPACE_KEY_HASH_CHARS = 16;
+var CREATE_REPLY_LOG_CHARS = 300;
+var DELTA_LOG_CHARS = 120;
+function isRecord3(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function errMessage2(err) {
+  return (0, import_subagent_engine_sdk3.toErrorMessage)(err);
+}
+function stableWorkspaceKey(workspacePath) {
+  return "ws-" + (0, import_node_crypto.createHash)("sha256").update(workspacePath).digest("hex").slice(0, WORKSPACE_KEY_HASH_CHARS);
+}
+function extractCreatedSessionId(created) {
+  if (!isRecord3(created)) return void 0;
+  const session = isRecord3(created.session) ? created.session : void 0;
+  if (session !== void 0 && typeof session.sessionId === "string" && session.sessionId !== "") {
+    return session.sessionId;
+  }
+  if (session !== void 0 && typeof session.id === "string" && session.id !== "") {
+    return session.id;
+  }
+  if (typeof created.sessionId === "string" && created.sessionId !== "") {
+    return created.sessionId;
+  }
+  return void 0;
+}
+function extractPushSessionId(params) {
+  if (!isRecord3(params)) return void 0;
+  if (typeof params.sessionId === "string" && params.sessionId !== "")
+    return params.sessionId;
+  if (isRecord3(params.session) && typeof params.session.id === "string" && params.session.id !== "") {
+    return params.session.id;
+  }
+  return void 0;
+}
+function messageRole(m) {
+  if (typeof m.role === "string") return m.role;
+  if (isRecord3(m.info) && typeof m.info.role === "string") return m.info.role;
+  return void 0;
+}
+function partsToText(parts) {
+  if (!Array.isArray(parts)) return void 0;
+  const texts = [];
+  for (const p of parts) {
+    if (isRecord3(p) && p.type === "text" && typeof p.text === "string")
+      texts.push(p.text);
+  }
+  return texts.length > 0 ? texts.join("") : void 0;
+}
+function contentToText(content) {
+  if (typeof content === "string") return content;
+  if (isRecord3(content) && typeof content.text === "string")
+    return content.text;
+  if (Array.isArray(content)) {
+    const texts = content.map((b) => {
+      if (typeof b === "string") return b;
+      return isRecord3(b) && typeof b.text === "string" ? b.text : "";
+    });
+    const joined = texts.join("");
+    return joined !== "" ? joined : void 0;
+  }
+  return void 0;
+}
+function extractAssistantText(readResult) {
+  if (typeof readResult === "string") return readResult;
+  if (!isRecord3(readResult)) return void 0;
+  if (Array.isArray(readResult.messages)) {
+    const last = [...readResult.messages].reverse().find(
+      (m) => isRecord3(m) && (messageRole(m) === "assistant" || messageRole(m) === void 0)
+    );
+    if (last !== void 0) {
+      const viaContent = contentToText(last.content);
+      if (viaContent !== void 0) return viaContent;
+      const viaParts = partsToText(last.parts);
+      if (viaParts !== void 0) return viaParts;
+    }
+  }
+  for (const k of ["text", "response", "content", "message"]) {
+    if (typeof readResult[k] === "string") return readResult[k];
+  }
+  return void 0;
+}
+function extractReadUsage(readResult) {
+  if (!isRecord3(readResult)) return void 0;
+  const messages = Array.isArray(readResult.messages) ? readResult.messages : [];
+  for (const m of [...messages].reverse()) {
+    if (!isRecord3(m) || messageRole(m) !== "assistant" || !Array.isArray(m.parts))
+      continue;
+    const finish = [...m.parts].reverse().find(
+      (p) => isRecord3(p) && p.type === "step-finish" && isRecord3(p.tokens)
+    );
+    if (finish !== void 0 && isRecord3(finish.tokens)) return finish.tokens;
+  }
+  return isRecord3(readResult.usage) ? readResult.usage : void 0;
+}
+var TurnTimeoutError = class extends Error {
+  kind;
+  elapsed;
+  lastEventAt;
+  thresholdMs;
+  constructor(kind, parts) {
+    super(
+      kind === "idle" ? `zcode turn idle \u5224\u6B7B\uFF1A\u8FDE\u7EED ${parts.thresholdMs}ms \u672A\u89C2\u5BDF\u5230\u672C turn \u4EFB\u4F55\u4E8B\u4EF6\uFF08session/event \u4E0E v4/telemetry/event \u5747\u9759\u9ED8\uFF09\uFF0C\u7EC8\u6001\u672A\u5230\u8FBE\u3002` + (parts.lastEventAt === void 0 ? "\u672C\u8F6E\u81EA send \u8D77\u672A\u89C2\u5BDF\u5230\u4EFB\u4F55\u4E8B\u4EF6\uFF08\u8FDB\u7A0B\u5047\u6B7B/\u534F\u8BAE\u9759\u9ED8\u5F62\u6001\uFF09\u3002" : `\u6700\u540E\u4E8B\u4EF6\u65F6\u523B ${new Date(parts.lastEventAt).toISOString()}\u3002`) + "\u6062\u590D\u6307\u5F15\uFF1A\u76F4\u63A5\u91CD\u8DD1\u672C\u4EFB\u52A1\uFF1B\u82E5\u6301\u7EED\u51FA\u73B0\uFF0C\u68C0\u67E5 ZCode \u684C\u9762\u7AEF\u6A21\u578B\u8FDE\u901A\u6027\u6216\u6539\u7528 engine: pi\u3002" : `zcode turn \u603B\u4E0A\u754C\u5224\u6B7B\uFF1A${parts.thresholdMs}ms \u5185\u672A\u89C2\u5BDF\u5230\u7EC8\u6001\uFF08turn.terminal \u4E0E\u6536\u5C3E\u5E27\u5747\u672A\u5230\u8FBE\uFF1Bidle \u5224\u5B9A\u672A\u89E6\u53D1\u2014\u2014\u4E8B\u4EF6\u6D41\u4ECD\u6D3B\u8DC3\uFF0Cchatty-wedge \u5F62\u6001\uFF09\u3002` + (parts.lastEventAt === void 0 ? "" : `\u6700\u540E\u4E8B\u4EF6\u65F6\u523B ${new Date(parts.lastEventAt).toISOString()}\u3002`) + `\u6062\u590D\u6307\u5F15\uFF1A\u76F4\u63A5\u91CD\u8DD1\u672C\u4EFB\u52A1\uFF1B\u82E5\u672C\u4EFB\u52A1\u5C5E\u5408\u6CD5\u8D85\u957F\u4EFB\u52A1\uFF08\u9884\u671F\u8D85\u8FC7 ${parts.thresholdMs}ms \u603B\u4E0A\u754C\uFF09\uFF0C\u91CD\u8DD1\u524D\u8BBE ${ZCODE_TURN_MAX_TIMEOUT_ENV} \u4E3A\u66F4\u5927\u6BEB\u79D2\u503C\uFF0C\u6216\u8BBE 0 \u5173\u95ED\u603B\u4E0A\u754C\uFF08\u5173\u95ED\u540E chatty \u5F62\u6001\u4E0D\u518D\u81EA\u52A8\u56DE\u6536\uFF0C\u9759\u9ED8 wedged \u4ECD\u7531 idle \u5C42\u515C\u5E95\u2014\u2014\u81EA\u884C\u6743\u8861\uFF09\u3002`
+    );
+    this.name = "TurnTimeoutError";
+    this.kind = kind;
+    this.elapsed = parts.elapsed;
+    this.lastEventAt = parts.lastEventAt;
+    this.thresholdMs = parts.thresholdMs;
+  }
+};
+function clearTurnTimers(turn) {
+  if (turn.idleTimer !== void 0) {
+    clearTimeout(turn.idleTimer);
+    turn.idleTimer = void 0;
+  }
+  if (turn.ceilingTimer !== void 0) {
+    clearTimeout(turn.ceilingTimer);
+    turn.ceilingTimer = void 0;
+  }
+}
+function armTurnTimer(onFire, ms) {
+  const timer = setTimeout(onFire, ms);
+  if (typeof timer.unref === "function") timer.unref();
+  return timer;
+}
+function resolveTurnTimerMs(parts) {
+  let value;
+  let source;
+  if (parts.explicit !== void 0) {
+    value = parts.explicit;
+    source = "\u663E\u5F0F\u4F20\u53C2";
+  } else {
+    const raw = process.env[parts.envName];
+    const parsed = parseZcodeTurnTimeoutEnv(raw);
+    if (parsed.state === "valid") {
+      value = parsed.ms;
+      source = `env ${parts.envName}=${raw}`;
+    } else {
+      if (parsed.state === "invalid") {
+        logger2.warn(
+          `[session-channel] ${parts.envName}="${raw}" \u975E\u6CD5\uFF08\u5E94\u4E3A\u6BEB\u79D2\u6570\u5B57\uFF09\u2014\u2014\u56DE\u843D\u9ED8\u8BA4 ${parts.fallbackMs}ms\uFF08${parts.label}\uFF09\u3002\u8BBE\u7F6E\u6B63\u6BEB\u79D2\u503C\u8986\u76D6\uFF0C\u6216 0 \u663E\u5F0F\u5173\u95ED`
+        );
+      }
+      value = parts.fallbackMs;
+      source = "\u9ED8\u8BA4\u503C";
+    }
+  }
+  if (value <= 0) {
+    logger2.warn(
+      `[session-channel] zcode turn ${parts.label}\u5DF2\u5173\u95ED\uFF08${source}\uFF09\u2014\u2014${parts.offConsequence}\u3002\u8BBE\u6B63\u6BEB\u79D2\u503C\uFF08env ${parts.envName} \u6216\u663E\u5F0F\u4F20\u53C2\uFF09\u6062\u590D\u56DE\u6536\u5C42`
+    );
+  }
+  return value;
+}
+var SessionChannel = class {
+  conn;
+  /** sessionId → 在途 turn（终态落定后仍保留到 runTurn 收尾——收尾帧数据吸收窗口）。 */
+  activeTurns = /* @__PURE__ */ new Map();
+  offHandlers;
+  /**
+   * [P0-1 U5/D7] dispose 标志：dispose 收割后 closeSession 短路——收割形态下连接
+   * 可能仍 alive（close 事件迟到，finalize 未跑、child 非 null），此时发 close
+   * request 会写死进程（请求挂到控制面超时）或触发惰性重建（凭空 spawn 无人使用的
+   * 进程，违背 dispose 防泄漏语义）；进程随即被引擎杀链回收，会话驻留随之消亡。
+   */
+  disposed = false;
+  constructor(conn) {
+    this.conn = conn;
+    this.offHandlers = [
+      conn.onNotification(
+        "session/event",
+        (params) => this.handleSessionEvent(params)
+      ),
+      conn.onNotification(
+        "v4/telemetry/event",
+        (params) => this.handleTelemetry(params)
+      ),
+      // 连接崩溃收割：进程死亡（崩溃/我方杀链）立即 fail 全部在途 turn——
+      // onClose 契约保证触发时连接层在途 request 已全部 reject，此处补齐
+      // 「无在途 request 的 turn」的收割（否则挂到 turn idle/总上界预算耗尽）
+      conn.onClose((reason) => this.failAllTurns(`app-server ${reason}`))
+    ];
+  }
+  /**
+   * [P0-1 U5/D7] dispose 前收割 + 退订：「退订 = 不会再有事件」在结构上蕴含「在途
+   * turn 不应再等」——close 缺失/被吞没形态（onClose 收割主路径未触发）下，在途
+   * turn 于退订前经既有 failAllTurns 收敛为明确失败，不再挂满自身 idle/总上界预算
+   * （设计 §3.4 退化路径闭合；race 窗口在引擎 shutdownRuntimeAndDisposeChannel，
+   * 量级与 awaitConnFinalized 同源 ZCODE_APPSERVER_HARVEST_GRACE_MS）。幂等：与
+   * onClose 收割先到者赢（turn.fail 的 settled 守卫——已落定 turn 不改写），
+   * activeTurns 已空则 no-op。不影响连接自身生命周期（R4）。
+   */
+  dispose() {
+    this.disposed = true;
+    this.failAllTurns(
+      "zcode session channel \u5DF2 dispose\uFF1A\u8FDE\u63A5 close \u4E8B\u4EF6\u672A\u5728\u6536\u5272\u7A97\u53E3\u5185\u5230\u8FBE\uFF0C\u5728\u9014 turn \u4E8E\u9000\u8BA2\u524D\u6536\u5272\u4E3A\u660E\u786E\u5931\u8D25\uFF08\u4E0D\u518D\u6302\u5230 turn \u81EA\u8EAB\u9884\u7B97\u8017\u5C3D\uFF09\u3002\u6062\u590D\u6307\u5F15\uFF1A\u76F4\u63A5\u91CD\u8DD1\u672C\u4EFB\u52A1\u3002"
+    );
+    for (const off of this.offHandlers.splice(0)) off();
+  }
+  /** 连接死亡收割：全部在途 turn 立即 reject（reason 即连接层崩溃错误）。 */
+  failAllTurns(reason) {
+    const err = new Error(reason);
+    for (const turn of [...this.activeTurns.values()]) {
+      turn.fail(err);
+      this.activeTurns.delete(turn.sessionId);
+    }
+  }
+  /**
+   * session/create（A.2 ① 键集逐字：对面 zod strict 拒未知键，出站必须精确）。
+   * persistence:"immediate" 固定携带（D4：SQLite 持久化，上游不可覆盖）；空工具
+   * 清单不设键（防上游带空数组）。sessionId 从 result.session.sessionId 提取
+   * （projection.sessionId 恒 "unknown" 勿用）。
+   */
+  async createSession(params) {
+    const frame = {
+      workspace: {
+        workspacePath: params.workspacePath,
+        workspaceKey: stableWorkspaceKey(params.workspacePath)
+      },
+      mode: params.mode,
+      ...params.model !== void 0 ? { model: params.model } : {},
+      ...params.thoughtLevel !== void 0 ? { thoughtLevel: params.thoughtLevel } : {},
+      ...params.toolAllowlist !== void 0 && params.toolAllowlist.length > 0 ? { toolAllowlist: params.toolAllowlist } : {},
+      ...params.toolDenylist !== void 0 && params.toolDenylist.length > 0 ? { toolDenylist: params.toolDenylist } : {},
+      persistence: "immediate"
+    };
+    const created = await this.conn.request("session/create", frame);
+    const sessionId = extractCreatedSessionId(created);
+    if (sessionId === void 0) {
+      throw new Error(
+        `session/create \u672A\u8FD4\u56DE sessionId: ${JSON.stringify(created).slice(
+          0,
+          CREATE_REPLY_LOG_CHARS
+        )}`
+      );
+    }
+    return sessionId;
+  }
+  /** session/subscribe（A.2 ②：deliveryKind 必填——缺失则终态事件不达、会话假死）。 */
+  async subscribe(sessionId) {
+    await this.conn.request("session/subscribe", {
+      sessionId,
+      deliveryKind: SUBSCRIBE_DELIVERY_KIND
+    });
+  }
+  /** session/send（A.2 ③：字段是 content 不是 text）→ {accepted:true}。 */
+  async send(sessionId, content) {
+    const r = await this.conn.request("session/send", { sessionId, content });
+    if (isRecord3(r) && r.accepted === false) {
+      throw new Error(
+        "session/send \u8FD4\u56DE accepted:false\uFF08\u6295\u9012\u672A\u88AB\u63A5\u53D7\u2014\u2014\u4F1A\u8BDD\u53EF\u80FD\u5DF2\u5931\u6548\u6216\u62D2\u7EDD\u6295\u9012\uFF09"
+      );
+    }
+  }
+  /**
+   * session/close（A.2 ⑦，D4 用后即毁——回收引擎驻留内存，SQLite 持久化保留）。
+   * best-effort：失败只 warn 不抛（会话已终态，close 失败只泄漏一个驻留会话，
+   * 不应炸掉已成功/已失败的任务结论）。连接已死时跳过——close 是 request 语义，
+   * 对死连接发请求会触发惰性重建（凭空 spawn 一代无人使用的进程）。
+   */
+  async closeSession(sessionId) {
+    if (this.disposed) return;
+    if (!this.conn.alive) return;
+    try {
+      await this.conn.request(
+        "session/close",
+        { sessionId },
+        { timeoutMs: ZCODE_APPSERVER_TURN_CLOSE_TIMEOUT_MS }
+      );
+    } catch (err) {
+      logger2.warn(
+        `session/close \u5931\u8D25\uFF08\u4F1A\u8BDD ${sessionId}\uFF0Cbest-effort \u5FFD\u7565\uFF09: ${errMessage2(
+          err
+        )}`
+      );
+    }
+  }
+  /**
+   * 单任务自包含入口（§2.4 ①-⑦）：create → subscribe → send → 事件流
+   * （onTextDelta）→ 终态 → read 兜底 → resolve {response, usage, sessionId}
+   * → close。resolve 严格晚于全部事件回调（不变量 2）；close 走 finally——成功/
+   * 失败路径都回收会话（D4）。RPC 错误（含 -32601/-32602 漂移类）原样透传（R5 消费）。
+   */
+  async runTurn(params, content, opts = {}) {
+    if (content === "")
+      throw new Error("runTurn: content \u5FC5\u586B\uFF08session/send \u7A7A\u6295\u9012\u65E0\u610F\u4E49\uFF09");
+    const sessionId = await this.createSession(params);
+    opts.onSessionCreated?.(sessionId);
+    const opened = this.openTurn(sessionId, opts);
+    try {
+      await this.subscribe(sessionId);
+      try {
+        await this.send(sessionId, content);
+      } catch (err) {
+        opened.turn.fail(err instanceof Error ? err : new Error(String(err)));
+        void opened.done.catch(() => {
+        });
+        throw err;
+      }
+      const terminal = await opened.done;
+      const readResult = await this.readBestEffort(sessionId);
+      const readText = extractAssistantText(readResult);
+      const response = readText ?? opened.turn.finalText ?? opened.turn.deltas.join("");
+      const usage = opened.turn.finalUsage ?? extractReadUsage(readResult);
+      return {
+        sessionId,
+        response,
+        ...usage !== void 0 ? { usage } : {},
+        terminal,
+        ...opened.turn.lastTerminalStatus !== void 0 ? { lastTerminalStatus: opened.turn.lastTerminalStatus } : {},
+        ...opened.turn.lastTerminalError !== void 0 ? { lastTerminalError: opened.turn.lastTerminalError } : {}
+      };
+    } finally {
+      opened.stopTimers();
+      this.activeTurns.delete(sessionId);
+      await this.closeSession(sessionId);
+    }
+  }
+  // ============================================================
+  // 内部：turn 生命周期与推送泵
+  // ============================================================
+  openTurn(sessionId, opts) {
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((res, rej) => {
+      resolveDone = res;
+      rejectDone = rej;
+    });
+    const turn = {
+      sessionId,
+      callbacks: { onTextDelta: opts.onTextDelta, onThinkingDelta: opts.onThinkingDelta },
+      settled: false,
+      deltas: [],
+      finalText: void 0,
+      finalUsage: void 0,
+      terminal: void 0,
+      lastTerminalStatus: void 0,
+      lastTerminalError: void 0,
+      idleMs: 0,
+      ceilingMs: 0,
+      startedAt: Date.now(),
+      lastEventAt: void 0,
+      idleTimer: void 0,
+      ceilingTimer: void 0,
+      // 装配占位：下方 timer 创建后重绑（settle/fail 需要清理两 timer）
+      settle: () => {
+      },
+      fail: () => {
+      },
+      fireTimeout: () => {
+      }
+    };
+    turn.idleMs = resolveTurnTimerMs({
+      explicit: opts.idleTimeoutMs,
+      envName: ZCODE_TURN_IDLE_TIMEOUT_ENV,
+      fallbackMs: ZCODE_TURN_IDLE_TIMEOUT_MS,
+      label: "idle \u4E3B\u5224\u5B9A",
+      offConsequence: "\u9759\u9ED8 wedged\uFF08\u65E0\u4E8B\u4EF6\uFF09\u5F62\u6001\u5C06\u65E0\u81EA\u52A8\u56DE\u6536\uFF0C\u4EFB\u52A1\u53EF\u80FD\u6302\u5230\u5BBF\u4E3B\u8FDB\u7A0B\u9000\u51FA"
+    });
+    turn.ceilingMs = resolveTurnTimerMs({
+      explicit: opts.turnTimeoutMs,
+      envName: ZCODE_TURN_MAX_TIMEOUT_ENV,
+      fallbackMs: ZCODE_TURN_MAX_TIMEOUT_MS,
+      label: "\u603B\u4E0A\u754C",
+      offConsequence: "chatty-wedge\uFF08\u6709\u4E8B\u4EF6\u65E0\u7EC8\u6001\uFF09\u5F62\u6001\u5C06\u65E0\u81EA\u52A8\u56DE\u6536\uFF0C\u4EC5\u5269 idle \u9759\u9ED8\u5224\u5B9A\u515C\u5E95"
+    });
+    const fireTimeout = (kind) => {
+      if (turn.settled) return;
+      turn.settled = true;
+      clearTurnTimers(turn);
+      this.activeTurns.delete(sessionId);
+      rejectDone(
+        new TurnTimeoutError(kind, {
+          thresholdMs: kind === "idle" ? turn.idleMs : turn.ceilingMs,
+          elapsed: Date.now() - turn.startedAt,
+          lastEventAt: turn.lastEventAt
+        })
+      );
+    };
+    turn.fireTimeout = fireTimeout;
+    if (turn.idleMs > 0) {
+      turn.idleTimer = armTurnTimer(() => turn.fireTimeout("idle"), turn.idleMs);
+    }
+    if (turn.ceilingMs > 0) {
+      turn.ceilingTimer = armTurnTimer(
+        () => turn.fireTimeout("ceiling"),
+        turn.ceilingMs
+      );
+    }
+    turn.settle = (t) => {
+      if (turn.settled) return;
+      turn.settled = true;
+      turn.terminal = t;
+      clearTurnTimers(turn);
+      resolveDone(t);
+    };
+    turn.fail = (err) => {
+      if (turn.settled) return;
+      turn.settled = true;
+      clearTurnTimers(turn);
+      rejectDone(err);
+    };
+    this.activeTurns.set(sessionId, turn);
+    return { turn, done, stopTimers: () => clearTurnTimers(turn) };
+  }
+  /**
+   * idle 主判定的事件刷新（P0-1 D1）：本 turn 任何事件到达即重置 idle 倒数——
+   * 活跃事件流零误杀的结构保证。总上界不受影响（固定倒数）。已落定 turn 无
+   * timer 可刷新（只剩 lastEventAt 记账）。
+   */
+  refreshIdle(turn) {
+    turn.lastEventAt = Date.now();
+    if (turn.settled || turn.idleTimer === void 0) return;
+    clearTimeout(turn.idleTimer);
+    turn.idleTimer = armTurnTimer(() => turn.fireTimeout("idle"), turn.idleMs);
+  }
+  lookupTurn(sessionId) {
+    if (sessionId !== void 0) return this.activeTurns.get(sessionId);
+    const pending = [];
+    for (const t of this.activeTurns.values()) if (!t.settled) pending.push(t);
+    return pending.length === 1 ? pending[0] : void 0;
+  }
+  /**
+   * turn.terminal 专用归因（P0-1 U1/S5 归因放宽）：在 `lookupTurn` 基础上放宽
+   * 「已落定 turn 不再受理」——权威终态晚于 final-frame 宽松终态到达（runTurn
+   * 收尾窗口内 turn 仍在册）时仍归因，**只记录 status 不改写落定结果**（D5①）。
+   * 带 sid 精确归因（落定与否均可）；无 sid 仍守宁丢勿错：唯一未落定优先，
+   * 全部落定且在册仅剩一个（单任务收尾窗口的典型形态）才归因，多在途丢弃。
+   */
+  lookupTurnForTerminal(sessionId) {
+    if (sessionId !== void 0) return this.activeTurns.get(sessionId);
+    const pending = [];
+    for (const t of this.activeTurns.values()) if (!t.settled) pending.push(t);
+    if (pending.length === 1) return pending[0];
+    if (pending.length === 0 && this.activeTurns.size === 1) {
+      return [...this.activeTurns.values()][0];
+    }
+    return void 0;
+  }
+  handleSessionEvent(params) {
+    const turn = this.lookupTurn(extractPushSessionId(params));
+    if (turn === void 0) return;
+    const payload = isRecord3(params) && isRecord3(params.payload) ? params.payload : void 0;
+    if (payload === void 0) return;
+    this.refreshIdle(turn);
+    if (this.applyFinalFrame(turn, payload)) return;
+    this.applyStreamDelta(turn, payload);
+  }
+  /**
+   * 收尾帧判定与吸收（A.2 ⑤ 两种形态：payload.response / stopReason+content 变体）。
+   * 命中任一形态则落 finalText/finalUsage 并以 final-frame 宽松终态收口，返回 true。
+   */
+  applyFinalFrame(turn, payload) {
+    if (typeof payload.response === "string" && payload.response !== "") {
+      turn.finalText = payload.response;
+      if (isRecord3(payload.usage)) turn.finalUsage = payload.usage;
+      turn.settle({ status: "success", source: "final-frame" });
+      return true;
+    }
+    if (payload.stopReason === "stop" && typeof payload.content === "string" && payload.content !== "") {
+      turn.finalText = payload.content;
+      if (isRecord3(payload.usage)) turn.finalUsage = payload.usage;
+      turn.settle({ status: "success", source: "final-frame" });
+      return true;
+    }
+    return false;
+  }
+  /** 增量 delta 分发：非空 delta 入账 + 回调；终态后迟到丢弃（不变量 2）。
+   *  kind 区分两通道（F2）：reasoning_delta 只走 thinking 回调（不入 deltas 账本
+   *  ——deltas 是 response 兜底聚合，推理文本不是答案正文）；text_delta / kind
+   *  缺席走 text 路径。 */
+  applyStreamDelta(turn, payload) {
+    if (typeof payload.delta !== "string" || payload.delta === "") return;
+    if (turn.settled) {
+      logger2.warn(
+        `\u7EC8\u6001\u540E\u8FDF\u5230\u7684 delta \u4E22\u5F03\uFF08\u4F1A\u8BDD ${turn.sessionId}\uFF0C\u4E0D\u53D8\u91CF 2\uFF1Aresolve \u540E\u4E0D\u518D\u53D1\u4E8B\u4EF6\uFF09: ${payload.delta.slice(
+          0,
+          DELTA_LOG_CHARS
+        )}`
+      );
+      return;
+    }
+    if (payload.kind === "reasoning_delta") {
+      turn.callbacks.onThinkingDelta?.(payload.delta);
+      return;
+    }
+    turn.deltas.push(payload.delta);
+    turn.callbacks.onTextDelta?.(payload.delta);
+  }
+  handleTelemetry(params) {
+    if (!isRecord3(params)) return;
+    if (params.kind === "turn.terminal") {
+      this.applyTerminalTelemetry(params);
+      return;
+    }
+    if (params.kind === "stream.chunk") {
+      this.applyStreamChunkTelemetry(params);
+    }
+  }
+  /** turn.terminal 遥测的吸收（含已落定 turn 的只记录路径，见 D5①）。 */
+  applyTerminalTelemetry(params) {
+    const turn = this.lookupTurnForTerminal(extractPushSessionId(params));
+    if (turn === void 0) return;
+    const status = typeof params.status === "string" ? params.status : "unknown";
+    turn.lastTerminalStatus = status;
+    this.recordTerminalError(turn, params);
+    if (turn.settled) {
+      logger2.warn(
+        `\u6743\u5A01\u7EC8\u6001\u665A\u4E8E\u843D\u5B9A\u7ED3\u679C\u5230\u8FBE\uFF08\u4F1A\u8BDD ${turn.sessionId}\uFF0C\u5DF2\u843D\u5B9A source=${turn.terminal?.source}\uFF09\uFF1Aturn.terminal status="${status}" \u4EC5\u8BB0\u5F55\u4E0D\u6539\u5199\uFF08P0-1 D5\u2460\uFF09`
+      );
+      return;
+    }
+    turn.settle({ status, source: "turn.terminal" });
+  }
+  /** terminal 帧专属错误信息入账（⛔P-Z2 实证：真实 failed 终态的 errorCode/errorMessage
+   *  只在 terminal 帧携带，read/delta 拿不到——先到/迟到都记录，消费层合成失败
+   *  文案时优先采信）。二者均缺失时不挂 lastTerminalError 字段。 */
+  recordTerminalError(turn, params) {
+    const errorCode = typeof params.errorCode === "string" ? params.errorCode : void 0;
+    const errorMessage = typeof params.errorMessage === "string" ? params.errorMessage : void 0;
+    if (errorCode === void 0 && errorMessage === void 0) return;
+    turn.lastTerminalError = {
+      ...errorCode !== void 0 ? { code: errorCode } : {},
+      ...errorMessage !== void 0 ? { message: errorMessage } : {}
+    };
+  }
+  /** stream.chunk 遥测的吸收（无文本遥测 + 文本字段漂移兜底）。 */
+  applyStreamChunkTelemetry(params) {
+    const turn = this.lookupTurn(extractPushSessionId(params));
+    if (turn === void 0 || turn.settled) return;
+    this.refreshIdle(turn);
+    for (const key of ["chunk", "text", "content"]) {
+      const v = params[key];
+      if (typeof v === "string" && v !== "") {
+        turn.deltas.push(v);
+        turn.callbacks.onTextDelta?.(v);
+        return;
+      }
+    }
+  }
+  /** 终态后 read（A.2 ⑥）。失败/超时不抛——降级链由 runTurn 收口（read 只兜底不致命）。
+   *  连接已死时跳过（与 closeSession 同判——对死连接发请求会凭空重建进程）。 */
+  async readBestEffort(sessionId) {
+    if (!this.conn.alive) return void 0;
+    try {
+      return await this.conn.request(
+        "session/read",
+        { sessionId },
+        {
+          timeoutMs: ZCODE_APPSERVER_TURN_READ_TIMEOUT_MS
+        }
+      );
+    } catch (err) {
+      logger2.warn(
+        `session/read \u515C\u5E95\u5931\u8D25\uFF08\u4F1A\u8BDD ${sessionId}\uFF0C\u964D\u7EA7\u6536\u5C3E\u5E27/delta \u805A\u5408\uFF09: ${errMessage2(
+          err
+        )}`
+      );
+      return void 0;
+    }
+  }
+};
+
+// src/zcode-engine.ts
+var logger3 = (0, import_subagent_engine_sdk8.getLogger)("subagents");
+var PROBE_VERSION_TIMEOUT_MS = 15e3;
+var COMMON_THOUGHT_LEVELS = ["low", "high", "max"];
+var ZcodeEngine = class {
+  id = ZCODE_ENGINE_ID;
+  deps;
+  probeCache;
+  appserverRuntime;
+  /**
+   * [P0-1 U4] 引擎停机标志（dispose 置位，不重置——dispose 后首个 run 走重建路径
+   * 不受影响）：瞬时重试判定据此排除 dispose 收割引发的崩溃形态——停机后的重试轮
+   * 会经 ensureAppServerRuntime 惰性重建进程（复活已停机引擎），违背 dispose 防泄漏
+   * 语义。
+   */
+  disposed = false;
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /**
+   * zcode 链路实际接通的能力（D3 链路口径。声明升级必须先改链路再改声明（C4 原则）。
+   */
+  capabilities() {
+    return {
+      // 无 --json-schema 类通道；公共 schema 仿真层（prompt 约定 + 容错提取 + ajv）
+      schemaEnforcement: "emulated",
+      // send-while-running 恒 -32010 硬错误（旧实测）——app-server 常驻化不改变此判据
+      steer: "unsupported",
+      // 无同进程 idle 复用（D4：每任务自包含 create→run→close）
+      conversation: "unsupported",
+      // 无 --append-system-prompt flag（实测拒收）——persona 只能拼进 prompt
+      personaInjection: "prompt",
+      // app-server 推送流实时流出（session/event payload.delta → text_delta）
+      eventGranularity: "stream",
+      // 首期未接 worktree 隔离（公共层 worktree-manager 接入后升 emulated）
+      sandbox: "none",
+      // sqlite 三级 JOIN 完整重建 turns（reader 实测）
+      sessionRead: "full",
+      // --resume 冷启动可用（实测）
+      resume: "cold",
+      // abort 走 D3 链（stop→grace→killChain）但声明维持 kill-only 不升级（改链路
+      // 先于改声明；stop 链路经 conformance 真机验证后再评估升 native）
+      interrupt: "kill-only",
+      // --mode build/edit/plan/yolo 原生权限档位
+      permissionMode: "native",
+      // [D3-④] 无 turn_end 语义，轮数上限不可兑现（预检 gate 据此同步拒绝）
+      maxTurns: false
+    };
+  }
+  /** 探针（D7）：二进制存在 + 版本解析（zcode 无公开契约，版本漂移的入口信号）。 */
+  async probe(opts) {
+    if (!opts?.force && this.probeCache) return this.probeCache;
+    const cliPath = this.deps.cliPath ?? ZCODE_CLI_DEFAULT_PATH;
+    const binary = this.probeBinaryCheck(cliPath);
+    const checks = [binary];
+    let engineVersion = "";
+    if (binary.ok) {
+      const version = await this.probeVersionCheck(cliPath);
+      checks.push(version.check);
+      engineVersion = version.engineVersion;
+    }
+    const ok = checks.every((c) => c.ok);
+    const report = {
+      ok,
+      engineVersion,
+      checks,
+      ...ok ? {} : { error: this.probeFailureRecovery(cliPath) }
+    };
+    this.probeCache = report;
+    return report;
+  }
+  /** check 1：二进制存在性（isFile 才算——同名目录不是可执行入口）。 */
+  probeBinaryCheck(cliPath) {
+    const binaryOk = fs5.existsSync(cliPath) && fs5.statSync(cliPath).isFile();
+    return {
+      name: "binary",
+      ok: binaryOk,
+      detail: binaryOk ? cliPath : `zcode CLI \u4E0D\u5B58\u5728\uFF1A${cliPath}`
+    };
+  }
+  /** check 2：`--version` 解析（probeVersion 可注入——测试 fake 防真实子进程）。 */
+  async probeVersionCheck(cliPath) {
+    const runVersion = this.deps.probeVersion ?? ((cliPath2) => defaultProbeVersion(cliPath2, this.deps.engineDataDir()));
+    const version = await runVersion(cliPath);
+    const versionOk = version !== void 0 && version.length > 0;
+    return {
+      check: {
+        name: "version",
+        ok: versionOk,
+        detail: versionOk ? version : "zcode --version \u8FD4\u56DE\u7A7A\u6216\u5931\u8D25"
+      },
+      engineVersion: version ?? ""
+    };
+  }
+  /** 探针失败的恢复指引（§3.3.3 终态四：版本确认命令 + 探针重跑 + 调研文档路径）。 */
+  probeFailureRecovery(cliPath) {
+    return {
+      code: "engine_probe_failed",
+      recovery: `Run \`node ${cliPath} --version\` \u786E\u8BA4 zcode CLI \u53EF\u7528\u4E14\u7248\u672C\u672A\u6F02\u79FB\uFF0C\u7136\u540E\u91CD\u8DD1\u63A2\u9488\uFF08\u91CD\u65B0\u521D\u59CB\u5316\u5F15\u64CE\u6216 probe({force:true})\uFF09\u3002\u82E5 app-server \u534F\u8BAE\u5DF2\u6F02\u79FB\uFF08RPC \u9519\u8BEF\uFF09\uFF0C\u91CD\u542F ZCode \u6216\u56FA\u5B9A zcode \u7248\u672C\u540E\u91CD\u8BD5\u3002\u53C2\u7167 docs/research/agent-engine-zcode.md\u3002`
+    };
+  }
+  /** D1 主语义：唯一通道 = app-server 常驻连接（spawn 降级链已删除）。 */
+  async run(task, ctx) {
+    return this.runViaAppServer(task, ctx);
+  }
+  // ============================================================
+  // app-server 常驻路径（D1/D3/D4）
+  // ============================================================
+  /**
+   * 常驻路径主编排：模型解析（v2 单源校验）→ 惰性连接 + runTurn（事件时序前移：
+   * text_delta 流式、终态后 message_end/turn_end）→ schema 仿真重试 → outcome/handle。
+   * poolKey 固定 'shared'（共享宿主 HOME，无池），onPoolResolved 在 prepare 期、
+   * onHandleReady 在 create 应答后（§3.4 不变量 3）。
+   */
+  async runViaAppServer(task, ctx) {
+    const startedAt = Date.now();
+    if (ctx.signal?.aborted === true) {
+      return this.abortedAppServerRun(task, ctx, startedAt);
+    }
+    const modelRef = resolveZcodeModelRef(task.model, this.deps.sources);
+    this.warnIgnoredCtxModel(task, ctx, modelRef);
+    this.warnThoughtLevelUncommon(task, ctx);
+    ctx.onPoolResolved?.(ZCODE_SHARED_POOL_KEY);
+    const cwd = task.cwd ?? process.cwd();
+    const schema = isPlainObject(task.schema) ? task.schema : void 0;
+    const basePrompt = this.buildPrompt(task, schema);
+    const usageAcc = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, has: false };
+    const final = await this.runAppServerAttemptsWithRetry(task, ctx, modelRef, cwd, basePrompt, schema, usageAcc);
+    const outcome = this.finalizeOutcome(task, ctx, final, usageAcc, startedAt);
+    return { handle: this.appServerHandle(outcome), outcome };
+  }
+  /** pre-aborted 短路收口：合成中止 outcome + 'shared' 锚定 handle。 */
+  abortedAppServerRun(task, ctx, startedAt) {
+    ctx.onPoolResolved?.(ZCODE_SHARED_POOL_KEY);
+    const outcome = this.finalizeOutcome(
+      task,
+      ctx,
+      abortedAppServerAttempt(ctx),
+      { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, has: false },
+      startedAt
+    );
+    return { handle: this.appServerHandle(outcome), outcome };
+  }
+  /**
+   * 首轮执行 + 双重试编排（常驻路径）：
+   * - **schema 仿真重试**（既有语义）：parsed 但校验失败时重试一次（强化 JSON 输出
+   *   指令——与 structured-output 的重试语义对齐）。
+   * - **瞬时失败自动重试一次**（[P0-1 U4/D6]）：末次 attempt 为 timeout 类（idle/
+   *   ceiling）或连接崩溃类失败且非用户 abort → 用新会话重跑一次（attempt 本就每次
+   *   新建会话）。重试轮 prompt 用 basePrompt 原样重跑（失败形态非 schema），文案补
+   *   「已自动重试一次」句（retried 标记仅对真实发生的重试生效）。
+   *
+   * 两次重试一次封顶各自独立（D6 被否①：多次重试/指数退避不做——重跑一轮=整任务
+   * 重算，一次封顶）。组合序：瞬时重试在前、schema 重试在后——瞬时重试轮 parsed 且
+   * 校验失败时仍进 schema 重试（末次 attempt 语义，schema 重试编排保持现状不动）。
+   *
+   * 重试轮是独立会话的独立 LLM 调用：token 计入 outcome.usage 总量；事件面
+   * text_delta 按实际流出（含失败轮——journal 记录真实流水），message_end/turn_end
+   * 只在最终轮终态后合成（不变量 2/5）。
+   */
+  async runAppServerAttemptsWithRetry(task, ctx, modelRef, cwd, basePrompt, schema, usageAcc) {
+    const attemptStartedAt = Date.now();
+    let final = await this.attemptAppServerTurn(task, ctx, modelRef, cwd, basePrompt);
+    accumulateUsage(usageAcc, final);
+    if (final.kind === "run-failed" && final.transient !== void 0 && ctx.signal?.aborted !== true && !this.disposed) {
+      const budget = resolveTransientRetryBudget(explicitTurnBudgetMs(), Date.now() - attemptStartedAt);
+      if (budget.state === "depleted") {
+        logger3.warn(
+          `[zcode-engine] \u672B\u6B21 attempt \u77AC\u65F6\u5931\u8D25\uFF08${final.transient}\uFF09\u2014\u2014\u663E\u5F0F\u603B\u4E0A\u754C\u9884\u7B97\u5269\u4F59\u4E0D\u8DB3 ${ZCODE_TURN_RETRY_MIN_BUDGET_MS}ms\uFF0C\u4E0D\u91CD\u8BD5\u76F4\u63A5\u7EC8\u6001\u5316\uFF08\u9884\u7B97\u7EE7\u627F\uFF1A\u91CD\u8BD5\u4E0D\u91CD\u7F6E\u603B\u9884\u7B97\uFF09`
+        );
+      } else {
+        logger3.warn(
+          `[zcode-engine] \u672B\u6B21 attempt \u77AC\u65F6\u5931\u8D25\uFF08${final.transient}\uFF09\u2014\u2014\u6B62\u635F\u94FE\u5DF2\u7EC8\u5C40\uFF0C\u65B0\u4F1A\u8BDD\u81EA\u52A8\u91CD\u8BD5\u4E00\u6B21` + (budget.state === "inherit" ? `\uFF08\u9884\u7B97\u7EE7\u627F\uFF1A\u91CD\u8BD5\u8F6E\u603B\u4E0A\u754C=\u5269\u4F59 ${budget.remainingMs}ms\uFF0C\u4E0D\u91CD\u7F6E\u603B\u9884\u7B97\uFF09` : "\uFF08\u65E0\u663E\u5F0F\u603B\u4E0A\u754C\u9884\u7B97\uFF0C\u91CD\u8BD5\u8F6E\u8D70 env/\u9ED8\u8BA4\u4E0A\u754C\uFF09")
+        );
+        const retry = await this.attemptAppServerTurn(task, ctx, modelRef, cwd, basePrompt, {
+          // 预算继承传递点（D2 内部传参面）：显式预算 → 剩余值；无显式预算 → 缺省
+          // （channel 侧走同一 env/默认，与首轮行为一致）
+          ...budget.state === "inherit" ? { turnTimeoutMs: budget.remainingMs } : {},
+          // 重试事实进文案：「已自动重试一次」句仅对真实发生的重试生效（未重试形态
+          // 不含——与行为一致，§5.2 F-1/F-4）
+          retried: true
+        });
+        accumulateUsage(usageAcc, retry);
+        final = retry;
+      }
+    }
+    if (final.kind === "parsed" && final.schemaResult !== void 0 && !final.schemaResult.ok && schema !== void 0) {
+      const retryPrompt = appendSchemaRetryDirective(basePrompt, final.schemaResult.error);
+      const retry = await this.attemptAppServerTurn(task, ctx, modelRef, cwd, retryPrompt);
+      accumulateUsage(usageAcc, retry);
+      final = retry;
+    }
+    return final;
+  }
+  /**
+   * 常驻路径的 handle 合成（poolKey 固定 'shared'；dbPath = 隔离会话库绝对路径——
+   * 2026-09 会话库隔离，与 spawn env 同源 zcodeSessionDbPath(engineDataDir)，设计 D1）。
+   */
+  appServerHandle(outcome) {
+    return {
+      data: {
+        v: 1,
+        engineId: ZCODE_ENGINE_ID,
+        sessionRef: {
+          dbPath: zcodeSessionDbPath(this.deps.engineDataDir()),
+          ...outcome.sessionId !== void 0 ? { sessionId: outcome.sessionId } : {}
+        },
+        poolKey: ZCODE_SHARED_POOL_KEY,
+        ...this.probeCache?.engineVersion !== void 0 && this.probeCache.engineVersion !== "" ? { engineVersion: this.probeCache.engineVersion } : {},
+        adapterVersion: ZCODE_ADAPTER_VERSION
+      }
+    };
+  }
+  /**
+   * 单轮常驻执行：runTurn 组合面 + D3 abort 链 + 事件前移（text_delta 实时流出；
+   * 终态数据经 read 兜底收口后才 resolve——不变量 1/2）。
+   *
+   * @param opts turnTimeoutMs：显式总上界传参面（D2 内部传参点）——U4/D6 预算继承
+   *   向重试轮传剩余值；缺省不传（channel 走 env→默认，首轮行为）。
+   *   retried：瞬时重试轮标记——失败文案补「已自动重试一次」句（F-1/F-4）。
+   */
+  async attemptAppServerTurn(task, ctx, modelRef, cwd, prompt, opts = {}) {
+    const rt = this.ensureAppServerRuntime();
+    const { providerId, modelId } = splitZcodeModelRef(modelRef);
+    const createParams = buildAppServerCreateParams(task, providerId, modelId, cwd);
+    let currentSessionId;
+    let signalSessionCreated;
+    const sessionCreated = new Promise((resolve) => {
+      signalSessionCreated = resolve;
+    });
+    const turn = rt.channel.runTurn(createParams, prompt, {
+      // 事件时序前移：payload.delta → text_delta 实时流出（stream 粒度，D5）；
+      // reasoning_delta → thinking_delta 分流（F2 口径：answer 通道仅 text_delta，
+      // 不变量 3a 的拼接比对不含 reasoning）
+      onTextDelta: (delta) => ctx.onEvent?.({ type: "text_delta", delta }),
+      onThinkingDelta: (delta) => ctx.onEvent?.({ type: "thinking_delta", delta }),
+      onSessionCreated: (sessionId) => {
+        currentSessionId = sessionId;
+        rt.activeSessions.add(sessionId);
+        signalSessionCreated?.();
+        ctx.onHandleReady?.({
+          sessionRef: { dbPath: zcodeSessionDbPath(this.deps.engineDataDir()), sessionId },
+          poolKey: ZCODE_SHARED_POOL_KEY
+        });
+      },
+      // 显式总上界传参（D2/U4：缺省缺席——channel 侧 resolveTurnTimerMs 走 env→默认）
+      ...opts.turnTimeoutMs !== void 0 ? { turnTimeoutMs: opts.turnTimeoutMs } : {}
+    });
+    const onAbort = () => {
+      void this.appServerAbortChain(rt, turn, () => currentSessionId, sessionCreated, { escalateOn: "turn-settled" });
+    };
+    if (ctx.signal !== void 0) {
+      if (ctx.signal.aborted) onAbort();
+      else ctx.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    try {
+      const r = await turn;
+      if (ctx.signal?.aborted === true) return abortedAppServerAttempt(ctx);
+      return parsedAppServerAttempt(task, r);
+    } catch (err) {
+      if (ctx.signal?.aborted === true) return abortedAppServerAttempt(ctx);
+      if (err instanceof TurnTimeoutError) {
+        const stopPath = await this.appServerAbortChain(
+          rt,
+          turn,
+          () => currentSessionId,
+          sessionCreated,
+          { escalateOn: "stop-outcome" }
+        );
+        return timeoutAppServerAttempt(err, currentSessionId, stopPath, { retried: opts.retried });
+      }
+      if (!isAppServerRpcError(err) && !rt.conn.alive) {
+        return failedAppServerAttempt(err, currentSessionId, { retried: opts.retried, transient: "conn-closed" });
+      }
+      return failedAppServerAttempt(err, currentSessionId, { retried: opts.retried });
+    } finally {
+      if (currentSessionId !== void 0) rt.activeSessions.delete(currentSessionId);
+      if (ctx.signal !== void 0) ctx.signal.removeEventListener("abort", onAbort);
+    }
+  }
+  /**
+   * killChain 后等待连接 finalize 实际完成（child 置空 + onClose 广播）再宣告链终局：
+   * shutdown resolve 于 `exit` 事件，而 finalize 挂 `close`（stdio 排空）——两者之间的
+   * 事件窗口内 conn.child 仍非 null，紧接的下一任务 request 会复用垂死进程（写入成功
+   * 但必败，走崩溃路径）而非触发重建。与 shutdownRuntimeAndDisposeChannel 的
+   * HARVEST_GRACE 同款 race 形态（close 永不到达不挂死）。超时入口的 await 链终局
+   * 语义（D6 重试时序依据）因此是「进程收割确认完成」而非「SIGTERM 已发出」。
+   */
+  async awaitConnFinalized(rt) {
+    if (!rt.conn.alive) return;
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => finish(), ZCODE_APPSERVER_HARVEST_GRACE_MS);
+      if (typeof timer.unref === "function") timer.unref();
+      const off = rt.conn.onClose(() => finish());
+      function finish() {
+        clearTimeout(timer);
+        off();
+        resolve();
+      }
+    });
+  }
+  /**
+   * D3 abort 链执行体（双入口分岔，P0-1 U2 参数化——设计
+   * timeout-zcode-turn-and-settled-watchdog.md §6 D3 v1.1）：
+   * - **用户取消入口**（`escalateOn: "turn-settled"`，现状语义零改动；fire-and-forget——
+   *   与 turn promise 并行推进）：stop 帧（超时 ZCODE_APPSERVER_STOP_TIMEOUT_MS）→
+   *   grace 窗口内 turn 落定即止（不杀共享进程）→ 超窗 killChain（conn.shutdown 全序：
+   *   SIGTERM→grace→SIGKILL）。turn 的最终落定由 attempt 主路径 await 收口，本链不
+   *   直接产出终态。abort 与 create 竞态（signal 先到、session 未建立）：等会话建立
+   *   （带上限）再发 stop——否则 stop 永远发不出，直接连坐杀共享进程。
+   * - **超时入口**（`escalateOn: "stop-outcome"`，channel 判死后由 catch await 链终局）：
+   *   turn 已 reject，对它 race 恒真不可用（v1 击穿点）——升级判据改挂在 **stop 应答
+   *   三态**：①成功应答 → 服务端接受停 turn，止损确认，链终止；②协议性 error 应答
+   *   （有 error 帧即控制面活的证据，多因 runTurn finally 的 closeSession 先行关会话，
+   *   健康形态竞态）→ 链终止**不升级**（止损由 close 回收 + 服务端自治承担；把
+   *   「stop 报错」一律升级会误杀健康共享进程并连坐并发任务）；③超时/写入失败/进程
+   *   死等连接级失败（控制面死）→ killChain 升级。判据实现依据：error 应答帧 reject
+   *   携带 number code（isAppServerRpcError）；连接级失败是无 code 的新 Error
+   *   （connection.request 三态 reject 形态）。返回值即止损路径（超时入口的 outcome
+   *   文案素材——D3 强制可观测面）。
+   */
+  async appServerAbortChain(rt, turn, getSessionId, sessionCreated, entry) {
+    const graceRaceThenKill = async () => {
+      const settled = await Promise.race([
+        turn.then(
+          () => true,
+          () => true
+        ),
+        delayResolved(ZCODE_APPSERVER_ABORT_GRACE_MS, false)
+      ]);
+      if (settled) return "settled-in-grace";
+      logger3.warn(
+        `[zcode-engine] abort grace \u7A97\u53E3\u5185\u672A\u89C1\u7EC8\u6001\u2014\u2014killChain \u6536\u5272\u5171\u4EAB\u8FDB\u7A0B\uFF08\u63A5\u53D7\u8FDE\u5750\uFF0C\u5728\u9014\u4EFB\u52A1\u8D70\u5D29\u6E83\u8DEF\u5F84\uFF09`
+      );
+      await rt.conn.shutdown({ graceMs: ZCODE_KILL_GRACE_MS });
+      await this.awaitConnFinalized(rt);
+      return "escalated-kill";
+    };
+    let sessionId = getSessionId();
+    if (sessionId === void 0) {
+      await Promise.race([sessionCreated, delayResolved(ZCODE_APPSERVER_STOP_TIMEOUT_MS, void 0)]);
+      sessionId = getSessionId();
+      if (sessionId === void 0) {
+        if (entry.escalateOn === "stop-outcome") return "no-session";
+        return graceRaceThenKill();
+      }
+    }
+    if (!rt.conn.alive) {
+      if (entry.escalateOn === "stop-outcome") return "stop-unreachable-killed";
+      return graceRaceThenKill();
+    }
+    try {
+      await rt.conn.request("session/stop", { sessionId }, { timeoutMs: ZCODE_APPSERVER_STOP_TIMEOUT_MS });
+    } catch (err) {
+      if (entry.escalateOn === "stop-outcome") {
+        if (isAppServerRpcError(err)) {
+          logger3.debug(
+            `[zcode-engine] session/stop \u62A5\u534F\u8BAE\u6027 error\uFF08${errMessage3(err)}\uFF09\u2014\u2014\u4F1A\u8BDD\u5DF2\u56DE\u6536\uFF0C\u63A7\u5236\u9762\u5B58\u6D3B\uFF0C\u4E0D\u5347\u7EA7\u6740\u94FE`
+          );
+          return "stop-rejected";
+        }
+        logger3.warn(
+          `[zcode-engine] session/stop \u65E0\u5E94\u7B54\uFF08${errMessage3(err)}\uFF09\u2014\u2014\u5347\u7EA7 killChain \u6536\u5272\u5171\u4EAB\u8FDB\u7A0B\uFF08\u8D85\u65F6\u5165\u53E3\uFF0C\u63A5\u53D7\u8FDE\u5750\uFF09`
+        );
+        await rt.conn.shutdown({ graceMs: ZCODE_KILL_GRACE_MS });
+        await this.awaitConnFinalized(rt);
+        return "stop-unreachable-killed";
+      }
+      logger3.debug(
+        `[zcode-engine] session/stop \u5931\u8D25\uFF08${errMessage3(err)}\uFF09\u2014\u2014grace \u540E\u8D70 killChain \u515C\u5E95`
+      );
+    }
+    if (entry.escalateOn === "stop-outcome") return "stop-acked";
+    return graceRaceThenKill();
+  }
+  // ── 常驻运行时管理（D1/D6）──────────────────────
+  /**
+   * 惰性获取常驻运行时（D1：每引擎实例一条连接，全任务共享；连接自身的崩溃重建在
+   * connection 层内部完成——同一条代码路径，§3.4 不变量 4）。常驻进程不进宿主
+   * spawnedChildren、不调 onChildSpawned（D6——生命周期归 dispose）。进程级 --cwd
+   * 用引擎数据目录（连接跨任务共享的中性位置，工作区由 create 的
+   * workspace.workspacePath 按任务传递——D10 基线不预设任务级进程 cwd）。
+   * spawn 经 fs 拦截 wrapper（appserver-launcher：cli config 读取重定向为
+   * 「真实文件 + v2 provider 注入」——CLI 形态 app-server 在共享宿主 HOME 下的
+   * 唯一凭据供数通路，机制与漂移面见该文件头注）。
+   */
+  ensureAppServerRuntime() {
+    if (this.appserverRuntime !== void 0) return this.appserverRuntime;
+    const cliPath = this.deps.cliPath ?? ZCODE_CLI_DEFAULT_PATH;
+    const engineDataDir = this.deps.engineDataDir();
+    const launcherScript = ensureAppServerLauncher(engineDataDir);
+    const env = buildAppServerEnv(this.deps.processEnv ?? process.env);
+    env.ZCODE_ENG_CLI_PATH = cliPath;
+    env.ZCODE_ENG_V2_CONFIG = this.deps.sources?.v2ConfigPath ?? defaultV2ConfigPath();
+    const sessionDbPath = zcodeSessionDbPath(engineDataDir);
+    env.ZCODE_SESSION_DB_PATH = sessionDbPath;
+    delete env.ZCODE_SESSION_DB;
+    fs5.mkdirSync(path4.dirname(sessionDbPath), { recursive: true });
+    const conn = new AppServerConnection({
+      cliPath,
+      dataDir: engineDataDir,
+      cwd: engineDataDir,
+      env,
+      launcherScript,
+      stderrLogPath: path4.join(engineDataDir, "logs", "zcode-appserver-stderr.log"),
+      // [W11] 实例维度 tee 路径（设计 §3.9）：文件名带当前代 app-server pid——
+      // 双实例（pi 宿主 + runtime 各一个引擎 CLI）并发 append/轮转互不干扰。
+      stderrLogPathResolver: (pid) => typeof pid === "number" ? stderrLogPathFor(engineDataDir, pid) : path4.join(engineDataDir, "logs", "zcode-appserver-stderr.log")
+    });
+    const rt = {
+      conn,
+      channel: new SessionChannel(conn),
+      activeSessions: /* @__PURE__ */ new Set()
+    };
+    this.appserverRuntime = rt;
+    return rt;
+  }
+  /**
+   * [R5 修复 R4 既有竞态] shutdown → 等崩溃收割实际发生 → channel 退订。killChain 在
+   * `exit` 事件 resolve，而连接 finalize（onClose → channel 的 failAllTurns）挂
+   * `close` 事件——两者之间有一个事件循环窗口：shutdown resolve 后立即退订，在途
+   * turn 会错过收割、挂到 turnTimeoutMs（300s）。退订前等 onClose 触发（本方法先于
+   * shutdown 订阅；channel 的订阅在构造期更早——其 failAllTurns 先于本 promise
+   * resolve 执行）；ZCODE_APPSERVER_HARVEST_GRACE_MS 兜底防 `close` 永不到达时挂死。
+   * [P0-1 U5/D7] grace race 输掉（close 迟到/永不到达——stdio 被孙进程持有排空不
+   * 尽等病态形态）时，channel.dispose() 内置的 dispose 收割（failAllTurns 先于退订，
+   * SessionChannel.dispose）兜底在途 turn——退化终点从「挂满 turn 自身 idle/总上界
+   * 预算」收敛为「grace 窗口内明确失败」（设计 §3.4 退化路径闭合）；race 窗口与
+   * awaitConnFinalized 同源同量级（ZCODE_APPSERVER_HARVEST_GRACE_MS）。正常 close
+   * 先到时 onClose 收割先行，dispose 收割幂等 no-op（零回归）。
+   */
+  async shutdownRuntimeAndDisposeChannel(rt) {
+    const harvested = new Promise((resolve) => {
+      const off = rt.conn.onClose(() => {
+        off();
+        resolve();
+      });
+    });
+    await rt.conn.shutdown({ graceMs: ZCODE_KILL_GRACE_MS });
+    await Promise.race([harvested, delayResolved(ZCODE_APPSERVER_HARVEST_GRACE_MS, void 0)]);
+    rt.channel.dispose();
+  }
+  /**
+   * [R1 D6 主体] 引擎停机面：①fire 全部在途会话的 session/close 帧（不等待
+   * 应答——D6① 顺序规定：close 帧必须先于 SIGTERM，否则对面来不及处理即被杀）→
+   * ②同步 SIGTERM（conn.shutdown 调用内 killChain 前缀同步执行——同步面在返回
+   * Promise 前完成）→ ③grace → SIGKILL（异步面，Promise resolve 于进程退出）。
+   * 幂等：运行时字段取走即置空，二次调用零副作用；dispose 后首个 run 经
+   * ensureAppServerRuntime 自动重建（与崩溃重建同一代码路径，不变量 4）。
+   */
+  async dispose() {
+    this.disposed = true;
+    const rt = this.appserverRuntime;
+    if (rt === void 0) return;
+    this.appserverRuntime = void 0;
+    if (rt.conn.alive) {
+      for (const sessionId of [...rt.activeSessions]) {
+        rt.conn.post("session/close", { sessionId });
+      }
+    }
+    await this.shutdownRuntimeAndDisposeChannel(rt);
+  }
+  /** 终态合成（extension-conventions 函数 80 行上限，从 run 提取）：aborted / run-failed / parsed 三分支。 */
+  finalizeOutcome(task, ctx, final, usageAcc, startedAt) {
+    const outcome = {
+      engineId: ZCODE_ENGINE_ID,
+      content: "",
+      durationMs: Date.now() - startedAt,
+      ...typeof task.worktree === "object" && task.worktree !== null ? { worktreePath: task.worktree.path } : {},
+      // D9① fallback 留痕：路由层经 RunContext 投影（zcode 无 record 通路，outcome 是
+      // 唯一留痕面；pi 引擎另有 record 投影）
+      ...ctx.engineFallback !== void 0 ? { engineFallback: ctx.engineFallback } : {}
+    };
+    const emit = (event) => {
+      ctx.onEvent?.(event);
+    };
+    if (final.kind === "aborted") {
+      this.applyAbortedOutcome(outcome, task, ctx, final, emit);
+    } else if (final.kind === "run-failed") {
+      this.applyRunFailedOutcome(outcome, final, emit);
+    } else {
+      this.applyParsedOutcome(outcome, final, usageAcc, emit);
+    }
+    return outcome;
+  }
+  /** abort 合成终态：exitCode=null（record 正常收尾，不留僵尸）。 */
+  applyAbortedOutcome(outcome, task, ctx, final, emit) {
+    outcome.exitCode = null;
+    outcome.error = isHostTimeoutAbort(ctx) ? (0, import_subagent_engine_sdk9.synthesizeTimeoutOutcome)(task, final.output.stdoutText, ZCODE_ENGINE_ID).error ?? (0, import_subagent_engine_sdk9.engineTimeoutDetail)(final.output.stdoutText) : final.abortMessage ?? `engine_run_failed: zcode \u4EFB\u52A1\u88AB\u4E2D\u6B62\uFF08app-server abort \u94FE\u6536\u53E3\uFF0C\u5BBF\u4E3B\u5408\u6210\u7EC8\u6001\uFF09\u3002\u8F93\u51FA\u5C3E\u90E8: ${final.output.stdoutText.slice(-ZCODE_ERROR_TAIL_CHARS)}`;
+    emit({ type: "error", message: outcome.error });
+  }
+  /**
+   * run-failed 合成终态：错误信息由 buildAppServerRunFailedMessage 产出（已含恢复
+   * 指引）直接透传；附带的会话 id 落 outcome.sessionId（错误规格表 -32004 行「含会话
+   * id」——appServerHandle 据此写 handle.sessionRef，run-failed 不再恒缺）。
+   */
+  applyRunFailedOutcome(outcome, final, emit) {
+    outcome.exitCode = final.output.exitCode;
+    if (final.sessionId !== void 0) outcome.sessionId = final.sessionId;
+    outcome.error = final.message;
+    emit({ type: "error", message: outcome.error });
+  }
+  /** parsed 合成终态：content/sessionId/usage 落位 + schema 校验分流 + coarse 事件。 */
+  applyParsedOutcome(outcome, final, usageAcc, emit) {
+    const payload = final.payload;
+    outcome.content = payload.response;
+    outcome.exitCode = final.output.exitCode;
+    if (payload.sessionId !== void 0) outcome.sessionId = payload.sessionId;
+    if (usageAcc.has) {
+      const last = payload.outcomeUsage;
+      outcome.usage = {
+        input: usageAcc.input,
+        output: usageAcc.output,
+        cacheRead: usageAcc.cacheRead,
+        cacheWrite: usageAcc.cacheWrite,
+        cost: 0,
+        contextTokens: last?.contextTokens ?? usageAcc.input + usageAcc.output + usageAcc.cacheRead + usageAcc.cacheWrite,
+        turns: last?.turns ?? 1
+      };
+    }
+    if (final.schemaResult !== void 0) {
+      if (final.schemaResult.ok) {
+        outcome.parsedOutput = final.schemaResult.parsed;
+      } else {
+        outcome.error = `schema_emulation_failed: zcode \u8F93\u51FA\u7ECF\u4E24\u8F6E\uFF08\u542B\u5F3A\u5316 prompt \u91CD\u8BD5\uFF09\u4ECD\u672A\u901A\u8FC7 schema \u6821\u9A8C\u3002\u672B\u8F6E\u5931\u8D25\u539F\u56E0: ${final.schemaResult.error}\u3002\u539F\u59CB\u8F93\u51FA\u5C3E\u90E8: ${final.schemaResult.tail}\u3002\u6062\u590D\u6307\u5F15\uFF1A\u7B80\u5316 schema \u6216\u62C6\u5C0F\u4EFB\u52A1\u540E\u91CD\u6D3E\uFF1B\u9700\u8981\u5F3A schema \u7EA6\u675F\u65F6\u6539\u7528 engine: pi\uFF08native schema \u6CE8\u5165\uFF09\u3002`;
+        emit({ type: "error", message: outcome.error });
+      }
+    }
+    for (const ev of synthesizeCoarseEvents(payload.response, payload.usage)) emit(ev);
+  }
+  /**
+   * D1 可选面：zcode 首期不支持 conversation（capabilities 声明）——同步拒绝、
+   * 不创建进程，文案给可操作建议（A11）。
+   */
+  async interact(_handle, _action) {
+    return {
+      ok: false,
+      code: "engine_capability_unsupported",
+      message: "zcode \u5F15\u64CE\u4E0D\u652F\u6301 conversation \u4EA4\u4E92\u63A7\u5236\u9762\uFF08capabilities.conversation = 'unsupported'\uFF0C\u6BCF\u4EFB\u52A1\u81EA\u5305\u542B\u4F1A\u8BDD\uFF0C\u65E0\u540C\u8FDB\u7A0B idle \u590D\u7528\uFF09\u3002\u6062\u590D\u6307\u5F15\uFF1A\u6539\u7528\u5355\u6B21 subagent \u8C03\u7528\u91CD\u65B0\u6D3E\u53D1\u4EFB\u52A1\uFF0C\u6216\u4F7F\u7528 engine: 'pi'\uFF08chatMode idle \u590D\u7528\uFF0C\u652F\u6301 message/close/cancel\uFF09\u3002"
+    };
+  }
+  /** [U7] 模型可发现性：v2 桌面登录态聚合（带凭据 provider × models），失败安全返回清单本身可能为空。 */
+  listModels() {
+    return listZcodeModels(this.deps.sources);
+  }
+  /**
+   * [u-h2 D2-2] 派发同步期 model 校验：委托 resolveZcodeModelRef（与 run prepare 期
+   * 同一函数——canonicalRef 归一化、短名缺省 provider、凭据与清单校验单一权威，无双实现）。
+   * modelRef undefined = 返回引擎缺省模型 canonical 全名（ZCODE_FALLBACK_DEFAULT_MODEL，
+   * D2-1 ctxModel 不透传的承接面）。校验失败原样抛 ZcodePrepareError，由编排层
+   * （engine/model-validation.ts）包装成「引擎与模型不配套」文案。
+   */
+  validateModel(modelRef) {
+    return { canonicalRef: resolveZcodeModelRef(modelRef, this.deps.sources) };
+  }
+  /**
+   * D6 read 三级降级：①sqlite 原生读取 → ②宿主 event journal 重放（对齐点①接线：
+   * replayJournalToSessionView 复用 live reducer，重放等价性见 §3.3.6）→ ③outcome-only。
+   * sessionId 缺失（解析失败的 run 无法定位 session）跳过①级；②级依赖
+   * handle.journalPath（宿主 run 后回填）。dbPath：新 handle 恒为隔离库绝对路径
+   * （zcodeSessionDbPath(engineDataDir)，tier1 白名单集合见方法体——宿主路径仅
+   * 「共享 HOME 时代」存量兼容）；旧 records（池时代）的相对路径仍按 poolKey
+   * 锚定解析（read 兼容旧数据，池目录不存在时自然落②级 journal 降级）。
+   */
+  async read(handle) {
+    if (handle.data.engineId !== ZCODE_ENGINE_ID) {
+      return { engineId: ZCODE_ENGINE_ID, turns: [], source: "outcome-only" };
+    }
+    const sessionId = handle.data.sessionRef["sessionId"];
+    const dbPathRaw = handle.data.sessionRef["dbPath"];
+    if (typeof sessionId === "string" && typeof dbPathRaw === "string") {
+      let dbPath;
+      if (path4.isAbsolute(dbPathRaw)) {
+        if (zcodeDbPathAllowlist(this.deps.engineDataDir()).includes(dbPathRaw)) {
+          dbPath = dbPathRaw;
+        } else {
+          logger3.warn("[zcode-engine] record dbPath \u975E\u767D\u540D\u5355 db \u7EDD\u5BF9\u8DEF\u5F84\uFF0C\u62D2\u7EDD \u2460\u7EA7\u8BFB\u53D6\u964D journal", {
+            dbPath: dbPathRaw
+          });
+        }
+      } else {
+        dbPath = path4.join(
+          (0, import_subagent_engine_sdk9.resolvePoolDir)(this.deps.engineDataDir(), ZCODE_ENGINE_ID, handle.data.poolKey),
+          dbPathRaw
+        );
+      }
+      if (dbPath !== void 0) {
+        try {
+          return await readZcodeSessionView(dbPath, sessionId);
+        } catch (err) {
+          logger3.warn("[zcode-engine] native session read failed, degrade to journal replay", {
+            dbPath,
+            sessionId,
+            reason: (0, import_subagent_engine_sdk3.toErrorMessage)(err)
+          });
+        }
+      }
+    }
+    const journaled = replayJournalToSessionView(handle, ZCODE_ENGINE_ID);
+    if (journaled !== void 0) return journaled;
+    return { engineId: ZCODE_ENGINE_ID, turns: [], source: "outcome-only" };
+  }
+  // ── 内部 ──
+  /**
+   * [RX2-F1] appserver 路径的非常见档位提示：thinkingLevel → thoughtLevel 恒等透传
+   * （F15a），全 7 档放行不拦截——但部分档位（off/minimal/medium/xhigh 等）不在部分
+   * 模型的合法值域内（如 GLM-5.3 仅接受 low/high/max），app-server 侧对不支持的档位
+   * warn-skip（会话照常但档位静默失效），调用方无从察觉。此处仅对
+   * COMMON_THOUGHT_LEVELS 之外的档位出声一行提示（措辞是「若不支持将被忽略/回落」的
+   * 或然警告，非无效断言）；是否真不支持由目标模型决定，core 不做权威校验（引擎层
+   * 不掌握各模型值域）。
+   */
+  warnThoughtLevelUncommon(task, ctx) {
+    const thoughtLevel = task.thinkingLevel?.trim();
+    if (thoughtLevel === void 0 || thoughtLevel === "") return;
+    if (COMMON_THOUGHT_LEVELS.includes(thoughtLevel)) return;
+    logger3.warn(
+      `[zcode-engine] thinkingLevel=${thoughtLevel} \u5DF2\u900F\u4F20\u4E3A thoughtLevel\uFF08\u975E\u5E38\u89C1\u6863\u4F4D\uFF09\uFF1A\u82E5\u76EE\u6807\u6A21\u578B\u4E0D\u652F\u6301\u8BE5\u6863\u4F4D\u5C06\u88AB\u5FFD\u7565/\u56DE\u843D\u5230\u6A21\u578B\u7F3A\u7701\u63A8\u7406\u6863\u4F4D\uFF08\u5E38\u89C1\u6863\u4F4D\uFF1A${COMMON_THOUGHT_LEVELS.join("/")}\uFF09\uFF1B\u6863\u4F4D\u662F\u5426\u751F\u6548\u4EE5\u6A21\u578B\u5B9E\u9645\u884C\u4E3A\u4E3A\u51C6`,
+      { taskId: ctx.taskId }
+    );
+  }
+  /**
+   * [F16b] ctxModel 忽略留痕：ctxModel 是 pi 链路的第三层兜底（port.ts 契约——
+   * 依赖 pi resolveModel 链的引擎才消费它），zcode 自带 provider 体系与缺省模型
+   * （resolveZcodeModelRef：requested > ZCODE_FALLBACK_DEFAULT_MODEL），不消费
+   * ctxModel。「调用方给了 ctxModel 但 task.model 未显式指定」时出声一行，说明
+   * 实际落引擎缺省模型（含实际 model id）——防静默降档无据可查。只在「ctx 有模型
+   * 但被忽略」场景输出：显式 task.model 走正常解析链、ctx 本就无模型属预期缺省，
+   * 均不出声（避免噪音）。
+   */
+  warnIgnoredCtxModel(task, ctx, modelRef) {
+    if (ctx.ctxModel === void 0) return;
+    const requested = task.model?.trim();
+    if (requested !== void 0 && requested !== "") return;
+    logger3.warn(
+      `[zcode-engine] ctx.ctxModel\uFF08${ctx.ctxModel.id}\uFF09\u88AB\u5FFD\u7565\u2014\u2014ctxModel \u662F pi \u94FE\u8DEF\u515C\u5E95\uFF0Czcode \u4E0D\u6D88\u8D39\uFF1Btask.model \u672A\u663E\u5F0F\u6307\u5B9A\uFF0C\u5B9E\u9645\u4F7F\u7528\u5F15\u64CE\u7F3A\u7701\u6A21\u578B ${modelRef}`,
+      { taskId: ctx.taskId }
+    );
+  }
+  /**
+   * persona 拼接后的完整 prompt（personaInjection: 'prompt'——zcode 无 flag 通道）：
+   * appendSystemPrompt 段在前（人设/约束语境——D6 合流后 persona≡skillPath+
+   * appendSystemPrompt 平铺，由上游解析进 appendSystemPrompt），task 正文居中，
+   * schema 仿真段尾置（common/schema-emulation 公共层产出）。
+   */
+  buildPrompt(task, schema) {
+    const segments = [...task.appendSystemPrompt ?? []];
+    segments.push(task.prompt);
+    if (schema !== void 0) segments.push((0, import_subagent_engine_sdk9.buildSchemaEmulationSegment)(schema));
+    return segments.join("\n\n");
+  }
+};
+var ZCODE_TURN_RETRY_MIN_BUDGET_MS = 3e5;
+function resolveTransientRetryBudget(totalBudgetMs, consumedMs) {
+  if (totalBudgetMs === void 0) return { state: "unbounded" };
+  const remainingMs = totalBudgetMs - consumedMs;
+  return remainingMs >= ZCODE_TURN_RETRY_MIN_BUDGET_MS ? { state: "inherit", remainingMs } : { state: "depleted" };
+}
+function explicitTurnBudgetMs() {
+  const parsed = parseZcodeTurnTimeoutEnv(process.env[ZCODE_TURN_MAX_TIMEOUT_ENV]);
+  return parsed.state === "valid" && parsed.ms > 0 ? parsed.ms : void 0;
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function errMessage3(err) {
+  return (0, import_subagent_engine_sdk3.toErrorMessage)(err);
+}
+function delayResolved(ms, value) {
+  return new Promise((resolve) => {
+    const t = setTimeout(() => resolve(value), ms);
+    if (typeof t.unref === "function") t.unref();
+  });
+}
+function syntheticAppServerOutput(exitCode) {
+  return { exitCode, stdoutText: "", stderrTail: "" };
+}
+function abortedAppServerAttempt(ctx) {
+  void ctx;
+  return {
+    kind: "aborted",
+    output: syntheticAppServerOutput(null),
+    abortMessage: `engine_run_failed: zcode \u4EFB\u52A1\u88AB\u4E2D\u6B62\uFF08app-server abort \u94FE\uFF1Asession/stop \u2192 ${ZCODE_APPSERVER_ABORT_GRACE_MS}ms grace \u786E\u8BA4 \u2192 \u8D85\u65F6 killChain SIGTERM\u2192${ZCODE_KILL_GRACE_MS}ms\u2192SIGKILL \u6536\u5272\u5171\u4EAB\u8FDB\u7A0B\uFF0C\u5728\u9014\u4EFB\u52A1\u8D70\u5D29\u6E83\u8DEF\u5F84\uFF09\u3002`
+  };
+}
+function turnResultToPayload(r) {
+  return {
+    response: r.response,
+    sessionId: r.sessionId,
+    ...mapZcodeUsage(r.usage) !== void 0 ? { usage: mapZcodeUsage(r.usage) } : {},
+    ...mapZcodeOutcomeUsage(r.usage, void 0) !== void 0 ? { outcomeUsage: mapZcodeOutcomeUsage(r.usage, void 0) } : {}
+  };
+}
+function buildAppServerRunFailedMessage(err, sessionId, retried = false) {
+  if (isAppServerRpcError(err) && err.code === ZCODE_APPSERVER_ERR_MODEL_CONFIG_MISSING && /Model config is missing/.test(err.message)) {
+    return `engine_credential_missing: app-server \u62A5 "Model config is missing"\uFF08\u5BBF\u4E3B HOME \u7684 zcode \u914D\u7F6E\u65E0\u53EF\u7528\u6A21\u578B\uFF09\u3002\u6062\u590D\u6307\u5F15\uFF1A\u5728 ZCode \u684C\u9762\u7AEF\u767B\u5F55\u5E76\u914D\u7F6E provider \u51ED\u636E\u540E\u91CD\u8DD1\u672C\u4EFB\u52A1\uFF08\u5E38\u9A7B\u8FDE\u63A5\u5728\u5F15\u64CE\u8FDB\u7A0B\u91CD\u542F\u540E\u751F\u6548\u65B0\u51ED\u636E\uFF09\u3002`;
+  }
+  if (isAppServerRpcError(err) && err.code === ZCODE_APPSERVER_ERR_BUSY_SESSION) {
+    const sid2 = sessionId !== void 0 ? `\uFF08\u4F1A\u8BDD id: ${sessionId}\uFF09` : "";
+    return `engine_run_failed: app-server \u62A5 -32010${sid2}\uFF08send \u65F6\u8BE5\u4F1A\u8BDD\u5DF2\u6709\u8F6E\u5728\u8DD1\uFF0Cbusy \u4E0D\u6392\u961F\u4E0D\u6253\u65AD\uFF09\u3002\u5355\u4F1A\u8BDD\u4E00\u4EFB\u52A1\u662F\u7ED3\u6784\u4FDD\u8BC1\uFF0C\u51FA\u73B0\u5373 bug\uFF1B\u8BF7\u9644\u5E26 sessionId \u4E0E state \u6D41\u6C34\uFF08\u8FDE\u63A5/\u4F1A\u8BDD\u4E8B\u4EF6\u65E5\u5FD7\uFF09\u4E0A\u62A5\u95EE\u9898\u3002`;
+  }
+  const code = isAppServerRpcError(err) && err.code !== void 0 ? `\uFF08code ${err.code}\uFF09` : "";
+  const sid = sessionId !== void 0 ? `\uFF08\u4F1A\u8BDD ${sessionId}\uFF09` : "";
+  const retryNote = retried ? `\u6062\u590D\u6307\u5F15\uFF1A\u76F4\u63A5\u91CD\u8DD1\u672C\u4EFB\u52A1\uFF08\u77AC\u65F6\u6545\u969C\u5DF2\u81EA\u52A8\u91CD\u8BD5\u4E00\u6B21\u4ECD\u5931\u8D25\uFF1B\u91CD\u8BD5\u7528\u7684\u662F\u5D29\u6E83\u540E\u81EA\u52A8\u91CD\u5EFA\u7684\u65B0\u4F1A\u8BDD\uFF09\u3002` : `\u6062\u590D\u6307\u5F15\uFF1A\u76F4\u63A5\u91CD\u8DD1\u672C\u4EFB\u52A1\uFF08\u8FDE\u63A5\u5D29\u6E83\u540E\u81EA\u52A8\u91CD\u5EFA\u8FDB\u7A0B\uFF09\uFF1B`;
+  return `engine_run_failed: app-server \u4F1A\u8BDD\u6267\u884C\u5931\u8D25${code}${sid}: ${errMessage3(err).slice(-ZCODE_ERROR_TAIL_CHARS)}\u3002${retryNote}\u82E5\u6301\u7EED\u5931\u8D25\uFF08\u7591\u4F3C zcode \u5347\u7EA7\u540E\u534F\u8BAE\u6F02\u79FB\u2014\u2014-32601/-32602 \u7C7B\u9519\u8BEF\uFF09\uFF0C\u91CD\u542F ZCode \u6216\u56FA\u5B9A zcode \u7248\u672C\u540E\u91CD\u8BD5\uFF0C\u6216\u6539\u7528 engine: pi\u3002`;
+}
+function accumulateUsage(acc, r) {
+  if (r.kind !== "parsed") return;
+  const u = r.payload.usage;
+  if (u === void 0) return;
+  acc.has = true;
+  acc.input += u.input;
+  acc.output += u.output;
+  acc.cacheRead += u.cacheRead;
+  acc.cacheWrite += u.cacheWrite;
+}
+function appendSchemaRetryDirective(basePrompt, validationError) {
+  return basePrompt + `
+
+## Retry: Structured Output Failed
+Your previous answer failed schema validation: ${validationError}
+Answer again. Output ONLY the JSON value conforming to the schema above \u2014 no prose, no markdown fences, no extra text.`;
+}
+function buildAppServerCreateParams(task, providerId, modelId, cwd) {
+  const denyTools = (task.denyTools ?? []).filter((t) => typeof t === "string" && t.trim() !== "");
+  const thoughtLevel = task.thinkingLevel?.trim();
+  return {
+    workspacePath: cwd,
+    mode: "yolo",
+    // per-session model（G3）：create 参数透传（A.2 ① strict 对象）——同进程任务
+    // 各用各的模型，互不干扰
+    model: { providerId, modelId },
+    ...thoughtLevel !== void 0 && thoughtLevel !== "" ? { thoughtLevel } : {},
+    ...denyTools.length > 0 ? { toolDenylist: denyTools } : {}
+  };
+}
+function authoritativeTerminalStatus(r) {
+  if (r.lastTerminalStatus !== void 0) return r.lastTerminalStatus;
+  return r.terminal.source === "turn.terminal" ? r.terminal.status : void 0;
+}
+function isFailedTerminalStatus(status) {
+  return status === "failed" || status === "error";
+}
+function parsedAppServerAttempt(task, r) {
+  if (isFailedTerminalStatus(authoritativeTerminalStatus(r))) {
+    return failedTerminalAppServerAttempt(r);
+  }
+  const schema = isPlainObject(task.schema) ? task.schema : void 0;
+  return {
+    kind: "parsed",
+    output: syntheticAppServerOutput(0),
+    payload: turnResultToPayload(r),
+    ...schema !== void 0 ? { schemaResult: (0, import_subagent_engine_sdk9.extractAndValidateStructuredOutput)(r.response, schema) } : {}
+  };
+}
+function failedTerminalAppServerAttempt(r) {
+  const status = authoritativeTerminalStatus(r);
+  const detail = r.lastTerminalError;
+  const detailParts = [];
+  if (detail?.code !== void 0) detailParts.push(`errorCode: ${detail.code}`);
+  if (detail?.message !== void 0) detailParts.push(detail.message);
+  let body;
+  if (detailParts.length > 0) {
+    body = `\u670D\u52A1\u7AEF\u9519\u8BEF\uFF1A${detailParts.join("\uFF1A")}\u3002`;
+  } else {
+    const tail = r.response.trim();
+    body = tail !== "" ? `\u670D\u52A1\u7AEF\u8FD4\u56DE\u5C3E\u90E8\uFF1A${tail.slice(-ZCODE_ERROR_TAIL_CHARS)}\u3002` : "\u670D\u52A1\u7AEF\u65E0\u8FD4\u56DE\u5185\u5BB9\uFF08read \u515C\u5E95/delta \u805A\u5408\u5747\u4E3A\u7A7A\uFF09\u3002";
+  }
+  return {
+    kind: "run-failed",
+    output: syntheticAppServerOutput(null),
+    message: `engine_run_failed: app-server \u7EC8\u6001 status=${status}\uFF08\u4F1A\u8BDD ${r.sessionId}\uFF09\u3002${body}
+\u{1F449} \u6062\u590D\u6307\u5F15\uFF1A\u9519\u8BEF\u5185\u5BB9\u6765\u81EA\u6A21\u578B/\u670D\u52A1\u7AEF\uFF1B\u76F4\u63A5\u91CD\u8DD1\uFF0C\u82E5\u6301\u7EED\u51FA\u73B0\u6838\u5BF9 ZCode \u684C\u9762\u7AEF\u51ED\u636E\u4E0E\u6A21\u578B\u914D\u7F6E\uFF08engine_credential_missing \u540C\u65CF\u6392\u67E5\uFF09\u3002`,
+    sessionId: r.sessionId
+  };
+}
+function failedAppServerAttempt(err, currentSessionId, opts = {}) {
+  return {
+    kind: "run-failed",
+    output: syntheticAppServerOutput(null),
+    message: buildAppServerRunFailedMessage(err, currentSessionId, opts.retried === true),
+    // [P0-1 U4/D6] 瞬时失败形态标记（重试判定判据——timeout 形态走
+    // timeoutAppServerAttempt，此处只承载 conn-closed）
+    ...opts.transient !== void 0 ? { transient: opts.transient } : {},
+    // 错误规格表 -32004 行「按任务失败上报（含会话 id）」：create 成功后运行中失败
+    // （-32004/-32010 等）时留痕会话 id——经 applyRunFailedOutcome 落 outcome.sessionId
+    // 与 handle.sessionRef（create 阶段失败无会话，缺省不带）
+    ...currentSessionId !== void 0 ? { sessionId: currentSessionId } : {}
+  };
+}
+function timeoutAppServerAttempt(err, currentSessionId, stopPath, opts = {}) {
+  return {
+    kind: "run-failed",
+    output: syntheticAppServerOutput(null),
+    message: buildAppServerTimeoutMessage(err, currentSessionId, stopPath, opts.retried === true),
+    transient: "timeout",
+    ...currentSessionId !== void 0 ? { sessionId: currentSessionId } : {}
+  };
+}
+function stopPathText(stopPath) {
+  switch (stopPath) {
+    case "stop-acked":
+      return "session/stop \u5DF2\u9001\u8FBE\uFF08\u670D\u52A1\u7AEF\u63A5\u53D7\u505C turn\uFF09";
+    case "stop-rejected":
+      return "session/stop \u62A5\u534F\u8BAE\u6027 error\uFF08\u4F1A\u8BDD\u5DF2\u88AB\u56DE\u6536\uFF0C\u63A7\u5236\u9762\u5B58\u6D3B\u2014\u2014\u6B62\u635F\u7531\u4F1A\u8BDD\u56DE\u6536\u627F\u62C5\uFF0C\u4E0D\u5347\u7EA7\u6740\u94FE\uFF09";
+    case "stop-unreachable-killed":
+      return `session/stop \u65E0\u5E94\u7B54\u5DF2\u5347\u7EA7\u6740\u94FE\uFF08SIGTERM\u2192${ZCODE_KILL_GRACE_MS}ms\u2192SIGKILL \u6536\u5272\u5171\u4EAB\u8FDB\u7A0B\uFF09`;
+    case "no-session":
+      return "\u4F1A\u8BDD\u672A\u5EFA\u7ACB\uFF08\u4EFB\u52A1\u672A\u5F00\u59CB\u6267\u884C\uFF0C\u65E0\u5728\u9014\u6D88\u8017\uFF09";
+    default:
+      return "grace \u7A97\u53E3\u5185\u7EC8\u6001\u843D\u5B9A\u6216\u5DF2\u8D70\u6740\u94FE";
+  }
+}
+function buildAppServerTimeoutMessage(err, sessionId, stopPath, retried = false) {
+  const sid = sessionId !== void 0 ? `\uFF08\u4F1A\u8BDD ${sessionId}\uFF09` : "";
+  const lastEventText = err.lastEventAt !== void 0 ? `\uFF0C\u6700\u540E\u4E8B\u4EF6 ${new Date(err.lastEventAt).toISOString()}` : "\uFF0C\u6574\u8F6E\u672A\u89C2\u5BDF\u5230\u4EFB\u4F55\u4E8B\u4EF6\uFF08\u8FDB\u7A0B\u5047\u6B7B/\u534F\u8BAE\u9759\u9ED8\u5F62\u6001\uFF09";
+  const head = err.kind === "idle" ? `engine_timeout: zcode turn \u8FDE\u7EED\u9759\u9ED8 ${err.thresholdMs}ms\uFF08idle \u5224\u5B9A${lastEventText}\uFF0C\u603B\u8017\u65F6 ${err.elapsed}ms\uFF09${sid}\u3002` : `engine_timeout: zcode turn \u603B\u4E0A\u754C ${err.thresholdMs}ms \u5185\u672A\u89C2\u5BDF\u5230\u7EC8\u6001\uFF08chatty-wedge \u5224\u5B9A\u2014\u2014\u4E8B\u4EF6\u6D41\u4ECD\u6D3B\u8DC3\u800C\u7EC8\u6001\u672A\u5230\u8FBE\uFF0C\u603B\u8017\u65F6 ${err.elapsed}ms\uFF09${sid}\u3002`;
+  const selfHelp = err.kind === "ceiling" ? `\u82E5\u672C\u4EFB\u52A1\u5C5E\u5408\u6CD5\u8D85\u957F\u4EFB\u52A1\uFF08\u9884\u671F\u8D85\u8FC7 ${err.thresholdMs}ms\uFF09\uFF0C\u91CD\u8DD1\u524D\u8BBE ${ZCODE_TURN_MAX_TIMEOUT_ENV} \u4E3A\u66F4\u5927\u6BEB\u79D2\u503C\u6216 0 \u5173\u95ED\u603B\u4E0A\u754C\uFF08\u5173\u95ED\u540E chatty \u5F62\u6001\u4E0D\u518D\u81EA\u52A8\u56DE\u6536\uFF0C\u9759\u9ED8 wedged \u4ECD\u7531 idle \u5C42\u515C\u5E95\u2014\u2014\u81EA\u884C\u6743\u8861\uFF09\u3002` : "";
+  const rerunGuide = retried ? `\u{1F449} \u6062\u590D\u6307\u5F15\uFF1A\u76F4\u63A5\u91CD\u8DD1\u672C\u4EFB\u52A1\uFF08\u77AC\u65F6\u6545\u969C\u5DF2\u81EA\u52A8\u91CD\u8BD5\u4E00\u6B21\u4ECD\u8D85\u65F6\uFF1B\u91CD\u8BD5\u5728\u6B62\u635F\u94FE\u7EC8\u5C40\u540E\u542F\u52A8\uFF0C\u65E0\u65B0\u65E7\u4EFB\u52A1\u53CC\u8DD1\u7A97\uFF09\uFF1B` : `\u{1F449} \u6062\u590D\u6307\u5F15\uFF1A\u76F4\u63A5\u91CD\u8DD1\u672C\u4EFB\u52A1\uFF1B`;
+  return `${head}\u6B62\u635F\u8DEF\u5F84\uFF1A${stopPathText(stopPath)}\u3002
+${rerunGuide}${selfHelp}\u82E5\u6301\u7EED\u51FA\u73B0\uFF0C\u68C0\u67E5 ZCode \u684C\u9762\u7AEF\u6A21\u578B\u8FDE\u901A\u6027\u6216\u6539\u7528 engine: pi\u3002`;
+}
+function isHostTimeoutAbort(ctx) {
+  return ctx.signal?.aborted === true && ctx.signal.reason === import_subagent_engine_sdk9.HOST_TIMEOUT_ABORT_REASON;
+}
+var PROBE_STDOUT_CAP_CHARS = 4096;
+async function defaultProbeVersion(cliPath, dataDir) {
+  try {
+    return await new Promise((resolve, reject) => {
+      const child = (0, import_subagent_engine_sdk9.spawnEngineChild)({
+        command: "node",
+        args: [cliPath, "--version"],
+        env: (0, import_subagent_engine_sdk9.buildEngineChildEnv)(process.env, { dataDir }),
+        stdout: "pipe",
+        stderr: "ignore",
+        signal: AbortSignal.timeout(PROBE_VERSION_TIMEOUT_MS)
+      });
+      let out = "";
+      child.stdout?.setEncoding("utf8");
+      child.stdout?.on("data", (chunk) => {
+        if (out.length < PROBE_STDOUT_CAP_CHARS) out += chunk;
+      });
+      child.once("error", reject);
+      child.once("close", (code) => {
+        if (code !== 0) reject(new Error(`zcode --version exited with code ${code}`));
+        else resolve(out.trim().split("\n")[0]?.trim() || void 0);
+      });
+    });
+  } catch (err) {
+    logger3.debug(
+      `[zcode-engine] probe version check failed (best-effort continue): ${(0, import_subagent_engine_sdk3.toErrorMessage)(err)}`
+    );
+    return void 0;
+  }
+}
+
+// src/registration.ts
+function defaultEngineDataDir() {
+  return (0, import_subagent_engine_sdk10.resolveEngineDataDir)(process.env);
+}
+function createZcodeEngine(deps) {
+  return new ZcodeEngine(deps);
+}
+function createDefaultZcodeEngine() {
+  return createZcodeEngine({
+    engineDataDir: defaultEngineDataDir,
+    ...process.env["XYZ_ZCODE_CLI"] !== void 0 ? { cliPath: process.env["XYZ_ZCODE_CLI"] } : {}
+  });
+}
+
+// src/port-types.ts
+var import_subagent_engine_sdk11 = require("@zhushanwen/subagent-engine-sdk");
+
+// src/server.ts
+var REVERSE_TIMEOUT_DEFAULT_MS = 6e4;
+var EngineProtocolServer = class {
+  write;
+  engine;
+  reverseClock;
+  reverseTimeoutMs;
+  activeRuns = /* @__PURE__ */ new Map();
+  reversePending = /* @__PURE__ */ new Map();
+  revSeq = 0;
+  initialized = false;
+  constructor(opts) {
+    this.write = opts.write;
+    this.engine = opts.engine ?? createDefaultZcodeEngine();
+    this.reverseClock = opts.reverseClock;
+    this.reverseTimeoutMs = opts.reverseTimeoutMs ?? REVERSE_TIMEOUT_DEFAULT_MS;
+  }
+  /** 入站帧消费（请求帧 + 反向请求应答帧；main.ts 的行解析器拆行后喂入）。 */
+  handleFrame(frame) {
+    if ((0, import_subagent_engine_sdk12.isResponseFrame)(frame)) {
+      this.settleReverse(frame.id, frame);
+      return;
+    }
+    if ((0, import_subagent_engine_sdk12.isReverseRequestFrame)(frame)) {
+      this.write({
+        id: 0,
+        error: {
+          code: "engine_protocol_bad_frame",
+          message: `unexpected reverse request frame from host: ${String(frame.method)}`,
+          recovery: "The engine protocol v1 only carries host/* requests engine\u2192host."
+        }
+      });
+      return;
+    }
+    if (typeof frame === "object" && frame !== null && "id" in frame && "method" in frame && typeof frame.method === "string") {
+      const { id, method, params } = frame;
+      if (typeof id === "number") {
+        void this.dispatch(id, method, params).then(
+          (result) => this.write({ id, result }),
+          (err) => this.write({ id, error: toProtocolError(err) })
+        );
+        return;
+      }
+    }
+  }
+  /** 10 正向方法分发（表驱动：method → 处理器；未知方法 → engine_protocol_unknown_method）。 */
+  async dispatch(id, method, params) {
+    const handler = this.methodHandlers[method];
+    if (handler === void 0) {
+      throw new import_subagent_engine_sdk12.EngineSdkError(
+        "engine_protocol_unknown_method",
+        `unknown protocol method: ${method} (request id ${id})`,
+        "The engine speaks protocol v1; check the installed engine package version vs the host."
+      );
+    }
+    return handler(params);
+  }
+  /**
+   * 10 正向方法 → 处理器映射（每个处理器消费原始 params 并自行收敛类型——
+   * 与原 switch case 表达式一一对应）。
+   */
+  methodHandlers = {
+    initialize: (p) => this.initialize(p),
+    probe: (p) => this.engine.probe(probeParamsOf(p)),
+    run: (p) => this.run(p),
+    cancel: (p) => this.cancel(p),
+    interact: (p) => this.interact(p),
+    read: (p) => this.read(p),
+    listModels: () => ({ models: this.engine.listModels?.() ?? null }),
+    validateModel: (p) => this.validateModel(p),
+    dispose: async () => {
+      await this.engine.dispose?.();
+      return { ok: true };
+    },
+    ping: () => ({ pong: true })
+  };
+  // ── initialize：版本协商（越界 → engine_protocol_mismatch）+ 能力应答 ──
+  initialize(params) {
+    if (params?.protocolVersion !== import_subagent_engine_sdk12.ENGINE_PROTOCOL_VERSION) {
+      throw new import_subagent_engine_sdk12.EngineSdkError(
+        "engine_protocol_mismatch",
+        `host protocol version ${String(params?.protocolVersion)} is not compatible with engine protocol v${import_subagent_engine_sdk12.ENGINE_PROTOCOL_VERSION}`,
+        `Upgrade the engine package or the host so both speak protocol v${import_subagent_engine_sdk12.ENGINE_PROTOCOL_VERSION}.`
+      );
+    }
+    this.initialized = true;
+    const models = this.engine.listModels?.() ?? null;
+    return {
+      protocolVersion: import_subagent_engine_sdk12.ENGINE_PROTOCOL_VERSION,
+      engineId: this.engine.id,
+      engineVersion: ZCODE_ADAPTER_VERSION,
+      adapterVersion: ZCODE_ADAPTER_VERSION,
+      capabilities: this.engine.capabilities(),
+      ...models !== null ? { models: models.map((m) => ({ id: m.id })) } : {}
+    };
+  }
+  // ── run：协议载荷 → 本地 AgentCallOpts/RunContext；事件 → 通知/host 通道 ──
+  async run(params) {
+    if (!this.initialized) {
+      throw new import_subagent_engine_sdk12.EngineSdkError(
+        "engine_protocol_not_initialized",
+        "run before initialize is a protocol violation",
+        "The host must complete the initialize handshake before dispatching runs."
+      );
+    }
+    const { runId, task, ctx } = params;
+    const controller = new AbortController();
+    const active = { controller, seq: 0 };
+    this.activeRuns.set(runId, active);
+    const fullTask = { ...task, ...ctx.model !== void 0 ? { model: ctx.model } : {} };
+    const ctxModel = (0, import_subagent_engine_sdk11.parseCtxModel)(ctx.ctxModel);
+    const stream = ctx.streamMode === "stream" ? { onDelta: (delta) => {
+      void this.reverseRequestInternal("host/streamDelta", { runId, delta });
+    } } : void 0;
+    const runCtx = {
+      taskId: runId,
+      poolKey: ctx.poolKey,
+      signal: controller.signal,
+      onEvent: (event) => this.emitEvent(runId, event),
+      ...ctxModel !== void 0 ? { ctxModel } : {},
+      ...stream !== void 0 ? { stream } : {},
+      ...ctx.schemaEnv !== void 0 ? { schemaEnv: ctx.schemaEnv } : {},
+      ...ctx.engineFallback !== void 0 ? { engineFallback: ctx.engineFallback } : {},
+      onPoolResolved: (poolKey) => {
+        void this.reverseRequestInternal("host/poolResolved", { runId, poolKey });
+      },
+      onHandleReady: (partial) => {
+        void this.reverseRequestInternal("host/handleReady", { runId, sessionRef: partial.sessionRef, poolKey: partial.poolKey });
+      }
+    };
+    try {
+      const r = await this.engine.run(fullTask, runCtx);
+      return { handle: r.handle.data, outcome: r.outcome };
+    } finally {
+      this.activeRuns.delete(runId);
+    }
+  }
+  cancel(params) {
+    const active = this.activeRuns.get(params.runId);
+    if (active !== void 0) active.controller.abort(new Error(`cancelled by host: ${params.reason}`));
+    return { ok: true };
+  }
+  async interact(params) {
+    return this.engine.interact({ data: params.handle }, params.action);
+  }
+  read(params) {
+    return this.engine.read({ data: params.handle });
+  }
+  validateModel(params) {
+    if (this.engine.validateModel === void 0) {
+      throw new import_subagent_engine_sdk12.EngineSdkError(
+        "engine_capability_unsupported",
+        "engine does not implement validateModel",
+        "Manifest omits modelCatalog; model validation falls back to run-time engine checks."
+      );
+    }
+    return this.engine.validateModel(params.modelRef);
+  }
+  // ── 出站：事件通知 + 反向请求客户端 ──
+  emitEvent(runId, event) {
+    const active = this.activeRuns.get(runId);
+    const seq = active !== void 0 ? ++active.seq : 0;
+    this.write({ method: "event", params: { runId, seq, event } });
+  }
+  /**
+   * 发反向请求并等应答（帧④必须应答）。计时面登记：发出 → clock.started；收到
+   * ack 形态应答 → clock.acked（两阶段第一段，等待不计超时）；终结 → clock.settled。
+   * 应答超时兜底 reject——数据面通道（host/log 等）core 10s 应答，reject 由调用方
+   * 吞掉留痕（数据面丢失不拖死主链路）。
+   */
+  /** 反向请求发送（公开面：main.ts 的 host/log 桥接消费；内部 run 通道同路）。 */
+  reverseRequest(method, params) {
+    return this.reverseRequestInternal(method, params);
+  }
+  reverseRequestInternal(method, params) {
+    const id = `rev-${++this.revSeq}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.reversePending.delete(id);
+        this.reverseClock?.settled(id);
+        reject(new Error(`reverse request ${method} (${id}) timed out after ${this.reverseTimeoutMs}ms`));
+      }, this.reverseTimeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+      this.reversePending.set(id, { resolve, reject, timer });
+      this.reverseClock?.started(id);
+      this.write({ id, method, params });
+    });
+  }
+  /** 反向请求应答落位（ack 两阶段：{ack:true}/{unsupported:true}/{ok:true} 均先 ack 计时面）。 */
+  settleReverse(id, frame) {
+    const pending = this.reversePending.get(String(id));
+    if (pending === void 0) return;
+    this.reversePending.delete(String(id));
+    clearTimeout(pending.timer);
+    this.reverseClock?.acked(String(id));
+    this.reverseClock?.settled(String(id));
+    if (frame.error !== void 0) pending.reject(new Error(`reverse request ${String(id)} rejected: ${(0, import_subagent_engine_sdk3.toErrorMessage)(frame.error)}`));
+    else pending.resolve(frame.result);
+  }
+};
+function probeParamsOf(params) {
+  return typeof params === "object" && params !== null ? params : void 0;
+}
+function toProtocolError(err) {
+  if (err instanceof import_subagent_engine_sdk12.EngineSdkError) return err.toStructured();
+  return {
+    code: "engine_run_failed",
+    message: (0, import_subagent_engine_sdk3.toErrorMessage)(err),
+    recovery: "Check the engine process logs (engineDataDir/logs/) and rerun; if persistent, reinstall or upgrade the engine package."
+  };
+}
+
+// src/main.ts
+var clock = (0, import_subagent_engine_sdk13.armEngineSelfDestruct)({ stdin: process.stdin });
+(0, import_subagent_engine_sdk13.runEngineCliEntry)({
+  component: "zcode-engine-cli",
+  server: new EngineProtocolServer({
+    write: (frame) => {
+      process.stdout.write(`${JSON.stringify(frame)}
+`);
+    },
+    reverseClock: clock
+  })
+});