@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/mach-mozconfig.d.ts

@@ -10,7 +10,7 @@ export interface MozconfigVariables {
 }
 /**
  * Extracts the `--with-branding=<path>` value from a rendered mozconfig
- * body. Returns `undefined` when no directive is present — callers treat
+ * body. Returns `undefined` when no directive is present, and callers treat
  * that as "mozconfig is missing branding", which is itself an actionable
  * configuration error.
  *
@@ -18,13 +18,13 @@ export interface MozconfigVariables {
  */
 export declare function extractWithBrandingPath(mozconfigContent: string): string | undefined;
 /**
- * Extracts the objdir NAME a mozconfig declares — the single trailing path
+ * Extracts the objdir name a mozconfig declares: the single trailing path
  * segment, which is what the `obj-*` scan enumerates.
  *
  * `@TOPSRCDIR@` and a leading `./` are both spellings of "beside the
- * source", which is the only arrangement FireForge's scan can see anyway;
- * an absolute path outside the engine directory reduces to its basename and
- * simply will not match a candidate, which is the correct outcome — a
+ * source", which is the only arrangement FireForge's scan can see anyway.
+ * An absolute path outside the engine directory reduces to its basename and
+ * simply will not match a candidate, which is the correct outcome. A
  * declaration that names something the scan cannot see must not select
  * anything.
  *
@@ -33,7 +33,7 @@ export declare function extractWithBrandingPath(mozconfigContent: string): strin
 export declare function extractMozObjdirName(mozconfigContent: string): string | undefined;
 /**
  * Preflights the just-written mozconfig against the branding tree FireForge
- * set up. A drift between the two is silent-corruption territory — the
+ * set up. A drift between the two is silent-corruption territory: the
  * build runs, `mach configure` reads the stale directory name out of
  * mozconfig, and then the recursive make backend errors out with a "path
  * does not exist" message that names the branding dir the mozconfig

package/dist/src/core/mach-mozconfig.js

@@ -21,17 +21,17 @@ function replaceVariables(content, variables) {
 }
 /**
  * Matches an `--with-branding=<path>` directive anywhere in a rendered
- * mozconfig. The directive form is the one mach reads; an optional
+ * mozconfig. The directive form is the one mach reads, and an optional
  * `ac_add_options` prefix is the on-disk convention. `m` flag anchors the
  * search per-line so a multi-line mozconfig with older directives earlier
- * in the file doesn't confuse the extractor. We pick the LAST match
+ * in the file doesn't confuse the extractor. We pick the last match
  * because mach itself takes the last-write-wins semantics of shell
  * configuration for overlapping `ac_add_options` calls.
  */
 const WITH_BRANDING_PATTERN = /^\s*(?:ac_add_options\s+)?--with-branding\s*=\s*(\S+)/gm;
 /**
  * Extracts the `--with-branding=<path>` value from a rendered mozconfig
- * body. Returns `undefined` when no directive is present — callers treat
+ * body. Returns `undefined` when no directive is present, and callers treat
  * that as "mozconfig is missing branding", which is itself an actionable
  * configuration error.
  *
@@ -51,13 +51,13 @@ export function extractWithBrandingPath(mozconfigContent) {
  */
 const MOZ_OBJDIR_PATTERN = /^\s*(?:mk_add_options\s+|export\s+)?MOZ_OBJDIR\s*=\s*["']?([^"'\s#]+)/gm;
 /**
- * Extracts the objdir NAME a mozconfig declares — the single trailing path
+ * Extracts the objdir name a mozconfig declares: the single trailing path
  * segment, which is what the `obj-*` scan enumerates.
  *
  * `@TOPSRCDIR@` and a leading `./` are both spellings of "beside the
- * source", which is the only arrangement FireForge's scan can see anyway;
- * an absolute path outside the engine directory reduces to its basename and
- * simply will not match a candidate, which is the correct outcome — a
+ * source", which is the only arrangement FireForge's scan can see anyway.
+ * An absolute path outside the engine directory reduces to its basename and
+ * simply will not match a candidate, which is the correct outcome. A
  * declaration that names something the scan cannot see must not select
  * anything.
  *
@@ -74,7 +74,7 @@ export function extractMozObjdirName(mozconfigContent) {
 }
 /**
  * Preflights the just-written mozconfig against the branding tree FireForge
- * set up. A drift between the two is silent-corruption territory — the
+ * set up. A drift between the two is silent-corruption territory: the
  * build runs, `mach configure` reads the stale directory name out of
  * mozconfig, and then the recursive make backend errors out with a "path
  * does not exist" message that names the branding dir the mozconfig
@@ -94,7 +94,7 @@ export async function assertBrandingMozconfigAgreement(engineDir, mozconfigPath,
     if (!found) {
         throw new BrandingMozconfigMismatchError(expected, '(no --with-branding directive)', 'mozconfig-missing-branding');
     }
-    // Normalise both sides to forward slashes before compare — Windows-edited
+    // Normalise both sides to forward slashes before compare. Windows-edited
     // configs can carry backslash path separators that the build would treat
     // as literal characters in a repo-relative path.
     const normalizedFound = normalizePathSlashes(found);
@@ -127,9 +127,9 @@ export async function generateMozconfig(configsDir, engineDir, config) {
         binaryName: config.binaryName,
     };
     let content = '';
-    // Bundle identity: branding configure.sh carries only the LEAF of appId
-    // (see splitAppId in branding.ts — upstream composes the mac bundle id as
-    // <distribution-id>.<MOZ_MACBUNDLE_ID>); the prefix travels here so the
+    // Bundle identity: branding configure.sh carries only the leaf of appId
+    // (see splitAppId in branding.ts, and upstream composes the mac bundle id
+    // as <distribution-id>.<MOZ_MACBUNDLE_ID>). The prefix travels here so the
     // two halves can never drift apart.
     const { distributionId } = splitAppId(config.appId);
     content +=
@@ -146,11 +146,11 @@ export async function generateMozconfig(configsDir, engineDir, config) {
     }
     const platformContent = await readText(platformPath);
     content += `# Platform configuration (${platform})\n${replaceVariables(platformContent, variables)}`;
-    // Write-if-changed: `mozconfig` is a mach CONFIGURE INPUT, so
-    // its mtime — not its content — is what `config.status` compares against.
+    // Write-if-changed: `mozconfig` is a mach configure input, so its mtime,
+    // not its content, is what `config.status` compares against.
     // Rewriting a byte-identical file on every build-capable invocation made
     // mach re-run `configure` plus backend regeneration ("Backend config
-    // changed; N files touched") on EVERY run, each run re-arming the next.
+    // changed; N files touched") on every run, each run re-arming the next.
     // Only touch the file when the rendered content actually differs.
     const wrote = await writeTextIfChanged(outputPath, content);
     if (!wrote) {

package/dist/src/core/mach-python.d.ts

@@ -1,7 +1,8 @@
 /**
  * Resets the resolved Python executable. Primarily useful for testing.
  *
- * @internal Exported only so tests can reach it; not part of the public surface.
+ * @internal Exported only so tests can reach it. Not part of the public
+ * surface.
  */
 export declare function resetResolvedPython(): void;
 /**

package/dist/src/core/mach-python.js

@@ -8,8 +8,8 @@ import { exec, executableExists } from '../utils/process.js';
 /** Cached Python resolution state */
 /**
  * The resolved interpreter and the requirement range it was resolved for.
- * `undefined` means "not resolved yet"; the two always move together, so one
- * nullable record beats two independently-deletable fields.
+ * `undefined` means "not resolved yet". The two always move together, so
+ * one nullable record beats two independently-deletable fields.
  */
 let pythonCache;
 const DEFAULT_MACH_PYTHON_REQUIREMENTS = {
@@ -79,7 +79,8 @@ function buildPythonCandidates(requirements) {
 /**
  * Resets the resolved Python executable. Primarily useful for testing.
  *
- * @internal Exported only so tests can reach it; not part of the public surface.
+ * @internal Exported only so tests can reach it. Not part of the public
+ * surface.
  */
 export function resetResolvedPython() {
     pythonCache = undefined;

package/dist/src/core/mach-resource-shim.d.ts

@@ -12,7 +12,7 @@
  *
  * The guard is installed as a `fireforge_mach_guard.pth` + module pair in
  * every discovered mach virtualenv site-packages directory. A PYTHONPATH
- * `sitecustomize.py` is NOT sufficient on its own: mach re-execs itself into
+ * `sitecustomize.py` is not sufficient on its own: mach re-execs itself into
  * its private virtualenv and drops PYTHONPATH, so that route never loads.
  * `.pth` files execute at interpreter startup from the venv's own
  * site-packages, which survives the re-exec. The PYTHONPATH copy is retained
@@ -21,12 +21,12 @@
  *
  * The guard covers the whole crash family:
  *  - wraps `psutil.virtual_memory` / `swap_memory` / `cpu_percent` /
- *    `cpu_times` / `disk_io_counters` module-wide, so every call site —
+ *    `cpu_times` / `disk_io_counters` module-wide, so every call site,
  *    including the direct `psutil.virtual_memory()` in
- *    `mozbuild.base._run_make` — degrades to a `UserWarning` and a zeroed
+ *    `mozbuild.base._run_make`, degrades to a `UserWarning` and a zeroed
  *    reading instead of aborting.
  *
- *    The fallback must be per-function ARITY-CORRECT and reconstructible:
+ *    The fallback must be per-function arity-correct and reconstructible:
  *    mozsystemmonitor captures reading types at `__init__`
  *    (`self._swap_type = type(psutil.swap_memory())`) and rebuilds each
  *    collector sample via `self._swap_type(*swap_mem)`. An svmem-shaped
@@ -36,28 +36,28 @@
  *    sentinel, and mach hangs forever in its atexit `waitpid`. Each wrapped
  *    function therefore degrades to a zeroed instance of psutil's own result
  *    namedtuple where resolvable, else a module-level guard-owned namedtuple
- *    with the exact field order and arity for THAT function (module-level so
+ *    with the exact field order and arity for that function (module-level so
  *    readings pickle by reference across the collector pipe).
  *    `_DegradedReading` remains only as a documented last resort and
  *    tolerates `type(reading)(*values)` reconstruction. Guard-owned fallback
  *    classes never depend on psutil internals resolving, which also makes
  *    them safe when two guard copies load (PYTHONPATH `sitecustomize` in the
- *    bootstrap phase plus the in-venv `.pth`), each with its own classes;
- *  - guards `SystemResourceMonitor` CONSTRUCTION via an import hook:
+ *    bootstrap phase plus the in-venv `.pth`), each with its own classes.
+ *  - guards `SystemResourceMonitor` construction via an import hook:
  *    `poll_interval` is pre-populated before the real `__init__` runs, a
  *    failing `__init__` marks the instance degraded instead of raising, and
- *    every monitor method no-ops on a degraded instance — so a
+ *    every monitor method no-ops on a degraded instance, so a
  *    partially-constructed monitor can never surface the
  *    `AttributeError: poll_interval` variant. Degraded aggregate methods
  *    return zeroed shapes (not `None`) where callers subscript the result
  *    (`aggregate_io` → zeroed io reading, so mozbuild's `log_resource_usage`
- *    does not die on `usage["io"].read_bytes` after a successful compile);
+ *    does not die on `usage["io"].read_bytes` after a successful compile).
  *  - suppresses the mozsystemmonitor collector child on degradation: once
  *    any psutil degradation is observed in the process, monitors are kept
  *    inert (`start` never spawns the collector), and a degraded transition
  *    or raising `stop` best-effort terminates a live collector child and
  *    drains the pipe, so a malformed sample stream cannot wedge mach's
- *    shutdown even if a future shape mismatch slips through;
+ *    shutdown even if a future shape mismatch slips through.
  *  - wraps `mozbuild.controller.building.BuildMonitor.log_resource_usage` to
  *    warn-and-continue on any exception, so end-of-build resource reporting
  *    can never fail a build whose artifacts are complete.
@@ -87,7 +87,7 @@ export interface MachResourceGuardInstallation {
  * Refuses a shim directory that is not a private directory of the current
  * user. `lstat`, not `stat`: a symlink planted at the path would otherwise
  * be followed and the check would describe its target. On Windows only the
- * "is a real directory" half applies — there is no POSIX owner or mode bit
+ * "is a real directory" half applies. There is no POSIX owner or mode bit
  * to read, and the per-user name is the isolation.
  *
  * @param dir - Shim directory that {@link ensureSitecustomizeFallback} created
@@ -100,7 +100,7 @@ export declare function assertPrivateShimDir(dir: string): Promise<void>;
  * `fireforge_mach_guard.pth` + `fireforge_mach_guard.py` into every
  * discovered mach virtualenv site-packages (survives mach's venv re-exec),
  * plus the PYTHONPATH sitecustomize fallback for the pre-venv bootstrap
- * phase. Idempotent and re-run before EVERY protected dispatch (including
+ * phase. Idempotent and re-run before every protected dispatch (including
  * each retry) so a venv created by a crashed first attempt is guarded on
  * the next one instead of re-dying on the same wedged state.
  */

package/dist/src/core/mach-resource-shim.js

@@ -13,7 +13,7 @@
  *
  * The guard is installed as a `fireforge_mach_guard.pth` + module pair in
  * every discovered mach virtualenv site-packages directory. A PYTHONPATH
- * `sitecustomize.py` is NOT sufficient on its own: mach re-execs itself into
+ * `sitecustomize.py` is not sufficient on its own: mach re-execs itself into
  * its private virtualenv and drops PYTHONPATH, so that route never loads.
  * `.pth` files execute at interpreter startup from the venv's own
  * site-packages, which survives the re-exec. The PYTHONPATH copy is retained
@@ -22,12 +22,12 @@
  *
  * The guard covers the whole crash family:
  *  - wraps `psutil.virtual_memory` / `swap_memory` / `cpu_percent` /
- *    `cpu_times` / `disk_io_counters` module-wide, so every call site —
+ *    `cpu_times` / `disk_io_counters` module-wide, so every call site,
  *    including the direct `psutil.virtual_memory()` in
- *    `mozbuild.base._run_make` — degrades to a `UserWarning` and a zeroed
+ *    `mozbuild.base._run_make`, degrades to a `UserWarning` and a zeroed
  *    reading instead of aborting.
  *
- *    The fallback must be per-function ARITY-CORRECT and reconstructible:
+ *    The fallback must be per-function arity-correct and reconstructible:
  *    mozsystemmonitor captures reading types at `__init__`
  *    (`self._swap_type = type(psutil.swap_memory())`) and rebuilds each
  *    collector sample via `self._swap_type(*swap_mem)`. An svmem-shaped
@@ -37,28 +37,28 @@
  *    sentinel, and mach hangs forever in its atexit `waitpid`. Each wrapped
  *    function therefore degrades to a zeroed instance of psutil's own result
  *    namedtuple where resolvable, else a module-level guard-owned namedtuple
- *    with the exact field order and arity for THAT function (module-level so
+ *    with the exact field order and arity for that function (module-level so
  *    readings pickle by reference across the collector pipe).
  *    `_DegradedReading` remains only as a documented last resort and
  *    tolerates `type(reading)(*values)` reconstruction. Guard-owned fallback
  *    classes never depend on psutil internals resolving, which also makes
  *    them safe when two guard copies load (PYTHONPATH `sitecustomize` in the
- *    bootstrap phase plus the in-venv `.pth`), each with its own classes;
- *  - guards `SystemResourceMonitor` CONSTRUCTION via an import hook:
+ *    bootstrap phase plus the in-venv `.pth`), each with its own classes.
+ *  - guards `SystemResourceMonitor` construction via an import hook:
  *    `poll_interval` is pre-populated before the real `__init__` runs, a
  *    failing `__init__` marks the instance degraded instead of raising, and
- *    every monitor method no-ops on a degraded instance — so a
+ *    every monitor method no-ops on a degraded instance, so a
  *    partially-constructed monitor can never surface the
  *    `AttributeError: poll_interval` variant. Degraded aggregate methods
  *    return zeroed shapes (not `None`) where callers subscript the result
  *    (`aggregate_io` → zeroed io reading, so mozbuild's `log_resource_usage`
- *    does not die on `usage["io"].read_bytes` after a successful compile);
+ *    does not die on `usage["io"].read_bytes` after a successful compile).
  *  - suppresses the mozsystemmonitor collector child on degradation: once
  *    any psutil degradation is observed in the process, monitors are kept
  *    inert (`start` never spawns the collector), and a degraded transition
  *    or raising `stop` best-effort terminates a live collector child and
  *    drains the pipe, so a malformed sample stream cannot wedge mach's
- *    shutdown even if a future shape mismatch slips through;
+ *    shutdown even if a future shape mismatch slips through.
  *  - wraps `mozbuild.controller.building.BuildMonitor.log_resource_usage` to
  *    warn-and-continue on any exception, so end-of-build resource reporting
  *    can never fail a build whose artifacts are complete.
@@ -73,7 +73,7 @@ import { verbose } from '../utils/logger.js';
 /**
  * Prefix of the per-user directory (under the OS temp dir) holding the
  * PYTHONPATH fallback. The uid (or, on Windows, the username) is appended:
- * a FIXED name under a shared `/tmp` lets any other local account pre-create
+ * a fixed name under a shared `/tmp` lets any other local account pre-create
  * the directory and own the `sitecustomize.py` that every mach dispatch
  * then imports.
  */
@@ -531,10 +531,10 @@ async function discoverMachSitePackages(engineDir) {
 /**
  * Per-user discriminator for the shim directory name. The numeric uid on
  * POSIX, read via `process.getuid` rather than `os.userInfo()`: the latter
- * resolves the passwd entry and THROWS (`ERR_SYSTEM_ERROR`) for a uid that
- * has none — `docker --user 1001:1001`, OpenShift's random uids, many CI
- * agents — which would take every build and test dispatch down with a raw
- * system error. On Windows there is no uid; the username is the
+ * resolves the passwd entry and throws (`ERR_SYSTEM_ERROR`) for a uid that
+ * has none (`docker --user 1001:1001`, OpenShift's random uids, many CI
+ * agents), which would take every build and test dispatch down with a raw
+ * system error. On Windows there is no uid. The username is the
  * discriminator, with `userInfo()` still guarded because the same lookup
  * can fail there for a service account, falling back to the environment.
  */
@@ -559,7 +559,7 @@ function resourceShimDir() {
  * Refuses a shim directory that is not a private directory of the current
  * user. `lstat`, not `stat`: a symlink planted at the path would otherwise
  * be followed and the check would describe its target. On Windows only the
- * "is a real directory" half applies — there is no POSIX owner or mode bit
+ * "is a real directory" half applies. There is no POSIX owner or mode bit
  * to read, and the per-user name is the isolation.
  *
  * @param dir - Shim directory that {@link ensureSitecustomizeFallback} created
@@ -588,13 +588,13 @@ export async function assertPrivateShimDir(dir) {
 /**
  * Writes the PYTHONPATH `sitecustomize.py` fallback into a per-user,
  * mode-0700 FireForge-owned temp directory, verified private before the
- * write, and returns that directory. Idempotent — overwriting each call
+ * write, and returns that directory. Idempotent: overwriting each call
  * keeps it in sync with this source across upgrades.
  */
 async function ensureSitecustomizeFallback() {
     const dir = resourceShimDir();
     // `mode` only applies when mkdir creates the directory (and is masked by
-    // the umask); a pre-existing one keeps whatever it had, which is exactly
+    // the umask). A pre-existing one keeps whatever it had, which is exactly
     // what the assertion below refuses if it is not private.
     await mkdir(dir, { recursive: true, mode: 0o700 });
     await assertPrivateShimDir(dir);
@@ -615,7 +615,7 @@ function machResourceShimEnv(shimDir, baseEnv = process.env) {
  * `fireforge_mach_guard.pth` + `fireforge_mach_guard.py` into every
  * discovered mach virtualenv site-packages (survives mach's venv re-exec),
  * plus the PYTHONPATH sitecustomize fallback for the pre-venv bootstrap
- * phase. Idempotent and re-run before EVERY protected dispatch (including
+ * phase. Idempotent and re-run before every protected dispatch (including
  * each retry) so a venv created by a crashed first attempt is guarded on
  * the next one instead of re-dying on the same wedged state.
  */
@@ -627,7 +627,7 @@ export async function installMachResourceGuard(engineDir) {
             await writeText(join(sitePackages, `${GUARD_MODULE_NAME}.pth`), `import ${GUARD_MODULE_NAME}\n`);
         }
         catch (error) {
-            // A read-only or vanished venv must not block the dispatch; the
+            // A read-only or vanished venv must not block the dispatch. The
             // PYTHONPATH fallback still applies and other venvs may have taken
             // the guard.
             verbose(`Could not install mach resource guard into ${sitePackages}: ${toError(error).message}`);

package/dist/src/core/mach.d.ts

@@ -18,17 +18,17 @@ export interface MachOptions {
     /** Whether to inherit stdio (show output directly) */
     inherit?: boolean;
     /**
-     * Collapse the KNOWN mozsystemmonitor teardown traceback to one labeled
-     * line in the terminal ECHO (capture-only option). The captured
-     * stdout/stderr stay raw — the harness classifier depends on the raw
+     * Collapse the known mozsystemmonitor teardown traceback to one labeled
+     * line in the terminal echo (capture-only option). The captured
+     * stdout/stderr stay raw, because the harness classifier depends on the raw
      * traceback. Unrecognized tracebacks always echo verbatim. Opted into by
      * the test dispatchers only.
      *
-     * Consumed by {@link runMachCapture} ALONE. `runMachInheritCapture` accepts
-     * it in the type and ignores it — the inherit path has no per-chunk hook,
+     * Consumed by {@link runMachCapture} alone. `runMachInheritCapture` accepts
+     * it in the type and ignores it: the inherit path has no per-chunk hook,
      * only a mirror stream that feeds the terminal and the run log the same
      * string, so filtering there would strip the traceback from the raw log
-     * too. The build path uses the recognition NOTE instead; see
+     * too. The build path uses the recognition note instead. See
      * `mach-known-noise-filter.ts`.
      */
     annotateKnownTeardownNoise?: boolean;
@@ -92,20 +92,20 @@ export interface ProtectedMachBuildResult extends MachCommandResult {
 }
 /**
  * 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.
  */
@@ -116,8 +116,8 @@ export declare function runProtectedMachBuild(kind: ProtectedBuildKind, engineDi
  * 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
@@ -141,13 +141,13 @@ export declare function buildUI(engineDir: string): Promise<ProtectedMachBuildRe
  *
  * 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.
@@ -185,7 +185,7 @@ export interface RunMachSmokeOptions {
  * 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.
@@ -206,7 +206,7 @@ export declare function machPackageCapture(engineDir: string): Promise<MachComma
  * `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
@@ -232,7 +232,7 @@ export type MachTestSuiteKind = 'test' | 'xpcshell-test' | 'mochitest';
 export interface MachTestSuiteOptions {
     /** Absolute path to the engine checkout. */
     engineDir: string;
-    /** Test paths to pass to the mach command; empty runs the default set. */
+    /** Test paths to pass to the mach command. Empty runs the default set. */
     testPaths?: string[];
     /** Extra mach arguments appended after the paths. */
     args?: string[];
@@ -251,8 +251,8 @@ export interface MachTestSuiteOptions {
 /**
  * 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