@openclaw/feishu 2026.9.8 → 2026.10.1-beta.2

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

@@ -0,0 +1,111 @@
+import path from "node:path";
+const parent = (name) => path.dirname(name) === "." ? "" : path.dirname(name);
+const below = (directory, name) => !directory || name.startsWith(directory + path.sep);
+const identity = (fingerprint) => fingerprint?.split(":").slice(0, 3).join(":");
+/** Only previously enumerated directories can be reconciled without discovering topology. */
+export function watchRescanScopes(scopes, snapshot, changes) {
+    if (scopes.some((scope, index) => scope.kind === "tree" && scope.depth > 0 && scopes.some((other, next) => index !== next && (scope.path === other.path || below(scope.path, other.path)))))
+        return;
+    const directories = new Set();
+    for (const change of changes) {
+        // A directory hint can cover descendant edits and new native registrations.
+        if (snapshot.listed?.has(change.path))
+            return undefined;
+        if (scopes.some(scope => scope.path === change.path && scope.kind === "tree" && scope.depth > 0))
+            return undefined;
+        if (scopes.some(scope => scope.path === change.path))
+            continue;
+        const directory = parent(change.path);
+        if (!snapshot.listed?.has(directory))
+            return undefined;
+        directories.add(directory);
+    }
+    return [
+        ...scopes.map(scope => ({ ...scope, depth: 0 })),
+        ...[...directories].map(name => ({ path: name, kind: "tree", depth: 1 })),
+    ];
+}
+/** Merge only freshly observed slices. Any topology/anchor ambiguity requires a full pass. */
+export function mergeWatchRescan(scopes, before, slice, requested) {
+    if (slice.overflow || slice.structural?.size)
+        return;
+    // An exclusion or a blocked path may stop before a requested directory is listed.
+    for (const scope of requested)
+        if (scope.kind === "tree" && scope.depth > 0 && !slice.listed?.has(scope.path))
+            return;
+    for (const [name, current] of slice.directories) {
+        const prior = before.directories.get(name);
+        if (!prior || prior.dev !== current.dev || prior.ino !== current.ino)
+            return;
+    }
+    for (const scope of scopes) {
+        if (identity(before.entries.get(scope.path)) !== identity(slice.entries.get(scope.path)))
+            return;
+        // A missing/blocked intermediate scope must not retain old descendant registrations.
+        for (const name of before.directories.keys())
+            if ((name === scope.path || below(name, scope.path)) &&
+                !slice.directories.has(name) && name !== scope.path)
+                return;
+    }
+    const directories = slice.listed;
+    const selected = new Set(scopes.map(scope => scope.path));
+    for (const directory of directories.keys()) {
+        for (const name of before.childPaths?.get(directory)?.values() ?? [])
+            selected.add(name);
+        for (const name of slice.childPaths?.get(directory)?.values() ?? [])
+            selected.add(name);
+    }
+    for (const [name, previous] of before.entries) {
+        if (!selected.has(name))
+            continue;
+        const current = slice.entries.get(name);
+        if ((previous.startsWith("directory:") || current?.startsWith("directory:")) && identity(previous) !== identity(current))
+            return;
+    }
+    for (const [name, current] of slice.entries) {
+        if (selected.has(name) && current.startsWith("directory:") && identity(current) !== identity(before.entries.get(name)))
+            return;
+    }
+    // Exclusion changes can retire or admit a subtree, including callback-driven changes.
+    for (const [name, kind] of before.excluded ?? [])
+        if (selected.has(name) && kind === "directory" && slice.entries.has(name))
+            return;
+    const entries = new Map(before.entries);
+    for (const name of selected)
+        if (!slice.entries.has(name))
+            entries.delete(name);
+    for (const [name, value] of slice.entries)
+        if (selected.has(name))
+            entries.set(name, value);
+    const excluded = new Map(before.excluded), excludedDirectories = new Map(before.excludedDirectories);
+    for (const name of selected) {
+        excluded.delete(name);
+        excludedDirectories.delete(name);
+    }
+    for (const [name, kind] of slice.excluded ?? [])
+        if (selected.has(name)) {
+            excluded.set(name, kind);
+            const canonical = slice.excludedDirectories?.get(name);
+            if (canonical)
+                excludedDirectories.set(name, canonical);
+        }
+    const listed = new Map(before.listed);
+    let scanned = before.scanned;
+    for (const [name, count] of directories) {
+        scanned += count - (listed.get(name) ?? 0);
+        listed.set(name, count);
+    }
+    return { ...before, entries, excluded, excludedDirectories, listed, scanned,
+        entryAnchors: slice.entryAnchors,
+        scopeAnchors: new Map(scopes.flatMap(scope => {
+            const anchor = slice.scopeAnchors?.get(scope.path);
+            return anchor ? [[scope.path, anchor]] : [];
+        })),
+        directoryPaths: new Map([...before.directoryPaths ?? [], ...slice.directoryPaths ?? []]),
+        childPaths: new Map([...before.childPaths ?? [], ...slice.childPaths ?? []]),
+        listingPaths: new Map([...before.listingPaths ?? [], ...slice.listingPaths ?? []]),
+        targets: new Map(scopes.flatMap(scope => {
+            const target = slice.targets.get(scope.path);
+            return target ? [[scope.path, target]] : [];
+        })), structural: slice.structural, overflow: false, };
+}

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

@@ -1,12 +1,21 @@
 import { type RootContext } from "./root-context.js";
 import { type RootDirectoryObservationGuard } from "./root-directory-list.js";
+import type { RootDirectoryListingPaths } from "./root-directory-list-types.js";
 import type { WatchEntry, WatchOptions, WatchScope } from "./watch-types.js";
 export type DirectoryIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
 }>;
+export type WatchEntryAnchor = {
+    directory: string;
+    name: string;
+    target?: DirectoryIdentity & {
+        kind: WatchEntry["kind"];
+    };
+};
 export type WatchSnapshot = {
     entries: Map<string, string>;
+    entryAnchors?: Map<string, WatchEntryAnchor>;
     excluded?: Map<string, WatchEntry["kind"]>;
     excludedDirectories?: Map<string, string>;
     directoryPaths?: Map<string, string>;
@@ -15,6 +24,10 @@ export type WatchSnapshot = {
     scanned: number;
     structural?: Set<string>;
     overflow?: boolean;
+    scopeAnchors?: Map<string, WatchEntryAnchor>;
+    listed?: Map<string, number>;
+    childPaths?: Map<string, Map<string, string>>;
+    listingPaths?: Map<string, RootDirectoryListingPaths>;
 };
 export declare function watchScopes(input: readonly WatchScope[]): readonly WatchScope[];
 /** A descendant's unavailable metadata never grants it authority or retires the Root. */

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

@@ -57,7 +57,10 @@ export function isWatchPathError(error) {
 export async function scanWatch(root, scopes, options, signal, register, onCleanupFailure) {
     const exclusions = new Map();
     const excludedDirectories = new Map(), directoryPaths = new Map();
-    const result = { entries: new Map(), excluded: exclusions, excludedDirectories, directoryPaths, directories: new Map(), targets: new Map(), scanned: 0 };
+    const entryAnchors = new Map();
+    const scopeAnchors = new Map();
+    const listed = new Map(), childPaths = new Map(), listingPaths = new Map();
+    const result = { entries: new Map(), entryAnchors, scopeAnchors, excluded: exclusions, excludedDirectories, directoryPaths, directories: new Map(), targets: new Map(), scanned: 0, listed, childPaths, listingPaths };
     const attempts = new Map();
     const guards = new Map();
     const walked = new Map();
@@ -70,7 +73,11 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
             result.overflow = true;
         // Discard partially observed names when their enclosing directory lost admission.
         const below = (name) => name === relative || !relative || name.startsWith(relative + path.sep);
-        for (const map of [result.entries, exclusions, excludedDirectories, directoryPaths, result.targets, result.directories, guards, walked]) {
+        for (const anchors of [entryAnchors, scopeAnchors])
+            for (const [scope, anchor] of anchors)
+                if (below(anchor.directory))
+                    anchors.delete(scope);
+        for (const map of [result.entries, exclusions, excludedDirectories, directoryPaths, result.targets, result.directories, guards, walked, listed, childPaths, listingPaths]) {
             for (const name of map.keys())
                 if (below(name))
                     map.delete(name);
@@ -167,8 +174,11 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         for (let attempt = 0; attempt < 3; attempt++) {
             try {
                 guard = await directory(relative);
+                listed.set(relative, 0);
                 listing = await openRootDirectoryListing(root, guard.realPath, {
-                    order: "filesystem", snapshot: false, signal, exactIdentity: true, skipVanished: true, onCleanupFailure, admitEntry: () => { examined(); return true; },
+                    order: "filesystem", snapshot: false, signal, exactIdentity: true, skipVanished: true, onCleanupFailure,
+                    previousPaths: options.previous?.listingPaths?.get(relative),
+                    admitEntry: () => { examined(); listed.set(relative, (listed.get(relative) ?? 0) + 1); return true; },
                 });
                 // The listing has its own guard. Both identities must agree before reading names.
                 await assertRootDirectoryObservationGuard(root, guard);
@@ -182,6 +192,10 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         }
         if (!listing)
             return;
+        listingPaths.set(relative, listing.paths);
+        const names = new Map();
+        childPaths.set(relative, names);
+        const previousNames = options.previous?.childPaths?.get(relative);
         let failed = false;
         let operationError;
         try {
@@ -195,7 +209,8 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                 if (!next.identity)
                     throw new FsSafeError("path-mismatch", "watch listing lacks exact identity");
                 const entry = next.entry;
-                const name = relative ? path.join(relative, entry.name) : entry.name;
+                const name = previousNames?.get(entry.name) ?? (relative ? path.join(relative, entry.name) : entry.name);
+                names.set(entry.name, name);
                 if (await excluded(name, entry))
                     continue;
                 result.entries.set(name, fingerprint(entry, next.identity));
@@ -231,6 +246,9 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         signal.throwIfAborted();
         if (!scope.path) {
             const guard = await directory("");
+            scopeAnchors.set(scope.path, { directory: "", name: "" });
+            if (scope.kind === "entry")
+                entryAnchors.set(scope.path, { directory: "", name: "" });
             result.entries.set("", fingerprint({ name: "", ...pathStatFromStats(guard.stat) }, guard.stat));
             if (scope.kind === "tree" && scope.depth > 0)
                 await tree("", scope.depth);
@@ -241,6 +259,10 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         try {
             for (let i = 0; i < segments.length; i++) {
                 const guard = await directory(relative);
+                const anchor = { directory: relative, name: segments[i] };
+                scopeAnchors.set(scope.path, anchor);
+                if (scope.kind === "entry")
+                    entryAnchors.set(scope.path, anchor);
                 examined();
                 // Filesystem lookup, not lowercase/prefix matching, owns case, Unicode and
                 // short-name aliases. It also preserves case-sensitive Windows directories.
@@ -251,6 +273,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                 const name = relative ? path.join(relative, segments[i]) : segments[i];
                 if (await excluded(name, found.entry))
                     break;
+                anchor.target = { ...found.identity, kind: kind(found.entry) };
                 if (i === segments.length - 1) {
                     result.entries.set(name, fingerprint(found.entry, found.identity));
                     result.targets.set(name, found.identity);

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

@@ -15,6 +15,8 @@ function shallowest(paths, limit) {
 export function watchStreamPaths(snapshot, scopes) {
     const anchors = [];
     for (const scope of scopes) {
+        if (scope.kind === "entry")
+            continue;
         let name = scope.kind === "tree" && scope.depth !== 0 ? scope.path : path.dirname(scope.path);
         if (name === ".")
             name = "";

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

@@ -4,9 +4,9 @@ import { assertRootIdentityCurrent } from "./root-context.js";
 import { rootHandleContext } from "./root-handle-context.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { admittedNativeChanges } from "./watch-alias.js";
+import { mergeWatchRescan, watchRescanScopes } from "./watch-rescan.js";
 import { watchStreamPaths } from "./watch-stream.js";
-import { changedEntries, excludedWatchPath, guardedHintChanges, scopedChanges } from "./watch-hints.js";
+import { admittedNativeChanges, changedEntries, excludedWatchPath, guardedHintChanges, scopedChanges } from "./watch-hints.js";
 import path from "node:path";
 import { watchBinding, NativeWatchBackend } from "./watch-native.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
@@ -60,6 +60,7 @@ export function watch(root, input) {
     const maxPendingPaths = budget(options.maxPendingPaths, 256, "maxPendingPaths", 4096);
     if (typeof options.onInvalidate !== "function")
         throw new TypeError("watch requires onInvalidate");
+    const callerSignal = options.signal ? AbortSignal.any([options.signal]) : undefined;
     const makeGeneration = (scopes) => ({
         scopes: watchScopes(scopes), abort: new AbortController(), waiter: deferred(),
     });
@@ -80,6 +81,8 @@ export function watch(root, input) {
     let resetRequested = false;
     let refreshBackend = false;
     let pending = false;
+    let fullRequested = false;
+    let pendingUncertain = false;
     let pendingWaiter;
     let runningWaiter;
     let pendingHint = false;
@@ -126,6 +129,7 @@ export function watch(root, input) {
         pendingHint = false;
         pendingChanges = new Map();
         pendingBackendOverflow = false;
+        pendingUncertain = false;
     };
     const notifyHealth = () => {
         try {
@@ -203,7 +207,7 @@ export function watch(root, input) {
         }
     };
     const scheduleInterval = () => {
-        if (terminal || failure !== undefined)
+        if (timer || fullRequested || terminal || failure !== undefined)
             return;
         timer = setTimeout(() => { timer = undefined; void request().catch(() => { }); }, intervalMs);
         if (!persistent)
@@ -232,16 +236,27 @@ export function watch(root, input) {
             pendingChanges = undefined;
         else if (pendingChanges)
             for (const hint of batch.hints) {
-                if (typeof hint.name === "string" && excludedWatchPath(snapshot, hint.directory ? path.join(hint.directory, hint.name) : hint.name))
+                if (hint.event === "rename")
+                    pendingUncertain = true;
+                if (typeof hint.name === "string" && excludedWatchPath(snapshot, hint.directory ? path.join(hint.directory, hint.name) : hint.name)) {
+                    pendingUncertain = true;
+                    continue;
+                }
+                // Multiple bounded native batches can still fill the JS coalescing window.
+                // A Root fold retains discovery while letting the guarded diff own detail.
+                if (pendingChanges.get("subtree-root")?.event === "subtree")
                     continue;
-                const key = JSON.stringify([hint.directory, hint.name]);
+                const key = JSON.stringify([hint.directory, hint.name, hint.event === "children" || hint.event === "subtree" ? hint.event : "entry"]);
                 if (!pendingChanges.has(key) && pendingChanges.size >= maxPendingPaths) {
-                    pendingChanges = undefined;
+                    pendingChanges.clear();
+                    pendingChanges.set("subtree-root", { directory: "", name: "", event: "subtree" });
                     break;
                 }
                 const previous = pendingChanges.get(key);
                 pendingChanges.set(key, previous?.event === "rename" ? previous : hint);
             }
+        if (!batch.hints.length)
+            pendingUncertain = true;
         pendingHint = true;
         pending = true;
         if (hintTimer)
@@ -251,7 +266,7 @@ export function watch(root, input) {
             if (terminal || current !== g || failure !== undefined)
                 return;
             // Raw backend filenames stay private. Reconcile before publishing detail.
-            void request().catch(() => { });
+            void request(false).catch(() => { });
         }, coalesceMs);
         if (!persistent)
             hintTimer.unref();
@@ -273,6 +288,7 @@ export function watch(root, input) {
             await retireBackend();
             check(g);
             refreshBackend = false;
+            fullRequested = true;
         }
         if (resetRequested) {
             await retireBackend();
@@ -280,17 +296,40 @@ export function watch(root, input) {
             snapshot = undefined;
             resetRequested = false;
         }
-        state = snapshot ? "reconciling" : "starting";
-        notifyHealth();
-        check(g);
         const hadHints = pendingHint;
         const hadBackendOverflow = pendingBackendOverflow;
         const hints = pendingChanges;
+        const full = fullRequested || pendingUncertain;
+        fullRequested = false;
+        pendingUncertain = false;
         pendingHint = false;
         pendingChanges = new Map();
         pendingBackendOverflow = false;
         clearTimeout(hintTimer);
         hintTimer = undefined;
+        let scanScopes = g.scopes;
+        if (snapshot && hadHints && hints && !full) {
+            try {
+                const admitted = await admittedNativeChanges(context, g.scopes, snapshot, snapshot, {
+                    hints: [...hints.values()], overflow: false,
+                }, g.abort.signal, maxPendingPaths, true);
+                check(g);
+                if (admitted?.length === 0)
+                    return;
+                if (admitted)
+                    scanScopes = watchRescanScopes(g.scopes, snapshot, admitted) ?? g.scopes;
+            }
+            catch (error) {
+                check(g);
+                await assertRootIdentityCurrent(context);
+                if (!isWatchPathError(error))
+                    throw error;
+                // An uncertain alias or stale identity never suppresses reconciliation.
+            }
+        }
+        state = snapshot ? "reconciling" : "starting";
+        notifyHealth();
+        check(g);
         if (mode === "events" && !backend && g.scopes.length) {
             try {
                 const candidate = new NativeWatchBackend(binding, context, batch => {
@@ -312,38 +351,83 @@ export function watch(root, input) {
             }
             check(g);
         }
-        const next = await scanWatch(context, g.scopes, { exclude: options.exclude, maxDirectories, maxEntries, maxPendingPaths, admitting: !snapshot, previous: snapshot }, g.abort.signal, async (name, identity, guard) => {
-            check(g);
-            const existing = registered.get(name);
-            const acquire = !existing || existing.dev !== identity.dev || existing.ino !== identity.ino;
-            await getFsSafeTestHooks()?.beforeWatchRegistration?.(guard.realPath);
-            check(g);
-            if (acquire) {
-                try {
-                    backend?.add(name, identity);
-                }
-                catch (error) {
-                    if (snapshot || !fallBack(error))
-                        throw error;
-                    await retireBackend();
+        let next;
+        for (let attempt = 0;; attempt++) {
+            if (scanScopes === g.scopes) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            try {
+                next = await scanWatch(context, scanScopes, { exclude: options.exclude, maxDirectories, maxEntries, maxPendingPaths, admitting: !snapshot, previous: snapshot }, g.abort.signal, async (name, identity, guard) => {
+                    check(g);
+                    const existing = registered.get(name);
+                    const acquire = !existing || existing.dev !== identity.dev || existing.ino !== identity.ino;
+                    await getFsSafeTestHooks()?.beforeWatchRegistration?.(guard.realPath);
+                    check(g);
+                    if (acquire) {
+                        try {
+                            backend?.add(name, identity);
+                        }
+                        catch (error) {
+                            if (snapshot || !fallBack(error))
+                                throw error;
+                            await retireBackend();
+                            check(g);
+                        }
+                    }
+                    await getFsSafeTestHooks()?.afterWatchRegistration?.(guard.realPath);
                     check(g);
+                    if (acquire)
+                        registered.set(name, identity);
+                }, retainRetirement);
+            }
+            catch (error) {
+                // A slice can repeat ancestor lookups that a full traversal shares.
+                // Let the authoritative full pass decide whether the configured limit is exceeded.
+                if (scanScopes !== g.scopes && error instanceof FsSafeError && error.code === "too-large") {
+                    scanScopes = g.scopes;
+                    continue;
                 }
+                throw error;
             }
-            await getFsSafeTestHooks()?.afterWatchRegistration?.(guard.realPath);
             check(g);
-            if (acquire)
-                registered.set(name, identity);
-        }, retainRetirement);
-        check(g);
-        if (backend?.configure(watchStreamPaths(next, g.scopes))) {
-            // The replacement stream is live before the next guarded pass covers the handover.
-            pending = true;
+            if (scanScopes !== g.scopes) {
+                const merged = mergeWatchRescan(g.scopes, snapshot, next, scanScopes);
+                if (!merged || merged.scanned > maxEntries || merged.directories.size > maxDirectories || (merged.excluded?.size ?? 0) > maxEntries) {
+                    scanScopes = g.scopes;
+                    continue;
+                }
+                next = merged;
+            }
+            try {
+                const entriesChanged = backend?.entries(next);
+                const streamsChanged = backend?.configure(watchStreamPaths(next, g.scopes));
+                if (entriesChanged || streamsChanged) {
+                    // Complete a guarded pass with the new transport before publishing readiness.
+                    // Bound handovers under churn; later passes still reconcile ongoing changes.
+                    scanScopes = g.scopes;
+                    if (attempt < 2)
+                        continue;
+                    pending = true;
+                    fullRequested = true;
+                }
+                break;
+            }
+            catch (error) {
+                await assertRootIdentityCurrent(context);
+                check(g);
+                if (attempt >= 2 || !isWatchPathError(error))
+                    throw error;
+                scanScopes = g.scopes;
+                // A replacement between scan and descriptor admission requires a fresh identity.
+            }
         }
         // Retire stale inventory before the next pass; that crawl installs fresh anchors first.
         if ([...registered.keys()].some(name => !next.directories.has(name))) {
             refreshBackend = true;
         }
-        observedDirectories = next.directories.size;
+        observedDirectories = backend?.directories === undefined ? next.directories.size
+            : backend.directories + (g.scopes.some(scope => scope.kind === "tree") ? next.directories.size : 0);
         const initial = !snapshot;
         let observed = next.overflow ? undefined : changedEntries(snapshot, next, maxPendingPaths);
         if (observed) {
@@ -384,6 +468,8 @@ export function watch(root, input) {
         state = "ready";
         notifyHealth();
         check(g);
+        // Rearm even when sustained hints keep the pump's coalesced request occupied.
+        scheduleInterval();
     };
     const pump = () => {
         if (active || terminal || failure !== undefined)
@@ -435,13 +521,16 @@ export function watch(root, input) {
             }
         });
     };
-    const request = () => {
+    const request = (full = true) => {
         if (terminal)
             return Promise.reject(retired());
         if (failure !== undefined)
             return Promise.reject(failure);
-        clearTimeout(timer);
-        timer = undefined;
+        if (full) {
+            clearTimeout(timer);
+            timer = undefined;
+            fullRequested = true;
+        }
         pending = true;
         pendingWaiter ??= deferred();
         const result = pendingWaiter.promise;
@@ -459,7 +548,8 @@ export function watch(root, input) {
         pendingWaiter = undefined;
         runningWaiter = undefined;
         clearTimers();
-        options.signal?.removeEventListener("abort", abort);
+        if (callerSignal)
+            callerSignal.onabort = null;
         // Start physical stop immediately, without waiting behind an in-flight scan.
         try {
             backend?.close();
@@ -485,7 +575,7 @@ export function watch(root, input) {
     const abort = () => { void close(); };
     const subscription = {
         ready, health, close, [Symbol.asyncDispose]: close,
-        reconcile: request,
+        reconcile: () => request(),
         setScopes(scopes) {
             if (terminal)
                 return Promise.reject(retired());
@@ -521,8 +611,9 @@ export function watch(root, input) {
             return next.waiter.promise;
         },
     };
-    options.signal?.addEventListener("abort", abort, { once: true });
-    if (options.signal?.aborted)
+    if (callerSignal)
+        callerSignal.onabort = abort;
+    if (callerSignal?.aborted)
         abort();
     else
         pump();

package/node_modules/@openclaw/fs-safe/dist/windows-path-alias.d.ts

@@ -1,5 +1,13 @@
 import { FsSafeError } from "./errors.js";
 export type WindowsPathAliasKind = "filesystem" | "relative";
+/**
+ * True when a Windows path could reach a UNC share or device namespace that
+ * none of the trusted boundary paths live on: its share or device differs from
+ * theirs or cannot be identified from its spelling, and it is not spelled
+ * exactly under one of them. Reject such input before any filesystem call:
+ * even lstat on `\\host\share\x` makes Windows contact host.
+ */
+export declare function isForeignWindowsShareOrDevicePath(value: string, trustedPaths: readonly (string | undefined)[], platform?: NodeJS.Platform | string): boolean;
 /**
  * Capture an ordinary Windows drive-relative path without normalizing its raw
  * suffix. This is only for public APIs whose existing contract accepts such

package/node_modules/@openclaw/fs-safe/dist/windows-path-alias.js

@@ -1,6 +1,28 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { hasWindowsDrivePrefix, rootedWindowsDriveColonIndex, windowsNamespaceMarker, } from "./windows-path-syntax.js";
+import { hasWindowsDrivePrefix, rootedWindowsDriveColonIndex, windowsNamespaceMarker, windowsSegmentsClimbAbove, windowsShareOrDeviceRoot, } from "./windows-path-syntax.js";
+function isExactlyUnderWindowsPath(trusted, value) {
+    const root = trusted.replaceAll("/", "\\").replace(/(?<=.)\\+$/, "");
+    const candidate = value.replaceAll("/", "\\");
+    if (candidate !== root && !candidate.startsWith(root.endsWith("\\") ? root : `${root}\\`))
+        return false;
+    return !windowsSegmentsClimbAbove(candidate.slice(root.length).split("\\"));
+}
+/**
+ * True when a Windows path could reach a UNC share or device namespace that
+ * none of the trusted boundary paths live on: its share or device differs from
+ * theirs or cannot be identified from its spelling, and it is not spelled
+ * exactly under one of them. Reject such input before any filesystem call:
+ * even lstat on `\\host\share\x` makes Windows contact host.
+ */
+export function isForeignWindowsShareOrDevicePath(value, trustedPaths, platform = process.platform) {
+    if (platform !== "win32")
+        return false;
+    const key = windowsShareOrDeviceRoot(value);
+    if (key === undefined)
+        return false;
+    return !trustedPaths.some(trusted => trusted !== undefined && ((key !== null && windowsShareOrDeviceRoot(trusted) === key) || isExactlyUnderWindowsPath(trusted, value)));
+}
 function isBareWindowsNamespaceDrive(value) {
     return value.length === 6 && windowsNamespaceMarker(value) !== undefined &&
         hasWindowsDrivePrefix(value, 4);
@@ -106,11 +128,7 @@ export function assertNoWindowsPathAliasForPlatform(value, kind, message, platfo
     }
 }
 export function assertNoWindowsPathAlias(value, kind = "filesystem", message = "path uses a Windows filesystem namespace alias", platform = process.platform) {
-    if (hasWindowsPathAlias(value, kind, platform)) {
-        throw new FsSafeError("invalid-path", message, {
-            details: { reason: "windows-path-alias" },
-        });
-    }
+    assertNoWindowsPathAliasForPlatform(value, kind, message, platform);
 }
 export function isWindowsPathAliasError(error) {
     return error instanceof FsSafeError && error.details?.reason === "windows-path-alias";

package/node_modules/@openclaw/fs-safe/dist/windows-path-syntax.d.ts

@@ -3,3 +3,16 @@ export declare function hasWindowsDrivePrefix(value: string, offset?: number): b
 /** Classify a raw prefix without normalizing any path components. */
 export declare function windowsNamespaceMarker(value: string): "." | "?" | undefined;
 export declare function rootedWindowsDriveColonIndex(value: string): number;
+/**
+ * True when dot-like components climb above the start of `segments`. Win32
+ * trims trailing dots and spaces, so any all-dot or all-space component other
+ * than `.` is counted as a parent step.
+ */
+export declare function windowsSegmentsClimbAbove(segments: readonly string[]): boolean;
+/**
+ * Comparable share or device root of a path spelled with two leading
+ * separators, excluding namespaced drive roots such as `\\?\C:\`.
+ * Returns undefined for drive, rooted, and relative spellings, and null when
+ * the spelling alone cannot establish which share or device it reaches.
+ */
+export declare function windowsShareOrDeviceRoot(value: string): string | null | undefined;