@hominis/fireforge 0.48.0 → 0.49.0

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[];

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;
 /**