@zhushanwen/subagent-core 0.2.0

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

package/src/execution/engine/__tests__/common/nesting-guard.test.ts

@@ -0,0 +1,81 @@
+// nesting-guard.test.ts —— 嵌套标记注入与原生标记剥离（D8 双层防护）。
+//
+// 三视角：①构建者——三引擎原生标记（PI_SUBAGENT_* / CLAUDECODE / ZSW_NESTED）全部
+// 剥离且其余 env 保留；②使用者——子代理进程内 assertNotNestedSpawn 同步拒绝且文案
+// 可操作；③观察者——产出的 env 是新对象（不污染入参）。
+
+import { describe, expect, it } from "vitest";
+
+import {
+  assertNotNestedSpawn,
+  buildNestedSpawnEnv,
+  NESTED_SPAWN_ENV,
+} from "../../common/nesting-guard.ts";
+import { EngineError } from "../../common/errors.ts";
+
+describe("buildNestedSpawnEnv", () => {
+  it("注入统一标记 XYZ_AGENT_SUBAGENT=1", () => {
+    const env = buildNestedSpawnEnv({ PATH: "/usr/bin" });
+    expect(env[NESTED_SPAWN_ENV]).toBe("1");
+    expect(env.PATH).toBe("/usr/bin");
+  });
+
+  it("剥离 pi 原生标记 PI_SUBAGENT_*（任意后缀）", () => {
+    const env = buildNestedSpawnEnv({
+      PI_SUBAGENT_ID: "bg-1",
+      PI_SUBAGENT_CWD: "/tmp/x",
+      PI_SUBAGENT_SESSION: "abc",
+      KEEP_ME: "yes",
+    });
+    expect("PI_SUBAGENT_ID" in env).toBe(false);
+    expect("PI_SUBAGENT_CWD" in env).toBe(false);
+    expect("PI_SUBAGENT_SESSION" in env).toBe(false);
+    expect(env.KEEP_ME).toBe("yes");
+  });
+
+  it("剥离 CC 与 zsub 的原生标记（CLAUDECODE / ZSW_NESTED）", () => {
+    const env = buildNestedSpawnEnv({
+      CLAUDECODE: "1",
+      ZSW_NESTED: "1",
+      CLAUDE_UNRELATED: "keep", // 非嵌套标记的 CLAUDE_ 前缀不受影响
+    });
+    expect("CLAUDECODE" in env).toBe(false);
+    expect("ZSW_NESTED" in env).toBe(false);
+    expect(env.CLAUDE_UNRELATED).toBe("keep");
+  });
+
+  it("返回新对象，不 mutate 入参（spawn env 组装链安全）", () => {
+    const base = { PATH: "/usr/bin", PI_SUBAGENT_ID: "x" };
+    const env = buildNestedSpawnEnv(base);
+    expect(base.PI_SUBAGENT_ID).toBe("x");
+    expect("XYZ_AGENT_SUBAGENT" in base).toBe(false);
+    expect(env).not.toBe(base);
+  });
+
+  it("空白 env 也能产出仅含标记的最小 env", () => {
+    const env = buildNestedSpawnEnv({});
+    expect(env).toEqual({ [NESTED_SPAWN_ENV]: "1" });
+  });
+});
+
+describe("assertNotNestedSpawn", () => {
+  it("检测到统一标记（本进程已是 subagent）→ 抛 nested_spawn_rejected", () => {
+    expect(() => assertNotNestedSpawn({ [NESTED_SPAWN_ENV]: "1" })).toThrowError(EngineError);
+    try {
+      assertNotNestedSpawn({ [NESTED_SPAWN_ENV]: "1" });
+      expect.unreachable("should throw");
+    } catch (err) {
+      const e = err as EngineError;
+      expect(e.code).toBe("nested_spawn_rejected");
+      // 文案说明防护规则（标记名）+ 指向 task 内自行完成
+      expect(e.message).toContain("XYZ_AGENT_SUBAGENT");
+      expect(e.recovery).toMatch(/inside the current task/);
+    }
+  });
+
+  it("无标记 / 值非 '1' → 不抛（顶层进程正常派发）", () => {
+    expect(() => assertNotNestedSpawn({})).not.toThrow();
+    expect(() => assertNotNestedSpawn({ [NESTED_SPAWN_ENV]: "0" })).not.toThrow();
+    expect(() => assertNotNestedSpawn({ [NESTED_SPAWN_ENV]: undefined })).not.toThrow();
+  });
+});

package/src/execution/engine/__tests__/common/persona-router.test.ts

@@ -0,0 +1,123 @@
+// persona-router.test.ts —— persona 三策略路由 + argv 预算前置拦截。
+//
+// 三视角：①构建者——三通道产出物各归其位；②使用者——argv 超限时报
+// prompt_too_large 且文案含三条恢复建议；③观察者——估算口径含多字节字符与分隔符。
+
+import { describe, expect, it } from "vitest";
+
+import {
+  applyPersona,
+  assertArgvBudget,
+  DEFAULT_ARGV_BUDGET_BYTES,
+  estimateArgvBytes,
+} from "../../common/persona-router.ts";
+import { EngineError } from "../../common/errors.ts";
+import type { EngineCapabilities } from "../../types.ts";
+
+const CAPS_FILE: EngineCapabilities = {
+  schemaEnforcement: "emulated", steer: "unsupported", conversation: "unsupported",
+  personaInjection: "file", eventGranularity: "coarse", sandbox: "none",
+  sessionRead: "partial", resume: "cold", interrupt: "kill-only", permissionMode: "native",
+};
+const CAPS_FLAG: EngineCapabilities = { ...CAPS_FILE, personaInjection: "flag" };
+const CAPS_PROMPT: EngineCapabilities = { ...CAPS_FILE, personaInjection: "prompt" };
+
+const persona = {
+  agentRef: "reviewer",
+  skillPath: "/skills/review.md",
+  appendSystemPrompt: ["You are a careful code reviewer.", "Be terse."],
+};
+
+describe("applyPersona 三策略路由", () => {
+  it("file 策略：人设全文进 fileCandidate（路径相对池目录），promptSegment 为空", () => {
+    const routing = applyPersona(persona, CAPS_FILE);
+    expect(routing.promptSegment).toBe("");
+    expect(routing.fileCandidate).toBeDefined();
+    expect(routing.fileCandidate?.suggestedPath).toBe("persona.md");
+    expect(routing.fileCandidate?.content).toContain("# Agent: reviewer");
+    expect(routing.fileCandidate?.content).toContain("/skills/review.md");
+    expect(routing.fileCandidate?.content).toContain("You are a careful code reviewer.");
+  });
+
+  it("flag 策略：promptSegment 为纯人设正文（launcher 组 flag 直传），无 fileCandidate", () => {
+    const routing = applyPersona(persona, CAPS_FLAG);
+    expect(routing.fileCandidate).toBeUndefined();
+    expect(routing.promptSegment).toContain("You are a careful code reviewer.");
+    expect(routing.promptSegment).toContain("Be terse.");
+    // 纯正文：不带 prompt 通道的结构头
+    expect(routing.promptSegment).not.toContain("## Persona");
+  });
+
+  it("prompt 策略：promptSegment 为带结构头的人设段（拼进最终 prompt）", () => {
+    const routing = applyPersona(persona, CAPS_PROMPT);
+    expect(routing.promptSegment.startsWith("## Persona")).toBe(true);
+    expect(routing.promptSegment).toContain("# Agent: reviewer");
+    expect(routing.promptSegment).toContain("You are a careful code reviewer.");
+  });
+
+  it("空 persona（全字段缺省）：三通道都产出空载体（白占 argv/prompt 无意义）", () => {
+    expect(applyPersona({}, CAPS_FILE)).toEqual({ promptSegment: "" });
+    expect(applyPersona({}, CAPS_FLAG)).toEqual({ promptSegment: "" });
+    expect(applyPersona({}, CAPS_PROMPT)).toEqual({ promptSegment: "" });
+  });
+
+  it("仅 appendSystemPrompt：file 通道照常落文件（agentRef/skillPath 头部行缺省）", () => {
+    const routing = applyPersona({ appendSystemPrompt: ["only body"] }, CAPS_FILE);
+    expect(routing.fileCandidate?.content).toBe("only body");
+  });
+});
+
+describe("estimateArgvBytes", () => {
+  it("ASCII：字节数之和 + 每参数 1 个 NUL 分隔符", () => {
+    // "ab"(2) + "cde"(3) + 2 个 NUL = 7
+    expect(estimateArgvBytes(["ab", "cde"])).toBe(7);
+    expect(estimateArgvBytes([])).toBe(0);
+  });
+
+  it("多字节字符按 UTF-8 计（中文 3 字节/字）——字符数口径会低估", () => {
+    // "中"=3 字节 + 1 NUL = 4
+    expect(estimateArgvBytes(["中"])).toBe(4);
+    // "a中b" = 1+3+1 = 5 字节 + 1 = 6
+    expect(estimateArgvBytes(["a中b"])).toBe(6);
+  });
+});
+
+describe("assertArgvBudget", () => {
+  it(`默认上限 ${DEFAULT_ARGV_BUDGET_BYTES} 字节（128KB）且预算内通过`, () => {
+    expect(DEFAULT_ARGV_BUDGET_BYTES).toBe(128 * 1024);
+    expect(() => assertArgvBudget(["--prompt", "short"])).not.toThrow();
+  });
+
+  it("超限抛 prompt_too_large：detail 含实际/上限字节数", () => {
+    const bigArg = "x".repeat(1024);
+    const argv = [bigArg, bigArg]; // 2KB，limit 1KB
+    let caught: EngineError | undefined;
+    try {
+      assertArgvBudget(argv, 1024);
+      expect.unreachable("should throw");
+    } catch (err) {
+      caught = err as EngineError;
+    }
+    expect(caught).toBeInstanceOf(EngineError);
+    expect(caught?.code).toBe("prompt_too_large");
+    expect(caught?.message).toContain("2050"); // 1024*2 + 2 NUL
+    expect(caught?.message).toContain("1024");
+  });
+
+  it("错误恢复指引含三条建议：缩短 task / persona 移 file 通道 / 换 stdin 引擎", () => {
+    try {
+      assertArgvBudget(["y".repeat(3000)], 1024);
+      expect.unreachable("should throw");
+    } catch (err) {
+      const e = err as EngineError;
+      expect(e.recovery).toMatch(/shorten the task/i);
+      expect(e.recovery).toMatch(/file channel/);
+      expect(e.recovery).toMatch(/stdin/);
+    }
+  });
+
+  it("limit 可配（调用方收紧到引擎实测限额）", () => {
+    expect(() => assertArgvBudget(["a".repeat(100)], 50)).toThrowError(/prompt_too_large/);
+    expect(() => assertArgvBudget(["a".repeat(100)], 101)).not.toThrow();
+  });
+});