@threadbase-sh/streamer 1.46.0 → 1.46.2

package/dist/index.d.cts

@@ -2340,6 +2340,27 @@ declare class ConversationWatcher {
      * Watch a directory of conversation JSONL files. Fires
      * onConversationChanged for any add/change/unlink event so the caller
      * can mark the cache dirty without scanning everything immediately.
+     *
+     * **This costs one OS watch handle per file under `directory`, not one per
+     * directory.** chokidar recurses the tree and registers a separate fs.watch
+     * per entry, because a directory watch alone does not report writes to files
+     * inside it — and per-file `change` events are exactly what the caller needs
+     * (they drive poke()'s tail self-heal and the external-tail attach). So the
+     * handle count tracks the size of the conversation corpus on disk, not the
+     * number of live sessions, and it does not shrink until transcripts are
+     * deleted. `ignoreInitial` suppresses the startup *events*, not the walk.
+     *
+     * Measured 2026-08-09 on the live macOS instance: 2131 open .jsonl fds
+     * against 2133 files under the watched roots — 1:1, ~88% of all fds on the
+     * process, at 2.0% of that box's 122 880 per-process ceiling. Comfortable
+     * there. **Linux is the tight one**: these are inotify watches billed to the
+     * per-user `max_user_watches`, which can be 8192 and is shared with every
+     * other watcher the user runs. Exhaustion surfaces as ENOSPC on the `error`
+     * event — which is why server.ts wires onError rather than leaving it unset.
+     *
+     * Before trading handles for a bound here, note the regression it invites: a
+     * conversation excluded from the walk (by age or by an LRU cap) is one whose
+     * external appends produce no event at all, and that failure is silent.
      */
     watchDirectory(directory: string): void;
     unwatchDirectory(directory: string): void;

package/dist/index.d.ts

@@ -2340,6 +2340,27 @@ declare class ConversationWatcher {
      * Watch a directory of conversation JSONL files. Fires
      * onConversationChanged for any add/change/unlink event so the caller
      * can mark the cache dirty without scanning everything immediately.
+     *
+     * **This costs one OS watch handle per file under `directory`, not one per
+     * directory.** chokidar recurses the tree and registers a separate fs.watch
+     * per entry, because a directory watch alone does not report writes to files
+     * inside it — and per-file `change` events are exactly what the caller needs
+     * (they drive poke()'s tail self-heal and the external-tail attach). So the
+     * handle count tracks the size of the conversation corpus on disk, not the
+     * number of live sessions, and it does not shrink until transcripts are
+     * deleted. `ignoreInitial` suppresses the startup *events*, not the walk.
+     *
+     * Measured 2026-08-09 on the live macOS instance: 2131 open .jsonl fds
+     * against 2133 files under the watched roots — 1:1, ~88% of all fds on the
+     * process, at 2.0% of that box's 122 880 per-process ceiling. Comfortable
+     * there. **Linux is the tight one**: these are inotify watches billed to the
+     * per-user `max_user_watches`, which can be 8192 and is shared with every
+     * other watcher the user runs. Exhaustion surfaces as ENOSPC on the `error`
+     * event — which is why server.ts wires onError rather than leaving it unset.
+     *
+     * Before trading handles for a bound here, note the regression it invites: a
+     * conversation excluded from the walk (by age or by an LRU cap) is one whose
+     * external appends produce no event at all, and that failure is silent.
      */
     watchDirectory(directory: string): void;
     unwatchDirectory(directory: string): void;

package/dist/index.js

@@ -8387,6 +8387,27 @@ var ConversationWatcher = class {
    * Watch a directory of conversation JSONL files. Fires
    * onConversationChanged for any add/change/unlink event so the caller
    * can mark the cache dirty without scanning everything immediately.
+   *
+   * **This costs one OS watch handle per file under `directory`, not one per
+   * directory.** chokidar recurses the tree and registers a separate fs.watch
+   * per entry, because a directory watch alone does not report writes to files
+   * inside it — and per-file `change` events are exactly what the caller needs
+   * (they drive poke()'s tail self-heal and the external-tail attach). So the
+   * handle count tracks the size of the conversation corpus on disk, not the
+   * number of live sessions, and it does not shrink until transcripts are
+   * deleted. `ignoreInitial` suppresses the startup *events*, not the walk.
+   *
+   * Measured 2026-08-09 on the live macOS instance: 2131 open .jsonl fds
+   * against 2133 files under the watched roots — 1:1, ~88% of all fds on the
+   * process, at 2.0% of that box's 122 880 per-process ceiling. Comfortable
+   * there. **Linux is the tight one**: these are inotify watches billed to the
+   * per-user `max_user_watches`, which can be 8192 and is shared with every
+   * other watcher the user runs. Exhaustion surfaces as ENOSPC on the `error`
+   * event — which is why server.ts wires onError rather than leaving it unset.
+   *
+   * Before trading handles for a bound here, note the regression it invites: a
+   * conversation excluded from the walk (by age or by an LRU cap) is one whose
+   * external appends produce no event at all, and that failure is silent.
    */
   watchDirectory(directory) {
     if (this.directories.has(directory)) return;
@@ -10683,6 +10704,13 @@ var StreamerServer = class {
             event: "cache.invalidate_on_unlink"
           });
         this.cacheMonitor?.recordUnlink(filePath);
+      },
+      onError: (filePath, err) => {
+        const enospc = err.code === "ENOSPC";
+        this.log.error(
+          enospc ? `Watcher hit the OS watch-handle limit on ${filePath} \u2014 raise fs.inotify.max_user_watches (Linux) or the process fd limit; conversation discovery and live tails are degraded until then` : `Watcher error on ${filePath}: ${err.message}`,
+          { filePath, err, event: enospc ? "watcher.limit_exhausted" : "watcher.error" }
+        );
       }
     });
     this.ptyManager = new LiveSessionManager({