@openclaw/openshell-sandbox 2026.10.5 → 2026.10.7

package/node_modules/@openclaw/fs-safe/dist/publish-copy-stage.js

@@ -2,7 +2,10 @@ import fs, {} from "node:fs";
 import path from "node:path";
 import { assertSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { assertExclusiveCreateLeaf } from "./exclusive-create.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { hasErrorCode } from "./file-cleanup.js";
+import { isHardlinkFallbackError } from "./hardlink-fallback.js";
 // Node has no portable no-replace rename. Publish the completed stage by link,
 // then remove its verified temporary name without yielding.
 export function publishCopyStage(params) {
@@ -27,7 +30,16 @@ export function publishCopyStage(params) {
         throw new FsSafeError("already-exists", "destination already exists");
     }
     params.onPublicationAttempt?.();
-    fs.linkSync(temporaryPath, targetPath);
+    let renamed = false;
+    try {
+        fs.linkSync(temporaryPath, targetPath);
+    }
+    catch (error) {
+        if (!isHardlinkFallbackError(error))
+            throw error;
+        publishThroughPlaceholder(params, assertCurrent);
+        renamed = true;
+    }
     let observerRejected = false;
     let observerError;
     try {
@@ -38,16 +50,29 @@ export function publishCopyStage(params) {
         observerError = error;
     }
     try {
-        const parent = fs.lstatSync(path.dirname(temporaryPath), { bigint: true });
-        const current = fs.lstatSync(temporaryPath, { bigint: true });
-        if (parent.isSymbolicLink() || !parent.isDirectory() ||
-            !sameFileIdentityForCleanup(parent, params.parentGuard.stat) ||
-            current.isSymbolicLink() || !current.isFile() ||
-            !sameFileIdentityForCleanup(current, identity)) {
-            throw new FsSafeError("path-mismatch", "published copy temporary name changed before cleanup");
+        if (renamed) {
+            assertSyncDirectoryGuard(params.parentGuard);
+            if (fs.lstatSync(temporaryPath, { throwIfNoEntry: false })) {
+                throw new FsSafeError("path-mismatch", "renamed copy stage still exists");
+            }
+            const target = fs.lstatSync(targetPath, { bigint: true });
+            if (!target.isFile() || target.isSymbolicLink() || target.nlink !== 1n ||
+                !sameFileIdentityForCleanup(target, identity)) {
+                throw new FsSafeError("path-mismatch", "renamed copy target changed after publication");
+            }
+        }
+        else {
+            const parent = fs.lstatSync(path.dirname(temporaryPath), { bigint: true });
+            const current = fs.lstatSync(temporaryPath, { bigint: true });
+            if (parent.isSymbolicLink() || !parent.isDirectory() ||
+                !sameFileIdentityForCleanup(parent, params.parentGuard.stat) ||
+                current.isSymbolicLink() || !current.isFile() ||
+                !sameFileIdentityForCleanup(current, identity)) {
+                throw new FsSafeError("path-mismatch", "published copy temporary name changed before cleanup");
+            }
+            // This removes the stage's name, never the published destination or source.
+            fs.unlinkSync(temporaryPath);
         }
-        // This removes the stage's name, never the published destination or source.
-        fs.unlinkSync(temporaryPath);
     }
     catch (error) {
         throw new FsSafeError("helper-failed", "published copy temporary cleanup failed", {
@@ -58,3 +83,60 @@ export function publishCopyStage(params) {
     if (observerRejected)
         throw observerError;
 }
+function isEmptyPlaceholder(current, identity) {
+    return current.isFile() && !current.isSymbolicLink() && current.nlink === 1n &&
+        current.size === 0n && sameFileIdentityForCleanup(current, identity);
+}
+function publishThroughPlaceholder(params, assertCurrent) {
+    const { targetPath, temporaryPath } = params;
+    // An empty placeholder can be observed before the completed stage atomically replaces it.
+    // The stage proved directory write access; a real permission denial still fails O_EXCL.
+    assertCurrent();
+    let fd;
+    try {
+        assertExclusiveCreateLeaf(targetPath);
+        fd = fs.openSync(targetPath, fs.constants.O_WRONLY | fs.constants.O_CREAT |
+            fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "EEXIST")) {
+            throw new FsSafeError("already-exists", "destination already exists", { cause: error });
+        }
+        throw error;
+    }
+    let placeholder;
+    try {
+        try {
+            placeholder = fs.fstatSync(fd, { bigint: true });
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        assertCurrent();
+        const current = fs.lstatSync(targetPath, { bigint: true, throwIfNoEntry: false });
+        if (!current || !isEmptyPlaceholder(current, placeholder)) {
+            throw new FsSafeError("path-mismatch", "exclusive copy placeholder changed before publication");
+        }
+        fs.renameSync(temporaryPath, targetPath);
+    }
+    catch (error) {
+        try {
+            assertSyncDirectoryGuard(params.parentGuard);
+            const current = fs.lstatSync(targetPath, { bigint: true, throwIfNoEntry: false });
+            if (current) {
+                if (!placeholder)
+                    throw new FsSafeError("path-mismatch", "copy placeholder identity unavailable for cleanup");
+                if (isEmptyPlaceholder(current, placeholder))
+                    fs.unlinkSync(targetPath);
+            }
+        }
+        catch (cleanupError) {
+            throw new FsSafeError("helper-failed", "unpublished copy placeholder cleanup failed", {
+                cause: new AggregateError([error, cleanupError], "publication and cleanup failed"),
+                details: { publication: "not-published", path: targetPath, cleanup: "failed",
+                    ...(placeholder ? { dev: placeholder.dev, ino: placeholder.ino } : {}) },
+            });
+        }
+        throw error;
+    }
+}

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

@@ -2,6 +2,7 @@ import { type BigIntStats, type Stats } from "node:fs";
 import { type DirectoryReceipt, type DirectorySyncOutcome } from "./directory-durability.js";
 import { type FileIdentityStat } from "./file-identity.js";
 import { type PublishFileExclusiveSyncFailurePolicy } from "./publish-file-failure.js";
+export { isHardlinkFallbackError } from "./hardlink-fallback.js";
 export type PublishFileExclusiveStrategy = "link-or-copy" | "link-required" | "rename-noreplace";
 export type PublishFileExclusiveResult = {
     method: "hardlink" | "exclusive-copy" | "rename-noreplace";
@@ -10,7 +11,6 @@ export type PublishFileExclusiveResult = {
     identity: Stats;
     directorySync: DirectorySyncOutcome;
 };
-export declare function isHardlinkFallbackError(error: unknown): boolean;
 export declare function publishFileExclusive(params: {
     sourcePath: string;
     targetPath: string;

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

@@ -11,7 +11,7 @@ import { ownDirectoryReceipt } from "./directory-receipt.js";
 import { hashFileHandle } from "./file-hash.js";
 import { sameFileIdentity, sameFileIdentityForCleanup, } from "./file-identity.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
-import { getNativeBinding, requireNativeBinding } from "./native.js";
+import { getNativeBinding, requireNativeBinding, selectNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { directorySyncFailure, publicationFailure, rememberCreatedTarget, } from "./publish-file-failure.js";
@@ -19,11 +19,9 @@ import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./wind
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { hasErrorCode } from "./file-cleanup.js";
 import { writeAllToFile } from "./write-file-handle.js";
-const HARDLINK_FALLBACK_CODES = new Set(["EPERM", "EXDEV", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
+import { isHardlinkFallbackError } from "./hardlink-fallback.js";
+export { isHardlinkFallbackError } from "./hardlink-fallback.js";
 const NATIVE_COPY_FALLBACK_CODES = new Set(["EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EPERM", "EXDEV"]);
-export function isHardlinkFallbackError(error) {
-    return HARDLINK_FALLBACK_CODES.has(error?.code ?? "");
-}
 function directoryOpenFlags() {
     return (fsSync.constants.O_RDONLY |
         (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0));
@@ -78,13 +76,16 @@ async function copyPinnedSource(params) {
     if (params.native && params.targetNativeParent) {
         const closeFd = captureNativeFdClose(params.native);
         for (const method of ["clone", "copy-file-range"]) {
+            const native = selectNativeBinding(params.native, method === "clone" ? "cloneFileExclusive" : "copyFileRangeExclusive");
+            if (!native)
+                continue;
             let nativeFd;
             try {
                 if (method === "clone") {
-                    nativeFd = params.native.cloneFileExclusive(params.source.fd, params.targetNativeParent.handle.fd, params.targetNativeParent.basename);
+                    nativeFd = native.cloneFileExclusive(params.source.fd, params.targetNativeParent.handle.fd, params.targetNativeParent.basename);
                 }
                 else {
-                    const copied = await params.native.copyFileRangeExclusive(params.source.fd, params.targetNativeParent.handle.fd, params.targetNativeParent.basename);
+                    const copied = await native.copyFileRangeExclusive(params.source.fd, params.targetNativeParent.handle.fd, params.targetNativeParent.basename);
                     if (copied.errorCode) {
                         throw Object.assign(new Error(copied.errorMessage ?? "native copy failed"), {
                             code: copied.errorCode,
@@ -263,14 +264,14 @@ export async function publishFileExclusive(params) {
         await parent.assertCurrent();
         assertSourceCurrent();
         const native = strategy === "rename-noreplace"
-            ? requireNativeBinding()
-            : getNativeBinding();
+            ? requireNativeBinding("renameNoReplace")
+            : getNativeBinding("linkBeneath");
         if (native) {
             sourceNativeParent = await openNativeParent(sourcePath);
             targetNativeParent = await openNativeParent(targetPath);
         }
         if (strategy === "rename-noreplace") {
-            const binding = requireNativeBinding();
+            const binding = requireNativeBinding("renameNoReplace");
             try {
                 const fallback = nativeMoveNoReplace(binding, [
                     sourceNativeParent.handle.fd, sourceNativeParent.basename,
@@ -313,7 +314,7 @@ export async function publishFileExclusive(params) {
             return await finishPublication("rename-noreplace", source, sourceExactIdentity);
         }
         try {
-            if (native) {
+            if (native?.linkBeneath) {
                 native.linkBeneath(sourceNativeParent.handle.fd, sourceNativeParent.basename, targetNativeParent.handle.fd, targetNativeParent.basename);
             }
             else {

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

@@ -0,0 +1,18 @@
+import { type BigIntStats } from "node:fs";
+import type { OpenResult } from "./root-impl.js";
+import type { RootContext } from "./root-context.js";
+import type { RootCopyOptions, RootCopySource, HardlinkPolicy } from "./root-options.js";
+import { onCopyPublication, onCopySourceAdmission, type CopyPublicationOptions } from "./copy-publication.js";
+type RootCopyParams = RootCopyOptions & {
+    source: RootCopySource;
+    relativePath: string;
+    verifyPublished?: CopyPublicationOptions[typeof onCopyPublication];
+    admitSource?: CopyPublicationOptions[typeof onCopySourceAdmission];
+};
+export declare function copyFileInRoot(root: RootContext, params: RootCopyParams, openVerifiedLocalFile: (path: string, options: {
+    hardlinks?: HardlinkPolicy;
+}) => Promise<{
+    opened: OpenResult;
+    identity: BigIntStats;
+}>): Promise<void>;
+export {};

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

@@ -0,0 +1,128 @@
+import fsSync, {} from "node:fs";
+import { assertCopySourceCurrent, resolveFileCopyCloneMode } from "./copy-file-input.js";
+import { resolveCopyCloneMode } from "./copy-policy.js";
+import { captureCopyMetadata } from "./copy-metadata.js";
+import { admitCopyLink, assertCopyLinkAvailable } from "./copy-link.js";
+import { assertAbsolutePathInput } from "./absolute-path.js";
+import { assertNoNulPathInput } from "./path.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { MutationAuthorityError } from "./mutation-authority.js";
+import { serializePathWrite } from "./write-queue.js";
+import { rootWriteQueueKey } from "./root-create-native.js";
+import { resolvePinnedWriteTargetInRoot } from "./root-write-admission.js";
+import { createCopyPublicationObserver, onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
+import { isAlreadyExistsError, normalizePinnedWriteError } from "./root-errors.js";
+import { runPinnedWriteHelper } from "./pinned-write.js";
+import { FsSafeError } from "./errors.js";
+export async function copyFileInRoot(root, params, openVerifiedLocalFile) {
+    params.signal?.throwIfAborted();
+    resolveCopyCloneMode(params.clone, "never");
+    if (params.sourceSymlinks !== undefined && params.sourceSymlinks !== "reject" && params.sourceSymlinks !== "copy-link") {
+        throw new FsSafeError("invalid-path", "sourceSymlinks must be reject or copy-link");
+    }
+    if (params.sourceSymlinks === "copy-link") {
+        if (typeof params.source !== "string") {
+            throw new FsSafeError("invalid-path", "sourceSymlinks: copy-link requires an absolute-path string source; open/stat capabilities cannot observe links without following them");
+        }
+        const link = await admitCopyLink(assertAbsolutePathInput(params.source), params.preserveMetadata === true, params.signal)
+            .catch(error => { throw normalizePinnedWriteError(error); });
+        if (link) {
+            if (params.overwrite === true)
+                throw new FsSafeError("invalid-path", "copy-link cannot overwrite an existing destination; omit overwrite or use false");
+            assertCopyLinkAvailable();
+            const mode = params.mode ?? (params.preserveSourceMode ? Number(link.identity.mode & 4095n) : undefined);
+            await copyInputInRoot(root, { ...params, overwrite: false }, link, mode);
+            return;
+        }
+    }
+    const clone = resolveFileCopyCloneMode(params.clone);
+    let source;
+    let sourceIdentity;
+    if (typeof params.source === "string") {
+        assertNoNulPathInput(params.source, "source path contains a NUL byte");
+        assertNoWindowsPathAlias(params.source, "filesystem", "source path uses a Windows filesystem namespace alias");
+        ({ opened: source, identity: sourceIdentity } = await openVerifiedLocalFile(params.source, {
+            hardlinks: params.sourceHardlinks,
+        }));
+    }
+    else {
+        source = await params.source.root.open(params.source.relativePath, params.sourceHardlinks === undefined ? undefined : { hardlinks: params.sourceHardlinks });
+        try {
+            sourceIdentity = await inspectFileIdentity(() => fsSync.fstatSync(source.handle.fd, { bigint: true }));
+        }
+        catch (error) {
+            await source.handle.close().catch(() => undefined);
+            throw error;
+        }
+    }
+    try {
+        if (params.maxBytes !== undefined && source.stat.size > params.maxBytes) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${source.stat.size})`);
+        }
+        let metadata;
+        try {
+            metadata = params.preserveMetadata ? captureCopyMetadata(source.handle.fd, sourceIdentity) : undefined;
+        }
+        catch (error) {
+            throw normalizePinnedWriteError(error);
+        }
+        const sourceAdmission = params.admitSource?.(sourceIdentity, source.realPath);
+        const verifySource = async () => {
+            params.signal?.throwIfAborted();
+            try {
+                sourceAdmission?.verify();
+            }
+            catch (error) {
+                throw new MutationAuthorityError(error);
+            }
+            if (typeof params.source !== "string")
+                await params.source.root.stat(".");
+            await assertCopySourceCurrent(source, sourceIdentity);
+        };
+        const mode = sourceAdmission?.mode ?? params.mode ?? (params.preserveSourceMode ? Number(sourceIdentity.mode & 4095n) : undefined);
+        await copyInputInRoot(root, params, {
+            kind: "file", handle: source.handle, size: source.stat.size, clone,
+            signal: params.signal, metadata, verifySource,
+        }, mode, () => assertCopySourceCurrent(source, sourceIdentity));
+    }
+    finally {
+        await source.handle.close().catch(() => { });
+    }
+}
+async function copyInputInRoot(root, params, input, mode, verifyAdmission = input.verifySource) {
+    if (mode !== undefined && (!Number.isInteger(mode) || mode < 0 || mode > 0o7777)) {
+        throw new FsSafeError("invalid-path", "invalid copy mode");
+    }
+    await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
+        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, mode, params.denyMutations, params.overwrite !== false, params.mutationSymlinks);
+        await serializePathWrite(pinned.targetPath, async () => {
+            await verifyAdmission();
+            const observer = createCopyPublicationObserver(pinned.targetPath, params.onDestinationPublished);
+            try {
+                await runPinnedWriteHelper({
+                    rootPath: pinned.rootReal, relativeParentPath: pinned.relativeParentPath, basename: pinned.basename,
+                    mkdir: params.mkdir !== false, mode: pinned.mode, overwrite: params.overwrite !== false,
+                    rejectFinalSymlink: params.mutationSymlinks !== undefined, maxBytes: params.maxBytes,
+                    sync: params.durable !== false,
+                    assertBeforeMutation: params.signal || params.assertBeforeMutation ? () => {
+                        if (params.signal?.aborted)
+                            throw new MutationAuthorityError(params.signal.reason);
+                        params.assertBeforeMutation?.();
+                    } : undefined,
+                    verifyPublished: params.verifyPublished, onPublished: observer.onPublished, input,
+                    rootIdentity: root.rootIdentity, mutationAdmission: pinned.mutationAdmission,
+                });
+            }
+            catch (error) {
+                observer.rethrowObserverFailure(error);
+                if (params.signal?.aborted && error === params.signal.reason)
+                    throw error;
+                if (isAlreadyExistsError(error))
+                    throw new FsSafeError("already-exists", "copy destination already exists", { cause: error });
+                throw normalizePinnedWriteError(error);
+            }
+            await input.verifySource();
+        });
+    });
+}

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

@@ -63,10 +63,11 @@ import { getNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { 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";
@@ -81,7 +82,7 @@ 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 directoryTarget = params.directory === params.target;
@@ -232,10 +233,17 @@ export async function tryMkdirRootNative(params) {
     // 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 {
+        return await withNativeDirectory(params, async (_binding, _fd, assertCurrent) => { assertCurrent(); return true; });
+    }
+    catch (error) {
+        if (hasNodeErrorCode(error, "ENOTDIR"))
+            throw directoryComponentNotDirectoryError(error);
+        throw error;
+    }
 }
 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;

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

@@ -55,7 +55,7 @@ import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
-import { assertCopySourceCurrent, resolveFileCopyCloneMode } from "./copy-file-input.js";
+import { copyFileInRoot } from "./root-copy.js";
 import { assertPrivateFileCreationAvailable, resolveCreationPermissions } from "./creation-boundary.js";
 import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
@@ -68,6 +68,7 @@ import { openedPathResolutionError, recordExclusiveCreateFailure, recordOpenedFi
 import { runPinnedWriteHelper, runPinnedWriteWithRenamePolicy } from "./pinned-write.js";
 import { preparePinnedWriteMutationAdmission, snapshotPinnedMutationPolicy } from "./pinned-mutation-admission.js";
 import { getNativeBinding } from "./native.js";
+import { getPinnedWriteNativeBinding } from "./native-pinned-write.js";
 import { isFsSafeNativeRequired } from "./native-config.js";
 import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { PATH_ALIAS_POLICIES } from "./path-policy.js";
@@ -104,7 +105,7 @@ import { assertRootFallbackWritePath } from "./root-write-lock-binding.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { admitMoveSourceStat, movePathNative } from "./root-move-noreplace.js";
 import { admitRootReadHandle, inspectOpenedPathIdentitySync } from "./root-read-admission.js";
-import { createCopyPublicationObserver, onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
+import { onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
 import { writeAllToFile } from "./write-file-handle.js";
 import { createInputOptions, rethrowCreateInputError, rootWriteInput, retainSidecarCreated } from "./root-create-input.js";
 import { assertFinalSymlinkRejected, mutationSymlinkResolution, readSymlinkResolution } from "./root-symlink-policy.js";
@@ -113,7 +114,7 @@ import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./wi
 import { resolvePinnedObservedPathInRoot } from "./root-observed-path.js";
 import { registerFileLockSyncRootAdapter } from "./file-lock-sync-root.js";
 import { mergeReadOptions, readDefaults, } from "./root-options.js";
-import { composeMutationAssertions, MutationAuthorityError, rethrowMutationAuthorityError } from "./mutation-authority.js";
+import { composeMutationAssertions, rethrowMutationAuthorityError } from "./mutation-authority.js";
 export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
 function logWarn(message) {
@@ -355,7 +356,7 @@ export class RootHandle {
             durable: options.durable ?? this.defaults.durable ?? true,
             verifyPublished: options[onCopyPublication],
             admitSource: options[onCopySourceAdmission],
-        }).catch(rethrowMutationAuthorityError);
+        }, openVerifiedLocalFile).catch(rethrowMutationAuthorityError);
     }
     async exists(relativePath) {
         try {
@@ -897,7 +898,7 @@ async function writeFileInRoot(root, params) {
     const input = rootWriteInput(params);
     await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
         if (!params.private && input.kind === "buffer" && !input.stageBeforePublish && process.platform === "win32" &&
-            (params.renameIdentity === "verify-content-with-lock" || !getNativeBinding())) {
+            (params.renameIdentity === "verify-content-with-lock" || !getPinnedWriteNativeBinding({ input }))) {
             await writeFileFallback(root, { ...params, data: input.data });
             return;
         }
@@ -965,93 +966,6 @@ async function commitPinnedWriteInRoot(root, pinned, params, input) {
         throw normalizePinnedWriteError(error);
     }
 }
-async function copyFileInRoot(root, params) {
-    params.signal?.throwIfAborted();
-    const clone = resolveFileCopyCloneMode(params.clone);
-    let source;
-    let sourceIdentity;
-    if (typeof params.source === "string") {
-        assertNoNulPathInput(params.source, "source path contains a NUL byte");
-        assertNoWindowsPathAlias(params.source, "filesystem", "source path uses a Windows filesystem namespace alias");
-        ({ opened: source, identity: sourceIdentity } = await openVerifiedLocalFile(params.source, {
-            hardlinks: params.sourceHardlinks,
-        }));
-    }
-    else {
-        source = await params.source.root.open(params.source.relativePath, params.sourceHardlinks === undefined ? undefined : { hardlinks: params.sourceHardlinks });
-        try {
-            sourceIdentity = await inspectFileIdentity(() => fsSync.fstatSync(source.handle.fd, { bigint: true }));
-        }
-        catch (error) {
-            await source.handle.close().catch(() => undefined);
-            throw error;
-        }
-    }
-    if (params.maxBytes !== undefined && source.stat.size > params.maxBytes) {
-        await source.handle.close().catch(() => { });
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${source.stat.size})`);
-    }
-    try {
-        const sourceAdmission = params.admitSource?.(sourceIdentity, source.realPath);
-        const mode = sourceAdmission?.mode ?? params.mode;
-        await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
-            const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, mode ?? (params.preserveSourceMode ? Number(sourceIdentity.mode & 4095n) : undefined), params.denyMutations, params.overwrite !== false, params.mutationSymlinks);
-            await serializePathWrite(pinned.targetPath, async () => {
-                await assertCopySourceCurrent(source, sourceIdentity);
-                const verifySource = async () => {
-                    params.signal?.throwIfAborted();
-                    try {
-                        sourceAdmission?.verify();
-                    }
-                    catch (error) {
-                        throw new MutationAuthorityError(error);
-                    }
-                    if (typeof params.source !== "string") {
-                        await params.source.root.stat(".");
-                    }
-                    await assertCopySourceCurrent(source, sourceIdentity);
-                };
-                const observer = createCopyPublicationObserver(pinned.targetPath, params.onDestinationPublished);
-                try {
-                    await runPinnedWriteHelper({
-                        rootPath: pinned.rootReal,
-                        relativeParentPath: pinned.relativeParentPath,
-                        basename: pinned.basename,
-                        mkdir: params.mkdir !== false,
-                        mode: pinned.mode,
-                        overwrite: params.overwrite !== false,
-                        rejectFinalSymlink: params.mutationSymlinks !== undefined,
-                        maxBytes: params.maxBytes,
-                        sync: params.durable !== false,
-                        assertBeforeMutation: params.signal || params.assertBeforeMutation ? () => {
-                            if (params.signal?.aborted)
-                                throw new MutationAuthorityError(params.signal.reason);
-                            params.assertBeforeMutation?.();
-                        } : undefined,
-                        verifyPublished: params.verifyPublished,
-                        onPublished: observer.onPublished,
-                        input: { kind: "file", handle: source.handle, size: source.stat.size, clone, signal: params.signal, verifySource },
-                        rootIdentity: root.rootIdentity,
-                        mutationAdmission: pinned.mutationAdmission,
-                    });
-                }
-                catch (error) {
-                    observer.rethrowObserverFailure(error);
-                    if (params.signal?.aborted && error === params.signal.reason)
-                        throw error;
-                    if (isAlreadyExistsError(error)) {
-                        throw new FsSafeError("already-exists", "copy destination already exists", { cause: error });
-                    }
-                    throw normalizePinnedWriteError(error);
-                }
-                await verifySource();
-            });
-        });
-    }
-    finally {
-        await source.handle.close().catch(() => { });
-    }
-}
 async function resolvePinnedPathInRoot(root, params) {
     const resolved = await resolvePinnedRootPathInRoot(root, {
         relativePath: params.relativePath,

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

@@ -80,7 +80,7 @@ export async function movePathNative(root, params, paths, overwrite = false) {
                 throw error;
             // Advisory fast rejection only. renameNoReplace owns the collision decision.
         }
-    const binding = requireNativeBinding();
+    const binding = requireNativeBinding("openBeneath", overwrite ? "renameReplaceWithIdentity" : "renameNoReplace");
     if (typeof (overwrite ? binding.renameReplaceWithIdentity : binding.renameNoReplace) !== "function") {
         throw new FsSafeError("helper-unavailable", "native move is unavailable");
     }

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

@@ -38,6 +38,8 @@ export type RootCopyOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyM
     clone?: CopyCloneMode;
     signal?: AbortSignal;
     preserveSourceMode?: boolean;
+    preserveMetadata?: boolean;
+    sourceSymlinks?: "reject" | "copy-link";
     onDestinationPublished?: (receipt: RootCopyPublicationReceipt) => void;
 };
 export type RootCopySource = string | {

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

@@ -29,7 +29,7 @@ function normalize(error, details) {
     return normalizeRemovePathError(error, details);
 }
 export async function removePathInRootNative(root, target, options, receipts) {
-    const binding = getNativeBinding();
+    const binding = getNativeBinding("openBeneath", "rootRemovalStat", "rootRemovalUnlink");
     if (!binding?.rootRemovalStat || !binding.rootRemovalUnlink) {
         unavailable();
     }
@@ -39,6 +39,13 @@ export async function removePathInRootNative(root, target, options, receipts) {
     const boundary = await captureNonrecursiveRemovalAdmission(root, target, options, receipts);
     if (!boundary)
         return;
+    if (options.recursive && options.maxEntries === 0) {
+        options.signal?.throwIfAborted();
+        boundary.assertCurrent();
+        throw new FsSafeError("too-large", "recursive removal budget exceeded", {
+            details: { operation: "remove", phase: "inspect", relativePath: "" },
+        });
+    }
     const rootAdmission = await openNativeRootAdmission(binding, {
         rootPath: root.rootReal, rootIdentity: root.rootIdentity, operation: "remove", reportCloseErrors: true, searchOnly: true,
     }).catch(error => { throw normalizeRemoveGuardError(error); });

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

@@ -75,7 +75,7 @@ async function writeIsolatedProducer(params) {
     const targetRoot = rootFromDirectoryGuard(parentGuard);
     // Select the handoff before invoking the producer. Missing required native
     // support must not leave producer output behind as a discovery side effect.
-    const native = getNativeBinding();
+    const native = getNativeBinding("openBeneath", "renameNoReplace");
     const cleanupErrors = [];
     const { target, identity } = await createOwnedTempFile({
         rootDir: targetRoot.rootReal,

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-retained.js

@@ -99,7 +99,7 @@ export function retainCreatedSidecar(lockPath, raw, createdFd, guard, nativePare
                 }
             } };
     }
-    if (!binding.stagedFileMatches || !binding.removeStagedFile)
+    if (!binding.openBeneath || !binding.stagedFileMatches || !binding.removeStagedFile)
         return undefined;
     const closeFile = captureNativeFdClose(binding);
     const parentFd = binding.openBeneath(nativeParent.fd, "", nativeOpenFlags(fs.constants.O_RDONLY | fs.constants.O_DIRECTORY)).fd;

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-target.js

@@ -1,3 +1,4 @@
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
@@ -23,7 +24,13 @@ export async function resolveSidecarTargetPath(resolved, lockRoot) {
         assertNoWindowsPathAlias(normalized);
         return normalized;
     }
-    await fs.mkdir(recursiveMkdirPath(dir), { recursive: true });
+    let parentExists = false;
+    try {
+        parentExists = fsSync.statSync(dir).isDirectory();
+    }
+    catch { /* Preserve mkdir errors below. */ }
+    if (!parentExists)
+        await fs.mkdir(recursiveMkdirPath(dir), { recursive: true });
     let parent;
     try {
         parent = realpathSync.native(dir);

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

@@ -1,5 +1,6 @@
 import type { FileHandle } from "node:fs/promises";
 import type { FileIdentityStat } from "./file-identity.js";
+export { holdWindowsSharingLock, setWindowsFileAttributes, readWindowsFileExtents } from "./windows-test-hooks.js";
 export type FsSafeTestHooks = {
     beforeWatchRegistration?: (path: string) => void | Promise<void>;
     afterWatchRegistration?: (path: string) => void | Promise<void>;

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

@@ -1,3 +1,4 @@
+export { holdWindowsSharingLock, setWindowsFileAttributes, readWindowsFileExtents } from "./windows-test-hooks.js";
 let fsSafeTestHooks;
 function allowFsSafeTestHooks() {
     return process.env.NODE_ENV === "test" || process.env.VITEST === "true";