@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,221 @@
+// src/execution/engine/common/kill-chain.ts
+//
+// 超时杀链与 abort 两级中断（P2 公共降级层）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D1（abort 分级：引擎原生中断 →
+// 公共杀链兜底；CLI-only 引擎直接杀链，杀死后宿主合成终态）+ §3.3.3 engine_timeout /
+// engine_run_failed 行 + 附录 A「CLI 超时」行（6/6 引擎全缺 → 宿主公共层全补）。
+//
+// 为什么放公共层：没有任何引擎有 CLI 级超时（§2.2 表），杀链写一次全引擎复用（D4）。
+
+import { getLogger } from "../../../core/logger.ts";
+
+import { engineTimeoutDetail } from "./errors.ts";
+import type { AgentOutcome, AgentTaskSpec } from "../types.ts";
+import { DEFAULT_ENGINE_ID } from "../registry.ts";
+
+const logger = getLogger("subagents");
+
+// ============================================================
+// 杀链（SIGTERM → grace → SIGKILL）
+// ============================================================
+
+/**
+ * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
+ * 用结构接口而非 ChildProcess 类型：测试可注入 fake（ChildProcess 全字段构造过重），
+ * 且未来 driver host 的常驻进程句柄只要满足此形状即可复用杀链。
+ */
+export interface KillableChild {
+  /** 非 null = 进程已退出（自然退出码）。 */
+  readonly exitCode: number | null;
+  /** 非 null = 进程被信号杀死。exitCode/signalCode 任一非 null 即已退出。 */
+  readonly signalCode: string | null;
+  /** 发信号。返回 false = 进程已不存在（kill no-op）。 */
+  kill(signal?: NodeJS.Signals | number): boolean;
+  once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+}
+
+/** SIGTERM 优雅窗口默认值（ms）。实测校准点：设计 §5 待验证检查点⑤（zcode 对 SIGTERM 的响应时序）。 */
+export const DEFAULT_KILL_GRACE_MS = 5_000;
+
+/** SIGKILL 发出后的收尸等待上限（ms）——SIGKILL 后进程必死（D 状态罕见），有界等待防挂死。 */
+const SIGKILL_REAP_TIMEOUT_MS = 10_000;
+
+/**
+ * 宿主超时 abort 的 signal.reason 标记（对齐点④）。mergeTimeoutSignal（SAR 侧超时
+ * 合并链）产出；引擎 abort 合成终态时判别「超时 vs 用户 cancel」——超时统一走
+ * synthesizeTimeoutOutcome（engine_timeout），cancel 维持中止标记（engine_run_failed）。
+ */
+export const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
+
+/**
+ * 杀链：SIGTERM → 等待 graceMs → 仍存活则 SIGKILL。
+ *
+ * @returns 'terminated' = SIGTERM 优雅退出（或进程已自行退出）；'killed' = 走了 SIGKILL。
+ */
+export async function killChain(
+  child: KillableChild,
+  opts: { graceMs: number },
+): Promise<"terminated" | "killed"> {
+  // 已退出（自然/已被杀）→ 无需发信号，按优雅终止口径返回
+  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+
+  const exited = waitForExit(child);
+  safeKill(child, "SIGTERM");
+
+  const graceful = await raceTimeout(exited, opts.graceMs);
+  if (graceful === "settled") return "terminated";
+  // grace 超时后进程可能恰好在检查前一刻退出——复核退出态，避免误杀已死进程
+  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+
+  safeKill(child, "SIGKILL");
+  // 有界收尸：无论等到与否都返回 'killed'（信号已发出，返回值表达「走了 SIGKILL」）
+  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS);
+  return "killed";
+}
+
+/**
+ * 发信号兜底包裹：进程恰在退出态检查与 kill 之间自退时，ChildProcess.kill 可能抛
+ * （zsub 实测经验）——幂等吞掉并 debug 留痕，不阻断杀链语义（对已退进程信号本就是
+ * no-op）。收口自 zcode launcher 的内联实现（对齐点②：单一权威）。
+ */
+function safeKill(child: KillableChild, signal: NodeJS.Signals): void {
+  try {
+    child.kill(signal);
+  } catch (err) {
+    logger.debug(
+      `[kill-chain] ${signal} on exited process: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+// ============================================================
+// 超时终态合成
+// ============================================================
+
+/**
+ * 合成 engine_timeout 终态（宿主超时杀链走完后的 AgentOutcome）。
+ * 含 stdout 尾部 2000 字 + 「可用 engine: pi 重跑」建议（§3.3.3 第 6 行）；
+ * exitCode: null = 被信号杀死（AgentOutcome 的杀链判据，§3.3.5）。
+ */
+export function synthesizeTimeoutOutcome(
+  task: AgentTaskSpec,
+  stdoutTail: string,
+  engineId: string = DEFAULT_ENGINE_ID,
+): AgentOutcome {
+  return {
+    content: "",
+    // slug 进错误信息：单看 outcome（record 之外）也能定位是哪个任务超时
+    error: `engine_timeout: [slug=${task.slug}] ${engineTimeoutDetail(stdoutTail)}`,
+    // 被信号杀死：退出码语义为 null（§3.3.5 AgentOutcome.exitCode 注释）
+    exitCode: null,
+    engineId,
+  };
+}
+
+// ============================================================
+// abort 两级编排
+// ============================================================
+
+/** 原生中断后的宽限窗口默认值（ms）：中断指令送达 → 引擎自行收尾的等待上限。 */
+export const DEFAULT_NATIVE_INTERRUPT_GRACE_MS = 3_000;
+
+/**
+ * abort 两级编排 helper（D1 abort 分级的公共实现）：
+ * signal abort 时 ①先调引擎原生中断（tryNativeInterrupt，若有）并给宽限窗口，
+ * 窗口内未停（或无原生中断——CLI-only 引擎）则 ②走杀链兜底。
+ *
+ * 进程自然退出时以 'terminated' settle（挂在 exit 事件上，杀链对已退进程是 no-op），
+ * 调用方可安全 await；signal 永不 abort 且进程已退时也会 settle，不悬挂。
+ */
+export function abortWithFallback(
+  child: KillableChild,
+  signal: AbortSignal,
+  tryNativeInterrupt?: () => Promise<void>,
+  opts?: { graceMs?: number; nativeGraceMs?: number },
+): Promise<"terminated" | "killed"> {
+  const graceMs = opts?.graceMs ?? DEFAULT_KILL_GRACE_MS;
+  const nativeGraceMs = opts?.nativeGraceMs ?? DEFAULT_NATIVE_INTERRUPT_GRACE_MS;
+
+  return new Promise<"terminated" | "killed">((resolve) => {
+    let settled = false;
+    // 三个 handler 互相引用（finish 移除 onAbort / onAbort 触发 runChain / runChain
+    // 兜底 finish），用函数声明 + 提升消解声明环，避免 use-before-define。
+    function finish(result: "terminated" | "killed"): void {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      resolve(result);
+    }
+
+    function onExit(): void {
+      finish("terminated");
+    }
+
+    function runChain(): void {
+      void (async () => {
+        if (tryNativeInterrupt) {
+          try {
+            await tryNativeInterrupt();
+          } catch (err) {
+            // 原生中断失败（协议错/管道断）→ 直接落杀链，中断失败不阻断兜底。
+            // debug 级留诊断线索：这不是错误终态，只是该引擎优雅中断不可用
+            logger.debug(
+              `[kill-chain] native interrupt failed, falling back to kill chain: ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            );
+          }
+          const stopped = await raceTimeout(waitForExit(child), nativeGraceMs);
+          if (stopped === "settled" || settled) return; // 原生中断生效，进程已停
+        }
+        finish(await killChain(child, { graceMs }));
+      })();
+    }
+
+    function onAbort(): void {
+      runChain();
+    }
+
+    // 进程自然退出（含原生中断生效）→ 优雅终止口径。
+    // once listener 不显式移除：触发时 finish 已幂等，单 child 单 listener 无堆积。
+    child.once("exit", onExit);
+    if (child.exitCode !== null || child.signalCode !== null) {
+      finish("terminated");
+      return;
+    }
+
+    if (signal.aborted) runChain();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// ── 内部工具 ────────────────────────────────────────────────────
+
+/** 等 child 退出（已退出立即 settle；否则挂一次性 exit listener）。 */
+function waitForExit(child: KillableChild): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve();
+      return;
+    }
+    child.once("exit", () => resolve());
+  });
+}
+
+/** promise vs 超时：超时先到返回 'timeout'（promise 继续但被放弃等待）。 */
+function raceTimeout(p: Promise<void>, ms: number): Promise<"settled" | "timeout"> {
+  return new Promise<"settled" | "timeout">((resolve) => {
+    const timer = setTimeout(() => resolve("timeout"), ms);
+    p.then(
+      () => {
+        clearTimeout(timer);
+        resolve("settled");
+      },
+      () => {
+        // 被 await 的 exit promise 不会 reject；防御分支保持语义完整（超时口径胜出前出错按 settled 处理）
+        clearTimeout(timer);
+        resolve("settled");
+      },
+    );
+  });
+}

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

@@ -0,0 +1,50 @@
+// src/execution/engine/common/nesting-guard.ts
+//
+// 嵌套防护（P2 公共降级层）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D8（嵌套防护双层）：
+//   统一 XYZ_AGENT_SUBAGENT=1 标记（所有引擎 spawn 都注入，引擎 adapter 检测到即拒绝
+//   递归派发）+ 剥离各引擎原生标记（CC 的 CLAUDECODE / zsub 的 ZSW_NESTED / pi 的
+//   PI_SUBAGENT_*）防继承泄漏——子代理环境的旧标记会让孙代理误判自己已在嵌套层。
+//
+// 为什么 env 标记是唯一跨引擎可靠手段（被否方案见设计）：「隔离目录里不装扩展」
+// 依赖配置洁癖，且 opencode/CC 会吃项目级配置；env 由宿主显式控制，随 spawn 必达。
+
+import { nestedSpawnRejectedError } from "./errors.ts";
+
+/** 统一嵌套标记 env 名（D8）。值恒 '1'。 */
+export const NESTED_SPAWN_ENV = "XYZ_AGENT_SUBAGENT";
+
+/** 需剥离的引擎原生嵌套标记（精确名）。 */
+const NATIVE_NESTED_KEYS: readonly string[] = ["CLAUDECODE", "ZSW_NESTED"];
+
+/** 需剥离的引擎原生嵌套标记前缀（pi 家族）。 */
+const NATIVE_NESTED_PREFIXES: readonly string[] = ["PI_SUBAGENT_"];
+
+/** env 对象形状（NodeJS.ProcessEnv 的结构子集，测试可传普通对象）。 */
+export type SpawnEnv = Record<string, string | undefined>;
+
+/**
+ * 构造子代理 spawn env：注入 XYZ_AGENT_SUBAGENT=1 + 剥离引擎原生嵌套标记。
+ * 返回新对象，不改入参（spawn env 组装链中的多层 spread 安全）。
+ */
+export function buildNestedSpawnEnv(baseEnv: SpawnEnv): SpawnEnv {
+  const env: SpawnEnv = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (NATIVE_NESTED_KEYS.includes(key)) continue;
+    if (NATIVE_NESTED_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
+    env[key] = value;
+  }
+  env[NESTED_SPAWN_ENV] = "1";
+  return env;
+}
+
+/**
+ * 嵌套 spawn 防护断言：检测到统一标记（本进程已是 subagent）抛
+ * EngineError(nested_spawn_rejected)——文案说明防护规则、指向 task 内自行完成。
+ * 调用点：subagent 工具入口（进程创建前拒绝，D11 处置三级）。
+ */
+export function assertNotNestedSpawn(env: SpawnEnv): void {
+  if (env[NESTED_SPAWN_ENV] === "1") {
+    throw nestedSpawnRejectedError();
+  }
+}

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

@@ -0,0 +1,108 @@
+// src/execution/engine/common/persona-router.ts
+//
+// persona 路由与 argv 预算（P2 公共降级层）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D4（persona 路由按 capabilities
+// 选择 file/flag/prompt 三策略，兼作 argv 长度分流）+ D5（preparer 在 spawn 前估算
+// argv 总长度：仅 argv 投递的引擎超长时在 prepare 期报 prompt_too_large，禁止 spawn
+// 后撞 E2BIG 才失败）+ §3.3.3 prompt_too_large 行。
+//
+// 路由产出按 capabilities.personaInjection 三分（中立层只决策通道与内容，具体 flag
+// 组装归各引擎 launcher）：
+//   - 'file'  → fileCandidate（人设全文落盘为文件，argv 只带文件路径——kimi
+//               --agent-file 形态）；promptSegment 为空（人设不进 prompt）。
+//   - 'flag'  → promptSegment 为人设全文（launcher 组 --system-prompt 类 flag 直传）。
+//   - 'prompt'→ promptSegment 为带引导结构的人设段（拼进最终 prompt——zcode 形态）。
+
+import { promptTooLargeError } from "./errors.ts";
+import type { EngineCapabilities, PersonaSpec } from "../types.ts";
+
+// ============================================================
+// persona 三策略路由
+// ============================================================
+
+/** applyPersona 的返回：按通道产出人设载体。 */
+export interface PersonaRouting {
+  /** 进 prompt / flag 通道的人设文本（file 通道为空串）。 */
+  promptSegment: string;
+  /** file 通道的人设文件落盘候选（suggestedPath 相对池目录，preparer 负责落位）。 */
+  fileCandidate?: { suggestedPath: string; content: string };
+}
+
+/** file 通道的人设文件建议名（相对池目录——preparer 知道池根，router 不感知）。 */
+const PERSONA_FILE_NAME = "persona.md";
+
+/**
+ * 按 capabilities.personaInjection 路由 persona 的注入通道。
+ *
+ * router 不解析 agent .md / skill 文件内容（身份解析归宿主 resolveIdentity）——
+ * 只把 PersonaSpec 声明的内容组装成通道载体：appendSystemPrompt 是人设正文，
+ * agentRef/skillPath 以引用提示行进文本（prompt 通道）或正文头（file 通道）。
+ */
+export function applyPersona(persona: PersonaSpec, capabilities: EngineCapabilities): PersonaRouting {
+  switch (capabilities.personaInjection) {
+    case "file": {
+      const content = buildPersonaBody(persona);
+      // 全空 persona 走 file 通道无意义（空文件白占 argv 一段）——降级为无载体
+      if (content === "") return { promptSegment: "" };
+      return { promptSegment: "", fileCandidate: { suggestedPath: PERSONA_FILE_NAME, content } };
+    }
+    case "flag":
+      // flag 直传：纯正文（launcher 把它作为 --append-system-prompt 类 flag 的值）
+      return { promptSegment: buildPersonaBody(persona) };
+    case "prompt":
+      return { promptSegment: buildPromptSegment(persona) };
+  }
+}
+
+/** 人设正文：appendSystemPrompt join + agentRef/skillPath 头部引用行。 */
+function buildPersonaBody(persona: PersonaSpec): string {
+  const parts: string[] = [];
+  if (persona.agentRef !== undefined) parts.push(`# Agent: ${persona.agentRef}`);
+  if (persona.skillPath !== undefined) parts.push(`Skill context: ${persona.skillPath}`);
+  const body = persona.appendSystemPrompt?.join("\n") ?? "";
+  if (body !== "") parts.push(body);
+  return parts.join("\n");
+}
+
+/** prompt 通道的人设段（带结构头，拼进最终 prompt）。 */
+function buildPromptSegment(persona: PersonaSpec): string {
+  const body = buildPersonaBody(persona);
+  if (body === "") return "";
+  return `## Persona\n${body}`;
+}
+
+// ============================================================
+// argv 长度预算（prepare 期前置拦截）
+// ============================================================
+
+/**
+ * argv 预算默认上限（128KB）。依据：POSIX ARG_MAX 通常 ≥ 256KB（Linux 单字符串
+ * MAX_ARG_STRLEN 128KB 是更紧的硬顶）——预算取 128KB 留出参数个数与 env 余量，
+ * spawn 前拦截，绝不 spawn 后撞 E2BIG（D5）。可经 assertArgvBudget 第二参覆盖。
+ */
+export const DEFAULT_ARGV_BUDGET_BYTES =
+  // eslint-disable-next-line no-magic-numbers -- 128KB = 128 * 1024 bytes 预算换算常数
+  128 * 1024;
+
+/**
+ * 估算 argv 总字节数：各参数 UTF-8 字节数之和 + 每参数一个 NUL 分隔符。
+ * execve 按字节计算参数区，估算口径与内核一致（字符数会低估多字节文本）。
+ */
+export function estimateArgvBytes(argv: string[]): number {
+  let total = 0;
+  for (const arg of argv) {
+    total += Buffer.byteLength(arg, "utf8") + 1;
+  }
+  return total;
+}
+
+/**
+ * argv 预算断言：估算超限抛 EngineError(prompt_too_large)（恢复指引三条：缩短 task /
+ * persona 移 file 通道 / 换 stdin 引擎）。调用点在 preparer（进程创建前，D5）。
+ */
+export function assertArgvBudget(argv: string[], limitBytes: number = DEFAULT_ARGV_BUDGET_BYTES): void {
+  const actual = estimateArgvBytes(argv);
+  if (actual > limitBytes) {
+    throw promptTooLargeError(actual, limitBytes);
+  }
+}

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

@@ -0,0 +1,226 @@
+// src/execution/engine/common/pool-manager.ts
+//
+// 隔离目录池管理（P2 公共降级层）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D5（隔离目录池化保留，随 record
+// 生命周期回收，清理只做到池粒度）+ §3.3.9（目录布局 / refs 方案）。
+//
+// P2 口径（与 §3.3.9 完整设计的差异，签名所限）：引用计数是**进程内注册表**——
+// acquire/release 的任务书签名无 taskId，refs.json 文件形态（登记 taskId + ts）留给
+// 后续 wave 在 preparer/host 接线时落地（宿主是唯一写者，升级为文件形态不改变本模块
+// 的 acquire/release 语义边界）。
+//
+// 删除边界（D5 三条硬规则）：
+//   1. 只删引擎原生状态（隔离 HOME / config / db.sqlite，均可由 preparer 重建）；
+//   2. journal-*.jsonl 不随池删——生命周期跟随 record，避免「池删导致仍存 record 的
+//      历史从②级静默跌③级」；
+//   3. 删除失败置 .pool-cleanup-failed 标记文件（可观测不静默），启动期扫描该标记告警。
+
+import { mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { getLogger } from "../../../core/logger.ts";
+
+import { resolvePoolDir } from "../paths.ts";
+
+const logger = getLogger("subagents");
+
+/** 清理失败标记文件名（置于池目录内；内容为 JSON 失败清单）。 */
+export const POOL_CLEANUP_FAILED_MARKER = ".pool-cleanup-failed";
+
+/** readdir withFileTypes 的条目结构子集。 */
+interface DirEntryLike {
+  name: string;
+  isDirectory(): boolean;
+}
+
+/** 池管理的文件系统依赖面（结构接口：测试注入 fake，免 vi.mock 整个 fs 模块）。 */
+export interface PoolFsDeps {
+  mkdir(path: string, opts: { recursive: boolean }): Promise<unknown>;
+  readdir(path: string): Promise<DirEntryLike[]>;
+  rm(path: string, opts: { recursive: boolean; force: boolean }): Promise<void>;
+  rmdir(path: string): Promise<void>;
+  writeFile(path: string, data: string): Promise<void>;
+}
+
+// ============================================================
+// 进程内池注册表（引用计数）
+// ============================================================
+
+/**
+ * key = 池目录绝对路径 → 活跃引用计数。进程级单例状态，用 globalThis[Symbol.for]
+ * 持有防 jiti 双路径加载分裂（development-guide §7.5），不用模块级 const。
+ */
+const POOL_REFS_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagent-workflow.poolRefs");
+
+function getPoolRefs(): Map<string, number> {
+  // globalThis 无 symbol 索引签名，但运行时支持 symbol 键——用 Reflect 安全读写，
+  // 避免双重断言（同 model-config-service.ts 先例）。
+  let refs = Reflect.get(globalThis, POOL_REFS_SLOT_KEY) as Map<string, number> | undefined;
+  if (!refs) {
+    refs = new Map();
+    Reflect.set(globalThis, POOL_REFS_SLOT_KEY, refs);
+  }
+  return refs;
+}
+
+/** 测试隔离专用：清空进程内注册表（生产禁用——会丢失活跃引用计数）。 */
+export function resetPoolRegistryForTests(): void {
+  getPoolRefs().clear();
+}
+
+// ============================================================
+// acquire / release
+// ============================================================
+
+/**
+ * 获取池目录：mkdir -p（幂等）+ 进程内引用计数 +1，返回池目录绝对路径。
+ * 路径一律经 paths.ts resolvePoolDir 派生（双端同源，禁自拼）。
+ */
+export async function acquirePool(
+  dataDir: string,
+  engineId: string,
+  poolKey: string,
+  fs: Pick<PoolFsDeps, "mkdir"> = nodeFs,
+): Promise<string> {
+  const poolDir = resolvePoolDir(dataDir, engineId, poolKey);
+  await fs.mkdir(poolDir, { recursive: true });
+  const poolRefs = getPoolRefs();
+  poolRefs.set(poolDir, (poolRefs.get(poolDir) ?? 0) + 1);
+  return poolDir;
+}
+
+/**
+ * 释放一次池引用（record GC / 删除时调用）：计数递减；归零删整池——只删引擎原生
+ * 状态，journal-*.jsonl 保留（D5）；删除失败置标记文件并 warn，不静默不 throw
+ * （清理失败不是 record GC 的失败）。
+ */
+export async function releasePoolRef(
+  dataDir: string,
+  engineId: string,
+  poolKey: string,
+  fs: PoolFsDeps = nodeFs,
+): Promise<void> {
+  const poolDir = resolvePoolDir(dataDir, engineId, poolKey);
+  const poolRefs = getPoolRefs();
+  const current = poolRefs.get(poolDir);
+  // 无计数（进程重启后释放 / 未 acquire 的释放）→ 保守不删池：删池决策必须有本进程
+  // 内的归零证据，凭空删除可能误删其他进程正在使用的池
+  if (current === undefined || current <= 0) {
+    poolRefs.delete(poolDir);
+    logger.debug(`[pool-manager] release without live ref, skip pool deletion: ${poolDir}`);
+    return;
+  }
+  if (current > 1) {
+    poolRefs.set(poolDir, current - 1);
+    return;
+  }
+  // 归零：删引擎原生状态（journal 保留）
+  poolRefs.delete(poolDir);
+  await deletePoolNativeState(poolDir, fs);
+}
+
+/** journal 文件名判定（与 paths.ts 的 journal-<taskId>.jsonl 命名约定一致）。 */
+function isJournalFile(name: string): boolean {
+  return name.startsWith("journal-") && name.endsWith(".jsonl");
+}
+
+/** 删池内引擎原生状态：逐条目删除（跳过 journal），目录清空后移除目录本身。 */
+async function deletePoolNativeState(poolDir: string, fs: PoolFsDeps): Promise<void> {
+  const failures: string[] = [];
+  let entries: DirEntryLike[];
+  try {
+    entries = await fs.readdir(poolDir);
+  } catch {
+    // 池目录不存在（从未创建 / 已删）= 无原生状态可清，视为成功
+    return;
+  }
+  for (const entry of entries) {
+    if (isJournalFile(entry.name)) continue;
+    try {
+      await fs.rm(join(poolDir, entry.name), { recursive: true, force: true });
+    } catch (err) {
+      failures.push(`${entry.name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (failures.length > 0) {
+    await markCleanupFailed(poolDir, failures, fs);
+    return;
+  }
+  try {
+    // 目录内只剩 journal（或已空）：只剩 journal 时保留目录（journal 生命周期跟 record）
+    const remaining = await fs.readdir(poolDir);
+    if (remaining.every((e) => isJournalFile(e.name))) return;
+    await fs.rmdir(poolDir);
+  } catch (err) {
+    await markCleanupFailed(
+      poolDir,
+      [`(rmdir): ${err instanceof Error ? err.message : String(err)}`],
+      fs,
+    );
+  }
+}
+
+/** 置 .pool-cleanup-failed 标记（失败清单 JSON）+ warn——可观测不静默（D5）。 */
+async function markCleanupFailed(poolDir: string, failures: string[], fs: PoolFsDeps): Promise<void> {
+  const marker = join(poolDir, POOL_CLEANUP_FAILED_MARKER);
+  const payload = JSON.stringify({ ts: Date.now(), failures });
+  logger.warn(
+    `[pool-manager] pool cleanup failed for ${poolDir} (${failures.length} item(s)); ` +
+      `marker written to ${marker} — re-run cleanup after fixing the underlying error`,
+  );
+  try {
+    await fs.writeFile(marker, `${payload}\n`);
+  } catch (err) {
+    // 标记本身也写不进（目录只读/磁盘满）——error 级留痕是最后防线，不再上抛
+    logger.warn(
+      `[pool-manager] failed to write cleanup-failed marker ${marker}: ` +
+        `${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+// ============================================================
+// 单次性产物清理（spawnedFiles）
+// ============================================================
+
+/** cleanupSpawnedFiles 选项。 */
+export interface SpawnedFilesCleanupOpts {
+  /**
+   * resume 场景保留：true = 全部保留（no-op）。resume 续接原 session，prompt 文件
+   * 等单次性产物不再重写（§3.3.7 preparer resume 语义），清理留给 record 终局。
+   */
+  keepForResume: boolean;
+}
+
+/**
+ * 清理单次性产物（preparer 的 spawnedFiles：临时 prompt / persona 文件）。
+ * 任务结束即清理（D5）；单条失败收集 warn 不 throw（部分清理优于整体失败），ENOENT
+ * 幂等忽略。
+ */
+export async function cleanupSpawnedFiles(
+  paths: string[],
+  opts: SpawnedFilesCleanupOpts,
+  fs: Pick<PoolFsDeps, "rm"> = nodeFs,
+): Promise<void> {
+  if (opts.keepForResume) return;
+  for (const p of paths) {
+    try {
+      await fs.rm(p, { recursive: true, force: true });
+    } catch (err) {
+      logger.warn(
+        `[pool-manager] spawned file cleanup failed for ${p}: ` +
+          `${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}
+
+// ── 默认 fs 实现 ────────────────────────────────────────────────
+
+const nodeFs: PoolFsDeps = {
+  mkdir: (p, o) => mkdir(p, o),
+  readdir: (p) => readdir(p, { withFileTypes: true }) as Promise<DirEntryLike[]>,
+  rm: (p, o) => rm(p, o),
+  rmdir: (p) => rmdir(p),
+  writeFile: (p, d) => writeFile(p, d, "utf8"),
+};