@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The `fireforge test` checks that run BEFORE the engine session lock.
+ *
+ * Everything here reads, never writes, so none of it needs the lock, and
+ * each check used to cost a full place in the lock queue before it could
+ * refuse:
+ *
+ *  - a missing launchable binary (a peer's interrupted build) refused only
+ *    after the wait, in every session, with nothing naming the cause;
+ *  - the named-file checkJs pass refused an `Element | null` after an
+ *    eighteen-minute queue;
+ *  - `--wait-browser` and `--wait-port` spent their budget holding the
+ *    lock, so every peer queued behind a run that was doing nothing.
+ *
+ * The in-lock ladder in `test.ts` still runs in full afterwards. That is
+ * the "re-check once under the lock": the waits this pass spent are
+ * stripped from the options it returns, so the in-lock browser and port
+ * checks probe once instead of waiting again.
+ */
+import { join } from 'node:path';
+import { describeBuildRunState, readBuildRunState } from '../core/build-run-record.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { assertEngineExists } from '../core/engine-precondition.js';
+import { autoPortsRequested } from '../core/harness-port-fallback.js';
+import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
+import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
+import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, extractForwardedMarionettePort, } from '../core/marionette-port.js';
+import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
+import { planNegativeControl } from '../core/negative-control.js';
+import { formatCompiledControlRefusal } from '../core/negative-control-compiled.js';
+import { waitBeforeLock } from '../core/preflight-wait.js';
+import { PreflightRefusalError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
+import { resolveWaitLockSeconds } from '../utils/options.js';
+import { stripEnginePrefix } from '../utils/paths.js';
+import { checkRequestedTestTypes } from './test-checkjs.js';
+import { assertPathlessTestMode, classifyBeforeDispatch, resolveCanaryPath } from './test-modes.js';
+import { enforceStaleBuildGate } from './test-stale-gate.js';
+/**
+ * Resolves the launchable binary a test run needs, or refuses naming why
+ * it is missing. The cause comes from the build run record, which any
+ * session's build writes, so a session that never ran the build can still
+ * say "a peer's build was interrupted" rather than only "the binary is
+ * missing".
+ *
+ * @param projectRoot - Project root
+ * @param engineDir - Absolute engine directory
+ * @param binaryName - Configured binary name
+ * @param objDir - Active objdir, when one exists
+ * @returns The engine-relative launchable path, or undefined without an objdir
+ */
+export async function resolveLaunchablePathForTests(projectRoot, engineDir, binaryName, objDir) {
+    if (!objDir)
+        return undefined;
+    const bundleCheck = await hasRunnableBundle(engineDir, binaryName, objDir);
+    if (bundleCheck.runnable)
+        return bundleCheck.expectedPath;
+    const expectedSuffix = bundleCheck.expectedPath
+        ? ` (expected at engine/${bundleCheck.expectedPath})`
+        : '';
+    const cause = describeBuildRunState(await readBuildRunState(projectRoot));
+    throw new PreflightRefusalError(`Tests require a complete launchable build${expectedSuffix}. ` +
+        'The obj-*/dist/ tree exists but the launchable binary is missing' +
+        (cause !== undefined
+            ? `.\n\n${cause}\n\n`
+            : ' — 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".', 'no-launchable-binary');
+}
+/** Build-artifact preflight wording for `fireforge test`. */
+export const TEST_BUILD_PREFLIGHT = {
+    label: 'Tests',
+    requirement: 'Tests require a completed build.',
+    remediation: "Run 'fireforge build' first, then run 'fireforge test'.",
+    requireExisting: true,
+};
+/**
+ * The head of the in-lock ladder, run early: argument shape, engine, build
+ * artifacts and config. Each refuses with exactly the message it gives
+ * under the lock. Returns undefined when there is no objdir to check
+ * further.
+ */
+async function loadPreLockContext(projectRoot, testPaths, options) {
+    assertPathlessTestMode(testPaths, options);
+    const paths = getProjectPaths(projectRoot);
+    await assertEngineExists(paths.engine);
+    const buildCheck = await hasBuildArtifacts(paths.engine);
+    assertBuildArtifacts(paths.engine, buildCheck, TEST_BUILD_PREFLIGHT);
+    const config = await loadConfig(projectRoot);
+    return buildCheck.objDir === undefined ? undefined : { paths, config, objDir: buildCheck.objDir };
+}
+/**
+ * Runs the lock-free checks and waits, and returns the options the in-lock
+ * run should use: with `waitBrowser`/`waitPort` removed when their budget
+ * was already spent here.
+ *
+ * @param projectRoot - Project root
+ * @param testPaths - Requested test paths
+ * @param options - Parsed test options
+ */
+export async function runTestPreLockPreflight(projectRoot, testPaths, options) {
+    const loaded = await loadPreLockContext(projectRoot, testPaths, options);
+    if (loaded === undefined)
+        return withLockMode(options, 'exclusive');
+    const { paths, config, objDir } = loaded;
+    options = withLockMode(options, resolveTestLockMode(options, config));
+    let launchablePath;
+    try {
+        launchablePath = await resolveLaunchablePathForTests(projectRoot, paths.engine, config.binaryName, objDir);
+    }
+    catch (error) {
+        // A build in progress holds the engine lock and relinks the bundle
+        // before it lets go, so this run queues behind it rather than refusing.
+        if ((await readBuildRunState(projectRoot)).kind !== 'running')
+            throw error;
+        info('The launchable binary is missing while a build runs; queueing behind it.');
+    }
+    const canaryPath = resolveCanaryPath(options, config);
+    const normalizedPaths = (canaryPath !== undefined ? [canaryPath] : testPaths).map((path) => stripEnginePrefix(path).trim());
+    if (options.build === true || options.buildOnly === true) {
+        await checkRequestedTestTypes(paths, config, normalizedPaths);
+    }
+    else {
+        await refuseCompiledControlBeforeLock(projectRoot, paths.engine, options);
+        await refuseStalePackagingBeforeLock(projectRoot, paths.engine, options, normalizedPaths);
+    }
+    return waitForResourcesBeforeLock(paths.engine, config, options, {
+        launchablePath,
+        normalizedPaths,
+    });
+}
+/** `options` with `sharedLock` set to the resolved decision. */
+function withLockMode(options, mode) {
+    if (mode === 'exclusive' && options.sharedLock === undefined)
+        return options;
+    const rest = { ...options };
+    delete rest.sharedLock;
+    return mode === 'shared' ? { ...rest, sharedLock: true } : rest;
+}
+/**
+ * How this run holds the engine session lock. Shared only on request
+ * (`--shared-lock` or `test.lockMode: "shared"`), and only for a run that
+ * writes nothing into engine/ or the objdir and can move its ports: no
+ * build, no negative control, auto ports. Every other run stays exclusive,
+ * so a shared holder can never overlap a build or a re-export.
+ */
+function resolveTestLockMode(options, config) {
+    const requested = options.sharedLock === true || config.test?.lockMode === 'shared';
+    if (!requested)
+        return 'exclusive';
+    const writes = options.build === true ||
+        options.buildOnly === true ||
+        options.negativeControl !== undefined ||
+        options.canary !== undefined ||
+        options.doctor === true;
+    if (writes || !autoPortsRequested(options, config)) {
+        info('Shared test lock requested, but this run ' +
+            (writes
+                ? 'builds, applies a negative control, or runs a canary/doctor preflight'
+                : 'does not use auto ports (--auto-ports or test.mochitestPorts: "auto")') +
+            ', so it holds the engine lock exclusively.');
+        return 'exclusive';
+    }
+    return 'shared';
+}
+/**
+ * Refuses a build-less `--negative-control` on compiled source before the
+ * lock: applied after the build it is never compiled, so the run could only
+ * report `control=missed` against the unmutated binary.
+ */
+async function refuseCompiledControlBeforeLock(projectRoot, engineDir, options) {
+    if (options.negativeControl === undefined)
+        return;
+    let plan;
+    try {
+        plan = await planNegativeControl(projectRoot, engineDir, options.negativeControl);
+    }
+    catch {
+        // Any other refusal (including a control a killed run left applied,
+        // which only the in-lock recovery may undo) is the in-lock pass's.
+        return;
+    }
+    if (plan.compiled === undefined)
+        return;
+    throw new PreflightRefusalError(formatCompiledControlRefusal(plan.compiled), 'negative-control');
+}
+/**
+ * Runs the build-less run's packaging gates (coverage, stale content,
+ * StaticComponents) before the lock, so a refusal surfaces before the run
+ * queues instead of after it reached the head of the queue. The same gate
+ * runs again under the lock, where a peer's build may since have changed
+ * the answer; this pass only refuses early what would refuse anyway.
+ *
+ * Skipped while a build runs (it will rewrite the record this reads) and
+ * under `--allow-stale-build`/`--allow-stale-components`, whose warnings
+ * belong to the in-lock pass alone. A `--negative-control` refusal says to
+ * add `--build`: without it the control has nothing current to run on, and
+ * the invocation used to end `control=inconclusive` after a full queue.
+ */
+async function refuseStalePackagingBeforeLock(projectRoot, engineDir, options, normalizedPaths) {
+    if (options.allowStaleBuild === true || options.allowStaleComponents === true)
+        return;
+    if ((await readBuildRunState(projectRoot)).kind === 'running')
+        return;
+    try {
+        await enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths, {
+            quiet: true,
+        });
+    }
+    catch (error) {
+        if (options.negativeControl === undefined || !(error instanceof PreflightRefusalError)) {
+            throw error;
+        }
+        throw new PreflightRefusalError(`${error.message}\n\nThis --negative-control run has no --build, so its control would ` +
+            'run on this packaging and end inconclusive. Add --build: the control is then planned ' +
+            'against a fresh build of the requested paths.', error.note);
+    }
+}
+/** `options` without one wait budget, which this pass already spent. */
+function withoutOption(options, key) {
+    const rest = { ...options };
+    if (key === 'waitBrowser')
+        delete rest.waitBrowser;
+    else
+        delete rest.waitPort;
+    return rest;
+}
+/**
+ * Spends `--wait-browser` and `--wait-port` before the lock, mirroring
+ * which in-lock checks would apply to this run, and strips each budget it
+ * spent from the returned options.
+ */
+async function waitForResourcesBeforeLock(engineDir, config, options, request) {
+    if (options.waitBrowser === undefined && options.waitPort === undefined)
+        return options;
+    let xpcshellOnly;
+    try {
+        ({ xpcshellOnly } = await classifyBeforeDispatch(engineDir, request.normalizedPaths, {
+            allowMixed: true,
+        }));
+    }
+    catch {
+        return options;
+    }
+    const kill = options.killStaleMarionette === true;
+    let result = options;
+    const building = options.build === true || options.buildOnly === true;
+    if (options.waitBrowser !== undefined &&
+        request.launchablePath !== undefined &&
+        (building || !xpcshellOnly)) {
+        const binary = join(engineDir, request.launchablePath);
+        await waitBeforeLock(() => ensureLaunchableBrowserNotRunning(binary), resolveWaitLockSeconds(options.waitBrowser), 
+        // A stale browser the run may reap is not worth waiting out; the
+        // in-lock check terminates it.
+        kill ? ['stale-browser'] : []);
+        result = withoutOption(result, 'waitBrowser');
+    }
+    // Port waits stay under the lock with --kill-stale-marionette: a stale
+    // listener reads as busy until the in-lock pass reaps it, so waiting it
+    // out here would only burn the budget.
+    if (options.waitPort !== undefined && options.buildOnly !== true && !kill) {
+        const seconds = resolveWaitLockSeconds(options.waitPort);
+        if (!xpcshellOnly) {
+            await waitBeforeLock(() => ensureMochitestServerPortAvailable(undefined, { engineDir }), seconds);
+        }
+        if (!xpcshellOnly || options.doctor === true) {
+            const port = options.marionettePort ?? extractForwardedMarionettePort(options.machArg ?? []);
+            await waitBeforeLock(() => assertMarionettePortAvailable(port, { binaryName: config.binaryName }), seconds);
+        }
+        result = withoutOption(result, 'waitPort');
+    }
+    return result;
+}

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

@@ -26,12 +26,33 @@ const TEST_HELP_TEXT = [
     'not exercise cross-argument state; --no-shard restores the',
     'combined single-instance invocation.',
     '',
+    'Mixed xpcshell and browser/mochitest paths run as two consecutive',
+    'mach invocations (xpcshell first) under one lock hold and one',
+    'verdict; with --build, one pre-test build packages both halves.',
+    '--repeat <n> and --negative-control <diff> run under one lock hold',
+    'too. Each sub-run prints a FIREFORGE-RUN: line (its own verdict',
+    'plus run=<i>/<n>) before the single aggregate verdict.',
+    '',
+    'A dev objdir symlinks chrome JS/CSS and widget files into engine/,',
+    'so the browser reads engine/ sources when it loads them, after the',
+    'build step: an edit made while a suite runs reaches that suite, and',
+    'a hand-made neuter must stay until the verdict line, not until',
+    '"Build complete", since one restored early is gone for later',
+    'shards. --negative-control applies its diff after the build and',
+    'restores it byte-exact only after the run, before the lock is',
+    'released.',
+    '',
     'Machine-readable verdict: every run (single, sharded, --canary,',
     '--doctor) ends with exactly one raw stdout line',
     '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|harness-arguments|test-failures|',
     '  no-tests|preflight|inconclusive|lock-timeout|killed] [checks=<n>]',
-    '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)] [shuffle=<seed>]',
-    '  [log=<path>]',
+    '  [unexpected=<n>] [started=<n>/<m> first-unstarted=<path>]',
+    '  [shards=<p>/<t>] [(<note>)] [shuffle=<seed>]',
+    '  [runs=<p>/<n>] [control=caught|missed|inconclusive]',
+    '  [furnace-applied=<names>|furnace-apply=skipped] [log=<path>]',
+    "control= is a negative control's outcome: caught (went red on test",
+    'failures, as a control should; exit 0), missed (stayed green; exit',
+    '5) or inconclusive.',
     'shuffle=<seed> is the seed a --shuffle run exported to the harness.',
     "log=<path> names this run's complete output, written to",
     '.fireforge/logs/ as the run streams, so a piped or truncated run',
@@ -39,7 +60,11 @@ const TEST_HELP_TEXT = [
     'The status follows the harness classifier, not the raw exit code:',
     'a crash-classified run says FAIL reason=crash even at exit 0, and',
     'a green-summary-override pass says PASS despite a non-zero mach',
-    'exit. reason=preflight covers any failure before the harness ran',
+    'exit. An exit-0 run is still FAIL reason=test-failures when its',
+    'summary reports unexpected results, the browser shut down mid-test,',
+    'or a requested file never started; started=/first-unstarted= then',
+    'name how far it got and where a re-run has to pick up.',
+    'reason=preflight covers any failure before the harness ran',
     '(missing/stale build, invalid paths, port conflicts, config',
     'errors); reason=inconclusive means engine/ or perf power source',
     'changed while tests ran, so the result cannot be trusted;',
@@ -56,13 +81,47 @@ const TEST_HELP_TEXT = [
     '"(headed run stalled with the display asleep)" marks a no-output',
     'stall whose display was measured asleep. Key on this line',
     'instead of mach internals.',
+    '',
+    'Lock-free checks run before the engine lock is requested: a missing',
+    'launchable binary (with the build that left it missing, when one is',
+    'recorded), the named-file checkJs pass of --build, and the',
+    '--wait-browser/--wait-port budgets. Each is re-checked once under the',
+    'lock.',
 ].join('\n');
+function registerTestMultiRunOptions(test) {
+    return test
+        .option('--repeat <n>', 'Run the same paths n times under one engine-lock hold (a --build builds once); prints each run and aggregates runs=<passed>/<n> on the verdict', commanderArgParser((raw) => parsePositiveIntegerFlag('--repeat', raw)))
+        .option('--negative-control <diff>', 'Apply this reviewed git diff (engine/ or components/ sources; project-relative path) after the pre-test build and right before dispatch, restore it byte-exact after the run (also on failure, SIGINT and SIGTERM) before the lock is released, and report control=caught|missed|inconclusive on the verdict')
+        .option('--auto-ports', "Let a browser run proceed when the mochitest server or Marionette port is held by something that is not this checkout's own: the engine's harness falls back to a free port itself. Same as test.mochitestPorts: \"auto\". This checkout's own leftovers are still refused.");
+}
 function registerTestSharingOptions(test) {
     return test
         .option('--wait-browser [seconds]', 'Wait for this objdir browser before any deployment/build (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
         .option('--wait-port [seconds]', 'Wait for the mochitest and Marionette ports (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
+        .option('--restart-between-tests', "Forward mochitest's --restart-between-tests: restart the browser between test files to expose undocumented cross-file dependencies (the shape a manifest's standalone key asks for). Mochitest dispatch only.")
+        .option('--keep-log <path>', "Also write this run's log to <path> (a directory receives it under its own name), outside .fireforge/logs/ retention. FIREFORGE_LOG_KEEP sets a session default.")
         .option('--profile-file <source=destination>', 'Merge a file into the harness profile, e.g. sheet.css=chrome/userChrome.css. Repeatable.', ...stringListOption());
 }
+/** Pre-test build options that shape the coverage claim and the Furnace step. */
+function registerTestBuildOptions(test) {
+    return test
+        .option('--extend-coverage', 'With --build/--build-only and explicit paths, refuse instead of dropping any earlier packaging claim. Scoped builds keep each earlier path by default while its own staging inputs (manifest directory and the fixtures its manifest names) and engine/mozconfig are unchanged; this flag turns a drop into a refusal before the build.')
+        .option('--furnace-apply <mode>', 'With --build/--build-only: all (default; deploy every component with undeployed edits), reached (only components a requested test names; the rest are reported as furnace-skipped=<names>), or none. Same as test.furnaceApply.', commanderArgParser((raw) => {
+        if (raw !== 'all' && raw !== 'reached' && raw !== 'none') {
+            throw new GeneralError(`--furnace-apply must be all, reached or none (got "${raw}")`);
+        }
+        return raw;
+    }))
+        .option('--no-furnace-apply', 'With --build/--build-only, skip the Furnace apply so the build packages engine/ as it stands; names the components whose undeployed components/ edits it leaves out (same as --furnace-apply none)');
+}
+/** Options that run a request on several harness instances, or judge it per file. */
+function registerTestParallelOptions(test) {
+    return test
+        .option('--jobs <n>', 'Run shards on n harness instances at once inside one lock hold, each with its own profile, Marionette port and (via auto ports) server ports. With --no-shard, or one directory argument, the files are split in order into n contiguous chunks. Prints a FIREFORGE-SHARD line per shard and one aggregate verdict. Requires --auto-ports or test.mochitestPorts: "auto".', commanderArgParser((raw) => parsePositiveIntegerFlag('--jobs', raw)))
+        .option('--shard-size <n>', 'Dispatch n files per mach invocation (mochitest restarts the browser between files) and judge each file from the structured log: shards= then counts files and failed-shards= names failed files. Combines with --jobs.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shard-size', raw)))
+        .option('--results <path>', 'Write a JSON record per test file and --repeat run (status, expected, duration, run-log line) from the mozlog structured log, and name it on the verdict as results=<path>')
+        .option('--shared-lock', 'Hold the engine session lock shared when this run is build-less, applies no negative control and uses auto ports, so peers\' build-less runs on this objdir overlap; builds and re-exports still wait. Same as test.lockMode: "shared".');
+}
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
     const test = program
@@ -72,7 +131,6 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--full-output', "Pass mozbuild's full verbosity through for the TEST phase. mozbuild quiets terminal output to warnings and errors when it detects a coding agent, which removes TEST_START and console INFO — the lines a hang or stall diagnosis needs. This unsets that detection for test dispatches only; the build phase stays quiet.")
         .option('--build', 'Run incremental UI build before testing')
         .option('--build-only', 'Run the scoped pre-test build (packaging exactly [paths...], mixed harnesses allowed) and exit without dispatching tests — one build covers both harness halves, then run each half without --build')
-        .option('--extend-coverage', 'With --build/--build-only and explicit paths, union those paths into the recorded test-packaging coverage instead of replacing it, so an earlier scoped build stays covered. Refused when the build anchor moved (engine HEAD, mozconfig, or a previously fingerprinted packageable file changed).')
         .option('--refuse-unexported-drift', 'With --build/--build-only, refuse (instead of warning) when the pre-test build would overwrite engine content recorded in neither a patch body nor the pristine baseline — the same belt as "fireforge build --refuse-unexported-drift", armable from the scripted "test --build" shape the hazard actually shows up in')
         .option('--auto', 'Forward mach test --auto. Valid only when no explicit paths are provided.')
         .option('--allow-stale-build', 'Allow tests to run even when packageable engine files changed since the last successful FireForge build')
@@ -83,7 +141,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
         .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', ...stringListOption())
-        .option('--shuffle [seed]', 'Shuffle isolated mochitest path arguments in a repeatable seeded order (fresh seed when omitted). Native mach --shuffle within each invocation remains unseeded. Export FIREFORGE_SHUFFLE_SEED for custom task code and stamp shuffle=<seed> on the verdict. --no-shard disables the seeded argument permutation. Write --shuffle=<seed> or place it after the paths.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shuffle', raw)))
+        .option('--shuffle [seed]', 'Shuffle isolated mochitest path arguments in a repeatable seeded order (fresh seed when omitted). Native mach --shuffle within each invocation remains unseeded. Export FIREFORGE_SHUFFLE_SEED for custom task code and stamp shuffle=<seed> on the verdict. --no-shard disables the seeded argument permutation. A path-shaped argument right after the flag (browser_x.js, dir/) is a test path, not a seed.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shuffle', raw)))
         .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${DEFAULT_HARNESS_RETRIES}.`, commanderArgParser((raw) => {
         const n = Number.parseInt(raw, 10);
         if (!Number.isFinite(n) || n < 0 || n > 10) {
@@ -102,14 +160,15 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         return n;
     }))
         .addHelpText('after', TEST_HELP_TEXT);
-    addWaitLockOption(registerTestSharingOptions(test)).action(withErrorHandling(async (paths, options) => {
+    addWaitLockOption(registerTestParallelOptions(registerTestBuildOptions(registerTestMultiRunOptions(registerTestSharingOptions(test))))).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
-        // The engine session lock is acquired outside testCommand's own
-        // exactly-one-verdict guarantee, so a lock failure must emit here or
-        // the run ends with no FIREFORGE-VERDICT line at all.
+        // Fallback for a verdict testCommand did not emit (it takes the lock).
         resetVerdictEmission();
         try {
-            await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+            await testCommand(projectRoot, paths, pickDefined(options), (body, mode) => withEngineSessionLock(projectRoot, 'test', body, {
+                waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+                ...(mode === 'shared' ? { mode } : {}),
+            }));
         }
         catch (error) {
             if (!verdictEmitted()) {

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

@@ -0,0 +1,62 @@
+/**
+ * `fireforge test --results <path>`: one record per test file and per
+ * `--repeat` run, from the mozlog raw log each dispatch writes.
+ *
+ * Gates and retry wrappers downstream named a run's failing files by
+ * reading `TEST_START`/`TEST_END` lines and the prose of the "sharded test
+ * run(s) did not pass" error out of the human log, which nothing promised
+ * to keep stable. The results file is the stable form: JSON with a
+ * `schemaVersion`, written once the invocation has finished, and named on
+ * the verdict line as `results=<path>`.
+ */
+import type { RawTestResult } from '../core/test-raw-log.js';
+/** One file's result in one dispatch. */
+export interface TestFileResult extends RawTestResult {
+    /** `--repeat` run (1-based); 1 for a single run. */
+    run: number;
+    /** The shard (path argument or `--shard-size` chunk) the file ran in. */
+    shard: string;
+    /** Line of the run log where this file's dispatch began (1-based). */
+    logLine: number;
+}
+/** The document `--results` writes. */
+export interface TestResultsDocument {
+    schemaVersion: 1;
+    /** Files in dispatch-completion order. */
+    files: TestFileResult[];
+    /** Started files that never ended, per dispatch. */
+    unfinished: Array<{
+        test: string;
+        run: number;
+        shard: string;
+    }>;
+}
+/** Clears the collector at the start of an invocation. */
+export declare function resetTestResults(): void;
+/**
+ * Adds one dispatch's parsed raw log to the invocation's results.
+ *
+ * @param results - The dispatch's finished files
+ * @param unfinished - Its started-but-unfinished files
+ * @param context - Run, shard and run-log line of the dispatch
+ */
+export declare function recordTestResults(results: readonly RawTestResult[], unfinished: readonly string[], context: {
+    run: number;
+    shard: string;
+    logLine: number;
+}): void;
+/** The results collected so far (for tests and the shard summary). */
+export declare function collectedTestResults(): TestResultsDocument;
+/**
+ * Writes the collected results.
+ *
+ * @param path - Destination of `--results`
+ */
+export declare function writeTestResults(path: string): Promise<void>;
+/**
+ * Creates the scratch directory the dispatches' raw logs go to, runs
+ * `body`, and removes it afterwards.
+ *
+ * @param body - Receives the directory
+ */
+export declare function withRawLogDir<T>(body: (dir: string) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge test --results <path>`: one record per test file and per
+ * `--repeat` run, from the mozlog raw log each dispatch writes.
+ *
+ * Gates and retry wrappers downstream named a run's failing files by
+ * reading `TEST_START`/`TEST_END` lines and the prose of the "sharded test
+ * run(s) did not pass" error out of the human log, which nothing promised
+ * to keep stable. The results file is the stable form: JSON with a
+ * `schemaVersion`, written once the invocation has finished, and named on
+ * the verdict line as `results=<path>`.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeJson } from '../utils/fs.js';
+let collected = { schemaVersion: 1, files: [], unfinished: [] };
+/** Clears the collector at the start of an invocation. */
+export function resetTestResults() {
+    collected = { schemaVersion: 1, files: [], unfinished: [] };
+}
+/**
+ * Adds one dispatch's parsed raw log to the invocation's results.
+ *
+ * @param results - The dispatch's finished files
+ * @param unfinished - Its started-but-unfinished files
+ * @param context - Run, shard and run-log line of the dispatch
+ */
+export function recordTestResults(results, unfinished, context) {
+    for (const result of results)
+        collected.files.push({ ...result, ...context });
+    for (const test of unfinished) {
+        collected.unfinished.push({ test, run: context.run, shard: context.shard });
+    }
+}
+/** The results collected so far (for tests and the shard summary). */
+export function collectedTestResults() {
+    return collected;
+}
+/**
+ * Writes the collected results.
+ *
+ * @param path - Destination of `--results`
+ */
+export async function writeTestResults(path) {
+    await writeJson(path, collectedTestResults());
+}
+/**
+ * Creates the scratch directory the dispatches' raw logs go to, runs
+ * `body`, and removes it afterwards.
+ *
+ * @param body - Receives the directory
+ */
+export async function withRawLogDir(body) {
+    const dir = await mkdtemp(join(tmpdir(), 'fireforge-raw-log-'));
+    try {
+        return await body(dir);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}

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

@@ -12,6 +12,7 @@
 import { type DisplaySleepState } from '../core/display-state.js';
 import { type MachCommandResult } from '../core/mach.js';
 import { type HarnessRunVerdict } from '../core/test-harness-crash.js';
+import { type RawTestResult } from '../core/test-raw-log.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export declare const DEFAULT_HARNESS_RETRIES = 2;
 /**
@@ -49,6 +50,15 @@ export interface TestRunContext {
     fullOutput?: boolean;
     /** `--pgid-file`: where each dispatch publishes its harness process group id. */
     pgidFile?: string | undefined;
+    /**
+     * Where each dispatch writes its mozlog raw log (`--results`,
+     * `--shard-size`). Unset: no `--log-raw` is added and nothing is parsed.
+     */
+    rawLogDir?: string | undefined;
+    /** `--repeat` run this dispatch belongs to (1-based), for `--results`. */
+    repetition?: number | undefined;
+    /** Prefix for every echoed and logged output line (`--jobs` instances). */
+    outputPrefix?: string | undefined;
 }
 /** Outcome of one (possibly retried) harness invocation. */
 export interface TestRunOutcome {
@@ -62,64 +72,12 @@ export interface TestRunOutcome {
      * when the shape did not apply and no probe ran.
      */
     displayState?: DisplaySleepState | undefined;
+    /** Per-file results from the raw log, when the run wrote one. */
+    fileResults?: RawTestResult[] | undefined;
 }
 /**
  * Runs one mach test invocation for `paths`, retrying recognized harness
  * crashes up to the configured budget. Every attempt goes through the
  * stale-xpcshell-symlink repair path the single-run flow already used.
  */
-export declare function runTestsWithRetries(ctx: TestRunContext, paths: string[]): Promise<TestRunOutcome>;
-/**
- * One sequential harness invocation of a sharded run: a requested path
- * argument and the mach paths dispatched for it. A file argument is a group
- * of one. A directory argument groups its enumerated test files so the whole
- * directory still runs in ONE browser instance, keeping cross-file state
- * behaviour within a directory run.
- */
-export interface ShardGroup {
-    /** The path argument as the operator passed it (display label). */
-    label: string;
-    /** The mach dispatch paths for this argument. */
-    paths: string[];
-}
-/** Per-shard summary entry. */
-export interface ShardOutcome {
-    label: string;
-    outcome: TestRunOutcome;
-}
-/** Aggregate result of a sharded run, verdict emission deferred to the caller. */
-export interface ShardedRunSummary {
-    shards: ShardOutcome[];
-    passed: number;
-    total: number;
-    /** Aggregate classifier verdict. See {@link deriveAggregateShardVerdict}. */
-    aggregate: HarnessRunVerdict;
-}
-/**
- * Derives the aggregate classification for a sharded run: all-green is
- * `tests-ran-ok`. Otherwise the most structural failure wins. A crashed
- * shard makes the whole run `harness-crash`, then `no-tests`, then plain
- * `test-failures`, so the aggregate `reason=` keeps the classifier-driven
- * contract instead of collapsing every failure to `test-failures`.
- */
-export declare function deriveAggregateShardVerdict(shards: ShardOutcome[]): HarnessRunVerdict;
-/**
- * Runs each requested path argument as its own sequential harness
- * invocation (a directory argument's enumerated files stay together in
- * one invocation, see {@link ShardGroup}) and prints an aggregate
- * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
- * (which receives the throwing diagnosis chain from the command layer)
- * but downgraded to warnings so every shard runs. The aggregate verdict
- * line and the aggregate error are not produced here: the caller runs
- * the engine-generation integrity check first and then calls
- * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
- * `engine/` mutation can never print `PASS` before the check fails.
- */
-export declare function runShardedTests(ctx: TestRunContext, groups: ShardGroup[], diagnoseShardFailure: (outcome: TestRunOutcome, label: string) => string | undefined): Promise<ShardedRunSummary>;
-/**
- * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
- * throws the aggregate error when any shard did not pass, the same
- * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
- * the engine-generation check succeeded.
- */
-export declare function finalizeShardedOutcome(summary: ShardedRunSummary): void;
+export declare function runTestsWithRetries(ctx: TestRunContext, paths: string[], label?: string): Promise<TestRunOutcome>;