@openclaw/fs-safe 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.21.0 - 2026-09-26
+
+### Highlights
+
+- **Guarded filesystem observation:** `@openclaw/fs-safe/watch` observes literal entry and tree scopes beneath an admitted Root and delivers bounded advisory invalidations; guarded scans stay authoritative. One shared Rust event thread per process uses inotify, FSEvents and ReadDirectoryChangesW on Linux, macOS and Windows, sleeps while idle, and falls back to portable polling under `mode: "auto"`. Subscriptions become ready after one baseline scan, stay available under sustained writes, fence stale generations on `setScopes()`, join native work on `close()`, and support `persistent: false` so one-shot Node commands can exit. Thanks @vincentkoc. ([#690](https://github.com/openclaw/fs-safe/pull/690), [#695](https://github.com/openclaw/fs-safe/pull/695), [#697](https://github.com/openclaw/fs-safe/pull/697), [#703](https://github.com/openclaw/fs-safe/pull/703), [#707](https://github.com/openclaw/fs-safe/pull/707))
+- **Linux user namespaces:** private temp workspaces now work beneath unmapped ancestors, including systemd user services with `PrivateUsers=true`, while UID/GID mappings and ancestor permissions are still rechecked. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+
+### Features
+
+- **Revocable atomic writes:** atomic replacement can recheck caller authority before new effects and report retained destination identities for partial writes and publication, without treating receipts as permission to roll back. ([#694](https://github.com/openclaw/fs-safe/pull/694))
+- **Root walking:** `symlinkPolicy: "include"` reports links without following their targets, preserving sorted traversal, entry budgets, and the existing skip/follow result types. Directory-to-symlink substitutions fail before descent. ([#692](https://github.com/openclaw/fs-safe/pull/692))
+- **Windows file retirement:** the advanced surface can retire existing NTFS files through a retained handle, with exact producer identity, current authority, and separate disposition and settlement facts. There is no persistence guarantee. ([#706](https://github.com/openclaw/fs-safe/pull/706))
+
+### Performance
+
+- **Temporary filename sanitization:** skip duplicate normalization after reserved-device suffixing while preserving filename admission and fallback rules. ([#689](https://github.com/openclaw/fs-safe/pull/689))
+
+### Compatibility
+
+- Supplied temp workspace roots must be owned by the effective user and must not be group- or world-writable; use a private per-user root instead of shared `/tmp`. A one-time warning reports host ownership that cannot be verified. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+- On Windows, an events-mode watch holds one handle on each watched Root, so the Root's own ancestor directories cannot be renamed while it is open; renaming inside the Root is unaffected. Use `mode: "poll"` where that matters. ([#697](https://github.com/openclaw/fs-safe/pull/697))
+- `watch()` requires an explicit `mode` (`"auto"`, `"events"` or `"poll"`); `"events"` fails readiness with `helper-unavailable` when no native backend is available, and Bun currently selects polling under `"auto"`. ([#690](https://github.com/openclaw/fs-safe/pull/690))
+
 ## 0.20.0 - 2026-09-25
 
 ### Highlights

package/README.md

@@ -279,6 +279,7 @@ contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are
 | `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
 | `@openclaw/fs-safe/file-lock` | async/sync sidecar locks, root-bounded sidecars, ownership verification, and stale policy |
 | `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection, raw owner/ACE facts, private-directory creation, and remediation helpers |
+| [`@openclaw/fs-safe/watch`](docs/watch.md) | Guarded observation with native event hints, bounded scans, and joined close |
 | `@openclaw/fs-safe/walk` | budget-bounded directory walking with symlink policy, filters, and truncation accounting; not root-bounded |
 | `@openclaw/fs-safe/copy` | directory copying with `clone: "auto"`, `"always"`, or `"never"`; native APFS, Btrfs, ReFS, XFS, and ZFS cloning, portable byte copying, and clone metadata; see [directory copying](docs/copy.md) |
 | `@openclaw/fs-safe/archive` | policy-driven ZIP/TAR extraction, clamp/filter policy, metadata/path-depth limits, gzip/zstd/bzip2 support, and bounded entry reads |
@@ -368,6 +369,12 @@ await replaceFileAtomic({
 
 `replaceFileAtomicSync()` covers the synchronous case with the same options shape. Both accept an injectable `fileSystem` for tests. Async adapters use `chmod()` on the `FileHandle` returned by their required `open()` operation; custom sync adapters using `mode` or `preserveExistingMode` provide the optional descriptor-bound `fchmodSync` operation.
 
+Both variants accept `assertBeforeMutation` for revocable caller authority and
+`onDestinationState` for observed removal, partial-write, and publication facts.
+The observer receives exact bigint identities from retained descriptors, including
+when later completion fails. These facts do not authorize rollback; the caller
+still owns current authority and content checks. See [atomic write authority](docs/atomic.md#atomic-write-authority-and-destination-state).
+
 ## External outputs
 
 Use `writeExternalFileWithinRoot()` when a browser download, renderer, media
@@ -559,7 +566,8 @@ Check `scan.truncated` before treating the result as complete, and `scan.failedD
 `walkDirectory()` accepts asynchronous `include` and `descend` callbacks through `AsyncWalkDirectoryOptions`, so a marker lookup can prune a directory before its children are read. Decisions remain serial and retain the options object as their `this` receiver; `walkDirectorySync()` and its options remain synchronous. See [Directory walking](docs/walk.md) for callback timing, JavaScript result compatibility, and error handling.
 
 For caller-controlled paths, `Root.walk()` is the root-bounded async iterator.
-It supports entry/depth budgets, in-root symlink following, cancellation, and a
+It supports entry/depth budgets, including links without following their targets,
+in-root symlink following, cancellation, and a
 truncation marker (or typed error) when a budget is reached. Its `entryFilter`
 accepts `"include"`, `"skip"`, or `"skip-subtree"`, directly or through a Promise.
 After an awaited decision resolves, the walk rechecks cancellation and the

package/dist/advanced.d.ts

@@ -37,3 +37,5 @@ export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile,
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
 export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions-windows.js";
 export type { PermissionCommandFailure } from "./permission-exec.js";
+export { retainFileInDirectory } from "./retained-file.js";
+export type { RetainedFile, RetainedFileAdmission, RetainedFileExpected, RetainedFileIssue, RetainedFileReceipt, RetainedFileResult, RetainFileInDirectoryOptions, } from "./retained-file-types.js";

package/dist/advanced.js

@@ -37,3 +37,4 @@ export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularF
 export { buildRandomTempFilePath, sanitizeTempFileName, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, } from "./sibling-temp.js";
 export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
+export { retainFileInDirectory } from "./retained-file.js";

package/dist/atomic.d.ts

@@ -1,4 +1,4 @@
-export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
+export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicDestinationState, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
 export type { RenameIdentityPolicy } from "./pinned-write-types.js";
 export type { ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, } from "./replace-file-copy-fallback.js";
 export { writeTextAtomic, type WriteTextAtomicOptions } from "./text-atomic.js";

package/dist/native-binding.d.ts

@@ -1,3 +1,11 @@
+import type { RetainedFileResult } from "./retained-file-types.js";
+export interface NativeRetainedFile {
+    readonly admission: RetainedFileResult | {
+        status: "retained";
+        identity: string;
+    };
+    settle(remove: boolean): RetainedFileResult;
+}
 import type { TarMeterLimits } from "./archive-limits.js";
 import type { ArchiveMemberKind } from "./archive-plan.js";
 import type { CopyCloneMode } from "./copy-policy.js";
@@ -95,6 +103,20 @@ type NativeTwoPathArgs = [
     targetRelPath: string
 ];
 export interface NativeBinding {
+    /** Windows-only, private handle custody; no borrowed/runtime descriptors. */
+    retainWindowsFile?(directory: string, basename: string, parentDev: bigint, parentIno: bigint, dev: bigint, ino: bigint, size: bigint, mtimeNs: bigint, ctimeNs: bigint, sha256: string, maxBytes: number): NativeRetainedFile;
+    watchRegister?(root: string, limit: number, callback: (batch: import("./watch-native.js").NativeWatchWireBatch) => void, persistent: boolean): number;
+    watchAdd?(id: number, directory: {
+        root: string;
+        relative: string;
+        rootDev: bigint;
+        rootIno: bigint;
+        dev: bigint;
+        ino: bigint;
+    }): void;
+    watchTestEvent?(id: number, path: string, flags: number): void;
+    watchUnregister?(id: number): void;
+    watchThreadCount?(): number;
     /** Internal: consumes only a descriptor returned by this binding. */
     closeOwnedFd(fd: number): void;
     /** Internal Darwin-only synchronous inspection; the caller retains its fd. */

package/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/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/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";
@@ -22,6 +23,7 @@ export declare function copyFallbackReplace(params: {
     maxRestoreBytes?: number;
     expectedSourceIdentity?: BigIntStats;
     sync: boolean;
+    mutation?: AtomicMutation;
 }): Promise<void>;
 export declare function copyFallbackReplaceSync(params: Omit<Parameters<typeof copyFallbackReplace>[0], "fsModule"> & {
     fsModule: SyncFallbackFs;

package/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?.beforeWrite, destination?.assertBeforeMutation, destination?.writing);
+            if (destination)
+                await destination.verify();
             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?.beforeWrite, destination?.writing);
+            destination?.verify();
             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/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-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,6 +12,7 @@ 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: Parameters<typeof pinDirectoryForMode>[0] & {
     mode: number;
@@ -20,6 +22,7 @@ export declare function applyDirectoryModeSync(params: {
     dirPath: string;
     mode: number;
     fchmodSync?: SyncFchmod;
+    mutation?: AtomicMutation;
 }): void;
 export declare function writeTempFile(params: {
     fsModule: AsyncTempFileSystem;
@@ -28,6 +31,7 @@ export declare function writeTempFile(params: {
     mode: number;
     sync: boolean;
     onIdentity?: (identity: BigIntStats) => void;
+    mutation?: AtomicMutation;
 }): Promise<{
     handle: FileHandle;
     identity: BigIntStats;

package/dist/replace-file-descriptor.js

@@ -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/dist/replace-file-destination.d.ts

@@ -0,0 +1,17 @@
+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>;
+    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;
+    published: () => void;
+};

package/dist/replace-file-destination.js

@@ -0,0 +1,61 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+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);
+    const verify = async () => {
+        try {
+            await inspectFileIdentity(async () => regular(await inspect(), pathname, rejectHardlinks), identity);
+            await inspectFileIdentity(async () => regular(await fsModule.lstat(pathname, { bigint: true }), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => mutation.destination("writing", pathname, identity),
+        beforeWrite: async () => {
+            mutation.assert();
+            await verify();
+        },
+        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);
+    const verify = () => {
+        try {
+            inspectFileIdentitySync(() => regular(fsModule.fstatSync(fd, { bigint: true }), pathname, rejectHardlinks), identity);
+            inspectFileIdentitySync(() => regular(fsModule.lstatSync(pathname, { bigint: true }), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => mutation.destination("writing", pathname, identity),
+        beforeWrite: () => {
+            mutation.assert();
+            verify();
+        },
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}

package/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;
+}