@hominis/fireforge 0.44.3 → 0.45.0

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

@@ -64,6 +64,26 @@ async function findAdjacentUnmanagedFiles(args) {
     }
     return [...candidates].sort();
 }
+/**
+ * Splits the candidates into the ones that refuse and the ones a
+ * `--expect-unmanaged` carve-out admits. Approved paths are recorded as seen
+ * so an unused carve-out can be reported, and are RETURNED rather than
+ * dropped: an exception nobody can see is how a carve-out quietly widens.
+ */
+function partitionApproved(files, ctx) {
+    const refusing = [];
+    const approved = [];
+    for (const file of files) {
+        if (ctx.approvedUnmanaged.has(file)) {
+            ctx.approvedSeen.add(file);
+            approved.push(file);
+        }
+        else {
+            refusing.push(file);
+        }
+    }
+    return { refusing, approved };
+}
 /**
  * Emits the scan-less advisory for one patch: missing manifest files and
  * unmanaged files adjacent to the patch's ownership. When
@@ -83,13 +103,18 @@ export async function reportAdjacentUnmanagedFiles(args) {
             `  Re-run with --scan to reconcile filesAffected with the current worktree, ` +
             `or pass --files <paths> to set the list explicitly.`);
     }
-    const unmanagedFiles = await findAdjacentUnmanagedFiles({
+    const allUnmanaged = await findAdjacentUnmanagedFiles({
         currentFilesAffected,
         engineDir: paths.engine,
         manifest,
         patchFilename: patch.filename,
         ctx,
     });
+    const { refusing: unmanagedFiles, approved } = partitionApproved(allUnmanaged, ctx);
+    if (approved.length > 0) {
+        info(`${patch.filename}: ${String(approved.length)} adjacent unmanaged file(s) admitted by ` +
+            `--expect-unmanaged (${approved.join(', ')}) — reported, not refused.`);
+    }
     if (unmanagedFiles.length === 0)
         return false;
     const firstFew = unmanagedFiles.slice(0, 3).join(', ');

package/dist/src/commands/re-export-drift.d.ts

@@ -72,3 +72,11 @@ export declare function reportForeignDrift(args: {
     newDiffContent: string;
     ctx: ForeignDriftContext;
 }): Promise<boolean>;
+/**
+ * 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 in several shapes, all named
+ * below.
+ */
+export declare function warnUnseenExpectedDrift(driftCtx: ForeignDriftContext): void;

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

@@ -271,3 +271,64 @@ function refuseUnreadableBaseline(ctx, patchFilename, detail) {
     warn(`${patchFilename}: skipped (--refuse-foreign-drift) — ${detail}; the drift comparison cannot run, refusing fail-closed.`);
     return true;
 }
+/**
+ * States, verbatim in the notice, WHAT the `--expect` whitelist is compared
+ * against and WHEN. This notice is the only feedback an operator gets that
+ * the drift belt looked at the files they named, and a downstream report
+ * showed the previous copy actively misleading: it warned "showed no drift"
+ * over an edit that WAS captured correctly, and none of the causes it named
+ * held, so the operator's only recourse was `grep -c` on the written body.
+ *
+ * The measurement, stated exactly:
+ *
+ *  - COMPARED: for each file already in the patch's `filesAffected`, the
+ *    `+`/`-` payload lines the REFRESHED body carries that the OLD patch
+ *    body did not (`computeForeignDrift`). It is a content comparison, and
+ *    it is ONE-DIRECTIONAL: excess in the new body only.
+ *  - WHEN: per patch, on the body about to be written, BEFORE the write —
+ *    never against post-write state.
+ *
+ * The one-directional half is what the earlier copy hid, and it is the
+ * cause the report's first shape actually hit: deleting a line from an
+ * engine file makes the refreshed body DROP that file's `+` line. Nothing
+ * is absorbed, so by design there is no drift to see — the belt exists to
+ * catch a concurrent session's edits being silently swallowed INTO a body,
+ * not every difference between two bodies. Naming it is the fix; widening
+ * the comparison would turn every ordinary line removal into a refusal.
+ */
+const EXPECT_MEASUREMENT_NOTE = '--expect is evaluated against CONTENT, before the write: for each file already in the ' +
+    "patch's filesAffected, the payload lines the refreshed body carries that the old patch " +
+    'body did not. It never looks at post-write state.';
+/**
+ * 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 in several shapes, all named
+ * below.
+ */
+export function warnUnseenExpectedDrift(driftCtx) {
+    const unseen = [...driftCtx.expectedDriftFiles].filter((file) => !driftCtx.expectedSeen.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: ' +
+        `${unseen.join(', ')}.\n` +
+        `${EXPECT_MEASUREMENT_NOTE}\n` +
+        'Causes, in rough order of likelihood:\n' +
+        '  1. Your edit only REMOVED lines from the body (you deleted a line from the engine ' +
+        'file). The comparison is one-directional — it reports lines ABSORBED into the body — ' +
+        'so a correctly captured deletion is not drift and never will be. Confirm the capture ' +
+        'with "grep -c" on the written patch body.\n' +
+        "  2. A typo in the path, or a path not in the patch's filesAffected (files adopted " +
+        'this run via --scan/--scan-file are excluded from the comparison by design).\n' +
+        '  3. Adoption already captured it: a "re-export <p> --scan --scan-file <f>" run also ' +
+        "captures that patch's other drifted files, so a scan-less re-export afterwards " +
+        'legitimately sees nothing left to absorb. Informational — a chain that treats this ' +
+        'warning as an error will false-red on it.\n' +
+        '  4. The slice was already captured by an earlier export in this session.\n' +
+        '  5. 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.');
+}

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

@@ -7,11 +7,11 @@ import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { listTrackedInHead } from '../core/git-file-ops.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
 import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
-import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
+import { buildNewFileTextProjection } from '../core/patch-transform.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, outro, success, warn } from '../utils/logger.js';
@@ -42,10 +42,7 @@ function resolveEffectiveTierAndLintIgnore(target, options) {
  */
 async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedDiff) {
     const baseCtx = await buildPatchQueueContext(patchesDir);
-    const projectedNewFiles = new Map();
-    for (const path of detectNewFilesInDiff(projectedDiff)) {
-        projectedNewFiles.set(path, extractNewFileContentFromDiff(projectedDiff, path));
-    }
+    const projectedNewFiles = buildNewFileTextProjection(projectedDiff);
     const projectedModifiedFileAdditions = buildModifiedFileAdditionsFromDiff(projectedDiff);
     const projectedEntries = baseCtx.entries.map((entry) => {
         if (entry.filename !== targetFilename)

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

@@ -45,6 +45,24 @@ export function applyReExportFilesPositionalFolding(patches, options) {
     }
     return { patches: normalized.patches, options: normalized.options };
 }
+/**
+ * Each carve-out flag is inert without the refusal it modifies, and a
+ * silently-inert whitelist is the worst shape: the operator believes an
+ * exception is in force while the refusal it was meant to relax was never
+ * armed. Refuse the combination instead of ignoring it.
+ */
+function validateWhitelistFlagDependencies(options) {
+    if (options.expect !== undefined &&
+        options.expect.length > 0 &&
+        options.refuseForeignDrift !== true) {
+        throw new InvalidArgumentError('--expect names files whose drift is expected under --refuse-foreign-drift and has no effect without it. Pass --refuse-foreign-drift, or drop --expect.', '--expect');
+    }
+    if (options.expectUnmanaged !== undefined &&
+        options.expectUnmanaged.length > 0 &&
+        options.refuseAdjacentUnmanaged !== true) {
+        throw new InvalidArgumentError('--expect-unmanaged names approved exceptions to --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop --expect-unmanaged.', '--expect-unmanaged');
+    }
+}
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export function validateReExportOptionCombinations(patches, options) {
     if (options.files !== undefined) {
@@ -83,11 +101,7 @@ export function validateReExportOptionCombinations(patches, options) {
     if (options.refuseForeignDrift === true && (options.scan || options.files !== undefined)) {
         throw new InvalidArgumentError('--refuse-foreign-drift applies to the scan-less path only and cannot be combined with --scan or --files (those explicitly capture the current engine state).', '--refuse-foreign-drift');
     }
-    if (options.expect !== undefined &&
-        options.expect.length > 0 &&
-        options.refuseForeignDrift !== true) {
-        throw new InvalidArgumentError('--expect names files whose drift is expected under --refuse-foreign-drift and has no effect without it. Pass --refuse-foreign-drift, or drop --expect.', '--expect');
-    }
+    validateWhitelistFlagDependencies(options);
     const usingTierFlag = options.tier !== undefined;
     const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
     if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {

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

@@ -29,6 +29,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('--refuse-adjacent-unmanaged', 'Refuse a scan-less re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Mutually exclusive with --scan and --files.')
         .option('--refuse-foreign-drift', "Refuse a scan-less re-export (non-zero exit, patch not written) when the refreshed body would absorb engine lines not present in the old patch body — protects multi-session checkouts from silently capturing another session's uncommitted edits. Mutually exclusive with --scan and --files.")
         .option('--expect <path>', "With --refuse-foreign-drift, name an engine-relative file whose drift is this session's intended edit: drift confined to --expect files proceeds, drift anywhere else still refuses. Repeatable, and the whitelist applies across EVERY patch in this invocation, not per patch — so pass all the patches and all their --expect paths in one call rather than looping one patch at a time.", ...stringListOption())
+        .option('--expect-unmanaged <path>', 'With --refuse-adjacent-unmanaged, name an engine-relative file that is a REVIEWED, recorded exception to the adjacency refusal: an approved unmanaged path is still listed, but no longer refuses. Repeatable, and the carve-out applies across EVERY patch in this invocation, not per patch. Use it to keep the belt armed for everything else instead of dropping --refuse-adjacent-unmanaged entirely.', ...stringListOption())
         .option('--dry-run', 'Show what would change without writing')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes for this re-export')
@@ -40,7 +41,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
         .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', ...stringListOption());
     addWaitLockOption(reExport).action(withErrorHandling(async (patches, options) => {
-        const { tier, lintIgnore, scanFile, scanFiles, cache, expect, ...rest } = options;
+        const { tier, lintIgnore, scanFile, scanFiles, cache, expect, expectUnmanaged, ...rest } = options;
         const projectRoot = getProjectRoot();
         await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, {
             ...pickDefined(rest),
@@ -49,6 +50,9 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
             ...(tier !== undefined ? { tier: tier } : {}),
             ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
             ...(expect !== undefined && expect.length > 0 ? { expect } : {}),
+            ...(expectUnmanaged !== undefined && expectUnmanaged.length > 0
+                ? { expectUnmanaged }
+                : {}),
             ...(cache === false ? { noCache: true } : {}),
         }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));

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

@@ -5,10 +5,10 @@ import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { listTrackedInHead } from '../core/git-file-ops.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, lintPatchQueue, } from '../core/patch-lint.js';
 import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
 import { getClaimedFiles } from '../core/patch-manifest.js';
-import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
+import { buildNewFileTextProjection } from '../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
@@ -176,10 +176,7 @@ export async function assertScanAdoptionsHaveNoForwardImports(args) {
     const candidateDiff = await getDiffForFilesAgainstHead(engineDir, [...added]);
     if (!candidateDiff.trim())
         return;
-    const candidateNewFiles = new Map();
-    for (const path of detectNewFilesInDiff(candidateDiff)) {
-        candidateNewFiles.set(path, extractNewFileContentFromDiff(candidateDiff, path));
-    }
+    const candidateNewFiles = buildNewFileTextProjection(candidateDiff);
     const candidateAdditions = buildModifiedFileAdditionsFromDiff(candidateDiff);
     const baseCtx = await buildPatchQueueContext(patchesDir);
     const projectedEntries = baseCtx.entries.map((entry) => {

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...'
@@ -84,7 +85,7 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
                     ? 'refresh'
                     : extend !== undefined
                         ? 'carry-forward'
-                        : 'auto');
+                        : 'auto', buildKind);
             }
             catch (baselineError) {
                 verbose(`Could not persist build baseline: ${toError(baselineError).message}`);

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

@@ -1,4 +1,24 @@
 import type { BuildBaseline } from './build-baseline-types.js';
+/**
+ * True for the build-input manifests the build consumes but never packages
+ * (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`).
+ * Excluded from the packaging audit and from `packageableFingerprints`;
+ * fingerprinted separately as `buildInputFingerprints` so `build-prepare`
+ * can tell "dirty against HEAD" from "changed since the last successful
+ * build".
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ */
+export declare function isBuildInputPath(sourcePath: string): boolean;
+/**
+ * True for a chrome packaging manifest (`jar.mn`). Its install-manifest
+ * destinations are the one build input whose change escalates a pre-test
+ * `mach build faster` to a full build, and whose fingerprint is therefore
+ * refreshed only by a full build.
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ */
+export declare function isJarManifestPath(sourcePath: string): boolean;
 /** Result of a single artifact lookup. */
 export interface AuditEntry {
     /** Engine-relative source file path (POSIX separators). */

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',
@@ -74,6 +77,30 @@ const BUILD_INPUT_BASENAMES = new Set([
     'Makefile.in',
     'mozbuild.in',
 ]);
+/**
+ * True for the build-input manifests the build consumes but never packages
+ * (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`).
+ * Excluded from the packaging audit and from `packageableFingerprints`;
+ * fingerprinted separately as `buildInputFingerprints` so `build-prepare`
+ * can tell "dirty against HEAD" from "changed since the last successful
+ * build".
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ */
+export function isBuildInputPath(sourcePath) {
+    return BUILD_INPUT_BASENAMES.has(basename(sourcePath));
+}
+/**
+ * True for a chrome packaging manifest (`jar.mn`). Its install-manifest
+ * destinations are the one build input whose change escalates a pre-test
+ * `mach build faster` to a full build, and whose fingerprint is therefore
+ * refreshed only by a full build.
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ */
+export function isJarManifestPath(sourcePath) {
+    return sourcePath === 'jar.mn' || sourcePath.endsWith('/jar.mn');
+}
 /**
  * Decides whether a source path should be packaged. Returns true for paths
  * whose extension or directory fragment matches a known-packaged pattern,
@@ -88,7 +115,7 @@ export function isPackageablePath(sourcePath) {
         if (sourcePath.includes(fragment))
             return false;
     }
-    if (BUILD_INPUT_BASENAMES.has(basename(sourcePath)))
+    if (isBuildInputPath(sourcePath))
         return false;
     // `.inc.xhtml` fragments are consumed via `#include` from a registered
     // chrome document and resolved at packaging time — they never ship as a
@@ -418,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
@@ -429,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,
@@ -448,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);
@@ -458,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;