@openclaw/fs-safe 0.11.0 → 0.12.0

package/docs/contributing.md

@@ -76,7 +76,10 @@ setup use `useSuiteFixture` from `test/helpers/suite-fixture.ts`: setup has a se
 removing directories. Run shared-state corpora sequentially with a deadline per
 payload. Keep child-process liveness limits separate from fixture preparation.
 The Windows CI slow-copy proof runs the real package-copy process-exit test with a
-six-second copy delay, retaining its four-second child deadline:
+16-second copy delay, a 10-second child deadline, a 15-second test deadline, and
+60-second setup and teardown hook budgets. Other hosts retain the ordinary
+six-second delay, four-second child deadline, five-second test deadline, and
+30-second hook budgets:
 
 ```bash
 pnpm build

package/docs/copy.md

@@ -64,7 +64,7 @@ Automatic copying does not recover from permission errors, I/O errors, cancellat
 
 On Windows, automatic byte copying uses the native binding when available to transfer data between the already-checked file handles in chunks of at most 1 MiB, with smaller buffers for small files. This accelerates NTFS and cross-volume copies without reopening source or destination pathnames. The native worker finishes before its descriptors are closed or cancellation is reported. `clone: "never"` and native-disabled copies use JavaScript read/write loops with reusable buffers: at most 1 MiB per active file on Windows, or 128 KiB elsewhere. Both paths share the file-worker budget across sibling directories, wait for all admitted writes after cancellation or failure, and restore directory timestamps after their descendants finish. Completed directory traversals awaiting writes or metadata are bounded by concurrency; ancestors remain pinned while traversing their children.
 
-On Linux, automatic byte copying also uses the native binding when available. It reads in 1 MiB chunks and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
+On Linux, automatic byte copying also uses the native binding when available. It reads in chunks up to 1 MiB, using smaller buffers for smaller source-size hints, and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
 
 Clones preserve file contents, empty directories, timestamps, executable modes where supported, and literal symbolic links. Editing a clone does not modify its source. Unsupported filesystem operations fail; callers may choose their own copy or checkout fallback after the failed operation has settled.
 

package/docs/durability.md

@@ -242,8 +242,10 @@ When the optional binding is active, hashing runs as an async native task and
 does not occupy the JavaScript event loop with digest updates. With native mode
 `off`, or in `auto` when no binding loads, the fallback performs asynchronous
 positioned reads in chunks of up to 256 KiB but updates Node's `Hash` on the JavaScript
-thread. Both paths stream constant-size buffers rather than loading the file
-into memory. Native mode `require` keeps its usual fail-closed loader semantics.
+thread. Both paths stream bounded buffers rather than loading the file into memory.
+The fallback sizes its scratch buffer to small files and grows it if a stale
+size hint is exceeded, while still probing for actual EOF and byte-limit overflow.
+Native mode `require` keeps its usual fail-closed loader semantics.
 
 ### Synchronous hashing
 

package/docs/file-store.md

@@ -256,6 +256,12 @@ type FileStorePruneOptions = {
 
 Symlinks are skipped. The walk is best-effort — failures on individual entries don't abort the whole prune. Compares against `mtimeMs`.
 
+Pruning rechecks that a selected entry is still a regular file and still expired
+immediately before guarded removal. Fresh replacements and in-place timestamp
+refreshes are preserved; replacements that are themselves expired remain
+eligible. This does not require read permission. The existing best-effort
+external-process race window after dispatch still applies.
+
 ## Difference from `Root`
 
 | `FileStore` | `Root` |

package/docs/filename.md

@@ -1,6 +1,6 @@
 # Filenames
 
-`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; pair with [`safeDirName`](install-path.md#safedirname) when you need stricter directory-name handling.
+`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; use [`safePathSegmentHashedV2`](install-path.md#safepathsegmenthashedv2) when mapping untrusted install IDs to separate directory names.
 
 ```ts
 import { sanitizeUntrustedFileName } from "@openclaw/fs-safe/advanced";
@@ -27,6 +27,13 @@ In order:
 6. **Suffix Windows reserved basenames.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension, preserving the original case and extension on every platform.
 7. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
 
+If truncation itself exposes a reserved-device basename after Windows ignores
+trailing spaces or dots, the result is shortened once more and receives the
+same underscore suffix. A name that reaches the sanitization branch therefore
+remains at most 200 UTF-16 code units and is never a Windows reserved-device
+alias. `fallbackName` is returned verbatim for empty or path-alias input, so
+callers must supply a fallback that already satisfies their filename policy.
+
 That's it. The function stays intentionally small: it removes traversal and
 the most obvious cross-platform device and character hazards, but it is not a
 complete portable-filename or uniqueness policy.
@@ -92,5 +99,5 @@ await fs.write(`uploads/${safe}`, body); // fs is a Root() handle; rejects trave
 
 ## See also
 
-- [Install path helpers](install-path.md) — `safeDirName`, `safePathSegmentHashed` for directory-segment sanitization.
+- [Install path helpers](install-path.md) — legacy directory-segment sanitizers and `safePathSegmentHashedV2` for untrusted install IDs.
 - [`root()`](root.md) — the boundary you'll write into after sanitizing.

package/docs/guest.md

@@ -113,6 +113,11 @@ prefixes and use short random suffixes independent of the destination basename,
 so legal names near the filesystem's component limit also work for writes and
 cross-device moves.
 
+Cross-device symlink moves create the new link in a private destination-side
+staging directory before atomically replacing the destination. Link creation or
+publication failure preserves the existing destination and source link; ordinary
+failure cleanup removes the staging directory.
+
 Cross-device directory moves build a copy manifest and check it during source
 cleanup. Source changes can leave the published destination and some or all
 of the source. Regular-file and symlink move fallbacks unlink the source

package/docs/install-path.md

@@ -8,6 +8,7 @@ import {
   resolveSafeInstallDir,
   safeDirName,
   safePathSegmentHashed,
+  safePathSegmentHashedV2,
 } from "@openclaw/fs-safe/advanced";
 ```
 
@@ -35,14 +36,17 @@ if (!r.ok) return reply(400, r.error);
 await fs.mkdir(r.path, { recursive: true });
 ```
 
-For ids whose default-sanitized form might collide (e.g. `"foo/bar"` and `"foo\\bar"` both map to `"foo__bar"`), pass `nameEncoder: safePathSegmentHashed` to append a content hash:
+For untrusted IDs that must occupy separate install directories, pass
+`nameEncoder: safePathSegmentHashedV2`. The default `safeDirName` and legacy
+`safePathSegmentHashed` can map distinct IDs to the same directory; the boundary
+check does not establish which ID owns an existing directory.
 
 ```ts
 const r = resolveSafeInstallDir({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   id: untrustedId,
   invalidNameMessage: "invalid plugin name",
-  nameEncoder: safePathSegmentHashed,
+  nameEncoder: safePathSegmentHashedV2,
 });
 ```
 
@@ -87,11 +91,48 @@ safeDirName("");                       // ""
 
 `safeDirName` does *not* try to be exhaustive about Windows-reserved names or special characters. It is purely a separator-stripping pass — `resolveSafeInstallDir` adds the boundary check on top so an `"../../etc"` input cannot escape `baseDir`.
 
-For stricter sanitization, use `safePathSegmentHashed`.
+Use `safePathSegmentHashedV2` when distinct untrusted IDs need separate names.
+
+### `safePathSegmentHashedV2`
+
+```ts
+function safePathSegmentHashedV2(input: string): string;
+```
+
+Hashes every trimmed ID, including ordinary short names, into `id-v2-` followed
+by 64 lowercase hexadecimal SHA-256 digits. The result is always 70 ASCII bytes,
+contains no separators, and avoids Windows device names and ignored suffixes.
+There is no readable prefix to truncate and no unchanged-name branch. Distinct
+trimmed IDs, including an ID that looks like an encoded output, remain distinct
+unless their full SHA-256 digests collide. The lowercase ASCII output also
+preserves that distinction on case-insensitive and Unicode-normalizing volumes.
+
+The stable V2 digest recipe is SHA-256 of the UTF-8 bytes of
+`"@openclaw/fs-safe:install-path:v2\0"`, followed by the UTF-16LE bytes of
+`input.trim()`, without a byte-order mark. The NUL-terminated prefix separates
+this use of SHA-256 from other hash domains. UTF-16LE preserves exact JavaScript
+code units, including lone surrogates. Inputs are not case-folded or Unicode
+normalized. Surrounding whitespace, as removed by JavaScript `String.trim()`,
+is the only intentional equivalence; internal whitespace remains significant.
+
+```ts
+const segment = safePathSegmentHashedV2("plugin/v1"); // id-v2-<64 hex digits>
+safePathSegmentHashedV2(" plugin/v1 ") === segment;  // true
+safePathSegmentHashedV2("Plugin/v1") === segment;    // false
+```
+
+This encoder computes a name; it does not authorize access or prove ownership
+of a directory. Store the original trimmed ID in application-owned metadata and
+verify it before reusing an existing install directory. Keep each install tree
+on one encoding version. Switching to V2 changes existing paths: use a new base
+directory or explicitly migrate directories after verifying their recorded IDs.
+Do not silently fall back to a legacy path when the V2 path is missing.
 
 ### `safePathSegmentHashed`
 
-Returns a directory-safe segment **plus** a short content hash when sanitization changed the input or when the safe form is too long. Use this when input collisions matter:
+Legacy readable encoding retained for path compatibility. It appends a short
+content hash when sanitization changed the input or when the safe form is too
+long; ordinary short names remain unchanged. Use V2 for new untrusted-ID mappings.
 
 ```ts
 safePathSegmentHashed("plugin-v1");                  // "plugin-v1"  (unchanged short input)
@@ -104,31 +145,35 @@ safePathSegmentHashed(".");                          // "skill-cdb4ee2aea"
 
 The sanitization is more aggressive than `safeDirName`: any character not in `[A-Za-z0-9._-]` becomes `-`, runs of `-` collapse, leading and trailing `-` are stripped, the empty/`.`/`..` fallback is `"skill"`. Long results are truncated to 50 chars before the hash is appended.
 
-The suffix is the first 10 hex characters of `sha256(trimmedInput)`. It makes
-collisions between distinct trimmed inputs unlikely, but it is a 40-bit
-identifier rather than a mathematical uniqueness guarantee. Inputs that differ
-only by surrounding whitespace intentionally map to the same output.
+The suffix is the first 10 hex characters of `sha256(trimmedInput)`. This is a
+40-bit identifier, and the hash is not applied to every ID: short generated
+outputs overlap with accepted literal inputs. Case variants can also share a
+directory on case-insensitive filesystems. Distinct IDs can therefore alias
+without a hash collision. Do not use this legacy encoder as an identity or
+authorization boundary for untrusted IDs. Inputs that differ only by surrounding
+whitespace intentionally map to the same output. Its output and the default
+encoder selected by `resolveSafeInstallDir` remain unchanged for compatibility.
 
 ## Common patterns
 
 ### Install a plugin
 
 ```ts
-import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashed } from "@openclaw/fs-safe/advanced";
+import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashedV2 } from "@openclaw/fs-safe/advanced";
 import { extractArchive } from "@openclaw/fs-safe/archive";
 import fs from "node:fs/promises";
 
 const r = resolveSafeInstallDir({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   id: untrustedName,
   invalidNameMessage: "invalid plugin name",
-  nameEncoder: safePathSegmentHashed,
+  nameEncoder: safePathSegmentHashedV2,
 });
 if (!r.ok) return reply(400, r.error);
 
 await fs.mkdir(r.path, { recursive: true, mode: 0o755 });
 await assertCanonicalPathWithinBase({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   candidatePath: r.path,
   boundaryLabel: "plugin install dir",
 });
@@ -148,6 +193,7 @@ const snap = resolveSafeInstallDir({
   baseDir: "/srv/snapshots",
   id: `${runId}-${version}`,
   invalidNameMessage: "invalid snapshot id",
+  nameEncoder: safePathSegmentHashedV2,
 });
 if (!snap.ok) throw new Error(snap.error);
 await fs.mkdir(snap.path, { recursive: true });

package/docs/install.md

@@ -54,7 +54,10 @@ also rejects canonicalization when the addon or its canonicalizer is unavailable
 Node and Windows use their existing runtime canonicalizers. On Windows, Bun's
 recursive directory creation receives an absolute spelling that preserves raw
 path components, working around its rejection of existing relative `.` and `..`
-directories. Public paths and caller-supplied filesystem adapters remain unchanged.
+directories. Windows native descriptor-relative operations require Bun to expose
+the paired libuv descriptor bridge from its host executable; a missing or partial
+bridge fails explicitly with `ENOTSUP`. Public paths and caller-supplied filesystem
+adapters remain unchanged.
 
 The upstream fix is tracked in [Bun #42374](https://github.com/oven-sh/bun/pull/42374).
 The adapter can be removed when the supported Bun baseline includes that fix.

package/docs/native-helper.md

@@ -70,10 +70,12 @@ normalization, and the decision to fall back.
 
 - Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
 - macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table.
 
 Native primitives back create-only and replacing pinned writes, async sidecar creation,
-guarded publication, archive acceleration, and direct Windows ACL operations.
+guarded publication, archive acceleration, and direct Windows ACL operations. Windows
+secure-file reads require descriptor-bound owner/DACL facts from the current helper;
+they do not use the standalone pathname inspector's command fallback.
 Equivalent JavaScript paths remain available for documented fallback-capable
 features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
 for the exact difference.

package/docs/native.md

@@ -55,7 +55,12 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   `FILE_OPEN_REPARSE_POINT`, then explicitly rejects reparse points. Rename and
   hardlink operations stay rooted in already-open handles. Owner/DACL reads
   use `GetSecurityInfo`; private directories receive their protected DACL in
-  the `CreateDirectoryW` call itself.
+  an exclusive, handle-relative `NtCreateFile` call. Their created handles remain
+  open through ACL and pathname-association checks and own any failure cleanup.
+  N-API descriptors cross into and out of
+  this layer only through the host executable's paired libuv descriptor bridge;
+  missing or partial exports fail with `ENOTSUP` instead of trying a raw HANDLE
+  or add-on CRT descriptor namespace.
 
 ## Archives
 
@@ -125,6 +130,13 @@ All routes preserve `wx` semantics and the same source/target identity and
 SHA-256 fencing. Native hashing and Linux whole-file copying run on N-API async
 workers rather than the JavaScript event loop.
 
+Linux range copying confirms every zero-byte result with a positioned source
+read at the current transfer offset, including after earlier calls copied data.
+If readable bytes remain, automatic Root copying resumes its byte loop from
+that offset; exclusive publication removes its partial target before retrying
+the guarded byte-copy fallback. EOF checks preserve descriptor cursors and do
+not bypass the byte limit.
+
 ## Mode semantics
 
 | Mode | Native loading | Fallback |
@@ -182,7 +194,7 @@ remain TypeScript-owned. What changes is the syscall strength or availability:
 | Zstd/bzip2 TAR | Supported. | Unsupported; typed `helper-unavailable`. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |
 | `rename-noreplace` | Atomic platform no-replace rename. | Unsupported; no emulation by check-then-rename. |
-| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. | Structured .NET owner/DACL inspection for coarse permission checks; the public raw ACE facts API remains native-only. |
+| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. Secure-file reads query the borrowed open descriptor and compare its 32-bit volume serial and 64-bit file-index projection with Node's bigint receipt. | Structured .NET owner/DACL inspection remains available to standalone pathname reporting. Secure-file reads fail closed without the descriptor capability. |
 | Windows private directory | Creation-time protected DACL. | Unsupported; no weaker pathname-only substitute. |
 
 Use `off` in CI to keep the fallback contract exercised. Use `require` when a

package/docs/path.md

@@ -36,7 +36,7 @@ isPathInside("/srv/uploads", "/srv/uploads-other/x");        // false
 isPathInside("/srv/uploads", "/srv/uploads");                // true (root itself counts)
 ```
 
-The check is platform-aware: on Windows, paths are normalized for case and separator before comparison.
+The check is platform-aware: on Windows, paths are normalized for case and separator before comparison. This is deliberately a string-only, lexical answer; case folding does not prove that two differently cased prefixes name the same directory on a case-sensitive Windows directory. Root operations perform their own filesystem-identity admission when containment depends on case folding.
 
 ### `isPathInsideWithRealpath(rootDir, target, opts?)`
 

package/docs/permissions.md

@@ -42,7 +42,7 @@ POSIX remediation strings shell-quote paths with whitespace or metacharacters
 and protect option-like paths with `--`, so they can be presented as commands
 without letting the inspected pathname add shell syntax.
 
-`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. Secure reads and callers that protect credential-bearing execution require `ownerTrusted === true`.
+`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` does not use those pathname fallbacks on Windows: it requires descriptor-bound native owner/DACL facts for the exact handle it reads.
 
 ## Advanced Windows ACL helpers
 
@@ -178,6 +178,31 @@ await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
 On Windows with native support, this creates the directory and applies a
 protected owner + LocalSystem + Administrators full-control DACL directly with
 an atomic security descriptor; no PowerShell or `icacls` process is launched.
+The native operation retains the parent and exact created-directory handles
+through ACL and final pathname validation. If validation fails, it attempts only
+nonrecursive deletion through the created handle, preserving any pathname
+replacement. If cleanup also fails, the error retains the original failure and
+includes the cleanup failure.
+
+Directory association checks compare the complete 64-bit volume serial and
+128-bit `FILE_ID_INFO` identity, including on ReFS. If that identity class is
+unavailable, the operation fails closed without a narrower file-index fallback.
+Validation confirms that the created directory is local, its DACL is protected
+from inheritance, and its final public pathname opens the same local directory.
+
+This is a point-in-time pathname association check. The function closes its
+handles before returning; callers must keep the pathname's ancestry trusted
+during subsequent use, including opening SQLite databases in the example above.
+The immediate parent and final directory must not be reparse points. Earlier
+ancestor reparse points can be followed; this API does not reject every reparse
+point in the full ancestry.
+
+Path components ending in a space or period are rejected before filesystem
+operations to avoid differing Win32 and native pathname interpretations. This
+also rejects explicit `.` and `..` components, including spellings such as
+`.\private` and `parent\..\private`, as a compatibility restriction. Simple
+relative names without these components remain supported.
+
 This API is Windows-only and native-only; it fails closed with
 `FsSafeError("helper-unavailable")` on other platforms, when native mode is off,
 or when the binding is unavailable. POSIX callers should create private

package/docs/public-api.md

@@ -26,6 +26,11 @@ deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
 
 ## `path` and `advanced`
 
+`safePathSegmentHashedV2` encodes every trimmed install ID with domain-separated
+SHA-256 into a fixed lowercase segment. The legacy `safePathSegmentHashed` keeps
+its existing output but can alias distinct IDs. See [install paths](install-path.md)
+for the exact encoding and migration contract.
+
 The lexical path surface additionally exports `isNodeError`,
 `isPathRelativeEscape`, `normalizeWindowsPathForComparison`,
 `resolveSafeRelativePath`, `splitSafeRelativePath`, and

package/docs/root.md

@@ -100,7 +100,9 @@ The read methods also accept an absolute spelling that already resolves inside
 the root. `readAbsolute()` and `reader()` make that intent explicit and accept
 both the configured root spelling and its canonical real path when the Root was
 created through a directory symlink or Windows junction. An absolute path
-outside the root is still rejected.
+outside the root is still rejected. On Windows, alternate casing is accepted
+only when the differently cased Root prefix has the Root's exact directory
+identity; the operation then continues under the trusted Root spelling.
 
 ### Writes
 

package/docs/secure-file.md

@@ -27,9 +27,11 @@ The helper:
 - enforces `maxBytes` before and after reading
 - closes the handle on success, error, and timeout
 
-On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper uses the ACL inspection helpers from [`permissions`](permissions.md) and refuses the read if ACLs cannot be verified.
+On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper queries owner, DACL, and locality from the same open descriptor that supplies the bytes. The native query returns the 32-bit volume serial and 64-bit file-index projection used by Node, which must equal Node's bigint descriptor receipt before its ACL facts are trusted. This avoids JavaScript number rounding but does not represent the full 128-bit file identity available on ReFS. Only the current user, LocalSystem, and built-in Administrators are trusted owner classes.
 
-Descriptor, pathname, and realpath identity checks use lossless bigint stats internally. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
+Windows secure reads require the matching current optional native package. A missing or stale helper, fd-to-handle conversion failure, denied `READ_CONTROL`, remote handle, incomplete descriptor, or unsupported ACE form rejects with `permission-unverified` before content is read. A malformed or different handle identity rejects with `path-mismatch`. There is no pathname-command fallback for `readSecureFile()`; the standalone reporting APIs in [`permissions`](permissions.md) retain their documented fallbacks. `permissions.allowInsecure` remains the explicit escape hatch and bypasses the ACL query.
+
+Descriptor, pathname, and realpath identity checks use bigint stats internally to avoid JavaScript number rounding. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
 
 ## Options
 
@@ -62,6 +64,8 @@ type SecureFileReadOptions = {
 
 `permissions.allowInsecure` is a migration escape hatch. Prefer fixing permissions and using [`formatPermissionRemediation`](permissions.md) to show the user what to run. `trust.allowNetworkPath` is off by default because UNC paths are remote authority, not local filesystem input. `inject` is for tests and platform adapters; production callers usually leave it unset.
 
+On an actual Windows process with effective `platform: "win32"`, `inject.env` and `inject.exec` do not replace descriptor inspection. They remain available to simulated Windows checks on non-Windows hosts.
+
 `permissions.allowInsecure` bypasses only permission checks. Neither it nor `inject.platform` changes filesystem identity verification, which always uses the actual process platform. `trust.allowSymlink` permits an alias but still requires its target and realpath to match the opened descriptor.
 
 ## Errors
@@ -77,23 +81,20 @@ type SecureFileReadOptions = {
 | `hardlink` | The descriptor, pathname, or realpath has more than one link. |
 | `path-mismatch` | The path or realpath changed between open and verification, or filesystem identity could not be verified after bounded re-inspection. |
 | `outside-workspace` | `realPath` is outside `trust.trustedDirs`. |
-| `permission-unverified` | Required mode/ACL checks could not be completed. |
+| `permission-unverified` | Required mode/ACL checks could not be completed, including when descriptor-bound Windows inspection is unavailable. |
 | `insecure-permissions` | Mode bits or ACLs grant broader access than allowed. |
 | `not-owned` | POSIX owner uid is not the current process uid. |
 | `too-large` | File size or bytes read exceeded `maxBytes`. |
 | `timeout` | `timeoutMs` elapsed while reading. |
 
-Windows inspection failures remain operational `permission-unverified` errors
-and still refuse the read. Their message includes the underlying reason when
-available. `details` includes `ownerError` for owner-query failures and, when
-command diagnostics are available, `command`, `durationMs`, `timedOut`,
-`exitCode`, `signal`, and `stderr`. Reasons and stderr are control-character
-escaped and limited to 400 characters each (including a truncation marker).
-No stdout or target file contents are copied into these display diagnostics.
-The original inspection exception is retained as `cause`; built-in command
-errors also retain their original execFile exception in the cause chain.
-Treat causes as restricted local diagnostic data. No retries are performed,
-and verification order and rejection conditions are unchanged.
+Windows descriptor-inspection failures are operational `permission-unverified`
+errors and refuse the read. The original native exception is retained as
+`cause`; treat causes as restricted local diagnostic data. No pathname or ACL
+content is copied into the display message. Test adapters that simulate Windows
+on another operating system retain the standalone pathname inspector's
+structured command diagnostics (`ownerError`, `command`, `durationMs`,
+`timedOut`, `exitCode`, `signal`, and bounded escaped `stderr`). Actual Windows
+secure reads do not start those commands. No retries are performed.
 
 ## See also
 

package/docs/security-model.md

@@ -45,7 +45,7 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 ### Path traversal and absolute paths
 
-Every path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
+Every path is resolved against the canonicalized real path of the root, then checked at that boundary. On Windows, an exact-case structural Root prefix stays on the lexical fast path; a prefix accepted only by case folding must have the Root's exact directory identity and is rebased onto the trusted Root spelling before use. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
 
 ### Symlinks (read side)
 

package/docs/store.md

@@ -72,12 +72,33 @@ Loading serializes consumers for one ID through a sidecar lock, then creates `pr
 
 Queue and failed directory creation fsyncs every newly-created parent edge from the leaf toward the trusted root. Enqueue and migration writes fsync the temp file and parent; claim, acknowledgement, quarantine, delivered-marker cleanup, and retirement transitions fsync every affected directory and propagate real sync failures. A transition may already be visible when a post-mutation sync fails, so retry the same operation to complete its crash-recovery state. Acknowledgement retries resync the queue directory even when both `.processing` and `.delivered` marker names are already absent, before reporting completion or rejecting a newer pending generation; quarantine retries with only failed evidence resync that destination before repairing the vanished queue source.
 
-`writeJsonDurableQueueEntry()` and migrations share strict parent synchronization inside the atomic writer's retained descriptor and per-path serialization lifetime, followed by published-file identity verification. If sync fails after publication, the write rejects without rolling back the published JSON; retrying writes the entry again and must complete its own sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
+`writeJsonDurableQueueEntry()` and migrations share strict parent synchronization inside the atomic writer's retained descriptor and per-path serialization lifetime, followed by published-file identity verification. If sync fails after publication, the write rejects without rolling back the published JSON; retrying `writeJsonDurableQueueEntry()` writes the entry again and must complete its own sync. Loader retries resync an existing processing claim's parent under the transfer lock before calling `read`, even when a version-dependent callback would no longer request migration. Fresh claims and same-directory source retirement already complete that sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
 
 Batch loading skips invalid entry names, malformed, oversized, or unreadable entry content, and caller `read` callback failures. Initially unowned pending entries (hardlinks or unverifiable identities), symlinks, non-files, and absent pending entries are also skipped. Claim, transfer-lock, retirement, and migration write/publication/durability failures reject the batch with the original error, even if earlier entries succeeded. Migration in both loaders strictly syncs the parent directory after successful publication. Visible transitions and earlier processing claims remain for retry; a rejected batch does not acknowledge or roll them back.
 
 Failed destinations are create-only. Quarantine publishes the claimed file by hardlink, so the queue and failed directories must share a filesystem with hardlink support. If `failed/<id>.json` already exists, quarantine rejects while preserving both that earlier evidence and the current claimed entry instead of overwriting either file. The `read` callback continues to receive the logical `.json` path even though bytes are read and migrations are written through the claimed path.
 
+Migrations stay bound to the exact processing file opened for that load. The
+read descriptor remains pinned while the callback runs outside the transfer
+lock; after the callback returns, migration reacquires the lock and rechecks the
+claim before publication. If another consumer acknowledged, quarantined, or
+replaced that claim, the migration rejects with `FsSafeError("path-mismatch")`
+and leaves the newer generation or failed evidence intact. A stale migration
+rejects both single and batch loads; ordinary callback failures retain their
+existing single-load rejection and batch-skip behavior.
+
+On Windows, migration releases its read pin once at this publication boundary
+because an open target can block replacement. It rechecks the exact pathname
+identity after the asynchronous close while still holding the transfer lock.
+POSIX retains the read pin through publication. Other readers keep ownership
+of their handles; Windows sharing denials still reject and can be retried after
+those readers close.
+
+Generation arbitration requires consumers to use the transfer lock. As with
+[atomic writes](atomic.md#beforerename), identity checks and pathname replacement
+are separate operations; use a trusted writable parent or OS isolation against
+processes that ignore the lock and mutate queue paths concurrently.
+
 Queue entry reads verify lossless file identities before opening, on the opened
 descriptor, and at the current pathname before reading bytes. POSIX opens are
 nonblocking, so a raced FIFO is rejected rather than stalling a consumer. On Windows, an

package/docs/temp.md

@@ -269,6 +269,10 @@ 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`.
 
+Generated temp filenames suffix Windows reserved-device basenames on every
+platform. A completed sibling staging component that still resolves as a
+Windows device alias rejects with `invalid-path` before hooks or producers run.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -167,13 +167,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.11.0",
-    "@openclaw/fs-safe-darwin-x64": "0.11.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.11.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.11.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.11.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.11.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.11.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.12.0",
+    "@openclaw/fs-safe-darwin-x64": "0.12.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.12.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.12.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.12.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.12.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.12.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {