@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/sibling-staged-file.js

@@ -4,13 +4,43 @@ import fs, {} from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, createAsyncDirectoryGuard, } from "./directory-guard.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { isWindowsReservedDeviceName } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { handoffPrivateProducerFile, } from "./private-producer-handoff.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
-import { root } from "./root.js";
+import { rootFromDirectoryGuard } from "./root-impl.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { createOwnedTempFile } from "./temp-target.js";
 import { serializePathWrite } from "./write-queue.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const INVALID_CALLBACK_COMPONENT_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/u;
+function resolveCallbackTempDirectory(workspaceDir) {
+    assertNoWindowsPathAlias(workspaceDir, "filesystem", "sibling temp parent uses a Windows filesystem namespace alias");
+    const dir = resolvePathPreservingWindowsRoot(workspaceDir);
+    assertNoWindowsPathAlias(dir, "filesystem", "sibling temp parent uses a Windows filesystem namespace alias");
+    return dir;
+}
+export function resolveCallbackTempPath(workspaceDir, component) {
+    const dir = resolveCallbackTempDirectory(workspaceDir);
+    if (typeof component !== "string" ||
+        component === "" ||
+        component === "." ||
+        component === ".." ||
+        INVALID_CALLBACK_COMPONENT_CHARACTERS.test(component) ||
+        component.endsWith(".") ||
+        component.endsWith(" ") ||
+        isWindowsReservedDeviceName(component)) {
+        throw new FsSafeError("invalid-path", "callback temp name must be one path component");
+    }
+    const joined = path.join(dir, component);
+    assertNoWindowsPathAlias(joined, "filesystem", "sibling temp path uses a Windows filesystem namespace alias");
+    if (path.dirname(joined) !== dir) {
+        throw new FsSafeError("invalid-path", "callback temp path must be a direct workspace child");
+    }
+    return joined;
+}
 function assertRegularFile(stat) {
     if (stat.isSymbolicLink()) {
         throw new FsSafeError("symlink", "symlink sibling temp not allowed");
@@ -29,42 +59,102 @@ async function inspectStage(inspect, expected) {
         return stat;
     }, expected);
 }
+function aggregateErrors(errors, message) {
+    if (errors.length === 1)
+        return errors[0];
+    return new AggregateError(errors, message);
+}
 // Own the workspace before the producer can leave partial output. The finished
 // file still enters the ordinary sibling admission and publication lifecycle.
 async function writeIsolatedProducer(params) {
-    const targetRoot = await root(path.dirname(params.tempPath));
+    const tempPath = params.tempPath;
+    const write = params.write;
+    const writeReceiver = params.writeReceiver;
+    const parentGuard = params.parentGuard;
+    const assertParent = params.assertParent;
+    const syncTempFile = params.syncTempFile;
+    assertParent();
+    const targetRoot = rootFromDirectoryGuard(parentGuard);
+    // Select the handoff before invoking the producer. Missing required native
+    // support must not leave producer output behind as a discovery side effect.
+    const native = getNativeBinding();
+    const cleanupErrors = [];
     const { target, identity } = await createOwnedTempFile({
         rootDir: targetRoot.rootReal,
         prefix: "fs-safe-output",
-        fileName: path.basename(params.tempPath),
+        fileName: path.basename(tempPath),
+        onCleanupError: (error) => cleanupErrors.push(error),
     });
-    const assertCurrent = () => {
-        params.assertParent();
+    let cleanupStarted = false;
+    const cleanupWorkspace = async () => {
+        if (cleanupStarted)
+            return;
+        cleanupStarted = true;
+        try {
+            await target.cleanup();
+        }
+        catch (error) {
+            cleanupErrors.push(error);
+        }
+        if (cleanupErrors.length > 0) {
+            throw aggregateErrors(cleanupErrors, "isolated producer workspace cleanup failed");
+        }
+    };
+    const assertWorkspace = () => {
         assertDirectoryIdentitySync(target.dir, { ...identity, realPath: target.dir });
     };
+    const assertCurrent = () => {
+        assertParent();
+        assertWorkspace();
+    };
     try {
+        const producerPath = resolveCallbackTempPath(target.dir, path.basename(target.path));
         assertCurrent();
-        const result = await params.write(target.path);
+        const result = await Reflect.apply(write, writeReceiver, [producerPath]);
         assertCurrent();
-        await targetRoot.move(path.relative(targetRoot.rootReal, target.path), path.basename(params.tempPath), {
-            assertBeforeMutation: assertCurrent,
+        if (native) {
+            await targetRoot.move(path.relative(targetRoot.rootReal, producerPath), path.basename(tempPath), { assertBeforeMutation: assertCurrent });
+            return { cleanupWorkspace, result };
+        }
+        const handoff = await handoffPrivateProducerFile({
+            sourcePath: producerPath,
+            targetPath: tempPath,
+            assertSourceParent: assertWorkspace,
+            assertTargetParent: assertParent,
+            readWrite: syncTempFile,
         });
-        return result;
+        return { cleanupWorkspace, handoff, result };
     }
-    finally {
-        await target.cleanup();
+    catch (error) {
+        try {
+            await cleanupWorkspace();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "isolated producer operation and workspace cleanup failed");
+        }
+        throw error;
     }
 }
 // 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 parent = resolveCallbackTempDirectory(params.tempDir);
+    const tempPath = resolveCallbackTempPath(parent, params.tempName);
+    const write = params.write;
+    const producerIsolation = params.producerIsolation;
+    const resolveFinalPath = params.resolveFinalPath;
+    const mode = params.mode;
+    const ignoreModeError = params.ignoreModeError;
+    const maxBytes = params.maxBytes;
+    const syncTempFile = params.syncTempFile;
+    const syncParentDir = params.syncParentDir;
     const guard = await createAsyncDirectoryGuard(parent, { bigint: true });
     const assertParent = () => assertAsyncDirectoryGuard(guard);
     let handle;
     let identity;
     let unregister;
+    let cleanupWorkspace;
     let renamed = false;
     let failure;
     const inspectPath = (pathname, expected) => inspectStage(() => fsSync.lstatSync(pathname, { bigint: true }), expected);
@@ -72,70 +162,98 @@ export async function writeCallbackSibling(params) {
         await assertParent();
         const opened = await inspectStage(() => fsSync.fstatSync(handle.fd, { 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})`);
+        if (maxBytes !== undefined &&
+            (opened.size > maxBytes || current.size > maxBytes)) {
+            throw new FsSafeError("too-large", `sibling temp exceeds maxBytes (${maxBytes})`);
         }
     };
     try {
-        const result = params.producerIsolation === "private-directory"
-            ? await writeIsolatedProducer({
-                tempPath: params.tempPath,
-                write: params.write,
+        let result;
+        if (producerIsolation === "private-directory") {
+            const isolated = await writeIsolatedProducer({
+                tempPath: tempPath,
+                write,
+                writeReceiver: params,
+                parentGuard: guard,
+                syncTempFile: syncTempFile,
                 assertParent: () => assertDirectoryIdentitySync(parent, {
                     dev: guard.stat.dev,
                     ino: guard.stat.ino,
                     realPath: guard.realPath,
                 }),
-            })
-            : await params.write(params.tempPath);
+            });
+            result = isolated.result;
+            cleanupWorkspace = isolated.cleanupWorkspace;
+            if (isolated.handoff) {
+                handle = isolated.handoff.handle;
+                identity = isolated.handoff.identity;
+                unregister = isolated.handoff.unregister;
+            }
+        }
+        else {
+            result = await Reflect.apply(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());
+        if (handle) {
+            const opened = await inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
+            await inspectPath(tempPath, opened);
         }
-        catch (error) {
-            if (error?.code === "ELOOP") {
-                throw new FsSafeError("symlink", "symlink sibling temp not allowed", { cause: error });
+        else {
+            const before = await inspectPath(tempPath);
+            try {
+                // No create/truncate flags; O_NONBLOCK also bounds a FIFO swap during open.
+                const access = syncTempFile ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
+                handle = await fs.open(tempPath, access | resolveReadOpenFlags());
+            }
+            catch (error) {
+                if (error?.code === "ELOOP") {
+                    throw new FsSafeError("symlink", "symlink sibling temp not allowed", { cause: error });
+                }
+                throw error;
             }
-            throw error;
+            const opened = await inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), before);
+            await inspectPath(tempPath, opened);
+            identity = opened;
+            unregister = registerTempPathForExit(tempPath, { identity, singleLinkFile: true });
         }
-        const opened = await inspectStage(() => fsSync.fstatSync(handle.fd, { 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 (cleanupWorkspace) {
+            const cleanup = cleanupWorkspace;
+            cleanupWorkspace = undefined;
+            await cleanup();
+        }
+        const rawFilePath = Reflect.apply(resolveFinalPath, params, [result]);
+        assertNoWindowsPathAlias(rawFilePath, "filesystem", "final path uses a Windows filesystem namespace alias");
+        const filePath = path.resolve(rawFilePath);
+        assertNoWindowsPathAlias(filePath, "filesystem", "final path uses a Windows filesystem namespace alias");
         if (path.dirname(filePath) !== parent) {
             throw new Error("Final path must be in the sibling temp directory.");
         }
-        if (filePath === params.tempPath) {
+        if (filePath === 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) {
+            await assertCurrent(tempPath);
+            if (mode !== undefined) {
                 try {
-                    await handle.chmod(params.mode);
+                    await handle.chmod(mode);
                 }
                 catch (error) {
-                    if (!params.ignoreModeError)
+                    if (!ignoreModeError)
                         throw error;
                 }
             }
-            if (params.syncTempFile) {
-                await assertCurrent(params.tempPath);
+            if (syncTempFile) {
+                await assertCurrent(tempPath);
                 await syncFileBestEffort(handle);
             }
-            await assertCurrent(params.tempPath);
-            await fs.rename(params.tempPath, filePath);
+            await assertCurrent(tempPath);
+            await fs.rename(tempPath, filePath);
             // A later verification failure never authorizes rollback of the final name.
             renamed = true;
             unregister();
             await assertCurrent(filePath);
-            if (params.syncParentDir)
+            if (syncParentDir)
                 await syncDirectoryBestEffort(parent);
             await assertCurrent(filePath);
         });
@@ -146,13 +264,22 @@ export async function writeCallbackSibling(params) {
         throw error;
     }
     finally {
+        const settlementErrors = [];
+        if (cleanupWorkspace) {
+            try {
+                await cleanupWorkspace();
+            }
+            catch (error) {
+                settlementErrors.push(error);
+            }
+        }
         try {
             if (!renamed && identity) {
                 try {
                     await assertParent();
                     await inspectStage(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
-                    await inspectPath(params.tempPath, identity);
-                    await fs.unlink(params.tempPath);
+                    await inspectPath(tempPath, identity);
+                    await fs.unlink(tempPath);
                     unregister?.();
                 }
                 catch (error) {
@@ -168,9 +295,13 @@ export async function writeCallbackSibling(params) {
                 await handle?.close();
             }
             catch (error) {
-                if (failure)
-                    throw new AggregateError([failure.error, error], "sibling publication and close failed");
-                throw error;
+                settlementErrors.push(error);
+            }
+            if (settlementErrors.length > 0) {
+                if (failure) {
+                    throw new AggregateError([failure.error, ...settlementErrors], "sibling publication and settlement failed");
+                }
+                throw aggregateErrors(settlementErrors, "sibling publication settlement failed");
             }
         }
     }

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

@@ -1 +1 @@
-{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAeA,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,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,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,CAqBxC;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,CA6ChB"}
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAmBA,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,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,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,CA0BxC;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,CAsDhB"}

package/dist/sibling-temp.js

@@ -9,17 +9,22 @@ import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { root } from "./root.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
-import { writeCallbackSibling } from "./sibling-staged-file.js";
+import { resolveCallbackTempPath, writeCallbackSibling } from "./sibling-staged-file.js";
 import { tempFile } from "./temp-target.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-function buildTempPath(dir, tempPrefix) {
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function buildTempName(tempPrefix) {
     const safePrefix = assertSafePathPrefix(tempPrefix ?? ".fs-safe-stream", {
         label: "sibling temp prefix",
     });
-    return path.join(dir, `${safePrefix}.${process.pid}.${randomUUID()}.tmp`);
+    return `${safePrefix}.${process.pid}.${randomUUID()}.tmp`;
 }
 export async function writeSiblingTempFile(options) {
-    const dir = path.resolve(options.dir);
+    const dirInput = options.dir;
+    assertNoWindowsPathAlias(dirInput, "filesystem", "sibling temp directory uses a Windows filesystem namespace alias");
+    const dir = resolvePathPreservingWindowsRoot(dirInput);
+    assertNoWindowsPathAlias(dir, "filesystem", "sibling temp directory uses a Windows filesystem namespace alias");
+    const producerIsolation = options.producerIsolation;
     await fs.mkdir(recursiveMkdirPath(dir), { recursive: true, mode: options.dirMode ?? 0o700 });
     if (options.chmodDir !== false) {
         await applyDirectoryMode({
@@ -30,9 +35,10 @@ export async function writeSiblingTempFile(options) {
         });
     }
     return await writeCallbackSibling({
-        tempPath: buildTempPath(dir, options.tempPrefix),
+        tempDir: dir,
+        tempName: buildTempName(options.tempPrefix),
         write: options.writeTemp,
-        producerIsolation: options.producerIsolation,
+        producerIsolation,
         resolveFinalPath: options.resolveFinalPath,
         mode: options.mode,
         ignoreModeError: true,
@@ -40,7 +46,7 @@ export async function writeSiblingTempFile(options) {
         syncParentDir: options.syncParentDir === true,
     });
 }
-function buildSiblingTempPath(params) {
+function buildSiblingTempName(params) {
     const id = crypto.randomUUID();
     const safePrefix = assertSafePathPrefix(params.tempPrefix, {
         label: "sibling temp prefix",
@@ -52,17 +58,23 @@ function buildSiblingTempPath(params) {
         fileName: sanitizeUntrustedFileName(path.basename(params.targetPath), params.fallbackFileName),
         suffix,
     });
-    return path.join(path.dirname(params.targetPath), `${prefix}${safeTail}${suffix}`);
+    return `${prefix}${safeTail}${suffix}`;
 }
 export async function writeViaSiblingTempPath(params) {
+    const rootDirInput = params.rootDir;
+    const targetPathInput = params.targetPath;
+    assertNoWindowsPathAlias(rootDirInput, "filesystem", "sibling temp root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(targetPathInput, "filesystem", "sibling temp target uses a Windows filesystem namespace alias");
     let rootDir;
     try {
-        rootDir = realpathSync.native(path.resolve(params.rootDir));
+        rootDir = realpathSync.native(resolvePathPreservingWindowsRoot(rootDirInput));
     }
     catch {
-        rootDir = path.resolve(params.rootDir);
+        rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
     }
-    const requestedTargetPath = path.resolve(params.targetPath);
+    assertNoWindowsPathAlias(rootDir, "filesystem", "sibling temp root uses a Windows filesystem namespace alias");
+    const requestedTargetPath = path.resolve(targetPathInput);
+    assertNoWindowsPathAlias(requestedTargetPath, "filesystem", "sibling temp target uses a Windows filesystem namespace alias");
     let targetPath;
     try {
         const realDir = realpathSync.native(path.dirname(requestedTargetPath));
@@ -71,6 +83,7 @@ export async function writeViaSiblingTempPath(params) {
     catch {
         targetPath = requestedTargetPath;
     }
+    assertNoWindowsPathAlias(targetPath, "filesystem", "sibling temp target uses a Windows filesystem namespace alias");
     const relativeTargetPath = path.relative(rootDir, targetPath);
     if (!relativeTargetPath ||
         relativeTargetPath === ".." ||
@@ -87,12 +100,14 @@ export async function writeViaSiblingTempPath(params) {
         }),
         prefix: "fs-safe-output",
     });
+    assertNoWindowsPathAlias(workspace.dir, "filesystem", "sibling temp workspace uses a Windows filesystem namespace alias");
     try {
-        const tempPath = buildSiblingTempPath({
+        const tempName = buildSiblingTempName({
             targetPath: path.join(workspace.dir, path.basename(targetPath)),
             fallbackFileName: params.fallbackFileName ?? "output.bin",
             tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
         });
+        const tempPath = resolveCallbackTempPath(workspace.dir, tempName);
         await getFsSafeTestHooks()?.beforeSiblingTempWrite?.(tempPath);
         await params.writeTemp(tempPath);
         await assertAsyncDirectoryGuard(rootGuard);

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":"AAUA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAW3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAI5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEvF,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,CA6T5B"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAUA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAW3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAK5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEvF,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;AAoCF,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,CA2U5B"}

package/dist/sidecar-lock-acquire.js

@@ -13,8 +13,16 @@ import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransient
 import { readSidecarLockRawSnapshot, parseSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { sleep } from "./timing.js";
-async function resolveNormalizedTargetPath(targetPath, lockRoot) {
-    const resolved = path.resolve(targetPath);
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+function isCwdIndependentAbsolutePath(filePath) {
+    if (!path.isAbsolute(filePath))
+        return false;
+    // A leading separator on Windows is rooted on the process's current drive.
+    // Drive-qualified, UNC, and namespace roots are longer and need no cwd state.
+    return process.platform !== "win32" || path.parse(filePath).root.length > 1;
+}
+async function resolveNormalizedTargetPath(resolved, lockRoot) {
+    assertNoWindowsPathAlias(resolved);
     const dir = path.dirname(resolved);
     if (lockRoot) {
         // The target is an arbitration key, not necessarily inside the lock Root.
@@ -22,15 +30,23 @@ async function resolveNormalizedTargetPath(targetPath, lockRoot) {
         await lockRoot.resolve(".");
         const parent = await canonicalPathFromExistingAncestor(dir);
         await lockRoot.resolve(".");
-        return path.join(parent, path.basename(resolved));
+        assertNoWindowsPathAlias(parent);
+        const normalized = path.join(parent, path.basename(resolved));
+        assertNoWindowsPathAlias(normalized);
+        return normalized;
     }
     await fs.mkdir(recursiveMkdirPath(dir), { recursive: true });
+    let parent;
     try {
-        return path.join(realpathSync.native(dir), path.basename(resolved));
+        parent = realpathSync.native(dir);
     }
     catch {
         return resolved;
     }
+    assertNoWindowsPathAlias(parent);
+    const normalized = path.join(parent, path.basename(resolved));
+    assertNoWindowsPathAlias(normalized);
+    return normalized;
 }
 export async function acquireSidecarLock(options, context) {
     const retry = options.retry ?? {};
@@ -38,9 +54,24 @@ export async function acquireSidecarLock(options, context) {
     validateSidecarLockTimeoutMs(options.timeoutMs);
     validateSidecarLockStaleMs(options.staleMs);
     validateSidecarLockCompromiseCheckIntervalMs(options.compromiseCheckIntervalMs);
+    const targetPath = options.targetPath;
+    const explicitLockPath = options.lockPath;
+    const anchoredTargetPath = anchorWindowsDriveRelativePath(targetPath);
+    assertNoWindowsPathAlias(anchoredTargetPath);
+    const resolvedTargetPath = path.resolve(anchoredTargetPath);
+    let resolvedLockPath;
+    if (explicitLockPath !== undefined) {
+        const anchoredLockPath = anchorWindowsDriveRelativePath(explicitLockPath);
+        assertNoWindowsPathAlias(anchoredLockPath);
+        resolvedLockPath = isCwdIndependentAbsolutePath(explicitLockPath)
+            ? explicitLockPath
+            : path.resolve(anchoredLockPath);
+    }
     context.ensureExitCleanupRegistered();
-    const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath, options.lockRoot);
-    const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
+    const lockRoot = options.lockRoot;
+    const normalizedTargetPath = await resolveNormalizedTargetPath(resolvedTargetPath, lockRoot);
+    const lockPath = resolvedLockPath ?? `${normalizedTargetPath}.lock`;
+    assertNoWindowsPathAlias(lockPath);
     let held = context.held.get(normalizedTargetPath);
     if (held &&
         options.reentrantOwner !== undefined &&
@@ -58,7 +89,7 @@ export async function acquireSidecarLock(options, context) {
             options.reentrantOwner !== undefined &&
             held.reentrantOwner !== undefined &&
             options.reentrantOwner === held.reentrantOwner) {
-            held.refCount += 1;
+            held.refCount = (held.refCount ?? 1) + 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) {
@@ -118,8 +149,7 @@ export async function acquireSidecarLock(options, context) {
             const payload = await options.payload();
             const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
             try {
-                if (options.lockRoot) {
-                    const lockRoot = options.lockRoot;
+                if (lockRoot) {
                     const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
                     const observation = fileObservation();
                     try {
@@ -180,7 +210,7 @@ export async function acquireSidecarLock(options, context) {
                     snapshot,
                     acquiredAt: Date.now(),
                     metadata: options.metadata ?? {},
-                    lockRoot: options.lockRoot,
+                    lockRoot,
                     retainOnExit: options.retainOnExit,
                     parsePayload: options.parsePayload,
                 };
@@ -239,13 +269,13 @@ export async function acquireSidecarLock(options, context) {
                         // 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,
+                            lockRoot,
                             parsePayload: options.parsePayload,
                         });
                     }
                     else if (createdSnapshot) {
                         await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
-                            lockRoot: options.lockRoot,
+                            lockRoot,
                             parsePayload: options.parsePayload,
                         });
                     }
@@ -271,7 +301,7 @@ export async function acquireSidecarLock(options, context) {
                 let lockFileOpenDenied = false;
                 try {
                     rawSnapshot = await readSidecarLockRawSnapshot(lockPath, {
-                        lockRoot: options.lockRoot,
+                        lockRoot,
                         rejectNonFile: true,
                         discardObservation: "changed",
                         onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
@@ -302,7 +332,7 @@ export async function acquireSidecarLock(options, context) {
                     heldByThisProcess: context.held.has(normalizedTargetPath),
                 })) {
                     if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
-                        lockRoot: options.lockRoot,
+                        lockRoot,
                         parsePayload: options.parsePayload,
                     }))) {
                         await waitForRetry();
@@ -320,7 +350,7 @@ export async function acquireSidecarLock(options, context) {
                             normalizedTargetPath,
                             snapshot,
                             shouldRemoveStaleLock: options.shouldRemoveStaleLock,
-                            lockRoot: options.lockRoot,
+                            lockRoot,
                             parsePayload: options.parsePayload,
                         });
                         if (removal === "removed" || removal === "changed") {

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

@@ -1 +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"}
+{"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,CAyD5B"}

package/dist/sidecar-lock-root.js

@@ -53,13 +53,15 @@ export async function openSidecarRoot(lockRoot, relative, discardObservation, on
         if (!discardObservation || (!missing && (!completeParents || !discardable)))
             throw error;
         try {
+            const probe = fileObservation();
             try {
-                const current = await lockRoot.stat(relative);
+                const current = await probe.run(() => lockRoot.stat(relative));
                 if (!current.isFile || current.isSymbolicLink || current.nlink !== 1)
                     throw error;
             }
             catch (probeError) {
-                if (!(probeError instanceof FsSafeError && probeError.code === "not-found"))
+                if (!(probeError instanceof FsSafeError && probeError.code === "not-found") &&
+                    !probe.has(probeError, `stat-leaf-missing:${expectedRealPath}`))
                     throw probeError;
             }
             for (const { dir, stat } of parents)

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

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

package/dist/sidecar-lock.js

@@ -37,9 +37,6 @@ function resolveManagerState(key) {
         // Backfill state created by fs-safe versions that predate reclaim guards.
         state.reclaimCleanupRegistered ??= false;
         state.reclaimGuards ??= new Set();
-        for (const held of state.held.values()) {
-            held.refCount ??= 1;
-        }
     }
     return state;
 }
@@ -163,6 +160,8 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
         await held.releasePromise;
         return true;
     }
+    // Older package copies can add holders after this manager was constructed.
+    held.refCount ??= 1;
     if (options.force) {
         held.refCount = 0;
     }