@openclaw/matrix 2026.10.5 → 2026.10.7

package/node_modules/@openclaw/fs-safe/dist/darwin-acl.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import { getNativeBinding } from "./native.js";
+/** Inspect one no-follow descriptor. Unknown is never evidence of no ACL. */
+export function inspectDarwinAcl(path) {
+    if (process.platform !== "darwin")
+        return { kind: "unknown", reason: "unsupported-platform" };
+    let fd;
+    try {
+        const native = getNativeBinding();
+        if (!native?.inspectDarwinAcl)
+            return { kind: "unknown", reason: "helper-unavailable" };
+        fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        const facts = native.inspectDarwinAcl(fd);
+        if (facts.state === "absent" || facts.state === "empty")
+            return { kind: "none" };
+        if (facts.state === "present" && typeof facts.inheritsToFiles === "boolean" &&
+            typeof facts.inheritsToDirectories === "boolean") {
+            return { kind: "present", inheritsToFiles: facts.inheritsToFiles, inheritsToDirectories: facts.inheritsToDirectories };
+        }
+        return { kind: "unknown", reason: "incomplete-acl-facts" };
+    }
+    catch (error) {
+        return { kind: "unknown", reason: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}

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

@@ -5,6 +5,7 @@ export type DirectoryModeChecks = {
 };
 export type DirectoryModeOwner = {
     verify(check?: () => void): Promise<void>;
+    verifyCanonical?(): Promise<boolean>;
     apply(mode: number, checks?: DirectoryModeChecks): Promise<void>;
     close(): Promise<void>;
 };
@@ -12,6 +13,7 @@ export declare function assertOwnedDirectory(expected: Stats | BigIntStats, actu
 /** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
 export declare function ownDirectoryMode(params: {
     inspect: () => Promise<number>;
+    inspectCanonical?: () => number | undefined;
     chmod: (mode: number) => Promise<void>;
     prepareChmod?: () => Promise<void>;
     verifyChmod?: () => Promise<void>;
@@ -28,6 +30,7 @@ export declare function nodeDirectorySearchOnlyFlags(): {
 export declare function pinNodeDirectoryForMode(dirPath: string, options?: {
     expectedIdentity?: BigIntStats;
     ownerUid?: number;
+    canonicalPath?: string;
 }): Promise<DirectoryModeOwner>;
 /** Synchronous counterpart with the same no-follow, identity, and owner checks. */
 export declare function pinNodeDirectoryForModeSync(dirPath: string, options?: {

package/node_modules/@openclaw/fs-safe/dist/directory-mode-node.js

@@ -4,6 +4,8 @@ import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { getNativeBinding } from "./native.js";
+import { nativePolicyDirectoryObserver } from "./native-policy-directory-observation.js";
 export function assertOwnedDirectory(expected, actual) {
     if (actual.isSymbolicLink() || !actual.isDirectory()) {
         throw new FsSafeError("not-file", "directory mode target must be a real directory");
@@ -23,7 +25,7 @@ export function ownDirectoryMode(params) {
         pending = operation.catch(() => undefined);
         return operation;
     };
-    return {
+    const owner = {
         verify: (check) => enqueue(async () => {
             check?.();
             await params.inspect();
@@ -79,6 +81,14 @@ export function ownDirectoryMode(params) {
             return closing;
         },
     };
+    if (params.inspectCanonical) {
+        owner.verifyCanonical = async () => {
+            let verified = false;
+            await enqueue(async () => { verified = params.inspectCanonical() !== undefined; });
+            return verified;
+        };
+    }
+    return owner;
 }
 /** Darwin descriptor inspection avoids requesting directory-content reads. */
 export function nodeDarwinDirectoryMetadataFlags() {
@@ -131,7 +141,11 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
         proc = route.proc;
         return await fs.open(dirPath, route.flags | flags);
     });
+    let observer;
     try {
+        observer = options.canonicalPath === dirPath && ownerUid === undefined
+            ? nativePolicyDirectoryObserver(getNativeBinding(), handle.fd, dirPath)
+            : undefined;
         const inspect = async () => {
             const opened = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), expected);
             assertOwnedDirectory(expected, opened);
@@ -153,8 +167,18 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
             assertOwner(opened);
             assertOwner(followed);
         };
+        const observeCanonical = observer;
         const owner = ownDirectoryMode({
             inspect,
+            inspectCanonical: observeCanonical ? () => {
+                const observed = observeCanonical();
+                if (!observed)
+                    return undefined;
+                if (observed.identity.dev !== expected.dev || observed.identity.ino !== expected.ino) {
+                    throw new FsSafeError("path-mismatch", "directory changed before its mode could be applied");
+                }
+                return Number(observed.identity.mode & 4095n);
+            } : undefined,
             prepareChmod: proc ? assertProcAuthority : undefined,
             verifyChmod: proc ? assertProcAuthority : undefined,
             async chmod(mode) {
@@ -165,12 +189,13 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
                     await handle.chmod(mode);
                 }
             },
-            close: () => handle.close(),
+            close: () => { observer?.dispose(); return handle.close(); },
         });
         await owner.verify();
         return owner;
     }
     catch (error) {
+        observer?.dispose();
         try {
             await handle.close();
         }

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

@@ -230,7 +230,7 @@ export function retainEntryForPublication(options) {
         inspectEntry(sourcePath, source.expected);
         const sourceFd = kind === "symlink"
             ? binding.openStagedSymlink(sourceParent.fd, source.basename)
-            : binding.openBeneath(sourceParent.fd, source.basename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK |
+            : native.openBeneath(sourceParent.fd, source.basename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK |
                 (kind === "directory" ? fs.constants.O_DIRECTORY : 0))?.fd;
         if (!Number.isInteger(sourceFd) || sourceFd < 0) {
             throw new FsSafeError("helper-unavailable", "publication source descriptor is unavailable");

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

@@ -113,7 +113,8 @@ export async function copyFileHandle(source, target, options = {}) {
     const assertBeforeMutation = composeMutationAssertions(undefined, options.assertBeforeMutation);
     const sourceStat = await inspectFileIdentity(() => {
         signal?.throwIfAborted();
-        return source.stat({ bigint: true });
+        const fd = source.fd;
+        return fd < 0 ? source.stat({ bigint: true }) : fs.fstatSync(fd, { bigint: true });
     });
     signal?.throwIfAborted();
     if (!sourceStat.isFile())
@@ -123,7 +124,8 @@ export async function copyFileHandle(source, target, options = {}) {
     }
     const targetStat = await inspectFileIdentity(() => {
         signal?.throwIfAborted();
-        return target.stat({ bigint: true });
+        const fd = target.fd;
+        return fd < 0 ? target.stat({ bigint: true }) : fs.fstatSync(fd, { bigint: true });
     });
     signal?.throwIfAborted();
     if (!targetStat.isFile())

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

@@ -55,7 +55,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
-import { getNativeBinding } from "./native.js";
+import { getNativeBinding, selectNativeBinding } from "./native.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
@@ -100,11 +100,12 @@ export async function hashFileHandle(handle, native = getNativeBinding(), { maxB
         if (stat.size > maxBytes) {
             throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
         }
-        if (native) {
+        const hasher = selectNativeBinding(native, "sha256File");
+        if (hasher) {
             // A completed N-API task can mask later aborts on the same signal.
             const nativeSignal = signal ? AbortSignal.any([signal]) : undefined;
             try {
-                const result = await native.sha256File(handle.fd, Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
+                const result = await hasher.sha256File(handle.fd, Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
                 signal?.throwIfAborted();
                 return result;
             }

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

@@ -1,4 +1,5 @@
 import { type SidecarLockAcquireOptions, type SidecarLockHandle, type SidecarLockHeldEntry, type SidecarLockRetryOptions, type SidecarLockStaleRecovery } from "./sidecar-lock.js";
+export { tryAcquireWriteLease, type FileWriteLease } from "./file-write-lease.js";
 export { acquireFileLockSync, withFileLockSync, type FileLockSyncAcquireOptions, type FileLockSyncHandle, } from "./file-lock-sync.js";
 export type FileLockRetryOptions = SidecarLockRetryOptions;
 export type FileLockStaleRecovery = SidecarLockStaleRecovery;

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

@@ -1,5 +1,6 @@
 import { createSidecarLockManager, } from "./sidecar-lock.js";
 import { getFsSafeLockConfig } from "./lock-config.js";
+export { tryAcquireWriteLease } from "./file-write-lease.js";
 export { acquireFileLockSync, withFileLockSync, } from "./file-lock-sync.js";
 function resolveFileLockManagerKey(targetPath, managerKey) {
     return managerKey ?? `fs-safe.file-lock:${targetPath}`;

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

@@ -0,0 +1,9 @@
+export type FileWriteLease = {
+    readonly fd: number;
+    /** False after release or when the kernel breaks or downgrades the lease. */
+    isHeld(): boolean;
+    release(): void;
+    [Symbol.dispose](): void;
+};
+/** Linux kernel write lease. The caller retains the open fd and SIGIO handling. */
+export declare function tryAcquireWriteLease(fd: number): FileWriteLease | null;

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

@@ -0,0 +1,42 @@
+import { FsSafeError } from "./errors.js";
+import { requireNativeBinding } from "./native.js";
+/** Linux kernel write lease. The caller retains the open fd and SIGIO handling. */
+export function tryAcquireWriteLease(fd) {
+    if (process.platform !== "linux") {
+        throw new FsSafeError("unsupported-platform", "File write leases require Linux");
+    }
+    if (!Number.isInteger(fd) || fd < 0 || fd > 0x7fffffff) {
+        throw new FsSafeError("invalid-path", "Expected an open file descriptor");
+    }
+    const native = requireNativeBinding();
+    const acquire = native.tryAcquireWriteLease?.bind(native);
+    const held = native.isFileWriteLeaseHeld?.bind(native);
+    const unlock = native.releaseFileWriteLease?.bind(native);
+    if (!acquire || !held || !unlock) {
+        throw new FsSafeError("helper-unavailable", "Native file write leases are unavailable");
+    }
+    const call = (operation) => {
+        try {
+            return operation();
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "Native file write lease operation failed", { cause });
+        }
+    };
+    if (!call(() => acquire(fd)))
+        return null;
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        // Never retry an ambiguous settlement against a potentially recycled fd.
+        released = true;
+        call(() => unlock(fd));
+    };
+    return Object.freeze({
+        fd,
+        isHeld: () => !released && call(() => held(fd)),
+        release,
+        [Symbol.dispose]: release,
+    });
+}

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

@@ -92,6 +92,9 @@ export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
     "        try:",
     "            os.rename(src_basename + '/', dst_basename, src_dir_fd=src_parent_fd, dst_dir_fd=dst_parent_fd)",
     "        except OSError as error:",
+    "            # ENOTDIR can describe the slash-checked source, not just the target.",
+    "            if error.errno == errno.ENOTDIR:",
+    "                verify(src_parent_fd, src_basename, 1)",
     "            if error.errno in (errno.ENOTEMPTY, errno.ENOTDIR, errno.EEXIST):",
     "                raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), dst_basename) from error",
     "            raise",

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

@@ -0,0 +1 @@
+export declare function isHardlinkFallbackError(error: unknown): boolean;

package/node_modules/@openclaw/fs-safe/dist/hardlink-fallback.js

@@ -0,0 +1,5 @@
+// These refusals leave the destination uncreated. EEXIST is deliberately excluded.
+const HARDLINK_FALLBACK_CODES = new Set(["EACCES", "EPERM", "EXDEV", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
+export function isHardlinkFallbackError(error) {
+    return HARDLINK_FALLBACK_CODES.has(error?.code ?? "");
+}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { syncDirectory } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+import { isHardlinkFallbackError } from "./hardlink-fallback.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { serializePathWrite } from "./write-queue.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
@@ -61,6 +62,18 @@ async function withQueueEntryLock(paths, run) {
     assertNoWindowsPathAlias(resolvedJsonPath);
     return await serializePathWrite(paths.jsonPath, async () => await withQueueTransferLock(resolvedJsonPath, run));
 }
+async function linkQueueGeneration(sourcePath, targetPath) {
+    try {
+        await fs.link(sourcePath, targetPath);
+    }
+    catch (error) {
+        // Shared inode identity is recovery evidence; a copy cannot replace it.
+        if (isHardlinkFallbackError(error)) {
+            throw new FsSafeError("helper-unavailable", "durable queue ownership requires hardlink support", { cause: error });
+        }
+        throw error;
+    }
+}
 async function claimDurableQueueEntryUnlocked(paths, options = {}) {
     const processingPath = paths.processingPath;
     await recoverDurableQueueRetirement({ jsonPath: paths.jsonPath, processingPath });
@@ -92,7 +105,7 @@ async function claimDurableQueueEntryUnlocked(paths, options = {}) {
         throw new FsSafeError("path-mismatch", "queue entry is not exclusively owned");
     }
     try {
-        await fs.link(paths.jsonPath, processingPath);
+        await linkQueueGeneration(paths.jsonPath, processingPath);
     }
     catch (error) {
         if (getErrorCode(error) === "EEXIST") {
@@ -227,7 +240,7 @@ export async function moveDurableQueueEntryToFailed(params) {
             throw new FsSafeError("already-exists", "failed queue destination already exists");
         }
         if (!failed)
-            await fs.link(sourcePath, failedPath);
+            await linkQueueGeneration(sourcePath, failedPath);
         await syncDirectory(path.dirname(failedPath));
         await fs.unlink(sourcePath);
         await syncDirectory(path.dirname(sourcePath));
@@ -305,7 +318,7 @@ async function recoverDurableQueueRetirement(params) {
     if (!sameFileIdentityForCleanup(entry, processing)) {
         const pending = regularQueueFileIdentity(params.jsonPath, "retirement");
         if (!pending) {
-            await fs.link(entryPath, params.jsonPath);
+            await linkQueueGeneration(entryPath, params.jsonPath);
             await syncDirectory(path.dirname(params.jsonPath));
         }
         else if (sameFileIdentityForCleanup(pending, entry)) {

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

@@ -124,6 +124,8 @@ export interface NativeWindowsDirectoryReceipt {
 }
 export interface NativeDarwinAclFacts {
     state: "absent" | "empty" | "present";
+    inheritsToFiles?: boolean;
+    inheritsToDirectories?: boolean;
 }
 type NativeTwoPathArgs = [
     sourceRootFd: number,
@@ -132,6 +134,37 @@ type NativeTwoPathArgs = [
     targetRelPath: string
 ];
 export interface NativeBinding {
+    readCopyMetadata?(fd: number): Buffer;
+    restoreCopyMetadata?(fd: number, snapshot: Buffer): void;
+    restoreCopyFileTimes?(fd: number, atimeNs: bigint, mtimeNs: bigint): void;
+    copyLinkExclusive?(sourceParent: number, sourceName: string, parent: number, name: string, dev: bigint, ino: bigint, preserveMetadata: boolean, mode: number): {
+        dev: bigint;
+        ino: bigint;
+    };
+    publishCopyLink?(parent: number, name: string, destination: string, dev: bigint, ino: bigint): void;
+    removeCopyLink?(parent: number, name: string, dev: bigint, ino: bigint): void;
+    createCopySymlink?(parent: number, name: string, target: Buffer, mode: number, atimeNs?: bigint, mtimeNs?: bigint): {
+        dev: bigint;
+        ino: bigint;
+        errorCode?: string;
+        errorMessage?: string;
+    };
+    tryAcquireWriteLease?(fd: number): boolean;
+    isFileWriteLeaseHeld?(fd: number): boolean;
+    releaseFileWriteLease?(fd: number): void;
+    holdWindowsSharingLock?(path: string): {
+        close(): void;
+    };
+    setWindowsFileAttributes?(path: string, attrs: {
+        readOnly?: boolean;
+        hidden?: boolean;
+        system?: boolean;
+    }): void;
+    readWindowsFileExtents?(path: string): {
+        vcn: bigint;
+        lcn: bigint;
+        clusters: bigint;
+    }[];
     rootRemovalStat?(parent: number, name: string): NativeRootRemovalEntry;
     rootRemovalUnlink?(parent: number, name: string, dev: bigint, ino: bigint, directory: boolean): void;
     openRootRemovalDirectory?(parent: number, name: string, dev: bigint, ino: bigint): NativeRootRemovalDirectory;
@@ -169,6 +202,11 @@ export interface NativeBinding {
     };
     /** Internal: consumes only a descriptor returned by this binding. */
     closeOwnedFd(fd: number): void;
+    createPipe?(): {
+        reader: number;
+        writer: number;
+        atomicCloseOnExec: boolean;
+    };
     /** Internal Darwin-only synchronous inspection; the caller retains its fd. */
     inspectDarwinAcl?(fd: number, inheritanceTarget?: "file" | "directory"): NativeDarwinAclFacts;
     /** POSIX system canonicalization; confinement and identity policy stay with callers. */
@@ -183,18 +221,18 @@ export interface NativeBinding {
     /** Linux/Windows byte transfer; callers retain both admitted descriptors until settlement. */
     copyFileContents?(sourceFd: number, targetFd: number, signal?: AbortSignal): Promise<void>;
     /** Internal: same private, immutable input ownership as the ZIP buffer reader. */
-    openTarBufferNative(buffer: Buffer, kind: string, limits: TarMeterLimits, signal?: AbortSignal): Promise<{
+    openTarBufferNative?(buffer: Buffer, kind: string, limits: TarMeterLimits, signal?: AbortSignal): Promise<{
         readonly entries: NativeArchiveEntry[];
         readEntry(index: number, maxBytes: number, signal?: AbortSignal): Promise<Buffer>;
     }>;
     /** Internal: input remains private, unpooled and immutable until the reader is released. */
-    openZipBufferNative(buffer: Buffer, limits: TarMeterLimits, signal?: AbortSignal): Promise<{
+    openZipBufferNative?(buffer: Buffer, limits: TarMeterLimits, signal?: AbortSignal): Promise<{
         readonly entries: NativeArchiveEntry[];
         readEntry(index: number, maxBytes: number, signal?: AbortSignal): Promise<Buffer>;
     }>;
-    readCloneFileMetadata(paths: string[]): Promise<(Buffer | null)[]>;
-    probeTreeClone(parentFd: number): "apfs" | "btrfs" | "refs" | "xfs" | "zfs" | null;
-    cloneTree(sourceFd: number | null, parentFd: number, basename: string, concurrency: number, signal?: AbortSignal): Promise<void>;
+    readCloneFileMetadata?(paths: string[]): Promise<(Buffer | null)[]>;
+    probeTreeClone?(parentFd: number): "apfs" | "btrfs" | "refs" | "xfs" | "zfs" | null;
+    cloneTree?(sourceFd: number | null, parentFd: number, basename: string, concurrency: number, signal?: AbortSignal): Promise<void>;
     openStagedSymlink?(parentFd: number, basename: string): number;
     stagedSymlinkTarget?(parentFd: number, basename: string, linkFd: number): string;
     stagedSymlinkMatches?(parentFd: number, basename: string, linkFd: number): boolean;
@@ -205,28 +243,28 @@ export interface NativeBinding {
     removeStagedFile?(parentFd: number, basename: string, fileFd: number): "removed" | "name-absent" | "preserved";
     copyFileExclusive?(sourceFd: number, parentFd: number, basename: string, clone: CopyCloneMode, maxBytes: number | undefined, signal: AbortSignal | undefined): Promise<NativeFileCopyResult>;
     copyFileExclusiveSync?(sourceFd: number, parentFd: number, basename: string, clone: CopyCloneMode, maxBytes: number | undefined): NativeFileCopyResult;
-    cloneFileExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): number;
-    copyFileRangeExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): Promise<NativeCopyResult>;
-    createPrivateDirectory(path: string): void;
+    cloneFileExclusive?(sourceFd: number, targetRootFd: number, targetRelPath: string): number;
+    copyFileRangeExclusive?(sourceFd: number, targetRootFd: number, targetRelPath: string): Promise<NativeCopyResult>;
+    createPrivateDirectory?(path: string): void;
     /** Internal Windows creation receipts use full FILE_ID_INFO, never Node's projection. */
     inspectWindowsDirectory?(path: string, requirePrivate: boolean): NativeWindowsDirectoryReceipt;
     createPrivateDirectoryWithParentIdentity?(path: string, expectedParentIdentity: string): NativeWindowsDirectoryReceipt;
     /** Protects an already-private borrowed Node file; descriptor ownership stays with Node. */
     protectPrivateWindowsFile?(fd: number, path: string, expectedParentIdentity: string): NativeWindowsDirectoryReceipt;
     verifyPrivateWindowsFile?(fd: number, path: string, expectedFileIdentity: string, expectedParentIdentity: string, expectedLinks: number): void;
-    extractArchiveNative(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], limits: TarMeterLimits, signal: AbortSignal): Promise<void>;
-    fstatIdentity(fd: number): NativeFileIdentity;
-    inspectArchiveNative(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
-    linkBeneath(...args: NativeTwoPathArgs): void;
+    extractArchiveNative?(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], limits: TarMeterLimits, signal: AbortSignal): Promise<void>;
+    fstatIdentity?(fd: number): NativeFileIdentity;
+    inspectArchiveNative?(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
+    linkBeneath?(...args: NativeTwoPathArgs): void;
     /** Direct-child mkdir; true is receipt provenance only, never cleanup ownership. */
     mkdirChildBeneath?(parentFd: number, basename: string, mode: number): boolean;
     mkdirOpenChildBeneath?(parentFd: number, basename: string, mode: number, flags: number): {
         fd: number;
         created: boolean;
     };
-    mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
-    openBeneath(rootFd: number, relPath: string, flags: number): NativeOpenBeneathResult;
-    readOwnerAndDacl(path: string): NativeWindowsSecurityFacts;
+    mkdirBeneath?(rootFd: number, relPath: string, mode: number): void;
+    openBeneath?(rootFd: number, relPath: string, flags: number): NativeOpenBeneathResult;
+    readOwnerAndDacl?(path: string): NativeWindowsSecurityFacts;
     /** Internal Windows-only inspection of the exact borrowed Node descriptor. */
     inspectWindowsSecureFileHandle?(fd: number): NativeWindowsDescriptorSecurityFacts;
     ownedTreeRemovalAvailable?(parentFd: number): boolean;
@@ -236,13 +274,14 @@ export interface NativeBinding {
     retainWindowsEntryPublication?(sourcePath: string, name: string, sourceDev: bigint, sourceIno: bigint, targetPath: string, targetName: string, targetDev: bigint, targetIno: bigint, dev: bigint, ino: bigint, kind: "file" | "directory" | "symlink"): NativeWindowsEntryPublication;
     entryPublicationFilesystem?(parentFd: number): string;
     publishRetainedEntryNoReplace?(sourceParentFd: number, sourceBasename: string, sourceFd: number, targetParentFd: number, targetBasename: string): NativePublicationTransition;
-    renameNoReplace(...args: NativeTwoPathArgs): void;
+    renameNoReplace?(...args: NativeTwoPathArgs): void;
     /** Linux auto-mode fallback through already-admitted direct-child parents. */
     moveNoReplaceFallback?(...args: [...paths: NativeTwoPathArgs, expectedSourceDev: bigint, expectedSourceIno: bigint]): void;
     /** Identity-fenced retained-directory rename capability. */
     renameNoReplaceWithIdentity?(...args: [...paths: NativeTwoPathArgs, expectedSourceDev: bigint, expectedSourceIno: bigint]): void;
-    renameReplace(...args: NativeTwoPathArgs): void;
-    sha256File(fd: number, maxBytes?: number, signal?: AbortSignal): Promise<NativeFileHash>;
+    renameReplace?(...args: NativeTwoPathArgs): void;
+    sha256File?(fd: number, maxBytes?: number, signal?: AbortSignal): Promise<NativeFileHash>;
 }
+export type CapableNativeBinding<K extends keyof NativeBinding> = NativeBinding & Required<Pick<NativeBinding, K>>;
 export declare function captureNativeFdClose(binding: NativeBinding): (fd: number) => void;
 export {};

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

@@ -5,7 +5,7 @@ import { inspectFileIdentitySync } from "./strict-file-identity.js";
 export function getNativeDirectoryObservationBackend(enabled = true) {
     if (!enabled)
         return undefined;
-    const binding = getNativeBinding();
+    const binding = getNativeBinding("observeDirectory");
     return binding && typeof binding.observeDirectory === "function"
         ? binding
         : undefined;

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

@@ -1,3 +1,3 @@
 import type { BigIntStats } from "node:fs";
 import type { NativeBinding } from "./native-binding.js";
-export declare function nativeMoveNoReplace(binding: NativeBinding, paths: Parameters<NativeBinding["renameNoReplace"]>, expected: BigIntStats | undefined, allowFallback: boolean, operation?: string): "link-unlink" | undefined;
+export declare function nativeMoveNoReplace(binding: NativeBinding, paths: Parameters<NonNullable<NativeBinding["renameNoReplace"]>>, expected: BigIntStats | undefined, allowFallback: boolean, operation?: string): "link-unlink" | undefined;

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

@@ -1,4 +1,5 @@
 import { FsSafeError } from "./errors.js";
+import { assertNativeCapabilities } from "./native.js";
 import { cachedNoReplaceUnavailable, noReplaceUnavailable, rememberNoReplaceUnavailable, } from "./native-noreplace.js";
 function fallbackError(error, operation) {
     const code = error?.code;
@@ -24,6 +25,7 @@ function fallbackError(error, operation) {
     return error;
 }
 export function nativeMoveNoReplace(binding, paths, expected, allowFallback, operation = "move") {
+    assertNativeCapabilities(binding, "renameNoReplace");
     const [sourceFd, source, targetFd, target] = paths;
     let unavailable = cachedNoReplaceUnavailable(binding, sourceFd, operation);
     if (!unavailable) {

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

@@ -32,7 +32,7 @@ export function removeNativeCreatedFileIfStillPinned(params) {
     }
 }
 export async function createNativeExclusiveFile(targetPath, mode) {
-    const binding = getNativeBinding();
+    const binding = getNativeBinding("openBeneath");
     if (!binding) {
         return undefined;
     }

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

@@ -1,7 +1,7 @@
 import { type BigIntStats, type Stats } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
 import type { FileIdentityStat } from "./file-identity.js";
-import type { NativeBinding } from "./native.js";
+import { type NativeBinding } from "./native.js";
 import { describeStagedDirectory } from "./staged-directory.js";
 type RootIdentity = Pick<FileIdentityStat, "dev" | "ino">;
 export type NativeRootAdmission = {

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

@@ -5,6 +5,7 @@ import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./direct
 import { nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
 import { inspectNativeDirectoryObservation } from "./native-directory-observation.js";
 import { FsSafeError } from "./errors.js";
+import { assertNativeCapabilities } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { realpathSync } from "./realpath.js";
 import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
@@ -22,6 +23,7 @@ function assertParentAdmissionAvailable(binding) {
         throw unavailable("native parent directory admission is unavailable");
     }
     captureNativeFdClose(binding);
+    assertNativeCapabilities(binding, "openBeneath");
 }
 export async function openNativeRootAdmission(binding, params) {
     assertParentAdmissionAvailable(binding);

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

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,24 @@ 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 (!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 +147,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);

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 {};