@openclaw/fs-safe 0.20.0 → 0.21.1

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## Unreleased
 
+## 0.21.1 - 2026-09-27
+
+### Fixes
+
+- **Linux without `openat2`:** native opens now follow in-root relative symlinks exactly as `RESOLVE_BENEATH` does, rejecting absolute links, `..` escapes, procfs and `nosymfollow` links, and chains longer than 40. Denial and symlink policies report the same errors as the `openat2` path. Links inside sticky world-writable directories are refused. ([#717](https://github.com/openclaw/fs-safe/pull/717))
+- **Deny policies on case-insensitive filesystems:** `denyMutations` now denies creating a not-yet-existing case or Unicode-normalization alias of a denied path (for example `case.txt` when `Case.txt` is denied on APFS, NTFS or casefold ext4). Where a filesystem's sensitivity cannot be proven, Unicode-equivalent names are denied conservatively. ([#720](https://github.com/openclaw/fs-safe/pull/720))
+- **Directory listings:** `list()`, `entries()` and `walk()` reject names that are not valid UTF-8 with `invalid-path` instead of decoding them lossily, which could collide with a real `U+FFFD` name and report another entry's metadata. ([#715](https://github.com/openclaw/fs-safe/pull/715))
+- **ZIP admission:** entries that differ only by case or Unicode normalization are rejected during preflight and member reads, matching extraction's collision policy. ([#716](https://github.com/openclaw/fs-safe/pull/716))
+- **Atomic restore:** when a metadata call fails with `EIO` after the destination was truncated, restore-original writes the original bytes back through the retained, identity-verified descriptor instead of leaving the file empty. ([#718](https://github.com/openclaw/fs-safe/pull/718))
+- **Lock and prune cleanup:** cleanup decisions compare exact bigint file identities. Legacy numeric receipts with IDs above 2^53 are refused instead of risking removal of the wrong file. ([#719](https://github.com/openclaw/fs-safe/pull/719))
+- **Watch overflow:** subscriptions no longer publish spurious whole-scope overflow invalidations for excluded or unselected paths or for slow reconcile passes. macOS streams use OS-level exclusion paths and anchor-scoped streams, and Windows uses a 1 MiB change buffer on local volumes. Genuine OS event drops still invalidate. ([#724](https://github.com/openclaw/fs-safe/pull/724))
+- **Mutation authority:** reject synchronous and asynchronous generator callback results before mutation, so lazy authority checks cannot be skipped. ([#711](https://github.com/openclaw/fs-safe/pull/711))
+- **Synchronous atomic writes:** reject deferred `beforeRename` hooks before publication and clean up the owned stage. ([#728](https://github.com/openclaw/fs-safe/pull/728))
+- **Copy publication callbacks:** reject deferred generator observers in `Root.copyIn()` while preserving the completed destination and source bytes. ([#726](https://github.com/openclaw/fs-safe/pull/726))
+- **Native move diagnostics:** no-clobber `Root.move()` keeps the original native loader error as its cause, including missing libraries or incompatible glibc versions. ([#709](https://github.com/openclaw/fs-safe/pull/709))
+
+### Features
+
+- **Watch polling interval:** `pollIntervalMs` sets the scan interval whenever polling is the selected transport, including `mode: "auto"` falling back to polling, without changing the events reconcile interval. ([#723](https://github.com/openclaw/fs-safe/pull/723))
+
+### Performance
+
+- **Linux directory cloning:** reuse the admitted filesystem type when creating clone sources and cloning trees, avoiding a duplicate filesystem probe and allocation per operation. ([#732](https://github.com/openclaw/fs-safe/pull/732))
+
+## 0.21.0 - 2026-09-26
+
+### Highlights
+
+- **Guarded filesystem observation:** `@openclaw/fs-safe/watch` observes literal entry and tree scopes beneath an admitted Root and delivers bounded advisory invalidations; guarded scans stay authoritative. One shared Rust event thread per process uses inotify, FSEvents and ReadDirectoryChangesW on Linux, macOS and Windows, sleeps while idle, and falls back to portable polling under `mode: "auto"`. Subscriptions become ready after one baseline scan, stay available under sustained writes, fence stale generations on `setScopes()`, join native work on `close()`, and support `persistent: false` so one-shot Node commands can exit. Thanks @vincentkoc. ([#690](https://github.com/openclaw/fs-safe/pull/690), [#695](https://github.com/openclaw/fs-safe/pull/695), [#697](https://github.com/openclaw/fs-safe/pull/697), [#703](https://github.com/openclaw/fs-safe/pull/703), [#707](https://github.com/openclaw/fs-safe/pull/707))
+- **Linux user namespaces:** private temp workspaces now work beneath unmapped ancestors, including systemd user services with `PrivateUsers=true`, while UID/GID mappings and ancestor permissions are still rechecked. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+
+### Features
+
+- **Revocable atomic writes:** atomic replacement can recheck caller authority before new effects and report retained destination identities for partial writes and publication, without treating receipts as permission to roll back. ([#694](https://github.com/openclaw/fs-safe/pull/694))
+- **Root walking:** `symlinkPolicy: "include"` reports links without following their targets, preserving sorted traversal, entry budgets, and the existing skip/follow result types. Directory-to-symlink substitutions fail before descent. ([#692](https://github.com/openclaw/fs-safe/pull/692))
+- **Windows file retirement:** the advanced surface can retire existing NTFS files through a retained handle, with exact producer identity, current authority, and separate disposition and settlement facts. There is no persistence guarantee. ([#706](https://github.com/openclaw/fs-safe/pull/706))
+
+### Performance
+
+- **Temporary filename sanitization:** skip duplicate normalization after reserved-device suffixing while preserving filename admission and fallback rules. ([#689](https://github.com/openclaw/fs-safe/pull/689))
+
+### Compatibility
+
+- Supplied temp workspace roots must be owned by the effective user and must not be group- or world-writable; use a private per-user root instead of shared `/tmp`. A one-time warning reports host ownership that cannot be verified. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+- On Windows, an events-mode watch holds one handle on each watched Root, so the Root's own ancestor directories cannot be renamed while it is open; renaming inside the Root is unaffected. Use `mode: "poll"` where that matters. ([#697](https://github.com/openclaw/fs-safe/pull/697))
+- `watch()` requires an explicit `mode` (`"auto"`, `"events"` or `"poll"`); `"events"` fails readiness with `helper-unavailable` when no native backend is available, and Bun currently selects polling under `"auto"`. ([#690](https://github.com/openclaw/fs-safe/pull/690))
+
 ## 0.20.0 - 2026-09-25
 
 ### Highlights

package/README.md

@@ -279,6 +279,7 @@ contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are
 | `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
 | `@openclaw/fs-safe/file-lock` | async/sync sidecar locks, root-bounded sidecars, ownership verification, and stale policy |
 | `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection, raw owner/ACE facts, private-directory creation, and remediation helpers |
+| [`@openclaw/fs-safe/watch`](docs/watch.md) | Guarded observation with native event hints, bounded scans, and joined close |
 | `@openclaw/fs-safe/walk` | budget-bounded directory walking with symlink policy, filters, and truncation accounting; not root-bounded |
 | `@openclaw/fs-safe/copy` | directory copying with `clone: "auto"`, `"always"`, or `"never"`; native APFS, Btrfs, ReFS, XFS, and ZFS cloning, portable byte copying, and clone metadata; see [directory copying](docs/copy.md) |
 | `@openclaw/fs-safe/archive` | policy-driven ZIP/TAR extraction, clamp/filter policy, metadata/path-depth limits, gzip/zstd/bzip2 support, and bounded entry reads |
@@ -368,6 +369,12 @@ await replaceFileAtomic({
 
 `replaceFileAtomicSync()` covers the synchronous case with the same options shape. Both accept an injectable `fileSystem` for tests. Async adapters use `chmod()` on the `FileHandle` returned by their required `open()` operation; custom sync adapters using `mode` or `preserveExistingMode` provide the optional descriptor-bound `fchmodSync` operation.
 
+Both variants accept `assertBeforeMutation` for revocable caller authority and
+`onDestinationState` for observed removal, partial-write, and publication facts.
+The observer receives exact bigint identities from retained descriptors, including
+when later completion fails. These facts do not authorize rollback; the caller
+still owns current authority and content checks. See [atomic write authority](docs/atomic.md#atomic-write-authority-and-destination-state).
+
 ## External outputs
 
 Use `writeExternalFileWithinRoot()` when a browser download, renderer, media
@@ -559,7 +566,8 @@ Check `scan.truncated` before treating the result as complete, and `scan.failedD
 `walkDirectory()` accepts asynchronous `include` and `descend` callbacks through `AsyncWalkDirectoryOptions`, so a marker lookup can prune a directory before its children are read. Decisions remain serial and retain the options object as their `this` receiver; `walkDirectorySync()` and its options remain synchronous. See [Directory walking](docs/walk.md) for callback timing, JavaScript result compatibility, and error handling.
 
 For caller-controlled paths, `Root.walk()` is the root-bounded async iterator.
-It supports entry/depth budgets, in-root symlink following, cancellation, and a
+It supports entry/depth budgets, including links without following their targets,
+in-root symlink following, cancellation, and a
 truncation marker (or typed error) when a budget is reached. Its `entryFilter`
 accepts `"include"`, `"skip"`, or `"skip-subtree"`, directly or through a Promise.
 After an awaited decision resolves, the walk rechecks cancellation and the

package/dist/advanced.d.ts

@@ -37,3 +37,5 @@ export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile,
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
 export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions-windows.js";
 export type { PermissionCommandFailure } from "./permission-exec.js";
+export { retainFileInDirectory } from "./retained-file.js";
+export type { RetainedFile, RetainedFileAdmission, RetainedFileExpected, RetainedFileIssue, RetainedFileReceipt, RetainedFileResult, RetainFileInDirectoryOptions, } from "./retained-file-types.js";

package/dist/advanced.js

@@ -37,3 +37,4 @@ export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularF
 export { buildRandomTempFilePath, sanitizeTempFileName, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, } from "./sibling-temp.js";
 export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
+export { retainFileInDirectory } from "./retained-file.js";

package/dist/archive-zip-directory.js

@@ -1,5 +1,6 @@
 import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
 import { admitZipNames, zipExtraFields, zipFormat, zipUInt64 } from "./archive-zip-names.js";
+import { createArchiveOutputPathTracker } from "./archive-entry.js";
 function entryKind(attributes, directory) {
     const type = (attributes >>> 16) & 0o170000;
     // High-word symlinks remain links regardless of the creator or directory bits.
@@ -186,6 +187,7 @@ export function* scanZipDirectory(size, limits, onEntry) {
     const directory = yield* layout(size);
     assertArchiveEntryCountWithinLimit(directory.count, limits);
     const seen = new Set();
+    const trackKnownPath = createArchiveOutputPathTracker();
     const spans = [];
     let at = directory.start;
     let count = 0;
@@ -226,6 +228,8 @@ export function* scanZipDirectory(size, limits, onEntry) {
         const localNames = yield* read(localAt + 30, localNameLength + localExtraLength, directory.start);
         const localExtra = zipExtraFields(localNames.subarray(localNameLength));
         const admittedName = admitZipNames({ central: centralName, local: localNames.subarray(0, localNameLength), flags, centralExtra, localExtra, seen });
+        if (admittedName.path !== undefined)
+            trackKnownPath(admittedName.path, admittedName.path);
         const localValues = wideValues(local, localExtra, false);
         const crc = central.readUInt32LE(16);
         if (!(flags & 8) && (local.readUInt32LE(14) !== crc || localValues.compressed !== values.compressed || localValues.uncompressed !== values.uncompressed)) {

package/dist/archive-zip-loader.js

@@ -1,5 +1,5 @@
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
+import { createArchiveOutputPathTracker, validateArchiveEntryPath } from "./archive-entry.js";
 import { createAdmittedZipEntry } from "./archive-zip-entry.js";
 import { zipPathKey } from "./archive-zip-names.js";
 export function assertZipEntryBinding(archive, record, path) {
@@ -27,7 +27,9 @@ function matchesData(value, physical) {
 /** Internal: the caller has admitted these unchanged bytes and their metadata. */
 export async function loadAdmittedZipArchive(buffer, admitted) {
     const physicalByPath = new Map();
+    const trackOutputPath = createArchiveOutputPathTracker();
     for (const entry of admitted) {
+        trackOutputPath(entry.portableKey, entry.portableKey);
         if (physicalByPath.has(entry.portableKey))
             collision();
         physicalByPath.set(entry.portableKey, entry);

package/dist/archive-zip-manifest.js

@@ -1,10 +1,11 @@
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
-import { stripArchivePath } from "./archive-entry.js";
+import { createArchiveOutputPathTracker, stripArchivePath } from "./archive-entry.js";
 /** Associate all native entries with physical admission before exposing any. */
 export function validateNativeZipManifest(manifest, admitted) {
     if (manifest.length !== admitted.length) {
         throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
     }
+    const trackOutputPath = createArchiveOutputPathTracker();
     for (const [ordinal, entry] of manifest.entries()) {
         const physical = admitted[ordinal];
         const physicalPath = physical?.path;
@@ -18,5 +19,6 @@ export function validateNativeZipManifest(manifest, admitted) {
             (physical.creatorSystem === 3 && entry.mode !== physical.externalAttributes >>> 16)) {
             throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
         }
+        trackOutputPath(entry.path, entry.path);
     }
 }

package/dist/atomic.d.ts

@@ -1,4 +1,4 @@
-export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
+export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicDestinationState, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
 export type { RenameIdentityPolicy } from "./pinned-write-types.js";
 export type { ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, } from "./replace-file-copy-fallback.js";
 export { writeTextAtomic, type WriteTextAtomicOptions } from "./text-atomic.js";

package/dist/copy-publication.d.ts

@@ -1,9 +1,7 @@
 import type { BigIntStats } from "node:fs";
 import type { PinnedWriteParams, PublishedWriteIdentity } from "./pinned-write-types.js";
-export type RootCopyPublicationReceipt = Readonly<{
+export type RootCopyPublicationReceipt = Readonly<PublishedWriteIdentity & {
     path: string;
-    dev: bigint;
-    ino: bigint;
 }>;
 export declare function createCopyPublicationObserver(path: string, notify?: (receipt: RootCopyPublicationReceipt) => void): {
     onPublished(identity: PublishedWriteIdentity): void;

package/dist/copy-publication.js

@@ -1,16 +1,12 @@
 import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 export function createCopyPublicationObserver(path, notify) {
     let rejected;
     return {
         onPublished(identity) {
             const receipt = Object.freeze({ path, dev: identity.dev, ino: identity.ino });
             try {
-                const result = notify?.(receipt);
-                if (result !== null && (typeof result === "object" || typeof result === "function") &&
-                    "then" in result && typeof result.then === "function") {
-                    void Promise.resolve(result).catch(() => undefined);
-                    throw new TypeError("onDestinationPublished must be synchronous");
-                }
+                assertSynchronousCallbackResult(notify?.(receipt), "onDestinationPublished");
             }
             catch (error) {
                 rejected = { error };

package/dist/deny-mutation-match.d.ts

@@ -0,0 +1,2 @@
+/** Cache observations only within one synchronous policy check, never across mutations or callbacks. */
+export declare function createMutationDenyMatcher(): (target: string, denied: string, prefix: boolean, protectAncestors?: boolean) => boolean;

package/dist/deny-mutation-match.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { isPathInside } from "./path.js";
+import { probePathCaseInsensitiveSync } from "./path-case.js";
+import { observeMutationPath } from "./pinned-mutation-observation.js";
+function foldedName(name) {
+    // Decompose before folding so combining marks precede an expanded Greek subscript.
+    // Default folding preserves dotless i even though its uppercase mapping is I.
+    return name.normalize("NFD").replace(/[^\u0131]+/gu, part => part.toLowerCase().toUpperCase().toLowerCase()).normalize("NFC");
+}
+function asciiCasePair(left, right) {
+    return /^[\x00-\x7f]*$/.test(left) && /^[\x00-\x7f]*$/.test(right) &&
+        left.toLowerCase() === right.toLowerCase();
+}
+/** Cache observations only within one synchronous policy check, never across mutations or callbacks. */
+export function createMutationDenyMatcher() {
+    const observations = new Map();
+    const caseObservations = new Map();
+    const observe = (pathname) => {
+        if (!observations.has(pathname))
+            observations.set(pathname, observeMutationPath(pathname));
+        return observations.get(pathname);
+    };
+    const prospectiveInside = (parent, child) => {
+        const root = path.parse(parent).root;
+        if (root !== path.parse(child).root)
+            return false;
+        const left = parent.slice(root.length).split(path.sep);
+        const right = child.slice(root.length).split(path.sep).slice(0, left.length);
+        if (left.length !== right.length || !left.every((name, i) => foldedName(name) === foldedName(right[i]))) {
+            return false;
+        }
+        // Byte-identical relations were already handled without any observations.
+        if (left.every((name, i) => name === right[i]))
+            return false;
+        const alignedChild = path.join(root, ...right);
+        const a = observe(parent);
+        const b = observe(alignedChild);
+        if (!a || !b)
+            return true;
+        // Distinct existing ancestors are real objects, not prospective aliases.
+        if (a.canonicalAncestor !== b.canonicalAncestor ||
+            a.missingSegments.length === 0 || a.missingSegments.length !== b.missingSegments.length)
+            return false;
+        const missingLeft = a.missingSegments;
+        const missingRight = b.missingSegments;
+        if (!missingLeft.every((name, i) => foldedName(name) === foldedName(missingRight[i])))
+            return false;
+        const difference = missingLeft.findIndex((name, i) => name !== missingRight[i]);
+        if (difference === -1)
+            return true;
+        // A read-only ASCII observation can disprove aliasing at this existing parent.
+        // It cannot prove Unicode sensitivity or the behavior of a future directory.
+        if (difference === 0 && asciiCasePair(missingLeft[0], missingRight[0])) {
+            if (!caseObservations.has(a.canonicalAncestor)) {
+                caseObservations.set(a.canonicalAncestor, probePathCaseInsensitiveSync(path.join(a.canonicalAncestor, missingLeft[0]), { allowTemporaryProbe: false }));
+            }
+            if (caseObservations.get(a.canonicalAncestor) === false)
+                return false;
+        }
+        // Suffix probing writes directories. Policy admission has no authority for
+        // those side effects, so unproven case/normalization equivalence fails closed.
+        return true;
+    };
+    return (target, denied, prefix, protectAncestors = false) => {
+        if ((isPathInside(denied, target) && (prefix || isPathInside(target, denied))) ||
+            (protectAncestors && isPathInside(target, denied)))
+            return true;
+        return ((prefix || target.split(path.sep).length === denied.split(path.sep).length) &&
+            prospectiveInside(denied, target)) || (protectAncestors && prospectiveInside(target, denied));
+    };
+}

package/dist/deny-mutations.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
+import { createMutationDenyMatcher } from "./deny-mutation-match.js";
 import { FsSafeError } from "./errors.js";
-import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+import { assertNoNulPathInput, isNotFoundPathError } from "./path.js";
 import { realpathSync } from "./realpath.js";
 import { resolveExistingAncestor } from "./root-path-existing.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
@@ -65,6 +66,7 @@ export function assertMutationNotDenied(filePath, policy, options = {}, mode = "
     const strict = mode === "sync-root-lock";
     const comparablePaths = strict ? strictMutationComparablePaths : resolveMutationComparablePaths;
     const targets = comparablePaths(filePath);
+    const matches = createMutationDenyMatcher();
     // Validate one complete phase at a time. A paths denial must not read or
     // canonicalize prefixes, and invalid later paths retain validation precedence.
     for (const kind of ["paths", "prefixes"]) {
@@ -72,8 +74,7 @@ export function assertMutationNotDenied(filePath, policy, options = {}, mode = "
             const deniedPaths = comparablePaths(entry);
             for (const target of targets) {
                 for (const denied of deniedPaths) {
-                    if ((isPathInside(denied, target) && (kind === "prefixes" || isPathInside(target, denied))) ||
-                        (options.protectAncestors === true && isPathInside(target, denied))) {
+                    if (matches(target, denied, kind === "prefixes", options.protectAncestors)) {
                         throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
                     }
                 }

package/dist/file-identity.js

@@ -22,9 +22,17 @@ export function sameFileIdentity(left, right, platform = process.platform) {
     return (!isStatValueProvablyDifferent(left.dev, right.dev, platform) &&
         !isStatValueProvablyDifferent(left.ino, right.ino, platform));
 }
+function sameCleanupStatValue(left, right) {
+    // Converting an unsafe number to bigint cannot recover an already rounded ID.
+    if (typeof left === "number" && !Number.isSafeInteger(left))
+        return false;
+    if (typeof right === "number" && !Number.isSafeInteger(right))
+        return false;
+    return sameStatValue(left, right);
+}
 export function sameFileIdentityForCleanup(left, right, platform = process.platform) {
     if (platform !== "win32") {
-        return sameStatValue(left.dev, right.dev) && sameStatValue(left.ino, right.ino);
+        return sameCleanupStatValue(left.dev, right.dev) && sameCleanupStatValue(left.ino, right.ino);
     }
     // A zero Windows device or inode is unknown, not proof that a pathname still
     // names the object we created. Cleanup must fail closed rather than delete a
@@ -44,5 +52,5 @@ export function sameFileIdentityForCleanup(left, right, platform = process.platf
     const rightIno = right.ino;
     if (isZero(rightIno))
         return false;
-    return sameStatValue(leftDev, rightDev) && sameStatValue(leftIno, rightIno);
+    return sameCleanupStatValue(leftDev, rightDev) && sameCleanupStatValue(leftIno, rightIno);
 }

package/dist/file-lock-sync-admission.js

@@ -30,7 +30,11 @@ export function defaultSyncShouldReclaim(snapshot, staleMs, nowMs) {
     const createdAtMs = sidecarLockPayloadCreatedAtMs(snapshot.payload);
     if (createdAtMs !== null)
         return nowMs - createdAtMs > staleMs;
-    return !snapshot.stat || nowMs - snapshot.stat.mtimeMs > staleMs;
+    if (!snapshot.stat)
+        return true;
+    const mtimeMs = "mtimeNs" in snapshot.stat
+        ? Number(snapshot.stat.mtimeNs) / 1e6 : snapshot.stat.mtimeMs;
+    return nowMs - mtimeMs > staleMs;
 }
 export function syncReclaimGuardExists(reclaimGuardPath) {
     try {

package/dist/file-lock-sync-root-io.d.ts

@@ -1,4 +1,4 @@
-import { type BigIntStats, type Stats } from "node:fs";
+import { type BigIntStats } from "node:fs";
 import type { RootDefaults } from "./root-options.js";
 import { type FileLockSyncRootPath } from "./file-lock-sync-root.js";
 export type ExactIdentity = Readonly<{
@@ -19,7 +19,7 @@ export type FileLockSyncRootDiskSnapshot = {
     ownershipToken?: never;
     payload: unknown;
     raw: string;
-    stat: Stats;
+    stat: BigIntStats;
 };
 export type FileLockSyncRootSnapshot = Readonly<{
     receipt: FileLockSyncRootFileReceipt;

package/dist/file-lock-sync-root-io.js

@@ -143,7 +143,7 @@ export function readFileLockSyncRootSnapshot(pathAuthority, options = {}) {
             throw error;
         }
         assertRegularFile(after, pathAuthority.authority.hardlinks);
-        const stat = fs.fstatSync(fd);
+        const stat = fs.fstatSync(fd, { bigint: true });
         if (expectedReceipt) {
             assertRetainedParentCurrent(pathAuthority, parent);
         }

package/dist/file-lock-sync.js

@@ -240,7 +240,7 @@ export function acquireFileLockSync(targetPath, options) {
                 createdSnapshot = {
                     raw,
                     payload,
-                    stat: fs.fstatSync(fd),
+                    stat: fs.fstatSync(fd, { bigint: true }),
                     ownershipToken,
                 };
                 createdHeld = {
@@ -280,7 +280,7 @@ export function acquireFileLockSync(targetPath, options) {
                     const failed = createdSnapshot ?? { payload: null };
                     if (!failed.stat) {
                         try {
-                            failed.stat = fs.fstatSync(fd);
+                            failed.stat = fs.fstatSync(fd, { bigint: true });
                         }
                         catch {
                             // Missing identity leaves the sidecar in place, but must not skip close.

package/dist/file-store-prune.js

@@ -23,10 +23,10 @@ export async function pruneExpiredStoreEntries(params) {
     const rootGuard = {
         dir: rootReal,
         realPath: rootReal,
-        stat: fsSync.lstatSync(rootReal),
+        stat: fsSync.lstatSync(rootReal, { bigint: true }),
     };
     async function assertRootGuard() {
-        const stat = fsSync.lstatSync(rootGuard.dir);
+        const stat = fsSync.lstatSync(rootGuard.dir, { bigint: true });
         if (stat.isSymbolicLink() ||
             !stat.isDirectory() ||
             stat.dev !== rootGuard.stat.dev ||
@@ -36,7 +36,7 @@ export async function pruneExpiredStoreEntries(params) {
         }
     }
     async function readStableDirectory(dir) {
-        const before = observeOrNull(() => fsSync.lstatSync(dir));
+        const before = observeOrNull(() => fsSync.lstatSync(dir, { bigint: true }));
         if (!before || before.isSymbolicLink() || !before.isDirectory()) {
             return null;
         }
@@ -48,7 +48,7 @@ export async function pruneExpiredStoreEntries(params) {
         if (!entries) {
             return null;
         }
-        const after = observeOrNull(() => fsSync.lstatSync(dir));
+        const after = observeOrNull(() => fsSync.lstatSync(dir, { bigint: true }));
         if (!after || before.dev !== after.dev || before.ino !== after.ino) {
             return null;
         }

package/dist/mutation-authority.js

@@ -1,3 +1,4 @@
+import { types } from "node:util";
 import { FsSafeError } from "./errors.js";
 export class MutationAuthorityError extends FsSafeError {
     rejection;
@@ -14,6 +15,10 @@ export function assertSynchronousCallbackResult(returned, name) {
         void Promise.resolve(returned).catch(() => undefined);
         throw new TypeError(`${name} must be synchronous`);
     }
+    // A generator returns its iterator before running the callback body.
+    if (types.isGeneratorObject(returned)) {
+        throw new TypeError(`${name} must be synchronous`);
+    }
 }
 export function composeMutationAssertions(defaultAssertion, callAssertion) {
     if (!defaultAssertion && !callAssertion)

package/dist/native-binding.d.ts

@@ -1,3 +1,11 @@
+import type { RetainedFileResult } from "./retained-file-types.js";
+export interface NativeRetainedFile {
+    readonly admission: RetainedFileResult | {
+        status: "retained";
+        identity: string;
+    };
+    settle(remove: boolean): RetainedFileResult;
+}
 import type { TarMeterLimits } from "./archive-limits.js";
 import type { ArchiveMemberKind } from "./archive-plan.js";
 import type { CopyCloneMode } from "./copy-policy.js";
@@ -95,6 +103,31 @@ type NativeTwoPathArgs = [
     targetRelPath: string
 ];
 export interface NativeBinding {
+    /** Windows-only, private handle custody; no borrowed/runtime descriptors. */
+    retainWindowsFile?(directory: string, basename: string, parentDev: bigint, parentIno: bigint, dev: bigint, ino: bigint, size: bigint, mtimeNs: bigint, ctimeNs: bigint, sha256: string, maxBytes: number): NativeRetainedFile;
+    watchRegister?(root: string, limit: number, callback: (batch: import("./watch-native.js").NativeWatchWireBatch) => void, persistent: boolean): number;
+    watchConfigure?(id: number, anchors: string[], exclusions: string[]): void;
+    watchAdd?(id: number, directory: {
+        root: string;
+        relative: string;
+        rootDev: bigint;
+        rootIno: bigint;
+        dev: bigint;
+        ino: bigint;
+    }): void;
+    watchTestEvent?(id: number, path: string, flags: number): void;
+    watchUnregister?(id: number): void;
+    watchThreadCount?(): number;
+    watchMemoryStats?(): {
+        registrations: number;
+        pendingSets: number;
+        payloadsLive: number;
+        payloadsCreated: number;
+        payloadsDestroyed: number;
+        threadsafeFunctionsLive: number;
+        threadsafeFunctionsCreated: number;
+        threadsafeFunctionsDestroyed: number;
+    };
     /** Internal: consumes only a descriptor returned by this binding. */
     closeOwnedFd(fd: number): void;
     /** Internal Darwin-only synchronous inspection; the caller retains its fd. */

package/dist/native-pinned-write.js

@@ -182,8 +182,14 @@ async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryF
             completeParentFd = binding.openBeneath(rootFd, params.relativeParentPath, directoryFlags).fd;
         }
         catch (error) {
-            if (error?.code !== "ENOENT" || !params.mkdir)
-                throw error;
+            if (error?.code !== "ENOENT" || !params.mkdir) {
+                // A mechanism rejection must not hide canonical denial/symlink policy.
+                // This admission only classifies failure; it cannot authorize a retry.
+                await authorizePinnedMutation(params, {
+                    targetPath: initialTarget, mutationPath: initialTarget, phase: "parent",
+                });
+                throw normalizePolicyParentOpenError(error, params);
+            }
         }
         if (completeParentFd !== undefined) {
             const parentFd = completeParentFd;

package/dist/pinned-mutation-admission.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { assertMutationNotDenied } from "./deny-mutations.js";
+import { createMutationDenyMatcher } from "./deny-mutation-match.js";
 import { FsSafeError } from "./errors.js";
 import { isPathInside } from "./path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
@@ -100,8 +101,9 @@ function epochCurrent(epoch, directories) {
         getFsSafeNativeConfig().mode === epoch.mode;
 }
 function assertCachedNotDenied(target, epoch) {
-    if (epoch.paths.some((paths) => paths.some((denied) => isPathInside(denied, target) && isPathInside(target, denied))) ||
-        epoch.prefixes.some((paths) => paths.some((denied) => isPathInside(denied, target)))) {
+    const matches = createMutationDenyMatcher();
+    if (epoch.paths.some((paths) => paths.some((denied) => matches(target, denied, false))) ||
+        epoch.prefixes.some((paths) => paths.some((denied) => matches(target, denied, true)))) {
         throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
     }
 }

package/dist/replace-file-buffer.d.ts

@@ -0,0 +1,4 @@
+import type syncFs from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export declare function writeAtomicDestination(handle: FileHandle, data: Buffer, beforeWrite?: () => Promise<void>, assertBeforeMutation?: () => void, onWriting?: () => void): Promise<void>;
+export declare function writeAtomicDestinationSync(fsModule: Pick<typeof syncFs, "ftruncateSync" | "writeSync">, fd: number, data: Buffer, beforeWrite?: () => void, onWriting?: () => void): void;

package/dist/replace-file-buffer.js

@@ -0,0 +1,36 @@
+export async function writeAtomicDestination(handle, data, beforeWrite, assertBeforeMutation, onWriting) {
+    if (beforeWrite)
+        await beforeWrite();
+    assertBeforeMutation?.();
+    await handle.truncate(0);
+    onWriting?.();
+    let written = 0;
+    while (written < data.length) {
+        if (beforeWrite)
+            await beforeWrite();
+        assertBeforeMutation?.();
+        const result = await handle.write(data, written, data.length - written, written);
+        if (result.bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += result.bytesWritten;
+    }
+    if (beforeWrite)
+        await beforeWrite();
+    assertBeforeMutation?.();
+    await handle.truncate(data.length);
+}
+export function writeAtomicDestinationSync(fsModule, fd, data, beforeWrite, onWriting) {
+    beforeWrite?.();
+    fsModule.ftruncateSync(fd, 0);
+    onWriting?.();
+    let written = 0;
+    while (written < data.length) {
+        beforeWrite?.();
+        const bytesWritten = fsModule.writeSync(fd, data, written, data.length - written, written);
+        if (bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += bytesWritten;
+    }
+    beforeWrite?.();
+    fsModule.ftruncateSync(fd, data.length);
+}

package/dist/replace-file-copy-fallback.d.ts

@@ -1,4 +1,5 @@
 import syncFs, { type BigIntStats } from "node:fs";
+import { AtomicMutation } from "./replace-file-mutation.js";
 export type ReplaceFileDestinationHardlinkPolicy = "reject";
 export type ReplaceFileCopyFallbackRestorePolicy = "restore-original" | "none";
 export type ReplaceFileAtomicRestoreCleanup = "restored" | "restore-failed";
@@ -22,6 +23,7 @@ export declare function copyFallbackReplace(params: {
     maxRestoreBytes?: number;
     expectedSourceIdentity?: BigIntStats;
     sync: boolean;
+    mutation?: AtomicMutation;
 }): Promise<void>;
 export declare function copyFallbackReplaceSync(params: Omit<Parameters<typeof copyFallbackReplace>[0], "fsModule"> & {
     fsModule: SyncFallbackFs;