@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

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

@@ -15,7 +15,7 @@ consumer Rust build.
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
+configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
 ```
 
@@ -25,14 +25,22 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 
 | Mode | Behavior |
 |---|---|
-| `auto` | Prefer native primitives when the current platform package loads; otherwise use guarded JavaScript where a safe fallback exists and reject native-only operations. |
-| `off` | Do not load a native package. Use guarded JavaScript where safe and reject native-only operations deterministically. |
+| `auto` | Prefer native primitives when the current platform package loads; otherwise use supported fallbacks and reject native-only operations. |
+| `off` | Do not load a native package. Use supported fallbacks and reject native-only operations deterministically. |
 | `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
 
-TAR/gzip in the guarded JavaScript path uses a bundled, import-free WASM build
-of the same Rust parser used by native. `off` still disables the optional native
-filesystem helper; it does not disable this portable parser. ZIP fallback still requires
-optional `jszip`, and zstd/bzip2 remain native-only.
+Plain TAR, gzip, zstd, and bzip2 extraction and bounded entry reads use a bundled,
+import-free WASM build of the same Rust TAR parser when native support is absent
+or disabled. Zstd/bzip2 codecs are bundled alongside the parser; gzip uses Node's
+built-in decoder. These archive fallbacks require no runtime interpreter or
+download. `off` disables the optional native filesystem helper, not the bundled
+WASM. `auto` prefers native and does not retry a native operation failure through
+WASM; `require` still rejects an unavailable native binding. ZIP fallback still
+requires optional `jszip`. `inspectTarArchive()` remains limited to plain TAR
+and gzip.
+
+Windows security operations can use the package's readable PowerShell/C# scripts
+in `auto` and `off`, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
 
 On Bun macOS/Linux, the [runtime path adapter](install.md#bun-runtime) uses the
 same Rust addon for system canonicalization in `auto` and `require`. No JIT is
@@ -95,15 +103,33 @@ 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)`. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
-- 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. 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, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees 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 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
+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.
 
 Native primitives back create-only and replacing pinned writes, no-clobber
 `Root.move()`, async sidecar creation, guarded publication, archive acceleration,
 and direct Windows ACL operations. Windows secure-file reads require
-descriptor-bound owner/DACL facts from the current helper; they do not use the
-standalone pathname inspector's command fallback. No-clobber moves fail with
+descriptor-bound owner/DACL facts. In native `auto` or `off` mode, a missing
+binding or capability can use a packaged PowerShell script that inspects the
+borrowed handle. Raw owner/DACL inspection and private-directory creation also support
+this fallback, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+Each capability emits a path-free warning once per process and adds PowerShell
+startup and compilation overhead per call. Native `require` rejects missing
+capabilities, and native operation failures remain terminal. No-clobber moves fail with
 `helper-unavailable` when descriptor-relative parent admission or the atomic
 no-replace rename is unavailable; they never use a check followed by a replacing
 rename. Equivalent JavaScript paths remain available for documented
@@ -113,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.
 
@@ -155,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

@@ -17,7 +17,7 @@ guarded JavaScript path. Native loading is lazy; installs do not compile Rust,
 run postinstall code, or fetch binaries at runtime. Seven exact-version optional
 packages are filtered by OS, CPU, and Linux libc, so an installation receives
 only its matching prebuilt binding.
-Native-only formats and creation-time Windows DACL guarantees fail explicitly
+Native-only formats fail explicitly
 instead of substituting a weaker implementation.
 
 ## The beneath model
@@ -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,
@@ -76,14 +77,75 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   or add-on CRT descriptor namespace.
 
 The internal macOS `inspectDarwinAcl(fd)` capability reports `absent`, `empty`,
-or `present` for the opened object's extended ACL. It synchronously owns a
-close-on-exec duplicate for inspection, leaves the caller's descriptor and file
-position alone, and never reopens a pathname. Darwin's `acl_get_entry` returns
+or `present` for the opened object's extended ACL. It synchronously borrows the
+caller's descriptor, preserving its file position and POSIX record locks, and
+never reopens a pathname. Keep the descriptor open until inspection returns.
+Darwin's `acl_get_entry` returns
 zero for an entry; end-of-list is accepted only for the first entry of a valid,
 privately owned empty ACL. Unsupported, malformed, and failed inspection is not
-reported as absence. These facts do not classify individual ACE permissions,
-prove volume ownership enforcement, or add ACL enforcement to private writers
-and secure readers outside the clone path.
+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
 
@@ -115,6 +177,17 @@ the guarded Node staging/publication boundary. ZIP behavior is unchanged.
 `maxMetaEntryBytes` bounds bodies before allocation; unsupported global/old
 metadata and sparse forms fail closed. See [bounded local PAX support](archive.md#bounded-local-pax-support).
 
+The bundled module also compiles the same zstd and bzip2 codec implementations
+used by native. In `off` or missing-native `auto`, those decoders feed the shared
+TAR parser through fixed 64 KiB windows in one import-free WASM session with a
+256 MiB linear-memory ceiling. Gzip retains Node's built-in decoder. Complete
+container and TAR admission precedes policy evaluation and guarded publication;
+concatenated compressed members and zstd skippable frames are consumed through
+physical EOF. No runtime command, interpreter, download, or consumer compilation
+is needed for these archive routes. `require` stays strict, and available native
+operation failures do not retry through WASM. Public `inspectTarArchive()` still
+accepts only plain TAR/gzip; ZIP fallback still requires optional JSZip.
+
 Every raw pass receives only TypeScript's resolved `maxEntries`,
 `maxMetaEntryBytes`, and `maxDecodedBytes`. Shared resolution caps metadata and
 decoded byte fields at JavaScript's safe-integer maximum and entry counts at
@@ -172,12 +245,26 @@ not bypass the byte limit.
 does not load the binding. Use asynchronous `sha256File()` for native hashing
 and cancellation that can respond while JavaScript callbacks run.
 
-Features without a safe JavaScript implementation, including no-clobber
-`Root.move()`, zstd/bzip2 TAR, Windows private-directory creation, and
+Features without a safe fallback, including no-clobber
+`Root.move()` and
 [retained-directory staging](staged-file.md), fail with `helper-unavailable`
 when native support is absent or off. Staging is currently Linux/macOS only and
 rejects Windows with `unsupported-platform`.
 
+Windows raw owner/DACL inspection, private-directory creation, and secure-file
+descriptor inspection can use a package-shipped, readable `.ps1` driver and
+adjacent `.cs` source in `auto` or `off` mode when their binding or capability is
+unavailable. System Windows PowerShell runs the fixed driver with `-File`;
+paths remain data, with no runtime-generated helper script or encoded launcher.
+The [Windows security fallback prerequisites](install.md#windows-security-fallback)
+apply, and unsupported or disallowed command execution fails closed. This route
+preserves raw ACL facts, private DACLs at creation, and descriptor-bound secure
+reads, and emits a path-free `FS_SAFE_NATIVE_FALLBACK` warning once per capability
+per process. Each call adds PowerShell startup and compilation overhead.
+`require` rejects missing capabilities without a command, and an available native operation's
+failure never triggers this fallback. See [Permissions](permissions.md) and
+[Secure file reads](secure-file.md) for error and platform contracts.
+
 The staged-file owner also serves POSIX native pinned writes, including streaming.
 Unpublished files remain at `0600`; requested modes are applied through the
 owned file descriptor only after rename and published-entry identity validation.
@@ -206,20 +293,34 @@ that fallback does not apply to POSIX no-read modes.
 
 ## JavaScript fallback guarantees and delta
 
+Policy-bound parent creation can refresh exact directory facts through the
+retained POSIX descriptor. The optional native observer compares descriptor and
+no-follow pathname metadata and verifies the descriptor's canonical path before
+and after the observation. Ordinary paths can share that observation within one
+synchronous admission phase; callbacks, mutations, and later phases require fresh
+evidence. Unsupported helpers retain the guarded pathname checks. Policy and
+denied-path decisions remain in TypeScript.
+
 Public policy does not change with the selected mechanism: traversal and link
 rejection, archive filters/limits/modes, exclusive target creation, source and
 target identity fencing, publication cleanup receipts, and secret/lock policy
 remain TypeScript-owned. What changes is the syscall strength or availability:
 
+The table compares underlying mechanisms. On Node, public `Root.open()`,
+`Root.read()`, and `Root.openWritable()` use guarded Node file opens and report
+`containment: "best-effort"` in every native mode. `require` checks availability
+when an operation requests native support; it does not upgrade those results.
+See [Root containment guarantees](security-model.md#containment-guarantees-by-platform).
+
 | Capability | Native path | Guarded JavaScript path |
 |---|---|---|
-| Root-relative opens/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. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. 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 | Supported. | Unsupported; typed `helper-unavailable`. |
+| 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. |
-| 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. | Structured .NET owner/DACL inspection remains available to standalone pathname reporting. Secure-file reads fail closed without the descriptor capability. |
-| Windows private directory | Creation-time protected DACL. | Unsupported; no weaker pathname-only substitute. |
+| 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. |
 
 Use `off` in CI to keep the fallback contract exercised. Use `require` when a
 deployment depends on the stronger mechanism or a native-only feature; do not
@@ -228,8 +329,9 @@ infer native loading from timing.
 ## Loader security
 
 Importing fs-safe never executes a child process. Linux libc selection uses
-the Node process report, conventional musl library filenames, and the ELF
-`PT_INTERP` field of `process.execPath`. If all probes are inconclusive, the
+the Node process report, then the ELF `PT_INTERP` field of `process.execPath`,
+then conventional musl library filenames. An installed compatibility loader
+does not override the running executable's interpreter. If all probes are inconclusive, the
 loader conservatively attempts the glibc package and lets normal module loading
 fail into `auto` fallback. The loader requires only the package selected from
 the detected target; it never probes unrelated packages, downloads code, or

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

@@ -49,6 +49,12 @@ The requested `path` must name a file. Missing destination parents are created
 by the helper because the operation is "produce this output file under the
 root"; callers should choose the filename before calling this API.
 
+The helper reads each option once before its first asynchronous operation.
+Changing the options object after invocation does not change the selected
+writer, staging mode, isolation, filename fallback, byte limit, or final mode
+for that write. Workspace writers retain the original options object as their
+callback receiver; sibling writers retain the internal staging receiver.
+
 `maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap and `Infinity` disables it. Invalid values reject before the producer or filesystem staging runs.
 
 Use `maxBytes` when the external producer can create arbitrarily large files,

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

@@ -56,6 +56,16 @@ they are collapsed. Native realpath alone does not establish this permission
 on every platform. Empty components from repeated or trailing separators do
 not introduce a `.` lookup.
 
+Raw component queues of at most 32 entries retain the legacy small-array
+consumption path. After both the initial parse and every symlink expansion, a
+longer queue uses forward cursor bookkeeping instead of moving the unprocessed
+suffix for every component. The fixed small-queue bound limits repeated front
+removal while retaining legacy shift-based consumption for shallow paths. This
+asymptotic bound is not a platform performance result; performance acceptance
+requires separate benchmark evidence. Callers should still apply their own
+input-size limits: the helper is synchronous, retains the raw suffix, and
+performs filesystem work for each non-empty existing component.
+
 This is a read-only path observation. It neither pins files nor creates a root
 boundary, authorizes access, or guarantees a consistent snapshot during
 concurrent changes. Results can become stale immediately. Use a guarded Root

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

@@ -36,6 +36,7 @@ type ProbePathSuffixAliasesOptions = {
   directory: string;
   left: string;
   right: string;
+  maxDepth?: number;
   shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
 };
 
@@ -44,9 +45,11 @@ function probePathSuffixAliasesSync(
 ): boolean | undefined;
 ```
 
-The helper reads and validates `directory`, then resolves it to an absolute path
-before reading the suffixes or predicate. Later option getters or the predicate
-cannot retarget a relative directory by changing the working directory. When
+The helper reads `directory`, rejects non-string values and supplied paths longer
+than 32,768 code units, then rejects NUL-containing inputs. It resolves the path
+to an absolute path and applies the same limit to that result before reading
+`maxDepth`. Each option is read once. Later option getters or the predicate cannot retarget a
+relative directory by changing the working directory. When
 filesystem observations are needed, the directory is canonicalized and its
 identity is checked; an initial directory alias can be followed.
 
@@ -56,26 +59,68 @@ inputs are rejected with `TypeError`. Windows additionally rejects drive-relativ
 components, colons, and reserved device names, including device aliases with
 extensions or trailing ignored characters. On POSIX, backslashes and colons are
 ordinary filename characters. The optional predicate must be a function.
+`maxDepth` defaults to `32` and must be a non-negative safe integer; invalid
+values, including `Infinity`, throw `RangeError` before mutation or an
+identical-suffix return. A value of `0` admits no ordinary nonempty suffix.
 
 Both suffixes and the predicate are validated before the identical-suffix fast
 path. Identical, valid, within-budget suffixes return `true` without filesystem
 access or a predicate call. This does not prove that the directory exists or that
 the suffix can be created.
 
-## Fixed resource limits
+The forward-observation allowance never exceeds 32,768, even with a large
+`maxDepth`. A deeper or repeatedly colliding probe can return `undefined` when
+that ceiling is reached. Reverse cleanup still runs outside this allowance.
 
-These limits apply to one call and cannot be raised through options:
+## Resource budgets
+
+The default limits for one call are:
 
 | Resource | Limit | On exceeding the limit |
 |---|---|---|
 | Each supplied suffix | 8,192 UTF-16 code units | `RangeError` before mutation |
 | Supplied and resolved directory paths | 32,768 UTF-16 code units each | `RangeError` before mutation |
-| Each suffix's component count | 32 | `RangeError` before mutation |
+| Each suffix's component count | `maxDepth`, default 32 | `RangeError` before mutation |
 | Directory-creation attempts | 128 | `undefined` after cleanup |
 | Successfully created probe directories | 64 | `undefined` after cleanup |
 | Forward filesystem observations | 4,096 | `undefined` after cleanup |
 | Each generated actual path | 32,768 UTF-16 code units | `undefined` after cleanup |
 
+### Deeper observations
+
+Applications comparing deeper prospective paths can explicitly raise `maxDepth`:
+
+```ts
+const prefix = "future/".repeat(32);
+const aliases = probePathSuffixAliasesSync({
+  directory: "/trusted/existing-directory",
+  left: `${prefix}Report.sqlite`,
+  right: `${prefix}report.sqlite`,
+  maxDepth: 33,
+});
+```
+
+The 8,192-code-unit suffix limit and 32,768-code-unit path limits remain fixed.
+Ordinary-component validation, Windows path controls, identity checks, and
+cleanup rules also remain unchanged.
+
+Operation budgets grow proportionally from the actual admitted suffix depth,
+not the requested `maxDepth`. For actual depth `D`, let `B = max(32, D)`.
+Directory-creation attempts are limited to `4 × B`, successfully created
+directories to `2 × B`, and forward filesystem observations to `min(32,768, 4 × B²)`.
+The quadratic observation allowance accommodates rechecks of owned ancestors.
+
+For example, 33 components allow 132 creation attempts, 66 created directories,
+and 4,356 forward observations; 65 components allow 260, 130, and 16,900.
+Specifying a large `maxDepth` for a short suffix keeps the original budgets.
+The suffix-length limit bounds actual depth to at most 4,096, so every budget
+remains a finite safe integer.
+
+Admission does not guarantee a boolean result. Repeated collisions, many
+normalization probes, filesystem limits, or identity failures can exhaust the
+budget or prevent an observation. The helper then returns `undefined` after
+cleanup attempts; callers must preserve their explicit ambiguity policy.
+
 Input limits are checked even for identical suffixes. Dynamic budgets count work
 across the whole call, including collision retries; removing a probe does not
 restore its creation budget. Cleanup is still attempted when a forward budget is

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

@@ -44,7 +44,7 @@ opened or mutated.
 
 ### `isPathInsideWithRealpath(rootDir, target, opts?)`
 
-Synchronous. Same as `isPathInside`, but resolves both inputs through `realpath` first. Use this when you want the canonical answer and either input might be a symlink.
+Synchronous. First requires lexical containment with `isPathInside`, then resolves both inputs through `realpath` and checks containment again. A lexically outside path is rejected even if its resolved target is inside the root.
 
 ```ts
 isPathInsideWithRealpath("/srv/uploads", "/srv/symlink-to-elsewhere"); // false
@@ -121,7 +121,7 @@ The check is intentionally not a normal consumer policy knob. Safe read APIs rej
 
 ### `isNotFoundPathError(err)`
 
-`true` if the error is a `NodeJS.ErrnoException` with code `ENOENT` (file or directory missing).
+`true` if the error has code `ENOENT` (file or directory missing) or `ENOTDIR` (a path component is not a directory).
 
 ```ts
 try {
@@ -207,8 +207,8 @@ import {
 } from "@openclaw/fs-safe/advanced";
 ```
 
-- `assertNoPathAliasEscape({ rootRealPath, candidatePath, policy })` — async. Asserts the candidate's resolved real path is inside the root. Configurable via `PATH_ALIAS_POLICIES` (which currently ships only the default `"strict"` policy).
-- `assertNoHardlinkedFinalPath({ filePath })` — async. Throws if the file at `filePath` has `nlink > 1`.
+- `assertNoPathAliasEscape({ absolutePath, rootPath, boundaryLabel, policy? })` — async. Applies root path resolution and final hardlink checks. `policy` defaults to `PATH_ALIAS_POLICIES.strict`; `PATH_ALIAS_POLICIES.unlinkTarget` permits final symlink and hardlink aliases for unlink operations.
+- `assertNoHardlinkedFinalPath({ filePath, root, boundaryLabel, allowFinalHardlinkForUnlink? })` — async. Rejects a regular file with `nlink > 1`; missing paths and nonregular resolved entries are ignored. Setting `allowFinalHardlinkForUnlink: true` skips this check for unlink operations.
 
 Use these when writing a custom helper that wants the same guards `root()` uses but with different surrounding logic.