@openclaw/fs-safe 0.5.1 → 0.5.2

package/docs/native-helper.md

@@ -30,21 +30,27 @@ Configure the mode once during startup. Loading is lazy and cached; changing fro
 ## Native boundary
 
 The bundled native layer exposes policy-free filesystem mechanisms: beneath-root
-open/mkdir/link, no-replace rename, identity reads, archive decode/execution,
+open/mkdir/link, replace and no-replace rename, identity reads, archive decode/execution,
 clone/copy/hash workers, and Windows security descriptor calls. The TypeScript
 layer owns policy, retries, filters, budgets, modes, cleanup, error
 normalization, and the decision to fall back.
 
-- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS` and `renameat2(RENAME_NOREPLACE)`.
-- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. No-replace publication uses `renameatx_np(RENAME_EXCL)`.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points, and uses `FileRenameInfoEx` with replacement disabled.
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`.
+- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer.
 
-Native primitives back create-only pinned writes, async sidecar creation,
+Native primitives back create-only and replacing pinned writes, async sidecar creation,
 guarded publication, archive acceleration, and direct Windows ACL operations.
 Equivalent JavaScript paths remain available for documented fallback-capable
 features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
 for the exact difference.
 
+The guarded JavaScript mutation path is detection-based, not containment-atomic.
+If a same-privilege peer can replace a writable parent after its identity guard
+but before Node resolves a pathname mutation, the mutation can land outside the
+intended root before the post-operation guard throws. Select `require` rather
+than `auto` or `off` when that concurrent attacker is part of the threat model.
+
 `openBeneath()` returns `{ fd, containment }`. `containment` is
 `"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
 Windows. Public JavaScript root open/read/writable results also expose the

package/docs/native.md

@@ -41,7 +41,7 @@ The TypeScript layer validates and decides. The native layer never decides
 whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
 - Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
-  `mkdirat`/`linkat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+  `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
 - macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
   components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
   pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
@@ -99,7 +99,7 @@ remain TypeScript-owned. What changes is the syscall strength or availability:
 
 | Capability | Native path | Guarded JavaScript path |
 |---|---|---|
-| Root-relative opens/mutations | Descriptor-relative beneath operations. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. A hostile same-UID peer has a wider pathname race window. |
+| Root-relative opens/mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves the pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
 | ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | JSZip/node-tar into a private stage, then the same guarded merge policy. |
 | Zstd/bzip2 TAR | Supported. | Unsupported; typed `helper-unavailable`. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |

package/docs/output.md

@@ -51,8 +51,11 @@ root"; callers should choose the filename before calling this API.
 Use `maxBytes` when the external producer can create arbitrarily large files,
 and `mode` when the finalized file needs a specific POSIX mode. Both staging
 modes enforce them after the producer returns and before committing the target.
-Requested basenames containing C0/C1 controls or Windows-invalid characters are
-sanitized portably; `fallbackFileName` supplies the name when nothing remains.
+Requested basenames containing C0/C1 controls or Windows-invalid characters go
+through the package's filename sanitizer; `fallbackFileName` supplies the name
+when nothing remains. This removes traversal, device-name, and invalid-character
+hazards but does not trim Windows-normalized trailing dots or spaces; reject or
+rewrite those when cross-platform filename uniqueness matters.
 The same sanitized basename is used for producer staging, guarded internal
 temps, the final rename target, and the returned `path`; raw and staged names
 never diverge.
@@ -73,7 +76,9 @@ and size-limit violations, applies `mode`, fsyncs it, and atomically renames it
 over the target. Existing files and symlink entries are replaced without
 following their contents or referents. The parent identity is guarded across
 the operation and the parent directory is synchronized best-effort after
-rename.
+rename. If an error leaves the sibling temp in place and immediate cleanup
+fails, its verified identity remains registered for a best-effort process-exit
+cleanup retry.
 
 ## Why not pass the final path to the library?
 

package/docs/path-scope.md

@@ -77,7 +77,10 @@ Async. Strict variant: every input must already exist as a regular file inside t
 
 ### `writable(rel, options?)`
 
-Async. Resolves a writable target: ensures the parent directory exists inside the scope, refuses targets whose existing inode is a symlink or hardlinked, and returns the absolute path to use for the write.
+Async. Resolves a writable target: requires the parent directory to already
+exist canonically inside the scope, refuses targets whose existing inode is a
+symlink or hardlinked, and returns the absolute path to use for the write. Use
+`ensureDir()` first when the parent needs to be created.
 
 ```ts
 const t = await uploads.writable("reports/2026/05/report.pdf");

package/docs/path.md

@@ -19,7 +19,9 @@ import {
 } from "@openclaw/fs-safe/path";
 ```
 
-Only `root()`, `FsSafeError`, and the native helper config live on the main entry. Path helpers are deliberately a subpath import so the main entry stays small.
+Path helpers are deliberately a subpath import so the main entry stays focused
+on the root capability, its shared configuration, errors, and external-output
+helper.
 
 ## Boundary checks
 
@@ -62,7 +64,7 @@ Convenience wrapper around `isPathInside`. Same semantics, different name kept f
 Resolve a base directory to an absolute, normalized form ready for prefix comparison. Pre-normalized directories make subsequent `isPathInside` checks unambiguous.
 
 ```ts
-const base = resolveSafeBaseDir("/srv/uploads/.");  // "/srv/uploads"
+const base = resolveSafeBaseDir("/srv/uploads/.");  // "/srv/uploads/"
 ```
 
 ## Realpath and stat
@@ -80,7 +82,9 @@ All `realpath` failures collapse to `null` — there is no distinction between `
 
 ### `safeStatSync(targetPath)`
 
-Synchronous `stat` that returns `null` instead of throwing on missing paths. Returns `Stats` on success.
+Synchronous `stat` that returns `Stats` on success and `null` on any failure,
+including missing paths and permission errors. Use `fs.statSync` directly when
+the distinction matters.
 
 ```ts
 const stat = safeStatSync("/srv/uploads/photo.jpg");

package/docs/permissions.md

@@ -38,6 +38,10 @@ isWorldReadable(bits);
 isGroupReadable(bits);
 ```
 
+POSIX remediation strings shell-quote paths with whitespace or metacharacters
+and protect option-like paths with `--`, so they can be presented as commands
+without letting the inspected pathname add shell syntax.
+
 `inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. Secure reads and callers that protect credential-bearing execution require `ownerTrusted === true`.
 
 ## Advanced Windows ACL helpers
@@ -67,6 +71,10 @@ resolveWindowsUserPrincipal(env);
 The fallback Windows inspector calls `icacls.exe <path>` using its supported
 path-only inspection syntax and classifies principals as trusted, world, or
 group. Trusted defaults include the current user, SYSTEM, and Administrators.
+Built-in PowerShell, `icacls.exe`, and `whoami.exe` invocations have a fixed
+30-second per-process deadline. A command failure or timeout returns an
+unverified result (`source: "unknown"`) so callers fail closed. Advanced callers
+that inject a custom `exec` implementation own that executor's deadline.
 The parser is on the advanced surface so tests and CLIs can process captured
 `icacls` output without spawning a process.
 

package/docs/public-api.md

@@ -0,0 +1,109 @@
+# Public API inventory
+
+This page closes the gap between the narrative guides and the complete package
+surface. The generated declarations define the exact signatures; the lists
+below name the lower-frequency exports that are easy to miss when reading only
+the focused guides. `test/public-api.json` guards the same inventory during
+pack checks.
+
+## Main entry and `root`
+
+The main entry and `@openclaw/fs-safe/root` expose the root capability types,
+including `ContainmentGuarantee`, `RootOpenOptions`, `RootCreateOptions`,
+`RootCreateJsonOptions`, and `WritableOpenMode`. The root-bounded iterator uses
+`RootWalkOptions`, `RootWalkEntry`, `RootWalkDataEntry`, `RootWalkEntryKind`,
+`RootWalkDataEntryKind`, `RootWalkSymlinkPolicy`, `RootWalkLimitBehavior`,
+`RootWalkDirectoryErrorBehavior`, `RootWalkEntryFilter`, and
+`RootWalkEntryFilterResult`.
+
+The root subpath also exports `openLocalFileSafely`, `readLocalFileSafely`, and
+`resolveOpenedFileRealPathForHandle` for trusted absolute-file composition.
+They do not create a root boundary around arbitrary caller input; prefer
+`root()` for untrusted paths.
+
+The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`. The
+deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
+
+## `path` and `advanced`
+
+The lexical path surface additionally exports `isNodeError`,
+`isPathRelativeEscape`, `normalizeWindowsPathForComparison`,
+`resolveSafeRelativePath`, `splitSafeRelativePath`, and
+`matchUnsafeDeviceReadPath`. The device matcher is described by
+`UnsafeDeviceReadPathMatch`, `UnsafeDeviceReadPathOptions`, and
+`UnsafeDeviceReadPathReason`.
+
+The advanced root-file primitive exports `OpenRootFileParams`,
+`OpenRootFileSyncParams`, `RootFileOpenResult`, and
+`RootFileOpenFailureReason`. These are composition types for callers building
+their own pinned-open flow, not substitutes for the higher-level `Root` verbs.
+
+## `json` and `store`
+
+Standalone structured reads use `ReadJsonOptions`, `ReadRootJsonSyncOptions`,
+`ReadRootStructuredFileSyncOptions`, and `RootStructuredFileReadResult`.
+
+The store surface additionally exports `FileStoreReadOptions` and
+`JsonFileStoreOptions`. Durable-queue inspection and recovery use
+`jsonDurableQueueEntryExists`, `loadJsonDurableQueueEntry`,
+`readJsonDurableQueueEntry`, and the `JsonDurableQueueLoadOptions` and
+`JsonDurableQueueReadResult` types. `unlinkBestEffort` is the explicitly
+best-effort cleanup helper used by those queue flows.
+
+## Permissions and secure files
+
+Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
+Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
+descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
+`WindowsAceFlags`.
+
+Secure reads split their option and result shapes into
+`SecureFileTrustOptions`, `SecureFilePermissionOptions`,
+`SecureFileInjectOptions`, `SecureFileIoOptions`, and `SecureFileReadResult`.
+
+## Locks, walking, and temp workspaces
+
+The file-lock diagnostics surface includes `FileLockHeldEntry`,
+`FileLockStaleRecovery`, and `SidecarLockCompromisedInfo`.
+`drainFileLockManagerForTest` and `resetFileLockManagerForTest` are test-only
+manager controls; production code should not use them as lock recovery.
+
+Standalone walkers use the `WalkEntryKind` and `WalkSymlinkPolicy` unions.
+Private workspaces expose `TempPathIdentityReceipt` and the
+`TempWorkspaceCleanupResult` union so callers can distinguish removal,
+absence, and identity mismatch.
+
+## Atomic replacement and durability
+
+Atomic helper option and receipt types include
+`MovePathWithCopyFallbackOptions`, `ReplaceDirectoryAtomicOptions`,
+`ReplaceFileAtomicSyncOptions`, `ReplaceFileAtomicResult`,
+`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`, and
+`ReplaceFileDestinationHardlinkPolicy`.
+
+The durability surface also exports the synchronous strict
+`syncDirectorySync`, plus `DirectoryReceipt`, `DurableDirectoryReceipt`,
+`EnsureDurableDirectoryOptions`, `PublishFileExclusiveResult`,
+`PublishFileExclusiveStrategy`, `PublishFileExclusiveCleanup`,
+`PublishFileExclusiveFailurePhase`,
+`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`, and
+`Sha256FileResult`.
+
+## Archives
+
+Archive option and policy types are `ExtractArchiveOptions`,
+`ArchiveEntryFilter`, `ArchiveEntryModePolicy`, and
+`ArchiveFilteredEntryPolicy`. Typed error-code unions are
+`ArchiveFormatErrorCode`, `ArchiveLimitErrorCode`, and
+`ArchiveSecurityErrorCode`. TAR and ZIP preflight composition uses
+`TarEntryInfo` and `ZipArchiveWithFiles`.
+
+`createArchiveSymlinkTraversalError` constructs the typed traversal failure
+used by extractors. `resolvePackedRootDir` finds the single packed root when an
+archive layout permits it; neither helper weakens entry validation.
+
+## Keeping this list honest
+
+Every runtime and type name in `test/public-api.json` must appear somewhere in
+`README.md` or `docs/`. Documentation examples are also checked so a named
+import cannot silently move to another package subpath.

package/docs/quickstart.md

@@ -18,7 +18,11 @@ const fs = await root("/srv/jobs/incoming", {
 
 `root()` resolves the directory through the real filesystem (so symlinked roots become canonical) and verifies it exists. The defaults you pass apply to every call below; per-call options override them.
 
-If the root directory itself does not exist yet, `root()` throws `FsSafeError` with code `not-found`. Either create the directory before calling `root()`, or call `await fs.ensureRoot()` after a successful `root()` to create empty subpaths.
+If the root directory itself does not exist yet, `root()` throws `FsSafeError`
+with code `not-found`; create it before constructing the capability.
+`fs.ensureRoot()` is for generic code that needs to assert or recreate the root
+itself after a handle was successfully constructed. It does not accept a
+subpath and cannot bootstrap a root that prevented `root()` from returning.
 
 ## 2. Read and write text
 
@@ -62,7 +66,7 @@ await fs.remove("notes/archive/today.txt");
 
 ```ts
 const here = await fs.exists("state/config.json"); // boolean
-const stat = await fs.stat("state/config.json");   // { kind, size, mtimeMs, ... }
+const stat = await fs.stat("state/config.json");   // { isFile, isDirectory, size, mtimeMs, ... }
 const names = await fs.list("state");              // string[]
 const entries = await fs.list("state", { withFileTypes: true }); // DirEntry[]
 ```

package/docs/reading.md

@@ -14,12 +14,12 @@ const opened = await fs.open("large.log");               // FileHandle for strea
 
 Regardless of shape, every read goes through the same boundary checks:
 
-1. Resolve the relative path against the canonical real root.
-2. Reject anything that escapes the root (`outside-workspace`).
-3. Reject `..` segments and absolute inputs (unless via `readAbsolute` with an in-root absolute path).
-4. Reject known unsafe device and process-fd paths before opening (`device-path`).
-5. Open with `O_NOFOLLOW` where available. A symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
-6. Stat the open fd and compare to the resolved path's identity (`sameFileIdentity`). A swap mid-call triggers `path-mismatch`.
+1. Resolve the input lexically against the canonical real root.
+2. Reject a lexically explicit unsafe device or process-fd namespace (`device-path`). This check precedes component alias policy because paths such as `/dev/fd` are themselves symlinks on common Linux hosts.
+3. Resolve path components and reject anything that escapes the root (`outside-workspace`).
+4. Reject `..` traversal and absolute spellings when they resolve outside the root. In-root absolute spellings remain accepted; `readAbsolute` makes that intent explicit.
+5. Open with `O_NOFOLLOW` where available. Any remaining symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
+6. Compare the pre-open path identity, the open fd, and the post-open resolved path (`sameFileIdentity`). A swap mid-call triggers `path-mismatch`.
 7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
 8. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
 
@@ -36,7 +36,8 @@ console.log(`${stat.size} bytes at ${realPath}`);
 
 ### `fs.readText(rel, options?)`
 
-`buffer.toString(encoding)`. Defaults to `defaults.encoding ?? "utf8"`. Pass `encoding` per call to override:
+`buffer.toString(encoding)`. Defaults to `"utf8"`; encoding is a per-call text
+option, not a `RootDefaults` field:
 
 ```ts
 const utf16 = await fs.readText("doc.txt", { encoding: "utf16le" });
@@ -83,14 +84,14 @@ try {
 type RootReadOptions = {
   hardlinks?: "reject" | "allow";   // override defaults.hardlinks
   maxBytes?: number;                // refuse reads larger than this many bytes
-  nonBlockingRead?: boolean;        // schedule the read off the main loop
+  nonBlockingRead?: boolean;        // compatibility hint; safe opens are already nonblocking where supported
   symlinks?: "reject" | "follow-within-root"; // override defaults.symlinks
 };
 ```
 
 `maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory.
 
-`nonBlockingRead` is a scheduling hint. It does not affect safety — it lets you keep the event loop responsive when reading large files.
+`nonBlockingRead` remains as a compatibility hint. Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely; regular-file descriptor reads retain normal Node behavior.
 
 ## `readAbsolute()` and `reader()`
 
@@ -101,7 +102,9 @@ fs.readAbsolute(absPath, options?)   // ReadResult, abs path must be inside the
 fs.reader(options?)              // (path) => Promise<Buffer>
 ```
 
-`readAbsolute` accepts absolute paths. Anything outside the root throws `outside-workspace`.
+`readAbsolute` accepts absolute paths. Anything outside the root throws
+`outside-workspace`. It also accepts relative paths for compatibility, but use
+`read()`/`readBytes()` when the input contract is explicitly relative.
 
 `reader()` returns a closure that takes either a relative or an absolute path and returns a Buffer. Useful for plugging `fs-safe` into framework loader hooks:
 

package/docs/root.md

@@ -21,9 +21,10 @@ type RootDefaults = {
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
-  mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append
+  mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append; default true
   mode?: number;                   // file mode applied to new writes; per-call override available
-  nonBlockingRead?: boolean;       // schedule reads on a worker; useful for large files
+  nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
+  renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
   symlinks?: "reject" | "follow-within-root"; // policy when a path component is a symlink
 };
 
@@ -83,6 +84,10 @@ await using opened = await fs.open("large.log");
 `containment: "best-effort"`. The field reports the mechanism used; see the
 [security model](security-model.md#containment-guarantees-by-platform).
 
+The read methods also accept an absolute spelling that already resolves inside
+the root. `readAbsolute()` and `reader()` make that intent explicit; an absolute
+path outside the root is still rejected.
+
 ### Writes
 
 ```ts
@@ -103,6 +108,14 @@ fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 
 `copyIn` is a one-shot ingest from a trusted absolute source path: it streams the source through the boundary, atomically renames into the root, and respects `maxBytes`.
 
+Root operations that choose a new destination reject a leading Windows
+drive-relative spelling such as `C:name` on every platform. This applies to
+`write`, `create`, `append`, `openWritable`, `mkdir`, `copyIn`, and the
+destination argument of `move`. In particular, `copyIn(path.basename(source),
+source)` can reject a legal POSIX basename such as `c:photo.png`; callers that
+derive portable destination names from host files must sanitize or map that
+basename first.
+
 `openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Use it for streaming output. Prefer `await using` for cleanup.
 
 All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
@@ -119,6 +132,12 @@ 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.
 
+`resolve()` is the exception to the existing-object rule: because it selects a
+location for later use, it rejects a leading drive-relative spelling. Reads,
+`stat`, `exists`, `list`, `walk`, `remove`, and the source argument of `move`
+accept an existing POSIX filename such as `c:notes.txt`. For `move`, only the
+new destination name is subject to the portable guard.
+
 ## Native helper mode
 
 Create-only writes prefer the bundled native helper for fd-relative opens and
@@ -147,11 +166,14 @@ fs.defaults      // the RootDefaults you passed
 
 ## Failure semantics
 
-Every method throws `FsSafeError` with a `code`. Branch on `err.code`, not message text. Common codes:
+Boundary and policy failures throw `FsSafeError` with a `code`. Parsing callbacks
+and underlying filesystem operations can also surface `SyntaxError` or native
+`NodeJS.ErrnoException` values. Branch on `err.code`, not message text, after
+checking `err instanceof FsSafeError`. Common fs-safe codes:
 
 | Code | When it fires |
 |---|---|
-| `invalid-path` | The input path is malformed, including embedded NUL bytes. |
+| `invalid-path` | The input path is malformed, including embedded NUL bytes. Portable relative-path helpers and `FileStore` keys reject drive-relative segments; Root destination and resolution operations reject a leading drive-relative spelling such as `C:name`. |
 | `outside-workspace` | The input resolves outside the root, or contains a `..` segment that would escape it. |
 | `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). |
 | `not-file` | A read or copy targeted a non-regular file (directory, FIFO, socket, …). |

package/docs/secret-file.md

@@ -23,7 +23,7 @@ import {
 | The file is a credential (token, key, password). | The file is application state. |
 | You want the parent directory created at `0o700` if missing. | You don't care about the parent directory mode. |
 | You want a hard size cap on reads (to defend against bogus input). | You're reading bounded JSON state. |
-| Mode `0o600` is mandatory, not just nice. | Mode is whatever umask gives you. |
+| Mode `0o600` and the private parent policy are mandatory. | Standalone `writeJson` also defaults to `0o600`, but it does not enforce the secret-directory ownership and permission policy. |
 
 ## Constants
 
@@ -39,7 +39,10 @@ The 16 KiB cap is intentionally aggressive — credentials should be small. If y
 
 ### `tryReadSecretFileSync(filePath, label, options?)`
 
-The lenient reader. Returns the trimmed secret string, or `undefined` when the path is missing or blank. Validation failures, unreadable files, oversized files, symlinks, and hardlinks throw `FsSafeError` so callers fail closed on suspicious credential state.
+The missing-is-optional reader. It returns the trimmed secret string, or
+`undefined` when the `filePath` argument is absent/blank or the target does not
+exist. An existing empty file is invalid and throws, as do unreadable,
+oversized, symlink, hardlink, and other validation failures.
 
 ```ts
 import { tryReadSecretFileSync } from "@openclaw/fs-safe/secret";
@@ -65,12 +68,22 @@ const token = readSecretFileSync("/var/lib/app/auth.token", "auth token");
 ```ts
 type SecretFileReadOptions = {
   maxBytes?: number;         // default DEFAULT_SECRET_FILE_MAX_BYTES (16 KiB)
-  rejectSymlink?: boolean;
+  rejectSymlink?: boolean;   // default false
   rejectHardlinks?: boolean; // default true
 };
 ```
 
-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.
+The reader trims the file content and rejects empty results. Symlink paths are
+followed and pinned by default; set `rejectSymlink: true` when the pathname
+itself must not be an alias. Hardlinks are rejected by default so another
+in-tree name cannot alias the credential; pass `rejectHardlinks: false` only
+when you explicitly trust that layout.
+
+These readers do not enforce ownership or mode bits on an existing file. Their
+read contract covers pinned identity, file type, link policy, and byte bounds;
+the `0o600` guarantee belongs to the write helpers below. Use
+[`readSecureFile`](secure-file.md) when reading an externally managed
+credential must also fail on broad permissions or unexpected ownership.
 
 `readSecretFile()` and `tryReadSecretFile()` are asynchronous counterparts with
 the same pinned-handle validation, byte cap, trimming, error codes, and strict

package/docs/security-model.md

@@ -22,7 +22,8 @@ case since `5ddca80`. Exposure is limited to consumers that call
 You hand a `root()` boundary to a piece of code that takes caller-controlled relative paths. The library defends against a caller that:
 
 - supplies `..` traversal segments to escape the boundary
-- supplies an absolute path where a relative one is expected
+- supplies an absolute path outside a configured root, or to an API whose input
+  contract is strictly relative/portable
 - replaces a path component with a symlink between check and use (TOCTOU)
 - replaces the destination directory with a symlink right before a write
 - creates a hardlink that aliases an out-of-tree inode and asks you to read or replace it
@@ -44,7 +45,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`. 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`.
+Every 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, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
 
 ### Symlinks (read side)
 
@@ -54,7 +55,20 @@ Per-call `symlinks: "follow-within-root"` allows symlinks whose final target is
 
 ### Symlinks (write side)
 
-Writes use a sibling-temp + rename helper that opens the parent directory by fd, then performs the rename `at` the parent fd. Replacing the parent directory with a symlink between the parent-fd open and the rename does not divert the write.
+With the native binding loaded, `write()`, `create()`, and `copyIn()` use a
+sibling temp file and create parents and publish the target relative to pinned
+directory descriptors. Replacement uses descriptor-relative rename just like
+no-replace publication, so replacing the parent pathname does not divert the
+mutation.
+
+The JavaScript fallback used by `off`, by `auto` when no binding loads, and by
+the explicit `renameIdentity: "verify-content-with-lock"` compatibility policy
+cannot provide that guarantee because Node exposes no `mkdirat` or `renameat`.
+It asserts directory identity around a pathname mutation and detects many
+swaps, but detection occurs after the kernel may already have followed a new
+parent symlink. A same-privilege peer with write access to the parent can
+therefore cause an out-of-root side effect before the operation throws. Use
+native `require` mode when concurrent hostile mutation is in scope.
 
 ### Hardlink aliasing
 
@@ -64,13 +78,15 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 `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.
 
+A `root()` handle also remembers the canonical root directory identity. Calls fail with `path-mismatch` if that canonical pathname is replaced, including advisory inspection and walking calls, rather than following a replacement root into another tree.
+
 ### Denied mutations
 
 `denyMutations` is an opt-in application policy for `root()` mutation methods. It blocks exact absolute paths with `paths` and whole subtrees with `prefixes`, merging root defaults with per-call entries so a call cannot clear root-level denies. This is not an OS permission boundary: code with access to `node:fs`, a shell, or another process with the same filesystem privileges can bypass it.
 
 ### Atomic writes
 
-`replaceFileAtomic` writes to a sibling temp file in the destination directory, optionally `fsync`s it, optionally `fsync`s the parent directory after rename, and atomically renames over the destination. On failure mid-write, the destination is either the old contents (rename never happened) or the new contents (rename succeeded). There is no half-written intermediate state visible at the destination path.
+`replaceFileAtomic` writes to a sibling temp file in the destination directory, optionally `fsync`s it, optionally `fsync`s the parent directory after rename, and atomically renames over the destination. On failure mid-write, the destination is either the old contents (rename never happened) or the new contents (rename succeeded). There is no half-written intermediate state visible at the destination path unless the caller explicitly enables `copyFallbackOnPermissionError`, whose default `copyFallbackRestore: "none"` contract may leave a partial destination after a failed in-place fallback.
 
 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.
 
@@ -120,6 +136,7 @@ The public `OpenResult`, `ReadResult`, and `WritableOpenResult` expose `containm
 | 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 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. |
+| JavaScript mutations are detection-based | Without the native binding, Node pathname mutations retain a check-to-syscall race. A writable parent can be swapped so a create, rename, or removal affects an out-of-root path before the fallback detects identity drift. |
 | 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. |

package/docs/sidecar-lock.md

@@ -96,6 +96,12 @@ type FileLockRetryOptions = {
 result is passed to `shouldReclaim` and `shouldRemoveStaleLock`, allowing PID,
 process-start, argv, or role schemas to remain application-owned.
 
+On Windows, a pathed `EPERM` from creating or opening the lock file can be a
+short teardown race after another holder unlinks it. The async lock retries that
+specific denial at most eight times. A parent-directory denial, a denial from a
+callback, or a ninth consecutive lock-file denial surfaces as the original
+`EPERM`; it is not converted to `file_lock_timeout`.
+
 ## Owner-scoped reentrancy
 
 Version 0.5 removes the unsound process-scoped `allowReentrant` boolean and
@@ -167,10 +173,10 @@ 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.
+retry, payload parsing, stale policy, owner-scoped reentrancy, guarded
+identity-conditioned reclaim, verification, and compromise monitoring. They do
+not use the async manager queue or support async callbacks. Retry waits block
+the calling thread; use the async API in request-serving code.
 
 Always release in a `finally`:
 
@@ -236,7 +242,11 @@ await locks.drain();
 
 ## Stale policy: `shouldReclaim`
 
-The default policy treats locks whose `createdAt` is older than `staleMs` as stale. Pass a custom callback when you want a richer notion of "is the holder still alive":
+The default policy treats locks whose valid `createdAt` is older than `staleMs`
+as stale. A valid current or future timestamp remains authoritative under
+filesystem clock skew; only absent or malformed timestamps fall back to the
+sidecar `mtime`. Pass a custom callback when you want a richer notion of "is the
+holder still alive":
 
 ```ts
 import { kill } from "node:process";

package/docs/temp.md

@@ -157,11 +157,15 @@ type TempFile = {
   path: string;                            // absolute path; safe to write to
   dir: string;                             // the enclosing private workspace dir
   file(fileName?: string): string;          // resolve another file in the same dir
-  cleanup(): Promise<void>;                 // removes the private workspace dir
+  cleanup(): Promise<void>;                 // removes the original private workspace dir
   [Symbol.asyncDispose](): Promise<void>;   // alias of cleanup()
 };
 ```
 
+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.
+
 ### `withTempFile`
 
 Same shape with auto-cleanup:
@@ -239,13 +243,41 @@ const tempRoot = resolveSecureTempRoot({ fallbackPrefix: "my-app" });
 
 ```ts
 type ResolveSecureTempRootOptions = {
-  fallbackPrefix: string;   // base name for the per-user fallback dir
-  preferredDir?: string;    // optional preferred secure temp root
-  tmpdir?: () => string;    // override os.tmpdir()
+  fallbackPrefix: string;             // one portable path segment; invalid values throw
+  preferredDir?: string;              // preferred secure temp root
+  skipPreferredOnWindows?: boolean;
+  unsafeFallbackLabel?: string;       // text used in thrown errors
+  warningPrefix?: string;             // default "[fs-safe]"
+  warn?: (message: string) => void;    // default console.warn
+
+  // Platform/test adapters; production callers normally omit these.
+  platform?: NodeJS.Platform;
+  getuid?: () => number | undefined;
+  tmpdir?: () => string;
+  accessSync?: typeof import("node:fs").accessSync;
+  chmodSync?: typeof import("node:fs").chmodSync;
+  lstatSync?: (path: string) => {
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    mode?: number;
+    uid?: number;
+  };
+  mkdirSync?: (
+    path: string,
+    options: { recursive: boolean; mode?: number },
+  ) => void;
 };
 ```
 
-The directory name embeds the user's UID (POSIX) or username so multi-user systems don't collide. On unsupported platforms, falls back to `os.tmpdir()` directly with a `helper-unavailable` error code surfaced to callers that explicitly required the secure root.
+When `process.getuid()` is available, the fallback is
+`<tmpdir>/<fallbackPrefix>-<uid>`. Without a UID (including Windows), it is
+`<tmpdir>/<fallbackPrefix>`; no username is appended. The helper never returns
+the shared `os.tmpdir()` directory itself. It requires the selected path to be
+a writable, non-symlink directory and, when UID/mode facts are available,
+owned by the current user without group/world write bits. It creates or repairs
+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.
 
 ## Common patterns