@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/commands/doctor-orphaned-harness.js

@@ -1,21 +1,20 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Doctor check for PRE-EXISTING orphaned test-harness workers.
+ * Doctor check for pre-existing orphaned test-harness workers.
  *
  * A mach invocation that dies at harness startup can strand a Python
- * `multiprocessing` spawn worker plus its resource tracker; the worker
+ * `multiprocessing` spawn worker plus its resource tracker. The worker
  * reparents to launchd (PPID 1) and busy-spins at 100% CPU indefinitely.
- * The dispatch-side fix is the process-group reaping in `utils/process.ts`;
- * this check covers orphans that predate it (or leaked from non-FireForge
+ * The dispatch-side fix is the process-group reaping in `utils/process.ts`.
+ * This check covers orphans that predate it (or leaked from non-FireForge
  * invocations), detecting them by PPID 1 + large accumulated CPU TIME + a
  * `multiprocessing.spawn`/`resource_tracker` command line.
  *
- * Report-only by design: FireForge never kills pre-existing processes it did
- * not spawn — the check names each candidate and suggests the kill.
+ * Report-only: FireForge never kills pre-existing processes it did not
+ * spawn, so the check names each candidate and suggests the kill.
  *
- * Deliberately not wired into `test --canary`: a system-wide process scan on
- * the canary hot path buys no coverage the doctor check does not already
- * give.
+ * Not wired into `test --canary`: a system-wide process scan on the canary
+ * hot path buys no coverage the doctor check does not already give.
  */
 import { toError } from '../utils/errors.js';
 import { exec } from '../utils/process.js';
@@ -29,19 +28,11 @@ import { ok, warning } from './doctor-check-core.js';
 const HARNESS_WORKER_COMMAND_PATTERN = /multiprocessing\.(?:spawn|forkserver)\b|multiprocessing\.resource_tracker|from multiprocessing\.\w+ import/;
 /** Minimum accumulated CPU time before a match is reported (10 minutes). */
 const DEFAULT_MIN_CPU_SECONDS = 600;
-/**
- * Parses a `ps` TIME (accumulated CPU) value. Implemented in terms of
- * {@link parsePsDuration} — `time=` and `etime=` share one grammar, and a
- * second copy is how the two would drift.
- */
-export function parseCpuTime(time) {
-    return parsePsDuration(time);
-}
 /**
  * Scans `ps -axo pid=,ppid=,time=,command=` output for orphaned harness
  * workers: PPID 1 (reparented to init/launchd), a multiprocessing
  * worker/tracker command line, and at least `minCpuSeconds` of accumulated
- * CPU time. Pure — fixture-testable without spawning anything.
+ * CPU time. Pure, so it is fixture-testable without spawning anything.
  */
 export function findOrphanedHarnessWorkers(psOutput, minCpuSeconds = DEFAULT_MIN_CPU_SECONDS) {
     const workers = [];
@@ -57,7 +48,7 @@ export function findOrphanedHarnessWorkers(psOutput, minCpuSeconds = DEFAULT_MIN
             continue;
         if (!HARNESS_WORKER_COMMAND_PATTERN.test(command))
             continue;
-        const cpuSeconds = parseCpuTime(cpuTime);
+        const cpuSeconds = parsePsDuration(cpuTime);
         if (Number.isNaN(cpuSeconds) || cpuSeconds < minCpuSeconds)
             continue;
         workers.push({ pid, ppid, cpuTime, cpuSeconds, command });
@@ -68,7 +59,7 @@ export function findOrphanedHarnessWorkers(psOutput, minCpuSeconds = DEFAULT_MIN
 async function listSystemProcesses() {
     const result = await exec('ps', ['-axo', 'pid=,ppid=,time=,command='], { timeout: 10000 });
     if (result.exitCode !== 0) {
-        throw new Error(`ps exited ${String(result.exitCode)}`);
+        throw new Error(`ps exited ${result.exitCode}`);
     }
     return result.stdout;
 }
@@ -86,17 +77,17 @@ async function runOrphanedHarnessCheck() {
         return ok(CHECK_NAME);
     }
     const rows = orphans
-        .map((w) => `PID ${String(w.pid)} (CPU time ${w.cpuTime}): ${w.command.slice(0, 160)}`)
+        .map((w) => `PID ${w.pid} (CPU time ${w.cpuTime}): ${w.command.slice(0, 160)}`)
         .join('; ');
     const pids = orphans.map((w) => String(w.pid)).join(' ');
-    return warning(CHECK_NAME, `Found ${String(orphans.length)} orphaned Python multiprocessing worker(s) — PPID 1 with ` +
+    return warning(CHECK_NAME, `Found ${orphans.length} orphaned Python multiprocessing worker(s) — PPID 1 with ` +
         `high accumulated CPU time, the shape a test harness that died at startup leaves behind ` +
         `(field incident: one such worker busy-spun for ~26 days). ${rows}`, `These look like workers orphaned by a crashed test harness. Verify each command line, ` +
         `then terminate with: kill ${pids} (or kill -9 if a process survives). ` +
         'FireForge never kills pre-existing processes automatically.');
 }
 /**
- * Doctor check reporting orphaned harness workers. Windows has no `ps`;
+ * Doctor check reporting orphaned harness workers. Windows has no `ps`, so
  * the check is skipped there (best-effort platform gap, matching the
  * process-group reaper's POSIX-only sweep).
  */

package/dist/src/commands/doctor-patch-manifest.d.ts

@@ -1,7 +1,8 @@
 /**
  * The patch-manifest consistency check and its two repair paths, split out of
  * `doctor.ts` for the line budget. Exports a single `DoctorCheckDefinition`
- * consumed by the doctor registry; no registrar is exported and none is wanted.
+ * consumed by the doctor registry. No registrar is exported and none is
+ * wanted.
  */
 import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /** Patch manifest consistency check, with its opt-in repair paths. */

package/dist/src/commands/doctor-patch-manifest.js

@@ -2,7 +2,8 @@
 /**
  * The patch-manifest consistency check and its two repair paths, split out of
  * `doctor.ts` for the line budget. Exports a single `DoctorCheckDefinition`
- * consumed by the doctor registry; no registrar is exported and none is wanted.
+ * consumed by the doctor registry. No registrar is exported and none is
+ * wanted.
  */
 import { rebuildPatchesManifest, recommendManifestRepair, repairPatchesFilesAffected, validatePatchesManifestConsistency, } from '../core/patch-manifest.js';
 import { FireForgeError } from '../errors/base.js';
@@ -65,8 +66,8 @@ function describeCount(count) {
 async function runManifestRebuild(ctx) {
     // Repair stamps sourceEsrVersion into every recovered entry. If the
     // earlier "fireforge.json is valid" check failed, ctx.config is
-    // undefined and we must refuse rather than fabricate a fallback —
-    // persisting 'unknown' into manifest metadata is hard to reverse
+    // undefined and we must refuse rather than fabricate a fallback.
+    // Persisting 'unknown' into manifest metadata is hard to reverse
     // and would mislead every later command that reads it.
     if (!ctx.config) {
         return failure(CHECK_NAME, 'Cannot repair patches.json: fireforge.json could not be loaded, so the Firefox version to stamp into recovered manifest entries is unknown.', 'Fix the fireforge.json errors reported above and re-run "fireforge doctor --repair-patches-manifest". ' +
@@ -84,7 +85,7 @@ async function runManifestRebuild(ctx) {
     // trustworthy as an audit trail. The rebuilder returns the list of
     // filenames whose metadata was entirely invented, named explicitly
     // here so the operator knows which patches to review. Entries that
-    // WERE preserved (only `filesAffected` / ordering drifted) are not
+    // were preserved (only `filesAffected` / ordering drifted) are not
     // flagged.
     for (const filename of repaired.recoveredFilenames) {
         // Telling the operator to hand-edit patches.json contradicts the
@@ -101,8 +102,8 @@ async function runManifestRebuild(ctx) {
             'Avoid hand-editing patches.json — FireForge owns that file and will regenerate it on the next manifest consistency pass.');
     }
     // A row whose patch file is gone is dropped by the rebuild. That is
-    // correct — the patch file is the source of truth — but a manifest that
-    // quietly loses rows is exactly what makes a repair hard to audit
+    // correct, since the patch file is the source of truth, but a manifest
+    // that quietly loses rows is what makes a repair hard to audit
     // afterwards, so each one is named.
     for (const filename of repaired.droppedFilenames) {
         warn(`Dropped the manifest entry for ${filename}: no such patch file on disk. ` +

package/dist/src/commands/doctor-post-rebase-audit.js

@@ -16,7 +16,7 @@ async function readEngineText(engineDir, relativePath) {
  * Reports unreadable directories separately from "none found": the consumer
  * turns an empty result into the issue "no browser.toml files found", which is
  * the opposite diagnosis from "the tree could not be read". A swallowed
- * mid-walk EACCES also silently *shrank* the result set, so one unreadable
+ * mid-walk EACCES also silently shrank the result set, so one unreadable
  * subdirectory produced a false clean for that subtree.
  */
 async function collectBrowserTomlFiles(root) {
@@ -54,7 +54,7 @@ async function runPostRebaseAudit(ctx) {
     // The four probes below are upstream-Firefox shape markers: each names a
     // file and a token that a healthy post-rebase tree must still contain. A
     // rebase that dropped a fork patch, or an upstream reorganisation, shows up
-    // as one of these going missing. The tokens are deliberately coarse — this
+    // as one of these going missing. The tokens are coarse on purpose: this
     // is a smoke check that runs warn-only behind an opt-in flag, not a
     // structural validator.
     const mozConfigure = await readEngineText(engineDir, 'browser/moz.configure');
@@ -88,7 +88,7 @@ async function runPostRebaseAudit(ctx) {
     }
     const browserTomls = await collectBrowserTomlFiles(engineDir);
     if (browserTomls.unreadable.length > 0) {
-        issues.push(`could not read ${String(browserTomls.unreadable.length)} ` +
+        issues.push(`could not read ${browserTomls.unreadable.length} ` +
             `${browserTomls.unreadable.length === 1 ? 'directory' : 'directories'} under ` +
             `browser/base/content/test: ${browserTomls.unreadable.join(', ')}`);
     }

package/dist/src/commands/doctor-source-pin.d.ts

@@ -1,29 +1,29 @@
 /**
- * Doctor check comparing the CONFIGURED Firefox source pin against what the
+ * Doctor check comparing the configured Firefox source pin against what the
  * engine checkout actually is.
  *
  * `fireforge source set` lands `firefox.version` inside `fireforge.json`,
  * beside hand-maintained policy sections. That is convenient and it is also
- * the whole problem: a routine `git checkout -- fireforge.json` — undoing an
- * accidental reformat, say — silently reverts an uncommitted pin along with
+ * the whole problem: a routine `git checkout -- fireforge.json` (undoing an
+ * accidental reformat, say) silently reverts an uncommitted pin along with
  * it, and nothing afterwards reports that the pin and the checkout have
- * diverged. The tell in the field was a gate flipping green with no change
- * that should have made it green.
+ * diverged. In the field this showed up as a gate flipping green with no
+ * change that should have made it green.
  *
- * This is deliberately not a lock and not a refusal: a tree may legitimately
- * be mid-migration between two versions. It only makes a mismatched tree
- * VISIBLE, which is all that was missing.
+ * This is not a lock and not a refusal: a tree may legitimately be
+ * mid-migration between two versions. It only makes a mismatched tree
+ * visible, which is all that was missing.
  *
  * Scope is limited by what is actually recorded. `firefox.product`,
- * `firefox.sha256` and `firefox.candidate` have NO counterpart anywhere on
- * disk — `.fireforge/state.json` records only `downloadedVersion` and
- * `baseCommit` — so there is nothing to compare them against and the check
+ * `firefox.sha256` and `firefox.candidate` have no counterpart anywhere on
+ * disk (`.fireforge/state.json` records only `downloadedVersion` and
+ * `baseCommit`), so there is nothing to compare them against and the check
  * says nothing about them rather than implying it verified them.
  */
 import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /**
  * Pin-vs-checkout reporting. Needs the loaded config, so it declares the
- * dependency on the config check that populates `ctx.config`; skipped
+ * dependency on the config check that populates `ctx.config`. It is skipped
  * entirely without an engine, where there is nothing to compare.
  */
 export declare const SOURCE_PIN_DOCTOR_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-source-pin.js

@@ -1,24 +1,24 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Doctor check comparing the CONFIGURED Firefox source pin against what the
+ * Doctor check comparing the configured Firefox source pin against what the
  * engine checkout actually is.
  *
  * `fireforge source set` lands `firefox.version` inside `fireforge.json`,
  * beside hand-maintained policy sections. That is convenient and it is also
- * the whole problem: a routine `git checkout -- fireforge.json` — undoing an
- * accidental reformat, say — silently reverts an uncommitted pin along with
+ * the whole problem: a routine `git checkout -- fireforge.json` (undoing an
+ * accidental reformat, say) silently reverts an uncommitted pin along with
  * it, and nothing afterwards reports that the pin and the checkout have
- * diverged. The tell in the field was a gate flipping green with no change
- * that should have made it green.
+ * diverged. In the field this showed up as a gate flipping green with no
+ * change that should have made it green.
  *
- * This is deliberately not a lock and not a refusal: a tree may legitimately
- * be mid-migration between two versions. It only makes a mismatched tree
- * VISIBLE, which is all that was missing.
+ * This is not a lock and not a refusal: a tree may legitimately be
+ * mid-migration between two versions. It only makes a mismatched tree
+ * visible, which is all that was missing.
  *
  * Scope is limited by what is actually recorded. `firefox.product`,
- * `firefox.sha256` and `firefox.candidate` have NO counterpart anywhere on
- * disk — `.fireforge/state.json` records only `downloadedVersion` and
- * `baseCommit` — so there is nothing to compare them against and the check
+ * `firefox.sha256` and `firefox.candidate` have no counterpart anywhere on
+ * disk (`.fireforge/state.json` records only `downloadedVersion` and
+ * `baseCommit`), so there is nothing to compare them against and the check
  * says nothing about them rather than implying it verified them.
  */
 import { getFirefoxVersion } from '../core/firefox.js';
@@ -40,8 +40,8 @@ async function runSourcePinCheck(ctx) {
     let actual;
     try {
         // A blank or whitespace-only version.txt (a truncated write, a partial
-        // extraction) carries no version to compare — treat it as absent rather
-        // than reporting the engine as being at version "".
+        // extraction) carries no version to compare, so treat it as absent
+        // rather than reporting the engine as being at version "".
         actual = (await getFirefoxVersion(ctx.paths.engine))?.trim() || undefined;
     }
     catch (error) {
@@ -70,7 +70,7 @@ async function runSourcePinCheck(ctx) {
 }
 /**
  * Pin-vs-checkout reporting. Needs the loaded config, so it declares the
- * dependency on the config check that populates `ctx.config`; skipped
+ * dependency on the config check that populates `ctx.config`. It is skipped
  * entirely without an engine, where there is nothing to compare.
  */
 export const SOURCE_PIN_DOCTOR_CHECK = {

package/dist/src/commands/doctor-working-tree.d.ts

@@ -3,18 +3,18 @@
  *
  * Partitions engine-tree dirtiness into `branding`, `patch-backed`,
  * `furnace`, `conflict`, and `unmanaged` buckets, and only warns on the
- * last two — everything else is tool-managed state that the operator
+ * last two. Everything else is tool-managed state that the operator
  * did not author directly.
  *
  * Split out of `doctor.ts` so that file stays under the per-file LOC
- * budget; see the call site in `runEngineGitChecks`.
+ * budget. See the call site in `runEngineGitChecks`.
  */
 import type { DoctorCheck } from '../types/commands/index.js';
 import type { DoctorCheckContext } from './doctor-check-core.js';
 /**
  * Inspects the engine working tree and returns a single `DoctorCheck`.
  * Ownership-aware: patch-backed / branding / furnace rows are reported as OK
- * with an ownership summary; unmanaged drift warns; cross-patch conflicts
+ * with an ownership summary. Unmanaged drift warns. Cross-patch conflicts
  * warn loudly with a pointer at `fireforge status --ownership` +
  * `fireforge verify`.
  *

package/dist/src/commands/doctor-working-tree.js

@@ -4,11 +4,11 @@
  *
  * Partitions engine-tree dirtiness into `branding`, `patch-backed`,
  * `furnace`, `conflict`, and `unmanaged` buckets, and only warns on the
- * last two — everything else is tool-managed state that the operator
+ * last two. Everything else is tool-managed state that the operator
  * did not author directly.
  *
  * Split out of `doctor.ts` so that file stays under the per-file LOC
- * budget; see the call site in `runEngineGitChecks`.
+ * budget. See the call site in `runEngineGitChecks`.
  */
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
@@ -30,7 +30,7 @@ function formatManagedDetail(counts) {
 /**
  * Inspects the engine working tree and returns a single `DoctorCheck`.
  * Ownership-aware: patch-backed / branding / furnace rows are reported as OK
- * with an ownership summary; unmanaged drift warns; cross-patch conflicts
+ * with an ownership summary. Unmanaged drift warns. Cross-patch conflicts
  * warn loudly with a pointer at `fireforge status --ownership` +
  * `fireforge verify`.
  *

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

@@ -10,7 +10,7 @@ import type { DoctorCheckDefinition } from './doctor-check-core.js';
  * context-population bug at runtime.
  *
  * Exported so tests can exercise the forward-only invariant against
- * fixtures — the real DOCTOR_CHECKS list is also validated at import
+ * fixtures. The real DOCTOR_CHECKS list is also validated at import
  * time, but a targeted unit test makes the contract explicit and
  * prevents regressions if the validator is ever relaxed.
  */
@@ -21,6 +21,8 @@ export declare function validateCheckDependencies(checks: readonly DoctorCheckDe
  * context-population dependency chain (see {@link DOCTOR_CHECKS}) must
  * also update this list, which gives us a single place to notice and
  * think through the consequences.
+ *
+ * @internal Exported only so tests can reach it. Not part of the public surface.
  */
 export declare const DOCTOR_CHECK_ORDER: readonly string[];
 /**

package/dist/src/commands/doctor.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { Command } from 'commander';
-import { configExists, getProjectPaths, loadConfig, loadState, updateState, } from '../core/config.js';
+import { configExists, getProjectPaths, loadConfig, loadState } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists } from '../core/furnace-config.js';
 import { getCurrentBranch, getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { ensureGit } from '../core/git-base.js';
@@ -14,7 +14,7 @@ import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
 import { addWaitLockOption } from '../utils/options.js';
 import { findExecutable } from '../utils/process.js';
-import { failure, ok, resolveDoctorSeverity, warning } from './doctor-check-core.js';
+import { failure, ok, warning } from './doctor-check-core.js';
 import { EXTERNAL_TOOLCHAIN_DOCTOR_CHECK } from './doctor-external-toolchains.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { ORPHANED_HARNESS_DOCTOR_CHECK } from './doctor-orphaned-harness.js';
@@ -22,6 +22,7 @@ import { PATCH_MANIFEST_CONSISTENCY_CHECK } from './doctor-patch-manifest.js';
 import { POST_REBASE_AUDIT_CHECK } from './doctor-post-rebase-audit.js';
 import { SOURCE_PIN_DOCTOR_CHECK } from './doctor-source-pin.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
+import { clearPendingResolution } from './pending-resolution.js';
 import { collectPatchQueueHealth } from './verify.js';
 /**
  * Runs a single check definition, converting thrown errors into
@@ -89,8 +90,8 @@ async function runEngineGitChecks(ctx) {
         branch === undefined &&
         currentHead === undefined &&
         !state.baseCommit) {
-        // Unborn repository with no recorded baseline — the earlier failure row
-        // explains recovery; avoid adding a second near-identical row.
+        // Unborn repository with no recorded baseline. The earlier failure row
+        // explains recovery. Avoid adding a second near-identical row.
     }
     else if (!canValidateBranch) {
         rows.push(warning('Engine branch', 'Skipped branch validation because the baseline commit is missing.', 'Finish recreating the engine baseline with "fireforge download --force".'));
@@ -113,7 +114,7 @@ async function runEngineGitChecks(ctx) {
  * context-population bug at runtime.
  *
  * Exported so tests can exercise the forward-only invariant against
- * fixtures — the real DOCTOR_CHECKS list is also validated at import
+ * fixtures. The real DOCTOR_CHECKS list is also validated at import
  * time, but a targeted unit test makes the contract explicit and
  * prevents regressions if the validator is ever relaxed.
  */
@@ -135,7 +136,7 @@ export function validateCheckDependencies(checks) {
 /**
  * The declarative doctor check registry. The order of entries here is the
  * order checks appear in the report. Adding a new check is a one-entry
- * edit; each check only contains its own inspection logic.
+ * edit. Each check only contains its own inspection logic.
  *
  * ## Ordering dependency chain
  *
@@ -202,11 +203,7 @@ const DOCTOR_CHECKS = [
                 if (health.errorCount > 0) {
                     return failure('Pending Resolution', `Refusing to clear pending resolution for ${patchFilename}: patch queue health check found ${health.errorCount} error(s).`, 'Run "fireforge verify" for details, fix the queue, then retry "fireforge doctor --clear-resolution".');
                 }
-                await updateState(ctx.projectRoot, (current) => {
-                    const next = { ...current };
-                    delete next.pendingResolution;
-                    return next;
-                });
+                await clearPendingResolution(ctx.projectRoot);
                 return ok('Pending Resolution');
             }
             return failure('Pending Resolution', `You are currently resolving a conflict for patch ${patchFilename}.`, 'Build and Export commands may behave unexpectedly until "fireforge resolve" is completed. If the queue now verifies cleanly, run "fireforge doctor --clear-resolution" to discard the stale marker.');
@@ -217,7 +214,7 @@ const DOCTOR_CHECKS = [
         name: 'Engine is git repository',
         skipIf: (ctx) => !ctx.engineExists,
         // runEngineGitChecks consults ctx.config for ownership-aware
-        // working-tree classification; declare the dependency so a future
+        // working-tree classification. Declare the dependency so a future
         // reorder doesn't silently regress the doctor back to the
         // count-only fallback.
         dependsOn: ['fireforge.json is valid'],
@@ -251,7 +248,7 @@ const DOCTOR_CHECKS = [
             // Resolve the absolute path so the OK row names what doctor actually
             // found. A PATH-export discrepancy between the operator's interactive
             // shell and the spawned subprocess otherwise reads as doctor printing
-            // "OK" for a binary `which watchman` cannot find; surfacing the
+            // "OK" for a binary `which watchman` cannot find. Surfacing the
             // resolved path makes the discrepancy visible without a verbose flag.
             const path = await findExecutable('watchman');
             if (path) {
@@ -298,7 +295,7 @@ const DOCTOR_CHECKS = [
     POST_REBASE_AUDIT_CHECK,
     // Furnace checks live in a sibling module so this file stays under the
     // max-lines threshold. Splicing them in as an array preserves the
-    // declarative registry contract — each entry remains a single
+    // declarative registry contract: each entry remains a single
     // `DoctorCheckDefinition` with its own skipIf/run/fix, and the order
     // here is the order they appear in the report.
     ...FURNACE_DOCTOR_CHECKS,
@@ -322,6 +319,8 @@ validateCheckDependencies(DOCTOR_CHECKS);
  * context-population dependency chain (see {@link DOCTOR_CHECKS}) must
  * also update this list, which gives us a single place to notice and
  * think through the consequences.
+ *
+ * @internal Exported only so tests can reach it. Not part of the public surface.
  */
 export const DOCTOR_CHECK_ORDER = DOCTOR_CHECKS.map((check) => check.name);
 /**
@@ -336,7 +335,7 @@ export function reportDoctorResults(checks, mutations = []) {
     let warningCount = 0;
     let failedCount = 0;
     for (const check of checks) {
-        const severity = resolveDoctorSeverity(check);
+        const severity = check.severity;
         if (severity === 'warning') {
             warn(`! ${check.name}: ${check.message}`);
             if (check.fix) {
@@ -383,7 +382,7 @@ export function reportDoctorResults(checks, mutations = []) {
  * Rejects repair-flag combinations that cannot mean what they say.
  *
  * The two manifest repairs are different operations on the same file, and
- * `--dry-run` with nothing to project is a flag that silently does nothing —
+ * `--dry-run` with nothing to project is a flag that silently does nothing,
  * the shape most likely to be mistaken for a preview that reported "no
  * changes".
  */

package/dist/src/commands/download.js

@@ -78,7 +78,7 @@ async function cleanPatchTouchedFiles(engineDir, patchesDir, preExistingDirty) {
  * Prints a one-line nudge pointing at `fireforge import` when the project
  * carries a non-empty patch queue but the just-downloaded engine has not yet
  * had any patches applied. The post-download spinner closes with
- * "Patch-touched files already match baseline" because a fresh tree IS at
+ * "Patch-touched files already match baseline" because a fresh tree is at
  * baseline, which reads as "patches are restored" and invites skipping the
  * import step. Suppressed when patches/ is missing or the manifest is empty
  * so unconfigured projects stay quiet.
@@ -94,10 +94,11 @@ async function noteUnappliedPatches(patchesDir) {
 }
 /**
  * Stops `restoreSpinner` with a message that reflects what actually
- * happened. Three branches: empty queue → explicit no-op; queue present but
- * nothing dirty → "already clean"; queue with dirty files → the usual
- * "Patch-touched files restored" success line. Always closing with the third
- * claims restore work that did not happen on a project with zero patches.
+ * happened. Three branches. An empty queue gives an explicit no-op. A queue
+ * that is present but has nothing dirty gives "already clean". A queue with
+ * dirty files gives the usual "Patch-touched files restored" success line.
+ * Always closing with the third claims restore work that did not happen on a
+ * project with zero patches.
  */
 function closeRestoreSpinner(restoreSpinner, result) {
     if (!result.hadQueue) {
@@ -110,11 +111,6 @@ function closeRestoreSpinner(restoreSpinner, result) {
     }
     restoreSpinner.stop('Patch-touched files restored');
 }
-async function clearStaleFurnaceApplyState(projectRoot) {
-    // --force installs a new baseCommit, which invalidates every applied
-    // checksum in furnace-state.json.
-    await clearAppliedFurnaceState(projectRoot);
-}
 async function activateReplacementEngine(args) {
     const { engineDir, replacementDir, backupDir } = args;
     await rename(engineDir, backupDir);
@@ -155,28 +151,39 @@ async function restorePreviousEngine(args) {
     }
 }
 async function downloadAndExtractFirefox(args) {
-    const { version, product, engineDir, cacheDir, sha256, candidate } = args;
+    const { version, product, engineDir, cacheDir, sha256, candidate, allowUnverifiedDownload } = args;
     let s = spinner(`Downloading Firefox ${version}...`);
     let lastPercent = 0;
     const phaseState = { value: 'download' };
     try {
-        await downloadFirefoxSource(version, product, engineDir, cacheDir, (downloaded, total) => {
-            if (total <= 0)
-                return;
-            const percent = Math.floor((downloaded / total) * 100);
-            if (percent !== lastPercent && percent % 5 === 0) {
-                s.message(`Downloading Firefox ${version}... ${percent}% (${formatBytes(downloaded)} / ${formatBytes(total)})`);
-                lastPercent = percent;
-            }
-        }, (phase) => {
-            if (phase === 'extract' && phaseState.value === 'download') {
-                s.stop(`Firefox ${version} downloaded`);
-                phaseState.value = 'extract';
-                s = spinner(`Extracting Firefox ${version}... (decompressing ~600 MB of source; typically 30–90s)`);
-            }
-        }, sha256, (message) => {
-            s.message(message);
-        }, candidate);
+        await downloadFirefoxSource({
+            version: version,
+            product: product,
+            destDir: engineDir,
+            cacheDir: cacheDir,
+            onProgress: (downloaded, total) => {
+                if (total <= 0)
+                    return;
+                const percent = Math.floor((downloaded / total) * 100);
+                if (percent !== lastPercent && percent % 5 === 0) {
+                    s.message(`Downloading Firefox ${version}... ${percent}% (${formatBytes(downloaded)} / ${formatBytes(total)})`);
+                    lastPercent = percent;
+                }
+            },
+            onPhase: (phase) => {
+                if (phase === 'extract' && phaseState.value === 'download') {
+                    s.stop(`Firefox ${version} downloaded`);
+                    phaseState.value = 'extract';
+                    s = spinner(`Extracting Firefox ${version}... (decompressing ~600 MB of source; typically 30–90s)`);
+                }
+            },
+            expectedSha256: sha256,
+            onPhaseProgress: (message) => {
+                s.message(message);
+            },
+            candidate: candidate,
+            integrity: allowUnverifiedDownload === undefined ? undefined : { allowUnverifiedDownload },
+        });
         s.stop(phaseState.value === 'extract'
             ? `Firefox ${version} extracted`
             : `Firefox ${version} downloaded`);
@@ -188,7 +195,7 @@ async function downloadAndExtractFirefox(args) {
 }
 /**
  * Prints the major-version-hop toolchain nudge when this download moved the
- * engine across a Firefox MAJOR version — the first post-hop build otherwise
+ * engine across a Firefox major version. The first post-hop build otherwise
  * dies in `mach configure` on a moved cbindgen minimum with nothing in the
  * download output suggesting `fireforge bootstrap`. Quiet on first downloads
  * and same-major re-downloads.
@@ -235,7 +242,9 @@ async function initializeDownloadedEngine(args) {
             throw error;
         }
         if (replacementActivated) {
-            await clearStaleFurnaceApplyState(projectRoot);
+            // --force installs a new baseCommit, which invalidates every applied
+            // checksum in furnace-state.json.
+            await clearAppliedFurnaceState(projectRoot);
         }
         await updateState(projectRoot, {
             downloadedVersion: version,
@@ -268,7 +277,7 @@ export async function downloadCommand(projectRoot, options) {
     intro('FireForge Download');
     const config = await loadConfig(projectRoot), version = config.firefox.version;
     const paths = getProjectPaths(projectRoot);
-    // Captured BEFORE any state update so the post-download major-hop
+    // Captured before any state update so the post-download major-hop
     // notice compares against what was actually on disk until now.
     const previousVersion = (await loadState(projectRoot)).downloadedVersion;
     info(`Firefox version: ${version}`);
@@ -276,7 +285,7 @@ export async function downloadCommand(projectRoot, options) {
     // A legitimate holder of this lock runs for 10+ minutes (download +
     // extract + git indexing). A 30 s timeout fails the second invocation with
     // "remove the lock directory if it is stale" advice while the lock is
-    // actively held — dangerous guidance mid-extraction. Wait generously
+    // actively held, which is dangerous guidance mid-extraction. Wait generously
     // instead: a dead holder is reaped within seconds by the PID-based stale
     // probe, so a long timeout only ever waits on real work.
     const downloadLockOptions = {
@@ -289,7 +298,7 @@ export async function downloadCommand(projectRoot, options) {
         // Reclaim multi-GB partial trees left behind by interrupted runs.
         // Safe under the download lock: any `.tmp-*`/`.replacement-*` dir
         // present now is orphaned, since live ones only exist while a
-        // download holds this lock. `.backup-*` dirs are NOT swept — a
+        // download holds this lock. `.backup-*` dirs are not swept: a
         // backup can hold the previous engine after a failed forced
         // replacement and is the operator's recovery copy.
         const sweptDirs = await sweepOrphanedEngineWorkDirs(paths.engine);
@@ -309,7 +318,8 @@ export async function downloadCommand(projectRoot, options) {
                     }
                     catch (error) {
                         if (isMissingHeadError(error)) {
-                            // Partial init detected — attempt to resume instead of requiring --force
+                            // Partial init detected. Attempt to resume instead of
+                            // requiring --force.
                             info('Detected partially initialized engine. Attempting to resume...');
                             // Snapshot patch-touched files that are already dirty so we
                             // can preserve them after the resume commit.
@@ -332,7 +342,7 @@ export async function downloadCommand(projectRoot, options) {
                                 });
                                 const baseCommit = await getHead(paths.engine);
                                 resumeSpinner.stop('Git repository resumed successfully');
-                                // Restore patch-touched files BEFORE stamping state. If this
+                                // Restore patch-touched files before stamping state. If this
                                 // step fails (disk full, permission denied, git object issue),
                                 // state.json keeps the previous downloadedVersion so the
                                 // invariant "state.downloadedVersion matches a clean engine"
@@ -351,7 +361,7 @@ export async function downloadCommand(projectRoot, options) {
                             }
                             catch (error) {
                                 resumeSpinner.error('Resume failed');
-                                // Preserve the underlying cause so the operator sees *why*
+                                // Preserve the underlying cause so the operator sees why
                                 // the resume failed (timeout, permission denied, corrupted
                                 // object, disk full) instead of only the generic "partial
                                 // engine exists" story. The cause reaches them through the
@@ -364,7 +374,7 @@ export async function downloadCommand(projectRoot, options) {
                         // Re-throw unexpected git errors (corrupted objects, permission
                         // denied, …) wrapped in PartialEngineExistsError so the user sees
                         // both narratives: "we detected a partial engine and attempted
-                        // resume" AND the underlying git failure. Without the wrap the
+                        // resume" and the underlying git failure. Without the wrap the
                         // raw git error loses the context that resume was in flight.
                         throw new PartialEngineExistsError(paths.engine, toError(error));
                     }
@@ -389,6 +399,9 @@ export async function downloadCommand(projectRoot, options) {
                 ...(config.firefox.candidate !== undefined
                     ? { candidate: config.firefox.candidate }
                     : {}),
+                ...(config.firefox.allowUnverifiedDownload !== undefined
+                    ? { allowUnverifiedDownload: config.firefox.allowUnverifiedDownload }
+                    : {}),
             });
             if (replacementEngineDir && backupEngineDir) {
                 warn('Activating replacement engine directory...');