@hominis/fireforge 0.35.0 → 0.37.0

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

@@ -63,35 +63,36 @@ const SHARD_STATUS_LABEL = {
     'no-tests': 'NO-TESTS',
 };
 /**
- * Runs each requested path as its own sequential harness invocation and
- * prints an aggregate report. Per-shard failures are diagnosed via
- * `diagnoseShardFailure` (which receives the throwing diagnosis chain from
- * the command layer) but downgraded to warnings so every shard runs; a
- * single aggregate error is thrown at the end when any shard did not pass.
+ * Runs each requested path argument as its own sequential harness
+ * invocation (a directory argument's enumerated files stay together in
+ * one invocation — see {@link ShardGroup}) and prints an aggregate
+ * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
+ * (which receives the throwing diagnosis chain from the command layer)
+ * but downgraded to warnings so every shard runs; a single aggregate
+ * error is thrown at the end when any shard did not pass.
  */
-export async function runShardedTests(ctx, paths, diagnoseShardFailure) {
+export async function runShardedTests(ctx, groups, diagnoseShardFailure) {
     const shards = [];
-    for (const [index, path] of paths.entries()) {
-        info(`— Shard ${index + 1}/${paths.length}: ${path}`);
-        const outcome = await runTestsWithRetries(ctx, [path]);
-        shards.push({ path, outcome });
+    for (const [index, group] of groups.entries()) {
+        info(`— Shard ${index + 1}/${groups.length}: ${group.label}`);
+        const outcome = await runTestsWithRetries(ctx, group.paths);
+        shards.push({ label: group.label, outcome });
         if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
             warn(buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts));
         }
         else if (outcome.verdict.kind !== 'tests-ran-ok') {
-            const diagnosis = diagnoseShardFailure(outcome, path);
+            const diagnosis = diagnoseShardFailure(outcome, group.label);
             if (diagnosis)
                 warn(diagnosis);
         }
     }
-    const lines = shards.map(({ path, outcome }) => `${SHARD_STATUS_LABEL[outcome.verdict.kind].padEnd(8)} ${path}` +
+    const lines = shards.map(({ label, outcome }) => `${SHARD_STATUS_LABEL[outcome.verdict.kind].padEnd(8)} ${label}` +
         (outcome.attempts > 1 ? `  (${outcome.attempts} attempts)` : ''));
     const failing = shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
     note(`${lines.join('\n')}\n\n${shards.length - failing.length}/${shards.length} shard(s) passed`, 'Sharded Test Summary');
     if (failing.length > 0) {
         throw new BuildError(`${failing.length} of ${shards.length} sharded test run(s) did not pass: ` +
-            `${failing.map(({ path }) => path).join(', ')}. ` +
+            `${failing.map(({ label }) => label).join(', ')}. ` +
             'See the per-shard diagnosis above. Use --no-shard to reproduce the combined single-invocation behaviour.', 'mach test');
     }
 }
-//# sourceMappingURL=test-run.js.map

package/dist/src/commands/test.d.ts

@@ -1,5 +1,3 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
 import type { TestOptions } from '../types/commands/index.js';
 /**
  * Runs the test command to execute mach tests.
@@ -8,5 +6,3 @@ import type { TestOptions } from '../types/commands/index.js';
  * @param options - Test options
  */
 export declare function testCommand(projectRoot: string, testPaths: string[], options?: TestOptions): Promise<void>;
-/** Registers the test command on the CLI program. */
-export declare function registerTest(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/test.js

@@ -1,23 +1,25 @@
 // 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';
 import { buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, runProtectedMachBuild, withBuildLock, } from '../core/mach.js';
-import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
+import { assertMarionettePortAvailable, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 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 { 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, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
+import { info, intro, outro, spinner, success, verbose, warn } 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';
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
@@ -102,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
@@ -127,6 +129,19 @@ 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.
+            try {
+                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, testPackagingCoverage);
+            }
+            catch (baselineError) {
+                verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
+            }
             return;
         }
         s.error('Pre-test build failed');
@@ -135,9 +150,57 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
             : 'Pre-test build failed', 'mach build faster');
     });
 }
-function logTestSelection(normalizedPaths) {
-    if (normalizedPaths.length > 0) {
-        info(`Running tests: ${normalizedPaths.join(', ')}`);
+/**
+ * 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
+            ? `${scope.requestedPath} (${scope.testFileCount} test file${scope.testFileCount === 1 ? '' : 's'}, passed explicitly)`
+            : scope.requestedPath);
+        info(`Running tests: ${labels.join(', ')}`);
     }
     else {
         info('Running all tests...');
@@ -255,6 +318,13 @@ function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort) {
         }
     }
 }
+async function ensureTestMarionettePortAvailable(port, binaryName, killStaleBrowser) {
+    if (killStaleBrowser) {
+        await ensureMarionettePortAvailable(port, { binaryName, killStaleBrowser: true });
+        return;
+    }
+    await assertMarionettePortAvailable(port, { binaryName });
+}
 /**
  * Runs the test command to execute mach tests.
  * @param projectRoot - Root directory of the project
@@ -268,11 +338,14 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (!(await pathExists(paths.engine))) {
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
+    assertPathlessTestMode(testPaths, options);
     const buildCheck = await assertTestBuildArtifacts(paths.engine);
     // Load the project config once so both the build and the port
     // probe have access to `binaryName` (the port probe uses it to
     // recognise a fork-branded browser holding the Marionette port).
     const projectConfig = await loadConfig(projectRoot);
+    const canaryPath = resolveCanaryPath(options, projectConfig);
+    assertTestModeCombinations(testPaths, options, canaryPath);
     // `hasBuildArtifacts` only confirms `obj-*/dist/` exists; a partial
     // build (linker failed, packaging step interrupted, etc.) can satisfy
     // that check without ever writing the launchable binary the marionette
@@ -283,24 +356,23 @@ 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.
+        const coverage = normalizedPaths.length === 0 ? 'full' : normalizedPaths;
+        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 warn UP-FRONT. Without this, edits to chrome / packaged resources
-        // surface only as a cryptic `NS_ERROR_FILE_NOT_FOUND` inside xpcshell
-        // after mach test has already launched (see motivating case in
-        // `core/test-stale-check.ts`). The check is warn-only so a fork that
-        // rebuilt out-of-band (no FireForge-recorded baseline update) is not
-        // blocked from running tests.
-        const stale = await checkStaleBuildForTest(projectRoot, paths.engine);
-        if (stale.stale) {
-            warn(formatStaleBuildWarning(stale));
-        }
+        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)
@@ -324,7 +396,7 @@ 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 assertMarionettePortAvailable(effectivePort, { binaryName: projectConfig.binaryName });
+    await ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options.killStaleMarionette === true);
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
             engineDir: paths.engine,
@@ -337,7 +409,6 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         if (doctorOutcome === 'stop')
             return;
     }
-    const normalizedPaths = testPaths.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) {
@@ -351,6 +422,12 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (options.headless) {
         extraArgs.push('--headless');
     }
+    if (options.auto === true) {
+        extraArgs.push('--auto');
+    }
+    if (canaryPath !== undefined) {
+        extraArgs.push(`--timeout=${String(canaryTimeoutSeconds(projectConfig))}`);
+    }
     // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
     // flags FireForge does not model directly (see the xpcshell appdir hint
     // above for the motivating case). Appended AFTER --headless so mach sees
@@ -364,13 +441,19 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // resolver matches paths by string prefix, so a bare directory arg
     // silently swept in prefix-named siblings (152.0b7 → 153.0b8 drill:
     // `…/test/hominis` also ran `…/test/hominis-tiles`, 1224 tests instead
-    // of ~200, with no indication the scope widened). The dispatch form
-    // gains a trailing `/` (making the prefix match exact) and any
-    // excluded prefix-siblings are echoed so the narrowed scope is
-    // visible. Classification above intentionally used the un-slashed
-    // forms; only the mach dispatch needs the exact-match shape.
+    // of ~200, with no indication the scope widened). Each directory
+    // argument dispatches as its enumerated explicit test-file list — a
+    // file list cannot prefix-match a sibling (0.35.0's trailing-`/`
+    // normalization turned out to be cosmetic on Firefox 153's mach; field
+    // verification showed the sibling still ran while the echo claimed it
+    // was excluded). Any prefix-siblings are echoed so the narrowed scope
+    // is visible. Classification above intentionally used the raw
+    // argument forms; only the mach dispatch needs the exact-match shape.
     const scopes = await analyzeTestPathScopes(paths.engine, normalizedPaths);
-    const dispatchPaths = scopes.map((scope) => scope.dispatchPath);
+    const dispatchGroups = scopes.map((scope) => ({
+        label: scope.requestedPath,
+        paths: scope.dispatchPaths,
+    }));
     for (const scope of scopes) {
         const notice = formatScopeNotice(scope);
         if (notice)
@@ -380,7 +463,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // `runTestsWithRetries` (src/commands/test-run.ts) so sharded runs probe
     // the manifest for each file individually. See src/core/xpcshell-appdir.ts
     // for the full motivation.
-    logTestSelection(dispatchPaths);
+    logTestSelection(scopes);
     const perfSampleEnv = buildPerfSampleEnv(projectRoot, projectConfig.binaryName, options.perfSamples);
     const runCtx = {
         engineDir: paths.engine,
@@ -394,29 +477,46 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     const postRebuildContext = options.build
         ? createPostRebuildFailureContext('fireforge test --build', normalizedPaths)
         : undefined;
-    // Multi-file requests shard into sequential single-file harness runs by
-    // default (field report C3): one shared mochitest profile across files
-    // bleeds pref/media-query state into later files. --no-shard restores
-    // the combined invocation. The default must not be SILENT (drill
-    // finding: a two-file cross-file pollution repro "passed" because the
-    // headed comparison run was sharded without saying so, briefly
-    // misattributing a suite-context bug to an upstream headless
-    // regression), so a one-line notice states what sharding does and
-    // does not exercise.
-    if (dispatchPaths.length > 1 && options.shard !== false) {
-        info(`Sharding: running ${dispatchPaths.length} test paths in isolated browser instances ` +
-            '(one mach invocation per path). Cross-file state is NOT exercised — pass --no-shard ' +
-            'for a combined single-instance run.');
-        await runShardedTests(runCtx, dispatchPaths, (outcome, path) => diagnoseShardOutcome(outcome, path, projectConfig.binaryName, postRebuildContext));
+    // Multi-argument requests shard into sequential harness runs by default
+    // (field report C3): one shared mochitest profile across files bleeds
+    // pref/media-query state into later files. Sharding is per path
+    // ARGUMENT — a directory argument keeps its enumerated files together
+    // in one invocation, preserving the one-browser-instance semantics of
+    // a directory run. --no-shard restores the combined invocation. The
+    // default must not be SILENT (drill finding: a two-file cross-file
+    // pollution repro "passed" because the headed comparison run was
+    // sharded without saying so, briefly misattributing a suite-context
+    // bug to an upstream headless regression), so a one-line notice states
+    // what sharding does and does not exercise.
+    if (canaryPath === undefined && dispatchGroups.length > 1 && options.shard !== false) {
+        info(`Sharding: running ${dispatchGroups.length} test path arguments in isolated browser instances ` +
+            '(one mach invocation per argument; a directory argument keeps its files in one instance). ' +
+            'Cross-argument state is NOT exercised — pass --no-shard for a combined single-instance run.');
+        const generationBefore = await snapshotEngineGeneration(paths.engine);
+        try {
+            await runShardedTests(runCtx, dispatchGroups, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, postRebuildContext));
+        }
+        finally {
+            await assertEngineGenerationUnchanged(paths.engine, generationBefore);
+        }
         return;
     }
+    const combinedDispatchPaths = dispatchGroups.flatMap((group) => group.paths);
     let outcome;
+    const generationBefore = await snapshotEngineGeneration(paths.engine);
     try {
-        outcome = await runTestsWithRetries(runCtx, dispatchPaths);
+        outcome = await runTestsWithRetries(runCtx, combinedDispatchPaths);
     }
     catch (error) {
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
     }
+    finally {
+        await assertEngineGenerationUnchanged(paths.engine, generationBefore);
+    }
+    if (canaryPath !== undefined) {
+        reportCanaryOutcome(outcome);
+        return;
+    }
     finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext);
 }
 /**
@@ -432,52 +532,3 @@ function buildPerfSampleEnv(projectRoot, binaryName, perfSamples) {
     info(`Perf sample contract: ${envName}=${artifactPath}`);
     return { [envName]: artifactPath };
 }
-/** Registers the test command on the CLI program. */
-export function registerTest(program, { getProjectRoot, withErrorHandling }) {
-    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('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
-        .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', (value, acc) => {
-        acc.push(value);
-        return acc;
-    }, [])
-        .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${String(DEFAULT_HARNESS_RETRIES)}.`, (raw) => {
-        const n = Number.parseInt(raw, 10);
-        if (!Number.isFinite(n) || n < 0 || n > 10) {
-            throw new GeneralError(`--harness-retries must be an integer in 0..10 (got "${raw}")`);
-        }
-        return n;
-    })
-        .option('--generic-mach-test', 'Force dispatch through generic `mach test` instead of the suite-specific `mach xpcshell-test` / `mach mochitest` a single-suite run auto-selects (the suite-specific commands skip the mozlog resource monitor that crashes `mach test` on some hosts).')
-        .option('--no-shard', 'Run multiple test paths in one combined mach invocation instead of sequential per-file shards (isolated instances do not exercise cross-file state, so use this to reproduce cross-file pollution bugs)')
-        .option('--perf-samples <path>', 'Publish a perf-sample artifact path to the harness via <BINARYNAME>_PERF_SAMPLE_JSON (resolved against the project root)')
-        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and (unless --mach-arg includes --flavor=xpcshell) auto-forwarded mach args: --setpref=marionette.port=<n> (browser listener) and --marionette=127.0.0.1:<n> (mochitest client). Omits the client flag when --mach-arg already sets --marionette. Use when 2828 is busy or CI assigns another port.', (raw) => {
-        const n = Number.parseInt(raw, 10);
-        if (!Number.isFinite(n) || n < 1 || n > 65535) {
-            throw new GeneralError(`--marionette-port must be an integer in 1..65535 (got "${raw}")`);
-        }
-        return n;
-    })
-        .addHelpText('after', [
-        '',
-        '[paths...] semantics: a directory argument selects EXACTLY that',
-        'directory. FireForge normalizes it with a trailing "/" before',
-        'handing it to mach, because mach resolves test paths by string',
-        'prefix and a bare directory name would silently sweep in sibling',
-        'directories sharing the prefix (e.g. foo also running foo-extras).',
-        'When such siblings exist, the excluded directories are listed with',
-        'their test-file counts; pass them as separate paths to include them.',
-        '',
-        'Multiple paths shard into sequential isolated harness runs (one',
-        'browser instance per path) by default, which does not exercise',
-        'cross-file state; --no-shard restores the combined single-instance',
-        'invocation.',
-    ].join('\n'))
-        .action(withErrorHandling(async (paths, options) => {
-        await testCommand(getProjectRoot(), paths, pickDefined(options));
-    }));
-}
-//# sourceMappingURL=test.js.map

package/dist/src/commands/token-coverage.js

@@ -174,4 +174,3 @@ async function collectFurnaceCustomCssFiles(projectRoot, engineDir, tokensCssPat
     }
     return results;
 }
-//# sourceMappingURL=token-coverage.js.map

package/dist/src/commands/token.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { Option } from 'commander';
+import { Command, Option } from 'commander';
 import { loadConfig } from '../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
 import { addToken, getTokensCssPath, validateTokenAdd, } from '../core/token-manager.js';
@@ -183,4 +183,3 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         await tokenCoverageCommand(getProjectRoot());
     }));
 }
-//# sourceMappingURL=token.js.map

package/dist/src/commands/typecheck.js

@@ -15,6 +15,7 @@
  * Exits non-zero on any error-severity diagnostic. Warnings print
  * but do not fail. Designed for CI use.
  */
+import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
 import { findJsconfigPathsDrift, syncFurnaceJsconfigPaths } from '../core/furnace-jsconfig.js';
@@ -147,4 +148,3 @@ export function registerTypecheck(program, { getProjectRoot, withErrorHandling }
         await typecheckCommand(getProjectRoot(), opts);
     }));
 }
-//# sourceMappingURL=typecheck.js.map

package/dist/src/commands/verify.js

@@ -15,6 +15,7 @@
  * treat the output as pass/fail.
  */
 import { join } from 'node:path';
+import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { isGitRepository } from '../core/git.js';
@@ -23,6 +24,7 @@ import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
 import { loadPatchesManifest, validatePatchesManifestConsistency } from '../core/patch-manifest.js';
 import { evaluatePatchPolicy } from '../core/patch-policy.js';
 import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
+import { buildPatchClaims } from '../core/status-classify.js';
 import { classifyFiles } from '../core/status-classify.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
@@ -88,14 +90,7 @@ async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
     return issues;
 }
 function detectCrossPatchFileClaims(manifestPatches) {
-    const claims = new Map();
-    for (const patch of manifestPatches) {
-        for (const file of patch.filesAffected) {
-            const existing = claims.get(file) ?? [];
-            existing.push(patch.filename);
-            claims.set(file, existing);
-        }
-    }
+    const claims = buildPatchClaims(manifestPatches);
     const results = [];
     for (const [path, filenames] of claims) {
         if (filenames.length > 1) {
@@ -284,4 +279,3 @@ export function registerVerify(program, { getProjectRoot, withErrorHandling }) {
         await verifyCommand(getProjectRoot());
     }));
 }
-//# sourceMappingURL=verify.js.map

package/dist/src/commands/watch.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { delimiter, dirname } from 'node:path';
+import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, hasRunnableBundle, watchWithOutput, } from '../core/mach.js';
@@ -195,6 +196,10 @@ export async function watchCommand(projectRoot) {
     catch (error) {
         throw new BuildError('Watch process failed to start', 'mach watch', error instanceof Error ? error : undefined);
     }
+    // On Ctrl+C the bin signal handler now waits for the mach child to shut
+    // down (waitForActiveChildShutdown) before exiting, so this continuation
+    // can run and whitelist the SIGINT exit code — though the bin may still
+    // win the race and terminate first; both outcomes are acceptable.
     if (result.exitCode !== 0 && result.exitCode !== 130) {
         const combinedOutput = `${result.stdout}\n${result.stderr}`;
         if (hasConfigureTimeWatchmanFailure(combinedOutput)) {
@@ -214,4 +219,3 @@ export function registerWatch(program, { getProjectRoot, withErrorHandling }) {
         await watchCommand(getProjectRoot());
     }));
 }
-//# sourceMappingURL=watch.js.map

package/dist/src/commands/wire.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, relative } from 'node:path';
+import { Command } from 'commander';
 import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript } from '../core/browser-wire.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
@@ -356,4 +357,3 @@ export function registerWire(program, { getProjectRoot, withErrorHandling }) {
         await wireCommand(getProjectRoot(), name, pickDefined(options));
     }));
 }
-//# sourceMappingURL=wire.js.map

package/dist/src/core/ast-utils.js

@@ -79,4 +79,3 @@ export function detectIndent(content, position) {
 export function getNodeSource(content, node) {
     return content.slice(node.start, node.end);
 }
-//# sourceMappingURL=ast-utils.js.map

package/dist/src/core/brand-validation.js

@@ -12,4 +12,3 @@ export function validateBrandOverride(configuredBrand, requestedBrand) {
     }
     throw new InvalidArgumentError(`Brand override "${requestedBrand}" is not supported yet. FireForge currently operates only on the configured brand "${configuredBrand}".`, 'brand');
 }
-//# sourceMappingURL=brand-validation.js.map

package/dist/src/core/branding.js

@@ -356,4 +356,3 @@ export function isBrandingManagedPath(file, binaryName) {
         normalized === `${brandingRoot}/` ||
         normalized.startsWith(`${brandingRoot}/`));
 }
-//# sourceMappingURL=branding.js.map

package/dist/src/core/browser-wire.js

@@ -125,4 +125,3 @@ export async function wireSubscript(root, name, options = {}) {
         throw error;
     }
 }
-//# sourceMappingURL=browser-wire.js.map

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

@@ -234,4 +234,3 @@ export async function detectPlatformGate(engineDir, sourcePath) {
     }
     return { gatedOff: false };
 }
-//# sourceMappingURL=build-audit-platform.js.map

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

@@ -184,4 +184,3 @@ export async function collectSameBasenameCandidates(source, searchRoots) {
     }
     return out;
 }
-//# sourceMappingURL=build-audit-registration.js.map

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

@@ -215,4 +215,3 @@ export async function resolveBestArtifact(sourcePath, searchRoots) {
     }
     return best;
 }
-//# sourceMappingURL=build-audit-resolve.js.map

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

@@ -91,4 +91,3 @@ export async function resolveArtifactByKnownTransform(source, searchRoots) {
     }
     return undefined;
 }
-//# sourceMappingURL=build-audit-transforms.js.map

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

@@ -475,4 +475,3 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
     info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
     return summary;
 }
-//# sourceMappingURL=build-audit.js.map

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

@@ -35,4 +35,28 @@ export interface BuildBaseline {
      * was recorded.
      */
     packageableFingerprints?: Record<string, string>;
+    /**
+     * What the packaged test runtime produced by the recorded build covers.
+     *
+     * - `'full'`: the build packaged the full test set — written by
+     *   `fireforge build` / `build --ui` and by a path-less
+     *   `fireforge test --build` (full-suite run).
+     * - `string[]`: engine-relative POSIX request paths of the file/directory-
+     *   scoped `fireforge test --build` invocation that produced the runtime.
+     *   A directory entry covers everything beneath it. Support fixtures for
+     *   manifests outside this list may be missing from `obj-*`/`_tests/`, so
+     *   an `--allow-stale-build` run over uncovered paths is refused rather
+     *   than dispatched into a hang.
+     *
+     * Missing on baselines written before 0.37.0 — only `fireforge build`
+     * wrote baselines then, so "full" is the honest historical value and the
+     * stale-check treats an absent field as full coverage.
+     *
+     * 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.
+     */
+    testPackagingCoverage?: TestPackagingCoverage;
 }
+/** Coverage claim of the packaged test runtime. See {@link BuildBaseline.testPackagingCoverage}. */
+export type TestPackagingCoverage = 'full' | string[];

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

@@ -7,4 +7,3 @@
  * into it would make the dependency graph cyclic.
  */
 export {};
-//# sourceMappingURL=build-baseline-types.js.map