@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

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

package/src/execution/engine/__tests__/common/pool-manager.test.ts

@@ -0,0 +1,154 @@
+// pool-manager.test.ts —— 池 acquire/release 引用计数 / 归零整池删除 / journal 保留
+// / 清理失败标记 / spawnedFiles 单次清理（D5 + §3.3.9）。
+//
+// 三视角：①构建者——计数归零才删、删除边界三硬规则逐条；②使用者——release 幂等
+// 安全（无引用 no-op）；③观察者——清理失败有 .pool-cleanup-failed 标记（可观测）。
+
+import { mkdirSync, mkdtempSync, existsSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  acquirePool,
+  cleanupSpawnedFiles,
+  POOL_CLEANUP_FAILED_MARKER,
+  releasePoolRef,
+  resetPoolRegistryForTests,
+} from "../../common/pool-manager.ts";
+import { resolvePoolDir } from "../../paths.ts";
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), "engine-pool-test-"));
+  resetPoolRegistryForTests();
+});
+
+afterEach(() => {
+  rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("acquirePool", () => {
+  it("mkdir -p 返回池目录（路径经 resolvePoolDir 派生），重复 acquire 幂等", async () => {
+    const dir1 = await acquirePool(tmpRoot, "zcode", "reviewer");
+    const dir2 = await acquirePool(tmpRoot, "zcode", "reviewer");
+    expect(dir1).toBe(resolvePoolDir(tmpRoot, "zcode", "reviewer"));
+    expect(dir1).toBe(dir2);
+    expect(existsSync(dir1)).toBe(true);
+  });
+
+  it("poolKey 经 sanitizeSeg 归一（脏字符不进文件系统路径）", async () => {
+    const dir = await acquirePool(tmpRoot, "zcode", "weird/key..name");
+    expect(dir).toBe(resolvePoolDir(tmpRoot, "zcode", "weird-key-name"));
+  });
+});
+
+describe("releasePoolRef 引用计数与整池删除", () => {
+  it("双引用：release 一次池仍在（原生状态未删），归零才整池删除", async () => {
+    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
+    await acquirePool(tmpRoot, "zcode", "reviewer");
+    await acquirePool(tmpRoot, "zcode", "reviewer");
+    mkdirSync(join(poolDir, "home"), { recursive: true });
+    writeFileSync(join(poolDir, "home", "config.json"), "{}");
+
+    await releasePoolRef(tmpRoot, "zcode", "reviewer");
+    expect(existsSync(join(poolDir, "home"))).toBe(true); // 计数 1，不删
+
+    await releasePoolRef(tmpRoot, "zcode", "reviewer"); // 归零
+    expect(existsSync(join(poolDir, "home"))).toBe(false); // 原生状态已删
+  });
+
+  it("journal-*.jsonl 不随池删（生命周期跟随 record），目录保留", async () => {
+    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
+    await acquirePool(tmpRoot, "zcode", "reviewer");
+    writeFileSync(join(poolDir, "journal-bg-1.jsonl"), "{}\n");
+    mkdirSync(join(poolDir, "home"), { recursive: true });
+
+    await releasePoolRef(tmpRoot, "zcode", "reviewer");
+    expect(existsSync(join(poolDir, "journal-bg-1.jsonl"))).toBe(true);
+    expect(existsSync(join(poolDir, "home"))).toBe(false);
+    // 只剩 journal：目录本体保留（journal 还在用）
+    expect(existsSync(poolDir)).toBe(true);
+    expect(readdirSync(poolDir)).toEqual(["journal-bg-1.jsonl"]);
+  });
+
+  it("无引用的 release（进程重启后 GC）→ 保守 no-op 不删池", async () => {
+    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
+    mkdirSync(join(poolDir, "home"), { recursive: true });
+    await releasePoolRef(tmpRoot, "zcode", "reviewer");
+    expect(existsSync(join(poolDir, "home"))).toBe(true);
+  });
+
+  it("池目录不存在时 release 归零 → 无原生状态可清，视为成功不抛", async () => {
+    await acquirePool(tmpRoot, "zcode", "ghost");
+    // 归零但目录已被外部删除
+    rmSync(resolvePoolDir(tmpRoot, "zcode", "ghost"), { recursive: true, force: true });
+    await expect(releasePoolRef(tmpRoot, "zcode", "ghost")).resolves.toBeUndefined();
+  });
+
+  it("删除失败置 .pool-cleanup-failed 标记文件（可观测不静默），不 throw", async () => {
+    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
+    await acquirePool(tmpRoot, "zcode", "reviewer");
+    mkdirSync(join(poolDir, "home"), { recursive: true });
+    writeFileSync(join(poolDir, "journal-bg-1.jsonl"), "{}\n");
+
+    // 注入失败 fs：rm 对 home 目录 reject（标记写入仍走真实 fs——失败要可观测）
+    const realFs = await import("node:fs/promises");
+    const injected = {
+      mkdir: (p: string, o: { recursive: boolean }) => realFs.mkdir(p, o),
+      readdir: (p: string) => realFs.readdir(p, { withFileTypes: true }),
+      rm: async (p: string, o: { recursive: boolean; force: boolean }) => {
+        if (p === join(poolDir, "home")) throw new Error("EACCES: permission denied");
+        return realFs.rm(p, o);
+      },
+      rmdir: (p: string) => realFs.rmdir(p),
+      writeFile: (p: string, d: string) => realFs.writeFile(p, d, "utf8"),
+    };
+
+    await expect(releasePoolRef(tmpRoot, "zcode", "reviewer", injected)).resolves.toBeUndefined();
+    const markerPath = join(poolDir, POOL_CLEANUP_FAILED_MARKER);
+    expect(existsSync(markerPath)).toBe(true);
+    // 标记内容是失败清单 JSON（含失败条目与原因）
+    const payload = JSON.parse(
+      (await import("node:fs")).readFileSync(markerPath, "utf8"),
+    ) as { failures: string[] };
+    expect(payload.failures.length).toBe(1);
+    expect(payload.failures[0]).toContain("home");
+    expect(payload.failures[0]).toContain("EACCES");
+  });
+});
+
+describe("cleanupSpawnedFiles（单次性产物）", () => {
+  it("keepForResume=true → 全部保留（resume 续接原 session，不重写产物）", async () => {
+    const f = join(tmpRoot, "prompt.txt");
+    writeFileSync(f, "x");
+    await cleanupSpawnedFiles([f], { keepForResume: true });
+    expect(existsSync(f)).toBe(true);
+  });
+
+  it("keepForResume=false → 删除；目录产物递归删", async () => {
+    const file = join(tmpRoot, "prompt.txt");
+    const dir = join(tmpRoot, "persona");
+    writeFileSync(file, "x");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "persona.md"), "y");
+    await cleanupSpawnedFiles([file, dir], { keepForResume: false });
+    expect(existsSync(file)).toBe(false);
+    expect(existsSync(dir)).toBe(false);
+  });
+
+  it("不存在的路径幂等（ENOENT 忽略）；单条失败不 throw 其余继续", async () => {
+    const good = join(tmpRoot, "good.txt");
+    writeFileSync(good, "x");
+    // 真实 fs 下很难制造 rm 失败——用「父路径为文件」制造 ENOTDIR 失败：
+    // rm(recursive, force) 对 «file/child» 形态报 ENOTDIR（force 只豁免 ENOENT）
+    const blocked = join(tmpRoot, "plain-file", "child");
+    writeFileSync(join(tmpRoot, "plain-file"), "not a dir");
+    await expect(
+      cleanupSpawnedFiles([blocked, good], { keepForResume: false }),
+    ).resolves.toBeUndefined();
+    expect(existsSync(good)).toBe(false);
+  });
+});

package/src/execution/engine/__tests__/common/schema-emulation.test.ts

@@ -0,0 +1,128 @@
+// schema-emulation.test.ts —— 三级容错提取逐级用例 + ajv 校验 + tail 载体。
+//
+// 三视角：①构建者——三级容错每级有独立触达用例（直接 parse / fence / 括号扫描）；
+// ②使用者——ok:false 时 error 简述 + tail 足以构造重试 prompt；③观察者——prompt
+// 注入段含 schema 声明与输出约定（emulated 引擎拼进 prompt 后模型可遵循）。
+
+import { describe, expect, it } from "vitest";
+
+import {
+  buildSchemaEmulationSegment,
+  extractAndValidateStructuredOutput,
+  SCHEMA_EMULATION_TAIL_CHARS,
+} from "../../common/schema-emulation.ts";
+
+const objectSchema = {
+  type: "object",
+  properties: { verdict: { type: "string" }, issues: { type: "array", items: { type: "string" } } },
+  required: ["verdict"],
+} as const;
+
+describe("buildSchemaEmulationSegment", () => {
+  it("注入段含 schema JSON 声明 + 输出格式约定（用户可见 prompt 断言）", () => {
+    const segment = buildSchemaEmulationSegment(objectSchema);
+    expect(segment).toContain("## Structured Output Requirement");
+    expect(segment).toContain(JSON.stringify(objectSchema));
+    expect(segment).toMatch(/```json/);
+    expect(segment).toMatch(/ONLY the JSON value/);
+    expect(segment).toMatch(/JSON Schema \(draft-07\)/);
+  });
+});
+
+describe("extractAndValidateStructuredOutput 三级容错", () => {
+  it("第 1 级：输出整体即合法 JSON → 直接 parse 通过 + ajv 通过", () => {
+    const text = JSON.stringify({ verdict: "pass", issues: [] });
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result).toEqual({ ok: true, parsed: { verdict: "pass", issues: [] } });
+  });
+
+  it("第 2 级：markdown code fence 包裹 → 剥 fence 后 parse 通过", () => {
+    const text = "Here is my answer:\n```json\n{\"verdict\": \"fail\", \"issues\": [\"a\", \"b\"]}\n```\n";
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result).toEqual({ ok: true, parsed: { verdict: "fail", issues: ["a", "b"] } });
+  });
+
+  it("第 2 级：无语言标注的裸 fence 也能剥", () => {
+    const text = "```\n{\"verdict\": \"pass\"}\n```";
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result).toEqual({ ok: true, parsed: { verdict: "pass" } });
+  });
+
+  it("第 3 级：前后杂文本包裹 → 首尾括号扫描提取", () => {
+    const text = "Sure! The review result is:\n\n{\"verdict\": \"fail\", \"issues\": [\"x\"]}\n\nHope this helps.";
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result).toEqual({ ok: true, parsed: { verdict: "fail", issues: ["x"] } });
+  });
+
+  it("第 3 级：array 根也支持（首个 '[' 到末个 ']'）", () => {
+    const arraySchema = { type: "array", items: { type: "string" } };
+    const result = extractAndValidateStructuredOutput("prefix [\"a\",\"b\"] suffix", arraySchema);
+    expect(result).toEqual({ ok: true, parsed: ["a", "b"] });
+  });
+
+  it("提取成功但 ajv 校验失败 → ok:false 含 ajv 错误明细与原始尾部", () => {
+    // verdict 缺失（required）+ issues 类型错
+    const text = '{"issues": "not-an-array"}';
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("Schema validation failed");
+      expect(result.error).toContain("verdict");
+      expect(result.tail).toBe(text);
+    }
+  });
+
+  it("三级提取全失败（无任何 JSON）→ ok:false 且 error 指明三级路径", () => {
+    const result = extractAndValidateStructuredOutput("no json here at all", objectSchema);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("3-stage");
+      expect(result.error).toContain("code-fence");
+      expect(result.error).toContain("bracket scan");
+    }
+  });
+
+  it("提取成功但 JSON 语法损坏（括号扫描后仍 parse 失败）→ ok:false", () => {
+    const result = extractAndValidateStructuredOutput("result: {verdict: pass}", objectSchema);
+    expect(result.ok).toBe(false);
+  });
+
+  it("ajv 编译失败（非法 schema）→ ok:false 指明 host 侧编译失败", () => {
+    // type: "foo" 是 ajv 编译期拒绝的非法类型值
+    const result = extractAndValidateStructuredOutput('{"a":1}', { type: "foo" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("compilation failed");
+    }
+  });
+});
+
+describe("tail 载体（错误展示）", () => {
+  it(`tail 截断到原始输出尾部 ${SCHEMA_EMULATION_TAIL_CHARS} 字`, () => {
+    const head = "H".repeat(300);
+    const tailPart = "T".repeat(400);
+    const text = `${head}${tailPart}`; // 700 字，尾部 500 = 末段（100H + 400T）
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.tail.length).toBe(SCHEMA_EMULATION_TAIL_CHARS);
+      expect(result.tail).toBe("H".repeat(100) + "T".repeat(400));
+    }
+  });
+
+  it("短输出 tail 为原文（不截断）", () => {
+    const text = "short broken output";
+    const result = extractAndValidateStructuredOutput(text, objectSchema);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.tail).toBe(text);
+    }
+  });
+});
+
+describe("D4 硬分流守护（静态断言）", () => {
+  it("本模块的 ajv 只在 emulated 路径——native 引擎（pi-env 链路）不 import 本模块（由全仓 grep 守护，见任务报告）", () => {
+    // 占位用例：硬分流是 import 约束，运行时无对应断言点；保留用例记录守护方式
+    expect(typeof extractAndValidateStructuredOutput).toBe("function");
+  });
+});