@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,95 +1,102 @@
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
-import path from "node:path";
-import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { FsSafeError } from "./errors.js";
 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, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
-import { readSidecarLockRawSnapshot, parseSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.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 { resolveSidecarLockPaths } from "./sidecar-lock-target.js";
 import { createSuppressedError } from "./suppressed-error.js";
-async function resolveNormalizedTargetPath(targetPath, lockRoot) {
-    const resolved = path.resolve(targetPath);
-    const dir = path.dirname(resolved);
-    if (lockRoot) {
-        // The target is an arbitration key, not necessarily inside the lock Root.
-        // Leave parent creation to the Root-backed sidecar write.
-        await lockRoot.resolve(".");
-        const parent = await canonicalPathFromExistingAncestor(dir);
-        await lockRoot.resolve(".");
-        return path.join(parent, path.basename(resolved));
-    }
-    await fs.mkdir(dir, { recursive: true });
-    try {
-        return path.join(await fs.realpath(dir), path.basename(resolved));
-    }
-    catch {
-        return resolved;
-    }
-}
+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;
+    context.assertRetainOnExitSupported(retainOnExit);
     const retry = options.retry ?? {};
+    const timeoutMs = options.timeoutMs;
+    const staleMs = options.staleMs;
+    const compromiseCheckIntervalMs = options.compromiseCheckIntervalMs;
     validateSidecarLockRetryOptions(retry);
-    validateSidecarLockTimeoutMs(options.timeoutMs);
-    context.ensureExitCleanupRegistered();
-    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath, options.lockRoot);
-    const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
+    validateSidecarLockTimeoutMs(timeoutMs);
+    validateSidecarLockStaleMs(staleMs);
+    validateSidecarLockCompromiseCheckIntervalMs(compromiseCheckIntervalMs);
+    const targetPath = options.targetPath;
+    const explicitLockPath = options.lockPath;
+    const lockRoot = options.lockRoot;
+    const requestedReentrantOwner = options.reentrantOwner;
+    const { lockPath, normalizedTargetPath } = await resolveSidecarLockPaths(targetPath, explicitLockPath, lockRoot);
+    const activeDescendant = ancestryHasSidecarAdmission(admissionAncestry, context.admissions, normalizedTargetPath);
+    const isReentrant = (candidate) => !!candidate &&
+        requestedReentrantOwner !== undefined &&
+        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 (held &&
-        options.reentrantOwner !== undefined &&
-        held.reentrantOwner !== undefined &&
-        options.reentrantOwner === held.reentrantOwner) {
-        // A final release may already have decremented the count to zero and be
-        // removing the sidecar. Do not admit a new reentrant handle until that
-        // cleanup settles: successful cleanup requires a fresh acquisition, while
-        // failed cleanup leaves the existing sidecar held for a retry.
+    if (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) {
+            if (activeDescendant)
+                throw sidecarLockTimeout(lockPath, normalizedTargetPath);
             await held.releasePromise.catch(() => undefined);
             held = context.held.get(normalizedTargetPath);
         }
-        if (held &&
-            options.reentrantOwner !== undefined &&
-            held.reentrantOwner !== undefined &&
-            options.reentrantOwner === held.reentrantOwner) {
-            held.refCount += 1;
-            // 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 (options.retainOnExit === true) {
-                held.retainOnExit = true;
-            }
-            return context.handleForHeldLock(normalizedTargetPath, held);
+        if (isReentrant(held)) {
+            const reused = reuseHeldLock(held);
+            if (reused)
+                return reused;
         }
     }
-    const startedAt = Date.now();
+    if (activeDescendant)
+        throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+    const admission = createSidecarAdmissionController(admissionAncestry, context.admissions, normalizedTargetPath);
+    const startedAt = performance.now();
     const reclaimGuardPath = `${lockPath}.reclaim`;
-    let ownsReclaimGuard = false;
+    let reclaimGuard;
+    const releaseReclaimGuard = async () => {
+        if (!reclaimGuard)
+            return;
+        await admission.run(() => reclaimGuard.release());
+        reclaimGuard = undefined;
+    };
     let attempt = 0;
     // Bounded so a genuine denial still surfaces as EPERM, not a lock timeout.
     let transientDenials = 0;
+    let payloadCallback;
+    let metadata = undefined;
+    let metadataObserved = false;
+    let onCompromised = undefined;
+    let onCompromisedObserved = false;
+    const staleOptionsState = {};
     const withinDenialBudget = () => ++transientDenials <= maxTransientLockDenials;
     const waitForRetry = async () => {
-        const elapsed = Date.now() - startedAt;
-        if ((options.timeoutMs !== undefined &&
-            options.timeoutMs !== Number.POSITIVE_INFINITY &&
-            elapsed >= options.timeoutMs) ||
-            (retry.retries !== undefined && attempt >= retry.retries)) {
-            throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-                code: "file_lock_timeout",
-                lockPath,
-                normalizedTargetPath,
-            });
-        }
-        const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
-            ? Number.POSITIVE_INFINITY
-            : Math.max(0, options.timeoutMs - elapsed);
-        const delay = Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
+        admission.release();
+        const delay = sidecarLockRetryDelay(retry, timeoutMs === Number.POSITIVE_INFINITY ? undefined : timeoutMs, performance.now() - startedAt, attempt);
+        if (delay === undefined)
+            throw sidecarLockTimeout(lockPath, normalizedTargetPath);
         attempt += 1;
-        await new Promise((resolve) => setTimeout(resolve, delay));
+        await sleep(delay);
     };
-    // Waiting can fail on the caller's own retry or deadline limits. Classifying
-    // a denial as contention must not cost them the original diagnosis, so hand
-    // the denial back when no further attempt can be scheduled.
+    // Preserve a denial diagnosis if contention backoff has no remaining budget.
     const retryOrRethrowDenial = async (denial) => {
         try {
             await waitForRetry();
@@ -100,30 +107,153 @@ export async function acquireSidecarLock(options, context) {
             throw waitError;
         }
     };
+    const assertAdmissionToken = () => {
+        if (!admission.hasToken())
+            throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+    };
     try {
         while (true) {
-            if (!ownsReclaimGuard && (await sidecarReclaimGuardExists(reclaimGuardPath))) {
+            if (!admission.owns) {
+                held = context.held.get(normalizedTargetPath);
+                if (isReentrant(held)) {
+                    if (held.releasePromise) {
+                        await held.releasePromise.catch(() => undefined);
+                        held = context.held.get(normalizedTargetPath);
+                    }
+                    if (isReentrant(held)) {
+                        const reused = reuseHeldLock(held);
+                        if (reused)
+                            return reused;
+                        continue;
+                    }
+                }
+                if (context.admissions.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+                admission.reserve();
+            }
+            const attemptHeld = context.held.get(normalizedTargetPath);
+            const holderWasReplaced = () => {
+                const current = context.held.get(normalizedTargetPath);
+                return current !== undefined && current !== attemptHeld;
+            };
+            const lifecycle = admission.run(() => context.ensureExitCleanupRegistered());
+            assertAdmissionToken();
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            admission.run(() => context.assertRetainOnExitSupported(retainOnExit));
+            assertAdmissionToken();
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            if (reclaimGuard?.assertHeld)
+                await admission.run(() => reclaimGuard.assertHeld());
+            const reclaimGuardExists = !reclaimGuard && (await (lockRoot
+                ? admission.run(() => sidecarReclaimGuardExists(reclaimGuardPath, lockRoot))
+                : sidecarReclaimGuardExists(reclaimGuardPath)));
+            assertAdmissionToken();
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            if (reclaimGuardExists) {
                 await waitForRetry();
                 continue;
             }
             let handle = null;
-            let createdSnapshot = null;
+            let createdSnapshot = null, createdHeld;
+            let admissionConflict = false;
+            let exclusiveCreateConflict = false;
             let lockFileCreateDenied = false;
-            const payload = await options.payload();
-            const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
+            const parserState = { observed: false };
+            if (!payloadCallback)
+                payloadCallback = runSidecarAdmissionBoundary(admission, assertAdmissionToken, () => options.payload);
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            const { value: payload } = await awaitSidecarAdmissionBoundary(admission, assertAdmissionToken, () => Reflect.apply(payloadCallback, options, []));
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            const { raw, ownershipToken } = runSidecarAdmissionBoundary(admission, assertAdmissionToken, () => serializeSidecarLockPayload(payload));
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            held = context.held.get(normalizedTargetPath);
+            if (held?.releasePromise) {
+                // Release cleanup never acquires this admission; retaining it here lets
+                // the serialized attempt continue without another callback or retry.
+                await held.releasePromise.catch(() => undefined);
+                assertAdmissionToken();
+                held = context.held.get(normalizedTargetPath);
+            }
+            if (held?.lockPath === lockPath) {
+                const observedHeld = held;
+                const observation = await observeHeldSidecarParser({
+                    admission, assertToken: assertAdmissionToken,
+                    currentHeld: () => context.held.get(normalizedTargetPath), held: observedHeld,
+                    lockPath, lockRoot, parserState,
+                    parserAccessor: () => options.parsePayload,
+                    isTransientDenial: (error) => isTransientLockFileDenial(error, lockPath),
+                });
+                assertAdmissionToken();
+                held = context.held.get(normalizedTargetPath);
+                if (held !== observedHeld || observedHeld.releasePromise) {
+                    await waitForRetry();
+                    continue;
+                }
+                if (observation.kind === "read-error") {
+                    if (!observation.transientDenial || !withinDenialBudget())
+                        throw observation.error;
+                    await retryOrRethrowDenial(observation.error);
+                    continue;
+                }
+            }
+            if (held) {
+                await waitForRetry();
+                continue;
+            }
+            if (!metadataObserved) {
+                metadata = runSidecarAdmissionBoundary(admission, assertAdmissionToken, () => options.metadata);
+                metadataObserved = true;
+                if (context.held.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+            }
+            if (!onCompromisedObserved) {
+                onCompromised = runSidecarAdmissionBoundary(admission, assertAdmissionToken, () => options.onCompromised);
+                onCompromisedObserved = true;
+                if (context.held.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+            }
+            assertAdmissionToken();
+            if (context.held.has(normalizedTargetPath)) {
+                await waitForRetry();
+                continue;
+            }
             try {
-                if (options.lockRoot) {
-                    const lockRoot = options.lockRoot;
+                if (lockRoot) {
                     const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
                     const observation = fileObservation();
                     try {
-                        await observation.run(() => lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 }));
+                        await observation.run(() => lockRoot.create(relativeLockPath, raw, { ...sidecarExclusiveCreate, mkdir: true, mode: 0o600 }));
                     }
                     catch (error) {
                         // Only this invocation's failed exclusive open grants denial retry authority.
                         lockFileCreateDenied = observation.has(error, `exclusive-create:${lockPath}`) &&
                             isTransientLockFileDenial(error, lockPath);
                         if (error instanceof FsSafeError && error.code === "already-exists") {
+                            exclusiveCreateConflict = true;
                             throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
                         }
                         throw error;
@@ -151,186 +281,162 @@ export async function acquireSidecarLock(options, context) {
                     try {
                         handle =
                             (await createNativeExclusiveFile(lockPath, 0o600)) ??
-                                (await fs.open(lockPath, "wx"));
+                                (await fs.open(lockPath, "wx", 0o600));
                     }
                     catch (createError) {
                         lockFileCreateDenied = isTransientLockFileDenial(createError, lockPath);
+                        exclusiveCreateConflict = createError.code === "EEXIST";
                         throw createError;
                     }
                     await handle.writeFile(raw, "utf8");
                 }
-                const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
+                const snapshot = { raw, payload, stat: fsSync.fstatSync(handle.fd), ownershipToken };
+                createdSnapshot = snapshot;
                 if (snapshot.stat.nlink === 0) {
                     await handle.close();
                     handle = null;
                     await waitForRetry();
                     continue;
                 }
-                const createdHeld = {
+                observeSidecarLockParser(parserState, admission, () => options.parsePayload, assertAdmissionToken);
+                if (context.held.has(normalizedTargetPath)) {
+                    admissionConflict = true;
+                    throw Object.assign(new Error("sidecar lock admission changed"), { code: "EEXIST" });
+                }
+                createdHeld = {
                     refCount: 1,
-                    reentrantOwner: options.reentrantOwner,
+                    reentrantOwner: requestedReentrantOwner,
                     handle,
                     lockPath,
                     snapshot,
                     acquiredAt: Date.now(),
-                    metadata: options.metadata ?? {},
-                    lockRoot: options.lockRoot,
-                    retainOnExit: options.retainOnExit,
-                    parsePayload: options.parsePayload,
+                    metadata: metadata ?? {},
+                    lockRoot,
+                    retainOnExit,
+                    parsePayload: parserState.parser,
                 };
-                context.held.set(normalizedTargetPath, createdHeld);
-                if (ownsReclaimGuard) {
-                    try {
-                        await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
-                        ownsReclaimGuard = false;
-                    }
-                    catch (err) {
-                        await context.releaseHeldLock(normalizedTargetPath, createdHeld, { force: true });
-                        throw err;
-                    }
-                }
-                const returnedHandle = context.handleForHeldLock(normalizedTargetPath, createdHeld);
-                const interval = options.compromiseCheckIntervalMs;
-                if (options.onCompromised && interval !== undefined && interval > 0) {
-                    createdHeld.compromiseTimer = setInterval(() => {
+                const candidateHeld = createdHeld;
+                if (reclaimGuard)
+                    await releaseReclaimGuard();
+                const returnedHandle = admission.run(() => context.handleForHeldLock(normalizedTargetPath, candidateHeld));
+                if (onCompromised &&
+                    compromiseCheckIntervalMs !== undefined &&
+                    compromiseCheckIntervalMs > 0) {
+                    const compromisedCallback = onCompromised;
+                    let compromiseCheckInFlight = false;
+                    candidateHeld.compromiseTimer = admission.run(() => setInterval(() => {
+                        if (compromiseCheckInFlight)
+                            return;
+                        compromiseCheckInFlight = true;
                         void returnedHandle
                             .verifyStillHeld()
                             .catch(() => false)
                             .then((stillHeld) => {
-                            if (!stillHeld && createdHeld.compromiseTimer) {
-                                clearInterval(createdHeld.compromiseTimer);
-                                createdHeld.compromiseTimer = undefined;
-                                options.onCompromised?.({ lockPath, normalizedTargetPath });
+                            if (!stillHeld && candidateHeld.compromiseTimer) {
+                                stopSidecarLockMonitoring(candidateHeld);
+                                Reflect.apply(compromisedCallback, options, [{ lockPath, normalizedTargetPath }]);
                             }
+                        })
+                            .finally(() => {
+                            compromiseCheckInFlight = false;
                         });
-                    }, interval);
-                    createdHeld.compromiseTimer.unref();
+                    }, compromiseCheckIntervalMs));
+                    admission.run(() => candidateHeld.compromiseTimer?.unref());
+                }
+                if (!admission.hasToken() ||
+                    context.held.has(normalizedTargetPath)) {
+                    admissionConflict = true;
+                    throw Object.assign(new Error("sidecar lock admission changed"), { code: "EEXIST" });
                 }
+                context.held.set(normalizedTargetPath, candidateHeld);
+                admission.release();
+                context.armExitCleanup(lifecycle);
                 return returnedHandle;
             }
             catch (err) {
                 try {
+                    if (createdHeld)
+                        stopSidecarLockMonitoring(createdHeld);
+                    let failedSnapshot = createdSnapshot;
                     if (handle) {
-                        const failedSnapshot = createdSnapshot ?? { payload: null };
+                        failedSnapshot ??= { payload: null };
                         try {
-                            failedSnapshot.stat = await handle.stat();
+                            failedSnapshot.stat = fsSync.fstatSync(handle.fd);
                         }
                         catch {
                             // Best-effort cleanup of a failed exclusive create.
                         }
                         const current = context.held.get(normalizedTargetPath);
-                        if (current?.handle === handle) {
+                        if (createdHeld && current === createdHeld) {
                             context.held.delete(normalizedTargetPath);
                         }
                         await handle.close().catch(() => undefined);
-                        // Root-created records retain the creator's byte/token receipt;
-                        // partial direct writes use the exclusive descriptor's identity.
-                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                            lockRoot: options.lockRoot,
-                            parsePayload: options.parsePayload,
-                        });
                     }
-                    else if (createdSnapshot) {
-                        await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
-                            lockRoot: options.lockRoot,
-                            parsePayload: options.parsePayload,
+                    // 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)),
                         });
                     }
                 }
                 catch (cleanupError) {
                     throw createSuppressedError(cleanupError, err, "file lock acquisition and cleanup both failed");
                 }
-                if (lockFileCreateDenied && withinDenialBudget()) {
-                    await retryOrRethrowDenial(err);
-                    continue;
-                }
-                if (err.code !== "EEXIST") {
-                    throw err;
-                }
-                if (ownsReclaimGuard) {
-                    await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
-                    ownsReclaimGuard = false;
+                if (admissionConflict) {
                     await waitForRetry();
                     continue;
                 }
-                const nowMs = Date.now();
-                let rawSnapshot;
-                let lockFileOpenDenied = false;
-                try {
-                    rawSnapshot = await readSidecarLockRawSnapshot(lockPath, {
-                        lockRoot: options.lockRoot,
-                        rejectNonFile: true,
-                        discardObservation: "changed",
-                        onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
-                    });
-                }
-                catch (readErr) {
-                    if (!lockFileOpenDenied || !withinDenialBudget())
-                        throw readErr;
-                    await retryOrRethrowDenial(readErr);
-                    continue;
+                if (lockFileCreateDenied) {
+                    assertAdmissionToken();
+                    if (context.held.has(normalizedTargetPath)) {
+                        await waitForRetry();
+                        continue;
+                    }
+                    if (withinDenialBudget()) {
+                        await retryOrRethrowDenial(err);
+                        continue;
+                    }
+                    throw err;
                 }
-                const snapshot = parseSidecarLockSnapshot(rawSnapshot, options.parsePayload);
-                if (!snapshot) {
+                if (!exclusiveCreateConflict)
+                    throw err;
+                assertAdmissionToken();
+                if (context.held.has(normalizedTargetPath)) {
                     await waitForRetry();
                     continue;
                 }
-                if (context.held.has(normalizedTargetPath)) {
+                if (reclaimGuard) {
+                    await releaseReclaimGuard();
                     await waitForRetry();
                     continue;
                 }
-                const shouldReclaim = options.shouldReclaim ?? defaultSidecarLockShouldReclaim;
-                if (await shouldReclaim({
+                await handleStaleSidecarAdmission({
+                    admission,
+                    assertToken: assertAdmissionToken,
+                    currentHeld: () => context.held.get(normalizedTargetPath),
                     lockPath,
+                    lockRoot,
                     normalizedTargetPath,
-                    payload: snapshot?.payload ?? null,
-                    staleMs: options.staleMs,
-                    nowMs,
-                    heldByThisProcess: context.held.has(normalizedTargetPath),
-                })) {
-                    if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    }))) {
-                        await waitForRetry();
-                        continue;
-                    }
-                    const staleRecovery = options.staleRecovery ?? "fail-closed";
-                    if (staleRecovery === "remove-if-unchanged") {
-                        if (!(await tryAcquireSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath))) {
-                            await waitForRetry();
-                            continue;
-                        }
-                        ownsReclaimGuard = true;
-                        const removal = await removeStaleSidecarLockIfAllowed({
-                            lockPath,
-                            normalizedTargetPath,
-                            snapshot,
-                            shouldRemoveStaleLock: options.shouldRemoveStaleLock,
-                            lockRoot: options.lockRoot,
-                            parsePayload: options.parsePayload,
-                        });
-                        if (removal === "removed" || removal === "changed") {
-                            if (removal === "changed")
-                                await waitForRetry();
-                            continue;
-                        }
-                        await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
-                        ownsReclaimGuard = false;
-                    }
-                    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                        code: "file_lock_stale",
-                        lockPath,
-                        normalizedTargetPath,
-                    });
-                }
-                await waitForRetry();
+                    options,
+                    parserState,
+                    reclaimGuardPath,
+                    reclaimGuards: context.reclaimGuards,
+                    setReclaimGuard: (guard) => { reclaimGuard = guard; },
+                    releaseReclaimGuard,
+                    staleOptionsState,
+                    staleMs,
+                    withinDenialBudget,
+                    retryOrRethrowDenial,
+                    waitForRetry,
+                });
+                continue;
             }
         }
     }
     finally {
-        if (ownsReclaimGuard) {
-            await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath).catch(() => undefined);
-        }
+        if (reclaimGuard)
+            await releaseReclaimGuard().catch(() => undefined);
+        admission.release();
     }
 }

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

@@ -0,0 +1,18 @@
+type AdmissionIdentity = {
+    active: boolean;
+    admissions: Map<string, object>;
+    normalizedTargetPath: string;
+    token: object;
+};
+type SidecarAdmissionAncestry = readonly AdmissionIdentity[];
+/** Capture active ancestry now; later lifecycle changes cannot reclassify this call. */
+export declare function captureSidecarAdmissionAncestry(): SidecarAdmissionAncestry;
+export declare function ancestryHasSidecarAdmission(ancestry: SidecarAdmissionAncestry, admissions: Map<string, object>, normalizedTargetPath: string): boolean;
+export declare function createSidecarAdmissionController(ancestry: SidecarAdmissionAncestry, admissions: Map<string, object>, normalizedTargetPath: string): {
+    readonly owns: boolean;
+    hasToken: () => boolean;
+    release(): void;
+    reserve(): void;
+    run<T>(callback: () => T): T;
+};
+export {};