@hominis/fireforge 0.46.1 → 0.47.0

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

@@ -20,15 +20,18 @@
  *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
  *   against the just-refreshed body instead of the stale one.
  */
-import { buildPatchQueueContext, countNonBinaryDiffLines, detectNewFilesInDiff, lintExportedPatch, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { buildPatchQueueContext, countNonBinaryDiffLines, detectNewFilesInDiff, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/patch-lint-cache.js';
 import { invalidateNewFileCreatorsCache } from '../core/patch-lint-cross.js';
-import { extractAddedLinesPerFile } from '../core/patch-lint-diff.js';
 import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
+import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
+import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
-import { info } from '../utils/logger.js';
+import { info, warn } from '../utils/logger.js';
 import { reportPatchLintOutcome } from './export-shared.js';
 import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
+import { projectEntryBody } from './patch/entry-projection.js';
+import { formatForwardImportRemedy } from './re-export-scan.js';
 /** Builds the once-per-invocation lint context. */
 export async function buildReExportLintContext(projectRoot, paths, config, noCache) {
     const patchQueueCtx = (await pathExists(paths.patches))
@@ -50,6 +53,7 @@ export async function buildReExportLintContext(projectRoot, paths, config, noCac
         cacheDirty: false,
         reusedCacheEntries: 0,
         globalsEmitted: false,
+        queueBaselineWarned: false,
     };
 }
 /** The checkJs-relevant files this fresh diff creates. */
@@ -179,10 +183,61 @@ export async function storeReExportLintResult(lintCtx, patchFilename, projectedM
     });
     lintCtx.cacheDirty = true;
 }
+/**
+ * Projects the rewritten body into the hoisted queue context and refuses
+ * when the projection introduces error-severity cross-patch findings the
+ * current queue does not have (a forward import an earlier owner gained,
+ * say). Mirrors `re-export --files` (its projected-state conflict) and the
+ * `--scan` adoption gate, which only covered files a scan adopted: a plain
+ * re-export of an unchanged file set with new CONTENT used to pass, and the
+ * queue carried the error until the next `export` placement refused it.
+ *
+ * Runs in dry-run. `--force-unsafe` downgrades the refusal to warnings;
+ * `--skip-lint` does not bypass it, same as `--files`. The baseline is the
+ * hoisted context, which {@link refreshQueueCtxEntry} keeps equal to the
+ * on-disk queue across an `--all` loop, so patch N+1 is projected against
+ * the queue as it will exist.
+ */
+export function assertRefreshedBodyHasNoNewQueueErrors(args) {
+    const { lintCtx, patchFilename, diffContent, forceUnsafe } = args;
+    const ctx = lintCtx.patchQueueCtx;
+    if (!ctx)
+        return;
+    const projection = projectEntryBody(diffContent);
+    const projectedEntries = ctx.entries.map((entry) => entry.filename === patchFilename ? { ...entry, ...projection } : entry);
+    const isError = (issue) => issue.severity === 'error';
+    const baseline = lintPatchQueue(ctx).filter(isError);
+    const projected = lintPatchQueue({
+        entries: projectedEntries,
+        ...(ctx.patchPolicy ? { patchPolicy: ctx.patchPolicy } : {}),
+    }).filter(isError);
+    const regressions = computeProjectedLintRegressions(baseline, projected);
+    if (regressions.length === 0) {
+        if (baseline.length > 0 && !lintCtx.queueBaselineWarned) {
+            lintCtx.queueBaselineWarned = true;
+            warn(`Note: projected queue still has ${baseline.length} pre-existing ` +
+                'cross-patch error(s) unrelated to this re-export. Run "fireforge verify" to list them.');
+        }
+        return;
+    }
+    const details = regressions.map((issue) => `  ${formatPatchLintIssue(issue)}`).join('\n');
+    const hasForwardImport = regressions.some((issue) => issue.check === 'forward-import');
+    const message = `Refusing to re-export ${patchFilename} because the refreshed body introduces ` +
+        `${regressions.length} new cross-patch lint error${regressions.length === 1 ? '' : 's'}:\n${details}` +
+        (hasForwardImport ? `\n${formatForwardImportRemedy('re-running the re-export')}` : '');
+    if (forceUnsafe) {
+        warn(message);
+        warn('Proceeding because --force-unsafe was provided.');
+        return;
+    }
+    throw new GeneralError(message);
+}
 /**
  * Refreshes the in-memory queue entry for a just-rewritten patch so later
  * iterations (and later cache keys) lint against the new body instead of
- * the stale one. The on-disk write is the authority. This mirrors it.
+ * the stale one. The on-disk write is the authority. This mirrors it, via
+ * the same projection `buildPatchQueueContext` derives an entry from, so
+ * `createdFiles` and `modifiedFileAdditions` stay in step with a rebuild.
  */
 export function refreshQueueCtxEntry(lintCtx, patchFilename, diffContent) {
     const ctx = lintCtx.patchQueueCtx;
@@ -191,22 +246,7 @@ export function refreshQueueCtxEntry(lintCtx, patchFilename, diffContent) {
     const entry = ctx.entries.find((e) => e.filename === patchFilename);
     if (!entry)
         return;
-    entry.diff = diffContent;
-    const newFilePaths = detectNewFilesInDiff(diffContent);
-    const addedLinesByFile = extractAddedLinesPerFile(diffContent);
-    const newFiles = new Map();
-    const modifiedFileAdditions = new Map();
-    for (const [file, lines] of addedLinesByFile) {
-        if (newFilePaths.has(file)) {
-            // A created file's content is its added lines.
-            newFiles.set(file, lines.join('\n'));
-        }
-        else {
-            modifiedFileAdditions.set(file, lines.join('\n'));
-        }
-    }
-    entry.newFiles = newFiles;
-    entry.modifiedFileAdditions = modifiedFileAdditions;
+    Object.assign(entry, projectEntryBody(diffContent));
     invalidateNewFileCreatorsCache(ctx);
 }
 /** Persists cache writes and reports reuse, once after the loop. */

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

@@ -45,6 +45,14 @@ export declare function assertScanAdoptionsHaveNoForwardImports(args: {
     patchFilename: string;
     added: readonly string[];
 }): Promise<void>;
+/**
+ * The one remedy sentence for a forward import a patch body cannot carry.
+ * Shared by the `--scan` adoption gate and the plain re-export projection
+ * gate so both refusals point at the same commands.
+ *
+ * @param reRunHint - What to do after the fix ("re-running the scan")
+ */
+export declare function formatForwardImportRemedy(reRunHint: string): string;
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export declare function assertScanFileAdditionsHaveDiffHunks(args: {
     diffContent: string;

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

@@ -201,9 +201,19 @@ export async function assertScanAdoptionsHaveNoForwardImports(args) {
     const details = offending.map((issue) => `  - ${issue.file}: ${issue.message}`).join('\n');
     throw new GeneralError(`Refusing to adopt ${offending.length} scanned file${offending.length === 1 ? '' : 's'} into ${patchFilename} ` +
         `because they import modules created by later patches:\n${details}\n` +
-        'Export those files as their own later patch ("fireforge export --order <n>" / ' +
+        formatForwardImportRemedy('re-running the scan'));
+}
+/**
+ * The one remedy sentence for a forward import a patch body cannot carry.
+ * Shared by the `--scan` adoption gate and the plain re-export projection
+ * gate so both refusals point at the same commands.
+ *
+ * @param reRunHint - What to do after the fix ("re-running the scan")
+ */
+export function formatForwardImportRemedy(reRunHint) {
+    return ('Export those files as their own later patch ("fireforge export --order <n>" / ' +
         '"fireforge patch split --order <n>") or declare the intentional dependency with ' +
-        '"fireforge patch staged-dependency --add" before re-running the scan.');
+        `"fireforge patch staged-dependency --add" before ${reRunHint}.`);
 }
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export function assertScanFileAdditionsHaveDiffHunks(args) {

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

@@ -16,7 +16,7 @@ import { info, success, warn } from '../utils/logger.js';
 import { sleep } from '../utils/sleep.js';
 import { findMissingFiles, reportAdjacentUnmanagedFiles } from './re-export-adjacent.js';
 import { reportForeignDrift } from './re-export-drift.js';
-import { lintReExportedPatch, refreshQueueCtxEntry, storeReExportLintResult, } from './re-export-lint.js';
+import { assertRefreshedBodyHasNoNewQueueErrors, lintReExportedPatch, refreshQueueCtxEntry, storeReExportLintResult, } from './re-export-lint.js';
 import { assertScanAdoptionsHaveNoForwardImports, assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, scanPatchFilesForReExport, } from './re-export-scan.js';
 const GIT_INDEX_LOCK_RETRY_MS = 300;
 /**
@@ -161,10 +161,16 @@ async function reExportSinglePatch(args) {
         return false;
     }
     const { updates, ignoreChecks, effectiveTier, existingIgnoreSet, flagIgnoreSet } = computeReExportUpdates(patch, options, currentFilesAffected);
-    enforcePatchPolicy({
-        config,
-        manifest: buildProjectedManifest(manifest, manifest.patches.map((entry) => entry.filename === patch.filename ? { ...entry, ...updates } : entry)),
-        command: 're-export',
+    enforceProjectedManifestPolicy({ config, manifest, patch, updates, options });
+    // Cross-patch projection gate (runs in dry-run too): the refreshed body
+    // must not introduce queue-level errors the current queue lacks, e.g. an
+    // earlier owner gaining an import of a later patch's module. Cheap
+    // (in-memory) and more actionable than the per-patch lint, so it fires
+    // first.
+    assertRefreshedBodyHasNoNewQueueErrors({
+        lintCtx,
+        patchFilename: patch.filename,
+        diffContent,
         forceUnsafe: options.forceUnsafe === true,
     });
     // Lint against the once-per-invocation hoisted context (queue context +
@@ -190,6 +196,9 @@ async function reExportSinglePatch(args) {
         if (addedIgnores.length > 0) {
             info(`[dry-run] ${patch.filename}: lintIgnore would gain ${addedIgnores.join(', ')}`);
         }
+        // Memory-only: later `--all --dry-run` iterations project against this
+        // patch's would-be body, exactly as the real run does after its write.
+        refreshQueueCtxEntry(lintCtx, patch.filename, diffContent);
     }
     else {
         await commitRefreshedPatch({
@@ -208,6 +217,16 @@ async function reExportSinglePatch(args) {
     }
     return true;
 }
+/** Manifest-level policy gate over the projected row (ranges, gaps, collisions). */
+function enforceProjectedManifestPolicy(args) {
+    const { config, manifest, patch, updates, options } = args;
+    enforcePatchPolicy({
+        config,
+        manifest: buildProjectedManifest(manifest, manifest.patches.map((entry) => entry.filename === patch.filename ? { ...entry, ...updates } : entry)),
+        command: 're-export',
+        forceUnsafe: options.forceUnsafe === true,
+    });
+}
 /**
  * Writes the refreshed body + manifest row atomically under the patch
  * directory lock (a split write would let a concurrent queue mutation

package/dist/src/commands/run.js

@@ -8,7 +8,7 @@ import { assertEngineExists } from '../core/engine-precondition.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { hasBuildArtifacts, hasRunnableBundle, run, runMachSmoke } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
-import { compileAllowlistFromFile, compileAllowlistFromStrings, matchAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
+import { compileAllowlistFromFile, compileAllowlistFromStrings, findOverCapAllowlistEntries, matchAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { ExitCode } from '../errors/codes.js';
@@ -192,17 +192,7 @@ async function runSmokeExit(engineDir, options) {
         }
         findings.push({ stream, line });
     };
-    // A headed smoke window on a developer desktop absorbs live input: a human
-    // interacting with the window mid-run can trigger console errors (a
-    // password-manager import scan probing an unreadable profile dir, say)
-    // that fail the smoke run looking like a product regression. CI hosts (CI
-    // env var set) are assumed display-free and unattended, so the notice
-    // stays quiet there.
-    if (!options.headless && !process.env['CI']) {
-        warn('Headed smoke window: keyboard/mouse input during the window will contaminate the ' +
-            'console capture and can fail the run. Pass --headless (or run on an unattended host) ' +
-            'for reliable smoke checks.');
-    }
+    warnIfHeadedOnDesktop(options.headless === true);
     info(`Launching browser (smoke-exit after ${smokeExit}s)...\n`);
     const startedAt = Date.now();
     let result;
@@ -222,6 +212,7 @@ async function runSmokeExit(engineDir, options) {
         captureStream?.end();
     }
     const elapsedMs = Date.now() - startedAt;
+    const overCap = findOverCapAllowlistEntries(allowlist, allowlistHits);
     reportSmokeSummary({
         smokeTimeoutMs,
         elapsedMs,
@@ -230,12 +221,14 @@ async function runSmokeExit(engineDir, options) {
         allowlistedTotalHits,
         allowlist,
         allowlistHits,
+        overCap,
         findings,
         exitCode: result.exitCode,
     });
-    // Exit contract (precedence: unallowed errors dominate timed-out).
-    if (findings.length > 0) {
-        throw new SmokeRunError(`Smoke run observed ${findings.length} unallowed console error(s).`, ExitCode.SMOKE_EXIT_FAILURE);
+    // Exit contract (precedence: unallowed errors and over-ceiling floods
+    // dominate timed-out).
+    if (findings.length > 0 || overCap.length > 0) {
+        throw new SmokeRunError(describeSmokeExitFailure(findings.length, overCap.length), ExitCode.SMOKE_EXIT_FAILURE);
     }
     if (result.timedOut) {
         // Clean window: SIGTERM came from us. Treat as success.
@@ -273,6 +266,30 @@ async function buildAllowlist(options) {
     }
     return allow;
 }
+/**
+ * A headed smoke window on a developer desktop absorbs live input: a human
+ * interacting with the window mid-run can trigger console errors (a
+ * password-manager import scan probing an unreadable profile dir, say)
+ * that fail the smoke run looking like a product regression. CI hosts (CI
+ * env var set) are assumed display-free and unattended, so the notice
+ * stays quiet there.
+ */
+function warnIfHeadedOnDesktop(headless) {
+    if (headless || process.env['CI'])
+        return;
+    warn('Headed smoke window: keyboard/mouse input during the window will contaminate the ' +
+        'console capture and can fail the run. Pass --headless (or run on an unattended host) ' +
+        'for reliable smoke checks.');
+}
+/** The SMOKE_EXIT_FAILURE message, naming whichever of the two causes fired. */
+function describeSmokeExitFailure(unallowed, overCap) {
+    const parts = [];
+    if (unallowed > 0)
+        parts.push(`${unallowed} unallowed console error(s)`);
+    if (overCap > 0)
+        parts.push(`${overCap} allowlist entr${overCap === 1 ? 'y' : 'ies'} over its max-hits ceiling`);
+    return `Smoke run observed ${parts.join(' and ')}.`;
+}
 /**
  * Prints the human-readable summary block that follows every smoke run.
  * Called once, right before the exit-code decision. Keeps the reporting
@@ -302,9 +319,17 @@ function reportSmokeSummary(args) {
         args.allowlist.forEach((entry, index) => {
             const hits = args.allowlistHits[index] ?? 0;
             const zeroSuffix = hits === 0 ? '  (never matched — candidate for removal)' : '';
-            info(`    ${hits}×  ${entry.origin}  ${entry.source}${zeroSuffix}`);
+            const cap = entry.maxHits === undefined ? '' : `/${entry.maxHits}`;
+            info(`    ${hits}×${cap}  ${entry.origin}  ${entry.source}${zeroSuffix}`);
         });
     }
+    // An allowlisted shape firing past its `# max-hits` ceiling is a flood the
+    // allowlist was never meant to absorb. It is reported next to the
+    // attribution it came from and counts toward the exit code below.
+    for (const over of args.overCap) {
+        warn(`  allowlisted shape "${over.entry.source}" (${over.entry.origin}) fired ${over.hits}× ` +
+            `over its ceiling of ${over.maxHits}`);
+    }
     if (args.findings.length === 0)
         return;
     warn('');
@@ -330,7 +355,7 @@ export function registerRun(program, { getProjectRoot, withErrorHandling }) {
         return parsed;
     }))
         .option('--console-allow <regex>', 'Allowlist regex (repeatable). Lines that match any entry do not count toward the smoke exit code.', ...stringListOption())
-        .option('--console-allow-file <path>', 'Newline-delimited allowlist regex file. Blank lines and # comments are ignored.')
+        .option('--console-allow-file <path>', 'Newline-delimited allowlist regex file. Blank lines and # comments are ignored. A "# max-hits: N" comment directly above an entry caps how many lines it may match in one run; more than that fails the run with exit 12.')
         .option('--capture-console <file>', 'Mirror captured console output to <file> for post-exit inspection.')
         .option('--headless', 'Launch the browser with --headless. Recommended for --smoke-exit on a shared desktop: input into a headed smoke window contaminates the console capture.')
         .action(withErrorHandling(

package/dist/src/commands/test-harness-env.d.ts

@@ -0,0 +1,24 @@
+import type { TestSuite } from './test-run.js';
+/**
+ * Builds the perf-sample env contract for the harness run:
+ * `--perf-samples <path>` exports `<BINARYNAME>_PERF_SAMPLE_JSON` naming the
+ * artifact file a budget checker consumes after the run.
+ */
+export declare function buildPerfSampleEnv(projectRoot: string, binaryName: string, perfSamples: string | undefined): Record<string, string> | undefined;
+/**
+ * Merges the per-feature harness env contracts into one map, or `undefined`
+ * when no feature exported anything (so `TestRunContext.env` stays absent).
+ */
+export declare function mergeHarnessEnv(...parts: (Record<string, string> | undefined)[]): Record<string, string> | undefined;
+/**
+ * Resolves the `--shuffle` seed: a fresh one when the flag was bare, the
+ * operator's when it carried one. Mach's `--shuffle` is an UNSEEDED
+ * Fisher–Yates over `Math.random` (SimpleTest/setup.js), so a red found by
+ * shuffling could not be reproduced. FireForge draws the seed, exports it
+ * as `FIREFORGE_SHUFFLE_SEED` for harness code that reorders inside a file,
+ * prints it, and stamps it on the verdict line.
+ *
+ * Mochitest-only: the xpcshell harness has no shuffle, and generic `mach
+ * test` dispatch would forward the flag to every suite it fans out to.
+ */
+export declare function resolveShuffleSeed(shuffle: number | boolean | undefined, suite: TestSuite): number | undefined;

package/dist/src/commands/test-harness-env.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-feature environment and argument contracts `fireforge test` exports to
+ * the harness process: the perf-sample artifact path and the seeded
+ * test-order shuffle. Split out of `test.ts` to keep the command body inside
+ * its file budget.
+ */
+import { randomInt } from 'node:crypto';
+import { resolve } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
+import { setVerdictRunAttribute } from './test-verdict.js';
+/**
+ * Builds the perf-sample env contract for the harness run:
+ * `--perf-samples <path>` exports `<BINARYNAME>_PERF_SAMPLE_JSON` naming the
+ * artifact file a budget checker consumes after the run.
+ */
+export function buildPerfSampleEnv(projectRoot, binaryName, perfSamples) {
+    if (!perfSamples)
+        return undefined;
+    const envName = `${binaryName.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_PERF_SAMPLE_JSON`;
+    const artifactPath = resolve(projectRoot, perfSamples);
+    info(`Perf sample contract: ${envName}=${artifactPath}`);
+    return { [envName]: artifactPath };
+}
+/**
+ * Merges the per-feature harness env contracts into one map, or `undefined`
+ * when no feature exported anything (so `TestRunContext.env` stays absent).
+ */
+export function mergeHarnessEnv(...parts) {
+    const merged = {};
+    for (const part of parts) {
+        if (part)
+            Object.assign(merged, part);
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * Resolves the `--shuffle` seed: a fresh one when the flag was bare, the
+ * operator's when it carried one. Mach's `--shuffle` is an UNSEEDED
+ * Fisher–Yates over `Math.random` (SimpleTest/setup.js), so a red found by
+ * shuffling could not be reproduced. FireForge draws the seed, exports it
+ * as `FIREFORGE_SHUFFLE_SEED` for harness code that reorders inside a file,
+ * prints it, and stamps it on the verdict line.
+ *
+ * Mochitest-only: the xpcshell harness has no shuffle, and generic `mach
+ * test` dispatch would forward the flag to every suite it fans out to.
+ */
+export function resolveShuffleSeed(shuffle, suite) {
+    if (shuffle === undefined || shuffle === false)
+        return undefined;
+    if (suite !== 'mochitest') {
+        throw new GeneralError("--shuffle forwards the mochitest harness's file-order shuffle; the xpcshell harness has " +
+            'none, and generic `mach test` dispatch would hand it to every suite. Narrow the paths to ' +
+            'browser-chrome/mochitest files (and drop --generic-mach-test).');
+    }
+    const seed = shuffle === true ? randomInt(1, 2 ** 31 - 1) : shuffle;
+    setVerdictRunAttribute('shuffle', String(seed));
+    info(`Test order shuffle: seed=${seed} (reproduce with "fireforge test --shuffle=${seed}")`);
+    return seed;
+}

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

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { GeneralError, LockContentionError } from '../errors/base.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, stringListOption, } from '../utils/options.js';
+import { parsePositiveIntegerFlag } from '../utils/validation.js';
 import { testCommand } from './test.js';
 import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
 import { emitFailVerdict, resetVerdictEmission, verdictEmitted } from './test-verdict.js';
@@ -29,7 +30,9 @@ const TEST_HELP_TEXT = [
     '--doctor) ends with exactly one raw stdout line',
     '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|test-failures|',
     '  no-tests|preflight|inconclusive|lock-timeout|killed] [checks=<n>]',
-    '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)] [log=<path>]',
+    '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)] [shuffle=<seed>]',
+    '  [log=<path>]',
+    'shuffle=<seed> is the seed a --shuffle run exported to the harness.',
     "log=<path> names this run's complete output, written to",
     '.fireforge/logs/ as the run streams, so a piped or truncated run',
     'still leaves a re-readable artifact.',
@@ -68,11 +71,12 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--auto', 'Forward mach test --auto. Valid only when no explicit paths are provided.')
         .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('--kill-stale-marionette', "Terminate a recognized stale browser from this objdir, one holding the Marionette port, or this checkout's own leftover mochitest httpd before running tests. Never touches another checkout's live harness.")
         .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())
+        .option('--shuffle [seed]', 'Run the mochitest files in a seeded random order: forwards mach --shuffle and exports FIREFORGE_SHUFFLE_SEED=<seed> to the harness (a fresh seed when omitted). The seed rides the FIREFORGE-VERDICT line as shuffle=<seed>; replay a red with --shuffle=<seed>. Mochitest-only. Write it as --shuffle=<seed> or after the paths, since a bare "--shuffle <path>" reads the path as the seed.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shuffle', raw)))
         .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${DEFAULT_HARNESS_RETRIES}.`, commanderArgParser((raw) => {
         const n = Number.parseInt(raw, 10);
         if (!Number.isFinite(n) || n < 0 || n > 10) {

package/dist/src/commands/test-verdict.d.ts

@@ -12,6 +12,8 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  * of the others.
  */
 export type FireforgeVerdictReason = 'crash' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
+/** Records an additive attribute for this run's verdict line. */
+export declare function setVerdictRunAttribute(key: 'shuffle', value: string): void;
 /**
  * Re-arms the verdict sink for a new run. Called at `testCommand` entry so
  * repeated programmatic invocations (and tests) each get their own
@@ -34,7 +36,7 @@ export declare function emitPassVerdict(): void;
  * Emits a FAIL verdict carrying an emission-layer reason code, and
  * optionally the refusal class that produced it.
  *
- * `note=` is additive, like the `log=`, `signal=` and `shards=` keys already
+ * `note=` is additive, like the `log=`, `signal=`, `shards=` and `shuffle=` keys already
  * on this line: `reason=` is unchanged and still comes from the closed set
  * in `docs/machine-output.md`, so a consumer that tokenises `key=value`
  * pairs is unaffected. It exists because `reason=preflight` covers every

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

@@ -3,6 +3,19 @@ import { getActiveRunLogPath } from '../core/run-log.js';
 import { formatFireforgeVerdictLine } from '../core/test-harness-crash.js';
 import { setStdoutSealed } from '../utils/logger.js';
 let emitted = false;
+/**
+ * Additive `key=value` attributes of the run in flight, appended to
+ * whichever verdict line ends it. `shuffle` is the seed a `--shuffle` run
+ * exported to the harness, so a red found by shuffling carries its own
+ * reproduction on the one line an unattended reader keeps. Cleared by
+ * {@link resetVerdictEmission}, so a later run in the same process cannot
+ * inherit it.
+ */
+const runAttributes = new Map();
+/** Records an additive attribute for this run's verdict line. */
+export function setVerdictRunAttribute(key, value) {
+    runAttributes.set(key, value);
+}
 /**
  * True once a test run has begun in this process.
  *
@@ -20,6 +33,7 @@ let armed = false;
 export function resetVerdictEmission() {
     emitted = false;
     armed = true;
+    runAttributes.clear();
     setStdoutSealed(false);
 }
 /** True once this run has written its `FIREFORGE-VERDICT:` line. */
@@ -45,9 +59,10 @@ function writeVerdictLine(line) {
     // break that contract, and one before it is the first thing a `tail` cuts.
     // Appended as an additive `key=value`, so consumers that tokenize the line
     // are unaffected and a truncated tail still says where the full output is.
+    const attributes = [...runAttributes].map(([key, value]) => ` ${key}=${value}`).join('');
     const logPath = getActiveRunLogPath();
     const suffix = logPath === undefined ? '' : ` log=${logPath}`;
-    process.stdout.write(`${line}${suffix}\n`);
+    process.stdout.write(`${line}${attributes}${suffix}\n`);
     setStdoutSealed(true);
 }
 /**
@@ -65,7 +80,7 @@ export function emitPassVerdict() {
  * Emits a FAIL verdict carrying an emission-layer reason code, and
  * optionally the refusal class that produced it.
  *
- * `note=` is additive, like the `log=`, `signal=` and `shards=` keys already
+ * `note=` is additive, like the `log=`, `signal=`, `shards=` and `shuffle=` keys already
  * on this line: `reason=` is unchanged and still comes from the closed set
  * in `docs/machine-output.md`, so a consumer that tokenises `key=value`
  * pairs is unaffected. It exists because `reason=preflight` covers every

package/dist/src/commands/test.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join, resolve } from 'node:path';
+import { join } 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';
@@ -21,6 +21,7 @@ import { info, intro, notice, outro, verbose } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { runTestBuildPhase } from './test-build-phase.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
+import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed } from './test-harness-env.js';
 import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
 import { DEFAULT_HARNESS_RETRIES, finalizeShardedOutcome, runShardedTests, runTestsWithRetries, } from './test-run.js';
 import { emitFailVerdict, emitPassVerdict, resetVerdictEmission, verdictEmitted, } from './test-verdict.js';
@@ -241,6 +242,7 @@ async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellO
     // does not use the httpd, so an xpcshell-only run is never blocked by it.
     if (!xpcshellOnly) {
         await ensureMochitestServerPortAvailable(undefined, {
+            engineDir,
             killStaleServer: options.killStaleMarionette === true,
         });
     }
@@ -418,6 +420,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     }
     await assertTestPathsExist(paths.engine, normalizedPaths);
     const suite = resolveTestSuite(classification, options.genericMachTest === true);
+    const shuffleSeed = resolveShuffleSeed(options.shuffle, suite);
     const forwardedMachArgs = options.machArg && options.machArg.length > 0
         ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
         : [];
@@ -425,6 +428,9 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     if (options.headless) {
         extraArgs.push('--headless');
     }
+    if (shuffleSeed !== undefined) {
+        extraArgs.push('--shuffle');
+    }
     if (options.auto === true) {
         extraArgs.push('--auto');
     }
@@ -465,7 +471,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     // the manifest for each file individually. See src/core/xpcshell-appdir.ts
     // for the full motivation.
     logTestSelection(scopes);
-    const perfSampleEnv = buildPerfSampleEnv(projectRoot, projectConfig.binaryName, options.perfSamples);
+    const harnessEnv = mergeHarnessEnv(buildPerfSampleEnv(projectRoot, projectConfig.binaryName, options.perfSamples), shuffleSeed === undefined ? undefined : { FIREFORGE_SHUFFLE_SEED: String(shuffleSeed) });
     const runCtx = {
         engineDir: paths.engine,
         objDir: buildCheck.objDir,
@@ -475,7 +481,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         harnessRetries,
         headless: options.headless === true,
         ...(options.fullOutput === true ? { fullOutput: true } : {}),
-        ...(perfSampleEnv ? { env: perfSampleEnv } : {}),
+        ...(harnessEnv ? { env: harnessEnv } : {}),
     };
     const postRebuildContext = options.build
         ? createPostRebuildFailureContext('fireforge test --build', normalizedPaths)
@@ -527,16 +533,3 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     }
     finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext, options.headless === true);
 }
-/**
- * Builds the perf-sample env contract for the harness run:
- * `--perf-samples <path>` exports `<BINARYNAME>_PERF_SAMPLE_JSON` naming the
- * artifact file a budget checker consumes after the run.
- */
-function buildPerfSampleEnv(projectRoot, binaryName, perfSamples) {
-    if (!perfSamples)
-        return undefined;
-    const envName = `${binaryName.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_PERF_SAMPLE_JSON`;
-    const artifactPath = resolve(projectRoot, perfSamples);
-    info(`Perf sample contract: ${envName}=${artifactPath}`);
-    return { [envName]: artifactPath };
-}

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

@@ -28,7 +28,6 @@
  * 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. */
@@ -51,11 +50,9 @@ export interface JarEscalationDecision {
  * @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>;
+export declare function evaluateJarManifestEscalation(engineDir: string, changedPaths: readonly string[]): 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

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

@@ -68,12 +68,9 @@ async function isNewJarManifest(engineDir, path) {
  * @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;
+export async function evaluateJarManifestEscalation(engineDir, changedPaths) {
     const causes = [];
     const cleared = [];
     for (const path of changedPaths.filter(isJarManifestPath)) {