@openclaw/fs-safe 0.14.0 → 0.16.0

package/docs/permissions.md

@@ -42,7 +42,7 @@ 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. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` does not use those pathname fallbacks on Windows: it requires descriptor-bound native owner/DACL facts for the exact handle it reads.
+`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. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` obtains descriptor-bound owner/DACL facts for the exact handle it reads, using native support or the packaged PowerShell/C# bridge in `auto` and `off` modes.
 
 ## Advanced Windows ACL helpers
 
@@ -69,9 +69,10 @@ resolveWindowsUserPrincipal(env);
 ```
 
 The fallback Windows inspector reads the owner and DACL together through one
-built-in Windows PowerShell/.NET query. It returns canonical SIDs and numeric
-access masks, so Unicode paths and account names do not pass through lossy
-console display text. `inspectWindowsAcl()` uses native descriptor facts for
+built-in Windows PowerShell/.NET query. The query addresses its JSON command by
+module name and limits module discovery to PowerShell's bundled system modules.
+It returns canonical SIDs and numeric access masks, so Unicode paths and account
+names do not pass through lossy console display text. `inspectWindowsAcl()` uses native descriptor facts for
 complete local ACLs with nonzero inherited ACEs (or empty/null DACLs) when the
 optional Windows binding is available. It applies
 the same classifier to native facts and the fallback query, returning canonical
@@ -102,6 +103,19 @@ characters, including a trailing `…` when truncated. Diagnostics do not copy
 stdout or read target file contents. The separate `errorCause` retains the
 original exception for restricted local diagnosis; do not serialize or expose
 it as display text.
+Custom executors may reject with any JavaScript value. The fallback display
+formatter handles primitives directly and reads only string-valued `name` and
+`message` data descriptors through a small, fixed prototype budget. It does not
+coerce objects, invoke accessors, or inspect proxy targets; unavailable display
+facts use a bounded generic reason. Command fields follow the same best-effort
+data-descriptor rule. Raw string, `Buffer`, or genuine `Uint8Array` stderr
+retains the sanitization above. Byte stderr is copied through captured
+typed-array intrinsics into a private bounded snapshot before replacement-based
+UTF-8 decoding; receiver properties, iterators, constructors, and altered
+prototypes are not consulted. Detached or out-of-bounds byte views contribute
+no stderr detail. These diagnostic limits do not relax permission policy:
+incomplete owner or ACL inspection remains unverified, and `errorCause` remains
+the exact rejected value even when no display metadata is safe to obtain.
 The parser and remediation command builders remain on the advanced surface for
 CLIs processing captured `icacls` output or presenting an explicit repair.
 Runtime inspection does not parse that display text. A null DACL reports
@@ -158,10 +172,12 @@ Object-specific and other ACE layouts are not guessed: they are omitted,
 `complete` becomes false, and their numeric types appear in
 `unsupportedAceTypes`, allowing a security-sensitive caller to fail closed.
 Non-Windows systems return `{ status: "unsupported-platform", platform }`.
-Windows requires the native binding; if it is unavailable or forced
-off, the call throws `FsSafeError("helper-unavailable")`. The existing coarse
-`inspectPathPermissions()` API still owns its compatibility fallback and trust
-classification.
+Windows prefers the native binding. In native `auto` or `off` mode, a missing
+binding or capability uses the packaged PowerShell/C# bridge with
+the same raw ACE projection. Native `require` rejects either absence with
+`FsSafeError("helper-unavailable")` and starts no command. An available native
+query's failure is terminal. The existing coarse `inspectPathPermissions()` API
+still owns its compatibility fallback and trust classification.
 
 ## Private directories
 
@@ -175,10 +191,11 @@ await createPrivateDirectory(sqliteDirectory);
 await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
 ```
 
-On Windows with native support, this creates the directory and applies a
+On Windows, this creates the directory and applies a
 protected owner + LocalSystem + Administrators full-control DACL directly with
-an atomic security descriptor; no PowerShell or `icacls` process is launched.
-The native operation retains the parent and exact created-directory handles
+an atomic security descriptor. The native route launches no command. When its
+binding or capability is unavailable, native `auto` and `off` modes use the
+packaged PowerShell/C# bridge. Both routes retain the parent and exact created-directory handles
 through ACL and final pathname validation. If validation fails, it attempts only
 nonrecursive deletion through the created handle, preserving any pathname
 replacement. If cleanup also fails, the error retains the original failure and
@@ -203,13 +220,32 @@ also rejects explicit `.` and `..` components, including spellings such as
 `.\private` and `parent\..\private`, as a compatibility restriction. Simple
 relative names without these components remain supported.
 
-This API is Windows-only and native-only; it fails closed with
-`FsSafeError("helper-unavailable")` on other platforms, when native mode is off,
-or when the binding is unavailable. POSIX callers should create private
+This API is Windows-only; it fails closed with `FsSafeError("helper-unavailable")`
+on other platforms. Native `require` also fails if the binding or capability is
+missing and never starts a command. An available native operation's failure is
+terminal. POSIX callers should create private
 directories through their existing trusted-root creation policy rather than a
 pathname-only compatibility shim. Existing Windows permission inspection still
 retains its structured .NET compatibility fallback.
 
+The raw owner/DACL and private-directory fallbacks each emit one path-free
+`FS_SAFE_NATIVE_FALLBACK` warning per process. PowerShell startup and C#
+compilation add overhead to each call; install the native package for frequent
+operations. These routes run the package's readable, fixed scripts under normal
+system PowerShell policy; see the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+If command support is unavailable, disallowed, or fails, the operation rejects.
+Private-directory creation never falls back to inherited permissions.
+The asynchronous creation command has a 30-second deadline. After a timeout or
+transport failure, fs-safe requests termination and waits at most one further
+second before rejecting and closing its output pipes. The error distinguishes
+observed process exit from an unconfirmed termination attempt. If the OS refuses
+termination, the command can still create the directory after rejection. An
+already-created object retains its protected DACL, but pathname validation and
+owned-handle cleanup may not finish. An error therefore does not prove the
+pathname is absent; a retry can report `EEXIST`. Before retrying or using the
+pathname, establish that the earlier operation stopped and verify any existing
+directory's security. The library does not attempt pathname-based cleanup.
+
 Use `createIcaclsResetCommand()` when you need a structured command and argv pair. Use `formatIcaclsResetCommand()` when you only need a remediation string for a user-facing message.
 
 ## Types

package/docs/public-api.md

@@ -43,8 +43,9 @@ The advanced root-file primitive exports `OpenRootFileParams`,
 `RootFileOpenFailureReason`. These are composition types for callers building
 their own pinned-open flow, not substitutes for the higher-level `Root` verbs.
 
-`copyFileHandle` and `CopyFileHandleOptions` transfer bytes between already-open
-regular files without taking over their cursors, lifetime, or publication.
+`copyFileHandle` and `copyFileDescriptorSync` share `CopyFileHandleOptions` to
+transfer bytes between already-open regular files without taking over their
+cursors, lifetime, or publication.
 See [borrowed-handle transfers](copy.md#borrowed-filehandle-transfers).
 
 `readDirectoryIdentity`, `assertDirectoryIdentitySync`, and `DirectoryIdentity`

package/docs/root.md

@@ -72,12 +72,22 @@ The default `order: "sorted"` enumerates and sorts each directory's names;
 wide directories. Budget exhaustion yields a `"truncated"` marker by
 default or throws `FsSafeError("too-large")` with `limitBehavior: "throw"`.
 Use `entryFilter(entry)` to return `"include"`, `"skip"`, or
-`"skip-subtree"`. `"skip"` omits the current entry but still descends into a
-directory; `"skip-subtree"` omits a directory and all of its descendants.
+`"skip-subtree"`, directly or through a Promise. `"skip"` omits the current
+entry but still descends into a directory; `"skip-subtree"` omits a directory
+and all of its descendants.
+Filters run serially outside metadata batches, with the options object as their
+`this` receiver. After an awaited filter resolves, the walk checks cancellation
+and revalidates the current listing directory and Root identities before using
+the decision. Captured entry metadata retains its snapshot semantics.
+
+Cancellation and iterator disposal wait for a pending filter to settle; they do
+not race the callback or close its directory while it is running. Callback
+throws and promise rejections reject the walk through normal cleanup.
 Directory reads remain fail-fast by default. With
 `onDirectoryError: "skip-and-report"`, the iterator instead yields
 `{ relativePath, kind: "directory-error", size: 0, error }` and continues with
-the remaining tree.
+the remaining tree. That policy also covers identity-check failures after an
+awaited filter, while callback failures always reject.
 See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
 with the standalone best-effort walkers.
 
@@ -120,8 +130,32 @@ fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
 fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 ```
 
+`mkdir`, `ensureRoot`, `create`, and `createJson` accept `private: true`.
+Missing directories are created with private permissions, and an existing
+requested directory must already be private. Existing ancestors are not
+chmodded or assigned new ACLs. Private files use owner-only POSIX permissions
+or a protected Windows DACL granting access to the current user, System, and
+Administrators. On macOS, private directories and files must also have no ACL;
+creation rejects relevant inheritable parent ACLs, while noninheriting parent
+ACLs remain allowed. A native helper with `inspectDarwinAcl` is required. Native
+`off`, a missing helper, or an older helper without that capability rejects with
+`helper-unavailable` before creating parents or stages. See [creation](creation.md)
+for platform support, synchronous leaf creation, and failure handling.
+
+```ts
+await fs.mkdir("private-data", { private: true });
+await fs.create("private-data/credential", "synthetic credential", { private: true });
+```
+
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
+Buffered `create` and `createJson` also accept `atomic?: boolean`. With `true`,
+complete content is staged before exclusive publication even in native-off mode;
+the fallback requires hardlinks. Omitted or `false` keeps the existing buffered
+publication behavior. Streamed creates always stage complete content. The flag
+does not change `durable` or promise stronger containment or crash durability.
+See [atomic creation and settlement](writing.md#atomic-buffered-creation).
+
 `create` also accepts `AsyncIterable<Uint8Array>` with `RootCreateStreamOptions`:
 the same path, authority, mode, and durability options, plus `maxBytes` and
 `signal`, without `encoding` or `renameIdentity`. It consumes one chunk at a
@@ -142,6 +176,11 @@ and parent-directory fsync calls. Use it only for reconstructible data: a crash
 may lose the write or leave the previous file. See [Writing](writing.md#write-options)
 for platform details.
 
+`create` and `createJson` additionally accept `durable: "file"` to require file
+synchronization, including propagating `EPERM`. Parent-directory synchronization
+retains its existing best-effort behavior. This option applies to buffered and
+streamed creation and does not select a publication strategy.
+
 `copyIn` accepts a `RootCopySource`: a trusted absolute source path or a file
 within another Root. The guarded form supplies `root` with only its `open` and
 `stat` read capabilities, plus `relativePath`:
@@ -290,6 +329,20 @@ the caller, which must check authority before its own later writes.
 
 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.
 
+`move()` snapshots its merged default and per-call mutation policy before
+asynchronous preparation. Later changes to the original policy objects or arrays
+apply to subsequent calls. Use `assertBeforeMutation` for live revocation of an
+in-flight move.
+
+For writes, creates, streams, and copies, parent creation admits the prospective
+file and each missing directory before creating that directory, including on the
+Windows native route. An exact deny on an existing parent does not prevent using
+that parent to write an allowed child. If a deeper missing parent is denied,
+earlier admitted directories may remain; the denied directory and file are not
+created. With `mkdir: false`, missing parents are never created. Native Windows
+policy-aware creation requires the direct-child helper and fails with
+`helper-unavailable` if it is absent.
+
 All mutation methods also accept `mutationSymlinks`. `"reject"` rejects symlink
 components; `"follow-parents-within-root"` resolves contained parent directory
 aliases but rejects the final component if it is a symlink, including a dangling

package/docs/secret-file.md

@@ -133,6 +133,15 @@ startWebhookVerifier(signingKey);
 
 Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file, finalizes `mode` (default `0o600`) through an owned descriptor after content writes, and atomically renames over the destination. Publication verification checks the final file identity and mode.
 
+On POSIX, both native and JavaScript writers verify actual `0o600` permission
+bits through the retained descriptor before writing content. A filesystem that
+reports successful chmod without enforcing those bits fails with
+`insecure-permissions` before any payload is written, including when an explicit
+`dirMode` permits other users to traverse the parent. The requested final `mode`
+is still applied after content writes, including restrictive and special-bit
+overrides. This mode-bit check does not require native ACL inspection; JavaScript
+secret writes remain available on macOS.
+
 Concurrent writes to distinct leaves may share creation of a missing parent.
 After a parent-creation race, the helper re-inspects the entry and requires a
 non-symlink directory, then revalidates root/parent guards, containment, and
@@ -270,9 +279,9 @@ await withTimeout(
 
 ## Threat model notes
 
-- These helpers protect the secret file from **other processes with the same UID** that respect filesystem permissions. They do not defend against root or against attackers who can read process memory.
+- On POSIX, the default `0600` file and `0700` directory modes restrict group and other access. They do not protect against processes with the same UID, root, attackers who can read process memory, or access granted by additional ACL entries.
 - Validation failures are tripwires, not authorization. Investigate before clearing a rejected credential file.
-- If the destination directory is on a tmpfs that does not honor mode bits, the helpers will set the mode bits but the OS may ignore them. Audit your platform.
+- On POSIX, a file that still reports a mode other than `0600` after initialization is rejected with `insecure-permissions` before payload is written. Matching mode reports alone cannot prove that an arbitrary filesystem actually enforces those permissions.
 
 ## See also
 

package/docs/secure-file.md

@@ -27,9 +27,13 @@ The helper:
 - enforces `maxBytes` before and after reading
 - closes the handle on success, error, and timeout
 
-On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper queries owner, DACL, and locality from the same open descriptor that supplies the bytes. The native query returns the 32-bit volume serial and 64-bit file-index projection used by Node, which must equal Node's bigint descriptor receipt before its ACL facts are trusted. This avoids JavaScript number rounding but does not represent the full 128-bit file identity available on ReFS. Only the current user, LocalSystem, and built-in Administrators are trusted owner classes.
+On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper queries owner, DACL, and locality from the same open descriptor that supplies the bytes. Both native and system-command queries return the 32-bit volume serial and 64-bit file-index projection used by Node, which must equal Node's bigint descriptor receipt before its ACL facts are trusted. This avoids JavaScript number rounding but does not represent the full 128-bit file identity available on ReFS. Only the current user, LocalSystem, and built-in Administrators are trusted owner classes.
 
-Windows secure reads require the matching current optional native package. A missing or stale helper, fd-to-handle conversion failure, denied `READ_CONTROL`, remote handle, incomplete descriptor, or unsupported ACE form rejects with `permission-unverified` before content is read. A malformed or different handle identity rejects with `path-mismatch`. There is no pathname-command fallback for `readSecureFile()`; the standalone reporting APIs in [`permissions`](permissions.md) retain their documented fallbacks. `permissions.allowInsecure` remains the explicit escape hatch and bypasses the ACL query.
+Windows secure reads prefer the matching optional native package. In native `auto` or `off` mode, a missing binding or descriptor-inspection capability uses a packaged, readable PowerShell script and adjacent C# source to inspect the borrowed file handle. This route requires the [Windows security fallback prerequisites](install.md#windows-security-fallback), including permission to run the scripts under normal system policy. The command does not read file contents or reopen the pathname. Successful inspection waits for the child to exit and its output pipes to close. This emits a path-free `FS_SAFE_NATIVE_FALLBACK` warning once per process for secure reads and adds PowerShell startup and compilation overhead to each inspection.
+
+Descriptor commands have a 30-second deadline. After a timeout or transport failure, fs-safe requests termination, waits at most one further second, and then rejects even if process exit or pipe closure remains unconfirmed. It closes its own output pipes and reports the observed exit separately from the termination attempt in the error cause. If the OS refuses termination, the child may retain its independently inherited Windows handle; closing the caller's descriptor cannot retarget that handle. No file bytes are returned from a failed inspection.
+
+Native `require` still rejects a missing binding or capability with `permission-unverified`, without starting a command. An available native helper's failure is terminal. On either route, fd-to-handle conversion failure, denied `READ_CONTROL`, a remote handle, incomplete descriptor, unsupported ACE form, or unavailable command support rejects with `permission-unverified` before content is read. A malformed or different handle identity rejects with `path-mismatch`. The standalone reporting APIs in [`permissions`](permissions.md) retain their documented pathname fallbacks. `permissions.allowInsecure` remains the explicit escape hatch and bypasses the ACL query.
 
 Descriptor, pathname, and realpath identity checks use bigint stats internally to avoid JavaScript number rounding. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
 
@@ -92,13 +96,14 @@ On an actual Windows process with effective `platform: "win32"`, `inject.env` an
 | `timeout` | `timeoutMs` elapsed while reading. |
 
 Windows descriptor-inspection failures are operational `permission-unverified`
-errors and refuse the read. The original native exception is retained as
+errors and refuse the read. The original native or descriptor-command exception is retained as
 `cause`; treat causes as restricted local diagnostic data. No pathname or ACL
 content is copied into the display message. Test adapters that simulate Windows
 on another operating system retain the standalone pathname inspector's
 structured command diagnostics (`ownerError`, `command`, `durationMs`,
 `timedOut`, `exitCode`, `signal`, and bounded escaped `stderr`). Actual Windows
-secure reads do not start those commands. No retries are performed.
+secure reads never invoke the injected pathname inspector: their optional
+command route inspects the borrowed descriptor instead. No retries are performed.
 
 ## See also
 

package/docs/sidecar-lock.md

@@ -9,6 +9,13 @@ 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.
 
+Root-backed lock records and reclaim guards also claim their final name
+exclusively, including with the native backend. The native path retains the
+admitted parent descriptor and removes incomplete claims only while their exact
+identity remains owned. Ordinary Root creates still stage privately; lock records
+use this internal exclusive-create path so racing contenders can retry without
+an ambiguous rename outcome.
+
 ```ts
 import { acquireFileLock } from "@openclaw/fs-safe/file-lock";
 
@@ -28,13 +35,32 @@ try {
 
 The lock file sits next to the protected resource. If a process crashes mid-lock, the next acquirer notices the held entry, inspects its payload (PID, host, acquired-at timestamp), and decides — via `shouldReclaim` (defaulting to "is the lock older than `staleMs`?") — whether it should keep waiting or fail.
 
-On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their retained Root capability and ownership receipt. The synchronous `process.on("exit")` handler provides last-chance cleanup for raw locks and reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it. Locks acquired with `retainOnExit: true` are exempt from both handlers: their sidecar stays in place after exit and is governed only by the caller's own stale policy. Because exit handlers are globally deduplicated across package copies, `retainOnExit` fails closed with `helper-unavailable` if an older copy that cannot honor it registered the handlers first.
+On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit")` handler attempts asynchronous cleanup of held Root-backed locks through their retained Root capability and ownership receipt. The synchronous `process.on("exit")` handler provides last-chance cleanup for raw locks and raw-path reclaim guards. Changed sidecars and failed Root cleanup remain in place; cleanup does not keep retrying during shutdown unless another acquisition re-arms it. Locks acquired with `retainOnExit: true` are exempt from both handlers: their sidecar stays in place after exit and is governed only by the caller's own stale policy. Because exit handlers are globally deduplicated across package copies, `retainOnExit` fails closed with `helper-unavailable` if an older copy that cannot honor it registered the handlers first.
+
+Asynchronous Root-backed stale recovery uses a regular file at the
+`.reclaim` name, created, verified, and removed through that Root. Its ownership
+token and exact bytes are checked after awaited decisions and before stale
+removal; Root mutation policies also apply to the guard. Raw and synchronous
+Root reclaimers use directories and recognize these files as occupied guards.
+Each asynchronous attempt owns its guard directly, outside process-exit cleanup,
+so `beforeExit` cannot release an exclusion still needed by an unsettled attempt.
+Normal completion removes it through the Root. Interrupted creation, revoked
+cleanup authority, identity changes, or process exit can leave the guard in
+place; recover it only after an application-owned liveness check proves the
+attempt has ended. There is no raw-path cleanup fallback. These token/byte
+checks retain the sidecar protocol's cooperative, non-atomic removal boundary.
+The final guard check follows the last sidecar snapshot and parser call, before
+removal. Parsers can run before guard ownership is established or verified;
+invocation is not mutation authority. A failing final parser keeps its error
+even if guard ownership has also changed.
+`manager.reset()` invalidates admission bookkeeping but preserves a pending
+Root guard; let its original attempt settle before retrying that guarded path.
 
 Always release locks in a `finally` block. Application-managed graceful shutdown can await `release()` or `manager.drain()` before terminating. Explicit `process.exit()`, uncaught failures, crashes, default signal handling, and fatal termination (including `SIGKILL`) do not reliably run asynchronous Root cleanup and may leave sidecars. Recover only after an application-owned liveness policy proves the holder cannot still be writing.
 
-Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
+Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. First registration is committed only after Node accepts the listener; synchronous `newListener` reentry fails closed and a thrown registration rolls back so a later acquisition can retry. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
 
-Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check.
+Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
 
 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.
 
@@ -62,6 +88,41 @@ function withFileLockSync<T, TPayload>(targetPath: string, options: FileLockSync
 
 `managerKey` is an optional identifier used to keep state isolated across multiple lock domains in the same process. Use distinct keys for distinct domains (`"snapshot"`, `"compact"`, `"build"`). If omitted, fs-safe derives one from the target path.
 
+Within one manager domain, the canonical target path is the in-process
+arbitration key even when callers supply different explicit `lockPath` values.
+Admission remains pending while payload serialization and stale-policy callbacks
+run, and becomes reentrant only after a matching owner is fully published.
+Foreign owners wait or reach the configured timeout without opening their
+alternate sidecar. Each unguarded attempt still invokes and serializes `payload`
+before a completed foreign holder consumes retry budget, preserving callback and
+retry compatibility; the holder is rechecked before delayed option accessors or
+sidecar I/O. When the candidate resolves to the holder's actual sidecar (the
+default path or an explicitly identical path), asynchronous retries also preserve
+the existing parser observation: bytes are observed first, then its accessor is
+read and the current holder bytes are parsed once per unguarded attempt.
+Distinct alternate sidecars do not trigger that observation. Async acquisition releases
+pending admission before retry backoff;
+synchronous callback reentry cannot let the active stack progress, so it fails
+closed with the normal `file_lock_timeout` fields. Async payload, serialization,
+delayed-option, and stale-policy callbacks carry a process-shared ancestry scope:
+a nested acquisition of the same canonical target in the same manager domain
+fails before waiting on its ancestor, while independent tasks, different targets,
+and different manager domains retain their normal retry behavior. The synchronous
+API uses one process-wide domain. An ancestry snapshot keeps each ancestor that
+is active when the child acquisition starts, even if the current callback's own
+scope already became inactive; later deactivation cannot reclassify that child.
+Detached work started only after every matching ancestor has finished is not
+retained as a descendant. Promise-like callback results are assimilated inside
+that ancestry scope, and the resolved payload crosses the internal return
+boundary in a non-thenable envelope. The helper therefore does not observe a
+stateful payload `then` accessor again outside the reservation.
+
+The pending-admission registry coordinates package copies that implement this
+protocol without placing incomplete state in the legacy held-lock map. An older
+already-loaded executable copy does not consult that registry, so a mixed-version
+process cannot rely on the new in-process arbitration until every copy is updated
+and the process is restarted.
+
 ## Acquire options
 
 ```ts
@@ -105,7 +166,11 @@ type FileLockRetryOptions = {
 };
 ```
 
-`payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
+`payload` is a function so you can re-evaluate it on each retry (e.g. timestamp,
+PID). Callback-valued option accessors are otherwise captured once for an
+acquisition; the asynchronous same-sidecar parser observation above reads
+`parsePayload` once per unguarded attempt. Callback invocation keeps its
+established receiver behavior.
 
 Asynchronous acquisition snapshots `targetPath`, an explicit `lockPath`, and
 `lockRoot` before its first asynchronous operation. Cwd-dependent path spellings
@@ -230,10 +295,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
+If that successor disappears or is replaced 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. Replacement also requires a single exact
+observation of a different regular file with one link. Current Root and canonical
+ancestor checks must still pass. 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
@@ -295,6 +361,46 @@ deadline budget. Errors from descriptor reads/stats or parsing are not treated
 as missing snapshots, even when their code is `ENOENT`. Held verification,
 release, and reclaim do not retry open denials.
 
+Synchronous `lockRoot` is an authority boundary, not only a containment hint.
+It requires a genuine `Root` returned by the same loaded package copy; a
+structural/custom Root lookalike or a handle constructed by another installed
+copy fails with `helper-unavailable` before any remaining acquisition option or
+nested retry getter, payload evaluation, or filesystem effects. After reading
+`lockRoot` once, the genuine Root and its policies are snapshotted before those
+getters run. Construct `lockRoot` through the same import instance that provides
+the synchronous lock function. The acquirer retains the original Root context,
+exact root, parent, and file identities, and the Root's entry-time read, hardlink,
+mutation-symlink, `denyMutations`, and `assertBeforeMutation` policies. Those
+receipts remain authoritative through same-owner reuse, compromise checks,
+reclaim, explicit release, and process-exit cleanup. If the Root, an admitted
+parent, or the owned entry changes, cleanup leaves the ambiguous path in place.
+Root-backed synchronous records and their exit handler use a separate versioned
+global domain; legacy raw-lock handlers and legacy package copies cannot adopt or
+pathname-delete those records. Root and raw acquisitions never share a
+reentrant reference, even when their owner strings match.
+
+As with asynchronous Root-backed acquisition, synchronous target normalization
+does not create the target's parent. An explicit in-root `lockPath` can therefore
+guard an external or not-yet-created target key without creating anything next
+to that target. Missing directories for the sidecar itself are created one
+component at a time through the retained Root policy; the returned `lockPath`
+uses the admitted canonical spelling. This strengthens earlier synchronous
+behavior that treated `lockRoot` as a one-time lexical/canonical bound and used
+raw pathname operations afterward.
+
+Windows Root-backed target keys use native existing-ancestor canonicalization,
+so long and short spellings of the same target parent share an arbitration key.
+Sidecar admission applies both the retained mutation policy and read/final-link
+policy before payload evaluation; a dangling final sidecar link is rejected
+without creating its target.
+
+Exact Root, parent, and file receipts narrow replacement races but do not make a
+pathname check and the following `open`, `mkdir`, `unlink`, or `rmdir` one atomic
+filesystem operation. A hostile peer with direct write access can still race the
+final syscall. An observed mismatch fails closed and ambiguous entries remain;
+use OS-enforced directory permissions or a native descriptor-relative primitive
+when that attacker model must be excluded.
+
 Both synchronous helpers consume the [process-wide lock defaults](config.md#configurefssafelocks-config).
 A synchronous retry sleep is clamped to the remaining finite deadline, so a long or jittered backoff cannot extend the configured timeout or block forever.
 Per-call options take precedence, including zero values; a per-call `retry`

package/docs/staged-file.md

@@ -65,6 +65,11 @@ interface StagedFile extends AsyncDisposable {
 Strings are UTF-8. `mode` is the requested **published** mode and defaults to
 `0600`; exact final modes, including `000`, are supported. The unpublished file
 stays at `0600` throughout preparation and any awaited application checks.
+The retained descriptor's actual mode is checked before writing payload bytes,
+by `assertCurrent()`, and before publication; a successful but ineffective
+`chmod` fails with `insecure-permissions`. Final mode verification after
+publication can fail with a `published` receipt while preserving the completed
+file. These are POSIX mode checks, not ACL or ownership admission.
 After rename succeeds and the published entry passes identity validation, the
 owner applies the requested mode through its retained file descriptor. Content
 was synchronized during preparation; publication always synchronizes the parent.
@@ -105,9 +110,13 @@ touching descriptors.
 basename. Empty, dot, dotdot, separators, absolute paths, NUL, control characters,
 drive-relative spellings, and the stage's own name are rejected.
 
-With `overwrite: false`, publication is genuine kernel no-replace rename; a
-collision leaves both names unchanged and raises `FsSafeError("already-exists")`.
-The stage may then be cleaned or published under another name. With
+With `overwrite: false`, publication is genuine kernel no-replace rename.
+A native collision raises `FsSafeError("already-exists")`, but ordinary errno
+does not prove that a remote rename never committed. Native rename failures
+without explicit pre-dispatch provenance therefore report `indeterminate`:
+cleanup preserves names and closes descriptors, and further publication rejects.
+Only rejection before rename dispatch leaves the stage eligible for cleanup or
+publication under another name. With
 `overwrite: true`, publication is plain atomic replacement. Neither route
 copies. Both source and destination resolve through the retained original
 parent, with checks immediately before rename and after publication.

package/docs/temp.md

@@ -221,9 +221,15 @@ A missing workspace returns `"missing"`. A replacement observed at the public
 name before quarantine returns `"identity-mismatch"` when the parent is stable;
 an ambiguous parent returns `"indeterminate"`. After successful removal,
 repeated cleanup returns `"missing"` without touching a recreated public name.
-Other statuses remain stable. Operational removal errors propagate and later
-cleanup returns `"indeterminate"` without retrying. Disposal and scoped helpers
-ignore returned statuses, while manual cleanup exposes the result.
+Other statuses remain stable. Compatible recursive-removal failures propagate
+the exact thrown value, including `undefined`, `null`, `false`, positive or
+negative numeric zero, bigint zero, an empty string, and `NaN`; they are never
+inferred from value identity or truthiness. Uncertain quarantine and
+retained-parent checks instead return
+`"indeterminate"`. After a propagated removal failure, later cleanup returns
+`"indeterminate"` without retrying. Disposal and scoped helpers ignore returned
+statuses, while manual cleanup exposes the result. A terminal descriptor-close
+failure retains its existing precedence if it also fails during settlement.
 
 When cleanup is part of a retention or audit decision, inspect the receipt
 instead of treating cleanup as fire-and-forget:
@@ -410,6 +416,12 @@ files, hardlinks, and changes between the pre-open pathname, opened descriptor,
 and current pathname are rejected. The callback must finish and close its
 writer before returning. Its return value is preserved as `result`.
 
+Each option is read once before directory creation starts, including both
+callbacks, the temp prefix, isolation, directory and file modes, and sync flags.
+Later changes to the options object do not change the in-flight operation.
+`writeTemp` and `resolveFinalPath` retain their shared internal staging object
+as the callback receiver.
+
 Generated temp filenames suffix Windows reserved-device basenames on every
 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
@@ -536,6 +548,11 @@ 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.
+
+The root, target, callback, fallback filename, and temp prefix are read once
+before setup. Later changes to the parameters do not affect the in-flight
+operation; `writeTemp` retains the original parameters object as its receiver.
+
 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