@hominis/fireforge 0.44.4 → 0.45.0

package/dist/src/commands/re-export.js

@@ -11,6 +11,7 @@ import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
 import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '../utils/logger.js';
 import { loadScanFilesAssignments, withDryRunPurityGuard, withDryRunReExportLock, } from './re-export-bulk-scan.js';
+import { warnUnseenExpectedDrift } from './re-export-drift.js';
 import { reExportFilesInPlace } from './re-export-files.js';
 import { buildReExportLintContext, finishReExportLint } from './re-export-lint.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
@@ -123,6 +124,8 @@ export async function reExportCommand(projectRoot, patches, options) {
         binaryName: config.binaryName,
         furnacePrefixes: await collectFurnaceManagedPrefixes(paths.root),
         refuseAdjacentUnmanaged: options.refuseAdjacentUnmanaged === true,
+        approvedUnmanaged: new Set((options.expectUnmanaged ?? []).map((file) => normalizeEngineRelativeInput(file, '--expect-unmanaged'))),
+        approvedSeen: new Set(),
         refusals: [],
     };
     const driftCtx = buildForeignDriftContext(options);
@@ -155,6 +158,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     }));
     await finishReExportLint(lintCtx);
     warnUnseenExpectedDrift(driftCtx);
+    warnUnseenApprovedUnmanaged(adjacentCtx);
     throwRunLevelRefusals(adjacentCtx, driftCtx, progress);
     if (reExported === 0 && selectedPatches.length > 0) {
         progress.error('Re-export failed');
@@ -198,26 +202,22 @@ function buildForeignDriftContext(options) {
     };
 }
 /**
- * Names `--expect` paths that never drifted this run. A typo'd
- * `--expect` path silently degrades the flag back to refusing the slice it
- * was meant to admit, so surface the mismatch — but only as a warning: an
- * expected file legitimately shows no drift when the slice was already
- * captured by an earlier export.
+ * Names `--expect-unmanaged` paths that were never met this run. A typo'd
+ * carve-out silently leaves the refusal armed for the path it was meant to
+ * admit — and, worse, reads as an approval that is in force when it is not.
+ * A warning rather than a refusal: an approved path legitimately goes unmet
+ * when the reviewed file has since been adopted into a patch, which is the
+ * outcome the carve-out exists to be retired by.
  */
-function warnUnseenExpectedDrift(driftCtx) {
-    const unseen = [...driftCtx.expectedDriftFiles].filter((file) => !driftCtx.expectedSeen.has(file));
+function warnUnseenApprovedUnmanaged(adjacentCtx) {
+    const unseen = [...adjacentCtx.approvedUnmanaged].filter((file) => !adjacentCtx.approvedSeen.has(file));
     if (unseen.length === 0)
         return;
-    if (driftCtx.evaluationRuns === 0) {
-        warn(`--expect path(s) were not evaluated because no selected patch reached the drift check (for example, an earlier refusal): ${unseen.join(', ')}`);
-        return;
-    }
-    warn('--expect path(s) showed no drift this run: ' +
+    warn('--expect-unmanaged path(s) were not met as adjacent unmanaged files this run: ' +
         `${unseen.join(', ')}. ` +
-        'Causes, in rough order of likelihood: a typo in the path; the slice was already ' +
-        'captured by an earlier export in this session; or the engine content already matches ' +
-        'the patch body — a concurrent session may have exported the same change, so the drift ' +
-        'converged before this run looked.');
+        'Causes, in rough order of likelihood: a typo in the path; the file is now owned by a ' +
+        'patch (the carve-out can be dropped); or no selected patch is adjacent to it. The ' +
+        'refusal stayed armed for everything else either way.');
 }
 /**
  * Turns the run's collected `--refuse-adjacent-unmanaged` and

package/dist/src/commands/test-build-phase.js

@@ -43,7 +43,8 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
             // Warning severity, not info: agent-facing output filters
             // keep warnings and errors only, and this is the line that explains an
             // otherwise unexplained multi-minute build.
-            notice('A jar.mn registration changed since the last successful build; escalating this pre-test build to a full mach build so new install-manifest destinations are created.');
+            notice(preparation.fullBuildReason ??
+                'A jar.mn registration changed since the last successful build; escalating this pre-test build to a full mach build so new install-manifest destinations are created.');
         }
         const s = spinner(preparation.fullBuildRequired
             ? 'Running required full build...'

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

@@ -7,11 +7,12 @@
  * `test-harness-crash.ts` for single and sharded invocations. Split out of
  * `test.ts` to keep both files within the per-file line budget.
  */
+import { getActiveRunLogPath } from '../core/run-log.js';
 import { describeChangedPrefNoise } from '../core/test-changed-prefs.js';
 import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, buildSilentSegfaultMessage, headedNoOutputTimeoutHint, isSilentSegfault, } from '../core/test-harness-crash.js';
 import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, completePostRebuildFailureContext, prependPostRebuildFailureContext, } from '../core/test-harness-output.js';
 import { GeneralError } from '../errors/base.js';
-import { BuildError } from '../errors/build.js';
+import { TestFailureError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
@@ -132,7 +133,13 @@ function buildMochitestHttp3ServerMessage() {
  * broader ones, so a fork-owned module failure is not reported as a stale
  * build.
  */
-function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext) {
+function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext, 
+/**
+ * The classified verdict, when one was reached. Carries the failing-test
+ * evidence the final throw names; every branch ABOVE that throw is a
+ * different diagnosis and does not use it.
+ */
+verdict) {
     if (result.exitCode === 0 || result.exitCode === 130)
         return;
     const combinedOutput = `${result.stdout}\n${result.stderr}`;
@@ -194,8 +201,10 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     // fail (exit code stays 5), so this only says WHICH KIND of failure it is.
     // Every branch above is a different diagnosis and outranks it.
     const changedPrefNoise = describeChangedPrefNoise(combinedOutput);
-    throw new BuildError(withContext(`Tests failed with exit code ${result.exitCode}. Check the output above for details.` +
-        (changedPrefNoise !== undefined ? `\n\n${changedPrefNoise}` : '')), 'mach test');
+    const failureBlocks = formatFailureBlocks(verdict?.realFailureBlocks);
+    const logPath = getActiveRunLogPath();
+    throw new TestFailureError(withContext(`Tests failed with exit code ${result.exitCode}.` +
+        (changedPrefNoise !== undefined ? `\n\n${changedPrefNoise}` : '')), 'mach test', failureBlocks, logPath);
 }
 /**
  * Applies the harness-run verdict for a single (non-sharded) invocation:
@@ -259,7 +268,7 @@ function applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuild
                 outcome.verdict.secondaryHarnessSignature.line);
         }
     }
-    handleNonZeroTestExit(outcome.result, normalizedPaths, outcome.appdirInjectionAttempted, binaryName, postRebuildContext);
+    handleNonZeroTestExit(outcome.result, normalizedPaths, outcome.appdirInjectionAttempted, binaryName, postRebuildContext, outcome.verdict);
 }
 /**
  * Shard-mode adapter over {@link handleNonZeroTestExit}: produces the

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

@@ -67,6 +67,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--allow-stale-build', 'Allow tests to run even when packageable engine files changed since the last successful FireForge build')
         .option('--allow-stale-components', 'Run tests despite components.conf changes that only a full "fireforge build" compiles in (the packaged child process will resolve the OLD StaticComponents table)')
         .option('--kill-stale-marionette', 'Terminate a recognized stale browser from this objdir or one holding the Marionette port before running tests')
+        .option('--reap-orphans', 'Terminate harness helper processes (httpd, pywebsocket, ssltunnel, moz-http2) from this objdir that survived an earlier run. The census itself runs on every test dispatch and is report-only; this flag opts into the kill.')
         .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
         .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', ...stringListOption())

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

@@ -12,11 +12,12 @@
  */
 import { probeDisplaySleepState } from '../core/display-state.js';
 import { mochitestWithOutput, testWithOutput, xpcshellTestWithOutput, } from '../core/mach.js';
+import { getActiveRunLogPath } from '../core/run-log.js';
 import { changedPrefNoiseVerdictNote } from '../core/test-changed-prefs.js';
 import { buildHarnessCrashMessage, classifyHarnessRun, headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
 import { withXpcshellProfileDir } from '../core/xpcshell-profile-dir.js';
-import { BuildError } from '../errors/build.js';
+import { TestFailureError } from '../errors/build.js';
 import { info, note, warn } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
 import { maybeInjectAppdirArg } from './test-appdir.js';
@@ -193,8 +194,8 @@ export function finalizeShardedOutcome(summary) {
     emitHarnessVerdict(summary.aggregate, { passed: summary.passed, total: summary.total });
     if (summary.passed < summary.total) {
         const failing = summary.shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
-        throw new BuildError(`${failing.length} of ${summary.total} sharded test run(s) did not pass: ` +
+        throw new TestFailureError(`${failing.length} of ${summary.total} sharded test run(s) did not pass: ` +
             `${failing.map(({ label }) => label).join(', ')}. ` +
-            'See the per-shard diagnosis above. Use --no-shard to reproduce the combined single-invocation behaviour.', 'mach test');
+            'See the per-shard diagnosis above. Use --no-shard to reproduce the combined single-invocation behaviour.', 'mach test', undefined, getActiveRunLogPath());
     }
 }

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

@@ -7,7 +7,7 @@
  * stays wiring; the probes and refusal copy live in
  * `src/core/test-stale-check.ts`.
  */
-import { checkStaleBuildForTest, checkStaticComponentsStale, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
+import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
 import { GeneralError } from '../errors/base.js';
 import { warn } from '../utils/logger.js';
 /**
@@ -37,7 +37,10 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
         const recordedCoverage = stale.baseline?.testPackagingCoverage;
         const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
         if (uncovered.length > 0) {
-            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : []));
+            // The refusal is correct on its own; naming the manifest that gained
+            // an entry is the triage step it otherwise leaves to the reader.
+            const changedManifests = await findChangedTestManifestsForPaths(engineDir, stale.baseline, uncovered);
+            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests));
         }
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);

package/dist/src/commands/test.js

@@ -3,6 +3,7 @@ import { join, resolve } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
+import { reportOrphanedHarnessProcesses } from '../core/harness-orphans.js';
 import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
@@ -224,7 +225,7 @@ async function ensureTestMarionettePortAvailable(port, binaryName, options, skip
     }
     await assertMarionettePortAvailable(port, { binaryName });
 }
-async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellOnly, binaryName, options) {
+async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellOnly, binaryName, options, objDir) {
     // A timed-out mochitest can leave the built app alive after its Marionette
     // listener has disappeared. The port probe cannot see that case, but the
     // survivor can still steal focus and wedge every later headed run.
@@ -242,6 +243,12 @@ async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellO
             killStaleServer: options.killStaleMarionette === true,
         });
     }
+    // Helpers that outlived an earlier run (httpd, pywebsocket, ssltunnel,
+    // moz-http2) slow every later run without appearing in its output. Both
+    // harnesses are affected, so this census is not gated on xpcshellOnly.
+    await reportOrphanedHarnessProcesses(objDir, {
+        reap: options.reapOrphans === true,
+    });
     const forwardedPort = options.machArg
         ? extractForwardedMarionettePort(options.machArg)
         : undefined;
@@ -359,7 +366,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     // documented `--mach-arg --marionette-port=NNNN` route still hits the
     // wrapper preflight refusing on 2828 before the forwarded arg reaches
     // mach.
-    const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig.binaryName, options);
+    const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig.binaryName, options, buildCheck.objDir);
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
             engineDir: paths.engine,

package/dist/src/core/build-audit.js

@@ -35,6 +35,7 @@
  */
 import { readdir, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
@@ -43,6 +44,8 @@ import { collectSameBasenameCandidates, findRegisteredTarget, resolveArtifactByR
 import { countTrailingSegmentMatches, GENERIC_PATH_SEGMENTS, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
 import { resolveArtifactByKnownTransform } from './build-audit-transforms.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
+import { loadPatchesManifest } from './patch-manifest-io.js';
+import { buildPatchClaims } from './status-classify.js';
 /** Path extensions that are conventionally packaged into the Firefox bundle. */
 const PACKAGEABLE_EXTENSIONS = [
     '.js',
@@ -442,6 +445,39 @@ function relativeManifestPath(engineDir, manifest) {
     }
     return manifest;
 }
+/**
+ * Path → owning patch filenames, from the patches manifest's
+ * `filesAffected`. Best-effort: a project with no queue (or an unreadable
+ * manifest) yields an empty map and the notices render exactly as before.
+ */
+async function resolveAuditOwnership(projectRoot) {
+    try {
+        const patchesDir = join(projectRoot, 'patches');
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            return new Map();
+        return buildPatchClaims(manifest.patches);
+    }
+    catch (error) {
+        verbose(`Audit: ownership lookup unavailable (${toError(error).message}).`);
+        return new Map();
+    }
+}
+/**
+ * Renders the ownership suffix for one audit notice: the owning patch, or
+ * an explicit `unmanaged` mark. An empty map (no queue, unreadable
+ * manifest) renders nothing rather than claiming everything is unmanaged —
+ * "unmanaged" must mean "checked and unowned", never "could not check".
+ */
+function describeOwnership(ownersByPath, source) {
+    if (ownersByPath.size === 0)
+        return '';
+    const owners = ownersByPath.get(source);
+    if (owners === undefined || owners.length === 0) {
+        return ' Ownership: unmanaged (no patch claims this path).';
+    }
+    return ` Ownership: ${owners.join(', ')}.`;
+}
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
@@ -453,7 +489,6 @@ function relativeManifestPath(engineDir, manifest) {
  * @returns Summary of artifact status counts.
  */
 export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
-    void projectRoot;
     const summary = {
         updated: 0,
         stale: 0,
@@ -472,6 +507,13 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
     if (changed.length === 0) {
         return summary;
     }
+    // Ownership, resolved once for the whole audit. The notices key on "was
+    // touched", which on a shared checkout means any concurrent session's
+    // dirty files — so an operator gets a registration-shaped warning about a
+    // file they never edited and has to census ownership by hand to dismiss
+    // it. FireForge already resolves this for `status --ownership`; carrying
+    // it here turns a three-line mystery into three dismissible lines.
+    const ownersByPath = await resolveAuditOwnership(projectRoot);
     const ctx = { engineDir, distRoot, testsRoot, testsPackaged };
     for (const source of changed) {
         const result = await auditSinglePath(source, ctx);
@@ -482,7 +524,7 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
             status: result.status,
         });
         if (result.warning)
-            warn(result.warning);
+            warn(`${result.warning}${describeOwnership(ownersByPath, result.source)}`);
     }
     info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
     return summary;

package/dist/src/core/build-jar-escalation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Decides whether a changed `jar.mn` really forces the pre-test build to
+ * escalate from `mach build faster` to a full `mach build`.
+ *
+ * The 0.41.0 rule was `any changed jar.mn ⇒ full build`, which costs ~10
+ * minutes against ~20 s for a chrome-only slice and is paid TWICE per
+ * green/no-change pair on a Furnace-touching slice. A downstream experiment
+ * (two clean runs, 2026-08-29, against 0.44.4) showed the rule is over-broad
+ * for the common case: a jar-only registration of a NEW content file added
+ * to an EXISTING `dist/bin` manifest was installed by a plain
+ * `fireforge build --ui` both times — `faster/install_dist_bin_browser` named
+ * the destination, the file landed in `dist/bin/…/content/browser/` and in
+ * the `.app` bundle, and a plain `fireforge test` fetched it over
+ * `chrome://` at runtime. Neither run escalated, and neither needed to.
+ *
+ * What the experiment did NOT exercise, and what therefore still escalates:
+ *
+ *  - a NEW `jar.mn` file. The install manifest for a manifest the backend
+ *    has never seen does not exist yet, and `mach build faster` consumes
+ *    install manifests rather than regenerating the backend that writes
+ *    them.
+ *  - a manifest whose jar declaration carries a bracketed base-directory
+ *    prefix (`[some/dir] name.jar:`), which redirects the install
+ *    destination away from the default chrome root. That redirect is the
+ *    "non-dist/bin target" half nobody has run.
+ *
+ * Everything else about the rule is unchanged, and every failure to read or
+ * parse a manifest escalates: this narrows a conservative rule, so its
+ * error direction stays the slow-but-correct one.
+ */
+import type { BuildBaseline } from './build-baseline-types.js';
+/** Why one changed `jar.mn` still forces a full build. */
+export interface JarEscalationCause {
+    /** Engine-relative manifest path. */
+    path: string;
+    /** Operator-facing reason, printed with the escalation notice. */
+    reason: string;
+}
+/** Outcome of {@link evaluateJarManifestEscalation}. */
+export interface JarEscalationDecision {
+    /** True when at least one changed manifest still needs a full build. */
+    escalate: boolean;
+    /** One entry per manifest that forces the escalation. */
+    causes: JarEscalationCause[];
+    /** Manifests the narrowing cleared; kept for the verbose explanation. */
+    cleared: string[];
+}
+/**
+ * Evaluates every changed `jar.mn` against the narrowed rule.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param changedPaths - Engine-relative paths changed since the last
+ *   successful build (non-`jar.mn` entries are ignored)
+ * @param baseline - Last successful build's baseline (reserved: the
+ *   fingerprint map already gated which paths reach here)
+ * @returns The escalation decision with per-manifest causes
+ */
+export declare function evaluateJarManifestEscalation(engineDir: string, changedPaths: readonly string[], baseline: BuildBaseline | undefined): Promise<JarEscalationDecision>;
+/**
+ * Renders the operator-facing escalation notice. Names the manifest AND the
+ * reason: "a jar.mn changed" is the sentence that made the previous rule
+ * impossible to argue with from outside.
+ */
+export declare function formatJarEscalationNotice(decision: JarEscalationDecision): string;

package/dist/src/core/build-jar-escalation.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Decides whether a changed `jar.mn` really forces the pre-test build to
+ * escalate from `mach build faster` to a full `mach build`.
+ *
+ * The 0.41.0 rule was `any changed jar.mn ⇒ full build`, which costs ~10
+ * minutes against ~20 s for a chrome-only slice and is paid TWICE per
+ * green/no-change pair on a Furnace-touching slice. A downstream experiment
+ * (two clean runs, 2026-08-29, against 0.44.4) showed the rule is over-broad
+ * for the common case: a jar-only registration of a NEW content file added
+ * to an EXISTING `dist/bin` manifest was installed by a plain
+ * `fireforge build --ui` both times — `faster/install_dist_bin_browser` named
+ * the destination, the file landed in `dist/bin/…/content/browser/` and in
+ * the `.app` bundle, and a plain `fireforge test` fetched it over
+ * `chrome://` at runtime. Neither run escalated, and neither needed to.
+ *
+ * What the experiment did NOT exercise, and what therefore still escalates:
+ *
+ *  - a NEW `jar.mn` file. The install manifest for a manifest the backend
+ *    has never seen does not exist yet, and `mach build faster` consumes
+ *    install manifests rather than regenerating the backend that writes
+ *    them.
+ *  - a manifest whose jar declaration carries a bracketed base-directory
+ *    prefix (`[some/dir] name.jar:`), which redirects the install
+ *    destination away from the default chrome root. That redirect is the
+ *    "non-dist/bin target" half nobody has run.
+ *
+ * Everything else about the rule is unchanged, and every failure to read or
+ * parse a manifest escalates: this narrows a conservative rule, so its
+ * error direction stays the slow-but-correct one.
+ */
+import { join } from 'node:path';
+import { readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { isJarManifestPath } from './build-audit.js';
+import { getUntrackedFilesInDir } from './git-status.js';
+/**
+ * A jar declaration line: an optional bracketed base-directory prefix, then
+ * the jar name. Matched at column zero because entry lines inside a section
+ * are indented — an indented `foo.jar:` is content, not a declaration.
+ */
+const JAR_DECLARATION_PATTERN = /^(\[[^\]]*\]\s*)?[^\s[\]]+\.jar:\s*$/;
+/** True when the jar declaration redirects the install base directory. */
+function declaresNonDefaultBase(line) {
+    const match = JAR_DECLARATION_PATTERN.exec(line);
+    if (!match)
+        return false;
+    return match[1] !== undefined;
+}
+/**
+ * True when a changed `jar.mn` is NEW to the last successful build.
+ *
+ * Untracked in the engine repo is the reliable tell: a fork's engine tree is
+ * a checkout of upstream with patches applied to the WORKTREE, so a manifest
+ * a patch created is untracked and one that shipped upstream is tracked. The
+ * baseline's fingerprints cannot answer this on their own — they record only
+ * the paths that were DIRTY at the last build, so a clean pre-existing
+ * manifest has no entry either.
+ */
+async function isNewJarManifest(engineDir, path) {
+    const untracked = await getUntrackedFilesInDir(engineDir, path);
+    return untracked.includes(path);
+}
+/**
+ * Evaluates every changed `jar.mn` against the narrowed rule.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param changedPaths - Engine-relative paths changed since the last
+ *   successful build (non-`jar.mn` entries are ignored)
+ * @param baseline - Last successful build's baseline (reserved: the
+ *   fingerprint map already gated which paths reach here)
+ * @returns The escalation decision with per-manifest causes
+ */
+export async function evaluateJarManifestEscalation(engineDir, changedPaths, baseline) {
+    void baseline;
+    const causes = [];
+    const cleared = [];
+    for (const path of changedPaths.filter(isJarManifestPath)) {
+        let isNew;
+        try {
+            isNew = await isNewJarManifest(engineDir, path);
+        }
+        catch (error) {
+            // Fail closed: an unanswerable "is this new?" keeps the old rule.
+            verbose(`jar escalation: could not classify engine/${path} (${String(error)}); escalating.`);
+            causes.push({ path, reason: 'could not determine whether the manifest is new' });
+            continue;
+        }
+        if (isNew) {
+            causes.push({ path, reason: 'new jar.mn (no install manifest exists for it yet)' });
+            continue;
+        }
+        let body;
+        try {
+            body = await readText(join(engineDir, path));
+        }
+        catch (error) {
+            verbose(`jar escalation: could not read engine/${path} (${String(error)}); escalating.`);
+            causes.push({ path, reason: 'manifest could not be read' });
+            continue;
+        }
+        const redirected = body
+            .split(/\r?\n/)
+            .filter((line) => declaresNonDefaultBase(line))
+            .map((line) => line.trim());
+        if (redirected.length > 0) {
+            causes.push({
+                path,
+                reason: `jar declaration redirects the install base directory (${redirected[0] ?? ''})`,
+            });
+            continue;
+        }
+        cleared.push(path);
+    }
+    return { escalate: causes.length > 0, causes, cleared };
+}
+/**
+ * Renders the operator-facing escalation notice. Names the manifest AND the
+ * reason: "a jar.mn changed" is the sentence that made the previous rule
+ * impossible to argue with from outside.
+ */
+export function formatJarEscalationNotice(decision) {
+    const detail = decision.causes.map((c) => `engine/${c.path} (${c.reason})`).join('; ');
+    return (`Escalating this pre-test build to a full mach build so new install-manifest destinations ` +
+        `are created: ${detail}. A changed jar.mn that merely adds entries to an existing ` +
+        `dist/bin manifest no longer escalates.`);
+}

package/dist/src/core/build-prepare.d.ts

@@ -14,6 +14,11 @@ export interface BuildPreparation {
     reconfigured: boolean;
     /** A changed packaging manifest cannot be safely handled by `mach build faster`. */
     fullBuildRequired?: boolean;
+    /**
+     * Operator-facing explanation for {@link fullBuildRequired}, naming the
+     * manifest and why it still escalates. Absent when no escalation applies.
+     */
+    fullBuildReason?: string;
 }
 /** Options for {@link prepareBuildEnvironment}. */
 export interface PrepareBuildOptions {
@@ -31,7 +36,13 @@ export interface PrepareBuildOptions {
      */
     refuseUnexportedDrift?: boolean | undefined;
 }
-/** Packaging manifests whose graph/destination directories need a full build. */
+/**
+ * Packaging manifests whose graph/destination directories MAY need a full
+ * build. Path-shape only: {@link evaluateJarManifestEscalation} decides
+ * whether a given changed manifest actually forces one (a new manifest, or
+ * one that redirects its install base directory), so an entry added to an
+ * existing `dist/bin` manifest no longer costs a ~10-minute build.
+ */
 export declare function requiresFullBuildForIncrementalTest(path: string): boolean;
 /**
  * Describes an exit code in the shell's 128+N signal convention. Truncated

package/dist/src/core/build-prepare.js

@@ -12,6 +12,7 @@ import { pathExists } from '../utils/fs.js';
 import { info, notice, spinner, verbose, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
 import { isBuildInputPath, isJarManifestPath } from './build-audit.js';
+import { evaluateJarManifestEscalation, formatJarEscalationNotice, } from './build-jar-escalation.js';
 import { findUnexportedDriftAtRisk, formatUnexportedDriftWarning, } from './build-overwrite-guard.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
 import { applyAllComponents } from './furnace-apply.js';
@@ -23,7 +24,13 @@ import { generateMozconfig, runMachCapture } from './mach.js';
 import { explainMachError } from './mach-error-hints.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
-/** Packaging manifests whose graph/destination directories need a full build. */
+/**
+ * Packaging manifests whose graph/destination directories MAY need a full
+ * build. Path-shape only: {@link evaluateJarManifestEscalation} decides
+ * whether a given changed manifest actually forces one (a new manifest, or
+ * one that redirects its install base directory), so an entry added to an
+ * existing `dist/bin` manifest no longer costs a ~10-minute build.
+ */
 export function requiresFullBuildForIncrementalTest(path) {
     return isJarManifestPath(path);
 }
@@ -107,6 +114,24 @@ function buildConfigureFailureError(captured) {
         (hints.length > 0 ? `\n\n${hints.map((hint) => `Hint: ${hint}`).join('\n')}` : '') +
         '\n\nBuild stopped because continuing would hide the real configure failure.', 'mach configure');
 }
+/**
+ * Runs the narrowed `jar.mn` escalation rule over this run's changed build
+ * inputs and returns the operator-facing reason when a full build is still
+ * required, or undefined when the narrowing cleared every changed manifest.
+ *
+ * Extracted so `prepareBuildEnvironment` stays under the complexity budget.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param changed - Build inputs changed since the last successful build
+ * @param baseline - Last successful build's baseline
+ */
+async function decideJarEscalation(engineDir, changed, baseline) {
+    const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(requiresFullBuildForIncrementalTest), baseline);
+    if (decision.cleared.length > 0) {
+        verbose(`jar escalation: ${String(decision.cleared.length)} changed jar.mn add entries to an existing dist/bin manifest; not escalating for ${decision.cleared.join(', ')}.`);
+    }
+    return decision.escalate ? formatJarEscalationNotice(decision) : undefined;
+}
 /**
  * Returns true when the file path matches a pattern that forces
  * `mach configure` to regenerate the backend. Exported for testing.
@@ -177,10 +202,13 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     // work against a stale recursive-make backend.
     let reconfigured = false;
     let fullBuildRequired = false;
+    let fullBuildReason;
     if (options.previousBaseline) {
         const changed = await collectChangedBuildInputs(paths.engine, options.previousBaseline);
         const invalidating = changed.filter(isBackendInvalidatingFile);
-        fullBuildRequired = changed.some(requiresFullBuildForIncrementalTest);
+        const jarEscalation = await decideJarEscalation(paths.engine, changed, options.previousBaseline);
+        fullBuildRequired = jarEscalation !== undefined;
+        fullBuildReason = jarEscalation;
         if (invalidating.length > 0) {
             // Warning severity: this is the "why is this run slow" explanation,
             // and an info-level line does not survive an agent output filter that
@@ -300,5 +328,10 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
         mozconfigSpinner.error('Failed to generate mozconfig');
         throw error;
     }
-    return { furnaceApplied, reconfigured, fullBuildRequired };
+    return {
+        furnaceApplied,
+        reconfigured,
+        fullBuildRequired,
+        ...(fullBuildReason !== undefined ? { fullBuildReason } : {}),
+    };
 }

package/dist/src/core/config-validate-file-size.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Validation for `patchLint.fileSizeThresholds`.
+ *
+ * Split out of `config-validate.ts`, which is at its per-file line budget.
+ */
+import type { PatchLintFileSizeThresholds } from '../types/config.js';
+/**
+ * Parses the `patchLint.fileSizeThresholds` block. Ordering is validated
+ * against the MERGED triple (overrides on top of the defaults), so setting
+ * only `warning` cannot land below the default `notice`.
+ */
+export declare function parsePatchLintFileSizeThresholds(raw: unknown): PatchLintFileSizeThresholds;