@hominis/fireforge 0.44.4 → 0.46.0

package/dist/src/core/file-lock-owner.js

@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Owner record of a `withFileLock` directory: the file that says WHICH
+ * process holds the lock, so stale recovery can tell a dead holder from a
+ * slow one and release can refuse to remove a lock it no longer owns.
+ *
+ * Split out of `file-lock.ts` so the record's format, its write-and-verify
+ * contract, and the PID-reuse guard live in one place with their own tests.
+ */
+import { readFileSync } from 'node:fs';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { isProcessAlive, toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { sleep } from '../utils/sleep.js';
+/**
+ * Filename of a lock directory's owner record, relative to the lock dir.
+ *
+ * Re-exported by `file-lock.ts` so external readers (`tree-store.ts`) share
+ * the constant instead of re-spelling `'pid'`; the file *format* is
+ * documented on {@link readLockOwner}.
+ */
+export const LOCK_PID_FILE = 'pid';
+/**
+ * Prefix of the mechanical owner-record line that carries the acquisition
+ * wall time. It lives among the metadata lines (line 3 onward) so older
+ * readers, which treat everything past line 2 as free-form diagnostics,
+ * still parse the record; the current reader lifts it out of `metadata`.
+ * Diagnostic only — see {@link START_TICK_PREFIX} for the liveness field.
+ */
+const ACQUIRED_AT_PREFIX = 'acquired-at-ms=';
+/**
+ * Prefix of the owner-record line carrying the holder's own process start
+ * tick (`/proc/self/stat` field 22, in USER_HZ since boot). Written only
+ * where procfs exposes it (Linux). Boot-relative ticks are what the
+ * PID-reuse guard compares: unlike a wall-clock time they are immune to
+ * the clock being stepped by NTP/chrony/`date -s` between acquisition and
+ * probe, and a process's start tick never changes for its lifetime, so the
+ * comparison is exact rather than a tolerance window.
+ */
+const START_TICK_PREFIX = 'start-tick=';
+/**
+ * How many times the post-write read-back is retried when the READ itself
+ * errors (not when the record is absent or differs). An on-access scanner
+ * on Windows briefly holding the just-written file (`EBUSY`), or a FUSE
+ * mount's momentary `EIO`, must not be indistinguishable from "the record
+ * never landed" — that verdict releases a lock this process has correctly
+ * acquired and aborts the run before it starts.
+ */
+const READ_BACK_ATTEMPTS = 5;
+/** Pause between read-back attempts. */
+const READ_BACK_RETRY_MS = 20;
+/**
+ * Parses the on-disk record text. Returns `undefined` when the PID line
+ * does not parse as a finite integer.
+ */
+function parseLockOwnerRecord(pidContent) {
+    const [pidLine, tokenLine, ...trailingLines] = pidContent.split('\n');
+    const pid = parseInt((pidLine ?? '').trim(), 10);
+    if (!Number.isFinite(pid))
+        return undefined;
+    const metadata = [];
+    let acquiredAtMs;
+    let startTick;
+    for (const rawLine of trailingLines) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith(ACQUIRED_AT_PREFIX)) {
+            const parsed = Number.parseInt(line.slice(ACQUIRED_AT_PREFIX.length), 10);
+            if (Number.isFinite(parsed))
+                acquiredAtMs ??= parsed;
+            continue;
+        }
+        if (line.startsWith(START_TICK_PREFIX)) {
+            const parsed = Number.parseInt(line.slice(START_TICK_PREFIX.length), 10);
+            if (Number.isFinite(parsed))
+                startTick ??= parsed;
+            continue;
+        }
+        metadata.push(line);
+    }
+    const token = tokenLine?.trim();
+    const owner = { present: true, pid, metadata };
+    if (token !== undefined && token.length > 0)
+        owner.token = token;
+    if (acquiredAtMs !== undefined)
+        owner.acquiredAtMs = acquiredAtMs;
+    if (startTick !== undefined)
+        owner.startTick = startTick;
+    return owner;
+}
+/**
+ * Reads the owner PID (line 1), acquisition token (line 2), the mechanical
+ * `acquired-at-ms=` / `start-tick=` lines (when present), and diagnostic
+ * metadata (the remaining lines 3+) from a lock directory's PID file.
+ * Returns `{ present: false }` when the PID file is missing, unreadable, or
+ * the PID does not parse as a finite integer (caller falls back to the
+ * age-only staleness heuristic).
+ *
+ * File format note: external readers do `parseInt(content.trim(), 10)`,
+ * which parses the leading digits of a multi-line file — so the token and
+ * mechanical lines stay compatible.
+ *
+ * @param lockPath - Lock directory whose owner record to read
+ * @returns The parsed owner record, or `{ present: false }`
+ */
+export async function readLockOwner(lockPath) {
+    try {
+        const owner = parseLockOwnerRecord(await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8'));
+        if (owner !== undefined)
+            return owner;
+    }
+    catch {
+        // PID file missing or unreadable — treat as absent.
+    }
+    return { present: false };
+}
+/**
+ * Reads the just-written record back, retrying a READ ERROR a few times
+ * before giving up. A missing or malformed record is returned as-is (the
+ * caller treats it as a failed write); only errno-level failures retry.
+ */
+async function readBackLockOwner(lockPath) {
+    let lastError;
+    for (let attempt = 0; attempt < READ_BACK_ATTEMPTS; attempt++) {
+        try {
+            return parseLockOwnerRecord(await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8'));
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < READ_BACK_ATTEMPTS - 1)
+                await sleep(READ_BACK_RETRY_MS);
+        }
+    }
+    throw new Error(`owner record could not be read back: ${toError(lastError).message}`);
+}
+/**
+ * Stamps this process's ownership (PID, per-acquisition token, acquisition
+ * time, own start tick, diagnostic metadata) into a lock directory it has
+ * just created, and reads the record back to prove it landed.
+ *
+ * The write is FATAL. It used to be best-effort, on the theory that stale
+ * recovery would fall back to the age heuristic — but that heuristic reaps
+ * any owner-less lock after five minutes, and the build lock legitimately
+ * holds for hours. A holder whose record failed to write was therefore
+ * reaped mid-build and a second process entered the critical section. On
+ * failure the just-created lock directory is removed (nothing else can own
+ * it yet) and a {@link GeneralError} names the cause.
+ *
+ * @param lockPath - Lock directory this process has just `mkdir`'d
+ * @param token - Per-acquisition UUID, later checked by release
+ * @param ownerMetadata - Extra human-diagnostic lines (see `FileLockOptions.ownerMetadata`)
+ * @throws {GeneralError} When the record cannot be written or does not read back as written
+ */
+export async function writeLockOwner(lockPath, token, ownerMetadata) {
+    const metadata = ownerMetadata
+        ?.map((line) => line.replace(/\r?\n/g, ' ').trim())
+        .filter((line) => line.length > 0 &&
+        !line.startsWith(ACQUIRED_AT_PREFIX) &&
+        !line.startsWith(START_TICK_PREFIX)) ?? [];
+    const ownStartTick = readProcessStartTick(process.pid);
+    const mechanicalLines = [
+        `${ACQUIRED_AT_PREFIX}${Date.now()}`,
+        ...(ownStartTick === undefined ? [] : [`${START_TICK_PREFIX}${ownStartTick}`]),
+    ];
+    const record = `${process.pid}\n${token}\n${[...mechanicalLines, ...metadata].map((line) => `${line}\n`).join('')}`;
+    let failure;
+    try {
+        await writeFile(join(lockPath, LOCK_PID_FILE), record, 'utf-8');
+        const readBack = await readBackLockOwner(lockPath);
+        if (readBack !== undefined && readBack.pid === process.pid && readBack.token === token) {
+            return;
+        }
+        failure = new Error('owner record did not read back as written');
+    }
+    catch (error) {
+        failure = error;
+    }
+    try {
+        await rm(lockPath, { recursive: true, force: true });
+    }
+    catch (cleanupError) {
+        verbose(`Could not remove unowned lock ${lockPath}: ${toError(cleanupError).message}`);
+    }
+    throw new GeneralError(`Could not record ownership of lock ${lockPath}: ${toError(failure).message}. ` +
+        'The lock was released without running the operation — a lock with no readable owner ' +
+        'would be reaped as stale after five minutes and a second process could enter the ' +
+        'critical section. Check permissions and free space on the lock directory, then retry.', failure);
+}
+/**
+ * Boot-relative start tick of a process, where the platform exposes it
+ * cheaply.
+ *
+ * Linux only: field 22 of `/proc/<pid>/stat`, in USER_HZ since boot.
+ * Elsewhere (macOS, Windows) obtaining a start time means spawning
+ * `ps`/`wmic` per probe, which is not worth paying on every poll of a
+ * contended lock — those platforms return `undefined` and liveness stays
+ * PID-only.
+ *
+ * Deliberately NOT converted to wall-clock time via `/proc/stat` `btime`:
+ * on current kernels `btime` is derived from the realtime clock and moves
+ * with every clock step, so a wall-clock comparison against a recorded
+ * acquisition time misjudges a live holder as a reused PID after NTP steps
+ * the clock forward — and reaps a lock that is in use.
+ *
+ * @param pid - Process to look up
+ * @param procRoot - procfs mount, overridable for tests
+ * @returns Start tick, or `undefined` when unobtainable
+ */
+export function readProcessStartTick(pid, procRoot = '/proc') {
+    try {
+        const stat = readFileSync(join(procRoot, String(pid), 'stat'), 'utf-8');
+        // `comm` (field 2) is parenthesised and may itself contain spaces or
+        // parentheses, so split only what follows the LAST closing paren:
+        // field 3 (state) is then index 0 and field 22 (starttime) index 19.
+        const startTick = Number.parseInt(stat
+            .slice(stat.lastIndexOf(')') + 1)
+            .trim()
+            .split(/\s+/)[19] ?? '', 10);
+        return Number.isFinite(startTick) ? startTick : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether the process named by a lock's owner record is the SAME process
+ * that acquired the lock, not merely a live process wearing its PID.
+ *
+ * `isProcessAlive` answers "does this PID exist"; after a holder crashes,
+ * the kernel may hand its PID to a long-lived daemon, and a PID-only check
+ * then honours the dead lock until the waiter's timeout. Where the record
+ * carries the writer's start tick and the candidate's own tick is cheaply
+ * obtainable (see {@link readProcessStartTick}), the two must be equal: a
+ * different tick is a different process. Records without a start tick, and
+ * platforms without one, keep the PID-only answer.
+ *
+ * @param owner - Owner record fields that identify the holder
+ * @param procRoot - procfs mount, overridable for tests
+ * @returns True when the original holder is still running (or cannot be proven gone)
+ */
+export function isLockOwnerAlive(owner, procRoot) {
+    if (!isProcessAlive(owner.pid))
+        return false;
+    if (owner.startTick === undefined)
+        return true;
+    const currentStartTick = readProcessStartTick(owner.pid, procRoot);
+    if (currentStartTick === undefined)
+        return true;
+    if (currentStartTick !== owner.startTick) {
+        verbose(`Lock owner PID ${owner.pid} started at tick ${currentStartTick}, but the ` +
+            `record was written by a process started at tick ${owner.startTick} — the PID was ` +
+            'reused; treating the holder as dead');
+        return false;
+    }
+    return true;
+}

package/dist/src/core/file-lock.d.ts

@@ -1,3 +1,5 @@
+import { LOCK_PID_FILE } from './file-lock-owner.js';
+export { LOCK_PID_FILE };
 /**
  * Snapshot of the current lock holder handed to {@link FileLockOptions.onWaitProgress}.
  * `metadata` carries the pid file's human-diagnostic lines (line 3 onward,
@@ -95,13 +97,6 @@ export interface FileLockOptions {
 }
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
 export declare function createSiblingLockPath(filePath: string, suffix?: string): string;
-/**
- * Filename of a lock directory's owner record, relative to the lock dir.
- *
- * Exported so external readers (`tree-store.ts`) share the constant instead of
- * re-spelling `'pid'`; the file *format* is documented on {@link readLockOwner}.
- */
-export declare const LOCK_PID_FILE = "pid";
 /**
  * Reads the live waiter queue around `lockPath`, dropping entries whose
  * process is gone (a killed waiter must not inflate the depth forever).

package/dist/src/core/file-lock.js

@@ -1,11 +1,14 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { randomUUID } from 'node:crypto';
-import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { LockContentionError } from '../errors/base.js';
 import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
 import { ensureDir } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
+import { sleep } from '../utils/sleep.js';
+import { isLockOwnerAlive, LOCK_PID_FILE, readLockOwner, writeLockOwner, } from './file-lock-owner.js';
+export { LOCK_PID_FILE };
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
 const DEFAULT_LOCK_POLL_MS = 50;
 const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
@@ -23,52 +26,10 @@ const STALE_REPROBE_INTERVAL_MS = 5_000;
  * deadline extension but no progress line of its own.
  */
 const WAIT_PROBE_INTERVAL_MS = 5_000;
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
-}
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
 export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
     return `${filePath}${suffix}`;
 }
-/**
- * Filename of a lock directory's owner record, relative to the lock dir.
- *
- * Exported so external readers (`tree-store.ts`) share the constant instead of
- * re-spelling `'pid'`; the file *format* is documented on {@link readLockOwner}.
- */
-export const LOCK_PID_FILE = 'pid';
-/**
- * Reads the owner PID (line 1), acquisition token (line 2), and diagnostic
- * metadata (lines 3+, see {@link FileLockOptions.ownerMetadata}) from a lock
- * directory's PID file. Returns `{ present: false }` when the PID file is
- * missing or the PID does not parse as a finite integer (caller falls back
- * to the age-only staleness heuristic).
- *
- * File format note: external readers do `parseInt(content.trim(), 10)`,
- * which parses the leading digits of a multi-line file — so the token line
- * stays compatible.
- */
-async function readLockOwner(lockPath) {
-    try {
-        const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
-        const [pidLine, tokenLine, ...metadataLines] = pidContent.split('\n');
-        const pid = parseInt((pidLine ?? '').trim(), 10);
-        if (Number.isFinite(pid)) {
-            const metadata = metadataLines.map((line) => line.trim()).filter((line) => line.length > 0);
-            const token = tokenLine?.trim();
-            if (token !== undefined && token.length > 0) {
-                return { present: true, pid, token, metadata };
-            }
-            return { present: true, pid, metadata };
-        }
-    }
-    catch {
-        // PID file missing or unreadable — treat as absent.
-    }
-    return { present: false };
-}
 /** Sibling directory in which waiters advertise themselves. */
 function lockWaitersDir(lockPath) {
     return `${lockPath}.waiters`;
@@ -127,7 +88,7 @@ export async function readLockStatus(lockPath) {
     }
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
-        ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
+        ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
         : undefined;
     return { held: true, holder, heldForMs, queueDepth: queue.depth };
 }
@@ -138,10 +99,10 @@ export async function readLockStatus(lockPath) {
  */
 async function registerWaiter(lockPath, startedAt) {
     const dir = lockWaitersDir(lockPath);
-    const file = join(dir, `${String(startedAt)}-${String(process.pid)}-${randomUUID()}`);
+    const file = join(dir, `${startedAt}-${process.pid}-${randomUUID()}`);
     try {
         await ensureDir(dir);
-        await writeFile(file, `${String(process.pid)}\n`, 'utf-8');
+        await writeFile(file, `${process.pid}\n`, 'utf-8');
     }
     catch (error) {
         // Advisory only — never fail a lock acquisition over the queue display.
@@ -164,7 +125,7 @@ async function registerWaiter(lockPath, startedAt) {
 async function probeWaitState(lockPath, startedAt) {
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
-        ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
+        ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
         : undefined;
     return { holder, queue: await readLockQueue(lockPath, startedAt) };
 }
@@ -189,7 +150,7 @@ async function probeWaitState(lockPath, startedAt) {
  *   legitimately held and the caller should keep waiting.
  */
 async function reapStaleLock(lockPath, ageMs, onStaleLockMessage) {
-    const reapPath = `${lockPath}.reaping-${String(process.pid)}-${randomUUID()}`;
+    const reapPath = `${lockPath}.reaping-${process.pid}-${randomUUID()}`;
     try {
         await rename(lockPath, reapPath);
     }
@@ -205,16 +166,16 @@ async function reapStaleLock(lockPath, ageMs, onStaleLockMessage) {
     // We exclusively own reapPath now. Re-verify: the owner may have changed
     // between the staleness probe and the rename (release + fresh acquire).
     const owner = await readLockOwner(reapPath);
-    if (owner.present && isProcessAlive(owner.pid)) {
+    if (owner.present && isLockOwnerAlive(owner)) {
         try {
             await rename(reapPath, lockPath);
-            verbose(`Aborted stale-lock reap of ${lockPath}: owner PID ${String(owner.pid)} is alive (lock was re-acquired mid-probe)`);
+            verbose(`Aborted stale-lock reap of ${lockPath}: owner PID ${owner.pid} is alive (lock was re-acquired mid-probe)`);
         }
         catch (restoreError) {
             // Rename-back can only fail if a third process mkdir'd the lock path
             // in this instant. The displaced live owner keeps running without its
             // lock — surface it loudly instead of hiding the lost exclusion.
-            warn(`Could not restore live lock for PID ${String(owner.pid)} at ${lockPath} ` +
+            warn(`Could not restore live lock for PID ${owner.pid} at ${lockPath} ` +
                 `(${toError(restoreError).message}). Displaced lock kept at ${reapPath} for inspection.`);
         }
         return false;
@@ -246,13 +207,14 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
         // PID-first check an explicitly-dead owner unblocks immediately.
         const owner = await readLockOwner(lockPath);
         if (owner.present) {
-            if (!isProcessAlive(owner.pid)) {
+            if (!isLockOwnerAlive(owner)) {
                 return await reapStaleLock(lockPath, ageMs, onStaleLockMessage);
             }
-            // PID is alive — respect it regardless of age. A slow `mach build`
-            // legitimately holds the lock past the stale threshold and we don't
-            // want to race-remove it.
-            verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${String(owner.pid)} is still running — not removing`);
+            // The owner is alive (PID exists AND, where `/proc` can tell, it is
+            // the process that acquired the lock, not a recycled PID) — respect
+            // it regardless of age. A slow `mach build` legitimately holds the
+            // lock past the stale threshold and we don't want to race-remove it.
+            verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${owner.pid} is still running — not removing`);
             return false;
         }
         // No readable PID file. Fall back to the age-only heuristic so locks
@@ -281,19 +243,16 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
  * double-acquisition. When the PID file no longer names us, warn and leave
  * the directory alone.
  *
- * `ownerFileWritten` is false when our own owner-file write failed at
- * acquisition (non-fatal there); ownership then cannot be verified and the
- * removal is unconditional, which is strictly better than leaking the lock.
+ * The owner record is always present here: `writeLockOwner` is fatal, so an
+ * acquisition whose record failed to write never reached the operation.
  */
-async function releaseLock(lockPath, ownerToken, ownerFileWritten) {
-    if (ownerFileWritten) {
-        const owner = await readLockOwner(lockPath);
-        if (owner.present &&
-            (owner.pid !== process.pid || (owner.token !== undefined && owner.token !== ownerToken))) {
-            warn(`Not removing lock ${lockPath}: it is now owned by PID ${String(owner.pid)} — ` +
-                'this process no longer holds it.');
-            return;
-        }
+async function releaseLock(lockPath, ownerToken) {
+    const owner = await readLockOwner(lockPath);
+    if (owner.present &&
+        (owner.pid !== process.pid || (owner.token !== undefined && owner.token !== ownerToken))) {
+        warn(`Not removing lock ${lockPath}: it is now owned by PID ${owner.pid} — ` +
+            'this process no longer holds it.');
+        return;
     }
     await rm(lockPath, { recursive: true, force: true });
 }
@@ -339,19 +298,17 @@ export async function releaseLockIfOwned(lockPath) {
  */
 async function buildLockTimeoutError(lockPath, onTimeoutMessage, cause, queue) {
     const owner = await readLockOwner(lockPath);
-    const liveHolder = owner.present && isProcessAlive(owner.pid) ? owner : undefined;
+    const liveHolder = owner.present && isLockOwnerAlive(owner) ? owner : undefined;
     const details = liveHolder !== undefined && liveHolder.metadata.length > 0
         ? ` (${liveHolder.metadata.join(', ')})`
         : '';
     const position = formatQueuePositionReached(queue);
     if (onTimeoutMessage !== undefined) {
-        const identifiedHolder = liveHolder !== undefined
-            ? ` The lock is held by PID ${String(liveHolder.pid)}${details}.`
-            : '';
+        const identifiedHolder = liveHolder !== undefined ? ` The lock is held by PID ${liveHolder.pid}${details}.` : '';
         return new LockContentionError(`${onTimeoutMessage}${identifiedHolder}${position}`, cause);
     }
     const holderHint = liveHolder !== undefined
-        ? ` It is held by running process ${String(liveHolder.pid)}${details} — wait for it to finish, or stop it and retry.`
+        ? ` It is held by running process ${liveHolder.pid}${details} — wait for it to finish, or stop it and retry.`
         : ' If no other FireForge process is running, remove the lock directory and retry.';
     return new LockContentionError(`Timed out waiting for file lock ${lockPath}.${holderHint}${position}`, cause);
 }
@@ -369,9 +326,9 @@ function formatQueuePositionReached(queue) {
     if (queue === undefined || queue.depth === 0)
         return '';
     if (queue.ahead === 0) {
-        return ` You were next in a queue of ${String(queue.depth)} when the wait expired — a larger --wait-lock would very likely have got a turn.`;
+        return ` You were next in a queue of ${queue.depth} when the wait expired — a larger --wait-lock would very likely have got a turn.`;
     }
-    return ` You were still ${String(queue.ahead)} from the head of a queue of ${String(queue.depth)} when the wait expired; re-run with a larger --wait-lock.`;
+    return ` You were still ${queue.ahead} from the head of a queue of ${queue.depth} when the wait expired; re-run with a larger --wait-lock.`;
 }
 /**
  * Runs one wait probe: reads holder and queue, and reports progress when the
@@ -515,28 +472,20 @@ export async function withFileLock(lockPath, operation, options = {}) {
         // acquired the lock or timed out.
         await deregisterWaiter?.();
     }
-    // Stamp ownership (PID + per-acquisition token) into the lock directory so
-    // stale-lock recovery can check liveness and release can verify the lock
-    // is still ours before removing it.
+    // Stamp ownership (PID + per-acquisition token + acquisition time) into
+    // the lock directory so stale-lock recovery can check liveness and release
+    // can verify the lock is still ours before removing it. Fatal on failure:
+    // an owner-less lock is reaped by the age heuristic after five minutes,
+    // which for a multi-hour build meant a second holder mid-critical-section.
+    // `writeLockOwner` removes the just-created directory before throwing.
     const ownerToken = randomUUID();
-    let ownerFileWritten = false;
-    try {
-        const metadata = options.ownerMetadata
-            ?.map((line) => line.replace(/\r?\n/g, ' ').trim())
-            .filter((line) => line.length > 0) ?? [];
-        await writeFile(join(lockPath, LOCK_PID_FILE), `${String(process.pid)}\n${ownerToken}\n${metadata.length > 0 ? `${metadata.join('\n')}\n` : ''}`, 'utf-8');
-        ownerFileWritten = true;
-    }
-    catch {
-        // Non-fatal: stale recovery falls back to age-only heuristic and release
-        // falls back to unconditional removal.
-    }
+    await writeLockOwner(lockPath, ownerToken, options.ownerMetadata);
     heldLocks.add(lockPath);
     try {
         return await operation();
     }
     finally {
         heldLocks.delete(lockPath);
-        await releaseLock(lockPath, ownerToken, ownerFileWritten);
+        await releaseLock(lockPath, ownerToken);
     }
 }

package/dist/src/core/firefox-cache.d.ts

@@ -3,13 +3,25 @@
  */
 import type { ResolvedArchive } from './firefox-archive.js';
 import type { ProgressCallback } from './firefox-download.js';
+/** Options governing the default (unpinned) integrity check. */
+export interface ArchiveIntegrityOptions {
+    /**
+     * Accept the download with a warning when the published SHA256SUMS cannot
+     * be obtained (`firefox.allowUnverifiedDownload`). Default: fail closed.
+     */
+    allowUnverifiedDownload?: boolean;
+}
 /**
  * Ensures a valid cached archive exists, downloading it if needed.
  * @param archive - Resolved archive descriptor
  * @param cacheDir - Cache directory
  * @param onProgress - Optional progress callback
+ * @param expectedSha256 - Operator-pinned digest; when set it replaces the
+ *   published-SHA256SUMS check
+ * @param onCacheProgress - Phase progress messages
+ * @param integrity - Default integrity-check options (unpinned downloads)
  */
-export declare function ensureCachedArchive(archive: ResolvedArchive, cacheDir: string, onProgress?: ProgressCallback, expectedSha256?: string, onCacheProgress?: (message: string) => void): Promise<void>;
+export declare function ensureCachedArchive(archive: ResolvedArchive, cacheDir: string, onProgress?: ProgressCallback, expectedSha256?: string, onCacheProgress?: (message: string) => void, integrity?: ArchiveIntegrityOptions): Promise<void>;
 /**
  * Removes cached tarball, metadata, and partial download files for an archive.
  * @param archive - Resolved archive descriptor