@hominis/fireforge 0.47.0 → 0.47.1

package/dist/src/core/harness-orphans.js

@@ -22,10 +22,15 @@
  *    for the same reason. FireForge has no business reporting, let alone
  *    terminating, a process it cannot attribute to the harness.
  *
- * `--reap-orphans` opts into termination. Without it the census is
- * report-only, exactly like the `Orphaned harness workers` doctor check
- * (which covers a different shape: reparented Python multiprocessing
- * workers, matched on PPID 1 and accumulated CPU time).
+ * `--reap-orphans` (or `test.reapOrphans: "reap"` in `fireforge.json`) opts
+ * into termination. Without it the census is report-only, exactly like the
+ * `Orphaned harness workers` doctor check (which covers a different shape:
+ * reparented Python multiprocessing workers, matched on PPID 1 and
+ * accumulated CPU time).
+ *
+ * The anchoring and termination primitives are exported for the teardown
+ * reaper in `harness-helper-pids.ts`, which applies the same objdir rule to
+ * the helpers THIS run launched, after mach has exited.
  */
 import { toError } from '../utils/errors.js';
 import { info, verbose, warn } from '../utils/logger.js';
@@ -33,42 +38,91 @@ import { exec } from '../utils/process.js';
 import { parsePsDuration } from '../utils/ps-duration.js';
 import { sleep } from '../utils/sleep.js';
 /**
- * Harness helper executables/scripts. Every one of these is started by the
- * mochitest/xpcshell harness and is expected to die with it. None of them
- * is a thing a developer runs by hand.
+ * Harness helper binaries, matched on the executable's basename. Every one
+ * of these is started by the mochitest/xpcshell harness and is expected to
+ * die with it. None of them is a thing a developer runs by hand.
+ */
+const HELPER_BINARY = /^(?:xpcshell|ssltunnel|http3server|moz-http2)(?:\.exe)?$/;
+/** Interpreters the harness runs its helper scripts under. */
+const HELPER_INTERPRETER = /^(?:python[\d.]*|Python|node)(?:\.exe)?$/;
+/** Harness helper scripts, matched on the interpreter's script argument. */
+const HELPER_SCRIPT = /(?:^|[/\\])(?:pywebsocket\w*\.py|websocket_server\.py|websocketprocessbridge\.py|moz-http2\.js|http2_server\.js|httpd\.js|server\.js|runtests\.py|runxpcshelltests\.py)$/;
+function basename(token) {
+    const cut = Math.max(token.lastIndexOf('/'), token.lastIndexOf('\\'));
+    return cut === -1 ? token : token.slice(cut + 1);
+}
+/**
+ * True when `command` IS a harness helper: its executable is a helper
+ * binary, or an interpreter whose first argument is a helper script.
+ *
+ * Structural on purpose. An earlier version matched the helper names
+ * anywhere in the command line, which is right for the httpd (`xpcshell -g
+ * … -f …/server.js`) and wrong for everything that merely mentions such a
+ * path: an editor opened on `server.js`, a shell whose command text quotes
+ * it, a `grep` over the objdir. Report-only, that printed a misleading
+ * `kill`; under the reap posture it terminated the operator's shell.
  */
-const HARNESS_HELPER_PATTERN = /\b(?:xpcshell|pywebsocket\w*|websocket_server\.py|ssltunnel|moz-http2|http2_server|httpd\.js|server\.js|runtests\.py|runxpcshelltests\.py)\b/;
+export function matchesHarnessHelper(command) {
+    const [exe, first] = command.trim().split(/\s+/);
+    if (exe === undefined)
+        return false;
+    if (HELPER_BINARY.test(basename(exe)))
+        return true;
+    if (first === undefined || !HELPER_INTERPRETER.test(basename(exe)))
+        return false;
+    return HELPER_SCRIPT.test(first);
+}
 /** Objdir provenance: an explicit objdir path, a `obj-…` path segment, or `_tests/`. */
-function isObjdirAnchored(command, objDir) {
+export function isObjdirAnchored(command, objDir) {
     if (objDir !== undefined && objDir.length > 0 && command.includes(objDir))
         return true;
     if (/[/\\]obj-[^/\\\s]*[/\\]/.test(command))
         return true;
     return /[/\\]_tests[/\\]/.test(command);
 }
+/** Pids of `selfPid` and every ancestor of it, as far as the listing reaches. */
+function ancestorsOf(rows, selfPid) {
+    const parentOf = new Map(rows.map((r) => [r.pid, r.ppid]));
+    const chain = new Set();
+    let cursor = selfPid;
+    while (cursor !== undefined && cursor > 0 && !chain.has(cursor)) {
+        chain.add(cursor);
+        cursor = parentOf.get(cursor);
+    }
+    return chain;
+}
 /**
  * Scans `ps -axo pid=,ppid=,etime=,command=` output for surviving harness
  * helpers. Pure, so it is fixture-testable without spawning anything.
  *
+ * FireForge's own process, its direct children and its ancestors are never
+ * candidates: the terminal shell FireForge runs under can carry the helper
+ * paths in its own command text, and must never be offered for a kill.
+ *
  * @param psOutput - Raw `ps` output
  * @param objDir - Absolute objdir of this project, when known. Widens the
  *   provenance test beyond the generic `obj-…` path segment
- * @param selfPid - This process's pid, excluded so FireForge cannot report
- *   itself
+ * @param selfPid - This process's pid
  */
 export function findOrphanedHarnessProcesses(psOutput, objDir, selfPid = process.pid) {
-    const found = [];
+    const rows = [];
     for (const line of psOutput.split('\n')) {
         const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/.exec(line);
         if (!match)
             continue;
-        const pid = Number(match[1]);
-        const ppid = Number(match[2]);
-        const elapsed = match[3] ?? '';
-        const command = (match[4] ?? '').trim();
-        if (pid === selfPid || ppid === selfPid)
+        rows.push({
+            pid: Number(match[1]),
+            ppid: Number(match[2]),
+            elapsed: match[3] ?? '',
+            command: (match[4] ?? '').trim(),
+        });
+    }
+    const excluded = ancestorsOf(rows, selfPid);
+    const found = [];
+    for (const { pid, ppid, elapsed, command } of rows) {
+        if (excluded.has(pid) || ppid === selfPid)
             continue;
-        if (!HARNESS_HELPER_PATTERN.test(command))
+        if (!matchesHarnessHelper(command))
             continue;
         if (!isObjdirAnchored(command, objDir))
             continue;
@@ -85,6 +139,8 @@ export function findOrphanedHarnessProcesses(psOutput, objDir, selfPid = process
 }
 /** Grace period between SIGTERM and SIGKILL when reaping. */
 const REAP_GRACE_MS = 500;
+/** Wait after SIGKILL before the final liveness probe, so the parent can collect the exit. */
+const KILL_SETTLE_MS = 200;
 /** Longest command excerpt carried into the report line. */
 const COMMAND_EXCERPT_LIMIT = 160;
 /**
@@ -102,7 +158,8 @@ export function formatOrphanReport(orphans) {
         `it):\n${rows}\n` +
         `Survivors like these slow every later run without appearing anywhere in its output — a ` +
         `three-second suite taking minutes of wall clock is the usual symptom. Terminate them with ` +
-        `"kill ${pids}", or re-run with --reap-orphans to have FireForge do it.`);
+        `"kill ${pids}", re-run with --reap-orphans, or set test.reapOrphans to "reap" in ` +
+        `fireforge.json to have FireForge do it at every preflight.`);
 }
 /** Thin exec wrapper for the process listing (tests mock `exec` instead). */
 async function listSystemProcesses() {
@@ -125,63 +182,87 @@ async function listSystemProcesses() {
  * @param objDir - Absolute objdir of this project, when known
  * @param options - `reap` terminates each recognized survivor (SIGTERM,
  *   then SIGKILL for anything that stays)
- * @returns The census, empty when nothing was found or nothing could be probed
+ * @returns The census (empty when nothing was found or nothing could be
+ *   probed) and how many of them are confirmed gone after reaping (0 in
+ *   report-only mode)
  */
 export async function reportOrphanedHarnessProcesses(objDir, options = {}) {
     if (process.platform === 'win32')
-        return [];
+        return { orphans: [], reaped: 0 };
     let psOutput;
     try {
         psOutput = await listSystemProcesses();
     }
     catch (error) {
         verbose(`Orphan preflight: could not scan processes (${toError(error).message}); skipping.`);
-        return [];
+        return { orphans: [], reaped: 0 };
     }
     const orphans = findOrphanedHarnessProcesses(psOutput, objDir);
     if (orphans.length === 0) {
         verbose('Orphan preflight: no surviving harness helper processes.');
-        return [];
+        return { orphans: [], reaped: 0 };
     }
     warn(formatOrphanReport(orphans));
-    if (options.reap === true) {
-        await reapOrphanedHarnessProcesses(orphans);
+    const reaped = options.reap === true ? await terminateHarnessProcesses(orphans, '--reap-orphans') : 0;
+    return { orphans, reaped };
+}
+/** Liveness probe: `kill(pid, 0)` throws for a pid that is gone. */
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
     }
-    return orphans;
 }
 /**
- * Terminates each census entry: SIGTERM first, then SIGKILL for anything
- * still alive. Failures are reported, never thrown. A process that exited
- * between the census and the signal is the common case rather than an error.
+ * Terminates each entry: SIGTERM first, then SIGKILL for anything still
+ * alive after the grace period. Failures are reported, never thrown. A
+ * process that exited between the listing and the signal is the common case
+ * rather than an error.
+ *
+ * @param targets - Processes to terminate, already attributed to the harness
+ *   by the caller (objdir anchor rule)
+ * @param label - Prefix for the log lines, naming which path is reaping
+ *   (`--reap-orphans` at preflight, `teardown` after mach exits)
+ * @returns How many targets are confirmed gone afterwards
  */
-async function reapOrphanedHarnessProcesses(orphans) {
-    for (const orphan of orphans) {
+export async function terminateHarnessProcesses(targets, label) {
+    let reaped = 0;
+    for (const target of targets) {
         try {
-            process.kill(orphan.pid, 'SIGTERM');
+            process.kill(target.pid, 'SIGTERM');
         }
         catch (error) {
-            verbose(`--reap-orphans: SIGTERM to ${orphan.pid} failed (${toError(error).message}).`);
+            verbose(`${label}: SIGTERM to ${target.pid} failed (${toError(error).message}).`);
             continue;
         }
         // Grace period before escalating: the httpd shape in the field
         // incident ignored SIGTERM while spinning, but an ordinary helper exits
         // promptly and must not be SIGKILLed for being slow by a millisecond.
         await sleep(REAP_GRACE_MS);
-        let alive = true;
-        try {
-            process.kill(orphan.pid, 0);
-        }
-        catch {
-            alive = false;
-        }
-        if (alive) {
+        if (isPidAlive(target.pid)) {
             try {
-                process.kill(orphan.pid, 'SIGKILL');
+                process.kill(target.pid, 'SIGKILL');
             }
             catch (error) {
-                verbose(`--reap-orphans: SIGKILL to ${orphan.pid} failed (${toError(error).message}).`);
+                verbose(`${label}: SIGKILL to ${target.pid} failed (${toError(error).message}).`);
             }
+            // A killed process answers kill(0) until its parent (launchd, for a
+            // reparented survivor) has collected it, which takes a moment.
+            await sleep(KILL_SETTLE_MS);
+        }
+        // Counted only when the probe agrees: the verdict line will carry this
+        // number, and a SIGKILL that was sent is not the same as a process that
+        // is gone.
+        if (isPidAlive(target.pid)) {
+            warn(`${label}: PID ${target.pid} is still alive after SIGKILL; inspect it by hand.`);
+        }
+        else {
+            reaped += 1;
+            info(`${label}: terminated PID ${target.pid}.`);
         }
-        info(`--reap-orphans: terminated PID ${orphan.pid}.`);
     }
+    return reaped;
 }

package/dist/src/core/mach.d.ts

@@ -37,6 +37,16 @@ export interface MachOptions {
      * layer's {@link ExecOptions.envUnset}.
      */
     envUnset?: readonly string[];
+    /**
+     * Observes every raw output chunk of a capture dispatch, on either stream,
+     * before the echo filter. The test dispatchers feed the harness helper-pid
+     * tracker from it. Capture-only, like `annotateKnownTeardownNoise`.
+     */
+    onOutputChunk?: (stream: 'stdout' | 'stderr', chunk: string) => void;
+    /** Exec-layer hook, see {@link ProcessGroupOptions.onProcessGroup}. Capture-only. */
+    onProcessGroup?: (pgid: number) => void;
+    /** Exec-layer hook, see {@link ProcessGroupOptions.postCloseSweep}. Capture-only. */
+    postCloseSweep?: () => Promise<void>;
 }
 /**
  * Result of running a mach command while capturing streamed output.
@@ -247,6 +257,12 @@ export interface MachTestSuiteOptions {
      * markers that quiet it. See {@link CODING_AGENT_ENV_MARKERS}.
      */
     fullOutput?: boolean | undefined;
+    /**
+     * Harness teardown hooks (`fireforge test`): the helper-pid tracker feed,
+     * the process-group announcement, and the post-close reap of the helpers
+     * the harness launched. See {@link MachOptions}.
+     */
+    teardown?: Pick<MachOptions, 'onOutputChunk' | 'onProcessGroup' | 'postCloseSweep'> | undefined;
 }
 /**
  * Runs one mach test command (`mach test` / `mach xpcshell-test` / `mach

package/dist/src/core/mach.js

@@ -96,7 +96,10 @@ export async function runMachCapture(args, engineDir, options = {}) {
         // storybook) runs as a process-group leader and is group-reaped on
         // exit/abort. See ExecOptions.processGroup.
         processGroup: true,
+        ...(options.onProcessGroup ? { onProcessGroup: options.onProcessGroup } : {}),
+        ...(options.postCloseSweep ? { postCloseSweep: options.postCloseSweep } : {}),
         onStdout: (data) => {
+            options.onOutputChunk?.('stdout', data);
             stdout += data;
             if (stdout.length > CAPTURE_TAIL_LIMIT) {
                 stdout = stdout.slice(-CAPTURE_TAIL_LIMIT);
@@ -110,6 +113,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
             process.stdout.write(stdoutFilter ? stdoutFilter.transform(data) : data);
         },
         onStderr: (data) => {
+            options.onOutputChunk?.('stderr', data);
             stderr += data;
             if (stderr.length > CAPTURE_TAIL_LIMIT) {
                 stderr = stderr.slice(-CAPTURE_TAIL_LIMIT);
@@ -407,12 +411,13 @@ function testVerbosityEnvUnset(fullOutput) {
  * @param options - Engine checkout, test paths, extra args, env, verbosity
  */
 export async function runMachTestSuite(kind, options) {
-    const { engineDir, testPaths = [], args = [], env, fullOutput } = options;
+    const { engineDir, testPaths = [], args = [], env, fullOutput, teardown } = options;
     const guard = await installMachResourceGuard(engineDir);
     const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture([kind, ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
         ...(envUnset ? { envUnset } : {}),
+        ...teardown,
         annotateKnownTeardownNoise: true,
     });
 }

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

@@ -154,9 +154,13 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         // (missing dylib, wrong CPU arch, corrupt profile) before the socket
         // poll swallows the full overall budget waiting for bytes that will
         // never come.
+        // Ref'd (sleep's default), like every wait in this probe: the browser is a
+        // detached child, so once it has exited nothing else holds the event
+        // loop, and an unref'd wait here let Node exit 0 mid-preflight with no
+        // `Marionette preflight:` line and no verdict at all.
         const settleDeadline = Math.min(spawnSettleMs, Math.max(0, timeoutMs - elapsed()));
         if (settleDeadline > 0) {
-            await sleep(settleDeadline, { unref: true });
+            await sleep(settleDeadline);
         }
         if (hasChildExited(spawnedChild)) {
             return fail('browser-spawns', `Browser process exited during spawn (exit code ${spawnedChild.exitCode}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
@@ -207,7 +211,9 @@ async function teardownPreflightChild(child, forwarder, closure, profileDir) {
         killProcessTree(child, 'SIGTERM', process.platform !== 'win32');
         // 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 sleep(500, { unref: true });
+        // Ref'd: an unref'd wait between a SIGTERM and its escalation lets Node
+        // exit mid-grace and skip the escalation.
+        await sleep(500);
         if (!hasChildExited(child)) {
             killProcessTree(child, 'SIGKILL', process.platform !== 'win32');
         }
@@ -255,7 +261,7 @@ async function waitForMarionetteSocket(port, connectFn, keepTrying) {
         if (result.ok) {
             return { ok: true };
         }
-        await sleep(400, { unref: true });
+        await sleep(400);
     }
     return { ok: false };
 }

package/dist/src/core/parent-exit-watchdog.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Detects the death of FireForge's own parent while a harness runs.
+ *
+ * A supervisor that SIGKILLs the process above `fireforge test` (the
+ * 2026-09-13 incident: a gate killed its `npm` step at the 15-minute bound)
+ * signals nothing below it. FireForge is not told; its stdout pipe merely
+ * breaks, and the broken-pipe handler swallows EPIPE on purpose so `| head`
+ * works. The mach tree it spawned as a separate process group keeps running
+ * under nobody's supervision, and the httpd in that tree spun at 100% CPU
+ * for hours.
+ *
+ * SIGKILL cannot be caught, but reparenting can be observed: once the parent
+ * is gone, `process.ppid` changes (to launchd/init, or to a subreaper). This
+ * watchdog polls for that while a dispatch is in flight and fires once. It
+ * does not decide what to do about it; the test command tears down the
+ * harness tree and ends the run.
+ *
+ * Off on Windows: `process.ppid` is not refreshed there after the parent
+ * exits, and there is no process group to signal in response anyway.
+ */
+/** Options for {@link startParentExitWatchdog}. */
+export interface ParentExitWatchdogOptions {
+    /** Probe interval, default {@link DEFAULT_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Called exactly once, the first time the parent is seen to be gone. */
+    onParentExit: (info: {
+        originalPpid: number;
+        currentPpid: number;
+    }) => void;
+    /**
+     * Reads the current parent pid; default `process.ppid`. Injectable because
+     * `process.ppid` cannot be stubbed on every Node line: redefining the
+     * property is honoured on Node 26 and silently ignored on Node 22, so a
+     * test that stubs it passes on one and never observes a reparent on the
+     * other.
+     */
+    readPpid?: () => number;
+}
+/** Handle for a running watchdog. */
+export interface ParentExitWatchdog {
+    /** Stops probing. Idempotent. A stopped watchdog never fires. */
+    stop(): void;
+}
+/**
+ * True once any watchdog in this process has seen the parent die. The
+ * dispatch loop reads it to end the run instead of classifying the killed
+ * harness as a crash and retrying it under a parent that no longer exists.
+ */
+export declare function parentExited(): boolean;
+/**
+ * Forgets an observed parent exit.
+ *
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
+ */
+export declare function resetParentExitForTests(): void;
+/**
+ * Starts probing `process.ppid`. The timer is unref'd so the watchdog can
+ * never be the thing keeping FireForge alive; while a child runs, the child
+ * does that.
+ */
+export declare function startParentExitWatchdog(options: ParentExitWatchdogOptions): ParentExitWatchdog;

package/dist/src/core/parent-exit-watchdog.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Detects the death of FireForge's own parent while a harness runs.
+ *
+ * A supervisor that SIGKILLs the process above `fireforge test` (the
+ * 2026-09-13 incident: a gate killed its `npm` step at the 15-minute bound)
+ * signals nothing below it. FireForge is not told; its stdout pipe merely
+ * breaks, and the broken-pipe handler swallows EPIPE on purpose so `| head`
+ * works. The mach tree it spawned as a separate process group keeps running
+ * under nobody's supervision, and the httpd in that tree spun at 100% CPU
+ * for hours.
+ *
+ * SIGKILL cannot be caught, but reparenting can be observed: once the parent
+ * is gone, `process.ppid` changes (to launchd/init, or to a subreaper). This
+ * watchdog polls for that while a dispatch is in flight and fires once. It
+ * does not decide what to do about it; the test command tears down the
+ * harness tree and ends the run.
+ *
+ * Off on Windows: `process.ppid` is not refreshed there after the parent
+ * exits, and there is no process group to signal in response anyway.
+ */
+/** How often the parent is probed. Cheap (one syscall), so a short interval is fine. */
+const DEFAULT_INTERVAL_MS = 2000;
+let parentExitObserved = false;
+/**
+ * True once any watchdog in this process has seen the parent die. The
+ * dispatch loop reads it to end the run instead of classifying the killed
+ * harness as a crash and retrying it under a parent that no longer exists.
+ */
+export function parentExited() {
+    return parentExitObserved;
+}
+/**
+ * Forgets an observed parent exit.
+ *
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
+ */
+export function resetParentExitForTests() {
+    parentExitObserved = false;
+}
+/**
+ * Starts probing `process.ppid`. The timer is unref'd so the watchdog can
+ * never be the thing keeping FireForge alive; while a child runs, the child
+ * does that.
+ */
+export function startParentExitWatchdog(options) {
+    if (process.platform === 'win32') {
+        return { stop: () => undefined };
+    }
+    const readPpid = options.readPpid ?? (() => process.ppid);
+    const originalPpid = readPpid();
+    let timer = setInterval(() => {
+        const currentPpid = readPpid();
+        if (currentPpid === originalPpid)
+            return;
+        stop();
+        parentExitObserved = true;
+        options.onParentExit({ originalPpid, currentPpid });
+    }, options.intervalMs ?? DEFAULT_INTERVAL_MS);
+    timer.unref();
+    function stop() {
+        if (timer === undefined)
+            return;
+        clearInterval(timer);
+        timer = undefined;
+    }
+    return { stop };
+}

package/dist/src/types/commands/options.d.ts

@@ -612,9 +612,19 @@ export interface TestOptions extends EngineLockWaitable {
      * project's objdir. The census itself runs on every test dispatch and is
      * report-only. This flag opts into the kill. Survivors slow later runs
      * without appearing in their output, so the visibility is the default and
-     * the termination is the choice.
+     * the termination is the choice. `test.reapOrphans: "reap"` in
+     * `fireforge.json` makes it the repo's default.
      */
     reapOrphans?: boolean;
+    /**
+     * Path to write the harness process-group id to, rewritten on every mach
+     * spawn (each retry attempt and shard) and removed when the run ends under
+     * FireForge's control. mach runs as its own process-group leader, so a
+     * supervisor's kill of its own group never reaches it; a supervisor that
+     * had to SIGKILL FireForge takes the whole harness tree afterwards with
+     * `kill -- -<pgid>`. The file survives exactly that case, by design.
+     */
+    pgidFile?: string;
     /** Permit tests against packageable engine edits newer than the last successful build. */
     allowStaleBuild?: boolean;
     /**

package/dist/src/types/config.d.ts

@@ -47,6 +47,13 @@ export interface TestConfig {
     canaryPath?: string;
     /** Short no-output ceiling for `fireforge test --canary`, in seconds. */
     canaryTimeoutSeconds?: number;
+    /**
+     * What the preflight orphan census does with a harness helper that
+     * survived an earlier run in this objdir: `report` (default) names it and
+     * proceeds; `reap` terminates it and stamps `orphans-reaped=<n>` on the
+     * verdict line. `--reap-orphans` is the per-invocation equivalent.
+     */
+    reapOrphans?: 'report' | 'reap';
 }
 /** A single external executable required by a project-specific toolchain. */
 export interface ExternalToolRequirement {

package/dist/src/utils/process-group.d.ts

@@ -32,8 +32,12 @@ interface ProcessGroupSurvivor {
  * about anything that still refuses to die. POSIX only (no-op on win32).
  * The only kill target is `-pgid`, never anything outside the group.
  * A healthy run costs exactly one `pgrep`.
+ *
+ * `context` names why the group is being reaped in the warning; the default
+ * is the post-close sweep. The parent-exit watchdog passes its own, because
+ * there the group is still running when the sweep begins.
  */
-export declare function sweepProcessGroup(pgid: number, graceMs?: number): Promise<{
+export declare function sweepProcessGroup(pgid: number, graceMs?: number, context?: string): Promise<{
     survivors: ProcessGroupSurvivor[];
 }>;
 export {};

package/dist/src/utils/process-group.js

@@ -130,15 +130,19 @@ function describeSurvivors(list) {
  * about anything that still refuses to die. POSIX only (no-op on win32).
  * The only kill target is `-pgid`, never anything outside the group.
  * A healthy run costs exactly one `pgrep`.
+ *
+ * `context` names why the group is being reaped in the warning; the default
+ * is the post-close sweep. The parent-exit watchdog passes its own, because
+ * there the group is still running when the sweep begins.
  */
-export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
+export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS, context = 'after exit') {
     if (process.platform === 'win32')
         return { survivors: [] };
     const survivors = await listGroupSurvivors(pgid);
     if (survivors.length === 0)
         return { survivors };
-    warn(`Harness process group ${pgid} left ${survivors.length} surviving ` +
-        `process(es) after exit — reaping the group. ${describeSurvivors(survivors)}`);
+    warn(`Harness process group ${pgid} has ${survivors.length} live ` +
+        `process(es) ${context} — reaping the group. ${describeSurvivors(survivors)}`);
     try {
         process.kill(-pgid, 'SIGTERM');
     }

package/dist/src/utils/process.d.ts

@@ -85,6 +85,24 @@ export interface ProcessGroupOptions {
      * whenever this option is set.
      */
     processGroup?: boolean;
+    /**
+     * Receives the process-group id (the detached child's pid) right after a
+     * group-leader spawn. Lets a caller expose the group to a supervisor that
+     * cannot signal FireForge itself gracefully (`fireforge test --pgid-file`),
+     * or hold it for a teardown of its own. Not called when no group was
+     * created (`processGroup` unset, or win32).
+     */
+    onProcessGroup?: (pgid: number) => void;
+    /**
+     * Extra teardown the caller owns, awaited after the child's `close` and
+     * the post-run group sweep, before the child's closure settles. Placed
+     * here rather than after the wrapper resolves so the bin signal handler's
+     * `waitForActiveChildShutdown` covers it too: a reap that ran after the
+     * wrapper resolved would race `process.exit` on a forwarded SIGTERM. Must
+     * never throw; a rejection is swallowed so it cannot mask the child's
+     * result.
+     */
+    postCloseSweep?: () => Promise<void>;
 }
 /**
  * Executes a command and returns its output.

package/dist/src/utils/process.js

@@ -154,6 +154,8 @@ async function spawnTracked(spec) {
             detached: usesProcessGroup,
         });
         const groupPid = usesProcessGroup ? child.pid : undefined;
+        if (groupPid !== undefined)
+            options.onProcessGroup?.(groupPid);
         spec.attach?.(child);
         // Group-aware kills route to the whole tree. A non-group child is killed
         // directly by the forwarder's own `child.kill`.
@@ -183,11 +185,21 @@ async function spawnTracked(spec) {
                 closure.settle();
                 resolve(spec.result(code, signal));
             };
+            // Group sweep first (it takes the helpers that stayed in the group),
+            // then the caller's own sweep (the ones that did not), then settle.
+            const callerSweep = () => {
+                const sweep = options.postCloseSweep;
+                if (sweep === undefined) {
+                    finish();
+                    return;
+                }
+                sweep().then(finish, finish);
+            };
             if (groupPid !== undefined) {
-                sweepProcessGroup(groupPid).then(finish, finish);
+                sweepProcessGroup(groupPid).then(callerSweep, callerSweep);
             }
             else {
-                finish();
+                callerSweep();
             }
         });
     });

package/docs/configuration.md

@@ -113,7 +113,13 @@ gaps does not move a patch out of the band its category owns.
 ## `test`
 
 `test.canaryPath` and `test.canaryTimeoutSeconds` supply the defaults for
-`fireforge test --canary`. See [`testing.md`](testing.md).
+`fireforge test --canary`.
+
+`test.reapOrphans` is `"report"` (default) or `"reap"`: what the preflight
+census does with a harness helper that survived an earlier run in this
+objdir. `"reap"` terminates it and stamps `orphans-reaped=<n>` on the verdict
+line; `--reap-orphans` does the same for one invocation. The objdir anchor
+rule is the same under both. See [`testing.md`](testing.md).
 
 ## `buildAudit`