@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-owner.js

@@ -14,13 +14,6 @@ function isNativeCleanupBinding(binding) {
         typeof binding.removeOwnedTreeSync === "function" &&
         typeof binding.ownedTreeRemovalAvailable === "function";
 }
-function nativeRemovalError(result) {
-    if (!result.errorCode)
-        return undefined;
-    return Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), {
-        code: result.errorCode,
-    });
-}
 export class TempWorkspaceCleanupCapability {
     binding;
     parent;
@@ -58,10 +51,10 @@ export class TempWorkspaceCleanupCapability {
         try {
             parent = openTempWorkspaceCleanupParent(root, admission);
         }
-        catch {
-            if (parent)
-                fsSync.closeSync(parent.fd);
-            parent = undefined;
+        catch (error) {
+            // Failed descriptor closure must retain the original admission failure too.
+            if (error instanceof AggregateError)
+                throw error;
         }
         let available = false;
         if (childModeAllowsRemoval && parent?.access === "read" && isNativeCleanupBinding(binding)) {
@@ -158,6 +151,36 @@ export class TempWorkspaceCleanupCapability {
             fsSync.closeSync(this.parent.fd);
     }
 }
+export function throwTempWorkspaceCreationFailure(error, retainedChild, capability, owner, label = "temp workspace") {
+    try {
+        if (owner)
+            owner.cleanupSync();
+        else {
+            const closeErrors = [];
+            try {
+                retainedChild?.close();
+            }
+            catch (closeError) {
+                closeErrors.push(closeError);
+            }
+            try {
+                capability.close();
+            }
+            catch (closeError) {
+                closeErrors.push(closeError);
+            }
+            if (closeErrors.length === 1)
+                throw closeErrors[0];
+            if (closeErrors.length > 1) {
+                throw new AggregateError(closeErrors, `${label} admission descriptor close failed`);
+            }
+        }
+    }
+    catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], `${label} creation and cleanup both failed`);
+    }
+    throw error;
+}
 export class TempWorkspaceCleanupOwner {
     #dir;
     #identity;
@@ -279,8 +302,10 @@ export class TempWorkspaceCleanupOwner {
         this.#capability.assertCurrent();
     }
     #mapRemoval(result) {
-        const error = nativeRemovalError(result);
-        if (error) {
+        if (result.errorCode) {
+            const error = Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), {
+                code: result.errorCode,
+            });
             if (error.code === "path-mismatch")
                 return "indeterminate";
             throw error;
@@ -294,22 +319,19 @@ export class TempWorkspaceCleanupOwner {
                 await beforeNativeRemoval(quarantine.path);
             return this.#mapRemoval(await this.#capability.binding.removeOwnedTree(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
         }
-        let removalError;
         try {
             this.#assertQuarantine(quarantine);
-            try {
-                await fs.rm(quarantine.path, { recursive: true, force: true });
-            }
-            catch (error) {
-                removalError = error;
-                throw error;
-            }
+        }
+        catch {
+            return "indeterminate";
+        }
+        // Removal failures propagate unchanged; only authority uncertainty becomes a receipt.
+        await fs.rm(quarantine.path, { recursive: true, force: true });
+        try {
             this.#capability.assertCurrent();
             return "removed";
         }
-        catch (error) {
-            if (error === removalError)
-                throw error;
+        catch {
             return "indeterminate";
         }
     }
@@ -318,22 +340,18 @@ export class TempWorkspaceCleanupOwner {
             getFsSafeTestHooks()?.beforeTempWorkspaceNativeRemovalSync?.(quarantine.path);
             return this.#mapRemoval(this.#capability.binding.removeOwnedTreeSync(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
         }
-        let removalError;
         try {
             this.#assertQuarantine(quarantine);
-            try {
-                fsSync.rmSync(quarantine.path, { recursive: true, force: true });
-            }
-            catch (error) {
-                removalError = error;
-                throw error;
-            }
+        }
+        catch {
+            return "indeterminate";
+        }
+        fsSync.rmSync(quarantine.path, { recursive: true, force: true });
+        try {
             this.#capability.assertCurrent();
             return "removed";
         }
-        catch (error) {
-            if (error === removalError)
-                throw error;
+        catch {
             return "indeterminate";
         }
     }

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-ownership.d.ts

@@ -0,0 +1,8 @@
+type DirectoryOwner = {
+    uid: number | bigint;
+    gid: number | bigint;
+};
+export type TempWorkspaceOwnership = "user" | "root" | "unmapped" | "foreign";
+export declare function classifyTempWorkspaceOwner(stat: DirectoryOwner, uid: number): TempWorkspaceOwnership;
+export declare function warnUnmappedTempWorkspaceAncestor(): void;
+export {};

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-ownership.js

@@ -0,0 +1,52 @@
+import fs from "node:fs";
+let warned = false;
+function overflowId(kind) {
+    try {
+        const value = Number(fs.readFileSync(`/proc/sys/kernel/overflow${kind}`, "utf8").trim());
+        if (Number.isSafeInteger(value) && value >= 0 && value < 0xffffffff)
+            return value;
+    }
+    catch {
+        // Linux defaults when the sysctl files are unavailable in the service mount.
+    }
+    return 65534;
+}
+function unmappedId(kind) {
+    const mappings = fs.readFileSync(`/proc/self/${kind}_map`, "utf8").trim()
+        .split("\n").map((line) => line.trim().split(/\s+/).map(Number));
+    if (!mappings.every((row) => row.length === 3 && row.every((id) => Number.isSafeInteger(id) && id >= 0 && id <= 0xffffffff) && row[2] > 0))
+        return null;
+    if (mappings.length === 1 && mappings[0][0] === 0 &&
+        mappings[0][1] === 0 && mappings[0][2] === 0xffffffff)
+        return null;
+    const id = overflowId(kind);
+    // Recheck every admission: an explicitly mapped overflow-number ID is real ownership.
+    return mappings.some(([start, , count]) => id >= start && id < start + count) ? null : id;
+}
+export function classifyTempWorkspaceOwner(stat, uid) {
+    if (stat.uid === uid || stat.uid === BigInt(uid))
+        return "user";
+    if (stat.uid === 0 || stat.uid === 0n)
+        return "root";
+    if (process.platform !== "linux")
+        return "foreign";
+    try {
+        const overflowUid = unmappedId("uid");
+        const overflowGid = unmappedId("gid");
+        return overflowUid !== null && overflowGid !== null &&
+            (stat.uid === overflowUid || stat.uid === BigInt(overflowUid)) &&
+            (stat.gid === overflowGid || stat.gid === BigInt(overflowGid))
+            ? "unmapped"
+            : "foreign";
+    }
+    catch {
+        // Unavailable mapping evidence cannot authorize the namespace exception.
+        return "foreign";
+    }
+}
+export function warnUnmappedTempWorkspaceAncestor() {
+    if (warned)
+        return;
+    warned = true;
+    process.emitWarning("Temp workspace ancestor ownership is unverifiable in this user namespace; trusting the host directory hierarchy while enforcing ancestor modes and a process-owned private root.", { code: "FS_SAFE_UNMAPPED_TEMP_ANCESTOR", type: "FsSafeWarning" });
+}

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

@@ -37,4 +37,3 @@ export type TempWorkspaceSync = {
     cleanup(): TempWorkspaceCleanupResult;
     [Symbol.dispose](): void;
 };
-//# sourceMappingURL=temp-workspace-types.d.ts.map

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

@@ -1,4 +1,3 @@
 export { tempWorkspace, type TempWorkspace, type TempWorkspaceOptions, type TempWorkspaceCleanupResult, type TempWorkspaceCleanupSafety, tempWorkspaceSync, type TempWorkspaceSync, withTempWorkspace, withTempWorkspaceSync, } from "./private-temp-workspace.js";
 export type { TempPathIdentityReceipt } from "./temp-cleanup.js";
 export { resolveSecureTempRoot, type ResolveSecureTempRootOptions, type SecureTempRootDescriptorAdapter, } from "./secure-temp-dir.js";
-//# sourceMappingURL=temp.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/test-hooks.d.ts

@@ -1,6 +1,10 @@
 import type { FileHandle } from "node:fs/promises";
 import type { FileIdentityStat } from "./file-identity.js";
 export type FsSafeTestHooks = {
+    beforeWatchRegistration?: (path: string) => void | Promise<void>;
+    afterWatchRegistration?: (path: string) => void | Promise<void>;
+    afterWatchBackendOverflow?: (root: string, phase: "received" | "reconciled") => void;
+    afterWatchBackendCreated?: (root: string, emit: (batch: import("./watch-native.js").NativeWatchBatch) => void, nativeEvent?: (path: string, flags: number) => void) => void;
     afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
     beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
     afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
@@ -25,8 +29,7 @@ export type FsSafeTestHooks = {
     beforeTempWorkspaceNativeRemovalSync?: (quarantinePath: string) => void;
     beforeTrashMove?: (targetPath: string, destPath: string) => void;
     afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
-    beforePublishDirectorySync?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
+    beforePublishDirectorySync?: NonNullable<FsSafeTestHooks["afterPublishTargetCreated"]>;
 };
 export declare function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
 export declare function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;
-//# sourceMappingURL=test-hooks.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/text-atomic.d.ts

@@ -1,4 +1,5 @@
-export type WriteTextAtomicOptions = {
+import { type ReplaceFileAtomicOptions } from "./replace-file.js";
+export type WriteTextAtomicOptions = Pick<ReplaceFileAtomicOptions, "beforeRename" | "tempPrefix"> & {
     mode?: number;
     dirMode?: number;
     trailingNewline?: boolean;
@@ -11,4 +12,3 @@ export type WriteTextAtomicOptions = {
     durable?: boolean;
 };
 export declare function writeTextAtomic(filePath: string, content: string, options?: WriteTextAtomicOptions): Promise<void>;
-//# sourceMappingURL=text-atomic.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/text-atomic.js

@@ -1,5 +1,5 @@
 import { replaceFileAtomic } from "./replace-file.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 export async function writeTextAtomic(filePath, content, options) {
     const admittedPath = admitStandalonePublicationPath(filePath);
     const payload = options?.trailingNewline && !content.endsWith("\n") ? `${content}\n` : content;
@@ -12,5 +12,7 @@ export async function writeTextAtomic(filePath, content, options) {
         copyFallbackOnPermissionError: true,
         syncTempFile: durable,
         syncParentDir: durable,
+        beforeRename: options?.beforeRename,
+        tempPrefix: options?.tempPrefix,
     });
 }

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

@@ -6,4 +6,3 @@ export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, l
     message?: string;
     createError?: () => Error;
 }): Promise<T>;
-//# sourceMappingURL=timing.d.ts.map

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

@@ -2,4 +2,3 @@ export type MovePathToTrashOptions = {
     allowedRoots?: Iterable<string>;
 };
 export declare function movePathToTrash(targetPath: string, options?: MovePathToTrashOptions): Promise<string>;
-//# sourceMappingURL=trash.d.ts.map

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

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { assertSyncDirectoryGuard, createSyncDirectoryGuard } from "./directory-guard.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { guardedRenameSync, guardedRmSync } from "./guarded-mutation.js";
 import { realpathSync } from "./realpath.js";
@@ -72,6 +73,22 @@ function resolveTrashTargetPath(targetPath) {
     assertNoTrashPathAlias(resolvedPath, "target path");
     return { path: resolvedPath, resolved: true };
 }
+function resolveTrashEntryParent(lexicalTarget, targetPath) {
+    const lexicalParent = path.dirname(lexicalTarget);
+    assertNoTrashPathAlias(lexicalParent, "target path");
+    let realParent;
+    try {
+        // The renamed name lives in this parent. rename follows intermediate
+        // symlinks, so a lexical parent inside an allowed root is not enough.
+        realParent = realpathSync.native(lexicalParent);
+    }
+    catch {
+        throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
+    }
+    const resolvedParent = path.resolve(realParent);
+    assertNoTrashPathAlias(resolvedParent, "target path");
+    return resolvedParent;
+}
 function assertAllowedTrashTarget(targetPath, allowedRoots) {
     assertNoTrashPathAlias(targetPath, "target path");
     const lexicalTarget = path.resolve(targetPath);
@@ -79,11 +96,19 @@ function assertAllowedTrashTarget(targetPath, allowedRoots) {
     const stat = fs.lstatSync(lexicalTarget);
     const resolvedTarget = resolveTrashTargetPath(targetPath);
     const resolvedTargetPath = resolvedTarget.path;
-    const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => resolvedTargetPath !== root && isSameOrChildPath(resolvedTargetPath, root));
+    const parent = createSyncDirectoryGuard(path.dirname(lexicalTarget));
+    // Admit the directory entry only when its parent really stays inside an
+    // allowed root. Do not admit it because the symlink target is inside.
+    const resolvedParent = resolveTrashEntryParent(lexicalTarget, targetPath);
+    const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => isSameOrChildPath(resolvedParent, root));
     if (!isAllowed) {
         throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
     }
+    // Sync and native realpath can use different Windows short-name spellings.
+    // Recheck the retained guard around native containment instead of comparing them.
+    assertSyncDirectoryGuard(parent);
     return {
+        parent,
         path: lexicalTarget,
         realPath: resolvedTargetPath,
         realPathResolved: resolvedTarget.resolved,
@@ -91,6 +116,7 @@ function assertAllowedTrashTarget(targetPath, allowedRoots) {
     };
 }
 function assertTrashTargetGuard(guard) {
+    assertSyncDirectoryGuard(guard.parent);
     const stat = fs.lstatSync(guard.path);
     if (!sameFileIdentity(stat, guard.stat)) {
         throw new Error(`Refusing to trash path after it changed: ${guard.path}`);

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

@@ -20,4 +20,3 @@ export type BasePathOptions = {
     rootDir: string;
     relativePath: string;
 };
-//# sourceMappingURL=types.d.ts.map

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

@@ -1,3 +1,2 @@
 export declare function lowerCaseNfc(value: string): string;
 export declare function maxNormalizedUtf8Bytes(value: string, includeRaw?: boolean): number;
-//# sourceMappingURL=unicode-path.d.ts.map

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

@@ -3,6 +3,9 @@ export function lowerCaseNfc(value) {
     return NON_ASCII.test(value) ? value.normalize("NFC").toLowerCase().normalize("NFC") : value.toLowerCase();
 }
 export function maxNormalizedUtf8Bytes(value, includeRaw = false) {
+    // ASCII has identical raw, NFC and NFD forms, with one UTF-8 byte per unit.
+    if (typeof value === "string" && !NON_ASCII.test(value))
+        return value.length;
     const nfc = value.normalize("NFC");
     const bytes = Buffer.byteLength(nfc, "utf8");
     const maximum = includeRaw && nfc !== value ? Math.max(bytes, Buffer.byteLength(value, "utf8")) : bytes;

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

@@ -16,12 +16,13 @@ export type WalkDirectoryOptions = {
     include?: (entry: WalkDirectoryEntry) => boolean;
     descend?: (entry: WalkDirectoryEntry) => boolean;
 };
-export type WalkDirectoryFailure = {
-    path: string;
-    relativePath: string;
-    depth: number;
-    error: unknown;
+export type AsyncWalkDirectoryOptions = Omit<WalkDirectoryOptions, "include" | "descend"> & {
+    include?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+    descend?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
 };
+export type WalkDirectoryFailure = Pick<WalkDirectoryEntry & {
+    error: unknown;
+}, "path" | "relativePath" | "depth" | "error">;
 export type WalkDirectoryResult = {
     entries: WalkDirectoryEntry[];
     scannedEntryCount: number;
@@ -32,6 +33,5 @@ type WalkDirectoryResultWithFailures = WalkDirectoryResult & {
     failedDirs: WalkDirectoryFailure[];
 };
 export declare function walkDirectorySync(rootDir: string, options?: WalkDirectoryOptions): WalkDirectoryResultWithFailures;
-export declare function walkDirectory(rootDir: string, options?: WalkDirectoryOptions): Promise<WalkDirectoryResultWithFailures>;
+export declare function walkDirectory(rootDir: string, options?: AsyncWalkDirectoryOptions): Promise<WalkDirectoryResultWithFailures>;
 export {};
-//# sourceMappingURL=walk.d.ts.map

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

@@ -16,6 +16,10 @@ function validateWalkOptions(options) {
         throw new TypeError(`invalid walk symlink policy: ${String(options.symlinks)}`);
     }
 }
+function isObjectResult(result) {
+    return result !== null &&
+        (typeof result === "object" || typeof result === "function");
+}
 function kindForDirent(dirent) {
     if (dirent.isDirectory())
         return "directory";
@@ -85,6 +89,8 @@ export function walkDirectorySync(rootDir, options = {}) {
         let realDir;
         const operationPath = pathForWindowsFilesystem(dir);
         try {
+            if (depth > 1 && symlinks !== "follow" && fsSync.lstatSync(operationPath).isSymbolicLink())
+                return;
             realDir = realpathSync(operationPath);
         }
         catch (error) {
@@ -102,13 +108,14 @@ export function walkDirectorySync(rootDir, options = {}) {
             recordFailedDir(result, root, dir, depth, error);
             return;
         }
+        const childPrefix = dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`;
         for (const dirent of entries) {
             if (shouldStop(result, options)) {
                 result.truncated = true;
                 return;
             }
             result.scannedEntryCount += 1;
-            const fullPath = path.join(dir, dirent.name);
+            const fullPath = childPrefix + dirent.name;
             const kind = resolveKind(fullPath, dirent, symlinks);
             if (!kind)
                 continue;
@@ -146,6 +153,8 @@ export async function walkDirectory(rootDir, options = {}) {
         let realDir;
         const operationPath = pathForWindowsFilesystem(dir);
         try {
+            if (depth > 1 && symlinks !== "follow" && fsSync.lstatSync(operationPath).isSymbolicLink())
+                return;
             realDir = realpathSync.native(operationPath);
         }
         catch (error) {
@@ -163,27 +172,33 @@ export async function walkDirectory(rootDir, options = {}) {
             recordFailedDir(result, root, dir, depth, error);
             return;
         }
+        const childPrefix = dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`;
         for (const dirent of entries) {
             if (shouldStop(result, options)) {
                 result.truncated = true;
                 return;
             }
             result.scannedEntryCount += 1;
-            const fullPath = path.join(dir, dirent.name);
+            const fullPath = childPrefix + dirent.name;
             const kind = resolveKind(fullPath, dirent, symlinks);
             if (!kind)
                 continue;
             const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
             const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
-            if (options.include?.(entry) ?? true) {
+            const include = options.include;
+            const included = include == null ? true : Reflect.apply(include, options, [entry]);
+            if ((isObjectResult(included) ? await included : included) ?? true) {
                 result.entries.push(entry);
             }
             if (kind === "directory" &&
-                (options.maxDepth === undefined || depth < options.maxDepth) &&
-                (options.descend?.(entry) ?? true)) {
-                await visit(fullPath, relativePath, depth + 1);
-                if (result.truncated)
-                    return;
+                (options.maxDepth === undefined || depth < options.maxDepth)) {
+                const descend = options.descend;
+                const descended = descend == null ? true : Reflect.apply(descend, options, [entry]);
+                if ((isObjectResult(descended) ? await descended : descended) ?? true) {
+                    await visit(fullPath, relativePath, depth + 1);
+                    if (result.truncated)
+                        return;
+                }
             }
         }
     }

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

@@ -0,0 +1,6 @@
+import { type RootContext } from "./root-context.js";
+import type { NativeWatchBatch } from "./watch-native.js";
+import type { WatchSnapshot } from "./watch-scan.js";
+import type { WatchChange, WatchScope } from "./watch-types.js";
+/** Resolve native spelling aliases without treating case folding as identity. */
+export declare function admittedNativeChanges(root: RootContext, scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, batch: NativeWatchBatch, signal: AbortSignal, limit: number): Promise<WatchChange[] | undefined>;

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

@@ -0,0 +1,88 @@
+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 { excludedWatchPath, nativeChanges, scopedChanges } from "./watch-hints.js";
+/** Resolve native spelling aliases without treating case folding as identity. */
+export async function admittedNativeChanges(root, scopes, before, after, batch, signal, limit) {
+    if (!nativeChanges(scopes, before, batch, limit, after))
+        return undefined;
+    const result = new Map();
+    const candidates = new Map([...before?.targets ?? [], ...after.targets, ...after.directories]);
+    const add = (change) => {
+        if (!result.has(change.path) && result.size >= limit)
+            return false;
+        const prior = result.get(change.path);
+        result.set(change.path, prior?.type === "structural" ? prior : change);
+        return true;
+    };
+    for (const hint of batch.hints) {
+        signal.throwIfAborted();
+        const name = hint.name; // nativeChanges rejected unknown or non-literal names.
+        let parent = hint.directory;
+        const relative = parent ? path.join(parent, name) : name;
+        if (excludedWatchPath(before, relative) || excludedWatchPath(after, relative))
+            continue;
+        let guard;
+        let expected = after.directories.get(parent);
+        if (!expected) {
+            // Native recursion observes one Root handle and may report descendants of
+            // unselected/entry-only directories. Admit a parent alias by exact identity,
+            // not by lowercasing, and do not turn unselected descendants into events.
+            try {
+                const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
+                guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
+            }
+            catch (error) {
+                await assertRootIdentityCurrent(root);
+                if (isNotFoundPathError(error) || (error instanceof FsSafeError && ["not-found", "path-alias", "outside-workspace", "symlink", "not-file"].includes(error.code)))
+                    continue;
+                throw error;
+            }
+            const admitted = [...after.directories].find(([, identity]) => identity.dev === guard.stat.dev && identity.ino === guard.stat.ino);
+            if (!admitted)
+                continue;
+            [parent, expected] = admitted;
+        }
+        const candidate = parent ? path.join(parent, name) : name;
+        if (excludedWatchPath(before, candidate) || excludedWatchPath(after, candidate))
+            continue;
+        const selected = scopedChanges(scopes, { path: candidate,
+            type: hint.event === "change" && before?.entries.get(candidate)?.startsWith("file:") ? "content" : "structural" });
+        if (selected.length) {
+            for (const change of selected)
+                if (!add(change))
+                    return undefined;
+            continue;
+        }
+        if (!guard) {
+            const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
+            guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
+        }
+        if (guard.stat.dev !== expected.dev || guard.stat.ino !== expected.ino) {
+            throw new FsSafeError("path-mismatch", "watch hint parent changed during reconciliation");
+        }
+        const found = await lookupRootDirectoryEntry(root, guard, name);
+        signal.throwIfAborted();
+        // A missing unselected sibling is not evidence of lost selected detail.
+        // Previously observed selected deletions remain visible in the snapshot diff;
+        // an unseen, already-gone name has no identity proving a selected alias.
+        if (!found)
+            continue;
+        for (const [relative, identity] of candidates) {
+            if (!relative || (path.dirname(relative) === "." ? "" : path.dirname(relative)) !== parent)
+                continue;
+            if (identity.dev !== found.identity.dev || identity.ino !== found.identity.ino)
+                continue;
+            for (const change of scopedChanges(scopes, { path: relative, type: "structural" }))
+                if (!add(change))
+                    return undefined;
+        }
+        await assertRootDirectoryObservationGuard(root, guard);
+    }
+    await assertRootIdentityCurrent(root);
+    signal.throwIfAborted();
+    return [...result.values()];
+}

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

@@ -0,0 +1,9 @@
+import type { NativeWatchBatch } from "./watch-native.js";
+import type { WatchSnapshot } from "./watch-scan.js";
+import type { WatchChange, WatchScope } from "./watch-types.js";
+export declare function excludedWatchPath(snapshot: WatchSnapshot | undefined, name: string): boolean;
+export declare function scopedChanges(scopes: readonly WatchScope[], change: WatchChange): WatchChange[];
+export declare function nativeChanges(scopes: readonly WatchScope[], snapshot: WatchSnapshot | undefined, batch: NativeWatchBatch, limit?: number, after?: WatchSnapshot): WatchChange[] | undefined;
+export declare function changedEntries(before: WatchSnapshot | undefined, after: WatchSnapshot, limit: number): WatchChange[] | undefined;
+/** Backend names never establish authority to publish a pathname. */
+export declare function guardedHintChanges(scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, hints: readonly WatchChange[] | undefined, observed: readonly WatchChange[] | undefined, limit: number): WatchChange[] | undefined;