@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/core/coverage-extend.js

@@ -4,34 +4,34 @@
  * into the recorded `testPackagingCoverage` instead of replacing it, under
  * an anchor guard.
  *
- * Coverage REPLACES by default for a reason documented in
+ * Coverage replaces by default for a reason documented in
  * `build-baseline-types.ts`: every baseline write refreshes
- * `packageableFingerprints` for ALL dirty packageable paths, so a blind
+ * `packageableFingerprints` for all dirty packageable paths, so a blind
  * union would whitewash an earlier scope's edited fixtures while
  * `obj-*`/`_tests/` still holds that scope's stale staging. Extending is
- * honest only while everything the PREVIOUS record vouched for is still
+ * honest only while everything the previous record vouched for is still
  * true, which is what {@link checkExtendCoverageAnchor} and
  * {@link checkExtendMozconfigAnchor} verify:
  *
- *   1. engine HEAD is unchanged — every committed edit is excluded;
+ *   1. engine HEAD is unchanged, so every committed edit is excluded.
  *   2. every path the previous baseline fingerprinted still hashes to the
  *      recorded digest, so the earlier scope's staging inputs are
- *      byte-identical. Files that became dirty SINCE that build are fine:
+ *      byte-identical. Files that became dirty since that build are fine:
  *      the current whole-tree `mach build faster` repackages `dist/` and
- *      vouches for them;
+ *      vouches for them.
  *   3. the generated `engine/mozconfig` is unchanged. Engine HEAD does not
- *      cover this — the mozconfig is regenerated from project-side
+ *      cover this: the mozconfig is regenerated from project-side
  *      `configs/*.mozconfig` templates plus `fireforge.json` on every build,
  *      so two builds at the same engine SHA can configure differently.
  *
- * Every failure refuses fail-closed; the operator's remedy is always a plain
+ * Every failure refuses fail-closed. The operator's remedy is always a plain
  * scoped build, which resets the claim to the paths it actually vouches for.
  *
- * Known boundary, documented rather than closed: dirty NON-packageable
+ * Known boundary, documented rather than closed: dirty non-packageable
  * fixtures under previously covered paths (plain test files, manifests
  * `isPackageablePath` rejects) are invisible to check 2. Editing one
  * uncommitted between two builds leaves the earlier scope's `_tests/`
- * staging stale while extend still vouches for it. Plain REPLACE has no such
+ * staging stale while extend still vouches for it. Plain replacement has no such
  * window, because the earlier scope simply stops being covered.
  */
 import { readFile } from 'node:fs/promises';
@@ -88,10 +88,10 @@ export async function checkExtendCoverageAnchor(engineDir, previousBaseline) {
 }
 /**
  * Verifies the mozconfig half of the anchor. Split from
- * {@link checkExtendCoverageAnchor} because it can only run AFTER
- * `prepareBuildEnvironment` regenerates `engine/mozconfig` — that file is
- * the one this build will configure with — and must still run BEFORE mach,
- * so a refusal costs no build time.
+ * {@link checkExtendCoverageAnchor} because it can only run after
+ * `prepareBuildEnvironment` regenerates `engine/mozconfig` (the file this
+ * build will configure with), and must still run before mach, so a refusal
+ * costs no build time.
  * @param engineDir - Path to the engine directory
  * @param previousBaseline - Baseline recorded by the previous build
  */
@@ -108,7 +108,7 @@ export async function checkExtendMozconfigAnchor(engineDir, previousBaseline) {
 }
 /**
  * Unions the newly built paths onto the recorded claim. A `'full'` claim, or
- * an absent one (which means full), stays `'full'` — it already covers
+ * an absent one (which means full), stays `'full'`, since it already covers
  * everything.
  *
  * @param previous - Coverage recorded by the previous build
@@ -161,7 +161,7 @@ function formatDivergedPaths(paths) {
 /**
  * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
  * baseline writer produces. `undefined` on any IO error, which every caller
- * treats as "cannot prove unchanged" — i.e. a refusal.
+ * treats as "cannot prove unchanged", i.e. a refusal.
  * @param engineDir - Path to the engine directory
  * @param relPath - Engine-relative POSIX path
  */

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

@@ -17,7 +17,7 @@ export declare const HISTORY_LOG_FILENAME = ".fireforge-history.jsonl";
  * A structural conflict that must block the operation even under `--force`.
  *
  * Intended for cases like "reorder would introduce a forward-import" or
- * "delete would orphan a later patch's import" — situations where the
+ * "delete would orphan a later patch's import", situations where the
  * operator almost certainly wants a different fix (re-export --files, etc.)
  * rather than a bypass. `--force-unsafe` is the escape hatch when the
  * operator genuinely accepts the risk.
@@ -35,9 +35,9 @@ export interface DestructiveOpInput {
     /** Short one-line title shown in the prompt. */
     title: string;
     /**
-     * Detailed change summary — every affected patch, file, or renumber row.
-     * Generic "proceed? [y/N]" is insufficient per the destructive-op contract;
-     * callers must list every concrete change here.
+     * Detailed change summary: every affected patch, file, or renumber row.
+     * Generic "proceed? [y/N]" is insufficient per the destructive-op
+     * contract. Callers must list every concrete change here.
      */
     summary: string[];
     /** Whether the caller passed `--yes`. */
@@ -52,9 +52,9 @@ export interface DestructiveOpInput {
 /**
  * Outcome of the destructive-operation contract.
  *
- * `'declined'` means the operator answered "no" — a successful run that
+ * `'declined'` means the operator answered "no", a successful run that
  * chose not to proceed, so callers return normally and the process exits 0.
- * An INTERRUPT (Esc / Ctrl+C) is not represented here: it throws
+ * An interrupt (Esc / Ctrl+C) is not represented here: it throws
  * {@link CancellationError} and exits 130. Collapsing the two would make an
  * interrupted prompt indistinguishable from a declined one.
  */
@@ -73,11 +73,11 @@ export interface HistoryEntry {
     yes?: boolean;
     /** True if `--force-unsafe` was used. */
     unsafeOverride?: boolean;
-    /** Result: `'ok'` on success; other strings describe failure. */
+    /** Result: `'ok'` on success. Other strings describe failure. */
     result: string;
 }
 /**
- * True when BOTH standard handles are real TTYs, i.e. an interactive prompt
+ * True when both standard handles are real TTYs, i.e. an interactive prompt
  * can actually be answered.
  *
  * Named for the condition rather than for confirmation specifically: many
@@ -87,16 +87,16 @@ export interface HistoryEntry {
  * Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
  * (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
  * capture, CI spawners, mocked pipes) can also leave it unset on only one
- * handle, so every falsy variant — false, undefined, a null-patched mock —
+ * handle, so every falsy variant (false, undefined, a null-patched mock)
  * must route to the non-interactive path.
  */
 export declare function stdioIsInteractive(): boolean;
 /**
- * UP-FRONT non-interactive refusal for a command that will end at
+ * Up-front non-interactive refusal for a command that will end at
  * {@link confirmDestructive}.
  *
  * `confirmDestructive` already refuses a prompt-less run rather than
- * proceeding silently — but it does so at the END, after the command has
+ * proceeding silently, but it does so at the end, after the command has
  * built diffs and run projected per-patch lint. On `patch move-files
  * --create` that is minutes of work before a scripted run learns it needed
  * `--yes`, and the failure reads as an obscure late error rather than a
@@ -117,7 +117,7 @@ export declare function assertConfirmationAvailable(operation: string, options:
  * Executes the destructive-operation contract: summary → conflict refusal →
  * dry-run / force / prompt / non-TTY refusal.
  *
- * Returns the decision for the caller to act on; callers must not execute
+ * Returns the decision for the caller to act on. Callers must not execute
  * the mutation when the result is `'dry-run'` or `'declined'`, and must call
  * {@link appendHistory} only after the mutation succeeds (never on dry-run
  * or decline).
@@ -132,8 +132,8 @@ export declare function confirmDestructive(input: DestructiveOpInput): Promise<D
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log
- * is append-only and advisory — no code path reads it back; it exists purely
- * so operators have a post-hoc audit trail when something goes wrong.
+ * is append-only and advisory: no code path reads it back. It exists so
+ * operators have a post-hoc audit trail when something goes wrong.
  *
  * @param patchesDir - Path to the patches directory
  * @param entry - Serializable history record

package/dist/src/core/destructive.js

@@ -40,7 +40,7 @@ function printConflicts(conflicts) {
     }
 }
 /**
- * True when BOTH standard handles are real TTYs, i.e. an interactive prompt
+ * True when both standard handles are real TTYs, i.e. an interactive prompt
  * can actually be answered.
  *
  * Named for the condition rather than for confirmation specifically: many
@@ -50,7 +50,7 @@ function printConflicts(conflicts) {
  * Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
  * (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
  * capture, CI spawners, mocked pipes) can also leave it unset on only one
- * handle, so every falsy variant — false, undefined, a null-patched mock —
+ * handle, so every falsy variant (false, undefined, a null-patched mock)
  * must route to the non-interactive path.
  */
 export function stdioIsInteractive() {
@@ -59,11 +59,11 @@ export function stdioIsInteractive() {
     return stdinIsTTY === true && stdoutIsTTY === true;
 }
 /**
- * UP-FRONT non-interactive refusal for a command that will end at
+ * Up-front non-interactive refusal for a command that will end at
  * {@link confirmDestructive}.
  *
  * `confirmDestructive` already refuses a prompt-less run rather than
- * proceeding silently — but it does so at the END, after the command has
+ * proceeding silently, but it does so at the end, after the command has
  * built diffs and run projected per-patch lint. On `patch move-files
  * --create` that is minutes of work before a scripted run learns it needed
  * `--yes`, and the failure reads as an obscure late error rather than a
@@ -90,7 +90,7 @@ export function assertConfirmationAvailable(operation, options) {
  * Executes the destructive-operation contract: summary → conflict refusal →
  * dry-run / force / prompt / non-TTY refusal.
  *
- * Returns the decision for the caller to act on; callers must not execute
+ * Returns the decision for the caller to act on. Callers must not execute
  * the mutation when the result is `'dry-run'` or `'declined'`, and must call
  * {@link appendHistory} only after the mutation succeeds (never on dry-run
  * or decline).
@@ -146,8 +146,8 @@ export async function confirmDestructive(input) {
         message: `${title} — proceed?`,
         initialValue: false,
     });
-    // An INTERRUPT and a "no" are different outcomes and must not share an
-    // exit code. Esc / Ctrl+C is a real interrupt — 130 is 128+SIGINT and is
+    // An interrupt and a "no" are different outcomes and must not share an
+    // exit code. Esc / Ctrl+C is a real interrupt. 130 is 128+SIGINT and is
     // what a script needs to tell "the operator aborted" from "the operator
     // considered it and declined". Answering "no" is a successful run.
     //
@@ -165,8 +165,8 @@ export async function confirmDestructive(input) {
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log
- * is append-only and advisory — no code path reads it back; it exists purely
- * so operators have a post-hoc audit trail when something goes wrong.
+ * is append-only and advisory: no code path reads it back. It exists so
+ * operators have a post-hoc audit trail when something goes wrong.
  *
  * @param patchesDir - Path to the patches directory
  * @param entry - Serializable history record

package/dist/src/core/diff-hunks.d.ts

@@ -1,6 +1,6 @@
 /**
  * An edit op produced by {@link computeLineDiff}. Indices are 0-based into the
- * source line arrays; `line` holds the verbatim text so callers do not have to
+ * source line arrays. `line` holds the verbatim text so callers do not have to
  * keep the input arrays around while rendering.
  */
 export interface LineDiffOp {
@@ -60,7 +60,7 @@ export declare function buildHunks(ops: readonly LineDiffOp[], context: number):
 /**
  * Computes a multi-hunk line diff between two strings. This is the public
  * entry point that {@link furnaceDiffCommand} uses. On normal inputs this
- * runs the exact LCS path and returns a proper multi-hunk diff; on inputs
+ * runs the exact LCS path and returns a proper multi-hunk diff. On inputs
  * that exceed {@link LCS_LINE_LIMIT} it falls back to a single coalesced
  * hunk so the command stays useful instead of OOMing.
  */

package/dist/src/core/diff-hunks.js

@@ -5,7 +5,7 @@ import { assert, expectDefined } from '../utils/assert.js';
  * O(m·n) diff and falling back to the simpler single-region coalesce. Chosen
  * so the worst-case Int32Array allocation stays under ~16 MB. Typical
  * Firefox widget files are a few hundred lines, so the fast path handles the
- * everyday case; the fallback keeps the command usable on a very large file.
+ * everyday case. The fallback keeps the command usable on a very large file.
  */
 const LCS_LINE_LIMIT = 2000;
 /** Splits a string on `\n`, discarding a single trailing empty line from a terminal newline. */
@@ -31,7 +31,7 @@ export function computeLineDiff(oldLines, newLines) {
     // The DP below indexes `dp`, `oldLines`, and `newLines` about 4·m·n times
     // for a worst-case pair, so its bounds are established once here rather
     // than re-checked per access. Callers gate on LCS_LINE_LIMIT before
-    // reaching this function; if that gate is ever moved or removed, this is
+    // reaching this function. If that gate is ever moved or removed, this is
     // where the resulting allocation blow-up surfaces as a named failure
     // instead of an out-of-memory crash.
     assert(m <= LCS_LINE_LIMIT && n <= LCS_LINE_LIMIT, () => `line diff inputs are within LCS_LINE_LIMIT (got ${m}x${n}, limit ${LCS_LINE_LIMIT})`);
@@ -48,7 +48,7 @@ export function computeLineDiff(oldLines, newLines) {
      * above, so the non-null assertions encode a property already checked
      * once per call rather than one that is never checked at all. The
      * rendering loops further down, which run O(ops), use `expectDefined`
-     * instead — this exemption is for the quadratic block only.
+     * instead. This exemption is for the quadratic block only.
      */
     for (let i = 1; i <= m; i++) {
         const oldLine = oldLines[i - 1];
@@ -184,8 +184,8 @@ export function buildHunks(ops, context) {
  * Fallback for inputs that exceed {@link LCS_LINE_LIMIT}. Reproduces the
  * original single-region coalesce: match the common prefix and suffix, then
  * emit one hunk containing the middle region plus `context` lines on each
- * side. Intentionally dumb — the fast path handles normal files, and this
- * only keeps the command usable on pathologically large inputs without
+ * side. Kept simple on purpose: the fast path handles normal files, and
+ * this only keeps the command usable on pathologically large inputs without
  * allocating a huge DP table.
  */
 function coalescedHunk(oldLines, newLines, context) {
@@ -218,7 +218,7 @@ function coalescedHunk(oldLines, newLines, context) {
     for (let k = firstDiff; k <= lastNewDiff; k++) {
         hunkLines.push({ marker: '+', content: expectDefined(newLines[k], () => `new line ${k}`) });
     }
-    // Trailing context comes from the common suffix, which lives at DIFFERENT
+    // Trailing context comes from the common suffix, which lives at different
     // indices on each side (lastOldDiff+1… vs lastNewDiff+1…). Mixing the two
     // coordinate spaces emits wrong context on asymmetric edits and drops the
     // trailing lines from the @@ header lengths, so the rendered header
@@ -245,7 +245,7 @@ function coalescedHunk(oldLines, newLines, context) {
 /**
  * Computes a multi-hunk line diff between two strings. This is the public
  * entry point that {@link furnaceDiffCommand} uses. On normal inputs this
- * runs the exact LCS path and returns a proper multi-hunk diff; on inputs
+ * runs the exact LCS path and returns a proper multi-hunk diff. On inputs
  * that exceed {@link LCS_LINE_LIMIT} it falls back to a single coalesced
  * hunk so the command stays useful instead of OOMing.
  */

package/dist/src/core/discard-baseline.d.ts

@@ -2,15 +2,15 @@
  * Patch-aware restore planning for `fireforge discard`.
  *
  * The engine convention is: HEAD = pristine upstream Firefox, and the
- * applied patch queue lives as UNCOMMITTED worktree changes on top of it
+ * applied patch queue lives as uncommitted worktree changes on top of it
  * (`git apply` without `--index` → patch-edited tracked files are unstaged
  * modifications, patch-created files are untracked). A purely git-mechanical
- * discard — restore to HEAD, delete untracked files — therefore reverts
- * patch-backed files PAST their owning patch and deletes patch-created files
+ * discard (restore to HEAD, delete untracked files) therefore reverts
+ * patch-backed files past their owning patch and deletes patch-created files
  * outright.
  *
  * This module classifies each status entry against the patch manifest's
- * ownership claims and plans the correct restore target: the PATCH-APPLIED
+ * ownership claims and plans the correct restore target: the patch-applied
  * baseline (HEAD content folded through every affecting patch in order) for
  * claimed files, and the plain git mechanics for unmanaged ones.
  */
@@ -25,22 +25,22 @@ export interface DiscardBaselinePlan {
     owners: string[];
     /** True when more than one patch claims the path (ownership conflict). */
     conflicted: boolean;
-    /** Baseline content for `entry.file`; null = absent at baseline. Unset for 'unmanaged'. */
+    /** Baseline content for `entry.file` (null = absent at baseline). Unset for 'unmanaged'. */
     expectedContent?: string | null;
     /** Rename/copy only: baseline content for `originalPath` when that side is claimed. */
     expectedOriginalContent?: string | null;
 }
-/** Builds an all-unmanaged plan set — the `--to-upstream` (legacy) shape. */
+/** Builds an all-unmanaged plan set, the `--to-upstream` (legacy) shape. */
 export declare function planUpstreamDiscards(entries: readonly GitStatusEntry[]): DiscardBaselinePlan[];
 /**
  * Plans the restore target for each status entry. Entries claimed by the
- * patch manifest restore to the patch-applied baseline; unclaimed entries
+ * patch manifest restore to the patch-applied baseline. Unclaimed entries
  * keep the plain git mechanics. A missing patches dir or empty manifest
  * degrades every plan to `unmanaged`.
  *
- * A corrupt manifest or an unreconstructible patch baseline REFUSES with a
- * GeneralError naming `--to-upstream` — silently falling back to pristine
- * HEAD is exactly the data-loss path this module exists to close.
+ * A corrupt manifest or an unreconstructible patch baseline refuses with a
+ * GeneralError naming `--to-upstream`. Silently falling back to pristine
+ * HEAD is the data-loss path this module exists to close.
  */
 export declare function planDiscardBaselines(patchesDir: string, engineDir: string, entries: readonly GitStatusEntry[]): Promise<DiscardBaselinePlan[]>;
 /**

package/dist/src/core/discard-baseline.js

@@ -3,15 +3,15 @@
  * Patch-aware restore planning for `fireforge discard`.
  *
  * The engine convention is: HEAD = pristine upstream Firefox, and the
- * applied patch queue lives as UNCOMMITTED worktree changes on top of it
+ * applied patch queue lives as uncommitted worktree changes on top of it
  * (`git apply` without `--index` → patch-edited tracked files are unstaged
  * modifications, patch-created files are untracked). A purely git-mechanical
- * discard — restore to HEAD, delete untracked files — therefore reverts
- * patch-backed files PAST their owning patch and deletes patch-created files
+ * discard (restore to HEAD, delete untracked files) therefore reverts
+ * patch-backed files past their owning patch and deletes patch-created files
  * outright.
  *
  * This module classifies each status entry against the patch manifest's
- * ownership claims and plans the correct restore target: the PATCH-APPLIED
+ * ownership claims and plans the correct restore target: the patch-applied
  * baseline (HEAD content folded through every affecting patch in order) for
  * claimed files, and the plain git mechanics for unmanaged ones.
  */
@@ -24,19 +24,19 @@ import { createPatchedContentContext } from './patch-apply.js';
 import { loadPatchesManifestState } from './patch-manifest-io.js';
 import { parseDiffSections } from './patch-parse.js';
 import { buildPatchClaims } from './status-classify.js';
-/** Builds an all-unmanaged plan set — the `--to-upstream` (legacy) shape. */
+/** Builds an all-unmanaged plan set, the `--to-upstream` (legacy) shape. */
 export function planUpstreamDiscards(entries) {
     return entries.map((entry) => ({ entry, kind: 'unmanaged', owners: [], conflicted: false }));
 }
 /**
  * Plans the restore target for each status entry. Entries claimed by the
- * patch manifest restore to the patch-applied baseline; unclaimed entries
+ * patch manifest restore to the patch-applied baseline. Unclaimed entries
  * keep the plain git mechanics. A missing patches dir or empty manifest
  * degrades every plan to `unmanaged`.
  *
- * A corrupt manifest or an unreconstructible patch baseline REFUSES with a
- * GeneralError naming `--to-upstream` — silently falling back to pristine
- * HEAD is exactly the data-loss path this module exists to close.
+ * A corrupt manifest or an unreconstructible patch baseline refuses with a
+ * GeneralError naming `--to-upstream`. Silently falling back to pristine
+ * HEAD is the data-loss path this module exists to close.
  */
 export async function planDiscardBaselines(patchesDir, engineDir, entries) {
     const state = await loadPatchesManifestState(patchesDir);
@@ -71,7 +71,7 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
     // `computePatchedContent` folds a deletion into an empty string (an
     // apply-to-content limitation), which is indistinguishable from a
     // legitimately empty file. Consult the owning patches' diff sections
-    // directly: the LAST section (highest-ordered owner) naming the path
+    // directly: the last section (highest-ordered owner) naming the path
     // decides whether the baseline is "absent".
     const sectionCache = new Map();
     const isDeletedAtBaseline = async (path, owners) => {
@@ -86,11 +86,10 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
                 }
                 catch (error) {
                     // Fail closed. Swallowing this yields no sections, which falls
-                    // through to `return false` — "not deleted at baseline" — so a path
-                    // the owning patch DELETES would be restored as present, i.e.
+                    // through to `return false` ("not deleted at baseline"), so a
+                    // path the owning patch deletes would be restored as present, i.e.
                     // rewritten instead of removed: silent data loss on the command
-                    // whose header promises a refusal for exactly this class of
-                    // failure.
+                    // whose header promises a refusal for this class of failure.
                     //
                     // `computeExpected` above reads the same patch first and refuses,
                     // so this is defence-in-depth against a TOCTOU (the patch file
@@ -160,7 +159,7 @@ export async function applyDiscardBaseline(engineDir, plan) {
     }
     const { entry } = plan;
     // Drop any staged edits/adds/renames first so the rewritten content is a
-    // plain worktree state (harmless when nothing is staged; skipped for
+    // plain worktree state (harmless when nothing is staged, and skipped for
     // purely-untracked entries which have no index footprint).
     if (!entry.isUntracked) {
         const indexPaths = entry.originalPath !== undefined ? [entry.file, entry.originalPath] : [entry.file];
@@ -172,7 +171,7 @@ export async function applyDiscardBaseline(engineDir, plan) {
     else {
         await writeText(join(engineDir, entry.file), plan.expectedContent);
     }
-    // A rename/copy's original side restores to ITS baseline too: the patch
+    // A rename/copy's original side restores to its baseline too: the patch
     // baseline when claimed, else the legacy HEAD restore (matching what
     // discardStatusEntry does for that side).
     if (entry.originalPath !== undefined) {

package/dist/src/core/display-state.d.ts

@@ -3,15 +3,15 @@
  *
  * `TIMEOUT … application timed out after N seconds with no output` /
  * `Ran 0 checks` has three known causes, one of them purely environmental:
- * a HEADED run on an unattended machine whose display is asleep or locked.
+ * a headed run on an unattended machine whose display is asleep or locked.
  * A headed Firefox on a sleeping display never paints, never reaches its
- * first test, and dies at the no-output timeout — indistinguishable, from
- * the log alone, from a product hang.
+ * first test, and dies at the no-output timeout, which from the log alone
+ * is indistinguishable from a product hang.
  *
- * `caffeinate -disu` does not cure it. It PREVENTS sleep; it cannot WAKE a
- * display that is already asleep, so wrapping the run changes nothing once
- * the machine has dimmed. `fireforge test` defaults to headed, so an
- * unattended run walks straight into this.
+ * `caffeinate -disu` does not cure it. It prevents sleep, but it cannot
+ * wake a display that is already asleep, so wrapping the run changes
+ * nothing once the machine has dimmed. `fireforge test` defaults to
+ * headed, so an unattended run walks straight into this.
  *
  * The probe is advisory and fail-open: anything unexpected reports
  * `'unknown'` and the caller degrades to the generic triage list rather than
@@ -30,10 +30,10 @@ export type DisplaySleepState = 'asleep' | 'awake' | 'unknown';
  * ```
  *
  * Only the `IODisplayWrangler` row matters, and only its first numeric
- * column (the current power state). Any other shape — no such row, a
- * non-numeric column, an error message — is `'unknown'`, never a guess.
+ * column (the current power state). Any other shape (no such row, a
+ * non-numeric column, an error message) is `'unknown'`, never a guess.
  *
- * Pure; exported for direct unit testing.
+ * Pure. Exported for direct unit testing.
  *
  * @param stdout - Raw `pmset -g powerstate IODisplayWrangler` output
  * @returns The measured state, or `'unknown'`
@@ -41,7 +41,7 @@ export type DisplaySleepState = 'asleep' | 'awake' | 'unknown';
 export declare function parseDisplayPowerState(stdout: string): DisplaySleepState;
 /**
  * Probes the display's power state. Non-darwin platforms report `'unknown'`
- * without spawning anything — the stall shape this serves is macOS-specific
+ * without spawning anything: the stall shape this serves is macOS-specific
  * and no equivalent single-command probe is wired for other platforms.
  *
  * @param platform - `process.platform`-style id (injected for testability)

package/dist/src/core/display-state.js

@@ -4,15 +4,15 @@
  *
  * `TIMEOUT … application timed out after N seconds with no output` /
  * `Ran 0 checks` has three known causes, one of them purely environmental:
- * a HEADED run on an unattended machine whose display is asleep or locked.
+ * a headed run on an unattended machine whose display is asleep or locked.
  * A headed Firefox on a sleeping display never paints, never reaches its
- * first test, and dies at the no-output timeout — indistinguishable, from
- * the log alone, from a product hang.
+ * first test, and dies at the no-output timeout, which from the log alone
+ * is indistinguishable from a product hang.
  *
- * `caffeinate -disu` does not cure it. It PREVENTS sleep; it cannot WAKE a
- * display that is already asleep, so wrapping the run changes nothing once
- * the machine has dimmed. `fireforge test` defaults to headed, so an
- * unattended run walks straight into this.
+ * `caffeinate -disu` does not cure it. It prevents sleep, but it cannot
+ * wake a display that is already asleep, so wrapping the run changes
+ * nothing once the machine has dimmed. `fireforge test` defaults to
+ * headed, so an unattended run walks straight into this.
  *
  * The probe is advisory and fail-open: anything unexpected reports
  * `'unknown'` and the caller degrades to the generic triage list rather than
@@ -25,7 +25,7 @@ import { exec } from '../utils/process.js';
 const DISPLAY_PROBE_TIMEOUT_MS = 5_000;
 /**
  * IOKit power state at which `IODisplayWrangler` is fully lit. Lower
- * states are dimmed or off; macOS reports 4 for a live display.
+ * states are dimmed or off. macOS reports 4 for a live display.
  */
 const DISPLAY_AWAKE_POWER_STATE = 4;
 /**
@@ -39,10 +39,10 @@ const DISPLAY_AWAKE_POWER_STATE = 4;
  * ```
  *
  * Only the `IODisplayWrangler` row matters, and only its first numeric
- * column (the current power state). Any other shape — no such row, a
- * non-numeric column, an error message — is `'unknown'`, never a guess.
+ * column (the current power state). Any other shape (no such row, a
+ * non-numeric column, an error message) is `'unknown'`, never a guess.
  *
- * Pure; exported for direct unit testing.
+ * Pure. Exported for direct unit testing.
  *
  * @param stdout - Raw `pmset -g powerstate IODisplayWrangler` output
  * @returns The measured state, or `'unknown'`
@@ -61,7 +61,7 @@ export function parseDisplayPowerState(stdout) {
 }
 /**
  * Probes the display's power state. Non-darwin platforms report `'unknown'`
- * without spawning anything — the stall shape this serves is macOS-specific
+ * without spawning anything: the stall shape this serves is macOS-specific
  * and no equivalent single-command probe is wired for other platforms.
  *
  * @param platform - `process.platform`-style id (injected for testability)

package/dist/src/core/engine-changes.d.ts

@@ -6,7 +6,7 @@
 import type { BuildBaseline } from './build-baseline-types.js';
 /**
  * Collects engine-relative paths changed since the baseline's HEAD SHA,
- * plus any workdir modifications (tracked and untracked). Defensive — git
+ * plus any workdir modifications (tracked and untracked). Defensive: git
  * failures surface as verbose lines and return the files collected so far,
  * so an empty result means "no drift we can prove" rather than "no drift
  * occurred". When the baseline is missing or the engine has no HEAD yet,
@@ -27,7 +27,7 @@ export declare function collectChangedEnginePaths(engineDir: string, baseline: B
  * full-build escalation in `build-prepare` (`buildInputFingerprints`).
  *
  * A path with no recorded entry, an unreadable file, or a differing hash
- * is kept — "cannot prove unchanged" must never turn into "unchanged".
+ * is kept, since "cannot prove unchanged" must never turn into "unchanged".
  * With no fingerprint set at all (a baseline written before the field
  * existed) every path is kept, which is the path-only comparison the
  * fingerprints refine.

package/dist/src/core/engine-changes.js

@@ -12,7 +12,7 @@ import { git } from './git-base.js';
 import { getUntrackedFiles } from './git-status.js';
 /**
  * Collects engine-relative paths changed since the baseline's HEAD SHA,
- * plus any workdir modifications (tracked and untracked). Defensive — git
+ * plus any workdir modifications (tracked and untracked). Defensive: git
  * failures surface as verbose lines and return the files collected so far,
  * so an empty result means "no drift we can prove" rather than "no drift
  * occurred". When the baseline is missing or the engine has no HEAD yet,
@@ -67,7 +67,7 @@ export async function collectChangedEnginePaths(engineDir, baseline, contextLabe
  * full-build escalation in `build-prepare` (`buildInputFingerprints`).
  *
  * A path with no recorded entry, an unreadable file, or a differing hash
- * is kept — "cannot prove unchanged" must never turn into "unchanged".
+ * is kept, since "cannot prove unchanged" must never turn into "unchanged".
  * With no fingerprint set at all (a baseline written before the field
  * existed) every path is kept, which is the path-only comparison the
  * fingerprints refine.

package/dist/src/core/engine-precondition.d.ts

@@ -14,13 +14,13 @@
 export interface EngineGitReadyOptions {
     /**
      * Appended to the unborn-HEAD remediation, e.g. `', then retry the rebase.'`
-     * The base message deliberately ends WITHOUT punctuation so the suffix
-     * reads as one sentence; callers that pass nothing get a plain full stop.
+     * The base message ends without punctuation on purpose so the suffix
+     * reads as one sentence. Callers that pass nothing get a plain full stop.
      */
     unbornHeadSuffix?: string;
 }
 /**
- * Asserts only that the engine checkout EXISTS.
+ * Asserts only that the engine checkout exists.
  *
  * The first rung of {@link assertEngineGitReady}. Most callers want exactly
  * this rung and no more: `build`, `run`, `test`, `package`, `watch`,
@@ -33,7 +33,7 @@ export interface EngineGitReadyOptions {
 export declare function assertEngineExists(engineDir: string): Promise<void>;
 /**
  * Asserts that `engineDir` exists, is a git repository, and has a baseline
- * commit — in that order, so the operator gets the most specific applicable
+ * commit, in that order, so the operator gets the most specific applicable
  * remediation rather than a downstream git error.
  *
  * @param engineDir - Absolute path to the engine checkout

package/dist/src/core/engine-precondition.js

@@ -21,7 +21,7 @@ const UNBORN_HEAD_REMEDIATION = 'Engine repository has no baseline commit yet
     // hardcoding one here rendered as "…cleanly., then retry the rebase."
     'Re-run "fireforge download --force" to recreate the baseline repository cleanly';
 /**
- * Asserts only that the engine checkout EXISTS.
+ * Asserts only that the engine checkout exists.
  *
  * The first rung of {@link assertEngineGitReady}. Most callers want exactly
  * this rung and no more: `build`, `run`, `test`, `package`, `watch`,
@@ -38,7 +38,7 @@ export async function assertEngineExists(engineDir) {
 }
 /**
  * Asserts that `engineDir` exists, is a git repository, and has a baseline
- * commit — in that order, so the operator gets the most specific applicable
+ * commit, in that order, so the operator gets the most specific applicable
  * remediation rather than a downstream git error.
  *
  * @param engineDir - Absolute path to the engine checkout