@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/harness-helper-pids.js

@@ -1,240 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Teardown reaper for the helper processes one mach test dispatch launched.
- *
- * The mochitest harness starts its httpd (`xpcshell … server.js`), the
- * websocket server, ssltunnel and the websocket/process bridge as plain
- * children, and the browser through mozprocess, which puts it in a process
- * group of its own. It logs each launch as `runtests.py | <what> pid: <n>`.
- * When mach dies before its own cleanup runs (a forwarded SIGTERM, a
- * no-output timeout, a harness crash, a supervisor kill), the helpers do not
- * necessarily die with it: the 2026-09-13 incident left the httpd reparented
- * to launchd at 100% CPU for hours after a gate killed the run at its bound.
- *
- * The exec layer already sweeps the dispatch's process group after close.
- * That reaches every helper that stayed in the group, and nothing else: the
- * browser is in its own group, and a helper that re-grouped itself is not.
- * This module closes that gap in two passes:
- *
- *  - {@link createHelperPidTracker} collects the announced pids from the
- *    streamed output. {@link reapTrackedHarnessPids} runs after mach has
- *    exited; a tracked pid still alive at that point is by definition a
- *    survivor (its parent is gone), so no age heuristic is needed. Before
- *    signalling, each pid is re-read from `ps` and must still be anchored to
- *    the objdir and still look like the thing the harness launched: a pid
- *    recycled onto an unrelated process between the launch line and
- *    teardown is skipped.
- *  - Not every helper is announced. mozserve starts `moz-http2` with
- *    `start_new_session=True` and logs no pid, so it is in neither the
- *    group nor the tracker, and it was the other survivor of the incident.
- *    {@link snapshotObjdirHelpers} records which same-objdir helpers existed
- *    before the dispatch spawned; after mach exits, a helper-shaped process
- *    under THIS checkout's absolute objdir that is not in that baseline and
- *    is reparented (its parent, the harness, is gone) is one this dispatch
- *    launched, and is reaped too. The absolute-path anchor keeps a sibling
- *    checkout's live harness out of it; the baseline keeps a survivor of an
- *    earlier run out of it, so the preflight census's report-only posture
- *    still decides that one's fate.
- */
-import { toError } from '../utils/errors.js';
-import { dispatchCompleteLines } from '../utils/line-dispatch.js';
-import { info, verbose } from '../utils/logger.js';
-import { exec } from '../utils/process.js';
-import { isObjdirAnchored, isPidAlive, matchesHarnessHelper, terminateHarnessProcesses, } from './harness-orphans.js';
-/**
- * The launch announcements in `testing/mochitest/runtests.py`. mozlog puts a
- * timestamp and level in front, so the match is unanchored.
- */
-const HARNESS_PID_LINE = /runtests\.py \| (Server|Websocket server|SSL tunnel|websocket\/process bridge|Application) pid: (\d+)\b/;
-/**
- * Creates a tracker for one dispatch. The two streams are buffered apart so
- * a half-line on one cannot be glued to a half-line on the other.
- */
-export function createHelperPidTracker() {
-    const seen = new Map();
-    const partial = { stdout: '', stderr: '' };
-    const onLine = (line) => {
-        const match = HARNESS_PID_LINE.exec(line);
-        if (!match)
-            return;
-        const pid = Number(match[2]);
-        if (!seen.has(pid)) {
-            seen.set(pid, { pid, kind: match[1] });
-        }
-    };
-    return {
-        feed(stream, chunk) {
-            partial[stream] = dispatchCompleteLines(partial[stream] + chunk, onLine);
-        },
-        tracked() {
-            return [...seen.values()];
-        },
-    };
-}
-/** Log prefix for every line this reaper writes. */
-const TEARDOWN_LABEL = 'harness teardown';
-/**
- * Decides whether a `ps` row still describes the process the harness
- * announced. Exported for fixture tests.
- *
- * The helpers must match the census's helper pattern and the objdir anchor.
- * The browser has no helper-shaped name, so the anchor alone attributes it:
- * its binary lives under the objdir (`<objdir>/dist/<App>.app/…`).
- */
-export function isStillTrackedProcess(tracked, command, objDir) {
-    if (!isObjdirAnchored(command, objDir))
-        return false;
-    return tracked.kind === 'Application' || matchesHarnessHelper(command);
-}
-/** Lists every process. Throws when `ps` is unusable, like the census. */
-async function listAllProcesses() {
-    const result = await exec('ps', ['-axo', 'pid=,ppid=,command='], { timeout: 10000 });
-    if (result.exitCode !== 0)
-        throw new Error(`ps exited ${result.exitCode}`);
-    const rows = [];
-    for (const line of result.stdout.split('\n')) {
-        const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
-        if (match) {
-            rows.push({
-                pid: Number(match[1]),
-                ppid: Number(match[2]),
-                command: (match[3] ?? '').trim(),
-            });
-        }
-    }
-    return rows;
-}
-/**
- * A helper-shaped process under this checkout's objdir. The anchor here is
- * the absolute objdir path alone, on purpose: the census's generic `obj-…`
- * fallback would also match a sibling checkout's live harness.
- */
-function isThisObjdirHelper(command, objDir) {
-    return command.includes(objDir) && matchesHarnessHelper(command);
-}
-/**
- * Records the same-objdir helpers alive before a dispatch spawns anything,
- * so the post-close pass can tell this dispatch's unannounced helpers from
- * an earlier run's survivors. Undefined when `ps` is unusable or no objdir
- * is known; the post-close pass then reaps no unannounced process at all.
- *
- * @param objDir - This project's absolute objdir
- * @returns The pids to leave alone at teardown, or undefined for "no baseline"
- */
-export async function snapshotObjdirHelpers(objDir) {
-    if (process.platform === 'win32' || objDir === undefined)
-        return undefined;
-    try {
-        const rows = await listAllProcesses();
-        return new Set(rows.filter((r) => isThisObjdirHelper(r.command, objDir)).map((r) => r.pid));
-    }
-    catch (error) {
-        verbose(`${TEARDOWN_LABEL}: could not snapshot helpers (${toError(error).message}).`);
-        return undefined;
-    }
-}
-/**
- * Helpers this dispatch launched without announcing them: helper-shaped,
- * under this checkout's objdir, not in the pre-dispatch baseline, and
- * reparented to pid 1 because the harness that started them is gone.
- * Returns nothing when `ps` is unusable rather than guessing. Without a
- * baseline (a snapshot that failed) it also returns nothing: an earlier
- * run's survivor must stay the census's call.
- */
-async function findUnannouncedSurvivors(objDir, baseline, exclude) {
-    if (baseline === undefined)
-        return [];
-    let rows;
-    try {
-        rows = await listAllProcesses();
-    }
-    catch (error) {
-        verbose(`${TEARDOWN_LABEL}: could not scan for unannounced helpers (${toError(error).message}).`);
-        return [];
-    }
-    return rows
-        .filter((r) => r.ppid === 1 &&
-        r.pid !== process.pid &&
-        !baseline.has(r.pid) &&
-        !exclude.has(r.pid) &&
-        isThisObjdirHelper(r.command, objDir))
-        .map((r) => ({ pid: r.pid, kind: 'unannounced', command: r.command }));
-}
-/** Reads `pid command` rows for the given pids. Missing pids simply produce no row. */
-async function listCommands(pids) {
-    const result = await exec('ps', ['-o', 'pid=,command=', '-p', pids.join(',')], {
-        timeout: 10000,
-    });
-    const rows = new Map();
-    // `ps -p` exits 1 when any listed pid is gone, while still printing the
-    // rest, so the exit code is not a failure signal here.
-    for (const line of result.stdout.split('\n')) {
-        const match = /^\s*(\d+)\s+(.+)$/.exec(line);
-        if (match)
-            rows.set(Number(match[1]), (match[2] ?? '').trim());
-    }
-    return rows;
-}
-/**
- * Re-reads the announced pids that are still alive and keeps the ones still
- * attributable to this dispatch. Empty when `ps` is unusable.
- */
-async function survivingTrackedPids(tracked, objDir) {
-    const alive = tracked.filter((entry) => isPidAlive(entry.pid));
-    if (alive.length === 0)
-        return [];
-    let commands;
-    try {
-        commands = await listCommands(alive.map((entry) => entry.pid));
-    }
-    catch (error) {
-        verbose(`${TEARDOWN_LABEL}: could not read ps for tracked helpers (${toError(error).message}); skipping.`);
-        return [];
-    }
-    const targets = [];
-    for (const entry of alive) {
-        const command = commands.get(entry.pid);
-        if (command === undefined)
-            continue; // exited between the probe and ps
-        if (!isStillTrackedProcess(entry, command, objDir)) {
-            verbose(`${TEARDOWN_LABEL}: PID ${entry.pid} (announced as ${entry.kind}) is now "${command.slice(0, 120)}", ` +
-                'not attributable to this run; left alone.');
-            continue;
-        }
-        targets.push(entry);
-    }
-    return targets;
-}
-function describeTarget(target) {
-    const excerpt = target.command === undefined ? '' : ` "${target.command.slice(0, 80)}"`;
-    return `${target.kind} ${target.pid}${excerpt}`;
-}
-/**
- * Terminates every process this dispatch launched that is still alive after
- * mach exited: the announced pids still attributable to the dispatch, and
- * the unannounced same-objdir survivors that appeared since the baseline.
- *
- * Best-effort like the census: a host without `ps` logs at verbose and
- * reaps nothing rather than signalling on the strength of a pid alone.
- *
- * @param tracked - The pids the harness announced during the dispatch
- * @param objDir - This project's absolute objdir, for the anchor rule
- * @param baseline - Same-objdir helpers alive before the dispatch spawned
- *   ({@link snapshotObjdirHelpers}); never touched here. Undefined disables
- *   the unannounced pass entirely
- * @returns How many survivors are confirmed gone afterwards
- */
-export async function reapTrackedHarnessPids(tracked, objDir, baseline) {
-    if (process.platform === 'win32')
-        return 0;
-    const targets = await survivingTrackedPids(tracked, objDir);
-    if (objDir !== undefined) {
-        const known = new Set(tracked.map((t) => t.pid));
-        targets.push(...(await findUnannouncedSurvivors(objDir, baseline, known)));
-    }
-    if (targets.length === 0)
-        return 0;
-    info(`${TEARDOWN_LABEL}: ${targets.length} harness process(es) outlived mach ` +
-        `(${targets.map(describeTarget).join(', ')}); terminating.`);
-    return terminateHarnessProcesses(targets, TEARDOWN_LABEL);
-}

package/dist/src/core/harness-orphans.d.ts

@@ -1,118 +0,0 @@
-/**
- * Preflight census of orphaned test-harness helper processes.
- *
- * Stopping a long mochitest run mid-flight does not necessarily take its
- * helpers with it. A downstream incident left `xpcshell` (the harness
- * httpd, pegged at 100% CPU), `pywebsocket`, `ssltunnel` and `moz-http2`
- * alive for an hour. Every subsequent run crawled: a three-second suite
- * took six minutes of wall clock and audio-start waits timed out. Nothing
- * in FireForge's output connected the slowness to the survivors.
- * The hour was spent mis-attributing it to the change under test.
- *
- * Visibility alone would have collapsed that hour, which is why the census
- * runs by default and the kill does not. Two rules keep it honest:
- *
- *  - The census runs at preflight, before this run spawns anything, so
- *    every matching process must be a survivor of an earlier run. No age
- *    heuristic is needed, and none is used.
- *  - A match must be anchored to a Firefox OBJDIR. `xpcshell` and
- *    `server.js` are far too generic on their own. The same rule
- *    `mochitest-server-port.ts` applies to the httpd holder applies here,
- *    for the same reason. FireForge has no business reporting, let alone
- *    terminating, a process it cannot attribute to the harness.
- *
- * `--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.
- */
-/** One surviving harness helper process. */
-export interface OrphanedHarnessProcess {
-    pid: number;
-    ppid: number;
-    /** Raw `ps` ELAPSED column. */
-    elapsed: string;
-    /** Parsed elapsed seconds since the process started. */
-    elapsedSeconds: number;
-    command: string;
-}
-/**
- * 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. Matching the helper names anywhere in the command
- * line 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 would print a misleading `kill`; under the reap
- * posture it would terminate the operator's shell.
- */
-export declare function matchesHarnessHelper(command: string): boolean;
-/** Objdir provenance: an explicit objdir path, a `obj-…` path segment, or `_tests/`. */
-export declare function isObjdirAnchored(command: string, objDir: string | undefined): boolean;
-/**
- * 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
- */
-export declare function findOrphanedHarnessProcesses(psOutput: string, objDir?: string, selfPid?: number): OrphanedHarnessProcess[];
-/**
- * Renders the census. Names every process with its elapsed time, because
- * "a leftover harness process exists" and "a leftover harness process has
- * been burning a core for 58 minutes" are different findings.
- */
-export declare function formatOrphanReport(orphans: readonly OrphanedHarnessProcess[]): string;
-/**
- * Preflight census of surviving harness helpers, run before a test
- * dispatch.
- *
- * Best-effort: a host without a usable `ps` (Windows, a locked-down
- * container) logs at verbose and runs exactly as before. It never refuses a
- * run. Unlike the server-port preflight, a survivor here degrades
- * performance rather than making the run dispatch against the wrong server,
- * so the correct response is to say so loudly rather than to stop.
- *
- * @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) and how many of them are confirmed gone after reaping (0 in
- *   report-only mode)
- */
-export declare function reportOrphanedHarnessProcesses(objDir: string | undefined, options?: {
-    reap?: boolean;
-}): Promise<OrphanCensus>;
-/** Result of {@link reportOrphanedHarnessProcesses}. */
-export interface OrphanCensus {
-    orphans: OrphanedHarnessProcess[];
-    /** Survivors confirmed gone after the reap. Always 0 in report-only mode. */
-    reaped: number;
-}
-/** Liveness probe: `kill(pid, 0)` throws for a pid that is gone. */
-export declare function isPidAlive(pid: number): boolean;
-/**
- * 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
- */
-export declare function terminateHarnessProcesses(targets: readonly Pick<OrphanedHarnessProcess, 'pid'>[], label: string): Promise<number>;

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

@@ -1,268 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Preflight census of orphaned test-harness helper processes.
- *
- * Stopping a long mochitest run mid-flight does not necessarily take its
- * helpers with it. A downstream incident left `xpcshell` (the harness
- * httpd, pegged at 100% CPU), `pywebsocket`, `ssltunnel` and `moz-http2`
- * alive for an hour. Every subsequent run crawled: a three-second suite
- * took six minutes of wall clock and audio-start waits timed out. Nothing
- * in FireForge's output connected the slowness to the survivors.
- * The hour was spent mis-attributing it to the change under test.
- *
- * Visibility alone would have collapsed that hour, which is why the census
- * runs by default and the kill does not. Two rules keep it honest:
- *
- *  - The census runs at preflight, before this run spawns anything, so
- *    every matching process must be a survivor of an earlier run. No age
- *    heuristic is needed, and none is used.
- *  - A match must be anchored to a Firefox OBJDIR. `xpcshell` and
- *    `server.js` are far too generic on their own. The same rule
- *    `mochitest-server-port.ts` applies to the httpd holder applies here,
- *    for the same reason. FireForge has no business reporting, let alone
- *    terminating, a process it cannot attribute to the harness.
- *
- * `--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';
-import { exec } from '../utils/process.js';
-import { parsePsDuration } from '../utils/ps-duration.js';
-import { sleep } from '../utils/sleep.js';
-/**
- * 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. Matching the helper names anywhere in the command
- * line 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 would print a misleading `kill`; under the reap
- * posture it would terminate the operator's shell.
- */
-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/`. */
-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
- */
-export function findOrphanedHarnessProcesses(psOutput, objDir, selfPid = process.pid) {
-    const rows = [];
-    for (const line of psOutput.split('\n')) {
-        const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/.exec(line);
-        if (!match)
-            continue;
-        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 (!matchesHarnessHelper(command))
-            continue;
-        if (!isObjdirAnchored(command, objDir))
-            continue;
-        const elapsedSeconds = parsePsDuration(elapsed);
-        found.push({
-            pid,
-            ppid,
-            elapsed,
-            elapsedSeconds: Number.isNaN(elapsedSeconds) ? 0 : elapsedSeconds,
-            command,
-        });
-    }
-    return found;
-}
-/** 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;
-/**
- * Renders the census. Names every process with its elapsed time, because
- * "a leftover harness process exists" and "a leftover harness process has
- * been burning a core for 58 minutes" are different findings.
- */
-export function formatOrphanReport(orphans) {
-    const rows = orphans
-        .map((p) => `  PID ${p.pid} (up ${p.elapsed}): ${p.command.slice(0, COMMAND_EXCERPT_LIMIT)}`)
-        .join('\n');
-    const pids = orphans.map((p) => String(p.pid)).join(' ');
-    return (`${orphans.length} harness helper process(es) from an EARLIER run are still alive ` +
-        `(this preflight runs before the current run spawns anything, so none of these belong to ` +
-        `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}", 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() {
-    const result = await exec('ps', ['-axo', 'pid=,ppid=,etime=,command='], { timeout: 10000 });
-    if (result.exitCode !== 0) {
-        throw new Error(`ps exited ${result.exitCode}`);
-    }
-    return result.stdout;
-}
-/**
- * Preflight census of surviving harness helpers, run before a test
- * dispatch.
- *
- * Best-effort: a host without a usable `ps` (Windows, a locked-down
- * container) logs at verbose and runs exactly as before. It never refuses a
- * run. Unlike the server-port preflight, a survivor here degrades
- * performance rather than making the run dispatch against the wrong server,
- * so the correct response is to say so loudly rather than to stop.
- *
- * @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) 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 { orphans: [], reaped: 0 };
-    let psOutput;
-    try {
-        psOutput = await listSystemProcesses();
-    }
-    catch (error) {
-        verbose(`Orphan preflight: could not scan processes (${toError(error).message}); skipping.`);
-        return { orphans: [], reaped: 0 };
-    }
-    const orphans = findOrphanedHarnessProcesses(psOutput, objDir);
-    if (orphans.length === 0) {
-        verbose('Orphan preflight: no surviving harness helper processes.');
-        return { orphans: [], reaped: 0 };
-    }
-    warn(formatOrphanReport(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;
-    }
-}
-/**
- * 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
- */
-export async function terminateHarnessProcesses(targets, label) {
-    let reaped = 0;
-    for (const target of targets) {
-        try {
-            process.kill(target.pid, 'SIGTERM');
-        }
-        catch (error) {
-            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);
-        if (isPidAlive(target.pid)) {
-            try {
-                process.kill(target.pid, 'SIGKILL');
-            }
-            catch (error) {
-                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}.`);
-        }
-    }
-    return reaped;
-}