@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/test-stale-gate.js

@@ -7,9 +7,12 @@
  * stays wiring. The probes and refusal copy live in
  * `src/core/test-stale-check.ts`.
  */
-import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
+import { filterByCarriedFullCoverage } from '../core/coverage-dispatch.js';
+import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, FULL_SUITE_REQUEST, } from '../core/test-stale-check.js';
+import { formatStaleExemptions } from '../core/test-stale-exempt.js';
 import { PreflightRefusalError } from '../errors/base.js';
-import { warn } from '../utils/logger.js';
+import { info, warn } from '../utils/logger.js';
+import { describePerfStaleImpact } from './test-perf-scope.js';
 /**
  * Stale-build preflight: when `--build` was not requested, detect packageable
  * engine edits since the last successful build and fail up front unless the
@@ -30,38 +33,67 @@ import { warn } from '../utils/logger.js';
  * a full-suite request would refuse a probe that touches no fixtures. The
  * stale-content refusal still applies to it unchanged.
  */
-export async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths) {
+export async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths, 
+/** `quiet`: refuse only, without the exemption note (the pre-lock pass). */
+gate = {}) {
     const stale = await checkStaleBuildForTest(projectRoot, engineDir);
     const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
     if (!dispatchesNoTests) {
-        const recordedCoverage = stale.baseline?.testPackagingCoverage;
-        const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
-        if (uncovered.length > 0) {
-            // The refusal is correct on its own. Naming the manifest that gained
-            // an entry is the triage step it otherwise leaves to the reader.
-            const changedManifests = await findChangedTestManifestsForPaths(engineDir, stale.baseline, uncovered);
-            throw new PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests), 'coverage-replaced');
-        }
+        await enforceCoverageGate(engineDir, stale.baseline, normalizedPaths);
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);
-    const staleMessage = stale.stale
-        ? `${formatStaleBuildWarning(stale)}\n\n` +
-            'Run `fireforge test --build` to refresh the packaged runtime first — that is almost ' +
-            'always the right move, because the usual cause is your own edit landing between the ' +
-            'last build and this run.\n\n' +
-            '`--allow-stale-build` is NOT the general escape hatch: it accepts a packaging that ' +
-            'predates the edit under test, so the run tests the OLD code. Pass it only when you ' +
-            'rebuilt out-of-band (outside FireForge) and know the packaged runtime already contains ' +
-            'the change.'
-        : undefined;
-    if (staleMessage !== undefined) {
-        if (options.allowStaleBuild === true) {
-            warn(staleMessage);
-        }
-        else {
-            throw new PreflightRefusalError(staleMessage, 'stale-build');
-        }
+    const exempt = stale.exempt ?? [];
+    if (!stale.stale && exempt.length > 0 && gate.quiet !== true) {
+        info(`Stale-build preflight: ${exempt.length} edit(s) since the last build need no rebuild: ${formatStaleExemptions(exempt)}.`);
     }
+    if (!stale.stale)
+        return;
+    // The one-line repackaging command, so a build-less sitting (a perf
+    // series) can repackage and continue without dispatching anything.
+    const repackage = normalizedPaths.length > 0
+        ? `fireforge test --build-only ${normalizedPaths.join(' ')}`
+        : 'fireforge build --ui';
+    const perfImpact = options.perfSamples === undefined
+        ? ''
+        : `\n\n${await describePerfStaleImpact(engineDir, stale.changedPaths, normalizedPaths)}`;
+    const staleMessage = `${formatStaleBuildWarning(stale)}\n\n` +
+        'Run `fireforge test --build` to refresh the packaged runtime first — that is almost ' +
+        'always the right move, because the usual cause is your own edit landing between the ' +
+        'last build and this run. To repackage without running anything: ' +
+        `\`${repackage}\`.${perfImpact}\n\n` +
+        '`--allow-stale-build` is NOT the general escape hatch: it accepts a packaging that ' +
+        'predates the edit under test, so the run tests the OLD code. Pass it only when you ' +
+        'rebuilt out-of-band (outside FireForge) and know the packaged runtime already contains ' +
+        'the change.';
+    if (options.allowStaleBuild === true) {
+        warn(staleMessage);
+    }
+    else {
+        throw new PreflightRefusalError(staleMessage, 'stale-build');
+    }
+}
+/**
+ * Packaging-coverage refusal. A path outside the recorded scoped list is
+ * still covered while its own staging inputs are unchanged against a
+ * carried full-build anchor. The refusal names, per uncovered path, the
+ * inputs that changed.
+ */
+async function enforceCoverageGate(engineDir, baseline, normalizedPaths) {
+    const recordedCoverage = baseline?.testPackagingCoverage;
+    const outsideList = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
+    if (outsideList.length === 0)
+        return;
+    const remaining = await filterByCarriedFullCoverage(engineDir, baseline, outsideList, FULL_SUITE_REQUEST);
+    if (remaining.length === 0)
+        return;
+    const uncovered = remaining.map((request) => request.path);
+    // The refusal is correct on its own. Naming the manifest that gained
+    // an entry is the triage step it otherwise leaves to the reader.
+    const changedManifests = await findChangedTestManifestsForPaths(engineDir, baseline, uncovered);
+    throw new PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests, {
+        changedInputs: Object.fromEntries(remaining.map((request) => [request.path, request.changed])),
+        carriesFullAnchor: baseline?.fullCoverageAnchor !== undefined,
+    }), 'coverage-replaced');
 }
 /**
  * Compiled-StaticComponents gate: refuses runs whose child process would

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

@@ -13,7 +13,7 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  */
 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' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed';
+export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed' | 'furnace-applied' | 'furnace-apply' | 'furnace-skipped' | 'control-build' | 'drift-tolerated' | 'lock' | 'jobs' | 'results';
 /** Records an additive attribute for this run's verdict line. */
 export declare function setVerdictRunAttribute(key: VerdictRunAttributeKey, value: string): void;
 /**
@@ -30,6 +30,15 @@ export declare function addVerdictRunCount(key: 'orphans-reaped', count: number)
 export declare function resetVerdictEmission(): void;
 /** True once this run has written its `FIREFORGE-VERDICT:` line. */
 export declare function verdictEmitted(): boolean;
+/** Installs (or, with `undefined`, removes) the sub-run capture slot. */
+export declare function setVerdictCapture(slot: {
+    line?: string;
+} | undefined): void;
+/**
+ * Emits a multi-run aggregate verdict. `body` is everything after the
+ * `FIREFORGE-VERDICT: ` prefix.
+ */
+export declare function emitAggregateVerdict(body: string): void;
 /**
  * Emits the classifier-derived verdict for a completed harness run, with
  * the aggregate `shards=<passed>/<total>` suffix for sharded runs.
@@ -37,6 +46,7 @@ export declare function verdictEmitted(): boolean;
 export declare function emitHarnessVerdict(verdict: HarnessRunVerdict, shards?: {
     passed: number;
     total: number;
+    failed?: readonly string[];
 }): void;
 /** Emits the pathless `--doctor` PASS verdict. */
 export declare function emitPassVerdict(): void;

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

@@ -51,11 +51,31 @@ export function resetVerdictEmission() {
     emitted = false;
     armed = true;
     runAttributes.clear();
+    capture = undefined;
     setStdoutSealed(false);
 }
+/**
+ * The sub-run capture slot of a multi-run invocation (`--repeat`, mixed
+ * harnesses, `--negative-control`; see `test-orchestrate.ts`). While one is
+ * installed, a sub-run's verdict line is recorded here, first write wins as
+ * on stdout, and nothing is printed or sealed, so the invocation can still
+ * end with its own single aggregate line.
+ */
+let capture;
 /** True once this run has written its `FIREFORGE-VERDICT:` line. */
 export function verdictEmitted() {
-    return emitted;
+    return capture === undefined ? emitted : capture.line !== undefined;
+}
+/** Installs (or, with `undefined`, removes) the sub-run capture slot. */
+export function setVerdictCapture(slot) {
+    capture = slot;
+}
+/**
+ * Emits a multi-run aggregate verdict. `body` is everything after the
+ * `FIREFORGE-VERDICT: ` prefix.
+ */
+export function emitAggregateVerdict(body) {
+    writeVerdictLine(`FIREFORGE-VERDICT: ${body}`);
 }
 /**
  * Writes the run's single verdict line to raw stdout (clack's renderer can
@@ -68,6 +88,10 @@ export function verdictEmitted() {
  * rendering after an emit-then-throw path, routes to stderr.
  */
 function writeVerdictLine(line) {
+    if (capture !== undefined) {
+        capture.line ??= line;
+        return;
+    }
     if (emitted)
         return;
     emitted = true;
@@ -130,6 +154,9 @@ export function emitFailVerdict(reason, note) {
 export function emitKilledVerdict(signal) {
     if (!armed || emitted)
         return false;
+    // A kill ends the whole invocation, so a sub-run capture must not
+    // swallow the one line that says so.
+    capture = undefined;
     writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=killed signal=${signal}`);
     return true;
 }

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

@@ -10,8 +10,13 @@ import type { TestOptions } from '../types/commands/index.js';
  * since no harness classification exists for such a run. Writers closer to
  * the harness (doctor, canary, single, sharded, the engine-generation
  * guard) emit first and win.
+ * The lock-free checks (launchable binary, named-file checkJs, the
+ * `--wait-browser`/`--wait-port` budgets) run first, outside `underLock`,
+ * so a run that would be refused or would only wait never holds a place in
+ * the engine lock queue. See `test-prelock.ts`.
  * @param projectRoot - Root directory of the project
  * @param testPaths - Test file or directory paths
  * @param options - Test options
+ * @param underLock - Runs the rest of the command under the engine session lock
  */
-export declare function testCommand(projectRoot: string, testPaths: string[], options?: TestOptions): Promise<void>;
+export declare function testCommand(projectRoot: string, testPaths: string[], options?: TestOptions, underLock?: (body: () => Promise<void>, mode?: 'exclusive' | 'shared') => Promise<void>): Promise<void>;

package/dist/src/commands/test.js

@@ -1,32 +1,33 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
-import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
-import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
+import { hasBuildArtifacts } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
 import { waitForPreflight } from '../core/preflight-wait.js';
-import { closeActiveRunLog, openRunLog, setActiveRunLog, writeToActiveRunLog, } from '../core/run-log.js';
+import { closeActiveRunLog, keepRunLogCopy, openRunLog, setActiveRunLog, writeToActiveRunLog, } from '../core/run-log.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
 import { cleanupProfileFiles, stageProfileFiles, } from '../core/test-profile-files.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
-import { FireForgeError, GeneralError, PreflightRefusalError } from '../errors/base.js';
-import { BuildError } from '../errors/build.js';
+import { FireForgeError, GeneralError, LockContentionError, PreflightRefusalError, } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, notice, warn } from '../utils/logger.js';
+import { info, intro, warn } from '../utils/logger.js';
 import { resolveWaitLockSeconds } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { appendMarionetteForwardingArgs, ensureTestBrowserEnvironment, runDoctorPreflight, } from './test-browser-preflight.js';
 import { runTestBuildPhase } from './test-build-phase.js';
-import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
-import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed, shuffleTestGroups, } from './test-harness-env.js';
+import { assertParallelTestUsage, dispatchTests } from './test-dispatch.js';
+import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed } from './test-harness-env.js';
 import { removePgidFile, setActivePgidFile } from './test-harness-teardown.js';
-import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
-import { DEFAULT_HARNESS_RETRIES, finalizeShardedOutcome, runShardedTests, runTestsWithRetries, } from './test-run.js';
-import { emitFailVerdict, resetVerdictEmission, verdictEmitted } from './test-verdict.js';
+import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, resolveCanaryPath, restartBetweenTestsArgs, } from './test-modes.js';
+import { orchestrateTestRuns } from './test-orchestrate.js';
+import { resolveLaunchablePathForTests, runTestPreLockPreflight, TEST_BUILD_PREFLIGHT, } from './test-prelock.js';
+import { resetTestResults, withRawLogDir, writeTestResults } from './test-results.js';
+import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
+import { emitFailVerdict, resetVerdictEmission, setVerdictRunAttribute, verdictEmitted, } from './test-verdict.js';
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
     for (const testPath of testPaths) {
@@ -77,20 +78,6 @@ function filterRedundantXpcshellFlavorArgs(machArgs, classification) {
     }
     return filtered;
 }
-async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
-    if (!objDir)
-        return undefined;
-    const bundleCheck = await hasRunnableBundle(engineDir, binaryName, objDir);
-    if (!bundleCheck.runnable) {
-        const expectedSuffix = bundleCheck.expectedPath
-            ? ` (expected at engine/${bundleCheck.expectedPath})`
-            : '';
-        throw new GeneralError(`Tests require a complete launchable build${expectedSuffix}. ` +
-            'The obj-*/dist/ tree exists but the launchable binary is missing — typically the result of an interrupted or partially failed `fireforge build`.\n\n' +
-            'Run "fireforge build" again and let it finish before retrying "fireforge test".');
-    }
-    return bundleCheck.expectedPath;
-}
 function logTestSelection(scopes) {
     if (scopes.length > 0) {
         const labels = scopes.map((scope) => scope.isDirectory && scope.testFileCount > 0
@@ -103,13 +90,6 @@ function logTestSelection(scopes) {
     }
     info('');
 }
-/** Build-artifact preflight wording for `fireforge test`. */
-const TEST_BUILD_PREFLIGHT = {
-    label: 'Tests',
-    requirement: 'Tests require a completed build.',
-    remediation: "Run 'fireforge build' first, then run 'fireforge test'.",
-    requireExisting: true,
-};
 /**
  * Runs the test command to execute mach tests.
  *
@@ -121,17 +101,22 @@ const TEST_BUILD_PREFLIGHT = {
  * since no harness classification exists for such a run. Writers closer to
  * the harness (doctor, canary, single, sharded, the engine-generation
  * guard) emit first and win.
+ * The lock-free checks (launchable binary, named-file checkJs, the
+ * `--wait-browser`/`--wait-port` budgets) run first, outside `underLock`,
+ * so a run that would be refused or would only wait never holds a place in
+ * the engine lock queue. See `test-prelock.ts`.
  * @param projectRoot - Root directory of the project
  * @param testPaths - Test file or directory paths
  * @param options - Test options
+ * @param underLock - Runs the rest of the command under the engine session lock
  */
-export async function testCommand(projectRoot, testPaths, options = {}) {
+export async function testCommand(projectRoot, testPaths, options = {}, underLock = (body) => body()) {
     intro('FireForge Test');
     resetVerdictEmission();
     // Opened before any work so a preflight refusal is logged too. Those are
     // exactly the runs whose only output a `tail` throws away. Closed in
     // `finally`, after the verdict line has already read the path.
-    setActiveRunLog(await openRunLog(projectRoot, 'test'));
+    setActiveRunLog(await keepRunLogCopy(await openRunLog(projectRoot, 'test'), options.keepLog, 'test'));
     setActivePgidFile(options.pgidFile);
     let staged;
     try {
@@ -139,12 +124,43 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             staged = await stageProfileFiles(projectRoot, options.profileFile);
             options = { ...options, machArg: [...(options.machArg ?? []), ...staged.args] };
         }
-        await runTestCommandBody(projectRoot, testPaths, options, staged?.env);
+        assertParallelTestUsage(testPaths, options);
+        const lockedOptions = await runTestPreLockPreflight(projectRoot, testPaths, options);
+        const profileEnv = staged?.env;
+        // The pre-lock pass resolved `sharedLock` against config and the run's shape.
+        const lockMode = lockedOptions.sharedLock === true ? 'shared' : 'exclusive';
+        if (lockMode === 'shared')
+            setVerdictRunAttribute('lock', 'shared');
+        resetTestResults();
+        if (options.results !== undefined) {
+            setVerdictRunAttribute('results', resolve(projectRoot, options.results));
+        }
+        const orchestrate = (rawLogDir) => orchestrateTestRuns(projectRoot, testPaths, lockedOptions, (paths, runOptions, hooks) => runTestCommandBody(projectRoot, paths, runOptions, profileEnv, {
+            ...hooks,
+            ...(rawLogDir === undefined ? {} : { rawLogDir }),
+        }), (error) => {
+            renderPreflightRefusal(error);
+            emitFailVerdict('preflight', refusalNote(error));
+        });
+        const collectsResults = options.results !== undefined || options.shardSize !== undefined;
+        try {
+            await underLock(() => (collectsResults ? withRawLogDir((dir) => orchestrate(dir)) : orchestrate()), lockMode);
+        }
+        finally {
+            if (options.results !== undefined) {
+                await writeResultsFile(resolve(projectRoot, options.results));
+            }
+        }
     }
     catch (error) {
         if (!verdictEmitted()) {
-            renderPreflightRefusal(error);
-            emitFailVerdict('preflight', refusalNote(error));
+            if (error instanceof LockContentionError) {
+                emitFailVerdict('lock-timeout');
+            }
+            else {
+                renderPreflightRefusal(error);
+                emitFailVerdict('preflight', refusalNote(error));
+            }
         }
         throw error;
     }
@@ -167,6 +183,15 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         }
     }
 }
+/** Writes `--results`; a failure warns, since the run's verdict is already out. */
+async function writeResultsFile(path) {
+    try {
+        await writeTestResults(path);
+    }
+    catch (error) {
+        warn(`Could not write --results ${path}: ${toError(error).message}`);
+    }
+}
 /** The refusal class a preflight gate named, when it named one. */
 function refusalNote(error) {
     return error instanceof PreflightRefusalError ? error.note : undefined;
@@ -201,24 +226,6 @@ function renderPreflightRefusal(error) {
     process.stdout.write(block);
     writeToActiveRunLog(block);
 }
-/**
- * Verifies `engine/` did not change under the run 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, powerChanged = false) {
-    try {
-        await assertEngineGenerationUnchanged(engineDir, before);
-        if (powerChanged)
-            throw new GeneralError('Perf power source changed during the run; repeat this sitting on a stable power source.');
-    }
-    catch (error) {
-        emitFailVerdict('inconclusive');
-        throw error;
-    }
-}
 async function guardBuildBrowser(engineDir, launchablePath, options) {
     if ((options.build || options.buildOnly) && launchablePath) {
         await waitForPreflight(() => ensureLaunchableBrowserNotRunning(join(engineDir, launchablePath), {
@@ -255,9 +262,40 @@ function prepareDispatchArguments(classification, options, canaryPath, projectCo
         ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
         : [];
     const extraArgs = prepareExtraMachArgs(options, shuffleSeed, canaryPath, projectConfig, forwardedMachArgs);
+    // A `--shard-size` chunk runs several files in one browser; mochitest
+    // restarts it between them so a chunk judges each file as a shard would.
+    const restart = options.shardSize !== undefined && suite === 'mochitest'
+        ? { ...options, restartBetweenTests: true }
+        : options;
+    extraArgs.push(...restartBetweenTestsArgs(restart, suite, forwardedMachArgs));
     return { suite, shuffleSeed, extraArgs };
 }
-async function runTestCommandBody(projectRoot, testPaths, options = {}, profileEnv) {
+/**
+ * Directory arguments mean exactly that directory: mozbuild's test resolver
+ * matches paths by string prefix, so a bare directory arg silently sweeps in
+ * prefix-named siblings, with `…/test/hominis` also running
+ * `…/test/hominis-tiles`, with no indication the scope widened. Each
+ * directory argument therefore dispatches as its enumerated explicit
+ * test-file list, which cannot prefix-match a sibling. A trailing-`/`
+ * normalization does not work, as mach still sweeps the sibling in. Any
+ * prefix-siblings are echoed so the narrowed scope is visible.
+ *
+ * xpcshell appdir auto-injection happens per harness invocation inside
+ * `runTestsWithRetries` (src/commands/test-run.ts) so sharded runs probe the
+ * manifest for each file individually. See src/core/xpcshell-appdir.ts for
+ * the full motivation.
+ */
+async function resolveDispatchGroups(engineDir, normalizedPaths) {
+    const scopes = await analyzeTestPathScopes(engineDir, normalizedPaths);
+    for (const scope of scopes) {
+        const notice = formatScopeNotice(scope);
+        if (notice)
+            info(notice);
+    }
+    logTestSelection(scopes);
+    return scopes.map((scope) => ({ label: scope.requestedPath, paths: scope.dispatchPaths }));
+}
+async function runTestCommandBody(projectRoot, testPaths, options = {}, profileEnv, hooks = {}) {
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     await assertEngineExists(paths.engine);
@@ -281,7 +319,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     // against an incomplete build surface the missing-bundle path instead of a
     // cryptic `Browser process exited during spawn (exit code 1, signal none).
     // stderr tail: (empty)`.
-    const launchablePath = await resolveLaunchablePathForTests(paths.engine, projectConfig.binaryName, buildCheck.objDir);
+    const launchablePath = await resolveLaunchablePathForTests(projectRoot, paths.engine, projectConfig.binaryName, buildCheck.objDir);
     const harnessRetries = options.harnessRetries ?? DEFAULT_HARNESS_RETRIES;
     // Normalized engine-relative request paths, hoisted above the build/stale
     // gate: the pre-test build records them as the packaging-coverage claim,
@@ -302,9 +340,12 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     // documented `--mach-arg --marionette-port=NNNN` route still hits the
     // wrapper preflight refusing on 2828 before the forwarded arg reaches
     // mach.
+    // A negative control on compiled source goes in here, so the build
+    // compiles it (see negative-control-compiled.ts).
+    await hooks.beforeBuild?.();
     if (await runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, {
         classification,
-        normalizedPaths,
+        normalizedPaths: hooks.coveragePaths ?? normalizedPaths,
     })) {
         return;
     }
@@ -324,31 +365,9 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     await assertTestPathsExist(paths.engine, normalizedPaths);
     const { suite, shuffleSeed, extraArgs } = prepareDispatchArguments(classification, options, canaryPath, projectConfig);
     appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
-    // Directory arguments mean exactly that directory: mozbuild's test
-    // resolver matches paths by string prefix, so a bare directory arg
-    // silently sweeps in prefix-named siblings, with `…/test/hominis` also
-    // running `…/test/hominis-tiles`, with no indication the scope widened. Each
-    // directory argument therefore dispatches as its enumerated explicit
-    // test-file list, which cannot prefix-match a sibling. A trailing-`/`
-    // normalization does not work, as mach still sweeps the sibling in. Any
-    // prefix-siblings are echoed so the narrowed scope is visible.
     // Classification above intentionally used the raw argument forms. Only the
     // mach dispatch needs the exact-match shape.
-    const scopes = await analyzeTestPathScopes(paths.engine, normalizedPaths);
-    const dispatchGroups = scopes.map((scope) => ({
-        label: scope.requestedPath,
-        paths: scope.dispatchPaths,
-    }));
-    for (const scope of scopes) {
-        const notice = formatScopeNotice(scope);
-        if (notice)
-            info(notice);
-    }
-    // xpcshell appdir auto-injection happens per harness invocation inside
-    // `runTestsWithRetries` (src/commands/test-run.ts) so sharded runs probe
-    // the manifest for each file individually. See src/core/xpcshell-appdir.ts
-    // for the full motivation.
-    logTestSelection(scopes);
+    const dispatchGroups = await resolveDispatchGroups(paths.engine, normalizedPaths);
     const harnessEnv = mergeHarnessEnv(buildPerfSampleEnv(projectRoot, projectConfig.binaryName, options.perfSamples), profileEnv, shuffleSeed === undefined ? undefined : { FIREFORGE_SHUFFLE_SEED: String(shuffleSeed) });
     const runCtx = {
         engineDir: paths.engine,
@@ -361,55 +380,32 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
         ...(options.fullOutput === true ? { fullOutput: true } : {}),
         ...(harnessEnv ? { env: harnessEnv } : {}),
         pgidFile: options.pgidFile,
+        ...(hooks.rawLogDir === undefined ? {} : { rawLogDir: hooks.rawLogDir }),
+        ...(hooks.repetition === undefined ? {} : { repetition: hooks.repetition }),
     };
     const postRebuildContext = options.build
         ? createPostRebuildFailureContext('fireforge test --build', normalizedPaths)
         : undefined;
+    // A negative control goes in here: after every gate and the build, so
+    // packaging cannot overwrite it and stale-build cannot refuse it.
+    await hooks.beforeDispatch?.();
     // Multi-argument requests shard into sequential harness runs by default:
     // one shared mochitest profile across files bleeds pref/media-query state
     // into later files. Sharding is per path argument: a directory argument
     // keeps its enumerated files together in one invocation, preserving the
     // one-browser-instance semantics of a directory run. `--no-shard` restores
-    // the combined invocation. 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.
-    // Hence the one-line notice stating what sharding does and does not
-    // exercise.
-    if (canaryPath === undefined && dispatchGroups.length > 1 && options.shard !== false) {
-        notice(`Sharding: running ${dispatchGroups.length} test path arguments in isolated browser 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.');
-        const generationBefore = await snapshotEngineGeneration(paths.engine);
-        let summary;
-        try {
-            const orderedGroups = shuffleSeed === undefined ? dispatchGroups : shuffleTestGroups(dispatchGroups, shuffleSeed);
-            summary = await runShardedTests(runCtx, orderedGroups, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, postRebuildContext));
-        }
-        finally {
-            // Runs before the aggregate verdict below: a mutated engine/ emits
-            // `FAIL reason=inconclusive` and throws, so an invalidated run can
-            // never print `PASS shards=N/N` first. (A throw here masks an
-            // in-flight shard error, as the plain assert always did.)
-            await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged);
-        }
-        finalizeShardedOutcome(summary);
-        return;
-    }
-    const combinedDispatchPaths = dispatchGroups.flatMap((group) => group.paths);
-    let outcome;
-    const generationBefore = await snapshotEngineGeneration(paths.engine);
-    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(paths.engine, generationBefore, runCtx.powerChanged);
-    }
-    if (canaryPath !== undefined) {
-        reportCanaryOutcome(outcome);
-        return;
-    }
-    finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext, options.headless === true);
+    // the combined invocation; `--shard-size` and `--jobs` reshape it (see
+    // test-dispatch.ts).
+    await dispatchTests({
+        engineDir: paths.engine,
+        runCtx,
+        dispatchGroups,
+        options,
+        projectConfig,
+        canaryPath,
+        shuffleSeed,
+        normalizedPaths,
+        xpcshellOnly,
+        postRebuildContext,
+    });
 }

package/dist/src/commands/token-lint.d.ts

@@ -0,0 +1,14 @@
+/** Options accepted by {@link tokenLintCommand}. */
+export interface TokenLintOptions {
+    /** Emit the machine-readable envelope instead of the human report. */
+    json?: boolean;
+}
+/**
+ * Runs `token lint`. Exits non-zero (GeneralError) when any finding is
+ * reported; with `--json` the report is written first, as `status --check
+ * --json` does.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Output-mode options
+ */
+export declare function tokenLintCommand(projectRoot: string, options?: TokenLintOptions): Promise<void>;