@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -7,11 +7,11 @@
  * browser with that flag, so any test run needs the port free at start.
  *
  * An interrupted `fireforge test` can leave an orphan browser process
- * listening on 2828 with parent PID 1, and the next test run — possibly in a
- * *different* FireForge project — then fails with a bare Marionette bind
- * error. This probe runs before every test launch, detects when the port is
- * held, and — when the holder is a browser process (by command-line
- * `-marionette` flag or by basename matching a known browser binary) —
+ * listening on 2828 with parent PID 1, and the next test run (possibly in a
+ * *different* FireForge project) then fails with a bare Marionette bind
+ * error. This probe runs before every test launch and detects when the port
+ * is held. When the holder is a browser process (by command-line
+ * `-marionette` flag or by basename matching a known browser binary), it
  * throws a targeted `GeneralError` naming the PID and the exact `kill`
  * command to run.
  *
@@ -22,9 +22,10 @@
  *
  * Both paths tolerate missing tooling: if `lsof` / PowerShell is not
  * installed the probe returns `{ inUse: false }` rather than failing the
- * test run — it is a best-effort friendliness check, not a prerequisite.
+ * test run. It is a best-effort friendliness check rather than a
+ * prerequisite.
  */
-import { GeneralError } from '../errors/base.js';
+import { PreflightRefusalError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { getPlatform } from '../utils/platform.js';
 import { exec } from '../utils/process.js';
@@ -63,7 +64,7 @@ async function findRunningBundleProcesses(launchableBinary) {
             return parseProcessList(result.stdout, launchableBinary);
         }
         // `etime=` is what makes the refusal attributable on a shared checkout:
-        // a browser that started as YOUR run was finishing is not yours.
+        // a browser that started as your run was finishing is not yours.
         const result = await exec('ps', ['-axo', 'pid=,etime=,args=']);
         return parseProcessList(result.stdout, launchableBinary);
     }
@@ -76,7 +77,7 @@ async function findRunningBundleProcesses(launchableBinary) {
  * regression-testable.
  *
  * Reads `pid etime args` where the middle field is a `ps` duration. The
- * elapsed field is parsed OPTIMISTICALLY: a listing produced without
+ * elapsed field is parsed optimistically: a listing produced without
  * `etime=` still parses, with the duration reported as `NaN` and the whole
  * second field folded back into the command line, so a caller that lost the
  * column degrades to the old behaviour instead of dropping the process.
@@ -133,19 +134,19 @@ export async function ensureLaunchableBrowserNotRunning(launchableBinary, option
             return;
         }
         catch (error) {
-            throw new GeneralError(`A browser from this objdir is still running (PID ${holder.pid}), but FireForge could not terminate it: ${toError(error).message}`);
+            throw new PreflightRefusalError(`A browser from this objdir is still running (PID ${holder.pid}), but FireForge could not terminate it: ${toError(error).message}`, 'stale-browser-kill-failed');
         }
     }
-    throw new GeneralError(describeRunningBundleRefusal(holder));
+    throw new PreflightRefusalError(describeRunningBundleRefusal(holder), 'stale-browser');
 }
 /**
- * True when the process was launched BY a test harness — its command line
- * carries `-marionette` (the control channel every `fireforge test` browser
- * is started with) or a harness `-profile`.
+ * True when the process was launched by a test harness, i.e. its command
+ * line carries `-marionette` (the control channel every `fireforge test`
+ * browser is started with) or a harness `-profile`.
  *
  * This is the distinction the refusal turns on. The objdir-bundle probe
  * matches any process running this project's binary, which on a shared
- * checkout includes a peer session's LIVE browser and a developer's own
+ * checkout includes a peer session's live browser and a developer's own
  * interactive one. Only a marionette-driven browser is safely
  * attributable to an interrupted run.
  */
@@ -155,17 +156,17 @@ function isHarnessDrivenBrowser(commandLine) {
 /**
  * Builds the refusal for a running objdir browser.
  *
- * Reports the EVIDENCE rather than a bare PID: the elapsed time and the
+ * Reports the evidence rather than a bare PID: the elapsed time and the
  * command line are what let an operator on a shared checkout decide whose
  * process it is, without reconstructing PID ancestry by hand. A downstream
- * fork hit exactly this — the message named a PID belonging to a peer
+ * fork hit exactly this: the message named a PID belonging to a peer
  * session's live browser and offered a flag that would have killed a
  * multi-hour evaluation run.
  *
- * So `--kill-stale-marionette` is offered ONLY for a marionette-driven
+ * So `--kill-stale-marionette` is offered only for a marionette-driven
  * browser. For a bare launch the message says what it found and stops:
  * FireForge cannot tell a dead run's orphan from someone's live window, and
- * the flag is the right MANUAL clear once ownership is verified, never an
+ * the flag is the right manual clear once ownership is verified, never an
  * automatic one.
  *
  * Exported for direct unit testing.
@@ -216,19 +217,19 @@ function isBrowserMarionettePortHolder(holder, binaryName) {
 }
 /**
  * Probes the given port with `lsof` (macOS / Linux). Returns
- * `{ inUse: false }` when the port is free OR when `lsof` is not
- * available — the probe is a best-effort courtesy check, so a
+ * `{ inUse: false }` when the port is free or when `lsof` is not
+ * available. The probe is a best-effort courtesy check, so a
  * missing tool must not block the test run.
  */
 async function probeWithLsof(port) {
     try {
-        // `-sTCP:LISTEN` filters to listeners only; `-P -n` avoids
+        // `-sTCP:LISTEN` filters to listeners only, and `-P -n` avoids
         // service/host lookups (faster + no DNS-dependent flakiness).
         // `-Fpcn` emits a machine-readable format: one field per line,
         // with `p<pid>`, `c<command>`, `n<name>` records.
         const result = await exec('lsof', ['-i', `tcp:${port}`, '-P', '-n', '-sTCP:LISTEN', '-Fpcn']);
-        // `lsof` exits 1 when no matches — that's "port is free", not an
-        // error. We key off stdout shape instead of exit code.
+        // `lsof` exits 1 when no matches, which means "port is free" rather
+        // than an error. We key off stdout shape instead of exit code.
         const stdout = result.stdout;
         const lines = stdout.split(/\r?\n/).filter((l) => l.length > 0);
         let pid = -1;
@@ -242,7 +243,7 @@ async function probeWithLsof(port) {
         if (!Number.isFinite(pid) || pid < 0 || command === '') {
             return { inUse: false };
         }
-        // `lsof` does not return the full command line; `ps` does. A
+        // `lsof` does not return the full command line, but `ps` does. A
         // missing `ps` (exotic Linux container) falls back to `command`
         // alone, which is still enough to match `BROWSER_BASENAMES`.
         let commandLine = command;
@@ -253,7 +254,7 @@ async function probeWithLsof(port) {
                 commandLine = psLine.trim();
         }
         catch {
-            // ps not available — keep the basename.
+            // ps not available, so keep the basename.
         }
         return { inUse: true, holder: { pid, command, commandLine } };
     }
@@ -320,7 +321,7 @@ export async function probeMarionettePort(port = DEFAULT_MARIONETTE_PORT) {
         platform = getPlatform();
     }
     catch {
-        // Unrecognised host platform — no probe strategy applies, so the port is
+        // Unrecognised host platform, so no probe strategy applies and the port is
         // reported free rather than blocking the run.
         return { inUse: false };
     }
@@ -332,7 +333,7 @@ export async function probeMarionettePort(port = DEFAULT_MARIONETTE_PORT) {
 }
 /**
  * Raises a targeted {@link GeneralError} when the Marionette port
- * is held by a browser process; raises a softer warning-shaped
+ * is held by a browser process. Raises a softer warning-shaped
  * error when the holder is unrelated (so the operator still sees
  * a useful signal but can decide whether to wait it out).
  *
@@ -349,18 +350,18 @@ export async function assertMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
         const killHint = process.platform === 'win32'
             ? `Stop-Process -Id ${holder.pid} -Force`
             : `kill ${holder.pid}  # or "kill -9 ${holder.pid}" if it doesn't exit`;
-        throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
+        throw new PreflightRefusalError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
             `This is usually a browser left running by a previously interrupted "fireforge test" run. ` +
             `Kill it with "${killHint}", then retry. ` +
             `(If you expected ${holder.command} to be running on ${port}, stop it manually or pass ` +
-            `"--marionette-port <port>" to launch mach test on a different port.)`);
+            `"--marionette-port <port>" to launch mach test on a different port.)`, 'marionette-port-busy');
     }
     // Non-browser holder: mach test will still fail to bind, but the
     // cause is not a stale FireForge-launched browser. Flag it
     // explicitly so the operator can decide what to do instead of
     // getting mach's bind error with no FireForge context.
-    throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
-        `This is not a FireForge-launched browser; stop the holder process or free the port before rerunning.`);
+    throw new PreflightRefusalError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
+        `This is not a FireForge-launched browser; stop the holder process or free the port before rerunning.`, 'marionette-port-busy');
 }
 /**
  * Ensures the Marionette port is usable, optionally terminating a stale
@@ -390,8 +391,8 @@ export async function ensureMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
         }
     }
     catch (error) {
-        throw new GeneralError(`Marionette port ${port} is held by stale browser ${holder.command} (PID ${holder.pid}), ` +
-            `but FireForge could not terminate it: ${toError(error).message}`);
+        throw new PreflightRefusalError(`Marionette port ${port} is held by stale browser ${holder.command} (PID ${holder.pid}), ` +
+            `but FireForge could not terminate it: ${toError(error).message}`, 'stale-browser-kill-failed');
     }
 }
 /**
@@ -405,15 +406,13 @@ export async function ensureMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
  * the test command auto-forwards to mach.
  *
  * @param machArgs - Forwarded mach args as they would appear on the command
- *   line (one element per token; `--foo=bar` and `--foo bar` both supported).
- * @returns The integer port if a recognised arg is present and parses; else
- *   `undefined`.
+ *   line (one element per token, with `--foo=bar` and `--foo bar` both
+ *   supported).
+ * @returns The integer port if a recognised arg is present and parses,
+ *   otherwise `undefined`.
  */
 export function extractForwardedMarionettePort(machArgs) {
-    for (let i = 0; i < machArgs.length; i++) {
-        const arg = machArgs[i];
-        if (arg === undefined)
-            continue;
+    for (const [i, arg] of machArgs.entries()) {
         // `--marionette-port=NNNN`
         let match = /^--marionette-port=(\d+)$/.exec(arg);
         if (match?.[1]) {
@@ -430,7 +429,7 @@ export function extractForwardedMarionettePort(machArgs) {
                     return n;
             }
         }
-        // `--setpref=marionette.port=NNNN` — the auto-forward shape; recognised
+        // `--setpref=marionette.port=NNNN`, the auto-forward shape. Recognised
         // here so a duplicate check at the call site can spot operator-supplied
         // setprefs without re-implementing the parse.
         match = /^--setpref=marionette\.port=(\d+)$/.exec(arg);
@@ -446,16 +445,14 @@ export function extractForwardedMarionettePort(machArgs) {
  * True when forwarded mach args already set a Marionette **client** address
  * for mach/mochitest (`--marionette=host:port` or `--marionette host:port`).
  * Used only to avoid duplicating FireForge's auto-injected
- * `--marionette=127.0.0.1:<n>`; this is not a full URL validator (IPv6, etc.).
+ * `--marionette=127.0.0.1:<n>`. This is not a full URL validator (IPv6,
+ * etc.).
  *
- * Deliberately does **not** treat `--marionette-port` as a client endpoint.
+ * Does not treat `--marionette-port` as a client endpoint.
  */
 export function forwardedMachArgsIncludeMarionetteClient(machArgs) {
     const valueLooksLikeHostPort = (token) => /:[0-9]+$/.test(token) || /^\[[^]]+\]:[0-9]+$/.test(token);
-    for (let i = 0; i < machArgs.length; i++) {
-        const arg = machArgs[i];
-        if (arg === undefined)
-            continue;
+    for (const [i, arg] of machArgs.entries()) {
         if (arg.startsWith('--marionette=') && !arg.startsWith('--marionette-port=')) {
             return true;
         }
@@ -473,8 +470,7 @@ export function forwardedMachArgsIncludeMarionetteClient(machArgs) {
  * for runs where the pref is ignored anyway.
  */
 export function hasExplicitXpcshellFlavor(machArgs) {
-    for (let i = 0; i < machArgs.length; i += 1) {
-        const arg = machArgs[i] ?? '';
+    for (const [i, arg] of machArgs.entries()) {
         if (/^--flavor=xpcshell\b/.test(arg) || arg === '--flavor=xpcshell-tests')
             return true;
         if (arg === '--flavor' && /^xpcshell(?:-tests)?$/.test(machArgs[i + 1] ?? ''))
@@ -493,42 +489,3 @@ export function hasExplicitXpcshellFlavor(machArgs) {
 export function shouldAutoForwardMarionettePortToMach(machArgs) {
     return !hasExplicitXpcshellFlavor(machArgs);
 }
-/**
- * Heuristic: do the test paths or forwarded mach args indicate a flavour
- * that actually launches a Marionette-driven browser? Browser-chrome and
- * mochitest do; xpcshell does not. A no-paths invocation (the default "run
- * all tests" shape) is treated as marionette-relevant since it includes
- * browser-chrome.
- *
- * Note: `fireforge test` auto-forward of `--marionette-port` to mach uses
- * {@link shouldAutoForwardMarionettePortToMach} (mach-arg flavor gate) rather
- * than this function alone, so toolkit paths without `/mochitest/` still get
- * the listener pref and harness `--marionette=127.0.0.1:<n>` when appropriate.
- *
- * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
- * @param machArgs - Forwarded mach args (post-`--mach-arg`).
- * @returns `true` when the run is likely to bind a Marionette listener.
- */
-export function isMarionetteFlavor(testPaths, machArgs) {
-    if (hasExplicitXpcshellFlavor(machArgs))
-        return false;
-    for (const arg of machArgs) {
-        if (/^--flavor=(browser-chrome|mochitest|chrome|a11y)\b/.test(arg))
-            return true;
-    }
-    if (testPaths.length === 0)
-        return true;
-    for (const path of testPaths) {
-        const base = path.split('/').pop() ?? path;
-        if (/^browser_.+\.(js|ini|toml)$/.test(base))
-            return true;
-        if (path.includes('/mochitest/') || path.startsWith('mochitest/'))
-            return true;
-        if (path.includes('/browser-chrome/') || path.startsWith('browser-chrome/'))
-            return true;
-        if (path.includes('toolkit/content/tests/') && !path.includes('/tests/xpcshell/')) {
-            return true;
-        }
-    }
-    return false;
-}

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

@@ -3,7 +3,7 @@
  *
  * Answers a single question before tests run: "does marionette come up?" A
  * silent 360-second mach-test hang is indistinguishable from "tests failed
- * to discover"; this helper surfaces the failure in under a minute with a
+ * to discover". This helper surfaces the failure in under a minute with a
  * clear PASS/FAIL line and the tail of the browser's stderr.
  *
  * The probe is a cascade of layered checks (engine → mach → python →
@@ -22,7 +22,7 @@ export interface MarionettePreflightResult {
 export interface MarionettePreflightOptions {
     /** Total budget in ms. Defaults to 30 seconds. */
     timeoutMs?: number;
-    /** Overrides marionette TCP port — primarily used in tests. */
+    /** Overrides marionette TCP port. Primarily used in tests. */
     port?: number;
     /**
      * Grace window after spawn() before the browser is considered "running
@@ -37,16 +37,16 @@ export interface MarionettePreflightOptions {
 }
 /**
  * Runs the marionette preflight. Returns PASS on first byte read from the
- * marionette socket within the budget; FAIL otherwise, with a diagnostic
- * identifying which layer of the cascade broke. Always tears down the
- * spawned browser before returning.
+ * marionette socket within the budget, and FAIL otherwise, with a
+ * diagnostic identifying which layer of the cascade broke. Always tears
+ * down the spawned browser before returning.
  */
 export declare function runMarionettePreflight(engineDir: string, options?: MarionettePreflightOptions): Promise<MarionettePreflightResult>;
 /** Renders a PASS/FAIL banner to the CLI using the shared logger helpers. */
 export declare function reportMarionettePreflight(result: MarionettePreflightResult): void;
 /**
  * Formats the PASS/FAIL banner as a plain string for direct
- * `process.stdout.write` use — bypassing the clack logger entirely so
+ * `process.stdout.write` use, bypassing the clack logger entirely so
  * operators running `fireforge test --doctor` under a non-TTY (pipe, CI,
  * `tee`-wrapped capture) always see the final line. Clack's renderer can
  * swallow trailing log output just before process exit, and a

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

@@ -4,7 +4,7 @@
  *
  * Answers a single question before tests run: "does marionette come up?" A
  * silent 360-second mach-test hang is indistinguishable from "tests failed
- * to discover"; this helper surfaces the failure in under a minute with a
+ * to discover". This helper surfaces the failure in under a minute with a
  * clear PASS/FAIL line and the tail of the browser's stderr.
  *
  * The probe is a cascade of layered checks (engine → mach → python →
@@ -22,6 +22,7 @@ import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { installGracefulShutdownForwarder, trackChildClosure } from '../utils/process.js';
 import { killProcessTree, sweepProcessGroup } from '../utils/process-group.js';
+import { sleep } from '../utils/sleep.js';
 import { ensureMach } from './mach.js';
 import { getPython } from './mach-python.js';
 /** Marionette's default TCP port when the browser is launched with `--marionette`. */
@@ -33,7 +34,7 @@ const SOCKET_ATTEMPT_TIMEOUT_MS = 2_000;
 /**
  * Grace window after spawn() returns before we accept the child as
  * "spawned OK". A browser binary that exits immediately (missing dylib,
- * wrong CPU arch, corrupt profile) must be caught here — not 30 seconds
+ * wrong CPU arch, corrupt profile) must be caught here, not 30 seconds
  * later at the socket layer.
  */
 const SPAWN_SETTLE_MS = 750;
@@ -57,9 +58,9 @@ function layerTag(name) {
 }
 /**
  * Runs the marionette preflight. Returns PASS on first byte read from the
- * marionette socket within the budget; FAIL otherwise, with a diagnostic
- * identifying which layer of the cascade broke. Always tears down the
- * spawned browser before returning.
+ * marionette socket within the budget, and FAIL otherwise, with a
+ * diagnostic identifying which layer of the cascade broke. Always tears
+ * down the spawned browser before returning.
  */
 export async function runMarionettePreflight(engineDir, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
@@ -100,15 +101,15 @@ export async function runMarionettePreflight(engineDir, options = {}) {
     let stderrTail = '';
     // Shutdown contract for a child spawned outside the exec layer.
     //
-    // This is the repo's one legitimate raw `spawn`: the preflight needs the
-    // live `ChildProcess` mid-run (`hasChildExited` gates the socket poll),
+    // This is the one raw `spawn` in the repo. The preflight needs the live
+    // `ChildProcess` mid-run (`hasChildExited` gates the socket poll),
     // returns while the browser is still running, and aborts on a TCP byte
-    // rather than on a deadline — none of which any wrapper in utils/process
-    // can express. What it does NOT get to skip is the contract every wrapper
-    // applies to a detached child: register the closure so the bin signal
-    // handler waits for it, and forward the parent's SIGINT/SIGTERM to the
-    // group. Without both, Ctrl+C during `fireforge test --doctor` left the
-    // whole mach → Firefox tree running.
+    // rather than on a deadline. No wrapper in utils/process can express
+    // that. It still has to honour the contract every wrapper applies to a
+    // detached child: register the closure so the bin signal handler waits
+    // for it, and forward the parent's SIGINT/SIGTERM to the group. Without
+    // both, Ctrl+C during `fireforge test --doctor` left the whole
+    // mach → Firefox tree running.
     let closure;
     let forwarder;
     try {
@@ -129,7 +130,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
                 // `detached: true` puts the child in a new process group so we can
                 // signal it and every descendant (Firefox, its helpers) via
                 // `process.kill(-pid, …)` in the finally block. Without it, the
-                // child is Python running mach; a SIGTERM kills Python but the
+                // child is Python running mach. A SIGTERM kills Python but the
                 // Firefox grandchild inherits the stderr pipe FD and keeps Node's
                 // event loop alive even after the preflight PASS log, so
                 // `fireforge test --doctor` prints `Marionette preflight: PASS`
@@ -143,22 +144,22 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         const spawnedChild = child;
         closure = trackChildClosure();
         forwarder = installGracefulShutdownForwarder(spawnedChild, 500, (signal) => {
-            killProcessGroup(spawnedChild, signal);
+            killProcessTree(spawnedChild, signal, process.platform !== 'win32');
         });
         child.stderr?.on('data', (data) => {
             const chunk = data.toString();
             stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_LIMIT);
         });
-        // Short settle window — catches "binary exits immediately" failures
+        // Short settle window. Catches "binary exits immediately" failures
         // (missing dylib, wrong CPU arch, corrupt profile) before the socket
         // poll swallows the full overall budget waiting for bytes that will
         // never come.
         const settleDeadline = Math.min(spawnSettleMs, Math.max(0, timeoutMs - elapsed()));
         if (settleDeadline > 0) {
-            await delay(settleDeadline);
+            await sleep(settleDeadline, { unref: true });
         }
         if (hasChildExited(spawnedChild)) {
-            return fail('browser-spawns', `Browser process exited during spawn (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+            return fail('browser-spawns', `Browser process exited during spawn (exit code ${spawnedChild.exitCode}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
                 `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
         }
         // Layer 6: marionette handshake within the remaining budget.
@@ -172,10 +173,10 @@ export async function runMarionettePreflight(engineDir, options = {}) {
                 detail: `Marionette handshake received on 127.0.0.1:${port} in ${Date.now() - startedAt}ms.`,
             };
         }
-        // Child may have exited before the socket was ever ready — surface that
+        // Child may have exited before the socket was ever ready. Surface that
         // distinctly from "socket never answered" so the operator has a lead.
         if (hasChildExited(spawnedChild)) {
-            return fail('marionette-handshake', `Browser process exited before marionette handshake (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+            return fail('marionette-handshake', `Browser process exited before marionette handshake (exit code ${spawnedChild.exitCode}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
                 `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
         }
         return fail('marionette-handshake', `Marionette socket on 127.0.0.1:${port} did not respond within ${timeoutMs}ms. ` +
@@ -203,17 +204,17 @@ async function teardownPreflightChild(child, forwarder, closure, profileDir) {
     forwarder?.dispose();
     const groupPid = child?.pid;
     if (child && !hasChildExited(child)) {
-        killProcessGroup(child, 'SIGTERM');
+        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 delay(500);
+        await sleep(500, { unref: true });
         if (!hasChildExited(child)) {
-            killProcessGroup(child, 'SIGKILL');
+            killProcessTree(child, 'SIGKILL', process.platform !== 'win32');
         }
     }
     // Reap anything that outlived the group signal. The file's own comments
-    // worry about exactly this — Firefox grandchildren surviving the Python
-    // mach wrapper — and every exec-layer wrapper sweeps for it.
+    // worry about exactly this case (Firefox grandchildren surviving the
+    // Python mach wrapper), and every exec-layer wrapper sweeps for it.
     if (groupPid !== undefined && process.platform !== 'win32') {
         try {
             await sweepProcessGroup(groupPid);
@@ -225,8 +226,8 @@ async function teardownPreflightChild(child, forwarder, closure, profileDir) {
     closure?.settle();
     // Destroy the stderr pipe explicitly. Firefox (a grandchild of the Python
     // mach wrapper we spawned) can inherit and hold the stderr FD even after
-    // its direct parent exits — until the pipe closes, Node's readable
-    // stream stays attached and `uv__io_poll` keeps the event loop alive.
+    // its direct parent exits. Until the pipe closes, Node's readable stream
+    // stays attached and `uv__io_poll` keeps the event loop alive.
     // `destroy()` closes the local end regardless, so `fireforge test
     // --doctor` exits cleanly after a passing preflight.
     child?.stderr?.destroy();
@@ -237,19 +238,6 @@ async function teardownPreflightChild(child, forwarder, closure, profileDir) {
         warn(`Could not clean up marionette preflight profile: ${toError(error).message}`);
     }
 }
-/**
- * Sends `signal` to the child's whole process group when possible, falling
- * back to a direct `child.kill` for environments that don't support
- * `detached: true` (Windows in particular: Node still returns a pid, but
- * `kill(-pid, …)` is not a supported kernel primitive).
- */
-function killProcessGroup(child, signal) {
-    // Delegates to the shared implementation, which is a strict superset of
-    // the hand-rolled one this replaced: same POSIX `kill(-pid)` with the same
-    // fall-through to a direct `child.kill`, plus a Windows `taskkill /T /F`
-    // branch and an already-exited early return.
-    killProcessTree(child, signal, process.platform !== 'win32');
-}
 function fail(layer, message, durationMs) {
     return {
         ok: false,
@@ -267,7 +255,7 @@ async function waitForMarionetteSocket(port, connectFn, keepTrying) {
         if (result.ok) {
             return { ok: true };
         }
-        await delay(400);
+        await sleep(400, { unref: true });
     }
     return { ok: false };
 }
@@ -283,7 +271,7 @@ function attemptMarionetteConnect(port, connectFn) {
                 socket.destroy();
             }
             catch {
-                // Ignore — already closed.
+                // Ignore: already closed.
             }
             resolve({ ok });
         };
@@ -292,7 +280,7 @@ function attemptMarionetteConnect(port, connectFn) {
         }, SOCKET_ATTEMPT_TIMEOUT_MS);
         attemptTimer.unref();
         socket.once('connect', () => {
-            // Connect alone is insufficient — the marionette server performs a
+            // Connect alone is insufficient. The marionette server performs a
             // handshake send as soon as the socket opens, so wait for at least one
             // byte to confirm the server is actually speaking marionette.
             const readTimer = setTimeout(() => {
@@ -312,12 +300,6 @@ function attemptMarionetteConnect(port, connectFn) {
         });
     });
 }
-function delay(ms) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, ms);
-        timer.unref();
-    });
-}
 /** Renders a PASS/FAIL banner to the CLI using the shared logger helpers. */
 export function reportMarionettePreflight(result) {
     if (result.ok) {
@@ -329,7 +311,7 @@ export function reportMarionettePreflight(result) {
 }
 /**
  * Formats the PASS/FAIL banner as a plain string for direct
- * `process.stdout.write` use — bypassing the clack logger entirely so
+ * `process.stdout.write` use, bypassing the clack logger entirely so
  * operators running `fireforge test --doctor` under a non-TTY (pipe, CI,
  * `tee`-wrapped capture) always see the final line. Clack's renderer can
  * swallow trailing log output just before process exit, and a

package/dist/src/core/markdown-table.d.ts

@@ -1,7 +1,7 @@
 /**
  * Minimal Markdown pipe-table parser/writer used by token-manager.
  *
- * This is **not** a general Markdown parser. It understands exactly the
+ * This is not a general Markdown parser. It understands exactly the
  * slice of GitHub-flavoured Markdown that FireForge emits into token docs:
  *
  *   - Leading `|` per row, trailing `|` optional.
@@ -12,10 +12,10 @@
  *   - Literal `|` and `\` inside a cell are expressed as `\|` and `\\`
  *     respectively. The parser treats any other backslash as a literal
  *     so prose-style backslashes in cell values (e.g. a Windows path)
- *     still round-trip. Unescaping happens at split time; serialization
+ *     still round-trip. Unescaping happens at split time. Serialization
  *     re-applies escapes so round-trips are exact for well-formed input.
  *
- * The parser returns **positional metadata** (`startLine`, `endLine`) so
+ * The parser returns positional metadata (`startLine`, `endLine`) so
  * callers can splice the table back into the surrounding document by
  * range instead of hand-rolled line counters. Mutation operations return
  * a fresh line array rather than mutating in place, matching the rest of
@@ -24,7 +24,7 @@
  * Fallback tolerance: rows with more cells than the header get their
  * overflow merged into the last column (using a literal `|` separator
  * between the merged values). This is for the rare case where a FireForge
- * writer emits an unescaped pipe — the parser still produces a consistent
+ * writer emits an unescaped pipe. The parser still produces a consistent
  * cell count rather than desynchronising the table. On re-serialize the
  * merged cell's literal pipes are escaped, so a malformed input becomes
  * a well-formed output after one round trip.
@@ -37,8 +37,8 @@ export interface MarkdownTable {
     headers: string[];
     /**
      * Data rows. Each row is an array with exactly `headers.length` entries,
-     * trimmed. Rows shorter than the header are right-padded with `''`;
-     * longer rows have trailing cells merged into the last column so the
+     * trimmed. Rows shorter than the header are right-padded with `''`.
+     * Longer rows have trailing cells merged into the last column so the
      * round-trip is faithful.
      */
     rows: string[][];
@@ -60,14 +60,14 @@ export interface MarkdownTable {
  */
 export declare function findNextTable(lines: string[], fromLine: number): MarkdownTable | null;
 /**
- * Returns the first table whose header contains **all** of the provided
+ * Returns the first table whose header contains all of the provided
  * column names (case-sensitive, order-insensitive). Useful when several
  * pipe tables share a document and you want to select "the one with a
  * Mode column".
  */
 export declare function findTableByColumns(lines: string[], requiredColumns: string[]): MarkdownTable | null;
 /**
- * Returns the first table that appears **after** a heading matching the
+ * Returns the first table that appears after a heading matching the
  * given regex. The heading regex is applied to raw lines (no trimming)
  * so callers that want leading whitespace flexibility should include
  * `^\s*` or `^#+\s*` as appropriate.
@@ -83,7 +83,7 @@ export declare function findTableAfterHeading(lines: string[], headingPattern: R
 export declare function serializeRow(cells: string[]): string;
 /**
  * Inserts a new row into `table.rows` at the given zero-based index. A
- * negative index counts from the end; `Infinity` appends. Mutates the
+ * negative index counts from the end. `Infinity` appends. Mutates the
  * table object so callers using {@link rewriteTableRows} see the update.
  */
 export declare function insertRow(table: MarkdownTable, cells: string[], index: number): void;