@hominis/fireforge 0.44.4 → 0.46.0

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

@@ -20,7 +20,7 @@
  * smoke run into noise for operators and every CI run into flake.
  */
 import { toError } from '../utils/errors.js';
-export const SMOKE_ERROR_PATTERNS = [
+const SMOKE_ERROR_PATTERNS = [
     // Firefox chrome error lines — `JavaScript error: chrome://…, line N: TypeError: …`.
     /^\s*JavaScript error:/i,
     // Some log paths prefix browser-console `console.error(...)` with the literal label below.
@@ -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
@@ -51,12 +63,7 @@ export function matchesSmokeError(line) {
  * allowlist (always returns -1).
  */
 export function matchAllowlist(line, allow) {
-    for (let i = 0; i < allow.length; i++) {
-        if (allow[i]?.pattern.test(line)) {
-            return i;
-        }
-    }
-    return -1;
+    return allow.findIndex((entry) => entry.pattern.test(line));
 }
 /**
  * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
@@ -76,12 +83,12 @@ export function compileAllowlistFromFile(body, sourcePath) {
             compiled.push({
                 pattern: new RegExp(line),
                 source: line,
-                origin: `${sourcePath}:${String(index + 1)}`,
+                origin: `${sourcePath}:${index + 1}`,
             });
         }
         catch (error) {
             const message = toError(error).message;
-            throw new Error(`Invalid allowlist regex at ${sourcePath}:${String(index + 1)}: ${message}`, {
+            throw new Error(`Invalid allowlist regex at ${sourcePath}:${index + 1}: ${message}`, {
                 cause: error,
             });
         }
@@ -99,12 +106,12 @@ export function compileAllowlistFromStrings(sources) {
             compiled.push({
                 pattern: new RegExp(source),
                 source,
-                origin: `--console-allow #${String(index + 1)}`,
+                origin: `--console-allow #${index + 1}`,
             });
         }
         catch (error) {
             const message = toError(error).message;
-            throw new Error(`Invalid --console-allow regex at position ${String(index + 1)} ("${source}"): ${message}`, { cause: error });
+            throw new Error(`Invalid --console-allow regex at position ${index + 1} ("${source}"): ${message}`, { cause: error });
         }
     });
     return compiled;

package/dist/src/core/state-file.d.ts

@@ -1,5 +1,16 @@
 /** Runs an operation while holding the sidecar lock for a FireForge state file. */
 export declare function withStateFileLock<T>(statePath: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
+ *
+ * Colons are not portable in filenames (Windows rejects them outright), so
+ * the ISO form is punctuated with dashes only. Lexical order still equals
+ * chronological order, which is what run-log pruning relies on.
+ *
+ * @param now - Instant to render
+ * @returns The ISO-8601 form with `:` and `.` replaced by `-`
+ */
+export declare function fileSafeTimestamp(now: Date): string;
 /** Renames a state file out of the way while preserving it for later inspection. */
 export declare function quarantineStateFile(statePath: string, reason?: string): Promise<string | undefined>;
 /**
@@ -15,7 +26,7 @@ export declare function quarantineStateFile(statePath: string, reason?: string):
  * inside that tree.
  *
  * `furnace.json` is the pattern the rest should follow: it refuses a newer
- * version by name and tells the operator to upgrade (`migrateFurnaceConfig`
+ * version by name and tells the operator to upgrade (`validateConfigVersion`
  * in `furnace-config.ts`).
  */
 export type DocumentVersionCheck = {

package/dist/src/core/state-file.js

@@ -12,12 +12,25 @@ export async function withStateFileLock(statePath, operation) {
             `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
     });
 }
+/**
+ * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
+ *
+ * Colons are not portable in filenames (Windows rejects them outright), so
+ * the ISO form is punctuated with dashes only. Lexical order still equals
+ * chronological order, which is what run-log pruning relies on.
+ *
+ * @param now - Instant to render
+ * @returns The ISO-8601 form with `:` and `.` replaced by `-`
+ */
+export function fileSafeTimestamp(now) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
 /** Renames a state file out of the way while preserving it for later inspection. */
 export async function quarantineStateFile(statePath, reason = 'corrupt') {
     if (!(await pathExists(statePath))) {
         return undefined;
     }
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const timestamp = fileSafeTimestamp(new Date());
     const quarantinedPath = `${statePath}.${reason}-${timestamp}`;
     await rename(statePath, quarantinedPath);
     return basename(quarantinedPath);

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

@@ -11,6 +11,7 @@ import { mapWithConcurrency } from '../utils/concurrency.js';
 import { toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { isBrandingManagedPath } from './branding.js';
 import { createPatchedContentContext } from './patch-apply.js';
 import { classifyBinaryOwnedFile } from './status-binary.js';
@@ -56,7 +57,7 @@ export function getPrimaryStatusCode(status) {
  * visible as unmanaged (the Assets.car precedent).
  */
 export function isGeneratedBrandingPath(file, binaryName) {
-    const normalized = file.replace(/\\/g, '/');
+    const normalized = normalizePathSlashes(file);
     const brandingRoot = `browser/branding/${binaryName}`;
     return (normalized === 'browser/moz.configure' ||
         normalized === `${brandingRoot}/configure.sh` ||

package/dist/src/core/test-changed-prefs.js

@@ -46,6 +46,30 @@ const CHANGED_PREF_BLOCK_PATTERN = /pref(?:erence)?s?\b/i;
  * @returns Operator-facing explanation, or undefined
  */
 export function describeChangedPrefNoise(output) {
+    const namesSeen = matchedTimeDrivenPrefNames(output);
+    if (namesSeen === undefined)
+        return undefined;
+    return (`Every unexpected result in this run is a changed-preference check on ${[...namesSeen].join(' / ')}. ` +
+        'Those preferences are TIME-DRIVEN: they move once a run is long enough to cross the ' +
+        'cold-startup check interval, so they correlate with run LENGTH rather than with the ' +
+        'change under test or with the build. The first probe is to halve the chunk size ' +
+        '(`--chunk 8` where a 40-row chunk tripped it) and see whether the same work passes; ' +
+        'if it does, this was harness noise, not a regression. FireForge cannot forgive the ' +
+        'check — it belongs to the harness — only tell you which kind of failure you are ' +
+        'looking at.');
+}
+/** Failure blocks inspected before the changed-pref shape is abandoned. */
+const CHANGED_PREF_BLOCK_LIMIT = 20;
+/**
+ * The RECOGNIZER half of the shape, split from the formatting so a caller
+ * that only needs the yes/no answer does not build the ~500-character
+ * explanation to throw it away.
+ *
+ * @param output - Combined harness stdout+stderr
+ * @returns The time-driven pref names seen, or undefined when the shape does
+ *   not apply
+ */
+function matchedTimeDrivenPrefNames(output) {
     const blocks = collectUnexpectedFailureBlocks(output, CHANGED_PREF_BLOCK_LIMIT).filter((block) => !block.startsWith('…'));
     if (blocks.length === 0)
         return undefined;
@@ -59,20 +83,11 @@ export function describeChangedPrefNoise(output) {
         for (const name of matched)
             namesSeen.add(name);
     }
-    return (`Every unexpected result in this run is a changed-preference check on ${[...namesSeen].join(' / ')}. ` +
-        'Those preferences are TIME-DRIVEN: they move once a run is long enough to cross the ' +
-        'cold-startup check interval, so they correlate with run LENGTH rather than with the ' +
-        'change under test or with the build. The first probe is to halve the chunk size ' +
-        '(`--chunk 8` where a 40-row chunk tripped it) and see whether the same work passes; ' +
-        'if it does, this was harness noise, not a regression. FireForge cannot forgive the ' +
-        'check — it belongs to the harness — only tell you which kind of failure you are ' +
-        'looking at.');
+    return namesSeen;
 }
-/** Failure blocks inspected before the changed-pref shape is abandoned. */
-const CHANGED_PREF_BLOCK_LIMIT = 20;
 /** Short verdict-line note for the changed-preference-noise shape. */
 export function changedPrefNoiseVerdictNote(output) {
-    return describeChangedPrefNoise(output) === undefined
+    return matchedTimeDrivenPrefNames(output) === undefined
         ? undefined
         : 'all unexpected results are time-driven changed-pref checks';
 }

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=${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(`${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

@@ -1,6 +1,4 @@
-import { isXpcomManifestPath } from './build-audit.js';
 import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
-export { isXpcomManifestPath };
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */
@@ -66,13 +64,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

@@ -24,11 +24,11 @@
  */
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
-export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
 /**
@@ -138,7 +138,7 @@ function toManifestGranule(path) {
 }
 /** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
 function normalizeCoveragePath(path) {
-    return path.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+    return normalizePathSlashes(path.trim()).replace(/\/+$/, '');
 }
 /**
  * Formats the refusal shown when a non-`--build` run requests paths the
@@ -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.)');
 }
 /**