@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,158 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
-import { GeneralError } from '../errors/base.js';
-import { info, success } from '../utils/logger.js';
-import { emitHarnessVerdict } from './test-verdict.js';
-/** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
-export function assertPathlessTestMode(testPaths, options) {
-    if (testPaths.length === 0 &&
-        options.auto !== true &&
-        options.doctor !== true &&
-        options.buildOnly !== true &&
-        options.canary === undefined) {
-        throw new GeneralError(buildPathlessTestMessage());
-    }
-}
-/** Rejects invalid combinations for mode-like `fireforge test` options. */
-export function assertTestModeCombinations(testPaths, options, canaryPath) {
-    if (options.auto === true && testPaths.length > 0) {
-        throw new GeneralError('`fireforge test --auto` is valid only when no explicit paths are provided.');
-    }
-    if (options.canary !== undefined && testPaths.length > 0) {
-        throw new GeneralError('`fireforge test --canary` runs one canary path; do not pass positional test paths.');
-    }
-    if (options.canary !== undefined && canaryPath === undefined) {
-        throw new GeneralError('No test canary path is configured.\n\n' +
-            'Pass `fireforge test --canary <path>` or set `test.canaryPath` in fireforge.json.');
-    }
-    if (options.buildOnly === true &&
-        (options.doctor === true || options.canary !== undefined || options.auto === true)) {
-        throw new GeneralError('`fireforge test --build-only` builds and exits without dispatching tests; it cannot be combined with --doctor, --canary, or --auto.');
-    }
-}
-/** Resolves the canary path from CLI or config. */
-export function resolveCanaryPath(options, projectConfig) {
-    if (options.canary === undefined || options.canary === false)
-        return undefined;
-    if (typeof options.canary === 'string')
-        return options.canary;
-    return projectConfig.test?.canaryPath;
-}
-/** Returns the configured canary no-output budget, defaulting to 60 seconds. */
-export function canaryTimeoutSeconds(projectConfig) {
-    return projectConfig.test?.canaryTimeoutSeconds ?? 60;
-}
-/** Emits or throws the one-word canary verdict. */
-export function reportCanaryOutcome(outcome) {
-    // Written raw as the run's last stdout line on green and throw paths
-    // alike. See the FIREFORGE-VERDICT contract in test-harness-crash.ts.
-    try {
-        if (outcome.verdict.kind === 'tests-ran-ok') {
-            success('Canary: green');
-            return;
-        }
-        if (outcome.verdict.kind === 'harness-crash' &&
-            outcome.verdict.signature?.reason.includes('no-output timeout')) {
-            throw new GeneralError(`Canary: hang\n\n${outcome.verdict.signature.line}`);
-        }
-        if (outcome.verdict.kind === 'harness-crash') {
-            throw new GeneralError(`Canary: crash\n\n${outcome.verdict.signature ? outcome.verdict.signature.line : 'Harness crashed before the canary completed.'}`);
-        }
-        throw new GeneralError('Canary: crash\n\nThe canary did not complete green; see mach output above.');
-    }
-    finally {
-        emitHarnessVerdict(outcome.verdict);
-    }
-}
-function buildPathlessTestMessage() {
-    return ('`fireforge test` now requires an explicit test path unless you choose a pathless mode.\n\n' +
-        'Use one of:\n' +
-        '  - `fireforge test <engine-relative test path>` for focused runs\n' +
-        "  - `fireforge test --auto` to forward mach's own auto-selection mode\n" +
-        '  - `fireforge test --doctor` to run the Marionette preflight only\n' +
-        '  - `fireforge test --canary` to run the configured short harness canary');
-}
-/** Buckets normalized request paths by the harness their nearest manifest selects. */
-export async function classifyTestHarnesses(engineDir, normalizedPaths) {
-    const result = { xpcshell: [], nonXpcshell: [] };
-    for (const testPath of normalizedPaths) {
-        const manifest = await findNearestXpcshellManifest(engineDir, testPath);
-        if (manifest) {
-            result.xpcshell.push(testPath);
-        }
-        else {
-            result.nonXpcshell.push(testPath);
-        }
-    }
-    return result;
-}
-function buildMixedHarnessMessage(classification) {
-    return ('FireForge cannot run xpcshell and browser/mochitest paths in the same mach invocation.\n\n' +
-        'Split this into separate `fireforge test` commands so each manifest selects its own harness:\n' +
-        `  - xpcshell: ${classification.xpcshell.join(', ')}\n` +
-        `  - browser/mochitest: ${classification.nonXpcshell.join(', ')}`);
-}
-/**
- * Harness classification is a pure path→manifest lookup and must precede
- * the build dispatch: a mixed xpcshell+mochitest request can never
- * dispatch, so refusing it before spending minutes in a pre-test build
- * is strictly better. A nonexistent path classifies as
- * nonXpcshell (findNearestXpcshellManifest returns null), so classifying
- * before assertTestPathsExist is harmless: existence is still asserted
- * after the stale/coverage gates, preserving their precedence over
- * missing-path errors. `xpcshellOnly` (non-empty request, zero
- * nonXpcshell paths) gates the Marionette preflight and the mochitest
- * client flags. Pathless runs keep the full-suite behavior.
- */
-export async function classifyBeforeDispatch(engineDir, normalizedPaths, options) {
-    const classification = await classifyTestHarnesses(engineDir, normalizedPaths);
-    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
-        // `--build-only` never dispatches, so a mixed request is legal there:
-        // packaging the union is the whole point.
-        if (options?.allowMixed !== true) {
-            throw new GeneralError(buildMixedHarnessMessage(classification));
-        }
-    }
-    return {
-        classification,
-        xpcshellOnly: normalizedPaths.length > 0 && classification.nonXpcshell.length === 0,
-    };
-}
-/**
- * Prints the `--build-only` completion guidance: the union build is
- * recorded as the packaging-coverage claim, so each harness half can now
- * run build-less without tripping the stale/coverage gate.
- */
-export function reportBuildOnlyCompletion(classification, normalizedPaths) {
-    info('Build complete. The recorded packaging coverage includes every requested path.');
-    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
-        info('Run each harness separately without --build:');
-        info(`  fireforge test ${classification.xpcshell.join(' ')}`);
-        info(`  fireforge test ${classification.nonXpcshell.join(' ')}`);
-    }
-    else if (normalizedPaths.length > 0) {
-        info(`Run: fireforge test ${normalizedPaths.join(' ')}`);
-    }
-}
-/**
- * The mach args `--restart-between-tests` forwards: mochitest's own flag,
- * which restarts the browser between test files (the run shape a
- * `standalone` manifest key asks for). Mochitest-only, refused otherwise
- * for the reason `--shuffle` is: xpcshell has no such flag and generic
- * `mach test` would hand it to every suite. Not duplicated when
- * `--mach-arg` already forwards it.
- *
- * @param options - Parsed test options
- * @param suite - The resolved dispatch target
- * @param forwardedMachArgs - `--mach-arg` values after filtering
- */
-export function restartBetweenTestsArgs(options, suite, forwardedMachArgs) {
-    if (options.restartBetweenTests !== true)
-        return [];
-    if (suite !== 'mochitest') {
-        throw new GeneralError("--restart-between-tests forwards the mochitest harness's per-file browser restart; the " +
-            'xpcshell harness has none, and generic `mach test` dispatch would hand it to every ' +
-            'suite. Narrow the paths to browser-chrome/mochitest files (and drop --generic-mach-test).');
-    }
-    return forwardedMachArgs.includes('--restart-between-tests') ? [] : ['--restart-between-tests'];
-}

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

@@ -1,61 +0,0 @@
-/**
- * Per-run lines and the aggregate verdict of a multi-run `fireforge test`
- * (`--repeat`, mixed harnesses, `--negative-control`). Pure: the
- * orchestration in `test-orchestrate.ts` feeds it the verdict line each
- * sub-run would have printed, captured instead of written.
- */
-/** One finished sub-run. */
-export interface SubRunResult {
-    /** 1-based repetition this run belongs to. */
-    repetition: number;
-    /** The harness half of a mixed invocation. */
-    harness?: 'xpcshell' | 'mochitest';
-    /** The captured verdict, without the `FIREFORGE-VERDICT: ` prefix. */
-    body: string;
-    passed: boolean;
-    /** `reason=` of a failed run. */
-    reason?: string;
-    /** `note=` of a failed run, when it carried one. */
-    note?: string;
-    /** What the sub-run threw, if anything. */
-    error?: unknown;
-}
-/**
- * How a negative control came out: `caught` when every repetition went red
- * on test failures, `missed` when a repetition stayed green (the tests did
- * not detect the mutation), `inconclusive` when any run failed for another
- * reason or the invocation stopped early.
- */
-export type ControlOutcome = 'caught' | 'missed' | 'inconclusive';
-/**
- * Parses a captured verdict line into a sub-run result.
- *
- * @param line - The captured line, or undefined when the sub-run wrote none
- */
-export declare function parseCapturedVerdict(line: string | undefined): Pick<SubRunResult, 'body' | 'passed' | 'reason' | 'note'>;
-/**
- * The `FIREFORGE-RUN:` line for one sub-run: the verdict it would have
- * printed alone, plus `run=<i>/<n>` and, for a mixed invocation,
- * `harness=`. Never `FIREFORGE-VERDICT:`, so the invocation keeps exactly
- * one verdict line.
- */
-export declare function formatRunLine(result: SubRunResult, index: number, total: number): string;
-/** The failed run with the most structural reason, or undefined when all passed. */
-export declare function worstRun(results: readonly SubRunResult[]): SubRunResult | undefined;
-/**
- * Derives a negative control's outcome.
- *
- * @param results - Every finished sub-run
- * @param repetitions - How many repetitions were planned
- * @param complete - False when the invocation stopped before its last run
- */
-export declare function deriveControlOutcome(results: readonly SubRunResult[], repetitions: number, complete: boolean): ControlOutcome;
-/**
- * The aggregate verdict body. A single planned run (a lone control) keeps
- * its own line, counts included; several aggregate to `PASS runs=<n>/<n>`
- * or `FAIL reason=<most structural> [note=] runs=<passed>/<planned>`.
- * A control appends `control=<outcome>`.
- */
-export declare function formatAggregateBody(results: readonly SubRunResult[], plannedTotal: number, control?: ControlOutcome): string;
-/** One-line human summary of a control's outcome. */
-export declare function describeControlOutcome(outcome: ControlOutcome): string;

package/dist/src/commands/test-multi-verdict.js

@@ -1,112 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Per-run lines and the aggregate verdict of a multi-run `fireforge test`
- * (`--repeat`, mixed harnesses, `--negative-control`). Pure: the
- * orchestration in `test-orchestrate.ts` feeds it the verdict line each
- * sub-run would have printed, captured instead of written.
- */
-/** The prefix every verdict line starts with. */
-const VERDICT_PREFIX = 'FIREFORGE-VERDICT: ';
-/**
- * Parses a captured verdict line into a sub-run result.
- *
- * @param line - The captured line, or undefined when the sub-run wrote none
- */
-export function parseCapturedVerdict(line) {
-    const body = (line ?? `${VERDICT_PREFIX}FAIL reason=preflight`).slice(VERDICT_PREFIX.length);
-    const passed = body.startsWith('PASS');
-    const reason = /(?:^| )reason=(\S+)/.exec(body)?.[1];
-    const note = /(?:^| )note=(\S+)/.exec(body)?.[1];
-    return {
-        body,
-        passed,
-        ...(reason === undefined ? {} : { reason }),
-        ...(note === undefined ? {} : { note }),
-    };
-}
-/**
- * The `FIREFORGE-RUN:` line for one sub-run: the verdict it would have
- * printed alone, plus `run=<i>/<n>` and, for a mixed invocation,
- * `harness=`. Never `FIREFORGE-VERDICT:`, so the invocation keeps exactly
- * one verdict line.
- */
-export function formatRunLine(result, index, total) {
-    const harness = result.harness === undefined ? '' : ` harness=${result.harness}`;
-    return `FIREFORGE-RUN: ${result.body} run=${index + 1}/${total}${harness}`;
-}
-/** Most structural first: the reason an aggregate failure reports. */
-const REASON_RANK = [
-    'inconclusive',
-    'preflight',
-    'crash',
-    'server-startup',
-    'harness-arguments',
-    'no-tests',
-    'test-failures',
-];
-function rankOf(reason) {
-    const rank = REASON_RANK.indexOf(reason ?? '');
-    return rank === -1 ? REASON_RANK.length : rank;
-}
-/** The failed run with the most structural reason, or undefined when all passed. */
-export function worstRun(results) {
-    let worst;
-    for (const result of results) {
-        if (result.passed)
-            continue;
-        if (worst === undefined || rankOf(result.reason) < rankOf(worst.reason))
-            worst = result;
-    }
-    return worst;
-}
-/**
- * Derives a negative control's outcome.
- *
- * @param results - Every finished sub-run
- * @param repetitions - How many repetitions were planned
- * @param complete - False when the invocation stopped before its last run
- */
-export function deriveControlOutcome(results, repetitions, complete) {
-    if (!complete)
-        return 'inconclusive';
-    if (results.some((result) => !result.passed && result.reason !== 'test-failures')) {
-        return 'inconclusive';
-    }
-    for (let repetition = 1; repetition <= repetitions; repetition += 1) {
-        const red = results.some((result) => result.repetition === repetition && result.reason === 'test-failures');
-        if (!red)
-            return 'missed';
-    }
-    return 'caught';
-}
-/**
- * The aggregate verdict body. A single planned run (a lone control) keeps
- * its own line, counts included; several aggregate to `PASS runs=<n>/<n>`
- * or `FAIL reason=<most structural> [note=] runs=<passed>/<planned>`.
- * A control appends `control=<outcome>`.
- */
-export function formatAggregateBody(results, plannedTotal, control) {
-    const controlKey = control === undefined ? '' : ` control=${control}`;
-    const only = results[0];
-    if (plannedTotal === 1 && only !== undefined)
-        return `${only.body}${controlKey}`;
-    const passed = results.filter((result) => result.passed).length;
-    const runs = ` runs=${passed}/${plannedTotal}`;
-    const worst = worstRun(results);
-    if (worst === undefined && results.length === plannedTotal)
-        return `PASS${runs}${controlKey}`;
-    const reason = worst?.reason ?? 'preflight';
-    const note = worst?.note === undefined ? '' : ` note=${worst.note}`;
-    return `FAIL reason=${reason}${note}${runs}${controlKey}`;
-}
-/** One-line human summary of a control's outcome. */
-export function describeControlOutcome(outcome) {
-    switch (outcome) {
-        case 'caught':
-            return 'Negative control: the tests went red on the mutation, as a control should (control=caught).';
-        case 'missed':
-            return 'Negative control: the tests STAYED GREEN with the mutation applied, so they do not detect it (control=missed).';
-        case 'inconclusive':
-            return 'Negative control: inconclusive, a run failed for a reason other than test failures or did not run (control=inconclusive).';
-    }
-}

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

@@ -1,70 +0,0 @@
-/**
- * Multi-run orchestration for `fireforge test`, all under the one
- * engine-session lock hold the command already has:
- *
- *  - mixed harness paths run as two consecutive mach invocations, xpcshell
- *    first, with one pre-test build (when `--build`) packaging both halves;
- *  - `--repeat <n>` runs the same selection n times, building once;
- *  - `--negative-control <diff>` applies a reviewed mutation after the
- *    build and right before each dispatch, and restores it after the run.
- *
- * Each sub-run is the ordinary single-run body. Its verdict line is
- * captured rather than printed (see `setVerdictCapture`) and echoed as a
- * `FIREFORGE-RUN:` line, and the invocation ends with one aggregate
- * `FIREFORGE-VERDICT:` line. A request that needs none of this runs the
- * body exactly as before.
- */
-import type { ControlBuildStamp } from '../core/build-baseline-types.js';
-import type { TestOptions } from '../types/commands/index.js';
-/** What the orchestrator asks of one sub-run beyond its paths and options. */
-export interface TestRunHooks {
-    /**
-     * Paths the pre-test build packages and records as coverage when they
-     * are wider than this run's own: the union of a mixed invocation's
-     * halves, so the second half runs build-less against the same build.
-     */
-    coveragePaths?: string[];
-    /** Runs after every preflight gate and the pre-test build, right before dispatch. */
-    beforeDispatch?: () => Promise<void>;
-    /**
-     * Runs right before the pre-test build: a negative control on compiled
-     * source, which only reaches the binary when the build compiles it.
-     */
-    beforeBuild?: () => Promise<void>;
-    /**
-     * Why the pre-test build must be a full `mach build`: `mach build faster`
-     * compiles nothing, so a compiled control's binary needs the full one.
-     */
-    fullBuildReason?: string;
-    /**
-     * Stamp the pre-test build records on its baseline because it compiles a
-     * negative control in (see `BuildBaseline.controlBuild`).
-     */
-    controlBuild?: ControlBuildStamp;
-    /**
-     * The stamp the first run's control build recorded, on every run after
-     * it: those runs test the binary that carries the control, with the
-     * control applied again, so the build-less gates accept that stamp and
-     * the fresh mtimes its restore left on the control's own targets.
-     */
-    ownControlBuild?: ControlBuildStamp;
-    /** `--repeat` run this sub-run is (1-based), for `--results`. */
-    repetition?: number;
-    /** Where dispatches write their mozlog raw logs (`--results`, `--shard-size`). */
-    rawLogDir?: string;
-}
-/** The single-run body (`runTestCommandBody`), injected to avoid an import cycle. */
-export type TestRunBody = (paths: string[], options: TestOptions, hooks: TestRunHooks) => Promise<void>;
-/**
- * Runs `fireforge test` as one or several sub-runs. Always recovers a
- * negative control a killed earlier run left applied, first.
- *
- * @param projectRoot - Project root
- * @param testPaths - The positional test paths
- * @param options - Parsed test options
- * @param body - The single-run body
- * @param onRefusal - Renders a sub-run's preflight refusal and emits its
- *   `FAIL reason=preflight` verdict (captured), as `testCommand` does for a
- *   single run
- */
-export declare function orchestrateTestRuns(projectRoot: string, testPaths: string[], options: TestOptions, body: TestRunBody, onRefusal: (error: unknown) => void): Promise<void>;

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

@@ -1,277 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Multi-run orchestration for `fireforge test`, all under the one
- * engine-session lock hold the command already has:
- *
- *  - mixed harness paths run as two consecutive mach invocations, xpcshell
- *    first, with one pre-test build (when `--build`) packaging both halves;
- *  - `--repeat <n>` runs the same selection n times, building once;
- *  - `--negative-control <diff>` applies a reviewed mutation after the
- *    build and right before each dispatch, and restores it after the run.
- *
- * Each sub-run is the ordinary single-run body. Its verdict line is
- * captured rather than printed (see `setVerdictCapture`) and echoed as a
- * `FIREFORGE-RUN:` line, and the invocation ends with one aggregate
- * `FIREFORGE-VERDICT:` line. A request that needs none of this runs the
- * body exactly as before.
- */
-import { getProjectPaths } from '../core/config.js';
-import { applyNegativeControl, planNegativeControl, recoverPendingNegativeControl, restoreNegativeControl, } from '../core/negative-control.js';
-import { formatCompiledControlBuildNotice, formatCompiledControlRefusal, } from '../core/negative-control-compiled.js';
-import { getActiveRunLogPath, writeToActiveRunLog } from '../core/run-log.js';
-import { GeneralError, InvalidArgumentError, PreflightRefusalError } from '../errors/base.js';
-import { TestFailureError } from '../errors/build.js';
-import { toError } from '../utils/errors.js';
-import { info, notice, success } from '../utils/logger.js';
-import { stripEnginePrefix } from '../utils/paths.js';
-import { controlBuildRecorded, runControlRestoreBuild } from './test-control-restore.js';
-import { classifyTestHarnesses } from './test-modes.js';
-import { deriveControlOutcome, describeControlOutcome, formatAggregateBody, formatRunLine, parseCapturedVerdict, worstRun, } from './test-multi-verdict.js';
-import { rearmSpentWaits } from './test-prelock.js';
-import { emitAggregateVerdict, emitFailVerdict, setVerdictCapture, setVerdictRunAttribute, verdictEmitted, } from './test-verdict.js';
-function assertMultiRunUsage(testPaths, options) {
-    const flag = options.negativeControl !== undefined ? '--negative-control' : '--repeat';
-    if (testPaths.length === 0) {
-        throw new InvalidArgumentError(`${flag} needs explicit test paths.`, flag);
-    }
-    if (options.buildOnly === true || options.canary !== undefined || options.auto === true) {
-        throw new InvalidArgumentError(`${flag} runs tests, so it cannot be combined with --build-only, --canary or --auto.`, flag);
-    }
-}
-async function splitHarnesses(engineDir, testPaths, options) {
-    // `--build-only` packages a mixed union itself and dispatches nothing.
-    if (testPaths.length === 0 || options.buildOnly === true || options.canary !== undefined) {
-        return undefined;
-    }
-    const normalized = testPaths.map((path) => stripEnginePrefix(path).trim());
-    const classification = await classifyTestHarnesses(engineDir, normalized);
-    if (classification.xpcshell.length === 0 || classification.nonXpcshell.length === 0) {
-        return undefined;
-    }
-    notice(`Mixed harnesses: running ${classification.xpcshell.length} xpcshell path(s), then ` +
-        `${classification.nonXpcshell.length} browser/mochitest path(s), as two mach invocations ` +
-        'under this lock hold' +
-        (options.build === true ? ', after one pre-test build that packages both.' : '.'));
-    return [
-        { harness: 'xpcshell', paths: classification.xpcshell },
-        { harness: 'mochitest', paths: classification.nonXpcshell },
-    ];
-}
-/** Options for every run after the first: the build and doctor run once. */
-function laterRunOptions(options) {
-    // A later run follows the earlier runs' work under the same lock hold, so
-    // its browser and port checks wait out the budgets again.
-    const later = { ...rearmSpentWaits(options) };
-    delete later.build;
-    delete later.extendCoverage;
-    delete later.refuseUnexportedDrift;
-    delete later.doctor;
-    return later;
-}
-async function planRuns(engineDir, testPaths, options) {
-    const repeat = options.repeat ?? 1;
-    const control = options.negativeControl !== undefined;
-    if (repeat > 1 || control)
-        assertMultiRunUsage(testPaths, options);
-    const halves = await splitHarnesses(engineDir, testPaths, options);
-    if (halves === undefined && repeat === 1 && !control)
-        return undefined;
-    const groups = halves ?? [
-        { paths: testPaths },
-    ];
-    const union = halves?.flatMap((half) => half.paths);
-    const runs = [];
-    for (let repetition = 1; repetition <= repeat; repetition += 1) {
-        for (const group of groups) {
-            const first = runs.length === 0;
-            runs.push({
-                repetition,
-                ...(group.harness === undefined ? {} : { harness: group.harness }),
-                paths: group.paths,
-                options: first ? options : laterRunOptions(options),
-                hooks: {
-                    repetition,
-                    ...(first && union !== undefined ? { coveragePaths: union } : {}),
-                },
-            });
-        }
-    }
-    return runs;
-}
-function writeRunLine(line) {
-    process.stdout.write(`${line}\n`);
-    writeToActiveRunLog(`${line}\n`);
-}
-function controlHook(paths, plan, slot) {
-    return async () => {
-        slot.applied = await applyNegativeControl(paths, plan);
-        notice(`Negative control applied to ${plan.targets.map((target) => `engine/${target.enginePath}`).join(', ')}; ` +
-            'it stays in place until this run has finished.');
-    };
-}
-/** The stamp a compiled control's pre-test build records on its baseline. */
-function compiledControlStamp(options, compiled) {
-    if (compiled === undefined || options.negativeControl === undefined)
-        return undefined;
-    return {
-        diffFile: options.negativeControl,
-        targets: [...compiled],
-        appliedAt: new Date().toISOString(),
-    };
-}
-/**
- * After a compiled control was restored, rebuilds the binary that still
- * carries it, when this run's control build recorded its stamp, and
- * stamps `control-restore-build=done|failed` on the verdict.
- */
-async function rebuildAfterCompiledControl(projectRoot, stamp, options) {
-    if (stamp === undefined || !(await controlBuildRecorded(projectRoot, stamp)))
-        return;
-    setVerdictRunAttribute('control-restore-build', await runControlRestoreBuild(projectRoot, stamp, options.harnessRetries));
-}
-/**
- * Throws the invocation's error after the aggregate verdict, or returns
- * when the invocation succeeded (all runs green, or a control caught).
- */
-function finishInvocation(results, plannedTotal, control) {
-    if (control !== undefined)
-        info(describeControlOutcome(control));
-    if (control === 'caught') {
-        success('Negative control caught.');
-        return;
-    }
-    if (control === 'missed') {
-        throw new TestFailureError('Negative control stayed green: no run went red with the mutation applied, so the selected tests do not detect it.', 'mach test', undefined, getActiveRunLogPath());
-    }
-    const worst = worstRun(results);
-    if (worst === undefined)
-        return;
-    if (worst.reason === 'preflight' || worst.reason === 'inconclusive') {
-        throw worst.error instanceof Error
-            ? worst.error
-            : new GeneralError(`Run ${results.indexOf(worst) + 1} was refused.`);
-    }
-    const failing = results
-        .map((result, index) => ({ result, index }))
-        .filter(({ result }) => !result.passed)
-        .map(({ result, index }) => `run ${index + 1} (${result.reason ?? 'failed'})`);
-    throw new TestFailureError(`${failing.length} of ${plannedTotal} run(s) did not pass: ${failing.join(', ')}. See each FIREFORGE-RUN line above.`, 'mach test', undefined, getActiveRunLogPath());
-}
-/**
- * Runs `fireforge test` as one or several sub-runs. Always recovers a
- * negative control a killed earlier run left applied, first.
- *
- * @param projectRoot - Project root
- * @param testPaths - The positional test paths
- * @param options - Parsed test options
- * @param body - The single-run body
- * @param onRefusal - Renders a sub-run's preflight refusal and emits its
- *   `FAIL reason=preflight` verdict (captured), as `testCommand` does for a
- *   single run
- */
-export async function orchestrateTestRuns(projectRoot, testPaths, options, body, onRefusal) {
-    const projectPaths = getProjectPaths(projectRoot);
-    const controlPaths = {
-        engineDir: projectPaths.engine,
-        fireforgeDir: projectPaths.fireforgeDir,
-    };
-    await recoverPendingNegativeControl(controlPaths);
-    const runs = await planRuns(projectPaths.engine, testPaths, options);
-    if (runs === undefined) {
-        await body(testPaths, options, {});
-        return;
-    }
-    const plan = options.negativeControl === undefined
-        ? undefined
-        : await planNegativeControl(projectRoot, projectPaths.engine, options.negativeControl, {
-            deferApplyCheck: options.build === true,
-        });
-    // A compiled target only reaches the binary through a build, so its
-    // control goes in before the first run's pre-test build.
-    const compiled = plan?.compiled;
-    const compiledControl = compiled !== undefined;
-    if (compiledControl) {
-        if (options.build !== true) {
-            throw new PreflightRefusalError(formatCompiledControlRefusal(compiled), 'negative-control');
-        }
-        setVerdictRunAttribute('control-build', 'compiled');
-    }
-    const controlStamp = compiledControlStamp(options, compiled);
-    const results = [];
-    let restoreError;
-    for (const [index, run] of runs.entries()) {
-        notice(`Run ${index + 1}/${runs.length}${run.harness === undefined ? '' : ` (${run.harness})`}` +
-            `${plan === undefined ? '' : ', negative control'}: ${run.paths.join(' ')}`);
-        const capture = {};
-        const slot = {};
-        let error;
-        setVerdictCapture(capture);
-        try {
-            await body(run.paths, run.options, {
-                ...run.hooks,
-                ...(plan === undefined
-                    ? {}
-                    : compiledControl && index === 0
-                        ? {
-                            beforeBuild: controlHook(controlPaths, plan, slot),
-                            fullBuildReason: formatCompiledControlBuildNotice(compiled),
-                            ...(controlStamp === undefined ? {} : { controlBuild: controlStamp }),
-                        }
-                        : {
-                            beforeDispatch: controlHook(controlPaths, plan, slot),
-                            ...(controlStamp === undefined ? {} : { ownControlBuild: controlStamp }),
-                        }),
-            });
-        }
-        catch (caught) {
-            error = caught;
-            if (capture.line === undefined)
-                onRefusal(caught);
-        }
-        finally {
-            setVerdictCapture(undefined);
-        }
-        // Only a kill writes a real verdict while a capture is installed (see
-        // emitKilledVerdict). The invocation is over: restore, start nothing
-        // more, print nothing after that line.
-        const killed = verdictEmitted();
-        if (slot.applied !== undefined) {
-            try {
-                const restored = await restoreNegativeControl(slot.applied);
-                info(`Negative control restored byte-exact: ${restored.restored.length} file(s).`);
-            }
-            catch (caught) {
-                restoreError = caught;
-            }
-        }
-        if (killed)
-            throw toError(restoreError ?? error ?? new GeneralError('The run was killed.'));
-        const result = {
-            repetition: run.repetition,
-            ...(run.harness === undefined ? {} : { harness: run.harness }),
-            ...parseCapturedVerdict(capture.line),
-            ...(error === undefined ? {} : { error }),
-        };
-        results.push(result);
-        writeRunLine(formatRunLine(result, index, runs.length));
-        if (restoreError !== undefined)
-            break;
-        if (result.reason === 'preflight' || result.reason === 'inconclusive')
-            break;
-    }
-    if (restoreError !== undefined) {
-        emitFailVerdict('inconclusive', 'negative-control-restore');
-        throw toError(restoreError);
-    }
-    // The source is back byte-exact, but the binary still carries the
-    // compiled control: rebuild it under this same hold (see
-    // test-control-restore.ts). Only after every run, since a later
-    // `--repeat` run tests the same control-built binary.
-    await rebuildAfterCompiledControl(projectRoot, controlStamp, options);
-    const repetitions = options.repeat ?? 1;
-    const control = plan === undefined
-        ? undefined
-        : deriveControlOutcome(results, repetitions, results.length === runs.length);
-    emitAggregateVerdict(formatAggregateBody(results, runs.length, control));
-    finishInvocation(results, runs.length, control);
-}