@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,225 @@
+# JSON files
+
+`@openclaw/fs-safe/json` is the standalone JSON surface: strict and lenient read variants plus atomic JSON writes.
+
+```ts
+import {
+  tryReadJson,
+  readJson,
+  readJsonIfExists,
+  readJsonSync,
+  tryReadJsonSync,
+  readRootJsonSync,
+  readRootJsonObjectSync,
+  readRootStructuredFileSync,
+  writeJson,
+  writeJsonSync,
+  JsonFileReadError,
+} from "@openclaw/fs-safe/json";
+```
+
+## Three reads, three failure shapes
+
+Same input, three distinct contracts — pick the one whose error story matches your call site:
+
+```ts
+await readJson<T>("./manifest.json");      // throws JsonFileReadError on missing or invalid
+await readJsonIfExists<T>("./cache.json"); // returns null on missing; throws on invalid
+await tryReadJson<T>("./optional.json");   // returns null on missing or invalid
+```
+
+| Helper | Missing file | Invalid JSON |
+|---|---|---|
+| `readJson` | throws | throws |
+| `readJsonIfExists` | `null` | throws |
+| `tryReadJson` | `null` | `null` |
+
+Use `readJson` when missing-or-malformed is a programmer error you want to surface immediately. Use `readJsonIfExists` when "file not there" is normal but malformed bytes should still page someone. Use `tryReadJson` when neither outcome should crash the caller.
+
+`JsonFileReadError` carries `cause` so you can inspect whether the underlying failure was an `ENOENT`, a `SyntaxError`, or something else.
+
+On Windows, filesystem path inputs reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`; ordinary colon-bearing POSIX names remain valid.
+Standalone JSON writers preserve their released support for an ordinary
+drive-relative destination by anchoring its leading drive designator at entry
+without normalizing the remaining suffix. Any additional colon is still
+rejected before filesystem access.
+Strict standalone readers retain `JsonFileReadError` and expose the
+`invalid-path` rejection as its cause, lenient `tryReadJson*` calls return
+`null`, and root-bounded readers report an `open`/`validation` failure.
+
+## Reading
+
+### `readJson<T>(filePath, options?)`
+
+Async strict reader. Throws `JsonFileReadError` on missing or invalid input. The cast is unchecked — validate the shape with your own schema (zod, valibot, …) if it came from an untrusted source.
+
+```ts
+const manifest = await readJson<Manifest>("./manifest.json");
+const smallManifest = await readJson<Manifest>("./manifest.json", {
+  maxBytes: 256 * 1024,
+});
+```
+
+All standalone readers accept `{ maxBytes?: number }`. When set, the read is
+incremental and consumes no more than `maxBytes + 1` bytes before rejecting, so
+file growth after the initial stat cannot cause an unbounded allocation.
+
+### `readJsonIfExists<T>(filePath, options?)`
+
+Async semi-lenient reader. Returns `null` if the file is missing; throws `JsonFileReadError` if the file exists but cannot be parsed.
+
+```ts
+const cache = (await readJsonIfExists<Cache>("./cache.json")) ?? freshCache();
+```
+
+### `tryReadJson<T>(filePath, options?)`
+
+Async lenient reader. Returns `null` for any failure (missing, unreadable, invalid). The "no fuss" sibling.
+
+```ts
+const optional = (await tryReadJson<Settings>("./settings.json")) ?? defaults;
+```
+
+### `readJsonSync<T>(filePath, options?)`
+
+Synchronous strict reader. Throws `JsonFileReadError` on missing or invalid input, matching the async `readJson` contract.
+
+### `tryReadJsonSync<T>(pathname, options?)`
+
+Synchronous, generic, lenient. Returns `T | null`. Useful in boot paths where you want a typed result without async.
+
+## Root-bounded structured reads
+
+Use the root-bounded readers when you already have a trusted root directory and
+a caller-controlled relative path, but you only need one synchronous structured
+read instead of a full `root()` handle.
+
+```ts
+const result = readRootJsonObjectSync({
+  rootDir: "/safe/workspace",
+  relativePath: "plugin/openclaw.plugin.json",
+  boundaryLabel: "plugin manifest",
+  maxBytes: 256 * 1024,
+});
+
+if (!result.ok) {
+  // reason is "open", "parse", or "invalid"
+  throw new Error(result.reason);
+}
+
+console.log(result.value);
+```
+
+`readRootJsonSync()` parses any JSON value. `readRootJsonObjectSync()` only
+accepts objects. `readRootStructuredFileSync()` accepts a custom parser and
+validator so callers can layer JSON5, TOML, YAML, or domain-specific validation
+without making `fs-safe` depend on those formats.
+
+## Writing
+
+### `writeJson(filePath, value, options?)`
+
+Async atomic JSON write. `JSON.stringify(value, null, 2)` + sibling-temp + rename. Defaults to file mode `0o600`.
+
+```ts
+await writeJson("./state.json", state, { trailingNewline: true });
+```
+
+Options:
+
+```ts
+type WriteJsonOptions = {
+  mode?: number;             // file mode (default 0o600)
+  dirMode?: number;          // mode for parent dirs created on demand
+  trailingNewline?: boolean; // append "\n" if missing (default false)
+  durable?: boolean;         // default true; false skips temp/parent fsync
+};
+```
+
+`durable: false` preserves atomic temp-file replacement but skips the temp-file
+and parent-directory `fsync` calls. Use it only for reconstructible JSON state
+where lower latency matters more than crash-durability.
+
+### `writeJsonSync(pathname, data)`
+
+Synchronous variant. It pretty-prints with two spaces, appends a newline,
+creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
+directory best-effort. A retained staging descriptor carries the exact bigint
+identity through rename and file-mode tightening. Publication and cleanup never
+adopt a substituted temporary file: a changed identity, type or link count rejects
+the write and leaves the replacement untouched. A swap detected after publication
+also rejects without deleting or changing the replacement. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+compatibility path removes the existing destination and retries the staged-file
+rename, so that fallback is temporarily non-atomic while retaining the staged
+file's `0600` mode; use the async `writeJson()`/`replaceFileAtomic()` surfaces
+when fallback policy must be explicit.
+
+Its private sibling temporary name is independent of the destination basename,
+so staging does not lengthen a valid destination filename.
+
+```ts
+writeJsonSync("./prefs.json", { theme: "dark" });
+```
+
+For atomic text writes, use [`writeTextAtomic`](atomic.md) from `@openclaw/fs-safe/atomic`. For in-process serialization, use `createAsyncLock` from the advanced surface, or prefer [`jsonStore`](json-store.md) when you want a JSON-specific read-modify-write helper.
+
+## Common patterns
+
+### Read-modify-write
+
+```ts
+const state = (await readJsonIfExists<State>("./state.json")) ?? initialState();
+state.lastRun = Date.now();
+await writeJson("./state.json", state, { mode: 0o600, dirMode: 0o700 });
+```
+
+### Atomic with secure mode
+
+For credentials or other sensitive JSON, write at mode `0o600`:
+
+```ts
+await writeJson("./auth.json", token, { mode: 0o600, dirMode: 0o700 });
+```
+
+For higher-assurance secrets, prefer the dedicated [secret-file helpers](secret-file.md) — they create the parent directory at `0o700` if missing.
+
+### Strict load on boot
+
+```ts
+let manifest: Manifest;
+try {
+  manifest = await readJson<Manifest>("./manifest.json");
+} catch (err) {
+  if (err instanceof JsonFileReadError) {
+    console.error("manifest unreadable:", err.cause);
+    process.exit(1);
+  }
+  throw err;
+}
+```
+
+### Concurrent readers, single writer
+
+```ts
+const state = await readJsonIfExists<State>("./state.json");
+// missing returns null; malformed JSON still throws
+```
+
+## Error reference
+
+| Throw / return | When |
+|---|---|
+| `null` from `tryReadJson` / `tryReadJsonSync` | Any read or parse failure. |
+| `null` from `readJsonIfExists` | File is missing; invalid or unreadable input still throws. |
+| `JsonFileReadError` | `readJson` or `readJsonIfExists` saw unreadable or invalid input. Inspect `cause`. |
+| Native `NodeJS.ErrnoException` | Lower-level fs errors not wrapped. |
+
+## See also
+
+- [JSON store](json-store.md) — a single-file state wrapper with explicit per-call fallback (`readOr` / `updateOr`) and optional sidecar locking.
+- [Atomic writes](atomic.md) — lower-level sibling-temp replacement helpers.
+- [Secret files](secret-file.md) — JSON-or-text writes with mode 0600 in mode 0700 dirs.
+- [Private file-store mode](private-file-store.md) — root-bounded JSON+text state stores.
+- [File lock](sidecar-lock.md) — cross-process coordination.

package/node_modules/@openclaw/fs-safe/docs/local-roots.md

@@ -0,0 +1,150 @@
+# Local roots
+
+The local-roots helpers accept a file path plus a list of trusted absolute
+directories and return the first canonical root that contains the file. Use
+them when configuration may name one of several approved media, cache, or
+workspace roots.
+
+```ts
+import {
+  readLocalFileFromRoots,
+  resolveLocalPathFromRootsSync,
+} from "@openclaw/fs-safe/advanced";
+```
+
+## Input shape
+
+Both helpers take one options object. `filePath` may be absolute, home-relative,
+relative to the current working directory, or a local `file://` URL. Relative
+inputs are resolved exactly as Node resolves them; they are not searched as a
+basename under each root.
+
+```ts
+type LocalRootsInputOptions = {
+  filePath: string;
+  roots: readonly string[]; // trusted absolute paths, checked in order
+  label?: string;           // used in validation errors
+};
+```
+
+Roots may use `~` or local `file://` spellings, but each resolved root must be
+absolute. Existing root symlinks are canonicalized before containment is
+checked. Invalid root entries throw `FsSafeError("invalid-path")`; an invalid
+`file://` input throws `Error`. A path that is valid but does not fall inside
+any usable root returns `null`.
+
+## `resolveLocalPathFromRootsSync(options)`
+
+```ts
+type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
+  allowMissing?: boolean; // default false
+  requireFile?: boolean;  // default false
+};
+
+type LocalRootsPathResult = {
+  path: string; // canonical candidate path
+  root: string; // canonical containing root
+};
+```
+
+For an existing upload:
+
+```ts
+import { resolveLocalPathFromRootsSync } from "@openclaw/fs-safe/advanced";
+
+const r = resolveLocalPathFromRootsSync({
+  filePath: "/srv/uploads/photo.jpg",
+  roots: ["/srv/uploads", "/srv/cache"],
+  requireFile: true,
+});
+
+if (!r) throw new Error("photo is outside the configured roots");
+console.log(r.path); // canonical path to photo.jpg
+console.log(r.root); // canonical /srv/uploads
+```
+
+By default the candidate must exist. `allowMissing: true` instead canonicalizes
+the nearest existing ancestor and validates the missing tail, which is useful
+when selecting a future output location. `requireFile: true` rejects existing
+directories and other non-file leaves. A missing suffix begins only at a
+component that does not exist: dangling symlinks, descendants of dangling
+symlinks, and candidates whose existing ancestors cannot be canonicalized are
+rejected rather than treated as safe missing paths.
+
+Filesystem path inputs retain symlinks and parent components until boundary
+resolution, including after home expansion. A followed `link/../file` resolves
+the parent of the link's target; default reads reject the link instead of
+normalizing it away. File URLs retain the URL parser's normal path semantics.
+An existing non-directory component cannot be traversed further, including by
+`..`; the helpers reject that input instead of selecting a different file.
+
+## `readLocalFileFromRoots(options)`
+
+The asynchronous helper opens the candidate through the matched [`Root`](root.md),
+so no-follow, identity, hardlink, device-path, and byte-limit checks happen at
+the read itself.
+Link policies are captured once before root initialization and reused for every
+candidate, so replacing options while a read is pending cannot weaken admission.
+
+```ts
+type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
+  hardlinks?: "reject" | "allow";
+  maxBytes?: number;
+  nonBlockingRead?: boolean;
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
+};
+
+type LocalRootsReadResult = ReadResult & {
+  root: string; // canonical containing root
+};
+```
+
+```ts
+const r = await readLocalFileFromRoots({
+  filePath: "/srv/uploads/photo.jpg",
+  roots: ["/srv/uploads", "/srv/cache"],
+  maxBytes: 8 * 1024 * 1024,
+});
+if (!r) throw new Error("photo is missing, unreadable, or outside the roots");
+process.stdout.write(r.buffer);
+```
+
+The helper returns `null` when no configured root can be opened or no safe read
+succeeds. This intentionally collapses missing, outside-root, and per-root read
+failures; use a single `Root` directly when the caller must distinguish those
+outcomes. Omitting `maxBytes` preserves `Root`'s 16 MiB default.
+
+## File URL and Windows-path companions
+
+The advanced surface also exports the normalization helpers used around this
+API:
+
+```ts
+import {
+  assertNoWindowsNetworkPath,
+  basenameFromMediaSource,
+  hasEncodedFileUrlSeparator,
+  isWindowsDriveLetterPath,
+  isWindowsNetworkPath,
+  safeFileURLToPath,
+  trySafeFileURLToPath,
+} from "@openclaw/fs-safe/advanced";
+```
+
+- `safeFileURLToPath(fileUrl)` parses a local file URL and refuses remote hosts
+  or paths that decode to Windows network paths.
+- `trySafeFileURLToPath(fileUrl)` returns `undefined` instead of throwing.
+- `isWindowsDriveLetterPath()` and `isWindowsNetworkPath()` classify Windows
+  absolute and network spellings.
+- `assertNoWindowsNetworkPath()` throws for a network path on Windows.
+- `basenameFromMediaSource()` extracts a best-effort filename from a URL, data
+  URI, or path.
+- `hasEncodedFileUrlSeparator()` detects percent-encoded slash or backslash
+  spellings.
+
+## See also
+
+- [`root()`](root.md) — use when one trusted root should preserve individual
+  failure codes.
+- [Path helpers](path.md) — lexical and canonical containment primitives.
+- [`pathScope()`](path-scope.md) — result-shaped single-root validation.

package/node_modules/@openclaw/fs-safe/docs/migrating-to-0.5.md

@@ -0,0 +1,205 @@
+---
+title: Migrating to 0.5
+description: "Ordered checklist for moving a 0.4 consumer from the Python helper to native mode and adopting the 0.5 API contracts."
+---
+
+# Migrating from 0.4 to 0.5
+
+Use this checklist from top to bottom. Version 0.5 replaces the Python worker,
+changes the default archive mode policy, and adds explicit contracts for
+publication, walking, locks, secrets, and native-only features. Nothing in this
+guide requires a Rust toolchain: all supported native binaries are prebuilt.
+Current releases install the matching exact-version optional platform package.
+
+## 1. Update the package and runtime
+
+- Run on Node.js 22 or newer.
+- Update `@openclaw/fs-safe` and regenerate every lock or shrinkwrap file your
+  deployment consumes.
+- Keep optional dependencies enabled if you want JavaScript ZIP/TAR support.
+  Native loading no longer depends on Python. Keep optional dependencies enabled
+  for the matching native package and JavaScript ZIP/TAR decoders. An install
+  that omits them can still import fs-safe, but native-only features and missing
+  JS archive decoders fail with actionable errors.
+
+If you call `resolveRootPath()` or `resolveRootPathSync()` directly, upgrade to
+0.5: versions through 0.4.7 could approve an in-root symlink traversal that
+resolved outside the root. `root()` handles were not affected. See the
+[affected versions and exposure](security-model.md#affected-versions-exposure).
+
+## 2. Replace Python helper configuration
+
+Change startup configuration before the first filesystem operation:
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });
+```
+
+| Remove from 0.4 | Use in 0.5 |
+|---|---|
+| `configureFsSafePython({ mode })` | `configureFsSafeNative({ mode })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, pinned-Python aliases | Nothing; prebuilt native binaries do not use an interpreter |
+
+The old names warn once and map `auto`, `off`, or `require` so a shipped 0.4
+deployment does not silently change policy. Interpreter paths are ignored and
+Python is never spawned. Treat that warning as an upgrade diagnostic, not as a
+second supported helper path.
+
+Choose the production mode deliberately:
+
+- `auto` keeps guarded JavaScript fallbacks when a binding is unavailable.
+- `off` makes fallback testing deterministic.
+- `require` fails with `helper-unavailable` instead of weakening an operation
+  that expected native support.
+
+See [Native helper policy](native-helper.md) and
+[Native architecture](native.md).
+
+## 3. Audit every archive call
+
+The 0.5 default is `entryModes: "clamp"`. Directories become `0o755`; files
+become `0o644` or `0o755` when owner-execute was archived. Set
+`entryModes: "preserve"` explicitly only if your 0.4 consumer intentionally
+relied on archived rwx bits. Setuid, setgid, sticky bits, and archived ownership
+are never restored.
+
+```ts
+await extractArchive({
+  archivePath: uploadPath,
+  destDir: restoreRoot,
+  timeoutMs: 30_000,
+  entryModes: "clamp",
+  entryFilter: (entry) =>
+    entry.path.startsWith("snapshot/cache/") ? "skip" : "extract",
+  onFiltered: "skip-entry",
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+    maxMetaEntryBytes: 1024 * 1024,
+    maxEntryPathComponents: 64,
+  },
+});
+```
+
+Returning `"skip"` rejects the archive unless `onFiltered: "skip-entry"` is
+explicit. Zstd and bzip2 TAR required native support in version 0.5; current
+versions also use bundled WASM codecs in `off` or missing-native `auto`, through
+the same guarded TAR pipeline. ZIP fallback still requires optional JSZip.
+Catch `ArchiveLimitError` by its code, including
+`archive-entry-path-components-exceeds-limit` for deep implicit-directory
+attacks. See [Archive extraction](archive.md).
+
+## 4. Pick a publication failure policy
+
+`publishFileExclusive()` never replaces an existing target. Choose a strategy
+and decide what a post-create directory-sync failure means to your application:
+
+```ts
+await publishFileExclusive({
+  sourcePath: stagedArchive,
+  targetPath: finalArchive,
+  strategy: "link-or-copy",
+  onSyncFailure: "preserve",
+});
+```
+
+`rollback` is the default: an unchanged target created by this call is removed
+when directory sync throws. `preserve` keeps a complete but possibly
+non-durable target and reports `cleanup: "preserved"` plus
+`directorySync: { status: "failed", code? }` in the typed error. Backup
+archives commonly need `preserve`; transactional protocols that expose only
+durably committed names usually want `rollback`. See
+[Directory durability](durability.md).
+
+## 5. Replace recursive scans with an explicit walk policy
+
+Use `Root.walk()` for caller-controlled relative paths. Every examined entry
+consumes the budget even when filtered:
+
+```ts
+for await (const entry of workspace.walk("memory", {
+  maxDepth: 12,
+  maxEntries: 50_000,
+  symlinkPolicy: "skip",
+  entryFilter: (entry) =>
+    entry.kind === "directory" && entry.relativePath.endsWith("/.git")
+      ? "skip-subtree"
+      : "include",
+  onDirectoryError: "skip-and-report",
+})) {
+  if (entry.kind === "directory-error") {
+    reportIncompleteSubtree(entry.relativePath, entry.error);
+    continue;
+  }
+  indexEntry(entry);
+}
+```
+
+The default directory-error policy remains `throw`. See
+[Directory walking](walk.md).
+
+## 6. Adopt the focused concurrency and secret APIs
+
+- Use `acquireFileLockSync()` only in synchronous boot or migration code; retry
+  waits block the thread. Request-serving paths should use `withFileLock()`.
+- Remove the `allowReentrant` boolean from async file-lock options. If a logical
+  holder intentionally nests acquisition, pass the same operation-scoped
+  `reentrantOwner` string to each acquisition; different or missing owners
+  contend normally. Never replace the boolean with a process-wide constant.
+  Locked and unlocked `jsonStore` mutations serialize by canonical file path
+  and do not opt into lock reentrancy; nested same-file mutations from an update
+  callback fail with `store-reentrant-update`, so return the complete value from
+  the outer callback instead.
+- Use `createSecretFileAtomic()` for first-writer-wins credentials and catch
+  `secret-exists`; use `writeSecretFileAtomic()` only when replacement is the
+  intended protocol.
+- Async `readSecretFile()` is strict; `tryReadSecretFile()` returns `undefined`
+  only for missing or blank content and still rejects suspicious files.
+- Check `tempWorkspace.cleanup()` results when ownership matters;
+  `identity-mismatch` deliberately preserves a replacement path.
+
+See [File locks](sidecar-lock.md), [Secret files](secret-file.md), and
+[Temp workspaces](temp.md).
+
+## 7. Gate native-only features
+
+Version 0.5 required native support for `createPrivateDirectory()`. Current
+releases also support a packaged PowerShell script in native `auto` and `off`
+modes, retaining its creation-time protected DACL. Check the
+[Windows security fallback prerequisites](install.md#windows-security-fallback)
+before relying on this route. The API remains Windows-only, explicit native
+`require` rejects a missing binding or capability, and native operation failures
+remain terminal.
+`strategy: "rename-noreplace"` remains native-only. Current zstd/bzip2 extraction
+and bounded reads have bundled WASM fallbacks, while explicit native `require`
+remains strict. Test unavailable native-only operations instead of assuming
+installation always succeeds.
+
+## 8. Run both behavior families in CI
+
+For each consumer workflow that matters:
+
+1. Run once with `FS_SAFE_NATIVE_MODE=auto` on every supported OS.
+2. Run once with `FS_SAFE_NATIVE_MODE=off` to prove the JavaScript fallback.
+3. Run native-required or native-only cases with `FS_SAFE_NATIVE_MODE=require`.
+4. Exercise archive traversal/link/depth limits, publication sync failure, and
+   partial-walk reporting with production-shaped fixtures.
+
+For downstream staging and backup consumers:
+
+- [ ] Replace private whole-file hashing with `sha256File(path | FileHandle)`
+      from `durability`; native mode keeps digest work off the event loop and
+      the JavaScript fallback remains streaming.
+- [ ] If Windows trust policy depends on exact principals, consume
+      `readOwnerAndDacl()` from `permissions`, reject incomplete/null/remote
+      descriptors as your policy requires, skip inherit-only ACEs where
+      appropriate, and apply the application's own SID allowlist.
+
+The [Testing](testing.md) page documents the test hooks and mode setup used by
+fs-safe itself.

package/node_modules/@openclaw/fs-safe/docs/migrating-to-0.6.md

@@ -0,0 +1,48 @@
+---
+title: Migrating to 0.6
+description: "Upgrade checklist for the platform-native package split."
+---
+
+# Migrating from 0.5 to 0.6
+
+Version 0.6 moves native bindings out of the root `@openclaw/fs-safe` tarball
+and into exact-version platform packages. This removes unrelated operating
+system and architecture binaries from each installation.
+
+## Keep optional dependencies enabled for native mode
+
+Package managers select one binding by OS, CPU, and Linux libc. A normal
+install needs no command change:
+
+```bash
+pnpm add @openclaw/fs-safe
+```
+
+If a deployment currently installs 0.5 with `--omit=optional`, `--no-optional`,
+or an equivalent lockfile policy, change that policy before upgrading when it
+uses native mode `require` or any native-only feature. Version 0.5 kept its
+binding in the root tarball; version 0.6 intentionally does not.
+
+Omitting optional dependencies remains supported for fallback-capable APIs in
+`auto` mode. It disables native-only features such as retained-directory staging
+and atomic `rename-noreplace`. Native mode `require`
+reports `helper-unavailable` when the matching package is absent or incompatible.
+Zstd/bzip2 TAR extraction and bounded reads required the binding in version 0.6;
+current versions also support bundled WASM codecs in `auto` and `off` through the
+same guarded TAR pipeline. ZIP fallback still requires optional JSZip.
+Windows private-directory creation required the binding in version 0.6; current
+releases also support [packaged Windows security scripts](install.md#windows-security-fallback)
+in `auto` and `off` mode while preserving the creation-time protected DACL.
+
+## Deployment checklist
+
+1. Remove any option or policy that omits optional dependencies when native
+   support is required.
+2. Regenerate every lockfile or shrinkwrap file consumed by deployment.
+3. Verify that the lock contains the matching `@openclaw/fs-safe-*` package.
+4. Run a native-required operation on every deployed OS/libc target.
+5. Keep an `FS_SAFE_NATIVE_MODE=off` lane when the guarded JavaScript fallback
+   is part of the application contract.
+
+No Rust toolchain, postinstall build, or runtime download is introduced. See
+[Native helper policy](native-helper.md) for the exact fallback boundary.