@openclaw/fs-safe 0.20.0 → 0.21.0

package/docs/retained-file.md

@@ -0,0 +1,113 @@
+---
+title: Retained Windows files
+description: "Explicit identity-bound retirement of an existing file; resource settlement is not persistence."
+---
+
+# Retain an existing Windows file
+
+`retainFileInDirectory` from `@openclaw/fs-safe/advanced` retains **one existing
+regular direct child**, without creating or deleting anything at admission.
+It requires the matching native package. There is no pathname-unlink fallback.
+The initial implementation supports fixed local NTFS drives only; other systems
+return `unsupported`.
+
+```ts
+import { retainFileInDirectory } from "@openclaw/fs-safe/advanced";
+
+const admission = retainFileInDirectory({
+  directory: producer.directory, // canonical C:\... spelling
+  parent: producer.parentIdentity, // exact bigint dev/ino
+  basename: producer.basename,
+  expected: producer.expected, // bigint dev/ino/size/mtimeNs/ctimeNs and SHA-256
+  assertBeforeMutation: () => producer.assertCurrentExclusiveAuthority(),
+});
+if (admission.status === "retained") {
+  using file = admission.file;
+  const outcome = file.remove(); // explicit; using alone does NOT delete
+  // outcome.persistence is always "not-proven".
+  producer.recordRetirementObservation(outcome);
+}
+```
+
+The producer must capture its expected identity, generation and bytes during its
+own creation/ownership protocol. Reading an arbitrary current pathname immediately
+before admission does **not** authenticate the producer. `Number` identities,
+zero/unknown identities, negative/overflowing identities, and malformed digests
+are rejected. A full opaque native volume/file ID is included in the receipt;
+no native handle or numeric descriptor is exposed. Receipts are immutable facts,
+not transferable authority.
+
+## Public types
+
+- `RetainFileInDirectoryOptions`: immutable admission inputs and synchronous authority.
+- `RetainedFileExpected`: exact producer identity, write generation and expected digest.
+- `RetainedFileAdmission`: a retained `RetainedFile` or a refusal/settlement result.
+- `RetainedFileReceipt`: immutable admitted facts, never reusable authority.
+- `RetainedFileResult`: separate disposition, namespace, resources and persistence facts.
+- `RetainedFileIssue`: phase, native code/message and optional original authority cause.
+
+## Admission and mutation custody
+
+The directory's ancestry is opened component by component without following
+reparse points, with delete sharing denied. Its exact expected parent identity
+and canonical path are checked. The file is opened relative to that retained
+parent, with write/delete sharing denied. Existing writer handles refuse
+admission; a read-oplock grant also excludes preexisting writable mapped
+sections. That oplock request is cancelled and joined before admission returns,
+while the no-write-sharing file handle remains open. No detached request remains.
+
+The opened file must match the expected exact NTFS identity, single-link regular
+type, write/change generation, size and SHA-256. Names with stream/device syntax,
+trailing-dot/space aliases and observed named data streams are unsupported.
+Readonly attributes and ACL denials are not repaired or overridden. Verification
+is synchronous and bounded by `maxBytes` (default 16 MiB, maximum 64 MiB).
+
+The original producer must retain **exclusive mutation custody for the entire
+file**, including alternate streams, attributes, security and hardlink creation.
+Windows read/write sharing is per-stream; it is not an application lock over
+all possible aliases. The helper rejects observed alternate streams and changed
+generations, but does not turn a point-in-time check into exclusion of concurrent
+alias/attribute operations. The synchronous `assertBeforeMutation` must check
+that this original authority is still current. Callers unable to establish that
+custody must not call `remove`. Privileged/raw-volume/kernel modifications are
+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.
+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
+`error.details.result` if resource settlement is uncertain; `dispose()` returns
+that result directly. GC closes only and produces no settlement receipt; use
+explicit disposal.
+
+## Read the facts separately
+
+| Field | Meaning |
+| --- | --- |
+| `status` | `unsupported`, `not-attempted`, `preserved-mismatch`, `disposition-accepted`, `name-absent-after-settlement`, `failed`, or `indeterminate`. |
+| `disposition` | Whether native deletion was unattempted, accepted, rejected, or indeterminate. |
+| `namespace` | A post-file-close observation: absent, original, foreign, unknown, or not observed. Absence alone never authenticates prior deletion. |
+| `resources` | `closed` or `close-failed`; operation and close errors are retained together. An uncertain close is never retried against a possibly recycled handle. |
+| `persistence` | Always `not-proven`; no namespace persistence barrier was performed. |
+
+An accepted disposition can still have an unknown/foreign/original namespace
+observation or failed close. A later replacement may exist even after observed
+absence. Existing read handles can retain access to old bytes after the name is
+absent. Namespace observation does not certify all foreign handles are closed.
+An unexpected native binding failure is indeterminate, not success.
+
+## No persistence or service-transaction guarantee
+
+This API does not flush a volume, implement a journal, certify power-loss-safe
+unlink, or issue an application dependency release. Process-termination tests
+establish process-owned handle lifetime only, not crash/storage durability.
+
+An update transaction must independently qualify either a real namespace
+persistence barrier or original-owned durable recovery with correct ordering,
+generation binding and restart consumption. Until then it must retain its
+uncertain recovery/dependency state. Successful removal of one payload does not
+establish a committed multi-file transaction or justify deleting its receipt.

package/docs/root.md

@@ -68,7 +68,10 @@ fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kin
 
 `walk()` is the incremental, root-bounded recursive scan. It supports entry and
 depth budgets, cancellation, and `symlinkPolicy: "skip" |
-"follow-within-root"`. With an entry budget, sorted walks prepare small metadata
+"follow-within-root" | "include"`. Include mode returns links as
+`{ relativePath, kind: "symlink", size }` without resolving or entering their
+targets, including dangling and outside-root links. `size` describes the link,
+not its target. With an entry budget, sorted walks prepare small metadata
 batches within the remaining budget; unbounded sorted walks reuse the full
 directory snapshot.
 The default `order: "sorted"` enumerates and sorts each directory's names;
@@ -92,6 +95,8 @@ Directory reads remain fail-fast by default. With
 `{ relativePath, kind: "directory-error", size: 0, error }` and continues with
 the remaining tree. That policy also covers identity-check failures after an
 awaited filter, while callback failures always reject.
+In include mode, a directory that becomes a symlink before descent is a
+`path-mismatch` directory error; it is never silently omitted or followed.
 See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
 with the standalone best-effort walkers.
 

package/docs/temp.md

@@ -22,10 +22,11 @@ substitutions; the compatible JavaScript fallback has the narrower race
 contract documented below.
 
 On POSIX, workspace creation verifies the supplied root and its canonical
-ancestors before creating a child. Each existing directory must be owned by the
-effective user or root. Group/world-writable directories must also have the
-sticky bit, so ordinary system temp directories remain usable without changing
-their modes. Foreign-owned directories and non-sticky writable ancestors reject
+ancestors before creating a child. The supplied root must be owned by the
+effective user and must not be group/world writable, even with the sticky bit.
+Use a private per-user directory rather than supplying a shared `/tmp` directly.
+Ancestors must be owned by the effective user or root; group/world-writable
+ancestors must have the sticky bit. Foreign-owned directories and non-sticky writable ancestors reject
 with `not-owned` or `insecure-permissions`; unavailable effective-user identity
 rejects with `permission-unverified`. Existing supplied directories keep their
 permissions. Missing root components are created at `0o700` and initialized
@@ -34,6 +35,25 @@ mode, correction uses a verified directory descriptor.
 An initial mode-descriptor admission error is preserved if closing that rejected
 descriptor also fails; close failures after successful admission remain reportable.
 
+On Linux, non-identity `/proc/self/uid_map` and `/proc/self/gid_map` evidence
+permits ancestors whose UID and GID equal unmapped kernel overflow IDs,
+provided the same ancestor mode checks pass.
+These owners are classified as **unmapped**, not verified root owners:
+[Linux maps all unmapped owners to overflow IDs](https://man7.org/linux/man-pages/man7/user_namespaces.7.html).
+Supporting systemd user services with `PrivateUsers=true` therefore trusts the
+host directory hierarchy against unmapped host peers who own an ancestor and
+can rename it. Sticky world-writable ancestors remain admitted because host
+`/tmp` and `PrivateTmp` appear unmapped under `PrivateUsers`; refusing them would
+disable the default system-temp layout even with a private per-user leaf root.
+An unmapped host owner of such a sticky ancestor could rename its children,
+but a normal host's `/tmp` is root-owned by construction. Mapped foreign owners
+still reject, and this exception never applies to the supplied root or newly
+created workspace. Both maps and mapped-owner exclusions are checked afresh
+whenever admission relies on unmapped ownership, including identity replay;
+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,

package/docs/testing.md

@@ -1,5 +1,58 @@
 # Testing
 
+## Manual watch stress campaign
+
+Build from the exact revision being qualified with `pnpm install --frozen-lockfile`,
+`pnpm native:build`, and `pnpm build`, then run on a disposable machine:
+
+```sh
+node scripts/watch-stress.mjs --scenario all
+```
+
+Individual scenario names are `scale`, `fanout`, `churn`, `lifecycle`,
+`adversarial`, `limits`, `idle`, and `soak`. The runner uses plain Node and no
+additional dependencies. Each scenario prints one JSON result line; progress
+goes to stderr. `all` isolates scenarios in child processes and stops at the
+first failure. This suite is manual and is not part of per-PR CI.
+
+Run `node scripts/watch-stress.mjs --scenario oracle-selftest` first to check
+that a poisoned cache fails comparison and can recover only after invalidation.
+All fixture Roots live in `os.tmpdir()`. The consumer cache refreshes only from
+`onInvalidate`, using guarded Root reads of invalidated paths/scopes. After
+quiescence and a fresh `reconcile()`, checkpoints compare it with an independent
+filesystem walk, including file-content hashes. A mismatch is a failure, with
+no comparison retry or checkpoint-triggered cache refresh. Transient guarded
+read failures retain already-invalidated consumer work and settle at 25 ms
+intervals, with a 120-second flush deadline; these errors are counted in results.
+
+Scale uses 50,000 files in 2,000 child directories. Fan-out checks 64 and 256
+distinct Roots, one shared hub thread, and return to the warmed handle baseline.
+Churn first creates 1,024 entries while JavaScript is blocked to exceed the
+default 256-path detail budget, then runs at least five minutes with persistent
+differences across 10,000-mutation batches and isolated edit latency measurements.
+Lifecycle performs 10,000 ready/close cycles plus admission
+cancellation, close-during-ready, 1,000 scope replacements, and callback-close.
+Adversarial cases exercise Root swaps, outside symlinks, recursive deletion and
+10,000 same-name create/delete pairs. Soak runs 30 minutes, checking the oracle
+each minute. Linux needs passwordless `sudo` for the limits scenario; it lowers
+`fs.inotify.max_user_watches` to 1 in a child shell with a restoration trap and
+verifies restoration. Never run that scenario on a shared production host.
+
+RSS limits are fixed before execution: 512 MiB peak for churn/soak, at most
+64 MiB growth after warmup, and at most 32 MiB lifecycle growth after 3,000
+cycles. Reports include samples and fitted slopes. Idle runs for ten minutes
+with 16 subscriptions and a one-hour reconciliation interval to isolate native
+hub wakeups, requiring less than 1% of one CPU and, on Linux, at most 30 hub
+context switches. macOS captures `ps -M`; Windows captures PowerShell thread
+CPU time and handle counts. macOS descriptor counts use `lsof`.
+
+The macOS limits case also exercises injected UserDropped/KernelDropped flags
+through the native decoder and labels these as synthetic. Natural FSEvents drop
+flags are not independently observable through the current public batch. Windows
+records native overflow and recovery, but the shared batch does not distinguish
+RDCW kernel-buffer loss from bounded native queue loss; a Windows qualification
+must retain that limitation rather than call it proved kernel overflow.
+
 ## Linux openat2 fallback
 
 Build the host addon and package first. The test hook is cached with the native
@@ -186,6 +239,13 @@ For tests that need a private temp workspace, [`withTempWorkspace`](temp.md) mak
 
 ## Repo test shards
 
+On macOS, after building the native addon, run the native watch cleanup allocation
+regression with `MallocStackLogging=1 node --expose-gc scripts/watch-cleanup-leak-proof.mjs`.
+It compares `leaks` results before and after 100 and 1,000 subscription cycles,
+requiring zero growth in leaked allocations. Allocation stacks are saved under
+`.artifacts/watch-cleanup-leaks`. The native macOS CI lane runs this short proof;
+the full stress campaign remains manual.
+
 Run the full local gate before handoff:
 
 ```sh

package/docs/types.md

@@ -4,6 +4,12 @@ The types most callers reach for. Shared data shapes are exported from `@opencla
 
 For atomic replacement, `ReplaceFileAtomicFileSystem` and `ReplaceFileAtomicSyncFileSystem` are exported from `@openclaw/fs-safe/atomic`. Async adapters use `chmod()` on the `FileHandle` returned by their required `open()` operation. The synchronous type adds optional `fchmodSync(fd, mode)`; custom sync adapters that explicitly request `mode` or `preserveExistingMode` must implement it. See [Atomic writes](atomic.md#test-injection).
 
+`ReplaceFileAtomicDestinationState` is also exported from that subpath. It is a
+readonly union of `{ state: "removed", path }` and
+`{ state: "writing" | "published", path, dev: bigint, ino: bigint }`. Both atomic
+replacement option types accept synchronous `assertBeforeMutation` and
+`onDestinationState` callbacks. See [authority and destination state](atomic.md#atomic-write-authority-and-destination-state).
+
 ```ts
 import type {
   BasePathOptions,

package/docs/walk.md

@@ -107,11 +107,32 @@ Unreadable directories are skipped rather than throwing, but every skipped direc
 `Root.walk(rel, options)` is the root-bounded counterpart to these standalone
 inventory helpers. It yields `{ relativePath, kind, size }` incrementally and
 accepts `maxDepth`, `maxEntries`, `symlinkPolicy: "skip" |
-"follow-within-root"`, `order: "sorted" | "filesystem"`, and an `AbortSignal`. The default budget behavior yields
+"follow-within-root" | "include"`, `order: "sorted" | "filesystem"`, and an `AbortSignal`. The default budget behavior yields
 one `kind: "truncated"` marker and ends; pass `limitBehavior: "throw"` for a
 typed `FsSafeError("too-large")` instead.
 
 For followed symlinks, both `kind` and `size` describe the resolved target.
+With `symlinkPolicy: "include"`, links retain `kind: "symlink"` and their own
+size. Targets are neither resolved nor visited; dangling and outside-root links
+are included. Filters receive these entries, and links consume the same entry
+budget as other names. A directory replaced by a symlink after observation
+fails with `path-mismatch` before descent, or produces a `directory-error`
+entry when `onDirectoryError` is `"skip-and-report"`.
+The starting directory retains existing Root path resolution; include mode
+controls the entries beneath that directory.
+
+```ts
+for await (const entry of capability.walk("", { symlinkPolicy: "include" })) {
+  if (entry.kind === "symlink") reportLink(entry.relativePath);
+}
+```
+
+Existing skip/follow calls keep their result types without a symlink variant.
+For explicitly annotated include-mode values, use `RootWalkOptions<"include">`
+and `RootWalkEntry<"include">`. `RootWalkSymlinkPolicy` describes all
+three policies when the policy is selected dynamically; the unparameterized
+entry and options types retain their previous shapes. Use
+`RootWalkOptions<RootWalkSymlinkPolicy>` for a dynamically selected policy.
 
 The caller's starting path retains Root home shorthand: `~` and `~/dir` expand
 the home directory when iteration starts and must resolve inside the Root.

package/docs/watch.md

@@ -0,0 +1,184 @@
+# Guarded filesystem observation
+
+`@openclaw/fs-safe/watch` observes literal paths under an admitted `Root`.
+Notifications are advisory invalidations, not a transaction log, stable content,
+or authority to read a reported pathname. Guarded metadata scans through the
+original Root determine what may be published. Use the Root again to read data.
+
+```ts
+import { root } from "@openclaw/fs-safe/root";
+import { watch } from "@openclaw/fs-safe/watch";
+
+const workspace = await root("/trusted/workspace");
+const subscription = watch(workspace, {
+  mode: "auto",
+  scopes: [
+    { path: "config.json", kind: "entry" },
+    { path: "skills", kind: "tree", depth: 8 },
+  ],
+  exclude: entry => entry.kind === "directory" && entry.path.endsWith("node_modules"),
+  onInvalidate(invalidation) {
+    // Schedule application-owned settling/reload work; this callback is synchronous.
+    console.log(invalidation.reason, invalidation.changes);
+  },
+});
+await subscription.ready;
+await subscription.setScopes([{ path: "skills", kind: "tree" }]);
+await subscription.reconcile();
+await subscription.close();
+```
+
+## Contract
+
+The subpath exports `watch` and the types `WatchScope`, `WatchEntry`,
+`WatchChange`, `WatchInvalidation`, `WatchFailure`, `WatchHealth`, `WatchOptions`,
+and `WatchSubscription`.
+
+An `entry` scope observes only that entry, including its identity and metadata.
+A `tree` also observes descendants to its depth (default 32, maximum 128).
+Depth zero observes only the entry. The empty string and `.` select the Root;
+trailing separators are accepted and normalized after validation. Scopes are
+literal names, never globs or home expansion. Absolute paths, traversal, NULs,
+and platform namespace aliases reject. Windows scopes also reject reserved
+device components and trailing dots/spaces that Win32 would silently alias. Filesystem identity determines ordinary
+case/Unicode aliases; names are not compared by lowercasing.
+
+Symlinks are observed as entries and never followed. A symbolic parent fails
+admission: separately admit a caller-trusted link target if needed. Missing
+entries and ordinary blocking files can become directories in later scans.
+Replacing, renaming, or losing the admitted Root fails observation; it never
+silently adopts a new Root. Directory entry scopes ignore child-only mtime/size
+changes, but include permission-mode changes to the directory itself.
+
+Each invalidation has `reason: "event" | "reconcile" | "overflow"` and optional
+bounded `changes: { path, type: "content" | "structural" }[]`. Missing detail
+means invalidate **every configured scope**. Initial admission and every
+successful `setScopes` publish one undetailed `reconcile` invalidation. A rename
+or identity replacement is structural; metadata changes to the same ordinary
+file may be content changes. Neither means the file is settled or readable.
+Raw event names remain private: detail comes from guarded scans, prior guarded
+snapshots, or explicitly configured targets. Unknown names and overflow lose
+detail. Exclusion callbacks are synchronous; excluded directories are not
+scanned. Exclusions are a scan policy, not a promise that overflow cannot wake
+the application.
+
+## Transport and mode
+
+| Platform/runtime | `auto` | Event transport / limitation |
+| --- | --- | --- |
+| Node.js on Linux with addon | `events` | One shared Rust thread and inotify instance; a nonrecursive watch per distinct directory inode. |
+| Node.js on macOS with addon | `events` | One FSEvents stream per subscription on a shared serial dispatch queue. Pathname activity after a swap remains advisory. |
+| Node.js on Windows with addon | `events` | One recursive ReadDirectoryChangesW Root handle per subscription on the shared IOCP hub; the open handle prevents ordinary renames of the Root's ancestors. |
+| Bun / other unsupported runtimes | `poll` | TSFN lifetime and shutdown have not been qualified; `events` rejects. |
+| Missing/disabled addon | `poll` | `events` rejects with `FsSafeError("helper-unavailable")`. |
+
+The shared hub sleeps until a filesystem event, command, or callback acknowledgement:
+Linux blocks on inotify plus eventfd, Windows on IOCP, and macOS on its command
+channel (FSEvents wakes it from the serial dispatch queue). There is no native
+polling timer; the independent JS reconciliation interval remains authoritative.
+
+`mode` is required. `poll` never starts or loads the watch hub; guarded scans
+may still use the existing addon. Existing `FS_SAFE_NATIVE_MODE=off` and
+`require` policies apply: `require` plus an unavailable event backend rejects
+`auto` too. Health reports the selected `events` or `poll` mode and failures
+from selection have `operation: "watch"`.
+
+Linux installs each watch **before** enumerating children. It opens directories
+beneath the Root using the shared guarded native open (openat2, or its checked
+openat fallback), checks exact identities, verifies the procfs namespace, and
+registers through `/proc/self/fd/N/.`. The final `/.` makes `IN_DONT_FOLLOW` apply
+to the directory instead of rejecting the procfs magic symlink. The descriptor
+closes immediately: inotify retains the inode reference. Reconciliation replaces
+registrations when the directory inventory changes. Queue overflow invalidates
+all owners; exhausted watch capacity reports `failure.code: "watch-limit"`.
+Nonblocking TSFN batches cannot block the hub on JavaScript, and per-owner
+pending detail and queued batches are bounded. The last removal stops and joins
+the native thread. No Worker threads, eval programs, or JS `fs.watch` are used.
+
+macOS uses FileEvents, NoDefer and WatchRoot with a 30 ms FSEvents latency.
+Absolute hints are reduced lexically against the admitted canonical Root;
+outside paths never become detail. Dropped/wrapped streams, RootChanged and
+Unmount trigger guarded reconciliation. Pathname hints can reflect activity
+after a swap, but the Root is never replaced and names require guarded admission.
+Removal synchronously stops, invalidates and releases the stream on its queue.
+
+Windows opens one identity-checked Root handle per subscription with
+READ/WRITE/DELETE sharing, backup semantics and overlapped I/O. Each handle
+observes the entire subtree; guarded scans filter hints to configured scopes.
+No descendant watch handles are retained, so directories inside the Root can be
+renamed while watching, including directories containing selected scopes.
+Root-wide noise can coalesce into whole-scope invalidation. Completed 64 KiB buffers are copied and the
+read re-armed before names are examined. Zero-byte / enumeration-loss completions
+invalidate every scope. Cancellation waits for IOCP completion before closing
+the handle or freeing its buffer; there are no detached retirement waits.
+
+Windows prevents ordinary renames of the Root's own ancestors while its directory
+handle is open, even with DELETE sharing. Use `mode: "poll"` when callers must not
+retain that handle. Renaming or replacing the Root still fails guarded observation;
+the subscription never adopts another location. Subscriptions have independent
+handles and delivery queues, and closing one does not retire another's observation.
+
+## Budgets and lifecycle
+
+| Option | Default / bound |
+| --- | --- |
+| `scopes` | At most 128 literal scopes |
+| `persistent` | `true`; `false` lets Node exit with the subscription still open |
+| `intervalMs` | 30000 with events; 1000 with poll; minimum 20 ms |
+| `maxDirectories` | 4096 observed directories, including scope ancestors |
+| `maxEntries` | 100000 examined entries per pass, including excluded entries |
+| `maxPendingPaths` | 256; maximum 4096 |
+| Reconciliation | One active pass and one coalesced pending pass; no convergence/pass budget |
+
+Periodic guarded reconciliation runs without needing an event. It catches
+missed events and works on filesystems where native hints are incomplete.
+Scans are metadata comparisons: content changes preserving all compared
+metadata may be missed in polling mode. No mode promises transactional
+snapshots, complete history, or hard real-time delivery.
+
+`ready` resolves after the first complete guarded scan establishes the baseline,
+even while writes continue. Events mode installs each directory registration
+before listing it (FSEvents and recursive RDCW anchors cover the crawl). A changed
+registration/listing identity is retried up to three times per directory; further
+churn invalidates that subtree. Poll mode starts with its first scan and detects
+changes during the crawl on the next comparison. Neither mode waits for two
+agreeing scans.
+
+Each later pass compares with the previous snapshot, publishes bounded differences,
+and adopts its result as the next snapshot. Vanishing entries, kind changes, and
+transient descendant scan errors produce structural invalidations, preserving the
+Root identity checks. Events during a pass coalesce into one pending pass; detail
+overflow or catching up beyond the 25 ms coalescing window emits `overflow` without
+detail. Sustained writes cannot exhaust a pass budget or disable observation.
+
+`reconcile()` resolves after a complete pass that **started after the call**. Calls
+waiting for the same future pass coalesce; an earlier in-flight pass cannot satisfy
+a new call. It rejects only when observation becomes unavailable or is closed.
+`setScopes` fences the old generation immediately and resolves after the new
+baseline scan; superseded scope calls reject `AbortError`.
+By default, an open subscription keeps the Node event loop alive, matching
+`fs.watch`. Set `persistent: false` for caches used by one-shot commands:
+the subscription's timers and native delivery handle do not keep Node alive,
+including during startup or reconciliation. Invalidations still arrive while
+other work keeps the process alive. Persistent and non-persistent subscriptions
+have independent lifetimes; closing the last persistent one lets Node exit.
+Native environment cleanup retires any remaining event registrations and joins
+the hub at exit. `signal` triggers close;
+await `close()` or `[Symbol.asyncDispose]()` to join owned work.
+
+`health()` returns `starting`, `ready`, `reconciling`, `unavailable`, or `closed`,
+the actual mode, observed `directories`, and optional `{ operation, code, error }`
+failure. A running reconciliation reports `reconciling`, then returns to `ready`.
+Observation becomes `unavailable` on loss of Root authority (removed, replaced,
+or inaccessible), fatal native backend/registration failures such as `watch-limit`,
+deterministic size limits (`too-large`, operation `scan`), or callback contract
+violations. Invalid scope admission, including symbolic parents, still rejects;
+it never grants authority through a link. Transient descendant churn does not
+make an admitted subscription unavailable. Callbacks may synchronously retire the owner; returning a thenable from
+`onInvalidate`, `onHealth`, or `exclude` rejects observation. Application async
+work remains application-owned and is not joined by the subscription.
+
+`close()` is terminal, idempotent, and joined. Observation failures remain in
+health but do not make successful retirement reject. Retirement failures do
+reject, with a `SuppressedError` retaining an earlier observation failure when
+both exist. No new generation or callback can be admitted after close.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -95,6 +95,10 @@
       "types": "./dist/file-lock.d.ts",
       "default": "./dist/file-lock.js"
     },
+    "./watch": {
+      "types": "./dist/watch.d.ts",
+      "default": "./dist/watch.js"
+    },
     "./walk": {
       "types": "./dist/walk.d.ts",
       "default": "./dist/walk.js"
@@ -169,13 +173,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.20.0",
-    "@openclaw/fs-safe-darwin-x64": "0.20.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.20.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.20.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.20.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.20.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.20.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.21.0",
+    "@openclaw/fs-safe-darwin-x64": "0.21.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.21.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.21.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.21.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.21.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.21.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {