wicked-brain 0.14.1 → 0.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [

package/server/bin/wicked-brain-call.mjs

@@ -11,6 +11,9 @@ import {
   unlinkSync,
   existsSync,
   mkdirSync,
+  openSync,
+  closeSync,
+  statSync,
 } from "node:fs";
 import { join, resolve, basename } from "node:path";
 import { homedir } from "node:os";
@@ -186,6 +189,24 @@ function pidAlive(pid) {
 
 // ---------- server lifecycle ----------
 
+// Open {brain}/_meta/server.log for the detached daemon's stdout+stderr. Without
+// this the server is spawned with stdio:"ignore", so a boot crash (e.g. an
+// EMFILE watch error) vanishes and the only symptom is the "did not become
+// ready" timeout below. Caps growth: starts fresh if the existing log exceeds
+// 5 MB so a long-lived daemon stays diagnosable without growing unbounded.
+function openServerLog(brainPath) {
+  const logPath = join(brainPath, "_meta", "server.log");
+  let flag = "a";
+  try {
+    if (statSync(logPath).size > 5 * 1024 * 1024) flag = "w";
+  } catch {}
+  try {
+    return { fd: openSync(logPath, flag), logPath };
+  } catch {
+    return { fd: null, logPath };
+  }
+}
+
 async function ensureServer(brainPath, opts) {
   const { explicitPort, sourceOverride, noSpawn, log, spawnTimeoutMs = 10_000 } = opts;
   const meta = readMetaConfig(brainPath);
@@ -227,15 +248,28 @@ async function ensureServer(brainPath, opts) {
     const argv = [SERVER_BIN, "--brain", brainPath, "--port", String(port)];
     if (sourcePath) argv.push("--source", sourcePath);
 
-    const child = spawn(process.execPath, argv, {
-      detached: true,
-      stdio: "ignore",
-      windowsHide: true,
-    });
-    child.unref();
+    const { fd: logFd, logPath } = openServerLog(brainPath);
+    try {
+      const child = spawn(process.execPath, argv, {
+        detached: true,
+        stdio: logFd === null ? "ignore" : ["ignore", logFd, logFd],
+        windowsHide: true,
+      });
+      child.unref();
+    } finally {
+      // Close our copy of the fd in all cases — the child keeps its own. Without
+      // the finally a synchronous spawn() throw would leak the descriptor.
+      if (logFd !== null) {
+        try { closeSync(logFd); } catch {}
+      }
+    }
+    if (logFd !== null) log(`server logs -> ${logPath}`);
 
     if (await waitForHealth(port, spawnTimeoutMs)) return port;
-    throw new Error(`server did not become ready within ${spawnTimeoutMs}ms on port ${port}`);
+    throw new Error(
+      `server did not become ready within ${spawnTimeoutMs}ms on port ${port}` +
+        (logFd !== null ? ` — see ${logPath} for the cause` : ""),
+    );
   } finally {
     releaseLock(lockPath);
   }

package/server/lib/file-watcher.mjs

@@ -1,3 +1,12 @@
+/**
+ * Recursive fs.watch over brain content with a polling fallback.
+ *
+ * Watches chunks/, wiki/, memory/ and registered project dirs; on any watch
+ * error (EMFILE/ENOSPC, or recursive watch unsupported) it degrades to polling
+ * instead of crashing the server.
+ *
+ * @module lib/file-watcher
+ */
 import { watch, readFileSync, existsSync, readdirSync, statSync, realpathSync } from "node:fs";
 import { join, relative } from "node:path";
 import { createHash } from "node:crypto";
@@ -48,12 +57,26 @@ export class FileWatcher {
   #pollInterval = null;
   #onChangeCallbacks = [];
   #projects = [];
+  #watch;
 
-  constructor(brainPath, db, brainId, projects = []) {
+  constructor(brainPath, db, brainId, projects = [], watchFn = watch) {
     this.#brainPath = brainPath;
     this.#db = db;
     this.#brainId = brainId;
     this.#projects = projects;
+    // Injectable so tests can drive the FSWatcher 'error' path deterministically
+    // without exhausting real file descriptors; defaults to node:fs watch.
+    this.#watch = watchFn;
+  }
+
+  /** Active fs watcher count (0 in polling mode). Exposed for tests/diagnostics. */
+  get watcherCount() {
+    return this.#watchers.length;
+  }
+
+  /** True once the watcher has fallen back to polling. For tests/diagnostics. */
+  get polling() {
+    return this.#pollInterval !== null;
   }
 
   onFileChange(callback) {
@@ -94,18 +117,14 @@ export class FileWatcher {
     for (const project of this.#projects) {
       if (!existsSync(project.path)) continue;
       this.#scanAndHashProject(project);
-      try {
-        const watcher = watch(canonicalDir(project.path), { recursive: true }, (eventType, filename) => {
-          if (!filename) return;
-          const parts = filename.split(/[/\\]/);
-          if (parts.some(p => IGNORE_DIRS.has(p))) return;
-          const relPath = normalizePath(`projects/${project.name}/${filename}`);
-          this.#debounce(relPath, () => this.#handleProjectChange(project, filename));
-        });
-        this.#watchers.push(watcher);
-      } catch {
-        // recursive watch not supported — polling fallback already handles this
-      }
+      const watcher = this.#safeWatch(project.path, (eventType, filename) => {
+        if (!filename) return;
+        const parts = filename.split(/[/\\]/);
+        if (parts.some(p => IGNORE_DIRS.has(p))) return;
+        const relPath = normalizePath(`projects/${project.name}/${filename}`);
+        this.#debounce(relPath, () => this.#handleProjectChange(project, filename));
+      });
+      if (watcher) this.#watchers.push(watcher);
     }
 
     // If no watchers were set up (Linux), use polling fallback
@@ -120,18 +139,67 @@ export class FileWatcher {
   #tryWatch(dir) {
     const absDir = join(this.#brainPath, dir);
     if (!existsSync(absDir)) return false;
+    const watcher = this.#safeWatch(absDir, (eventType, filename) => {
+      if (!filename || !filename.endsWith(".md")) return;
+      const relPath = normalizePath(`${dir}/${filename}`);
+      this.#debounce(relPath, () => this.#handleChange(relPath));
+    });
+    if (!watcher) return false;
+    this.#watchers.push(watcher);
+    return true;
+  }
+
+  /**
+   * Create a recursive fs.watch with an 'error' handler attached. An unhandled
+   * 'error' event on an FSWatcher is rethrown by Node and crashes the entire
+   * server — that turned a common, recoverable condition (EMFILE when the
+   * open-file limit is low on macOS, ENOSPC/inotify exhaustion on Linux) into a
+   * fatal boot crash that left the brain permanently stale. On any watch error
+   * we degrade to polling, which holds no persistent watch descriptors.
+   *
+   * Returns the watcher, or null if watching could not be started (caller then
+   * relies on the polling fallback). The path is canonicalized first — see
+   * canonicalDir; required on Windows to avoid a libuv abort on 8.3 paths.
+   */
+  #safeWatch(absPath, listener) {
+    if (this.#pollInterval) return null; // already degraded — don't reopen fs watches
+    let watcher;
     try {
-      const watcher = watch(canonicalDir(absDir), { recursive: true }, (eventType, filename) => {
-        if (!filename || !filename.endsWith(".md")) return;
-        const relPath = normalizePath(`${dir}/${filename}`);
-        this.#debounce(relPath, () => this.#handleChange(relPath));
-      });
-      this.#watchers.push(watcher);
-      return true;
-    } catch {
-      // recursive watch not supported (Linux) — polling fallback handles it
-      return false;
+      watcher = this.#watch(canonicalDir(absPath), { recursive: true }, listener);
+    } catch (err) {
+      // Resource exhaustion (EMFILE/ENFILE/ENOSPC) can throw synchronously, not
+      // only as an async 'error' event. Don't leave already-watched dirs in a
+      // half-watched state — degrade the whole watcher to polling. Other sync
+      // failures (e.g. recursive watch unsupported on older Linux) fall through
+      // to the polling fallback in start() when no watcher attaches.
+      if (err && (err.code === "EMFILE" || err.code === "ENFILE" || err.code === "ENOSPC")) {
+        this.#degradeToPolling();
+      }
+      return null;
+    }
+    if (watcher && typeof watcher.on === "function") {
+      watcher.on("error", (err) => this.#onWatchError(err));
+    }
+    return watcher;
+  }
+
+  /** A watch backend errored. Log and fall back to polling rather than crash. */
+  #onWatchError(err) {
+    const code = (err && err.code) || "UNKNOWN";
+    console.error(
+      `[watcher] fs.watch error (${code}) — degrading to polling: ${(err && err.message) || err}`,
+    );
+    this.#degradeToPolling();
+  }
+
+  /** Tear down fs watchers and switch to polling. Idempotent. */
+  #degradeToPolling() {
+    if (this.#pollInterval) return; // already polling
+    for (const w of this.#watchers) {
+      try { w.close(); } catch {}
     }
+    this.#watchers = [];
+    this.#startPolling();
   }
 
   stop() {
@@ -310,6 +378,7 @@ export class FileWatcher {
   }
 
   #startPolling() {
+    if (this.#pollInterval) return; // already polling — keep a single interval
     console.log("File watcher using polling mode (recursive watch not available)");
     this.#pollInterval = setInterval(() => {
       for (const dir of ["chunks", "wiki", "memory"]) {

package/server/lib/memory-subscriber.mjs

@@ -13,6 +13,12 @@ import { join } from "node:path";
 import { getBusDb, isBusAvailable, emitEvent } from "./bus.mjs";
 import { promoteFact } from "./memory-promoter.mjs";
 
+// Subscriber identity on the bus. Used both to register the subscription and to
+// locate its cursor for the TTL self-heal — keep them in one place so the two
+// can't drift.
+const PLUGIN = "wicked-brain";
+const FACT_FILTER = "wicked.fact.extracted";
+
 /**
  * Start the auto-memorize subscriber.
  * Returns the subscription handle (with .stop()) or null if the bus is unavailable.
@@ -38,10 +44,22 @@ export async function startMemorySubscriber({ brainPath, brainId, db }) {
 
   const memoryDir = join(brainPath, "memory");
 
+  // Self-heal a cursor stranded behind the bus TTL window (e.g. after a long
+  // server outage). The subscriber RESUMES its existing cursor, so cursor_init
+  // "latest" does not recover a stale one — poll() would throw WB-003 every
+  // cycle and auto-memorize would stall until manually reset. Advance it to the
+  // latest event before subscribing.
+  const healed = fastForwardStaleCursor(busDb, PLUGIN, FACT_FILTER);
+  if (healed) {
+    console.error(
+      `[memory-subscriber] cursor was behind the TTL window; repositioned ${healed.from} -> ${healed.to} to replay survivors`,
+    );
+  }
+
   const sub = subscribe({
     db: busDb,
-    plugin: "wicked-brain",
-    filter: "wicked.fact.extracted",
+    plugin: PLUGIN,
+    filter: FACT_FILTER,
     cursor_init: "latest",
     pollIntervalMs: 5000,
     maxRetries: 3,
@@ -84,6 +102,63 @@ export async function startMemorySubscriber({ brainPath, brainId, db }) {
   return sub;
 }
 
+/**
+ * Fast-forward a subscriber cursor that has fallen behind the bus TTL window.
+ *
+ * After a long server outage the durable cursor can sit below the oldest
+ * surviving event; wicked-bus poll() then throws WB-003 ("cursor behind the TTL
+ * window") every cycle. The subscriber resumes its existing cursor (cursor_init
+ * only applies on first registration), so it never recovers on its own. This
+ * mirrors poll()'s WB-003 check and, when behind, repositions the cursor to just
+ * before the oldest surviving event so the subscriber still replays everything
+ * left in the bus (at-least-once) instead of discarding the survivors.
+ *
+ * No-op when the cursor is current, when there are no events, or when no cursor
+ * exists yet (a fresh subscriber initializes at "latest" anyway). Never throws —
+ * a self-heal failure must not block server startup.
+ *
+ * @param {import('better-sqlite3').Database} busDb
+ * @param {string} plugin
+ * @param {string} filter  event_type_filter the subscriber registered with
+ * @returns {{from:number,to:number}|null} the adjustment made, or null for no-op
+ */
+export function fastForwardStaleCursor(busDb, plugin, filter) {
+  try {
+    const bounds = busDb
+      .prepare("SELECT MIN(event_id) AS min_id FROM events")
+      .get();
+    if (!bounds || bounds.min_id == null) return null; // no events to be behind of
+
+    const row = busDb
+      .prepare(
+        `SELECT c.cursor_id AS cursor_id, c.last_event_id AS last_event_id
+           FROM subscriptions s
+           INNER JOIN cursors c ON c.subscription_id = s.subscription_id
+          WHERE s.plugin = ? AND s.role = 'subscriber'
+            AND s.event_type_filter = ?
+            AND s.deregistered_at IS NULL AND c.deregistered_at IS NULL
+          ORDER BY s.registered_at DESC
+          LIMIT 1`,
+      )
+      .get(plugin, filter);
+    if (!row) return null; // no existing cursor — fresh subscribe inits at "latest"
+
+    // Mirror wicked-bus poll(): WB-003 fires when last_event_id < oldest - 1.
+    // Reposition to oldest-1 (not latest) so the subscriber replays every event
+    // that survived the sweep instead of discarding the backlog.
+    const target = bounds.min_id - 1;
+    if (row.last_event_id < target) {
+      busDb
+        .prepare("UPDATE cursors SET last_event_id = ? WHERE cursor_id = ?")
+        .run(target, row.cursor_id);
+      return { from: row.last_event_id, to: target };
+    }
+    return null;
+  } catch {
+    return null; // never block startup on the self-heal
+  }
+}
+
 /**
  * Render a memory descriptor as a markdown file with YAML-ish frontmatter.
  * Minimal serializer — no YAML lib. Matches the format used by wicked-brain:memory.

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [