@hominis/fireforge 0.36.0 → 0.38.0

package/dist/src/commands/re-export-files.js

@@ -2,6 +2,7 @@
 import { join } from 'node:path';
 import { getProjectPaths } from '../core/config.js';
 import { appendHistory, confirmDestructive } from '../core/destructive.js';
+import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { computeProjectedLintRegressions } from '../core/lint-projection.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
@@ -151,6 +152,9 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
         throw new InvalidArgumentError('reExportFilesInPlace called with no --files.', '--files');
     }
     const requested = [...new Set(filesOption)].sort();
+    // Stale-furnace-source gate (0.37.0 item 4): same refusal as the generic
+    // re-export path — the projected diff would capture stale deployed copies.
+    await enforceFreshFurnaceSources(paths.root, requested, options.allowStaleFurnace === true, 're-export');
     const removed = target.filesAffected.filter((f) => !requested.includes(f));
     const added = requested.filter((f) => !target.filesAffected.includes(f));
     const retained = target.filesAffected.filter((f) => requested.includes(f));

package/dist/src/commands/re-export-scan.d.ts

@@ -28,6 +28,23 @@ export declare function confirmBroadScanAdditions(args: {
     yes: boolean;
     isInteractive: boolean;
 }): Promise<boolean>;
+/**
+ * Refuses scan adoptions whose candidate files import modules created by
+ * LATER patches. Modeled on the `re-export --files` cross-patch
+ * projection: the candidates' diffs are projected into the adopting
+ * patch's queue entry, the queue lint runs baseline vs projection, and
+ * only forward-import regressions attributable to the candidates block.
+ * Staged-dependency declarations and inline lint-ignore markers are
+ * honored automatically because the real lint rule evaluates them.
+ * Covers broad `--scan`, `--scan-file`, and the `--scan-files` bulk flow
+ * (all adopt through the same scan result), including dry-run.
+ */
+export declare function assertScanAdoptionsHaveNoForwardImports(args: {
+    patchesDir: string;
+    engineDir: string;
+    patchFilename: string;
+    added: readonly string[];
+}): Promise<void>;
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export declare function assertScanFileAdditionsHaveDiffHunks(args: {
     diffContent: string;

package/dist/src/commands/re-export-scan.js

@@ -1,9 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
 import { confirm } from '@clack/prompts';
+import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
+import { computeProjectedLintRegressions } from '../core/lint-projection.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
 import { getClaimedFiles } from '../core/patch-manifest.js';
+import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
@@ -132,6 +136,53 @@ function scanAdditionsNeedConfirmation(added) {
         return true;
     return new Set(added.map((f) => dirname(f))).size >= SCAN_DIR_COUNT_THRESHOLD;
 }
+/**
+ * Refuses scan adoptions whose candidate files import modules created by
+ * LATER patches. Modeled on the `re-export --files` cross-patch
+ * projection: the candidates' diffs are projected into the adopting
+ * patch's queue entry, the queue lint runs baseline vs projection, and
+ * only forward-import regressions attributable to the candidates block.
+ * Staged-dependency declarations and inline lint-ignore markers are
+ * honored automatically because the real lint rule evaluates them.
+ * Covers broad `--scan`, `--scan-file`, and the `--scan-files` bulk flow
+ * (all adopt through the same scan result), including dry-run.
+ */
+export async function assertScanAdoptionsHaveNoForwardImports(args) {
+    const { patchesDir, engineDir, patchFilename, added } = args;
+    if (added.length === 0)
+        return;
+    const candidateDiff = await getDiffForFilesAgainstHead(engineDir, [...added]);
+    if (!candidateDiff.trim())
+        return;
+    const candidateNewFiles = new Map();
+    for (const path of detectNewFilesInDiff(candidateDiff)) {
+        candidateNewFiles.set(path, extractNewFileContentFromDiff(candidateDiff, path));
+    }
+    const candidateAdditions = buildModifiedFileAdditionsFromDiff(candidateDiff);
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const projectedEntries = baseCtx.entries.map((entry) => {
+        if (entry.filename !== patchFilename)
+            return entry;
+        return {
+            ...entry,
+            diff: `${entry.diff}\n${candidateDiff}`,
+            newFiles: new Map([...entry.newFiles, ...candidateNewFiles]),
+            modifiedFileAdditions: new Map([...entry.modifiedFileAdditions, ...candidateAdditions]),
+        };
+    });
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const addedSet = new Set(added);
+    const offending = computeProjectedLintRegressions(baselineIssues, projectedIssues).filter((issue) => issue.check === 'forward-import' && addedSet.has(issue.file));
+    if (offending.length === 0)
+        return;
+    const details = offending.map((issue) => `  - ${issue.file}: ${issue.message}`).join('\n');
+    throw new GeneralError(`Refusing to adopt ${offending.length} scanned file${offending.length === 1 ? '' : 's'} into ${patchFilename} ` +
+        `because they import modules created by later patches:\n${details}\n` +
+        'Export those files as their own later patch ("fireforge export --order <n>" / ' +
+        '"fireforge patch split --order <n>") or declare the intentional dependency with ' +
+        '"fireforge patch staged-dependency --add" before re-running the scan.');
+}
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export function assertScanFileAdditionsHaveDiffHunks(args) {
     const { diffContent, patchFilename, previousFilesAffected, scanFiles } = args;

package/dist/src/commands/re-export.js

@@ -5,6 +5,7 @@ import { multiselect } from '@clack/prompts';
 import { Command, Option } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
@@ -17,12 +18,12 @@ import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
 import { loadScanFilesAssignments, withDryRunReExportLock } from './re-export-bulk-scan.js';
 import { reExportFilesInPlace } from './re-export-files.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
-import { assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
+import { assertScanAdoptionsHaveNoForwardImports, assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
 async function findMissingFiles(engineDir, files) {
     const missingFiles = [];
     for (const file of files) {
@@ -86,6 +87,17 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
             isDryRun,
             ...(options.scanFiles !== undefined ? { scanFiles: options.scanFiles } : {}),
         });
+        // Forward-import gate at adoption time (runs in dry-run too): refuse
+        // to adopt unmanaged files that import modules created by LATER
+        // patches — the after-the-fact lint failure this leaves behind is the
+        // field-reported footgun. Applies to broad --scan, --scan-file, and
+        // the --scan-files bulk assignments alike.
+        await assertScanAdoptionsHaveNoForwardImports({
+            patchesDir: paths.patches,
+            engineDir: paths.engine,
+            patchFilename: patch.filename,
+            added: scanResult.added,
+        });
         if (options.scanFiles === undefined) {
             const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
             const proceed = await confirmBroadScanAdditions({
@@ -129,6 +141,12 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         for (const f of removed)
             info(`  - ${f}`);
     }
+    // Stale-furnace-source gate (0.37.0 item 4): re-export captures deployed
+    // engine copies, so a component source edited after the last furnace
+    // apply would land in the patch as its OLD deployed content. Refuse (or
+    // warn under --allow-stale-furnace) before diffing. Runs in dry-run too
+    // so the failure surfaces early.
+    await enforceFreshFurnaceSources(paths.root, currentFilesAffected, options.allowStaleFurnace === true, 're-export');
     const missingFiles = await findMissingFiles(paths.engine, currentFilesAffected);
     if (missingFiles.length === currentFilesAffected.length) {
         warn(`Skipped ${patch.filename}: all affected files missing`);
@@ -400,7 +418,7 @@ export async function reExportCommand(projectRoot, patches, options) {
 }
 /** Registers the re-export command on the CLI program. */
 export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const reExport = program
         .command('re-export [patches...]')
         .description('Refresh existing patch bodies (and filesAffected with --scan) from the current engine ' +
         'state. Does NOT change sourceVersion/sourceProduct by default — use --stamp or run ' +
@@ -415,13 +433,14 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .filter((v) => v.length > 0))
         .option('--dry-run', 'Show what would change without writing')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
+        .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
         .option('--allow-shrink', 'Allow --files to remove paths currently owned by the patch. Required before --yes can bypass the shrink confirmation.')
         .option('-y, --yes', 'Skip confirmation prompts (required for non-TTY destructive writes)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
         .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceVersion/sourceProduct in patches.json to firefox.version/firefox.product from fireforge.json. No effect on a partial run.")
         .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
-        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], [])
-        .action(withErrorHandling(async (patches, options) => {
+        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], []);
+    addWaitLockOption(reExport).action(withErrorHandling(async (patches, options) => {
         const { tier, lintIgnore, scanFile, scanFiles, ...rest } = options;
         const projectRoot = getProjectRoot();
         await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, {
@@ -430,6 +449,6 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
             ...(scanFiles !== undefined ? { scanFilesManifest: scanFiles } : {}),
             ...(tier !== undefined ? { tier: tier } : {}),
             ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
-        }));
+        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

package/dist/src/commands/source.js

@@ -4,7 +4,7 @@ import { configExists, loadRawConfigDocument, validateConfig, withConfigFileLock
 import { resolveArchive } from '../core/firefox-archive.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { info, intro, outro, success } from '../utils/logger.js';
-import { isValidFirefoxProduct } from '../utils/validation.js';
+import { isValidFirefoxCandidate, isValidFirefoxProduct } from '../utils/validation.js';
 const SOURCE_PRODUCTS = [
     'firefox',
     'firefox-esr',
@@ -27,6 +27,12 @@ function parseSourceProduct(product) {
     }
     throw new InvalidArgumentError(`--product must be one of: ${SOURCE_PRODUCTS.join(', ')}`, '--product');
 }
+function parseSourceCandidate(candidate) {
+    if (isValidFirefoxCandidate(candidate)) {
+        return candidate;
+    }
+    throw new InvalidArgumentError(`--candidate must look like "buildN" (e.g. "build2"), got "${candidate}"`, '--candidate');
+}
 /**
  * Atomically updates the Firefox source tuple in fireforge.json.
  */
@@ -38,6 +44,9 @@ export async function sourceSetCommand(projectRoot, options) {
     if (options.sha256 !== undefined && options.clearSha256 === true) {
         throw new InvalidArgumentError('--sha256 cannot be combined with --clear-sha256', '--sha256');
     }
+    if (options.candidate !== undefined && options.clearCandidate === true) {
+        throw new InvalidArgumentError('--candidate cannot be combined with --clear-candidate', '--candidate');
+    }
     const written = await withConfigFileLock(projectRoot, async () => {
         const raw = await loadRawConfigDocument(projectRoot);
         const updated = cloneRawConfig(raw);
@@ -50,6 +59,12 @@ export async function sourceSetCommand(projectRoot, options) {
         else if (options.sha256 !== undefined) {
             firefox['sha256'] = options.sha256;
         }
+        if (options.clearCandidate === true) {
+            delete firefox['candidate'];
+        }
+        else if (options.candidate !== undefined) {
+            firefox['candidate'] = options.candidate;
+        }
         updated['firefox'] = firefox;
         const validated = validateConfig(updated);
         if (validated.firefox.sha256 !== undefined) {
@@ -58,7 +73,7 @@ export async function sourceSetCommand(projectRoot, options) {
         await writeConfigDocument(projectRoot, updated);
         return validated.firefox;
     });
-    const archive = resolveArchive(written.version, written.product);
+    const archive = resolveArchive(written.version, written.product, written.candidate);
     success(`Set firefox.version = ${written.version}`);
     success(`Set firefox.product = ${written.product}`);
     success(`Resolved source URL: ${archive.url}`);
@@ -68,6 +83,12 @@ export async function sourceSetCommand(projectRoot, options) {
     else if (options.clearSha256 === true) {
         info('Cleared firefox.sha256');
     }
+    if (written.candidate !== undefined) {
+        success(`Set firefox.candidate = ${written.candidate}`);
+    }
+    else if (options.clearCandidate === true) {
+        info('Cleared firefox.candidate');
+    }
     outro('');
 }
 /** Registers the source command on the CLI program. */
@@ -82,13 +103,17 @@ export function registerSource(program, { getProjectRoot, withErrorHandling }) {
         .makeOptionMandatory())
         .option('--sha256 <hash>', 'Pinned SHA-256 for the resolved source archive')
         .option('--clear-sha256', 'Clear any existing pinned SHA-256')
+        .option('--candidate <buildN>', 'Release-candidate build directory (e.g. "build2")', parseSourceCandidate)
+        .option('--clear-candidate', 'Clear any existing release-candidate build directory')
         .action(withErrorHandling(async (options) => {
-        const { product, version, sha256, clearSha256 } = options;
+        const { product, version, sha256, clearSha256, candidate, clearCandidate } = options;
         await sourceSetCommand(getProjectRoot(), {
             version,
             product: parseSourceProduct(product),
             ...(sha256 !== undefined ? { sha256 } : {}),
             ...(clearSha256 !== undefined ? { clearSha256 } : {}),
+            ...(candidate !== undefined ? { candidate } : {}),
+            ...(clearCandidate !== undefined ? { clearCandidate } : {}),
         });
     }));
 }

package/dist/src/commands/test-diagnose.js

@@ -209,6 +209,10 @@ export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, p
     }
     if (outcome.verdict.realFailureLine !== undefined) {
         info(`First real test failure: ${outcome.verdict.realFailureLine}`);
+        const blocks = formatFailureBlocks(outcome.verdict.realFailureBlocks);
+        if (blocks !== undefined) {
+            info(blocks);
+        }
         if (outcome.verdict.secondaryHarnessSignature !== undefined) {
             info(`Secondary harness noise also present: ${outcome.verdict.secondaryHarnessSignature.reason}; ` +
                 outcome.verdict.secondaryHarnessSignature.line);
@@ -233,6 +237,21 @@ export function diagnoseShardOutcome(outcome, path, binaryName, postRebuildConte
         return undefined;
     }
     catch (error) {
-        return error instanceof Error ? error.message : String(error);
+        const diagnosis = error instanceof Error ? error.message : String(error);
+        const blocks = formatFailureBlocks(outcome.verdict.realFailureBlocks);
+        return blocks !== undefined ? `${blocks}\n${diagnosis}` : diagnosis;
     }
 }
+/**
+ * Renders the verdict's TEST-UNEXPECTED blocks (verbatim failing lines +
+ * their assertion/diff context) for the failure summary. Returns undefined
+ * when the verdict carries none, so callers can skip the section entirely.
+ */
+function formatFailureBlocks(blocks) {
+    if (blocks === undefined || blocks.length === 0)
+        return undefined;
+    // The collector appends a `…(+N more …)` note when it truncated; that
+    // note is not a failure block, so it does not count toward the header.
+    const shown = blocks.filter((block) => !block.startsWith('…(')).length;
+    return `Unexpected test failures (first ${shown}):\n${blocks.join('\n\n')}`;
+}

package/dist/src/commands/test-register.js

@@ -2,18 +2,19 @@
 import { Command } from 'commander';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { GeneralError } from '../errors/base.js';
-import { commanderArgParser, pickDefined } from '../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
 import { testCommand } from './test.js';
 import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const test = program
         .command('test [paths...]')
         .description('Run tests via mach test')
         .option('--headless', 'Run tests in headless mode')
         .option('--build', 'Run incremental UI build before testing')
         .option('--auto', 'Forward mach test --auto. Valid only when no explicit paths are provided.')
         .option('--allow-stale-build', 'Allow tests to run even when packageable engine files changed since the last successful FireForge build')
+        .option('--allow-stale-components', 'Run tests despite components.conf changes that only a full "fireforge build" compiles in (the packaged child process will resolve the OLD StaticComponents table)')
         .option('--kill-stale-marionette', 'Terminate a recognized stale browser process holding the Marionette port before running tests')
         .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
@@ -56,9 +57,9 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         'runs (one browser instance per argument) by default, which does',
         'not exercise cross-argument state; --no-shard restores the',
         'combined single-instance invocation.',
-    ].join('\n'))
-        .action(withErrorHandling(async (paths, options) => {
+    ].join('\n'));
+    addWaitLockOption(test).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)));
+        await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

package/dist/src/commands/test-stale-gate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pre-dispatch gates for `fireforge test` that stand between the request
+ * and a run against a stale or under-packaged runtime: the packaging
+ * coverage refusal, the stale-content refusal, and the compiled
+ * StaticComponents refusal. Split out of `test.ts` so the command module
+ * stays wiring; the probes and refusal copy live in
+ * `src/core/test-stale-check.ts`.
+ */
+import type { BuildBaseline } from '../core/build-baseline-types.js';
+import type { TestOptions } from '../types/commands/index.js';
+/**
+ * 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.
+ */
+export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[]): Promise<void>;
+/**
+ * Compiled-StaticComponents gate — refuses runs whose child process would
+ * resolve a stale compiled component table. `components.conf` entries bake
+ * into compiled code that only a FULL build regenerates; a scoped
+ * `test --build` repackages the file but the failure surfaces as
+ * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
+ * (after the coverage refusal) AND to scoped `test --build` runs (before
+ * the pre-test build — that build cannot fix the table). A path-less
+ * `test --build` is exempt: its full build refreshes the anchor itself.
+ * `--allow-stale-components` downgrades the refusal to a warning.
+ */
+export declare function enforceStaticComponentsGate(engineDir: string, baseline: BuildBaseline | undefined, options: TestOptions): Promise<void>;

package/dist/src/commands/test-stale-gate.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Pre-dispatch gates for `fireforge test` that stand between the request
+ * and a run against a stale or under-packaged runtime: the packaging
+ * coverage refusal, the stale-content refusal, and the compiled
+ * StaticComponents refusal. Split out of `test.ts` so the command module
+ * stays wiring; the probes and refusal copy live in
+ * `src/core/test-stale-check.ts`.
+ */
+import { checkStaleBuildForTest, checkStaticComponentsStale, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
+import { GeneralError } from '../errors/base.js';
+import { warn } from '../utils/logger.js';
+/**
+ * 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.
+ */
+export 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 : []));
+        }
+    }
+    await enforceStaticComponentsGate(engineDir, stale.baseline, options);
+    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);
+        }
+    }
+}
+/**
+ * Compiled-StaticComponents gate — refuses runs whose child process would
+ * resolve a stale compiled component table. `components.conf` entries bake
+ * into compiled code that only a FULL build regenerates; a scoped
+ * `test --build` repackages the file but the failure surfaces as
+ * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
+ * (after the coverage refusal) AND to scoped `test --build` runs (before
+ * the pre-test build — that build cannot fix the table). A path-less
+ * `test --build` is exempt: its full build refreshes the anchor itself.
+ * `--allow-stale-components` downgrades the refusal to a warning.
+ */
+export async function enforceStaticComponentsGate(engineDir, baseline, options) {
+    const result = await checkStaticComponentsStale(engineDir, baseline);
+    if (!result.stale) {
+        return;
+    }
+    const message = formatStaticComponentsRefusal(result.changedManifests);
+    if (options.allowStaleComponents === true) {
+        warn(message);
+        return;
+    }
+    throw new GeneralError(message);
+}

package/dist/src/commands/test.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, resolve } from 'node:path';
-import { readBuildBaseline } from '../core/build-baseline.js';
+import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
@@ -10,16 +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, formatStaleBuildWarning } 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, 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) {
@@ -103,7 +104,7 @@ async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
     }
     return bundleCheck.expectedPath;
 }
-async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries) {
+async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage) {
     await withBuildLock(projectRoot, async () => {
         // Pass the previous baseline exactly like `fireforge build` does, so
         // auto-configure runs under the same conditions on both paths. The
@@ -128,6 +129,22 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
         });
         if (result.exitCode === 0) {
             s.stop('Build complete');
+            // Same record, same failure tolerance as `fireforge build` /
+            // `build --ui` (build.ts): a green pre-test build refreshes the
+            // stale-build baseline so a later plain `fireforge test` over the
+            // 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. 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, previousBaseline);
+            }
+            catch (baselineError) {
+                verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
+            }
             return;
         }
         s.error('Pre-test build failed');
@@ -297,28 +314,30 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // during spawn (exit code 1, signal none). stderr tail: (empty)`.
     const launchablePath = await resolveLaunchablePathForTests(paths.engine, projectConfig.binaryName, buildCheck.objDir);
     const harnessRetries = options.harnessRetries ?? DEFAULT_HARNESS_RETRIES;
+    // Normalized engine-relative request paths, hoisted above the build/stale
+    // gate: the pre-test build records them as the packaging-coverage claim,
+    // and the --allow-stale-build path checks the request against the
+    // recorded coverage. (Existence is still asserted later, after the gate —
+    // stale/coverage refusals keep precedence over missing-path errors.)
+    const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
+    const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
     // Run incremental build if requested
     if (options.build) {
-        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries);
+        // A path-less `test --build` runs (and packages for) the full suite;
+        // 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('');
     }
     else {
-        // Stale-build preflight — when --build was NOT requested, detect
-        // packageable engine edits since the last successful `fireforge build`
-        // and fail UP-FRONT unless the operator explicitly accepts the stale
-        // package risk.
-        const stale = await checkStaleBuildForTest(projectRoot, paths.engine);
-        if (stale.stale) {
-            const message = `${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.';
-            if (options.allowStaleBuild === true) {
-                warn(message);
-            }
-            else {
-                throw new GeneralError(message);
-            }
-        }
+        await enforceStaleBuildGate(projectRoot, paths.engine, options, normalizedPaths);
     }
     // Resolve the effective Marionette port. Operator precedence:
     //   1. `--marionette-port` (first-class option, parsed at the CLI layer)
@@ -355,8 +374,6 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         if (doctorOutcome === 'stop')
             return;
     }
-    const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
-    const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
     await assertTestPathsExist(paths.engine, normalizedPaths);
     const classification = await classifyTestHarnesses(paths.engine, normalizedPaths);
     if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {

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