@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/docs/staged-file.md

@@ -49,7 +49,7 @@ remain with the caller.
 
 ```ts
 function stageFileInDirectory(options: {
-  directory: string | DirectoryReceipt;
+  directory: string | DirectoryReceipt<Stats | BigIntStats>;
   content: string | Uint8Array;
   mode?: number;
 }): Promise<StagedFile>;
@@ -65,6 +65,11 @@ interface StagedFile extends AsyncDisposable {
 Strings are UTF-8. `mode` is the requested **published** mode and defaults to
 `0600`; exact final modes, including `000`, are supported. The unpublished file
 stays at `0600` throughout preparation and any awaited application checks.
+The retained descriptor's actual mode is checked before writing payload bytes,
+by `assertCurrent()`, and before publication; a successful but ineffective
+`chmod` fails with `insecure-permissions`. Final mode verification after
+publication can fail with a `published` receipt while preserving the completed
+file. These are POSIX mode checks, not ACL or ownership admission.
 After rename succeeds and the published entry passes identity validation, the
 owner applies the requested mode through its retained file descriptor. Content
 was synchronized during preparation; publication always synchronizes the parent.
@@ -76,8 +81,9 @@ Creation uses an exclusive, no-follow, close-on-exec open of a generated direct
 child name. Writes use that descriptor. Inspection uses non-following metadata
 operations, never a potentially blocking reopen of the leaf.
 
-A supplied directory receipt must still match at admission. Its numeric
-identity must be exactly representable; ambiguous identity fails closed.
+A supplied directory receipt must still match at admission. Caller receipts can
+carry numeric `Stats` or exact `BigIntStats`; untracked numeric identities must
+be exactly representable. Ambiguous identity fails closed.
 Returned receipts are frozen descriptive snapshots, not mutable authority.
 Changing a supplied receipt after admission cannot retarget the lifecycle.
 
@@ -105,9 +111,13 @@ touching descriptors.
 basename. Empty, dot, dotdot, separators, absolute paths, NUL, control characters,
 drive-relative spellings, and the stage's own name are rejected.
 
-With `overwrite: false`, publication is genuine kernel no-replace rename; a
-collision leaves both names unchanged and raises `FsSafeError("already-exists")`.
-The stage may then be cleaned or published under another name. With
+With `overwrite: false`, publication is genuine kernel no-replace rename.
+A native collision raises `FsSafeError("already-exists")`, but ordinary errno
+does not prove that a remote rename never committed. Native rename failures
+without explicit pre-dispatch provenance therefore report `indeterminate`:
+cleanup preserves names and closes descriptors, and further publication rejects.
+Only rejection before rename dispatch leaves the stage eligible for cleanup or
+publication under another name. With
 `overwrite: true`, publication is plain atomic replacement. Neither route
 copies. Both source and destination resolve through the retained original
 parent, with checks immediately before rename and after publication.

package/node_modules/@openclaw/fs-safe/docs/staged-symlink.md

@@ -0,0 +1,124 @@
+---
+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 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
+`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/node_modules/@openclaw/fs-safe/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
@@ -89,7 +91,15 @@ claim before publication. If another consumer acknowledged, quarantined, or
 replaced that claim, the migration rejects with `FsSafeError("path-mismatch")`
 and leaves the newer generation or failed evidence intact. A stale migration
 rejects both single and batch loads; ordinary callback failures retain their
-existing single-load rejection and batch-skip behavior.
+existing single-load rejection and batch-skip behavior. A caller or migration
+error with code `ENOENT` is still a failure, not a missing queue entry; only a
+claim that is absent or disappears before reading returns `null` from a single load.
+
+If closing the read descriptor also fails, the original read, validation,
+callback, or migration failure keeps precedence, including non-Error rejection
+values. A close failure without an earlier failure is reported through the same
+loader policy: direct reads and single loads reject, while batch loads skip it
+unless migration has started.
 
 On Windows, migration releases its read pin once at this publication boundary
 because an open target can block replacement. It rechecks the exact pathname

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

@@ -22,15 +22,37 @@ 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
 from their first exact security snapshot; if a restrictive umask changes that
 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
@@ -155,12 +177,15 @@ uses guarded pathname-recursive removal. This fallback never recursively
 removes the public workspace name, but it is not atomic conditional deletion: a
 same-privilege peer that discovers and replaces the private quarantine after
 verification can still redirect the final pathname removal.
+If admitting a cleanup parent fails and closing its descriptor also fails,
+creation rejects with both failures in an `AggregateError`. This does not select
+compatible fallback or retry the indeterminate descriptor close.
 
 Set `cleanupSafety: "require-bounded"` when that concurrent attacker is in scope.
 Creation then requires native no-replace directory rename, native owned-tree
 removal, and a readable retained parent descriptor **before** child creation.
 On POSIX, the final requested `dirMode` must also include owner read
-and search (`(dirMode & 0o500) === 0o500`). Preflight failure throws
+and search (`(dirMode & 0o500) === 0o500`). An unavailable capability throws
 `FsSafeError("helper-unavailable")` without creating a child or calling a scoped
 callback. The child descriptor is opened
 while the new directory still has its private creation mode, before an explicit
@@ -221,9 +246,15 @@ A missing workspace returns `"missing"`. A replacement observed at the public
 name before quarantine returns `"identity-mismatch"` when the parent is stable;
 an ambiguous parent returns `"indeterminate"`. After successful removal,
 repeated cleanup returns `"missing"` without touching a recreated public name.
-Other statuses remain stable. Operational removal errors propagate and later
-cleanup returns `"indeterminate"` without retrying. Disposal and scoped helpers
-ignore returned statuses, while manual cleanup exposes the result.
+Other statuses remain stable. Compatible recursive-removal failures propagate
+the exact thrown value, including `undefined`, `null`, `false`, positive or
+negative numeric zero, bigint zero, an empty string, and `NaN`; they are never
+inferred from value identity or truthiness. Uncertain quarantine and
+retained-parent checks instead return
+`"indeterminate"`. After a propagated removal failure, later cleanup returns
+`"indeterminate"` without retrying. Disposal and scoped helpers ignore returned
+statuses, while manual cleanup exposes the result. A terminal descriptor-close
+failure retains its existing precedence if it also fails during settlement.
 
 When cleanup is part of a retention or audit decision, inspect the receipt
 instead of treating cleanup as fire-and-forget:
@@ -410,6 +441,12 @@ files, hardlinks, and changes between the pre-open pathname, opened descriptor,
 and current pathname are rejected. The callback must finish and close its
 writer before returning. Its return value is preserved as `result`.
 
+Each option is read once before directory creation starts, including both
+callbacks, the temp prefix, isolation, directory and file modes, and sync flags.
+Later changes to the options object do not change the in-flight operation.
+`writeTemp` and `resolveFinalPath` retain their shared internal staging object
+as the callback receiver.
+
 Generated temp filenames suffix Windows reserved-device basenames on every
 platform. Before either an ordinary or isolated producer runs, the completed staging
 name must be a nonempty, non-dot path component with no POSIX or Windows
@@ -536,6 +573,11 @@ await writeViaSiblingTempPath({
 If `replaceFileAtomic` does what you need, prefer that. Use
 `writeViaSiblingTempPath` when the producer needs a concrete temp pathname but
 the final destination still needs root-boundary checks.
+
+The root, target, callback, fallback filename, and temp prefix are read once
+before setup. Later changes to the parameters do not affect the in-flight
+operation; `writeTemp` retains the original parameters object as its receiver.
+
 Its private workspace uses `tempFile()`'s compatible identity-aware cleanup.
 It preserves replacements observed before removal, but retains the final
 pathname-recursive-removal gap described above; this helper does not expose
@@ -625,7 +667,12 @@ recursive-`mkdir` winner is inspected as an untrusted existing directory.
 Broad-mode repair also uses a pinned descriptor; there is no pathname chmod.
 
 Repair and finalization require a known nonnegative safe-integer UID and exact
-bigint device, inode, owner, mode, and directory-type facts. They open with
+bigint device, inode, owner, mode, and directory-type facts. Device and inode
+identities accept Node's signed 64-bit stat representation, including negative
+values down to `-(1n << 63n)`; inode zero remains invalid. Previously supported
+nonnegative device and positive inode adapter values remain supported without
+an upper cap. Values are compared exactly as received: signed and unsigned
+encodings of the same bits are not treated as equal. They open with
 `O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK`, verify the descriptor and
 current directory entry against the initial receipt before `fchmod`, then
 verify identity, permissions, and write/search access again before closing.

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

@@ -1,5 +1,154 @@
 # Testing
 
+## Coverage gates
+
+The coverage workflow measures `src/**/*.ts` with V8 on Linux, macOS, and
+Windows, then merges their counters before enforcing the thresholds in
+`vitest.config.ts`: lines 94%, statements 92%, functions 95%, and branches 89%.
+`pnpm test:coverage:collect` disables per-OS thresholds so platform-only paths
+are credited by their own OS; `pnpm test:coverage:merge` requires all three
+reports and enforces the combined gate. The DACL batch child entrypoint also
+runs in-process in a unit test so its protocol and budget handling are measured.
+
+The Linux Rust job uses pinned `cargo-llvm-cov` and a pinned nightly compiler
+for line and branch instrumentation. It combines native crate unit tests with
+TS native suites running the instrumented addon, and exports LCOV plus separate
+unit-only and combined summaries. The Rust line threshold is 71%; addon execution
+must also increase covered Rust lines beyond the unit tests. Only native crate sources compiled on Linux are measured;
+macOS/Windows Rust implementations and the archive WASM crate are outside this
+report. Run `pnpm build` followed by `bash scripts/native-coverage.sh` on Linux
+after installing the toolchain versions specified in `coverage.yml`.
+
+Percentages complement behavioral gates: mutation-policy proof, nightly watch
+stress, and platform lanes are equally important. High coverage cannot establish
+root confinement, race safety, event delivery, or bounded resource retirement.
+
+## 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. The full qualification remains manual. A smaller nightly campaign runs outside
+per-PR CI; it can also be dispatched with `watch-stress.yml`.
+
+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 60 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 churn growth after warmup, and at most 32 MiB lifecycle growth after 3,000
+cycles. Soak collects garbage twice at every checkpoint, limits collected-heap
+and external-memory growth to 8 MiB after minute five, and requires the fitted
+RSS slope over minutes 31–60 to stay at or below 1 MiB/minute. The runner launches
+soak with `--expose-gc` automatically, including through `--scenario all`.
+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.
+
+### Nightly workload
+
+The nightly workflow runs on `ubuntu-latest` (x64), `ubuntu-24.04-arm`,
+`macos-15` (arm64), `macos-15-intel`, and the Windows latest 16-core runner,
+using Node 24 and freshly built native bindings. Each job has a 25-minute
+budget, uploads one JSON result per scenario (including failures), and fails
+if any scenario fails. Remaining scenarios still run after a failure. Only
+Linux runs the kernel-limits scenario automatically.
+
+The same harness accepts these environment overrides; defaults remain the
+full qualification workload. Child processes inherit the settings, which are
+recorded in every JSON result.
+
+| Environment variable | Default | Nightly |
+| --- | ---: | ---: |
+| `FS_SAFE_STRESS_SCALE_DIRECTORIES` (25 files each) | 2,000 | 400 (10,000 files) |
+| `FS_SAFE_STRESS_FANOUT` (maximum subscriptions) | 256 | 64 |
+| `FS_SAFE_STRESS_CHURN_SECONDS` | 300 | 60 |
+| `FS_SAFE_STRESS_LIFECYCLE_CYCLES` | 10,000 | 1,000 |
+| `FS_SAFE_STRESS_IDLE_SECONDS` | 600 | 120 |
+| `FS_SAFE_STRESS_SOAK_MINUTES` (minimum 10) | 60 | 10 |
+
+Soaks shorter than 30 minutes keep the hard peak-RSS, collected-heap, and external-memory
+growth gates, but report the second-half RSS slope and its limit without using it
+to pass or fail (`memory.rssSlopeGated: false`): [#701](https://github.com/openclaw/fs-safe/pull/701)
+found that V8 capacity expansion and allocator retention can raise RSS while live memory stays flat.
+Runs of 30 minutes or longer enforce the same second-half slope limit; only runs of
+at least 60 minutes report `memory.qualification: true`.
+Lifecycle memory is sampled across ten intervals, with
+the first two excluded as warm-up; idle's Linux wakeup bound scales with the
+requested duration (three per minute). Adversarial cases remain unchanged.
+
+## 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-parity.test.ts 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"
+FS_SAFE_TEST_OPENAT2_FILTER=/tmp/fs-safe-deny-openat2 FS_SAFE_NATIVE_MODE=require pnpm test test/linux-openat2-parity.test.ts
+```
+
+Use the matching native artifact filename on other Linux architectures/libcs.
+The fixtures prove in-root alias operations and policy parity, nested moves,
+collisions, read/write, traversal and escaping-link rejection, 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. PR CI's `Native check
+(linux-x64-no-openat2)` runs the native Node suites and watch proofs with the
+hook set. It replaces the four bounded-cleanup success suites and quarantine
+success proof with the explicit refusal fixture above. XFS tree-clone proof
+requires the same openat2/NO_XDEV primitive and runs in the ordinary Linux
+lanes. Bun's full compatibility
+suite remains in the normal native lanes, because it includes bounded cleanup.
+
 `@openclaw/fs-safe/test-hooks` exposes test-only injection points. Registration
 is allowed only when `process.env.NODE_ENV === "test"` or
 `process.env.VITEST === "true"`; registering a non-empty hook set elsewhere
@@ -158,6 +307,14 @@ 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 qualification remains manual, with the smaller nightly
+campaign above.
+
 Run the full local gate before handoff:
 
 ```sh
@@ -182,6 +339,59 @@ workspace reads that bypass pinned file descriptors.
 
 `pnpm check` also runs `pnpm lint:file-size`. New source and test files should stay under 500 lines. Existing larger files have explicit budgets in `scripts/check-file-size.mjs`; do not increase those budgets as part of unrelated work.
 
+## Watch memory diagnosis
+
+The original soak rule rejected more than 64 MiB RSS growth after minute five.
+That outcome remains in `memory.legacyRss`, with its original limit and pass/fail
+value; it is no longer the soak pass criterion. Static guarded poll scans alone
+reproduced growth from 72 to 181 MiB RSS while collected heap stayed near 7–8 MiB:
+V8 expanded its almost-empty young generation to 128 MiB, with 103 MiB physically
+committed. A diagnostic run limiting that space ended at 85 MiB RSS with the
+same live heap. The normal harness keeps Node's default nursery sizing.
+
+The 60-minute qualification separates this capacity warm-up from the later RSS
+trend. The measured Linux event run had under 1 MiB collected-heap drift and a
+0.55 MiB/minute second-half RSS slope; its final ten-minute RSS range was 1.60 MiB.
+The 8 MiB live-memory allowance and 1 MiB/minute RSS slope leave measurement
+margin while rejecting retained growth and continued rapid RSS growth. The
+512 MiB peak ceiling is unchanged. Native allocation leaks need independent
+accounting/profiling too: the investigation found a much smaller cleanup-hook
+context leak even when registrations, pending sets, and TSFN counters retired.
+
+Build the native addon and package from the same revision, then run each control
+in a fresh Node process on a disposable machine:
+
+```sh
+node --expose-gc scripts/watch-memory.mjs --arm events --minutes 60 --output .artifacts/events
+node --expose-gc scripts/watch-memory.mjs --arm none --minutes 30 --output .artifacts/none
+node --expose-gc scripts/watch-memory.mjs --arm poll --minutes 30 --output .artifacts/poll
+node --expose-gc scripts/watch-memory.mjs --arm lifecycle --minutes 30 --output .artifacts/lifecycle
+node --expose-gc scripts/watch-memory.mjs --arm steady --minutes 30 --output .artifacts/steady
+```
+
+`events` and `poll` combine low-rate edits, a 10,000-operation burst every fifth
+minute, and subscription cycling. `steady` omits cycling; `lifecycle` omits
+writes. `none` drives the same writer and consumer cache using explicit synthetic
+invalidations, without constructing subscriptions. That arm is an allocation
+control, not evidence of watcher correctness. Every arm checks its consumer
+cache against an independent filesystem walk at each checkpoint.
+
+The diagnostic runner emits JSONL to stdout and `memory.jsonl` in its output
+directory. Each minute includes all five `process.memoryUsage()` fields before
+and after collection, V8 heap-space capacity, Linux `smaps_rollup`, operation and
+guarded-read counts, and live/created/destroyed native watch allocations.
+`--gc none` measures the same workload without forced collection. `--snapshots`
+writes V8 snapshots at minutes 5 and 30; use a separate run because snapshots
+perturb memory usage. On macOS, `--tools` saves `vmmap --summary` and `leaks`
+reports at minutes 5, 30, and 60. `--smoke` is a short calibration, explicitly
+marked in output; it is not a duration-qualified soak.
+
+The native allocation getter is internal and requires `NODE_ENV=test` or
+`VITEST=true`; the runner sets the former. After close, it requires no live
+registrations, pending sets, callback payloads, or thread-safe functions.
+Diagnostic success establishes correctness and retirement; it does not classify
+an RSS curve as a leak or automatically approve a memory budget.
+
 ## See also
 
 - [Security model](security-model.md) — what the boundary is supposed to defend; design tests around the same threats.

package/node_modules/@openclaw/fs-safe/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,
@@ -128,6 +134,8 @@ type RootOptions = {
 ## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
 
 ```ts
+import type { CopyCloneMode, RootCopyPublicationReceipt } from "@openclaw/fs-safe";
+
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
 type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity" | "mutationSymlinks"> & {
   encoding?: BufferEncoding;
@@ -135,6 +143,11 @@ type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutatio
 };
 type RootCopyOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "maxBytes" | "mkdir" | "mode" | "mutationSymlinks"> & {
   sourceHardlinks?: "reject" | "allow";
+  overwrite?: boolean;
+  clone?: CopyCloneMode;
+  signal?: AbortSignal;
+  preserveSourceMode?: boolean;
+  onDestinationPublished?: (receipt: RootCopyPublicationReceipt) => void;
 };
 type RootOpenWritableOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mkdir" | "mode" | "mutationSymlinks"> & {
   writeMode?: "replace" | "append" | "update";
@@ -150,8 +163,17 @@ type RootAppendOptions = RootWriteOptions & {
 type RootMoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
   overwrite?: boolean;
 };
-type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
-type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
+type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+  recursive?: boolean;
+  force?: boolean;
+  order?: "filesystem" | "sorted";
+  maxEntries?: number;
+  maxDepth?: number;
+  signal?: AbortSignal;
+};
+type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+  private?: boolean;
+};
 ```
 
 Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.