@openclaw/openshell-sandbox 2026.10.1-beta.2 → 2026.10.5-beta.1

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

@@ -191,7 +191,37 @@ try {
 |---|---|---|
 | `link-required` | Create a same-filesystem hardlink or propagate the failure. | No; guarded JS `link` fallback remains. |
 | `link-or-copy` | Try hardlink, then clone, Linux `copy_file_range`, then the JS byte loop for classified unsupported errors. | No; acceleration is optional. |
-| `rename-noreplace` | Atomically move the source without replacing an existing target. Success consumes `sourcePath`. | Yes. |
+| `rename-noreplace` | Move the source without replacing an existing target; Linux `auto` can use identity-checked link/unlink when no-replace rename is unsupported. Success consumes `sourcePath`. | Yes. |
+
+`rename-noreplace` normally uses atomic native rename. On Linux in native `auto`
+mode, a definitively unsupported `RENAME_NOREPLACE` result (`EINVAL`, `ENOSYS`,
+or unsupported-operation errno) permits the existing native file-move fallback.
+It requires a regular source with one link, retains both parents, creates the
+target with `linkat` without following symlinks, verifies both names against the
+staged identity with exactly two links, then unlinks the source and verifies the
+target has one link. Fallback collisions report `already-exists` without clobbering;
+the atomic rename path retains its existing `EEXIST` error.
+Success still returns `method: "rename-noreplace"`, with the additive
+`fallback: "link-unlink"` field identifying this weaker mechanism. Atomic rename
+and the other strategies omit `fallback`.
+
+**Link/unlink is not crash-atomic.** A crash between those syscalls can leave both
+names on the same complete inode. Callers must recognize that interrupted pair
+as incomplete evidence or recover it under their own identity/ownership rules
+before accepting a sealed artifact. The source parent is synchronized after
+unlink, and the target parent is synchronized through the existing pinned
+directory/`parentReceipt` path before success. These directory barriers do not
+flush file contents: callers must finish and synchronize staged contents first.
+Identity checks and syscalls remain separate, not source-name compare-and-swap;
+detected substitutions refuse completion and preserve evidence.
+
+Native `require` remains fail-closed with `helper-unavailable` and
+`details.capability === "rename-noreplace"`. Missing helpers, native `off`, and
+non-Linux platforms gain no fallback. If `linkat` returns `EPERM`, `EOPNOTSUPP`,
+`EMLINK`, `EXDEV`, or `ENOSYS`, publication also fails closed, naming both
+`rename-noreplace` and `details.fallbackCapability: "linkat"`. Permission or link
+count limits need not mean the entire filesystem lacks hard-link support.
+`link-required` and `link-or-copy` do not use `renameat2` and are unchanged.
 
 `"link-required"` propagates an unsupported hardlink failure.
 `"link-or-copy"` falls back only for `EPERM`, `EXDEV`, `ENOTSUP`,
@@ -339,6 +369,9 @@ type PublishFileExclusiveFailureDetails = {
   targetIdentity?: { dev: number | bigint; ino: number | bigint };
   cleanup: "removed" | "preserved" | "unknown";
   directorySync?: { status: "failed"; code?: string };
+  fallback?: "link-unlink";
+  publication?: "published";
+  sourceRemoval?: "not-attempted" | "still-linked" | "unverified" | "removed";
 };
 ```
 
@@ -352,6 +385,16 @@ this receipt instead of inferring ownership from path existence. The original
 failure remains available as `cause`. Failures before target creation retain
 their existing error shape and do not claim a cleanup result.
 
+After a fallback link succeeds, failure always preserves the target, irrespective
+of `onSyncFailure`. The receipt reports `fallback: "link-unlink"`,
+`publication: "published"`, and the source-removal state. `still-linked` means
+unlink failed and both names were reverified as the exact two-link pair;
+`not-attempted` means pair verification failed before unlink; `unverified` means
+unlink failed and the pair could no longer be verified; `removed` means unlink
+completed but a later verification or sync failed. Publication describes the
+completed link operation, not continuing authority over the target pathname.
+Unverified targets do not receive a claimed `targetIdentity`.
+
 Source and target identities are checked again after successful or unsupported
 directory synchronization, while their descriptors remain owned. A late
 verification failure retains its strategy's verification phase and is not a
@@ -389,13 +432,15 @@ can make a failed directory sync succeed: rollback deletion is also not proven
 durable, and a preserved name may disappear after a crash. Always use the
 typed receipt rather than inferring ownership from `exists()`.
 
-`rename-noreplace` always preserves its target after a successful rename,
+`rename-noreplace` always preserves its target after a successful rename or fallback link,
 because removing it would discard the source's only remaining name; its typed
 failure receipt makes that explicit regardless of `onSyncFailure`.
 
-`"rename-noreplace"` requires the native helper and atomically moves the
-source to the target without replacement. A collision is reported as
-`EEXIST`, both files remain unchanged, and a successful call returns
+`"rename-noreplace"` requires the native helper and moves the
+source to the target without replacement, with the Linux `auto` fallback limits
+described above. A collision is reported as `EEXIST` for atomic rename or
+`already-exists` for its Linux fallback, both files remain
+unchanged, and a successful call returns
 `method: "rename-noreplace"` after synchronizing the source and target parent
 directories. Unlike the link/copy strategies, success consumes `sourcePath`.
 

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

@@ -45,6 +45,11 @@ failures with messages such as `permission denied (EACCES)` or
 code and `policy` category for compatibility, along with the original `cause`;
 they do not expose native message text or paths. Already-classified `FsSafeError`
 instances and missing-path errors keep their existing classification.
+Disk-space diagnostics also survive combined publication and disposal failures,
+including `SuppressedError` and `AggregateError`. They retain the original cause
+graph and cleanup/publication receipts, without changing the compatibility code
+or category. An uncertain native rename still reports indeterminate publication
+and a preserved stage; `ENOSPC` does not prove that publication never happened.
 
 Descriptor exhaustion during writes uses `helper-failed` / `operational` and
 names `EMFILE` (process descriptor limit) or `ENFILE` (system descriptor limit)
@@ -254,3 +259,35 @@ Two reasons it isn't a richer hierarchy of subclasses:
 - [Reading](reading.md) — read-path codes.
 - [Writing](writing.md) — write-path codes.
 - [Archive extraction](archive.md) — `ArchiveLimitError` and `ArchiveSecurityError`.
+
+## Unsupported no-replace moves
+
+`isNoReplaceUnsupported(error)` is exported from `@openclaw/fs-safe` and
+`@openclaw/fs-safe/errors`. It recognizes a `helper-unavailable` `FsSafeError`
+with `details.capability === "rename-noreplace"`. This includes strict native
+publication refusals and a Root file move whose link fallback is also unavailable
+(`details.fallback === "link-unlink"`, `details.fallbackCapability === "linkat"`).
+It does not classify a missing native addon, unrelated permission errors, or
+post-publication failures. Once no-replace rename has been rejected, a denied
+or unsupported `linkat` fallback (`EPERM`, `EOPNOTSUPP`, `EMLINK`, `EXDEV`,
+or `ENOSYS`) also fails with this classification. `EPERM` can reflect source
+permissions or inode flags rather than a filesystem-wide lack of hard links;
+the fallback is unavailable for this move. No link-capability cache is populated.
+Consumers need not inspect internal native cause codes.
+The classifier is diagnostic; it does not authorize a replacing retry.
+
+When a Root file move's link/unlink fallback fails after creating the target,
+`details.operation` is `"move"`, `details.fallback` is `"link-unlink"`, and
+`details.publication` is `"published"` (the link was created, not a guarantee
+that a concurrent actor has left it unchanged). `details.sourceRemoval` is:
+
+| Value | Observation |
+| --- | --- |
+| `"not-attempted"` | Identity or link-pair verification failed; source unlink was refused (`path-mismatch`). |
+| `"still-linked"` | Unlink failed and both original inode links were reverified (`helper-failed`). |
+| `"unverified"` | Unlink failed and the current pair could not be verified (`helper-failed`). |
+| `"removed"` | Source unlink succeeded but final target verification failed (`helper-failed`). |
+
+The target is never deleted to roll back these failures. These are observations,
+not locks; inspect the names and identities before recovery. Interrupted processes
+can likewise leave both links, and default hardlink rejection remains enabled.

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

@@ -43,9 +43,26 @@ The fragment has no argument preflight of its own.
 
 On Linux it uses `renameat2(RENAME_NOREPLACE)`; on macOS it uses
 `renameatx_np(RENAME_EXCL)`. If Linux lacks that function or reports it as
-unsupported, it falls back to `link(..., follow_symlinks=False)`, leaving the
-source entry for caller cleanup. That fallback supports files, not directory
-publication. Existing destinations are never replaced by this fragment.
+unsupported, it falls back to `link(..., follow_symlinks=False)`, verifying the
+source and target against the admitted inode with exactly two links
+before unlinking the source. Admission and final target verification require
+one link. A successful file publication consumes the source in both paths.
+
+For directories, a definitive Linux rejection (`EINVAL`, `ENOSYS`, `ENOTSUP`,
+or `EOPNOTSUPP`) or missing `renameat2` rechecks the source identity and target
+absence, then uses plain rename through the same directory descriptors. A
+trailing slash enforces directory source type at the syscall. Directory rename
+can replace only an **empty directory created concurrently**; non-empty
+directories and non-directory targets are refused as `EEXIST`. An existing
+empty directory observed by the absence check is also refused. No empty claim
+directory is exposed before publishing the completed source.
+
+Identity checks and mutation remain separate, not source-name compare-and-swap.
+The fallback verifies the published identity afterward. A file fallback failure
+can leave both names, and post-publication failures preserve the destination
+for caller reconciliation. Exclusive-create cleanup preserves changed payloads
+and incomplete link pairs. The guest has no strict/require mode; host native
+policy does not apply. macOS and other errors retain their fail-closed behavior.
 
 ## Invocation protocol
 
@@ -107,7 +124,7 @@ entries, including symlinks, without following them. A force removal tolerates
 a missing leaf but does not suppress failure to open its parent.
 
 Write preserves an existing regular file's mode and otherwise creates private
-files. Copy preserves the source mode. Exclusive create publishes a mode-0600
+files. Copy and cross-device file moves preserve the admitted source descriptor's mode. Exclusive create publishes a mode-0600
 file from a private staging directory. Staging names retain the `.openclaw-*`
 prefixes and use short random suffixes independent of the destination basename,
 so legal names near the filesystem's component limit also work for writes and

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

@@ -94,9 +94,11 @@ through the retained parents without another receipt, duplicate, reopen, or
 macOS `F_GETPATH`; the documented final source-name substitution window remains
 there. Deeper names retain guarded parent traversal.
 
-No-clobber `Root.move()` fails with `helper-unavailable` if descriptor-relative
-parent admission or atomic no-replace rename is unavailable; it never substitutes
-a check followed by a replacing rename. See the
+No-clobber `Root.move()` requires descriptor-relative parent admission. On Linux,
+`auto` can use identity-checked link/unlink for files or plain descriptor-relative
+rename for directories when `RENAME_NOREPLACE` is unsupported. Directory fallback
+can replace an empty directory created concurrently; `require` stays strict.
+See the [move contract](writing.md#fs-move-from-to-options) and the
 [fallback contract](native.md#javascript-fallback-guarantees-and-delta).
 
 Guarded JavaScript mutations can have out-of-root effects before a post-check

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

@@ -127,11 +127,44 @@ is the same documented containment class as the macOS and JavaScript paths;
 applications requiring atomic beneath resolution must check the result or use
 OS isolation. Rejection after a mutating open does not promise rollback.
 
-Nested no-clobber `Root.move()` still admits both parents and uses
-`renameat2(RENAME_NOREPLACE)`. Existing destinations are never overwritten.
-That separate syscall/filesystem capability remains required; if unavailable,
-the operation fails with `helper-unavailable`. Turning native mode `off` still
-disables no-clobber moves because Node has no equivalent atomic rename API.
+Nested no-clobber `Root.move()` admits both parents and first uses
+`renameat2(RENAME_NOREPLACE)`. Linux `auto` can fall back through those same
+descriptors to identity-checked file link/unlink or directory `renameat`;
+the directory fallback can replace an empty directory created concurrently.
+See the [move contract](writing.md#fs-move-from-to-options) for identity windows
+and partial-state receipts. `require` rejects an unsupported capability.
+Turning native mode `off` still disables no-clobber moves.
+
+For regular-file writes with no-clobber publication (including `Root.create()`
+and archive file extraction), `auto` removes its identity-checked unpublished
+stage and retries through the same guarded JavaScript path as native mode `off`
+when Linux rejects `RENAME_NOREPLACE` with `EINVAL`, `ENOSYS`, or unsupported-operation
+errno. This is a definite non-publication, not an uncertain remote rename.
+Completed streams are replayed from the retained stage descriptor, without
+calling their producer again. Unsupported capability is cached by the retained
+parent's exact device number in a process-local cache bounded to 128 devices.
+Only distinct sibling publication/quarantine/move failures populate that cache; generic
+cross-parent moves can also reject directory ancestry after a source swap.
+Other devices and replacement writes retain their native route. `require`
+cleans the stage and reports `helper-unavailable`, naming the operation and
+`renameat2 RENAME_NOREPLACE`. Failed cleanup prevents retry.
+Copies explicitly requiring `clone: "always"` also fail closed: the JavaScript
+byte-copy path cannot satisfy that requirement.
+
+Private producer workspace promotion likewise uses its existing guarded
+JavaScript handoff in `auto`, preserving the completed producer output.
+Explicit native-only staged, retained-entry, symlink and directory-replacement
+contracts fail closed with the same capability
+diagnostic. Compatible temp-workspace cleanup can use its existing guarded
+JavaScript quarantine/removal path; `require-bounded` and native `require` refuse
+that downgrade. These publication/cleanup owners keep their own recovery
+contracts. Regular-file `publishFileExclusive` with `rename-noreplace` also opts
+into the retained-parent file-move fallback in Linux `auto`, reporting
+`fallback: "link-unlink"`; `require` still refuses. This fallback is not
+crash-atomic: see [publication strategies](durability.md#strategies) and partial
+failure receipts. The standalone
+`movePathWithCopyFallback()` uses guarded replacing rename and its existing
+cross-device copy policy, so unsupported no-replace flags do not affect it.
 
 Bounded owned-tree cleanup deliberately has no `openat` fallback:
 `RESOLVE_NO_XDEV` rejects bind mounts even when device numbers match, which
@@ -311,7 +344,7 @@ See [Root containment guarantees](security-model.md#containment-guarantees-by-pl
 | ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
 | Zstd/bzip2 TAR | Rust streaming decode and fd-relative output creation. | Bundled WASM codecs feed the shared Rust TAR parser, then guarded private staging and the same merge policy; no optional codec dependency. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |
-| `rename-noreplace` | Atomic platform no-replace rename. | Unsupported; no emulation by check-then-rename. |
+| `rename-noreplace` | Atomic platform no-replace rename; Linux `auto` file publication can use identity-checked, non-crash-atomic link/unlink when unsupported. | Unsupported; no emulation by check-then-rename. |
 | Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. Secure-file reads query the borrowed open descriptor and compare its 32-bit volume serial and 64-bit file-index projection with Node's bigint receipt. | The packaged PowerShell/C# bridge preserves raw facts and inspects the borrowed descriptor for secure reads, with the same Node identity comparison; its command failures reject. Structured .NET pathname reporting retains its separate compatibility query. |
 | Windows private directory | Creation-time protected DACL. | The packaged PowerShell/C# bridge applies the protected DACL at creation and retains exact handles through identity validation and failure cleanup. Command failures reject. |
 

package/node_modules/@openclaw/fs-safe/docs/path-scope.md

@@ -1,5 +1,9 @@
 # pathScope()
 
+Paths supplied to a scope are literal filesystem names. In particular, `~/file`
+selects a file inside a directory named `~` beneath the scope; it does not expand
+the user's home directory.
+
 `pathScope()` prepares absolute paths and returns plain `{ ok, path }` results. `resolve()` and `resolveAll()` check lexical containment without touching the filesystem; `existing()`, `files()`, and `writable()` add the filesystem checks described below. Use it to prepare paths before handing them to another library, whose file-opening and mutation behavior still applies.
 
 ```ts

package/node_modules/@openclaw/fs-safe/docs/public-api.md

@@ -24,7 +24,9 @@ The handle resolver verifies exact descriptor and pathname identities, with one
 bounded retry for unknown Windows observations. It borrows the handle without
 reading, reopening, closing it, or changing its cursor.
 
-The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`.
+The error helpers are `categorizeFsSafeError`, `isNoReplaceUnsupported`, and
+`FsSafeErrorDetails`. The no-replace classifier recognizes the documented
+capability refusal without matching internal cause codes.
 
 ## `path` and `advanced`
 

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

@@ -35,7 +35,7 @@ try {
 
 The lock file sits next to the protected resource. If a process crashes mid-lock, the next acquirer notices the held entry, inspects its payload (PID, host, acquired-at timestamp), and decides — via `shouldReclaim` (defaulting to "is the lock older than `staleMs`?") — whether it should keep waiting or fail.
 
-On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their retained Root capability and ownership receipt. The synchronous `process.on("exit")` handler provides last-chance cleanup for raw locks and raw-path reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it. Locks acquired with `retainOnExit: true` are exempt from both handlers: their sidecar stays in place after exit and is governed only by the caller's own stale policy. Because exit handlers are globally deduplicated across package copies, `retainOnExit` fails closed with `helper-unavailable` if an older copy that cannot honor it registered the handlers first.
+On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their creation receipt (or the Root capability when native retention is unavailable). The synchronous `process.on("exit")` handler also cleans retained native sidecars, raw locks, and raw-path reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it. Locks acquired with `retainOnExit: true` are exempt from both handlers: their sidecar stays in place after exit and is governed only by the caller's own stale policy. Because exit handlers are globally deduplicated across package copies, `retainOnExit` fails closed with `helper-unavailable` if an older copy that cannot honor it registered the handlers first.
 
 Asynchronous Root-backed stale recovery uses a regular file at the
 `.reclaim` name, created, verified, and removed through that Root. Its ownership
@@ -57,17 +57,17 @@ even if guard ownership has also changed.
 Root guard; let its original attempt settle before retrying that guarded path.
 It stops compromise monitoring for forgotten holders, including callbacks from checks already in flight.
 
-Always release locks in a `finally` block. Application-managed graceful shutdown can await `release()` or `manager.drain()` before terminating. Explicit `process.exit()`, uncaught failures, crashes, default signal handling, and fatal termination (including `SIGKILL`) do not reliably run asynchronous Root cleanup and may leave sidecars. Recover only after an application-owned liveness policy proves the holder cannot still be writing.
+Always release locks in a `finally` block. Application-managed graceful shutdown can await `release()` or `manager.drain()` before terminating. Explicit `process.exit()` runs synchronous cleanup for retained native sidecars, but cannot run asynchronous fallback Root cleanup. Uncaught failures, crashes, default signal handling, and fatal termination (including `SIGKILL`) may leave sidecars. Recover only after an application-owned liveness policy proves the holder cannot still be writing.
 
 Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. First registration is committed only after Node accepts the listener; synchronous `newListener` reentry fails closed and a thrown registration rolls back so a later acquisition can retry. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
 
-Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. Raw acquisition, snapshot, and exit cleanup capture bigint device/inode values; unsafe numeric identities from older in-process receipts cannot authorize cleanup. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
+Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Raw and JavaScript fallback release compare the in-memory token and exact serialized bytes, and require the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. Retained native Root locks additionally require the exact created inode and a single link, as described below. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. Raw acquisition, snapshot, and exit cleanup capture bigint device/inode values; unsafe numeric identities from older in-process receipts cannot authorize cleanup. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
 
 Last-chance raw-lock exit cleanup requires known Windows device and inode values from both pathname observations and the opened descriptor. A zero value leaves the sidecar in place, including for token-owned locks. Known descriptor/path identity differences remain supported; a pathname identity change during the read still prevents cleanup.
 
 The raw sidecar bytes are not a canonical JSON representation: tools that trim or rewrite the trailing whitespace invalidate the ownership token, so release leaves the changed sidecar in place and fails closed. The token distinguishes cooperating acquisitions; it is not a secret and does not make pathname compare-and-remove atomic against a hostile process that can replace files outside the lock protocol.
 
-`release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` or `withFileLockSync()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed asynchronous acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.
+`release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. Raw and JavaScript fallback handles and managers retain the cleanup receipt after an I/O failure, so the same handle can retry `release()` and `manager.drain()` can retry cleanup. Retained native Root locks settle once and close their retained handles on every outcome, including failure; a failed deletion requires application-owned recovery. A changed sidecar is left untouched. Retained native Root release reports `FsSafeError` code `path-mismatch`, distinguishing a changed identity from a changed owner record; this includes a replacement inode containing an exact copy of the original bytes. If both a `withFileLock()` or `withFileLockSync()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed asynchronous acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.
 
 ## API
 
@@ -265,10 +265,48 @@ its separate canonical-path mutation queue. The synchronous APIs implement the
 same owner/refcount rules; a mismatched synchronous acquisition blocks the
 calling thread according to its retry and timeout options.
 
-Pass `lockRoot` to place sidecar create, read, verification, and removal behind
-an existing `Root` capability. `lockPath` must resolve inside that root.
-Identity-conditioned removal remains the only release and reclaim deletion
-path.
+Pass `lockRoot` to admit sidecar creation, reads, and verification through an
+existing `Root` capability. `lockPath` must resolve inside that root.
+
+With the maintained native helper, asynchronous acquisition retains cleanup
+authority over only the sidecar it created: an identity-checked parent descriptor
+and file descriptor on POSIX, or a shared-delete parent directory handle on Windows
+(local NTFS). `release()` and process-exit cleanup verify the original named
+entry's exact identity, regular-file type, single link, and complete owner record
+through those retained handles. They then use guarded descriptor-relative removal
+or Windows disposition-delete, without resolving the Root again. Cleanup therefore
+works after the Root moves, is replaced, or its parent becomes a symlink. A foreign
+entry at either the original Root path or the retained sidecar name is preserved.
+The retained handles close on success, mismatch, failed acquisition, and exit
+(including `retainOnExit`, which closes handles without deleting).
+If retention itself fails after creation, rollback checks the original identity
+and owner bytes through the creator's still-open descriptors before removing the
+claim. A changed entry is preserved and both the retention and cleanup errors are
+reported; cleanup never falls back to token-only deletion of a replacement.
+Retention duplicates the already-admitted parent authority instead of walking
+its pathname again or requiring extra access to its ancestors.
+Windows opens the named file through the retained parent only for settlement,
+with delete access and sharing; keeping a file handle open would prevent ordinary
+directory relocation. Retained cleanup compares the owner bytes directly and does
+not invoke `parsePayload`; verification and stale-policy reads still do.
+Windows permits renaming that retained parent itself, but refuses renaming an
+ancestor containing the open directory handle, even with delete sharing and no
+data access. Such a refused move leaves the Root and lock in place; release or
+exit cleanup closes the pin so the ancestor can then move. POSIX also supports
+cleanup after a successful ancestor move or symlink swap.
+
+`verifyStillHeld()` retains its Root-based semantics and can still reject a moved
+Root even though `release()` can remove its own sidecar. This creation-specific
+cleanup receipt does not authorize other Root operations or stale reclamation;
+those continue to enforce current confinement and mutation policy. As with the
+sidecar protocol generally, the POSIX final identity check and unlink are not an
+atomic compare-and-delete against an uncooperative process racing the same name.
+
+When native retention is unavailable or explicitly disabled, release keeps the
+existing Root-based fail-closed behavior; a moved Root can leave a sidecar requiring
+application-owned recovery. Use the matching maintained native package to obtain
+relocation-safe cleanup. Synchronous Root locks keep their existing Root authority.
+Identity-conditioned removal remains the only release and reclaim deletion path.
 Root mutation refusals during stale removal propagate unchanged, including
 `null`, `undefined`, and errors carrying `ENOENT`; they do not become missing-sidecar retries.
 

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

@@ -114,10 +114,17 @@ drive-relative spellings, and the stage's own name are rejected.
 With `overwrite: false`, publication is genuine kernel no-replace rename.
 A native collision raises `FsSafeError("already-exists")`, but ordinary errno
 does not prove that a remote rename never committed. Native rename failures
-without explicit pre-dispatch provenance therefore report `indeterminate`:
+without explicit non-publication provenance therefore report `indeterminate`:
 cleanup preserves names and closes descriptors, and further publication rejects.
-Only rejection before rename dispatch leaves the stage eligible for cleanup or
-publication under another name. With
+Rejection before rename dispatch, or an unsupported no-replace capability,
+leaves the stage eligible for identity-checked cleanup. Linux `EINVAL` for the
+fixed `RENAME_NOREPLACE` flag on a regular file renamed to a distinct sibling,
+`ENOSYS`, and unsupported-operation errno prove that nothing was published
+([rename(2)](https://man7.org/linux/man-pages/man2/rename.2.html),
+[VFS rename contract](https://www.kernel.org/doc/html/latest/filesystems/vfs.html)).
+This native-only API reports `helper-unavailable` with the capability name;
+it does not retry through JavaScript. `Root.create()` in native `auto` mode owns
+that separate compatibility retry. With
 `overwrite: true`, publication is plain atomic replacement. Neither route
 copies. Both source and destination resolve through the retained original
 parent, with checks immediately before rename and after publication.

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

@@ -35,6 +35,18 @@ mode, correction uses a verified directory descriptor.
 An initial mode-descriptor admission error is preserved if closing that rejected
 descriptor also fails; close failures after successful admission remain reportable.
 
+These rules apply equally to effective UID 0: root-owned `0700` or `0755` temp
+roots beneath root-owned sticky `1777` `/tmp` are accepted. Passing `/tmp` itself
+as `rootDir` is rejected because the workspace root must be private. Permission
+and ownership errors name the rejected directory (including an unsafe ancestor),
+the observed mode or owner UID, the expected property, and a recovery path.
+Prefer `resolveSecureTempRoot()` or a dedicated directory owned by the effective
+user with mode `0700`. For a non-sticky writable ancestor, have its administrator
+restore appropriate permissions (`1777` for shared system temp) or move the root
+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 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.

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

@@ -131,7 +131,9 @@ and, when present, the entry itself. Parent activity requests a guarded scan
 without supplying filenames. The entry descriptor covers 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. Every
+symlinks; a symlink entry uses `O_SYMLINK` to observe the link itself. All
+non-directory entries are opened nonblocking so a FIFO cannot stall the shared
+watch hub. Every
 descriptor's device/inode must match the guarded observation. There are at most
 two retained descriptors per entry scope (128 scopes maximum), counted in health
 `directories`; descriptor exhaustion fails registration with `EMFILE`. Removal
@@ -150,8 +152,9 @@ FSEvents drops, including during recursive deletion. A shallow tree anchored abo
 a busy unselected subtree still receives recursive traffic; pending hints fold
 under pressure, while genuine FSEvents drops can still overflow.
 Absolute hints are reduced lexically against the admitted canonical Root;
-outside paths never become detail. Dropped/wrapped streams, RootChanged and
-Unmount trigger guarded reconciliation. Pathname hints can reflect activity
+outside paths never become detail. Dropped/wrapped streams, RootChanged, Unmount
+and notifications naming the Root itself trigger guarded reconciliation without detail.
+Pathname hints can reflect activity
 after a swap, but the Root is never replaced and names require guarded admission.
 Removal synchronously stops, invalidates and releases the stream on its queue.
 

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

@@ -367,6 +367,11 @@ For high-volume logging, consider [`openWritable`](#openwritable-for-streaming)
 
 ### `fs.copyIn(rel, sourceAbsPath, options?)`
 
+Synchronous module hooks can use [`copyRootFileSync`](copy.md#synchronous-guarded-file-copies)
+from `@openclaw/fs-safe/advanced` to create an absent destination and retain its
+descriptor for hashing. Root itself remains asynchronous.
+
+
 `copyIn` accepts a `RootCopySource`: a trusted absolute source path or a file
 within another Root. The guarded form supplies `root` with only its `open` and
 `stat` read capabilities, plus `relativePath`:
@@ -416,8 +421,11 @@ 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. Windows
-currently uses byte copying for `never` and `auto`; `always` fails. Clone choice
+Native file cloning supports APFS and supported Linux filesystems. 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
 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.
@@ -460,17 +468,38 @@ Mutation policy is captured at call start; changes to caller-owned denial arrays
 apply to later moves. For live cancellation or revocation, throw from
 `assertBeforeMutation` immediately before dispatch.
 
-The default no-clobber mode requires the native helper. It admits both parent
-directory descriptors and performs a descriptor-relative no-replace rename, so
-a competitor that creates the target first is preserved and the source remains
-in place. If the helper or safe parent admission is unavailable, the call fails
-with `helper-unavailable`; it never falls back to a check followed by a
-replacing rename. After dispatch it rechecks both parent identities, so a
-post-operation rejection can mean the no-replace rename completed. Directory
-moves continue to require `overwrite: true`.
+The default no-clobber mode supports regular files and directories and requires
+the native helper. It admits both parent directory descriptors and first uses
+descriptor-relative no-replace rename. If the helper or safe parent admission
+is unavailable, the call fails with `helper-unavailable`. After dispatch it
+rechecks both parent identities; rejection does not imply rollback.
+
+On Linux filesystems that reject `renameat2(RENAME_NOREPLACE)`, `auto` uses the
+same retained parents and rechecks the source identity before falling back:
+
+- Regular files use `linkat` without following symlinks, verify the exact
+  source/target inode pair with two links, then recheck the source before
+  `unlinkat`. Existing targets cannot be overwritten. Only this intermediate
+  pair permits two links; admission and completed publication require one.
+  Denied or unsupported hard links fail closed, naming both capabilities.
+- Directories recheck that the target is absent and use plain `renameat`.
+  A concurrent non-empty directory or non-directory target rejects as
+  `already-exists`. **A concurrently created empty directory can be replaced.**
+  A trailing slash on the direct-child source requires a directory at syscall
+  time, even after a file or symlink substitution. Source identity checks and
+  rename/unlink are separate syscalls,
+  not source-name compare-and-swap; use exclusive namespace ownership or OS
+  isolation against hostile actors in the final check-to-syscall window.
+
+`require` does not take these fallbacks. Use
+[`isNoReplaceUnsupported(error)`](errors.md#unsupported-no-replace-moves) to
+classify the capability refusal. File fallback failures after link publication
+leave the target intact and report `details.publication: "published"` plus
+`details.sourceRemoval`; callers must inspect that partial state before retrying.
+There is no automatic rollback or crash-durability guarantee.
 
 Linux without `openat2` uses the [guarded native parent walk](native.md#linux-without-openat2).
-The move still uses `renameat2(RENAME_NOREPLACE)` and preserves collisions;
+The move uses `renameat2(RENAME_NOREPLACE)` or the Linux auto fallbacks above;
 parent resolution reports the documented `best-effort` containment class.
 Disabling the addon still makes no-clobber moves unavailable.
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -173,32 +173,32 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.23.0",
-    "@openclaw/fs-safe-darwin-x64": "0.23.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.23.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.23.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.23.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.23.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.23.0",
+    "@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",
     "jszip": "^3.10.2"
   },
   "devDependencies": {
-    "@emnapi/runtime": "2.0.0-alpha.5",
-    "@napi-rs/cli": "3.10.5",
-    "@types/node": "^26.6.1",
-    "@vitest/coverage-v8": "5.0.2",
-    "fast-check": "^4.10.1",
+    "@emnapi/runtime": "2.0.0-alpha.6",
+    "@napi-rs/cli": "3.10.8",
+    "@types/node": "^26.6.4",
+    "@vitest/coverage-v8": "5.0.3",
+    "fast-check": "^4.10.2",
     "istanbul-lib-coverage": "3.2.2",
     "istanbul-lib-report": "3.0.1",
     "istanbul-reports": "3.2.0",
     "sigstore": "5.0.0",
     "tar": "7.5.22",
     "typescript": "^7.0.2",
-    "vite": "8.3.1",
-    "vitest": "^5.0.1"
+    "vite": "8.3.3",
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@12.4.2"
+  "packageManager": "pnpm@12.10.1"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe-darwin-arm64",
-  "version": "0.23.0",
+  "version": "0.25.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.23.0",
+  "version": "0.25.0",
   "description": "macOS x64 native binding for @openclaw/fs-safe.",
   "license": "MIT",
   "author": "OpenClaw Team <dev@openclaw.ai>",

package/node_modules/@openclaw/fs-safe-linux-arm64-gnu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe-linux-arm64-gnu",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Linux arm64 glibc native binding for @openclaw/fs-safe.",
   "license": "MIT",
   "author": "OpenClaw Team <dev@openclaw.ai>",

package/node_modules/@openclaw/fs-safe-linux-arm64-musl/package.json

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