@openclaw/matrix 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/docs/test-hooks.md

@@ -0,0 +1,110 @@
+---
+title: Test hooks
+description: "Internal-only injection hooks used by the fs-safe test suite. Active only when NODE_ENV=test or VITEST=true."
+---
+
+# `@openclaw/fs-safe/test-hooks`
+
+Internal injection points the `fs-safe` test suite uses to deterministically reproduce open/lstat races. They are exposed as a public subpath so downstream test suites can reuse the same harness, but they are **not** part of the supported runtime API.
+
+```ts
+import {
+  getFsSafeTestHooks,
+  __setFsSafeTestHooksForTest,
+  type FsSafeTestHooks,
+} from "@openclaw/fs-safe/test-hooks";
+```
+
+## When the hooks are active
+
+Hooks are only honored when one of the following is true:
+
+- `process.env.NODE_ENV === "test"`
+- `process.env.VITEST === "true"`
+
+Calling `__setFsSafeTestHooksForTest(hooks)` outside of those environments throws. `getFsSafeTestHooks()` returns `undefined` when no hooks are registered, regardless of the environment.
+
+## Shape
+
+```ts
+type FsSafeTestHooks = {
+  afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
+  beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
+  afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterOpenedPathIdentityCheck?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterRootReadPathResolution?: (filePath: string) => Promise<void> | void;
+  beforeRootReadFinalFence?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterRootReadFinalPathIdentityCheck?: (filePath: string, handle: FileHandle) => void;
+  beforeArchiveOutputMutation?: (operation: "mkdir" | "chmod", targetPath: string) => Promise<void> | void;
+  beforeFileStorePruneDescend?: (dirPath: string) => Promise<void> | void;
+  beforeFileStoreSyncPrivateWrite?: (filePath: string) => void;
+  beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
+  beforeRootStatObservation?: (targetPath: string) => Promise<void> | void;
+  beforeRootStatInitialObservation?: (targetPath: string) => Promise<void> | void;
+  beforeRootListObservation?: (directoryPath: string, withFileTypes: boolean) => Promise<void> | void;
+  afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
+  beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+  beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
+  beforeTrashMove?: (targetPath: string, destPath: string) => void;
+  afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
+  beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
+};
+```
+
+| Hook | Fires when |
+|---|---|
+| `afterPreOpenLstat` | A pre-open `lstat` has just resolved. Use this to swap a path between validation and open. |
+| `beforeOpen` | The library is about to call `open(path, flags)`. Use this to inject a TOCTOU window. |
+| `afterOpen` | An open just succeeded. Use this to mutate state before the post-open identity check runs. |
+| `afterOpenedPathIdentityCheck` | A standalone local-file or absolute copy-source descriptor matches its pathname and the generic opened-path resolver is about to run. Root reads use their final admission hooks instead. |
+| `afterRootReadPathResolution` | A Root read path was resolved and has not yet entered local-file open admission. |
+| `beforeRootReadFinalFence` | A Root read descriptor passed pre-open/descriptor identity and hardlink checks and is about to enter its single final root/path/canonical-path/root admission fence. |
+| `afterRootReadFinalPathIdentityCheck` | The final pathname-to-descriptor comparison passed and the second root check has not run. This hook is synchronous-only. |
+| `beforeArchiveOutputMutation` | Archive staging is about to create a directory or apply a mode. |
+| `beforeFileStorePruneDescend` | File-store pruning is about to descend into a directory. |
+| `beforeFileStoreSyncPrivateWrite` | A synchronous private-store write is about to mutate its target. |
+| `beforeRootFallbackMutation` | A guarded JS root fallback is about to mkdir, move, or remove. |
+| `beforeRootStatObservation` | `Root.stat()` admitted its exact target and parent and is about to collect returned metadata. |
+| `beforeRootStatInitialObservation` | `Root.stat()` admitted its exact parent and is about to inspect the target for the first time. |
+| `beforeRootListObservation` | `Root.list()` admitted its exact selected directory and is about to collect names and optional metadata. |
+| `afterPinnedWriteFallbackRename` | A fallback rename committed and post-commit identity checks have not run yet. |
+| `beforeSiblingTempWrite` | A sibling temp file exists and its writer is about to run. |
+| `beforeSidecarLockSnapshotOpen` | A sidecar lock was inspected and is about to be opened for a bounded snapshot read. |
+| `beforeTrashMove` | Trash handling is about to move the target. |
+| `afterPublishTargetCreated` | Exclusive publication created its target and final fences have not run yet. |
+| `beforePublishDirectorySync` | Publication verified the target and is about to sync its parent directory. |
+
+Hooks typed `Promise<void> | void` may be sync or async and are awaited.
+Hooks used by synchronous code paths are typed `void` and must not return a
+promise.
+
+## Usage
+
+```ts
+import { afterEach, beforeEach } from "vitest";
+import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
+
+beforeEach(() => {
+  __setFsSafeTestHooksForTest({
+    beforeOpen: async (filePath) => {
+      // swap a victim file with a symlink right before fs-safe opens it
+      await replaceWithSymlink(filePath);
+    },
+  });
+});
+
+afterEach(() => {
+  __setFsSafeTestHooksForTest(undefined);
+});
+```
+
+Always clear the hooks in `afterEach` so a stuck hook does not leak across tests.
+
+## Stability
+
+The shape can grow new optional fields between minor versions. Treat the surface as test-only and do not rely on it from production code.
+
+## Related pages
+
+- [Testing](testing.md) — broader notes on testing against `fs-safe`.
+- [Security model](security-model.md) — the races these hooks help reproduce.

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

@@ -0,0 +1,399 @@
+# 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
+throws. Production code must not import this subpath.
+
+```ts
+import {
+  __setFsSafeTestHooksForTest,
+  type FsSafeTestHooks,
+} from "@openclaw/fs-safe/test-hooks";
+```
+
+The double-underscore prefix is a deliberate "hands off" signal: production code should never import this module. ESLint or your equivalent linter should flag it.
+
+## When to reach for hooks
+
+- Reproduce a TOCTOU race deterministically: simulate a symlink swap between resolve and open, or between write and rename.
+- Force guarded JavaScript behavior without removing platform packages from your runners.
+- Inject latency to test cancellation/timeout paths.
+
+If you don't need to inject a race, you don't need hooks — most tests should drive the library through normal calls and assert on observable behavior.
+
+## Hooks API
+
+```ts
+type FsSafeTestHooks = {
+  afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
+  beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
+  afterOpen?: (filePath: string, handle: import("node:fs/promises").FileHandle) => Promise<void> | void;
+  afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
+  beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
+  // Additional archive, store, root-fallback, temp, and trash race hooks are
+  // documented on the focused Test hooks reference page.
+};
+
+function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;
+function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
+```
+
+Hooks are called at well-defined points in the library's hot paths:
+
+- **`afterPreOpenLstat`** — runs after the pre-open `lstat`. A common use is to swap the path's target via `fs.symlink`/`fs.unlink` to drive a TOCTOU race.
+- **`beforeOpen`** — runs before `fs.open` with the exact flags the root read path will use.
+- **`afterOpen`** — runs after the file handle is opened. Useful to wrap handle methods or inject a size race before a stream is consumed.
+- **`afterPublishTargetCreated`** — runs after exclusive publication created a target but before its final fences.
+- **`beforePublishDirectorySync`** — runs after target verification and immediately before strict parent sync; useful for exercising `onSyncFailure`.
+
+`__setFsSafeTestHooksForTest(undefined)` clears all hooks. Always clean up between tests.
+
+## Example: simulate a TOCTOU swap
+
+```ts
+import { describe, it, beforeEach, afterEach, expect } from "vitest";
+import { mkdtemp, mkdir, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(os.tmpdir(), "fs-safe-toctou-"));
+  await writeFile(path.join(dir, "real.txt"), "secret");
+  await writeFile(path.join(dir, "decoy.txt"), "decoy");
+});
+afterEach(async () => {
+  __setFsSafeTestHooksForTest(undefined);
+  await rm(dir, { recursive: true, force: true });
+});
+
+it("rejects a swap between resolve and open", async () => {
+  const fs = await root(dir, { symlinks: "reject" });
+
+  __setFsSafeTestHooksForTest({
+    afterPreOpenLstat: async (absPath) => {
+      // swap real.txt for a symlink to decoy.txt right before the open
+      await unlink(absPath);
+      await symlink(path.join(dir, "decoy.txt"), absPath);
+    },
+  });
+
+  await expect(fs.read("real.txt")).rejects.toMatchObject({
+    name: "FsSafeError",
+    code: expect.stringMatching(/symlink|path-mismatch/),
+  });
+});
+```
+
+The `code` may be `symlink` (caught at open by `O_NOFOLLOW`) or `path-mismatch` (caught by the post-open identity check) depending on platform — both are correct refusals.
+
+## Example: force guarded JavaScript fallback behavior
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+beforeEach(() => {
+  configureFsSafeNative({ mode: "off" });
+});
+
+afterEach(() => {
+  configureFsSafeNative({ mode: "auto" });
+});
+
+it("runs without the native helper", async () => {
+  const fs = await root(dir);
+  await fs.write("file.txt", "ok");
+  await expect(fs.readText("file.txt")).resolves.toBe("ok");
+});
+```
+
+## Cleanup is mandatory
+
+Hooks set by `__setFsSafeTestHooksForTest` persist across tests until explicitly cleared. Always clear in `afterEach` (or your test framework's equivalent) — leaked hooks will silently change behavior in unrelated tests and cause maddening intermittent failures.
+
+```ts
+import { afterEach } from "vitest";
+import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
+
+afterEach(() => {
+  __setFsSafeTestHooksForTest(undefined);
+});
+```
+
+A global hook clear in your test setup file is a good safety net.
+
+See the [complete Test hooks reference](test-hooks.md) for every optional hook.
+
+## Patterns for testing fs-safe-using code
+
+You usually don't need hooks. Most tests follow this shape:
+
+```ts
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { root } from "@openclaw/fs-safe";
+
+let dir: string;
+let fs: Awaited<ReturnType<typeof root>>;
+
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(os.tmpdir(), "my-feature-"));
+  fs = await root(dir, { symlinks: "reject", hardlinks: "reject", mkdir: true });
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+it("writes and reads through the boundary", async () => {
+  await fs.write("notes/today.txt", "hello");
+  expect(await fs.readText("notes/today.txt")).toBe("hello");
+});
+```
+
+For tests that need a private temp workspace, [`withTempWorkspace`](temp.md) makes the setup-and-teardown story trivial.
+
+## 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
+pnpm check
+```
+
+Run only the security boundary corpus while iterating on root/path/archive/temp hardening:
+
+```sh
+pnpm test:security
+```
+
+Run the static primitive guard after changing low-level filesystem helpers:
+
+```sh
+pnpm lint:fs-boundary
+```
+
+It catches the specific raw fallback patterns that previously led to
+check-then-use bugs, such as direct copy-to-destination fallback and sync temp
+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.
+- [`root()`](root.md) — the surface most tests will exercise.
+- [Temp workspaces](temp.md) — `withTempWorkspace` for cleanup-on-exit test directories.

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

@@ -0,0 +1,123 @@
+# Timing
+
+`withTimeout(promise, timeoutMs, labelOrOptions?)` is a small helper for putting a wall-clock ceiling on an async operation. It rejects with a synthetic timeout error after `timeoutMs` and clears its internal timer when the wrapped promise settles first.
+
+```ts
+import { withTimeout } from "@openclaw/fs-safe/advanced";
+```
+
+## Signature
+
+```ts
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  labelOrOptions?: string | {
+    label?: string;
+    message?: string;
+    createError?: () => Error;
+  },
+): Promise<T>;
+```
+
+If `timeoutMs` is `0`, negative, `Infinity`, or `NaN`, the helper is a no-op and simply awaits the original promise.
+
+Finite delays above Node's single-timer limit (2,147,483,647 ms, about 24.9 days) are scheduled in bounded intervals without expiring early. The timer is still cleared if the wrapped promise settles first.
+
+## Examples
+
+### Simple ceiling
+
+```ts
+import { withTimeout } from "@openclaw/fs-safe/advanced";
+
+const buf = await withTimeout(
+  fs.readFile("/srv/big.bin"),
+  5_000,
+  "read big.bin",
+);
+```
+
+If the read doesn't resolve within 5 seconds, the returned promise rejects with `Error: read big.bin timed out after 5000ms`. The underlying `fs.readFile` continues until Node finishes it — `withTimeout` does not cancel the wrapped work, only the wait.
+
+### Custom message
+
+```ts
+await withTimeout(work(), 5_000, {
+  message: "build did not finish in time",
+});
+```
+
+### Custom error factory
+
+```ts
+class BuildTimeout extends Error {}
+
+await withTimeout(work(), 5_000, {
+  createError: () => new BuildTimeout("build timeout (5s)"),
+});
+```
+
+`createError` is called when the timer fires; the returned error is what the promise rejects with. Use this when callers branch on `instanceof` or want a custom `cause`.
+
+## Cancellation
+
+`withTimeout` does **not** abort the wrapped operation when the timer fires — it just stops waiting. If you need real cancellation, the wrapped operation must opt into an `AbortSignal` itself:
+
+```ts
+const controller = new AbortController();
+const timer = setTimeout(() => controller.abort(), 5_000);
+
+try {
+  const res = await fetch(url, { signal: controller.signal });
+  // ...
+} finally {
+  clearTimeout(timer);
+}
+```
+
+For the common "I want a deadline AND cancellation" shape, use `AbortSignal.timeout(ms)` directly — it's the standard library's answer and handles both at once.
+
+## Patterns
+
+### Bound a credential refresh
+
+```ts
+const fresh = await withTimeout(
+  refreshToken(currentRefresh),
+  5_000,
+  "refresh oauth token",
+);
+await writeSecretFileAtomic({ rootDir, filePath, content: JSON.stringify(fresh) });
+```
+
+### Compose with archive extraction
+
+```ts
+import { extractArchive } from "@openclaw/fs-safe/archive";
+
+await extractArchive({
+  archivePath,
+  destDir,
+  kind: "zip",
+  timeoutMs: 30_000,
+});
+```
+
+`extractArchive` already takes `timeoutMs` and carries its own abort signal/deadline checks — you don't need to wrap it. Reach for `withTimeout` for operations that don't carry their own timeout knob.
+
+### Disable in tests
+
+When unit-testing flaky code, you might want to disable the timeout. Pass `0`:
+
+```ts
+await withTimeout(work(), process.env.NODE_ENV === "test" ? 0 : 5_000, "work");
+```
+
+Better, gate it from the caller — `withTimeout(p, 0, ...)` returns the promise as-is.
+
+## See also
+
+- [Archive extraction](archive.md) — `extractArchive` already takes `timeoutMs`.
+- [File lock](sidecar-lock.md) — retry policy is a different form of bounded waiting.
+- [`AbortSignal.timeout`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static) — standard-library cancellation when you need to *abort*, not just *give up*.