@openclaw/feishu 2026.9.8 → 2026.10.1-beta.1

package/node_modules/@openclaw/fs-safe/docs/security-model.md

@@ -49,6 +49,24 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 Every path is resolved against the canonicalized real path of the root, then checked at that boundary. On Windows, an exact-case structural Root prefix stays on the lexical fast path; a prefix accepted only by case folding must have the Root's exact directory identity and is rebased onto the trusted Root spelling before use. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
 
+On Windows, Root, root-file readers, `pathScope`, `isPathInside`, secret-file
+writers, sibling-temp output, trash admission, and archive output preparation
+reject foreign share or device roots before filesystem access can contact an
+attacker-chosen host. Shares are compared by exact host and share name with
+ASCII-only case folding, so Unicode case folding (for example the Kelvin sign
+for `k`) cannot make another host look trusted. Namespaced drive roots keep
+their existing handling, and explicitly selected shares, such as a Root,
+allowed trash root, or destination on `\\server\share`, remain supported.
+`\\?\` and `\\.\` spellings under `GLOBALROOT`/`Global`, or whose components
+Windows would rewrite (empty or trailing-dot/space authority components, or
+dot segments climbing above the drive, share, or device), are foreign unless
+spelled exactly under the trusted boundary, because their target cannot be
+identified from the spelling.
+
+An absolute path on a different share or device is rejected even when a
+filesystem alias would resolve it back inside the boundary. Pass a path
+relative to the boundary, or spell it on the boundary's own share.
+
 Guarded pathname APIs reject Windows `:` namespace aliases before normalization
 or filesystem access. The only colon admitted in a Windows filesystem path is
 the rooted ASCII drive designator (including extended-drive syntax); relative
@@ -73,6 +91,19 @@ publication, and cleanup. File writers preserve the raw suffix. Root-relative
 APIs and caller-constructed relative directory receipts continue to reject
 drive designators.
 
+### Exclusive creation on Windows
+
+Windows Node exclusive creation can follow a dangling file symlink before an
+opened-descriptor check can reject it. Fallback creators therefore inspect the
+final leaf before opening it, including create-only Root writes, standalone
+creators, exclusive copy publication, lock records, and internal staging files. This preserves an unchanged
+link and its missing target, including a target outside the intended directory.
+Random staging names and freshly created workspaces reduce the opportunity to
+preplace such a link, but are not a replacement for this check. The preflight is
+best-effort: a concurrent replacement between inspection and open can still
+redirect a pathname operation in native `auto`/`off` mode. Use the documented
+native `require` creation paths and OS isolation when hostile concurrency is in scope.
+
 ### Symlinks (read side)
 
 `open()` and `read()` use `fs.open` with `O_NOFOLLOW` on POSIX where available. The library then `fstat`s the open fd and `realpath`s the original input, asserting the two refer to the same inode. A symlink swap that happens between resolve and open will fail at the identity check rather than silently following the new target.
@@ -149,7 +180,24 @@ final component again after awaited staging and parent fences, immediately befor
 the rename or exclusive open. These are best-effort symlink checks, not an atomic
 expected-entry/CAS replacement: a concurrent process can still replace the final
 entry between its check and rename. Existing parent containment guarantees remain
-as described below. Omitting `mutationSymlinks` preserves existing mutation behavior.
+as described below. Omitting `mutationSymlinks` preserves each implementation's
+existing mutation behavior; it does not currently provide uniform Windows link
+handling.
+
+For Windows buffered replacement `write()` and `writeJson()` calls (`overwrite`
+omitted or `true`), the native pinned path rejects
+a final file symlink with `path-alias`. The legacy JavaScript path can follow an
+unchanged contained final link, keep the link itself, and replace the admitted
+target. Its configured mutation policy reauthorizes the original target before
+staging and publication, and its file/parent identity checks remain in force.
+Likewise, native Windows parent admission refuses junction/reparse traversal
+and can report `invalid-path`, while the legacy path can write through an
+admitted contained parent-junction target.
+
+The legacy writer is selected by native `off`, missing-binding `auto`, or
+`renameIdentity: "verify-content-with-lock"`. Callers requiring the same link
+rejection across implementations must set `mutationSymlinks: "reject"`
+explicitly. See [Windows link modes](writing.md#windows-link-modes).
 
 The JavaScript fallback used by `off`, by `auto` when no binding loads, and by
 the explicit `renameIdentity: "verify-content-with-lock"` compatibility policy
@@ -158,7 +206,9 @@ It asserts directory identity around a pathname mutation and detects many
 swaps, but detection occurs after the kernel may already have followed a new
 parent symlink. A same-privilege peer with write access to the parent can
 therefore cause an out-of-root side effect before the operation throws. Use
-native `require` mode when concurrent hostile mutation is in scope.
+native `require` mode to refuse implicit pathname mutation fallbacks, then check
+the operation capabilities below. Loading an addon alone does not establish
+confinement for every method.
 
 The separate [retained-directory staging lifecycle](staged-file.md) keeps abort
 cleanup anchored to the original directory after a parent or ancestor move.
@@ -233,7 +283,7 @@ The library does not modify or constrain the global Node.js `fs` namespace, and
 | Mechanism | Reported containment | Boundary |
 |---|---|---|
 | Linux native with `openat2` | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
-| Linux native without `openat2` | `best-effort` | A no-follow `openat` component walk retains each parent and verifies exact identity associations before and after the final open; all symlink components are rejected. |
+| Linux native without `openat2` | `best-effort` | A no-follow `openat` component walk retains each parent, follows admitted in-root relative symlinks, and rechecks exact directory/link identities and link targets before and after the final open. |
 | macOS native | `best-effort` | macOS 15.4 and newer use `O_RESOLVE_BENEATH` first; older kernels use the guarded `openat(O_NOFOLLOW)` component walk. Both verify the opened descriptor with `F_GETPATH`. |
 | Windows native | `best-effort` | Handle-relative `NtCreateFile` rejects reparse points, but this package does not claim a Linux-style atomic beneath guarantee. |
 | JavaScript fallback | `best-effort` | Canonical checks, no-follow opens where Node exposes them, and post-open identity checks form a check-then-use sequence. |
@@ -244,6 +294,68 @@ The Linux fallback's identity checks are also detection-based: a directory can b
 
 The public `OpenResult`, `ReadResult`, and `WritableOpenResult` expose `containment`. Those root APIs currently report `best-effort`; direct native `openBeneath()` reports the platform value above. No-replace publication uses `renameat2(RENAME_NOREPLACE)` on Linux, `renameatx_np(RENAME_EXCL)` on macOS, and `FileRenameInfoEx` with replacement disabled on Windows, but those separate mutation semantics do not upgrade an open result's containment label.
 
+### Native Root mutation capabilities
+
+For removal, recursive removal, mkdir, overwrite move, and writable-open creation,
+`require` selects the hardened native capability or rejects with
+`helper-unavailable`; it does not silently perform the corresponding Node
+pathname mutation. Default `auto` keeps its previous best-effort paths for these
+operations, even with a native addon loaded. **`auto` does not confine these
+operations under hostile concurrency.** The matrix below describes `require`.
+The existing native publication paths for `write`, `create`, `writeJson`, and
+`copyIn` are unchanged, and no-clobber move still requires native support in every mode.
+
+| Root operation | Linux with `openat2` | Linux guarded fallback | macOS native | Windows native |
+|---|---|---|---|---|
+| `write`, `create`, `writeJson`, `copyIn` publication | Retained parent descriptors | Retained parents; best-effort admission | Retained parents; best-effort admission | Handle-relative publication; best-effort admission |
+| `remove` file, symlink, or empty directory | Identity check and `unlinkat` at retained parent | Same unlink; best-effort parent admission | Same unlink; best-effort parent admission | Handle-relative open and identity-checked `FileDispositionInfoEx`; best-effort parent admission |
+| Recursive `remove` | Descriptor-relative enumeration and deletion; `RESOLVE_NO_XDEV` on descent | `require` rejects; `auto` uses JavaScript | Descriptor-relative traversal with mount-identity checks; best-effort admission | `require` rejects; `auto` uses JavaScript |
+| `mkdir` | `mkdirat` and retained child identity checks | Same creation; best-effort admission | Same creation plus guarded admission | Handle-relative directory creation, including the existing protected private creator; best-effort admission |
+| `move` with overwrite | Retained parents, source identity check, `renameat` | Same rename; best-effort admission | Retained parents and rename; best-effort admission | Source handle identity check and handle-relative rename; best-effort admission |
+| `append` / `openWritable` creating a file | Beneath exclusive open, no-follow final component, identity-checked FileHandle handoff | Same creation through guarded native open; best-effort admission | Guarded native creation and identity-checked FileHandle handoff; best-effort admission | Handle-relative exclusive creation, identity-checked FileHandle handoff and handle-bound cleanup; best-effort admission |
+
+These guarantees have a per-call cost in `require`: removal pays for retained
+parent admission and entry checks, recursive removal additionally fences each
+visited directory, mkdir admits and verifies each created parent, overwrite move
+retains both parents, and open-create verifies the FileHandle handoff. Adjacent
+native steps are combined where no authorization callback must intervene, but
+the identity and policy fences remain. `auto` keeps its previous operation paths
+and avoids this added cost.
+
+On Linux, `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` admits the parent
+under the Root atomically. Later mutations use that retained parent, so replacing
+its pathname with a symlink cannot redirect the syscall to the link's target.
+Recursive removal never follows an enumerated symlink; it unlinks the link itself
+unless an explicit mutation policy rejects it. The fallback Linux walk rejects
+symlinks and keeps its `best-effort` label. macOS uses the existing guarded
+`O_RESOLVE_BENEATH`/`F_GETPATH` admission and also remains `best-effort`.
+
+Directory pinning is not an atomic check of the entire namespace at mutation
+time. A peer can move an admitted directory, and POSIX has no expected-inode
+conditional unlink or rename: a final name can change after its identity check.
+Post-operation rejection does not roll back a completed mutation. Policy and
+identity checks remain defense in depth; OS isolation is needed for stronger
+same-privilege namespace or authorization guarantees.
+
+Writable-open creation retains a native descriptor while reopening the same
+inode as a Node `FileHandle`, without create or truncate flags. If the requested
+mode or umask cannot be preserved through initial creation and that handoff,
+`require` rejects rather than widening permissions. `auto` keeps its existing
+JavaScript creation path. The native
+creation syscall receives the requested mode, preserving inherited ACLs.
+If the resulting kernel permissions prevent handoff, the call fails closed and
+attempts identity-bound cleanup of its empty created file; it never broadens
+those permissions with `chmod`.
+Existing-file writable opens, reads, advisory methods, and caller operations on
+returned handles retain their existing `best-effort` contracts. Explicit
+`renameIdentity: "verify-content-with-lock"` also retains its documented
+JavaScript compatibility path, including in `require` mode.
+
+Compatibility: an older or incomplete addon, unavailable mount-bounded descent,
+or another missing operation capability now causes `helper-unavailable` in
+`require`, including cases that previously fell through to JavaScript. The
+public result types and containment labels are unchanged.
+
 ## Limitations to keep in mind
 
 | Limitation | What it means |

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

@@ -30,7 +30,7 @@ import {
 | `fileStoreSync()` | Synchronous variant of `fileStore()` for places that genuinely cannot await. |
 | [`jsonStore()`](json-store.md) | A single keyed JSON state file with explicit fallback, atomic writes, and optional sidecar locking around read-modify-write updates. |
 | Durable JSON queue helpers | Append/load/ack JSON entry files using atomic writes and delivered markers. |
-| [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for credentials, tokens, and per-agent state at `0600` files under `0700` directories. |
+| [Private file-store mode](file-store.md#private-mode) | `fileStore({ private: true })` for credentials, tokens, and per-agent state at `0600` files under `0700` directories. |
 
 `fileStore().json("rel.json")` and `jsonStore({ filePath })` are intentionally separate primitives. Use `fileStore().json(...)` when JSON state lives alongside other files in the same managed directory; use `jsonStore({ filePath })` when you have one trusted path, resolved to an absolute path at construction, and want the keyed JSON shape directly.
 
@@ -124,6 +124,6 @@ rejects non-files, symlinks, hardlinks, and entries over the byte limit.
 
 - [`fileStore`](file-store.md) — full API for the multi-file store.
 - [`jsonStore`](json-store.md) — single-file JSON store with locking.
-- [Private file-store mode](private-file-store.md) — credential-shaped variant.
+- [Private file-store mode](file-store.md#private-mode) — credential-shaped variant.
 - [JSON files](json.md) — lower-level `readJson` / `writeJson` helpers.
 - [Atomic writes](atomic.md) — what `fileStore` and `jsonStore` use under the hood.

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

@@ -54,55 +54,31 @@ unavailable namespace evidence leaves admission unchanged.
 The first admitted unmapped ancestor emits `FS_SAFE_UNMAPPED_TEMP_ANCESTOR`
 through Node's warning event. The warning contains no caller paths.
 
-For an already existing canonical root, discovery retains only its immutable
-exact identity. Cleanup-parent retention is provisional: after any native
-capability probe, creation captures and validates the complete ancestry,
-re-observes the root against discovery, and associates the retained parent
-descriptor. Async creation and sync creation outside the Linux/macOS
-direct-mode case dispatch `mkdtemp` immediately after that synchronous boundary
-without another yield or native probe. Existing aliases and missing-component
-roots keep the guarded admission route.
-
-On Linux and macOS, synchronous creation can instead use an exclusive six-character
-random child name when an explicit requested mode other than `0o700` has owner
-`rwx`, no special bits, and no group/world write bits. The requested mode is
-passed directly to `mkdir` and the observed complete permission bits, rather
-than the requested bits, are authoritative. Umask, inherited ACL state, or
-inherited special bits can make that observation differ, in which case creation
-corrects the mode through the retained descriptor. This mode-based optimization
-does not claim that Linux and macOS have identical syscall or ACL behavior, and
-POSIX mode bits do not establish ACL privacy. Creation makes at most 64 attempts;
-after a name collision, each retry generates its candidate first, replays the
-already admitted immutable ancestry and descriptor receipts, and then
-immediately attempts exclusive creation. A colliding entry is never inspected,
-adopted, corrected, registered, or deleted. The default `0o700`, async creation, and
-other sync modes retain the `mkdtemp` path. That path requests initial mode
-`0o700`; a result different from `dirMode` is initialized through the same
-descriptor-bound correction.
-
-The direct sync path opens the new child without following its final component
-and captures one exact descriptor observation after the parent replay. The new
-child's exact identity, type, owner, private bits, and complete `0o7777` mode are
-checked before mode initialization. When its creation mode already
-matches `dirMode` (including the default `0o700`), creation avoids an extra mode
-descriptor and chmod. If the observed creation mode differs from `dirMode`, the
-immediate synchronous correction consumes that one-shot observation, checks the
-fresh child name, replays the parent, and applies correction through the retained
-descriptor. Later admission always performs fresh descriptor and name checks.
-Permission failures propagate. POSIX `dirMode`
-must not grant group/world write access; it only controls the new workspace,
-not existing supplied directories. After the
-first exact child observation, final adoption retains a no-follow child
-descriptor, rechecks complete ancestry and retained cleanup-parent authority,
-and then validates the original child's descriptor and current name for exact
-identity, owner, private bits, and requested mode before cleanup is registered.
-Linux and macOS may replay exact identities through round-trip-safe nonnegative
-numeric `dev`/`ino` projections. Initial receipts that cannot be represented
-exactly stay on the BigInt path; a malformed or mismatched numeric replay fails
-closed without an exact retry.
-Parent or child replacements observed during creation reject before cleanup
-ownership is registered. Unverified artifacts are left in place for
-caller-directed recovery.
+Existing canonical-root discovery retains immutable exact identity; parent retention is provisional until,
+after any native probe, creation validates complete ancestry, rechecks the root, and binds the parent descriptor.
+Existing aliases and missing-component roots keep guarded admission. Async creation, default `0o700`, and
+ineligible sync modes dispatch `mkdtemp` (initial mode `0o700`) immediately after admission, without another yield or probe.
+
+Linux/macOS sync creation can use exclusive `mkdir` with a six-character random suffix when an explicit
+mode other than `0o700` grants owner `rwx`, no special bits, and no group/world write. Each of at most
+64 attempts generates a candidate, replays admitted ancestry and descriptor receipts, then creates immediately.
+Colliding entries are never inspected, adopted, corrected, registered, or deleted. Observed complete mode bits
+are authoritative: umask, inherited ACLs, or special bits can change the requested mode. POSIX modes do not
+establish ACL privacy, and this optimization does not promise identical Linux/macOS syscalls or ACL behavior.
+
+The direct sync path opens the child without following its final component and captures one exact descriptor
+observation after parent replay. Creation checks identity, type, owner, private bits, and complete `0o7777` mode.
+Matching `dirMode` avoids an extra mode descriptor and chmod; mismatches use descriptor-bound correction.
+Immediate sync correction consumes the initial observation, checks the fresh child name, and replays the parent;
+later admission uses fresh descriptor/name checks. Permission failures propagate. POSIX `dirMode` cannot grant
+group/world write and affects only the new workspace, never existing supplied directories.
+
+Before registering cleanup, final adoption retains a no-follow child descriptor, rechecks complete ancestry
+and retained cleanup-parent authority, then verifies the original child's descriptor and current name for exact
+identity, owner, private bits, and requested mode. Linux/macOS replay retained identities through round-trip-safe
+nonnegative numeric `dev`/`ino` projections when exact (otherwise BigInt); malformed or mismatched numeric
+observations fail closed without an exact retry. Observed parent/child replacements reject before ownership
+registration; unverifiable artifacts remain for caller-directed recovery.
 
 On Windows, POSIX mode/UID metadata does not establish ACL privacy, and these
 factories neither claim nor initialize a POSIX `dirMode`; every requested value
@@ -247,9 +223,7 @@ name before quarantine returns `"identity-mismatch"` when the parent is stable;
 an ambiguous parent returns `"indeterminate"`. After successful removal,
 repeated cleanup returns `"missing"` without touching a recreated public name.
 Other statuses remain stable. Compatible recursive-removal failures propagate
-the exact thrown value, including `undefined`, `null`, `false`, positive or
-negative numeric zero, bigint zero, an empty string, and `NaN`; they are never
-inferred from value identity or truthiness. Uncertain quarantine and
+the original thrown value, including falsy values. Uncertain quarantine and
 retained-parent checks instead return
 `"indeterminate"`. After a propagated removal failure, later cleanup returns
 `"indeterminate"` without retrying. Disposal and scoped helpers ignore returned
@@ -293,16 +267,8 @@ The callback receives the same workspace shape as `tempWorkspace()`. Cleanup is
 
 ### Manual lifetime
 
-Lower-level. You manage the lifetime:
-
-```ts
-const workspace = await tempWorkspace({ rootDir: "/tmp/my-app", prefix: "scan-" });
-try {
-  // …work in workspace.dir…
-} finally {
-  await workspace.cleanup();
-}
-```
+Manage the lifetime with `try/finally` and inspect the cleanup result, as in the
+[receipt-inspecting example above](#tempworkspace).
 
 ### Sync variants
 
@@ -634,7 +600,6 @@ type ResolveSecureTempRootOptions = {
   getuid?: () => number | undefined;
   tmpdir?: () => string;
   accessSync?: typeof import("node:fs").accessSync;
-  chmodSync?: typeof import("node:fs").chmodSync; // deprecated, never read or called
   descriptor?: SecureTempRootDescriptorAdapter; // complete bundle; see below
   lstatSync?: (path: string) => {
     isDirectory(): boolean;
@@ -710,8 +675,7 @@ flags make repair/finalization unavailable. Injecting `lstatSync`, `accessSync`,
 or `mkdirSync` disables the default host descriptor bundle. Injected observations
 also require an explicit `mkdirSync` for creation; supplying a descriptor bundle
 likewise never implicitly authorizes host mkdir. A custom mkdir requires the
-complete descriptor bundle for POSIX finalization. The deprecated `chmodSync`
-option is inert and alone does not disable normal host behavior.
+complete descriptor bundle for POSIX finalization.
 
 These checks bind chmod to the admitted object and reject observed replacements;
 the returned path is not a retained capability. Pathname access and identity

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

@@ -1,5 +1,10 @@
 # Testing
 
+The [seeded differential harness](https://github.com/openclaw/fs-safe/blob/main/scripts/differential-root.md) compares
+isolated Node/Bun, native/fallback and sync/async public API runs, retaining
+replayable return/error/tree receipts and bounded reduced repros. Its small
+`node scripts/differential-root.mjs --ci` corpus runs in native CI lanes.
+
 ## Coverage gates
 
 The coverage workflow measures `src/**/*.ts` with V8 on Linux, macOS, and
@@ -23,6 +28,23 @@ Percentages complement behavioral gates: mutation-policy proof, nightly watch
 stress, and platform lanes are equally important. High coverage cannot establish
 root confinement, race safety, event delivery, or bounded resource retirement.
 
+## Hosted mutation-policy proof
+
+The [hosted workflow](https://github.com/openclaw/fs-safe/blob/main/.github/workflows/mutation-policy-proof.yml)
+builds the event-head package and host addon on Node 24 Linux, macOS, and Windows.
+The [harness](https://github.com/openclaw/fs-safe/blob/main/scripts/mutation-policy-proof.mjs)
+runs isolated temporary fixtures and binds sources, built modules, and the addon
+to the tested revision. Its [receipt contract](https://github.com/openclaw/fs-safe/blob/main/test/mutation-policy-proof-contract.test.ts)
+and [case contract](https://github.com/openclaw/fs-safe/blob/main/test/mutation-policy-proof-cases-contract.test.ts)
+define the executable inventory and bounds.
+
+Receipts describe representative observations: final listings and sentinels
+neither count native syscalls nor exclude transient effects. Windows compatibility
+payload writes remain JavaScript even when native-required sidecar publication
+uses `Root.create`. Hosted cases complement internal interleaving tests; they
+are neither exhaustive race proof nor performance clearance. Inspect exact
+hosted artifacts before relying on a receipt's claims.
+
 ## Watch stress campaign
 
 Build from the exact revision being qualified with `pnpm install --frozen-lockfile`,
@@ -149,20 +171,6 @@ requires the same openat2/NO_XDEV primitive and runs in the ordinary Linux
 lanes. Bun's full compatibility
 suite remains in the normal native lanes, because it includes bounded cleanup.
 
-`@openclaw/fs-safe/test-hooks` exposes test-only injection points. Registration
-is allowed only when `process.env.NODE_ENV === "test"` or
-`process.env.VITEST === "true"`; registering a non-empty hook set elsewhere
-throws. Production code must not import this subpath.
-
-```ts
-import {
-  __setFsSafeTestHooksForTest,
-  type FsSafeTestHooks,
-} from "@openclaw/fs-safe/test-hooks";
-```
-
-The double-underscore prefix is a deliberate "hands off" signal: production code should never import this module. ESLint or your equivalent linter should flag it.
-
 ## When to reach for hooks
 
 - Reproduce a TOCTOU race deterministically: simulate a symlink swap between resolve and open, or between write and rename.
@@ -173,30 +181,71 @@ If you don't need to inject a race, you don't need hooks — most tests should d
 
 ## Hooks API
 
+`@openclaw/fs-safe/test-hooks` exposes injection points for downstream tests,
+not a supported runtime API. Production code must not import it; enforce that
+with your linter. New optional fields may appear between minor versions.
+
 ```ts
-type FsSafeTestHooks = {
-  afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
-  beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
-  afterOpen?: (filePath: string, handle: import("node:fs/promises").FileHandle) => Promise<void> | void;
-  afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
-  beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
-  // Additional archive, store, root-fallback, temp, and trash race hooks are
-  // documented on the focused Test hooks reference page.
-};
+import {
+  getFsSafeTestHooks,
+  __setFsSafeTestHooksForTest,
+  type FsSafeTestHooks,
+} from "@openclaw/fs-safe/test-hooks";
+```
 
+```ts
 function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;
 function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
 ```
 
-Hooks are called at well-defined points in the library's hot paths:
-
-- **`afterPreOpenLstat`** — runs after the pre-open `lstat`. A common use is to swap the path's target via `fs.symlink`/`fs.unlink` to drive a TOCTOU race.
-- **`beforeOpen`** — runs before `fs.open` with the exact flags the root read path will use.
-- **`afterOpen`** — runs after the file handle is opened. Useful to wrap handle methods or inject a size race before a stream is consumed.
-- **`afterPublishTargetCreated`** — runs after exclusive publication created a target but before its final fences.
-- **`beforePublishDirectorySync`** — runs after target verification and immediately before strict parent sync; useful for exercising `onSyncFailure`.
-
-`__setFsSafeTestHooksForTest(undefined)` clears all hooks. Always clean up between tests.
+Registering any truthy hook set (including `{}`) requires
+`process.env.NODE_ENV === "test"` or `process.env.VITEST === "true"`; otherwise
+the setter throws. Clearing with `undefined` is allowed in any environment.
+The getter returns the registered set, or `undefined` when none is registered;
+changing the environment does not erase registered hooks.
+
+All fields are optional. Callbacks return `Promise<void> | void` and are awaited
+unless marked **sync**, which requires `void` and must not return a promise.
+Path arguments are strings, `flags` is a number, `withFileTypes` is a boolean,
+and `handle` is a Node `FileHandle`. Publication `method` is `"hardlink"`,
+`"exclusive-copy"`, or `"rename-noreplace"`; `identity` carries `dev` and `ino`
+as numbers or bigints.
+
+| Hook | Callback arguments | Timing |
+|---|---|---|
+| `beforeWatchRegistration` | `path` | Before a scanned directory's registration step, including when its existing registration is reused. |
+| `afterWatchRegistration` | `path` | After that registration step, before recording a newly acquired registration. |
+| `afterWatchBackendOverflow` (**sync**) | `root, phase` (`"received"` or `"reconciled"`) | On an overflow hint, and after a noninitial reconciliation produces an overflow invalidation. |
+| `afterWatchBackendCreated` (**sync**) | `root, emit, nativeEvent?` | After creating/configuring the backend, before scanning. `emit(batch)` injects a native watch batch; `nativeEvent(path, flags)` injects a decoder event. |
+| `afterPreOpenLstat` | `filePath` | After pre-open `lstat`, before opening the file. |
+| `beforeOpen` | `filePath, flags` | Immediately before the guarded file open. |
+| `afterOpen` | `filePath, handle` | After open, before the post-open identity check. |
+| `afterOpenedPathIdentityCheck` | `filePath, handle` | A standalone local-file or absolute copy-source descriptor matches its pathname, before the generic opened-path resolver. Root reads use final admission hooks instead. |
+| `afterRootReadPathResolution` | `filePath` | After Root read path resolution, before local-file open admission. |
+| `beforeRootReadFinalFence` | `filePath, handle` | After descriptor identity and hardlink checks, before the final root/path/canonical-path/root admission fence. |
+| `afterRootReadFinalPathIdentityCheck` (**sync**) | `filePath, handle` | After the final pathname-to-descriptor comparison, before the second root check. |
+| `beforeArchiveOutputMutation` | `operation` (`"mkdir"` or `"chmod"`), `targetPath` | Before archive staging creates a directory or applies a mode. |
+| `beforeFileStorePruneDescend` | `dirPath` | Before file-store pruning descends into a directory. |
+| `beforeFileStoreSyncPrivateWrite` (**sync**) | `filePath` | Before a synchronous private-store write mutates its target. |
+| `beforeRootFallbackMutation` | `operation` (`"mkdir"`, `"move"`, or `"remove"`), `targetPath` | Before a guarded JavaScript Root fallback mutation. |
+| `beforePinnedWriteParentAdmission` | `targetPath` | After pinned-write policy preflight, before parent admission; also before refreshing retained JavaScript write authority and parent checks. |
+| `beforeRootStatObservation` | `targetPath` | After `Root.stat()` admits the target and parent, before collecting returned metadata. |
+| `beforeRootStatInitialObservation` | `targetPath` | After `Root.stat()` admits the parent, before its first target inspection. |
+| `beforeRootListObservation` | `directoryPath, withFileTypes` | After `Root.list()` admits the selected directory, before collecting names and optional metadata. |
+| `afterPinnedWriteFallbackRename` | `targetPath` | After fallback rename commits, before post-commit identity checks. |
+| `beforeSiblingTempWrite` | `tempPath` | Before the `writeViaSiblingTempPath` producer runs, with its selected output pathname still absent. |
+| `beforeSidecarLockSnapshotOpen` | `lockPath` | After sidecar inspection, before opening it for a bounded snapshot read. |
+| `beforeRegularFileAppendOpen` | `filePath` | After append preflight and the initial size-budget check, before async open. |
+| `beforeRegularFileAppendOpenSync` (**sync**) | `filePath` | The corresponding sync append point, before `openSync`. |
+| `beforeTempWorkspaceNativeRemoval` | `quarantinePath` | After workspace quarantine admission, immediately before native owned-tree removal. |
+| `beforeTempWorkspaceNativeRemovalSync` (**sync**) | `quarantinePath` | The corresponding sync native-removal point. |
+| `beforeTrashMove` (**sync**) | `targetPath, destPath` | Before trash handling moves the target. |
+| `afterPublishTargetCreated` | `method, targetPath, identity` | After exclusive publication creates the target, before final fences. |
+| `beforePublishDirectorySync` | `method, targetPath, identity` | After publication verifies the target, immediately before strict parent sync. |
+
+The watch `emit` callback accepts `{ hints, overflow, error? }`: `overflow` is
+boolean, `error` is a string, and each hint has string `directory` and `name`
+fields plus an `event` of `"rename"`, `"change"`, or `"children"`.
 
 ## Example: simulate a TOCTOU swap
 
@@ -263,18 +312,9 @@ it("runs without the native helper", async () => {
 
 Hooks set by `__setFsSafeTestHooksForTest` persist across tests until explicitly cleared. Always clear in `afterEach` (or your test framework's equivalent) — leaked hooks will silently change behavior in unrelated tests and cause maddening intermittent failures.
 
-```ts
-import { afterEach } from "vitest";
-import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
-
-afterEach(() => {
-  __setFsSafeTestHooksForTest(undefined);
-});
-```
-
-A global hook clear in your test setup file is a good safety net.
-
-See the [complete Test hooks reference](test-hooks.md) for every optional hook.
+Use `__setFsSafeTestHooksForTest(undefined)` as in the TOCTOU example above.
+A global hook clear in your test setup file is a good safety net; the
+[Hooks API](#hooks-api) lists every optional hook.
 
 ## Patterns for testing fs-safe-using code
 
@@ -343,20 +383,12 @@ workspace reads that bypass pinned file descriptors.
 
 The original soak rule rejected more than 64 MiB RSS growth after minute five.
 That outcome remains in `memory.legacyRss`, with its original limit and pass/fail
-value; it is no longer the soak pass criterion. Static guarded poll scans alone
-reproduced growth from 72 to 181 MiB RSS while collected heap stayed near 7–8 MiB:
-V8 expanded its almost-empty young generation to 128 MiB, with 103 MiB physically
-committed. A diagnostic run limiting that space ended at 85 MiB RSS with the
-same live heap. The normal harness keeps Node's default nursery sizing.
-
-The 60-minute qualification separates this capacity warm-up from the later RSS
-trend. The measured Linux event run had under 1 MiB collected-heap drift and a
-0.55 MiB/minute second-half RSS slope; its final ten-minute RSS range was 1.60 MiB.
-The 8 MiB live-memory allowance and 1 MiB/minute RSS slope leave measurement
-margin while rejecting retained growth and continued rapid RSS growth. The
-512 MiB peak ceiling is unchanged. Native allocation leaks need independent
-accounting/profiling too: the investigation found a much smaller cleanup-hook
-context leak even when registrations, pending sets, and TSFN counters retired.
+value; it is no longer the soak pass criterion. V8 capacity expansion and
+allocator retention can raise RSS while collected live memory stays flat.
+The normal harness keeps Node's default nursery sizing and separates warm-up
+from later RSS growth with the [current stress gates](#watch-stress-campaign).
+Native allocation leaks still need independent accounting/profiling, even when
+registrations, pending sets, and thread-safe function counters retire.
 
 Build the native addon and package from the same revision, then run each control
 in a fresh Node process on a disposable machine:

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

@@ -112,7 +112,6 @@ type RootDefaults = {
   maxBytes?: number;
   mkdir?: boolean; // default true for mutation methods
   mode?: number;
-  nonBlockingRead?: boolean;
   renameIdentity?: RenameIdentityPolicy;
   symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
   mutationSymlinks?: MutationSymlinkPolicy;
@@ -136,7 +135,7 @@ type RootOptions = {
 ```ts
 import type { CopyCloneMode, RootCopyPublicationReceipt } from "@openclaw/fs-safe";
 
-type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
+type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "symlinks">;
 type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity" | "mutationSymlinks"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
@@ -194,21 +193,9 @@ policy; omission preserves each mutation method's existing behavior.
 
 ## `FsSafeErrorCode` / `FsSafeErrorCategory`
 
-```ts
-type FsSafeErrorCode =
-  | "already-exists" | "denied-path" | "device-path" | "hardlink"
-  | "helper-failed"
-  | "helper-unavailable" | "insecure-permissions" | "invalid-path"
-  | "not-empty" | "not-file" | "not-found" | "not-owned"
-  | "not-removable" | "outside-workspace" | "path-alias"
-  | "path-mismatch" | "permission-unverified" | "read-failed" | "secret-exists"
-  | "store-reentrant-update" | "symlink"
-  | "timeout" | "too-large" | "unsupported-platform";
-```
-
-Closed union you switch on. See the [Errors](errors.md) reference for what each one means.
+`FsSafeErrorCode` is a closed union you switch on; the [code union](errors.md#code-union) lists every member and the [code reference](errors.md#code-reference) explains each one.
 
-`FsSafeError.category` is `"policy"` for unsafe input or target state rejected by a safety policy and `"operational"` for routine filesystem outcomes or environment/runtime failures. `not-found`, `not-empty`, `not-removable`, and `read-failed` are operational.
+`FsSafeError.category` is `"policy"` for unsafe input or target state rejected by a safety policy and `"operational"` for routine filesystem outcomes or environment/runtime failures. [Errors](errors.md#shape) lists the exact operational set.
 
 ## See also
 

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

@@ -51,7 +51,7 @@ Each entry's `path` is absolute and retains the normalized spelling of the
 supplied root, including followed directory aliases. Paths do not switch to
 the canonical symlink target during descent.
 
-`walkDirectory()` and `walkDirectorySync()` always return `failedDirs`; the property remains optional on the exported `WalkDirectoryResult` type so existing callers that manually construct the legacy result shape remain source-compatible. It lists every directory whose `realpath`/`readdir` threw, so its contents are absent from `entries`. `error` is the thrown value (a `NodeJS.ErrnoException` at runtime), so callers can distinguish a benign missing-directory race (`ENOENT`) from a real read failure (`EACCES`, `EIO`, `ESTALE`, …). The walk-root failure has an empty `relativePath` and `depth: 0`. Failures resolving a symlink's target kind are not reported here.
+`walkDirectory()` and `walkDirectorySync()` always return `failedDirs`; the property remains optional on the exported `WalkDirectoryResult` type so existing callers that manually construct the legacy result shape remain source-compatible. It lists every directory whose directory resolution, opening, reading, or closing threw, so some or all of its contents may be absent from `entries`. `error` is the thrown value (a `NodeJS.ErrnoException` at runtime), so callers can distinguish a benign missing-directory race (`ENOENT`) from a real read failure (`EACCES`, `EIO`, `ESTALE`, …). The walk-root failure has an empty `relativePath` and `depth: 0`. Failures resolving a symlink's target kind are not reported here.
 
 ## Options
 
@@ -102,6 +102,14 @@ This prunes a directory after finding its marker without listing that directory'
 
 Unreadable directories are skipped rather than throwing, but every skipped directory is recorded in `failedDirs`. This keeps the helper suitable for best-effort inventories while letting pruning jobs tell an incomplete scan from an empty one: a destructive reconcile that deletes state for paths missing from `entries` must first confirm `failedDirs` holds no real read failures, or a transient `EIO`/`EACCES` blip would be mistaken for mass deletion. Use a stricter root-bounded operation when every entry must be accounted for.
 
+With `maxEntries`, both standalone walkers stream in filesystem order with a
+Node.js's default 32-entry directory buffer. They examine at most the remaining
+budget plus one lookahead per visited directory; Node may prefetch the rest of
+the current 32-entry batch without invoking filters for those names. Memory is
+bounded independently of directory width. Streams close on completion,
+truncation, and callback failure. Filtering consumes the budget. Without an entry
+budget, they retain eager directory snapshots for complete scans. Neither standalone API sorts its output.
+
 ## Root-bounded async iteration
 
 `Root.walk(rel, options)` is the root-bounded counterpart to these standalone
@@ -148,9 +156,13 @@ home-directory expansion, prefix it with `./`, as in
 
 The default `order: "sorted"` visits each directory's names in lexicographic
 order before descending depth first. It reads and sorts all names in each
-visited directory. With `maxEntries`, it prepares small metadata batches capped
-by the remaining global entry budget. Every batch stops at the first directory
-or symlink, so recursive descent cannot spend a budget already used by later
+visited directory, even with `maxEntries`, so truncated walks select the globally
+smallest names within each directory rather than a filesystem-order-dependent
+subset. For an unchanged tree this preserves deterministic results. The entry
+budget bounds metadata and filtering work, but does not bound sorted name
+enumeration memory or time. With `maxEntries`, it prepares small metadata batches
+capped by the remaining global entry budget. Every batch stops at the first
+directory or symlink, so recursive descent cannot spend a budget already used by later
 siblings. An early `break` may leave metadata from the current batch unused;
 the total still stays within `maxEntries`. Filtering requires metadata and
 consumes the entry budget, including entries skipped by the filter.
@@ -237,7 +249,9 @@ for await (const entry of capability.walk("", {
 ```
 
 Filters run serially outside metadata batches and retain the supplied options
-object as their `this` receiver. When an awaited filter resolves, the walk
+object as their `this` receiver. Cancellation is checked after every filter
+decision, including synchronous callbacks, before yielding or descending.
+When an awaited filter resolves, the walk
 checks cancellation and revalidates the current listing directory and Root
 identities before using the decision. These checks do not refresh the entry's
 captured metadata or pin a later operation.
@@ -276,6 +290,20 @@ root-bounded and reports failures inline because an async iterator has no final
 result summary. Its default remains to throw on unreadable or invalid
 directories.
 
+`Root.list()` always returns a complete sorted array and has no entry budget.
+`Root.entries()` defaults to streaming filesystem order; its sorted mode buffers
+names, and `maxEntries` caps that buffer with one lookahead before throwing
+`too-large`. Watch scans use the same guarded filesystem-order stream and enforce
+their examined-entry budget before metadata lookup. Every Root listing mode
+rejects invalid UTF-8 names before application metadata lookup, including the
+lookahead; unexamined suffixes are not validated.
+
+Bun 1.4.2 implements `Dir` with an internal eager `readdir`, including when
+`bufferSize` is one. On that runtime, these budgets bound fs-safe's admitted
+names, metadata, and results, but cannot bound Bun's internal enumeration memory.
+Async scans retain async directory reads there; use Node.js when the directory
+width itself must not determine enumeration allocation.
+
 ## See also
 
 - [`fileStore`](file-store.md) — managed stores use bounded walking for pruning.