@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

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

@@ -1,658 +0,0 @@
-// 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 错误语义三条）。
-//
-// 职责编排（四件套的消费方）：
-//   preparer（隔离 HOME 池 + 凭据 config）→ launcher（argv/env/spawn/杀链）
-//   → parser（stdout 收集 + 终 JSON + coarse 事件合成）→ reader（read 第①级 sqlite）。
-//
-// 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 含杀链标记）。
-//
-// 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）。
-
-import { execFile } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import {
-  buildSchemaEmulationSegment,
-  extractAndValidateStructuredOutput,
-} from "../../common/schema-emulation.ts";
-import { HOST_TIMEOUT_ABORT_REASON, synthesizeTimeoutOutcome } from "../../common/kill-chain.ts";
-import { engineTimeoutDetail } from "../../common/errors.ts";
-import { replayJournalToSessionView } from "../../common/journal-replay.ts";
-import type { EnginePort, EngineRunResult, RunContext } from "../../port.ts";
-import type {
-  AgentEvent,
-  AgentOutcome,
-  AgentTaskSpec,
-  EngineCapabilities,
-  EngineHandle,
-  InteractAction,
-  InteractResult,
-  ProbeReport,
-  SessionView,
-} from "../../types.ts";
-import { resolvePoolDir } from "../../paths.ts";
-import {
-  ZCODE_ADAPTER_VERSION,
-  ZCODE_CLI_DEFAULT_PATH,
-  ZCODE_ENGINE_ID,
-  ZCODE_ERROR_TAIL_CHARS,
-  ZCODE_KILL_GRACE_MS,
-  ZCODE_POOL_DB_RELATIVE_PATH,
-} from "./constants.ts";
-import { ZCODE_GOLDEN_STDOUT } from "./golden-sample.ts";
-import {
-  buildZcodeArgv,
-  buildZcodeEnv,
-  assertZcodeArgvBudget,
-  launchZcodeProcess,
-  type ZcodeLaunchedProcess,
-} from "./launcher.ts";
-import {
-  buildRunFailedMessage,
-  collectZcodeOutput,
-  parseZcodeTerminal,
-  synthesizeCoarseEvents,
-  type ZcodeCollectedOutput,
-  type ZcodeTerminalPayload,
-} from "./parser.ts";
-import { listZcodeModels, prepareZcodeHome, resolveZcodeModelRef, type ZcodeSourcePaths } from "./preparer.ts";
-import { readZcodeSessionView } from "./reader.ts";
-
-const logger = getLogger("subagents");
-
-/** probe 的版本探测超时（ms）——二进制无响应按探针失败处理，不静默挂死。 */
-const PROBE_VERSION_TIMEOUT_MS = 15_000;
-
-/** ZcodeEngine 构造依赖（全部可注入——测试不依赖真机 CLI/真凭据）。 */
-export interface ZcodeEngineDeps {
-  /**
-   * 引擎数据目录（池根：<dir>/engines/zcode/<poolKey>/）。来源通道（宿主 dataDir）
-   * 由并行任务/W3 解决——本引擎只消费，见 registration.ts 缺省解析。
-   */
-  engineDataDir: () => string;
-  /** zcode CLI 路径；缺省 ZCODE_CLI_DEFAULT_PATH。 */
-  cliPath?: string;
-  /** 源 config 路径覆盖（测试注入临时源；缺省读 ~/.zcode）。 */
-  sources?: ZcodeSourcePaths;
-  /** 版本探测执行器（probe check "version"；测试注入 fake 防真实子进程）。 */
-  probeVersion?: (cliPath: string) => Promise<string | undefined>;
-  /** spawn 执行器（测试注入 fake 进程）。 */
-  launch?: (opts: { cliPath: string; args: string[]; env: NodeJS.ProcessEnv }) => ZcodeLaunchedProcess;
-  /** env 基底（测试注入；缺省 process.env）。 */
-  processEnv?: NodeJS.ProcessEnv;
-}
-
-/** zcode 引擎适配器。 */
-export class ZcodeEngine implements EnginePort {
-  readonly id = ZCODE_ENGINE_ID;
-
-  private readonly deps: ZcodeEngineDeps;
-  private probeCache: ProbeReport | undefined;
-
-  constructor(deps: ZcodeEngineDeps) {
-    this.deps = deps;
-  }
-
-  /**
-   * zcode 链路首期实际接通的能力（D3 链路口径）。声明升级（如 schema 仿真段接入
-   * common 层后仍为 emulated；app-server 常驻化后 eventGranularity 升 stream）必须
-   * 先改链路再改声明。
-   */
-  capabilities(): EngineCapabilities {
-    return {
-      // 无 --json-schema 类通道；公共 schema 仿真层（prompt 约定 + 容错提取 + ajv）
-      schemaEnforcement: "emulated",
-      // argv-only spawn，无运行中插话通道（app-server 属引擎内部优化，首期不接）
-      steer: "unsupported",
-      // 无同进程 idle 复用；--resume 是冷启动
-      conversation: "unsupported",
-      // 无 --append-system-prompt flag（实测拒收）——persona 只能拼进 prompt
-      personaInjection: "prompt",
-      // stdout 只有终态单 JSON（message_end/turn_end 合成）
-      eventGranularity: "coarse",
-      // 首期未接 worktree 隔离（公共层 worktree-manager 接入后升 emulated）
-      sandbox: "none",
-      // sqlite 三级 JOIN 完整重建 turns（reader 实测）
-      sessionRead: "full",
-      // --resume 冷启动可用（实测）
-      resume: "cold",
-      // 无原生中断——AbortSignal 走公共杀链（SIGTERM→grace→SIGKILL）
-      interrupt: "kill-only",
-      // --mode build/edit/plan/yolo 原生权限档位
-      permissionMode: "native",
-    };
-  }
-
-  /** 探针（D7）：二进制存在 + 版本解析 + golden 样本干跑回归（zsub 式逆向契约引擎必做）。 */
-  async probe(opts?: { force?: boolean }): Promise<ProbeReport> {
-    if (!opts?.force && this.probeCache) return this.probeCache;
-
-    const cliPath = this.deps.cliPath ?? ZCODE_CLI_DEFAULT_PATH;
-    // check 1：二进制存在（不在 PATH，固定绝对路径形态——存在性即可用性的第一道判据）
-    const binary = this.probeBinaryCheck(cliPath);
-    const checks: ProbeReport["checks"] = [binary];
-
-    // check 2：版本解析（存在才尝试——必败进程不再 spawn）
-    let engineVersion = "";
-    if (binary.ok) {
-      const version = await this.probeVersionCheck(cliPath);
-      checks.push(version.check);
-      engineVersion = version.engineVersion;
-    }
-
-    // check 3：golden 样本干跑回归（parser 对实录样本解析——格式漂移入口拦截）
-    checks.push(this.probeGoldenCheck());
-
-    const ok = checks.every((c) => c.ok);
-    const report: ProbeReport = {
-      ok,
-      engineVersion,
-      checks,
-      ...(ok ? {} : { error: this.probeFailureRecovery(cliPath) }),
-    };
-    this.probeCache = report;
-    return report;
-  }
-
-  /** check 1：二进制存在性（isFile 才算——同名目录不是可执行入口）。 */
-  private probeBinaryCheck(cliPath: string): ProbeReport["checks"][number] {
-    const binaryOk = fs.existsSync(cliPath) && fs.statSync(cliPath).isFile();
-    return {
-      name: "binary",
-      ok: binaryOk,
-      detail: binaryOk ? cliPath : `zcode CLI 不存在：${cliPath}`,
-    };
-  }
-
-  /** check 2：`--version` 解析（probeVersion 可注入——测试 fake 防真实子进程）。 */
-  private async probeVersionCheck(
-    cliPath: string,
-  ): Promise<{ check: ProbeReport["checks"][number]; engineVersion: string }> {
-    const runVersion = this.deps.probeVersion ?? defaultProbeVersion;
-    const version = await runVersion(cliPath);
-    const versionOk = version !== undefined && version.length > 0;
-    return {
-      check: {
-        name: "version",
-        ok: versionOk,
-        detail: versionOk ? version : "zcode --version 返回空或失败",
-      },
-      engineVersion: version ?? "",
-    };
-  }
-
-  /** check 3：golden 样本干跑（parser 对实录样本解析——stdout 格式漂移的入口拦截）。 */
-  private probeGoldenCheck(): ProbeReport["checks"][number] {
-    const golden = parseZcodeTerminal(ZCODE_GOLDEN_STDOUT);
-    const goldenOk = golden.ok && golden.payload.sessionId !== undefined && golden.payload.usage !== undefined;
-    return {
-      name: "golden-regression",
-      ok: goldenOk,
-      detail: goldenOk
-        ? "parser 对 0.16.5 实录样本回归通过（sessionId/response/usage 形状完整）"
-        : `解析实录样本失败：${golden.ok ? "字段缺失（sessionId/usage）" : golden.reason}`,
-    };
-  }
-
-  /** 探针失败的恢复指引（§3.3.3 终态四：版本确认命令 + 探针重跑 + 调研文档路径）。 */
-  private probeFailureRecovery(cliPath: string): NonNullable<ProbeReport["error"]> {
-    return {
-      code: "engine_probe_failed",
-      recovery:
-        `Run \`node ${cliPath} --version\` 确认 zcode CLI 可用且版本未漂移，然后重跑探针（重新初始化引擎或 probe({force:true})）。` +
-        `若 stdout 格式已变：把新样本补录进 golden 库（__tests__/__fixtures__/zcode-golden-spawn.json 与 golden-sample.ts）并更新 parser。` +
-        `参照 docs/research/agent-engine-zcode.md。`,
-    };
-  }
-
-  /** D1 主语义：preparer → launcher → parser →（schema 仿真校验 + 一次重试）→ outcome/handle。 */
-  async run(task: AgentTaskSpec, ctx: RunContext): Promise<EngineRunResult> {
-    const startedAt = Date.now();
-    this.rejectUnsupportedTaskShapes(task);
-
-    // ① prepare 期：模型解析（provider 体系校验）+ 隔离 HOME 池引导（凭据 + model.main）
-    const modelRef = resolveZcodeModelRef(task.model, this.deps.sources);
-    const prepared = prepareZcodeHome({
-      engineDataDir: this.deps.engineDataDir(),
-      modelRef,
-      sources: this.deps.sources,
-    });
-    // 对齐点③：把实际池 key 声明给宿主（journal writer 重定向到 handle.poolKey 同源
-    // 的路径——单一权威，宿主不再两边推导）；须在首个事件 emit 前（终态后合成，天然满足）
-    ctx.onPoolResolved?.(prepared.poolKey);
-    logger.debug("[zcode-engine] isolated home prepared", {
-      poolKey: prepared.poolKey,
-      wroteConfig: prepared.wroteConfig,
-      modelRef,
-      taskId: ctx.taskId,
-    });
-
-    const cwd = task.cwd ?? process.cwd();
-    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）。
-    const usageAcc = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, has: false };
-    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) {
-      const retryPrompt = appendSchemaRetryDirective(basePrompt, final.schemaResult.error);
-      const retry = await this.attemptOnce(task, ctx, prepared, cwd, retryPrompt);
-      accumulateUsage(usageAcc, retry);
-      final = retry;
-    }
-
-    const outcome = this.finalizeOutcome(task, ctx, final, usageAcc, startedAt);
-
-    const handle: EngineHandle = {
-      data: {
-        v: 1,
-        engineId: ZCODE_ENGINE_ID,
-        sessionRef: {
-          // 相对池目录自描述（设计 §3.3.6）——read 时经 resolvePoolDir + 此相对路径重定位
-          dbPath: ZCODE_POOL_DB_RELATIVE_PATH,
-          ...(outcome.sessionId !== undefined ? { sessionId: outcome.sessionId } : {}),
-        },
-        poolKey: prepared.poolKey,
-        ...(this.probeCache?.engineVersion !== undefined && this.probeCache.engineVersion !== ""
-          ? { engineVersion: this.probeCache.engineVersion }
-          : {}),
-        adapterVersion: ZCODE_ADAPTER_VERSION,
-      },
-    };
-    return { handle, outcome };
-  }
-
-  /** 终态合成（extension-conventions 函数 80 行上限，从 run 提取）：aborted / run-failed / parsed 三分支。 */
-  private finalizeOutcome(
-    task: AgentTaskSpec,
-    ctx: RunContext,
-    final: AttemptResult,
-    usageAcc: { input: number; output: number; cacheRead: number; cacheWrite: number; has: boolean },
-    startedAt: number,
-  ): AgentOutcome {
-    const outcome: AgentOutcome = {
-      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 !== undefined ? { engineFallback: ctx.engineFallback } : {}),
-    };
-    const emit = (event: AgentEvent): void => {
-      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 正常收尾，不留僵尸）。 */
-  private applyAbortedOutcome(
-    outcome: AgentOutcome,
-    task: AgentTaskSpec,
-    ctx: RunContext,
-    final: Extract<AttemptResult, { kind: "aborted" }>,
-    emit: (event: AgentEvent) => void,
-  ): void {
-    outcome.exitCode = null;
-    // 对齐点④：宿主超时（mergeTimeoutSignal 的 timeout abort）统一走公共合成终态
-    // （common/kill-chain.synthesizeTimeoutOutcome——engine_timeout 文案 SSOT：stdout
-    // 尾部 + 「可用 engine: pi 重跑」建议）；用户主动 cancel 维持 engine_run_failed
-    // 中止标记（非超时语义，不冒充超时）。?? 兜底是类型收窄（合成器恒写 error）
-    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)}`;
-    emit({ type: "error", message: outcome.error });
-  }
-
-  /** run-failed 合成终态：错误信息由 buildRunFailedMessage 产出（已含恢复指引），直接透传。 */
-  private applyRunFailedOutcome(
-    outcome: AgentOutcome,
-    final: Extract<AttemptResult, { kind: "run-failed" }>,
-    emit: (event: AgentEvent) => void,
-  ): void {
-    outcome.exitCode = final.output.exitCode;
-    outcome.error = final.message;
-    emit({ type: "error", message: outcome.error });
-  }
-
-  /** parsed 合成终态：content/sessionId/usage 落位 + schema 校验分流 + coarse 事件。 */
-  private applyParsedOutcome(
-    outcome: AgentOutcome,
-    final: Extract<AttemptResult, { kind: "parsed" }>,
-    usageAcc: { input: number; output: number; cacheRead: number; cacheWrite: number; has: boolean },
-    emit: (event: AgentEvent) => void,
-  ): void {
-    const payload = final.payload;
-    outcome.content = payload.response;
-    outcome.exitCode = final.output.exitCode;
-    if (payload.sessionId !== undefined) outcome.sessionId = payload.sessionId;
-    // usage：token 四项取两轮之和（重试的 LLM 调用真实发生），contextTokens/turns 取末轮
-    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 !== undefined) {
-      if (final.schemaResult.ok) {
-        // D4 硬分流的 emulated 侧产出：公共仿真层的 ajv 校验结果即 parsedOutput
-        outcome.parsedOutput = final.schemaResult.parsed;
-      } else {
-        // 两轮（原始 + 强化重试）均未通过三级容错提取/ajv 校验
-        outcome.error =
-          `schema_emulation_failed: zcode 输出经两轮（含强化 prompt 重试）仍未通过 schema 校验。` +
-          `末轮失败原因: ${final.schemaResult.error}。原始输出尾部: ${final.schemaResult.tail}。` +
-          `恢复指引：简化 schema 或拆小任务后重派；需要强 schema 约束时改用 engine: pi（native schema 注入）。`;
-        emit({ type: "error", message: outcome.error });
-      }
-    }
-    // coarse 事件（不变量 5：事件 emit 完成先于 run resolve——journal 完整性）
-    for (const ev of synthesizeCoarseEvents(payload.response, payload.usage)) emit(ev);
-  }
-
-  /**
-   * 单轮执行（launch → collect → parse → schema 校验）。产出三态之一给 run 编排：
-   * aborted（我方杀链）/ run-failed（非零退出或解析失败）/ parsed（含 schema 校验结果）。
-   */
-  private async attemptOnce(
-    task: AgentTaskSpec,
-    ctx: RunContext,
-    prepared: ReturnType<typeof prepareZcodeHome>,
-    cwd: string,
-    prompt: string,
-  ): Promise<AttemptResult> {
-    // ② argv 组装 + 字节估算（超限抛 prompt_too_large——进程创建前；公共预算权威）
-    const args = buildZcodeArgv({ cwd, prompt, denyTools: task.denyTools });
-    const cliPath = this.deps.cliPath ?? ZCODE_CLI_DEFAULT_PATH;
-    assertZcodeArgvBudget("node", cliPath, args);
-
-    // ③ launch：spawn 单轮（stdin ignore；HOME=池目录；嵌套标记经公共 nesting-guard）
-    const launch = this.deps.launch ?? launchZcodeProcess;
-    const env = buildZcodeEnv(prepared.homeDir, this.deps.processEnv ?? process.env);
-    let proc: ZcodeLaunchedProcess;
-    try {
-      proc = launch({ cliPath, args, env });
-    } catch (err) {
-      // spawn 同步失败（node 缺失等）：进程未创建，按 prepare 期语义 reject
-      throw new Error(
-        `[engine_run_failed] 无法启动 zcode CLI（${cliPath}）：${err instanceof Error ? err.message : String(err)}。` +
-          `恢复指引：确认 node 在 PATH 且 ${cliPath} 存在（probe 可探测），或改用 engine: pi。`,
-      );
-    }
-
-    // [U0 D10] 终止链路径①：spawn 成功后同步注册子进程句柄进宿主 spawnedChildren
-    // 记账（port.ts 契约「spawn 成功后同步回调」）——cancelBackground SIGTERM /
-    // dispose killAll 收割兜底对引擎 record 生效，防 controller 丢失/竞态场景下孤儿进程
-    ctx.onChildSpawned?.(proc.child);
-
-    // abort 分级（D1）：zcode 无原生中断（interrupt: kill-only），AbortSignal 直通
-    // SIGTERM → grace → SIGKILL 杀链，终态由宿主合成
-    const onAbort = (): void => {
-      void proc.abort(ZCODE_KILL_GRACE_MS);
-    };
-    if (ctx.signal !== undefined) {
-      if (ctx.signal.aborted) onAbort();
-      else ctx.signal.addEventListener("abort", onAbort, { once: true });
-    }
-
-    // ④ parser：有界收集 + 终 JSON
-    const output = await collectZcodeOutput(proc);
-    if (ctx.signal !== undefined) ctx.signal.removeEventListener("abort", onAbort);
-
-    if (proc.killedByUs()) return { kind: "aborted", output };
-    if (output.exitCode !== 0) {
-      return {
-        kind: "run-failed",
-        output,
-        message: buildRunFailedMessage({
-          cliPath,
-          exitCode: output.exitCode,
-          stdoutTail: output.stdoutText,
-          stderrTail: output.stderrTail,
-          modelRef: prepared.modelRef,
-          configPath: prepared.configPath,
-        }),
-      };
-    }
-    const terminal = parseZcodeTerminal(output.stdoutText);
-    if (!terminal.ok) {
-      return {
-        kind: "run-failed",
-        output,
-        message: buildRunFailedMessage({
-          cliPath,
-          exitCode: output.exitCode,
-          stdoutTail: output.stdoutText,
-          stderrTail: output.stderrTail,
-          parseReason: terminal.reason,
-          modelRef: prepared.modelRef,
-          configPath: prepared.configPath,
-        }),
-      };
-    }
-    const schema = isPlainObject(task.schema) ? task.schema : undefined;
-    return {
-      kind: "parsed",
-      output,
-      payload: terminal.payload,
-      ...(schema !== undefined
-        ? { schemaResult: extractAndValidateStructuredOutput(terminal.payload.response, schema) }
-        : {}),
-    };
-  }
-
-  /**
-   * D1 可选面：zcode 首期不支持 conversation（capabilities 声明）——同步拒绝、
-   * 不创建进程，文案给可操作建议（A11）。
-   */
-  async interact(_handle: EngineHandle, _action: InteractAction): Promise<InteractResult> {
-    return {
-      ok: false,
-      code: "engine_capability_unsupported",
-      message:
-        "zcode 引擎不支持 conversation 交互控制面（capabilities.conversation = 'unsupported'，" +
-        "spawn 单轮模式无同进程 idle 复用）。恢复指引：改用单次 subagent 调用重新派发任务，" +
-        "或使用 engine: 'pi'（chatMode idle 复用，支持 message/close/cancel）。",
-    };
-  }
-
-  /**
-   * D6 read 三级降级：①sqlite 原生读取 → ②宿主 event journal 重放（对齐点①接线：
-   * replayJournalToSessionView 复用 live reducer，重放等价性见 §3.3.6）→ ③outcome-only。
-   * sessionId 缺失（解析失败的 run 无法在共享池 db 内定位 session）跳过①级；②级
-   * 依赖 handle.journalPath（宿主 run 后回填）。
-   */
-  /** [U7] 模型可发现性：v2 桌面登录态聚合（带凭据 provider × models），失败安全返回清单本身可能为空。 */
-  listModels(): Array<{ id: string; name?: string }> {
-    return listZcodeModels(this.deps.sources);
-  }
-
-  async read(handle: EngineHandle): Promise<SessionView> {
-    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") {
-      // 相对路径锚定池目录（handle.poolKey 自描述）；绝对路径（未来形态）直用
-      const dbPath = path.isAbsolute(dbPathRaw)
-        ? dbPathRaw
-        : path.join(resolvePoolDir(this.deps.engineDataDir(), ZCODE_ENGINE_ID, handle.data.poolKey), dbPathRaw);
-      try {
-        return await readZcodeSessionView(dbPath, sessionId);
-      } catch (err) {
-        logger.warn("[zcode-engine] native session read failed, degrade to journal replay", {
-          dbPath,
-          sessionId,
-          reason: err instanceof Error ? err.message : String(err),
-        });
-      }
-    }
-    // ②级：journal 重放（journalPath 缺省 / 文件不存在 / 无事件 → undefined 落③级）
-    const journaled = replayJournalToSessionView(handle, ZCODE_ENGINE_ID);
-    if (journaled !== undefined) return journaled;
-    return { engineId: ZCODE_ENGINE_ID, turns: [], source: "outcome-only" };
-  }
-
-  // ── 内部 ──
-
-  /**
-   * prepare 期的能力拒绝（进程创建前）：fork 是 pi 专属（AgentTaskSpec.fork 契约：
-   * 其他引擎按 capabilities 拒绝）；conversation 是 interact 控制面的 task 标志，
-   * zcode 无此面（A11：同步拒绝 + 可操作建议，无进程创建）；maxTurns 是 pi 引擎
-   * 专属（turn limiter + spawn watchdog 估算依赖 pi 的 turn_end 事件流）——zcode
-   * 无 turn_end 语义，静默丢弃会造成「传了上限却失控」的假象，显式拒绝（U4，
-   * 同 fork 模式）。
-   */
-  private rejectUnsupportedTaskShapes(task: AgentTaskSpec): void {
-    if (task.fork === true) {
-      throw new ZcodeTaskShapeError(
-        "engine_capability_unsupported",
-        "zcode 引擎不支持 fork（pi 专属会话分叉语义）。恢复指引：去掉 fork 参数重派，或使用 engine: 'pi'。",
-      );
-    }
-    if (task.conversation === true) {
-      throw new ZcodeTaskShapeError(
-        "engine_capability_unsupported",
-        "zcode 引擎不支持 conversation 模式（spawn 单轮，无同进程 idle 复用）。" +
-          "恢复指引：改用单次调用（去掉 conversation），或使用 engine: 'pi'。",
-      );
-    }
-    if (task.maxTurns !== undefined) {
-      throw new ZcodeTaskShapeError(
-        "engine_capability_unsupported",
-        "zcode 引擎不支持 maxTurns（pi 引擎专属 turn limiter；zcode 无 turn_end 语义，无法兑现轮数上限）。" +
-          "恢复指引：去掉 maxTurns 参数重派，或使用 engine: 'pi'。",
-      );
-    }
-  }
-
-  /**
-   * persona 拼接后的完整 prompt（personaInjection: 'prompt'——zcode 无 flag 通道）：
-   * appendSystemPrompt 段在前（人设/约束语境），task 正文居中，schema 仿真段尾置
-   * （common/schema-emulation 公共层产出，D4 emulated 侧——zcode 无 native schema 通道）。
-   */
-  private buildPrompt(task: AgentTaskSpec, schema: object | undefined): string {
-    const segments: string[] = [...(task.persona?.appendSystemPrompt ?? [])];
-    segments.push(task.task);
-    if (schema !== undefined) segments.push(buildSchemaEmulationSegment(schema));
-    return segments.join("\n\n");
-  }
-}
-
-// ── 模块级辅助（run 的重试编排件） ──
-
-/** attemptOnce 的三态产物（run 按序编排重试与终态合成）。 */
-type AttemptResult =
-  | { kind: "aborted"; output: ZcodeCollectedOutput }
-  | { kind: "run-failed"; output: ZcodeCollectedOutput; message: string }
-  | {
-      kind: "parsed";
-      output: ZcodeCollectedOutput;
-      payload: ZcodeTerminalPayload;
-      schemaResult?: { ok: true; parsed: unknown } | { ok: false; error: string; tail: string };
-    };
-
-/** Record 形状 guard（task.schema 的运行时窄化——Record<string, unknown> 不满足 ajv 的 object 入参）。 */
-function isPlainObject(v: unknown): v is object {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-/** 跨重试轮累计 token 用量（重试的 LLM 调用真实发生）。 */
-function accumulateUsage(acc: { input: number; output: number; cacheRead: number; cacheWrite: number; has: boolean }, r: AttemptResult): void {
-  if (r.kind !== "parsed") return;
-  const u = r.payload.usage;
-  if (u === undefined) return;
-  acc.has = true;
-  acc.input += u.input;
-  acc.output += u.output;
-  acc.cacheRead += u.cacheRead;
-  acc.cacheWrite += u.cacheWrite;
-}
-
-/** 强化重试 prompt：首战校验失败后追加更明确的 JSON 输出指令（structured-output 重试语义）。 */
-function appendSchemaRetryDirective(basePrompt: string, validationError: string): string {
-  return (
-    basePrompt +
-    "\n\n## Retry: Structured Output Failed\n" +
-    `Your previous answer failed schema validation: ${validationError}\n` +
-    "Answer again. Output ONLY the JSON value conforming to the schema above — " +
-    "no prose, no markdown fences, no extra text."
-  );
-}
-
-/** prepare 期能力拒绝的载体（code 进 message 前缀，调用方可程序化分流）。 */
-class ZcodeTaskShapeError extends Error {
-  readonly code: string;
-
-  constructor(code: string, message: string) {
-    super(`[${code}] ${message}`);
-    this.name = "ZcodeTaskShapeError";
-    this.code = code;
-  }
-}
-
-/** 宿主超时 abort 判别（对齐点④）：signal.reason 带超时标记 = 超时杀链合成终态路径。 */
-function isHostTimeoutAbort(ctx: RunContext): boolean {
-  return ctx.signal?.aborted === true && ctx.signal.reason === HOST_TIMEOUT_ABORT_REASON;
-}
-
-/** 默认版本探测：`node <cli> --version`（首行 trim；超时按探针失败处理）。 */
-async function defaultProbeVersion(cliPath: string): Promise<string | undefined> {
-  try {
-    return await new Promise<string | undefined>((resolve, reject) => {
-      execFile(
-        "node",
-        [cliPath, "--version"],
-        { encoding: "utf8", timeout: PROBE_VERSION_TIMEOUT_MS },
-        (err: Error | null, stdout: string) => {
-          if (err) reject(err);
-          else resolve(stdout.trim().split("\n")[0]?.trim() || undefined);
-        },
-      );
-    });
-  } catch (err) {
-    logger.debug(
-      `[zcode-engine] probe version check failed (best-effort continue): ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return undefined;
-  }
-}