@hominis/fireforge 0.35.0 → 0.36.0

package/dist/src/core/config-validate-test-toolchains.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { ConfigError } from '../errors/config.js';
+import { parseObject } from '../utils/parse.js';
+import { isContainedRelativePath } from '../utils/paths.js';
+function optionalConfigString(rec, key, label) {
+    const value = rec.raw(key);
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new ConfigError(`Config field "${label}" must be a string`);
+    }
+    return value;
+}
+function optionalConfigObject(rec, key) {
+    const value = rec.raw(key);
+    if (value === undefined)
+        return undefined;
+    try {
+        return rec.object(key);
+    }
+    catch {
+        throw new ConfigError(`Config field "${key}" must be an object`);
+    }
+}
+/** Parses the optional `test` block. */
+export function parseTestBlock(rec, config) {
+    const testRec = optionalConfigObject(rec, 'test');
+    if (!testRec)
+        return;
+    const out = {};
+    const canaryPath = optionalConfigString(testRec, 'canaryPath', 'test.canaryPath');
+    if (canaryPath !== undefined) {
+        if (canaryPath.trim() === '' || !isContainedRelativePath(canaryPath)) {
+            throw new ConfigError('Config field "test.canaryPath" must be a project-relative path');
+        }
+        out.canaryPath = canaryPath;
+    }
+    const canaryTimeout = testRec.raw('canaryTimeoutSeconds');
+    if (canaryTimeout !== undefined) {
+        if (typeof canaryTimeout !== 'number' ||
+            !Number.isInteger(canaryTimeout) ||
+            canaryTimeout < 1 ||
+            canaryTimeout > 600) {
+            throw new ConfigError('Config field "test.canaryTimeoutSeconds" must be an integer in 1..600');
+        }
+        out.canaryTimeoutSeconds = canaryTimeout;
+    }
+    config.test = out;
+}
+/** Parses optional project-specific external toolchain doctor probes. */
+export function parseExternalToolchainsBlock(rec, config) {
+    const raw = rec.raw('externalToolchains');
+    if (raw === undefined)
+        return;
+    if (!Array.isArray(raw)) {
+        throw new ConfigError('Config field "externalToolchains" must be an array');
+    }
+    config.externalToolchains = raw.map((entry, index) => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw new ConfigError(`Config field "externalToolchains[${String(index)}]" must be an object`);
+        }
+        const item = entry;
+        const name = item['name'];
+        if (typeof name !== 'string' || name.trim() === '') {
+            throw new ConfigError(`Config field "externalToolchains[${String(index)}].name" must be a non-empty string`);
+        }
+        const tools = item['tools'];
+        if (!Array.isArray(tools) || tools.length === 0) {
+            throw new ConfigError(`Config field "externalToolchains[${String(index)}].tools" must be a non-empty array`);
+        }
+        return {
+            name,
+            tools: tools.map((tool, toolIndex) => parseExternalToolRequirement(tool, index, toolIndex)),
+        };
+    });
+}
+function parseExternalToolRequirement(tool, index, toolIndex) {
+    const label = `externalToolchains[${String(index)}].tools[${String(toolIndex)}]`;
+    if (typeof tool !== 'object' || tool === null || Array.isArray(tool)) {
+        throw new ConfigError(`Config field "${label}" must be an object`);
+    }
+    const toolRec = tool;
+    const toolName = toolRec['name'];
+    if (typeof toolName !== 'string' || toolName.trim() === '') {
+        throw new ConfigError(`Config field "${label}.name" must be a non-empty string`);
+    }
+    const toolPath = toolRec['path'];
+    if (toolPath !== undefined && (typeof toolPath !== 'string' || toolPath.trim() === '')) {
+        throw new ConfigError(`Config field "${label}.path" must be a non-empty string`);
+    }
+    const xcrun = toolRec['xcrun'];
+    if (xcrun !== undefined && typeof xcrun !== 'boolean') {
+        throw new ConfigError(`Config field "${label}.xcrun" must be a boolean`);
+    }
+    const required = toolRec['required'];
+    if (required !== undefined && typeof required !== 'boolean') {
+        throw new ConfigError(`Config field "${label}.required" must be a boolean`);
+    }
+    return {
+        name: toolName,
+        ...(toolPath !== undefined ? { path: toolPath } : {}),
+        ...(xcrun !== undefined ? { xcrun } : {}),
+        ...(required !== undefined ? { required } : {}),
+    };
+}

package/dist/src/core/config-validate.js

@@ -9,6 +9,7 @@ import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.
 import { isValidAppId, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
+import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
 /**
  * Parses and validates the four required identity fields (`name`,
  * `vendor`, `appId`, `binaryName`): all non-empty strings, with
@@ -145,6 +146,8 @@ export function validateConfig(data) {
     const firefox = parseFirefoxBlock(rec);
     const config = { ...identity, firefox };
     parseBuildBlock(rec, config);
+    parseTestBlock(rec, config);
+    parseExternalToolchainsBlock(rec, config);
     parseWireBlock(rec, config);
     parseLicenseField(rec, config);
     // Marker comment — appended to lines FireForge writes into upstream files.
@@ -429,4 +432,3 @@ function parseTypecheckProjectOverrides(raw, projects) {
     }
     return out;
 }
-//# sourceMappingURL=config-validate.js.map

package/dist/src/core/config.js

@@ -149,4 +149,3 @@ export async function withConfigFileLock(root, operation) {
             `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
     });
 }
-//# sourceMappingURL=config.js.map

package/dist/src/core/destructive.js

@@ -134,4 +134,3 @@ export async function appendHistory(patchesDir, entry) {
     const line = `${JSON.stringify(record)}\n`;
     await appendFile(join(patchesDir, HISTORY_LOG_FILENAME), line, 'utf-8');
 }
-//# sourceMappingURL=destructive.js.map

package/dist/src/core/diff-hunks.js

@@ -194,7 +194,6 @@ function coalescedHunk(oldLines, newLines, context) {
         return [];
     }
     const contextStart = Math.max(0, firstDiff - context);
-    const contextEndOld = Math.min(oldLines.length - 1, lastOldDiff + context);
     const contextEndNew = Math.min(newLines.length - 1, lastNewDiff + context);
     const hunkLines = [];
     for (let k = contextStart; k < firstDiff; k++) {
@@ -206,13 +205,21 @@ function coalescedHunk(oldLines, newLines, context) {
     for (let k = firstDiff; k <= lastNewDiff; k++) {
         hunkLines.push({ marker: '+', content: newLines[k] });
     }
-    const trailingStart = Math.max(lastOldDiff + 1, lastNewDiff + 1);
-    const trailingEnd = Math.max(contextEndOld, contextEndNew);
-    for (let k = trailingStart; k <= trailingEnd && k < newLines.length; k++) {
+    // Trailing context comes from the common suffix, which lives at
+    // DIFFERENT indices on each side (lastOldDiff+1… vs lastNewDiff+1…).
+    // The previous mixed-coordinate loop (max() of both sides indexing
+    // newLines) emitted wrong context on asymmetric edits, and the trailing
+    // lines were excluded from the @@ header lengths entirely — so on
+    // >LCS_LINE_LIMIT files the rendered header disagreed with the body.
+    for (let k = lastNewDiff + 1; k <= contextEndNew; k++) {
         hunkLines.push({ marker: ' ', content: newLines[k] });
     }
-    const oldLength = lastOldDiff - firstDiff + 1 + (firstDiff - contextStart);
-    const newLength = lastNewDiff - firstDiff + 1 + (firstDiff - contextStart);
+    const leadingContext = firstDiff - contextStart;
+    // Common-suffix symmetry: oldLen-1-lastOldDiff === newLen-1-lastNewDiff,
+    // so both sides clamp to the same trailing context count.
+    const trailingContext = contextEndNew - lastNewDiff;
+    const oldLength = lastOldDiff - firstDiff + 1 + leadingContext + trailingContext;
+    const newLength = lastNewDiff - firstDiff + 1 + leadingContext + trailingContext;
     return [
         {
             oldStart: contextStart + 1,
@@ -265,4 +272,3 @@ export function renderHunks(hunks) {
     }
     return out;
 }
-//# sourceMappingURL=diff-hunks.js.map

package/dist/src/core/engine-changes.js

@@ -61,4 +61,3 @@ export async function collectChangedEnginePaths(engineDir, baseline, contextLabe
     }
     return [...collected].sort();
 }
-//# sourceMappingURL=engine-changes.js.map

package/dist/src/core/engine-session-lock.d.ts

@@ -0,0 +1,12 @@
+/**
+ *
+ */
+export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>): Promise<T>;
+/**
+ *
+ */
+export declare function snapshotEngineGeneration(engineDir: string): Promise<string>;
+/**
+ *
+ */
+export declare function assertEngineGenerationUnchanged(engineDir: string, before: string): Promise<void>;

package/dist/src/core/engine-session-lock.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { withFileLock } from './file-lock.js';
+import { git } from './git-base.js';
+const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
+/**
+ *
+ */
+export async function withEngineSessionLock(projectRoot, command, operation) {
+    if (process.env['FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST'] !== '1' &&
+        (process.env['NODE_ENV'] === 'test' || process.env['VITEST'] !== undefined)) {
+        return operation();
+    }
+    return withFileLock(join(projectRoot, ENGINE_SESSION_LOCK_PATH), operation, {
+        timeoutMs: 1000,
+        ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
+        onTimeoutMessage: `Another FireForge engine-mutating command is already running. ` +
+            `Wait for it to finish, then retry \`${command}\`.`,
+        onStaleLockMessage: (ageMs) => `Removed stale FireForge engine session lock (${Math.round(ageMs / 1000)}s old).`,
+    });
+}
+/**
+ *
+ */
+export async function snapshotEngineGeneration(engineDir) {
+    try {
+        const head = (await git(['rev-parse', 'HEAD'], engineDir)).trim();
+        const status = await git(['status', '--porcelain=v1', '-z'], engineDir);
+        return `${head}\0${status}`;
+    }
+    catch (error) {
+        return `unavailable:${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+/**
+ *
+ */
+export async function assertEngineGenerationUnchanged(engineDir, before) {
+    const after = await snapshotEngineGeneration(engineDir);
+    if (after === before)
+        return;
+    throw new GeneralError('engine/ changed while `fireforge test` was running, so this test verdict is invalid/inconclusive.\n\n' +
+        'Use one writer per engine checkout, then rebuild and rerun the affected tests.');
+}

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

@@ -2,8 +2,16 @@ export interface FileLockOptions {
     timeoutMs?: number;
     pollMs?: number;
     staleMs?: number;
+    /**
+     * Interval between stale-lock probes while waiting (defaults to
+     * {@link STALE_REPROBE_INTERVAL_MS}). Exists mainly so tests can exercise
+     * the mid-wait reaping path without multi-second sleeps.
+     */
+    staleReprobeMs?: number;
     onTimeoutMessage?: string;
     onStaleLockMessage?: (ageMs: number) => string | undefined;
+    /** Extra owner-file lines for human diagnostics; ignored by lock mechanics. */
+    ownerMetadata?: readonly string[];
 }
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
 export declare function createSiblingLockPath(filePath: string, suffix?: string): string;

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { ensureDir } from '../utils/fs.js';
@@ -7,6 +8,15 @@ import { verbose, warn } from '../utils/logger.js';
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
 const DEFAULT_LOCK_POLL_MS = 50;
 const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
+/**
+ * Minimum interval between stale-lock probes while a waiter polls. The probe
+ * used to run exactly once per waiter: if the holder died *after* that single
+ * probe, the waiter polled a permanently dead lock until `timeoutMs` — for
+ * the build lock that meant up to 24 hours (see `withBuildLock` in mach.ts).
+ * Re-probing on a small interval bounds that hang to seconds while keeping
+ * the per-poll cost negligible (one stat + one small read every ~5 s).
+ */
+const STALE_REPROBE_INTERVAL_MS = 5_000;
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
@@ -39,6 +49,100 @@ function isProcessAlive(pid) {
         return getNodeErrorCode(error) !== 'ESRCH';
     }
 }
+/**
+ * Reads the owner PID (line 1) and acquisition token (line 2) 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 (`doctor-furnace.ts`, older FireForge
+ * releases) do `parseInt(content.trim(), 10)`, which parses the leading
+ * digits of a multi-line file — so adding the token line stays compatible.
+ */
+async function readLockOwner(lockPath) {
+    try {
+        const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
+        const [pidLine, tokenLine] = pidContent.split('\n');
+        const pid = parseInt((pidLine ?? '').trim(), 10);
+        if (Number.isFinite(pid)) {
+            const token = tokenLine?.trim();
+            if (token !== undefined && token.length > 0) {
+                return { present: true, pid, token };
+            }
+            return { present: true, pid };
+        }
+    }
+    catch {
+        // PID file missing or unreadable — treat as absent.
+    }
+    return { present: false };
+}
+/**
+ * Reaps a lock directory believed to be stale, safely against concurrent
+ * reapers and a concurrent legitimate re-acquisition.
+ *
+ * The naive stat → read-PID → `rm` sequence had a TOCTOU hole: two waiters
+ * could both observe the dead owner, one would remove the stale dir and
+ * `mkdir` its own lock, and the other's already-decided `rm` then deleted
+ * the *fresh* lock — two processes inside the critical section at once.
+ *
+ * Rename-aside closes it: `rename()` is atomic, so exactly one reaper wins
+ * ownership of the directory (the loser gets ENOENT and simply re-polls),
+ * and nothing ever deletes the live path directly. After winning the rename
+ * we re-read the owner from the renamed dir — if it is now a *live* process
+ * (the lock was released and re-acquired between our staleness read and the
+ * rename), we rename it back instead of reaping.
+ *
+ * @returns true when the caller should immediately retry `mkdir` (the lock
+ *   path is now free or was freed by someone else), false when the lock is
+ *   legitimately held and the caller should keep waiting.
+ */
+async function reapStaleLock(lockPath, ageMs, onStaleLockMessage) {
+    const reapPath = `${lockPath}.reaping-${String(process.pid)}-${randomUUID()}`;
+    try {
+        await rename(lockPath, reapPath);
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT') {
+            // Another reaper won, or the owner released — either way, retry mkdir.
+            verbose(`Stale lock disappeared before reaping completed: ${lockPath}`);
+            return true;
+        }
+        verbose(`Could not rename stale lock aside (${lockPath}): ${toError(error).message}`);
+        return false;
+    }
+    // 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)) {
+        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)`);
+        }
+        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} ` +
+                `(${toError(restoreError).message}). Displaced lock kept at ${reapPath} for inspection.`);
+        }
+        return false;
+    }
+    const staleMessage = onStaleLockMessage?.(ageMs);
+    if (staleMessage) {
+        warn(staleMessage);
+    }
+    else {
+        verbose(`Removing stale lock ${lockPath} (age: ${Math.round(ageMs / 1000)}s)`);
+    }
+    await rm(reapPath, { recursive: true, force: true });
+    return true;
+}
+/**
+ * Probes a contended lock for staleness and reaps it when the owner is gone.
+ *
+ * @returns true when the caller should immediately retry `mkdir`.
+ */
 async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     try {
         const lockStat = await stat(lockPath);
@@ -48,27 +152,19 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
         // 5 minutes) was never removed even when its PID file pointed at a
         // process that had already exited. That's the exact situation an
         // operator lands in after SIGINT'ing `furnace preview` — the signal
-        // handler calls `process.exit`, `withFileLock`'s `finally { rm }`
-        // never runs, and the next command has to either wait 5 minutes for
-        // the staleness gate or manually remove the lock directory. With the
-        // PID-first check, an explicitly-dead owner unblocks immediately.
-        const pidCheck = await readLockOwnerPid(lockPath);
-        if (pidCheck.present) {
-            if (!isProcessAlive(pidCheck.pid)) {
-                const staleMessage = onStaleLockMessage?.(ageMs);
-                if (staleMessage) {
-                    warn(staleMessage);
-                }
-                else {
-                    verbose(`Lock at ${lockPath} owner PID ${pidCheck.pid} is no longer running — removing (age: ${Math.round(ageMs / 1000)}s)`);
-                }
-                await rm(lockPath, { recursive: true, force: true });
-                return true;
+        // handler calls `process.exit`, `withFileLock`'s release never runs,
+        // and the next command has to either wait 5 minutes for the staleness
+        // gate or manually remove the lock directory. With the PID-first check,
+        // an explicitly-dead owner unblocks immediately.
+        const owner = await readLockOwner(lockPath);
+        if (owner.present) {
+            if (!isProcessAlive(owner.pid)) {
+                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 ${pidCheck.pid} is still running — not removing`);
+            verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${String(owner.pid)} is still running — not removing`);
             return false;
         }
         // No readable PID file. Fall back to the age-only heuristic so locks
@@ -77,12 +173,7 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
         if (ageMs <= staleMs) {
             return false;
         }
-        const staleMessage = onStaleLockMessage?.(ageMs);
-        if (staleMessage) {
-            warn(staleMessage);
-        }
-        await rm(lockPath, { recursive: true, force: true });
-        return true;
+        return await reapStaleLock(lockPath, ageMs, onStaleLockMessage);
     }
     catch (error) {
         const code = getNodeErrorCode(error);
@@ -95,30 +186,38 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     }
 }
 /**
- * Reads the owner PID from a lock directory's PID file. Returns `{ present:
- * false }` when the PID file is missing or the content does not parse as a
- * finite integer (caller falls back to the age-only staleness heuristic).
+ * Releases a lock previously acquired by this process, verifying ownership
+ * first. The unconditional `finally { rm }` this replaces would remove
+ * *whichever* lock directory was present — if a stale-lock reaper had (in a
+ * pathological race) replaced our lock, we deleted the new owner's lock and
+ * compounded the 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 we
+ * fall back to unconditional removal — identical to the historical behavior
+ * and strictly better than leaking the lock.
  */
-async function readLockOwnerPid(lockPath) {
-    try {
-        const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
-        const pid = parseInt(pidContent.trim(), 10);
-        if (Number.isFinite(pid)) {
-            return { present: true, pid };
+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;
         }
     }
-    catch {
-        // PID file missing or unreadable — treat as absent.
-    }
-    return { present: false };
+    await rm(lockPath, { recursive: true, force: true });
 }
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
 export async function withFileLock(lockPath, operation, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
     const pollMs = options.pollMs ?? DEFAULT_LOCK_POLL_MS;
     const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
+    const staleReprobeMs = options.staleReprobeMs ?? STALE_REPROBE_INTERVAL_MS;
     const deadline = Date.now() + timeoutMs;
-    let attemptedStaleRecovery = false;
+    let lastStaleProbeAt;
     await ensureDir(dirname(lockPath));
     for (;;) {
         try {
@@ -134,32 +233,42 @@ export async function withFileLock(lockPath, operation, options = {}) {
             if (!isAlreadyLocked) {
                 throw error;
             }
-            if (!attemptedStaleRecovery) {
-                attemptedStaleRecovery = true;
+            if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
+                lastStaleProbeAt = Date.now();
                 if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
                     continue;
                 }
             }
             if (Date.now() >= deadline) {
-                throw new Error(options.onTimeoutMessage ??
-                    `Timed out waiting for file lock ${lockPath}. Remove the lock directory if it is stale.`, { cause: error });
+                const owner = await readLockOwner(lockPath);
+                const holderHint = owner.present && isProcessAlive(owner.pid)
+                    ? ` It is held by running process ${String(owner.pid)} — wait for it to finish, or stop it and retry.`
+                    : ' If no other FireForge process is running, remove the lock directory and retry.';
+                throw new Error(options.onTimeoutMessage ?? `Timed out waiting for file lock ${lockPath}.${holderHint}`, { cause: error });
             }
             await sleep(pollMs);
         }
     }
-    // Write PID into the lock directory so stale-lock recovery can check
-    // whether the owning process is still alive before removing.
+    // 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.
+    const ownerToken = randomUUID();
+    let ownerFileWritten = false;
     try {
-        await writeFile(join(lockPath, LOCK_PID_FILE), String(process.pid), 'utf-8');
+        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
+        // Non-fatal: stale recovery falls back to age-only heuristic and release
+        // falls back to unconditional removal.
     }
     try {
         return await operation();
     }
     finally {
-        await rm(lockPath, { recursive: true, force: true });
+        await releaseLock(lockPath, ownerToken, ownerFileWritten);
     }
 }
-//# sourceMappingURL=file-lock.js.map

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

@@ -12,6 +12,10 @@ export interface ResolvedArchive {
     url: string;
     filename: string;
     metadataFilename: string;
+    /** URL of Mozilla's published SHA256SUMS file for the release. */
+    checksumsUrl: string;
+    /** The archive's path as listed inside SHA256SUMS (relative to the release dir). */
+    pathInChecksums: string;
 }
 /**
  * Sidecar metadata stored alongside a cached archive.

package/dist/src/core/firefox-archive.js

@@ -62,6 +62,11 @@ export function resolveArchive(version, product = 'firefox') {
         url: `${getArchiveBaseUrl(product)}/${archiveVersion}/source/firefox-${archiveVersion}.source.tar.xz`,
         filename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz`,
         metadataFilename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz.json`,
+        // Mozilla publishes one SHA256SUMS per release directory listing every
+        // artifact by its release-relative path. Downloads verify against it by
+        // default (fail closed on mismatch), so a compromised CDN response
+        // cannot silently become the trusted git baseline.
+        checksumsUrl: `${getArchiveBaseUrl(product)}/${archiveVersion}/SHA256SUMS`,
+        pathInChecksums: `source/firefox-${archiveVersion}.source.tar.xz`,
     };
 }
-//# sourceMappingURL=firefox-archive.js.map

package/dist/src/core/firefox-cache.js

@@ -10,7 +10,7 @@ import { pipeline } from 'node:stream/promises';
 import { ChecksumMismatchError } from '../errors/download.js';
 import { toError } from '../utils/errors.js';
 import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
+import { verbose, warn } from '../utils/logger.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { validateArchiveMetadata } from './firefox-archive.js';
 import { downloadFile } from './firefox-download.js';
@@ -24,6 +24,39 @@ async function sha256File(filePath) {
     await pipeline(stream, hash);
     return hash.digest('hex');
 }
+/**
+ * Fetches Mozilla's published SHA256SUMS for the release and extracts the
+ * digest for this archive. Returns null when the checksum file cannot be
+ * fetched or does not list the archive — the caller warns loudly and
+ * continues (offline mirrors and staging hosts legitimately lack it), while
+ * a FETCHED-but-mismatching digest always fails closed.
+ *
+ * Line format (both variants appear in the wild):
+ *   `<64-hex-digest>  <release-relative-path>`
+ *   `<64-hex-digest> *<release-relative-path>`
+ */
+async function fetchPublishedSha256(archive) {
+    try {
+        const response = await fetch(archive.checksumsUrl);
+        if (!response.ok) {
+            verbose(`SHA256SUMS fetch returned HTTP ${String(response.status)} for ${archive.checksumsUrl}`);
+            return null;
+        }
+        const body = await response.text();
+        for (const line of body.split('\n')) {
+            const match = /^([0-9a-f]{64})\s+\*?(.+)$/.exec(line.trim());
+            if (match?.[1] && match[2] === archive.pathInChecksums) {
+                return match[1];
+            }
+        }
+        verbose(`SHA256SUMS at ${archive.checksumsUrl} does not list ${archive.pathInChecksums}`);
+        return null;
+    }
+    catch (error) {
+        verbose(`SHA256SUMS fetch failed for ${archive.checksumsUrl}: ${toError(error).message}`);
+        return null;
+    }
+}
 /**
  * Ensures a valid cached archive exists, downloading it if needed.
  * @param archive - Resolved archive descriptor
@@ -117,8 +150,32 @@ async function downloadToCache(archive, cacheDir, onProgress, expectedSha256, on
         promotedTarball = true;
         onCacheProgress?.(`Calculating source archive SHA-256 for ${archive.filename}...`);
         const sha256 = await sha256File(tarballPath);
-        if (expectedSha256 && sha256 !== expectedSha256) {
-            throw new ChecksumMismatchError(archive.product, expectedSha256, sha256, archive.url);
+        if (expectedSha256) {
+            // Operator-pinned digest (firefox.sha256 config): takes precedence
+            // and always fails closed.
+            if (sha256 !== expectedSha256) {
+                throw new ChecksumMismatchError(archive.product, expectedSha256, sha256, archive.url);
+            }
+        }
+        else {
+            // Default integrity check: verify against Mozilla's published
+            // SHA256SUMS. TLS alone is thin trust for the artifact that becomes
+            // the git baseline every patch is built on — a compromised CDN
+            // response would otherwise be trusted with no signal. Mismatch fails
+            // closed (the catch below deletes the artifact); an unfetchable
+            // SHA256SUMS degrades to a loud warning so offline/mirror workflows
+            // keep working (pin firefox.sha256 in fireforge.json to fail closed
+            // even then).
+            onCacheProgress?.(`Verifying archive against published SHA256SUMS...`);
+            const publishedSha256 = await fetchPublishedSha256(archive);
+            if (publishedSha256 === null) {
+                warn(`Could not verify ${archive.filename} against Mozilla's published SHA256SUMS ` +
+                    `(${archive.checksumsUrl} unavailable). The download is trusted on TLS alone — ` +
+                    'set firefox.sha256 in fireforge.json to require checksum verification.');
+            }
+            else if (sha256 !== publishedSha256) {
+                throw new ChecksumMismatchError(archive.product, publishedSha256, sha256, archive.url);
+            }
         }
         onCacheProgress?.(`Writing source archive cache metadata for ${archive.metadataFilename}...`);
         await writeJson(metadataPath, {
@@ -167,4 +224,3 @@ async function removeArchivePartFiles(archive, cacheDir) {
         // Cache dir may not exist yet — that's fine.
     }
 }
-//# sourceMappingURL=firefox-cache.js.map