@openclaw/matrix 2026.10.1-beta.2 → 2026.10.2

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

@@ -59,12 +59,14 @@ import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult, isMutationAuthorityError } from "./mutation-authority.js";
 import { captureNativeFdClose } from "./native-binding.js";
-import { writePinnedInput } from "./pinned-write-input.js";
+import { replayPinnedInput, writePinnedInput } from "./pinned-write-input.js";
 import { assertNativeCopyCompleted, createNativeCopyFile } from "./copy-file-input.js";
 import { assertStagedDirectoryCurrent, 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";
 export function assertNativeStaging(binding) {
     if ([
         binding.closeOwnedFd,
@@ -93,6 +95,9 @@ class NativeStagedFile {
     #state = { status: "open", publication: NOT_PUBLISHED };
     #receipt;
     #rejectFinalSymlink = false;
+    #unsupportedNoReplace;
+    #fallbackCleanup;
+    #fallbackCleanupError;
     constructor(owner) {
         const name = owner.name ?? `.fs-safe-${randomUUID()}.tmp`;
         assertBasename(name, owner.portableNames !== false);
@@ -121,7 +126,7 @@ class NativeStagedFile {
         await staged.#prepare(input, maxBytes);
         return staged;
     }
-    static async write(binding, parentFd, closeParentFd, directory, params, parentGuard) {
+    static async write(binding, parentFd, closeParentFd, directory, params, parentGuard, fallback) {
         const env_1 = { stack: [], error: void 0, hasError: false };
         try {
             const exclusive = params.overwrite === false && params.input.kind === "buffer" && params.input.stageBeforePublish === false;
@@ -143,9 +148,33 @@ class NativeStagedFile {
                 if (staged.#verifyMode)
                     staged.#assertCurrent();
             }
-            const published = exclusive
-                ? staged.#completePublication(params.basename, false, params.onPublished)
-                : await staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
+            let published;
+            try {
+                published = exclusive
+                    ? staged.#completePublication(params.basename, false, params.onPublished)
+                    : await staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
+            }
+            catch (error) {
+                if (!staged.#unsupportedNoReplace || isFsSafeNativeRequired() ||
+                    (params.input.kind === "file" && params.input.clone === "always"))
+                    throw error;
+                // Remove only our identity-known stage before re-admitting the JS write.
+                // Keep its descriptor alive to replay a one-shot stream in bounded chunks.
+                staged.#fallbackCleanup = "failed";
+                let removed;
+                try {
+                    removed = binding.removeStagedFile(parentFd, staged.#owner.name, staged.#file());
+                    staged.#fallbackCleanup = removed;
+                }
+                catch (cleanupError) {
+                    staged.#fallbackCleanupError = { error: cleanupError };
+                    throw error;
+                }
+                if (removed !== "removed" && removed !== "name-absent")
+                    throw error;
+                rememberNoReplaceUnavailable(binding, parentFd, staged.#unsupportedNoReplace);
+                return await fallback(replayPinnedInput(staged.#file(), params.input));
+            }
             const identity = published.staged.identity;
             try {
                 await params.verifyPublished?.(staged.#file(), identity, parentGuard);
@@ -321,6 +350,15 @@ class NativeStagedFile {
             catch (error) {
                 // Record before inspecting metadata, whose getters can reenter cleanup.
                 state.publication = Object.freeze({ status: "indeterminate", basename, overwrite });
+                // Linux VFS and rename(2): unsupported flags return EINVAL; ENOSYS
+                // means no syscall. A regular file renamed to a distinct sibling cannot
+                // hit the directory-into-itself EINVAL case. Nothing was published.
+                const unavailable = !overwrite ? noReplaceUnavailable(error, "publication", true) : undefined;
+                if (unavailable && this.#state === state && state.status === "open") {
+                    state.publication = NOT_PUBLISHED;
+                    this.#unsupportedNoReplace = unavailable;
+                    throw unavailable;
+                }
                 // Only explicit pre-dispatch provenance can rule out a committed rename.
                 if (classifyNativeRenameFailure(error) === "uncommitted") {
                     state.publication = NOT_PUBLISHED;
@@ -377,6 +415,11 @@ class NativeStagedFile {
         if (state.publication.status === "indeterminate") {
             outcome = "preserved";
         }
+        else if (this.#fallbackCleanup) {
+            outcome = this.#fallbackCleanup;
+            if (this.#fallbackCleanupError)
+                errors.push(this.#fallbackCleanupError.error);
+        }
         else if (state.publication.status === "not-published" && state.fileFd !== undefined) {
             try {
                 outcome = this.#owner.binding.removeStagedFile(this.#owner.parentFd, this.#owner.name, state.fileFd);

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

@@ -1,3 +1,5 @@
 import type { FileHandle } from "node:fs/promises";
 import type { PinnedWriteInput } from "./pinned-write-types.js";
+/** Replay a consumed stream from an owned, readable stage descriptor. */
+export declare function replayPinnedInput(fd: number, input: PinnedWriteInput): PinnedWriteInput;
 export declare function writePinnedInput(target: FileHandle | number, input: PinnedWriteInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;

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

@@ -1,8 +1,25 @@
+import { readSync } from "node:fs";
 import { types } from "node:util";
 import { snapshotByteView } from "./byte-view.js";
 import { writeCopyFileToFd } from "./copy-file-input.js";
 import { FsSafeError } from "./errors.js";
 import { writeAllToFile } from "./write-file-handle.js";
+/** Replay a consumed stream from an owned, readable stage descriptor. */
+export function replayPinnedInput(fd, input) {
+    if (input.kind !== "stream")
+        return input;
+    return { kind: "stream", stageBeforePublish: true, stream: (async function* () {
+            let position = 0;
+            const buffer = Buffer.alloc(64 * 1024);
+            for (;;) {
+                const bytes = readSync(fd, buffer, 0, buffer.length, position);
+                if (!bytes)
+                    return;
+                position += bytes;
+                yield buffer.subarray(0, bytes);
+            }
+        })() };
+}
 const isUint8Array = types.isUint8Array;
 function streamChunkBytes(chunk) {
     if (Buffer.isBuffer(chunk))

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

@@ -90,7 +90,7 @@ export async function runPinnedWriteHelper(params) {
     }
     const native = getNativeBinding();
     if (native) {
-        return await runPinnedWriteNative(native, normalizedParams);
+        return await runPinnedWriteNative(native, normalizedParams, input => runPinnedWriteFallback({ ...normalizedParams, input }));
     }
     return await runPinnedWriteFallback(normalizedParams);
 }

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

@@ -13,6 +13,9 @@ export type PublishFileExclusiveFailureDetails = {
     targetIdentity?: FileIdentityStat;
     cleanup: PublishFileExclusiveCleanup;
     directorySync?: PublishFileExclusiveDirectorySyncFailure;
+    fallback?: "link-unlink";
+    publication?: "published";
+    sourceRemoval?: "not-attempted" | "still-linked" | "unverified" | "removed";
 };
 export type PublishFailureState = {
     phase: PublishFileExclusiveFailurePhase;
@@ -21,6 +24,8 @@ export type PublishFailureState = {
     targetCleanupIdentity?: FileIdentityStat;
     preserveTarget: boolean;
     directorySync?: PublishFileExclusiveDirectorySyncFailure;
+    fallback?: PublishFileExclusiveFailureDetails["fallback"];
+    sourceRemoval?: PublishFileExclusiveFailureDetails["sourceRemoval"];
 };
 export declare function rememberCreatedTarget(state: PublishFailureState, identity: FileIdentityStat, phase: PublishFileExclusiveFailurePhase): void;
 export declare function publicationFailure(error: unknown, state: PublishFailureState, cleanup: PublishFileExclusiveCleanup): FsSafeError;

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

@@ -12,6 +12,7 @@ export function publicationFailure(error, state, cleanup) {
         targetCreated: state.targetCreated,
         ...(state.targetIdentity ? { targetIdentity: state.targetIdentity } : {}),
         ...(state.directorySync ? { directorySync: state.directorySync } : {}),
+        ...(state.fallback ? { fallback: state.fallback, publication: "published", sourceRemoval: state.sourceRemoval } : {}),
         cleanup,
     };
     return new FsSafeError(error instanceof FsSafeError ? error.code : "helper-failed", `exclusive file publication failed during ${state.phase}: ${cause.message}`, { cause, details });

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

@@ -0,0 +1,4 @@
+import type { BigIntStats } from "node:fs";
+import type { NativeBinding } from "./native-binding.js";
+import { type PublishFailureState } from "./publish-file-failure.js";
+export declare function publishFileNoReplaceNative(binding: NativeBinding, paths: Parameters<NativeBinding["renameNoReplace"]>, expected: BigIntStats, failure: PublishFailureState): "link-unlink" | undefined;

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

@@ -0,0 +1,35 @@
+import { FsSafeError } from "./errors.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { nativeMoveNoReplace } from "./native-move-fallback.js";
+import { rememberCreatedTarget } from "./publish-file-failure.js";
+export function publishFileNoReplaceNative(binding, paths, expected, failure) {
+    try {
+        const fallback = nativeMoveNoReplace(binding, paths, expected, getFsSafeNativeConfig().mode === "auto", "file publication");
+        if (fallback) {
+            failure.fallback = fallback;
+            failure.sourceRemoval = "removed";
+        }
+        return fallback;
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.details?.publication === "published") {
+            failure.targetCreated = true;
+            failure.preserveTarget = true;
+            failure.phase = "rename-verify";
+            failure.fallback = "link-unlink";
+            failure.sourceRemoval = error.details.sourceRemoval;
+            // Changed/unverified pairs cannot establish which inode was published.
+            if (failure.sourceRemoval === "still-linked")
+                rememberCreatedTarget(failure, expected, "rename-verify");
+        }
+        if (error instanceof FsSafeError)
+            throw error;
+        const code = error?.code;
+        if (code === "path-mismatch" || code === "hardlink") {
+            throw new FsSafeError(code, "publication source changed before fallback", { cause: error });
+        }
+        if (code === "ELOOP")
+            throw new FsSafeError("symlink", "publication source became a symlink", { cause: error });
+        throw error;
+    }
+}

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

@@ -5,6 +5,8 @@ import { type PublishFileExclusiveSyncFailurePolicy } from "./publish-file-failu
 export type PublishFileExclusiveStrategy = "link-or-copy" | "link-required" | "rename-noreplace";
 export type PublishFileExclusiveResult = {
     method: "hardlink" | "exclusive-copy" | "rename-noreplace";
+    /** Linux auto fallback; exclusive and identity-checked, but not crash-atomic. */
+    fallback?: "link-unlink";
     identity: Stats;
     directorySync: DirectorySyncOutcome;
 };

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

@@ -1,3 +1,4 @@
+import { publishFileNoReplaceNative } from "./publish-file-native.js";
 import { createHash } from "node:crypto";
 import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
@@ -256,7 +257,7 @@ export async function publishFileExclusive(params) {
             else
                 assertSourceCurrent();
             assertPublishedTargetCurrent(targetPath, identity, "publication target changed during directory sync");
-            return { method, identity: fsSync.fstatSync(handle.fd), directorySync };
+            return { method, ...(failure.fallback ? { fallback: failure.fallback } : {}), identity: fsSync.fstatSync(handle.fd), directorySync };
         };
         await parent.assertCurrent();
         assertSourceCurrent();
@@ -269,7 +270,12 @@ export async function publishFileExclusive(params) {
         }
         if (strategy === "rename-noreplace") {
             const binding = requireNativeBinding();
-            binding.renameNoReplace(sourceNativeParent.handle.fd, sourceNativeParent.basename, targetNativeParent.handle.fd, targetNativeParent.basename);
+            publishFileNoReplaceNative(binding, [
+                sourceNativeParent.handle.fd,
+                sourceNativeParent.basename,
+                targetNativeParent.handle.fd,
+                targetNativeParent.basename,
+            ], sourceExactIdentity, failure);
             rememberCreatedTarget(failure, sourceExactIdentity, "rename-verify");
             // A failed post-rename fence must not delete the only remaining name.
             failure.preserveTarget = true;

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

@@ -1,3 +1,4 @@
+import { noReplaceUnavailable } from "./native-noreplace.js";
 import { randomUUID } from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
@@ -19,7 +20,8 @@ function assertGuardsCurrent(guards) {
 }
 function replacementFailure(error, message, details, cause = error) {
     if (error instanceof FsSafeError) {
-        return new FsSafeError(error.code, message, { cause, details });
+        const code = error.code;
+        return new FsSafeError(code, code === "helper-unavailable" ? `${message}: ${error.message}` : message, { cause, details });
     }
     const failure = new Error(message, { cause });
     copyOperationalCode(failure, error);
@@ -46,14 +48,13 @@ function observeOptionalDirectory(pathname) {
     return inspectDirectoryIdentitySync(pathname, undefined, initial);
 }
 function normalizeNativeRenameFailure(error) {
+    const unavailable = noReplaceUnavailable(error, "directory rename", true);
+    if (unavailable)
+        return unavailable;
     const code = error?.code;
     if (code === NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH) {
         return new FsSafeError("path-mismatch", "directory replacement source identity changed before native rename", { cause: error });
     }
-    if (code === "EINVAL" || code === "ENOSYS" || code === "ENOTSUP" ||
-        code === "EOPNOTSUPP") {
-        return new FsSafeError("helper-unavailable", "native no-replace directory rename is unavailable on this filesystem", { cause: error });
-    }
     return error;
 }
 function renameRetainedDirectory(params) {

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

@@ -29,7 +29,7 @@ export function hardlinkedPathNotAllowedError() {
 export function isAlreadyExistsError(error) {
     return hasNodeErrorCode(error, "EEXIST") || /File exists|EEXIST/i.test(String(error));
 }
-function descriptorExhaustion(error) {
+function resourceExhaustion(error) {
     const pending = [error];
     let details;
     let code;
@@ -45,7 +45,11 @@ function descriptorExhaustion(error) {
         const diagnostic = current;
         if (current instanceof FsSafeError && (!details || current.details?.cleanup))
             details = current.details ?? details;
-        if (diagnostic.code === "EMFILE" || diagnostic.code === "ENFILE")
+        if (diagnostic.code === "EMFILE" || diagnostic.code === "ENFILE") {
+            if (!code || code === "ENOSPC")
+                code = diagnostic.code;
+        }
+        else if (diagnostic.code === "ENOSPC")
             code ??= diagnostic.code;
         if (diagnostic.name === "SuppressedError")
             pending.push(diagnostic.suppressed, diagnostic.error);
@@ -55,15 +59,32 @@ function descriptorExhaustion(error) {
     }
     if (!code)
         return;
+    // Disk-space diagnostics retain the published direct-write code and already-classified errors.
+    if (code === "ENOSPC" && error instanceof FsSafeError)
+        return;
     const cleanup = details?.cleanup;
     const publication = details?.publication;
     const preserved = cleanup?.status === "preserved" && publication?.status === "indeterminate";
-    return new FsSafeError("helper-failed", `filesystem write failed: too many open files (${code})${preserved ? "; publication outcome is indeterminate; staged file preserved" : ""}`, { cause: error, details });
+    const message = code === "ENOSPC" ? PINNED_WRITE_ERRNO_MESSAGES.get(code) : "filesystem write failed: too many open files";
+    return new FsSafeError(code === "ENOSPC" ? "invalid-path" : "helper-failed", `${message} (${code})${preserved ? "; publication outcome is indeterminate; staged file preserved" : ""}`, { cause: error, details });
 }
 export function normalizePinnedWriteError(error) {
-    const exhausted = descriptorExhaustion(error);
+    const exhausted = resourceExhaustion(error);
     if (exhausted)
         return exhausted;
+    // Disposal retains cleanup evidence, but the failed publication remains primary.
+    let primary = error;
+    const seen = new Set();
+    try {
+        while (primary instanceof Error && primary.name === "SuppressedError" && !seen.has(primary)) {
+            seen.add(primary);
+            primary = primary.suppressed;
+        }
+        if (primary !== error && primary instanceof FsSafeError && primary.details?.phase === "publish") {
+            return new FsSafeError(primary.code, primary.message, { cause: error, details: primary.details });
+        }
+    }
+    catch { /* Unreadable diagnostics retain the original failure. */ }
     if (error instanceof FsSafeError) {
         return error;
     }

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

@@ -1167,10 +1167,10 @@ async function movePathFallback(root, params) {
     let sourceIdentity;
     try {
         if (params.overwrite && params.assertBeforeMutation) {
-            sourceIdentity = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true }), true));
+            sourceIdentity = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true })));
         }
         else {
-            admitMoveSourceStat(fsSync.lstatSync(source.resolved), params.overwrite);
+            admitMoveSourceStat(fsSync.lstatSync(source.resolved));
         }
     }
     catch (error) {
@@ -1234,7 +1234,7 @@ async function movePathFallback(root, params) {
                     }
                 }
             }
-            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true }), true), sourceIdentity);
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true })), sourceIdentity);
         }
         await fs.rename(source.resolved, target.resolved);
     }

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

@@ -1,8 +1,10 @@
 import { type BigIntStats, type Stats } from "node:fs";
 import type { RootMoveOptions } from "./root-options.js";
 import { type RootContext } from "./root-context.js";
-export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
-export declare function movePathNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">, paths: {
+export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T): T;
+export declare function movePathNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+    requireNative: boolean;
+}, paths: {
     sourcePath: string;
     sourceParentPath: string;
     targetPath: string;

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

@@ -15,6 +15,7 @@ import { PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+import { nativeMoveNoReplace } from "./native-move-fallback.js";
 function nativeParentRelativePath(rootReal, parentPath) {
     const relative = path.relative(rootReal, parentPath);
     if (relative === "" || relative === ".")
@@ -57,22 +58,13 @@ function normalizeMoveError(error) {
     }
     return error;
 }
-function normalizeRenameNoReplaceError(error) {
-    if (error?.code === "EINVAL") {
-        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", errorCauseOptions(error));
-    }
-    return normalizeMoveError(error);
-}
-export function admitMoveSourceStat(stat, overwrite = false) {
+export function admitMoveSourceStat(stat) {
     if (stat.isSymbolicLink()) {
         throw new FsSafeError("symlink", "symlink not allowed");
     }
     if (stat.isFile() && stat.nlink > 1) {
         throw hardlinkedPathNotAllowedError();
     }
-    if (!overwrite && stat.isDirectory()) {
-        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
-    }
     return stat;
 }
 export async function movePathNative(root, params, paths, overwrite = false) {
@@ -124,10 +116,9 @@ export async function movePathNative(root, params, paths, overwrite = false) {
         await assertRootIdentityCurrent(root);
         for (const admission of parentAdmissions)
             assertSyncDirectoryGuard(admission.guard);
-        // Overwrite publication always binds an exact source; no-clobber retains
-        // its existing callback-dependent identity contract.
-        const sourceStat = overwrite || params.assertBeforeMutation
-            ? inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true }), overwrite), paths.expectedSourceIdentity)
+        // Linux auto fallback needs an exact source even without an authority callback.
+        const sourceStat = overwrite || params.assertBeforeMutation || (process.platform === "linux" && !params.requireNative)
+            ? inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })), paths.expectedSourceIdentity)
             : undefined;
         if (!sourceStat)
             admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath));
@@ -172,20 +163,25 @@ export async function movePathNative(root, params, paths, overwrite = false) {
             }
         }
         if (sourceStat !== undefined) {
-            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true }), overwrite), sourceStat);
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })), sourceStat);
         }
         try {
             assertFinalSymlinkRejected(admittedTargetPath, params.mutationSymlinks !== undefined);
             if (overwrite)
                 binding.renameReplaceWithIdentity(sourceParent.fd, path.basename(paths.sourcePath), targetParent.fd, path.basename(paths.targetPath), sourceStat.dev, sourceStat.ino);
             else
-                binding.renameNoReplace(sourceParent.fd, path.basename(paths.sourcePath), targetParent.fd, path.basename(paths.targetPath));
+                nativeMoveNoReplace(binding, [
+                    sourceParent.fd,
+                    path.basename(paths.sourcePath),
+                    targetParent.fd,
+                    path.basename(paths.targetPath),
+                ], sourceStat, !params.requireNative);
         }
         catch (error) {
             if (isAlreadyExistsError(error) || (!overwrite && error?.code === "ENOTEMPTY")) {
                 throw new FsSafeError("already-exists", "destination exists", errorCauseOptions(error));
             }
-            throw overwrite ? normalizeMoveError(error) : normalizeRenameNoReplaceError(error);
+            throw normalizeMoveError(error);
         }
         try {
             for (const admission of parentAdmissions)

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

@@ -8,6 +8,8 @@ import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { isWindowsReservedDeviceName } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
+import { isFsSafeNativeRequired } from "./native-config.js";
+import { cachedNoReplaceDevice, isNoReplaceUnavailable } from "./native-noreplace.js";
 import { handoffPrivateProducerFile, } from "./private-producer-handoff.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { rootFromDirectoryGuard } from "./root-impl.js";
@@ -109,8 +111,18 @@ async function writeIsolatedProducer(params) {
         const result = await Reflect.apply(write, writeReceiver, [producerPath]);
         assertCurrent();
         if (native) {
-            await targetRoot.move(path.relative(targetRoot.rootReal, producerPath), path.basename(tempPath), { assertBeforeMutation: assertCurrent });
-            return { cleanupWorkspace, result };
+            try {
+                const cached = cachedNoReplaceDevice(native, parentGuard.stat.dev, "producer handoff");
+                if (cached)
+                    throw cached;
+                await targetRoot.move(path.relative(targetRoot.rootReal, producerPath), path.basename(tempPath), { assertBeforeMutation: assertCurrent });
+                return { cleanupWorkspace, result };
+            }
+            catch (error) {
+                if (isFsSafeNativeRequired() || !isNoReplaceUnavailable(error))
+                    throw error;
+                assertCurrent();
+            }
         }
         const handoff = await handoffPrivateProducerFile({
             sourcePath: producerPath,
@@ -126,7 +138,10 @@ async function writeIsolatedProducer(params) {
             await cleanupWorkspace();
         }
         catch (cleanupError) {
-            throw new AggregateError([error, cleanupError], "isolated producer operation and workspace cleanup failed");
+            const combined = new AggregateError([error, cleanupError], "isolated producer operation and workspace cleanup failed");
+            if (isNoReplaceUnavailable(error))
+                throw new FsSafeError(error.code, error.message, { cause: combined });
+            throw combined;
         }
         throw error;
     }

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

@@ -1,4 +1,5 @@
 import { FsSafeError } from "./errors.js";
+import { noReplaceUnavailable } from "./native-noreplace.js";
 export function createStagedFileReceipt(directory, temporaryBasename, stat) {
     return Object.freeze({
         directory,
@@ -11,6 +12,7 @@ export function createStagedFileReceipt(directory, temporaryBasename, stat) {
     });
 }
 export function stagedFailure(kind, error, details) {
+    error = noReplaceUnavailable(error, `${kind} publication`) ?? error;
     let code = "helper-failed";
     try {
         code = error instanceof FsSafeError ? error.code
@@ -19,7 +21,8 @@ export function stagedFailure(kind, error, details) {
     catch {
         // Uninspectable error metadata must not interrupt terminal settlement.
     }
-    return new FsSafeError(code, `staged ${kind} ${details.phase} failed`, { cause: error, details });
+    return new FsSafeError(code, code === "helper-unavailable" && error instanceof FsSafeError
+        ? error.message : `staged ${kind} ${details.phase} failed`, { cause: error, details });
 }
 /** Finish owned cleanup and every close before surfacing publication evidence. */
 export async function settleStagedFile(params) {

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-owner.d.ts

@@ -9,6 +9,7 @@ export declare class TempWorkspaceCleanupCapability {
     readonly parent: RetainedDirectory | undefined;
     constructor(root: string, safety: TempWorkspaceCleanupSafety, admission: TempWorkspaceRootAdmission, dirMode: number);
     get canRemoveOwnedTree(): boolean;
+    get canUseCompatibleCleanup(): boolean;
     prepareChildCreation(): void;
     admitChildDescriptor(canEnumerate: boolean): boolean;
     assertCurrent(): void;

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-owner.js

@@ -8,6 +8,8 @@ import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { openTempWorkspaceCleanupParent, TempWorkspaceRetainedChild, } from "./temp-workspace-descriptor.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+import { isFsSafeNativeRequired } from "./native-config.js";
+import { cachedNoReplaceUnavailable, noReplaceUnavailable, rememberNoReplaceUnavailable } from "./native-noreplace.js";
 function isNativeCleanupBinding(binding) {
     return typeof binding?.renameNoReplace === "function" &&
         typeof binding.removeOwnedTree === "function" &&
@@ -94,6 +96,9 @@ export class TempWorkspaceCleanupCapability {
         return (this.#phase === "ready" || this.#phase === "sealed") &&
             this.#ownedTreeRemovalAvailable;
     }
+    get canUseCompatibleCleanup() {
+        return this.#safety === "compatible" && !isFsSafeNativeRequired();
+    }
     prepareChildCreation() {
         const replay = this.#phase === "ready";
         if (this.#phase !== "new" && !replay) {
@@ -269,11 +274,27 @@ export class TempWorkspaceCleanupOwner {
             }
             const name = `.fs-safe-workspace-cleanup-${randomUUID()}`;
             const quarantinePath = path.join(parent.receipt.path, name);
-            const nativeRemoval = this.#capability.canRemoveOwnedTree && this.#directory !== undefined;
+            let nativeRemoval = this.#capability.canRemoveOwnedTree && this.#directory !== undefined;
             if (nativeRemoval) {
-                this.#capability.binding.renameNoReplace(parent.fd, path.basename(this.#dir), parent.fd, name);
+                const binding = this.#capability.binding;
+                try {
+                    const cached = cachedNoReplaceUnavailable(binding, parent.fd, "workspace quarantine");
+                    if (cached)
+                        throw cached;
+                    binding.renameNoReplace(parent.fd, path.basename(this.#dir), parent.fd, name);
+                }
+                catch (error) {
+                    const unavailable = error instanceof FsSafeError && error.code === "helper-unavailable"
+                        ? error : noReplaceUnavailable(error, "workspace quarantine", true);
+                    if (!unavailable)
+                        throw error;
+                    rememberNoReplaceUnavailable(binding, parent.fd, unavailable);
+                    if (!this.#capability.canUseCompatibleCleanup)
+                        throw unavailable;
+                    nativeRemoval = false;
+                }
             }
-            else {
+            if (!nativeRemoval) {
                 // The admitted receipt is exact and descriptor-associated. Reuse it as
                 // the pre/post parent fence instead of layering a numeric guard over it.
                 this.#capability.assertCurrent();
@@ -288,7 +309,9 @@ export class TempWorkspaceCleanupOwner {
             }
             return { name, path: quarantinePath, nativeRemoval };
         }
-        catch {
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "helper-unavailable")
+                throw error;
             // A failed rename can still have committed on a remote filesystem.
             return "indeterminate";
         }

package/node_modules/@openclaw/fs-safe/docs/advanced.md

@@ -82,6 +82,7 @@ concurrent namespace changes.
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `retainEntryForPublication`, `RetainedEntryPublication`, `RetainEntryForPublicationOptions`, `EntryPublicationReceipt`, `EntryPublicationResult`, `EntryPublicationIssue`, `PublicationIdentity`, `PublicationParent` | [One-way entry publication](entry-publication.md) | Native no-replace directory/regular-file/symlink export, including Windows NTFS junctions, under caller-exclusive namespace; explicit transition receipts, close-only disposal, no source CAS. |
 | `retainFileInDirectory`, `RetainedFile`, related receipt/result types | [Retained Windows files](retained-file.md) | Existing-file native handle custody and explicit removal; local NTFS, producer authority required, no persistence guarantee. |
+| `copyRootFileSync`, `CopyRootFileSyncOptions`, `CopiedRootFileSync` | [copy.md](copy.md#synchronous-guarded-file-copies) | Synchronous guarded exclusive file copy, optionally cloned and bound to an expected source identity, returning an owned destination descriptor and both identities. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |

package/node_modules/@openclaw/fs-safe/docs/archive.md

@@ -179,7 +179,8 @@ between native and JavaScript paths rather than reimplementing it in Rust.
 
 ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless internal separator and dot-component equivalence is allowed only after validation; every raw and Unicode interpretation must also agree on whether its name ends in `/` or `\`. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
 
-ZIP preflight and bounded reads apply extraction's case-insensitive NFC collision
+ZIP preflight and bounded reads use extraction's canonical path identity, including
+removing directory trailing separators, and apply its case-insensitive NFC collision
 policy to the complete archive, including entries that extraction would strip
 or skip. Known UTF-8 and Unicode Path names are checked during physical admission;
 legacy names retain backend-selected decoding and undergo the same collision