@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/dist/sidecar-lock-root.js

@@ -61,7 +61,8 @@ export async function openSidecarRoot(lockRoot, relative, discardObservation, on
             }
             catch (probeError) {
                 if (!(probeError instanceof FsSafeError && probeError.code === "not-found") &&
-                    !probe.has(probeError, `stat-leaf-missing:${expectedRealPath}`))
+                    !probe.has(probeError, `stat-leaf-missing:${expectedRealPath}`) &&
+                    !probe.has(probeError, `stat-leaf-changed:${expectedRealPath}`))
                     throw probeError;
             }
             for (const { dir, stat } of parents)

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-stale-admission.d.ts

@@ -0,0 +1,34 @@
+import { type SidecarReclaimGuard } from "./sidecar-lock-reclaim.js";
+import { type SidecarLockParserState, type SidecarAdmissionRunner } from "./sidecar-lock-admission-parser.js";
+import type { Root } from "./root-impl.js";
+import type { SidecarLockAcquireOptions } from "./sidecar-lock-types.js";
+type StaleOptions = Pick<SidecarLockAcquireOptions<Record<string, unknown>>, "shouldReclaim" | "shouldRemoveStaleLock" | "staleRecovery">;
+export type SidecarLockStaleOptionsState = {
+    shouldReclaimObserved?: boolean;
+    shouldReclaim?: StaleOptions["shouldReclaim"];
+    shouldRemoveObserved?: boolean;
+    shouldRemove?: StaleOptions["shouldRemoveStaleLock"];
+    staleRecoveryObserved?: boolean;
+    staleRecovery?: StaleOptions["staleRecovery"];
+};
+/** Handle one historical EEXIST attempt while its canonical admission is held. */
+export declare function handleStaleSidecarAdmission<TPayload extends Record<string, unknown>>(params: {
+    admission: SidecarAdmissionRunner;
+    assertToken(): void;
+    currentHeld(): unknown;
+    lockPath: string;
+    lockRoot?: Root;
+    normalizedTargetPath: string;
+    options: SidecarLockAcquireOptions<TPayload>;
+    parserState: SidecarLockParserState;
+    reclaimGuardPath: string;
+    reclaimGuards: Set<string>;
+    setReclaimGuard(guard: SidecarReclaimGuard): void;
+    releaseReclaimGuard(): Promise<void>;
+    staleOptionsState: SidecarLockStaleOptionsState;
+    staleMs: number;
+    withinDenialBudget(): boolean;
+    retryOrRethrowDenial(error: unknown): Promise<void>;
+    waitForRetry(): Promise<void>;
+}): Promise<void>;
+export {};

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-stale-admission.js

@@ -0,0 +1,228 @@
+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. */
+export async function handleStaleSidecarAdmission(params) {
+    const { admission, lockPath, normalizedTargetPath, options } = params;
+    const holderChanged = {};
+    const assertUnheld = () => {
+        params.assertToken();
+        if (params.currentHeld())
+            throw holderChanged;
+    };
+    const retryHolderChange = async (error) => {
+        if (error !== holderChanged)
+            return false;
+        await params.waitForRetry();
+        return true;
+    };
+    const retryChangedBoundary = async () => {
+        try {
+            assertUnheld();
+            return false;
+        }
+        catch (error) {
+            if (await retryHolderChange(error))
+                return true;
+            throw error;
+        }
+    };
+    let rawSnapshot;
+    let lockFileOpenDenied = false;
+    try {
+        rawSnapshot = await admission.run(async () => await readSidecarLockRawSnapshot(lockPath, {
+            lockRoot: params.lockRoot,
+            rejectNonFile: true,
+            discardObservation: "changed",
+            onOpenFailure: (error) => {
+                lockFileOpenDenied = isTransientLockFileDenial(error, lockPath);
+            },
+        }));
+    }
+    catch (error) {
+        if (await retryChangedBoundary())
+            return;
+        if (!lockFileOpenDenied || !params.withinDenialBudget())
+            throw error;
+        await params.retryOrRethrowDenial(error);
+        return;
+    }
+    params.assertToken();
+    if (params.currentHeld()) {
+        await params.waitForRetry();
+        return;
+    }
+    let snapshot;
+    try {
+        observeSidecarLockParser(params.parserState, admission, () => options.parsePayload, assertUnheld);
+        snapshot = parseSidecarLockSnapshotUnderAdmission(rawSnapshot, params.parserState, admission, assertUnheld);
+        assertUnheld();
+    }
+    catch (error) {
+        if (await retryHolderChange(error))
+            return;
+        if (await retryChangedBoundary())
+            return;
+        throw error;
+    }
+    if (!snapshot) {
+        await params.waitForRetry();
+        return;
+    }
+    const staleOptions = params.staleOptionsState;
+    try {
+        if (!staleOptions.shouldReclaimObserved) {
+            assertUnheld();
+            staleOptions.shouldReclaim = admission.run(() => options.shouldReclaim);
+            staleOptions.shouldReclaimObserved = true;
+            assertUnheld();
+        }
+        if (!staleOptions.shouldRemoveObserved) {
+            assertUnheld();
+            staleOptions.shouldRemove = admission.run(() => options.shouldRemoveStaleLock);
+            staleOptions.shouldRemoveObserved = true;
+            assertUnheld();
+        }
+        if (!staleOptions.staleRecoveryObserved) {
+            assertUnheld();
+            staleOptions.staleRecovery = admission.run(() => options.staleRecovery);
+            staleOptions.staleRecoveryObserved = true;
+            assertUnheld();
+        }
+    }
+    catch (error) {
+        if (await retryHolderChange(error))
+            return;
+        if (await retryChangedBoundary())
+            return;
+        throw error;
+    }
+    const shouldReclaim = staleOptions.shouldReclaim ?? defaultSidecarLockShouldReclaim;
+    let reclaim;
+    try {
+        reclaim = await admission.run(async () => {
+            assertUnheld();
+            try {
+                return await Reflect.apply(shouldReclaim, undefined, [{
+                        lockPath,
+                        normalizedTargetPath,
+                        payload: snapshot.payload ?? null,
+                        staleMs: params.staleMs,
+                        nowMs: Date.now(),
+                        heldByThisProcess: false,
+                    }]);
+            }
+            finally {
+                assertUnheld();
+            }
+        });
+        assertUnheld();
+    }
+    catch (error) {
+        if (await retryHolderChange(error))
+            return;
+        if (await retryChangedBoundary())
+            return;
+        throw error;
+    }
+    if (!reclaim) {
+        await params.waitForRetry();
+        return;
+    }
+    let stillPresent;
+    try {
+        stillPresent = await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
+            lockRoot: params.lockRoot,
+            parsePayload: scopedSidecarLockParser(params.parserState, admission, assertUnheld),
+        });
+        assertUnheld();
+    }
+    catch (error) {
+        if (await retryHolderChange(error))
+            return;
+        if (await retryChangedBoundary())
+            return;
+        throw error;
+    }
+    if (!stillPresent) {
+        await params.waitForRetry();
+        return;
+    }
+    if ((staleOptions.staleRecovery ?? "fail-closed") === "remove-if-unchanged") {
+        const acquiredGuard = await admission.run(() => tryAcquireSidecarReclaimGuard(params.reclaimGuards, params.reclaimGuardPath, params.lockRoot));
+        if (acquiredGuard)
+            params.setReclaimGuard(acquiredGuard);
+        params.assertToken();
+        if (params.currentHeld()) {
+            if (acquiredGuard) {
+                await params.releaseReclaimGuard();
+            }
+            await params.waitForRetry();
+            return;
+        }
+        if (!acquiredGuard) {
+            await params.waitForRetry();
+            return;
+        }
+        const shouldRemove = staleOptions.shouldRemove;
+        const assertRemovalAuthorized = assertUnheld;
+        const guardedShouldRemove = shouldRemove && function (staleSnapshot) {
+            return admission.run(async () => {
+                assertRemovalAuthorized();
+                try {
+                    return await Reflect.apply(shouldRemove, this, [staleSnapshot]);
+                }
+                finally {
+                    assertRemovalAuthorized();
+                }
+            });
+        };
+        let removal;
+        try {
+            removal = await removeStaleSidecarLockIfAllowed({
+                lockPath,
+                normalizedTargetPath,
+                snapshot,
+                assertGuardHeld: acquiredGuard.assertHeld && (() => admission.run(async () => {
+                    assertUnheld();
+                    await acquiredGuard.assertHeld();
+                    assertUnheld();
+                })),
+                shouldRemoveStaleLock: guardedShouldRemove,
+                lockRoot: params.lockRoot,
+                parsePayload: scopedSidecarLockParser(params.parserState, admission, assertRemovalAuthorized),
+                assertAuthorized: assertRemovalAuthorized,
+            });
+        }
+        catch (error) {
+            if (error !== holderChanged) {
+                try {
+                    assertRemovalAuthorized();
+                }
+                catch (boundaryError) {
+                    if (boundaryError !== holderChanged)
+                        throw boundaryError;
+                }
+                if (!params.currentHeld())
+                    throw error;
+            }
+            await params.releaseReclaimGuard();
+            await params.waitForRetry();
+            return;
+        }
+        params.assertToken();
+        if (params.currentHeld()) {
+            await params.releaseReclaimGuard();
+            await params.waitForRetry();
+            return;
+        }
+        if (removal === "removed")
+            return;
+        if (removal === "changed") {
+            await params.waitForRetry();
+            return;
+        }
+        await params.releaseReclaimGuard();
+    }
+    throw sidecarLockStale(lockPath, normalizedTargetPath);
+}

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-target.d.ts

@@ -0,0 +1,7 @@
+import type { Root } from "./root-impl.js";
+export declare function isCwdIndependentAbsolutePath(filePath: string): boolean;
+export declare function resolveSidecarTargetPath(resolved: string, lockRoot?: Root): Promise<string>;
+export declare function resolveSidecarLockPaths(targetPath: string, explicitLockPath: string | undefined, lockRoot: Root | undefined): Promise<{
+    lockPath: string;
+    normalizedTargetPath: string;
+}>;

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-target.js

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+export function isCwdIndependentAbsolutePath(filePath) {
+    if (!path.isAbsolute(filePath))
+        return false;
+    // A leading separator on Windows is rooted on the process's current drive.
+    return process.platform !== "win32" || path.parse(filePath).root.length > 1;
+}
+export async function resolveSidecarTargetPath(resolved, lockRoot) {
+    assertNoWindowsPathAlias(resolved);
+    const dir = path.dirname(resolved);
+    if (lockRoot) {
+        // The target is an arbitration key, not necessarily inside the lock Root.
+        await lockRoot.resolve(".");
+        const parent = await canonicalPathFromExistingAncestor(dir);
+        await lockRoot.resolve(".");
+        assertNoWindowsPathAlias(parent);
+        const normalized = path.join(parent, path.basename(resolved));
+        assertNoWindowsPathAlias(normalized);
+        return normalized;
+    }
+    await fs.mkdir(recursiveMkdirPath(dir), { recursive: true });
+    let parent;
+    try {
+        parent = realpathSync.native(dir);
+    }
+    catch {
+        return resolved;
+    }
+    assertNoWindowsPathAlias(parent);
+    const normalized = path.join(parent, path.basename(resolved));
+    assertNoWindowsPathAlias(normalized);
+    return normalized;
+}
+export async function resolveSidecarLockPaths(targetPath, explicitLockPath, lockRoot) {
+    const anchoredTargetPath = anchorWindowsDriveRelativePath(targetPath);
+    assertNoWindowsPathAlias(anchoredTargetPath);
+    const resolvedTargetPath = path.resolve(anchoredTargetPath);
+    let resolvedLockPath;
+    if (explicitLockPath !== undefined) {
+        const anchoredLockPath = anchorWindowsDriveRelativePath(explicitLockPath);
+        assertNoWindowsPathAlias(anchoredLockPath);
+        resolvedLockPath = isCwdIndependentAbsolutePath(explicitLockPath)
+            ? explicitLockPath
+            : path.resolve(anchoredLockPath);
+    }
+    const normalizedTargetPath = await resolveSidecarTargetPath(resolvedTargetPath, lockRoot);
+    const lockPath = resolvedLockPath ?? `${normalizedTargetPath}.lock`;
+    assertNoWindowsPathAlias(lockPath);
+    return { lockPath, normalizedTargetPath };
+}

package/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/dist/sidecar-lock.js

@@ -1,14 +1,18 @@
 import fsSync from "node:fs";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { sameFileIdentityForCleanup } 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");
+const GLOBAL_CLEANUP_REGISTRATION_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistration");
 const GLOBAL_BEFORE_EXIT_KEY = Symbol.for("fsSafe.sidecarLockBeforeExitCleanup");
+const GLOBAL_BEFORE_EXIT_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockBeforeExitCleanupHandler");
+const GLOBAL_BEFORE_EXIT_REGISTRATION_KEY = Symbol.for("fsSafe.sidecarLockBeforeExitCleanupRegistration");
 // Set by copies whose exit handlers honor retainOnExit. When an older package
 // copy registered the handlers first, this marker stays absent and retained
 // acquisitions must fail closed rather than silently lose the guarantee.
@@ -27,6 +31,7 @@ function resolveManagerState(key) {
         state = {
             cleanupRegistered: false,
             held: new Map(),
+            admissions: new Map(),
             reclaimCleanupRegistered: false,
             reclaimGuards: new Set(),
         };
@@ -34,7 +39,9 @@ function resolveManagerState(key) {
     }
     else {
         // The global manager symbol is shared across package copies and hot reloads.
-        // Backfill state created by fs-safe versions that predate reclaim guards.
+        // Backfill state created by fs-safe versions that predate admission tokens
+        // or reclaim guards without placing an incomplete value in the held map.
+        state.admissions ??= new Map();
         state.reclaimCleanupRegistered ??= false;
         state.reclaimGuards ??= new Set();
     }
@@ -43,7 +50,7 @@ function resolveManagerState(key) {
 function snapshotMatchesSync(lockPath, observed) {
     let fd;
     try {
-        const beforeStat = fsSync.lstatSync(lockPath);
+        const beforeStat = fsSync.lstatSync(lockPath, { bigint: true });
         if (!beforeStat.isFile()) {
             return false;
         }
@@ -53,16 +60,18 @@ function snapshotMatchesSync(lockPath, observed) {
                 : 0) |
             (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0);
         fd = fsSync.openSync(lockPath, openFlags);
-        const openedStat = fsSync.fstatSync(fd);
-        if (!openedStat.isFile()) {
+        const openedStat = fsSync.fstatSync(fd, { bigint: true });
+        // Token-owned files can have different descriptor/path identities on VirtioFS.
+        // Require a known descriptor identity without rejecting that supported drift.
+        if (!openedStat.isFile() || !sameFileIdentityForCleanup(openedStat, openedStat)) {
             return false;
         }
-        if (observed.raw !== undefined && openedStat.size !== Buffer.byteLength(observed.raw)) {
+        if (observed.raw !== undefined && openedStat.size !== BigInt(Buffer.byteLength(observed.raw))) {
             return false;
         }
         const raw = fsSync.readFileSync(fd, "utf8");
-        const afterStat = fsSync.lstatSync(lockPath);
-        if (!afterStat.isFile() || !sameFileIdentity(beforeStat, afterStat)) {
+        const afterStat = fsSync.lstatSync(lockPath, { bigint: true });
+        if (!afterStat.isFile() || !sameFileIdentityForCleanup(beforeStat, afterStat)) {
             return false;
         }
         return sidecarLockSnapshotMatches({ raw, payload: null, stat: afterStat }, observed);
@@ -95,6 +104,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;
@@ -107,21 +117,23 @@ function releaseAllLocksSync(state, options) {
         }
         state.held.delete(normalizedTargetPath);
     }
+    state.admissions?.clear();
     releaseAllReclaimGuardsSync(state);
 }
 function ensureGlobalExitCleanupRegistered() {
-    const globalWithCleanup = globalThis;
-    if (globalWithCleanup[GLOBAL_CLEANUP_KEY])
-        return;
-    globalWithCleanup[GLOBAL_CLEANUP_KEY] = true;
-    globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] = true;
     const cleanup = () => {
         for (const state of getGlobalManagers().values()) {
             releaseAllLocksSync(state, { preserveRetained: true });
         }
     };
-    globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
-    process.on("exit", cleanup);
+    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() {
@@ -129,14 +141,9 @@ 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];
-    }
     // Independent of the exit registration, which an older package copy may own.
     const lifecycle = { armed: false };
-    globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] = lifecycle;
-    process.on("beforeExit", () => {
+    const cleanup = () => {
         if (!lifecycle.armed)
             return;
         // Cleanup itself schedules I/O; retry only after another acquisition.
@@ -148,8 +155,14 @@ function ensureGlobalBeforeExitCleanupRegistered() {
                 }
             }
         }
-    });
-    return lifecycle;
+    };
+    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);
@@ -180,10 +193,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;
@@ -194,7 +204,6 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
     }
 }
 function handleForHeldLock(state, normalizedTargetPath, held) {
-    ensureGlobalBeforeExitCleanupRegistered().armed = true;
     return createHeldSidecarLockHandle({
         normalizedTargetPath,
         held,
@@ -204,21 +213,29 @@ function handleForHeldLock(state, normalizedTargetPath, held) {
 export function createSidecarLockManager(key) {
     const state = resolveManagerState(key);
     function ensureExitCleanupRegistered() {
+        ensureGlobalExitCleanupRegistered();
+        const lifecycle = ensureGlobalBeforeExitCleanupRegistered();
         state.cleanupRegistered = true;
         state.reclaimCleanupRegistered = true;
-        ensureGlobalExitCleanupRegistered();
-        ensureGlobalBeforeExitCleanupRegistered().armed = true;
+        return lifecycle;
+    }
+    function armExitCleanup(lifecycle) {
+        lifecycle.armed = true;
+    }
+    function assertRetainOnExitSupported(retainOnExit) {
+        if (retainOnExit !== true || !exitCleanupCannotRetain())
+            return;
+        throw new FsSafeError("helper-unavailable", "retainOnExit requires this process's exit handlers to be retain-aware; an older package copy registered them first");
     }
     async function acquire(options) {
-        if (options.retainOnExit === true && exitCleanupCannotRetain()) {
-            throw new FsSafeError("helper-unavailable", "retainOnExit requires this process's exit handlers to be retain-aware; an older package copy registered them first");
-        }
         return await acquireSidecarLock(options, {
             held: state.held,
+            admissions: state.admissions,
             reclaimGuards: state.reclaimGuards,
             ensureExitCleanupRegistered,
+            armExitCleanup,
+            assertRetainOnExitSupported,
             handleForHeldLock: (normalizedTargetPath, held) => handleForHeldLock(state, normalizedTargetPath, held),
-            releaseHeldLock: async (normalizedTargetPath, held, releaseOptions) => await releaseHeldLock(state, normalizedTargetPath, held, releaseOptions),
         });
     }
     async function withLock(options, fn) {