@openclaw/fs-safe 0.7.1 → 0.8.0

package/docs/archive.md

@@ -61,9 +61,42 @@ type ExtractArchiveOptions = {
 `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
-sticky bits, and neither applies archived ownership. TAR extraction disables
-`tar`'s ownership and mode restoration and applies the selected modes in the
-private staging tree; ZIP applies the same policy to `unixPermissions`.
+sticky bits, and neither applies archived ownership. An explicit zero mode,
+including a mode containing only stripped special bits, stays zero under
+`"preserve"`. Absent metadata defaults to `0o644` for files and `0o755` for
+directories; ZIP UNIX creator records with zero attributes are explicit zero,
+while non-UNIX ZIP records use the absent-metadata defaults.
+
+TAR mode fields containing only NUL/ASCII-space padding use absent defaults.
+Native extraction also recognizes GNU binary modes, including signed values,
+within node-tar's JavaScript safe-integer range before masking permission bits.
+Malformed or unsupported mode representations retain existing decoder behavior:
+native falls back to zero, while JavaScript may default, parse an octal prefix,
+or reject. These representations are not newly admitted or standardized by the
+mode repair; raw framing and other numeric-field checks remain unchanged.
+
+Final modes remain separate from private working staging permissions: files
+stay `0o600` and directories `0o700` until publication. Files receive their final
+mode through the guarded copy's owned writer descriptor. Directories are pinned
+before descending and finalized after their children, including empty and
+restrictive directories. Explicit accepted directory modes win regardless of
+archive order; implicit parents receive `0o755`. Existing destination directories
+also receive the requested final mode. They are never temporarily widened to
+allow child writes; insufficient write/search access still rejects.
+
+Directory mode changes use a retained no-follow read descriptor when possible.
+On macOS x64/arm64, read-denied directories can use a retained search descriptor.
+On Linux x64/arm64, the Node-only search route retains an `O_PATH` descriptor and
+changes modes through its exact `/proc/self/fd/N` reference after verifying the
+procfs namespace and followed identity. The descriptor stays open through the
+operation and verification; original root, ancestor and named-directory checks
+still apply. This route trusts host mount-namespace integrity and does not claim
+atomic ancestry checks or protection against privileged mount replacement.
+Readable directories do not depend on procfs. A Linux search-only directory
+needing a mode change requires accessible, genuine procfs; unavailable or
+untrusted authority rejects explicitly instead of silently accepting a wrong
+mode. Other unsupported search-only routes also fail closed. Windows retains
+its existing bounded lack of POSIX mode enforcement.
 
 Native extraction is deliberately split into two phases. Rust first reports an
 entry manifest without creating paths. TypeScript validates paths, applies
@@ -157,6 +190,22 @@ record and are then cleared; local PAX on unsupported types and GNU sparse
 
 If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). Archive inputs must remain regular files from preview through descriptor admission; POSIX opens are no-follow and nonblocking, so a FIFO swap cannot stall before deadline checks resume. A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline. Non-mutating work rejects promptly when the budget expires. If a live destination mutation is already in flight, rejection waits only for that mutation and any rollback to finish; no later destination mutation can begin.
 
+The destination merge is nontransactional: each file is published atomically,
+but completed files and directories can remain when a later copy, post-copy
+check, mode application, or deadline fails. This also applies to
+`mergeExtractedTreeIntoDestination()`. Guarded `Root.copyIn()` owns cleanup for
+its operation; the archive merge does not unlink the current destination name
+on error because it has no publication receipt proving ownership. A failure
+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
+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
+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.
+
 ### Limits
 
 ```ts
@@ -453,9 +502,9 @@ The archive subpath also exports the helpers `extractArchive` is built on. Most
 | `withStagedArchiveDestination(opts)` | Creates a private staging dir outside the destination, calls your `run(stagingDir)`, then cleans it up. |
 | `mergeExtractedTreeIntoDestination(opts)` | The merge step alone — staged tree → destination through boundary checks. |
 | `prepareArchiveDestinationDir(destDir)` | Canonicalizes and asserts the destination directory. |
-| `prepareArchiveOutputPath(opts)` | Resolves a single entry's output path against the staging dir. |
-| `loadZipArchiveWithPreflight(opts)` | Loads a JSZip with size/entry-count preflight before unzipping. |
-| `readZipCentralDirectoryEntryCount(path)` | Returns the entry count from a ZIP's central directory without reading any payloads. |
+| `prepareArchiveOutputPath({ destinationDir, destinationRealDir, relPath, outPath, originalPath, isDirectory, deadline? })` | Validates and prepares parents for an already-resolved entry output path. |
+| `loadZipArchiveWithPreflight(buffer, limits?)` | Loads a JSZip from a `Buffer` or `Uint8Array` with size/entry-count preflight before unzipping. |
+| `readZipCentralDirectoryEntryCount(buffer)` | Returns the entry count from an already-loaded ZIP `Buffer` or `Uint8Array` without decoding payloads. |
 | `createTarEntryPreflightChecker(opts)` | Returns a per-entry checker for use as a `tar.x` `onReadEntry` hook. |
 
 These let you build custom extractors that share the same safety machinery — for example, a streaming uploader that wants to refuse archives with too many entries before reading any payloads.
@@ -477,7 +526,7 @@ import {
 - `validateArchiveEntryPath(raw, opts)` — throws `ArchiveSecurityError` for `..`, absolute, NUL-containing, drive-relative, or otherwise unsafe entry paths, including alternate data stream names on Windows.
 - `normalizeArchiveEntryPath(raw)` — converts backslashes in the entry path to forward slashes.
 - `stripArchivePath(entryPath, n)` — normalize separators, drop empty and `.` components, then strip the leading N components, returning `null` if none remain.
-- `resolveArchiveOutputPath({ destDir, entryPath })` — combines the entry path with the destination, after validation.
+- `resolveArchiveOutputPath({ rootDir, relPath, originalPath, escapeLabel? })` — combines the validated relative path with the root and rejects escapes using the original archive path for diagnostics.
 - `isWindowsDrivePath(value)` — detects drive-relative segments such as `C:secret` or `nested/C:secret` that should be rejected.
 
 Validate attacker-controlled paths before calling normalization or stripping

package/docs/atomic.md

@@ -184,7 +184,9 @@ an identity-bound process-exit cleanup retry.
 On POSIX, staged directory modes are applied through no-follow directory
 descriptors; on Windows, Node cannot portably open those descriptors and no
 pathname `chmod` fallback is attempted, so directory modes remain subject to
-Windows' `mkdir(mode)` behavior.
+Windows' `mkdir(mode)` behavior. Symlink sources are copied as links rather than
+followed, including when the referent is absent; only a source proven to be a
+directory is dereferenced for the destination-descendant guard.
 
 ```ts
 import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
@@ -207,7 +209,45 @@ the preflight cap fails with `FsSafeError("too-large")`.
 If another writer changes source entries during the fallback, the staged copy
 throws `ESTALE` before commit when possible. If the destination has already
 been committed, cleanup still preserves the changed source entries and throws
-`ESTALE`.
+`ESTALE`. When allowed source names are hardlinks to the same inode, each owned
+unlink is verified through a remaining manifested alias and its exact resulting
+identity becomes the next cleanup receipt. This accounts for the operation's
+own link-count and ctime changes without suppressing unexpected external
+mutations.
+
+### Final rename authorization
+
+Pass `assertBeforeRename` when a move depends on a revocable lease or another
+caller-owned authorization. The helper captures this callback when called and
+runs it synchronously after asynchronous preparation and directory checks,
+immediately before each rename is dispatched:
+
+```ts
+type MovePathWithCopyFallbackOptions = {
+  from: string;
+  sourceHardlinks?: "allow" | "reject";
+  to: string;
+  assertBeforeRename?: () => void;
+};
+```
+
+Throw to refuse publication. The original error is propagated, including errors
+with `EXDEV` or `EPERM` codes; an authorization failure never starts a copy
+fallback. A genuine rename failure may still require a second authorization
+check before publishing the staged copy.
+
+The callback must return `undefined` synchronously. Returning a Promise, thenable,
+or any other value refuses the rename with a `TypeError`; rejected asynchronous
+results are consumed without authorizing the operation. Perform asynchronous
+policy checks before calling the helper and use this callback to recheck the
+current owner at the mutation boundary.
+
+A refused rename leaves the source and destination unchanged; any private
+staged copy follows the helper's normal cleanup. The check does not cancel an
+already-dispatched rename or make an external lease store atomic with the
+filesystem. Cleanup after a successful move retains the existing source-identity
+checks. Omitting the
+callback preserves the usual move behavior.
 
 ## Difference from `root()`
 

package/docs/contributing.md

@@ -35,6 +35,19 @@ pnpm test test/archive.test.ts
 
 Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
 
+Vitest timeouts do not cancel filesystem promises. Shared fixtures with expensive
+setup use `useSuiteFixture` from `test/helpers/suite-fixture.ts`: setup has a separate
+30-second hook budget, and teardown waits for tracked setup and test work before
+removing directories. Run shared-state corpora sequentially with a deadline per
+payload. Keep child-process liveness limits separate from fixture preparation.
+The Windows CI slow-copy proof runs the real package-copy process-exit test with a
+six-second copy delay, retaining its four-second child deadline:
+
+```bash
+pnpm build
+pnpm test --config scripts/slow-package-copy.config.ts
+```
+
 ## Checks
 
 Run the complete repository gate before handoff:

package/docs/durability.md

@@ -142,8 +142,9 @@ success. `parentReceipt`, when supplied, must name the target's direct parent.
 With a native binding, the copy fallback first attempts a copy-on-write clone
 (`fclonefileat` on macOS, `FICLONE` on Linux), then Linux
 `copy_file_range`, and finally the existing JavaScript byte loop. Every route
-creates the target exclusively, normalizes its mode to `0o600`, and goes
-through the same post-copy identity and SHA-256 fencing. Hashing uses an async
+creates the target exclusively, applies mode `0o600` through its owned
+descriptor independently of the process umask, and goes through the same
+post-copy identity and SHA-256 fencing. Hashing uses an async
 native task when available, so large verification reads do not occupy the
 JavaScript event loop.
 

package/docs/errors.md

@@ -116,7 +116,7 @@ type FsSafeErrorCode =
 | `helper-failed` | A native mechanism or multi-step operational helper failed. | Inspect `cause` and any operation-specific `details`; retrying may be unsafe if the operation partially completed. |
 | `helper-unavailable` | Required native binding could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
 | `insecure-permissions` | A secure file or path permission check found a mode/ACL that allows broader access than requested. | File or directory is group/world writable/readable; Windows ACL grants broad read. |
-| `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable. | Caller didn't validate input; input was a network path on Windows, a drive-relative segment in a portable relative path or store key, or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain legal POSIX drive-like names. |
+| `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable; a FileStore key used a noncanonical spelling. | Noncanonical FileStore aliases, backslashes, or complete parent segments; a network path on Windows; a drive-relative segment in a portable relative path or store key; or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain broader confined path compatibility, including legal POSIX drive-like names. |
 | `not-empty` | `remove()` on a non-empty directory. | Use `replaceDirectoryAtomic` or remove children first. |
 | `not-file` | Read or copy targeted a non-regular file, or a path walk found a non-directory ancestor. | Target was a directory, FIFO, socket, device, or an existing file was followed by another segment. |
 | `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). | Typical missing-file case. |
@@ -134,6 +134,8 @@ type FsSafeErrorCode =
 | `too-large` | A read or bounded walk exceeded its configured budget. | Caller gave a too-permissive file or traversal limit. |
 | `unsupported-platform` | Reserved compatibility code for a platform-specific operation. | No current public helper emits this `FsSafeError` code. Platform-specific APIs currently return a typed unsupported result or use `helper-unavailable`; keep the union member when exhaustively switching across supported package versions. |
 
+Secret writes reject invalid `mode` / `dirMode` values with `invalid-path` before directory creation. Existing secret directories with a mode different from the requested `dirMode` report `insecure-permissions` without chmod; a created directory whose descriptor ownership no longer matches its initializing effective user reports `not-owned`.
+
 Pathname `sha256File()` also reports `path-mismatch` when pre-open, descriptor,
 or current-path identity remains unknown after one bounded Windows retry, even
 if the file is benign. It never reopens to recover identity. Preview symlinks

package/docs/file-store.md

@@ -66,14 +66,36 @@ type FileStore = {
 
 `path()` returns the absolute path the store would use, after asserting it stays inside `rootDir`. Useful for logging or for handing to other libraries.
 
-Every `relativePath` is a portable store key, including keys passed to reads,
-`exists`, and `remove`. A segment with a Windows drive-relative spelling such
-as `C:name` (including an embedded segment such as `a/C:name`) throws
-`invalid-path` on every platform. This prevents a key created on POSIX from
-aliasing a different file when the store is moved to Windows. Colons elsewhere,
-such as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain valid.
-Keys with surrounding whitespace also throw `invalid-path`; the store never
-silently trims one caller-supplied key onto another key.
+Every `relativePath` is a portable store key. The same lexical policy applies
+to every keyed async and sync method, including reads, `exists`, `remove`,
+`path()`, and `json()` construction, with either `private: false` or `true`.
+Keys must use their exact canonical spelling; the store never trims, normalizes,
+or converts one caller-supplied key onto another:
+
+- Keys are nonempty NFC Unicode strings without surrounding whitespace or NUL.
+- Segments are separated by a single forward slash. Empty segments, repeated or
+  trailing slashes, and complete `.` or `..` segments are rejected, including
+  `./b`, `a/./b`, and `a/../b`.
+- Every backslash is rejected on every platform, including a literal POSIX
+  `a\b` filename. POSIX and Windows absolute, rooted, UNC, and extended paths
+  are rejected.
+- Windows drive-relative segments such as `C:name` or `C:` are rejected
+  anywhere in a key, including `a/C:name`.
+- No segment may end in an ASCII dot or space.
+
+Violations report `invalid-path` when key validation is reached. Ordinary nested
+keys, NFC Unicode such as `café/日本語.txt`, `.hidden`, `a..b`, and internal spaces
+such as `internal space/a b.txt` are accepted. Colons elsewhere, such as the
+timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid; filesystem
+success still depends on the platform and the underlying Root policies.
+
+Validation retains each method's operation order. Async reads, `exists`, and
+`remove` open the root first: if the root is missing, strict methods report
+`not-found` and `readTextIfExists` / `readJsonIfExists` return `null`, even for an
+invalid key. With an existing root, those same invalid keys report `invalid-path`.
+Private `copyIn` checks and reads its source before validating the destination
+key, and `writeJson` serializes its value before validating the key. Key rejection
+therefore does not imply that no filesystem access or serialization occurred.
 
 `root()` returns a [`Root`](root.md) handle for the same directory when you need the full surface (move, list, mkdir). It's a fresh handle per call and is safe to call frequently.
 
@@ -187,6 +209,14 @@ Symlinks are skipped. The walk is best-effort — failures on individual entries
 
 If you need richer ops (move, list, append, mkdir), call `store.root()` to get a `Root` and use that.
 
+`FileStore` owns portable key identity; `Root` owns filesystem confinement.
+Existing-object Root lookups intentionally retain broader confined path
+compatibility, including in-root absolute paths and parent-segment spellings,
+and literal backslashes on POSIX. FileStore rejects those spellings even when
+Root could resolve them safely inside the directory. This key policy does not
+change Root's containment checks or the absolute-path `jsonStore({ filePath })`
+contract.
+
 ## Common patterns
 
 ### Cache with TTL prune

package/docs/local-roots.md

@@ -66,9 +66,10 @@ console.log(r.root); // canonical /srv/uploads
 By default the candidate must exist. `allowMissing: true` instead canonicalizes
 the nearest existing ancestor and validates the missing tail, which is useful
 when selecting a future output location. `requireFile: true` rejects existing
-directories and other non-file leaves. Dangling symlinks and candidates whose
-ancestors cannot be canonicalized are rejected rather than treated as safe
-missing paths.
+directories and other non-file leaves. A missing suffix begins only at a
+component that does not exist: dangling symlinks, descendants of dangling
+symlinks, and candidates whose existing ancestors cannot be canonicalized are
+rejected rather than treated as safe missing paths.
 
 ## `readLocalFileFromRoots(options)`
 

package/docs/output.md

@@ -60,7 +60,10 @@ hazards but does not trim Windows-normalized trailing dots or spaces; reject or
 rewrite those when cross-platform filename uniqueness matters.
 `staging: "workspace"` passes the sanitized basename to the producer.
 `staging: "sibling"` embeds that basename in its randomized temporary name.
-The final target and returned `path` use the destination basename, sanitized
+When the complete temporary component would exceed 255 bytes under NFC or NFD,
+only the embedded tail is shortened, preserving its extension when possible;
+short callback paths remain unchanged. The final target and returned `path` use
+the destination basename, sanitized
 when needed as described above. Guarded temporary files used only inside
 fs-safe have independent names so their length does not grow with the
 destination basename.

package/docs/private-file-store.md

@@ -17,8 +17,17 @@ const loaded = await store.readJsonIfExists<State>("state.json");
 
 - Writes create parent directories at `0o700` and files at `0o600` unless you
   pass stricter `dirMode` / `mode` options.
-- Private-mode writes route through the secret-file atomic path, which refuses
-  symlink parent components and re-asserts mode after rename.
+- Async private-mode writes route through the secret-file atomic path, which refuses
+  symlink parent components and re-asserts mode after rename. Existing directories
+  must already have the requested mode; writes do not repair their permissions.
+  New-directory initialization requires guarded descriptor authority and may
+  fail closed under restrictive platform/umask combinations; see the
+  [secret-directory policy](secret-file.md#parameters).
+- Locked JSON mutations prepare private directories before acquiring their
+  sidecar and bind the lock to the admitted parent identity. Lock normalization
+  is read-only: a deleted or replaced admitted parent is rejected, not recreated.
+  The writer still revalidates directory admission afterward; reads do not create
+  directories.
 - `readText()` and `readJson()` are strict and throw on missing files.
 - `readTextIfExists()` and `readJsonIfExists()` return `null` on missing files.
 - `write()`, `writeText()`, `writeJson()`, `writeStream()`, and `copyIn()` all

package/docs/reading.md

@@ -102,7 +102,9 @@ fs.readAbsolute(absPath, options?)   // ReadResult, abs path must be inside the
 fs.reader(options?)              // (path) => Promise<Buffer>
 ```
 
-`readAbsolute` accepts absolute paths. Anything outside the root throws
+`readAbsolute` accepts absolute paths using either the configured root spelling
+or its canonical real path. This includes roots configured through a directory
+symlink or Windows junction. Anything outside the root throws
 `outside-workspace`. It also accepts relative paths for compatibility, but use
 `read()`/`readBytes()` when the input contract is explicitly relative.
 

package/docs/regular-file.md

@@ -111,14 +111,28 @@ append boundary; rounded-equal replacements and persistent unknown Windows
 identities reject before chmod or writing bytes. With
 `rejectSymlinkParents: true`, it also rejects symlinked ancestor directories.
 
+On POSIX, `O_NONBLOCK` prevents a no-reader FIFO substituted before open from
+stalling admission. A confirmed non-regular target is refused before chmod or
+append; other open errors propagate unchanged. This safeguard does not change
+ordinary regular-file append semantics or require read permission.
+
+The requested mode is applied through the admitted descriptor **before** any
+content is appended, so an existing file is tightened first. On successful
+completion, explicitly requested POSIX special bits are reapplied after the
+content write, which can otherwise clear set-ID bits. An initial chmod failure
+leaves the content untouched; a write or final chmod failure can leave appended
+content and is not rolled back. Windows does not enforce POSIX mode semantics.
+
 ### `appendRegularFileSync(options)`
 
-Synchronous. Same options.
+Synchronous. Same options and mode ordering. Writes the complete input through
+the already-open descriptor, including when an individual write is short.
 
 ### `resolveRegularFileAppendFlags()`
 
 Helper that returns the append helpers' `O_WRONLY | O_APPEND | O_CREAT` flags,
-plus `O_NOFOLLOW` where the platform provides it:
+plus `O_NOFOLLOW` where the platform provides it and `O_NONBLOCK` on POSIX
+where available. Windows flags are unchanged:
 
 ```ts
 import { resolveRegularFileAppendFlags } from "@openclaw/fs-safe/advanced";

package/docs/root.md

@@ -87,8 +87,10 @@ await using opened = await fs.open("large.log");
 [security model](security-model.md#containment-guarantees-by-platform).
 
 The read methods also accept an absolute spelling that already resolves inside
-the root. `readAbsolute()` and `reader()` make that intent explicit; an absolute
-path outside the root is still rejected.
+the root. `readAbsolute()` and `reader()` make that intent explicit and accept
+both the configured root spelling and its canonical real path when the Root was
+created through a directory symlink or Windows junction. An absolute path
+outside the root is still rejected.
 
 ### Writes
 

package/docs/secret-file.md

@@ -123,7 +123,30 @@ startWebhookVerifier(signingKey);
 
 ### `writeSecretFileAtomic(params)`
 
-Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file at `mode` (default `0o600`), atomically renames over the destination, and re-asserts the file mode after rename.
+Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file, finalizes `mode` (default `0o600`) through an owned descriptor after content writes, and atomically renames over the destination. Publication verification checks the final file identity and mode.
+
+Concurrent writes to distinct leaves may share creation of a missing parent.
+After a parent-creation race, the helper re-inspects the entry and requires a
+non-symlink directory, then revalidates root/parent guards, containment, and
+the requested directory mode before writing either leaf.
+
+Publication verification borrows the writer's still-open descriptor to check
+the exact file identity, regular-file and link policy, requested POSIX mode,
+and root/parent ancestry before the writer closes it. All `0o7777` mode bits
+must match, including explicitly requested special bits; unexpected special
+bits are rejected. POSIX mode overrides such as `0o000` and `0o200` do not
+require read permission or a readonly reopen, and verification does not widen
+the final mode. Windows retains pathname-identity verification without enforcing
+POSIX mode bits; its native writer checks the reopened descriptor against the
+original lossless file identity before changing the final mode.
+
+Failed JavaScript fallback writes attempt cleanup while retaining the original
+descriptor and only after checking parent and file identities. Native cleanup
+also compares lossless parent and file identities. Unverifiable paths are left
+for caller-managed cleanup, and cleanup failures do not replace the original
+write error. These are best-effort identity checks followed by name-based
+removal, not atomic conditional unlink. A publication-verification failure
+after a completed write does not authorize deleting the published file.
 
 ```ts
 import { writeSecretFileAtomic } from "@openclaw/fs-safe/secret";
@@ -147,7 +170,15 @@ type WriteSecretFileParams = {
 };
 ```
 
-The directory mode is asserted on each component along the path: `rootDir`, then any intermediate dirs, then the parent. The helper enforces that every component matches `dirMode` — wider permissions on an existing directory cause the write to fail. Audit and tighten existing secret directories yourself.
+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.
+
+Both mode options must resolve to integers between `0o0000` and `0o7777`; invalid values fail with `invalid-path` before directory creation or file publication. Windows validates the options but does not enforce POSIX permission bits.
+
+After this operation wins directory creation, initialization uses a pinned descriptor bound to the admitted identity and effective user, with ancestor checks before chmod. It does not chmod the caller's pathname. Creation and descriptor admission are separate operations, not an atomic create-and-pin guarantee. A raced directory that has not reached its requested mode yet is rejected rather than repaired; callers may retry after its creator finishes initialization.
+
+Initialization fails closed if the platform cannot safely pin a created directory. In particular, a non-root macOS process cannot pin a new `000` directory produced by `umask(0o777)`; the write fails without repairing that directory or writing a secret. Restrictive masks retaining owner search permission remain usable. Linux x64/arm64 can use the guarded `O_PATH`/procfs descriptor route where available. There is no unguarded pathname-chmod fallback, and a failure may leave a created directory for caller-managed cleanup.
 
 ### `createSecretFileAtomic(params)`
 
@@ -157,6 +188,10 @@ if anything already occupies the target path it throws
 `FsSafeError("secret-exists")` without modifying that entry. Use the distinct
 name when first-writer-wins is part of the credential protocol.
 
+Distinct leaves can share missing-parent creation without a `secret-exists`
+error. Concurrent creates at the same leaf still have exactly one winner;
+the loser receives `secret-exists` and leaves the winner's bytes intact.
+
 For example, two onboarding requests may race to install the first refresh
 token. Exactly one should win, and the loser must not overwrite it:
 

package/docs/sidecar-lock.md

@@ -21,7 +21,9 @@ try {
 
 The lock file sits next to the protected resource. If a process crashes mid-lock, the next acquirer notices the held entry, inspects its payload (PID, host, acquired-at timestamp), and decides — via `shouldReclaim` (defaulting to "is the lock older than `staleMs`?") — whether it should keep waiting or fail.
 
-The library installs a `process.on("exit")` handler that releases all currently-held locks synchronously, so well-behaved exits leave no stale sidecars. Crashed holders leave their sidecar behind; recover only after an application-owned liveness policy proves the holder cannot still be writing.
+On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their retained Root capability and ownership receipt. The synchronous `process.on("exit")` handler provides last-chance cleanup for raw locks and reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it.
+
+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.
 
 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.
 
@@ -94,10 +96,23 @@ type FileLockRetryOptions = {
 ```
 
 `payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
+
+The complete serialized sidecar must fit within 1 MiB (1,048,576 UTF-8 bytes),
+including pretty-printed JSON, newlines, and the internal ownership token's
+trailing whitespace. The limit counts bytes, not string characters. Oversized
+payloads reject with `FsSafeError` code `too-large` before sidecar creation or
+acquisition, without retrying serialization or reclaiming an existing sidecar.
+This bound applies to raw and Root-backed locks, both async and sync.
+
 Errors thrown by `payload`, its JSON serialization (including `toJSON`), or
 `parsePayload` propagate unchanged without retrying the callback. Rethrowing an
 error saved from an earlier filesystem operation does not grant retry authority.
-Retry counts must be non-negative safe integers. Retry factors and delays must be finite and non-negative, and when both delay bounds are provided `minTimeout` cannot exceed `maxTimeout`. `timeoutMs` accepts a finite non-negative deadline or positive infinity for an unbounded wait; invalid numeric values reject before filesystem acquisition starts.
+Retry counts must be non-negative safe integers. Retry factors and delays must be finite and non-negative, and when both delay bounds are provided `minTimeout` cannot exceed `maxTimeout`. `timeoutMs` accepts a finite non-negative deadline or positive infinity for no deadline; invalid numeric values reject before filesystem acquisition starts.
+Both async and sync locks enforce retry counts and deadlines independently: an
+explicit `retry.retries` still applies with `timeoutMs: Infinity`, and zero allows
+only the initial attempt. After process defaults are applied, an omitted retry
+count means unlimited retries, and an omitted or infinite timeout means no
+deadline. With neither budget bounded, contention can wait indefinitely.
 `parsePayload` replaces JSON parsing for legacy or custom sidecars. Its `unknown`
 result is passed to `shouldReclaim` and `shouldRemoveStaleLock`, allowing PID,
 process-start, argv, or role schemas to remain application-owned.
@@ -107,8 +122,11 @@ short teardown race after another holder unlinks it. Both async and sync locks
 retry that specific open denial at most eight times per acquisition, within the
 caller's retry/deadline budget. A parent-directory denial, a callback/read/stat
 failure, or exhaustion of either budget surfaces the original error; a denied
-open is not converted to `file_lock_timeout`. Retrying always requires fresh
-exclusive creation and grants no ownership or removal authority.
+open is not converted to `file_lock_timeout`. Root-backed async creation uses
+this same policy for the Windows fallback's exclusive-open denial, captured
+within that individual create call. A generic `Root.create()` error or an error
+replayed from an earlier call is not exclusive-open evidence. Retrying always
+requires fresh exclusive creation and grants no ownership or removal authority.
 
 ## Owner-scoped reentrancy
 
@@ -160,6 +178,15 @@ an existing `Root` capability. `lockPath` must resolve inside that root.
 Identity-conditioned removal remains the only release and reclaim deletion
 path.
 
+Async Root-backed acquisition normalizes the target's parent without creating
+it, checking the retained Root before and after normalization. A deleted or
+replaced Root fails before payload execution or held-entry reuse. Missing lock
+subdirectories are still created through `Root.create`, never by target-key
+normalization. The target is an arbitration key and may be outside the Root
+when an explicit in-root `lockPath` is supplied; normalization does not follow a
+target-leaf symlink. Non-Root acquisition retains its existing parent-creation
+behavior.
+
 An owner can finish releasing while another async acquirer inspects its record.
 Create-only Root writes do not open an existing record merely to inherit its
 mode. Once a pathname sample and opened descriptor agree, a failed acquisition
@@ -267,7 +294,7 @@ The sync payload, reclaim, and parsing callbacks must also be synchronous. This
 shape is appropriate for a short boot migration; it is a poor fit for a server
 request because retry backoff uses a blocking wait.
 
-If your process dies before `release()` runs and skips the exit handler, the sidecar remains. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed by default instead of deleting by path.
+If termination skips the relevant cleanup handler or cleanup fails, the sidecar remains. In particular, `process.exit()` skips asynchronous Root cleanup; await explicit release or drain during application-managed graceful shutdown. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed by default instead of deleting by path.
 
 ## `withFileLock` — common shape made one-liner
 

package/docs/store.md

@@ -70,7 +70,11 @@ entry for inspection.
 
 Loading serializes consumers for one ID through a sidecar lock, then creates `processingPath` with a no-replace hardlink and retires the source through a recoverable sibling record. Whichever producer generation occupies `.json` at the hardlink operation becomes the claim; a replacement published afterward remains pending. After a crash, `.processing` is retried before that pending replacement. Transfer locks are fail-closed and are never reclaimed automatically, so an operator must remove a proven-stale lock after a hard process crash. Acknowledgement atomically moves `.processing` through the short-lived `.delivered` marker, and existing delivered markers are cleaned during batch loading. `ackJsonDurableQueueEntry()` rejects while `.json` exists without a processing claim: callers that previously paired direct `readJsonDurableQueueEntry()` with acknowledgement must load through `loadJsonDurableQueueEntry()` before processing so acknowledgement is generation-bound.
 
-Queue and failed directory creation fsyncs every newly-created parent edge from the leaf toward the trusted root. Enqueue and migration writes fsync the temp file and parent; claim, acknowledgement, quarantine, delivered-marker cleanup, and retirement transitions fsync every affected directory and propagate real sync failures. A transition may already be visible when a post-mutation sync fails, so retry the same operation to complete its crash-recovery state; quarantine retries with only failed evidence resync that destination before repairing the vanished queue source.
+Queue and failed directory creation fsyncs every newly-created parent edge from the leaf toward the trusted root. Enqueue and migration writes fsync the temp file and parent; claim, acknowledgement, quarantine, delivered-marker cleanup, and retirement transitions fsync every affected directory and propagate real sync failures. A transition may already be visible when a post-mutation sync fails, so retry the same operation to complete its crash-recovery state. Acknowledgement retries resync the queue directory even when both `.processing` and `.delivered` marker names are already absent, before reporting completion or rejecting a newer pending generation; quarantine retries with only failed evidence resync that destination before repairing the vanished queue source.
+
+`writeJsonDurableQueueEntry()` and migrations share strict parent synchronization inside the atomic writer's retained descriptor and per-path serialization lifetime, followed by published-file identity verification. If sync fails after publication, the write rejects without rolling back the published JSON; retrying writes the entry again and must complete its own sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
+
+Batch loading skips invalid entry names, malformed, oversized, or unreadable entry content, and caller `read` callback failures. Initially unowned pending entries (hardlinks or unverifiable identities), symlinks, non-files, and absent pending entries are also skipped. Claim, transfer-lock, retirement, and migration write/publication/durability failures reject the batch with the original error, even if earlier entries succeeded. Migration in both loaders strictly syncs the parent directory after successful publication. Visible transitions and earlier processing claims remain for retry; a rejected batch does not acknowledge or roll them back.
 
 Failed destinations are create-only. Quarantine publishes the claimed file by hardlink, so the queue and failed directories must share a filesystem with hardlink support. If `failed/<id>.json` already exists, quarantine rejects while preserving both that earlier evidence and the current claimed entry instead of overwriting either file. The `read` callback continues to receive the logical `.json` path even though bytes are read and migrations are written through the claimed path.
 

package/docs/temp.md

@@ -345,7 +345,11 @@ If `replaceFileAtomic` does what you need, prefer that. Use
 the final destination still needs root-boundary checks.
 Its private workspace uses the same identity-aware directory cleanup as
 `tempFile()`: moving and replacing the workspace preserves the replacement.
-This workspace owns its contents, unlike the unadmitted sibling pathname above.
+The callback staging component is capped at 255 bytes under NFC and NFD by
+shortening only an overlong embedded destination tail, while preserving an
+extension when possible. Short callback paths and the final target stay
+unchanged. This workspace owns its contents, unlike the unadmitted sibling
+pathname above.
 
 ## Secure temp root
 
@@ -358,6 +362,20 @@ const tempRoot = resolveSecureTempRoot({ fallbackPrefix: "my-app" });
 // e.g. /tmp/my-app-501
 ```
 
+Consumers that only need this resolver can use the narrow package subpath:
+
+```ts
+import {
+  resolveSecureTempRoot,
+  type ResolveSecureTempRootOptions,
+} from "@openclaw/fs-safe/secure-temp-root";
+```
+
+This entry excludes the temp workspace and store implementations from the
+module graph, keeping the import closure small for browser-aware builds that
+shim or exclude Node built-ins. The resolver remains a Node filesystem API; the
+narrow entry does not make it runnable in a browser.
+
 ### Options
 
 ```ts

package/docs/writing.md

@@ -1,8 +1,16 @@
 # Writing
 
 The `Root` handle exposes a tight set of mutation verbs. Replacement writes
-(`write`, `create`, `writeJson`, `createJson`, and `copyIn`) publish with a
-sibling-temp commit so no half-written replacement appears at the destination.
+(`write`, `writeJson`, and `copyIn`) publish with a sibling-temp commit so no
+half-written replacement appears at the destination. Create-only writes
+(`create`, `createJson`, and `write` with `overwrite: false`) use sibling-temp
+staging with an atomic no-replace rename only on backends that provide one —
+the native binding, which `require` mode guarantees and `auto` mode uses when
+the binding loads. The pure-JavaScript fallback has no atomic no-clobber
+rename and does not stage: it claims the final name exclusively with `O_EXCL`
+and writes content in place, so a concurrent observer can see the new file
+before its content is complete. Use `require` mode when that visibility window
+matters.
 `append` and `openWritable` intentionally modify an opened file in place;
 `move`, `remove`, and `mkdir` mutate directory entries rather than file bytes.
 Each verb applies the boundary checks appropriate to its operation.
@@ -91,7 +99,13 @@ alone is never proof that the name still refers to the expected file.
 Don't-clobber variant of `write()`. Throws `already-exists` if the target is there.
 Create-only preflight preserves boundary, alias, hardlink, and type checks without
 opening an existing target to inherit its mode; a fresh file uses the requested
-mode or the normal new-file default.
+mode or the normal new-file default. When the native binding is in use
+(`require` mode, or `auto` mode with a successfully loaded binding), content is
+staged privately and published with an atomic no-replace rename, so the name
+never appears before its bytes. In the pure-JavaScript fallback the name is
+claimed exclusively first and content is written afterward, so observers can
+briefly see an empty file; failure cleanup removes a claimed file only when its
+identity is unchanged.
 
 ```ts
 try {
@@ -207,6 +221,13 @@ destination — there is no atomic-rename step. If you need both streaming and
 atomicity, write to a sibling temp yourself and rename when done; the
 [`atomic`](atomic.md) helpers can do this for you.
 
+On POSIX, existing-target opens use `O_NONBLOCK` as an admission safeguard so
+a no-reader FIFO cannot stall regular-file validation. This does not change
+ordinary regular-file write semantics. `replace` and `update` remain write-only
+opens, including for mode `0o200` files; replacement truncation happens only
+after type, identity, and boundary checks pass. Rejected existing paths are
+never cleanup-owned or unlinked.
+
 ## Write defaults vs per-call options
 
 Set `mkdir: true` once on `root()`; pass text encodings per call when needed: