@openclaw/fs-safe 0.6.0 → 0.7.1

package/docs/root.md

@@ -38,6 +38,8 @@ type DenyMutationPolicy = {
 
 `defaults` apply to every method on the returned handle. Per-call options on individual methods override the defaults for that call only, except `denyMutations`: root and per-call deny entries are merged so a call cannot clear a root-level deny.
 
+Every `maxBytes` value must be a non-negative safe integer or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` explicitly disables the cap. An omitted or explicitly `undefined` per-call value preserves the configured Root default instead of clearing it.
+
 ## The `Root` interface
 
 Every method on the returned handle accepts paths relative to the root and rejects anything that would escape it.

package/docs/secret-file.md

@@ -73,6 +73,8 @@ type SecretFileReadOptions = {
 };
 ```
 
+`maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap, `Infinity` disables it, and omitted or explicitly `undefined` values preserve the 16 KiB default.
+
 The reader trims the file content and rejects empty results. Symlink paths are
 followed and pinned by default; set `rejectSymlink: true` when the pathname
 itself must not be an alias. Hardlinks are rejected by default so another
@@ -90,7 +92,9 @@ the same pinned-handle validation, byte cap, trimming, error codes, and strict
 versus missing-is-undefined naming semantics.
 
 Both sync and async readers compare lossless bigint identities from the preview,
-opened descriptor, resolved target, and current input path before reading. An
+opened descriptor, resolved target, and current input path before reading. POSIX
+opens are nonblocking, so a raced FIFO is rejected by descriptor type instead of
+waiting for a writer. An
 allowed symlink must still point to the opened file. On Windows, a zero device
 or inode is unverified: that inspection is retried once without reopening the
 file, preserving known identity components and link checks. Definite mismatches

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
@@ -57,6 +57,8 @@ 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.

package/docs/security-model.md

@@ -58,6 +58,9 @@ 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)
 
@@ -121,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,15 +94,21 @@ type FileLockRetryOptions = {
 ```
 
 `payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
+Errors thrown by `payload`, its JSON serialization (including `toJSON`), or
+`parsePayload` propagate unchanged without retrying the callback. Rethrowing an
+error saved from an earlier filesystem operation does not grant retry authority.
+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.
 
 On Windows, a pathed `EPERM` from creating or opening the lock file can be a
-short teardown race after another holder unlinks it. The async lock retries that
-specific denial at most eight times. A parent-directory denial, a denial from a
-callback, or a ninth consecutive lock-file denial surfaces as the original
-`EPERM`; it is not converted to `file_lock_timeout`.
+short teardown race after another holder unlinks it. Both async and sync locks
+retry that specific open denial at most eight times per acquisition, within the
+caller's retry/deadline budget. A parent-directory denial, a callback/read/stat
+failure, or exhaustion of either budget surfaces the original error; a denied
+open is not converted to `file_lock_timeout`. Retrying always requires fresh
+exclusive creation and grants no ownership or removal authority.
 
 ## Owner-scoped reentrancy
 
@@ -152,6 +160,45 @@ an existing `Root` capability. `lockPath` must resolve inside that root.
 Identity-conditioned removal remains the only release and reclaim deletion
 path.
 
+An owner can finish releasing while another async acquirer inspects its record.
+Create-only Root writes do not open an existing record merely to inherit its
+mode. Once a pathname sample and opened descriptor agree, a failed acquisition
+snapshot can be discarded only when the original descriptor has exact identity,
+was not observed with multiple links, and proves it was unlinked (`nlink === 0`).
+This includes Windows resolver
+`EPERM`/`EBADF` failures, with evidence captured at the failing operation before
+closing the descriptor. The canonical in-root ancestor chain and Root are
+rechecked; permitted in-root parent symlinks are resolved before those checks.
+
+A contending waiter may also encounter a new holder between its pre-open
+pathname inspection and opening the file. It may discard that stale observation
+only when the old sample and opened descriptor have different, strictly known
+regular-file identities, neither was observed with multiple links, and the
+opened descriptor and complete canonical ancestry pass reinspection. This does
+not prove the old pathname sample was unlinked rather than moved. The new
+holder's payload is not read or adopted. Post-create admission never opts into
+this pre-open-change policy.
+
+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.
+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
+errors fail closed. Failure receipts belong only to the current Root observation,
+including during nested or concurrent acquisitions; historical error identity
+is not changed-file, unlink, or open-denial evidence.
+
+After creating a record, the async Root-backed acquirer checks the reopened
+bytes against its exact serialized payload and ownership token. A replacement
+is never adopted; a descriptor observed unlinked at the end of admission is
+never registered as held. Failed admission cleanup retains the original creator
+receipt, so it cannot remove a replacement using a later stat alone. Native
+mode changes the create mechanism, not these Root-backed admission checks.
+Non-Root and synchronous snapshots retain their descriptor/read/path checks
+and do not use the Root opened-path resolver.
+
 ## Release handle
 
 ```ts
@@ -181,7 +228,16 @@ 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.
 
+Windows synchronous lock parents use the same canonical path spelling as
+`root()`, including short-name expansion. With `lockRoot`, a failed parent
+canonicalization or an out-of-root parent still rejects. Missing-path observations from snapshot
+`lstat`/`open`, and identity-mismatched snapshots, consume the normal retry and
+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.
+
 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

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/writing.md

@@ -27,6 +27,9 @@ await fs.mkdir("snapshots/2026/05");
 5. Atomically rename the temp file over the destination.
 6. Stat the resulting fd and verify identity.
 
+Private sibling temporary names are independent of the destination basename,
+so staging does not add a suffix to an otherwise valid long filename.
+
 A failure before the final rename leaves the destination at its previous
 contents. A successful rename publishes the complete replacement. This
 old-or-new guarantee does not apply to `append()` or `openWritable()`, which
@@ -86,6 +89,9 @@ 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.
+Create-only preflight preserves boundary, alias, hardlink, and type checks without
+opening an existing target to inherit its mode; a fresh file uses the requested
+mode or the normal new-file default.
 
 ```ts
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -128,7 +128,7 @@
     "prepack": "node scripts/prepack-build.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:coverage:collect": "vitest run --coverage --coverage.reporter=json --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.statements=0 --coverage.thresholds.branches=0",
+    "test:coverage:collect": "pnpm build && vitest run --coverage --coverage.reporter=json --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.statements=0 --coverage.thresholds.branches=0",
     "test:coverage:merge": "node scripts/merge-coverage.mjs",
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
     "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm docs:check && pnpm test && node scripts/check-pack.mjs",
@@ -149,20 +149,20 @@
     "crabbox:warmup": "crabbox warmup"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.6.0",
-    "@openclaw/fs-safe-darwin-x64": "0.6.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.6.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.6.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.6.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.6.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.6.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.7.1",
+    "@openclaw/fs-safe-darwin-x64": "0.7.1",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.7.1",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.7.1",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.7.1",
+    "@openclaw/fs-safe-linux-x64-musl": "0.7.1",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.7.1",
     "jszip": "^3.10.1",
     "tar": "7.5.22"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.4",
     "@napi-rs/cli": "3.8.6",
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.4.0",
     "@vitest/coverage-v8": "4.1.11",
     "fast-check": "^4.9.0",
     "istanbul-lib-coverage": "3.2.2",