@openclaw/openshell-sandbox 2026.10.5-beta.4 → 2026.10.10-beta.2

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

@@ -54,36 +54,102 @@ import fs from "node:fs";
 import { randomUUID } from "node:crypto";
 import fsAsync from "node:fs/promises";
 import path from "node:path";
-import { assertSyncDirectoryGuard } from "./directory-guard.js";
+import { assertSyncDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
 import { assertDarwinCreationAcl, assertPrivateDirectory } from "./creation-boundary.js";
 import { assertMutationNotDenied } from "./deny-mutations.js";
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
-import { openNativeRootAdmission } from "./native-parent-admission.js";
+import { openExactNativeRootSync, openNativeRootAdmission } from "./native-parent-admission.js";
 import { capturePolicyAwareNativeParent } from "./native-policy-parent.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { hasNodeErrorCode, isNotFoundPathError, isPathInside } from "./path.js";
 import { preparePinnedWriteMutationAdmission } from "./pinned-mutation-admission.js";
 import { resolvePathViaExistingAncestor } from "./root-path-existing.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+import { directoryComponentNotDirectoryError } from "./root-errors.js";
 import { assertRootIdentityCurrentSync } from "./root-context.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { createSuppressedError } from "./suppressed-error.js";
+import { describePolicyStagedDirectory } from "./staged-directory.js";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
+import { isSafePathSegment } from "./safe-path-segment.js";
+import { nativePolicyDirectoryObserver } from "./native-policy-directory-observation.js";
+import { existingCreationParent } from "./root-native-creation-path.js";
+export { probeNativeCreationPath } from "./root-native-creation-path.js";
 export function rootWriteQueueKey(root, relativePath) {
     return `${root.rootReal}\0${relativePath}`;
 }
 export function buildAtomicWriteTempPath(targetPath) {
     return path.join(path.dirname(targetPath), `.fs-safe-${randomUUID()}.tmp`);
 }
+const nativeCreateCollisions = new WeakSet();
+export function isNativeCreateCollision(error) {
+    return typeof error === "object" && error !== null && nativeCreateCollisions.has(error);
+}
 function unavailable() {
     throw new FsSafeError("helper-unavailable", "native confined creation is unavailable");
 }
 async function withNativeDirectory(params, operation, discard) {
-    const binding = getNativeBinding();
+    const binding = getNativeBinding("openBeneath", "mkdirChildBeneath");
     if (!binding?.openBeneath || !binding.mkdirChildBeneath || (params.private && process.platform === "win32"))
         return unavailable();
+    const existing = params.selectedParent ?? existingCreationParent(params);
+    if (existing) {
+        let pending;
+        try {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const rootOwner = __addDisposableResource(env_1, openExactNativeRootSync(binding, {
+                    rootPath: params.root.rootReal, rootIdentity: params.root.rootIdentity,
+                }), false);
+                const close = captureNativeFdClose(binding);
+                const borrowed = existing.path === params.root.rootReal;
+                const fd = borrowed ? rootOwner.fd : binding.openBeneath(rootOwner.fd, existing.relative, existing.flags).fd;
+                const parentOwner = __addDisposableResource(env_1, { [Symbol.dispose]() { if (!borrowed)
+                        close(fd); } }, false);
+                inspectFileIdentitySync(() => borrowed ? rootOwner.stat : fs.fstatSync(fd, { bigint: true }), existing.identity);
+                verifyMkdirDirectory(binding, fd, existing.path);
+                const guard = { dir: existing.path, realPath: existing.path, stat: existing.identity };
+                const assertCurrent = () => {
+                    let currentRoot;
+                    assertRootIdentityCurrentSync(params.root, stat => { currentRoot = stat; });
+                    if (borrowed) {
+                        // Root and parent are the same name in this synchronous fence.
+                        inspectDirectoryIdentitySync(existing.path, existing.identity, currentRoot);
+                        if (realpathSync.native(pathForWindowsFilesystem(existing.path)) !== existing.path) {
+                            throw new FsSafeError("path-mismatch", "directory changed during operation");
+                        }
+                    }
+                    else {
+                        assertSyncDirectoryGuard(guard);
+                    }
+                };
+                pending = { value: await operation(binding, fd, assertCurrent) };
+                return pending.value;
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+        catch (error) {
+            if (pending && discard) {
+                try {
+                    await discard(pending.value);
+                }
+                catch (cleanupError) {
+                    throw createSuppressedError(cleanupError, error, "creation handoff and cleanup failed");
+                }
+            }
+            throw error;
+        }
+    }
     const directoryTarget = params.directory === params.target;
     const canonicalTarget = async (target) => directoryTarget
         ? await resolvePathViaExistingAncestor(target)
@@ -100,14 +166,14 @@ async function withNativeDirectory(params, operation, discard) {
     const close = captureNativeFdClose(binding);
     let pending;
     try {
-        const env_1 = { stack: [], error: void 0, hasError: false };
+        const env_2 = { stack: [], error: void 0, hasError: false };
         try {
             const admitted = await openNativeRootAdmission(binding, {
                 rootPath: params.root.rootReal, rootIdentity: params.root.rootIdentity, operation: "create", reportCloseErrors: true, searchOnly: true,
             });
-            const rootOwner = __addDisposableResource(env_1, admitted.root, true);
+            const rootOwner = __addDisposableResource(env_2, admitted.root, true);
             const descriptors = [];
-            const directoryOwner = __addDisposableResource(env_1, { [Symbol.dispose]() {
+            const directoryOwner = __addDisposableResource(env_2, { [Symbol.dispose]() {
                     const errors = [];
                     for (const fd of descriptors.reverse())
                         try {
@@ -205,12 +271,12 @@ async function withNativeDirectory(params, operation, discard) {
             pending = { value: await operation(binding, current, assertCurrent) };
             return pending.value;
         }
-        catch (e_1) {
-            env_1.error = e_1;
-            env_1.hasError = true;
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
         }
         finally {
-            const result_1 = __disposeResources(env_1);
+            const result_1 = __disposeResources(env_2);
             if (result_1)
                 await result_1;
         }
@@ -227,15 +293,166 @@ async function withNativeDirectory(params, operation, discard) {
         throw error;
     }
 }
+/** Admit only an ordinary direct child; aliases keep the full resolver. */
+export function tryMkdirNativeDirectChild(root, relativePath) {
+    if (!isSafePathSegment(relativePath, { allowDotPrefix: true }) || relativePath.endsWith(".") ||
+        getFsSafeTestHooks()?.beforeRootFallbackMutation)
+        return false;
+    assertRootIdentityCurrentSync(root);
+    const target = path.join(root.rootReal, relativePath);
+    try {
+        const entry = fs.lstatSync(pathForWindowsFilesystem(target), { throwIfNoEntry: false });
+        if (entry && (!entry.isDirectory() ||
+            realpathSync.native(pathForWindowsFilesystem(target)) !== target))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    try {
+        mkdirNativeRootChild({ root, target });
+        return true;
+    }
+    catch (error) {
+        if (hasNodeErrorCode(error, "ENOTDIR"))
+            throw directoryComponentNotDirectoryError(error);
+        throw error;
+    }
+}
 export async function tryMkdirRootNative(params) {
     // The protected Windows creator already verifies the admitted parent identity
     // and uses handle-relative NtCreateFile with its protected security descriptor.
     if (params.private && process.platform === "win32")
         return false;
-    return await withNativeDirectory(params, async (_binding, _fd, assertCurrent) => { assertCurrent(); return true; });
+    try {
+        if (!params.private && !params.policy && !params.assertBeforeMutation &&
+            !getFsSafeTestHooks()?.beforeRootFallbackMutation &&
+            params.originalPath === path.basename(params.target) &&
+            path.dirname(params.target) === params.root.rootReal &&
+            params.directory === params.target) {
+            mkdirNativeRootChild(params);
+            return true;
+        }
+        return await withNativeDirectory(params, async (_binding, _fd, assertCurrent) => { assertCurrent(); return true; });
+    }
+    catch (error) {
+        if (hasNodeErrorCode(error, "ENOTDIR"))
+            throw directoryComponentNotDirectoryError(error);
+        throw error;
+    }
+}
+export function verifyMkdirDirectory(binding, fd, pathname) {
+    const observe = nativePolicyDirectoryObserver(binding, fd, pathname);
+    try {
+        // The native observation compares this retained descriptor before and
+        // after the no-follow name check, including mode, links, and canonical path.
+        if (observe?.())
+            return;
+    }
+    finally {
+        observe?.dispose();
+    }
+    describePolicyStagedDirectory(fd, pathname);
+}
+export function ensureNativeRootCurrent(root) {
+    assertRootIdentityCurrentSync(root);
+    const binding = getNativeBinding("openBeneath", "mkdirChildBeneath");
+    if (!binding?.openBeneath || !binding.mkdirChildBeneath)
+        return unavailable();
+    if (binding.verifyRootDirectory) {
+        const closeNative = captureNativeFdClose(binding);
+        const failure = binding.verifyRootDirectory(root.rootReal, root.rootIdentity.dev, root.rootIdentity.ino);
+        if (failure === null)
+            return;
+        if (failure?.fallbackFd !== undefined && failure.fallbackFd !== null) {
+            const env_3 = { stack: [], error: void 0, hasError: false };
+            try {
+                const fd = failure.fallbackFd;
+                if (!Number.isInteger(fd) || fd < 0)
+                    throw new FsSafeError("helper-failed", "invalid root fallback descriptor");
+                const owner = __addDisposableResource(env_3, { [Symbol.dispose]() { closeNative(fd); } }, false);
+                if (failure.errorCode || failure.closeErrorCode)
+                    throw new FsSafeError("helper-failed", "invalid root verification result");
+                ensureNativeRootCurrentLegacy(root, binding);
+                return;
+            }
+            catch (e_3) {
+                env_3.error = e_3;
+                env_3.hasError = true;
+            }
+            finally {
+                __disposeResources(env_3);
+            }
+        }
+        const error = failure?.errorCode ? rootVerificationError(failure.errorCode, failure.errorMessage, failure.errorErrno) : undefined;
+        const closeError = failure?.closeErrorCode ? Object.assign(new Error(failure.closeErrorMessage), {
+            code: failure.closeErrorCode,
+            ...(typeof failure.closeErrorErrno === "number" ? { errno: failure.closeErrorErrno } : {}),
+        }) : undefined;
+        if (error && closeError)
+            throw createSuppressedError(closeError, error, "root verification and close failed");
+        if (error || closeError)
+            throw error ?? closeError;
+        throw new FsSafeError("helper-failed", "invalid root verification result");
+    }
+    ensureNativeRootCurrentLegacy(root, binding);
+}
+function rootVerificationError(code, message, errno) {
+    const error = Object.assign(new Error(message), { code, ...(typeof errno === "number" ? { errno } : {}) });
+    return code === "path-mismatch" || code === "OBSERVATION_REDIRECTED"
+        ? new FsSafeError("path-mismatch", "root identity changed during verification", { cause: error }) : error;
+}
+function ensureNativeRootCurrentLegacy(root, binding) {
+    const env_4 = { stack: [], error: void 0, hasError: false };
+    try {
+        const rootOwner = __addDisposableResource(env_4, openExactNativeRootSync(binding, {
+            rootPath: root.rootReal, rootIdentity: root.rootIdentity,
+        }), false);
+        verifyMkdirDirectory(binding, rootOwner.fd, root.rootReal);
+        assertRootIdentityCurrentSync(root);
+    }
+    catch (e_4) {
+        env_4.error = e_4;
+        env_4.hasError = true;
+    }
+    finally {
+        __disposeResources(env_4);
+    }
+}
+function mkdirNativeRootChild(params) {
+    const env_5 = { stack: [], error: void 0, hasError: false };
+    try {
+        const binding = getNativeBinding("openBeneath", "mkdirChildBeneath");
+        if (!binding?.openBeneath || !binding.mkdirChildBeneath)
+            return unavailable();
+        const rootOwner = __addDisposableResource(env_5, openExactNativeRootSync(binding, {
+            rootPath: params.root.rootReal, rootIdentity: params.root.rootIdentity,
+        }), false);
+        verifyMkdirDirectory(binding, rootOwner.fd, params.root.rootReal);
+        const flags = (nodeDirectorySearchOnlyFlags()?.flags ?? fs.constants.O_RDONLY) |
+            (fs.constants.O_DIRECTORY ?? 0) | (fs.constants.O_NOFOLLOW ?? 0);
+        const name = path.basename(params.target);
+        // The admitted Root is already this operation's immediate parent. Retain
+        // both handles through the same fresh pathname and canonical identity fences.
+        const child = binding.mkdirOpenChildBeneath
+            ? binding.mkdirOpenChildBeneath(rootOwner.fd, name, 0o777, flags).fd
+            : (binding.mkdirChildBeneath(rootOwner.fd, name, 0o777), binding.openBeneath(rootOwner.fd, name, flags).fd);
+        const close = captureNativeFdClose(binding);
+        const childOwner = __addDisposableResource(env_5, { [Symbol.dispose]() { close(child); } }, false);
+        assertRootIdentityCurrentSync(params.root);
+        verifyMkdirDirectory(binding, child, params.target);
+        verifyMkdirDirectory(binding, rootOwner.fd, params.root.rootReal);
+    }
+    catch (e_5) {
+        env_5.error = e_5;
+        env_5.hasError = true;
+    }
+    finally {
+        __disposeResources(env_5);
+    }
 }
 export async function tryOpenCreateRootNative(params) {
-    const binding = getNativeBinding();
+    const binding = getNativeBinding("openBeneath", "mkdirChildBeneath", "removeStagedFile", "openCreateBeneath");
     if (!binding?.removeStagedFile || !binding.openCreateBeneath)
         return unavailable();
     const access = (params.existingFlags & fs.constants.O_RDWR) ? 0o600 : 0o200;
@@ -253,7 +470,7 @@ export async function tryOpenCreateRootNative(params) {
     if (creationMode() === undefined)
         return unavailable();
     return await withNativeDirectory(params, async (binding, parent, assertCurrent) => {
-        const env_2 = { stack: [], error: void 0, hasError: false };
+        const env_6 = { stack: [], error: void 0, hasError: false };
         try {
             params.assertBeforeMutation?.();
             assertCurrent();
@@ -263,13 +480,21 @@ export async function tryOpenCreateRootNative(params) {
             // Native creation owns the only O_CREAT dispatch. The subsequent Node open
             // carries neither O_CREAT nor O_TRUNC and must match this retained inode.
             const close = captureNativeFdClose(binding);
-            const fd = binding.openCreateBeneath(parent, path.basename(params.target), params.flags, params.mode & 0o7777);
+            let fd;
+            try {
+                fd = binding.openCreateBeneath(parent, path.basename(params.target), params.flags, params.mode & 0o7777);
+            }
+            catch (error) {
+                if (hasNodeErrorCode(error, "EEXIST") && typeof error === "object" && error !== null)
+                    nativeCreateCollisions.add(error);
+                throw error;
+            }
             let rawOpen = true;
             const closeRaw = () => { if (rawOpen) {
                 rawOpen = false;
                 close(fd);
             } };
-            const owner = __addDisposableResource(env_2, { [Symbol.dispose]: closeRaw }, false);
+            const owner = __addDisposableResource(env_6, { [Symbol.dispose]: closeRaw }, false);
             try {
                 const identity = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }));
                 if (!identity.isFile() || identity.nlink !== 1n)
@@ -323,26 +548,26 @@ export async function tryOpenCreateRootNative(params) {
                 throw error;
             }
         }
-        catch (e_2) {
-            env_2.error = e_2;
-            env_2.hasError = true;
+        catch (e_6) {
+            env_6.error = e_6;
+            env_6.hasError = true;
         }
         finally {
-            __disposeResources(env_2);
+            __disposeResources(env_6);
         }
     }, async (created) => {
-        const env_3 = { stack: [], error: void 0, hasError: false };
+        const env_7 = { stack: [], error: void 0, hasError: false };
         try {
-            const handle = __addDisposableResource(env_3, created.handle, true);
-            const parent = __addDisposableResource(env_3, { [Symbol.dispose]: created.releaseCreationParent }, false);
+            const handle = __addDisposableResource(env_7, created.handle, true);
+            const parent = __addDisposableResource(env_7, { [Symbol.dispose]: created.releaseCreationParent }, false);
             await created.cleanupCreated();
         }
-        catch (e_3) {
-            env_3.error = e_3;
-            env_3.hasError = true;
+        catch (e_7) {
+            env_7.error = e_7;
+            env_7.hasError = true;
         }
         finally {
-            const result_2 = __disposeResources(env_3);
+            const result_2 = __disposeResources(env_7);
             if (result_2)
                 await result_2;
         }

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

@@ -198,10 +198,14 @@ export async function mkdirPathFallback(root, resolved, assertBeforeMutation, re
     const baseParams = {
         rootReal: resolved.rootReal, targetPath: resolved.resolved, assertBeforeMutation,
         rootIdentity: root.rootIdentity,
+        synchronousMkdir: !privateMode && !mutationAdmission && !assertBeforeMutation &&
+            !getFsSafeTestHooks()?.beforeRootFallbackMutation,
         rejectSymlinks,
         private: privateMode,
         mode: privateMode ? 0o700 : undefined,
-        beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
+        beforeComponent: getFsSafeTestHooks()?.beforeRootFallbackMutation
+            ? (componentPath) => getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath)
+            : undefined,
     };
     const mutationWalk = mutationAdmission
         ? mutationWalkOptions(mutationAdmission, (prospectiveDirectory) => prospectiveDirectory, assertBeforeMutation, root.rootReal, resolved.resolved)

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

@@ -5,17 +5,20 @@ export type RootDirectoryListingPaths = {
     directory: string;
     names: Map<string, string>;
 };
+export type RootDirectoryListingResult = {
+    kind: "entry";
+    entry: DirEntry;
+    identity?: ExactStatIdentity;
+} | {
+    kind: "limit";
+    name: string;
+} | undefined;
 export type RootDirectoryListing = {
     paths: RootDirectoryListingPaths;
     assertCurrent(): Promise<void>;
-    next(): Promise<{
-        kind: "entry";
-        entry: DirEntry;
-        identity?: ExactStatIdentity;
-    } | {
-        kind: "limit";
-        name: string;
-    } | undefined>;
+    next(): Promise<RootDirectoryListingResult>;
+    /** Only a complete, already-fenced snapshot can be consumed without awaiting. */
+    nextSnapshot?: () => RootDirectoryListingResult;
     [Symbol.asyncDispose](): Promise<void>;
 };
 export type RootDirectoryListingOptions = {

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

@@ -1,3 +1,4 @@
+import { exactFileIdentity, numberStatScalar } from "./exact-identity.js";
 import { isUtf8 } from "node:buffer";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
@@ -21,6 +22,15 @@ function directoryEntryName(bytes) {
     }
     return bytes.toString("utf8");
 }
+async function readDirectoryNames(directory) {
+    const names = await fs.readdir(directory);
+    // Invalid UTF-8 always decodes to U+FFFD. Re-read suspect batches as bytes
+    // so literal U+FFFD names remain valid without returning a lossy spelling.
+    if (names.some(name => name.includes("\ufffd"))) {
+        return (await fs.readdir(directory, { encoding: "buffer" })).map(directoryEntryName);
+    }
+    return names;
+}
 async function readDirectoryEntryName(handle, synchronous = false) {
     const entry = synchronous ? handle.readSync() : await handle.read();
     // Bun returns the raw Buffer directly; Node returns a Dirent whose name is a Buffer.
@@ -37,13 +47,16 @@ export function pathStatFromStats(stat, name) {
             ? Number(stat.mtimeNs) / 1_000_000
             : stat.mtime.getTime()
         : stat.mtimeMs;
-    const dev = Number(stat.dev), gid = Number(stat.gid), ino = Number(stat.ino);
+    const exactIdentity = exactFileIdentity(stat);
+    const dev = numberStatScalar(stat.dev), gid = numberStatScalar(stat.gid), ino = numberStatScalar(stat.ino);
     const isDirectory = stat.isDirectory(), isFile = stat.isFile(), isSymbolicLink = stat.isSymbolicLink();
-    const mode = Number(stat.mode), nlink = Number(stat.nlink), size = Number(stat.size), uid = Number(stat.uid);
+    const mode = numberStatScalar(stat.mode), nlink = numberStatScalar(stat.nlink), size = numberStatScalar(stat.size), uid = numberStatScalar(stat.uid);
     // Construct named metadata directly, preserving property order without a spread copy.
-    return name === undefined
+    const result = name === undefined
         ? { dev, gid, ino, isDirectory, isFile, isSymbolicLink, mode, mtimeMs, nlink, size, uid }
         : { name, dev, gid, ino, isDirectory, isFile, isSymbolicLink, mode, mtimeMs, nlink, size, uid };
+    // PathStat's established JSON shape stays numeric. Retain this object or copy the companion explicitly.
+    return Object.defineProperty(result, "exactIdentity", { value: exactIdentity });
 }
 export async function createRootDirectoryObservationGuard(root, directory) {
     const guard = await createAsyncDirectoryGuard(directory, { bigint: true });
@@ -207,11 +220,11 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
         const beforeObservation = getFsSafeTestHooks()?.beforeRootListObservation;
         if (beforeObservation)
             await beforeObservation(guard.realPath, withFileTypes);
-        const names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName).sort();
+        const names = (await readDirectoryNames(guard.realPath)).sort();
         if (withFileTypes) {
             // readdir supplies literal child names beneath the already-canonical directory.
             const prefix = guard.realPath.endsWith(path.sep) ? guard.realPath : `${guard.realPath}${path.sep}`;
-            entries = names.map(name => pathStatFromStats(fsSync.lstatSync(`${prefix}${name}`), name));
+            entries = names.map(name => pathStatFromStats(fsSync.lstatSync(`${prefix}${name}`, { bigint: true }), name));
         }
         else {
             entries = names;
@@ -339,7 +352,7 @@ export async function openRootDirectoryListing(root, directory, options, receipt
         preparedIndex = 0;
         while (true) {
             try {
-                const entry = pathStatFromStats(fsSync.lstatSync(path.join(guard.realPath, name)), name);
+                const entry = pathStatFromStats(fsSync.lstatSync(path.join(guard.realPath, name), { bigint: true }), name);
                 prepared.push(entry);
                 // No later sibling can be observed before a possible recursive descent.
                 if (entry.isDirectory || entry.isSymbolicLink || prepared.length >= (options.metadataBatchSize ?? METADATA_BATCH_SIZE))
@@ -367,18 +380,27 @@ export async function openRootDirectoryListing(root, directory, options, receipt
             throw error;
         }
     };
+    const nextSnapshot = snapshot ? () => {
+        try {
+            options.signal?.throwIfAborted();
+            const entry = snapshot[index++];
+            if (!entry)
+                return;
+            return options.admitEntry() ? { kind: "entry", entry } : { kind: "limit", name: entry.name };
+        }
+        catch (error) {
+            throw normalizeDirectoryError(error);
+        }
+    } : undefined;
     return {
         paths,
         assertCurrent,
+        nextSnapshot,
         async next() {
             try {
+                if (nextSnapshot)
+                    return nextSnapshot();
                 options.signal?.throwIfAborted();
-                if (snapshot) {
-                    const entry = snapshot[index++];
-                    if (!entry)
-                        return;
-                    return options.admitEntry() ? { kind: "entry", entry } : { kind: "limit", name: entry.name };
-                }
                 if (names) {
                     if (preparedIndex >= prepared.length && !pendingFailure && pendingLimit === undefined) {
                         await prepareBatch(names);
@@ -409,7 +431,7 @@ export async function openRootDirectoryListing(root, directory, options, receipt
                     let observed;
                     try {
                         observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
-                            ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : { stat: fsSync.lstatSync(pathname) };
+                            ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : { stat: fsSync.lstatSync(pathname, { bigint: true }) };
                     }
                     catch (error) {
                         await assertCurrent();

package/node_modules/@openclaw/fs-safe/dist/root-file-open-batch-sync.d.ts

@@ -0,0 +1,8 @@
+import { type OpenRootFileSyncParams, type RootFileOpenResult } from "./root-file.js";
+export type RootFileOpenBatchSync = {
+    openFile(params: OpenRootFileSyncParams): RootFileOpenResult;
+    close(): void;
+    [Symbol.dispose](): void;
+};
+/** Reuses native Windows root handles; other reads keep their one-shot admission. */
+export declare function createRootFileOpenBatchSync(): RootFileOpenBatchSync;

package/node_modules/@openclaw/fs-safe/dist/root-file-open-batch-sync.js

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { openExactNativeRootSync } from "./native-parent-admission.js";
+import { isExpectedPathError } from "./pinned-open.js";
+import { realpathSync } from "./realpath.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { observeCanonicalRoot } from "./root-file-final-admission.js";
+import { openRootFileSync, openRootFileWithRetainedRootSync } from "./root-file.js";
+import { hasWindowsPathAlias } from "./windows-path-alias.js";
+const WINDOWS_ERROR_REPARSE_POINT_ENCOUNTERED = 4395;
+function canRetainRoot(params) {
+    return process.platform === "win32" && typeof params.rootPath === "string" &&
+        typeof params.absolutePath === "string" && params.ioFs === undefined &&
+        params.rootRealPath === undefined && !params.skipLexicalRootCheck &&
+        (params.symlinks === "reject" || (params.symlinks === undefined && params.rejectSymlinks !== false)) &&
+        /^[a-z]:\\/iu.test(params.rootPath) &&
+        !hasWindowsPathAlias(params.rootPath, "filesystem") &&
+        !hasWindowsPathAlias(params.absolutePath, "filesystem") &&
+        !params.absolutePath.slice(3).split("\\").some(segment => /[. ]$/u.test(segment) || segment.includes("~")) &&
+        !params.rootPath.includes("\0") && !params.absolutePath.includes("\0") &&
+        path.resolve(params.rootPath) === params.rootPath && path.resolve(params.absolutePath) === params.absolutePath &&
+        params.absolutePath.startsWith(params.rootPath.endsWith(path.sep) ? params.rootPath : `${params.rootPath}${path.sep}`);
+}
+function failure(error) {
+    return { ok: false, reason: error instanceof FsSafeError ? "validation" : isExpectedPathError(error) ? "path" : "io", error };
+}
+/** Reuses native Windows root handles; other reads keep their one-shot admission. */
+export function createRootFileOpenBatchSync() {
+    const roots = new Map();
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        let error;
+        let failed = false;
+        for (const { owner } of roots.values()) {
+            try {
+                owner.close();
+            }
+            catch (cause) {
+                if (!failed) {
+                    failed = true;
+                    error = cause;
+                }
+            }
+        }
+        roots.clear();
+        if (failed)
+            throw error;
+    };
+    return Object.freeze({
+        openFile(input) {
+            if (closed)
+                return failure(new FsSafeError("invalid-path", "open batch is closed"));
+            const params = {
+                absolutePath: input.absolutePath, rootPath: input.rootPath,
+                boundaryLabel: input.boundaryLabel, rootRealPath: input.rootRealPath,
+                maxBytes: input.maxBytes, rejectHardlinks: input.rejectHardlinks,
+                rejectSymlinks: input.rejectSymlinks, symlinks: input.symlinks,
+                allowedType: input.allowedType, skipLexicalRootCheck: input.skipLexicalRootCheck,
+                ioFs: input.ioFs,
+            };
+            try {
+                if (!canRetainRoot(params))
+                    return openRootFileSync(params);
+                const binding = getNativeBinding("openBeneath");
+                const openBeneath = binding?.openBeneath;
+                if (!binding || !openBeneath)
+                    return openRootFileSync(params);
+                let retained = roots.get(params.rootPath);
+                if (!retained) {
+                    if (realpathSync(params.rootPath) !== params.rootPath)
+                        return openRootFileSync(params);
+                    const observation = observeCanonicalRoot(fs, params.rootPath);
+                    if (!observation.ok)
+                        return failure(observation.error);
+                    const owner = openExactNativeRootSync(binding, { rootPath: observation.path, rootIdentity: observation.identity });
+                    retained = { owner, observation };
+                    roots.set(params.rootPath, retained);
+                }
+                const { owner, observation } = retained;
+                inspectDirectoryIdentitySync(observation.path, observation.identity);
+                let admittedFd;
+                try {
+                    // Reject reparses before any full-leaf pathname observation can follow them.
+                    admittedFd = openBeneath.call(binding, owner.fd, path.relative(params.rootPath, params.absolutePath), resolveReadOpenFlags()).fd;
+                }
+                catch (error) {
+                    const failure = error;
+                    if (failure?.code === "ELOOP" || failure?.errno === WINDOWS_ERROR_REPARSE_POINT_ENCOUNTERED) {
+                        throw new FsSafeError("symlink", "symlink not allowed", { cause: error });
+                    }
+                    throw error;
+                }
+                return openRootFileWithRetainedRootSync(params, observation, admittedFd);
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+        close,
+        [Symbol.dispose]: close,
+    });
+}