@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

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

@@ -2,6 +2,10 @@ import path from "node:path";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { isPathRelativeEscape } from "./path.js";
 import { realpathSync } from "./realpath.js";
+export function sameNormalizedPathSpelling(left, right) {
+    // Preserve case on Windows, where individual directories can be case-sensitive.
+    return path.resolve(left) === path.resolve(right);
+}
 function windowsComparablePath(value, normalize) {
     const original = normalize
         ? path.win32.normalize(value.replaceAll("/", "\\"))

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

@@ -41,12 +41,3 @@ export declare function resolvePathInRoot(root: RootContext, relativePath: strin
     rootWithSep: string;
     resolved: string;
 }>;
-export declare function resolvePathWithinRoot(params: {
-    rootDir: string;
-    relativePath: string;
-}): Promise<{
-    rootReal: string;
-    rootWithSep: string;
-    resolved: string;
-}>;
-//# sourceMappingURL=root-context.d.ts.map

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

@@ -7,7 +7,7 @@ import { sameFileIdentity } from "./file-identity.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
-import { outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
+import { errorCauseOptions, outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
 import { isDriveRelativePath } from "./safe-path-segment.js";
 import { realpathSync } from "./realpath.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
@@ -107,7 +107,7 @@ export function rootRelativeReadPath(root, filePath) {
                 resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
             });
             if (admitted)
-                return admitted.relativePath;
+                return `.${path.sep}${admitted.relativePath}`;
             continue;
         }
         const prefix = ensureTrailingSep(base);
@@ -116,7 +116,8 @@ export function rootRelativeReadPath(root, filePath) {
             let start = prefix.length;
             while (raw[start] === path.sep)
                 start += 1;
-            return raw.slice(start);
+            // An admitted absolute tail stays literal, including a leading home marker.
+            return `.${path.sep}${raw.slice(start)}`;
         }
     }
     return raw;
@@ -223,17 +224,10 @@ export async function resolvePathInRoot(root, relativePath, options) {
             throw error;
         }
         if (hasNodeErrorCode(error, "ENAMETOOLONG")) {
-            throw new FsSafeError("invalid-path", "relative path is too long", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("invalid-path", "relative path is too long", errorCauseOptions(error));
         }
         const code = options?.aliasErrorCode ?? "outside-workspace";
-        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", errorCauseOptions(error));
     }
     return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
 }
-export async function resolvePathWithinRoot(params) {
-    return await resolvePathInRoot(await resolveRootContext(params.rootDir), params.relativePath);
-}

package/node_modules/@openclaw/fs-safe/dist/root-create-input.d.ts

@@ -1,10 +1,16 @@
-import type { PinnedWriteInput } from "./pinned-write.js";
+import type { PinnedWriteInput } from "./pinned-write-types.js";
 import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
-export type RootWriteParams = RootWriteOptions & RootCreateStreamOptions & {
+declare const exclusiveSidecarCreate: unique symbol;
+export declare const sidecarExclusiveCreate: Readonly<{
+    [exclusiveSidecarCreate]: true;
+}>;
+export type RootWriteParams = RootWriteOptions & RootCreateOptions & RootCreateStreamOptions & {
     relativePath: string;
     data: string | Buffer | AsyncIterable<Uint8Array>;
+    strictFileSync?: boolean;
+    [exclusiveSidecarCreate]?: true;
 };
 export declare function rethrowCreateInputError(error: unknown): never;
 export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
 export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
-//# sourceMappingURL=root-create-input.d.ts.map
+export {};

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

@@ -1,6 +1,10 @@
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 import { MutationAuthorityError } from "./mutation-authority.js";
+// Lock records need exclusive creation, not private-before-visible publication.
+// Keep this composition hook off the public Root options and package exports.
+const exclusiveSidecarCreate = Symbol("exclusiveSidecarCreate");
+export const sidecarExclusiveCreate = Object.freeze({ [exclusiveSidecarCreate]: true });
 class CreateInputError extends FsSafeError {
     rejection;
     constructor(rejection) {
@@ -16,24 +20,33 @@ export function rethrowCreateInputError(error) {
 export function createInputOptions(data, options, defaultMaxBytes) {
     if (typeof data === "string" || Buffer.isBuffer(data))
         return options;
-    options.signal?.throwIfAborted();
+    const { signal } = options;
+    signal?.throwIfAborted();
     if (options.encoding !== undefined || options.renameIdentity !== undefined) {
         throw new TypeError("streamed create does not accept encoding or renameIdentity");
     }
     const maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: defaultMaxBytes });
+    const { assertBeforeMutation } = options;
     return {
         ...options,
         maxBytes,
+        signal,
         assertBeforeMutation: () => {
-            options.signal?.throwIfAborted();
-            return options.assertBeforeMutation?.();
+            signal?.throwIfAborted();
+            return assertBeforeMutation == null ? undefined : Reflect.apply(assertBeforeMutation, options, []);
         },
     };
 }
 export function rootWriteInput(params) {
+    if (params.atomic !== undefined && typeof params.atomic !== "boolean") {
+        throw new TypeError("atomic must be a boolean");
+    }
     const data = params.data;
     if (typeof data === "string" || Buffer.isBuffer(data)) {
-        return { kind: "buffer", data, encoding: params.encoding };
+        return {
+            kind: "buffer", data, encoding: params.encoding,
+            stageBeforePublish: params[exclusiveSidecarCreate] ? false : params.atomic === true ? true : undefined,
+        };
     }
     return {
         kind: "stream",

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

@@ -1,13 +1,12 @@
-import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
-import type { RootContext } from "./root-context.js";
+import type { PinnedWriteMutationAdmission } from "./pinned-write-types.js";
+import { type RootContext } from "./root-context.js";
 /**
  * Complete the common Root.mkdir case with one exact existing parent. This is
  * optional evidence: every uncertain probe returns to the ordered root walk.
  */
 export declare function tryMkdirAtExactParent(root: RootContext, targetPath: string, mutationAdmission: PinnedWriteMutationAdmission): Promise<boolean>;
-export declare function prepareRootWriteTarget(root: RootContext, targetPath: string, assertBeforeMutation?: () => void, mutationAdmission?: PinnedWriteMutationAdmission): Promise<string>;
+export declare function prepareRootWriteTarget(root: RootContext, targetPath: string, assertBeforeMutation?: () => void, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<string>;
 export declare function mkdirPathFallback(root: RootContext, resolved: {
     rootReal: string;
     resolved: string;
-}, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission): Promise<void>;
-//# sourceMappingURL=root-directory-creation.d.ts.map
+}, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<void>;

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

@@ -1,16 +1,19 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { assertPrivateDirectory } from "./creation-boundary.js";
 import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { hasNodeErrorCode } from "./path.js";
 import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-function mutationWalkOptions(mutationAdmission, operationTarget, assertBeforeMutation) {
-    const session = assertBeforeMutation === undefined
+function mutationWalkOptions(mutationAdmission, operationTarget, assertBeforeMutation, rootPath, targetPath) {
+    const session = canReuseParentWithMutationAssertion(assertBeforeMutation, rootPath, targetPath)
         ? mutationAdmission.beginSharedParentWalk?.()
         : undefined;
     return {
@@ -164,16 +167,18 @@ export async function tryMkdirAtExactParent(root, targetPath, mutationAdmission)
         session.dispose();
     }
 }
-export async function prepareRootWriteTarget(root, targetPath, assertBeforeMutation, mutationAdmission) {
+export async function prepareRootWriteTarget(root, targetPath, assertBeforeMutation, mutationAdmission, privateMode = false) {
     const basename = path.basename(targetPath);
     const baseParams = {
         rootReal: root.rootReal,
         rootIdentity: root.rootIdentity,
         targetPath: path.dirname(targetPath),
         assertBeforeMutation,
+        private: privateMode,
+        mode: privateMode ? 0o700 : undefined,
     };
     const mutationWalk = mutationAdmission
-        ? mutationWalkOptions(mutationAdmission, (prospectiveParent) => path.join(prospectiveParent, basename), assertBeforeMutation)
+        ? mutationWalkOptions(mutationAdmission, (prospectiveParent) => path.join(prospectiveParent, basename), assertBeforeMutation, root.rootReal, targetPath)
         : undefined;
     let parentPath;
     try {
@@ -189,22 +194,30 @@ export async function prepareRootWriteTarget(root, targetPath, assertBeforeMutat
     // the original path through a symlinked component.
     return path.join(parentPath, basename);
 }
-export async function mkdirPathFallback(root, resolved, assertBeforeMutation, rejectSymlinks = false, mutationAdmission) {
+export async function mkdirPathFallback(root, resolved, assertBeforeMutation, rejectSymlinks = false, mutationAdmission, privateMode = false) {
     const baseParams = {
         rootReal: resolved.rootReal, targetPath: resolved.resolved, assertBeforeMutation,
         rootIdentity: root.rootIdentity,
         rejectSymlinks,
+        private: privateMode,
+        mode: privateMode ? 0o700 : undefined,
         beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
     };
     const mutationWalk = mutationAdmission
-        ? mutationWalkOptions(mutationAdmission, (prospectiveDirectory) => prospectiveDirectory, assertBeforeMutation)
+        ? mutationWalkOptions(mutationAdmission, (prospectiveDirectory) => prospectiveDirectory, assertBeforeMutation, root.rootReal, resolved.resolved)
         : undefined;
     try {
-        await mkdirPathComponentsWithGuards(mutationWalk ? {
+        const directory = await mkdirPathComponentsWithGuards(mutationWalk ? {
             ...baseParams,
             ...mutationWalk.options,
             rejectSymlinks: rejectSymlinks || mutationAdmission.rejectParentSymlinks,
         } : baseParams);
+        if (privateMode) {
+            const guard = await createAsyncDirectoryGuard(directory, { bigint: true });
+            await assertPrivateDirectory(directory);
+            await assertAsyncDirectoryGuard(guard);
+            await assertRootIdentityCurrent(root);
+        }
     }
     finally {
         mutationWalk?.dispose();

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

@@ -0,0 +1,9 @@
+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";
+/** 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<{
+    entry: DirEntry;
+    identity: ExactStatIdentity;
+} | undefined>;

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

@@ -0,0 +1,28 @@
+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";
+/** One literal entry lookup under an operation-local admitted parent; never follow the leaf. */
+export async function lookupRootDirectoryEntry(root, guard, name) {
+    if (!name || name === "." || name === ".." || path.basename(name) !== name || path.isAbsolute(name)) {
+        throw new FsSafeError("invalid-path", "directory lookup requires one literal name");
+    }
+    assertValidRootRelativePath(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));
+        await assertRootDirectoryObservationGuard(root, guard);
+        return { entry: { name, ...pathStatFromStats(observed.stat) }, identity: observed.identity };
+    }
+    catch (error) {
+        await assertRootDirectoryObservationGuard(root, guard);
+        if (isNotFoundPathError(error))
+            return undefined;
+        throw error;
+    }
+}

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

@@ -2,6 +2,7 @@ import type { BigIntStats, Stats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type RootContext } from "./root-context.js";
 import type { RootPathDirectoryObservationGuard, RootPathObservationReceipt, RootPathParentObservationReceipt } from "./root-path.js";
+import { type ExactStatIdentity } from "./stat-observation.js";
 import type { DirEntry, PathStat } from "./types.js";
 export declare function pathStatFromStats(stat: Stats | BigIntStats): PathStat;
 export type RootDirectoryObservationGuard = AsyncDirectoryGuard<BigIntStats>;
@@ -17,9 +18,11 @@ export declare function assertRootPathObservationReceiptCurrent(root: RootContex
 export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: true, receipt?: RootPathObservationReceipt): Promise<DirEntry[]>;
 export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: boolean, receipt?: RootPathObservationReceipt): Promise<string[] | DirEntry[]>;
 export type RootDirectoryListing = {
+    assertCurrent(): Promise<void>;
     next(): Promise<{
         kind: "entry";
         entry: DirEntry;
+        identity?: ExactStatIdentity;
     } | {
         kind: "limit";
         name: string;
@@ -32,7 +35,12 @@ export type RootDirectoryListingOptions = {
     snapshot: boolean;
     maxNames?: number;
     metadataBatchSize?: number;
+    /** Internal exact metadata lane, supported by streaming filesystem order. */
+    exactIdentity?: boolean;
+    /** Advisory scans may omit vanished leaves after revalidating their parent. */
+    skipVanished?: boolean;
+    /** Internal owner receives cleanup failures, including acquisition rollback. */
+    onCleanupFailure?: (error: unknown) => void;
     admitEntry(): boolean;
 };
-export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
-//# sourceMappingURL=root-directory-list.d.ts.map
+export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;

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

@@ -1,18 +1,36 @@
+import { isUtf8 } from "node:buffer";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { setImmediate as yieldToEventLoop } from "node:timers/promises";
-import { assertAsyncDirectoryGuard, assertDirectoryObservationGuardSync, assertDirectoryObservationSync, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, assertDirectoryObservationGuardSync, assertDirectoryObservationSync, createAsyncDirectoryGuard, extendDirectoryObservationGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
-import { rootPathChangedError } from "./root-errors.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 { getFsSafeTestHooks } from "./test-hooks.js";
 const METADATA_BATCH_SIZE = 32;
+function directoryEntryName(bytes) {
+    if (!isUtf8(bytes)) {
+        throw new FsSafeError("invalid-path", "directory entry name is not valid UTF-8");
+    }
+    return bytes.toString("utf8");
+}
+async function readDirectoryEntryName(handle) {
+    const entry = await handle.read();
+    // Bun returns the raw Buffer directly; Node returns a Dirent whose name is a Buffer.
+    // Node's Dir types still declare only string names.
+    return entry === null ? undefined
+        : directoryEntryName(Buffer.isBuffer(entry) ? entry : entry.name);
+}
+function openDirectoryNames(directory) {
+    return fs.opendir(directory, { bufferSize: 1, encoding: "buffer" });
+}
 export function pathStatFromStats(stat) {
     const mtimeMs = typeof stat.mtimeMs === "bigint"
         ? "mtimeNs" in stat && typeof stat.mtimeNs === "bigint"
@@ -50,9 +68,7 @@ export async function createRootDirectoryObservationGuard(root, directory) {
 function directoryChangedError(error) {
     if (error instanceof FsSafeError && error.code === "path-mismatch")
         return error;
-    return new FsSafeError("path-mismatch", "directory changed during operation", {
-        cause: error instanceof Error ? error : undefined,
-    });
+    return new FsSafeError("path-mismatch", "directory changed during operation", errorCauseOptions(error));
 }
 export async function assertRootDirectoryObservationGuard(root, guard) {
     if (isNativeDirectoryObservationGuard(guard)) {
@@ -73,7 +89,18 @@ export async function assertRootDirectoryObservationGuard(root, guard) {
         }
         return;
     }
-    await assertRootIdentityCurrent(root);
+    if ("identity" in guard && typeof root.rootIdentity.dev === "bigint" &&
+        typeof root.rootIdentity.ino === "bigint") {
+        try {
+            assertDirectoryObservationSync(root.rootReal, root.rootIdentity);
+        }
+        catch (error) {
+            throw rootPathChangedError(error instanceof Error ? error : undefined);
+        }
+    }
+    else {
+        await assertRootIdentityCurrent(root);
+    }
     try {
         if ("identity" in guard)
             assertDirectoryObservationGuardSync(guard);
@@ -151,9 +178,7 @@ export function assertRootPathObservationReceiptCurrent(root, receipt, finalTarg
 }
 function normalizeDirectoryError(error) {
     if (isNotFoundPathError(error)) {
-        return new FsSafeError("not-found", "directory not found", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("not-found", "directory not found", errorCauseOptions(error));
     }
     return error;
 }
@@ -166,14 +191,7 @@ function normalizeInitialDirectoryError(error) {
 export async function listDirectoryPath(root, directory, withFileTypes, receipt) {
     let guard;
     if (receipt) {
-        if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
-            receipt.directoryGuard.dir !== directory ||
-            receipt.target !== receipt.directoryGuard ||
-            (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
-                !receipt.directoryGuard.stat.isDirectory())) {
-            throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
-        }
-        guard = receipt.directoryGuard;
+        guard = directoryGuardFromReceipt(directory, receipt);
     }
     else {
         try {
@@ -185,13 +203,23 @@ export async function listDirectoryPath(root, directory, withFileTypes, receipt)
     }
     return await listGuardedDirectoryPath(root, guard, withFileTypes, receipt);
 }
+function directoryGuardFromReceipt(directory, receipt) {
+    if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
+        receipt.directoryGuard.dir !== directory ||
+        receipt.target !== receipt.directoryGuard ||
+        (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
+            !receipt.directoryGuard.stat.isDirectory())) {
+        throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
+    }
+    return receipt.directoryGuard;
+}
 async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
     let entries;
     try {
         const beforeObservation = getFsSafeTestHooks()?.beforeRootListObservation;
         if (beforeObservation)
             await beforeObservation(guard.realPath, withFileTypes);
-        const names = (await fs.readdir(guard.realPath)).sort();
+        const names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName).sort();
         entries = withFileTypes
             ? names.map(name => ({
                 name,
@@ -214,13 +242,30 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
         await assertRootDirectoryObservationGuard(root, guard);
     return entries;
 }
-export async function openRootDirectoryListing(root, directory, options) {
-    const guard = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
-        throw normalizeDirectoryError(error);
-    });
+export async function openRootDirectoryListing(root, directory, options, receipt) {
+    if (options.exactIdentity && options.order !== "filesystem")
+        throw new TypeError("exact entry identities require filesystem order");
+    let guard;
+    if (receipt) {
+        guard = directoryGuardFromReceipt(directory, receipt);
+    }
+    else {
+        const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
+            throw normalizeDirectoryError(error);
+        });
+        // Retain exact admission identities; metadata rechecks can use numeric Stats
+        // only when every identity component is losslessly representable.
+        guard = extendDirectoryObservationGuard({
+            stat: admitted.stat,
+            identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
+        }, admitted.dir, admitted.realPath);
+    }
     const assertCurrent = async () => {
         options.signal?.throwIfAborted();
-        await assertRootDirectoryObservationGuard(root, guard);
+        if (receipt)
+            assertRootPathObservationReceiptCurrent(root, receipt);
+        else
+            await assertRootDirectoryObservationGuard(root, guard);
         options.signal?.throwIfAborted();
     };
     let handle;
@@ -235,23 +280,29 @@ export async function openRootDirectoryListing(root, directory, options) {
     const close = async () => {
         const owned = handle;
         handle = undefined;
-        await owned?.close();
+        try {
+            await owned?.close();
+        }
+        catch (error) {
+            options.onCleanupFailure?.(error);
+            throw error;
+        }
     };
     try {
         await assertCurrent();
         if (options.order === "filesystem") {
             // A one-entry buffer keeps the truncation lookahead independent of width.
-            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            handle = await openDirectoryNames(guard.realPath);
         }
         else if (options.snapshot) {
-            snapshot = await listGuardedDirectoryPath(root, guard, true);
+            snapshot = await listGuardedDirectoryPath(root, guard, true, receipt);
         }
         else if (options.maxNames !== undefined) {
             names = [];
-            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            handle = await openDirectoryNames(guard.realPath);
             while (true) {
                 await assertCurrent();
-                const name = (await handle.read())?.name;
+                const name = await readDirectoryEntryName(handle);
                 await assertCurrent();
                 if (name === undefined)
                     break;
@@ -263,7 +314,7 @@ export async function openRootDirectoryListing(root, directory, options) {
             await close();
         }
         else {
-            names = await fs.readdir(guard.realPath);
+            names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName);
         }
         await assertCurrent();
         names?.sort();
@@ -325,6 +376,7 @@ export async function openRootDirectoryListing(root, directory, options) {
         }
     };
     return {
+        assertCurrent,
         async next() {
             try {
                 options.signal?.throwIfAborted();
@@ -347,17 +399,30 @@ export async function openRootDirectoryListing(root, directory, options) {
                         return { kind: "limit", name: pendingLimit };
                     return;
                 }
-                await assertCurrent();
-                const name = (await handle.read())?.name;
-                await assertCurrent();
-                if (name === undefined)
-                    return;
-                if (!options.admitEntry())
-                    return { kind: "limit", name };
-                // The stream's post-read fence is also the pre-stat fence in this owned operation.
-                const stat = fsSync.lstatSync(path.join(guard.realPath, name));
-                await assertCurrent();
-                return { kind: "entry", entry: { name, ...pathStatFromStats(stat) } };
+                for (;;) {
+                    await assertCurrent();
+                    const name = await readDirectoryEntryName(handle);
+                    await assertCurrent();
+                    if (name === undefined)
+                        return;
+                    if (!options.admitEntry())
+                        return { kind: "limit", name };
+                    // The stream's post-read fence is also the pre-stat fence in this owned operation.
+                    const pathname = path.join(guard.realPath, name);
+                    let observed;
+                    try {
+                        observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
+                            ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : { stat: fsSync.lstatSync(pathname) };
+                    }
+                    catch (error) {
+                        await assertCurrent();
+                        if (options.skipVanished && isNotFoundPathError(error))
+                            continue;
+                        throw error;
+                    }
+                    await assertCurrent();
+                    return { kind: "entry", entry: { name, ...pathStatFromStats(observed.stat) }, identity: observed.identity };
+                }
             }
             catch (error) {
                 throw normalizeDirectoryError(error);

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

@@ -20,4 +20,3 @@ export declare function ensureDirectoryWithinRoot(params: {
     defaultDirName?: string;
     mode?: number;
 }): Promise<DirectoryResult>;
-//# sourceMappingURL=root-directory.d.ts.map

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

@@ -8,4 +8,3 @@ export type RootEntriesOptions = {
     symlinks?: SymlinkPolicy;
 };
 export declare function entriesInRoot(root: RootContext, relativePath: string, options: RootEntriesOptions): AsyncGenerator<DirEntry>;
-//# sourceMappingURL=root-entries.d.ts.map

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

@@ -1,5 +1,5 @@
 import { FsSafeError } from "./errors.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { resolvePathInRoot } from "./root-context.js";
 import { openRootDirectoryListing } from "./root-directory-list.js";
 import { readSymlinkResolution } from "./root-symlink-policy.js";
@@ -13,7 +13,7 @@ export async function* entriesInRoot(root, relativePath, options) {
         throw new TypeError(`invalid root entries order: ${String(options.order)}`);
     }
     options.signal?.throwIfAborted();
-    validatePinnedOperationPayload({ relativePath });
+    validatePinnedRelativePath(relativePath);
     const resolved = await resolvePathInRoot(root, relativePath, {
         ...readSymlinkResolution(options.symlinks),
         resolveCanonical: true,

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

@@ -10,4 +10,7 @@ export declare function normalizePinnedPathError(error: unknown, details?: FsSaf
 export declare function normalizeRemoveGuardError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function normalizeRemovePathError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function throwFsSafeReadError(error: unknown, label: string): never;
-//# sourceMappingURL=root-errors.d.ts.map
+/** Existing boundaries retain only Error instances as their cause. */
+export declare function errorCauseOptions(error: unknown): {
+    cause: Error | undefined;
+};

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

@@ -41,9 +41,7 @@ export function normalizePinnedWriteError(error) {
     const message = code
         ? `${PINNED_WRITE_ERRNO_MESSAGES.get(code) ?? "filesystem write failed"} (${code})`
         : "path is not a regular file under root";
-    return new FsSafeError("invalid-path", message, {
-        cause: error instanceof Error ? error : undefined,
-    });
+    return new FsSafeError("invalid-path", message, errorCauseOptions(error));
 }
 export function normalizePinnedPathError(error, details) {
     if (error instanceof FsSafeError) {
@@ -88,3 +86,7 @@ export function throwFsSafeReadError(error, label) {
     }
     throw error;
 }
+/** Existing boundaries retain only Error instances as their cause. */
+export function errorCauseOptions(error) {
+    return { cause: error instanceof Error ? error : undefined };
+}

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

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import type { PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
+import { type PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
 export type RootFileAdmissionFs = Pick<typeof fs, "lstatSync" | "realpathSync">;
 type ExactIdentity = Readonly<{
     dev: bigint;
@@ -16,6 +16,5 @@ export type CanonicalRootObservation = {
 export declare function observeCanonicalRoot(ioFs: RootFileAdmissionFs, rootPath: string): CanonicalRootObservation;
 export declare function createRootFileFinalAdmission(ioFs: RootFileAdmissionFs, root: Extract<CanonicalRootObservation, {
     ok: true;
-}>, boundaryLabel: string): PinnedOpenSyncFinalAdmission;
+}>, boundaryLabel: string, rejectHardlinks?: boolean): PinnedOpenSyncFinalAdmission;
 export {};
-//# sourceMappingURL=root-file-final-admission.d.ts.map