@indigoai-us/hq-cloud 6.18.22-alpha.702 → 6.18.22

package/dist/watcher.js

@@ -355,9 +355,9 @@ function errorPath(err) {
 /**
  * Which backend a platform gets.
  *
- *   - macOS (FSEvents) and Windows (ReadDirectoryChangesW) watch a directory
- *     recursively with ONE OS handle, so the scoped planner places a few
- *     recursive watches over the in-scope tree.
+ *   - macOS (FSEvents) uses one recursive root handle and filters events
+ *     before they reach TreeWatcher. Windows uses the exact scoped recursive
+ *     plan over ReadDirectoryChangesW handles.
  *   - Linux has no recursive handle: a directory watch reports only its own
  *     direct contents. The same scoped backend runs with one shallow inotify
  *     watch per in-scope directory instead — and NONE per file, because the
@@ -370,7 +370,9 @@ function errorPath(err) {
 export function selectTreeWatchBackend(platform, forcePolling) {
     if (forcePolling)
         return "polling";
-    if (platform === "darwin" || platform === "win32")
+    if (platform === "darwin")
+        return "native-root";
+    if (platform === "win32")
         return "native-recursive";
     if (platform === "linux")
         return "native-shallow";
@@ -390,6 +392,12 @@ function startChokidarTreeWatch(hqRoot, shouldEmit, onEvent, onError, maxWatched
     const readyListeners = new Set();
     try {
         cw = watch(hqRoot, {
+            // Push walkers record a directory symlink as a link entry and never
+            // traverse its target. Keep polling discovery on the same boundary so
+            // aliased trees do not consume the path budget or produce events for
+            // content that cannot upload. Chokidar still reports changes to the
+            // symlink entry itself.
+            followSymlinks: false,
             // On Linux chokidar adds one fs.watch/inotify watch per descended dir.
             // The predicate therefore enforces both scope and the hard per-runner cap.
             ignored: toChokidarIgnored(shouldEmit, hqRoot, budget),
@@ -642,7 +650,7 @@ export function startScopedRecursiveWatch(hqRoot, shouldEmit, onEvent, onError,
         const openedOn = directoryIdentity(dir);
         let handle;
         try {
-            handle = fs.watch(dir, { recursive, persistent: true }, (eventType, filename) => {
+            handle = (opts.watchDirectory ?? fs.watch)(dir, { recursive, persistent: true }, (eventType, filename) => {
                 // `filename` is relative to THIS watch's directory (or null/empty if
                 // the platform couldn't provide it — nothing actionable then).
                 // `String()` coerces both the string and (older @types/node) Buffer
@@ -680,6 +688,11 @@ export function startScopedRecursiveWatch(hqRoot, shouldEmit, onEvent, onError,
         }
         handle.on("error", (err) => {
             onError(err);
+            // TreeWatcher handles systemic watch exhaustion by closing this backend
+            // and moving to polling. Reopening the failed path before that transition
+            // runs only repeats the same EMFILE/ENFILE failure.
+            if (isSystemicWatchError(err))
+                return;
             // A handle a re-plan already replaced (retiring) must not tear down its
             // replacement at the same path.
             if (closed || watchers.get(dir) !== handle)
@@ -730,6 +743,7 @@ export function startScopedRecursiveWatch(hqRoot, shouldEmit, onEvent, onError,
                 }
                 : onDirectorySeen,
             recursiveWatches,
+            maxDepth: opts.maxDepth,
             listChildDirs: opts.listChildDirs,
         }));
     }
@@ -982,17 +996,101 @@ export function startScopedRecursiveWatch(hqRoot, shouldEmit, onEvent, onError,
         }),
     };
 }
+/** Start one recursive watch on the HQ root and filter every event at ingress. */
+export function startNativeRootWatch(hqRoot, shouldEmit, onEvent, onError, opts = {}) {
+    const root = path.resolve(hqRoot);
+    const watchDirectory = opts.watchDirectory ?? fs.watch;
+    let handle = null;
+    let closed = false;
+    let attachFailures = 0;
+    const identity = new Map();
+    const closeHandle = () => {
+        const current = handle;
+        handle = null;
+        if (!current)
+            return;
+        try {
+            current.close();
+        }
+        catch {
+            // Already closed by the OS.
+        }
+    };
+    const attach = () => {
+        if (closed)
+            return;
+        try {
+            const openedOn = directoryIdentityAt(root);
+            const opened = watchDirectory(root, { recursive: true, persistent: true }, (eventType, filename) => {
+                if (closed || filename == null)
+                    return;
+                const absolutePath = path.resolve(root, String(filename));
+                const relative = path.relative(root, absolutePath);
+                if (relative === ".." ||
+                    relative.startsWith(`..${path.sep}`) ||
+                    path.isAbsolute(relative)) {
+                    return;
+                }
+                let isDir;
+                try {
+                    isDir = fs.lstatSync(absolutePath).isDirectory();
+                }
+                catch {
+                    // A rename event can describe a path that has already vanished.
+                }
+                const admitted = isDir === undefined
+                    ? shouldEmit(absolutePath, false) && shouldEmit(absolutePath, true)
+                    : shouldEmit(absolutePath, isDir);
+                if (!admitted)
+                    return;
+                onEvent(absolutePath, eventType === "change" ? "change" : "rename");
+            });
+            handle = opened;
+            if (openedOn !== undefined)
+                identity.set(root, openedOn);
+            opened.on("error", (err) => {
+                onError(err);
+                // Systemic errors are handled by TreeWatcher, which closes this
+                // backend and switches to polling. Reopening would repeat exhaustion.
+                if (closed || isSystemicWatchError(err) || handle !== opened)
+                    return;
+                closeHandle();
+                attach();
+            });
+        }
+        catch (err) {
+            attachFailures += 1;
+            onError(err);
+        }
+    };
+    attach();
+    return {
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            closeHandle();
+        },
+        mode: "native-root",
+        needsKnownKinds: true,
+        attachFailures,
+        watchedPathCount: () => (handle ? 1 : 0),
+        probeCoverage: () => probeScopedWatchCoverage({
+            root,
+            identities: identity,
+            directoryIdentity: directoryIdentityAt,
+        }),
+    };
+}
 /**
  * Start watching `hqRoot`, calling `onEvent(absolutePath)` for every change.
  *
  * Backend selection (the whole point of this helper):
- *   - macOS / Windows → scoped recursive `fs.watch` handles over the in-scope
- *     tree only ({@link startScopedRecursiveWatch}). chokidar 4 dropped its
- *     `fsevents` backend, so on macOS it watches via kqueue, which costs ~1
- *     open fd PER watched path — ~11k fds over a real HQ tree, which EMFILEs
- *     under the default soft `ulimit -n` (256) and silently kills the watcher
- *     (instant sync then falls back to the poll).
- *   - Linux / other → chokidar (recursive `fs.watch` is unsupported there).
+ *   - macOS → one recursive root `fs.watch`, with the scope filter applied
+ *     before an event reaches TreeWatcher.
+ *   - Windows → scoped recursive `fs.watch` handles over the in-scope tree.
+ *   - Linux → one shallow native watch per in-scope directory; other platforms
+ *     use chokidar (recursive `fs.watch` is unsupported there).
  *
  * The recursive backend does no descent-time filtering WITHIN a watched
  * subtree, so changes there are funneled to `onEvent`, which re-applies the
@@ -1002,11 +1100,41 @@ export function startScopedRecursiveWatch(hqRoot, shouldEmit, onEvent, onError,
  * ancestor-descent pruning that the chokidar backend needs
  * {@link toChokidarIgnored} to avoid.
  */
-function startTreeWatch(hqRoot, shouldEmit, onEvent, onError, maxWatchedPaths, onWatchBudgetExceeded, onDirectorySeen, forcePolling = false) {
+/** @internal Exported for backend-level regression tests. */
+export function startTreeWatch(hqRoot, shouldEmit, onEvent, onError, maxWatchedPaths, onWatchBudgetExceeded, onDirectorySeen, forcePolling = false) {
+    // Resolve the root once before the backend starts. Chokidar with
+    // followSymlinks:false treats descendant links as leaf entries, but an
+    // explicitly supplied root may itself be a symlink. Watch its real tree and
+    // map observed paths back to the caller's root spelling so the caller's
+    // filter and path routing retain their existing contract.
+    const displayRoot = path.resolve(hqRoot);
+    const root = fs.realpathSync(displayRoot);
+    const displayPath = (absolutePath) => root === displayRoot
+        ? absolutePath
+        : path.join(displayRoot, path.relative(root, absolutePath));
+    const watchFilter = root === displayRoot
+        ? shouldEmit
+        : (absolutePath, isDir) => shouldEmit(displayPath(absolutePath), isDir);
+    const watchEvent = root === displayRoot
+        ? onEvent
+        : (absolutePath, kind) => onEvent(displayPath(absolutePath), kind);
+    const watchDirectorySeen = onDirectorySeen
+        ? root === displayRoot
+            ? onDirectorySeen
+            : (absolutePath) => onDirectorySeen(displayPath(absolutePath))
+        : undefined;
     const choice = selectTreeWatchBackend(process.platform, forcePolling);
-    if (choice === "native-recursive" || choice === "native-shallow") {
+    if (choice === "native-root") {
+        const nativeRoot = startNativeRootWatch(root, watchFilter, watchEvent, onError);
+        if (nativeRoot.attachFailures === 0 && nativeRoot.watchedPathCount() === 1) {
+            return nativeRoot;
+        }
+        nativeRoot.close();
+    }
+    if (choice === "native-recursive" ||
+        choice === "native-shallow") {
         try {
-            const scoped = startScopedRecursiveWatch(hqRoot, shouldEmit, onEvent, onError, onDirectorySeen, choice === "native-shallow"
+            const scoped = startScopedRecursiveWatch(root, watchFilter, watchEvent, onError, watchDirectorySeen, choice === "native-shallow"
                 ? { recursiveWatches: false, maxWatchedPaths, onWatchBudgetExceeded }
                 : {});
             // Partial coverage is worse than a different backend: a planned root we
@@ -1024,7 +1152,7 @@ function startTreeWatch(hqRoot, shouldEmit, onEvent, onError, maxWatchedPaths, o
             onError(err);
         }
     }
-    return startChokidarTreeWatch(hqRoot, shouldEmit, onEvent, onError, maxWatchedPaths, onWatchBudgetExceeded, forcePolling);
+    return startChokidarTreeWatch(root, watchFilter, watchEvent, onError, maxWatchedPaths, onWatchBudgetExceeded, forcePolling);
 }
 /**
  * Build the composite emit-decision predicate. Returns true when a change to
@@ -2333,7 +2461,10 @@ export class TreeWatcher {
     }
     /** Active backend mode, including the no-inotify polling fallback. */
     watchMode() {
-        return this.backend?.mode ?? (this.backend ? "unknown" : "inactive");
+        const mode = this.backend?.mode;
+        if (mode === "native-root")
+            return "native";
+        return mode ?? (this.backend ? "unknown" : "inactive");
     }
     /**
      * Check that the HQ root and every live watch still resolve to the inode