@hominis/fireforge 0.52.0 → 0.54.0

package/dist/src/core/rebase-session.js

@@ -29,9 +29,8 @@ const REBASE_PATCH_STATUSES = [
 /**
  * Drops payload that does not belong to an entry's status.
  *
- * Applied on read so a session written by an older FireForge, where
- * `rebase --continue` left `error`/`conflictingFiles` on a now-`resolved`
- * entry, loads cleanly and is corrected, instead of being refused by a
+ * Applied on read so a session whose `resolved` entry still carries
+ * `error`/`conflictingFiles` loads cleanly and is corrected, instead of being refused by a
  * stricter validator mid-rebase.
  *
  * @param entry - A structurally valid entry, possibly carrying stale payload
@@ -145,11 +144,10 @@ export async function readRebaseSession(projectRoot) {
     if (!isValidSession(data)) {
         return { present: true, valid: false, reason: 'the file is not a valid rebase session' };
     }
-    // Normalize on read: an older session can carry a failure's
+    // Normalize on read: a session can carry a failure's
     // `error`/`conflictingFiles` on an entry whose status has since been
     // flipped to `resolved`. Correcting it here is what lets the validator
-    // stay permissive, so an in-flight rebase from an older FireForge still
-    // loads.
+    // stay permissive, so such an in-flight rebase still loads.
     return {
         present: true,
         valid: true,

package/dist/src/core/register-xpcshell-test.d.ts

@@ -2,7 +2,8 @@
  * xpcshell test-file registration. Without it, xpcshell test files (e.g.
  * `<module-dir>/test/unit/test_*.js`) are rejected by `fireforge register`
  * as "Unknown file pattern". This writer inserts the `["test_*.js"]` section
- * into the directory's `xpcshell.toml` (alphabetically, idempotently). With
+ * into the directory's `xpcshell.toml` (alphabetically or after the
+ * `--after` entry, idempotently). With
  * `--create-manifest` it also creates the manifest and wires
  * `XPCSHELL_TESTS_MANIFESTS` into the nearest moz.build.
  */
@@ -14,16 +15,36 @@ import type { RegisterResult } from './register-result.js';
  * missing rather than the file as unregistered).
  */
 export declare function isXpcshellTestRegistered(engineDir: string, dirRel: string, fileName: string): Promise<boolean>;
+/** Where a new section goes and what placed it there. */
+export interface XpcshellSectionPlacement {
+    /** The manifest content with the section inserted. */
+    content: string;
+    /** The `["…"]` header of the `--after` entry the section follows. */
+    previousEntry?: string | undefined;
+    /** `--after` named no entry, so the section went in sort order. */
+    afterFallback?: boolean | undefined;
+}
 /**
- * Inserts the `["<fileName>"]` section into the manifest content in
- * mozbuild's case-insensitive sort order relative to the other test
- * sections, keeping one blank line between sections. Exported for direct
- * unit testing.
+ * Places the `["<fileName>"]` section in the manifest content.
+ *
+ * Without `after`, the section goes in mozbuild's case-insensitive sort
+ * order relative to the other test sections. With `after`, it goes right
+ * after the named entry's whole block (its keys included). Either way it
+ * is inserted ahead of the `#` comment lines that introduce the next
+ * entry, never between a comment and its entry, keeping one
+ * blank line between sections.
  */
-export declare function insertXpcshellManifestSection(content: string, fileName: string): string;
+export declare function placeXpcshellManifestSection(content: string, fileName: string, after?: string): XpcshellSectionPlacement;
+/**
+ * Inserts the `["<fileName>"]` section into the manifest content; see
+ * {@link placeXpcshellManifestSection}. Exported for direct unit testing.
+ *
+ * @internal
+ */
+export declare function insertXpcshellManifestSection(content: string, fileName: string, after?: string): string;
 /**
  * Registers an xpcshell test file in its directory's `xpcshell.toml`.
  * With `createManifest`, a missing manifest is scaffolded and wired into
  * the nearest moz.build via `XPCSHELL_TESTS_MANIFESTS`.
  */
-export declare function registerXpcshellTest(engineDir: string, dirRel: string, fileName: string, dryRun?: boolean, createManifest?: boolean): Promise<RegisterResult>;
+export declare function registerXpcshellTest(engineDir: string, dirRel: string, fileName: string, dryRun?: boolean, createManifest?: boolean, after?: string): Promise<RegisterResult>;

package/dist/src/core/register-xpcshell-test.js

@@ -3,7 +3,8 @@
  * xpcshell test-file registration. Without it, xpcshell test files (e.g.
  * `<module-dir>/test/unit/test_*.js`) are rejected by `fireforge register`
  * as "Unknown file pattern". This writer inserts the `["test_*.js"]` section
- * into the directory's `xpcshell.toml` (alphabetically, idempotently). With
+ * into the directory's `xpcshell.toml` (alphabetically or after the
+ * `--after` entry, idempotently). With
  * `--create-manifest` it also creates the manifest and wires
  * `XPCSHELL_TESTS_MANIFESTS` into the nearest moz.build.
  */
@@ -32,40 +33,82 @@ export async function isXpcshellTestRegistered(engineDir, dirRel, fileName) {
     const content = await readText(manifestPath);
     return content.includes(`["${fileName}"]`);
 }
+const SECTION_HEADER = /^\["([^"]+)"\]\s*$/;
 /**
- * Inserts the `["<fileName>"]` section into the manifest content in
- * mozbuild's case-insensitive sort order relative to the other test
- * sections, keeping one blank line between sections. Exported for direct
- * unit testing.
+ * The line where the block headed at `headerIndex` starts: the header
+ * itself, or the first of the `#` comment lines directly above it. A
+ * comment describes the entry below it, so nothing is inserted between
+ * them.
  */
-export function insertXpcshellManifestSection(content, fileName) {
+function blockStart(lines, headerIndex) {
+    let start = headerIndex;
+    while (start > 0 && (lines[start - 1] ?? '').trimStart().startsWith('#'))
+        start -= 1;
+    return start;
+}
+/** Index of the section header `after` names: exact name first, then a substring. */
+function findAfterHeader(lines, after) {
+    const headers = lines
+        .map((line, index) => ({ index, line, name: SECTION_HEADER.exec(line)?.[1] }))
+        .filter((header) => header.name !== undefined);
+    const exact = headers.find((header) => header.name === after || header.line.trim() === after);
+    return (exact ?? headers.find((header) => header.line.includes(after)))?.index ?? -1;
+}
+function spliceSection(lines, index, fileName) {
+    if (index === -1) {
+        // Append after the last section (or at end of file when there are no
+        // sections yet), keeping exactly one trailing newline.
+        while (lines.length > 0 && (lines.at(-1) ?? '').trim() === '')
+            lines.pop();
+        return [...lines, '', `["${fileName}"]`, ''].join('\n');
+    }
+    lines.splice(index, 0, `["${fileName}"]`, '');
+    return lines.join('\n');
+}
+/**
+ * Places the `["<fileName>"]` section in the manifest content.
+ *
+ * Without `after`, the section goes in mozbuild's case-insensitive sort
+ * order relative to the other test sections. With `after`, it goes right
+ * after the named entry's whole block (its keys included). Either way it
+ * is inserted ahead of the `#` comment lines that introduce the next
+ * entry, never between a comment and its entry, keeping one
+ * blank line between sections.
+ */
+export function placeXpcshellManifestSection(content, fileName, after) {
     const lines = content.split('\n');
-    const sectionHeaderPattern = /^\["([^"]+)"\]\s*$/;
-    let insertIndex = -1;
-    for (let i = 0; i < lines.length; i += 1) {
-        const match = sectionHeaderPattern.exec(lines[i] ?? '');
-        if (!match)
-            continue;
-        if (insertIndex === -1 && mozbuildSortCompare(fileName, match[1] ?? '') < 0) {
-            insertIndex = i;
+    const headerIndexes = lines.flatMap((line, index) => (SECTION_HEADER.test(line) ? [index] : []));
+    if (after !== undefined) {
+        const afterIndex = findAfterHeader(lines, after);
+        if (afterIndex !== -1) {
+            const next = headerIndexes.find((index) => index > afterIndex);
+            return {
+                content: spliceSection(lines, next === undefined ? -1 : blockStart(lines, next), fileName),
+                previousEntry: (lines[afterIndex] ?? '').trim(),
+            };
         }
     }
-    if (insertIndex !== -1) {
-        lines.splice(insertIndex, 0, `["${fileName}"]`, '');
-        return lines.join('\n');
-    }
-    // Append after the last section (or at end of file when there are no
-    // sections yet), keeping exactly one trailing newline.
-    while (lines.length > 0 && (lines.at(-1) ?? '').trim() === '')
-        lines.pop();
-    return [...lines, '', `["${fileName}"]`, ''].join('\n');
+    const before = headerIndexes.find((index) => mozbuildSortCompare(fileName, SECTION_HEADER.exec(lines[index] ?? '')?.[1] ?? '') < 0);
+    return {
+        content: spliceSection(lines, before === undefined ? -1 : blockStart(lines, before), fileName),
+        ...(after !== undefined ? { afterFallback: true } : {}),
+    };
+}
+/**
+ * Inserts the `["<fileName>"]` section into the manifest content; see
+ * {@link placeXpcshellManifestSection}. Exported for direct unit testing.
+ *
+ * @internal
+ */
+export function insertXpcshellManifestSection(content, fileName, after) {
+    return placeXpcshellManifestSection(content, fileName, after).content;
 }
 /**
  * Registers an xpcshell test file in its directory's `xpcshell.toml`.
  * With `createManifest`, a missing manifest is scaffolded and wired into
  * the nearest moz.build via `XPCSHELL_TESTS_MANIFESTS`.
  */
-export async function registerXpcshellTest(engineDir, dirRel, fileName, dryRun = false, createManifest = false) {
+export async function registerXpcshellTest(engineDir, dirRel, fileName, dryRun = false, createManifest = false, after) {
     const manifestRel = `${dirRel}/xpcshell.toml`;
     const manifestPath = join(engineDir, manifestRel);
     const entry = `["${fileName}"]`;
@@ -86,9 +129,15 @@ export async function registerXpcshellTest(engineDir, dirRel, fileName, dryRun =
     if (content.includes(entry)) {
         return { manifest: manifestRel, entry, skipped: true };
     }
-    const updated = insertXpcshellManifestSection(content, fileName);
+    const placement = placeXpcshellManifestSection(content, fileName, after);
     if (!dryRun) {
-        await writeText(manifestPath, updated);
+        await writeText(manifestPath, placement.content);
     }
-    return { manifest: manifestRel, entry, skipped: false };
+    return {
+        manifest: manifestRel,
+        entry,
+        skipped: false,
+        previousEntry: placement.previousEntry,
+        afterFallback: placement.afterFallback,
+    };
 }

package/dist/src/core/run-log.d.ts

@@ -1,13 +1,13 @@
 /**
  * Per-run output logs under `.fireforge/logs/`.
  *
- * A run's diagnosis used to exist in exactly one place: the terminal. Piping
- * through `tail`/`grep`, the ergonomic default when output is long, keeps
- * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say what
- * broke, and it launders the exit code besides. The operator rule ("never
- * pipe a run") was written down three times downstream and broken after each
- * writing, so this is not an operator problem: the tool is the only party
- * that can make the log survive the mistake.
+ * Without a log, a run's diagnosis exists in exactly one place: the terminal.
+ * Piping through `tail`/`grep`, the ergonomic default when output is long,
+ * keeps the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say
+ * what broke, and it launders the exit code besides. An operator rule
+ * ("never pipe a run") does not hold in practice, so this is not an operator
+ * problem: the tool is the only party that can make the log survive the
+ * mistake.
  *
  * So `test` and `build` write their own complete copy as they stream, and the
  * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
@@ -16,7 +16,7 @@
  * Everything here is best-effort. A log is a diagnostic aid, and a run must
  * never fail because one could not be opened, written, or pruned.
  * Every entry point swallows its errors and degrades to "no log", which is
- * exactly the behaviour that existed before this module.
+ * exactly the behaviour of a run without this module.
  */
 /** A run log sink. `write` never throws. */
 export interface RunLog {

package/dist/src/core/run-log.js

@@ -2,13 +2,13 @@
 /**
  * Per-run output logs under `.fireforge/logs/`.
  *
- * A run's diagnosis used to exist in exactly one place: the terminal. Piping
- * through `tail`/`grep`, the ergonomic default when output is long, keeps
- * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say what
- * broke, and it launders the exit code besides. The operator rule ("never
- * pipe a run") was written down three times downstream and broken after each
- * writing, so this is not an operator problem: the tool is the only party
- * that can make the log survive the mistake.
+ * Without a log, a run's diagnosis exists in exactly one place: the terminal.
+ * Piping through `tail`/`grep`, the ergonomic default when output is long,
+ * keeps the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say
+ * what broke, and it launders the exit code besides. An operator rule
+ * ("never pipe a run") does not hold in practice, so this is not an operator
+ * problem: the tool is the only party that can make the log survive the
+ * mistake.
  *
  * So `test` and `build` write their own complete copy as they stream, and the
  * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
@@ -17,7 +17,7 @@
  * Everything here is best-effort. A log is a diagnostic aid, and a run must
  * never fail because one could not be opened, written, or pruned.
  * Every entry point swallows its errors and degrades to "no log", which is
- * exactly the behaviour that existed before this module.
+ * exactly the behaviour of a run without this module.
  */
 import { createWriteStream } from 'node:fs';
 import { mkdir, readdir, stat, unlink } from 'node:fs/promises';

package/dist/src/core/status-classify.d.ts

@@ -63,8 +63,7 @@ export interface ClassifiedFile extends StatusFile {
  * Builds the file → owning-patch-filenames multimap from manifest rows.
  * Single source of truth for cross-patch claim detection: status
  * classification, verify's cross-claim check, and the ownership table all
- * consume this builder (they used to each rebuild it, one drift away from
- * disagreeing about what "claimed" means).
+ * consume this builder, so they cannot disagree about what "claimed" means.
  */
 export declare function buildPatchClaims(manifestPatches: ReadonlyArray<{
     filename: string;

package/dist/src/core/status-classify.js

@@ -20,8 +20,7 @@ import { classifyBinaryOwnedFile } from './status-binary.js';
  * Builds the file → owning-patch-filenames multimap from manifest rows.
  * Single source of truth for cross-patch claim detection: status
  * classification, verify's cross-claim check, and the ownership table all
- * consume this builder (they used to each rebuild it, one drift away from
- * disagreeing about what "claimed" means).
+ * consume this builder, so they cannot disagree about what "claimed" means.
  */
 export function buildPatchClaims(manifestPatches) {
     const ownersByPath = new Map();

package/dist/src/core/test-harness-crash.d.ts

@@ -23,6 +23,7 @@
  */
 export type { HarnessCrashSignature } from './test-harness-signature.js';
 import { type HarnessCrashSignature, type IncompleteRunEvidence } from './test-harness-signature.js';
+export { buildHarnessCrashMessage } from './test-harness-infra.js';
 export { headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint } from './test-stall-triage.js';
 /** How a completed harness run should be interpreted. */
 export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'harness-arguments' | 'no-tests';
@@ -160,7 +161,10 @@ export declare function detectHarnessCrashSignature(output: string): HarnessCras
  * 1. A recognized crash signature wins regardless of exit code (the
  *    shutdown re-entry shape exits non-zero on an otherwise green run,
  *    and the hang shape can even exit zero with a `Passed: 0` summary).
- * 2. No execution signal with explicit paths requested means no test ran:
+ * 2. No execution signal with explicit paths requested means no test ran.
+ *    A mochitest server that failed to start explains that, and is a
+ *    retriable infrastructure failure (`harness-crash` with
+ *    `reason=server-startup` on the verdict line). Otherwise it is
  *    `no-tests`, even when the exit code is zero. The execution signal is
  *    a `TEST-START` line (generic `mach test` / browser-chrome dispatch)
  *    or the suite-specific xpcshell result-summary block (the xpcshell
@@ -206,8 +210,6 @@ export declare function formatFireforgeVerdictLine(verdict: HarnessRunVerdict, s
  * pass, regardless of how green the embedded counts look).
  */
 export declare function buildGreenSummaryRejectedMessage(rejection: GreenSummaryRejection, exitCode: number): string;
-/** Builds the operator-facing failure message after retries are exhausted. */
-export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number, commandLabel?: string): string;
 /**
  * True when a harness run died on SIGSEGV having produced no test evidence
  * whatsoever.

package/dist/src/core/test-harness-crash.js

@@ -23,9 +23,13 @@
  * reporting phantom test failures (or phantom passes).
  */
 import { hasKnownTeardownNoise } from './mach-known-noise-filter.js';
+import { detectServerStartupFailure } from './test-harness-infra.js';
 import { truncateEvidence, unmarkedFailureEvidenceNote, } from './test-harness-verdict-notes.js';
 import { classifyProfileArgumentFailure } from './test-profile-files.js';
 import { formatIncompleteSuffix, formatShardsSuffix, } from './test-harness-signature.js';
+// The operator message after exhausted retries lives beside the
+// server-startup shape in `test-harness-infra.ts`.
+export { buildHarnessCrashMessage } from './test-harness-infra.js';
 // The no-output-stall triage text lives in `test-stall-triage.ts` (it is
 // operator advice, not classification) and is re-exported here so the
 // command layer keeps importing its harness diagnostics from one module.
@@ -458,7 +462,10 @@ export function detectHarnessCrashSignature(output) {
  * 1. A recognized crash signature wins regardless of exit code (the
  *    shutdown re-entry shape exits non-zero on an otherwise green run,
  *    and the hang shape can even exit zero with a `Passed: 0` summary).
- * 2. No execution signal with explicit paths requested means no test ran:
+ * 2. No execution signal with explicit paths requested means no test ran.
+ *    A mochitest server that failed to start explains that, and is a
+ *    retriable infrastructure failure (`harness-crash` with
+ *    `reason=server-startup` on the verdict line). Otherwise it is
  *    `no-tests`, even when the exit code is zero. The execution signal is
  *    a `TEST-START` line (generic `mach test` / browser-chrome dispatch)
  *    or the suite-specific xpcshell result-summary block (the xpcshell
@@ -512,7 +519,10 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     }
     const ranTests = hasExecutionSignal(output);
     if (!ranTests && requestedPaths.length > 0) {
-        return { kind: 'no-tests', ...counts };
+        const serverStartup = detectServerStartupFailure(output);
+        return serverStartup === undefined
+            ? { kind: 'no-tests', ...counts }
+            : { kind: 'harness-crash', signature: serverStartup, ...counts };
     }
     if (exitCode === 0) {
         return { kind: 'tests-ran-ok', ...counts };
@@ -663,7 +673,7 @@ export function formatFireforgeVerdictLine(verdict, shards) {
     const tail = `${formatShardsSuffix(shards)}${verdict.note !== undefined ? ` (${verdict.note})` : ''}`;
     if (verdict.kind === 'tests-ran-ok')
         return `FIREFORGE-VERDICT: PASS${counts}${tail}`;
-    const reason = verdict.kind === 'harness-crash' ? 'crash' : verdict.kind;
+    const reason = verdict.kind === 'harness-crash' ? (verdict.signature?.verdictReason ?? 'crash') : verdict.kind;
     return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${formatIncompleteSuffix(verdict.incomplete)}${tail}`;
 }
 /**
@@ -690,17 +700,6 @@ export function buildGreenSummaryRejectedMessage(rejection, exitCode) {
         'FAILED run — check the crash/truncation point in the output above, then re-run the ' +
         'remaining files.');
 }
-/** Builds the operator-facing failure message after retries are exhausted. */
-export function buildHarnessCrashMessage(signature, attempts, commandLabel = 'mach test') {
-    return (`${commandLabel} crashed in the harness itself (not in your tests) on all ${attempts} attempt(s).\n\n` +
-        `Detected shape: ${signature.reason}\n` +
-        `Evidence line: ${signature.line}\n\n` +
-        'This failure mode is environmental (mozlog resource monitor / psutil on macOS, focus-stall ' +
-        'shutdown re-entry, or a pre-test hang) rather than a test regression. Re-run the command, ' +
-        'raise the retry budget with --harness-retries <n>, or run the file in isolation. ' +
-        'If it persists across many runs, inspect the mach virtualenv (mach resyncs psutil on its own; ' +
-        'patching it manually does not stick).');
-}
 /**
  * Exit codes that mean "the child died on SIGSEGV": Node reports a
  * signal-killed child as the negated signal number, while a shell layer

package/dist/src/core/test-harness-infra.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Harness failures that are the environment's, not the tests': the
+ * operator message for a recognized harness crash after its retries ran
+ * out, and the mochitest server that never came up.
+ *
+ * A server never comes up when the harness's httpd cannot bind its port,
+ * typically because a parallel `--jobs` instance, a sibling checkout or a
+ * leftover httpd held it (see `harness-port-reservation.ts`). Without this
+ * shape the run read as `no-tests`, a finding about the
+ * request, and was not retried. It is an infrastructure failure instead:
+ * `classifyHarnessRun` reports it as a `harness-crash` carrying
+ * `verdictReason: 'server-startup'`, so the harness-crash retry loop
+ * (`--harness-retries`) reruns the shard, and a run that exhausts the
+ * budget says `reason=server-startup` on its verdict line.
+ */
+import type { HarnessCrashSignature } from './test-harness-signature.js';
+/**
+ * Detects a mochitest server that failed to start. The caller checks that
+ * no test ran first: both lines precede any test.
+ *
+ * @param output - Captured mach stdout and stderr
+ * @returns The infrastructure signature, or undefined
+ */
+export declare function detectServerStartupFailure(output: string): HarnessCrashSignature | undefined;
+/**
+ * Builds the operator-facing failure message after retries are exhausted.
+ *
+ * @param signature - The recognized shape
+ * @param attempts - Attempts made
+ * @param commandLabel - The mach command, for the message
+ */
+export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number, commandLabel?: string): string;

package/dist/src/core/test-harness-infra.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Harness failures that are the environment's, not the tests': the
+ * operator message for a recognized harness crash after its retries ran
+ * out, and the mochitest server that never came up.
+ *
+ * A server never comes up when the harness's httpd cannot bind its port,
+ * typically because a parallel `--jobs` instance, a sibling checkout or a
+ * leftover httpd held it (see `harness-port-reservation.ts`). Without this
+ * shape the run read as `no-tests`, a finding about the
+ * request, and was not retried. It is an infrastructure failure instead:
+ * `classifyHarnessRun` reports it as a `harness-crash` carrying
+ * `verdictReason: 'server-startup'`, so the harness-crash retry loop
+ * (`--harness-retries`) reruns the shard, and a run that exhausts the
+ * budget says `reason=server-startup` on its verdict line.
+ */
+/**
+ * The harness's own lines for the shape: the httpd's bind failure
+ * (`!!! could not start server on port 8888`) and `runtests.py`'s wait for
+ * it (`Timed out while waiting for server startup`).
+ */
+const SERVER_STARTUP_FAILURE_PATTERNS = [
+    /could not start server on port \d+/,
+    /Timed out while waiting for server startup/,
+];
+/**
+ * Detects a mochitest server that failed to start. The caller checks that
+ * no test ran first: both lines precede any test.
+ *
+ * @param output - Captured mach stdout and stderr
+ * @returns The infrastructure signature, or undefined
+ */
+export function detectServerStartupFailure(output) {
+    for (const line of output.split(/\r?\n/)) {
+        if (SERVER_STARTUP_FAILURE_PATTERNS.some((pattern) => pattern.test(line))) {
+            return {
+                reason: 'mochitest server failed to start (server-startup)',
+                line: line.trim(),
+                verdictReason: 'server-startup',
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * Builds the operator-facing failure message after retries are exhausted.
+ *
+ * @param signature - The recognized shape
+ * @param attempts - Attempts made
+ * @param commandLabel - The mach command, for the message
+ */
+export function buildHarnessCrashMessage(signature, attempts, commandLabel = 'mach test') {
+    if (signature.verdictReason !== 'server-startup') {
+        return (`${commandLabel} crashed in the harness itself (not in your tests) on all ${attempts} attempt(s).\n\n` +
+            `Detected shape: ${signature.reason}\n` +
+            `Evidence line: ${signature.line}\n\n` +
+            'This failure mode is environmental (mozlog resource monitor / psutil on macOS, focus-stall ' +
+            'shutdown re-entry, or a pre-test hang) rather than a test regression. Re-run the command, ' +
+            'raise the retry budget with --harness-retries <n>, or run the file in isolation. ' +
+            'If it persists across many runs, inspect the mach virtualenv (mach resyncs psutil on its own; ' +
+            'patching it manually does not stick).');
+    }
+    return (`${commandLabel} could not start a mochitest server on all ${attempts} attempt(s), so no ` +
+        'test ran (an infrastructure failure, not a test result).\n\n' +
+        `Evidence line: ${signature.line}\n\n` +
+        'Another harness (a parallel --jobs instance, a sibling checkout, or a leftover httpd) ' +
+        'most likely held the server port when this one started. Re-run the shard, raise the ' +
+        'retry budget with --harness-retries <n>, or check "lsof -nP -iTCP:8888".');
+}

package/dist/src/core/test-harness-signature.d.ts

@@ -19,6 +19,12 @@ export interface HarnessCrashSignature {
     reason: string;
     /** The concrete output line the recognition was based on. */
     line: string;
+    /**
+     * The verdict line's `reason=` for an infrastructure shape that is not a
+     * crash of the harness: `server-startup` when a mochitest server never
+     * came up. Unset: `reason=crash`.
+     */
+    verdictReason?: 'server-startup';
 }
 /**
  * The verdict line's `started=<n>/<m> first-unstarted=<path>

package/dist/src/core/test-stale-check.d.ts

@@ -48,6 +48,44 @@ export declare function checkStaleBuildForTest(projectRoot: string, engineDir: s
  * result without matching the rendered copy.
  */
 export declare function formatStaleBuildWarning(result: StaleBuildResult): string;
+/** Result of {@link findCompiledSourcesNewerThanBinary}. */
+export interface StaleCompiledResult {
+    /** Engine-relative compiled sources modified after the binary was linked. Sorted. */
+    paths: string[];
+    /** Engine-relative file that anchored the comparison (the binary or its libxul). */
+    linkedPath: string;
+    /** When that file was last written. */
+    linkedAt: Date;
+}
+/**
+ * Changed compiled sources (C++, Rust, IDL, WebIDL, IPDL, StaticPrefList
+ * YAML, …) whose mtime is newer than the launchable build's last link.
+ * `mach build faster` compiles none of them, so such a run tests the
+ * binary from before the edit, which reads as a failed fix rather than a
+ * stale build. Candidates are the engine paths changed since the baseline
+ * plus every workdir edit; a fork's persistent patch diff is older than any
+ * build that followed it, so only genuine post-build edits remain.
+ * Returns undefined when there is nothing to compare against (no
+ * launchable binary).
+ *
+ * @param engineDir - Absolute engine directory
+ * @param baseline - Last-build baseline, when one exists
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export declare function findCompiledSourcesNewerThanBinary(engineDir: string, baseline: BuildBaseline | undefined, launchablePath: string | undefined): Promise<StaleCompiledResult | undefined>;
+/**
+ * The `stale-compiled` refusal (or, under `--allow-stale-build`, warning).
+ *
+ * @param result - A non-empty {@link StaleCompiledResult}
+ */
+export declare function formatStaleCompiledRefusal(result: StaleCompiledResult): string;
+/**
+ * The notice that explains why a `test --build` pre-test build escalated
+ * to a full `mach build` for stale compiled sources.
+ *
+ * @param result - A non-empty {@link StaleCompiledResult}
+ */
+export declare function formatStaleCompiledBuildNotice(result: StaleCompiledResult): string;
 /**
  * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
  * request (no paths) is checked against a scoped coverage record.