@openclaw/openshell-sandbox 2026.9.6 → 2026.9.7

package/node_modules/@openclaw/fs-safe/docs/sidecar-lock.md

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

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

package/node_modules/@openclaw/fs-safe/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/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,

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

@@ -107,11 +107,44 @@ 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.
+Home-started walks report actual Root-relative paths, such as `home/dir/file`,
+rather than `~/dir/file`. Use `./~/dir` to start at a literal `~` directory.
+An alias within a home-started path is reported under its admitted canonical
+target; ordinary non-home starting aliases retain their caller-supplied spelling.
+
+Entry names remain literal filesystem data, including a directory named `~`
+and its descendants. To reuse an entry path in another Root method without
+home-directory expansion, prefix it with `./`, as in
+`capability.open("./" + entry.relativePath)`.
 
 The default `order: "sorted"` visits each directory's names in lexicographic
 order before descending depth first. It reads and sorts all names in each