@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/secure-file.js

@@ -1,15 +1,15 @@
-import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileHandleBounded } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
 import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-access.js";
 import { isPathInside, isSymlinkOpenError } from "./path.js";
+import { formatPermissionErrorDetail } from "./permission-exec.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, } from "./permissions.js";
-const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
-const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
+import { inspectFileIdentity } from "./strict-file-identity.js";
 function isAbsolutePathname(value) {
     return (path.isAbsolute(value) ||
         (process.platform === "win32" &&
@@ -18,7 +18,7 @@ function isAbsolutePathname(value) {
 function label(options) {
     return options.label ?? "Secure file";
 }
-async function openSecureHandle(options) {
+async function openSecureHandle(options, maxBytes) {
     assertNoUnsafeDeviceReadPath(options.filePath);
     if (isWindowsNetworkPath(options.filePath, "win32") && !options.trust?.allowNetworkPath) {
         throw new FsSafeError("invalid-path", `${label(options)} must be a local absolute path.`);
@@ -31,15 +31,19 @@ async function openSecureHandle(options) {
             cause: err,
         });
     });
-    if (preStat.isDirectory()) {
-        throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
+    if (preStat.isSymbolicLink()) {
+        if (!options.trust?.allowSymlink) {
+            throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+        }
     }
-    if (preStat.isSymbolicLink() && !options.trust?.allowSymlink) {
-        throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+    else if (!preStat.isFile()) {
+        throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
     }
     let handle;
     try {
-        handle = await fs.open(options.filePath, options.trust?.allowSymlink ? fsConstants.O_RDONLY : OPEN_READ_FLAGS);
+        handle = await fs.open(options.filePath, resolveReadOpenFlags({
+            followSymlinks: options.trust?.allowSymlink === true,
+        }));
     }
     catch (err) {
         if (isSymlinkOpenError(err)) {
@@ -52,22 +56,20 @@ async function openSecureHandle(options) {
         if (!openedStat.isFile()) {
             throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
         }
-        const pathStat = options.trust?.allowSymlink
-            ? await fs.stat(options.filePath)
-            : await fs.lstat(options.filePath);
-        if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
-        }
-        if (!sameFileIdentity(pathStat, openedStat)) {
-            throw new FsSafeError("path-mismatch", `${label(options)} changed during open.`);
-        }
+        const openedIdentity = await inspectFileIdentity(() => handle.stat({ bigint: true }));
+        await inspectFileIdentity(async () => {
+            const pathStat = options.trust?.allowSymlink
+                ? await fs.stat(options.filePath, { bigint: true })
+                : await fs.lstat(options.filePath, { bigint: true });
+            if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
+                throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+            }
+            return pathStat;
+        }, openedIdentity);
         const realPath = await fs.realpath(options.filePath);
-        const realStat = await fs.stat(realPath);
-        if (!sameFileIdentity(realStat, openedStat)) {
-            throw new FsSafeError("path-mismatch", `${label(options)} real path changed during open.`);
-        }
-        if (options.io?.maxBytes !== undefined && openedStat.size > options.io.maxBytes) {
-            throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${options.io.maxBytes}).`);
+        await inspectFileIdentity(() => fs.stat(realPath, { bigint: true }), openedIdentity);
+        if (maxBytes !== undefined && openedStat.size > maxBytes) {
+            throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${maxBytes}).`);
         }
         return { handle, pathStat: openedStat, realPath };
     }
@@ -111,11 +113,21 @@ async function assertSecurePermissions(options, stat, realPath) {
     const permissions = platform === "win32"
         ? await inspectPathPermissions(realPath, options.inject)
         : inspectOpenedPermissions(stat, platform);
+    const reason = permissions.error ? `: ${formatPermissionErrorDetail(permissions.error)}` : "";
+    const diagnostics = {
+        ...(permissions.errorCause !== undefined ? { cause: permissions.errorCause } : {}),
+        ...(permissions.ownerError || permissions.errorDetail ? {
+            details: {
+                ...(permissions.ownerError ? { ownerError: formatPermissionErrorDetail(permissions.ownerError) } : {}),
+                ...permissions.errorDetail,
+            },
+        } : {}),
+    };
     if (!permissions.ok) {
-        throw new FsSafeError("permission-unverified", `${label(options)} permissions could not be verified: ${realPath}`);
+        throw new FsSafeError("permission-unverified", `${label(options)} permissions could not be verified: ${realPath}${reason}`, diagnostics);
     }
     if (platform === "win32" && permissions.source === "unknown") {
-        throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}.`);
+        throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}${reason || "."}`, diagnostics);
     }
     if (platform === "win32" && permissions.ownerTrusted !== true) {
         throw new FsSafeError(permissions.ownerTrusted === false ? "not-owned" : "permission-unverified", `${label(options)} owner could not be trusted on Windows: ${realPath}`);
@@ -156,11 +168,12 @@ async function readHandleWithTimeout(handle, timeoutMs, maxBytes) {
     }
 }
 export async function readSecureFile(options) {
-    const opened = await openSecureHandle(options);
+    const maxBytes = normalizeMaxBytes(options.io?.maxBytes);
+    const opened = await openSecureHandle(options, maxBytes);
     try {
         await assertTrustedDirs(options, opened.realPath);
         const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath);
-        const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, options.io?.maxBytes);
+        const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, maxBytes);
         return { buffer, realPath: opened.realPath, stat: opened.pathStat, permissions };
     }
     finally {

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

@@ -0,0 +1,15 @@
+export declare function writeCallbackSibling<T>(params: {
+    tempPath: string;
+    write: (tempPath: string) => Promise<T>;
+    resolveFinalPath: (result: T) => string;
+    mode?: number;
+    /** Preserve the caller's historical best-effort mode behavior. */
+    ignoreModeError?: boolean;
+    maxBytes?: number;
+    syncTempFile: boolean;
+    syncParentDir: boolean;
+}): Promise<{
+    filePath: string;
+    result: T;
+}>;
+//# sourceMappingURL=sibling-staged-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAkCA,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CA6G3C"}

package/dist/sibling-staged-file.js

@@ -0,0 +1,148 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+import { serializePathWrite } from "./write-queue.js";
+function assertRegularFile(stat) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "symlink sibling temp not allowed");
+    }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "sibling temp must be a regular file");
+    }
+    if (stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", "sibling temp must have exactly one link");
+    }
+}
+async function inspectStage(inspect, expected) {
+    return await inspectFileIdentity(async () => {
+        const stat = await inspect();
+        assertRegularFile(stat);
+        return stat;
+    }, expected);
+}
+// Callback paths are not owned until all three admission observations agree.
+// Keep one descriptor and one exact identity through mode, sync, rename and cleanup.
+// Read/write access is needed only when the caller requests file synchronization.
+export async function writeCallbackSibling(params) {
+    const parent = path.dirname(params.tempPath);
+    const guard = await createAsyncDirectoryGuard(parent);
+    const parentIdentity = await inspectFileIdentity(() => fs.lstat(parent, { bigint: true }));
+    const assertParent = async () => {
+        await assertAsyncDirectoryGuard(guard);
+        await inspectFileIdentity(() => fs.lstat(parent, { bigint: true }), parentIdentity);
+    };
+    let handle;
+    let identity;
+    let unregister;
+    let renamed = false;
+    let failure;
+    const inspectPath = (pathname, expected) => inspectStage(() => fs.lstat(pathname, { bigint: true }), expected);
+    const assertCurrent = async (pathname) => {
+        await assertParent();
+        const opened = await inspectStage(() => handle.stat({ bigint: true }), identity);
+        const current = await inspectPath(pathname, opened);
+        if (params.maxBytes !== undefined &&
+            (opened.size > params.maxBytes || current.size > params.maxBytes)) {
+            throw new FsSafeError("too-large", `sibling temp exceeds maxBytes (${params.maxBytes})`);
+        }
+    };
+    try {
+        const result = await params.write(params.tempPath);
+        await assertParent();
+        const before = await inspectPath(params.tempPath);
+        try {
+            // No create/truncate flags; O_NONBLOCK also bounds a FIFO swap during open.
+            const access = params.syncTempFile ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
+            handle = await fs.open(params.tempPath, access | resolveReadOpenFlags());
+        }
+        catch (error) {
+            if (error?.code === "ELOOP") {
+                throw new FsSafeError("symlink", "symlink sibling temp not allowed", { cause: error });
+            }
+            throw error;
+        }
+        const opened = await inspectStage(() => handle.stat({ bigint: true }), before);
+        await inspectPath(params.tempPath, opened);
+        await assertParent();
+        identity = opened;
+        unregister = registerTempPathForExit(params.tempPath, { identity, singleLinkFile: true });
+        const filePath = path.resolve(params.resolveFinalPath(result));
+        if (path.dirname(filePath) !== parent) {
+            throw new Error("Final path must be in the sibling temp directory.");
+        }
+        if (filePath === params.tempPath) {
+            throw new FsSafeError("invalid-path", "final path must differ from the sibling temp path");
+        }
+        await serializePathWrite(filePath, async () => {
+            await assertCurrent(params.tempPath);
+            if (params.mode !== undefined) {
+                try {
+                    await handle.chmod(params.mode);
+                }
+                catch (error) {
+                    if (!params.ignoreModeError)
+                        throw error;
+                }
+            }
+            if (params.syncTempFile) {
+                await assertCurrent(params.tempPath);
+                try {
+                    await handle.sync();
+                }
+                catch (error) {
+                    if (error?.code !== "EPERM")
+                        throw error;
+                }
+            }
+            await assertCurrent(params.tempPath);
+            await fs.rename(params.tempPath, filePath);
+            // A later verification failure never authorizes rollback of the final name.
+            renamed = true;
+            unregister();
+            await assertCurrent(filePath);
+            if (params.syncParentDir)
+                await syncDirectoryBestEffort(parent);
+            await assertCurrent(filePath);
+        });
+        return { filePath, result };
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        try {
+            if (!renamed && identity) {
+                try {
+                    await assertParent();
+                    await inspectStage(() => handle.stat({ bigint: true }), identity);
+                    await inspectPath(params.tempPath, identity);
+                    await fs.unlink(params.tempPath);
+                    unregister?.();
+                }
+                catch (error) {
+                    // Preserve observed substitutes; retry only operational cleanup failures.
+                    if (error instanceof FsSafeError || error?.code === "ENOENT") {
+                        unregister?.();
+                    }
+                }
+            }
+        }
+        finally {
+            try {
+                await handle?.close();
+            }
+            catch (error) {
+                if (failure)
+                    throw new AggregateError([failure.error, error], "sibling publication and close failed");
+                throw error;
+            }
+        }
+    }
+}

package/dist/sibling-temp.d.ts

@@ -5,8 +5,11 @@ export type WriteSiblingTempFileOptions<T> = {
     tempPrefix?: string;
     dirMode?: number;
     chmodDir?: boolean;
+    /** Final file mode; omitted preserves the producer's mode. Applied through the retained descriptor. */
     mode?: number;
+    /** Sync the staged descriptor before rename; defaults to false. */
     syncTempFile?: boolean;
+    /** Best-effort parent directory sync after rename; defaults to false. */
     syncParentDir?: boolean;
 };
 export type WriteSiblingTempFileResult<T> = {

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

@@ -1 +1 @@
-{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAcA,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,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,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;AA8BF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CA0CxC;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,CA8ChB"}
+{"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"}

package/dist/sibling-temp.js

@@ -2,85 +2,40 @@ 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 { syncDirectoryBestEffort } from "./directory-durability.js";
-import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { sanitizeUntrustedFileName } from "./filename.js";
+import { applyDirectoryMode } from "./replace-file-descriptor.js";
 import { root } from "./root.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
-import { registerTempPathForExit } from "./temp-cleanup.js";
+import { writeCallbackSibling } from "./sibling-staged-file.js";
+import { tempFile } from "./temp-target.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { serializePathWrite } from "./write-queue.js";
 function buildTempPath(dir, tempPrefix) {
     const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-stream", {
         label: "sibling temp prefix",
     });
     return path.join(dir, `${safePrefix}.${process.pid}.${randomUUID()}.tmp`);
 }
-async function syncFileBestEffort(filePath) {
-    const handle = await fs.open(filePath, "r+");
-    try {
-        await handle.sync();
-    }
-    catch (error) {
-        if (error.code !== "EPERM") {
-            throw error;
-        }
-    }
-    finally {
-        await handle.close();
-    }
-}
-function assertFinalPathIsSibling(dir, filePath) {
-    const resolvedDir = path.resolve(dir);
-    const resolvedFile = path.resolve(filePath);
-    if (path.dirname(resolvedFile) !== resolvedDir) {
-        throw new Error("Final path must be in the sibling temp directory.");
-    }
-}
 export async function writeSiblingTempFile(options) {
     const dir = path.resolve(options.dir);
     await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o700 });
     if (options.chmodDir !== false) {
-        await fs.chmod(dir, options.dirMode ?? 0o700).catch(() => undefined);
-    }
-    const dirGuard = await createAsyncDirectoryGuard(dir);
-    const tempPath = buildTempPath(dir, options.tempPrefix);
-    const unregisterTempPath = registerTempPathForExit(tempPath);
-    let tempExists = false;
-    try {
-        tempExists = true;
-        const result = await options.writeTemp(tempPath);
-        unregisterTempPath.setIdentity(await fs.lstat(tempPath, { bigint: true }));
-        if (options.mode !== undefined) {
-            await fs.chmod(tempPath, options.mode).catch(() => undefined);
-        }
-        if (options.syncTempFile) {
-            await syncFileBestEffort(tempPath);
-        }
-        const filePath = path.resolve(options.resolveFinalPath(result));
-        assertFinalPathIsSibling(dir, filePath);
-        await serializePathWrite(filePath, async () => {
-            await withAsyncDirectoryGuards([dirGuard], async () => {
-                await fs.rename(tempPath, filePath);
-            });
-            tempExists = false;
-            unregisterTempPath();
-            if (options.mode !== undefined) {
-                await fs.chmod(filePath, options.mode).catch(() => undefined);
-            }
-            if (options.syncParentDir) {
-                await syncDirectoryBestEffort(dir);
-            }
+        await applyDirectoryMode({
+            fsModule: fs,
+            dirPath: dir,
+            mode: options.dirMode ?? 0o700,
+            ignoreChmodError: true,
         });
-        return { filePath, result };
-    }
-    finally {
-        if (tempExists) {
-            await fs.rm(tempPath, { force: true }).catch(() => undefined);
-        }
-        unregisterTempPath();
     }
+    return await writeCallbackSibling({
+        tempPath: buildTempPath(dir, options.tempPrefix),
+        write: options.writeTemp,
+        resolveFinalPath: options.resolveFinalPath,
+        mode: options.mode,
+        ignoreModeError: true,
+        syncTempFile: options.syncTempFile === true,
+        syncParentDir: options.syncParentDir === true,
+    });
 }
 function buildSiblingTempPath(params) {
     const id = crypto.randomUUID();
@@ -107,18 +62,20 @@ export async function writeViaSiblingTempPath(params) {
         throw new Error("Target path is outside the allowed root");
     }
     const rootGuard = await createAsyncDirectoryGuard(rootDir);
-    const tempDir = await fs.mkdtemp(path.join(resolveSecureTempRoot({
-        fallbackPrefix: "fs-safe-output",
-        unsafeFallbackLabel: "sibling temp output dir",
-        warn: () => undefined,
-    }), "fs-safe-output-"));
-    const tempPath = buildSiblingTempPath({
-        targetPath: path.join(tempDir, path.basename(targetPath)),
-        fallbackFileName: params.fallbackFileName ?? "output.bin",
-        tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
+    const workspace = await tempFile({
+        rootDir: resolveSecureTempRoot({
+            fallbackPrefix: "fs-safe-output",
+            unsafeFallbackLabel: "sibling temp output dir",
+            warn: () => undefined,
+        }),
+        prefix: "fs-safe-output",
     });
-    const unregisterTempPath = registerTempPathForExit(tempDir, { recursive: true });
     try {
+        const tempPath = buildSiblingTempPath({
+            targetPath: path.join(workspace.dir, path.basename(targetPath)),
+            fallbackFileName: params.fallbackFileName ?? "output.bin",
+            tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
+        });
         await getFsSafeTestHooks()?.beforeSiblingTempWrite?.(tempPath);
         await params.writeTemp(tempPath);
         await assertAsyncDirectoryGuard(rootGuard);
@@ -127,7 +84,6 @@ export async function writeViaSiblingTempPath(params) {
         await assertAsyncDirectoryGuard(rootGuard);
     }
     finally {
-        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => { });
-        unregisterTempPath();
+        await workspace.cleanup();
     }
 }

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":"AAGA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAO3C,OAAO,EAUL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5F,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,CAsP5B"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAS3C,OAAO,EAUL,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,CA+Q5B"}

package/dist/sidecar-lock-acquire.js

@@ -2,8 +2,9 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { createNativeExclusiveFile } from "./native-operations.js";
-import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, } from "./sidecar-lock-policy.js";
+import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { readSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+import { createSuppressedError } from "./suppressed-error.js";
 async function resolveNormalizedTargetPath(targetPath) {
     const resolved = path.resolve(targetPath);
     const dir = path.dirname(resolved);
@@ -16,19 +17,34 @@ async function resolveNormalizedTargetPath(targetPath) {
     }
 }
 export async function acquireSidecarLock(options, context) {
+    const retry = options.retry ?? {};
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(options.timeoutMs);
     context.ensureExitCleanupRegistered();
     const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
     const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
-    const held = context.held.get(normalizedTargetPath);
+    let held = context.held.get(normalizedTargetPath);
     if (held &&
         options.reentrantOwner !== undefined &&
         held.reentrantOwner !== undefined &&
         options.reentrantOwner === held.reentrantOwner) {
-        held.refCount += 1;
-        return context.handleForHeldLock(normalizedTargetPath, held);
+        // A final release may already have decremented the count to zero and be
+        // removing the sidecar. Do not admit a new reentrant handle until that
+        // cleanup settles: successful cleanup requires a fresh acquisition, while
+        // failed cleanup leaves the existing sidecar held for a retry.
+        if (held.releasePromise) {
+            await held.releasePromise.catch(() => undefined);
+            held = context.held.get(normalizedTargetPath);
+        }
+        if (held &&
+            options.reentrantOwner !== undefined &&
+            held.reentrantOwner !== undefined &&
+            options.reentrantOwner === held.reentrantOwner) {
+            held.refCount += 1;
+            return context.handleForHeldLock(normalizedTargetPath, held);
+        }
     }
     const startedAt = Date.now();
-    const retry = options.retry ?? {};
     const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
     const reclaimGuardPath = `${lockPath}.reclaim`;
     let ownsReclaimGuard = false;
@@ -149,31 +165,36 @@ export async function acquireSidecarLock(options, context) {
                 return returnedHandle;
             }
             catch (err) {
-                if (handle) {
-                    const failedSnapshot = { payload: null };
-                    try {
-                        failedSnapshot.stat = await handle.stat();
-                    }
-                    catch {
-                        // Best-effort cleanup of a failed exclusive create.
+                try {
+                    if (handle) {
+                        const failedSnapshot = { payload: null };
+                        try {
+                            failedSnapshot.stat = await handle.stat();
+                        }
+                        catch {
+                            // Best-effort cleanup of a failed exclusive create.
+                        }
+                        const current = context.held.get(normalizedTargetPath);
+                        if (current?.handle === handle) {
+                            context.held.delete(normalizedTargetPath);
+                        }
+                        await handle.close().catch(() => undefined);
+                        // The file may be empty or partial JSON, so remove by the identity
+                        // captured from our exclusive handle rather than by pathname alone.
+                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
                     }
-                    const current = context.held.get(normalizedTargetPath);
-                    if (current?.handle === handle) {
-                        context.held.delete(normalizedTargetPath);
+                    else if (createdSnapshot) {
+                        await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
                     }
-                    await handle.close().catch(() => undefined);
-                    // The file may be empty or partial JSON, so remove by the identity
-                    // captured from our exclusive handle rather than by pathname alone.
-                    await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    });
                 }
-                else if (createdSnapshot) {
-                    await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    });
+                catch (cleanupError) {
+                    throw createSuppressedError(cleanupError, err, "file lock acquisition and cleanup both failed");
                 }
                 if (lockFileCreateDenied && withinDenialBudget()) {
                     await retryOrRethrowDenial(err);

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

@@ -5,7 +5,9 @@ export declare function createSidecarLockHandle(params: {
     lockPath: string;
     normalizedTargetPath: string;
     verifyStillHeld: () => Promise<boolean>;
-    release: () => Promise<unknown>;
+    release: (options?: {
+        retry?: boolean;
+    }) => Promise<unknown>;
 }): SidecarLockHandle;
 export declare function createHeldSidecarLockHandle(params: {
     normalizedTargetPath: string;
@@ -15,6 +17,8 @@ export declare function createHeldSidecarLockHandle(params: {
         lockRoot?: Root;
         parsePayload?: (raw: string) => unknown;
     };
-    release: () => Promise<unknown>;
+    release: (options?: {
+        retry?: boolean;
+    }) => Promise<unknown>;
 }): SidecarLockHandle;
 //# sourceMappingURL=sidecar-lock-handle.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-handle.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,iBAAiB,CAcpB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,QAAQ,CAAC,EAAE,IAAI,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IACF,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,iBAAiB,CAWpB"}
+{"version":3,"file":"sidecar-lock-handle.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,GAAG,iBAAiB,CA2BpB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,QAAQ,CAAC,EAAE,IAAI,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IACF,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D,GAAG,iBAAiB,CAWpB"}

package/dist/sidecar-lock-handle.js

@@ -1,11 +1,25 @@
 import { sidecarLockSnapshotStillPresent, } from "./sidecar-lock-reclaim.js";
 export function createSidecarLockHandle(params) {
     let released = false;
+    let releasePromise;
+    let releaseStarted = false;
     const release = async () => {
         if (released)
             return;
-        released = true;
-        await params.release();
+        if (!releasePromise) {
+            const retry = releaseStarted;
+            releaseStarted = true;
+            releasePromise = (async () => {
+                await params.release({ retry });
+                released = true;
+            })();
+        }
+        try {
+            await releasePromise;
+        }
+        finally {
+            releasePromise = undefined;
+        }
     };
     return {
         lockPath: params.lockPath,
@@ -23,6 +37,6 @@ export function createHeldSidecarLockHandle(params) {
             lockRoot: params.held.lockRoot,
             parsePayload: params.held.parsePayload,
         }),
-        release: params.release,
+        release: (options) => params.release(options),
     });
 }

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

@@ -1,4 +1,6 @@
 import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
+export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;