ppxans-harness 2.4.0 → 3.2.0

package/src/utils/json-state.js

@@ -0,0 +1,33 @@
+// src/utils/json-state.js - agent 作用域 JSON 状态文件 (唯一实现, 2026-09-18 重构收敛)
+// 原先 ans/{eviction,proactive,reward}.js 各写一份逐字节相同的 loadState/saveState
+// (读: 缺失/损坏 → {}; 写: ensureDir + 同步写, 失败静默降级不打断主流程)。
+// 统一后改语义只动这一处; 各模块仍导出自己的 loadState/saveState 保持对外接口不变。
+import path from "node:path";
+import { readJson, writeJson } from "./store.js";
+
+// 读: 缺失/损坏 → {} (对象语义); 复用 store.readJson (含去 BOM)
+// statePath: 由调用方给出完整路径 (通常 agent.dataDir/memory/<name>.json)
+export function loadStateFile(file) {
+  const s = readJson(file, null);
+  return (s && typeof s === "object") ? s : {};
+}
+
+// 写: 原子落盘; 失败静默降级不打断主流程
+export function saveStateFile(file, state) {
+  try {
+    writeJson(file, state);
+  } catch { /* 状态落盘失败不影响主流程 */ }
+}
+
+// agent 作用域便捷封装: name 为 memory/<name>.json 的文件名
+export function agentStatePath(agent, name) {
+  return path.join(agent.dataDir, "memory", `${name}.json`);
+}
+
+export function loadAgentState(agent, name) {
+  return loadStateFile(agentStatePath(agent, name));
+}
+
+export function saveAgentState(agent, name, state) {
+  return saveStateFile(agentStatePath(agent, name), state);
+}

package/src/utils/logger.js

@@ -1,17 +1,17 @@
-// src/utils/logger.js - 分级日志
-const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
-
-let minLevel = LEVELS.info;
-
-export function setLevel(lv) {
-  if (lv in LEVELS) minLevel = LEVELS[lv];
-}
-
-function ts() {
-  return new Date().toISOString();
-}
-
-export function debug(...a) { if (minLevel <= LEVELS.debug) console.log(`[${ts()}] [debug]`, ...a); }
-export function info(...a)  { if (minLevel <= LEVELS.info)  console.log(`[${ts()}] [info]`, ...a); }
-export function warn(...a)  { if (minLevel <= LEVELS.warn)  console.log(`[${ts()}] [warn]`, ...a); }
-export function error(...a) { if (minLevel <= LEVELS.error) console.error(`[${ts()}] [error]`, ...a); }
+// src/utils/logger.js - 分级日志
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+
+let minLevel = LEVELS.info;
+
+export function setLevel(lv) {
+  if (lv in LEVELS) minLevel = LEVELS[lv];
+}
+
+function ts() {
+  return new Date().toISOString();
+}
+
+export function debug(...a) { if (minLevel <= LEVELS.debug) console.log(`[${ts()}] [debug]`, ...a); }
+export function info(...a)  { if (minLevel <= LEVELS.info)  console.log(`[${ts()}] [info]`, ...a); }
+export function warn(...a)  { if (minLevel <= LEVELS.warn)  console.log(`[${ts()}] [warn]`, ...a); }
+export function error(...a) { if (minLevel <= LEVELS.error) console.error(`[${ts()}] [error]`, ...a); }

package/src/utils/ndjson.js

@@ -0,0 +1,25 @@
+// src/utils/ndjson.js - 尾随 NDJSON (换行分隔 JSON) 流工具 (唯一实现, 2026-09-18 重构收敛)
+// 背景: orchestrator/legion.js 读子进程 stdout 与 orchestrator/agent-worker.js 读 stdin,
+// 各写一份逐字相同的「累积缓冲 → 按 \n 切行 → 跳过空行」循环; 写侧同样散落 6 处
+// `stream.write(JSON.stringify(obj) + "\n")`。缓冲边界是最易出错的点, 收敛为单一实现。
+
+// 创建行读取器: 把 data 分片喂进去, 每切出完整一行就回调 onLine(已 trim 的行内容)。
+// 残行留在内部缓冲等下一片。返回的函数直接挂到 stream 的 "data" 事件上。
+export function createLineReader(onLine) {
+  let buf = "";
+  return (chunk) => {
+    buf += chunk;
+    let idx;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (!line) continue;
+      onLine(line);
+    }
+  };
+}
+
+// 把对象序列化成一行 NDJSON 并写入流 (进程间消息收发的统一写法)
+export function writeLine(stream, obj) {
+  stream.write(JSON.stringify(obj) + "\n");
+}

package/src/utils/pii.js

@@ -1,42 +1,42 @@
-// src/utils/pii.js - PII / 凭证检测与脱敏 (架构参考 openhanako pii-guard)
-const HARD_PATTERNS = [
-  { name: "api_key", regex: /\b(sk-[a-zA-Z0-9]{20,}|AKIA[A-Z0-9]{16}|gsk_[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]{20,}|xoxb-[a-zA-Z0-9-]+)\b/g },
-  // v1.0.8: 放宽 inline_secret 值域 (含 :/# 等) + 8 位起, 短密钥不漏检 (原 16+ 位且不含 :#)
-  // P0 (2026-09-15): key 后允许可选闭合引号 —— 原版只匹配 key=value / key: value,
-  //   JSON 序列化形式 "key":"value" (key 后先有闭合引号) 完全漏检, 已修。
-  { name: "inline_secret", regex: /\b(api[_-]?key|secret[_-]?key|access[_-]?token|auth[_-]?token|password|bearer)["']?\s*[:=]\s*["']?([a-zA-Z0-9_/+=\-.:#]{8,})["']?/gi },
-  { name: "private_key", regex: /-----BEGIN\s+(RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/g },
-  { name: "credit_card", regex: /\b(?:\d{4}[- ]?){3}\d{4}\b/g },
-  { name: "id_card", regex: /\b\d{6}(?:19|20)\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])\d{3}[\dXx]\b/g },
-  { name: "ssn", regex: /\b\d{3}-\d{2}-\d{4}\b/g },
-  // v1.0.8: 邮箱 + 中国大陆手机号 (11 位, 1[3-9] 开头)
-  { name: "email", regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
-  { name: "phone", regex: /\b1[3-9]\d{9}\b/g },
-  // v1.6.0-dev: URL query 里的敏感参数值 (token/key/secret/sign 等) — 最常见的凭证泄漏渠道, 此前未覆盖
-  // 仅匹配参数名白名单, 避免误伤合法 URL 参数; 保留参数名, 只替换值
-  { name: "url_secret", regex: /([?&](?:token|key|secret|api[_-]?key|access[_-]?token|auth|sign|sig|password)=)[^&#\s"']*/gi, redact: (m, pre) => pre + "[REDACTED]" },
-];
-
-export function scrubPII(text) {
-  if (!text) return { cleaned: text, detected: [] };
-  const detected = [];
-  let cleaned = text;
-  for (const { name, regex, redact } of HARD_PATTERNS) {
-    regex.lastIndex = 0;
-    if (regex.test(cleaned)) {
-      detected.push(name);
-      regex.lastIndex = 0;
-      cleaned = cleaned.replace(regex, redact ? redact : "[REDACTED]");
-    }
-  }
-  return { cleaned, detected };
-}
-
-export function hasPII(text) {
-  if (!text) return false;
-  for (const { regex } of HARD_PATTERNS) {
-    regex.lastIndex = 0;
-    if (regex.test(text)) return true;
-  }
-  return false;
-}
+// src/utils/pii.js - PII / 凭证检测与脱敏 (架构参考 openhanako pii-guard)
+const HARD_PATTERNS = [
+  { name: "api_key", regex: /\b(sk-[a-zA-Z0-9]{20,}|AKIA[A-Z0-9]{16}|gsk_[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]{20,}|xoxb-[a-zA-Z0-9-]+)\b/g },
+  // v1.0.8: 放宽 inline_secret 值域 (含 :/# 等) + 8 位起, 短密钥不漏检 (原 16+ 位且不含 :#)
+  // P0 (2026-09-15): key 后允许可选闭合引号 —— 原版只匹配 key=value / key: value,
+  //   JSON 序列化形式 "key":"value" (key 后先有闭合引号) 完全漏检, 已修。
+  { name: "inline_secret", regex: /\b(api[_-]?key|secret[_-]?key|access[_-]?token|auth[_-]?token|password|bearer)["']?\s*[:=]\s*["']?([a-zA-Z0-9_/+=\-.:#]{8,})["']?/gi },
+  { name: "private_key", regex: /-----BEGIN\s+(RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/g },
+  { name: "credit_card", regex: /\b(?:\d{4}[- ]?){3}\d{4}\b/g },
+  { name: "id_card", regex: /\b\d{6}(?:19|20)\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])\d{3}[\dXx]\b/g },
+  { name: "ssn", regex: /\b\d{3}-\d{2}-\d{4}\b/g },
+  // v1.0.8: 邮箱 + 中国大陆手机号 (11 位, 1[3-9] 开头)
+  { name: "email", regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+  { name: "phone", regex: /\b1[3-9]\d{9}\b/g },
+  // v1.6.0-dev: URL query 里的敏感参数值 (token/key/secret/sign 等) — 最常见的凭证泄漏渠道, 此前未覆盖
+  // 仅匹配参数名白名单, 避免误伤合法 URL 参数; 保留参数名, 只替换值
+  { name: "url_secret", regex: /([?&](?:token|key|secret|api[_-]?key|access[_-]?token|auth|sign|sig|password)=)[^&#\s"']*/gi, redact: (m, pre) => pre + "[REDACTED]" },
+];
+
+export function scrubPII(text) {
+  if (!text) return { cleaned: text, detected: [] };
+  const detected = [];
+  let cleaned = text;
+  for (const { name, regex, redact } of HARD_PATTERNS) {
+    regex.lastIndex = 0;
+    if (regex.test(cleaned)) {
+      detected.push(name);
+      regex.lastIndex = 0;
+      cleaned = cleaned.replace(regex, redact ? redact : "[REDACTED]");
+    }
+  }
+  return { cleaned, detected };
+}
+
+export function hasPII(text) {
+  if (!text) return false;
+  for (const { regex } of HARD_PATTERNS) {
+    regex.lastIndex = 0;
+    if (regex.test(text)) return true;
+  }
+  return false;
+}

package/src/utils/rate-limit.js

@@ -0,0 +1,50 @@
+// src/utils/rate-limit.js - 每来源令牌桶限流 (唯一实现, 2026-09-18 重构收敛)
+// 原先 channels/http.js 与 aml-server.js 各写一份同逻辑令牌桶 (后者注释自述"对齐 http.js"),
+// 且 aml 那份缺过期回收 —— 桶表只增不减, 长期运行 + 多变源地址会持续吃内存。
+// 统一后两处共享同一实现与回收策略。
+//
+// 用法:
+//   const limiter = new TokenBucket({ perMin: 60 });
+//   if (!limiter.take(ip)) { /* 回 429 */ }
+export const RATE_WINDOW_MS = 60_000;
+// 桶数超过此值时顺带回收过期桶 (摊还 O(1), 不引入定时器)
+const DEFAULT_SWEEP_AT = 512;
+
+export class TokenBucket {
+  constructor({ perMin = 60, windowMs = RATE_WINDOW_MS, sweepAt = DEFAULT_SWEEP_AT } = {}) {
+    this.perMin = perMin;
+    this.windowMs = windowMs;
+    this.sweepAt = sweepAt;
+    // 公开 Map: 调用方可直接观测/清理 (http 通道的测试据此注入过期桶)
+    this.buckets = new Map(); // key -> { tokens, last }
+  }
+
+  // 取一个令牌。返回 false 表示本窗口已耗尽 (调用方负责写 429)。
+  take(key) {
+    const now = Date.now();
+    let b = this.buckets.get(key);
+    if (!b) {
+      this.sweep(now);
+      b = { tokens: this.perMin, last: now };
+      this.buckets.set(key, b);
+    }
+    // 按窗口整数倍补充令牌 (上限 perMin)
+    const refill = Math.floor((now - b.last) / this.windowMs);
+    if (refill > 0) {
+      b.tokens = Math.min(this.perMin, b.tokens + refill * this.perMin);
+      b.last = now;
+    }
+    if (b.tokens <= 0) return false;
+    b.tokens -= 1;
+    return true;
+  }
+
+  // 回收连续两个窗口未活动的桶 (摊还成本, 防内存无界增长)
+  sweep(now = Date.now()) {
+    if (this.buckets.size <= this.sweepAt) return;
+    const stale = now - this.windowMs * 2;
+    for (const [k, b] of this.buckets) {
+      if (b.last < stale) this.buckets.delete(k);
+    }
+  }
+}

package/src/utils/schema.js

@@ -0,0 +1,80 @@
+// src/utils/schema.js - 数据文件 schema 版本 + 迁移钩子
+// 目标: 记忆数据文件 (facts.json / scenes.json) 保持纯数组格式不变 (现有读取者 healer/测试全部无感),
+//       版本号写在旁挂的 <file>.schema 小文件中; 数据结构升级时注册迁移函数, 启动自动迁移。
+// 设计:
+//   - 无 .schema 文件的历史数据一律视为 v1 (基线, 纯数组格式)
+//   - registerMigration(name, from, to, fn) 注册迁移链, 不允许跳级, 不允许覆盖
+//   - migrateData() 读当前版本 -> 沿迁移链推进 -> 原子写回数据 + 更新 .schema 文件
+//   - 崩溃安全: 迁移在原子写回后版本才推进, 中断重跑幂等
+import path from "node:path";
+import { atomicWrite, ensureDir, readJson } from "./store.js";
+
+// 基线版本: 无 .schema 文件 (历史纯数组格式) 一律视为 v1
+export const SCHEMA_BASE_VERSION = 1;
+
+// name -> Map<fromVersion, { to, fn }>
+const MIGRATIONS = new Map();
+
+// 注册迁移: from 版本 -> to 版本 (to 必须 > from)
+// fn(data, { from, to }) => 迁移后的 data
+export function registerMigration(name, from, to, fn) {
+  if (!Number.isInteger(from) || !Number.isInteger(to) || to <= from) {
+    throw new Error(`非法迁移版本: ${name} ${from}->${to}`);
+  }
+  if (typeof fn !== "function") throw new Error(`迁移函数缺失: ${name} v${from}`);
+  let chain = MIGRATIONS.get(name);
+  if (!chain) { chain = new Map(); MIGRATIONS.set(name, chain); }
+  if (chain.has(from)) throw new Error(`迁移冲突: ${name} v${from} 已注册`);
+  chain.set(from, { to, fn });
+  return { name, from, to };
+}
+
+function schemaFileOf(file) {
+  return file + ".schema";
+}
+
+// 读当前数据文件版本 (无 .schema 文件视为基线 v1)
+export function readSchema(file) {
+  const meta = readJson(schemaFileOf(file), null);
+  if (!meta || !Number.isInteger(meta.version)) return SCHEMA_BASE_VERSION;
+  return meta.version;
+}
+
+// 写版本 (原子)
+export function writeSchema(file, name, version) {
+  const p = schemaFileOf(file);
+  ensureDir(path.dirname(p));
+  atomicWrite(p, JSON.stringify({ name, version, updatedAt: new Date().toISOString() }, null, 2));
+}
+
+// 把数据文件迁移到 currentVersion: 沿注册链逐级推进, 无迁移函数则安全跳过 (版本直接标记到目标, 数据不动)。
+// 返回 { from(初始版本), to(最终版本), applied, data } —— applied 为实际执行的迁移步骤列表
+export function migrateData({ file, name, data, currentVersion, logger = null }) {
+  const chain = MIGRATIONS.get(name) || new Map();
+  const start = readSchema(file);
+  let from = start;
+  let d = data;
+  const applied = [];
+  let guard = 0;
+  while (from < currentVersion) {
+    if (++guard > 20) throw new Error(`迁移链疑似死循环: ${name} v${from}`);
+    const step = chain.get(from);
+    if (!step) {
+      // 没有迁移函数但仍落后于目标: 记录说明并直接标记版本 (数据保持原样)
+      if (logger) logger(`schema ${name}: v${from} -> v${currentVersion} 无迁移函数, 数据保持原样`);
+      applied.push({ from, to: currentVersion, note: "no-migration" });
+      from = currentVersion;
+      break;
+    }
+    if (step.to > currentVersion) throw new Error(`迁移越界: ${name} v${from}->v${step.to} 超过目标 v${currentVersion}`);
+    d = step.fn(d, { from, to: step.to });
+    applied.push({ from, to: step.to });
+    from = step.to;
+  }
+  if (applied.length) {
+    // 迁移产生新数据: 原子写回 (rename 覆盖, 崩溃安全), 版本随 .schema 文件推进
+    atomicWrite(file, JSON.stringify(d, null, 2));
+  }
+  writeSchema(file, name, from);
+  return { from: start, to: from, applied, data: d };
+}

package/src/utils/similarity.js

@@ -0,0 +1,43 @@
+// src/utils/similarity.js - 中文文本相似度的公共基元 (唯一实现, 2026-09-18 重构收敛)
+// 背景: "字符级 bigram + 交集" 的相似度思路在 fact-store / experience / eviction 三处各写一份,
+//       集合运算 (交集大小 / Jaccard / overlap) 完全重复。这里只收敛「集合级运算 + 字符 bigram 分词」,
+//       各模块保留自己的分词策略与阈值 (fact-store 用 scope 感知的 _bigramSet, 语义不同, 不强行合并)。
+// 零依赖, 纯函数。
+
+// 字符级 bigram: 去空白 + 按码点取相邻两字符 (对中文简繁/词序变化有容错)
+// 与 experience/_bigrams、eviction/_bigramSet 原实现一致 (Array.from 按码点切分, astral 字符不劈半)
+export function charBigrams(s) {
+  const chars = Array.from(String(s ?? "").replace(/\s+/g, ""));
+  const out = new Set();
+  for (let i = 0; i < chars.length - 1; i++) out.add(chars[i] + chars[i + 1]);
+  return out;
+}
+
+// 集合交集大小
+export function intersectSize(A, B) {
+  let inter = 0;
+  for (const x of A) if (B.has(x)) inter++;
+  return inter;
+}
+
+// Jaccard 系数: 交集 / 并集 (0~1)
+export function setJaccard(A, B) {
+  if (!A.size || !B.size) return 0;
+  const union = A.size + B.size - intersectSize(A, B);
+  return union ? intersectSize(A, B) / union : 0;
+}
+
+// overlap 系数: 交集 / 较短集合 (0~1) —— 对"共享核心词但词序/措辞大变"比 Jaccard 更敏感
+export function setOverlap(A, B) {
+  if (!A.size || !B.size) return 0;
+  return intersectSize(A, B) / Math.min(A.size, B.size);
+}
+
+// 文本级便捷封装 (字符 bigram)
+export function overlapCoefficient(a, b) {
+  return setOverlap(charBigrams(a), charBigrams(b));
+}
+
+export function jaccardCoefficient(a, b) {
+  return setJaccard(charBigrams(a), charBigrams(b));
+}

package/src/utils/store.js

@@ -1,108 +1,170 @@
-// src/utils/store.js - 零依赖文件存储 (JSON + 原子写)
-import fs from "node:fs";
-import path from "node:path";
-import crypto from "node:crypto";
-
-export function ensureDir(dir) {
-  fs.mkdirSync(dir, { recursive: true });
-  return dir;
-}
-
-export function atomicWrite(file, data) {
-  ensureDir(path.dirname(file));
-  const tmp = file + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
-  fs.writeFileSync(tmp, data, "utf8");
-  // v1.0.8: rename 覆盖已存在文件在 Windows 并发下可能 EPERM/EEXIST (短窗口), 重试 3 次;
-  // 不再降级为非原子直接写 (并发双写可交错损坏文件), 重试仍失败则抛错由调用方处理
-  for (let attempt = 0; ; attempt++) {
-    try {
-      fs.renameSync(tmp, file);
-      return;
-    } catch (e) {
-      if (attempt >= 2) {
-        try { fs.unlinkSync(tmp); } catch {}
-        throw new Error(`原子写失败: ${file} (${e.message})`);
-      }
-      const end = Date.now() + 30;
-      while (Date.now() < end) {} // 短延迟后重试
-    }
-  }
-}
-
-export function readJson(file, fallback = null) {
-  try {
-    if (!fs.existsSync(file)) return fallback;
-    let raw = fs.readFileSync(file, "utf8");
-    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1); // 去 BOM
-    return JSON.parse(raw);
-  } catch {
-    return fallback;
-  }
-}
-
-export function writeJson(file, obj) {
-  atomicWrite(file, JSON.stringify(obj, null, 2));
-}
-
-// 简单跨进程文件锁 (零依赖, 同步): 原子创建 .lock 文件, 临界区内执行 fn, finally 释放
-// 用于跨 agent 共享文件的"读-改-写"临界区 (防并发覆盖, 如共享经验库)
-// 锁是同步 busy-wait (低频写场景可接受); 超时视为陈旧锁 (崩溃残留) 强取
-export function withFileLock(file, fn, { timeoutMs = 3000, pollMs = 20 } = {}) {
-  const lock = file + ".lock";
-  const acquire = () => {
-    try {
-      const fd = fs.openSync(lock, "wx"); // 'wx': 已存在则抛错 (原子)
-      try { fs.writeSync(fd, String(process.pid)); } catch {}
-      fs.closeSync(fd);
-      return true;
-    } catch {
-      return false;
-    }
-  };
-  const start = Date.now();
-  while (!acquire()) {
-    if (Date.now() - start > timeoutMs) {
-      try { fs.rmSync(lock, { force: true }); } catch {} // 陈旧锁强取
-      if (!acquire()) throw new Error("文件锁获取超时: " + lock);
-      break;
-    }
-    const end = Date.now() + pollMs;
-    while (Date.now() < end) {} // 同步短暂等待
-  }
-  try {
-    return fn();
-  } finally {
-    try { fs.rmSync(lock, { force: true }); } catch {}
-  }
-}
-
-export function readText(file, fallback = "") {
-  try {
-    if (!fs.existsSync(file)) return fallback;
-    return fs.readFileSync(file, "utf8");
-  } catch {
-    return fallback;
-  }
-}
-
-export function writeText(file, text) {
-  atomicWrite(file, text);
-}
-
-export function appendLine(file, line) {
-  ensureDir(path.dirname(file));
-  fs.appendFileSync(file, line + "\n", "utf8");
-}
-
-export function nowISO() {
-  return new Date().toISOString();
-}
-
-export function logicalDay(d = new Date()) {
-  // 逻辑日 (本地时区): 今日/归档/按天检索统一用本地年月日
-  // 与 eventsByDay() 的本地解析保持一致, 避免 8 小时时区偏移导致按天检索错位
-  const y = d.getFullYear();
-  const m = String(d.getMonth() + 1).padStart(2, "0");
-  const day = String(d.getDate()).padStart(2, "0");
-  return `${y}-${m}-${day}`;
-}
+// src/utils/store.js - 零依赖文件存储 (JSON + 原子写)
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { debug, warn } from "../utils/logger.js";
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function atomicWrite(file, data) {
+  ensureDir(path.dirname(file));
+  const tmp = file + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  fs.writeFileSync(tmp, data, "utf8");
+  // v1.0.8: rename 覆盖已存在文件在 Windows 并发下可能 EPERM/EEXIST (短窗口), 重试 3 次;
+  // 不再降级为非原子直接写 (并发双写可交错损坏文件), 重试仍失败则抛错由调用方处理
+  for (let attempt = 0; ; attempt++) {
+    try {
+      fs.renameSync(tmp, file);
+      return;
+    } catch (e) {
+      if (attempt >= 2) {
+        try { fs.unlinkSync(tmp); } catch (e) { debug(`[utils/store] 已忽略异常: ${e && e.message ? e.message : e}`); }
+        throw new Error(`原子写失败: ${file} (${e.message})`);
+      }
+      const end = Date.now() + 30;
+      while (Date.now() < end) {} // 短延迟后重试
+    }
+  }
+}
+
+export function readJson(file, fallback = null) {
+  try {
+    if (!fs.existsSync(file)) return fallback;
+    let raw = fs.readFileSync(file, "utf8");
+    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1); // 去 BOM
+    return JSON.parse(raw);
+  } catch (e) {
+    // v3.0.1 (P0#1): 解析失败不再完全静默 —— 至少留一条 warn。
+    // 注意: 此处**不动文件** (不自作主张改名/删除) —— healer 等组件对损坏文件
+    // 有自己的备份恢复契约 (如 healer.js 把 facts.json 改名为 .corrupt-<ts> 后重建),
+    // 低层 readJson 若抢先把文件改名会破坏该契约 (实测把 selfheal-bench 炸出 ENOENT)。
+    warn(`[utils/store] JSON 解析失败, 返回 fallback (文件保留): ${file} (${e && e.message ? e.message : e})`);
+    return fallback;
+  }
+}
+
+// 带信号的 readJson: 供"读-改-写"型存储 (如 FactStore) 区分「文件不存在」与「文件损坏」。
+// 损坏时 (parseFailed=true) 调用方必须避免立即用 fallback 覆盖回写 —— 文件原地保留,
+// 交给 healer / 人工恢复。非破坏式: 本函数同样不改名不删除。
+export function readJsonGuarded(file, fallback = null) {
+  const existedBefore = fs.existsSync(file);
+  if (!existedBefore) return { data: fallback, existedBefore: false, parseFailed: false };
+  try {
+    let raw = fs.readFileSync(file, "utf8");
+    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+    return { data: JSON.parse(raw), existedBefore: true, parseFailed: false };
+  } catch (e) {
+    warn(`[utils/store] JSON 损坏 (文件保留待恢复): ${file} (${e && e.message ? e.message : e})`);
+    return { data: fallback, existedBefore: true, parseFailed: true };
+  }
+}
+
+export function writeJson(file, obj) {
+  atomicWrite(file, JSON.stringify(obj, null, 2));
+}
+
+// 简单跨进程文件锁 (零依赖, 同步): 原子创建 .lock 文件, 临界区内执行 fn, finally 释放
+// 用于跨 agent 共享文件的"读-改-写"临界区 (防并发覆盖, 如共享经验库)
+// v3.0.1 (P1#5) 两处修复:
+//   ① 锁文件写 "pid:ts", 超时后先判持有者存活 —— 活进程持锁时不许抢 (原实现无脑强删锁文件,
+//      持有者还在临界区就出现双写, 互斥被破坏 → 数据交错损坏); 死进程/超长持有/自进程残留才强取。
+//   ② 等待用 Atomics.wait (OS 级阻塞, 零 CPU), 替代原自旋空转 (20ms×150 轮纯烧 CPU 且卡事件循环)。
+const _sleepArr = new Int32Array(new SharedArrayBuffer(4));
+function _syncSleep(ms) {
+  try { Atomics.wait(_sleepArr, 0, 0, ms); } catch { const end = Date.now() + ms; while (Date.now() < end) {} }
+}
+function _pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === "EPERM"; } // EPERM=存在但无权限
+}
+export function withFileLock(file, fn, { timeoutMs = 3000, pollMs = 20, staleMs = 15000 } = {}) {
+  const lock = file + ".lock";
+  const acquire = () => {
+    try {
+      const fd = fs.openSync(lock, "wx"); // 'wx': 已存在则抛错 (原子)
+      try { fs.writeSync(fd, `${process.pid}:${Date.now()}`); } catch (e) { debug(`[utils/store] 已忽略异常: ${e && e.message ? e.message : e}`); }
+      fs.closeSync(fd);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  // 陈旧锁判定 (v3.0.1 P1#5): 持有者进程已死 / 锁超长持有 / 自进程残留 → 可抢; 活跃进程持有 → 不可抢
+  const canSteal = () => {
+    try {
+      const raw = fs.readFileSync(lock, "utf8").trim();
+      const m = /^(\d+):(\d+)$/.exec(raw);
+      if (m) {
+        const pid = Number(m[1]);
+        if (pid === process.pid) return true;                       // 自进程残留
+        if (!_pidAlive(pid)) return true;                           // 持有者已死 (崩溃残留)
+        if (Date.now() - Number(m[2]) > staleMs) return true;       // 超长持有视为陈旧 (防 pid 复用误判)
+        return false;                                               // 活跃进程持锁: 不抢
+      }
+      // 兼容旧格式 (纯 pid) / 无法解析: 按 mtime 与 pid 存活判
+      const legacyPid = parseInt(raw, 10);
+      if (Number.isFinite(legacyPid) && legacyPid !== process.pid && !_pidAlive(legacyPid)) return true;
+      const st = fs.statSync(lock);
+      return Date.now() - st.mtimeMs > staleMs;
+    } catch {
+      return true; // 锁文件刚被释放/读不到 → 直接尝试抢
+    }
+  };
+  const start = Date.now();
+  while (!acquire()) {
+    if (Date.now() - start > timeoutMs) {
+      // v3.0.1 (P1#5): 活跃进程持锁 → 抛错而非抢锁 (宁可失败不可双写损坏)
+      if (!canSteal()) throw new Error(`文件锁被活跃进程持有, 等待 ${timeoutMs}ms 后放弃: ` + lock);
+      try { fs.rmSync(lock, { force: true }); } catch (e) { debug(`[utils/store] 已忽略异常: ${e && e.message ? e.message : e}`); } // 陈旧锁强取
+      if (!acquire()) throw new Error("文件锁获取超时: " + lock);
+      break;
+    }
+    _syncSleep(pollMs);
+  }
+  try {
+    return fn();
+  } finally {
+    try { fs.rmSync(lock, { force: true }); } catch (e) { debug(`[utils/store] 已忽略异常: ${e && e.message ? e.message : e}`); }
+  }
+}
+
+export function readText(file, fallback = "") {
+  try {
+    if (!fs.existsSync(file)) return fallback;
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeText(file, text) {
+  atomicWrite(file, text);
+}
+
+export function appendLine(file, line) {
+  ensureDir(path.dirname(file));
+  fs.appendFileSync(file, line + "\n", "utf8");
+}
+
+export function nowISO() {
+  return new Date().toISOString();
+}
+
+export function logicalDay(d = new Date()) {
+  // 逻辑日 (本地时区): 今日/归档/按天检索统一用本地年月日
+  // 与 eventsByDay() 的本地解析保持一致, 避免 8 小时时区偏移导致按天检索错位
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+// 按逻辑日切分 JSONL 的日志目录 (工具轨迹 utils/trace.js 与事件流 core/trace.js 共用)。
+// 两个写入器必须落在同一目录, 用同一函数取路径可避免字面量各写一份后悄悄漂移。
+export function logsDir(dataDir, sub = "traces") {
+  const dir = path.join(dataDir, "logs", sub);
+  ensureDir(dir);
+  return dir;
+}