@hominis/fireforge 0.37.0 → 0.39.0

package/dist/src/commands/test.js

@@ -10,17 +10,16 @@ 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 { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, 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) {
@@ -34,19 +33,6 @@ async function assertTestPathsExist(engineDir, testPaths) {
     throw new GeneralError(`Test path${missingPaths.length === 1 ? '' : 's'} not found under engine/: ${missingPaths.join(', ')}\n\n` +
         'If you expected these files to come from your patch stack, run "fireforge import" first.');
 }
-async function classifyTestHarnesses(engineDir, normalizedPaths) {
-    const result = { xpcshell: [], nonXpcshell: [] };
-    for (const testPath of normalizedPaths) {
-        const manifest = await findNearestXpcshellManifest(engineDir, testPath);
-        if (manifest) {
-            result.xpcshell.push(testPath);
-        }
-        else {
-            result.nonXpcshell.push(testPath);
-        }
-    }
-    return result;
-}
 /**
  * Picks the mach dispatch target for a (non-mixed) run. A single-suite run
  * auto-routes to the suite-specific command (`mach xpcshell-test` /
@@ -66,12 +52,6 @@ function resolveTestSuite(classification, forceGeneric) {
     }
     return 'generic';
 }
-function buildMixedHarnessMessage(classification) {
-    return ('FireForge cannot run xpcshell and browser/mochitest paths in the same mach invocation.\n\n' +
-        'Split this into separate `fireforge test` commands so each manifest selects its own harness:\n' +
-        `  - xpcshell: ${classification.xpcshell.join(', ')}\n` +
-        `  - browser/mochitest: ${classification.nonXpcshell.join(', ')}`);
-}
 function filterRedundantXpcshellFlavorArgs(machArgs, classification) {
     if (classification.xpcshell.length === 0 || classification.nonXpcshell.length > 0) {
         return [...machArgs];
@@ -135,9 +115,14 @@ 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, testPackagingCoverage === 'full'
+                    ? 'fireforge test --build'
+                    : `fireforge test --build ${testPackagingCoverage.join(' ')}`);
             }
             catch (baselineError) {
                 verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
@@ -150,51 +135,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
@@ -281,7 +221,7 @@ async function runDoctorPreflight(args) {
  * `--mach-arg` and the xpcshell flavor that ignores the pref entirely.
  * Mutates `extraArgs` in place.
  */
-function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort) {
+function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly = false) {
     // Auto-forward the Marionette port to mach when `--marionette-port` is
     // set. `--setpref=marionette.port=<n>` configures where the browser
     // listener binds; `--marionette=127.0.0.1:<n>` tells the mochitest harness
@@ -300,6 +240,14 @@ function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort) {
     // `--marionette=...` (or two-token `--marionette host:port`).
     if (options.marionettePort === undefined)
         return;
+    if (xpcshellOnly) {
+        // Manifest classification says every requested path is xpcshell —
+        // xpcshell ignores the browser Marionette path entirely, and the
+        // mochitest client flags previously forwarded here made mach reject
+        // the dispatch (FORGE F10).
+        info(`--marionette-port=${options.marionettePort} applied to the preflight probe only: the requested paths are xpcshell-only, and xpcshell ignores the browser Marionette port. Not forwarding --setpref=marionette.port or --marionette to mach.`);
+        return;
+    }
     {
         const operatorAlreadyForwarded = forwardedPort !== undefined;
         const machArgs = options.machArg ?? [];
@@ -318,8 +266,23 @@ function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort) {
         }
     }
 }
-async function ensureTestMarionettePortAvailable(port, binaryName, killStaleBrowser) {
-    if (killStaleBrowser) {
+async function ensureTestMarionettePortAvailable(port, binaryName, options, skip) {
+    if (skip.xpcshellOnly && !skip.doctor) {
+        // xpcshell does not bind the browser Marionette port, so a developer's
+        // interactive browser holding 2828 must not kill an xpcshell run
+        // (FORGE F10). --doctor keeps the preflight: its probe launches a
+        // Marionette browser regardless of the requested harness.
+        const message = 'Skipping the Marionette stale-port preflight: all requested paths are xpcshell ' +
+            '(xpcshell does not bind the browser Marionette port).';
+        if (options.marionettePort !== undefined || options.killStaleMarionette === true) {
+            info(message);
+        }
+        else {
+            verbose(message);
+        }
+        return;
+    }
+    if (options.killStaleMarionette === true) {
         await ensureMarionettePortAvailable(port, { binaryName, killStaleBrowser: true });
         return;
     }
@@ -363,11 +326,19 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // stale/coverage refusals keep precedence over missing-path errors.)
     const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
     const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
+    const { classification, xpcshellOnly } = await classifyBeforeDispatch(paths.engine, normalizedPaths);
     // 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('');
     }
@@ -396,7 +367,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // generic bind failure. 2026-04-21 eval (Finding #20): a stale
     // `-marionette` process from `fresh/` poisoned a later test run in
     // the sibling `mybrowser/` workspace.
-    await ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options.killStaleMarionette === true);
+    await ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options, {
+        xpcshellOnly,
+        doctor: options.doctor === true,
+    });
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
             engineDir: paths.engine,
@@ -410,10 +384,6 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             return;
     }
     await assertTestPathsExist(paths.engine, normalizedPaths);
-    const classification = await classifyTestHarnesses(paths.engine, normalizedPaths);
-    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
-        throw new GeneralError(buildMixedHarnessMessage(classification));
-    }
     const suite = resolveTestSuite(classification, options.genericMachTest === true);
     const forwardedMachArgs = options.machArg && options.machArg.length > 0
         ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
@@ -436,7 +406,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (forwardedMachArgs.length > 0) {
         extraArgs.push(...forwardedMachArgs);
     }
-    appendMarionetteForwardingArgs(extraArgs, options, forwardedPort);
+    appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
     // Directory arguments mean EXACTLY that directory: mozbuild's test
     // resolver matches paths by string prefix, so a bare directory arg
     // silently swept in prefix-named siblings (152.0b7 → 153.0b8 drill:
@@ -472,6 +442,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         suite,
         baseExtraArgs: extraArgs,
         harnessRetries,
+        headless: options.headless === true,
         ...(perfSampleEnv ? { env: perfSampleEnv } : {}),
     };
     const postRebuildContext = options.build
@@ -517,7 +488,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         reportCanaryOutcome(outcome);
         return;
     }
-    finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext);
+    finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext, options.headless === true);
 }
 /**
  * Builds the perf-sample env contract for the harness run (field report

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,49 @@ 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;
+    /**
+     * Invocation shape that recorded this baseline (`'fireforge build'`,
+     * `'fireforge build --ui'`, `'fireforge test --build [paths]'`).
+     * Informational — surfaced by `fireforge status --test-coverage`.
+     * Missing on pre-0.39.0 baselines; render as "unknown".
+     */
+    recordedBy?: string;
+}
+/**
+ * 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, recordedBy?: string): 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, recordedBy) {
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -84,12 +89,21 @@ 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 } : {}),
+        ...(recordedBy !== undefined ? { recordedBy } : {}),
     };
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }
@@ -107,6 +121,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 +161,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 +175,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/build-prepare.d.ts

@@ -24,6 +24,15 @@ export interface PrepareBuildOptions {
      */
     previousBaseline?: BuildBaseline | undefined;
 }
+/**
+ * Describes an exit code in the shell's 128+N signal convention. Truncated
+ * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
+ * on macOS) are environmental interruptions, not compiler failures — naming
+ * that in the failure text saves the operator a fruitless log hunt
+ * (FORGE F16). Returns undefined for codes <= 128 (regular failures) and
+ * for codes past the conventional signal range, so callers append nothing.
+ */
+export declare function describeSignalShapedExit(exitCode: number): string | undefined;
 /**
  * Returns true when the file path matches a pattern that forces
  * `mach configure` to regenerate the backend. Exported for testing.

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

@@ -3,6 +3,7 @@
  * Shared pre-flight logic for build and package commands:
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
+import { constants as osConstants } from 'node:os';
 import { BuildError } from '../errors/build.js';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
@@ -33,6 +34,27 @@ function extractMachConfigureError(result) {
         return '';
     return combined.split('\n').slice(-40).join('\n').trim();
 }
+/**
+ * Describes an exit code in the shell's 128+N signal convention. Truncated
+ * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
+ * on macOS) are environmental interruptions, not compiler failures — naming
+ * that in the failure text saves the operator a fruitless log hunt
+ * (FORGE F16). Returns undefined for codes <= 128 (regular failures) and
+ * for codes past the conventional signal range, so callers append nothing.
+ */
+export function describeSignalShapedExit(exitCode) {
+    if (exitCode <= 128 || exitCode > 192)
+        return undefined;
+    const signalNumber = exitCode - 128;
+    const names = Object.entries(osConstants.signals)
+        .filter(([, value]) => value === signalNumber)
+        .map(([name]) => name);
+    const label = names.length > 0 ? names.join('/') : `signal ${signalNumber}`;
+    return (`Exit ${exitCode} is signal-shaped (${exitCode} - 128 = ${signalNumber}, ${label} on this host): ` +
+        'the process was likely interrupted externally (OOM-killer, terminal disconnect, ' +
+        'display/session teardown) rather than failing on its own, and the log may be ' +
+        'truncated mid-step.');
+}
 /**
  * Builds the `BuildError` for a non-zero auto-configure exit: the output
  * tail (so the underlying mozbuild failure survives), any matched
@@ -43,8 +65,10 @@ function extractMachConfigureError(result) {
 function buildConfigureFailureError(captured) {
     const detail = extractMachConfigureError(captured);
     const hints = explainMachError(`${captured.stderr}\n${captured.stdout}`);
+    const signalNote = describeSignalShapedExit(captured.exitCode);
     return new BuildError(`Backend regeneration failed: mach configure exited with code ${captured.exitCode}.` +
         (detail ? `\n\nmach configure output (tail):\n${detail}` : '') +
+        (signalNote ? `\n\n${signalNote}` : '') +
         (hints.length > 0 ? `\n\n${hints.map((hint) => `Hint: ${hint}`).join('\n')}` : '') +
         '\n\nBuild stopped because continuing would hide the real configure failure.', 'mach configure');
 }

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`). */
@@ -343,6 +348,10 @@ function parsePatchLintBlock(rec) {
     if (chromeScriptJsDoc !== undefined) {
         out.chromeScriptJsDoc = chromeScriptJsDoc;
     }
+    const undefinedIdentifiers = parseSeverityGate(rec.raw('undefinedIdentifiers'), 'patchLint.undefinedIdentifiers');
+    if (undefinedIdentifiers !== undefined) {
+        out.undefinedIdentifiers = undefinedIdentifiers;
+    }
     if (out.checkJsStrict === true && out.checkJs !== true) {
         throw new ConfigError('Config field "patchLint.checkJsStrict" requires "patchLint.checkJs": true');
     }
@@ -408,6 +417,10 @@ function parseTypecheckBlock(rec) {
     if (overrides) {
         out.projectOverrides = overrides;
     }
+    const undefinedIdentifiers = parseSeverityGate(rec.raw('undefinedIdentifiers'), 'typecheck.undefinedIdentifiers');
+    if (undefinedIdentifiers !== undefined) {
+        out.undefinedIdentifiers = undefinedIdentifiers;
+    }
     return out;
 }
 /**

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

@@ -0,0 +1,60 @@
+/**
+ * Patch-aware restore planning for `fireforge discard` (FORGE F1, P0).
+ *
+ * The engine convention is: HEAD = pristine upstream Firefox, and the
+ * applied patch queue lives as UNCOMMITTED worktree changes on top of it
+ * (`git apply` without `--index` → patch-edited tracked files are unstaged
+ * modifications, patch-created files are untracked). The pre-0.39.0
+ * `discard` was purely git-mechanical — it restored to HEAD and deleted
+ * untracked files, silently reverting patch-backed files PAST their owning
+ * patch and deleting patch-created files outright.
+ *
+ * This module classifies each status entry against the patch manifest's
+ * ownership claims and plans the correct restore target: the PATCH-APPLIED
+ * baseline (HEAD content folded through every affecting patch in order) for
+ * claimed files, and the legacy git mechanics for unmanaged ones.
+ */
+import type { GitStatusEntry } from './git-base.js';
+/** How one status entry's canonical path will be restored. */
+export type DiscardKind = 'unmanaged' | 'patch-backed' | 'patch-created' | 'patch-deleted';
+/** Restore plan for one git status entry. */
+export interface DiscardBaselinePlan {
+    entry: GitStatusEntry;
+    kind: DiscardKind;
+    /** Claiming patch filenames for `entry.file` ∪ `entry.originalPath`. */
+    owners: string[];
+    /** True when more than one patch claims the path (ownership conflict). */
+    conflicted: boolean;
+    /** Baseline content for `entry.file`; null = absent at baseline. Unset for 'unmanaged'. */
+    expectedContent?: string | null;
+    /** Rename/copy only: baseline content for `originalPath` when that side is claimed. */
+    expectedOriginalContent?: string | null;
+}
+/** Builds an all-unmanaged plan set — the `--to-upstream` (legacy) shape. */
+export declare function planUpstreamDiscards(entries: readonly GitStatusEntry[]): DiscardBaselinePlan[];
+/**
+ * Plans the restore target for each status entry. Entries claimed by the
+ * patch manifest restore to the patch-applied baseline; unclaimed entries
+ * keep the legacy git mechanics. A missing patches dir or empty manifest
+ * degrades every plan to `unmanaged` (identical to pre-0.39.0 behavior).
+ *
+ * A corrupt manifest or an unreconstructible patch baseline REFUSES with a
+ * GeneralError naming `--to-upstream` — silently falling back to pristine
+ * HEAD is exactly the data-loss path this module exists to close.
+ */
+export declare function planDiscardBaselines(patchesDir: string, engineDir: string, entries: readonly GitStatusEntry[]): Promise<DiscardBaselinePlan[]>;
+/**
+ * Applies one restore plan. Patch-claimed paths end up exactly as `import`
+ * leaves them: patched content as an unstaged worktree state (tracked files
+ * read ` M`, created files `??`), nothing staged. Unmanaged plans delegate
+ * to the legacy {@link discardStatusEntry} mechanics.
+ */
+export declare function applyDiscardBaseline(engineDir: string, plan: DiscardBaselinePlan): Promise<void>;
+/** One-line annotation for dry-run listings and confirmation summaries. */
+export declare function describeDiscardBaseline(plan: DiscardBaselinePlan): string;
+/** Single-file outro naming the baseline that was restored. */
+export declare function describeDiscardOutcome(plan: DiscardBaselinePlan, toUpstream: boolean): string;
+/** Batch outro summarising how many files restored to which baseline. */
+export declare function summarizeDiscardBaselines(plans: readonly DiscardBaselinePlan[], succeeded: number): string;
+/** Warn text for a multi-owner (conflicted) restore. */
+export declare function describeConflictWarning(plan: DiscardBaselinePlan): string;