@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/commands/doctor-furnace.js

@@ -4,15 +4,15 @@ import { join } from 'node:path';
 import { applyAllComponents } from '../core/furnace-apply.js';
 import { hasCustomEngineDrift, hasOverrideEngineDrift } from '../core/furnace-apply-helpers.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, } from '../core/furnace-config.js';
-import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from '../core/furnace-constants.js';
+import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir, WIDGETS_DIR, } from '../core/furnace-constants.js';
 import { getFurnaceLockPath, runFurnaceMutation } from '../core/furnace-operation.js';
 import { hasBlockingStepErrors } from '../core/furnace-step-errors.js';
 import { validateAllComponents } from '../core/furnace-validate.js';
 import { isProcessAlive, toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { failure, ok, warning } from './doctor-check-core.js';
+import { furnaceConfigSyncCheck } from './doctor-furnace-config-sync.js';
 import { furnaceStaleJarRegistrationCheck } from './doctor-furnace-jar.js';
-import { furnaceManifestSyncCheck } from './doctor-furnace-manifest-sync.js';
 const ENGINE_REPAIRABLE_OPERATIONS = [
     'preview-teardown',
     'apply-rollback',
@@ -98,7 +98,7 @@ async function collectFurnaceDrift(projectRoot, engineDir, config, ftlDir) {
             continue;
         }
         try {
-            if (await hasOverrideEngineDrift(engineDir, componentDir, overrideConfig, ftlDir)) {
+            if (await hasOverrideEngineDrift({ engineDir, componentDir, ftlDir }, overrideConfig)) {
                 drifted.push(name);
             }
         }
@@ -115,7 +115,7 @@ async function collectFurnaceDrift(projectRoot, engineDir, config, ftlDir) {
             continue;
         }
         try {
-            if (await hasCustomEngineDrift(projectRoot, name, componentDir, customConfig, ftlDir)) {
+            if (await hasCustomEngineDrift({ root: projectRoot, name, componentDir, ftlDir }, customConfig)) {
                 drifted.push(name);
             }
         }
@@ -336,7 +336,7 @@ const furnaceEnginePathsCheck = {
         const expectedPaths = [
             CUSTOM_ELEMENTS_JS,
             JAR_MN,
-            'toolkit/content/widgets',
+            WIDGETS_DIR,
             resolveFtlDir(ctx.furnaceConfig?.ftlBasePath),
             ...hostDocs,
         ];
@@ -437,18 +437,17 @@ async function readFurnaceLockPid(lockPath) {
     }
 }
 /**
- * "Furnace stale lock" check: detect and (under `--repair-furnace`)
- * remove a `.fireforge/furnace.lock` directory whose owner process is no
- * longer alive.
+ * "Furnace stale lock" check: detect and (under `--repair-furnace`) remove a
+ * `.fireforge/furnace.lock` directory whose owner process is no longer
+ * alive.
  *
  * This is the recovery path when the signal-handler sweep
  * (`forceReleaseFurnaceLocksForActiveOperations` in `bin/fireforge.ts`)
- * misses — e.g. a SIGKILL'd process that never got to run the handler, or
- * a lock created by an older FireForge release without a PID file. The
- * motivating eval scenario: SIGINT'ing `furnace preview` left the lock
- * behind, and the next `fireforge test --build` timed out waiting for it.
- * `doctor --repair-furnace` now clears the lock explicitly so the next
- * command runs immediately.
+ * misses — a SIGKILL'd process that never ran the handler, or a lock created
+ * by an older FireForge release without a PID file. SIGINT'ing `furnace
+ * preview` leaves the lock behind, and the next `fireforge test --build`
+ * then times out waiting for it; `doctor --repair-furnace` clears it so the
+ * next command runs immediately.
  */
 const furnaceStaleLockCheck = {
     name: 'Furnace lock',
@@ -466,16 +465,14 @@ const furnaceStaleLockCheck = {
         // Two signals mark a lock as stale:
         //   1. PID file says owner is dead → unambiguous, remove immediately.
         //   2. PID file absent AND lock is older than 60s → older FireForge
-        //      releases (or an externally-created lock directory) fall into
-        //      this bucket; the age gate avoids false positives on a lock
-        //      that was just acquired by a concurrent process that hadn't
-        //      written its PID yet.
+        //      releases (or an externally-created lock directory) fall into this
+        //      bucket; the age gate avoids false positives on a lock just
+        //      acquired by a concurrent process that has not written its PID yet.
         //
-        // `isProcessAlive` treats EPERM as ALIVE. The local copy it replaced
-        // returned false for EPERM, so a furnace lock held by a live process
-        // owned by another uid was reported as "owner is no longer running"
-        // and deleted by --repair-furnace, dropping mutual exclusion under a
-        // concurrent furnace operation.
+        // `isProcessAlive` treats EPERM as ALIVE. Returning false for EPERM
+        // reports a furnace lock held by a live process owned by another uid as
+        // "owner is no longer running", and --repair-furnace then deletes it,
+        // dropping mutual exclusion under a concurrent furnace operation.
         const ownerDead = pid !== null && !isProcessAlive(pid);
         const pidMissingAndOld = pid === null && (ageMs ?? 0) > 60_000;
         const isStale = ownerDead || pidMissingAndOld;
@@ -513,5 +510,5 @@ export const FURNACE_DOCTOR_CHECKS = [
     furnaceStaleLockCheck,
     furnaceEngineStateCheck,
     furnaceComponentValidationCheck,
-    furnaceManifestSyncCheck,
+    furnaceConfigSyncCheck,
 ];

package/dist/src/commands/doctor-orphaned-harness.d.ts

@@ -1,23 +1,20 @@
 /**
- * Doctor check for PRE-EXISTING orphaned test-harness workers (0.37.0
- * item 9b).
+ * Doctor check for PRE-EXISTING orphaned test-harness workers.
  *
- * Field incident: a mach invocation that died at harness startup stranded a
- * Python 3.14 `multiprocessing` spawn worker plus its resource tracker; the
- * worker reparented to launchd (PPID 1) and busy-spun at 100% CPU for ~26
- * days (~415 CPU-hours) undetected. 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), using the
- * detection recipe that found the incident process: PPID 1 + large
- * accumulated CPU TIME + a `multiprocessing.spawn`/`resource_tracker`
- * command line.
+ * A mach invocation that dies at harness startup can strand a Python
+ * `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
+ * 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 by design: FireForge never kills pre-existing processes it did
+ * not spawn — the check names each candidate and suggests the kill.
  *
- * Canary integration was deliberately skipped: the friction log asked for
- * doctor AND/OR `test --canary`, and adding a system-wide process scan to
- * the canary hot path buys no extra coverage over the doctor check.
+ * 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.
  */
 import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /** One process matching the orphaned-harness-worker shape. */
@@ -31,10 +28,9 @@ export interface OrphanedHarnessWorker {
     command: string;
 }
 /**
- * Parses a `ps` TIME value in either dialect:
- *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
- *   - darwin/BSD `mm:ss.cc` with cumulative minutes (e.g. `38412:07.55`)
- * Returns NaN for unrecognized shapes.
+ * 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 declare function parseCpuTime(time: string): number;
 /**

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

@@ -1,27 +1,25 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Doctor check for PRE-EXISTING orphaned test-harness workers (0.37.0
- * item 9b).
+ * Doctor check for PRE-EXISTING orphaned test-harness workers.
  *
- * Field incident: a mach invocation that died at harness startup stranded a
- * Python 3.14 `multiprocessing` spawn worker plus its resource tracker; the
- * worker reparented to launchd (PPID 1) and busy-spun at 100% CPU for ~26
- * days (~415 CPU-hours) undetected. 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), using the
- * detection recipe that found the incident process: PPID 1 + large
- * accumulated CPU TIME + a `multiprocessing.spawn`/`resource_tracker`
- * command line.
+ * A mach invocation that dies at harness startup can strand a Python
+ * `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
+ * 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 by design: FireForge never kills pre-existing processes it did
+ * not spawn — the check names each candidate and suggests the kill.
  *
- * Canary integration was deliberately skipped: the friction log asked for
- * doctor AND/OR `test --canary`, and adding a system-wide process scan to
- * the canary hot path buys no extra coverage over the doctor check.
+ * 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.
  */
 import { toError } from '../utils/errors.js';
 import { exec } from '../utils/process.js';
+import { parsePsDuration } from '../utils/ps-duration.js';
 import { ok, warning } from './doctor-check-core.js';
 /**
  * Command-line shapes of Python multiprocessing helper processes: the
@@ -32,36 +30,12 @@ const HARNESS_WORKER_COMMAND_PATTERN = /multiprocessing\.(?:spawn|forkserver)\b|
 /** Minimum accumulated CPU time before a match is reported (10 minutes). */
 const DEFAULT_MIN_CPU_SECONDS = 600;
 /**
- * Parses a `ps` TIME value in either dialect:
- *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
- *   - darwin/BSD `mm:ss.cc` with cumulative minutes (e.g. `38412:07.55`)
- * Returns NaN for unrecognized shapes.
+ * 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) {
-    const trimmed = time.trim();
-    let days = 0;
-    let rest = trimmed;
-    const dayMatch = /^(\d+)-(.*)$/.exec(trimmed);
-    if (dayMatch) {
-        days = Number(dayMatch[1]);
-        rest = dayMatch[2] ?? '';
-    }
-    const parts = rest.split(':');
-    if (parts.length === 3) {
-        // hh:mm:ss (linux; seconds may not carry fractions but tolerate them)
-        const [h, m, s] = parts.map(Number);
-        if ([h, m, s].some((n) => Number.isNaN(n)))
-            return NaN;
-        return days * 86400 + (h ?? 0) * 3600 + (m ?? 0) * 60 + (s ?? 0);
-    }
-    if (parts.length === 2) {
-        // mm:ss.cc (darwin — the minutes field accumulates without wrapping)
-        const [m, s] = parts.map(Number);
-        if ([m, s].some((n) => Number.isNaN(n)))
-            return NaN;
-        return days * 86400 + (m ?? 0) * 60 + (s ?? 0);
-    }
-    return NaN;
+    return parsePsDuration(time);
 }
 /**
  * Scans `ps -axo pid=,ppid=,time=,command=` output for orphaned harness

package/dist/src/commands/doctor-post-rebase-audit.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+export declare const POST_REBASE_AUDIT_CHECK: DoctorCheckDefinition;

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

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { toError } from '../../utils/errors.js';
-import { pathExists, readText } from '../../utils/fs.js';
-import { ok, warning } from '../doctor-check-core.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { ok, warning } from './doctor-check-core.js';
 async function readEngineText(engineDir, relativePath) {
     const fullPath = join(engineDir, relativePath);
     if (!(await pathExists(fullPath)))

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

@@ -12,18 +12,16 @@
 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 warn loudly with a pointer at
- * `fireforge status --ownership` + `fireforge verify`.
+ * 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
+ * warn loudly with a pointer at `fireforge status --ownership` +
+ * `fireforge verify`.
  *
- * Before 0.16.1 this check warned on every dirty row regardless of
- * ownership and told the operator to export/discard/reset — advice
- * that was actively destructive on a patch-backed import (eval
- * Finding: a correctly imported 126-file patch stack was reported as
- * unhealthy and the suggested fix would have dropped the entire
- * import). Returns `undefined` when the worktree is clean so the
- * caller can emit its own ok() row.
+ * Ownership is what makes the advice safe: warning on every dirty row and
+ * telling the operator to export/discard/reset is actively destructive on a
+ * patch-backed import, where the suggested fix would drop the entire patch
+ * stack. Returns `undefined` when the worktree is clean so the caller can
+ * emit its own ok() row.
  */
 export declare function inspectEngineWorkingTree(ctx: DoctorCheckContext): Promise<DoctorCheck | undefined>;

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

@@ -28,19 +28,17 @@ function formatManagedDetail(counts) {
         .join(', ');
 }
 /**
- * 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 warn loudly with a pointer at
- * `fireforge status --ownership` + `fireforge verify`.
+ * 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
+ * warn loudly with a pointer at `fireforge status --ownership` +
+ * `fireforge verify`.
  *
- * Before 0.16.1 this check warned on every dirty row regardless of
- * ownership and told the operator to export/discard/reset — advice
- * that was actively destructive on a patch-backed import (eval
- * Finding: a correctly imported 126-file patch stack was reported as
- * unhealthy and the suggested fix would have dropped the entire
- * import). Returns `undefined` when the worktree is clean so the
- * caller can emit its own ok() row.
+ * Ownership is what makes the advice safe: warning on every dirty row and
+ * telling the operator to export/discard/reset is actively destructive on a
+ * patch-backed import, where the suggested fix would drop the entire patch
+ * stack. Returns `undefined` when the worktree is clean so the caller can
+ * emit its own ok() row.
  */
 export async function inspectEngineWorkingTree(ctx) {
     const { paths } = ctx;
@@ -82,12 +80,7 @@ export async function inspectEngineWorkingTree(ctx) {
     const managedTotal = counts.branding + counts.furnace + counts.patchBacked + counts.patchOwnedDrift;
     if (counts.unmanaged === 0) {
         const managedDetail = formatManagedDetail(counts);
-        return {
-            name: 'Engine working tree',
-            passed: true,
-            severity: 'ok',
-            message: `${managedTotal} tool-managed change${managedTotal === 1 ? '' : 's'} (${managedDetail}), 0 unmanaged. Use "fireforge status --ownership" for details.`,
-        };
+        return ok('Engine working tree', `${managedTotal} tool-managed change${managedTotal === 1 ? '' : 's'} (${managedDetail}), 0 unmanaged. Use "fireforge status --ownership" for details.`);
     }
     const managedTail = managedTotal > 0
         ? ` (${managedTotal} other change${managedTotal === 1 ? '' : 's'} are tool-managed: ${formatManagedDetail(counts)}).`

package/dist/src/commands/doctor.js

@@ -11,12 +11,13 @@ import { ExitCode } from '../errors/codes.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
+import { addWaitLockOption, resolveWaitLockSeconds } from '../utils/options.js';
 import { findExecutable } from '../utils/process.js';
-import { POST_REBASE_AUDIT_CHECK } from './doctor/post-rebase-audit.js';
 import { failure, ok, resolveDoctorSeverity, 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';
+import { POST_REBASE_AUDIT_CHECK } from './doctor-post-rebase-audit.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 import { collectPatchQueueHealth } from './verify.js';
 /**
@@ -236,31 +237,21 @@ const DOCTOR_CHECKS = [
         fix: 'Firefox source may be corrupted. Re-download with "fireforge download --force"',
     },
     {
-        // `fireforge watch` has an undeclared hard dependency on watchman —
-        // neither `bootstrap` nor `doctor` used to surface it, so operators
-        // got through setup → download → build → and only discovered the gap
-        // when they tried to start watch mode. A warning-severity doctor row
-        // is the right shape: most projects never run watch, so a missing
-        // watchman should not fail `doctor` outright, but the information
-        // needs to be visible ahead of time rather than at the watch-mode
-        // failure site.
+        // `fireforge watch` has an undeclared hard dependency on watchman, and
+        // without a doctor row operators only discover the gap when they try to
+        // start watch mode. Warning severity is the right shape: most projects
+        // never run watch, so a missing watchman should not fail `doctor`
+        // outright, but the information needs to be visible ahead of time.
         name: 'Watchman available',
         run: async () => {
             // Resolve the absolute path so the OK row names what doctor actually
-            // found. The 2026-04-25 eval flagged a confusing case where the
-            // operator's interactive shell returned no result for `which
-            // watchman` but doctor still printed "OK" — the cause was a
-            // PATH-export discrepancy between the shell and the spawned
-            // subprocess, and surfacing the resolved path makes the discrepancy
-            // visible without users having to re-run with a verbose flag.
+            // 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
+            // resolved path makes the discrepancy visible without a verbose flag.
             const path = await findExecutable('watchman');
             if (path) {
-                return {
-                    name: 'Watchman available',
-                    passed: true,
-                    severity: 'ok',
-                    message: `OK (${path})`,
-                };
+                return ok('Watchman available', `OK (${path})`);
             }
             return warning('Watchman available', 'watchman is not installed or not on PATH. "fireforge watch" requires it.', 'Install watchman (brew install watchman / dnf install watchman / https://facebook.github.io/watchman/), then re-run doctor.');
         },
@@ -270,12 +261,7 @@ const DOCTOR_CHECKS = [
         name: 'Patches directory exists',
         run: async (ctx) => {
             const patchesExist = await pathExists(ctx.paths.patches);
-            return {
-                name: 'Patches directory exists',
-                passed: true,
-                severity: 'ok',
-                message: patchesExist ? 'OK' : 'No patches/ directory (optional)',
-            };
+            return ok('Patches directory exists', patchesExist ? 'OK' : 'No patches/ directory (optional)');
         },
     },
     {
@@ -285,12 +271,7 @@ const DOCTOR_CHECKS = [
                 return [];
             }
             const patchCount = await countPatches(ctx.paths.patches);
-            return {
-                name: 'Patches found',
-                passed: true,
-                severity: 'ok',
-                message: `${patchCount} patch${patchCount === 1 ? '' : 'es'} found`,
-            };
+            return ok('Patches found', `${patchCount} patch${patchCount === 1 ? '' : 'es'} found`);
         },
     },
     {
@@ -316,25 +297,26 @@ const DOCTOR_CHECKS = [
                 return failure('Patch manifest consistency', '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".');
             }
             try {
-                const repaired = await rebuildPatchesManifest(ctx.paths.patches, ctx.config.firefox.version);
-                // 2026-04-21 eval (Finding #17): the repair path silently
-                // overwrote useful human-written descriptions on recovered
-                // entries, leaving the queue less trustworthy as an audit
-                // trail. The rebuilder now returns the list of filenames
-                // whose metadata was entirely invented, and we name them
-                // explicitly here so the operator knows exactly which
-                // patches to review. Names that DID have a preserved entry
-                // (only `filesAffected` / ordering drifted) are not flagged.
+                const repaired = await rebuildPatchesManifest(ctx.paths.patches, ctx.config.firefox.version, {
+                    waitLockSeconds: resolveWaitLockSeconds(ctx.options.waitLock),
+                    command: 'doctor --repair-patches-manifest',
+                });
+                // The repair path must not silently overwrite human-written
+                // descriptions on recovered entries, which leaves the queue less
+                // 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
+                // flagged.
                 if (repaired.recoveredFilenames.length > 0) {
                     for (const filename of repaired.recoveredFilenames) {
-                        // 2026-04-24 eval Finding 6: the repair path used to tell the
-                        // operator to hand-edit patches.json, which contradicts the
-                        // README + downstream docs that treat the manifest as
-                        // FireForge-owned. Point at the existing `re-export` /
-                        // `export` workflow instead so the fix stays inside the tool:
-                        // re-exporting the same files with an explicit `--description`
-                        // overwrites the recovered entry with operator-supplied
-                        // metadata and supersedes the mtime-based createdAt stamp.
+                        // Telling the operator to hand-edit patches.json contradicts the
+                        // README and downstream docs, which treat the manifest as
+                        // FireForge-owned. Point at the existing `re-export` / `export`
+                        // workflow so the fix stays inside the tool: re-exporting the
+                        // same files with an explicit `--description` overwrites the
+                        // recovered entry with operator-supplied metadata and supersedes
+                        // the mtime-based createdAt stamp.
                         warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. ` +
                             'Re-export the affected files with `fireforge re-export <filename> --description "<your description>"` ' +
                             '(or `fireforge export <paths...> --name <name> --category <category> --description "<your description>"`) ' +
@@ -468,14 +450,14 @@ export async function doctorCommand(projectRoot, options = {}) {
 }
 /** Registers the doctor command on the CLI program. */
 export function registerDoctor(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const command = program
         .command('doctor')
         .description('Diagnose project issues')
         .option('--repair-patches-manifest', 'Rebuild patches/patches.json from the current patch files before reporting results')
         .option('--repair-furnace', 'Reconcile furnace state: clear stale furnace-state.json entries, re-run furnace apply to fix engine drift, and clear the pending-repair marker set by a failed preview teardown')
         .option('--clear-resolution', 'Clear stale pendingResolution state after the patch queue health check reports no errors')
-        .option('--post-rebase-audit', 'Check common registration surfaces after a Firefox source rebase')
-        .action(withErrorHandling(async (options) => {
+        .option('--post-rebase-audit', 'Check common registration surfaces after a Firefox source rebase');
+    addWaitLockOption(command).action(withErrorHandling(async (options) => {
         const result = await doctorCommand(getProjectRoot(), options);
         if (result.exitCode !== 0) {
             process.exitCode = result.exitCode;

package/dist/src/commands/download.js

@@ -76,13 +76,12 @@ 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
+ * 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
- * baseline, but the 2026-04-25 eval saw operators read that as "patches
- * are restored" and skip the import step. The note is suppressed when
- * patches/ is missing or the manifest is empty so unconfigured projects
- * stay quiet.
+ * 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.
  */
 async function noteUnappliedPatches(patchesDir) {
     if (!(await pathExists(patchesDir)))
@@ -97,12 +96,8 @@ 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.
- *
- * Before 0.16.0 the spinner always closed with "Patch-touched files
- * restored", so a fresh project with zero patches saw a claim of restore
- * work that had not happened — misleading and easy to mistake for a
- * silent retry.
+ * "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) {
@@ -192,12 +187,11 @@ async function downloadAndExtractFirefox(args) {
     }
 }
 /**
- * Prints the major-version-hop toolchain nudge when this download moved
- * the engine across a Firefox MAJOR version (152.0b7 → 153.0b8 drill:
- * the first post-hop build died in `mach configure` on a moved cbindgen
- * minimum, and nothing in the download output suggested re-running
- * `fireforge bootstrap`). Quiet on first downloads and same-major
- * re-downloads.
+ * Prints the major-version-hop toolchain nudge when this download moved the
+ * 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.
  */
 function noteMajorVersionHop(previousVersion, version) {
     const hopNotice = formatMajorVersionHopNotice(previousVersion, version);
@@ -207,9 +201,9 @@ function noteMajorVersionHop(previousVersion, version) {
 }
 async function initializeDownloadedEngine(args) {
     const { projectRoot, patchesDir, version, previousVersion, engineDir, replacementActivated, backupEngineDir, } = args;
-    // Finding #17: the git indexing phase of `download` can block for
-    // minutes on a ~600 MB Firefox tree. Emit a one-line heads-up banner
-    // before the spinner starts so CI logs show the expected duration.
+    // The git indexing phase of `download` can block for minutes on a ~600 MB
+    // Firefox tree. Emit a one-line heads-up banner before the spinner starts
+    // so CI logs show the expected duration.
     try {
         info('Indexing downloaded source into git (one-time; typically 3–5 minutes on a ~600 MB Firefox tree)...');
         info('Git phase: initializing/resetting source repository metadata.');
@@ -280,11 +274,11 @@ export async function downloadCommand(projectRoot, options) {
     info(`Firefox version: ${version}`);
     await checkDiskSpace(projectRoot, 5 * 1024 * 1024 * 1024, warn);
     // A legitimate holder of this lock runs for 10+ minutes (download +
-    // extract + git indexing). The previous default 30 s timeout failed the
-    // second invocation with "remove the lock directory if it is stale" advice
-    // while the lock was actively held — 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.
+    // 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
+    // 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 = {
         timeoutMs: 30 * 60_000,
         onTimeoutMessage: 'Timed out waiting for another FireForge download to finish. ' +
@@ -329,11 +323,9 @@ export async function downloadCommand(projectRoot, options) {
                                     // The non-TTY spinner fallback in `src/utils/logger.ts`
                                     // already calls `p.log.step(msg)` from `message()`, so
                                     // forwarding the progress message is the single authority
-                                    // in both TTY and non-TTY modes. Before 0.16.0 this
-                                    // callback also invoked `step(message)` explicitly when
-                                    // stdio was not a TTY, which printed the same step line
-                                    // twice in CI logs (once from the fallback, once from
-                                    // the explicit call).
+                                    // in both TTY and non-TTY modes. Calling `step(message)`
+                                    // explicitly here as well prints the same line twice in
+                                    // CI logs.
                                     onProgress: (message) => {
                                         resumeSpinner.message(message);
                                     },
@@ -359,17 +351,14 @@ export async function downloadCommand(projectRoot, options) {
                             }
                             catch (error) {
                                 resumeSpinner.error('Resume failed');
-                                // Preserve the underlying cause so the user sees *why* the
-                                // resume failed (timeout, permission denied, corrupted object,
-                                // disk full, …) instead of only the generic "partial engine
-                                // exists" story. Verbose mode prints the stack for deeper
-                                // triage.
-                                const cause = toError(error);
-                                verbose(`Resume failure detail: ${cause.message}`);
-                                if (cause.stack) {
-                                    verbose(cause.stack);
-                                }
-                                throw new PartialEngineExistsError(paths.engine, cause);
+                                // 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
+                                // CLI boundary's chain walk under --verbose (src/cli.ts),
+                                // which is what makes PartialEngineExistsError's "re-run
+                                // with --verbose" promise true.
+                                throw new PartialEngineExistsError(paths.engine, toError(error));
                             }
                         }
                         // Re-throw unexpected git errors (corrupted objects, permission
@@ -377,12 +366,7 @@ export async function downloadCommand(projectRoot, options) {
                         // both narratives: "we detected a partial engine and attempted
                         // resume" AND the underlying git failure. Without the wrap the
                         // raw git error loses the context that resume was in flight.
-                        const cause = toError(error);
-                        verbose(`Partial-engine probe failed with unexpected error: ${cause.message}`);
-                        if (cause.stack) {
-                            verbose(cause.stack);
-                        }
-                        throw new PartialEngineExistsError(paths.engine, cause);
+                        throw new PartialEngineExistsError(paths.engine, toError(error));
                     }
                 }
                 throw new EngineExistsError(paths.engine);