@hominis/fireforge 0.52.0 → 0.54.0

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 {
@@ -35,6 +36,11 @@ export interface TestRunHooks {
      * 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

@@ -24,8 +24,10 @@ import { TestFailureError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info, notice, success } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
+import { controlBuildRecorded, runControlRestoreBuild } from './test-control-restore.js';
 import { classifyTestHarnesses } from './test-modes.js';
 import { deriveControlOutcome, describeControlOutcome, formatAggregateBody, formatRunLine, parseCapturedVerdict, worstRun, } from './test-multi-verdict.js';
+import { rearmSpentWaits } from './test-prelock.js';
 import { emitAggregateVerdict, emitFailVerdict, setVerdictCapture, setVerdictRunAttribute, verdictEmitted, } from './test-verdict.js';
 function assertMultiRunUsage(testPaths, options) {
     const flag = options.negativeControl !== undefined ? '--negative-control' : '--repeat';
@@ -57,7 +59,9 @@ async function splitHarnesses(engineDir, testPaths, options) {
 }
 /** Options for every run after the first: the build and doctor run once. */
 function laterRunOptions(options) {
-    const later = { ...options };
+    // A later run follows the earlier runs' work under the same lock hold, so
+    // its browser and port checks wait out the budgets again.
+    const later = { ...rearmSpentWaits(options) };
     delete later.build;
     delete later.extendCoverage;
     delete later.refuseUnexportedDrift;
@@ -105,6 +109,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 +196,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()) {
@@ -190,6 +215,7 @@ export async function orchestrateTestRuns(projectRoot, testPaths, options, body,
                         ? {
                             beforeBuild: controlHook(controlPaths, plan, slot),
                             fullBuildReason: formatCompiledControlBuildNotice(compiled),
+                            ...(controlStamp === undefined ? {} : { controlBuild: controlStamp }),
                         }
                         : { beforeDispatch: controlHook(controlPaths, plan, slot) }),
             });
@@ -234,6 +260,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
@@ -49,3 +48,14 @@ export declare const TEST_BUILD_PREFLIGHT: {
  * @param options - Parsed test options
  */
 export declare function runTestPreLockPreflight(projectRoot: string, testPaths: string[], options: TestOptions): Promise<TestOptions>;
+/**
+ * `options` with the wait budgets the pre-lock pass spent put back, for a
+ * browser or port check that follows work this invocation already did
+ * under the lock: its pre-test build, or an earlier run of a sequence. A
+ * busy browser there is a peer that started after the lock was taken, and
+ * refusing would throw the build away, so it is waited out like the first
+ * check's.
+ *
+ * @param options - In-lock run options
+ */
+export declare function rearmSpentWaits(options: TestOptions): TestOptions;

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) {
@@ -216,15 +219,40 @@ async function refuseStalePackagingBeforeLock(projectRoot, engineDir, options, n
             'against a fresh build of the requested paths.', error.note);
     }
 }
-/** `options` without one wait budget, which this pass already spent. */
+/**
+ * `options` without one wait budget, which this pass already spent. The
+ * budget moves to `spentWaits`, for {@link rearmSpentWaits}.
+ */
 function withoutOption(options, key) {
-    const rest = { ...options };
+    const rest = { ...options, spentWaits: { ...options.spentWaits, [key]: options[key] } };
     if (key === 'waitBrowser')
         delete rest.waitBrowser;
     else
         delete rest.waitPort;
     return rest;
 }
+/**
+ * `options` with the wait budgets the pre-lock pass spent put back, for a
+ * browser or port check that follows work this invocation already did
+ * under the lock: its pre-test build, or an earlier run of a sequence. A
+ * busy browser there is a peer that started after the lock was taken, and
+ * refusing would throw the build away, so it is waited out like the first
+ * check's.
+ *
+ * @param options - In-lock run options
+ */
+export function rearmSpentWaits(options) {
+    const spent = options.spentWaits;
+    if (spent === undefined)
+        return options;
+    const rearmed = { ...options };
+    if (spent.waitBrowser !== undefined)
+        rearmed.waitBrowser = spent.waitBrowser;
+    if (spent.waitPort !== undefined)
+        rearmed.waitPort = spent.waitPort;
+    delete rearmed.spentWaits;
+    return rearmed;
+}
 /**
  * Spends `--wait-browser` and `--wait-port` before the lock, mirroring
  * which in-lock checks would apply to this run, and strips each budget it

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]',
@@ -86,7 +86,8 @@ const TEST_HELP_TEXT = [
     '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.',
+    'lock; the checks after a pre-test build or an earlier run of the',
+    'sequence wait the budgets out again.',
 ].join('\n');
 function registerTestMultiRunOptions(test) {
     return test

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;
 /**

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

@@ -13,6 +13,7 @@
  * judged per file from each dispatch's raw log: `shards=` then counts files
  * and `failed-shards=` names the files that failed.
  */
+import { formatHarnessServerPorts } from '../core/harness-port-reservation.js';
 import { getActiveRunLogPath, writeToActiveRunLog } from '../core/run-log.js';
 import { buildHarnessCrashMessage, formatFireforgeVerdictLine, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
 import { TestFailureError } from '../errors/build.js';
@@ -27,19 +28,32 @@ const SHARD_STATUS_LABEL = {
     'no-tests': 'NO-TESTS',
     'harness-arguments': 'ARGUMENTS',
 };
+/** The summary box's status word; a server that never started is not a crash. */
+function shardStatusLabel(verdict) {
+    return verdict.signature?.verdictReason === 'server-startup'
+        ? 'SERVER'
+        : SHARD_STATUS_LABEL[verdict.kind];
+}
 /**
  * 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`.
+ * 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 function deriveAggregateShardVerdict(shards) {
     const kinds = new Set(shards.map(({ outcome }) => outcome.verdict.kind));
     if (kinds.has('harness-arguments'))
         return { kind: 'harness-arguments' };
-    if (kinds.has('harness-crash'))
-        return { kind: 'harness-crash' };
+    if (kinds.has('harness-crash')) {
+        const crashes = shards.filter(({ outcome }) => outcome.verdict.kind === 'harness-crash');
+        const signature = crashes[0]?.outcome.verdict.signature;
+        return crashes.every(({ outcome }) => outcome.verdict.signature?.verdictReason === 'server-startup') && signature !== undefined
+            ? { kind: 'harness-crash', signature }
+            : { kind: 'harness-crash' };
+    }
     if (kinds.has('no-tests'))
         return { kind: 'no-tests' };
     if (kinds.has('test-failures'))
@@ -48,15 +62,18 @@ export function deriveAggregateShardVerdict(shards) {
 }
 /**
  * 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 function formatShardLine(shard, index, total, failedFiles) {
     const body = formatFireforgeVerdictLine(shard.outcome.verdict).slice('FIREFORGE-VERDICT: '.length);
     const files = failedFiles !== undefined && failedFiles.length > 0
         ? ` failed-files=${failedFiles.join(',')}`
         : '';
-    return `FIREFORGE-SHARD: ${body} shard=${index + 1}/${total} path=${shard.label.replace(/\s+/g, '_')}${files}`;
+    const ports = formatHarnessServerPorts(shard.outcome.serverPorts);
+    return `FIREFORGE-SHARD: ${body} shard=${index + 1}/${total} path=${shard.label.replace(/\s+/g, '_')}${files}${ports === undefined ? '' : ` ports=${ports}`}`;
 }
 function writeShardLine(line) {
     process.stdout.write(`${line}\n`);
@@ -163,7 +180,7 @@ function reportProgress(finished, total, jobs) {
  * counts as a whole.
  */
 function summarizeShards(shards, perFile) {
-    const lines = shards.map(({ label, outcome }) => `${SHARD_STATUS_LABEL[outcome.verdict.kind].padEnd(8)} ${label}` +
+    const lines = shards.map(({ label, outcome }) => `${shardStatusLabel(outcome.verdict).padEnd(8)} ${label}` +
         (outcome.attempts > 1 ? `  (${outcome.attempts} attempts)` : ''));
     const failingShards = shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
     let passed = shards.length - failingShards.length;

package/dist/src/commands/test-stale-gate.d.ts

@@ -29,9 +29,14 @@ import type { TestOptions } from '../types/commands/index.js';
  * stale-content refusal still applies to it unchanged.
  */
 export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[], 
-/** `quiet`: refuse only, without the exemption note (the pre-lock pass). */
+/**
+ * `quiet`: refuse only, without the exemption note (the pre-lock pass).
+ * `launchablePath`: the engine-relative binary the run launches, which
+ * anchors the stale-compiled check (skipped without one).
+ */
 gate?: {
     quiet?: boolean;
+    launchablePath?: string | undefined;
 }): Promise<void>;
 /**
  * Compiled-StaticComponents gate: refuses runs whose child process would

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

@@ -8,7 +8,7 @@
  * `src/core/test-stale-check.ts`.
  */
 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 { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findCompiledSourcesNewerThanBinary, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaleCompiledRefusal, 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 { isProcessAlive } from '../utils/errors.js';
@@ -35,14 +35,20 @@ import { describePerfStaleImpact } from './test-perf-scope.js';
  * stale-content refusal still applies to it unchanged.
  */
 export async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths, 
-/** `quiet`: refuse only, without the exemption note (the pre-lock pass). */
+/**
+ * `quiet`: refuse only, without the exemption note (the pre-lock pass).
+ * `launchablePath`: the engine-relative binary the run launches, which
+ * anchors the stale-compiled check (skipped without one).
+ */
 gate = {}) {
     const stale = await checkStaleBuildForTest(projectRoot, engineDir);
+    enforceControlBuiltGate(stale.baseline);
     const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
     if (!dispatchesNoTests) {
         await enforceCoverageGate(engineDir, stale.baseline, normalizedPaths);
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);
+    await enforceStaleCompiledGate(engineDir, stale.baseline, options, gate.launchablePath);
     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)}.`);
@@ -73,6 +79,38 @@ gate = {}) {
         throw new PreflightRefusalError(staleMessage, 'stale-build');
     }
 }
+/**
+ * Control-built refusal: the recorded build compiled a negative control
+ * into the binary, and no build since has recompiled the restored source
+ * (the run was killed, or its restore build failed). Every test against
+ * that binary tests the mutation. Not bypassable: `--allow-stale-build`
+ * accepts old content, not a deliberately broken binary.
+ */
+function enforceControlBuiltGate(baseline) {
+    const stamp = baseline?.controlBuild;
+    if (stamp === undefined)
+        return;
+    throw new PreflightRefusalError(`The binary under test was built with the negative control ${stamp.diffFile} applied ` +
+        `(${stamp.targets.map((target) => `engine/${target}`).join(', ')}, applied ${stamp.appliedAt}), ` +
+        'and no build has recompiled the restored source since. Run "fireforge build" to ' +
+        'rebuild the binary without the control, then rerun.', 'control-built');
+}
+/**
+ * Stale-compiled refusal: compiled sources modified after the binary under
+ * test was linked. `--allow-stale-build` downgrades it to a warning, as it
+ * does the stale-build refusal.
+ */
+async function enforceStaleCompiledGate(engineDir, baseline, options, launchablePath) {
+    const result = await findCompiledSourcesNewerThanBinary(engineDir, baseline, launchablePath);
+    if (result === undefined || result.paths.length === 0)
+        return;
+    const message = formatStaleCompiledRefusal(result);
+    if (options.allowStaleBuild === true) {
+        warn(message);
+        return;
+    }
+    throw new PreflightRefusalError(message, 'stale-compiled');
+}
 /**
  * Packaging-coverage refusal. A path outside the recorded scoped list is
  * still covered while its own staging inputs are unchanged against a