@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/sibling-staged-file.js

@@ -2,7 +2,7 @@ import { syncFileBestEffort } from "./file-sync.js";
 import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
-import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { assertDirectoryIdentitySync, createAsyncDirectoryGuard, } from "./directory-guard.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { isWindowsReservedDeviceName } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
@@ -10,7 +10,7 @@ import { getNativeBinding } from "./native.js";
 import { handoffPrivateProducerFile, } from "./private-producer-handoff.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { rootFromDirectoryGuard } from "./root-impl.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { createOwnedTempFile } from "./temp-target.js";
 import { serializePathWrite } from "./write-queue.js";
@@ -52,8 +52,8 @@ function assertRegularFile(stat) {
         throw new FsSafeError("hardlink", "sibling temp must have exactly one link");
     }
 }
-async function inspectStage(inspect, expected) {
-    return await inspectFileIdentity(async () => {
+function inspectStage(inspect, expected) {
+    return inspectFileIdentitySync(() => {
         const stat = inspect();
         assertRegularFile(stat);
         return stat;
@@ -67,12 +67,7 @@ function aggregateErrors(errors, message) {
 // Own the workspace before the producer can leave partial output. The finished
 // file still enters the ordinary sibling admission and publication lifecycle.
 async function writeIsolatedProducer(params) {
-    const tempPath = params.tempPath;
-    const write = params.write;
-    const writeReceiver = params.writeReceiver;
-    const parentGuard = params.parentGuard;
-    const assertParent = params.assertParent;
-    const syncTempFile = params.syncTempFile;
+    const { tempPath, write, writeReceiver, parentGuard, assertParent, syncTempFile } = params;
     assertParent();
     const targetRoot = rootFromDirectoryGuard(parentGuard);
     // Select the handoff before invoking the producer. Missing required native
@@ -150,7 +145,9 @@ export async function writeCallbackSibling(params) {
     const syncTempFile = params.syncTempFile;
     const syncParentDir = params.syncParentDir;
     const guard = await createAsyncDirectoryGuard(parent, { bigint: true });
-    const assertParent = () => assertAsyncDirectoryGuard(guard);
+    const assertParent = () => assertDirectoryIdentitySync(parent, {
+        dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath,
+    });
     let handle;
     let identity;
     let unregister;
@@ -158,10 +155,10 @@ export async function writeCallbackSibling(params) {
     let renamed = false;
     let failure;
     const inspectPath = (pathname, expected) => inspectStage(() => fsSync.lstatSync(pathname, { bigint: true }), expected);
-    const assertCurrent = async (pathname) => {
-        await assertParent();
-        const opened = await inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
-        const current = await inspectPath(pathname, opened);
+    const assertCurrent = (pathname) => {
+        assertParent();
+        const opened = inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
+        const current = inspectPath(pathname, opened);
         if (maxBytes !== undefined &&
             (opened.size > maxBytes || current.size > maxBytes)) {
             throw new FsSafeError("too-large", `sibling temp exceeds maxBytes (${maxBytes})`);
@@ -176,11 +173,7 @@ export async function writeCallbackSibling(params) {
                 writeReceiver: params,
                 parentGuard: guard,
                 syncTempFile: syncTempFile,
-                assertParent: () => assertDirectoryIdentitySync(parent, {
-                    dev: guard.stat.dev,
-                    ino: guard.stat.ino,
-                    realPath: guard.realPath,
-                }),
+                assertParent,
             });
             result = isolated.result;
             cleanupWorkspace = isolated.cleanupWorkspace;
@@ -193,13 +186,10 @@ export async function writeCallbackSibling(params) {
         else {
             result = await Reflect.apply(write, params, [tempPath]);
         }
-        await assertParent();
-        if (handle) {
-            const opened = await inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
-            await inspectPath(tempPath, opened);
-        }
-        else {
-            const before = await inspectPath(tempPath);
+        assertParent();
+        let expected = identity;
+        if (!handle) {
+            expected = inspectPath(tempPath);
             try {
                 // No create/truncate flags; O_NONBLOCK also bounds a FIFO swap during open.
                 const access = syncTempFile ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
@@ -211,12 +201,14 @@ export async function writeCallbackSibling(params) {
                 }
                 throw error;
             }
-            const opened = await inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), before);
-            await inspectPath(tempPath, opened);
+        }
+        const opened = inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), expected);
+        inspectPath(tempPath, opened);
+        if (!identity) {
             identity = opened;
             unregister = registerTempPathForExit(tempPath, { identity, singleLinkFile: true });
         }
-        await assertParent();
+        assertParent();
         if (cleanupWorkspace) {
             const cleanup = cleanupWorkspace;
             cleanupWorkspace = undefined;
@@ -233,7 +225,7 @@ export async function writeCallbackSibling(params) {
             throw new FsSafeError("invalid-path", "final path must differ from the sibling temp path");
         }
         await serializePathWrite(filePath, async () => {
-            await assertCurrent(tempPath);
+            assertCurrent(tempPath);
             if (mode !== undefined) {
                 try {
                     await handle.chmod(mode);
@@ -242,20 +234,21 @@ export async function writeCallbackSibling(params) {
                     if (!ignoreModeError)
                         throw error;
                 }
+                assertCurrent(tempPath);
             }
             if (syncTempFile) {
-                await assertCurrent(tempPath);
                 await syncFileBestEffort(handle);
+                assertCurrent(tempPath);
             }
-            await assertCurrent(tempPath);
             await fs.rename(tempPath, filePath);
             // A later verification failure never authorizes rollback of the final name.
             renamed = true;
             unregister();
-            await assertCurrent(filePath);
-            if (syncParentDir)
+            assertCurrent(filePath);
+            if (syncParentDir) {
                 await syncDirectoryBestEffort(parent);
-            await assertCurrent(filePath);
+                assertCurrent(filePath);
+            }
         });
         return { filePath, result };
     }
@@ -276,9 +269,9 @@ export async function writeCallbackSibling(params) {
         try {
             if (!renamed && identity) {
                 try {
-                    await assertParent();
-                    await inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
-                    await inspectPath(tempPath, identity);
+                    assertParent();
+                    inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
+                    inspectPath(tempPath, identity);
                     await fs.unlink(tempPath);
                     unregister?.();
                 }

package/dist/sibling-temp.d.ts

@@ -26,4 +26,3 @@ export declare function writeViaSiblingTempPath(params: {
     fallbackFileName?: string;
     tempPrefix?: string;
 }): Promise<void>;
-//# sourceMappingURL=sibling-temp.d.ts.map

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

@@ -1,5 +1,4 @@
 import type { SidecarLockAcquireOptions, SidecarLockHandle } from "./sidecar-lock-types.js";
-import { type SidecarLockAcquisitionContext } from "./sidecar-lock-admission.js";
+import type { SidecarLockAcquisitionContext } from "./sidecar-lock-admission.js";
 export type { HeldSidecarLock } from "./sidecar-lock-admission.js";
 export declare function acquireSidecarLock<TPayload extends Record<string, unknown>>(options: SidecarLockAcquireOptions<TPayload>, context: SidecarLockAcquisitionContext): Promise<SidecarLockHandle>;
-//# sourceMappingURL=sidecar-lock-acquire.d.ts.map

package/dist/sidecar-lock-acquire.js

@@ -5,12 +5,11 @@ import { fileObservation } from "./file-observation.js";
 import { readFileHandleBounded } from "./bounded-read.js";
 import { openSidecarRoot } from "./sidecar-lock-root.js";
 import { createNativeExclusiveFile } from "./native-operations.js";
-import { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockStaleMs, validateSidecarLockRetryOptions, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { sidecarLockRetryDelay, sidecarLockTimeout, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockStaleMs, validateSidecarLockRetryOptions, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { relativeSidecarLockPath, removeSidecarLockIfUnchanged, serializeSidecarLockPayload, sidecarReclaimGuardExists, } from "./sidecar-lock-reclaim.js";
 import { awaitSidecarAdmissionBoundary, conditionalSidecarLockParser, observeHeldSidecarParser, observeSidecarLockParser, runSidecarAdmissionBoundary, } from "./sidecar-lock-admission-parser.js";
 import { handleStaleSidecarAdmission, } from "./sidecar-lock-stale-admission.js";
 import { ancestryHasSidecarAdmission, captureSidecarAdmissionAncestry, createSidecarAdmissionController, } from "./sidecar-lock-admission-context.js";
-import { sidecarLockTimeout } from "./sidecar-lock-admission.js";
 import { resolveSidecarLockPaths } from "./sidecar-lock-target.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { sleep } from "./timing.js";
@@ -34,11 +33,25 @@ export async function acquireSidecarLock(options, context) {
     const requestedReentrantOwner = options.reentrantOwner;
     const { lockPath, normalizedTargetPath } = await resolveSidecarLockPaths(targetPath, explicitLockPath, lockRoot);
     const activeDescendant = ancestryHasSidecarAdmission(admissionAncestry, context.admissions, normalizedTargetPath);
-    let held = context.held.get(normalizedTargetPath);
-    if (held &&
+    const isReentrant = (candidate) => !!candidate &&
         requestedReentrantOwner !== undefined &&
-        held.reentrantOwner !== undefined &&
-        requestedReentrantOwner === held.reentrantOwner) {
+        candidate.reentrantOwner !== undefined &&
+        requestedReentrantOwner === candidate.reentrantOwner;
+    const reuseHeldLock = (candidate) => {
+        const lifecycle = context.ensureExitCleanupRegistered();
+        context.assertRetainOnExitSupported(retainOnExit);
+        if (context.held.get(normalizedTargetPath) !== candidate || candidate.releasePromise)
+            return undefined;
+        candidate.refCount = (candidate.refCount ?? 1) + 1;
+        // Any same-owner request upgrades exit retention; later requests never revoke it.
+        if (retainOnExit === true)
+            candidate.retainOnExit = true;
+        const returnedHandle = context.handleForHeldLock(normalizedTargetPath, candidate);
+        context.armExitCleanup(lifecycle);
+        return returnedHandle;
+    };
+    let held = context.held.get(normalizedTargetPath);
+    if (isReentrant(held)) {
         // Join a final release before deciding whether this completed owner remains.
         // Successful cleanup requires a fresh acquisition; failed cleanup can retry.
         if (held.releasePromise) {
@@ -47,29 +60,16 @@ export async function acquireSidecarLock(options, context) {
             await held.releasePromise.catch(() => undefined);
             held = context.held.get(normalizedTargetPath);
         }
-        if (held &&
-            requestedReentrantOwner !== undefined &&
-            held.reentrantOwner !== undefined &&
-            requestedReentrantOwner === held.reentrantOwner) {
-            const lifecycle = context.ensureExitCleanupRegistered();
-            context.assertRetainOnExitSupported(retainOnExit);
-            if (context.held.get(normalizedTargetPath) === held && !held.releasePromise) {
-                held.refCount = (held.refCount ?? 1) + 1;
-                // Retention is monotonic: any same-owner request to keep the sidecar on
-                // exit upgrades the held lock; a later default acquisition never revokes it.
-                if (retainOnExit === true) {
-                    held.retainOnExit = true;
-                }
-                const returnedHandle = context.handleForHeldLock(normalizedTargetPath, held);
-                context.armExitCleanup(lifecycle);
-                return returnedHandle;
-            }
+        if (isReentrant(held)) {
+            const reused = reuseHeldLock(held);
+            if (reused)
+                return reused;
         }
     }
     if (activeDescendant)
         throw sidecarLockTimeout(lockPath, normalizedTargetPath);
     const admission = createSidecarAdmissionController(admissionAncestry, context.admissions, normalizedTargetPath);
-    const startedAt = Date.now();
+    const startedAt = performance.now();
     const reclaimGuardPath = `${lockPath}.reclaim`;
     let reclaimGuard;
     const releaseReclaimGuard = async () => {
@@ -90,17 +90,9 @@ export async function acquireSidecarLock(options, context) {
     const withinDenialBudget = () => ++transientDenials <= maxTransientLockDenials;
     const waitForRetry = async () => {
         admission.release();
-        const elapsed = Date.now() - startedAt;
-        if ((timeoutMs !== undefined &&
-            timeoutMs !== Number.POSITIVE_INFINITY &&
-            elapsed >= timeoutMs) ||
-            (retry.retries !== undefined && attempt >= retry.retries)) {
+        const delay = sidecarLockRetryDelay(retry, timeoutMs === Number.POSITIVE_INFINITY ? undefined : timeoutMs, performance.now() - startedAt, attempt);
+        if (delay === undefined)
             throw sidecarLockTimeout(lockPath, normalizedTargetPath);
-        }
-        const remaining = timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY
-            ? Number.POSITIVE_INFINITY
-            : Math.max(0, timeoutMs - elapsed);
-        const delay = Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
         attempt += 1;
         await sleep(delay);
     };
@@ -123,29 +115,16 @@ export async function acquireSidecarLock(options, context) {
         while (true) {
             if (!admission.owns) {
                 held = context.held.get(normalizedTargetPath);
-                if (held &&
-                    requestedReentrantOwner !== undefined &&
-                    held.reentrantOwner !== undefined &&
-                    requestedReentrantOwner === held.reentrantOwner) {
+                if (isReentrant(held)) {
                     if (held.releasePromise) {
                         await held.releasePromise.catch(() => undefined);
                         held = context.held.get(normalizedTargetPath);
                     }
-                    if (held &&
-                        requestedReentrantOwner !== undefined &&
-                        held.reentrantOwner !== undefined &&
-                        requestedReentrantOwner === held.reentrantOwner) {
-                        const lifecycle = context.ensureExitCleanupRegistered();
-                        context.assertRetainOnExitSupported(retainOnExit);
-                        if (context.held.get(normalizedTargetPath) !== held || held.releasePromise) {
-                            continue;
-                        }
-                        held.refCount = (held.refCount ?? 1) + 1;
-                        if (retainOnExit === true)
-                            held.retainOnExit = true;
-                        const returnedHandle = context.handleForHeldLock(normalizedTargetPath, held);
-                        context.armExitCleanup(lifecycle);
-                        return returnedHandle;
+                    if (isReentrant(held)) {
+                        const reused = reuseHeldLock(held);
+                        if (reused)
+                            return reused;
+                        continue;
                     }
                 }
                 if (context.admissions.has(normalizedTargetPath)) {
@@ -378,8 +357,9 @@ export async function acquireSidecarLock(options, context) {
                 try {
                     if (createdHeld)
                         stopSidecarLockMonitoring(createdHeld);
+                    let failedSnapshot = createdSnapshot;
                     if (handle) {
-                        const failedSnapshot = createdSnapshot ?? { payload: null };
+                        failedSnapshot ??= { payload: null };
                         try {
                             failedSnapshot.stat = fsSync.fstatSync(handle.fd);
                         }
@@ -391,14 +371,10 @@ export async function acquireSidecarLock(options, context) {
                             context.held.delete(normalizedTargetPath);
                         }
                         await handle.close().catch(() => undefined);
-                        // Root records use the creator receipt; partial raw writes use fd identity.
-                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                            lockRoot,
-                            parsePayload: conditionalSidecarLockParser(parserState, admission, () => admission.hasToken() && !context.held.has(normalizedTargetPath)),
-                        });
                     }
-                    else if (createdSnapshot) {
-                        await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
+                    // Root records use the creator receipt; partial raw writes use fd identity.
+                    if (failedSnapshot) {
+                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
                             lockRoot,
                             parsePayload: conditionalSidecarLockParser(parserState, admission, () => admission.hasToken() && !context.held.has(normalizedTargetPath)),
                         });

package/dist/sidecar-lock-admission-context.d.ts

@@ -16,4 +16,3 @@ export declare function createSidecarAdmissionController(ancestry: SidecarAdmiss
     run<T>(callback: () => T): T;
 };
 export {};
-//# sourceMappingURL=sidecar-lock-admission-context.d.ts.map

package/dist/sidecar-lock-admission-parser.d.ts

@@ -40,4 +40,3 @@ export declare function observeHeldSidecarParser(params: {
     isTransientDenial(error: unknown): boolean;
 }): Promise<HeldSidecarParserObservation>;
 export {};
-//# sourceMappingURL=sidecar-lock-admission-parser.d.ts.map

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

@@ -2,11 +2,10 @@ import type { NativeFileHandle } from "./native-operations.js";
 import type { Root } from "./root-impl.js";
 import type { SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
 import type { SidecarLockHandle } from "./sidecar-lock-types.js";
-type SidecarFileHandle = Pick<NativeFileHandle, "fd" | "close" | "stat" | "writeFile">;
 export type HeldSidecarLock = {
     refCount: number;
     reentrantOwner?: string;
-    handle: SidecarFileHandle;
+    handle: NativeFileHandle;
     lockPath: string;
     snapshot: SidecarLockSnapshot;
     acquiredAt: number;
@@ -30,6 +29,3 @@ export type SidecarLockAcquisitionContext = {
     assertRetainOnExitSupported(retainOnExit: boolean | undefined): void;
     handleForHeldLock(normalizedTargetPath: string, held: HeldSidecarLock): SidecarLockHandle;
 };
-export declare function sidecarLockTimeout(lockPath: string, normalizedTargetPath: string): Error;
-export {};
-//# sourceMappingURL=sidecar-lock-admission.d.ts.map

package/dist/sidecar-lock-admission.js

@@ -1,7 +1 @@
-export function sidecarLockTimeout(lockPath, normalizedTargetPath) {
-    return Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-        code: "file_lock_timeout",
-        lockPath,
-        normalizedTargetPath,
-    });
-}
+export {};

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

@@ -24,4 +24,3 @@ export declare function createHeldSidecarLockHandle(params: {
         retry?: boolean;
     }) => Promise<unknown>;
 }): SidecarLockHandle;
-//# sourceMappingURL=sidecar-lock-handle.d.ts.map

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

@@ -4,6 +4,10 @@ export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefin
 export declare function validateSidecarLockStaleMs(staleMs: number | undefined): void;
 export declare function validateSidecarLockCompromiseCheckIntervalMs(intervalMs: number | undefined): void;
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
+export declare function sidecarLockTimeout(lockPath: string, normalizedTargetPath: string): Error;
+export declare function sidecarLockStale(lockPath: string, normalizedTargetPath: string): Error;
+/** Undefined means the deadline or retry count is exhausted. */
+export declare function sidecarLockRetryDelay(retry: SidecarLockRetryOptions, timeoutMs: number | undefined, elapsed: number, attempt: number): number | undefined;
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;
 export declare function sidecarLockPayloadCreatedAtMs(payload: unknown): number | null;
@@ -13,4 +17,3 @@ export declare function defaultSidecarLockShouldReclaim(params: {
     staleMs: number;
     nowMs: number;
 }): Promise<boolean>;
-//# sourceMappingURL=sidecar-lock-policy.d.ts.map

package/dist/sidecar-lock-policy.js

@@ -55,6 +55,29 @@ export function computeSidecarLockDelayMs(retry, attempt) {
     const jitter = retry.randomize ? 1 + Math.random() : 1;
     return Math.min(maxTimeout, Math.round(base * jitter));
 }
+export function sidecarLockTimeout(lockPath, normalizedTargetPath) {
+    return Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+        code: "file_lock_timeout",
+        lockPath,
+        normalizedTargetPath,
+    });
+}
+export function sidecarLockStale(lockPath, normalizedTargetPath) {
+    return Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+        code: "file_lock_stale",
+        lockPath,
+        normalizedTargetPath,
+    });
+}
+/** Undefined means the deadline or retry count is exhausted. */
+export function sidecarLockRetryDelay(retry, timeoutMs, elapsed, attempt) {
+    if ((timeoutMs !== undefined && elapsed >= timeoutMs) ||
+        (retry.retries !== undefined && attempt >= retry.retries))
+        return undefined;
+    const remaining = timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY
+        ? Number.POSITIVE_INFINITY : Math.max(0, timeoutMs - elapsed);
+    return Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
+}
 // 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

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

@@ -65,4 +65,3 @@ export declare function removeStaleSidecarLockIfAllowed(params: {
     assertGuardHeld?: () => Promise<void>;
 }): Promise<"removed" | "changed" | "not-approved">;
 export {};
-//# sourceMappingURL=sidecar-lock-reclaim.d.ts.map

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

@@ -0,0 +1,13 @@
+type CleanupRegistration = {
+    event: "exit" | "beforeExit";
+    registered: symbol;
+    registering: symbol;
+    handler: symbol;
+    retainAware?: symbol;
+    reentryError(): Error;
+};
+/** Preserve the legacy, first-registration-wins protocol across package copies. */
+export declare function ensureSidecarLockCleanupRegistered<T extends true | {
+    armed: boolean;
+}>(keys: CleanupRegistration, cleanup: () => void, marker: T): T;
+export {};

package/dist/sidecar-lock-registration.js

@@ -0,0 +1,47 @@
+/** Preserve the legacy, first-registration-wins protocol across package copies. */
+export function ensureSidecarLockCleanupRegistered(keys, cleanup, marker) {
+    const state = globalThis;
+    if (state[keys.registered])
+        return state[keys.registered];
+    // process.on emits newListener synchronously; reentry cannot wait for it.
+    if (state[keys.registering])
+        throw keys.reentryError();
+    const registration = {};
+    const commit = () => {
+        state[keys.handler] = cleanup;
+        if (keys.retainAware)
+            state[keys.retainAware] = true;
+        state[keys.registered] = marker;
+    };
+    state[keys.registering] = registration;
+    try {
+        process.on(keys.event, cleanup);
+        commit();
+        return marker;
+    }
+    catch (error) {
+        if (process.listeners(keys.event).includes(cleanup)) {
+            try {
+                process.off(keys.event, cleanup);
+            }
+            catch {
+                // Reconcile the marker with the actual listener below.
+            }
+        }
+        if (process.listeners(keys.event).includes(cleanup)) {
+            commit();
+        }
+        else {
+            if (state[keys.handler] === cleanup)
+                delete state[keys.handler];
+            // Only the before-exit lifecycle has an individually owned marker.
+            if (marker !== true && state[keys.registered] === marker)
+                delete state[keys.registered];
+        }
+        throw error;
+    }
+    finally {
+        if (state[keys.registering] === registration)
+            delete state[keys.registering];
+    }
+}

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

@@ -1,3 +1,2 @@
 import type { OpenResult, Root } from "./root-impl.js";
 export declare function openSidecarRoot(lockRoot: Root, relative: string, discardObservation?: "unlinked" | "changed", onOpenFailure?: (error: unknown) => void): Promise<OpenResult | null>;
-//# sourceMappingURL=sidecar-lock-root.d.ts.map

package/dist/sidecar-lock-stale-admission.d.ts

@@ -36,4 +36,3 @@ export declare function handleStaleSidecarAdmission<TPayload extends Record<stri
     waitForRetry(): Promise<void>;
 }): Promise<void>;
 export {};
-//# sourceMappingURL=sidecar-lock-stale-admission.d.ts.map

package/dist/sidecar-lock-stale-admission.js

@@ -1,4 +1,4 @@
-import { defaultSidecarLockShouldReclaim, isTransientLockFileDenial } from "./sidecar-lock-policy.js";
+import { defaultSidecarLockShouldReclaim, isTransientLockFileDenial, sidecarLockStale } from "./sidecar-lock-policy.js";
 import { readSidecarLockRawSnapshot, removeStaleSidecarLockIfAllowed, sidecarLockSnapshotStillPresent, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
 import { observeSidecarLockParser, parseSidecarLockSnapshotUnderAdmission, scopedSidecarLockParser, } from "./sidecar-lock-admission-parser.js";
 /** Handle one historical EEXIST attempt while its canonical admission is held. */
@@ -224,9 +224,5 @@ export async function handleStaleSidecarAdmission(params) {
         }
         await params.releaseReclaimGuard();
     }
-    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-        code: "file_lock_stale",
-        lockPath,
-        normalizedTargetPath,
-    });
+    throw sidecarLockStale(lockPath, normalizedTargetPath);
 }

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

@@ -5,4 +5,3 @@ export declare function resolveSidecarLockPaths(targetPath: string, explicitLock
     lockPath: string;
     normalizedTargetPath: string;
 }>;
-//# sourceMappingURL=sidecar-lock-target.d.ts.map

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

@@ -12,27 +12,35 @@ export type SidecarLockCompromisedInfo = {
     lockPath: string;
     normalizedTargetPath: string;
 };
-export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = {
-    targetPath: string;
+export type SidecarLockOptionFields<T> = {
+    [K in keyof T]: T[K];
+};
+export type SidecarLockCommonAcquireOptions = {
     lockPath?: string;
-    staleMs: number;
     timeoutMs?: number;
     retry?: SidecarLockRetryOptions;
     staleRecovery?: SidecarLockStaleRecovery;
     reentrantOwner?: string;
+    parsePayload?: (raw: string) => unknown;
+    lockRoot?: Root;
+    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+    compromiseCheckIntervalMs?: number;
+};
+export type SidecarLockReclaimParams<Held extends boolean = boolean> = {
+    lockPath: string;
+    normalizedTargetPath: string;
+    payload: unknown;
+    staleMs: number;
+    nowMs: number;
+    heldByThisProcess: Held;
+};
+export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = SidecarLockOptionFields<SidecarLockCommonAcquireOptions & {
+    targetPath: string;
+    staleMs: number;
     payload: () => TPayload | Promise<TPayload>;
-    shouldReclaim?: (params: {
-        lockPath: string;
-        normalizedTargetPath: string;
-        payload: unknown;
-        staleMs: number;
-        nowMs: number;
-        heldByThisProcess: boolean;
-    }) => boolean | Promise<boolean>;
+    shouldReclaim?: (params: SidecarLockReclaimParams) => boolean | Promise<boolean>;
     shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
     metadata?: Record<string, unknown>;
-    parsePayload?: (raw: string) => unknown;
-    lockRoot?: Root;
     /**
      * Keep the lock file when the process exits naturally. Default `false`:
      * process-exit handlers release held locks. Set only for deliberately
@@ -40,9 +48,7 @@ export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>>
      * liveness is governed by the caller's own stale policy.
      */
     retainOnExit?: boolean;
-    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
-    compromiseCheckIntervalMs?: number;
-};
+}>;
 export type SidecarLockHandle = {
     lockPath: string;
     normalizedTargetPath: string;
@@ -60,4 +66,3 @@ export type SidecarLockHeldEntry = {
 export type WithSidecarLockOptions<TPayload extends Record<string, unknown>> = Omit<SidecarLockAcquireOptions<TPayload>, "targetPath"> & {
     managerKey?: string;
 };
-//# sourceMappingURL=sidecar-lock-types.d.ts.map

package/dist/sidecar-lock.d.ts

@@ -11,4 +11,3 @@ export declare function createSidecarLockManager(key: string): {
     heldEntries: () => SidecarLockHeldEntry[];
 };
 export declare function withSidecarLock<T, TPayload extends Record<string, unknown>>(targetPath: string, options: WithSidecarLockOptions<TPayload>, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=sidecar-lock.d.ts.map