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

package/README.md

@@ -4,7 +4,7 @@ Official NVIDIA OpenShell sandbox backend for OpenClaw.
 
 This plugin lets OpenClaw use OpenShell-managed local or remote sandboxes with
 SSH command execution. Choose `mirror` mode for a synchronized local workspace
-or `remote` mode for a remote-canonical workspace.
+or `remote` mode for a workspace managed on the remote host.
 
 Mirror operations sharing a workspace run sequentially so concurrent agent
 turns cannot overwrite one another. Outbound attachments resolve against the

package/node_modules/@openclaw/fs-safe/CHANGELOG.md

@@ -2,6 +2,154 @@
 
 ## Unreleased
 
+## 0.26.5 - 2026-10-14
+
+### Highlights
+
+- **Android/Termux and WSL compatibility:** create temporary workspaces under Android system-owned ancestors and complete short nonblocking reads on WSL/9p filesystems. ([#982](https://github.com/openclaw/fs-safe/pull/982), [#983](https://github.com/openclaw/fs-safe/pull/983))
+- **Windows synchronous read batches:** add `createRootFileOpenBatchSync()` to reuse native root handles while retaining per-file safety checks. ([#984](https://github.com/openclaw/fs-safe/pull/984))
+
+### Features
+
+- **Windows synchronous read batches:** reuse native root handles with `createRootFileOpenBatchSync()` while retaining fresh file identity, reparse, hardlink, byte-limit, and confinement checks. ([#984](https://github.com/openclaw/fs-safe/pull/984))
+
+### Fixes
+
+- **WSL/9p reads:** finish short nonblocking reads instead of truncating uncapped files, atomic copy fallbacks, or content verification. Thanks @Hawk5150 for [openclaw/openclaw#145589](https://github.com/openclaw/openclaw/issues/145589). ([#983](https://github.com/openclaw/fs-safe/pull/983))
+- **Android/Termux temp workspaces:** admit system-owned ancestors and Android-private writable groups while preserving private roots and full ancestry checks. Thanks @kukirin-ui for [openclaw/openclaw#171406](https://github.com/openclaw/openclaw/issues/171406). ([#982](https://github.com/openclaw/fs-safe/pull/982))
+
+## 0.26.4 - 2026-10-13
+
+### Fixes
+
+- **Windows AppContainers:** private files and directories now work inside a Windows AppContainer: the creating container can reopen them and other containers stay denied. Requires the native addon; folder-mounted volumes fail closed. Behavior outside a container is unchanged. Thanks @jonathanlindsay. Reported in [openclaw/openclaw#160287](https://github.com/openclaw/openclaw/issues/160287); limits are in the [permissions guide](docs/permissions.md#advanced-windows-acl-helpers). ([#980](https://github.com/openclaw/fs-safe/pull/980))
+
+### Docs and Tooling
+
+- **Windows durability costs:** explain what non-durable writes cost and save on Windows. ([#973](https://github.com/openclaw/fs-safe/pull/973))
+
+## 0.26.3 - 2026-10-13
+
+### Highlights
+
+- **Native health and signed Windows binaries:** inspect runtime native support with `getFsSafeNativeStatus()`; Windows addons and the security helper now carry timestamped OpenClaw Foundation signatures. ([#965](https://github.com/openclaw/fs-safe/pull/965), [#960](https://github.com/openclaw/fs-safe/pull/960))
+- **Linux copy compatibility:** recover from refused reflink I/O, including ZFS block cloning, through a guarded byte copy. ([#972](https://github.com/openclaw/fs-safe/pull/972))
+- **Less native filesystem overhead:** retain directory parents, reuse writable-file admission, batch Root verification, and avoid unrelated macOS watch wakeups. ([#971](https://github.com/openclaw/fs-safe/pull/971), [#959](https://github.com/openclaw/fs-safe/pull/959), [#966](https://github.com/openclaw/fs-safe/pull/966), [#955](https://github.com/openclaw/fs-safe/pull/955), [#968](https://github.com/openclaw/fs-safe/pull/968))
+
+### Features
+
+- **Native runtime health:** add async `getFsSafeNativeStatus()` with optional probing, path-free load reasons, and actionable guidance, exported from the root and `config` entry points. ([#965](https://github.com/openclaw/fs-safe/pull/965))
+- **Signed Windows binaries:** Authenticode-sign both Windows native addons and the security helper with timestamped OpenClaw Foundation signatures, and verify the signed bytes before publication. ([#960](https://github.com/openclaw/fs-safe/pull/960))
+
+### Fixes
+
+- **High-bit filesystem identities:** preserve Node's signed bigint stat identities across native directory checks, allowing guarded writes and build locks on filesystems with high-bit inode numbers. ([#979](https://github.com/openclaw/fs-safe/pull/979))
+- **Linux reflink fallback:** fall back to a guarded byte copy when FICLONE refuses I/O with `EIO` or `EAGAIN`, including ZFS block cloning; real copy and cleanup errors remain fatal. Reported in [openclaw/openclaw#169071](https://github.com/openclaw/openclaw/issues/169071). ([#972](https://github.com/openclaw/fs-safe/pull/972))
+- **Native fallback warnings:** explain why native support is unavailable, name the expected package version, and give cause-specific recovery guidance for Windows security and private-creation fallbacks. ([#961](https://github.com/openclaw/fs-safe/pull/961))
+
+### Performance
+
+- **Native directory creation:** retain parent handles during recursive mkdir, reducing the measured case from 160 to 5 promises and 381 to 74 Linux syscalls; nested mkdir also reuses existing parents. ([#971](https://github.com/openclaw/fs-safe/pull/971), [#959](https://github.com/openclaw/fs-safe/pull/959))
+- **Native writable-file creation:** reuse parent admission, reducing measured direct-root append syscalls from 117 to 36 and `openWritable` syscalls from 115 to 34 while retaining identity and cleanup checks. ([#966](https://github.com/openclaw/fs-safe/pull/966))
+- **Native Root verification:** batch verification and checked close to reduce dispatch overhead while retaining identity checks and close-error handling. ([#955](https://github.com/openclaw/fs-safe/pull/955))
+- **macOS file watching:** avoid JavaScript reconciliation for unrelated sibling writes and child-only changes to directory entry scopes while preserving missing-entry discovery and replacement notifications. ([#968](https://github.com/openclaw/fs-safe/pull/968))
+
+### Docs and Tooling
+
+- **Durable queue design:** document a link-free ownership protocol and mixed-version boundaries. ([#969](https://github.com/openclaw/fs-safe/pull/969))
+- **Benchmark comparisons:** balance independent build comparisons and restore benchmark setup in relocated checkouts. ([#976](https://github.com/openclaw/fs-safe/pull/976), [#970](https://github.com/openclaw/fs-safe/pull/970))
+
+## 0.26.2 - 2026-10-11
+
+### Highlights
+
+- **Windows receipt round trips:** use exact bigint identities from fs-safe receipts with the fail-closed identity checks introduced in 0.26.1. ([#962](https://github.com/openclaw/fs-safe/pull/962))
+
+### Fixes
+
+- **Windows file identity:** publication, reads, opens, directory and temporary-workspace receipts, typed listings, and clone metadata now expose bigint `exactIdentity`; publication failures expose `exactTargetIdentity`. Pass the exact form back to identity-checking APIs, including publication and copy expectations, to avoid rejecting rounded legacy Number identities on volumes with large file IDs. Existing exact copy and staged-file receipts remain supported. ([#962](https://github.com/openclaw/fs-safe/pull/962))
+
+### Performance
+
+- **Windows permission inspection:** avoid PowerShell startup for portable owner and ACL queries, about 8× faster in a Windows x64 probe, while preserving injected executors and .NET ACL semantics; requires .NET Framework 4.6.2+. ([#958](https://github.com/openclaw/fs-safe/pull/958))
+
+## 0.26.1 - 2026-10-11
+
+### Highlights
+
+- **Windows identity checks:** reject rounded file IDs; callers supplying identity stats must use bigint values. ([#949](https://github.com/openclaw/fs-safe/pull/949))
+- **Listings and copies:** measured listings are 38–54% faster on Linux and Windows; direct synchronous file copies are 11–31% faster, with Windows batches up to 48% faster. ([#934](https://github.com/openclaw/fs-safe/pull/934), [#932](https://github.com/openclaw/fs-safe/pull/932))
+- **Windows private creation:** the portable helper is about 5× faster, and private creation works beyond MAX_PATH. ([#930](https://github.com/openclaw/fs-safe/pull/930), [#924](https://github.com/openclaw/fs-safe/pull/924))
+- **Native overhead:** reduce dispatch and repeated admission for direct-child mkdir, removal, moves, existing-file opens, buffered publication, and async temp creation; measured eligible cases reach or improve on fallback performance while retaining native checks. ([#927](https://github.com/openclaw/fs-safe/pull/927), [#928](https://github.com/openclaw/fs-safe/pull/928), [#929](https://github.com/openclaw/fs-safe/pull/929), [#948](https://github.com/openclaw/fs-safe/pull/948), [#953](https://github.com/openclaw/fs-safe/pull/953))
+
+### Fixes
+
+- **Windows file identity:** stop accepting rounded Number file IDs as matches. Callers supplying identity stats must now pass bigint stats; unsafe Number identities fail with `path-mismatch`. ([#949](https://github.com/openclaw/fs-safe/pull/949))
+- **Windows long paths:** support private directory and file creation beyond MAX_PATH, including internal staging and pathname verification, while preserving ACL, alias, identity, and cleanup checks. ([#924](https://github.com/openclaw/fs-safe/pull/924))
+
+### Performance
+
+- **Listings and traversal:** avoid per-entry filename buffers for losslessly decoded names, making measured Linux and Windows listings 38–54% faster; halve per-entry promise allocation in complete sorted `Root.walk()` scans, improving measured 50,000-entry Linux walks by 3–4%. ([#934](https://github.com/openclaw/fs-safe/pull/934), [#937](https://github.com/openclaw/fs-safe/pull/937))
+- **File copies and moves:** reuse canonical admission in `copyRootFileSync`, improving measured direct copies by 11–31% on Linux and Windows and batches by up to 47–48% on Windows; reduce ordinary `Root.copyIn()` and same-parent move promise allocation without claiming a reproduced latency gain. ([#932](https://github.com/openclaw/fs-safe/pull/932), [#941](https://github.com/openclaw/fs-safe/pull/941), [#936](https://github.com/openclaw/fs-safe/pull/936))
+- **Reads and hashing:** trim file-admission and bounded-read metadata work for 2–9% faster measured Linux reads; reuse privately owned Windows handles for 42% faster native async SHA-256 on small pathname inputs, retaining borrowed-handle positions. ([#931](https://github.com/openclaw/fs-safe/pull/931), [#938](https://github.com/openclaw/fs-safe/pull/938))
+- **Locks and directories:** reduce uncontended sidecar-lock acquisition overhead by up to 34% with native; remove ordinary mkdir dispatch hops for 37% faster native direct-child creation, 17–22% faster existing-directory admission, and 81% faster native `ensureRoot` in the combined Linux benchmark. ([#939](https://github.com/openclaw/fs-safe/pull/939), [#944](https://github.com/openclaw/fs-safe/pull/944), [#927](https://github.com/openclaw/fs-safe/pull/927))
+- **Temporary workspaces and removal:** make measured empty-workspace cleanup 13–32% faster on Linux, create async workspaces through retained parents, and reduce recursive-removal stat allocation for 2–6% faster measured Linux recursive removal; retain identity-bound cleanup. ([#942](https://github.com/openclaw/fs-safe/pull/942), [#953](https://github.com/openclaw/fs-safe/pull/953), [#933](https://github.com/openclaw/fs-safe/pull/933))
+- **Private and exclusive creation:** run portable Windows security checks in a prebuilt helper for about 5× faster private creation; streamline exclusive-creation metadata and skip redundant Windows write-mode changes without removing flushes or permission checks. ([#930](https://github.com/openclaw/fs-safe/pull/930), [#935](https://github.com/openclaw/fs-safe/pull/935), [#940](https://github.com/openclaw/fs-safe/pull/940))
+- **Native operations:** reuse retained roots for removal and moves, defer parent creation until an opened file is missing, and streamline buffered creation and replacement-write publication; preserve descriptor-relative mutation and exact identity checks. Native non-durable publication reaches fallback parity in the measured cases; durable creation remains slower. ([#928](https://github.com/openclaw/fs-safe/pull/928), [#929](https://github.com/openclaw/fs-safe/pull/929), [#948](https://github.com/openclaw/fs-safe/pull/948))
+
+### Docs and Tooling
+
+- **Raw Node baseline:** add `pnpm benchmark:node` with alternating raw/safe/control samples and documented operation semantics; raw Node is a performance reference, not a security-equivalent implementation. ([#925](https://github.com/openclaw/fs-safe/pull/925))
+- **Native API reference:** enumerate APIs that require native bindings and their fallback availability. ([#926](https://github.com/openclaw/fs-safe/pull/926))
+
+## 0.26.0 - 2026-10-10
+
+### Highlights
+
+- **New platforms:** native packages for FreeBSD x64/arm64 and Windows ARM64. ([#905](https://github.com/openclaw/fs-safe/pull/905), [#893](https://github.com/openclaw/fs-safe/pull/893))
+- **Native capabilities:** anonymous pipes, Linux write leases, Darwin ACL inspection, ReFS block cloning, and metadata- and link-preserving `Root.copyIn`. ([#892](https://github.com/openclaw/fs-safe/pull/892), [#896](https://github.com/openclaw/fs-safe/pull/896), [#920](https://github.com/openclaw/fs-safe/pull/920), [#921](https://github.com/openclaw/fs-safe/pull/921))
+- **Android/Termux publication:** staged no-replace copies and writes work when the OS refuses hard links. ([#888](https://github.com/openclaw/fs-safe/pull/888))
+- **Performance:** faster deep archive extraction, borrowed-handle copies and overwrites, sidecar locks, and Linux descriptor verification, with identity checks retained. ([#912](https://github.com/openclaw/fs-safe/pull/912), [#906](https://github.com/openclaw/fs-safe/pull/906), [#902](https://github.com/openclaw/fs-safe/pull/902), [#901](https://github.com/openclaw/fs-safe/pull/901), [#899](https://github.com/openclaw/fs-safe/pull/899))
+
+### Features
+
+- **ReFS file copies:** support guarded `Root.copyIn` block cloning on Windows ReFS and Dev Drive, with exclusive publication, cancellation cleanup, and automatic byte-copy fallback for unavailable clone capabilities. ([#920](https://github.com/openclaw/fs-safe/pull/920))
+- **Guarded file copying:** add `Root.copyIn` metadata preservation and exclusive literal-link copying, including dangling Windows file and directory links; keep permission selection separate from timestamps and attributes. ([#921](https://github.com/openclaw/fs-safe/pull/921))
+
+- **Native filesystem capabilities:** add Linux write leases on caller-owned descriptors, no-follow Darwin ACL inspection with separate file and directory inheritance facts, and Windows sharing-lock, attribute, and physical-extent test fixtures. ([#896](https://github.com/openclaw/fs-safe/pull/896))
+- **Anonymous pipes:** add `@openclaw/fs-safe/pipe` with native-owned, reopenable close-on-exec pipe ends for one-shot child input on POSIX, including safe stream closure in Workers. ([#892](https://github.com/openclaw/fs-safe/pull/892))
+
+### Fixes
+
+- **Windows creation diagnostics:** retain native Win32 error numbers through private directory and file creation failures, including the command fallback, without changing semantic error codes. ([#919](https://github.com/openclaw/fs-safe/pull/919))
+- **FreeBSD native packages:** add x64 and arm64 packages for FreeBSD 14.4+, with native anonymous pipes and canonicalization, and explicit capability absence for unported operations. ([#905](https://github.com/openclaw/fs-safe/pull/905))
+- **Partial native bindings:** select guarded fallbacks when an operation's native capabilities are absent, and report typed capability errors in required mode before mutation. ([#905](https://github.com/openclaw/fs-safe/pull/905))
+- **Android/Termux publication:** publish staged no-replace copies and writes when hardlinks are refused, using a verified empty placeholder before atomic replacement; include `EACCES` in the public hardlink-to-copy fallback classifier. Reported in [openclaw/openclaw#167791](https://github.com/openclaw/openclaw/issues/167791). ([#888](https://github.com/openclaw/fs-safe/pull/888))
+- **Native ZIP names:** preserve CP437 decoding for unflagged legacy filenames after the ZIP 9 upgrade, including collision rejection and bounded entry selection; continue rejecting invalid Unicode Path checksums and encodings before decoder normalization. ([#885](https://github.com/openclaw/fs-safe/pull/885))
+- **Native ZIP Unicode fields:** retain rejection of invalid Unicode Comment CRCs and UTF-8 before callbacks or bounded reads, and validate sequential Unicode fields in decoder order without repeated hashing of the original name. ([#887](https://github.com/openclaw/fs-safe/pull/887))
+- **Portable ZIP extraction:** accept safe relative root-directory markers such as `./` from libarchive and other producers without turning them into absolute paths; root markers remain skipped before callbacks and publication. ([#886](https://github.com/openclaw/fs-safe/pull/886))
+- **Durable JSON queues on Android/Termux:** claim, failed-entry quarantine, and retirement recovery report typed `helper-unavailable` errors when hardlinks are refused, preserving pending, claimed, and retirement evidence for retry. ([#889](https://github.com/openclaw/fs-safe/pull/889))
+- **Windows exclusive publication:** preserve dangling destination symlinks when a refused hard link falls back to placeholder publication. ([#894](https://github.com/openclaw/fs-safe/pull/894))
+- **Native mkdir collisions:** `Root.mkdir` consistently reports `not-file` for an existing regular-file destination in native require mode. ([#895](https://github.com/openclaw/fs-safe/pull/895))
+- **Guest directory publication:** report a changed source identity instead of a false destination collision when a Linux fallback rename refuses a substituted source. ([#898](https://github.com/openclaw/fs-safe/pull/898))
+- **Native recursive removal:** honor a zero entry budget before ignoring a missing target, including with `force`. ([#904](https://github.com/openclaw/fs-safe/pull/904))
+
+### Performance
+
+- **Linux opened-file verification:** read ordinary procfs descriptor paths directly instead of walking realpath, keeping identity checks and deleted-path canonicalization; `readLocalFileSafely` is 25–28% faster on deep paths. ([#899](https://github.com/openclaw/fs-safe/pull/899))
+- **Borrowed handles and locks:** keep descriptor metadata inspection off the asynchronous I/O queue for small overwrites (26–28% faster) and copies (31–34% faster), and skip a redundant parent `mkdir` when acquiring sidecar locks (15–18% faster). ([#901](https://github.com/openclaw/fs-safe/pull/901), [#902](https://github.com/openclaw/fs-safe/pull/902), [#906](https://github.com/openclaw/fs-safe/pull/906))
+- **Deep archive extraction:** native extraction verifies every retained ancestor through its open descriptor instead of repeated realpath walks: about 16% faster at depth 8 and 5–6% at depth 4, with every ancestor substitution check retained. ([#912](https://github.com/openclaw/fs-safe/pull/912))
+
+### Docs and Tooling
+
+- **Docs accuracy:** correct native-mode migration guidance for removed Python settings and bundled TAR fallbacks, clarify Root streaming ownership, create-only visibility, and Linux no-clobber move fallback limits, and fix the JSON-store and stale-lock examples so denied process probes keep live locks; README and docs examples are now type-checked in CI. ([#897](https://github.com/openclaw/fs-safe/pull/897), [#900](https://github.com/openclaw/fs-safe/pull/900), [#903](https://github.com/openclaw/fs-safe/pull/903))
+
+### Compatibility
+
+- **Windows ARM64:** add a native ARM64 package with real Windows 11 ARM64 and x64-emulation validation, including private ACL creation and Worker descriptor ownership. ([#893](https://github.com/openclaw/fs-safe/pull/893))
+
+- **Native ZIP metadata:** invalid UTF-8-flagged names now reject instead of decoding lossily or falling back to CP437. Public ZIP extraction, preflight, and reads already reject these names during physical admission. ([#885](https://github.com/openclaw/fs-safe/pull/885))
+
 ## 0.25.0 - 2026-10-08
 
 ### Highlights

package/node_modules/@openclaw/fs-safe/README.md

@@ -10,6 +10,9 @@
 
 Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.
 
+Platform-specific additions include [Linux write leases, Darwin ACL inspection,
+and Windows test fixtures](docs/platform-capabilities.md).
+
 Think Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), but for Node. Hand `root()` a trusted directory and you get back a handle whose every method resolves relative paths against it and defends against `..`, symlink swaps, hardlink aliases, and TOCTOU rename races. The exact containment strength is reported per mechanism: Linux `openat2` opens are kernel-atomic; guarded Linux fallback, macOS, Windows, and JavaScript paths are best-effort.
 
 ```ts
@@ -81,6 +84,12 @@ kernel-atomic. Read the [native helper policy](docs/native-helper.md) and
 [operation/platform matrix](docs/security-model.md#native-root-mutation-capabilities)
 when concurrent mutation is in scope.
 
+For doctor/startup checks, use
+[`await getFsSafeNativeStatus({ probe: true })`](docs/config.md#getfssafenativestatus-options)
+from `@openclaw/fs-safe/config` to report whether the native addon is active,
+why it is unavailable, and what to do next. Calling it without options only reads
+the cache. Status is per module instance; Workers must be checked separately.
+
 ## Migrating from the Python helper
 
 Version 0.5 replaced the Python worker with prebuilt native bindings. Follow the
@@ -113,9 +122,14 @@ operation; per-call options handle exceptions. See the [Root reference](docs/roo
 
 `write()` replaces contents by default. Use `create()` or `overwrite: false`
 when an existing destination should be an error. `move()` defaults to no clobber
-and requires native support for the atomic collision decision; it fails with
-`helper-unavailable` when unavailable. Pass `overwrite: true` when replacement
-is intended.
+and requires native support. On Linux, `auto` can replace a concurrently created
+empty directory if no-replace rename is unsupported; use native `require` for
+strict refusal. See the [move fallback contract](docs/writing.md#fs-move-from-to-options).
+Pass `overwrite: true` when replacement is intended.
+
+Staged JavaScript copies and creates also work when hardlinks are refused
+(including Android/Termux), using a verified empty placeholder before atomic
+replacement. See the [visibility and concurrency tradeoffs](docs/writing.md#publication-without-hardlinks).
 
 See [Writing](docs/writing.md) for copy sources, mutation authority, symlink
 policy, writable handles, and bounded removal, and [Creation](docs/creation.md)
@@ -159,6 +173,8 @@ and error exports. Prefer focused subpaths when a consumer needs a narrower
 contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are grouped under
 `@openclaw/fs-safe/advanced` instead of being separate public leaf contracts.
 
+Use [`@openclaw/fs-safe/pipe`](docs/pipe.md) for native-owned, reopenable anonymous pipes and one-shot child input.
+
 See the [complete subpath catalogue](docs/install.md#subpath-exports) for every entry point and its contents.
 
 ## Failure semantics in the name
@@ -236,7 +252,7 @@ updates:
 import { fileStore } from "@openclaw/fs-safe/store";
 
 const files = fileStore({ rootDir: "/safe/workspace/state", private: true });
-const store = files.json("settings.json", { lock: true });
+const store = files.json<{ enabled: boolean }>("settings.json", { lock: true });
 
 await store.updateOr({ enabled: false }, (current) => ({ ...current, enabled: true }));
 ```

package/node_modules/@openclaw/fs-safe/dist/advanced.d.ts

@@ -17,7 +17,7 @@ export { readFileWindowFully, readFileWindowFullySync, type ReadFileWindowOption
 export { writeFileWindowFully, type WriteFileWindowOptions } from "./write-file-handle.js";
 export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, type UnsafeDeviceReadPathMatch, type UnsafeDeviceReadPathOptions, type UnsafeDeviceReadPathReason, } from "./device-path.js";
 export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, ensureAbsoluteDirectory, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, type AbsolutePathSymlinkPolicy, type EnsureAbsoluteDirectoryOptions, type EnsureAbsoluteDirectoryResult, type ResolvedAbsolutePath, type ResolvedWritableAbsolutePath, } from "./absolute-path.js";
-export { sameFileIdentity, type FileIdentityStat } from "./file-identity.js";
+export { sameFileIdentity, type FileIdentityStat, type FileIdentityInput, type ExactFileIdentity, type ExactIdentityReceipt } from "./file-identity.js";
 export { sanitizeUntrustedFileName } from "./filename.js";
 export { pathExists, pathExistsSync } from "./fs.js";
 export { resolveLocalPathFromRootsSync, readLocalFileFromRoots, type LocalRootsInputOptions, type LocalRootsPathResult, type LocalRootsReadResult, type ReadLocalFileFromRootsOptions, type ResolveLocalPathFromRootsSyncOptions, } from "./local-roots.js";
@@ -26,6 +26,7 @@ export { formatPosixMode } from "./permissions.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
 export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, type PathAliasPolicy, } from "./path-policy.js";
 export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, type OpenRootFileParams, type OpenRootFileSyncParams, type RootFileOpenFailure, type RootFileOpenFailureReason, type RootFileOpenResult, } from "./root-file.js";
+export { createRootFileOpenBatchSync, type RootFileOpenBatchSync } from "./root-file-open-batch-sync.js";
 export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, type ResolvedRootPath, type RootPathAliasPolicy, } from "./root-path.js";
 export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, type PathScope, type PathScopeOptions, type PathScopeResolveOptions, } from "./root-paths.js";
 export { safeDirName, safePathSegmentHashed, safePathSegmentHashedV2, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";

package/node_modules/@openclaw/fs-safe/dist/advanced.js

@@ -27,6 +27,7 @@ export { formatPosixMode } from "./permissions.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";
 export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, } from "./path-policy.js";
 export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, } from "./root-file.js";
+export { createRootFileOpenBatchSync } from "./root-file-open-batch-sync.js";
 export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, } from "./root-path.js";
 export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, } from "./root-paths.js";
 export { safeDirName, safePathSegmentHashed, safePathSegmentHashedV2, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";

package/node_modules/@openclaw/fs-safe/dist/archive-merge.js

@@ -17,6 +17,7 @@ import { syncFileBestEffortSync } from "./file-sync.js";
 import { finalizeArchivePublication } from "./archive-durability.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { ArchiveSecurityError } from "./archive-errors.js";
 export async function withStagedArchivePublication(params, extract) {
     await withStagedArchiveDestination({
         destinationRealDir: params.destinationGuard.realPath,
@@ -101,6 +102,23 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
         assertDirectoryIdentityGuard(destinationGuard);
         check();
         for (const ancestor of ancestors) {
+            // Verify every retained ancestor, including its current name and physical path.
+            // Shallow chains cost less to verify directly than crossing the native bridge.
+            if (ancestors.length >= 4 && ancestor.owner.verifyCanonical) {
+                let verified;
+                try {
+                    verified = await ancestor.owner.verifyCanonical();
+                }
+                catch (error) {
+                    if (error instanceof FsSafeError || isNotFoundPathError(error)) {
+                        throw createArchiveSymlinkTraversalError(path.relative(destinationDir, ancestor.guard.dir));
+                    }
+                    throw error;
+                }
+                check();
+                if (verified)
+                    continue;
+            }
             assertDirectoryIdentityGuard(ancestor.guard);
             check();
             await ancestor.owner.verify(check);
@@ -156,15 +174,22 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
                     await ownExtractionDestinationMutation(params.deadline, async () => {
                         await assertGuards();
                         assertSourceFrontier();
-                        const owner = await pinNodeDirectoryForMode(destinationPath).catch((error) => {
+                        const guard = await createDirectoryIdentityGuard(destinationPath).catch((error) => {
+                            if (error instanceof ArchiveSecurityError && error.code === "destination-symlink") {
+                                throw createArchiveSymlinkTraversalError(originalPath);
+                            }
+                            throw error;
+                        });
+                        check();
+                        const owner = await pinNodeDirectoryForMode(destinationPath, {
+                            expectedIdentity: guard.stat, canonicalPath: guard.realPath,
+                        }).catch((error) => {
                             if (error instanceof FsSafeError && (error.code === "not-file" || error.code === "path-mismatch")) {
                                 throw createArchiveSymlinkTraversalError(originalPath);
                             }
                             throw error;
                         });
                         try {
-                            check();
-                            const guard = await createDirectoryIdentityGuard(destinationPath);
                             check();
                             await owner.verify(check);
                             ancestors.push({ guard, owner });

package/node_modules/@openclaw/fs-safe/dist/archive-read.js

@@ -17,7 +17,7 @@ import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { realpathSync } from "./realpath.js";
-import { getNativeBinding } from "./native.js";
+import { assertNativeCapabilities, getNativeBinding } from "./native.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
 import { validateNativeZipManifest } from "./archive-zip-manifest.js";
 import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
@@ -199,9 +199,15 @@ async function readNativeBufferEntry(native, buffer, kind, requested, displayPat
     try {
         const signal = new AbortController().signal;
         const limits = resolveTarMeterLimits();
-        const reader = kind === "zip"
-            ? await native.openZipBufferNative(buffer, limits, AbortSignal.any([signal]))
-            : await native.openTarBufferNative(buffer, kind, limits, AbortSignal.any([signal]));
+        let reader;
+        if (kind === "zip") {
+            assertNativeCapabilities(native, "openZipBufferNative");
+            reader = await native.openZipBufferNative(buffer, limits, AbortSignal.any([signal]));
+        }
+        else {
+            assertNativeCapabilities(native, "openTarBufferNative");
+            reader = await native.openTarBufferNative(buffer, kind, limits, AbortSignal.any([signal]));
+        }
         const manifest = reader.entries;
         if (kind === "zip")
             validateNativeZipManifest(manifest, zipEntries);
@@ -227,7 +233,7 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
     const zipEntries = [];
     if (kind === "zip")
         admitZipBuffer(buffer, resolveExtractLimits(), entry => { zipEntries.push(entry); });
-    const native = getNativeBinding();
+    const native = getNativeBinding(kind === "zip" ? "openZipBufferNative" : "openTarBufferNative");
     if (native)
         return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, maxBytes, zipEntries);
     return kind === "zip" ? await readZipEntry(buffer, requestedEntry, maxBytes, zipEntries)

package/node_modules/@openclaw/fs-safe/dist/archive-zip-loader.js

@@ -118,11 +118,13 @@ export async function loadAdmittedZipArchive(buffer, admitted) {
     const entries = new Map();
     for (const [name, entry, physical] of normalized) {
         const appendSlash = physical.kind === "directory" && !name.endsWith("/");
-        const normalizedName = appendSlash ? `${name}/` : name;
+        // JSZip reduces a relative root marker such as "./" to an empty name.
+        // Keep its directory spelling relative when restoring the terminal slash.
+        const normalizedName = appendSlash ? `${name || "."}/` : name;
         if (Object.hasOwn(files, normalizedName))
             collision();
         if (appendSlash) {
-            entry.name = `${entry.name}/`;
+            entry.name = `${entry.name || "."}/`;
         }
         files[normalizedName] = entry;
         entries.set(physical.portableKey, createAdmittedZipEntry(entry, normalizedName, physical));

package/node_modules/@openclaw/fs-safe/dist/archive.js

@@ -154,7 +154,7 @@ export async function extractArchive(params) {
     const label = kind === "zip" ? "extract zip" : "extract tar";
     const limits = resolveExtractLimits(params.limits);
     const tarLimits = resolveTarMeterLimits(limits);
-    const native = getNativeBinding();
+    const native = getNativeBinding("inspectArchiveNative", "extractArchiveNative");
     assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
     assertNoWindowsPathAlias(destDir, "filesystem", "archive destination uses a Windows filesystem namespace alias");
     // Read the declared public fields before private adapters copy options: class
@@ -282,7 +282,7 @@ export async function inspectTarArchive(params) {
     const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
     const limits = resolveExtractLimits(params.limits);
     const tarLimits = resolveTarMeterLimits(limits);
-    const native = getNativeBinding();
+    const native = getNativeBinding("inspectArchiveNative");
     assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
     return await withExtractionDeadline(params.timeoutMs, "inspect tar", async (deadline) => {
         const staged = await stageArchiveFileForExtraction({ archivePath, limits, deadline });

package/node_modules/@openclaw/fs-safe/dist/atomic-io.js

@@ -1,6 +1,6 @@
 import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
-import { readBoundedSync } from "./bounded-read.js";
+import { readBoundedSync, readFileHandleBounded } from "./bounded-read.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { sleep, sleepSync } from "./timing.js";
@@ -207,7 +207,7 @@ export class AtomicFile {
     }
     *readFile(sizeHint) {
         if (typeof this.resource !== "number")
-            return yield* wait(this.resource.readFile());
+            return yield* wait(readFileHandleBounded(this.resource, Infinity));
         if (sizeHint === undefined)
             return this.io.syncFs.readFileSync(this.resource);
         const fd = this.resource;

package/node_modules/@openclaw/fs-safe/dist/bounded-read.d.ts

@@ -13,6 +13,7 @@ export declare function readBoundedAsync(maxBytes: number, readChunk: (scratch:
  * force an unbounded allocation.
  */
 export declare function readFileHandleBounded(handle: ReadableFileHandle, maxBytes: number): Promise<Buffer>;
+export declare function readFileHandleBoundedWithSize(handle: ReadableFileHandle, maxBytes: number, initialSize?: number): Promise<Buffer>;
 /** Async bounded read from a numeric descriptor. The caller owns the descriptor. */
 export declare function readFileDescriptorBounded(fd: number, maxBytes: number): Promise<Buffer>;
 export declare function readBoundedSync(maxBytes: number, readChunk: (scratch: Buffer, length: number) => number, options?: {

package/node_modules/@openclaw/fs-safe/dist/bounded-read.js

@@ -73,11 +73,18 @@ export async function readBoundedAsync(maxBytes, readChunk, options = {}) {
  * force an unbounded allocation.
  */
 export async function readFileHandleBounded(handle, maxBytes) {
+    return await readFileHandleBoundedWithSize(handle, maxBytes);
+}
+// Internal: the admitted size bounds the first allocation, never the read.
+export function readFileHandleBoundedWithSize(handle, maxBytes, initialSize) {
     normalizeMaxBytes(maxBytes);
     const fd = "fd" in handle && typeof handle.fd === "number" ? handle.fd : undefined;
-    return await readBoundedAsync(maxBytes, async (scratch, length) => {
+    return readBoundedAsync(maxBytes, async (scratch, length) => {
         return (await handle.read(scratch, 0, length, null)).bytesRead;
-    }, { observeRegularFileSize: fd === undefined ? undefined : () => regularFileSize(fd) });
+    }, {
+        initialSize,
+        observeRegularFileSize: fd === undefined ? undefined : () => regularFileSize(fd),
+    });
 }
 function regularFileSize(fd) {
     try {

package/node_modules/@openclaw/fs-safe/dist/clone-metadata.d.ts

@@ -1,4 +1,6 @@
+import type { ExactFileIdentity } from "./exact-identity.js";
 export type CloneFileMetadata = {
+    exactIdentity?: ExactFileIdentity;
     dev: number;
     type: number;
     mtimeSec: number;

package/node_modules/@openclaw/fs-safe/dist/clone-metadata.js

@@ -6,7 +6,7 @@ import { getNativeBinding, requireNativeBinding } from "./native.js";
  */
 export async function readCloneFileMetadata(files) {
     const paths = files.map(assertAbsolutePathInput);
-    const native = process.platform === "darwin" ? requireNativeBinding() : getNativeBinding();
+    const native = process.platform === "darwin" ? requireNativeBinding("readCloneFileMetadata") : getNativeBinding("readCloneFileMetadata");
     if (!native)
         return paths.map(() => undefined);
     const results = await native.readCloneFileMetadata(paths);
@@ -19,6 +19,7 @@ export async function readCloneFileMetadata(files) {
             result.readUInt32LE(20) !== 0x100)
             return undefined;
         return {
+            exactIdentity: Object.freeze({ dev: BigInt(result.readUInt32LE(24)), ino: result.readBigInt64LE(76) }),
             dev: result.readUInt32LE(24),
             type: result.readUInt32LE(28),
             mtimeSec: Number(result.readBigInt64LE(32)),

package/node_modules/@openclaw/fs-safe/dist/config.d.ts

@@ -1,2 +1,8 @@
+import type { FsSafeNativeStatus } from "./native-status.js";
 export { configureFsSafeNative, getFsSafeNativeConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
+export type { FsSafeNativeStatus, FsSafeNativeStatusReason, } from "./native-status.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
+/** Read native status without loading the native module on config import. */
+export declare function getFsSafeNativeStatus(options?: {
+    probe?: boolean;
+}): Promise<FsSafeNativeStatus>;

package/node_modules/@openclaw/fs-safe/dist/config.js

@@ -1,2 +1,7 @@
 export { configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";
+/** Read native status without loading the native module on config import. */
+export async function getFsSafeNativeStatus(options) {
+    const { readFsSafeNativeStatus } = await import("./native-status.js");
+    return readFsSafeNativeStatus(options);
+}

package/node_modules/@openclaw/fs-safe/dist/copy-file-input.d.ts

@@ -3,19 +3,21 @@ import type { FileHandle } from "node:fs/promises";
 import { type CopyCloneMode } from "./copy-policy.js";
 import { type NativeBinding } from "./native.js";
 import { type NativeFileCopyResult } from "./native-binding.js";
+import type { CopyMetadata } from "./copy-metadata.js";
 export type CopyFileInput = {
     kind: "file";
     handle: FileHandle;
     size: number;
     clone: CopyCloneMode;
     signal?: AbortSignal;
+    metadata?: CopyMetadata;
     verifySource(): Promise<void>;
 };
 export declare function resolveFileCopyCloneMode(mode?: CopyCloneMode): CopyCloneMode;
 export declare function assertCopySourceCurrent(source: {
     handle: FileHandle;
     realPath: string;
-}, identity: BigIntStats): Promise<void>;
+}, identity: BigIntStats): void;
 export declare function writeCopyFileToFd(fd: number, input: CopyFileInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;
 export declare function createNativeCopyFile(native: NativeBinding, input: CopyFileInput, parentFd: number, basename: string, maxBytes: number | undefined): Promise<NativeFileCopyResult | undefined>;
 export declare function assertNativeCopyCompleted(input: CopyFileInput, copied?: NativeFileCopyResult): void;

package/node_modules/@openclaw/fs-safe/dist/copy-file-input.js

@@ -1,9 +1,9 @@
 import fs, {} from "node:fs";
 import { resolveCopyCloneMode } from "./copy-policy.js";
 import { FsSafeError } from "./errors.js";
-import { getNativeBinding } from "./native.js";
+import { getNativeBinding, selectNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { transferFileHandle } from "./file-handle-transfer.js";
 export function resolveFileCopyCloneMode(mode) {
     const clone = resolveCopyCloneMode(mode, "never");
@@ -12,9 +12,9 @@ export function resolveFileCopyCloneMode(mode) {
     }
     return clone;
 }
-export async function assertCopySourceCurrent(source, identity) {
-    await inspectFileIdentity(() => fs.fstatSync(source.handle.fd, { bigint: true }), identity);
-    await inspectFileIdentity(() => {
+export function assertCopySourceCurrent(source, identity) {
+    inspectFileIdentitySync(() => fs.fstatSync(source.handle.fd, { bigint: true }), identity);
+    inspectFileIdentitySync(() => {
         const current = fs.lstatSync(source.realPath, { bigint: true });
         if (current.isSymbolicLink() || !current.isFile()) {
             throw new FsSafeError("path-mismatch", "copy source path changed");
@@ -29,7 +29,8 @@ export async function writeCopyFileToFd(fd, input, maxBytes, assertBeforeMutatio
 }
 export async function createNativeCopyFile(native, input, parentFd, basename, maxBytes) {
     input.signal?.throwIfAborted();
-    if (!native.copyFileExclusive) {
+    const copier = selectNativeBinding(native, "copyFileExclusive");
+    if (!copier) {
         if (input.clone === "always") {
             throw new FsSafeError("helper-unavailable", "native file cloning is unavailable");
         }
@@ -39,7 +40,7 @@ export async function createNativeCopyFile(native, input, parentFd, basename, ma
     const nativeSignal = input.signal ? AbortSignal.any([input.signal]) : undefined;
     try {
         // The caller adopts this descriptor before observing a later cancellation.
-        return await native.copyFileExclusive(input.handle.fd, parentFd, basename, input.clone, maxBytes !== undefined && Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
+        return await copier.copyFileExclusive(input.handle.fd, parentFd, basename, input.clone, maxBytes !== undefined && Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
     }
     catch (error) {
         const code = error?.code;

package/node_modules/@openclaw/fs-safe/dist/copy-link.d.ts

@@ -0,0 +1,26 @@
+import { type BigIntStats } from "node:fs";
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { NativeBinding } from "./native-binding.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
+export type CopyLinkInput = {
+    kind: "link";
+    stageBeforePublish: true;
+    sourcePath: string;
+    identity: BigIntStats;
+    target?: Buffer;
+    preserveMetadata: boolean;
+    signal?: AbortSignal;
+    verifySource(): Promise<void>;
+};
+/** Shared by tree byte copying and per-file copying; never resolves the target. */
+export declare function readCopyLinkTarget(source: string): Promise<Buffer>;
+export declare function assertCopyLinkAvailable(): void;
+export declare function admitCopyLink(sourcePath: string, preserveMetadata: boolean, signal?: AbortSignal): Promise<CopyLinkInput | undefined>;
+/** The caller has admitted the destination parent under Root's mutation policy. */
+export declare function copyLinkAtParent(params: PinnedWriteParams, input: CopyLinkInput, parent: AnyAsyncDirectoryGuard, native?: {
+    binding: NativeBinding;
+    fd: number;
+}): Promise<{
+    dev: bigint;
+    ino: bigint;
+}>;