@hominis/fireforge 0.46.2 → 0.47.1

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

@@ -21,10 +21,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.
  */
 /** One surviving harness helper process. */
 export interface OrphanedHarnessProcess {
@@ -36,15 +41,32 @@ export interface OrphanedHarnessProcess {
     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. 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.
+ */
+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, excluded so FireForge cannot report
- *   itself
+ * @param selfPid - This process's pid
  */
 export declare function findOrphanedHarnessProcesses(psOutput: string, objDir?: string, selfPid?: number): OrphanedHarnessProcess[];
 /**
@@ -66,8 +88,31 @@ export declare function formatOrphanReport(orphans: readonly OrphanedHarnessProc
  * @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 declare function reportOrphanedHarnessProcesses(objDir: string | undefined, options?: {
     reap?: boolean;
-}): Promise<OrphanedHarnessProcess[]>;
+}): 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

@@ -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-build-artifacts.js

@@ -140,8 +140,7 @@ export async function hasBuildArtifacts(engineDir) {
         }
         return { exists: true, objDir: selectedObjDir };
     }
-    catch (error) {
-        void error;
+    catch {
         return { exists: false };
     }
 }

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/mochitest-server-port.d.ts

@@ -12,6 +12,36 @@ export declare const DEFAULT_MOCHITEST_SERVER_PORT = 8888;
  * harness's httpd has.
  */
 export declare function isMochitestServerHolder(holder: MarionettePortHolder): boolean;
+/**
+ * How a recognized harness httpd relates to the checkout about to run.
+ *
+ * `this-checkout` is debris from one of OUR interrupted runs and may be
+ * offered for termination. `foreign-checkout` is the same harness serving a
+ * LIVE run in a sibling worktree: `server.js` plus objdir provenance is
+ * exactly what a peer's in-flight suite looks like, and the only thing
+ * separating the two is whose objdir the command line points into.
+ * `unrecognized` is not the harness at all.
+ */
+export type MochitestServerHolderClass = 'this-checkout' | 'foreign-checkout' | 'unrecognized';
+/**
+ * Classifies the holder against this project's engine directory. Every
+ * absolute path on the command line is tested with {@link isPathInsideRoot}
+ * (a token test, not a substring test, so `/a/hominis/engine` does not claim
+ * a holder living under `/a/hominis-2/engine`). On POSIX the command line is
+ * the full `ps -o args=` output, so the objdir path is always present for a
+ * harness httpd; a holder whose paths all lie elsewhere belongs to another
+ * checkout.
+ *
+ * @param holder - The listener found on the port
+ * @param engineDir - Absolute engine directory of THIS project
+ */
+export declare function classifyMochitestServerHolder(holder: MarionettePortHolder, engineDir: string): MochitestServerHolderClass;
+/**
+ * The objdir a foreign holder is serving from, for the refusal text: the
+ * first absolute command-line token with an `obj-…` segment, cut at that
+ * segment. Falls back to the first absolute token, then to a placeholder.
+ */
+export declare function describeHolderObjdir(commandLine: string): string;
 /**
  * Refuses a mochitest dispatch when the harness's server port is held. It
  * terminates the holder first only for a recognized stale harness httpd,
@@ -26,10 +56,19 @@ export declare function isMochitestServerHolder(holder: MarionettePortHolder): b
  * Best effort: {@link probeMarionettePort} reports an
  * unprobeable port as free, so a host without `lsof` runs exactly as before.
  *
+ * A recognized httpd from ANOTHER checkout is a refusal and never a kill
+ * either, flag or no flag: it is a peer's live suite, not our debris. The
+ * browser-side probe draws the same line for a bare launch it cannot
+ * attribute; this one can attribute, because the objdir is on the command
+ * line, so it names the other checkout instead of offering `kill -9`.
+ *
  * @param port - Port to probe (default {@link DEFAULT_MOCHITEST_SERVER_PORT})
- * @param options - `killStaleServer` opts into terminating a recognized holder
+ * @param options - `engineDir` is this project's absolute engine directory,
+ *   the ownership boundary; `killStaleServer` opts into terminating a holder
+ *   recognized as THIS checkout's debris
  */
-export declare function ensureMochitestServerPortAvailable(port?: number, options?: {
+export declare function ensureMochitestServerPortAvailable(port: number | undefined, options: {
+    engineDir: string;
     killStaleServer?: boolean;
 }): Promise<void>;
 /**
@@ -37,6 +76,6 @@ export declare function ensureMochitestServerPortAvailable(port?: number, option
  *
  * @param port - The probed port
  * @param holder - The listener found on it
- * @param recognized - Whether it is the harness's own `server.js`
+ * @param holderClass - Whose harness `server.js` it is, if it is one at all
  */
-export declare function describeMochitestServerRefusal(port: number, holder: MarionettePortHolder, recognized: boolean): string;
+export declare function describeMochitestServerRefusal(port: number, holder: MarionettePortHolder, holderClass: MochitestServerHolderClass): string;

package/dist/src/core/mochitest-server-port.js

@@ -23,6 +23,7 @@
  * port-generic, rather than growing a second probe.
  */
 import { GeneralError } from '../errors/base.js';
+import { isExplicitAbsolutePath, isPathInsideRoot } from '../utils/paths.js';
 import { exec } from '../utils/process.js';
 import { probeMarionettePort } from './marionette-port.js';
 /** Default port the mochitest harness binds its httpd to. */
@@ -43,6 +44,40 @@ export function isMochitestServerHolder(holder) {
         return false;
     return /\bxpcshell\b/.test(line) || /\/obj-[^/\s]*\//.test(line) || /\b_tests\b/.test(line);
 }
+/**
+ * Classifies the holder against this project's engine directory. Every
+ * absolute path on the command line is tested with {@link isPathInsideRoot}
+ * (a token test, not a substring test, so `/a/hominis/engine` does not claim
+ * a holder living under `/a/hominis-2/engine`). On POSIX the command line is
+ * the full `ps -o args=` output, so the objdir path is always present for a
+ * harness httpd; a holder whose paths all lie elsewhere belongs to another
+ * checkout.
+ *
+ * @param holder - The listener found on the port
+ * @param engineDir - Absolute engine directory of THIS project
+ */
+export function classifyMochitestServerHolder(holder, engineDir) {
+    if (!isMochitestServerHolder(holder))
+        return 'unrecognized';
+    const absoluteTokens = holder.commandLine.split(/\s+/).filter(isExplicitAbsolutePath);
+    return absoluteTokens.some((token) => isPathInsideRoot(engineDir, token))
+        ? 'this-checkout'
+        : 'foreign-checkout';
+}
+/**
+ * The objdir a foreign holder is serving from, for the refusal text: the
+ * first absolute command-line token with an `obj-…` segment, cut at that
+ * segment. Falls back to the first absolute token, then to a placeholder.
+ */
+export function describeHolderObjdir(commandLine) {
+    const tokens = commandLine.split(/\s+/).filter(isExplicitAbsolutePath);
+    for (const token of tokens) {
+        const match = /^(.*?[/\\]obj-[^/\\]*)(?:[/\\]|$)/.exec(token);
+        if (match?.[1])
+            return match[1];
+    }
+    return tokens[0] ?? '(no path visible on the command line)';
+}
 /**
  * Refuses a mochitest dispatch when the harness's server port is held. It
  * terminates the holder first only for a recognized stale harness httpd,
@@ -57,16 +92,24 @@ export function isMochitestServerHolder(holder) {
  * Best effort: {@link probeMarionettePort} reports an
  * unprobeable port as free, so a host without `lsof` runs exactly as before.
  *
+ * A recognized httpd from ANOTHER checkout is a refusal and never a kill
+ * either, flag or no flag: it is a peer's live suite, not our debris. The
+ * browser-side probe draws the same line for a bare launch it cannot
+ * attribute; this one can attribute, because the objdir is on the command
+ * line, so it names the other checkout instead of offering `kill -9`.
+ *
  * @param port - Port to probe (default {@link DEFAULT_MOCHITEST_SERVER_PORT})
- * @param options - `killStaleServer` opts into terminating a recognized holder
+ * @param options - `engineDir` is this project's absolute engine directory,
+ *   the ownership boundary; `killStaleServer` opts into terminating a holder
+ *   recognized as THIS checkout's debris
  */
-export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITEST_SERVER_PORT, options = {}) {
+export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITEST_SERVER_PORT, options) {
     const probe = await probeMarionettePort(port);
     if (!probe.inUse || !probe.holder)
         return;
     const holder = probe.holder;
-    const recognized = isMochitestServerHolder(holder);
-    if (recognized && options.killStaleServer === true) {
+    const holderClass = classifyMochitestServerHolder(holder, options.engineDir);
+    if (holderClass === 'this-checkout' && options.killStaleServer === true) {
         try {
             if (process.platform === 'win32') {
                 await exec('powershell.exe', [
@@ -87,16 +130,16 @@ export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITES
             // pretending the port is now free.
         }
     }
-    throw new GeneralError(describeMochitestServerRefusal(port, holder, recognized));
+    throw new GeneralError(describeMochitestServerRefusal(port, holder, holderClass));
 }
 /**
  * Builds the operator-facing refusal. Exported for direct unit testing.
  *
  * @param port - The probed port
  * @param holder - The listener found on it
- * @param recognized - Whether it is the harness's own `server.js`
+ * @param holderClass - Whose harness `server.js` it is, if it is one at all
  */
-export function describeMochitestServerRefusal(port, holder, recognized) {
+export function describeMochitestServerRefusal(port, holder, holderClass) {
     const killHint = process.platform === 'win32'
         ? `Stop-Process -Id ${holder.pid} -Force`
         : `kill -9 ${holder.pid}`;
@@ -106,11 +149,21 @@ export function describeMochitestServerRefusal(port, holder, recognized) {
         "  A browser launched now would connect to THAT server, which cannot serve this run's " +
         'manifest — the run would stall before TEST_START and die on the no-output timeout with ' +
         '"Ran 0 checks".\n';
-    if (recognized) {
+    if (holderClass === 'this-checkout') {
+        return (evidence +
+            "  This is the mochitest harness's own server.js from THIS checkout's objdir, so it is " +
+            'debris from an interrupted run. Retry with "--kill-stale-marionette" to have FireForge ' +
+            `stop it, or stop it yourself with "${killHint}" (a wedged httpd can ignore SIGTERM).`);
+    }
+    if (holderClass === 'foreign-checkout') {
+        // No kill hint on this branch, on purpose: the PID is a peer's live
+        // suite, and "kill -9 <pid>" is exactly the instruction that would have
+        // destroyed it.
         return (evidence +
-            "  This is the mochitest harness's own server.js, so it is debris from an interrupted run. " +
-            'Retry with "--kill-stale-marionette" to have FireForge stop it, or stop it yourself with ' +
-            `"${killHint}" (a wedged httpd can ignore SIGTERM).`);
+            `  This is a mochitest httpd from ANOTHER checkout: ${describeHolderObjdir(holder.commandLine)}. ` +
+            'It is serving a live run there, so FireForge will not stop it and "--kill-stale-marionette" ' +
+            'will not either. Wait for that run to finish or free the port yourself, then retry. ' +
+            `Diagnose with "lsof -nP -iTCP:${port}".`);
     }
     return (evidence +
         "  This is NOT the mochitest harness's server.js, so FireForge will not offer to kill it. " +