@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/core/mach.js

@@ -12,6 +12,11 @@ import { getPython } from './mach-python.js';
 import { installMachResourceGuard } from './mach-resource-shim.js';
 import { detectHarnessCrashSignature } from './test-harness-crash.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
+// This block is a frozen compatibility list, not a barrel to grow: every name
+// here already had a `from './mach.js'` import when the module was split.
+// New helpers belong in their own sub-module and are imported from it
+// directly — adding to this list pulls the whole sub-module into every suite
+// that mocks `mach.js`.
 export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
@@ -87,7 +92,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
         ...(options.env ? { env: options.env } : {}),
         // Every capture dispatch (test suites, protected builds, package,
         // storybook) runs as a process-group leader and is group-reaped on
-        // exit/abort — see ExecOptions.processGroup (0.37.0 item 9a).
+        // exit/abort — see ExecOptions.processGroup.
         processGroup: true,
         onStdout: (data) => {
             stdout += data;
@@ -148,18 +153,16 @@ export async function bootstrapWithOutput(engineDir) {
     return runMachInheritCapture(['bootstrap', '--application-choice', 'browser'], engineDir);
 }
 /**
- * Prints any matched {@link MachErrorHint} hints for the captured mach output.
- * No-op when nothing matches. Always called before a non-zero exit propagates
- * so the hint sits immediately below the raw mach error in the operator's
- * terminal.
+ * Prints any matched {@link MachErrorHint} hints for the captured mach
+ * output. No-op when nothing matches. Always called before a non-zero exit
+ * propagates so the hint sits immediately below the raw mach error in the
+ * operator's terminal.
  *
  * The scanner is passed the concatenation of stderr AND stdout because mach
  * streams its subcommand output through a timestamp-prefixing wrapper that
- * writes both streams to whatever FD the subprocess chose — in practice,
- * `rustc` errors from `mach build` can land on stdout rather than stderr,
- * and the eval run's Darwin 25 `_CharT` hint pattern matched the captured
- * text but our pre-0.16 code only fed `result.stderr` into the scanner, so
- * the hint never fired.
+ * writes both streams to whatever FD the subprocess chose — `rustc` errors
+ * from `mach build` can land on stdout, so feeding only `result.stderr`
+ * silently loses the match.
  */
 function surfaceMachErrorHints(result) {
     const combined = `${result.stderr}\n${result.stdout}`;
@@ -179,21 +182,20 @@ function surfaceMachErrorHints(result) {
 const DEFAULT_BUILD_CRASH_RETRIES = 2;
 /**
  * The single protected path every FireForge mach build dispatch routes
- * through (field report: `build --ui` and the pre-test `--build` step died
- * on the resource-monitor crash family while plain `build` survived,
- * because only some entries were protected and retry budgets differed):
+ * through — `build`, `build --ui`, and the pre-test `--build` step all use
+ * it, so no entry point is left unprotected with a different retry budget:
  *
  *  1. installs the resource-monitor degrade guard IN the mach virtualenvs
- *     (plus the PYTHONPATH fallback) — re-installed before every attempt,
- *     so a venv materialized by a crashed first attempt is guarded on the
- *     next one instead of every retry dying on the same wedged state;
+ *     (plus the PYTHONPATH fallback) — re-installed before every attempt, so
+ *     a venv materialized by a crashed first attempt is guarded on the next
+ *     one instead of every retry dying on the same wedged state;
  *  2. spawns a fresh mach process per attempt;
  *  3. retries ONLY the recognized harness-crash family (resource monitor /
  *     psutil startup tracebacks) up to the uniform budget — an ordinary
  *     compile error is never retried.
  *
- * The protected path never runs `mach configure`, never clobbers, and
- * never widens the requested build kind — a `faster` dispatch retries as
+ * The protected path never runs `mach configure`, never clobbers, and never
+ * widens the requested build kind — a `faster` dispatch retries as
  * `mach build faster`, so it cannot invalidate more of the objdir than the
  * command the operator asked for.
  */
@@ -249,32 +251,27 @@ export async function buildUI(engineDir) {
     return runProtectedMachBuild('faster', engineDir);
 }
 /**
- * Runs an operation while holding a sidecar build lock keyed on the
- * project root. Concurrent `fireforge build` / `fireforge build --ui`
- * invocations against the same tree serialise instead of racing through
- * the mach obj-dir.
+ * Runs an operation while holding a sidecar build lock keyed on the project
+ * root. Concurrent `fireforge build` / `fireforge build --ui` invocations
+ * against the same tree serialise instead of racing through the mach
+ * obj-dir.
  *
- * Motivating case (2026-04-21 eval): a `fireforge build --ui` run
- * kicked off while a full `fireforge build` was still in flight against
- * the same engine tree accepted the command and handed off to `mach
- * build faster`, which failed almost immediately with `No rule to make
- * target 'XUL'`. The real problem is that the first build had not yet
- * materialised the full backend; the operator was left staring at a
- * low-level make error with no link to the actual cause (a concurrent
- * build in flight). The lock intercepts the second invocation before
- * it touches mach, and the refusal message names the PID currently
- * holding the lock so the operator can decide whether to wait or
- * investigate a hung process.
+ * Without it, a `build --ui` started while a full `build` is still in flight
+ * hands off to `mach build faster` and fails almost immediately with `No
+ * rule to make target 'XUL'` — the real problem being that the first build
+ * has not yet materialised the full backend, with nothing in the low-level
+ * make error pointing at the concurrent run. The lock intercepts the second
+ * invocation before it touches mach, and the refusal names the PID holding
+ * the lock so the operator can decide whether to wait or investigate.
  *
  * Stale-lock recovery: the lock stores the owner PID; a crashed build
- * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but
- * not the owning process, and `withFileLock` removes the lock on the
- * next attempt when `process.kill(pid, 0)` shows the owner is gone.
+ * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but not the
+ * owning process, and `withFileLock` removes the lock on the next attempt
+ * when `process.kill(pid, 0)` shows the owner is gone.
  *
- * The project-root variant is the right granularity: a single machine
- * may have several FireForge projects side by side, and nothing says
- * they cannot build in parallel. The lock serialises *within* one
- * project, not across unrelated ones.
+ * The project-root variant is the right granularity: a single machine may
+ * have several FireForge projects side by side and nothing says they cannot
+ * build in parallel. The lock serialises *within* one project.
  *
  * Returns whatever the inner operation returns.
  */
@@ -356,18 +353,17 @@ export async function watch(engineDir) {
 }
 /**
  * Runs mach watch while preserving stdin and capturing emitted output.
+ *
+ * `env` is threaded through so the caller can prepend the resolved watchman
+ * directory to PATH in a way mach inherits: `fireforge watch` can locate
+ * `watchman` via `which`, but the mach subprocess spawns with the parent's
+ * PATH only — on macOS that typically omits `/opt/homebrew/bin`, so
+ * `mach watch` fails at the `watch-project` subscription step.
+ *
  * @param engineDir - Path to the engine directory
- * @param options - Optional environment overrides merged into the mach subprocess env
+ * @param options - Optional environment overrides merged into the mach
+ *   subprocess env
  * @returns Captured output and exit code
- *
- * 2026-04-24 eval Finding 12: the pre-0.18.1 shape accepted no options
- * and so never forwarded the detected watchman path into the mach
- * subprocess env. `fireforge watch` could locate `watchman` via PATH
- * (the probe's `which` succeeded) but the mach subprocess spawned with
- * the parent's PATH only — on macOS that typically omits
- * `/opt/homebrew/bin`, so `mach watch` failed at the `watch-project`
- * subscription step. Accepting `env` here lets the caller prepend the
- * resolved watchman directory to PATH in a way mach inherits.
  */
 export async function watchWithOutput(engineDir, options = {}) {
     return runMachInheritCapture(['watch'], engineDir, options.env ? { env: options.env } : {});
@@ -385,6 +381,9 @@ export async function test(engineDir, testPaths = [], args = []) {
 /**
  * Runs mach test while capturing streamed output for better diagnostics.
  *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param testPaths - Test paths to pass to `mach test`; empty runs the default set
+ * @param args - Extra `mach test` arguments appended after the paths
  * @param env - Optional extra environment variables for the mach process
  *   (merged over `process.env` by the exec layer). Used by
  *   `fireforge test --perf-samples` to publish the artifact-path contract.
@@ -401,7 +400,7 @@ export async function testWithOutput(engineDir, testPaths = [], args = [], env)
  * capturing output. Unlike the generic `mach test`, the suite-specific
  * commands degrade a broken mozlog resource monitor to a warning instead of
  * crashing at startup, so `fireforge test` dispatches single-suite runs here
- * to stay resilient to the host psutil failure (field report E1).
+ * to stay resilient to the host psutil failure.
  *
  * Signature mirrors {@link testWithOutput} so the two are interchangeable in
  * the dispatch path.

package/dist/src/core/marionette-port.d.ts

@@ -31,8 +31,24 @@ export interface MarionettePortProbeResult {
 export interface RunningBundleProcess {
     pid: number;
     commandLine: string;
+    /**
+     * Elapsed wall-clock seconds since the process started, from `ps
+     * etime=`. `NaN` when the field was absent or unparseable — callers must
+     * omit the clause rather than print a zero, because "started 0s ago" is
+     * exactly the wrong attribution for a peer session's long-lived browser.
+     */
+    elapsedSeconds: number;
 }
-/** Pure parser kept exported so platform output handling is regression-testable. */
+/**
+ * Pure parser kept exported so platform output handling is
+ * regression-testable.
+ *
+ * Reads `pid etime args` where the middle field is a `ps` duration. The
+ * elapsed field is parsed OPTIMISTICALLY: a listing produced without
+ * `etime=` still parses, with the duration reported as `NaN` and the whole
+ * second field folded back into the command line, so a caller that lost the
+ * column degrades to the old behaviour instead of dropping the process.
+ */
 export declare function parseProcessList(stdout: string, launchableBinary: string): RunningBundleProcess[];
 /**
  * Refuses a browser-harness launch when this objdir's app is already alive,
@@ -43,6 +59,25 @@ export declare function parseProcessList(stdout: string, launchableBinary: strin
 export declare function ensureLaunchableBrowserNotRunning(launchableBinary: string, options?: {
     killStaleBrowser?: boolean;
 }): Promise<void>;
+/**
+ * Builds the refusal for a running objdir browser.
+ *
+ * Reports the EVIDENCE rather than a bare PID: the elapsed time and the
+ * command line are what let an operator on a shared checkout decide whose
+ * process it is, without reconstructing PID ancestry by hand. A downstream
+ * fork hit exactly this — the message named a PID belonging to a peer
+ * session's live browser and offered a flag that would have killed a
+ * multi-hour evaluation run.
+ *
+ * So `--kill-stale-marionette` is offered ONLY for a marionette-driven
+ * browser. For a bare launch the message says what it found and stops:
+ * FireForge cannot tell a dead run's orphan from someone's live window, and
+ * the flag is the right MANUAL clear once ownership is verified, never an
+ * automatic one.
+ *
+ * Exported for direct unit testing.
+ */
+export declare function describeRunningBundleRefusal(holder: RunningBundleProcess): string;
 /**
  * Probes whether the Marionette port is currently bound by a
  * listener. The probe is best-effort: missing tooling returns

package/dist/src/core/marionette-port.js

@@ -2,38 +2,33 @@
 /**
  * Marionette port probe.
  *
- * Gecko's Marionette control channel binds `127.0.0.1:2828` when a
- * Firefox / ForgeFresh / fork instance is launched with
- * `-marionette`. The `fireforge test` harness spawns the browser with
- * that flag, so any test run needs the port to be free at start.
+ * Gecko's Marionette control channel binds `127.0.0.1:2828` when a browser
+ * is launched with `-marionette`. The `fireforge test` harness spawns the
+ * browser with that flag, so any test run needs the port free at start.
  *
- * Motivating case (2026-04-21 eval, Finding #20): an interrupted
- * `fireforge test --headless` left an orphan
- * `ForgeFresh.app/Contents/MacOS/forgefresh -marionette` process
- * listening on 2828 with parent PID 1. The next `fireforge test` run
- * — in a *different* FireForge project — failed immediately with a
- * Marionette bind error, and FireForge's generic "re-run build" hint
- * did not mention the stale listener. The probe in this module runs
- * before every test launch, detects when the port is held, and —
- * when the holder is a browser process (by command-line `-marionette`
- * flag or by basename matching a known browser binary) — throws a
- * targeted `GeneralError` naming the PID and the exact `kill` command
- * to run.
+ * An interrupted `fireforge test` can leave an orphan browser process
+ * listening on 2828 with parent PID 1, and the next test run — possibly in a
+ * *different* FireForge project — then fails with a bare Marionette bind
+ * error. This probe runs before every test launch, detects when the port is
+ * held, and — when the holder is a browser process (by command-line
+ * `-marionette` flag or by basename matching a known browser binary) —
+ * throws a targeted `GeneralError` naming the PID and the exact `kill`
+ * command to run.
  *
  * Cross-platform implementation:
  *   - POSIX (macOS / Linux): `lsof -i tcp:<port> -P -n -sTCP:LISTEN`
- *   - Windows: `Get-NetTCPConnection` via PowerShell, then
- *     `Get-Process` to resolve the PID into a command line.
+ *   - Windows: `Get-NetTCPConnection` via PowerShell, then `Get-Process` to
+ *     resolve the PID into a command line.
  *
- * Both paths tolerate missing tooling: if `lsof` / PowerShell isn't
- * installed, the probe returns `{ inUse: false }` rather than failing
- * the test run itself — the probe is a best-effort friendliness
- * check, not a prerequisite.
+ * Both paths tolerate missing tooling: if `lsof` / PowerShell is not
+ * installed the probe returns `{ inUse: false }` rather than failing the
+ * test run — it is a best-effort friendliness check, not a prerequisite.
  */
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { getPlatform } from '../utils/platform.js';
 import { exec } from '../utils/process.js';
+import { formatPsDuration, parsePsDuration } from '../utils/ps-duration.js';
 /** Default Marionette control port set by `-marionette`. */
 export const DEFAULT_MARIONETTE_PORT = 2828;
 /** Basenames of browser binaries that ship a Marionette listener. */
@@ -57,7 +52,8 @@ async function findRunningBundleProcesses(launchableBinary) {
         if (process.platform === 'win32') {
             const escapedPath = launchableBinary.replaceAll("'", "''");
             const script = `Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -eq '${escapedPath}' } | ` +
-                'ForEach-Object { Write-Output ("$($_.ProcessId) $($_.CommandLine)") }';
+                'ForEach-Object { Write-Output ("$($_.ProcessId) ' +
+                '$([int]((Get-Date) - $_.CreationDate).TotalSeconds)s $($_.CommandLine)") }';
             const result = await exec('powershell.exe', [
                 '-NoProfile',
                 '-NonInteractive',
@@ -66,24 +62,44 @@ async function findRunningBundleProcesses(launchableBinary) {
             ]);
             return parseProcessList(result.stdout, launchableBinary);
         }
-        const result = await exec('ps', ['-axo', 'pid=,args=']);
+        // `etime=` is what makes the refusal attributable on a shared checkout:
+        // a browser that started as YOUR run was finishing is not yours.
+        const result = await exec('ps', ['-axo', 'pid=,etime=,args=']);
         return parseProcessList(result.stdout, launchableBinary);
     }
     catch {
         return [];
     }
 }
-/** Pure parser kept exported so platform output handling is regression-testable. */
+/**
+ * Pure parser kept exported so platform output handling is
+ * regression-testable.
+ *
+ * Reads `pid etime args` where the middle field is a `ps` duration. The
+ * elapsed field is parsed OPTIMISTICALLY: a listing produced without
+ * `etime=` still parses, with the duration reported as `NaN` and the whole
+ * second field folded back into the command line, so a caller that lost the
+ * column degrades to the old behaviour instead of dropping the process.
+ */
 export function parseProcessList(stdout, launchableBinary) {
     const matches = [];
     for (const line of stdout.split(/\r?\n/)) {
-        const match = /^\s*(\d+)\s+(.+)$/.exec(line);
-        if (!match?.[1] || !match[2]?.includes(launchableBinary))
+        const match = /^\s*(\d+)\s+(\S+)\s+(.+)$/.exec(line);
+        if (!match?.[1])
             continue;
         const pid = Number(match[1]);
         if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid)
             continue;
-        matches.push({ pid, commandLine: match[2] });
+        const maybeElapsed = match[2] ?? '';
+        const elapsedSeconds = parsePsDuration(maybeElapsed);
+        // Without an `etime` column the second field is the head of the command
+        // line, so put it back rather than swallowing it.
+        const commandLine = Number.isNaN(elapsedSeconds)
+            ? `${maybeElapsed} ${match[3] ?? ''}`.trim()
+            : (match[3] ?? '');
+        if (!commandLine.includes(launchableBinary))
+            continue;
+        matches.push({ pid, commandLine, elapsedSeconds });
     }
     return matches;
 }
@@ -120,12 +136,61 @@ export async function ensureLaunchableBrowserNotRunning(launchableBinary, option
             throw new GeneralError(`A browser from this objdir is still running (PID ${holder.pid}), but FireForge could not terminate it: ${toError(error).message}`);
         }
     }
+    throw new GeneralError(describeRunningBundleRefusal(holder));
+}
+/**
+ * True when the process was launched BY a test harness — its command line
+ * carries `-marionette` (the control channel every `fireforge test` browser
+ * is started with) or a harness `-profile`.
+ *
+ * This is the distinction the refusal turns on. The objdir-bundle probe
+ * matches any process running this project's binary, which on a shared
+ * checkout includes a peer session's LIVE browser and a developer's own
+ * interactive one. Only a marionette-driven browser is safely
+ * attributable to an interrupted run.
+ */
+function isHarnessDrivenBrowser(commandLine) {
+    return /\s-marionette(?:\s|$)/.test(commandLine) || /\s-profile(?:\s|=)/.test(commandLine);
+}
+/**
+ * Builds the refusal for a running objdir browser.
+ *
+ * Reports the EVIDENCE rather than a bare PID: the elapsed time and the
+ * command line are what let an operator on a shared checkout decide whose
+ * process it is, without reconstructing PID ancestry by hand. A downstream
+ * fork hit exactly this — the message named a PID belonging to a peer
+ * session's live browser and offered a flag that would have killed a
+ * multi-hour evaluation run.
+ *
+ * So `--kill-stale-marionette` is offered ONLY for a marionette-driven
+ * browser. For a bare launch the message says what it found and stops:
+ * FireForge cannot tell a dead run's orphan from someone's live window, and
+ * the flag is the right MANUAL clear once ownership is verified, never an
+ * automatic one.
+ *
+ * Exported for direct unit testing.
+ */
+export function describeRunningBundleRefusal(holder) {
     const killHint = process.platform === 'win32'
         ? `Stop-Process -Id ${holder.pid} -Force`
         : `kill ${holder.pid}  # or "kill -9 ${holder.pid}" if it doesn't exit`;
-    throw new GeneralError(`A browser from this project's objdir is already running (PID ${holder.pid}). ` +
-        'It may have survived a previously timed-out or interrupted "fireforge test" run and can wedge the next headed launch. ' +
-        `Stop it with "${killHint}", or retry with "--kill-stale-marionette".`);
+    const elapsed = formatPsDuration(holder.elapsedSeconds);
+    const age = elapsed !== undefined ? ` running for ${elapsed}` : '';
+    const harnessDriven = isHarnessDrivenBrowser(holder.commandLine);
+    const evidence = `A browser from this project's objdir is already running (PID ${holder.pid}${age}).\n` +
+        `  command: ${holder.commandLine}\n`;
+    if (harnessDriven) {
+        return (evidence +
+            '  This one carries harness arguments (-marionette/-profile), so it is very likely an orphan ' +
+            'of a timed-out or interrupted "fireforge test" run, and it can wedge the next headed launch.\n' +
+            `  Stop it with "${killHint}", or retry with "--kill-stale-marionette".`);
+    }
+    return (evidence +
+        '  This one carries NO harness arguments (-marionette/-profile), so it is not a test browser — ' +
+        "it is more likely a developer's own window, or another session sharing this checkout.\n" +
+        '  "--kill-stale-marionette" is deliberately NOT suggested here: FireForge cannot tell an orphan ' +
+        "from someone else's live browser. Confirm the owner (start time above, and the command line), " +
+        `then stop it yourself with "${killHint}" if it is in fact yours.`);
 }
 /**
  * Returns `true` when the holder's command basename or command-line

package/dist/src/core/marionette-preflight.d.ts

@@ -46,17 +46,13 @@ export declare function runMarionettePreflight(engineDir: string, options?: Mari
 export declare function reportMarionettePreflight(result: MarionettePreflightResult): void;
 /**
  * Formats the PASS/FAIL banner as a plain string for direct
- * `process.stdout.write` use — bypasses the clack logger entirely so
- * operators running `fireforge test --doctor` under a non-TTY (pipe,
- * CI, `tee`-wrapped capture) always see the final line even when the
- * clack renderer swallows trailing log output just before process exit.
- *
- * 2026-04-24 eval Finding 7 reproducibly captured only the `"Running
- * marionette preflight..."` intro and no PASS line at all — the
- * `success()` + `outro()` + direct `stdout.write` belt-and-suspenders
- * we used to ship still lost the summary under some non-TTY flush
- * races. Returning the raw string here lets the caller compose a single
- * authoritative write without any clack layer between the probe and
- * the captured log.
+ * `process.stdout.write` use — bypassing the clack logger entirely so
+ * operators running `fireforge test --doctor` under a non-TTY (pipe, CI,
+ * `tee`-wrapped capture) always see the final line. Clack's renderer can
+ * swallow trailing log output just before process exit, and a
+ * `success()` + `outro()` + direct-write combination still loses the
+ * summary under some non-TTY flush races. Returning the raw string lets the
+ * caller compose a single authoritative write with no clack layer between
+ * the probe and the captured log.
  */
 export declare function formatMarionettePreflightLine(result: MarionettePreflightResult): string;

package/dist/src/core/marionette-preflight.js

@@ -19,7 +19,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, warn } from '../utils/logger.js';
+import { info, verbose, warn } from '../utils/logger.js';
+import { installGracefulShutdownForwarder, trackChildClosure } from '../utils/process.js';
+import { killProcessTree, sweepProcessGroup } from '../utils/process-group.js';
 import { ensureMach } from './mach.js';
 import { getPython } from './mach-python.js';
 /** Marionette's default TCP port when the browser is launched with `--marionette`. */
@@ -69,7 +71,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
     const elapsed = () => Date.now() - startedAt;
     // Layer 1: engine directory exists.
     if (!(await pathExists(engineDir))) {
-        return fail('engine-present', 'Engine directory not found — run "fireforge download" first.', elapsed());
+        return fail('engine-present', 'Engine directory not found. Run "fireforge download" first.', elapsed());
     }
     // Layer 2: mach binary resolves in the engine.
     try {
@@ -96,6 +98,19 @@ export async function runMarionettePreflight(engineDir, options = {}) {
     }
     let child;
     let stderrTail = '';
+    // Shutdown contract for a child spawned outside the exec layer.
+    //
+    // This is the repo's one legitimate raw `spawn`: the preflight needs the
+    // live `ChildProcess` mid-run (`hasChildExited` gates the socket poll),
+    // returns while the browser is still running, and aborts on a TCP byte
+    // rather than on a deadline — none of which any wrapper in utils/process
+    // can express. What it does NOT get to skip is the contract every wrapper
+    // applies to a detached child: register the closure so the bin signal
+    // handler waits for it, and forward the parent's SIGINT/SIGTERM to the
+    // group. Without both, Ctrl+C during `fireforge test --doctor` left the
+    // whole mach → Firefox tree running.
+    let closure;
+    let forwarder;
     try {
         // Layer 5: browser spawns and does not crash within the settle window.
         try {
@@ -113,13 +128,12 @@ export async function runMarionettePreflight(engineDir, options = {}) {
                 stdio: ['ignore', 'ignore', 'pipe'],
                 // `detached: true` puts the child in a new process group so we can
                 // signal it and every descendant (Firefox, its helpers) via
-                // `process.kill(-pid, …)` in the finally block. Without this, the
+                // `process.kill(-pid, …)` in the finally block. Without it, the
                 // child is Python running mach; a SIGTERM kills Python but the
                 // Firefox grandchild inherits the stderr pipe FD and keeps Node's
-                // event loop alive even after the preflight PASS log. The symptom
-                // is `fireforge test --doctor` printing `Marionette preflight:
-                // PASS` and then hanging indefinitely in `uv__io_poll` — see the
-                // eval finding.
+                // event loop alive even after the preflight PASS log, so
+                // `fireforge test --doctor` prints `Marionette preflight: PASS`
+                // and then hangs indefinitely in `uv__io_poll`.
                 detached: true,
             });
         }
@@ -127,6 +141,10 @@ export async function runMarionettePreflight(engineDir, options = {}) {
             return fail('browser-spawns', `Could not spawn mach run: ${toError(error).message}`, elapsed());
         }
         const spawnedChild = child;
+        closure = trackChildClosure();
+        forwarder = installGracefulShutdownForwarder(spawnedChild, 500, (signal) => {
+            killProcessGroup(spawnedChild, signal);
+        });
         child.stderr?.on('data', (data) => {
             const chunk = data.toString();
             stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_LIMIT);
@@ -164,29 +182,60 @@ export async function runMarionettePreflight(engineDir, options = {}) {
             `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
     }
     finally {
-        if (child && !hasChildExited(child)) {
-            killProcessGroup(child, 'SIGTERM');
-            // Small escalation: if the child doesn't honour SIGTERM quickly, SIGKILL
-            // so we don't leave a ghost mach process around after a failed probe.
-            await delay(500);
-            if (!hasChildExited(child)) {
-                killProcessGroup(child, 'SIGKILL');
-            }
+        await teardownPreflightChild(child, forwarder, closure, profileDir);
+    }
+}
+/**
+ * Deterministic teardown for the preflight's detached child.
+ *
+ * Extracted from {@link runMarionettePreflight} so the probe body stays
+ * inside the per-function complexity budget alongside the shutdown contract
+ * (forwarder + closure tracking + group sweep) and the kill escalation.
+ *
+ * @param child - The spawned child, if the spawn got that far
+ * @param forwarder - Parent-signal forwarder to dispose
+ * @param closure - Closure registration to settle
+ * @param profileDir - Temporary profile directory to remove
+ */
+async function teardownPreflightChild(child, forwarder, closure, profileDir) {
+    // Dispose before killing: the forwarder's own escalation timer must not
+    // race the deterministic teardown below.
+    forwarder?.dispose();
+    const groupPid = child?.pid;
+    if (child && !hasChildExited(child)) {
+        killProcessGroup(child, 'SIGTERM');
+        // Small escalation: if the child doesn't honour SIGTERM quickly, SIGKILL
+        // so we don't leave a ghost mach process around after a failed probe.
+        await delay(500);
+        if (!hasChildExited(child)) {
+            killProcessGroup(child, 'SIGKILL');
         }
-        // Destroy the stderr pipe explicitly. Firefox (a grandchild of the Python
-        // mach wrapper we spawned) can inherit and hold the stderr FD even after
-        // its direct parent exits — until the pipe closes, Node's readable
-        // stream stays attached and `uv__io_poll` keeps the event loop alive.
-        // `destroy()` closes the local end regardless, so `fireforge test
-        // --doctor` exits cleanly after a passing preflight.
-        child?.stderr?.destroy();
+    }
+    // Reap anything that outlived the group signal. The file's own comments
+    // worry about exactly this — Firefox grandchildren surviving the Python
+    // mach wrapper — and every exec-layer wrapper sweeps for it.
+    if (groupPid !== undefined && process.platform !== 'win32') {
         try {
-            await rm(profileDir, { recursive: true, force: true });
+            await sweepProcessGroup(groupPid);
         }
         catch (error) {
-            warn(`Could not clean up marionette preflight profile: ${toError(error).message}`);
+            verbose(`Marionette preflight group sweep failed: ${toError(error).message}`);
         }
     }
+    closure?.settle();
+    // Destroy the stderr pipe explicitly. Firefox (a grandchild of the Python
+    // mach wrapper we spawned) can inherit and hold the stderr FD even after
+    // its direct parent exits — until the pipe closes, Node's readable
+    // stream stays attached and `uv__io_poll` keeps the event loop alive.
+    // `destroy()` closes the local end regardless, so `fireforge test
+    // --doctor` exits cleanly after a passing preflight.
+    child?.stderr?.destroy();
+    try {
+        await rm(profileDir, { recursive: true, force: true });
+    }
+    catch (error) {
+        warn(`Could not clean up marionette preflight profile: ${toError(error).message}`);
+    }
 }
 /**
  * Sends `signal` to the child's whole process group when possible, falling
@@ -195,22 +244,11 @@ export async function runMarionettePreflight(engineDir, options = {}) {
  * `kill(-pid, …)` is not a supported kernel primitive).
  */
 function killProcessGroup(child, signal) {
-    if (child.pid !== undefined && process.platform !== 'win32') {
-        try {
-            process.kill(-child.pid, signal);
-            return;
-        }
-        catch {
-            // ESRCH / EPERM — fall through to the narrow kill below so we at
-            // least signal the direct child.
-        }
-    }
-    try {
-        child.kill(signal);
-    }
-    catch {
-        // Already exited — nothing to do.
-    }
+    // Delegates to the shared implementation, which is a strict superset of
+    // the hand-rolled one this replaced: same POSIX `kill(-pid)` with the same
+    // fall-through to a direct `child.kill`, plus a Windows `taskkill /T /F`
+    // branch and an already-exited early return.
+    killProcessTree(child, signal, process.platform !== 'win32');
 }
 function fail(layer, message, durationMs) {
     return {
@@ -291,18 +329,14 @@ export function reportMarionettePreflight(result) {
 }
 /**
  * Formats the PASS/FAIL banner as a plain string for direct
- * `process.stdout.write` use — bypasses the clack logger entirely so
- * operators running `fireforge test --doctor` under a non-TTY (pipe,
- * CI, `tee`-wrapped capture) always see the final line even when the
- * clack renderer swallows trailing log output just before process exit.
- *
- * 2026-04-24 eval Finding 7 reproducibly captured only the `"Running
- * marionette preflight..."` intro and no PASS line at all — the
- * `success()` + `outro()` + direct `stdout.write` belt-and-suspenders
- * we used to ship still lost the summary under some non-TTY flush
- * races. Returning the raw string here lets the caller compose a single
- * authoritative write without any clack layer between the probe and
- * the captured log.
+ * `process.stdout.write` use — bypassing the clack logger entirely so
+ * operators running `fireforge test --doctor` under a non-TTY (pipe, CI,
+ * `tee`-wrapped capture) always see the final line. Clack's renderer can
+ * swallow trailing log output just before process exit, and a
+ * `success()` + `outro()` + direct-write combination still loses the
+ * summary under some non-TTY flush races. Returning the raw string lets the
+ * caller compose a single authoritative write with no clack layer between
+ * the probe and the captured log.
  */
 export function formatMarionettePreflightLine(result) {
     const status = result.ok ? 'PASS' : 'FAIL';