@openclaw/fs-safe 0.5.1 → 0.5.3

package/dist/secret-file.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
+import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
@@ -8,6 +9,7 @@ import { sameFileIdentity } from "./file-identity.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
+import { serializePathWrite } from "./write-queue.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export const PRIVATE_SECRET_DIR_MODE = 0o700;
 export const PRIVATE_SECRET_FILE_MODE = 0o600;
@@ -89,7 +91,6 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
         filePath: resolvedPath,
         rejectPathSymlink: options.rejectSymlink,
         rejectHardlinks: options.rejectHardlinks !== false,
-        maxBytes,
     });
     if (!opened.ok) {
         const error = normalizeSecretReadError(opened.reason === "validation" ? new Error("security validation failed") : opened.error);
@@ -101,6 +102,15 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
         };
     }
     try {
+        if (!sameFileIdentity(previewStat, opened.stat)) {
+            const error = new FsSafeError("path-mismatch", "security validation failed");
+            return {
+                ok: false,
+                code: "path-mismatch",
+                error,
+                message: `Failed to read ${label} file at ${resolvedPath}: ${String(error)}`,
+            };
+        }
         const raw = readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
         const secret = raw.trim();
         if (!secret) {
@@ -116,9 +126,7 @@ function readSecretFileOutcomeSync(filePath, label, options = {}) {
         const normalized = normalizeSecretReadError(error);
         return {
             ok: false,
-            code: error instanceof FsSafeError && error.code === "too-large"
-                ? "too-large"
-                : "invalid-path",
+            code: error instanceof FsSafeError ? error.code : "read-failed",
             error: normalized,
             message: `Failed to read ${label} file at ${resolvedPath}: ${String(normalized)}`,
         };
@@ -257,6 +265,15 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     }
     return { rootGuard, targetReal: await fsp.realpath(resolvedTarget) };
 }
+async function secretFileWriteQueueKey(filePath) {
+    try {
+        return await canonicalPathFromExistingAncestor(filePath);
+    }
+    catch {
+        // Keep validation and its public error shape owned by the write path below.
+        return path.resolve(filePath);
+    }
+}
 async function materializeSecretFileAtomic(params, createOnly) {
     const mode = params.mode ?? PRIVATE_SECRET_FILE_MODE;
     const dirMode = params.dirMode ?? PRIVATE_SECRET_DIR_MODE;
@@ -304,11 +321,17 @@ async function materializeSecretFileAtomic(params, createOnly) {
     await enforcePrivateFileIdentityAndMode(finalFilePath, identity, mode);
 }
 export async function writeSecretFileAtomic(params) {
-    await materializeSecretFileAtomic(params, false);
+    const canonicalPath = await secretFileWriteQueueKey(params.filePath);
+    await serializePathWrite(canonicalPath, async () => {
+        await materializeSecretFileAtomic(params, false);
+    });
 }
 export async function createSecretFileAtomic(params) {
     try {
-        await materializeSecretFileAtomic(params, true);
+        const canonicalPath = await secretFileWriteQueueKey(params.filePath);
+        await serializePathWrite(canonicalPath, async () => {
+            await materializeSecretFileAtomic(params, true);
+        });
     }
     catch (error) {
         if ((error instanceof FsSafeError && error.code === "already-exists") ||

package/dist/secret-read-async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AAqF1B,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B"}
+{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AA0F1B,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B"}

package/dist/secret-read-async.js

@@ -68,7 +68,11 @@ async function readSecretFileOutcome(filePath, label, options) {
         const normalized = error instanceof Error ? error : new Error(String(error));
         return {
             ok: false,
-            code: error instanceof FsSafeError ? error.code : pathErrorCode(error) === "not-found" ? "not-found" : "path-mismatch",
+            code: error instanceof FsSafeError
+                ? error.code
+                : pathErrorCode(error) === "not-found"
+                    ? "not-found"
+                    : "read-failed",
             error: normalized,
             message: `Failed to read ${label} file at ${resolvedPath}: ${String(normalized)}`,
         };

package/dist/secure-temp-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-temp-dir.d.ts","sourceRoot":"","sources":["../src/secure-temp-dir.ts"],"names":[],"mappings":"AAMA,KAAK,aAAa,GAAG;IACnB,WAAW,IAAI,OAAO,CAAC;IACvB,cAAc,IAAI,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,CAAC;IAC5C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAWF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA0JnF"}
+{"version":3,"file":"secure-temp-dir.d.ts","sourceRoot":"","sources":["../src/secure-temp-dir.ts"],"names":[],"mappings":"AAOA,KAAK,aAAa,GAAG;IACnB,WAAW,IAAI,OAAO,CAAC;IACvB,cAAc,IAAI,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,CAAC;IAC5C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAWF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA8JnF"}

package/dist/secure-temp-dir.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { tmpdir as getOsTmpDir } from "node:os";
 import path from "node:path";
+import { assertSafePathSegment } from "./safe-path-segment.js";
 function isNodeErrorWithCode(err, code) {
     return (typeof err === "object" &&
         err !== null &&
@@ -8,6 +9,10 @@ function isNodeErrorWithCode(err, code) {
         err.code === code);
 }
 export function resolveSecureTempRoot(options) {
+    const fallbackPrefix = assertSafePathSegment(options.fallbackPrefix, {
+        allowDotPrefix: true,
+        label: "fallback temp prefix",
+    });
     const TMP_DIR_ACCESS_MODE = fs.constants.W_OK | fs.constants.X_OK;
     const accessSync = options.accessSync ?? fs.accessSync;
     const chmodSync = options.chmodSync ?? fs.chmodSync;
@@ -42,7 +47,7 @@ export function resolveSecureTempRoot(options) {
     };
     const fallback = () => {
         const base = tmpdir();
-        const suffix = uid === undefined ? options.fallbackPrefix : `${options.fallbackPrefix}-${uid}`;
+        const suffix = uid === undefined ? fallbackPrefix : `${fallbackPrefix}-${uid}`;
         const joiner = platform === "win32" ? path.win32.join : path.join;
         return joiner(base, suffix);
     };

package/dist/short-path.d.ts

@@ -0,0 +1,2 @@
+export declare function shortPath(value: string): string;
+//# sourceMappingURL=short-path.d.ts.map

package/dist/short-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"short-path.d.ts","sourceRoot":"","sources":["../src/short-path.ts"],"names":[],"mappings":"AAGA,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C"}

package/dist/short-path.js

@@ -0,0 +1,7 @@
+import os from "node:os";
+import { formatErrorDetail } from "./error-detail.js";
+export function shortPath(value) {
+    const home = os.homedir();
+    const shortened = value.startsWith(home) ? `~${value.slice(home.length)}` : value;
+    return formatErrorDetail(shortened);
+}

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

@@ -0,0 +1,30 @@
+import { type NativeFileHandle } from "./native-operations.js";
+import type { Root } from "./root-impl.js";
+import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import type { SidecarLockAcquireOptions, SidecarLockHandle } from "./sidecar-lock-types.js";
+type SidecarFileHandle = Pick<NativeFileHandle, "close" | "stat" | "writeFile">;
+export type HeldSidecarLock = {
+    refCount: number;
+    reentrantOwner?: string;
+    handle: SidecarFileHandle;
+    lockPath: string;
+    snapshot: SidecarLockSnapshot;
+    acquiredAt: number;
+    metadata: Record<string, unknown>;
+    releasePromise?: Promise<void>;
+    lockRoot?: Root;
+    parsePayload?: (raw: string) => unknown;
+    compromiseTimer?: NodeJS.Timeout;
+};
+type SidecarLockAcquisitionContext = {
+    held: Map<string, HeldSidecarLock>;
+    reclaimGuards: Set<string>;
+    ensureExitCleanupRegistered(): void;
+    handleForHeldLock(normalizedTargetPath: string, held: HeldSidecarLock): SidecarLockHandle;
+    releaseHeldLock(normalizedTargetPath: string, held: HeldSidecarLock, options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+};
+export declare function acquireSidecarLock<TPayload extends Record<string, unknown>>(options: SidecarLockAcquireOptions<TPayload>, context: SidecarLockAcquisitionContext): Promise<SidecarLockHandle>;
+export {};
+//# sourceMappingURL=sidecar-lock-acquire.d.ts.map

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

@@ -0,0 +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,CAmP5B"}

package/dist/sidecar-lock-acquire.js

@@ -0,0 +1,260 @@
+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 { readSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+async function resolveNormalizedTargetPath(targetPath) {
+    const resolved = path.resolve(targetPath);
+    const dir = path.dirname(resolved);
+    await fs.mkdir(dir, { recursive: true });
+    try {
+        return path.join(await fs.realpath(dir), path.basename(resolved));
+    }
+    catch {
+        return resolved;
+    }
+}
+export async function acquireSidecarLock(options, context) {
+    context.ensureExitCleanupRegistered();
+    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
+    const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
+    const 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;
+    let attempt = 0;
+    // Bounded so a genuine denial still surfaces as EPERM, not a lock timeout.
+    let transientDenials = 0;
+    const withinDenialBudget = () => ++transientDenials <= maxTransientLockDenials;
+    const waitForRetry = async () => {
+        const elapsed = Date.now() - startedAt;
+        if ((options.timeoutMs !== undefined &&
+            options.timeoutMs !== Number.POSITIVE_INFINITY &&
+            elapsed >= options.timeoutMs) ||
+            (maxRetries !== undefined && attempt >= maxRetries)) {
+            throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+                code: "file_lock_timeout",
+                lockPath,
+                normalizedTargetPath,
+            });
+        }
+        const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
+            ? Number.POSITIVE_INFINITY
+            : Math.max(0, options.timeoutMs - elapsed);
+        const delay = Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
+        attempt += 1;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    };
+    // Waiting can fail on the caller's own retry or deadline limits. Classifying
+    // a denial as contention must not cost them the original diagnosis, so hand
+    // the denial back when no further attempt can be scheduled.
+    const retryOrRethrowDenial = async (denial) => {
+        try {
+            await waitForRetry();
+        }
+        catch (waitError) {
+            if (waitError.code === "file_lock_timeout")
+                throw denial;
+            throw waitError;
+        }
+    };
+    try {
+        while (true) {
+            if (!ownsReclaimGuard && (await sidecarReclaimGuardExists(reclaimGuardPath))) {
+                await waitForRetry();
+                continue;
+            }
+            let handle = null;
+            let createdSnapshot = null;
+            let lockFileCreateDenied = false;
+            try {
+                const payload = await options.payload();
+                const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
+                if (options.lockRoot) {
+                    const relativeLockPath = relativeSidecarLockPath(options.lockRoot, lockPath);
+                    try {
+                        await options.lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
+                    }
+                    catch (error) {
+                        if (error instanceof FsSafeError && error.code === "already-exists") {
+                            throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
+                        }
+                        throw error;
+                    }
+                    createdSnapshot = { raw, payload, ownershipToken };
+                    handle = (await options.lockRoot.open(relativeLockPath)).handle;
+                }
+                else {
+                    try {
+                        handle =
+                            (await createNativeExclusiveFile(lockPath, 0o600)) ??
+                                (await fs.open(lockPath, "wx"));
+                    }
+                    catch (createError) {
+                        lockFileCreateDenied = isTransientLockFileDenial(createError, lockPath);
+                        throw createError;
+                    }
+                    await handle.writeFile(raw, "utf8");
+                }
+                const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
+                const createdHeld = {
+                    refCount: 1,
+                    reentrantOwner: options.reentrantOwner,
+                    handle,
+                    lockPath,
+                    snapshot,
+                    acquiredAt: Date.now(),
+                    metadata: options.metadata ?? {},
+                    lockRoot: options.lockRoot,
+                    parsePayload: options.parsePayload,
+                };
+                context.held.set(normalizedTargetPath, createdHeld);
+                if (ownsReclaimGuard) {
+                    try {
+                        await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
+                        ownsReclaimGuard = false;
+                    }
+                    catch (err) {
+                        await context.releaseHeldLock(normalizedTargetPath, createdHeld, { force: true });
+                        throw err;
+                    }
+                }
+                const returnedHandle = context.handleForHeldLock(normalizedTargetPath, createdHeld);
+                const interval = options.compromiseCheckIntervalMs;
+                if (options.onCompromised && interval !== undefined && interval > 0) {
+                    createdHeld.compromiseTimer = setInterval(() => {
+                        void returnedHandle.verifyStillHeld().then((stillHeld) => {
+                            if (!stillHeld && createdHeld.compromiseTimer) {
+                                clearInterval(createdHeld.compromiseTimer);
+                                createdHeld.compromiseTimer = undefined;
+                                options.onCompromised?.({ lockPath, normalizedTargetPath });
+                            }
+                        });
+                    }, interval);
+                    createdHeld.compromiseTimer.unref();
+                }
+                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.
+                    }
+                    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,
+                    });
+                }
+                else if (createdSnapshot) {
+                    await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
+                        lockRoot: options.lockRoot,
+                        parsePayload: options.parsePayload,
+                    });
+                }
+                if (lockFileCreateDenied && withinDenialBudget()) {
+                    await retryOrRethrowDenial(err);
+                    continue;
+                }
+                if (err.code !== "EEXIST") {
+                    throw err;
+                }
+                if (ownsReclaimGuard) {
+                    await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
+                    ownsReclaimGuard = false;
+                    continue;
+                }
+                const nowMs = Date.now();
+                let snapshot;
+                try {
+                    snapshot = await readSidecarLockSnapshot(lockPath, {
+                        lockRoot: options.lockRoot,
+                        parsePayload: options.parsePayload,
+                        rejectNonFile: true,
+                    });
+                }
+                catch (readErr) {
+                    if (!isTransientLockFileDenial(readErr, lockPath) || !withinDenialBudget())
+                        throw readErr;
+                    await retryOrRethrowDenial(readErr);
+                    continue;
+                }
+                if (!snapshot) {
+                    continue;
+                }
+                if (context.held.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+                const shouldReclaim = options.shouldReclaim ?? defaultSidecarLockShouldReclaim;
+                if (await shouldReclaim({
+                    lockPath,
+                    normalizedTargetPath,
+                    payload: snapshot?.payload ?? null,
+                    staleMs: options.staleMs,
+                    nowMs,
+                    heldByThisProcess: context.held.has(normalizedTargetPath),
+                })) {
+                    if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
+                        lockRoot: options.lockRoot,
+                        parsePayload: options.parsePayload,
+                    }))) {
+                        continue;
+                    }
+                    const staleRecovery = options.staleRecovery ?? "fail-closed";
+                    if (staleRecovery === "remove-if-unchanged") {
+                        if (!(await tryAcquireSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath))) {
+                            await waitForRetry();
+                            continue;
+                        }
+                        ownsReclaimGuard = true;
+                        const removal = await removeStaleSidecarLockIfAllowed({
+                            lockPath,
+                            normalizedTargetPath,
+                            snapshot,
+                            shouldRemoveStaleLock: options.shouldRemoveStaleLock,
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
+                        if (removal === "removed" || removal === "changed") {
+                            continue;
+                        }
+                        await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
+                        ownsReclaimGuard = false;
+                    }
+                    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+                        code: "file_lock_stale",
+                        lockPath,
+                        normalizedTargetPath,
+                    });
+                }
+                await waitForRetry();
+            }
+        }
+    }
+    finally {
+        if (ownsReclaimGuard) {
+            await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath).catch(() => undefined);
+        }
+    }
+}

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

@@ -1,6 +1,9 @@
 import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
+export declare const maxTransientLockDenials = 8;
+export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;
 export declare function sidecarLockPayloadIsStale(payload: unknown, staleMs: number, nowMs: number): boolean;
+export declare function sidecarLockPayloadCreatedAtMs(payload: unknown): number | null;
 export declare function defaultSidecarLockShouldReclaim(params: {
     lockPath: string;
     payload: unknown;

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;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAUT;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,CAOnB"}
+{"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"}

package/dist/sidecar-lock-policy.js

@@ -7,7 +7,23 @@ export function computeSidecarLockDelayMs(retry, attempt) {
     const jitter = retry.randomize ? 1 + Math.random() : 1;
     return Math.min(maxTimeout, Math.round(base * jitter));
 }
+// Windows denies access to a lock file while a just-unlinked directory entry
+// is still being torn down, so a contended acquire sees EPERM on a name that is
+// already gone -- both when creating it exclusively and when reading the
+// holder's snapshot. The next attempt succeeds, so this is contention rather
+// than a permission failure. The error must name the lock file itself: the
+// exclusive-create helper opens the parent directory first, and a denial from
+// that setup step carries no teardown evidence and has to reach the caller.
+export const maxTransientLockDenials = 8;
+export function isTransientLockFileDenial(error, lockPath) {
+    const denial = error;
+    return process.platform === "win32" && denial?.code === "EPERM" && denial.path === lockPath;
+}
 export function sidecarLockPayloadIsStale(payload, staleMs, nowMs) {
+    const createdAtMs = sidecarLockPayloadCreatedAtMs(payload);
+    return createdAtMs !== null && nowMs - createdAtMs > staleMs;
+}
+export function sidecarLockPayloadCreatedAtMs(payload) {
     const createdAt = payload &&
         typeof payload === "object" &&
         "createdAt" in payload &&
@@ -15,11 +31,12 @@ export function sidecarLockPayloadIsStale(payload, staleMs, nowMs) {
         ? payload.createdAt
         : "";
     const createdAtMs = Date.parse(createdAt);
-    return Number.isFinite(createdAtMs) && nowMs - createdAtMs > staleMs;
+    return Number.isFinite(createdAtMs) ? createdAtMs : null;
 }
 export async function defaultSidecarLockShouldReclaim(params) {
-    if (sidecarLockPayloadIsStale(params.payload, params.staleMs, params.nowMs))
-        return true;
+    const createdAtMs = sidecarLockPayloadCreatedAtMs(params.payload);
+    if (createdAtMs !== null)
+        return params.nowMs - createdAtMs > params.staleMs;
     try {
         return params.nowMs - (await fs.stat(params.lockPath)).mtimeMs > params.staleMs;
     }

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

@@ -22,8 +22,12 @@ export declare function parseSidecarLockPayload(raw: string, parser?: (raw: stri
 export declare function readSidecarLockSnapshot(lockPath: string, options?: {
     lockRoot?: Root;
     parsePayload?: (raw: string) => unknown;
+    rejectNonFile?: boolean;
+    allowDescriptorIdentityDrift?: boolean;
 }): Promise<SidecarLockSnapshot | null>;
-export declare function readSidecarLockSnapshotSync(lockPath: string, parsePayload?: (raw: string) => unknown): SidecarLockSnapshot | null;
+export declare function readSidecarLockSnapshotSync(lockPath: string, parsePayload?: (raw: string) => unknown, options?: {
+    rejectNonFile?: boolean;
+}): SidecarLockSnapshot | null;
 export declare function removeSidecarLockIfUnchangedSync(lockPath: string, observed: SidecarLockSnapshot): boolean;
 export declare function sidecarLockSnapshotMatches(current: SidecarLockSnapshot, observed: SidecarLockSnapshot): boolean;
 export declare function removeSidecarLockIfUnchanged(lockPath: string, observed: SidecarLockSnapshot | null, options?: {

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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"}