@openclaw/openshell-sandbox 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/retained-directory-replacement.js

@@ -0,0 +1,193 @@
+import fsSync from "node:fs";
+import { assertDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+function helperUnavailable(message, cause) {
+    return new FsSafeError("helper-unavailable", message, {
+        ...(cause instanceof Error ? { cause } : {}),
+    });
+}
+function copyOperationalCode(target, source) {
+    const code = source?.code;
+    if (typeof code === "string") {
+        Object.defineProperty(target, "code", { configurable: true, value: code });
+    }
+}
+function primaryWithCloseFailure(error, closeError, message) {
+    const cause = new AggregateError([error, closeError], message);
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, {
+            cause,
+            ...(error.details ? { details: error.details } : {}),
+        });
+    }
+    const wrapped = new Error(message, { cause });
+    copyOperationalCode(wrapped, error);
+    return wrapped;
+}
+function supportsRename(binding) {
+    return typeof binding?.renameNoReplaceWithIdentity === "function";
+}
+function supportsCleanup(binding) {
+    return typeof binding.ownedTreeRemovalAvailable === "function" &&
+        typeof binding.removeOwnedTree === "function";
+}
+function closeDescriptors(descriptors) {
+    const errors = [];
+    const closed = new Set();
+    for (const fd of descriptors) {
+        if (fd === undefined || closed.has(fd))
+            continue;
+        closed.add(fd);
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1) {
+        throw new AggregateError(errors, "retained directory replacement descriptors failed to close");
+    }
+}
+const retainedDirectoryOpenFlags = fsSync.constants.O_RDONLY |
+    fsSync.constants.O_DIRECTORY |
+    fsSync.constants.O_NOFOLLOW |
+    fsSync.constants.O_NONBLOCK;
+function openRetainedDirectory(label, expected) {
+    let fd;
+    try {
+        fd = fsSync.openSync(expected.path, retainedDirectoryOpenFlags);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "EACCES" || code === "EPERM") {
+            const purpose = label === "original target"
+                ? "original target for bounded cleanup"
+                : label;
+            throw helperUnavailable(`atomic directory replacement cannot retain the ${purpose}`, error);
+        }
+        throw error;
+    }
+    try {
+        const descriptor = fsSync.fstatSync(fd, { bigint: true });
+        if (!descriptor.isDirectory()) {
+            throw new FsSafeError("not-file", `directory replacement ${label} must be a directory`);
+        }
+        if (descriptor.dev !== expected.identity.dev || descriptor.ino !== expected.identity.ino) {
+            throw new FsSafeError("path-mismatch", `directory replacement ${label} changed during admission`);
+        }
+        assertDirectoryIdentitySync(expected.path, {
+            dev: expected.identity.dev,
+            ino: expected.identity.ino,
+            ...(expected.realPath === undefined ? {} : { realPath: expected.realPath }),
+        });
+    }
+    catch (error) {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch (closeError) {
+            throw primaryWithCloseFailure(error, closeError, `directory replacement ${label} admission and close failed`);
+        }
+        throw error;
+    }
+    return fd;
+}
+export class RetainedDirectoryReplacement {
+    #binding;
+    #originalDirectoryFd;
+    #stagedParentFd;
+    #targetParentFd;
+    #cleanupUsed = false;
+    #closed = false;
+    constructor(binding, targetParentFd, stagedParentFd, originalDirectoryFd) {
+        this.#binding = binding;
+        this.#targetParentFd = targetParentFd;
+        this.#stagedParentFd = stagedParentFd;
+        this.#originalDirectoryFd = originalDirectoryFd;
+    }
+    static requireBinding() {
+        const binding = getNativeBinding();
+        if (!supportsRename(binding)) {
+            throw helperUnavailable("atomic directory replacement requires native identity-fenced no-replace rename support");
+        }
+        return binding;
+    }
+    static retain(params, binding = RetainedDirectoryReplacement.requireBinding()) {
+        let targetParentFd;
+        let stagedParentFd;
+        let originalDirectoryFd;
+        try {
+            targetParentFd = openRetainedDirectory("target parent", params.targetParent);
+            stagedParentFd = params.stagedParent.path === params.targetParent.path
+                ? targetParentFd
+                : openRetainedDirectory("staged parent", params.stagedParent);
+            if (params.originalTarget) {
+                if (!supportsCleanup(binding)) {
+                    throw helperUnavailable("replacing an existing directory requires native bounded owned-tree cleanup");
+                }
+                let available = false;
+                try {
+                    available = binding.ownedTreeRemovalAvailable(targetParentFd) === true;
+                }
+                catch (error) {
+                    throw helperUnavailable("native owned-tree cleanup capability probe failed", error);
+                }
+                if (!available) {
+                    throw helperUnavailable("native owned-tree cleanup is unavailable for the target parent");
+                }
+                originalDirectoryFd = openRetainedDirectory("original target", {
+                    path: params.originalTarget.path,
+                    identity: params.originalTarget.identity,
+                });
+            }
+            return new RetainedDirectoryReplacement(binding, targetParentFd, stagedParentFd, originalDirectoryFd);
+        }
+        catch (error) {
+            try {
+                closeDescriptors([originalDirectoryFd, stagedParentFd, targetParentFd]);
+            }
+            catch (closeError) {
+                throw primaryWithCloseFailure(error, closeError, "retained directory replacement admission and descriptor close failed");
+            }
+            throw error;
+        }
+    }
+    renameNoReplace(sourceParent, sourceBasename, targetBasename, expectedSource) {
+        if (this.#closed) {
+            throw new FsSafeError("path-mismatch", "retained directory rename authority is unavailable");
+        }
+        this.#binding.renameNoReplaceWithIdentity(sourceParent === "staged" ? this.#stagedParentFd : this.#targetParentFd, sourceBasename, this.#targetParentFd, targetBasename, expectedSource.dev, expectedSource.ino);
+    }
+    async removeOriginal(backupBasename) {
+        if (this.#closed || this.#cleanupUsed || this.#originalDirectoryFd === undefined ||
+            !supportsCleanup(this.#binding)) {
+            throw new FsSafeError("path-mismatch", "retained owned-tree cleanup authority is unavailable");
+        }
+        this.#cleanupUsed = true;
+        const result = await this.#binding.removeOwnedTree(this.#targetParentFd, backupBasename, this.#originalDirectoryFd);
+        if (result.errorCode) {
+            if (result.errorCode === "path-mismatch") {
+                throw new FsSafeError("path-mismatch", result.errorMessage ?? "native owned-tree cleanup lost retained identity");
+            }
+            throw Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), { code: result.errorCode });
+        }
+        if (result.outcome !== "removed" && result.outcome !== "preserved") {
+            throw helperUnavailable("native owned-tree cleanup returned an invalid result");
+        }
+        return result.outcome;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        closeDescriptors([
+            this.#originalDirectoryFd,
+            this.#stagedParentFd,
+            this.#targetParentFd,
+        ]);
+    }
+}

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

@@ -1,3 +1,4 @@
+export declare function sameNormalizedPathSpelling(left: string, right: string): boolean;
 export type RootBoundaryIdentity = Readonly<{
     dev: number | bigint;
     ino: number | bigint;
@@ -26,4 +27,3 @@ export declare function admitPathInsideRoot(params: {
         ino: bigint;
     }>) => void;
 }): AdmittedRootPath | undefined;
-//# sourceMappingURL=root-boundary.d.ts.map

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";
@@ -223,17 +223,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-list.d.ts

@@ -17,6 +17,7 @@ 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;
@@ -35,4 +36,3 @@ export type RootDirectoryListingOptions = {
     admitEntry(): boolean;
 };
 export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
-//# sourceMappingURL=root-directory-list.d.ts.map

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

@@ -2,12 +2,12 @@ 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";
@@ -50,9 +50,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 +71,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 +160,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;
 }
@@ -215,9 +222,15 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
     return entries;
 }
 export async function openRootDirectoryListing(root, directory, options) {
-    const guard = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
+    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.
+    const 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);
@@ -325,6 +338,7 @@ export async function openRootDirectoryListing(root, directory, options) {
         }
     };
     return {
+        assertCurrent,
         async next() {
             try {
                 options.signal?.throwIfAborted();

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

@@ -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

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

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
 import { realpathSync } from "./realpath.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+import { hardlinkedPathNotAllowedError } from "./root-errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
 function rootIdentityMismatch(cause) {
@@ -51,7 +52,7 @@ export function observeCanonicalRoot(ioFs, rootPath) {
 function resolveConsumedPath(ioFs, filePath) {
     return ioFs === fs ? realpathSync.native(filePath) : ioFs.realpathSync(filePath);
 }
-export function createRootFileFinalAdmission(ioFs, root, boundaryLabel) {
+export function createRootFileFinalAdmission(ioFs, root, boundaryLabel, rejectHardlinks = true) {
     const inspectRoot = (candidateRootPath, expected) => {
         inspectCanonicalRoot(ioFs, candidateRootPath, expected);
     };
@@ -69,7 +70,9 @@ export function createRootFileFinalAdmission(ioFs, root, boundaryLabel) {
             throw new FsSafeError("outside-workspace", `resolved path escapes ${boundaryLabel}`);
         }
         try {
-            inspectFileIdentitySync(() => ioFs.lstatSync(admitted.path, { bigint: true }), descriptorIdentity);
+            const current = inspectFileIdentitySync(() => ioFs.lstatSync(admitted.path, { bigint: true }), descriptorIdentity);
+            if (rejectHardlinks && current.isFile() && current.nlink > 1n)
+                throw hardlinkedPathNotAllowedError();
         }
         catch (error) {
             if (isExpectedPathError(error)) {

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

@@ -44,4 +44,3 @@ export declare function matchRootFileOpenFailure<T>(failure: RootFileOpenFailure
 }): T;
 export declare function openRootFile(params: OpenRootFileParams): Promise<RootFileOpenResult>;
 export {};
-//# sourceMappingURL=root-file.d.ts.map

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

@@ -70,14 +70,15 @@ export function matchRootFileOpenFailure(failure, handlers) {
     return handlers.fallback(failure);
 }
 function openRootFileResolved(params) {
+    const rejectHardlinks = params.rejectHardlinks ?? true;
     const opened = openPinnedFileSync({
         filePath: params.absolutePath,
         resolvedPath: params.resolvedPath,
-        rejectHardlinks: params.rejectHardlinks ?? true,
+        rejectHardlinks,
         maxBytes: params.maxBytes,
         allowedType: params.allowedType,
         ioFs: params.ioFs,
-        finalAdmission: createRootFileFinalAdmission(params.ioFs, params.rootObservation, params.boundaryLabel),
+        finalAdmission: createRootFileFinalAdmission(params.ioFs, params.rootObservation, params.boundaryLabel, rejectHardlinks),
     });
     if (!opened.ok) {
         return opened;