@openclaw/fs-safe 0.12.0 → 0.13.1

package/docs/path.md

@@ -37,6 +37,10 @@ isPathInside("/srv/uploads", "/srv/uploads");                // true (root itsel
 ```
 
 The check is platform-aware: on Windows, paths are normalized for case and separator before comparison. This is deliberately a string-only, lexical answer; case folding does not prove that two differently cased prefixes name the same directory on a case-sensitive Windows directory. Root operations perform their own filesystem-identity admission when containment depends on case folding.
+It is a lexical comparison, not a filesystem-admission boundary: it does not
+reject Windows alternate data streams or index-allocation aliases. Use a
+filesystem operation such as `root()` when a caller-controlled path will be
+opened or mutated.
 
 ### `isPathInsideWithRealpath(rootDir, target, opts?)`
 
@@ -54,6 +58,9 @@ type Options = {
 ```
 
 Does not throw on missing inputs — `realpath` failures are absorbed by the underlying `safeRealpathSync`. By default (`requireRealpath: true`) the function returns `false` when either input cannot be resolved. Pass `{ requireRealpath: false }` to fall back to the lexical answer from `isPathInside` instead.
+On Windows it returns `false` for namespace aliases in either raw input or in
+a canonical value returned by `realpath` or the supplied cache. The
+`requireRealpath: false` fallback does not admit those aliases.
 
 ### `isWithinDir(rootDir, targetPath)`
 
@@ -79,12 +86,16 @@ if (real === null) return notFound();
 ```
 
 All `realpath` failures collapse to `null` — there is no distinction between `ENOENT`, `EACCES`, and other I/O errors. Use `fs.realpathSync` directly if you need to branch on the error code.
+This convenience wrapper preserves ordinary Node `realpath` semantics; it is
+not a caller-path admission boundary on its own.
 
 ### `safeStatSync(targetPath)`
 
 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.
+Like `safeRealpathSync`, it does not apply the pathname-admission policy used
+by the higher-level filesystem boundaries.
 
 ```ts
 const stat = safeStatSync("/srv/uploads/photo.jpg");

package/docs/private-file-store.md

@@ -47,6 +47,20 @@ fileStoreSync({ rootDir: "/var/lib/app", private: true }).writeJson("config.json
 The sync store intentionally exposes a smaller surface: path resolution,
 lenient reads, and atomic text/JSON writes.
 
+Sync directory modes remain repair-compatible on POSIX, but repairs are applied
+only through an exact-identity, no-follow directory descriptor after the store
+root and admitted parent name are revalidated. Root or component swaps fail
+without chmodding the substituted directory. Matching modes take the no-open
+fast path. Windows uses its existing `mkdir` mode request plus exact directory
+identity checks and never falls back to pathname chmod.
+
+On Linux, Node offers no portable search-only descriptor that can also be
+`fchmod`ed. A mismatched directory without effective read access—including one
+created under an owner-read-removing umask—fails closed with
+`permission-unverified`. Supported macOS x64/arm64 hosts additionally try
+`O_SEARCH` when the directory remains searchable; an inaccessible directory
+still fails rather than restoring the pathname race.
+
 ## See also
 
 - [`fileStore`](file-store.md) — full store API.

package/docs/public-api.md

@@ -61,6 +61,15 @@ prefix preparation. See [in-place writes](in-place-write.md).
 for local ASCII-case observations. An unavailable answer remains `undefined`;
 the caller selects any fallback. See [path case probing](path-case.md).
 
+`resolvePathPrefixSync` and `ResolvedPathPrefix` separate a canonical existing
+path prefix from its raw unresolved suffix after physical symlink traversal.
+See [resolving path prefixes](path-prefix.md).
+
+`probePathSuffixAliasesSync` and `ProbePathSuffixAliasesOptions` compare selected
+missing relative suffixes beneath an existing directory using bounded temporary
+directory probes. The caller owns Unicode-pair policy, caching, and the fallback
+for `undefined`. See [path suffix alias probing](path-suffix-aliases.md).
+
 ## Guest source
 
 `@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,

package/docs/quickstart.md

@@ -60,7 +60,7 @@ await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true })
 await fs.remove("notes/archive/today.txt");
 ```
 
-`move()` defaults to no clobber. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
+`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
 
 ## 5. Inspect
 

package/docs/reading.md

@@ -27,10 +27,17 @@ Regardless of shape, every read goes through the same boundary checks:
 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`.
+6. Compare the pre-open bigint path identity with the open fd, then perform one best-effort final admission: check the captured root identity, compare the policy-aware pathname with the fd, freshly canonicalize and re-admit that target inside the captured root, compare its exact bigint identity without following a final symlink with the fd, and check the root again. Both final pathname observations run even when their spellings match. An observed swap triggers `path-mismatch` or `outside-workspace`; a missing final path triggers `not-found`.
 7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
 8. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
 
+The final fence closes a rejected descriptor before any Root read consumes bytes or
+`open()` hands the descriptor to its caller. It is a sequence of filesystem
+observations, not an atomic kernel pathname/open primitive, so a hostile peer can
+still race the namespace after the last observation. Standalone absolute-file
+helpers have no captured `Root` identity and do not claim this replacement-root
+fence; use a `Root` for untrusted paths.
+
 ## Read shapes
 
 ### `fs.read(rel, options?)`

package/docs/root.md

@@ -114,7 +114,7 @@ fs.createJson(rel, value, options?)      // create() variant of writeJson
 fs.append(rel, data, options?)           // append text/buffer; syncs before close by default
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
-fs.move(from, to, options?)              // rename within the root; defaults to no clobber
+fs.move(from, to, options?)              // rename within the root; native-backed no clobber by default
 fs.remove(rel, options?)                 // unlink file, rmdir, or bounded recursive removal
 fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
 fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
@@ -221,7 +221,17 @@ 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.
+On Windows, every Root pathname admission also rejects NTFS alternate-data-stream
+and directory-index aliases: relative names containing `:`, or absolute names
+with a colon beyond the single rooted drive designator, fail with
+`invalid-path` before filesystem access. This includes spellings such as
+`file:stream`, `dir::$INDEX_ALLOCATION`, and `dir:$I30:$INDEX_ALLOCATION`.
+Rooted drive, UNC, and extended-drive paths keep their existing handling, and
+the separate device/network policies remain in force. Ordinary colon-bearing
+names remain valid on POSIX where the operation's existing drive-relative rule
+does not otherwise reject them.
+
+`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. Before truncation or handle return, descriptor and pathname identities are compared with lossless bigint metadata; persistently unknown Windows identities fail closed. The returned `stat` remains an ordinary numeric Node `Stats` object. Use it for streaming output. Prefer `await using` for cleanup.
 
 `remove` leaves non-empty directories unchanged unless `recursive: true` is
 provided. Recursive removal defaults to streaming entries in filesystem order;
@@ -299,7 +309,12 @@ fs.entries(rel, options?)        // nonrecursive AsyncIterable<DirEntry>, includ
 fs.resolve(rel)                  // absolute path inside the root, after canonicalization
 ```
 
-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.
+These do not pin a later operation. During `stat()`, the exact selected target and
+parent are checked around metadata collection; `list()` checks one exact selected
+directory around the complete name/metadata batch instead of repeating containment
+work for every child. A detectable redirection rejects with `path-mismatch` rather
+than returning names or metadata from the replacement. Results remain advisory
+after the call returns, so use the verb methods for the actual read or write.
 
 `entries()` streams immediate children in filesystem order by default. It
 supports cancellation, a physical-entry limit that throws on overflow, and

package/docs/secret-file.md

@@ -81,6 +81,9 @@ 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.
 
+Read options are captured when the call starts. Mutating a shared options
+object while an asynchronous read is in flight cannot relax its link policy.
+
 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

package/docs/secure-file.md

@@ -62,6 +62,10 @@ type SecureFileReadOptions = {
 
 `io.maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap and `Infinity` disables the cap. Invalid limits reject before filesystem admission.
 
+The helper synchronously snapshots the supplied options, including nested permission and I/O settings, the injection callback, and supplied injection environment values, before opening the file or reaching its first `await`. Mutating those objects after this snapshot does not change that read's policy. This is not an atomic snapshot at invocation entry: caller getters run during snapshot construction and can affect values or working directories that have not yet been captured. `trust.trustedDirs` must be an array with a valid length and an own string entry without null bytes at every index; malformed lengths or entries, including sparse entries filled by inherited properties, reject with `invalid-path` before filesystem admission. An omitted or empty array leaves the read unrestricted by directory.
+
+Relative trusted directories (including an empty string) are resolved to absolute lexical paths during this synchronous snapshot using Node's `path.resolve()` semantics. Windows drive-relative entries retain their per-drive current-directory semantics, and extended-length drive roots retain their root separator. Raw alternate-stream and filesystem-namespace aliases reject before normalization. Working-directory changes after the snapshot cannot redirect this allowlist. The existing realpath check still follows trusted-directory symlinks when it runs and falls back to the captured lexical path if realpath lookup fails; the allowlist does not pin directory identities.
+
 `permissions.allowInsecure` is a migration escape hatch. Prefer fixing permissions and using [`formatPermissionRemediation`](permissions.md) to show the user what to run. `trust.allowNetworkPath` is off by default because UNC paths are remote authority, not local filesystem input. `inject` is for tests and platform adapters; production callers usually leave it unset.
 
 On an actual Windows process with effective `platform: "win32"`, `inject.env` and `inject.exec` do not replace descriptor inspection. They remain available to simulated Windows checks on non-Windows hosts.
@@ -74,7 +78,7 @@ On an actual Windows process with effective `platform: "win32"`, `inject.env` an
 
 | Code | Meaning |
 |---|---|
-| `invalid-path` | `filePath` was not a local absolute path. |
+| `invalid-path` | `filePath` was not a local absolute path, `trust.trustedDirs` contained malformed paths, or a Windows file path/trusted directory used an alternate-stream or filesystem-namespace alias. |
 | `not-found` | The path could not be stat'd before open. |
 | `not-file` | The opened target is not a regular file. |
 | `symlink` | The path is a symlink and `trust.allowSymlink` is false. |
@@ -83,7 +87,7 @@ On an actual Windows process with effective `platform: "win32"`, `inject.env` an
 | `outside-workspace` | `realPath` is outside `trust.trustedDirs`. |
 | `permission-unverified` | Required mode/ACL checks could not be completed, including when descriptor-bound Windows inspection is unavailable. |
 | `insecure-permissions` | Mode bits or ACLs grant broader access than allowed. |
-| `not-owned` | POSIX owner uid is not the current process uid. |
+| `not-owned` | POSIX owner uid is not the process's effective uid. |
 | `too-large` | File size or bytes read exceeded `maxBytes`. |
 | `timeout` | `timeoutMs` elapsed while reading. |
 

package/docs/security-model.md

@@ -28,6 +28,8 @@ You hand a `root()` boundary to a piece of code that takes caller-controlled rel
 - 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
 - asks a read/open primitive to target a known unsafe device or process-fd path
+- uses an NTFS alternate-stream or directory-index pathname to alias a different
+  Windows filesystem object than the visible path suggests
 - triggers a partial write that leaves a half-written file at the destination
 - ships an archive with `..` paths, absolute paths, or symlinks pointing outside the destination
 
@@ -47,6 +49,30 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 Every path is resolved against the canonicalized real path of the root, then checked at that boundary. On Windows, an exact-case structural Root prefix stays on the lexical fast path; a prefix accepted only by case folding must have the Root's exact directory identity and is rebased onto the trusted Root spelling before use. 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.
 
+Guarded pathname APIs reject Windows `:` namespace aliases before normalization
+or filesystem access. The only colon admitted in a Windows filesystem path is
+the rooted ASCII drive designator (including extended-drive syntax); relative
+paths admit none. This rule does not authorize device or network paths, which
+retain their independent restrictions. Pure formatters, descriptor-only calls,
+and `walkDirectory` (documented as a non-boundary traversal helper) are outside
+this pathname-admission guarantee. Output helpers continue to sanitize an
+untrusted basename, then validate the resulting path.
+
+The low-level existing-object readers `openRootFile()` and
+`openRootFileSync()` preserve their historical Windows drive-relative input:
+they anchor its leading drive designator before this admission check. The raw
+suffix remains unnormalized, and any additional colon is still rejected before
+filesystem access.
+
+Trusted-path standalone publication APIs retain the same drive-relative
+compatibility. This includes the atomic file, text, JSON, JSON store/direct
+queue writer, directory-replacement, move, and exclusive-publication helpers.
+They capture the drive's current directory at publication entry and carry the
+anchored spelling through their remaining checks, locks, callbacks, receipts,
+publication, and cleanup. File writers preserve the raw suffix. Root-relative
+APIs and caller-constructed relative directory receipts continue to reject
+drive designators.
+
 ### Symlinks (read side)
 
 `open()` and `read()` use `fs.open` with `O_NOFOLLOW` on POSIX where available. The library then `fstat`s the open fd and `realpath`s the original input, asserting the two refer to the same inode. A symlink swap that happens between resolve and open will fail at the identity check rather than silently following the new target.
@@ -60,12 +86,33 @@ checks, so callers do not need their own parent canonicalization.
 
 Guarded root reads compare lossless bigint identities from before open, the opened
 descriptor, the input path, and the canonical target; numeric public `Stats`
-receipts are not used as identity evidence. Unknown Windows device/inode values
-receive one re-inspection without reopening the file. A definite mismatch or
-persistent unknown identity rejects with `path-mismatch` before reading bytes.
-Regular-file readers, root-file adapters, and archive input staging use the same
-exact admission policy. `copyIn()` retains the admitted source identity for its
-checks before and after copying, independently of its numeric metadata receipt.
+receipts are not used as identity evidence. Before returning a handle or reading
+bytes, one best-effort final admission fence checks the originally captured root
+identity, freshly compares the policy-aware pathname with the opened descriptor,
+canonicalizes and re-admits that current target inside the captured root, compares
+the canonical target's exact bigint identity without following a final symlink
+with the descriptor, and checks the root identity again. The two final pathname
+observations remain independent even when the spellings match. Unknown Windows
+device/inode values receive one re-inspection without reopening the file.
+A definite mismatch or persistent unknown identity
+rejects with `path-mismatch`; escaped fresh containment rejects with
+`outside-workspace`. This is not an atomic kernel pathname/open primitive, so the
+namespace can still change after the final observation.
+
+Other regular-file readers, root-file adapters, and archive input staging retain
+their documented descriptor/path admission. The exported unrooted
+`openLocalFileSafely()` and `readLocalFileSafely()` helpers have no captured `Root`
+identity and therefore do not provide the replacement-root fence. `copyIn()`
+retains the admitted source identity for its checks before and after copying,
+independently of its numeric metadata receipt.
+
+The low-level `openRootFile()` adapters additionally retain the canonical root's
+exact identity from before component traversal. After their existing pathname and
+descriptor checks, they verify the root, freshly resolve and re-admit the consumed
+pathname, compare that canonical leaf with the descriptor, and verify the root
+again before returning ownership. A failed final fence closes the descriptor
+without reading. The checks detect substitutions at each observation boundary;
+they do not make pathname confinement atomic against a continuously racing peer.
 
 ### Symlinks (write side)
 
@@ -75,6 +122,26 @@ directory descriptors. Replacement uses descriptor-relative rename just like
 no-replace publication, so replacing the parent pathname does not divert the
 mutation.
 
+When either `denyMutations` or an explicit `mutationSymlinks` policy applies,
+the POSIX writer binds that exact policy snapshot to parent admission. An existing
+parent is canonicalized and identity-matched to its retained descriptor before
+the actual destination is authorized. A missing-parent walk authorizes each
+prospective directory before `mkdirat`, opens it without following a newly
+introduced link, and authorizes the opened object before continuing. This
+prevents a contained Linux `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`
+redirect from reusing policy approval for a different in-root subtree.
+For an ordinary unchanged route, operation-local observations may carry that
+admission across a direct-child creation only after exact parent and child
+fences and a synchronous full-epoch validation. The resulting operation-local
+token authorizes the opened child without an intervening await; stale,
+redirected, incomplete, or foreign evidence returns to the full ordered
+admission. An already-complete fallback parent is likewise retained only after
+full target admission and a fresh exact guard fence. Native acceleration additionally requires an exclusive
+direct-child mkdir result proving that this syscall created the name; a
+collision, legacy helper, or malformed result performs the guarded walk but
+cannot advance the receipt. That boolean is admission provenance only and does
+not grant ownership for cleanup by pathname.
+
 The opt-in `mutationSymlinks` policy applies independently of read policy.
 `"reject"` rejects symlink components; `"follow-parents-within-root"` resolves
 contained directory aliases and rejects final symlinks. Publication checks the
@@ -107,13 +174,13 @@ 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 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.
+`resolve()`, `exists()`, `stat()`, and `list()` are explicitly advisory — they answer a question and return. `stat()` checks the exact selected target and parent while collecting metadata, and `list()` checks the exact selected directory around its complete batch, so detectable descendant redirection rejects before results are returned. Those checks do not preserve identity after the call. 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.
+`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. POSIX pinned `write`, `create`, and `copyIn` copy the merged entries before awaiting preflight and reapply them to their admitted canonical parent, including before missing parent creation. 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
 

package/docs/sidecar-lock.md

@@ -2,6 +2,11 @@
 
 `acquireFileLock()` and `withFileLock()` provide a cross-process file lock with retry and process-exit cleanup. The lock is implemented as a sidecar file (e.g. `state.json` ↔ `state.json.lock`) — only one acquirer can create the sidecar with `O_CREAT | O_EXCL` at a time.
 
+On Windows, both the target and an explicitly supplied `lockPath` reject NTFS
+alternate-stream and directory-index namespace spellings before parent creation,
+in-process reentrant lookup, or sidecar access. Rooted drive paths retain their
+normal meaning, and ordinary colon-bearing POSIX paths remain valid.
+
 JavaScript raw-sidecar creation passes mode `0o600` to that exclusive open. On POSIX, the process umask may further restrict the new file but cannot add group or other access. No pathname `chmod` fallback is used.
 
 ```ts
@@ -33,7 +38,7 @@ Each new sidecar also carries an internal random ownership token encoded as JSON
 
 The raw sidecar bytes are not a canonical JSON representation: tools that trim or rewrite the trailing whitespace invalidate the ownership token, so release leaves the changed sidecar in place and fails closed. The token distinguishes cooperating acquisitions; it is not a secret and does not make pathname compare-and-remove atomic against a hostile process that can replace files outside the lock protocol.
 
-`release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.
+`release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed asynchronous acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.
 
 ## API
 
@@ -102,6 +107,16 @@ type FileLockRetryOptions = {
 
 `payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
 
+Asynchronous acquisition snapshots `targetPath`, an explicit `lockPath`, and
+`lockRoot` before its first asynchronous operation. Cwd-dependent path spellings
+are resolved using Node's platform path-resolution rules at that point, and the
+resulting absolute paths remain fixed through retries, stale recovery,
+verification, and release even if the process later changes its working
+directory. An explicit, fully qualified `lockPath` retains its caller-supplied
+spelling; current-drive-rooted and drive-relative Windows paths are resolved at
+the snapshot boundary. The snapshot adds no normalization beyond what is
+required to remove that cwd or current-drive dependency.
+
 The complete serialized sidecar must fit within 1 MiB (1,048,576 UTF-8 bytes),
 including pretty-printed JSON, newlines, and the internal ownership token's
 trailing whitespace. The limit counts bytes, not string characters. Oversized
@@ -215,6 +230,11 @@ Discarding an acquisition observation is not proof that the pathname is absent:
 another owner may already have created the next record. Every discarded
 observation consumes the normal retry/deadline budget and requires fresh
 exclusive creation. It supplies no release, reclaim, or held-lock authority.
+If that successor disappears during the recovery metadata probe, the waiter
+may discard the probe only with an operation-local receipt for an admitted
+regular file with one link, followed by current Root and canonical ancestor
+checks. A generic metadata error does not permit this retry, and public
+`Root.stat()` still rejects a file that changes during observation.
 Generic `Root.open()` and held-owner/reclaim reads still reject failed opens.
 Moving an already-matched pinned descriptor without unlinking it, unknown or
 inexact identities, retargeted ancestors, and unrelated filesystem or caller
@@ -302,6 +322,13 @@ try {
 }
 ```
 
+Failed synchronous acquisition attempts close the created descriptor once even
+if its metadata cannot be read. Cleanup leaves the sidecar in place without an
+exact descriptor identity. A metadata-capture failure does not replace the
+acquisition error; if close or identity-checked removal also fails, the
+`SuppressedError.error` is the acquisition error and `suppressed` is the cleanup
+error.
+
 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.

package/docs/store.md

@@ -32,7 +32,7 @@ import {
 | Durable JSON queue helpers | Append/load/ack JSON entry files using atomic writes and delivered markers. |
 | [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for credentials, tokens, and per-agent state at `0600` files under `0700` directories. |
 
-`fileStore().json("rel.json")` and `jsonStore({ filePath })` are intentionally separate primitives. Use `fileStore().json(...)` when JSON state lives alongside other files in the same managed directory; use `jsonStore({ filePath })` when you have a single absolute path and want the keyed JSON shape directly.
+`fileStore().json("rel.json")` and `jsonStore({ filePath })` are intentionally separate primitives. Use `fileStore().json(...)` when JSON state lives alongside other files in the same managed directory; use `jsonStore({ filePath })` when you have one trusted path, resolved to an absolute path at construction, and want the keyed JSON shape directly.
 
 ## Picking a shape
 
@@ -74,6 +74,10 @@ Queue and failed directory creation fsyncs every newly-created parent edge from
 
 `writeJsonDurableQueueEntry()` and migrations share strict parent synchronization inside the atomic writer's retained descriptor and per-path serialization lifetime, followed by published-file identity verification. If sync fails after publication, the write rejects without rolling back the published JSON; retrying `writeJsonDurableQueueEntry()` writes the entry again and must complete its own sync. Loader retries resync an existing processing claim's parent under the transfer lock before calling `read`, even when a version-dependent callback would no longer request migration. Fresh claims and same-directory source retirement already complete that sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
 
+The direct queue writer accepts trusted relative paths. On Windows it anchors
+an ordinary drive-relative `filePath` before publication and strict parent
+sync. Other queue lifecycle APIs retain their own root/path admission contracts.
+
 Batch loading skips invalid entry names, malformed, oversized, or unreadable entry content, and caller `read` callback failures. Initially unowned pending entries (hardlinks or unverifiable identities), symlinks, non-files, and absent pending entries are also skipped. Claim, transfer-lock, retirement, and migration write/publication/durability failures reject the batch with the original error, even if earlier entries succeeded. Migration in both loaders strictly syncs the parent directory after successful publication. Visible transitions and earlier processing claims remain for retry; a rejected batch does not acknowledge or roll them back.
 
 Failed destinations are create-only. Quarantine publishes the claimed file by hardlink, so the queue and failed directories must share a filesystem with hardlink support. If `failed/<id>.json` already exists, quarantine rejects while preserving both that earlier evidence and the current claimed entry instead of overwriting either file. The `read` callback continues to receive the logical `.json` path even though bytes are read and migrations are written through the claimed path.