@hominis/fireforge 0.50.0 → 0.52.0

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

@@ -19,7 +19,7 @@ import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations
 import { validateExpectedRemovals } from './re-export-removed.js';
 import { normalizeEngineRelativeInput, normalizeScanFiles } from './re-export-scan.js';
 import { assignScanFileOwners, scanOptionsForPatch } from './re-export-scan-owner.js';
-import { reExportSinglePatchWithIndexLockRetry } from './re-export-single.js';
+import { reExportSinglePatchWithIndexLockRetry, } from './re-export-single.js';
 import { formatReExportRunSummary } from './re-export-summary.js';
 async function resolveSelectedPatches(patches, options, manifest) {
     if (options.all) {
@@ -59,6 +59,27 @@ async function resolveSelectedPatches(patches, options, manifest) {
     const selectedFilenames = selected;
     return manifest.patches.filter((p) => selectedFilenames.includes(p.filename));
 }
+/** Refreshes each selected patch in turn, collecting which wrote and which failed. */
+async function reExportEach(args) {
+    const { selectedPatches, options, scanAssignments, progress, startedAt, shared } = args;
+    const written = [];
+    const failed = [];
+    for (const [index, patch] of selectedPatches.entries()) {
+        const patchOptions = scanOptionsForPatch(options, patch.filename, scanAssignments);
+        progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
+        try {
+            if (await reExportSinglePatchWithIndexLockRetry({ ...shared, patch, options: patchOptions })) {
+                written.push(patch.filename);
+            }
+        }
+        catch (error) {
+            failed.push(patch.filename);
+            warn(`Failed to re-export ${patch.filename}`);
+            warn(toError(error).message);
+        }
+    }
+    return { written, failed };
+}
 /**
  * Runs the re-export command to regenerate existing patches from current engine state.
  * @param projectRoot - Root directory of the project
@@ -105,7 +126,7 @@ export async function reExportCommand(projectRoot, patches, options) {
         outro('Nothing to re-export');
         return;
     }
-    const expectedRemovals = await validateExpectedRemovals(paths, selectedPatches, options);
+    const expectedRemovals = await validateExpectedRemovals(paths, selectedPatches, options, manifest.patches);
     if (expectedRemovals.length > 0)
         options = { ...options, expectRemoved: expectedRemovals };
     if (scanFilesByPatch !== undefined) {
@@ -125,7 +146,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     // we write anything.
     if (options.files !== undefined) {
         const filesConfig = await loadConfig(projectRoot);
-        await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportFilesInPlace(paths, selectedPatches, options, filesConfig)));
+        await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportFilesInPlace(paths, selectedPatches, options, filesConfig), { patches: selectedPatches }));
         return;
     }
     const config = await loadConfig(projectRoot);
@@ -139,38 +160,18 @@ export async function reExportCommand(projectRoot, patches, options) {
     // reports includes it.
     const startedAt = Date.now();
     const lintCtx = await buildReExportLintContext(projectRoot, paths, config, options.noCache === true, new Set(selectedPatches.map((patch) => patch.filename)));
-    let reExported = 0;
-    const reExportedFilenames = [];
-    const failedFilenames = [];
     const progress = spinner('Preparing re-export...');
-    await withDryRunReExportLock(paths.fireforgeDir, isDryRun, async () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, async () => {
-        for (const [index, patch] of selectedPatches.entries()) {
-            const patchOptions = scanOptionsForPatch(options, patch.filename, scanAssignments);
-            progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
-            try {
-                const exported = await reExportSinglePatchWithIndexLockRetry({
-                    patch,
-                    paths,
-                    manifest,
-                    options: patchOptions,
-                    isDryRun,
-                    config,
-                    adjacentCtx,
-                    driftCtx,
-                    lintCtx,
-                });
-                if (exported) {
-                    reExported++;
-                    reExportedFilenames.push(patch.filename);
-                }
-            }
-            catch (error) {
-                failedFilenames.push(patch.filename);
-                warn(`Failed to re-export ${patch.filename}`);
-                warn(toError(error).message);
-            }
-        }
-    }));
+    const outcome = await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportEach({
+        selectedPatches,
+        options,
+        scanAssignments,
+        progress,
+        startedAt,
+        shared: { paths, manifest, isDryRun, config, adjacentCtx, driftCtx, lintCtx },
+    }), { patches: selectedPatches }));
+    const reExportedFilenames = outcome.written;
+    const failedFilenames = outcome.failed;
+    const reExported = reExportedFilenames.length;
     await finishReExportLint(lintCtx);
     warnUnseenExpectedDrift(driftCtx);
     warnUnseenApprovedUnmanaged(adjacentCtx);

package/dist/src/commands/status-output.js

@@ -206,7 +206,11 @@ export function renderTestCoverageStatus(baseline) {
     }
     info(`Last build: ${baseline.builtAt}  (binary: ${baseline.binaryName}, ` +
         `engine HEAD: ${baseline.engineHeadSha || '(unborn)'})`);
-    info(`Recorded by: ${baseline.recordedBy ?? 'unknown'}`);
+    const recorder = baseline.recorder;
+    info(`Recorded by: ${baseline.recordedBy ?? 'unknown'}` +
+        (recorder === undefined
+            ? ''
+            : ` (pid ${recorder.pid}${recorder.sessionId !== undefined ? `, session ${recorder.sessionId}` : ''})`));
     const coverage = baseline.testPackagingCoverage;
     if (coverage === undefined) {
         info('Test packaging coverage: full (implicit — baseline predates coverage recording)');

package/dist/src/commands/test-build-furnace.d.ts

@@ -16,6 +16,7 @@ import type { BuildPreparation } from '../core/build-prepare.js';
  *
  * @param projectRoot - Root directory of the project
  * @param preparation - Result of `prepareBuildEnvironment`
- * @param skipped - True under `--no-furnace-apply`
+ * @param skipped - True under `--no-furnace-apply` / `--furnace-apply none`
+ * @param unreached - Components `--furnace-apply reached` left out
  */
-export declare function reportPreTestFurnace(projectRoot: string, preparation: BuildPreparation, skipped: boolean): Promise<void>;
+export declare function reportPreTestFurnace(projectRoot: string, preparation: BuildPreparation, skipped: boolean, unreached?: readonly string[]): Promise<void>;

package/dist/src/commands/test-build-furnace.js

@@ -20,9 +20,10 @@ import { setVerdictRunAttribute } from './test-verdict.js';
  *
  * @param projectRoot - Root directory of the project
  * @param preparation - Result of `prepareBuildEnvironment`
- * @param skipped - True under `--no-furnace-apply`
+ * @param skipped - True under `--no-furnace-apply` / `--furnace-apply none`
+ * @param unreached - Components `--furnace-apply reached` left out
  */
-export async function reportPreTestFurnace(projectRoot, preparation, skipped) {
+export async function reportPreTestFurnace(projectRoot, preparation, skipped, unreached) {
     if (skipped) {
         setVerdictRunAttribute('furnace-apply', 'skipped');
         let pending = [];
@@ -37,6 +38,11 @@ export async function reportPreTestFurnace(projectRoot, preparation, skipped) {
             : 'Furnace apply skipped (--no-furnace-apply): engine/ is packaged as it stands.');
         return;
     }
+    if (unreached !== undefined && unreached.length > 0) {
+        setVerdictRunAttribute('furnace-skipped', unreached.join(','));
+        notice(`--furnace-apply reached: ${unreached.length} component(s) with undeployed components/ ` +
+            `edits that no requested test reaches are NOT in this build: ${unreached.join(', ')}.`);
+    }
     const applied = preparation.furnaceAppliedNames ?? [];
     if (applied.length === 0)
         return;

package/dist/src/commands/test-build-phase.d.ts

@@ -16,4 +16,6 @@ import type { HarnessClassification } from './test-modes.js';
 export declare function runTestBuildPhase(projectRoot: string, paths: ProjectPaths, projectConfig: FireForgeConfig, harnessRetries: number, options: TestOptions, request: {
     classification: HarnessClassification;
     normalizedPaths: string[];
+    /** Forces a full pre-test build (a compiled negative control). */
+    fullBuildReason?: string;
 }): Promise<boolean>;

package/dist/src/commands/test-build-phase.js

@@ -16,6 +16,7 @@ import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info, notice, spinner, verbose } from '../utils/logger.js';
 import { reportPreTestFurnace } from './test-build-furnace.js';
+import { partitionReachedComponents, resolveFurnaceApplyMode } from './test-furnace-reach.js';
 import { reportBuildOnlyCompletion } from './test-modes.js';
 import { enforceStaleBuildGate, enforceStaticComponentsGate } from './test-stale-gate.js';
 import { emitPassVerdict } from './test-verdict.js';
@@ -26,7 +27,7 @@ import { emitPassVerdict } from './test-verdict.js';
  * @param options - See {@link RunPreTestBuildOptions}
  */
 async function runPreTestBuild(options) {
-    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, skipFurnaceApply, } = options;
+    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, furnace, fullBuildReason, } = options;
     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
@@ -46,9 +47,10 @@ async function runPreTestBuild(options) {
         const preparation = await prepareBuildEnvironment(projectRoot, paths, projectConfig, {
             previousBaseline,
             refuseUnexportedDrift,
-            skipFurnaceApply,
+            skipFurnaceApply: furnace.skip,
+            furnaceComponents: furnace.only,
         });
-        await reportPreTestFurnace(projectRoot, preparation, skipFurnaceApply);
+        await reportPreTestFurnace(projectRoot, preparation, furnace.skip, furnace.unreached);
         // Which earlier claims this scoped build keeps, per staged path. The
         // mozconfig half can only be checked once prepareBuildEnvironment has
         // regenerated engine/mozconfig (the file this build will configure
@@ -64,17 +66,16 @@ async function runPreTestBuild(options) {
             if (retentionNotice !== undefined)
                 notice(retentionNotice);
         }
-        const buildKind = preparation.fullBuildRequired ? 'full' : 'faster';
-        if (preparation.fullBuildRequired) {
+        const fullBuild = preparation.fullBuildRequired || fullBuildReason !== undefined;
+        const buildKind = fullBuild ? 'full' : 'faster';
+        if (fullBuild) {
             // Warning severity rather than info: agent-facing output filters
             // keep warnings and errors only, and this is the line that explains an
             // otherwise unexplained multi-minute build.
-            notice(preparation.fullBuildReason ??
+            notice((preparation.fullBuildRequired ? preparation.fullBuildReason : fullBuildReason) ??
                 'A jar.mn registration changed since the last successful build; escalating this pre-test build to a full mach build so new install-manifest destinations are created.');
         }
-        const s = spinner(preparation.fullBuildRequired
-            ? 'Running required full build...'
-            : 'Running incremental build...');
+        const s = spinner(fullBuild ? 'Running required full build...' : 'Running incremental build...');
         // The pre-test build routes through the same protected mach dispatch as
         // `fireforge build` / `build --ui`: in-venv resource-monitor guard plus
         // the uniform recognized-crash retry budget, with a fresh mach process
@@ -114,7 +115,7 @@ async function runPreTestBuild(options) {
                     ...recorded,
                     previousBaseline,
                     recordedBy: describeBuildInvocation(extend !== undefined, testPackagingCoverage),
-                    staticComponentsHandling: preparation.fullBuildRequired
+                    staticComponentsHandling: fullBuild
                         ? 'refresh'
                         : plan !== undefined && (plan.keepFull || Object.keys(plan.retained).length > 0)
                             ? 'carry-forward'
@@ -129,8 +130,8 @@ async function runPreTestBuild(options) {
         }
         s.error('Pre-test build failed');
         throw new BuildError(result.crashSignature
-            ? buildHarnessCrashMessage(result.crashSignature, result.attempts, 'mach build faster')
-            : 'Pre-test build failed', preparation.fullBuildRequired ? 'mach build' : 'mach build faster');
+            ? buildHarnessCrashMessage(result.crashSignature, result.attempts, fullBuild ? 'mach build' : 'mach build faster')
+            : 'Pre-test build failed', fullBuild ? 'mach build' : 'mach build faster');
     });
 }
 /**
@@ -161,13 +162,28 @@ function assertRefuseUnexportedDriftUsage(options) {
         return;
     throw new InvalidArgumentError('--refuse-unexported-drift requires --build or --build-only: it guards the pre-test build, and this run dispatches none.', '--refuse-unexported-drift');
 }
-/** Refuses `--no-furnace-apply` on a run that dispatches no build, for the same reason. */
+/** Refuses `--no-furnace-apply`/`--furnace-apply` on a run that dispatches no build, for the same reason. */
 function assertNoFurnaceApplyUsage(options) {
-    if (options.furnaceApply !== false)
+    if (options.furnaceApply === undefined || options.furnaceApply === true)
         return;
     if (options.build === true || options.buildOnly === true)
         return;
-    throw new InvalidArgumentError("--no-furnace-apply requires --build or --build-only: it skips the pre-test build's Furnace apply, and this run dispatches no build.", '--no-furnace-apply');
+    const flag = options.furnaceApply === false ? '--no-furnace-apply' : '--furnace-apply';
+    throw new InvalidArgumentError(`${flag} requires --build or --build-only: it shapes the pre-test build's Furnace apply, and this run dispatches no build.`, flag);
+}
+/**
+ * The Furnace part of a pre-test build: skip the apply, apply everything,
+ * or apply only the components the request reaches (and name the rest).
+ */
+async function planPreTestFurnace(projectRoot, paths, projectConfig, options, normalizedPaths) {
+    const mode = resolveFurnaceApplyMode(options, projectConfig);
+    if (mode === 'none')
+        return { skip: true };
+    // A path-less build packages the whole suite, which reaches everything.
+    if (mode === 'all' || normalizedPaths.length === 0)
+        return { skip: false };
+    const { reached, skipped } = await partitionReachedComponents(projectRoot, paths.engine, normalizedPaths);
+    return { skip: false, only: reached, unreached: skipped };
 }
 /** Renders the `recordedBy` invocation string surfaced by `status --test-coverage`. */
 function describeBuildInvocation(extending, coverage) {
@@ -184,7 +200,7 @@ function describeBuildInvocation(extending, coverage) {
  * next steps, and emits the run's single `PASS` verdict.
  */
 export async function runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, request) {
-    const { classification, normalizedPaths } = request;
+    const { classification, normalizedPaths, fullBuildReason } = request;
     const extending = options.extendCoverage === true;
     if (extending) {
         assertExtendCoverageUsage(options, normalizedPaths);
@@ -218,7 +234,8 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
             testPackagingCoverage: coverage,
             refuseUnexportedDrift: options.refuseUnexportedDrift === true,
             extend: extending ? { requestedPaths: normalizedPaths } : undefined,
-            skipFurnaceApply: options.furnaceApply === false,
+            fullBuildReason,
+            furnace: await planPreTestFurnace(projectRoot, paths, projectConfig, options, normalizedPaths),
         });
         info('');
         if (options.buildOnly) {

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

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { findUnownedSupportHeads, formatUnownedSupportHeadNotice, } from '../core/checkjs-support-heads.js';
+import { buildPatchQueueContext } from '../core/patch-lint.js';
 import { runCheckJsTestFilesGrouped } from '../core/patch-lint-checkjs.js';
-import { isTestScriptFile } from '../core/patch-lint-ownership.js';
+import { isTestScriptFile, resolvableModulesForTests } from '../core/patch-lint-ownership.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { analyzeTestPathScopes } from '../core/test-path-scope.js';
 import { GeneralError } from '../errors/base.js';
@@ -24,7 +25,7 @@ export async function checkRequestedTestTypes(paths, config, requested) {
         owned.add(head.file);
         notice(`Pre-build checkJs: ${formatUnownedSupportHeadNotice(head)}`);
     }
-    const result = await runCheckJsTestFilesGrouped(paths.engine, owned, config.patchLint, paths.root, selected);
+    const result = await runCheckJsTestFilesGrouped(paths.engine, owned, config.patchLint, paths.root, selected, resolvableModulesForTests(await buildPatchQueueContext(paths.patches)));
     const issues = [...result.global, ...[...result.byFile.values()].flat()];
     for (const issue of issues)
         notice(`Pre-build checkJs: ${issue.file}: ${issue.message}`);

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

@@ -0,0 +1,39 @@
+/**
+ * The dispatch half of one `fireforge test` run, split out of `test.ts`:
+ * the engine-generation guard around the harness, and the choice between
+ * one combined invocation, per-argument shards, `--shard-size` chunks and
+ * `--jobs` parallel harness instances.
+ */
+import type { PostRebuildFailureContext } from '../core/test-harness-output.js';
+import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type TestRunContext } from './test-run.js';
+import { type ShardGroup } from './test-shards.js';
+/** Everything the dispatch half needs from the run body. */
+export interface TestDispatchInputs {
+    engineDir: string;
+    runCtx: TestRunContext;
+    dispatchGroups: ShardGroup[];
+    options: TestOptions;
+    projectConfig: FireForgeConfig;
+    canaryPath: string | undefined;
+    shuffleSeed: number | undefined;
+    normalizedPaths: string[];
+    xpcshellOnly: boolean;
+    postRebuildContext: PostRebuildFailureContext | undefined;
+}
+/**
+ * Refuses `--jobs`/`--shard-size` shapes that cannot work, before any lock
+ * or build: both need explicit paths and a real dispatch, and parallel
+ * instances cannot share one operator-pinned Marionette port.
+ *
+ * @param testPaths - Requested paths
+ * @param options - Parsed options
+ */
+export declare function assertParallelTestUsage(testPaths: readonly string[], options: TestOptions): void;
+/**
+ * Runs the planned dispatch and finalizes its verdict.
+ *
+ * @param inputs - See {@link TestDispatchInputs}
+ */
+export declare function dispatchTests(inputs: TestDispatchInputs): Promise<void>;

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

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The dispatch half of one `fireforge test` run, split out of `test.ts`:
+ * the engine-generation guard around the harness, and the choice between
+ * one combined invocation, per-argument shards, `--shard-size` chunks and
+ * `--jobs` parallel harness instances.
+ */
+import { createServer } from 'node:net';
+import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
+import { autoPortsRequested } from '../core/harness-port-fallback.js';
+import { extractForwardedMarionettePort } from '../core/marionette-port.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { BuildError } from '../errors/build.js';
+import { notice } from '../utils/logger.js';
+import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
+import { shuffleTestGroups } from './test-harness-env.js';
+import { reportCanaryOutcome } from './test-modes.js';
+import { perfGenerationTolerance, runGenerationTolerance } from './test-perf-scope.js';
+import { runTestsWithRetries } from './test-run.js';
+import { chunkShardGroups, finalizeShardedOutcome, runShardedTests, splitContiguous, } from './test-shards.js';
+import { emitFailVerdict, setVerdictRunAttribute } from './test-verdict.js';
+/**
+ * Refuses `--jobs`/`--shard-size` shapes that cannot work, before any lock
+ * or build: both need explicit paths and a real dispatch, and parallel
+ * instances cannot share one operator-pinned Marionette port.
+ *
+ * @param testPaths - Requested paths
+ * @param options - Parsed options
+ */
+export function assertParallelTestUsage(testPaths, options) {
+    const parallel = (options.jobs ?? 1) > 1;
+    const flags = [
+        ...(parallel ? ['--jobs'] : []),
+        ...(options.shardSize !== undefined ? ['--shard-size'] : []),
+    ];
+    if (flags.length === 0)
+        return;
+    const flag = flags.join('/');
+    if (testPaths.length === 0 || options.canary !== undefined || options.auto === true) {
+        throw new InvalidArgumentError(`${flag} splits explicit test paths, so it needs paths and cannot be combined with --canary or --auto.`, flags[0]);
+    }
+    if (options.buildOnly === true) {
+        throw new InvalidArgumentError(`${flag} shapes a dispatch; --build-only runs none.`, flags[0]);
+    }
+    if (parallel &&
+        (options.marionettePort !== undefined ||
+            extractForwardedMarionettePort(options.machArg ?? []) !== undefined)) {
+        throw new InvalidArgumentError('--jobs gives every harness instance its own Marionette port, so it cannot be combined with a pinned --marionette-port (or a forwarded one).', '--jobs');
+    }
+}
+/**
+ * Verifies `engine/` did not change under the run in a way the run could
+ * see before any PASS verdict may print. On failure the run's verdict is
+ * `FAIL reason=inconclusive`, because the harness result exists but cannot
+ * be trusted (`preflight` would misdescribe a run whose harness already
+ * executed). It is emitted here so the guard's throw can never leave a
+ * stale or missing verdict line behind.
+ */
+async function verifyEngineGenerationOrEmitInconclusive(engineDir, before, inputs) {
+    try {
+        await assertEngineGenerationUnchanged(engineDir, before, inputs.perfSamples === undefined
+            ? runGenerationTolerance(engineDir, inputs.requested, (count) => {
+                setVerdictRunAttribute('drift-tolerated', String(count));
+            })
+            : perfGenerationTolerance(engineDir));
+        if (inputs.powerChanged === true)
+            throw new GeneralError('Perf power source changed during the run; repeat this sitting on a stable power source.');
+    }
+    catch (error) {
+        emitFailVerdict('inconclusive');
+        throw error;
+    }
+}
+/** A free TCP port on the loopback interface, for one harness instance. */
+async function allocateLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address !== null ? address.port : 0;
+            server.close(() => {
+                resolve(port);
+            });
+        });
+    });
+}
+/**
+ * The mochitest harness writes the dispatched test list to
+ * `_tests/testing/mochitest/tests.json` and the browser fetches it from
+ * there, so instances sharing the default name read each other's list (and
+ * one instance's cleanup removes it under the other). Each instance names
+ * its own file.
+ */
+function testRunManifestArg(index) {
+    return `--testrun-manifest-file=fireforge-tests-${process.pid}-job${index + 1}.json`;
+}
+/**
+ * The context for `--jobs` instance `index` (0-based): its own output
+ * prefix and test-list manifest, and from the second instance on its own
+ * Marionette port, so browsers started at the same moment never race for
+ * 2828. The mochitest server ports are left to the engine harness's
+ * busy-port fallback, which `--jobs` requires (auto ports).
+ */
+async function instanceContext(base, index, xpcshellOnly) {
+    const ctx = { ...base, outputPrefix: `[job ${index + 1}] ` };
+    if (xpcshellOnly)
+        return ctx;
+    const own = [...base.baseExtraArgs, testRunManifestArg(index)];
+    if (index === 0)
+        return { ...ctx, baseExtraArgs: own };
+    const port = await allocateLoopbackPort();
+    return {
+        ...ctx,
+        baseExtraArgs: [...own, `--setpref=marionette.port=${port}`, `--marionette=127.0.0.1:${port}`],
+    };
+}
+/** The shards to run, or undefined for one combined invocation. */
+function planShards(inputs) {
+    const { dispatchGroups, options, canaryPath, shuffleSeed } = inputs;
+    if (canaryPath !== undefined)
+        return undefined;
+    const ordered = shuffleSeed === undefined ? dispatchGroups : shuffleTestGroups(dispatchGroups, shuffleSeed);
+    if (options.shardSize !== undefined)
+        return chunkShardGroups(ordered, options.shardSize);
+    const jobs = options.jobs ?? 1;
+    if (jobs > 1 && (options.shard === false || ordered.length === 1)) {
+        return splitContiguous(ordered.flatMap((group) => group.paths), jobs);
+    }
+    if (ordered.length > 1 && options.shard !== false)
+        return ordered;
+    return undefined;
+}
+/**
+ * Runs the planned dispatch and finalizes its verdict.
+ *
+ * @param inputs - See {@link TestDispatchInputs}
+ */
+export async function dispatchTests(inputs) {
+    const { engineDir, runCtx, options, projectConfig, normalizedPaths } = inputs;
+    const jobs = options.jobs ?? 1;
+    if (jobs > 1 && !inputs.xpcshellOnly && !autoPortsRequested(options, projectConfig)) {
+        throw new InvalidArgumentError('--jobs runs several browsers at once, which needs auto ports (--auto-ports or ' +
+            'test.mochitestPorts: "auto") so the harness can move each instance to free server ports.', '--jobs');
+    }
+    const guard = {
+        perfSamples: options.perfSamples,
+        requested: normalizedPaths,
+    };
+    const shards = planShards(inputs);
+    if (shards !== undefined) {
+        notice(describeSharding(shards.length, options, jobs));
+        const base = jobs > 1 ? await instanceContext(runCtx, 0, inputs.xpcshellOnly) : runCtx;
+        if (jobs > 1)
+            setVerdictRunAttribute('jobs', String(jobs));
+        const generationBefore = await snapshotEngineGeneration(engineDir);
+        let summary;
+        try {
+            summary = await runShardedTests(base, shards, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, inputs.postRebuildContext), {
+                jobs,
+                contextFor: (index) => instanceContext(runCtx, index, inputs.xpcshellOnly),
+                perFile: options.shardSize !== undefined,
+            });
+        }
+        finally {
+            // Runs before the aggregate verdict below: a mutated engine/ emits
+            // `FAIL reason=inconclusive` and throws, so an invalidated run can
+            // never print `PASS shards=N/N` first. (A throw here masks an
+            // in-flight shard error, as the plain assert always did.)
+            await verifyEngineGenerationOrEmitInconclusive(engineDir, generationBefore, {
+                ...guard,
+                ...(base.powerChanged === true || runCtx.powerChanged === true
+                    ? { powerChanged: true }
+                    : {}),
+            });
+        }
+        finalizeShardedOutcome(summary);
+        return;
+    }
+    const combinedDispatchPaths = inputs.dispatchGroups.flatMap((group) => group.paths);
+    let outcome;
+    const generationBefore = await snapshotEngineGeneration(engineDir);
+    try {
+        outcome = await runTestsWithRetries(runCtx, combinedDispatchPaths);
+    }
+    catch (error) {
+        throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
+    }
+    finally {
+        await verifyEngineGenerationOrEmitInconclusive(engineDir, generationBefore, {
+            ...guard,
+            ...(runCtx.powerChanged === true ? { powerChanged: true } : {}),
+        });
+    }
+    if (inputs.canaryPath !== undefined) {
+        reportCanaryOutcome(outcome);
+        return;
+    }
+    finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, inputs.postRebuildContext, options.headless === true);
+}
+/**
+ * The sharding notice. The default must not be silent: a cross-file
+ * pollution repro otherwise "passes" because the comparison run was
+ * sharded without saying so, misattributing a suite-context bug upstream.
+ */
+function describeSharding(count, options, jobs) {
+    const instances = jobs > 1 ? ` on ${jobs} harness instances at once (each with its own ports and profile)` : '';
+    if (options.shardSize !== undefined) {
+        return (`Sharding: running ${count} chunk(s) of up to ${options.shardSize} file(s)${instances}, ` +
+            'each chunk one mach invocation with a browser restart between files; results are judged ' +
+            'per file from the structured log.');
+    }
+    if (jobs > 1 && options.shard === false) {
+        return (`Sharding: --jobs splits the combined request into ${count} contiguous chunk(s) in order` +
+            `${instances}. Cross-chunk state is NOT exercised.`);
+    }
+    return (`Sharding: running ${count} test path arguments in isolated browser instances${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.');
+}

package/dist/src/commands/test-furnace-reach.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `fireforge test --build --furnace-apply reached`: deploy only the Furnace
+ * components a requested test reaches.
+ *
+ * The pre-test build's Furnace apply runs over the whole `components/`
+ * tree, so on a shared engine a peer's `test --build` deployed every
+ * session's undeployed component edits into the shared objdir, including
+ * edits another session was holding back for a before-capture. `reached`
+ * keeps the apply to the components the run can observe and names the rest.
+ *
+ * "Reaches" is textual, and errs towards applying: a component is reached
+ * when a requested test file, a `head*.js` beside it, or any test file
+ * under a requested directory names the component's tag, or when the test
+ * path itself names it. A component no test names cannot change what the
+ * run observes through its own code, so leaving its undeployed edit out
+ * keeps the run honest about what it packaged.
+ */
+import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/** The effective Furnace apply mode for a pre-test build. */
+export type FurnaceApplyMode = 'all' | 'reached' | 'none';
+/**
+ * Resolves the mode from the flag and `test.furnaceApply`. `false`
+ * (`--no-furnace-apply`) is `none`.
+ */
+export declare function resolveFurnaceApplyMode(options: TestOptions, config: FireForgeConfig): FurnaceApplyMode;
+/**
+ * The stale components a request reaches, and the stale ones it does not.
+ *
+ * @param projectRoot - Project root
+ * @param engineDir - Absolute engine directory
+ * @param testPaths - Engine-relative requested paths
+ */
+export declare function partitionReachedComponents(projectRoot: string, engineDir: string, testPaths: readonly string[]): Promise<{
+    reached: string[];
+    skipped: string[];
+}>;