@openclaw/fs-safe 0.19.0 → 0.21.0

package/docs/public-api.md

@@ -41,6 +41,11 @@ The lexical path surface additionally exports `isNodeError`,
 `UnsafeDeviceReadPathMatch`, `UnsafeDeviceReadPathOptions`, and
 `UnsafeDeviceReadPathReason`.
 
+`isPathRelativeEscape()` rejects absolute paths and relative paths that step
+above their starting directory at any point. Contained paths such as
+`dir/../file` remain relative. It accepts both separators on Windows; on POSIX,
+a backslash remains a literal filename character.
+
 The advanced root-file primitive exports `OpenRootFileParams`,
 `OpenRootFileSyncParams`, `RootFileOpenResult`, and
 `RootFileOpenFailureReason`. These are composition types for callers building
@@ -100,7 +105,8 @@ best-effort cleanup helper used by those queue flows.
 Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
 Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
 descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
-`WindowsAceFlags`.
+`WindowsAceFlags`. `readOwnerAndDaclBatch()` returns those same facts in input
+order through an isolated asynchronous batch with a whole-process timeout.
 
 Secure reads split their option and result shapes into
 `SecureFileTrustOptions`, `SecureFilePermissionOptions`,

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/security-model.md

@@ -232,13 +232,16 @@ The library does not modify or constrain the global Node.js `fs` namespace, and
 
 | Mechanism | Reported containment | Boundary |
 |---|---|---|
-| Linux native | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| 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. |
 | 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. |
 
 The macOS `F_GETPATH` verification is an escape detector, not a race-atomic guarantee. A hostile same-UID process can rename a directory after `O_RESOLVE_BENEATH` or the manual walk and race the post-open sample or a later descriptor-relative mutation. The native result therefore remains `best-effort` on macOS even when the kernel flag is available. No policy decision is attached to these labels; callers can inspect the fact and decide what their own threat model requires.
 
+The Linux fallback's identity checks are also detection-based: a directory can be renamed between chain samples or before a later descriptor-relative mutation. It cannot provide atomic resolution, and rejection after a mutating open does not promise rollback. See [Linux without openat2](native.md#linux-without-openat2) for the cached capability probe, conservative symlink rejection, and operations that remain unavailable.
+
 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.
 
 ## Limitations to keep in mind

package/docs/sidecar-lock.md

@@ -63,6 +63,8 @@ Exit cleanup tolerates shared managers created by older package copies that lack
 
 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.
 
+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.
+
 The raw sidecar bytes are not a canonical JSON representation: tools that trim or rewrite the trailing whitespace invalidate the ownership token, so release leaves the changed sidecar in place and fails closed. The token distinguishes cooperating acquisitions; it is not a secret and does not make pathname compare-and-remove atomic against a hostile process that can replace files outside the lock protocol.
 
 `release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` or `withFileLockSync()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed asynchronous acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.

package/docs/staged-symlink.md

@@ -0,0 +1,123 @@
+---
+title: Retained symlink publication
+description: "Admit and retain an identified staged symlink for no-replace publication and explicit recovery."
+---
+
+# Retained symlink publication
+
+`retainSymlinkInDirectory()` from `@openclaw/fs-safe/advanced` admits an
+**existing** direct-child symlink against caller-captured identity, ownership,
+change time and target. It holds a no-follow descriptor to that inode and its
+parent until cleanup. It does not create a symlink or infer ownership from a
+same-target pathname observation. This dedicated lifecycle does not relax
+`Root.move()` or regular-file staging's symlink rejection.
+
+The caller owns staging and admission evidence. Create and inspect the stage
+under the application's cooperative writer lock, and keep that lock through
+admission. A historical stat is not a lifetime handle: if peers can recycle
+inodes between capture and admission, identity numbers alone cannot establish
+historical ownership. Once admitted, the retained descriptor prevents inode
+reuse until this owner closes. Failed admission closes descriptors without
+unlinking anything; all staging cleanup remains with the caller.
+
+Linux uses `O_PATH | O_NOFOLLOW`; macOS uses metadata-only `O_EVTONLY | O_SYMLINK`
+with nonblocking/no-controlling-terminal flags. A non-following preflight rejects
+observed special files before open; the opened descriptor must still match.
+Windows, native mode off, and missing or older bindings reject before namespace
+mutation. No fallback interpreter, copy, following open, or public descriptor
+is used. Symlinks must have one link and a UTF-8 target; their targets are never
+opened or confined by this API. The application must authorize the target.
+
+## Example
+
+```ts
+import {
+  retainSymlinkInDirectory,
+  type StagedSymlinkExpected,
+  type PublishedSymlinkReceipt,
+} from "@openclaw/fs-safe/advanced";
+import type { DirectoryReceipt } from "@openclaw/fs-safe/durability";
+
+// Application owns stage creation, capture, locking and transaction policy.
+export async function publishInstallerLink(options: {
+  directory: DirectoryReceipt;
+  stagedBasename: string;
+  expected: StagedSymlinkExpected;
+  finalBasename: string;
+  assertAuthorizedAndCurrent(): void;
+}): Promise<PublishedSymlinkReceipt> {
+  await using staged = await retainSymlinkInDirectory({
+    directory: options.directory,
+    basename: options.stagedBasename,
+    expected: options.expected,
+    assertBeforeMutation: options.assertAuthorizedAndCurrent,
+  });
+  return await staged.publish(options.finalBasename);
+}
+```
+
+`expected` requires exact bigint `dev`, `ino`, `ctimeNs`, integer `uid`
+and `gid`, and `target`. Admission snapshots these values and the parent
+receipt. The frozen returned receipt contains `directory`,
+`temporaryBasename`, `target`, and preparation-time `identity` metadata,
+like [regular-file staging](staged-file.md). Rename may change timestamps;
+the original receipt is never replaced by a post-publication identity.
+
+## Lifetime and outcomes
+
+- `assertCurrent()` checks the admitted parent pathname, original name, retained
+  inode, single-link count, ownership, mode and target before publication.
+- `publish(basename)` accepts a distinct portable direct-child name. It performs
+  the synchronous authority assertion, rechecks source and parent, and dispatches
+  guarded native no-replace rename. An existing file, symlink or directory is
+  never overwritten, and the link is never nested inside a destination directory.
+- Successful dispatch is recorded as `published` **before** fallible postchecks.
+  A foreign same-target replacement fails verification without becoming owned.
+  `assertPublished()` checks against the still-retained inode.
+- `removePublished()` is an explicit recovery action, not automatic rollback.
+  It reasserts authority and removes only an observed matching published link
+  through the retained original parent. It returns `removed`, `name-absent`,
+  or `preserved`. Its outcome or error is cached: it never retries an uncertain
+  unlink or touches a later replacement. It does not restore an old destination.
+- `cleanup()` removes only an unattempted, still-owned stage, then closes both
+  handles. Published names are preserved. Indeterminate publication preserves
+  both names. Authority rejection during cleanup preserves the stage and still
+  closes handles. Repeated cleanup replays the cached result/error without
+  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.
+
+Errors carry `StagedSymlinkFailureDetails` in `FsSafeError.details`: the phase,
+recorded `publication`, and a cleanup receipt when applicable. Publication is
+`not-published`, `published` (with the precaptured receipt), or
+`indeterminate` (with the attempted name). Native errno, including a collision,
+does not rule out a committed remote rename whose response was lost. Only
+pre-dispatch rejection leaves publication `not-published`. After an indeterminate
+result, this owner cannot publish again or remove the possibly published name.
+If inspecting a native rename error itself fails, publication is likewise
+`indeterminate`; the original thrown value remains the reported cause.
+
+Cleanup records `temporaryBasename`, `publication`, `resources`
+(`closed` or `close-failed`), and `status` (`removed`, `name-absent`,
+`preserved`, `failed`, or `not-needed`). Failure closes every retained handle
+once and aggregates cleanup/close errors. A failed explicit recovery unlink is
+reported to its caller and is not converted into successful recovery by cleanup.
+Thrown values whose error metadata cannot be inspected are reported as
+`helper-failed` with the original value as `cause`; cleanup and recovery still
+cache their terminal error without retrying callbacks or descriptor closes.
+
+## Limits
+
+This is directory-relative targeting, **not CAS**. Identity checks followed by
+rename or unlink are not atomic conditional mutations. An uncooperative writer
+can replace a child in the final syscall gap; observed substitutes are preserved,
+but callers must coordinate writers to exclude that gap. The retained parent
+prevents redirection into a replacement parent; a parent move can still cause
+publication in the moved original and a `published` postcheck failure.
+
+No receipt promises crash durability or recovery after process death, arbitrary
+renames, permission revocation or I/O failure. This API does not sync directories
+or persist descriptors. Caller journals, state capture, conditional restoration,
+durability, and transaction settlement remain separate requirements. Keep the
+owner alive until the application's publication or recovery decision settles.

package/docs/store.md

@@ -62,7 +62,9 @@ const pending = await loadPendingJsonDurableQueueEntries({ queueDir, tempPrefix:
 
 `id` must be a single safe path segment: non-empty, not dot-prefixed, and made
 from letters, numbers, `_`, `-`, and `.`. Slashes, backslashes, NUL bytes, `.`,
-and `..` are rejected.
+`..`, and Windows reserved device names such as `CON`, `NUL`, and `COM1` are
+rejected on every platform so queue IDs remain portable. Temporary filenames
+continue to suffix reserved stems (for example, `CON.txt` becomes `CON_.txt`).
 
 Use `ackJsonDurableQueueEntry()` after durable processing succeeds and
 `moveJsonDurableQueueEntryToFailed()` when the caller wants to quarantine an

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,86 @@
 # 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
+capability probe; set it before starting the process, rather than changing it
+between tests in one process:
+
+```bash
+pnpm native:build
+pnpm build
+FS_SAFE_TEST_NO_OPENAT2=1 FS_SAFE_NATIVE_MODE=require pnpm test test/linux-openat2-fallback.test.ts test/root-move-noreplace.test.ts test/root-move-native-integration.test.ts test/native-write-containment.test.ts
+```
+
+On Linux, the seccomp harness also exercises the real syscall failure without
+the environment hook. It needs a C compiler and permission to install an
+unprivileged seccomp filter; it affects only its child process:
+
+```bash
+cc test/fixtures/deny-openat2.c -o /tmp/fs-safe-deny-openat2
+/tmp/fs-safe-deny-openat2 ENOSYS node test/fixtures/linux-openat2-fallback.mjs "$PWD/native/fs-safe-native.linux-x64-gnu.node"
+/tmp/fs-safe-deny-openat2 EPERM node test/fixtures/linux-openat2-fallback.mjs "$PWD/native/fs-safe-native.linux-x64-gnu.node"
+```
+
+Use the matching native artifact filename on other Linux architectures/libcs.
+The fixture proves nested moves, collisions, read/write, traversal, symlink and
+hardlink rejection, cached selection, and `helper-unavailable` for strict
+bounded cleanup. Bounded-cleanup success tests require real `openat2`; run the
+full suite with the environment hook unset.
+
 `@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
@@ -158,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.