@openclaw/fs-safe 0.10.0 → 0.11.0

package/docs/guest.md

@@ -0,0 +1,141 @@
+# 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 }`; 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 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.

package/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/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/docs/install.md

@@ -31,6 +31,37 @@ 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. 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:

package/docs/native-helper.md

@@ -30,10 +30,17 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 | `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.
 
 [`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
@@ -57,7 +64,7 @@ change the mode policy of existing fallback-capable APIs.
 
 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.
 

package/docs/native.md

@@ -133,6 +133,10 @@ workers rather than the JavaScript event loop.
 | `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
 | `off` | Never attempt a binding load | Always use guarded JavaScript |
 
+`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

package/docs/output.md

@@ -35,6 +35,7 @@ type ExternalFileWriteOptions<T = void> = {
   maxBytes?: number;
   mode?: number;
   staging?: "workspace" | "sibling"; // default: "workspace"
+  producerIsolation?: "private-directory"; // opt-in for sibling staging
   fallbackFileName?: string;          // safe staged-name fallback
 };
 
@@ -60,7 +61,7 @@ hazards but does not trim Windows-normalized trailing dots or spaces; reject or
 rewrite those when cross-platform filename uniqueness matters.
 `staging: "workspace"` passes the sanitized basename to the producer.
 `staging: "sibling"` embeds that basename in its randomized temporary name.
-When the complete temporary component would exceed 255 bytes under NFC or NFD,
+When the complete temporary component would exceed 255 bytes as written or under NFC or NFD,
 only the embedded tail is shortened, preserving its extension when possible;
 short callback paths remain unchanged. The final target and returned `path` use
 the destination basename, sanitized
@@ -76,8 +77,8 @@ the temp and destination filesystems may differ, or when an externally produced
 partial file must never appear in the destination directory. The final target
 still appears only after guarded finalization.
 
-`staging: "sibling"` gives the producer a randomized temp path in the target
-directory. Choose it only when that directory itself is the approved writable
+By default, `staging: "sibling"` gives the producer a randomized temp path in
+the target directory. Choose it only when that directory itself is the approved writable
 boundary and same-filesystem atomic replacement is required. After the callback
 returns, fs-safe pins and validates the staged regular file, rejects hardlinks
 and size-limit violations, applies `mode`, fsyncs it, and atomically renames it
@@ -91,11 +92,36 @@ cleanup retry.
 Sibling staging shares the [callback sibling owner](temp.md#sibling-temp-writes):
 it checks exact pre-open, descriptor, and current-path identities, retains the
 descriptor through publication, and never chmods or reads a replacement by path.
-Cleanup preserves unverified paths, including partial output when the callback
-throws before admission. Native-off and Windows operation remain supported with
-the platform limits and non-atomic rename/unlink identity checks described there.
+Without producer isolation, cleanup preserves unverified paths, including partial
+output when the callback throws before admission. Native-off and Windows
+operation remain supported with the platform limits and non-atomic
+rename/unlink identity checks described there.
 When `mode` is omitted, output-sibling staging preserves the producer's mode.
 
+Add `producerIsolation: "private-directory"` to sibling staging when the
+producer can leave partial output before throwing. It receives an initially
+absent file path inside a private child workspace under the target parent, on
+the target filesystem. Directory cleanup ownership is captured before the
+callback. A callback exception triggers owned workspace cleanup, including
+partial output, subject to directory identity checks and I/O failures.
+After success, `Root.move` checks source aliases and moves the output to the
+ordinary sibling path; an escaping symlink can fail with `path-alias` here.
+Rejected output still inside the workspace follows its cleanup contract. Once
+output moves to the sibling path, the existing unadmitted-file retention and
+single-link regular-file admission, mode, file sync, and final rename rules apply.
+
+Exact bigint parent and workspace identities are rechecked before moving
+output to the sibling path to reject observed replacements. Cleanup uses the
+existing [`withTempFile` ownership contract](temp.md#withtempfile). A moved or replaced parent or workspace can
+leave original or replacement paths behind; the option does not promise
+cleanup through a retained directory after a rename. The existing Windows,
+native-off, and JavaScript guard limitations remain, with no additional
+permissions or durability guarantee. See the [producer-isolation contract](temp.md#sibling-temp-writes)
+for cleanup and pathname-race details. The option affects only `staging: "sibling"`;
+with `staging: "workspace"`, it is redundant and harmless because the producer
+already uses a private workspace. Omitting it leaves both staging defaults
+unchanged.
+
 ## Why not pass the final path to the library?
 
 If a target parent can be swapped after validation, handing an external library

package/docs/path-case.md

@@ -0,0 +1,64 @@
+# Path case probing
+
+`probePathCaseInsensitiveSync()` observes whether a path's lookup location
+folds ASCII case. It returns `true`, `false`, or `undefined` when the observation
+cannot establish an answer. It does not infer a filesystem property from the
+operating system or cache its result.
+
+```ts
+import { probePathCaseInsensitiveSync } from "@openclaw/fs-safe/advanced";
+
+const insensitive = probePathCaseInsensitiveSync("/srv/data/future.json", {
+  allowTemporaryProbe: false,
+});
+if (insensitive === undefined) {
+  // The application decides how to handle an unavailable observation.
+}
+```
+
+## Lookup location
+
+The input is resolved with Node's `path.resolve()`. Existing targets, including
+directories and final symlinks, are first compared by basename in their parent.
+The probe does not follow a final symlink to decide the target's case behavior.
+Parent aliases are followed. For a missing path, it walks to the nearest existing
+directory whose metadata can be read, without creating the missing directories.
+An unreadable directory listing returns `undefined`.
+
+The probe checks existing directory entries before considering a temporary
+file. Separately listed case variants count as distinct entries even when they
+are hardlinks to the same inode. Identity comparisons retain bigint precision;
+unknown Windows identities do not count as matches. The original entry is
+rechecked after looking up its case variant, so its disappearance or replacement
+invalidates the observation. A detected directory replacement also returns
+`undefined`.
+
+## Temporary probes and cleanup
+
+`allowTemporaryProbe` defaults to `true`. When existing entries give no answer,
+the helper exclusively creates one empty `.fs-safe-case-probe-*` file in the
+selected directory at mode `0o600`. It uses the existing temporary-file owner
+to retain the descriptor and exact cleanup identity. Successful ordinary
+completion removes the probe and closes the descriptor.
+
+Set `allowTemporaryProbe: false` for strictly read-only observation. In that
+mode an empty directory, or one with no useful ASCII-case names, returns
+`undefined` without creating a temporary file. Temporary probing can change
+directory timestamps and trigger filesystem watchers even when cleanup succeeds.
+
+Operational failures, unverified identities, changed entries, and cleanup
+failures return `undefined`. A substituted or hardlinked temporary entry is
+preserved. When cleanup fails operationally, the existing owner retains its
+identity-bound process-exit retry. A creation whose identity cannot be obtained
+may leave an empty file; the helper never guesses cleanup ownership. Therefore
+`undefined` does not promise that no temporary artifact remains.
+
+## Limits
+
+This is a local ASCII-case observation, not a Unicode-normalization test,
+filesystem-wide guarantee, lock, or authorization receipt. Directory enumeration
+and metadata lookups are separate operations. Concurrent changes can invalidate
+or immediately stale a result, and the final identity check and unlink are not
+an atomic conditional deletion. Use temporary probing only where creating a
+temporary file is permitted. The caller retains any admission, serialization,
+fallback, or later mutation policy.

package/docs/path-scope.md

@@ -1,6 +1,6 @@
 # pathScope()
 
-`pathScope()` is an advanced helper with the same boundary semantics as `root()`, but it operates on **absolute paths** the caller already trusts and returns plain `{ ok, path }` results instead of throwing. Use it when you want the boundary check up front before handing an absolute path to another library.
+`pathScope()` prepares absolute paths and returns plain `{ ok, path }` results. `resolve()` and `resolveAll()` check lexical containment without touching the filesystem; `existing()`, `files()`, and `writable()` add the filesystem checks described below. Use it to prepare paths before handing them to another library, whose file-opening and mutation behavior still applies.
 
 ```ts
 import { pathScope } from "@openclaw/fs-safe/advanced";

package/docs/permissions.md

@@ -71,8 +71,17 @@ resolveWindowsUserPrincipal(env);
 The fallback Windows inspector reads the owner and DACL together through one
 built-in Windows PowerShell/.NET query. It returns canonical SIDs and numeric
 access masks, so Unicode paths and account names do not pass through lossy
-console display text. `inspectWindowsAcl()` uses the same query and returns
-canonical SIDs in its `principal` fields, with normalized rights tokens.
+console display text. `inspectWindowsAcl()` uses native descriptor facts for
+complete local ACLs with nonzero inherited ACEs (or empty/null DACLs) when the
+optional Windows binding is available. It applies
+the same classifier to native facts and the fallback query, returning canonical
+SIDs in its `principal` fields with normalized rights tokens. Explicit `env` or
+`exec` options retain the query path. Disabled or unavailable native helpers,
+remote or incomplete descriptors, leaf symbolic links, and native query errors
+use the fallback. Explicit ACEs and zero-mask entries also retain the query so
+.NET continues to own its ACE ordering and normalization.
+Structured ACLs containing only canonical SIDs are classified directly from
+the current-user SID without requiring a separate account-name lookup.
 The advanced options retain `currentUserSid` as an explicit classification
 override and `principalTranslationFailed: true` as an immediate unverified
 result. The optional `principalSids` translation cache is still accepted but

package/docs/public-api.md

@@ -38,6 +38,33 @@ The advanced root-file primitive exports `OpenRootFileParams`,
 `RootFileOpenFailureReason`. These are composition types for callers building
 their own pinned-open flow, not substitutes for the higher-level `Root` verbs.
 
+`copyFileHandle` and `CopyFileHandleOptions` transfer bytes between already-open
+regular files without taking over their cursors, lifetime, or publication.
+See [borrowed-handle transfers](copy.md#borrowed-filehandle-transfers).
+
+`readDirectoryIdentity`, `assertDirectoryIdentitySync`, and `DirectoryIdentity`
+provide exact directory observations without owning a descriptor or a mutation.
+The assertion accepts an observed path and optional expected canonical path;
+see [directory identity](directory-identity.md).
+
+`overwriteFileHandle` and `OverwriteFileHandleOptions` provide in-place byte
+replacement through a borrowed regular-file handle. Its once-only `beforeWrite`
+callback admits the complete write and any required best-effort rollback after
+prefix preparation. See [in-place writes](in-place-write.md).
+
+`probePathCaseInsensitiveSync` and `ProbePathCaseOptions` are advanced exports
+for local ASCII-case observations. An unavailable answer remains `undefined`;
+the caller selects any fallback. See [path case probing](path-case.md).
+
+## Guest source
+
+`@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,
+`GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE`,
+`GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE`, and
+`GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON`. These are source and protocol
+constants; the caller launches the Python guest and owns authorization and
+transport lifetime. See the [guest protocol](guest.md).
+
 ## `json` and `store`
 
 Standalone structured reads use `ReadJsonOptions`, `ReadRootJsonSyncOptions`,
@@ -89,8 +116,10 @@ The durability surface also exports the synchronous strict
 `EnsureDurableDirectoryOptions`, `PublishFileExclusiveResult`,
 `PublishFileExclusiveStrategy`, `PublishFileExclusiveCleanup`,
 `PublishFileExclusiveFailurePhase`,
-`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`, and
-`Sha256FileResult`.
+`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`,
+`Sha256FileSyncInput`, `Sha256FileOptions`, and `Sha256FileResult`.
+`sha256FileSync()` provides synchronous pathname or borrowed-descriptor hashing
+with the same byte-budget and digest-result contracts as `sha256File()`.
 
 ## Archives
 

package/docs/root.md

@@ -113,13 +113,21 @@ fs.append(rel, data, options?)           // append text/buffer; syncs before clo
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
 fs.move(from, to, options?)              // rename within the root; defaults to no clobber
-fs.remove(rel, options?)                 // unlink file or rmdir empty directory
+fs.remove(rel, options?)                 // unlink file, rmdir, or bounded recursive removal
 fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
 fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 ```
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
+`create` also accepts `AsyncIterable<Uint8Array>` with `RootCreateStreamOptions`:
+the same path, authority, mode, and durability options, plus `maxBytes` and
+`signal`, without `encoding` or `renameIdentity`. It consumes one chunk at a
+time and publishes the completed file exclusively. The byte cap inherits an
+explicit `Root.defaults.maxBytes`; without either cap, consumption is unlimited.
+See [streamed creation](writing.md#streamed-creation) for cancellation,
+cleanup, and filesystem requirements.
+
 `append` accepts `prependNewlineIfNeeded: true` to separate text from existing
 content when neither side supplies a newline. String data uses its `encoding`
 for the newline check, including UTF-16LE; Buffer data uses a single LF byte.
@@ -213,6 +221,18 @@ basename first.
 
 `openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Use it for streaming output. Prefer `await using` for cleanup.
 
+`remove` leaves non-empty directories unchanged unless `recursive: true` is
+provided. Recursive removal defaults to streaming entries in filesystem order;
+`order: "sorted"` processes each directory's children lexicographically. The
+`maxEntries` (100,000 by default) and `maxDepth` (64 by default) budgets accept
+explicit `Infinity` when the caller needs unlimited traversal. It never
+follows discovered symlinks; an explicit `mutationSymlinks` policy rejects them,
+while the omitted policy unlinks them. `force: true` ignores missing targets,
+and `signal` stops further work after admitted I/O and resource cleanup settle.
+Removal is not transactional: a budget, cancellation, policy, or identity
+failure can leave a partially removed tree. See [removal](writing.md)
+for the full counting and failure contract.
+
 ### Live mutation authority
 
 All mutation methods accept `assertBeforeMutation?: () => void`. Use it when a
@@ -273,14 +293,22 @@ fs.exists(rel)                   // boolean
 fs.stat(rel)                     // PathStat
 fs.list(rel)                     // string[]
 fs.list(rel, { withFileTypes })  // DirEntry[]
+fs.entries(rel, options?)        // nonrecursive AsyncIterable<DirEntry>, including symlinks
 fs.resolve(rel)                  // absolute path inside the root, after canonicalization
 ```
 
 These do not pin a later operation. They are safe to expose to UIs and decision points; for the actual read or write, use the verb methods so the operation pins identity at the point of use.
 
+`entries()` streams immediate children in filesystem order by default. It
+supports cancellation, a physical-entry limit that throws on overflow, and
+bounded sorted-name collection. It reports child symlinks without following
+them; its `symlinks` option applies only to the selected directory path.
+See [Directory entries](entries.md) for ordering, identity, and partial-result
+semantics.
+
 `resolve()` is the exception to the existing-object rule: because it selects a
 location for later use, it rejects a leading drive-relative spelling. Reads,
-`stat`, `exists`, `list`, `walk`, `remove`, and the source argument of `move`
+`stat`, `exists`, `list`, `entries`, `walk`, `remove`, and the source argument of `move`
 accept an existing POSIX filename such as `c:notes.txt`. For `move`, only the
 new destination name is subject to the portable guard.
 

package/docs/secure-file.md

@@ -21,6 +21,7 @@ The helper:
 - rejects every non-regular preview and, by default, symlink paths
 - opens POSIX paths no-follow and nonblocking before reading, then verifies the opened fd still matches the path and realpath; a FIFO swap cannot block before `timeoutMs` owns the byte read
 - optionally requires the real path to live under one of `trust.trustedDirs`
+- rejects hardlink aliases using descriptor, pathname, and realpath link counts, then rechecks the descriptor after reading before returning bytes
 - rejects hard-to-verify or unsafe permissions unless `permissions.allowInsecure` is set
 - rejects files owned by another POSIX uid
 - enforces `maxBytes` before and after reading
@@ -73,6 +74,7 @@ type SecureFileReadOptions = {
 | `not-found` | The path could not be stat'd before open. |
 | `not-file` | The opened target is not a regular file. |
 | `symlink` | The path is a symlink and `trust.allowSymlink` is false. |
+| `hardlink` | The descriptor, pathname, or realpath has more than one link. |
 | `path-mismatch` | The path or realpath changed between open and verification, or filesystem identity could not be verified after bounded re-inspection. |
 | `outside-workspace` | `realPath` is outside `trust.trustedDirs`. |
 | `permission-unverified` | Required mode/ACL checks could not be completed. |