@zhushanwen/subagent-core 0.2.0

package/src/execution/dialog-queue.ts

@@ -0,0 +1,330 @@
+// src/execution/dialog-queue.ts
+//
+// L2 跨子进程全局 dialog 串行队列。
+//
+// 进程单例语义：跨所有子进程共享，串行所有 dialog 类 UI 请求
+//（isDialogMethod(method)===true，即 select/confirm/input/editor）。
+//
+// 设计动机（.fix-plans/00-master-summary.md §一 冲突 3）：
+//   - L1 per-child 队列（session-runner.createUiRequestQueue）只解决同一子进程内的串行，
+//     多个并行子进程仍可同时把 dialog 请求涌向父 UI（争输入焦点）。
+//   - L2 全局队列在主 agent handler 入口前再串行一次，保证同一时刻主 agent 只呈现一个 dialog。
+//   - 排队绑定 method 交互模型（dialog 才排队），不绑定 channel——排队是 Pi 协议固有属性。
+//
+// SR-4（child close reject）：入队项带 child 引用，child close 时把该 child 的 pending dialog
+//   全部 resolve 为 {cancelled:true}，防 Promise 永挂 + 内存泄漏。
+//
+// handler 抛错兜底：catch → 回 {cancelled:true} → 继续处理下一个。不能让一个失败卡死队列。
+//
+// 调用方约定：只对 dialog 类（isDialogMethod===true）调 enqueue；fire-and-forget 由调用方
+//   直接调 handler（见 ui-request-handler-factory.ts），不经过本队列。enqueue 内仍防御性兼容
+//   fire-and-forget（万一调用方未判）：直接调 handler 返回，不入队串行。调用方不应依赖此防御。
+
+import { isDialogMethod } from "./ui-interaction-model.ts";
+
+// ── 类型定义（本模块是 UiRequest/UiResponse/UiRequestHandler 的规范来源） ──
+// session-runner.ts 和 ui-channels.ts 复用这些类型（session-runner 再导出供测试 import）。
+
+/** Pi extension_ui_request 的方法枚举（dialog + fire-and-forget 两类）。
+ *  dialog 类：select/confirm/input/editor（占输入焦点，等响应）。
+ *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
+ *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
+export type UiMethod =
+  | "select"
+  | "confirm"
+  | "input"
+  | "editor"
+  | "notify"
+  | "setStatus"
+  | "setWidget"
+  | "setTitle"
+  | "set_editor_text"
+  | (string & {});
+
+/** UI 请求（session-runner 构造后传给 handler）。
+ *
+ *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
+ *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
+ *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
+ *
+ *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
+export interface UiRequest {
+  /** Pi rpc-types.ts 的 method（select/confirm/input/editor 为 dialog 类）。 */
+  method: UiMethod;
+  /** 请求 id（从 extension_ui_request envelope 顶层提取，用于 response 关联）。 */
+  id: string;
+  // method 特定字段（按 method 可选，与 ExtensionUiRequest 1:1）
+  title?: string;
+  options?: string[];
+  message?: string;
+  placeholder?: string;
+  prefill?: string;
+  notifyType?: string;
+  statusKey?: string;
+  statusText?: string | undefined;
+  widgetKey?: string;
+  widgetLines?: string[] | undefined;
+  widgetPlacement?: "aboveEditor" | "belowEditor";
+  text?: string;
+  timeout?: number;
+  /** channel 名（从 method 对应字段的 NUL 前缀解析）。
+   *  select → 从 title 解析；setWidget → 从 widgetLines[0] 解析；其他 → undefined。
+   *  已知值："ask_user"（select）、"gui_widget"（setWidget）。handler 按 channel 分发。 */
+  channel?: string;
+  /** channel 解析后的结构化 payload（已 JSON.parse）。
+   *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
+  channelPayload?: unknown;
+  /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
+   *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
+   *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
+  _childPid?: number;
+}
+
+/** UI 响应（handler 返回，session-runner 按 shape 回写 stdin）。
+ *  - {value}: select/input/editor 的答案
+ *  - {confirmed}: confirm 的答案
+ *  - {cancelled}: 取消（child close / handler 抛错 / 用户取消）
+ *  - {ack}: fire-and-forget（当前不透传到 TUI，留作协议完整） */
+export type UiResponse =
+  | { value: string }
+  | { confirmed: boolean }
+  | { cancelled: true }
+  | { ack: true };
+
+/** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
+ *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
+ *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
+export type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
+
+// ── DialogGlobalQueue 实现 ──
+
+/** 入队项的 child 引用形状（只取 pid 用于 rejectChildDialogs 匹配）。 */
+export interface DialogChildRef {
+  pid: number;
+}
+
+/** enqueue 的可选项。child 用于 rejectChildDialogs 关联（child close 时批量 reject）。 */
+export interface EnqueueOptions {
+  child?: DialogChildRef;
+}
+
+/** 队列内一项：请求 + handler + resolve + 所属 child。
+ *  pending 状态持有 resolve，handler 完成 / rejectChildDialogs 时调它 settle Promise。
+ *  settled 标志保证只 settle 一次（rejectChildDialogs 与 handler 完成可能竞争）。 */
+interface QueueItem {
+  req: UiRequest;
+  handler: UiRequestHandler;
+  resolve: (resp: UiResponse) => void;
+  childPid: number | undefined;
+  /** 是否已 settle（防 handler 完成 / rejectChildDialogs 重复 resolve）。 */
+  settled: boolean;
+}
+
+/**
+ * L2 跨子进程全局 dialog 串行队列（进程单例）。
+ *
+ * 用法（createUiRequestHandlerForMode 返回的总 handler 内）：
+ * ```ts
+ * const dialogQueue = new DialogGlobalQueue();
+ * return async (req: UiRequest) => {
+ *   // 调用方负责判断：dialog 入队，fire-and-forget 直接调 realHandler
+ *   if (isDialogMethod(req.method)) return dialogQueue.enqueue(req, realHandler);
+ *   return realHandler(req);
+ * };
+ * ```
+ *
+ * 语义保证：
+ *   - FIFO 串行：前一个 handler settle 后才处理下一个
+ *   - SR-4：rejectChildDialogs(child) 把该 child 的 pending 全部 resolve 为 {cancelled:true}
+ *   - handler 抛错兜底：catch → {cancelled:true} → 继续下一个（队列不卡死）
+ *   - 调用方约定只对 dialog 类调 enqueue；fire-and-forget 由调用方直接调 handler 不入队
+ *（enqueue 内仍防御性兼容 fire-and-forget，但不保证行为）
+ *
+ * 线程模型：纯 Promise + 微任务驱动，无锁。Node 单线程 event loop 保证队列状态一致。
+ *
+ * 单 session 假设（M-2，与 index.ts lastSessionId 同源）：本队列是进程级单例（实例挂在
+ * globalThis[Symbol.for("@zhushanwen/pi-subagents.dialogQueue")]，见 getOrCreateDialogQueue）。
+ * rejectAll() 清空所有 pending dialog——无 per-session 隔离。Pi 当前架构保证单进程
+ * 单 session 串行（同进程不会并发多个 session），故 session_shutdown 调 rejectAll() 只会清掉
+ * 当前 session 的 pending。若未来 Pi 支持同进程多 session 并发，session A 退出会误清 session B
+ * 的 pending dialog——届时需改为 per-session 隔离（入队项 QueueItem 带 sessionId，rejectAll
+ * 改 rejectAllForSession(sessionId)，session_shutdown 只清当前 session）。
+ */
+export class DialogGlobalQueue {
+  /** 等待处理的队列（FIFO）。正在处理的项从 queue shift 出后由 current 持有。 */
+  private queue: QueueItem[] = [];
+  /** 正在处理的项（handler 已调、未 settle）。用于 rejectChildDialogs 取消占位中的 dialog。 */
+  private current: QueueItem | undefined;
+  private processing = false;
+
+  /**
+   * 入队一个 UI 请求，返回 Promise<UiResponse>。
+   *
+   * 调用方约定：只对 dialog 类（isDialogMethod===true）调 enqueue。fire-and-forget 由
+   * 调用方（ui-request-handler-factory.ts）在 enqueue 前判 isDialogMethod 后直接调 handler，
+   * 不经过本队列。enqueue 内仍防御性兼容 fire-and-forget（万一调用方未判）：直接调 handler 返回，
+   * 不入队串行，但调用方不应依赖此防御行为。
+   *
+   * dialog 项处理（TC-E4 case 1）：进队列 FIFO 串行，等前一个 settle 后才调 handler
+   *（争输入焦点，防并发弹窗）。
+   *
+   * handler 抛错兜底：catch → 回 {cancelled:true}（dialog 路径，队列不卡死）。
+   * SR-4：opts.child 用于 rejectChildDialogs 关联（dialog 项会被批量 reject，含 current）。
+   *
+   * @param req UI 请求（约定只传 dialog 类；fire-and-forget 防御性兼容）
+   * @param handler 真正执行请求的 handler（TUI/GUI 模式分流后的 realHandler）
+   * @param opts 可选 child 引用（用于 rejectChildDialogs 关联）
+   * @returns handler 的响应；dialog 抛错时回 {cancelled:true}；child close 时回 {cancelled:true}
+   */
+  enqueue(
+    req: UiRequest,
+    handler: UiRequestHandler,
+    opts?: EnqueueOptions,
+  ): Promise<UiResponse> {
+    // 防御性兼容 fire-and-forget：调用方约定不应传此类 req 进 enqueue（factory 层已判
+    // isDialogMethod 直接调 handler），但万一调用方未判，这里直接调 handler 不入队，避免阻塞。
+    // 直接返回 handler 真实结果（不做兜底形变为 cancelled——fire-and-forget 无串行语义）。
+    if (!isDialogMethod(req.method)) {
+      return handler(req);
+    }
+    // dialog：入队 FIFO 串行
+    return new Promise<UiResponse>((resolve) => {
+      this.queue.push({
+        req,
+        handler,
+        resolve,
+        childPid: opts?.child?.pid,
+        settled: false,
+      });
+      void this.processNext();
+    });
+  }
+
+  /**
+   * settle 一个 item（幂等）。handler 完成 / rejectChildDialogs / rejectAll 都通过本方法，
+   * settled 标志保证只 settle 一次（防竞争）。
+   *
+   * #19 单一推进点：本方法 settle Promise + 清状态后，**唯一**调 processNext 推进队列。
+   * processNext 尾部不再调 processNext（旧代码双重推进，虽靠 processing 标志幂等，但语义混乱）。
+   * 为什么推进必须在 settleItem 而非 processNext 尾部：rejectChildDialogs 取消一个永不 settle
+   * 的 current（handler 等用户输入卡死）时，processNext 的 `await item.handler` 永不 resume，
+   * 尾部不会执行；只有 settleItem 里的 processNext 才能打破死锁，推进下一个。
+   */
+  private settleItem(item: QueueItem, resp: UiResponse): void {
+    if (item.settled) return;
+    item.settled = true;
+    item.resolve(resp);
+    // 若是正在处理的项，清空 current/processing 并推进队列（唯一推进点）。
+    // 非当前项（队列中被 reject）只 settle Promise，不影响 current/推进。
+    if (this.current === item) {
+      this.current = undefined;
+      this.processing = false;
+      void this.processNext();
+    }
+  }
+
+  /**
+   * SR-4：把指定 child 的所有 pending dialog resolve 为 {cancelled:true}。
+   *
+   * 触发场景：子进程 close（用户取消 / crash / 超时 kill）时，其 pending dialog 的 handler
+   * 可能永不 settle（等用户输入），导致 Promise 永挂 + 内存泄漏。本方法批量清理。
+   *
+   * 处理范围（TC-E4 case 2）：
+   *   - 正在处理中（current）的该 child 项：settle {cancelled:true}，解阻塞队列推进下一个
+   *     （关键：handler 可能永不 settle，必须由这里打破死锁）
+   *   - 队列中等待处理的该 child 项：settle {cancelled:true} 并移除
+   *
+   * 不影响其他 child 的 pending dialog（TC-E4 case 2 子测试 2）。
+   */
+  rejectChildDialogs(child: DialogChildRef): void {
+    // 先处理正在处理的项（可能永不 settle，必须由这里解阻塞）
+    if (this.current && this.current.childPid === child.pid) {
+      this.settleItem(this.current, { cancelled: true });
+    }
+    // 再处理队列中等待的项
+    if (this.queue.length === 0) return;
+    const remaining: QueueItem[] = [];
+    for (const item of this.queue) {
+      if (item.childPid === child.pid) {
+        // settle 该 child 的 pending Promise 为 cancelled
+        this.settleItem(item, { cancelled: true });
+      } else {
+        remaining.push(item);
+      }
+    }
+    this.queue = remaining;
+  }
+
+  /**
+   * 处理队列下一项（FIFO）。
+   *
+   * processing 标志保证串行：handler 运行期间 processing=true，新的 processNext 调用直接返回；
+   * handler settle 后由 settleItem 清 processing=false 并推进下一项（#19 单一推进点）。
+   *
+   * handler 抛错兜底（TC-E4 case 3）：catch → settle {cancelled:true} → 继续。
+   * 不能让一个失败卡死队列（processing 永远 true）。
+   */
+  private async processNext(): Promise<void> {
+    if (this.processing) return;
+    if (this.queue.length === 0) return;
+    this.processing = true;
+    const item = this.queue.shift()!;
+    this.current = item;
+    try {
+      const resp = await item.handler(item.req);
+      // handler 完成：settle（若已被 rejectChildDialogs 抢先 settle 则 noop）。
+      // settleItem 内会清 current/processing 并推进队列（#19 单一推进点）。
+      this.settleItem(item, resp);
+    } catch {
+      // handler 抛错兜底：回 cancelled，不向上抛（队列不能卡死）
+      this.settleItem(item, { cancelled: true });
+    }
+    // #19：不在尾部再调 processNext——推进统一由 settleItem 负责（避免双重推进）。
+  }
+
+  /**
+   * #10：把所有 pending dialog（queue + current）全部 settle 为 {cancelled:true}，
+   * 并清空 queue/current/processing 状态。session_shutdown 调用，保证不留永挂 Promise。
+   *
+   * 约定签名：rejectAll(): void（无参，返 void）。Group C 的 index.ts session_shutdown 依赖此契约。
+   *
+   * 幂等：依赖 settleItem 的 settled 标志——重复调用只会对已 settled 项 noop。
+   * 顺序敏感（#19 推进点在 settleItem）：必须先清空 queue 数组再 settle current，
+   * 否则 settleItem(current) 同步触发的 processNext 会从旧 queue 抢占下一项作为新 current，
+   * 避开本方法的 cancel 语义。清空后 processNext 看到空队列直接返回，新 current 不会被抢占。
+   *
+   * 单 session 假设（M-2）：见类注释。本方法清空所有 pending 不分 session——依赖 Pi 单进程
+   * 单 session 串行保证。session_shutdown handler（index.ts）调用本方法时，进程内只会有当前
+   * session 的 pending dialog。多 session 并发场景的迁移策略（rejectAllForSession）见类注释。
+   */
+  rejectAll(): void {
+    // 先捕获并清空队列——防 settleItem(current) 触发的 processNext 抢占同队列下一项
+    const items = this.queue;
+    this.queue = [];
+    // 再 settle current（processNext 此时看到空队列，不会抢占）
+    if (this.current) {
+      this.settleItem(this.current, { cancelled: true });
+    }
+    // settle 所有原队列项（Promise 必须 resolve，不能挂）
+    for (const item of items) {
+      this.settleItem(item, { cancelled: true });
+    }
+    // 状态清理（幂等：settleItem(current) 可能已清）
+    this.current = undefined;
+    this.processing = false;
+  }
+
+  /** 清空队列状态（仅在 rejectAll 之后调用）。pending Promise 必须先由 rejectAll settle。
+   *  不 settle Promise 的纯状态重置——单独调用会导致 Promise 永挂（footgun），故设为 private。
+   *  外部调用方应使用 rejectAll()（它 settle 所有 pending + 重置状态，是原子操作）。 */
+  private resetState(): void {
+    this.queue = [];
+    this.current = undefined;
+    this.processing = false;
+  }
+
+  /** 当前队列长度（测试/诊断用）。含等待处理项（不含 current）。 */
+  get size(): number {
+    return this.queue.length;
+  }
+}

package/src/execution/engine/__tests__/common/data-dir.test.ts

@@ -0,0 +1,78 @@
+// data-dir.test.ts —— dataDir 通道解析（XYZ_AGENT_DATA_DIR 权威通道 + 宿主数据根回退）。
+//
+// 三视角：①构建者——两级解析顺序正确；②使用者——独立 pi 用户（无 xyz env）拿到
+// 宿主数据根（pi 壳 dataRoot() = getAgentDir()）作根；③观察者——回退路径 warn 一次
+// （不留静默漂移），不刷屏。
+//
+// 隔离（u0-data-discovery 注入化后）：fallback 值来自 HostServices.dataRoot() 端口，
+// 每用例 resetCoreForTests + configureCore 假宿主控制端口态，避免跨用例泄漏；
+// 不再依赖 vitest alias 的 pi-coding-agent mock。
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { configureCore, resetCoreForTests } from "../../../../core/host-services.ts";
+import {
+  getEngineDataDir,
+  resetDataDirWarnForTests,
+  XYZ_DATA_DIR_ENV,
+} from "../../common/data-dir.ts";
+
+const FAKE_DATA_ROOT = "/home/user/.pi/agent";
+
+beforeEach(() => {
+  resetCoreForTests();
+  configureCore({
+    dataRoot: () => FAKE_DATA_ROOT,
+    log: () => {},
+  });
+  resetDataDirWarnForTests();
+});
+
+afterEach(() => {
+  resetCoreForTests();
+});
+
+describe("getEngineDataDir", () => {
+  it("XYZ_AGENT_DATA_DIR 存在 → 权威通道直取，不 warn", () => {
+    const warnings: string[] = [];
+    const dir = getEngineDataDir({ [XYZ_DATA_DIR_ENV]: "/data/xyz-agent" }, (m) => warnings.push(m));
+    expect(dir).toBe("/data/xyz-agent");
+    expect(warnings).toEqual([]);
+  });
+
+  it("空串/空白串视为缺失（truthy 语义与 shared getDataDir 的 || 归一对齐）", () => {
+    const warnings: string[] = [];
+    const dir = getEngineDataDir({ [XYZ_DATA_DIR_ENV]: "   " }, (m) => warnings.push(m));
+    expect(dir).not.toBe("   ");
+    expect(warnings.length).toBe(1);
+  });
+
+  it("缺 env → 回退宿主数据根（HostServices.dataRoot()，假宿主值）并 warn 一次", () => {
+    const warnings: string[] = [];
+    const warn = (m: string): void => warnings.push(m);
+    const dir1 = getEngineDataDir({}, warn);
+    expect(dir1).toBe(FAKE_DATA_ROOT);
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).toContain("XYZ_AGENT_DATA_DIR");
+
+    // warn once：第二次调用不再刷
+    const dir2 = getEngineDataDir({}, warn);
+    expect(dir2).toBe(dir1);
+    expect(warnings.length).toBe(1);
+  });
+
+  it("reset 后再次回退会重新 warn（测试隔离钩子可用）", () => {
+    const warnings: string[] = [];
+    getEngineDataDir({}, (m) => warnings.push(m));
+    resetDataDirWarnForTests();
+    getEngineDataDir({}, (m) => warnings.push(m));
+    expect(warnings.length).toBe(2);
+  });
+
+  it("未 configureCore 即消费回退段 → 抛 core_host_not_configured（端口必需语义）", () => {
+    resetCoreForTests();
+    expect(() => getEngineDataDir({}, (m) => warningsNoop(m))).toThrow(/core_host_not_configured/);
+  });
+});
+
+function warningsNoop(_msg: string): void {}

package/src/execution/engine/__tests__/common/errors.test.ts

@@ -0,0 +1,132 @@
+// errors.test.ts —— 引擎层错误 SSOT 的结构锁定。
+//
+// 三视角：①构建者——11 条 code 与设计 §3.3.3 全表一致；②使用者——错误消息
+// code 前缀格式可被字符串匹配分流；③观察者——每条错误必有非空恢复指引（可操作）。
+
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_RECOVERY_HINTS,
+  ENGINE_ERROR_CODES,
+  EngineError,
+  engineRunFailedDetail,
+  engineTimeoutDetail,
+  isEngineErrorCode,
+  nestedSpawnRejectedError,
+  promptTooLargeError,
+  schemaEmulationFailedDetail,
+  STDOUT_TAIL_ECHO_CHARS,
+} from "../../common/errors.ts";
+
+describe("ENGINE_ERROR_CODES（§3.3.3 全表）", () => {
+  it("11 条错误码与设计文档错误规格表逐条一致", () => {
+    expect([...ENGINE_ERROR_CODES]).toEqual([
+      "engine_not_found",
+      "engine_probe_failed",
+      "engine_credential_missing",
+      "nested_spawn_rejected",
+      "schema_emulation_failed",
+      "engine_timeout",
+      "engine_capability_unsupported",
+      "engine_session_not_resumable",
+      "model_not_available",
+      "prompt_too_large",
+      "engine_run_failed",
+    ]);
+  });
+
+  it("isEngineErrorCode 收窄：表内 code 为 true，表外/非字符串为 false", () => {
+    expect(isEngineErrorCode("engine_timeout")).toBe(true);
+    expect(isEngineErrorCode("engine_not_found")).toBe(true);
+    expect(isEngineErrorCode("engine_oops")).toBe(false);
+    expect(isEngineErrorCode(42)).toBe(false);
+    expect(isEngineErrorCode(undefined)).toBe(false);
+  });
+});
+
+describe("DEFAULT_RECOVERY_HINTS（恢复指引全集）", () => {
+  it("11 条 code 每条都有非空恢复指引（可操作，非安慰性文案）", () => {
+    for (const code of ENGINE_ERROR_CODES) {
+      const hint = DEFAULT_RECOVERY_HINTS[code];
+      expect(hint, `recovery hint for ${code}`).toMatch(/\S/);
+      expect(hint.length).toBeGreaterThan(20);
+    }
+  });
+
+  it("关键恢复动作在指引中（抽查三条错误规格的载体系数）", () => {
+    expect(DEFAULT_RECOVERY_HINTS.engine_timeout).toMatch(/stdout tail/i);
+    expect(DEFAULT_RECOVERY_HINTS.prompt_too_large).toMatch(/stdin/);
+    expect(DEFAULT_RECOVERY_HINTS.nested_spawn_rejected).toMatch(/inside the current task/);
+  });
+});
+
+describe("EngineError", () => {
+  it("message 为 <code>: <detail> 前缀格式（outcome.error 分流依据）", () => {
+    const err = new EngineError("engine_timeout", "chain exhausted", "retry with pi");
+    expect(err.message).toBe("engine_timeout: chain exhausted");
+    expect(err.code).toBe("engine_timeout");
+    expect(err.recovery).toBe("retry with pi");
+    expect(err.name).toBe("EngineError");
+  });
+
+  it("toStructured 投影 code/message/recovery 三字段", () => {
+    const structured = new EngineError("model_not_available", "no such model", "pick another").toStructured();
+    expect(structured).toEqual({
+      code: "model_not_available",
+      message: "model_not_available: no such model",
+      recovery: "pick another",
+    });
+  });
+});
+
+describe("具名构造器", () => {
+  it("promptTooLargeError：detail 含实际/上限字节数，recovery 含三条恢复建议", () => {
+    const err = promptTooLargeError(200_000, 131_072);
+    expect(err.code).toBe("prompt_too_large");
+    expect(err.message).toContain("200000");
+    expect(err.message).toContain("131072");
+    expect(err.recovery).toMatch(/shorten the task/i);
+    expect(err.recovery).toMatch(/file channel/);
+    expect(err.recovery).toMatch(/stdin/);
+  });
+
+  it("nestedSpawnRejectedError：说明防护规则 + 指向 task 内自行完成", () => {
+    const err = nestedSpawnRejectedError();
+    expect(err.code).toBe("nested_spawn_rejected");
+    expect(err.message).toContain("XYZ_AGENT_SUBAGENT");
+    expect(err.recovery).toMatch(/inside the current task/);
+  });
+
+  it("engineTimeoutDetail：含 stdout 尾部 + engine: pi 重跑建议", () => {
+    const detail = engineTimeoutDetail("partial stdout output");
+    expect(detail).toContain("partial stdout output");
+    expect(detail).toMatch(/SIGTERM/);
+    expect(detail).toMatch(/SIGKILL/);
+    expect(detail).toMatch(/`engine: pi`/);
+  });
+
+  it(`engineTimeoutDetail：stdout 尾部截断到 ${STDOUT_TAIL_ECHO_CHARS} 字符`, () => {
+    const longTail = "x".repeat(STDOUT_TAIL_ECHO_CHARS + 500);
+    const detail = engineTimeoutDetail(longTail);
+    // 截断后含省略号标记，总长有界（不含前后固定文案不超过 2000 + 常量开销）
+    expect(detail).toContain("...");
+    expect(detail.length).toBeLessThan(STDOUT_TAIL_ECHO_CHARS + 600);
+  });
+
+  it("engineRunFailedDetail：含 reason / exit code / 尾部 / 恢复指引", () => {
+    const detail = engineRunFailedDetail("stdout parse failed", 3, "some output");
+    expect(detail).toContain("stdout parse failed");
+    expect(detail).toContain("exit code 3");
+    expect(detail).toContain("some output");
+    expect(detail).toMatch(/probe/);
+    // exitCode=null（被信号杀死）的形态
+    expect(engineRunFailedDetail("crash", null, "t")).toContain("killed by signal");
+  });
+
+  it("schemaEmulationFailedDetail：含错误明细 + 原始输出尾部 + 重试一次语义", () => {
+    const detail = schemaEmulationFailedDetail("Schema validation failed: /a must be number", '{"a":"x"}');
+    expect(detail).toContain("Schema validation failed");
+    expect(detail).toContain('{"a":"x"}');
+    expect(detail).toMatch(/retry once/i);
+  });
+});