@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/docs/in-place-write.md

@@ -0,0 +1,81 @@
+---
+title: In-place writes
+description: "Replace bytes through a borrowed file handle while preserving its inode and attempting rollback on failure."
+---
+
+# In-place writes
+
+`overwriteFileHandle()` replaces a regular file's contents through a handle the
+caller already owns. Use it when replacing the inode would break hardlinked
+aliases, or when an existing writable file lives in a directory where the caller
+cannot create a sibling temporary file.
+
+```ts
+import { open } from "node:fs/promises";
+import { overwriteFileHandle } from "@openclaw/fs-safe/advanced";
+
+const handle = await open(filePath, "r+");
+try {
+  await overwriteFileHandle(handle, Buffer.from(nextContents, "utf8"), {
+    beforeWrite: () => assertCurrentOwner(),
+  });
+} finally {
+  await handle.close();
+}
+```
+
+## Contract
+
+```ts
+overwriteFileHandle(
+  handle: FileHandle,
+  data: Uint8Array,
+  options?: { beforeWrite?: () => void },
+): Promise<void>;
+```
+
+The handle must be readable and writable, refer to a regular file, and have been
+opened **without append mode**. Node cannot portably inspect a handle's append
+flag, and some operating systems ignore positioned-write offsets for append
+handles. Opening, path admission, symlink and hardlink policy, and closing remain
+the caller's responsibility. The helper never reopens or replaces the inode,
+changes the handle's current position, or closes it. Every hardlinked alias sees
+the in-place changes.
+
+The payload is borrowed, including its byte offset and length. Keep it unchanged,
+attached, and accessible until the returned promise settles. Do not close the
+handle or run concurrent I/O against the file, including through other aliases,
+during preparation, writing, or rollback. This helper does not acquire a lock.
+
+## Preparation, ordering, and failure
+
+The helper checks the file type and original size, then saves only the prefix
+that will be overwritten: `min(data.byteLength, originalSize)` bytes. A short
+prefix read fails with `FsSafeError("read-failed")` before writing. Memory for the
+backup is bounded by that prefix length; a short replacement of a large file does
+not read or buffer the untouched tail.
+
+After preparation, `beforeWrite` runs synchronously once. A thrown value is
+propagated unchanged without any file mutation. A Promise or thenable return is
+rejected with `TypeError`; asynchronous callbacks cannot admit a write. Once
+admitted, the operation finishes the write or its failure recovery without
+calling `beforeWrite` again. This callback is a whole-operation admission point,
+not the per-mutation `assertBeforeMutation` callback used by Root operations.
+It must not change the file, handle, or payload. There is no cancellation option.
+
+For growth, additional tail bytes are written before the existing prefix is
+touched. The prefix is then overwritten, completing partial writes. For shrinkage,
+truncation is last. If a write or truncation fails, the helper attempts to restore
+the saved prefix, if touched, and the original length. It waits for both recovery
+attempts and then rethrows the original error, even when recovery also fails.
+Zero-progress writes fail with `FsSafeError("helper-failed")`.
+
+Recovery is best effort, not atomic publication or a crash-recovery guarantee.
+Other observers can see intermediate contents; failed recovery can leave partial
+bytes. The helper does not chmod or synchronize the file or its directory.
+Normal filesystem effects such as timestamp updates or clearing special mode
+bits can still occur. Callers own any durability or broader transaction policy.
+
+The implementation uses Node positional reads and writes in every native mode;
+it does not load a native binding. Prefer [`Root.write`](writing.md) when atomic
+replacement and root-based path admission are the intended contract.

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:
@@ -85,34 +119,59 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 ## Runtime dependencies
 
-`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser for guarded JavaScript TAR/gzip [archive extraction](archive.md), including installs with optional dependencies omitted. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability.
+`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser and zstd/bzip2 codecs for guarded [archive extraction and bounded entry reads](archive.md). Plain TAR, gzip, zstd, and bzip2 work in `off` and missing-native `auto`, including installs with all optional dependencies omitted; gzip uses Node's built-in decoder. These archive fallbacks need no runtime interpreter, download, or consumer compiler. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability. Native `require` remains strict, and an available native operation's failure never triggers a WASM retry.
 
 There are no peer dependencies. Exact-version optional packages carry the seven
 native targets and npm-compatible OS, CPU, and Linux libc filters install only
-the matching binary. Consumers do not run a native build, download code at
+the matching binary. Consumers do not run a Rust 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
+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.
+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.
 
 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.
 
+### Windows security fallback
+
+Windows raw owner/DACL inspection, private-directory creation, and secure-file
+reads work without the addon in `auto` or `off` mode when system Windows
+PowerShell and its .NET `Add-Type` compilation support are available. The package
+ships a readable, fixed `.ps1` driver and adjacent `.cs` source and invokes the
+driver with Windows PowerShell `-File`. Paths are passed as data. The fallback
+does not generate helper scripts at runtime or use an encoded launcher.
+The driver addresses built-in commands by module name and limits module
+discovery to PowerShell's bundled system modules, avoiding broad command
+discovery scans during each helper startup.
+
+Normal PowerShell execution policy and Microsoft Defender policy must permit
+the packaged scripts, including their use of `Add-Type`. The package does not
+bypass restrictions, change policies, or add exclusions. Unsupported or
+disallowed command execution fails closed.
+
+The fallback preserves private DACLs at creation and inspects the same open
+handle that supplies secure-file bytes. Each capability emits a path-free
+`FS_SAFE_NATIVE_FALLBACK` warning once per process; each call adds PowerShell
+startup and compilation overhead. Execution or compilation failure also fails
+closed. Native `require` still rejects a missing binding or capability, and an
+available native operation's error never triggers a command retry. See
+[Permissions](permissions.md) and [Secure file reads](secure-file.md).
+
 ## Native helper policy
 
 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" });     // disable the addon; 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,24 @@ 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.
+
+Each `write`, `update`, or `updateOr` invocation captures the retained options'
+`durable` and `trailingNewline` values before queueing, locking, reading, or
+calling the updater. Changes to those options affect later invocations only,
+including when a mutation is waiting behind another operation.
 
 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?)`
@@ -135,10 +146,11 @@ where lower latency matters more than crash-durability.
 
 Synchronous variant. It pretty-prints with two spaces, appends a newline,
 creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
-directory best-effort. File-mode tightening carries the staged bigint identity
-through rename and applies `fchmod` only when the reopened descriptor and current
-pathname still name that same single-link regular file; a swap is preserved and
-skips this best-effort step. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+directory best-effort. A retained staging descriptor carries the exact bigint
+identity through rename and file-mode tightening. Publication and cleanup never
+adopt a substituted temporary file: a changed identity, type or link count rejects
+the write and leaves the replacement untouched. A swap detected after publication
+also rejects without deleting or changing the replacement. It has no options bag. On `EPERM`/`EEXIST`, its legacy
 compatibility path removes the existing destination and retries the staged-file
 rename, so that fallback is temporarily non-atomic while retaining the staged
 file's `0600` mode; use the async `writeJson()`/`replaceFileAtomic()` surfaces

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

@@ -71,18 +71,27 @@ 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),
 so no-follow, identity, hardlink, device-path, and byte-limit checks happen at
 the read itself.
+Link policies are captured once before root initialization and reused for every
+candidate, so replacing options while a read is pending cannot weaken admission.
 
 ```ts
 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/migrating-to-0.5.md

@@ -88,8 +88,10 @@ await extractArchive({
 ```
 
 Returning `"skip"` rejects the archive unless `onFiltered: "skip-entry"` is
-explicit. Zstd and bzip2 TAR are native-only; ZIP, TAR, and gzip retain guarded
-JavaScript implementations. Catch `ArchiveLimitError` by its code, including
+explicit. Zstd and bzip2 TAR required native support in version 0.5; current
+versions also use bundled WASM codecs in `off` or missing-native `auto`, through
+the same guarded TAR pipeline. ZIP fallback still requires optional JSZip.
+Catch `ArchiveLimitError` by its code, including
 `archive-entry-path-components-exceeds-limit` for deep implicit-directory
 attacks. See [Archive extraction](archive.md).
 
@@ -167,10 +169,17 @@ See [File locks](sidecar-lock.md), [Secret files](secret-file.md), and
 
 ## 7. Gate native-only features
 
-`createPrivateDirectory()` is Windows-only and native-only because a pathname
-fallback cannot promise the same creation-time DACL. Zstd/bzip2 extraction and
-`strategy: "rename-noreplace"` are also native-only. Test the unavailable path
-instead of assuming installation always succeeds.
+Version 0.5 required native support for `createPrivateDirectory()`. Current
+releases also support a packaged PowerShell script in native `auto` and `off`
+modes, retaining its creation-time protected DACL. Check the
+[Windows security fallback prerequisites](install.md#windows-security-fallback)
+before relying on this route. The API remains Windows-only, explicit native
+`require` rejects a missing binding or capability, and native operation failures
+remain terminal.
+`strategy: "rename-noreplace"` remains native-only. Current zstd/bzip2 extraction
+and bounded reads have bundled WASM fallbacks, while explicit native `require`
+remains strict. Test unavailable native-only operations instead of assuming
+installation always succeeds.
 
 ## 8. Run both behavior families in CI
 

package/node_modules/@openclaw/fs-safe/docs/migrating-to-0.6.md

@@ -24,10 +24,15 @@ uses native mode `require` or any native-only feature. Version 0.5 kept its
 binding in the root tarball; version 0.6 intentionally does not.
 
 Omitting optional dependencies remains supported for fallback-capable APIs in
-`auto` mode. It disables native-only features such as zstd/bzip2 TAR handling,
-retained-directory staging, atomic `rename-noreplace`, and Windows private
-directory creation. Native mode `require` reports `helper-unavailable` when the
-matching package is absent or incompatible.
+`auto` mode. It disables native-only features such as retained-directory staging
+and atomic `rename-noreplace`. Native mode `require`
+reports `helper-unavailable` when the matching package is absent or incompatible.
+Zstd/bzip2 TAR extraction and bounded reads required the binding in version 0.6;
+current versions also support bundled WASM codecs in `auto` and `off` through the
+same guarded TAR pipeline. ZIP fallback still requires optional JSZip.
+Windows private-directory creation required the binding in version 0.6; current
+releases also support [packaged Windows security scripts](install.md#windows-security-fallback)
+in `auto` and `off` mode while preserving the creation-time protected DACL.
 
 ## Deployment checklist
 

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

@@ -0,0 +1,69 @@
+# 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 stage creation for a missing destination, before publishing a
+complete stage to that still-missing destination, and before publishing to an
+existing symlink-selected destination. Missing destinations must remain absent at
+every authority callback and after refusal. The workers verify alias binding,
+destination preservation, complete single-link stages, 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. In native-require mode, the compatibility route loads
+the addon to publish its retained sidecar lock through `Root.create`; the payload
+writer remains JS. The receipt does not mislabel this as native payload
+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.