@zhushanwen/subagent-core 0.4.0 → 0.6.0

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

@@ -2,31 +2,62 @@
 //
 // 隔离目录池管理（P2 公共降级层）。设计权威源：
 // docs/architecture/subagent-engine-abstraction.md D5（隔离目录池化保留，随 record
-// 生命周期回收，清理只做到池粒度）+ §3.3.9（目录布局 / refs 方案）。
+// 生命周期回收，清理只做到池粒度）+ §3.3.9（目录布局 / refs.json 方案）。
 //
-// P2 口径（与 §3.3.9 完整设计的差异，签名所限）：引用计数是**进程内注册表**——
-// acquire/release 的任务书签名无 taskId，refs.json 文件形态（登记 taskId + ts）留给
-// 后续 wave 在 preparer/host 接线时落地（宿主是唯一写者，升级为文件形态不改变本模块
-// 的 acquire/release 语义边界）。
+// refs.json 文件形态（D8 接线，dual-track-convergence）：引用计数的唯一权威源是
+// 池目录内 refs.json——进程重启后计数可恢复（文件在即计数在）。.acquire 登记
+// taskId（幂等刷新 ts），release 移除 taskId 并删对应 journal；计数归零删池内
+// 引擎原生状态。读写全同步 fs 且无 await 让出点——单线程事件循环天然不交错，
+// §3.3.9「进程内互斥」由此满足（宿主是唯一写者，无跨进程竞争）。
 //
 // 删除边界（D5 三条硬规则）：
 //   1. 只删引擎原生状态（隔离 HOME / config / db.sqlite，均可由 preparer 重建）；
-//   2. journal-*.jsonl 不随池删——生命周期跟随 record，避免「池删导致仍存 record 的
-//      历史从②级静默跌③级」；
+//   2. journal-*.jsonl 不随池删——生命周期跟随 record，release 只删「该 record 自己的」
+//      journal（record GC 时联动，避免「池删导致仍存 record 的历史从②级静默跌③级」）；
 //   3. 删除失败置 .pool-cleanup-failed 标记文件（可观测不静默），启动期扫描该标记告警。
+//
+// TTL 兜底（cleanupExpiredPoolRefs）：record 主数据的死亡（主 session 文件被 pi 侧
+// 管理）对 core 无触发点，done record 的 journal 因此没有精确回收锚——按 30 天 mtime
+// 兜底回收（journal/refs 条目），与 session-file-gc 的 session TTL 同时间尺度，是
+// D8 分域口径「journal 依赖 30 天 TTL 自然回收」的落地（workflow 域 taskId 占位无
+// record 生命周期锚，同样依赖此兜底）。
 
-import { mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
+import * as fsSync from "node:fs";
 import { join } from "node:path";
 
 import { getLogger } from "../../../core/logger.ts";
 
-import { resolvePoolDir } from "../paths.ts";
+import { resolveEnginesRoot, resolveJournalPath, resolvePoolDir, sanitizeSeg } from "../paths.ts";
+import { toErrorMessage } from "../../../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
 /** 清理失败标记文件名（置于池目录内；内容为 JSON 失败清单）。 */
 export const POOL_CLEANUP_FAILED_MARKER = ".pool-cleanup-failed";
 
+/** 池引用登记文件名（§3.3.9 目录布局）。 */
+export const REFS_JSON_FILENAME = "refs.json";
+
+/** refs.json 的 v1 schema 版本号。 */
+const REFS_VERSION = 1 as const;
+
+/** journal 文件名前缀（与 paths.ts 的 journal-<taskId>.jsonl 命名约定一致）。 */
+const JOURNAL_PREFIX = "journal-";
+/** journal 文件名后缀。 */
+const JOURNAL_SUFFIX = ".jsonl";
+
+/** refs.json 单条引用登记（§3.3.9 v1 形态）。 */
+interface PoolRefEntry {
+  taskId: string;
+  ts: number;
+}
+
+/** refs.json v1 文件形态。 */
+interface PoolRefsFile {
+  v: 1;
+  refs: Record<string, PoolRefEntry>;
+}
+
 /** readdir withFileTypes 的条目结构子集。 */
 interface DirEntryLike {
   name: string;
@@ -35,37 +66,78 @@ interface DirEntryLike {
 
 /** 池管理的文件系统依赖面（结构接口：测试注入 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>;
+  mkdirSync(path: string, opts: { recursive: boolean }): void;
+  readdirSync(path: string): DirEntryLike[];
+  statSync(path: string): { mtimeMs: number };
+  existsSync(path: string): boolean;
+  readFileSync(path: string): string;
+  writeFileSync(path: string, data: string): void;
+  renameSync(from: string, to: string): void;
+  rmSync(path: string, opts: { recursive: boolean; force: boolean }): void;
+  rmdirSync(path: string): void;
 }
 
 // ============================================================
-// 进程内池注册表（引用计数）
+// refs.json 读写（原子写 + 防御读）
 // ============================================================
 
+function emptyRefs(): PoolRefsFile {
+  return { v: REFS_VERSION, refs: {} };
+}
+
 /**
- * key = 池目录绝对路径 → 活跃引用计数。进程级单例状态，用 globalThis[Symbol.for]
- * 持有防 jiti 双路径加载分裂（development-guide §7.5），不用模块级 const。
+ * 读池引用登记。ENOENT / 损坏 JSON / 非 v1 形态 → 空登记起步（warn 留痕）——
+ * refs 丢失的后果是「池留置」（保守方向），不是误删。
  */
-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);
+function readPoolRefs(poolDir: string, fs: Pick<PoolFsDeps, "existsSync" | "readFileSync">): PoolRefsFile {
+  const refsPath = join(poolDir, REFS_JSON_FILENAME);
+  if (!fs.existsSync(refsPath)) return emptyRefs();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(refsPath));
+  } catch (err) {
+    logger.warn(
+      `[pool-manager] refs.json unparsable for ${poolDir}, starting from empty refs: ` +
+        `${toErrorMessage(err)}`,
+    );
+    return emptyRefs();
+  }
+  if (typeof parsed !== "object" || parsed === null) return emptyRefs();
+  const obj = parsed as Record<string, unknown>;
+  if (obj.v !== REFS_VERSION || typeof obj.refs !== "object" || obj.refs === null) {
+    logger.warn(`[pool-manager] refs.json unexpected shape for ${poolDir}, starting from empty refs`);
+    return emptyRefs();
+  }
+  const refs: Record<string, PoolRefEntry> = {};
+  for (const [taskId, entry] of Object.entries(obj.refs as Record<string, unknown>)) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const e = entry as Record<string, unknown>;
+    if (typeof e.taskId !== "string" || typeof e.ts !== "number") continue;
+    refs[taskId] = { taskId: e.taskId, ts: e.ts };
   }
-  return refs;
+  return { v: REFS_VERSION, refs };
 }
 
-/** 测试隔离专用：清空进程内注册表（生产禁用——会丢失活跃引用计数）。 */
-export function resetPoolRegistryForTests(): void {
-  getPoolRefs().clear();
+/** 原子写回 refs.json（tmp + rename）。失败置清理失败标记（§3.3.9），不 throw。 */
+function writePoolRefs(
+  poolDir: string,
+  file: PoolRefsFile,
+  fs: Pick<PoolFsDeps, "writeFileSync" | "renameSync">,
+): boolean {
+  const refsPath = join(poolDir, REFS_JSON_FILENAME);
+  const tmpPath = `${refsPath}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(tmpPath, `${JSON.stringify(file)}\n`);
+    fs.renameSync(tmpPath, refsPath);
+    return true;
+  } catch (err) {
+    markCleanupFailed(
+      poolDir,
+      [`(${REFS_JSON_FILENAME} write): ${toErrorMessage(err)}`],
+      fs,
+    );
+    return false;
+  }
 }
 
 // ============================================================
@@ -73,63 +145,237 @@ export function resetPoolRegistryForTests(): void {
 // ============================================================
 
 /**
- * 获取池目录：mkdir -p（幂等）+ 进程内引用计数 +1，返回池目录绝对路径。
- * 路径一律经 paths.ts resolvePoolDir 派生（双端同源，禁自拼）。
+ * 获取池目录：mkdir -p（幂等）+ refs.json 登记 taskId（幂等：已存在刷新 ts），
+ * 返回池目录绝对路径。路径一律经 paths.ts resolvePoolDir 派生（双端同源，禁自拼）。
+ * taskId = 引用计数 key（chat 域 = record.id；与 journal 文件名同源）。
  */
-export async function acquirePool(
+export function acquirePool(
   dataDir: string,
   engineId: string,
   poolKey: string,
-  fs: Pick<PoolFsDeps, "mkdir"> = nodeFs,
-): Promise<string> {
+  taskId: string,
+  fs: Pick<PoolFsDeps, "mkdirSync" | "existsSync" | "readFileSync" | "writeFileSync" | "renameSync"> = nodeFs,
+): string {
   const poolDir = resolvePoolDir(dataDir, engineId, poolKey);
-  await fs.mkdir(poolDir, { recursive: true });
-  const poolRefs = getPoolRefs();
-  poolRefs.set(poolDir, (poolRefs.get(poolDir) ?? 0) + 1);
+  fs.mkdirSync(poolDir, { recursive: true });
+  const file = readPoolRefs(poolDir, fs);
+  file.refs[taskId] = { taskId, ts: Date.now() };
+  // 写失败置标记但池目录已建——run 照常用池（标记可观测， refs 登记下次 acquire 重试）
+  writePoolRefs(poolDir, file, fs);
   return poolDir;
 }
 
 /**
- * 释放一次池引用（record GC / 删除时调用）：计数递减；归零删整池——只删引擎原生
- * 状态，journal-*.jsonl 保留（D5）；删除失败置标记文件并 warn，不静默不 throw
- * （清理失败不是 record GC 的失败）。
+ * 释放一次池引用（record GC / 删除时调用）：
+ *   1. 删该 taskId 的 journal 文件（journal 生命周期跟随 record，§3.3.9 release 语义
+ *      ——record 已死则②级数据源无保留意义；无条目也删，record 死亡是充分条件）；
+ *   2. refs.json 移除该 taskId；移除后归零 → 删池内引擎原生状态（其他 journal 保留）；
+ *   3. taskId 不在 refs（进程重启前 refs 丢失 / 未 acquire 的释放）→ 保守不删池：
+ *      删池决策必须有 refs 归零证据，凭空删除可能误删其他引用方正在使用的池。
+ * 删除失败置标记文件并 warn，不静默不 throw（清理失败不是 record GC 的失败）。
  */
-export async function releasePoolRef(
+export function releasePoolRef(
   dataDir: string,
   engineId: string,
   poolKey: string,
+  taskId: string,
   fs: PoolFsDeps = nodeFs,
-): Promise<void> {
+): 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}`);
+  removeJournalFile(dataDir, engineId, poolKey, taskId, fs);
+
+  const file = readPoolRefs(poolDir, fs);
+  if (file.refs[taskId] === undefined) {
+    logger.debug(`[pool-manager] release without live ref, skip pool deletion: ${poolDir} (${taskId})`);
     return;
   }
-  if (current > 1) {
-    poolRefs.set(poolDir, current - 1);
+  delete file.refs[taskId];
+  writePoolRefs(poolDir, file, fs);
+  if (Object.keys(file.refs).length === 0) {
+    deletePoolNativeState(poolDir, fs);
+  }
+}
+
+/** 删单个 journal 文件（force 豁免 ENOENT；失败置标记可观测）。 */
+function removeJournalFile(
+  dataDir: string,
+  engineId: string,
+  poolKey: string,
+  taskId: string,
+  fs: Pick<PoolFsDeps, "rmSync" | "writeFileSync" | "renameSync">,
+): void {
+  const journalPath = resolveJournalPath(dataDir, engineId, poolKey, taskId);
+  try {
+    fs.rmSync(journalPath, { force: true, recursive: true });
+  } catch (err) {
+    markCleanupFailed(
+      resolvePoolDir(dataDir, engineId, poolKey),
+      [`(journal ${taskId}): ${toErrorMessage(err)}`],
+      fs,
+    );
+  }
+}
+
+// ============================================================
+// TTL 兜底清理（journal / refs 条目按 30 天 mtime 回收）
+// ============================================================
+
+/**
+ * 按 TTL 回收全部引擎池的超龄引用：journal mtime 超龄 → 删 journal + 移除 refs 条目；
+ * refs 条目 ts 超龄且 journal 不存在 → 移除（孤儿条目）；无 refs 对应的超龄 journal
+ * （refs 丢失场景）→ 删；归零删池内引擎原生状态（未超龄 journal 保留——目录随之保留）。
+ * 语义 = D8 分域口径「journal 依赖 30 天 TTL 自然回收」的落地（record 主数据由 pi 侧
+ * 主 session 文件管理，其删除对 core 无触发点，done record 只能靠 mtime 兜底）。
+ */
+export function cleanupExpiredPoolRefs(
+  dataDir: string,
+  ttlMs: number,
+  fs: PoolFsDeps = nodeFs,
+  now: number = Date.now(),
+): void {
+  const enginesRoot = resolveEnginesRoot(dataDir);
+  let engines: DirEntryLike[];
+  try {
+    engines = fs.readdirSync(enginesRoot);
+  } catch {
+    return; // engines 根不存在（从未建池）= 无可清理
+  }
+  for (const engineEntry of engines) {
+    if (!engineEntry.isDirectory()) continue;
+    const engineDir = join(enginesRoot, engineEntry.name);
+    let pools: DirEntryLike[];
+    try {
+      pools = fs.readdirSync(engineDir);
+    } catch {
+      continue;
+    }
+    for (const poolEntry of pools) {
+      if (!poolEntry.isDirectory()) continue;
+      cleanupPoolByTtl(join(engineDir, poolEntry.name), ttlMs, fs, now);
+    }
+  }
+}
+
+/** 单池 TTL 清理（见 cleanupExpiredPoolRefs 语义分解）。两阶段见下方辅助函数。 */
+function cleanupPoolByTtl(poolDir: string, ttlMs: number, fs: PoolFsDeps, now: number): void {
+  const file = readPoolRefs(poolDir, fs);
+  const hadRefs = Object.keys(file.refs).length > 0;
+
+  // 1. refs 条目决策：journal 超龄（或 journal 不在 + 条目 ts 超龄）→ 移除
+  let changed = removeExpiredRefEntries(poolDir, file, ttlMs, fs, now);
+
+  // 2. 无主超龄 journal（无任何 refs 条目对应——refs 丢失/损坏重建场景）：按 mtime 删。
+  // readdir 失败 → 中止本池清理（阶段 1 的 refs 变更不落盘，下次扫描按原 refs 重算）。
+  let entries: DirEntryLike[];
+  try {
+    entries = fs.readdirSync(poolDir);
+  } catch {
     return;
   }
-  // 归零：删引擎原生状态（journal 保留）
-  poolRefs.delete(poolDir);
-  await deletePoolNativeState(poolDir, fs);
+  if (removeOrphanJournals(poolDir, file, entries, ttlMs, fs, now)) changed = true;
+
+  if (!changed) return;
+  writePoolRefs(poolDir, file, fs);
+  if (hadRefs && Object.keys(file.refs).length === 0) {
+    deletePoolNativeState(poolDir, fs);
+  }
 }
 
+/**
+ * TTL 阶段 1——refs 条目决策（直接变更 file.refs，按需删对应 journal）：
+ * journal 超龄 → 删 journal + 移除条目；journal 不在 + 条目 ts 超龄 → 移除（孤儿条目）。
+ * 返回 refs 是否有变更。
+ */
+function removeExpiredRefEntries(
+  poolDir: string,
+  file: PoolRefsFile,
+  ttlMs: number,
+  fs: PoolFsDeps,
+  now: number,
+): boolean {
+  let changed = false;
+  for (const [taskId, entry] of Object.entries(file.refs)) {
+    const journalPath = join(poolDir, `${JOURNAL_PREFIX}${sanitizeSeg(taskId)}${JOURNAL_SUFFIX}`);
+    if (fs.existsSync(journalPath)) {
+      const age = now - fs.statSync(journalPath).mtimeMs;
+      if (age > ttlMs) {
+        unlinkBestEffort(journalPath, fs);
+        delete file.refs[taskId];
+        changed = true;
+      }
+    } else if (now - entry.ts > ttlMs) {
+      delete file.refs[taskId];
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+/**
+ * TTL 阶段 2——无主超龄 journal 回收。ownedSegments 基于阶段 1 变更后的 refs
+ * （仍有 refs 对应的 journal 不动）。返回是否有删除。
+ */
+function removeOrphanJournals(
+  poolDir: string,
+  file: PoolRefsFile,
+  entries: DirEntryLike[],
+  ttlMs: number,
+  fs: PoolFsDeps,
+  now: number,
+): boolean {
+  let changed = false;
+  const ownedSegments = new Set(Object.keys(file.refs).map((taskId) => sanitizeSeg(taskId)));
+  for (const entry of entries) {
+    if (!isJournalFile(entry.name)) continue;
+    const segment = journalTaskSegment(entry.name);
+    if (segment !== undefined && ownedSegments.has(segment)) continue;
+    const journalPath = join(poolDir, entry.name);
+    try {
+      if (now - fs.statSync(journalPath).mtimeMs > ttlMs) {
+        unlinkBestEffort(journalPath, fs);
+        changed = true;
+      }
+    } catch (err) {
+      // stat 失败（并发删除等）跳过该条——TTL 扫描周期性重跑，最终一致
+      logger.debug(
+        `[pool-manager] ttl cleanup stat failed for ${journalPath}: ` +
+          `${toErrorMessage(err)}`,
+      );
+    }
+  }
+  return changed;
+}
+
+/** journal 文件名 → taskId 段（journal-<seg>.jsonl → seg；形态不符返回 undefined）。 */
+function journalTaskSegment(name: string): string | undefined {
+  if (!name.startsWith(JOURNAL_PREFIX) || !name.endsWith(JOURNAL_SUFFIX)) return undefined;
+  return name.slice(JOURNAL_PREFIX.length, name.length - JOURNAL_SUFFIX.length);
+}
+
+/** unlink 单文件（force 豁免 ENOENT；失败 best-effort 留痕）。 */
+function unlinkBestEffort(path: string, fs: Pick<PoolFsDeps, "rmSync">): void {
+  try {
+    fs.rmSync(path, { force: true, recursive: true });
+  } catch (err) {
+    logger.debug(`[pool-manager] ttl cleanup failed for ${path}: ${toErrorMessage(err)}`);
+  }
+}
+
+// ============================================================
+// 归零删池（引擎原生状态）
+// ============================================================
+
 /** journal 文件名判定（与 paths.ts 的 journal-<taskId>.jsonl 命名约定一致）。 */
 function isJournalFile(name: string): boolean {
-  return name.startsWith("journal-") && name.endsWith(".jsonl");
+  return name.startsWith(JOURNAL_PREFIX) && name.endsWith(JOURNAL_SUFFIX);
 }
 
 /** 删池内引擎原生状态：逐条目删除（跳过 journal），目录清空后移除目录本身。 */
-async function deletePoolNativeState(poolDir: string, fs: PoolFsDeps): Promise<void> {
+function deletePoolNativeState(poolDir: string, fs: PoolFsDeps): void {
   const failures: string[] = [];
   let entries: DirEntryLike[];
   try {
-    entries = await fs.readdir(poolDir);
+    entries = fs.readdirSync(poolDir);
   } catch {
     // 池目录不存在（从未创建 / 已删）= 无原生状态可清，视为成功
     return;
@@ -137,31 +383,35 @@ async function deletePoolNativeState(poolDir: string, fs: PoolFsDeps): Promise<v
   for (const entry of entries) {
     if (isJournalFile(entry.name)) continue;
     try {
-      await fs.rm(join(poolDir, entry.name), { recursive: true, force: true });
+      fs.rmSync(join(poolDir, entry.name), { recursive: true, force: true });
     } catch (err) {
-      failures.push(`${entry.name}: ${err instanceof Error ? err.message : String(err)}`);
+      failures.push(`${entry.name}: ${toErrorMessage(err)}`);
     }
   }
   if (failures.length > 0) {
-    await markCleanupFailed(poolDir, failures, fs);
+    markCleanupFailed(poolDir, failures, fs);
     return;
   }
   try {
     // 目录内只剩 journal（或已空）：只剩 journal 时保留目录（journal 生命周期跟 record）
-    const remaining = await fs.readdir(poolDir);
+    const remaining = fs.readdirSync(poolDir);
     if (remaining.every((e) => isJournalFile(e.name))) return;
-    await fs.rmdir(poolDir);
+    fs.rmdirSync(poolDir);
   } catch (err) {
-    await markCleanupFailed(
+    markCleanupFailed(
       poolDir,
-      [`(rmdir): ${err instanceof Error ? err.message : String(err)}`],
+      [`(rmdir): ${toErrorMessage(err)}`],
       fs,
     );
   }
 }
 
 /** 置 .pool-cleanup-failed 标记（失败清单 JSON）+ warn——可观测不静默（D5）。 */
-async function markCleanupFailed(poolDir: string, failures: string[], fs: PoolFsDeps): Promise<void> {
+function markCleanupFailed(
+  poolDir: string,
+  failures: string[],
+  fs: Pick<PoolFsDeps, "writeFileSync">,
+): void {
   const marker = join(poolDir, POOL_CLEANUP_FAILED_MARKER);
   const payload = JSON.stringify({ ts: Date.now(), failures });
   logger.warn(
@@ -169,12 +419,12 @@ async function markCleanupFailed(poolDir: string, failures: string[], fs: PoolFs
       `marker written to ${marker} — re-run cleanup after fixing the underlying error`,
   );
   try {
-    await fs.writeFile(marker, `${payload}\n`);
+    fs.writeFileSync(marker, `${payload}\n`);
   } catch (err) {
     // 标记本身也写不进（目录只读/磁盘满）——error 级留痕是最后防线，不再上抛
     logger.warn(
       `[pool-manager] failed to write cleanup-failed marker ${marker}: ` +
-        `${err instanceof Error ? err.message : String(err)}`,
+        `${toErrorMessage(err)}`,
     );
   }
 }
@@ -197,19 +447,19 @@ export interface SpawnedFilesCleanupOpts {
  * 任务结束即清理（D5）；单条失败收集 warn 不 throw（部分清理优于整体失败），ENOENT
  * 幂等忽略。
  */
-export async function cleanupSpawnedFiles(
+export function cleanupSpawnedFiles(
   paths: string[],
   opts: SpawnedFilesCleanupOpts,
-  fs: Pick<PoolFsDeps, "rm"> = nodeFs,
-): Promise<void> {
+  fs: Pick<PoolFsDeps, "rmSync"> = nodeFs,
+): void {
   if (opts.keepForResume) return;
   for (const p of paths) {
     try {
-      await fs.rm(p, { recursive: true, force: true });
+      fs.rmSync(p, { recursive: true, force: true });
     } catch (err) {
       logger.warn(
         `[pool-manager] spawned file cleanup failed for ${p}: ` +
-          `${err instanceof Error ? err.message : String(err)}`,
+          `${toErrorMessage(err)}`,
       );
     }
   }
@@ -218,9 +468,13 @@ export async function cleanupSpawnedFiles(
 // ── 默认 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"),
+  mkdirSync: (p, o) => fsSync.mkdirSync(p, o),
+  readdirSync: (p) => fsSync.readdirSync(p, { withFileTypes: true }),
+  statSync: (p) => fsSync.statSync(p),
+  existsSync: (p) => fsSync.existsSync(p),
+  readFileSync: (p) => fsSync.readFileSync(p, "utf8"),
+  writeFileSync: (p, d) => fsSync.writeFileSync(p, d, "utf8"),
+  renameSync: (from, to) => fsSync.renameSync(from, to),
+  rmSync: (p, o) => fsSync.rmSync(p, o),
+  rmdirSync: (p) => fsSync.rmdirSync(p),
 };