@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/docs/creation.md

@@ -0,0 +1,132 @@
+# Exclusive leaf creation
+
+The creation-policy work is tracked in [#482](https://github.com/openclaw/fs-safe/issues/482).
+
+Use `createDirectory()`, `createDirectorySync()`, and `createFileSync()` from
+`@openclaw/fs-safe/advanced` when an existing, trusted parent should receive
+one new entry. These operations are exclusive and nonrecursive: an existing
+entry throws `FsSafeError("already-exists")`, and missing parents are not
+created. They do not repair or adopt an existing destination. `Root.mkdir()`
+continues to own recursive, idempotent directory creation within a Root.
+
+```ts
+import {
+  createDirectorySync,
+  createFileSync,
+} from "@openclaw/fs-safe/advanced";
+import fs from "node:fs";
+
+createDirectorySync("/trusted/application/new-state", { private: true });
+using file = createFileSync("/trusted/application/new-state/initial.db", {
+  private: true,
+});
+fs.fsyncSync(file.fd);
+```
+
+Both directory variants return `void`; `createFileSync()` returns an empty,
+read/write descriptor owned by `OwnedFileDescriptorSync`, with
+`{ fd, close(), [Symbol.dispose]() }`. Use the
+owner to close it, rather than calling `fs.closeSync()` yourself. Closing and
+disposal are idempotent; a failed close is not retried through a descriptor
+number that might already have been reused. File creation does not write
+payload data or request file or parent-directory synchronization.
+
+## Permission options
+
+`CreateDirectoryOptions` and `CreateFileOptions` both support `private?: boolean`
+for private creation. `mode?: number` selects permission
+bits; invalid values and private requests with group/world or special bits
+reject before mutation. Restrictive owner-only modes remain restrictive.
+Without `private`, ordinary Node defaults and the process umask apply. Private
+POSIX creation requests `0700` for directories and `0600` for files by default;
+the umask may restrict those permissions further. Existing directory privacy
+checks never broaden permissions.
+
+Private POSIX `Root.create()` and `createJson()` writes check the retained descriptor's actual owner and
+permissions before writing payload bytes, after producer and authority callbacks,
+and at publication, including JavaScript fallback writes. Payload writes require
+the temporary `0600` mode even when the requested final mode differs.
+Private ownership, permissions and ACLs are checked before preparing that mode,
+including after authority callbacks; valid restrictive initial modes remain supported.
+A successful `chmod` is insufficient: filesystems that do not
+enforce owner-only permissions reject before payload writes. The requested final
+mode is verified too; a failure after publication preserves the completed file
+and staged creation reports its published outcome.
+
+On macOS (Darwin), private creation also requires an ACL-free result. The native
+helper must provide `inspectDarwinAcl`; native `off`, a missing helper, or an
+older helper without that capability rejects with `helper-unavailable` before
+creating parents or staging entries. There is no system-command fallback for
+Darwin private creation. Operations without `private: true` keep their existing
+native-mode behavior.
+
+Private Darwin directories must retain owner-read or owner-search permission
+after applying the umask so their ACL can be inspected. Modes `0000` and `0200`
+reject with `helper-unavailable` before directory creation. Existing private
+directories with neither permission also reject with `helper-unavailable`;
+permissions are never broadened to inspect them. Modes `0100`, `0300`, and `0400`
+remain supported, as does the default `0700`. Private files with mode `0000`
+remain supported because inspection uses the owned creation descriptor.
+
+Before creation, the parent ACL is inspected for entries that could be inherited
+by the new directory or file, as applicable. Relevant inheritable entries reject
+creation. Noninheriting parent ACLs, such as the usual macOS home-directory
+deny-delete entry, do not reject child creation. Created directories and files
+are checked for owner-only permissions and no ACL before admitting the directory
+or allowing payload writes. An existing directory requested with `private: true`
+must also be owned by the current user, have owner-only permissions, and have no
+ACL. These checks never clear an ACL after creation or repair an existing entry.
+
+On Windows, mode bits alone do not establish privacy. Private creation uses a
+protected current-user, LocalSystem and Administrators DACL. A private staging
+directory supplies trusted-only inheritable permissions before Node creates
+the file. The original Node descriptor stays pinned while its full Windows
+identity is compared with a security handle before the file DACL is protected.
+An already broadly accessible file is rejected, not repaired. Keep the trusted
+parent ancestry and staging directory ACL protected from untrusted changes;
+post-operation checks do not make pathname-based fallback operations atomic
+against an adversary who can change that namespace.
+
+The internal async writer awaits system commands, file opens and closes, and
+security verification. It does not wrap the synchronous creator in a promise.
+Short identity checks and the existing guarded link/unlink critical sections
+remain synchronous.
+
+Private Windows file publication retains the same inode and never overwrites
+an existing destination. The current implementation requires hardlinks on the same
+local filesystem. Unsupported filesystems reject with `helper-unavailable`;
+there is no copy-to-destination fallback. On Windows the owner overlaps a
+verified destination descriptor with the creation descriptor before removing
+the temporary name. Requested read-only attributes are finalized through the
+retained destination descriptor after that handoff.
+
+On Windows, native `auto` uses available capabilities; native `off` and
+missing-capability `auto` use the packaged system-command security bridge. Native `require`
+rejects unavailable required capabilities instead of starting a command. The
+private-file capability check runs before creating parents or staging entries;
+directory-only operations require only their directory capabilities. The
+[Windows security fallback prerequisites](install.md#windows-security-fallback)
+apply. All command mutations report unconfirmed outcomes when their reply or
+termination cannot establish completion.
+
+## Authority and failure outcomes
+
+`assertBeforeMutation?: () => void` is a synchronous current-authority check.
+It runs after preparation and immediately before creation or publication;
+thenables reject before mutation. Parent and file identity checks are repeated
+after the callback. Final permission checks, descriptor settlement and cleanup
+retain the operation's cleanup ownership after publication.
+
+Failure does not always mean the final path is absent. Staged private-file errors
+after publication or ambiguous publication preserve the destination and carry
+`details.publication.status` (`published` or `indeterminate`), the target path and
+staging cleanup outcome. Cleanup and close failures retain the original error
+in the cause chain. When `stageDirectory` is present, `cleanup` describes that
+stage's settlement; it does not mean the published destination was removed.
+If a directory is created but its subsequent admission fails, the error records
+its published path and preserves it. A private file whose staging directory
+cannot be admitted reports `not-published` and identifies the preserved stage.
+Observed replacement paths are preserved. Existing
+`createPrivateDirectory()` retains its Windows-only compatibility contract;
+new portable callers should use the ordinary creation operations with
+`private: true`.

package/node_modules/@openclaw/fs-safe/docs/durability.md

@@ -69,6 +69,49 @@ descriptor, pathname identity, and canonical path. `assertCurrent()` repeats
 those checks. This prevents a pathname replacement from turning a later sync
 into proof for a different directory.
 
+Pathname and descriptor checks compare exact bigint device and inode values.
+Each inspection allows one retry for unknown Windows identity components,
+retaining known components and rejecting definite mismatches immediately.
+Persistent unknown identity fails closed with `path-mismatch`, including on an
+otherwise usable directory. A failed preflight identity check never syncs the
+descriptor; a replacement discovered after sync still rejects the operation.
+
+`DirectoryReceipt.identity` remains a numeric Node `Stats` object for metadata
+compatibility, projected from the same exact observation as the private
+identity. Library-created receipts and their identity objects retain a
+private exact snapshot; mutating their public fields cannot change the
+directory authorized by that snapshot. Each returned receipt owns a mutable
+numeric metadata copy. Later admissions retain the original metadata snapshot
+even if advisory fields such as mode or timestamps were edited; changed paths
+or identity components reject. Pass the receipt or its original
+identity object through to later operations to retain this evidence. A copied
+or reconstructed numeric identity is accepted only when both components are
+safe integers and, on Windows, nonzero. Rounded or unknown caller identities
+fail with `path-mismatch` rather than authorizing a different directory.
+
+Caller-supplied receipts may use `DirectoryReceipt<BigIntStats>` with the result
+of `lstat(path, { bigint: true })`. `pinDirectory()`, `syncDirectory()`,
+`syncDirectorySync()`, `publishFileExclusive()`'s `parentReceipt`, and
+`stageFileInDirectory()` accept both numeric and bigint receipt inputs.
+`DirectoryReceipt` without a type argument and all returned durability receipts
+still expose numeric `Stats`, including working type predicates and Date
+properties. Bigint metadata is projected from the supplied observation, retaining
+fractional timestamps and the private exact device/inode identity.
+
+```ts
+import { lstatSync, realpathSync, type BigIntStats } from "node:fs";
+import { syncDirectorySync, type DirectoryReceipt } from "@openclaw/fs-safe/durability";
+
+const directoryPath = "/srv/backups/sqlite";
+const receipt: DirectoryReceipt<BigIntStats> = {
+  path: directoryPath,
+  realPath: realpathSync(directoryPath),
+  identity: lstatSync(directoryPath, { bigint: true }),
+};
+// Keep this receipt across the application's publication operation.
+const outcome = syncDirectorySync(receipt);
+```
+
 Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
 
 These checks intentionally reject a moved or replaced pathname. For one file's
@@ -94,6 +137,10 @@ accepted.
 `expectedExistingIdentity` binds an existing target to an identity observed by
 the caller before a separate permission or policy check. A missing or replaced
 target fails with `FsSafeError("path-mismatch")`.
+Use bigint `dev` and `ino` from `lstat(path, { bigint: true })` or
+[`readDirectoryIdentity()`](directory-identity.md) for caller-owned observations
+that may exceed the numeric safe-integer range. An original library receipt's
+`identity` object also retains its private exact identity for this option.
 
 ## Exclusive file publication
 
@@ -252,6 +299,11 @@ pathname without reopening the file and repeat the symlink and file-type checks.
 POSIX opens are nonblocking, so a raced FIFO or device is rejected after
 descriptor inspection rather than waiting for a writer.
 
+A pathname hash reports failure to close its owned descriptor after successful
+hashing. If hashing, admission, or cancellation already failed, that original
+failure remains primary even when close also fails. This also applies to
+`sha256FileSync()`; borrowed handles and descriptors remain caller-owned.
+
 When the optional binding is active, hashing runs as an async native task and
 does not occupy the JavaScript event loop with digest updates. With native mode
 `off`, or in `auto` when no binding loads, the fallback performs asynchronous
@@ -323,6 +375,13 @@ this receipt instead of inferring ownership from path existence. The original
 failure remains available as `cause`. Failures before target creation retain
 their existing error shape and do not claim a cleanup result.
 
+Source and target identities are checked again after successful or unsupported
+directory synchronization, while their descriptors remain owned. A late
+verification failure retains its strategy's verification phase and is not a
+directory-sync failure. Completed copied targets stay pinned during conditional
+cleanup; substituted entries remain untouched. Returned numeric metadata comes
+from the retained target descriptor and grants no continuing pathname authority.
+
 ### Directory-sync failure policy
 
 `onSyncFailure` applies only after target creation and content/identity fencing
@@ -377,3 +436,10 @@ owning product boundary.
 - [Migrating to 0.5](migrating-to-0.5.md) — choosing a publication policy during upgrade.
 - [Native architecture](native.md) — clone/copy/hash mechanisms and fallback guarantees.
 - [Errors](errors.md) — typed operational failure handling.
+
+## Existing Windows file retirement
+
+[`retainFileInDirectory`](retained-file.md) describes identity-bound native
+disposition and resource settlement separately from persistence. Its result is
+always `persistence: "not-proven"`; neither accepted disposition nor observed
+namespace absence is a directory/volume barrier or an application commit.

package/node_modules/@openclaw/fs-safe/docs/file-contents.md

@@ -0,0 +1,68 @@
+# Exact file comparison
+
+`sameFileContentsSync()` compares the bytes of two already-open regular files,
+starting at offset zero. It uses bounded buffers and completes positive short
+reads independently on each descriptor. A `true` result requires matching bytes
+and observed EOF on both inputs; a difference can return `false` immediately.
+
+```ts
+import fs from "node:fs";
+import { sameFileContentsSync } from "@openclaw/fs-safe/advanced";
+
+const source = fs.openSync("/trusted/source.sqlite", "r");
+try {
+  const copy = fs.openSync("/trusted/copy.sqlite", "r");
+  try {
+    console.log(sameFileContentsSync(source, copy, { maxBytes: 256 * 1024 * 1024 }));
+  } finally {
+    fs.closeSync(copy);
+  }
+} finally {
+  fs.closeSync(source);
+}
+```
+
+## Signature
+
+```ts
+type SameFileContentsOptions = { maxBytes?: number };
+
+function sameFileContentsSync(
+  leftFd: number,
+  rightFd: number,
+  options?: SameFileContentsOptions,
+): boolean;
+```
+
+Both descriptors must be open regular files. Nonregular inputs throw
+`FsSafeError("not-file")`; underlying filesystem errors propagate unchanged.
+Passing the same descriptor twice is allowed, but does not bypass validation,
+the byte limit, or reads. File sizes are checked against the limit, but are not
+used as proof that contents match or that EOF has been reached.
+
+## Bounds and ownership
+
+`maxBytes` is a limit for each file, not their combined size. It accepts a
+non-negative safe integer or `Infinity`; omission imposes no caller-selected
+limit. Invalid limits throw `RangeError` before filesystem work. Comparisons
+cannot exceed `Number.MAX_SAFE_INTEGER` bytes because positions must remain
+exactly representable.
+
+A reported file size above the limit throws `FsSafeError("too-large")` before
+reading. At the limit, the comparison reads at most one additional byte from
+each input to prove EOF; any observed overflow throws the same error. A
+matching prefix is never reported as complete equality. An early mismatch
+does not scan the remaining bytes or promise to detect later errors or growth.
+A zero-byte limit admits two empty files. Memory use is at most two 1 MiB
+payload buffers, regardless of file size.
+
+The operation neither changes the descriptors' current offsets nor closes
+them, including on failure. It performs no writes, hashing, pathname lookup,
+or identity comparison. Callers retain path admission, hardlink policy,
+descriptor lifetime, and any before/after mutation-fingerprint checks. A
+comparison is not a snapshot of concurrently modified files; applications
+requiring stable contents must retain their existing coordination and checks.
+
+Use [`readFileWindowFullySync()`](positional-read.md) for a selected byte
+window and [bounded descriptor reads](advanced.md#files-and-identity) when the
+caller needs the file contents in memory.

package/node_modules/@openclaw/fs-safe/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
@@ -133,6 +138,13 @@ the published entry intact for caller-owned recovery. Ordinary write-only and
 mode-000 outputs do not require a readable descriptor when pathname metadata is
 available.
 
+If a synchronous write operation and its final temp-descriptor close both fail,
+the store reports them in operation-then-close order in an `AggregateError`.
+This ordering and the original JavaScript thrown value are preserved even when
+that value is `undefined` or otherwise falsy. An unsuccessful best-effort temp
+unlink remains registered for identity-checked process-exit cleanup; it does not
+prevent the close attempt or replace either reportable failure.
+
 If an opaque pathname cannot be reopened because of an ACL denial or sharing
 restriction, the synchronous writer intentionally rejects with `path-mismatch`:
 its exact publication identity cannot be verified. There is no equal-content
@@ -219,6 +231,14 @@ with the same precedence as `write`.
 
 Per-call overrides for the store-level defaults:
 
+Writes capture byte limits, modes, and durability before asynchronous work or
+stream consumption. JSON writes capture those fields and the trailing-newline
+setting before serialization. Later mutation cannot change those captured values.
+Accessors run on the original options object. Ordinary writes retain content
+conversion and byte-limit validation before reading modes and durability.
+The legacy non-private stream `tempPrefix` accessor still runs after staging;
+it does not control the publication policy.
+
 ```ts
 type FileStoreWriteOptions = {
   durable?: boolean;   // store default, otherwise true
@@ -283,6 +303,10 @@ refreshes are preserved; replacements that are themselves expired remain
 eligible. This does not require read permission. The existing best-effort
 external-process race window after dispatch still applies.
 
+Empty-directory pruning likewise rechecks that the selected entry is still a
+directory immediately before guarded removal. File and symlink replacements
+are preserved, and a directory that becomes nonempty is left in place.
+
 ## Difference from `Root`
 
 | `FileStore` | `Root` |

package/node_modules/@openclaw/fs-safe/docs/guest.md

@@ -80,7 +80,7 @@ disables. Do not omit required fields.
 | Rename | `rename srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Rename with cross-device copy/delete fallback. |
 | Remove | `remove root parent basename recursive force` | Removes the leaf, or recursively removes its tree. |
 | Make directories | `mkdirp root directory` | Creates missing relative directory components. |
-| List directory | `readdir root directory` | JSON array of `{ name, isDirectory }`; no sorting guarantee. |
+| List directory | `readdir root directory` | JSON array of `{ name, isDirectory, isFile }`; both kind fields are false for symlinks and special entries; no sorting guarantee. |
 
 The complete program rejects empty, `.`, `..`, slash-containing, and NUL
 basenames before opening roots or creating parents. Both leaf operands of copy
@@ -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/node_modules/@openclaw/fs-safe/docs/index.md

@@ -65,6 +65,7 @@ await fs.remove("notes/archive/today.txt");
 | [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for private JSON/text state at 0600 under 0700 dirs. |
 | [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
 | [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
+| [`watch`](watch.md) | Guarded filesystem observation with advisory native hints and polling. |
 | [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
 | [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
 | [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |

package/node_modules/@openclaw/fs-safe/docs/install.md

@@ -119,24 +119,78 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 ## Runtime dependencies
 
-`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser for guarded JavaScript TAR/gzip [archive extraction](archive.md), including installs with optional dependencies omitted. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability.
+`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser and zstd/bzip2 codecs for guarded [archive extraction and bounded entry reads](archive.md). Plain TAR, gzip, zstd, and bzip2 work in `off` and missing-native `auto`, including installs with all optional dependencies omitted; gzip uses Node's built-in decoder. These archive fallbacks need no runtime interpreter, download, or consumer compiler. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability. Native `require` remains strict, and an available native operation's failure never triggers a WASM retry.
 
 There are no peer dependencies. Exact-version optional packages carry the seven
 native targets and npm-compatible OS, CPU, and Linux libc filters install only
-the matching binary. Consumers do not run a native build, download code at
+the matching binary. Consumers do not run a Rust build, download code at
 runtime, or execute a postinstall step. Omitting optional dependencies keeps
-non-archive fallback-capable operations working in `auto` or `off`. Native-only
+fallback-capable operations working in `auto` or `off`. Native-only
 features, including strict owned-tree temp cleanup, retained-directory staging,
-atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
-zstd/bzip2 TAR handling, and Windows private-directory creation, remain
-unavailable. Operations without a safe fallback fail with `helper-unavailable`
+and atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
+remain unavailable. Operations without a safe fallback fail with `helper-unavailable`
 when the matching package is absent, incompatible, or disabled.
+No-clobber `Root.move()` preserves a native loader failure in the error's
+`cause`, including the original missing-library or incompatible-glibc diagnostic.
 
 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
+reads work without the addon in `auto` or `off` mode when system Windows
+PowerShell and its .NET `Add-Type` compilation support are available. The package
+ships a readable, fixed `.ps1` driver and adjacent `.cs` source and invokes the
+driver with Windows PowerShell `-File`. Paths are passed as data. The fallback
+does not generate helper scripts at runtime or use an encoded launcher.
+The driver addresses built-in commands by module name and limits module
+discovery to PowerShell's bundled system modules, avoiding broad command
+discovery scans during each helper startup.
+
+Normal PowerShell execution policy and Microsoft Defender policy must permit
+the packaged scripts, including their use of `Add-Type`. The package does not
+bypass restrictions, change policies, or add exclusions. Unsupported or
+disallowed command execution fails closed.
+
+The fallback preserves private DACLs at creation and inspects the same open
+handle that supplies secure-file bytes. Each capability emits a path-free
+`FS_SAFE_NATIVE_FALLBACK` warning once per process; each call adds PowerShell
+startup and compilation overhead. Execution or compilation failure also fails
+closed. Native `require` still rejects a missing binding or capability, and an
+available native operation's error never triggers a command retry. See
+[Permissions](permissions.md) and [Secure file reads](secure-file.md).
+
 ## 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
@@ -147,7 +201,7 @@ where a safe fallback exists. Native-only operations fail with
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
+configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
 ```
 

package/node_modules/@openclaw/fs-safe/docs/json-store.md

@@ -85,6 +85,11 @@ For `fileStore(...).json(rel, options)`, `options.durable` overrides the parent
 file store's durability, while omission or `undefined` inherits it. Modes,
 identity checks, mutation serialization, and sidecar locking are unchanged.
 
+Each `write`, `update`, or `updateOr` invocation captures the retained options'
+`durable` and `trailingNewline` values before queueing, locking, reading, or
+calling the updater. Changes to those options affect later invocations only,
+including when a mutation is waiting behind another operation.
+
 The store does **not** validate the parsed value against `T` at runtime — the cast is unchecked. Wrap with a schema (zod/valibot) if the file might be hand-edited or written by another process you don't control.
 
 ## `read()`

package/node_modules/@openclaw/fs-safe/docs/json.md

@@ -146,10 +146,11 @@ where lower latency matters more than crash-durability.
 
 Synchronous variant. It pretty-prints with two spaces, appends a newline,
 creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
-directory best-effort. File-mode tightening carries the staged bigint identity
-through rename and applies `fchmod` only when the reopened descriptor and current
-pathname still name that same single-link regular file; a swap is preserved and
-skips this best-effort step. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+directory best-effort. A retained staging descriptor carries the exact bigint
+identity through rename and file-mode tightening. Publication and cleanup never
+adopt a substituted temporary file: a changed identity, type or link count rejects
+the write and leaves the replacement untouched. A swap detected after publication
+also rejects without deleting or changing the replacement. It has no options bag. On `EPERM`/`EEXIST`, its legacy
 compatibility path removes the existing destination and retries the staged-file
 rename, so that fallback is temporarily non-atomic while retaining the staged
 file's `0600` mode; use the async `writeJson()`/`replaceFileAtomic()` surfaces

package/node_modules/@openclaw/fs-safe/docs/local-roots.md

@@ -83,6 +83,8 @@ An existing non-directory component cannot be traversed further, including by
 The asynchronous helper opens the candidate through the matched [`Root`](root.md),
 so no-follow, identity, hardlink, device-path, and byte-limit checks happen at
 the read itself.
+Link policies are captured once before root initialization and reused for every
+candidate, so replacing options while a read is pending cannot weaken admission.
 
 ```ts
 type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {

package/node_modules/@openclaw/fs-safe/docs/migrating-to-0.5.md

@@ -88,8 +88,10 @@ await extractArchive({
 ```
 
 Returning `"skip"` rejects the archive unless `onFiltered: "skip-entry"` is
-explicit. Zstd and bzip2 TAR are native-only; ZIP, TAR, and gzip retain guarded
-JavaScript implementations. Catch `ArchiveLimitError` by its code, including
+explicit. Zstd and bzip2 TAR required native support in version 0.5; current
+versions also use bundled WASM codecs in `off` or missing-native `auto`, through
+the same guarded TAR pipeline. ZIP fallback still requires optional JSZip.
+Catch `ArchiveLimitError` by its code, including
 `archive-entry-path-components-exceeds-limit` for deep implicit-directory
 attacks. See [Archive extraction](archive.md).
 
@@ -167,10 +169,17 @@ See [File locks](sidecar-lock.md), [Secret files](secret-file.md), and
 
 ## 7. Gate native-only features
 
-`createPrivateDirectory()` is Windows-only and native-only because a pathname
-fallback cannot promise the same creation-time DACL. Zstd/bzip2 extraction and
-`strategy: "rename-noreplace"` are also native-only. Test the unavailable path
-instead of assuming installation always succeeds.
+Version 0.5 required native support for `createPrivateDirectory()`. Current
+releases also support a packaged PowerShell script in native `auto` and `off`
+modes, retaining its creation-time protected DACL. Check the
+[Windows security fallback prerequisites](install.md#windows-security-fallback)
+before relying on this route. The API remains Windows-only, explicit native
+`require` rejects a missing binding or capability, and native operation failures
+remain terminal.
+`strategy: "rename-noreplace"` remains native-only. Current zstd/bzip2 extraction
+and bounded reads have bundled WASM fallbacks, while explicit native `require`
+remains strict. Test unavailable native-only operations instead of assuming
+installation always succeeds.
 
 ## 8. Run both behavior families in CI
 

package/node_modules/@openclaw/fs-safe/docs/migrating-to-0.6.md

@@ -24,10 +24,15 @@ uses native mode `require` or any native-only feature. Version 0.5 kept its
 binding in the root tarball; version 0.6 intentionally does not.
 
 Omitting optional dependencies remains supported for fallback-capable APIs in
-`auto` mode. It disables native-only features such as zstd/bzip2 TAR handling,
-retained-directory staging, atomic `rename-noreplace`, and Windows private
-directory creation. Native mode `require` reports `helper-unavailable` when the
-matching package is absent or incompatible.
+`auto` mode. It disables native-only features such as retained-directory staging
+and atomic `rename-noreplace`. Native mode `require`
+reports `helper-unavailable` when the matching package is absent or incompatible.
+Zstd/bzip2 TAR extraction and bounded reads required the binding in version 0.6;
+current versions also support bundled WASM codecs in `auto` and `off` through the
+same guarded TAR pipeline. ZIP fallback still requires optional JSZip.
+Windows private-directory creation required the binding in version 0.6; current
+releases also support [packaged Windows security scripts](install.md#windows-security-fallback)
+in `auto` and `off` mode while preserving the creation-time protected DACL.
 
 ## Deployment checklist
 

package/node_modules/@openclaw/fs-safe/docs/mutation-policy-proof.md

@@ -39,14 +39,18 @@ sentinel. The same rejection object must escape, no callback may follow refusal,
 and the owned stage must be gone before fixture teardown.
 
 Windows workers exercise buffer `Root.write` through a stable final-file symlink,
-then refuse before staging a newly created placeholder, before publishing over a
-new placeholder, and before publishing to an existing symlink-selected destination.
-They verify alias binding, destination preservation, observed placeholder/stage
-states, and cleanup before fixture teardown. The default native-off and explicit
+then refuse before stage creation for a missing destination, before publishing a
+complete stage to that still-missing destination, and before publishing to an
+existing symlink-selected destination. Missing destinations must remain absent at
+every authority callback and after refusal. The workers verify alias binding,
+destination preservation, complete single-link stages, and cleanup before fixture
+teardown. The default native-off and explicit
 `verify-content-with-lock` native-require configurations both select the existing
-Windows JS buffer writer. The compatibility route is expected not to load the
-addon; the receipt does not mislabel this as native publication or evidence that
-content-verification fallback or lock contention was exercised.
+Windows JS buffer writer. In native-require mode, the compatibility route loads
+the addon to publish its retained sidecar lock through `Root.create`; the payload
+writer remains JS. The receipt does not mislabel this as native payload
+publication or evidence that content-verification fallback or lock contention
+was exercised.
 
 ## Bounds and interpretation