@openclaw/fs-safe 0.7.2 → 0.8.1

package/dist/secret-file.js

@@ -1,18 +1,20 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { normalizeMaxBytes } from "./byte-budget.js";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
+import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
+import { assertOwnedDirectory } from "./directory-mode-owner.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
-import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
+import { ensureTrailingSep } from "./root-context.js";
+import { verifyAtomicWriteResult } from "./root-write-verification.js";
 import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
-import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { serializePathWrite } from "./write-queue.js";
 export const PRIVATE_SECRET_DIR_MODE = 0o700;
 export const PRIVATE_SECRET_FILE_MODE = 0o600;
@@ -104,95 +106,131 @@ function assertRealPathWithinRoot(rootDir, targetPath) {
         throw new Error(`Private secret path must stay under ${rootDir}.`);
     }
 }
-async function enforcePrivatePathMode(resolvedPath, expectedMode, kind) {
-    if (process.platform === "win32") {
-        return;
+async function createPrivateDirectory(directory, mode) {
+    try {
+        await fsp.mkdir(directory, { mode });
+        return true;
     }
-    await fsp.chmod(resolvedPath, expectedMode);
-    const stat = await fsp.stat(resolvedPath);
-    const actualMode = stat.mode & 0o777;
-    if (actualMode !== expectedMode) {
-        throw new Error(`Private secret ${kind} ${resolvedPath} has insecure permissions ${actualMode.toString(8)}.`);
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
     }
 }
-async function enforcePrivateFileIdentityAndMode(resolvedPath, expectedIdentity, expectedMode) {
-    const handle = await fsp.open(resolvedPath, resolveReadOpenFlags());
-    try {
-        const openedStat = await handle.stat();
-        if (!openedStat.isFile() || !sameFileIdentity(openedStat, expectedIdentity)) {
-            throw new FsSafeError("path-mismatch", "private secret file changed during write");
-        }
-        const pathStat = await fsp.lstat(resolvedPath);
-        if (pathStat.isSymbolicLink() || !sameFileIdentity(pathStat, openedStat)) {
-            throw new FsSafeError("path-mismatch", "private secret path changed during write");
-        }
-        if (process.platform !== "win32") {
-            await handle.chmod(expectedMode);
-            const chmodStat = await handle.stat();
-            const actualMode = chmodStat.mode & 0o777;
-            if (actualMode !== expectedMode) {
-                throw new Error(`Private secret file ${resolvedPath} has insecure permissions ${actualMode.toString(8)}.`);
-            }
-            const refreshedPathStat = await fsp.lstat(resolvedPath);
-            if (refreshedPathStat.isSymbolicLink() || !sameFileIdentity(refreshedPathStat, chmodStat)) {
-                throw new FsSafeError("path-mismatch", "private secret path changed during mode check");
-            }
+async function enforcePrivateDirectoryMode(params) {
+    if (process.platform === "win32")
+        return;
+    const stat = await inspectDirectoryIdentity(params.realPath, params.identity);
+    if (!params.created) {
+        const actualMode = Number(stat.mode & 4095n);
+        if (actualMode !== params.mode) {
+            throw new FsSafeError("insecure-permissions", `Private secret directory ${JSON.stringify(params.realPath)} has insecure permissions ${actualMode.toString(8)}.`);
         }
+        return;
+    }
+    const ownerUid = process.geteuid?.();
+    if (ownerUid === undefined) {
+        throw new FsSafeError("helper-unavailable", "secret directory initialization requires owner identity");
+    }
+    const owner = await pinNodeDirectoryForMode(params.realPath, {
+        expectedIdentity: params.identity,
+        ownerUid,
+    });
+    try {
+        await owner.apply(params.mode, { beforeChmod: params.beforeChmod });
     }
     finally {
-        await handle.close().catch(() => undefined);
+        await owner.close();
     }
 }
+async function inspectPrivateDirectory(directory, kind) {
+    return await inspectFileIdentity(async () => {
+        const stat = await fsp.lstat(directory, { bigint: true });
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Private secret ${kind} ${directory} must not be a symlink.`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`Private secret ${kind} ${directory} must be a directory.`);
+        }
+        return stat;
+    });
+}
 async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     const resolvedRoot = path.resolve(rootDir);
     const resolvedTarget = path.resolve(targetDir);
-    await fsp.mkdir(resolvedRoot, { recursive: true, mode });
-    const rootStat = await fsp.lstat(resolvedRoot);
-    if (rootStat.isSymbolicLink()) {
-        throw new Error(`Private secret root ${resolvedRoot} must not be a symlink.`);
-    }
-    if (!rootStat.isDirectory()) {
-        throw new Error(`Private secret root ${resolvedRoot} must be a directory.`);
+    let rootStat = await inspectPrivateDirectory(resolvedRoot, "root").catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+        return undefined;
+    });
+    let createdRoot = false;
+    if (!rootStat) {
+        try {
+            createdRoot = await createPrivateDirectory(resolvedRoot, mode);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await fsp.mkdir(path.dirname(resolvedRoot), { recursive: true, mode });
+            createdRoot = await createPrivateDirectory(resolvedRoot, mode);
+        }
+        rootStat = await inspectPrivateDirectory(resolvedRoot, "root");
     }
-    const rootGuard = await createAsyncDirectoryGuard(resolvedRoot);
-    await enforcePrivatePathMode(rootGuard.realPath, mode, "directory");
+    const rootGuard = await createAsyncDirectoryGuard(resolvedRoot, { bigint: true });
+    assertOwnedDirectory(rootStat, rootGuard.stat);
+    await enforcePrivateDirectoryMode({
+        realPath: rootGuard.realPath, identity: rootStat, mode, created: createdRoot,
+        beforeChmod: () => assertAsyncDirectoryGuard(rootGuard),
+    });
     await assertAsyncDirectoryGuard(rootGuard);
     if (resolvedTarget === resolvedRoot) {
-        return { rootGuard, targetReal: rootGuard.realPath };
+        return { rootGuard, parentGuard: rootGuard };
     }
     assertPathWithinRoot(resolvedRoot, resolvedTarget);
     const resolvedRootReal = rootGuard.realPath;
     let current = resolvedRoot;
+    let targetGuard = rootGuard;
     for (const segment of path
         .relative(resolvedRoot, resolvedTarget)
         .split(path.sep)
         .filter(Boolean)) {
         current = path.join(current, segment);
-        const parentGuard = await createAsyncDirectoryGuard(path.dirname(current));
-        await assertAsyncDirectoryGuard(rootGuard);
-        try {
-            const stat = await fsp.lstat(current);
-            if (stat.isSymbolicLink()) {
-                throw new Error(`Private secret directory component ${current} must not be a symlink.`);
-            }
-            if (!stat.isDirectory()) {
-                throw new Error(`Private secret directory component ${current} must be a directory.`);
+        const parentGuard = targetGuard;
+        let created = false;
+        let identity;
+        while (true) {
+            await assertAsyncDirectoryGuard(rootGuard);
+            await assertAsyncDirectoryGuard(parentGuard);
+            try {
+                identity = await inspectPrivateDirectory(current, "directory component");
+                break;
             }
-        }
-        catch (error) {
-            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
-                throw error;
+            catch (error) {
+                if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
+                    throw error;
+                }
+                await assertAsyncDirectoryGuard(parentGuard);
+                created = await createPrivateDirectory(current, mode);
+                // EEXIST grants no initialization authority; both outcomes need fresh type checks.
             }
-            await assertAsyncDirectoryGuard(parentGuard);
-            await fsp.mkdir(current, { mode });
         }
-        const currentReal = await fsp.realpath(current);
-        assertRealPathWithinRoot(resolvedRootReal, currentReal);
-        await enforcePrivatePathMode(currentReal, mode, "directory");
+        const currentGuard = await createAsyncDirectoryGuard(current, { bigint: true });
+        assertOwnedDirectory(identity, currentGuard.stat);
+        assertRealPathWithinRoot(resolvedRootReal, currentGuard.realPath);
+        await enforcePrivateDirectoryMode({
+            realPath: currentGuard.realPath, identity, mode, created,
+            beforeChmod: async () => {
+                await assertAsyncDirectoryGuard(parentGuard);
+                await assertAsyncDirectoryGuard(rootGuard);
+                await assertAsyncDirectoryGuard(currentGuard);
+            },
+        });
         await assertAsyncDirectoryGuard(parentGuard);
         await assertAsyncDirectoryGuard(rootGuard);
+        await assertAsyncDirectoryGuard(currentGuard);
+        targetGuard = currentGuard;
     }
-    return { rootGuard, targetReal: await fsp.realpath(resolvedTarget) };
+    return { rootGuard, parentGuard: targetGuard };
 }
 async function secretFileWriteQueueKey(filePath) {
     try {
@@ -203,19 +241,29 @@ async function secretFileWriteQueueKey(filePath) {
         return path.resolve(filePath);
     }
 }
-async function materializeSecretFileAtomic(params, createOnly) {
+// Internal preparation for private writers and their pre-write locks; not lasting authorization.
+export async function prepareSecretFileWrite(params) {
     const mode = params.mode ?? PRIVATE_SECRET_FILE_MODE;
     const dirMode = params.dirMode ?? PRIVATE_SECRET_DIR_MODE;
     const resolvedRoot = path.resolve(params.rootDir);
     const resolvedFile = path.resolve(params.filePath);
     assertPathWithinRoot(resolvedRoot, resolvedFile);
+    for (const [kind, value] of [["file", mode], ["directory", dirMode]]) {
+        if (!Number.isInteger(value) || value < 0 || value > 0o7777) {
+            throw new FsSafeError("invalid-path", `Private secret ${kind} mode must be an integer between 0o0000 and 0o7777.`);
+        }
+    }
     const intendedParentDir = path.dirname(resolvedFile);
-    const { rootGuard, targetReal } = await ensurePrivateDirectory(resolvedRoot, intendedParentDir, dirMode);
+    const { rootGuard, parentGuard } = await ensurePrivateDirectory(resolvedRoot, intendedParentDir, dirMode);
     await assertAsyncDirectoryGuard(rootGuard);
-    assertRealPathWithinRoot(rootGuard.realPath, targetReal);
-    const parentGuard = await createAsyncDirectoryGuard(targetReal);
+    await assertAsyncDirectoryGuard(parentGuard);
+    assertRealPathWithinRoot(rootGuard.realPath, parentGuard.realPath);
     const fileName = path.basename(resolvedFile);
-    const finalFilePath = path.join(targetReal, fileName);
+    const finalFilePath = path.join(parentGuard.realPath, fileName);
+    return { mode, rootGuard, parentGuard, fileName, finalFilePath };
+}
+async function materializeSecretFileAtomic(params, createOnly) {
+    const { mode, rootGuard, parentGuard, fileName, finalFilePath } = await prepareSecretFileWrite(params);
     try {
         const stat = await fsp.lstat(finalFilePath);
         if (createOnly) {
@@ -235,7 +283,7 @@ async function materializeSecretFileAtomic(params, createOnly) {
     }
     await assertAsyncDirectoryGuard(rootGuard);
     await assertAsyncDirectoryGuard(parentGuard);
-    const identity = await runPinnedWriteHelper({
+    await runPinnedWriteHelper({
         rootPath: parentGuard.realPath,
         relativeParentPath: "",
         basename: fileName,
@@ -244,10 +292,24 @@ async function materializeSecretFileAtomic(params, createOnly) {
         overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
         rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
+        verifyPublished: async (fd, expectedIdentity, publishedParentGuard) => {
+            await assertAsyncDirectoryGuard(rootGuard);
+            await assertAsyncDirectoryGuard(parentGuard);
+            await verifyAtomicWriteResult({
+                root: {
+                    rootDir: rootGuard.dir,
+                    rootReal: rootGuard.realPath,
+                    rootWithSep: ensureTrailingSep(rootGuard.realPath),
+                    rootIdentity: { dev: rootGuard.stat.dev, ino: rootGuard.stat.ino },
+                },
+                targetPath: finalFilePath,
+                fd,
+                expectedIdentity,
+                expectedMode: mode,
+                parentGuard: publishedParentGuard,
+            });
+        },
     });
-    await assertAsyncDirectoryGuard(rootGuard);
-    await assertAsyncDirectoryGuard(parentGuard);
-    await enforcePrivateFileIdentityAndMode(finalFilePath, identity, mode);
 }
 export async function writeSecretFileAtomic(params) {
     const canonicalPath = await secretFileWriteQueueKey(params.filePath);

package/dist/sibling-temp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uGAAuG;IACvG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AASF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAoBxC;AAkBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0ChB"}
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uGAAuG;IACvG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AASF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAoBxC;AAwBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0ChB"}

package/dist/sibling-temp.js

@@ -2,7 +2,7 @@ import crypto, { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
-import { sanitizeUntrustedFileName } from "./filename.js";
+import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./filename.js";
 import { applyDirectoryMode } from "./replace-file-descriptor.js";
 import { root } from "./root.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
@@ -42,8 +42,14 @@ function buildSiblingTempPath(params) {
     const safePrefix = assertSafePathPrefix(params.tempPrefix, {
         label: "sibling temp prefix",
     });
-    const safeTail = sanitizeUntrustedFileName(path.basename(params.targetPath), params.fallbackFileName);
-    return path.join(path.dirname(params.targetPath), `${safePrefix}${id}-${safeTail}.part`);
+    const prefix = `${safePrefix}${id}-`;
+    const suffix = ".part";
+    const safeTail = fitFileNameToPortableComponent({
+        prefix,
+        fileName: sanitizeUntrustedFileName(path.basename(params.targetPath), params.fallbackFileName),
+        suffix,
+    });
+    return path.join(path.dirname(params.targetPath), `${prefix}${safeTail}${suffix}`);
 }
 export async function writeViaSiblingTempPath(params) {
     const rootDir = await fs

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

@@ -13,6 +13,7 @@ export type HeldSidecarLock = {
     metadata: Record<string, unknown>;
     releasePromise?: Promise<void>;
     lockRoot?: Root;
+    retainOnExit?: boolean;
     parsePayload?: (raw: string) => unknown;
     compromiseTimer?: NodeJS.Timeout;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAKA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAS3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAaF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CA4S5B"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAOA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAS3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAqBF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAqT5B"}

package/dist/sidecar-lock-acquire.js

@@ -1,15 +1,25 @@
 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 { createSuppressedError } from "./suppressed-error.js";
-async function resolveNormalizedTargetPath(targetPath) {
+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));
@@ -23,7 +33,7 @@ export async function acquireSidecarLock(options, context) {
     validateSidecarLockRetryOptions(retry);
     validateSidecarLockTimeoutMs(options.timeoutMs);
     context.ensureExitCleanupRegistered();
-    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
+    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath, options.lockRoot);
     const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
     let held = context.held.get(normalizedTargetPath);
     if (held &&
@@ -43,11 +53,15 @@ export async function acquireSidecarLock(options, context) {
             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);
         }
     }
     const startedAt = Date.now();
-    const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
     const reclaimGuardPath = `${lockPath}.reclaim`;
     let ownsReclaimGuard = false;
     let attempt = 0;
@@ -59,7 +73,7 @@ export async function acquireSidecarLock(options, context) {
         if ((options.timeoutMs !== undefined &&
             options.timeoutMs !== Number.POSITIVE_INFINITY &&
             elapsed >= options.timeoutMs) ||
-            (maxRetries !== undefined && attempt >= maxRetries)) {
+            (retry.retries !== undefined && attempt >= retry.retries)) {
             throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
                 code: "file_lock_timeout",
                 lockPath,
@@ -101,10 +115,14 @@ export async function acquireSidecarLock(options, context) {
                 if (options.lockRoot) {
                     const lockRoot = options.lockRoot;
                     const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
+                    const observation = fileObservation();
                     try {
-                        await lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
+                        await observation.run(() => lockRoot.create(relativeLockPath, raw, { 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") {
                             throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
                         }
@@ -157,6 +175,7 @@ export async function acquireSidecarLock(options, context) {
                     acquiredAt: Date.now(),
                     metadata: options.metadata ?? {},
                     lockRoot: options.lockRoot,
+                    retainOnExit: options.retainOnExit,
                     parsePayload: options.parsePayload,
                 };
                 context.held.set(normalizedTargetPath, createdHeld);

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}

package/dist/sidecar-lock-reclaim.js

@@ -30,10 +30,12 @@ export function readSidecarLockOwnershipToken(raw) {
 }
 export function serializeSidecarLockPayload(payload) {
     const ownershipToken = createSidecarLockOwnershipToken();
-    return {
-        raw: `${JSON.stringify(payload, null, 2)}\n${ownershipToken}\n`,
-        ownershipToken,
-    };
+    const raw = `${JSON.stringify(payload, null, 2)}\n${ownershipToken}\n`;
+    const bytes = Buffer.byteLength(raw, "utf8");
+    if (bytes > MAX_LOCK_PAYLOAD_BYTES) {
+        throw new FsSafeError("too-large", `sidecar lock payload exceeds limit of ${MAX_LOCK_PAYLOAD_BYTES} bytes (got ${bytes})`);
+    }
+    return { raw, ownershipToken };
 }
 export function relativeSidecarLockPath(lockRoot, lockPath) {
     const resolved = path.resolve(lockPath);

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

@@ -33,6 +33,13 @@ export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>>
     metadata?: Record<string, unknown>;
     parsePayload?: (raw: string) => unknown;
     lockRoot?: Root;
+    /**
+     * Keep the lock file when the process exits naturally. Default `false`:
+     * process-exit handlers release held locks. Set only for deliberately
+     * retained ownership records (for example, fail-closed build locks) whose
+     * liveness is governed by the caller's own stale policy.
+     */
+    retainOnExit?: boolean;
     onCompromised?: (info: SidecarLockCompromisedInfo) => void;
     compromiseCheckIntervalMs?: number;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-types.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAE1E,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,aAAa,GAAG,qBAAqB,CAAC;AAE7E,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC3D,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC"}
+{"version":3,"file":"sidecar-lock-types.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-types.ts"],"names":[],"mappings":"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"}

package/dist/sidecar-lock.d.ts

@@ -1,6 +1,8 @@
 import type { SidecarLockAcquireOptions, SidecarLockHandle, SidecarLockHeldEntry, WithSidecarLockOptions } from "./sidecar-lock-types.js";
 export type { SidecarLockStaleSnapshot } from "./sidecar-lock-reclaim.js";
 export type { SidecarLockAcquireOptions, SidecarLockCompromisedInfo, SidecarLockHandle, SidecarLockHeldEntry, SidecarLockRetryOptions, SidecarLockStaleRecovery, WithSidecarLockOptions, } from "./sidecar-lock-types.js";
+/** True when a retain-unaware package copy registered the process-exit handlers first. */
+export declare function exitCleanupCannotRetain(): boolean;
 export declare function createSidecarLockManager(key: string): {
     acquire: <TPayload extends Record<string, unknown>>(options: SidecarLockAcquireOptions<TPayload>) => Promise<SidecarLockHandle>;
     withLock: <T, TPayload extends Record<string, unknown>>(options: SidecarLockAcquireOptions<TPayload>, fn: () => Promise<T>) => Promise<T>;

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAUA,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;AAsLjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAS3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAYL,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;AAqIjC,0FAA0F;AAC1F,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAuFD,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"}

package/dist/sidecar-lock.js

@@ -1,4 +1,5 @@
 import fsSync from "node:fs";
+import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { removeSidecarLockIfUnchanged, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
 import { acquireSidecarLock } from "./sidecar-lock-acquire.js";
@@ -7,6 +8,11 @@ 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_BEFORE_EXIT_KEY = Symbol.for("fsSafe.sidecarLockBeforeExitCleanup");
+// 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.
+const GLOBAL_RETAIN_AWARE_KEY = Symbol.for("fsSafe.sidecarLockRetainAwareCleanup");
 function getGlobalManagers() {
     const globalWithState = globalThis;
     if (!globalWithState[GLOBAL_STATE_KEY]) {
@@ -89,11 +95,12 @@ function releaseAllReclaimGuardsSync(state) {
         }
     }
 }
-function releaseAllLocksSync(state) {
+function releaseAllLocksSync(state, options) {
     for (const [normalizedTargetPath, held] of state.held) {
         void held.handle.close().catch(() => undefined);
         try {
-            if (!held.lockRoot && snapshotMatchesSync(held.lockPath, held.snapshot)) {
+            const retained = options?.preserveRetained === true && held.retainOnExit;
+            if (!retained && !held.lockRoot && snapshotMatchesSync(held.lockPath, held.snapshot)) {
                 fsSync.rmSync(held.lockPath, { force: true });
             }
         }
@@ -109,14 +116,43 @@ function ensureGlobalExitCleanupRegistered() {
     if (globalWithCleanup[GLOBAL_CLEANUP_KEY])
         return;
     globalWithCleanup[GLOBAL_CLEANUP_KEY] = true;
+    globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] = true;
     const cleanup = () => {
         for (const state of getGlobalManagers().values()) {
-            releaseAllLocksSync(state);
+            releaseAllLocksSync(state, { preserveRetained: true });
         }
     };
     globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
     process.on("exit", cleanup);
 }
+/** True when a retain-unaware package copy registered the process-exit handlers first. */
+export function exitCleanupCannotRetain() {
+    const globalWithCleanup = globalThis;
+    return globalWithCleanup[GLOBAL_CLEANUP_KEY] === true && globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] !== true;
+}
+function ensureGlobalBeforeExitCleanupRegistered() {
+    const globalWithCleanup = globalThis;
+    if (globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY]) {
+        return globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY];
+    }
+    // Independent of the exit registration, which an older package copy may own.
+    const lifecycle = { armed: false };
+    globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] = lifecycle;
+    process.on("beforeExit", () => {
+        if (!lifecycle.armed)
+            return;
+        // Cleanup itself schedules I/O; retry only after another acquisition.
+        lifecycle.armed = false;
+        for (const state of getGlobalManagers().values()) {
+            for (const [normalizedTargetPath, held] of Array.from(state.held.entries())) {
+                if (held.lockRoot && !held.retainOnExit) {
+                    void releaseHeldLock(state, normalizedTargetPath, held, { force: true }).catch(() => undefined);
+                }
+            }
+        }
+    });
+    return lifecycle;
+}
 async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
     const current = state.held.get(normalizedTargetPath);
     if (current !== held) {
@@ -158,6 +194,7 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
     }
 }
 function handleForHeldLock(state, normalizedTargetPath, held) {
+    ensureGlobalBeforeExitCleanupRegistered().armed = true;
     return createHeldSidecarLockHandle({
         normalizedTargetPath,
         held,
@@ -170,8 +207,12 @@ export function createSidecarLockManager(key) {
         state.cleanupRegistered = true;
         state.reclaimCleanupRegistered = true;
         ensureGlobalExitCleanupRegistered();
+        ensureGlobalBeforeExitCleanupRegistered().armed = true;
     }
     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,
             reclaimGuards: state.reclaimGuards,

package/dist/write-open-flags.d.ts

@@ -0,0 +1,5 @@
+import fsSync from "node:fs";
+export declare function resolveNonblockingWriteFlag(constants?: Partial<Pick<typeof fsSync.constants, "O_NONBLOCK">>): number;
+export declare function isNonRegularWriteOpenError(error: unknown, filePath: string, flags: number): Promise<boolean>;
+export declare function isNonRegularWriteOpenErrorSync(error: unknown, filePath: string, flags: number): boolean;
+//# sourceMappingURL=write-open-flags.d.ts.map

package/dist/write-open-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}