@hominis/fireforge 0.46.2 → 0.47.1

package/dist/src/core/firefox-cache.js

@@ -242,8 +242,7 @@ async function removeArchivePartFiles(archive, cacheDir) {
             .filter((name) => name.startsWith(partPrefix))
             .map((name) => removeFile(join(cacheDir, name))));
     }
-    catch (error) {
-        void error;
+    catch {
         // Cache dir may not exist yet. That's fine.
     }
 }

package/dist/src/core/furnace-apply-output.d.ts

@@ -13,4 +13,14 @@ type ApplyResultWithActions = ApplyResult & {
  * @param isDryRun - Whether apply was invoked with dryRun=true
  */
 export declare function logApplyResult(result: ApplyResultWithActions, isDryRun: boolean): void;
+/**
+ * Prints the operator-facing apply warnings (patch-owned overwrites) one
+ * per line and returns how many were printed. Shared by `furnace apply`
+ * and the pre-build source → engine sync, so a warning the apply computed
+ * is never dropped on one path and printed on the other.
+ *
+ * @param warnings - `result.warnings` from applyAllComponents
+ * @returns Number of warning lines printed
+ */
+export declare function logApplyWarnings(warnings: readonly string[] | undefined): number;
 export {};

package/dist/src/core/furnace-apply-output.js

@@ -55,12 +55,27 @@ export function logApplyResult(result, isDryRun) {
     // outcome, including the rolled-back branch, where the overwrite
     // happened before the rollback restored it and the operator still needs
     // to know the deployed copy was momentarily replaced.
-    if (!isDryRun && result.warnings !== undefined) {
-        for (const line of result.warnings) {
-            warn(line);
-        }
+    if (!isDryRun) {
+        logApplyWarnings(result.warnings);
     }
     for (const err of result.errors) {
         error(`${err.name} — ${err.error}`);
     }
 }
+/**
+ * Prints the operator-facing apply warnings (patch-owned overwrites) one
+ * per line and returns how many were printed. Shared by `furnace apply`
+ * and the pre-build source → engine sync, so a warning the apply computed
+ * is never dropped on one path and printed on the other.
+ *
+ * @param warnings - `result.warnings` from applyAllComponents
+ * @returns Number of warning lines printed
+ */
+export function logApplyWarnings(warnings) {
+    if (warnings === undefined)
+        return 0;
+    for (const line of warnings) {
+        warn(line);
+    }
+    return warnings.length;
+}

package/dist/src/core/furnace-css-fragments.d.ts

@@ -20,6 +20,13 @@
  */
 import type { ValidationIssue } from '../types/furnace.js';
 export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
+/**
+ * Reads a shared fragment as the exact body an expansion inlines: the
+ * trailing newline is dropped so the fenced block ends on the end marker.
+ * One definition, so every consumer (expansion, validation, the stale
+ * includer probe) compares the same bytes.
+ */
+export declare function readFragmentSource(sharedDir: string, name: string): Promise<string>;
 /** Returns the fragment names referenced by `@fireforge-include` directives. */
 export declare function listFragmentIncludes(css: string): string[];
 /**

package/dist/src/core/furnace-css-fragments.js

@@ -29,6 +29,15 @@ export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
 import { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
 const INCLUDE_PATTERN = /^\s*\/\*\s*@fireforge-include\s+([\w./-]+)\s*\*\/\s*$/;
 const END_INCLUDE_PATTERN = /^\s*\/\*\s*@fireforge-end-include\s+([\w./-]+)\s*\*\/\s*$/;
+/**
+ * Reads a shared fragment as the exact body an expansion inlines: the
+ * trailing newline is dropped so the fenced block ends on the end marker.
+ * One definition, so every consumer (expansion, validation, the stale
+ * includer probe) compares the same bytes.
+ */
+export async function readFragmentSource(sharedDir, name) {
+    return (await readText(join(sharedDir, name))).replace(/\n$/, '');
+}
 /** Returns the fragment names referenced by `@fireforge-include` directives. */
 export function listFragmentIncludes(css) {
     const names = [];
@@ -93,12 +102,12 @@ export async function expandCssFragments(css, sharedDir) {
             throw new FurnaceError(`CSS fragment "${name}" not found in components/${SHARED_FRAGMENTS_DIR}/. ` +
                 'Create the fragment file or remove the @fireforge-include directive.');
         }
-        const content = await readText(fragmentPath);
+        const content = await readFragmentSource(sharedDir, name);
         if (listFragmentIncludes(content).length > 0) {
             throw new FurnaceError(`CSS fragment "${name}" contains an @fireforge-include directive of its own; ` +
                 'nested fragment includes are not supported.');
         }
-        fragments.set(name, content.replace(/\n$/, ''));
+        fragments.set(name, content);
     }
     const out = [];
     for (const line of stripped.split('\n')) {
@@ -226,7 +235,7 @@ export async function validateCssFragments(componentDir, tagName, sharedDir, eng
             }
             if (deployedBodies === null)
                 continue;
-            const fragmentContent = (await readText(fragmentPath)).replace(/\n$/, '');
+            const fragmentContent = await readFragmentSource(sharedDir, include);
             const deployed = deployedBodies.get(include);
             if (deployed === undefined || deployed !== fragmentContent) {
                 issues.push({

package/dist/src/core/furnace-fragment-includers.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Reverse index from shared CSS fragments to the custom components that
+ * include them, plus the staleness probe a targeted `furnace deploy <tag>`
+ * runs over the OTHER includers of the fragments it just refreshed.
+ *
+ * Fragment staleness was only ever a validator finding
+ * (`stale-fragment-expansion` in {@link validateCssFragments}), printed per
+ * includer by `furnace validate` and `deploy --dry-run`. A targeted deploy
+ * validates only the component it was asked for, so the one command that
+ * changes a fragment's deployed state for SOME includers is the one that
+ * never mentioned the rest: after a fragment edit, `deploy <a> <b>` left
+ * every other consumer carrying the old expansion, and nothing said so
+ * until a `grep` over the engine found it.
+ *
+ * Only custom components are indexed. Override components are copied
+ * byte-for-byte and never expand fragments.
+ */
+import type { CustomComponentConfig } from '../types/furnace.js';
+import type { FurnacePaths } from './furnace-config.js';
+/** One includer whose deployed sheets carry a stale expansion. */
+export interface StaleFragmentIncluder {
+    /** Custom component tag. */
+    tag: string;
+    /** Fragments (relative to `components/shared/`) whose expansion is stale. */
+    fragments: string[];
+}
+/**
+ * Maps every fragment name to the custom tags whose workspace sheets
+ * include it.
+ *
+ * @param customDir - `components/custom/` directory
+ * @param custom - The `custom` map from furnace.json
+ */
+export declare function collectFragmentIncluders(customDir: string, custom: Readonly<Record<string, CustomComponentConfig>>): Promise<Map<string, Set<string>>>;
+/**
+ * Finds the other DEPLOYED includers of the fragments `targetTag` includes
+ * whose engine sheets do not carry the current fragment source.
+ *
+ * Only fragments the target includes are considered: a fragment unrelated
+ * to this deploy is not its business. An includer whose engine sheet does
+ * not exist is not deployed and is skipped. A deployed sheet with no
+ * expansion at all counts as stale, the same rule `validateCssFragments`
+ * applies.
+ *
+ * @returns The fragments the target includes, and the stale includers
+ *   (sorted by tag), each naming the fragments that are stale for it
+ */
+export declare function findStaleIncludersOfTargetFragments(args: {
+    targetTag: string;
+    custom: Readonly<Record<string, CustomComponentConfig>>;
+    furnacePaths: FurnacePaths;
+    engineDir: string;
+}): Promise<{
+    fragments: string[];
+    stale: StaleFragmentIncluder[];
+}>;

package/dist/src/core/furnace-fragment-includers.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Reverse index from shared CSS fragments to the custom components that
+ * include them, plus the staleness probe a targeted `furnace deploy <tag>`
+ * runs over the OTHER includers of the fragments it just refreshed.
+ *
+ * Fragment staleness was only ever a validator finding
+ * (`stale-fragment-expansion` in {@link validateCssFragments}), printed per
+ * includer by `furnace validate` and `deploy --dry-run`. A targeted deploy
+ * validates only the component it was asked for, so the one command that
+ * changes a fragment's deployed state for SOME includers is the one that
+ * never mentioned the rest: after a fragment edit, `deploy <a> <b>` left
+ * every other consumer carrying the old expansion, and nothing said so
+ * until a `grep` over the engine found it.
+ *
+ * Only custom components are indexed. Override components are copied
+ * byte-for-byte and never expand fragments.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { extractExpandedFragmentBodies, listFragmentIncludes, readFragmentSource, } from './furnace-css-fragments.js';
+/** Workspace `.css` sheets of one custom component, with their includes. */
+async function listComponentSheetIncludes(componentDir) {
+    if (!(await pathExists(componentDir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(componentDir);
+    }
+    catch {
+        // An unreadable component directory includes nothing. Same degradation
+        // as validateCssFragments: the index must never crash a deploy.
+        return [];
+    }
+    const sheets = [];
+    for (const fileName of entries.sort()) {
+        if (!fileName.endsWith('.css'))
+            continue;
+        const includes = listFragmentIncludes(await readText(join(componentDir, fileName)));
+        if (includes.length > 0)
+            sheets.push({ fileName, includes });
+    }
+    return sheets;
+}
+/**
+ * Maps every fragment name to the custom tags whose workspace sheets
+ * include it.
+ *
+ * @param customDir - `components/custom/` directory
+ * @param custom - The `custom` map from furnace.json
+ */
+export async function collectFragmentIncluders(customDir, custom) {
+    const index = new Map();
+    for (const tag of Object.keys(custom).sort()) {
+        for (const sheet of await listComponentSheetIncludes(join(customDir, tag))) {
+            for (const fragment of sheet.includes) {
+                const tags = index.get(fragment) ?? new Set();
+                tags.add(tag);
+                index.set(fragment, tags);
+            }
+        }
+    }
+    return index;
+}
+/**
+ * Finds the other DEPLOYED includers of the fragments `targetTag` includes
+ * whose engine sheets do not carry the current fragment source.
+ *
+ * Only fragments the target includes are considered: a fragment unrelated
+ * to this deploy is not its business. An includer whose engine sheet does
+ * not exist is not deployed and is skipped. A deployed sheet with no
+ * expansion at all counts as stale, the same rule `validateCssFragments`
+ * applies.
+ *
+ * @returns The fragments the target includes, and the stale includers
+ *   (sorted by tag), each naming the fragments that are stale for it
+ */
+export async function findStaleIncludersOfTargetFragments(args) {
+    const { targetTag, custom, furnacePaths, engineDir } = args;
+    const index = await collectFragmentIncluders(furnacePaths.customDir, custom);
+    const fragments = [...index]
+        .filter(([, tags]) => tags.has(targetTag))
+        .map(([fragment]) => fragment)
+        .sort();
+    if (fragments.length === 0)
+        return { fragments, stale: [] };
+    const targetFragments = new Set(fragments);
+    const sources = new Map();
+    const stale = [];
+    for (const tag of Object.keys(custom).sort()) {
+        if (tag === targetTag)
+            continue;
+        const componentConfig = custom[tag];
+        if (!componentConfig)
+            continue;
+        const engineTargetDir = join(engineDir, componentConfig.targetPath);
+        const staleFragments = new Set();
+        for (const sheet of await listComponentSheetIncludes(join(furnacePaths.customDir, tag))) {
+            const relevant = sheet.includes.filter((f) => targetFragments.has(f));
+            if (relevant.length === 0)
+                continue;
+            const destPath = join(engineTargetDir, sheet.fileName);
+            if (!(await pathExists(destPath)))
+                continue;
+            const bodies = extractExpandedFragmentBodies(await readText(destPath));
+            for (const fragment of relevant) {
+                let source = sources.get(fragment);
+                if (source === undefined) {
+                    source = await readFragmentSource(furnacePaths.sharedDir, fragment);
+                    sources.set(fragment, source);
+                }
+                if (bodies.get(fragment) !== source)
+                    staleFragments.add(fragment);
+            }
+        }
+        if (staleFragments.size > 0) {
+            stale.push({ tag, fragments: [...staleFragments].sort() });
+        }
+    }
+    return { fragments, stale };
+}

package/dist/src/core/git-diff-new-file.js

@@ -31,8 +31,7 @@ function decodeStrictUtf8(bytes) {
     try {
         return strictUtf8.decode(bytes);
     }
-    catch (error) {
-        void error;
+    catch {
         return undefined;
     }
 }

package/dist/src/core/git-file-ops.js

@@ -199,8 +199,7 @@ export async function isBinaryFile(repoDir, filePath) {
             await fh.close();
         }
     }
-    catch (error) {
-        void error;
+    catch {
         return false;
     }
 }

package/dist/src/core/git.js

@@ -340,8 +340,7 @@ async function getLockAgeMs(lockPath) {
         const stats = await stat(lockPath);
         return Math.max(0, Date.now() - stats.mtimeMs);
     }
-    catch (error) {
-        void error;
+    catch {
         return undefined;
     }
 }

package/dist/src/core/harness-helper-pids.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * What the harness said it launched, as it names it in the log line, or
+ * `unannounced` for a survivor found by the post-close objdir scan.
+ */
+export type TrackedHarnessKind = 'Server' | 'Websocket server' | 'SSL tunnel' | 'websocket/process bridge' | 'Application' | 'unannounced';
+/** One helper the harness launched. */
+export interface TrackedHarnessPid {
+    pid: number;
+    kind: TrackedHarnessKind;
+    /** Command line, when the entry came from `ps` rather than a log line. */
+    command?: string;
+}
+/** Which child stream a chunk came from. */
+export type OutputStreamName = 'stdout' | 'stderr';
+/** Collects harness launch announcements from streamed output chunks. */
+export interface HelperPidTracker {
+    /** Feed one chunk. Chunk boundaries need not align with lines. */
+    feed(stream: OutputStreamName, chunk: string): void;
+    /** Every pid announced so far, in announcement order, without duplicates. */
+    tracked(): TrackedHarnessPid[];
+}
+/**
+ * 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 declare function createHelperPidTracker(): HelperPidTracker;
+/**
+ * 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 declare function isStillTrackedProcess(tracked: TrackedHarnessPid, command: string, objDir: string | undefined): boolean;
+/**
+ * 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 declare function snapshotObjdirHelpers(objDir: string | undefined): Promise<Set<number> | undefined>;
+/**
+ * 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 declare function reapTrackedHarnessPids(tracked: readonly TrackedHarnessPid[], objDir: string | undefined, baseline?: ReadonlySet<number>): Promise<number>;

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

@@ -0,0 +1,240 @@
+// 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);
+}