@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

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

@@ -1,132 +0,0 @@
-// 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

@@ -1,177 +0,0 @@
-// 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

@@ -1,192 +0,0 @@
-// 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

@@ -1,81 +0,0 @@
-// 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();
-  });
-});