@hominis/fireforge 0.47.1 → 0.49.0

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

@@ -11,19 +11,20 @@
  * Supports `--continue` (resume after manual fix) and `--abort` (cancel).
  */
 import { Command } from 'commander';
-import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { getProjectPaths, loadConfig, loadState } from '../../core/config.js';
 import { assertEngineGitReady } from '../../core/engine-precondition.js';
 import { clearAppliedFurnaceState } from '../../core/furnace-config.js';
 import { getHead, resetChanges } from '../../core/git.js';
 import { discoverPatches } from '../../core/patch-files.js';
 import { loadPatchesManifest } from '../../core/patch-manifest.js';
 import { getPatchSourceVersion } from '../../core/patch-source-metadata.js';
+import { replayQueueIndexOnly } from '../../core/rebase-dry-run.js';
 import { getRebaseSessionPath, readRebaseSession, saveRebaseSession, } from '../../core/rebase-session.js';
 import { GeneralError } from '../../errors/base.js';
-import { CorruptRebaseSessionError, RebaseSessionExistsError } from '../../errors/rebase.js';
-import { info, intro, outro, spinner } from '../../utils/logger.js';
+import { CorruptRebaseSessionError, RebaseDryRunRejectError, RebaseSessionExistsError, } from '../../errors/rebase.js';
+import { info, intro, outro, spinner, warn } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
-import { parsePositiveIntegerFlag } from '../../utils/validation.js';
+import { compareFirefoxVersions, parsePositiveIntegerFlag } from '../../utils/validation.js';
 import { handleAbort } from './abort.js';
 import { confirmDirtyEngineReset } from './confirm.js';
 import { handleContinue } from './continue.js';
@@ -57,23 +58,51 @@ async function handleFreshStart(projectRoot, options) {
     if (!manifest || manifest.patches.length === 0) {
         throw new GeneralError('No patches found in manifest. Nothing to rebase.');
     }
-    // Determine the "from" version from the patches
-    const patchVersions = new Set(manifest.patches.map((p) => getPatchSourceVersion(p)));
-    const patchProducts = new Set(manifest.patches.map((p) => p.sourceProduct).filter(Boolean));
-    const sortedVersions = [...patchVersions].sort();
+    // Determine the "from" version from the patch stamps. A queue can carry
+    // several: patches re-exported since the last hop are stamped newer than
+    // untouched ones. The oldest stamp is "from", compared semantically (a
+    // lexical sort put 153.10.0esr before 153.2.0esr).
+    const versionCounts = new Map();
+    for (const patch of manifest.patches) {
+        const version = getPatchSourceVersion(patch);
+        versionCounts.set(version, (versionCounts.get(version) ?? 0) + 1);
+    }
+    const sortedVersions = [...versionCounts.keys()].sort(compareFirefoxVersions);
     const fromVersion = sortedVersions[0] ?? currentVersion;
-    const fromProduct = [...patchProducts].sort()[0] ?? config.firefox.product;
-    if (patchVersions.size === 1 && fromVersion === currentVersion) {
+    const fromProduct = manifest.patches.find((p) => getPatchSourceVersion(p) === fromVersion)?.sourceProduct ??
+        config.firefox.product;
+    if (versionCounts.size === 1 && fromVersion === currentVersion) {
         info('All patches already match the current Firefox version. Nothing to rebase.');
         outro('Rebase not needed');
         return;
     }
     info(`Rebasing patches: ${fromVersion} → ${currentVersion}`);
+    if (versionCounts.size > 1) {
+        info(`Patch stamps: ${sortedVersions.map((v) => `${versionCounts.get(v)} at ${v}`).join(', ')}`);
+    }
+    // The rebase replays onto whatever engine/ holds. The pin is the target,
+    // so an engine still on another version means the download step has not
+    // run yet and every verdict below would be against the wrong tree.
+    const engineVersion = (await loadState(projectRoot)).downloadedVersion;
+    if (engineVersion !== undefined && engineVersion !== currentVersion) {
+        warn(`engine/ holds ${engineVersion}, not the pinned target ${currentVersion}. ` +
+            'Run "fireforge download --force" first, or the rebase applies onto the old source.');
+    }
     info(`Found ${manifest.patches.length} patch(es)`);
     info(`Max context-reduction steps (fuzz-like): ${maxFuzz}`);
     if (isDryRun) {
-        info('[dry-run] Would reset engine, apply patches with context reduction, and re-export.');
-        outro('Dry run complete');
+        const patches = await discoverPatches(paths.patches);
+        const replaySpinner = spinner(`Replaying ${patches.length} patch(es) on a private index...`);
+        let replay;
+        try {
+            replay = await replayQueueIndexOnly(paths.engine, patches, maxFuzz);
+            replaySpinner.stop('Replay finished; engine/ untouched');
+        }
+        catch (error) {
+            replaySpinner.error('Replay failed');
+            throw error;
+        }
+        reportDryRunReplay(replay);
         return;
     }
     if (!(await confirmDirtyEngineReset({
@@ -114,6 +143,41 @@ async function handleFreshStart(projectRoot, options) {
     // Run the patch loop
     await runPatchLoop(projectRoot, session, paths, maxFuzz, resolveWaitLockSeconds(options.waitLock));
 }
+/**
+ * Prints one line per patch and a tally, then fails the run when any patch
+ * rejects: a dry run that exits 0 must mean the real rebase would apply the
+ * whole queue.
+ */
+function reportDryRunReplay(replay) {
+    let reduced = 0;
+    const rejected = [];
+    for (const [index, verdict] of replay.verdicts.entries()) {
+        const cascade = replay.firstRejectIndex !== undefined && index > replay.firstRejectIndex
+            ? ' (after an earlier reject; may cascade from it)'
+            : '';
+        switch (verdict.outcome) {
+            case 'clean':
+                info(`  clean            ${verdict.filename}`);
+                break;
+            case 'reduced-context':
+                reduced += 1;
+                info(`  reduced context  ${verdict.filename} (step ${verdict.step}, ${verdict.contextArg})`);
+                break;
+            case 'reject': {
+                rejected.push(verdict.filename);
+                const files = verdict.files.length > 0 ? verdict.files.join(', ') : 'see git output';
+                warn(`  reject           ${verdict.filename}: ${files}${cascade}`);
+                break;
+            }
+        }
+    }
+    const clean = replay.verdicts.length - reduced - rejected.length;
+    info(`[dry-run] ${replay.verdicts.length} patch(es): ${clean} clean, ${reduced} with reduced context, ${rejected.length} rejected.`);
+    if (rejected.length > 0) {
+        throw new RebaseDryRunRejectError(rejected);
+    }
+    outro('Dry run complete: every patch applies');
+}
 // ── Public API ──
 /**
  * Runs the rebase command to orchestrate a Firefox source version upgrade.
@@ -136,7 +200,7 @@ export function registerRebase(program, { getProjectRoot, withErrorHandling }) {
         .description('Semi-automated Firefox source version upgrade — apply patches with drift tolerance and re-export')
         .option('--continue', 'Resume after manually resolving a failed patch')
         .option('--abort', 'Cancel the rebase and restore engine to pre-rebase state')
-        .option('--dry-run', 'Show what would happen without modifying anything')
+        .option('--dry-run', 'Replay the queue onto the engine base commit in a private index and report each patch as clean, reduced-context or reject (exit 6 on any reject); engine/ is not touched')
         .option('--max-fuzz <n>', 'Maximum context-reduction steps for git apply -C<n> (fuzz-like drift tolerance; default: 3)', commanderArgParser((v) => parsePositiveIntegerFlag('--max-fuzz', v)))
         .option('-y, --yes', 'Skip dirty-tree confirmation prompt');
     addWaitLockOption(command).action(withErrorHandling(async (options) => {

package/dist/src/commands/run.js

@@ -8,6 +8,7 @@ import { assertEngineExists } from '../core/engine-precondition.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { hasBuildArtifacts, hasRunnableBundle, run, runMachSmoke } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
+import { resolveRunProfile, sweepAbandonedRunProfiles, } from '../core/run-profile.js';
 import { compileAllowlistFromFile, compileAllowlistFromStrings, findOverCapAllowlistEntries, matchAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
@@ -97,12 +98,38 @@ export async function runCommand(projectRoot, options = {}) {
     await warnIfFurnaceStale(projectRoot);
     // Clean stale profile state to prevent silent startup failures
     await cleanDevProfile(paths.engine);
-    if (options.smokeExit !== undefined) {
-        await runSmokeExit(paths.engine, options);
-        return;
+    // Reclaim temporary profiles a SIGKILLed FireForge could not remove.
+    const swept = await sweepAbandonedRunProfiles();
+    if (swept > 0)
+        verbose(`Removed ${swept} abandoned temporary run profile(s).`);
+    const profile = await resolveRunProfile({
+        profile: options.profile,
+        tempProfile: options.tempProfile,
+        smoke: options.smokeExit !== undefined,
+    });
+    try {
+        if (options.smokeExit !== undefined) {
+            await runSmokeExit(paths.engine, options, profile);
+            return;
+        }
+        info('Launching browser...\n');
+        await runInteractive(paths.engine, options, profile);
+    }
+    finally {
+        await profile.dispose();
     }
-    info('Launching browser...\n');
-    const exitCode = await run(paths.engine, options.headless ? ['--headless'] : []);
+}
+/**
+ * Launches the browser under `mach run` for an interactive session.
+ * @param engineDir - Path to the engine directory
+ * @param options - Run options
+ * @param profile - The profile this run launches with
+ */
+async function runInteractive(engineDir, options, profile) {
+    const exitCode = await run(engineDir, [
+        ...(options.headless ? ['--headless'] : []),
+        ...profile.args,
+    ]);
     // Exit-code whitelist:
     //   0:   clean shutdown
     //   130: SIGINT (Ctrl+C), user-initiated termination
@@ -121,7 +148,7 @@ export async function runCommand(projectRoot, options = {}) {
  * exit contract. The deadline-fires-SIGTERM path is treated as a clean
  * window iff no unallowed errors were observed.
  */
-async function runSmokeExit(engineDir, options) {
+async function runSmokeExit(engineDir, options, profile) {
     // Windows lacks the POSIX process-group primitives --smoke-exit leans on to
     // SIGTERM the whole mach → python → firefox tree. Running through anyway
     // would only kill the top-level wrapper and orphan Firefox content
@@ -194,10 +221,17 @@ async function runSmokeExit(engineDir, options) {
     };
     warnIfHeadedOnDesktop(options.headless === true);
     info(`Launching browser (smoke-exit after ${smokeExit}s)...\n`);
+    if (profile.temporary) {
+        info(`Profile: fresh temporary profile (removed after the run; --profile <path> to use a named one)`);
+    }
+    else if (profile.dir !== undefined) {
+        info(`Profile: ${profile.dir}`);
+    }
     const startedAt = Date.now();
     let result;
     try {
-        result = await runMachSmoke(options.headless ? ['run', '--headless'] : ['run'], engineDir, {
+        const machArgs = ['run', ...(options.headless ? ['--headless'] : []), ...profile.args];
+        result = await runMachSmoke(machArgs, engineDir, {
             smokeTimeoutMs,
             onStdoutLine: (line) => {
                 handleLine('stdout', line);
@@ -358,6 +392,8 @@ export function registerRun(program, { getProjectRoot, withErrorHandling }) {
         .option('--console-allow-file <path>', 'Newline-delimited allowlist regex file. Blank lines and # comments are ignored. A "# max-hits: N" comment directly above an entry caps how many lines it may match in one run; more than that fails the run with exit 12.')
         .option('--capture-console <file>', 'Mirror captured console output to <file> for post-exit inspection.')
         .option('--headless', 'Launch the browser with --headless. Recommended for --smoke-exit on a shared desktop: input into a headed smoke window contaminates the console capture.')
+        .option('--profile <path>', 'Launch with this profile directory (passed to Firefox as -profile). Left in place after the run. With --smoke-exit it replaces the default fresh profile.')
+        .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.

package/dist/src/commands/status.js

@@ -6,7 +6,7 @@ import { assertEngineExists } from '../core/engine-precondition.js';
 import { formatEngineSessionLockStatus, readEngineSessionLockStatus, } from '../core/engine-session-lock.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
-import { getUntrackedFilesInDir, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
+import { listUntrackedFilesInDirs, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
 import { renderOwnershipTable } from '../core/ownership-table.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { readProcessCpuSeconds } from '../core/process-cpu-time.js';
@@ -49,9 +49,11 @@ function renderTruncationBanner(truncations) {
 async function expandDirectoryEntries(files, engineDir) {
     const expanded = [];
     const truncations = [];
+    const isCollapsedUntracked = (entry) => entry.file.endsWith('/') && entry.status.includes('?');
+    const untrackedByDir = await listUntrackedFilesInDirs(engineDir, files.filter(isCollapsedUntracked).map((entry) => entry.file));
     for (const entry of files) {
-        if (entry.file.endsWith('/') && entry.status.includes('?')) {
-            const individualFiles = await getUntrackedFilesInDir(engineDir, entry.file);
+        if (isCollapsedUntracked(entry)) {
+            const individualFiles = untrackedByDir.get(entry.file) ?? [];
             const cap = getMaxUntrackedFilesPerDir();
             if (individualFiles.length > cap) {
                 // Recorded once here, reported once by renderTruncationBanner. The

package/dist/src/commands/test-browser-preflight.d.ts

@@ -0,0 +1,28 @@
+import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Runs the `--doctor` marionette handshake probe. With no test paths the
+ * probe is the entire command (returns `'stop'` after reporting). With
+ * paths it gates the mach invocation, where a FAIL throws before mach runs.
+ */
+export declare function runDoctorPreflight(args: {
+    engineDir: string;
+    effectivePort: number | undefined;
+    hasTestPaths: boolean;
+    objDir: string | undefined;
+    binaryName: string;
+    launchablePath: string | undefined;
+}): Promise<'stop' | 'continue'>;
+/**
+ * Auto-forwards `--marionette-port` to mach (`--setpref=marionette.port`
+ * for the listener, `--marionette=127.0.0.1:<n>` for the mochitest
+ * client), skipping each piece the operator already forwarded via
+ * `--mach-arg` and the xpcshell flavor that ignores the pref entirely.
+ * Mutates `extraArgs` in place.
+ */
+export declare function appendMarionetteForwardingArgs(extraArgs: string[], options: TestOptions, forwardedPort: number | undefined, xpcshellOnly?: boolean): void;
+/** Prepares profile overlays and browser/port ownership preconditions. */
+export declare function ensureTestBrowserEnvironment(engineDir: string, launchablePath: string | undefined, xpcshellOnly: boolean, projectConfig: FireForgeConfig, options: TestOptions, objDir: string | undefined): Promise<{
+    forwardedPort: number | undefined;
+    effectivePort: number | undefined;
+}>;

package/dist/src/commands/test-browser-preflight.js

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { reportOrphanedHarnessProcesses } from '../core/harness-orphans.js';
+import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
+import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
+import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
+import { waitForPreflight } from '../core/preflight-wait.js';
+import { GeneralError } from '../errors/base.js';
+import { info, outro, verbose } from '../utils/logger.js';
+import { resolveWaitLockSeconds } from '../utils/options.js';
+import { addVerdictRunCount, emitFailVerdict, emitPassVerdict } from './test-verdict.js';
+/**
+ * Runs the `--doctor` marionette handshake probe. With no test paths the
+ * probe is the entire command (returns `'stop'` after reporting). With
+ * paths it gates the mach invocation, where a FAIL throws before mach runs.
+ */
+export async function runDoctorPreflight(args) {
+    const { engineDir, effectivePort, hasTestPaths, objDir, binaryName, launchablePath } = args;
+    // Non-TTY captures need the banner even if clack's renderer defers output
+    // in pipe mode. TTY users need the clack framing. Gated rather than
+    // written twice: the unconditional pair printed the same line twice on a
+    // terminal.
+    if (process.stdout.isTTY) {
+        info('Running marionette preflight...');
+    }
+    else {
+        process.stdout.write('Running marionette preflight...\n');
+    }
+    const preflight = effectivePort !== undefined
+        ? await runMarionettePreflight(engineDir, { port: effectivePort })
+        : await runMarionettePreflight(engineDir);
+    // The authoritative PASS/FAIL line is written with `process.stdout.write`
+    // as the first output after the probe returns, because clack's renderer
+    // can drop the summary under non-TTY capture.
+    //
+    // Gated on non-TTY: unconditional, it stacks with the two clack renderings
+    // below and the same line appears three times on a terminal. Captured
+    // streams are exactly where this branch still fires.
+    const directLine = formatMarionettePreflightLine(preflight);
+    if (!process.stdout.isTTY) {
+        process.stdout.write(`${directLine}\n`);
+    }
+    process.stdout.write(`Marionette preflight environment: objdir=${objDir ?? '(none)'}; binary=${binaryName}; app=${launchablePath ? `engine/${launchablePath}` : '(unknown)'}; port=${effectivePort ?? 2828}; elapsed=${preflight.durationMs}ms\n`);
+    reportMarionettePreflight(preflight);
+    if (!hasTestPaths) {
+        if (!preflight.ok) {
+            emitFailVerdict('preflight');
+            throw new GeneralError('Marionette preflight reported FAIL — see output above.');
+        }
+        // Doctor-only runs end here, so they carry their own verdict line
+        // (reason=preflight on failure). With test paths the verdict comes
+        // from the actual harness run downstream.
+        emitPassVerdict();
+        outro('Test completed');
+        return 'stop';
+    }
+    if (!preflight.ok) {
+        emitFailVerdict('preflight');
+        throw new GeneralError('Marionette preflight reported FAIL — see output above. Aborting before mach test runs.');
+    }
+    return 'continue';
+}
+/**
+ * Auto-forwards `--marionette-port` to mach (`--setpref=marionette.port`
+ * for the listener, `--marionette=127.0.0.1:<n>` for the mochitest
+ * client), skipping each piece the operator already forwarded via
+ * `--mach-arg` and the xpcshell flavor that ignores the pref entirely.
+ * Mutates `extraArgs` in place.
+ */
+export function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly = false) {
+    // Auto-forward the Marionette port to mach when `--marionette-port` is set.
+    // `--setpref=marionette.port=<n>` configures where the browser listener
+    // binds. `--marionette=127.0.0.1:<n>` tells the mochitest harness client to
+    // connect there (default client is 127.0.0.1:2828). xpcshell ignores both
+    // for browser Marionette.
+    //
+    // Skip setpref forwarding when the operator already supplied an equivalent
+    // arg via `--mach-arg`: duplicates would confuse without changing
+    // semantics. Skip when mach args explicitly request `--flavor=xpcshell` (or
+    // `xpcshell-tests`): the preflight still honours `--marionette-port`, but
+    // mach does not use the marionette.port pref on that harness. Any other arg
+    // shape still forwards so toolkit widget paths and mixed suites stay
+    // aligned with the probe without duplicate `--mach-arg` flags.
+    //
+    // Skip auto `--marionette=...` when `--mach-arg` already includes a client
+    // `--marionette=...` (or two-token `--marionette host:port`).
+    if (options.marionettePort === undefined)
+        return;
+    if (xpcshellOnly) {
+        // Manifest classification says every requested path is xpcshell.
+        // xpcshell ignores the browser Marionette path entirely, and forwarding
+        // the mochitest client flags here makes mach reject the dispatch.
+        info(`--marionette-port=${options.marionettePort} applied to the preflight probe only: the requested paths are xpcshell-only, and xpcshell ignores the browser Marionette port. Not forwarding --setpref=marionette.port or --marionette to mach.`);
+        return;
+    }
+    {
+        const operatorAlreadyForwarded = forwardedPort !== undefined;
+        const machArgs = options.machArg ?? [];
+        if (operatorAlreadyForwarded) {
+            info(`--marionette-port=${options.marionettePort} set, but the same port is already forwarded via --mach-arg; skipping auto-forward.`);
+        }
+        else if (shouldAutoForwardMarionettePortToMach(machArgs)) {
+            extraArgs.push(`--setpref=marionette.port=${options.marionettePort}`);
+        }
+        else {
+            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but --flavor=xpcshell is set — mach is not auto-configured with --setpref=marionette.port or --marionette (xpcshell ignores the browser Marionette path). Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if you still need mach to see the port.`);
+        }
+        if (shouldAutoForwardMarionettePortToMach(machArgs) &&
+            !forwardedMachArgsIncludeMarionetteClient(machArgs)) {
+            extraArgs.push(`--marionette=127.0.0.1:${options.marionettePort}`);
+        }
+    }
+}
+async function ensureTestMarionettePortAvailable(port, binaryName, options, skip) {
+    // Refuse a stale listener before mach surfaces a generic bind failure.
+    // This also recognizes a fork-branded browser via binaryName.
+    if (skip.xpcshellOnly && !skip.doctor) {
+        // xpcshell does not bind the browser Marionette port, so a developer's
+        // interactive browser holding 2828 must not kill an xpcshell run.
+        // --doctor keeps the preflight: its probe launches a
+        // Marionette browser regardless of the requested harness.
+        const message = 'Skipping the Marionette stale-port preflight: all requested paths are xpcshell ' +
+            '(xpcshell does not bind the browser Marionette port).';
+        if (options.marionettePort !== undefined || options.killStaleMarionette === true) {
+            info(message);
+        }
+        else {
+            verbose(message);
+        }
+        return;
+    }
+    if (options.killStaleMarionette === true) {
+        await ensureMarionettePortAvailable(port, { binaryName, killStaleBrowser: true });
+        return;
+    }
+    await assertMarionettePortAvailable(port, { binaryName });
+}
+/** Prepares profile overlays and browser/port ownership preconditions. */
+export async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellOnly, projectConfig, options, objDir) {
+    // A timed-out mochitest can leave the built app alive after its Marionette
+    // listener has disappeared. The port probe cannot see that case, but the
+    // survivor can still steal focus and wedge every later headed run.
+    if (!xpcshellOnly && launchablePath) {
+        await waitForPreflight(() => ensureLaunchableBrowserNotRunning(join(engineDir, launchablePath), {
+            killStaleBrowser: options.killStaleMarionette === true,
+        }), options.waitBrowser === undefined ? undefined : resolveWaitLockSeconds(options.waitBrowser));
+    }
+    // Packaging-only runs must protect a running objdir, but do not bind any
+    // harness ports or launch tests, so peer listeners cannot block packaging.
+    if (options.buildOnly)
+        return { forwardedPort: undefined, effectivePort: undefined };
+    // A zombie mochitest httpd squatting the server port makes a fresh
+    // browser connect to a server that cannot serve this run's manifest,
+    // which surfaces as a 370s "Ran 0 checks" stall naming nothing. xpcshell
+    // does not use the httpd, so an xpcshell-only run is never blocked by it.
+    if (!xpcshellOnly) {
+        await waitForPreflight(() => ensureMochitestServerPortAvailable(undefined, {
+            engineDir,
+            killStaleServer: options.killStaleMarionette === true,
+        }), options.waitPort === undefined ? undefined : resolveWaitLockSeconds(options.waitPort));
+    }
+    // Helpers that outlived an earlier run (httpd, pywebsocket, ssltunnel,
+    // moz-http2) slow every later run without appearing in its output. Both
+    // harnesses are affected, so this census is not gated on xpcshellOnly.
+    // Reaping is opt-in per invocation (--reap-orphans) or per repo
+    // (test.reapOrphans: "reap"); a reap is stamped on the verdict line so a
+    // green after one is not mistaken for a green on a quiet machine.
+    const census = await reportOrphanedHarnessProcesses(objDir, {
+        reap: options.reapOrphans === true || projectConfig.test?.reapOrphans === 'reap',
+    });
+    addVerdictRunCount('orphans-reaped', census.reaped);
+    const forwardedPort = options.machArg
+        ? extractForwardedMarionettePort(options.machArg)
+        : undefined;
+    const effectivePort = options.marionettePort ?? forwardedPort;
+    await waitForPreflight(() => ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options, {
+        xpcshellOnly,
+        doctor: options.doctor === true,
+    }), options.waitPort === undefined ? undefined : resolveWaitLockSeconds(options.waitPort));
+    return { forwardedPort, effectivePort };
+}

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

@@ -7,12 +7,15 @@
 import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { checkExtendCoverageAnchor, checkExtendMozconfigAnchor, formatExtendCoverageRefusal, unionTestPackagingCoverage, } from '../core/coverage-extend.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 { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info, notice, spinner, verbose } from '../utils/logger.js';
+import { checkRequestedTestTypes } from './test-checkjs.js';
 import { reportBuildOnlyCompletion } from './test-modes.js';
 import { enforceStaleBuildGate, enforceStaticComponentsGate } from './test-stale-gate.js';
 import { emitPassVerdict } from './test-verdict.js';
@@ -31,6 +34,14 @@ async function runPreTestBuild(options) {
         // `mach build faster` would: a failed pre-test build followed by a full
         // rebuild is an hour where an incremental one would have sufficed.
         const previousBaseline = await readBuildBaseline(projectRoot);
+        const artifacts = await hasBuildArtifacts(paths.engine);
+        if (artifacts.objDir) {
+            await assertHealthyPartialConfig(paths.engine, artifacts.objDir);
+            const pruned = await pruneDanglingTestLinks(paths.engine, artifacts.objDir);
+            if (pruned > 0)
+                notice(`Pruned ${pruned} dangling _tests symlink(s).`);
+        }
+        await checkRequestedTestTypes(paths, projectConfig, testPackagingCoverage === 'full' ? [] : testPackagingCoverage);
         const preparation = await prepareBuildEnvironment(projectRoot, paths, projectConfig, {
             previousBaseline,
             refuseUnexportedDrift,
@@ -39,10 +50,22 @@ async function runPreTestBuild(options) {
         // only be checked once prepareBuildEnvironment has regenerated
         // engine/mozconfig (the file this build will configure with), and must
         // still be checked before mach, so a refusal costs no build.
-        if (extend !== undefined) {
+        let retainCoverage = false;
+        if (testPackagingCoverage !== 'full' && previousBaseline) {
+            const anchor = await checkExtendCoverageAnchor(paths.engine, previousBaseline, testPackagingCoverage);
             const mozconfigAnchor = await checkExtendMozconfigAnchor(paths.engine, previousBaseline);
-            if (!mozconfigAnchor.ok) {
-                throw new GeneralError(formatExtendCoverageRefusal(mozconfigAnchor));
+            retainCoverage =
+                anchor.ok && mozconfigAnchor.ok && previousBaseline.testInputFingerprints !== undefined;
+            if (extend !== undefined && (!anchor.ok || !mozconfigAnchor.ok)) {
+                throw new GeneralError(formatExtendCoverageRefusal(!anchor.ok ? anchor : mozconfigAnchor));
+            }
+            if (!retainCoverage) {
+                const old = previousBaseline.testPackagingCoverage;
+                const dropped = old === undefined || old === 'full'
+                    ? ['full coverage outside this scope']
+                    : old.filter((file) => !testPackagingCoverage.includes(file));
+                if (dropped.length)
+                    notice(`Scoped build drops previous packaging coverage: ${dropped.join(', ')}. Earlier staging inputs changed or have no complete fingerprint anchor; rebuild those paths together to retain them.`);
             }
         }
         const buildKind = preparation.fullBuildRequired ? 'full' : 'faster';
@@ -85,8 +108,8 @@ async function runPreTestBuild(options) {
                 // is always carried forward: that union can evaluate to 'full'
                 // while the build behind it was a scoped `mach build faster` that
                 // did not rebake the compiled table.
-                const recordedCoverage = extend !== undefined
-                    ? unionTestPackagingCoverage(previousBaseline?.testPackagingCoverage, extend.requestedPaths)
+                const recordedCoverage = retainCoverage
+                    ? unionTestPackagingCoverage(previousBaseline?.testPackagingCoverage, testPackagingCoverage === 'full' ? [] : testPackagingCoverage)
                     : testPackagingCoverage;
                 await writeBuildBaseline({
                     projectRoot,
@@ -97,7 +120,7 @@ async function runPreTestBuild(options) {
                     recordedBy: describeBuildInvocation(extend !== undefined, testPackagingCoverage),
                     staticComponentsHandling: preparation.fullBuildRequired
                         ? 'refresh'
-                        : extend !== undefined
+                        : retainCoverage
                             ? 'carry-forward'
                             : 'auto',
                     buildKind,
@@ -176,7 +199,7 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
             if (extending) {
                 // Head/fingerprint half of the anchor, before the build lock: a
                 // refusal here costs neither build time nor the lock.
-                const anchor = await checkExtendCoverageAnchor(paths.engine, previousBaseline);
+                const anchor = await checkExtendCoverageAnchor(paths.engine, previousBaseline, normalizedPaths);
                 if (!anchor.ok) {
                     throw new GeneralError(formatExtendCoverageRefusal(anchor));
                 }

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

@@ -0,0 +1,3 @@
+import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
+/** Runs the configured patch test checkJs pass before paying for a proving build. */
+export declare function checkRequestedTestTypes(paths: ProjectPaths, config: FireForgeConfig, requested: string[]): Promise<void>;

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

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { runCheckJsTestFilesGrouped } from '../core/patch-lint-checkjs.js';
+import { isTestScriptFile } 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';
+import { notice } from '../utils/logger.js';
+/** Runs the configured patch test checkJs pass before paying for a proving build. */
+export async function checkRequestedTestTypes(paths, config, requested) {
+    if (config.patchLint?.checkJs !== true ||
+        config.patchLint.checkJsTestFiles !== true ||
+        requested.length === 0)
+        return;
+    const manifest = await loadPatchesManifest(paths.patches);
+    const owned = new Set(manifest?.patches.flatMap((patch) => patch.filesAffected.filter(isTestScriptFile)) ?? []);
+    const scopes = await analyzeTestPathScopes(paths.engine, requested);
+    const selected = new Set(scopes.flatMap((scope) => scope.dispatchPaths.filter(isTestScriptFile)));
+    for (const file of selected)
+        owned.add(file);
+    const result = await runCheckJsTestFilesGrouped(paths.engine, owned, config.patchLint, paths.root, selected);
+    const issues = [...result.global, ...[...result.byFile.values()].flat()];
+    for (const issue of issues)
+        notice(`Pre-build checkJs: ${issue.file}: ${issue.message}`);
+    if (issues.some((issue) => issue.severity === 'error')) {
+        throw new GeneralError('Named test files failed the configured patch checkJs pass before build. Fix the type errors above before running the proof.');
+    }
+}

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

@@ -143,6 +143,9 @@ verdict) {
     if (result.exitCode === 0 || result.exitCode === 130)
         return;
     const combinedOutput = `${result.stdout}\n${result.stderr}`;
+    if (/copyExtraFilesToProfile/.test(combinedOutput) && /FileExistsError/.test(combinedOutput)) {
+        throw new GeneralError('Harness argument failure: --extra-profile-file collided with the existing profile directory. Use --profile-file source=chrome/userChrome.css to merge an individual file; rebuilding does not repair this argument.');
+    }
     const failureContext = postRebuildContext
         ? completePostRebuildFailureContext(postRebuildContext, combinedOutput)
         : undefined;

package/dist/src/commands/test-harness-env.d.ts

@@ -11,14 +11,13 @@ export declare function buildPerfSampleEnv(projectRoot: string, binaryName: stri
  */
 export declare function mergeHarnessEnv(...parts: (Record<string, string> | undefined)[]): Record<string, string> | undefined;
 /**
- * Resolves the `--shuffle` seed: a fresh one when the flag was bare, the
- * operator's when it carried one. Mach's `--shuffle` is an UNSEEDED
- * Fisher–Yates over `Math.random` (SimpleTest/setup.js), so a red found by
- * shuffling could not be reproduced. FireForge draws the seed, exports it
- * as `FIREFORGE_SHUFFLE_SEED` for harness code that reorders inside a file,
- * prints it, and stamps it on the verdict line.
+ * Resolves the seed for FireForge's isolated shard order and exports it for
+ * custom in-file task code. Native mach file shuffling remains unseeded;
+ * replaying this seed guarantees only the FireForge shard permutation.
  *
  * Mochitest-only: the xpcshell harness has no shuffle, and generic `mach
  * test` dispatch would forward the flag to every suite it fans out to.
  */
 export declare function resolveShuffleSeed(shuffle: number | boolean | undefined, suite: TestSuite): number | undefined;
+/** Returns a deterministic Fisher–Yates permutation without mutating the selection. */
+export declare function shuffleTestGroups<T>(groups: readonly T[], seed: number): T[];