@openclaw/fs-safe 0.8.6 → 0.10.0

package/dist/sidecar-lock-reclaim.js

@@ -90,7 +90,13 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
                 await opened.handle.close().catch(() => undefined);
             }
         }
-        const before = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        let before;
+        try {
+            before = fsSync.lstatSync(lockPath);
+        }
+        catch (error) {
+            before = missingSnapshotPath(error);
+        }
         if (!before)
             return null;
         if (!before.isFile() || before.isSymbolicLink()) {
@@ -119,7 +125,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
             options.onOpenFailure?.(error);
             throw error;
         }
-        const opened = await handle.stat();
+        const opened = fsSync.fstatSync(handle.fd);
         if (!opened.isFile()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
@@ -129,7 +135,13 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
         if (!options.allowDescriptorIdentityDrift && !sameFileIdentity(before, opened))
             return null;
         const raw = (await readFileHandleBounded(handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
-        const after = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        let after;
+        try {
+            after = fsSync.lstatSync(lockPath);
+        }
+        catch (error) {
+            after = missingSnapshotPath(error);
+        }
         if (!after || !after.isFile() || !sameFileIdentity(before, after))
             return null;
         return { raw, stat: after };
@@ -241,7 +253,7 @@ export async function sidecarLockSnapshotStillPresent(lockPath, observed, option
 }
 export async function sidecarReclaimGuardExists(pathname) {
     try {
-        await fs.lstat(pathname);
+        fsSync.lstatSync(pathname);
         return true;
     }
     catch (err) {

package/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAqIjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAuFD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAU3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAkBL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAsIjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAuFD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAU3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAkBL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}

package/dist/sidecar-lock.js

@@ -85,7 +85,8 @@ function snapshotMatchesSync(lockPath, observed) {
     }
 }
 function releaseAllReclaimGuardsSync(state) {
-    for (const reclaimGuardPath of state.reclaimGuards) {
+    // Exit cleanup also visits managers created by older copies and never reopened here.
+    for (const reclaimGuardPath of state.reclaimGuards ?? []) {
         try {
             fsSync.rmdirSync(reclaimGuardPath);
             state.reclaimGuards.delete(reclaimGuardPath);

package/dist/temp-cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-cleanup.d.ts","sourceRoot":"","sources":["../src/temp-cleanup.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEvF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC;AAEvD,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG;IAChD,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/C,CAAC;AAkDF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B,GACA,oBAAoB,CA2BtB;AAED,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUzE"}
+{"version":3,"file":"temp-cleanup.d.ts","sourceRoot":"","sources":["../src/temp-cleanup.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEvF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC;AAEvD,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG;IAChD,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/C,CAAC;AAmDF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B,GACA,oBAAoB,CA2BtB;AAED,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUzE"}

package/dist/temp-cleanup.js

@@ -11,8 +11,9 @@ function pathStillMatchesReceipt(entry) {
         return (!entry.singleLinkFile || (current.isFile() && current.nlink === 1n)) &&
             sameFileIdentityForCleanup(current, entry.identity);
     }
-    catch (error) {
-        return !entry.singleLinkFile && error.code === "ENOENT";
+    catch {
+        // A missing pathname grants no authority over an entry created after this lookup.
+        return false;
     }
 }
 function removeRegisteredPathSync(entry) {

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAsCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
@@ -81,12 +82,16 @@ function isNodeErrorWithCode(err, code) {
 }
 async function cleanupTempDir(dir, identity, onCleanupError) {
     try {
-        const current = await fs.lstat(dir, { bigint: true }).catch((error) => {
+        let current;
+        try {
+            current = fsSync.lstatSync(dir, { bigint: true });
+        }
+        catch (error) {
             if (isNodeErrorWithCode(error, "ENOENT")) {
-                return undefined;
+                return;
             }
             throw error;
-        });
+        }
         if (!current || !sameFileIdentityForCleanup(current, identity)) {
             return;
         }
@@ -107,7 +112,7 @@ export async function tempFile(params) {
     const dir = await fs.mkdtemp(path.join(rootDir, prefix));
     // Windows file indexes can exceed Number.MAX_SAFE_INTEGER. Cleanup receipts
     // must retain the exact identity or adjacent directories can compare equal.
-    const identity = await fs.lstat(dir, { bigint: true });
+    const identity = fsSync.lstatSync(dir, { bigint: true });
     const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
     const file = (fileName) => path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
     const cleanup = async () => {

package/dist/timing.d.ts

@@ -1,3 +1,4 @@
+export declare function scheduleTimeout(callback: () => void, ms: number): () => void;
 export declare function sleep(ms: number): Promise<void>;
 export declare function sleepSync(ms: number): void;
 export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, labelOrOptions?: string | {

package/dist/timing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAK1C;AAED,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CA6BZ"}
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAEA,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,IAAI,CAgB5E;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAK1C;AAED,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ"}

package/dist/timing.js

@@ -1,5 +1,26 @@
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+export function scheduleTimeout(callback, ms) {
+    let timer;
+    if (Number.isFinite(ms) && ms > MAX_TIMER_DELAY_MS) {
+        const startedAt = performance.now();
+        const tick = () => {
+            const remaining = ms - (performance.now() - startedAt);
+            if (remaining <= 0)
+                callback();
+            else
+                timer = setTimeout(tick, Math.min(remaining, MAX_TIMER_DELAY_MS));
+        };
+        // Node clamps overflowing delays to 1 ms. Rearm bounded timers against a
+        // monotonic clock so clock changes and event-loop stalls cannot shorten them.
+        timer = setTimeout(tick, MAX_TIMER_DELAY_MS);
+    }
+    else {
+        timer = setTimeout(callback, ms);
+    }
+    return () => clearTimeout(timer);
+}
 export function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return new Promise((resolve) => { scheduleTimeout(resolve, ms); });
 }
 export function sleepSync(ms) {
     if (ms <= 0) {
@@ -16,12 +37,12 @@ export async function withTimeout(promise, timeoutMs, labelOrOptions = {
     const options = typeof labelOrOptions === "string" ? { label: labelOrOptions } : labelOrOptions;
     const createError = options.createError ??
         (() => new Error(options.message ?? `${options.label ?? "operation"} timed out after ${timeoutMs}ms`));
-    let timeoutId;
+    let cancelTimeout;
     try {
         return await Promise.race([
             promise,
             new Promise((_, reject) => {
-                timeoutId = setTimeout(() => {
+                cancelTimeout = scheduleTimeout(() => {
                     try {
                         reject(createError());
                     }
@@ -33,8 +54,6 @@ export async function withTimeout(promise, timeoutMs, labelOrOptions = {
         ]);
     }
     finally {
-        if (timeoutId) {
-            clearTimeout(timeoutId);
-        }
+        cancelTimeout?.();
     }
 }

package/dist/trash.js

@@ -18,7 +18,7 @@ function isTrashDestinationCollision(error) {
     return Boolean(code && TRASH_DESTINATION_COLLISION_CODES.has(code));
 }
 function isSameOrChildPath(candidate, parent) {
-    return candidate === parent || candidate.startsWith(`${parent}${path.sep}`);
+    return candidate === parent || candidate.startsWith(parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`);
 }
 function resolveAllowedTrashRoots(allowedRoots) {
     const roots = [...(allowedRoots ?? [os.homedir(), os.tmpdir()])].flatMap((root) => {
@@ -107,7 +107,7 @@ function resolveContainedPath(root, leaf) {
     return resolvedPath;
 }
 function reserveTrashDestination(trashDir, base, timestamp) {
-    const containerPrefix = resolveContainedPath(trashDir, `${base}-${timestamp}-`);
+    const containerPrefix = resolveContainedPath(trashDir, `.fs-safe-trash-${timestamp}-`);
     const container = fs.mkdtempSync(containerPrefix);
     const resolvedContainer = path.resolve(container);
     const resolvedTrashDir = path.resolve(trashDir);

package/dist/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AA+FF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAyDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAyD1C"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AAgFF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAyDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAyD1C"}

package/dist/walk.js

@@ -27,7 +27,7 @@ function shouldStop(result, options) {
     return options.maxEntries !== undefined && result.scannedEntryCount >= Math.max(0, options.maxEntries);
 }
 function buildEntry(params) {
-    const fullPath = path.join(params.dir, params.dirent.name);
+    const fullPath = params.fullPath;
     const relativePath = path.relative(params.rootDir, fullPath) || params.dirent.name;
     return {
         name: params.dirent.name,
@@ -47,7 +47,7 @@ function recordFailedDir(result, root, dir, depth, error) {
         error,
     });
 }
-function resolveSyncKind(fullPath, dirent, symlinks) {
+function resolveKind(fullPath, dirent, symlinks) {
     const kind = kindForDirent(dirent);
     if (kind !== "symlink")
         return kind;
@@ -67,26 +67,6 @@ function resolveSyncKind(fullPath, dirent, symlinks) {
     }
     return "other";
 }
-async function resolveAsyncKind(fullPath, dirent, symlinks) {
-    const kind = kindForDirent(dirent);
-    if (kind !== "symlink")
-        return kind;
-    if (symlinks === "skip")
-        return null;
-    if (symlinks === "include")
-        return "symlink";
-    try {
-        const stat = await fs.stat(fullPath);
-        if (stat.isDirectory())
-            return "directory";
-        if (stat.isFile())
-            return "file";
-    }
-    catch {
-        return null;
-    }
-    return "other";
-}
 export function walkDirectorySync(rootDir, options = {}) {
     validateWalkOptions(options);
     const root = path.resolve(rootDir);
@@ -127,10 +107,10 @@ export function walkDirectorySync(rootDir, options = {}) {
             }
             result.scannedEntryCount += 1;
             const fullPath = path.join(dir, dirent.name);
-            const kind = resolveSyncKind(fullPath, dirent, symlinks);
+            const kind = resolveKind(fullPath, dirent, symlinks);
             if (!kind)
                 continue;
-            const entry = buildEntry({ rootDir: root, dir, dirent, depth, kind });
+            const entry = buildEntry({ rootDir: root, fullPath, dirent, depth, kind });
             if (options.include?.(entry) ?? true) {
                 result.entries.push(entry);
             }
@@ -162,7 +142,7 @@ export async function walkDirectory(rootDir, options = {}) {
             return;
         let realDir;
         try {
-            realDir = await fs.realpath(dir);
+            realDir = fsSync.realpathSync.native(dir);
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
@@ -186,10 +166,10 @@ export async function walkDirectory(rootDir, options = {}) {
             }
             result.scannedEntryCount += 1;
             const fullPath = path.join(dir, dirent.name);
-            const kind = await resolveAsyncKind(fullPath, dirent, symlinks);
+            const kind = resolveKind(fullPath, dirent, symlinks);
             if (!kind)
                 continue;
-            const entry = buildEntry({ rootDir: root, dir, dirent, depth, kind });
+            const entry = buildEntry({ rootDir: root, fullPath, dirent, depth, kind });
             if (options.include?.(entry) ?? true) {
                 result.entries.push(entry);
             }

package/dist/windows-owner.d.ts

@@ -6,24 +6,21 @@ export type WindowsOwnerExec = (command: string, args: string[]) => Promise<{
 export type WindowsOwnerSummary = {
     sid?: string;
     currentUserSid?: string;
-    principalSids?: Record<string, string>;
-    principalTranslationFailed?: boolean;
+    daclPresent?: boolean;
+    aces?: WindowsOwnerAce[];
+    aclError?: string;
     remote?: boolean;
     trusted?: boolean;
     error?: string;
     errorDetail?: PermissionCommandFailure;
     errorCause?: unknown;
 };
-export declare function resolveWindowsPrincipalSids(params: {
-    principals: string[];
-    known?: Record<string, string>;
-    env?: NodeJS.ProcessEnv;
-    exec: WindowsOwnerExec;
-}): Promise<Record<string, string>>;
-export declare function resolveWindowsCurrentUserSid(params: {
-    env?: NodeJS.ProcessEnv;
-    exec: WindowsOwnerExec;
-}): Promise<string | null>;
+export type WindowsOwnerAce = {
+    sid: string;
+    mask: number;
+    deny: boolean;
+    inheritOnly: boolean;
+};
 export declare function inspectWindowsOwner(params: {
     targetPath: string;
     env?: NodeJS.ProcessEnv;

package/dist/windows-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AA4DF,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyBlC;AAED,wBAAsB,4BAA4B,CAAC,MAAM,EAAE;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWzB;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAkD/B"}
+{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAqDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA+C/B"}

package/dist/windows-owner.js

@@ -23,65 +23,28 @@ function windowsOwnerQueryCommand(targetPath) {
         "$driveRoot=if($extendedDrive){$p.Substring(4,3)}else{$root}",
         "$namespacePath=$p.StartsWith('\\\\')",
         "$remote=($namespacePath -and -not $extendedDrive) -or ([IO.DriveInfo]::new($driveRoot).DriveType -eq [IO.DriveType]::Network)",
-        "$rules=$acl.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])",
-        "$principalSids=@($rules|ForEach-Object {$identity=$_.IdentityReference;$sid=$identity.Value;@{name=$sid;sid=$sid};try{@{name=$identity.Translate([System.Security.Principal.NTAccount]).Value;sid=$sid}}catch{}})",
-        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;principalSids=$principalSids;principalTranslationFailed=$false;remote=$remote}|ConvertTo-Json -Depth 4 -Compress",
+        // Emit only ASCII SID and numeric facts: console encodings can replace both
+        // Unicode pathnames and account names before JavaScript receives the bytes.
+        "$raw=[System.Security.AccessControl.RawSecurityDescriptor]::new($acl.GetSecurityDescriptorBinaryForm(),0)",
+        "$dacl=$raw.DiscretionaryAcl;$complete=$true",
+        "$aces=@(foreach($ace in $dacl){if($ace -isnot [System.Security.AccessControl.CommonAce] -or $ace.IsCallback -or [int]$ace.AceType -notin @(0,1)){$complete=$false;continue};@{sid=$ace.SecurityIdentifier.Value;mask=([long]$ace.AccessMask -band 4294967295);deny=([int]$ace.AceType -eq 1);inheritOnly=([int]$ace.AceFlags -band 8) -ne 0}})",
+        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|ConvertTo-Json -Depth 4 -Compress",
     ].join(";");
 }
-function windowsPrincipalQueryCommand(principals) {
-    const encodedPrincipals = Buffer.from(JSON.stringify(principals), "utf8").toString("base64");
-    return [
-        "$ErrorActionPreference='Stop'",
-        `$names=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPrincipals}'))|ConvertFrom-Json`,
-        "$rows=@($names|ForEach-Object {@{name=$_;sid=(New-Object System.Security.Principal.NTAccount($_)).Translate([System.Security.Principal.SecurityIdentifier]).Value}})",
-        "ConvertTo-Json -InputObject $rows -Compress",
-    ].join(";");
-}
-function parsePrincipalSidRows(value) {
-    const rows = Array.isArray(value) ? value : value ? [value] : [];
-    const result = {};
-    for (const row of rows) {
-        if (!row || typeof row !== "object") {
-            continue;
-        }
-        const name = "name" in row && typeof row.name === "string" ? row.name.trim() : "";
-        const sid = "sid" in row && typeof row.sid === "string" ? normalizeSid(row.sid) : "";
-        if (name && SID_RE.test(sid)) {
-            result[name.toLowerCase()] = sid;
-        }
-    }
-    return result;
-}
-export async function resolveWindowsPrincipalSids(params) {
-    const principals = [...new Set(params.principals.map((value) => value.trim()).filter(Boolean))];
-    const known = Object.fromEntries(Object.entries(params.known ?? {}).map(([name, sid]) => [name.toLowerCase(), normalizeSid(sid)]));
-    const unresolved = principals.filter((principal) => !known[principal.toLowerCase()]);
-    if (unresolved.length === 0) {
-        return known;
+function parseWindowsAclFacts(parsed) {
+    if (parsed.complete !== true || typeof parsed.daclPresent !== "boolean" || !Array.isArray(parsed.aces)) {
+        return { aclError: "Windows ACL query returned incomplete descriptor data" };
     }
-    const command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
-    const { stdout } = await params.exec(command, [
-        "-NoLogo",
-        "-NoProfile",
-        "-NonInteractive",
-        "-EncodedCommand",
-        encodePowerShellCommand(windowsPrincipalQueryCommand(unresolved)),
-    ]);
-    const resolved = { ...known, ...parsePrincipalSidRows(JSON.parse(stdout.trim())) };
-    if (principals.some((principal) => !resolved[principal.toLowerCase()])) {
-        throw new Error("Windows ACL principal translation returned incomplete SID data");
-    }
-    return resolved;
-}
-export async function resolveWindowsCurrentUserSid(params) {
-    try {
-        const { stdout, stderr } = await params.exec(resolveWindowsSystemCommand("whoami.exe", params.env), ["/user", "/fo", "csv", "/nh"]);
-        const match = `${stdout}\n${stderr}`.match(/\*?S-\d+-\d+(?:-\d+)+/i);
-        return match ? normalizeSid(match[0]) : null;
-    }
-    catch {
-        return null;
+    const aces = [];
+    for (const row of parsed.aces) {
+        if (!row || typeof row !== "object" || typeof row.sid !== "string" || !SID_RE.test(row.sid) ||
+            typeof row.mask !== "number" || !Number.isInteger(row.mask) || row.mask < 0 || row.mask > 0xffff_ffff ||
+            typeof row.deny !== "boolean" || typeof row.inheritOnly !== "boolean") {
+            return { aclError: "Windows ACL query returned invalid access-rule data" };
+        }
+        aces.push({ sid: normalizeSid(row.sid), mask: row.mask, deny: row.deny, inheritOnly: row.inheritOnly });
     }
+    return { daclPresent: parsed.daclPresent, aces };
 }
 export async function inspectWindowsOwner(params) {
     let command = "";
@@ -96,7 +59,11 @@ export async function inspectWindowsOwner(params) {
             "-EncodedCommand",
             encodePowerShellCommand(windowsOwnerQueryCommand(params.targetPath)),
         ]);
-        const parsed = JSON.parse(stdout.trim());
+        const value = JSON.parse(stdout.trim());
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return { error: "Windows owner query returned invalid SID data" };
+        }
+        const parsed = value;
         const ownerSid = typeof parsed.ownerSid === "string" && SID_RE.test(parsed.ownerSid)
             ? normalizeSid(parsed.ownerSid)
             : undefined;
@@ -110,8 +77,7 @@ export async function inspectWindowsOwner(params) {
         return {
             sid: ownerSid,
             currentUserSid,
-            principalSids: parsePrincipalSidRows(parsed.principalSids),
-            principalTranslationFailed: parsed.principalTranslationFailed === true,
+            ...parseWindowsAclFacts(parsed),
             remote,
             trusted: !remote && (ownerSid === currentUserSid || TRUSTED_OWNER_SIDS.has(ownerSid)),
         };

package/dist/write-file-handle.d.ts

@@ -0,0 +1,6 @@
+import type { FileHandle } from "node:fs/promises";
+export declare function writeAllToFile(target: FileHandle | number, data: string | Uint8Array, options?: {
+    encoding?: BufferEncoding;
+    assertBeforeMutation?: () => void;
+}): Promise<void>;
+//# sourceMappingURL=write-file-handle.d.ts.map

package/dist/write-file-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file-handle.d.ts","sourceRoot":"","sources":["../src/write-file-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAC7E,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/write-file-handle.js

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+const WRITE_CHUNK_BYTES = 512 * 1024;
+export async function writeAllToFile(target, data, options = {}) {
+    const buffer = typeof data === "string" ? Buffer.from(data, options.encoding ?? "utf8") : data;
+    let offset = 0;
+    while (offset < buffer.byteLength) {
+        const length = Math.min(WRITE_CHUNK_BYTES, buffer.byteLength - offset);
+        options.assertBeforeMutation?.();
+        const written = typeof target === "number"
+            ? await new Promise((resolve, reject) => {
+                fs.write(target, buffer, offset, length, null, (error, bytesWritten) => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(bytesWritten);
+                });
+            })
+            : (await target.write(buffer, offset, length, null)).bytesWritten;
+        if (written <= 0) {
+            throw new FsSafeError("helper-failed", "file write made no progress");
+        }
+        offset += written;
+    }
+}

package/dist/write-open-flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}
+{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAG7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}

package/dist/write-open-flags.js

@@ -1,5 +1,4 @@
 import fsSync from "node:fs";
-import fs from "node:fs/promises";
 import { hasNodeErrorCode } from "./path.js";
 export function resolveNonblockingWriteFlag(constants = fsSync.constants) {
     return process.platform !== "win32" && typeof constants.O_NONBLOCK === "number"
@@ -17,7 +16,7 @@ export async function isNonRegularWriteOpenError(error, filePath, flags) {
     if (!isNonblockingWriteEnxio(error, flags))
         return false;
     try {
-        return !(await fs.lstat(filePath)).isFile();
+        return !fsSync.lstatSync(filePath).isFile();
     }
     catch {
         return false;

package/docs/advanced.md

@@ -65,7 +65,8 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | Export | Page | Notes |
 |---|---|---|
 | `readFileDescriptorBounded`, `readFileDescriptorBoundedSync`, `readFileHandleBounded` | – | Incremental whole-file reads for already-open descriptors/handles. They consume at most `maxBytes + 1`, do not close the input, and throw `FsSafeError("too-large")` on overflow. |
-| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `rejectSymlinks: false` for explicit in-root following. |
+| `readFileWindowFully`, `readFileWindowFullySync`, `ReadFileWindowOptions` | [positional-read.md](positional-read.md) | Fill a caller-owned buffer at an explicit file position, completing short reads and returning the EOF count without moving or closing the descriptor. |
+| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |
@@ -79,6 +80,19 @@ receipts remain numeric. Custom `ioFs` adapters must honor `{ bigint: true }` fo
 Windows identities receive one re-inspection without reopening, then fail
 validation if still unknown.
 
+The explicit `symlinks` policy takes precedence over the existing `rejectSymlinks`
+boolean. Without `symlinks`, `rejectSymlinks: false` retains its existing behavior
+of following contained links, and omission still rejects all symlink components.
+
+The bounded descriptor helpers cap their initial speculative allocation at
+16 MiB plus the overflow-probe byte, even when a file reports a much larger
+size. Regular files up to that size can return from one read without copying
+chunks; larger files and short reads continue incrementally under the same
+byte limit. Continuation buffers grow only after filling with actual bytes,
+up to the byte budget plus its probe; file-size hints cannot force that growth.
+Unknown-size inputs start with at most 64 KiB. This avoids per-chunk copies and
+a final concatenation when a file exceeds the initial allocation.
+
 The bounded descriptor helpers start at the descriptor's current offset and
 leave ownership with the caller. They are intended for the second half of a
 safe read: first open and validate the path using the boundary appropriate to
@@ -117,7 +131,7 @@ component is followed by another segment, both helpers throw
 |---|---|---|
 | `safeDirName`, `safePathSegmentHashed`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories from caller-supplied identifiers. |
 | `sanitizeUntrustedFileName` | [filename.md](filename.md) | Coerce an untrusted string into a safe filename. |
-| `resolveHomeRelativePath` | – | Expand `~`-prefixed paths. |
+| `resolveHomeRelativePath` | – | Expand a leading `~` before resolving `.` and `..`; tildes inside relative paths stay literal. |
 
 ### Temp targets and sibling-temp writes
 
@@ -139,7 +153,7 @@ component is followed by another segment, both helpers throw
 | Export | Page | Notes |
 |---|---|---|
 | `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
-| `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `FsSafeError("timeout")`. |
+| `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `Error` by default, or an error supplied by `createError`. |
 | `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. |
 
 ## Stability
@@ -149,5 +163,5 @@ Items in this surface can change shape between minor versions if a higher-level
 ## Related pages
 
 - [Root API](root.md) — built on top of these helpers.
-- [Errors](errors.md) — every helper here surfaces failures as `FsSafeError`.
+- [Errors](errors.md) — shared filesystem error codes; generic timing helpers retain their documented error types.
 - [Security model](security-model.md) — what the underlying boundary checks promise.