@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/sidecar-lock-acquire.js

@@ -5,16 +5,16 @@ 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";
 import { sidecarExclusiveCreate } from "./root-create-input.js";
+import { stopSidecarLockMonitoring } from "./sidecar-lock-handle.js";
 export async function acquireSidecarLock(options, context) {
     const admissionAncestry = captureSidecarAdmissionAncestry();
     const retainOnExit = options.retainOnExit;
@@ -33,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) {
@@ -46,23 +60,10 @@ 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)
@@ -89,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, Date.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);
     };
@@ -122,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)) {
@@ -353,8 +333,7 @@ export async function acquireSidecarLock(options, context) {
                             .catch(() => false)
                             .then((stillHeld) => {
                             if (!stillHeld && candidateHeld.compromiseTimer) {
-                                clearInterval(candidateHeld.compromiseTimer);
-                                candidateHeld.compromiseTimer = undefined;
+                                stopSidecarLockMonitoring(candidateHeld);
                                 Reflect.apply(compromisedCallback, options, [{ lockPath, normalizedTargetPath }]);
                             }
                         })
@@ -376,10 +355,8 @@ export async function acquireSidecarLock(options, context) {
             }
             catch (err) {
                 try {
-                    if (createdHeld?.compromiseTimer) {
-                        clearInterval(createdHeld.compromiseTimer);
-                        createdHeld.compromiseTimer = undefined;
-                    }
+                    if (createdHeld)
+                        stopSidecarLockMonitoring(createdHeld);
                     if (handle) {
                         const failedSnapshot = createdSnapshot ?? { payload: null };
                         try {

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

@@ -1,6 +1,9 @@
 import type { Root } from "./root-impl.js";
 import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
 import type { SidecarLockHandle } from "./sidecar-lock-types.js";
+export declare function stopSidecarLockMonitoring(held: {
+    compromiseTimer?: NodeJS.Timeout;
+}): void;
 export declare function createSidecarLockHandle(params: {
     lockPath: string;
     normalizedTargetPath: string;
@@ -21,4 +24,3 @@ export declare function createHeldSidecarLockHandle(params: {
         retry?: boolean;
     }) => Promise<unknown>;
 }): SidecarLockHandle;
-//# sourceMappingURL=sidecar-lock-handle.d.ts.map

package/dist/sidecar-lock-handle.js

@@ -1,4 +1,10 @@
 import { sidecarLockSnapshotStillPresent, } from "./sidecar-lock-reclaim.js";
+export function stopSidecarLockMonitoring(held) {
+    const timer = held.compromiseTimer;
+    held.compromiseTimer = undefined;
+    if (timer)
+        clearInterval(timer);
+}
 export function createSidecarLockHandle(params) {
     let released = false;
     let releasePromise;

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

@@ -4,6 +4,9 @@ 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;
+/** 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 +16,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,22 @@ 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,
+    });
+}
+/** 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

@@ -39,7 +39,7 @@ export declare function readSidecarLockRawSnapshotSync(lockPath: string, options
     onOpenFailure?: (error: unknown) => void;
 }): SidecarLockRawSnapshot | null;
 export declare function removeSidecarLockIfUnchangedSync(lockPath: string, observed: SidecarLockSnapshot, assertAuthorized?: () => void): boolean;
-export declare function sidecarLockSnapshotMatches(current: SidecarLockSnapshot, observed: SidecarLockSnapshot): boolean;
+export declare function sidecarLockSnapshotMatches(current: SidecarLockRawSnapshot | SidecarLockSnapshot, observed: SidecarLockSnapshot): boolean;
 export declare function removeSidecarLockIfUnchanged(lockPath: string, observed: SidecarLockSnapshot | null, options?: {
     lockRoot?: Root;
     parsePayload?: (raw: string) => unknown;
@@ -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-reclaim.js

@@ -71,6 +71,12 @@ function missingSnapshotPath(error) {
 export async function readSidecarLockSnapshot(lockPath, options = {}) {
     return parseSidecarLockSnapshot(await readSidecarLockRawSnapshot(lockPath, options), options.parsePayload);
 }
+async function readSidecarLockComparisonSnapshot(lockPath, options) {
+    const snapshot = await readSidecarLockRawSnapshot(lockPath, options);
+    const parsePayload = options?.parsePayload;
+    // Ownership uses raw bytes and identity, but custom parsers retain their effects.
+    return parsePayload ? parseSidecarLockSnapshot(snapshot, parsePayload) : snapshot;
+}
 export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
     let handle;
     try {
@@ -197,7 +203,6 @@ export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
         return {
             raw,
             stat: after,
-            ownershipToken: readSidecarLockOwnershipToken(raw),
         };
     }
     finally {
@@ -207,7 +212,7 @@ export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
 }
 export function removeSidecarLockIfUnchangedSync(lockPath, observed, assertAuthorized) {
     assertAuthorized?.();
-    const current = readSidecarLockSnapshotSync(lockPath);
+    const current = readSidecarLockRawSnapshotSync(lockPath);
     assertAuthorized?.();
     if (!current || !sidecarLockSnapshotMatches(current, observed))
         return false;
@@ -219,10 +224,8 @@ export function sidecarLockSnapshotMatches(current, observed) {
     if (observed.ownershipToken !== undefined) {
         return (current.stat?.isFile() === true &&
             current.raw !== undefined &&
-            observed.raw !== undefined &&
-            readSidecarLockOwnershipToken(current.raw) === observed.ownershipToken &&
-            readSidecarLockOwnershipToken(observed.raw) === observed.ownershipToken &&
-            current.raw === observed.raw);
+            current.raw === observed.raw &&
+            readSidecarLockOwnershipToken(current.raw) === observed.ownershipToken);
     }
     if (observed.stat &&
         current.stat &&
@@ -235,7 +238,7 @@ export function sidecarLockSnapshotMatches(current, observed) {
     return observed.stat !== undefined && current.stat !== undefined;
 }
 export async function removeSidecarLockIfUnchanged(lockPath, observed, options = {}) {
-    const current = await readSidecarLockSnapshot(lockPath, {
+    const current = await readSidecarLockComparisonSnapshot(lockPath, {
         ...options,
         allowDescriptorIdentityDrift: observed?.ownershipToken !== undefined,
     });
@@ -251,7 +254,7 @@ export async function removeSidecarLockIfUnchanged(lockPath, observed, options =
     return true;
 }
 export async function sidecarLockSnapshotStillPresent(lockPath, observed, options = {}) {
-    const current = await readSidecarLockSnapshot(lockPath, {
+    const current = await readSidecarLockComparisonSnapshot(lockPath, {
         ...options,
         allowDescriptorIdentityDrift: observed?.ownershipToken !== undefined,
     });

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

@@ -60,4 +60,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

package/dist/sidecar-lock.js

@@ -3,8 +3,9 @@ import { FsSafeError } from "./errors.js";
 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 { createHeldSidecarLockHandle, stopSidecarLockMonitoring } from "./sidecar-lock-handle.js";
 import { createSuppressedError } from "./suppressed-error.js";
+import { ensureSidecarLockCleanupRegistered } from "./sidecar-lock-registration.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");
@@ -101,6 +102,7 @@ function releaseAllReclaimGuardsSync(state) {
 }
 function releaseAllLocksSync(state, options) {
     for (const [normalizedTargetPath, held] of state.held) {
+        stopSidecarLockMonitoring(held);
         void held.handle.close().catch(() => undefined);
         try {
             const retained = options?.preserveRetained === true && held.retainOnExit;
@@ -117,51 +119,19 @@ function releaseAllLocksSync(state, options) {
     releaseAllReclaimGuardsSync(state);
 }
 function ensureGlobalExitCleanupRegistered() {
-    const globalWithCleanup = globalThis;
-    if (globalWithCleanup[GLOBAL_CLEANUP_KEY])
-        return;
-    if (globalWithCleanup[GLOBAL_CLEANUP_REGISTRATION_KEY]) {
-        throw new FsSafeError("helper-unavailable", "sidecar lock exit cleanup registration is already in progress");
-    }
-    const registration = {};
     const cleanup = () => {
         for (const state of getGlobalManagers().values()) {
             releaseAllLocksSync(state, { preserveRetained: true });
         }
     };
-    globalWithCleanup[GLOBAL_CLEANUP_REGISTRATION_KEY] = registration;
-    try {
-        process.on("exit", cleanup);
-        globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
-        globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] = true;
-        globalWithCleanup[GLOBAL_CLEANUP_KEY] = true;
-    }
-    catch (error) {
-        if (process.listeners("exit").includes(cleanup)) {
-            try {
-                process.off("exit", cleanup);
-            }
-            catch {
-                // Reconcile the marker with the actual listener below.
-            }
-        }
-        if (process.listeners("exit").includes(cleanup)) {
-            globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
-            globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] = true;
-            globalWithCleanup[GLOBAL_CLEANUP_KEY] = true;
-        }
-        else {
-            if (globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] === cleanup) {
-                delete globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY];
-            }
-        }
-        throw error;
-    }
-    finally {
-        if (globalWithCleanup[GLOBAL_CLEANUP_REGISTRATION_KEY] === registration) {
-            delete globalWithCleanup[GLOBAL_CLEANUP_REGISTRATION_KEY];
-        }
-    }
+    ensureSidecarLockCleanupRegistered({
+        event: "exit",
+        registered: GLOBAL_CLEANUP_KEY,
+        registering: GLOBAL_CLEANUP_REGISTRATION_KEY,
+        handler: GLOBAL_CLEANUP_HANDLER_KEY,
+        retainAware: GLOBAL_RETAIN_AWARE_KEY,
+        reentryError: () => new FsSafeError("helper-unavailable", "sidecar lock exit cleanup registration is already in progress"),
+    }, cleanup, true);
 }
 /** True when a retain-unaware package copy registered the process-exit handlers first. */
 export function exitCleanupCannotRetain() {
@@ -169,16 +139,8 @@ export function exitCleanupCannotRetain() {
     return globalWithCleanup[GLOBAL_CLEANUP_KEY] === true && globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] !== true;
 }
 function ensureGlobalBeforeExitCleanupRegistered() {
-    const globalWithCleanup = globalThis;
-    if (globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY]) {
-        return globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY];
-    }
-    if (globalWithCleanup[GLOBAL_BEFORE_EXIT_REGISTRATION_KEY]) {
-        throw new FsSafeError("helper-unavailable", "sidecar lock before-exit cleanup registration is already in progress");
-    }
     // Independent of the exit registration, which an older package copy may own.
     const lifecycle = { armed: false };
-    const registration = {};
     const cleanup = () => {
         if (!lifecycle.armed)
             return;
@@ -192,41 +154,13 @@ function ensureGlobalBeforeExitCleanupRegistered() {
             }
         }
     };
-    globalWithCleanup[GLOBAL_BEFORE_EXIT_REGISTRATION_KEY] = registration;
-    try {
-        process.on("beforeExit", cleanup);
-        globalWithCleanup[GLOBAL_BEFORE_EXIT_HANDLER_KEY] = cleanup;
-        globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] = lifecycle;
-        return lifecycle;
-    }
-    catch (error) {
-        if (process.listeners("beforeExit").includes(cleanup)) {
-            try {
-                process.off("beforeExit", cleanup);
-            }
-            catch {
-                // Reconcile the marker with the actual listener below.
-            }
-        }
-        if (process.listeners("beforeExit").includes(cleanup)) {
-            globalWithCleanup[GLOBAL_BEFORE_EXIT_HANDLER_KEY] = cleanup;
-            globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] = lifecycle;
-        }
-        else {
-            if (globalWithCleanup[GLOBAL_BEFORE_EXIT_HANDLER_KEY] === cleanup) {
-                delete globalWithCleanup[GLOBAL_BEFORE_EXIT_HANDLER_KEY];
-            }
-            if (globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] === lifecycle) {
-                delete globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY];
-            }
-        }
-        throw error;
-    }
-    finally {
-        if (globalWithCleanup[GLOBAL_BEFORE_EXIT_REGISTRATION_KEY] === registration) {
-            delete globalWithCleanup[GLOBAL_BEFORE_EXIT_REGISTRATION_KEY];
-        }
-    }
+    return ensureSidecarLockCleanupRegistered({
+        event: "beforeExit",
+        registered: GLOBAL_BEFORE_EXIT_KEY,
+        registering: GLOBAL_BEFORE_EXIT_REGISTRATION_KEY,
+        handler: GLOBAL_BEFORE_EXIT_HANDLER_KEY,
+        reentryError: () => new FsSafeError("helper-unavailable", "sidecar lock before-exit cleanup registration is already in progress"),
+    }, cleanup, lifecycle);
 }
 async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
     const current = state.held.get(normalizedTargetPath);
@@ -257,10 +191,7 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
         if (state.held.get(normalizedTargetPath) === held) {
             state.held.delete(normalizedTargetPath);
         }
-        if (held.compromiseTimer) {
-            clearInterval(held.compromiseTimer);
-            held.compromiseTimer = undefined;
-        }
+        stopSidecarLockMonitoring(held);
     })();
     try {
         await held.releasePromise;

package/dist/staged-directory.d.ts

@@ -1,4 +1,4 @@
-import { type BigIntStats } from "node:fs";
+import { type BigIntStats, type Stats } from "node:fs";
 import type { DirectoryReceipt } from "./directory-durability.js";
 import type { FileIdentityStat } from "./file-identity.js";
 import type { NativeBinding } from "./native-binding.js";
@@ -21,8 +21,7 @@ export declare function assertStagedDirectoryCurrent(receipt: StagedDirectorySna
 export declare function describePolicyStagedDirectory(fd: number, pathname: string, binding?: NativeBinding): PolicyStagedDirectory;
 export declare function assertPolicyStagedDirectoryCurrent(captured: PolicyStagedDirectory): BigIntStats;
 export declare function refreshPolicyStagedDirectoryObservation(captured: PolicyStagedDirectory): MutationDirectoryObservation;
-export declare function openStagedDirectory(directory: string | DirectoryReceipt): {
+export declare function openStagedDirectory(directory: string | DirectoryReceipt<Stats | BigIntStats>): {
     fd: number;
     receipt: StagedDirectorySnapshot;
 };
-//# sourceMappingURL=staged-directory.d.ts.map

package/dist/staged-file-settlement.d.ts

@@ -14,4 +14,3 @@ export declare function settleStagedFile(params: {
     cleanup: () => Promise<StagedFileCleanupReceipt["status"]>;
     close: readonly (() => Promise<void> | void)[];
 }): Promise<void>;
-//# sourceMappingURL=staged-file-settlement.d.ts.map

package/dist/staged-file-types.d.ts

@@ -53,4 +53,3 @@ export interface StagedFile extends AsyncDisposable {
     }): Promise<PublishedFileReceipt>;
     cleanup(): Promise<StagedFileCleanupReceipt>;
 }
-//# sourceMappingURL=staged-file-types.d.ts.map

package/dist/standalone-publication-path.d.ts

@@ -1,2 +1 @@
 export declare function admitStandalonePublicationPath(value: string, message?: string): string;
-//# sourceMappingURL=standalone-publication-path.d.ts.map

package/dist/stat-observation.d.ts

@@ -8,4 +8,3 @@ export type StatObservationReceipt = {
 export declare function inspectStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected?: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): StatObservationReceipt;
 /** Revalidate an exact identity without allocating a receipt that the caller will discard. */
 export declare function assertStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): Stats | BigIntStats;
-//# sourceMappingURL=stat-observation.d.ts.map

package/dist/store.d.ts

@@ -1,4 +1,3 @@
 export { fileStore, fileStoreSync, type FileStore, type FileStoreOptions, type FileStorePruneOptions, type FileStoreReadOptions, type FileStoreSync, type FileStoreWriteOptions, } from "./file-store.js";
 export { jsonStore, type JsonStore, type JsonFileStoreOptions, type JsonStoreLockOptions, type JsonStoreOptions, } from "./json-store.js";
 export { ackJsonDurableQueueEntry, ensureJsonDurableQueueDirs, jsonDurableQueueEntryExists, loadJsonDurableQueueEntry, loadPendingJsonDurableQueueEntries, moveJsonDurableQueueEntryToFailed, readJsonDurableQueueEntry, resolveJsonDurableQueueEntryPaths, unlinkBestEffort, writeJsonDurableQueueEntry, type JsonDurableQueueEntryPaths, type JsonDurableQueueLoadOptions, type JsonDurableQueueReadResult, } from "./json-durable-queue.js";
-//# sourceMappingURL=store.d.ts.map

package/dist/strict-file-identity.d.ts

@@ -1,6 +1,5 @@
 import type { BigIntStats } from "node:fs";
 type ExactFileIdentity = Pick<BigIntStats, "dev" | "ino">;
 export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => T | Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
-export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform): T;
+export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform, mismatch?: () => Error): T;
 export {};
-//# sourceMappingURL=strict-file-identity.d.ts.map