@zhushanwen/subagent-core 0.2.0 → 0.4.0

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

@@ -1,25 +1,38 @@
 // src/execution/engine/engines/zcode/zcode-engine.ts
 //
-// ZcodeEngine（P3）：zcode CLI spawn 单轮模式的 EnginePort 实现。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D10（MVP 引擎集 + zcode 首期只做
-// spawn 单轮）、§3.3.4（reviewer@zcode 物理数据流）、§3.3.5（run 错误语义三条）。
+// ZcodeEngine（P3 → R4 双模式）：zcode CLI 的 EnginePort 实现。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D10（MVP 引擎集）/ §3.3.4（reviewer@zcode
+// 物理数据流）/ §3.3.5（run 错误语义三条）；docs/design/zcode-engine-appserver-resident.md
+// §3.3 D1（每引擎实例一条连接）/ D3（abort 链）/ D4（会话自包含）/ D5（capabilities
+// 升级序）/ D6（停机面 + 孤儿自愈）/ D7（常驻 HOME）/ §3.4 不变量 1-4。
+//
+// 双模式分派（R4；D2 降级链的骨架）：
+//   - appserver（缺省）：惰性常驻连接（connection.ts + session-channel.ts）上的
+//     create→subscribe→send→事件流→终态→read→close；per-session model 经 create
+//     参数透传；常驻 HOME = engines/zcode/home-appserver（D7 全量语义见 appserver-home.ts）；
+//     缺省路径带 R5 降级链门控：协议冒烟探针（appserver-probe.ts，结论与 CLI mtime
+//     绑定）失败 → 本任务起 spawn 直走；首任务命中漂移类 RPC 错误（-32601/-32602）
+//     → 本任务降级 spawn 重跑一次 + 后续任务直走 spawn（标志内存化）；
+//   - spawn（XYZ_ZCODE_MODE=spawn 定向 / 降级目标）：原单轮路径**零行为改动**
+//     保留（runViaSpawn——launcher/parser 四件套原链路）。
 //
 // 职责编排（四件套的消费方）：
 //   preparer（隔离 HOME 池 + 凭据 config）→ launcher（argv/env/spawn/杀链）
 //   → parser（stdout 收集 + 终 JSON + coarse 事件合成）→ reader（read 第①级 sqlite）。
 //
-// run 错误语义（设计 §3.3.5）：
+// run 错误语义（设计 §3.3.5，两模式共用）：
 //   ① prepare 期错误（credential_missing / model_not_available / prompt_too_large /
 //      capability 拒绝）在进程创建前 reject，不产生 handle；
 //   ② 运行中失败不 reject——合成 engine_run_failed outcome + 正常 handle 返回
 //      （record 必须收尾）；
-//   ③ abort 走杀链（SIGTERM→grace→SIGKILL，interrupt: kill-only 无原生中断）后同 ②
-//      （exitCode=null + error 含杀链标记）。
+//   ③ abort：appserver 走 D3 链（session/stop → grace → killChain 连坐共享进程）；
+//      spawn 走公共杀链（SIGTERM→grace→SIGKILL）——终态同为 exitCode=null + 杀链标记。
 //
-// schema 仿真接线（D4 emulated 侧）：common/schema-emulation.ts（并行任务 P2 交付，
-// 2026-08-25 已就绪并接线）——spawn 前拼 prompt 仿真段、终态后三级容错提取 + ajv
-// 校验、失败强化重试一次、仍失败报 schema_emulation_failed。read 第②级 journal 降级
-// 已接线（P4 对齐点①：common/journal-replay 复用 live reducer）。
+// schema 仿真接线（D4 emulated 侧）：common/schema-emulation.ts——spawn 前拼 prompt
+// 仿真段、终态后三级容错提取 + ajv 校验、失败强化重试一次、仍失败报
+// schema_emulation_failed（appserver 路径同接线：prompt 组装共享 buildPrompt，
+// 校验/重试编排共享 run 级重试轮）。read 第②级 journal 降级已接线（对齐点①：
+// common/journal-replay 复用 live reducer）。
 
 import { execFile } from "node:child_process";
 import * as fs from "node:fs";
@@ -32,6 +45,7 @@ import {
   extractAndValidateStructuredOutput,
 } from "../../common/schema-emulation.ts";
 import { HOST_TIMEOUT_ABORT_REASON, synthesizeTimeoutOutcome } from "../../common/kill-chain.ts";
+import { applyPersona } from "../../common/persona-router.ts";
 import { engineTimeoutDetail } from "../../common/errors.ts";
 import { replayJournalToSessionView } from "../../common/journal-replay.ts";
 import type { EnginePort, EngineRunResult, RunContext } from "../../port.ts";
@@ -49,10 +63,19 @@ import type {
 import { resolvePoolDir } from "../../paths.ts";
 import {
   ZCODE_ADAPTER_VERSION,
+  ZCODE_APPSERVER_ABORT_GRACE_MS,
+  ZCODE_APPSERVER_DRIFT_RPC_CODES,
+  ZCODE_APPSERVER_ERR_BUSY_SESSION,
+  ZCODE_APPSERVER_ERR_MODEL_CONFIG_MISSING,
+  ZCODE_APPSERVER_HARVEST_GRACE_MS,
+  ZCODE_APPSERVER_PIDFILE_NAME,
+  ZCODE_APPSERVER_POOL_KEY,
+  ZCODE_APPSERVER_STOP_TIMEOUT_MS,
   ZCODE_CLI_DEFAULT_PATH,
   ZCODE_ENGINE_ID,
   ZCODE_ERROR_TAIL_CHARS,
   ZCODE_KILL_GRACE_MS,
+  ZCODE_MODE_ENV_VAR,
   ZCODE_POOL_DB_RELATIVE_PATH,
 } from "./constants.ts";
 import { ZCODE_GOLDEN_STDOUT } from "./golden-sample.ts";
@@ -66,19 +89,64 @@ import {
 import {
   buildRunFailedMessage,
   collectZcodeOutput,
+  mapZcodeOutcomeUsage,
+  mapZcodeUsage,
   parseZcodeTerminal,
   synthesizeCoarseEvents,
   type ZcodeCollectedOutput,
   type ZcodeTerminalPayload,
 } from "./parser.ts";
-import { listZcodeModels, prepareZcodeHome, resolveZcodeModelRef, type ZcodeSourcePaths } from "./preparer.ts";
+import {
+  acquireAppServerHome,
+  bootstrapAppServerConfig,
+  isLockHeldByUs,
+  startLockHeartbeat,
+  writeAppServerPidFile,
+  type AppServerHomeHandle,
+} from "./appserver-home.ts";
+import {
+  listZcodeModels,
+  prepareZcodeHome,
+  resolveZcodeModelRef,
+  splitZcodeModelRef,
+  type ZcodeSourcePaths,
+} from "./preparer.ts";
 import { readZcodeSessionView } from "./reader.ts";
+import { runAppServerSmokeProbe } from "./appserver-probe.ts";
+import { AppServerConnection, buildAppServerEnv, isAppServerRpcError } from "./connection.ts";
+import { SessionChannel, type SessionCreateParams, type SessionTurnResult } from "./session-channel.ts";
 
 const logger = getLogger("subagents");
 
 /** probe 的版本探测超时（ms）——二进制无响应按探针失败处理，不静默挂死。 */
 const PROBE_VERSION_TIMEOUT_MS = 15_000;
 
+/**
+ * [RX2-F1] 常见 thoughtLevel 档位（仅作提示基准，非权威值域）：pi 全 7 档
+ * （off/minimal/low/medium/high/xhigh/max）恒等透传不拦截——core 引擎层不掌握各模型
+ * 真实值域，禁止硬编码枚举做拒收或映射；不在此列的档位只触发一行提示（warnThoughtLevelUncommon）。
+ */
+const COMMON_THOUGHT_LEVELS: readonly string[] = ["low", "high", "max"];
+
+// ============================================================
+// [R4/R5] 执行模式分派（D2：定向不探不降；缺省探 + 降）
+// ============================================================
+
+export type ZcodeRunMode = "appserver" | "spawn";
+
+/** [R5] 三态：undefined = 未定向（缺省路径，探 + 降）；定向值原样。 */
+export type ZcodeModePin = ZcodeRunMode | undefined;
+
+/**
+ * [R5 D2④] 定向判定：`XYZ_ZCODE_MODE=appserver|spawn` 是**定向**（不探不降——失败
+ * 直接上报，不给定向者换通道）；undefined = 缺省（probe 门控 + 首败降级）。
+ * deps.processEnv 可注入（测试钉扎三态）。
+ */
+export function pinnedZcodeMode(env: NodeJS.ProcessEnv = process.env): ZcodeModePin {
+  const v = env[ZCODE_MODE_ENV_VAR];
+  return v === "appserver" || v === "spawn" ? v : undefined;
+}
+
 /** ZcodeEngine 构造依赖（全部可注入——测试不依赖真机 CLI/真凭据）。 */
 export interface ZcodeEngineDeps {
   /**
@@ -94,8 +162,31 @@ export interface ZcodeEngineDeps {
   probeVersion?: (cliPath: string) => Promise<string | undefined>;
   /** spawn 执行器（测试注入 fake 进程）。 */
   launch?: (opts: { cliPath: string; args: string[]; env: NodeJS.ProcessEnv }) => ZcodeLaunchedProcess;
-  /** env 基底（测试注入；缺省 process.env）。 */
+  /** env 基底（测试注入；缺省 process.env——模式分派与 app-server env 组装都经它）。 */
   processEnv?: NodeJS.ProcessEnv;
+  /**
+   * [R5 D8] 协议冒烟探针总预算（缺省 ZCODE_APPSERVER_PROBE_BUDGET_MS = 10s；测试
+   * 注入短预算验证超时降级路径，不真等 10s）。
+   */
+  probeBudgetMs?: number;
+}
+
+/** 常驻运行时（每引擎实例一份；dispose/凭据刷新/池变更时整件丢弃重建）。 */
+interface AppServerRuntime {
+  conn: AppServerConnection;
+  channel: SessionChannel;
+  homePoolKey: string;
+  homeDir: string;
+  /** 在途会话登记（dispose 时 fire session/close 的目标集；settle 后移除）。 */
+  activeSessions: Set<string>;
+}
+
+/** 已持有的常驻 HOME 记账（锁心跳归属；dispose 不释放——锁随宿主进程存活）。 */
+interface AppServerHomeState {
+  poolKey: string;
+  homeDir: string;
+  lockPath: string;
+  stopHeartbeat: () => void;
 }
 
 /** zcode 引擎适配器。 */
@@ -104,35 +195,53 @@ export class ZcodeEngine implements EnginePort {
 
   private readonly deps: ZcodeEngineDeps;
   private probeCache: ProbeReport | undefined;
+  private appserverRuntime: AppServerRuntime | undefined;
+  private homeState: AppServerHomeState | undefined;
+  /** 并发任务的首次锁获取在途 promise（重入守卫，见 ensureAppServerHome）。 */
+  private homeAcquireInFlight: Promise<AppServerHomeHandle> | undefined;
+  /**
+   * [R5 D2③] 探针结论（与 CLI 文件 mtime 绑定的内存缓存）：mtime 未变不重探；
+   * zcode 升级（mtime 变化）后首个任务前重探。不落盘——进程重启后重探重建。
+   */
+  private smokeConclusion: { cliMtimeMs: number; ok: boolean; detail: string } | undefined;
+  /**
+   * [R5 D2②] 漂移降级标志（内存化，不落盘）：首任务运行中命中 -32601/-32602 后置
+   * true，本进程后续任务直走 spawn；进程重启后经探针门控重建（重探通过则恢复
+   * app-server）。
+   */
+  private driftDegraded = false;
 
   constructor(deps: ZcodeEngineDeps) {
     this.deps = deps;
   }
 
   /**
-   * zcode 链路首期实际接通的能力（D3 链路口径）。声明升级（如 schema 仿真段接入
-   * common 层后仍为 emulated；app-server 常驻化后 eventGranularity 升 stream）必须
-   * 先改链路再改声明。
+   * zcode 链路实际接通的能力（D3 链路口径；R4 D5 升级序：eventGranularity
+   * coarse→stream——链路先行〔session/event payload.delta → text_delta 实时流出，
+   * turn.terminal → turn_end，收尾帧 usage → message_end.usage〕，其余能力位维持
+   * 现值。声明升级必须先改链路再改声明（C4 原则）。
    */
   capabilities(): EngineCapabilities {
     return {
       // 无 --json-schema 类通道；公共 schema 仿真层（prompt 约定 + 容错提取 + ajv）
       schemaEnforcement: "emulated",
-      // argv-only spawn，无运行中插话通道（app-server 属引擎内部优化，首期不接）
+      // send-while-running 恒 -32010 硬错误（旧实测）——app-server 常驻化不改变此判据
       steer: "unsupported",
-      // 无同进程 idle 复用；--resume 是冷启动
+      // 无同进程 idle 复用（D4：每任务自包含 create→run→close）；--resume 是冷启动
       conversation: "unsupported",
       // 无 --append-system-prompt flag（实测拒收）——persona 只能拼进 prompt
       personaInjection: "prompt",
-      // stdout 只有终态单 JSON（message_end/turn_end 合成）
-      eventGranularity: "coarse",
+      // app-server 推送流实时流出（R4）；spawn 降级路径退化为终态两事件（D2 声明不降级
+      // ——降级是任务级兜底非能力级，record 留痕降级事实）
+      eventGranularity: "stream",
       // 首期未接 worktree 隔离（公共层 worktree-manager 接入后升 emulated）
       sandbox: "none",
       // sqlite 三级 JOIN 完整重建 turns（reader 实测）
       sessionRead: "full",
       // --resume 冷启动可用（实测）
       resume: "cold",
-      // 无原生中断——AbortSignal 走公共杀链（SIGTERM→grace→SIGKILL）
+      // abort 走 D3 链（stop→grace→killChain）但声明维持 kill-only 不升级（改链路
+      // 先于改声明；stop 链路经 conformance 真机验证后再评估升 native）
       interrupt: "kill-only",
       // --mode build/edit/plan/yolo 原生权限档位
       permissionMode: "native",
@@ -221,13 +330,510 @@ export class ZcodeEngine implements EnginePort {
     };
   }
 
-  /** D1 主语义：preparer → launcher → parser →（schema 仿真校验 + 一次重试）→ outcome/handle。 */
+  /**
+   * D1 主语义 + [R5] D2 降级链四步：
+   *   ① 定向（XYZ_ZCODE_MODE=appserver|spawn）：不探不降——定向者要的就是这条通道，
+   *      失败直接上报（spawn 兜底原路径 / appserver 直连）；
+   *   ② 缺省 + 已漂移降级（内存标志）：后续任务直走 spawn（record 标注降级事实）；
+   *   ③ 缺省 + 探针门控（结论与 CLI mtime 绑定）：探针失败 → 本任务起直接 spawn；
+   *   ④ 缺省 + 探针通过但首任务命中漂移类 RPC 错误（-32601/-32602）→ 本任务降级
+   *      spawn 重跑一次（同一任务，结果标注降级）+ 后续任务直走 spawn。
+   */
   async run(task: AgentTaskSpec, ctx: RunContext): Promise<EngineRunResult> {
+    this.rejectUnsupportedTaskShapes(task);
+    const pin = pinnedZcodeMode(this.deps.processEnv ?? process.env);
+    if (pin === "appserver") return (await this.runViaAppServer(task, ctx)).result;
+    if (pin === "spawn") return this.runViaSpawn(task, ctx);
+
+    // 缺省：probe 门控 + 首败降级（D2）
+    if (this.driftDegraded) {
+      return this.runViaSpawn(task, ctx, {
+        degradedReason:
+          "protocol-drift（app-server 首任务命中 -32601/-32602 漂移类错误，本进程后续任务直走 spawn；进程重启后重探重建）",
+      });
+    }
+    // pre-aborted 短路：不触发探针（不 spawn 探针进程），由常驻路径内部合成中止终态
+    if (ctx.signal?.aborted !== true) {
+      const gate = await this.appServerProbeGate(task);
+      if (!gate.ok) {
+        return this.runViaSpawn(task, ctx, {
+          degradedReason: `probe-failed（协议冒烟探针未通过：${gate.detail}；CLI mtime 变化后首个任务前重探）`,
+        });
+      }
+    }
+    const { result, driftCode } = await this.runViaAppServer(task, ctx);
+    if (driftCode === undefined) return result;
+    // D2② 首败降级：漂移错误 → 标志内存化 + 同一任务 spawn 重跑一次（结果标注）。
+    // [RX2-F3] skipCtxModelWarn：appserver 首跑已出声过 ctxModel 忽略留痕，同任务
+    // spawn 重跑再 warn 一遍是噪音（探针场景同款自我要求）——重跑侧跳过。
+    this.driftDegraded = true;
+    logger.warn(
+      `[zcode-engine] app-server 漂移类错误（RPC code ${driftCode}）——本任务降级 spawn 重跑，后续任务直走 spawn`,
+      { taskId: ctx.taskId },
+    );
+    return this.runViaSpawn(task, ctx, {
+      degradedReason: `protocol-drift（首任务 app-server 命中 RPC code ${driftCode}，已降级 spawn 重跑本任务；后续任务直走 spawn）`,
+      skipCtxModelWarn: true,
+    });
+  }
+
+  /**
+   * [R5 D8] 探针门控：CLI 文件 mtime 与结论绑定——mtime 未变命中缓存不重探；变化
+   * （zcode 升级）或首次 → 独立短命连接上跑协议冒烟（appserver-probe.ts；必须用已
+   * 引导的常驻 HOME——D7 教训「先 bootstrap 再 probe 否则永远误降级」）。CLI 不存在
+   * 按探针失败处理（spawn 路径自身还有 binary 检查兜底）。
+   */
+  private async appServerProbeGate(task: AgentTaskSpec): Promise<{ ok: boolean; detail: string }> {
+    const cliPath = this.deps.cliPath ?? ZCODE_CLI_DEFAULT_PATH;
+    let cliMtimeMs: number;
+    try {
+      cliMtimeMs = fs.statSync(cliPath).mtimeMs;
+    } catch {
+      return { ok: false, detail: `zcode CLI 不存在：${cliPath}` };
+    }
+    if (this.smokeConclusion !== undefined && this.smokeConclusion.cliMtimeMs === cliMtimeMs) {
+      return this.smokeConclusion; // mtime 未变不重探（D2③）
+    }
+    const modelRef = resolveZcodeModelRef(task.model, this.deps.sources);
+    const home = await this.ensureAppServerHome(modelRef);
+    const r = await runAppServerSmokeProbe({
+      cliPath,
+      homeDir: home.homeDir,
+      baseEnv: this.deps.processEnv ?? process.env,
+      stderrLogPath: path.join(this.deps.engineDataDir(), "logs", "zcode-appserver-probe-stderr.log"),
+      ...(this.deps.probeBudgetMs !== undefined ? { budgetMs: this.deps.probeBudgetMs } : {}),
+    });
+    this.smokeConclusion = { cliMtimeMs, ok: r.ok, detail: r.detail };
+    logger.debug("[zcode-engine] appserver smoke probe", { ok: r.ok, detail: r.detail, cliMtimeMs });
+    return this.smokeConclusion;
+  }
+
+  // ============================================================
+  // [R4] app-server 常驻路径（D1/D3/D4/D7）
+  // ============================================================
+
+  /**
+   * 常驻路径主编排：常驻 HOME（锁/派生/孤儿回收/凭据刷新——appserver-home D7 全量）→
+   * 惰性连接 + runTurn（事件时序前移：text_delta 流式、终态后 message_end/turn_end）→
+   * schema 仿真重试（与 spawn 同编排）→ outcome/handle。poolKey 静态常量，
+   * onPoolResolved 在 prepare 期、onHandleReady 在 create 应答后（§3.4 不变量 3）。
+   *
+   * [R5] 返回附带 driftCode：末轮 attempt 以漂移类 RPC 错误（-32601/-32602）收场时
+   * 给出 code（run 编排降级 spawn 重跑）；其余终态（成功/中止/非漂移失败）为
+   * undefined——-32004/-32010/-32603 按错误规格表各自上报，不降级。
+   */
+  private async runViaAppServer(
+    task: AgentTaskSpec,
+    ctx: RunContext,
+  ): Promise<{ result: EngineRunResult; driftCode: number | undefined }> {
+    const startedAt = Date.now();
+    // pre-aborted 短路：取消先于启动——不创建会话、不触发连接惰性启动（防误杀共享
+    // 进程殃及在途任务；spawn 路径无此形态因每任务独占进程）
+    if (ctx.signal?.aborted === true) {
+      return this.abortedAppServerRun(task, ctx, startedAt);
+    }
+
+    // ① prepare 期：模型解析（provider 体系校验——错误语义与 spawn 同为进程创建前
+    // reject）+ 常驻 HOME（锁判定/派生/pidfile 孤儿回收/config 内容 hash 刷新）
+    const modelRef = resolveZcodeModelRef(task.model, this.deps.sources);
+    this.warnIgnoredCtxModel(task, ctx, modelRef);
+    // [RX2-F1] 非常见档位出声一行（不拦截透传）；放主编排而非 attemptAppServerTurn——
+    // schema 重试轮会二次进 attempt，warn 只应随任务出声一次
+    this.warnThoughtLevelUncommon(task, ctx);
+    const home = await this.ensureAppServerHome(modelRef);
+    // 对齐点③（不变量 3）：poolKey 在 prepare 期声明（静态常量或派生目录名），
+    // 早于连接建立与首个事件
+    ctx.onPoolResolved?.(home.poolKey);
+
+    const cwd = task.cwd ?? process.cwd();
+    const schema = isPlainObject(task.schema) ? task.schema : undefined;
+    const basePrompt = this.buildPrompt(task, schema);
+
+    // ② 首轮执行 + schema 仿真重试（重试语义与不变量注释见 runAppServerAttemptsWithRetry）
+    const usageAcc = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, has: false };
+    const final = await this.runAppServerAttemptsWithRetry(task, ctx, home, modelRef, cwd, basePrompt, schema, usageAcc);
+
+    const outcome = this.finalizeOutcome(task, ctx, final, usageAcc, startedAt);
+    return { result: { handle: this.appServerHandle(home.poolKey, outcome), outcome }, driftCode: driftCodeOf(final) };
+  }
+
+  /** pre-aborted 短路收口（常驻路径专用）：合成中止 outcome + 池锚定 handle。 */
+  private abortedAppServerRun(
+    task: AgentTaskSpec,
+    ctx: RunContext,
+    startedAt: number,
+  ): { result: EngineRunResult; driftCode: number | undefined } {
+    // poolKey 锚定：已持有 HOME（含派生场景）用其真实 poolKey；首次即 abort 尚无
+    // HOME 可用，退回静态常量（此刻确实无派生事实可锚定）
+    const poolKey = this.homeState?.poolKey ?? ZCODE_APPSERVER_POOL_KEY;
+    // 对齐点③（不变量 3）：onPoolResolved 必须先于首个事件 emit——本分支
+    // finalizeOutcome 经 applyAbortedOutcome emit error 事件，缺本调用会把事件落
+    // shared 占位池，与 handle.poolKey 漂移（契约同正常路径 prepare 期声明）
+    ctx.onPoolResolved?.(poolKey);
+    const outcome = this.finalizeOutcome(
+      task,
+      ctx,
+      abortedAppServerAttempt(ctx),
+      { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, has: false },
+      startedAt,
+    );
+    return { result: { handle: this.appServerHandle(poolKey, outcome), outcome }, driftCode: undefined };
+  }
+
+  /**
+   * 首轮执行 + schema 仿真重试编排（常驻路径）：schema 任务校验失败时重试一次（强化
+   * JSON 输出指令——与 spawn/structured-output 的重试语义对齐）。重试轮是独立会话的
+   * 独立 LLM 调用：token 计入 outcome.usage 总量；事件面 text_delta 按实际流出（含
+   * 失败轮——journal 记录真实流水），message_end/turn_end 只在最终轮终态后合成
+   * （不变量 2/5）。
+   */
+  private async runAppServerAttemptsWithRetry(
+    task: AgentTaskSpec,
+    ctx: RunContext,
+    home: AppServerHomeHandle,
+    modelRef: string,
+    cwd: string,
+    basePrompt: string,
+    schema: object | undefined,
+    usageAcc: { input: number; output: number; cacheRead: number; cacheWrite: number; has: boolean },
+  ): Promise<AttemptResult> {
+    let final = await this.attemptAppServerTurn(task, ctx, home, modelRef, cwd, basePrompt);
+    accumulateUsage(usageAcc, final);
+    if (final.kind === "parsed" && final.schemaResult !== undefined && !final.schemaResult.ok && schema !== undefined) {
+      const retryPrompt = appendSchemaRetryDirective(basePrompt, final.schemaResult.error);
+      const retry = await this.attemptAppServerTurn(task, ctx, home, modelRef, cwd, retryPrompt);
+      accumulateUsage(usageAcc, retry);
+      final = retry;
+    }
+    return final;
+  }
+
+  /** 常驻路径的 handle 合成（poolKey = 常驻 HOME 实际目录名——锚定不变量载体）。 */
+  private appServerHandle(poolKey: string, outcome: AgentOutcome): EngineHandle {
+    return {
+      data: {
+        v: 1,
+        engineId: ZCODE_ENGINE_ID,
+        sessionRef: {
+          dbPath: ZCODE_POOL_DB_RELATIVE_PATH,
+          ...(outcome.sessionId !== undefined ? { sessionId: outcome.sessionId } : {}),
+        },
+        poolKey,
+        ...(this.probeCache?.engineVersion !== undefined && this.probeCache.engineVersion !== ""
+          ? { engineVersion: this.probeCache.engineVersion }
+          : {}),
+        adapterVersion: ZCODE_ADAPTER_VERSION,
+      },
+    };
+  }
+
+  /**
+   * 单轮常驻执行：runTurn 组合面 + D3 abort 链 + 事件前移（text_delta 实时流出；
+   * 终态数据经 read 兜底收口后才 resolve——不变量 1/2）。产出三态与 spawn 同构。
+   */
+  private async attemptAppServerTurn(
+    task: AgentTaskSpec,
+    ctx: RunContext,
+    home: AppServerHomeHandle,
+    modelRef: string,
+    cwd: string,
+    prompt: string,
+  ): Promise<AttemptResult> {
+    const rt = this.ensureAppServerRuntime(home);
+    const { providerId, modelId } = splitZcodeModelRef(modelRef);
+    const createParams = buildAppServerCreateParams(task, providerId, modelId, cwd);
+
+    let currentSessionId: string | undefined;
+    let signalSessionCreated: (() => void) | undefined;
+    const sessionCreated = new Promise<void>((resolve) => {
+      signalSessionCreated = resolve;
+    });
+    const turn = rt.channel.runTurn(createParams, prompt, {
+      // 事件时序前移：payload.delta → text_delta 实时流出（stream 粒度，D5）
+      onTextDelta: (delta) => ctx.onEvent?.({ type: "text_delta", delta }),
+      onSessionCreated: (sessionId) => {
+        currentSessionId = sessionId;
+        rt.activeSessions.add(sessionId);
+        signalSessionCreated?.();
+        // §3.4 不变量 3：create 应答后立即回填（早于 subscribe/send/终态/run resolve）
+        ctx.onHandleReady?.({
+          sessionRef: { dbPath: ZCODE_POOL_DB_RELATIVE_PATH, sessionId },
+          poolKey: home.poolKey,
+        });
+      },
+    });
+
+    // D3 abort 链：signal abort → ① session/stop {sessionId} ② grace 窗口确认终态
+    // ③ stop 失败/超时 → killChain 杀共享进程（接受连坐——协议已不可信）→ 在途
+    // 其他任务走崩溃路径。capabilities.interrupt 维持 kill-only 不升级（C4）。
+    const onAbort = (): void => {
+      void this.appServerAbortChain(rt, turn, () => currentSessionId, sessionCreated);
+    };
+    if (ctx.signal !== undefined) {
+      if (ctx.signal.aborted) onAbort();
+      else ctx.signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    try {
+      const r = await turn;
+      // stop 优雅生效（终态在 grace 内到达）：宿主已取消——按中止终态收口（record
+      // 终态迁移由编排层 CAS 决定，engine 侧保持与 spawn abort 同构语义）
+      if (ctx.signal?.aborted === true) return abortedAppServerAttempt(ctx);
+      return parsedAppServerAttempt(task, r);
+    } catch (err) {
+      if (ctx.signal?.aborted === true) return abortedAppServerAttempt(ctx);
+      return failedAppServerAttempt(err, home, currentSessionId);
+    } finally {
+      if (currentSessionId !== undefined) rt.activeSessions.delete(currentSessionId);
+      if (ctx.signal !== undefined) ctx.signal.removeEventListener("abort", onAbort);
+    }
+  }
+
+  /**
+   * D3 abort 链执行体（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 永远发不出，直接连坐杀共享进程。
+   */
+  private async appServerAbortChain(
+    rt: AppServerRuntime,
+    turn: Promise<SessionTurnResult>,
+    getSessionId: () => string | undefined,
+    sessionCreated: Promise<void>,
+  ): Promise<void> {
+    let sessionId = getSessionId();
+    if (sessionId === undefined) {
+      await Promise.race([sessionCreated, delayResolved(ZCODE_APPSERVER_STOP_TIMEOUT_MS, undefined)]);
+      sessionId = getSessionId();
+    }
+    if (sessionId !== undefined) {
+      try {
+        await rt.conn.request("session/stop", { sessionId }, { timeoutMs: ZCODE_APPSERVER_STOP_TIMEOUT_MS });
+      } catch (err) {
+        logger.debug(
+          `[zcode-engine] session/stop 失败（${errMessage(err)}）——grace 后走 killChain 兜底`,
+        );
+      }
+    }
+    const settled = await Promise.race([
+      turn.then(
+        () => true,
+        () => true,
+      ),
+      delayResolved(ZCODE_APPSERVER_ABORT_GRACE_MS, false),
+    ]);
+    if (settled) return; // stop 生效：终态在 grace 窗口内到达，共享进程不杀
+    logger.warn(
+      `[zcode-engine] abort grace 窗口内未见终态——killChain 收割共享进程（接受连坐，在途任务走崩溃路径）`,
+    );
+    await rt.conn.shutdown({ graceMs: ZCODE_KILL_GRACE_MS });
+  }
+
+  // ── 常驻 HOME 与运行时管理（D1/D6/D7）──────────────────────
+
+  /**
+   * 每任务的常驻 HOME 保障：已持有（lockfile.pid=本进程）→ 只做凭据刷新比对
+   * （config 内容 hash；不一致重写 + 重建连接——在途任务走崩溃路径，换取凭据变更
+   * 下一任务生效）；未持有（首任务/锁被夺）→ acquireAppServerHome 全量（锁判定/
+   * 派生/接管 + pidfile 孤儿回收/引导）+ 启动锁心跳。
+   */
+  private async ensureAppServerHome(modelRef: string): Promise<AppServerHomeHandle> {
+    const engineDataDir = this.deps.engineDataDir();
+    // 并发任务重入守卫：首任务在途的锁获取只跑一次（同进程并发 run 各自走判定循环
+    // 会把「自己的活锁」误判成他人活持有 → 派生 -2 → poolKey 漂移触发 teardown 杀
+    // 活连接）。在途完成后落回已持有路径（含凭据刷新比对）。
+    if (this.homeAcquireInFlight !== undefined) {
+      try {
+        await this.homeAcquireInFlight;
+      } catch (err) {
+        // 共享失败不击穿并发任务：首任务 acquire 失败（如凭据缺失）后 homeState 未落，
+        // 落到下方自行重走 acquire 一次——成功则本任务正常推进，仍失败则报本任务自身
+        // 的错误语义（而非继承首任务的异常实例）
+        logger.debug(
+          `[zcode-engine] 并发等待的首任务 home acquire 失败（${errMessage(err)}）——自行重走 acquire`,
+        );
+      }
+    }
+    if (this.homeState !== undefined && isLockHeldByUs(this.homeState.lockPath)) {
+      const boot = bootstrapAppServerConfig({
+        homeDir: this.homeState.homeDir,
+        modelRef,
+        sources: this.deps.sources,
+      });
+      if (boot.wroteConfig) this.teardownAppServerRuntime("credential-refresh");
+      return {
+        poolKey: this.homeState.poolKey,
+        homeDir: this.homeState.homeDir,
+        lockPath: this.homeState.lockPath,
+        tookOver: false,
+        orphanReap: "not-applicable",
+        ...boot,
+      };
+    }
+    const acquire = (async () => {
+      const fresh = await acquireAppServerHome({ engineDataDir, modelRef, sources: this.deps.sources });
+      if (this.homeState !== undefined) this.homeState.stopHeartbeat();
+      this.homeState = {
+        poolKey: fresh.poolKey,
+        homeDir: fresh.homeDir,
+        lockPath: fresh.lockPath,
+        stopHeartbeat: startLockHeartbeat(fresh.lockPath),
+      };
+      logger.debug("[zcode-engine] appserver home acquired", {
+        poolKey: fresh.poolKey,
+        tookOver: fresh.tookOver,
+        orphanReap: fresh.orphanReap,
+        wroteConfig: fresh.wroteConfig,
+        providers: fresh.providerIds.length,
+      });
+      if (fresh.wroteConfig || (this.appserverRuntime !== undefined && this.appserverRuntime.homePoolKey !== fresh.poolKey)) {
+        this.teardownAppServerRuntime(fresh.wroteConfig ? "credential-refresh" : "home-pool-changed");
+      }
+      return fresh;
+    })();
+    this.homeAcquireInFlight = acquire;
+    try {
+      return await acquire;
+    } finally {
+      this.homeAcquireInFlight = undefined;
+    }
+  }
+
+  /**
+   * 惰性获取常驻运行时（D1：每引擎实例一条连接，全任务共享）。池 key 未变直接复用
+   * （连接自身的崩溃重建在 connection 层内部完成——同一条代码路径，§3.4 不变量 4）；
+   * 池变更（派生目录名变化）→ 旧运行时整件丢弃（shutdown fire）+ 新建。常驻进程
+   **不进**宿主 spawnedChildren、不调 onChildSpawned（D6——生命周期归 dispose）。
+   */
+  private ensureAppServerRuntime(home: AppServerHomeHandle): AppServerRuntime {
+    if (this.appserverRuntime !== undefined && this.appserverRuntime.homePoolKey === home.poolKey) {
+      return this.appserverRuntime;
+    }
+    if (this.appserverRuntime !== undefined) this.teardownAppServerRuntime("home-pool-changed");
+    const conn = new AppServerConnection({
+      cliPath: this.deps.cliPath ?? ZCODE_CLI_DEFAULT_PATH,
+      // 进程级 --cwd 用稳定 HOME（连接跨任务共享，工作区由 create 的
+      // workspace.workspacePath 按任务传递——D10 基线不预设任务级进程 cwd）
+      cwd: home.homeDir,
+      env: buildAppServerEnv(home.homeDir, this.deps.processEnv ?? process.env),
+      stderrLogPath: path.join(this.deps.engineDataDir(), "logs", "zcode-appserver-stderr.log"),
+      // 每代进程 spawn 后写 pidfile（D6③ 孤儿回收的数据源；崩溃重建的代同样覆盖写）
+      onSpawned: (child) => {
+        void writeAppServerPidFile(home.homeDir, child.pid ?? -1).catch((err: unknown) => {
+          logger.debug(`[zcode-engine] pidfile 写入失败（best-effort）: ${errMessage(err)}`);
+        });
+      },
+    });
+    const rt: AppServerRuntime = {
+      conn,
+      channel: new SessionChannel(conn),
+      homePoolKey: home.poolKey,
+      homeDir: home.homeDir,
+      activeSessions: new Set<string>(),
+    };
+    this.appserverRuntime = rt;
+    return rt;
+  }
+
+  /** 丢弃当前常驻运行时（凭据刷新/池变更）：shutdown fire（killChain 全序），在途任务走崩溃路径。 */
+  private teardownAppServerRuntime(reason: string): void {
+    const rt = this.appserverRuntime;
+    if (rt === undefined) return;
+    this.appserverRuntime = undefined;
+    // 退订必须在崩溃收割**之后**：channel 的 onClose 收割（failAllTurns）是在途 turn
+    // 的快速失败通道，先退订会让它们挂到 turnTimeoutMs（300s）预算耗尽
+    void this.shutdownRuntimeAndDisposeChannel(rt).catch((err: unknown) => {
+      logger.debug(`[zcode-engine] 常驻连接关闭失败（${reason}，best-effort）: ${errMessage(err)}`);
+    });
+    logger.debug(`[zcode-engine] appserver runtime torn down (${reason})`, { poolKey: rt.homePoolKey });
+  }
+
+  /**
+   * [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` 永不到达时挂死。
+   */
+  private async shutdownRuntimeAndDisposeChannel(rt: AppServerRuntime): Promise<void> {
+    const harvested = new Promise<void>((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, undefined)]);
+    rt.channel.dispose();
+  }
+
+  /**
+   * [R1 D6/R4 主体] 引擎停机面：①fire 全部在途会话的 session/close 帧（不等待
+   * 应答——D6① 顺序规定：close 帧必须先于 SIGTERM，否则对面来不及处理即被杀）→
+   * ②同步 SIGTERM（conn.shutdown 调用内 killChain 前缀同步执行——同步面在返回
+   * Promise 前完成）→ ③grace → SIGKILL（异步面，Promise resolve 于进程退出）。
+   * 幂等：运行时字段取走即置空，二次调用零副作用；dispose 后首个 run 经
+   * ensureAppServerRuntime 自动重建（与崩溃重建同一代码路径，不变量 4）。
+   * 锁不释放（随宿主进程存活——活宿主持有语义；进程死锁自然无主可接管）。
+   */
+  async dispose(): Promise<void> {
+    const rt = this.appserverRuntime;
+    if (rt === undefined) return;
+    this.appserverRuntime = undefined;
+    // ①fire 全部在途会话的 session/close 帧（不等待应答——D6① 顺序规定：close 帧
+    // 必须先于 SIGTERM，否则对面来不及处理即被杀）。进程已死（child=null，如崩溃
+    // 收割与 activeSessions 清理之间的微拍）则整体跳过：post 会经 ensureStarted 惰性
+    // 拉起新进程再被同次 dispose 杀掉——无意义的 spawn+kill 循环（D6 dispose=防泄漏
+    // 语义不制造新进程），且对面进程已不在，close 帧也没有送达对象。同步循环内
+    // alive 不会中途翻转（进程退出是异步事件，本轮循环不可重入）
+    if (rt.conn.alive) {
+      for (const sessionId of [...rt.activeSessions]) {
+        rt.conn.post("session/close", { sessionId });
+      }
+    }
+    // ②③ 同步 SIGTERM（killChain 前缀在 shutdown 调用内同步执行）→ grace → SIGKILL
+    //（异步面，resolve 于进程退出）。channel 退订放在崩溃收割之后（exit→close 窗口
+    //竞态的修复体，见 shutdownRuntimeAndDisposeChannel——先退订会让在途 turn 挂到
+    //turnTimeoutMs）
+    await this.shutdownRuntimeAndDisposeChannel(rt);
+    // 进程已死：pidfile 成为陈旧记录，清掉（防后续 pid 复用误判）
+    try {
+      fs.rmSync(path.join(rt.homeDir, ZCODE_APPSERVER_PIDFILE_NAME), { force: true });
+    } catch (err) {
+      logger.debug(`[zcode-engine] dispose 后 pidfile 清理失败（best-effort）: ${errMessage(err)}`);
+    }
+  }
+
+  // ============================================================
+  // spawn 单轮路径（D2 兜底——R4 起仅 XYZ_ZCODE_MODE=spawn 定向 / R5 降级可达）
+  // ============================================================
+
+  /**
+   * spawn 路径主编排（原 run 主体，行为零改动）：preparer → launcher → parser → 仿真重试 → outcome/handle。
+   * [R5] degrade 参数：降级链落点（探针失败 / 漂移首败重跑 / 降级后直走）——结果经
+   * outcome.engineFallback 标注「degraded: spawn + 原因」（D9① 留痕面复用，record
+   * 同步投影；capabilities 声明不降级——D2 降级是任务级兜底非能力级）。
+   * [RX2-F3] degrade.skipCtxModelWarn（内部标志）：漂移首败重跑场景置 true——该任务
+   * 的 appserver 首跑已输出过 ctxModel 忽略留痕，spawn 重跑侧跳过防同 taskId 双份
+   * 相同 warn；warnEffortUnsupportedBySpawn 不受此标志影响（降级重跑时最终结果出自
+   * spawn，其出声合理，保持现状）。探针失败/降级直走两个落点不置位——任务此前未走
+   * 过 appserver，spawn 侧的 warn 是首次出声。
+   */
+  private async runViaSpawn(
+    task: AgentTaskSpec,
+    ctx: RunContext,
+    degrade?: { degradedReason: string; skipCtxModelWarn?: boolean },
+  ): Promise<EngineRunResult> {
     const startedAt = Date.now();
     this.rejectUnsupportedTaskShapes(task);
+    this.warnEffortUnsupportedBySpawn(task, ctx);
 
     // ① prepare 期：模型解析（provider 体系校验）+ 隔离 HOME 池引导（凭据 + model.main）
     const modelRef = resolveZcodeModelRef(task.model, this.deps.sources);
+    if (degrade?.skipCtxModelWarn !== true) this.warnIgnoredCtxModel(task, ctx, modelRef);
     const prepared = prepareZcodeHome({
       engineDataDir: this.deps.engineDataDir(),
       modelRef,
@@ -247,11 +853,36 @@ export class ZcodeEngine implements EnginePort {
     const schema = isPlainObject(task.schema) ? task.schema : undefined;
     const basePrompt = this.buildPrompt(task, schema);
 
-    // ②-④ 首轮执行；schema 任务校验失败时重试一次（强化 JSON 输出指令——与
-    // structured-output 的重试语义对齐，设计 §3.3.3 schema_emulation_failed 行）。
-    // 重试轮产生的新 session 是独立 LLM 调用：token 计入 outcome.usage 总量，
-    // 事件只在最终轮终态后一次性合成（不变量 5：事件 emit 完成先于 run resolve）。
+    // ②-④ 首轮执行 + schema 仿真重试（重试语义与不变量注释见 runSpawnAttemptsWithRetry）
     const usageAcc = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, has: false };
+    const final = await this.runSpawnAttemptsWithRetry(task, ctx, prepared, cwd, basePrompt, schema, usageAcc);
+
+    const outcome = this.finalizeOutcome(task, ctx, final, usageAcc, startedAt);
+
+    const handle: EngineHandle = this.buildSpawnEngineHandle(prepared, outcome);
+    if (degrade !== undefined) {
+      // 降级标注（engineFallback 留痕面合并语义见 applyDegradeFallback）
+      applyDegradeFallback(outcome, degrade.degradedReason);
+    }
+    return { handle, outcome };
+  }
+
+  /**
+   * 首轮执行 + schema 仿真重试编排（spawn 路径）：schema 任务校验失败时重试一次（强化
+   * JSON 输出指令——与 structured-output 的重试语义对齐，设计 §3.3.3
+   * schema_emulation_failed 行）。重试轮产生的新 session 是独立 LLM 调用：token 计入
+   * outcome.usage 总量，事件只在最终轮终态后一次性合成（不变量 5：事件 emit 完成先于
+   * run resolve）。
+   */
+  private async runSpawnAttemptsWithRetry(
+    task: AgentTaskSpec,
+    ctx: RunContext,
+    prepared: ReturnType<typeof prepareZcodeHome>,
+    cwd: string,
+    basePrompt: string,
+    schema: object | undefined,
+    usageAcc: { input: number; output: number; cacheRead: number; cacheWrite: number; has: boolean },
+  ): Promise<AttemptResult> {
     let final = await this.attemptOnce(task, ctx, prepared, cwd, basePrompt);
     accumulateUsage(usageAcc, final);
     if (final.kind === "parsed" && final.schemaResult !== undefined && !final.schemaResult.ok && schema !== undefined) {
@@ -260,10 +891,15 @@ export class ZcodeEngine implements EnginePort {
       accumulateUsage(usageAcc, retry);
       final = retry;
     }
+    return final;
+  }
 
-    const outcome = this.finalizeOutcome(task, ctx, final, usageAcc, startedAt);
-
-    const handle: EngineHandle = {
+  /** spawn 路径的 handle 合成（poolKey = 隔离池目录名；探针版本可留痕）。 */
+  private buildSpawnEngineHandle(
+    prepared: ReturnType<typeof prepareZcodeHome>,
+    outcome: AgentOutcome,
+  ): EngineHandle {
+    return {
       data: {
         v: 1,
         engineId: ZCODE_ENGINE_ID,
@@ -279,7 +915,6 @@ export class ZcodeEngine implements EnginePort {
         adapterVersion: ZCODE_ADAPTER_VERSION,
       },
     };
-    return { handle, outcome };
   }
 
   /** 终态合成（extension-conventions 函数 80 行上限，从 run 提取）：aborted / run-failed / parsed 三分支。 */
@@ -325,22 +960,29 @@ export class ZcodeEngine implements EnginePort {
     // 对齐点④：宿主超时（mergeTimeoutSignal 的 timeout abort）统一走公共合成终态
     // （common/kill-chain.synthesizeTimeoutOutcome——engine_timeout 文案 SSOT：stdout
     // 尾部 + 「可用 engine: pi 重跑」建议）；用户主动 cancel 维持 engine_run_failed
-    // 中止标记（非超时语义，不冒充超时）。?? 兜底是类型收窄（合成器恒写 error）
+    // 中止标记（非超时语义，不冒充超时）。?? 兜底是类型收窄（合成器恒写 error）。
+    // appserver 路径经 abortMessage 描述 D3 链形态（与 spawn 杀链文案分立）
     outcome.error = isHostTimeoutAbort(ctx)
       ? synthesizeTimeoutOutcome(task, final.output.stdoutText, ZCODE_ENGINE_ID).error ??
         engineTimeoutDetail(final.output.stdoutText)
-      : `engine_run_failed: zcode 任务被中止（杀链 SIGTERM→${ZCODE_KILL_GRACE_MS}ms→SIGKILL，宿主合成终态）。` +
-        `stdout 尾部: ${final.output.stdoutText.slice(-ZCODE_ERROR_TAIL_CHARS)}`;
+      : final.abortMessage ??
+        `engine_run_failed: zcode 任务被中止（杀链 SIGTERM→${ZCODE_KILL_GRACE_MS}ms→SIGKILL，宿主合成终态）。` +
+          `stdout 尾部: ${final.output.stdoutText.slice(-ZCODE_ERROR_TAIL_CHARS)}`;
     emit({ type: "error", message: outcome.error });
   }
 
-  /** run-failed 合成终态：错误信息由 buildRunFailedMessage 产出（已含恢复指引），直接透传。 */
+  /**
+   * run-failed 合成终态：错误信息由 buildRunFailedMessage 产出（已含恢复指引）直接透传；
+   * appserver 路径附带的会话 id 落 outcome.sessionId（错误规格表 -32004 行「含会话 id」
+   * ——appServerHandle 据此写 handle.sessionRef，run-failed 不再恒缺）。
+   */
   private applyRunFailedOutcome(
     outcome: AgentOutcome,
     final: Extract<AttemptResult, { kind: "run-failed" }>,
     emit: (event: AgentEvent) => void,
   ): void {
     outcome.exitCode = final.output.exitCode;
+    if (final.sessionId !== undefined) outcome.sessionId = final.sessionId;
     outcome.error = final.message;
     emit({ type: "error", message: outcome.error });
   }
@@ -563,13 +1205,77 @@ export class ZcodeEngine implements EnginePort {
     }
   }
 
+  /**
+   * [F15b] spawn 路径的 effort 丢弃信号：spawn CLI 无 thoughtLevel 类 flag（协议
+   * 通道是 appserver 路径专属），effort 只能丢弃——但静默丢弃会让调用方误以为推理
+   * 档位已生效，故出声留痕（引擎现成信号风格：logger.warn，同漂移降级先例）。
+   * 诊断语义：effort 是可忽略档位（降档不改变任务正确性），warn 留痕而非硬拒绝
+   * （与 maxTurns「传了上限却失控」的假象不同质性）。
+   */
+  private warnEffortUnsupportedBySpawn(task: AgentTaskSpec, ctx: RunContext): void {
+    const effort = task.effort?.trim();
+    if (effort === undefined || effort === "") return;
+    logger.warn(
+      `[zcode-engine] effort=${effort} 被忽略：zcode spawn 不支持 thoughtLevel 通道（CLI 无对应 flag），任务按引擎缺省推理档位执行；需要 effort 请走 appserver 模式`,
+      { taskId: ctx.taskId },
+    );
+  }
+
+  /**
+   * [RX2-F1] appserver 路径的非常见档位提示：effort → thoughtLevel 恒等透传（F15a），
+   * 全 7 档放行不拦截——但部分档位（off/minimal/medium/xhigh 等）不在部分模型的合法
+   * 值域内（如 GLM-5.3 仅接受 low/high/max），app-server 侧对不支持的档位 warn-skip
+   * （会话照常但档位静默失效），调用方无从察觉。此处仅对 COMMON_THOUGHT_LEVELS 之外
+   * 的档位出声一行提示（措辞是「若不支持将被忽略/回落」的或然警告，非无效断言）；
+   * 是否真不支持由目标模型决定，core 不做权威校验（引擎层不掌握各模型值域）。
+   */
+  private warnThoughtLevelUncommon(task: AgentTaskSpec, ctx: RunContext): void {
+    const thoughtLevel = task.effort?.trim();
+    if (thoughtLevel === undefined || thoughtLevel === "") return;
+    if (COMMON_THOUGHT_LEVELS.includes(thoughtLevel)) return;
+    logger.warn(
+      `[zcode-engine] effort=${thoughtLevel} 已透传为 thoughtLevel（非常见档位）：若目标模型不支持该档位将被忽略/回落到模型缺省推理档位（常见档位：${COMMON_THOUGHT_LEVELS.join("/")}）；档位是否生效以模型实际行为为准`,
+      { 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 本就无模型属预期缺省，
+   * 均不出声（避免噪音）。探针期（appServerProbeGate）不调用——同一任务的正式
+   * run 链路必经此处，双份输出是噪音。[RX2-F3] 漂移首败的 spawn 重跑同理由调用方
+   * 带 degrade.skipCtxModelWarn 跳过——appserver 首跑已出声过，同任务双份相同 warn
+   * 是噪音（与探针场景同一自我要求）。
+   */
+  private warnIgnoredCtxModel(task: AgentTaskSpec, ctx: RunContext, modelRef: string): void {
+    if (ctx.ctxModel === undefined) return;
+    const requested = task.model?.trim();
+    if (requested !== undefined && requested !== "") return;
+    logger.warn(
+      `[zcode-engine] ctx.ctxModel（${ctx.ctxModel.id}）被忽略——ctxModel 是 pi 链路兜底，zcode 不消费；` +
+        `task.model 未显式指定，实际使用引擎缺省模型 ${modelRef}`,
+      { taskId: ctx.taskId },
+    );
+  }
+
   /**
    * persona 拼接后的完整 prompt（personaInjection: 'prompt'——zcode 无 flag 通道）：
-   * appendSystemPrompt 段在前（人设/约束语境），task 正文居中，schema 仿真段尾置
-   * （common/schema-emulation 公共层产出，D4 emulated 侧——zcode 无 native schema 通道）。
+   * persona 段经 common/persona-router.applyPersona 按 capabilities 路由产出
+   * （agentRef/skillPath 引用行 + appendSystemPrompt 正文统一拼装，S5 接线——替换
+   * 原手拼 appendSystemPrompt 段，skillPath/agentRef 不再丢弃），task 正文居中，
+   * schema 仿真段尾置（common/schema-emulation 公共层产出，D4 emulated 侧——zcode
+   * 无 native schema 通道）。
    */
   private buildPrompt(task: AgentTaskSpec, schema: object | undefined): string {
-    const segments: string[] = [...(task.persona?.appendSystemPrompt ?? [])];
+    const segments: string[] = [];
+    if (task.persona !== undefined) {
+      const routed = applyPersona(task.persona, this.capabilities());
+      if (routed.promptSegment !== "") segments.push(routed.promptSegment);
+    }
     segments.push(task.task);
     if (schema !== undefined) segments.push(buildSchemaEmulationSegment(schema));
     return segments.join("\n\n");
@@ -578,10 +1284,20 @@ export class ZcodeEngine implements EnginePort {
 
 // ── 模块级辅助（run 的重试编排件） ──
 
-/** attemptOnce 的三态产物（run 按序编排重试与终态合成）。 */
+/**
+ * attempt 的三态产物（两模式共用；run 按序编排重试与终态合成）。appserver 路径的
+ * output 为合成形态（stdoutText 恒空——其失败素材在 message/abortMessage 内）。
+ */
 type AttemptResult =
-  | { kind: "aborted"; output: ZcodeCollectedOutput }
-  | { kind: "run-failed"; output: ZcodeCollectedOutput; message: string }
+  | { kind: "aborted"; output: ZcodeCollectedOutput; abortMessage?: string }
+  | {
+      kind: "run-failed";
+      output: ZcodeCollectedOutput;
+      message: string;
+      rpcCode?: number;
+      /** appserver 路径失败时已建立的会话 id（错误规格表 -32004 行：按任务失败上报含会话 id）。 */
+      sessionId?: string;
+    }
   | {
       kind: "parsed";
       output: ZcodeCollectedOutput;
@@ -594,6 +1310,86 @@ function isPlainObject(v: unknown): v is object {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
+/** 错误/日志出声用的 message 提取（非 Error 值不抛二次异常）。 */
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** [R5 D2] 漂移类 RPC code 判据（错误规格表第 1 行：-32601 方法不存在 / -32602 参数变形）。 */
+function isDriftRpcCode(code: number): boolean {
+  return (ZCODE_APPSERVER_DRIFT_RPC_CODES as readonly number[]).includes(code);
+}
+
+/** ms 后 resolve 指定值（abort 链 grace 窗口的 race 材料；unref 不阻塞进程退出）。 */
+function delayResolved<T>(ms: number, value: T): Promise<T> {
+  return new Promise<T>((resolve) => {
+    const t = setTimeout(() => resolve(value), ms);
+    if (typeof t.unref === "function") t.unref();
+  });
+}
+
+/** appserver 路径的合成 output（无 stdout 可收集——exitCode 语义：0=正常轮；null=中止/连接级失败）。 */
+function syntheticAppServerOutput(exitCode: number | null): ZcodeCollectedOutput {
+  return { exitCode, stdoutText: "", stderrTail: "" };
+}
+
+/** appserver 路径的 aborted 三态（abortMessage 描述 D3 链形态——与 spawn 杀链文案分立）。 */
+function abortedAppServerAttempt(ctx: RunContext): AttemptResult {
+  void ctx;
+  return {
+    kind: "aborted",
+    output: syntheticAppServerOutput(null),
+    abortMessage:
+      `engine_run_failed: zcode 任务被中止（app-server abort 链：session/stop → ${ZCODE_APPSERVER_ABORT_GRACE_MS}ms grace 确认 → ` +
+      `超时 killChain SIGTERM→${ZCODE_KILL_GRACE_MS}ms→SIGKILL 收割共享进程，在途任务走崩溃路径）。`,
+  };
+}
+
+/** runTurn 终态 → parser 载荷形态（usage 映射与 spawn 路径同源：parser.mapZcodeUsage 一族）。 */
+function turnResultToPayload(r: SessionTurnResult): ZcodeTerminalPayload {
+  return {
+    response: r.response,
+    sessionId: r.sessionId,
+    ...(mapZcodeUsage(r.usage) !== undefined ? { usage: mapZcodeUsage(r.usage) } : {}),
+    ...(mapZcodeOutcomeUsage(r.usage, undefined) !== undefined
+      ? { outcomeUsage: mapZcodeOutcomeUsage(r.usage, undefined) }
+      : {}),
+  };
+}
+
+/**
+ * appserver 路径运行中失败的结构化文案（错误规格表）：-32603 "Model config is
+ * missing" → engine_credential_missing（与 prepare 期同码——错误定位常驻 HOME config）；
+ * -32010 → 单会话一任务是结构保证（busy 不排队不打断），文案引导附带 sessionId/state
+ * 流水报告；其余（连接崩溃/会话失败/漂移类透传——漂移降级归 R5）→ engine_run_failed +
+ * 恢复指引。sessionId 已建立时随文案透出（错误规格表 -32004 行「按任务失败上报含会话 id」）。
+ */
+function buildAppServerRunFailedMessage(err: unknown, home: AppServerHomeHandle, sessionId?: string): string {
+  if (
+    isAppServerRpcError(err) &&
+    err.code === ZCODE_APPSERVER_ERR_MODEL_CONFIG_MISSING &&
+    /Model config is missing/.test(err.message)
+  ) {
+    return (
+      `engine_credential_missing: app-server 报 "Model config is missing"（常驻 HOME ${home.homeDir} 的 config.json ` +
+      `无可用模型配置）。恢复指引：在 ZCode 桌面端登录并配置 provider 凭据后重跑本任务（引擎将在下任务重写常驻 config 并重建连接）。`
+    );
+  }
+  if (isAppServerRpcError(err) && err.code === ZCODE_APPSERVER_ERR_BUSY_SESSION) {
+    const sid = sessionId !== undefined ? `（会话 id: ${sessionId}）` : "";
+    return (
+      `engine_run_failed: app-server 报 -32010${sid}（send 时该会话已有轮在跑，busy 不排队不打断）。` +
+      `单会话一任务是结构保证，出现即 bug；请附带 sessionId 与 state 流水（连接/会话事件日志）上报问题。`
+    );
+  }
+  const code = isAppServerRpcError(err) && err.code !== undefined ? `（code ${err.code}）` : "";
+  const sid = sessionId !== undefined ? `（会话 ${sessionId}）` : "";
+  return (
+    `engine_run_failed: app-server 会话执行失败${code}${sid}: ${errMessage(err).slice(-ZCODE_ERROR_TAIL_CHARS)}。` +
+    `恢复指引：直接重跑本任务（连接崩溃后自动重建进程）；若持续失败，跑 probe 核对协议漂移（R5 降级链）或改用 engine: pi。`
+  );
+}
+
 /** 跨重试轮累计 token 用量（重试的 LLM 调用真实发生）。 */
 function accumulateUsage(acc: { input: number; output: number; cacheRead: number; cacheWrite: number; has: boolean }, r: AttemptResult): void {
   if (r.kind !== "parsed") return;
@@ -617,8 +1413,80 @@ function appendSchemaRetryDirective(basePrompt: string, validationError: string)
   );
 }
 
-/** prepare 期能力拒绝的载体（code 进 message 前缀，调用方可程序化分流）。 */
-class ZcodeTaskShapeError extends Error {
+/** create 参数组装（A.2 ① strict 键集：空白 thoughtLevel / 空 deny 清单不设键）。 */
+function buildAppServerCreateParams(
+  task: AgentTaskSpec,
+  providerId: string,
+  modelId: string,
+  cwd: string,
+): SessionCreateParams {
+  const denyTools = (task.denyTools ?? []).filter((t) => typeof t === "string" && t.trim() !== "");
+  // effort → thoughtLevel（A.2 ① 键集内）：空白串归一为不设键——strict 对象下
+  // 空值键位无语义且防 -32602 变形拒收（与 denyTools 空清单不设键同款纪律）
+  const thoughtLevel = task.effort?.trim();
+  return {
+    workspacePath: cwd,
+    mode: "yolo",
+    // per-session model（G3）：create 参数透传（A.2 ① strict 对象）——同进程任务
+    // 各用各的模型，互不干扰
+    model: { providerId, modelId },
+    ...(thoughtLevel !== undefined && thoughtLevel !== "" ? { thoughtLevel } : {}),
+    ...(denyTools.length > 0 ? { toolDenylist: denyTools } : {}),
+  };
+}
+
+/** appserver 轮成功收口的 parsed 三态（read 兜底后的 response + schema 校验）。 */
+function parsedAppServerAttempt(task: AgentTaskSpec, r: SessionTurnResult): AttemptResult {
+  const schema = isPlainObject(task.schema) ? task.schema : undefined;
+  return {
+    kind: "parsed",
+    output: syntheticAppServerOutput(0),
+    payload: turnResultToPayload(r),
+    ...(schema !== undefined
+      ? { schemaResult: extractAndValidateStructuredOutput(r.response, schema) }
+      : {}),
+  };
+}
+
+/** appserver 轮失败收口的 run-failed 三态（结构化文案 + RPC code 透传 + 会话 id 留痕）。 */
+function failedAppServerAttempt(
+  err: unknown,
+  home: AppServerHomeHandle,
+  currentSessionId: string | undefined,
+): AttemptResult {
+  return {
+    kind: "run-failed",
+    output: syntheticAppServerOutput(null),
+    message: buildAppServerRunFailedMessage(err, home, currentSessionId),
+    // [R5] RPC code 透传给 run 编排（-32601/-32602 漂移降级判据；连接级/超时类
+    // 错误无 code 不参与降级）
+    ...(isAppServerRpcError(err) && err.code !== undefined ? { rpcCode: err.code } : {}),
+    // 错误规格表 -32004 行「按任务失败上报（含会话 id）」：create 成功后运行中失败
+    // （-32004/-32010 等）时留痕会话 id——经 applyRunFailedOutcome 落 outcome.sessionId
+    // 与 handle.sessionRef（create 阶段失败无会话，缺省不带）
+    ...(currentSessionId !== undefined ? { sessionId: currentSessionId } : {}),
+  };
+}
+
+/** [R5] 末轮 attempt 的漂移类 RPC code 提取（-32601/-32602 → run 编排降级判据；其余 undefined）。 */
+function driftCodeOf(final: AttemptResult): number | undefined {
+  return final.kind === "run-failed" && final.rpcCode !== undefined && isDriftRpcCode(final.rpcCode)
+    ? final.rpcCode
+    : undefined;
+}
+
+/** 降级留痕（outcome.engineFallback 唯一通道；路由级 fallback 已存在时合并不覆盖）。 */
+function applyDegradeFallback(outcome: AgentOutcome, degradedReason: string): void {
+  const prior = outcome.engineFallback;
+  outcome.engineFallback = {
+    from: prior?.from ?? "zcode:appserver",
+    reason: `${prior !== undefined ? `${prior.reason}；` : ""}degraded: spawn（${degradedReason}）`,
+  };
+}
+
+/** prepare 期能力拒绝的载体（code 进 message 前缀，调用方可程序化分流）。
+ *  [U10① D6] execution 运行时面错误族成员：export 供宿主 instanceof 分流（纯追加，零逻辑改动）。 */
+export class ZcodeTaskShapeError extends Error {
   readonly code: string;
 
   constructor(code: string, message: string) {