@hominis/fireforge 0.44.4 → 0.45.0

package/dist/src/core/patch-lint.js

@@ -8,11 +8,13 @@ import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
 import { lintPatchedCss } from './patch-lint-css.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
+import { formatFileTooLargeMessage, resolveFileSizeThresholds } from './patch-lint-file-size.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
 import { lintMozBuildSortedLists } from './patch-lint-mozbuild.js';
 import { lintObserverTopics } from './patch-lint-observer.js';
 import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from './patch-lint-ownership.js';
+import { invokePatchLintPrettier } from './patch-lint-prettier.js';
 // ---------------------------------------------------------------------------
 // Cross-patch lint re-exports
 // ---------------------------------------------------------------------------
@@ -31,10 +33,6 @@ export { lintPatchedCss };
 // Helpers
 // ---------------------------------------------------------------------------
 const JS_EXTENSIONS = ['.js', '.mjs', '.jsm'];
-const FILE_SIZE_THRESHOLDS = {
-    general: { notice: 500, warning: 750, error: 900 },
-    test: { notice: 1200, warning: 1400, error: 1600 },
-};
 /**
  * Counts the lines of `content` the way `wc -l` reports them: a trailing
  * newline terminates the last line rather than starting an empty extra one.
@@ -407,31 +405,22 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
         if (isNew) {
             const lineCount = countContentLines(content);
             const isTest = isTestFile(file);
-            const thresholds = isTest ? FILE_SIZE_THRESHOLDS.test : FILE_SIZE_THRESHOLDS.general;
+            const thresholds = resolveFileSizeThresholds(config.patchLint?.fileSizeThresholds, isTest);
             const label = isTest ? 'Test file' : 'New file';
             const verb = isTest ? 'splitting' : 'decomposing';
-            if (lineCount > thresholds.error) {
-                issues.push({
-                    file,
-                    check: 'file-too-large',
-                    message: `${label} has ${lineCount} lines (hard limit: ${thresholds.error}). Consider ${verb}.`,
-                    severity: 'error',
-                });
-            }
-            else if (lineCount > thresholds.warning) {
+            const band = lineCount > thresholds.error
+                ? 'error'
+                : lineCount > thresholds.warning
+                    ? 'warning'
+                    : lineCount > thresholds.notice
+                        ? 'notice'
+                        : undefined;
+            if (band !== undefined) {
                 issues.push({
                     file,
                     check: 'file-too-large',
-                    message: `${label} has ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider ${verb}.`,
-                    severity: 'warning',
-                });
-            }
-            else if (lineCount > thresholds.notice) {
-                issues.push({
-                    file,
-                    check: 'file-too-large',
-                    message: `${label} has ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider ${verb}.`,
-                    severity: 'notice',
+                    message: formatFileTooLargeMessage({ label, lineCount, thresholds, band, verb }),
+                    severity: band,
                 });
             }
         }
@@ -715,6 +704,16 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
             }
         }
     }
+    // Prettier over patch-owned .sys.mjs. Deliberately NOT part of the
+    // precomputedCheckJs short-circuit: it is a separate tool with its own
+    // gate, and a queue-wide program has no equivalent to share. Scoped to
+    // the files THIS patch owns, run from engine/ so the engine's own config
+    // and ignore file decide (see `patch-lint-prettier.ts`).
+    const prettierGate = config.patchLint?.prettier ?? 'off';
+    if (prettierGate !== 'off' && patchOwnedFiles.size > 0) {
+        const scoped = [...patchOwnedFiles].filter((file) => !options?.checkJsReportScope || options.checkJsReportScope.has(file));
+        issues.push(...(await invokePatchLintPrettier(repoDir, dirname(repoDir), scoped.sort(), prettierGate)));
+    }
     // Filter out ignored checks last so every rule still runs (keeps the
     // implementation uniform) but suppressed rules do not surface. We do not
     // reclassify severities — an ignored error simply drops, mirroring how

package/dist/src/core/patch-transform.d.ts

@@ -18,6 +18,27 @@
  *   binary new-file conflicts as unresolvable rather than auto-resolving.
  */
 export declare function extractNewFileContentFromDiff(diff: string, targetFile?: string): string;
+/**
+ * Projects every TEXT new file a diff creates into a path → content map, for
+ * the cross-patch lint projections that build a synthetic patch-queue entry.
+ *
+ * Binary new files are SKIPPED rather than refused. The map feeds only the
+ * forward-import rule, which scans content for import statements — a binary
+ * blob authors none, so omitting it contributes exactly what including it
+ * would. Refusing instead (which is what
+ * {@link extractNewFileContentFromDiff} correctly does for a caller that
+ * named ONE file) made vendoring a new binary impossible: every projection
+ * site fed it every detected new file, so `export --order`, `re-export
+ * --scan --scan-file`, `patch move-files-into` and `patch split` all died on
+ * a file the export half had just written a valid `GIT binary patch` for.
+ * Nothing is lost by skipping: binary bodies are covered independently by the
+ * `binary-body-not-reconstructable` queue lint, and
+ * `buildPatchQueueContext` already tolerates them for real queue entries.
+ *
+ * One parse for the whole diff, rather than one per new file as the five
+ * call sites previously did.
+ */
+export declare function buildNewFileTextProjection(diff: string): Map<string, string>;
 /**
  * Extracts the complete file content from a "new file" patch.
  * When targetFile is provided, only extracts content for that file

package/dist/src/core/patch-transform.js

@@ -27,6 +27,15 @@ export function extractNewFileContentFromDiff(diff, targetFile) {
     if (binary) {
         throw new PatchError(`Cannot extract text content from binary patch section for ${binary.targetPath}`, binary.targetPath);
     }
+    return contentFromSections(sections);
+}
+/**
+ * Walks the added (`+`) lines of already-parsed sections into file content.
+ * Shared by {@link extractNewFileContentFromDiff} and
+ * {@link buildNewFileTextProjection} so the two cannot drift on the empty-file
+ * and no-trailing-newline cases below.
+ */
+function contentFromSections(sections) {
     // An empty new file is a legitimate git diff: `new file mode` with no
     // hunks at all. It must extract as '' — the historical line-walker
     // returned '\n' for it, creating a one-byte file that failed checksum
@@ -51,6 +60,35 @@ export function extractNewFileContentFromDiff(diff, targetFile) {
     const result = contentLines.join('\n');
     return hasNoNewlineMarker ? result : result + '\n';
 }
+/**
+ * Projects every TEXT new file a diff creates into a path → content map, for
+ * the cross-patch lint projections that build a synthetic patch-queue entry.
+ *
+ * Binary new files are SKIPPED rather than refused. The map feeds only the
+ * forward-import rule, which scans content for import statements — a binary
+ * blob authors none, so omitting it contributes exactly what including it
+ * would. Refusing instead (which is what
+ * {@link extractNewFileContentFromDiff} correctly does for a caller that
+ * named ONE file) made vendoring a new binary impossible: every projection
+ * site fed it every detected new file, so `export --order`, `re-export
+ * --scan --scan-file`, `patch move-files-into` and `patch split` all died on
+ * a file the export half had just written a valid `GIT binary patch` for.
+ * Nothing is lost by skipping: binary bodies are covered independently by the
+ * `binary-body-not-reconstructable` queue lint, and
+ * `buildPatchQueueContext` already tolerates them for real queue entries.
+ *
+ * One parse for the whole diff, rather than one per new file as the five
+ * call sites previously did.
+ */
+export function buildNewFileTextProjection(diff) {
+    const newFiles = new Map();
+    for (const section of parseDiffSections(diff)) {
+        if (!section.isNewFile || section.isBinary)
+            continue;
+        newFiles.set(section.targetPath, contentFromSections([section]));
+    }
+    return newFiles;
+}
 /**
  * Extracts the complete file content from a "new file" patch.
  * When targetFile is provided, only extracts content for that file

package/dist/src/core/smoke-patterns.js

@@ -29,6 +29,18 @@ export const SMOKE_ERROR_PATTERNS = [
     /^\s*\[JavaScript (Error|Warning)\]/i,
     // IPC-layer fatal assertions — Firefox prints `###!!! [Parent] Error: …` on content-process crashes.
     /^\s*###!!! \[Parent\]/,
+    // A chrome:// or resource:// URL that resolves to nothing. Outside
+    // automation Gecko only PRINTS this (printf_stderr in
+    // `CheckForBrokenChromeURL`, netwerk/base/nsNetUtil.cpp); under
+    // `xpc::IsInAutomation()` the same condition is a
+    // `MOZ_CRASH_UNSAFE_PRINTF` in whichever process opened the channel. So
+    // the smoke probe — which runs OUTSIDE automation — sees the printed
+    // line for the same defect that hard-crashes every harness run, and a
+    // probe that exits 0 on it reports "startup is healthy" for a build that
+    // hangs at "Waiting for browser…". Both spellings are matched: the
+    // non-automation singular `URL:` and the automation plural `URLs:`.
+    // Allowlistable through `--console-allow` like any other pattern.
+    /^\s*Missing chrome or resource URLs?:/,
 ];
 /**
  * Returns `true` when `line` matches any pattern in

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

@@ -23,6 +23,7 @@
  * reporting phantom test failures (or phantom passes).
  */
 import { hasKnownTeardownNoise } from './mach-known-noise-filter.js';
+import { truncateEvidence, unmarkedFailureEvidenceNote, } from './test-harness-verdict-notes.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.
@@ -487,12 +488,22 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     // shutdown-re-entry shape, or a requested file that never started keeps
     // the run failing. Only the missing shutdown marker is forgiven, and only
     // when the recognized teardown traceback explains it.
-    if (isGreenSuiteEndedByKnownTeardownNoise(output, counts, realFailures, requestedPaths)) {
+    const teardownOverride = evaluateGreenTeardownOverride(output, counts, realFailures, requestedPaths);
+    if (teardownOverride.accepted) {
         return { kind: 'tests-ran-ok', note: 'harness teardown noise ignored', ...counts };
     }
+    // A run that carried the recognized teardown noise and still failed says
+    // WHICH condition rejected the override, on the one greppable line.
+    const teardownNote = teardownOverride.rejectedBy !== undefined
+        ? `green-teardown override rejected: ${teardownOverride.rejectedBy}`
+        : undefined;
+    const withNotes = (verdict, extra) => {
+        const notes = [teardownNote, extra].filter((n) => n !== undefined);
+        return notes.length > 0 ? { ...verdict, note: notes.join('; ') } : verdict;
+    };
     const signature = detectHarnessCrashSignature(output);
     if (signature) {
-        return { kind: 'harness-crash', signature, ...counts };
+        return withNotes({ kind: 'harness-crash', signature, ...counts });
     }
     const ranTests = hasExecutionSignal(output);
     if (!ranTests && requestedPaths.length > 0) {
@@ -518,7 +529,7 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
         if (crashLine !== undefined ||
             completeness.neverStarted.length > 0 ||
             completeness.neverEnded.length > 0) {
-            return {
+            return withNotes({
                 kind: 'test-failures',
                 ...counts,
                 ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
@@ -529,43 +540,18 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
                     neverStarted: completeness.neverStarted,
                     neverEnded: completeness.neverEnded,
                 },
-            };
+            });
         }
         return { kind: 'tests-ran-ok', greenSummaryOverride: true, ...counts };
     }
     const wordMatchNote = unmarkedFailureEvidenceNote(counts, realFailures);
-    return {
+    return withNotes({
         kind: 'test-failures',
         ...counts,
         ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
         ...(failureBlocks.length > 0 ? { realFailureBlocks: failureBlocks } : {}),
         ...(secondaryHarnessSignature !== undefined ? { secondaryHarnessSignature } : {}),
-        ...(wordMatchNote !== undefined ? { note: wordMatchNote } : {}),
-    };
-}
-/**
- * Belt for the residual case the tightened {@link FAIL_LINE_PATTERN} /
- * {@link ASSERTION_LINE_PATTERN} cannot reach: the summary reported
- * `Unexpected results: 0`, yet the run is still classified `test-failures`
- * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
- *
- * `unexpected=0` printed beside `reason=test-failures` is the tell that the
- * verdict rests on pattern matching rather than on a harness result, and a
- * reader who cannot see that spends hours attributing a red run to the
- * change under test. The note says so on the verdict line itself.
- *
- * Deliberately a NOTE and not a reclassification: a non-zero exit with no
- * green-shaped summary is still a failing run, and inventing a new `reason`
- * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
- */
-function unmarkedFailureEvidenceNote(counts, realFailures) {
-    if (counts.unexpected !== 0)
-        return undefined;
-    if (realFailures.length === 0)
-        return undefined;
-    if (realFailures.some((line) => UNEXPECTED_LINE_SINGLE.test(line)))
-        return undefined;
-    return 'summary reported 0 unexpected; no TEST-UNEXPECTED marker in the matched evidence';
+    }, wordMatchNote);
 }
 /**
  * True when the capture shows a substantively GREEN suite whose only
@@ -577,29 +563,56 @@ function unmarkedFailureEvidenceNote(counts, realFailures) {
  * unexpected count anywhere; no real `TEST-UNEXPECTED-*`/assertion line;
  * no crash marker; every requested test file both started and ended; and
  * the recognized teardown traceback is present. Anything short of that
- * falls through to the normal (failing) chain.
+ * falls through to the normal (failing) chain — with the failing condition
+ * NAMED, so the next occurrence is a filed bug rather than another
+ * undiagnosable re-run.
+ *
+ * The conditions are evaluated in a fixed order and the FIRST failing one
+ * is reported; a run can violate several, and reporting one deterministic
+ * condition beats an unordered list of everything that happened to be true.
  */
-function isGreenSuiteEndedByKnownTeardownNoise(output, counts, realFailures, requestedPaths) {
+function evaluateGreenTeardownOverride(output, counts, realFailures, requestedPaths) {
     if (!hasKnownTeardownNoise(output))
-        return false;
+        return { accepted: false };
+    const reject = (rejectedBy) => ({ accepted: false, rejectedBy });
     if (!hasExecutionSignal(output))
-        return false;
-    if (counts.checks === undefined || counts.unexpected !== 0)
-        return false;
-    if (!GREEN_UNEXPECTED_SUMMARY_PATTERN.test(output))
-        return false;
-    if (NONZERO_UNEXPECTED_SUMMARY_PATTERN.test(output))
-        return false;
-    if (realFailures.length > 0)
-        return false;
-    if (findCrashMarkerLine(output) !== undefined)
-        return false;
+        return reject('no execution signal (no TEST-START/TEST_START)');
+    if (counts.checks === undefined)
+        return reject('summary printed no "Ran N checks" line');
+    // `counts.unexpected === 0` IS the explicit-`Unexpected results: 0` test
+    // the previous revision spelled a second time with
+    // GREEN_UNEXPECTED_SUMMARY_PATTERN: the count is parsed from the same
+    // line and an absent line leaves it undefined. The two are kept apart in
+    // the message because "printed no such line" and "printed a non-zero one"
+    // are different findings for the reader.
+    if (counts.unexpected === undefined) {
+        return reject('summary printed no "Unexpected results:" line');
+    }
+    if (counts.unexpected !== 0) {
+        return reject(`summary reported unexpected=${String(counts.unexpected)}`);
+    }
+    if (NONZERO_UNEXPECTED_SUMMARY_PATTERN.test(output)) {
+        return reject('a non-zero "Unexpected results:" line is present somewhere in the output');
+    }
+    if (realFailures.length > 0) {
+        return reject(`${String(realFailures.length)} matched failure line(s), first: ${truncateEvidence(realFailures[0] ?? '')}`);
+    }
+    const crashLine = findCrashMarkerLine(output);
+    if (crashLine !== undefined)
+        return reject(`crash marker present: ${truncateEvidence(crashLine)}`);
     // The post-green shutdown re-entry shape is deliberately a crash verdict
     // on an otherwise-green log; it must not be swept up here.
-    if (SHUTDOWN_REENTRY_PATTERN.test(output))
-        return false;
+    if (SHUTDOWN_REENTRY_PATTERN.test(output)) {
+        return reject('post-green shutdown re-entry shape present');
+    }
     const completeness = analyzeTestCompleteness(output, requestedPaths);
-    return completeness.neverStarted.length === 0 && completeness.neverEnded.length === 0;
+    if (completeness.neverStarted.length > 0) {
+        return reject(`requested file(s) never started: ${completeness.neverStarted.join(', ')}`);
+    }
+    if (completeness.neverEnded.length > 0) {
+        return reject(`requested file(s) never ended: ${completeness.neverEnded.join(', ')}`);
+    }
+    return { accepted: true };
 }
 /**
  * Parses the numeric counts from the harness's embedded result summary

package/dist/src/core/test-harness-verdict-notes.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Verdict-note helpers for the harness classifier.
+ *
+ * Split out of `test-harness-crash.ts` (at its per-file line budget). These
+ * decide the ADVISORY parenthetical on the `FIREFORGE-VERDICT:` line; none
+ * of them changes a status or a reason key, which the verdict contract's
+ * consumers parse.
+ */
+/**
+ * The only part of the classifier's summary counts these notes read.
+ * Structural rather than an import of `HarnessSummaryCounts`: a type edge
+ * back into `test-harness-crash.ts` is still an edge, and the cycle gate
+ * rejects it.
+ */
+interface SummaryCountsView {
+    unexpected?: number;
+}
+/**
+ * Belt for the residual case the tightened {@link FAIL_LINE_PATTERN} /
+ * {@link ASSERTION_LINE_PATTERN} cannot reach: the summary reported
+ * `Unexpected results: 0`, yet the run is still classified `test-failures`
+ * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
+ *
+ * `unexpected=0` printed beside `reason=test-failures` is the tell that the
+ * verdict rests on pattern matching rather than on a harness result, and a
+ * reader who cannot see that spends hours attributing a red run to the
+ * change under test. The note says so on the verdict line itself.
+ *
+ * Deliberately a NOTE and not a reclassification: a non-zero exit with no
+ * green-shaped summary is still a failing run, and inventing a new `reason`
+ * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
+ */
+export declare function unmarkedFailureEvidenceNote(counts: SummaryCountsView, realFailures: readonly string[]): string | undefined;
+/** Caps an evidence line so the one-line verdict note stays one line. */
+export declare function truncateEvidence(line: string): string;
+/**
+ * Outcome of the green-teardown belt.
+ *
+ * `accepted` is the pass. A rejection carries `rejectedBy` ONLY when the
+ * recognized teardown noise was present — i.e. when the belt was the thing
+ * that could have applied and did not. That distinction is the whole point
+ * of the field: a run with no teardown traceback was never a candidate and
+ * naming a "rejecting condition" for it would be noise, whereas a run that
+ * DOES carry the traceback and still fails is the shape an operator
+ * otherwise cannot diagnose from outside — every condition is
+ * all-or-nothing, so the failing verdict looks identical whichever one
+ * rejected it, and a downstream report spent a re-run and a filed-bug's
+ * worth of effort guessing between them.
+ */
+export interface GreenTeardownOverride {
+    accepted: boolean;
+    /** Which single condition rejected, when the teardown noise was present. */
+    rejectedBy?: string;
+}
+export {};

package/dist/src/core/test-harness-verdict-notes.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Verdict-note helpers for the harness classifier.
+ *
+ * Split out of `test-harness-crash.ts` (at its per-file line budget). These
+ * decide the ADVISORY parenthetical on the `FIREFORGE-VERDICT:` line; none
+ * of them changes a status or a reason key, which the verdict contract's
+ * consumers parse.
+ */
+/**
+ * A single `TEST-UNEXPECTED-*` marker. Local copy of the classifier's line
+ * pattern: importing the value would draw a runtime edge back into
+ * `test-harness-crash.ts` and make the split circular.
+ */
+const UNEXPECTED_MARKER = /TEST-UNEXPECTED-\w+/;
+/**
+ * Belt for the residual case the tightened {@link FAIL_LINE_PATTERN} /
+ * {@link ASSERTION_LINE_PATTERN} cannot reach: the summary reported
+ * `Unexpected results: 0`, yet the run is still classified `test-failures`
+ * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
+ *
+ * `unexpected=0` printed beside `reason=test-failures` is the tell that the
+ * verdict rests on pattern matching rather than on a harness result, and a
+ * reader who cannot see that spends hours attributing a red run to the
+ * change under test. The note says so on the verdict line itself.
+ *
+ * Deliberately a NOTE and not a reclassification: a non-zero exit with no
+ * green-shaped summary is still a failing run, and inventing a new `reason`
+ * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
+ */
+export function unmarkedFailureEvidenceNote(counts, realFailures) {
+    if (counts.unexpected !== 0)
+        return undefined;
+    if (realFailures.length === 0)
+        return undefined;
+    if (realFailures.some((line) => UNEXPECTED_MARKER.test(line)))
+        return undefined;
+    return 'summary reported 0 unexpected; no TEST-UNEXPECTED marker in the matched evidence';
+}
+/** Caps an evidence line so the one-line verdict note stays one line. */
+export function truncateEvidence(line) {
+    const flat = line.trim().replace(/\s+/g, ' ');
+    return flat.length <= GREEN_TEARDOWN_EVIDENCE_LIMIT
+        ? flat
+        : `${flat.slice(0, GREEN_TEARDOWN_EVIDENCE_LIMIT)}…`;
+}
+/** Character budget for an evidence excerpt inside the verdict note. */
+const GREEN_TEARDOWN_EVIDENCE_LIMIT = 80;

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

@@ -66,13 +66,30 @@ export declare const FULL_SUITE_REQUEST = "(entire suite)";
  */
 export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
 /**
- * Formats the refusal shown when a non-`--build` run requests paths the
- * packaged runtime's scoped `test --build` coverage does not include —
- * enforced on every such run, with or without `--allow-stale-build`. Kept
- * separate from the matcher so tests can pin structure and copy
- * independently (same split as {@link formatStaleBuildWarning}).
+ * Test manifests changed since the recorded build that sit in (or above)
+ * the directory of an uncovered request path — i.e. the manifests that
+ * EXPLAIN why this run needs coverage the build never claimed.
+ *
+ * Best-effort: a probe failure returns an empty list, so the refusal
+ * degrades to exactly its previous text rather than failing differently.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param baseline - Last successful build's baseline
+ * @param uncovered - Uncovered request paths from
+ *   {@link findUncoveredRequestPaths}
+ * @returns Engine-relative manifest paths, capped at
+ *   {@link STALE_PATHS_LIMIT}
+ */
+export declare function findChangedTestManifestsForPaths(engineDir: string, baseline: BuildBaseline | undefined, uncovered: readonly string[]): Promise<string[]>;
+/**
+ * @param uncovered - Request paths the recorded packaging does not cover
+ * @param coverage - The recorded scoped coverage claim
+ * @param changedManifests - Test manifests changed since the recorded
+ *   build that explain an uncovered path (from
+ *   {@link findChangedTestManifestsForPaths}); omitted or empty renders
+ *   nothing
  */
-export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[]): string;
+export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[], changedManifests?: readonly string[]): string;
 /** Result of the compiled-StaticComponents staleness probe. */
 export interface StaticComponentsStaleResult {
     /** True when at least one `components.conf` genuinely diverged from the anchor. */

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

@@ -147,7 +147,74 @@ function normalizeCoveragePath(path) {
  * separate from the matcher so tests can pin structure and copy
  * independently (same split as {@link formatStaleBuildWarning}).
  */
-export function formatTestCoverageRefusal(uncovered, coverage) {
+/**
+ * Basenames of the test manifests whose entries decide what a packaged test
+ * runtime stages. A manifest that gained an entry is the single most common
+ * reason a run needs coverage the last build never claimed — and it is a
+ * fact FireForge already holds but never said, leaving the operator to
+ * rediscover it after a correct refusal.
+ */
+const TEST_MANIFEST_BASENAMES = new Set([
+    'xpcshell.toml',
+    'xpcshell.ini',
+    'browser.toml',
+    'browser.ini',
+    'mochitest.toml',
+    'mochitest.ini',
+    'chrome.toml',
+    'chrome.ini',
+    'a11y.toml',
+    'a11y.ini',
+]);
+/** True for a test manifest path (by basename). */
+function isTestManifestPath(path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    return TEST_MANIFEST_BASENAMES.has(base);
+}
+/**
+ * Test manifests changed since the recorded build that sit in (or above)
+ * the directory of an uncovered request path — i.e. the manifests that
+ * EXPLAIN why this run needs coverage the build never claimed.
+ *
+ * Best-effort: a probe failure returns an empty list, so the refusal
+ * degrades to exactly its previous text rather than failing differently.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param baseline - Last successful build's baseline
+ * @param uncovered - Uncovered request paths from
+ *   {@link findUncoveredRequestPaths}
+ * @returns Engine-relative manifest paths, capped at
+ *   {@link STALE_PATHS_LIMIT}
+ */
+export async function findChangedTestManifestsForPaths(engineDir, baseline, uncovered) {
+    let changed;
+    try {
+        changed = await collectChangedEnginePaths(engineDir, baseline, 'Coverage refusal');
+    }
+    catch (error) {
+        verbose(`Coverage refusal: manifest probe failed — ${toError(error).message}`);
+        return [];
+    }
+    const requestDirs = uncovered
+        .filter((p) => p !== FULL_SUITE_REQUEST)
+        .map((p) => toManifestGranule(normalizeCoveragePath(p)));
+    const hits = changed.filter((path) => {
+        if (!isTestManifestPath(path))
+            return false;
+        const dir = path.slice(0, Math.max(0, path.lastIndexOf('/')));
+        return requestDirs.some((req) => req === dir || req.startsWith(`${dir}/`));
+    });
+    return hits.slice(0, STALE_PATHS_LIMIT);
+}
+/**
+ * @param uncovered - Request paths the recorded packaging does not cover
+ * @param coverage - The recorded scoped coverage claim
+ * @param changedManifests - Test manifests changed since the recorded
+ *   build that explain an uncovered path (from
+ *   {@link findChangedTestManifestsForPaths}); omitted or empty renders
+ *   nothing
+ */
+export function formatTestCoverageRefusal(uncovered, coverage, changedManifests = []) {
     const cap = (paths) => {
         const head = paths.slice(0, STALE_PATHS_LIMIT);
         const truncated = paths.length - head.length;
@@ -166,10 +233,16 @@ export function formatTestCoverageRefusal(uncovered, coverage) {
     const rebuildHint = rebuildTargets.length > 0
         ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.${extendHint}`
         : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
+    // Why THIS run needs new coverage, when a changed manifest explains it: a
+    // manifest that gained an entry is not covered by a build claim recorded
+    // for other paths, and a browser-chrome claim never covers xpcshell.
+    const manifestLine = changedManifests.length > 0
+        ? ` This run needs coverage the recorded build never claimed because a test manifest changed since it: ${changedManifests.map((m) => `engine/${m}`).join(', ')} — a manifest that gained an entry stages new support fixtures, and a claim recorded for other paths (or another harness) does not cover them.`
+        : '';
     return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\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. ${rebuildHint} ` +
+        `rather than fail.${manifestLine} ${rebuildHint} ` +
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
 /**