@openclaw/fs-safe 0.7.0 → 0.7.2

package/dist/root-impl.js

@@ -11,6 +11,7 @@ import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { assertMutationNotDenied, mergeDenyMutationPolicies, } from "./deny-mutations.js";
 import { resolveOpenedFileRealPathForFd, resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
+import { openedPathResolutionError, recordFileOpenFailure, recordOpenedFileFailure, recordPreOpenFileChange } from "./opened-file-failure.js";
 import { runPinnedWriteHelper, runPinnedWriteWithRenamePolicy, } from "./pinned-write.js";
 import { getNativeBinding } from "./native.js";
 import { validatePinnedOperationPayload } from "./pinned-operation.js";
@@ -102,25 +103,15 @@ async function openVerifiedLocalFile(filePath, options) {
     if (preOpenStat) {
         await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
     }
+    const openFlags = options?.symlinks === "follow-within-root"
+        ? OPEN_READ_FOLLOW_FLAGS
+        : OPEN_READ_FLAGS;
+    await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
     let handle;
     try {
-        const openFlags = options?.symlinks === "follow-within-root"
-            ? OPEN_READ_FOLLOW_FLAGS
-            : OPEN_READ_FLAGS;
-        await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
-        handle = await fs.open(filePath, openFlags);
-        try {
-            await fsSafeTestHooks?.afterOpen?.(filePath, handle);
-        }
-        catch (err) {
-            await handle.close().catch(() => { });
-            throw err;
-        }
+        handle = await fs.open(filePath, openFlags).catch((error) => recordFileOpenFailure(isNotFoundPathError(error) ? fileNotFoundError() : error, filePath));
     }
     catch (err) {
-        if (isNotFoundPathError(err)) {
-            throw fileNotFoundError();
-        }
         if (isSymlinkOpenError(err)) {
             throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
         }
@@ -131,16 +122,35 @@ async function openVerifiedLocalFile(filePath, options) {
         throw err;
     }
     try {
+        await fsSafeTestHooks?.afterOpen?.(filePath, handle);
         const stat = await handle.stat();
         if (!stat.isFile()) {
             throw new FsSafeError("not-file", "not a file");
         }
         // Keep numeric Stats for the public receipt, never for identity verification.
-        const identity = await inspectFileIdentity(() => handle.stat({ bigint: true }), preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined);
+        let openedIdentity;
+        const identity = await inspectFileIdentity(async () => (openedIdentity = await handle.stat({ bigint: true })), preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined).catch(async (error) => {
+            if ([0, 1].includes(stat.nlink)) {
+                await recordPreOpenFileChange(error, handle, filePath, preOpenStat, openedIdentity);
+            }
+            throw error;
+        });
         if (options?.hardlinks === "reject" && stat.nlink > 1) {
             throw hardlinkedPathNotAllowedError();
         }
-        await inspectFileIdentity(async () => {
+        const inspectPathIdentity = async (inspect) => {
+            try {
+                return await inspectFileIdentity(inspect, identity);
+            }
+            catch (error) {
+                const failure = isNotFoundPathError(error) ? openedPathResolutionError(fileNotFoundError()) : error;
+                if (stat.nlink <= 1 && (!preOpenStat || preOpenStat.nlink <= 1n)) {
+                    await recordOpenedFileFailure(failure, handle, filePath, identity);
+                }
+                throw failure;
+            }
+        };
+        await inspectPathIdentity(async () => {
             const pathStat = options?.symlinks === "follow-within-root"
                 ? await fs.stat(filePath, { bigint: true })
                 : await fs.lstat(filePath, { bigint: true });
@@ -148,26 +158,26 @@ async function openVerifiedLocalFile(filePath, options) {
                 throw new FsSafeError("symlink", "symlink not allowed");
             }
             return pathStat;
-        }, identity);
+        });
         await fsSafeTestHooks?.afterOpenedPathIdentityCheck?.(filePath, handle);
-        const realPath = await resolveOpenedFileRealPathForFd(handle.fd, identity, filePath);
-        await inspectFileIdentity(async () => {
+        const realPath = await resolveOpenedFileRealPathForFd(handle.fd, identity, filePath)
+            .catch(async (error) => {
+            if (stat.nlink <= 1 && (!preOpenStat || preOpenStat.nlink <= 1n)) {
+                await recordOpenedFileFailure(error, handle, filePath, identity);
+            }
+            throw error;
+        });
+        await inspectPathIdentity(async () => {
             const realStat = await fs.stat(realPath, { bigint: true });
             if (options?.hardlinks === "reject" && realStat.nlink > 1n) {
                 throw hardlinkedPathNotAllowedError();
             }
             return realStat;
-        }, identity);
+        });
         return { opened: openResult({ handle, realPath, stat }), identity };
     }
     catch (err) {
         await handle.close().catch(() => { });
-        if (err instanceof FsSafeError) {
-            throw err;
-        }
-        if (isNotFoundPathError(err)) {
-            throw fileNotFoundError();
-        }
         throw err;
     }
 }
@@ -396,19 +406,10 @@ async function openFileInRoot(root, params) {
         rejectUnsafeDeviceReads: true,
         rejectSymlinks: params.symlinks !== "follow-within-root",
     });
-    let opened;
-    try {
-        ({ opened } = await openVerifiedLocalFile(resolved, {
-            nonBlockingRead: params.nonBlockingRead,
-            symlinks: params.symlinks,
-        }));
-    }
-    catch (err) {
-        if (err instanceof FsSafeError) {
-            throw err;
-        }
-        throw err;
-    }
+    const { opened } = await openVerifiedLocalFile(resolved, {
+        nonBlockingRead: params.nonBlockingRead,
+        symlinks: params.symlinks,
+    });
     if (params.hardlinks !== "allow" && opened.stat.nlink > 1) {
         await opened.handle.close().catch(() => { });
         throw hardlinkedPathNotAllowedError();
@@ -460,9 +461,7 @@ function emitWriteBoundaryWarning(reason) {
     logWarn(`security: fs-safe write boundary warning (${reason})`);
 }
 function buildAtomicWriteTempPath(targetPath) {
-    const dir = path.dirname(targetPath);
-    const base = path.basename(targetPath);
-    return path.join(dir, `.${base}.${process.pid}.${randomUUID()}.tmp`);
+    return path.join(path.dirname(targetPath), `.fs-safe-${randomUUID()}.tmp`);
 }
 function rootWriteQueueKey(root, relativePath) {
     return `${root.rootReal}\0${relativePath}`;
@@ -701,7 +700,7 @@ async function writeFileInRoot(root, params) {
             await writeFileFallback(root, params);
             return;
         }
-        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
+        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations, params.overwrite);
         await serializePathWrite(pinned.targetPath, async () => {
             await commitPinnedWriteInRoot(root, pinned, params);
         });
@@ -823,7 +822,7 @@ async function removePathIfIdentityUnchanged(targetPath, identity) {
         await fs.rm(targetPath);
     });
 }
-async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations) {
+async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations, overwrite = true) {
     const { rootReal, rootWithSep, resolved } = await resolveGuardedWritePathInRoot(root, {
         relativePath,
         denyMutations,
@@ -841,22 +840,40 @@ async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode,
     if (!basename || basename === "." || basename === "/") {
         throw new FsSafeError("invalid-path", "invalid target path");
     }
+    // Exclusive publication cannot inherit an existing file's mode. Keep type
+    // and alias checks, but never open a competing owner's record just to reject it.
+    if (!overwrite) {
+        try {
+            const existing = await fs.stat(resolved);
+            if (!existing.isFile())
+                throw new FsSafeError("not-file", "not a file");
+            if (existing.nlink > 1)
+                throw hardlinkedPathNotAllowedError();
+            throw new FsSafeError("already-exists", "file already exists");
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+        }
+    }
     let mode = requestedMode ?? 0o600;
     try {
-        const opened = await openFileInRoot(root, {
-            relativePath,
-            hardlinks: "reject",
-            nonBlockingRead: true,
-            symlinks: "follow-within-root",
-        });
-        try {
-            mode = requestedMode ?? (opened.stat.mode & 0o777);
-            if (!isPathInside(rootWithSep, opened.realPath)) {
-                throw outsideWorkspaceError();
+        if (overwrite) {
+            const opened = await openFileInRoot(root, {
+                relativePath,
+                hardlinks: "reject",
+                nonBlockingRead: true,
+                symlinks: "follow-within-root",
+            });
+            try {
+                mode = requestedMode ?? (opened.stat.mode & 0o777);
+                if (!isPathInside(rootWithSep, opened.realPath)) {
+                    throw outsideWorkspaceError();
+                }
+            }
+            finally {
+                await opened.handle.close().catch(() => { });
             }
-        }
-        finally {
-            await opened.handle.close().catch(() => { });
         }
     }
     catch (err) {

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;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"}
+{"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"}

package/dist/sidecar-lock-acquire.js

@@ -1,9 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.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 { readSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.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) {
     const resolved = path.resolve(targetPath);
@@ -93,13 +95,14 @@ export async function acquireSidecarLock(options, context) {
             let handle = null;
             let createdSnapshot = null;
             let lockFileCreateDenied = false;
+            const payload = await options.payload();
+            const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
             try {
-                const payload = await options.payload();
-                const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
                 if (options.lockRoot) {
-                    const relativeLockPath = relativeSidecarLockPath(options.lockRoot, lockPath);
+                    const lockRoot = options.lockRoot;
+                    const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
                     try {
-                        await options.lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
+                        await lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
                     }
                     catch (error) {
                         if (error instanceof FsSafeError && error.code === "already-exists") {
@@ -108,7 +111,23 @@ export async function acquireSidecarLock(options, context) {
                         throw error;
                     }
                     createdSnapshot = { raw, payload, ownershipToken };
-                    handle = (await options.lockRoot.open(relativeLockPath)).handle;
+                    const opened = await openSidecarRoot(lockRoot, relativeLockPath, "unlinked");
+                    if (!opened) {
+                        await waitForRetry();
+                        continue;
+                    }
+                    try {
+                        // Root.open admits the current file, not necessarily the one we created.
+                        const currentRaw = await readFileHandleBounded(opened.handle, Buffer.byteLength(raw));
+                        if (!currentRaw.equals(Buffer.from(raw))) {
+                            throw new FsSafeError("path-mismatch", "created sidecar lock changed before admission");
+                        }
+                    }
+                    catch (error) {
+                        await opened.handle.close().catch(() => undefined);
+                        throw error;
+                    }
+                    handle = opened.handle;
                 }
                 else {
                     try {
@@ -123,6 +142,12 @@ export async function acquireSidecarLock(options, context) {
                     await handle.writeFile(raw, "utf8");
                 }
                 const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
+                if (snapshot.stat.nlink === 0) {
+                    await handle.close();
+                    handle = null;
+                    await waitForRetry();
+                    continue;
+                }
                 const createdHeld = {
                     refCount: 1,
                     reentrantOwner: options.reentrantOwner,
@@ -167,7 +192,7 @@ export async function acquireSidecarLock(options, context) {
             catch (err) {
                 try {
                     if (handle) {
-                        const failedSnapshot = { payload: null };
+                        const failedSnapshot = createdSnapshot ?? { payload: null };
                         try {
                             failedSnapshot.stat = await handle.stat();
                         }
@@ -179,8 +204,8 @@ export async function acquireSidecarLock(options, context) {
                             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.
+                        // Root-created records retain the creator's byte/token receipt;
+                        // partial direct writes use the exclusive descriptor's identity.
                         await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
                             lockRoot: options.lockRoot,
                             parsePayload: options.parsePayload,
@@ -206,24 +231,29 @@ export async function acquireSidecarLock(options, context) {
                 if (ownsReclaimGuard) {
                     await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);
                     ownsReclaimGuard = false;
+                    await waitForRetry();
                     continue;
                 }
                 const nowMs = Date.now();
-                let snapshot;
+                let rawSnapshot;
+                let lockFileOpenDenied = false;
                 try {
-                    snapshot = await readSidecarLockSnapshot(lockPath, {
+                    rawSnapshot = await readSidecarLockRawSnapshot(lockPath, {
                         lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
                         rejectNonFile: true,
+                        discardObservation: "changed",
+                        onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
                     });
                 }
                 catch (readErr) {
-                    if (!isTransientLockFileDenial(readErr, lockPath) || !withinDenialBudget())
+                    if (!lockFileOpenDenied || !withinDenialBudget())
                         throw readErr;
                     await retryOrRethrowDenial(readErr);
                     continue;
                 }
+                const snapshot = parseSidecarLockSnapshot(rawSnapshot, options.parsePayload);
                 if (!snapshot) {
+                    await waitForRetry();
                     continue;
                 }
                 if (context.held.has(normalizedTargetPath)) {
@@ -243,6 +273,7 @@ export async function acquireSidecarLock(options, context) {
                         lockRoot: options.lockRoot,
                         parsePayload: options.parsePayload,
                     }))) {
+                        await waitForRetry();
                         continue;
                     }
                     const staleRecovery = options.staleRecovery ?? "fail-closed";
@@ -261,6 +292,8 @@ export async function acquireSidecarLock(options, context) {
                             parsePayload: options.parsePayload,
                         });
                         if (removal === "removed" || removal === "changed") {
+                            if (removal === "changed")
+                                await waitForRetry();
                             continue;
                         }
                         await releaseSidecarReclaimGuard(context.reclaimGuards, reclaimGuardPath);

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

@@ -12,6 +12,10 @@ export type SidecarLockSnapshot = {
     stat?: Stats;
     ownershipToken?: string;
 };
+type SidecarLockRawSnapshot = Omit<SidecarLockSnapshot, "payload"> & {
+    raw: string;
+};
+export declare function parseSidecarLockSnapshot(snapshot: SidecarLockRawSnapshot | null, parser?: (raw: string) => unknown): SidecarLockSnapshot | null;
 export declare function readSidecarLockOwnershipToken(raw: string): string | undefined;
 export declare function serializeSidecarLockPayload(payload: Record<string, unknown>): {
     raw: string;
@@ -19,15 +23,21 @@ export declare function serializeSidecarLockPayload(payload: Record<string, unkn
 };
 export declare function relativeSidecarLockPath(lockRoot: Root, lockPath: string): string;
 export declare function parseSidecarLockPayload(raw: string, parser?: (raw: string) => unknown): unknown;
-export declare function readSidecarLockSnapshot(lockPath: string, options?: {
-    lockRoot?: Root;
+export declare function readSidecarLockSnapshot(lockPath: string, options?: Parameters<typeof readSidecarLockRawSnapshot>[1] & {
     parsePayload?: (raw: string) => unknown;
+}): Promise<SidecarLockSnapshot | null>;
+export declare function readSidecarLockRawSnapshot(lockPath: string, options?: {
+    lockRoot?: Root;
     rejectNonFile?: boolean;
     allowDescriptorIdentityDrift?: boolean;
-}): Promise<SidecarLockSnapshot | null>;
-export declare function readSidecarLockSnapshotSync(lockPath: string, parsePayload?: (raw: string) => unknown, options?: {
+    discardObservation?: "unlinked" | "changed";
+    onOpenFailure?: (error: unknown) => void;
+}): Promise<SidecarLockRawSnapshot | null>;
+export declare function readSidecarLockSnapshotSync(lockPath: string, parsePayload?: (raw: string) => unknown, options?: Parameters<typeof readSidecarLockRawSnapshotSync>[1]): SidecarLockSnapshot | null;
+export declare function readSidecarLockRawSnapshotSync(lockPath: string, options?: {
     rejectNonFile?: boolean;
-}): SidecarLockSnapshot | null;
+    onOpenFailure?: (error: unknown) => void;
+}): SidecarLockRawSnapshot | null;
 export declare function removeSidecarLockIfUnchangedSync(lockPath: string, observed: SidecarLockSnapshot): boolean;
 export declare function sidecarLockSnapshotMatches(current: SidecarLockSnapshot, observed: SidecarLockSnapshot): boolean;
 export declare function removeSidecarLockIfUnchanged(lockPath: string, observed: SidecarLockSnapshot | null, options?: {
@@ -49,4 +59,5 @@ export declare function removeStaleSidecarLockIfAllowed(params: {
     lockRoot?: Root;
     parsePayload?: (raw: string) => unknown;
 }): Promise<"removed" | "changed" | "not-approved">;
+export {};
 //# sourceMappingURL=sidecar-lock-reclaim.d.ts.map

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

@@ -6,12 +6,16 @@ import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { openSidecarRoot } from "./sidecar-lock-root.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const MAX_LOCK_PAYLOAD_BYTES = 1024 * 1024;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES = 16;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS = SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES * 8;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX = "\t".repeat(8);
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_PATTERN = new RegExp(`\\n(${SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX}[ \\t]{${SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS}})\\n$`);
+export function parseSidecarLockSnapshot(snapshot, parser) {
+    return snapshot && { ...snapshot, payload: parseSidecarLockPayload(snapshot.raw, parser) };
+}
 function createSidecarLockOwnershipToken() {
     let token = SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX;
     for (const byte of randomBytes(SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES)) {
@@ -56,34 +60,27 @@ export function parseSidecarLockPayload(raw, parser) {
         return null;
     }
 }
+function missingSnapshotPath(error) {
+    if (error.code === "ENOENT")
+        return null;
+    throw error;
+}
 export async function readSidecarLockSnapshot(lockPath, options = {}) {
+    return parseSidecarLockSnapshot(await readSidecarLockRawSnapshot(lockPath, options), options.parsePayload);
+}
+export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
     let handle;
     try {
         if (options.lockRoot) {
             const lockRoot = options.lockRoot;
             const relative = relativeSidecarLockPath(lockRoot, lockPath);
-            const opened = await lockRoot.open(relative).catch(async (error) => {
-                if (error instanceof FsSafeError && error.code === "path-mismatch") {
-                    // An owner can unlink after open. Prove absence through the same root;
-                    // acquisition retries create-only, so a later replacement stays guarded.
-                    try {
-                        await lockRoot.stat(relative);
-                    }
-                    catch (probeError) {
-                        if (probeError instanceof FsSafeError && probeError.code === "not-found") {
-                            return null;
-                        }
-                    }
-                }
-                throw error;
-            });
+            const opened = await openSidecarRoot(lockRoot, relative, options.discardObservation, options.onOpenFailure);
             if (!opened)
                 return null;
             try {
                 const raw = (await readFileHandleBounded(opened.handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
                 return {
                     raw,
-                    payload: parseSidecarLockPayload(raw, options.parsePayload),
                     stat: opened.stat,
                 };
             }
@@ -91,7 +88,9 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
                 await opened.handle.close().catch(() => undefined);
             }
         }
-        const before = await fs.lstat(lockPath);
+        const before = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        if (!before)
+            return null;
         if (!before.isFile() || before.isSymbolicLink()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
@@ -108,11 +107,14 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
                 (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0));
         }
         catch (error) {
+            if (error.code === "ENOENT")
+                return null;
             if (options.rejectNonFile && error.code === "ELOOP") {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`, {
                     cause: error,
                 });
             }
+            options.onOpenFailure?.(error);
             throw error;
         }
         const opened = await handle.stat();
@@ -125,33 +127,47 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
         if (!options.allowDescriptorIdentityDrift && !sameFileIdentity(before, opened))
             return null;
         const raw = (await readFileHandleBounded(handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
-        const after = await fs.lstat(lockPath);
-        if (!after.isFile() || !sameFileIdentity(before, after))
-            return null;
-        return { raw, payload: parseSidecarLockPayload(raw, options.parsePayload), stat: after };
-    }
-    catch (err) {
-        if (err.code === "ENOENT" ||
-            (err instanceof FsSafeError && err.code === "not-found")) {
+        const after = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        if (!after || !after.isFile() || !sameFileIdentity(before, after))
             return null;
-        }
-        throw err;
+        return { raw, stat: after };
     }
     finally {
         await handle?.close().catch(() => undefined);
     }
 }
+function lstatSidecarLockSync(lockPath) {
+    try {
+        return fsSync.lstatSync(lockPath);
+    }
+    catch (error) {
+        return missingSnapshotPath(error);
+    }
+}
 export function readSidecarLockSnapshotSync(lockPath, parsePayload, options = {}) {
+    return parseSidecarLockSnapshot(readSidecarLockRawSnapshotSync(lockPath, options), parsePayload);
+}
+export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
     let fd;
     try {
-        const before = fsSync.lstatSync(lockPath);
+        const before = lstatSidecarLockSync(lockPath);
+        if (!before)
+            return null;
         if (!before.isFile() || before.isSymbolicLink()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
             }
             return null;
         }
-        fd = fsSync.openSync(lockPath, resolveReadOpenFlags());
+        try {
+            fd = fsSync.openSync(lockPath, resolveReadOpenFlags());
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            options.onOpenFailure?.(error);
+            throw error;
+        }
         const opened = fsSync.fstatSync(fd);
         if (!opened.isFile()) {
             if (options.rejectNonFile) {
@@ -160,21 +176,15 @@ export function readSidecarLockSnapshotSync(lockPath, parsePayload, options = {}
             return null;
         }
         const raw = readFileDescriptorBoundedSync(fd, MAX_LOCK_PAYLOAD_BYTES).toString("utf8");
-        const after = fsSync.lstatSync(lockPath);
-        if (!sameFileIdentity(before, opened) || !sameFileIdentity(opened, after))
+        const after = lstatSidecarLockSync(lockPath);
+        if (!after || !sameFileIdentity(before, opened) || !sameFileIdentity(opened, after))
             return null;
         return {
             raw,
-            payload: parseSidecarLockPayload(raw, parsePayload),
             stat: after,
             ownershipToken: readSidecarLockOwnershipToken(raw),
         };
     }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return null;
-        throw error;
-    }
     finally {
         if (fd !== undefined)
             fsSync.closeSync(fd);

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

@@ -0,0 +1,3 @@
+import type { OpenResult, Root } from "./root-impl.js";
+export declare function openSidecarRoot(lockRoot: Root, relative: string, discardObservation?: "unlinked" | "changed", onOpenFailure?: (error: unknown) => void): Promise<OpenResult | null>;
+//# sourceMappingURL=sidecar-lock-root.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-root.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-root.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGvD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,IAAI,EACd,QAAQ,EAAE,MAAM,EAChB,kBAAkB,CAAC,EAAE,UAAU,GAAG,SAAS,EAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACvC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAuD5B"}