@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

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

@@ -0,0 +1,334 @@
+# Atomic writes
+
+`@openclaw/fs-safe/atomic` re-exports the lower-level helpers that `root()`'s write methods are built on. Reach for them when you have an absolute path you trust and want sibling-temp + rename without setting up a `Root`, or when you need finer control over `fsync`, mode preservation, or pre-rename hooks.
+
+```ts
+import {
+  replaceFileAtomic,
+  replaceFileAtomicSync,
+  writeTextAtomic,
+  replaceDirectoryAtomic,
+  movePathWithCopyFallback,
+} from "@openclaw/fs-safe/atomic";
+```
+
+## `replaceFileAtomic` / `replaceFileAtomicSync`
+
+Write `content` to a sibling temp file in the destination directory, apply the parent-directory and final file modes through verified descriptors, optionally `fsync` the file descriptor, optionally `fsync` the parent directory after rename, then atomically rename over the destination. No permission change follows a caller-supplied pathname.
+
+On POSIX, the parent is opened with no-follow and directory-only flags, checked against its pre-open identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
+
+Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
+
+```ts
+import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceFileAtomic({
+  filePath: "/srv/workspace/state.json",
+  content: JSON.stringify(state, null, 2),
+  mode: 0o600,
+  syncTempFile: true,
+  syncParentDir: true,
+});
+```
+
+### Options
+
+```ts
+type ReplaceFileAtomicOptions = {
+  filePath: string;                 // destination
+  content: string | Uint8Array;
+  dirMode?: number;                 // parent-directory mode (POSIX; default 0o700)
+  mode?: number;                    // new-file mode (default 0o600)
+  preserveExistingMode?: boolean;   // copy existing mode; default false
+  tempPrefix?: string;              // default ".fs-safe-replace"
+  renameMaxRetries?: number;        // EBUSY retries; default 0
+  renameRetryBaseDelayMs?: number;  // exponential base; default 50
+  copyFallbackOnPermissionError?: boolean; // default false
+  copyFallbackRestore?: "restore-original" | "none"; // default: "none"
+  maxRestoreBytes?: number;          // required with "restore-original"
+  destinationHardlinks?: "reject"; // default unset (no destination nlink policy)
+  renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
+  syncTempFile?: boolean;           // fsync(temp) before rename, or the final file after copy fallback; default false
+  syncParentDir?: boolean;          // fsync(parent) after rename, POSIX only; default false
+  throwOnCleanupError?: boolean;    // report temp cleanup failure; default false
+  beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
+  fileSystem?: ReplaceFileAtomicFileSystem; // injectable fs for tests
+};
+```
+
+### `beforeRename`
+
+Runs after the temp file is fully written and before the rename. Use it to take a backup snapshot, capture the about-to-be-replaced contents, or notify an observer. The helper retains the staged descriptor and exact bigint identity across the hook; replacing, deleting, hardlinking, or changing the temp entry to a non-regular file is rejected before publication:
+
+```ts
+await replaceFileAtomic({
+  filePath: "/srv/workspace/config.toml",
+  content: rendered,
+  beforeRename: async ({ filePath }) => {
+    await fs.copyFile(filePath, `${filePath}.bak`); // snapshot existing
+  },
+});
+```
+
+If `beforeRename` throws, the rename is skipped and the owned temp file is removed — the destination is unchanged. Cleanup unlinks only the exact admitted single-link file; a substitute observed at the temp name is preserved and removed from cleanup authority. The same identity is rechecked before every rename retry, when entering copy fallback, and at the final name after rename. A post-rename verification failure reports the race without rolling back or deleting the published name.
+
+Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
+
+### FUSE mounts and unstable rename identity
+
+Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
+
+This is the same explicit weaker contract available on `Root` writes: cooperating writers are serialized, stale locks fail closed, and mismatched content is rejected after publication without rollback. A same-authority actor that ignores the advisory lock can still substitute another file with identical bytes, so do not use this compatibility policy in directories writable by untrusted same-UID processes.
+
+### `EPERM` and copy fallback
+
+On systems where `rename` fails with `EPERM`/`EEXIST`, pass
+`copyFallbackOnPermissionError: true` to fall back to a non-atomic copy
+replacement. The fallback removes the old destination, opens the replacement
+with exclusive/no-follow flags where the platform supports them, and refuses
+known symlink destinations so it does not write through a replaced destination
+link.
+
+Set `destinationHardlinks: "reject"` when an existing regular-file destination
+must not have aliases. The policy reads `nlink` from a pinned destination
+descriptor, not pathname metadata, before rename and rechecks it in the copy
+fallback.
+
+The default `copyFallbackRestore: "none"` preserves the existing fallback
+contract: a failed copy can leave a partial destination. For state files where
+preserving the old bytes is more important, choose `"restore-original"` and set
+an explicit `maxRestoreBytes` memory budget. If the destination exists, fs-safe
+snapshots it through a pinned descriptor, overwrites and mode-adjusts through
+that same descriptor, and synchronizes the result. Any write, mode, or sync
+failure triggers a byte-and-mode restore and another sync through the same
+descriptor.
+
+Restore failures are `FsSafeError("helper-failed")` values with typed
+`details.cleanup` set to `"restored"` or `"restore-failed"`. An original larger
+than `maxRestoreBytes` fails with `too-large` before mutation. A missing
+destination has no original to restore and follows the exclusive-create copy
+fallback.
+
+### Sync variant
+
+`replaceFileAtomicSync` accepts the same base options, a synchronous
+`beforeRename` callback, and `ReplaceFileAtomicSyncFileSystem`. Use it inside
+synchronous boot paths or test setup code. It returns the same
+`{ method: "rename" | "copy-fallback" }` receipt as the async variant.
+
+## `replaceDirectoryAtomic`
+
+Atomically swap one directory's contents with another, using a temporary backup during the swap.
+
+```ts
+import { replaceDirectoryAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceDirectoryAtomic({
+  stagedDir: "/srv/workspace/staging/snapshot-2026-05-05",
+  targetDir: "/srv/workspace/snapshot",
+});
+```
+
+The helper renames `targetDir` to a generated backup path, renames `stagedDir → targetDir`, then removes the backup. If the second rename fails, it tries to restore the original target before rethrowing.
+Concurrent replacements of the same resolved target are serialized inside the
+current process so their backup, commit, and cleanup phases cannot interleave.
+`backupPrefix`, when supplied, is sanitized as one path prefix and cannot contain
+path separators or NUL bytes; the generated backup tail is randomized.
+
+Use it when callers must see a whole staged tree at the target path. For single-file replacement, `replaceFileAtomic` is the right tool.
+
+## `writeTextAtomic`
+
+Atomic UTF-8 text write with the same secure defaults as `writeJson`: sibling
+temp file, descriptor-bound mode setting and fsync, rename, and parent fsync.
+It delegates to `replaceFileAtomic()` with a smaller call shape. Use it when
+you do not need replacement hooks such as `beforeRename`, `preserveExistingMode`,
+or custom copy-fallback policy.
+
+```ts
+import { writeTextAtomic } from "@openclaw/fs-safe/atomic";
+
+await writeTextAtomic("/srv/workspace/rendered.md", rendered, {
+  mode: 0o600,
+  dirMode: 0o700,
+  trailingNewline: true,
+});
+```
+
+Options:
+
+```ts
+type WriteTextAtomicOptions = {
+  mode?: number;             // file mode (default 0o600)
+  dirMode?: number;          // parent mode (default 0o777 masked by process umask)
+  trailingNewline?: boolean; // append "\n" if missing; default false
+  durable?: boolean;         // default true; false skips temp/parent fsync
+};
+```
+
+`durable: false` keeps the sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability.
+
+## `movePathWithCopyFallback`
+
+Rename a path. If the rename fails with `EXDEV` (cross-device), or `EPERM` on
+Windows, fall back to
+copying into a staged sibling path, renaming that staged path into place, and
+then removing only the source entries that were copied. The fallback avoids
+buffering regular files into memory and does not tighten the destination parent
+directory mode. Staged file modes are applied through their still-open handles.
+If descriptor-bound mode application fails, the staged path is removed and the
+move fails before publication. A transient staged-path cleanup failure retains
+an identity-bound process-exit cleanup retry.
+On POSIX, staged directory modes are applied through no-follow directory
+descriptors; on Windows, Node cannot portably open those descriptors and no
+pathname `chmod` fallback is attempted, so directory modes remain subject to
+Windows' `mkdir(mode)` behavior. Symlink sources are copied as links rather than
+followed, including when the referent is absent; only a source proven to be a
+directory is dereferenced for the destination-descendant guard.
+
+```ts
+import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
+
+await movePathWithCopyFallback({
+  from: "/srv/cache/blob.bin",
+  sourceHardlinks: "reject",
+  to: "/srv/persistent/blob.bin",
+});
+```
+
+Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+The hardlink policy is captured when the move starts. Changing or reusing the
+options object later does not change the policy of an in-flight move.
+`sourceHardlinks: "reject"` performs a recursive preflight capped at 50,000
+entries before any mutation. Because link count and rename cannot be one atomic
+portable operation, this mode always commits a fresh inode/tree through the
+staged-copy route, even on one filesystem. Each regular file is checked again
+after open and after copying, so a post-scan hardlink cannot become the
+published target. A hardlink fails with `FsSafeError("hardlink")`; exceeding
+the preflight cap fails with `FsSafeError("too-large")`.
+If another writer changes source entries during the fallback, the staged copy
+throws `ESTALE` before commit when possible. If the destination has already
+been committed, cleanup still preserves the changed source entries and throws
+`ESTALE`. When allowed source names are hardlinks to the same inode, each owned
+unlink is verified through a remaining manifested alias and its exact resulting
+identity becomes the next cleanup receipt. This accounts for the operation's
+own link-count and ctime changes without suppressing unexpected external
+mutations.
+
+### Mutation authority and publication receipts
+
+Pass `assertBeforeMutation` when a move depends on a revocable lease or another
+caller-owned authorization. The helper captures the callback when called and
+runs it synchronously after asynchronous preparation and identity checks,
+immediately before each rename, source-file or source-symlink unlink, and
+source-directory removal. `assertBeforeRename` remains available for callers
+that only guard publication. When both are set, the rename check runs first,
+then the mutation check, without yielding before dispatch.
+
+```ts
+type MovePathPublicationReceipt = Readonly<{
+  path: string;
+  dev: bigint;
+  ino: bigint;
+}>;
+
+type MovePathWithCopyFallbackOptions = {
+  from: string;
+  sourceHardlinks?: "allow" | "reject";
+  to: string;
+  assertBeforeRename?: () => void;
+  assertBeforeMutation?: () => void;
+  onDestinationPublished?: (receipt: MovePathPublicationReceipt) => void;
+};
+```
+
+Throw to refuse the next mutation. The original error is propagated, including
+errors with `EXDEV` or `EPERM` codes; an authorization failure never starts a
+copy fallback. A genuine rename failure may still require a second authority
+check before publishing the staged copy.
+
+All three callbacks must return `undefined` synchronously. Returning a Promise,
+thenable, or any other value fails with a `TypeError`; rejected asynchronous
+results are consumed. Perform asynchronous policy checks before calling the
+helper and use the authority callback to recheck the current owner at each
+mutation boundary. All callbacks are captured before the first await.
+
+`onDestinationPublished` runs exactly once after a successful rename resolves,
+before awaited post-rename directory checks or source cleanup. It receives a
+frozen receipt with the resolved absolute destination path and the exact bigint
+device/inode identity observed on the rename source before dispatch: the
+original source for a direct rename, or the staged copy for fallback. Failed
+rename attempts never emit receipts. The return contract remains `Promise<void>`.
+
+The receipt records an observed identity, not authorization, durable storage,
+or an atomic guarantee against concurrent pathname replacement. Before recovery,
+recheck caller authority and compare the retained identity with a fresh bigint
+stat of the destination. In particular, unknown Windows device/inode values
+must not be treated as proof of ownership. Do not derive ownership from a new
+post-failure snapshot alone.
+
+A refused rename leaves the source and destination unchanged; any private
+staged copy follows normal cleanup. If publication has already happened, a
+callback error or later verification failure preserves the published destination
+and stops further source cleanup. Revocation during cleanup leaves all
+as-yet-unremoved source entries intact; entries already removed remain removed.
+The caller retains the receipt even if the move later rejects and owns recovery
+from this partial-move state. An observer that throws must retain its receipt
+before throwing if recovery needs it.
+
+These callbacks do not cancel already-dispatched operations or make an external
+lease store atomic with the filesystem. `assertBeforeMutation` guards renames
+and removal of copied source entries; private staging creation, writes, and
+failed-staging cleanup remain owned by the helper. Omitting the new callbacks
+preserves the existing move and source-identity behavior.
+
+## Difference from `root()`
+
+| `Root` methods | `atomic` helpers |
+|---|---|
+| Take relative paths, bound to a `rootDir`. | Take absolute paths, no boundary. |
+| Throw `FsSafeError` with `code`. | Throw `FsSafeError` *or* the underlying `NodeJS.ErrnoException`, depending on failure point. |
+| Atomicity, mode, hooks, fsync are sane defaults. | Caller controls all of the above. |
+| `mkdir`, identity check, hardlink reject built in. | No root boundary; `movePathWithCopyFallback` has explicit `sourceHardlinks` policy, while other helpers expose their own narrower checks. |
+
+Use `Root` when the path is caller-controlled. Use `atomic` when the path is fully under your control and you want explicit knobs.
+
+## Test injection
+
+Both `replaceFileAtomic` and `replaceFileAtomicSync` accept a `fileSystem` option that overrides the small set of `fs` calls they make. Pass a stub in unit tests to assert order, simulate `EPERM`, or capture the temp filename:
+
+```ts
+const ops: string[] = [];
+await replaceFileAtomic({
+  filePath: "/tmp/x",
+  content: "hi",
+  fileSystem: {
+    promises: {
+      ...realFs,
+      writeFile: async (...args) => { ops.push("write"); return realFs.writeFile(...args); },
+      rename: async (...args) => { ops.push("rename"); return realFs.rename(...args); },
+    },
+  },
+});
+```
+
+The synchronous injectable interface has one optional descriptor-mode operation:
+
+```ts
+type ReplaceFileAtomicSyncFileSystem = {
+  // other required operations omitted
+  fchmodSync?: typeof import("node:fs").fchmodSync;
+};
+```
+
+The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. On POSIX, that `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Older adapter literals may continue to include `chmod` or `chmodSync` for source compatibility, but those operations are ignored. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
+
+## See also
+
+- [`root()`](root.md) — when you want method-style writes with the boundary baked in.
+- [JSON files](json.md) — JSON/text helpers built on sibling-temp replacement.
+- [Temp workspaces](temp.md) — for staging-then-swap directory builds.
+- [Errors](errors.md) — code union for failures.

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

@@ -0,0 +1,131 @@
+---
+title: Config
+description: "Process-global defaults for optional fs-safe helpers."
+---
+
+# `@openclaw/fs-safe/config`
+
+Process-global configuration knobs for optional fs-safe helpers. The native helper policy is described in the [native helper policy](native-helper.md); this page is the API reference.
+
+```ts
+import {
+  configureFsSafeNative,
+  configureFsSafeLocks,
+  getFsSafeNativeConfig,
+  getFsSafeLockConfig,
+  type FsSafeLockConfig,
+  type FsSafeNativeConfig,
+  type FsSafeNativeMode,
+} from "@openclaw/fs-safe/config";
+```
+
+These functions are also re-exported from the main entry point. Prefer the subpath when you only need helper configuration and want the smallest import surface.
+
+## `configureFsSafeNative(config)`
+
+```ts
+function configureFsSafeNative(config: Partial<FsSafeNativeConfig>): void;
+
+type FsSafeNativeConfig = {
+  mode: FsSafeNativeMode;
+};
+
+type FsSafeNativeMode = "auto" | "off" | "require";
+```
+
+Set the process-global loading policy. Configure once at startup, before the first filesystem operation. The binding is loaded lazily and the result is cached.
+
+| Mode | Behavior |
+|---|---|
+| `auto` | Default. Prefer the platform binding and use guarded JavaScript when it is unavailable. |
+| `off` | Do not load the binding; use guarded JavaScript deterministically. |
+| `require` | Operations that need the binding raise `FsSafeError("helper-unavailable")` when it cannot load. |
+
+## `getFsSafeNativeConfig()`
+
+```ts
+function getFsSafeNativeConfig(): FsSafeNativeConfig;
+```
+
+Return the effective configuration: programmatic overrides win, then env vars, then the package default (`auto`).
+
+## `configureFsSafeLocks(config)`
+
+```ts
+function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
+
+type FsSafeLockConfig = {
+  staleRecovery: "fail-closed" | "remove-if-unchanged";
+  staleMs?: number;
+  timeoutMs?: number;
+  retry?: FileLockRetryOptions;
+};
+```
+
+Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
+
+`staleRecovery` defaults to `"fail-closed"`. The opt-in `"remove-if-unchanged"` mode requires caller approval and serializes the final snapshot check and unlink with an exclusive `.reclaim` guard. A reclaim guard left by a killed reclaimer fails closed and requires externally coordinated cleanup.
+
+For a daemon that should wait briefly for normal contention but never delete a
+stale owner without per-lock approval:
+
+```ts
+configureFsSafeLocks({
+  staleRecovery: "fail-closed",
+  staleMs: 2 * 60_000,
+  timeoutMs: 15_000,
+  retry: { retries: 30, minTimeout: 50, maxTimeout: 1_000, randomize: true },
+});
+```
+
+These defaults apply to both `acquireFileLock()` / `withFileLock()` and
+`acquireFileLockSync()` / `withFileLockSync()`. Each acquisition resolves
+`retry`, `staleMs`, `staleRecovery`, and `timeoutMs` from the per-call option
+first, then the process configuration, then the package default. Explicit zero
+values are preserved. A per-call `retry` object replaces the configured object
+as a whole; omitted retry fields use package defaults, not configured fields.
+
+Individual lock calls can override any default. Switching the global stale
+recovery mode does not provide the application-owned liveness proof required
+by `shouldRemoveStaleLock`.
+
+## `getFsSafeLockConfig()`
+
+```ts
+function getFsSafeLockConfig(): FsSafeLockConfig;
+```
+
+Return the current sidecar lock defaults.
+
+## Environment variables
+
+The same policy can be set without code:
+
+```bash
+FS_SAFE_NATIVE_MODE=auto      # auto | off | require | true | false | on | 1 | 0 | never | required
+```
+
+`OPENCLAW_FS_SAFE_NATIVE_MODE` is accepted as an alias. Programmatic overrides via `configureFsSafeNative` always win.
+
+### Python-helper migration bridge
+
+Version 0.5 detects the former `FS_SAFE_PYTHON_MODE`, `FS_SAFE_PYTHON`,
+`OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`,
+`OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON` names. It emits one
+`FS_SAFE_PYTHON_DEPRECATED` warning and maps `auto`, `off`, or `require` to the
+same native mode; interpreter paths are ignored. The deprecated
+`configureFsSafePython()` export behaves the same way.
+
+Replace these inputs with `configureFsSafeNative()` or
+`FS_SAFE_NATIVE_MODE` during the 0.5 upgrade. The bridge exists only so shipped
+0.4 configuration fails loudly and maps predictably; it is not a supported
+Python execution path. Follow the [0.5 migration checklist](migrating-to-0.5.md)
+for the full upgrade.
+
+## Related pages
+
+- [Native helper policy](native-helper.md) — when to pick `auto`, `off`, or `require`, and what each mode protects.
+- [File lock](sidecar-lock.md) — the per-resource lock API that consumes lock defaults.
+- [Root API](root.md) — the API whose POSIX hardening the helper backs.
+- [Errors](errors.md) — `helper-unavailable` and `helper-failed`.
+- [Migrating to 0.5](migrating-to-0.5.md) — ordered consumer upgrade checklist.

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

@@ -0,0 +1,180 @@
+# Contributing
+
+The `fs-safe` repo lives at [github.com/openclaw/fs-safe](https://github.com/openclaw/fs-safe). Contributions welcome — issues, bug reports, focused PRs.
+
+## Local setup
+
+```bash
+git clone https://github.com/openclaw/fs-safe.git
+cd fs-safe
+pnpm install
+```
+
+Node 22 or newer. The dev toolchain and lockfile use pnpm; use the package
+manager version declared in `package.json`.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Runs TypeScript compilation and builds the portable Rust TAR parser for
+`wasm32-unknown-unknown`. Contributors need Rust (the native crate's declared
+minimum or newer) and `rustup target add wasm32-unknown-unknown`; Alpine's
+packaged toolchain uses `rust-wasm`. `pnpm archive:wasm` rebuilds just the parser.
+The import-free asset lands at `dist/archive-parser.wasm`; source tests and
+compiled consumers both resolve that generated artifact. Run `pnpm build`
+before source tests in a fresh checkout. Do not commit `dist/` or built WASM.
+Consumers receive the asset in the npm package and need no compiler.
+
+Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
+
+## Test
+
+```bash
+pnpm test
+```
+
+Vitest. Tests live in `test/` and follow `*.test.ts`. Run a single file with:
+
+```bash
+pnpm test test/archive.test.ts
+```
+
+Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
+
+Vitest timeouts do not cancel filesystem promises. Shared fixtures with expensive
+setup use `useSuiteFixture` from `test/helpers/suite-fixture.ts`: setup has a separate
+30-second hook budget, and teardown waits for tracked setup and test work before
+removing directories. Run shared-state corpora sequentially with a deadline per
+payload. Keep child-process liveness limits separate from fixture preparation.
+The Windows CI slow-copy proof runs the real package-copy process-exit test with a
+six-second copy delay, retaining its four-second child deadline:
+
+```bash
+pnpm build
+pnpm test --config scripts/slow-package-copy.config.ts
+```
+
+## Checks
+
+Run the complete repository gate before handoff:
+
+```bash
+pnpm check
+```
+
+This runs the filesystem boundary checks, build, tests, and package
+tarball/import validation.
+
+### Real TAR producers
+
+After installing the freshly packed root (and optionally its freshly built host
+binding) in a disposable consumer, run:
+
+```bash
+pnpm archive:producer-smoke ./consumer off
+pnpm archive:producer-smoke ./consumer require
+```
+
+This uses a child bound to canonical cwd/device/inode running `/usr/bin/tar -czf - .`
+with unchanged stdout, and npm tar, on synthetic Unicode/newline/long-name files,
+then the installed package API for exact payload hashes and bounded reads.
+It also rejects a valid PAX override attached to an invalid raw UTF-8 field.
+The `require` command must resolve the freshly packed native binding; the
+`off` command uses the installed WASM asset. No live user files are read.
+
+### Native consumer installs
+
+The CI Node 24 and native jobs also run `node scripts/device-path-proof.mjs off`
+and `node scripts/device-path-proof.mjs require` against the built package.
+This extracts real ZIP files and checks bounded member reads, preserving reserved
+device-like names on POSIX while rejecting them and ignored-space aliases on
+Windows. It also verifies ordinary secret reads and typed device-path rejection
+without replacing filesystem functions. Run after `pnpm build`, and build the
+host binding with `pnpm native:build` before the `require` case.
+
+After `pnpm build` and a fresh `pnpm native:build`, run `pnpm package:smoke`.
+It packs the real root and host binding, then runs root-only npm and the
+declared pnpm version against a disposable loopback registry. The root's exact
+optional dependencies stay unchanged. Each consumer lives outside the workspace
+with isolated configuration, caches, and stores; the registry never proxies to
+the Internet. The smoke verifies root integrity, consumer-local resolution,
+OS/CPU/libc selection, a native-required SHA-256 operation, and fresh-process
+`auto`/`off` fallbacks and `require` failures for missing bindings and omitted
+optionals. Omitted-optionals installs also verify that all public subpaths can
+be imported, without implying every operation remains available.
+
+Host-only smoke supplies the six foreign packages using their unchanged real
+manifests and clearly marked synthetic, non-executable payloads. Every foreign
+metadata/tarball endpoint is checked before installation, so a missing fixture
+cannot masquerade as successful platform filtering. These temporary fixtures
+never enter `packages/`, release artifacts, or the publish manifest. They prove
+installer filtering, not foreign native compilation or execution. Full release
+collection uses the actual seven collected native tarballs instead. Run it with
+`pnpm package:collect` after assembling all seven real bindings; missing targets
+fail collection. `pnpm package:collect --allow-host-only` exercises the same
+lifecycle boundary locally but proves only the host. Both collection commands
+require the pnpm lifecycle CLI path; direct `node` invocation is unsupported. Archive
+codecs and their dependencies are packed from the installed dependency graph.
+
+PR CI builds and executes four host targets: Linux x64 glibc, Linux x64 musl
+(Alpine), macOS arm64, and Windows x64. The root-only smoke runs on each. The
+seven-target source build matrix runs on release tags; packaging all seven is
+not execution proof for every architecture. The smoke writes manager versions,
+cases, and synthetic-fixture scope to `release-artifacts/consumer-proof.json`.
+
+## Docs
+
+The docs site is rendered recursively from Markdown files under `docs/` by `scripts/build-docs-site.mjs`. Build locally to preview:
+
+```bash
+pnpm docs:site
+open dist/docs-site/index.html
+```
+
+The build validates internal links and embedded anchors. Broken links fail the build — fix them before pushing. Navigation must list every non-excluded Markdown page exactly once: missing, nonexistent, and duplicate entries fail before the build replaces existing site output. The builder and navigation tests share discovery and validation in `scripts/docs-site-navigation.mjs`.
+
+Adding a new doc page:
+
+1. Create `docs/<page>.md`. Use a leading `# Title` heading.
+2. Add the page to the appropriate section in `scripts/docs-site-navigation.mjs` (`sections` array near the top). Nested pages use slash-separated paths relative to `docs/`, such as `guides/example.md`.
+3. Cross-link from `docs/index.md` if it's a major surface.
+4. Run `pnpm test test/docs-site-navigation.test.ts` and re-run the local build.
+
+Internal links use relative `*.md` paths — the builder rewrites them to the rendered HTML. Code fences support GitHub-flavored markdown.
+
+## PRs
+
+Small, focused PRs land faster. The general shape:
+
+- One concern per PR. Bug fixes separate from new APIs.
+- A regression test for every bug fix where the test framework can express it.
+- A changelog entry under `## Unreleased` when behavior visibly changes.
+- For new public APIs: a docs page in `docs/` plus a sidebar entry.
+
+## Releases
+
+Maintainers publish from a protected `vX.Y.Z` tag on `main` through
+`.github/workflows/release.yml`. The workflow requires the package version and a
+dated `CHANGELOG.md` section to match the tag. It builds and publishes all seven
+platform packages before publishing `@openclaw/fs-safe`, verifies every registry
+artifact and provenance statement, and then creates the GitHub release.
+
+Each package needs its own npm trusted-publisher configuration for
+`openclaw/fs-safe` and `release.yml`. A new platform package must be created and
+configured on npm before the first tag that references it; npm trust is
+package-specific and cannot be bootstrapped by the tag workflow itself.
+
+External contributors do not need to do anything beyond getting the pull
+request merged. Maintainers must not publish locally or add npm automation
+tokens.
+
+## Reporting security issues
+
+Suspected security issues belong in private disclosure first. See [`SECURITY.md`](https://github.com/openclaw/fs-safe/blob/main/SECURITY.md) in the repo for the current contact path. Don't open a public issue for a credential-stealing or sandbox-escape bug — coordinate the disclosure first.
+
+## License
+
+By contributing you agree that your contributions are licensed under the project's [MIT license](https://github.com/openclaw/fs-safe/blob/main/LICENSE).