@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -0,0 +1,109 @@
+# Directory entries
+
+`Root.entries()` observes one directory at a time. Use it when the application
+owns traversal order or must inspect symlinks itself, such as an installer that
+validates selected dependency links or a manifest builder that rejects all links.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const workspace = await root("/srv/workspace");
+for await (const entry of workspace.entries("plugins", {
+  maxEntries: 1_000,
+  signal: AbortSignal.timeout(5_000),
+})) {
+  if (entry.isSymbolicLink) {
+    throw new Error(`unexpected link: ${entry.name}`);
+  }
+  console.log(entry.name, entry.size);
+}
+```
+
+## API
+
+```ts
+interface Root {
+  entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
+}
+
+type RootEntriesOptions = {
+  maxEntries?: number;
+  order?: "filesystem" | "sorted";
+  signal?: AbortSignal;
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
+};
+```
+
+Each result is the existing [`DirEntry`](types.md) shape: a basename and advisory
+`lstat` metadata, including `isFile`, `isDirectory`, `isSymbolicLink`, `size`,
+`mode`, `nlink`, `dev`, and `ino`. Entries are immediate children; the iterator
+never descends. An empty path or `"."` selects the root directory.
+
+Child symlinks are always reported without following them, including dangling
+links and links whose targets lie outside the root. Their metadata describes
+the link, not its target. Hardlinked files are also reported regardless of the
+Root's read hardlink policy. Reporting a name grants no read or mutation access.
+Use the Root operation methods when consuming or changing an entry.
+
+The `symlinks` option applies only to the path of the selected directory. It
+inherits the Root's read policy and defaults to `"reject"`. The two follow
+policies allow only contained aliases; `"follow-parents-within-root"` also
+rejects a link as the final directory component. Child-link reporting is
+independent of this path policy.
+
+## Work limits and ordering
+
+`maxEntries` is an optional non-negative safe integer. Every child counts,
+including directories, symlinks, special files, and entries the caller later
+ignores. Omit it to leave the count unbounded. An empty directory satisfies a
+zero limit. Exceeding the limit throws `FsSafeError` with code `"too-large"`;
+there is no silent truncation or success marker for a partial scan.
+
+The default `order: "filesystem"` reads names incrementally in the filesystem's
+nondeterministic order. It observes one child's metadata per iterator step,
+with one name of lookahead to distinguish an exact limit from an overflow.
+Entries already yielded before overflow remain partial observations. A caller
+that stops early has not established that the whole directory fits the limit.
+
+`order: "sorted"` collects names first and orders them with JavaScript's default
+string sort, not locale collation. With `maxEntries`, names are collected from
+a bounded directory stream; overflow rejects before yielding any entries or
+requesting their full metadata. Without a limit, sorted mode enumerates the
+complete name list. Metadata is observed only as each sorted entry is consumed.
+Applications that need locale-specific ordering can collect with an explicit
+limit and apply their own comparator.
+
+The count bounds logical directory reads and fs-safe metadata requests. Node
+may classify a directory entry with `lstat` when the filesystem omits type
+information, including the single lookahead entry. It does not bound elapsed
+time for an individual filesystem operation or the size of one filename.
+
+Cancellation is checked before setup and around awaited work. Directory
+handles close on completion, overflow, cancellation, failure, and early
+`break` or iterator return. In-flight filesystem work settles before rejection;
+an individual syscall cannot be interrupted. If iteration and disposal both
+fail, a `SuppressedError` retains the close failure in `error` and the original
+failure in `suppressed`.
+
+## Identity and caller responsibilities
+
+The iterator reuses Root's guarded directory-listing owner. It validates the
+selected path, pins exact Root and directory identities, and checks them around
+directory observations, including after control returns from the caller. A
+replaced directory rejects instead of continuing under the replacement.
+
+These are pure-Node, best-effort checks. The iterator does not hold descriptors
+for every path component and cannot sandbox a hostile process that repeatedly
+swaps and restores directories. Results are not an atomic snapshot, an exact
+identity receipt, or permission to use the name later. Contents and metadata
+can change between entries; a removed entry may cause iteration to reject.
+Use an admitted descriptor for metadata and hashing that must refer to the same
+opened file, and keep snapshot consistency or cooperative locking with its
+application owner.
+
+Traversal strategy, global budgets, ignored names, and approved external peers
+remain application policy. A per-directory physical-entry limit cannot replace
+a global file-only or unique-directory budget. Full metadata also requires a
+child `lstat`; a caller that previously needed only `Dirent` types should assess
+that cost. `Root.walk()` remains the recursive option for its supported link,
+pruning, and error policies; `Root.list()` returns an eager advisory listing.

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

@@ -38,6 +38,14 @@ class FsSafeError extends Error {
 
 `cause` is available through the standard `Error` `cause` property when the failure was triggered by a `NodeJS.ErrnoException` (e.g. a wrapped `EACCES`). Inspect it for the original `code` / `errno` / `syscall` if you need finer-grained reporting.
 
+Guarded write preparation describes permission, read-only filesystem, and disk-space
+failures with messages such as `permission denied (EACCES)` or
+`no space left on device (ENOSPC)`. Other errno failures include their code in
+`filesystem write failed (EIO)`. These wrappers retain the existing `invalid-path`
+code and `policy` category for compatibility, along with the original `cause`;
+they do not expose native message text or paths. Already-classified `FsSafeError`
+instances and missing-path errors keep their existing classification.
+
 `details` is an operation-specific receipt, not an alternate error code. For
 example, `publishFileExclusive()` uses it to report the failing phase, created
 target identity, cleanup decision, and failed directory-sync outcome. Narrow
@@ -114,14 +122,14 @@ type FsSafeErrorCode =
 | `device-path` | A read/open target is a known unsafe device or process-fd path. | `/dev/zero`, `/dev/random`, `/dev/stdin`, `/dev/fd/*`, `/proc/*/fd/*`, or a Windows reserved device name. |
 | `hardlink` | Read or copy with `hardlinks: "reject"` saw `nlink > 1`. | File is hardlinked — possibly an alias of an out-of-tree inode. |
 | `helper-failed` | A native mechanism or multi-step operational helper failed. | Inspect `cause` and any operation-specific `details`; retrying may be unsafe if the operation partially completed. |
-| `helper-unavailable` | Required native binding could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
+| `helper-unavailable` | A required native binding or bounded primitive could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, `FS_SAFE_NATIVE_MODE=off`, or a no-clobber `Root.move()` without safe native parent admission. `auto` falls back only where a safe fallback exists. |
 | `insecure-permissions` | A secure file or path permission check found a mode/ACL that allows broader access than requested. | File or directory is group/world writable/readable; Windows ACL grants broad read. |
 | `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable; a FileStore key used a noncanonical spelling. | Noncanonical FileStore aliases, backslashes, or complete parent segments; a network path on Windows; a drive-relative segment in a portable relative path or store key; or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain broader confined path compatibility, including legal POSIX drive-like names. |
-| `not-empty` | `remove()` on a non-empty directory. | Use `replaceDirectoryAtomic` or remove children first. |
+| `not-empty` | Nonrecursive `remove()` on a non-empty directory, or new children appeared during recursive removal. | Use bounded `recursive: true` removal or coordinate concurrent writers. |
 | `not-file` | Read or copy targeted a non-regular file, or a path walk found a non-directory ancestor. | Target was a directory, FIFO, socket, device, or an existing file was followed by another segment. |
 | `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). | Typical missing-file case. |
 | `not-owned` | A secure file owner check failed. | File is owned by another UID. |
-| `not-removable` | `remove()` couldn't `unlink`/`rmdir` for a reason other than non-empty. | Permissions, device busy, immutable bit. |
+| `not-removable` | `remove()` couldn't inspect a directory stream or `unlink`/`rmdir` for a reason other than non-empty. | Permissions, device busy, immutable bit; the original filesystem error remains in `cause`. |
 | `outside-workspace` | Path resolves outside the configured root. | `..` traversal; absolute path outside the root; symlink resolved out. |
 | `path-alias` | A path alias check failed (e.g. canonical-real-path moved out of the root). | Symlink resolution lands outside the root. |
 | `path-mismatch` | Post-open identity check failed: the opened fd does not match the resolved path. | TOCTOU — something else swapped the path between resolve and open. |
@@ -131,16 +139,16 @@ type FsSafeErrorCode =
 | `store-reentrant-update` | A `JsonStore.update()` callback called `update()` or `updateOr()` for the same canonical store before returning. | Reentrant mutation would deadlock or lose an update; return the complete next value from the outer callback. |
 | `symlink` | Path component is a symlink, policy is `reject`. | Caller followed a symlink they shouldn't have, or `symlinks: "reject"` is set. |
 | `timeout` | An operation with a wall-clock budget overran. | Secure file read or timed operation exceeded `timeoutMs`. |
-| `too-large` | A read or bounded walk exceeded its configured budget. | Caller gave a too-permissive file or traversal limit. |
-| `unsupported-platform` | Reserved compatibility code for a platform-specific operation. | No current public helper emits this `FsSafeError` code. Platform-specific APIs currently return a typed unsupported result or use `helper-unavailable`; keep the union member when exhaustively switching across supported package versions. |
+| `too-large` | A read, bounded walk, or recursive removal exceeded its configured budget. | Review the expected file or tree size before increasing the limit; recursive removal may have completed earlier entries. |
+| `unsupported-platform` | The platform or filesystem cannot perform the requested operation. | `createCloneSource` and `copyTree({ clone: "always" })` require native cloning support. The default `copyTree({ clone: "auto" })` selects portable byte copying when cloning is unavailable; unsupported source contents or metadata still fail. See [directory copying](copy.md) for backend limits and fallback behavior. |
 
 Secret writes reject invalid `mode` / `dirMode` values with `invalid-path` before directory creation. Existing secret directories with a mode different from the requested `dirMode` report `insecure-permissions` without chmod; a created directory whose descriptor ownership no longer matches its initializing effective user reports `not-owned`.
 
-Pathname `sha256File()` also reports `path-mismatch` when pre-open, descriptor,
-or current-path identity remains unknown after one bounded Windows retry, even
-if the file is benign. It never reopens to recover identity. Preview symlinks
-report `symlink`, preview or descriptor non-files report `not-file`, and a
-current-path symlink or non-file reports `path-mismatch`.
+Pathname `sha256File()` and `sha256FileSync()` also report `path-mismatch` when
+pre-open, descriptor, or current-path identity remains unknown after one bounded
+Windows retry, even if the file is benign. Neither reopens to recover identity.
+Preview symlinks report `symlink`, preview or descriptor non-files report
+`not-file`, and a current-path symlink or non-file reports `path-mismatch`.
 
 ## Branching
 

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

@@ -0,0 +1,68 @@
+# Exact file comparison
+
+`sameFileContentsSync()` compares the bytes of two already-open regular files,
+starting at offset zero. It uses bounded buffers and completes positive short
+reads independently on each descriptor. A `true` result requires matching bytes
+and observed EOF on both inputs; a difference can return `false` immediately.
+
+```ts
+import fs from "node:fs";
+import { sameFileContentsSync } from "@openclaw/fs-safe/advanced";
+
+const source = fs.openSync("/trusted/source.sqlite", "r");
+try {
+  const copy = fs.openSync("/trusted/copy.sqlite", "r");
+  try {
+    console.log(sameFileContentsSync(source, copy, { maxBytes: 256 * 1024 * 1024 }));
+  } finally {
+    fs.closeSync(copy);
+  }
+} finally {
+  fs.closeSync(source);
+}
+```
+
+## Signature
+
+```ts
+type SameFileContentsOptions = { maxBytes?: number };
+
+function sameFileContentsSync(
+  leftFd: number,
+  rightFd: number,
+  options?: SameFileContentsOptions,
+): boolean;
+```
+
+Both descriptors must be open regular files. Nonregular inputs throw
+`FsSafeError("not-file")`; underlying filesystem errors propagate unchanged.
+Passing the same descriptor twice is allowed, but does not bypass validation,
+the byte limit, or reads. File sizes are checked against the limit, but are not
+used as proof that contents match or that EOF has been reached.
+
+## Bounds and ownership
+
+`maxBytes` is a limit for each file, not their combined size. It accepts a
+non-negative safe integer or `Infinity`; omission imposes no caller-selected
+limit. Invalid limits throw `RangeError` before filesystem work. Comparisons
+cannot exceed `Number.MAX_SAFE_INTEGER` bytes because positions must remain
+exactly representable.
+
+A reported file size above the limit throws `FsSafeError("too-large")` before
+reading. At the limit, the comparison reads at most one additional byte from
+each input to prove EOF; any observed overflow throws the same error. A
+matching prefix is never reported as complete equality. An early mismatch
+does not scan the remaining bytes or promise to detect later errors or growth.
+A zero-byte limit admits two empty files. Memory use is at most two 1 MiB
+payload buffers, regardless of file size.
+
+The operation neither changes the descriptors' current offsets nor closes
+them, including on failure. It performs no writes, hashing, pathname lookup,
+or identity comparison. Callers retain path admission, hardlink policy,
+descriptor lifetime, and any before/after mutation-fingerprint checks. A
+comparison is not a snapshot of concurrently modified files; applications
+requiring stable contents must retain their existing coordination and checks.
+
+Use [`readFileWindowFullySync()`](positional-read.md) for a selected byte
+window and [bounded descriptor reads](advanced.md#files-and-identity) when the
+caller needs the file contents in memory.

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

@@ -28,9 +28,18 @@ const cache = fileStore({
   dirMode: 0o700,     // mode for parent directories created on demand (default 0o700)
   maxBytes: 64 * 1024 * 1024, // optional: refuse writes/reads larger than this
   private: true,      // use secret-file atomic writes for private state
+  durable: true,      // sync file and parent directory (default true)
 });
 ```
 
+| `FileStoreOptions` option | Default | Purpose |
+|---|---|---|
+| `rootDir` | Required | Store directory. |
+| `private` | `false` | Use the secret-file atomic path. |
+| `mode` / `dirMode` | `0o600` / `0o700` | File and parent-directory modes. |
+| `maxBytes` | Unset | Store read/write byte limit. |
+| `durable` | `true` | Sync the written file and its parent directory; see method support below. |
+
 Store and per-call `maxBytes` values must be non-negative safe integers or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` disables the cap. An omitted or explicitly `undefined` per-call value preserves the store-level limit. The same rule applies to buffer writes, streams, copies, async reads, and synchronous reads/writes.
 
 Use `private: true` for credentials, auth profiles, tokens, and other private
@@ -81,13 +90,16 @@ or converts one caller-supplied key onto another:
   are rejected.
 - Windows drive-relative segments such as `C:name` or `C:` are rejected
   anywhere in a key, including `a/C:name`.
+- On Windows, every other colon is rejected too, preventing a key from naming
+  an NTFS alternate stream or directory-index alias. POSIX keeps accepting
+  ordinary colon-bearing segments that are not drive-relative spellings.
 - No segment may end in an ASCII dot or space.
 
 Violations report `invalid-path` when key validation is reached. Ordinary nested
 keys, NFC Unicode such as `café/日本語.txt`, `.hidden`, `a..b`, and internal spaces
-such as `internal space/a b.txt` are accepted. Colons elsewhere, such as the
-timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid; filesystem
-success still depends on the platform and the underlying Root policies.
+such as `internal space/a b.txt` are accepted. On POSIX, colons elsewhere, such
+as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid;
+Windows rejects that spelling as stream syntax.
 
 Validation retains each method's operation order. Async reads, `exists`, and
 `remove` open the root first: if the root is missing, strict methods report
@@ -101,7 +113,62 @@ therefore does not imply that no filesystem access or serialization occurred.
 
 ## Writes
 
-Every write goes through `writeSiblingTempFile` — temp + rename, mode applied to file and parent dir, both `fsync`'d.
+Writes use guarded sibling-temp publication: apply file and directory modes,
+then rename into place. By default, the file and parent directory are synced
+where supported by the platform and writer.
+
+`durable: false` keeps the 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. Per-call
+`durable` overrides the store option, which defaults to `true`; an omitted or
+`undefined` override preserves the store default. Modes, path confinement,
+and publication identity checks are unchanged.
+
+Synchronous writes retain their original write-only descriptor through rename
+and publication checks, using exact bigint file identities. When Windows cannot
+report a pathname's identity, verification reopens the name only to compare its
+descriptor with the retained writer; it never reads file contents. A substituted
+file is rejected even if its bytes match, and a post-publication failure leaves
+the published entry intact for caller-owned recovery. Ordinary write-only and
+mode-000 outputs do not require a readable descriptor when pathname metadata is
+available.
+
+If a synchronous write operation and its final temp-descriptor close both fail,
+the store reports them in operation-then-close order in an `AggregateError`.
+This ordering and the original JavaScript thrown value are preserved even when
+that value is `undefined` or otherwise falsy. An unsuccessful best-effort temp
+unlink remains registered for identity-checked process-exit cleanup; it does not
+prevent the close attempt or replace either reportable failure.
+
+If an opaque pathname cannot be reopened because of an ACL denial or sharing
+restriction, the synchronous writer intentionally rejects with `path-mismatch`:
+its exact publication identity cannot be verified. There is no equal-content
+fallback. The published entry remains present, so callers must inspect or
+recover that outcome instead of assuming the write did not occur.
+
+Synchronous directory creation retains exact bigint receipts for the store root
+and every parent component. On POSIX, an existing or newly created directory
+whose complete requested mode differs is reopened without following the final
+name, checked against its receipt and parent chain, and finalized through that
+descriptor. A concurrent root or parent replacement is rejected without
+applying the mode to the replacement. Directories already at the requested mode
+skip the descriptor and mode operation. Windows retains its bounded `mkdir`
+mode request and identity checks without relying on directory descriptors or a
+pathname `chmod`, because Node does not enforce POSIX directory modes there.
+
+Node does not expose a portable, `fchmod`-capable search-only directory
+descriptor on Linux. If a mismatched existing directory, or one created under
+an owner-read-removing umask, cannot be opened for reading, the synchronous
+store therefore fails closed with `permission-unverified`; it never falls back
+to pathname `chmod`. On supported macOS x64/arm64 hosts it also tries an
+`O_SEARCH` descriptor, so owner-searchable directories can still be repaired.
+Directories with neither usable read nor search access remain fail-closed.
+
+| Method | Durability support |
+|---|---|
+| `write`, `writeText`, `writeJson` (async and sync) | Per-call option overrides store default. |
+| `writeStream`, `copyIn` (either private mode) | Per-call option overrides store default. |
+| JSON `write`, `update`, `updateOr` | JSON handle option overrides file-store default. |
 
 ### `write(rel, data, options?)`
 
@@ -118,7 +185,7 @@ Convenience wrappers over `write`. `writeJson` pretty-prints with a trailing new
 ### `json<T>(rel, options?)`
 
 Returns a typed single-file JSON state helper for a file under this store. It
-inherits the store's root, mode, max-size, and private-write policy, then adds
+inherits the store's root, mode, max-size, durability, and private-write policy, then adds
 `readOr`, `readRequired`, `update`, `updateOr`, and optional sidecar locking:
 
 ```ts
@@ -129,6 +196,9 @@ await state.updateOr(defaultState, (current) => ({ ...current, enabled: true }))
 Use this when one JSON file owns one piece of state. `jsonStore({ filePath })`
 is the absolute-path convenience wrapper for the same primitive.
 
+Pass `{ durable: false }` or `{ durable: true }` to `json()` to override the
+parent store's durability for all mutations of that JSON handle.
+
 ### `writeStream(rel, stream, options?)`
 
 ```ts
@@ -138,6 +208,9 @@ const path = await cache.writeStream("downloads/blob.bin", Readable.from(remoteF
 
 Streams into a sibling temp with a running byte budget. Aborts the source stream with `too-large` if `maxBytes` is exceeded mid-stream — partial writes are cleaned up.
 
+Streams honor `durable` in both private modes. Non-private streams stage their
+input and forward the resolved durability option to Root `copyIn` for publication.
+
 ### `copyIn(rel, sourcePath, options?)`
 
 ```ts
@@ -146,12 +219,24 @@ const path = await cache.copyIn("ingest/upload.bin", "/tmp/upload.bin");
 
 One-shot ingest from an absolute source path. Source is checked for symlink/non-regular before copy. Same mode rules as `write`.
 
+`copyIn` honors per-call and store-level `durable` values in both private modes,
+with the same precedence as `write`.
+
 ### `FileStoreWriteOptions`
 
 Per-call overrides for the store-level defaults:
 
+Writes capture byte limits, modes, and durability before asynchronous work or
+stream consumption. JSON writes capture those fields and the trailing-newline
+setting before serialization. Later mutation cannot change those captured values.
+Accessors run on the original options object. Ordinary writes retain content
+conversion and byte-limit validation before reading modes and durability.
+The legacy non-private stream `tempPrefix` accessor still runs after staging;
+it does not control the publication policy.
+
 ```ts
 type FileStoreWriteOptions = {
+  durable?: boolean;   // store default, otherwise true
   dirMode?: number;
   mode?: number;
   maxBytes?: number;
@@ -159,6 +244,17 @@ type FileStoreWriteOptions = {
 };
 ```
 
+| `FileStoreWriteOptions` option | Default |
+|---|---|
+| `durable` | Store option, otherwise `true`. |
+| `dirMode` / `mode` | Store directory/file modes. |
+| `maxBytes` | Store byte limit. |
+| `tempPrefix` | Writer-specific temporary prefix. |
+
+The same durability precedence applies to `fileStoreSync().write`,
+`writeText`, and `writeJson`. The synchronous store has no `writeStream` or
+`copyIn` methods.
+
 ## Reads
 
 `open`, `read`, `readBytes`, `readText`, and `readJson` delegate to a fresh `Root` with `hardlinks: "reject"` and the store's `maxBytes`. Same return shapes as `Root`.
@@ -196,6 +292,16 @@ type FileStorePruneOptions = {
 
 Symlinks are skipped. The walk is best-effort — failures on individual entries don't abort the whole prune. Compares against `mtimeMs`.
 
+Pruning rechecks that a selected entry is still a regular file and still expired
+immediately before guarded removal. Fresh replacements and in-place timestamp
+refreshes are preserved; replacements that are themselves expired remain
+eligible. This does not require read permission. The existing best-effort
+external-process race window after dispatch still applies.
+
+Empty-directory pruning likewise rechecks that the selected entry is still a
+directory immediately before guarded removal. File and symlink replacements
+are preserved, and a directory that becomes nonempty is left in place.
+
 ## Difference from `Root`
 
 | `FileStore` | `Root` |
@@ -254,5 +360,5 @@ await root.move(`pending/${id}`, `done/${id}`);
 
 - [`root()`](root.md) — the boundary `FileStore` is built on; reach for it when you need move/list/append.
 - [JSON store](json-store.md) — the JSON-state-file equivalent of this surface.
-- [Atomic writes](atomic.md) — `writeSiblingTempFile` is what every write goes through.
+- [Atomic writes](atomic.md) — lower-level sibling-temp publication helpers.
 - [Temp workspaces](temp.md) — private scratch directories backed by `FileStore`.

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

@@ -1,6 +1,6 @@
 # Filenames
 
-`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; pair with [`safeDirName`](install-path.md#safedirname) when you need stricter directory-name handling.
+`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; use [`safePathSegmentHashedV2`](install-path.md#safepathsegmenthashedv2) when mapping untrusted install IDs to separate directory names.
 
 ```ts
 import { sanitizeUntrustedFileName } from "@openclaw/fs-safe/advanced";
@@ -17,15 +17,27 @@ function sanitizeUntrustedFileName(fileName: string, fallbackName: string): stri
 
 ## What it does
 
-In order:
+The primary name goes through this pipeline first:
 
-1. **Trim** whitespace. If the result is empty, return `fallbackName`.
+1. **Trim** whitespace. An empty result is unusable.
 2. **Strip path components.** Apply `path.posix.basename` then `path.win32.basename` so neither `foo/bar.txt` nor `foo\bar.txt` survives — only the final segment remains.
 3. **Strip non-portable characters.** C0/C1 controls (`0x00`–`0x1f`, `0x7f`–`0x9f`) and the Windows-invalid set `< > : " / \\ | ? *` are removed on every platform.
 4. **Trim again.**
-5. If the result is empty, `"."`, or `".."`, return `fallbackName`.
-6. **Suffix Windows reserved basenames.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension, preserving the original case and extension on every platform.
-7. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
+5. An empty result, `"."`, or `".."` is unusable.
+6. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
+7. **Make the final name device-safe.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension on every platform. If the suffix would exceed 200 code units, the unsuffixed tail is shortened first, so truncation cannot recreate a device name.
+
+Only when the primary name is unusable does `fallbackName` go through the same
+nonrecursive pipeline. A safe fallback is preserved exactly; path components,
+controls, reserved device names, and overlong fallback names receive the same
+treatment as the primary name. If both candidates are unusable, the function
+returns the fixed safe literal `"file"`.
+
+If truncation itself exposes a reserved-device basename after Windows ignores
+trailing spaces or dots, the result is shortened once more and receives the
+same underscore suffix. A name that reaches the sanitization branch therefore
+remains at most 200 UTF-16 code units and is never a Windows reserved-device
+alias. Fallback names pass through the same checks before they can be returned.
 
 That's it. The function stays intentionally small: it removes traversal and
 the most obvious cross-platform device and character hazards, but it is not a
@@ -41,6 +53,8 @@ sanitizeUntrustedFileName("a\u0000b\tc", "upload");       // "abc"
 sanitizeUntrustedFileName("   ", "fallback");              // "fallback"
 sanitizeUntrustedFileName(".", "fallback");                // "fallback"
 sanitizeUntrustedFileName("..", "fallback");               // "fallback"
+sanitizeUntrustedFileName("<>", "../../etc/passwd");       // "passwd"
+sanitizeUntrustedFileName("<>", "../..");                  // "file"
 sanitizeUntrustedFileName("CON", "fallback");              // "CON_"
 sanitizeUntrustedFileName("nul.txt", "fallback");          // "nul_.txt"
 sanitizeUntrustedFileName("aux.c", "fallback");            // "aux_.c"
@@ -92,5 +106,5 @@ await fs.write(`uploads/${safe}`, body); // fs is a Root() handle; rejects trave
 
 ## See also
 
-- [Install path helpers](install-path.md) — `safeDirName`, `safePathSegmentHashed` for directory-segment sanitization.
+- [Install path helpers](install-path.md) — legacy directory-segment sanitizers and `safePathSegmentHashedV2` for untrusted install IDs.
 - [`root()`](root.md) — the boundary you'll write into after sanitizing.

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

@@ -0,0 +1,146 @@
+# Guest filesystem source
+
+`@openclaw/fs-safe/guest` exports Python 3 source for filesystem operations in
+Linux and macOS guests that do not have Node installed. The host imports a
+string and passes it to its existing container, SSH, or process transport.
+Importing this subpath performs no I/O and launches no process.
+
+This is the filesystem engine extracted from OpenClaw's sandbox bridge. The
+caller still owns root admission, mount selection, read-only policy, canonical
+path authorization, live authority, argument framing, and process lifetime.
+Use [Root](root.md) for ordinary filesystem operations in the Node process.
+This source artifact is separate from the retired host-side Python worker
+described in [Migrating to 0.5](migrating-to-0.5.md).
+
+## Exports and requirements
+
+```ts
+import {
+  GUEST_FILESYSTEM_PYTHON,
+  GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE,
+  GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE,
+  GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON,
+} from "@openclaw/fs-safe/guest";
+```
+
+`GUEST_FILESYSTEM_PYTHON` is the complete single-invocation program. The two
+exit constants are `17` for an exclusive-create collision and `2` for a
+missing read parent or leaf after the root opens. Other nonzero statuses are
+errors; stderr is diagnostic text, not a structured error protocol.
+
+The guest needs Python 3 with `ctypes`, descriptor-relative POSIX operations,
+`O_DIRECTORY`, and `O_NOFOLLOW`. Linux and macOS are the supported guest
+platforms. The guest does not need fs-safe's Node package, native addon, Rust,
+or WASM. Native mode configuration in the host does not configure this program.
+
+`GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON` contains just the
+`rename_no_replace(src_parent_fd, src_basename, dst_parent_fd, dst_basename)`
+definition. OpenClaw's workspace bootstrap consumes this same fragment when
+publishing a prepared workspace; exporting it avoids a second source owner.
+Its embedding program must import `ctypes`, `errno`, `os`, and `sys`, admit
+the descriptors and single-component names, and own cleanup and syncing.
+The fragment has no argument preflight of its own.
+
+On Linux it uses `renameat2(RENAME_NOREPLACE)`; on macOS it uses
+`renameatx_np(RENAME_EXCL)`. If Linux lacks that function or reports it as
+unsupported, it falls back to `link(..., follow_symlinks=False)`, leaving the
+source entry for caller cleanup. That fallback supports files, not directory
+publication. Existing destinations are never replaced by this fragment.
+
+## Invocation protocol
+
+Pass the source through `python3 -c` and arguments as literal argv elements.
+Do not concatenate untrusted values into a shell command. Transport adapters
+that require a shell must apply their existing quoting rules to every element.
+The following example uses an already admitted guest root and parent path:
+
+```ts
+import { spawnSync } from "node:child_process";
+import { GUEST_FILESYSTEM_PYTHON } from "@openclaw/fs-safe/guest";
+
+const result = spawnSync("python3", [
+  "-c", GUEST_FILESYSTEM_PYTHON,
+  "write", "/srv/admitted-workspace", "notes", "today.txt", "1",
+], { input: Buffer.from("hello\n"), timeout: 10_000 });
+if (result.error) throw result.error;
+if (result.status !== 0) throw new Error(result.stderr.toString());
+```
+
+All frames below start at `sys.argv[1]`. `root` is an admitted guest directory;
+`parent` and `directory` are paths relative to that root. An empty relative
+path selects the root itself. Flags are strings: `"1"` enables and `"0"`
+disables. Do not omit required fields.
+
+| Operation | Positional frame | Input / output |
+|---|---|---|
+| Read | `read root parent basename [maxBytes]` | Raw bytes on stdout; optional nonnegative integer byte limit. |
+| Write | `write root parent basename mkdir` | Raw stdin; atomically replaces a file entry. |
+| Create | `create root parent basename mkdir` | Raw stdin; exclusively publishes a completed file. |
+| Copy | `copy srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Regular-file copy, atomically replaces destination. |
+| Rename | `rename srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Rename with cross-device copy/delete fallback. |
+| Remove | `remove root parent basename recursive force` | Removes the leaf, or recursively removes its tree. |
+| Make directories | `mkdirp root directory` | Creates missing relative directory components. |
+| List directory | `readdir root directory` | JSON array of `{ name, isDirectory, isFile }`; both kind fields are false for symlinks and special entries; no sorting guarantee. |
+
+The complete program rejects empty, `.`, `..`, slash-containing, and NUL
+basenames before opening roots or creating parents. Both leaf operands of copy
+and rename are checked. Backslashes, colons, quotes, and newlines remain legal
+POSIX basename characters. Relative directory traversal rejects `..`; empty
+and `.` components are skipped. Supply admitted relative paths, not arbitrary
+absolute paths whose spelling happens to pass that component walk.
+
+## Boundary and operation behavior
+
+The supplied root spelling is trusted. Opening it does not prove the root is
+the mount or inode previously authorized by the caller. Basename syntax checks
+are not authorization. Callers must admit their roots and paths, preserve
+read-only shadows and live authority, and run the program inside the intended
+OS isolation boundary.
+
+Parent traversal and operation bodies use directory descriptors. Reads and
+copies refuse final symlinks, hardlinked files, and nonregular files. Bounded
+reads check both admitted size and consumed bytes; a growing file can produce
+partial stdout before rejection. Consumers must discard read output when the
+exit status indicates failure. Removal unlinks a final symlink without
+following it; rename moves symlink entries. Write and copy replace destination
+entries, including symlinks, without following them. A force removal tolerates
+a missing leaf but does not suppress failure to open its parent.
+
+Write preserves an existing regular file's mode and otherwise creates private
+files. Copy preserves the source mode. Exclusive create publishes a mode-0600
+file from a private staging directory. Staging names retain the `.openclaw-*`
+prefixes and use short random suffixes independent of the destination basename,
+so legal names near the filesystem's component limit also work for writes and
+cross-device moves.
+
+Cross-device symlink moves create the new link in a private destination-side
+staging directory before atomically replacing the destination. Link creation or
+publication failure preserves the existing destination and source link; ordinary
+failure cleanup removes the staging directory.
+
+Cross-device directory moves build a copy manifest and check it during source
+cleanup. Source changes can leave the published destination and some or all
+of the source. Regular-file and symlink move fallbacks unlink the source
+pathname after publication; they do not perform the directory manifest's
+identity checks. Directory cleanup also has check-to-unlink race windows.
+These mechanics do not promise content integrity against same-UID peers.
+
+## Failure, cancellation, and budgets
+
+Nonzero exit is not proof that nothing was published. A post-publication
+identity or sync failure, or cross-device source-cleanup failure, can leave a
+destination. The caller owns reconciliation and retry policy; do not assume
+it is safe to remove that destination or replay a mutation blindly.
+
+Ordinary Python failures run `finally` cleanup. There is no cancellation frame
+or signal handler. Process death closes descriptors, but forced termination
+can leave staging names. The transport owns termination, waiting for children
+to settle, and any application-specific recovery.
+
+Read byte limits are optional. Copy, write, recursive removal, directory
+listing, and cross-device tree moves have no byte, entry, or depth budget in
+this protocol. Recursive traversal and listing collect entries eagerly.
+Use caller-owned isolation and resource limits appropriate to the operation.
+The existing fsync sequence is preserved; this is not a recursive transaction,
+rollback facility, or a stronger durability guarantee than the underlying
+filesystem provides.