@openclaw/openshell-sandbox 2026.10.5-beta.4 → 2026.10.10-beta.2

package/node_modules/@openclaw/fs-safe/docs/platform-capabilities.md

@@ -0,0 +1,63 @@
+# Platform filesystem capabilities
+
+These synchronous capabilities load the native helper only when called. All
+three entry points import on every supported platform.
+
+## Linux write leases
+
+`tryAcquireWriteLease(fd)` from `@openclaw/fs-safe/file-lock` returns a frozen
+`FileWriteLease`, or `null` when another open descriptor prevents acquisition
+(`EAGAIN` or `EBUSY`). Other failures throw `FsSafeError`; unsupported systems
+throw `unsupported-platform` and unavailable helpers throw `helper-unavailable`.
+
+The caller owns the descriptor, must keep it open until release, and must install
+its own process-wide `SIGIO` handler **before** acquiring a lease. Prefer a
+disposable child process when an application cannot own that signal. The API
+does not install a signal handler. A competing open starts the kernel's lease
+break; `isHeld()` then returns false, including during a pending downgrade.
+Release promptly so the competing opener can proceed.
+
+`lease.fd` is the borrowed descriptor. `lease.release()` and
+`lease[Symbol.dispose]()` settle once without closing it; `isHeld()` returns
+false after release. Never close or reuse the fd before settling the lease.
+Lease acquisition does not replace the caller's path identity and age checks.
+
+## Darwin ACL inspection
+
+`inspectDarwinAcl(path)` from `@openclaw/fs-safe/permissions` opens the final
+component without following symlinks, then inspects a descriptor-bound security
+snapshot. Its `DarwinAclInspection` result is one of:
+
+- `{ kind: "none" }` for a proven absent or empty extended ACL.
+- `{ kind: "present", inheritsToFiles, inheritsToDirectories }` for an ACL with
+  entries, including when both inheritance flags are false.
+- `{ kind: "unknown", reason }` when opening or inspection fails, the helper
+  is unavailable, or the native facts are incomplete. Other platforms return
+  `reason: "unsupported-platform"`.
+
+Unknown is never evidence of absence. The two inheritance booleans report flag
+presence, not effective permissions or volume ownership enforcement. Intermediate
+path components follow ordinary path resolution; this is inspection, not a Root
+confinement capability.
+
+## Windows test fixtures
+
+The following exports from `@openclaw/fs-safe/test-hooks` are for tests, not
+production policy. They require the Windows native helper and reject final
+reparse points. Other platforms throw `unsupported-platform`.
+
+- `holdWindowsSharingLock(path)` returns a frozen disposable with idempotent
+  `close()`. Its native owner holds a non-inheritable handle with read/write
+  sharing, omitting delete sharing, until closed or collected.
+- `setWindowsFileAttributes(path, { readOnly?, hidden?, system? })` updates the
+  supplied bits through the opened handle and preserves unspecified attributes.
+- `readWindowsFileExtents(path)` returns `{ vcn, lcn, clusters }[]`, all bigint.
+  Empty or resident files may have no extents; `lcn: -1n` denotes sparse clusters.
+  Enumeration validates each response and fails on incomplete or invalid data.
+  It is an observation, not a snapshot against concurrent file modification.
+
+Use Node's `fs.statfsSync(path).bsize` for Windows cluster size. Windows CI
+compares it directly against `GetDiskFreeSpaceW`'s sectors-per-cluster times
+bytes-per-sector on NTFS. CI does not provide ReFS; this does not establish ReFS
+clone sharing. The extent reader reports mappings independently of the clone
+implementation.

package/node_modules/@openclaw/fs-safe/docs/public-api.md

@@ -187,3 +187,13 @@ budgets, `persistent`, and lifecycle.
 Every runtime and type name in `test/public-api.json` must appear somewhere in
 `README.md` or `docs/`. Documentation examples are also checked so a named
 import cannot silently move to another package subpath.
+
+## Exact receipt types
+
+`ExactFileIdentity` is the immutable bigint `dev`/`ino` pair returned alongside
+legacy numeric metadata. `ExactIdentityReceipt` describes an object with that
+`exactIdentity` companion. `FileIdentityInput` accepts either a traditional
+`FileIdentityStat` pair or an explicit exact-companion receipt.
+`ExactDirectoryReceipt` guarantees the exact companion on a returned directory
+receipt while the caller-constructible `DirectoryReceipt` remains compatible.
+See [the identity round-trip guidance](security-model.md#exact-receipts-and-legacy-numeric-metadata).

package/node_modules/@openclaw/fs-safe/docs/queue-link-free-design.md

@@ -0,0 +1,237 @@
+---
+title: Link-free queue design
+description: "Unimplemented durable JSON queue v2 proposal, crash recovery, and barriers to mixed-version Android support."
+---
+
+# Link-free durable JSON queue design
+
+**Status: design only; not implemented.** The current queue still requires
+hardlinks for claim, quarantine, and retirement recovery. Android/Termux systems
+that refuse those links receive `helper-unavailable`. This document does not
+announce Android support or change any existing API, error code, or disk format.
+
+The candidate below moves ownership into one atomic state file in a separate,
+versioned store. It explains how link-free transitions could work for cooperating
+v2 clients. It does **not** solve transparent migration with concurrent legacy
+writers, arbitrary processing paths, or existing failed-file destinations.
+Those gaps prevent implementation as a replacement or fallback for v1.
+
+## Existing guarantees
+
+The [durable queue contract](store.md#durable-json-queues) uses plain payloads at
+`<id>.json`, `<id>.processing`, and `<id>.delivered`. A transfer lock serializes
+consumer transitions for the JSON path; producers atomically replace `.json`
+without taking that lock. The lock is not a worker lease. Another load can return
+the existing processing generation, so delivery is at least once.
+
+Claim creates a no-replace hardlink from the pending name to the processing
+name. The generation at that syscall is the claimed generation. Source
+retirement moves the then-current pending file into a journal and compares exact
+device/inode identity with the claim. A different generation is restored
+create-only if no newer pending generation exists. Thus acknowledging an older
+claim cannot remove a newer enqueue. Replacing a still-pending generation by a
+later enqueue for the same ID is already permitted; this is not a FIFO of all
+writes to that ID.
+
+Quarantine publishes create-only to the failed destination. A shared inode
+distinguishes an interrupted publication from an unrelated destination collision.
+Acknowledgement moves only the claim through the delivered marker. Migration
+retains the opened claim and rejects a stale generation after its callback.
+Completed transitions synchronize affected directories; ambiguous ownership,
+identity, and stale transfer locks fail closed. Existing same-privilege race
+limitations in the [security model](security-model.md) still apply.
+
+These are ownership guarantees, not consequences that can be recovered from
+equal JSON bytes. Two independent enqueues may contain identical JSON. A digest,
+timestamp, or rounded numeric inode cannot establish that they are one generation.
+
+## Why an in-place fallback is insufficient
+
+| Candidate | Lost guarantee |
+|---|---|
+| Ordinary rename after testing for absence | A competing processing or failed destination can be overwritten. Different queues can share a failed destination without sharing a transfer lock. |
+| Copy into an exclusive destination | A crash can expose partial JSON; equal bytes cannot identify interrupted publication versus unrelated collision evidence. |
+| Exclusive empty placeholder, then record its owner | A crash between creation and recording ownership leaves an empty file indistinguishable from a pre-existing collision. |
+| Add a producer lock or format marker | Old producers ignore both and can replace `.json` during retirement recovery. |
+| Rename a retirement record back to `.json` | An old producer can publish after the absence check; replacing rename then destroys that newer generation. |
+
+Native atomic no-replace rename could remove some of these obstacles without
+making old producers cooperate. It is a distinct implementation route, requiring
+qualified Android support and full claim, retirement, and quarantine crash proof.
+An unavailable primitive, cross-device move, or unsupported filesystem must not
+select a replacing rename or a weaker copy fallback.
+
+## Candidate v2 disk format
+
+V2 would be an additive, explicitly selected API with a dedicated store root,
+not an option that silently changes the existing helpers. Proposed layout:
+
+```text
+store/
+  .fs-safe-queue-v2/
+    format.json
+    state.json
+    objects/
+      <object-token>/
+        payload.json
+    .state-transfer.lock
+```
+
+`format.json` identifies protocol `fs-safe-json-queue`, integer version `2`, and
+a random store ID. `state.json` repeats those values, has a monotonically
+increasing decimal-string revision, and contains queue/ID slots plus a shared
+failed index. Queue names and IDs use validated portable segments; object tokens
+are library-generated and never interpreted as caller-supplied paths.
+
+Each queue/ID slot has nullable `pending` and `claimed` references. A reference
+contains a logical delivery-generation token and an object token. Migration can
+replace the object while retaining the delivery generation. Failed slots contain
+the originating queue, ID, delivery generation, and object reference. All queues
+sharing a failed namespace must live in this same store and share its state
+lock. Two separately configured stores cannot advertise one shared failed index.
+
+Payload objects are immutable. They remain ordinary JSON, not envelopes exposed
+to the caller. Their unique, exclusively created directories distinguish
+independent equal-byte enqueues. Tokens select protocol records; they never
+replace exact bigint filesystem identity, no-follow admission, or pinned-file
+checks. Reused tokens, references to missing objects, unexpected links, malformed
+state, unknown versions, and inconsistent store IDs fail closed.
+
+Opening v2 requires both valid format and state files and an admitted dedicated
+root. Merely finding a directory, an empty file, or a partial initialization is
+not permission to adopt or delete it. Initialization exclusively creates the
+namespace, writes and synchronizes its files and directory edges before success,
+and leaves interrupted/ambiguous initialization for explicit recovery. An
+existing v1 directory remains v1; absence of a marker never means an empty v2
+store. No v2 file uses a top-level legacy queue filename.
+
+## State transitions and persistence ordering
+
+All v2 producers, consumers, migrations, and collectors take the same store
+transfer lock. Start with a coarse lock and bounded state/object sizes; splitting
+it requires a separate transaction design. Stale locks require operator recovery
+after proving the owner is gone. No timeout grants ownership automatically.
+Callbacks run outside the lock with their payload descriptor retained.
+
+Every state transaction re-admits the root, format, state, and referenced objects,
+including exact identity checks around awaited work. It writes a private sibling
+state temp, synchronizes that file, atomically replaces the admitted state file,
+then strictly synchronizes its parent before reporting success. Replacement has
+the same documented platform confinement limits as existing guarded writes; a
+format token or cooperative lock cannot upgrade those limits.
+
+Before publishing a new object reference, synchronize the complete payload file,
+its object directory, and the new edge in `objects/`. Persist store initialization
+edges first. No mutable state may refer to an incomplete object. Before consuming
+a state observed after an interrupted commit, synchronize the state parent under
+the lock. A visible post-rename sync failure is uncertain completion: retain all
+potentially referenced objects, report the error, and retry recovery. Never undo
+the transaction by deleting its payload.
+
+| Operation | One atomic state replacement |
+|---|---|
+| Enqueue | Set `pending` to a newly persisted object and delivery generation; retain `claimed`. A later enqueue may supersede this pending reference. |
+| Load without a claim | Move the pending reference to `claimed` and clear `pending`; synchronize before returning bytes. |
+| Load with a claim | Keep the same reference and retry that generation before any pending replacement. |
+| Acknowledge | After processing succeeds, clear only the expected claimed generation. A retry with an absent claim succeeds; a different claim rejects. Never clear pending. |
+| Quarantine | Require an absent failed slot, add its claim reference, and clear that claim in the same state update. An identical origin/generation/object reference is an idempotent retry; any other occupant is a collision. |
+| Migrate | After the callback, require both the delivery generation and original object reference still match the claim; publish a fully persisted replacement object and change only that claim's object reference. |
+
+The failed index is terminal inspection evidence, not pending work. It remains
+create-only even across different queues in the store. A loader never scans
+objects to infer pending work. The authoritative state alone determines whether
+an object is pending, claimed, quarantined, superseded, or acknowledged.
+
+Garbage collection holds the same lock, first completes parent synchronization,
+and removes only objects unreachable from the committed state. It must preserve
+objects pinned by active readers/migration callbacks; uncertain ownership or
+unverifiable pin lifetime defers collection. Version 2 can initially omit
+collection entirely. Leaked unreferenced objects are preferable to lost entries.
+There is no age-based deletion of potentially referenced data.
+
+## Crash-point table
+
+This table is the proposed protocol invariant, **not implementation proof**.
+It assumes cooperative v2 participants, an already initialized store, atomic
+whole-file replacement, a filesystem honoring successful file/directory syncs,
+and recovery after proven-stale lock removal. Filesystem corruption, concurrent
+hostile mutation, and an unavailable durability mechanism remain explicit errors.
+Power-loss behavior on each supported Android filesystem needs qualification.
+
+For a durably accepted generation that has not been superseded, acknowledged,
+or quarantined, recovery must find exactly one authoritative pending or claimed
+reference. Physical orphan objects are never redelivered. Quarantine and
+acknowledgement are deliberate terminal states, not exceptions silently counted
+as pending. Processing can repeat if its external side effect precedes durable
+acknowledgement; this is the existing at-least-once boundary.
+
+| Crash after / during | Recovery and surviving generation |
+|---|---|
+| Acquiring a lock, before any transaction | Prior state stays authoritative; stale lock blocks until explicit recovery. |
+| Exclusive object directory creation or partial payload write | No state reference exists. Prior pending/claimed state survives; enqueue has not succeeded. Never expose the incomplete object. |
+| Payload file sync, before all object-directory edges sync | Same as above; the object is not yet eligible for publication. |
+| All object syncs, before state replacement | Complete but unreferenced object is retained or later collected; prior state survives. |
+| Partial state-temp write or its file sync | Prior state survives. Temp contents never authorize delivery or cleanup. |
+| State replacement, before parent sync | After restart, admit the complete old or new state and sync its parent before acting. Retain objects needed by either outcome until recovery. No operation has reported durable success. Missing/invalid state is a hard failure, never an empty queue. |
+| Enqueue parent sync, before response | New generation is pending (or subsequently superseded under the ordinary same-ID contract). Producer may retry after an uncertain response; no exactly-once enqueue is promised. |
+| Claim replacement/sync, before returning payload | Old state has pending; new state has the same generation claimed. Recovery retries the claim first. Never both. |
+| Read or callback, before ack | Claim remains; side effects may repeat. A concurrent enqueue changes only pending. |
+| Migration object persistence, before state commit | Original claim survives; new unreferenced object is not delivered. |
+| Migration commit/sync, before response | Old or new object belongs to the same claimed delivery generation; stale callbacks cannot overwrite the new object reference. |
+| Ack replacement, before parent sync | Old state retains the claim and may redeliver; new state has an acknowledged generation. A newer pending reference survives both. |
+| Ack parent sync, before response | Acknowledged generation is absent; retry never clears a different claim. Objects left behind cannot resurrect it. |
+| Quarantine replacement, before parent sync | Old state retains the claim; new state has only terminal failed evidence for it. No intermediate state removes both references or exposes both as deliverable. |
+| Quarantine parent sync, before response | Failed reference remains; identical retry succeeds, different-origin collision preserves both generations. |
+| Collection unlink or directory sync | Only unreferenced, unpinned garbage is affected; pending/claimed/failed objects stay intact. |
+
+## Mixed-version behavior and cutover
+
+An old writer cannot be made to honor a new marker or lock by updating the
+consumer. For example: read legacy generation A, copy it into v2, then let an
+old writer replace `.json` with B. Removing `.json` can now delete B; leaving
+it can deliver A twice through independent protocols. Equality of bytes does
+not distinguish these events. Watching for a quiet interval cannot prove the
+old writer will not publish later.
+
+| Participants | Permitted behavior |
+|---|---|
+| Old and upgraded clients on v1 | Keep the current v1 protocol and error codes. Upgraded clients do not auto-convert or copy around refused links. |
+| All cooperating clients on a new v2 store | Candidate state protocol above; requires an explicit new API and validation before implementation. |
+| Old v1 writers alongside an isolated v2 store | Namespace coexistence only: separate backlogs. V2 must neither delete nor adopt v1 files. Old writers' work is not silently included in v2 success/drain results. |
+| Old writers with a requested single merged backlog on link-refusing storage | Unsupported. Report the capability/migration failure and preserve legacy evidence; do not claim the queue was drained. |
+| Quiesced legacy queue | A future explicit importer could retain migration receipts and copy under exclusive ownership. No importer is specified or authorized by this proposal. |
+
+Old batch loaders do not recurse into the v2 namespace, but that is only format
+separation, not a guarantee that an application shares a logical queue safely.
+Applications must stop and fence old producers/consumers before any destructive
+cutover. A directory scan, PID timeout, or absence of a current lock is not that
+fence. Deployments unable to stop old writers need a qualified native primitive
+route that continues the v1 ownership protocol.
+
+## Implementation gates and decision
+
+Do not retrofit this candidate into `writeJsonDurableQueueEntry()` or the
+existing path-based lifecycle helpers. A separate proposal must settle the
+public API, callback path semantics, expected-generation receipts, bounded state
+growth, active-reader collection, and fail-closed initialization recovery.
+Arbitrary `processingPath`/`deliveredPath`, shared external `failed/<id>.json`,
+and cross-device destinations cannot be represented by this single-store
+transaction without another protocol. They must retain v1 behavior, not acquire
+a silently weaker fallback. V2 is not an implementation of those contracts.
+
+Before implementing an approved scope, require deterministic crashes before and
+after every mutation and sync above, subprocess termination/restart tests,
+identical-payload distinct-generation tests, stale migration/ack tests, failed
+index collisions across queues, invalid-format/identity tests, and initialization
+and garbage-collection failures. Run a link-refusal matrix for `EACCES`, `EPERM`,
+`EXDEV`, `ENOTSUP`, `EOPNOTSUPP`, and `ENOSYS` in `off`, `auto`, and `require`.
+V1 must preserve its typed failures; v2 must make no ownership link attempt.
+Use real Linux seccomp denial of `link`/`linkat` and Android/Termux filesystem
+crash/durability qualification as separate evidence, not substitutes for one
+another. Native-capable operations must retain their native security mechanism;
+any performance change needs measured native/off comparison with an A/A control.
+
+**Decision: retain the existing fail-closed implementation and land this design
+only.** Transparent link-free v1 support with concurrent old writers has not
+been established. A separately scoped v2 API or qualified native no-replace
+implementation remains follow-up work; neither is required for 0.26.3.

package/node_modules/@openclaw/fs-safe/docs/quickstart.md

@@ -1,6 +1,8 @@
 # Quickstart
 
-Five minutes. By the end you will have a working `root()` and know how to read, write, atomically replace, and unpack an archive — without your code being able to escape the workspace.
+Build a `root()` and use it to read, write, atomically replace, and unpack an
+archive under a trusted workspace. Confinement strength and concurrent-mutation
+limits depend on the operation and platform; see the [security model](security-model.md).
 
 If you have used Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), this is the same shape: a capability-style handle that carries the boundary across every operation. The first thing to internalize is that you stop reasoning about *paths* and start reasoning about *the handle*.
 
@@ -31,7 +33,9 @@ await fs.write("notes/today.txt", "hello\n");
 const text = await fs.readText("notes/today.txt");
 ```
 
-Writes use a sibling temp file plus `rename`, so a partial write never appears at the destination. Reads open with `O_NOFOLLOW` where available and verify the opened fd matches the path identity before returning the buffer.
+Replacement writes use a sibling temp file plus `rename`, so a partial write
+never appears at the destination. Reads open with `O_NOFOLLOW` where available
+and verify the opened fd matches the path identity before returning the buffer.
 
 `create()` is the don't-clobber variant of `write()` and throws `already-exists` when the target is already there:
 
@@ -39,6 +43,13 @@ Writes use a sibling temp file plus `rename`, so a partial write never appears a
 await fs.create("notes/README.md", "seed\n"); // throws if it already exists
 ```
 
+Default create-only writes can expose incomplete content on the JavaScript
+fallback. Pass `{ atomic: true }` to stage complete content before publication.
+When hardlinks are refused, staged publication can still expose an empty
+destination placeholder before replacing it with the completed file. See
+[atomic creation](writing.md#atomic-buffered-creation) and
+[publication without hardlinks](writing.md#publication-without-hardlinks).
+
 ## 3. JSON, with parsing
 
 ```ts
@@ -60,7 +71,16 @@ await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true })
 await fs.remove("notes/archive/today.txt");
 ```
 
-`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` removes files and empty directories by default. To remove a non-empty directory, pass `{ recursive: true }`; use `maxEntries`, `maxDepth`, and `signal` to bound the work. See [`root()`](root.md) for removal ordering, limits, and partial-removal semantics.
+`move()` defaults to no clobber and requires native support. Linux `auto` can
+fall back when no-replace rename is unsupported; its directory fallback can
+replace a concurrently created empty directory. Use native `require` when
+that must fail closed. See the [move contract](writing.md#fs-move-from-to-options).
+Pass `{ overwrite: true }` when replacement is intended.
+
+`remove()` removes files and empty directories by default. For a non-empty
+directory, pass `{ recursive: true }`; use `maxEntries`, `maxDepth`, and `signal`
+to bound the work. See [`root()`](root.md) for removal ordering, limits, and
+partial-removal semantics.
 
 ## 5. Inspect
 

package/node_modules/@openclaw/fs-safe/docs/reading.md

@@ -81,6 +81,12 @@ For tighter control over malformed-or-missing JSON, use the standalone helpers i
 
 Returns a `FileHandle` plus `containment: "best-effort"`, the verified `realPath`, and `stat`. Use this for streaming or partial reads, and **always close the handle**:
 
+`open()` accepts `RootOpenOptions`: the read symlink and hardlink policies,
+without `maxBytes`. It does not consume bytes or apply the Root's read-size
+budget to later handle or stream operations. Bound that I/O in the caller, or
+use `read()` / `readBytes()` when the library should enforce the whole-file cap.
+The result also supports `await using` for automatic handle cleanup.
+
 ```ts
 const opened = await fs.open("large.log");
 try {
@@ -103,9 +109,9 @@ type RootReadOptions = {
 };
 ```
 
-`maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory. Values must be non-negative safe integers or positive `Infinity`; zero is an active cap, while `Infinity` disables it. Explicitly forwarding `undefined` preserves the Root default.
+For the byte-consuming read methods, `maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory. Values must be non-negative safe integers or positive `Infinity`; zero is an active cap, while `Infinity` disables it. Explicitly forwarding `undefined` preserves the Root default.
 
-Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely; regular-file descriptor reads retain normal Node behavior.
+Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely. Whole-file reads continue after short chunks, including on WSL 9p mounts; a short read alone is not treated as EOF. This also applies when the byte cap is disabled.
 
 ## `readAbsolute()` and `reader()`
 
@@ -175,6 +181,44 @@ try {
 }
 ```
 
+## Synchronous open batches
+
+`createRootFileOpenBatchSync()` from `@openclaw/fs-safe/advanced` returns an
+explicitly scoped batch for repeated `openRootFileSync` calls:
+
+```ts
+import fs from "node:fs";
+import { createRootFileOpenBatchSync } from "@openclaw/fs-safe/advanced";
+
+using batch = createRootFileOpenBatchSync();
+for (const absolutePath of sourceFiles) {
+  const opened = batch.openFile({ rootPath: sourceRoot, absolutePath, boundaryLabel: "source" });
+  if (!opened.ok) throw opened.error;
+  try {
+    consume(fs.readFileSync(opened.fd));
+  } finally {
+    fs.closeSync(opened.fd);
+  }
+}
+```
+
+`openFile()` accepts `OpenRootFileSyncParams` and returns the same
+`RootFileOpenResult` as `openRootFileSync()`. On Windows, canonical drive paths
+with the default symlink rejection reuse a native root descriptor within the
+batch. Native opens reject every reparse component beneath that root. Each open
+still checks the root and current leaf identities, applies its hardlink and
+byte-limit policy, and runs the final root/file/root confinement fence. Replacing
+an admitted root rejects later native opens; file contents and file identities
+are never cached. Other platforms, unavailable native support, other path
+spellings, explicit canonical-root hints, custom filesystem adapters, and
+symlink-following policies retain the ordinary per-open admission path.
+
+Successful opens transfer descriptor ownership to the caller. `close()` and
+`Symbol.dispose` release retained root descriptors, are idempotent, and do not close
+previously returned descriptors. Opening after close returns a validation
+failure with code `invalid-path`. Keep batches scoped to one operation rather
+than retaining them as a process-wide filesystem cache.
+
 ## Common errors
 
 - **`outside-workspace`** — relative path escaped the root, or `readAbsolute` got an absolute path outside.
@@ -193,3 +237,13 @@ See [Errors](errors.md) for the full list.
 - [Writing](writing.md) — companion verbs for produce-side I/O.
 - [JSON files](json.md) — standalone strict/lenient JSON helpers.
 - [Secure file reads](secure-file.md) — pinned absolute file reads with permission checks.
+
+## Exact identity metadata
+
+`OpenResult`, `WritableOpenResult`, `ReadResult`, and advanced `openRootFile()` /
+`openRootFileSync()` results include immutable bigint `exactIdentity` alongside
+`stat: Stats`. The legacy stat and companion derive from the same descriptor
+observation. Use the companion for later identity checks, especially on Windows;
+retain it rather than re-statting a pathname after closing the handle.
+`readRegularFile()` / `readRegularFileSync()`, `statRegularFile()` /
+`statRegularFileSync()`, and `readSecureFile()` follow the same rule.

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

@@ -72,6 +72,8 @@ re-inspection without reopening; persistent unknowns or replacements throw
 
 Throws `FsSafeError` with code `too-large` if the file exceeds `maxBytes`. Other I/O errors propagate as `NodeJS.ErrnoException`.
 
+Reads continue after short filesystem chunks even when `maxBytes` is omitted. Nonblocking opens remain enabled to reject raced FIFOs without hanging.
+
 ### `readRegularFileSync(params)`
 
 Synchronous variant. Same shape; the only required field is `filePath`. `maxBytes` is optional.

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

@@ -27,11 +27,11 @@ import {
 
 ## Constants
 
-```ts
-DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;  // 16 KiB
-PRIVATE_SECRET_DIR_MODE = 0o700;
-PRIVATE_SECRET_FILE_MODE = 0o600;
-```
+| Exported constant | Value |
+|---|---|
+| `DEFAULT_SECRET_FILE_MAX_BYTES` | `16 * 1024` (16 KiB) |
+| `PRIVATE_SECRET_DIR_MODE` | `0o700` |
+| `PRIVATE_SECRET_FILE_MODE` | `0o600` |
 
 The 16 KiB cap is intentionally aggressive — credentials should be small. If you need bigger, pass `maxBytes` explicitly.
 

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

@@ -29,7 +29,7 @@ The helper:
 
 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 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.
+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, prebuilt .NET Framework helper to inspect the borrowed file handle. This route requires the [Windows security fallback prerequisites](install.md#windows-security-fallback), including permission to run the executable 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 starts a fresh helper process for 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.
 

package/node_modules/@openclaw/fs-safe/docs/security-model.md

@@ -91,6 +91,18 @@ publication, and cleanup. File writers preserve the raw suffix. Root-relative
 APIs and caller-constructed relative directory receipts continue to reject
 drive designators.
 
+### Portable Windows security transport
+
+The portable fallback runs a prebuilt .NET Framework helper for each security
+check. Node passes the borrowed fd as the child's stdin; C# inspects that exact
+handle using `GetStdHandle(-10)`. Replacement descriptors and every verification
+across callbacks, publication, link-count changes, and chmod retain the same
+ordering and ownership boundaries as the native fallback protocol. No facts are
+cached between calls. A persistent helper cannot inherit later-opened fds, and
+portable Node does not expose the OS HANDLE or `DuplicateHandle` needed to send
+them. See the [reproducible build](native.md#windows-helper-build) and
+[execution policy requirements](install.md#windows-security-fallback).
+
 ### Exclusive creation on Windows
 
 Windows Node exclusive creation can follow a dangling file symlink before an
@@ -382,3 +394,26 @@ public result types and containment labels are unchanged.
 ## Reporting issues
 
 Suspected security issues belong in private disclosure first. See [`SECURITY.md`](https://github.com/openclaw/fs-safe/blob/main/SECURITY.md) in the repo for the current contact path.
+
+## Exact receipts and legacy numeric metadata
+
+Identity comparisons require bigint or safe-integer components. Unsafe Number
+IDs remain rejected: converting a rounded Number to bigint cannot recover the
+lost bits. This matters on NTFS, whose file IDs can exceed Number precision.
+
+Public open/read results, standalone publication results, directory durability
+receipts, and temp-workspace receipts carry `exactIdentity`. Publication failures
+carry `exactTargetIdentity` when the created target is known. Retain and pass
+those exact companions back to identity-checking APIs. Existing numeric fields
+keep their types and serve as legacy metadata views. Both views come from the
+same admitted observation, never an extra pathname stat to recover identity.
+`sameFileIdentity()` and standalone publication prefer an explicit
+`exactIdentity` on a whole receipt. They do not guess between nested source,
+target, directory, or staged identities.
+
+`Root.stat()`, typed `list()`, and `entries()` expose a non-enumerable
+`exactIdentity`, preserving their established numeric JSON representation.
+Object spread and JSON serialization omit that field: retain the returned object
+or copy its exact companion explicitly. Other bigint receipt fields also require
+an application-defined encoding for JSON. Exact receipts record identity at an
+observation; they add no atomic rename, deletion, ownership, or durability guarantee.

package/node_modules/@openclaw/fs-safe/docs/sidecar-lock.md

@@ -1,5 +1,7 @@
 # File lock
 
+For [Linux kernel write leases](platform-capabilities.md#linux-write-leases), `FileWriteLease.isHeld() === false` means “do not act on the file,” including while the kernel is still processing a lease break. The caller’s `SIGIO` handler still owns break notification.
+
 `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
@@ -72,21 +74,29 @@ The raw sidecar bytes are not a canonical JSON representation: tools that trim o
 ## API
 
 ```ts
-function acquireFileLock<TPayload>(
+import type {
+  FileLockAcquireOptions,
+  FileLockHandle,
+  FileLockManager,
+  FileLockSyncAcquireOptions,
+  FileLockSyncHandle,
+} from "@openclaw/fs-safe/file-lock";
+
+declare function acquireFileLock<TPayload extends Record<string, unknown>>(
   targetPath: string,
   options: FileLockAcquireOptions<TPayload>,
 ): Promise<FileLockHandle>;
 
-function withFileLock<T, TPayload>(
+declare function withFileLock<T, TPayload extends Record<string, unknown>>(
   targetPath: string,
   options: FileLockAcquireOptions<TPayload>,
   fn: () => Promise<T>,
 ): Promise<T>;
 
-function createFileLockManager(key: string): FileLockManager;
+declare function createFileLockManager(key: string): FileLockManager;
 
-function acquireFileLockSync<TPayload>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>): FileLockSyncHandle;
-function withFileLockSync<T, TPayload>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>, fn: () => T): T;
+declare function acquireFileLockSync<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>): FileLockSyncHandle;
+declare function withFileLockSync<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>, fn: () => T): T;
 ```
 
 `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.
@@ -141,7 +151,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   shouldReclaim?: (params: {
     lockPath: string;
     normalizedTargetPath: string;
-    payload: Record<string, unknown> | null;
+    payload: unknown;
     staleMs: number;
     nowMs: number;
     heldByThisProcess: boolean;
@@ -150,7 +160,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     lockPath: string;
     normalizedTargetPath: string;
     raw: string;
-    payload: Record<string, unknown> | null;
+    payload: unknown;
   }) => boolean | Promise<boolean>;
   metadata?: Record<string, unknown>;    // attached to heldEntries() output for diagnostics
   parsePayload?: (raw: string) => unknown;
@@ -542,24 +552,32 @@ holder still alive":
 
 ```ts
 import { kill } from "node:process";
+import { acquireFileLock } from "@openclaw/fs-safe/file-lock";
 
 const handle = await acquireFileLock(targetPath, {
   staleMs: 60_000,
   payload: () => ({ pid: process.pid }),
-  shouldReclaim: ({ payload, nowMs, staleMs }) => {
-    if (!payload) return true;
-    const pid = Number(payload.pid);
-    if (!Number.isFinite(pid)) return true;
+  shouldReclaim: ({ payload }) => {
+    if (!payload || typeof payload !== "object" || !("pid" in payload)) return true;
+    const pid = payload.pid;
+    if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return true;
     try {
       kill(pid, 0);
       return false;                     // process still alive — keep waiting
-    } catch {
-      return true;                      // process gone — fail closed for recovery
+    } catch (error) {
+      return error !== null && typeof error === "object" &&
+        "code" in error && error.code === "ESRCH"; // only a missing process is stale
     }
   },
 });
 ```
 
+The observed payload is `unknown`, even when this caller writes a typed payload.
+Validate it before reading fields. Permission failures such as `EPERM` do not
+prove that the holder exited. PID checks assume a shared local PID namespace;
+PID reuse can keep a stale lock waiting. This callback classifies staleness,
+not ownership or permission to remove another holder's lock.
+
 `heldByThisProcess` is true when this manager already holds the lock. A `true` result marks the observed sidecar as stale; `staleRecovery` then decides whether acquisition fails closed or attempts caller-approved removal.
 
 ## Stale recovery: guarded `remove-if-unchanged`