@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/docs/secure-file.md

@@ -21,14 +21,21 @@ The helper:
 - rejects every non-regular preview and, by default, symlink paths
 - opens POSIX paths no-follow and nonblocking before reading, then verifies the opened fd still matches the path and realpath; a FIFO swap cannot block before `timeoutMs` owns the byte read
 - optionally requires the real path to live under one of `trust.trustedDirs`
+- rejects hardlink aliases using descriptor, pathname, and realpath link counts, then rechecks the descriptor after reading before returning bytes
 - rejects hard-to-verify or unsafe permissions unless `permissions.allowInsecure` is set
 - rejects files owned by another POSIX uid
 - 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 uses the ACL inspection helpers from [`permissions`](permissions.md) and refuses the read if ACLs cannot be verified.
+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.
 
-Descriptor, pathname, and realpath identity checks use lossless bigint stats internally. 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.
+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.
 
 ## Options
 
@@ -59,8 +66,14 @@ 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.
+
 `permissions.allowInsecure` bypasses only permission checks. Neither it nor `inject.platform` changes filesystem identity verification, which always uses the actual process platform. `trust.allowSymlink` permits an alias but still requires its target and realpath to match the opened descriptor.
 
 ## Errors
@@ -69,29 +82,28 @@ type SecureFileReadOptions = {
 
 | 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. |
+| `hardlink` | The descriptor, pathname, or realpath has more than one link. |
 | `path-mismatch` | The path or realpath changed between open and verification, or filesystem identity could not be verified after bounded re-inspection. |
 | `outside-workspace` | `realPath` is outside `trust.trustedDirs`. |
-| `permission-unverified` | Required mode/ACL checks could not be completed. |
+| `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. |
 
-Windows inspection failures remain operational `permission-unverified` errors
-and still refuse the read. Their message includes the underlying reason when
-available. `details` includes `ownerError` for owner-query failures and, when
-command diagnostics are available, `command`, `durationMs`, `timedOut`,
-`exitCode`, `signal`, and `stderr`. Reasons and stderr are control-character
-escaped and limited to 400 characters each (including a truncation marker).
-No stdout or target file contents are copied into these display diagnostics.
-The original inspection exception is retained as `cause`; built-in command
-errors also retain their original execFile exception in the cause chain.
-Treat causes as restricted local diagnostic data. No retries are performed,
-and verification order and rejection conditions are unchanged.
+Windows descriptor-inspection failures are operational `permission-unverified`
+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 never invoke the injected pathname inspector: their optional
+command route inspects the borrowed descriptor instead. No retries are performed.
 
 ## See also
 

package/node_modules/@openclaw/fs-safe/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
 
@@ -45,7 +47,31 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 ### Path traversal and absolute paths
 
-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.
+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)
 
@@ -53,14 +79,40 @@ Every path is resolved against the canonicalized real path of the root, then che
 
 Per-call `symlinks: "follow-within-root"` allows symlinks whose final target is still inside the root. The default is `"reject"`.
 
+`symlinks: "follow-parents-within-root"` allows contained parent directory aliases
+while rejecting a final symlink, including dangling links. Reads open the checked
+canonical parent plus the final basename with the usual no-follow and identity
+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)
 
@@ -70,6 +122,35 @@ 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
+final component again after awaited staging and parent fences, immediately before
+the rename or exclusive open. These are best-effort symlink checks, not an atomic
+expected-entry/CAS replacement: a concurrent process can still replace the final
+entry between its check and rename. Existing parent containment guarantees remain
+as described below. Omitting `mutationSymlinks` preserves existing mutation behavior.
+
 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`.
@@ -93,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/node_modules/@openclaw/fs-safe/docs/sidecar-lock.md

@@ -2,6 +2,20 @@
 
 `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.
+
+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";
 
@@ -21,15 +35,37 @@ 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.
+It stops compromise monitoring for forgotten holders, including callbacks from checks already in flight.
 
 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.
 
-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.
+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. 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.
 
-`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()` or `withFileLockSync()` 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
 
@@ -53,13 +89,48 @@ 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
 type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   managerKey?: string;                   // optional in-process manager namespace
   lockPath?: string;                     // override; defaults to `${targetPath}.lock`
-  staleMs?: number;                      // default 30_000
+  staleMs?: number;                      // non-negative or Infinity; default 30_000
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
   staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
@@ -84,7 +155,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   lockRoot?: Root;
   retainOnExit?: boolean;               // keep the sidecar across process exit (default false)
   onCompromised?: (info: { lockPath: string; normalizedTargetPath: string }) => void;
-  compromiseCheckIntervalMs?: number;
+  compromiseCheckIntervalMs?: number;    // 0/omitted disables; otherwise 1..2_147_483_647
 };
 
 type FileLockRetryOptions = {
@@ -96,7 +167,21 @@ 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
+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
@@ -114,6 +199,10 @@ explicit `retry.retries` still applies with `timeoutMs: Infinity`, and zero allo
 only the initial attempt. After process defaults are applied, an omitted retry
 count means unlimited retries, and an omitted or infinite timeout means no
 deadline. With neither budget bounded, contention can wait indefinitely.
+Finite deadlines use monotonic elapsed time, so system clock corrections do not
+extend or shorten the retry budget. Payload timestamps, `heldEntries().acquiredAt`,
+and stale-policy `nowMs` remain wall-clock based. Deadlines are checked at retry
+boundaries; they do not interrupt callbacks or filesystem operations.
 `parsePayload` replaces JSON parsing for legacy or custom sidecars. Its `unknown`
 result is passed to `shouldReclaim` and `shouldRemoveStaleLock`, allowing PID,
 process-start, argv, or role schemas to remain application-owned.
@@ -211,6 +300,12 @@ 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 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
 inexact identities, retargeted ancestors, and unrelated filesystem or caller
@@ -243,7 +338,20 @@ type FileLockHandle = {
 captured at acquisition. Set `compromiseCheckIntervalMs` together with
 `onCompromised` for a cheap periodic check; the callback fires once after the
 sidecar no longer matches or after a verification I/O failure. This is
-detection, not revocation of work already in progress.
+detection, not revocation of work already in progress. Asynchronous checks are
+serialized, so a slow verification never overlaps the next timer tick.
+
+Ownership-only checks compare serialized bytes, tokens, and file identities
+without decoding an unused default JSON payload. Stale-policy reads still
+decode the payload. Explicit `parsePayload` callbacks keep their existing
+verification and asynchronous-cleanup calls, receivers, and errors;
+synchronous release continues without invoking a custom parser.
+
+The compromise-check interval is validated before payload evaluation or
+filesystem acquisition. Omit it or pass `0` to disable monitoring; enabled
+intervals must be finite and between 1 and 2,147,483,647 milliseconds. Values
+outside that range are rejected instead of being clamped by Node.js to an
+unexpectedly tight polling loop.
 
 ## Synchronous locks
 
@@ -264,6 +372,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`
@@ -291,9 +439,17 @@ 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.
+Synchronous `shouldReclaim` and `shouldRemoveStaleLock` reject Promise or thenable results with `TypeError` before deleting the observed sidecar; an asynchronous result is never approval.
 
 If termination skips the relevant cleanup handler or cleanup fails, the sidecar remains. In particular, `process.exit()` skips asynchronous Root cleanup; await explicit release or drain during application-managed graceful shutdown. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed by default instead of deleting by path.
 

package/node_modules/@openclaw/fs-safe/docs/staged-file.md

@@ -49,7 +49,7 @@ remain with the caller.
 
 ```ts
 function stageFileInDirectory(options: {
-  directory: string | DirectoryReceipt;
+  directory: string | DirectoryReceipt<Stats | BigIntStats>;
   content: string | Uint8Array;
   mode?: number;
 }): Promise<StagedFile>;
@@ -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.
@@ -76,8 +81,9 @@ Creation uses an exclusive, no-follow, close-on-exec open of a generated direct
 child name. Writes use that descriptor. Inspection uses non-following metadata
 operations, never a potentially blocking reopen of the leaf.
 
-A supplied directory receipt must still match at admission. Its numeric
-identity must be exactly representable; ambiguous identity fails closed.
+A supplied directory receipt must still match at admission. Caller receipts can
+carry numeric `Stats` or exact `BigIntStats`; untracked numeric identities must
+be exactly representable. Ambiguous identity fails closed.
 Returned receipts are frozen descriptive snapshots, not mutable authority.
 Changing a supplied receipt after admission cannot retarget the lifecycle.
 
@@ -105,9 +111,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/node_modules/@openclaw/fs-safe/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
 
@@ -72,12 +72,45 @@ Loading serializes consumers for one ID through a sidecar lock, then creates `pr
 
 Queue and failed directory creation fsyncs every newly-created parent edge from the leaf toward the trusted root. Enqueue and migration writes fsync the temp file and parent; claim, acknowledgement, quarantine, delivered-marker cleanup, and retirement transitions fsync every affected directory and propagate real sync failures. A transition may already be visible when a post-mutation sync fails, so retry the same operation to complete its crash-recovery state. Acknowledgement retries resync the queue directory even when both `.processing` and `.delivered` marker names are already absent, before reporting completion or rejecting a newer pending generation; quarantine retries with only failed evidence resync that destination before repairing the vanished queue source.
 
-`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 writes the entry again and must complete its own sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
+`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.
 
+Migrations stay bound to the exact processing file opened for that load. The
+read descriptor remains pinned while the callback runs outside the transfer
+lock; after the callback returns, migration reacquires the lock and rechecks the
+claim before publication. If another consumer acknowledged, quarantined, or
+replaced that claim, the migration rejects with `FsSafeError("path-mismatch")`
+and leaves the newer generation or failed evidence intact. A stale migration
+rejects both single and batch loads; ordinary callback failures retain their
+existing single-load rejection and batch-skip behavior. A caller or migration
+error with code `ENOENT` is still a failure, not a missing queue entry; only a
+claim that is absent or disappears before reading returns `null` from a single load.
+
+If closing the read descriptor also fails, the original read, validation,
+callback, or migration failure keeps precedence, including non-Error rejection
+values. A close failure without an earlier failure is reported through the same
+loader policy: direct reads and single loads reject, while batch loads skip it
+unless migration has started.
+
+On Windows, migration releases its read pin once at this publication boundary
+because an open target can block replacement. It rechecks the exact pathname
+identity after the asynchronous close while still holding the transfer lock.
+POSIX retains the read pin through publication. Other readers keep ownership
+of their handles; Windows sharing denials still reject and can be retried after
+those readers close.
+
+Generation arbitration requires consumers to use the transfer lock. As with
+[atomic writes](atomic.md#beforerename), identity checks and pathname replacement
+are separate operations; use a trusted writable parent or OS isolation against
+processes that ignore the lock and mutate queue paths concurrently.
+
 Queue entry reads verify lossless file identities before opening, on the opened
 descriptor, and at the current pathname before reading bytes. POSIX opens are
 nonblocking, so a raced FIFO is rejected rather than stalling a consumer. On Windows, an