@openclaw/feishu 2026.9.8 → 2026.10.1-beta.2

package/node_modules/@openclaw/fs-safe/dist/walk.js

@@ -39,7 +39,7 @@ function buildEntry(params) {
         path: fullPath,
         relativePath: params.relativePath,
         depth: params.depth,
-        kind: params.kind ?? kindForDirent(params.dirent),
+        kind: params.kind,
         dirent: params.dirent,
     };
 }
@@ -101,35 +101,62 @@ export function walkDirectorySync(rootDir, options = {}) {
             return;
         visitedDirs.add(realDir);
         let entries;
+        let handle;
         try {
-            entries = fsSync.readdirSync(operationPath, { withFileTypes: true });
+            if (options.maxEntries === undefined) {
+                entries = fsSync.readdirSync(operationPath, { withFileTypes: true });
+            }
+            else {
+                handle = fsSync.opendirSync(operationPath);
+            }
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
             return;
         }
         const childPrefix = dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`;
-        for (const dirent of entries) {
-            if (shouldStop(result, options)) {
-                result.truncated = true;
-                return;
+        let index = 0;
+        try {
+            while (true) {
+                let dirent;
+                try {
+                    dirent = handle ? handle.readSync() : entries[index++];
+                }
+                catch (error) {
+                    recordFailedDir(result, root, dir, depth, error);
+                    return;
+                }
+                if (!dirent)
+                    return;
+                if (shouldStop(result, options)) {
+                    result.truncated = true;
+                    return;
+                }
+                result.scannedEntryCount += 1;
+                const fullPath = childPrefix + dirent.name;
+                const kind = resolveKind(fullPath, dirent, symlinks);
+                if (!kind)
+                    continue;
+                const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
+                const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
+                if (options.include?.(entry) ?? true) {
+                    result.entries.push(entry);
+                }
+                if (kind === "directory" &&
+                    (options.maxDepth === undefined || depth < options.maxDepth) &&
+                    (options.descend?.(entry) ?? true)) {
+                    visit(fullPath, relativePath, depth + 1);
+                    if (result.truncated)
+                        return;
+                }
             }
-            result.scannedEntryCount += 1;
-            const fullPath = childPrefix + dirent.name;
-            const kind = resolveKind(fullPath, dirent, symlinks);
-            if (!kind)
-                continue;
-            const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
-            const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
-            if (options.include?.(entry) ?? true) {
-                result.entries.push(entry);
+        }
+        finally {
+            try {
+                handle?.closeSync();
             }
-            if (kind === "directory" &&
-                (options.maxDepth === undefined || depth < options.maxDepth) &&
-                (options.descend?.(entry) ?? true)) {
-                visit(fullPath, relativePath, depth + 1);
-                if (result.truncated)
-                    return;
+            catch (error) {
+                recordFailedDir(result, root, dir, depth, error);
             }
         }
     }
@@ -165,40 +192,67 @@ export async function walkDirectory(rootDir, options = {}) {
             return;
         visitedDirs.add(realDir);
         let entries;
+        let handle;
         try {
-            entries = await fs.readdir(operationPath, { withFileTypes: true });
+            if (options.maxEntries === undefined) {
+                entries = await fs.readdir(operationPath, { withFileTypes: true });
+            }
+            else {
+                handle = await fs.opendir(operationPath);
+            }
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
             return;
         }
         const childPrefix = dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`;
-        for (const dirent of entries) {
-            if (shouldStop(result, options)) {
-                result.truncated = true;
-                return;
+        let index = 0;
+        try {
+            while (true) {
+                let dirent;
+                try {
+                    dirent = handle ? await handle.read() : entries[index++];
+                }
+                catch (error) {
+                    recordFailedDir(result, root, dir, depth, error);
+                    return;
+                }
+                if (!dirent)
+                    return;
+                if (shouldStop(result, options)) {
+                    result.truncated = true;
+                    return;
+                }
+                result.scannedEntryCount += 1;
+                const fullPath = childPrefix + dirent.name;
+                const kind = resolveKind(fullPath, dirent, symlinks);
+                if (!kind)
+                    continue;
+                const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
+                const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
+                const include = options.include;
+                const included = include == null ? true : Reflect.apply(include, options, [entry]);
+                if ((isObjectResult(included) ? await included : included) ?? true) {
+                    result.entries.push(entry);
+                }
+                if (kind === "directory" &&
+                    (options.maxDepth === undefined || depth < options.maxDepth)) {
+                    const descend = options.descend;
+                    const descended = descend == null ? true : Reflect.apply(descend, options, [entry]);
+                    if ((isObjectResult(descended) ? await descended : descended) ?? true) {
+                        await visit(fullPath, relativePath, depth + 1);
+                        if (result.truncated)
+                            return;
+                    }
+                }
             }
-            result.scannedEntryCount += 1;
-            const fullPath = childPrefix + dirent.name;
-            const kind = resolveKind(fullPath, dirent, symlinks);
-            if (!kind)
-                continue;
-            const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
-            const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
-            const include = options.include;
-            const included = include == null ? true : Reflect.apply(include, options, [entry]);
-            if ((isObjectResult(included) ? await included : included) ?? true) {
-                result.entries.push(entry);
+        }
+        finally {
+            try {
+                await handle?.close();
             }
-            if (kind === "directory" &&
-                (options.maxDepth === undefined || depth < options.maxDepth)) {
-                const descend = options.descend;
-                const descended = descend == null ? true : Reflect.apply(descend, options, [entry]);
-                if ((isObjectResult(descended) ? await descended : descended) ?? true) {
-                    await visit(fullPath, relativePath, depth + 1);
-                    if (result.truncated)
-                        return;
-                }
+            catch (error) {
+                recordFailedDir(result, root, dir, depth, error);
             }
         }
     }

package/node_modules/@openclaw/fs-safe/dist/watch-hints.d.ts

@@ -1,9 +1,16 @@
+import { type RootContext } from "./root-context.js";
 import type { NativeWatchBatch } from "./watch-native.js";
 import type { WatchSnapshot } from "./watch-scan.js";
 import type { WatchChange, WatchScope } from "./watch-types.js";
 export declare function excludedWatchPath(snapshot: WatchSnapshot | undefined, name: string): boolean;
 export declare function scopedChanges(scopes: readonly WatchScope[], change: WatchChange): WatchChange[];
+/** An undecodable child cannot equal a validated literal scope component. */
+export declare function selectedWatchChildren(scopes: readonly WatchScope[], directory: string): boolean;
+/** A folded directory can contain a missing scope component, unlike a nameless child. */
+export declare function selectedWatchSubtree(scopes: readonly WatchScope[], directory: string): boolean;
 export declare function nativeChanges(scopes: readonly WatchScope[], snapshot: WatchSnapshot | undefined, batch: NativeWatchBatch, limit?: number, after?: WatchSnapshot): WatchChange[] | undefined;
 export declare function changedEntries(before: WatchSnapshot | undefined, after: WatchSnapshot, limit: number): WatchChange[] | undefined;
 /** Backend names never establish authority to publish a pathname. */
 export declare function guardedHintChanges(scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, hints: readonly WatchChange[] | undefined, observed: readonly WatchChange[] | undefined, limit: number): WatchChange[] | undefined;
+/** Resolve native spelling aliases without treating case folding as identity. */
+export declare function admittedNativeChanges(root: RootContext, scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, batch: NativeWatchBatch, signal: AbortSignal, limit: number, scheduling?: boolean): Promise<WatchChange[] | undefined>;

package/node_modules/@openclaw/fs-safe/dist/watch-hints.js

@@ -1,9 +1,22 @@
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertRootIdentityCurrent, resolvePathInRoot } from "./root-context.js";
+import { createRootDirectoryObservationGuard, assertRootDirectoryObservationGuard } from "./root-directory-list.js";
+import { lookupRootDirectoryEntry } from "./root-directory-entry.js";
 function below(parent, child) {
     return parent === "" ? child !== "" : child.startsWith(parent + path.sep);
 }
-function distance(parent, child) {
-    return (parent === "" ? child : child.slice(parent.length + 1)).split(path.sep).length;
+function selectedByTree(scope, name, childDepth = 0) {
+    return scope.kind === "tree" && (scope.path === name ? childDepth <= scope.depth : below(scope.path, name) &&
+        (scope.path === "" ? name : name.slice(scope.path.length + 1)).split(path.sep).length + childDepth <= scope.depth);
+}
+function addChange(result, change, limit) {
+    if (!result.has(change.path) && result.size >= limit)
+        return false;
+    const prior = result.get(change.path);
+    result.set(change.path, prior?.type === "structural" ? prior : change);
+    return true;
 }
 export function excludedWatchPath(snapshot, name) {
     const exclusions = snapshot?.excluded;
@@ -20,7 +33,7 @@ export function excludedWatchPath(snapshot, name) {
 export function scopedChanges(scopes, change) {
     const result = new Map();
     for (const scope of scopes) {
-        if (scope.path === change.path || (scope.kind === "tree" && below(scope.path, change.path) && distance(scope.path, change.path) <= scope.depth)) {
+        if (scope.path === change.path || selectedByTree(scope, change.path)) {
             result.set(change.path, change);
         }
         else if (below(change.path, scope.path)) {
@@ -30,6 +43,19 @@ export function scopedChanges(scopes, change) {
     }
     return [...result.values()];
 }
+/** An undecodable child cannot equal a validated literal scope component. */
+export function selectedWatchChildren(scopes, directory) {
+    return scopes.some(scope => selectedByTree(scope, directory, 1));
+}
+/** A folded directory can contain a missing scope component, unlike a nameless child. */
+export function selectedWatchSubtree(scopes, directory) {
+    return scopes.some(scope => scope.path === directory || below(directory, scope.path) ||
+        selectedByTree(scope, directory));
+}
+function literalName(name) {
+    return typeof name === "string" && !!name && name !== "." && name !== ".." && !name.includes("\0") && !name.includes("/") &&
+        (process.platform !== "win32" || !/[\\:]/.test(name));
+}
 export function nativeChanges(scopes, snapshot, batch, limit = 256, after) {
     if (batch.overflow)
         return undefined;
@@ -37,19 +63,25 @@ export function nativeChanges(scopes, snapshot, batch, limit = 256, after) {
     for (const hint of batch.hints) {
         const name = hint.name;
         // Backend filenames are untrusted hints. Never resolve or perform I/O on them.
-        if (typeof name !== "string" || !name || name === "." || name === ".." || name.includes("\0") || name.includes("/") || (process.platform === "win32" && /[\\:]/.test(name)))
+        if (typeof hint.directory !== "string" || (hint.directory && !hint.directory.split(path.sep).every(literalName)))
             return undefined;
-        const relative = hint.directory ? path.join(hint.directory, name) : name;
+        const children = hint.event === "children";
+        const subtree = hint.event === "subtree";
+        if (children || subtree ? name !== "" : !literalName(name))
+            return undefined;
+        if (subtree)
+            continue; // Folded hints only schedule guarded diff passes; never publish their spelling.
+        if (children && !selectedWatchChildren(scopes, hint.directory))
+            continue;
+        const relative = children ? hint.directory : hint.directory ? path.join(hint.directory, name) : name;
         if (excludedWatchPath(snapshot, relative) || excludedWatchPath(after, relative))
             continue;
         for (const change of scopedChanges(scopes, {
             path: relative,
             type: hint.event === "change" && snapshot?.entries.get(relative)?.startsWith("file:") ? "content" : "structural",
         })) {
-            if (!result.has(change.path) && result.size >= limit)
+            if (!addChange(result, change, limit))
                 return undefined;
-            const prior = result.get(change.path);
-            result.set(change.path, prior?.type === "structural" ? prior : change);
         }
     }
     return [...result.values()];
@@ -58,17 +90,24 @@ export function changedEntries(before, after, limit) {
     if (!before)
         return undefined;
     const changes = [];
-    for (const name of new Set([...before.entries.keys(), ...after.entries.keys()])) {
+    const compare = (name) => {
         const left = before.entries.get(name);
         const right = after.entries.get(name);
         if (left === right)
-            continue;
+            return true;
         if (changes.length >= limit)
-            return undefined;
+            return false;
         const sameFile = left?.startsWith("file:") && right?.startsWith("file:") &&
             left.split(":").slice(0, 3).join(":") === right.split(":").slice(0, 3).join(":");
         changes.push(Object.freeze({ path: name, type: sameFile ? "content" : "structural" }));
-    }
+        return true;
+    };
+    for (const name of before.entries.keys())
+        if (!compare(name))
+            return undefined;
+    for (const name of after.entries.keys())
+        if (!before.entries.has(name) && !compare(name))
+            return undefined;
     return changes;
 }
 /** Backend names never establish authority to publish a pathname. */
@@ -77,17 +116,194 @@ export function guardedHintChanges(scopes, before, after, hints, observed, limit
         return undefined;
     const result = new Map(observed.map(change => [change.path, change]));
     for (const hint of hints) {
-        // Only publish an independently observed name (including a deletion from
-        // the previous guarded snapshot), or a target explicitly supplied by caller.
-        // A stale/misdirected inode watch may report outside names: erase its detail.
-        if (!before?.entries.has(hint.path) && !after.entries.has(hint.path) && !scopes.some(scope => scope.path === hint.path))
+        // Drop unobserved non-target names only under a parent with the same guarded
+        // identity in both passes; otherwise a stale/misdirected watch erases detail.
+        if (!before?.entries.has(hint.path) && !after.entries.has(hint.path) && !scopes.some(scope => scope.path === hint.path)) {
+            const parent = path.dirname(hint.path);
+            const directory = parent === "." ? "" : parent;
+            const left = before?.directories.get(directory), right = after.directories.get(directory);
+            if (left && right && left.dev === right.dev && left.ino === right.ino)
+                continue;
             return undefined;
+        }
         // Equal snapshots cannot exclude an intermediate change and restoration (ABA).
         // Preserve admitted hints, including setup activity delivered after ready.
-        if (!result.has(hint.path) && result.size >= limit)
+        if (!addChange(result, hint, limit))
             return undefined;
-        const prior = result.get(hint.path);
-        result.set(hint.path, Object.freeze(prior?.type === "structural" ? prior : hint));
+        Object.freeze(result.get(hint.path));
+    }
+    return [...result.values()];
+}
+/** Resolve native spelling aliases without treating case folding as identity. */
+export async function admittedNativeChanges(root, scopes, before, after, batch, signal, limit, scheduling = false) {
+    if (!nativeChanges(scopes, before, batch, limit, after))
+        return undefined;
+    if (scheduling && !batch.hints.length)
+        return undefined;
+    const result = new Map();
+    const candidates = new Map([...before?.targets ?? [], ...after.targets, ...after.directories]);
+    if (scheduling) {
+        const identities = new Map();
+        for (const { dev, ino } of candidates.values()) {
+            let inodes = identities.get(dev);
+            if (!inodes)
+                identities.set(dev, inodes = new Set());
+            // One spelling cannot discard activity selected through another spelling,
+            // including entry targets that alias a tree's directory without registering it.
+            if (inodes.has(ino))
+                return undefined;
+            inodes.add(ino);
+        }
+    }
+    const guards = new Map();
+    const admittedParent = async (parent) => {
+        let guard = guards.get(parent);
+        if (!guard) {
+            const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
+            guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
+            const expected = after.directories.get(parent);
+            if (expected && (guard.stat.dev !== expected.dev || guard.stat.ino !== expected.ino)) {
+                throw new FsSafeError("path-mismatch", "watch hint parent changed during reconciliation");
+            }
+            guards.set(parent, guard);
+        }
+        await assertRootDirectoryObservationGuard(root, guard);
+        signal.throwIfAborted();
+        return guard;
+    };
+    if (scheduling) {
+        // A sibling hint cannot hide a replaced scope anchor or its identity chain.
+        for (const name of after.directories.keys())
+            if (scopes.some(scope => !name || scope.path === name || scope.path.startsWith(name + path.sep)))
+                await admittedParent(name);
+        for (const scope of scopes) {
+            const anchor = after.scopeAnchors?.get(scope.path);
+            if (!anchor)
+                return undefined;
+            if (!anchor.name)
+                continue;
+            const guard = await admittedParent(anchor.directory);
+            const found = await lookupRootDirectoryEntry(root, guard, anchor.name);
+            signal.throwIfAborted();
+            const expected = anchor.target;
+            // Missing targets and vanished/replaced spelling aliases have no hint inode
+            // to match. Recheck the selected spelling before declaring a batch unrelated.
+            if (!found) {
+                if (expected)
+                    return undefined;
+            }
+            else if (!expected || found.identity.dev !== expected.dev || found.identity.ino !== expected.ino ||
+                (found.entry.isSymbolicLink ? "symlink" : found.entry.isDirectory ? "directory" : found.entry.isFile ? "file" : "other") !== expected.kind)
+                return undefined;
+        }
+    }
+    for (const hint of batch.hints) {
+        signal.throwIfAborted();
+        if (hint.event === "subtree") {
+            if (!scheduling)
+                continue; // Only the full guarded snapshot supplies detail.
+            if (selectedWatchSubtree(scopes, hint.directory))
+                return undefined;
+            const guard = await admittedParent(hint.directory);
+            for (const [name, identity] of candidates) {
+                if (identity.dev === guard.stat.dev && identity.ino === guard.stat.ino && selectedWatchSubtree(scopes, name))
+                    return undefined;
+            }
+            continue;
+        }
+        const name = hint.name; // nativeChanges rejected unknown or non-literal names.
+        let parent = hint.directory;
+        const relative = parent ? path.join(parent, name) : name;
+        if (excludedWatchPath(before, relative) || excludedWatchPath(after, relative)) {
+            if (scheduling)
+                return undefined;
+            continue;
+        }
+        let guard;
+        let expected = after.directories.get(parent);
+        if (!expected) {
+            // Native recursion observes one Root handle and may report descendants of
+            // unselected/entry-only directories. Admit a parent alias by exact identity,
+            // not by lowercasing, and do not turn unselected descendants into events.
+            try {
+                guard = await admittedParent(parent);
+            }
+            catch (error) {
+                await assertRootIdentityCurrent(root);
+                if (scheduling)
+                    throw error;
+                if (isNotFoundPathError(error) || (error instanceof FsSafeError && ["not-found", "path-alias", "outside-workspace", "symlink", "not-file"].includes(error.code)))
+                    continue;
+                throw error;
+            }
+            const admitted = [...after.directories].find(([, identity]) => identity.dev === guard.stat.dev && identity.ino === guard.stat.ino);
+            if (!admitted) {
+                // A newly created directory may contain selected entries absent from the baseline.
+                if (scheduling)
+                    return undefined;
+                continue;
+            }
+            [parent, expected] = admitted;
+        }
+        if (scheduling)
+            guard = await admittedParent(parent);
+        if (hint.event === "children") {
+            // There is no child spelling to look up. Only guarded scans may discover it.
+            if (selectedWatchChildren(scopes, parent) && !excludedWatchPath(before, parent) && !excludedWatchPath(after, parent) &&
+                !addChange(result, { path: parent, type: "structural" }, limit))
+                return undefined;
+            continue;
+        }
+        const candidate = parent ? path.join(parent, name) : name;
+        if (excludedWatchPath(before, candidate) || excludedWatchPath(after, candidate)) {
+            if (scheduling)
+                return undefined;
+            continue;
+        }
+        const inspected = scheduling ? await lookupRootDirectoryEntry(root, guard, name) : undefined;
+        signal.throwIfAborted();
+        // A vanished or multiply linked leaf may have changed selected entries in
+        // another directory. Its current spelling cannot prove unrelatedness.
+        if (scheduling && (!inspected || (!inspected.entry.isDirectory && inspected.entry.nlink !== 1)))
+            return undefined;
+        const selected = scopedChanges(scopes, { path: candidate,
+            type: hint.event === "change" && before?.entries.get(candidate)?.startsWith("file:") ? "content" : "structural" });
+        if (selected.length) {
+            for (const change of selected)
+                if (!addChange(result, change, limit))
+                    return undefined;
+            continue;
+        }
+        guard ??= await admittedParent(parent);
+        if (guard.stat.dev !== expected.dev || guard.stat.ino !== expected.ino) {
+            throw new FsSafeError("path-mismatch", "watch hint parent changed during reconciliation");
+        }
+        const found = scheduling ? inspected : await lookupRootDirectoryEntry(root, guard, name);
+        signal.throwIfAborted();
+        // A missing unselected sibling is not evidence of lost selected detail.
+        // Previously observed selected deletions remain visible in the snapshot diff;
+        // an unseen, already-gone name has no identity proving a selected alias.
+        if (!found)
+            continue;
+        if (scheduling && found.entry.isSymbolicLink)
+            return undefined;
+        for (const [relative, identity] of candidates) {
+            if (!relative || identity.dev !== found.identity.dev || identity.ino !== found.identity.ino)
+                continue;
+            if ((path.dirname(relative) === "." ? "" : path.dirname(relative)) !== parent) {
+                if (scheduling)
+                    return undefined;
+                continue;
+            }
+            for (const change of scopedChanges(scopes, { path: relative, type: "structural" }))
+                if (!addChange(result, change, limit))
+                    return undefined;
+        }
+        await assertRootDirectoryObservationGuard(root, guard);
     }
+    for (const guard of guards.values())
+        await assertRootDirectoryObservationGuard(root, guard);
+    await assertRootIdentityCurrent(root);
+    signal.throwIfAborted();
     return [...result.values()];
 }

package/node_modules/@openclaw/fs-safe/dist/watch-native.d.ts

@@ -1,11 +1,11 @@
 import { type NativeBinding } from "./native.js";
 import type { RootContext } from "./root-context.js";
-import type { DirectoryIdentity } from "./watch-scan.js";
+import type { DirectoryIdentity, WatchSnapshot } from "./watch-scan.js";
 import type { WatchStreamPaths } from "./watch-stream.js";
 export type NativeWatchHint = {
     directory: string;
     name: string;
-    event: "rename" | "change";
+    event: "rename" | "change" | "children" | "subtree";
 };
 export type NativeWatchBatch = {
     hints: NativeWatchHint[];
@@ -18,19 +18,38 @@ export type NativeWatchWireBatch = {
         name: string;
         structural: boolean;
         flags?: number;
+        namelessChild?: boolean;
+        subtree?: boolean;
     }[];
     overflow: boolean;
     error?: string;
 };
+export type NativeWatchEntry = {
+    scope: string;
+    directory: {
+        root: string;
+        relative: string;
+        rootDev: bigint;
+        rootIno: bigint;
+        dev: bigint;
+        ino: bigint;
+    };
+    name: string;
+    target?: DirectoryIdentity & {
+        kind: string;
+    };
+};
 export declare function watchBinding(mode: "auto" | "events" | "poll"): NativeBinding | undefined;
 export declare class NativeWatchBackend {
     private binding;
     private root;
     private id;
     private streamPaths;
+    directories: number | undefined;
     constructor(binding: NativeBinding, root: RootContext, callback: (batch: NativeWatchBatch) => void, limit: number, persistent: boolean);
     add(name: string, identity: DirectoryIdentity): void;
     testEvent(path: string, flags: number): void;
+    entries(snapshot: WatchSnapshot): boolean;
     configure(paths: WatchStreamPaths): boolean;
     close(): void;
 }

package/node_modules/@openclaw/fs-safe/dist/watch-native.js

@@ -6,7 +6,7 @@ export function watchBinding(mode) {
         return;
     const binding = getNativeBinding(); // Preserves require + missing-addon failure.
     // Bun TSFN teardown remains unqualified; guarded native scans remain usable.
-    if (binding?.watchRegister && (process.platform !== "darwin" || binding.watchConfigure) && !process.versions.bun && !process.versions.deno && ["linux", "darwin", "win32"].includes(process.platform))
+    if (binding?.watchRegister && (process.platform !== "darwin" || (binding.watchConfigure && binding.watchEntries)) && !process.versions.bun && !process.versions.deno && ["linux", "darwin", "win32"].includes(process.platform))
         return binding;
     if (mode === "events" || getFsSafeNativeConfig().mode === "require") {
         throw new FsSafeError("helper-unavailable", "native watch events are unavailable", { details: { operation: "watch" } });
@@ -17,15 +17,16 @@ export class NativeWatchBackend {
     root;
     id;
     streamPaths;
+    directories;
     constructor(binding, root, callback, limit, persistent) {
         this.binding = binding;
         this.root = root;
-        this.streamPaths = JSON.stringify({ anchors: [root.rootReal], exclusions: [] });
+        this.streamPaths = JSON.stringify({ anchors: [], exclusions: [] });
         try {
             this.id = binding.watchRegister(root.rootReal, limit, batch => {
                 if (this.id !== undefined)
                     callback({ overflow: batch.overflow, error: batch.error, hints: batch.hints.map(hint => ({
-                            directory: hint.directory, name: hint.name, event: hint.structural ? "rename" : "change",
+                            directory: hint.directory, name: hint.name, event: hint.subtree ? "subtree" : hint.namelessChild ? "children" : hint.structural ? "rename" : "change",
                         })) });
             }, persistent);
         }
@@ -43,6 +44,23 @@ export class NativeWatchBackend {
         }
     }
     testEvent(path, flags) { this.binding.watchTestEvent(this.id, path, flags); }
+    entries(snapshot) {
+        if (process.platform !== "darwin")
+            return false;
+        const entries = [...snapshot.entryAnchors ?? []].map(([scope, anchor]) => ({
+            scope, name: anchor.name, target: anchor.target,
+            directory: { root: this.root.rootReal, relative: anchor.directory,
+                rootDev: BigInt(this.root.rootIdentity.dev), rootIno: BigInt(this.root.rootIdentity.ino), ...snapshot.directories.get(anchor.directory) },
+        }));
+        try {
+            const result = this.binding.watchEntries(this.id, entries);
+            this.directories = result.directories;
+            return result.changed;
+        }
+        catch (cause) {
+            throw watchError(cause);
+        }
+    }
     configure(paths) {
         if (process.platform !== "darwin")
             return false;

package/node_modules/@openclaw/fs-safe/dist/watch-rescan.d.ts

@@ -0,0 +1,6 @@
+import type { WatchChange, WatchScope } from "./watch-types.js";
+import type { WatchSnapshot } from "./watch-scan.js";
+/** Only previously enumerated directories can be reconciled without discovering topology. */
+export declare function watchRescanScopes(scopes: readonly WatchScope[], snapshot: WatchSnapshot, changes: readonly WatchChange[]): readonly WatchScope[] | undefined;
+/** Merge only freshly observed slices. Any topology/anchor ambiguity requires a full pass. */
+export declare function mergeWatchRescan(scopes: readonly WatchScope[], before: WatchSnapshot, slice: WatchSnapshot, requested: readonly WatchScope[]): WatchSnapshot | undefined;