@openclaw/fs-safe 0.8.5 → 0.9.0

package/dist/sidecar-lock-reclaim.js

@@ -90,7 +90,13 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
                 await opened.handle.close().catch(() => undefined);
             }
         }
-        const before = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        let before;
+        try {
+            before = fsSync.lstatSync(lockPath);
+        }
+        catch (error) {
+            before = missingSnapshotPath(error);
+        }
         if (!before)
             return null;
         if (!before.isFile() || before.isSymbolicLink()) {
@@ -119,7 +125,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
             options.onOpenFailure?.(error);
             throw error;
         }
-        const opened = await handle.stat();
+        const opened = fsSync.fstatSync(handle.fd);
         if (!opened.isFile()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
@@ -129,7 +135,13 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
         if (!options.allowDescriptorIdentityDrift && !sameFileIdentity(before, opened))
             return null;
         const raw = (await readFileHandleBounded(handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
-        const after = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        let after;
+        try {
+            after = fsSync.lstatSync(lockPath);
+        }
+        catch (error) {
+            after = missingSnapshotPath(error);
+        }
         if (!after || !after.isFile() || !sameFileIdentity(before, after))
             return null;
         return { raw, stat: after };
@@ -241,7 +253,7 @@ export async function sidecarLockSnapshotStillPresent(lockPath, observed, option
 }
 export async function sidecarReclaimGuardExists(pathname) {
     try {
-        await fs.lstat(pathname);
+        fsSync.lstatSync(pathname);
         return true;
     }
     catch (err) {

package/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAqIjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAuFD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAU3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAkBL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAsIjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAuFD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAU3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAkBL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}

package/dist/sidecar-lock.js

@@ -85,7 +85,8 @@ function snapshotMatchesSync(lockPath, observed) {
     }
 }
 function releaseAllReclaimGuardsSync(state) {
-    for (const reclaimGuardPath of state.reclaimGuards) {
+    // Exit cleanup also visits managers created by older copies and never reopened here.
+    for (const reclaimGuardPath of state.reclaimGuards ?? []) {
         try {
             fsSync.rmdirSync(reclaimGuardPath);
             state.reclaimGuards.delete(reclaimGuardPath);

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAsCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
@@ -81,12 +82,16 @@ function isNodeErrorWithCode(err, code) {
 }
 async function cleanupTempDir(dir, identity, onCleanupError) {
     try {
-        const current = await fs.lstat(dir, { bigint: true }).catch((error) => {
+        let current;
+        try {
+            current = fsSync.lstatSync(dir, { bigint: true });
+        }
+        catch (error) {
             if (isNodeErrorWithCode(error, "ENOENT")) {
-                return undefined;
+                return;
             }
             throw error;
-        });
+        }
         if (!current || !sameFileIdentityForCleanup(current, identity)) {
             return;
         }
@@ -107,7 +112,7 @@ export async function tempFile(params) {
     const dir = await fs.mkdtemp(path.join(rootDir, prefix));
     // Windows file indexes can exceed Number.MAX_SAFE_INTEGER. Cleanup receipts
     // must retain the exact identity or adjacent directories can compare equal.
-    const identity = await fs.lstat(dir, { bigint: true });
+    const identity = fsSync.lstatSync(dir, { bigint: true });
     const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
     const file = (fileName) => path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
     const cleanup = async () => {

package/dist/walk.js

@@ -76,7 +76,7 @@ async function resolveAsyncKind(fullPath, dirent, symlinks) {
     if (symlinks === "include")
         return "symlink";
     try {
-        const stat = await fs.stat(fullPath);
+        const stat = fsSync.statSync(fullPath);
         if (stat.isDirectory())
             return "directory";
         if (stat.isFile())
@@ -162,7 +162,7 @@ export async function walkDirectory(rootDir, options = {}) {
             return;
         let realDir;
         try {
-            realDir = await fs.realpath(dir);
+            realDir = fsSync.realpathSync.native(dir);
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);

package/dist/write-open-flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}
+{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAG7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}

package/dist/write-open-flags.js

@@ -1,5 +1,4 @@
 import fsSync from "node:fs";
-import fs from "node:fs/promises";
 import { hasNodeErrorCode } from "./path.js";
 export function resolveNonblockingWriteFlag(constants = fsSync.constants) {
     return process.platform !== "win32" && typeof constants.O_NONBLOCK === "number"
@@ -17,7 +16,7 @@ export async function isNonRegularWriteOpenError(error, filePath, flags) {
     if (!isNonblockingWriteEnxio(error, flags))
         return false;
     try {
-        return !(await fs.lstat(filePath)).isFile();
+        return !fsSync.lstatSync(filePath).isFile();
     }
     catch {
         return false;

package/docs/archive.md

@@ -43,6 +43,7 @@ type ExtractArchiveOptions = {
   archivePath: string;          // absolute path to the archive
   destDir: string;              // absolute destination directory; must already exist
   timeoutMs: number;            // positive wall-clock budget; <= 0/non-finite disables it
+  durable?: boolean;            // false; opt into syncing published files and directories before completion
   kind?: ArchiveKind;           // "zip" | "tar" | "tar-zstd" | "tar-bzip2"
   stripComponents?: number;     // strip N leading dirs from entry paths
   tarGzip?: boolean;            // when archive is .tar.gz/.tgz
@@ -55,6 +56,36 @@ type ExtractArchiveOptions = {
 };
 ```
 
+`durable` defaults to `false`. Private staging never fsyncs, and publication copies
+defer opted-in durability until the complete merge succeeds. With `durable: true`, the final pass syncs each
+published file once (at most eight concurrently), then each published directory
+once, deepest first, and finally the destination directory. All work stays inside
+the extraction deadline; active syncs are joined before rejection. File sync
+failures use the same error surface as `Root.copyIn()`; directory I/O failures
+also reject, with the existing platform limitations on directory flushing.
+Files whose final mode prevents reading, including `0o000` and write-only files,
+sync once through the copy's retained descriptor during publication. Permissions
+are never widened to reopen them. Directory modes are finalized after the file
+pass, with a descriptor pinned before chmod for syncing restrictive directories.
+Existing inaccessible directories are never widened; an existing search-only
+directory must become readable in its final mode if no readable sync descriptor
+can be acquired before chmod.
+
+The default suits extractions into temporary or reconstructible locations.
+It skips all file and directory syncs while preserving atomic file publication,
+mode enforcement, identity checks, and containment checks. Successful `durable: true`
+extraction syncs file contents and directory entries before returning; failures
+can leave a partially published tree as described below.
+
+For a crash-safe install workflow, extract with the default into a scratch
+directory, then apply the caller's durability policy: sync the staged files and
+directories before publishing with [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic),
+and sync the affected parent directories afterward. The directory swap alone
+does not sync the staged tree. Alternatively, pass `durable: true` when extracted
+files must be on stable storage before the extraction call returns, subject to
+the platform's flushing guarantees. A plain fsync on macOS does not flush the
+drive cache.
+
 `entryModes` defaults to `"clamp"`: directories become `0o755`; files become
 `0o644`, or `0o755` when the archived owner-execute bit is set. `"preserve"`
 keeps archived read/write/execute bits. Both policies strip setuid, setgid, and
@@ -201,11 +232,13 @@ before publication preserves a pre-existing file, and rejection does not grant
 authority to delete a substituted file or alias. Failed extraction does not
 restore overwritten contents. Active destination mutations and their guarded
 cleanup still finish before rejection; no later destination mutation begins.
-New directories whose postorder finalization was never reached can retain their
+New directories whose finalization was never reached can retain their
 private working mode after failure. Failure cleanup closes retained descriptors;
-it does not run a final chmod sweep or roll back the archive. The public merge
+it does not run a cleanup chmod sweep or roll back the archive. The public merge
 helper still derives modes from its external source tree and must be able to
 read that source; it never chmods an unreadable external source to admit it.
+That helper retains per-copy durability and immediate postorder directory-mode
+finalization; the deferred pass described above belongs to `extractArchive()`.
 
 ### Limits
 

package/docs/atomic.md

@@ -75,12 +75,37 @@ If `beforeRename` throws, the rename is skipped and the owned temp file is remov
 
 Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
 
-### FUSE mounts and unstable rename identity
+### FUSE, Windows exFAT/FAT32, and unstable rename identity
 
 Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
 
 This is the same explicit weaker contract available on `Root` writes: cooperating writers are serialized, stale locks fail closed, and mismatched content is rejected after publication without rollback. A same-authority actor that ignores the advisory lock can still substitute another file with identical bytes, so do not use this compatibility policy in directories writable by untrusted same-UID processes.
 
+Windows exFAT/FAT32 volumes can also change file identity during rename, depending
+on the source and destination names. The destination may already contain the
+requested bytes when strict verification reports `path-mismatch`. A short
+temporary name alone does not guarantee stable identity for a longer destination.
+For an application-controlled directory on such a volume, callers can explicitly
+select `renameIdentity: "verify-content-with-lock"` on `replaceFileAtomic` or
+`replaceFileAtomicSync`. Keep strict mode for directories that require the
+stronger identity contract; do not automatically retry every `path-mismatch`
+with the weaker policy. Staging names remain random, including custom prefixes.
+
+To verify the built package against an actual volume, run
+`node scripts/atomic-rename-compat-proof.mjs EXISTING_PARENT` after `pnpm build`.
+Use a trusted parent directory that no other process can rename or modify during
+the entire run, including cleanup; do not point the probe at a shared writable
+volume root. Cleanup checks the created directory's identity before recursive
+removal, but the check and removal are not atomic. The probe does not test safety
+against hostile concurrent namespace mutation.
+The probe creates and cleans up its own child directory and emits JSON without
+local paths. It compares default, strict, and locked policies in both async and
+sync calls, checks real rename identities and file contents, injects different-
+and identical-content substitutions, checks lock cleanup, and exercises custom
+prefix isolation and validation. Callback staging remains strict and can still
+report identity drift; the probe records that result separately. Filesystem type
+must be recorded independently; the probe does not infer it from a drive letter.
+
 ### `EPERM` and copy fallback
 
 On systems where `rename` fails with `EPERM`/`EEXIST`, pass

package/docs/file-store.md

@@ -28,9 +28,18 @@ const cache = fileStore({
   dirMode: 0o700,     // mode for parent directories created on demand (default 0o700)
   maxBytes: 64 * 1024 * 1024, // optional: refuse writes/reads larger than this
   private: true,      // use secret-file atomic writes for private state
+  durable: true,      // sync file and parent directory (default true)
 });
 ```
 
+| `FileStoreOptions` option | Default | Purpose |
+|---|---|---|
+| `rootDir` | Required | Store directory. |
+| `private` | `false` | Use the secret-file atomic path. |
+| `mode` / `dirMode` | `0o600` / `0o700` | File and parent-directory modes. |
+| `maxBytes` | Unset | Store read/write byte limit. |
+| `durable` | `true` | Sync the written file and its parent directory; see method support below. |
+
 Store and per-call `maxBytes` values must be non-negative safe integers or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` disables the cap. An omitted or explicitly `undefined` per-call value preserves the store-level limit. The same rule applies to buffer writes, streams, copies, async reads, and synchronous reads/writes.
 
 Use `private: true` for credentials, auth profiles, tokens, and other private
@@ -101,7 +110,22 @@ therefore does not imply that no filesystem access or serialization occurred.
 
 ## Writes
 
-Every write goes through `writeSiblingTempFile` — temp + rename, mode applied to file and parent dir, both `fsync`'d.
+Writes use guarded sibling-temp publication: apply file and directory modes,
+then rename into place. By default, the file and parent directory are synced
+where supported by the platform and writer.
+
+`durable: false` keeps the sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability. Per-call
+`durable` overrides the store option, which defaults to `true`; an omitted or
+`undefined` override preserves the store default. Modes, path confinement,
+and publication identity checks are unchanged.
+
+| Method | Durability support |
+|---|---|
+| `write`, `writeText`, `writeJson` (async and sync) | Per-call option overrides store default. |
+| `writeStream`, `copyIn` (either private mode) | Per-call option overrides store default. |
+| JSON `write`, `update`, `updateOr` | JSON handle option overrides file-store default. |
 
 ### `write(rel, data, options?)`
 
@@ -118,7 +142,7 @@ Convenience wrappers over `write`. `writeJson` pretty-prints with a trailing new
 ### `json<T>(rel, options?)`
 
 Returns a typed single-file JSON state helper for a file under this store. It
-inherits the store's root, mode, max-size, and private-write policy, then adds
+inherits the store's root, mode, max-size, durability, and private-write policy, then adds
 `readOr`, `readRequired`, `update`, `updateOr`, and optional sidecar locking:
 
 ```ts
@@ -129,6 +153,9 @@ await state.updateOr(defaultState, (current) => ({ ...current, enabled: true }))
 Use this when one JSON file owns one piece of state. `jsonStore({ filePath })`
 is the absolute-path convenience wrapper for the same primitive.
 
+Pass `{ durable: false }` or `{ durable: true }` to `json()` to override the
+parent store's durability for all mutations of that JSON handle.
+
 ### `writeStream(rel, stream, options?)`
 
 ```ts
@@ -138,6 +165,9 @@ const path = await cache.writeStream("downloads/blob.bin", Readable.from(remoteF
 
 Streams into a sibling temp with a running byte budget. Aborts the source stream with `too-large` if `maxBytes` is exceeded mid-stream — partial writes are cleaned up.
 
+Streams honor `durable` in both private modes. Non-private streams stage their
+input and forward the resolved durability option to Root `copyIn` for publication.
+
 ### `copyIn(rel, sourcePath, options?)`
 
 ```ts
@@ -146,12 +176,16 @@ const path = await cache.copyIn("ingest/upload.bin", "/tmp/upload.bin");
 
 One-shot ingest from an absolute source path. Source is checked for symlink/non-regular before copy. Same mode rules as `write`.
 
+`copyIn` honors per-call and store-level `durable` values in both private modes,
+with the same precedence as `write`.
+
 ### `FileStoreWriteOptions`
 
 Per-call overrides for the store-level defaults:
 
 ```ts
 type FileStoreWriteOptions = {
+  durable?: boolean;   // store default, otherwise true
   dirMode?: number;
   mode?: number;
   maxBytes?: number;
@@ -159,6 +193,17 @@ type FileStoreWriteOptions = {
 };
 ```
 
+| `FileStoreWriteOptions` option | Default |
+|---|---|
+| `durable` | Store option, otherwise `true`. |
+| `dirMode` / `mode` | Store directory/file modes. |
+| `maxBytes` | Store byte limit. |
+| `tempPrefix` | Writer-specific temporary prefix. |
+
+The same durability precedence applies to `fileStoreSync().write`,
+`writeText`, and `writeJson`. The synchronous store has no `writeStream` or
+`copyIn` methods.
+
 ## Reads
 
 `open`, `read`, `readBytes`, `readText`, and `readJson` delegate to a fresh `Root` with `hardlinks: "reject"` and the store's `maxBytes`. Same return shapes as `Root`.
@@ -254,5 +299,5 @@ await root.move(`pending/${id}`, `done/${id}`);
 
 - [`root()`](root.md) — the boundary `FileStore` is built on; reach for it when you need move/list/append.
 - [JSON store](json-store.md) — the JSON-state-file equivalent of this surface.
-- [Atomic writes](atomic.md) — `writeSiblingTempFile` is what every write goes through.
+- [Atomic writes](atomic.md) — lower-level sibling-temp publication helpers.
 - [Temp workspaces](temp.md) — private scratch directories backed by `FileStore`.

package/docs/json-store.md

@@ -45,6 +45,7 @@ type JsonStoreOptions<T> = {
   filePath: string;
   dirMode?: number;                                // default 0o700
   mode?: number;                                   // default 0o600
+  durable?: boolean;                              // default true
   trailingNewline?: boolean;                       // default true
   lock?: boolean | JsonStoreLockOptions;           // false / undefined = no lock
 };
@@ -71,6 +72,15 @@ type JsonStore<T> = {
 `jsonStore({ filePath })` resolves `rootDir = dirname(filePath)` and calls
 `fileStore({ rootDir, private: true }).json(basename(filePath), options)`.
 
+`durable: false` keeps sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability. The default
+is `true`, subject to platform sync support. This store-level policy applies
+to `write`, `update`, and `updateOr`; these methods have no per-call options.
+For `fileStore(...).json(rel, options)`, `options.durable` overrides the parent
+file store's durability, while omission or `undefined` inherits it. Modes,
+identity checks, mutation serialization, and sidecar locking are unchanged.
+
 The store does **not** validate the parsed value against `T` at runtime — the cast is unchecked. Wrap with a schema (zod/valibot) if the file might be hand-edited or written by another process you don't control.
 
 ## `read()`

package/docs/reading.md

@@ -14,6 +14,12 @@ const opened = await fs.open("large.log");               // FileHandle for strea
 
 Identity and containment checks use brief synchronous metadata calls, like Node's module resolution, while file data is read asynchronously. Canonical paths retain Node's native realpath spelling, including expansion of Windows short paths.
 
+The same observation rule applies to archive extraction, copy, publication, move,
+directory modes, and supporting lock, queue, and secret-file operations. Opens,
+data transfers, durability syncs, filesystem mutations, and closes retain their
+existing asynchronous behavior. Custom filesystem adapters retain their async
+metadata interface.
+
 Regardless of shape, every read goes through the same boundary checks:
 
 1. Resolve the input lexically against the canonical real root.

package/docs/root.md

@@ -18,7 +18,7 @@ const fs = await root("/srv/workspace", {
 function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 
 type RootDefaults = {
-  durable?: boolean;               // fsync write/create/writeJson/createJson/append; default true
+  durable?: boolean;               // fsync write/create/writeJson/createJson/append/copyIn; default true
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
@@ -111,7 +111,7 @@ fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
-These five methods also accept `durable?: boolean`: the per-call value overrides
+These five methods and `copyIn` also accept `durable?: boolean`: the per-call value overrides
 `Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
 `undefined` per-call value preserves the root default. `durable: false` keeps
 the existing publication behavior, modes, and identity checks but skips file

package/docs/secret-file.md

@@ -172,9 +172,15 @@ type WriteSecretFileParams = {
   content: string | Uint8Array;
   mode?: number;                // file mode for the new file (default PRIVATE_SECRET_FILE_MODE = 0o600)
   dirMode?: number;             // mode for the root and intermediate dirs (default PRIVATE_SECRET_DIR_MODE = 0o700)
+  durable?: boolean;            // default true; false skips file and parent fsync
 };
 ```
 
+`durable: false` preserves atomic publication, modes, and identity checks while
+skipping file and parent-directory `fsync` calls. Use it only for reconstructible
+data where lower latency matters more than crash-durability; private and JSON
+stores forward their durability policy here.
+
 The full POSIX directory mode is asserted on each component along the path: `rootDir`, then any intermediate dirs, then the parent. Existing directories, including another creator's `EEXIST` winner, must already match `dirMode` exactly or the write fails with `insecure-permissions`; they are never chmod-repaired. An explicitly requested directory mode such as `0o2750` preserves its setgid bit. Audit and adjust existing secret directories yourself. The admitted directory guards are retained through traversal and the final writer/lock handoff; a fresh pathname lookup cannot silently authorize a replacement. The caller must still trust the selected root and its owners; matching permission bits alone do not establish that trust.
 
 Directory admission and its retained guards use lossless bigint identities, including through private locks and native writes. On Windows, an unknown zero device or inode gets one reinspection that retains known components; a definite mismatch or persistent ambiguity fails with `path-mismatch` rather than authorizing a replacement.

package/docs/sidecar-lock.md

@@ -25,6 +25,8 @@ On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit"
 
 Always release locks in a `finally` block. Application-managed graceful shutdown can await `release()` or `manager.drain()` before terminating. Explicit `process.exit()`, uncaught failures, crashes, default signal handling, and fatal termination (including `SIGKILL`) do not reliably run asynchronous Root cleanup and may leave sidecars. Recover only after an application-owned liveness policy proves the holder cannot still be writing.
 
+Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
+
 Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check.
 
 The raw sidecar bytes are not a canonical JSON representation: tools that trim or rewrite the trailing whitespace invalidate the ownership token, so release leaves the changed sidecar in place and fails closed. The token distinguishes cooperating acquisitions; it is not a secret and does not make pathname compare-and-remove atomic against a hostile process that can replace files outside the lock protocol.

package/docs/writing.md

@@ -91,14 +91,14 @@ await fs.write("notes/today.txt", "hello\n", { encoding: "utf8" });
 | `overwrite` | `boolean` | `true`; `false` is create-only. |
 | `renameIdentity` | `RenameIdentityPolicy` | `"strict"`. |
 
-`write`, `create`, `writeJson`, `createJson`, and `append` accept `durable`.
+`write`, `create`, `writeJson`, `createJson`, `append`, and `copyIn` accept `durable`.
 Precedence is per-call option, then `Root.defaults.durable`, then `true`;
 an explicitly `undefined` call option preserves the root default.
 `durable: false` keeps the sibling-temp replace/rename behavior of replacement
 writes but skips file and parent-directory fsync calls. Create-only and append
 publication behavior, permissions, identity checks, and error codes are unchanged.
 Use it only for reconstructible data: a crash may lose the write or leave the
-previous file. `copyIn`, `move`, and streaming `openWritable` do not use this option.
+previous file. `move` and streaming `openWritable` do not use this option.
 The existing pure-JavaScript Windows writer performs no fsync calls in either
 setting; native Windows writes honor the option. Directory sync remains best-effort.
 
@@ -185,7 +185,9 @@ await fs.copyIn("inbox/upload.bin", "/tmp/incoming.bin", {
 });
 ```
 
-Options are `{ denyMutations?, maxBytes?, mkdir?, mode?, sourceHardlinks? }`.
+Options are `{ denyMutations?, durable?, maxBytes?, mkdir?, mode?, sourceHardlinks? }`.
+`durable` follows the root default and is `true` when omitted at both levels;
+set it to `false` to skip file and parent-directory syncs for reconstructible data.
 Use `sourceHardlinks: "reject"` to refuse if the source itself is a hardlinked
 alias. There is no encoding option: copying preserves source bytes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -156,19 +156,19 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.8.5",
-    "@openclaw/fs-safe-darwin-x64": "0.8.5",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.5",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.8.5",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.8.5",
-    "@openclaw/fs-safe-linux-x64-musl": "0.8.5",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.8.5",
-    "jszip": "^3.10.1"
+    "@openclaw/fs-safe-darwin-arm64": "0.9.0",
+    "@openclaw/fs-safe-darwin-x64": "0.9.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.9.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.9.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.9.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.9.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.9.0",
+    "jszip": "^3.10.2"
   },
   "devDependencies": {
-    "@emnapi/runtime": "2.0.0-alpha.4",
+    "@emnapi/runtime": "2.0.0-alpha.5",
     "@napi-rs/cli": "3.9.0",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.5.1",
     "@vitest/coverage-v8": "5.0.0",
     "fast-check": "^4.9.0",
     "istanbul-lib-coverage": "3.2.2",