@openclaw/signal 2026.9.4 → 2026.9.6

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.

package/node_modules/@openclaw/fs-safe/docs/mutation-policy-proof.md

@@ -0,0 +1,69 @@
+# Hosted mutation-policy proof
+
+The `mutation policy public behavior proof` workflow builds the exact event-head
+package and host addon on Node 24 Linux, macOS, and Windows. Each case executes in
+a fresh process, uses a private temporary fixture, and emits only a bounded,
+canonical receipt. POSIX workers require both real and effective non-root UIDs.
+
+Receipt schema `fs-safe-mutation-policy-proof-v2` deliberately does not describe
+final directory emptiness as a mutation-dispatch count. Root replacement records
+the unchanged contents of the original and replacement parent; denied redirect
+records rejection and unchanged denied/displaced parents. The existing JS mkdir
+counters name their exact child or next component. None counts native syscalls
+or excludes transient mutations that leave no final trace.
+
+## Additional hosted cases
+
+Each POSIX write/create/copy worker, under both native-off and native-require,
+performs an eligible success control, an exact deeper-parent denial after an
+earlier parent is created, a denied redirect after preflight, and a stale-parent
+replacement at the public pre-mkdir authority boundary. Exact directory listings
+and sentinels verify that denied/current/displaced parents contain no prohibited
+child, target, or stage. Copy sources must retain their original bytes.
+
+Redirect injection uses the existing public `@openclaw/fs-safe/test-hooks` subpath
+from `dist`, not a mocked native binding. Only these isolated workers enable
+`NODE_ENV=test`. The exact target and single hook visit are required. The hook is
+after policy preflight but before parent admission; it must not be described as
+a post-parent-admission hook. Stale replacement instead uses the public authority
+callback after child-create policy admission, with an existing sentinel parent
+and a still-missing child. Both implementation files that enforce the following
+freshness check are hash-bound. No unchecked callback ordinal chooses a fault.
+
+Representative POSIX `Root.write` workers refuse authority before the first mkdir,
+after one parent has been created and before the next mkdir, before staging, and
+immediately before publication. Epoch selection uses actual fixture state. The
+publication refusal requires a real single-link, caller-owned mode-0600 stage
+containing the complete payload while the destination still contains its original
+sentinel. The same rejection object must escape, no callback may follow refusal,
+and the owned stage must be gone before fixture teardown.
+
+Windows workers exercise buffer `Root.write` through a stable final-file symlink,
+then refuse before stage creation for a missing destination, before publishing a
+complete stage to that still-missing destination, and before publishing to an
+existing symlink-selected destination. Missing destinations must remain absent at
+every authority callback and after refusal. The workers verify alias binding,
+destination preservation, complete single-link stages, and cleanup before fixture
+teardown. The default native-off and explicit
+`verify-content-with-lock` native-require configurations both select the existing
+Windows JS buffer writer. In native-require mode, the compatibility route loads
+the addon to publish its retained sidecar lock through `Root.create`; the payload
+writer remains JS. The receipt does not mislabel this as native payload
+publication or evidence that content-verification fallback or lock contention
+was exercised.
+
+## Bounds and interpretation
+
+The receipt remains below 32 KiB, each worker has a 15-second process timeout and
+4-KiB stdout limit, and the proof step has a six-minute outer timeout. Worker I/O
+and cleanup retain their existing deadlines. The canonical pending/failed receipt
+is preserved if setup, a worker, provenance validation, or emission fails.
+Source, built modules, the public test seam, harness helper, contract tests, and
+host addon are hashed and checked again after workers.
+
+These are deterministic representative observations, not an exhaustive race proof
+or syscall audit. Existing hash-bound internal tests remain complementary for
+other awaited-admission, receipt-refresh, and observation-failure interleavings.
+Windows root replacement and POSIX-specific pinned routes are not claimed on
+Windows. Hosted CI and exact artifact inspection are required before relying on
+new receipts; the proof supplies no performance release clearance.

package/node_modules/@openclaw/fs-safe/docs/native-helper.md

@@ -0,0 +1,177 @@
+---
+title: Native helper policy
+description: "How fs-safe loads its platform-specific native filesystem primitives and how auto, require, and off affect guarded fallbacks."
+---
+
+# Native helper policy
+
+`@openclaw/fs-safe` declares seven exact-version optional packages for Linux
+x64/arm64 (glibc or musl), macOS x64/arm64, and Windows x64. Package-manager
+OS, CPU, and libc filters install only the matching package. The loader requires
+that package lazily, without runtime downloads, postinstall scripts, or a
+consumer Rust build.
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });    // default
+configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
+configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
+```
+
+The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_SAFE_NATIVE_MODE`. Accepted values are `auto`, `off`, `require`, `true`, `false`, `on`, `never`, `required`, `1`, and `0`.
+
+## Modes
+
+| Mode | Behavior |
+|---|---|
+| `auto` | Prefer native primitives when the current platform package loads; otherwise use supported fallbacks and reject native-only operations. |
+| `off` | Do not load a native package. Use supported fallbacks and reject native-only operations deterministically. |
+| `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
+
+Plain TAR, gzip, zstd, and bzip2 extraction and bounded entry reads use a bundled,
+import-free WASM build of the same Rust TAR parser when native support is absent
+or disabled. Zstd/bzip2 codecs are bundled alongside the parser; gzip uses Node's
+built-in decoder. These archive fallbacks require no runtime interpreter or
+download. `off` disables the optional native filesystem helper, not the bundled
+WASM. `auto` prefers native and does not retry a native operation failure through
+WASM; `require` still rejects an unavailable native binding. ZIP fallback still
+requires optional `jszip`. `inspectTarArchive()` remains limited to plain TAR
+and gzip.
+
+Windows security operations can use the package's readable PowerShell/C# scripts
+in `auto` and `off`, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+
+On Bun macOS/Linux, the [runtime path adapter](install.md#bun-runtime) uses the
+same Rust addon for system canonicalization in `auto` and `require`. No JIT is
+needed. With `off` or a missing addon in `auto`, Bun's own resolver retains its
+path and permission limitations. Canonicalization in `require` fails with
+`helper-unavailable` if the addon or its canonicalizer is missing, including
+when admitting a temp workspace. Containment and identity checks stay intact.
+
+Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
+
+Native-created descriptors retain their originating native close operation through
+normal and error cleanup, including later mode changes. Node-created roots and
+directory handles keep Node's close operation, and borrowed handles keep their
+caller-owned lifetime. This preserves Node worker-thread descriptor tracking
+without unmanaged-descriptor warnings. A helper missing native close support is
+unavailable before descriptor allocation.
+
+Close retained native resources and let in-flight operations finish before
+forcibly terminating a worker. Native-created descriptors are not registered
+with Node's automatic worker-exit cleanup; `Worker.terminate()` can leave them
+open until process exit. The native close operation handles explicit cleanup,
+not forced worker termination.
+
+[`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
+remain available in every mode. Their default compatible cleanup uses guarded
+JavaScript quarantine when owned native tree removal is unavailable.
+`cleanupSafety: "require-bounded"` instead rejects before child creation unless
+no-replace quarantine plus descriptor-relative owned-tree removal are available.
+On Linux, admission probes the exact `openat2` child-directory flags, including
+`RESOLVE_NO_XDEV`, at runtime. An unavailable or denied probe selects compatible
+JavaScript cleanup even in global `require` mode; `require-bounded` rejects before
+child creation.
+Already-created strict workspaces retain their binding
+and descriptors across later mode changes.
+
+[`stageFileInDirectory()`](staged-file.md) always requires native support on
+Linux/macOS and rejects before creation when off, unavailable, or missing the
+required capability. Windows is unsupported for this lifecycle. This does not
+change the mode policy of existing fallback-capable APIs.
+
+## Native boundary
+
+The internal Darwin descriptor ACL inspector requires its matching native
+capability in both `auto` and `require`; `off`, a missing package, or an older
+binding without `inspectDarwinAcl` rejects with `helper-unavailable`. Inspection
+failure or malformed facts reject with `permission-unverified`; there is no
+mode-bit or pathname fallback for this capability. Clone admission uses a fused
+descriptor-bound metadata and ACL observation, then compares immutable receipts
+with fresh no-follow pathname identity fences; pathnames never authorize ACL
+state. The payload ACL-clear readback is part of that fused observation. Once
+a clone payload exists, normalization and verification failures become terminal
+`EIO` errors (with the underlying status and detail retained), not capability
+signals that permit an ordinary-copy retry. Checked cleanup cannot undo that
+terminal classification.
+This addition does not change other APIs' native-mode or permission contracts.
+
+The native layer exposes policy-free filesystem mechanisms: beneath-root
+open/mkdir/link, replace and no-replace rename, identity reads, archive decode/execution,
+clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor calls. The TypeScript
+layer owns policy, retries, filters, budgets, modes, cleanup, error
+normalization, and the decision to fall back.
+
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
+- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
+
+`replaceDirectoryAtomic()` requires `renameNoReplaceWithIdentity` before it
+creates a missing target parent. On POSIX the dedicated entry point keeps the
+existing pre-dispatch exact receipt fence but dispatches direct-child names
+through the retained parents without another receipt, duplicate, reopen, or
+macOS `F_GETPATH`; the documented final source-name substitution window remains
+there. Deeper names retain guarded parent traversal.
+
+Native primitives back create-only and replacing pinned writes, no-clobber
+`Root.move()`, async sidecar creation, guarded publication, archive acceleration,
+and direct Windows ACL operations. Windows secure-file reads require
+descriptor-bound owner/DACL facts. In native `auto` or `off` mode, a missing
+binding or capability can use a packaged PowerShell script that inspects the
+borrowed handle. Raw owner/DACL inspection and private-directory creation also support
+this fallback, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+Each capability emits a path-free warning once per process and adds PowerShell
+startup and compilation overhead per call. Native `require` rejects missing
+capabilities, and native operation failures remain terminal. No-clobber moves fail with
+`helper-unavailable` when descriptor-relative parent admission or the atomic
+no-replace rename is unavailable; they never use a check followed by a replacing
+rename. Equivalent JavaScript paths remain available for documented
+fallback-capable features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
+for the exact difference.
+
+The guarded JavaScript mutation path is detection-based, not containment-atomic.
+If a same-privilege peer can replace a writable parent after its identity guard
+but before Node resolves a pathname mutation, the mutation can land outside the
+intended root before the post-operation guard throws. Select `require` rather
+than `auto` or `off` when that concurrent attacker is part of the threat model.
+
+`openBeneath()` returns `{ fd, containment }`. `containment` is
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
+Windows. Public JavaScript root open/read/writable results also expose the
+field and report `"best-effort"`; the label reports mechanism, not policy.
+
+## Migration from the Python helper
+
+Version 0.5 removes the Python worker and interpreter-path selection. The mode
+contract is unchanged, so migrate startup configuration directly:
+
+| Python helper configuration | Native replacement |
+|---|---|
+| `configureFsSafePython({ mode: "auto" })` | `configureFsSafeNative({ mode: "auto" })` |
+| `configureFsSafePython({ mode: "off" })` | `configureFsSafeNative({ mode: "off" })` |
+| `configureFsSafePython({ mode: "require" })` | `configureFsSafeNative({ mode: "require" })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, and the OpenClaw interpreter-path aliases | Remove; prebuilt bindings do not use an interpreter path |
+
+In 0.5, `configureFsSafePython` and the legacy Python environment names
+remain only as an upgrade bridge. On the first config read they emit one
+`DeprecationWarning` with code `FS_SAFE_PYTHON_DEPRECATED`, state the mapped
+native mode, and then apply that mode. A legacy interpreter path without an
+explicit mode maps to `auto` and the path itself is ignored. Native config has
+the normal precedence over legacy environment config.
+
+There is no silent alias and no Python execution fallback. The bridge exists
+only to make shipped 0.4 configuration visible and predictable while the
+consumer performs its 0.5 upgrade.
+
+## Related pages
+
+- [Config](config.md)
+- [Security model](security-model.md)
+- [Writing](writing.md)
+- [File locks](sidecar-lock.md)
+- [Durability](durability.md)
+- [Migrating to 0.5](migrating-to-0.5.md)
+- [Migrating to 0.6](migrating-to-0.6.md)