@openclaw/openshell-sandbox 2026.9.6 → 2026.9.7

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

@@ -130,10 +130,22 @@ features, including strict owned-tree temp cleanup, retained-directory staging,
 and atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
 remain unavailable. Operations without a safe fallback fail with `helper-unavailable`
 when the matching package is absent, incompatible, or disabled.
+No-clobber `Root.move()` preserves a native loader failure in the error's
+`cause`, including the original missing-library or incompatible-glibc diagnostic.
 
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.
 
+### Older Linux kernels and seccomp
+
+The native addon supports kernels without `openat2` (before Linux 5.6) and
+containers returning `ENOSYS` or probe-time `EPERM` for that syscall. Beneath
+opens use a guarded no-follow component walk and report `best-effort`.
+Nested no-clobber moves retain atomic `renameat2(RENAME_NOREPLACE)` and exact
+identity checks; keep native mode enabled. Strict bounded cleanup still
+requires `openat2` with `RESOLVE_NO_XDEV` and reports `helper-unavailable`
+without it. See [Linux capability behavior and limits](native.md#linux-without-openat2).
+
 ### Windows security fallback
 
 Windows raw owner/DACL inspection, private-directory creation, and secure-file
@@ -161,6 +173,24 @@ available native operation's error never triggers a command retry. See
 
 ## Native helper policy
 
+### Supported native platforms
+
+Prebuilt bindings cover Linux x64/arm64 (GNU glibc **2.28 or newer**, or musl),
+macOS x64/arm64, and Windows x64. The GNU baseline includes RHEL 8, Rocky Linux 8,
+and AlmaLinux 8. A compatible Node 22+ runtime and the kernel/filesystem features
+required by each operation are still necessary; a loadable addon alone does not
+guarantee every native capability. Systems older than glibc 2.28 are outside the
+GNU binary support floor.
+
+A missing or incompatible optional binding (including `ERR_DLOPEN_FAILED` from
+glibc) does not prevent importing fs-safe. In `auto`, supported JavaScript/WASM
+fallbacks remain available. Native-only operations such as the default
+no-clobber `Root.move()` still fail closed with `helper-unavailable`; `require`
+also rejects fallback-capable operations and retains the binding load error as
+the cause.
+
+### Loading modes
+
 The platform native binaries provide fd-relative open/link/mkdir primitives,
 atomic no-replace rename, and file identity checks. The default is `auto`: use
 the matching binary when it loads, otherwise use the guarded JavaScript path

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

@@ -103,10 +103,16 @@ clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor
 layer owns policy, retries, filters, budgets, modes, cleanup, error
 normalization, and the decision to fall back.
 
-- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Without `openat2`, beneath opens use the [no-follow component walk](native.md#linux-without-openat2) with exact identity checks and report `best-effort`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup still requires `openat2` with `RESOLVE_NO_XDEV` and fails closed when unavailable.
 - macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
 - Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
 
+Linux root lookups reject negative descriptor sentinels before borrowing a handle or resolving a relative path; they never substitute the process working directory for an admitted root. Public Root operations already supply retained, admitted handles.
+
+On Linux and macOS, native asynchronous file-copy admission rejects negative source and parent descriptors before creating a stage, preserving source-before-parent error ordering. Callers must keep nonnegative source and parent descriptors open until the operation settles.
+
+Low-level Unix query, hash, copy, clone, staging, and owned-tree cleanup calls also reject negative descriptors before using them, preserving each operation's path-validation, cancellation, and cleanup order. Descriptor-relative mutations never accept a working-directory sentinel as a retained capability. On modern macOS, beneath opens reject negative roots with `EBADF` before calling `openat`, rather than returning `EIO` after an OS failure or working-directory operation. This check does not establish the validity of arbitrary nonnegative integers: callers must supply live descriptors and retain them until synchronous calls return or asynchronous operations settle.
+
 `replaceDirectoryAtomic()` requires `renameNoReplaceWithIdentity` before it
 creates a missing target parent. On POSIX the dedicated entry point keeps the
 existing pre-dispatch exact receipt fence but dispatches direct-child names
@@ -133,11 +139,12 @@ for the exact difference.
 The guarded JavaScript mutation path is detection-based, not containment-atomic.
 If a same-privilege peer can replace a writable parent after its identity guard
 but before Node resolves a pathname mutation, the mutation can land outside the
-intended root before the post-operation guard throws. Select `require` rather
-than `auto` or `off` when that concurrent attacker is part of the threat model.
+intended root before the post-operation guard throws. Native `require` ensures the addon is present, but does not require a
+`kernel-atomic` resolver; inspect containment and use OS isolation when that
+concurrent attacker is part of the threat model.
 
 `openBeneath()` returns `{ fd, containment }`. `containment` is
-`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for the Linux fallback, macOS and
 Windows. Public JavaScript root open/read/writable results also expose the
 field and report `"best-effort"`; the label reports mechanism, not policy.
 
@@ -175,3 +182,12 @@ consumer performs its 0.5 upgrade.
 - [Durability](durability.md)
 - [Migrating to 0.5](migrating-to-0.5.md)
 - [Migrating to 0.6](migrating-to-0.6.md)
+
+### Retained existing Windows file
+
+The maintained Windows helper supports the public
+[`retainFileInDirectory`](retained-file.md) lifecycle on fixed local NTFS.
+Private native handles, exact identity/generation checks, writable-section
+admission and explicit close results stay behind that public API. Older helpers
+without this capability are unsupported; there is no pathname deletion fallback.
+No Windows namespace persistence barrier is provided.

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

@@ -43,6 +43,7 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
 - Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
   `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+  Without `openat2`, beneath opens use the [guarded fallback](#linux-without-openat2).
 - macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
   components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
   pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
@@ -85,6 +86,67 @@ privately owned empty ACL. Unsupported, malformed, and failed inspection is not
 reported as absence. These facts do not classify individual ACE permissions or
 prove volume ownership enforcement; each caller applies its own security policy.
 
+## Linux without openat2
+
+Linux kernels before 5.6 and containers whose seccomp policy denies `openat2`
+can keep native mode `auto` or `require`. The addon caches one harmless
+`openat2(".")` capability probe per process. `ENOSYS`, or `EPERM` on that probe,
+selects the native `openat` fallback. An `EPERM`/`EACCES` from an application
+operation is still a permission error and never triggers a retry. Install
+syscall filters before the first native operation; a later `ENOSYS` fails with
+`ENOTSUP`, rather than changing the cached mechanism during a call.
+
+The fallback inspects components with `O_PATH | O_NOFOLLOW`, follows relative
+symlink targets using a stack of retained directory descriptors, and rejects
+absolute targets or `..` past the retained root with `EXDEV`. It permits at most
+40 link expansions (`ELOOP` beyond that limit). Final `O_NOFOLLOW` and exclusive
+creation retain their syscall semantics, including opening the link itself with
+`O_PATH | O_NOFOLLOW` and creating through a dangling in-root relative link.
+Exact device/inode/type identities are checked before and after the final
+no-follow open; followed links also retain their descriptors and have their
+named identities and target strings rechecked. Detected replacements fail with
+`EXDEV`, including changes to directories left behind by a link's `..` target.
+
+The fallback also honors `nosymfollow` mount restrictions on retained links.
+Two conservative restrictions remain: the fallback refuses to follow **any
+procfs symlink** with `ELOOP`, including ordinary links such as `/proc/mounts`.
+Userspace metadata cannot distinguish these from procfs magic links, which
+`RESOLVE_NO_MAGICLINKS` must never follow. Opening a final link itself with
+`O_PATH | O_NOFOLLOW` remains allowed. In a sticky, world-writable directory,
+the fallback refuses all symlink following with `EACCES`, even when the calling
+thread or directory owner owns the link, or `fs.protected_symlinks=0`. This
+preserves Linux's protected-symlink restriction without assuming the thread's
+filesystem UID or treating equal mapped `stat` UIDs as proof of equal kernel
+owners (distinct unmapped owners can both appear as the overflow UID).
+
+Public Root policy and canonical-path admission, hardlink rejection, pinned-file checks, and mutation
+identity fences remain in place. `openBeneath()` reports `best-effort`: these
+identity samples detect replacements but cannot make a multi-component walk
+atomic against a hostile process renaming directories between samples. This
+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.
+
+Bounded owned-tree cleanup deliberately has no `openat` fallback:
+`RESOLVE_NO_XDEV` rejects bind mounts even when device numbers match, which
+ordinary identity checks cannot reproduce. `cleanupSafety: "require-bounded"`
+fails before workspace creation with `helper-unavailable`; low-level cleanup
+opens report `ENOTSUP`. Compatible cleanup retains its documented behavior.
+Low-level `O_TMPFILE` anonymous opens also fail before creation with `ENOTSUP`
+in the fallback, because named-entry identity checks cannot verify an unnamed
+file. Public staged-write APIs use exclusive named files and remain available.
+
+For tests, set `FS_SAFE_TEST_NO_OPENAT2=1` before starting Node to force the
+fallback (including bounded-cleanup refusal). It is read only at the first
+capability probe. It has no effect on macOS or Windows.
+See [Linux fallback testing](testing.md#linux-openat2-fallback).
+
 ## Archives
 
 Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
@@ -252,7 +314,7 @@ See [Root containment guarantees](security-model.md#containment-guarantees-by-pl
 
 | Capability | Native path | Guarded JavaScript path |
 |---|---|---|
-| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` on Linux and `best-effort` on macOS and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` with Linux `openat2` and `best-effort` with the guarded Linux fallback, macOS, and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
 | 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. |

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

@@ -185,6 +185,72 @@ the same raw ACE projection. Native `require` rejects either absence with
 query's failure is terminal. The existing coarse `inspectPathPermissions()` API
 still owns its compatibility fallback and trust classification.
 
+### Asynchronous batches
+
+Use `readOwnerAndDaclBatch()` when several paths, such as a directory and its
+ancestors, need inspection without blocking the caller's event loop:
+
+```ts
+import { readOwnerAndDaclBatch } from "@openclaw/fs-safe/permissions";
+
+const facts = await readOwnerAndDaclBatch(stagingDirectories, { timeoutMs: 60_000 });
+```
+
+```ts
+function readOwnerAndDaclBatch(
+  paths: readonly string[],
+  options?: { timeoutMs?: number },
+): Promise<OwnerAndDaclResult[]>;
+```
+
+Results use the same raw fact shape and SID spelling as `readOwnerAndDacl()`.
+They correspond one-for-one to input order, including duplicate paths. An empty
+array returns `[]` without dispatch. Other platforms return an
+`unsupported-platform` result for each path. Query failures, malformed facts,
+or missing/reordered response rows reject the entire batch; no partial facts
+are returned. Null DACLs, incomplete ACE lists and nonlocal observations remain
+raw facts for the caller's policy to evaluate.
+
+The call captures paths, options and native mode before awaiting. Windows
+relative paths are anchored to the current directory or selected drive at
+entry, without normalizing their remaining `.` or `..` components. Empty,
+nonstring, sparse or NUL-containing path entries and Windows namespace aliases
+reject before dispatch. The UTF-8 JSON input is limited to 16 MiB.
+
+An available native capability runs all queries in one isolated process using
+the current runtime executable. Its resolved native mode is forwarded explicitly;
+Node preload and module-search environment overrides are not inherited. An
+available native query's failure is terminal. In `auto` when the binding or
+capability is absent, or in `off`, one packaged PowerShell process reads the
+path array from stdin and compiles the existing C# bridge once. Native `require`
+rejects missing support before launching a process. No route launches one
+process per path or wraps synchronous parent-process queries in promises.
+
+`timeoutMs` defaults to 60,000 and applies to the whole process, including
+startup and fallback compilation. It must be an integer from 1 through
+2,147,483,647. Combined stdout and stderr are limited to 16 MiB. Success waits
+for process exit and both output pipes to close. Timeout and transport failure
+request termination, then retain the existing one-second settlement grace.
+The error's `processExitConfirmed` field, also retained in its cause receipt,
+distinguishes observed exit from an unconfirmed termination attempt. An
+unconfirmed child can still be reading after rejection; the operation returns
+no facts and owns no output files or artifact cleanup. Neither timing out nor
+receiving a successful kill request is reported as confirmed exit.
+
+The PowerShell fallback encodes and budgets each result while collecting it,
+instead of retaining every descriptor graph until the entire batch finishes.
+An encoded response that would exceed 16 MiB rejects with `too-large` before
+inspecting later paths. A query failure observed earlier retains its original
+error, and no partial facts are returned. Duplicate paths remain independent
+observations. This bounds accumulated encoded results, not total process memory:
+the current descriptor and row, decoded input, and runtime overhead still exist.
+
+Batch observations are point-in-time pathname facts, not a snapshot or a
+retained filesystem capability. The caller still owns ancestry trust, principal
+policy and authorization for subsequent operations. Existing singular queries
+and other command operations retain their 30-second deadline, 1 MiB output
+budget and documented failure behavior.
+
 ## Private directories
 
 ```ts

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

@@ -41,6 +41,11 @@ The lexical path surface additionally exports `isNodeError`,
 `UnsafeDeviceReadPathMatch`, `UnsafeDeviceReadPathOptions`, and
 `UnsafeDeviceReadPathReason`.
 
+`isPathRelativeEscape()` rejects absolute paths and relative paths that step
+above their starting directory at any point. Contained paths such as
+`dir/../file` remain relative. It accepts both separators on Windows; on POSIX,
+a backslash remains a literal filename character.
+
 The advanced root-file primitive exports `OpenRootFileParams`,
 `OpenRootFileSyncParams`, `RootFileOpenResult`, and
 `RootFileOpenFailureReason`. These are composition types for callers building
@@ -74,6 +79,16 @@ missing relative suffixes beneath an existing directory using bounded temporary
 directory probes. The caller owns Unicode-pair policy, caching, and the fallback
 for `undefined`. See [path suffix alias probing](path-suffix-aliases.md).
 
+`retainSymlinkInDirectory` holds an explicitly identified POSIX symlink through
+exact-slot no-replace publication; its receipts use the `StagedSymlink*` and
+`PublishedSymlinkReceipt` types. See [staged symlinks](staged-symlink.md).
+
+`retainFileInDirectory` retains an existing Windows NTFS file through a native
+handle for explicit identity-bound retirement. It is described by
+`RetainFileInDirectoryOptions`, `RetainedFile`, `RetainedFileAdmission`,
+`RetainedFileExpected`, `RetainedFileIssue`, `RetainedFileReceipt`, and
+`RetainedFileResult`. See [retained Windows files](retained-file.md).
+
 ## Guest source
 
 `@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,
@@ -100,7 +115,8 @@ best-effort cleanup helper used by those queue flows.
 Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
 Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
 descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
-`WindowsAceFlags`.
+`WindowsAceFlags`. `readOwnerAndDaclBatch()` returns those same facts in input
+order through an isolated asynchronous batch with a whole-process timeout.
 
 Secure reads split their option and result shapes into
 `SecureFileTrustOptions`, `SecureFilePermissionOptions`,
@@ -126,8 +142,11 @@ parent/workspace descriptors; see the
 Atomic helper option and receipt types include
 `MovePathWithCopyFallbackOptions`, `ReplaceDirectoryAtomicOptions`,
 `ReplaceFileAtomicSyncOptions`, `ReplaceFileAtomicResult`,
-`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`, and
-`ReplaceFileDestinationHardlinkPolicy`.
+`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`,
+`ReplaceFileDestinationHardlinkPolicy`, and `ReplaceFileAtomicDestinationState`.
+The `assertBeforeMutation` option rechecks caller authority before new effects,
+and `onDestinationState` reports retained destination identities as
+`ReplaceFileAtomicDestinationState` values; see [atomic writes](atomic.md).
 
 The durability surface also exports the synchronous strict
 `syncDirectorySync`, plus `DirectoryReceipt`, `DurableDirectoryReceipt`,
@@ -154,6 +173,14 @@ Archive option and policy types are `ExtractArchiveOptions`,
 used by extractors. `resolvePackedRootDir` finds the single packed root when an
 archive layout permits it; neither helper weakens entry validation.
 
+## `watch`
+
+`@openclaw/fs-safe/watch` exports `watch()` plus `WatchScope`, `WatchEntry`,
+`WatchChange`, `WatchInvalidation`, `WatchFailure`, `WatchHealth`,
+`WatchOptions`, and `WatchSubscription`. Invalidations are advisory; guarded
+scans stay authoritative. See [filesystem observation](watch.md) for modes,
+budgets, `persistent`, and lifecycle.
+
 ## Keeping this list honest
 
 Every runtime and type name in `test/public-api.json` must appear somewhere in

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

@@ -0,0 +1,115 @@
+---
+title: Retained Windows files
+description: "Explicit identity-bound retirement of an existing file; resource settlement is not persistence."
+---
+
+# Retain an existing Windows file
+
+`retainFileInDirectory` from `@openclaw/fs-safe/advanced` retains **one existing
+regular direct child**, without creating or deleting anything at admission.
+It requires the matching native package. There is no pathname-unlink fallback.
+The initial implementation supports fixed local NTFS drives only; other systems
+return `unsupported`.
+
+```ts
+import { retainFileInDirectory } from "@openclaw/fs-safe/advanced";
+
+const admission = retainFileInDirectory({
+  directory: producer.directory, // canonical C:\... spelling
+  parent: producer.parentIdentity, // exact bigint dev/ino
+  basename: producer.basename,
+  expected: producer.expected, // bigint dev/ino/size/mtimeNs/ctimeNs and SHA-256
+  assertBeforeMutation: () => producer.assertCurrentExclusiveAuthority(),
+});
+if (admission.status === "retained") {
+  using file = admission.file;
+  const outcome = file.remove(); // explicit; using alone does NOT delete
+  // outcome.persistence is always "not-proven".
+  producer.recordRetirementObservation(outcome);
+}
+```
+
+The producer must capture its expected identity, generation and bytes during its
+own creation/ownership protocol. Reading an arbitrary current pathname immediately
+before admission does **not** authenticate the producer. `Number` identities,
+zero/unknown identities, negative/overflowing identities, and malformed digests
+are rejected. A full opaque native volume/file ID is included in the receipt;
+no native handle or numeric descriptor is exposed. Receipts are immutable facts,
+not transferable authority.
+
+## Public types
+
+- `RetainFileInDirectoryOptions`: immutable admission inputs and synchronous authority.
+- `RetainedFileExpected`: exact producer identity, write generation and expected digest.
+- `RetainedFileAdmission`: a retained `RetainedFile` or a refusal/settlement result.
+- `RetainedFileReceipt`: immutable admitted facts, never reusable authority.
+- `RetainedFileResult`: separate disposition, namespace, resources and persistence facts.
+- `RetainedFileIssue`: phase, native code/message and optional original authority cause.
+
+## Admission and mutation custody
+
+The directory's ancestry is opened component by component without following
+reparse points, with delete sharing denied. Its exact expected parent identity
+and canonical path are checked. The file is opened relative to that retained
+parent, with write/delete sharing denied. Existing writer handles refuse
+admission; a read-oplock grant also excludes preexisting writable mapped
+sections. That oplock request is cancelled and joined before admission returns,
+while the no-write-sharing file handle remains open. No detached request remains.
+
+The opened file must match the expected exact NTFS identity, single-link regular
+type, write/change generation, size and SHA-256. Names with stream/device syntax,
+trailing-dot/space aliases and observed named data streams are unsupported.
+Readonly attributes and ACL denials are not repaired or overridden. Verification
+is synchronous and bounded by `maxBytes` (default 16 MiB, maximum 64 MiB).
+
+The original producer must retain **exclusive mutation custody for the entire
+file**, including alternate streams, attributes, security and hardlink creation.
+Windows read/write sharing is per-stream; it is not an application lock over
+all possible aliases. The helper rejects observed alternate streams and changed
+generations, but does not turn a point-in-time check into exclusion of concurrent
+alias/attribute operations. The synchronous `assertBeforeMutation` must check
+that this original authority is still current. Callers unable to establish that
+custody must not call `remove`. Privileged/raw-volume/kernel modifications are
+outside this capability's threat model.
+
+`remove()` admits authority once, revalidates the retained object, sets native
+handle disposition, closes the file, observes the name under the still-retained
+parent, then closes ancestry. No pathname is passed to unlink. Ordinary
+`dispose()` and `[Symbol.dispose]()` only close resources. Authority callbacks
+returning Promises, thenables, or synchronous or asynchronous generator objects
+are refused without deletion; generators are never advanced. Reentrancy is also
+refused, and even caught reentrancy poisons that attempt.
+Repeated settlement returns the original receipt without another mutation or
+another authority call. A copied receipt cannot be used to remove a replacement.
+`[Symbol.dispose]()` throws `FsSafeError` with the complete result in
+`error.details.result` if resource settlement is uncertain; `dispose()` returns
+that result directly. GC closes only and produces no settlement receipt; use
+explicit disposal.
+
+## Read the facts separately
+
+| Field | Meaning |
+| --- | --- |
+| `status` | `unsupported`, `not-attempted`, `preserved-mismatch`, `disposition-accepted`, `name-absent-after-settlement`, `failed`, or `indeterminate`. |
+| `disposition` | Whether native deletion was unattempted, accepted, rejected, or indeterminate. |
+| `namespace` | A post-file-close observation: absent, original, foreign, unknown, or not observed. Absence alone never authenticates prior deletion. |
+| `resources` | `closed` or `close-failed`; operation and close errors are retained together. An uncertain close is never retried against a possibly recycled handle. |
+| `persistence` | Always `not-proven`; no namespace persistence barrier was performed. |
+
+An accepted disposition can still have an unknown/foreign/original namespace
+observation or failed close. A later replacement may exist even after observed
+absence. Existing read handles can retain access to old bytes after the name is
+absent. Namespace observation does not certify all foreign handles are closed.
+An unexpected native binding failure is indeterminate, not success.
+
+## No persistence or service-transaction guarantee
+
+This API does not flush a volume, implement a journal, certify power-loss-safe
+unlink, or issue an application dependency release. Process-termination tests
+establish process-owned handle lifetime only, not crash/storage durability.
+
+An update transaction must independently qualify either a real namespace
+persistence barrier or original-owned durable recovery with correct ordering,
+generation binding and restart consumption. Until then it must retain its
+uncertain recovery/dependency state. Successful removal of one payload does not
+establish a committed multi-file transaction or justify deleting its receipt.

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

@@ -24,7 +24,7 @@ type RootDefaults = {
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
   mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append; default true
-  mode?: number;                   // file mode applied to new writes; per-call override available
+  mode?: number;                   // requested file mode; per-call override available
   nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
   renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
   symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // read policy
@@ -68,7 +68,10 @@ fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kin
 
 `walk()` is the incremental, root-bounded recursive scan. It supports entry and
 depth budgets, cancellation, and `symlinkPolicy: "skip" |
-"follow-within-root"`. With an entry budget, sorted walks prepare small metadata
+"follow-within-root" | "include"`. Include mode returns links as
+`{ relativePath, kind: "symlink", size }` without resolving or entering their
+targets, including dangling and outside-root links. `size` describes the link,
+not its target. With an entry budget, sorted walks prepare small metadata
 batches within the remaining budget; unbounded sorted walks reuse the full
 directory snapshot.
 The default `order: "sorted"` enumerates and sorts each directory's names;
@@ -92,6 +95,8 @@ Directory reads remain fail-fast by default. With
 `{ relativePath, kind: "directory-error", size: 0, error }` and continues with
 the remaining tree. That policy also covers identity-check failures after an
 awaited filter, while callback failures always reject.
+In include mode, a directory that becomes a symlink before descent is a
+`path-mismatch` directory error; it is never silently omitted or followed.
 See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
 with the standalone best-effort walkers.
 
@@ -117,6 +122,10 @@ created through a directory symlink or Windows junction. An absolute path
 outside the root is still rejected. On Windows, alternate casing is accepted
 only when the differently cased Root prefix has the Root's exact directory
 identity; the operation then continues under the trusted Root spelling.
+Absolute paths keep literal `~` components: `readAbsolute("/srv/root/~/file")`
+reads that entry under the root, without expanding the user's home directory.
+Relative `~/file` inputs still expand the home directory and must remain inside
+the Root; use `./~/file` for a literal relative `~` directory.
 
 ### Writes
 
@@ -153,6 +162,11 @@ await fs.create("private-data/credential", "synthetic credential", { private: tr
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
+For `append` and `openWritable`, `mode` only affects new-file creation: POSIX
+permissions remain subject to the process umask. These methods do not chmod
+existing files. Replacement and create-only writes apply their final mode
+through the retained descriptor; see [Writing](writing.md#write-options).
+
 Buffered `create` and `createJson` also accept `atomic?: boolean`. With `true`,
 complete content is staged before exclusive publication even in native-off mode;
 the fallback requires hardlinks. Omitted or `false` keeps the existing buffered
@@ -249,8 +263,10 @@ occurred, later cancellation or verification failure preserves the destination.
 The synchronous optional `onDestinationPublished` callback receives a frozen
 `RootCopyPublicationReceipt` containing `{ path, dev, ino }`, with exact bigint identity immediately after
 publication, before later checks can fail. Callback errors also preserve the
-published file. This receipt records an outcome; it does not authorize removing
-a file that another actor may have edited. Application recovery and cooperative
+published file. Promise, thenable, and synchronous or asynchronous generator
+results reject with `TypeError`; returned generators are never advanced. Other
+synchronous return values are ignored. This receipt records an outcome; it does
+not authorize removing a file that another actor may have edited. Application recovery and cooperative
 locking remain caller-owned.
 
 Existing `copyIn` callers must account for completed destinations retained after
@@ -310,10 +326,12 @@ truncation, append, move, and removal. Buffered writes use bounded chunks and
 recheck before every partial-write submission; file removal submits a direct
 unlink request. Native calls that perform multiple filesystem steps are one
 dispatch. No asynchronous wait separates the check
-from that dispatch. A thrown value rejects the operation unchanged; an async
-or thenable-returning callback rejects with `TypeError` before that mutation.
-Synchronous return values are ignored. Callbacks can run multiple times and
-must inspect current authority each time.
+from that dispatch. A thrown value rejects the operation unchanged; a Promise,
+thenable, or synchronous or asynchronous generator result rejects with `TypeError`
+before that mutation. Returned generators are never advanced. Other synchronous
+return values are ignored. Generator detection applies to generator objects
+themselves, not proxy wrappers. Callbacks can run multiple times and must inspect
+current authority during each call; return-value validation does not establish it.
 Directory creation rechecks the retained parent after the callback and before
 submitting mkdir, so a replacement is rejected before creating that component.
 Overwrite moves recheck the retained root, parents, source identity and both
@@ -340,7 +358,9 @@ For `openWritable()`, the callback covers the library's parent creation,
 exclusive creation, and truncation. The returned raw `FileHandle` belongs to
 the caller, which must check authority before its own later writes.
 
-All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
+All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Missing suffixes also match prospective case and canonical Unicode normalization aliases: case-folding and Unicode NFC/NFD-equivalent spellings cannot bypass a denied path or prefix. A read-only observation of the existing parent can establish that ASCII case variants are distinct. Admission never creates temporary probe files or directories. If sensitivity cannot be established (including empty or unreadable parents, future directories, and Unicode normalization), equivalent suffixes are denied conservatively, even on a filesystem that would allow distinct names. Distinct existing canonical ancestors and unrelated names remain distinct. Observations are local to each synchronous policy check and are refreshed after callbacks or mutations. This conservative fallback does not model other filesystem-specific equivalences, such as HFS+ ignorable formatting characters.
+
+Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
 
 `move()` snapshots its merged default and per-call mutation policy before
 asynchronous preparation. Later changes to the original policy objects or arrays
@@ -375,6 +395,12 @@ fs.entries(rel, options?)        // nonrecursive AsyncIterable<DirEntry>, includ
 fs.resolve(rel)                  // absolute path inside the root, after canonicalization
 ```
 
+Directory enumeration (`list`, `entries`, and `walk`) requires UTF-8 filenames.
+A discovered name that cannot be represented losslessly as a JavaScript string
+rejects with `invalid-path`, before looking up metadata through that name.
+Streaming traversal may already have yielded earlier entries. Literal Unicode
+replacement characters (`U+FFFD`) remain valid names.
+
 These do not pin a later operation. During `stat()`, the exact selected target and
 parent are checked around metadata collection; `list()` checks one exact selected
 directory around the complete name/metadata batch instead of repeating containment

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

@@ -113,6 +113,10 @@ If an already validated descriptor fails while reading, both readers throw an
 operational `FsSafeError` with `code: "read-failed"`; inspect `cause` for the
 underlying Node filesystem code such as `EIO`.
 
+Caught `null` or `undefined` inspection and read failures are reported as
+structured errors with an `Error` cause carrying `"null"` or `"undefined"`,
+instead of an internal `TypeError` while inspecting the thrown value.
+
 A synchronous reader closes its descriptor once. A close failure preserves an
 earlier read or identity-validation error; after a successful read, the close
 failure is reported before trimming or rejecting empty content.
@@ -137,6 +141,11 @@ startWebhookVerifier(signingKey);
 
 Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file, finalizes `mode` (default `0o600`) through an owned descriptor after content writes, and atomically renames over the destination. Publication verification checks the final file identity and mode.
 
+Both secret writers capture top-level parameter values when called, before
+asynchronous filesystem preparation; a supplied byte buffer is captured by
+reference. A parameter getter throwing `null` or `undefined` rejects with that
+same value before filesystem inspection.
+
 On POSIX, both native and JavaScript writers verify actual `0o600` permission
 bits through the retained descriptor before writing content. A filesystem that
 reports successful chmod without enforcing those bits fails with
@@ -219,6 +228,15 @@ if anything already occupies the target path it throws
 `FsSafeError("secret-exists")` without modifying that entry. Use the distinct
 name when first-writer-wins is part of the credential protocol.
 
+Its `durable` option also accepts `"file"`, matching `Root.create()`. This
+requires every file `fsync` to succeed, including on `EPERM`, while parent-directory
+synchronization remains best effort. The default and boolean options retain their
+existing behavior. `writeSecretFileAtomic()` continues to accept boolean durability.
+
+Strict file synchronization preserves the existing publication strategy and
+identity-checked cleanup. A failed file flush before staged publication prevents
+publication; a failure after publication can leave the complete file present.
+
 Distinct leaves can share missing-parent creation without a `secret-exists`
 error. Concurrent creates at the same leaf still have exactly one winner;
 the loser receives `secret-exists` and leaves the winner's bytes intact.
@@ -235,6 +253,7 @@ try {
     rootDir: "/var/lib/app/credentials",
     filePath: "/var/lib/app/credentials/provider.refresh-token",
     content: refreshToken,
+    durable: "file",
   });
 } catch (error) {
   if (!(error instanceof FsSafeError) || error.code !== "secret-exists") throw error;

package/node_modules/@openclaw/fs-safe/docs/security-model.md

@@ -232,13 +232,16 @@ The library does not modify or constrain the global Node.js `fs` namespace, and
 
 | Mechanism | Reported containment | Boundary |
 |---|---|---|
-| Linux native | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| Linux native with `openat2` | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| Linux native without `openat2` | `best-effort` | A no-follow `openat` component walk retains each parent and verifies exact identity associations before and after the final open; all symlink components are rejected. |
 | macOS native | `best-effort` | macOS 15.4 and newer use `O_RESOLVE_BENEATH` first; older kernels use the guarded `openat(O_NOFOLLOW)` component walk. Both verify the opened descriptor with `F_GETPATH`. |
 | Windows native | `best-effort` | Handle-relative `NtCreateFile` rejects reparse points, but this package does not claim a Linux-style atomic beneath guarantee. |
 | JavaScript fallback | `best-effort` | Canonical checks, no-follow opens where Node exposes them, and post-open identity checks form a check-then-use sequence. |
 
 The macOS `F_GETPATH` verification is an escape detector, not a race-atomic guarantee. A hostile same-UID process can rename a directory after `O_RESOLVE_BENEATH` or the manual walk and race the post-open sample or a later descriptor-relative mutation. The native result therefore remains `best-effort` on macOS even when the kernel flag is available. No policy decision is attached to these labels; callers can inspect the fact and decide what their own threat model requires.
 
+The Linux fallback's identity checks are also detection-based: a directory can be renamed between chain samples or before a later descriptor-relative mutation. It cannot provide atomic resolution, and rejection after a mutating open does not promise rollback. See [Linux without openat2](native.md#linux-without-openat2) for the cached capability probe, conservative symlink rejection, and operations that remain unavailable.
+
 The public `OpenResult`, `ReadResult`, and `WritableOpenResult` expose `containment`. Those root APIs currently report `best-effort`; direct native `openBeneath()` reports the platform value above. No-replace publication uses `renameat2(RENAME_NOREPLACE)` on Linux, `renameatx_np(RENAME_EXCL)` on macOS, and `FileRenameInfoEx` with replacement disabled on Windows, but those separate mutation semantics do not upgrade an open result's containment label.
 
 ## Limitations to keep in mind