@openclaw/fs-safe 0.14.0 → 0.16.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.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,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"}
+{"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;AAGlE,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,CAgCA"}

package/dist/staged-directory.js

@@ -1,5 +1,6 @@
 import fs, {} from "node:fs";
 import path from "node:path";
+import { directoryReceiptAuthority, ownDirectoryReceipt } from "./directory-receipt.js";
 import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { nativePolicyDirectoryObserver, NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
@@ -116,16 +117,15 @@ export function refreshPolicyStagedDirectoryObservation(captured) {
     return checkedMutationDirectory(captured.directory.path, canonicalPath, current);
 }
 export function openStagedDirectory(directory) {
-    // Copy supplied facts before any asynchronous work; receipts are not authority.
-    const pathname = resolvePathPreservingWindowsRoot(typeof directory === "string" ? directory : directory.path);
-    const expected = typeof directory === "string" ? undefined : {
-        realPath: directory.realPath, dev: directory.identity.dev, ino: directory.identity.ino,
-    };
+    const expected = typeof directory === "string"
+        ? undefined
+        : directoryReceiptAuthority(ownDirectoryReceipt(directory));
+    const pathname = resolvePathPreservingWindowsRoot(typeof directory === "string" ? directory : expected.path);
     const before = fs.lstatSync(pathname, { bigint: true });
     if (!before.isDirectory()) {
         throw new FsSafeError("not-file", "staging parent must be a real directory");
     }
-    if (expected && (!exactIdentityMatches(expected, before) || realpathSync(pathname) !== expected.realPath)) {
+    if (expected && (!exactIdentityMatches(expected.identity, before) || realpathSync(pathname) !== expected.realPath)) {
         throw new FsSafeError("path-mismatch", "stale staging directory receipt");
     }
     const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);

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

@@ -0,0 +1,17 @@
+import type { BigIntStats } from "node:fs";
+import { FsSafeError } from "./errors.js";
+import type { StagedFileCleanupReceipt, StagedFileFailureDetails, StagedFilePublication, StagedFileReceipt } from "./staged-file-types.js";
+export declare function createStagedFileReceipt(directory: StagedFileReceipt["directory"], temporaryBasename: string, stat: BigIntStats): StagedFileReceipt;
+export declare function stagedFileFailure(error: unknown, details: StagedFileFailureDetails): FsSafeError;
+/** Finish owned cleanup and every close before surfacing publication evidence. */
+export declare function settleStagedFile(params: {
+    temporaryBasename: string;
+    publication: StagedFilePublication;
+    phase: StagedFileFailureDetails["phase"];
+    failure?: {
+        error: unknown;
+    };
+    cleanup: () => Promise<StagedFileCleanupReceipt["status"]>;
+    close: readonly (() => Promise<void> | void)[];
+}): Promise<void>;
+//# sourceMappingURL=staged-file-settlement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staged-file-settlement.d.ts","sourceRoot":"","sources":["../src/staged-file-settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,iBAAiB,EAAE,MAAM,EACzB,IAAI,EAAE,WAAW,GAChB,iBAAiB,CAUnB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAKhG;AAED,kFAAkF;AAClF,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,qBAAqB,CAAC;IACnC,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3D,KAAK,EAAE,SAAS,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;CAChD,GAAG,OAAO,CAAC,IAAI,CAAC,CAkChB"}

package/dist/staged-file-settlement.js

@@ -0,0 +1,57 @@
+import { FsSafeError } from "./errors.js";
+export function createStagedFileReceipt(directory, temporaryBasename, stat) {
+    return Object.freeze({
+        directory,
+        temporaryBasename,
+        identity: Object.freeze({
+            dev: stat.dev, ino: stat.ino, mode: Number(stat.mode & 4095n),
+            nlink: stat.nlink, size: stat.size, uid: Number(stat.uid), gid: Number(stat.gid),
+            mtimeNs: stat.mtimeNs, ctimeNs: stat.ctimeNs,
+        }),
+    });
+}
+export function stagedFileFailure(error, details) {
+    const code = error instanceof FsSafeError
+        ? error.code
+        : error?.code === "EEXIST" ? "already-exists" : "helper-failed";
+    return new FsSafeError(code, `staged file ${details.phase} failed`, { cause: error, details });
+}
+/** Finish owned cleanup and every close before surfacing publication evidence. */
+export async function settleStagedFile(params) {
+    const errors = params.failure ? [params.failure.error] : [];
+    let status;
+    try {
+        status = await params.cleanup();
+    }
+    catch (error) {
+        status = "failed";
+        errors.push(error);
+    }
+    let resources = "closed";
+    for (const close of params.close) {
+        try {
+            await close();
+        }
+        catch (error) {
+            resources = "close-failed";
+            errors.push(error);
+        }
+    }
+    const incomplete = status === "failed" || status === "preserved" || resources === "close-failed";
+    // A settled pre-publication failure retains the producer/authority rejection exactly.
+    if (!incomplete && (!params.failure || params.publication.status === "not-published"))
+        return;
+    const error = errors.length > 1 ? new AggregateError(errors, "staged operation and settlement failed")
+        : errors.length === 1 ? errors[0] : new FsSafeError("not-removable", "staged cleanup preserved an unverified entry");
+    const cleanup = Object.freeze({
+        temporaryBasename: params.temporaryBasename,
+        publication: params.publication,
+        status,
+        resources,
+    });
+    throw stagedFileFailure(error, {
+        phase: params.failure ? params.phase : "cleanup",
+        publication: params.publication,
+        cleanup,
+    });
+}

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

@@ -1 +1 @@
-{"version":3,"file":"temp-workspace-descriptor.d.ts","sourceRoot":"","sources":["../src/temp-workspace-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAU7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAMhF,OAAO,EAML,KAAK,yBAAyB,EAC/B,MAAM,8BAA8B,CAAC;AAEtC,KAAK,yBAAyB,GAAG,MAAM,GAAG,QAAQ,CAAC;AASnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,yBAAyB,CAAC;IAClC,OAAO,EAAE,QAAQ,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClD,CAAC,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAmDpD,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,0BAA0B,GACpC,iBAAiB,CA8BnB;AAED,+EAA+E;AAC/E,qBAAa,0BAA0B;;IAWrC,OAAO,eAqBN;IAED,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,0BAA0B,CAcjF;IAED,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;QACjC,QAAQ,EAAE,0BAA0B,CAAC;QACrC,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC;KAC1B,CAoBA;IAED,qBAAqB,IAAI,IAAI,CAE5B;IAUD,iBAAiB,CACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,GACX,yBAAyB,CAsB3B;IAoEK,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,IAAI,GACvB,OAAO,CAAC,IAAI,CAAC,CAgCf;IAED,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,IAAI,GACvB,IAAI,CAsBN;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,cAAc,IAAI,OAAO,CAmDxB;IAED,QAAQ,CAAC,gBAAgB,EAAE,OAAO,GAAG;QACnC,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,QAAQ,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjD,SAAS,EAAE,sBAAsB,GAAG,SAAS,CAAC;KAC/C,CAiCA;IAED,KAAK,IAAI,IAAI,CAOZ;CACF"}
+{"version":3,"file":"temp-workspace-descriptor.d.ts","sourceRoot":"","sources":["../src/temp-workspace-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAU7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAMhF,OAAO,EAML,KAAK,yBAAyB,EAC/B,MAAM,8BAA8B,CAAC;AAEtC,KAAK,yBAAyB,GAAG,MAAM,GAAG,QAAQ,CAAC;AASnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,yBAAyB,CAAC;IAClC,OAAO,EAAE,QAAQ,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClD,CAAC,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAmDpD,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,0BAA0B,GACpC,iBAAiB,CA8BnB;AAED,+EAA+E;AAC/E,qBAAa,0BAA0B;;IAWrC,OAAO,eAqBN;IAED,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,0BAA0B,CAcjF;IAED,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;QACjC,QAAQ,EAAE,0BAA0B,CAAC;QACrC,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC;KAC1B,CAoBA;IAED,qBAAqB,IAAI,IAAI,CAE5B;IAUD,iBAAiB,CACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,GACX,yBAAyB,CAsB3B;IAgEK,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,IAAI,GACvB,OAAO,CAAC,IAAI,CAAC,CAgCf;IAED,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,IAAI,GACvB,IAAI,CAsBN;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,cAAc,IAAI,OAAO,CA2CxB;IAED,QAAQ,CAAC,gBAAgB,EAAE,OAAO,GAAG;QACnC,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,QAAQ,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjD,SAAS,EAAE,sBAAsB,GAAG,SAAS,CAAC;KAC/C,CA0BA;IAED,KAAK,IAAI,IAAI,CAOZ;CACF"}