@hominis/fireforge 0.47.1 → 0.49.0

package/dist/src/commands/test-harness-env.js

@@ -36,12 +36,9 @@ export function mergeHarnessEnv(...parts) {
     return Object.keys(merged).length > 0 ? merged : 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.
@@ -56,6 +53,29 @@ export function resolveShuffleSeed(shuffle, suite) {
     }
     const seed = shuffle === true ? randomInt(1, 2 ** 31 - 1) : shuffle;
     setVerdictRunAttribute('shuffle', String(seed));
-    info(`Test order shuffle: seed=${seed} (reproduce with "fireforge test --shuffle=${seed}")`);
+    info(`Test shard order: seed=${seed} (replay with "fireforge test --shuffle=${seed}"). ` +
+        'Native harness file shuffle remains unseeded.');
     return seed;
 }
+/** Returns a deterministic Fisher–Yates permutation without mutating the selection. */
+export function shuffleTestGroups(groups, seed) {
+    const shuffled = [...groups];
+    // Hash the decimal seed so every accepted safe integer contributes, rather
+    // than silently discarding its high bits in the 32-bit PRNG.
+    let state = 2166136261;
+    for (const character of String(seed))
+        state = Math.imul(state ^ character.charCodeAt(0), 16777619);
+    state = state >>> 0 || 1;
+    for (let index = shuffled.length - 1; index > 0; index--) {
+        state ^= state << 13;
+        state ^= state >>> 17;
+        state ^= state << 5;
+        const destination = Math.floor(((state >>> 0) / 2 ** 32) * (index + 1));
+        // Both indexes are bounded by the array length, including under
+        // noUncheckedIndexedAccess; T may itself contain undefined.
+        const selected = shuffled[index];
+        shuffled[index] = shuffled[destination];
+        shuffled[destination] = selected;
+    }
+    return shuffled;
+}

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

@@ -1,15 +1,14 @@
 import type { TestOptions } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import type { TestRunOutcome } from './test-run.js';
-type ProjectConfig = FireForgeConfig;
 /** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
 export declare function assertPathlessTestMode(testPaths: readonly string[], options: TestOptions): void;
 /** Rejects invalid combinations for mode-like `fireforge test` options. */
 export declare function assertTestModeCombinations(testPaths: readonly string[], options: TestOptions, canaryPath: string | undefined): void;
 /** Resolves the canary path from CLI or config. */
-export declare function resolveCanaryPath(options: TestOptions, projectConfig: ProjectConfig): string | undefined;
+export declare function resolveCanaryPath(options: TestOptions, projectConfig: FireForgeConfig): string | undefined;
 /** Returns the configured canary no-output budget, defaulting to 60 seconds. */
-export declare function canaryTimeoutSeconds(projectConfig: ProjectConfig): number;
+export declare function canaryTimeoutSeconds(projectConfig: FireForgeConfig): number;
 /** Emits or throws the one-word canary verdict. */
 export declare function reportCanaryOutcome(outcome: TestRunOutcome): void;
 /** Per-harness bucketing of the requested test paths. */
@@ -41,4 +40,3 @@ export declare function classifyBeforeDispatch(engineDir: string, normalizedPath
  * run build-less without tripping the stale/coverage gate.
  */
 export declare function reportBuildOnlyCompletion(classification: HarnessClassification, normalizedPaths: readonly string[]): void;
-export {};

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

@@ -28,7 +28,7 @@ const TEST_HELP_TEXT = [
     '',
     'Machine-readable verdict: every run (single, sharded, --canary,',
     '--doctor) ends with exactly one raw stdout line',
-    '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|test-failures|',
+    '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|harness-arguments|test-failures|',
     '  no-tests|preflight|inconclusive|lock-timeout|killed] [checks=<n>]',
     '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)] [shuffle=<seed>]',
     '  [log=<path>]',
@@ -41,8 +41,8 @@ const TEST_HELP_TEXT = [
     'a green-summary-override pass says PASS despite a non-zero mach',
     'exit. reason=preflight covers any failure before the harness ran',
     '(missing/stale build, invalid paths, port conflicts, config',
-    'errors); reason=inconclusive means engine/ changed while the',
-    'tests ran, so the harness result cannot be trusted;',
+    'errors); reason=inconclusive means engine/ or perf power source',
+    'changed while tests ran, so the result cannot be trusted;',
     'reason=lock-timeout means the run never started because another',
     'engine-mutating command held the lock past the wait budget;',
     'reason=killed means a signal terminated the run before it reached',
@@ -57,6 +57,12 @@ const TEST_HELP_TEXT = [
     'stall whose display was measured asleep. Key on this line',
     'instead of mach internals.',
 ].join('\n');
+function registerTestSharingOptions(test) {
+    return test
+        .option('--wait-browser [seconds]', 'Wait for this objdir browser before any deployment/build (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
+        .option('--wait-port [seconds]', 'Wait for the mochitest and Marionette ports (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
+        .option('--profile-file <source=destination>', 'Merge a file into the harness profile, e.g. sheet.css=chrome/userChrome.css. Repeatable.', ...stringListOption());
+}
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
     const test = program
@@ -77,7 +83,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
         .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', ...stringListOption())
-        .option('--shuffle [seed]', 'Run the mochitest files in a seeded random order: forwards mach --shuffle and exports FIREFORGE_SHUFFLE_SEED=<seed> to the harness (a fresh seed when omitted). The seed rides the FIREFORGE-VERDICT line as shuffle=<seed>; replay a red with --shuffle=<seed>. Mochitest-only. Write it as --shuffle=<seed> or after the paths, since a bare "--shuffle <path>" reads the path as the seed.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shuffle', raw)))
+        .option('--shuffle [seed]', 'Shuffle isolated mochitest path arguments in a repeatable seeded order (fresh seed when omitted). Native mach --shuffle within each invocation remains unseeded. Export FIREFORGE_SHUFFLE_SEED for custom task code and stamp shuffle=<seed> on the verdict. --no-shard disables the seeded argument permutation. Write --shuffle=<seed> or place it after the paths.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shuffle', raw)))
         .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${DEFAULT_HARNESS_RETRIES}.`, commanderArgParser((raw) => {
         const n = Number.parseInt(raw, 10);
         if (!Number.isFinite(n) || n < 0 || n > 10) {
@@ -96,7 +102,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         return n;
     }))
         .addHelpText('after', TEST_HELP_TEXT);
-    addWaitLockOption(test).action(withErrorHandling(async (paths, options) => {
+    addWaitLockOption(registerTestSharingOptions(test)).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
         // The engine session lock is acquired outside testCommand's own
         // exactly-one-verdict guarantee, so a lock failure must emit here or

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

@@ -24,6 +24,8 @@ export declare const DEFAULT_HARNESS_RETRIES = 2;
 export type TestSuite = 'xpcshell' | 'mochitest' | 'generic';
 /** Inputs shared by every harness invocation in one `fireforge test` run. */
 export interface TestRunContext {
+    /** A perf run changed power source; no green result can be trusted. */
+    powerChanged?: boolean;
     engineDir: string;
     objDir: string | undefined;
     classification: {

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

@@ -17,6 +17,7 @@ import { parentExited } from '../core/parent-exit-watchdog.js';
 import { getActiveRunLogPath } from '../core/run-log.js';
 import { changedPrefNoiseVerdictNote } from '../core/test-changed-prefs.js';
 import { buildHarnessCrashMessage, classifyHarnessRun, headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
+import { reportTestHost, sampleTestHost, stampPerfHost } from '../core/test-host-state.js';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
 import { withXpcshellProfileDir } from '../core/xpcshell-profile-dir.js';
 import { TestFailureError } from '../errors/build.js';
@@ -24,7 +25,7 @@ import { info, note, warn } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
 import { maybeInjectAppdirArg } from './test-appdir.js';
 import { createHarnessTeardown } from './test-harness-teardown.js';
-import { emitHarnessVerdict } from './test-verdict.js';
+import { emitHarnessVerdict, setVerdictRunAttribute } from './test-verdict.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
 /** Resolves the mach test command a suite dispatches to. */
@@ -121,6 +122,15 @@ async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env) {
         objDir: ctx.objDir === undefined ? undefined : join(ctx.engineDir, ctx.objDir),
         pgidFile: ctx.pgidFile,
     });
+    const start = await sampleTestHost();
+    const warned = reportTestHost(start, 'suite start');
+    setVerdictRunAttribute('host-load', start.load.toFixed(2));
+    if (warned)
+        setVerdictRunAttribute('host-cpu-warning', 'true');
+    if (env && Object.keys(env).some((key) => key.endsWith('_PERF_SAMPLE_JSON'))) {
+        setVerdictRunAttribute('power-source', start.power);
+        env = { ...env, FIREFORGE_POWER_SOURCE: start.power };
+    }
     try {
         await teardown.prepare();
         return await runMachTestSuite(kind, {
@@ -134,6 +144,13 @@ async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env) {
     }
     finally {
         teardown.dispose();
+        const end = await sampleTestHost();
+        if (reportTestHost(end, 'suite end'))
+            setVerdictRunAttribute('host-cpu-warning', 'true');
+        if (await stampPerfHost(env, start, end)) {
+            ctx.powerChanged = true;
+            setVerdictRunAttribute('power-changed', 'true');
+        }
     }
 }
 /**
@@ -158,6 +175,7 @@ const SHARD_STATUS_LABEL = {
     'test-failures': 'FAIL',
     'harness-crash': 'CRASH',
     'no-tests': 'NO-TESTS',
+    'harness-arguments': 'ARGUMENTS',
 };
 /**
  * Derives the aggregate classification for a sharded run: all-green is
@@ -168,6 +186,8 @@ const SHARD_STATUS_LABEL = {
  */
 export function deriveAggregateShardVerdict(shards) {
     const kinds = new Set(shards.map(({ outcome }) => outcome.verdict.kind));
+    if (kinds.has('harness-arguments'))
+        return { kind: 'harness-arguments' };
     if (kinds.has('harness-crash'))
         return { kind: 'harness-crash' };
     if (kinds.has('no-tests'))

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

@@ -11,9 +11,9 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  * and `killed` marks a run terminated by a signal before it could reach any
  * of the others.
  */
-export type FireforgeVerdictReason = 'crash' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
+export type FireforgeVerdictReason = 'crash' | 'harness-arguments' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
 /** Additive keys a run can stamp on its verdict line. */
-export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped';
+export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed';
 /** Records an additive attribute for this run's verdict line. */
 export declare function setVerdictRunAttribute(key: VerdictRunAttributeKey, value: string): void;
 /**

package/dist/src/commands/test.js

@@ -3,29 +3,30 @@ import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
-import { reportOrphanedHarnessProcesses } from '../core/harness-orphans.js';
 import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.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 { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
+import { waitForPreflight } from '../core/preflight-wait.js';
 import { closeActiveRunLog, openRunLog, setActiveRunLog, writeToActiveRunLog, } from '../core/run-log.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
+import { cleanupProfileFiles, stageProfileFiles, } from '../core/test-profile-files.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
 import { FireForgeError, GeneralError, PreflightRefusalError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, notice, outro, verbose } from '../utils/logger.js';
+import { info, intro, notice, warn } from '../utils/logger.js';
+import { resolveWaitLockSeconds } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
+import { appendMarionetteForwardingArgs, ensureTestBrowserEnvironment, runDoctorPreflight, } from './test-browser-preflight.js';
 import { runTestBuildPhase } from './test-build-phase.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
-import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed } from './test-harness-env.js';
+import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed, shuffleTestGroups, } from './test-harness-env.js';
 import { removePgidFile, setActivePgidFile } from './test-harness-teardown.js';
 import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
 import { DEFAULT_HARNESS_RETRIES, finalizeShardedOutcome, runShardedTests, runTestsWithRetries, } from './test-run.js';
-import { addVerdictRunCount, emitFailVerdict, emitPassVerdict, resetVerdictEmission, verdictEmitted, } from './test-verdict.js';
+import { emitFailVerdict, resetVerdictEmission, verdictEmitted } from './test-verdict.js';
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
     for (const testPath of testPaths) {
@@ -102,171 +103,6 @@ function logTestSelection(scopes) {
     }
     info('');
 }
-/**
- * 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.
- */
-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.
- */
-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 });
-}
-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 ensureLaunchableBrowserNotRunning(join(engineDir, launchablePath), {
-            killStaleBrowser: options.killStaleMarionette === true,
-        });
-    }
-    // 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 ensureMochitestServerPortAvailable(undefined, {
-            engineDir,
-            killStaleServer: options.killStaleMarionette === true,
-        });
-    }
-    // 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 ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options, {
-        xpcshellOnly,
-        doctor: options.doctor === true,
-    });
-    return { forwardedPort, effectivePort };
-}
 /** Build-artifact preflight wording for `fireforge test`. */
 const TEST_BUILD_PREFLIGHT = {
     label: 'Tests',
@@ -297,8 +133,13 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // `finally`, after the verdict line has already read the path.
     setActiveRunLog(await openRunLog(projectRoot, 'test'));
     setActivePgidFile(options.pgidFile);
+    let staged;
     try {
-        await runTestCommandBody(projectRoot, testPaths, options);
+        if (options.profileFile?.length) {
+            staged = await stageProfileFiles(projectRoot, options.profileFile);
+            options = { ...options, machArg: [...(options.machArg ?? []), ...staged.args] };
+        }
+        await runTestCommandBody(projectRoot, testPaths, options, staged?.env);
     }
     catch (error) {
         if (!verdictEmitted()) {
@@ -310,8 +151,20 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     finally {
         // A run that ends under FireForge's control owns no harness group any
         // more; the file only outlives FireForge when FireForge was killed.
-        await removePgidFile(options.pgidFile);
-        await closeActiveRunLog();
+        const stagedRoot = staged?.root;
+        const cleanups = [
+            ...(stagedRoot === undefined ? [] : [() => cleanupProfileFiles(stagedRoot)]),
+            () => removePgidFile(options.pgidFile),
+            () => closeActiveRunLog(),
+        ];
+        for (const cleanup of cleanups) {
+            try {
+                await cleanup();
+            }
+            catch (error) {
+                warn(`Test cleanup failed: ${toError(error).message}`);
+            }
+        }
     }
 }
 /** The refusal class a preflight gate named, when it named one. */
@@ -355,16 +208,56 @@ function renderPreflightRefusal(error) {
  * 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) {
+async function verifyEngineGenerationOrEmitInconclusive(engineDir, before, powerChanged = false) {
     try {
         await assertEngineGenerationUnchanged(engineDir, before);
+        if (powerChanged)
+            throw new GeneralError('Perf power source changed during the run; repeat this sitting on a stable power source.');
     }
     catch (error) {
         emitFailVerdict('inconclusive');
         throw error;
     }
 }
-async function runTestCommandBody(projectRoot, testPaths, options = {}) {
+async function guardBuildBrowser(engineDir, launchablePath, options) {
+    if ((options.build || options.buildOnly) && launchablePath) {
+        await waitForPreflight(() => ensureLaunchableBrowserNotRunning(join(engineDir, launchablePath), {
+            killStaleBrowser: options.killStaleMarionette === true,
+        }), options.waitBrowser === undefined ? undefined : resolveWaitLockSeconds(options.waitBrowser));
+    }
+}
+function prepareExtraMachArgs(options, shuffleSeed, canaryPath, projectConfig, forwardedMachArgs) {
+    const extraArgs = [];
+    if (options.headless) {
+        extraArgs.push('--headless');
+    }
+    if (shuffleSeed !== undefined) {
+        extraArgs.push('--shuffle');
+    }
+    if (options.auto === true) {
+        extraArgs.push('--auto');
+    }
+    if (canaryPath !== undefined)
+        extraArgs.push(`--timeout=${canaryTimeoutSeconds(projectConfig)}`);
+    // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
+    // flags FireForge does not model directly (see the xpcshell appdir hint
+    // above for why). Appended after --headless so mach sees
+    // the FireForge-managed flags first and the escape-valve ones last, which
+    // keeps the override precedence predictable.
+    if (forwardedMachArgs.length > 0)
+        extraArgs.push(...forwardedMachArgs);
+    return extraArgs;
+}
+function prepareDispatchArguments(classification, options, canaryPath, projectConfig) {
+    const suite = resolveTestSuite(classification, options.genericMachTest === true);
+    const shuffleSeed = resolveShuffleSeed(options.shuffle, suite);
+    const forwardedMachArgs = options.machArg && options.machArg.length > 0
+        ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
+        : [];
+    const extraArgs = prepareExtraMachArgs(options, shuffleSeed, canaryPath, projectConfig, forwardedMachArgs);
+    return { suite, shuffleSeed, extraArgs };
+}
+async function runTestCommandBody(projectRoot, testPaths, options = {}, profileEnv) {
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     await assertEngineExists(paths.engine);
@@ -398,12 +291,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
     const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
     const { classification, xpcshellOnly } = await classifyBeforeDispatch(paths.engine, normalizedPaths, { allowMixed: options.buildOnly === true });
-    if (await runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, {
-        classification,
-        normalizedPaths,
-    })) {
-        return;
-    }
+    await guardBuildBrowser(paths.engine, launchablePath, options);
     // Resolve the effective Marionette port. Operator precedence:
     //   1. `--marionette-port` (first-class option, parsed at the CLI layer)
     //   2. forwarded `--mach-arg --marionette-port=NNNN` /
@@ -414,6 +302,12 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     // documented `--mach-arg --marionette-port=NNNN` route still hits the
     // wrapper preflight refusing on 2828 before the forwarded arg reaches
     // mach.
+    if (await runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, {
+        classification,
+        normalizedPaths,
+    })) {
+        return;
+    }
     const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig, options, buildCheck.objDir);
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
@@ -428,30 +322,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
             return;
     }
     await assertTestPathsExist(paths.engine, normalizedPaths);
-    const suite = resolveTestSuite(classification, options.genericMachTest === true);
-    const shuffleSeed = resolveShuffleSeed(options.shuffle, suite);
-    const forwardedMachArgs = options.machArg && options.machArg.length > 0
-        ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
-        : [];
-    const extraArgs = [];
-    if (options.headless) {
-        extraArgs.push('--headless');
-    }
-    if (shuffleSeed !== undefined) {
-        extraArgs.push('--shuffle');
-    }
-    if (options.auto === true) {
-        extraArgs.push('--auto');
-    }
-    if (canaryPath !== undefined)
-        extraArgs.push(`--timeout=${canaryTimeoutSeconds(projectConfig)}`);
-    // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
-    // flags FireForge does not model directly (see the xpcshell appdir hint
-    // above for why). Appended after --headless so mach sees
-    // the FireForge-managed flags first and the escape-valve ones last, which
-    // keeps the override precedence predictable.
-    if (forwardedMachArgs.length > 0)
-        extraArgs.push(...forwardedMachArgs);
+    const { suite, shuffleSeed, extraArgs } = prepareDispatchArguments(classification, options, canaryPath, projectConfig);
     appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
     // Directory arguments mean exactly that directory: mozbuild's test
     // resolver matches paths by string prefix, so a bare directory arg
@@ -478,7 +349,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     // the manifest for each file individually. See src/core/xpcshell-appdir.ts
     // for the full motivation.
     logTestSelection(scopes);
-    const harnessEnv = mergeHarnessEnv(buildPerfSampleEnv(projectRoot, projectConfig.binaryName, options.perfSamples), shuffleSeed === undefined ? undefined : { FIREFORGE_SHUFFLE_SEED: String(shuffleSeed) });
+    const harnessEnv = mergeHarnessEnv(buildPerfSampleEnv(projectRoot, projectConfig.binaryName, options.perfSamples), profileEnv, shuffleSeed === undefined ? undefined : { FIREFORGE_SHUFFLE_SEED: String(shuffleSeed) });
     const runCtx = {
         engineDir: paths.engine,
         objDir: buildCheck.objDir,
@@ -511,14 +382,15 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         const generationBefore = await snapshotEngineGeneration(paths.engine);
         let summary;
         try {
-            summary = await runShardedTests(runCtx, dispatchGroups, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, postRebuildContext));
+            const orderedGroups = shuffleSeed === undefined ? dispatchGroups : shuffleTestGroups(dispatchGroups, shuffleSeed);
+            summary = await runShardedTests(runCtx, orderedGroups, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, postRebuildContext));
         }
         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(paths.engine, generationBefore);
+            await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged);
         }
         finalizeShardedOutcome(summary);
         return;
@@ -533,7 +405,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
     }
     finally {
-        await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore);
+        await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged);
     }
     if (canaryPath !== undefined) {
         reportCanaryOutcome(outcome);

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

@@ -26,6 +26,11 @@ export interface TypecheckCommandOptions {
      * issues without waiting for the full set.
      */
     project?: string;
+    /**
+     * Build every project from scratch and write no incremental build info
+     * (`--no-cache`).
+     */
+    noCache?: boolean;
 }
 /**
  * Resolves the project list to type-check. `--project` wins over