@openclaw/signal 2026.11.3 → 2026.11.5-beta.2

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

@@ -1,3 +1,4 @@
+import { watchYield } from "./watch-io.js";
 import path from "node:path";
 const parent = (name) => path.dirname(name) === "." ? "" : path.dirname(name);
 const below = (directory, name) => !directory || name.startsWith(directory + path.sep);
@@ -26,14 +27,32 @@ export function watchRescanScopes(scopes, snapshot, changes) {
     ];
 }
 /** 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)
+export async function mergeWatchRescan(scopes, before, slice, requested) {
+    const checkpoint = watchYield();
+    const copy = async (entries) => {
+        const result = new Map();
+        for (const [key, value] of entries ?? []) {
+            result.set(key, value);
+            await checkpoint();
+        }
+        return result;
+    };
+    const combine = async (left, right) => {
+        const result = await copy(left);
+        for (const [key, value] of right ?? []) {
+            result.set(key, value);
+            await checkpoint();
+        }
+        return result;
+    };
+    if (before.overflow || before.structural?.size || 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) {
+        await checkpoint();
         const prior = before.directories.get(name);
         if (!prior || prior.dev !== current.dev || prior.ino !== current.ino)
             return;
@@ -42,62 +61,105 @@ export function mergeWatchRescan(scopes, before, slice, requested) {
         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)
+        for (const name of before.directories.keys()) {
+            await checkpoint();
+            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() ?? [])
+        for (const name of before.childPaths?.get(directory)?.values() ?? []) {
             selected.add(name);
-        for (const name of slice.childPaths?.get(directory)?.values() ?? [])
+            await checkpoint();
+        }
+        for (const name of slice.childPaths?.get(directory)?.values() ?? []) {
             selected.add(name);
+            await checkpoint();
+        }
     }
     for (const name of selected) {
+        await checkpoint();
         const previous = before.entries.get(name), current = slice.entries.get(name);
         if ((previous?.startsWith("directory:") || current?.startsWith("directory:")) && identity(previous) !== identity(current))
             return;
     }
     // Exclusion changes can retire or admit a subtree, including callback-driven changes.
-    for (const [name, kind] of before.excluded ?? [])
+    for (const [name, kind] of before.excluded ?? []) {
+        await checkpoint();
         if (selected.has(name) && kind === "directory" && slice.entries.has(name))
             return;
-    const entries = new Map(before.entries);
-    for (const name of selected)
+    }
+    const entries = await copy(before.entries);
+    for (const name of selected) {
+        await checkpoint();
         if (!slice.entries.has(name))
             entries.delete(name);
-    for (const [name, value] of slice.entries)
+    }
+    for (const [name, value] of slice.entries) {
+        await checkpoint();
         if (selected.has(name))
             entries.set(name, value);
-    const excluded = new Map(before.excluded), excludedDirectories = new Map(before.excludedDirectories);
+    }
+    const excluded = await copy(before.excluded), excludedDirectories = await copy(before.excludedDirectories);
     for (const name of selected) {
+        await checkpoint();
         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);
+    for (const [name, kind] of slice.excluded ?? []) {
+        await checkpoint();
+        if (!selected.has(name))
+            continue;
+        excluded.set(name, kind);
+        const canonical = slice.excludedDirectories?.get(name);
+        if (canonical)
+            excludedDirectories.set(name, canonical);
+    }
+    const listed = await copy(before.listed);
     let scanned = before.scanned;
     for (const [name, count] of directories) {
+        await checkpoint();
         scanned += count - (listed.get(name) ?? 0);
         listed.set(name, count);
     }
-    return { ...before, entries, excluded, excludedDirectories, listed, scanned,
+    const observations = before.observations && slice.observations ? await copy(before.observations) : undefined;
+    if (observations) {
+        for (const name of selected) {
+            await checkpoint();
+            if (!slice.observations.has(name))
+                observations.delete(name);
+        }
+        for (const [name, observation] of slice.observations) {
+            await checkpoint();
+            // A parent's listing can observe a child's new timestamps without reading
+            // its children. Keep the old stamp until that directory is actually listed.
+            if (before.listed?.has(name) && !directories.has(name))
+                continue;
+            observations.set(name, observation);
+        }
+    }
+    const unsettled = new Set();
+    for (const name of before.unsettled ?? []) {
+        await checkpoint();
+        if (!directories.has(name))
+            unsettled.add(name);
+    }
+    for (const name of slice.unsettled ?? []) {
+        await checkpoint();
+        unsettled.add(name);
+    }
+    return { ...before, entries, excluded, excludedDirectories, listed, scanned, unsettled,
         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 ?? []]),
+        directoryPaths: await combine(before.directoryPaths, slice.directoryPaths),
+        childPaths: await combine(before.childPaths, slice.childPaths),
+        listingPaths: await combine(before.listingPaths, slice.listingPaths),
+        observations,
         targets: new Map(scopes.flatMap(scope => {
             const target = slice.targets.get(scope.path);
             return target ? [[scope.path, target]] : [];

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

@@ -2,6 +2,7 @@ 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";
+import { type WatchObservation } from "./watch-probe.js";
 export type DirectoryIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
@@ -28,6 +29,8 @@ export type WatchSnapshot = {
     listed?: Map<string, number>;
     childPaths?: Map<string, Map<string, string>>;
     listingPaths?: Map<string, RootDirectoryListingPaths>;
+    observations?: Map<string, WatchObservation>;
+    unsettled?: Set<string>;
 };
 export declare function watchScopes(input: readonly WatchScope[]): readonly WatchScope[];
 /** A descendant's unavailable metadata never grants it authority or retires the Root. */
@@ -38,4 +41,5 @@ export declare function scanWatch(root: RootContext, scopes: readonly WatchScope
     maxPendingPaths: number;
     admitting: boolean;
     previous?: WatchSnapshot;
+    reuse?: Set<string>;
 }, signal: AbortSignal, register: (name: string, identity: DirectoryIdentity, guard: RootDirectoryObservationGuard) => Promise<void>, onCleanupFailure?: (error: unknown) => void): Promise<WatchSnapshot>;

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

@@ -1,13 +1,14 @@
+import { watchRootCurrent as assertRootIdentityCurrent, watchResolve as resolvePathInRoot, watchGuard as createRootDirectoryObservationGuard, watchAssert as assertRootDirectoryObservationGuard, watchListing as openRootDirectoryListing, watchLookup as lookupRootDirectoryEntry, watchYield } from "./watch-io.js";
 import path from "node:path";
 import { isWindowsReservedDeviceName } from "./device-path.js";
 import { isNotFoundPathError } from "./path.js";
 import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { validatePinnedRelativePath } from "./pinned-operation.js";
-import { assertRootIdentityCurrent, assertValidRootRelativePath, resolvePathInRoot } from "./root-context.js";
-import { createRootDirectoryObservationGuard, assertRootDirectoryObservationGuard, openRootDirectoryListing, pathStatFromStats } from "./root-directory-list.js";
+import { assertValidRootRelativePath } from "./root-context.js";
+import { pathStatFromStats } from "./root-directory-list.js";
 import { createSuppressedError } from "./suppressed-error.js";
-import { lookupRootDirectoryEntry } from "./root-directory-entry.js";
+import { watchObservation } from "./watch-probe.js";
 export function watchScopes(input) {
     if (!Array.isArray(input) || input.length > 128)
         throw new RangeError("watch accepts at most 128 scopes");
@@ -35,13 +36,13 @@ export function watchScopes(input) {
 function kind(entry) {
     return entry.isSymbolicLink ? "symlink" : entry.isDirectory ? "directory" : entry.isFile ? "file" : "other";
 }
-function fingerprint(entry, identity) {
+function fingerprint(entry, identity, observation) {
     const { dev, ino } = identity;
     // Metadata is advisory; identity bits are never rounded through PathStat. Directory size/mtime
     // reflect children, not changes to an entry-only scope.
     return entry.isDirectory
         ? [kind(entry), dev, ino, entry.mode].join(":")
-        : [kind(entry), dev, ino, entry.size, entry.mtimeMs, entry.mode].join(":");
+        : [kind(entry), dev, ino, entry.size, entry.mtimeMs, entry.mode, entry.nlink, observation?.ctimeNs].join(":");
 }
 /** A descendant's unavailable metadata never grants it authority or retires the Root. */
 export function isWatchPathError(error) {
@@ -52,21 +53,34 @@ export function isWatchPathError(error) {
             return true;
         return ["not-found", "path-mismatch", "not-file", "symlink", "outside-workspace", "path-alias"].includes(error.code);
     }
-    return ["ENOTDIR", "EACCES", "EPERM", "EBUSY", "ESTALE", "EIO", "ELOOP"].includes(error?.code ?? "");
+    const failure = error;
+    // Windows realpath can lose its temporary handle during directory removal.
+    if (failure?.code === "EBADF" && failure.syscall === "realpath")
+        return true;
+    return ["ENOTDIR", "EACCES", "EPERM", "EBUSY", "ESTALE", "EIO", "ELOOP"].includes(failure?.code ?? "");
 }
 export async function scanWatch(root, scopes, options, signal, register, onCleanupFailure) {
+    const checkpoint = watchYield();
     const exclusions = new Map();
     const excludedDirectories = new Map(), directoryPaths = new Map();
     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 observations = new Map();
+    const unsettled = new Set();
+    const record = (name, observation, directory) => {
+        observations.set(name, watchObservation(observation));
+        const settledBefore = BigInt(Date.now() - 1000) * 1000000n;
+        if (observation.mtimeNs > settledBefore || observation.ctimeNs > settledBefore)
+            unsettled.add(directory);
+    };
+    const result = { entries: new Map(), entryAnchors, scopeAnchors, excluded: exclusions, excludedDirectories, directoryPaths, directories: new Map(), targets: new Map(), scanned: 0, listed, childPaths, listingPaths, observations, unsettled };
     const attempts = new Map();
     const guards = new Map();
     const walked = new Map();
     const structural = new Set();
     result.structural = structural;
-    const invalidate = (relative) => {
+    const invalidate = async (relative) => {
         if (structural.size < options.maxPendingPaths)
             structural.add(relative);
         else
@@ -77,10 +91,12 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
             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())
+        for (const map of [result.entries, exclusions, excludedDirectories, directoryPaths, result.targets, result.directories, guards, walked, listed, childPaths, listingPaths, observations, unsettled]) {
+            for (const name of map.keys()) {
+                await checkpoint();
                 if (below(name))
                     map.delete(name);
+            }
         }
     };
     const recover = async (relative, error) => {
@@ -89,7 +105,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         const code = error instanceof FsSafeError ? error.details?.code ?? error.code : error?.code;
         if (!isWatchPathError(error) || (!relative && (code === "EACCES" || code === "EPERM")))
             throw error;
-        invalidate(relative);
+        await invalidate(relative);
     };
     const examined = () => {
         if (++result.scanned > options.maxEntries)
@@ -147,6 +163,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                 const guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
                 const identity = { dev: guard.stat.dev, ino: guard.stat.ino };
                 result.directories.set(relative, identity);
+                record(relative, guard.stat, relative);
                 directoryPaths.set(relative, guard.realPath);
                 await register(relative, identity, guard);
                 signal.throwIfAborted();
@@ -166,9 +183,44 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         throw new FsSafeError("path-mismatch", "watch directory changed during registration");
     };
     const tree = async (relative, depth) => {
+        await checkpoint();
         if ((walked.get(relative) ?? 0) >= depth)
             return;
         walked.set(relative, depth);
+        const previous = options.previous;
+        if (options.reuse?.has(relative) && previous?.childPaths?.has(relative)) {
+            // Copy only a previously guarded listing, never metadata obtained by the probe.
+            const names = previous.childPaths.get(relative);
+            childPaths.set(relative, names);
+            listed.set(relative, previous.listed.get(relative));
+            listingPaths.set(relative, previous.listingPaths.get(relative));
+            result.directories.set(relative, previous.directories.get(relative));
+            directoryPaths.set(relative, previous.directoryPaths.get(relative));
+            observations.set(relative, previous.observations.get(relative));
+            if (previous.unsettled?.has(relative))
+                unsettled.add(relative);
+            result.scanned += previous.listed.get(relative);
+            for (const name of names.values()) {
+                await checkpoint();
+                const observation = previous.observations?.get(name);
+                if (observation)
+                    observations.set(name, observation);
+                const excludedKind = previous.excluded?.get(name);
+                if (excludedKind) {
+                    exclusions.set(name, excludedKind);
+                    const canonical = previous.excludedDirectories?.get(name);
+                    if (canonical)
+                        excludedDirectories.set(name, canonical);
+                    continue;
+                }
+                const entry = previous.entries.get(name);
+                if (entry)
+                    result.entries.set(name, entry);
+                if (entry?.startsWith("directory:") && depth > 1)
+                    await tree(name, depth - 1);
+            }
+            return;
+        }
         let guard;
         let listing;
         for (let attempt = 0; attempt < 3; attempt++) {
@@ -179,7 +231,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                     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; },
-                });
+                }, () => options.maxEntries - result.scanned);
                 // The listing has its own guard. Both identities must agree before reading names.
                 await assertRootDirectoryObservationGuard(root, guard);
                 break;
@@ -200,6 +252,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         let operationError;
         try {
             while (true) {
+                await checkpoint();
                 const next = await listing.next();
                 signal.throwIfAborted();
                 if (!next)
@@ -211,9 +264,11 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                 const entry = next.entry;
                 const name = previousNames?.get(entry.name) ?? (relative ? path.join(relative, entry.name) : entry.name);
                 names.set(entry.name, name);
+                if (next.observation)
+                    record(name, next.observation, relative);
                 if (await excluded(name, entry))
                     continue;
-                result.entries.set(name, fingerprint(entry, next.identity));
+                result.entries.set(name, fingerprint(entry, next.identity, next.observation));
                 if (entry.isDirectory && !entry.isSymbolicLink && depth > 1)
                     await tree(name, depth - 1);
             }
@@ -266,16 +321,18 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                 examined();
                 // Filesystem lookup, not lowercase/prefix matching, owns case, Unicode and
                 // short-name aliases. It also preserves case-sensitive Windows directories.
-                const found = await lookupRootDirectoryEntry(root, guard, segments[i]);
+                const found = await lookupRootDirectoryEntry(root, guard, segments[i], true);
                 signal.throwIfAborted();
                 if (!found)
                     break;
                 const name = relative ? path.join(relative, segments[i]) : segments[i];
+                if (found.observation)
+                    record(name, found.observation, relative);
                 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.entries.set(name, fingerprint(found.entry, found.identity, found.observation));
                     result.targets.set(name, found.identity);
                     if (scope.kind === "tree" && found.entry.isDirectory && !found.entry.isSymbolicLink && scope.depth > 0)
                         await tree(name, scope.depth);
@@ -284,7 +341,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                 if (found.entry.isSymbolicLink) {
                     if (options.admitting)
                         throw new FsSafeError("symlink", "watch scope traverses a symbolic link; admit its target separately", { details: { operation: "scope" } });
-                    invalidate(name);
+                    await invalidate(name);
                     break;
                 }
                 if (!found.entry.isDirectory)
@@ -299,6 +356,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         }
     }
     for (const [relative, guard] of guards) {
+        await checkpoint();
         try {
             await assertRootDirectoryObservationGuard(root, guard);
         }
@@ -308,9 +366,13 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
     }
     await assertRootIdentityCurrent(root);
     signal.throwIfAborted();
+    if (result.directories.size > options.maxDirectories || result.scanned > options.maxEntries) {
+        throw new FsSafeError("too-large", "watch observation budget exceeded", { details: { operation: "scan" } });
+    }
     // Native deletion hints can arrive after a later scan. Keep bounded tombstones
     // until the name is admitted again; they never grant authority to publish it.
     for (const [name, kind] of options.previous?.excluded ?? []) {
+        await checkpoint();
         if (exclusions.size >= options.maxEntries)
             break;
         if (!result.entries.has(name) && !result.directories.has(name) && !exclusions.has(name))

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

@@ -6,3 +6,5 @@ export type WatchStreamPaths = {
 };
 /** Canonical names come only from guarded directory observations, never backend hints. */
 export declare function watchStreamPaths(snapshot: WatchSnapshot, scopes: readonly WatchScope[]): WatchStreamPaths;
+/** Avoid a tree-sized sort on the host when many directories are excluded. */
+export declare function watchStreamPathsAsync(snapshot: WatchSnapshot, scopes: readonly WatchScope[]): Promise<WatchStreamPaths>;

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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { watchYield } from "./watch-io.js";
 function shallowest(paths, limit) {
     const result = [];
     const sorted = [...new Set(paths)].sort((a, b) => a.split(path.sep).length - b.split(path.sep).length || a.localeCompare(b));
@@ -32,3 +33,25 @@ export function watchStreamPaths(snapshot, scopes) {
     }
     return { anchors: shallowest(anchors, 128), exclusions: shallowest(snapshot.excludedDirectories?.values() ?? [], 8) };
 }
+/** Avoid a tree-sized sort on the host when many directories are excluded. */
+export async function watchStreamPathsAsync(snapshot, scopes) {
+    const result = watchStreamPaths({ ...snapshot, excludedDirectories: undefined }, scopes);
+    const checkpoint = watchYield();
+    for (let n = 0; n < 8; n++) {
+        let selected, depth = Infinity;
+        for (const name of snapshot.excludedDirectories?.values() ?? []) {
+            await checkpoint();
+            if (result.exclusions.some(parent => name === parent || name.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep)))
+                continue;
+            const nextDepth = name.split(path.sep).length;
+            if (nextDepth < depth || (nextDepth === depth && name.localeCompare(selected) < 0)) {
+                selected = name;
+                depth = nextDepth;
+            }
+        }
+        if (selected === undefined)
+            break;
+        result.exclusions.push(selected);
+    }
+    return result;
+}

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

@@ -35,8 +35,10 @@ export type WatchOptions = {
     mode: "auto" | "events" | "poll";
     /** Keep the Node event loop alive while open. Defaults to true. */
     persistent?: boolean;
-    /** Guarded reconciliation interval: events 30000, poll 1000; minimum 20 ms. */
+    /** Incremental metadata check interval: events 30000, poll 1000; minimum 20 ms. */
     intervalMs?: number;
+    /** Full guarded safety-net reconciliation interval. Defaults to 300000 ms; minimum 20 ms. */
+    fullReconcileIntervalMs?: number;
     /** Polling transport interval; overrides intervalMs in poll mode or auto fallback. Minimum 20 ms. */
     pollIntervalMs?: number;
     exclude?: (entry: WatchEntry) => boolean;