@openclaw/fs-safe 0.5.6 → 0.7.0

package/docs/secure-file.md

@@ -18,8 +18,8 @@ const { buffer, realPath, permissions } = await readSecureFile({
 The helper:
 
 - requires a local absolute path and rejects UNC/network paths by default
-- rejects directories and, by default, symlink paths
-- opens the file before reading and verifies the opened fd still matches the path and realpath
+- 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 hard-to-verify or unsafe permissions unless `permissions.allowInsecure` is set
 - rejects files owned by another POSIX uid
@@ -28,6 +28,8 @@ The helper:
 
 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.
 
+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.
+
 ## Options
 
 ```ts
@@ -55,8 +57,12 @@ 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.
+
 `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.
 
+`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
 
 `readSecureFile()` throws `FsSafeError` with codes such as:
@@ -67,7 +73,7 @@ type SecureFileReadOptions = {
 | `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. |
-| `path-mismatch` | The path or realpath changed between open and verification. |
+| `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. |
 | `insecure-permissions` | Mode bits or ACLs grant broader access than allowed. |
@@ -75,6 +81,18 @@ type SecureFileReadOptions = {
 | `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.
+
 ## See also
 
 - [Permissions](permissions.md) — standalone POSIX mode and Windows ACL checks.

package/docs/security-model.md

@@ -49,10 +49,19 @@ Every path is resolved against the canonicalized real path of the root, then che
 
 ### Symlinks (read side)
 
-`open()` and `read()` use `fs.open` with `O_NOFOLLOW` on POSIX where available. The library then `fstat`s the open fd and `realpath`s the original input, asserting the two refer to the same inode (`sameFileIdentity`). A symlink swap that happens between resolve and open will fail at the identity check rather than silently following the new target.
+`open()` and `read()` use `fs.open` with `O_NOFOLLOW` on POSIX where available. The library then `fstat`s the open fd and `realpath`s the original input, asserting the two refer to the same inode. A symlink swap that happens between resolve and open will fail at the identity check rather than silently following the new target.
 
 Per-call `symlinks: "follow-within-root"` allows symlinks whose final target is still inside the root. The default is `"reject"`.
 
+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.
+
 ### Symlinks (write side)
 
 With the native binding loaded, `write()`, `create()`, and `copyIn()` use a
@@ -70,6 +79,14 @@ parent symlink. A same-privilege peer with write access to the parent can
 therefore cause an out-of-root side effect before the operation throws. Use
 native `require` mode when concurrent hostile mutation is in scope.
 
+The separate [retained-directory staging lifecycle](staged-file.md) keeps abort
+cleanup anchored to the original directory after a parent or ancestor move.
+It preserves observed substituted temporary entries and never cleans a recorded
+publication. Directory anchoring is not expected-inode/CAS replacement, and
+identity-check-then-unlink is not atomic conditional unlink. The guarantee
+requires the temporary name to remain owned and removal to remain permitted;
+application authorization and cooperative coordination remain necessary.
+
 ### Hardlink aliasing
 
 When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink > 1`, on the conservative assumption that a hardlinked file might alias an out-of-tree inode. This is defense-in-depth: the link count check is best-effort and platform-dependent. Treat it as a tripwire, not authorization.
@@ -107,6 +124,21 @@ durability guarantee.
 
 `extractArchive` first stages into a private temp directory (mode 0700) outside the destination, validates each entry path against `..` and absolute prefixes, refuses link-type entries by default, enforces entry count and byte budgets, and only then merges the staged tree into the destination through the same boundary checks used by direct writes.
 
+TAR extraction and bounded reads validate the complete decompressed raw framing
+before parser normalization: directory/link sizes must be zero, EOF must contain
+two consecutive zero blocks, and only zero padding may follow EOF. This rejects
+hidden headers and body/header smuggling consistently across the JavaScript and
+native backends. The meter checks logical member count before consuming bodies,
+even for unrequested or filtered members. Per-entry/cumulative payload budgets
+apply only to entries accepted after strip/filter policy, outside the raw meter.
+A separate absolute decoded cap includes every member body, headers, metadata,
+all padding, and EOF, closing cumulative-metadata and zero-tail bypasses. Native
+extraction/read passes drain through physical EOF before publication or
+returning selected bytes, even when the TAR parser stops earlier. Bounded
+reads use default archive admission limits and keep `maxBytes` scoped to the
+requested output. Metadata retains its per-record bound. See [archive framing](archive.md#raw-tar-framing) for supported
+metadata and compression formats.
+
 ## What "library-level" means
 
 A library cannot revoke its own caller's authority. If your code chooses to bypass `fs-safe` and call `fs.writeFile` directly with the same path, you bypass the defenses too. The contract `fs-safe` enforces is: *every filesystem operation that touches caller-controlled input goes through the boundary*. That contract is yours to keep.

package/docs/sidecar-lock.md

@@ -27,6 +27,8 @@ Each new sidecar also carries an internal random ownership token encoded as JSON
 
 The raw sidecar bytes are not a canonical JSON representation: tools that trim or rewrite the trailing whitespace invalidate the ownership token, so release leaves the changed sidecar in place and fails closed. The token distinguishes cooperating acquisitions; it is not a secret and does not make pathname compare-and-remove atomic against a hostile process that can replace files outside the lock protocol.
 
+`release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.
+
 ## API
 
 ```ts
@@ -92,6 +94,7 @@ type FileLockRetryOptions = {
 ```
 
 `payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
+Retry counts must be non-negative safe integers. Retry factors and delays must be finite and non-negative, and when both delay bounds are provided `minTimeout` cannot exceed `maxTimeout`. `timeoutMs` accepts a finite non-negative deadline or positive infinity for an unbounded wait; invalid numeric values reject before filesystem acquisition starts.
 `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.
@@ -176,7 +179,18 @@ detection, not revocation of work already in progress.
 retry, payload parsing, stale policy, owner-scoped reentrancy, guarded
 identity-conditioned reclaim, verification, and compromise monitoring. They do
 not use the async manager queue or support async callbacks. Retry waits block
-the calling thread; use the async API in request-serving code.
+the calling thread; use the async API in request-serving code. The sync
+compromise interval treats a thrown verification I/O error as a lost lock and
+invokes `onCompromised` once, matching the asynchronous `.catch(() => false)`
+contract. An explicit `verifyStillHeld()` call still propagates that I/O error.
+
+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`
+object replaces the entire configured retry object. A configured
+`staleRecovery: "remove-if-unchanged"` still needs per-call
+`shouldRemoveStaleLock` approval, and per-call `staleRecovery: "fail-closed"`
+disables recovery even when the process configuration opts in.
 
 Always release in a `finally`:
 

package/docs/staged-file.md

@@ -0,0 +1,178 @@
+---
+title: Retained-directory staging
+description: "Prepare and publish one file while retaining its original directory for abort cleanup."
+---
+
+# Retained-directory staging
+
+`stageFileInDirectory()` from `@openclaw/fs-safe/advanced` prepares one file in
+an existing directory and keeps that directory open until cleanup or disposal.
+It requires the native binding on Linux or macOS, even in native mode `auto`.
+Native off, an unavailable binding, or a binding without the required mechanism
+fails before file creation. Windows is explicitly unsupported for this API.
+Existing root, output, temp, lock, and durability APIs retain their documented
+platform and fallback contracts.
+
+```ts
+import type { DirectoryReceipt } from "@openclaw/fs-safe/durability";
+import {
+  stageFileInDirectory,
+  type PublishedFileReceipt,
+} from "@openclaw/fs-safe/advanced";
+
+// Call while holding the application's cooperative writer lock. The caller
+// supplies its authorization, manager, snapshot, and fingerprint checks.
+export async function publishReviewedUpdate(options: {
+  directory: DirectoryReceipt;
+  basename: string;
+  bytes: Uint8Array;
+  assertAuthorizedAndCurrent(): Promise<void>;
+}): Promise<PublishedFileReceipt> {
+  await options.assertAuthorizedAndCurrent();
+  await using staged = await stageFileInDirectory({
+    directory: options.directory,
+    content: options.bytes,
+  });
+  await options.assertAuthorizedAndCurrent();
+  await staged.assertCurrent();
+  return await staged.publish(options.basename, { overwrite: true });
+}
+```
+
+`await using` always disposes, including on exceptions. If both the body and
+disposal fail, JavaScript preserves both errors in a `SuppressedError`. A
+successful return means publication was observed and verified, not that a
+separate application transaction committed. Application rollback and recovery
+remain with the caller.
+
+## API
+
+```ts
+function stageFileInDirectory(options: {
+  directory: string | DirectoryReceipt;
+  content: string | Uint8Array;
+  mode?: number;
+}): Promise<StagedFile>;
+
+interface StagedFile extends AsyncDisposable {
+  readonly receipt: StagedFileReceipt;
+  assertCurrent(): Promise<void>;
+  publish(basename: string, options: { overwrite: boolean }): Promise<PublishedFileReceipt>;
+  cleanup(): Promise<StagedFileCleanupReceipt>;
+}
+```
+
+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.
+After rename succeeds and the published entry passes identity validation, the
+owner applies the requested mode through its retained file descriptor and
+synchronizes the file. No parent is created or chmodded.
+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.
+Returned receipts are frozen descriptive snapshots, not mutable authority.
+Changing a supplied receipt after admission cannot retarget the lifecycle.
+
+`StagedFileReceipt` contains `directory` (`path`, `realPath`, and exact bigint
+`identity.dev`/`identity.ino`), `temporaryBasename`, and the prepared file's
+`identity` (`dev`, `ino`, `size`, `nlink`, `mtimeNs`, `ctimeNs` as bigint;
+`mode`, `uid`, `gid` as numbers). This is a preparation-time snapshot of the
+private stage: its mode is `0600`. Publication does not refresh this snapshot;
+neither its mode nor its timestamps are a final-file fingerprint. No raw
+descriptors are exposed.
+
+`assertCurrent()` verifies the original pathname's directory identity and the
+staged name against the retained file. A failed check does not disable cleanup.
+After successful publication there is no staged name to check, so further
+checks or publication reject. Cleanup closes the lifecycle; later checks and
+publication reject before descriptor use. Rejected publication still carries its
+phase, cause, and recorded publication outcome after closure. Concurrent calls
+are serialized in invocation order, including cleanup and disposal. Repeated
+cleanup returns the recorded outcome, or repeats the recorded error, without
+touching descriptors.
+
+## Publication and failure evidence
+
+`publish()` requires an explicit boolean `overwrite` and one direct-child
+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
+`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.
+
+`PublishedFileReceipt` has `status: "published"`, `staged`, `basename`, and
+`overwrite`. Its `staged` field retains the private preparation snapshot, not
+final metadata. Errors from publication carry typed `StagedFileFailureDetails`
+in `FsSafeError.details`, including `phase` and `publication`. Publication is
+`not-published`, `published` (with its receipt), or `indeterminate` (with the
+attempted basename and overwrite policy) if a rename error cannot establish
+whether it committed. The underlying error remains in `cause`.
+
+A parent move after the final pre-check cannot divert the rename to a
+replacement parent. It can publish inside the moved original and then fail
+post-validation. Successful rename is recorded before those checks; cleanup
+never deletes or rolls back a published final name. Indeterminate publication
+also preserves names for caller-directed recovery.
+
+The same rule applies if applying the published mode, synchronizing, or a later
+check fails: the error reports `published`, and cleanup preserves the final
+name. The file may still have mode `0600` or may already have the requested
+mode, depending on which operation failed. A `published` failure receipt records
+rename success, not successful permission finalization.
+
+## Cleanup guarantee and limits
+
+If the temporary basename still names the object created by this lifecycle and
+filesystem removal remains permitted, moving or replacing the actual parent
+(or an ancestor) does not strand the unpublished temp. Cleanup resolves through
+the retained original directory, even after `assertCurrent()` rejects drift.
+Same-name sentinels in the replacement parent are not touched.
+
+`StagedFileCleanupReceipt` records `temporaryBasename`, `publication`,
+`resources` (`closed` or `close-failed`), and `status`:
+
+| Status | Meaning |
+|---|---|
+| `removed` | The owned recorded name was unlinked through the retained directory. |
+| `name-absent` | That name was absent in the original directory; this does not prove the inode has no other names. |
+| `preserved` | An observed substitute or an indeterminate publication was left alone. |
+| `failed` | Inspection or removal failed. |
+| `not-needed` | Publication was recorded, or preparation failed before creating a file. |
+
+Explicit cleanup returns preservation outcomes. Removal or close failures throw
+an `FsSafeError` with the receipt in `details.cleanup` and underlying errors in
+`cause`. Disposal also throws for preservation, so ignoring its return value
+cannot hide incomplete cleanup. Setup failures preserve the original error;
+when cleanup also fails, an aggregate cause retains both failures. Descriptors
+are closed on every cleanup outcome, with no retry through recycled numbers.
+
+This is **directory-relative targeting**, not expected-destination-inode/CAS
+publication. Checking an identity before rename does not make rename CAS.
+Likewise, the identity check followed by `unlinkat` is not an atomic conditional
+unlink: an adversary can replace the leaf in that final syscall gap. Observed
+substitutions are preserved, but this API does not guarantee recovery after
+arbitrary child renames, permission revocation, I/O failure, or process death.
+Keep application authorization, manager checks, snapshots, fingerprints,
+cooperative locks, and conditional rollback.
+
+Namespace cleanup is not crash durability. Staging retains the native writer's
+file synchronization behavior, and publication synchronizes its directory
+(with the existing `EPERM` exception); cleanup does not promise a durable unlink.
+No successful receipt promises survival across a crash. See [Directory
+durability](durability.md) when an application needs a separate durability proof.
+`pinDirectory().assertCurrent()` and `.sync()` still require a current pathname;
+they do not gain this cleanup authority.
+
+## Related pages
+
+- [Advanced composition](advanced.md)
+- [Native architecture](native.md)
+- [Security model](security-model.md)

package/docs/store.md

@@ -68,6 +68,19 @@ Use `ackJsonDurableQueueEntry()` after durable processing succeeds and
 `moveJsonDurableQueueEntryToFailed()` when the caller wants to quarantine an
 entry for inspection.
 
+Loading serializes consumers for one ID through a sidecar lock, then creates `processingPath` with a no-replace hardlink and retires the source through a recoverable sibling record. Whichever producer generation occupies `.json` at the hardlink operation becomes the claim; a replacement published afterward remains pending. After a crash, `.processing` is retried before that pending replacement. Transfer locks are fail-closed and are never reclaimed automatically, so an operator must remove a proven-stale lock after a hard process crash. Acknowledgement atomically moves `.processing` through the short-lived `.delivered` marker, and existing delivered markers are cleaned during batch loading. `ackJsonDurableQueueEntry()` rejects while `.json` exists without a processing claim: callers that previously paired direct `readJsonDurableQueueEntry()` with acknowledgement must load through `loadJsonDurableQueueEntry()` before processing so acknowledgement is generation-bound.
+
+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; quarantine retries with only failed evidence resync that destination before repairing the vanished queue source.
+
+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.
+
+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
+unknown identity gets one bounded reinspection; persistent ambiguity or a
+mismatch rejects with `queue entry changed during read`. Each inspection still
+rejects non-files, symlinks, hardlinks, and entries over the byte limit.
+
 ## Related pages
 
 - [`fileStore`](file-store.md) — full API for the multi-file store.

package/docs/temp.md

@@ -14,7 +14,7 @@ import {
 
 ## Private temp workspaces
 
-A private workspace is a directory created at mode `0o700` under a caller-provided temp root. It is unique per call (random suffix) and cleaned up when you call `cleanup()` or leave an `await using` scope.
+A private workspace is a directory created at mode `0o700` under a caller-provided temp root. It is unique per call (random suffix). Calling `cleanup()` or leaving an `await using` scope moves an unchanged workspace through a private quarantine before removal. Descriptor-bounded cleanup prevents recursive traversal of substitutions; the compatible JavaScript fallback has the narrower race contract documented below.
 
 ### `tempWorkspace`
 
@@ -31,7 +31,7 @@ type TempWorkspace = {
   writeJson(fileName: string, data: unknown, options?: { trailingNewline?: boolean }): Promise<string>;
   copyIn(fileName: string, sourcePath: string): Promise<string>;
   read(fileName: string): Promise<Buffer>;
-  cleanup(): Promise<"removed" | "missing" | "identity-mismatch">;
+  cleanup(): Promise<"removed" | "missing" | "identity-mismatch" | "indeterminate">;
   [Symbol.asyncDispose](): Promise<void>;
 };
 ```
@@ -64,12 +64,66 @@ await state.write({ ready: true });
 The workspace owns cleanup; the store is only a view over the workspace
 directory.
 
-The identity receipt is captured when the workspace is created. Manual,
-disposal, and process-exit cleanup remove the path only while `lstat` still
-matches that receipt. If another actor renames the workspace away and places a
-new directory at the old name, cleanup returns `"identity-mismatch"` and leaves
-the replacement untouched. Disposal hooks perform the same check and ignore
-the returned status.
+**Compatibility and security:** workspace creation remains available in native
+`auto`, `off`, and unavailable-native environments. The default
+`cleanupSafety: "compatible"` preserves the JavaScript cleanup behavior from
+0.6: it verifies the workspace identity, moves the public name to a fresh
+`.fs-safe-workspace-cleanup-<uuid>` sibling, verifies that quarantine, and then
+uses guarded pathname-recursive removal. This fallback never recursively
+removes the public workspace name, but it is not atomic conditional deletion: a
+same-privilege peer that discovers and replaces the private quarantine after
+verification can still redirect the final pathname removal.
+
+Set `cleanupSafety: "require-bounded"` when that concurrent attacker is in scope.
+Creation then requires native no-replace directory rename, native owned-tree
+removal, and a retained parent descriptor **before** `mkdtemp` creates
+a child. If any capability is unavailable, creation throws
+`FsSafeError("helper-unavailable")`; no child is created and a scoped callback is
+not called. The compatible default retains its fallback even if process-global
+native mode is `require`; select `require-bounded` to make cleanup capability
+mandatory for this API.
+
+On Linux, bounded cleanup requires a successful runtime probe of the exact
+`openat2` child-directory flags, including `RESOLVE_NO_XDEV`, against the retained
+parent descriptor. If the kernel or seccomp policy denies that capability,
+compatible mode uses the guarded JavaScript fallback; `require-bounded` rejects
+before child creation. The probe runs once at creation, without filesystem mutation.
+
+Bounded cleanup checks the parent and public workspace identity, quarantines
+the direct child without replacement, and verifies the quarantine against the
+retained workspace descriptor. It binds every enumerated child to its native
+identity before opening it, rejects mount crossings, and traverses descendants
+only through opened directory handles; symlinks/reparse entries are removed as
+leaves and never traversed. Windows marks the exact opened objects for deletion by handle.
+
+POSIX has no unlink-by-fd or expected-inode unlink for directory entries. After
+the final identity check, each `unlinkat` can still be raced; the possible side
+effect is bounded to one substituted non-directory leaf or one empty directory
+entry per raced syscall. A substituted nonempty directory is never recursively
+traversed and is preserved as `"indeterminate"`, but a leaf replacement removed
+in that irreducible final gap cannot be distinguished after the syscall.
+
+The workspace captures its identity, binding, and descriptors until cleanup.
+Later process-global mode changes or loader resets do not revoke that authority.
+Manual, disposal, and process-exit cleanup share one serialized owner,
+registered before store construction; a construction failure after registration
+remains exit-cleanable. Earlier creation failures close retained descriptors
+without deleting an unverified child.
+
+If the quarantine does not match the creation descriptor, cleanup leaves it in
+place without restoring the public name or recursively deleting it and returns
+`"indeterminate"`. A collision, uncertain rename outcome, changed parent,
+mount/device crossing, changed reparse state, or detected concurrent mutation also
+preserves the remaining artifact. Recover `.fs-safe-workspace-cleanup-<uuid>` entries only
+after excluding competing mutators and re-establishing ownership.
+
+A missing workspace returns `"missing"`. A replacement observed at the public
+name before quarantine returns `"identity-mismatch"` when the parent is stable;
+an ambiguous parent returns `"indeterminate"`. After successful removal,
+repeated cleanup returns `"missing"` without touching a recreated public name.
+Other statuses remain stable. Operational removal errors propagate and later
+cleanup returns `"indeterminate"` without retrying. Disposal and scoped helpers
+ignore returned statuses, while manual cleanup exposes the result.
 
 When cleanup is part of a retention or audit decision, inspect the receipt
 instead of treating cleanup as fire-and-forget:
@@ -82,6 +136,8 @@ try {
   const cleanup = await workspace.cleanup();
   if (cleanup === "identity-mismatch") {
     alertOperator("restore workspace path was replaced; replacement preserved");
+  } else if (cleanup === "indeterminate") {
+    alertOperator("restore workspace cleanup could not establish safe completion; inspect retained entries");
   }
 }
 ```
@@ -91,7 +147,7 @@ types and a `FileStoreSync` at `workspace.store`.
 
 ### `withTempWorkspace`
 
-The recommended shape. Auto-cleanup on every exit path:
+The recommended shape. Attempts cleanup on every exit path:
 
 ```ts
 import { withTempWorkspace } from "@openclaw/fs-safe/temp";
@@ -129,6 +185,7 @@ type TempWorkspaceOptions = {
   prefix: string;           // dir prefix (sanitized)
   dirMode?: number;         // dir mode; default 0o700
   mode?: number;            // file write mode; default 0o600
+  cleanupSafety?: "compatible" | "require-bounded"; // default compatible
 };
 ```
 
@@ -205,11 +262,65 @@ const result = await writeSiblingTempFile<string>({
 // result.filePath, result.result (returned by writeTemp)
 ```
 
-`writeSiblingTempFile` chooses a random sibling name in `dir`, calls your `writeTemp()` callback, validates that `resolveFinalPath(result)` is still inside that same directory, and renames the temp file there.
-
-By default it preserves the historical private-helper behavior of chmodding
-`dir` to `dirMode` (default `0o700`). Pass `chmodDir: false` when the directory
-is a public staging/output path whose existing mode must be preserved.
+`writeSiblingTempFile` chooses a random, initially absent sibling name in `dir`
+and calls `writeTemp()`. After the callback succeeds, it validates the produced
+regular file before taking ownership: symlinks, directories, other non-regular
+files, hardlinks, and changes between the pre-open pathname, opened descriptor,
+and current pathname are rejected. The callback must finish and close its
+writer before returning. Its return value is preserved as `result`.
+
+The helper retains one descriptor through requested mode application, opt-in
+file synchronization, rename, and publication verification. It opens read-only
+unless file synchronization is requested, so closed read-only producer output
+remains publishable under the historical default. Omitting
+`mode` preserves the callback-produced mode without chmod; explicit modes,
+including `0`, are applied through that descriptor. File-mode errors are
+tolerated for compatibility with the helper's historical best-effort behavior.
+No chmod, content read, or reopen follows
+the staged or published pathname. `resolveFinalPath(result)` must resolve to a
+distinct direct child of the same directory. Final-path writes are serialized
+within the process, and the retained descriptor and current name must still
+have the admitted exact bigint identity and exactly one link before rename and
+after publication. A verification failure after rename does not roll back or
+delete the final name.
+
+`syncTempFile` and `syncParentDir` retain their historical `false` defaults.
+Explicit `syncTempFile: true` synchronizes the descriptor before rename;
+file-sync errors propagate except for the existing `EPERM` compatibility case.
+Explicit `syncParentDir: true` requests best-effort parent sync after rename.
+Omitting either option or passing `false` skips that sync, never the identity
+checks. Parent synchronization can be unsupported or fail without rejecting
+the write, so success is not a strict crash-durability receipt.
+
+Cleanup only unlinks an admitted file while the parent, pathname identity, and
+single-link regular-file checks still agree. Observed substitutes are preserved,
+including during process-exit cleanup. Operational cleanup failures retain an
+identity-bound exit retry. If the callback throws or admission fails, no file
+has been adopted: even a regular partial file is left for caller-directed
+recovery. The helper never recursively removes a sibling temp.
+
+On POSIX, admission uses no-follow and nonblocking open flags, so a FIFO swap
+does not block the helper. Windows retains Node's guarded pathname-open behavior
+because Node has no portable no-follow flag there; metadata is checked before
+and after opening, and unknown Windows identities fail closed after one bounded
+re-inspection without reopening. These helpers remain available with native
+mode `off`; they do not acquire the native-required retained-directory contract
+of [`stageFileInDirectory`](staged-file.md).
+
+Identity checks and pathname rename/unlink are separate syscalls, not atomic
+conditional mutations. A hostile process can still replace a leaf or parent in
+the final syscall gap or mutate an open file's contents. Use an approved writable
+directory and cooperative locking or OS isolation; a moved parent can leave an
+unpublished original temp behind. Observed replacements are preserved, but
+arbitrary concurrent namespace changes cannot be prevented by these helpers.
+
+By default the helper attempts to set `dir` to `dirMode` (default `0o700`)
+through the shared verified POSIX directory-descriptor helper. Only the actual
+descriptor chmod error is tolerated, preserving the historical best-effort
+directory-mode behavior. Directory lstat, open, type, identity, and close errors
+still propagate; there is no pathname chmod fallback. Windows only passes the
+directory mode to `mkdir`. Pass
+`chmodDir: false` when an existing staging/output directory mode must be preserved.
 
 ### `writeViaSiblingTempPath`
 
@@ -232,6 +343,9 @@ await writeViaSiblingTempPath({
 If `replaceFileAtomic` does what you need, prefer that. Use
 `writeViaSiblingTempPath` when the producer needs a concrete temp pathname but
 the final destination still needs root-boundary checks.
+Its private workspace uses the same identity-aware directory cleanup as
+`tempFile()`: moving and replacing the workspace preserves the replacement.
+This workspace owns its contents, unlike the unadmitted sibling pathname above.
 
 ## Secure temp root
 

package/docs/testing.md

@@ -17,7 +17,7 @@ The double-underscore prefix is a deliberate "hands off" signal: production code
 ## When to reach for hooks
 
 - Reproduce a TOCTOU race deterministically: simulate a symlink swap between resolve and open, or between write and rename.
-- Force guarded JavaScript behavior without removing bundled binaries from your runners.
+- Force guarded JavaScript behavior without removing platform packages from your runners.
 - Inject latency to test cancellation/timeout paths.
 
 If you don't need to inject a race, you don't need hooks — most tests should drive the library through normal calls and assert on observable behavior.

package/docs/writing.md

@@ -33,6 +33,10 @@ old-or-new guarantee does not apply to `append()` or `openWritable()`, which
 write in place, or to lower-level atomic helpers when their explicitly
 non-atomic permission-error copy fallback is enabled.
 
+Post-publication verification can still reject after a complete replacement has
+been committed. Rejection does not promise that a successful rename was rolled
+back; the published file or a raced replacement may remain at the destination.
+
 ## Denying mutations
 
 All mutation verbs accept `denyMutations?: DenyMutationPolicy`, either as a root default or per-call option:
@@ -64,6 +68,21 @@ await fs.write("notes/today.txt", "hello\n", { encoding: "utf8" });
 
 `data` accepts `string | Buffer`. `options` are `{ denyMutations?: DenyMutationPolicy; encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean; renameIdentity?: RenameIdentityPolicy }`. `mode` sets the file's POSIX mode. If neither the call nor `RootDefaults` supplies it, a replacement preserves the existing file mode and a new file uses `0o600`. `mkdir` and `overwrite` both default to `true`; set `overwrite: false` for the same no-clobber behavior as `create()`.
 
+POSIX modes without read permission, including `0o000` and `0o200`, succeed:
+final verification uses a descriptor retained by the writer rather than reopening
+the published file. The requested mode is not relaxed for verification.
+Publication verification compares exact bigint descriptor and pathname identities,
+including large file indexes that cannot be represented by a JavaScript number.
+Later reads still obey OS permissions, and access checks on a pre-existing
+destination are unchanged. The explicit FUSE compatibility policy still requires
+a readable destination to prove matching content when rename changes its identity.
+
+When Windows cannot report a pathname's identity, the publication verifier reopens
+the name and compares that descriptor's exact identity with the original retained
+file, without reading bytes. It also rechecks links and root/parent containment.
+This write-specific proof does not relax ordinary reads: unknown pathname metadata
+alone is never proof that the name still refers to the expected file.
+
 ### `fs.create(rel, data, options?)`
 
 Don't-clobber variant of `write()`. Throws `already-exists` if the target is there.