@openclaw/fs-safe 0.12.0 → 0.13.1

package/docs/temp.md

@@ -14,7 +14,89 @@ import {
 
 ## Private temp workspaces
 
-A private workspace is a directory created at mode `0o700` under a caller-provided temp root. It is unique per call (random suffix). Calling `cleanup()` or leaving an `await using` scope moves an unchanged workspace through a private quarantine before removal. Descriptor-bounded cleanup prevents recursive traversal of substitutions; the compatible JavaScript fallback has the narrower race contract documented below.
+A private workspace is a uniquely named directory under a caller-provided temp
+root. The default requested mode is `0o700`. Calling `cleanup()` or leaving an
+`await using` scope moves an unchanged workspace through a private quarantine
+before removal. Descriptor-bounded cleanup prevents recursive traversal of
+substitutions; the compatible JavaScript fallback has the narrower race
+contract documented below.
+
+On POSIX, workspace creation verifies the supplied root and its canonical
+ancestors before creating a child. Each existing directory must be owned by the
+effective user or root. Group/world-writable directories must also have the
+sticky bit, so ordinary system temp directories remain usable without changing
+their modes. Foreign-owned directories and non-sticky writable ancestors reject
+with `not-owned` or `insecure-permissions`; unavailable effective-user identity
+rejects with `permission-unverified`. Existing supplied directories keep their
+permissions. Missing root components are created at `0o700` and initialized
+from their first exact security snapshot; if a restrictive umask changes that
+mode, correction uses a verified directory descriptor.
+
+For an already existing canonical root, discovery retains only its immutable
+exact identity. Cleanup-parent retention is provisional: after any native
+capability probe, creation captures and validates the complete ancestry,
+re-observes the root against discovery, and associates the retained parent
+descriptor. Async creation and sync creation outside the Linux/macOS
+direct-mode case dispatch `mkdtemp` immediately after that synchronous boundary
+without another yield or native probe. Existing aliases and missing-component
+roots keep the guarded admission route.
+
+On Linux and macOS, synchronous creation can instead use an exclusive six-character
+random child name when an explicit requested mode other than `0o700` has owner
+`rwx`, no special bits, and no group/world write bits. The requested mode is
+passed directly to `mkdir` and the observed complete permission bits, rather
+than the requested bits, are authoritative. Umask, inherited ACL state, or
+inherited special bits can make that observation differ, in which case creation
+corrects the mode through the retained descriptor. This mode-based optimization
+does not claim that Linux and macOS have identical syscall or ACL behavior, and
+POSIX mode bits do not establish ACL privacy. Creation makes at most 64 attempts;
+after a name collision, each retry generates its candidate first, replays the
+already admitted immutable ancestry and descriptor receipts, and then
+immediately attempts exclusive creation. A colliding entry is never inspected,
+adopted, corrected, registered, or deleted. The default `0o700`, async creation, and
+other sync modes retain the `mkdtemp` path. That path requests initial mode
+`0o700`; a result different from `dirMode` is initialized through the same
+descriptor-bound correction.
+
+The direct sync path opens the new child without following its final component
+and captures one exact descriptor observation after the parent replay. The new
+child's exact identity, type, owner, private bits, and complete `0o7777` mode are
+checked before mode initialization. When its creation mode already
+matches `dirMode` (including the default `0o700`), creation avoids an extra mode
+descriptor and chmod. If the observed creation mode differs from `dirMode`, the
+immediate synchronous correction consumes that one-shot observation, checks the
+fresh child name, replays the parent, and applies correction through the retained
+descriptor. Later admission always performs fresh descriptor and name checks.
+Permission failures propagate. POSIX `dirMode`
+must not grant group/world write access; it only controls the new workspace,
+not existing supplied directories. After the
+first exact child observation, final adoption retains a no-follow child
+descriptor, rechecks complete ancestry and retained cleanup-parent authority,
+and then validates the original child's descriptor and current name for exact
+identity, owner, private bits, and requested mode before cleanup is registered.
+Linux and macOS may replay exact identities through round-trip-safe nonnegative
+numeric `dev`/`ino` projections. Initial receipts that cannot be represented
+exactly stay on the BigInt path; a malformed or mismatched numeric replay fails
+closed without an exact retry.
+Parent or child replacements observed during creation reject before cleanup
+ownership is registered. Unverified artifacts are left in place for
+caller-directed recovery.
+
+On Windows, POSIX mode/UID metadata does not establish ACL privacy, and these
+factories neither claim nor initialize a POSIX `dirMode`; every requested value
+uses the identity-only path without opening a mode descriptor or applying chmod.
+Callers must supply a root with trusted ACLs that protect its children and
+ancestors; exact pathname identity checks still apply. `cleanupSafety` controls
+removal capability, not Windows ACL admission.
+
+Root aliases already present at entry retain their historical support and are
+canonicalized. Callers remain responsible for choosing trusted root paths and
+excluding hostile peers with the same filesystem authority. Node's pathname
+`mkdir`/`mkdtemp` calls do not atomically return a creation descriptor: identity
+checks detect observed substitutions but cannot prove provenance against every
+same-privilege replacement before the first observation. Descriptor chmod
+cannot be redirected to a subsequently substituted pathname. Native bounded
+cleanup does not upgrade the creation operation to an atomic namespace boundary.
 
 ### `tempWorkspace`
 
@@ -76,18 +158,36 @@ verification can still redirect the final pathname removal.
 
 Set `cleanupSafety: "require-bounded"` when that concurrent attacker is in scope.
 Creation then requires native no-replace directory rename, native owned-tree
-removal, and a retained parent descriptor **before** `mkdtemp` creates
-a child. If any capability is unavailable, creation throws
-`FsSafeError("helper-unavailable")`; no child is created and a scoped callback is
-not called. The compatible default retains its fallback even if process-global
-native mode is `require`; select `require-bounded` to make cleanup capability
-mandatory for this API.
+removal, and a readable retained parent descriptor **before** child creation.
+On POSIX, the final requested `dirMode` must also include owner read
+and search (`(dirMode & 0o500) === 0o500`). Preflight failure throws
+`FsSafeError("helper-unavailable")` without creating a child or calling a scoped
+callback. The child descriptor is opened
+while the new directory still has its private creation mode, before an explicit
+`dirMode` can lower access. Retaining a read descriptor does not bypass the
+POSIX final-mode requirement: enumeration reopens the directory relative to
+that descriptor. Compatible mode accepts these restrictive modes but selects
+the JavaScript fallback and does not retain native traversal authority for the
+child, even if the caller later restores its permissions. Windows cleanup
+does not use this POSIX mode gate. A search-only descriptor remains valid identity
+evidence but is never native traversal authority: compatible cleanup selects
+the JavaScript fallback, while `require-bounded` rejects and leaves the
+unregistered child in place for caller-directed recovery. The compatible
+default retains its fallback even if process-global native mode is `require`;
+select `require-bounded` to make cleanup capability mandatory for this API.
 
 On Linux, bounded cleanup requires a successful runtime probe of the exact
 `openat2` child-directory flags, including `RESOLVE_NO_XDEV`, against the retained
 parent descriptor. If the kernel or seccomp policy denies that capability,
 compatible mode uses the guarded JavaScript fallback; `require-bounded` rejects
-before child creation. The probe runs once at creation, without filesystem mutation.
+before child creation. For eligible modes, the probe runs once at creation,
+without filesystem mutation.
+
+Cleanup does not repair POSIX workspace or descendant permissions. In compatible
+mode, a restrictive workspace mode or caller-created unreadable descendants
+can prevent recursive removal; native bounded cleanup can also encounter later
+permission changes or inaccessible descendants. These remain operational
+cleanup failures, with the propagation and recovery behavior described below.
 
 Bounded cleanup checks the parent and public workspace identity, quarantines
 the direct child without replacement, and verifies the quarantine against the
@@ -183,12 +283,20 @@ try {
 type TempWorkspaceOptions = {
   rootDir: string;          // parent directory for workspaces
   prefix: string;           // dir prefix (sanitized)
-  dirMode?: number;         // dir mode; default 0o700
+  dirMode?: number;         // new workspace mode; default 0o700; no POSIX group/world write
   mode?: number;            // file write mode; default 0o600
   cleanupSafety?: "compatible" | "require-bounded"; // default compatible
 };
 ```
 
+On Windows, caller-provided workspace roots and workspace leaf names reject
+NTFS alternate-stream and directory-index namespace spellings before directory
+creation or file access. The lower-level temp and sibling helpers apply the
+same admission to supplied roots, sibling directories, and callback-selected
+final paths. Prefixes and `tempFile()` filenames keep their documented
+sanitization behavior; ordinary colon-bearing POSIX roots and leaf names remain
+valid.
+
 ## Advanced temp primitives
 
 When you don't need the stable workspace abstraction, the lower-level temp-file
@@ -212,6 +320,18 @@ try {
 }
 ```
 
+Options:
+
+```ts
+type TempFileOptions = {
+  rootDir?: string;
+  prefix: string;
+  fileName?: string;
+  onCleanupError?: (error: unknown) => void;
+  cleanupSafety?: "compatible" | "require-bounded"; // default compatible
+};
+```
+
 Returns:
 
 ```ts
@@ -224,9 +344,30 @@ type TempFile = {
 };
 ```
 
-Cleanup captures the directory identity at creation time. If that path is
-renamed away and replaced, cleanup preserves the replacement rather than
-recursively deleting a directory it did not create.
+The default `cleanupSafety: "compatible"` retains the historical temp-file
+behavior without loading or probing the native helper. Cleanup captures the
+directory identity at creation time and preserves a replacement observed by
+its pre-removal identity check. That check and pathname-recursive removal are
+separate operations, however: a same-privilege peer can substitute a directory
+in the final gap and redirect recursive traversal. Process-exit cleanup has the
+same compatible contract.
+
+The bounded mode requires an existing supplied root and applies the same
+trusted-ancestry admission as private temp workspaces. On POSIX it finalizes
+the new directory to `0o700` through its retained descriptor; Windows keeps
+identity checks without treating POSIX modes as ACL privacy. Unverified
+creation artifacts are preserved for caller-directed recovery.
+
+Set `cleanupSafety: "require-bounded"` to require the retained-parent,
+no-replace quarantine, and descriptor-bounded owned-tree removal described for
+[private temp workspaces](#private-temp-workspaces). Admission, including the
+runtime probe, completes before `mkdtemp`; unavailable support throws
+`FsSafeError("helper-unavailable")` before a child is created. Manual, disposal,
+scoped, and process-exit cleanup then share one owner, and no pathname-recursive
+fallback is used. `cleanup()` still resolves `Promise<void>`: operational
+cleanup errors are passed to `onCleanupError` when supplied and otherwise
+suppressed for compatibility. The bounded POSIX final-entry unlink limit still
+applies.
 
 ### `withTempFile`
 
@@ -270,8 +411,13 @@ and current pathname are rejected. The callback must finish and close its
 writer before returning. Its return value is preserved as `result`.
 
 Generated temp filenames suffix Windows reserved-device basenames on every
-platform. A completed sibling staging component that still resolves as a
-Windows device alias rejects with `invalid-path` before hooks or producers run.
+platform. Before either an ordinary or isolated producer runs, the completed staging
+name must be a nonempty, non-dot path component with no POSIX or Windows
+separator, C0/C1 control, Windows-invalid punctuation or stream colon. Windows
+reserved devices and trailing-dot/space aliases are rejected on every host.
+The helper joins that validated component to the guarded or owned directory and
+verifies that the result is a direct child. An invalid completion rejects with
+`invalid-path` without calling the producer or its pre-write hook.
 
 The helper retains one descriptor through requested mode application, opt-in
 file synchronization, rename, and publication verification. It opens read-only
@@ -313,23 +459,35 @@ owned workspace cleanup, including partial output, subject to directory
 identity checks and I/O failures. The callback must still finish and close its
 writer before returning.
 
-After the callback succeeds, `Root.move` checks source aliases and moves the
-output to the ordinary sibling path before file admission. An escaping symlink
-can fail with `path-alias` at this step. Rejected output still inside the owned
-workspace follows its cleanup contract. Once output moves to the sibling path,
-failures before file adoption retain it for caller-directed recovery, as above.
-File admission, requested modes, sync options, and final rename keep their
-existing contracts; `resolveFinalPath(result)` still names a direct child of `dir`.
+After the callback succeeds, an available native helper uses guarded
+no-replace `Root.move`. Native-off operation admits the completed regular file
+with a retained descriptor. On Windows, that branch first requests write-only
+access so admission does not request completed-file data reads; access or provider
+rejections fall back to the historical read-only or read/write open before admission.
+It then creates the randomized sibling with an atomic
+no-clobber hard link and verifies the expected two-link transition. On Windows,
+it opens and verifies a sibling descriptor before closing the source descriptor,
+keeping the file pinned while allowing the private name to disappear on runtimes
+with legacy deletion behavior. It removes the private name before continuing.
+If legacy deletion clears the completed file's read-only attribute, the helper
+restores it through the retained sibling descriptor and verifies its mode and
+identity before publication. Restoration failures reject the operation.
+An escaping symlink fails with `path-alias`, and
+a filesystem without either handoff reports `helper-unavailable`. The retained
+descriptor carries file admission, requested modes, sync options, and final
+rename with their existing contracts; `resolveFinalPath(result)` still names a
+direct child of `dir`.
 
 The isolated path retains exact bigint identities for both the parent and the
 workspace and rechecks them before moving output to the sibling path. An
-observed replacement is rejected. Cleanup uses the existing
-[`withTempFile` ownership contract](#withtempfile), backed by [`tempFile`](#tempfile):
-moving or replacing the parent or workspace can leave the original or
-replacement paths in place. This option does not promise cleanup through a
-retained directory after a rename, stronger permissions, or additional crash
-durability. Omitting it preserves the direct sibling callback path and
-unadmitted partial-file retention.
+observed replacement is rejected. This internal use of [`withTempFile`](#withtempfile)
+does not expose `cleanupSafety` and uses compatible cleanup: moving or replacing
+the parent or workspace can leave artifacts, and a workspace substituted in
+the final check-to-recursive-removal gap can redirect traversal. It does not
+promise cleanup through a retained directory after a rename, bounded cleanup,
+stronger permissions, or additional crash durability. Omitting producer
+isolation preserves the direct sibling callback path and unadmitted
+partial-file retention.
 
 On POSIX, admission uses no-follow and nonblocking open flags, so a FIFO swap
 does not block the helper. Windows retains Node's guarded pathname-open behavior
@@ -343,8 +501,11 @@ Identity checks and pathname rename/unlink are separate syscalls, not atomic
 conditional mutations. A hostile process can still replace a leaf or parent in
 the final syscall gap or mutate an open file's contents. Use an approved writable
 directory and cooperative locking or OS isolation; a moved parent can leave an
-unpublished original temp behind. Observed replacements are preserved, but
-arbitrary concurrent namespace changes cannot be prevented by these helpers.
+unpublished original temp behind. Replacements observed before the final
+namespace mutation are preserved, but that observation is not an atomic
+condition on the later unlink or rename. Private producer isolation also has
+the compatible recursive-cleanup gap described above. Arbitrary concurrent
+namespace changes cannot be prevented by these helpers.
 
 By default the helper attempts to set `dir` to `dirMode` (default `0o700`)
 through the shared verified POSIX directory-descriptor helper. Only the actual
@@ -375,12 +536,18 @@ await writeViaSiblingTempPath({
 If `replaceFileAtomic` does what you need, prefer that. Use
 `writeViaSiblingTempPath` when the producer needs a concrete temp pathname but
 the final destination still needs root-boundary checks.
-Its private workspace uses the same identity-aware directory cleanup as
-`tempFile()`: moving and replacing the workspace preserves the replacement.
+Its private workspace uses `tempFile()`'s compatible identity-aware cleanup.
+It preserves replacements observed before removal, but retains the final
+pathname-recursive-removal gap described above; this helper does not expose
+`cleanupSafety: "require-bounded"`.
 The callback staging component is capped at 255 bytes as written and under NFC and NFD by
 shortening only an overlong embedded destination tail, while preserving an
 extension when possible. Short callback paths and the final target stay
-unchanged. This workspace owns its contents, unlike the unadmitted sibling
+unchanged. An unusable target basename causes `fallbackFileName` to pass through
+the same basename, character, reserved-device, and length sanitization before it
+is embedded; if neither candidate is usable, the fixed tail `file` is used. The
+completed component is then checked as a direct child before test hooks or the
+producer run. This workspace owns its contents, unlike the unadmitted sibling
 pathname above.
 
 ## Secure temp root
@@ -400,6 +567,7 @@ Consumers that only need this resolver can use the narrow package subpath:
 import {
   resolveSecureTempRoot,
   type ResolveSecureTempRootOptions,
+  type SecureTempRootDescriptorAdapter,
 } from "@openclaw/fs-safe/secure-temp-root";
 ```
 
@@ -424,12 +592,13 @@ type ResolveSecureTempRootOptions = {
   getuid?: () => number | undefined;
   tmpdir?: () => string;
   accessSync?: typeof import("node:fs").accessSync;
-  chmodSync?: typeof import("node:fs").chmodSync;
+  chmodSync?: typeof import("node:fs").chmodSync; // deprecated, never read or called
+  descriptor?: SecureTempRootDescriptorAdapter; // complete bundle; see below
   lstatSync?: (path: string) => {
     isDirectory(): boolean;
     isSymbolicLink(): boolean;
-    mode?: number;
-    uid?: number;
+    mode?: number | bigint;
+    uid?: number | bigint;
   };
   mkdirSync?: (
     path: string,
@@ -448,6 +617,61 @@ the fallback to mode `0o700` where mode bits apply. If it cannot establish that
 state, it throws an ordinary `Error`; there is no native mode or
 `helper-unavailable` branch on this API.
 
+Existing secure directories retain the one-`lstat`/access fast path, with no
+descriptor open or chmod. On POSIX, a directory created by this call is instead
+finalized through a pinned descriptor and must finish at exactly `0o700`, even
+when a privileged caller can access its initial restrictive mode. A concurrent
+recursive-`mkdir` winner is inspected as an untrusted existing directory.
+Broad-mode repair also uses a pinned descriptor; there is no pathname chmod.
+
+Repair and finalization require a known nonnegative safe-integer UID and exact
+bigint device, inode, owner, mode, and directory-type facts. They open with
+`O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK`, verify the descriptor and
+current directory entry against the initial receipt before `fchmod`, then
+verify identity, permissions, and write/search access again before closing.
+Trailing separators are stripped only for entry inspection, preserving filesystem
+roots and symlink-sensitive `..` components. Unknown, numeric, or malformed
+identity facts cannot authorize a mutation. A failed chmod is tolerated only for
+the existing `EPERM`/`EACCES`/`ENOENT` cases when the same exact pinned directory
+has concurrently become safe and accessible; it emits no repair warning.
+
+There is no search-only descriptor or `/proc` fallback. A newly created `000`
+directory that cannot be opened read-only is left in place; the resolver tries
+the secure fallback or throws. Actual Windows uses directory-type and access
+checks and performs no POSIX chmod, regardless of an injected `platform` value.
+Failures keep the ordinary `Error` contract; available underlying repair and
+close failures are retained in `cause`, including paired errors.
+
+The optional descriptor adapter is a complete authority bundle:
+
+```ts
+type SecureTempRootDescriptorAdapter = {
+  lstatSync(path: string, options: { bigint: true }): Pick<import("node:fs").BigIntStats,
+    "dev" | "ino" | "uid" | "mode" | "isDirectory" | "isSymbolicLink">;
+  fstatSync(fd: number, options: { bigint: true }): ReturnType<SecureTempRootDescriptorAdapter["lstatSync"]>;
+  openSync(path: string, flags: number): number;
+  fchmodSync(fd: number, mode: number): void;
+  closeSync(fd: number): void;
+  constants: { O_RDONLY: number; O_DIRECTORY: number; O_NOFOLLOW: number; O_NONBLOCK: number };
+};
+```
+
+Options, adapter functions, and flags are captured synchronously before callbacks.
+On POSIX a complete bundle supplies exact admission and repair observations,
+taking precedence over the legacy `lstatSync` hook. Partial bundles or unavailable
+flags make repair/finalization unavailable. Injecting `lstatSync`, `accessSync`,
+or `mkdirSync` disables the default host descriptor bundle. Injected observations
+also require an explicit `mkdirSync` for creation; supplying a descriptor bundle
+likewise never implicitly authorizes host mkdir. A custom mkdir requires the
+complete descriptor bundle for POSIX finalization. The deprecated `chmodSync`
+option is inert and alone does not disable normal host behavior.
+
+These checks bind chmod to the admitted object and reject observed replacements;
+the returned path is not a retained capability. Pathname access and identity
+checks remain separate syscalls, and another process can replace the path after
+the final check. Applications still need a trusted namespace or OS isolation
+when other processes can mutate it.
+
 ## Common patterns
 
 ### Build something, atomically place it

package/docs/test-hooks.md

@@ -31,10 +31,17 @@ type FsSafeTestHooks = {
   afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
   beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
   afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterOpenedPathIdentityCheck?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterRootReadPathResolution?: (filePath: string) => Promise<void> | void;
+  beforeRootReadFinalFence?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterRootReadFinalPathIdentityCheck?: (filePath: string, handle: FileHandle) => 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;
+  beforeRootStatObservation?: (targetPath: string) => Promise<void> | void;
+  beforeRootStatInitialObservation?: (targetPath: string) => Promise<void> | void;
+  beforeRootListObservation?: (directoryPath: string, withFileTypes: boolean) => Promise<void> | void;
   afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
   beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
   beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
@@ -49,10 +56,17 @@ 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. |
+| `afterOpenedPathIdentityCheck` | A standalone local-file or absolute copy-source descriptor matches its pathname and the generic opened-path resolver is about to run. Root reads use their final admission hooks instead. |
+| `afterRootReadPathResolution` | A Root read path was resolved and has not yet entered local-file open admission. |
+| `beforeRootReadFinalFence` | A Root read descriptor passed pre-open/descriptor identity and hardlink checks and is about to enter its single final root/path/canonical-path/root admission fence. |
+| `afterRootReadFinalPathIdentityCheck` | The final pathname-to-descriptor comparison passed and the second root check has not run. This hook is synchronous-only. |
 | `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. |
+| `beforeRootStatObservation` | `Root.stat()` admitted its exact target and parent and is about to collect returned metadata. |
+| `beforeRootStatInitialObservation` | `Root.stat()` admitted its exact parent and is about to inspect the target for the first time. |
+| `beforeRootListObservation` | `Root.list()` admitted its exact selected directory and is about to collect names and optional metadata. |
 | `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. |
 | `beforeSidecarLockSnapshotOpen` | A sidecar lock was inspected and is about to be opened for a bounded snapshot read. |

package/docs/writing.md

@@ -29,8 +29,8 @@ await fs.mkdir("snapshots/2026/05");
 ## What replacement writes do
 
 1. Resolve the relative target against the canonical root and reject anything that escapes (`outside-workspace`).
-2. If `mkdir: true`, create missing parent directories relative to a pinned parent fd in the native path, or with per-component identity guards in the JavaScript fallback.
-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. The JavaScript check cannot make the intervening pathname syscall atomic, so a same-privilege peer that can replace the parent may cause an out-of-root side effect before detection. Use native `require` mode for that threat model; see the [security model](security-model.md#symlinks-write-side).
+2. If `mkdir: true`, create missing parent directories relative to a pinned parent fd in the native path, or with per-component identity guards in the JavaScript fallback. When `denyMutations` or an explicit `mutationSymlinks` policy is present, each missing POSIX-native component is authorized before creation and its opened descriptor is authorized again before descent.
+3. Pin or guard the parent directory for the selected mechanism. Native operations use a parent fd and reapply configured mutation policy to the actual canonical destination selected by that descriptor; the pinned JavaScript fallback verifies directory identity before and after mutation and performs the same policy revalidation before its pathname dispatch. The JavaScript check cannot make the intervening pathname syscall atomic, so a same-privilege peer that can replace the parent may cause an out-of-root side effect before detection. Use native `require` mode for that threat model; see the [security model](security-model.md#symlinks-write-side).
 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.
@@ -74,7 +74,7 @@ await fs.write(".env", "x");       // throws FsSafeError code "denied-path"
 await fs.remove(".ssh/id_rsa");    // throws FsSafeError code "denied-path"
 ```
 
-`paths` blocks exact absolute paths. `prefixes` blocks absolute paths and everything below them. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a mutation through a symlinked ancestor to a denied path is still denied. Root-level and per-call policies are additive; per-call policy can add denies, but cannot clear root defaults.
+`paths` blocks exact absolute paths. `prefixes` blocks absolute paths and everything below them. For POSIX pinned `write`, `create`, and `copyIn`, an existing exact-path directory does not implicitly deny a mutation to its descendants, but creating a missing directory at that exact path is itself denied. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a mutation through a symlinked ancestor to a denied path is still denied. Root-level and per-call policies are additive; per-call policy can add denies, but cannot clear root defaults. Those POSIX pinned operations snapshot the merged policy before their first path observation, then authorize the actual descriptor-selected parent before staging or publication. A caller mutation of the original arrays, or a contained parent redirect after preflight, cannot clear that admission check.
 
 ## Write verbs
 
@@ -268,16 +268,35 @@ await fs.move("incoming/foo.txt", "archive/foo.txt", { overwrite: true });
 
 Both `from` and `to` are bounded; `..` in either is rejected.
 
-The JavaScript fallback checks both parent directories before and after the
-rename. A failed post-operation check rejects even though the rename may
-already have completed; rejection does not imply rollback.
+The default no-clobber mode requires the native helper. It admits both parent
+directory descriptors and performs a descriptor-relative no-replace rename, so
+a competitor that creates the target first is preserved and the source remains
+in place. If the helper or safe parent admission is unavailable, the call fails
+with `helper-unavailable`; it never falls back to a check followed by a
+replacing rename. After dispatch it rechecks both parent identities, so a
+post-operation rejection can mean the no-replace rename completed. Directory
+moves continue to require `overwrite: true`.
+
+Both selected canonical endpoints are admitted inside the retained Root after
+native parent admission. With `mutationSymlinks: "reject"`, both full operation
+paths are rechecked after the live mutation-authority callback and before
+dispatch. The Root and retained parents are fenced again after any such callback.
+These checks retain the documented final check-to-syscall race.
+
+For `{ overwrite: true }`, the JavaScript path checks both parent directories
+before and after the rename. A failed post-operation check rejects even though
+the rename may already have completed; rejection does not imply rollback.
 
 ### `fs.remove(rel)`
 
 Unlink a file or `rmdir` an empty directory. Non-empty directories throw `not-empty`. For atomic directory replacement, use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
 
-The JavaScript fallback reports failed parent-directory checks after removal.
-The entry may already have been removed when this verification rejects.
+Before a nonrecursive JavaScript fallback removal, fs-safe retains exact
+Root-to-parent directory identities, with canonical endpoint checks at Root and
+the immediate parent. It rejects a parent redirected through a symlink or
+junction before `unlink` or `rmdir`, even with `force: true`, and rechecks the
+retained ancestry after the operation settles. The entry may already have been
+removed when that final verification rejects.
 
 ```ts
 await fs.remove("logs/yesterday.log");
@@ -426,6 +445,13 @@ opens, including for mode `0o200` files; replacement truncation happens only
 after type, identity, and boundary checks pass. Rejected existing paths are
 never cleanup-owned or unlinked.
 
+Identity admission uses bigint descriptor and pathname receipts even though the
+public `stat` field remains a numeric Node `Stats` object. Windows retries an
+unknown device or file index once while retaining known components, then rejects
+persistent ambiguity. If admission of a newly created file fails, cleanup only
+unlinks a pathname that still has the exact created identity; rounded aliases,
+symlinks, and unknown identities are preserved.
+
 ## Write defaults vs per-call options
 
 Set `mkdir: true` once on `root()`; pass text encodings per call when needed:
@@ -507,6 +533,10 @@ await fs.write("state.json", body); // succeeds on rclone FUSE
 
 **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.
 
+Windows `Root.write()` and `Root.writeJson()` honor this policy both as a Root default and as a per-call option. The Windows buffered writer acquires the same Root compatibility lock before creating parents, placeholders, or content. It keeps staging writable until publication, then applies the final mode through the retained destination descriptor. When content verification accepts a changed rename identity, that destination remains pinned through file sync, parent sync, and final strict identity checks.
+
+The Windows buffered compatibility path resolves permitted in-root aliases before choosing its lock and binds publication to that effective destination. With the existing lock protocol, effective path components beneath the Root must contain only lower-case ASCII letters, digits, `.`, `_`, or `-`, with no trailing `.`. Unsupported spellings, including missing upper-case or non-ASCII names, fail with `path-alias` before mutation; no filesystem case-sensitivity or Unicode-folding behavior is guessed. This restriction does not apply to strict writes. Opaque Windows pathname identities still use strict verification against the retained original descriptor: they never, by themselves, authorize content-based acceptance of a replacement.
+
 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).
 
 ## See also

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -167,18 +167,18 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.12.0",
-    "@openclaw/fs-safe-darwin-x64": "0.12.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.12.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.12.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.12.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.12.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.12.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.13.1",
+    "@openclaw/fs-safe-darwin-x64": "0.13.1",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.13.1",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.13.1",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.13.1",
+    "@openclaw/fs-safe-linux-x64-musl": "0.13.1",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.13.1",
     "jszip": "^3.10.2"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.5",
-    "@napi-rs/cli": "3.9.0",
+    "@napi-rs/cli": "3.9.1",
     "@types/node": "^26.5.1",
     "@vitest/coverage-v8": "5.0.0",
     "fast-check": "^4.9.0",
@@ -188,7 +188,7 @@
     "sigstore": "5.0.0",
     "tar": "7.5.22",
     "typescript": "^7.0.2",
-    "vite": "8.2.2",
+    "vite": "8.3.0",
     "vitest": "^5.0.0"
   },
   "engines": {