@openclaw/openshell-sandbox 2026.10.6 → 2026.10.8

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

@@ -1,6 +1,8 @@
 # Quickstart
 
-Five minutes. By the end you will have a working `root()` and know how to read, write, atomically replace, and unpack an archive — without your code being able to escape the workspace.
+Build a `root()` and use it to read, write, atomically replace, and unpack an
+archive under a trusted workspace. Confinement strength and concurrent-mutation
+limits depend on the operation and platform; see the [security model](security-model.md).
 
 If you have used Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), this is the same shape: a capability-style handle that carries the boundary across every operation. The first thing to internalize is that you stop reasoning about *paths* and start reasoning about *the handle*.
 
@@ -31,7 +33,9 @@ await fs.write("notes/today.txt", "hello\n");
 const text = await fs.readText("notes/today.txt");
 ```
 
-Writes use a sibling temp file plus `rename`, so a partial write never appears at the destination. Reads open with `O_NOFOLLOW` where available and verify the opened fd matches the path identity before returning the buffer.
+Replacement writes use a sibling temp file plus `rename`, so a partial write
+never appears at the destination. Reads open with `O_NOFOLLOW` where available
+and verify the opened fd matches the path identity before returning the buffer.
 
 `create()` is the don't-clobber variant of `write()` and throws `already-exists` when the target is already there:
 
@@ -39,6 +43,13 @@ Writes use a sibling temp file plus `rename`, so a partial write never appears a
 await fs.create("notes/README.md", "seed\n"); // throws if it already exists
 ```
 
+Default create-only writes can expose incomplete content on the JavaScript
+fallback. Pass `{ atomic: true }` to stage complete content before publication.
+When hardlinks are refused, staged publication can still expose an empty
+destination placeholder before replacing it with the completed file. See
+[atomic creation](writing.md#atomic-buffered-creation) and
+[publication without hardlinks](writing.md#publication-without-hardlinks).
+
 ## 3. JSON, with parsing
 
 ```ts
@@ -60,7 +71,16 @@ await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true })
 await fs.remove("notes/archive/today.txt");
 ```
 
-`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` removes files and empty directories by default. To remove a non-empty directory, pass `{ recursive: true }`; use `maxEntries`, `maxDepth`, and `signal` to bound the work. See [`root()`](root.md) for removal ordering, limits, and partial-removal semantics.
+`move()` defaults to no clobber and requires native support. Linux `auto` can
+fall back when no-replace rename is unsupported; its directory fallback can
+replace a concurrently created empty directory. Use native `require` when
+that must fail closed. See the [move contract](writing.md#fs-move-from-to-options).
+Pass `{ overwrite: true }` when replacement is intended.
+
+`remove()` removes files and empty directories by default. For a non-empty
+directory, pass `{ recursive: true }`; use `maxEntries`, `maxDepth`, and `signal`
+to bound the work. See [`root()`](root.md) for removal ordering, limits, and
+partial-removal semantics.
 
 ## 5. Inspect
 

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

@@ -81,6 +81,12 @@ For tighter control over malformed-or-missing JSON, use the standalone helpers i
 
 Returns a `FileHandle` plus `containment: "best-effort"`, the verified `realPath`, and `stat`. Use this for streaming or partial reads, and **always close the handle**:
 
+`open()` accepts `RootOpenOptions`: the read symlink and hardlink policies,
+without `maxBytes`. It does not consume bytes or apply the Root's read-size
+budget to later handle or stream operations. Bound that I/O in the caller, or
+use `read()` / `readBytes()` when the library should enforce the whole-file cap.
+The result also supports `await using` for automatic handle cleanup.
+
 ```ts
 const opened = await fs.open("large.log");
 try {
@@ -103,7 +109,7 @@ type RootReadOptions = {
 };
 ```
 
-`maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory. Values must be non-negative safe integers or positive `Infinity`; zero is an active cap, while `Infinity` disables it. Explicitly forwarding `undefined` preserves the Root default.
+For the byte-consuming read methods, `maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory. Values must be non-negative safe integers or positive `Infinity`; zero is an active cap, while `Infinity` disables it. Explicitly forwarding `undefined` preserves the Root default.
 
 Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely; regular-file descriptor reads retain normal Node behavior.
 

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

@@ -27,11 +27,11 @@ import {
 
 ## Constants
 
-```ts
-DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;  // 16 KiB
-PRIVATE_SECRET_DIR_MODE = 0o700;
-PRIVATE_SECRET_FILE_MODE = 0o600;
-```
+| Exported constant | Value |
+|---|---|
+| `DEFAULT_SECRET_FILE_MAX_BYTES` | `16 * 1024` (16 KiB) |
+| `PRIVATE_SECRET_DIR_MODE` | `0o700` |
+| `PRIVATE_SECRET_FILE_MODE` | `0o600` |
 
 The 16 KiB cap is intentionally aggressive — credentials should be small. If you need bigger, pass `maxBytes` explicitly.
 

package/node_modules/@openclaw/fs-safe/docs/sidecar-lock.md

@@ -1,5 +1,7 @@
 # File lock
 
+For [Linux kernel write leases](platform-capabilities.md#linux-write-leases), `FileWriteLease.isHeld() === false` means “do not act on the file,” including while the kernel is still processing a lease break. The caller’s `SIGIO` handler still owns break notification.
+
 `acquireFileLock()` and `withFileLock()` provide a cross-process file lock with retry and process-exit cleanup. The lock is implemented as a sidecar file (e.g. `state.json` ↔ `state.json.lock`) — only one acquirer can create the sidecar with `O_CREAT | O_EXCL` at a time.
 
 On Windows, both the target and an explicitly supplied `lockPath` reject NTFS
@@ -72,21 +74,29 @@ The raw sidecar bytes are not a canonical JSON representation: tools that trim o
 ## API
 
 ```ts
-function acquireFileLock<TPayload>(
+import type {
+  FileLockAcquireOptions,
+  FileLockHandle,
+  FileLockManager,
+  FileLockSyncAcquireOptions,
+  FileLockSyncHandle,
+} from "@openclaw/fs-safe/file-lock";
+
+declare function acquireFileLock<TPayload extends Record<string, unknown>>(
   targetPath: string,
   options: FileLockAcquireOptions<TPayload>,
 ): Promise<FileLockHandle>;
 
-function withFileLock<T, TPayload>(
+declare function withFileLock<T, TPayload extends Record<string, unknown>>(
   targetPath: string,
   options: FileLockAcquireOptions<TPayload>,
   fn: () => Promise<T>,
 ): Promise<T>;
 
-function createFileLockManager(key: string): FileLockManager;
+declare function createFileLockManager(key: string): FileLockManager;
 
-function acquireFileLockSync<TPayload>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>): FileLockSyncHandle;
-function withFileLockSync<T, TPayload>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>, fn: () => T): T;
+declare function acquireFileLockSync<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>): FileLockSyncHandle;
+declare function withFileLockSync<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>, fn: () => T): T;
 ```
 
 `managerKey` is an optional identifier used to keep state isolated across multiple lock domains in the same process. Use distinct keys for distinct domains (`"snapshot"`, `"compact"`, `"build"`). If omitted, fs-safe derives one from the target path.
@@ -141,7 +151,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   shouldReclaim?: (params: {
     lockPath: string;
     normalizedTargetPath: string;
-    payload: Record<string, unknown> | null;
+    payload: unknown;
     staleMs: number;
     nowMs: number;
     heldByThisProcess: boolean;
@@ -150,7 +160,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     lockPath: string;
     normalizedTargetPath: string;
     raw: string;
-    payload: Record<string, unknown> | null;
+    payload: unknown;
   }) => boolean | Promise<boolean>;
   metadata?: Record<string, unknown>;    // attached to heldEntries() output for diagnostics
   parsePayload?: (raw: string) => unknown;
@@ -542,24 +552,32 @@ holder still alive":
 
 ```ts
 import { kill } from "node:process";
+import { acquireFileLock } from "@openclaw/fs-safe/file-lock";
 
 const handle = await acquireFileLock(targetPath, {
   staleMs: 60_000,
   payload: () => ({ pid: process.pid }),
-  shouldReclaim: ({ payload, nowMs, staleMs }) => {
-    if (!payload) return true;
-    const pid = Number(payload.pid);
-    if (!Number.isFinite(pid)) return true;
+  shouldReclaim: ({ payload }) => {
+    if (!payload || typeof payload !== "object" || !("pid" in payload)) return true;
+    const pid = payload.pid;
+    if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return true;
     try {
       kill(pid, 0);
       return false;                     // process still alive — keep waiting
-    } catch {
-      return true;                      // process gone — fail closed for recovery
+    } catch (error) {
+      return error !== null && typeof error === "object" &&
+        "code" in error && error.code === "ESRCH"; // only a missing process is stale
     }
   },
 });
 ```
 
+The observed payload is `unknown`, even when this caller writes a typed payload.
+Validate it before reading fields. Permission failures such as `EPERM` do not
+prove that the holder exited. PID checks assume a shared local PID namespace;
+PID reuse can keep a stale lock waiting. This callback classifies staleness,
+not ownership or permission to remove another holder's lock.
+
 `heldByThisProcess` is true when this manager already holds the lock. A `true` result marks the observed sidecar as stale; `staleRecovery` then decides whether acquisition fails closed or attempts caller-approved removal.
 
 ## Stale recovery: guarded `remove-if-unchanged`

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

@@ -84,6 +84,17 @@ 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.
+
 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/types.md

@@ -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`
 

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.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -83,6 +83,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"
@@ -156,6 +160,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 +178,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.0",
+    "@openclaw/fs-safe-darwin-x64": "0.26.0",
+    "@openclaw/fs-safe-freebsd-arm64": "0.26.0",
+    "@openclaw/fs-safe-freebsd-x64": "0.26.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.26.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.26.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.26.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.26.0",
+    "@openclaw/fs-safe-win32-arm64-msvc": "0.26.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.26.0",
     "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 +202,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.0",
   "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.0",
   "description": "macOS x64 native binding for @openclaw/fs-safe.",
   "license": "MIT",
   "author": "OpenClaw Team <dev@openclaw.ai>",