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

package/node_modules/@openclaw/fs-safe/dist/native-parent-admission.js

@@ -1,18 +1,20 @@
 import fsSync, {} from "node:fs";
-import fs from "node:fs/promises";
 import path from "node:path";
-import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { assertSyncDirectoryGuard, inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
 import { inspectNativeDirectoryObservation } from "./native-directory-observation.js";
 import { FsSafeError } from "./errors.js";
+import { hasSafeFileIdentity } from "./file-identity.js";
+import { assertNativeCapabilities } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { realpathSync } from "./realpath.js";
-import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
+import { describeNativeStagedDirectory, describePolicyStagedDirectory, describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
 export function sameNativeIdentity(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
+    return hasSafeFileIdentity(left) && hasSafeFileIdentity(right) &&
+        BigInt(left.dev) === BigInt(right.dev) && BigInt(left.ino) === BigInt(right.ino);
 }
 function unavailable(message) {
     return new FsSafeError("helper-unavailable", message);
@@ -22,13 +24,67 @@ function assertParentAdmissionAvailable(binding) {
         throw unavailable("native parent directory admission is unavailable");
     }
     captureNativeFdClose(binding);
+    assertNativeCapabilities(binding, "openBeneath");
+}
+/** Short native mutations need a retained descriptor, not a Node FileHandle. */
+export function openExactNativeRootSync(binding, params) {
+    assertParentAdmissionAvailable(binding);
+    assertNoWindowsPathAlias(params.rootPath, "filesystem", "native root uses a Windows filesystem namespace alias");
+    const flags = (nodeDirectorySearchOnlyFlags()?.flags ?? fsSync.constants.O_RDONLY) |
+        (fsSync.constants.O_DIRECTORY ?? 0);
+    const fd = fsSync.openSync(pathForWindowsFilesystem(params.rootPath), flags);
+    let held = true;
+    const close = () => {
+        if (!held)
+            return;
+        held = false;
+        fsSync.closeSync(fd);
+    };
+    try {
+        const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), params.rootIdentity);
+        if (!stat.isDirectory())
+            throw new FsSafeError("path-mismatch", "native root is not a directory");
+        return { fd, stat, close, [Symbol.dispose]: close };
+    }
+    catch (error) {
+        try {
+            close();
+        }
+        catch (closeError) {
+            throw createSuppressedError(closeError, error, "native root admission and close failed");
+        }
+        throw error;
+    }
+}
+export function openExactNativeRootAdmissionSync(binding, params) {
+    return {
+        directoryFlags: (nodeDirectorySearchOnlyFlags()?.flags ?? fsSync.constants.O_RDONLY) | (fsSync.constants.O_DIRECTORY ?? 0),
+        exactRoot: true,
+        reportCloseErrors: params.reportCloseErrors,
+        operation: params.operation,
+        root: openExactNativeRootSync(binding, params),
+        rootPath: params.rootPath,
+    };
+}
+export function borrowNativeRootParent(admission) {
+    const guard = { dir: admission.rootPath, realPath: admission.rootPath, stat: admission.root.stat };
+    assertSyncDirectoryGuard(guard);
+    return { fd: admission.root.fd, guard, close() { } };
 }
 export async function openNativeRootAdmission(binding, params) {
     assertParentAdmissionAvailable(binding);
     const directoryFlags = (params.searchOnly ? nodeDirectorySearchOnlyFlags()?.flags ?? fsSync.constants.O_RDONLY : fsSync.constants.O_RDONLY) |
         (fsSync.constants.O_DIRECTORY ?? 0);
     assertNoWindowsPathAlias(params.rootPath, "filesystem", "native root uses a Windows filesystem namespace alias");
-    const root = await fs.open(pathForWindowsFilesystem(params.rootPath), directoryFlags);
+    let fd = fsSync.openSync(pathForWindowsFilesystem(params.rootPath), directoryFlags);
+    const close = async () => {
+        if (fd < 0)
+            return;
+        const owned = fd;
+        fd = -1;
+        fsSync.closeSync(owned);
+    };
+    const root = { get fd() { return fd; }, close, [Symbol.asyncDispose]: close };
     try {
         const exactRoot = typeof params.rootIdentity?.dev === "bigint" &&
             typeof params.rootIdentity.ino === "bigint";
@@ -38,10 +94,7 @@ export async function openNativeRootAdmission(binding, params) {
             rootMatches = true;
         }
         else if (process.platform === "win32") {
-            if (typeof binding.fstatIdentity !== "function") {
-                throw unavailable("native root directory identity checks are unavailable");
-            }
-            const identity = binding.fstatIdentity(root.fd);
+            const identity = fsSync.fstatSync(root.fd, { bigint: true });
             rootMatches = !params.rootIdentity || sameNativeIdentity(params.rootIdentity, identity);
         }
         else {
@@ -87,7 +140,8 @@ export async function openNativeParentAdmission(binding, rootAdmission, relative
         const parentInput = relativeParentPath
             ? path.join(rootAdmission.rootPath, ...relativeParentPath.split("/"))
             : rootAdmission.rootPath;
-        if (observation === "native-directory" && process.platform === "win32" && rootAdmission.exactRoot &&
+        if ((observation === "native-directory" || observation === "native-publication") &&
+            process.platform === "win32" && rootAdmission.exactRoot &&
             typeof binding.observeDirectory === "function") {
             const stat = inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true }));
             let observed;
@@ -110,17 +164,33 @@ export async function openNativeParentAdmission(binding, rootAdmission, relative
         }
         const parentPath = realpathSync.native(pathForWindowsFilesystem(parentInput));
         assertNoWindowsPathAlias(parentPath, "filesystem", "native parent uses a Windows filesystem namespace alias");
+        if (observation === "native-publication" && process.platform !== "win32" && rootAdmission.exactRoot) {
+            const captured = describeNativeStagedDirectory(binding, parentFd, parentPath);
+            return {
+                fd: parentFd,
+                close: () => closeFd(parentFd),
+                guard: { dir: parentPath, realPath: parentPath, stat: captured.stat },
+                stagedDirectory: captured.directory,
+            };
+        }
+        if (observation === "native-directory" && process.platform !== "win32" && rootAdmission.exactRoot) {
+            const captured = describePolicyStagedDirectory(parentFd, parentPath, binding);
+            captured.disposeObservation?.();
+            return {
+                fd: parentFd,
+                close: () => closeFd(parentFd),
+                guard: { dir: parentPath, realPath: parentPath, stat: captured.stat },
+                stagedDirectory: captured.directory,
+            };
+        }
         const stagedDirectory = process.platform === "win32"
             ? undefined
             : describeStagedDirectory(parentFd, parentPath);
         const parentPathStat = rootAdmission.exactRoot
             ? await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })))
-            : fsSync.lstatSync(pathForWindowsFilesystem(parentPath));
+            : fsSync.lstatSync(pathForWindowsFilesystem(parentPath), { bigint: true });
         if (process.platform === "win32" && !rootAdmission.exactRoot) {
-            if (typeof binding.fstatIdentity !== "function") {
-                throw unavailable("native parent directory identity checks are unavailable");
-            }
-            const parentIdentity = binding.fstatIdentity(parentFd);
+            const parentIdentity = fsSync.fstatSync(parentFd, { bigint: true });
             if (parentPathStat.isSymbolicLink() || !sameNativeIdentity(parentPathStat, parentIdentity)) {
                 throw new FsSafeError("path-mismatch", `${rootAdmission.operation} parent changed during resolution`);
             }

package/node_modules/@openclaw/fs-safe/dist/native-pinned-write-windows.d.ts

@@ -1,6 +1,6 @@
-import type { FileHandle } from "node:fs/promises";
+import type { NativeRootAdmission } from "./native-parent-admission.js";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
-import type { NativeBinding } from "./native.js";
+import { type NativeBinding } from "./native.js";
 import type { PinnedWriteParams } from "./pinned-write-types.js";
-export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: FileHandle, parentFd: number, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;
+export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: NativeRootAdmission["root"], parentFd: number, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;

package/node_modules/@openclaw/fs-safe/dist/native-pinned-write-windows.js

@@ -8,6 +8,8 @@ import { assertSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { nativeOpenFlags, removeNativeCreatedFileIfStillPinned, } from "./native-operations.js";
 import { writePinnedInput } from "./pinned-write-input.js";
+import { assertNativeCopyCompleted, createNativeCopyFile } from "./copy-file-input.js";
+import { assertNativeCapabilities } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
@@ -15,6 +17,7 @@ import { classifyNativeRenameFailure } from "./native-rename-outcome.js";
 import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { createStagedFileReceipt, settleStagedFile } from "./staged-file-settlement.js";
 import { exactIdentityMatches } from "./staged-directory.js";
+import { restoreCopyMetadata } from "./copy-metadata.js";
 import { inspectNativeDirectoryObservation } from "./native-directory-observation.js";
 function closeWriteFd(closeFd, fd) {
     if (fd === undefined)
@@ -50,6 +53,7 @@ function assertNamedParentCurrent(binding, guard, identity) {
     assertSyncDirectoryGuard({ ...guard, stat: identity });
 }
 export async function runPinnedWriteWindows(binding, params, root, parentFd, parentGuard) {
+    assertNativeCapabilities(binding, "openBeneath", "renameNoReplace", "renameReplace", "fstatIdentity");
     const closeFd = captureNativeFdClose(binding);
     const parentPath = parentGuard.realPath;
     let tempFd;
@@ -78,6 +82,9 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
     try {
         tempName = `.fs-safe-${randomUUID()}.tmp`;
         params.assertBeforeMutation?.();
+        const copied = params.input.kind === "file" && !params.private
+            ? await createNativeCopyFile(binding, params.input, parentFd, tempName, params.maxBytes)
+            : undefined;
         if (params.private) {
             const parentIdentity = fsSync.fstatSync(parentFd, { bigint: true });
             privateHandle = await createFileHandle(path.join(parentPath, tempName), {
@@ -91,16 +98,25 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
             });
             tempFd = privateHandle.fd;
         }
+        else if (copied) {
+            tempFd = copied.fd;
+        }
         else {
             tempFd = binding.openBeneath(parentFd, tempName, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL)).fd;
         }
         const verificationIdentity = inspectFileIdentitySync(() => fsSync.fstatSync(tempFd, { bigint: true }));
         tempIdentity = verificationIdentity;
+        if (params.input.kind === "file")
+            assertNativeCopyCompleted(params.input, copied);
         // Creation is requested at 0600 in the binding, but a restrictive umask
         // can remove owner access. Keep the unpublished inode private and
         // reopenable until the published name has been identity-fenced.
-        fsSync.fchmodSync(tempFd, 0o600);
-        await writePinnedInput(tempFd, params.input, params.maxBytes, params.assertBeforeMutation);
+        if ((verificationIdentity.mode & 128n) === 0n)
+            fsSync.fchmodSync(tempFd, 0o600);
+        if (!copied)
+            await writePinnedInput(tempFd, params.input, params.maxBytes, params.assertBeforeMutation);
+        if (params.input.kind === "file")
+            restoreCopyMetadata(tempFd, params.input.metadata);
         if (params.sync !== false) {
             if (params.strictFileSync)
                 fsSync.fsyncSync(tempFd);
@@ -132,6 +148,9 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
             }
             assertFinalSymlinkRejected(path.join(parentPath, params.basename), params.rejectFinalSymlink);
         }
+        // The authority callback itself may have cancelled an otherwise completed copy.
+        if (params.input.kind === "file")
+            params.input.signal?.throwIfAborted();
         try {
             if (params.overwrite === false) {
                 binding.renameNoReplace(parentFd, tempName, parentFd, params.basename);
@@ -150,17 +169,25 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
         if (receipt)
             publication = Object.freeze({ status: "published", staged: receipt, basename: params.basename, overwrite: false });
         params.onPublished?.(verificationIdentity);
-        targetFd = binding.openBeneath(parentFd, params.basename, nativeOpenFlags(fsSync.constants.O_RDONLY)).fd;
+        const metadataOnly = params.overwrite === false && params.input.kind === "buffer" &&
+            params.input.stageBeforePublish !== false && !params.private &&
+            !params.assertBeforeMutation && binding.openPublicationMetadata;
+        targetFd = metadataOnly
+            ? metadataOnly(parentFd, params.basename)
+            : binding.openBeneath(parentFd, params.basename, nativeOpenFlags(fsSync.constants.O_RDONLY)).fd;
         const targetStat = inspectFileIdentitySync(() => fsSync.fstatSync(targetFd, { bigint: true }), verificationIdentity);
-        const targetIdentity = binding.fstatIdentity(targetFd);
         if (!targetStat.isFile()) {
             throw new FsSafeError("path-mismatch", "native write target changed after rename");
         }
         // Native exclusive creation starts at 0600. Apply the requested mode only
         // after reopening and fencing the published name, both so mode 000 stays
         // verifiable and so broader modes are never exposed before that fence.
+        // Windows chmod only changes the read-only attribute; use the fresh target
+        // observation to avoid rewriting an unchanged attribute.
+        const modeChange = (targetStat.mode & 128n) !== BigInt(params.mode & 0o200);
         try {
-            fsSync.fchmodSync(targetFd, params.mode);
+            if (modeChange)
+                fsSync.fchmodSync(targetFd, params.mode);
             // Windows FlushFileBuffers needs write access; the verification reopen is read-only.
             if (params.sync !== false) {
                 if (params.strictFileSync)
@@ -194,7 +221,7 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
         else
             await params.verifyPublished?.(targetFd, verificationIdentity, parentGuard);
         completed = true;
-        return { dev: targetIdentity.dev, ino: targetIdentity.ino };
+        return { dev: targetStat.dev, ino: targetStat.ino };
     }
     catch (error) {
         failure = { error };

package/node_modules/@openclaw/fs-safe/dist/native-pinned-write.d.ts

@@ -1,4 +1,7 @@
 import type { FileIdentityStat } from "./file-identity.js";
-import type { NativeBinding } from "./native.js";
+import { type NativeBinding } from "./native.js";
 import type { PinnedWriteParams } from "./pinned-write-types.js";
+type PinnedWriteCapabilitiesInput = Pick<PinnedWriteParams, "input" | "private" | "verifyPosixMode">;
+export declare function getPinnedWriteNativeBinding(params: PinnedWriteCapabilitiesInput): NativeBinding | undefined;
 export declare function runPinnedWriteNative(binding: NativeBinding, params: PinnedWriteParams, fallback: (input: PinnedWriteParams["input"]) => Promise<FileIdentityStat>): Promise<FileIdentityStat>;
+export {};

package/node_modules/@openclaw/fs-safe/dist/native-pinned-write.js

@@ -56,12 +56,27 @@ import { runPinnedWriteWindows } from "./native-pinned-write-windows.js";
 import { capturePolicyAwareNativeParent } from "./native-policy-parent.js";
 import { openNativeParentAdmission, openNativeRootAdmission } from "./native-parent-admission.js";
 import { assertNativeStaging, writeNativeStage } from "./native-staged-file.js";
+import { assertNativeCapabilities, getNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { cachedNoReplaceUnavailable } from "./native-noreplace.js";
 import { isFsSafeNativeRequired } from "./native-config.js";
+import { copyLinkAtParent } from "./copy-link.js";
+const writeCapabilities = ["openBeneath", "mkdirBeneath", "renameNoReplace", "renameReplace"];
+const posixWriteCapabilities = [...writeCapabilities, "createStagedFile", "stagedFileMatches", "removeStagedFile"];
+function pinnedWriteCapabilities(params) {
+    const windows = process.platform === "win32";
+    const capabilities = windows ? [...writeCapabilities, "fstatIdentity"] : posixWriteCapabilities;
+    const nativeCopy = params.input.kind === "file" && !params.private &&
+        (windows || !params.verifyPosixMode);
+    return nativeCopy ? [...capabilities, "copyFileExclusive"] : capabilities;
+}
+export function getPinnedWriteNativeBinding(params) {
+    return getNativeBinding(...pinnedWriteCapabilities(params));
+}
 export async function runPinnedWriteNative(binding, params, fallback) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
+        assertNativeCapabilities(binding, ...pinnedWriteCapabilities(params));
         const closeFd = captureNativeFdClose(binding);
         const windows = process.platform === "win32";
         if (!windows) {
@@ -105,17 +120,21 @@ export async function runPinnedWriteNative(binding, params, fallback) {
                     params.assertBeforeMutation?.();
                     binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
                 }
-                const admitted = await openNativeParentAdmission(binding, rootAdmission, params.relativeParentPath);
+                const admitted = await openNativeParentAdmission(binding, rootAdmission, params.relativeParentPath, "native-publication");
                 parentFd = admitted.fd;
                 parentPath = admitted.guard.realPath;
                 directory = admitted.stagedDirectory;
                 parentPathStat = admitted.guard.stat;
             }
             const verificationGuard = { dir: parentPath, realPath: parentPath, stat: parentPathStat };
+            if (params.input.kind === "link") {
+                return await copyLinkAtParent(params, params.input, verificationGuard, { binding, fd: parentFd });
+            }
             if (params.overwrite === false) {
                 try {
-                    fsSync.lstatSync(path.join(parentPath, params.basename));
-                    throw Object.assign(new Error("destination already exists"), { code: "EEXIST" });
+                    if (fsSync.lstatSync(path.join(parentPath, params.basename), { throwIfNoEntry: false })) {
+                        throw Object.assign(new Error("destination already exists"), { code: "EEXIST" });
+                    }
                 }
                 catch (error) {
                     if (error.code !== "ENOENT") {

package/node_modules/@openclaw/fs-safe/dist/native-policy-directory-observation.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
+import { isNativeStatIdentity, statIdentityFromNative } from "./native-stat-identity.js";
 export class NativePolicyDirectoryMismatch extends FsSafeError {
     constructor(cause) {
         super("path-mismatch", "staging directory pathname changed", { cause });
@@ -39,8 +40,8 @@ export function nativePolicyDirectoryObserver(binding, fd, pathname) {
         }
         if (getFsSafeNativeConfig().mode !== mode)
             return undefined;
-        if (!observed || typeof observed.dev !== "bigint" || observed.dev < 0n || observed.dev > 0xffffffffffffffffn ||
-            typeof observed.ino !== "bigint" || observed.ino < 0n || observed.ino > 0xffffffffffffffffn ||
+        if (!observed || !isNativeStatIdentity(observed.dev) ||
+            !isNativeStatIdentity(observed.ino) ||
             typeof observed.mode !== "bigint" || observed.mode < 0n || observed.mode > 0xffffffffn ||
             typeof observed.nlink !== "bigint" || observed.nlink < 0n || observed.nlink > 0xffffffffffffffffn ||
             typeof observed.realPath !== "string" || observed.realPath.includes("\0") ||
@@ -53,7 +54,7 @@ export function nativePolicyDirectoryObserver(binding, fd, pathname) {
         return Object.freeze({
             canonicalPath: observed.realPath,
             identity: Object.freeze({
-                dev: observed.dev, ino: observed.ino, mode: observed.mode, nlink: observed.nlink,
+                dev: statIdentityFromNative(observed.dev), ino: statIdentityFromNative(observed.ino), mode: observed.mode, nlink: observed.nlink,
             }),
         });
     };

package/node_modules/@openclaw/fs-safe/dist/native-policy-parent.d.ts

@@ -1,6 +1,6 @@
 import { type BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
-import type { NativeBinding } from "./native.js";
+import { type NativeBinding } from "./native.js";
 import type { NativeRootAdmission } from "./native-parent-admission.js";
 import type { PinnedWriteParams } from "./pinned-write-types.js";
 import { describeStagedDirectory, type PolicyStagedDirectory } from "./staged-directory.js";

package/node_modules/@openclaw/fs-safe/dist/native-policy-parent.js

@@ -54,6 +54,7 @@ import fsSync, {} from "node:fs";
 import path from "node:path";
 import { inspectDirectoryIdentity, inspectDirectoryIdentitySync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { assertNativeCapabilities } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
 import { assertWindowsPolicyParentCurrent, closeWindowsPolicyParentAfterFailure, openWindowsPolicyParent, windowsParentObservation, } from "./native-policy-parent-windows.js";
@@ -76,6 +77,7 @@ function mkdirPosixPolicyChild(binding, parentFd, basename) {
         if (typeof created === "boolean")
             return created;
     }
+    assertNativeCapabilities(binding, "mkdirBeneath");
     binding.mkdirBeneath(parentFd, basename, 0o777);
     return false;
 }
@@ -122,6 +124,7 @@ function tryDescribePolicyPosixParent(binding, fd, pathname) {
 export async function capturePolicyAwareNativeParent(binding, params, rootAdmission, windows, directoryFlags, fuseChildCreation = false) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
+        assertNativeCapabilities(binding, "openBeneath");
         const rootFd = rootAdmission.root.fd;
         const closeFd = captureNativeFdClose(binding);
         const observationDisposers = windows ? undefined : new Map();

package/node_modules/@openclaw/fs-safe/dist/native-staged-file-metadata.d.ts

@@ -0,0 +1,3 @@
+import type { NativeBinding } from "./native-binding.js";
+/** Exact nonprivate stage facts from one fresh named/retained observation. */
+export declare function nativeStagedFileMode(binding: NativeBinding, parentFd: number, name: string, fd: number, expectedMode?: number): number | undefined;

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

@@ -0,0 +1,16 @@
+import { FsSafeError } from "./errors.js";
+/** Exact nonprivate stage facts from one fresh named/retained observation. */
+export function nativeStagedFileMode(binding, parentFd, name, fd, expectedMode) {
+    if (typeof binding.stagedFileMetadata !== "function")
+        return undefined;
+    const stat = binding.stagedFileMetadata(parentFd, name, fd);
+    if (!stat || typeof stat.mode !== "bigint" || stat.mode < 0n || stat.mode > 0xffffffffn ||
+        typeof stat.nlink !== "bigint" || stat.nlink !== 1n || (stat.mode & 61440n) !== 32768n) {
+        throw new FsSafeError("path-mismatch", "staged entry no longer names the exclusive created file");
+    }
+    const mode = Number(stat.mode & 4095n);
+    if (expectedMode !== undefined && mode !== expectedMode) {
+        throw new FsSafeError("insecure-permissions", "filesystem did not enforce the staged file mode");
+    }
+    return mode;
+}

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

@@ -5,7 +5,7 @@ import type { FileIdentityStat } from "./file-identity.js";
 import { type NativeBinding } from "./native-binding.js";
 import type { PinnedWriteInput, PinnedWriteParams } from "./pinned-write-types.js";
 import type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileReceipt } from "./staged-file-types.js";
-export type NativeStagingBinding = NativeBinding & Required<Pick<NativeBinding, "createStagedFile" | "stagedFileMatches" | "removeStagedFile">>;
+export type NativeStagingBinding = NativeBinding & Required<Pick<NativeBinding, "createStagedFile" | "stagedFileMatches" | "removeStagedFile" | "renameReplace" | "renameNoReplace">>;
 export declare function assertNativeStaging(binding: NativeBinding): asserts binding is NativeStagingBinding;
 type StagedPermissionPolicy = "private-creation" | "mode-only";
 type NativeStageOwner = Readonly<{

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

@@ -60,13 +60,15 @@ import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult, isMutationAuthorityError } from "./mutation-authority.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { replayPinnedInput, writePinnedInput } from "./pinned-write-input.js";
+import { nativeStagedFileMode } from "./native-staged-file-metadata.js";
 import { assertNativeCopyCompleted, createNativeCopyFile } from "./copy-file-input.js";
-import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
+import { assertNativeStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { classifyNativeRenameFailure } from "./native-rename-outcome.js";
 import { createStagedFileReceipt, stagedFailure } from "./staged-file-settlement.js";
 import { noReplaceUnavailable, rememberNoReplaceUnavailable } from "./native-noreplace.js";
 import { isFsSafeNativeRequired } from "./native-config.js";
+import { restoreCopyMetadata } from "./copy-metadata.js";
 export function assertNativeStaging(binding) {
     if ([
         binding.closeOwnedFd,
@@ -221,6 +223,9 @@ class NativeStagedFile {
     }
     #assertNamed(name, expectedMode) {
         const fd = this.#file();
+        const mode = !this.#private ? nativeStagedFileMode(this.#owner.binding, this.#owner.parentFd, name, fd, this.#verifyMode ? expectedMode : undefined) : undefined;
+        if (mode !== undefined)
+            return mode;
         const stat = this.#owner.binding.stagedFileMatches(this.#owner.parentFd, name, fd)
             ? fs.fstatSync(fd, { bigint: true }) : undefined;
         if (!stat || stat.nlink !== 1n) {
@@ -233,9 +238,12 @@ class NativeStagedFile {
         if (this.#open().publication.status !== "not-published") {
             throw new FsSafeError("helper-failed", "staged file publication has already been attempted");
         }
-        assertStagedDirectoryCurrent(this.#owner.directory);
+        this.#assertDirectory();
         this.#assertNamed(this.#owner.name, 0o600);
     }
+    #assertDirectory() {
+        assertNativeStagedDirectoryCurrent(this.#owner.binding, this.#owner.parentFd, this.#owner.directory);
+    }
     #assertPermissions(fd, stat, expectedMode) {
         if (this.#private)
             assertPrivateCreationFile(stat, fd);
@@ -259,7 +267,7 @@ class NativeStagedFile {
                     throw new FsSafeError("helper-unavailable", "required cloning cannot verify staged permissions before copying");
                 }
             }
-            assertStagedDirectoryCurrent(this.#owner.directory);
+            this.#assertDirectory();
             // The exclusive open performs no fallible post-open checks. Store its fd
             // before every subsequent operation, including the first metadata read.
             const state = this.#open();
@@ -299,6 +307,8 @@ class NativeStagedFile {
             } : this.#assertBeforeMutation;
             if (!copied)
                 await writePinnedInput(fd, input, maxBytes, assertBeforeMutation);
+            if (input.kind === "file")
+                restoreCopyMetadata(fd, input.metadata);
             if (this.#verifyMode)
                 this.#assertStagePermissions(fd);
             if (this.#owner.sync !== false) {
@@ -386,7 +396,7 @@ class NativeStagedFile {
         this.#open().publication = receipt;
         onPublished?.(receipt.staged.identity);
         const stagedMode = this.#assertNamed(basename, 0o600);
-        assertStagedDirectoryCurrent(this.#owner.directory);
+        this.#assertDirectory();
         // Keep contents private until the name passes its identity fence. Mode
         // changes use the owned fd, including for final mode 000.
         const fd = this.#file();
@@ -403,7 +413,7 @@ class NativeStagedFile {
         if (this.#owner.sync !== false)
             syncFileBestEffortSync(this.#owner.parentFd);
         this.#assertNamed(basename, this.#owner.mode);
-        assertStagedDirectoryCurrent(this.#owner.directory);
+        this.#assertDirectory();
         return receipt;
     }
     #finalize() {

package/node_modules/@openclaw/fs-safe/dist/native-stat-identity.d.ts

@@ -0,0 +1,3 @@
+/** Native stat identities are unsigned; Node BigIntStats preserves them as signed bits. */
+export declare function statIdentityFromNative(value: bigint): bigint;
+export declare function isNativeStatIdentity(value: unknown): value is bigint;

package/node_modules/@openclaw/fs-safe/dist/native-stat-identity.js

@@ -0,0 +1,7 @@
+/** Native stat identities are unsigned; Node BigIntStats preserves them as signed bits. */
+export function statIdentityFromNative(value) {
+    return value <= 0x7fffffffffffffffn || process.versions.bun ? value : BigInt.asIntN(64, value);
+}
+export function isNativeStatIdentity(value) {
+    return typeof value === "bigint" && value >= 0n && value <= 0xffffffffffffffffn;
+}

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

@@ -0,0 +1,17 @@
+import { type FsSafeNativeMode } from "./native-config.js";
+export type FsSafeNativeStatusReason = "not-probed" | "loaded" | "disabled" | "unsupported-target" | "package-missing" | "load-failed" | "capability-missing";
+export type FsSafeNativeStatus = {
+    mode: FsSafeNativeMode;
+    modeSource: "programmatic configuration" | "FS_SAFE_NATIVE_MODE" | "OPENCLAW_FS_SAFE_NATIVE_MODE" | "default";
+    reason: FsSafeNativeStatusReason;
+    loaded: boolean;
+    target: string;
+    packageName?: string;
+    packageVersion?: string;
+    loadErrorCode?: string;
+    guidance?: string;
+};
+/** Read this module instance's cached native outcome, optionally probing once. */
+export declare function readFsSafeNativeStatus(options?: {
+    probe?: boolean;
+}): FsSafeNativeStatus;

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

@@ -0,0 +1,30 @@
+import { getNativeModeSetting } from "./native-config.js";
+import { nativeGuidance } from "./native-guidance.js";
+import { getNativeBinding, getNativeFallbackDiagnostic } from "./native.js";
+/** Read this module instance's cached native outcome, optionally probing once. */
+export function readFsSafeNativeStatus(options) {
+    const { mode, source: modeSource } = getNativeModeSetting();
+    if (options?.probe && mode !== "off") {
+        try {
+            getNativeBinding();
+        }
+        catch {
+            // Required-mode load failures are cached; health checks report them.
+        }
+    }
+    const diagnostic = getNativeFallbackDiagnostic();
+    const guidance = nativeGuidance(diagnostic.reason, modeSource);
+    return {
+        mode,
+        modeSource,
+        reason: diagnostic.reason,
+        loaded: diagnostic.reason === "loaded",
+        target: diagnostic.target,
+        ...(diagnostic.packageName === undefined ? {} : {
+            packageName: diagnostic.packageName,
+            packageVersion: diagnostic.packageVersion,
+        }),
+        ...(diagnostic.reason === "load-failed" ? { loadErrorCode: diagnostic.code } : {}),
+        ...(guidance === undefined ? {} : { guidance }),
+    };
+}

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

@@ -1,5 +1,30 @@
-import { type NativeBinding } from "./native-binding.js";
+import { type NativeBinding, type CapableNativeBinding } from "./native-binding.js";
 export type { NativeBinding } from "./native-binding.js";
+/** Internal view of the cached load; never attempts to load an addon. */
+export declare function getNativeFallbackDiagnostic(...capabilities: (keyof NativeBinding)[]): {
+    target: string;
+    packageName: string | undefined;
+    packageVersion: string | undefined;
+    reason: "disabled";
+    source: "FS_SAFE_NATIVE_MODE" | "OPENCLAW_FS_SAFE_NATIVE_MODE" | "default" | "programmatic configuration";
+} | {
+    target: string;
+    packageName: string | undefined;
+    packageVersion: string | undefined;
+    reason: "capability-missing";
+    capabilities: (keyof NativeBinding)[];
+} | {
+    reason: "not-probed" | "loaded" | "unsupported-target" | "package-missing";
+    target: string;
+    packageName: string | undefined;
+    packageVersion: string | undefined;
+} | {
+    reason: "load-failed";
+    code: string;
+    target: string;
+    packageName: string | undefined;
+    packageVersion: string | undefined;
+};
 export declare function __loadBundledNativeForTest(): NativeBinding;
 export declare function __nativeLoaderDetectorsForTest(): {
     report: boolean | undefined;
@@ -7,7 +32,9 @@ export declare function __nativeLoaderDetectorsForTest(): {
     elfInterpreter: boolean | undefined;
 };
 export declare function __nativeTargetForTest(platform: NodeJS.Platform, arch: string, musl?: boolean): string | undefined;
-export declare function getNativeBinding(): NativeBinding | undefined;
-export declare function requireNativeBinding(): NativeBinding;
-export declare function __setNativeLoaderForTest(loader: () => NativeBinding): void;
+export declare function selectNativeBinding<K extends keyof NativeBinding>(native: NativeBinding | undefined, ...capabilities: K[]): CapableNativeBinding<K> | undefined;
+export declare function assertNativeCapabilities<K extends keyof NativeBinding>(native: NativeBinding, ...capabilities: K[]): asserts native is CapableNativeBinding<K>;
+export declare function getNativeBinding<K extends keyof NativeBinding = never>(...capabilities: K[]): CapableNativeBinding<K> | undefined;
+export declare function requireNativeBinding<K extends keyof NativeBinding = never>(...capabilities: K[]): CapableNativeBinding<K>;
+export declare function __setNativeLoaderForTest(loader: () => NativeBinding, resolver?: (name: string) => string): void;
 export declare function __resetNativeLoaderForTest(): void;