@openclaw/fs-safe 0.6.0 → 0.7.0

package/dist/sibling-temp.js

@@ -2,85 +2,40 @@ import crypto, { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
-import { syncDirectoryBestEffort } from "./directory-durability.js";
-import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { sanitizeUntrustedFileName } from "./filename.js";
+import { applyDirectoryMode } from "./replace-file-descriptor.js";
 import { root } from "./root.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
-import { registerTempPathForExit } from "./temp-cleanup.js";
+import { writeCallbackSibling } from "./sibling-staged-file.js";
+import { tempFile } from "./temp-target.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { serializePathWrite } from "./write-queue.js";
 function buildTempPath(dir, tempPrefix) {
     const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-stream", {
         label: "sibling temp prefix",
     });
     return path.join(dir, `${safePrefix}.${process.pid}.${randomUUID()}.tmp`);
 }
-async function syncFileBestEffort(filePath) {
-    const handle = await fs.open(filePath, "r+");
-    try {
-        await handle.sync();
-    }
-    catch (error) {
-        if (error.code !== "EPERM") {
-            throw error;
-        }
-    }
-    finally {
-        await handle.close();
-    }
-}
-function assertFinalPathIsSibling(dir, filePath) {
-    const resolvedDir = path.resolve(dir);
-    const resolvedFile = path.resolve(filePath);
-    if (path.dirname(resolvedFile) !== resolvedDir) {
-        throw new Error("Final path must be in the sibling temp directory.");
-    }
-}
 export async function writeSiblingTempFile(options) {
     const dir = path.resolve(options.dir);
     await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o700 });
     if (options.chmodDir !== false) {
-        await fs.chmod(dir, options.dirMode ?? 0o700).catch(() => undefined);
-    }
-    const dirGuard = await createAsyncDirectoryGuard(dir);
-    const tempPath = buildTempPath(dir, options.tempPrefix);
-    const unregisterTempPath = registerTempPathForExit(tempPath);
-    let tempExists = false;
-    try {
-        tempExists = true;
-        const result = await options.writeTemp(tempPath);
-        unregisterTempPath.setIdentity(await fs.lstat(tempPath, { bigint: true }));
-        if (options.mode !== undefined) {
-            await fs.chmod(tempPath, options.mode).catch(() => undefined);
-        }
-        if (options.syncTempFile) {
-            await syncFileBestEffort(tempPath);
-        }
-        const filePath = path.resolve(options.resolveFinalPath(result));
-        assertFinalPathIsSibling(dir, filePath);
-        await serializePathWrite(filePath, async () => {
-            await withAsyncDirectoryGuards([dirGuard], async () => {
-                await fs.rename(tempPath, filePath);
-            });
-            tempExists = false;
-            unregisterTempPath();
-            if (options.mode !== undefined) {
-                await fs.chmod(filePath, options.mode).catch(() => undefined);
-            }
-            if (options.syncParentDir) {
-                await syncDirectoryBestEffort(dir);
-            }
+        await applyDirectoryMode({
+            fsModule: fs,
+            dirPath: dir,
+            mode: options.dirMode ?? 0o700,
+            ignoreChmodError: true,
         });
-        return { filePath, result };
-    }
-    finally {
-        if (tempExists) {
-            await fs.rm(tempPath, { force: true }).catch(() => undefined);
-        }
-        unregisterTempPath();
     }
+    return await writeCallbackSibling({
+        tempPath: buildTempPath(dir, options.tempPrefix),
+        write: options.writeTemp,
+        resolveFinalPath: options.resolveFinalPath,
+        mode: options.mode,
+        ignoreModeError: true,
+        syncTempFile: options.syncTempFile === true,
+        syncParentDir: options.syncParentDir === true,
+    });
 }
 function buildSiblingTempPath(params) {
     const id = crypto.randomUUID();
@@ -107,18 +62,20 @@ export async function writeViaSiblingTempPath(params) {
         throw new Error("Target path is outside the allowed root");
     }
     const rootGuard = await createAsyncDirectoryGuard(rootDir);
-    const tempDir = await fs.mkdtemp(path.join(resolveSecureTempRoot({
-        fallbackPrefix: "fs-safe-output",
-        unsafeFallbackLabel: "sibling temp output dir",
-        warn: () => undefined,
-    }), "fs-safe-output-"));
-    const tempPath = buildSiblingTempPath({
-        targetPath: path.join(tempDir, path.basename(targetPath)),
-        fallbackFileName: params.fallbackFileName ?? "output.bin",
-        tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
+    const workspace = await tempFile({
+        rootDir: resolveSecureTempRoot({
+            fallbackPrefix: "fs-safe-output",
+            unsafeFallbackLabel: "sibling temp output dir",
+            warn: () => undefined,
+        }),
+        prefix: "fs-safe-output",
     });
-    const unregisterTempPath = registerTempPathForExit(tempDir, { recursive: true });
     try {
+        const tempPath = buildSiblingTempPath({
+            targetPath: path.join(workspace.dir, path.basename(targetPath)),
+            fallbackFileName: params.fallbackFileName ?? "output.bin",
+            tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
+        });
         await getFsSafeTestHooks()?.beforeSiblingTempWrite?.(tempPath);
         await params.writeTemp(tempPath);
         await assertAsyncDirectoryGuard(rootGuard);
@@ -127,7 +84,6 @@ export async function writeViaSiblingTempPath(params) {
         await assertAsyncDirectoryGuard(rootGuard);
     }
     finally {
-        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => { });
-        unregisterTempPath();
+        await workspace.cleanup();
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAO3C,OAAO,EAUL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAaF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAsP5B"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAS3C,OAAO,EAUL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAaF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CA+Q5B"}

package/dist/sidecar-lock-acquire.js

@@ -2,8 +2,9 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { createNativeExclusiveFile } from "./native-operations.js";
-import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, } from "./sidecar-lock-policy.js";
+import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { readSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+import { createSuppressedError } from "./suppressed-error.js";
 async function resolveNormalizedTargetPath(targetPath) {
     const resolved = path.resolve(targetPath);
     const dir = path.dirname(resolved);
@@ -16,19 +17,34 @@ async function resolveNormalizedTargetPath(targetPath) {
     }
 }
 export async function acquireSidecarLock(options, context) {
+    const retry = options.retry ?? {};
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(options.timeoutMs);
     context.ensureExitCleanupRegistered();
     const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
     const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
-    const held = context.held.get(normalizedTargetPath);
+    let held = context.held.get(normalizedTargetPath);
     if (held &&
         options.reentrantOwner !== undefined &&
         held.reentrantOwner !== undefined &&
         options.reentrantOwner === held.reentrantOwner) {
-        held.refCount += 1;
-        return context.handleForHeldLock(normalizedTargetPath, held);
+        // A final release may already have decremented the count to zero and be
+        // removing the sidecar. Do not admit a new reentrant handle until that
+        // cleanup settles: successful cleanup requires a fresh acquisition, while
+        // failed cleanup leaves the existing sidecar held for a retry.
+        if (held.releasePromise) {
+            await held.releasePromise.catch(() => undefined);
+            held = context.held.get(normalizedTargetPath);
+        }
+        if (held &&
+            options.reentrantOwner !== undefined &&
+            held.reentrantOwner !== undefined &&
+            options.reentrantOwner === held.reentrantOwner) {
+            held.refCount += 1;
+            return context.handleForHeldLock(normalizedTargetPath, held);
+        }
     }
     const startedAt = Date.now();
-    const retry = options.retry ?? {};
     const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
     const reclaimGuardPath = `${lockPath}.reclaim`;
     let ownsReclaimGuard = false;
@@ -149,31 +165,36 @@ export async function acquireSidecarLock(options, context) {
                 return returnedHandle;
             }
             catch (err) {
-                if (handle) {
-                    const failedSnapshot = { payload: null };
-                    try {
-                        failedSnapshot.stat = await handle.stat();
-                    }
-                    catch {
-                        // Best-effort cleanup of a failed exclusive create.
+                try {
+                    if (handle) {
+                        const failedSnapshot = { payload: null };
+                        try {
+                            failedSnapshot.stat = await handle.stat();
+                        }
+                        catch {
+                            // Best-effort cleanup of a failed exclusive create.
+                        }
+                        const current = context.held.get(normalizedTargetPath);
+                        if (current?.handle === handle) {
+                            context.held.delete(normalizedTargetPath);
+                        }
+                        await handle.close().catch(() => undefined);
+                        // The file may be empty or partial JSON, so remove by the identity
+                        // captured from our exclusive handle rather than by pathname alone.
+                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
                     }
-                    const current = context.held.get(normalizedTargetPath);
-                    if (current?.handle === handle) {
-                        context.held.delete(normalizedTargetPath);
+                    else if (createdSnapshot) {
+                        await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
                     }
-                    await handle.close().catch(() => undefined);
-                    // The file may be empty or partial JSON, so remove by the identity
-                    // captured from our exclusive handle rather than by pathname alone.
-                    await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    });
                 }
-                else if (createdSnapshot) {
-                    await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    });
+                catch (cleanupError) {
+                    throw createSuppressedError(cleanupError, err, "file lock acquisition and cleanup both failed");
                 }
                 if (lockFileCreateDenied && withinDenialBudget()) {
                     await retryOrRethrowDenial(err);

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

@@ -5,7 +5,9 @@ export declare function createSidecarLockHandle(params: {
     lockPath: string;
     normalizedTargetPath: string;
     verifyStillHeld: () => Promise<boolean>;
-    release: () => Promise<unknown>;
+    release: (options?: {
+        retry?: boolean;
+    }) => Promise<unknown>;
 }): SidecarLockHandle;
 export declare function createHeldSidecarLockHandle(params: {
     normalizedTargetPath: string;
@@ -15,6 +17,8 @@ export declare function createHeldSidecarLockHandle(params: {
         lockRoot?: Root;
         parsePayload?: (raw: string) => unknown;
     };
-    release: () => Promise<unknown>;
+    release: (options?: {
+        retry?: boolean;
+    }) => Promise<unknown>;
 }): SidecarLockHandle;
 //# sourceMappingURL=sidecar-lock-handle.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-handle.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,iBAAiB,CAcpB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,QAAQ,CAAC,EAAE,IAAI,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IACF,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,iBAAiB,CAWpB"}
+{"version":3,"file":"sidecar-lock-handle.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,GAAG,iBAAiB,CA2BpB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,QAAQ,CAAC,EAAE,IAAI,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IACF,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,GAAG,iBAAiB,CAWpB"}

package/dist/sidecar-lock-handle.js

@@ -1,11 +1,25 @@
 import { sidecarLockSnapshotStillPresent, } from "./sidecar-lock-reclaim.js";
 export function createSidecarLockHandle(params) {
     let released = false;
+    let releasePromise;
+    let releaseStarted = false;
     const release = async () => {
         if (released)
             return;
-        released = true;
-        await params.release();
+        if (!releasePromise) {
+            const retry = releaseStarted;
+            releaseStarted = true;
+            releasePromise = (async () => {
+                await params.release({ retry });
+                released = true;
+            })();
+        }
+        try {
+            await releasePromise;
+        }
+        finally {
+            releasePromise = undefined;
+        }
     };
     return {
         lockPath: params.lockPath,
@@ -23,6 +37,6 @@ export function createHeldSidecarLockHandle(params) {
             lockRoot: params.held.lockRoot,
             parsePayload: params.held.parsePayload,
         }),
-        release: params.release,
+        release: (options) => params.release(options),
     });
 }

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

@@ -1,4 +1,6 @@
 import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
+export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAGT;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}
+{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAQvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAGT;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}

package/dist/sidecar-lock-policy.js

@@ -1,5 +1,34 @@
 import fs from "node:fs/promises";
+function assertFiniteNonNegative(value, label) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${label} must be a finite non-negative number`);
+    }
+}
+export function validateSidecarLockRetryOptions(retry) {
+    if (retry.retries !== undefined && (!Number.isSafeInteger(retry.retries) || retry.retries < 0)) {
+        throw new RangeError("lock retry.retries must be a non-negative safe integer");
+    }
+    if (retry.factor !== undefined)
+        assertFiniteNonNegative(retry.factor, "lock retry.factor");
+    if (retry.minTimeout !== undefined) {
+        assertFiniteNonNegative(retry.minTimeout, "lock retry.minTimeout");
+    }
+    if (retry.maxTimeout !== undefined) {
+        assertFiniteNonNegative(retry.maxTimeout, "lock retry.maxTimeout");
+    }
+    if (retry.minTimeout !== undefined &&
+        retry.maxTimeout !== undefined &&
+        retry.minTimeout > retry.maxTimeout) {
+        throw new RangeError("lock retry.minTimeout must not exceed retry.maxTimeout");
+    }
+}
+export function validateSidecarLockTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY)
+        return;
+    assertFiniteNonNegative(timeoutMs, "lock timeoutMs");
+}
 export function computeSidecarLockDelayMs(retry, attempt) {
+    validateSidecarLockRetryOptions(retry);
     const minTimeout = retry.minTimeout ?? 50;
     const maxTimeout = retry.maxTimeout ?? 1000;
     const factor = retry.factor ?? 1;

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}

package/dist/sidecar-lock-reclaim.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const MAX_LOCK_PAYLOAD_BYTES = 1024 * 1024;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES = 16;
@@ -59,7 +60,25 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
     let handle;
     try {
         if (options.lockRoot) {
-            const opened = await options.lockRoot.open(relativeSidecarLockPath(options.lockRoot, lockPath));
+            const lockRoot = options.lockRoot;
+            const relative = relativeSidecarLockPath(lockRoot, lockPath);
+            const opened = await lockRoot.open(relative).catch(async (error) => {
+                if (error instanceof FsSafeError && error.code === "path-mismatch") {
+                    // An owner can unlink after open. Prove absence through the same root;
+                    // acquisition retries create-only, so a later replacement stays guarded.
+                    try {
+                        await lockRoot.stat(relative);
+                    }
+                    catch (probeError) {
+                        if (probeError instanceof FsSafeError && probeError.code === "not-found") {
+                            return null;
+                        }
+                    }
+                }
+                throw error;
+            });
+            if (!opened)
+                return null;
             try {
                 const raw = (await readFileHandleBounded(opened.handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
                 return {
@@ -132,11 +151,14 @@ export function readSidecarLockSnapshotSync(lockPath, parsePayload, options = {}
             }
             return null;
         }
-        const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
-            ? fsSync.constants.O_NOFOLLOW
-            : 0;
-        fd = fsSync.openSync(lockPath, fsSync.constants.O_RDONLY | noFollow);
+        fd = fsSync.openSync(lockPath, resolveReadOpenFlags());
         const opened = fsSync.fstatSync(fd);
+        if (!opened.isFile()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
         const raw = readFileDescriptorBoundedSync(fd, MAX_LOCK_PAYLOAD_BYTES).toString("utf8");
         const after = fsSync.lstatSync(lockPath);
         if (!sameFileIdentity(before, opened) || !sameFileIdentity(opened, after))
@@ -191,10 +213,10 @@ export async function removeSidecarLockIfUnchanged(lockPath, observed, options =
         return false;
     }
     if (options.lockRoot) {
-        await options.lockRoot.remove(relativeSidecarLockPath(options.lockRoot, lockPath)).catch(() => undefined);
+        await options.lockRoot.remove(relativeSidecarLockPath(options.lockRoot, lockPath));
     }
     else {
-        await fs.rm(lockPath, { force: true }).catch(() => undefined);
+        await fs.rm(lockPath, { force: true });
     }
     return true;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AASA,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;AAmLjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAS3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAYL,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;iBASW,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":"AAUA,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;AAsLjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAS3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAYL,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

@@ -3,6 +3,7 @@ import { sameFileIdentity } from "./file-identity.js";
 import { removeSidecarLockIfUnchanged, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
 import { acquireSidecarLock } from "./sidecar-lock-acquire.js";
 import { createHeldSidecarLockHandle } from "./sidecar-lock-handle.js";
+import { createSuppressedError } from "./suppressed-error.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
 const GLOBAL_CLEANUP_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistered");
 const GLOBAL_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockCleanupHandler");
@@ -121,23 +122,18 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
     if (current !== held) {
         return false;
     }
+    if (held.releasePromise) {
+        await held.releasePromise;
+        return true;
+    }
     if (options.force) {
         held.refCount = 0;
     }
-    else {
+    else if (!options.retry && held.refCount > 0) {
         held.refCount -= 1;
-        if (held.refCount > 0) {
-            return false;
-        }
-    }
-    if (held.releasePromise) {
-        await held.releasePromise.catch(() => undefined);
-        return true;
     }
-    state.held.delete(normalizedTargetPath);
-    if (held.compromiseTimer) {
-        clearInterval(held.compromiseTimer);
-        held.compromiseTimer = undefined;
+    if (held.refCount > 0) {
+        return false;
     }
     held.releasePromise = (async () => {
         await held.handle.close().catch(() => undefined);
@@ -145,6 +141,13 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
             lockRoot: held.lockRoot,
             parsePayload: held.parsePayload,
         });
+        if (state.held.get(normalizedTargetPath) === held) {
+            state.held.delete(normalizedTargetPath);
+        }
+        if (held.compromiseTimer) {
+            clearInterval(held.compromiseTimer);
+            held.compromiseTimer = undefined;
+        }
     })();
     try {
         await held.releasePromise;
@@ -158,7 +161,7 @@ function handleForHeldLock(state, normalizedTargetPath, held) {
     return createHeldSidecarLockHandle({
         normalizedTargetPath,
         held,
-        release: async () => await releaseHeldLock(state, normalizedTargetPath, held),
+        release: async (options) => await releaseHeldLock(state, normalizedTargetPath, held, { retry: options?.retry }),
     });
 }
 export function createSidecarLockManager(key) {
@@ -179,12 +182,21 @@ export function createSidecarLockManager(key) {
     }
     async function withLock(options, fn) {
         const lock = await acquire(options);
+        let result;
         try {
-            return await fn();
+            result = await fn();
         }
-        finally {
-            await lock.release();
+        catch (bodyError) {
+            try {
+                await lock.release();
+            }
+            catch (releaseError) {
+                throw createSuppressedError(releaseError, bodyError, "file lock callback and release both failed");
+            }
+            throw bodyError;
         }
+        await lock.release();
+        return result;
     }
     async function drain() {
         for (const [normalizedTargetPath, held] of Array.from(state.held.entries())) {

package/dist/suppressed-error.d.ts

@@ -0,0 +1,6 @@
+export type SuppressedErrorLike = Error & {
+    error: unknown;
+    suppressed: unknown;
+};
+export declare function createSuppressedError(error: unknown, suppressed: unknown, message: string): SuppressedErrorLike;
+//# sourceMappingURL=suppressed-error.d.ts.map

package/dist/suppressed-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppressed-error.d.ts","sourceRoot":"","sources":["../src/suppressed-error.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAQF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,MAAM,GACd,mBAAmB,CAgBrB"}

package/dist/suppressed-error.js

@@ -0,0 +1,15 @@
+export function createSuppressedError(error, suppressed, message) {
+    const constructor = globalThis.SuppressedError;
+    if (constructor) {
+        return new constructor(error, suppressed, message);
+    }
+    const combined = new Error(message, {
+        cause: error instanceof Error ? error : undefined,
+    });
+    combined.name = "SuppressedError";
+    Object.defineProperties(combined, {
+        error: { configurable: true, value: error },
+        suppressed: { configurable: true, value: suppressed },
+    });
+    return combined;
+}

package/dist/temp-cleanup.d.ts

@@ -6,6 +6,8 @@ export type TempPathRegistration = (() => void) & {
 export declare function registerTempPathForExit(tempPath: string, options?: {
     recursive?: boolean;
     identity?: FileIdentityStat;
+    singleLinkFile?: boolean;
+    cleanupSync?: () => unknown;
 }): TempPathRegistration;
 export declare function __cleanupRegisteredTempPathsForTest(): void;
 export declare function __cleanupRegisteredTempPathForTest(tempPath: string): void;

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;AAsCF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAAE,GAC7D,oBAAoB,CAyBtB;AAED,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYzE"}
+{"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"}