@openclaw/fs-safe 0.13.1 → 0.15.0

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

@@ -0,0 +1,232 @@
+import { defaultSidecarLockShouldReclaim, isTransientLockFileDenial } 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 Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+        code: "file_lock_stale",
+        lockPath,
+        normalizedTargetPath,
+    });
+}

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

@@ -0,0 +1,8 @@
+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;
+}>;
+//# sourceMappingURL=sidecar-lock-target.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-target.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-target.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAG3C,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAItE;AAED,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBjG;AAED,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,QAAQ,EAAE,IAAI,GAAG,SAAS,GACzB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAAC,CAgB7D"}

package/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/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAmIjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAyFD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAU3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAkBL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AA2KjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AA8HD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAuB3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAaL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}

package/dist/sidecar-lock.js

@@ -8,7 +8,10 @@ import { createSuppressedError } from "./suppressed-error.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 +30,7 @@ function resolveManagerState(key) {
         state = {
             cleanupRegistered: false,
             held: new Map(),
+            admissions: new Map(),
             reclaimCleanupRegistered: false,
             reclaimGuards: new Set(),
         };
@@ -34,7 +38,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();
     }
@@ -107,21 +113,55 @@ 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;
+    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_HANDLER_KEY] = cleanup;
-    process.on("exit", cleanup);
+    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];
+        }
+    }
 }
 /** True when a retain-unaware package copy registered the process-exit handlers first. */
 export function exitCleanupCannotRetain() {
@@ -133,10 +173,13 @@ function ensureGlobalBeforeExitCleanupRegistered() {
     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 };
-    globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] = lifecycle;
-    process.on("beforeExit", () => {
+    const registration = {};
+    const cleanup = () => {
         if (!lifecycle.armed)
             return;
         // Cleanup itself schedules I/O; retry only after another acquisition.
@@ -148,8 +191,42 @@ function ensureGlobalBeforeExitCleanupRegistered() {
                 }
             }
         }
-    });
-    return lifecycle;
+    };
+    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];
+        }
+    }
 }
 async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
     const current = state.held.get(normalizedTargetPath);
@@ -194,7 +271,6 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
     }
 }
 function handleForHeldLock(state, normalizedTargetPath, held) {
-    ensureGlobalBeforeExitCleanupRegistered().armed = true;
     return createHeldSidecarLockHandle({
         normalizedTargetPath,
         held,
@@ -204,21 +280,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) {

package/dist/staged-directory.d.ts

@@ -1,13 +1,16 @@
 import { type BigIntStats } from "node:fs";
 import type { DirectoryReceipt } from "./directory-durability.js";
 import type { FileIdentityStat } from "./file-identity.js";
-import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+import type { NativeBinding } from "./native-binding.js";
+import { type MutationDirectoryObservation, type MutationDirectoryObserver } from "./pinned-mutation-observation.js";
 import type { StagedFileReceipt } from "./staged-file-types.js";
 export type StagedDirectorySnapshot = StagedFileReceipt["directory"];
 export type PolicyStagedDirectory = Readonly<{
     directory: StagedDirectorySnapshot;
     observation: MutationDirectoryObservation;
     stat: BigIntStats;
+    observeCurrent?: MutationDirectoryObserver;
+    disposeObservation?(): void;
 }>;
 export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
     dev: bigint;
@@ -15,7 +18,7 @@ export declare function exactIdentityMatches(expected: FileIdentityStat, actual:
 }>): boolean;
 export declare function describeStagedDirectory(fd: number, pathname: string): StagedDirectorySnapshot;
 export declare function assertStagedDirectoryCurrent(receipt: StagedDirectorySnapshot): BigIntStats;
-export declare function describePolicyStagedDirectory(fd: number, pathname: string): PolicyStagedDirectory;
+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): {

package/dist/staged-directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAwBvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAOb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAU9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAE/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;IAClB,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC7B,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CA2CvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAeb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAoB9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}

package/dist/staged-directory.js

@@ -2,6 +2,7 @@ import fs, {} from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { nativePolicyDirectoryObserver, NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
 import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { realpathSync } from "./realpath.js";
 import { resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
@@ -38,12 +39,31 @@ function sameDirectoryMetadata(left, right) {
 }
 // The policy hot path is Node/POSIX-only. It deliberately uses native
 // canonicalization so a successful capture contains no JS realpath work.
-export function describePolicyStagedDirectory(fd, pathname) {
+export function describePolicyStagedDirectory(fd, pathname, binding) {
     const resolved = path.resolve(pathname);
     const descriptor = fs.fstatSync(fd, { bigint: true });
     if (!descriptor.isDirectory()) {
         throw new FsSafeError("not-file", "staging parent must be a directory");
     }
+    const observeCurrent = nativePolicyDirectoryObserver(binding, fd, resolved);
+    const observed = observeCurrent?.();
+    if (observed) {
+        if (!sameDirectoryMetadata(descriptor, observed.identity)) {
+            throw new NativePolicyDirectoryMismatch();
+        }
+        const directory = Object.freeze({
+            path: resolved,
+            realPath: observed.canonicalPath,
+            identity: Object.freeze({ dev: descriptor.dev, ino: descriptor.ino }),
+        });
+        return Object.freeze({
+            directory,
+            observation: checkedMutationDirectory(resolved, observed.canonicalPath, observed.identity, observeCurrent),
+            stat: descriptor,
+            observeCurrent,
+            disposeObservation: observeCurrent.dispose,
+        });
+    }
     const before = inspectDirectoryIdentitySync(resolved);
     const canonicalPath = path.resolve(realpathSync.native(resolved));
     const after = inspectDirectoryIdentitySync(resolved, descriptor);
@@ -64,6 +84,14 @@ export function describePolicyStagedDirectory(fd, pathname) {
     });
 }
 export function assertPolicyStagedDirectoryCurrent(captured) {
+    const observed = captured.observeCurrent?.();
+    if (observed) {
+        if (!sameDirectoryMetadata(captured.stat, observed.identity) ||
+            observed.canonicalPath !== captured.directory.realPath) {
+            throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+        }
+        return captured.stat;
+    }
     const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
     if (!sameDirectoryMetadata(captured.stat, current) ||
         path.resolve(realpathSync.native(captured.directory.path)) !== captured.directory.realPath) {
@@ -72,6 +100,14 @@ export function assertPolicyStagedDirectoryCurrent(captured) {
     return current;
 }
 export function refreshPolicyStagedDirectoryObservation(captured) {
+    const observed = captured.observeCurrent?.();
+    if (observed) {
+        if (!exactIdentityMatches(captured.directory.identity, observed.identity) ||
+            observed.canonicalPath !== captured.directory.realPath) {
+            throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+        }
+        return checkedMutationDirectory(captured.directory.path, observed.canonicalPath, observed.identity, captured.observeCurrent);
+    }
     const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
     const canonicalPath = path.resolve(realpathSync.native(captured.directory.path));
     if (canonicalPath !== captured.directory.realPath) {

package/dist/temp-workspace-admission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-workspace-admission.d.ts","sourceRoot":"","sources":["../src/temp-workspace-admission.ts"],"names":[],"mappings":"AA6BA,KAAK,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAiB5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,aAAa,IAAI,IAAI,CAAC;IACtB,cAAc,IAAI,IAAI,CAAC;IACvB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,CAAC;AA0UF,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAM1F;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyBjG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAsBtF"}
+{"version":3,"file":"temp-workspace-admission.d.ts","sourceRoot":"","sources":["../src/temp-workspace-admission.ts"],"names":[],"mappings":"AA6BA,KAAK,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAiB5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,aAAa,IAAI,IAAI,CAAC;IACtB,cAAc,IAAI,IAAI,CAAC;IACvB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,CAAC;AAsWF,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAM1F;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyBjG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAsBtF"}