@hominis/fireforge 0.37.0 → 0.38.0

package/dist/src/commands/test.js

@@ -10,17 +10,17 @@ import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionette
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
-import { checkStaleBuildForTest, findUncoveredRequestPaths, formatStaleBuildWarning, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, outro, spinner, success, verbose, warn } from '../utils/logger.js';
+import { info, intro, outro, spinner, success, verbose } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
 import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
 import { DEFAULT_HARNESS_RETRIES, runShardedTests, runTestsWithRetries, } from './test-run.js';
+import { enforceStaleBuildGate, enforceStaticComponentsGate } from './test-stale-gate.js';
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
     for (const testPath of testPaths) {
@@ -135,9 +135,12 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
             // same files — in any invocation shape — is not refused. A failed
             // write never fails the run. The coverage claim is scoped to the
             // requested test paths, since a file-scoped `test --build` only
-            // guarantees packaging for those manifests.
+            // guarantees packaging for those manifests. The previous baseline is
+            // passed through so a scoped write carries the static-components
+            // anchor forward (a `mach build faster` does not rebake
+            // components.conf into the compiled table).
             try {
-                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, testPackagingCoverage);
+                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, testPackagingCoverage, previousBaseline);
             }
             catch (baselineError) {
                 verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
@@ -150,51 +153,6 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
             : 'Pre-test build failed', 'mach build faster');
     });
 }
-/**
- * Stale-build preflight — when `--build` was NOT requested, detect
- * packageable engine edits since the last successful build and fail
- * UP-FRONT unless the operator explicitly accepts the stale package risk.
- *
- * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
- * regardless of staleness or `--allow-stale-build`: a runtime packaged by
- * a file-scoped `test --build` can lack support fixtures for OTHER
- * manifests even when nothing changed since — dispatching such a run
- * hangs on missing fixtures rather than failing, so the flag (which only
- * accepts stale CONTENT) must not be the trigger. Field incident: a
- * three-file scoped rebuild left `file_tiles_audio.html` unpackaged and a
- * later run over different files timed out twice at 45s waiting on
- * `DOMAudioPlaybackStarted`.
- *
- * Exception: a path-less `test --doctor` stops at the Marionette health
- * check (`runDoctorPreflight` returns 'stop' when no test paths were
- * given) and never dispatches a test, so it needs no packaging coverage —
- * treating it as a full-suite request would refuse a probe that touches
- * no fixtures. The stale-content refusal still applies to it unchanged.
- */
-async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths) {
-    const stale = await checkStaleBuildForTest(projectRoot, engineDir);
-    const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
-    if (!dispatchesNoTests) {
-        const recordedCoverage = stale.baseline?.testPackagingCoverage;
-        const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
-        if (uncovered.length > 0) {
-            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : []));
-        }
-    }
-    const staleMessage = stale.stale
-        ? `${formatStaleBuildWarning(stale)}\n\n` +
-            'Run `fireforge test --build` to refresh the packaged runtime first, or pass ' +
-            '`--allow-stale-build` if you intentionally rebuilt out-of-band and accept the risk.'
-        : undefined;
-    if (staleMessage !== undefined) {
-        if (options.allowStaleBuild === true) {
-            warn(staleMessage);
-        }
-        else {
-            throw new GeneralError(staleMessage);
-        }
-    }
-}
 function logTestSelection(scopes) {
     if (scopes.length > 0) {
         const labels = scopes.map((scope) => scope.isDirectory && scope.testFileCount > 0
@@ -366,8 +324,15 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // Run incremental build if requested
     if (options.build) {
         // A path-less `test --build` runs (and packages for) the full suite;
-        // a scoped invocation only vouches for the requested paths.
+        // a scoped invocation only vouches for the requested paths. A SCOPED
+        // rebuild also cannot regenerate the compiled StaticComponents table,
+        // so it runs the components.conf gate up-front (the path-less shape
+        // refreshes the anchor itself and skips it).
         const coverage = normalizedPaths.length === 0 ? 'full' : normalizedPaths;
+        if (normalizedPaths.length > 0) {
+            const previousBaseline = await readBuildBaseline(projectRoot);
+            await enforceStaticComponentsGate(paths.engine, previousBaseline, options);
+        }
         await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, coverage);
         info('');
     }

package/dist/src/core/build-audit.d.ts

@@ -36,6 +36,18 @@ export interface AuditSummary {
  * @returns True when the path implies packaging.
  */
 export declare function isPackageablePath(sourcePath: string): boolean;
+/**
+ * Decides whether a source path is an XPCOM static-component manifest —
+ * i.e. a file whose registrations are baked into the compiled
+ * StaticComponents table at FULL-build time rather than packaged into
+ * `dist/`. This basename check is the single extension point for that
+ * classification; parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
+ * renamed manifests is out of scope.
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ * @returns True when the path is a `components.conf` manifest.
+ */
+export declare function isXpcomManifestPath(sourcePath: string): boolean;
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns

package/dist/src/core/build-audit.js

@@ -111,6 +111,20 @@ export function isPackageablePath(sourcePath) {
     }
     return false;
 }
+/**
+ * Decides whether a source path is an XPCOM static-component manifest —
+ * i.e. a file whose registrations are baked into the compiled
+ * StaticComponents table at FULL-build time rather than packaged into
+ * `dist/`. This basename check is the single extension point for that
+ * classification; parsing `moz.build` `XPCOM_MANIFESTS` entries to follow
+ * renamed manifests is out of scope.
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ * @returns True when the path is a `components.conf` manifest.
+ */
+export function isXpcomManifestPath(sourcePath) {
+    return basename(sourcePath.replace(/\\/g, '/')) === 'components.conf';
+}
 /*
  * Finds the unique obj-star directory with a dist subtree, or undefined
  * when zero or multiple match. The ambiguous case is already rejected

package/dist/src/core/build-baseline-types.d.ts

@@ -55,8 +55,42 @@ export interface BuildBaseline {
      * The record is project-scoped, which is also per-obj-dir: multi-objdir
      * checkouts are refused up-front (`AmbiguousBuildArtifactsError`), so at
      * most one obj dir exists per project.
+     *
+     * Union/"shared coverage" across successive scoped builds was evaluated
+     * and rejected as unsound — every baseline write refreshes
+     * `packageableFingerprints` for ALL dirty packageable paths, so a union
+     * would whitewash an earlier scope's edited fixtures while
+     * `obj-*`/`_tests/` still holds its stale staging; coverage therefore
+     * REPLACES.
      */
     testPackagingCoverage?: TestPackagingCoverage;
+    /**
+     * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
+     * the last FULL-coverage build plus content fingerprints of the
+     * `components.conf` manifests that were dirty at that moment. Written
+     * fresh only on FULL-coverage baseline writes (`fireforge build`,
+     * `build --ui`, path-less `test --build`); a scoped `test --build`
+     * carries the previous record forward verbatim, because `mach build
+     * faster` does not rebake `components.conf` registrations into the
+     * compiled table. Missing on pre-0.38.0 baselines — the
+     * static-components stale check degrades to "fresh" in that case.
+     */
+    staticComponentsBaseline?: StaticComponentsBaseline;
+}
+/**
+ * State of the engine at the last FULL build, as far as compiled-in XPCOM
+ * component registration is concerned. See
+ * {@link BuildBaseline.staticComponentsBaseline}.
+ */
+export interface StaticComponentsBaseline {
+    /** Engine HEAD SHA at the time of the last full build. */
+    engineHeadSha: string;
+    /**
+     * Hex-encoded SHA-256 per `components.conf` path that was dirty
+     * (modified-against-HEAD or untracked) when the full build ran. Keys are
+     * engine-relative POSIX paths.
+     */
+    fingerprints: Record<string, string>;
 }
 /** Coverage claim of the packaged test runtime. See {@link BuildBaseline.testPackagingCoverage}. */
 export type TestPackagingCoverage = 'full' | string[];

package/dist/src/core/build-baseline.d.ts

@@ -42,5 +42,10 @@ export declare function readBuildBaseline(projectRoot: string): Promise<BuildBas
  * @param testPackagingCoverage - Coverage claim of the packaged test
  *   runtime this build produced (`'full'`, or the scoped request paths of
  *   a `test --build` invocation). Omitted → field left off the marker.
+ * @param previousBaseline - The baseline this write replaces, when the
+ *   caller has it. A scoped (non-`'full'`) write carries its
+ *   `staticComponentsBaseline` forward verbatim — `mach build faster`
+ *   does not rebake `components.conf` registrations, so the last FULL
+ *   build stays the honest anchor for the compiled StaticComponents table.
  */
-export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage): Promise<void>;
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline): Promise<void>;

package/dist/src/core/build-baseline.js

@@ -22,7 +22,7 @@ import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { isPackageablePath } from './build-audit.js';
+import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { getHead, hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
@@ -68,8 +68,13 @@ export async function readBuildBaseline(projectRoot) {
  * @param testPackagingCoverage - Coverage claim of the packaged test
  *   runtime this build produced (`'full'`, or the scoped request paths of
  *   a `test --build` invocation). Omitted → field left off the marker.
+ * @param previousBaseline - The baseline this write replaces, when the
+ *   caller has it. A scoped (non-`'full'`) write carries its
+ *   `staticComponentsBaseline` forward verbatim — `mach build faster`
+ *   does not rebake `components.conf` registrations, so the last FULL
+ *   build stays the honest anchor for the compiled StaticComponents table.
  */
-export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage) {
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline) {
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -84,12 +89,20 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
         }
     }
     const packageableFingerprints = await collectPackageableFingerprints(engineDir);
+    // A full-coverage write (and the legacy no-claim `fireforge build` shape)
+    // just recompiled the StaticComponents table, so it anchors the table to
+    // the current engine state. A scoped write did not — carry the previous
+    // anchor forward verbatim.
+    const staticComponentsBaseline = testPackagingCoverage === undefined || testPackagingCoverage === 'full'
+        ? await collectStaticComponentsBaseline(engineDir, engineHeadSha)
+        : previousBaseline?.staticComponentsBaseline;
     const baseline = {
         engineHeadSha,
         builtAt: new Date().toISOString(),
         binaryName,
         ...(packageableFingerprints !== undefined ? { packageableFingerprints } : {}),
         ...(testPackagingCoverage !== undefined ? { testPackagingCoverage } : {}),
+        ...(staticComponentsBaseline !== undefined ? { staticComponentsBaseline } : {}),
     };
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }
@@ -107,6 +120,33 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
  * back to the pre-0.16.0 "path-only" behavior on the next test run.
  */
 async function collectPackageableFingerprints(engineDir) {
+    return collectDirtyFingerprints(engineDir, isPackageablePath, 'packageable fingerprint');
+}
+/**
+ * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
+ * this (full) build plus content fingerprints of the `components.conf`
+ * manifests dirty right now — the same dirty-path probe family as
+ * {@link collectPackageableFingerprints}, filtered to XPCOM manifests.
+ * Returns `undefined` on probe failure so a broken probe omits the field
+ * (the static-components stale check then degrades to "fresh") rather than
+ * anchoring to a garbage record.
+ */
+async function collectStaticComponentsBaseline(engineDir, engineHeadSha) {
+    const fingerprints = await collectDirtyFingerprints(engineDir, isXpcomManifestPath, 'static-components fingerprint');
+    if (fingerprints === undefined) {
+        return undefined;
+    }
+    return { engineHeadSha, fingerprints };
+}
+/**
+ * Shared dirty-path fingerprint probe backing
+ * {@link collectPackageableFingerprints} and
+ * {@link collectStaticComponentsBaseline}: enumerates engine workdir
+ * modifications (tracked and untracked), keeps the paths `includePath`
+ * accepts, and hashes each. Returns `undefined` on any git failure so a
+ * broken probe never corrupts the on-disk baseline with `{}`.
+ */
+async function collectDirtyFingerprints(engineDir, includePath, contextLabel) {
     try {
         const dirtyPaths = new Set();
         if (await hasChanges(engineDir)) {
@@ -120,12 +160,12 @@ async function collectPackageableFingerprints(engineDir) {
                 dirtyPaths.add(untracked);
             }
         }
-        const packageable = [...dirtyPaths].filter(isPackageablePath);
-        if (packageable.length === 0) {
+        const included = [...dirtyPaths].filter(includePath);
+        if (included.length === 0) {
             return {};
         }
         const fingerprints = {};
-        for (const relPath of packageable) {
+        for (const relPath of included) {
             try {
                 const buffer = await readFile(join(engineDir, relPath));
                 fingerprints[relPath] = createHash('sha256').update(buffer).digest('hex');
@@ -134,13 +174,13 @@ async function collectPackageableFingerprints(engineDir) {
                 // A file that disappeared between status probe and hash is
                 // expected in concurrent scenarios; skip it without failing the
                 // whole baseline write.
-                verbose(`Build baseline: skipping fingerprint for ${relPath} — ${toError(fileError).message}`);
+                verbose(`Build baseline: skipping ${contextLabel} for ${relPath} — ${toError(fileError).message}`);
             }
         }
         return fingerprints;
     }
     catch (error) {
-        verbose(`Build baseline: packageable fingerprint probe failed — ${toError(error).message}`);
+        verbose(`Build baseline: ${contextLabel} probe failed — ${toError(error).message}`);
         return undefined;
     }
 }

package/dist/src/core/config-paths.d.ts

@@ -11,7 +11,7 @@ export declare const STATE_FILENAME = "state.json";
 /** Supported top-level fireforge.json keys backed by the current schema. */
 export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "test", "externalToolchains", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

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

@@ -45,6 +45,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'firefox.version',
     'firefox.product',
     'firefox.sha256',
+    'firefox.candidate',
     'build',
     'build.jobs',
     'test',

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

@@ -6,7 +6,7 @@ import { ConfigError } from '../errors/config.js';
 import { verbose } from '../utils/logger.js';
 import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
-import { isValidAppId, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
+import { isValidAppId, isValidFirefoxCandidate, 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';
@@ -81,10 +81,15 @@ function parseFirefoxBlock(rec) {
     if (firefoxSha256 !== undefined && !/^[a-f0-9]{64}$/i.test(firefoxSha256)) {
         throw new ConfigError('Config field "firefox.sha256" must be a 64-character SHA-256 hex digest');
     }
+    const firefoxCandidate = optionalConfigString(firefoxRec, 'candidate', 'firefox.candidate');
+    if (firefoxCandidate !== undefined && !isValidFirefoxCandidate(firefoxCandidate)) {
+        throw new ConfigError('Config field "firefox.candidate" must look like "buildN" (e.g. "build2")');
+    }
     return {
         version: firefoxVersion,
         product: firefoxProduct,
         ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
+        ...(firefoxCandidate !== undefined ? { candidate: firefoxCandidate } : {}),
     };
 }
 /** Parses the optional `build` block (currently just `build.jobs`). */

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

@@ -1,7 +1,16 @@
+export interface EngineSessionLockOptions {
+    /**
+     * Wait up to this many seconds for the engine session lock instead of the
+     * legacy ~1 s fail-fast. Enables exponential poll backoff (100 ms → 2 s)
+     * and a holder-identified progress line roughly every 5 s. `undefined`
+     * preserves the historical fail-fast behavior exactly.
+     */
+    waitLockSeconds?: number | undefined;
+}
 /**
  *
  */
-export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>): Promise<T>;
+export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>, options?: EngineSessionLockOptions): Promise<T>;
 /**
  *
  */

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

@@ -1,19 +1,45 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
 import { withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
+/**
+ * Formats the periodic operator-facing waiting line printed while `--wait-lock`
+ * polls a contended engine session lock. The holder identification comes from
+ * the lock's owner-metadata lines (`command=…`, `started=…`); an unreadable
+ * owner file degrades to the anonymous form.
+ */
+function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
+    const progress = `${String(Math.round(waitedMs / 1000))}s of up to ${String(Math.round(timeoutMs / 1000))}s`;
+    if (holder === undefined) {
+        return `Waiting for the FireForge engine lock — ${progress}.`;
+    }
+    const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
+    return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.`;
+}
 /**
  *
  */
-export async function withEngineSessionLock(projectRoot, command, operation) {
+export async function withEngineSessionLock(projectRoot, command, operation, options = {}) {
     if (process.env['FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST'] !== '1' &&
         (process.env['NODE_ENV'] === 'test' || process.env['VITEST'] !== undefined)) {
         return operation();
     }
+    const { waitLockSeconds } = options;
     return withFileLock(join(projectRoot, ENGINE_SESSION_LOCK_PATH), operation, {
-        timeoutMs: 1000,
+        timeoutMs: waitLockSeconds !== undefined ? waitLockSeconds * 1000 : 1000,
+        ...(waitLockSeconds !== undefined
+            ? {
+                pollMs: 100,
+                pollMaxMs: 2000,
+                waitProgressMs: 5000,
+                onWaitProgress: ({ waitedMs, timeoutMs, holder }) => {
+                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder));
+                },
+            }
+            : {}),
         ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
         onTimeoutMessage: `Another FireForge engine-mutating command is already running. ` +
             `Wait for it to finish, then retry \`${command}\`.`,

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

@@ -1,6 +1,23 @@
+/**
+ * Snapshot of the current lock holder handed to {@link FileLockOptions.onWaitProgress}.
+ * `metadata` carries the pid file's human-diagnostic lines (line 3 onward,
+ * e.g. `command=build`, `started=…`) written via
+ * {@link FileLockOptions.ownerMetadata}.
+ */
+export interface LockHolder {
+    pid: number;
+    alive: boolean;
+    metadata: string[];
+}
 export interface FileLockOptions {
     timeoutMs?: number;
     pollMs?: number;
+    /**
+     * When set, the poll interval doubles after every contended poll (starting
+     * from `pollMs`) up to this cap. When absent, polling stays at the fixed
+     * `pollMs` interval — zero behavior change for existing callers.
+     */
+    pollMaxMs?: number;
     staleMs?: number;
     /**
      * Interval between stale-lock probes while waiting (defaults to
@@ -8,6 +25,22 @@ export interface FileLockOptions {
      * the mid-wait reaping path without multi-second sleeps.
      */
     staleReprobeMs?: number;
+    /**
+     * Interval between {@link onWaitProgress} callbacks while the lock is
+     * contended. Progress reporting is off unless both this and
+     * `onWaitProgress` are set.
+     */
+    waitProgressMs?: number;
+    /**
+     * Invoked roughly every `waitProgressMs` while waiting for a contended
+     * lock. `holder` is `undefined` when the owner PID file is missing or
+     * unreadable.
+     */
+    onWaitProgress?: (progress: {
+        waitedMs: number;
+        timeoutMs: number;
+        holder: LockHolder | undefined;
+    }) => void;
     onTimeoutMessage?: string;
     onStaleLockMessage?: (ageMs: number) => string | undefined;
     /** Extra owner-file lines for human diagnostics; ignored by lock mechanics. */

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

@@ -50,7 +50,8 @@ function isProcessAlive(pid) {
     }
 }
 /**
- * Reads the owner PID (line 1) and acquisition token (line 2) from a lock
+ * 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).
@@ -62,14 +63,15 @@ function isProcessAlive(pid) {
 async function readLockOwner(lockPath) {
     try {
         const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
-        const [pidLine, tokenLine] = pidContent.split('\n');
+        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 };
+                return { present: true, pid, token, metadata };
             }
-            return { present: true, pid };
+            return { present: true, pid, metadata };
         }
     }
     catch {
@@ -77,6 +79,18 @@ async function readLockOwner(lockPath) {
     }
     return { present: false };
 }
+/**
+ * Reads the contended lock's owner and reports wait progress to the caller's
+ * `onWaitProgress` callback. Failure to read the owner degrades to
+ * `holder: undefined` — progress reporting must never break the wait loop.
+ */
+async function reportWaitProgress(lockPath, waitedMs, timeoutMs, onWaitProgress) {
+    const owner = await readLockOwner(lockPath);
+    const holder = owner.present
+        ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
+        : undefined;
+    onWaitProgress({ waitedMs, timeoutMs, holder });
+}
 /**
  * Reaps a lock directory believed to be stale, safely against concurrent
  * reapers and a concurrent legitimate re-acquisition.
@@ -216,8 +230,11 @@ export async function withFileLock(lockPath, operation, options = {}) {
     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;
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
     let lastStaleProbeAt;
+    let currentPollMs = pollMs;
+    let lastProgressAt = startedAt;
     await ensureDir(dirname(lockPath));
     for (;;) {
         try {
@@ -246,7 +263,16 @@ export async function withFileLock(lockPath, operation, options = {}) {
                     : ' 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);
+            if (options.onWaitProgress !== undefined &&
+                options.waitProgressMs !== undefined &&
+                Date.now() - lastProgressAt >= options.waitProgressMs) {
+                lastProgressAt = Date.now();
+                await reportWaitProgress(lockPath, Date.now() - startedAt, timeoutMs, options.onWaitProgress);
+            }
+            await sleep(currentPollMs);
+            if (options.pollMaxMs !== undefined) {
+                currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
+            }
         }
     }
     // Stamp ownership (PID + per-acquisition token) into the lock directory so

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

@@ -39,6 +39,7 @@ export declare function validateArchiveMetadata(data: unknown): ArchiveMetadata;
  * Resolves archive identity for URL generation and cache storage.
  * @param version - Requested Firefox version
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Resolved archive descriptor
  */
-export declare function resolveArchive(version: string, product?: FirefoxProduct): ResolvedArchive;
+export declare function resolveArchive(version: string, product?: FirefoxProduct, candidate?: string): ResolvedArchive;

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

@@ -4,15 +4,26 @@
  */
 import { ConfigError } from '../errors/config.js';
 import { parseObject } from '../utils/parse.js';
-import { isValidFirefoxProduct } from '../utils/validation.js';
+import { isValidFirefoxCandidate, isValidFirefoxProduct } from '../utils/validation.js';
 /**
  * Base URLs for Firefox source archives on archive.mozilla.org.
  */
-const FIREFOX_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox/releases';
-const DEVEDITION_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/devedition/releases';
+const FIREFOX_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox';
+const DEVEDITION_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/devedition';
 function getArchiveBaseUrl(product) {
     return product === 'firefox-devedition' ? DEVEDITION_ARCHIVE_BASE_URL : FIREFOX_ARCHIVE_BASE_URL;
 }
+/**
+ * Directory holding the release's artifacts: `releases/<version>/` for
+ * final releases, `candidates/<version>-candidates/<buildN>/` when a
+ * release-candidate build is requested for pre-release verification.
+ */
+function getArchiveDirUrl(product, archiveVersion, candidate) {
+    const base = getArchiveBaseUrl(product);
+    return candidate === undefined
+        ? `${base}/releases/${archiveVersion}`
+        : `${base}/candidates/${archiveVersion}-candidates/${candidate}`;
+}
 /**
  * Validates raw JSON data as ArchiveMetadata.
  * @param data - Unknown data to validate
@@ -41,13 +52,20 @@ export function validateArchiveMetadata(data) {
  * Resolves archive identity for URL generation and cache storage.
  * @param version - Requested Firefox version
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Resolved archive descriptor
  */
-export function resolveArchive(version, product = 'firefox') {
+export function resolveArchive(version, product = 'firefox', candidate) {
     // Reject versions containing path traversal characters
     if (version.includes('/') || version.includes('..') || version.includes('\\')) {
         throw new ConfigError(`Invalid Firefox version "${version}": contains disallowed characters`, 'firefox.version');
     }
+    // Defense-in-depth: config validation enforces this shape already, but a
+    // caller-supplied candidate becomes both a URL path segment and part of
+    // the cache filename, so re-validate here like the version check above.
+    if (candidate !== undefined && !isValidFirefoxCandidate(candidate)) {
+        throw new ConfigError(`Invalid Firefox candidate "${candidate}": must look like "buildN" (e.g. "build2")`, 'firefox.candidate');
+    }
     // ESR status is determined solely by the product field. Config validation
     // ensures product and version are consistent, so we never need to infer
     // ESR from the version string independently.
@@ -55,18 +73,24 @@ export function resolveArchive(version, product = 'firefox') {
     const isEsr = product === 'firefox-esr';
     const archiveVersion = isEsr ? `${cleanVersion}esr` : cleanVersion;
     const safeProduct = product.replace(/[^a-z0-9-]/gi, '-');
+    const dirUrl = getArchiveDirUrl(product, archiveVersion, candidate);
+    // Candidate artifacts get a `-<candidate>` filename suffix so a build2
+    // archive can never collide with the final release artifact (same
+    // archiveVersion, potentially different bytes) in .fireforge/cache.
+    const candidateSuffix = candidate === undefined ? '' : `-${candidate}`;
+    const filename = `firefox-${safeProduct}-${archiveVersion}${candidateSuffix}.source.tar.xz`;
     return {
         requestedVersion: version,
         product,
         archiveVersion,
-        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`,
+        url: `${dirUrl}/source/firefox-${archiveVersion}.source.tar.xz`,
+        filename,
+        metadataFilename: `${filename}.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`,
+        checksumsUrl: `${dirUrl}/SHA256SUMS`,
         pathInChecksums: `source/firefox-${archiveVersion}.source.tar.xz`,
     };
 }