@openclaw/openshell-sandbox 2026.9.3 → 2026.9.5

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

@@ -52,6 +52,7 @@ await fs.remove("notes/archive/today.txt");
 |---|---|
 | [`root()`](root.md) | One boundary for read/write/move/remove and bounded recursive walking inside a trusted directory. |
 | [`@openclaw/fs-safe/config`](config.md) | Process-global native helper and lock-option defaults. |
+| [`@openclaw/fs-safe/guest`](guest.md) | Python filesystem source for caller-owned guest transports, with admitted roots and descriptor-relative operations. |
 | [Native helper policy](native-helper.md) | Choose `auto`, `off`, or `require` for platform-native primitives. |
 | [Native architecture](native.md) | Understand the thin syscall layer, beneath model, platform mechanisms, and fallback boundary. |
 | [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
@@ -65,6 +66,7 @@ await fs.remove("notes/archive/today.txt");
 | [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
 | [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
 | [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
+| [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
 | [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |
 | [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
 | [Permissions](permissions.md) | POSIX mode helpers plus Windows ACL inspection, raw owner/ACE facts, remediation, and private-directory creation. |

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

@@ -8,6 +8,7 @@ import {
   resolveSafeInstallDir,
   safeDirName,
   safePathSegmentHashed,
+  safePathSegmentHashedV2,
 } from "@openclaw/fs-safe/advanced";
 ```
 
@@ -22,7 +23,7 @@ function resolveSafeInstallDir(params: {
 }): { ok: true; path: string } | { ok: false; error: string };
 ```
 
-Computes the absolute install directory for `id` under `baseDir`, after running `id` through `nameEncoder` (`safeDirName` by default). Verifies the result stays inside `baseDir` — anything that would escape returns `{ ok: false, error: invalidNameMessage }`.
+Computes the absolute install directory for `id` under `baseDir`, after running `id` through `nameEncoder` (`safeDirName` by default). Verifies the result stays inside `baseDir` — anything that would escape returns `{ ok: false, error: invalidNameMessage }`. On Windows, contained alternate-stream and filesystem-namespace aliases are rejected with the same result.
 
 ```ts
 const r = resolveSafeInstallDir({
@@ -35,14 +36,17 @@ if (!r.ok) return reply(400, r.error);
 await fs.mkdir(r.path, { recursive: true });
 ```
 
-For ids whose default-sanitized form might collide (e.g. `"foo/bar"` and `"foo\\bar"` both map to `"foo__bar"`), pass `nameEncoder: safePathSegmentHashed` to append a content hash:
+For untrusted IDs that must occupy separate install directories, pass
+`nameEncoder: safePathSegmentHashedV2`. The default `safeDirName` and legacy
+`safePathSegmentHashed` can map distinct IDs to the same directory; the boundary
+check does not establish which ID owns an existing directory.
 
 ```ts
 const r = resolveSafeInstallDir({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   id: untrustedId,
   invalidNameMessage: "invalid plugin name",
-  nameEncoder: safePathSegmentHashed,
+  nameEncoder: safePathSegmentHashedV2,
 });
 ```
 
@@ -60,7 +64,7 @@ function assertCanonicalPathWithinBase(params: {
 }): Promise<void>;
 ```
 
-Throws if the candidate resolves outside `baseDir` after `realpath`. The `boundaryLabel` is included in the error message ("Invalid path: must stay within {boundaryLabel}").
+Throws if the candidate resolves outside `baseDir` after `realpath`. On Windows it also throws for alternate-stream or filesystem-namespace aliases in the base, candidate, or canonical path. The `boundaryLabel` is included in the containment-shaped error message ("Invalid path: must stay within {boundaryLabel}").
 
 ```ts
 await assertCanonicalPathWithinBase({
@@ -87,11 +91,48 @@ safeDirName("");                       // ""
 
 `safeDirName` does *not* try to be exhaustive about Windows-reserved names or special characters. It is purely a separator-stripping pass — `resolveSafeInstallDir` adds the boundary check on top so an `"../../etc"` input cannot escape `baseDir`.
 
-For stricter sanitization, use `safePathSegmentHashed`.
+Use `safePathSegmentHashedV2` when distinct untrusted IDs need separate names.
+
+### `safePathSegmentHashedV2`
+
+```ts
+function safePathSegmentHashedV2(input: string): string;
+```
+
+Hashes every trimmed ID, including ordinary short names, into `id-v2-` followed
+by 64 lowercase hexadecimal SHA-256 digits. The result is always 70 ASCII bytes,
+contains no separators, and avoids Windows device names and ignored suffixes.
+There is no readable prefix to truncate and no unchanged-name branch. Distinct
+trimmed IDs, including an ID that looks like an encoded output, remain distinct
+unless their full SHA-256 digests collide. The lowercase ASCII output also
+preserves that distinction on case-insensitive and Unicode-normalizing volumes.
+
+The stable V2 digest recipe is SHA-256 of the UTF-8 bytes of
+`"@openclaw/fs-safe:install-path:v2\0"`, followed by the UTF-16LE bytes of
+`input.trim()`, without a byte-order mark. The NUL-terminated prefix separates
+this use of SHA-256 from other hash domains. UTF-16LE preserves exact JavaScript
+code units, including lone surrogates. Inputs are not case-folded or Unicode
+normalized. Surrounding whitespace, as removed by JavaScript `String.trim()`,
+is the only intentional equivalence; internal whitespace remains significant.
+
+```ts
+const segment = safePathSegmentHashedV2("plugin/v1"); // id-v2-<64 hex digits>
+safePathSegmentHashedV2(" plugin/v1 ") === segment;  // true
+safePathSegmentHashedV2("Plugin/v1") === segment;    // false
+```
+
+This encoder computes a name; it does not authorize access or prove ownership
+of a directory. Store the original trimmed ID in application-owned metadata and
+verify it before reusing an existing install directory. Keep each install tree
+on one encoding version. Switching to V2 changes existing paths: use a new base
+directory or explicitly migrate directories after verifying their recorded IDs.
+Do not silently fall back to a legacy path when the V2 path is missing.
 
 ### `safePathSegmentHashed`
 
-Returns a directory-safe segment **plus** a short content hash when sanitization changed the input or when the safe form is too long. Use this when input collisions matter:
+Legacy readable encoding retained for path compatibility. It appends a short
+content hash when sanitization changed the input or when the safe form is too
+long; ordinary short names remain unchanged. Use V2 for new untrusted-ID mappings.
 
 ```ts
 safePathSegmentHashed("plugin-v1");                  // "plugin-v1"  (unchanged short input)
@@ -104,31 +145,35 @@ safePathSegmentHashed(".");                          // "skill-cdb4ee2aea"
 
 The sanitization is more aggressive than `safeDirName`: any character not in `[A-Za-z0-9._-]` becomes `-`, runs of `-` collapse, leading and trailing `-` are stripped, the empty/`.`/`..` fallback is `"skill"`. Long results are truncated to 50 chars before the hash is appended.
 
-The suffix is the first 10 hex characters of `sha256(trimmedInput)`. It makes
-collisions between distinct trimmed inputs unlikely, but it is a 40-bit
-identifier rather than a mathematical uniqueness guarantee. Inputs that differ
-only by surrounding whitespace intentionally map to the same output.
+The suffix is the first 10 hex characters of `sha256(trimmedInput)`. This is a
+40-bit identifier, and the hash is not applied to every ID: short generated
+outputs overlap with accepted literal inputs. Case variants can also share a
+directory on case-insensitive filesystems. Distinct IDs can therefore alias
+without a hash collision. Do not use this legacy encoder as an identity or
+authorization boundary for untrusted IDs. Inputs that differ only by surrounding
+whitespace intentionally map to the same output. Its output and the default
+encoder selected by `resolveSafeInstallDir` remain unchanged for compatibility.
 
 ## Common patterns
 
 ### Install a plugin
 
 ```ts
-import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashed } from "@openclaw/fs-safe/advanced";
+import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashedV2 } from "@openclaw/fs-safe/advanced";
 import { extractArchive } from "@openclaw/fs-safe/archive";
 import fs from "node:fs/promises";
 
 const r = resolveSafeInstallDir({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   id: untrustedName,
   invalidNameMessage: "invalid plugin name",
-  nameEncoder: safePathSegmentHashed,
+  nameEncoder: safePathSegmentHashedV2,
 });
 if (!r.ok) return reply(400, r.error);
 
 await fs.mkdir(r.path, { recursive: true, mode: 0o755 });
 await assertCanonicalPathWithinBase({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   candidatePath: r.path,
   boundaryLabel: "plugin install dir",
 });
@@ -148,6 +193,7 @@ const snap = resolveSafeInstallDir({
   baseDir: "/srv/snapshots",
   id: `${runId}-${version}`,
   invalidNameMessage: "invalid snapshot id",
+  nameEncoder: safePathSegmentHashedV2,
 });
 if (!snap.ok) throw new Error(snap.error);
 await fs.mkdir(snap.path, { recursive: true });

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

@@ -31,6 +31,40 @@ node --version
 # v22.0.0 or newer
 ```
 
+## Bun runtime
+
+Bun 1.4.2 can run the same public APIs and load the matching native package.
+On macOS and Linux, fs-safe uses its Rust N-API addon to call the system
+`realpath` implementation for native resolution. Ordinary resolution follows
+Node's component walk, including lexical normalization of expanded symlink
+targets, in Rust, with a 1,024-link expansion limit that returns `ELOOP` for
+excessive or cyclic expansion. This works around Bun path-resolution defects that
+otherwise reject restrictive permissions and confuse literal POSIX backslashes
+with directory separators. The OS still resolves symlinks and canonical file
+names; fs-safe retains its confinement and file-identity checks.
+
+This works with `bun --jitless` and needs no runtime FFI or JIT. Use native mode
+`auto` or `require` with the matching addon installed. `FS_SAFE_NATIVE_MODE=off`
+still disables all addon loading; `auto` without the addon falls back to Bun's
+resolver. Those configurations retain Bun 1.4.2's limitations with restrictive
+permissions, sockets, literal backslashes, and symlink/parent traversal. Use
+Node if you need full compatibility without the addon. On Bun POSIX, `require`
+also rejects canonicalization when the addon or its canonicalizer is unavailable.
+
+Node and Windows use their existing runtime canonicalizers. On Windows, Bun's
+recursive directory creation receives an absolute spelling that preserves raw
+path components, working around its rejection of existing relative `.` and `..`
+directories. Windows native descriptor-relative operations require Bun to expose
+the paired libuv descriptor bridge from its host executable; a missing or partial
+bridge fails explicitly with `ENOTSUP`. Public paths and caller-supplied filesystem
+adapters remain unchanged.
+
+The upstream fix is tracked in [Bun #42374](https://github.com/oven-sh/bun/pull/42374).
+The adapter can be removed when the supported Bun baseline includes that fix.
+Run native compatibility checks with `pnpm test:bun:native` after building the
+package and addon. See [contributing](contributing.md) for the Node/pnpm toolchain
+and the broader diagnostic suite.
+
 ## TypeScript
 
 Types ship with the package — no `@types/openclaw__fs-safe` needed. The `exports` map in `package.json` provides typed entries for every subpath:
@@ -93,9 +127,10 @@ the matching binary. Consumers do not run a native build, download code at
 runtime, or execute a postinstall step. Omitting optional dependencies keeps
 non-archive fallback-capable operations working in `auto` or `off`. Native-only
 features, including strict owned-tree temp cleanup, retained-directory staging,
-atomic `rename-noreplace`, zstd/bzip2 TAR handling, and Windows private-directory
-creation, remain unavailable. Operations needing the binding in `require` mode fail with
-`helper-unavailable` when the matching package is absent or incompatible.
+atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
+zstd/bzip2 TAR handling, and Windows private-directory creation, remain
+unavailable. Operations without a safe fallback fail with `helper-unavailable`
+when the matching package is absent, incompatible, or disabled.
 
 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.
@@ -104,15 +139,15 @@ before deploying with native mode `require` or native-only features.
 
 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 silently keep the guarded
-JavaScript path. Platforms without one of the seven published targets therefore
-continue through the documented fallback in `auto` mode.
+the matching binary when it loads, otherwise use the guarded JavaScript path
+where a safe fallback exists. Native-only operations fail with
+`helper-unavailable`.
 
 ```ts
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
 ```
 

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

@@ -1,6 +1,6 @@
 # JSON store
 
-`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the absolute-path
+`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the single-path
 convenience wrapper for `fileStore(...).json(...)`: a small read-modify-write
 handle around a single JSON file. It bakes in atomic writes, explicit fallback
 reads, and optional cross-process locking via
@@ -45,6 +45,7 @@ type JsonStoreOptions<T> = {
   filePath: string;
   dirMode?: number;                                // default 0o700
   mode?: number;                                   // default 0o600
+  durable?: boolean;                              // default true
   trailingNewline?: boolean;                       // default true
   lock?: boolean | JsonStoreLockOptions;           // false / undefined = no lock
 };
@@ -70,6 +71,19 @@ type JsonStore<T> = {
 
 `jsonStore({ filePath })` resolves `rootDir = dirname(filePath)` and calls
 `fileStore({ rootDir, private: true }).json(basename(filePath), options)`.
+On Windows, the factory rejects NTFS alternate-stream and directory-index
+namespace spellings before preparing its private parent. An ordinary
+drive-relative path is anchored at entry and `store.filePath` exposes the
+resulting absolute path; ordinary colon-bearing POSIX paths remain valid.
+
+`durable: false` keeps sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability. The default
+is `true`, subject to platform sync support. This store-level policy applies
+to `write`, `update`, and `updateOr`; these methods have no per-call options.
+For `fileStore(...).json(rel, options)`, `options.durable` overrides the parent
+file store's durability, while omission or `undefined` inherits it. Modes,
+identity checks, mutation serialization, and sidecar locking are unchanged.
 
 The store does **not** validate the parsed value against `T` at runtime — the cast is unchecked. Wrap with a schema (zod/valibot) if the file might be hand-edited or written by another process you don't control.
 

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

@@ -38,6 +38,17 @@ Use `readJson` when missing-or-malformed is a programmer error you want to surfa
 
 `JsonFileReadError` carries `cause` so you can inspect whether the underlying failure was an `ENOENT`, a `SyntaxError`, or something else.
 
+On Windows, filesystem path inputs reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`; ordinary colon-bearing POSIX names remain valid.
+Standalone JSON writers preserve their released support for an ordinary
+drive-relative destination by anchoring its leading drive designator at entry
+without normalizing the remaining suffix. Any additional colon is still
+rejected before filesystem access.
+Strict standalone readers retain `JsonFileReadError` and expose the
+`invalid-path` rejection as its cause, lenient `tryReadJson*` calls return
+`null`, and root-bounded readers report an `open`/`validation` failure.
+
 ## Reading
 
 ### `readJson<T>(filePath, options?)`

package/node_modules/@openclaw/fs-safe/docs/local-roots.md

@@ -71,6 +71,13 @@ component that does not exist: dangling symlinks, descendants of dangling
 symlinks, and candidates whose existing ancestors cannot be canonicalized are
 rejected rather than treated as safe missing paths.
 
+Filesystem path inputs retain symlinks and parent components until boundary
+resolution, including after home expansion. A followed `link/../file` resolves
+the parent of the link's target; default reads reject the link instead of
+normalizing it away. File URLs retain the URL parser's normal path semantics.
+An existing non-directory component cannot be traversed further, including by
+`..`; the helpers reject that input instead of selecting a different file.
+
 ## `readLocalFileFromRoots(options)`
 
 The asynchronous helper opens the candidate through the matched [`Root`](root.md),
@@ -82,7 +89,7 @@ type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
   nonBlockingRead?: boolean;
-  symlinks?: "reject" | "follow-within-root";
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
 };
 
 type LocalRootsReadResult = ReadResult & {

package/node_modules/@openclaw/fs-safe/docs/mutation-policy-proof.md

@@ -0,0 +1,65 @@
+# Hosted mutation-policy proof
+
+The `mutation policy public behavior proof` workflow builds the exact event-head
+package and host addon on Node 24 Linux, macOS, and Windows. Each case executes in
+a fresh process, uses a private temporary fixture, and emits only a bounded,
+canonical receipt. POSIX workers require both real and effective non-root UIDs.
+
+Receipt schema `fs-safe-mutation-policy-proof-v2` deliberately does not describe
+final directory emptiness as a mutation-dispatch count. Root replacement records
+the unchanged contents of the original and replacement parent; denied redirect
+records rejection and unchanged denied/displaced parents. The existing JS mkdir
+counters name their exact child or next component. None counts native syscalls
+or excludes transient mutations that leave no final trace.
+
+## Additional hosted cases
+
+Each POSIX write/create/copy worker, under both native-off and native-require,
+performs an eligible success control, an exact deeper-parent denial after an
+earlier parent is created, a denied redirect after preflight, and a stale-parent
+replacement at the public pre-mkdir authority boundary. Exact directory listings
+and sentinels verify that denied/current/displaced parents contain no prohibited
+child, target, or stage. Copy sources must retain their original bytes.
+
+Redirect injection uses the existing public `@openclaw/fs-safe/test-hooks` subpath
+from `dist`, not a mocked native binding. Only these isolated workers enable
+`NODE_ENV=test`. The exact target and single hook visit are required. The hook is
+after policy preflight but before parent admission; it must not be described as
+a post-parent-admission hook. Stale replacement instead uses the public authority
+callback after child-create policy admission, with an existing sentinel parent
+and a still-missing child. Both implementation files that enforce the following
+freshness check are hash-bound. No unchecked callback ordinal chooses a fault.
+
+Representative POSIX `Root.write` workers refuse authority before the first mkdir,
+after one parent has been created and before the next mkdir, before staging, and
+immediately before publication. Epoch selection uses actual fixture state. The
+publication refusal requires a real single-link, caller-owned mode-0600 stage
+containing the complete payload while the destination still contains its original
+sentinel. The same rejection object must escape, no callback may follow refusal,
+and the owned stage must be gone before fixture teardown.
+
+Windows workers exercise buffer `Root.write` through a stable final-file symlink,
+then refuse before staging a newly created placeholder, before publishing over a
+new placeholder, and before publishing to an existing symlink-selected destination.
+They verify alias binding, destination preservation, observed placeholder/stage
+states, and cleanup before fixture teardown. The default native-off and explicit
+`verify-content-with-lock` native-require configurations both select the existing
+Windows JS buffer writer. The compatibility route is expected not to load the
+addon; the receipt does not mislabel this as native publication or evidence that
+content-verification fallback or lock contention was exercised.
+
+## Bounds and interpretation
+
+The receipt remains below 32 KiB, each worker has a 15-second process timeout and
+4-KiB stdout limit, and the proof step has a six-minute outer timeout. Worker I/O
+and cleanup retain their existing deadlines. The canonical pending/failed receipt
+is preserved if setup, a worker, provenance validation, or emission fails.
+Source, built modules, the public test seam, harness helper, contract tests, and
+host addon are hashed and checked again after workers.
+
+These are deterministic representative observations, not an exhaustive race proof
+or syscall audit. Existing hash-bound internal tests remain complementary for
+other awaited-admission, receipt-refresh, and observation-failure interleavings.
+Windows root replacement and POSIX-specific pinned routes are not claimed on
+Windows. Hosted CI and exact artifact inspection are required before relying on
+new receipts; the proof supplies no performance release clearance.

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 only
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
 ```
 
@@ -25,17 +25,37 @@ 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 silently use the guarded JavaScript path. |
-| `off` | Do not load a native package. Use the guarded JavaScript path deterministically. |
+| `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. |
 | `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 native filesystem
-code; it does not disable this portable parser. ZIP fallback still requires
+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.
 
+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
+needed. With `off` or a missing addon in `auto`, Bun's own resolver retains its
+path and permission limitations. Canonicalization in `require` fails with
+`helper-unavailable` if the addon or its canonicalizer is missing, including
+when admitting a temp workspace. Containment and identity checks stay intact.
+
 Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
 
+Native-created descriptors retain their originating native close operation through
+normal and error cleanup, including later mode changes. Node-created roots and
+directory handles keep Node's close operation, and borrowed handles keep their
+caller-owned lifetime. This preserves Node worker-thread descriptor tracking
+without unmanaged-descriptor warnings. A helper missing native close support is
+unavailable before descriptor allocation.
+
+Close retained native resources and let in-flight operations finish before
+forcibly terminating a worker. Native-created descriptors are not registered
+with Node's automatic worker-exit cleanup; `Worker.terminate()` can leave them
+open until process exit. The native close operation handles explicit cleanup,
+not forced worker termination.
+
 [`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
 remain available in every mode. Their default compatible cleanup uses guarded
 JavaScript quarantine when owned native tree removal is unavailable.
@@ -55,20 +75,39 @@ change the mode policy of existing fallback-capable APIs.
 
 ## Native boundary
 
+The internal Darwin descriptor ACL inspector requires its matching native
+capability in both `auto` and `require`; `off`, a missing package, or an older
+binding without `inspectDarwinAcl` rejects with `helper-unavailable`. Inspection
+failure or malformed facts reject with `permission-unverified`; there is no
+mode-bit or pathname fallback for this capability. Clone admission uses a fused
+descriptor-bound metadata and ACL observation, then compares immutable receipts
+with fresh no-follow pathname identity fences; pathnames never authorize ACL
+state. The payload ACL-clear readback is part of that fused observation. Once
+a clone payload exists, normalization and verification failures become terminal
+`EIO` errors (with the underlying status and detail retained), not capability
+signals that permit an ordinary-copy retry. Checked cleanup cannot undo that
+terminal classification.
+This addition does not change other APIs' native-mode or permission contracts.
+
 The native layer exposes policy-free filesystem mechanisms: beneath-root
 open/mkdir/link, replace and no-replace rename, identity reads, archive decode/execution,
-clone/copy/hash workers, and Windows security descriptor calls. The TypeScript
+clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor calls. The TypeScript
 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.
-
-Native primitives back create-only and replacing pinned writes, async sidecar creation,
-guarded publication, archive acceleration, and direct Windows ACL operations.
-Equivalent JavaScript paths remain available for documented fallback-capable
-features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
+- 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.
+
+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
+`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
+fallback-capable features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
 for the exact difference.
 
 The guarded JavaScript mutation path is detection-based, not containment-atomic.

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

@@ -50,15 +50,56 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   race-atomic. macOS uses `renameatx_np(RENAME_EXCL)` and permits
   `fclonefileat` in an owned, non-shared parent. The clone is normalized inside
   a private staging directory: flags, ACLs, extended attributes, and broad mode
-  bits are cleared before no-replace publication.
+  bits are cleared before no-replace publication. Clone admission obtains mode,
+  owner, exact identity, flags, and ACL state together from the retained descriptor;
+  immutable receipts are compared across the private staging operation and against
+  fresh no-follow pathname identity reads. Any extended entry on the target parent
+  or private staging directory is rejected before cloning bytes. The payload's
+  cleared ACL and normalized descriptor facts are verified before publication and
+  again, with a fresh published-name identity fence, before its descriptor is
+  returned. Unsupported admission before payload
+  creation or an unsupported clone syscall may still select the documented
+  ordinary-copy path. After the clone creates bytes, normalization and security
+  verification failures report terminal `EIO`, retaining the original error
+  detail; successful cleanup does not make them eligible for ordinary-copy retry.
+  Cleanup failures remain secondary diagnostics, and already-terminal publication
+  errors such as `EEXIST` retain their status.
 - Windows uses handle-relative `NtCreateFile` with `OBJ_DONT_REPARSE` and
   `FILE_OPEN_REPARSE_POINT`, then explicitly rejects reparse points. Rename and
   hardlink operations stay rooted in already-open handles. Owner/DACL reads
   use `GetSecurityInfo`; private directories receive their protected DACL in
-  the `CreateDirectoryW` call itself.
+  an exclusive, handle-relative `NtCreateFile` call. Their created handles remain
+  open through ACL and pathname-association checks and own any failure cleanup.
+  N-API descriptors cross into and out of
+  this layer only through the host executable's paired libuv descriptor bridge;
+  missing or partial exports fail with `ENOTSUP` instead of trying a raw HANDLE
+  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
+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.
 
 ## Archives
 
+Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
+the async reader. ZIP reuses its parsed directory; TAR retains admitted member
+offsets. TypeScript validates and selects the requested member before reading. The internal binding borrows that allocation: it must never be
+mutated or detached while the reader or a read task exists. The public API only
+accepts a pathname and owns this buffer exclusively. An N-API reference keeps
+the bytes alive; a mutex serializes access to the retained ZIP cursor. Plain
+TAR copies only the selected range after complete admission, while gzip, zstd,
+and bzip2 replay bounded decompression and validate the full physical stream.
+Concurrent TAR reads share immutable input and own separate decoder state.
+Each output owns a new vector, which N-API transfers to Node without a second
+payload copy on runtimes supporting external buffers. No entry-read path
+requires temporary-file staging. Extraction retains its private staged input.
+
 Rust streams ZIP and TAR payloads, including gzip, zstd, and bzip2. It first
 returns a bounded manifest. TypeScript applies the shared path, filter, strip,
 mode, and byte policies and returns an index-bound extraction plan. Rust then
@@ -112,18 +153,30 @@ All routes preserve `wx` semantics and the same source/target identity and
 SHA-256 fencing. Native hashing and Linux whole-file copying run on N-API async
 workers rather than the JavaScript event loop.
 
+Linux range copying confirms every zero-byte result with a positioned source
+read at the current transfer offset, including after earlier calls copied data.
+If readable bytes remain, automatic Root copying resumes its byte loop from
+that offset; exclusive publication removes its partial target before retrying
+the guarded byte-copy fallback. EOF checks preserve descriptor cursors and do
+not bypass the byte limit.
+
 ## Mode semantics
 
 | Mode | Native loading | Fallback |
 |---|---|---|
-| `auto` | Try once, cache the result | Use guarded JavaScript when unavailable |
+| `auto` | Try once, cache the result | Use guarded JavaScript when safe; reject native-only operations |
 | `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
-| `off` | Never attempt a binding load | Always use guarded JavaScript |
+| `off` | Never attempt a binding load | Use guarded JavaScript when safe; reject native-only operations |
+
+`sha256FileSync()` is a synchronous Node implementation in all three modes and
+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 zstd/bzip2 TAR,
-Windows private-directory creation, 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`.
+Features without a safe JavaScript implementation, including no-clobber
+`Root.move()`, zstd/bzip2 TAR, Windows private-directory creation, 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`.
 
 The staged-file owner also serves POSIX native pinned writes, including streaming.
 Unpublished files remain at `0600`; requested modes are applied through the
@@ -160,12 +213,12 @@ remain TypeScript-owned. What changes is the syscall strength or availability:
 
 | 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. 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. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves the pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| 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. |
 | 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`. |
 | 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. | Established .NET/`icacls` inspection fallback for coarse permission checks; raw ACE facts are native-only. |
+| 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. |
 
 Use `off` in CI to keep the fallback contract exercised. Use `require` when a