@openclaw/fs-safe 0.4.6 → 0.5.0

package/docs/root.md

@@ -44,15 +44,30 @@ Every method on the returned handle accepts paths relative to the root and rejec
 ### Reads
 
 ```ts
-fs.read(rel, options?)         // { buffer, realPath, stat }
+fs.read(rel, options?)         // { buffer, containment, realPath, stat }
 fs.readBytes(rel, options?)    // Buffer
 fs.readText(rel, options?)     // string
 fs.readJson<T>(rel, options?)  // parsed T
-fs.open(rel, options?)         // { handle, realPath, stat, [Symbol.asyncDispose] }
+fs.open(rel, options?)         // { handle, containment, realPath, stat, [Symbol.asyncDispose] }
 fs.readAbsolute(absPath, options?) // ReadResult; absPath must already be inside the root
 fs.reader(options?)            // (path) => Promise<Buffer>; useful for loader APIs
+fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kind, size }>
 ```
 
+`walk()` is the incremental, root-bounded recursive scan. It supports entry and
+depth budgets, cancellation, and `symlinkPolicy: "skip" |
+"follow-within-root"`. Budget exhaustion yields a `"truncated"` marker by
+default or throws `FsSafeError("too-large")` with `limitBehavior: "throw"`.
+Use `entryFilter(entry)` to return `"include"`, `"skip"`, or
+`"skip-subtree"`. `"skip"` omits the current entry but still descends into a
+directory; `"skip-subtree"` omits a directory and all of its descendants.
+Directory reads remain fail-fast by default. With
+`onDirectoryError: "skip-and-report"`, the iterator instead yields
+`{ relativePath, kind: "directory-error", size: 0, error }` and continues with
+the remaining tree.
+See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
+with the standalone best-effort walkers.
+
 `open()` returns a Node `FileHandle` for streaming. Prefer `await using` for cleanup:
 
 ```ts
@@ -64,6 +79,10 @@ await using opened = await fs.open("large.log");
 }
 ```
 
+`open()`, `read()`, and `openWritable()` results include
+`containment: "best-effort"`. The field reports the mechanism used; see the
+[security model](security-model.md#containment-guarantees-by-platform).
+
 ### Writes
 
 ```ts
@@ -100,25 +119,22 @@ fs.resolve(rel)                  // absolute path inside the root, after canonic
 
 These do not pin a later operation. They are safe to expose to UIs and decision points; for the actual read or write, use the verb methods so the operation pins identity at the point of use.
 
-## Python helper mode
+## Native helper mode
 
-On POSIX, mutation and inspection methods that need fd-relative directory
-operations go through one persistent Python helper process. This avoids a
-spawn-per-call cost while still using `openat`/`renameat`/`unlinkat`-style
-operations that Node's `fs` API does not expose ergonomically.
+Create-only writes prefer the bundled native helper for fd-relative opens and
+atomic no-replace rename. Operations without native wiring retain their guarded
+JavaScript implementations.
 
 ```ts
-import { configureFsSafePython } from "@openclaw/fs-safe/config";
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
-configureFsSafePython({ mode: "off" });     // Node-only fallback path
-configureFsSafePython({ mode: "require" }); // fail if fd-relative helper unavailable
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript path
+configureFsSafeNative({ mode: "require" }); // fail if the binding is unavailable
 ```
 
-`auto` is the default. Configure the mode before creating roots. Without the
-helper, root methods still run, but same-UID races that swap parent directories
-between validation and mutation are harder to close completely. Use `require`
-when that downgrade should be treated as a deployment failure. See
-[Python helper policy](python-helper.md) for deployment guidance.
+`auto` is the default. Configure the mode before creating roots. See the
+[native helper policy](native-helper.md) for supported platforms, the native
+surface, and the precise fallback boundary.
 
 ### Properties
 

package/docs/secret-file.md

@@ -4,7 +4,10 @@ Helpers for reading and writing credentials. Files are written at mode `0o600`,
 
 ```ts
 import {
+  createSecretFileAtomic,
+  readSecretFile,
   readSecretFileSync,
+  tryReadSecretFile,
   tryReadSecretFileSync,
   writeSecretFileAtomic,
   DEFAULT_SECRET_FILE_MAX_BYTES,
@@ -54,7 +57,7 @@ if (token) {
 Strict reader. Throws `FsSafeError` when the file is missing, too large, empty, unreadable, or rejected by the validation checks. Use when failing loudly is the right call:
 
 ```ts
-const token = readSecretFileSync("/var/lib/app/auth.token");
+const token = readSecretFileSync("/var/lib/app/auth.token", "auth token");
 ```
 
 ### Read options
@@ -69,6 +72,24 @@ type SecretFileReadOptions = {
 
 The reader trims the file content and rejects empty results. `rejectSymlink` blocks a symlink path before the pinned read. Hardlinks are rejected by default so another in-tree name cannot alias the credential; pass `rejectHardlinks: false` only when you explicitly trust that layout.
 
+`readSecretFile()` and `tryReadSecretFile()` are asynchronous counterparts with
+the same pinned-handle validation, byte cap, trimming, error codes, and strict
+versus missing-is-undefined naming semantics.
+
+Use the async strict reader when a service cannot start safely without the
+credential:
+
+```ts
+import { readSecretFile } from "@openclaw/fs-safe/secret";
+
+const signingKey = await readSecretFile(
+  "/var/lib/app/keys/webhook-signing.key",
+  "webhook signing key",
+  { maxBytes: 8 * 1024, rejectSymlink: true },
+);
+startWebhookVerifier(signingKey);
+```
+
 ## Writing
 
 ### `writeSecretFileAtomic(params)`
@@ -99,6 +120,33 @@ type WriteSecretFileParams = {
 
 The directory mode is asserted on each component along the path: `rootDir`, then any intermediate dirs, then the parent. The helper enforces that every component matches `dirMode` — wider permissions on an existing directory cause the write to fail. Audit and tighten existing secret directories yourself.
 
+### `createSecretFileAtomic(params)`
+
+This create-only sibling has the same directory, mode, pinned-write, and
+post-write verification policy. Final materialization uses exclusive create;
+if anything already occupies the target path it throws
+`FsSafeError("secret-exists")` without modifying that entry. Use the distinct
+name when first-writer-wins is part of the credential protocol.
+
+For example, two onboarding requests may race to install the first refresh
+token. Exactly one should win, and the loser must not overwrite it:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe/errors";
+import { createSecretFileAtomic } from "@openclaw/fs-safe/secret";
+
+try {
+  await createSecretFileAtomic({
+    rootDir: "/var/lib/app/credentials",
+    filePath: "/var/lib/app/credentials/provider.refresh-token",
+    content: refreshToken,
+  });
+} catch (error) {
+  if (!(error instanceof FsSafeError) || error.code !== "secret-exists") throw error;
+  // Another initializer won. Read and validate the installed credential.
+}
+```
+
 For more permissive credentials, override `mode`:
 
 ```ts
@@ -153,3 +201,4 @@ await withTimeout(
 - [JSON files](json.md) — `writeJson` accepts `mode: 0o600` for non-secret JSON state.
 - [Atomic writes](atomic.md) — the lower-level `replaceFileAtomic` used by these helpers.
 - [Private file-store mode](private-file-store.md) — root-bounded JSON+text stores using secret-file write policy.
+- [Migrating to 0.5](migrating-to-0.5.md) — strict/try reads and create-only adoption checklist.

package/docs/security-model.md

@@ -4,6 +4,19 @@
 
 The same shape exists in other languages: Go's [`os.Root` / `OpenInRoot`](https://go.dev/blog/osroot) and Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std) both expose a root handle whose operations refuse to escape it. `fs-safe` is the Node-side equivalent: a single `root()` capability that carries the boundary across every read, write, move, and remove, instead of leaving each call site to redo `path.resolve(...).startsWith(...)` and hope.
 
+## Affected versions / exposure
+
+In published releases through 0.4.7, the exported `resolveRootPath()` and
+`resolveRootPathSync()` helpers validated a lexically normalized path spelling.
+A caller-supplied path traversing an in-root symlink could therefore pass
+validation while resolving outside the root. Version 0.5 fixes this with
+component-wise alias resolution, resolving each alias before applying later
+path components.
+
+`root()` handles were **not** affected: their operations have contained this
+case since `5ddca80`. Exposure is limited to consumers that call
+`resolveRootPath()` or `resolveRootPathSync()` directly.
+
 ## Threat model
 
 You hand a `root()` boundary to a piece of code that takes caller-controlled relative paths. The library defends against a caller that:
@@ -31,7 +44,7 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 ### Path traversal and absolute paths
 
-Every relative path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Inputs containing `..`, leading `/` (without `pathScope` opt-in), or that resolve outside the root throw `outside-workspace`.
+Every relative path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal that escapes, leading `/` (without `pathScope` opt-in), or any canonical result outside the root throws `outside-workspace`.
 
 ### Symlinks (read side)
 
@@ -49,7 +62,7 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 ### TOCTOU between resolve and use
 
-`resolve()`, `exists()`, `stat()`, and `list()` are explicitly **not** race-resistant — they answer a question and return. To act on a path with race resistance, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. They re-pin the path identity at the point of use.
+`resolve()`, `exists()`, `stat()`, and `list()` are explicitly advisory — they answer a question and return. To act on a path with operation-local identity checks, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. The containment table below states which opens are kernel-atomic and which remain best-effort.
 
 ### Denied mutations
 
@@ -61,6 +74,19 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 Within one process, async writes to the same target are queued so their temp-write/rename phases do not overlap. Cross-process writers still need an external protocol such as the sidecar lock helpers.
 
+### Directory durability
+
+`pinDirectory()` opens a directory without following its final component on
+POSIX, verifies the descriptor against the pathname identity and canonical
+path, and repeats those checks around synchronization. `ensureDurableDirectory()`
+pins the nearest existing ancestor and each newly created segment before
+synchronizing every new directory edge from the leaf upward.
+
+Known Windows directory-flush limitations are returned as an explicit
+`unsupported` outcome. POSIX and other I/O failures propagate from the strict
+API. The separately named best-effort helpers intentionally provide no crash
+durability guarantee.
+
 ### Archive extraction
 
 `extractArchive` first stages into a private temp directory (mode 0700) outside the destination, validates each entry path against `..` and absolute prefixes, refuses link-type entries by default, enforces entry count and byte budgets, and only then merges the staged tree into the destination through the same boundary checks used by direct writes.
@@ -71,12 +97,20 @@ A library cannot revoke its own caller's authority. If your code chooses to bypa
 
 The library does not modify or constrain the global Node.js `fs` namespace, and it does not patch the runtime. Other code in the same process retains its normal filesystem authority.
 
-## Platform notes
+## Containment guarantees by platform
+
+`openBeneath()` and JavaScript open results report one of two factual containment classes:
+
+| Mechanism | Reported containment | Boundary |
+|---|---|---|
+| Linux native | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| macOS native | `best-effort` | macOS 15.4 and newer use `O_RESOLVE_BENEATH` first; older kernels use the guarded `openat(O_NOFOLLOW)` component walk. Both verify the opened descriptor with `F_GETPATH`. |
+| Windows native | `best-effort` | Handle-relative `NtCreateFile` rejects reparse points, but this package does not claim a Linux-style atomic beneath guarantee. |
+| JavaScript fallback | `best-effort` | Canonical checks, no-follow opens where Node exposes them, and post-open identity checks form a check-then-use sequence. |
 
-- **POSIX (Linux, macOS):** Best-defended path. Uses `O_NOFOLLOW`, fd identity checks, and one persistent Python helper process for fd-relative `unlinkat` / `mkdirat` / `renameat` / parent-fd write operations. Configure `FS_SAFE_PYTHON_MODE=require` when helper startup must fail closed, or `off` when you need a no-Python runtime. See [Python helper policy](python-helper.md).
-- **Windows:** Falls back to the safest Node-level behavior available. `O_NOFOLLOW` is not honored. Some fd-relative POSIX hardening is unavailable. The library does the path canonicalization, identity, and atomic-rename checks it can.
+The macOS `F_GETPATH` verification is an escape detector, not a race-atomic guarantee. A hostile same-UID process can rename a directory after `O_RESOLVE_BENEATH` or the manual walk and race the post-open sample or a later descriptor-relative mutation. The native result therefore remains `best-effort` on macOS even when the kernel flag is available. No policy decision is attached to these labels; callers can inspect the fact and decide what their own threat model requires.
 
-The library does not advertise different security guarantees per platform — it advertises the same surface and relies on the strongest mechanism the platform offers.
+The public `OpenResult`, `ReadResult`, and `WritableOpenResult` expose `containment`. Those root APIs currently report `best-effort`; direct native `openBeneath()` reports the platform value above. No-replace publication uses `renameat2(RENAME_NOREPLACE)` on Linux, `renameatx_np(RENAME_EXCL)` on macOS, and `FileRenameInfoEx` with replacement disabled on Windows, but those separate mutation semantics do not upgrade an open result's containment label.
 
 ## Limitations to keep in mind
 
@@ -85,11 +119,11 @@ The library does not advertise different security guarantees per platform — it
 | Not ambient authority removal | Code that can import `node:fs` can still bypass the handle. Keep caller-controlled path operations behind `root()` by convention, review, and tests. |
 | Absolute paths are escape hatches | APIs that accept or return absolute paths exist for audit, ingest, and advanced composition. Prefer root-relative names in normal application flow. |
 | Not a mount boundary | `root()` keeps path traversal inside the directory tree and blocks known unsafe read device paths, but it does not make bind mounts or virtual filesystems safe to expose wholesale. |
-| Per-call, not per-session | Another process with the same privileges can still mutate the tree between two separate calls. Use one verb method for the operation you need to make race-resistant. |
+| Per-call, not per-session | Another process with the same privileges can still mutate the tree between calls, and best-effort mechanisms retain documented same-call race windows. Use one verb method to minimize the window and inspect its reported containment class. |
 | Hardlink rejection is best-effort | Link-count checks depend on platform metadata. Treat `hardlinks: "reject"` as a tripwire, not an authorization primitive. |
 | Mode bits are not a full policy engine | `replaceFileAtomic` and secret-file helpers set requested modes, but you should still set umask and inspect modes when policy requires it. |
 | Archive extraction is path safety, not content safety | Unsafe entry paths and links are rejected; malicious payload contents remain your application layer's problem. |
-| Helper failures degrade fd-relative hardening | `helper-unavailable` falls back in `auto` mode and fails closed in `require` mode. Atomicity and identity checks remain, but parent-directory swaps between validation and mutation are less tightly pinned without the helper. |
+| Native package unavailable | `helper-unavailable` falls back in `auto` mode and fails closed in `require` mode for native-backed operations. Guarded JavaScript atomicity and identity checks remain. |
 | FUSE mounts with rename-unstable inode numbers | Some FUSE mounts (rclone is a confirmed example) do not preserve source inode identity at the rename destination. The explicit `renameIdentity: "verify-content-with-lock"` compatibility mode verifies content under a cooperative lock for that boundary only; subsequent path identity checks and the default remain strict. See [Writing](writing.md) for the weaker opt-in contract. |
 
 ## Recommended deployment shape

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`