@hominis/fireforge 0.46.2 → 0.47.1

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

@@ -0,0 +1,62 @@
+/**
+ * Owns the kill path of one mach test dispatch for `fireforge test`.
+ *
+ * Three things the run must do around every `runMachTestSuite` call, kept
+ * together because each one exists for the same incident (a supervisor
+ * killed the process above FireForge at its bound and the harness httpd it
+ * had launched spun for hours):
+ *
+ *  1. Track the helper pids the harness announces, and after mach has
+ *     exited terminate any that outlived it (`harness-helper-pids.ts`).
+ *  2. Publish the harness process group (`--pgid-file`), so a supervisor
+ *     that can only SIGKILL FireForge can still take the whole tree with
+ *     one `kill -- -<pgid>` afterwards.
+ *  3. Watch FireForge's own parent (`parent-exit-watchdog.ts`). When it
+ *     vanishes mid-run, write the killed verdict, reap the group, and let
+ *     the dispatch loop end the run instead of retrying.
+ *
+ * Every reap adds to the `orphans-reaped=` verdict attribute.
+ */
+import type { MachTestSuiteOptions } from '../core/mach.js';
+/** Inputs for {@link createHarnessTeardown}. */
+export interface HarnessTeardownInputs {
+    /** Absolute objdir of this project, when known: the anchor for every kill. */
+    objDir: string | undefined;
+    /** `--pgid-file`: where to publish the harness process group id. */
+    pgidFile: string | undefined;
+}
+/** One dispatch's teardown: the hooks to spread into `runMachTestSuite`, and its lifecycle. */
+export interface HarnessTeardown {
+    /** Hooks for {@link MachTestSuiteOptions.teardown}. */
+    hooks: NonNullable<MachTestSuiteOptions['teardown']>;
+    /**
+     * Records the same-objdir helpers alive right now, before the dispatch
+     * spawns anything, so the post-close reap can tell this dispatch's
+     * unannounced helpers from an earlier run's survivors. Await it before
+     * `runMachTestSuite`.
+     */
+    prepare(): Promise<void>;
+    /** Stops the parent watchdog. Call after the dispatch resolved or threw. */
+    dispose(): void;
+}
+/**
+ * Builds the teardown for one dispatch (one retry attempt of one shard).
+ * The pid tracker and the group id are per dispatch; the parent watchdog
+ * runs only while that dispatch is in flight.
+ */
+export declare function createHarnessTeardown(inputs: HarnessTeardownInputs): HarnessTeardown;
+/** Records the run's pgid file so {@link removeActivePgidFile} can find it from the signal handler. */
+export declare function setActivePgidFile(path: string | undefined): void;
+/**
+ * Removes the pgid file at the end of a run that ended under FireForge's
+ * control. A file left behind after a normal exit would name a group id
+ * the kernel may have reused; the file must only outlive FireForge when
+ * FireForge itself was killed without notice, which is what it is for.
+ */
+export declare function removePgidFile(path: string | undefined): Promise<void>;
+/**
+ * Signal-pipeline variant of {@link removePgidFile}: removes the run's pgid
+ * file, if one is registered. Called by the bin entry point after the child
+ * shutdown wait, so the group the file names has already been signalled.
+ */
+export declare function removeActivePgidFile(): Promise<void>;

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

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Owns the kill path of one mach test dispatch for `fireforge test`.
+ *
+ * Three things the run must do around every `runMachTestSuite` call, kept
+ * together because each one exists for the same incident (a supervisor
+ * killed the process above FireForge at its bound and the harness httpd it
+ * had launched spun for hours):
+ *
+ *  1. Track the helper pids the harness announces, and after mach has
+ *     exited terminate any that outlived it (`harness-helper-pids.ts`).
+ *  2. Publish the harness process group (`--pgid-file`), so a supervisor
+ *     that can only SIGKILL FireForge can still take the whole tree with
+ *     one `kill -- -<pgid>` afterwards.
+ *  3. Watch FireForge's own parent (`parent-exit-watchdog.ts`). When it
+ *     vanishes mid-run, write the killed verdict, reap the group, and let
+ *     the dispatch loop end the run instead of retrying.
+ *
+ * Every reap adds to the `orphans-reaped=` verdict attribute.
+ */
+import { unlink, writeFile } from 'node:fs/promises';
+import { createHelperPidTracker, reapTrackedHarnessPids, snapshotObjdirHelpers, } from '../core/harness-helper-pids.js';
+import { startParentExitWatchdog } from '../core/parent-exit-watchdog.js';
+import { toError } from '../utils/errors.js';
+import { verbose, warn } from '../utils/logger.js';
+import { sweepProcessGroup } from '../utils/process-group.js';
+import { addVerdictRunCount, emitKilledVerdict } from './test-verdict.js';
+/**
+ * Builds the teardown for one dispatch (one retry attempt of one shard).
+ * The pid tracker and the group id are per dispatch; the parent watchdog
+ * runs only while that dispatch is in flight.
+ */
+export function createHarnessTeardown(inputs) {
+    const tracker = createHelperPidTracker();
+    let pgid;
+    let baseline;
+    const watchdog = startParentExitWatchdog({
+        onParentExit: ({ originalPpid, currentPpid }) => {
+            // Verdict first, before anything that can stall: the parent that would
+            // have read it is gone, but the run log and any tee of stdout are not.
+            emitKilledVerdict('parent-exit');
+            warn(`Parent process ${originalPpid} exited while the harness was running (this process now ` +
+                `reports parent ${currentPpid}); ending the run and terminating the harness tree so it ` +
+                'cannot run on unsupervised.');
+            if (pgid !== undefined) {
+                void sweepProcessGroup(pgid, undefined, 'after the parent process exited').catch((error) => {
+                    warn(`Reaping harness group ${pgid} after parent exit failed: ${toError(error).message}`);
+                });
+            }
+        },
+    });
+    return {
+        hooks: {
+            onOutputChunk: (stream, chunk) => {
+                tracker.feed(stream, chunk);
+            },
+            onProcessGroup: (id) => {
+                pgid = id;
+                verbose(`Harness process group: ${id} (mach is the group leader).`);
+                if (inputs.pgidFile !== undefined)
+                    void publishPgid(inputs.pgidFile, id);
+            },
+            postCloseSweep: async () => {
+                const reaped = await reapTrackedHarnessPids(tracker.tracked(), inputs.objDir, baseline);
+                addVerdictRunCount('orphans-reaped', reaped);
+            },
+        },
+        prepare: async () => {
+            baseline = await snapshotObjdirHelpers(inputs.objDir);
+        },
+        dispose: () => {
+            watchdog.stop();
+        },
+    };
+}
+/**
+ * Writes `<pgid>\n` to the pgid file. Best-effort: a supervisor that asked
+ * for the file and cannot get it is warned, and the run proceeds, because
+ * the file is a courtesy to the supervisor and not a precondition of the
+ * tests.
+ */
+async function publishPgid(path, pgid) {
+    try {
+        await writeFile(path, `${pgid}\n`, 'utf8');
+    }
+    catch (error) {
+        warn(`Could not write --pgid-file ${path}: ${toError(error).message}`);
+    }
+}
+/**
+ * The pgid file of the run in flight, for the signal pipeline. `testCommand`'s
+ * own `finally` removes the file on every path it controls, but on SIGTERM
+ * that `finally` races the bin handler's `process.exit` and loses, and a
+ * SIGTERM is notice: the file must not outlive a run FireForge itself
+ * ended. Set when the run starts, cleared by {@link removePgidFile}.
+ */
+let activePgidFile;
+/** Records the run's pgid file so {@link removeActivePgidFile} can find it from the signal handler. */
+export function setActivePgidFile(path) {
+    activePgidFile = path;
+}
+/**
+ * Removes the pgid file at the end of a run that ended under FireForge's
+ * control. A file left behind after a normal exit would name a group id
+ * the kernel may have reused; the file must only outlive FireForge when
+ * FireForge itself was killed without notice, which is what it is for.
+ */
+export async function removePgidFile(path) {
+    if (path === undefined)
+        return;
+    if (activePgidFile === path)
+        activePgidFile = undefined;
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        // ENOENT is the usual case when no dispatch ever spawned.
+        verbose(`--pgid-file ${path} not removed: ${toError(error).message}`);
+    }
+}
+/**
+ * Signal-pipeline variant of {@link removePgidFile}: removes the run's pgid
+ * file, if one is registered. Called by the bin entry point after the child
+ * shutdown wait, so the group the file names has already been signalled.
+ */
+export async function removeActivePgidFile() {
+    await removePgidFile(activePgidFile);
+}

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,13 @@ 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('--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('--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 (or test.reapOrphans: "reap" in fireforge.json) opts into the kill. Reaps are stamped on the verdict line as orphans-reaped=<n>.')
+        .option('--pgid-file <path>', 'Write the harness process-group id (mach is the group leader) to this file on every spawn, so a supervisor that had to SIGKILL fireforge can still take the whole harness tree with "kill -- -$(cat <path>)". Removed when the run ends normally.')
         .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-run.d.ts

@@ -45,6 +45,8 @@ export interface TestRunContext {
      * the coding-agent markers that quiet it. Off by default.
      */
     fullOutput?: boolean;
+    /** `--pgid-file`: where each dispatch publishes its harness process group id. */
+    pgidFile?: string | undefined;
 }
 /** Outcome of one (possibly retried) harness invocation. */
 export interface TestRunOutcome {