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

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

@@ -87,6 +87,12 @@ be exactly representable. Ambiguous identity fails closed.
 Returned receipts are frozen descriptive snapshots, not mutable authority.
 Changing a supplied receipt after admission cannot retarget the lifecycle.
 
+Use `fs.lstat(path, { bigint: true })` for caller-created directory receipts:
+bigint stats retain exact Windows file IDs. Copied or reconstructed receipts
+with unsafe Number identities reject with `FsSafeError("path-mismatch")`.
+Original library receipts retain their private exact identity even when their
+public numeric metadata cannot represent every bit.
+
 `StagedFileReceipt` contains `directory` (`path`, `realPath`, and exact bigint
 `identity.dev`/`identity.ino`), `temporaryBasename`, and the prepared file's
 `identity` (`dev`, `ino`, `size`, `nlink`, `mtimeNs`, `ctimeNs` as bigint;
@@ -197,3 +203,15 @@ they do not gain this cleanup authority.
 - [Advanced composition](advanced.md)
 - [Native architecture](native.md)
 - [Security model](security-model.md)
+
+## Round-tripping identities
+
+`StagedFileReceipt.identity` and `directory.identity` already contain exact
+bigint `dev`/`ino` values. Retain those values directly; do not convert them to
+Number. `PublishedFileReceipt.staged.identity` is the same staged file's identity,
+not a new pathname observation. File metadata such as size and timestamps is a
+preparation-time snapshot and can change during writing. Publication callbacks
+using `PublishedWriteIdentity` likewise already return exact bigint identities.
+
+For the standalone `publishFileExclusive()` API, retain its `exactIdentity`
+companion instead of its legacy `identity: Stats`; see [directory durability](durability.md#exclusive-file-publication).

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

@@ -84,6 +84,21 @@ Batch loading skips invalid entry names, malformed, oversized, or unreadable ent
 
 Failed destinations are create-only. Quarantine publishes the claimed file by hardlink, so the queue and failed directories must share a filesystem with hardlink support. If `failed/<id>.json` already exists, quarantine rejects while preserving both that earlier evidence and the current claimed entry instead of overwriting either file. The `read` callback continues to receive the logical `.json` path even though bytes are read and migrations are written through the claimed path.
 
+Claim, quarantine, and retirement recovery require hardlinks. If a link syscall
+is refused with `EACCES`, `EPERM`, `EXDEV`, `ENOTSUP`, `EOPNOTSUPP`, or `ENOSYS`,
+the operation rejects with `FsSafeError("helper-unavailable")` and retains the
+original error in `cause`. This includes Android/Termux environments that deny
+hardlinks. The refusal leaves the pending entry, processing claim, or retirement
+record intact for retry after the capability or permission problem is resolved;
+it does not acknowledge delivery. Batch loading propagates this capability
+failure too. The queue does not fall back to copying or overwriting rename:
+those operations cannot preserve its shared-inode recovery and create-only
+collision evidence. Enqueue alone does not prove that an entry can be claimed.
+
+The [link-free queue design](queue-link-free-design.md) describes an unimplemented
+v2 candidate and its mixed-version barriers. It does not change these helpers or
+provide Android/Termux queue support.
+
 Migrations stay bound to the exact processing file opened for that load. The
 read descriptor remains pinned while the callback runs outside the transfer
 lock; after the callback returns, migration reacquires the lock and rechecks the

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

@@ -47,6 +47,26 @@ under trusted ancestry. Do not make shared `/tmp` private or take ownership of
 another user's directory. A caller's preferred root takes precedence over
 `TMPDIR`; changing `TMPDIR` only changes the resolver's fallback location.
 
+On Android only (`process.platform === "android"`), ancestors may also be owned
+by Android's OS system identity, AID_SYSTEM (UID 1000). The system is trusted like
+root; this does not trust arbitrary foreign UIDs or stop the walk at `HOME` or
+`PREFIX`. Mode/sticky checks still apply, with one Android group-write exception:
+an ancestor's group may write when both owner and group are AID_SYSTEM and the
+caller belongs to neither that effective nor supplementary group, or when both
+are the calling app's private Android UID/GID (app ID 10000–19999, including
+multi-user UID offsets). Android reserves those groups for the system or the
+same app identity. Unknown group membership fails closed for system-owned
+group-writable ancestors. World-write still needs sticky protection.
+
+This admits Termux's system-owned `/data` and `/data/data` at `0771` and its
+app-owned `files` ancestor at `0771`, without allowing another app or an
+untrusted writable group to replace the next child. Canonical ancestors are
+rechecked through `/`; symlink/type and identity checks remain in force. The
+supplied temp root and created workspace must still be owned by the effective
+user and reject **all** group/world write, including these Android groups and
+sticky directories. No Android native-addon or Linux user-namespace assumption
+is made by this policy.
+
 On Linux, non-identity `/proc/self/uid_map` and `/proc/self/gid_map` evidence
 permits ancestors whose UID and GID equal unmapped kernel overflow IDs,
 provided the same ancestor mode checks pass.
@@ -209,6 +229,17 @@ identity before opening it, rejects mount crossings, and traverses descendants
 only through opened directory handles; symlinks/reparse entries are removed as
 leaves and never traversed. Windows marks the exact opened objects for deletion by handle.
 
+Empty quarantines can be removed without directory enumeration: the native
+helper can attempt a descriptor-relative empty-directory removal, and the
+compatible POSIX JavaScript path can attempt `rmdir`. Unchanged creation timestamps
+select this attempt as a performance hint, never as emptiness or ownership proof;
+all fresh identity checks still run. Changed timestamps and nonempty directories
+continue through the same guarded recursive removal. The native empty attempt is bounded
+and synchronous, including for async workspaces; recursive native cleanup stays
+asynchronous. Older bindings and Windows compatible cleanup retain their
+existing recursive route; Windows can defer directory timestamp changes, so
+the empty-attempt hint does not select a faster compatible path there.
+
 POSIX has no unlink-by-fd or expected-inode unlink for directory entries. After
 the final identity check, each `unlinkat` can still be raced; the possible side
 effect is bounded to one substituted non-directory leaf or one empty directory
@@ -754,3 +785,11 @@ it("processes a fixture", async () => {
 - [Atomic writes](atomic.md) — `replaceDirectoryAtomic` for whole-directory swaps.
 - [`root()`](root.md) — `fs.copyIn(rel, sourceAbs)` for moving files from a temp into a `Root`.
 - [File lock](sidecar-lock.md) — when many processes share a temp tree.
+
+## Exact workspace receipts
+
+`tempWorkspace()` and `tempWorkspaceSync()` return `exactIdentity` alongside
+their unchanged legacy `identity`. Preserve the bigint companion for identity
+comparisons. `tempFile().identity` already uses bigint `dev` and `ino` and needs
+no conversion. Cleanup retains its own exact authority; editing or discarding a
+public receipt does not rebind cleanup to another file or directory.

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

@@ -135,6 +135,19 @@ Lifecycle memory is sampled across ten intervals, with
 the first two excluded as warm-up; idle's Linux wakeup bound scales with the
 requested duration (three per minute). Adversarial cases remain unchanged.
 
+## Native syscall budgets
+
+After building the host addon and package, run the Linux syscall proof with
+`node scripts/native-call-budget-proof.mjs --operation remove` (or `mkdir`,
+`ensureRoot`, `move`, `append`, `openWritable`, `create`, `write`, `tempWorkspace`).
+It traces all threads with `strace -f -yy` and enforces exact per-mode syscall
+and async-resource counts. Canonicalization ancestors and worker-thread I/O
+remain counted. The only runtime filesystem exclusion is Node/V8 Abseil's
+read-only open of `/sys/devices/system/cpu/cpu0/tsc_freq_khz`, a lazy CPU-clock
+probe unrelated to the temporary fixture that can occur on the main thread.
+Other sysfs calls and subsequent I/O remain counted. Failed proofs print the
+retained raw trace path for diagnosis.
+
 ## Linux openat2 fallback
 
 Build the host addon and package first. The test hook is cached with the native

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

@@ -38,7 +38,7 @@ type PathStat = {
 };
 ```
 
-The shape returned by `Root.stat()`. It is a serializable view of the identity,
+The shape returned by `Root.stat()`. Its enumerable fields are a serializable legacy view of the identity,
 ownership, mode, size, timestamp, link count, and three file-kind facts the
 boundary uses. Unlike Node's `Stats`, `isFile`, `isDirectory`, and
 `isSymbolicLink` are boolean fields rather than methods.
@@ -79,103 +79,68 @@ Used by helpers that accept either an encoding (returning a string) or `null` (r
 
 ## `OpenResult` / `ReadResult`
 
-Returned by `Root.open()` and `Root.read()`:
+Import the result types rather than copying their shapes:
 
 ```ts
-type OpenResult = {
-  handle: import("node:fs/promises").FileHandle;
-  containment: "kernel-atomic" | "best-effort";
-  realPath: string;
-  stat: import("node:fs").Stats;
-};
-
-type ReadResult = {
-  buffer: Buffer;
-  containment: "kernel-atomic" | "best-effort";
-  realPath: string;
-  stat: import("node:fs").Stats;
-};
+import type { OpenResult, ReadResult, WritableOpenResult } from "@openclaw/fs-safe/root";
 ```
 
 `realPath` is the canonical real path the read or open landed on, after symlink resolution; `stat` is the verified `fstat` result. Public root results currently report `containment: "best-effort"`; the union also describes direct native `openBeneath()` results, which report `"kernel-atomic"` on Linux. See the [security model](security-model.md#containment-guarantees-by-platform).
 
+`ReadResult` carries the read `buffer`. `OpenResult` and `WritableOpenResult`
+carry an owned Node `FileHandle` as `handle` and implement
+`[Symbol.asyncDispose]()`; use `await using` or explicitly close the handle.
+See [reading](reading.md#fs-open-rel-options) and
+[writable handles](writing.md#openwritable-for-streaming) for ownership and streaming.
+
 ## `RootDefaults` / `RootOptions`
 
 ```ts
-type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
-
-type RootDefaults = {
-  assertBeforeMutation?: () => void;
-  denyMutations?: DenyMutationPolicy;
-  durable?: boolean; // default true for write/create/writeJson/createJson/append
-  hardlinks?: "reject" | "allow";
-  maxBytes?: number;
-  mkdir?: boolean; // default true for mutation methods
-  mode?: number;
-  renameIdentity?: RenameIdentityPolicy;
-  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
-  mutationSymlinks?: MutationSymlinkPolicy;
-};
-
-type DenyMutationPolicy = {
-  paths?: readonly string[];
-  prefixes?: readonly string[];
-};
-
-type RootOptions = {
-  rootDir: string;
-  defaults?: RootDefaults;
-};
+import type {
+  DenyMutationPolicy,
+  RenameIdentityPolicy,
+  RootDefaults,
+  RootOptions,
+} from "@openclaw/fs-safe/root";
 ```
 
-`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these. `denyMutations` and `assertBeforeMutation` are exceptions: deny entries are merged, and the root authority assertion runs before the per-call assertion.
+`RootDefaults` is what `root(rootDir, defaults)` accepts. `RootOptions` is the
+`{ rootDir, defaults? }` record. See the [Root signature and defaults](root.md#signature)
+for fields and behavior. `denyMutations` and `assertBeforeMutation` compose with
+per-call restrictions: deny entries are merged, and the root authority assertion
+runs before the per-call assertion.
 
 ## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
 
 ```ts
-import type { CopyCloneMode, RootCopyPublicationReceipt } from "@openclaw/fs-safe";
-
-type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity" | "mutationSymlinks"> & {
-  encoding?: BufferEncoding;
-  overwrite?: boolean;
-};
-type RootCopyOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "maxBytes" | "mkdir" | "mode" | "mutationSymlinks"> & {
-  sourceHardlinks?: "reject" | "allow";
-  overwrite?: boolean;
-  clone?: CopyCloneMode;
-  signal?: AbortSignal;
-  preserveSourceMode?: boolean;
-  onDestinationPublished?: (receipt: RootCopyPublicationReceipt) => void;
-};
-type RootOpenWritableOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mkdir" | "mode" | "mutationSymlinks"> & {
-  writeMode?: "replace" | "append" | "update";
-};
-type RootWriteJsonOptions = RootWriteOptions & {
-  replacer?: Parameters<typeof JSON.stringify>[1];
-  space?: Parameters<typeof JSON.stringify>[2];
-  trailingNewline?: boolean;
-};
-type RootAppendOptions = RootWriteOptions & {
-  prependNewlineIfNeeded?: boolean;
-};
-type RootMoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
-  overwrite?: boolean;
-};
-type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
-  recursive?: boolean;
-  force?: boolean;
-  order?: "filesystem" | "sorted";
-  maxEntries?: number;
-  maxDepth?: number;
-  signal?: AbortSignal;
-};
-type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
-  private?: boolean;
-};
+import type {
+  RootAppendOptions,
+  RootCopyOptions,
+  RootCreateJsonOptions,
+  RootCreateOptions,
+  RootCreateStreamOptions,
+  RootMkdirOptions,
+  RootMoveOptions,
+  RootOpenOptions,
+  RootOpenWritableOptions,
+  RootReadOptions,
+  RootRemoveOptions,
+  RootWriteJsonOptions,
+  RootWriteOptions,
+} from "@openclaw/fs-safe/root";
 ```
 
-Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.
+Each method accepts only its applicable defaults and method-specific options:
+
+| Types | Contract |
+|---|---|
+| `RootReadOptions` | Read symlink/hardlink policy and `maxBytes`; see [read options](reading.md#read-options). |
+| `RootOpenOptions` | Read link policies, without `maxBytes`. The returned handle's I/O belongs to the caller. |
+| `RootWriteOptions`, `RootWriteJsonOptions`, `RootAppendOptions` | [Write options](writing.md#write-options), JSON formatting, and append newline handling. |
+| `RootCreateOptions`, `RootCreateJsonOptions`, `RootCreateStreamOptions` | [Exclusive creation](writing.md#atomic-buffered-creation), private permissions, and `durable: "file"`; streamed creation also accepts byte limits and cancellation. |
+| `RootCopyOptions` | [Guarded copying](writing.md#write-verbs), source policy, `CopyCloneMode`, and `RootCopyPublicationReceipt`. |
+| `RootOpenWritableOptions` | [Writable handles](writing.md#openwritable-for-streaming) with `writeMode`, without buffered-write durability or byte limits. |
+| `RootMoveOptions`, `RootRemoveOptions`, `RootMkdirOptions` | [Mutation methods](root.md#writes) with their collision, removal-budget, and directory-privacy options. |
 
 ## `SymlinkPolicy` / `MutationSymlinkPolicy` / `HardlinkPolicy`
 
@@ -202,3 +167,8 @@ policy; omission preserves each mutation method's existing behavior.
 - [`root()`](root.md) — how `RootDefaults` and `Root*Options` are used.
 - [Errors](errors.md) — the closed code union in context.
 - [Reading](reading.md), [Writing](writing.md) — option shapes per verb.
+
+`PathStat.exactIdentity` is an immutable bigint `dev`/`ino` companion, present on
+returned values and non-enumerable to preserve the numeric JSON shape. Typed
+`list()` and `entries()` results have the same field. Copy it explicitly when
+spreading metadata that will later be used for identity checks.

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

@@ -171,7 +171,10 @@ Without `maxEntries`, sorted walks reuse a full directory metadata snapshot
 from the `Root.list()` owner. This preserves the existing fast complete-scan
 behavior and its snapshot semantics: changes made after a directory is listed
 do not alter its already-captured entries. Supply an entry budget or use
-filesystem order when metadata work must remain incremental. Sorted entries
+filesystem order when metadata work must remain incremental. Complete snapshots
+are consumed directly between public iterator yields, without per-entry listing
+promises. Directory admission, cancellation, and awaited-filter identity fences
+remain in place. Sorted entries
 describe the observations captured in their directory snapshot or batch.
 
 Use `order: "filesystem"` when a wide directory must not be fully enumerated:

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

@@ -127,8 +127,9 @@ pending detail and queued batches are bounded. The last removal stops and joins
 the native thread. No Worker threads, eval programs, or JS `fs.watch` are used.
 
 macOS entry scopes use nonrecursive `EVFILT_VNODE` watches on the admitted parent
-and, when present, the entry itself. Parent activity requests a guarded scan
-without supplying filenames. The entry descriptor covers content and attribute
+and, when present, the entry itself. Child activity requests a guarded scan only
+while the selected entry is missing. Once it exists, sibling activity does not
+wake JavaScript; the entry descriptor covers replacement, content and attribute
 changes and is replaced when a guarded scan admits a new identity. Missing paths
 use their nearest admitted ancestor. Descriptors are opened without following
 symlinks; a symlink entry uses `O_SYMLINK` to observe the link itself. All

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

@@ -223,12 +223,12 @@ await fs.createJson("config/settings.json", { enabled: true }, { atomic: true })
 await fs.create("config/flushed.json", initial, { atomic: true, durable: "file" });
 ```
 
-`atomic: true` keeps the destination absent until all bytes have been written.
+`atomic: true` finishes all bytes in a sibling stage before publication.
 The native backend uses its no-replace rename; the JavaScript fallback hardlinks
 the completed stage and unlinks its temporary name in the same JavaScript turn.
-The fallback requires hardlink support and fails without publishing partial bytes
-when that mechanism is unavailable. Other processes can briefly observe both
-names. Existing and raced entries are preserved, including dangling symlinks;
+When the OS refuses hardlinks, it uses the [placeholder-rename fallback](#publication-without-hardlinks).
+Other processes can briefly observe both linked names, or an empty placeholder
+before the atomic replacement. Entries present at the exclusive claim are preserved, including dangling symlinks;
 ordinary confinement, type, hardlink, and symlink-policy rejections still apply.
 `assertBeforeMutation` retains its live checks through content writes and publication.
 
@@ -254,7 +254,7 @@ complete publication, and an indeterminate link or native rename must preserve n
 recovery. A cleanup or close failure also retains the original operation failure.
 The JavaScript fallback checks the destination again immediately before attempting
 publication. A collision observed there leaves publication unattempted and cleans
-the owned stage. A later collision or other error from the link call remains
+the owned stage. A later collision or unclassified error from the link call remains
 indeterminate, including `EEXIST`; the error code alone does not prove that the
 filesystem left both names unchanged.
 No later verification, mode, or synchronization failure authorizes deleting an
@@ -293,9 +293,10 @@ unlimited. Zero permits an empty input only. Invalid limits reject before I/O.
 Unlike buffered creation's JavaScript fallback, streamed creation stages all
 chunks before publishing the final name. Native mode uses no-replace rename;
 the JavaScript fallback hardlinks the completed stage and removes its temporary
-name in the same JavaScript turn. That fallback requires a filesystem supporting
-hardlinks; other processes may briefly observe both names. An existing or
-concurrently created destination is preserved. Existing-target preflight does
+name in the same JavaScript turn. If hardlinks are refused, it uses the
+[placeholder-rename fallback](#publication-without-hardlinks); other processes may
+briefly observe an empty placeholder. A destination present at the exclusive
+claim is preserved. Existing-target preflight does
 not consume the input. The final mode and durability policy use the same guarded
 writer as other Root operations.
 
@@ -408,8 +409,103 @@ With `overwrite: false`, an existing destination produces `already-exists` and
 is never altered. Copying prepares a private sibling file before publishing its
 completed contents. Native mode uses no-replace rename. The guarded JavaScript
 fallback links the completed stage and removes its temporary name in the same
-JavaScript turn; the filesystem must support hardlinks. Other processes can
-briefly observe both names. The source is never hardlinked to the destination.
+JavaScript turn. If the OS refuses hardlinks, it uses the placeholder-rename
+fallback below. Other processes can briefly observe both linked names or an
+empty placeholder. The source is never hardlinked to the destination.
+
+### Copy metadata and source links
+
+`preserveMetadata: true` restores metadata to the completed staging entry before
+publication. It defaults to `false`; it does not select permissions, ownership,
+ACLs, or extended attributes. Use the existing `preserveSourceMode` option as
+well when source permissions should be selected. An explicit `mode` or Root
+mode default continues to take precedence over `preserveSourceMode`.
+
+| State | `preserveMetadata: true` | Permission selection |
+| --- | --- | --- |
+| POSIX access and modification times | Preserved | Not affected by `mode` |
+| POSIX permission and executable bits | Not selected by this option | Existing `mode` / `preserveSourceMode` rules |
+| Windows creation, access and write times | Preserved by native copying | Not affected by `mode` |
+| Windows hidden, system, archive, temporary, offline, not-content-indexed | Preserved by native copying | Not affected by `mode` |
+| Windows readonly | Not selected by this option | Existing `mode` / `preserveSourceMode` rules |
+| Ownership, ACLs, POSIX extended attributes | Not copied | Existing destination policy |
+| Windows sparse/integrity flags | Not set through metadata copying | Owned by the clone/FSCTL mechanism |
+
+This applies to clones, native byte copies, and JavaScript byte copies. On
+POSIX, native timestamp restoration retains nanoseconds; JavaScript restoration
+uses Node's timestamp precision, as the portable tree copier does. On
+Windows without the native metadata helper, JavaScript can restore only access
+and write times; creation time and the non-permission attributes are not
+preserved. Native `require` mode rejects a missing helper before publication.
+The Windows attribute mask and POSIX timestamp conversion share the
+[tree-copy implementation](copy.md#api); native tree copying has additional
+metadata guarantees that this narrower option does not request.
+
+`sourceSymlinks` defaults to `"reject"`, preserving the existing rejection of
+symlinked absolute string sources with code `symlink` and message
+`symlink not allowed`. There is no follow mode. Set
+`sourceSymlinks: "copy-link"` to copy a source link itself, including a dangling
+file or directory link. Its literal target remains data: copying never resolves
+it. Windows uses the link's own directory attribute and copies the reparse
+payload through the same native mechanism as `copyTree`.
+
+```ts
+await destination.copyIn("template-link", "/srv/templates/template-link", {
+  sourceSymlinks: "copy-link",
+  preserveMetadata: true,
+});
+```
+
+Link destinations are always exclusive. Omit `overwrite` or set it to `false`;
+explicit `overwrite: true` with a link source fails with `invalid-path` before
+mutation. Regular files retain the usual overwrite behavior. Destination Root
+confinement, denied paths, parent-link policy, and mutation-authority checks
+apply to copied links too.
+macOS link permissions use the selected mode on the link itself; Linux link
+permissions remain fixed by the kernel. The link target's permissions are never
+changed.
+
+`"copy-link"` requires an absolute-path string source. A `{ root, relativePath }`
+source fails with `invalid-path` before either source method is called or a
+destination is mutated: its `open` and `stat` capabilities cannot expose literal
+link text or Windows link type without following the link. With the default
+`"reject"`, capability sources continue to use their own Root read policies.
+
+macOS and Windows link copying requires native support and otherwise reports
+`helper-unavailable` before destination mutation. macOS `link(2)` follows its
+source, so it cannot publish dangling symlink inodes exclusively. Linux can
+publish the staged symlink inode with guarded hardlink/unlink when native
+support is off or automatic no-replace rename is unavailable. This has the
+same documented pathname identity windows as the JavaScript write fallback;
+no operation follows the link target. Successful native publication uses
+no-replace rename. No link publication uses the regular-file placeholder
+fallback.
+
+### Publication without hardlinks
+
+For staged JavaScript no-replace copies and writes, `EACCES`, `EPERM`, `EXDEV`,
+`ENOTSUP`, `EOPNOTSUPP`, and `ENOSYS` from the link operation permit a
+**placeholder-rename** fallback, including Android/Termux hardlink restrictions.
+It exclusively creates a mode-`0600`, no-follow destination, closes it after
+capturing its exact identity, rechecks the parent and stage, and requires the
+same empty, singly linked regular placeholder before renaming the completed
+stage over it. A real creation-permission failure still rejects. `EEXIST` from
+the link operation does not permit fallback or establish non-publication.
+
+An empty placeholder is observable before the atomic replacement, and a crash
+can leave that placeholder and the completed stage. Detected placeholder swaps
+reject without removing foreign entries; failed pre-rename operations remove
+only a verified owned empty placeholder. Failed cleanup reports `helper-failed`
+with `details.publication: "not-published"` and `details.cleanup: "failed"`.
+After rename, verification requires the stage name to be absent and the target
+to retain the staged identity; the complete published file is preserved on failure.
+
+These pathname checks are best-effort, not compare-and-swap: a same-directory
+writer can replace the placeholder after the final check, and rename can replace
+that intervening file or symlink (without following it). Protect the parent from
+untrusted mutation when strict concurrent no-clobber is required. This fallback
+preserves existing receipt shapes; `RootCopyPublicationReceipt` reports identity
+and path, with no method or fallback field.
 
 `clone` chooses the file-data transfer strategy through `CopyCloneMode`, shared
 with [`copyTree`](copy.md#api). File copies default to `"never"`; tree copies
@@ -421,11 +517,19 @@ default to `"auto"`:
 | `auto` | Try native file cloning, then copy offload or ordinary byte copying when cloning is unavailable. |
 | `always` | Require native cloning; fail when the binding or filesystem cannot provide it. |
 
-Native file cloning supports APFS and supported Linux filesystems. On Linux, a
+Native file cloning supports APFS, supported Linux filesystems, and Windows ReFS
+(including Dev Drive). On Linux, a
 `FICLONE` request denied with `EPERM`, as container seccomp profiles commonly
 do, counts as unavailable cloning: `auto` copies bytes and `always` fails with
-`unsupported-platform`. Windows currently uses byte copying for `never` and
-`auto`; `always` fails. Clone choice
+`unsupported-platform`. On Windows, `always` requires source and destination on
+the same ReFS volume; other volumes report `unsupported-platform`. `auto` falls
+back to bytes only for unavailable cloning capabilities, and `never` copies bytes.
+ReFS named streams are rejected rather than silently discarded by cloning.
+For successful native ReFS clones through either `copyIn` or `copyTree`, all full
+clusters are block-cloned; a final partial cluster may be copied. Exact tail bytes and logical file size are
+preserved. See the [shared ReFS contract](copy.md) and Microsoft's
+[cluster-alignment and EOF requirements](https://learn.microsoft.com/en-us/windows/win32/fileio/block-cloning#restrictions-and-remarks).
+Clone choice
 does not change modes, durability, root confinement, or source and publication
 identity checks. The shared strategy does not replace Root's guarded regular-file
 contract with `copyTree`'s caller-owned immutable-tree and metadata contract.
@@ -560,6 +664,8 @@ await fs.remove("scratch/finished-job", {
 Budgets must be non-negative safe integers or explicit `Infinity`, and require
 `recursive: true`. Omitted budgets retain their finite defaults. An entry or
 depth limit throws `too-large` before processing the over-budget entry.
+Once the parent is admitted, `maxEntries: 0` rejects before inspecting even a
+missing requested entry; `force: true` does not bypass that budget.
 
 The default filesystem order streams each directory once, using memory and open
 handles proportional to depth rather than directory width. Sorted order also
@@ -643,7 +749,8 @@ for the precise parent-pinning guarantee and remaining same-call limitations.
 
 ### `fs.mkdir(rel)`
 
-`mkdir -p`. Creates missing parents.
+`mkdir -p`. Creates missing parents. An existing regular file at the requested
+directory name rejects with `not-file` in every native mode and remains unchanged.
 
 `require` mode creates each missing component relative to a retained directory,
 opens the child without following a final symlink, and checks its identity before

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

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.25.0",
+  "version": "0.26.5",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -25,8 +25,7 @@
   },
   "files": [
     "dist/archive-parser.wasm",
-    "dist/windows-security-bridge.cs",
-    "dist/windows-security-bridge.ps1",
+    "dist/windows-security-helper.exe",
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "docs/**/*.md",
@@ -83,6 +82,10 @@
       "types": "./dist/secret.d.ts",
       "default": "./dist/secret.js"
     },
+    "./pipe": {
+      "types": "./dist/pipe.d.ts",
+      "default": "./dist/pipe.js"
+    },
     "./permissions": {
       "types": "./dist/permissions-public.d.ts",
       "default": "./dist/permissions-public.js"
@@ -140,7 +143,9 @@
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
     "benchmark:methods": "node benchmarks/runner.mjs",
+    "benchmark:node": "node benchmarks/node-baseline.mjs",
     "benchmark:publish": "pnpm build && node scripts/bench-publish.mjs",
+    "build:windows-helper": "node scripts/build-windows-helper.mjs",
     "build": "node scripts/prepack-build.mjs",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
@@ -156,6 +161,7 @@
     "docs:check": "node scripts/check-doc-examples.mjs",
     "docs:site": "node scripts/build-docs-site.mjs",
     "native:build": "pnpm --filter @openclaw/fs-safe-native-build build",
+    "native:build:freebsd": "node scripts/build-freebsd.mjs",
     "native:test": "cargo test --workspace",
     "pack:check": "pnpm build && node scripts/check-pack.mjs",
     "public-api:update": "pnpm build && node scripts/check-pack.mjs --update-public-api",
@@ -173,19 +179,22 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.25.0",
-    "@openclaw/fs-safe-darwin-x64": "0.25.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.25.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.25.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.25.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.25.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.25.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.26.5",
+    "@openclaw/fs-safe-darwin-x64": "0.26.5",
+    "@openclaw/fs-safe-freebsd-arm64": "0.26.5",
+    "@openclaw/fs-safe-freebsd-x64": "0.26.5",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.26.5",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.26.5",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.26.5",
+    "@openclaw/fs-safe-linux-x64-musl": "0.26.5",
+    "@openclaw/fs-safe-win32-arm64-msvc": "0.26.5",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.26.5",
     "jszip": "^3.10.2"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.6",
     "@napi-rs/cli": "3.10.8",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "@vitest/coverage-v8": "5.0.3",
     "fast-check": "^4.10.2",
     "istanbul-lib-coverage": "3.2.2",
@@ -194,7 +203,7 @@
     "sigstore": "5.0.0",
     "tar": "7.5.22",
     "typescript": "^7.0.2",
-    "vite": "8.3.3",
+    "vite": "8.3.4",
     "vitest": "^5.0.3"
   },
   "engines": {

package/node_modules/@openclaw/fs-safe-darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe-darwin-arm64",
-  "version": "0.25.0",
+  "version": "0.26.5",
   "description": "macOS arm64 native binding for @openclaw/fs-safe.",
   "license": "MIT",
   "author": "OpenClaw Team <dev@openclaw.ai>",

package/node_modules/@openclaw/fs-safe-darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe-darwin-x64",
-  "version": "0.25.0",
+  "version": "0.26.5",
   "description": "macOS x64 native binding for @openclaw/fs-safe.",
   "license": "MIT",
   "author": "OpenClaw Team <dev@openclaw.ai>",