@hominis/fireforge 0.52.0 → 0.54.0

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

@@ -3,23 +3,40 @@
  * Re-export prunes a staged registration the queue can no longer satisfy.
  *
  * A merge that deletes a file whose jar.mn line lives in another patch
- * left the staged registration on that patch: re-export kept it, lint then
- * warned `staged-dependency-unused`, and the stale declaration also kept
- * the holder measuring above a just-lowered size ceiling. When no patch in
+ * leaves the staged registration on that patch: lint warns
+ * `staged-dependency-unused`, and the stale declaration keeps the holder
+ * measuring above a just-lowered size ceiling. When no patch in
  * the queue owns a registration's `creates` path any more, the declaration
  * cannot be met, so the holder's own re-export drops it and says so.
+ *
+ * A registration whose `creates` file exists in `engine/`, or is an
+ * `--expect-new` path of the run, is kept: a manifest owner's re-export can
+ * run between declaring the registration and the scan that adopts the
+ * file, and pruning it there would break the scan that needs it next.
  */
+import { join } from 'node:path';
 import { appendHistoryBestEffort } from '../core/history-log.js';
+import { pathExists } from '../utils/fs.js';
 import { info } from '../utils/logger.js';
 /**
- * Finds `patch`'s registrations whose `creates` path no patch in the queue
- * owns, judging `patch` by the file list this re-export will write.
- * Returns undefined when nothing is stale.
+ * The unowned `creates` paths of `patch`'s registrations that are pending
+ * adoption: the file exists in `engine/`, or is an `--expect-new` path of
+ * this run. Such a registration is waiting for its subject patch's scan.
  */
-export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected) {
-    const registrations = patch.stagedDependencies?.registrations ?? [];
-    if (registrations.length === 0)
-        return undefined;
+export async function findPendingRegistrationCreates(engineDir, manifest, patch, currentFilesAffected, expectedNew) {
+    const owned = ownedPaths(manifest, patch, currentFilesAffected);
+    const pending = new Set();
+    for (const registration of patch.stagedDependencies?.registrations ?? []) {
+        const creates = registration.creates;
+        if (owned.has(creates) || pending.has(creates))
+            continue;
+        if (expectedNew.has(creates) || (await pathExists(join(engineDir, creates)))) {
+            pending.add(creates);
+        }
+    }
+    return pending;
+}
+function ownedPaths(manifest, patch, currentFilesAffected) {
     const owned = new Set(currentFilesAffected);
     for (const entry of manifest.patches) {
         if (entry.filename === patch.filename)
@@ -27,10 +44,26 @@ export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected)
         for (const file of entry.filesAffected)
             owned.add(file);
     }
-    const dropped = registrations.filter((registration) => !owned.has(registration.creates));
-    if (dropped.length === 0)
+    return owned;
+}
+/**
+ * Finds `patch`'s registrations whose `creates` path no patch in the queue
+ * owns, judging `patch` by the file list this re-export will write. A
+ * registration whose `creates` path is in `pending` (see
+ * {@link findPendingRegistrationCreates}) is kept and reported instead.
+ * Returns undefined when nothing is stale or pending.
+ */
+export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected, pendingCreates = new Set()) {
+    const registrations = patch.stagedDependencies?.registrations ?? [];
+    if (registrations.length === 0)
         return undefined;
-    const kept = registrations.filter((registration) => owned.has(registration.creates));
+    const owned = ownedPaths(manifest, patch, currentFilesAffected);
+    const unowned = registrations.filter((registration) => !owned.has(registration.creates));
+    const pending = unowned.filter((registration) => pendingCreates.has(registration.creates));
+    const dropped = unowned.filter((registration) => !pendingCreates.has(registration.creates));
+    if (dropped.length === 0 && pending.length === 0)
+        return undefined;
+    const kept = registrations.filter((registration) => !dropped.includes(registration));
     const forwardImports = patch.stagedDependencies?.forwardImports ?? [];
     const staged = {
         ...(forwardImports.length > 0 ? { forwardImports } : {}),
@@ -38,25 +71,36 @@ export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected)
     };
     return {
         dropped,
+        pending,
         stagedDependencies: Object.keys(staged).length > 0 ? staged : undefined,
     };
 }
-/** Names each dropped registration, in both a dry run and a write. */
+/** Names each dropped and each kept-pending registration, in both a dry run and a write. */
 export function reportStaleRegistrationDrop(patchFilename, plan, isDryRun) {
     const verb = isDryRun ? 'would drop' : 'drops';
     for (const registration of plan.dropped) {
         info(`${patchFilename}: ${verb} staged registration ${registration.file} "${registration.line.trim()}": ` +
             `no patch in the queue creates ${registration.creates} any more.`);
     }
+    for (const registration of plan.pending) {
+        info(`${patchFilename}: staged registration ${registration.file} "${registration.line.trim()}" ` +
+            `for ${registration.creates} kept: file exists but no patch owns it yet.`);
+    }
 }
-/** Records the dropped declarations as a delta, like `staged-dependency --remove`. */
-export async function recordStaleRegistrationDrop(patchesDir, patchFilename, plan) {
+/**
+ * Records declarations a re-export pruned from one patch as a delta, like
+ * `staged-dependency --remove`.
+ */
+export async function recordStagedDeclarationPrune(patchesDir, patchFilename, removed, what) {
+    if (removed.length === 0)
+        return;
     await appendHistoryBestEffort(patchesDir, {
         operation: 're-export-staged-prune',
-        args: {
-            filename: patchFilename,
-            removed: plan.dropped.map((registration) => ({ kind: 'registration', ...registration })),
-        },
+        args: { filename: patchFilename, removed: [...removed] },
         result: 'ok',
-    }, `re-export pruned stale staged registrations on ${patchFilename}`);
+    }, `re-export pruned ${what} on ${patchFilename}`);
+}
+/** Records the dropped registrations as a delta, like `staged-dependency --remove`. */
+export async function recordStaleRegistrationDrop(patchesDir, patchFilename, plan) {
+    await recordStagedDeclarationPrune(patchesDir, patchFilename, plan.dropped.map((registration) => ({ kind: 'registration', ...registration })), 'stale staged registrations');
 }

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

@@ -17,6 +17,7 @@ import { reExportFilesInPlace } from './re-export-files.js';
 import { buildReExportLintContext, finishReExportLint } from './re-export-lint.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
 import { validateExpectedRemovals } from './re-export-removed.js';
+import { dropRetiredPathDeclarations } from './re-export-retired-declarations.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';
@@ -190,6 +191,9 @@ export async function reExportCommand(projectRoot, patches, options) {
         progress.error('Re-export failed');
         throw new GeneralError('All selected patches failed to re-export. Check the errors above.');
     }
+    // Declarations on a path this run retired can never be met; drop them
+    // now rather than leave them for the next per-patch lint to report.
+    await dropRetiredPathDeclarations({ paths, manifest, options, selectedPatches, isDryRun });
     // `--stamp` only fires on a run where every selected patch refreshed
     // cleanly. A partial success would leave some patches with a stale body
     // but a new version, the opposite of the "what I tested, what the

package/dist/src/commands/rebase/continue.js

@@ -21,9 +21,9 @@ import { runPatchLoop } from './patch-loop.js';
  */
 export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
     intro('FireForge Rebase — Continue');
-    // A present-but-unreadable session is not "no session in progress". That
-    // conflation is what made a corrupt file unrecoverable. Name the file and
-    // point at --abort, which can now clear it.
+    // A present-but-unreadable session is not "no session in progress":
+    // treating it as one leaves a corrupt file unrecoverable. Name the file
+    // and point at --abort, which can clear it.
     const read = await readRebaseSession(projectRoot);
     if (!read.present)
         throw new NoRebaseSessionError();

package/dist/src/commands/register.js

@@ -32,9 +32,9 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
     }
     // Accept either repo-root-relative (`engine/browser/...`) or
     // engine-relative (`browser/...`) inputs. Operators frequently paste
-    // the former from the output of tab completion or `git status`, and
-    // the mismatch used to produce a "File not found" error that named
-    // the original path with no hint that dropping `engine/` would fix it.
+    // the former from the output of tab completion or `git status`, so
+    // both shapes resolve to the same path instead of a "File not found"
+    // error.
     const engineRelativePath = stripEnginePrefix(filePath);
     // Verify the file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
@@ -97,7 +97,8 @@ export function registerRegister(program, { getProjectRoot, withErrorHandling })
         .command('register <path>')
         .description('Register a file in the appropriate build manifest')
         .option('--dry-run', 'Show what would be changed without writing')
-        .option('--after <entry>', 'Place entry after line containing this substring (instead of alphabetical)')
+        .option('--after <entry>', 'Place entry after line containing this substring (instead of alphabetical); for an ' +
+        'xpcshell test, after the whole section of the xpcshell.toml entry it names')
         .option('--create-manifest', 'Scaffold a missing manifest (directory moz.build with EXTRA_JS_MODULES / XPCSHELL_TESTS_MANIFESTS, or xpcshell.toml) and wire the parent DIRS chain instead of failing with "Manifest not found"')
         .action(withErrorHandling(async (path, options) => {
         await registerCommand(getProjectRoot(), path, pickDefined(options));

package/dist/src/commands/run.js

@@ -130,6 +130,7 @@ async function runInteractive(engineDir, options, profile) {
     const exitCode = await run(engineDir, [
         ...(options.headless ? ['--headless'] : []),
         ...profile.args,
+        ...(options.args ?? []),
     ]);
     // Exit-code whitelist:
     //   0:   clean shutdown
@@ -234,7 +235,12 @@ async function runSmokeExit(engineDir, options, profile) {
     const startedAt = Date.now();
     let result;
     try {
-        const machArgs = ['run', ...(options.headless ? ['--headless'] : []), ...profile.args];
+        const machArgs = [
+            'run',
+            ...(options.headless ? ['--headless'] : []),
+            ...profile.args,
+            ...(options.args ?? []),
+        ];
         result = await runMachSmoke(machArgs, engineDir, {
             smokeTimeoutMs,
             onStdoutLine: (line) => {
@@ -394,6 +400,7 @@ export function registerRun(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('run')
         .description('Launch the built browser')
+        .argument('[args...]', 'Arguments passed to the browser after the profile ones, given after "--" (e.g. -- -marionette -remote-allow-system-access)')
         .option('--smoke-exit <seconds>', 'Smoke-run mode (POSIX only): launch, capture console, SIGTERM the process group after <seconds>. Exit 0 on a clean window, 12 on unallowed errors, 13 on launch failure.', commanderArgParser((value) => {
         const parsed = Number.parseInt(value, 10);
         if (!Number.isFinite(parsed) || parsed < 1 || String(parsed) !== value.trim()) {
@@ -410,8 +417,8 @@ export function registerRun(program, { getProjectRoot, withErrorHandling }) {
         .option('--temp-profile', 'Launch with a fresh temporary profile that is removed when the run ends. The default for --smoke-exit.')
         .action(withErrorHandling(
     // `args` is the variadic positional, not a Commander flag, so it
-    // never appears in this object.
-    async (options) => {
-        await runCommand(getProjectRoot(), pickDefined(options));
+    // arrives apart from the options object.
+    async (args, options) => {
+        await runCommand(getProjectRoot(), pickDefined({ ...options, ...(args.length > 0 ? { args } : {}) }));
     }));
 }

package/dist/src/commands/status.js

@@ -409,7 +409,7 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .option('--fail-on <classifications>', 'Comma-separated classification list that fails --check, replacing the default set (implies --check). Valid: patch-backed, patch-owned-drift, unmanaged, branding, furnace, conflict, binary-unsupported, ownership-conflict (a path claimed by more than one patch)')
         .option('--allow <classifications>', 'Comma-separated classification list that never fails --check, removed from the fail set (implies --check; same values as --fail-on)')
         .option('--fail-on-unknown', 'With --allow: also fail on every present classification that neither --fail-on nor --allow names, so a classification added in a later FireForge fails closed (implies --check)')
-        .option('--patches <names...>', 'Judge only the named patches: keeps the files each owns or claims and the ownership rows naming it (filename, stem, order number, manifest name, or slug; repeat or comma-separate). Unmanaged files belong to no patch and drop out. Default view, --json and --ownership only')
+        .option('--patches <names...>', 'Judge only the named patches: keeps the files each owns or claims and the ownership rows naming it (filename, stem, order number, manifest name, or slug; repeat, or separate with commas or whitespace). Unmanaged files belong to no patch and drop out. Default view, --json and --ownership only')
         .action(withErrorHandling(async (options) => {
         await statusCommand(getProjectRoot(), options);
     }));

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

@@ -3,8 +3,7 @@
  * runs `furnace apply` over the whole `components/` tree, so a
  * `fireforge test --build` meant to capture the committed behaviour could
  * silently ship component edits nobody had deployed yet (another session's
- * included), and nothing in the test output said so. The applied names now
- * ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
+ * included). The applied names therefore ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
  * stands, naming the undeployed edits it left out.
  */
 import type { BuildPreparation } from '../core/build-prepare.js';

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

@@ -4,8 +4,7 @@
  * runs `furnace apply` over the whole `components/` tree, so a
  * `fireforge test --build` meant to capture the committed behaviour could
  * silently ship component edits nobody had deployed yet (another session's
- * included), and nothing in the test output said so. The applied names now
- * ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
+ * included). The applied names therefore ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
  * stands, naming the undeployed edits it left out.
  */
 import { listStaleFurnaceComponents } from '../core/furnace-staleness.js';

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

@@ -3,6 +3,7 @@
  * the per-file line budget): the incremental protected mach build with
  * its baseline write, and the `--build-only` union-build shape.
  */
+import type { ControlBuildStamp } from '../core/build-baseline-types.js';
 import type { TestOptions } from '../types/commands/index.js';
 import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
 import type { HarnessClassification } from './test-modes.js';
@@ -18,4 +19,11 @@ export declare function runTestBuildPhase(projectRoot: string, paths: ProjectPat
     normalizedPaths: string[];
     /** Forces a full pre-test build (a compiled negative control). */
     fullBuildReason?: string;
+    /** Recorded on the pre-test build's baseline (a compiled negative control). */
+    controlBuild?: ControlBuildStamp;
+    /**
+     * Engine-relative launchable binary: anchors the stale-compiled check,
+     * which refuses a build-less run and escalates a `--build` one.
+     */
+    launchablePath?: string | undefined;
 }): Promise<boolean>;

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

@@ -7,10 +7,12 @@
 import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { applyMozconfigAnchor, formatCoverageRetentionNotice, formatExtendCoverageRefusal, planCoverageRetention, recordScopedCoverage, } from '../core/coverage-extend.js';
+import { normalizeRequestPath } from '../core/coverage-records.js';
 import { hasBuildArtifacts } from '../core/mach.js';
 import { runProtectedMachBuild, withBuildLock } from '../core/mach.js';
 import { assertHealthyPartialConfig, pruneDanglingTestLinks } from '../core/objdir-maintenance.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
+import { findCompiledSourcesNewerThanBinary, formatStaleCompiledBuildNotice, } from '../core/test-stale-check.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -27,7 +29,7 @@ import { emitPassVerdict } from './test-verdict.js';
  * @param options - See {@link RunPreTestBuildOptions}
  */
 async function runPreTestBuild(options) {
-    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, furnace, fullBuildReason, } = options;
+    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, furnace, fullBuildReason, controlBuild, } = 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
@@ -121,6 +123,7 @@ async function runPreTestBuild(options) {
                             ? 'carry-forward'
                             : 'auto',
                     buildKind,
+                    controlBuild,
                 });
             }
             catch (baselineError) {
@@ -200,7 +203,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, fullBuildReason } = request;
+    const { classification, normalizedPaths, controlBuild, launchablePath } = request;
     const extending = options.extendCoverage === true;
     if (extending) {
         assertExtendCoverageUsage(options, normalizedPaths);
@@ -213,19 +216,28 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
         // 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) {
+        // Coverage paths are recorded normalized (no trailing slash, no `./`):
+        // the baseline validator refuses the raw `dir/` CLI shape, which would
+        // block every later plain `fireforge test`. A request
+        // for the engine root (`.`) packages everything, so it records `'full'`.
+        const coveragePaths = normalizedPaths.map(normalizeRequestPath);
+        const coverage = coveragePaths.length === 0 || coveragePaths.includes('')
+            ? 'full'
+            : [...new Set(coveragePaths)];
+        if (coverage !== 'full') {
             const previousBaseline = await readBuildBaseline(projectRoot);
             await enforceStaticComponentsGate(paths.engine, previousBaseline, options);
             if (extending) {
                 // Staging-input half of the plan, before the build lock: a refusal
                 // here costs neither build time nor the lock.
-                const plan = await planCoverageRetention(paths.engine, previousBaseline, normalizedPaths);
+                const plan = await planCoverageRetention(paths.engine, previousBaseline, coverage);
                 if (plan.dropped.length > 0) {
                     throw new GeneralError(formatExtendCoverageRefusal(plan.dropped));
                 }
             }
         }
+        const fullBuildReason = request.fullBuildReason ??
+            (await describeCompiledEscalation(projectRoot, paths.engine, launchablePath));
         await runPreTestBuild({
             projectRoot,
             paths,
@@ -233,8 +245,9 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
             harnessRetries,
             testPackagingCoverage: coverage,
             refuseUnexportedDrift: options.refuseUnexportedDrift === true,
-            extend: extending ? { requestedPaths: normalizedPaths } : undefined,
+            extend: extending && coverage !== 'full' ? { requestedPaths: coverage } : undefined,
             fullBuildReason,
+            controlBuild,
             furnace: await planPreTestFurnace(projectRoot, paths, projectConfig, options, normalizedPaths),
         });
         info('');
@@ -249,7 +262,29 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
         }
     }
     else {
-        await enforceStaleBuildGate(projectRoot, paths.engine, options, normalizedPaths);
+        await enforceStaleBuildGate(projectRoot, paths.engine, options, normalizedPaths, {
+            launchablePath,
+        });
     }
     return false;
 }
+/**
+ * Why a `--build` run's pre-test build must be a full `mach build` although
+ * nothing asked for one: compiled sources changed after the binary was
+ * linked, or the binary still carries a negative control a killed run (or a
+ * failed restore build) left compiled in. `mach build faster` compiles
+ * nothing, so either would otherwise survive the build.
+ */
+async function describeCompiledEscalation(projectRoot, engineDir, launchablePath) {
+    const baseline = await readBuildBaseline(projectRoot);
+    const stale = await findCompiledSourcesNewerThanBinary(engineDir, baseline, launchablePath);
+    if (stale !== undefined && stale.paths.length > 0)
+        return formatStaleCompiledBuildNotice(stale);
+    const stamp = baseline?.controlBuild;
+    if (stamp !== undefined) {
+        return (`The binary was built with the negative control ${stamp.diffFile} applied and not ` +
+            'rebuilt since; escalating this pre-test build to a full mach build so it recompiles ' +
+            'the restored source.');
+    }
+    return undefined;
+}

package/dist/src/commands/test-control-restore.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The restore build after a compiled negative control.
+ *
+ * A control on compiled source is applied before a full pre-test build, so
+ * the binary under test carries it. Restoring the source byte-exact after
+ * the run does not unbuild it: the objdir binary keeps the mutation until a
+ * build recompiles the original. Every later `fireforge test` would then
+ * test the control. The orchestrator therefore runs one more full
+ * `mach build` right after a successful restore, still under the same
+ * engine-session hold, and its baseline drops the `controlBuild` stamp the
+ * control's build recorded. When that build fails, or the run never gets
+ * here (killed), the stamp stays and the next `fireforge test` refuses with
+ * `note=control-built` until `fireforge build` replaces it.
+ */
+import type { ControlBuildStamp } from '../core/build-baseline-types.js';
+/** Outcome of {@link runControlRestoreBuild}, stamped as `control-restore-build=`. */
+export type ControlRestoreBuildOutcome = 'done' | 'failed';
+/**
+ * Whether the recorded baseline is the one this run's control build wrote:
+ * only then did a build compile the control in (a failed control build
+ * writes no baseline, and its restored source's fresh mtime trips the
+ * stale-compiled check instead).
+ *
+ * @param projectRoot - Project root
+ * @param stamp - The stamp this run's control build recorded
+ */
+export declare function controlBuildRecorded(projectRoot: string, stamp: ControlBuildStamp): Promise<boolean>;
+/**
+ * Rebuilds the binary after a compiled control was restored: a full
+ * protected `mach build` under the build lock, then a baseline without the
+ * stamp. The previous baseline's packaging-coverage claim is carried
+ * forward unchanged, since recompiling the restored source stages no tests.
+ * Never throws: a failure leaves the stamp in place, which is the refusal
+ * the next run needs.
+ *
+ * @param projectRoot - Project root
+ * @param stamp - The stamp this run's control build recorded
+ * @param harnessRetries - Recognized-crash retry budget for the build
+ */
+export declare function runControlRestoreBuild(projectRoot: string, stamp: ControlBuildStamp, harnessRetries: number | undefined): Promise<ControlRestoreBuildOutcome>;

package/dist/src/commands/test-control-restore.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The restore build after a compiled negative control.
+ *
+ * A control on compiled source is applied before a full pre-test build, so
+ * the binary under test carries it. Restoring the source byte-exact after
+ * the run does not unbuild it: the objdir binary keeps the mutation until a
+ * build recompiles the original. Every later `fireforge test` would then
+ * test the control. The orchestrator therefore runs one more full
+ * `mach build` right after a successful restore, still under the same
+ * engine-session hold, and its baseline drops the `controlBuild` stamp the
+ * control's build recorded. When that build fails, or the run never gets
+ * here (killed), the stamp stays and the next `fireforge test` refuses with
+ * `note=control-built` until `fireforge build` replaces it.
+ */
+import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { runProtectedMachBuild, withBuildLock } from '../core/mach.js';
+import { toError } from '../utils/errors.js';
+import { info, notice, verbose, warn } from '../utils/logger.js';
+/**
+ * Whether the recorded baseline is the one this run's control build wrote:
+ * only then did a build compile the control in (a failed control build
+ * writes no baseline, and its restored source's fresh mtime trips the
+ * stale-compiled check instead).
+ *
+ * @param projectRoot - Project root
+ * @param stamp - The stamp this run's control build recorded
+ */
+export async function controlBuildRecorded(projectRoot, stamp) {
+    const baseline = await readBuildBaseline(projectRoot);
+    return (baseline?.controlBuild?.appliedAt === stamp.appliedAt &&
+        baseline.controlBuild.diffFile === stamp.diffFile);
+}
+/**
+ * Rebuilds the binary after a compiled control was restored: a full
+ * protected `mach build` under the build lock, then a baseline without the
+ * stamp. The previous baseline's packaging-coverage claim is carried
+ * forward unchanged, since recompiling the restored source stages no tests.
+ * Never throws: a failure leaves the stamp in place, which is the refusal
+ * the next run needs.
+ *
+ * @param projectRoot - Project root
+ * @param stamp - The stamp this run's control build recorded
+ * @param harnessRetries - Recognized-crash retry budget for the build
+ */
+export async function runControlRestoreBuild(projectRoot, stamp, harnessRetries) {
+    const paths = getProjectPaths(projectRoot);
+    notice(`Rebuilding after the compiled negative control (${stamp.targets.map((target) => `engine/${target}`).join(', ')}): ` +
+        'the binary still carries the mutation until a full mach build recompiles the restored source.');
+    try {
+        const config = await loadConfig(projectRoot);
+        return await withBuildLock(projectRoot, async () => {
+            const previousBaseline = await readBuildBaseline(projectRoot);
+            const result = await runProtectedMachBuild('full', paths.engine, {
+                ...(harnessRetries === undefined ? {} : { retries: harnessRetries }),
+            });
+            if (result.exitCode !== 0) {
+                warn('The restore build after the negative control failed, so the binary still carries ' +
+                    'the control. The next "fireforge test" refuses (note=control-built) until ' +
+                    '"fireforge build" succeeds.');
+                return 'failed';
+            }
+            await writeBuildBaseline({
+                projectRoot,
+                engineDir: paths.engine,
+                binaryName: config.binaryName,
+                testPackagingCoverage: previousBaseline?.testPackagingCoverage,
+                testCoverageRecords: previousBaseline?.testCoverageRecords,
+                fullCoverageAnchor: previousBaseline?.fullCoverageAnchor,
+                previousBaseline,
+                recordedBy: 'fireforge test --negative-control (restore build)',
+                staticComponentsHandling: 'refresh',
+                buildKind: 'full',
+            });
+            info('Restore build complete: the binary no longer carries the negative control.');
+            return 'done';
+        });
+    }
+    catch (error) {
+        verbose(`Restore build after the negative control failed: ${toError(error).message}`);
+        warn(`The restore build after the negative control could not run (${toError(error).message}). ` +
+            'The next "fireforge test" refuses (note=control-built) until "fireforge build" succeeds.');
+        return 'failed';
+    }
+}

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

@@ -6,11 +6,14 @@
  * `--jobs` parallel harness instances.
  */
 import { createServer } from 'node:net';
+import { join } from 'node:path';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
-import { autoPortsRequested } from '../core/harness-port-fallback.js';
+import { autoPortsRequested, detectHarnessPortFallback } from '../core/harness-port-fallback.js';
+import { reserveHarnessServerPorts, } from '../core/harness-port-reservation.js';
 import { extractForwardedMarionettePort } from '../core/marionette-port.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
+import { ensureDir } from '../utils/fs.js';
 import { notice } from '../utils/logger.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
 import { shuffleTestGroups } from './test-harness-env.js';
@@ -95,15 +98,40 @@ async function allocateLoopbackPort() {
 function testRunManifestArg(index) {
     return `--testrun-manifest-file=fireforge-tests-${process.pid}-job${index + 1}.json`;
 }
+/**
+ * The `MOZ_UPLOAD_DIR` the caller gave this run (its own env first, then
+ * the process environment), or undefined when there is none.
+ */
+function uploadDirBase(base) {
+    const dir = base.env?.['MOZ_UPLOAD_DIR'] ?? process.env['MOZ_UPLOAD_DIR'];
+    return dir === undefined || dir === '' ? undefined : dir;
+}
+/**
+ * `--jobs` instance `index`'s own upload directory, `<base>/job-<n>`. The
+ * harness writes per-run artifacts there under fixed names (the
+ * `modifiedPrefs.json` pref census among them), so instances sharing the
+ * caller's directory replace each other's files.
+ */
+function instanceUploadDir(uploadBase, index) {
+    return join(uploadBase, `job-${index + 1}`);
+}
 /**
  * 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).
+ * prefix, upload directory (when the caller set `MOZ_UPLOAD_DIR`) 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 moved by the engine harness's busy-port
+ * fallback, which `--jobs` requires (auto ports), while
+ * {@link reserveHarnessServerPorts} holds the defaults.
  */
 async function instanceContext(base, index, xpcshellOnly) {
-    const ctx = { ...base, outputPrefix: `[job ${index + 1}] ` };
+    let ctx = { ...base, outputPrefix: `[job ${index + 1}] ` };
+    const uploadBase = uploadDirBase(base);
+    if (uploadBase !== undefined) {
+        const uploadDir = instanceUploadDir(uploadBase, index);
+        await ensureDir(uploadDir);
+        ctx = { ...ctx, env: { ...base.env, MOZ_UPLOAD_DIR: uploadDir } };
+    }
     if (xpcshellOnly)
         return ctx;
     const own = [...base.baseExtraArgs, testRunManifestArg(index)];
@@ -115,6 +143,37 @@ async function instanceContext(base, index, xpcshellOnly) {
         baseExtraArgs: [...own, `--setpref=marionette.port=${port}`, `--marionette=127.0.0.1:${port}`],
     };
 }
+/**
+ * Stamps a `--jobs` run's verdict attributes: `jobs=<n>`, and
+ * `upload-dirs=<dir>,...` naming each instance's upload directory, so a
+ * caller can merge per-instance artifacts.
+ */
+function stampParallelAttributes(runCtx, jobs, shards) {
+    setVerdictRunAttribute('jobs', String(jobs));
+    const uploadBase = uploadDirBase(runCtx);
+    if (uploadBase === undefined)
+        return;
+    const instances = Math.max(1, Math.min(jobs, shards));
+    setVerdictRunAttribute('upload-dirs', Array.from({ length: instances }, (_, index) => instanceUploadDir(uploadBase, index)).join(','));
+}
+/**
+ * Holds the mochitest server ports for a browser run on more than one
+ * instance (see `harness-port-reservation.ts`). Only on an engine whose
+ * harness falls back from a busy server port: without that fallback a
+ * held port would fail every instance instead of moving it.
+ */
+async function reserveParallelServerPorts(engineDir, instances, xpcshellOnly) {
+    if (instances < 2 || xpcshellOnly)
+        return undefined;
+    if (!(await detectHarnessPortFallback(engineDir)).serverPorts)
+        return undefined;
+    const reservation = await reserveHarnessServerPorts();
+    if (reservation.held.length > 0) {
+        notice(`Holding mochitest server port(s) ${reservation.held.join(', ')} for the parallel run, so ` +
+            "each instance's harness moves to server ports of its own.");
+    }
+    return reservation;
+}
 /** The shards to run, or undefined for one combined invocation. */
 function planShards(inputs) {
     const { dispatchGroups, options, canaryPath, shuffleSeed } = inputs;
@@ -152,9 +211,10 @@ export async function dispatchTests(inputs) {
         notice(describeSharding(shards.length, options, jobs));
         const base = jobs > 1 ? await instanceContext(runCtx, 0, inputs.xpcshellOnly) : runCtx;
         if (jobs > 1)
-            setVerdictRunAttribute('jobs', String(jobs));
+            stampParallelAttributes(runCtx, jobs, shards.length);
         const generationBefore = await snapshotEngineGeneration(engineDir);
         let summary;
+        const reservation = await reserveParallelServerPorts(engineDir, Math.min(jobs, shards.length), inputs.xpcshellOnly);
         try {
             summary = await runShardedTests(base, shards, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, inputs.postRebuildContext), {
                 jobs,
@@ -163,6 +223,7 @@ export async function dispatchTests(inputs) {
             });
         }
         finally {
+            await reservation?.release();
             // 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