@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/commands/test-modes.js

@@ -45,7 +45,7 @@ export function canaryTimeoutSeconds(projectConfig) {
 /** Emits or throws the one-word canary verdict. */
 export function reportCanaryOutcome(outcome) {
     // Written raw as the run's last stdout line on green and throw paths
-    // alike — see the FIREFORGE-VERDICT contract in test-harness-crash.ts.
+    // alike. See the FIREFORGE-VERDICT contract in test-harness-crash.ts.
     try {
         if (outcome.verdict.kind === 'tests-ran-ok') {
             success('Canary: green');
@@ -97,16 +97,16 @@ function buildMixedHarnessMessage(classification) {
  * dispatch, so refusing it before spending minutes in a pre-test build
  * is strictly better. A nonexistent path classifies as
  * nonXpcshell (findNearestXpcshellManifest returns null), so classifying
- * before assertTestPathsExist is harmless — existence is still asserted
+ * before assertTestPathsExist is harmless: existence is still asserted
  * after the stale/coverage gates, preserving their precedence over
  * missing-path errors. `xpcshellOnly` (non-empty request, zero
  * nonXpcshell paths) gates the Marionette preflight and the mochitest
- * client flags; pathless runs keep the full-suite behavior.
+ * client flags. Pathless runs keep the full-suite behavior.
  */
 export async function classifyBeforeDispatch(engineDir, normalizedPaths, options) {
     const classification = await classifyTestHarnesses(engineDir, normalizedPaths);
     if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
-        // `--build-only` never dispatches, so a mixed request is legal there —
+        // `--build-only` never dispatches, so a mixed request is legal there:
         // packaging the union is the whole point.
         if (options?.allowMixed !== true) {
             throw new GeneralError(buildMixedHarnessMessage(classification));

package/dist/src/commands/test-run.d.ts

@@ -3,10 +3,10 @@
  * sequential per-file sharding of multi-path invocations.
  *
  * Sharding exists because passing several browser-chrome files to one mach
- * invocation destabilizes later files — cross-file profile/pref bleed in the
+ * invocation destabilizes later files: cross-file profile/pref bleed in the
  * shared mochitest profile makes the second file time out at window-open
  * while each file passes in isolation. Sequential single-file harness runs
- * cost startup time but make results reproducible; the combined invocation
+ * cost startup time but make results reproducible. The combined invocation
  * stays available via `--no-shard`.
  */
 import { type DisplaySleepState } from '../core/display-state.js';
@@ -54,8 +54,8 @@ export interface TestRunOutcome {
     /** Whether xpcshell appdir injection was attempted for this invocation. */
     appdirInjectionAttempted: boolean;
     /**
-     * Display power state measured for a HEADED no-output stall;
-     * undefined when the shape did not apply and no probe ran.
+     * Display power state measured for a HEADED no-output stall. Undefined
+     * when the shape did not apply and no probe ran.
      */
     displayState?: DisplaySleepState | undefined;
 }
@@ -68,7 +68,7 @@ export declare function runTestsWithRetries(ctx: TestRunContext, paths: string[]
 /**
  * One sequential harness invocation of a sharded run: a requested path
  * argument and the mach paths dispatched for it. A file argument is a group
- * of one; a directory argument groups its enumerated test files so the whole
+ * of one. A directory argument groups its enumerated test files so the whole
  * directory still runs in ONE browser instance, keeping cross-file state
  * behaviour within a directory run.
  */
@@ -88,25 +88,25 @@ export interface ShardedRunSummary {
     shards: ShardOutcome[];
     passed: number;
     total: number;
-    /** Aggregate classifier verdict — see {@link deriveAggregateShardVerdict}. */
+    /** Aggregate classifier verdict. See {@link deriveAggregateShardVerdict}. */
     aggregate: HarnessRunVerdict;
 }
 /**
  * Derives the aggregate classification for a sharded run: all-green is
- * `tests-ran-ok`; otherwise the most structural failure wins — a crashed
+ * `tests-ran-ok`. Otherwise the most structural failure wins. A crashed
  * shard makes the whole run `harness-crash`, then `no-tests`, then plain
- * `test-failures` — so the aggregate `reason=` keeps the classifier-driven
+ * `test-failures`, so the aggregate `reason=` keeps the classifier-driven
  * contract instead of collapsing every failure to `test-failures`.
  */
 export declare function deriveAggregateShardVerdict(shards: ShardOutcome[]): HarnessRunVerdict;
 /**
  * Runs each requested path argument as its own sequential harness
  * invocation (a directory argument's enumerated files stay together in
- * one invocation — see {@link ShardGroup}) and prints an aggregate
+ * one invocation, see {@link ShardGroup}) and prints an aggregate
  * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
  * (which receives the throwing diagnosis chain from the command layer)
  * but downgraded to warnings so every shard runs. The aggregate verdict
- * line and the aggregate error are NOT produced here — the caller runs
+ * line and the aggregate error are not produced here: the caller runs
  * the engine-generation integrity check first and then calls
  * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
  * `engine/` mutation can never print `PASS` before the check fails.
@@ -114,7 +114,7 @@ export declare function deriveAggregateShardVerdict(shards: ShardOutcome[]): Har
 export declare function runShardedTests(ctx: TestRunContext, groups: ShardGroup[], diagnoseShardFailure: (outcome: TestRunOutcome, label: string) => string | undefined): Promise<ShardedRunSummary>;
 /**
  * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
- * throws the aggregate error when any shard did not pass — the same
+ * throws the aggregate error when any shard did not pass, the same
  * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
  * the engine-generation check succeeded.
  */

package/dist/src/commands/test-run.js

@@ -4,10 +4,10 @@
  * sequential per-file sharding of multi-path invocations.
  *
  * Sharding exists because passing several browser-chrome files to one mach
- * invocation destabilizes later files — cross-file profile/pref bleed in the
+ * invocation destabilizes later files: cross-file profile/pref bleed in the
  * shared mochitest profile makes the second file time out at window-open
  * while each file passes in isolation. Sequential single-file harness runs
- * cost startup time but make results reproducible; the combined invocation
+ * cost startup time but make results reproducible. The combined invocation
  * stays available via `--no-shard`.
  */
 import { probeDisplaySleepState } from '../core/display-state.js';
@@ -38,16 +38,16 @@ function machKindForSuite(suite) {
  * stale-xpcshell-symlink repair path the single-run flow already used.
  */
 export async function runTestsWithRetries(ctx, paths) {
-    // Pure mochitest dispatches keep their env byte-identical — the profile
+    // Pure mochitest dispatches keep their env byte-identical, since the profile
     // variable is xpcshell-harness-specific. Generic `mach
     // test` runs may include xpcshell paths, so they get the isolation too.
     if (ctx.suite === 'mochitest') {
         return runTestsWithRetriesInner(ctx, paths, ctx.env);
     }
     // Fresh profile dir per harness invocation: shards isolate from each
-    // other and from concurrent `fireforge test` processes; the crash /
-    // symlink-repair retries inside one invocation deliberately REUSE the
-    // same directory (they are the same logical run and the harness
+    // other and from concurrent `fireforge test` processes. The crash /
+    // symlink-repair retries inside one invocation reuse the same directory
+    // on purpose (they are the same logical run and the harness
     // re-initialises the profile contents itself).
     return withXpcshellProfileDir(ctx.env, (env) => runTestsWithRetriesInner(ctx, paths, env));
 }
@@ -88,7 +88,7 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
             `Retrying (attempt ${attempts + 1} of ${maxAttempts})...`);
     }
     // A verdict whose every unexpected result is time-driven pref noise is
-    // still a FAIL — only the note changes, so a `unexpected=2` line is not
+    // still a FAIL. Only the note changes, so a `unexpected=2` line is not
     // read as two real assertion failures.
     if (verdict.kind === 'test-failures' && verdict.note === undefined) {
         const prefNote = changedPrefNoiseVerdictNote(`${result.stdout}\n${result.stderr}`);
@@ -108,9 +108,9 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
     return { result, verdict, attempts, appdirInjectionAttempted, displayState };
 }
 /**
- * Probes the display's power state for a HEADED no-output stall, and only for
- * that shape. Every other outcome — a passing run, a real test failure, a
- * headless run, any other crash shape — skips the probe entirely, so the
+ * Probes the display's power state for a headed no-output stall, and only for
+ * that shape. Every other outcome (a passing run, a real test failure, a
+ * headless run, any other crash shape) skips the probe entirely, so the
  * common paths spawn nothing.
  *
  * @returns The measured state, or undefined when the shape does not apply
@@ -132,9 +132,9 @@ const SHARD_STATUS_LABEL = {
 };
 /**
  * Derives the aggregate classification for a sharded run: all-green is
- * `tests-ran-ok`; otherwise the most structural failure wins — a crashed
+ * `tests-ran-ok`. Otherwise the most structural failure wins. A crashed
  * shard makes the whole run `harness-crash`, then `no-tests`, then plain
- * `test-failures` — so the aggregate `reason=` keeps the classifier-driven
+ * `test-failures`, so the aggregate `reason=` keeps the classifier-driven
  * contract instead of collapsing every failure to `test-failures`.
  */
 export function deriveAggregateShardVerdict(shards) {
@@ -150,11 +150,11 @@ export function deriveAggregateShardVerdict(shards) {
 /**
  * Runs each requested path argument as its own sequential harness
  * invocation (a directory argument's enumerated files stay together in
- * one invocation — see {@link ShardGroup}) and prints an aggregate
+ * one invocation, see {@link ShardGroup}) and prints an aggregate
  * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
  * (which receives the throwing diagnosis chain from the command layer)
  * but downgraded to warnings so every shard runs. The aggregate verdict
- * line and the aggregate error are NOT produced here — the caller runs
+ * line and the aggregate error are not produced here: the caller runs
  * the engine-generation integrity check first and then calls
  * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
  * `engine/` mutation can never print `PASS` before the check fails.
@@ -193,7 +193,7 @@ export async function runShardedTests(ctx, groups, diagnoseShardFailure) {
 }
 /**
  * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
- * throws the aggregate error when any shard did not pass — the same
+ * throws the aggregate error when any shard did not pass, the same
  * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
  * the engine-generation check succeeded.
  */

package/dist/src/commands/test-stale-gate.d.ts

@@ -3,40 +3,40 @@
  * and a run against a stale or under-packaged runtime: the packaging
  * coverage refusal, the stale-content refusal, and the compiled
  * StaticComponents refusal. Split out of `test.ts` so the command module
- * stays wiring; the probes and refusal copy live in
+ * stays wiring. The probes and refusal copy live in
  * `src/core/test-stale-check.ts`.
  */
 import type { BuildBaseline } from '../core/build-baseline-types.js';
 import type { TestOptions } from '../types/commands/index.js';
 /**
- * Stale-build preflight — when `--build` was NOT requested, detect packageable
- * engine edits since the last successful build and fail UP-FRONT unless the
+ * Stale-build preflight: when `--build` was not requested, detect packageable
+ * engine edits since the last successful build and fail up front unless the
  * operator explicitly accepts the stale package risk.
  *
- * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * Packaging coverage is checked first, on every non-`--build` run and
  * regardless of staleness or `--allow-stale-build`: a runtime packaged by a
- * file-scoped `test --build` can lack support fixtures for OTHER manifests
- * even when nothing changed since — dispatching such a run hangs on missing
+ * file-scoped `test --build` can lack support fixtures for other manifests
+ * even when nothing changed since, and dispatching such a run hangs on missing
  * fixtures rather than failing, so the flag (which only accepts stale
- * CONTENT) must not be the trigger. A three-file scoped rebuild leaving one
+ * content) must not be the trigger. A three-file scoped rebuild leaving one
  * fixture unpackaged makes a later run over different files time out waiting
  * on an event that never fires.
  *
  * Exception: a path-less `test --doctor` stops at the Marionette health check
  * (`runDoctorPreflight` returns 'stop' when no test paths were given) and
- * never dispatches a test, so it needs no packaging coverage — treating it as
+ * never dispatches a test, so it needs no packaging coverage. Treating it as
  * a full-suite request would refuse a probe that touches no fixtures. The
  * stale-content refusal still applies to it unchanged.
  */
 export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[]): Promise<void>;
 /**
- * Compiled-StaticComponents gate — refuses runs whose child process would
+ * Compiled-StaticComponents gate: refuses runs whose child process would
  * resolve a stale compiled component table. `components.conf` entries bake
- * into compiled code that only a FULL build regenerates; a scoped
+ * into compiled code that only a full build regenerates. A scoped
  * `test --build` repackages the file but the failure surfaces as
  * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
- * (after the coverage refusal) AND to scoped `test --build` runs (before
- * the pre-test build — that build cannot fix the table). A path-less
+ * (after the coverage refusal) and to scoped `test --build` runs (before
+ * the pre-test build, which cannot fix the table). A path-less
  * `test --build` is exempt: its full build refreshes the anchor itself.
  * `--allow-stale-components` downgrades the refusal to a warning.
  */

package/dist/src/commands/test-stale-gate.js

@@ -4,29 +4,29 @@
  * and a run against a stale or under-packaged runtime: the packaging
  * coverage refusal, the stale-content refusal, and the compiled
  * StaticComponents refusal. Split out of `test.ts` so the command module
- * stays wiring; the probes and refusal copy live in
+ * stays wiring. The probes and refusal copy live in
  * `src/core/test-stale-check.ts`.
  */
 import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
 import { PreflightRefusalError } from '../errors/base.js';
 import { warn } from '../utils/logger.js';
 /**
- * Stale-build preflight — when `--build` was NOT requested, detect packageable
- * engine edits since the last successful build and fail UP-FRONT unless the
+ * Stale-build preflight: when `--build` was not requested, detect packageable
+ * engine edits since the last successful build and fail up front unless the
  * operator explicitly accepts the stale package risk.
  *
- * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * Packaging coverage is checked first, on every non-`--build` run and
  * regardless of staleness or `--allow-stale-build`: a runtime packaged by a
- * file-scoped `test --build` can lack support fixtures for OTHER manifests
- * even when nothing changed since — dispatching such a run hangs on missing
+ * file-scoped `test --build` can lack support fixtures for other manifests
+ * even when nothing changed since, and dispatching such a run hangs on missing
  * fixtures rather than failing, so the flag (which only accepts stale
- * CONTENT) must not be the trigger. A three-file scoped rebuild leaving one
+ * content) must not be the trigger. A three-file scoped rebuild leaving one
  * fixture unpackaged makes a later run over different files time out waiting
  * on an event that never fires.
  *
  * Exception: a path-less `test --doctor` stops at the Marionette health check
  * (`runDoctorPreflight` returns 'stop' when no test paths were given) and
- * never dispatches a test, so it needs no packaging coverage — treating it as
+ * never dispatches a test, so it needs no packaging coverage. Treating it as
  * a full-suite request would refuse a probe that touches no fixtures. The
  * stale-content refusal still applies to it unchanged.
  */
@@ -37,7 +37,7 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
         const recordedCoverage = stale.baseline?.testPackagingCoverage;
         const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
         if (uncovered.length > 0) {
-            // The refusal is correct on its own; naming the manifest that gained
+            // The refusal is correct on its own. Naming the manifest that gained
             // an entry is the triage step it otherwise leaves to the reader.
             const changedManifests = await findChangedTestManifestsForPaths(engineDir, stale.baseline, uncovered);
             throw new PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests), 'coverage-replaced');
@@ -64,13 +64,13 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
     }
 }
 /**
- * Compiled-StaticComponents gate — refuses runs whose child process would
+ * Compiled-StaticComponents gate: refuses runs whose child process would
  * resolve a stale compiled component table. `components.conf` entries bake
- * into compiled code that only a FULL build regenerates; a scoped
+ * into compiled code that only a full build regenerates. A scoped
  * `test --build` repackages the file but the failure surfaces as
  * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
- * (after the coverage refusal) AND to scoped `test --build` runs (before
- * the pre-test build — that build cannot fix the table). A path-less
+ * (after the coverage refusal) and to scoped `test --build` runs (before
+ * the pre-test build, which cannot fix the table). A path-less
  * `test --build` is exempt: its full build refreshes the anchor itself.
  * `--allow-stale-components` downgrades the refusal to a warning.
  */

package/dist/src/commands/test-verdict.d.ts

@@ -1,7 +1,7 @@
 import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
 /**
  * Reason codes the emission layer can put on a `FIREFORGE-VERDICT: FAIL`
- * line. The first three mirror the harness classifier; `preflight` covers
+ * line. The first three mirror the harness classifier. `preflight` covers
  * every failure before harness classification (missing/stale builds,
  * invalid paths, port conflicts, config errors, spawn failures),
  * `inconclusive` marks a run whose harness result exists but cannot be
@@ -34,12 +34,12 @@ export declare function emitPassVerdict(): void;
  * Emits a FAIL verdict carrying an emission-layer reason code, and
  * optionally the refusal class that produced it.
  *
- * `note=` is ADDITIVE, like the `log=`, `signal=` and `shards=` keys already
+ * `note=` is additive, like the `log=`, `signal=` and `shards=` keys already
  * on this line: `reason=` is unchanged and still comes from the closed set
  * in `docs/machine-output.md`, so a consumer that tokenises `key=value`
  * pairs is unaffected. It exists because `reason=preflight` covers every
- * gate before the harness — a missing build, a peer's packaging record, a
- * developer browser holding the objdir — and an unattended reader whose
+ * gate before the harness (a missing build, a peer's packaging record, a
+ * developer browser holding the objdir), and an unattended reader whose
  * pipe kept only the verdict line could not tell those apart.
  *
  * @param reason - Closed-set verdict reason
@@ -49,8 +49,8 @@ export declare function emitFailVerdict(reason: FireforgeVerdictReason, note?: s
 /**
  * Emits the terminal verdict for a run killed by a signal.
  *
- * Without it a killed run wrote NO terminal line, so a log tail could not
- * distinguish "killed" from "still running" from "never started" — recovery
+ * Without it a killed run wrote no terminal line, so a log tail could not
+ * distinguish "killed" from "still running" from "never started". Recovery
  * meant checking `ps` and the lock file by hand, at the exact moment (a
  * mass kill under a usage limit, mid-drain) when the tree's state most
  * needs to be readable. A no-op unless a run was actually in flight: the

package/dist/src/commands/test-verdict.js

@@ -27,21 +27,21 @@ export function verdictEmitted() {
     return emitted;
 }
 /**
- * Writes the run's single verdict line — raw stdout (clack's renderer can
- * drop output under non-TTY capture), first write wins. Every later call
+ * Writes the run's single verdict line to raw stdout (clack's renderer can
+ * drop output under non-TTY capture). First write wins. Every later call
  * is a no-op: the writer closest to the harness result runs first, so the
  * fallback layers (the engine-generation guard, the preflight wrapper)
  * can emit unconditionally without risking a second line. Writing also
- * seals stdout: the verdict must stay the run's LAST stdout write, so all
- * subsequent logger output — including the CLI-boundary error/cancel
- * rendering after an emit-then-throw path — routes to stderr.
+ * seals stdout: the verdict must stay the run's last stdout write, so all
+ * subsequent logger output, including the CLI-boundary error/cancel
+ * rendering after an emit-then-throw path, routes to stderr.
  */
 function writeVerdictLine(line) {
     if (emitted)
         return;
     emitted = true;
     // The run log's path rides the verdict line because the verdict must stay
-    // the run's LAST stdout write — a separate announcement after it would
+    // the run's last stdout write: a separate announcement after it would
     // break that contract, and one before it is the first thing a `tail` cuts.
     // Appended as an additive `key=value`, so consumers that tokenize the line
     // are unaffected and a truncated tail still says where the full output is.
@@ -65,12 +65,12 @@ export function emitPassVerdict() {
  * Emits a FAIL verdict carrying an emission-layer reason code, and
  * optionally the refusal class that produced it.
  *
- * `note=` is ADDITIVE, like the `log=`, `signal=` and `shards=` keys already
+ * `note=` is additive, like the `log=`, `signal=` and `shards=` keys already
  * on this line: `reason=` is unchanged and still comes from the closed set
  * in `docs/machine-output.md`, so a consumer that tokenises `key=value`
  * pairs is unaffected. It exists because `reason=preflight` covers every
- * gate before the harness — a missing build, a peer's packaging record, a
- * developer browser holding the objdir — and an unattended reader whose
+ * gate before the harness (a missing build, a peer's packaging record, a
+ * developer browser holding the objdir), and an unattended reader whose
  * pipe kept only the verdict line could not tell those apart.
  *
  * @param reason - Closed-set verdict reason
@@ -83,8 +83,8 @@ export function emitFailVerdict(reason, note) {
 /**
  * Emits the terminal verdict for a run killed by a signal.
  *
- * Without it a killed run wrote NO terminal line, so a log tail could not
- * distinguish "killed" from "still running" from "never started" — recovery
+ * Without it a killed run wrote no terminal line, so a log tail could not
+ * distinguish "killed" from "still running" from "never started". Recovery
  * meant checking `ps` and the lock file by hand, at the exact moment (a
  * mass kill under a usage limit, mid-drain) when the tree's state most
  * needs to be readable. A no-op unless a run was actually in flight: the

package/dist/src/commands/test.d.ts

@@ -4,9 +4,9 @@ import type { TestOptions } from '../types/commands/index.js';
  *
  * Owns the run's exactly-one-`FIREFORGE-VERDICT:`-line guarantee: the sink
  * is re-armed at entry, and any failure that reaches this boundary without
- * an inner writer having emitted — the preflight ladder (missing engine or
- * build, config errors, stale-build and port gates, missing paths), and a
- * harness process that failed to start — emits `FAIL reason=preflight`,
+ * an inner writer having emitted (the preflight ladder: missing engine or
+ * build, config errors, stale-build and port gates, missing paths, and a
+ * harness process that failed to start) emits `FAIL reason=preflight`,
  * since no harness classification exists for such a run. Writers closer to
  * the harness (doctor, canary, single, sharded, the engine-generation
  * guard) emit first and win.

package/dist/src/commands/test.js

@@ -42,7 +42,7 @@ async function assertTestPathsExist(engineDir, testPaths) {
  * auto-routes to the suite-specific command (`mach xpcshell-test` /
  * `mach mochitest`), which degrades a broken host resource monitor to a
  * warning instead of crashing generic `mach test` at startup. Mixed runs are
- * rejected before this point; a path-less "run all" or an explicit
+ * rejected before this point. A path-less "run all" or an explicit
  * `--generic-mach-test` opt-out stays on the generic command.
  */
 function resolveTestSuite(classification, forceGeneric) {
@@ -102,14 +102,14 @@ function logTestSelection(scopes) {
 }
 /**
  * Runs the `--doctor` marionette handshake probe. With no test paths the
- * probe is the entire command (returns `'stop'` after reporting); with
- * paths it gates the mach invocation — a FAIL throws before mach runs.
+ * probe is the entire command (returns `'stop'` after reporting). With
+ * paths it gates the mach invocation, where a FAIL throws before mach runs.
  */
 async function runDoctorPreflight(args) {
     const { engineDir, effectivePort, hasTestPaths, objDir, binaryName, launchablePath } = args;
     // Non-TTY captures need the banner even if clack's renderer defers output
-    // in pipe mode; TTY users need the clack framing. Gated rather than
-    // written twice — the unconditional pair printed the same line twice on a
+    // in pipe mode. TTY users need the clack framing. Gated rather than
+    // written twice: the unconditional pair printed the same line twice on a
     // terminal.
     if (process.stdout.isTTY) {
         info('Running marionette preflight...');
@@ -125,7 +125,7 @@ async function runDoctorPreflight(args) {
     // can drop the summary under non-TTY capture.
     //
     // Gated on non-TTY: unconditional, it stacks with the two clack renderings
-    // below and the same line appears THREE times on a terminal. Captured
+    // below and the same line appears three times on a terminal. Captured
     // streams are exactly where this branch still fires.
     const directLine = formatMarionettePreflightLine(preflight);
     if (!process.stdout.isTTY) {
@@ -139,7 +139,7 @@ async function runDoctorPreflight(args) {
             throw new GeneralError('Marionette preflight reported FAIL — see output above.');
         }
         // Doctor-only runs end here, so they carry their own verdict line
-        // (reason=preflight on failure); with test paths the verdict comes
+        // (reason=preflight on failure). With test paths the verdict comes
         // from the actual harness run downstream.
         emitPassVerdict();
         outro('Test completed');
@@ -161,12 +161,12 @@ async function runDoctorPreflight(args) {
 function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly = false) {
     // Auto-forward the Marionette port to mach when `--marionette-port` is set.
     // `--setpref=marionette.port=<n>` configures where the browser listener
-    // binds; `--marionette=127.0.0.1:<n>` tells the mochitest harness client to
+    // binds. `--marionette=127.0.0.1:<n>` tells the mochitest harness client to
     // connect there (default client is 127.0.0.1:2828). xpcshell ignores both
     // for browser Marionette.
     //
     // Skip setpref forwarding when the operator already supplied an equivalent
-    // arg via `--mach-arg` — duplicates would confuse without changing
+    // arg via `--mach-arg`: duplicates would confuse without changing
     // semantics. Skip when mach args explicitly request `--flavor=xpcshell` (or
     // `xpcshell-tests`): the preflight still honours `--marionette-port`, but
     // mach does not use the marionette.port pref on that harness. Any other arg
@@ -178,7 +178,7 @@ function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcsh
     if (options.marionettePort === undefined)
         return;
     if (xpcshellOnly) {
-        // Manifest classification says every requested path is xpcshell —
+        // Manifest classification says every requested path is xpcshell.
         // xpcshell ignores the browser Marionette path entirely, and forwarding
         // the mochitest client flags here makes mach reject the dispatch.
         info(`--marionette-port=${options.marionettePort} applied to the preflight probe only: the requested paths are xpcshell-only, and xpcshell ignores the browser Marionette port. Not forwarding --setpref=marionette.port or --marionette to mach.`);
@@ -272,9 +272,9 @@ const TEST_BUILD_PREFLIGHT = {
  *
  * Owns the run's exactly-one-`FIREFORGE-VERDICT:`-line guarantee: the sink
  * is re-armed at entry, and any failure that reaches this boundary without
- * an inner writer having emitted — the preflight ladder (missing engine or
- * build, config errors, stale-build and port gates, missing paths), and a
- * harness process that failed to start — emits `FAIL reason=preflight`,
+ * an inner writer having emitted (the preflight ladder: missing engine or
+ * build, config errors, stale-build and port gates, missing paths, and a
+ * harness process that failed to start) emits `FAIL reason=preflight`,
  * since no harness classification exists for such a run. Writers closer to
  * the harness (doctor, canary, single, sharded, the engine-generation
  * guard) emit first and win.
@@ -285,7 +285,7 @@ const TEST_BUILD_PREFLIGHT = {
 export async function testCommand(projectRoot, testPaths, options = {}) {
     intro('FireForge Test');
     resetVerdictEmission();
-    // Opened before ANY work so a preflight refusal is logged too — those are
+    // Opened before any work so a preflight refusal is logged too. Those are
     // exactly the runs whose only output a `tail` throws away. Closed in
     // `finally`, after the verdict line has already read the path.
     setActiveRunLog(await openRunLog(projectRoot, 'test'));
@@ -308,14 +308,14 @@ function refusalNote(error) {
     return error instanceof PreflightRefusalError ? error.note : undefined;
 }
 /**
- * Puts a preflight refusal's own text on the operator's channel BEFORE the
+ * Puts a preflight refusal's own text on the operator's channel before the
  * verdict line, and into the run log.
  *
- * Both halves are load-bearing, and neither happened before:
+ * Both halves matter, and neither happened before:
  *
  *  - `withErrorHandling` renders `error.userMessage` back in `cli.ts`, but
- *    by then `emitFailVerdict` has called `setStdoutSealed(true)` — the seal
- *    that keeps the verdict the LAST stdout write — so `logError` routes to
+ *    by then `emitFailVerdict` has called `setStdoutSealed(true)`, the seal
+ *    that keeps the verdict the last stdout write, so `logError` routes to
  *    stderr. A run captured with `> file` therefore kept the verdict and
  *    dropped the reason.
  *  - That same rendering happens after this function's caller returns, and
@@ -333,15 +333,15 @@ function renderPreflightRefusal(error) {
     const block = `Preflight refused:\n${text}\n`;
     // Raw stdout rather than the clack logger: this must land on the captured
     // stream verbatim, and clack's renderer can drop output under non-TTY
-    // capture — the same reason the verdict line is written this way.
+    // capture, the same reason the verdict line is written this way.
     process.stdout.write(block);
     writeToActiveRunLog(block);
 }
 /**
  * Verifies `engine/` did not change under the run before any PASS verdict
- * may print. On failure the run's verdict is `FAIL reason=inconclusive` —
- * the harness result exists but cannot be trusted (`preflight` would
- * misdescribe a run whose harness already executed) — emitted here so the
+ * may print. On failure the run's verdict is `FAIL reason=inconclusive`,
+ * because the harness result exists but cannot be trusted (`preflight` would
+ * misdescribe a run whose harness already executed). It is emitted here so the
  * guard's throw can never leave a stale or missing verdict line behind.
  */
 async function verifyEngineGenerationOrEmitInconclusive(engineDir, before) {
@@ -361,7 +361,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     const buildCheck = await hasBuildArtifacts(paths.engine);
     assertBuildArtifacts(paths.engine, buildCheck, TEST_BUILD_PREFLIGHT);
     // Inside a verification tree, only the objdir the marker records was
-    // proven rewritten-and-reconfigured to the tree; refuse any other.
+    // proven rewritten-and-reconfigured to the tree. Refuse any other.
     await assertObjdirMatchesTreeMarker(projectRoot, buildCheck.objDir);
     // Load the project config once so both the build and the port
     // probe have access to `binaryName` (the port probe uses it to
@@ -369,11 +369,11 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     const projectConfig = await loadConfig(projectRoot);
     const canaryPath = resolveCanaryPath(options, projectConfig);
     assertTestModeCombinations(testPaths, options, canaryPath);
-    // `hasBuildArtifacts` only confirms `obj-*/dist/` exists; a partial build
+    // `hasBuildArtifacts` only confirms `obj-*/dist/` exists. A partial build
     // (linker failed, packaging step interrupted) can satisfy that check
     // without ever writing the launchable binary the marionette preflight
     // needs to spawn. `fireforge run` already uses `hasRunnableBundle` to fail
-    // fast with a precise message; mirroring it here makes `test --doctor`
+    // fast with a precise message. Mirroring it here makes `test --doctor`
     // against an incomplete build surface the missing-bundle path instead of a
     // cryptic `Browser process exited during spawn (exit code 1, signal none).
     // stderr tail: (empty)`.
@@ -382,8 +382,8 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     // Normalized engine-relative request paths, hoisted above the build/stale
     // gate: the pre-test build records them as the packaging-coverage claim,
     // and the --allow-stale-build path checks the request against the
-    // recorded coverage. (Existence is still asserted later, after the gate —
-    // stale/coverage refusals keep precedence over missing-path errors.)
+    // recorded coverage. (Existence is still asserted later, after the gate,
+    // so stale/coverage refusals keep precedence over missing-path errors.)
     const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
     const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
     const { classification, xpcshellOnly } = await classifyBeforeDispatch(paths.engine, normalizedPaths, { allowMixed: options.buildOnly === true });
@@ -433,22 +433,22 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     }
     // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
     // flags FireForge does not model directly (see the xpcshell appdir hint
-    // above for why). Appended AFTER --headless so mach sees
+    // above for why). Appended after --headless so mach sees
     // the FireForge-managed flags first and the escape-valve ones last, which
     // keeps the override precedence predictable.
     if (forwardedMachArgs.length > 0) {
         extraArgs.push(...forwardedMachArgs);
     }
     appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
-    // Directory arguments mean EXACTLY that directory: mozbuild's test
+    // Directory arguments mean exactly that directory: mozbuild's test
     // resolver matches paths by string prefix, so a bare directory arg
-    // silently sweeps in prefix-named siblings — `…/test/hominis` also running
-    // `…/test/hominis-tiles`, with no indication the scope widened. Each
+    // silently sweeps in prefix-named siblings, with `…/test/hominis` also
+    // running `…/test/hominis-tiles`, with no indication the scope widened. Each
     // directory argument therefore dispatches as its enumerated explicit
-    // test-file list, which cannot prefix-match a sibling; a trailing-`/`
+    // test-file list, which cannot prefix-match a sibling. A trailing-`/`
     // normalization does not work, as mach still sweeps the sibling in. Any
     // prefix-siblings are echoed so the narrowed scope is visible.
-    // Classification above intentionally used the raw argument forms; only the
+    // Classification above intentionally used the raw argument forms. Only the
     // mach dispatch needs the exact-match shape.
     const scopes = await analyzeTestPathScopes(paths.engine, normalizedPaths);
     const dispatchGroups = scopes.map((scope) => ({
@@ -482,10 +482,10 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         : undefined;
     // Multi-argument requests shard into sequential harness runs by default:
     // one shared mochitest profile across files bleeds pref/media-query state
-    // into later files. Sharding is per path ARGUMENT — a directory argument
+    // into later files. Sharding is per path argument: a directory argument
     // keeps its enumerated files together in one invocation, preserving the
     // one-browser-instance semantics of a directory run. `--no-shard` restores
-    // the combined invocation. The default must not be SILENT: a cross-file
+    // the combined invocation. The default must not be silent: a cross-file
     // pollution repro otherwise "passes" because the comparison run was
     // sharded without saying so, misattributing a suite-context bug upstream.
     // Hence the one-line notice stating what sharding does and does not
@@ -500,7 +500,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
             summary = await runShardedTests(runCtx, dispatchGroups, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, postRebuildContext));
         }
         finally {
-            // Runs BEFORE the aggregate verdict below: a mutated engine/ emits
+            // Runs before the aggregate verdict below: a mutated engine/ emits
             // `FAIL reason=inconclusive` and throws, so an invalidated run can
             // never print `PASS shards=N/N` first. (A throw here masks an
             // in-flight shard error, as the plain assert always did.)