@hominis/fireforge 0.51.0 → 0.53.0

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-run-completeness.d.ts

@@ -17,10 +17,14 @@
  * `FAIL reason=test-failures`, and a short start count is stamped on the
  * verdict line as `started=<n>/<m> first-unstarted=<path>`.
  *
- * The start-count check only runs when at least one start marker names a
- * requested file. The suite-specific xpcshell dispatch can prove execution
- * with a result-summary block alone and print no `TEST_START` line, and a
- * run that never names its files cannot be counted against them.
+ * From streamed or captured text, the start-count check only runs when at
+ * least one start marker names a requested file. The suite-specific xpcshell
+ * dispatch can prove execution with a result-summary block alone and print
+ * no `TEST_START` line, and a run that never names its files cannot be
+ * counted against them. The structured raw log names every test by its
+ * manifest id, so a raw log whose starts name none of the requested files
+ * ran something else: a `--jobs` instance that read another instance's test
+ * list once passed on that instance's file.
  */
 import { type HarnessRunVerdict } from './test-harness-crash.js';
 import type { IncompleteRunEvidence } from './test-harness-signature.js';
@@ -62,8 +66,11 @@ export declare function createStartMarkerTracker(): StartMarkerTracker;
  * @param evidence - Captured mach stdout and stderr, or the markers
  *   collected from the complete stream
  * @param requestedPaths - Dispatched paths, in dispatch order
+ * @param authoritative - The markers come from the raw log, so a run whose
+ *   starts name no requested file is counted (as none started) instead of
+ *   being left uncounted
  */
-export declare function countStartedFiles(evidence: string | StartMarkers, requestedPaths: readonly string[]): {
+export declare function countStartedFiles(evidence: string | StartMarkers, requestedPaths: readonly string[], authoritative?: boolean): {
     started: number;
     requested: number;
     firstUnstarted?: string;

package/dist/src/core/test-run-completeness.js

@@ -18,10 +18,14 @@
  * `FAIL reason=test-failures`, and a short start count is stamped on the
  * verdict line as `started=<n>/<m> first-unstarted=<path>`.
  *
- * The start-count check only runs when at least one start marker names a
- * requested file. The suite-specific xpcshell dispatch can prove execution
- * with a result-summary block alone and print no `TEST_START` line, and a
- * run that never names its files cannot be counted against them.
+ * From streamed or captured text, the start-count check only runs when at
+ * least one start marker names a requested file. The suite-specific xpcshell
+ * dispatch can prove execution with a result-summary block alone and print
+ * no `TEST_START` line, and a run that never names its files cannot be
+ * counted against them. The structured raw log names every test by its
+ * manifest id, so a raw log whose starts name none of the requested files
+ * ran something else: a `--jobs` instance that read another instance's test
+ * list once passed on that instance's file.
  */
 import { SHUTDOWN_REENTRY_PATTERN, START_MARKER_PATTERN, TEST_FILE_BASENAME_PATTERN, } from './test-harness-crash.js';
 /**
@@ -80,8 +84,11 @@ export function createStartMarkerTracker() {
  * @param evidence - Captured mach stdout and stderr, or the markers
  *   collected from the complete stream
  * @param requestedPaths - Dispatched paths, in dispatch order
+ * @param authoritative - The markers come from the raw log, so a run whose
+ *   starts name no requested file is counted (as none started) instead of
+ *   being left uncounted
  */
-export function countStartedFiles(evidence, requestedPaths) {
+export function countStartedFiles(evidence, requestedPaths, authoritative = false) {
     const requested = requestedPaths.filter((path) => TEST_FILE_BASENAME_PATTERN.test(basenameOf(path)));
     if (requested.length === 0)
         return undefined;
@@ -92,8 +99,8 @@ export function countStartedFiles(evidence, requestedPaths) {
     };
     // Counting needs a dialect that names the requested files on its start
     // lines. When no start line names any of them, the output cannot be
-    // counted against the request at all.
-    if (!requested.some((path) => names(path, started)))
+    // counted against the request at all, unless it is the raw log.
+    if (!authoritative && !requested.some((path) => names(path, started)))
         return undefined;
     const unstarted = requested.filter((path) => !names(path, started) && !names(path, skipped));
     const firstUnstarted = unstarted[0];
@@ -125,7 +132,7 @@ export function vetoIncompletePass(verdict, output, requestedPaths, tracked) {
     // tracker means nothing was streamed through it, and the capture is then
     // the only evidence there is.
     const useTracked = tracked !== undefined && tracked.markers.started.length > 0;
-    const counted = countStartedFiles(useTracked ? tracked.markers : output, requestedPaths);
+    const counted = countStartedFiles(useTracked ? tracked.markers : output, requestedPaths, useTracked && tracked.source === 'raw');
     const unexpected = verdict.unexpected ?? 0;
     const truncated = counted?.firstUnstarted !== undefined;
     if (unexpected === 0 && shutdownLine === undefined && !truncated)

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

@@ -1,4 +1,4 @@
-import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
+import type { BaselineRecorder, BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
 import { type StaleExemption } from './test-stale-exempt.js';
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
@@ -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.
@@ -97,6 +135,15 @@ export interface CoverageRefusalDetail {
     changedInputs?: Readonly<Record<string, readonly string[]>>;
     /** The record carries a full build's anchor forward for unchanged paths. */
     carriesFullAnchor?: boolean;
+    /**
+     * Who wrote the record and when, so a run whose coverage a peer's scoped
+     * build replaced can tell whose build that was.
+     */
+    recordedBy?: string | undefined;
+    builtAt?: string | undefined;
+    recorder?: BaselineRecorder | undefined;
+    /** Whether the recorder's process is still running (it may still be using the packaging). */
+    recorderAlive?: boolean | undefined;
 }
 /**
  * Formats the refusal shown when a non-`--build` run requests paths the

package/dist/src/core/test-stale-check.js

@@ -22,6 +22,8 @@
  * legitimately have a fresh `dist/` with no FireForge-recorded baseline
  * update.
  */
+import { stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
@@ -30,6 +32,8 @@ import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
 import { isTestManifestPath } from './coverage-records.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
+import { readLinkedAt } from './launchable-build.js';
+import { isCompiledSourcePath } from './negative-control-compiled.js';
 import { formatStaleExemptions, partitionStaleCandidates, } from './test-stale-exempt.js';
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
@@ -91,6 +95,83 @@ export function formatStaleBuildWarning(result) {
         '"fireforge build --ui") first. Passing --build skips this check.' +
         exemptLine);
 }
+/**
+ * Path segments whose compiled sources never reach the binary under test
+ * (gtests, cppunittests, CI config YAML): an edit there must not make the
+ * browser read as stale.
+ */
+const NON_RUNTIME_SEGMENTS = new Set(['test', 'tests', 'gtest', 'testing', 'taskcluster']);
+/**
+ * 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 async function findCompiledSourcesNewerThanBinary(engineDir, baseline, launchablePath) {
+    if (launchablePath === undefined)
+        return undefined;
+    const linked = await readLinkedAt(engineDir, launchablePath);
+    if (linked === undefined)
+        return undefined;
+    const changed = await collectChangedEnginePaths(engineDir, baseline, 'Stale-compiled preflight');
+    const candidates = changed.filter((path) => isCompiledSourcePath(path) &&
+        !path.split('/').some((segment) => NON_RUNTIME_SEGMENTS.has(segment)));
+    const paths = [];
+    for (const path of candidates) {
+        try {
+            const { mtimeMs } = await stat(join(engineDir, path));
+            if (mtimeMs > linked.mtimeMs)
+                paths.push(path);
+        }
+        catch {
+            // A deleted source cannot be newer than anything; the build that
+            // drops it is the stale-build check's business.
+        }
+    }
+    return {
+        paths: paths.sort(),
+        linkedPath: relative(engineDir, linked.path),
+        linkedAt: new Date(linked.mtimeMs),
+    };
+}
+/**
+ * The `stale-compiled` refusal (or, under `--allow-stale-build`, warning).
+ *
+ * @param result - A non-empty {@link StaleCompiledResult}
+ */
+export function formatStaleCompiledRefusal(result) {
+    const head = result.paths.slice(0, STALE_PATHS_LIMIT).map((path) => `engine/${path}`);
+    const truncated = result.paths.length - head.length;
+    const list = head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    return (`Compiled sources changed after the binary under test was linked ` +
+        `(engine/${result.linkedPath}, ${result.linkedAt.toISOString()}): ${list}.\n` +
+        'The run would test the binary from before those edits, so a red reads as a failed fix ' +
+        'and a green proves nothing about them. Run "fireforge build" first, or rerun with ' +
+        '"fireforge test --build", which escalates to a full mach build when compiled sources ' +
+        'changed. --allow-stale-build turns this refusal into a warning.');
+}
+/**
+ * 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 function formatStaleCompiledBuildNotice(result) {
+    const head = result.paths.slice(0, STALE_PATHS_LIMIT).map((path) => `engine/${path}`);
+    const truncated = result.paths.length - head.length;
+    return (`Compiled sources changed after the binary was linked (${head.join(', ')}` +
+        `${truncated > 0 ? `, … (+${truncated} more)` : ''}); escalating this pre-test build to a ` +
+        'full mach build, since mach build faster compiles nothing.');
+}
 /**
  * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
  * request (no paths) is checked against a scoped coverage record.
@@ -163,6 +244,20 @@ export async function findChangedTestManifestsForPaths(engineDir, baseline, unco
     });
     return hits.slice(0, STALE_PATHS_LIMIT);
 }
+/** The refusal's sentence naming who wrote the coverage record. */
+function formatCoverageHolder(detail) {
+    if (detail.recorder === undefined && detail.recordedBy === undefined)
+        return '';
+    const what = detail.recordedBy !== undefined ? `"${detail.recordedBy}"` : 'a build';
+    const when = detail.builtAt !== undefined ? ` at ${detail.builtAt}` : '';
+    const recorder = detail.recorder;
+    const who = recorder === undefined
+        ? ''
+        : ` (pid ${recorder.pid}${detail.recorderAlive === true ? ', still running' : ''}` +
+            (recorder.sessionId !== undefined ? `, session ${recorder.sessionId}` : '') +
+            `, invocation ${recorder.invocationId})`;
+    return ` The current record was written by ${what}${when}${who}.`;
+}
 /**
  * Formats the refusal shown when a non-`--build` run requests paths the
  * packaged runtime's scoped `test --build` coverage does not include. It is
@@ -186,7 +281,7 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     };
     const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
     // Per-path retention is the default, so rebuilding only the uncovered
-    // paths no longer costs anyone else's claim. Saying so is what keeps a
+    // paths costs no one else's claim. Saying so is what keeps a
     // peer from rebuilding everything "to be safe".
     const keepHint = rebuildTargets.length > 0
         ? ' That scoped build keeps every other recorded path whose own staging inputs (manifest directory and the fixtures its manifest names) and engine/mozconfig are unchanged.'
@@ -210,7 +305,7 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${scope}.\n` +
         `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
         'fixtures for those manifests may be missing from obj-*/_tests/, and the run can hang ' +
-        `rather than fail.${affectedLine}${manifestLine} ${rebuildHint} ` +
+        `rather than fail.${formatCoverageHolder(detail)}${affectedLine}${manifestLine} ${rebuildHint} ` +
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
 /**

package/dist/src/core/test-stall-triage.js

@@ -37,9 +37,8 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  *  - (4) is mechanical and was root-caused downstream: the harness serves
  *    its manifest from `server.js` on 8888, and a survivor of an
  *    interrupted run keeps the port. Its probe is exact, and the preflight
- *    in `mochitest-server-port.ts` now refuses it before a run starts.
- *  - (3) is now mechanical and root-caused, replacing the correlation an
- *    earlier revision recorded. A `chrome://` (or `resource://`) URL that
+ *    in `mochitest-server-port.ts` refuses it before a run starts.
+ *  - (3) is mechanical and root-caused. A `chrome://` (or `resource://`) URL that
  *    resolves to nothing reaches `CheckForBrokenChromeURL`
  *    (netwerk/base/nsNetUtil.cpp), which outside automation only
  *    `printf_stderr`s `Missing chrome or resource URL: <uri>`, but under
@@ -47,9 +46,8 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  *    `MOZ_CRASH_UNSAFE_PRINTF("Missing chrome or resource URLs: %s")`. A
  *    downstream reproduction symbolicated the faulting frame as
  *    `CheckForBrokenChromeURL`, which is the established diagnosis the bar
- *    in `mach-error-hints.ts` asks for. The discredited "stalls first
- *    paint" story an even earlier revision asserted must not come back: a
- *    failed image load in Gecko fires `error` and does not gate the
+ *    in `mach-error-hints.ts` asks for. It is not a "stalls first paint"
+ *    problem: a failed image load in Gecko fires `error` and does not gate the
  *    document load event.
  *
  * Detection by log line is not specified for (3), because of the mechanism
@@ -62,7 +60,7 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  * the census points at the two artefacts that do carry it: the OS crash
  * report (whose faulting frame names `CheckForBrokenChromeURL`) and the
  * out-of-automation smoke probe (which prints the non-crashing spelling
- * and, since 0.45.0, counts it as an unallowed error so the exit code
+ * and counts it as an unallowed error so the exit code
  * agrees with the capture).
  */
 const NO_OUTPUT_STALL_TRIAGE = [

package/dist/src/core/token-category.js

@@ -18,8 +18,8 @@ import { escapeRegex } from '../utils/regex.js';
  * Body of the first `/* … *\/` comment on `line`, or `undefined` when the
  * line carries no closed block comment.
  *
- * This uses index arithmetic rather than a regex: every regex spelling of
- * "banner comment" this module used to carry was super-linear on a line that
+ * This uses index arithmetic rather than a regex: the natural regex
+ * spellings of "banner comment" are super-linear on a line that
  * repeats the opening shape (CodeQL `js/polynomial-redos`), and `tokens.css`
  * is a file FireForge reads out of a consumer's engine tree, so a
  * pathological line needs no attacker to arrive.

package/dist/src/core/token-inventory.js

@@ -4,9 +4,9 @@
  * tokens each declares, and what a single token resolves to in every theme
  * block that mentions it.
  *
- * `token add` requires `--category` and, until now, nothing reported the
- * categories a project actually has, so the only way to name one correctly
- * was to hand-parse a neighbouring `= Category =` banner out of the file.
+ * `token add` requires `--category`, so it needs a report of the categories
+ * a project actually has; without one, the only way to name one correctly
+ * is to hand-parse a neighbouring `= Category =` banner out of the file.
  * This module is that report. It reuses the banner and
  * category-region model from `token-category.ts` rather than parsing
  * tokens CSS a second way: two readers that disagree on what a banner is

package/dist/src/core/token-manager.d.ts

@@ -4,7 +4,7 @@ import { type TokenDeclarationLocation } from './token-category.js';
  *
  * Derived from {@link TOKEN_MODES} so the runtime allowlist and the type
  * cannot drift: adding a member here without updating the list (or the
- * reverse) is no longer possible, because there is only one list.
+ * reverse) is impossible, because there is only one list.
  */
 export declare const TOKEN_MODES: readonly ["auto", "static", "override"];
 /** Dark mode behaviour for a token. */
@@ -21,7 +21,7 @@ export interface AddTokenOptions {
     value: string;
     /**
      * Token category matching section headers in the CSS file. Required for a
-     * base declaration. Ignored, and no longer required, under
+     * base declaration. Ignored, and not required, under
      * {@link AddTokenOptions.variant}, which routes into a `:root<selector>`
      * block and never touches a category section.
      */