@openclaw/openshell-sandbox 2026.9.6 → 2026.9.7

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

@@ -3,7 +3,7 @@ import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { ownDirectoryMode } from "./directory-mode-owner.js";
+import { ownDirectoryMode } from "./directory-mode-node.js";
 export async function syncDirectoryBestEffort(fsModule, dirPath) {
     let handle;
     try {
@@ -73,7 +73,10 @@ export async function pinDirectoryForMode(params) {
                     : await inspectFileIdentity(async () => assertDirectory(await handle.stat({ bigint: true }), params.dirPath), expected);
                 return Number(opened.mode & 4095n);
             },
-            chmod: (mode) => handle.chmod(mode),
+            chmod: (mode) => {
+                params.mutation?.assert();
+                return handle.chmod(mode);
+            },
             close: () => handle.close(),
             ignoreChmodError: params.ignoreChmodError,
         });
@@ -103,6 +106,7 @@ export function applyDirectoryModeSync(params) {
     try {
         inspectFileIdentitySync(() => assertDirectory(params.fsModule.fstatSync(fd, { bigint: true }), params.dirPath), expected);
         // chmod ignores file-type bits; mask so raw stat modes are tolerated.
+        params.mutation?.assert();
         params.fchmodSync?.(fd, params.mode & 0o7777);
     }
     finally {
@@ -110,6 +114,7 @@ export function applyDirectoryModeSync(params) {
     }
 }
 export async function writeTempFile(params) {
+    params.mutation?.assert();
     const handle = await params.fsModule.open(params.tempPath, "wx", params.mode);
     try {
         // Custom adapters retain their async-only metadata contract.
@@ -117,6 +122,7 @@ export async function writeTempFile(params) {
             ? syncFs.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
         const identity = await inspectFileIdentity(inspect);
         params.onIdentity?.(identity);
+        params.mutation?.assert();
         await params.fsModule.writeFile(handle, params.content);
         await handle.chmod(params.mode);
         if (params.sync) {
@@ -136,10 +142,12 @@ export async function writeTempFile(params) {
     }
 }
 export function writeTempFileSync(params) {
+    params.mutation?.assert();
     const fd = params.fsModule.openSync(params.tempPath, "wx", params.mode);
     try {
         const identity = inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }));
         params.onIdentity?.(identity);
+        params.mutation?.assert();
         params.fsModule.writeFileSync(fd, params.content);
         params.fchmodSync?.(fd, params.mode);
         if (params.sync) {

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

@@ -0,0 +1,21 @@
+import fsSync from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import type { AtomicMutation } from "./replace-file-mutation.js";
+/** Borrow the writer's descriptor; never adopt an identity from a later pathname open. */
+export declare function captureAtomicDestination(fsModule: Pick<typeof fs, "lstat">, handle: FileHandle, pathname: string, mutation: AtomicMutation, rejectHardlinks: boolean): Promise<{
+    verify: () => Promise<void>;
+    writing: () => void;
+    beforeWrite: () => Promise<void>;
+    beforeRestore: () => Promise<void>;
+    verifyRestore: () => Promise<void>;
+    assertBeforeMutation: () => void;
+    published: () => void;
+}>;
+export declare function captureAtomicDestinationSync(fsModule: Pick<typeof fsSync, "lstatSync" | "fstatSync">, fd: number, pathname: string, mutation: AtomicMutation, rejectHardlinks: boolean): {
+    verify: () => void;
+    writing: () => void;
+    beforeWrite: () => void;
+    beforeRestore: () => void;
+    verifyRestore: () => void;
+    published: () => void;
+};

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

@@ -0,0 +1,123 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { hasErrorCode } from "./file-cleanup.js";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+function regular(stat, pathname, rejectHardlinks) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new FsSafeError("path-mismatch", `Atomic replace destination changed: ${pathname}`);
+    }
+    if (rejectHardlinks && stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${pathname}`);
+    }
+    return stat;
+}
+/** Borrow the writer's descriptor; never adopt an identity from a later pathname open. */
+export async function captureAtomicDestination(fsModule, handle, pathname, mutation, rejectHardlinks) {
+    const inspect = () => fsModule === fs
+        ? fsSync.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
+    const identity = await inspectFileIdentity(inspect);
+    regular(identity, pathname, rejectHardlinks);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verifyDescriptor = async () => {
+        await inspectFileIdentity(async () => regular(await inspect(), pathname, rejectHardlinks), identity);
+    };
+    const verify = async () => {
+        let metadataFailure = false;
+        const observe = async (read) => {
+            try {
+                return await read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            await inspectFileIdentity(async () => regular(await observe(inspect), pathname, rejectHardlinks), identity);
+            await inspectFileIdentity(async () => regular(await observe(() => fsModule.lstat(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                // A metadata observation failed, but the already-owned descriptor can
+                // still restore its bytes after fresh exact descriptor verification.
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = async () => {
+        if (!restoreDescriptorOnly)
+            return await verify();
+        try {
+            await verifyDescriptor();
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
+        beforeWrite: async () => {
+            mutation.assert();
+            await verify();
+        },
+        beforeRestore: async () => { mutation.assert(); await verifyRestore(); },
+        verifyRestore,
+        assertBeforeMutation: () => mutation.assert(),
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}
+export function captureAtomicDestinationSync(fsModule, fd, pathname, mutation, rejectHardlinks) {
+    const identity = inspectFileIdentitySync(() => fsModule.fstatSync(fd, { bigint: true }));
+    regular(identity, pathname, rejectHardlinks);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verify = () => {
+        let metadataFailure = false;
+        const observe = (read) => {
+            try {
+                return read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.fstatSync(fd, { bigint: true })), pathname, rejectHardlinks), identity);
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.lstatSync(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = () => {
+        if (!restoreDescriptorOnly)
+            return verify();
+        try {
+            inspectFileIdentitySync(() => regular(fsModule.fstatSync(fd, { bigint: true }), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
+        beforeWrite: () => {
+            mutation.assert();
+            verify();
+        },
+        beforeRestore: () => { mutation.assert(); verifyRestore(); },
+        verifyRestore,
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}

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

@@ -0,0 +1,26 @@
+import type { BigIntStats } from "node:fs";
+export type ReplaceFileAtomicDestinationState = Readonly<{
+    state: "removed";
+    path: string;
+}> | Readonly<{
+    state: "writing" | "published";
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
+export type AtomicMutationOptions = {
+    /** Recheck live authority before new effects; retained descriptor completion may settle. */
+    assertBeforeMutation?: () => void;
+    /** Retain observed destination facts even when later completion fails. */
+    onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
+};
+export declare class AtomicMutation {
+    #private;
+    readonly active: boolean;
+    constructor(options: AtomicMutationOptions);
+    rethrowRefusal(): void;
+    refuse(error: unknown): never;
+    assert(): void;
+    destination(state: "writing" | "published", path: string, identity: BigIntStats): void;
+    removed(path: string): void;
+}

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

@@ -0,0 +1,47 @@
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+export class AtomicMutation {
+    active;
+    #assertion;
+    #observer;
+    #refusal;
+    #writingReported = false;
+    constructor(options) {
+        this.#assertion = options.assertBeforeMutation;
+        this.#observer = options.onDestinationState;
+        this.active = Boolean(this.#assertion || this.#observer);
+    }
+    rethrowRefusal() {
+        if (this.#refusal)
+            throw this.#refusal.error;
+    }
+    refuse(error) {
+        this.#refusal ??= { error };
+        throw this.#refusal.error;
+    }
+    #invoke(operation, name) {
+        this.rethrowRefusal();
+        try {
+            const result = operation();
+            assertSynchronousCallbackResult(result, name);
+        }
+        catch (error) {
+            this.refuse(error);
+        }
+    }
+    assert() {
+        this.#invoke(() => this.#assertion?.(), "assertBeforeMutation");
+    }
+    destination(state, path, identity) {
+        if (state === "writing") {
+            if (this.#writingReported)
+                return;
+            this.#writingReported = true;
+        }
+        this.#invoke(() => this.#observer?.(Object.freeze({
+            state, path, dev: identity.dev, ino: identity.ino,
+        })), "onDestinationState");
+    }
+    removed(path) {
+        this.#invoke(() => this.#observer?.(Object.freeze({ state: "removed", path })), "onDestinationState");
+    }
+}

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

@@ -26,7 +26,7 @@ export declare class AsyncAtomicTempOwner extends AtomicTempOwner<FileHandle> {
         identity: BigIntStats;
     }): void;
     assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
-    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string): Promise<void>;
+    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): Promise<void>;
     finish(params: {
         fsModule: AsyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;
@@ -39,7 +39,7 @@ export declare class SyncAtomicTempOwner extends AtomicTempOwner<number> {
         identity: BigIntStats;
     }): void;
     assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
-    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string): void;
+    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): void;
     finish(params: {
         fsModule: SyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;

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

@@ -161,16 +161,21 @@ export class AsyncAtomicTempOwner extends AtomicTempOwner {
             throw error;
         }
     }
-    async assertPublished(fsModule, pathname, expectedHash) {
+    async assertPublished(fsModule, pathname, expectedHash, onVerified) {
+        let identityCurrent = false;
         try {
             await this.assertCurrent(fsModule, pathname);
-            return;
+            identityCurrent = true;
         }
         catch (error) {
             if (!(error instanceof FsSafeError) || !hasErrorCode(error, "path-mismatch") || !expectedHash) {
                 throw error;
             }
         }
+        if (identityCurrent) {
+            onVerified?.(this.identity);
+            return;
+        }
         let published;
         try {
             try {
@@ -199,6 +204,7 @@ export class AsyncAtomicTempOwner extends AtomicTempOwner {
             if (sha256Hex(await published.readFile()) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
+            onVerified?.(identity);
             const previousHandle = this.takeResource();
             await previousHandle?.close();
             this.resource = published;
@@ -269,16 +275,21 @@ export class SyncAtomicTempOwner extends AtomicTempOwner {
             throw error;
         }
     }
-    assertPublished(fsModule, pathname, expectedHash) {
+    assertPublished(fsModule, pathname, expectedHash, onVerified) {
+        let identityCurrent = false;
         try {
             this.assertCurrent(fsModule, pathname);
-            return;
+            identityCurrent = true;
         }
         catch (error) {
             if (!(error instanceof FsSafeError) || !hasErrorCode(error, "path-mismatch") || !expectedHash) {
                 throw error;
             }
         }
+        if (identityCurrent) {
+            onVerified?.(this.identity);
+            return;
+        }
         let publishedFd;
         try {
             try {
@@ -305,6 +316,7 @@ export class SyncAtomicTempOwner extends AtomicTempOwner {
             if (sha256Hex(fsModule.readFileSync(publishedFd)) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
+            onVerified?.(identity);
             const previousFd = this.takeResource();
             fsModule.closeSync(previousFd);
             this.resource = publishedFd;

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

@@ -0,0 +1,55 @@
+import type syncFs from "node:fs";
+import type fs from "node:fs/promises";
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
+import type { AtomicMutationOptions } from "./replace-file-mutation.js";
+import type { ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
+export type ReplaceFileAtomicFileSystem = {
+    promises: Pick<typeof fs, "mkdir" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat"> & {
+        /** @deprecated Accepted for adapter compatibility but never called. */
+        chmod?: typeof fs.chmod;
+    };
+};
+export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "readFileSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "fstatSync" | "statSync" | "lstatSync" | "ftruncateSync" | "readSync" | "writeSync"> & {
+    /** @deprecated Accepted for adapter compatibility but never called. */
+    chmodSync?: typeof syncFs.chmodSync;
+    fchmodSync?: typeof syncFs.fchmodSync;
+};
+export type ReplaceFileAtomicBaseOptions = AtomicMutationOptions & {
+    filePath: string;
+    content: string | Uint8Array;
+    dirMode?: number;
+    mode?: number;
+    /** Inherit only rwx bits from an existing non-symlink regular file. */
+    preserveExistingMode?: boolean;
+    tempPrefix?: string;
+    renameMaxRetries?: number;
+    renameRetryBaseDelayMs?: number;
+    copyFallbackOnPermissionError?: boolean;
+    copyFallbackRestore?: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    /** Strict by default; locked content verification is an explicit FUSE compatibility policy. */
+    renameIdentity?: RenameIdentityPolicy;
+    syncTempFile?: boolean;
+    syncParentDir?: boolean;
+    throwOnCleanupError?: boolean;
+};
+export type ReplaceFileAtomicOptions = ReplaceFileAtomicBaseOptions & {
+    fileSystem?: ReplaceFileAtomicFileSystem;
+    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
+    beforeRename?: (params: {
+        filePath: string;
+        tempPath: string;
+    }) => Promise<void>;
+};
+export type ReplaceFileAtomicSyncOptions = ReplaceFileAtomicBaseOptions & {
+    fileSystem?: ReplaceFileAtomicSyncFileSystem;
+    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
+    beforeRename?: (params: {
+        filePath: string;
+        tempPath: string;
+    }) => void;
+};
+export type ReplaceFileAtomicResult = {
+    method: "rename" | "copy-fallback";
+};

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

@@ -0,0 +1 @@
+export {};

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

@@ -1,58 +1,6 @@
-import syncFs from "node:fs";
-import fs from "node:fs/promises";
-import type { RenameIdentityPolicy } from "./pinned-write-types.js";
-import { type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
-export type ReplaceFileAtomicFileSystem = {
-    promises: Pick<typeof fs, "mkdir" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat"> & {
-        /** @deprecated Accepted for adapter compatibility but never called. */
-        chmod?: typeof fs.chmod;
-    };
-};
-export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" | "readFileSync" | "writeFileSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync" | "openSync" | "fsyncSync" | "closeSync" | "fstatSync" | "statSync" | "lstatSync" | "ftruncateSync" | "readSync" | "writeSync"> & {
-    /** @deprecated Accepted for adapter compatibility but never called. */
-    chmodSync?: typeof syncFs.chmodSync;
-    fchmodSync?: typeof syncFs.fchmodSync;
-};
-type ReplaceFileAtomicBaseOptions = {
-    filePath: string;
-    content: string | Uint8Array;
-    dirMode?: number;
-    mode?: number;
-    /** Inherit only rwx bits from an existing non-symlink regular file. */
-    preserveExistingMode?: boolean;
-    tempPrefix?: string;
-    renameMaxRetries?: number;
-    renameRetryBaseDelayMs?: number;
-    copyFallbackOnPermissionError?: boolean;
-    copyFallbackRestore?: ReplaceFileCopyFallbackRestorePolicy;
-    maxRestoreBytes?: number;
-    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
-    /** Strict by default; locked content verification is an explicit FUSE compatibility policy. */
-    renameIdentity?: RenameIdentityPolicy;
-    syncTempFile?: boolean;
-    syncParentDir?: boolean;
-    throwOnCleanupError?: boolean;
-};
-export type ReplaceFileAtomicOptions = ReplaceFileAtomicBaseOptions & {
-    fileSystem?: ReplaceFileAtomicFileSystem;
-    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
-    beforeRename?: (params: {
-        filePath: string;
-        tempPath: string;
-    }) => Promise<void>;
-};
-export type ReplaceFileAtomicSyncOptions = ReplaceFileAtomicBaseOptions & {
-    fileSystem?: ReplaceFileAtomicSyncFileSystem;
-    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
-    beforeRename?: (params: {
-        filePath: string;
-        tempPath: string;
-    }) => void;
-};
-export type ReplaceFileAtomicResult = {
-    method: "rename" | "copy-fallback";
-};
+import type { ReplaceFileAtomicOptions, ReplaceFileAtomicSyncOptions, ReplaceFileAtomicResult } from "./replace-file-types.js";
+export type { ReplaceFileAtomicDestinationState } from "./replace-file-mutation.js";
+export type { ReplaceFileAtomicFileSystem, ReplaceFileAtomicSyncFileSystem, ReplaceFileAtomicOptions, ReplaceFileAtomicSyncOptions, ReplaceFileAtomicResult, } from "./replace-file-types.js";
 export declare function replaceFileAtomic(options: ReplaceFileAtomicOptions): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicWithDirectorySync(options: ReplaceFileAtomicOptions, syncParent?: (directoryPath: string) => Promise<unknown>): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicSync(options: ReplaceFileAtomicSyncOptions): ReplaceFileAtomicResult;
-export {};

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

@@ -13,15 +13,19 @@ import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
 import { hasErrorCode, readErrorCode } from "./file-cleanup.js";
+import { AtomicMutation } from "./replace-file-mutation.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 async function renameWithRetry(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
         if (attempt > 0)
             await params.assertSourceCurrent();
         try {
+            params.mutation.assert();
             await params.fsModule.rename(params.src, params.dest);
             return { method: "rename" };
         }
         catch (error) {
+            params.mutation.rethrowRefusal();
             const code = readErrorCode(error);
             if (code === "EBUSY" && attempt < params.maxRetries) {
                 await sleep(params.baseDelayMs * 2 ** attempt);
@@ -37,6 +41,7 @@ async function renameWithRetry(params) {
                     maxRestoreBytes: params.maxRestoreBytes,
                     expectedSourceIdentity: params.sourceIdentity,
                     sync: params.syncFallback,
+                    mutation: params.mutation,
                 });
                 return { method: "copy-fallback" };
             }
@@ -50,10 +55,12 @@ function renameWithRetrySync(params) {
         if (attempt > 0)
             params.assertSourceCurrent();
         try {
+            params.mutation.assert();
             params.fsModule.renameSync(params.src, params.dest);
             return { method: "rename" };
         }
         catch (error) {
+            params.mutation.rethrowRefusal();
             const code = readErrorCode(error);
             if (code === "EBUSY" && attempt < params.maxRetries) {
                 sleepSync(params.baseDelayMs * 2 ** attempt);
@@ -70,6 +77,7 @@ function renameWithRetrySync(params) {
                     expectedSourceIdentity: params.sourceIdentity,
                     fchmodSync: params.fchmodSync,
                     sync: params.syncFallback,
+                    mutation: params.mutation,
                 });
                 return { method: "copy-fallback" };
             }
@@ -142,24 +150,27 @@ export async function replaceFileAtomic(options) {
 }
 // Internal owner hook: keep directory durability inside publication verification and serialization.
 export async function replaceFileAtomicWithDirectorySync(options, syncParent) {
+    const mutation = new AtomicMutation(options);
     const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
     const renameIdentity = options.renameIdentity;
     validateRenameIdentity(renameIdentity);
     return await serializePathWrite(path.resolve(filePath), async () => {
         if (renameIdentity !== "verify-content-with-lock") {
-            return await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent);
+            return await replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent);
         }
         const fsModule = options.fileSystem?.promises ?? fs;
         const dir = path.dirname(filePath);
+        mutation.assert();
         await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, {
             recursive: true,
             mode: options.dirMode ?? 0o700,
         });
-        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent));
+        mutation.assert();
+        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent));
     });
 }
-async function replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent) {
+async function replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent) {
     const fsModule = options.fileSystem?.promises ?? fs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
@@ -169,8 +180,9 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
     const tempOwner = new AsyncAtomicTempOwner(tempPath);
     let originalFailure;
     try {
+        mutation.assert();
         await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
-        await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
+        await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode, mutation });
         tempOwner.start();
         tempOwner.adopt(await writeTempFile({
             fsModule,
@@ -179,6 +191,7 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
             mode,
             sync: options.syncTempFile === true,
             onIdentity: tempOwner.onIdentity,
+            mutation,
         }));
         await tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
@@ -202,10 +215,11 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
             sourceIdentity: tempOwner.identity,
             assertSourceCurrent: () => tempOwner.assertCurrent(fsModule),
             syncFallback: options.syncTempFile === true,
+            mutation,
         });
         if (result.method === "rename") {
             tempOwner.markRenamed();
-            await tempOwner.assertPublished(fsModule, filePath, expectedHash);
+            await tempOwner.assertPublished(fsModule, filePath, expectedHash, identity => mutation.destination("published", filePath, identity));
         }
         else {
             await tempOwner.assertCurrent(fsModule);
@@ -237,22 +251,25 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
     }
 }
 export function replaceFileAtomicSync(options) {
+    const mutation = new AtomicMutation(options);
     const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
     const renameIdentity = options.renameIdentity;
     validateRenameIdentity(renameIdentity);
     if (renameIdentity !== "verify-content-with-lock") {
-        return replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity);
+        return replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation);
     }
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
+    mutation.assert();
     fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, {
         recursive: true,
         mode: options.dirMode ?? 0o700,
     });
-    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity));
+    mutation.assert();
+    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation));
 }
-function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
+function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation) {
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
@@ -269,8 +286,9 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
     const tempOwner = new SyncAtomicTempOwner(tempPath);
     let originalFailure;
     try {
+        mutation.assert();
         fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
-        applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
+        applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync, mutation });
         tempOwner.start();
         tempOwner.adopt(writeTempFileSync({
             fsModule,
@@ -280,10 +298,11 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
             fchmodSync,
             sync: options.syncTempFile === true,
             onIdentity: tempOwner.onIdentity,
+            mutation,
         }));
         tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
-            options.beforeRename({ filePath, tempPath });
+            assertSynchronousCallbackResult(options.beforeRename({ filePath, tempPath }), "beforeRename");
             tempOwner.assertCurrent(fsModule);
         }
         if (options.destinationHardlinks === "reject") {
@@ -304,10 +323,11 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
             assertSourceCurrent: () => tempOwner.assertCurrent(fsModule),
             fchmodSync,
             syncFallback: options.syncTempFile === true,
+            mutation,
         });
         if (result.method === "rename") {
             tempOwner.markRenamed();
-            tempOwner.assertPublished(fsModule, filePath, expectedHash);
+            tempOwner.assertPublished(fsModule, filePath, expectedHash, identity => mutation.destination("published", filePath, identity));
         }
         else {
             tempOwner.assertCurrent(fsModule);

package/node_modules/@openclaw/fs-safe/dist/retained-directory-replacement.d.ts

@@ -6,6 +6,7 @@ export type RetainedReplacementParent = Readonly<{
     realPath: string;
     identity: Pick<BigIntStats, "dev" | "ino">;
 }>;
+export declare function copyOperationalCode(target: Error, source: unknown): void;
 export declare class RetainedDirectoryReplacement {
     #private;
     private constructor();