@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

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

@@ -16,7 +16,7 @@ import {
 
 Write `content` to a sibling temp file in the destination directory, apply the parent-directory and final file modes through verified descriptors, optionally `fsync` the file descriptor, optionally `fsync` the parent directory after rename, then atomically rename over the destination. No permission change follows a caller-supplied pathname.
 
-On POSIX, the parent is opened with no-follow and directory-only flags, checked against its pre-open identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
+On POSIX, the parent is opened with no-follow and directory-only flags, checked against its exact pre-open device/inode identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
 
 Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
 
@@ -60,6 +60,8 @@ type ReplaceFileAtomicOptions = {
   syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
   syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
   throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
+  assertBeforeMutation?: () => void;
+  onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
   beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
   fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
 };
@@ -92,8 +94,82 @@ await replaceFileAtomic({
 
 If `beforeRename` throws, the rename is skipped and the owned temp file is removed — the destination is unchanged. Cleanup unlinks only the exact admitted single-link file; a substitute observed at the temp name is preserved and removed from cleanup authority. The same identity is rechecked before every rename retry, when entering copy fallback, and at the final name after rename. A post-rename verification failure reports the race without rolling back or deleting the published name.
 
+JavaScript permits `beforeRename` callbacks and filesystem adapters to throw any value, including
+`undefined`, `null`, `false`, signed zero, `0n`, an empty string, and `NaN`.
+Atomic replacement preserves such operational failures when cleanup and close
+succeed, including rename and post-rename verification failures. Rename retry
+and copy-fallback classification reads the error code once without coercion;
+missing or unreadable codes preserve the original failure. A rejected call has
+no success receipt even if an adapter committed its rename before throwing. With
+`throwOnCleanupError: true`, an additional owned-temp cleanup failure keeps the
+existing cleanup wrapper whose `cause` is the original thrown value. A later
+descriptor-close failure is reported in an `AggregateError`, in operation/cleanup
+then close order. The default `throwOnCleanupError: false` omits only the cleanup
+failure: the temp stays registered for identity-checked process-exit cleanup, the
+descriptor is still closed, and a close failure remains reportable.
+
 Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
 
+### Atomic write authority and destination state
+
+Use `assertBeforeMutation` when a write depends on a lease or other revocable
+application authority. Both atomic variants capture the callback at entry and
+run it synchronously before directory creation or mode changes, compatibility
+lock acquisition, staging creation and writes, each rename attempt, and fallback
+removal, destination acquisition, truncation, and each content write. Asynchronous destination identity checks
+finish before the final authority check; no await separates that check from the
+write dispatch. A dispatched operation still owns its completion.
+
+`onDestinationState` captures facts that a caller may need if the operation later
+rejects:
+
+```ts
+type ReplaceFileAtomicDestinationState =
+  | Readonly<{ state: "removed"; path: string }>
+  | Readonly<{
+      state: "writing" | "published";
+      path: string;
+      dev: bigint;
+      ino: bigint;
+    }>;
+```
+
+- `removed` follows successful removal of an existing fallback destination.
+- `writing` records the fallback's retained descriptor after exclusive creation
+  or the first successful truncation of an existing `restore-original` target.
+  Opening an existing target leaves it untouched and emits no receipt. This state
+  does not claim that all requested bytes were written.
+- `published` follows successful rename and destination identity verification,
+  before parent synchronization or descriptor close can fail. Copy fallback
+  reports it after its content, mode, and requested file synchronization complete.
+  The explicit `verify-content-with-lock` policy first applies its existing
+  locked content verification to admit the replacement descriptor.
+
+Receipts are frozen and use the destination spelling captured by the operation.
+File identities come from retained descriptors, never from reopening a pathname
+after a failed copy. Failed or indeterminate admission can leave no identity
+receipt; a rename followed by replacement before verification also has no
+publication receipt. Do not infer ownership from a fresh post-failure stat. A later writer
+can replace the pathname, so compare the recorded identity with the current
+entry and recheck application authority before compensation. Receipts do not
+promise durable storage or authorize rollback.
+
+Both callbacks must complete synchronously; Promise, thenable, and synchronous
+or asynchronous generator results are rejected. Returned generators are never
+advanced; other ordinary return values are ignored. The first callback refusal
+is terminal, including falsy thrown values; an `EPERM`, `EEXIST`, or `EBUSY` code
+from a callback never starts fallback or retry. Refusal during an in-place
+fallback also stops new restoration writes. Final mode, synchronization, close,
+and private-stage cleanup may still settle against owned identities after
+revocation. Callback refusal does not delete a published destination or a
+competing file at a staging name. An observer that throws must retain its receipt
+first if recovery needs it.
+
+`beforeRename` remains the hook for preparing backups. Effects performed inside
+that hook remain the caller's responsibility; the authority option guards the
+atomic writer's own effects. Omitting both new callbacks preserves existing
+write, fallback, restoration, result, and cleanup behavior.
+
 ### FUSE, Windows exFAT/FAT32, and unstable rename identity
 
 Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
@@ -139,6 +215,28 @@ must not have aliases. The policy reads `nlink` from a pinned destination
 descriptor, not pathname metadata, before rename and rechecks it in the copy
 fallback.
 
+The asynchronous helper closes a successfully admitted hardlink-check pin
+best-effort, including synchronous adapter throws and rejected close promises.
+The synchronous helper reports a close failure after successful admission.
+
+Source and pinned destination admission compare exact bigint device/inode
+observations, so distinct identities that round to the same JavaScript number
+cannot authorize a copy. Unknown Windows identities get one bounded reinspection
+of the same descriptor or path; incomplete or inconsistent observations fail
+closed without reopening. Injected filesystem adapters must honor the
+`{ bigint: true }` stat option. Source admission reuses that exact pair instead
+of immediately repeating it with numeric metadata.
+
+Copy-source close is best-effort. A failed pinned-destination admission also
+preserves its selected failure when close fails. These cleanup rules include
+synchronous throws and rejected promises from custom asynchronous adapters.
+
+The best-effort parent-directory synchronization helper also ignores either form
+of close failure. Parent-directory mode admission and its close remain fail-closed.
+A compatibility-publication handle that was not adopted also receives one
+best-effort close, preserving the selected verification or previous-handle close
+failure. The retained owner's close failures remain reportable.
+
 The default `copyFallbackRestore: "none"` preserves the existing fallback
 contract: a failed copy can leave a partial destination. For state files where
 preserving the old bytes is more important, choose `"restore-original"` and set
@@ -148,6 +246,35 @@ that same descriptor, and synchronizes the result. Any write, mode, or sync
 failure triggers a byte-and-mode restore and another sync through the same
 descriptor.
 
+With mutation callbacks enabled, an `EIO` from destination `stat`/`lstat` after
+successful truncation also attempts restoration through that retained descriptor.
+Each restore write still requires live application authority and fresh exact
+descriptor identity, regular-file, and configured hardlink checks. The failed
+pathname observation is not retried to authorize restoration; no pathname is
+opened, removed, or replaced. A successor at that name is left untouched.
+`details.cleanup: "restored"` means the retained original file's bytes and mode
+were restored and synchronized, not that the pathname still names it. The existing
+`writing` receipt identifies that file; no `published` receipt is emitted for a
+failed replacement. Restoration I/O failures report `"restore-failed"`.
+
+Callback refusals, detected identity/type/link changes, and other metadata errors
+remain terminal. Failed descriptor revalidation also stops restoration. These
+cases can leave the retained file empty or partial with only a `writing` receipt;
+before the first successful truncation, verification failure leaves it untouched.
+
+With `syncTempFile: false`, an exclusive-create copy fallback does not report
+success until its new destination writer closes successfully. This includes
+`"restore-original"` when the destination did not exist. A close rejection or throw is
+propagated exactly, including falsy values. The destination may already contain
+all or part of the replacement, so a close failure does not prove that the old
+destination survived or that the replacement was published. The outer atomic
+operation still attempts identity-bound cleanup of its owned source temp; an
+unverifiable or substituted temp remains preserved. If writing, mode adjustment,
+or another earlier operation also fails, that earlier value remains the reported
+failure and the destination close is attempted once. Successful synchronized
+fallbacks and in-place `"restore-original"` replacements retain their existing best-effort final-close
+handling.
+
 Restore failures are `FsSafeError("helper-failed")` values with typed
 `details.cleanup` set to `"restored"` or `"restore-failed"`. An original larger
 than `maxRestoreBytes` fails with `too-large` before mutation. A missing
@@ -165,10 +292,16 @@ through short reads and EOF, grow only as data arrives, and enforce the same
 `beforeRename` callback, and `ReplaceFileAtomicSyncFileSystem`. Use it inside
 synchronous boot paths or test setup code. It returns the same
 `{ method: "rename" | "copy-fallback" }` receipt as the async variant.
+Promise, thenable, and synchronous or asynchronous generator results from the
+hook reject with `TypeError` before publication; rejected promises are consumed
+and generators are never advanced. Other synchronous return values are ignored.
+The replacement is not published; owned-temp cleanup follows the rules above.
 
 ## `replaceDirectoryAtomic`
 
-Atomically swap one directory's contents with another, using a temporary backup during the swap.
+Publish one staged directory at a target without overwriting a concurrently
+created entry. Despite the historical name, replacing an existing target is a
+guarded two-rename protocol, not an atomic directory exchange.
 
 ```ts
 import { replaceDirectoryAtomic } from "@openclaw/fs-safe/atomic";
@@ -179,23 +312,74 @@ await replaceDirectoryAtomic({
 });
 ```
 
-The helper renames `targetDir` to a generated backup path, renames `stagedDir → targetDir`, then removes the backup. If the second rename fails, it tries to restore the original target before rethrowing.
-Concurrent replacements of the same resolved target are serialized inside the
-current process so their backup, commit, and cleanup phases cannot interleave.
-On Windows, ordinary drive-relative staged and target paths are anchored at
-entry before namespace-alias admission and resolution.
+Every publication requires the dedicated native identity-fenced,
+descriptor-relative no-replace rename capability and readable retained
+descriptors for the staged and target parents. Older bindings that expose only
+the legacy four-argument no-replace rename fail with `helper-unavailable`
+before target-parent creation or any other replacement effect. This applies
+when the parents are the same or different. There is no JavaScript rename
+fallback, and a cross-device rename still fails. Replacing an existing target
+additionally requires usable native bounded owned-tree cleanup and a readable
+retained descriptor for the original target.
+
+If the target is absent, the helper publishes `stagedDir → targetDir` with a
+single no-replace rename. If the target exists, it renames `targetDir` to a
+randomized sibling backup and then renames `stagedDir → targetDir`. The target
+name is temporarily absent between those two operations. A competing entry is
+never overwritten. Publication rollback is attempted only when the staged
+rename is known not to have committed and the target name is still absent; the
+rollback itself is no-replace, so a competitor is preserved and the backup is
+left for recovery.
+
+Exact staged-directory identity and parent checks run before and after each
+rename. On Windows, the native rename opens the source relative to the retained
+parent, compares that handle's exact volume and file-index identity with the
+pre-rename bigint receipt, and only then mutates it. POSIX does not provide a
+rename operation that also compares an expected source inode, so on POSIX a
+source-name substitution in the final check-to-rename gap can be moved briefly
+and then detected by the post-rename verification. Similarly, a successful
+rename can be followed by a verification error. Inspect the error's
+`details.publication` value rather than treating rejection as proof that
+publication did not happen.
+
+A Windows source-identity mismatch is rejected before mutation, reported
+publicly as `path-mismatch`, and treated as definitely uncommitted so an earlier
+backup can be rolled back. Other `path-mismatch`-shaped native errors are not
+assumed to be pre-commit failures; their publication outcome remains
+indeterminate and observed competitors are preserved.
+
+Any native rename error without explicit pre-dispatch provenance has an
+indeterminate outcome, including ordinary errno such as `ENOENT`, `EEXIST`,
+or `EACCES`: a remote filesystem may commit before losing its reply. The helper
+does not guess whether that rename committed or perform another rename or
+cleanup based on that guess; observed names are preserved for caller-directed
+recovery. An error `details.backupPath`, when present, is only the attempted or
+last-observed backup pathname. It does not prove that the path still exists or
+still names the original directory.
+
+After a verified commit, the original backup is removed through its retained
+directory identity and bounded native traversal. Cleanup failures reject after
+publication and can leave the backup. On POSIX, cleanup retains the
+[bounded final-entry unlink limitation](temp.md#private-temp-workspaces).
+
+Concurrent calls for the same resolved target are serialized inside the current
+process so their backup, publication, and cleanup phases cannot interleave.
+Other processes are not serialized; no-replace renames provide the competitor
+boundary. On Windows, ordinary drive-relative staged and target paths are
+anchored at entry before namespace-alias admission and resolution.
 `backupPrefix`, when supplied, is sanitized as one path prefix and cannot contain
 path separators or NUL bytes; the generated backup tail is randomized.
 
-Use it when callers must see a whole staged tree at the target path. For single-file replacement, `replaceFileAtomic` is the right tool.
+Use it when callers must publish a whole staged tree with these recovery
+semantics. For single-file replacement, `replaceFileAtomic` is the right tool.
 
 ## `writeTextAtomic`
 
 Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
 temp file, descriptor-bound mode setting and fsync, rename, and parent fsync.
-It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
-you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
-or custom copy-fallback policy.
+It delegates to `replaceFileAtomic()` with a smaller call shape, including its
+pre-publication hook and staging-prefix options. Use `replaceFileAtomic()` when
+you need mode preservation or a custom copy-fallback policy.
 
 ```ts
 import { writeTextAtomic } from "@openclaw/fs-safe/atomic";
@@ -215,9 +399,17 @@ type WriteTextAtomicOptions = {
   dirMode?: number;          // parent mode (default 0o777 masked by process umask)
   trailingNewline?: boolean; // append "\n" if missing; default false
   durable?: boolean;         // default true; false skips temp/parent fsync
+  beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
+  tempPrefix?: string;       // default ".fs-safe-replace"
 };
 ```
 
+`beforeRename` is awaited after the complete text is staged and before
+publication, with the same [stage identity and refusal cleanup](#beforerename)
+checks as `replaceFileAtomic`. Pass `tempPrefix` to identify staged files; it
+uses the same prefix validation, including rejection of empty prefixes and path
+separators.
+
 `durable: false` keeps the sibling-temp replace/rename behavior but skips the
 temp-file and parent-directory `fsync` calls. Use it only for reconstructible
 metadata where lower latency matters more than crash-durability.
@@ -272,7 +464,10 @@ the preflight cap fails with `FsSafeError("too-large")`.
 If another writer changes source entries during the fallback, the staged copy
 throws `ESTALE` before commit when possible. If the destination has already
 been committed, cleanup still preserves the changed source entries and throws
-`ESTALE`. Directory manifests retain an exact bigint device/inode receipt from
+`ESTALE`. Copied file and symlink manifests retain exact bigint identities and
+nanosecond timestamps, so rounded file IDs cannot authorize copying or removal
+of a different entry. Hardlink groups also use exact identities. Directory
+manifests retain an exact bigint device/inode receipt from
 copy admission. Each directory is rechecked after traversal, and the source root
 is checked again before publication. Cleanup checks the same receipt before
 removing children, then invokes mutation authority and rechecks the receipt and
@@ -289,6 +484,11 @@ unlink is verified through a remaining manifested alias and its exact resulting
 identity becomes the next cleanup receipt. This accounts for the operation's
 own link-count and ctime changes without suppressing unexpected external
 mutations.
+On Windows, opening a regular source may advance its ctime while all other
+fingerprint fields match. That exception applies only to opening; post-copy
+verification and cleanup retain their full fingerprint checks.
+Copied aliases share each verified open-time update. Changes observed between
+copies still reject instead of being mistaken for an owned open transition.
 
 ### Mutation authority and publication receipts
 
@@ -327,6 +527,11 @@ thenable, or any other value fails with a `TypeError`; rejected asynchronous
 results are consumed. Perform asynchronous policy checks before calling the
 helper and use the authority callback to recheck the current owner at each
 mutation boundary. All callbacks are captured before the first await.
+Copied source leaves are checked again immediately after authority returns and
+before unlink is submitted. Supplying any of the three callbacks also
+retains the original source-parent route and renews copied-directory ancestry
+before cleanup. Substituted entries are preserved; pathname checks and unlink
+remain a best-effort sequence, not atomic.
 
 `onDestinationPublished` runs exactly once after a successful rename resolves,
 before awaited post-rename directory checks or source cleanup. It receives a
@@ -396,7 +601,7 @@ type ReplaceFileAtomicSyncFileSystem = {
 };
 ```
 
-The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. On POSIX, that `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Older adapter literals may continue to include `chmod` or `chmodSync` for source compatibility, but those operations are ignored. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
+The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. The async temp owner consumes its retained handle before awaiting `close()` during publication handoff and terminal settlement: if a custom adapter releases the resource and then rejects, that rejection is reported without calling `close()` on the same retained handle again. If publication verification opened a replacement handle before the previous retained handle failed to close, the replacement receives one best-effort close attempt. On POSIX, `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Older adapter literals may continue to include `chmod` or `chmodSync` for source compatibility, but those operations are ignored. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
 
 ## See also
 

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

@@ -37,10 +37,14 @@ Set the process-global loading policy. Configure once at startup, before the fir
 
 | Mode | Behavior |
 |---|---|
-| `auto` | Default. Prefer the platform binding and use guarded JavaScript when it is unavailable. |
-| `off` | Do not load the binding; use guarded JavaScript deterministically. |
+| `auto` | Default. Prefer the platform binding and use supported fallbacks when it is unavailable. |
+| `off` | Do not load the binding; use supported fallbacks and reject native-only operations. |
 | `require` | Operations that need the binding raise `FsSafeError("helper-unavailable")` when it cannot load. |
 
+Fallbacks include guarded JavaScript, the bundled TAR/gzip WASM parser, and the
+[packaged Windows security scripts](install.md#windows-security-fallback).
+Windows command fallbacks remain subject to normal system execution policy.
+
 ## `getFsSafeNativeConfig()`
 
 ```ts

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

@@ -19,10 +19,50 @@ manager version declared in `package.json`.
 pnpm build
 ```
 
-Runs TypeScript compilation and builds the portable Rust TAR parser for
-`wasm32-unknown-unknown`. Contributors need Rust (the native crate's declared
-minimum or newer) and `rustup target add wasm32-unknown-unknown`; Alpine's
-packaged toolchain uses `rust-wasm`. `pnpm archive:wasm` rebuilds just the parser.
+Runs TypeScript compilation and builds the portable Rust TAR parser and its
+bzip2/zstd codecs for `wasm32-unknown-unknown`. Contributors need Rust (the
+native crate's declared minimum or newer), `rustup target add
+wasm32-unknown-unknown`, and LLVM's WebAssembly-capable `clang` and `llvm-ar`.
+The system's native `ar` is not sufficient. `pnpm archive:wasm` rebuilds just
+the portable module.
+
+Linux, macOS, and Windows CI use the same pinned WASI SDK 34 LLVM toolchain;
+Alpine uses its versioned LLVM 22 packages alongside `rust-wasm`. For local
+builds, install LLVM through your package manager or use the official
+[WASI SDK](https://github.com/WebAssembly/wasi-sdk/releases/tag/wasi-sdk-34).
+On macOS, `brew install llvm` supplies the archiver missing from Apple's
+Command Line Tools. On Windows, install the LLVM distribution with both
+`clang.exe` and `llvm-ar.exe`. On Linux, install the matching `clang` and
+`llvm` packages; a GCC-only build toolchain cannot compile these WASM codecs.
+
+The build discovers tools on `PATH`, in `LLVM_PATH/bin`, in Homebrew's LLVM
+prefixes, and in Windows' standard LLVM installation. It also checks the
+versioned `clang-18` through `clang-21` and `llvm-ar-18` through `llvm-ar-21`
+executables. To select another installation explicitly, set
+`CC_wasm32_unknown_unknown` and `AR_wasm32_unknown_unknown` to its compiler
+and archiver. The corresponding hyphenated target variables and cc-rs's
+`TARGET_CC`/`TARGET_AR` or `CC`/`AR` overrides are also respected; an unusable
+explicit override fails with a builder diagnostic instead of being ignored.
+Windows build environment names are case-insensitive, including when worker
+processes uppercase them. The build normalizes only its copied child environment.
+Clang's implicit configuration is disabled for this target so the WASI SDK's
+default libc/sysroot cannot leak into the import-free module. These settings
+affect compilation only and do not become runtime dependencies.
+
+The build disables release LTO only in the WASM Cargo subprocess. An observed
+Rust 1.98.1 optimized-WASM-LTO allocation/free failure makes that necessary;
+the native release profile stays unchanged. The WASM linker strips debug
+sections to keep the bundled module small without stripping native binaries.
+The build verifies zero host
+imports and one unshared 32-bit memory with the existing 256 MiB maximum
+before copying the artifact. Allocator regression tests build a separate
+instrumented module with `pnpm archive:wasm:allocator-tests` under the Cargo
+target directory. That module is never copied to `dist/` or packaged. `pnpm
+check` and coverage collection build it explicitly before testing. After a
+fresh checkout, run that command before `pnpm test`, `pnpm test:coverage`, or
+focused `test/archive-codec-wasm-allocator.test.ts` runs; the tests fail if
+their prerequisite artifact is missing.
+
 The import-free asset lands at `dist/archive-parser.wasm`; source tests and
 compiled consumers both resolve that generated artifact. Run `pnpm build`
 before source tests in a fresh checkout. Do not commit `dist/` or built WASM.
@@ -30,6 +70,36 @@ Consumers receive the asset in the npm package and need no compiler.
 
 Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
 
+### Linux GNU release bindings
+
+GNU x64 and arm64 artifacts use Zig 0.16.0 and `cargo-zigbuild` 0.23.4 with an
+explicit glibc 2.28 target, independent of the runner's libc. This matches the
+Node Linux runtime baseline and supports RHEL 8-family users without adding a
+second legacy package. Run the same build and ABI gate used in CI and releases:
+
+```bash
+cargo install cargo-zigbuild --version 0.23.4 --locked
+rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs x86_64-unknown-linux-gnu
+node scripts/build-linux-gnu.mjs aarch64-unknown-linux-gnu
+```
+
+These commands require Zig on `PATH` and GNU `objdump`. They build the N-API
+cdylib with `cargo zigbuild --target <triple>.2.28`, copy it to the existing
+`artifacts/fs-safe-native.<platform>.node` name, and reject any GLIBC symbol
+requirement above 2.28 before upload. The gate also rejects missing or unknown
+GLIBC versions. To inspect an existing binding, use
+`node scripts/check-linux-glibc.mjs <binding.node>`.
+
+`pnpm native:build` remains a host-toolchain development build; it does not
+establish the GNU release ABI floor.
+
+On Linux x64 or arm64 with Docker, run `pnpm build`, copy the matching GNU artifact from
+`artifacts/` to `native/`, run `node scripts/stage-host-native.mjs`, then run
+`bash scripts/test-linux-glibc-floor.sh`. CI uses this command to load the actual
+artifact and run native security and no-replace move tests in Rocky Linux 8
+(glibc 2.28). Both GNU architectures execute this load test on matching runners.
+
 ## Test
 
 ```bash
@@ -97,6 +167,52 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+The native watch lane requires events on Linux, macOS, and Windows and reports
+actual edit latency. Run `FS_SAFE_TEST_SERIAL=1 pnpm check` to isolate local timing
+checks from the other filesystem stress suites. Watch fixtures use normal OS
+temporary storage; session scratch trees may suppress macOS filesystem events.
+
+### Optional Linux Testbox
+
+The manual `testbox-validation.yml` workflow prepares a 16-vCPU Ubuntu 24.04
+Blacksmith Testbox with Node 24.21.0, pnpm 12.4.2, dependencies, the Rust WASM
+target, and the pinned portable archive compiler. It leaves library builds and
+validation commands to the caller and does not replace required CI checks.
+
+Use an authenticated Blacksmith CLI with access to the repository and its
+Blacksmith organization. From a full repository checkout, warm one session
+through Crabbox:
+
+```sh
+CRABBOX_BLACKSMITH_IDLE_TIMEOUT=240m crabbox warmup --provider blacksmith-testbox \
+  --blacksmith-org openclaw \
+  --blacksmith-workflow .github/workflows/testbox-validation.yml \
+  --blacksmith-job validate --blacksmith-ref main \
+  --idle-timeout 240m --timing-json
+```
+
+Use a branch or tag containing the workflow for `--blacksmith-ref`; GitHub must
+first have registered the workflow on the default branch. The job has a fixed
+240-minute limit. Keep the idle timeout at that limit (240 minutes in the native
+Blacksmith CLI) because the pinned Testbox action can miss active SSH sessions
+behind a forwarded port. Bound commands by the remaining job time and leave time
+to collect results and stop before the deadline.
+
+Use the returned `tbx_...` ID for subsequent commands. The `fs-safe-testbox`
+wrapper restores the prepared tool paths and WASM compiler settings in the SSH
+shell. For example:
+
+```sh
+crabbox run --provider blacksmith-testbox --id <tbx_id> --timing-json -- \
+  fs-safe-testbox pnpm check
+crabbox stop --provider blacksmith-testbox <tbx_id>
+```
+
+Stop the session when finished and verify its terminal status. Blacksmith owns
+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.
+
 ### Method benchmarks
 
 `pnpm benchmark:methods` measures the callable library surface against synthetic
@@ -117,6 +233,10 @@ pnpm archive:producer-smoke ./consumer require
 This uses a child bound to canonical cwd/device/inode running `/usr/bin/tar -czf - .`
 with unchanged stdout, and npm tar, on synthetic Unicode/newline/long-name files,
 then the installed package API for exact payload hashes and bounded reads.
+The consumer must be separate from the source checkout; package resolution must
+stay within its own `node_modules`, including pnpm's local `.pnpm` layout.
+Workspace self-resolution, upward resolution, and external package links reject
+before package imports or archive fixture creation.
 It also rejects a valid PAX override attached to an invalid raw UTF-8 field.
 The `require` command must resolve the freshly packed native binding; the
 `off` command uses the installed WASM asset. No live user files are read.
@@ -157,10 +277,32 @@ 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 four host targets: Linux x64 glibc, Linux x64 musl
-(Alpine), macOS arm64, and Windows x64. The root-only smoke runs on each. The
-seven-target source build matrix runs on release tags; packaging all seven is
-not execution proof for every architecture. The smoke writes manager versions,
+PR CI builds and executes all seven 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).
+
+| Lane | Runner | Architecture / libc | Runtime |
+| --- | --- | --- | --- |
+| JavaScript check | `ubuntu-latest` | x64 / glibc | Node 22, 24, 26 |
+| JavaScript check | `macos-15` | arm64 | Node 22, 24, 26 |
+| JavaScript check | `fs-safe-windows-16core` (`windows-latest`) | x64 | Node 22, 24, 26 |
+| Native check | `ubuntu-latest` | x64 / glibc | Node 24, Bun 1.4.2 |
+| Native check (forced no-openat2) | `ubuntu-latest` | x64 / glibc | Node 24 |
+| Native check | `ubuntu-24.04-arm` | arm64 / glibc | Node 24, Bun 1.4.2 |
+| Native check | `macos-15` | arm64 | Node 24, Bun 1.4.2 |
+| 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 |
+| 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 |
+| GNU glibc 2.28 build + Rocky Linux 8 load | `ubuntu-24.04-arm` | arm64 / glibc | Node 24 |
+| Bundled package smoke | `ubuntu-latest`, `macos-15`, `fs-safe-windows-16core` | host | Node 22, 24 |
+| 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,
 cases, and synthetic-fixture scope to `release-artifacts/consumer-proof.json`.
 
 ## Docs

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

@@ -66,16 +66,22 @@ On Windows, automatic byte copying uses the native binding when available to tra
 
 On Linux, automatic byte copying also uses the native binding when available. It reads in chunks up to 1 MiB, using smaller buffers for smaller source-size hints, and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
 
+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.
+
 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.
 
+Failed ReFS clones attempt to remove their partial output through the retained directory handles. On Windows versions that reject the ignore-readonly deletion flag, clone rollback retries without that flag so ordinary output can be removed. It never clears readonly attributes: readonly output can remain, and the original clone error includes the cleanup failure. Other processes retaining output handles can delay deletion beyond settlement; a failed call does not guarantee an absent destination.
+
 XFS and ZFS preserve regular-file and directory modes, timestamps, extended attributes, and ACLs. They reject special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
 
 `readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.
 
+All input paths must be absolute and valid before native availability is checked. On platforms other than macOS, `auto` and `off` can return one `undefined` per path without the addon, matching native's unsupported result. On macOS, `off` or an unavailable addon still rejects with `helper-unavailable`; JavaScript cannot supply APFS clone IDs. Explicit `require` mode rejects an unavailable addon on every platform, including for an empty batch. Errors from a loaded native helper remain terminal.
+
 ## Borrowed FileHandle transfers
 
 `copyFileHandle` from `@openclaw/fs-safe/advanced` copies bytes between two
@@ -137,14 +143,49 @@ descriptor inspection does not prove that the source remained unchanged while
 copying. Keep existing source-fingerprint and publication checks around the
 transfer when building snapshot operations.
 
+### Synchronous descriptor transfers
+
+`copyFileDescriptorSync(sourceFd, targetFd, options?)` provides the same
+zero-origin byte transfer for borrowed numeric descriptors. It shares
+`CopyFileHandleOptions` and returns the copied byte count synchronously:
+
+```ts
+import { copyFileDescriptorSync } from "@openclaw/fs-safe/advanced";
+
+const bytes = copyFileDescriptorSync(sourceFd, targetFd, {
+  maxBytes: expectedSize,
+  assertBeforeMutation: assertSnapshotOwnerCurrent,
+});
+```
+
+The same regular-file and exact-identity admission, byte limits, short-I/O
+handling, cursor preservation, and caller-owned cleanup apply. The target must
+be opened without append mode, and both descriptors must remain open and free
+of concurrent I/O, including inside callbacks. Neither helper makes a mutable
+source into a consistent snapshot or truncates an existing destination suffix.
+
+The synchronous helper snapshots the four options once and invokes both
+callbacks with no receiver (`this` is `undefined` in strict callbacks).
+`onChunk` receives a borrowed view that must be consumed immediately without
+retaining or mutating it. Both callbacks must finish synchronously; thenables
+throw `TypeError` before the current write. Cancellation is cooperative: a
+pre-aborted signal or an abort triggered by a callback stops the transfer before
+the next write. Timers cannot interrupt synchronous filesystem calls while the
+event loop is blocked. Authority runs before every partial write; an abort
+triggered by that assertion prevents the same write.
+
 ## Ownership and cancellation
 
 These are low-level operations on caller-owned absolute paths, not Root-relative methods. The source and destination parent must be real directories. The library pins their descriptors and verifies their identities; it does not establish the caller's authorization to use them. Keep the source immutable for the operation, including writes through other aliases, and keep the destination namespace under the caller's control. Literal symlinks in the cloned contents are preserved rather than followed or sanitized.
 
 An already aborted signal prevents dispatch. In-flight cancellation stops cancellable traversal and waits for admitted native writes to finish before rejecting. APFS and Btrfs bulk operations cannot be interrupted once dispatched. An aborted or failed call can therefore leave a destination, including a complete bulk clone. It remains caller-owned; after settlement, the caller decides whether to retain or remove it. Do not start cleanup by racing the cloning promise against an abort promise.
 
+Tree copying preserves caller abort handlers and receives cancellation even when a caller handler stops event propagation, including native cloning and byte-copy fallbacks.
+
 Completion is not a crash-durability guarantee. The API is suitable for reconstructible templates and checkouts; it does not sync every file or replace application-level publication and recovery rules.
 
+A close-only rejection reports descriptor settlement, not whether bytes reached stable storage. The destination can already be complete when a close fails, just as other failed or cancelled calls can leave caller-owned output. Inspect or remove that output only after the copying promise settles and under the same source and destination authority assumptions.
+
 Byte copying retains fractional file and directory access/modification timestamps to the precision supported by Node's timestamp APIs and the destination filesystem. This includes dates before 1970 on Unix. On Windows, [Node's unsigned stat seconds](https://github.com/nodejs/node/blob/v26.8.2/src/node_file-inl.h#L93-L104) can report pre-1970 timestamps as dates about 136 years later; byte copying inherits that upstream limitation.
 
 ## Platform tests and benchmarks