@hominis/fireforge 0.51.0 → 0.53.0

package/dist/src/commands/test-control-restore.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The restore build after a compiled negative control.
+ *
+ * A control on compiled source is applied before a full pre-test build, so
+ * the binary under test carries it. Restoring the source byte-exact after
+ * the run does not unbuild it: the objdir binary keeps the mutation until a
+ * build recompiles the original. Every later `fireforge test` would then
+ * test the control. The orchestrator therefore runs one more full
+ * `mach build` right after a successful restore, still under the same
+ * engine-session hold, and its baseline drops the `controlBuild` stamp the
+ * control's build recorded. When that build fails, or the run never gets
+ * here (killed), the stamp stays and the next `fireforge test` refuses with
+ * `note=control-built` until `fireforge build` replaces it.
+ */
+import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { runProtectedMachBuild, withBuildLock } from '../core/mach.js';
+import { toError } from '../utils/errors.js';
+import { info, notice, verbose, warn } from '../utils/logger.js';
+/**
+ * Whether the recorded baseline is the one this run's control build wrote:
+ * only then did a build compile the control in (a failed control build
+ * writes no baseline, and its restored source's fresh mtime trips the
+ * stale-compiled check instead).
+ *
+ * @param projectRoot - Project root
+ * @param stamp - The stamp this run's control build recorded
+ */
+export async function controlBuildRecorded(projectRoot, stamp) {
+    const baseline = await readBuildBaseline(projectRoot);
+    return (baseline?.controlBuild?.appliedAt === stamp.appliedAt &&
+        baseline.controlBuild.diffFile === stamp.diffFile);
+}
+/**
+ * Rebuilds the binary after a compiled control was restored: a full
+ * protected `mach build` under the build lock, then a baseline without the
+ * stamp. The previous baseline's packaging-coverage claim is carried
+ * forward unchanged, since recompiling the restored source stages no tests.
+ * Never throws: a failure leaves the stamp in place, which is the refusal
+ * the next run needs.
+ *
+ * @param projectRoot - Project root
+ * @param stamp - The stamp this run's control build recorded
+ * @param harnessRetries - Recognized-crash retry budget for the build
+ */
+export async function runControlRestoreBuild(projectRoot, stamp, harnessRetries) {
+    const paths = getProjectPaths(projectRoot);
+    notice(`Rebuilding after the compiled negative control (${stamp.targets.map((target) => `engine/${target}`).join(', ')}): ` +
+        'the binary still carries the mutation until a full mach build recompiles the restored source.');
+    try {
+        const config = await loadConfig(projectRoot);
+        return await withBuildLock(projectRoot, async () => {
+            const previousBaseline = await readBuildBaseline(projectRoot);
+            const result = await runProtectedMachBuild('full', paths.engine, {
+                ...(harnessRetries === undefined ? {} : { retries: harnessRetries }),
+            });
+            if (result.exitCode !== 0) {
+                warn('The restore build after the negative control failed, so the binary still carries ' +
+                    'the control. The next "fireforge test" refuses (note=control-built) until ' +
+                    '"fireforge build" succeeds.');
+                return 'failed';
+            }
+            await writeBuildBaseline({
+                projectRoot,
+                engineDir: paths.engine,
+                binaryName: config.binaryName,
+                testPackagingCoverage: previousBaseline?.testPackagingCoverage,
+                testCoverageRecords: previousBaseline?.testCoverageRecords,
+                fullCoverageAnchor: previousBaseline?.fullCoverageAnchor,
+                previousBaseline,
+                recordedBy: 'fireforge test --negative-control (restore build)',
+                staticComponentsHandling: 'refresh',
+                buildKind: 'full',
+            });
+            info('Restore build complete: the binary no longer carries the negative control.');
+            return 'done';
+        });
+    }
+    catch (error) {
+        verbose(`Restore build after the negative control failed: ${toError(error).message}`);
+        warn(`The restore build after the negative control could not run (${toError(error).message}). ` +
+            'The next "fireforge test" refuses (note=control-built) until "fireforge build" succeeds.');
+        return 'failed';
+    }
+}

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

@@ -6,11 +6,14 @@
  * `--jobs` parallel harness instances.
  */
 import { createServer } from 'node:net';
+import { join } from 'node:path';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
-import { autoPortsRequested } from '../core/harness-port-fallback.js';
+import { autoPortsRequested, detectHarnessPortFallback } from '../core/harness-port-fallback.js';
+import { reserveHarnessServerPorts, } from '../core/harness-port-reservation.js';
 import { extractForwardedMarionettePort } from '../core/marionette-port.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
+import { ensureDir } from '../utils/fs.js';
 import { notice } from '../utils/logger.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
 import { shuffleTestGroups } from './test-harness-env.js';
@@ -85,27 +88,92 @@ async function allocateLoopbackPort() {
         });
     });
 }
+/**
+ * The mochitest harness writes the dispatched test list to
+ * `_tests/testing/mochitest/tests.json` and the browser fetches it from
+ * there, so instances sharing the default name read each other's list (and
+ * one instance's cleanup removes it under the other). Each instance names
+ * its own file.
+ */
+function testRunManifestArg(index) {
+    return `--testrun-manifest-file=fireforge-tests-${process.pid}-job${index + 1}.json`;
+}
+/**
+ * The `MOZ_UPLOAD_DIR` the caller gave this run (its own env first, then
+ * the process environment), or undefined when there is none.
+ */
+function uploadDirBase(base) {
+    const dir = base.env?.['MOZ_UPLOAD_DIR'] ?? process.env['MOZ_UPLOAD_DIR'];
+    return dir === undefined || dir === '' ? undefined : dir;
+}
+/**
+ * `--jobs` instance `index`'s own upload directory, `<base>/job-<n>`. The
+ * harness writes per-run artifacts there under fixed names (the
+ * `modifiedPrefs.json` pref census among them), so instances sharing the
+ * caller's directory replace each other's files.
+ */
+function instanceUploadDir(uploadBase, index) {
+    return join(uploadBase, `job-${index + 1}`);
+}
 /**
  * The context for `--jobs` instance `index` (0-based): its own output
- * prefix, and from the second instance on its own Marionette port, so
- * browsers started at the same moment never race for 2828. The mochitest
- * server ports are left to the engine harness's busy-port fallback, which
- * `--jobs` requires (auto ports).
+ * prefix, upload directory (when the caller set `MOZ_UPLOAD_DIR`) and
+ * test-list manifest, and from the second instance on its own Marionette
+ * port, so browsers started at the same moment never race for 2828. The
+ * mochitest server ports are moved by the engine harness's busy-port
+ * fallback, which `--jobs` requires (auto ports), while
+ * {@link reserveHarnessServerPorts} holds the defaults.
  */
 async function instanceContext(base, index, xpcshellOnly) {
-    const ctx = { ...base, outputPrefix: `[job ${index + 1}] ` };
-    if (index === 0 || xpcshellOnly)
+    let ctx = { ...base, outputPrefix: `[job ${index + 1}] ` };
+    const uploadBase = uploadDirBase(base);
+    if (uploadBase !== undefined) {
+        const uploadDir = instanceUploadDir(uploadBase, index);
+        await ensureDir(uploadDir);
+        ctx = { ...ctx, env: { ...base.env, MOZ_UPLOAD_DIR: uploadDir } };
+    }
+    if (xpcshellOnly)
         return ctx;
+    const own = [...base.baseExtraArgs, testRunManifestArg(index)];
+    if (index === 0)
+        return { ...ctx, baseExtraArgs: own };
     const port = await allocateLoopbackPort();
     return {
         ...ctx,
-        baseExtraArgs: [
-            ...base.baseExtraArgs,
-            `--setpref=marionette.port=${port}`,
-            `--marionette=127.0.0.1:${port}`,
-        ],
+        baseExtraArgs: [...own, `--setpref=marionette.port=${port}`, `--marionette=127.0.0.1:${port}`],
     };
 }
+/**
+ * Stamps a `--jobs` run's verdict attributes: `jobs=<n>`, and
+ * `upload-dirs=<dir>,...` naming each instance's upload directory, so a
+ * caller can merge per-instance artifacts.
+ */
+function stampParallelAttributes(runCtx, jobs, shards) {
+    setVerdictRunAttribute('jobs', String(jobs));
+    const uploadBase = uploadDirBase(runCtx);
+    if (uploadBase === undefined)
+        return;
+    const instances = Math.max(1, Math.min(jobs, shards));
+    setVerdictRunAttribute('upload-dirs', Array.from({ length: instances }, (_, index) => instanceUploadDir(uploadBase, index)).join(','));
+}
+/**
+ * Holds the mochitest server ports for a browser run on more than one
+ * instance (see `harness-port-reservation.ts`). Only on an engine whose
+ * harness falls back from a busy server port: without that fallback a
+ * held port would fail every instance instead of moving it.
+ */
+async function reserveParallelServerPorts(engineDir, instances, xpcshellOnly) {
+    if (instances < 2 || xpcshellOnly)
+        return undefined;
+    if (!(await detectHarnessPortFallback(engineDir)).serverPorts)
+        return undefined;
+    const reservation = await reserveHarnessServerPorts();
+    if (reservation.held.length > 0) {
+        notice(`Holding mochitest server port(s) ${reservation.held.join(', ')} for the parallel run, so ` +
+            "each instance's harness moves to server ports of its own.");
+    }
+    return reservation;
+}
 /** The shards to run, or undefined for one combined invocation. */
 function planShards(inputs) {
     const { dispatchGroups, options, canaryPath, shuffleSeed } = inputs;
@@ -143,9 +211,10 @@ export async function dispatchTests(inputs) {
         notice(describeSharding(shards.length, options, jobs));
         const base = jobs > 1 ? await instanceContext(runCtx, 0, inputs.xpcshellOnly) : runCtx;
         if (jobs > 1)
-            setVerdictRunAttribute('jobs', String(jobs));
+            stampParallelAttributes(runCtx, jobs, shards.length);
         const generationBefore = await snapshotEngineGeneration(engineDir);
         let summary;
+        const reservation = await reserveParallelServerPorts(engineDir, Math.min(jobs, shards.length), inputs.xpcshellOnly);
         try {
             summary = await runShardedTests(base, shards, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, inputs.postRebuildContext), {
                 jobs,
@@ -154,6 +223,7 @@ export async function dispatchTests(inputs) {
             });
         }
         finally {
+            await reservation?.release();
             // Runs before the aggregate verdict below: a mutated engine/ emits
             // `FAIL reason=inconclusive` and throws, so an invalidated run can
             // never print `PASS shards=N/N` first. (A throw here masks an

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

@@ -39,6 +39,7 @@ const REASON_RANK = [
     'inconclusive',
     'preflight',
     'crash',
+    'server-startup',
     'harness-arguments',
     'no-tests',
     'test-failures',

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

@@ -14,6 +14,7 @@
  * `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 {
@@ -30,6 +31,16 @@ export interface TestRunHooks {
      * 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;
     /** `--repeat` run this sub-run is (1-based), for `--results`. */
     repetition?: number;
     /** Where dispatches write their mozlog raw logs (`--results`, `--shard-size`). */

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

@@ -17,13 +17,14 @@
  */
 import { getProjectPaths } from '../core/config.js';
 import { applyNegativeControl, planNegativeControl, recoverPendingNegativeControl, restoreNegativeControl, } from '../core/negative-control.js';
-import { formatCompiledControlRefusal } from '../core/negative-control-compiled.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 { emitAggregateVerdict, emitFailVerdict, setVerdictCapture, setVerdictRunAttribute, verdictEmitted, } from './test-verdict.js';
@@ -105,6 +106,26 @@ function controlHook(paths, plan, slot) {
             '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).
@@ -172,6 +193,7 @@ export async function orchestrateTestRuns(projectRoot, testPaths, options, body,
         }
         setVerdictRunAttribute('control-build', 'compiled');
     }
+    const controlStamp = compiledControlStamp(options, compiled);
     const results = [];
     let restoreError;
     for (const [index, run] of runs.entries()) {
@@ -187,7 +209,11 @@ export async function orchestrateTestRuns(projectRoot, testPaths, options, body,
                 ...(plan === undefined
                     ? {}
                     : compiledControl && index === 0
-                        ? { beforeBuild: controlHook(controlPaths, plan, slot) }
+                        ? {
+                            beforeBuild: controlHook(controlPaths, plan, slot),
+                            fullBuildReason: formatCompiledControlBuildNotice(compiled),
+                            ...(controlStamp === undefined ? {} : { controlBuild: controlStamp }),
+                        }
                         : { beforeDispatch: controlHook(controlPaths, plan, slot) }),
             });
         }
@@ -231,6 +257,11 @@ export async function orchestrateTestRuns(projectRoot, testPaths, options, body,
         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

package/dist/src/commands/test-perf-scope.d.ts

@@ -32,7 +32,7 @@ export declare function perfGenerationTolerance(engineDir: string): (before: str
  * (with a warning, and `drift-tolerated=<n>` on the verdict) when HEAD did
  * not move and every changed path is one the running browser cannot see.
  *
- * A peer deleting an unrelated chrome script used to make a whole run
+ * A peer deleting an unrelated chrome script must not make a whole run
  * inconclusive. What a running browser can see mid-run is narrower than
  * "anything under engine/": a file the objdir links to its source (`live`),
  * one the harness stages at dispatch (`at-dispatch`), and the run's own

package/dist/src/commands/test-perf-scope.js

@@ -86,7 +86,7 @@ export function perfGenerationTolerance(engineDir) {
  * (with a warning, and `drift-tolerated=<n>` on the verdict) when HEAD did
  * not move and every changed path is one the running browser cannot see.
  *
- * A peer deleting an unrelated chrome script used to make a whole run
+ * A peer deleting an unrelated chrome script must not make a whole run
  * inconclusive. What a running browser can see mid-run is narrower than
  * "anything under engine/": a file the objdir links to its source (`live`),
  * one the harness stages at dispatch (`at-dispatch`), and the run's own

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

@@ -2,15 +2,14 @@
  * 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:
+ * running it first keeps each check from costing a full place in the lock
+ * queue before it can 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.
+ *  - a missing launchable binary (a peer's interrupted build) refuses
+ *    before the wait, naming the cause;
+ *  - the named-file checkJs pass refuses a type error without a queue;
+ *  - `--wait-browser` and `--wait-port` spend their budget without holding
+ *    the lock, so no peer queues behind a run that is 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

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

@@ -3,15 +3,14 @@
  * 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:
+ * running it first keeps each check from costing a full place in the lock
+ * queue before it can 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.
+ *  - a missing launchable binary (a peer's interrupted build) refuses
+ *    before the wait, naming the cause;
+ *  - the named-file checkJs pass refuses a type error without a queue;
+ *  - `--wait-browser` and `--wait-port` spend their budget without holding
+ *    the lock, so no peer queues behind a run that is 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
@@ -122,7 +121,10 @@ export async function runTestPreLockPreflight(projectRoot, testPaths, options) {
     }
     else {
         await refuseCompiledControlBeforeLock(projectRoot, paths.engine, options);
-        await refuseStalePackagingBeforeLock(projectRoot, paths.engine, options, normalizedPaths);
+        await refuseStalePackagingBeforeLock(projectRoot, paths.engine, options, {
+            normalizedPaths,
+            launchablePath,
+        });
     }
     return waitForResourcesBeforeLock(paths.engine, config, options, {
         launchablePath,
@@ -195,16 +197,17 @@ async function refuseCompiledControlBeforeLock(projectRoot, engineDir, options)
  * 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.
+ * the invocation would end `control=inconclusive` after a full queue.
  */
-async function refuseStalePackagingBeforeLock(projectRoot, engineDir, options, normalizedPaths) {
+async function refuseStalePackagingBeforeLock(projectRoot, engineDir, options, request) {
     if (options.allowStaleBuild === true || options.allowStaleComponents === true)
         return;
     if ((await readBuildRunState(projectRoot)).kind === 'running')
         return;
     try {
-        await enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths, {
+        await enforceStaleBuildGate(projectRoot, engineDir, options, request.normalizedPaths, {
             quiet: true,
+            launchablePath: request.launchablePath,
         });
     }
     catch (error) {

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

@@ -44,8 +44,8 @@ const TEST_HELP_TEXT = [
     '',
     'Machine-readable verdict: every run (single, sharded, --canary,',
     '--doctor) ends with exactly one raw stdout line',
-    '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|harness-arguments|test-failures|',
-    '  no-tests|preflight|inconclusive|lock-timeout|killed] [checks=<n>]',
+    '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|server-startup|harness-arguments|',
+    '  test-failures|no-tests|preflight|inconclusive|lock-timeout|killed] [checks=<n>]',
     '  [unexpected=<n>] [started=<n>/<m> first-unstarted=<path>]',
     '  [shards=<p>/<t>] [(<note>)] [shuffle=<seed>]',
     '  [runs=<p>/<n>] [control=caught|missed|inconclusive]',

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

@@ -18,6 +18,13 @@ export interface TestFileResult extends RawTestResult {
     shard: string;
     /** Line of the run log where this file's dispatch began (1-based). */
     logLine: number;
+    /**
+     * The shard's dispatched files, on a harness pseudo-record only (see
+     * {@link HARNESS_PSEUDO_TEST}).
+     */
+    shardFiles?: string[];
+    /** The shard's one file, on a harness pseudo-record of a one-file shard. */
+    file?: string;
 }
 /** The document `--results` writes. */
 export interface TestResultsDocument {
@@ -38,12 +45,14 @@ export declare function resetTestResults(): void;
  *
  * @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
+ * @param context - Run, shard and run-log line of the dispatch, and the
+ *   shard's dispatched files for harness pseudo-records
  */
 export declare function recordTestResults(results: readonly RawTestResult[], unfinished: readonly string[], context: {
     run: number;
     shard: string;
     logLine: number;
+    shardFiles?: readonly string[];
 }): void;
 /** The results collected so far (for tests and the shard summary). */
 export declare function collectedTestResults(): TestResultsDocument;

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

@@ -14,6 +14,13 @@ import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { writeJson } from '../utils/fs.js';
+/**
+ * The `test` id mozlog gives a result the harness itself reports, such as
+ * the no-output TIMEOUT of a hung browser: a record that names no test
+ * file. It keeps that id, and gains the shard's files so a consumer can
+ * attribute it without matching `shard` labels back to paths.
+ */
+const HARNESS_PSEUDO_TEST = 'automation.py';
 let collected = { schemaVersion: 1, files: [], unfinished: [] };
 /** Clears the collector at the start of an invocation. */
 export function resetTestResults() {
@@ -24,15 +31,25 @@ export function resetTestResults() {
  *
  * @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
+ * @param context - Run, shard and run-log line of the dispatch, and the
+ *   shard's dispatched files for harness pseudo-records
  */
 export function recordTestResults(results, unfinished, context) {
-    for (const result of results)
-        collected.files.push({ ...result, ...context });
+    const { shardFiles, ...dispatch } = context;
+    for (const result of results) {
+        collected.files.push({ ...result, ...dispatch, ...harnessRecordFiles(result, shardFiles) });
+    }
     for (const test of unfinished) {
         collected.unfinished.push({ test, run: context.run, shard: context.shard });
     }
 }
+/** The `shardFiles`/`file` keys a harness pseudo-record gains. */
+function harnessRecordFiles(result, shardFiles) {
+    if (result.test !== HARNESS_PSEUDO_TEST || shardFiles === undefined)
+        return {};
+    const only = shardFiles.length === 1 ? shardFiles[0] : undefined;
+    return { shardFiles: [...shardFiles], ...(only === undefined ? {} : { file: only }) };
+}
 /** The results collected so far (for tests and the shard summary). */
 export function collectedTestResults() {
     return collected;

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

@@ -10,6 +10,7 @@
  * stays available via `--no-shard`.
  */
 import { type DisplaySleepState } from '../core/display-state.js';
+import { type HarnessServerPorts } from '../core/harness-port-reservation.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';
@@ -74,6 +75,11 @@ export interface TestRunOutcome {
     displayState?: DisplaySleepState | undefined;
     /** Per-file results from the raw log, when the run wrote one. */
     fileResults?: RawTestResult[] | undefined;
+    /**
+     * The mochitest server ports the last attempt reported (its "falling
+     * back to port" lines), for the shard line's `ports=` key.
+     */
+    serverPorts?: HarnessServerPorts | undefined;
 }
 /**
  * Runs one mach test invocation for `paths`, retrying recognized harness

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

@@ -12,6 +12,7 @@
  */
 import { join } from 'node:path';
 import { probeDisplaySleepState } from '../core/display-state.js';
+import { createHarnessPortTracker, } from '../core/harness-port-reservation.js';
 import { runMachTestSuite } from '../core/mach.js';
 import { parentExited } from '../core/parent-exit-watchdog.js';
 import { activeRunLogLine, getActiveRunLogPath } from '../core/run-log.js';
@@ -68,12 +69,17 @@ async function runTestsWithRetriesInner(ctx, paths, env, label) {
     let verdict;
     let rawLog;
     let logLine;
+    let portTracker;
     for (;;) {
         attempts += 1;
         let tracker = createStartMarkerTracker();
+        portTracker = createHarnessPortTracker();
         const raw = rawLogDispatchArgs(ctx, extraArgs);
         logLine = activeRunLogLine();
-        const dispatched = await runTrackedMachTestSuite(ctx, kind, paths, raw.args, env, tracker);
+        const dispatched = await runTrackedMachTestSuite(ctx, kind, paths, raw.args, env, [
+            tracker,
+            portTracker,
+        ]);
         result = dispatched;
         // The parent that was reading this run is gone and the watchdog has
         // already killed the harness. Classifying the corpse would call it a
@@ -108,9 +114,14 @@ async function runTestsWithRetriesInner(ctx, paths, env, label) {
         verdict = vetoIncompletePass(classifyHarnessRun(result.exitCode, combined, paths), combined, paths, rawLog !== undefined && rawLog.markers.started.length > 0
             ? { markers: rawLog.markers, source: 'raw' }
             : { markers: tracker.markers(), source: 'stream' });
+        // A mochitest server that never came up is retried like a crash: no
+        // test ran, and a parallel instance's port race is not a result.
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)
             break;
-        warn(`Harness crash detected (${verdict.signature?.reason ?? 'unknown shape'}): ` +
+        const shape = verdict.signature?.verdictReason === 'server-startup'
+            ? 'Harness server startup failed'
+            : 'Harness crash detected';
+        warn(`${shape} (${verdict.signature?.reason ?? 'unknown shape'}): ` +
             `${verdict.signature?.line ?? ''}\n` +
             `Retrying (attempt ${attempts + 1} of ${maxAttempts})...`);
     }
@@ -137,6 +148,7 @@ async function runTestsWithRetriesInner(ctx, paths, env, label) {
             run: ctx.repetition ?? 1,
             shard: label,
             logLine,
+            shardFiles: paths,
         });
     }
     return {
@@ -146,8 +158,14 @@ async function runTestsWithRetriesInner(ctx, paths, env, label) {
         appdirInjectionAttempted,
         displayState,
         ...(rawLog === undefined ? {} : { fileResults: rawLog.results }),
+        ...serverPortsOf(portTracker),
     };
 }
+/** The `serverPorts` field of an outcome, present only when a port was seen. */
+function serverPortsOf(tracker) {
+    const ports = tracker.ports();
+    return Object.keys(ports).length > 0 ? { serverPorts: ports } : {};
+}
 /** Sequence for raw-log file names, unique within the process. */
 let rawLogSequence = 0;
 /**
@@ -170,7 +188,7 @@ function rawLogDispatchArgs(ctx, extraArgs) {
  * post-close reaping, the process-group announcement, and the parent-exit
  * watchdog for exactly as long as mach runs.
  */
-async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env, tracker) {
+async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env, trackers) {
     const teardown = createHarnessTeardown({
         objDir: ctx.objDir === undefined ? undefined : join(ctx.engineDir, ctx.objDir),
         pgidFile: ctx.pgidFile,
@@ -196,7 +214,8 @@ async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env, tracker
             teardown: {
                 ...teardown.hooks,
                 onOutputChunk: (stream, chunk) => {
-                    tracker.onChunk(stream, chunk);
+                    for (const tracker of trackers)
+                        tracker.onChunk(stream, chunk);
                     teardown.hooks.onOutputChunk?.(stream, chunk);
                 },
             },

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

@@ -62,13 +62,17 @@ export interface ShardRunOptions {
  * `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`.
+ * contract instead of collapsing every failure to `test-failures`. When
+ * every crashed shard is a server that never started, the aggregate keeps
+ * that signature, so its line says `reason=server-startup` too.
  */
 export declare function deriveAggregateShardVerdict(shards: ShardOutcome[]): HarnessRunVerdict;
 /**
  * The `FIREFORGE-SHARD:` line for one finished shard: the verdict it would
- * have printed alone, plus `shard=<i>/<n>` and `path=<label>`. Never a
- * `FIREFORGE-VERDICT:` line, so the run keeps exactly one.
+ * have printed alone, plus `shard=<i>/<n>` and `path=<label>`, and
+ * `ports=http:N,ssl:N,ws:N` when the harness reported the mochitest server
+ * ports it took. Never a `FIREFORGE-VERDICT:` line, so the run keeps
+ * exactly one.
  */
 export declare function formatShardLine(shard: ShardOutcome, index: number, total: number, failedFiles?: readonly string[]): string;
 /**