@openclaw/openshell-sandbox 2026.10.6 → 2026.10.7

package/node_modules/@openclaw/fs-safe/dist/windows-test-hooks.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { requireNativeBinding } from "./native.js";
+function call(operation) {
+    if (process.platform !== "win32") {
+        throw new FsSafeError("unsupported-platform", "Windows test fixtures require Windows");
+    }
+    try {
+        return operation();
+    }
+    catch (cause) {
+        if (cause instanceof FsSafeError)
+            throw cause;
+        throw new FsSafeError("helper-failed", "Windows test fixture operation failed", { cause });
+    }
+}
+/** Test-only handle that omits delete sharing. */
+export function holdWindowsSharingLock(filePath) {
+    return call(() => {
+        const native = requireNativeBinding();
+        if (!native.holdWindowsSharingLock)
+            throw new FsSafeError("helper-unavailable", "Windows sharing fixture unavailable");
+        const owner = native.holdWindowsSharingLock(path.toNamespacedPath(filePath));
+        let closed = false;
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            call(() => owner.close());
+        };
+        return Object.freeze({ close, [Symbol.dispose]: close });
+    });
+}
+/** Test-only attribute updates preserve unspecified bits on the opened object. */
+export function setWindowsFileAttributes(filePath, attrs) {
+    call(() => {
+        const native = requireNativeBinding();
+        if (!native.setWindowsFileAttributes)
+            throw new FsSafeError("helper-unavailable", "Windows attribute fixture unavailable");
+        native.setWindowsFileAttributes(path.toNamespacedPath(filePath), attrs);
+    });
+}
+/** Test-only physical mapping reader; lcn -1 represents sparse clusters. */
+export function readWindowsFileExtents(filePath) {
+    return call(() => {
+        const native = requireNativeBinding();
+        if (!native.readWindowsFileExtents)
+            throw new FsSafeError("helper-unavailable", "Windows extent fixture unavailable");
+        return native.readWindowsFileExtents(path.toNamespacedPath(filePath));
+    });
+}

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

@@ -185,6 +185,15 @@ policy to the complete archive, including entries that extraction would strip
 or skip. Known UTF-8 and Unicode Path names are checked during physical admission;
 legacy names retain backend-selected decoding and undergo the same collision
 check before callbacks or selected bytes are returned.
+Native legacy decoding is CP437 when neither the UTF-8 flag nor a valid Unicode
+Path override declares UTF-8, even if the raw bytes also happen to form valid
+UTF-8. Invalid flagged UTF-8 and invalid Unicode Path CRC/encoding fail closed;
+the native metadata boundary enforces these checks before decoder normalization.
+Native ZIP inspection also retains rejection of malformed Unicode Comment
+checksums and UTF-8, including in entries unrelated to a requested payload.
+Comment CRCs follow the native decoder's historical decoded-comment semantics;
+valid sequential Unicode overrides retain their decoder order. Public physical
+admission continues to reject duplicate critical Unicode Path fields.
 
 ZIP end-record admission searches the bounded comment window for signatures
 while retaining complete comment-length and ambiguity checks. Dense signature
@@ -244,6 +253,9 @@ remaining components are skipped before the filter callback, but still count
 toward `maxEntries` and undergo traversal validation. JavaScript TAR extraction
 copies the admitted payload range to this accepted output path, so depth checks,
 collision checks, writes, and mode application agree.
+ZIP directories naming the relative archive root (for example `./`) follow the
+same skip rule on both backends. Portable preflight retains their relative `./`
+spelling; a literal absolute `/` entry is still rejected.
 
 An `entryFilter` sees the validated **canonical effective archive path before
 stripping**, entry kind, and declared size. On every JavaScript and native
@@ -348,6 +360,10 @@ A failure before publication preserves a pre-existing file, and rejection does
 not grant authority to delete a substituted file or alias. Failed extraction does not
 restore overwritten contents. Active destination mutations and their guarded
 cleanup still finish before rejection; no later destination mutation begins.
+On supported native POSIX paths, each active destination ancestor uses its retained
+descriptor plus fresh named-identity and physical-path observations at every guard
+boundary. These checks are never cached or reduced to the deepest directory alone.
+Other paths retain the full pathname checks.
 Portable ZIP output is not eligible for publication until its stream closes or
 the defensive `FileHandle` close succeeds. If that fallback close rejects,
 `extractArchive()` propagates the error and publishes no entry from the staged

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
+complete 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
@@ -262,14 +285,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 +300,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 +317,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 +326,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.

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

@@ -224,9 +224,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.
 

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,8 +148,11 @@ 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).
 
@@ -180,7 +186,9 @@ available native operation's error never triggers a command retry. See
 ### 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

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.
@@ -33,6 +35,12 @@ 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
 `off`; `require` stays strict, and native operation failures remain terminal.
@@ -109,10 +117,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
 

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

@@ -5,6 +5,9 @@ description: "The platform-specific native bindings, fd-relative beneath model,
 
 # Native architecture
 
+See [platform filesystem capabilities](platform-capabilities.md) for Linux
+write leases, public Darwin ACL facts, and Windows test fixtures.
+
 `@openclaw/fs-safe` uses native bindings that supply mechanisms Node does
 not expose directly. The Rust layer is deliberately not a second policy engine.
 TypeScript owns trusted-root selection, path validation, archive filtering,
@@ -14,12 +17,46 @@ platform syscall sequence that can preserve the boundary.
 
 Every operation that has an equivalent safe Node implementation keeps that
 guarded JavaScript path. Native loading is lazy; installs do not compile Rust,
-run postinstall code, or fetch binaries at runtime. Seven exact-version optional
+run postinstall code, or fetch binaries at runtime. Exact-version optional
 packages are filtered by OS, CPU, and Linux libc, so an installation receives
-only its matching prebuilt binding.
+only its matching prebuilt binding. Windows ships both x64 and ARM64 MSVC
+bindings; selection follows the Node process architecture. An x64 Node process
+on Windows ARM64 uses the x64 binding under emulation.
 Native-only operations fail explicitly
 instead of substituting a weaker implementation.
 
+## FreeBSD 14.4 and newer
+
+The FreeBSD x64 and arm64 packages provide native anonymous pipes, descriptor
+close and POSIX canonicalization. The larger Linux/macOS/Windows filesystem backend is excluded
+from these binaries: its Unix gates contain platform-specific resolver, clone,
+copy, observation and cleanup implementations. FreeBSD does not export stubs for
+those operations. In `auto`, each operation selects its existing guarded JavaScript
+or WASM backend; in `require`, a missing required capability fails with
+`helper-unavailable`. Pure JavaScript APIs retain their ordinary behavior.
+
+| Native capability | FreeBSD binding |
+|---|---|
+| `createPipe`, `closeOwnedFd`, `canonicalizePath` | Implemented; real pipe, descriptor and pathname syscalls |
+| Beneath open/create/mkdir/link, replace/no-replace rename and identity-fenced rename | Absent; guarded fallback where supported |
+| Directory observations, retained files/symlinks, entry publication, owned-tree and root removal | Absent; guarded fallback or explicit native-only rejection |
+| File/tree clone, native copy/hash, archive inspection/extraction and buffer readers | Absent; JavaScript/WASM fallback where supported |
+| Native watch | Absent; polling fallback in `auto` |
+| Darwin ACL and Windows security/identity methods | Not applicable |
+
+The release workflow builds inside FreeBSD 14.4 VMs and checks installed-package
+behavior on the main thread and a real Worker. ARM64 uses QEMU CPU emulation
+with a real FreeBSD kernel. This is not a Linux cross-build runtime test. Build
+locally on FreeBSD with `pnpm native:build:freebsd`; the JavaScript/WASM distribution
+can be prepared separately with `pnpm build`. There is no qualified FreeBSD Bun
+artifact in the runtime matrix. FreeBSD x64 installed-package proof covers npm
+and pnpm. FreeBSD arm64 covers npm only because pnpm does not publish a native
+binary for that target. CI prepares the ARM64 proof harness dependencies on Linux
+and syncs them into the VM; consumer installations and runtime proof run inside
+FreeBSD, without running pnpm there.
+Reopening pipe descriptors through `/dev/fd` requires the standard `fdescfs`
+mount there; the VM proof mounts it before testing reopen, inheritance and EOF.
+
 ## The beneath model
 
 A trusted directory descriptor is the capability. Native operations accept
@@ -75,6 +112,11 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   this layer only through the host executable's paired libuv descriptor bridge;
   missing or partial exports fail with `ENOTSUP` instead of trying a raw HANDLE
   or add-on CRT descriptor namespace.
+  `Root.copyIn` uses the same ReFS integrity, sparse-file, and cluster-aligned
+  block-clone operations as tree cloning, through retained source and destination
+  parent handles. The exclusive stage enters the existing guarded publication
+  path; transfer failures retain its cleanup receipt. It does not inherit the
+  tree API's source metadata policy.
 
 The internal macOS `inspectDarwinAcl(fd)` capability reports `absent`, `empty`,
 or `present` for the opened object's extended ACL. It synchronously borrows the
@@ -375,6 +417,13 @@ silently selects the JavaScript fallback in `auto`, throws typed
 `helper-unavailable` in `require`, and is never inspected in `off`. Tests reject
 `child_process`, `exec`, or `spawn` usage in the loader.
 
+## Anonymous pipes
+
+The lean [`pipe` subpath](pipe.md) creates native-owned anonymous pipes. Linux and
+FreeBSD use atomic close-on-exec creation; Darwin reports its non-atomic flag
+setup explicitly. Each end must close through its native owner, including when
+a Node stream uses it in a Worker.
+
 ## Related pages
 
 - [Native helper policy](native-helper.md)

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

@@ -0,0 +1,81 @@
+# Anonymous pipes
+
+`@openclaw/fs-safe/pipe` exposes a synchronous, native anonymous pipe for
+one-shot input to a child process. Both ends are reopenable through
+`/proc/self/fd/N` on Linux and `/dev/fd/N` on Darwin and FreeBSD. This supports
+programs that open an inherited descriptor as a pathname.
+
+On FreeBSD, reopening through `/dev/fd/N` requires `fdescfs` mounted at `/dev/fd`.
+An administrator can mount it with `mount -t fdescfs fdesc /dev/fd`; pipe creation
+itself does not require that mount.
+
+```ts
+import { createPipe, type OwnedPipeSync } from "@openclaw/fs-safe/pipe";
+
+const pipe: OwnedPipeSync = createPipe();
+try {
+  // Pass pipe.reader.fd as a numeric child_process spawn stdio entry.
+  // Keep both owners alive until their respective users finish.
+} finally {
+  pipe.reader.close();
+  pipe.writer.close();
+}
+```
+
+The frozen result has `reader` and `writer` members of the existing
+`OwnedFileDescriptorSync` type (`readonly fd: number`, `close(): void`, and
+`[Symbol.dispose](): void`) and `readonly atomicCloseOnExec: boolean`.
+Each end closes idempotently through its native owner. A close attempt consumes
+ownership even if it throws; do not retry with a raw close or use the fd again.
+The pair itself does not have a `close` or disposal method.
+
+Linux and FreeBSD create both ends atomically with close-on-exec set.
+Darwin sets the flag on both ends immediately after creation and reports
+`atomicCloseOnExec: false`: a concurrent native fork/exec can inherit an end
+in that short window. No JavaScript async work intervenes, but this is not an
+atomic inheritance guarantee. Partial setup failure closes both ends.
+
+Importing the subpath is lazy and does not load the addon or the secret-file
+modules. Calling `createPipe()` requires a compatible native helper; disabled
+or missing helpers throw `FsSafeError` with `helper-unavailable`. Windows and
+other unsupported platforms throw `unsupported-platform`. Native creation
+failures throw `helper-failed` with the original error as `cause`.
+The cause's `code` preserves the native errno, including `EMFILE` (the process
+descriptor limit) and `ENFILE` (the system-wide limit).
+
+## Handing the writer to a Node stream
+
+A native-created fd must close through its owner, including in Workers.
+Provide the stream's custom close hook; do not let Node close it directly.
+This is the writer handoff contract: retain the owner in the hook rather than
+detaching its descriptor.
+
+```ts
+import { createWriteStream, write, writev } from "node:fs";
+import { createPipe } from "@openclaw/fs-safe/pipe";
+
+const pipe = createPipe();
+const stream = createWriteStream("", {
+  fd: pipe.writer.fd,
+  fs: {
+    write,
+    writev,
+    close(_fd, callback) {
+      try {
+        pipe.writer.close();
+        callback(null);
+      } catch (error) {
+        callback(error instanceof Error ? error : new Error(String(error)));
+      }
+    },
+  },
+});
+// After spawning with pipe.reader.fd in the child's stdio:
+pipe.reader.close();
+stream.end("one-shot input");
+```
+
+Once the stream is created, its lifetime owns use of the writer: keep an error
+listener, destroy it on cancellation, and wait for `close` before considering
+the fd released. If stream construction fails, close both owners. Closing the
+last writer delivers EOF; unread bytes remain available to the reader.

package/node_modules/@openclaw/fs-safe/docs/platform-capabilities.md

@@ -0,0 +1,63 @@
+# Platform filesystem capabilities
+
+These synchronous capabilities load the native helper only when called. All
+three entry points import on every supported platform.
+
+## Linux write leases
+
+`tryAcquireWriteLease(fd)` from `@openclaw/fs-safe/file-lock` returns a frozen
+`FileWriteLease`, or `null` when another open descriptor prevents acquisition
+(`EAGAIN` or `EBUSY`). Other failures throw `FsSafeError`; unsupported systems
+throw `unsupported-platform` and unavailable helpers throw `helper-unavailable`.
+
+The caller owns the descriptor, must keep it open until release, and must install
+its own process-wide `SIGIO` handler **before** acquiring a lease. Prefer a
+disposable child process when an application cannot own that signal. The API
+does not install a signal handler. A competing open starts the kernel's lease
+break; `isHeld()` then returns false, including during a pending downgrade.
+Release promptly so the competing opener can proceed.
+
+`lease.fd` is the borrowed descriptor. `lease.release()` and
+`lease[Symbol.dispose]()` settle once without closing it; `isHeld()` returns
+false after release. Never close or reuse the fd before settling the lease.
+Lease acquisition does not replace the caller's path identity and age checks.
+
+## Darwin ACL inspection
+
+`inspectDarwinAcl(path)` from `@openclaw/fs-safe/permissions` opens the final
+component without following symlinks, then inspects a descriptor-bound security
+snapshot. Its `DarwinAclInspection` result is one of:
+
+- `{ kind: "none" }` for a proven absent or empty extended ACL.
+- `{ kind: "present", inheritsToFiles, inheritsToDirectories }` for an ACL with
+  entries, including when both inheritance flags are false.
+- `{ kind: "unknown", reason }` when opening or inspection fails, the helper
+  is unavailable, or the native facts are incomplete. Other platforms return
+  `reason: "unsupported-platform"`.
+
+Unknown is never evidence of absence. The two inheritance booleans report flag
+presence, not effective permissions or volume ownership enforcement. Intermediate
+path components follow ordinary path resolution; this is inspection, not a Root
+confinement capability.
+
+## Windows test fixtures
+
+The following exports from `@openclaw/fs-safe/test-hooks` are for tests, not
+production policy. They require the Windows native helper and reject final
+reparse points. Other platforms throw `unsupported-platform`.
+
+- `holdWindowsSharingLock(path)` returns a frozen disposable with idempotent
+  `close()`. Its native owner holds a non-inheritable handle with read/write
+  sharing, omitting delete sharing, until closed or collected.
+- `setWindowsFileAttributes(path, { readOnly?, hidden?, system? })` updates the
+  supplied bits through the opened handle and preserves unspecified attributes.
+- `readWindowsFileExtents(path)` returns `{ vcn, lcn, clusters }[]`, all bigint.
+  Empty or resident files may have no extents; `lcn: -1n` denotes sparse clusters.
+  Enumeration validates each response and fails on incomplete or invalid data.
+  It is an observation, not a snapshot against concurrent file modification.
+
+Use Node's `fs.statfsSync(path).bsize` for Windows cluster size. Windows CI
+compares it directly against `GetDiskFreeSpaceW`'s sectors-per-cluster times
+bytes-per-sector on NTFS. CI does not provide ReFS; this does not establish ReFS
+clone sharing. The extent reader reports mappings independently of the clone
+implementation.