@openclaw/signal 2026.11.3 → 2026.11.5-beta.2

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

@@ -6,6 +6,7 @@ import { createFileHandle } from "./create.js";
 import { hasPreservedCreationArtifacts } from "./creation-boundary.js";
 import { assertSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { annotateReadOnlyOpenError } from "./file-open-error.js";
 import { nativeOpenFlags, removeNativeCreatedFileIfStillPinned, } from "./native-operations.js";
 import { writePinnedInput } from "./pinned-write-input.js";
 import { assertNativeCopyCompleted, createNativeCopyFile } from "./copy-file-input.js";
@@ -83,7 +84,7 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
         tempName = `.fs-safe-${randomUUID()}.tmp`;
         params.assertBeforeMutation?.();
         const copied = params.input.kind === "file" && !params.private
-            ? await createNativeCopyFile(binding, params.input, parentFd, tempName, params.maxBytes)
+            ? await createNativeCopyFile(binding, params.input, parentFd, tempName, params.maxBytes, path.join(parentPath, tempName))
             : undefined;
         if (params.private) {
             const parentIdentity = fsSync.fstatSync(parentFd, { bigint: true });
@@ -102,7 +103,13 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
             tempFd = copied.fd;
         }
         else {
-            tempFd = binding.openBeneath(parentFd, tempName, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL)).fd;
+            try {
+                tempFd = binding.openBeneath(parentFd, tempName, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL)).fd;
+            }
+            catch (error) {
+                annotateReadOnlyOpenError(error, path.join(parentPath, tempName));
+                throw error;
+            }
         }
         const verificationIdentity = inspectFileIdentitySync(() => fsSync.fstatSync(tempFd, { bigint: true }));
         tempIdentity = verificationIdentity;

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

@@ -52,7 +52,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 });
 import { assertDarwinCreationAcl, assertPrivateCreationFile } from "./creation-boundary.js";
 import { requireNativeBinding } from "./native.js";
-import { syncFileBestEffortSync } from "./file-sync.js";
+import { syncFile, syncFileBestEffort } from "./file-sync.js";
 import { randomUUID } from "node:crypto";
 import fs, {} from "node:fs";
 import path from "node:path";
@@ -69,6 +69,7 @@ import { createStagedFileReceipt, stagedFailure } from "./staged-file-settlement
 import { noReplaceUnavailable, rememberNoReplaceUnavailable } from "./native-noreplace.js";
 import { isFsSafeNativeRequired } from "./native-config.js";
 import { restoreCopyMetadata } from "./copy-metadata.js";
+import { annotateReadOnlyOpenError } from "./file-open-error.js";
 export function assertNativeStaging(binding) {
     if ([
         binding.closeOwnedFd,
@@ -96,6 +97,7 @@ class NativeStagedFile {
     #verifyMode;
     #state = { status: "open", publication: NOT_PUBLISHED };
     #receipt;
+    #publicationFlush;
     #rejectFinalSymlink = false;
     #unsupportedNoReplace;
     #fallbackCleanup;
@@ -132,8 +134,7 @@ class NativeStagedFile {
         const env_1 = { stack: [], error: void 0, hasError: false };
         try {
             const exclusive = params.overwrite === false && params.input.kind === "buffer" && params.input.stageBeforePublish === false;
-            // This owner never escapes. Only the internal verifier borrows its fd;
-            // public descriptor methods remain await-free and cannot race disposal.
+            // This owner never escapes; only the internal verifier borrows its fd.
             const staged = __addDisposableResource(env_1, await NativeStagedFile.create({
                 binding, parentFd, closeParentFd, directory, mode: params.mode, sync: params.sync,
                 // Public staging uses portable names; existing POSIX writes accept literal names.
@@ -152,9 +153,10 @@ class NativeStagedFile {
             }
             let published;
             try {
-                published = exclusive
+                const publication = exclusive
                     ? staged.#completePublication(params.basename, false, params.onPublished)
-                    : await staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
+                    : staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
+                published = publication instanceof Promise ? await publication : publication;
             }
             catch (error) {
                 if (!staged.#unsupportedNoReplace || isFsSafeNativeRequired() ||
@@ -278,14 +280,20 @@ class NativeStagedFile {
                 assertDarwinCreationAcl(this.#owner.parentFd, "file");
             // Native copying populates its new file before returning its descriptor.
             const copied = input.kind === "file" && !this.#verifyMode
-                ? await createNativeCopyFile(this.#owner.binding, input, this.#owner.parentFd, this.#owner.name, maxBytes)
+                ? await createNativeCopyFile(this.#owner.binding, input, this.#owner.parentFd, this.#owner.name, maxBytes, path.join(this.#owner.directory.realPath, this.#owner.name))
                 : undefined;
             state.fileFd = copied?.fd;
             if (state.fileFd === undefined) {
                 this.#assertBeforeMutation?.();
                 if (this.#private)
                     assertDarwinCreationAcl(this.#owner.parentFd, "file");
-                state.fileFd = this.#owner.binding.createStagedFile(this.#owner.parentFd, this.#owner.name);
+                try {
+                    state.fileFd = this.#owner.binding.createStagedFile(this.#owner.parentFd, this.#owner.name);
+                }
+                catch (error) {
+                    annotateReadOnlyOpenError(error, path.join(this.#owner.directory.realPath, this.#owner.name));
+                    throw error;
+                }
             }
             const fd = state.fileFd;
             if (input.kind === "file")
@@ -311,29 +319,21 @@ class NativeStagedFile {
                 restoreCopyMetadata(fd, input.metadata);
             if (this.#verifyMode)
                 this.#assertStagePermissions(fd);
-            if (this.#owner.sync !== false) {
-                if (this.#owner.strictFileSync)
-                    fs.fsyncSync(fd);
-                else
-                    syncFileBestEffortSync(fd);
-            }
+            if (this.#owner.sync !== false)
+                await (this.#owner.strictFileSync ? syncFile(fd) : syncFileBestEffort(fd));
             const stat = fs.fstatSync(fd, { bigint: true });
             this.#receipt = createStagedFileReceipt(this.#owner.directory, this.#owner.name, stat);
             this.#assertCurrent();
         }
         catch (error) {
             const { receipt: cleanup, error: cleanupError } = this.#finalize();
-            if (cleanupError) {
-                throw stagedFailure("file", new AggregateError([error, cleanupError], "preparation and cleanup failed"), { phase: "prepare", publication: cleanup.publication, cleanup });
-            }
-            if (cleanup.status === "preserved") {
-                throw stagedFailure("file", error, { phase: "prepare", publication: cleanup.publication, cleanup });
+            if (cleanupError || cleanup.status === "preserved") {
+                throw stagedFailure("file", cleanupError
+                    ? new AggregateError([error, cleanupError], "preparation and cleanup failed") : error, { phase: "prepare", publication: cleanup.publication, cleanup });
             }
             throw error;
         }
     }
-    // Keep public descriptor work await-free: each call completes its mutations
-    // before the next invocation, including closure and cached cleanup failures.
     async assertCurrent() {
         this.#assertCurrent();
     }
@@ -378,7 +378,8 @@ class NativeStagedFile {
                 }
                 throw error;
             }
-            return this.#completePublication(basename, overwrite, onPublished);
+            const publication = this.#completePublication(basename, overwrite, onPublished);
+            return publication instanceof Promise ? await publication : publication;
         }
         catch (error) {
             if (isMutationAuthorityError(error))
@@ -404,17 +405,21 @@ class NativeStagedFile {
             fs.fchmodSync(fd, this.#owner.mode);
         // Content was synced during preparation. A lost chmod leaves 0600, no wider
         // than modes retaining owner rw; restrictive modes still need a durable correction.
-        if (this.#owner.sync !== false && ((this.#owner.mode & 0o600) !== 0o600 || (stagedMode & ~this.#owner.mode) !== 0)) {
-            if (this.#owner.strictFileSync)
-                fs.fsyncSync(fd);
-            else
-                syncFileBestEffortSync(fd);
-        }
-        if (this.#owner.sync !== false)
-            syncFileBestEffortSync(this.#owner.parentFd);
-        this.#assertNamed(basename, this.#owner.mode);
-        this.#assertDirectory();
-        return receipt;
+        const verify = () => {
+            this.#assertNamed(basename, this.#owner.mode);
+            this.#assertDirectory();
+            return receipt;
+        };
+        if (this.#owner.sync === false)
+            return verify();
+        this.#publicationFlush = Promise.resolve().then(async () => {
+            if ((this.#owner.mode & 0o600) !== 0o600 || (stagedMode & ~this.#owner.mode) !== 0) {
+                await (this.#owner.strictFileSync ? syncFile(fd) : syncFileBestEffort(fd));
+            }
+            await syncFileBestEffort(this.#owner.parentFd);
+            return verify();
+        }).finally(() => { this.#publicationFlush = undefined; });
+        return this.#publicationFlush;
     }
     #finalize() {
         if (this.#state.status === "closed") {
@@ -469,6 +474,9 @@ class NativeStagedFile {
         return this.#state;
     }
     async cleanup() {
+        // Native descriptors cannot close or be recycled while libuv is synchronizing them.
+        if (this.#publicationFlush)
+            await this.#publicationFlush.catch(() => { });
         const closed = this.#finalize();
         if (closed.error) {
             throw closed.error;

package/node_modules/@openclaw/fs-safe/dist/output.js

@@ -8,6 +8,7 @@ import { isPathInside } from "./path.js";
 import { root } from "./root.js";
 import { tempFile } from "./temp-target.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { createAsyncDirectoryGuard } from "./directory-guard.js";
 const NON_PORTABLE_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/u;
 function tempFileNameForTarget(targetPath, fallbackFileName) {
     const fallback = sanitizeUntrustedFileName(fallbackFileName ?? "output.bin", "output.bin");
@@ -62,6 +63,9 @@ export async function writeExternalFileWithinRoot(options) {
     const staging = options.staging;
     const fallbackFileName = options.fallbackFileName;
     const targetRoot = await root(rootDir);
+    const rootBoundary = staging === "sibling"
+        ? await createAsyncDirectoryGuard(targetRoot.rootReal, { bigint: true })
+        : undefined;
     if (requestedTargetPath.length === 0) {
         throw new FsSafeError("invalid-path", "target path is required");
     }
@@ -84,6 +88,7 @@ export async function writeExternalFileWithinRoot(options) {
         const siblingFinalPath = await targetRoot.resolve(targetPath);
         const result = await writeExternalFileViaSibling({
             finalPath: siblingFinalPath,
+            rootBoundary,
             write,
             producerIsolation,
             fallbackFileName,
@@ -126,6 +131,7 @@ async function writeExternalFileViaSibling(params) {
     assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const { result } = await writeCallbackSibling({
         tempDir: path.dirname(finalPath),
+        rootBoundary: params.rootBoundary,
         tempName: buildSiblingTempName(finalPath, params.fallbackFileName),
         write: params.write,
         producerIsolation: params.producerIsolation,

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

@@ -21,6 +21,8 @@ export type OwnerAndDaclResult = {
     currentUserSid: string;
     daclPresent: boolean;
     isLocal: boolean;
+    /** Verified local volume root with a matching non-reparse entry; omitted by older helpers. */
+    isVolumeRoot?: boolean;
     complete: boolean;
     unsupportedAceTypes: number[];
     aces: WindowsAccessControlEntry[];

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

@@ -27,6 +27,7 @@ export function projectOwnerAndDacl(facts) {
         currentUserSid: facts.currentUserSid,
         daclPresent: facts.daclPresent,
         isLocal: facts.isLocal,
+        ...(facts.isVolumeRoot === undefined ? {} : { isVolumeRoot: facts.isVolumeRoot }),
         complete: facts.aceListComplete,
         unsupportedAceTypes: [...facts.unsupportedAceTypes],
         aces: facts.aces.map((entry) => ({

package/node_modules/@openclaw/fs-safe/dist/path.js

@@ -115,7 +115,11 @@ export function safeRealpathSync(targetPath, cache) {
         return cached;
     }
     try {
-        const resolved = realpathSync(pathForWindowsFilesystem(targetPath));
+        const ordinary = realpathSync(pathForWindowsFilesystem(targetPath));
+        // Ordinary resolution keeps the caller's letter case. Its result has no symlinks or
+        // dot segments left, so native resolution on POSIX only adopts the on-disk spelling
+        // that root admission compares against. Windows root admission reconciles aliases.
+        const resolved = process.platform === "win32" ? ordinary : realpathSync.native(ordinary);
         cache?.set(targetPath, resolved);
         cache?.set(resolved, resolved);
         return resolved;

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

@@ -14,6 +14,7 @@ import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { writePinnedInput } from "./pinned-write-input.js";
 import { assertPinnedWriteMode, pinnedWriteModeAssertion, preparePinnedWriteMode } from "./pinned-write-mode.js";
 import { publishCopyStage } from "./publish-copy-stage.js";
+import { openPublicationHandle } from "./publication-handle.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
@@ -35,6 +36,7 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
     let handle;
     let tempIdentity;
     let readHandle;
+    let handoffCloseFailure;
     let renamed = false;
     const completeCreate = params.overwrite === false && params.input.kind !== "file" && params.input.stageBeforePublish === true;
     let receipt;
@@ -89,11 +91,15 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
             }), path.basename(tempPath), fsSync.fstatSync(handle.fd, { bigint: true }));
         }
         let verifiedIdentity = expectedTempStat;
+        // Keep unreadable modes supported where Node has no read-free file open.
+        const canHandoff = process.platform !== "win32" &&
+            ((params.mode & 0o400) !== 0 ||
+                (process.platform === "linux" && (process.arch === "x64" || process.arch === "arm64")));
         phase = "publish";
         await withAsyncDirectoryGuards([parentGuard], async () => {
             assertFinalSymlinkRejected(targetPath, params.rejectFinalSymlink);
             if (params.overwrite === false) {
-                publishCopyStage({
+                await publishCopyStage({
                     temporaryPath: tempPath, targetPath, fd: handle.fd,
                     identity: tempIdentity, parentGuard,
                     assertBeforeMutation,
@@ -107,6 +113,18 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
                             publication = Object.freeze({ status: "published", staged: receipt, basename: params.basename, overwrite: false });
                         params.onPublished?.(identity);
                     },
+                    beforeTemporaryUnlink: !canHandoff ? undefined : async () => {
+                        readHandle = await openPublicationHandle(targetPath, expectedTempStat);
+                        // Keep the destination pinned while closing the stage's NFS dentry.
+                        const stagedHandle = handle;
+                        handle = undefined;
+                        try {
+                            await stagedHandle.close();
+                        }
+                        catch (error) {
+                            handoffCloseFailure = { error };
+                        }
+                    },
                 });
             }
             else {
@@ -134,6 +152,7 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
                     throw new FsSafeError("path-mismatch", "fallback target changed during write");
                 }
                 const expectedHash = sha256Hex(params.input.data, params.input.encoding);
+                await readHandle?.close();
                 readHandle = await fs.open(targetPath, resolveReadOpenFlags());
                 const readHandleStat = fsSync.fstatSync(readHandle.fd, { bigint: true });
                 const actualHash = sha256Hex(await readFileHandleBounded(readHandle, Infinity));
@@ -172,7 +191,11 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
                         pathname: tempPath, handle, identity: tempIdentity, parentGuard, throwOnCleanupError: true,
                     }) : "not-needed";
                 },
-                close: [async () => { await readHandle?.close(); }, async () => { await handle?.close(); }],
+                close: [async () => { await readHandle?.close(); }, async () => {
+                        await handle?.close();
+                        if (handoffCloseFailure)
+                            throw handoffCloseFailure.error;
+                    }],
             });
         }
         else

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

@@ -0,0 +1,4 @@
+import { type BigIntStats } from "node:fs";
+import fs from "node:fs/promises";
+/** Pin the published name before releasing a descriptor opened through its stage. */
+export declare function openPublicationHandle(targetPath: string, identity: BigIntStats): Promise<fs.FileHandle>;

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

@@ -0,0 +1,32 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { hasErrorCode } from "./file-cleanup.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+/** Pin the published name before releasing a descriptor opened through its stage. */
+export async function openPublicationHandle(targetPath, identity) {
+    const flags = resolveReadOpenFlags();
+    const handle = await fs.open(targetPath, flags).catch(async (error) => {
+        // Restrictive final modes must not be widened just to inspect publication.
+        if (!hasErrorCode(error, "EACCES") || (process.arch !== "x64" && process.arch !== "arm64"))
+            throw error;
+        const metadataFlag = process.platform === "linux" ? 0x200000 : undefined; // O_PATH
+        if (metadataFlag === undefined)
+            throw error;
+        return fs.open(targetPath, metadataFlag | fsSync.constants.O_NOFOLLOW);
+    });
+    try {
+        const opened = fsSync.fstatSync(handle.fd, { bigint: true });
+        const named = fsSync.lstatSync(targetPath, { bigint: true });
+        if (!opened.isFile() || !named.isFile() || named.isSymbolicLink() ||
+            !sameFileIdentityForCleanup(opened, identity) || !sameFileIdentityForCleanup(named, identity)) {
+            throw new FsSafeError("path-mismatch", "publication descriptor handoff identity changed");
+        }
+        return handle;
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}

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

@@ -10,4 +10,5 @@ export declare function publishCopyStage(params: {
     assertBeforeMutation?: () => void;
     onPublicationAttempt?: () => void;
     onPublished?: (identity: PublishedWriteIdentity) => void;
-}): void;
+    beforeTemporaryUnlink?: () => Promise<void>;
+}): Promise<void>;

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

@@ -7,8 +7,8 @@ import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { hasErrorCode } from "./file-cleanup.js";
 import { isHardlinkFallbackError } from "./hardlink-fallback.js";
 // Node has no portable no-replace rename. Publish the completed stage by link,
-// then remove its verified temporary name without yielding.
-export function publishCopyStage(params) {
+// then remove its verified temporary name after any descriptor handoff.
+export async function publishCopyStage(params) {
     const { identity, temporaryPath, targetPath } = params;
     const assertCurrent = () => {
         assertSyncDirectoryGuard(params.parentGuard);
@@ -62,13 +62,23 @@ export function publishCopyStage(params) {
             }
         }
         else {
-            const parent = fs.lstatSync(path.dirname(temporaryPath), { bigint: true });
-            const current = fs.lstatSync(temporaryPath, { bigint: true });
-            if (parent.isSymbolicLink() || !parent.isDirectory() ||
-                !sameFileIdentityForCleanup(parent, params.parentGuard.stat) ||
-                current.isSymbolicLink() || !current.isFile() ||
-                !sameFileIdentityForCleanup(current, identity)) {
-                throw new FsSafeError("path-mismatch", "published copy temporary name changed before cleanup");
+            const verifyPair = () => {
+                assertSyncDirectoryGuard(params.parentGuard);
+                const parent = fs.lstatSync(path.dirname(temporaryPath), { bigint: true });
+                const current = fs.lstatSync(temporaryPath, { bigint: true });
+                const target = fs.lstatSync(targetPath, { bigint: true });
+                if (parent.isSymbolicLink() || !parent.isDirectory() ||
+                    !sameFileIdentityForCleanup(parent, params.parentGuard.stat) ||
+                    current.isSymbolicLink() || !current.isFile() || current.nlink !== 2n ||
+                    target.isSymbolicLink() || !target.isFile() || target.nlink !== 2n ||
+                    !sameFileIdentityForCleanup(current, identity) || !sameFileIdentityForCleanup(target, identity)) {
+                    throw new FsSafeError("path-mismatch", "published copy temporary name changed before cleanup");
+                }
+            };
+            verifyPair();
+            if (params.beforeTemporaryUnlink) {
+                await params.beforeTemporaryUnlink();
+                verifyPair();
             }
             // This removes the stage's name, never the published destination or source.
             fs.unlinkSync(temporaryPath);

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

@@ -21,6 +21,8 @@ import { getFsSafeTestHooks } from "./test-hooks.js";
 import { hasErrorCode } from "./file-cleanup.js";
 import { writeAllToFile } from "./write-file-handle.js";
 import { isHardlinkFallbackError } from "./hardlink-fallback.js";
+import { publishRenameFallback } from "./publish-rename-fallback.js";
+import { isNoReplaceUnavailable } from "./native-noreplace.js";
 export { isHardlinkFallbackError } from "./hardlink-fallback.js";
 const NATIVE_COPY_FALLBACK_CODES = new Set(["EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EPERM", "EXDEV"]);
 function directoryOpenFlags() {
@@ -232,6 +234,7 @@ export async function publishFileExclusive(params) {
     let sourceNativeParent;
     let targetNativeParent;
     let copiedTarget;
+    let renamedTarget;
     const strategy = params.strategy;
     const failure = {
         phase: strategy === "rename-noreplace" ? "rename-create" : "hardlink-create",
@@ -264,6 +267,9 @@ export async function publishFileExclusive(params) {
             const observed = fsSync.fstatSync(handle.fd, { bigint: true });
             if (!sameFileIdentity(observed, identity))
                 throw new FsSafeError("path-mismatch", "publication descriptor changed");
+            if (failure.fallback && (observed.nlink !== 1n || fsSync.lstatSync(targetPath, { bigint: true }).nlink !== 1n)) {
+                throw new FsSafeError("hardlink", "no-replace publication link count changed");
+            }
             return { method, ...(failure.fallback ? { fallback: failure.fallback } : {}), identity: numberStats(observed), exactIdentity: exactFileIdentity(observed), directorySync };
         };
         await parent.assertCurrent();
@@ -278,36 +284,28 @@ export async function publishFileExclusive(params) {
         if (strategy === "rename-noreplace") {
             const binding = requireNativeBinding("renameNoReplace");
             try {
-                const fallback = nativeMoveNoReplace(binding, [
+                nativeMoveNoReplace(binding, [
                     sourceNativeParent.handle.fd, sourceNativeParent.basename,
                     targetNativeParent.handle.fd, targetNativeParent.basename,
-                ], sourceExactIdentity, getFsSafeNativeConfig().mode === "auto", "file publication");
-                if (fallback) {
-                    failure.fallback = fallback;
-                    failure.sourceRemoval = "removed";
-                }
+                ], sourceExactIdentity, false, "file publication");
             }
             catch (error) {
-                if (error instanceof FsSafeError) {
-                    if (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, sourceExactIdentity, "rename-verify");
+                if (isNoReplaceUnavailable(error) && getFsSafeNativeConfig().mode === "auto" && process.platform === "linux") {
+                    renamedTarget = await publishRenameFallback({
+                        binding, source, sourcePath, targetPath, identity: sourceExactIdentity, failure,
+                        sourceParent: { fd: sourceNativeParent.handle.fd, basename: sourceNativeParent.basename },
+                        targetParent: { fd: targetNativeParent.handle.fd, basename: targetNativeParent.basename },
+                    });
+                }
+                else {
+                    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;
                 }
-                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;
             }
             rememberCreatedTarget(failure, sourceExactIdentity, "rename-verify");
             // A failed post-rename fence must not delete the only remaining name.
@@ -316,7 +314,7 @@ export async function publishFileExclusive(params) {
             assertPublishedTargetCurrent(targetPath, sourceExactIdentity, "no-replace publication target changed");
             assertRenamedSourceAbsent(sourcePath);
             syncFileBestEffortSync(sourceNativeParent.handle.fd);
-            return await finishPublication("rename-noreplace", source, sourceExactIdentity);
+            return await finishPublication("rename-noreplace", renamedTarget ?? source, sourceExactIdentity);
         }
         try {
             if (native?.linkBeneath) {
@@ -363,6 +361,7 @@ export async function publishFileExclusive(params) {
         throw publicationFailure(error, failure, cleanup);
     }
     finally {
+        await renamedTarget?.close().catch(() => undefined);
         await copiedTarget?.close().catch(() => undefined);
         await sourceNativeParent?.handle.close().catch(() => undefined);
         await targetNativeParent?.handle.close().catch(() => undefined);

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

@@ -0,0 +1,21 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { NativeBinding } from "./native-binding.js";
+import { type PublishFailureState } from "./publish-file-failure.js";
+/** Retain the target pin while closing the source dentry, before native unlink. */
+export declare function publishRenameFallback(params: {
+    binding: NativeBinding;
+    sourceParent: {
+        fd: number;
+        basename: string;
+    };
+    targetParent: {
+        fd: number;
+        basename: string;
+    };
+    sourcePath: string;
+    targetPath: string;
+    source: FileHandle;
+    identity: BigIntStats;
+    failure: PublishFailureState;
+}): Promise<FileHandle>;

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

@@ -0,0 +1,102 @@
+import fs, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { openPublicationHandle } from "./publication-handle.js";
+import { rememberCreatedTarget } from "./publish-file-failure.js";
+/** Retain the target pin while closing the source dentry, before native unlink. */
+export async function publishRenameFallback(params) {
+    const { binding, sourceParent, targetParent, sourcePath, targetPath, source, identity, failure } = params;
+    if (!binding.linkBeneath || !binding.removeStagedFile) {
+        throw new FsSafeError("helper-unavailable", "no-replace publication needs native link and identity-bound unlink", {
+            details: { capability: "rename-noreplace", fallback: "link-unlink", fallbackCapability: "linkat" },
+        });
+    }
+    const verify = (stat, links) => {
+        if (!stat.isFile() || stat.isSymbolicLink() || !sameFileIdentityForCleanup(stat, identity)) {
+            throw new FsSafeError("path-mismatch", "no-replace publication identity changed");
+        }
+        if (stat.nlink !== links)
+            throw new FsSafeError("hardlink", "no-replace publication link count changed");
+    };
+    verify(fs.fstatSync(source.fd, { bigint: true }), 1n);
+    verify(fs.lstatSync(sourcePath, { bigint: true }), 1n);
+    try {
+        binding.linkBeneath(sourceParent.fd, sourceParent.basename, targetParent.fd, targetParent.basename);
+    }
+    catch (error) {
+        if (error?.code === "EEXIST") {
+            throw new FsSafeError("already-exists", "no-replace fallback destination exists", { cause: error });
+        }
+        if (["EPERM", "ENOTSUP", "EOPNOTSUPP", "EMLINK", "EXDEV", "ENOSYS"].includes(error?.code ?? "")) {
+            throw new FsSafeError("helper-unavailable", "renameat2 RENAME_NOREPLACE unavailable; linkat file publication fallback is unavailable", {
+                cause: error, details: { capability: "rename-noreplace", fallback: "link-unlink", fallbackCapability: "linkat" },
+            });
+        }
+        throw error;
+    }
+    failure.targetCreated = true;
+    failure.preserveTarget = true;
+    failure.phase = "rename-verify";
+    failure.fallback = "link-unlink";
+    failure.sourceRemoval = "not-attempted";
+    let target;
+    const verifyPair = () => {
+        try {
+            verify(fs.lstatSync(sourcePath, { bigint: true }), 2n);
+            verify(fs.lstatSync(targetPath, { bigint: true }), 2n);
+            if (target)
+                verify(fs.fstatSync(target.fd, { bigint: true }), 2n);
+        }
+        catch (cause) {
+            throw new FsSafeError("path-mismatch", "no-replace publication link pair changed", { cause });
+        }
+    };
+    try {
+        verifyPair();
+        rememberCreatedTarget(failure, identity, "rename-verify");
+        target = await openPublicationHandle(targetPath, identity);
+        await source.close();
+        verifyPair();
+        failure.sourceRemoval = "still-linked";
+        let removed;
+        try {
+            removed = binding.removeStagedFile(sourceParent.fd, sourceParent.basename, target.fd);
+        }
+        catch (error) {
+            try {
+                verify(fs.fstatSync(target.fd, { bigint: true }), 1n);
+                verify(fs.lstatSync(targetPath, { bigint: true }), 1n);
+                if (fs.lstatSync(sourcePath, { bigint: true, throwIfNoEntry: false }))
+                    throw error;
+                removed = "name-absent";
+            }
+            catch {
+                try {
+                    verifyPair();
+                }
+                catch {
+                    failure.sourceRemoval = "unverified";
+                }
+                const detail = failure.sourceRemoval === "still-linked" ? "source still linked" : "source removal unverified";
+                throw new FsSafeError("helper-failed", `linkat file publication fallback published target; ${detail}`, { cause: error });
+            }
+        }
+        if (removed !== "removed" && removed !== "name-absent") {
+            failure.sourceRemoval = "unverified";
+            throw new FsSafeError("helper-failed", "no-replace publication source removal is unverified");
+        }
+        failure.sourceRemoval = "removed";
+        try {
+            verify(fs.fstatSync(target.fd, { bigint: true }), 1n);
+            verify(fs.lstatSync(targetPath, { bigint: true }), 1n);
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "no-replace publication target verification failed", { cause });
+        }
+        return target;
+    }
+    catch (error) {
+        await target?.close().catch(() => undefined);
+        throw error;
+    }
+}