wicked-brain 0.14.1 → 0.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "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/package.json

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