@openclaw/fs-safe 0.4.7 → 0.5.1

package/docs/sidecar-lock.md

@@ -42,6 +42,9 @@ function withFileLock<T, TPayload>(
 ): Promise<T>;
 
 function createFileLockManager(key: string): FileLockManager;
+
+function acquireFileLockSync<TPayload>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>): FileLockSyncHandle;
+function withFileLockSync<T, TPayload>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>, fn: () => T): T;
 ```
 
 `managerKey` is an optional identifier used to keep state isolated across multiple lock domains in the same process. Use distinct keys for distinct domains (`"snapshot"`, `"compact"`, `"build"`). If omitted, fs-safe derives one from the target path.
@@ -56,7 +59,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
   staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
-  allowReentrant?: boolean;              // if this process already holds it, increment a count instead of failing
+  reentrantOwner?: string;               // logical holder identity for owner-scoped nesting
   payload: () => TPayload | Promise<TPayload>;
   shouldReclaim?: (params: {
     lockPath: string;
@@ -73,11 +76,15 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     payload: Record<string, unknown> | null;
   }) => boolean | Promise<boolean>;
   metadata?: Record<string, unknown>;    // attached to heldEntries() output for diagnostics
+  parsePayload?: (raw: string) => unknown;
+  lockRoot?: Root;
+  onCompromised?: (info: { lockPath: string; normalizedTargetPath: string }) => void;
+  compromiseCheckIntervalMs?: number;
 };
 
 type FileLockRetryOptions = {
   retries?: number;       // number of retry attempts after the first failure
-  factor?: number;        // exponential backoff factor (default 2)
+  factor?: number;        // exponential backoff factor (default 1: constant delay)
   minTimeout?: number;    // initial delay (ms)
   maxTimeout?: number;    // delay cap (ms)
   randomize?: boolean;    // jitter
@@ -85,6 +92,59 @@ type FileLockRetryOptions = {
 ```
 
 `payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
+`parsePayload` replaces JSON parsing for legacy or custom sidecars. Its `unknown`
+result is passed to `shouldReclaim` and `shouldRemoveStaleLock`, allowing PID,
+process-start, argv, or role schemas to remain application-owned.
+
+## Owner-scoped reentrancy
+
+Version 0.5 removes the unsound process-scoped `allowReentrant` boolean and
+replaces it with `reentrantOwner`. When a manager already holds the canonical
+target path, another acquisition reuses that sidecar only when both acquisitions
+provide the same owner string. Each acquisition gets an idempotent release
+handle; the sidecar remains until the last reference is released. A different or
+missing owner waits under the normal contention, retry, and timeout policy. A
+known live in-process holder is never stale-reclaimed by its own manager.
+
+This supports logical session writers that may reach one file through real and
+symlinked parent paths:
+
+```ts
+const managerKey = "session-write-locks";
+const reentrantOwner = `session:${sessionId}:operation:${operationId}`;
+
+const outer = await acquireFileLock(realSessionPath, {
+  managerKey,
+  reentrantOwner,
+  staleMs: 60_000,
+  payload: () => ({ pid: process.pid, operationId }),
+});
+const nested = await acquireFileLock(symlinkedSessionPath, {
+  managerKey,
+  reentrantOwner,
+  staleMs: 60_000,
+  payload: () => ({ pid: process.pid, operationId }),
+});
+
+await nested.release(); // sidecar remains for outer
+await outer.release();  // final reference removes it
+```
+
+The manager domain and canonical target path are part of the identity, so
+aliased paths must use the same `managerKey`. The owner key must identify one
+logical holder or call chain. **Never use a process-wide or other shared constant
+for unrelated tasks**: doing so would admit concurrent work to the same critical
+section and recreate the lost-update bug that removed `allowReentrant`.
+
+Omit `reentrantOwner` for ordinary acquisitions. `jsonStore` does so and keeps
+its separate canonical-path mutation queue. The synchronous APIs implement the
+same owner/refcount rules; a mismatched synchronous acquisition blocks the
+calling thread according to its retry and timeout options.
+
+Pass `lockRoot` to place sidecar create, read, verification, and removal behind
+an existing `Root` capability. `lockPath` must resolve inside that root.
+Identity-conditioned removal remains the only release and reclaim deletion
+path.
 
 ## Release handle
 
@@ -92,25 +152,49 @@ type FileLockRetryOptions = {
 type FileLockHandle = {
   lockPath: string;
   normalizedTargetPath: string;
+  verifyStillHeld: () => Promise<boolean>;
   release: () => Promise<void>;
   [Symbol.asyncDispose](): Promise<void>;
 };
 ```
 
+`verifyStillHeld()` compares the current sidecar with the ownership snapshot
+captured at acquisition. Set `compromiseCheckIntervalMs` together with
+`onCompromised` for a cheap periodic check; the callback fires once after the
+sidecar no longer matches. This is detection, not revocation of work already in
+progress.
+
+## Synchronous locks
+
+`acquireFileLockSync()` and `withFileLockSync()` mirror filesystem arbitration,
+retry, payload parsing, stale policy, guarded identity-conditioned reclaim,
+verification, and compromise monitoring. They do not use the async manager
+queue, support async callbacks, or provide same-process reentrancy. Retry waits
+block the calling thread; use the async API in request-serving code.
+
 Always release in a `finally`:
 
 ```ts
-const handle = await acquireFileLock(targetPath, {
+import { acquireFileLockSync } from "@openclaw/fs-safe/file-lock";
+
+const handle = acquireFileLockSync("/var/lib/app/schema.json", {
   staleMs: 60_000,
-  payload: () => ({ pid: process.pid }),
+  timeoutMs: 5_000,
+  retry: { retries: 20, minTimeout: 25, maxTimeout: 250 },
+  payload: () => ({ pid: process.pid, operation: "schema-migration" }),
 });
 try {
-  await doExclusiveWork();
+  if (!handle.verifyStillHeld()) throw new Error("migration lock was replaced");
+  migrateSchemaSynchronously();
 } finally {
-  await handle.release();
+  handle.release();
 }
 ```
 
+The sync payload, reclaim, and parsing callbacks must also be synchronous. This
+shape is appropriate for a short boot migration; it is a poor fit for a server
+request because retry backoff uses a blocking wait.
+
 If your process dies before `release()` runs and skips the exit handler, the sidecar remains. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed by default instead of deleting by path.
 
 ## `withFileLock` — common shape made one-liner
@@ -174,7 +258,7 @@ const handle = await acquireFileLock(targetPath, {
 });
 ```
 
-`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result marks the observed sidecar as stale; `staleRecovery` then decides whether acquisition fails closed or attempts caller-approved removal.
+`heldByThisProcess` is true when this manager already holds the lock. A `true` result marks the observed sidecar as stale; `staleRecovery` then decides whether acquisition fails closed or attempts caller-approved removal.
 
 ## Stale recovery: guarded `remove-if-unchanged`
 
@@ -248,3 +332,4 @@ await withFileLock(
 
 - [Atomic writes](atomic.md) — single-writer atomicity that often replaces the need for a lock entirely.
 - `createAsyncLock` from `@openclaw/fs-safe/advanced` — in-process serialization for a single Node process.
+- [Migrating to 0.5](migrating-to-0.5.md) — choosing sync versus async lock APIs.

package/docs/temp.md

@@ -23,6 +23,7 @@ The compact factory. Returns:
 ```ts
 type TempWorkspace = {
   dir: string;
+  identity: { dev: number | bigint; ino: number | bigint };
   store: FileStore;
   path(fileName: string): string;
   write(fileName: string, data: string | Uint8Array): Promise<string>;
@@ -30,7 +31,7 @@ type TempWorkspace = {
   writeJson(fileName: string, data: unknown, options?: { trailingNewline?: boolean }): Promise<string>;
   copyIn(fileName: string, sourcePath: string): Promise<string>;
   read(fileName: string): Promise<Buffer>;
-  cleanup(): Promise<void>;
+  cleanup(): Promise<"removed" | "missing" | "identity-mismatch">;
   [Symbol.asyncDispose](): Promise<void>;
 };
 ```
@@ -58,6 +59,28 @@ await state.write({ ready: true });
 The workspace owns cleanup; the store is only a view over the workspace
 directory.
 
+The identity receipt is captured when the workspace is created. Manual,
+disposal, and process-exit cleanup remove the path only while `lstat` still
+matches that receipt. If another actor renames the workspace away and places a
+new directory at the old name, cleanup returns `"identity-mismatch"` and leaves
+the replacement untouched. Disposal hooks perform the same check and ignore
+the returned status.
+
+When cleanup is part of a retention or audit decision, inspect the receipt
+instead of treating cleanup as fire-and-forget:
+
+```ts
+const workspace = await tempWorkspace({ rootDir: "/var/lib/app/tmp", prefix: "restore-" });
+try {
+  await restoreInto(workspace.dir);
+} finally {
+  const cleanup = await workspace.cleanup();
+  if (cleanup === "identity-mismatch") {
+    alertOperator("restore workspace path was replaced; replacement preserved");
+  }
+}
+```
+
 The sync variant `tempWorkspaceSync` exposes the same surface with sync return
 types and a `FileStoreSync` at `workspace.store`.
 

package/docs/test-hooks.md

@@ -31,6 +31,15 @@ type FsSafeTestHooks = {
   afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
   beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
   afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  beforeArchiveOutputMutation?: (operation: "mkdir" | "chmod", targetPath: string) => Promise<void> | void;
+  beforeFileStorePruneDescend?: (dirPath: string) => Promise<void> | void;
+  beforeFileStoreSyncPrivateWrite?: (filePath: string) => void;
+  beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
+  afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
+  beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+  beforeTrashMove?: (targetPath: string, destPath: string) => void;
+  afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
+  beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
 };
 ```
 
@@ -39,8 +48,19 @@ type FsSafeTestHooks = {
 | `afterPreOpenLstat` | A pre-open `lstat` has just resolved. Use this to swap a path between validation and open. |
 | `beforeOpen` | The library is about to call `open(path, flags)`. Use this to inject a TOCTOU window. |
 | `afterOpen` | An open just succeeded. Use this to mutate state before the post-open identity check runs. |
-
-Each hook may be sync or async; async hooks are awaited.
+| `beforeArchiveOutputMutation` | Archive staging is about to create a directory or apply a mode. |
+| `beforeFileStorePruneDescend` | File-store pruning is about to descend into a directory. |
+| `beforeFileStoreSyncPrivateWrite` | A synchronous private-store write is about to mutate its target. |
+| `beforeRootFallbackMutation` | A guarded JS root fallback is about to mkdir, move, or remove. |
+| `afterPinnedWriteFallbackRename` | A fallback rename committed and post-commit identity checks have not run yet. |
+| `beforeSiblingTempWrite` | A sibling temp file exists and its writer is about to run. |
+| `beforeTrashMove` | Trash handling is about to move the target. |
+| `afterPublishTargetCreated` | Exclusive publication created its target and final fences have not run yet. |
+| `beforePublishDirectorySync` | Publication verified the target and is about to sync its parent directory. |
+
+Hooks typed `Promise<void> | void` may be sync or async and are awaited.
+Hooks used by synchronous code paths are typed `void` and must not return a
+promise.
 
 ## Usage
 

package/docs/testing.md

@@ -1,6 +1,9 @@
 # Testing
 
-`@openclaw/fs-safe/test-hooks` exposes a small set of test-only injection points. They are inert in production: the hooks only activate when `process.env.NODE_ENV === "test"`. Outside test mode, calls to set hooks are no-ops, so leaking a test setup line into production is safe but ineffective.
+`@openclaw/fs-safe/test-hooks` exposes test-only injection points. Registration
+is allowed only when `process.env.NODE_ENV === "test"` or
+`process.env.VITEST === "true"`; registering a non-empty hook set elsewhere
+throws. Production code must not import this subpath.
 
 ```ts
 import {
@@ -14,7 +17,7 @@ The double-underscore prefix is a deliberate "hands off" signal: production code
 ## When to reach for hooks
 
 - Reproduce a TOCTOU race deterministically: simulate a symlink swap between resolve and open, or between write and rename.
-- Force Node-only behavior without uninstalling Python from your runners.
+- Force guarded JavaScript behavior without removing bundled binaries from your runners.
 - Inject latency to test cancellation/timeout paths.
 
 If you don't need to inject a race, you don't need hooks — most tests should drive the library through normal calls and assert on observable behavior.
@@ -26,6 +29,10 @@ type FsSafeTestHooks = {
   afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
   beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
   afterOpen?: (filePath: string, handle: import("node:fs/promises").FileHandle) => Promise<void> | void;
+  afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
+  beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
+  // Additional archive, store, root-fallback, temp, and trash race hooks are
+  // documented on the focused Test hooks reference page.
 };
 
 function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;
@@ -37,6 +44,8 @@ Hooks are called at well-defined points in the library's hot paths:
 - **`afterPreOpenLstat`** — runs after the pre-open `lstat`. A common use is to swap the path's target via `fs.symlink`/`fs.unlink` to drive a TOCTOU race.
 - **`beforeOpen`** — runs before `fs.open` with the exact flags the root read path will use.
 - **`afterOpen`** — runs after the file handle is opened. Useful to wrap handle methods or inject a size race before a stream is consumed.
+- **`afterPublishTargetCreated`** — runs after exclusive publication created a target but before its final fences.
+- **`beforePublishDirectorySync`** — runs after target verification and immediately before strict parent sync; useful for exercising `onSyncFailure`.
 
 `__setFsSafeTestHooksForTest(undefined)` clears all hooks. Always clean up between tests.
 
@@ -81,20 +90,20 @@ it("rejects a swap between resolve and open", async () => {
 
 The `code` may be `symlink` (caught at open by `O_NOFOLLOW`) or `path-mismatch` (caught by the post-open identity check) depending on platform — both are correct refusals.
 
-## Example: force Node-only fallback behavior
+## Example: force guarded JavaScript fallback behavior
 
 ```ts
-import { configureFsSafePython } from "@openclaw/fs-safe/config";
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 beforeEach(() => {
-  configureFsSafePython({ mode: "off" });
+  configureFsSafeNative({ mode: "off" });
 });
 
 afterEach(() => {
-  configureFsSafePython({ mode: "auto", pythonPath: undefined });
+  configureFsSafeNative({ mode: "auto" });
 });
 
-it("runs without the Python helper", async () => {
+it("runs without the native helper", async () => {
   const fs = await root(dir);
   await fs.write("file.txt", "ok");
   await expect(fs.readText("file.txt")).resolves.toBe("ok");
@@ -116,6 +125,8 @@ afterEach(() => {
 
 A global hook clear in your test setup file is a good safety net.
 
+See the [complete Test hooks reference](test-hooks.md) for every optional hook.
+
 ## Patterns for testing fs-safe-using code
 
 You usually don't need hooks. Most tests follow this shape:

package/docs/types.md

@@ -65,18 +65,20 @@ Returned by `Root.open()` and `Root.read()`:
 ```ts
 type OpenResult = {
   handle: import("node:fs/promises").FileHandle;
+  containment: "kernel-atomic" | "best-effort";
   realPath: string;
   stat: import("node:fs").Stats;
 };
 
 type ReadResult = {
   buffer: Buffer;
+  containment: "kernel-atomic" | "best-effort";
   realPath: string;
   stat: import("node:fs").Stats;
 };
 ```
 
-`realPath` is the canonical real path the read or open landed on, after symlink resolution; `stat` is the verified `fstat` result.
+`realPath` is the canonical real path the read or open landed on, after symlink resolution; `stat` is the verified `fstat` result. Public root results currently report `containment: "best-effort"`; the union also describes direct native `openBeneath()` results, which report `"kernel-atomic"` on Linux. See the [security model](security-model.md#containment-guarantees-by-platform).
 
 ## `RootDefaults` / `RootOptions`
 

package/docs/walk.md

@@ -67,7 +67,62 @@ type WalkDirectoryOptions = {
 
 Unreadable directories are skipped rather than throwing, but every skipped directory is recorded in `failedDirs`. This keeps the helper suitable for best-effort inventories while letting pruning jobs tell an incomplete scan from an empty one: a destructive reconcile that deletes state for paths missing from `entries` must first confirm `failedDirs` holds no real read failures, or a transient `EIO`/`EACCES` blip would be mistaken for mass deletion. Use a stricter root-bounded operation when every entry must be accounted for.
 
+## Root-bounded async iteration
+
+`Root.walk(rel, options)` is the root-bounded counterpart to these standalone
+inventory helpers. It yields `{ relativePath, kind, size }` incrementally and
+accepts `maxDepth`, `maxEntries`, `symlinkPolicy: "skip" |
+"follow-within-root"`, and an `AbortSignal`. The default budget behavior yields
+one `kind: "truncated"` marker and ends; pass `limitBehavior: "throw"` for a
+typed `FsSafeError("too-large")` instead.
+
+`entryFilter` is evaluated for each resolved file, directory, or other entry:
+
+```ts
+for await (const entry of capability.walk("", {
+  symlinkPolicy: "skip",
+  entryFilter: (entry) =>
+    entry.kind === "directory" && entry.relativePath === ".git"
+      ? "skip-subtree"
+      : "include",
+  onDirectoryError: "skip-and-report",
+})) {
+  if (entry.kind === "directory-error") {
+    console.warn("incomplete subtree", entry.relativePath, entry.error);
+    continue;
+  }
+  consume(entry);
+}
+```
+
+The result values are `"include"`, `"skip"`, and `"skip-subtree"`. Plain
+`"skip"` omits an entry but still descends when it is a directory;
+`"skip-subtree"` omits that directory and prunes its descendants. Returning
+`"skip-subtree"` for a non-directory is equivalent to `"skip"`.
+
+`onDirectoryError` defaults to `"throw"`, preserving the original fail-fast
+contract. `"skip-and-report"` yields a discriminated
+`{ kind: "directory-error", relativePath, size: 0, error }` marker for a
+directory that cannot be resolved or listed, then continues with its siblings.
+Every examined directory entry consumes `maxEntries` before filtering, so
+`"skip"` cannot turn the iterator into an unbounded traversal. Reporting and
+`"truncated"` markers describe already-reached state and do not authorize
+further descent.
+
+The pure-Node path validates every directory canonically inside the root,
+revalidates each listing through the normal `Root.list()` boundary, and tracks
+canonical directories to stop symlink cycles. It does not hold a descriptor
+for the entire tree, so it is not a process sandbox against a hostile peer that
+can continuously swap and restore directories. Each individual lookup retains
+the documented Node `Root` boundary checks.
+
+Unlike `walkDirectory()` and `walkDirectorySync()`, `Root.walk()` is
+root-bounded and reports failures inline because an async iterator has no final
+result summary. Its default remains to throw on unreadable or invalid
+directories.
+
 ## See also
 
 - [`fileStore`](file-store.md) — managed stores use bounded walking for pruning.
 - [Path scopes](path-scope.md) — boundary checks for known absolute paths.
+- [Migrating to 0.5](migrating-to-0.5.md) — adopting bounded pruning and partial-result handling.

package/docs/writing.md

@@ -17,7 +17,7 @@ await fs.mkdir("snapshots/2026/05");
 
 1. Resolve the relative target against the canonical root and reject anything that escapes (`outside-workspace`).
 2. If `mkdir: true`, create missing parent directories with the parent fd pinned.
-3. Open the parent directory by fd. Subsequent rename/unlink uses the parent fd, not the path string, so a parent-directory symlink swap mid-call cannot divert the write.
+3. Pin or guard the parent directory for the selected mechanism. Native operations use a parent fd; guarded JavaScript verifies directory identity before and after mutation. Linux beneath opens are kernel-atomic, while macOS, Windows, and JavaScript routes retain the best-effort race boundaries in the [security model](security-model.md#containment-guarantees-by-platform).
 4. Write data to a sibling temp file in the same directory.
 5. Atomically rename the temp file over the destination.
 6. Stat the resulting fd and verify identity.
@@ -246,9 +246,9 @@ const fs = await root("/mnt/rclone-workspace", {
 await fs.write("state.json", body); // succeeds on rclone FUSE
 ```
 
-**How it works.** The full write runs under an exclusive per-target lock named `.fs-safe-write-<sha256>.lock` in the root. Keeping the lock in the already-canonical root avoids creating an unguarded lock path through a missing or raced target parent. The guarded Node fallback accepts the source-temp-to-destination inode mismatch only when the SHA-256 of the re-read bytes matches the SHA-256 of the bytes written. Subsequent path identity checks remain strict, so this mode requires an unchanged destination path to report stable identity. It deliberately bypasses the stricter fd-relative Python helper because that helper requires rename to preserve inode identity. The lock is released before the call returns.
+**How it works.** The full write runs under an exclusive per-target lock named `.fs-safe-write-<sha256>.lock` in the root. Keeping the lock in the already-canonical root avoids creating an unguarded lock path through a missing or raced target parent. The guarded Node fallback accepts the source-temp-to-destination inode mismatch only when the SHA-256 of the re-read bytes matches the SHA-256 of the bytes written. Subsequent path identity checks remain strict, so this mode requires an unchanged destination path to report stable identity. It deliberately stays on the guarded JavaScript path because content verification replaces the normal inode-preserving rename contract. The lock is released before the call returns.
 
-**Security note.** `verify-content-with-lock` proves that the bytes observed after rename match the requested write and prevents *cooperating* writers from interleaving. It does **not** prove that the destination still names the temp-file object, retain the Python helper's fd-relative parent pinning, or stop a same-UID process that ignores the advisory lock. Do not use this option on directories writable by untrusted same-UID processes. Strict identity verification remains the default.
+**Security note.** `verify-content-with-lock` proves that the bytes observed after rename match the requested write and prevents *cooperating* writers from interleaving. It does **not** prove that the destination still names the temp-file object, retain fd-relative parent pinning, or stop a same-UID process that ignores the advisory lock. Do not use this option on directories writable by untrusted same-UID processes. Strict identity verification remains the default.
 
 Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Recover only under external authority that excludes every competing writer; see [File lock](sidecar-lock.md#stale-recovery-guarded-remove-if-unchanged).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.4.7",
+  "version": "0.5.1",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -27,6 +27,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
+    "dist/native/**/*.node",
     "docs/**/*.md",
     "README.md",
     "CHANGELOG.md",
@@ -120,6 +121,7 @@
   },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
+    "benchmark:publish": "pnpm build && node scripts/bench-publish.mjs",
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
@@ -129,7 +131,10 @@
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
     "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm test && node scripts/check-pack.mjs",
     "docs:site": "node scripts/build-docs-site.mjs",
+    "native:build": "pnpm --filter @openclaw/fs-safe-native-build build",
+    "native:test": "cargo test --manifest-path native/Cargo.toml",
     "pack:check": "pnpm build && node scripts/check-pack.mjs",
+    "package:smoke": "node scripts/check-release-packages.mjs --allow-host-only --output release-artifacts",
     "check:changed": "pnpm run check",
     "release:notes": "node scripts/release-notes.mjs",
     "test:changed": "pnpm run test",
@@ -140,13 +145,14 @@
   },
   "optionalDependencies": {
     "jszip": "^3.10.1",
-    "tar": "7.5.20"
+    "tar": "7.5.22"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@napi-rs/cli": "3.8.1",
+    "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "4.1.10",
     "typescript": "^7.0.2",
-    "vite": "8.1.5",
+    "vite": "8.2.0",
     "vitest": "^4.1.10"
   },
   "engines": {

package/dist/pinned-helper.d.ts

@@ -1,9 +0,0 @@
-import type { DirEntry, PathStat } from "./types.js";
-import { isPinnedHelperUnavailable } from "./pinned-python.js";
-type HelperOperation = "stat" | "readdir" | "mkdirp" | "remove" | "rename";
-export { isPinnedHelperUnavailable };
-export declare function runPinnedHelper<T>(operation: HelperOperation, rootDir: string, payload: Record<string, unknown>): Promise<T>;
-export declare function helperStat(rootDir: string, relativePath: string): Promise<PathStat>;
-export declare function helperReaddir(rootDir: string, relativePath: string, withFileTypes: false): Promise<string[]>;
-export declare function helperReaddir(rootDir: string, relativePath: string, withFileTypes: true): Promise<DirEntry[]>;
-//# sourceMappingURL=pinned-helper.d.ts.map

package/dist/pinned-helper.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pinned-helper.d.ts","sourceRoot":"","sources":["../src/pinned-helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EACL,yBAAyB,EAG1B,MAAM,oBAAoB,CAAC;AAE5B,KAAK,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3E,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAErC,wBAAsB,eAAe,CAAC,CAAC,EACrC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzF;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,KAAK,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AACrB,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,IAAI,GAClB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC"}

package/dist/pinned-helper.js

@@ -1,19 +0,0 @@
-import { isPinnedHelperUnavailable, runPinnedPythonOperation, validatePinnedOperationPayload, } from "./pinned-python.js";
-export { isPinnedHelperUnavailable };
-export async function runPinnedHelper(operation, rootDir, payload) {
-    validatePinnedOperationPayload(payload);
-    return await runPinnedPythonOperation({
-        operation,
-        rootPath: rootDir,
-        payload,
-    });
-}
-export async function helperStat(rootDir, relativePath) {
-    return await runPinnedHelper("stat", rootDir, { relativePath });
-}
-export async function helperReaddir(rootDir, relativePath, withFileTypes) {
-    return await runPinnedHelper("readdir", rootDir, {
-        relativePath,
-        withFileTypes,
-    });
-}

package/dist/pinned-path.d.ts

@@ -1,7 +0,0 @@
-export declare function isPinnedPathHelperSpawnError(error: unknown): boolean;
-export declare function runPinnedPathHelper(params: {
-    operation: "mkdirp" | "remove";
-    rootPath: string;
-    relativePath: string;
-}): Promise<void>;
-//# sourceMappingURL=pinned-path.d.ts.map

package/dist/pinned-path.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pinned-path.d.ts","sourceRoot":"","sources":["../src/pinned-path.ts"],"names":[],"mappings":"AAIA,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB"}

package/dist/pinned-path.js

@@ -1,21 +0,0 @@
-import { FsSafeError } from "./errors.js";
-import { canFallbackFromPythonError } from "./pinned-python-config.js";
-import { runPinnedHelper } from "./pinned-helper.js";
-export function isPinnedPathHelperSpawnError(error) {
-    return canFallbackFromPythonError(error);
-}
-export async function runPinnedPathHelper(params) {
-    try {
-        await runPinnedHelper(params.operation, params.rootPath, {
-            relativePath: params.relativePath,
-        });
-    }
-    catch (error) {
-        if (error instanceof FsSafeError) {
-            throw error;
-        }
-        throw new FsSafeError("helper-failed", "pinned path helper failed", {
-            cause: error instanceof Error ? error : undefined,
-        });
-    }
-}

package/dist/pinned-python-config.d.ts

@@ -1,9 +0,0 @@
-export type FsSafePythonMode = "auto" | "off" | "require";
-export type FsSafePythonConfig = {
-    mode: FsSafePythonMode;
-    pythonPath?: string;
-};
-export declare function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
-export declare function getFsSafePythonConfig(): FsSafePythonConfig;
-export declare function canFallbackFromPythonError(error: unknown): boolean;
-//# sourceMappingURL=pinned-python-config.d.ts.map

package/dist/pinned-python-config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pinned-python-config.d.ts","sourceRoot":"","sources":["../src/pinned-python-config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAqBF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE/E;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAc1D;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMlE"}

package/dist/pinned-python-config.js

@@ -1,38 +0,0 @@
-let overrideConfig = {};
-function parseMode(value) {
-    if (!value) {
-        return undefined;
-    }
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "0" || normalized === "false" || normalized === "off" || normalized === "never") {
-        return "off";
-    }
-    if (normalized === "1" || normalized === "true" || normalized === "on" || normalized === "auto") {
-        return "auto";
-    }
-    if (normalized === "required" || normalized === "require") {
-        return "require";
-    }
-    return undefined;
-}
-export function configureFsSafePython(config) {
-    overrideConfig = { ...overrideConfig, ...config };
-}
-export function getFsSafePythonConfig() {
-    return {
-        mode: overrideConfig.mode ??
-            parseMode(process.env.FS_SAFE_PYTHON_MODE) ??
-            parseMode(process.env.OPENCLAW_FS_SAFE_PYTHON_MODE) ??
-            "auto",
-        pythonPath: overrideConfig.pythonPath ??
-            process.env.FS_SAFE_PYTHON ??
-            process.env.OPENCLAW_FS_SAFE_PYTHON ??
-            process.env.OPENCLAW_PINNED_PYTHON ??
-            process.env.OPENCLAW_PINNED_WRITE_PYTHON,
-    };
-}
-export function canFallbackFromPythonError(error) {
-    const code = error instanceof Error && "code" in error ? error.code : undefined;
-    return (getFsSafePythonConfig().mode !== "require" &&
-        (code === "helper-unavailable" || code === "unsupported-platform"));
-}

package/dist/pinned-python.d.ts

@@ -1,12 +0,0 @@
-type PinnedPythonOperation = "copy" | "stat" | "readdir" | "mkdirp" | "remove" | "rename" | "write";
-export declare function __resetPinnedPythonWorkerForTest(): void;
-export declare function runPinnedPythonOperation<T>(params: {
-    operation: PinnedPythonOperation;
-    rootPath: string;
-    payload: Record<string, unknown>;
-}): Promise<T>;
-export declare function assertPinnedPythonOperationAvailable(): void;
-export declare function validatePinnedOperationPayload(payload: Record<string, unknown>): void;
-export declare function isPinnedHelperUnavailable(error: unknown): boolean;
-export {};
-//# sourceMappingURL=pinned-python.d.ts.map

package/dist/pinned-python.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pinned-python.d.ts","sourceRoot":"","sources":["../src/pinned-python.ts"],"names":[],"mappings":"AA2ZA,KAAK,qBAAqB,GACtB,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,CAAC;AAiBZ,wBAAgB,gCAAgC,IAAI,IAAI,CAQvD;AAiOD,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,MAAM,EAAE;IACxD,SAAS,EAAE,qBAAqB,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4Bb;AAED,wBAAgB,oCAAoC,IAAI,IAAI,CAK3D;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAarF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEjE"}