ai-or-die 0.1.64 → 0.1.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.64",
+  "version": "0.1.66",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {

package/src/server.js

@@ -352,7 +352,15 @@ class ClaudeCodeWebServer {
       // .native form); .native is only used HERE, where it can't leak
       // into response paths or watcher-subscription keys.
       const resolvedTarget = this._canonicalizePathSync(targetPath);
-      const resolvedBase = this._canonicalizePathSync(this.baseFolder);
+      // Memoized — baseFolder is constant for the process lifetime, but
+      // _canonicalizePathSync calls fs.realpathSync.native which is a real
+      // syscall (10–50ms on a SUBST/network drive). isPathWithinBase runs
+      // on every OSC 7 emission via validatePath; without this cache, each
+      // emission paid a redundant baseFolder realpath round-trip.
+      if (!this._canonicalizedBaseFolder) {
+        this._canonicalizedBaseFolder = this._canonicalizePathSync(this.baseFolder);
+      }
+      const resolvedBase = this._canonicalizedBaseFolder;
       // Use path.relative instead of startsWith to avoid prefix-matching false positives
       // (e.g. /home/user-admin would match /home/user with startsWith)
       const relative = path.relative(resolvedBase, resolvedTarget);
@@ -2253,7 +2261,12 @@ class ClaudeCodeWebServer {
 
       let watcher;
       let watcherClosed = false;
-      const debounceMs = parseInt(process.env.FS_WATCHER_DEBOUNCE_MS, 10) || 100;
+      // Per the diagnosed Windows hang on Q:\src with multi-worktree + Claude
+      // bulk edits: the 100ms default barely coalesced — a single bulk-edit
+      // wave produced thousands of debounce timers. 500ms is still well below
+      // the 5s "stale buffer" UX threshold from ADR-0017 but cuts emitted
+      // event rate by ~5x under bulk activity.
+      const debounceMs = parseInt(process.env.FS_WATCHER_DEBOUNCE_MS, 10) || 500;
       // FS_WATCHER_STABILITY_MS env: defaults to 80ms (the tuned-down
       // value per ADR-0017 §Coalescing). Setting to 0 DISABLES chokidar's
       // awaitWriteFinish entirely — useful in tests where sync
@@ -2335,6 +2348,16 @@ class ClaudeCodeWebServer {
           // FS_WATCHER_USE_POLLING=1 → chokidar uses fs.stat-loop backend.
           usePolling: usePolling,
           ignoreDirs: ignoreFromEnv.length ? ignoreFromEnv : undefined,
+          // Narrow scope: chokidar only watches direct children of every
+          // subscribed path (vs. the prior recursive watch of the entire
+          // watchRoot tree). This is the load-bearing knob that bounds
+          // active_handles on large/multi-worktree trees — the symptom
+          // that prompted the unhang work. The client's existing soft-
+          // filter subscription model (current dir + open tabs) drives
+          // what chokidar actually watches via add()/unwatch() inside
+          // FileWatcher. Subscriptions for paths NOT in the displayed
+          // dir or an open tab don't allocate watch handles at all.
+          depth: 0,
         });
         sessionEntry.watcher = watcher;
 

package/src/terminal-bridge.js

@@ -42,6 +42,19 @@ class TerminalBridge extends BaseBridge {
      * @type {Map<string, string|null>}
      */
     this._liveCwd = new Map();
+
+    /**
+     * Raw OSC 7 path most recently seen for each session — used to skip the
+     * entire validate-and-emit chain when the shell re-emits the same path
+     * (every prompt redraw on pwsh/oh-my-posh/Starship). Without this, each
+     * redraw fires 3–4 fs.realpathSync syscalls per session; on a SUBST or
+     * mapped Windows drive (e.g. Q:\), those syscalls are 10–50ms each and
+     * pending requests pile up faster than they complete, blocking the event
+     * loop. The dedupe at line ~205 below only saves the *broadcast* — this
+     * one saves the syscalls.
+     * @type {Map<string, string|null>}
+     */
+    this._lastRawOsc7 = new Map();
   }
 
   // Override async command discovery — use default shell instead of searching PATH
@@ -156,6 +169,7 @@ class TerminalBridge extends BaseBridge {
     this._osc7Parsers.set(sessionId, new Osc7Parser());
     this._osc7Hooks.set(sessionId, hooks);
     this._liveCwd.set(sessionId, null);
+    this._lastRawOsc7.set(sessionId, null);
   }
 
   /**
@@ -169,6 +183,7 @@ class TerminalBridge extends BaseBridge {
     this._osc7Parsers.delete(sessionId);
     this._osc7Hooks.delete(sessionId);
     this._liveCwd.delete(sessionId);
+    this._lastRawOsc7.delete(sessionId);
   }
 
   /**
@@ -186,6 +201,18 @@ class TerminalBridge extends BaseBridge {
     if (!decoded.length) return;
 
     for (const raw of decoded) {
+      // Fast-path: skip the entire validate-and-emit chain when the shell
+      // re-emits the same raw path. pwsh + oh-my-posh/Starship redraws on
+      // every keystroke, so the same `file:///Q:/src` arrives N times per
+      // second. validatePath does 3–4 fs.realpathSync syscalls per call;
+      // on a SUBST/mapped/network drive each syscall is 10–50ms, and
+      // pending requests pile up faster than they complete. The dedupe
+      // at the cwd-level below (line 207) only saves the BROADCAST — it
+      // can't save the syscalls because they happen during validation.
+      const lastRaw = this._lastRawOsc7.get(sessionId);
+      if (raw === lastRaw) continue;
+      this._lastRawOsc7.set(sessionId, raw);
+
       let validated;
       try {
         validated = hooks.validatePath(raw);
@@ -199,9 +226,8 @@ class TerminalBridge extends BaseBridge {
       const cwd = validated.path || raw;
       const prev = this._liveCwd.get(sessionId) || null;
 
-      // Only emit on actual change — OSC 7 fires every prompt, including
-      // the no-cd common case. Suppressing same-value emits keeps the
-      // WebSocket frame count bounded by user activity, not prompt rate.
+      // Defence-in-depth: even if validation collapses two different raw
+      // strings to the same canonical cwd, don't broadcast a no-op change.
       if (cwd === prev) continue;
 
       this._liveCwd.set(sessionId, cwd);

package/src/utils/file-watcher.js

@@ -98,7 +98,12 @@ class FileWatcher extends EventEmitter {
    *                Subscribed paths are typically children of this root, but
    *                relPath is computed regardless (may include `..` segments
    *                if a subscription is outside the root).
-   *   - debounceMs: per-path debounce window (default 100, ADR §Coalescing).
+   *   - debounceMs: per-path debounce window (default 500, ADR §Coalescing).
+   *                 Bumped from 100 to 500 when the "Windows + multi-worktree
+   *                 + Claude bulk edits" hang was diagnosed — under bulk edits
+   *                 a 100ms window barely coalesces, and combined with the
+   *                 narrow-scope `depth: 0` path below the longer window
+   *                 substantially cuts event rate without harming UX.
    *   - addChangeDedupMs: window within which add+change collapses to change
    *                       (default 50, ADR §Coalescing layer 3).
    *   - renameDetectMs: window within which same-inode unlink+add collapses
@@ -108,7 +113,19 @@ class FileWatcher extends EventEmitter {
    *                                    layer 1; tunable for tests).
    *   - ignoreDirs: directory-name list for ignore patterns; default
    *                 DEFAULT_IGNORE_DIRS.
-   *   - includeHash: emit hash on change events (default true).
+   *   - depth: passed through to chokidar. `0` confines the watcher to direct
+   *            children of every watched path — used by the file-browser SSE
+   *            endpoint to eliminate the recursive-tree handle explosion on
+   *            Windows + large worktree trees. Default `undefined`
+   *            (chokidar's recursive default, for backward compat).
+   *   - includeHash: emit MD5 hash on change events. Default `true` UNLESS
+   *                 `depth: 0` is set, in which case the default flips to
+   *                 `false` because the sync `fs.readFileSync` inside
+   *                 `_flush()` can block the event loop under bulk edits
+   *                 (e.g. an agent generating many files in the displayed
+   *                 directory). The `file-tabs.js` hash short-circuit falls
+   *                 through gracefully when hash is absent (always refresh
+   *                 via HTTP), so functionality is preserved.
    */
   constructor(opts) {
     super();
@@ -124,14 +141,24 @@ class FileWatcher extends EventEmitter {
     let resolvedRoot = path.resolve(opts.watchRoot);
     try { resolvedRoot = fs.realpathSync(resolvedRoot); } catch (_) {}
     this._watchRoot = resolvedRoot;
-    this._debounceMs = typeof opts.debounceMs === 'number' ? opts.debounceMs : 100;
+    this._debounceMs = typeof opts.debounceMs === 'number' ? opts.debounceMs : 500;
     this._addChangeDedupMs = typeof opts.addChangeDedupMs === 'number' ? opts.addChangeDedupMs : 50;
     this._renameDetectMs = typeof opts.renameDetectMs === 'number' ? opts.renameDetectMs : 50;
     this._stabilityMs = typeof opts.stabilityMs === 'number' ? opts.stabilityMs : 80;
     this._pollIntervalMs = typeof opts.pollIntervalMs === 'number' ? opts.pollIntervalMs : 30;
     this._ignoreDirs = Array.isArray(opts.ignoreDirs) ? opts.ignoreDirs : DEFAULT_IGNORE_DIRS;
     this._ignoreRegexes = buildIgnoreRegexes(this._ignoreDirs);
-    this._includeHash = opts.includeHash !== false;
+    this._depth = typeof opts.depth === 'number' ? opts.depth : undefined;
+    // When the caller opted into narrow-scope (depth: 0) and didn't explicitly
+    // ask for hashes, default-off to keep _flush() from doing sync MD5 reads
+    // under bulk-edit storms. Explicit `includeHash: true` still wins.
+    if (typeof opts.includeHash === 'boolean') {
+      this._includeHash = opts.includeHash;
+    } else if (this._depth === 0) {
+      this._includeHash = false;
+    } else {
+      this._includeHash = true;
+    }
     // Allow callers to disable awaitWriteFinish entirely (for tests where
     // sync writeFileSync races chokidar's poll cycle). Default = on with
     // tuned-down values per ADR-0017.
@@ -211,6 +238,15 @@ class FileWatcher extends EventEmitter {
       usePolling: this._usePolling,
       interval: this._usePolling ? 50 : undefined,
       atomic: false,
+      // depth: 0 confines chokidar to direct children of every watched
+      // path (the watchRoot + anything later added via subscribe). The
+      // server passes this for the file-browser SSE path; subscriptions
+      // drive what's actually watched beyond the watchRoot via
+      // chokidar.add(). This is the load-bearing knob that bounds the
+      // active_handles cost on large/multi-worktree trees. `undefined`
+      // (the default) restores chokidar's recursive behaviour for
+      // backward compat in callers that haven't migrated.
+      depth: this._depth,
     });
 
     this._watcher.on('add', (p, stat) => this._onChokidar('add', p, stat));
@@ -270,24 +306,38 @@ class FileWatcher extends EventEmitter {
 
   /**
    * Add a path to the active subscription set. Events for this path will
-   * now flow through the consumer's 'event' listener. The path does not
-   * need to exist at subscribe time — chokidar already watches the
-   * watchRoot subtree, so add events fire when the file is created.
+   * now flow through the consumer's 'event' listener.
+   *
+   * When the watcher was constructed with `depth: 0`, the chokidar watch
+   * scope is dynamically managed: subscribing to a file watches its parent
+   * directory (chokidar emits events for direct children of the watched
+   * dir); subscribing to a directory recursively watches that directory.
+   * A physical-watch-target refcount means we only call chokidar.add()
+   * for the first subscription that needs a given dir, and chokidar.unwatch()
+   * for the last. Without this, two tabs in the same dir would race the
+   * underlying watch and a tab-close could kill another tab's events.
+   *
+   * For constructors NOT using depth: 0 (legacy callers), chokidar already
+   * watches the full subtree of watchRoot recursively, so subscribe is
+   * pure soft-filter bookkeeping (no chokidar.add).
    *
    * @param {string} absPath
    * @param {object} [opts]
-   *   - recursive: boolean — if true, the subscription is treated as a
-   *                directory-recursive match: events for `absPath` AND
-   *                any descendant fire. Used by FileBrowserPanel for
-   *                the "auto-refresh listing on agent-create" case
-   *                where the new file's path isn't known at subscribe
-   *                time. Default false (exact-path match).
+   *   - recursive: boolean — if true, the subscription matches the dir AND
+   *                its descendants (in the recursive-watch model). Under
+   *                depth: 0 the soft-filter set still uses this for event
+   *                matching, but chokidar itself only watches direct
+   *                children of the dir — descendant events would not
+   *                arrive (file-browser listing already filters to direct
+   *                children, so this is invisible to current consumers).
+   *                Default false (exact-path match).
    */
   async subscribe(absPath, opts) {
     if (this._closed) throw new Error('FileWatcher: cannot subscribe on a closed watcher');
     if (!this._watcher) throw new Error('FileWatcher: must call start() before subscribe()');
     const canonical = this._canonicalize(absPath);
-    if (opts && opts.recursive) {
+    const isRecursive = !!(opts && opts.recursive);
+    if (isRecursive) {
       // Store with a trailing path separator so the prefix-match in
       // _onChokidar via `startsWith(dir + sep)` works without false
       // positives (e.g. /a/b should NOT match /a/bc).
@@ -295,14 +345,21 @@ class FileWatcher extends EventEmitter {
     } else {
       this._subscriptions.add(canonical);
     }
+    if (this._depth === 0) {
+      const target = isRecursive ? canonical : path.dirname(canonical);
+      this._refWatchTarget(target);
+    }
   }
 
   /**
    * Remove a path from the active subscription set. Subsequent events for
-   * this path will be dropped on emit (chokidar continues to fire them
-   * internally — cheap to discard). Idempotent: removing a non-subscribed
+   * this path will be dropped on emit. Idempotent: removing a non-subscribed
    * path is a no-op.
    *
+   * Under `depth: 0`, also drops the chokidar watch on the corresponding
+   * target directory when no other subscription still references it (see
+   * `_refWatchTarget`).
+   *
    * The `recursive` opt must match the flavour the path was subscribed
    * with — calling unsubscribe(path, {recursive:true}) on an exact-
    * subscribed path is a no-op (and vice versa). Mismatched-flavour
@@ -312,10 +369,59 @@ class FileWatcher extends EventEmitter {
   async unsubscribe(absPath, opts) {
     if (this._closed) return;
     const canonical = this._canonicalize(absPath);
-    if (opts && opts.recursive) {
-      this._dirSubscriptions.delete(canonical + path.sep);
+    const isRecursive = !!(opts && opts.recursive);
+    let hadSub = false;
+    if (isRecursive) {
+      hadSub = this._dirSubscriptions.delete(canonical + path.sep);
+    } else {
+      hadSub = this._subscriptions.delete(canonical);
+    }
+    if (!hadSub) return; // idempotent — nothing to release
+    if (this._depth === 0) {
+      const target = isRecursive ? canonical : path.dirname(canonical);
+      this._unrefWatchTarget(target);
+    }
+  }
+
+  /**
+   * Refcount-key normalization for the watch-target map. On Windows the
+   * filesystem is case-insensitive but path strings carry whatever casing
+   * the caller used (or whatever realpathSync returned, which is not
+   * always the on-disk form for paths it can't resolve). Lower-casing the
+   * key means `subscribe('Q:\\src\\file.js')` and `unsubscribe('q:\\SRC\\
+   * FILE.JS')` resolve to the same refcount slot. Forward-slash
+   * normalization is a separate cross-platform concern handled by
+   * normalizePath above.
+   */
+  _watchKeyNorm(p) {
+    const n = normalizePath(p);
+    return process.platform === 'win32' ? n.toLowerCase() : n;
+  }
+
+  _refWatchTarget(target) {
+    // The watchRoot is already watched at start() time — never add/unwatch it
+    // dynamically here, or we'd risk closing the root chokidar handle.
+    if (this._watchKeyNorm(target) === this._watchKeyNorm(this._watchRoot)) return;
+    const key = this._watchKeyNorm(target);
+    const cur = this._dirRefcount.get(key) || 0;
+    this._dirRefcount.set(key, cur + 1);
+    if (cur === 0) {
+      this._watchedDirs.add(key);
+      try { this._watcher.add(target); } catch (_) { /* chokidar will surface via 'error' if real */ }
+    }
+  }
+
+  _unrefWatchTarget(target) {
+    if (this._watchKeyNorm(target) === this._watchKeyNorm(this._watchRoot)) return;
+    const key = this._watchKeyNorm(target);
+    const cur = this._dirRefcount.get(key) || 0;
+    if (cur === 0) return; // defensive — refcount should never go negative
+    if (cur === 1) {
+      this._dirRefcount.delete(key);
+      this._watchedDirs.delete(key);
+      try { this._watcher.unwatch(target); } catch (_) {}
     } else {
-      this._subscriptions.delete(canonical);
+      this._dirRefcount.set(key, cur - 1);
     }
   }