@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,317 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Failure diagnosis for `fireforge test`: maps captured mach output to
- * actionable operator messages (unknown test paths, stale build artifacts,
- * fork-module registration, xpcshell appdir, harness symlinks, mochitest
- * branding interactions), and applies harness-run verdicts from
- * `test-harness-crash.ts` for single and sharded invocations. Split out of
- * `test.ts` to keep both files within the per-file line budget.
- */
-import { getActiveRunLogPath } from '../core/run-log.js';
-import { describeChangedPrefNoise } from '../core/test-changed-prefs.js';
-import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, buildSilentSegfaultMessage, headedNoOutputTimeoutHint, isSilentSegfault, } from '../core/test-harness-crash.js';
-import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, completePostRebuildFailureContext, prependPostRebuildFailureContext, } from '../core/test-harness-output.js';
-import { buildIncompleteRunMessage } from '../core/test-run-completeness.js';
-import { GeneralError } from '../errors/base.js';
-import { TestFailureError } from '../errors/build.js';
-import { toError } from '../utils/errors.js';
-import { info } from '../utils/logger.js';
-import { getPlatform } from '../utils/platform.js';
-import { escapeRegex } from '../utils/regex.js';
-import { emitHarnessVerdict } from './test-verdict.js';
-function buildUnknownTestMessage(testPaths) {
-    return (`mach could not discover the requested test path${testPaths.length === 1 ? '' : 's'}: ${testPaths.join(', ')}\n\n` +
-        'The file may exist, but Firefox does not currently resolve it as a runnable test.\n\n' +
-        'Check the nearest test manifest (for example browser.toml or xpcshell.toml), confirm the file is listed under the correct test type, and make sure each parent moz.build registers that manifest before retrying.');
-}
-function buildStaleBuildMessage(postRebuild) {
-    if (postRebuild) {
-        return ('Firefox test runtime still reported stale-artifact-shaped resource failures after the rebuild completed.\n\n' +
-            'FireForge already ran the requested rebuild before this focused test, so treat the remaining failure as a real runtime, registration, routing, or test-contract regression rather than another stale deployed-artifact-only blocker.\n\n' +
-            'Check the first post-rebuild failure above and the raw mach output for the concrete path or module that still fails.');
-    }
-    return ('Firefox test runtime appears to be using stale build artifacts.\n\n' +
-        'The failing output referenced missing branding or distribution resources, which usually means the current obj-* build does not match recent engine or branding changes.\n\n' +
-        'Re-run "fireforge build --ui" or "fireforge test --build" and then retry.');
-}
-function hasStaleBuildArtifactsSignal(output) {
-    // Narrow on purpose: only fire on branding-specific resource paths that
-    // are always a stale-artifact symptom. A pattern that also matches
-    // `resource:///modules/distribution.sys.mjs` fires on real packaging and
-    // module-resolution failures too (a fork's own `.sys.mjs` missing from
-    // the installed app dir after a successful build), pushing operators
-    // toward "rebuild" advice for a module-registration issue.
-    return (/chrome:\/\/branding\/locale\/brand\.properties/i.test(output) ||
-        /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
-}
-/**
- * Fork-module-not-registered signal.
- *
- * A fork's test failing with `Failed to load
- * resource:///modules/<binary>/Store.sys.mjs` can also match the branding
- * pattern, because the harness prints a branding warning during teardown,
- * and the stale-build branch then wins by precedence, telling the operator
- * to rebuild when the real fix is to register the module in the fork's
- * `browser/modules/<binary>/moz.build`. Matching a
- * `resource:///modules/<binaryName>/` pattern surfaces the right diagnosis.
- */
-function hasForkModuleSignal(output, binaryName) {
-    // `binaryName` comes from fireforge.json, and config validation bars only
-    // `..`, path separators, NUL and absolute paths, so regex metacharacters
-    // get through. A hand-written character class is easy to get wrong (one that
-    // closes early after an escaped backslash escapes nothing), which makes
-    // `my.browser` match `myXbrowser` and lets an unbalanced `(` or `[` throw
-    // a SyntaxError out of the failure-diagnosis path, replacing the real test
-    // failure with an opaque regex error.
-    const pattern = new RegExp(`Failed to load resource:\\/\\/\\/modules\\/${escapeRegex(binaryName)}\\/`, 'i');
-    return pattern.test(output);
-}
-function buildForkModuleMessage(binaryName) {
-    return (`Test failed to load a fork-owned module at resource:///modules/${binaryName}/*.sys.mjs.\n\n` +
-        'This is almost always a module-registration issue, not a stale build. The fork module directory is missing an entry that maps its file into the resource URI tree, so `ChromeUtils.importESModule` cannot resolve it.\n\n' +
-        'Check that:\n' +
-        `  - browser/modules/${binaryName}/moz.build lists the missing module in EXTRA_JS_MODULES.\n` +
-        `  - browser/modules/moz.build references the ${binaryName}/ subdirectory (DIRS += [...]).\n` +
-        '  - The last `fireforge build` (or `fireforge build --ui`) completed successfully against the current manifests. If the registration is new, the UI-faster build path may not pick it up — a full build may be required.\n\n' +
-        'Use `fireforge register browser/modules/' +
-        binaryName +
-        '/<file>.sys.mjs` to add the EXTRA_JS_MODULES entry if it is missing.');
-}
-// Detects the broader xpcshell symptom where every `resource:///modules/...`
-// import fails, the signature of xpcshell running with the wrong app-dir on
-// a manifest that sets `firefox-appdir = "browser"`. Checked after the
-// stale-build signal (which matches the narrower `distribution.sys.mjs`
-// path) so the more specific diagnosis wins when both patterns apply.
-function hasXpcshellAppdirSignal(output) {
-    return /Failed to load resource:\/\/\/modules\//i.test(output);
-}
-function buildXpcshellAppdirMessage(injectionAttempted) {
-    const isMacos = process.platform === 'darwin';
-    const macosNote = isMacos
-        ? 'Detected: macOS host. On macOS the xpcshell harness binds `-a` to `<obj>/dist/<App>.app/Contents/Resources` by default and frequently ignores `--app-path` overrides when the `.app` bundle is present — the surest fix is the `<appname>-appdir` migration below rather than trying to force a different path.\n\n'
-        : '';
-    const triggerLines = injectionAttempted
-        ? 'FireForge auto-injected `--app-path=<absolute>` against the resolved obj-dir before mach test ran, but the failure persists. The injected path either does not match the appdir layout your harness expects, or (on macOS) the harness bound `-a` to the `.app/Contents/Resources` default and ignored the override.\n\n'
-        : 'Likely triggers:\n' +
-            '  - The nearest xpcshell.toml sets `firefox-appdir = "browser"` but the harness reads `<appname>-appdir` instead — the literal `firefox-appdir` directive is silently ignored on rebranded forks (appname != "firefox").\n' +
-            '  - FireForge could not find an xpcshell.toml above the test path, so the auto-injection never ran.\n\n';
-    return ('xpcshell failed to load core resource:///modules/*.sys.mjs imports.\n\n' +
-        'This is the canonical symptom of xpcshell running with the wrong app directory: the runtime resolves `resource:///modules/` against the parent of the expected app root, so every `ChromeUtils.importESModule("resource:///modules/…")` throws.\n\n' +
-        macosNote +
-        triggerLines +
-        'Options:\n' +
-        '  - Add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the xpcshell.toml [DEFAULT] so the harness reads the appname-keyed value directly. This is the most reliable fix on rebranded macOS builds.\n' +
-        '  - Pass overrides through `fireforge test <path> --mach-arg="--app-path=<absolute>"` to inject the path verbatim (operator overrides always win over auto-injection, but see the macOS caveat above).\n' +
-        '  - Remove `firefox-appdir = "browser"` from the xpcshell.toml [DEFAULT] and move browser-chrome dependencies into a browser-chrome mochitest (see `fireforge furnace create --test-style=browser-chrome`).\n' +
-        '  - If the test only touches toolkit chrome (chrome://global/*), drop the `firefox-appdir` setting entirely — toolkit chrome is registered without it.');
-}
-function buildHarnessSymlinkMessage() {
-    return ('mach failed while preparing test harness symlinks before the requested tests ran.\n\n' +
-        'This usually means the objdir contains stale harness setup from an earlier run. Re-run with `fireforge test --build` to refresh the harness state, or remove the stale harness symlink in the active obj-* directory before retrying.');
-}
-// Detects the `AttributeError: 'MochitestDesktop' object has no attribute
-// 'http3Server'` teardown crash. The attribute is lazy-initialized inside
-// harness code paths that presume chrome://branding resolves correctly. A
-// missing or miswired branding registration short-circuits the setup and
-// leaves the cleanup path looking up an attribute that was never assigned.
-function hasMochitestHttp3ServerSignal(output) {
-    return /'MochitestDesktop' object has no attribute 'http3Server'/.test(output);
-}
-function buildMochitestHttp3ServerMessage() {
-    return ("Mochitest raised `AttributeError: 'MochitestDesktop' object has no attribute 'http3Server'`.\n\n" +
-        'This is almost always a symptom of `chrome://branding` not registering correctly in your fork — the mochitest harness lazy-initializes `http3Server` only after branding resolves, and a missing branding registration short-circuits setup. The cleanup path then trips the AttributeError, masking the real error.\n\n' +
-        'Check that:\n' +
-        "  - Your fork's branding directory is listed in `browser/branding/moz.build` (or equivalent) and ships a `brand.properties` / `brand.ftl`.\n" +
-        '  - `chrome://branding/locale/brand.properties` resolves at runtime (try `fireforge run` and inspect the Browser Console).\n' +
-        "  - The `BROWSER_CHROME_MANIFESTS` entry for your fork's chrome.manifest is registered.\n\n" +
-        'This is an upstream Firefox harness interaction; FireForge can only diagnose it.');
-}
-/**
- * Maps a non-zero mach exit to the most specific actionable diagnosis the
- * captured output supports, throwing it as a domain error.
- *
- * The branch order is load-bearing: narrower signals are checked before
- * broader ones, so a fork-owned module failure is not reported as a stale
- * build.
- */
-function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext, 
-/**
- * The classified verdict, when one was reached. Carries the failing-test
- * evidence the final throw names. Every branch above that throw is a
- * different diagnosis and does not use it.
- */
-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;
-    const withContext = (message) => prependPostRebuildFailureContext(message, failureContext);
-    const throwGeneral = (message) => {
-        throw new GeneralError(withContext(message));
-    };
-    // First, because there is nothing else to go on: a SIGSEGV with zero
-    // output has exactly one known cause and no other evidence.
-    // Every branch below keys on output text this shape does not have.
-    if (isSilentSegfault(result.exitCode, combinedOutput)) {
-        throwGeneral(buildSilentSegfaultMessage(result.exitCode, normalizedPaths));
-    }
-    if (/UNKNOWN TEST\b/i.test(combinedOutput)) {
-        throwGeneral(buildUnknownTestMessage(normalizedPaths));
-    }
-    const earlyExit = classifyHarnessEarlyExit(combinedOutput, normalizedPaths);
-    if (earlyExit) {
-        throwGeneral(buildHarnessEarlyExitMessage(earlyExit, normalizedPaths));
-    }
-    // Fork-owned module load failures must beat the branding stale-build
-    // branch: a test failing with `Failed to load
-    // resource:///modules/<binary>/Store.sys.mjs` while the harness teardown
-    // prints a branding warning would otherwise be told to rebuild, when the
-    // real fix is to register the missing module.
-    if (hasForkModuleSignal(combinedOutput, binaryName)) {
-        throwGeneral(buildForkModuleMessage(binaryName));
-    }
-    // Branding-specific stale-build signals keep priority over the broader
-    // xpcshell-appdir hint: when `chrome://branding/locale/brand.properties`
-    // fails to resolve, the fix really is "rebuild", not "pass --app-path".
-    // The stale-build check is narrow enough not to match
-    // `resource:///modules/distribution.sys.mjs` alone, which produced
-    // false-positive rebuild advice on fork-custom module-load failures. Those
-    // cases fall through to xpcshell-appdir, the more useful diagnosis for
-    // `Failed to load resource:///modules/…`.
-    if (hasStaleBuildArtifactsSignal(combinedOutput)) {
-        throwGeneral(buildStaleBuildMessage(Boolean(failureContext)));
-    }
-    if (hasXpcshellAppdirSignal(combinedOutput)) {
-        throwGeneral(buildXpcshellAppdirMessage(appdirInjectionAttempted));
-    }
-    if (hasMochitestHttp3ServerSignal(combinedOutput)) {
-        throwGeneral(buildMochitestHttp3ServerMessage());
-    }
-    if (/FileExistsError/i.test(combinedOutput) &&
-        /(mochitest|xpcshell|_tests)/i.test(combinedOutput)) {
-        throwGeneral(buildHarnessSymlinkMessage());
-    }
-    if (/invalid filename/i.test(combinedOutput) ||
-        /chrome:\/\/mochitests.*not found/i.test(combinedOutput)) {
-        info('Hint: The test file may not be registered in browser.toml or jar.mn.');
-        info('Run "fireforge register <test-path>" to register it.');
-    }
-    // Last, and additive rather than a branch of its own: the run really did
-    // fail (exit code stays 5), so this only says which kind of failure it is.
-    // Every branch above is a different diagnosis and outranks it.
-    const changedPrefNoise = describeChangedPrefNoise(combinedOutput);
-    const failureBlocks = formatFailureBlocks(verdict?.realFailureBlocks);
-    const logPath = getActiveRunLogPath();
-    throw new TestFailureError(withContext(`Tests failed with exit code ${result.exitCode}.` +
-        (changedPrefNoise !== undefined ? `\n\n${changedPrefNoise}` : '')), 'mach test', failureBlocks, logPath);
-}
-/**
- * Applies the harness-run verdict for a single (non-sharded) invocation:
- * exhausted harness-crash retries and silent zero-TEST-START runs are
- * harness problems with their own messages. Everything else flows into
- * the regular non-zero-exit diagnosis chain.
- */
-export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless = false) {
-    // The FIREFORGE-VERDICT line is the last stdout write of the run, on the
-    // pass return and every throw path alike, written raw (not via clack,
-    // whose renderer drops output under non-TTY capture) so harness-verdict
-    // consumers grep one stable line instead of mach internals.
-    try {
-        applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless);
-    }
-    finally {
-        emitHarnessVerdict(outcome.verdict);
-    }
-}
-function applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless) {
-    if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
-        const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
-        const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
-            headless,
-            platform: getPlatform(),
-            ...(outcome.displayState !== undefined ? { displayState: outcome.displayState } : {}),
-        });
-        throw new GeneralError(hint ? `${base}\n\n${hint}` : base);
-    }
-    if (outcome.verdict.kind === 'tests-ran-ok') {
-        // The verdict is authoritative over the raw exit code: a completed green
-        // embedded summary overrides a non-zero exit caused by harness noise,
-        // which would otherwise leave operators parsing embedded summaries by
-        // hand.
-        if (outcome.verdict.greenSummaryOverride) {
-            info(`Note: mach exited ${outcome.result.exitCode}, but the embedded suite summary completed ` +
-                'green (Unexpected results: 0). FireForge treats the run as passed; the non-zero exit ' +
-                'came from non-fatal harness noise (resource-monitor degradation / telemetry).');
-        }
-        return;
-    }
-    if (outcome.verdict.incomplete !== undefined) {
-        throw new TestFailureError(buildIncompleteRunMessage(outcome.verdict.incomplete), 'mach test', formatFailureBlocks(outcome.verdict.realFailureBlocks), getActiveRunLogPath());
-    }
-    if (outcome.verdict.kind === 'no-tests' && outcome.result.exitCode === 0) {
-        // The silent false green: exit 0 plus a "Passed: 0"-style summary with
-        // zero TEST-START lines must fail rather than pass.
-        throw new GeneralError(buildNoTestsRanMessage(0, normalizedPaths));
-    }
-    // A green-looking summary rejected on crash/truncation evidence gets its
-    // own explanation instead of the generic exit-code message, so the
-    // operator can see why the green counts were not trusted.
-    if (outcome.verdict.greenSummaryRejected) {
-        throw new GeneralError(buildGreenSummaryRejectedMessage(outcome.verdict.greenSummaryRejected, outcome.result.exitCode));
-    }
-    if (outcome.verdict.realFailureLine !== undefined) {
-        info(`First real test failure: ${outcome.verdict.realFailureLine}`);
-        const blocks = formatFailureBlocks(outcome.verdict.realFailureBlocks);
-        if (blocks !== undefined) {
-            info(blocks);
-        }
-        if (outcome.verdict.secondaryHarnessSignature !== undefined) {
-            info(`Secondary harness noise also present: ${outcome.verdict.secondaryHarnessSignature.reason}; ` +
-                outcome.verdict.secondaryHarnessSignature.line);
-        }
-    }
-    handleNonZeroTestExit(outcome.result, normalizedPaths, outcome.appdirInjectionAttempted, binaryName, postRebuildContext, outcome.verdict);
-}
-/**
- * Shard-mode adapter over {@link handleNonZeroTestExit}: produces the
- * diagnosis text as a string (to warn per shard) instead of throwing, so
- * later shards still run and the aggregate error stays singular.
- */
-export function diagnoseShardOutcome(outcome, path, binaryName, postRebuildContext) {
-    if (outcome.verdict.kind === 'no-tests' && outcome.result.exitCode === 0) {
-        return buildNoTestsRanMessage(0, [path]);
-    }
-    if (outcome.verdict.incomplete !== undefined) {
-        return buildIncompleteRunMessage(outcome.verdict.incomplete);
-    }
-    if (outcome.verdict.greenSummaryRejected) {
-        return buildGreenSummaryRejectedMessage(outcome.verdict.greenSummaryRejected, outcome.result.exitCode);
-    }
-    try {
-        handleNonZeroTestExit(outcome.result, [path], outcome.appdirInjectionAttempted, binaryName, postRebuildContext);
-        return undefined;
-    }
-    catch (error) {
-        const diagnosis = toError(error).message;
-        const blocks = formatFailureBlocks(outcome.verdict.realFailureBlocks);
-        return blocks !== undefined ? `${blocks}\n${diagnosis}` : diagnosis;
-    }
-}
-/**
- * Renders the verdict's TEST-UNEXPECTED blocks (verbatim failing lines +
- * their assertion/diff context) for the failure summary. Returns undefined
- * when the verdict carries none, so callers can skip the section entirely.
- */
-function formatFailureBlocks(blocks) {
-    if (blocks === undefined || blocks.length === 0)
-        return undefined;
-    // The collector appends a `…(+N more …)` note when it truncated. That
-    // note is not a failure block, so it does not count toward the header.
-    const shown = blocks.filter((block) => !block.startsWith('…(')).length;
-    return `Unexpected test failures (first ${shown}):\n${blocks.join('\n\n')}`;
-}

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

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

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

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