@openclaw/fs-safe 0.21.0 → 0.21.1

package/dist/watch-stream.js

@@ -0,0 +1,32 @@
+import path from "node:path";
+function shallowest(paths, limit) {
+    const result = [];
+    const sorted = [...new Set(paths)].sort((a, b) => a.split(path.sep).length - b.split(path.sep).length || a.localeCompare(b));
+    for (const name of sorted) {
+        if (result.some(parent => name.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep)))
+            continue;
+        result.push(name);
+        if (result.length === limit)
+            break;
+    }
+    return result;
+}
+/** Canonical names come only from guarded directory observations, never backend hints. */
+export function watchStreamPaths(snapshot, scopes) {
+    const anchors = [];
+    for (const scope of scopes) {
+        let name = scope.kind === "tree" && scope.depth !== 0 ? scope.path : path.dirname(scope.path);
+        if (name === ".")
+            name = "";
+        while (!snapshot.directoryPaths?.has(name)) {
+            if (!name)
+                break;
+            const parent = path.dirname(name);
+            name = parent === "." ? "" : parent;
+        }
+        const canonical = snapshot.directoryPaths?.get(name);
+        if (canonical)
+            anchors.push(canonical);
+    }
+    return { anchors: shallowest(anchors, 128), exclusions: shallowest(snapshot.excludedDirectories?.values() ?? [], 8) };
+}

package/dist/watch-types.d.ts

@@ -37,6 +37,8 @@ export type WatchOptions = {
     persistent?: boolean;
     /** Guarded reconciliation interval: events 30000, poll 1000; minimum 20 ms. */
     intervalMs?: number;
+    /** Polling transport interval; overrides intervalMs in poll mode or auto fallback. Minimum 20 ms. */
+    pollIntervalMs?: number;
     exclude?: (entry: WatchEntry) => boolean;
     maxDirectories?: number;
     maxEntries?: number;

package/dist/watch.js

@@ -5,7 +5,9 @@ import { rootHandleContext } from "./root-handle-context.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { admittedNativeChanges } from "./watch-alias.js";
-import { changedEntries, guardedHintChanges, scopedChanges } from "./watch-hints.js";
+import { watchStreamPaths } from "./watch-stream.js";
+import { changedEntries, excludedWatchPath, guardedHintChanges, scopedChanges } from "./watch-hints.js";
+import path from "node:path";
 import { watchBinding, NativeWatchBackend } from "./watch-native.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
 import { isWatchPathError, scanWatch, watchScopes } from "./watch-scan.js";
@@ -48,6 +50,11 @@ export function watch(root, input) {
     let intervalMs = budget(options.intervalMs, mode === "events" ? 30_000 : 1000, "intervalMs", 2_147_483_647);
     if (intervalMs < 20)
         throw new RangeError("watch intervalMs must be at least 20");
+    const pollIntervalMs = budget(options.pollIntervalMs, options.intervalMs ?? 1000, "pollIntervalMs", 2_147_483_647);
+    if (pollIntervalMs < 20)
+        throw new RangeError("watch pollIntervalMs must be at least 20");
+    if (mode === "poll")
+        intervalMs = pollIntervalMs;
     const maxDirectories = budget(options.maxDirectories, 4096, "maxDirectories");
     const maxEntries = budget(options.maxEntries, 100_000, "maxEntries");
     const maxPendingPaths = budget(options.maxPendingPaths, 256, "maxPendingPaths", 4096);
@@ -76,6 +83,7 @@ export function watch(root, input) {
     let pendingWaiter;
     let runningWaiter;
     let pendingHint = false;
+    let pendingBackendOverflow = false;
     let pendingChanges = new Map();
     let timer;
     let hintTimer;
@@ -117,6 +125,7 @@ export function watch(root, input) {
         pending = false;
         pendingHint = false;
         pendingChanges = new Map();
+        pendingBackendOverflow = false;
     };
     const notifyHealth = () => {
         try {
@@ -203,6 +212,16 @@ export function watch(root, input) {
     const onHint = (g, batch) => {
         if (terminal || current !== g || g.abort.signal.aborted || failure !== undefined)
             return;
+        if (batch.overflow) {
+            pendingBackendOverflow = true;
+            try {
+                assertSynchronousCallbackResult(getFsSafeTestHooks()?.afterWatchBackendOverflow?.(context.rootReal, "received"), "afterWatchBackendOverflow");
+            }
+            catch (error) {
+                lose(error, "callback");
+                return;
+            }
+        }
         if (batch.error === "ESTALE")
             refreshBackend = true;
         else if (batch.error) {
@@ -213,6 +232,8 @@ export function watch(root, input) {
             pendingChanges = undefined;
         else if (pendingChanges)
             for (const hint of batch.hints) {
+                if (typeof hint.name === "string" && excludedWatchPath(snapshot, hint.directory ? path.join(hint.directory, hint.name) : hint.name))
+                    continue;
                 const key = JSON.stringify([hint.directory, hint.name]);
                 if (!pendingChanges.has(key) && pendingChanges.size >= maxPendingPaths) {
                     pendingChanges = undefined;
@@ -241,7 +262,7 @@ export function watch(root, input) {
             return false;
         mode = "poll";
         binding = undefined;
-        intervalMs = options.intervalMs ?? 1000;
+        intervalMs = pollIntervalMs;
         return true;
     };
     const observe = async (g) => {
@@ -262,11 +283,12 @@ export function watch(root, input) {
         state = snapshot ? "reconciling" : "starting";
         notifyHealth();
         check(g);
-        const started = performance.now();
         const hadHints = pendingHint;
+        const hadBackendOverflow = pendingBackendOverflow;
         const hints = pendingChanges;
         pendingHint = false;
         pendingChanges = new Map();
+        pendingBackendOverflow = false;
         clearTimeout(hintTimer);
         hintTimer = undefined;
         if (mode === "events" && !backend && g.scopes.length) {
@@ -276,6 +298,8 @@ export function watch(root, input) {
                         onHint(g, batch);
                 }, maxPendingPaths, persistent);
                 backend = candidate;
+                if (snapshot)
+                    candidate.configure(watchStreamPaths(snapshot, g.scopes));
                 const hookResult = getFsSafeTestHooks()?.afterWatchBackendCreated?.(context.rootReal, batch => {
                     if (backend === candidate)
                         onHint(g, batch);
@@ -288,7 +312,7 @@ export function watch(root, input) {
             }
             check(g);
         }
-        const next = await scanWatch(context, g.scopes, { exclude: options.exclude, maxDirectories, maxEntries, maxPendingPaths, admitting: !snapshot }, g.abort.signal, async (name, identity, guard) => {
+        const next = await scanWatch(context, g.scopes, { exclude: options.exclude, maxDirectories, maxEntries, maxPendingPaths, admitting: !snapshot, previous: snapshot }, g.abort.signal, async (name, identity, guard) => {
             check(g);
             const existing = registered.get(name);
             const acquire = !existing || existing.dev !== identity.dev || existing.ino !== identity.ino;
@@ -311,6 +335,10 @@ export function watch(root, input) {
                 registered.set(name, identity);
         }, retainRetirement);
         check(g);
+        if (backend?.configure(watchStreamPaths(next, g.scopes))) {
+            // The replacement stream is live before the next guarded pass covers the handover.
+            pending = true;
+        }
         // Retire stale inventory before the next pass; that crawl installs fresh anchors first.
         if ([...registered.keys()].some(name => !next.directories.has(name))) {
             refreshBackend = true;
@@ -345,10 +373,10 @@ export function watch(root, input) {
         let details = hadHints
             ? guardedHintChanges(g.scopes, snapshot, next, admittedHints, observed, maxPendingPaths)
             : observed;
-        const behind = (hadHints || pendingHint) && performance.now() - started > coalesceMs;
-        if (behind)
-            details = undefined;
         snapshot = next;
+        if (!initial && !details && hadBackendOverflow) {
+            assertSynchronousCallbackResult(getFsSafeTestHooks()?.afterWatchBackendOverflow?.(context.rootReal, "reconciled"), "afterWatchBackendOverflow");
+        }
         // Publish before readiness; callbacks may synchronously retire this generation.
         if (initial || !details || details.length)
             dirty(g, initial ? "reconcile" : !details ? "overflow" : hadHints ? "event" : "reconcile", initial ? undefined : details);

package/docs/archive.md

@@ -179,6 +179,12 @@ between native and JavaScript paths rather than reimplementing it in Rust.
 
 ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless internal separator and dot-component equivalence is allowed only after validation; every raw and Unicode interpretation must also agree on whether its name ends in `/` or `\`. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
 
+ZIP preflight and bounded reads apply extraction's case-insensitive NFC collision
+policy to the complete archive, including entries that extraction would strip
+or skip. Known UTF-8 and Unicode Path names are checked during physical admission;
+legacy names retain backend-selected decoding and undergo the same collision
+check before callbacks or selected bytes are returned.
+
 ZIP end-record admission searches the bounded comment window for signatures
 while retaining complete comment-length and ambiguity checks. Dense signature
 sequences fall back to the bounded byte scan.

package/docs/atomic.md

@@ -154,8 +154,9 @@ can replace the pathname, so compare the recorded identity with the current
 entry and recheck application authority before compensation. Receipts do not
 promise durable storage or authorize rollback.
 
-Both callbacks must complete synchronously; Promise and thenable results are
-rejected, and ordinary return values are ignored. The first callback refusal
+Both callbacks must complete synchronously; Promise, thenable, and synchronous
+or asynchronous generator results are rejected. Returned generators are never
+advanced; other ordinary return values are ignored. The first callback refusal
 is terminal, including falsy thrown values; an `EPERM`, `EEXIST`, or `EBUSY` code
 from a callback never starts fallback or retry. Refusal during an in-place
 fallback also stops new restoration writes. Final mode, synchronization, close,
@@ -245,6 +246,22 @@ that same descriptor, and synchronizes the result. Any write, mode, or sync
 failure triggers a byte-and-mode restore and another sync through the same
 descriptor.
 
+With mutation callbacks enabled, an `EIO` from destination `stat`/`lstat` after
+successful truncation also attempts restoration through that retained descriptor.
+Each restore write still requires live application authority and fresh exact
+descriptor identity, regular-file, and configured hardlink checks. The failed
+pathname observation is not retried to authorize restoration; no pathname is
+opened, removed, or replaced. A successor at that name is left untouched.
+`details.cleanup: "restored"` means the retained original file's bytes and mode
+were restored and synchronized, not that the pathname still names it. The existing
+`writing` receipt identifies that file; no `published` receipt is emitted for a
+failed replacement. Restoration I/O failures report `"restore-failed"`.
+
+Callback refusals, detected identity/type/link changes, and other metadata errors
+remain terminal. Failed descriptor revalidation also stops restoration. These
+cases can leave the retained file empty or partial with only a `writing` receipt;
+before the first successful truncation, verification failure leaves it untouched.
+
 With `syncTempFile: false`, an exclusive-create copy fallback does not report
 success until its new destination writer closes successfully. This includes
 `"restore-original"` when the destination did not exist. A close rejection or throw is
@@ -275,6 +292,10 @@ through short reads and EOF, grow only as data arrives, and enforce the same
 `beforeRename` callback, and `ReplaceFileAtomicSyncFileSystem`. Use it inside
 synchronous boot paths or test setup code. It returns the same
 `{ method: "rename" | "copy-fallback" }` receipt as the async variant.
+Promise, thenable, and synchronous or asynchronous generator results from the
+hook reject with `TypeError` before publication; rejected promises are consumed
+and generators are never advanced. Other synchronous return values are ignored.
+The replacement is not published; owned-temp cleanup follows the rules above.
 
 ## `replaceDirectoryAtomic`
 

package/docs/contributing.md

@@ -94,11 +94,11 @@ GLIBC versions. To inspect an existing binding, use
 `pnpm native:build` remains a host-toolchain development build; it does not
 establish the GNU release ABI floor.
 
-On Linux x64 with Docker, run `pnpm build`, copy the GNU x64 artifact from
+On Linux x64 or arm64 with Docker, run `pnpm build`, copy the matching GNU artifact from
 `artifacts/` to `native/`, run `node scripts/stage-host-native.mjs`, then run
 `bash scripts/test-linux-glibc-floor.sh`. CI uses this command to load the actual
 artifact and run native security and no-replace move tests in Rocky Linux 8
-(glibc 2.28). GNU arm64 is cross-built and symbol-checked in the same CI matrix.
+(glibc 2.28). Both GNU architectures execute this load test on matching runners.
 
 ## Test
 
@@ -172,6 +172,47 @@ actual edit latency. Run `FS_SAFE_TEST_SERIAL=1 pnpm check` to isolate local tim
 checks from the other filesystem stress suites. Watch fixtures use normal OS
 temporary storage; session scratch trees may suppress macOS filesystem events.
 
+### Optional Linux Testbox
+
+The manual `testbox-validation.yml` workflow prepares a 16-vCPU Ubuntu 24.04
+Blacksmith Testbox with Node 24.21.0, pnpm 12.4.2, dependencies, the Rust WASM
+target, and the pinned portable archive compiler. It leaves library builds and
+validation commands to the caller and does not replace required CI checks.
+
+Use an authenticated Blacksmith CLI with access to the repository and its
+Blacksmith organization. From a full repository checkout, warm one session
+through Crabbox:
+
+```sh
+CRABBOX_BLACKSMITH_IDLE_TIMEOUT=240m crabbox warmup --provider blacksmith-testbox \
+  --blacksmith-org openclaw \
+  --blacksmith-workflow .github/workflows/testbox-validation.yml \
+  --blacksmith-job validate --blacksmith-ref main \
+  --idle-timeout 240m --timing-json
+```
+
+Use a branch or tag containing the workflow for `--blacksmith-ref`; GitHub must
+first have registered the workflow on the default branch. The job has a fixed
+240-minute limit. Keep the idle timeout at that limit (240 minutes in the native
+Blacksmith CLI) because the pinned Testbox action can miss active SSH sessions
+behind a forwarded port. Bound commands by the remaining job time and leave time
+to collect results and stop before the deadline.
+
+Use the returned `tbx_...` ID for subsequent commands. The `fs-safe-testbox`
+wrapper restores the prepared tool paths and WASM compiler settings in the SSH
+shell. For example:
+
+```sh
+crabbox run --provider blacksmith-testbox --id <tbx_id> --timing-json -- \
+  fs-safe-testbox pnpm check
+crabbox stop --provider blacksmith-testbox <tbx_id>
+```
+
+Stop the session when finished and verify its terminal status. Blacksmith owns
+checkout synchronization; record the tested source revision or diff, Testbox ID,
+and Actions run. This backend is Linux-only and does not accept Crabbox's direct
+SSH `--script` or `--download` flags. The workflow provides no application secrets.
+
 ### Method benchmarks
 
 `pnpm benchmark:methods` measures the callable library surface against synthetic
@@ -236,10 +277,32 @@ require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standa
 direct `node` invocation without lifecycle metadata is unsupported. Archive
 codecs and their dependencies are packed from the installed dependency graph.
 
-PR CI builds and executes four host targets: Linux x64 glibc, Linux x64 musl
-(Alpine), macOS arm64, and Windows x64. The root-only smoke runs on each. The
-seven-target source build matrix runs on release tags; packaging all seven is
-not execution proof for every architecture. The smoke writes manager versions,
+PR CI builds and executes all seven shipped bindings. The existing check names
+stay stable; extra runner/runtime combinations add checks without changing the
+repository ruleset. Native lanes run Node 24; the GNU host lanes also exercise
+Bun 1.4.2 (as do macOS and Windows).
+
+| Lane | Runner | Architecture / libc | Runtime |
+| --- | --- | --- | --- |
+| JavaScript check | `ubuntu-latest` | x64 / glibc | Node 22, 24, 26 |
+| JavaScript check | `macos-15` | arm64 | Node 22, 24, 26 |
+| JavaScript check | `fs-safe-windows-16core` (`windows-latest`) | x64 | Node 22, 24, 26 |
+| Native check | `ubuntu-latest` | x64 / glibc | Node 24, Bun 1.4.2 |
+| Native check (forced no-openat2) | `ubuntu-latest` | x64 / glibc | Node 24 |
+| Native check | `ubuntu-24.04-arm` | arm64 / glibc | Node 24, Bun 1.4.2 |
+| Native check | `macos-15` | arm64 | Node 24, Bun 1.4.2 |
+| Native check | `macos-15-intel` | x64 | Node 24, Bun 1.4.2 |
+| Native check | `fs-safe-windows-16core` (`windows-latest`) | x64 | Node 24, Bun 1.4.2 |
+| Native check | `windows-2022` (standard hosted) | x64 | Node 24, Bun 1.4.2 |
+| Native check (Alpine 3.24) | `ubuntu-latest` | x64 / musl | Node 24 |
+| Native check (Alpine 3.24) | `ubuntu-24.04-arm` | arm64 / musl | Node 24 |
+| GNU glibc 2.28 build + Rocky Linux 8 load | `ubuntu-latest` | x64 / glibc | Node 24 |
+| GNU glibc 2.28 build + Rocky Linux 8 load | `ubuntu-24.04-arm` | arm64 / glibc | Node 24 |
+| Bundled package smoke | `ubuntu-latest`, `macos-15`, `fs-safe-windows-16core` | host | Node 22, 24 |
+| Coverage | `ubuntu-latest`, `macos-15`, `fs-safe-windows-16core` | host | Node 22 |
+
+Both musl lanes also run root-only package smoke with the real host binding.
+The seven-target source build matrix still runs on release tags. The smoke writes manager versions,
 cases, and synthetic-fixture scope to `release-artifacts/consumer-proof.json`.
 
 ## Docs

package/docs/install.md

@@ -130,6 +130,8 @@ features, including strict owned-tree temp cleanup, retained-directory staging,
 and atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
 remain unavailable. Operations without a safe fallback fail with `helper-unavailable`
 when the matching package is absent, incompatible, or disabled.
+No-clobber `Root.move()` preserves a native loader failure in the error's
+`cause`, including the original missing-library or incompatible-glibc diagnostic.
 
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.

package/docs/native.md

@@ -96,12 +96,30 @@ operation is still a permission error and never triggers a retry. Install
 syscall filters before the first native operation; a later `ENOSYS` fails with
 `ENOTSUP`, rather than changing the cached mechanism during a call.
 
-The fallback opens each directory relative to a retained descriptor with
-`O_PATH | O_DIRECTORY | O_NOFOLLOW`, compares exact device/inode/type identities,
-and rechecks the retained parent chain before and after the final no-follow
-open. It rejects all symlink components, including procfs magic links, even
-when the low-level caller requests symlink following. Public Root policy and
-canonical-path admission, hardlink rejection, pinned-file checks, and mutation
+The fallback inspects components with `O_PATH | O_NOFOLLOW`, follows relative
+symlink targets using a stack of retained directory descriptors, and rejects
+absolute targets or `..` past the retained root with `EXDEV`. It permits at most
+40 link expansions (`ELOOP` beyond that limit). Final `O_NOFOLLOW` and exclusive
+creation retain their syscall semantics, including opening the link itself with
+`O_PATH | O_NOFOLLOW` and creating through a dangling in-root relative link.
+Exact device/inode/type identities are checked before and after the final
+no-follow open; followed links also retain their descriptors and have their
+named identities and target strings rechecked. Detected replacements fail with
+`EXDEV`, including changes to directories left behind by a link's `..` target.
+
+The fallback also honors `nosymfollow` mount restrictions on retained links.
+Two conservative restrictions remain: the fallback refuses to follow **any
+procfs symlink** with `ELOOP`, including ordinary links such as `/proc/mounts`.
+Userspace metadata cannot distinguish these from procfs magic links, which
+`RESOLVE_NO_MAGICLINKS` must never follow. Opening a final link itself with
+`O_PATH | O_NOFOLLOW` remains allowed. In a sticky, world-writable directory,
+the fallback refuses all symlink following with `EACCES`, even when the calling
+thread or directory owner owns the link, or `fs.protected_symlinks=0`. This
+preserves Linux's protected-symlink restriction without assuming the thread's
+filesystem UID or treating equal mapped `stat` UIDs as proof of equal kernel
+owners (distinct unmapped owners can both appear as the overflow UID).
+
+Public Root policy and canonical-path admission, hardlink rejection, pinned-file checks, and mutation
 identity fences remain in place. `openBeneath()` reports `best-effort`: these
 identity samples detect replacements but cannot make a multi-component walk
 atomic against a hostile process renaming directories between samples. This

package/docs/public-api.md

@@ -79,6 +79,16 @@ missing relative suffixes beneath an existing directory using bounded temporary
 directory probes. The caller owns Unicode-pair policy, caching, and the fallback
 for `undefined`. See [path suffix alias probing](path-suffix-aliases.md).
 
+`retainSymlinkInDirectory` holds an explicitly identified POSIX symlink through
+exact-slot no-replace publication; its receipts use the `StagedSymlink*` and
+`PublishedSymlinkReceipt` types. See [staged symlinks](staged-symlink.md).
+
+`retainFileInDirectory` retains an existing Windows NTFS file through a native
+handle for explicit identity-bound retirement. It is described by
+`RetainFileInDirectoryOptions`, `RetainedFile`, `RetainedFileAdmission`,
+`RetainedFileExpected`, `RetainedFileIssue`, `RetainedFileReceipt`, and
+`RetainedFileResult`. See [retained Windows files](retained-file.md).
+
 ## Guest source
 
 `@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,
@@ -132,8 +142,11 @@ parent/workspace descriptors; see the
 Atomic helper option and receipt types include
 `MovePathWithCopyFallbackOptions`, `ReplaceDirectoryAtomicOptions`,
 `ReplaceFileAtomicSyncOptions`, `ReplaceFileAtomicResult`,
-`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`, and
-`ReplaceFileDestinationHardlinkPolicy`.
+`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`,
+`ReplaceFileDestinationHardlinkPolicy`, and `ReplaceFileAtomicDestinationState`.
+The `assertBeforeMutation` option rechecks caller authority before new effects,
+and `onDestinationState` reports retained destination identities as
+`ReplaceFileAtomicDestinationState` values; see [atomic writes](atomic.md).
 
 The durability surface also exports the synchronous strict
 `syncDirectorySync`, plus `DirectoryReceipt`, `DurableDirectoryReceipt`,
@@ -160,6 +173,14 @@ Archive option and policy types are `ExtractArchiveOptions`,
 used by extractors. `resolvePackedRootDir` finds the single packed root when an
 archive layout permits it; neither helper weakens entry validation.
 
+## `watch`
+
+`@openclaw/fs-safe/watch` exports `watch()` plus `WatchScope`, `WatchEntry`,
+`WatchChange`, `WatchInvalidation`, `WatchFailure`, `WatchHealth`,
+`WatchOptions`, and `WatchSubscription`. Invalidations are advisory; guarded
+scans stay authoritative. See [filesystem observation](watch.md) for modes,
+budgets, `persistent`, and lifecycle.
+
 ## Keeping this list honest
 
 Every runtime and type name in `test/public-api.json` must appear somewhere in

package/docs/retained-file.md

@@ -75,8 +75,10 @@ outside this capability's threat model.
 `remove()` admits authority once, revalidates the retained object, sets native
 handle disposition, closes the file, observes the name under the still-retained
 parent, then closes ancestry. No pathname is passed to unlink. Ordinary
-`dispose()` and `[Symbol.dispose]()` only close resources. Asynchronous authority
-callbacks and reentrancy are refused; even caught reentrancy poisons that attempt.
+`dispose()` and `[Symbol.dispose]()` only close resources. Authority callbacks
+returning Promises, thenables, or synchronous or asynchronous generator objects
+are refused without deletion; generators are never advanced. Reentrancy is also
+refused, and even caught reentrancy poisons that attempt.
 Repeated settlement returns the original receipt without another mutation or
 another authority call. A copied receipt cannot be used to remove a replacement.
 `[Symbol.dispose]()` throws `FsSafeError` with the complete result in

package/docs/root.md

@@ -263,8 +263,10 @@ occurred, later cancellation or verification failure preserves the destination.
 The synchronous optional `onDestinationPublished` callback receives a frozen
 `RootCopyPublicationReceipt` containing `{ path, dev, ino }`, with exact bigint identity immediately after
 publication, before later checks can fail. Callback errors also preserve the
-published file. This receipt records an outcome; it does not authorize removing
-a file that another actor may have edited. Application recovery and cooperative
+published file. Promise, thenable, and synchronous or asynchronous generator
+results reject with `TypeError`; returned generators are never advanced. Other
+synchronous return values are ignored. This receipt records an outcome; it does
+not authorize removing a file that another actor may have edited. Application recovery and cooperative
 locking remain caller-owned.
 
 Existing `copyIn` callers must account for completed destinations retained after
@@ -324,10 +326,12 @@ truncation, append, move, and removal. Buffered writes use bounded chunks and
 recheck before every partial-write submission; file removal submits a direct
 unlink request. Native calls that perform multiple filesystem steps are one
 dispatch. No asynchronous wait separates the check
-from that dispatch. A thrown value rejects the operation unchanged; an async
-or thenable-returning callback rejects with `TypeError` before that mutation.
-Synchronous return values are ignored. Callbacks can run multiple times and
-must inspect current authority each time.
+from that dispatch. A thrown value rejects the operation unchanged; a Promise,
+thenable, or synchronous or asynchronous generator result rejects with `TypeError`
+before that mutation. Returned generators are never advanced. Other synchronous
+return values are ignored. Generator detection applies to generator objects
+themselves, not proxy wrappers. Callbacks can run multiple times and must inspect
+current authority during each call; return-value validation does not establish it.
 Directory creation rechecks the retained parent after the callback and before
 submitting mkdir, so a replacement is rejected before creating that component.
 Overwrite moves recheck the retained root, parents, source identity and both
@@ -354,7 +358,9 @@ For `openWritable()`, the callback covers the library's parent creation,
 exclusive creation, and truncation. The returned raw `FileHandle` belongs to
 the caller, which must check authority before its own later writes.
 
-All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
+All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Missing suffixes also match prospective case and canonical Unicode normalization aliases: case-folding and Unicode NFC/NFD-equivalent spellings cannot bypass a denied path or prefix. A read-only observation of the existing parent can establish that ASCII case variants are distinct. Admission never creates temporary probe files or directories. If sensitivity cannot be established (including empty or unreadable parents, future directories, and Unicode normalization), equivalent suffixes are denied conservatively, even on a filesystem that would allow distinct names. Distinct existing canonical ancestors and unrelated names remain distinct. Observations are local to each synchronous policy check and are refreshed after callbacks or mutations. This conservative fallback does not model other filesystem-specific equivalences, such as HFS+ ignorable formatting characters.
+
+Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
 
 `move()` snapshots its merged default and per-call mutation policy before
 asynchronous preparation. Later changes to the original policy objects or arrays
@@ -389,6 +395,12 @@ fs.entries(rel, options?)        // nonrecursive AsyncIterable<DirEntry>, includ
 fs.resolve(rel)                  // absolute path inside the root, after canonicalization
 ```
 
+Directory enumeration (`list`, `entries`, and `walk`) requires UTF-8 filenames.
+A discovered name that cannot be represented losslessly as a JavaScript string
+rejects with `invalid-path`, before looking up metadata through that name.
+Streaming traversal may already have yielded earlier entries. Literal Unicode
+replacement characters (`U+FFFD`) remain valid names.
+
 These do not pin a later operation. During `stat()`, the exact selected target and
 parent are checked around metadata collection; `list()` checks one exact selected
 directory around the complete name/metadata batch instead of repeating containment

package/docs/sidecar-lock.md

@@ -61,7 +61,7 @@ Always release locks in a `finally` block. Application-managed graceful shutdown
 
 Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. First registration is committed only after Node accepts the listener; synchronous `newListener` reentry fails closed and a thrown registration rolls back so a later acquisition can retry. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
 
-Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
+Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. Raw acquisition, snapshot, and exit cleanup capture bigint device/inode values; unsafe numeric identities from older in-process receipts cannot authorize cleanup. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
 
 Last-chance raw-lock exit cleanup requires known Windows device and inode values from both pathname observations and the opened descriptor. A zero value leaves the sidecar in place, including for token-owned locks. Known descriptor/path identity differences remain supported; a pathname identity change during the read still prevents cleanup.
 

package/docs/staged-symlink.md

@@ -86,7 +86,8 @@ the original receipt is never replaced by a post-publication identity.
   touching descriptor numbers.
 - `await using` invokes cleanup and raises on a `preserved` outcome. Invocation
   order serializes descriptor work; reentrant calls from the authority callback
-  reject. Callbacks must be synchronous; returned thenables are refused.
+  reject. Callbacks must be synchronous; returned thenables and synchronous or
+  asynchronous generator objects are refused. Generators are never advanced.
 
 Errors carry `StagedSymlinkFailureDetails` in `FsSafeError.details`: the phase,
 recorded `publication`, and a cleanup receipt when applicable. Publication is