@openclaw/openshell-sandbox 2026.9.6 → 2026.9.8

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

@@ -1,4 +1,4 @@
-import { type PermissionCommandFailure } from "./permission-exec.js";
+import { type PermissionFailureFields } from "./permission-exec.js";
 import { type PermissionCheck, type PermissionCheckOptions } from "./permissions.js";
 export type PermissionExec = (command: string, args: string[]) => Promise<{
     stdout: string;
@@ -13,16 +13,13 @@ export type WindowsAclEntry = {
     canRead: boolean;
     canWrite: boolean;
 };
-export type WindowsAclSummary = {
+export type WindowsAclSummary = Omit<PermissionFailureFields & {
     ok: boolean;
     entries: WindowsAclEntry[];
     untrustedWorld: WindowsAclEntry[];
     untrustedGroup: WindowsAclEntry[];
     trusted: WindowsAclEntry[];
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    errorCause?: unknown;
-};
+}, never>;
 export type WindowsUserInfoProvider = () => {
     username?: string | null;
 };

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

@@ -1,9 +1,6 @@
-import type { PermissionCommandFailure } from "./permission-exec.js";
+import type { PermissionFailureFields } from "./permission-exec.js";
 import { type PermissionExec } from "./permissions-windows.js";
-export type { PermissionCommandFailure } from "./permission-exec.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
-export type { IcaclsResetCommandOptions, PermissionExec, WindowsAclEntry, WindowsAclSummary, WindowsUserInfoProvider, } from "./permissions-windows.js";
-export type PermissionCheck = {
+export type PermissionCheck = Omit<PermissionFailureFields & {
     ok: boolean;
     isSymlink: boolean;
     isDir: boolean;
@@ -21,11 +18,7 @@ export type PermissionCheck = {
     /** Owner-query failure detail when Windows ownership could not be verified. */
     ownerError?: string;
     aclSummary?: string;
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    /** Original inspection failure, retained separately from serializable diagnostics. */
-    errorCause?: unknown;
-};
+}, never>;
 export type PermissionCheckOptions = {
     platform?: NodeJS.Platform;
     env?: NodeJS.ProcessEnv;

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

@@ -1,7 +1,6 @@
 import fsSync from "node:fs";
 import { formatIcaclsResetCommand, inspectWindowsPermissions, } from "./permissions-windows.js";
 import { hasWindowsPathAlias, pathForWindowsFilesystem, } from "./windows-path-alias.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
 function failedSafeStat(error) {
     return {
         ok: false,

package/node_modules/@openclaw/fs-safe/dist/pinned-mutation-admission.d.ts

@@ -9,7 +9,6 @@ export type PinnedMutationPolicySnapshot = Readonly<{
 export declare function snapshotPinnedMutationPolicy(denyMutations: DenyMutationPolicy | undefined, mutationSymlinks: MutationSymlinkPolicy | undefined): PinnedMutationPolicySnapshot | undefined;
 export declare function preparePinnedWriteMutationAdmission(params: {
     rootReal: string;
-    rootWithSep: string;
     rootIdentity?: RootBoundaryIdentity;
     resolvedTargetPath: string;
     defaultRelativeParentPath: string;

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

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { assertMutationNotDenied } from "./deny-mutations.js";
+import { createMutationDenyMatcher } from "./deny-mutation-match.js";
 import { FsSafeError } from "./errors.js";
 import { isPathInside } from "./path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
@@ -100,8 +101,9 @@ function epochCurrent(epoch, directories) {
         getFsSafeNativeConfig().mode === epoch.mode;
 }
 function assertCachedNotDenied(target, epoch) {
-    if (epoch.paths.some((paths) => paths.some((denied) => isPathInside(denied, target) && isPathInside(target, denied))) ||
-        epoch.prefixes.some((paths) => paths.some((denied) => isPathInside(denied, target)))) {
+    const matches = createMutationDenyMatcher();
+    if (epoch.paths.some((paths) => paths.some((denied) => matches(target, denied, false))) ||
+        epoch.prefixes.some((paths) => paths.some((denied) => matches(target, denied, true)))) {
         throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
     }
 }

package/node_modules/@openclaw/fs-safe/dist/pinned-mutation-shared-route.d.ts

@@ -1,14 +1,9 @@
-import type { DenyMutationPolicy } from "./deny-mutations.js";
+import type { PinnedMutationPolicySnapshot } from "./pinned-mutation-admission.js";
 import type { RootBoundaryIdentity } from "./root-boundary.js";
-import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export type ExactRootIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
 }>;
-type SharedMutationPolicy = Readonly<{
-    denyMutations?: DenyMutationPolicy;
-    mutationSymlinks?: MutationSymlinkPolicy;
-}>;
 export declare function ordinaryWindowsSegments(relativePath: string): boolean;
 export declare function ordinarySharedAbsoluteInsideRoot(rootReal: string, candidatePath: string, rootIdentity: ExactRootIdentity): boolean;
 export declare function simpleSharedRoute(params: {
@@ -16,9 +11,8 @@ export declare function simpleSharedRoute(params: {
     rootIdentity?: RootBoundaryIdentity;
     originalPath?: string;
     selectedTarget: string;
-    policy: SharedMutationPolicy;
+    policy: PinnedMutationPolicySnapshot;
 }): {
     route: string;
     rootIdentity: ExactRootIdentity;
 } | undefined;
-export {};

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

@@ -14,10 +14,10 @@ export type PinnedOpenSyncResult = {
 export type PinnedOpenSyncAllowedType = "file" | "directory";
 export type PinnedOpenSyncFinalAdmission = (params: {
     path: string;
-    preRealpathIdentity: fs.BigIntStats;
     descriptorIdentity: fs.BigIntStats;
 }) => string;
 export type PinnedOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;
+export declare function isExpectedPathError(error: unknown): boolean;
 export declare function openPinnedFileSync(params: {
     filePath: string;
     resolvedPath?: string;

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

@@ -5,7 +5,7 @@ import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
-function isExpectedPathError(error) {
+export function isExpectedPathError(error) {
     const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
     return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
 }
@@ -53,14 +53,13 @@ export function openPinnedFileSync(params) {
             assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, preOpenStat);
-        const pathIdentity = inspectFileIdentitySync(() => {
+        inspectFileIdentitySync(() => {
             const stat = ioFs.lstatSync(realPath, { bigint: true });
             assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, identity);
         const admittedPath = params.finalAdmission?.({
             path: realPath,
-            preRealpathIdentity: pathIdentity,
             descriptorIdentity: identity,
         }) ?? realPath;
         const opened = { ok: true, path: admittedPath, fd, stat: openedStat, identity };

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

@@ -22,6 +22,10 @@ export function publishCopyStage(params) {
     // Caller authority checks can synchronously replace a parent or staged entry.
     if (params.assertBeforeMutation)
         assertCurrent();
+    // An observed collision needs no dispatch; errno after a link attempt remains ambiguous.
+    if (fs.lstatSync(targetPath, { throwIfNoEntry: false })) {
+        throw new FsSafeError("already-exists", "destination already exists");
+    }
     params.onPublicationAttempt?.();
     fs.linkSync(temporaryPath, targetPath);
     let observerRejected = false;

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

@@ -7,12 +7,9 @@ export type ReadResult = {
     realPath: string;
     stat: Stats;
 };
-type OpenedFile = {
+type OpenedFile = Omit<ReadResult & {
     handle: FileHandle;
-    containment: ContainmentGuarantee;
-    realPath: string;
-    stat: Stats;
-};
+}, "buffer">;
 export declare function readOpenedFileSafely(params: {
     opened: OpenedFile;
     maxBytes?: number;

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

@@ -208,10 +208,10 @@ function inspectAppendPath(filePath) {
 }
 function prepareRegularAppend(filePath, rejectSymlinkParents) {
     if (rejectSymlinkParents === true) {
-        const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
+        const unresolvedDir = path.dirname(filePath);
         assertNoSymlinkParentsSync({
-            rootDir: path.parse(resolvedDir).root,
-            targetPath: resolvedDir,
+            rootDir: path.parse(resolvePathPreservingWindowsRoot(unresolvedDir)).root,
+            targetPath: unresolvedDir,
             allowMissing: false,
             allowRootChildSymlink: true,
             requireDirectories: true,

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

@@ -6,7 +6,7 @@ import { assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryId
 import { FsSafeError } from "./errors.js";
 import { classifyNativeRenameFailure, NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH, } from "./native-rename-outcome.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
-import { RetainedDirectoryReplacement } from "./retained-directory-replacement.js";
+import { copyOperationalCode, RetainedDirectoryReplacement } from "./retained-directory-replacement.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { serializePathWrite } from "./write-queue.js";
@@ -17,30 +17,18 @@ function assertGuardsCurrent(guards) {
     for (const guard of guards)
         assertSyncDirectoryGuard(guard);
 }
-function copyOperationalCode(target, source) {
-    const code = source?.code;
-    if (typeof code === "string") {
-        Object.defineProperty(target, "code", { configurable: true, value: code });
-    }
-}
-function replacementFailure(error, message, details) {
+function replacementFailure(error, message, details, cause = error) {
     if (error instanceof FsSafeError) {
-        return new FsSafeError(error.code, message, { cause: error, details });
+        return new FsSafeError(error.code, message, { cause, details });
     }
-    const failure = new Error(message, { cause: error });
+    const failure = new Error(message, { cause });
     copyOperationalCode(failure, error);
     Object.defineProperty(failure, "details", { configurable: true, value: details });
     return failure;
 }
 function replacementAggregate(error, recoveryError, message, details) {
     const combined = new AggregateError([error, recoveryError], "directory replacement operation and recovery both failed");
-    if (error instanceof FsSafeError) {
-        return new FsSafeError(error.code, message, { cause: combined, details });
-    }
-    const failure = new Error(message, { cause: combined });
-    copyOperationalCode(failure, error);
-    Object.defineProperty(failure, "details", { configurable: true, value: details });
-    return failure;
+    return replacementFailure(error, message, details, combined);
 }
 function isMissingDirectoryEntry(error) {
     return error?.code === "ENOENT";

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

@@ -0,0 +1,4 @@
+import type syncFs from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export declare function writeAtomicDestination(handle: FileHandle, data: Buffer, beforeWrite?: () => Promise<void>, assertBeforeMutation?: () => void, onWriting?: () => void): Promise<void>;
+export declare function writeAtomicDestinationSync(fsModule: Pick<typeof syncFs, "ftruncateSync" | "writeSync">, fd: number, data: Buffer, beforeWrite?: () => void, onWriting?: () => void): void;

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

@@ -0,0 +1,36 @@
+export async function writeAtomicDestination(handle, data, beforeWrite, assertBeforeMutation, onWriting) {
+    if (beforeWrite)
+        await beforeWrite();
+    assertBeforeMutation?.();
+    await handle.truncate(0);
+    onWriting?.();
+    let written = 0;
+    while (written < data.length) {
+        if (beforeWrite)
+            await beforeWrite();
+        assertBeforeMutation?.();
+        const result = await handle.write(data, written, data.length - written, written);
+        if (result.bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += result.bytesWritten;
+    }
+    if (beforeWrite)
+        await beforeWrite();
+    assertBeforeMutation?.();
+    await handle.truncate(data.length);
+}
+export function writeAtomicDestinationSync(fsModule, fd, data, beforeWrite, onWriting) {
+    beforeWrite?.();
+    fsModule.ftruncateSync(fd, 0);
+    onWriting?.();
+    let written = 0;
+    while (written < data.length) {
+        beforeWrite?.();
+        const bytesWritten = fsModule.writeSync(fd, data, written, data.length - written, written);
+        if (bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += bytesWritten;
+    }
+    beforeWrite?.();
+    fsModule.ftruncateSync(fd, data.length);
+}

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

@@ -1,4 +1,5 @@
 import syncFs, { type BigIntStats } from "node:fs";
+import { AtomicMutation } from "./replace-file-mutation.js";
 export type ReplaceFileDestinationHardlinkPolicy = "reject";
 export type ReplaceFileCopyFallbackRestorePolicy = "restore-original" | "none";
 export type ReplaceFileAtomicRestoreCleanup = "restored" | "restore-failed";
@@ -9,9 +10,8 @@ type AsyncFallbackFs = {
     lstat: typeof import("node:fs/promises").lstat;
     open: typeof import("node:fs/promises").open;
     rm: typeof import("node:fs/promises").rm;
-    unlink: typeof import("node:fs/promises").unlink;
 };
-type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "unlinkSync" | "writeSync">;
+type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "writeSync">;
 export declare function assertDestinationHardlinkPolicy(fsModule: AsyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): Promise<void>;
 export declare function assertDestinationHardlinkPolicySync(fsModule: SyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): void;
 export declare function copyFallbackReplace(params: {
@@ -23,16 +23,10 @@ export declare function copyFallbackReplace(params: {
     maxRestoreBytes?: number;
     expectedSourceIdentity?: BigIntStats;
     sync: boolean;
+    mutation?: AtomicMutation;
 }): Promise<void>;
-export declare function copyFallbackReplaceSync(params: {
+export declare function copyFallbackReplaceSync(params: Omit<Parameters<typeof copyFallbackReplace>[0], "fsModule"> & {
     fsModule: SyncFallbackFs;
-    src: string;
-    dest: string;
-    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
-    restore: ReplaceFileCopyFallbackRestorePolicy;
-    maxRestoreBytes?: number;
-    expectedSourceIdentity?: BigIntStats;
     fchmodSync?: (fd: number, mode: number) => void;
-    sync: boolean;
 }): void;
 export {};

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

@@ -6,6 +6,9 @@ import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-iden
 import { readOwnedCopySource, readOwnedCopySourceSync } from "./replace-file-copy-source.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { hasErrorCode } from "./file-cleanup.js";
+import { writeAtomicDestination, writeAtomicDestinationSync } from "./replace-file-buffer.js";
+import { AtomicMutation } from "./replace-file-mutation.js";
+import { captureAtomicDestination, captureAtomicDestinationSync } from "./replace-file-destination.js";
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants;
 const NOFOLLOW = SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0;
 const OPEN_READ_FLAGS = resolveReadOpenFlags();
@@ -44,7 +47,7 @@ function inspectPinnedDestinationSync(fsModule, fd, dest, admission, hardlinks)
     inspectFileIdentitySync(() => admitDestinationKind(fsModule.lstatSync(dest, { bigint: true }), opened, dest, admission), opened);
     assertDestinationLinks(opened, dest, admission, hardlinks);
 }
-async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
+async function openPinnedDestination(fsModule, dest, admission, hardlinks, mutation) {
     let preview;
     try {
         preview = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
@@ -61,6 +64,7 @@ async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
     if (admission === "restore" && preview.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
+    mutation?.assert();
     const handle = await fsModule.open(dest, admission === "restore" ? OPEN_READ_WRITE_FLAGS : OPEN_READ_FLAGS);
     try {
         if (fsModule === fs)
@@ -82,7 +86,7 @@ async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
         throw error;
     }
 }
-function openPinnedDestinationSync(fsModule, dest, admission, hardlinks) {
+function openPinnedDestinationSync(fsModule, dest, admission, hardlinks, mutation) {
     let preview;
     try {
         preview = fsModule.lstatSync(dest);
@@ -97,6 +101,7 @@ function openPinnedDestinationSync(fsModule, dest, admission, hardlinks) {
     if (admission === "restore" && preview.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
+    mutation?.assert();
     const fd = fsModule.openSync(dest, admission === "restore" ? OPEN_READ_WRITE_FLAGS : OPEN_READ_FLAGS);
     try {
         inspectPinnedDestinationSync(fsModule, fd, dest, admission, hardlinks);
@@ -148,28 +153,6 @@ function readRestoreSnapshotSync(fsModule, fd, maxBytes, stat) {
         return bytesRead;
     }, restoreReadOptions(stat, maxBytes));
 }
-async function writeAll(handle, data) {
-    await handle.truncate(0);
-    let written = 0;
-    while (written < data.length) {
-        const result = await handle.write(data, written, data.length - written, written);
-        if (result.bytesWritten === 0)
-            throw new Error("Copy fallback write made no progress");
-        written += result.bytesWritten;
-    }
-    await handle.truncate(data.length);
-}
-function writeAllSync(fsModule, fd, data) {
-    fsModule.ftruncateSync(fd, 0);
-    let written = 0;
-    while (written < data.length) {
-        const bytesWritten = fsModule.writeSync(fd, data, written, data.length - written, written);
-        if (bytesWritten === 0)
-            throw new Error("Copy fallback write made no progress");
-        written += bytesWritten;
-    }
-    fsModule.ftruncateSync(fd, data.length);
-}
 function restoreFailure(writeError, cleanup, restoreError) {
     const primary = writeError instanceof Error ? writeError : new Error(String(writeError));
     const details = { cleanup };
@@ -180,23 +163,29 @@ function restoreFailure(writeError, cleanup, restoreError) {
         ? `Atomic copy fallback failed; original destination restored: ${primary.message}`
         : `Atomic copy fallback failed and original restoration failed: ${primary.message}`, { cause, details });
 }
-async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestoreBytes, replacementMode) {
+async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestoreBytes, replacementMode, destination, mutation) {
     const originalStat = fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
     const originalMode = originalStat.mode;
     const original = await readRestoreSnapshot(handle, maxRestoreBytes, originalStat);
     try {
-        await writeAll(handle, replacement);
+        await writeAtomicDestination(handle, replacement, destination?.beforeWrite, destination?.assertBeforeMutation, destination?.writing);
+        if (destination)
+            await destination.verify();
         await handle.chmod(replacementMode);
         await handle.sync();
     }
     catch (writeError) {
+        mutation.rethrowRefusal();
         try {
-            await writeAll(handle, original);
+            await writeAtomicDestination(handle, original, destination?.beforeRestore, destination?.assertBeforeMutation, destination?.writing);
+            if (destination)
+                await destination.verifyRestore();
             await handle.chmod(originalMode);
             await handle.sync();
             throw restoreFailure(writeError, "restored");
         }
         catch (restoreError) {
+            mutation.rethrowRefusal();
             if (restoreError instanceof FsSafeError && restoreError.details?.cleanup === "restored") {
                 throw restoreError;
             }
@@ -204,23 +193,27 @@ async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestor
         }
     }
 }
-function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes, replacementMode, fchmodSync) {
+function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes, replacementMode, fchmodSync, destination, mutation) {
     const originalStat = fsModule.fstatSync(fd);
     const originalMode = originalStat.mode;
     const original = readRestoreSnapshotSync(fsModule, fd, maxRestoreBytes, originalStat);
     try {
-        writeAllSync(fsModule, fd, replacement);
+        writeAtomicDestinationSync(fsModule, fd, replacement, destination?.beforeWrite, destination?.writing);
+        destination?.verify();
         fchmodSync?.(fd, replacementMode);
         fsModule.fsyncSync(fd);
     }
     catch (writeError) {
+        mutation?.rethrowRefusal();
         try {
-            writeAllSync(fsModule, fd, original);
+            writeAtomicDestinationSync(fsModule, fd, original, destination?.beforeRestore, destination?.writing);
+            destination?.verifyRestore();
             fchmodSync?.(fd, originalMode);
             fsModule.fsyncSync(fd);
             throw restoreFailure(writeError, "restored");
         }
         catch (restoreError) {
+            mutation?.rethrowRefusal();
             if (restoreError instanceof FsSafeError && restoreError.details?.cleanup === "restored") {
                 throw restoreError;
             }
@@ -229,6 +222,7 @@ function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes
     }
 }
 export async function copyFallbackReplace(params) {
+    const mutation = params.mutation ?? new AtomicMutation({});
     const source = await readOwnedCopySource({
         fsModule: params.fsModule,
         src: params.src,
@@ -237,12 +231,16 @@ export async function copyFallbackReplace(params) {
     const { replacement } = source;
     let destHandle = null;
     let closeRequiredForSuccess = false;
+    let completed = false;
+    let destination;
     try {
         if (params.restore === "restore-original") {
-            const pinned = await openPinnedDestination(params.fsModule, params.dest, "restore", params.destinationHardlinks);
+            const pinned = await openPinnedDestination(params.fsModule, params.dest, "restore", params.destinationHardlinks, mutation);
             if (pinned) {
                 destHandle = pinned;
-                await replacePinnedWithRestore(params.fsModule, destHandle, replacement, params.maxRestoreBytes, source.mode);
+                if (mutation.active)
+                    destination = await captureAtomicDestination(params.fsModule, pinned, params.dest, mutation, params.destinationHardlinks === "reject");
+                await replacePinnedWithRestore(params.fsModule, destHandle, replacement, params.maxRestoreBytes, source.mode, destination, mutation);
             }
         }
         if (!destHandle) {
@@ -260,16 +258,31 @@ export async function copyFallbackReplace(params) {
             }
             if (destStat) {
                 await assertDestinationHardlinkPolicy(params.fsModule, params.dest, params.destinationHardlinks);
+                mutation.assert();
                 await params.fsModule.rm(params.dest, { force: true });
+                mutation.removed(params.dest);
             }
+            mutation.assert();
             destHandle = await params.fsModule.open(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, source.mode & 0o777);
-            await destHandle.writeFile(replacement);
+            if (mutation.active) {
+                destination = await captureAtomicDestination(params.fsModule, destHandle, params.dest, mutation, params.destinationHardlinks === "reject");
+                destination.writing();
+                await writeAtomicDestination(destHandle, replacement, destination.beforeWrite, destination.assertBeforeMutation);
+                await destination.verify();
+            }
+            else {
+                await destHandle.writeFile(replacement);
+            }
             await destHandle.chmod(source.mode);
             if (params.sync) {
                 await destHandle.sync();
             }
             closeRequiredForSuccess = !params.sync;
         }
+        if (destination)
+            await destination.verify();
+        destination?.published();
+        completed = true;
     }
     finally {
         if (destHandle) {
@@ -277,7 +290,7 @@ export async function copyFallbackReplace(params) {
                 await destHandle.close();
             }
             catch (closeError) {
-                if (closeRequiredForSuccess) {
+                if (closeRequiredForSuccess && completed) {
                     throw closeError;
                 }
             }
@@ -285,6 +298,7 @@ export async function copyFallbackReplace(params) {
     }
 }
 export function copyFallbackReplaceSync(params) {
+    const mutation = params.mutation ?? new AtomicMutation({});
     const source = readOwnedCopySourceSync({
         fsModule: params.fsModule,
         src: params.src,
@@ -293,12 +307,16 @@ export function copyFallbackReplaceSync(params) {
     const { replacement } = source;
     let destFd;
     let closeRequiredForSuccess = false;
+    let completed = false;
+    let destination;
     try {
         if (params.restore === "restore-original") {
-            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, "restore", params.destinationHardlinks);
+            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, "restore", params.destinationHardlinks, mutation);
             if (pinned !== null) {
                 destFd = pinned;
-                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, source.mode, params.fchmodSync);
+                if (mutation.active)
+                    destination = captureAtomicDestinationSync(params.fsModule, pinned, params.dest, mutation, params.destinationHardlinks === "reject");
+                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, source.mode, params.fchmodSync, destination, mutation);
             }
         }
         if (destFd === undefined) {
@@ -315,16 +333,26 @@ export function copyFallbackReplaceSync(params) {
             }
             if (destStat) {
                 assertDestinationHardlinkPolicySync(params.fsModule, params.dest, params.destinationHardlinks);
+                mutation.assert();
                 params.fsModule.rmSync(params.dest, { force: true });
+                mutation.removed(params.dest);
             }
+            mutation.assert();
             destFd = params.fsModule.openSync(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, source.mode & 0o777);
-            writeAllSync(params.fsModule, destFd, replacement);
+            if (mutation.active)
+                destination = captureAtomicDestinationSync(params.fsModule, destFd, params.dest, mutation, params.destinationHardlinks === "reject");
+            destination?.writing();
+            writeAtomicDestinationSync(params.fsModule, destFd, replacement, destination?.beforeWrite);
+            destination?.verify();
             params.fchmodSync?.(destFd, source.mode);
             if (params.sync) {
                 params.fsModule.fsyncSync(destFd);
             }
             closeRequiredForSuccess = !params.sync;
         }
+        destination?.verify();
+        destination?.published();
+        completed = true;
     }
     finally {
         if (destFd !== undefined) {
@@ -332,7 +360,7 @@ export function copyFallbackReplaceSync(params) {
                 params.fsModule.closeSync(destFd);
             }
             catch (closeError) {
-                if (closeRequiredForSuccess) {
+                if (closeRequiredForSuccess && completed) {
                     throw closeError;
                 }
             }

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

@@ -1,6 +1,7 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
-import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+import { type DirectoryModeOwner } from "./directory-mode-node.js";
+import type { AtomicMutation } from "./replace-file-mutation.js";
 type AsyncTempFileSystem = Pick<typeof fs, "lstat" | "open" | "writeFile">;
 type SyncTempFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "lstatSync" | "openSync" | "writeFileSync">;
 export type SyncFchmod = (fd: number, mode: number) => void;
@@ -11,18 +12,17 @@ export declare function pinDirectoryForMode(params: {
     dirPath: string;
     /** Compatibility for best-effort directory modes; admission and close still fail closed. */
     ignoreChmodError?: boolean;
+    mutation?: AtomicMutation;
 }): Promise<DirectoryModeOwner | undefined>;
-export declare function applyDirectoryMode(params: {
-    fsModule: AsyncTempFileSystem;
-    dirPath: string;
+export declare function applyDirectoryMode(params: Parameters<typeof pinDirectoryForMode>[0] & {
     mode: number;
-    ignoreChmodError?: boolean;
 }): Promise<void>;
 export declare function applyDirectoryModeSync(params: {
     fsModule: SyncTempFileSystem;
     dirPath: string;
     mode: number;
     fchmodSync?: SyncFchmod;
+    mutation?: AtomicMutation;
 }): void;
 export declare function writeTempFile(params: {
     fsModule: AsyncTempFileSystem;
@@ -31,18 +31,14 @@ export declare function writeTempFile(params: {
     mode: number;
     sync: boolean;
     onIdentity?: (identity: BigIntStats) => void;
+    mutation?: AtomicMutation;
 }): Promise<{
     handle: FileHandle;
     identity: BigIntStats;
 }>;
-export declare function writeTempFileSync(params: {
+export declare function writeTempFileSync(params: Omit<Parameters<typeof writeTempFile>[0], "fsModule"> & {
     fsModule: SyncTempFileSystem;
-    tempPath: string;
-    content: string | Uint8Array;
-    mode: number;
     fchmodSync?: SyncFchmod;
-    sync: boolean;
-    onIdentity?: (identity: BigIntStats) => void;
 }): {
     fd: number;
     identity: BigIntStats;