@nomicfoundation/hardhat-utils 3.0.6 → 4.0.0

package/dist/src/synchronization.d.ts

@@ -1,7 +1,105 @@
+export { IncompatibleHostnameMultiProcessMutexError, IncompatibleMultiProcessMutexError, IncompatiblePlatformMultiProcessMutexError, IncompatibleUidMultiProcessMutexError, InvalidMultiProcessMutexPathError, MultiProcessMutexError, MultiProcessMutexTimeoutError, StaleMultiProcessMutexError, } from "./errors/synchronization.js";
+/**
+ * A class that implements an inter-process mutex.
+ *
+ * This Mutex is implemented using hard-link-based atomic file creation. A
+ * temporary file containing JSON metadata (PID, hostname, platform, uid,
+ * session ID, and creation timestamp) is written first, then hard-linked to
+ * the lock path via `fs.linkSync`. `linkSync` fails atomically with `EEXIST`
+ * if the lock already exists, ensuring only one process can hold the lock at
+ * a time.
+ *
+ * Staleness is determined by PID liveness only — timestamps are stored for
+ * debugging purposes but are never used to determine staleness. This avoids the
+ * clock-skew and long-running-task problems that time-based staleness detection
+ * has (where a second process can break into a lock that's still legitimately
+ * held).
+ *
+ * Incompatible locks — those created by a different hostname, platform, or
+ * uid — are rejected immediately with specific subclasses of
+ * `IncompatibleMultiProcessMutexError`
+ * (`IncompatibleHostnameMultiProcessMutexError`,
+ * `IncompatiblePlatformMultiProcessMutexError`, or
+ * `IncompatibleUidMultiProcessMutexError`) because their PID liveness cannot
+ * be verified or their lock file cannot be removed. These must be removed
+ * manually.
+ *
+ * When the lock is held by a live process, the caller polls with exponential
+ * backoff (default: 5ms → 10ms → ...  → 160ms → 200ms cap) until the lock is
+ * released or a timeout (default: 60s) is reached.
+ *
+ * If the filesystem does not support hard links (e.g., certain network
+ * filesystems), acquisition fails fast with a `MultiProcessMutexError` rather
+ * than degrading into timeout-based retries.
+ *
+ * ## Performance characteristics
+ *
+ * - **Uncontended acquisition:** One temp file write + one `linkSync` — takes
+ *   less than 1ms on most systems.
+ * - **Stale lock recovery:** One `readFileSync` to read metadata, one
+ *   `process.kill(pid, 0)` liveness check, and one `unlinkSync` to remove the
+ *   stale lock file before retrying acquisition. The retry is immediate (no
+ *   sleep), so recovery adds sub-millisecond overhead.
+ * - **Contended (live holder):** Polls with exponential backoff starting at
+ *   5ms and doubling each iteration until capped at 200ms. Worst-case latency
+ *   after the lock is released is up to `MAX_POLL_INTERVAL_MS` (200ms).
+ * - **Release:** A single `unlinkSync` call.
+ *
+ * ## Limitations
+ *
+ * - **Polling-based:** There is no filesystem notification; callers discover
+ *   that the lock is free only on the next poll, so there can be up to 200ms
+ *   of wasted wait time after the lock is released.
+ * - **Not reentrant:** The same process (or even the same `MultiProcessMutex`
+ *   instance) calling `use()` while already holding the lock will deadlock
+ *   until the timeout fires.
+ * - **Single-host, single-user only:** Encountering a lock from a different
+ *   hostname throws `IncompatibleHostnameMultiProcessMutexError`, a different
+ *   platform throws `IncompatiblePlatformMultiProcessMutexError`, and a
+ *   different uid throws `IncompatibleUidMultiProcessMutexError`. All extend
+ *   `IncompatibleMultiProcessMutexError`. This means the lock is not safe to
+ *   use on shared/networked filesystems (e.g., NFS) where multiple hosts or
+ *   users may access the same path.
+ * - **Requires hard-link support:** The underlying filesystem must support
+ *   `linkSync`. If hard links are unsupported, acquisition fails immediately
+ *   with `MultiProcessMutexError`.
+ * - **PID recycling:** If a process dies and the OS reassigns its PID to a new
+ *   unrelated process before the stale check runs, the lock is incorrectly
+ *   considered live. This is extremely unlikely in practice due to the large
+ *   PID space on modern systems.
+ * - **No fairness guarantee:** Multiple waiters polling concurrently have no
+ *   guaranteed ordering — whichever one succeeds at `linkSync` first after the
+ *   lock is released wins.
+ */
 export declare class MultiProcessMutex {
     #private;
-    constructor(mutexName: string, maxMutexLifespanInMs?: number);
+    /**
+     * Creates an inter-process mutex given an absolute path.
+     *
+     * @param absolutePathToLock The absolute path of the mutex.
+     * @param timeout The max amount of time to spend trying to acquire the lock
+     *  in milliseconds. Defaults to 60000.
+     * @param initialPollInterval The initial poll interval in milliseconds.
+     *  Defaults to 5.
+     */
+    constructor(absolutePathToLock: string, timeout?: number, initialPollInterval?: number);
+    /**
+     * Runs the function f while holding the mutex, returning its result.
+     *
+     * @param f The function to run.
+     * @returns The result of the function.
+     */
     use<T>(f: () => Promise<T>): Promise<T>;
+    /**
+     * Acquires the mutex, returning an async function to release it.
+     * The function MUST be called after using the mutex.
+     *
+     * If this function throws, no cleanup is necessary — the lock was never
+     * acquired.
+     *
+     * @returns The mutex's release function.
+     */
+    acquire(): Promise<() => Promise<void>>;
 }
 /**
  * A class that implements an asynchronous mutex (mutual exclusion) lock.

package/dist/src/synchronization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"synchronization.d.ts","sourceRoot":"","sources":["../../src/synchronization.ts"],"names":[],"mappings":"AAwBA,qBAAa,iBAAiB;;gBAIhB,SAAS,EAAE,MAAM,EAAE,oBAAoB,CAAC,EAAE,MAAM;IAQ/C,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CA8HrD;AAED;;;;;GAKG;AACH,qBAAa,UAAU;;IAIrB;;;;;;OAMG;IACU,YAAY,CAAC,OAAO,EAC/B,CAAC,EAAE,MAAM,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CA+B7B"}
+{"version":3,"file":"synchronization.d.ts","sourceRoot":"","sources":["../../src/synchronization.ts"],"names":[],"mappings":"AAqBA,OAAO,EACL,0CAA0C,EAC1C,kCAAkC,EAClC,0CAA0C,EAC1C,qCAAqC,EACrC,iCAAiC,EACjC,sBAAsB,EACtB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AAgCrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,qBAAa,iBAAiB;;IAK5B;;;;;;;;OAQG;gBAED,kBAAkB,EAAE,MAAM,EAC1B,OAAO,CAAC,EAAE,MAAM,EAChB,mBAAmB,CAAC,EAAE,MAAM;IAY9B;;;;;OAKG;IACU,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAUpD;;;;;;;;OAQG;IACU,OAAO,IAAI,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CA+XrD;AAED;;;;;GAKG;AACH,qBAAa,UAAU;;IAIrB;;;;;;OAMG;IACU,YAAY,CAAC,OAAO,EAC/B,CAAC,EAAE,MAAM,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CA+B7B"}

package/dist/src/synchronization.js

@@ -1,137 +1,455 @@
-// Logic explanation: the fs.writeFile function, when used with the wx+ flag, performs an atomic operation to create a file.
-// If multiple processes try to create the same file simultaneously, only one will succeed.
-// This logic can be utilized to implement a mutex.
-// ATTENTION: in the current implementation, there's still a risk of two processes running simultaneously.
-// For example, if processA has locked the mutex and is running, processB will wait.
-// During this wait, processB continuously checks the elapsed time since the mutex lock file was created.
-// If an excessive amount of time has passed, processB will assume ownership of the mutex to prevent stale locks, even if processA is still running.
-// As a result, two processes will be running simultaneously in what is theoretically a mutex-locked section.
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import debug from "debug";
-import { ensureNodeErrnoExceptionError } from "./error.js";
-import { FileSystemAccessError } from "./errors/fs.js";
-import { readUtf8File } from "./fs.js";
+import { ensureError, ensureNodeErrnoExceptionError } from "./error.js";
+import { BaseMultiProcessMutexError, IncompatibleHostnameMultiProcessMutexError, IncompatiblePlatformMultiProcessMutexError, IncompatibleUidMultiProcessMutexError, InvalidMultiProcessMutexPathError, MultiProcessMutexError, MultiProcessMutexTimeoutError, StaleMultiProcessMutexError, } from "./errors/synchronization.js";
+import { ensureDir } from "./fs.js";
 import { sleep } from "./lang.js";
+export { IncompatibleHostnameMultiProcessMutexError, IncompatibleMultiProcessMutexError, IncompatiblePlatformMultiProcessMutexError, IncompatibleUidMultiProcessMutexError, InvalidMultiProcessMutexPathError, MultiProcessMutexError, MultiProcessMutexTimeoutError, StaleMultiProcessMutexError, } from "./errors/synchronization.js";
 const log = debug("hardhat:util:multi-process-mutex");
-const DEFAULT_MAX_MUTEX_LIFESPAN_IN_MS = 60000;
-const MUTEX_LOOP_WAITING_TIME_IN_MS = 100;
+const PROCESS_SESSION_ID = randomUUID();
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_INITIAL_POLL_INTERVAL_MS = 5;
+const MAX_POLL_INTERVAL_MS = 200;
+/**
+ * Error codes indicating hard links are definitively unsupported on the
+ * target filesystem. These cause immediate failure rather than retries.
+ */
+const HARD_LINK_UNSUPPORTED_CODES = new Set(["EOPNOTSUPP", "ENOTSUP", "EXDEV"]);
+/**
+ * A class that implements an inter-process mutex.
+ *
+ * This Mutex is implemented using hard-link-based atomic file creation. A
+ * temporary file containing JSON metadata (PID, hostname, platform, uid,
+ * session ID, and creation timestamp) is written first, then hard-linked to
+ * the lock path via `fs.linkSync`. `linkSync` fails atomically with `EEXIST`
+ * if the lock already exists, ensuring only one process can hold the lock at
+ * a time.
+ *
+ * Staleness is determined by PID liveness only — timestamps are stored for
+ * debugging purposes but are never used to determine staleness. This avoids the
+ * clock-skew and long-running-task problems that time-based staleness detection
+ * has (where a second process can break into a lock that's still legitimately
+ * held).
+ *
+ * Incompatible locks — those created by a different hostname, platform, or
+ * uid — are rejected immediately with specific subclasses of
+ * `IncompatibleMultiProcessMutexError`
+ * (`IncompatibleHostnameMultiProcessMutexError`,
+ * `IncompatiblePlatformMultiProcessMutexError`, or
+ * `IncompatibleUidMultiProcessMutexError`) because their PID liveness cannot
+ * be verified or their lock file cannot be removed. These must be removed
+ * manually.
+ *
+ * When the lock is held by a live process, the caller polls with exponential
+ * backoff (default: 5ms → 10ms → ...  → 160ms → 200ms cap) until the lock is
+ * released or a timeout (default: 60s) is reached.
+ *
+ * If the filesystem does not support hard links (e.g., certain network
+ * filesystems), acquisition fails fast with a `MultiProcessMutexError` rather
+ * than degrading into timeout-based retries.
+ *
+ * ## Performance characteristics
+ *
+ * - **Uncontended acquisition:** One temp file write + one `linkSync` — takes
+ *   less than 1ms on most systems.
+ * - **Stale lock recovery:** One `readFileSync` to read metadata, one
+ *   `process.kill(pid, 0)` liveness check, and one `unlinkSync` to remove the
+ *   stale lock file before retrying acquisition. The retry is immediate (no
+ *   sleep), so recovery adds sub-millisecond overhead.
+ * - **Contended (live holder):** Polls with exponential backoff starting at
+ *   5ms and doubling each iteration until capped at 200ms. Worst-case latency
+ *   after the lock is released is up to `MAX_POLL_INTERVAL_MS` (200ms).
+ * - **Release:** A single `unlinkSync` call.
+ *
+ * ## Limitations
+ *
+ * - **Polling-based:** There is no filesystem notification; callers discover
+ *   that the lock is free only on the next poll, so there can be up to 200ms
+ *   of wasted wait time after the lock is released.
+ * - **Not reentrant:** The same process (or even the same `MultiProcessMutex`
+ *   instance) calling `use()` while already holding the lock will deadlock
+ *   until the timeout fires.
+ * - **Single-host, single-user only:** Encountering a lock from a different
+ *   hostname throws `IncompatibleHostnameMultiProcessMutexError`, a different
+ *   platform throws `IncompatiblePlatformMultiProcessMutexError`, and a
+ *   different uid throws `IncompatibleUidMultiProcessMutexError`. All extend
+ *   `IncompatibleMultiProcessMutexError`. This means the lock is not safe to
+ *   use on shared/networked filesystems (e.g., NFS) where multiple hosts or
+ *   users may access the same path.
+ * - **Requires hard-link support:** The underlying filesystem must support
+ *   `linkSync`. If hard links are unsupported, acquisition fails immediately
+ *   with `MultiProcessMutexError`.
+ * - **PID recycling:** If a process dies and the OS reassigns its PID to a new
+ *   unrelated process before the stale check runs, the lock is incorrectly
+ *   considered live. This is extremely unlikely in practice due to the large
+ *   PID space on modern systems.
+ * - **No fairness guarantee:** Multiple waiters polling concurrently have no
+ *   guaranteed ordering — whichever one succeeds at `linkSync` first after the
+ *   lock is released wins.
+ */
 export class MultiProcessMutex {
-    #mutexFilePath;
-    #mutexLifespanInMs;
-    constructor(mutexName, maxMutexLifespanInMs) {
-        log(`Creating mutex with name '${mutexName}'`);
-        this.#mutexFilePath = path.join(os.tmpdir(), `${mutexName}.txt`);
-        this.#mutexLifespanInMs =
-            maxMutexLifespanInMs ?? DEFAULT_MAX_MUTEX_LIFESPAN_IN_MS;
+    #lockFilePath;
+    #timeout;
+    #initialPollInterval;
+    /**
+     * Creates an inter-process mutex given an absolute path.
+     *
+     * @param absolutePathToLock The absolute path of the mutex.
+     * @param timeout The max amount of time to spend trying to acquire the lock
+     *  in milliseconds. Defaults to 60000.
+     * @param initialPollInterval The initial poll interval in milliseconds.
+     *  Defaults to 5.
+     */
+    constructor(absolutePathToLock, timeout, initialPollInterval) {
+        if (!path.isAbsolute(absolutePathToLock)) {
+            throw new InvalidMultiProcessMutexPathError(absolutePathToLock);
+        }
+        this.#lockFilePath = absolutePathToLock;
+        this.#timeout = timeout ?? DEFAULT_TIMEOUT_MS;
+        this.#initialPollInterval =
+            initialPollInterval ?? DEFAULT_INITIAL_POLL_INTERVAL_MS;
     }
+    /**
+     * Runs the function f while holding the mutex, returning its result.
+     *
+     * @param f The function to run.
+     * @returns The result of the function.
+     */
     async use(f) {
-        log(`Starting mutex process with mutex file '${this.#mutexFilePath}'`);
-        while (true) {
-            if (await this.#tryToAcquireMutex()) {
-                // Mutex has been acquired
-                return this.#executeFunctionAndReleaseMutex(f);
+        const release = await this.acquire();
+        try {
+            return await f();
+        }
+        finally {
+            await release();
+        }
+    }
+    /**
+     * Acquires the mutex, returning an async function to release it.
+     * The function MUST be called after using the mutex.
+     *
+     * If this function throws, no cleanup is necessary — the lock was never
+     * acquired.
+     *
+     * @returns The mutex's release function.
+     */
+    async acquire() {
+        log(`Starting mutex process with lock file '${this.#lockFilePath}'`);
+        try {
+            await this.#acquireLock();
+        }
+        catch (e) {
+            ensureError(e);
+            if (e instanceof BaseMultiProcessMutexError) {
+                throw e;
+            }
+            throw new MultiProcessMutexError(this.#lockFilePath, e);
+        }
+        let released = false;
+        return async () => {
+            if (released) {
+                return;
             }
-            // Mutex not acquired
-            if (this.#isMutexFileTooOld()) {
-                // If the mutex file is too old, it likely indicates a stale lock, so the file should be removed
-                log(`Current mutex file is too old, removing it at path '${this.#mutexFilePath}'`);
-                this.#deleteMutexFile();
+            this.#releaseLock();
+            released = true;
+        };
+    }
+    async #acquireLock() {
+        const startTime = Date.now();
+        let pollInterval = this.#initialPollInterval;
+        await ensureDir(path.dirname(this.#lockFilePath));
+        while (true) {
+            const result = this.#tryAcquire();
+            if (result.acquired) {
+                return;
             }
-            else if (await this.#isMutexProcessOwnerDead()) {
-                log(`The process owning the mutex file no longer exists. Removing mutex file at '${this.#mutexFilePath}'.`);
-                this.#deleteMutexFile();
+            // Check timeout
+            const elapsed = Date.now() - startTime;
+            if (elapsed >= this.#timeout) {
+                throw new MultiProcessMutexTimeoutError(this.#lockFilePath, this.#timeout);
             }
-            else {
-                // wait
-                await sleep(MUTEX_LOOP_WAITING_TIME_IN_MS / 1000);
+            // Skip sleep after reclaiming a stale lock — retry immediately
+            if (result.reclaimedStaleLock) {
+                continue;
             }
+            // Wait with exponential backoff
+            log(`Lock at ${this.#lockFilePath} is busy, waiting ${pollInterval}ms`);
+            await sleep(pollInterval / 1000);
+            // Exponential backoff, capped
+            pollInterval = Math.min(pollInterval * 2, MAX_POLL_INTERVAL_MS);
         }
     }
-    async #tryToAcquireMutex() {
+    #releaseLock() {
         try {
-            // Create a file only if it does not exist
-            fs.writeFileSync(this.#mutexFilePath, process.pid.toString(), {
-                flag: "wx+",
-            });
-            return true;
+            fs.unlinkSync(this.#lockFilePath);
+            log(`Released lock at ${this.#lockFilePath}`);
         }
         catch (e) {
             ensureNodeErrnoExceptionError(e);
-            if (e.code === "EEXIST") {
-                // File already exists, so the mutex is already acquired
-                return false;
+            if (e.code === "ENOENT") {
+                log(`Lock at ${this.#lockFilePath} already removed`);
+                return;
             }
-            throw new FileSystemAccessError(e.message, e);
+            throw new MultiProcessMutexError(this.#lockFilePath, e);
         }
     }
-    async #executeFunctionAndReleaseMutex(f) {
-        log(`Mutex acquired at path '${this.#mutexFilePath}'`);
+    #tryAcquire() {
+        const lockPath = this.#lockFilePath;
+        // Fast path: if the lock file already exists, check staleness directly
+        // without creating temp files. This is both an optimization for the
+        // common contended case and is required for correct behavior when the
+        // parent directory is read-only (stale locks can still be detected via
+        // readFileSync even when file creation in the directory is blocked).
+        //
+        // Note: handleExistingLock() must be called outside the try/catch so
+        // that errors like StaleMultiProcessMutexError propagate correctly.
+        let lockExists = false;
         try {
-            return await f();
+            fs.accessSync(lockPath, fs.constants.F_OK);
+            lockExists = true;
         }
-        finally {
-            // Release the mutex
-            // Note: if a process dies, its `finally` block never executes, and the process hangs indefinitely since no response is received.
-            // To handle this, we use the function `isMutexProcessOwnerDead`.
-            log(`Mutex released at path '${this.#mutexFilePath}'`);
-            this.#deleteMutexFile();
-            log(`Mutex released at path '${this.#mutexFilePath}'`);
+        catch {
+            // Lock doesn't exist (or can't be checked) — proceed to acquire
         }
-    }
-    #isMutexFileTooOld() {
-        let fileStat;
+        if (lockExists) {
+            return this.#handleExistingLock();
+        }
+        // Lock doesn't appear to exist — try to acquire via temp file + hard link
+        const metadata = this.#buildMetadata();
+        const contents = JSON.stringify(metadata, null, 2);
+        const randomSuffix = Math.random().toString(16).slice(2);
+        const tempPath = `${lockPath}.tmp-${process.pid}-${PROCESS_SESSION_ID}-${Date.now()}-${randomSuffix}`;
+        let tempFd;
         try {
-            fileStat = fs.statSync(this.#mutexFilePath);
+            // Create temp file with exclusive flag to prevent collisions
+            tempFd = fs.openSync(tempPath, "wx");
+            fs.writeFileSync(tempFd, contents, "utf8");
+            fs.closeSync(tempFd);
+            tempFd = undefined;
+            // Attempt atomic hard link to the lock path
+            fs.linkSync(tempPath, lockPath);
+            log(`Acquired lock at ${lockPath}`);
+            // Best-effort cleanup of temp files left by dead processes.
+            // We hold the lock, so only one process runs this at a time.
+            this.#cleanupDeadProcessTempFiles();
+            return { acquired: true };
         }
         catch (e) {
             ensureNodeErrnoExceptionError(e);
+            if (e.code === "EEXIST") {
+                // Lock was created between our accessSync and linkSync
+                return this.#handleExistingLock();
+            }
             if (e.code === "ENOENT") {
-                // The file might have been deleted by another process while this function was trying to access it.
-                return false;
+                // Parent directory doesn't exist. Create it and retry.
+                const parentDir = path.dirname(lockPath);
+                log(`Parent directory ${parentDir} does not exist, creating it`);
+                fs.mkdirSync(parentDir, { recursive: true });
+                return { acquired: false, reclaimedStaleLock: false };
+            }
+            // Hard links definitively unsupported — fail fast
+            if (HARD_LINK_UNSUPPORTED_CODES.has(e.code ?? "")) {
+                throw new MultiProcessMutexError(lockPath, e);
+            }
+            // We retry on permission errors, as this is a common transient failure
+            // on Windows.
+            if (e.code === "EPERM" || e.code === "EACCES") {
+                log("Failed to acquire lock, retrying due to permission error");
+                return { acquired: false, reclaimedStaleLock: false };
             }
-            throw new FileSystemAccessError(e.message, e);
+            // Any other error (ENAMETOOLONG, ENOSPC, etc.)
+            throw new MultiProcessMutexError(lockPath, e);
+        }
+        finally {
+            // Close fd if still open (write or close failed)
+            if (tempFd !== undefined) {
+                try {
+                    fs.closeSync(tempFd);
+                }
+                catch {
+                    // Best effort
+                }
+            }
+            // Always clean up the temp file
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch {
+                // Best effort — file may not exist if openSync failed
+            }
+        }
+    }
+    #handleExistingLock() {
+        const staleness = this.#checkStaleness();
+        if (staleness.isStale) {
+            const reclaimed = this.#tryUnlockingStaleLock(staleness.metadata);
+            return { acquired: false, reclaimedStaleLock: reclaimed };
         }
-        const now = new Date();
-        const fileDate = new Date(fileStat.ctime);
-        const diff = now.getTime() - fileDate.getTime();
-        return diff > this.#mutexLifespanInMs;
+        return { acquired: false, reclaimedStaleLock: false };
     }
-    #deleteMutexFile() {
+    #checkStaleness() {
+        const lockPath = this.#lockFilePath;
+        const metadata = this.#readMetadata();
+        if (metadata === undefined) {
+            log(`Lock at ${lockPath} has missing/corrupt metadata, treating as stale`);
+            return { isStale: true, metadata: undefined };
+        }
+        // Different hostname — can't verify PID remotely
+        if (metadata.hostname !== os.hostname()) {
+            throw new IncompatibleHostnameMultiProcessMutexError(lockPath, metadata.hostname, os.hostname());
+        }
+        // Different platform — can't verify PID across platforms
+        if (metadata.platform !== process.platform) {
+            throw new IncompatiblePlatformMultiProcessMutexError(lockPath, metadata.platform, process.platform);
+        }
+        // Different uid — can't remove a lock owned by another user
+        const currentUid = process.getuid?.();
+        if (metadata.uid !== undefined &&
+            currentUid !== undefined &&
+            metadata.uid !== currentUid) {
+            throw new IncompatibleUidMultiProcessMutexError(lockPath, metadata.uid, currentUid);
+        }
+        // PID liveness check
+        if (!this.#isProcessAlive(metadata.pid)) {
+            log(`Lock at ${lockPath} owned by dead process PID=${metadata.pid}`);
+            return { isStale: true, metadata };
+        }
+        // Process is alive, lock is not stale
+        return { isStale: false };
+    }
+    #tryUnlockingStaleLock(metadata) {
+        const lockPath = this.#lockFilePath;
         try {
-            log(`Deleting mutex file at path '${this.#mutexFilePath}'`);
-            fs.unlinkSync(this.#mutexFilePath);
+            fs.unlinkSync(lockPath);
+            log(`Removed stale lock at ${lockPath}`);
         }
         catch (e) {
             ensureNodeErrnoExceptionError(e);
             if (e.code === "ENOENT") {
-                // The file might have been deleted by another process while this function was trying to access it.
-                return;
+                // Already removed by another process — safe to retry acquisition
+                log(`Stale lock at ${lockPath} already removed by another process`);
+                return true;
+            }
+            if (e.code === "EACCES" || e.code === "EPERM" || e.code === "EBUSY") {
+                throw new StaleMultiProcessMutexError(lockPath, metadata?.uid, e);
             }
-            throw new FileSystemAccessError(e.message, e);
+            throw new MultiProcessMutexError(lockPath, e);
         }
+        // Best-effort cleanup of orphaned temp files from dead processes
+        this.#cleanupDeadProcessTempFiles();
+        return true;
     }
-    async #isMutexProcessOwnerDead() {
-        let mutexPid;
-        try {
-            // If the file doesn't exist, it means the owning process deleted it
-            mutexPid = await readUtf8File(this.#mutexFilePath);
-        }
-        catch (_e) {
-            return false;
-        }
+    /**
+     * Checks if a process with the given PID is alive using signal 0, which is
+     * a platform-independent existence check supported on both POSIX and Windows.
+     *
+     * `ESRCH` means the process doesn't exist. `EPERM` means it exists but
+     * belongs to another user — still alive.
+     */
+    #isProcessAlive(pid) {
         try {
-            process.kill(parseInt(mutexPid, 10), 0);
+            process.kill(pid, 0);
+            return true;
         }
         catch (e) {
             ensureNodeErrnoExceptionError(e);
             if (e.code === "ESRCH") {
-                // The process owning the mutex no longer exists
-                return true;
+                return false; // Process does not exist
             }
+            // EPERM means the process exists but we don't have permission to signal it
+            return true;
+        }
+    }
+    #buildMetadata() {
+        return {
+            pid: process.pid,
+            hostname: os.hostname(),
+            createdAt: Date.now(),
+            ...(process.getuid !== undefined ? { uid: process.getuid() } : {}),
+            platform: process.platform,
+            sessionId: PROCESS_SESSION_ID,
+        };
+    }
+    #readMetadata() {
+        try {
+            const content = fs.readFileSync(this.#lockFilePath, "utf8");
+            const parsed = JSON.parse(content);
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                !("pid" in parsed) ||
+                !("hostname" in parsed) ||
+                !("createdAt" in parsed) ||
+                !("platform" in parsed) ||
+                typeof parsed.pid !== "number" ||
+                typeof parsed.hostname !== "string" ||
+                typeof parsed.createdAt !== "number" ||
+                typeof parsed.platform !== "string" ||
+                Number.isSafeInteger(parsed.pid) === false ||
+                parsed.pid < 1 ||
+                Number.isSafeInteger(parsed.createdAt) === false ||
+                parsed.createdAt < 1 ||
+                ("uid" in parsed &&
+                    parsed.uid !== undefined &&
+                    (typeof parsed.uid !== "number" ||
+                        Number.isSafeInteger(parsed.uid) === false)) ||
+                ("sessionId" in parsed && typeof parsed.sessionId !== "string")) {
+                return undefined;
+            }
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We just validated it
+            return parsed;
+        }
+        catch {
+            // Missing file, corrupt JSON, permission error — all treated as "no valid metadata"
+            return undefined;
+        }
+    }
+    /**
+     * Best-effort cleanup of orphaned temp files left by dead processes.
+     *
+     * Scans the parent directory for all temp files matching this lock's naming
+     * pattern (`{baseName}.tmp-{pid}-...`), parses the PID from each filename,
+     * and removes files whose PID is no longer alive. Files with unparseable
+     * PIDs are left untouched (conservative — don't delete what we can't verify).
+     *
+     * This is safe because the class is single-host-only (cross-host usage
+     * throws `IncompatibleHostnameMultiProcessMutexError`).
+     */
+    #cleanupDeadProcessTempFiles() {
+        const parentDir = path.dirname(this.#lockFilePath);
+        const baseName = path.basename(this.#lockFilePath);
+        const prefix = `${baseName}.tmp-`;
+        try {
+            const entries = fs.readdirSync(parentDir);
+            for (const entry of entries) {
+                if (!entry.startsWith(prefix)) {
+                    continue;
+                }
+                // Parse PID from filename: {baseName}.tmp-{pid}-{sessionId}-{ts}-{rand}
+                const afterPrefix = entry.slice(prefix.length);
+                const pidStr = afterPrefix.split("-")[0];
+                const pid = Number(pidStr);
+                if (!Number.isSafeInteger(pid) || pid < 1) {
+                    // Can't verify liveness — leave file alone
+                    continue;
+                }
+                if (this.#isProcessAlive(pid)) {
+                    continue;
+                }
+                try {
+                    fs.unlinkSync(path.join(parentDir, entry));
+                    log(`Cleaned up orphaned temp file: ${entry}`);
+                }
+                catch {
+                    // Best effort
+                }
+            }
+        }
+        catch {
+            // Best effort — parent directory may not be readable
         }
-        return false;
     }
 }
 /**