@openclaw/openshell-sandbox 2026.10.5-beta.4 → 2026.10.10-beta.2

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

@@ -100,6 +100,29 @@ On Linux x64 or arm64 with Docker, run `pnpm build`, copy the matching GNU artif
 artifact and run native security and no-replace move tests in Rocky Linux 8
 (glibc 2.28). Both GNU architectures execute this load test on matching runners.
 
+### Windows ARM64 builds
+
+`windows-11-arm` builds and runs the ARM64 MSVC addon using native ARM64 Node
+and Rust, and separately tests x64 Node and Rust under Windows emulation. Both
+lanes run the native suite, main-thread and Worker private-creation/descriptor
+proof, and root-only npm/pnpm install smoke. PE inspection matches the loaded
+consumer binary's hash, architecture and required NT imports. Omitted-optionals
+creation probes in the x64-emulated cell have a 600-second deadline: three
+pre-helper measurements had a 183.18-second median, with 140 PowerShell launches
+accounting for 98–99% of wall time. This is over three times that median, rounded
+up to a whole minute. Native ARM64 and x64 cells, and every other consumer probe,
+retain their 120-second deadlines. Release builds
+also run the ARM64 native security and Worker tests before uploading the binding.
+
+The only linked C codec is `zstd-sys`; `cargo test --workspace --locked` and the
+release addon build compile it for `aarch64-pc-windows-msvc`. Bzip2 uses
+`libbz2-rs-sys`, and deflate uses `miniz_oxide`, both Rust implementations.
+The portable WASM build uses the checksum-pinned x64 WASI SDK under Windows
+emulation because that SDK has no Windows ARM64 host archive. Its compiler and
+archiver produce wasm32 only; the addon still uses MSVC for the selected target.
+Bun 1.4.2 has no Windows ARM64 artifact; the existing Windows x64 Bun lanes remain
+the Bun runtime proof. Native Windows ARM64 support is qualified with Node.
+
 ## Test
 
 ```bash
@@ -213,6 +236,16 @@ checkout synchronization; record the tested source revision or diff, Testbox ID,
 and Actions run. This backend is Linux-only and does not accept Crabbox's direct
 SSH `--script` or `--download` flags. The workflow provides no application secrets.
 
+### Node baseline benchmark
+
+After `pnpm build` and `pnpm native:build`, run `pnpm benchmark:node --json results.json --markdown results.md` on an idle machine. This runs native `off` and `require` in separate processes and writes combined JSON, one JSON file per mode, and a side-by-side Markdown table. `require` fails if its binding cannot load. `--mode off` runs without a native build.
+
+Use `--temp-root /path/on/the/target/filesystem` to select the measured storage (otherwise the OS temporary directory is used). In particular, avoid tmpfs for durable-write comparisons. Record the filesystem, OS, Node version, CPU and load with the results; the JSON includes filesystem magic, artifact hashes, runtime details and sample observations. The [benchmark guide](https://github.com/openclaw/fs-safe/tree/main/benchmarks#node-baseline-comparison) describes the workloads and optional Linux syscall tracing.
+
+Defaults are seven alternating raw/safe/control blocks, three warmup invocations per arm, and 30 calls per sample (fewer for traversal and extraction). Each sample is a mean of timed calls; reported latency is the median sample mean, not a tail percentile. Setup, verification and cleanup are outside timing. Adjust `--iterations`, `--samples`, `--warmup`, or use `--filter read` for a focused run.
+
+Ratios divide fs-safe time by raw Node time; smaller is faster. The A/A row and per-operation A/A column compare identical raw calls and show measurement noise. Raw Node is **not security-equivalent**: raw writes truncate in place, while fs-safe stages and atomically publishes; durable raw writes sync the file, while fs-safe also synchronizes publication where supported. Each row documents the actual comparison. Treat ratios near the A/A spread cautiously, and retain all samples when comparing changes. No benchmark changes a production safety or durability default.
+
 ### Method benchmarks
 
 `pnpm benchmark:methods` measures the callable library surface against synthetic
@@ -262,14 +295,14 @@ OS/CPU/libc selection, a native-required SHA-256 operation, and fresh-process
 optionals. Omitted-optionals installs also verify that all public subpaths can
 be imported, without implying every operation remains available.
 
-Host-only smoke supplies the six foreign packages using their unchanged real
+Host-only smoke supplies the seven foreign packages using their unchanged real
 manifests and clearly marked synthetic, non-executable payloads. Every foreign
 metadata/tarball endpoint is checked before installation, so a missing fixture
 cannot masquerade as successful platform filtering. These temporary fixtures
 never enter `packages/`, release artifacts, or the publish manifest. They prove
 installer filtering, not foreign native compilation or execution. Full release
-collection uses the actual seven collected native tarballs instead. Run it with
-`pnpm package:collect` after assembling all seven real bindings; missing targets
+collection uses the actual eight collected native tarballs instead. Run it with
+`pnpm package:collect` after assembling all eight real bindings; missing targets
 fail collection. `pnpm package:collect --allow-host-only` exercises the same
 lifecycle boundary locally but proves only the host. Both collection commands
 require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standalone
@@ -277,7 +310,7 @@ require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standa
 direct `node` invocation without lifecycle metadata is unsupported. Archive
 codecs and their dependencies are packed from the installed dependency graph.
 
-PR CI builds and executes all seven shipped bindings. The existing check names
+PR CI builds and executes all eight shipped bindings. The existing check names
 stay stable; extra runner/runtime combinations add checks without changing the
 repository ruleset. Native lanes run Node 24; the GNU host lanes also exercise
 Bun 1.4.2 (as do macOS and Windows).
@@ -294,6 +327,7 @@ Bun 1.4.2 (as do macOS and Windows).
 | Native check | `macos-15-intel` | x64 | Node 24, Bun 1.4.2 |
 | Native check | `fs-safe-windows-16core` (`windows-latest`) | x64 | Node 24, Bun 1.4.2 |
 | Native check | `windows-2022` (standard hosted) | x64 | Node 24, Bun 1.4.2 |
+| Windows ARM64 host | `windows-11-arm` | arm64 native and x64 emulated | Node 24 |
 | Native check (Alpine 3.24) | `ubuntu-latest` | x64 / musl | Node 24 |
 | Native check (Alpine 3.24) | `ubuntu-24.04-arm` | arm64 / musl | Node 24 |
 | GNU glibc 2.28 build + Rocky Linux 8 load | `ubuntu-latest` | x64 / glibc | Node 24 |
@@ -302,11 +336,17 @@ Bun 1.4.2 (as do macOS and Windows).
 | Coverage | `ubuntu-latest`, `macos-15`, `fs-safe-windows-16core` | host | Node 22 |
 
 Both musl lanes also run root-only package smoke with the real host binding.
-The seven-target source build matrix still runs on release tags. The smoke writes manager versions,
+The eight-target source build matrix still runs on release tags. The smoke writes manager versions,
 cases, and synthetic-fixture scope to `release-artifacts/consumer-proof.json`.
 
 ## Docs
 
+`pnpm docs:check` runs examples against the built package and compiles every
+TypeScript block in `README.md`, the lock API signatures, and the custom stale-lock
+policy example against its declarations. Run `pnpm build` first.
+The compiler supplies typed application context for excerpted variables such as
+`download`; package API calls and callback values remain fully type-checked.
+
 The docs site is rendered recursively from Markdown files under `docs/` by `scripts/build-docs-site.mjs`. Build locally to preview:
 
 ```bash

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

@@ -68,12 +68,24 @@ On Linux, automatic byte copying also uses the native binding when available. It
 
 Tree-copy cleanup attempts every acquired close once, even when another close fails. Portable file handles close output before input; completed directories close their pinned source before target; the public wrapper then closes its source before the destination parent. A copy, identity, metadata, native-clone, or cancellation failure already observed at one of those scopes remains the reported value instead of being replaced by cleanup. If that scope otherwise succeeded, its first close failure is reported unchanged. Concurrent siblings have no global structural close order: the first observed sibling failure stops new work while admitted work settles. Portable copying records caller cancellation when it occurs, so a later abort during cleanup cannot replace an earlier copy failure.
 
+For guarded per-file copying, [`Root.copyIn`](writing.md#copy-metadata-and-source-links) can preserve timestamps and Windows non-permission attributes with `preserveMetadata`, and copy literal links with `sourceSymlinks: "copy-link"`. Permission selection remains separate. Windows reparse payload handling is shared with this tree copier.
+
 Clones preserve file contents, empty directories, timestamps, executable modes where supported, and literal symbolic links. Editing a clone does not modify its source. Unsupported filesystem operations fail; callers may choose their own copy or checkout fallback after the failed operation has settled.
 
 Native Windows byte copies can store large zero-filled chunks as sparse ranges when the destination is initially empty and its filesystem supports sparse files. This still reads every source byte and creates an independent copy.
 
 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.
 
+For successful native ReFS clones through `copyTree` or `Root.copyIn`, all full
+clusters are block-cloned; a final partial cluster may be copied. Both preserve exact bytes and logical file size.
+The shared implementation keeps EOF at the source size and rounds only the final
+clone request to the allocation-cluster boundary. Microsoft's
+[block-cloning rules](https://learn.microsoft.com/en-us/windows/win32/fileio/block-cloning#restrictions-and-remarks)
+require cluster-aligned ranges and setting destination EOF before cloning;
+rounding a request does not promise physical sharing of a partial final cluster.
+Windows x64 and ARM64 tests compare every full-cluster LCN for both APIs,
+including the 4 MiB shared prefix of a 4 MiB + 1 byte file.
+
 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.
@@ -192,6 +204,16 @@ Byte copying retains fractional file and directory access/modification timestamp
 
 After building the host native binding, run `pnpm test test/clone.test.ts test/copy-tree.test.ts`. APFS tests can use the normal macOS temporary directory. For Btrfs, ReFS, XFS, or ZFS, set `FS_SAFE_CLONE_TEST_ROOT` to an existing writable directory on that filesystem. The test creates and cleans only its own temporary children. An explicitly configured unsupported directory fails the test rather than silently skipping platform proof. XFS and ZFS metadata tests require the `attr` and `acl` utilities.
 
+The `ReFS copyIn` CI workflow creates a disposable 2 GiB expanding VHD on
+Windows Server 2025 x64 and Windows 11 ARM64. It formats the latter as a Dev
+Drive, verifies that the mounted filesystem is ReFS, and sets
+`FS_SAFE_CLONE_TEST_ROOT`. `test/root-copy-refs.test.ts` runs the built package on
+the main thread and in a real Node Worker, checks shared physical extents with
+`readWindowsFileExtents`, independent writes, exclusive publication, byte limits,
+cancellation cleanup, and revocation between file copies. Both jobs also run the
+tree clone suite, then detach and delete the VHD even after failure. A failed
+volume setup fails the job; it never substitutes NTFS or skips the ReFS proof.
+
 Run `node scripts/clone-xfs-proof.mjs MOUNT` on a real XFS volume to verify the public API, hashes, independent writes, and shared physical extents. It requires `filefrag` from `e2fsprogs`. Add `no-reflink` for an XFS fixture formatted with reflinks disabled; strict copying must fail and automatic copying must succeed through byte copying.
 
 Run `node scripts/clone-zfs-proof.mjs MOUNT POOL` on a dedicated, otherwise idle Linux ZFS pool with compression and deduplication disabled. It verifies both `copyTree` and `Root.copyIn` through hashes and changes in the documented `bclonesaved` pool counter. It requires `zfs`, `zpool`, and `findmnt`, including permission to run `zpool sync`. Add `no-reflink` for a pool without block cloning to verify strict refusal and automatic byte fallback. The script creates and removes only its temporary directory; it does not create pools or change their properties.
@@ -226,6 +248,10 @@ readable/writable `fd`, with idempotent `close()` and `Symbol.dispose`, and retu
 bigint destination `identity` and `sourceIdentity` (`dev`, `ino`). Both identities
 are readonly and frozen. Closing releases the descriptor, not the file.
 
+Use `fs.stat(path, { bigint: true })` for exact Windows file IDs.
+`expectedSourceIdentity` requires bigint components and rejects Number inputs
+with `FsSafeError("path-mismatch")`, including unsafe rounded Numbers.
+
 Callers that already pinned a source can pass `expectedSourceIdentity: { dev, ino }`
 from `fs.fstatSync(pinnedSourceFd, { bigint: true })`. fs-safe still admits and
 opens its own source descriptor, and compares its exact bigint identity before
@@ -280,15 +306,15 @@ for (const name of ["plugin.js", "package.json"]) {
 }
 ```
 
-On canonical POSIX paths, the batch retains root and ancestor directory
+On canonical POSIX and ordinary Windows drive paths, the batch retains root and ancestor directory
 identities across files. Every use still checks those identities without
 following directory symlinks; root and parent canonical paths are rechecked.
 Source opens, source and destination file identities, hardlink policy, exclusive
 creation, bounds, permissions, and cleanup are checked separately for every file.
 No source descriptor, file contents, or successful file-admission result is cached.
 An ancestor replacement rejects even when the leaf parent has not changed.
-Windows and noncanonical path spellings keep the full per-file resolver and its
-alias handling. There is no option to bypass validation.
+Windows namespaces, short-name spellings, trailing-dot/space components, and
+noncanonical path spellings keep the full per-file resolver and its alias handling. There is no option to bypass validation.
 
 Keep the batch scoped to one capture or materialization, with unchanged source
 and destination directory topology. `close()` and `Symbol.dispose` idempotently
@@ -299,9 +325,23 @@ identity-checked cleanup contract; the batch is not an atomic tree transaction
 or a coherent snapshot of concurrent edits. The single-file helper also reuses
 directory admissions for the duration of its one copy.
 
-Both APIs reuse the freshly checked canonical root during initial POSIX path
+Both APIs reuse the freshly checked canonical root during initial canonical path
 admission. This avoids repeatedly resolving every absolute root component while
 retaining lexical traversal and the before/after root and parent identity checks.
-Windows and root aliases retain the ordinary resolver, including its handling
+Windows namespace spellings and root aliases retain the ordinary resolver, including its handling
 of dot segments in symlink targets. No caller changes are needed for the
 single-file improvement.
+
+## Exact identity receipts
+
+`copyRootFileSync()` returns exact bigint `identity` (destination) and
+`sourceIdentity` values. Pass `sourceIdentity` to `expectedSourceIdentity` to
+bind another copy to that source, or the destination `identity` when copying the
+new file. `Root.copyIn()` reports exact bigint `dev`/`ino` through
+`onDestinationPublished`; retain that callback receipt when reopening the output.
+`PublishedWriteIdentity` callbacks already use the same exact shape.
+
+`readCloneFileMetadata()` now also supplies `exactIdentity`, derived from the
+same native metadata record as its legacy `dev` and `ino` fields. These remain
+point-in-time observations. Exact identity does not grant ownership or protect
+against later replacement; use the operation's identity-checking API.

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

@@ -77,15 +77,16 @@ 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
+compatibility. Its `exactIdentity` companion contains immutable bigint `dev`
+and `ino`, projected from the same observation. 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
+identity object through to later operations to retain this evidence. When copying
+a receipt, preserve `exactIdentity`; pass it to `expectedExistingIdentity`. A copied
+numeric identity without its exact companion 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.
 
@@ -149,6 +150,27 @@ target. It pins the source with nonblocking `O_NOFOLLOW`, optionally verifies
 `expectedSourceIdentity`, tries a hardlink first, then synchronizes the target
 parent directory.
 
+Pass `expectedSourceIdentity` from `fs.stat(path, { bigint: true })` (or
+`fs.lstat`) for exact Windows file IDs. Unsafe Number components cannot prove
+identity and reject with `FsSafeError("path-mismatch")` before publication;
+safe integer Numbers remain supported. Internal source fences use bigint stats.
+
+Every successful publication returns `exactIdentity: Readonly<{ dev: bigint;
+ino: bigint }>` alongside the unchanged `identity: Stats` metadata view. Both
+come from one final bigint `fstat` of the retained descriptor. Pass
+`result.exactIdentity` back as `expectedSourceIdentity` when publishing that file
+again. Passing the whole publication result is also supported: its explicit
+`exactIdentity` takes precedence. `sameFileIdentity()` and
+`copyRootFileSync().expectedSourceIdentity` accept that same receipt shape.
+
+On Windows, the Number view may round an NTFS file ID; it must not be used for
+identity checks. Do not re-stat a pathname to reconstruct an earlier publication
+receipt: that can observe a replacement. After a failed publication,
+`PublishFileExclusiveFailureDetails.exactTargetIdentity` identifies the created
+target when known; `targetIdentity` remains the legacy numeric view. Retain the
+exact failure field when inspecting a preserved target. Unknown or mismatching
+identities still fail closed.
+
 Trusted relative source and target paths are resolved to absolute paths before
 authority checks. On Windows, ordinary drive-relative operands are anchored at
 entry before namespace-alias admission. A caller-supplied `parentReceipt` must
@@ -171,7 +193,7 @@ try {
     onSyncFailure: "preserve",
     parentReceipt: backupDirectory,
   });
-  recordDurableBackup(result.identity, result.directorySync);
+  recordDurableBackup(result.exactIdentity, result.directorySync);
 } catch (error) {
   if (
     error instanceof FsSafeError &&
@@ -224,9 +246,11 @@ count limits need not mean the entire filesystem lacks hard-link support.
 `link-required` and `link-or-copy` do not use `renameat2` and are unchanged.
 
 `"link-required"` propagates an unsupported hardlink failure.
-`"link-or-copy"` falls back only for `EPERM`, `EXDEV`, `ENOTSUP`,
+`"link-or-copy"` falls back only for `EACCES`, `EPERM`, `EXDEV`, `ENOTSUP`,
 `EOPNOTSUPP`, or `ENOSYS`; `isHardlinkFallbackError()` exposes that exact
-classifier. The fallback copies from the pinned source into a `wx` target,
+classifier, including Android/Termux hardlink permission refusals. A genuine
+permission denial still fails the fallback's exclusive target creation; `EEXIST`
+never permits fallback. The fallback copies from the pinned source into a `wx` target,
 fsyncs it, and fences source and target identity and content before reporting
 success. `parentReceipt`, when supplied, must name the target's direct parent.
 
@@ -319,6 +343,9 @@ thread. Both paths stream bounded buffers rather than loading the file into memo
 The fallback sizes its scratch buffer to small files and grows it if a stale
 size hint is exceeded, while still probing for actual EOF and byte-limit overflow.
 Native mode `require` keeps its usual fail-closed loader semantics.
+On Windows, pathname hashing can read through its privately owned handle
+without reopening it. Hashing a caller-owned handle still uses an independent
+reader to preserve the caller's position.
 
 ### Synchronous hashing
 

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

@@ -38,6 +38,14 @@ class FsSafeError extends Error {
 
 `cause` is available through the standard `Error` `cause` property when the failure was triggered by a `NodeJS.ErrnoException` (e.g. a wrapped `EACCES`). Inspect it for the original `code` / `errno` / `syscall` if you need finer-grained reporting.
 
+Native Windows failures, including private directory and file creation failures,
+retain the original numeric Win32 error in `errno` (for example, 183 for
+`ERROR_ALREADY_EXISTS` or 5 for `ERROR_ACCESS_DENIED`). This also applies to the
+Windows security command fallback. A wrapped failure retains that number on its
+original `cause`; the semantic `FsSafeError.code` remains the contract. Policy
+checks and preflight rejections that do not execute a failing Windows operation
+have no Win32 error number. Node-managed filesystem errors retain Node's own errno.
+
 Guarded write preparation describes permission, read-only filesystem, and disk-space
 failures with messages such as `permission denied (EACCES)` or
 `no space left on device (ENOSPC)`. Other errno failures include their code in

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

@@ -56,6 +56,8 @@ can replace only an **empty directory created concurrently**; non-empty
 directories and non-directory targets are refused as `EEXIST`. An existing
 empty directory observed by the absence check is also refused. No empty claim
 directory is exposed before publishing the completed source.
+An `ENOTDIR` rename failure rechecks the source before reporting a destination
+collision; a detected source substitution reports `ESTALE` instead of `EEXIST`.
 
 Identity checks and mutation remain separate, not source-name compare-and-swap.
 The fallback verifies the published identity afterward. A file fallback failure

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

@@ -106,6 +106,7 @@ Use the main entry for the common surface, or the focused subpaths when you want
 | `@openclaw/fs-safe/json` | `tryReadJson`, `readJson`, `readJsonIfExists`, `writeJson`, sync variants. |
 | `@openclaw/fs-safe/store` | `fileStore()`, `fileStoreSync()`, and `jsonStore<T>()`. |
 | `@openclaw/fs-safe/secret` | Secret file read/write helpers. |
+| `@openclaw/fs-safe/pipe` | Native-owned, reopenable anonymous pipes for one-shot child input. |
 | `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `writeTextAtomic`, `replaceDirectoryAtomic`, `movePathWithCopyFallback`. |
 | `@openclaw/fs-safe/durability` | Pinned directories, strict sync, durable directory creation, exclusive publication, and streaming SHA-256. |
 | `@openclaw/fs-safe/temp` | `tempWorkspace`, `withTempWorkspace`, sync variants, `resolveSecureTempRoot`. |
@@ -125,9 +126,11 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 `@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
+There are no peer dependencies. Exact-version optional packages carry the
 native targets and npm-compatible OS, CPU, and Linux libc filters install only
-the matching binary. Consumers do not run a Rust build, download code at
+the matching binary. Windows ARM64 Node selects
+`@openclaw/fs-safe-win32-arm64-msvc`; x64 Node on the same host selects the x64
+package. Consumers do not run a Rust build, download code at
 runtime, or execute a postinstall step. Omitting optional dependencies keeps
 fallback-capable operations working in `auto` or `off`. Native-only
 features, including strict owned-tree temp cleanup, retained-directory staging,
@@ -145,42 +148,59 @@ before deploying with native mode `require` or native-only features.
 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
+Nested no-clobber moves retain native parent admission and exact identity checks;
+keep native mode enabled. If `renameat2(RENAME_NOREPLACE)` is also unsupported,
+Linux `auto` uses [move fallbacks](writing.md#fs-move-from-to-options), including
+a directory rename that can replace a concurrently created empty directory.
+Native `require` refuses these fallbacks. 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).
+Windows pathname permission inspection, raw owner/DACL inspection, private-directory creation, and secure-file
+reads work without the addon in `auto` or `off` mode using the packaged
+`windows-security-helper.exe`. This prebuilt AnyCPU console application targets
+.NET Framework 4.6.2 or newer (CLR v4.0.30319), with the modern path handling
+used by Windows PowerShell 5.1. It runs as native x64 on x64 Windows and native ARM64 on Windows
+11 ARM with .NET Framework 4.8.1, including when the calling Node is x64.
+No compiler, .NET SDK, or PowerShell is needed by this fallback at runtime.
+
+Each check starts a separate helper process. The compatibility owner/ACL query
+passes `["owner", targetPath]` as arguments and preserves .NET's named security
+lookup and ACL normalization. Other paths and expected identities stay
+in environment variables, and descriptor checks inherit the actual borrowed
+handle through stdin. No security facts are cached or checks combined. 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 feature in each JavaScript context.
+It names the native availability reason and expected package version; see
+[troubleshooting fallback warnings](native-helper.md#troubleshooting-fallback-warnings).
+
+Release Windows native addons and `windows-security-helper.exe` are
+Authenticode-signed by **OpenClaw Foundation** with a timestamp. The executable
+is included in the main npm package and covered by its npm provenance, just
+like its JavaScript. Source lives in the repository; consumers receive only the
+executable. Missing or disallowed execution fails closed with a rebuild/reinstall
+hint. Signing does not guarantee acceptance by every Smart App Control,
+AppLocker, or WDAC policy; local policy can still block execution in user
+directories. There is no PowerShell retry. Such hosts can also restrict
+PowerShell to Constrained Language Mode, where the former Add-Type fallback
+was unavailable. The package does not bypass policies or add exclusions.
+
+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), [Secure file reads](secure-file.md), and
+[reproducible helper builds](native.md#windows-helper-build).
 
 ## 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,
+macOS x64/arm64, Windows x64/arm64, and FreeBSD 14.4+ x64/arm64. FreeBSD provides the
+[documented subset](native.md#freebsd-14-4-and-newer); its other operations retain
+guarded fallbacks in `auto`. 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

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

@@ -16,11 +16,11 @@ Current releases install the matching exact-version optional platform package.
 - Run on Node.js 22 or newer.
 - Update `@openclaw/fs-safe` and regenerate every lock or shrinkwrap file your
   deployment consumes.
-- Keep optional dependencies enabled if you want JavaScript ZIP/TAR support.
-  Native loading no longer depends on Python. Keep optional dependencies enabled
-  for the matching native package and JavaScript ZIP/TAR decoders. An install
-  that omits them can still import fs-safe, but native-only features and missing
-  JS archive decoders fail with actionable errors.
+- Keep optional dependencies enabled for the matching native package and the
+  JSZip fallback. Current TAR/gzip/zstd/bzip2 fallbacks are bundled and work
+  with optional dependencies omitted. Native loading no longer depends on
+  Python. See [runtime dependencies](install.md#runtime-dependencies) for the
+  current installation contract.
 
 If you call `resolveRootPath()` or `resolveRootPathSync()` directly, upgrade to
 0.5: versions through 0.4.7 could approve an in-root symlink traversal that
@@ -170,7 +170,7 @@ See [File locks](sidecar-lock.md), [Secret files](secret-file.md), and
 ## 7. Gate native-only features
 
 Version 0.5 required native support for `createPrivateDirectory()`. Current
-releases also support a packaged PowerShell script in native `auto` and `off`
+releases also support a packaged .NET Framework helper 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

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

@@ -31,7 +31,7 @@ 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)
+releases also support [packaged Windows security helper](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/native-helper.md

@@ -5,8 +5,10 @@ description: "How fs-safe loads its platform-specific native filesystem primitiv
 
 # Native helper policy
 
-`@openclaw/fs-safe` declares seven exact-version optional packages for Linux
-x64/arm64 (glibc or musl), macOS x64/arm64, and Windows x64. Package-manager
+`@openclaw/fs-safe` declares exact-version optional packages for Linux
+x64/arm64 (glibc or musl), macOS x64/arm64, Windows x64/arm64, and FreeBSD x64/arm64.
+The FreeBSD 14.4+ bindings expose the [qualified subset](native.md#freebsd-14-4-and-newer).
+Package-manager
 OS, CPU, and libc filters install only the matching package. The loader requires
 that package lazily, without runtime downloads, postinstall scripts, or a
 consumer Rust build.
@@ -29,18 +31,87 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 | `off` | Do not load a native package. Use supported fallbacks and reject native-only operations deterministically. |
 | `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
 
+See [What needs the native binding](native.md#what-needs-the-native-binding)
+for the native-only APIs and options.
+
 See [Archive extraction](archive.md) for native, bundled WASM, and ZIP backends.
 Native archive-operation failures are terminal; `auto` does not retry them through a
 fallback. `require` rejects missing bindings or required capabilities.
 
+A loaded binding may provide only a subset of native operations. Each operation
+checks its required capabilities before native dispatch: missing capabilities
+select the existing guarded fallback in `auto`, or report `helper-unavailable`
+in `require`. A failure from an available native method is still an operation
+failure; it is not treated as a missing capability.
+
 Windows owner/DACL inspection, private-directory creation, and secure reads can
-use [PowerShell fallbacks](install.md#windows-security-fallback) in `auto` and
+use [Windows helper fallbacks](install.md#windows-security-fallback) in `auto` and
 `off`; `require` stays strict, and native operation failures remain terminal.
 Bun macOS/Linux canonicalization uses the addon under its
 [runtime requirements](install.md#bun-runtime).
 
 Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
 
+## Runtime health checks
+
+`getFsSafeNativeStatus(options?: { probe?: boolean }): Promise<FsSafeNativeStatus>` is
+exported from `@openclaw/fs-safe/config` and the main entry point. It reports the
+loader state without parsing warnings, on every supported runtime. A doctor can
+explicitly probe without changing the configured mode or mutating the filesystem:
+
+```ts
+import { getFsSafeNativeStatus } from "@openclaw/fs-safe/config";
+
+const status = await getFsSafeNativeStatus({ probe: true });
+console.log(status.loaded ? "Native helper active" : `Native helper: ${status.reason}`);
+if (status.guidance) console.log(status.guidance);
+```
+
+| Fields | Meaning |
+|---|---|
+| `mode`, `modeSource` | Effective policy and its source; only environment variable names are exposed. |
+| `reason`, `loaded` | `not-probed`, `loaded`, `disabled`, `unsupported-target`, `package-missing`, `load-failed`, or `capability-missing`; `loaded` is true only for `loaded`. |
+| `target` | Runtime platform/architecture/libc, including unsupported targets. |
+| `packageName`, `packageVersion` | Expected platform package and exact pinned manifest version; absent for unsupported targets. |
+| `loadErrorCode` | Allowlisted code or `UNKNOWN`, only for `load-failed`. |
+| `guidance` | The same next-step text as fallback warnings; absent for `not-probed` and `loaded`. |
+
+Await the returned promise. With no options, this API only reads the cache and
+never loads the addon;
+`not-probed` means no load has been attempted. With `{ probe: true }`, it uses
+the existing lazy loader and cache. Mode `off` always reports `disabled` without
+attempting a load. Failures are reported without throwing, including in `require`
+mode. Core `capability-missing` does not expose internal function names, and a
+`loaded` result does not promise that every operation is available or kernel-atomic.
+Fields omit paths and raw loader errors.
+
+Each module instance has its own status, so probe real Workers separately when
+their health matters. After repairing an installation, start a fresh process or
+Worker: the cached failure is not retried by another probe or mode change.
+See the [full API reference](config.md#getfssafenativestatus-options) for exported
+types and field details.
+
+## Troubleshooting fallback warnings
+
+Windows security and private-creation fallbacks emit `FS_SAFE_NATIVE_FALLBACK`
+once per feature in each JavaScript context (the main thread or a Worker).
+Warnings identify the reason and, on supported targets, the expected platform
+package and its exact version from fs-safe's manifest. They omit caller paths
+and raw loader error messages. Other guarded fallbacks, including Linux/macOS
+operations, do not currently emit this warning.
+
+| Reason | Next step |
+|---|---|
+| `package-missing` | Reinstall with optional dependencies included: npm `--include=optional`, or pnpm without `--no-optional` / `optional=false`. Check that the lockfile and registry mirror include the named package at the exact version. Install for the deployed Node architecture and Linux libc. |
+| `disabled` | The warning names the effective source: programmatic configuration, `FS_SAFE_NATIVE_MODE`, or `OPENCLAW_FS_SAFE_NATIVE_MODE`. If native loading is intended, set that source to `auto` or `require`. Programmatic configuration takes precedence, then `FS_SAFE_NATIVE_MODE`, then `OPENCLAW_FS_SAFE_NATIVE_MODE`. Keep intentional `off` settings for isolated runtimes. |
+| `unsupported-target` | Portable mode is expected on this platform/architecture/libc target; no matching native package is published. Native-only operations remain unavailable. |
+| `load-failed` | Check Node architecture, Linux libc compatibility, and OS code-integrity policy. A missing dependency inside an installed platform package is also a load failure. Reinstalling identical bytes may not help; resolve compatibility or approved signing/policy requirements without disabling security controls. |
+| `capability-missing` | Use matching fs-safe and platform-package versions. A loaded binding may intentionally provide a platform-specific subset; see the [FreeBSD capabilities](native.md#freebsd-14-4-and-newer). |
+
+Restart the process or Worker after repairing an installation: failed loads are
+cached. These diagnostics do not change `auto`, `off`, or `require` behavior,
+and a loaded addon does not imply that every operation is kernel-atomic.
+
 Native-created descriptors retain their originating native close operation through
 normal and error cleanup, including later mode changes. Node-created roots and
 directory handles keep Node's close operation, and borrowed handles keep their
@@ -109,10 +180,12 @@ is authoritative for operation and platform guarantees.
 
 ## Migration from the Python helper
 
-The deprecated configuration bridge maps Python settings to native modes and
-warns once; it never executes Python. Follow the
+The Python configuration bridge has been removed. Old Python environment
+settings are ignored without a warning, so an old `require` or `off` setting
+does not select the corresponding native policy. Configure
+`FS_SAFE_NATIVE_MODE` or `configureFsSafeNative()` explicitly. Follow the
 [0.5 migration checklist](migrating-to-0.5.md#2-replace-python-helper-configuration)
-for aliases, warning behavior, and precedence.
+for the removed settings and current precedence.
 
 ## Related pages