@zhushanwen/subagent-core 0.2.0

package/src/execution/engine/engines/pi/task-spec-mapper.ts

@@ -0,0 +1,100 @@
+// src/execution/engine/engines/pi/task-spec-mapper.ts
+//
+// AgentTaskSpec ↔ ExecuteOptions 映射（P1 回填）。pi 专有语义的隔离点（设计 §3.3.5
+// 删字段去向 + P1 行「ExecuteOptions→AgentTaskSpec 映射层」）：
+//   - effort ↔ thinkingLevel：pi 的 7 档枚举是引擎私有语义，中立层只透传字符串——
+//     pi 侧恒等映射（不识别的档位与现状一致：交 resolveModel 层处理）；
+//   - persona ↔ skillPath + appendSystemPrompt：skillPath 并入 persona 语义（D2），
+//     pi 侧原样还原（pi 的 persona 注入通道 = --skill/--append-system-prompt flag）；
+//   - schemaEnv 内化：中立层无此字段，PiEngine 从 task.schema 派生（stringifySchemaCached
+//     compact——与 agent-opts-resolver 同一函数同一缓存，逐字节等值，D-A6 bridge 保真）；
+//   - conversation/idleTimeoutMs：interact 控制面的 task 标志，原名透传。
+//
+// 往返保真（验收 A1 的映射层证据）：executeOptionsToTaskSpec ∘ taskSpecToExecuteOptions
+// 对全部 ExecuteOptions 字段恒等（schemaEnv 由 schema 派生后逐字节等于原值——resolver
+// 与本 mapper 共用 WeakMap 缓存的同一 compact 串）。唯一归一化：appendSystemPrompt: []
+// 归一为 persona 缺省（下游 spread 空数组与 undefined 均为 no-op，行为等价）。
+
+import type { ModelInfo } from "../../../model-resolver.ts";
+import type { ExecuteOptions } from "../../../types.ts";
+import { stringifySchemaCached } from "../../../../shared/schema-jsonify.ts";
+import type { AgentTaskSpec, PersonaSpec } from "../../types.ts";
+
+/**
+ * ExecuteOptions → AgentTaskSpec（宿主侧声明 → 引擎中立声明）。
+ * 纯函数、无副作用——同一 opts 可重复转换（幂等）。
+ */
+export function executeOptionsToTaskSpec(opts: ExecuteOptions): AgentTaskSpec {
+  // persona 归并：skillPath / appendSystemPrompt 有其一即建 persona，避免空对象噪声。
+  const persona: PersonaSpec | undefined =
+    opts.skillPath !== undefined || opts.appendSystemPrompt !== undefined
+      ? {
+          ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
+          ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
+        }
+      : undefined;
+  return {
+    task: opts.task,
+    slug: opts.slug,
+    agent: opts.agent,
+    model: opts.model,
+    // pi 7 档枚举 → 引擎无关 effort（恒等：档位集合是 pi 私有语义，中立层透传）
+    effort: opts.thinkingLevel,
+    ...(persona !== undefined ? { persona } : {}),
+    schema: opts.schema,
+    maxTurns: opts.maxTurns,
+    graceTurns: opts.graceTurns,
+    fork: opts.fork,
+    worktree: opts.worktree,
+    cwd: opts.cwd,
+    conversation: opts.conversation,
+    idleTimeoutMs: opts.idleTimeoutMs,
+    // ExecuteOptions 不携带的运行期字段（signal/ctxModel/onComplete）归 RunContext；
+    // schemaEnv 由 taskSpecToExecuteOptions 从 schema 派生。
+  };
+}
+
+/**
+ * AgentTaskSpec → ExecuteOptions（pi 引擎侧还原）。
+ *
+ * @param spec 中立任务声明
+ * @param runCtx 运行期上下文：ctxModel 是 ExecuteOptions 的运行期字段（从 RunContext
+ *               回填）；schemaEnvFallback 是解耦形态（有 schemaEnv 无 schema，生产
+ *               不可达）的兜底透传——schema 可派生时派生优先（逐字节等值）
+ */
+export function taskSpecToExecuteOptions(
+  spec: AgentTaskSpec,
+  runCtx?: { ctxModel?: ModelInfo; schemaEnvFallback?: string },
+): ExecuteOptions {
+  return {
+    task: spec.task,
+    slug: spec.slug,
+    // 身份解析键：spec.agent 优先；persona.agentRef 是 persona 注入通道的定位符，
+    // 仅在 spec.agent 缺失时兜底（flag/file 通道引擎的主路径；pi 恒走 spec.agent）
+    agent: spec.agent ?? spec.persona?.agentRef,
+    model: spec.model,
+    // effort → pi thinkingLevel（恒等映射）
+    thinkingLevel: spec.effort,
+    // persona 还原：pi 的注入通道是 --skill / --append-system-prompt flag
+    skillPath: spec.persona?.skillPath,
+    appendSystemPrompt: spec.persona?.appendSystemPrompt,
+    schema: spec.schema,
+    // schemaEnv 内化派生（D-A6 bridge）：与 agent-opts-resolver 共用 stringifySchemaCached
+    // compact 缓存，输出逐字节等值。schema 缺失（无法派生）且调用方持有预编码值时兜底
+    // 透传（解耦形态，生产不可达）；无 schema 亦无兜底时不设（BC-6：childEnv 不注入）。
+    schemaEnv: spec.schema !== undefined
+      ? stringifySchemaCached(spec.schema, "compact")
+      : runCtx?.schemaEnvFallback,
+    maxTurns: spec.maxTurns,
+    graceTurns: spec.graceTurns,
+    ctxModel: runCtx?.ctxModel,
+    fork: spec.fork,
+    worktree: spec.worktree,
+    cwd: spec.cwd,
+    conversation: spec.conversation,
+    idleTimeoutMs: spec.idleTimeoutMs,
+    // signal 不入 opts（PiEngine 直接传给 executeAndAwait 第 2 参，与 SAR 现行为一致）；
+    // onComplete 不经引擎（workflow 路径从不设置；background 完成通知走 service 内部 notifier）。
+    // denyTools/permissionMode：中立新字段，pi 链路暂无对应面（P2 公共层接 denylist 映射）。
+  };
+}

package/src/execution/engine/engines/zcode/__tests__/__fixtures__/zcode-golden-spawn.json

@@ -0,0 +1,39 @@
+{
+  "_meta": {
+    "description": "zcode CLI spawn 单轮模式 golden 实录（2026-08-25 验收前置门）",
+    "engineVersion": "0.16.5",
+    "recordedAt": "2026-08-25T01:41:43Z",
+    "recordedOn": "macOS arm64, node v24.11.1",
+    "argv": [
+      "node",
+      "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
+      "--json",
+      "--cwd",
+      "<临时目录>",
+      "--mode",
+      "yolo",
+      "--prompt",
+      "Reply with the single word: ok"
+    ],
+    "envSummary": {
+      "HOME": "<隔离池目录>（config.json = model.main + 目标 provider 条目，无 plugins 块）",
+      "stdin": "/dev/null（stdio ignore——CLI 不读 stdin，否则挂起）",
+      "XYZ_AGENT_SUBAGENT": "实录未注入；引擎实现注入 =1"
+    },
+    "exitCode": 0,
+    "durationMs": 4914,
+    "fieldStructure": {
+      "sessionId": "string，sess_<uuid>",
+      "traceId": "string（诊断用）",
+      "turnId": "string，turn_<uuid>",
+      "response": "string——assistant 全文",
+      "usage": "object：source/modelRequestCount/inputTokens/outputTokens/totalTokens/cacheReadTokens/cacheWriteTokens/reasoningTokens/webFetchRequests/webSearchRequests",
+      "eventCount": "number",
+      "projection": "object：status/turnCount/totalTokenCount/contextUsed/contextWindow"
+    },
+    "usageMapping": "inputTokens→input、outputTokens→output、cacheReadTokens→cacheRead、cacheWriteTokens→cacheWrite；cost 无来源（cost 回传 ❌ 与调研一致）",
+    "credentialNote": "stdout 不含凭据；凭据只存在于池内 config.json（此处不收录）。隔离 HOME 的凭据源用 ~/.zcode/v2/config.json（桌面登录态）——本机 ~/.zcode/cli/config.json 的 router provider 指向局域网网关 192.168.1.202:9981，实录时不可达",
+    "sigtermTiming": "SIGTERM → exit 实测 103ms（exit code 143，stderr \"Turn was cancelled\"）；引擎杀链 grace 取 5000ms（zsub 同构，保守）"
+  },
+  "stdoutRaw": "{\n  \"sessionId\": \"sess_35852a0f-1302-4e20-9e48-87f47527abe3\",\n  \"traceId\": \"9fffaebd-749e-468b-af3f-2a89e3347785\",\n  \"turnId\": \"turn_99879260-1c9b-4e97-afe1-c2e7abeaf5b9\",\n  \"response\": \"ok\",\n  \"usage\": {\n    \"source\": \"provider\",\n    \"modelRequestCount\": 1,\n    \"inputTokens\": 12599,\n    \"outputTokens\": 17,\n    \"totalTokens\": 12616,\n    \"cacheReadTokens\": 512,\n    \"cacheWriteTokens\": 0,\n    \"reasoningTokens\": 0,\n    \"webFetchRequests\": 0,\n    \"webSearchRequests\": 0\n  },\n  \"eventCount\": 17,\n  \"projection\": {\n    \"status\": \"idle\",\n    \"turnCount\": 1,\n    \"totalTokenCount\": 12616,\n    \"contextUsed\": 12616,\n    \"contextWindow\": 1000000\n  }\n}\n"
+}

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

@@ -0,0 +1,150 @@
+// launcher.test.ts —— argv 组装 / 字节估算超限 / env 构造 / 真实子进程杀链（用 node -e
+// 代替 zcode CLI，验证 SIGTERM→grace→SIGKILL 与 exited 标志机制本身）。
+
+import { execFileSync } from "node:child_process";
+
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_ARGV_BUDGET_BYTES, estimateArgvBytes } from "../../../common/persona-router.ts";
+import {
+  assertZcodeArgvBudget,
+  buildZcodeArgv,
+  buildZcodeEnv,
+  launchZcodeProcess,
+} from "../launcher.ts";
+
+describe("buildZcodeArgv", () => {
+  it("基础形态：--json --cwd --mode yolo --prompt 尾置", () => {
+    const args = buildZcodeArgv({ cwd: "/tmp/w", prompt: "do it" });
+    expect(args).toEqual(["--json", "--cwd", "/tmp/w", "--mode", "yolo", "--prompt", "do it"]);
+  });
+
+  it("denyTools 逗号连接进 --disallowed-tools", () => {
+    const args = buildZcodeArgv({ cwd: "/w", prompt: "p", denyTools: ["bash", "edit"] });
+    expect(args).toContain("--disallowed-tools");
+    expect(args[args.indexOf("--disallowed-tools") + 1]).toBe("bash,edit");
+  });
+
+  it("denyTools 空/空白项过滤，全空不加 flag", () => {
+    expect(buildZcodeArgv({ cwd: "/w", prompt: "p", denyTools: [] })).not.toContain("--disallowed-tools");
+    expect(buildZcodeArgv({ cwd: "/w", prompt: "p", denyTools: ["  ", ""] })).not.toContain("--disallowed-tools");
+  });
+
+  it("resumeSessionId 落 --resume（prompt 之前）", () => {
+    const args = buildZcodeArgv({ cwd: "/w", prompt: "p", resumeSessionId: "sess_x" });
+    expect(args.indexOf("--resume")).toBeLessThan(args.indexOf("--prompt"));
+    expect(args[args.indexOf("--resume") + 1]).toBe("sess_x");
+  });
+});
+
+describe("assertZcodeArgvBudget（对齐点②：公共 persona-router 权威预算的引擎侧消费）", () => {
+  it("估算含 node 与 cliPath 前导（NUL 分隔近似），中文 prompt 按字节计", () => {
+    // 公共 estimateArgvBytes 的口径回归：前导两元素计入 + 多字节按 UTF-8 字节
+    const est = estimateArgvBytes(["n", "c", "--prompt", "中文"]);
+    expect(est).toBe(2 + 2 + ("--prompt".length + 1) + Buffer.byteLength("中文") + 1);
+  });
+
+  it("超 128KB 阈值抛 prompt_too_large（含恢复指引；阈值 = DEFAULT_ARGV_BUDGET_BYTES）", () => {
+    const bigPrompt = "x".repeat(DEFAULT_ARGV_BUDGET_BYTES);
+    expect(() => assertZcodeArgvBudget("node", "/cli.cjs", ["--prompt", bigPrompt])).toThrowError(
+      /prompt_too_large/,
+    );
+    try {
+      assertZcodeArgvBudget("node", "/cli.cjs", ["--prompt", bigPrompt]);
+    } catch (err) {
+      // 公共 EngineError 形态：message 是 code 前缀 detail，恢复指引在 recovery 字段
+      expect((err as { code: string }).code).toBe("prompt_too_large");
+      expect((err as { recovery: string }).recovery).toContain("Shorten the task text");
+    }
+  });
+
+  it("阈值内不抛", () => {
+    expect(() => assertZcodeArgvBudget("node", "/cli.cjs", ["--prompt", "x".repeat(1024)])).not.toThrow();
+  });
+});
+
+describe("buildZcodeEnv", () => {
+  it("HOME 强制覆盖（同名键不许覆盖隔离值）+ 统一嵌套标记（经公共 nesting-guard）", () => {
+    const env = buildZcodeEnv("/pool/home", { HOME: "/real/home", PATH: "/usr/bin" });
+    expect(env["HOME"]).toBe("/pool/home");
+    expect(env["XYZ_AGENT_SUBAGENT"]).toBe("1");
+    expect(env["PATH"]).toBe("/usr/bin");
+  });
+
+  it("剥离引擎原生嵌套标记（D8：防孙代理误判已在嵌套层）", () => {
+    const env = buildZcodeEnv("/pool/home", {
+      ZSW_NESTED: "1",
+      CLAUDECODE: "1",
+      PI_SUBAGENT_SELF_RECORD_ID: "sa-x",
+      PI_SUBAGENT_DEPTH: "2",
+    });
+    expect(env["ZSW_NESTED"]).toBeUndefined();
+    expect(env["CLAUDECODE"]).toBeUndefined();
+    expect(env["PI_SUBAGENT_SELF_RECORD_ID"]).toBeUndefined();
+    expect(env["PI_SUBAGENT_DEPTH"]).toBeUndefined();
+    expect(env["XYZ_AGENT_SUBAGENT"]).toBe("1");
+  });
+});
+
+describe("launchZcodeProcess：真实子进程杀链（node -e 代替 CLI）", () => {
+  // 杀链/exited 机制与 CLI 无关（对子进程发信号 + close 事件），用 `node -e <script>`
+  // 验证机制本身：launchZcodeProcess 的 spawn 形态是 `node <cliPath> <args...>`，
+  // 测试借 cliPath 槽位传 -e、args 传脚本内容。
+  it("child 句柄暴露（D10 记账数据源）：proc.child 即 spawn 出的进程，退出码可读", async () => {
+    const proc = launchZcodeProcess({
+      cliPath: "-e",
+      args: ["process.stdout.write('hi'); process.exit(0)"],
+      env: process.env,
+    });
+    // 句柄与 pid 同源（宿主经 RunContext.onChildSpawned 注册进 spawnedChildren）
+    expect(proc.child.pid).toBe(proc.pid);
+    expect(proc.child.killed).toBe(false);
+    const exited = await proc.exited;
+    expect(exited.code).toBe(0);
+    expect(proc.child.exitCode).toBe(0); // close 后 exitCode 可读（close 事件先于 exited resolve）
+  });
+
+  it("正常退出：exited 带退出码，stdout 可收集", async () => {
+    const proc = launchZcodeProcess({
+      cliPath: "-e",
+      args: ["process.stdout.write('hello'); process.exit(0)"],
+      env: process.env,
+    });
+    let out = "";
+    proc.stdout.on("data", (d: Buffer) => {
+      out += d.toString();
+    });
+    const exited = await proc.exited;
+    expect(out).toBe("hello");
+    expect(exited.code).toBe(0);
+    expect(proc.killedByUs()).toBe(false);
+  });
+
+  it("abort 触发杀链：SIGTERM 后进程退出，killedByUs 标记", async () => {
+    const proc = launchZcodeProcess({
+      cliPath: "-e",
+      args: ["setInterval(() => {}, 1000)"],
+      env: process.env,
+    });
+    expect(proc.pid).toBeGreaterThan(0);
+    // 实测 zcode 对 SIGTERM ~103ms 退出；普通 node 进程无 handler 直接终止
+    const abortPromise = proc.abort(3000);
+    const exited = await proc.exited;
+    await abortPromise;
+    expect(exited.code === null || exited.code === 143 || exited.code === 1).toBe(true);
+    expect(proc.killedByUs()).toBe(true);
+    // 无僵尸：进程已从系统进程表消失
+    expect(() => execFileSync("ps", ["-p", String(proc.pid)])).toThrow();
+  });
+
+  it("abort 幂等：重复调用不再触发第二条杀链", async () => {
+    const proc = launchZcodeProcess({
+      cliPath: "-e",
+      args: ["setInterval(() => {}, 1000)"],
+      env: process.env,
+    });
+    await proc.abort(2000);
+    await proc.abort(2000); // 不应抛
+    await proc.exited;
+  });
+});

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

@@ -0,0 +1,246 @@
+// parser.test.ts —— golden 样本回归（验收 2）+ 损坏 stdout 错误路径 + 缓冲有界性。
+// golden 原文来自 2026-08-25 真机实录（zcode 0.16.5），采集元数据见 fixture _meta。
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  buildRunFailedMessage,
+  createBoundedLineBuffer,
+  mapZcodeUsage,
+  parseZcodeStdoutJson,
+  parseZcodeTerminal,
+  synthesizeCoarseEvents,
+} from "../parser.ts";
+
+interface GoldenFixture {
+  stdoutRaw: string;
+  _meta: { engineVersion: string; exitCode: number; usageMapping: string };
+}
+
+const golden: GoldenFixture = JSON.parse(
+  readFileSync(fileURLToPath(new URL("./__fixtures__/zcode-golden-spawn.json", import.meta.url)), "utf8"),
+);
+
+describe("parseZcodeTerminal：golden 回归", () => {
+  it("实录样本解析出完整终态（sessionId/response/usage/turnCount）", () => {
+    const r = parseZcodeTerminal(golden.stdoutRaw);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.payload.sessionId).toBe("sess_35852a0f-1302-4e20-9e48-87f47527abe3");
+    expect(r.payload.response).toBe("ok");
+    expect(r.payload.usage).toEqual({ input: 12599, output: 17, cacheRead: 512, cacheWrite: 0 });
+    expect(r.payload.turnCount).toBe(1);
+    // 终态层 usage（orchestration 版）：cost 显式 0（zcode 不回传）、contextTokens=
+    // projection.contextUsed、turns=projection.turnCount
+    expect(r.payload.outcomeUsage).toEqual({
+      input: 12599,
+      output: 17,
+      cacheRead: 512,
+      cacheWrite: 0,
+      cost: 0,
+      contextTokens: 12616,
+      turns: 1,
+    });
+  });
+
+  it("usage 字段名映射：inputTokens→input 等四项（cost 无来源不出现）", () => {
+    const u = mapZcodeUsage({
+      inputTokens: 10,
+      outputTokens: 20,
+      cacheReadTokens: 5,
+      cacheWriteTokens: 0,
+    });
+    expect(u).toEqual({ input: 10, output: 20, cacheRead: 5, cacheWrite: 0 });
+    expect(u !== undefined && "cost" in u).toBe(false);
+  });
+
+  it("usage 形状不完整时显式 undefined（不给残缺对象）", () => {
+    expect(mapZcodeUsage(undefined)).toBeUndefined();
+    expect(mapZcodeUsage("nope")).toBeUndefined();
+    expect(mapZcodeUsage({})).toBeUndefined();
+  });
+});
+
+describe("parseZcodeTerminal：损坏 stdout → ok:false（engine_run_failed 输入）", () => {
+  it("非 JSON 文本", () => {
+    const r = parseZcodeTerminal("Error: something broke\n");
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.reason).toContain("不是 JSON");
+  });
+
+  it("JSON 但缺 string 型 response（格式漂移形态）", () => {
+    const r = parseZcodeTerminal('{"sessionId": "sess_x", "usage": {}}');
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.reason).toContain("response");
+  });
+
+  it("数组/标量 JSON 拒收", () => {
+    expect(parseZcodeTerminal("[1,2,3]").ok).toBe(false);
+    expect(parseZcodeTerminal("42").ok).toBe(false);
+  });
+
+  it("混入日志行时首尾大括号容错提取", () => {
+    const mixed = '[info] boot\n{"sessionId":"sess_a","response":"done"}\n[info] exit';
+    const r = parseZcodeTerminal(mixed);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.payload.sessionId).toBe("sess_a");
+    expect(r.payload.response).toBe("done");
+  });
+});
+
+describe("parseZcodeStdoutJson：空对象形态防御", () => {
+  it("无大括号文本返回 null", () => {
+    expect(parseZcodeStdoutJson("plain text")).toBeNull();
+  });
+});
+
+describe("synthesizeCoarseEvents：coarse 不变量", () => {
+  it("message_end（含 usage）在前、turn_end 最后", () => {
+    const usage = { input: 1, output: 2, cacheRead: 0, cacheWrite: 0 };
+    const evs = synthesizeCoarseEvents("ok", usage);
+    expect(evs).toEqual([{ type: "message_end", usage }, { type: "turn_end" }]);
+  });
+
+  it("无 usage 时 message_end 不带残缺字段", () => {
+    const evs = synthesizeCoarseEvents("ok");
+    expect(evs[0]).toEqual({ type: "message_end" });
+    expect("usage" in evs[0]!).toBe(false);
+    expect(evs[evs.length - 1]).toEqual({ type: "turn_end" });
+  });
+});
+
+describe("buildRunFailedMessage：错误规格（stdout 尾部 + exit code + 恢复指引）", () => {
+  it("含 exit code、尾部内容与三段恢复动作", () => {
+    const msg = buildRunFailedMessage({
+      exitCode: 3,
+      stdoutTail: "x".repeat(5000),
+      stderrTail: "boom",
+      parseReason: "stdout 不是 JSON 对象",
+    });
+    expect(msg).toContain("engine_run_failed");
+    expect(msg).toContain("exit code: 3");
+    expect(msg).toContain("解析失败");
+    expect(msg).toContain("stderr 尾部: boom");
+    // stdout 尾部截断到 2000 字
+    expect(msg).toContain("x".repeat(2000));
+    expect(msg).not.toContain("x".repeat(2001));
+    expect(msg).toContain("--version");
+    expect(msg).toContain("golden");
+    expect(msg).toContain("engine: pi");
+  });
+
+  it("null exit code 标注被信号杀死", () => {
+    const msg = buildRunFailedMessage({ exitCode: null, stdoutTail: "" });
+    expect(msg).toContain("null（被信号杀死）");
+  });
+
+  it("空 stdout 不产生空 part（防「stdout 尾部: <指引段>」视觉嵌套误读）", () => {
+    const msg = buildRunFailedMessage({ exitCode: 1, stdoutTail: "   " });
+    expect(msg).not.toContain("stdout 尾部");
+  });
+
+  it("LLM API 失败（AI_APICallError）归因到端点/凭据指引，不再给 probe 指引", () => {
+    const msg = buildRunFailedMessage({
+      cliPath: "/fake/zcode.cjs",
+      exitCode: 1,
+      stdoutTail: "",
+      stderrTail: "AI_APICallError: 500 Internal Server Error\nError: Turn execution failed",
+      modelRef: "router/mimo-v2.5-pro",
+      configPath: "/pool/.zcode/cli/config.json",
+    });
+    expect(msg).toContain("模型 API 调用失败");
+    expect(msg).toContain("router/mimo-v2.5-pro");
+    expect(msg).toContain("/pool/.zcode/cli/config.json");
+    expect(msg).toContain("baseURL");
+    expect(msg).toContain("engine: pi");
+    // probe/golden 指引不出现（误导排查方向——2026-08-25 真机教训）
+    expect(msg).not.toContain("--version");
+    expect(msg).not.toContain("golden");
+    expect(msg).not.toContain("stdout 尾部");
+  });
+
+  it("401 有响应形态（无 AI_APICallError 类名）也归因，且带 HTTP 状态与凭据定向", () => {
+    const stderr401 = [
+      "  'x-mife-upstream-status': '401'",
+      "  },",
+      "  responseStatus: 401,",
+      "  statusCode: 401",
+      "}",
+      "Error: Turn execution failed (traceId: a487a9b3)",
+    ].join("\n");
+    const msg = buildRunFailedMessage({
+      cliPath: "/fake/zcode.cjs",
+      exitCode: 1,
+      stdoutTail: "",
+      stderrTail: stderr401,
+      modelRef: "router/mimo-v2.5-pro",
+      configPath: "/pool/.zcode/cli/config.json",
+    });
+    expect(msg).toContain("模型 API 调用失败");
+    expect(msg).toContain("HTTP 401");
+    expect(msg).toContain("凭据无效或过期");
+    expect(msg).toContain("apiKey 大概率无效或过期");
+    expect(msg).not.toContain("--version");
+    expect(msg).not.toContain("golden");
+  });
+
+  it("LLM 归因在缺省 modelRef/configPath 时兜底可读", () => {
+    const msg = buildRunFailedMessage({
+      cliPath: "/fake/zcode.cjs",
+      exitCode: 1,
+      stdoutTail: "ok",
+      stderrTail: "Symbol(vercel.ai.error.AI_APICallError): true",
+    });
+    expect(msg).toContain("模型 API 调用失败");
+    expect(msg).toContain("provider 的 baseURL 可达性");
+    expect(msg).not.toContain("undefined");
+  });
+
+  it("stderr 的 [Object] 噪音行折叠为计数", () => {
+    const noisy = [
+      "AIError: fail",
+      ...Array.from({ length: 12 }, () => "  [Object], [Object],"),
+      "    statusCode: undefined,",
+    ].join("\n");
+    const msg = buildRunFailedMessage({ cliPath: "/c", exitCode: 1, stdoutTail: "", stderrTail: noisy });
+    expect(msg).toContain("[Object]×12");
+    expect(msg).not.toContain("[Object], [Object]");
+  });
+});
+
+describe("createBoundedLineBuffer：有界双缓冲", () => {
+  it("头 4K + 尾 64K 保留，中间丢弃并标记", () => {
+    const buf = createBoundedLineBuffer();
+    const line = "a".repeat(100) + "\n"; // 每行 101 字节
+    for (let i = 0; i < 2000; i++) buf.push(line); // ~202KB，远超 4K+64K
+    const text = buf.text();
+    expect(text.startsWith("a".repeat(100))).toBe(true); // 头部保留
+    expect(text).toContain("已丢弃"); // 中间丢弃标记
+    expect(text.endsWith("\n")).toBe(true);
+    // 尾部窗口 ≈ 64K：总长有界
+    expect(text.length).toBeLessThan(4 * 1024 + 64 * 1024 + 200);
+  });
+
+  it("单行超整个尾部窗口时保留行尾（错误信息在末尾）", () => {
+    const buf = createBoundedLineBuffer({ headLimit: 0, tailLimit: 1000 });
+    buf.push("B".repeat(5000) + "\n");
+    const text = buf.text();
+    // 有效载荷 ≤ 1000（text 里另有「已丢弃 N 字节」标记行）
+    expect(text.match(/B/g)?.length ?? 0).toBeLessThanOrEqual(1000);
+    expect(text.endsWith("\n")).toBe(true);
+    expect(text).toContain("已丢弃");
+  });
+
+  it("未超限时原文完整（golden 646 字节场景）", () => {
+    const buf = createBoundedLineBuffer();
+    buf.push(golden.stdoutRaw);
+    expect(buf.text()).toBe(golden.stdoutRaw);
+    expect(buf.tail(10)).toBe(golden.stdoutRaw.slice(-10));
+  });
+});