@openclaw/signal 2026.11.3 → 2026.11.5-beta.2

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

@@ -51,6 +51,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import fs from "node:fs";
+import { annotateReadOnlyOpenError } from "./file-open-error.js";
 import { randomUUID } from "node:crypto";
 import fsAsync from "node:fs/promises";
 import path from "node:path";
@@ -487,6 +488,7 @@ export async function tryOpenCreateRootNative(params) {
             catch (error) {
                 if (hasNodeErrorCode(error, "EEXIST") && typeof error === "object" && error !== null)
                     nativeCreateCollisions.add(error);
+                annotateReadOnlyOpenError(error, params.target);
                 throw error;
             }
             let rawOpen = true;

package/node_modules/@openclaw/fs-safe/dist/root-directory-entry.d.ts

@@ -2,8 +2,10 @@ import { type RootContext } from "./root-context.js";
 import { type RootDirectoryObservationGuard } from "./root-directory-list.js";
 import { type ExactStatIdentity } from "./stat-observation.js";
 import type { DirEntry } from "./types.js";
+import type { RootEntryObservation } from "./root-directory-list-types.js";
 /** One literal entry lookup under an operation-local admitted parent; never follow the leaf. */
-export declare function lookupRootDirectoryEntry(root: RootContext, guard: RootDirectoryObservationGuard, name: string): Promise<{
+export declare function lookupRootDirectoryEntry(root: RootContext, guard: RootDirectoryObservationGuard, name: string, exactMetadata?: boolean): Promise<{
     entry: DirEntry;
     identity: ExactStatIdentity;
+    observation?: RootEntryObservation;
 } | undefined>;

package/node_modules/@openclaw/fs-safe/dist/root-directory-entry.js

@@ -1,12 +1,13 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertValidRootRelativePath } from "./root-context.js";
 import { assertRootDirectoryObservationGuard, pathStatFromStats } from "./root-directory-list.js";
 import { inspectStatObservationSync } from "./stat-observation.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 /** One literal entry lookup under an operation-local admitted parent; never follow the leaf. */
-export async function lookupRootDirectoryEntry(root, guard, name) {
+export async function lookupRootDirectoryEntry(root, guard, name, exactMetadata = false) {
     if (!name || name === "." || name === ".." || path.basename(name) !== name || path.isAbsolute(name)) {
         throw new FsSafeError("invalid-path", "directory lookup requires one literal name");
     }
@@ -14,10 +15,12 @@ export async function lookupRootDirectoryEntry(root, guard, name) {
     await assertRootDirectoryObservationGuard(root, guard);
     try {
         const pathname = path.join(guard.realPath, name);
-        const observed = inspectStatObservationSync(bigint => bigint
-            ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname));
+        const exact = exactMetadata ? inspectFileIdentitySync(() => fs.lstatSync(pathname, { bigint: true })) : undefined;
+        const observed = exact ? { stat: exact, identity: { dev: exact.dev, ino: exact.ino } }
+            : inspectStatObservationSync(bigint => bigint ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname));
         await assertRootDirectoryObservationGuard(root, guard);
-        return { entry: pathStatFromStats(observed.stat, name), identity: observed.identity };
+        return { entry: pathStatFromStats(observed.stat, name), identity: observed.identity,
+            ...(exactMetadata ? { observation: observed.stat } : {}) };
     }
     catch (error) {
         await assertRootDirectoryObservationGuard(root, guard);

package/node_modules/@openclaw/fs-safe/dist/root-directory-list-types.d.ts

@@ -1,14 +1,17 @@
 import type { ExactStatIdentity } from "./stat-observation.js";
+import type { BigIntStats } from "node:fs";
 import type { DirEntry } from "./types.js";
 /** Strings only: cached spellings never replace an observation or its identity fences. */
 export type RootDirectoryListingPaths = {
     directory: string;
     names: Map<string, string>;
 };
+export type RootEntryObservation = Pick<BigIntStats, "dev" | "ino" | "mode" | "nlink" | "size" | "mtimeNs" | "ctimeNs">;
 export type RootDirectoryListingResult = {
     kind: "entry";
     entry: DirEntry;
     identity?: ExactStatIdentity;
+    observation?: RootEntryObservation;
 } | {
     kind: "limit";
     name: string;

package/node_modules/@openclaw/fs-safe/dist/root-directory-list.d.ts

@@ -1,5 +1,6 @@
 import type { BigIntStats, Stats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { type NativeDirectoryObservationBackend } from "./native-directory-observation.js";
 import { type RootContext } from "./root-context.js";
 import type { RootPathDirectoryObservationGuard, RootPathObservationReceipt, RootPathParentObservationReceipt } from "./root-path.js";
 import type { DirEntry, PathStat } from "./types.js";
@@ -8,7 +9,7 @@ export declare function pathStatFromStats(stat: Stats | BigIntStats): PathStat;
 export declare function pathStatFromStats(stat: Stats | BigIntStats, name: string): DirEntry;
 export type RootDirectoryObservationGuard = AsyncDirectoryGuard<BigIntStats>;
 export declare function createRootDirectoryObservationGuard(root: RootContext, directory: string): Promise<RootDirectoryObservationGuard>;
-export declare function assertRootDirectoryObservationGuard(root: RootContext, guard: RootDirectoryObservationGuard | RootPathDirectoryObservationGuard): Promise<void>;
+export declare function assertRootDirectoryObservationGuard(root: RootContext, guard: RootDirectoryObservationGuard | RootPathDirectoryObservationGuard, backend?: NativeDirectoryObservationBackend): Promise<void>;
 /**
  * Close an operation-local traversal receipt with fresh exact observations.
  * Descendant canonical paths are admitted while the receipt is created. The

package/node_modules/@openclaw/fs-safe/dist/root-directory-list.js

@@ -6,14 +6,14 @@ import path from "node:path";
 import { setImmediate as yieldToEventLoop } from "node:timers/promises";
 import { assertAsyncDirectoryGuard, assertDirectoryObservationGuardSync, assertDirectoryObservationSync, createAsyncDirectoryGuard, extendDirectoryObservationGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
+import { inspectNativeDirectoryObservation, getNativeDirectoryObservationBackend, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
 import { errorCauseOptions, rootPathChangedError } from "./root-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { realpathSync } from "./realpath.js";
-import { inspectStatObservationSync } from "./stat-observation.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const METADATA_BATCH_SIZE = 32;
 function directoryEntryName(bytes) {
@@ -77,7 +77,7 @@ function directoryChangedError(error) {
         return error;
     return new FsSafeError("path-mismatch", "directory changed during operation", errorCauseOptions(error));
 }
-export async function assertRootDirectoryObservationGuard(root, guard) {
+export async function assertRootDirectoryObservationGuard(root, guard, backend) {
     if (isNativeDirectoryObservationGuard(guard)) {
         throw new FsSafeError("path-mismatch", "native directory observation cannot be revalidated");
     }
@@ -86,7 +86,9 @@ export async function assertRootDirectoryObservationGuard(root, guard) {
         identity.dev === root.rootIdentity.dev && identity.ino === root.rootIdentity.ino;
     if (guardPinsRoot) {
         try {
-            if ("identity" in guard)
+            if (backend && "identity" in guard)
+                assertReceiptDirectoryGuardSync(root, guard, backend);
+            else if ("identity" in guard)
                 assertDirectoryObservationGuardSync(guard);
             else
                 await assertAsyncDirectoryGuard(guard);
@@ -109,7 +111,9 @@ export async function assertRootDirectoryObservationGuard(root, guard) {
         await assertRootIdentityCurrent(root);
     }
     try {
-        if ("identity" in guard)
+        if (backend && "identity" in guard)
+            assertReceiptDirectoryGuardSync(root, guard, backend);
+        else if ("identity" in guard)
             assertDirectoryObservationGuardSync(guard);
         else
             await assertAsyncDirectoryGuard(guard);
@@ -263,12 +267,15 @@ export async function openRootDirectoryListing(root, directory, options, receipt
             identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
         }, admitted.dir, admitted.realPath);
     }
+    // Windows watch listings keep every fence while sharing one handle for its
+    // identity/path queries. POSIX pathname checks are cheaper than this helper.
+    const backend = getNativeDirectoryObservationBackend(options.exactIdentity === true && process.platform === "win32");
     const assertCurrent = async () => {
         options.signal?.throwIfAborted();
         if (receipt)
             assertRootPathObservationReceiptCurrent(root, receipt);
         else
-            await assertRootDirectoryObservationGuard(root, guard);
+            await assertRootDirectoryObservationGuard(root, guard, backend);
         options.signal?.throwIfAborted();
     };
     const paths = { directory: guard.realPath, names: new Map() };
@@ -430,8 +437,10 @@ export async function openRootDirectoryListing(root, directory, options, receipt
                         paths.names.set(name, pathname);
                     let observed;
                     try {
-                        observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
-                            ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : { stat: fsSync.lstatSync(pathname, { bigint: true }) };
+                        const stat = options.exactIdentity
+                            ? inspectFileIdentitySync(() => fsSync.lstatSync(pathname, { bigint: true }))
+                            : fsSync.lstatSync(pathname, { bigint: true });
+                        observed = { stat, ...(options.exactIdentity ? { identity: { dev: stat.dev, ino: stat.ino } } : {}) };
                     }
                     catch (error) {
                         await assertCurrent();
@@ -440,7 +449,8 @@ export async function openRootDirectoryListing(root, directory, options, receipt
                         throw error;
                     }
                     await assertCurrent();
-                    return { kind: "entry", entry: pathStatFromStats(observed.stat, name), identity: observed.identity };
+                    return { kind: "entry", entry: pathStatFromStats(observed.stat, name), identity: observed.identity,
+                        ...(options.exactIdentity ? { observation: observed.stat } : {}) };
                 }
             }
             catch (error) {

package/node_modules/@openclaw/fs-safe/dist/root-file-final-admission.js

@@ -31,9 +31,9 @@ export function observeCanonicalRoot(ioFs, rootPath) {
         const stat = inspectCanonicalRoot(ioFs, rootPath);
         const identity = Object.freeze({ dev: stat.dev, ino: stat.ino });
         let observedPath = rootPath;
-        if (process.platform === "win32" && ioFs === fs) {
-            // Native leaf resolution expands Windows short names. Bind that root
-            // spelling before traversal without replacing the observed identity.
+        if (ioFs === fs) {
+            // Match native leaf resolution (including case and Windows short names)
+            // without replacing the already observed root identity.
             observedPath = realpathSync.native(pathForWindowsFilesystem(rootPath));
             if (observedPath !== rootPath)
                 inspectCanonicalRoot(ioFs, observedPath, identity);

package/node_modules/@openclaw/fs-safe/dist/root-path-existing.d.ts

@@ -8,5 +8,5 @@ export declare function rawPathRelativeToCanonicalRoot(candidate: string, rootCa
 export declare function resolvePathViaExistingAncestor(targetPath: string): Promise<string>;
 export declare function resolvePathViaExistingAncestorSync(targetPath: string): string;
 export type RootPathMetadataMode = "native" | "ordinary";
-export declare function resolveExistingAncestor(targetPath: string, mode: RootPathMetadataMode): string;
-export declare function resolveSymlinkHopPath(symlinkPath: string, mode: RootPathMetadataMode, rejectUnresolved?: boolean): string;
+export declare function resolveExistingAncestor(targetPath: string, mode: RootPathMetadataMode, preserveRawSegments?: boolean, remainingHops?: number): string;
+export declare function resolveSymlinkHopPath(symlinkPath: string, mode: RootPathMetadataMode, rejectUnresolved?: boolean, remainingHops?: number): string;

package/node_modules/@openclaw/fs-safe/dist/root-path-existing.js

@@ -104,14 +104,15 @@ function pathExistsSync(targetPath) {
 export function resolvePathViaExistingAncestorSync(targetPath) {
     return resolveExistingAncestor(targetPath, "ordinary");
 }
-export function resolveExistingAncestor(targetPath, mode) {
-    const exists = mode === "native" ? pathExists : pathExistsSync;
-    const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
+export function resolveExistingAncestor(targetPath, mode, preserveRawSegments = false, remainingHops = 64) {
+    const exists = mode === "native" || preserveRawSegments ? pathExists : pathExistsSync;
+    const canonicalize = realpathSync.native;
     assertNoWindowsPathAlias(targetPath);
     const normalized = resolvePathPreservingWindowsRoot(targetPath);
     assertNoWindowsPathAlias(normalized);
-    let cursor = normalized;
-    const filesystemRoot = path.parse(normalized).root;
+    const candidate = preserveRawSegments ? absolutePathWithRawSegments(targetPath) : normalized;
+    let cursor = candidate;
+    const filesystemRoot = path.parse(candidate).root;
     while (cursor !== filesystemRoot &&
         !exists(cursor)) {
         cursor = path.dirname(cursor);
@@ -123,22 +124,30 @@ export function resolveExistingAncestor(targetPath, mode) {
     try {
         rawResolvedAncestor = canonicalize(pathForWindowsFilesystem(cursor));
     }
-    catch {
-        return normalized;
+    catch (error) {
+        if (!preserveRawSegments)
+            return normalized;
+        if (!isNotFoundPathError(error))
+            throw error;
+        rawResolvedAncestor = resolveSymlinkHopPath(cursor, mode, false, remainingHops);
     }
     assertNoWindowsPathAlias(rawResolvedAncestor);
     const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
     assertNoWindowsPathAlias(resolvedAncestor);
     // Keep a leading suffix separator relative to the canonical ancestor.
-    const resolved = cursor === normalized
+    const suffix = candidate.slice(cursor.length);
+    if (preserveRawSegments && suffix.split(path.sep).includes("..")) {
+        throw new FsSafeError("symlink", "symlink target has an unresolved parent component");
+    }
+    const resolved = cursor === candidate
         ? resolvedAncestor
-        : path.resolve(resolvedAncestor, `.${path.sep}${normalized.slice(cursor.length)}`);
+        : path.resolve(resolvedAncestor, `.${path.sep}${suffix}`);
     assertNoWindowsPathAlias(resolved);
     return resolved;
 }
-export function resolveSymlinkHopPath(symlinkPath, mode, rejectUnresolved) {
+export function resolveSymlinkHopPath(symlinkPath, mode, rejectUnresolved, remainingHops = 64) {
     try {
-        const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
+        const canonicalize = realpathSync.native;
         const rawRealPath = canonicalize(symlinkPath);
         assertNoWindowsPathAlias(rawRealPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
         const realPath = resolvePathPreservingWindowsRoot(rawRealPath);
@@ -151,11 +160,16 @@ export function resolveSymlinkHopPath(symlinkPath, mode, rejectUnresolved) {
         }
         if (!isNotFoundPathError(error))
             throw error;
+        if (remainingHops <= 0)
+            throw new FsSafeError("symlink", "too many unresolved symlink hops");
         const linkTarget = fs.readlinkSync(symlinkPath);
         assertNoWindowsPathAlias(linkTarget, "filesystem", "symlink target uses a Windows filesystem namespace alias");
         const linkDir = resolvePathPreservingWindowsRoot(path.dirname(symlinkPath));
-        const targetPath = resolvePathFromBasePreservingWindowsRoot(linkDir, linkTarget);
-        const resolved = resolveExistingAncestor(targetPath, mode);
+        // Keep parent segments until the kernel has resolved the existing prefix.
+        const targetPath = path.isAbsolute(linkTarget) ? linkTarget
+            : path.parse(linkTarget).root ? resolvePathFromBasePreservingWindowsRoot(linkDir, linkTarget)
+                : `${linkDir}${path.sep}${linkTarget}`;
+        const resolved = resolveExistingAncestor(targetPath, mode, true, remainingHops - 1);
         assertNoWindowsPathAlias(resolved, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
         return resolved;
     }

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

@@ -255,8 +255,8 @@ function assertResolvedLinkDirectory(pathname, isLast) {
     const stat = fs.statSync(pathForWindowsFilesystem(pathname));
     assertDirectoryBeforeMoreSegments(stat, pathname, isLast);
 }
-// Both public APIs use synchronous metadata; only canonicalization and ancestor
-// existence differ. Promise wrappers preserve the asynchronous rejection API.
+// Both public APIs use kernel canonicalization and synchronous metadata; only
+// ancestor existence differs. Promise wrappers preserve asynchronous rejection.
 function traverseRootPath(params, { mode = "native", observation: observationOutput, observeRoot, removalReceipts }) {
     const input = captureValidRootPathInputs(params);
     const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);

package/node_modules/@openclaw/fs-safe/dist/sibling-staged-file.d.ts

@@ -1,7 +1,10 @@
+import { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
 export declare function resolveCallbackTempPath(workspaceDir: string, component: string): string;
 export declare function writeCallbackSibling<T>(params: {
     tempDir: string;
     tempName: string;
+    rootBoundary?: AsyncDirectoryGuard<BigIntStats>;
     write: (tempPath: string) => Promise<T>;
     producerIsolation?: "private-directory";
     resolveFinalPath: (result: T) => string;

package/node_modules/@openclaw/fs-safe/dist/sibling-staged-file.js

@@ -13,6 +13,7 @@ import { cachedNoReplaceDevice, isNoReplaceUnavailable } from "./native-noreplac
 import { handoffPrivateProducerFile, } from "./private-producer-handoff.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { rootFromDirectoryGuard } from "./root-impl.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { createOwnedTempFile } from "./temp-target.js";
@@ -160,10 +161,22 @@ export async function writeCallbackSibling(params) {
     const maxBytes = params.maxBytes;
     const syncTempFile = params.syncTempFile;
     const syncParentDir = params.syncParentDir;
+    const rootBoundary = params.rootBoundary;
     const guard = await createAsyncDirectoryGuard(parent, { bigint: true });
-    const assertParent = () => assertDirectoryIdentitySync(parent, {
-        dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath,
-    });
+    const assertParent = () => {
+        assertDirectoryIdentitySync(parent, {
+            dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath,
+        });
+        if (rootBoundary) {
+            assertDirectoryIdentitySync(rootBoundary.dir, {
+                dev: rootBoundary.stat.dev, ino: rootBoundary.stat.ino, realPath: rootBoundary.realPath,
+            });
+            if (!admitPathInsideRoot({
+                rootPath: rootBoundary.realPath, candidatePath: guard.realPath, rootIdentity: rootBoundary.stat,
+            }))
+                throw new FsSafeError("outside-workspace", "sibling parent resolves outside the root");
+        }
+    };
     let handle;
     let identity;
     let unregister;
@@ -181,6 +194,8 @@ export async function writeCallbackSibling(params) {
         }
     };
     try {
+        if (rootBoundary)
+            assertParent();
         let result;
         if (producerIsolation === "private-directory") {
             const isolated = await writeIsolatedProducer({

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

@@ -9,7 +9,7 @@ export declare function selectedWatchChildren(scopes: readonly WatchScope[], dir
 /** 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;
+export declare function changedEntries(before: WatchSnapshot | undefined, after: WatchSnapshot, limit: number): Promise<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. */

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

@@ -1,9 +1,9 @@
 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";
+import {} from "./root-context.js";
+import {} from "./root-directory-list.js";
+import { watchRootCurrent as assertRootIdentityCurrent, watchResolve as resolvePathInRoot, watchGuard as createRootDirectoryObservationGuard, watchAssert as assertRootDirectoryObservationGuard, watchLookup as lookupRootDirectoryEntry, watchYield } from "./watch-io.js";
 function below(parent, child) {
     return parent === "" ? child !== "" : child.startsWith(parent + path.sep);
 }
@@ -86,7 +86,7 @@ export function nativeChanges(scopes, snapshot, batch, limit = 256, after) {
     }
     return [...result.values()];
 }
-export function changedEntries(before, after, limit) {
+export async function changedEntries(before, after, limit) {
     if (!before)
         return undefined;
     const changes = [];
@@ -102,12 +102,17 @@ export function changedEntries(before, after, limit) {
         changes.push(Object.freeze({ path: name, type: sameFile ? "content" : "structural" }));
         return true;
     };
-    for (const name of before.entries.keys())
+    const checkpoint = watchYield();
+    for (const name of before.entries.keys()) {
+        await checkpoint();
         if (!compare(name))
             return undefined;
-    for (const name of after.entries.keys())
+    }
+    for (const name of after.entries.keys()) {
+        await checkpoint();
         if (!before.entries.has(name) && !compare(name))
             return undefined;
+    }
     return changes;
 }
 /** Backend names never establish authority to publish a pathname. */
@@ -116,14 +121,19 @@ 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) {
-        // Drop unobserved non-target names only under a parent with the same guarded
-        // identity in both passes; otherwise a stale/misdirected watch erases detail.
+        // A consumer can observe a transient child between our scans. Invalidate
+        // its admitted parent without publishing an unobserved backend spelling.
         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)
+            if (left && right && left.dev === right.dev && left.ino === right.ino) {
+                for (const change of scopedChanges(scopes, { path: directory, type: "structural" })) {
+                    if (!addChange(result, change, limit))
+                        return undefined;
+                }
                 continue;
+            }
             return undefined;
         }
         // Equal snapshots cannot exclude an intermediate change and restoration (ABA).
@@ -140,11 +150,18 @@ export async function admittedNativeChanges(root, scopes, before, after, batch,
         return undefined;
     if (scheduling && !batch.hints.length)
         return undefined;
+    const checkpoint = watchYield();
     const result = new Map();
-    const candidates = new Map([...before?.targets ?? [], ...after.targets, ...after.directories]);
+    const candidates = new Map();
+    for (const entries of [before?.targets, after.targets, after.directories])
+        for (const [name, identity] of entries ?? []) {
+            candidates.set(name, identity);
+            await checkpoint();
+        }
     if (scheduling) {
         const identities = new Map();
         for (const { dev, ino } of candidates.values()) {
+            await checkpoint();
             let inodes = identities.get(dev);
             if (!inodes)
                 identities.set(dev, inodes = new Set());
@@ -173,9 +190,11 @@ export async function admittedNativeChanges(root, scopes, before, after, batch,
     };
     if (scheduling) {
         // A sibling hint cannot hide a replaced scope anchor or its identity chain.
-        for (const name of after.directories.keys())
+        for (const name of after.directories.keys()) {
+            await checkpoint();
             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)
@@ -206,6 +225,7 @@ export async function admittedNativeChanges(root, scopes, before, after, batch,
                 return undefined;
             const guard = await admittedParent(hint.directory);
             for (const [name, identity] of candidates) {
+                await checkpoint();
                 if (identity.dev === guard.stat.dev && identity.ino === guard.stat.ino && selectedWatchSubtree(scopes, name))
                     return undefined;
             }
@@ -225,22 +245,48 @@ export async function admittedNativeChanges(root, scopes, before, after, batch,
             // 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)
+            for (let attempt = 0;; attempt++) {
+                const retained = guards.has(parent);
+                try {
+                    guard = await admittedParent(parent);
+                    break;
+                }
+                catch (error) {
+                    await assertRootIdentityCurrent(root);
+                    // An earlier hint may already depend on this selected-alias guard.
+                    if (scheduling || retained)
+                        throw error;
+                    guards.delete(parent);
+                    if (isNotFoundPathError(error) || (error instanceof FsSafeError && ["not-found", "path-alias", "outside-workspace", "symlink", "not-file"].includes(error.code)))
+                        break;
+                    // A yielded admission may race an ordinary sibling deletion. Fresh
+                    // admission can establish absence; persistent ambiguity still fails.
+                    // Windows also reports EPERM while an unrelated directory is delete-pending.
+                    const failure = error;
+                    const failedRealpath = failure?.syscall === "realpath" &&
+                        (failure.code === "EBADF" || failure.code === "EPERM");
+                    if (attempt < 2 && (failedRealpath || error instanceof FsSafeError && error.code === "path-mismatch"))
+                        continue;
                     throw error;
-                if (isNotFoundPathError(error) || (error instanceof FsSafeError && ["not-found", "path-alias", "outside-workspace", "symlink", "not-file"].includes(error.code)))
-                    continue;
-                throw error;
+                }
+            }
+            if (!guard)
+                continue;
+            let admitted;
+            for (const entry of after.directories) {
+                await checkpoint();
+                if (entry[1].dev === guard.stat.dev && entry[1].ino === guard.stat.ino) {
+                    admitted = entry;
+                    break;
+                }
             }
-            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;
+                // The guarded observation proved this parent is not a selected alias.
+                // No result depends on it; do not extend its lifetime through sibling churn.
+                guards.delete(hint.directory);
                 continue;
             }
             [parent, expected] = admitted;
@@ -288,6 +334,7 @@ export async function admittedNativeChanges(root, scopes, before, after, batch,
         if (scheduling && found.entry.isSymbolicLink)
             return undefined;
         for (const [relative, identity] of candidates) {
+            await checkpoint();
             if (!relative || identity.dev !== found.identity.dev || identity.ino !== found.identity.ino)
                 continue;
             if ((path.dirname(relative) === "." ? "" : path.dirname(relative)) !== parent) {

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

@@ -0,0 +1,2 @@
+export declare function encodeWatchError(error: unknown): unknown;
+export declare function decodeWatchError(value: unknown): unknown;

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

@@ -0,0 +1,27 @@
+import { FsSafeError } from "./errors.js";
+import { createSuppressedError } from "./suppressed-error.js";
+export function encodeWatchError(error) {
+    if (!(error instanceof Error))
+        return error;
+    const combined = error;
+    const syscall = error.syscall;
+    return {
+        name: error.name, message: error.message, code: error.code,
+        ...(typeof syscall === "string" ? { syscall } : {}),
+        ...(error instanceof FsSafeError ? { details: error.details } : {}),
+        cause: error.cause === undefined ? undefined : encodeWatchError(error.cause),
+        ...(error.name === "SuppressedError" ? { error: encodeWatchError(combined.error), suppressed: encodeWatchError(combined.suppressed) } : {}),
+    };
+}
+export function decodeWatchError(value) {
+    if (!value || typeof value !== "object" || !("message" in value) || typeof value.message !== "string")
+        return value;
+    const error = value;
+    if (error.name === "SuppressedError")
+        return createSuppressedError(decodeWatchError(error.error), decodeWatchError(error.suppressed), error.message);
+    const cause = error.cause === undefined ? undefined : decodeWatchError(error.cause);
+    if (error.name === "FsSafeError")
+        return new FsSafeError(error.code, error.message, { cause, details: error.details });
+    return Object.assign(new Error(error.message, { cause }), { name: error.name, code: error.code,
+        ...(typeof error.syscall === "string" ? { syscall: error.syscall } : {}) });
+}

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

@@ -0,0 +1 @@
+export {};