@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/mach.js

@@ -16,7 +16,7 @@ import { detectHarnessCrashSignature } from './test-harness-crash.js';
 // This block is a frozen compatibility list, not a barrel to grow: every name
 // here already had a `from './mach.js'` import when the module was split.
 // New helpers belong in their own sub-module and are imported from it
-// directly — adding to this list pulls the whole sub-module into every suite
+// directly. Adding to this list pulls the whole sub-module into every suite
 // that mocks `mach.js`.
 export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
@@ -51,8 +51,8 @@ export async function runMach(args, engineDir, options = {}) {
     if (options.inherit) {
         // Group-reap every long-lived inherited mach dispatch (bootstrap, run,
         // watch): a mach dying at startup must not strand multiprocessing
-        // workers. Short-lived metadata queries below stay on plain exec() —
-        // adding groups there would touch every non-mach exec consumer's path
+        // workers. Short-lived metadata queries below stay on plain exec().
+        // Adding groups there would touch every non-mach exec consumer's path
         // for no reaping benefit.
         return execInherit(python, [machPath, ...args], { ...execOptions, processGroup: true });
     }
@@ -79,7 +79,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
     const machPath = join(engineDir, 'mach');
     let stdout = '';
     let stderr = '';
-    // Echo-path filters only: the captured strings above accumulate RAW so the
+    // Echo-path filters only: the captured strings above accumulate raw so the
     // classifier still sees the full teardown traceback. When the option is
     // off, the filters are absent and echo is a straight write (unchanged).
     // One shutdown context per run, shared by both stream filters: the
@@ -94,18 +94,18 @@ export async function runMachCapture(args, engineDir, options = {}) {
         ...(options.envUnset ? { envUnset: options.envUnset } : {}),
         // Every capture dispatch (test suites, protected builds, package,
         // storybook) runs as a process-group leader and is group-reaped on
-        // exit/abort — see ExecOptions.processGroup.
+        // exit/abort. See ExecOptions.processGroup.
         processGroup: true,
         onStdout: (data) => {
             stdout += data;
             if (stdout.length > CAPTURE_TAIL_LIMIT) {
                 stdout = stdout.slice(-CAPTURE_TAIL_LIMIT);
             }
-            // RAW into the log, filtered into the echo. The log exists to be
+            // Raw into the log, filtered into the echo. The log exists to be
             // re-read after the fact by whoever is diagnosing the run, and the
-            // echo filter's whole purpose is to shorten what a HUMAN scrolls
-            // past — collapsing a traceback in the artifact would reintroduce
-            // the loss this log exists to prevent.
+            // echo filter only exists to shorten what a human scrolls past.
+            // Collapsing a traceback in the artifact would reintroduce the loss
+            // this log exists to prevent.
             writeToActiveRunLog(data);
             process.stdout.write(stdoutFilter ? stdoutFilter.transform(data) : data);
         },
@@ -163,9 +163,9 @@ export async function bootstrapWithOutput(engineDir) {
  * propagates so the hint sits immediately below the raw mach error in the
  * operator's terminal.
  *
- * The scanner is passed the concatenation of stderr AND stdout because mach
+ * The scanner is passed the concatenation of stderr and stdout because mach
  * streams its subcommand output through a timestamp-prefixing wrapper that
- * writes both streams to whatever FD the subprocess chose — `rustc` errors
+ * writes both streams to whatever FD the subprocess chose, so `rustc` errors
  * from `mach build` can land on stdout, so feeding only `result.stderr`
  * silently loses the match.
  */
@@ -186,10 +186,10 @@ function surfaceMachErrorHints(result) {
  */
 const DEFAULT_BUILD_CRASH_RETRIES = 2;
 /**
- * Names the known mozsystemmonitor teardown traceback when a BUILD carried
- * it. The test path collapses this signature in the echo; a build cannot
+ * Names the known mozsystemmonitor teardown traceback when a build carried
+ * it. The test path collapses this signature in the echo. A build cannot
  * (see `mach-known-noise-filter.ts`), so it reached operators as an
- * unexplained traceback in a build log — a recognized, documented upstream
+ * unexplained traceback in a build log: a recognized, documented upstream
  * defect wearing the appearance of a new one. The output is left verbatim
  * and this one line is added beside it, so the same signature reads the same
  * in both phases.
@@ -201,20 +201,20 @@ function noteKnownTeardownNoiseInBuild(result) {
 }
 /**
  * The single protected path every FireForge mach build dispatch routes
- * through — `build`, `build --ui`, and the pre-test `--build` step all use
+ * through. `build`, `build --ui`, and the pre-test `--build` step all use
  * it, so no entry point is left unprotected with a different retry budget:
  *
- *  1. installs the resource-monitor degrade guard IN the mach virtualenvs
- *     (plus the PYTHONPATH fallback) — re-installed before every attempt, so
+ *  1. installs the resource-monitor degrade guard in the mach virtualenvs
+ *     (plus the PYTHONPATH fallback), re-installed before every attempt, so
  *     a venv materialized by a crashed first attempt is guarded on the next
- *     one instead of every retry dying on the same wedged state;
- *  2. spawns a fresh mach process per attempt;
- *  3. retries ONLY the recognized harness-crash family (resource monitor /
- *     psutil startup tracebacks) up to the uniform budget — an ordinary
+ *     one instead of every retry dying on the same wedged state.
+ *  2. spawns a fresh mach process per attempt.
+ *  3. retries only the recognized harness-crash family (resource monitor /
+ *     psutil startup tracebacks) up to the uniform budget. An ordinary
  *     compile error is never retried.
  *
  * The protected path never runs `mach configure`, never clobbers, and never
- * widens the requested build kind — a `faster` dispatch retries as
+ * widens the requested build kind: a `faster` dispatch retries as
  * `mach build faster`, so it cannot invalidate more of the objdir than the
  * command the operator asked for.
  */
@@ -250,8 +250,8 @@ export async function runProtectedMachBuild(kind, engineDir, options = {}) {
  * hints are surfaced on top of the raw mach output so operators get an
  * actionable nudge alongside the cryptic mozbuild traceback. Returns the
  * captured result so the caller (e.g. `fireforge build`) can inspect the
- * tail for post-build diagnostics that mach prints AFTER "Your build was
- * successful!" — notably the stale `config.status is out of date`
+ * tail for post-build diagnostics that mach prints after "Your build was
+ * successful!", notably the stale `config.status is out of date`
  * notice that mach emits when a tool-managed edit landed on
  * `moz.configure` before the build.
  * @param engineDir - Path to the engine directory
@@ -279,13 +279,13 @@ export async function buildUI(engineDir) {
  *
  * Without it, a `build --ui` started while a full `build` is still in flight
  * hands off to `mach build faster` and fails almost immediately with `No
- * rule to make target 'XUL'` — the real problem being that the first build
+ * rule to make target 'XUL'`, the real problem being that the first build
  * has not yet materialised the full backend, with nothing in the low-level
  * make error pointing at the concurrent run. The lock intercepts the second
  * invocation before it touches mach, and the refusal names the PID holding
  * the lock so the operator can decide whether to wait or investigate.
  *
- * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * Stale-lock recovery: the lock stores the owner PID. A crashed build
  * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but not the
  * owning process, and `withFileLock` removes the lock on the next attempt
  * when `process.kill(pid, 0)` shows the owner is gone.
@@ -299,9 +299,9 @@ export async function buildUI(engineDir) {
 export async function withBuildLock(projectRoot, operation) {
     const lockPath = createSiblingLockPath(join(projectRoot, '.fireforge-build'), '.lock');
     return withFileLock(lockPath, operation, {
-        // Default lock timeout is 30s; bump to 24h so a slow full build does
-        // not trip the timeout while the second invocation waits. A real
-        // operator will ^C long before 24h elapses; the ceiling is there
+        // Default lock timeout is 30s. Bump it to 24h so a slow full build
+        // does not trip the timeout while the second invocation waits. A real
+        // operator will ^C long before 24h elapses. The ceiling is there
         // purely so a forgotten lock cannot wedge the command forever.
         timeoutMs: 24 * 60 * 60 * 1000,
         onTimeoutMessage: `Timed out waiting for the FireForge build lock at ${lockPath}. ` +
@@ -323,7 +323,7 @@ export async function run(engineDir, args = []) {
  * enforces a deadline by SIGTERMing the whole process group, and returns
  * the captured output alongside a `timedOut` flag.
  *
- * Unlike {@link run}, this variant does NOT inherit stdio. The child
+ * Unlike {@link run}, this variant does not inherit stdio. The child
  * stdout/stderr are piped back through the line callbacks so the caller
  * can scan for `JavaScript error:` / `console.error:` without coupling
  * the runner to chrome-specific pattern logic.
@@ -360,7 +360,7 @@ export async function machPackageCapture(engineDir) {
  * `env` is threaded through so the caller can prepend the resolved watchman
  * directory to PATH in a way mach inherits: `fireforge watch` can locate
  * `watchman` via `which`, but the mach subprocess spawns with the parent's
- * PATH only — on macOS that typically omits `/opt/homebrew/bin`, so
+ * PATH only, and on macOS that typically omits `/opt/homebrew/bin`, so
  * `mach watch` fails at the `watch-project` subscription step.
  *
  * @param engineDir - Path to the engine directory
@@ -376,13 +376,13 @@ export async function watchWithOutput(engineDir, options = {}) {
  * agent (`mozbuild.util.is_running_under_coding_agent`), which quiets
  * terminal output to warnings and errors.
  *
- * The quieting is genuinely useful for BUILDS — that is most of what an
- * agent session prints — but it applies to test runs too, where it removes
+ * The quieting is genuinely useful for builds, which are most of what an
+ * agent session prints, but it applies to test runs too, where it removes
  * `TEST_START` and console INFO: exactly the lines a hang or stall
  * diagnosis needs, and the ones FireForge's own classifier reads
  * (`Ran N checks`, `Unexpected results:`, `TEST-UNEXPECTED-*`). Unsetting
  * the variable globally would give up the build half as well, so the
- * dispatchers below unset it per TEST dispatch and leave the build path
+ * dispatchers below unset it per test dispatch and leave the build path
  * alone.
  */
 const CODING_AGENT_ENV_MARKERS = ['CLAUDECODE'];
@@ -399,8 +399,8 @@ function testVerbosityEnvUnset(fullOutput) {
 /**
  * Runs one mach test command (`mach test` / `mach xpcshell-test` / `mach
  * mochitest`) while capturing streamed output for better diagnostics. The
- * three commands share every other detail of the dispatch — resource guard,
- * verbosity env, teardown-noise annotation — so they share one entry point
+ * three commands share every other detail of the dispatch (resource guard,
+ * verbosity env, teardown-noise annotation), so they share one entry point
  * keyed by `kind` rather than three copies that drift.
  *
  * @param kind - Which mach command to run

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

@@ -11,7 +11,7 @@ export interface MarionettePortHolder {
     /**
      * Full command line the holder was launched with, when the probe
      * can recover it. `lsof` by itself only returns the basename, so
-     * POSIX callers see `command === commandLine`; Windows callers
+     * POSIX callers see `command === commandLine`. Windows callers
      * recover the full command line via `Get-Process`. Used to detect
      * the `-marionette` flag, which positively identifies a stale
      * browser rather than an unrelated listener.
@@ -33,7 +33,7 @@ export interface RunningBundleProcess {
     commandLine: string;
     /**
      * Elapsed wall-clock seconds since the process started, from `ps
-     * etime=`. `NaN` when the field was absent or unparseable — callers must
+     * etime=`. `NaN` when the field was absent or unparseable, and callers must
      * omit the clause rather than print a zero, because "started 0s ago" is
      * exactly the wrong attribution for a peer session's long-lived browser.
      */
@@ -44,7 +44,7 @@ export interface RunningBundleProcess {
  * 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.
@@ -62,17 +62,17 @@ export declare function ensureLaunchableBrowserNotRunning(launchableBinary: stri
 /**
  * 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.
@@ -88,7 +88,7 @@ export declare function describeRunningBundleRefusal(holder: RunningBundleProces
 export declare function probeMarionettePort(port?: number): Promise<MarionettePortProbeResult>;
 /**
  * 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).
  *
@@ -118,18 +118,20 @@ export declare function ensureMarionettePortAvailable(port?: number, options?: {
  * 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 declare function extractForwardedMarionettePort(machArgs: string[]): number | undefined;
 /**
  * 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 declare function forwardedMachArgsIncludeMarionetteClient(machArgs: string[]): boolean;
 /**

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,7 +22,8 @@
  *
  * 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 { PreflightRefusalError } from '../errors/base.js';
 import { toError } from '../utils/errors.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.
@@ -139,13 +140,13 @@ export async function ensureLaunchableBrowserNotRunning(launchableBinary, option
     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).
  *
@@ -405,9 +406,10 @@ 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 (const [i, arg] of machArgs.entries()) {
@@ -427,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);
@@ -443,9 +445,10 @@ 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);

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 →
@@ -34,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;
@@ -58,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;
@@ -101,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 {
@@ -130,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`
@@ -150,7 +150,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
             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.
@@ -173,7 +173,7 @@ 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 ${spawnedChild.exitCode}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
@@ -213,8 +213,8 @@ async function teardownPreflightChild(child, forwarder, closure, profileDir) {
         }
     }
     // 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);
@@ -226,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();
@@ -271,7 +271,7 @@ function attemptMarionetteConnect(port, connectFn) {
                 socket.destroy();
             }
             catch {
-                // Ignore — already closed.
+                // Ignore: already closed.
             }
             resolve({ ok });
         };
@@ -280,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(() => {
@@ -311,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