@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,161 @@
+// src/execution/engine/engines/zcode/launcher.ts
+//
+// ZcodeEngine launcher（P3）：spawn 命令组装 + 进程启动——四件套里唯一持有 spawn 权
+// 的模块（设计 §3.3.7）。TS 重写自 zsub driver.js 的 runHeadless 命令组装段，机制
+// 保留（真机验证过）：
+//   - argv 形态：`node <zcode.cjs> --json --cwd <dir> --mode yolo [--disallowed-tools a,b]
+//     [--resume <sid>] --prompt <text>`；flag 拒收清单（--model/--skill/--max-turns 等
+//     help 漂移项）一个不用；
+//   - stdin: 'ignore'（CLI 不读 stdin，置管道会挂起——zsub 实测）；
+//   - env：HOME=隔离池目录（provider 配置与 db 全部落池内）+ 嵌套防护标记；
+//   - 杀链：SIGTERM → grace → SIGKILL，exited 用 close 事件维护的标志判断
+//     （child.killed 在 kill() 调用后恒 true，zsub 修过的原版死代码 bug）。
+//
+// 与 zsub 的差异：超时不在本模块（宿主公共杀链职责，设计 D4/附录 A「CLI 超时 6/6
+// 全缺全补」）；abort 由 AbortSignal 驱动（EnginePort 契约），zsub 的 cancel() 变为
+// abort(graceMs)。
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { Readable } from "node:stream";
+
+import { killChain } from "../../common/kill-chain.ts";
+import { buildNestedSpawnEnv } from "../../common/nesting-guard.ts";
+import { assertArgvBudget } from "../../common/persona-router.ts";
+import { ZCODE_KILL_GRACE_MS } from "./constants.ts";
+
+// ============================================================
+// argv 组装与字节预算（对齐点②收口：估算/断言单一权威 = common/persona-router，
+// 本模块只组装；引擎侧在 launch 前调 assertArgvBudget）
+// ============================================================
+
+export interface ZcodeSpawnSpec {
+  /** 任务运行目录（--cwd flag 的值）。 */
+  cwd: string;
+  /** 完整 prompt（persona 拼接后的产物）。 */
+  prompt: string;
+  /** 工具 denylist（逗号连接进 --disallowed-tools；空数组不加 flag）。 */
+  denyTools?: string[];
+  /** 冷续聊目标 session（--resume；spawn 单轮模式内不做 resume 仿真，留给宿主）。 */
+  resumeSessionId?: string;
+}
+
+/** 组装 zcode.cjs 的 argv（不含 `node` 与 cli 路径两个前导元素）。 */
+export function buildZcodeArgv(spec: ZcodeSpawnSpec): string[] {
+  const args = ["--json", "--cwd", spec.cwd, "--mode", "yolo"];
+  // denylist 硬约束：非空数组才落 flag（CLI 对空值行为未定义，不赌——zsub 同判）
+  const disallowed = (spec.denyTools ?? []).filter((t) => typeof t === "string" && t.trim() !== "");
+  if (disallowed.length > 0) args.push("--disallowed-tools", disallowed.join(","));
+  if (spec.resumeSessionId) args.push("--resume", String(spec.resumeSessionId));
+  args.push("--prompt", String(spec.prompt));
+  return args;
+}
+
+/**
+ * argv 预算断言（launch 前调用；对齐点②：公共 persona-router 的单一权威实现，
+ * DEFAULT_ARGV_BUDGET_BYTES 128KB 阈值同源——超限抛 EngineError(prompt_too_large)，
+ * 进程创建前拦截，禁止 spawn 后撞 E2BIG）。
+ */
+export function assertZcodeArgvBudget(nodeBin: string, cliPath: string, args: string[]): void {
+  assertArgvBudget([nodeBin, cliPath, ...args]);
+}
+
+// ============================================================
+// env 构造
+// ============================================================
+
+/**
+ * 构造子进程 env：嵌套防护经公共 nesting-guard（D8：注入统一 XYZ_AGENT_SUBAGENT=1 +
+ * 剥离引擎原生嵌套标记 ZSW_NESTED/PI_SUBAGENT_*——旧标记继承会让孙代理误判嵌套层），
+ * HOME 最后落（隔离 HOME 是 provider 配置与 db 的定位锚，基 env 同名键不许覆盖）。
+ */
+export function buildZcodeEnv(homeDir: string, baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  return { ...buildNestedSpawnEnv(baseEnv), HOME: homeDir };
+}
+
+// ============================================================
+// 进程启动（EngineProcess 形态，设计 §3.3.7）
+// ============================================================
+
+/** launcher 产出的进程句柄（parser 消费 stdout/stderr/exited；abort 是杀链执行体）。 */
+export interface ZcodeLaunchedProcess {
+  /** spawn 出的原始子进程句柄（[U0 D10] 终止链记账——引擎经 RunContext.onChildSpawned 注册进宿主 spawnedChildren）。 */
+  readonly child: ChildProcess;
+  readonly pid: number;
+  readonly stdout: Readable;
+  readonly stderr: Readable;
+  /** 杀链：SIGTERM → graceMs 后未退出则 SIGKILL；resolve 于进程退出。幂等。 */
+  readonly abort: (graceMs?: number) => Promise<void>;
+  /** 进程退出（code=null 表示被信号杀死）。 */
+  readonly exited: Promise<{ code: number | null; signal: string | undefined }>;
+  /** 本方杀链是否介入过（合成终态的判据：介入后 code 语义不再是引擎自身失败）。 */
+  readonly killedByUs: () => boolean;
+}
+
+export interface ZcodeLaunchOptions {
+  /** zcode CLI 路径（node 脚本）。 */
+  cliPath: string;
+  /** cliPath 之后的 argv（buildZcodeArgv 产物）。 */
+  args: string[];
+  /** 完整 env（buildZcodeEnv 产物）。 */
+  env: NodeJS.ProcessEnv;
+  /** node 二进制（缺省 'node'，走 PATH）。 */
+  nodeBin?: string;
+}
+
+/**
+ * 启动 zcode 子进程。spawn 同步失败（如 node 不存在）直接 throw——调用方（引擎 run）
+ * 按进程创建前错误处理；启动成功后的一切失败归 parser 终态路径（不 throw）。
+ *
+ * 杀链（对齐点②收口）：SIGTERM → grace → SIGKILL 的实现单一权威 =
+ * common/kill-chain.killChain（ChildProcess 结构满足 KillableChild）——本模块只保留
+ * killedByUs 标志（合成终态判据：「我方介入过」与「引擎自身失败」的区分）与幂等守卫。
+ */
+export function launchZcodeProcess(opts: ZcodeLaunchOptions): ZcodeLaunchedProcess {
+  const nodeBin = opts.nodeBin ?? "node";
+  const child = spawn(nodeBin, [opts.cliPath, ...opts.args], {
+    env: opts.env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  let exited = false;
+  let killTriggered = false;
+
+  // ENOENT（node 缺失）等 spawn 失败经 'error' 事件异步到达且 stdout/stderr 可能为
+  // null——空流兜底，保证消费方（parser）始终拿到可读流
+  const emptyStream = (): Readable => Readable.from([]);
+  const stdoutStream = child.stdout ?? emptyStream();
+  const stderrStream = child.stderr ?? emptyStream();
+
+  const exitedPromise = new Promise<{ code: number | null; signal: string | undefined }>((resolve) => {
+    child.once("close", (code, signal) => {
+      exited = true;
+      resolve({ code, signal: signal ?? undefined });
+    });
+    child.once("error", () => {
+      // spawn 失败（ENOENT 等）也会走 error；close 不一定触发，这里兜底 resolve 防
+      // exited 永挂——code 取 null（无引擎语义可判）
+      exited = true;
+      resolve({ code: null, signal: undefined });
+    });
+  });
+
+  const abort = (graceMs: number = ZCODE_KILL_GRACE_MS): Promise<void> => {
+    if (!killTriggered && !exited) {
+      killTriggered = true;
+      // 公共杀链（不 await：abort 以 exitedPromise 为准；killChain 自身含 grace/
+      // SIGKILL/收尸全时序，fire-and-forget 不改变 abort 的 resolve 语义）
+      void killChain(child, { graceMs });
+    }
+    return exitedPromise.then(() => undefined);
+  };
+
+  return {
+    child,
+    pid: child.pid ?? -1,
+    stdout: stdoutStream,
+    stderr: stderrStream,
+    abort,
+    exited: exitedPromise,
+    killedByUs: () => killTriggered,
+  };
+}

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

@@ -0,0 +1,436 @@
+// src/execution/engine/engines/zcode/parser.ts
+//
+// ZcodeEngine parser（P3）：stdout 有界收集 → 终 JSON 解析 → 合成 coarse AgentEvent
+// 流（设计 §3.3.7「批量引擎进程退出后一次性 emit 合成事件」形态）。TS 重写自 zsub
+// driver.js 的 createBoundedLineBuffer / parseStdoutJson，机制保留：
+//   - 有界双缓冲（头 4K + 尾 64K）：zcode response 可达数十 KB，无上限累加在长任务
+//     下爆内存；超限以「行」为单位丢弃，头尾各自保持可读。代价：单行 JSON 超过尾部
+//     窗口时无法完整解析——按错误路径处理（错误信息带尾部），内存安全优先。
+//   - 容错解析：正常是单个 JSON 文档；混入日志行则截取首尾大括号间内容。
+//
+// 事件产出不变量（设计 §3.3.7，coarse 口径）：turn_end 前至少一个 message_end；
+// message_end.usage 出现时为完整 AgentUsage 形状（缺数据给显式 0，不给残缺对象）。
+
+import type { Readable } from "node:stream";
+
+import type { AgentUsage as ExecutionAgentUsage } from "../../../types.ts";
+import type { AgentUsage as OutcomeAgentUsage } from "../../../../orchestration/models/types.ts";
+import type { AgentEvent } from "../../types.ts";
+import { ZCODE_ERROR_TAIL_CHARS } from "./constants.ts";
+import type { ZcodeLaunchedProcess } from "./launcher.ts";
+
+// ============================================================
+// 有界行缓冲（zsub createBoundedLineBuffer 移植）
+// ============================================================
+
+export interface BoundedLineBuffer {
+  push(chunk: string): void;
+  flush(): void;
+  text(): string;
+  tail(n: number): string;
+}
+
+const DEFAULT_HEAD_BYTES = 4096;
+// eslint-disable-next-line no-magic-numbers -- 64KB = 64 * 1024 bytes
+const DEFAULT_TAIL_BYTES = 64 * 1024;
+
+export function createBoundedLineBuffer(opts: { headLimit?: number; tailLimit?: number } = {}): BoundedLineBuffer {
+  const headLimit = opts.headLimit ?? DEFAULT_HEAD_BYTES;
+  const tailLimit = opts.tailLimit ?? DEFAULT_TAIL_BYTES;
+  let pending = "";
+  let head = "";
+  let headFull = false;
+  const tailLines: string[] = [];
+  let tailBytes = 0;
+  let droppedBytes = 0;
+
+  function addLine(line: string): void {
+    if (!headFull) {
+      if (head.length + line.length <= headLimit) {
+        head += line;
+        return;
+      }
+      headFull = true;
+    }
+    tailLines.push(line);
+    tailBytes += line.length;
+    // 超出尾部窗口：从最旧的行开始丢
+    while (tailBytes > tailLimit && tailLines.length > 1) {
+      const dropped = tailLines.shift()!;
+      tailBytes -= dropped.length;
+      droppedBytes += dropped.length;
+    }
+    // 单行超过整个尾部窗口：只保留该行结尾（JSON 的错误信息通常在末尾）
+    if (tailBytes > tailLimit && tailLines.length === 1) {
+      const over = tailBytes - tailLimit;
+      tailLines[0] = tailLines[0]!.slice(over);
+      tailBytes -= over;
+      droppedBytes += over;
+    }
+  }
+
+  return {
+    push(chunk: string): void {
+      pending += chunk;
+      let nl: number;
+      while ((nl = pending.indexOf("\n")) >= 0) {
+        addLine(pending.slice(0, nl + 1));
+        pending = pending.slice(nl + 1);
+      }
+    },
+    flush(): void {
+      if (pending !== "") {
+        addLine(pending);
+        pending = "";
+      }
+    },
+    text(): string {
+      this.flush();
+      const mid =
+        droppedBytes > 0 ? `\n[zcode-engine] 输出过长，头尾之间已丢弃 ${droppedBytes} 字节\n` : "";
+      return head + mid + tailLines.join("");
+    },
+    tail(n: number): string {
+      const t = this.text();
+      return t.length > n ? t.slice(t.length - n) : t;
+    },
+  };
+}
+
+// ============================================================
+// 终 JSON 解析（含运行时 guard——禁 any）
+// ============================================================
+
+/** stdout 里的原生 usage 形状（2026-08-25 实测 0.16.5，字段名带 Tokens 后缀）。 */
+export interface ZcodeRawUsage {
+  source?: unknown;
+  modelRequestCount?: unknown;
+  inputTokens?: unknown;
+  outputTokens?: unknown;
+  totalTokens?: unknown;
+  cacheReadTokens?: unknown;
+  cacheWriteTokens?: unknown;
+  reasoningTokens?: unknown;
+}
+
+/** 容错解析 stdout：直接 JSON.parse；失败则截取首尾大括号间内容再试。 */
+export function parseZcodeStdoutJson(stdout: string): unknown {
+  const trimmed = stdout.trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch (err) {
+    // 混入日志行等形态——吞掉异常继续首尾大括号容错提取（malformed 是降级输入不是错误态）
+    void err;
+  }
+  const first = trimmed.indexOf("{");
+  const last = trimmed.lastIndexOf("}");
+  if (first >= 0 && last > first) {
+    try {
+      return JSON.parse(trimmed.slice(first, last + 1));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function finiteOr(v: unknown, fallback: number): number {
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+/** 原生 usage → 事件层 AgentUsage（execution 版：四项 token；cost 无来源缺省）。 */
+export function mapZcodeUsage(raw: unknown): ExecutionAgentUsage | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const r = raw as ZcodeRawUsage;
+  if (r.inputTokens === undefined && r.outputTokens === undefined) return undefined;
+  return {
+    input: finiteOr(r.inputTokens, 0),
+    output: finiteOr(r.outputTokens, 0),
+    cacheRead: finiteOr(r.cacheReadTokens, 0),
+    cacheWrite: finiteOr(r.cacheWriteTokens, 0),
+  };
+}
+
+/**
+ * 原生 usage + projection → 终态层 AgentUsage（orchestration 版：cost/contextTokens/
+ * turns 为必填）。zcode 不回传 cost（调研附录 A「cost 回传 ❌」）——显式 0（消费方按
+ * 「显示降级」处理，不给残缺）；contextTokens 取 projection.contextUsed（当前上下文
+ * 占用），turns 取 projection.turnCount。
+ */
+export function mapZcodeOutcomeUsage(rawUsage: unknown, projection: unknown): OutcomeAgentUsage | undefined {
+  const base = mapZcodeUsage(rawUsage);
+  if (base === undefined) return undefined;
+  const p =
+    typeof projection === "object" && projection !== null ? (projection as Record<string, unknown>) : {};
+  const r = typeof rawUsage === "object" && rawUsage !== null ? (rawUsage as ZcodeRawUsage) : {};
+  const contextTokens = firstFinite(p["contextUsed"], r.totalTokens, 0);
+  const turns = firstFinite(p["turnCount"], 1);
+  return { ...base, cost: 0, contextTokens, turns };
+}
+
+function firstFinite(...vals: unknown[]): number {
+  for (const v of vals) {
+    const n = typeof v === "number" ? v : Number(v);
+    if (Number.isFinite(n)) return n;
+  }
+  return 0;
+}
+
+/** 终 JSON 的解析产物（引擎消费面——response 必须是 string 才算合法终态）。 */
+export interface ZcodeTerminalPayload {
+  sessionId?: string;
+  response: string;
+  /** 事件层 usage（execution 版 AgentUsage——message_end 合成用）。 */
+  usage?: ExecutionAgentUsage;
+  /** 终态层 usage（orchestration 版 AgentUsage——AgentOutcome.usage 用）。 */
+  outcomeUsage?: OutcomeAgentUsage;
+  /** projection.turnCount（gui/record 的轮数参考；解析不出则缺省）。 */
+  turnCount?: number;
+}
+
+export type ZcodeTerminalParse =
+  | { ok: true; payload: ZcodeTerminalPayload }
+  | { ok: false; reason: string };
+
+/** 解析终 JSON 并做形状校验（sessionId/usage/turnCount 逐字段 guard）。 */
+export function parseZcodeTerminal(stdout: string): ZcodeTerminalParse {
+  const parsed = parseZcodeStdoutJson(stdout);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, reason: "stdout 不是 JSON 对象" };
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (typeof obj.response !== "string") {
+    return { ok: false, reason: "终 JSON 缺 string 型 response 字段（zcode 格式漂移嫌疑）" };
+  }
+  const usage = mapZcodeUsage(obj.usage);
+  const projection =
+    typeof obj.projection === "object" && obj.projection !== null
+      ? (obj.projection as Record<string, unknown>)
+      : undefined;
+  const outcomeUsage = mapZcodeOutcomeUsage(obj.usage, projection);
+  const turnCountRaw = projection?.turnCount;
+  return {
+    ok: true,
+    payload: {
+      response: obj.response,
+      ...(typeof obj.sessionId === "string" ? { sessionId: obj.sessionId } : {}),
+      ...(usage !== undefined ? { usage } : {}),
+      ...(outcomeUsage !== undefined ? { outcomeUsage } : {}),
+      ...(typeof turnCountRaw === "number" && Number.isFinite(turnCountRaw) ? { turnCount: turnCountRaw } : {}),
+    },
+  };
+}
+
+// ============================================================
+// 输出收集（进程退出 + 有界缓冲终态）
+// ============================================================
+
+export interface ZcodeCollectedOutput {
+  exitCode: number | null;
+  signal?: string;
+  /** 有界 stdout 全文（头 4K + 尾 64K，中间丢弃段有标记行）。 */
+  stdoutText: string;
+  /** stderr 尾部（有界 4K）。 */
+  stderrTail: string;
+}
+
+/**
+ * 等待可读流终止（end/close/error 任一，1s 超时兜底）。
+ * 为什么不能只 await 进程退出：宿主在微任务上下文里续跑时（vitest / async 编排链），
+ * 进程 exited 的 promise 续跑可能先于流 data/end 事件的 nextTick 冲刷——直接读缓冲
+ * 会拿到空串。等流终止事件是确定性的「数据已收完」判据；超时兜底防流异常挂起。
+ */
+/** 流终止等待超时（兜底挂起流；比杀链 grace 短一个量级即可）。 */
+const DRAIN_TIMEOUT_MS = 1_000;
+
+function drainReadable(stream: Readable): Promise<void> {
+  return new Promise((resolve) => {
+    if (stream.readableEnded || stream.destroyed) {
+      resolve();
+      return;
+    }
+    let settled = false;
+    const finish = (): void => {
+      if (settled) return;
+      settled = true;
+      stream.removeListener("end", finish);
+      stream.removeListener("close", finish);
+      stream.removeListener("error", finish);
+      clearTimeout(timer);
+      resolve();
+    };
+    stream.once("end", finish);
+    stream.once("close", finish);
+    stream.once("error", finish);
+    const timer = setTimeout(finish, DRAIN_TIMEOUT_MS);
+    if (typeof timer.unref === "function") timer.unref();
+  });
+}
+
+/** 消费进程输出直到退出（事件 emit 前的收集段——终态解析素材）。 */
+export async function collectZcodeOutput(
+  proc: Pick<ZcodeLaunchedProcess, "stdout" | "stderr" | "exited">,
+): Promise<ZcodeCollectedOutput> {
+  const outBuf = createBoundedLineBuffer();
+  // stderr 只做诊断：不进解析路径，尾部 4K 足够
+  const errBuf = createBoundedLineBuffer({ headLimit: 0, tailLimit: DEFAULT_TAIL_BYTES });
+  proc.stdout.on("data", (d: Buffer | string) => {
+    outBuf.push(typeof d === "string" ? d : d.toString("utf8"));
+  });
+  proc.stderr.on("data", (d: Buffer | string) => {
+    errBuf.push(typeof d === "string" ? d : d.toString("utf8"));
+  });
+  const { code, signal } = await proc.exited;
+  await drainReadable(proc.stdout);
+  await drainReadable(proc.stderr);
+  outBuf.flush();
+  errBuf.flush();
+  return {
+    exitCode: code,
+    ...(signal !== undefined ? { signal } : {}),
+    stdoutText: outBuf.text(),
+    stderrTail: errBuf.text(),
+  };
+}
+
+// ============================================================
+// coarse 事件合成（不变量：turn_end 最后、其前至少一个 message_end）
+// ============================================================
+
+/** 终态成功时合成的最小事件序列（coarse 引擎只有终态级信息——设计 D3 eventGranularity）。 */
+export function synthesizeCoarseEvents(response: string, usage?: ExecutionAgentUsage): AgentEvent[] {
+  return [
+    // usage 给不出完整形状时显式缺省整个字段，不给残缺对象（不变量 2）
+    { type: "message_end", ...(usage !== undefined ? { usage } : {}) },
+    { type: "turn_end" },
+  ] as AgentEvent[];
+}
+
+// ============================================================
+// engine_run_failed 错误文案（设计 §3.3.3 错误规格行）
+// ============================================================
+
+/**
+ * 运行中失败的结构化文案：stdout 尾部 2000 字 + exit code + 恢复指引。
+ *
+ * 指引按 stderr 特征归因（2026-08-25 真机教训：LLM 端点不可达导致的
+ * AI_APICallError 曾套用「查版本/重跑探针/补 golden」指引，误导排查方向）：
+ *   - LLM API 调用失败（stderr 含 AI_APICallError）：CLI 本体与输出解析正常，
+ *     指向池内 provider 的 baseURL/apiKey 排查；
+ *   - 其余（spawn 成功但格式漂移/解析失败）：保留 probe/golden 指引。
+ */
+/** 错误文案里 stderr 尾部回显长度（stdout 有专用 2000 常量，stderr 更短防刷屏）。 */
+const STDERR_TAIL_IN_MSG_CHARS = 500;
+
+/** vercel.ai SDK 的 API 调用错误类名——zcode CLI 内部 LLM 调用失败的稳定特征。 */
+const LLM_API_FAILURE_SIGNATURE = "APICallError";
+
+/**
+ * LLM/turn 级失败判定。两种实测形态（2026-08-25 真机）：
+ *   - 无响应形态（端点不可达）：stderr 含 AI_APICallError 类名 + Symbol 行；
+ *   - 有响应形态（如 HTTP 401）：stderr 打印 response headers + responseStatus/
+ *     statusCode，类名行被截断不在尾部——靠 `Turn execution failed`（zcode CLI
+ *     turn 失败统一尾巴）兜住。
+ */
+function isLlmTurnFailure(stderrTail: string | undefined): boolean {
+  if (stderrTail === undefined) return false;
+  return (
+    stderrTail.includes(LLM_API_FAILURE_SIGNATURE) ||
+    stderrTail.includes("Turn execution failed")
+  );
+}
+
+/** stderr 中提取 HTTP 状态码（有响应形态），用于凭据/限流/上游错误的定向指引。 */
+function extractHttpStatus(stderrTail: string | undefined): string {
+  if (stderrTail === undefined) return "";
+  const m = stderrTail.match(/statusCode:\s*(\d{3})/);
+  if (m === null) return "";
+  const code = m[1]!;
+  const meaning: Record<string, string> = {
+    "401": "——凭据无效或过期（apiKey 被上游拒绝）",
+    "403": "——凭据无权限（apiKey 有效但无该模型/资源权限）",
+    "404": "——模型或路径不存在（核对模型名与 baseURL）",
+    "429": "——限流/配额耗尽",
+  };
+  return `，HTTP ${code}${meaning[code] ?? ""}`;
+}
+
+/**
+ * 折叠 stderr 里 console.log 浅序列化产生的 "[Object]" 噪音行
+ * （真实堆栈里常出现连续十余行 `[Object], [Object], …`，折叠后保留计数）。
+ */
+function compactStderrObjectNoise(tail: string): string {
+  const OBJECT_LINE = /^(\[Object\][,\s]*)+$/;
+  const lines = tail.split("\n");
+  const out: string[] = [];
+  let run = 0;
+  const flush = (): void => {
+    if (run > 0) {
+      out.push(`[Object]×${run}`);
+      run = 0;
+    }
+  };
+  for (const line of lines) {
+    if (OBJECT_LINE.test(line.trim())) {
+      run++;
+      continue;
+    }
+    flush();
+    out.push(line);
+  }
+  flush();
+  return out.join("\n");
+}
+
+export function buildRunFailedMessage(opts: {
+  /** 实际使用的 CLI 路径（用户可经 XYZ_ZCODE_CLI 覆盖——文案必须引用真路径，不硬编码缺省值）。 */
+  cliPath: string;
+  exitCode: number | null;
+  stdoutTail: string;
+  stderrTail?: string;
+  parseReason?: string;
+  /** 本次任务解析出的模型全名（provider/model）——LLM 失败归因时点名排查对象。 */
+  modelRef?: string;
+  /** 池内 config.json 绝对路径——LLM 失败归因时给出 baseURL/apiKey 核对位置。 */
+  configPath?: string;
+}): string {
+  const parts: string[] = [];
+  if (opts.parseReason !== undefined) {
+    parts.push(`解析失败：${opts.parseReason}。`);
+  }
+  parts.push(`exit code: ${opts.exitCode ?? "null（被信号杀死）"}。`);
+  if (opts.stderrTail !== undefined && opts.stderrTail.trim() !== "") {
+    const compacted = compactStderrObjectNoise(opts.stderrTail);
+    parts.push(`stderr 尾部: ${compacted.slice(-STDERR_TAIL_IN_MSG_CHARS)}`);
+  }
+  // stdout 空段跳过（与 stderr 同判）——turn 0 即失败时 stdout 恒空，保留空 part
+  // 只会制造「stdout 尾部: <指引段>」的视觉嵌套误读（2026-08-25 真机复盘）
+  if (opts.stdoutTail.trim() !== "") {
+    parts.push(`stdout 尾部: ${opts.stdoutTail.slice(-ZCODE_ERROR_TAIL_CHARS)}`);
+  }
+
+  if (isLlmTurnFailure(opts.stderrTail)) {
+    const statusHint = extractHttpStatus(opts.stderrTail);
+    const modelHint =
+      opts.modelRef !== undefined ? `（本任务模型 '${opts.modelRef}'）` : "";
+    const configHint =
+      opts.configPath !== undefined
+        ? `① 核对池内 provider 的 baseURL 可达性与 apiKey 有效性（\`${opts.configPath}\`）${statusHint.includes("401") || statusHint.includes("403") ? "——apiKey 大概率无效或过期，需在凭据来源（ZCode 桌面或自建网关）更新" : ""}；`
+        : `① 核对 zcode 池内 provider 的 baseURL 可达性与 apiKey 有效性${statusHint}；`;
+    parts.push(
+      `恢复指引：模型 API 调用失败${statusHint}——CLI 本体与输出解析正常，问题在模型端点或凭据${modelHint}。` +
+        configHint +
+        "② 修复后直接重跑本任务（probe 缓存不受影响——运行期失败不缓存）；" +
+        "③ 或任务显式指定其他可用模型（provider/model 全名）；" +
+        "④ 或改用 engine: pi 重跑本任务。",
+    );
+  } else {
+    parts.push(
+      `恢复指引：跑 \`node ${opts.cliPath} --version\` 确认版本后重跑探针（probe）——` +
+        "若为格式漂移，把新 stdout 样本补录进 golden 库（\`__tests__/__fixtures__/zcode-golden-spawn.json\`）并更新 parser；" +
+        "或改用 engine: pi 重跑本任务。详见 docs/research/agent-engine-zcode.md。",
+    );
+  }
+  return `engine_run_failed: zcode CLI 运行失败。${parts.join(" ")}`;
+}