@openclaw/matrix 2026.10.1-beta.2 → 2026.10.2

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

@@ -58,7 +58,7 @@ Apple [strongly discourages general directory cloning](https://github.com/apple-
 | `"always"`         | Require native cloning. Unsupported operations fail without a byte-copy fallback.                                                            |
 | `"never"`          | Copy regular file bytes using reads and writes. No native cloning or copy-offload calls. Works without a native binding.                     |
 
-Automatic copying does not recover from permission errors, I/O errors, cancellation, or rejected source contents such as ReFS named streams. A failed clone must leave the destination absent before fallback can create it; otherwise copying fails rather than merging into a partial tree.
+On Linux XFS and ZFS, `FICLONE` capability failures (including an ioctl denied by container seccomp or LSM policy with `EPERM`) select byte copying in `"auto"` mode; `"always"` reports `unsupported-platform`. Automatic copying does not recover from ordinary file-access permission errors, I/O errors, cancellation, or rejected source contents such as ReFS named streams. Native reflink workers settle and remove partial output before returning a clone failure. A failed clone must leave the destination absent before fallback can create it; otherwise copying fails rather than merging into a partial tree.
 
 `concurrency` accepts integers from 1 through 32 and bounds active file copies. ReFS, XFS, and ZFS cloning default to 16 workers. Byte copying defaults to four concurrent files on Windows and one elsewhere. Btrfs uses its bulk operation. APFS uses a bulk clone followed by native directory-entry enumeration to restore directory timestamps; known regular files and symbolic links need no additional stat or open.
 
@@ -197,3 +197,63 @@ Run `node scripts/clone-xfs-proof.mjs MOUNT` on a real XFS volume to verify the
 Run `node scripts/clone-zfs-proof.mjs MOUNT POOL` on a dedicated, otherwise idle Linux ZFS pool with compression and deduplication disabled. It verifies both `copyTree` and `Root.copyIn` through hashes and changes in the documented `bclonesaved` pool counter. It requires `zfs`, `zpool`, and `findmnt`, including permission to run `zpool sync`. Add `no-reflink` for a pool without block cloning to verify strict refusal and automatic byte fallback. The script creates and removes only its temporary directory; it does not create pools or change their properties.
 
 Run `node benchmarks/clone.mjs SOURCE DESTINATION_PARENT` after `pnpm build` to compare one, four, and 16 workers on the same immutable source. Add `3 auto` or `3 never` to measure three samples of ordinary copying, including NTFS destinations. It records copying time separately from fixture preparation and full file-hash verification, and retains its uniquely named output directory for inspection. Prepare Btrfs sources with `createCloneSource` first.
+
+## Synchronous guarded file copies
+
+`copyRootFileSync` from `@openclaw/fs-safe/advanced` is for synchronous module
+hooks and capture owners. Both roots and file paths are absolute; destination
+parents must exist. The destination must be absent, and is created exclusively.
+
+```ts
+import { copyRootFileSync } from "@openclaw/fs-safe/advanced";
+
+using copied = copyRootFileSync({
+  source: { rootPath: "/srv/plugins", absolutePath: "/srv/plugins/plugin.js" },
+  destination: { rootPath: "/srv/capture", absolutePath: "/srv/capture/plugin.js" },
+  clone: "auto",
+  maxBytes: 16 * 1024 * 1024,
+  mode: 0o600,
+});
+// Hash or read copied.fd: this is the owned destination, never a reopened path.
+console.log(copied.bytes, copied.method, copied.identity, copied.sourceIdentity);
+```
+
+`CopyRootFileSyncOptions` selects the source and destination, `clone`, `maxBytes`,
+`mode`, `preserveSourceMode`, `sourceHardlinks`, and optional `expectedSourceIdentity`.
+`CopiedRootFileSync` owns a
+readable/writable `fd`, with idempotent `close()` and `Symbol.dispose`, and returns
+`path`, `bytes`, `method` (`"clone"`, `"copy-file-range"`, or `"copy"`), and exact
+bigint destination `identity` and `sourceIdentity` (`dev`, `ino`). Both identities
+are readonly and frozen. Closing releases the descriptor, not the file.
+
+Callers that already pinned a source can pass `expectedSourceIdentity: { dev, ino }`
+from `fs.fstatSync(pinnedSourceFd, { bigint: true })`. fs-safe still admits and
+opens its own source descriptor, and compares its exact bigint identity before
+creating any destination. A mismatch throws `FsSafeError("path-mismatch")`.
+Keep the caller's descriptor open across the call; it remains caller-owned and
+its cursor is unchanged. Do not derive the expectation from numeric stat fields,
+which may have lost identity bits. Omitting the option preserves ordinary source
+admission. Every successful copy method returns `sourceIdentity` for the source
+actually copied, verified current again at the end of the operation. This binds
+identity only; keep any existing source fingerprint/content and destination
+receipt checks for concurrent edits and later replacements.
+
+Clone policy matches `Root.copyIn`: the default is `"never"`; `"auto"` tries
+native cloning, then bounded copy offload and byte copying on capability failure;
+`"always"` requires cloning or throws `unsupported-platform`. APFS cloning
+creates the guarded destination name from the admitted source descriptor. Linux
+uses FICLONE and copy_file_range. Windows and native-disabled operation copy
+bytes; they cannot satisfy `"always"`.
+
+The source descriptor remains open through before/after source identity checks.
+Symlink components are rejected; source hardlinks are rejected unless
+`sourceHardlinks: "allow"` is selected. The byte limit is an EOF bound, not a
+prefix length: overflow throws `too-large`. Omitted limits are unlimited. An
+explicit mode wins over `preserveSourceMode`; otherwise new files use `0o600`
+subject to the process umask, consistently with `copyIn`.
+
+Failures attempt identity-checked removal of the owned destination and preserve
+replacement entries. This helper creates directly at the destination name, so
+other processes may observe partial bytes until it returns. It does not promise
+crash durability or a coherent snapshot of concurrent in-place source edits.
+Use a private capture directory and keep sources unchanged while capturing.

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/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/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/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/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

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.24.2",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -173,20 +173,20 @@
     "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.24.2",
+    "@openclaw/fs-safe-darwin-x64": "0.24.2",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.24.2",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.24.2",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.24.2",
+    "@openclaw/fs-safe-linux-x64-musl": "0.24.2",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.24.2",
     "jszip": "^3.10.2"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.5",
-    "@napi-rs/cli": "3.10.5",
+    "@napi-rs/cli": "3.10.6",
     "@types/node": "^26.6.1",
-    "@vitest/coverage-v8": "5.0.2",
+    "@vitest/coverage-v8": "5.0.3",
     "fast-check": "^4.10.1",
     "istanbul-lib-coverage": "3.2.2",
     "istanbul-lib-report": "3.0.1",
@@ -194,7 +194,7 @@
     "sigstore": "5.0.0",
     "tar": "7.5.22",
     "typescript": "^7.0.2",
-    "vite": "8.3.1",
+    "vite": "8.3.2",
     "vitest": "^5.0.1"
   },
   "engines": {

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.24.2",
   "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.24.2",
   "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.24.2",
   "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.24.2",
   "description": "Linux arm64 musl native binding for @openclaw/fs-safe.",
   "license": "MIT",
   "author": "OpenClaw Team <dev@openclaw.ai>",

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

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

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

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

package/node_modules/@openclaw/fs-safe-win32-x64-msvc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe-win32-x64-msvc",
-  "version": "0.23.0",
+  "version": "0.24.2",
   "description": "Windows x64 MSVC native binding for @openclaw/fs-safe.",
   "license": "MIT",
   "author": "OpenClaw Team <dev@openclaw.ai>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/matrix",
-  "version": "2026.10.1-beta.2",
+  "version": "2026.10.2",
   "description": "OpenClaw Matrix channel plugin for rooms and direct messages.",
   "repository": {
     "type": "git",
@@ -10,7 +10,7 @@
   "dependencies": {
     "@matrix-org/matrix-sdk-crypto-nodejs": "0.6.6",
     "@matrix-org/matrix-sdk-crypto-wasm": "18.8.0",
-    "@openclaw/fs-safe": "0.23.0",
+    "@openclaw/fs-safe": "0.24.2",
     "fake-indexeddb": "6.2.5",
     "markdown-it": "15.0.2",
     "matrix-js-sdk": "42.4.0",
@@ -19,7 +19,7 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.10.1-beta.2"
+    "openclaw": ">=2026.10.2"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -169,11 +169,11 @@
       "allowInvalidConfigRecovery": true
     },
     "compat": {
-      "pluginApi": ">=2026.10.1-beta.2"
+      "pluginApi": ">=2026.10.2"
     },
     "build": {
       "bundledDist": false,
-      "openclawVersion": "2026.10.1-beta.2"
+      "openclawVersion": "2026.10.2"
     },
     "release": {
       "publishToClawHub": true,