billion-context 0.1.86-pr.561.380 → 0.1.86

package/README.md

@@ -389,6 +389,23 @@ recommended** for many concurrent conversations because of the collision
 risk — until pi grows its own session-id signal. For pi multi-agent use,
 pass an explicit `x-acp-session` header per conversation to avoid collisions.
 
+### Windows: exclude the sessions dir from antivirus (#362)
+
+The proxy persists each session's compression state to the sessions dir
+(`%USERPROFILE%\.local\share\billion-context\` by default) and rewrites the
+file every turn of a long session. On Windows, real-time antivirus (Windows
+Defender), the search indexer, or a sync tool (OneDrive) can lock that
+directory mid-write, so the rename fails with `EPERM` and every persist for
+that session fails until the lock clears.
+
+When the same session fails N consecutive writes (default `5`), the proxy
+logs a one-time, actionable alert naming the directory to exclude. To fix it
+at the root: add `%USERPROFILE%\.local\share\billion-context\` to your
+antivirus **exclusions** (Windows Defender: Settings → Virus & threat
+protection → Manage settings → Exclusions → Add an exclusion → Folder) and
+make sure no sync tool (OneDrive / Dropbox / …) is syncing that path. Full
+steps in [CONFIGURATION.md](CONFIGURATION.md#windows-exclude-the-sessions-dir-from-antivirus-362).
+
 ## Status
 
 Early. Protocol handling and compression work against mock tests (500+ passing). Real-model integration testing is the next milestone. Expect rough edges.

package/README.zh-CN.md

@@ -265,6 +265,12 @@ Windows 下会自动发现常见 Clash/Mihomo 静态系统代理;Web UI 会显
 
 **建议:** Codex 和 OpenCode 可以安全地通过代理并发跑很多会话。pi 单个 agent 没问题,但因碰撞风险**不建议**并发多会话 —— 直到 pi 自己长出 session-id 信号。pi 多 agent 场景下,每个会话发一个显式 `x-acp-session` header 来避免碰撞。
 
+### Windows：把会话目录加入杀软排除项（#362）
+
+代理把每个会话的压缩状态持久化到会话目录（默认 `%USERPROFILE%\.local\share\billion-context\`），长会话每一轮都会重写该文件。在 Windows 上，实时杀毒（Windows Defender）、搜索索引器或同步工具（OneDrive）可能在写入中途锁住该目录，导致 rename 以 `EPERM` 失败，在锁解除前该会话的每次持久化都会失败。
+
+当同一会话连续 N 次写失败（默认 `5`）时，代理会打一条一次性、可操作的告警，明确指出要排除的目录。要从根上修复：把 `%USERPROFILE%\.local\share\billion-context\` 加入杀软**排除项**（Windows Defender：设置 → 病毒和威胁防护 → 管理设置 → 排除项 → 添加排除 → 文件夹），并确认没有同步工具（OneDrive / Dropbox / …）在同步该路径。完整步骤见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md) 的「Windows：把会话目录加入杀软排除项」章节。
+
 ## 状态
 
 早期。协议处理和压缩已通过 mock 测试(500+ 项通过)。真实模型集成测试是下一里程碑。预期会有粗糙的地方。

package/dist/index.js

@@ -49818,6 +49818,57 @@ function rel(p2, base) {
   return r && !r.startsWith("..") ? r : p2;
 }
 
+// src/persist-eperm.ts
+var LOCK_CODES = /\b(EPERM|EBUSY|EACCES)\b/;
+var WRITE_FAIL_RE = /^\[persist\] write failed for (.+?) \(total (\d+)x\): (.+)$/;
+var PersistEpermAlert = class {
+  dir;
+  threshold;
+  repeatMs;
+  platform;
+  now;
+  onAlert;
+  hasAlerted = false;
+  alertedAt = 0;
+  constructor(opts) {
+    this.dir = opts.dir;
+    this.threshold = opts.threshold ?? 5;
+    this.repeatMs = opts.repeatMs ?? 0;
+    this.platform = opts.platform ?? process.platform;
+    this.now = opts.now ?? Date.now;
+    this.onAlert = opts.onAlert ?? ((d, c) => log("warn", buildAlertMessage(d, c)));
+  }
+  // Returns true iff an alert was emitted. Runs on every kernel log line, so
+  // the non-matching cases bail before any allocation.
+  observe(level, msg) {
+    if (this.platform !== "win32") return false;
+    if (level !== "error" && level !== "warn") return false;
+    const m2 = WRITE_FAIL_RE.exec(msg);
+    if (!m2) return false;
+    const count = Number(m2[2]);
+    if (count < this.threshold) return false;
+    if (!LOCK_CODES.test(m2[3])) return false;
+    if (!this.shouldAlert()) return false;
+    this.hasAlerted = true;
+    this.alertedAt = this.now();
+    this.onAlert(this.dir, count);
+    return true;
+  }
+  shouldAlert() {
+    if (!this.hasAlerted) return true;
+    if (this.repeatMs <= 0) return false;
+    return this.now() - this.alertedAt >= this.repeatMs;
+  }
+};
+function buildAlertMessage(dir, count) {
+  return [
+    `[persist] session dir ${dir} failed ${count} consecutive writes (EPERM \u2014 rename is locked).`,
+    "Likely cause: Windows Defender / antivirus / indexer / a sync tool is locking the directory.",
+    `Fix: add ${dir} to Windows Defender exclusions (Settings \u2192 Virus & threat protection \u2192 Manage settings \u2192 Exclusions \u2192 Add an exclusion),`,
+    "and make sure no OneDrive / sync tool is syncing this path."
+  ].join("\n");
+}
+
 // src/persist.ts
 var PERSIST_VERSION = 3;
 var MIGRATION_MARKER = ".bili-migration-286.done";
@@ -49855,12 +49906,21 @@ var SessionStore = class {
     const debounceMs = opts?.debounceMs ?? defaultDebounce();
     this.enabled = (opts?.enabled ?? true) && debounceMs >= 0;
     this.dir = opts?.dir ?? defaultDir();
+    const baseLog = opts?.log ?? defaultLogger;
+    const epermAlert = new PersistEpermAlert({
+      dir: this.dir,
+      threshold: epermAlertThreshold(),
+      repeatMs: epermAlertRepeatMs()
+    });
     this.store = new StateStore({
       dir: this.dir,
       version: PERSIST_VERSION,
       debounceMs: Math.max(0, debounceMs),
       enabled: this.enabled,
-      log: opts?.log ?? defaultLogger,
+      log: (level, msg) => {
+        epermAlert.observe(level, msg);
+        baseLog(level, msg);
+      },
       relPath: (id, payload) => relPathFor(id, payload.meta?.protocol ?? payload.protocol, payload.meta?.upstreamOrigin ?? payload.upstreamOrigin),
       // Adopt the pre-envelope flat format this store itself wrote
       // before the kernel extraction (and every v1/v2 file before it).
@@ -50128,6 +50188,22 @@ function persistEnabled() {
   if (env === "0" || env === "false") return false;
   return true;
 }
+function epermAlertThreshold() {
+  const env = process.env.BILI_PERSIST_EPERM_ALERT_THRESHOLD;
+  if (env) {
+    const n = Number.parseInt(env, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return 5;
+}
+function epermAlertRepeatMs() {
+  const env = process.env.BILI_PERSIST_EPERM_ALERT_REPEAT_MS;
+  if (env) {
+    const n = Number.parseInt(env, 10);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return 0;
+}
 function defaultLogger(level, m2) {
   log(level, m2);
 }