@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/execution/config.ts

@@ -20,15 +20,16 @@ import type { SubagentsGlobalConfig } from "./types.ts";
  * 但 config.json 被 .gitignore 排除且不应随 npm 包分发用户私有配置——导致
  * npm pack 后读不到文件，catch 兜底用空字段，pi install 后首次执行抛错。
  * 修复：默认值内联在代码里，不依赖任何包内文件。
+ *
+ * export 供守护测试断言 package.json startupConfig 声明与此深相等（防漂移）。
  */
-const DEFAULT_CONFIG: SubagentsGlobalConfig = {
+export const DEFAULT_CONFIG: SubagentsGlobalConfig = {
   version: 1,
   maxConcurrent: 6,
 };
 
 /** 默认 maxConcurrent（DEFAULT_CONFIG 的镜像，sanitize 用）。 */
 const DEFAULT_MAX_CONCURRENT = 6;
-
 // ============================================================
 // 路径
 // ============================================================
@@ -56,9 +57,15 @@ export function loadGlobalConfig(agentDir: string): SubagentsGlobalConfig {
   try {
     const raw = fs.readFileSync(configPath, "utf-8");
     const parsed = JSON.parse(raw) as Partial<SubagentsGlobalConfig>;
+    // P4 引擎路由（D9）：全局默认引擎 + strict 模式。非法值静默回缺省（'pi' /
+    // false）——config.json 是用户手编文件，坏值不炸启动（与 maxConcurrent 同判）
+    const defaultEngine = sanitizeDefaultEngine(parsed.defaultEngine);
+    const engineRouting = sanitizeEngineRouting(parsed.engineRouting);
     return {
       version: parsed.version ?? DEFAULT_CONFIG.version,
       maxConcurrent: sanitizeMaxConcurrent(parsed.maxConcurrent),
+      ...(defaultEngine !== undefined ? { defaultEngine } : {}),
+      ...(engineRouting !== undefined ? { engineRouting } : {}),
     };
   } catch {
     return { ...DEFAULT_CONFIG };
@@ -71,3 +78,19 @@ function sanitizeMaxConcurrent(value: unknown): number {
     ? value
     : DEFAULT_MAX_CONCURRENT;
 }
+
+/**
+ * defaultEngine 校验：非空字符串透传，其余 undefined（缺省引擎由路由层落 'pi'）。
+ * 为什么不在加载期对注册表校验 hasEngine：加载早于组合根注册（agentDir 解析在
+ * session_start），注册表此刻可能为空——校验归路由层（getEngine 抛 EngineNotFoundError）。
+ */
+function sanitizeDefaultEngine(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+/** engineRouting 校验：仅认 strict 布尔，其余键忽略（向前兼容追加）。 */
+function sanitizeEngineRouting(value: unknown): { strict: boolean } | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const strict = (value as Record<string, unknown>).strict;
+  return typeof strict === "boolean" ? { strict } : undefined;
+}

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

@@ -0,0 +1,53 @@
+// data-dir.test.ts —— dataDir 通道解析（XYZ_AGENT_DATA_DIR 权威通道 + piAgentDir 回退）。
+//
+// 三视角：①构建者——两级解析顺序正确；②使用者——独立 pi 用户（无 xyz env）拿到
+// piAgentDir 作根；③观察者——回退路径 warn 一次（不留静默漂移），不刷屏。
+//
+// 注意：getAgentDir 在 vitest 下 alias 到 mocks/pi-coding-agent.ts（返回
+// /home/user/.pi/agent）——本测试只断言两级解析顺序与 warn 行为，不测 pi SDK 内部。
+
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { getEngineDataDir, resetDataDirWarnForTests, XYZ_DATA_DIR_ENV } from "../../common/data-dir.ts";
+
+beforeEach(() => {
+  resetDataDirWarnForTests();
+});
+
+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 → 回退 piAgentDir（getAgentDir()，mock 值）并 warn 一次", () => {
+    const warnings: string[] = [];
+    const warn = (m: string): void => warnings.push(m);
+    const dir1 = getEngineDataDir({}, warn);
+    expect(dir1).toBe("/home/user/.pi/agent"); // vitest mock 的 getAgentDir
+    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);
+  });
+});

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);
+  });
+});

package/src/execution/engine/__tests__/common/event-journal.test.ts

@@ -0,0 +1,177 @@
+// event-journal.test.ts —— JournalWriter 写入-重放往返一致 + 中立格式字段断言。
+//
+// 三视角：①构建者——行格式 v/ts/taskId/engineId/seq/event 逐字段、seq 单调；②使用者
+// ——replayJournal 重放即得事件流（read 第②级），文件不存在/坏行不 throw；③观察者
+// ——写失败 warn 留痕且 close 不抛（journal 是尽力而为的②级数据源）。
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { JournalWriter, replayJournal } from "../../common/event-journal.ts";
+import type { JournalFsDeps } from "../../common/event-journal.ts";
+import type { AgentEvent } from "../../../types.ts";
+
+let tmpRoot: string | undefined;
+
+function tmpPath(name: string): string {
+  tmpRoot ??= mkdtempSync(join(tmpdir(), "engine-journal-test-"));
+  const path = join(tmpRoot, name);
+  mkdirSync(dirname(path), { recursive: true });
+  return path;
+}
+
+afterEach(() => {
+  if (tmpRoot !== undefined) {
+    rmSync(tmpRoot, { recursive: true, force: true });
+    tmpRoot = undefined;
+  }
+});
+
+const EVENTS: AgentEvent[] = [
+  { type: "text_delta", delta: "hello " },
+  { type: "text_delta", delta: "world" },
+  { type: "tool_start", toolName: "bash", args: { cmd: "ls" } },
+  { type: "tool_end", toolName: "bash", isError: false },
+  { type: "turn_end" },
+];
+
+describe("JournalWriter 写入 + replayJournal 重放", () => {
+  it("写入-重放往返一致：append N 事件 → close → replay 深等事件流", async () => {
+    const path = tmpPath("roundtrip/journal-bg-1.jsonl");
+    const writer = new JournalWriter({ path, taskId: "bg-1", engineId: "zcode" });
+    for (const ev of EVENTS) writer.append(ev);
+    await writer.close();
+
+    expect(replayJournal(path)).toEqual(EVENTS);
+  });
+
+  it("中立格式字段断言：每行 {v:1, ts, taskId, engineId, seq, event}，seq 单调递增", async () => {
+    const path = tmpPath("format/journal-bg-2.jsonl");
+    const writer = new JournalWriter({ path, taskId: "bg-2", engineId: "pi" });
+    const before = Date.now();
+    for (const ev of EVENTS) writer.append(ev);
+    await writer.close();
+
+    const lines = readFileSync(path, "utf8").trim().split("\n");
+    expect(lines.length).toBe(EVENTS.length);
+    const parsed = lines.map((l) => JSON.parse(l) as Record<string, unknown>);
+    let prevSeq = -1;
+    for (const [i, row] of parsed.entries()) {
+      expect(row.v).toBe(1);
+      expect(typeof row.ts).toBe("number");
+      expect(row.ts).toBeGreaterThanOrEqual(before);
+      expect(row.taskId).toBe("bg-2");
+      expect(row.engineId).toBe("pi");
+      expect(row.seq).toBe(i);
+      expect((row.seq as number) > prevSeq).toBe(true);
+      prevSeq = row.seq as number;
+      expect(row.event).toEqual(EVENTS[i]);
+    }
+  });
+
+  it("close 幂等（二次 close 不追加不抛错）；close 后 append 丢弃", async () => {
+    const path = tmpPath("idempotent/journal-bg-3.jsonl");
+    const writer = new JournalWriter({ path, taskId: "bg-3", engineId: "pi" });
+    writer.append({ type: "turn_end" });
+    await writer.close();
+    writer.append({ type: "error", message: "late" });
+    await writer.close();
+    expect(replayJournal(path)).toEqual([{ type: "turn_end" }]);
+  });
+
+  it("无事件任务不产生空 journal 文件（惰性创建）", async () => {
+    const path = tmpPath("empty/journal-bg-4.jsonl");
+    const writer = new JournalWriter({ path, taskId: "bg-4", engineId: "pi" });
+    await writer.close();
+    expect(existsSync(path)).toBe(false);
+    expect(replayJournal(path)).toEqual([]);
+  });
+});
+
+describe("JournalWriter 写失败（尽力而为语义）", () => {
+  function failingFs(): { fs: JournalFsDeps; warnings: string[] } {
+    const warnings: string[] = [];
+    const fs: JournalFsDeps = {
+      mkdir: async () => undefined,
+      appendFile: async () => {
+        throw new Error("disk full");
+      },
+      open: async () => {
+        throw new Error("unreachable in failed path");
+      },
+    };
+    return { fs, warnings };
+  }
+
+  it("appendFile 失败 → warn 留痕 + failed，close 不抛，后续 append 丢弃", async () => {
+    const path = tmpPath("failing/journal-bg-5.jsonl");
+    const { fs } = failingFs();
+    const warnings: string[] = [];
+    const writer = new JournalWriter(
+      { path, taskId: "bg-5", engineId: "zcode" },
+      fs,
+      (msg) => warnings.push(msg),
+    );
+    writer.append({ type: "turn_end" });
+    await writer.flush();
+    expect(writer.isFailed).toBe(true);
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).toContain("bg-5");
+    expect(warnings[0]).toContain("disk full");
+
+    writer.append({ type: "error", message: "dropped" });
+    await writer.close(); // 不抛
+    expect(existsSync(path)).toBe(false);
+  });
+});
+
+describe("replayJournal 容错", () => {
+  it("文件不存在 → []（②级不可达不算错误，降级链语义）", () => {
+    expect(replayJournal(tmpPath("missing/journal-none.jsonl"))).toEqual([]);
+  });
+
+  it("损坏行跳过（追加写末行可能截断），好行保留", () => {
+    const path = tmpPath("corrupt/journal-bg-6.jsonl");
+    const good = JSON.stringify({
+      v: 1, ts: 1, taskId: "bg-6", engineId: "pi", seq: 0, event: { type: "turn_end" },
+    });
+    writeFileSync(path, `${good}\n{"v":1,"truncated...\n`, "utf8");
+    expect(replayJournal(path)).toEqual([{ type: "turn_end" }]);
+  });
+
+  it("行序乱 → 按 seq 稳定排序返回（重放顺序权威是 seq）", () => {
+    const path = tmpPath("unordered/journal-bg-7.jsonl");
+    const line = (seq: number, delta: string): string =>
+      JSON.stringify({ v: 1, ts: seq, taskId: "bg-7", engineId: "pi", seq, event: { type: "text_delta", delta } });
+    writeFileSync(path, `${line(2, "c")}\n${line(0, "a")}\n${line(1, "b")}\n`, "utf8");
+    expect(replayJournal(path)).toEqual([
+      { type: "text_delta", delta: "a" },
+      { type: "text_delta", delta: "b" },
+      { type: "text_delta", delta: "c" },
+    ]);
+  });
+
+  it("空文件 → []", () => {
+    const path = tmpPath("blank/journal-bg-8.jsonl");
+    writeFileSync(path, "\n\n", "utf8");
+    expect(replayJournal(path)).toEqual([]);
+  });
+
+  it("结构不符的行（缺 event / v≠1）跳过", () => {
+    const path = tmpPath("shape/journal-bg-9.jsonl");
+    writeFileSync(
+      path,
+      [
+        JSON.stringify({ v: 1, ts: 1, taskId: "t", engineId: "pi", seq: 0, event: { type: "compaction" } }),
+        JSON.stringify({ v: 1, ts: 2, taskId: "t", engineId: "pi", seq: 1 }), // 无 event
+        JSON.stringify({ v: 2, ts: 3, taskId: "t", engineId: "pi", seq: 2, event: { type: "turn_end" } }), // v≠1
+        JSON.stringify({ v: 1, ts: 4, taskId: "t", engineId: "pi", seq: 3, event: "not-an-object" }),
+      ].join("\n") + "\n",
+      "utf8",
+    );
+    expect(replayJournal(path)).toEqual([{ type: "compaction" }]);
+  });
+});

package/src/execution/engine/__tests__/common/kill-chain.test.ts

@@ -0,0 +1,192 @@
+// kill-chain.test.ts —— 杀链两分支 + 超时终态合成 + abort 两级编排（fake timers）。
+//
+// 三视角：①构建者——SIGTERM 优雅 / 超时 SIGKILL 两分支的信号序列正确；②使用者——
+// abortWithFallback 对 CLI-only 与 native-interrupt 引擎都收敛不悬挂；③观察者——
+// 合成终态的 error 含 stdout 尾部与 exitCode=null（被信号杀死判据）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  abortWithFallback,
+  killChain,
+  synthesizeTimeoutOutcome,
+} from "../../common/kill-chain.ts";
+import type { KillableChild } from "../../common/kill-chain.ts";
+
+/** fake 子进程：记录 kill 信号序列，emitExit 模拟退出（置退出态 + 触发 exit listener）。 */
+function makeFakeChild(): {
+  child: KillableChild;
+  signals: string[];
+  emitExit(code: number | null, signal: NodeJS.Signals | null): void;
+} {
+  const listeners: Array<(code: number | null, signal: NodeJS.Signals | null) => void> = [];
+  const signals: string[] = [];
+  const child: KillableChild = {
+    exitCode: null,
+    signalCode: null,
+    kill(signal?: NodeJS.Signals | number): boolean {
+      signals.push(String(signal ?? "SIGTERM"));
+      return true;
+    },
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): KillableChild {
+      if (event === "exit") listeners.push(listener);
+      return child;
+    },
+  };
+  return {
+    child,
+    signals,
+    emitExit(code, signal) {
+      child.exitCode = code;
+      child.signalCode = signal;
+      for (const l of listeners.splice(0)) l(code, signal);
+    },
+  };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("killChain", () => {
+  it("SIGTERM 后进程优雅退出 → 'terminated'，无 SIGKILL", async () => {
+    const { child, signals, emitExit } = makeFakeChild();
+    const p = killChain(child, { graceMs: 5_000 });
+    emitExit(0, null); // SIGTERM 被 trap 后正常退出
+    expect(await p).toBe("terminated");
+    expect(signals).toEqual(["SIGTERM"]);
+  });
+
+  it("SIGTERM 超时未退 → SIGKILL 兜底 → 'killed'（fake timers 推进两级窗口）", async () => {
+    const { child, signals } = makeFakeChild();
+    const p = killChain(child, { graceMs: 5_000 });
+    expect(signals).toEqual(["SIGTERM"]); // kill 同步发出
+    await vi.advanceTimersByTimeAsync(5_000); // grace 窗口走完，进程仍活
+    expect(signals).toEqual(["SIGTERM", "SIGKILL"]);
+    await vi.advanceTimersByTimeAsync(10_000); // SIGKILL 收尸窗口（进程不退也返回）
+    expect(await p).toBe("killed");
+  });
+
+  it("进程已退出（调用前）→ 不发任何信号，'terminated'", async () => {
+    const { child, signals, emitExit } = makeFakeChild();
+    emitExit(1, null);
+    expect(await killChain(child, { graceMs: 5_000 })).toBe("terminated");
+    expect(signals).toEqual([]);
+  });
+
+  it("grace 窗口内恰在超时前一毫秒退出 → 复核退出态，不误发 SIGKILL", async () => {
+    const { child, signals, emitExit } = makeFakeChild();
+    const p = killChain(child, { graceMs: 5_000 });
+    emitExit(null, "SIGTERM"); // 被 SIGTERM 杀死（signalCode 形态）
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(await p).toBe("terminated");
+    expect(signals).toEqual(["SIGTERM"]);
+  });
+});
+
+describe("synthesizeTimeoutOutcome", () => {
+  it("合成 engine_timeout 终态：error 含 slug + stdout 尾部 + engine: pi 重跑建议；exitCode=null", () => {
+    const outcome = synthesizeTimeoutOutcome(
+      { task: "review files", slug: "review-files" },
+      "last stdout lines...",
+    );
+    expect(outcome.error).toContain("engine_timeout");
+    expect(outcome.error).toContain("review-files");
+    expect(outcome.error).toContain("last stdout lines...");
+    expect(outcome.error).toMatch(/`engine: pi`/);
+    expect(outcome.exitCode).toBe(null);
+    expect(outcome.content).toBe("");
+    expect(outcome.engineId).toBe("pi");
+  });
+
+  it("stdout 尾部超 2000 字截断；engineId 可指定", () => {
+    const outcome = synthesizeTimeoutOutcome(
+      { task: "t", slug: "s" },
+      "y".repeat(3_000),
+      "zcode",
+    );
+    expect(outcome.engineId).toBe("zcode");
+    expect(outcome.error).toContain("...");
+    expect(outcome.error.length).toBeLessThan(3_000);
+  });
+});
+
+describe("abortWithFallback", () => {
+  it("CLI-only 引擎（无原生中断）：abort → 直接杀链，SIGTERM 退 → 'terminated'", async () => {
+    const { child, signals, emitExit } = makeFakeChild();
+    const controller = new AbortController();
+    const p = abortWithFallback(child, controller.signal);
+    controller.abort();
+    emitExit(0, null); // SIGTERM 生效
+    expect(await p).toBe("terminated");
+    expect(signals).toEqual(["SIGTERM"]);
+  });
+
+  it("原生中断生效：abort → native interrupt → 进程退出，不走杀链（零 kill 信号）", async () => {
+    const { child, signals, emitExit } = makeFakeChild();
+    const controller = new AbortController();
+    const interrupt = vi.fn(async () => {
+      emitExit(0, null); // 引擎原生中断让进程优雅退出
+    });
+    const p = abortWithFallback(child, controller.signal, interrupt);
+    controller.abort();
+    expect(await p).toBe("terminated");
+    expect(interrupt).toHaveBeenCalledTimes(1);
+    expect(signals).toEqual([]); // 从未发信号——原生中断足量
+  });
+
+  it("原生中断无效（进程未停）→ 宽限窗口后落杀链 SIGKILL → 'killed'", async () => {
+    const { child, signals } = makeFakeChild();
+    const controller = new AbortController();
+    const interrupt = vi.fn(async () => undefined); // 中断送达但进程不退
+    const p = abortWithFallback(child, controller.signal, interrupt, {
+      nativeGraceMs: 3_000,
+      graceMs: 5_000,
+    });
+    controller.abort();
+    expect(interrupt).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(3_000); // native 宽限窗口走完
+    expect(signals).toEqual(["SIGTERM"]);
+    await vi.advanceTimersByTimeAsync(5_000); // 杀链 grace 窗口走完
+    expect(signals).toEqual(["SIGTERM", "SIGKILL"]);
+    await vi.advanceTimersByTimeAsync(10_000);
+    expect(await p).toBe("killed");
+  });
+
+  it("原生中断 throw（协议错）→ 不阻断兜底，继续杀链", async () => {
+    const { child, signals, emitExit } = makeFakeChild();
+    const controller = new AbortController();
+    const interrupt = vi.fn(async () => {
+      throw new Error("rpc broken");
+    });
+    const p = abortWithFallback(child, controller.signal, interrupt, { nativeGraceMs: 100, graceMs: 5_000 });
+    controller.abort();
+    await vi.advanceTimersByTimeAsync(100);
+    emitExit(0, null); // 后续 SIGTERM 生效
+    expect(await p).toBe("terminated");
+    expect(signals).toEqual(["SIGTERM"]);
+  });
+
+  it("进程自然退出（signal 从未 abort）→ 'terminated'，promise 不悬挂", async () => {
+    const { child, signals, emitExit } = makeFakeChild();
+    const controller = new AbortController();
+    const p = abortWithFallback(child, controller.signal);
+    emitExit(0, null);
+    expect(await p).toBe("terminated");
+    expect(signals).toEqual([]);
+  });
+
+  it("signal 已 abort 的场景（先 abort 后接线）→ 立即执行两级中断", async () => {
+    const { child, signals, emitExit } = makeFakeChild();
+    const controller = new AbortController();
+    controller.abort(); // 先 abort
+    const p = abortWithFallback(child, controller.signal);
+    emitExit(0, null);
+    expect(await p).toBe("terminated");
+    expect(signals).toEqual(["SIGTERM"]);
+  });
+});