@hominis/fireforge 0.47.0 → 0.48.0

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

@@ -32,15 +32,39 @@ 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) {
+/**
+ * Builds the once-per-invocation lint context.
+ *
+ * The checkJs program is rooted at the patches being re-exported, exactly as
+ * `lint --per-patch --patches` roots it at its subset: the rest of the
+ * queue stays resolvable, so cross-patch imports type-check identically,
+ * but nothing else is parsed or checked. Unscoped, a one-patch re-export
+ * that missed the lint cache type-checked the whole queue (76 s on a
+ * 401-patch queue) to report on one patch.
+ *
+ * @param projectRoot - FireForge project root
+ * @param paths - Resolved project paths
+ * @param config - Loaded configuration
+ * @param noCache - Skip the per-patch lint result cache (`--no-cache`)
+ * @param scopePatches - Filenames of the patches this run re-exports
+ */
+export async function buildReExportLintContext(projectRoot, paths, config, noCache, scopePatches) {
     const patchQueueCtx = (await pathExists(paths.patches))
         ? await buildPatchQueueContext(paths.patches, config)
         : undefined;
     const checkJs = patchQueueCtx
-        ? buildPerRunCheckJs(projectRoot, paths, config, patchQueueCtx)
+        ? buildPerRunCheckJs(projectRoot, paths, config, patchQueueCtx, scopePatches)
         : undefined;
     const cache = noCache ? undefined : await loadPerPatchLintCache(projectRoot);
+    if (patchQueueCtx) {
+        // The queue rules and the projection below read every patch, so the
+        // wait is named rather than left behind one spinner line.
+        info(`Lint scope: queue rules over all ${patchQueueCtx.entries.length} patch(es); ` +
+            `checkJs rooted at the ${scopePatches.size} re-exported patch(es); ` +
+            (cache === undefined
+                ? 'lint cache off (--no-cache).'
+                : `lint cache ${Object.keys(cache.entries).length === 0 ? 'empty' : 'loaded'}.`));
+    }
     const engineHeadSha = cache ? await getPerPatchLintCacheHeadSha(paths.engine) : undefined;
     return {
         projectRoot,
@@ -123,7 +147,12 @@ export async function lintReExportedPatch(args) {
     lintOptions.onSuppressed = (suppressed) => suppressedIssues.push(...suppressed);
     if (checkJs) {
         const created = checkJsFilesInDiff(diffContent, checkJs);
-        const allKnown = [...created].every((f) => checkJs.resolutionSet.has(f));
+        if (created.size > 0) {
+            info(`checkJs: type-checking ${created.size} file(s) of ${patch.filename} (lint cache ${cache ? 'miss' : 'off'}).`);
+        }
+        // A file the scoped program does not root at would be resolvable but
+        // never checked, so it takes the per-patch build too.
+        const allKnown = [...created].every((f) => checkJs.resolutionSet.has(f) && (checkJs.rootScope?.has(f) ?? true));
         if (allKnown) {
             // Slice this patch's findings out of the one queue-wide program.
             lintOptions.precomputedCheckJs = await checkJs.sliceFor(created);

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

@@ -132,12 +132,14 @@ export async function reExportCommand(projectRoot, patches, options) {
     const driftCtx = buildForeignDriftContext(options);
     // Hoisted lint context, one per run: queue context + checkJs
     // program + per-patch result cache, shared across every loop iteration.
-    const lintCtx = await buildReExportLintContext(projectRoot, paths, config, options.noCache === true);
+    // Taken before the context build, so the elapsed time the progress line
+    // reports includes it.
+    const startedAt = Date.now();
+    const lintCtx = await buildReExportLintContext(projectRoot, paths, config, options.noCache === true, new Set(selectedPatches.map((patch) => patch.filename)));
     let reExported = 0;
     const reExportedFilenames = [];
     const failedFilenames = [];
     const progress = spinner('Preparing re-export...');
-    const startedAt = Date.now();
     await withDryRunReExportLock(paths.fireforgeDir, isDryRun, async () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, async () => {
         for (const [index, patch] of selectedPatches.entries()) {
             const assignedScanFiles = scanFilesByPatch?.get(patch.filename);

package/dist/src/commands/rebase/confirm.d.ts

@@ -22,10 +22,21 @@ export interface DirtyEngineConfirmationOptions {
     warningMessage: string;
     promptMessage: string;
     cancelMessage: string;
+    /**
+     * Precomputed dirtiness. A caller that already measured what would be
+     * lost (and may count more than the working tree, such as commits made
+     * on top of the base) passes it here instead of the `hasChanges` probe.
+     */
+    dirty?: boolean;
+    /**
+     * Replaces the generic "Engine has uncommitted changes" opening of the
+     * non-interactive refusal, so the refusal names what would be lost.
+     */
+    refusalDetail?: string;
 }
 /**
  * Checks if the engine has uncommitted changes and prompts for confirmation.
  * Returns true if safe to proceed, false if the user cancelled.
  * Throws in non-interactive mode without --yes.
  */
-export declare function confirmDirtyEngineReset({ engineDir, yes, nonInteractiveCommand, argumentName, warningMessage, promptMessage, cancelMessage, }: DirtyEngineConfirmationOptions): Promise<boolean>;
+export declare function confirmDirtyEngineReset({ engineDir, yes, nonInteractiveCommand, argumentName, warningMessage, promptMessage, cancelMessage, dirty, refusalDetail, }: DirtyEngineConfirmationOptions): Promise<boolean>;

package/dist/src/commands/rebase/confirm.js

@@ -12,13 +12,16 @@ import { cancel, isCancel, warn } from '../../utils/logger.js';
  * Returns true if safe to proceed, false if the user cancelled.
  * Throws in non-interactive mode without --yes.
  */
-export async function confirmDirtyEngineReset({ engineDir, yes, nonInteractiveCommand, argumentName, warningMessage, promptMessage, cancelMessage, }) {
-    if (!(await hasChanges(engineDir)) || yes) {
+export async function confirmDirtyEngineReset({ engineDir, yes, nonInteractiveCommand, argumentName, warningMessage, promptMessage, cancelMessage, dirty, refusalDetail, }) {
+    if (yes || !(dirty ?? (await hasChanges(engineDir)))) {
         return true;
     }
     const isInteractive = stdioIsInteractive();
     if (!isInteractive) {
-        throw new InvalidArgumentError(`Engine has uncommitted changes and interactive confirmation is not available. Run: ${nonInteractiveCommand}`, argumentName);
+        const opening = refusalDetail !== undefined
+            ? `${refusalDetail} Interactive confirmation is not available.`
+            : 'Engine has uncommitted changes and interactive confirmation is not available.';
+        throw new InvalidArgumentError(`${opening} Run: ${nonInteractiveCommand}`, argumentName);
     }
     warn(warningMessage);
     const confirmed = await confirm({

package/dist/src/commands/rebase/index.js

@@ -11,19 +11,20 @@
  * Supports `--continue` (resume after manual fix) and `--abort` (cancel).
  */
 import { Command } from 'commander';
-import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { getProjectPaths, loadConfig, loadState } from '../../core/config.js';
 import { assertEngineGitReady } from '../../core/engine-precondition.js';
 import { clearAppliedFurnaceState } from '../../core/furnace-config.js';
 import { getHead, resetChanges } from '../../core/git.js';
 import { discoverPatches } from '../../core/patch-files.js';
 import { loadPatchesManifest } from '../../core/patch-manifest.js';
 import { getPatchSourceVersion } from '../../core/patch-source-metadata.js';
+import { replayQueueIndexOnly } from '../../core/rebase-dry-run.js';
 import { getRebaseSessionPath, readRebaseSession, saveRebaseSession, } from '../../core/rebase-session.js';
 import { GeneralError } from '../../errors/base.js';
-import { CorruptRebaseSessionError, RebaseSessionExistsError } from '../../errors/rebase.js';
-import { info, intro, outro, spinner } from '../../utils/logger.js';
+import { CorruptRebaseSessionError, RebaseDryRunRejectError, RebaseSessionExistsError, } from '../../errors/rebase.js';
+import { info, intro, outro, spinner, warn } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
-import { parsePositiveIntegerFlag } from '../../utils/validation.js';
+import { compareFirefoxVersions, parsePositiveIntegerFlag } from '../../utils/validation.js';
 import { handleAbort } from './abort.js';
 import { confirmDirtyEngineReset } from './confirm.js';
 import { handleContinue } from './continue.js';
@@ -57,23 +58,51 @@ async function handleFreshStart(projectRoot, options) {
     if (!manifest || manifest.patches.length === 0) {
         throw new GeneralError('No patches found in manifest. Nothing to rebase.');
     }
-    // Determine the "from" version from the patches
-    const patchVersions = new Set(manifest.patches.map((p) => getPatchSourceVersion(p)));
-    const patchProducts = new Set(manifest.patches.map((p) => p.sourceProduct).filter(Boolean));
-    const sortedVersions = [...patchVersions].sort();
+    // Determine the "from" version from the patch stamps. A queue can carry
+    // several: patches re-exported since the last hop are stamped newer than
+    // untouched ones. The oldest stamp is "from", compared semantically (a
+    // lexical sort put 153.10.0esr before 153.2.0esr).
+    const versionCounts = new Map();
+    for (const patch of manifest.patches) {
+        const version = getPatchSourceVersion(patch);
+        versionCounts.set(version, (versionCounts.get(version) ?? 0) + 1);
+    }
+    const sortedVersions = [...versionCounts.keys()].sort(compareFirefoxVersions);
     const fromVersion = sortedVersions[0] ?? currentVersion;
-    const fromProduct = [...patchProducts].sort()[0] ?? config.firefox.product;
-    if (patchVersions.size === 1 && fromVersion === currentVersion) {
+    const fromProduct = manifest.patches.find((p) => getPatchSourceVersion(p) === fromVersion)?.sourceProduct ??
+        config.firefox.product;
+    if (versionCounts.size === 1 && fromVersion === currentVersion) {
         info('All patches already match the current Firefox version. Nothing to rebase.');
         outro('Rebase not needed');
         return;
     }
     info(`Rebasing patches: ${fromVersion} → ${currentVersion}`);
+    if (versionCounts.size > 1) {
+        info(`Patch stamps: ${sortedVersions.map((v) => `${versionCounts.get(v)} at ${v}`).join(', ')}`);
+    }
+    // The rebase replays onto whatever engine/ holds. The pin is the target,
+    // so an engine still on another version means the download step has not
+    // run yet and every verdict below would be against the wrong tree.
+    const engineVersion = (await loadState(projectRoot)).downloadedVersion;
+    if (engineVersion !== undefined && engineVersion !== currentVersion) {
+        warn(`engine/ holds ${engineVersion}, not the pinned target ${currentVersion}. ` +
+            'Run "fireforge download --force" first, or the rebase applies onto the old source.');
+    }
     info(`Found ${manifest.patches.length} patch(es)`);
     info(`Max context-reduction steps (fuzz-like): ${maxFuzz}`);
     if (isDryRun) {
-        info('[dry-run] Would reset engine, apply patches with context reduction, and re-export.');
-        outro('Dry run complete');
+        const patches = await discoverPatches(paths.patches);
+        const replaySpinner = spinner(`Replaying ${patches.length} patch(es) on a private index...`);
+        let replay;
+        try {
+            replay = await replayQueueIndexOnly(paths.engine, patches, maxFuzz);
+            replaySpinner.stop('Replay finished; engine/ untouched');
+        }
+        catch (error) {
+            replaySpinner.error('Replay failed');
+            throw error;
+        }
+        reportDryRunReplay(replay);
         return;
     }
     if (!(await confirmDirtyEngineReset({
@@ -114,6 +143,41 @@ async function handleFreshStart(projectRoot, options) {
     // Run the patch loop
     await runPatchLoop(projectRoot, session, paths, maxFuzz, resolveWaitLockSeconds(options.waitLock));
 }
+/**
+ * Prints one line per patch and a tally, then fails the run when any patch
+ * rejects: a dry run that exits 0 must mean the real rebase would apply the
+ * whole queue.
+ */
+function reportDryRunReplay(replay) {
+    let reduced = 0;
+    const rejected = [];
+    for (const [index, verdict] of replay.verdicts.entries()) {
+        const cascade = replay.firstRejectIndex !== undefined && index > replay.firstRejectIndex
+            ? ' (after an earlier reject; may cascade from it)'
+            : '';
+        switch (verdict.outcome) {
+            case 'clean':
+                info(`  clean            ${verdict.filename}`);
+                break;
+            case 'reduced-context':
+                reduced += 1;
+                info(`  reduced context  ${verdict.filename} (step ${verdict.step}, ${verdict.contextArg})`);
+                break;
+            case 'reject': {
+                rejected.push(verdict.filename);
+                const files = verdict.files.length > 0 ? verdict.files.join(', ') : 'see git output';
+                warn(`  reject           ${verdict.filename}: ${files}${cascade}`);
+                break;
+            }
+        }
+    }
+    const clean = replay.verdicts.length - reduced - rejected.length;
+    info(`[dry-run] ${replay.verdicts.length} patch(es): ${clean} clean, ${reduced} with reduced context, ${rejected.length} rejected.`);
+    if (rejected.length > 0) {
+        throw new RebaseDryRunRejectError(rejected);
+    }
+    outro('Dry run complete: every patch applies');
+}
 // ── Public API ──
 /**
  * Runs the rebase command to orchestrate a Firefox source version upgrade.
@@ -136,7 +200,7 @@ export function registerRebase(program, { getProjectRoot, withErrorHandling }) {
         .description('Semi-automated Firefox source version upgrade — apply patches with drift tolerance and re-export')
         .option('--continue', 'Resume after manually resolving a failed patch')
         .option('--abort', 'Cancel the rebase and restore engine to pre-rebase state')
-        .option('--dry-run', 'Show what would happen without modifying anything')
+        .option('--dry-run', 'Replay the queue onto the engine base commit in a private index and report each patch as clean, reduced-context or reject (exit 6 on any reject); engine/ is not touched')
         .option('--max-fuzz <n>', 'Maximum context-reduction steps for git apply -C<n> (fuzz-like drift tolerance; default: 3)', commanderArgParser((v) => parsePositiveIntegerFlag('--max-fuzz', v)))
         .option('-y, --yes', 'Skip dirty-tree confirmation prompt');
     addWaitLockOption(command).action(withErrorHandling(async (options) => {

package/dist/src/commands/run.js

@@ -8,6 +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 { resolveRunProfile, sweepAbandonedRunProfiles, } from '../core/run-profile.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';
@@ -97,12 +98,38 @@ export async function runCommand(projectRoot, options = {}) {
     await warnIfFurnaceStale(projectRoot);
     // Clean stale profile state to prevent silent startup failures
     await cleanDevProfile(paths.engine);
-    if (options.smokeExit !== undefined) {
-        await runSmokeExit(paths.engine, options);
-        return;
+    // Reclaim temporary profiles a SIGKILLed FireForge could not remove.
+    const swept = await sweepAbandonedRunProfiles();
+    if (swept > 0)
+        verbose(`Removed ${swept} abandoned temporary run profile(s).`);
+    const profile = await resolveRunProfile({
+        profile: options.profile,
+        tempProfile: options.tempProfile,
+        smoke: options.smokeExit !== undefined,
+    });
+    try {
+        if (options.smokeExit !== undefined) {
+            await runSmokeExit(paths.engine, options, profile);
+            return;
+        }
+        info('Launching browser...\n');
+        await runInteractive(paths.engine, options, profile);
+    }
+    finally {
+        await profile.dispose();
     }
-    info('Launching browser...\n');
-    const exitCode = await run(paths.engine, options.headless ? ['--headless'] : []);
+}
+/**
+ * Launches the browser under `mach run` for an interactive session.
+ * @param engineDir - Path to the engine directory
+ * @param options - Run options
+ * @param profile - The profile this run launches with
+ */
+async function runInteractive(engineDir, options, profile) {
+    const exitCode = await run(engineDir, [
+        ...(options.headless ? ['--headless'] : []),
+        ...profile.args,
+    ]);
     // Exit-code whitelist:
     //   0:   clean shutdown
     //   130: SIGINT (Ctrl+C), user-initiated termination
@@ -121,7 +148,7 @@ export async function runCommand(projectRoot, options = {}) {
  * exit contract. The deadline-fires-SIGTERM path is treated as a clean
  * window iff no unallowed errors were observed.
  */
-async function runSmokeExit(engineDir, options) {
+async function runSmokeExit(engineDir, options, profile) {
     // Windows lacks the POSIX process-group primitives --smoke-exit leans on to
     // SIGTERM the whole mach → python → firefox tree. Running through anyway
     // would only kill the top-level wrapper and orphan Firefox content
@@ -194,10 +221,17 @@ async function runSmokeExit(engineDir, options) {
     };
     warnIfHeadedOnDesktop(options.headless === true);
     info(`Launching browser (smoke-exit after ${smokeExit}s)...\n`);
+    if (profile.temporary) {
+        info(`Profile: fresh temporary profile (removed after the run; --profile <path> to use a named one)`);
+    }
+    else if (profile.dir !== undefined) {
+        info(`Profile: ${profile.dir}`);
+    }
     const startedAt = Date.now();
     let result;
     try {
-        result = await runMachSmoke(options.headless ? ['run', '--headless'] : ['run'], engineDir, {
+        const machArgs = ['run', ...(options.headless ? ['--headless'] : []), ...profile.args];
+        result = await runMachSmoke(machArgs, engineDir, {
             smokeTimeoutMs,
             onStdoutLine: (line) => {
                 handleLine('stdout', line);
@@ -358,6 +392,8 @@ export function registerRun(program, { getProjectRoot, withErrorHandling }) {
         .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.')
+        .option('--profile <path>', 'Launch with this profile directory (passed to Firefox as -profile). Left in place after the run. With --smoke-exit it replaces the default fresh profile.')
+        .option('--temp-profile', 'Launch with a fresh temporary profile that is removed when the run ends. The default for --smoke-exit.')
         .action(withErrorHandling(
     // `args` is the variadic positional, not a Commander flag, so it
     // never appears in this object.

package/dist/src/commands/status.js

@@ -6,7 +6,7 @@ import { assertEngineExists } from '../core/engine-precondition.js';
 import { formatEngineSessionLockStatus, readEngineSessionLockStatus, } from '../core/engine-session-lock.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
-import { getUntrackedFilesInDir, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
+import { listUntrackedFilesInDirs, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
 import { renderOwnershipTable } from '../core/ownership-table.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { readProcessCpuSeconds } from '../core/process-cpu-time.js';
@@ -49,9 +49,11 @@ function renderTruncationBanner(truncations) {
 async function expandDirectoryEntries(files, engineDir) {
     const expanded = [];
     const truncations = [];
+    const isCollapsedUntracked = (entry) => entry.file.endsWith('/') && entry.status.includes('?');
+    const untrackedByDir = await listUntrackedFilesInDirs(engineDir, files.filter(isCollapsedUntracked).map((entry) => entry.file));
     for (const entry of files) {
-        if (entry.file.endsWith('/') && entry.status.includes('?')) {
-            const individualFiles = await getUntrackedFilesInDir(engineDir, entry.file);
+        if (isCollapsedUntracked(entry)) {
+            const individualFiles = untrackedByDir.get(entry.file) ?? [];
             const cap = getMaxUntrackedFilesPerDir();
             if (individualFiles.length > cap) {
                 // Recorded once here, reported once by renderTruncationBanner. The

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

@@ -72,7 +72,8 @@ 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, 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('--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())

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 {