@hominis/fireforge 0.45.0 → 0.46.1

package/dist/bin/fireforge.d.ts

@@ -3,7 +3,7 @@
  * FireForge CLI entry point, and the only file that may call process.exit().
  * Library code propagates errors via CommandError or FireForgeError instead.
  *
- * The signal pipeline below composes several lifecycle modules; see
+ * The signal pipeline below composes several lifecycle modules. See
  * docs/lifecycle-invariants.md for who owns what.
  */
 export {};

package/dist/bin/fireforge.js

@@ -4,13 +4,14 @@
  * FireForge CLI entry point, and the only file that may call process.exit().
  * Library code propagates errors via CommandError or FireForgeError instead.
  *
- * The signal pipeline below composes several lifecycle modules; see
+ * The signal pipeline below composes several lifecycle modules. See
  * docs/lifecycle-invariants.md for who owns what.
  */
 import { installBrokenPipeHandler, main } from '../src/cli.js';
 import { emitKilledVerdict } from '../src/commands/test-verdict.js';
 import { forceReleaseHeldLocksForSignal } from '../src/core/file-lock.js';
 import { forceReleaseFurnaceLocksForActiveOperations, isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
+import { closeActiveRunLog } from '../src/core/run-log.js';
 import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
 import { CommandError } from '../src/errors/base.js';
 import { waitForActiveChildShutdown } from '../src/utils/process.js';
@@ -27,22 +28,22 @@ const SIGNAL_CRITICAL_SECTION_TIMEOUT_MS = 5_000;
  * under `run`/`test`, mach under `build`) to shut down after the signal was
  * forwarded to them. Must exceed the largest child grace window
  * (execSmokeRun's killGraceMs default of 10 s) so the SIGTERM → grace →
- * SIGKILL escalation can complete; exiting earlier orphans hung Firefox
+ * SIGKILL escalation can complete. Exiting earlier orphans hung Firefox
  * trees. A second Ctrl+C escalates to SIGKILL immediately.
  */
 const CHILD_SHUTDOWN_TIMEOUT_MS = 12_000;
 /**
  * Upper bound (ms) a delayed exit waits for stdout/stderr to drain. A pipe
- * is ASYNC, so `process.exit()` discards anything queued past the 64 KiB
- * kernel buffer — enough to truncate a JSON payload mid-object. Bounded so
- * a stalled reader cannot wedge a failing process; an EPIPE'd/closed pipe
- * releases the wait immediately.
+ * is async, so `process.exit()` discards anything queued past the 64 KiB
+ * kernel buffer, which is enough to truncate a JSON payload mid-object.
+ * Bounded so a stalled reader cannot wedge a failing process. An
+ * EPIPE'd/closed pipe releases the wait immediately.
  */
 const STDIO_FLUSH_TIMEOUT_MS = 5_000;
 /**
- * Drains stdio, then exits. Every delayed exit routes through here — only
- * the second-Ctrl+C force-exit (an explicit "out NOW") and this helper's
- * own call terminate directly.
+ * Drains stdio, then exits. Every delayed exit routes through here. Only
+ * the second-Ctrl+C force-exit (an explicit request to quit at once) and
+ * this helper's own call terminate directly.
  */
 function exitAfterStdioFlush(code) {
     void waitForStdioDrain(STDIO_FLUSH_TIMEOUT_MS).finally(() => {
@@ -75,9 +76,9 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // A diagnostic must never keep the process from exiting.
         }
         if (isSignalRollbackInFlight()) {
-            // A second Ctrl+C while we're already rolling back is a noisy "I want
-            // out now" — let the second signal terminate the process forcefully
-            // rather than queueing another rollback that will race the first.
+            // A second Ctrl+C while we're already rolling back means the user
+            // wants out now, so let it terminate the process forcefully rather
+            // than queueing another rollback that will race the first.
             process.exit(exitCode);
         }
         // Rollback, critical-section drain, and child shutdown run in parallel.
@@ -86,7 +87,7 @@ function installFurnaceSignalHandler(signal, exitCode) {
         // applied to the engine but a stale session file that mis-tracks progress
         // on `--continue`. Waiting on child shutdown keeps the parent alive through
         // the SIGTERM → grace → SIGKILL escalation execInherit/execSmokeRun forward
-        // to Firefox/mach; exiting first orphans those trees.
+        // to Firefox/mach. Exiting first orphans those trees.
         void Promise.allSettled([
             rollbackActiveOperationsForSignal(signal).catch((error) => {
                 console.error(`Furnace rollback after ${signal} failed:`, error instanceof Error ? error.message : error);
@@ -97,11 +98,16 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // `withFileLock`'s `finally { rm }` never runs across `process.exit`,
             // so both sweeps exist for the same reason. The generic one covers
             // every lock this process holds (engine session, patch directory,
-            // build); the furnace one stays because it carries rollback
+            // build). The furnace one stays because it carries rollback
             // bookkeeping the generic sweep does not, and runs after it so the
             // ownership checks see a settled tree.
             .then(() => forceReleaseHeldLocksForSignal())
             .then(() => forceReleaseFurnaceLocksForActiveOperations())
+            // The run log's held partial line and queued writes do not survive
+            // `process.exit`. The command's own `finally` that would close it is
+            // racing this handler and usually loses. Best-effort like the log
+            // itself: a diagnostic must never keep the process from exiting.
+            .then(() => closeActiveRunLog().catch(() => undefined))
             .finally(() => {
             exitAfterStdioFlush(exitCode);
         });
@@ -114,7 +120,7 @@ main().catch((error) => {
         exitAfterStdioFlush(error.exitCode);
         return;
     }
-    // Truly unexpected — CommandError should have been thrown by withErrorHandling
+    // Unexpected: withErrorHandling should have thrown a CommandError.
     console.error('Fatal error:', error);
     exitAfterStdioFlush(1);
 });

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.45.0",
-  "commit": "19d461eb43b89962970510f9a2e655704e9fb952",
-  "shortCommit": "19d461eb43b8",
+  "version": "0.46.1",
+  "commit": "821990fd7d076a205f37618055c0a01a95180aed",
+  "shortCommit": "821990fd7d07",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-09-01T10:47:47.465Z"
+  "buildTime": "2026-09-05T22:29:34.415Z"
 }

package/dist/src/cli-usage-error.d.ts

@@ -0,0 +1,46 @@
+import { FireForgeError } from './errors/base.js';
+/**
+ * Stable machine-readable tag for an error class, for the `--json` envelope.
+ *
+ * Derived from the class name rather than hand-mapped: a new error class gets
+ * a sensible tag automatically, and the mapping cannot drift out of sync with
+ * the taxonomy. `ConfigNotFoundError` becomes `config-not-found`.
+ *
+ * @param error - The error being rendered
+ * @returns A kebab-case tag with the `Error` suffix stripped
+ */
+export declare function machineErrorCode(error: FireForgeError): string;
+/**
+ * Whether the invocation asked for machine-readable output.
+ *
+ * Reading the flag from argv is blunt but exact: if the invocation asked for
+ * machine output, stdout belongs to the payload from the first byte, before
+ * commander has parsed anything.
+ *
+ * @param argv - Process argv (defaults to `process.argv`)
+ * @returns True when `--json` or `--raw` is present
+ */
+export declare function wantsMachineOutput(argv?: readonly string[]): boolean;
+/**
+ * Converts a `CommanderError` thrown out of `parseAsync` into the exit
+ * contract, and rethrows anything else untouched.
+ *
+ * `--help` and `--version` also travel through `exitOverride()` (codes
+ * `commander.helpDisplayed` / `commander.version`, exit 0): commander has
+ * already written their output, so those simply return. So does
+ * `commander.help`: a command group invoked with no subcommand (`fireforge`,
+ * `fireforge tree`), for which commander prints the group's help and would
+ * exit 1. That is an informational invocation rather than a wrong flag.
+ * `patch`, `token` and `furnace` already answer it with help and exit 0
+ * through an explicit action, and the groups without one must not exit 8 (or
+ * leak commander's `(outputHelp)` placeholder into a `--json` envelope)
+ * merely for lacking it. A genuine usage error has already had its message
+ * written to stderr by commander. It becomes exit 8, and under `--json` it
+ * also gets the standard refusal envelope on stdout so a scripted consumer
+ * sees a parseable failure.
+ *
+ * @param error - Whatever `parseAsync` rejected with
+ * @param machineOutput - Whether the invocation asked for `--json`/`--raw`
+ * @throws CommandError carrying `INVALID_ARGUMENT` for a usage error
+ */
+export declare function handleParseError(error: unknown, machineOutput: boolean): void;

package/dist/src/cli-usage-error.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Maps commander's own parse failures onto the FireForge exit-code contract.
+ *
+ * Commander terminates the process itself on a usage error (unknown option,
+ * missing argument, unknown command) with exit 1, which contradicts the
+ * documented `INVALID_ARGUMENT` (8) in `docs/exit-codes.md` and bypasses the
+ * `--json` refusal envelope because no action (and therefore no
+ * `withErrorHandling` wrapper) ever runs. `createProgram` installs
+ * `exitOverride()` so those failures surface as a thrown `CommanderError`,
+ * and `main` routes them through here.
+ */
+import { CommanderError } from 'commander';
+import { CommandError, FireForgeError, InvalidArgumentError } from './errors/base.js';
+import { emitMachineError } from './utils/machine-output.js';
+/**
+ * Stable machine-readable tag for an error class, for the `--json` envelope.
+ *
+ * Derived from the class name rather than hand-mapped: a new error class gets
+ * a sensible tag automatically, and the mapping cannot drift out of sync with
+ * the taxonomy. `ConfigNotFoundError` becomes `config-not-found`.
+ *
+ * @param error - The error being rendered
+ * @returns A kebab-case tag with the `Error` suffix stripped
+ */
+export function machineErrorCode(error) {
+    return error.name
+        .replace(/Error$/, '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .toLowerCase();
+}
+/**
+ * Whether the invocation asked for machine-readable output.
+ *
+ * Reading the flag from argv is blunt but exact: if the invocation asked for
+ * machine output, stdout belongs to the payload from the first byte, before
+ * commander has parsed anything.
+ *
+ * @param argv - Process argv (defaults to `process.argv`)
+ * @returns True when `--json` or `--raw` is present
+ */
+export function wantsMachineOutput(argv = process.argv) {
+    return argv.includes('--json') || argv.includes('--raw');
+}
+/**
+ * Converts a `CommanderError` thrown out of `parseAsync` into the exit
+ * contract, and rethrows anything else untouched.
+ *
+ * `--help` and `--version` also travel through `exitOverride()` (codes
+ * `commander.helpDisplayed` / `commander.version`, exit 0): commander has
+ * already written their output, so those simply return. So does
+ * `commander.help`: a command group invoked with no subcommand (`fireforge`,
+ * `fireforge tree`), for which commander prints the group's help and would
+ * exit 1. That is an informational invocation rather than a wrong flag.
+ * `patch`, `token` and `furnace` already answer it with help and exit 0
+ * through an explicit action, and the groups without one must not exit 8 (or
+ * leak commander's `(outputHelp)` placeholder into a `--json` envelope)
+ * merely for lacking it. A genuine usage error has already had its message
+ * written to stderr by commander. It becomes exit 8, and under `--json` it
+ * also gets the standard refusal envelope on stdout so a scripted consumer
+ * sees a parseable failure.
+ *
+ * @param error - Whatever `parseAsync` rejected with
+ * @param machineOutput - Whether the invocation asked for `--json`/`--raw`
+ * @throws CommandError carrying `INVALID_ARGUMENT` for a usage error
+ */
+export function handleParseError(error, machineOutput) {
+    if (!(error instanceof CommanderError)) {
+        throw error;
+    }
+    if (error.exitCode === 0 || error.code === 'commander.help') {
+        return;
+    }
+    // Commander's message carries its own `error: ` prefix. Strip it so the
+    // envelope text matches how every other refusal reads.
+    const usage = new InvalidArgumentError(error.message.replace(/^error:\s*/, ''));
+    if (machineOutput) {
+        emitMachineError(machineErrorCode(usage), usage.message, usage.code);
+    }
+    throw new CommandError(usage.code);
+}

package/dist/src/cli.d.ts

@@ -6,13 +6,18 @@ import { Command } from 'commander';
  * We treat this as a clean exit.
  */
 export declare function installBrokenPipeHandler(): void;
-/** Removes the broken-pipe handler installed for CLI tests. */
+/**
+ * Removes the broken-pipe handler installed for CLI tests.
+ *
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
+ */
 export declare function resetBrokenPipeHandlerForTests(): void;
 /**
  * Gets the project root directory.
  * Walks up from the current working directory until a fireforge.json is found.
  * Throws a {@link ConfigNotFoundError} (code: CONFIG_ERROR) when no
- * fireforge.json is found within the walk depth limit — the error is
+ * fireforge.json is found within the walk depth limit. The error is
  * user-facing so `withErrorHandling` can print the guidance without
  * the stack dump that a plain `Error` would trigger.
  */

package/dist/src/cli.js

@@ -2,6 +2,7 @@
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { Command, Help } from 'commander';
+import { handleParseError, machineErrorCode, wantsMachineOutput } from './cli-usage-error.js';
 import { COMMAND_MANIFEST } from './commands/manifest.js';
 import { runTreeGuardHook } from './core/tree-guard.js';
 import { CancellationError, CommandError, FireForgeError, InternalInvariantError, } from './errors/base.js';
@@ -32,27 +33,11 @@ function getBrokenPipeHandler(state) {
     state[brokenPipeListenerKey] = handler;
     return handler;
 }
-/**
- * Stable machine-readable tag for an error class, for the `--json` envelope.
- *
- * Derived from the class name rather than hand-mapped: a new error class gets
- * a sensible tag automatically, and the mapping cannot drift out of sync with
- * the taxonomy. `ConfigNotFoundError` becomes `config-not-found`.
- *
- * @param error - The error being rendered
- * @returns A kebab-case tag with the `Error` suffix stripped
- */
-function machineErrorCode(error) {
-    return error.name
-        .replace(/Error$/, '')
-        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-        .toLowerCase();
-}
 /**
  * Prints an error's `cause` chain under `--verbose`.
  *
- * Nine error classes declare a `cause` and twenty-two throw sites pass one;
- * without this the underlying git stderr, errno or parse failure never
+ * Nine error classes declare a `cause` and twenty-two throw sites pass one.
+ * Without this the underlying git stderr, errno or parse failure never
  * reaches the operator, because a `FireForgeError` renders as its
  * `userMessage` and stops.
  *
@@ -93,7 +78,12 @@ export function installBrokenPipeHandler() {
     process.stderr.on('error', handleStreamError);
     state[brokenPipeInstalledKey] = true;
 }
-/** Removes the broken-pipe handler installed for CLI tests. */
+/**
+ * Removes the broken-pipe handler installed for CLI tests.
+ *
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
+ */
 export function resetBrokenPipeHandlerForTests() {
     const state = getProcessState();
     const handleStreamError = state[brokenPipeListenerKey];
@@ -108,14 +98,14 @@ export function resetBrokenPipeHandlerForTests() {
  * Maximum number of directory levels to walk when searching for
  * `fireforge.json`. `dirname()` walking is pure string manipulation and
  * cannot cycle (the `parent === current` check already terminates at the
- * root); this cap only bounds the cost on pathologically deep paths.
+ * root). This cap only bounds the cost on pathologically deep paths.
  */
 const MAX_PROJECT_ROOT_WALK_DEPTH = 50;
 /**
  * Gets the project root directory.
  * Walks up from the current working directory until a fireforge.json is found.
  * Throws a {@link ConfigNotFoundError} (code: CONFIG_ERROR) when no
- * fireforge.json is found within the walk depth limit — the error is
+ * fireforge.json is found within the walk depth limit. The error is
  * user-facing so `withErrorHandling` can print the guidance without
  * the stack dump that a plain `Error` would trigger.
  */
@@ -143,15 +133,15 @@ export function getProjectRoot() {
  */
 export function withErrorHandling(handler) {
     return async (...args) => {
-        // Rule 3 of docs/machine-output.md: machine mode engages BEFORE any
-        // output. Anything that throws on the way in — most visibly
-        // `getProjectRoot`'s ConfigNotFoundError — would otherwise render a
+        // Rule 3 of docs/machine-output.md: machine mode engages before any
+        // output. Anything that throws on the way in (most visibly
+        // `getProjectRoot`'s ConfigNotFoundError) would otherwise render a
         // clack-styled block to stdout and leave a `--json` consumer with
         // un-parseable output. Reading the flag from argv is blunt but exact: if
         // the invocation asked for machine output, stdout belongs to the payload
         // from the first byte.
-        const wantsMachineOutput = process.argv.includes('--json') || process.argv.includes('--raw');
-        if (wantsMachineOutput) {
+        const machineOutput = wantsMachineOutput();
+        if (machineOutput) {
             setMachineOutputMode(true);
         }
         try {
@@ -166,9 +156,9 @@ export function withErrorHandling(handler) {
             }
             if (error instanceof CancellationError) {
                 cancel('Operation cancelled');
-                // 130 (128+SIGINT) is the conventional "user interrupted" code —
-                // scripts/CI can distinguish a deliberate prompt cancellation from
-                // a real failure (which exits 1).
+                // 130 (128+SIGINT) is the conventional "user interrupted" code, so
+                // scripts/CI can distinguish a prompt cancellation from a real
+                // failure (which exits 1).
                 throw new CommandError(ExitCode.USER_CANCELLED);
             }
             // An invariant failure is the one FireForgeError whose stack is part
@@ -189,9 +179,9 @@ export function withErrorHandling(handler) {
                 logError(error.userMessage);
                 printCauseChain(error);
                 // Not when a payload already owns stdout: `status --json --fail-on`
-                // writes its full document and THEN refuses, and appending an
+                // writes its full document and then refuses, and appending an
                 // envelope would make that two JSON documents.
-                if (wantsMachineOutput && !isStdoutSealed()) {
+                if (machineOutput && !isStdoutSealed()) {
                     emitMachineError(machineErrorCode(error), error.message, error.code);
                 }
                 throw new CommandError(error.code);
@@ -205,9 +195,9 @@ export function withErrorHandling(handler) {
         }
         finally {
             // Central machine-mode and stdout-seal reset. Commands leave both
-            // ENGAGED while an error propagates (a mid-throw restore would route
+            // engaged while an error propagates (a mid-throw restore would route
             // the styled error to stdout, corrupting the `--json`/`--raw` payload
-            // stream or displacing the FIREFORGE-VERDICT line); the reset happens
+            // stream or displacing the FIREFORGE-VERDICT line). The reset happens
             // here, after logError has picked its stream, so no state leaks into a
             // subsequent in-process invocation.
             setMachineOutputMode(false);
@@ -255,9 +245,9 @@ function buildGroupedHelpFormatter(manifest) {
             return formatHelpLine(term, desc, termWidth, helpWidth);
         });
         // -V/--version is handled in main() before commander parses (a real
-        // root-level `.version()` option would claim `--version` ANYWHERE in
+        // root-level `.version()` option would claim `--version` anywhere in
         // argv under commander's default parsing, breaking subcommand flags
-        // like `source set --version <v>`); advertise it here so root help
+        // like `source set --version <v>`). Advertise it here so root help
         // stays truthful.
         optionLines.unshift(formatHelpLine('-V, --version', 'output the version number', termWidth, helpWidth));
         if (optionLines.length > 0) {
@@ -339,6 +329,11 @@ export function createProgram() {
     const program = new Command();
     program
         .name('fireforge')
+        // Usage errors must not let commander call process.exit(1) itself: the
+        // documented code is INVALID_ARGUMENT (8) and `--json` owes a refusal
+        // envelope. Installed before any subcommand registers, because
+        // `.command()` copies the override into the child at creation time.
+        .exitOverride()
         .description('A build tool for customizing Firefox')
         .option('-v, --verbose', 'Enable debug output')
         .option('--ignore-corrupt-tree-marker', 'Run even when .fireforge/tree.json exists but cannot be parsed. Without this the tree guard refuses, because an unreadable marker leaves it unknown whether this is a snapshot or the primary tree.')
@@ -348,9 +343,9 @@ export function createProgram() {
             setVerbose(true);
         }
     })
-        // Verification-tree guard: when the cwd resolves into a
-        // tree snapshot, refuse mutating commands before their action runs —
-        // one hook covers every command regardless of how the cwd got there.
+        // Verification-tree guard: when the cwd resolves into a tree snapshot,
+        // refuse mutating commands before their action runs. One hook covers
+        // every command regardless of how the cwd got there.
         .hook('preAction', async (thisCommand, actionCommand) => {
         await runTreeGuardHook(thisCommand.name(), actionCommand);
     });
@@ -365,7 +360,7 @@ export function createProgram() {
     // Uniform `--wait-lock`: scripted sequences blanket-append the flag, and a
     // subcommand that rejects it with "unknown option" kills the sequence with
     // a usage error instead of a lock message. Applied after registration so it
-    // covers every subcommand at every depth; commands that already declare the
+    // covers every subcommand at every depth. Commands that already declare the
     // honoring flag keep it untouched.
     ensureWaitLockOptionEverywhere(program);
     return program;
@@ -374,13 +369,13 @@ export function createProgram() {
  * Main CLI entry point.
  */
 export async function main() {
-    // Root-level --version/-V handling. Deliberately NOT a commander
-    // `.version()` option: under commander's default (non-positional)
-    // parsing, a root version option claims `--version` anywhere in argv and
-    // hijacks subcommand flags like `source set --version <v>`. The rule
-    // here: when NO subcommand was given, any -V/--version among the root
-    // flags prints the version — so `fireforge --verbose --version` works,
-    // and `fireforge source set --version 152` is untouched.
+    // Root-level --version/-V handling. This is not a commander `.version()`
+    // option, because under commander's default (non-positional) parsing a
+    // root version option claims `--version` anywhere in argv and hijacks
+    // subcommand flags like `source set --version <v>`. The rule here: when no
+    // subcommand was given, any -V/--version among the root flags prints the
+    // version, so `fireforge --verbose --version` works and
+    // `fireforge source set --version 152` is untouched.
     const userArgs = process.argv.slice(2);
     const hasSubcommand = userArgs.some((arg) => !arg.startsWith('-'));
     if (!hasSubcommand && userArgs.some((arg) => arg === '--version' || arg === '-V')) {
@@ -388,5 +383,10 @@ export async function main() {
         return;
     }
     const program = createProgram();
-    await program.parseAsync(process.argv);
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        handleParseError(error, wantsMachineOutput());
+    }
 }

package/dist/src/commands/bootstrap-checks.js

@@ -13,7 +13,8 @@ export function detectBootstrapIssues(output) {
     const hasTraceback = /traceback \(most recent call last\):/i.test(normalized);
     const has403 = /\bhttp(?:\s+error)?\s*403\b/i.test(normalized) || /\b403\b.*forbidden/i.test(normalized);
     if (has403) {
-        // The traceback is just the stack trace from the HTTP error — report once.
+        // The traceback is just the stack trace from the HTTP error, so report
+        // it once.
         issues.push('sdk-fetch-403');
     }
     else if (hasTraceback) {

package/dist/src/commands/bootstrap.js

@@ -10,7 +10,6 @@ import { ExitCode } from '../errors/codes.js';
 import { error, info, intro, outro, warn } from '../utils/logger.js';
 import { detectBootstrapIssues, runPostBootstrapChecks, } from './bootstrap-checks.js';
 import { reportDoctorResults } from './doctor.js';
-import { resolveDoctorSeverity } from './doctor-check-core.js';
 /** One sentence per detected issue, keyed by the scanner's own tags. */
 const BOOTSTRAP_FAILURE_SENTENCES = {
     'python-traceback': 'Bootstrap emitted a Python traceback.',
@@ -24,7 +23,7 @@ const BOOTSTRAP_FAILURE_SENTENCES = {
 function buildBootstrapFailureMessage(output) {
     // Delegates detection to the canonical scanner rather than keeping a
     // second copy of its six regexes. The copies had already disagreed: this
-    // one reported a traceback AND a 403 separately, while
+    // one reported a traceback and a 403 separately, while
     // `detectBootstrapIssues` collapses them, because a bootstrap traceback
     // accompanying a 403 is just the stack trace from that HTTP error.
     const issues = detectBootstrapIssues(output).map((issue) => BOOTSTRAP_FAILURE_SENTENCES[issue]);
@@ -68,7 +67,7 @@ export async function bootstrapCommand(projectRoot) {
         // Shares one resolver with reportDoctorResults so the two consumers of
         // this same array cannot drift apart on how a check's severity is
         // derived.
-        const hasErrors = checks.some((c) => resolveDoctorSeverity(c) === 'error');
+        const hasErrors = checks.some((c) => c.severity === 'error');
         info('');
         if (hasErrors) {
             warn('Bootstrap completed with issues:');
@@ -80,7 +79,7 @@ export async function bootstrapCommand(projectRoot) {
         if (hasErrors) {
             outro('Build dependencies installed with errors');
             // Propagate the failure (mirroring doctor's exit-code handling)
-            // instead of exiting 0 — CI gating on bootstrap used to proceed to a
+            // instead of exiting 0. CI gating on bootstrap used to proceed to a
             // build that could not succeed because error-severity check results
             // were discarded here.
             return checksExitCode;

package/dist/src/commands/build.js

@@ -13,6 +13,7 @@ import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { formatToolchainMismatchMessage, runToolchainPreflight, } from '../core/toolchain-preflight.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
 import { checkDiskSpace } from '../utils/fs.js';
 import { error, info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
@@ -29,9 +30,9 @@ function parseJobCount(value) {
  * Patches `mozinfo.json` under the active obj-* directory so its recorded
  * paths match the current engine checkout, then runs `mach configure` to
  * regenerate every other generated path alongside it. Throws with the
- * original mismatch guidance when the rewriter refuses to proceed — that
- * always covers the unsafe cases, so the operator still gets the correct
- * fallback recovery instruction.
+ * original mismatch guidance when the rewriter refuses to proceed. That
+ * covers the unsafe cases, so the operator still gets the correct fallback
+ * recovery instruction.
  */
 async function rewriteAndReconfigure(engineDir, objDir, mismatchMessage) {
     const rewriteSpinner = spinner('Rewriting mozinfo.json paths...');
@@ -200,7 +201,7 @@ async function runBuildCommandBody(projectRoot, options) {
     // and fail fast naming `fireforge bootstrap` instead of dying ~8s into
     // configure with mach's "./mach bootstrap" remediation text. Fail-soft by
     // design: only a definitively parsed minimum vs a definitively probed host
-    // version can fail here; anything uncertain proceeds to mach, where the
+    // version can fail here. Anything uncertain proceeds to mach, where the
     // mach-error-hints translator still names the right remedy.
     const toolchainMismatches = await runToolchainPreflight(paths.engine);
     if (toolchainMismatches.length > 0) {
@@ -216,7 +217,7 @@ async function runBuildCommandBody(projectRoot, options) {
             // Safe-relocation rewrite path: patch mozinfo.json paths in place so
             // `mach configure` can regenerate the backend without scrubbing the
             // whole obj tree. The rewriter refuses anything that is not a pure
-            // prefix-move; on refusal we surface the refusal reason alongside
+            // prefix-move. On refusal we surface the refusal reason alongside
             // the original mismatch guidance and abort.
             await rewriteAndReconfigure(paths.engine, buildCheck.objDir, mismatchMessage);
         }
@@ -274,7 +275,7 @@ async function runBuildCommandBody(projectRoot, options) {
         // overlapping `fireforge build` / `fireforge build --ui` commands
         // against the same engine tree serialise instead of racing through the
         // same obj-*. A `build --ui` launched during an in-progress full build
-        // otherwise hits `No rule to make target 'XUL'` in mach — the
+        // otherwise hits `No rule to make target 'XUL'` in mach, the
         // downstream consequence of an incomplete backend, with no clue that a
         // concurrent build caused it. The lock turns the second invocation's
         // failure into an explicit refusal naming the holder PID.
@@ -288,10 +289,7 @@ async function runBuildCommandBody(projectRoot, options) {
     catch (error) {
         throw new BuildError('Build process failed to start', options.ui ? 'mach build faster' : 'mach build', error instanceof Error ? error : undefined);
     }
-    const duration = Date.now() - startTime;
-    const minutes = Math.floor(duration / 60000);
-    const seconds = Math.floor((duration % 60000) / 1000);
-    const timeStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+    const timeStr = elapsedSince(startTime);
     if (result.exitCode !== 0) {
         error(`Build failed after ${timeStr}`);
         const machCommand = options.ui ? 'mach build faster' : 'mach build';
@@ -315,9 +313,10 @@ async function runBuildCommandBody(projectRoot, options) {
     // Matching only (1) leaves operators on the (2) path seeing mach's own
     // "Configure complete!" and "run |mach build|" lines unexplained between
     // mach's "Your build was successful!" and FireForge's "Build completed in
-    // Xm Ys" outro — a contradictory tail. Both shapes route through the same
-    // annotation, emitted BEFORE FireForge's outro so the operator's last
-    // terminal line is the explanation, not the confusing mach guard text.
+    // Xm Ys" outro, a contradictory tail. Both shapes route through the same
+    // annotation, emitted before FireForge's outro so the operator's last
+    // terminal line is the explanation instead of the confusing mach guard
+    // text.
     const staleConfigurePatterns = [
         /config\.status is out of date/i,
         /Config object not found by mach\.[\s\S]*Configure complete!/i,
@@ -331,10 +330,12 @@ async function runBuildCommandBody(projectRoot, options) {
     }
     // Warn-only post-build audit: surfaces silent packaging drops (files
     // edited in engine/ but never registered for packaging) against the
-    // previous-build baseline. Never fails the build; the worst case is a
+    // previous-build baseline. Never fails the build. The worst case is a
     // warning an operator chooses to investigate.
     try {
-        await auditBuildArtifacts(projectRoot, paths.engine, previousBaseline);
+        await auditBuildArtifacts(projectRoot, paths.engine, previousBaseline, {
+            ...(config.buildAudit?.unpackaged ? { unpackaged: config.buildAudit.unpackaged } : {}),
+        });
     }
     catch (auditError) {
         verbose(`Audit skipped: ${toError(auditError).message}`);
@@ -346,14 +347,23 @@ async function runBuildCommandBody(projectRoot, options) {
     outro(`Build completed in ${timeStr}!`);
 }
 /**
- * Persists the full-coverage baseline; a failed write never fails the build.
+ * Persists the full-coverage baseline. A failed write never fails the build.
  * `--ui` is a `mach build faster`, so it is recorded as such: its `jar.mn`
  * fingerprints are carried forward from the previous baseline rather than
  * refreshed, which is why that baseline is threaded through.
  */
 async function recordFullBuildBaseline(projectRoot, engineDir, binaryName, ui, previousBaseline) {
     try {
-        await writeBuildBaseline(projectRoot, engineDir, binaryName, 'full', previousBaseline, ui ? 'fireforge build --ui' : 'fireforge build', 'auto', ui ? 'faster' : 'full');
+        await writeBuildBaseline({
+            projectRoot,
+            engineDir,
+            binaryName,
+            testPackagingCoverage: 'full',
+            previousBaseline,
+            recordedBy: ui ? 'fireforge build --ui' : 'fireforge build',
+            staticComponentsHandling: 'auto',
+            buildKind: ui ? 'faster' : 'full',
+        });
     }
     catch (baselineError) {
         verbose(`Could not persist build baseline: ${toError(baselineError).message}`);