@openclaw/fs-safe 0.18.2 → 0.20.0

package/docs/archive.md

@@ -211,6 +211,14 @@ loading, including failure. Public preflight still returns ordinary JSZip entry
 objects, with directory keys ending in `/` and recognizable symlink type bits.
 Compressed data is retained even for declared-zero entries, so an empty-size
 claim cannot bypass payload-size or CRC verification during extraction or reads.
+Extraction and bounded reads retain the admitted CRC and size independently of
+mutable decoder objects, so later decoder changes cannot redefine the expected
+payload integrity. Public preflight archives retain ordinary JSZip mutation
+and entry-reading behavior.
+Portable bounded reads select the admitted canonical name and reject a selected
+decoder entry that no longer belongs to that archive and name before reading its
+payload. Extraction retains the admitted names and physical order independently
+of later changes to the decoder's public `files` object.
 
 Within one ZIP entry, identical local and central name bytes reuse the same
 decoded validation. Unicode Path admission is shared only when both the raw names
@@ -238,6 +246,8 @@ directory paths. For example, `./pkg//state\cache/value` is presented as
 `pkg/state/cache/value`, even with `stripComponents: 1`. Case and Unicode
 spelling are preserved. Local PAX `path`, GNU long-name, and supported ZIP
 Unicode Path names use the same canonicalization.
+A leading `~` is a literal archive entry name and is never expanded to the
+user's home directory during extraction, publication, or durability checks.
 Callbacks follow physical archive order, including ZIP names that look like
 integer object keys. The public ZIP loader's `files` object retains ordinary
 JavaScript object enumeration and mutation behavior.

package/docs/atomic.md

@@ -295,9 +295,9 @@ semantics. For single-file replacement, `replaceFileAtomic` is the right tool.
 
 Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
 temp file, descriptor-bound mode setting and fsync, rename, and parent fsync.
-It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
-you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
-or custom copy-fallback policy.
+It delegates to `replaceFileAtomic()` with a smaller call shape, including its
+pre-publication hook and staging-prefix options. Use `replaceFileAtomic()` when
+you need mode preservation or a custom copy-fallback policy.
 
 ```ts
 import { writeTextAtomic } from "@openclaw/fs-safe/atomic";
@@ -317,9 +317,17 @@ type WriteTextAtomicOptions = {
   dirMode?: number;          // parent mode (default 0o777 masked by process umask)
   trailingNewline?: boolean; // append "\n" if missing; default false
   durable?: boolean;         // default true; false skips temp/parent fsync
+  beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
+  tempPrefix?: string;       // default ".fs-safe-replace"
 };
 ```
 
+`beforeRename` is awaited after the complete text is staged and before
+publication, with the same [stage identity and refusal cleanup](#beforerename)
+checks as `replaceFileAtomic`. Pass `tempPrefix` to identify staged files; it
+uses the same prefix validation, including rejection of empty prefixes and path
+separators.
+
 `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.

package/docs/contributing.md

@@ -70,6 +70,36 @@ Consumers receive the asset in the npm package and need no compiler.
 
 Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
 
+### Linux GNU release bindings
+
+GNU x64 and arm64 artifacts use Zig 0.16.0 and `cargo-zigbuild` 0.23.4 with an
+explicit glibc 2.28 target, independent of the runner's libc. This matches the
+Node Linux runtime baseline and supports RHEL 8-family users without adding a
+second legacy package. Run the same build and ABI gate used in CI and releases:
+
+```bash
+cargo install cargo-zigbuild --version 0.23.4 --locked
+rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs x86_64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs aarch64-unknown-linux-gnu
+```
+
+These commands require Zig on `PATH` and GNU `objdump`. They build the N-API
+cdylib with `cargo zigbuild --target <triple>.2.28`, copy it to the existing
+`artifacts/fs-safe-native.<platform>.node` name, and reject any GLIBC symbol
+requirement above 2.28 before upload. The gate also rejects missing or unknown
+GLIBC versions. To inspect an existing binding, use
+`node scripts/check-linux-glibc.mjs <binding.node>`.
+
+`pnpm native:build` remains a host-toolchain development build; it does not
+establish the GNU release ABI floor.
+
+On Linux x64 with Docker, run `pnpm build`, copy the GNU x64 artifact from
+`artifacts/` to `native/`, run `node scripts/stage-host-native.mjs`, then run
+`bash scripts/test-linux-glibc-floor.sh`. CI uses this command to load the actual
+artifact and run native security and no-replace move tests in Rocky Linux 8
+(glibc 2.28). GNU arm64 is cross-built and symbol-checked in the same CI matrix.
+
 ## Test
 
 ```bash

package/docs/copy.md

@@ -74,6 +74,8 @@ Native Windows byte copies can store large zero-filled chunks as sparse ranges w
 
 The ReFS backend rejects files with alternate data streams and unsupported reparse-point types instead of silently losing their contents. Symbolic links and junctions are preserved.
 
+Failed ReFS clones attempt to remove their partial output through the retained directory handles. On Windows versions that reject the ignore-readonly deletion flag, clone rollback retries without that flag so ordinary output can be removed. It never clears readonly attributes: readonly output can remain, and the original clone error includes the cleanup failure. Other processes retaining output handles can delay deletion beyond settlement; a failed call does not guarantee an absent destination.
+
 XFS and ZFS preserve regular-file and directory modes, timestamps, extended attributes, and ACLs. They reject special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
 
 `readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.

package/docs/file-store.md

@@ -101,6 +101,11 @@ such as `internal space/a b.txt` are accepted. On POSIX, colons elsewhere, such
 as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid;
 Windows rejects that spelling as stream syntax.
 
+Keys such as `~` and `~/state.json` name literal entries inside the store; they
+do not expand the user's home directory. Reads, writes, removal, and pruning
+all use that literal identity. The `Root` returned by `root()` retains its own
+home-expansion behavior.
+
 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

package/docs/guest.md

@@ -119,7 +119,13 @@ publication failure preserves the existing destination and source link; ordinary
 failure cleanup removes the staging directory.
 
 Cross-device directory moves build a copy manifest and check it during source
-cleanup. Source changes can leave the published destination and some or all
+cleanup. Directory creation keeps the source mode subject to the guest's umask;
+mode `000` is not replaced with a default. A top-level mode-000 directory uses
+owner-only staging until publication, then restores zero through its retained
+descriptor. Reading a mode-000 source still requires sufficient OS privileges;
+the guest does not change source permissions to gain access. A permission error
+after publication preserves the source and published copy for reconciliation.
+Source changes can leave the published destination and some or all
 of the source. Regular-file and symlink move fallbacks unlink the source
 pathname after publication; they do not perform the directory manifest's
 identity checks. Directory cleanup also has check-to-unlink race windows.

package/docs/install.md

@@ -134,6 +134,16 @@ when the matching package is absent, incompatible, or disabled.
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.
 
+### Older Linux kernels and seccomp
+
+The native addon supports kernels without `openat2` (before Linux 5.6) and
+containers returning `ENOSYS` or probe-time `EPERM` for that syscall. Beneath
+opens use a guarded no-follow component walk and report `best-effort`.
+Nested no-clobber moves retain atomic `renameat2(RENAME_NOREPLACE)` and exact
+identity checks; keep native mode enabled. Strict bounded cleanup still
+requires `openat2` with `RESOLVE_NO_XDEV` and reports `helper-unavailable`
+without it. See [Linux capability behavior and limits](native.md#linux-without-openat2).
+
 ### Windows security fallback
 
 Windows raw owner/DACL inspection, private-directory creation, and secure-file
@@ -161,6 +171,24 @@ available native operation's error never triggers a command retry. See
 
 ## Native helper policy
 
+### Supported native platforms
+
+Prebuilt bindings cover Linux x64/arm64 (GNU glibc **2.28 or newer**, or musl),
+macOS x64/arm64, and Windows x64. The GNU baseline includes RHEL 8, Rocky Linux 8,
+and AlmaLinux 8. A compatible Node 22+ runtime and the kernel/filesystem features
+required by each operation are still necessary; a loadable addon alone does not
+guarantee every native capability. Systems older than glibc 2.28 are outside the
+GNU binary support floor.
+
+A missing or incompatible optional binding (including `ERR_DLOPEN_FAILED` from
+glibc) does not prevent importing fs-safe. In `auto`, supported JavaScript/WASM
+fallbacks remain available. Native-only operations such as the default
+no-clobber `Root.move()` still fail closed with `helper-unavailable`; `require`
+also rejects fallback-capable operations and retains the binding load error as
+the cause.
+
+### Loading modes
+
 The platform native binaries provide fd-relative open/link/mkdir primitives,
 atomic no-replace rename, and file identity checks. The default is `auto`: use
 the matching binary when it loads, otherwise use the guarded JavaScript path

package/docs/native-helper.md

@@ -103,10 +103,16 @@ clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor
 layer owns policy, retries, filters, budgets, modes, cleanup, error
 normalization, and the decision to fall back.
 
-- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Without `openat2`, beneath opens use the [no-follow component walk](native.md#linux-without-openat2) with exact identity checks and report `best-effort`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup still requires `openat2` with `RESOLVE_NO_XDEV` and fails closed when unavailable.
 - macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
 - Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
 
+Linux root lookups reject negative descriptor sentinels before borrowing a handle or resolving a relative path; they never substitute the process working directory for an admitted root. Public Root operations already supply retained, admitted handles.
+
+On Linux and macOS, native asynchronous file-copy admission rejects negative source and parent descriptors before creating a stage, preserving source-before-parent error ordering. Callers must keep nonnegative source and parent descriptors open until the operation settles.
+
+Low-level Unix query, hash, copy, clone, staging, and owned-tree cleanup calls also reject negative descriptors before using them, preserving each operation's path-validation, cancellation, and cleanup order. Descriptor-relative mutations never accept a working-directory sentinel as a retained capability. On modern macOS, beneath opens reject negative roots with `EBADF` before calling `openat`, rather than returning `EIO` after an OS failure or working-directory operation. This check does not establish the validity of arbitrary nonnegative integers: callers must supply live descriptors and retain them until synchronous calls return or asynchronous operations settle.
+
 `replaceDirectoryAtomic()` requires `renameNoReplaceWithIdentity` before it
 creates a missing target parent. On POSIX the dedicated entry point keeps the
 existing pre-dispatch exact receipt fence but dispatches direct-child names
@@ -133,11 +139,12 @@ for the exact difference.
 The guarded JavaScript mutation path is detection-based, not containment-atomic.
 If a same-privilege peer can replace a writable parent after its identity guard
 but before Node resolves a pathname mutation, the mutation can land outside the
-intended root before the post-operation guard throws. Select `require` rather
-than `auto` or `off` when that concurrent attacker is part of the threat model.
+intended root before the post-operation guard throws. Native `require` ensures the addon is present, but does not require a
+`kernel-atomic` resolver; inspect containment and use OS isolation when that
+concurrent attacker is part of the threat model.
 
 `openBeneath()` returns `{ fd, containment }`. `containment` is
-`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for the Linux fallback, macOS and
 Windows. Public JavaScript root open/read/writable results also expose the
 field and report `"best-effort"`; the label reports mechanism, not policy.
 

package/docs/native.md

@@ -43,6 +43,7 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
 - Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
   `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+  Without `openat2`, beneath opens use the [guarded fallback](#linux-without-openat2).
 - macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
   components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
   pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
@@ -85,6 +86,49 @@ privately owned empty ACL. Unsupported, malformed, and failed inspection is not
 reported as absence. These facts do not classify individual ACE permissions or
 prove volume ownership enforcement; each caller applies its own security policy.
 
+## Linux without openat2
+
+Linux kernels before 5.6 and containers whose seccomp policy denies `openat2`
+can keep native mode `auto` or `require`. The addon caches one harmless
+`openat2(".")` capability probe per process. `ENOSYS`, or `EPERM` on that probe,
+selects the native `openat` fallback. An `EPERM`/`EACCES` from an application
+operation is still a permission error and never triggers a retry. Install
+syscall filters before the first native operation; a later `ENOSYS` fails with
+`ENOTSUP`, rather than changing the cached mechanism during a call.
+
+The fallback opens each directory relative to a retained descriptor with
+`O_PATH | O_DIRECTORY | O_NOFOLLOW`, compares exact device/inode/type identities,
+and rechecks the retained parent chain before and after the final no-follow
+open. It rejects all symlink components, including procfs magic links, even
+when the low-level caller requests symlink following. Public Root policy and
+canonical-path admission, hardlink rejection, pinned-file checks, and mutation
+identity fences remain in place. `openBeneath()` reports `best-effort`: these
+identity samples detect replacements but cannot make a multi-component walk
+atomic against a hostile process renaming directories between samples. This
+is the same documented containment class as the macOS and JavaScript paths;
+applications requiring atomic beneath resolution must check the result or use
+OS isolation. Rejection after a mutating open does not promise rollback.
+
+Nested no-clobber `Root.move()` still admits both parents and uses
+`renameat2(RENAME_NOREPLACE)`. Existing destinations are never overwritten.
+That separate syscall/filesystem capability remains required; if unavailable,
+the operation fails with `helper-unavailable`. Turning native mode `off` still
+disables no-clobber moves because Node has no equivalent atomic rename API.
+
+Bounded owned-tree cleanup deliberately has no `openat` fallback:
+`RESOLVE_NO_XDEV` rejects bind mounts even when device numbers match, which
+ordinary identity checks cannot reproduce. `cleanupSafety: "require-bounded"`
+fails before workspace creation with `helper-unavailable`; low-level cleanup
+opens report `ENOTSUP`. Compatible cleanup retains its documented behavior.
+Low-level `O_TMPFILE` anonymous opens also fail before creation with `ENOTSUP`
+in the fallback, because named-entry identity checks cannot verify an unnamed
+file. Public staged-write APIs use exclusive named files and remain available.
+
+For tests, set `FS_SAFE_TEST_NO_OPENAT2=1` before starting Node to force the
+fallback (including bounded-cleanup refusal). It is read only at the first
+capability probe. It has no effect on macOS or Windows.
+See [Linux fallback testing](testing.md#linux-openat2-fallback).
+
 ## Archives
 
 Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
@@ -252,7 +296,7 @@ See [Root containment guarantees](security-model.md#containment-guarantees-by-pl
 
 | Capability | Native path | Guarded JavaScript path |
 |---|---|---|
-| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` on Linux and `best-effort` on macOS and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` with Linux `openat2` and `best-effort` with the guarded Linux fallback, macOS, and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
 | ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
 | Zstd/bzip2 TAR | Rust streaming decode and fd-relative output creation. | Bundled WASM codecs feed the shared Rust TAR parser, then guarded private staging and the same merge policy; no optional codec dependency. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |

package/docs/permissions.md

@@ -185,6 +185,72 @@ the same raw ACE projection. Native `require` rejects either absence with
 query's failure is terminal. The existing coarse `inspectPathPermissions()` API
 still owns its compatibility fallback and trust classification.
 
+### Asynchronous batches
+
+Use `readOwnerAndDaclBatch()` when several paths, such as a directory and its
+ancestors, need inspection without blocking the caller's event loop:
+
+```ts
+import { readOwnerAndDaclBatch } from "@openclaw/fs-safe/permissions";
+
+const facts = await readOwnerAndDaclBatch(stagingDirectories, { timeoutMs: 60_000 });
+```
+
+```ts
+function readOwnerAndDaclBatch(
+  paths: readonly string[],
+  options?: { timeoutMs?: number },
+): Promise<OwnerAndDaclResult[]>;
+```
+
+Results use the same raw fact shape and SID spelling as `readOwnerAndDacl()`.
+They correspond one-for-one to input order, including duplicate paths. An empty
+array returns `[]` without dispatch. Other platforms return an
+`unsupported-platform` result for each path. Query failures, malformed facts,
+or missing/reordered response rows reject the entire batch; no partial facts
+are returned. Null DACLs, incomplete ACE lists and nonlocal observations remain
+raw facts for the caller's policy to evaluate.
+
+The call captures paths, options and native mode before awaiting. Windows
+relative paths are anchored to the current directory or selected drive at
+entry, without normalizing their remaining `.` or `..` components. Empty,
+nonstring, sparse or NUL-containing path entries and Windows namespace aliases
+reject before dispatch. The UTF-8 JSON input is limited to 16 MiB.
+
+An available native capability runs all queries in one isolated process using
+the current runtime executable. Its resolved native mode is forwarded explicitly;
+Node preload and module-search environment overrides are not inherited. An
+available native query's failure is terminal. In `auto` when the binding or
+capability is absent, or in `off`, one packaged PowerShell process reads the
+path array from stdin and compiles the existing C# bridge once. Native `require`
+rejects missing support before launching a process. No route launches one
+process per path or wraps synchronous parent-process queries in promises.
+
+`timeoutMs` defaults to 60,000 and applies to the whole process, including
+startup and fallback compilation. It must be an integer from 1 through
+2,147,483,647. Combined stdout and stderr are limited to 16 MiB. Success waits
+for process exit and both output pipes to close. Timeout and transport failure
+request termination, then retain the existing one-second settlement grace.
+The error's `processExitConfirmed` field, also retained in its cause receipt,
+distinguishes observed exit from an unconfirmed termination attempt. An
+unconfirmed child can still be reading after rejection; the operation returns
+no facts and owns no output files or artifact cleanup. Neither timing out nor
+receiving a successful kill request is reported as confirmed exit.
+
+The PowerShell fallback encodes and budgets each result while collecting it,
+instead of retaining every descriptor graph until the entire batch finishes.
+An encoded response that would exceed 16 MiB rejects with `too-large` before
+inspecting later paths. A query failure observed earlier retains its original
+error, and no partial facts are returned. Duplicate paths remain independent
+observations. This bounds accumulated encoded results, not total process memory:
+the current descriptor and row, decoded input, and runtime overhead still exist.
+
+Batch observations are point-in-time pathname facts, not a snapshot or a
+retained filesystem capability. The caller still owns ancestry trust, principal
+policy and authorization for subsequent operations. Existing singular queries
+and other command operations retain their 30-second deadline, 1 MiB output
+budget and documented failure behavior.
+
 ## Private directories
 
 ```ts

package/docs/public-api.md

@@ -41,6 +41,11 @@ The lexical path surface additionally exports `isNodeError`,
 `UnsafeDeviceReadPathMatch`, `UnsafeDeviceReadPathOptions`, and
 `UnsafeDeviceReadPathReason`.
 
+`isPathRelativeEscape()` rejects absolute paths and relative paths that step
+above their starting directory at any point. Contained paths such as
+`dir/../file` remain relative. It accepts both separators on Windows; on POSIX,
+a backslash remains a literal filename character.
+
 The advanced root-file primitive exports `OpenRootFileParams`,
 `OpenRootFileSyncParams`, `RootFileOpenResult`, and
 `RootFileOpenFailureReason`. These are composition types for callers building
@@ -100,7 +105,8 @@ best-effort cleanup helper used by those queue flows.
 Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
 Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
 descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
-`WindowsAceFlags`.
+`WindowsAceFlags`. `readOwnerAndDaclBatch()` returns those same facts in input
+order through an isolated asynchronous batch with a whole-process timeout.
 
 Secure reads split their option and result shapes into
 `SecureFileTrustOptions`, `SecureFilePermissionOptions`,

package/docs/root.md

@@ -24,7 +24,7 @@ type RootDefaults = {
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
   mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append; default true
-  mode?: number;                   // file mode applied to new writes; per-call override available
+  mode?: number;                   // requested file mode; per-call override available
   nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
   renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
   symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // read policy
@@ -117,6 +117,10 @@ created through a directory symlink or Windows junction. An absolute path
 outside the root is still rejected. On Windows, alternate casing is accepted
 only when the differently cased Root prefix has the Root's exact directory
 identity; the operation then continues under the trusted Root spelling.
+Absolute paths keep literal `~` components: `readAbsolute("/srv/root/~/file")`
+reads that entry under the root, without expanding the user's home directory.
+Relative `~/file` inputs still expand the home directory and must remain inside
+the Root; use `./~/file` for a literal relative `~` directory.
 
 ### Writes
 
@@ -153,6 +157,11 @@ await fs.create("private-data/credential", "synthetic credential", { private: tr
 
 `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`).
 
+For `append` and `openWritable`, `mode` only affects new-file creation: POSIX
+permissions remain subject to the process umask. These methods do not chmod
+existing files. Replacement and create-only writes apply their final mode
+through the retained descriptor; see [Writing](writing.md#write-options).
+
 Buffered `create` and `createJson` also accept `atomic?: boolean`. With `true`,
 complete content is staged before exclusive publication even in native-off mode;
 the fallback requires hardlinks. Omitted or `false` keeps the existing buffered

package/docs/secret-file.md

@@ -228,6 +228,15 @@ 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.
 
+Its `durable` option also accepts `"file"`, matching `Root.create()`. This
+requires every file `fsync` to succeed, including on `EPERM`, while parent-directory
+synchronization remains best effort. The default and boolean options retain their
+existing behavior. `writeSecretFileAtomic()` continues to accept boolean durability.
+
+Strict file synchronization preserves the existing publication strategy and
+identity-checked cleanup. A failed file flush before staged publication prevents
+publication; a failure after publication can leave the complete file present.
+
 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.
@@ -244,6 +253,7 @@ try {
     rootDir: "/var/lib/app/credentials",
     filePath: "/var/lib/app/credentials/provider.refresh-token",
     content: refreshToken,
+    durable: "file",
   });
 } catch (error) {
   if (!(error instanceof FsSafeError) || error.code !== "secret-exists") throw error;

package/docs/security-model.md

@@ -232,13 +232,16 @@ The library does not modify or constrain the global Node.js `fs` namespace, and
 
 | Mechanism | Reported containment | Boundary |
 |---|---|---|
-| Linux native | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| Linux native with `openat2` | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| Linux native without `openat2` | `best-effort` | A no-follow `openat` component walk retains each parent and verifies exact identity associations before and after the final open; all symlink components are rejected. |
 | macOS native | `best-effort` | macOS 15.4 and newer use `O_RESOLVE_BENEATH` first; older kernels use the guarded `openat(O_NOFOLLOW)` component walk. Both verify the opened descriptor with `F_GETPATH`. |
 | Windows native | `best-effort` | Handle-relative `NtCreateFile` rejects reparse points, but this package does not claim a Linux-style atomic beneath guarantee. |
 | JavaScript fallback | `best-effort` | Canonical checks, no-follow opens where Node exposes them, and post-open identity checks form a check-then-use sequence. |
 
 The macOS `F_GETPATH` verification is an escape detector, not a race-atomic guarantee. A hostile same-UID process can rename a directory after `O_RESOLVE_BENEATH` or the manual walk and race the post-open sample or a later descriptor-relative mutation. The native result therefore remains `best-effort` on macOS even when the kernel flag is available. No policy decision is attached to these labels; callers can inspect the fact and decide what their own threat model requires.
 
+The Linux fallback's identity checks are also detection-based: a directory can be renamed between chain samples or before a later descriptor-relative mutation. It cannot provide atomic resolution, and rejection after a mutating open does not promise rollback. See [Linux without openat2](native.md#linux-without-openat2) for the cached capability probe, conservative symlink rejection, and operations that remain unavailable.
+
 The public `OpenResult`, `ReadResult`, and `WritableOpenResult` expose `containment`. Those root APIs currently report `best-effort`; direct native `openBeneath()` reports the platform value above. No-replace publication uses `renameat2(RENAME_NOREPLACE)` on Linux, `renameatx_np(RENAME_EXCL)` on macOS, and `FileRenameInfoEx` with replacement disabled on Windows, but those separate mutation semantics do not upgrade an open result's containment label.
 
 ## Limitations to keep in mind

package/docs/sidecar-lock.md

@@ -63,6 +63,8 @@ Exit cleanup tolerates shared managers created by older package copies that lack
 
 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. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
 
+Last-chance raw-lock exit cleanup requires known Windows device and inode values from both pathname observations and the opened descriptor. A zero value leaves the sidecar in place, including for token-owned locks. Known descriptor/path identity differences remain supported; a pathname identity change during the read still prevents cleanup.
+
 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.
 
 `release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` or `withFileLockSync()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed asynchronous acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.

package/docs/staged-symlink.md

@@ -0,0 +1,123 @@
+---
+title: Retained symlink publication
+description: "Admit and retain an identified staged symlink for no-replace publication and explicit recovery."
+---
+
+# Retained symlink publication
+
+`retainSymlinkInDirectory()` from `@openclaw/fs-safe/advanced` admits an
+**existing** direct-child symlink against caller-captured identity, ownership,
+change time and target. It holds a no-follow descriptor to that inode and its
+parent until cleanup. It does not create a symlink or infer ownership from a
+same-target pathname observation. This dedicated lifecycle does not relax
+`Root.move()` or regular-file staging's symlink rejection.
+
+The caller owns staging and admission evidence. Create and inspect the stage
+under the application's cooperative writer lock, and keep that lock through
+admission. A historical stat is not a lifetime handle: if peers can recycle
+inodes between capture and admission, identity numbers alone cannot establish
+historical ownership. Once admitted, the retained descriptor prevents inode
+reuse until this owner closes. Failed admission closes descriptors without
+unlinking anything; all staging cleanup remains with the caller.
+
+Linux uses `O_PATH | O_NOFOLLOW`; macOS uses metadata-only `O_EVTONLY | O_SYMLINK`
+with nonblocking/no-controlling-terminal flags. A non-following preflight rejects
+observed special files before open; the opened descriptor must still match.
+Windows, native mode off, and missing or older bindings reject before namespace
+mutation. No fallback interpreter, copy, following open, or public descriptor
+is used. Symlinks must have one link and a UTF-8 target; their targets are never
+opened or confined by this API. The application must authorize the target.
+
+## Example
+
+```ts
+import {
+  retainSymlinkInDirectory,
+  type StagedSymlinkExpected,
+  type PublishedSymlinkReceipt,
+} from "@openclaw/fs-safe/advanced";
+import type { DirectoryReceipt } from "@openclaw/fs-safe/durability";
+
+// Application owns stage creation, capture, locking and transaction policy.
+export async function publishInstallerLink(options: {
+  directory: DirectoryReceipt;
+  stagedBasename: string;
+  expected: StagedSymlinkExpected;
+  finalBasename: string;
+  assertAuthorizedAndCurrent(): void;
+}): Promise<PublishedSymlinkReceipt> {
+  await using staged = await retainSymlinkInDirectory({
+    directory: options.directory,
+    basename: options.stagedBasename,
+    expected: options.expected,
+    assertBeforeMutation: options.assertAuthorizedAndCurrent,
+  });
+  return await staged.publish(options.finalBasename);
+}
+```
+
+`expected` requires exact bigint `dev`, `ino`, `ctimeNs`, integer `uid`
+and `gid`, and `target`. Admission snapshots these values and the parent
+receipt. The frozen returned receipt contains `directory`,
+`temporaryBasename`, `target`, and preparation-time `identity` metadata,
+like [regular-file staging](staged-file.md). Rename may change timestamps;
+the original receipt is never replaced by a post-publication identity.
+
+## Lifetime and outcomes
+
+- `assertCurrent()` checks the admitted parent pathname, original name, retained
+  inode, single-link count, ownership, mode and target before publication.
+- `publish(basename)` accepts a distinct portable direct-child name. It performs
+  the synchronous authority assertion, rechecks source and parent, and dispatches
+  guarded native no-replace rename. An existing file, symlink or directory is
+  never overwritten, and the link is never nested inside a destination directory.
+- Successful dispatch is recorded as `published` **before** fallible postchecks.
+  A foreign same-target replacement fails verification without becoming owned.
+  `assertPublished()` checks against the still-retained inode.
+- `removePublished()` is an explicit recovery action, not automatic rollback.
+  It reasserts authority and removes only an observed matching published link
+  through the retained original parent. It returns `removed`, `name-absent`,
+  or `preserved`. Its outcome or error is cached: it never retries an uncertain
+  unlink or touches a later replacement. It does not restore an old destination.
+- `cleanup()` removes only an unattempted, still-owned stage, then closes both
+  handles. Published names are preserved. Indeterminate publication preserves
+  both names. Authority rejection during cleanup preserves the stage and still
+  closes handles. Repeated cleanup replays the cached result/error without
+  touching descriptor numbers.
+- `await using` invokes cleanup and raises on a `preserved` outcome. Invocation
+  order serializes descriptor work; reentrant calls from the authority callback
+  reject. Callbacks must be synchronous; returned thenables are refused.
+
+Errors carry `StagedSymlinkFailureDetails` in `FsSafeError.details`: the phase,
+recorded `publication`, and a cleanup receipt when applicable. Publication is
+`not-published`, `published` (with the precaptured receipt), or
+`indeterminate` (with the attempted name). Native errno, including a collision,
+does not rule out a committed remote rename whose response was lost. Only
+pre-dispatch rejection leaves publication `not-published`. After an indeterminate
+result, this owner cannot publish again or remove the possibly published name.
+If inspecting a native rename error itself fails, publication is likewise
+`indeterminate`; the original thrown value remains the reported cause.
+
+Cleanup records `temporaryBasename`, `publication`, `resources`
+(`closed` or `close-failed`), and `status` (`removed`, `name-absent`,
+`preserved`, `failed`, or `not-needed`). Failure closes every retained handle
+once and aggregates cleanup/close errors. A failed explicit recovery unlink is
+reported to its caller and is not converted into successful recovery by cleanup.
+Thrown values whose error metadata cannot be inspected are reported as
+`helper-failed` with the original value as `cause`; cleanup and recovery still
+cache their terminal error without retrying callbacks or descriptor closes.
+
+## Limits
+
+This is directory-relative targeting, **not CAS**. Identity checks followed by
+rename or unlink are not atomic conditional mutations. An uncooperative writer
+can replace a child in the final syscall gap; observed substitutes are preserved,
+but callers must coordinate writers to exclude that gap. The retained parent
+prevents redirection into a replacement parent; a parent move can still cause
+publication in the moved original and a `published` postcheck failure.
+
+No receipt promises crash durability or recovery after process death, arbitrary
+renames, permission revocation or I/O failure. This API does not sync directories
+or persist descriptors. Caller journals, state capture, conditional restoration,
+durability, and transaction settlement remain separate requirements. Keep the
+owner alive until the application's publication or recovery decision settles.

package/docs/store.md

@@ -62,7 +62,9 @@ const pending = await loadPendingJsonDurableQueueEntries({ queueDir, tempPrefix:
 
 `id` must be a single safe path segment: non-empty, not dot-prefixed, and made
 from letters, numbers, `_`, `-`, and `.`. Slashes, backslashes, NUL bytes, `.`,
-and `..` are rejected.
+`..`, and Windows reserved device names such as `CON`, `NUL`, and `COM1` are
+rejected on every platform so queue IDs remain portable. Temporary filenames
+continue to suffix reserved stems (for example, `CON.txt` becomes `CON_.txt`).
 
 Use `ackJsonDurableQueueEntry()` after durable processing succeeds and
 `moveJsonDurableQueueEntryToFailed()` when the caller wants to quarantine an