@hominis/fireforge 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 0.46.0
+
+### Downstream friction
+
+- **A successful build printed seven `Audit:` warnings, none of them real, and summarised `4 missing` on a run with zero real misses.** The post-build packaging audit is warn-only, which makes a false positive cheap alone and ruinous in aggregate: an operator who learns these lines are usually wrong stops reading the one that is right. Four distinct causes, each now its own classification with its own counted skip reason. (1) `--with-branding` selects ONE branding tree; files under the others are not inputs to the objdir at all, so "no packaged artifact" is their expected state — and worse, the basename walker matched them against the SELECTED branding's same-named artifact and reported them "newer than its packaged artifact", a stale claim about a comparison with no meaning. The selected branding is read from the `engine/mozconfig` FireForge generates, through the `extractWithBrandingPath` that already existed for the branding-agreement assertion; when the mozconfig cannot be read or names no branding, the old behaviour is kept deliberately — a skip that cannot name its evidence is a masked warning. (2) `detectPlatformGate` reads the file's OWN nearest `moz.build`, but Firefox gates whole subtrees one or more levels up: nothing in `toolkit/mozapps/defaultagent/moz.build` says "Windows only", yet `toolkit/moz.build` reaches it through a `DIRS +=` nested inside `OS_ARCH == "WINNT"`, a `CC_TYPE` test and `MOZ_DEFAULT_BROWSER_AGENT`. A new ancestor walk collects the FULL enclosing `if` stack for the `DIRS` entry that reaches the file's directory — not the innermost, which `findEnclosingGate` returns, because it is the OUTERMOST one that excludes the directory off-Windows — and only quoted values inside a `DIRS` assignment are considered, so an unrelated string literal cannot gate a subtree. The walk is bounded (12 ancestors, 256 KiB per `moz.build`) and an unreadable or oversized ancestor falls back to warning. (3) `*.stories.mjs` / `*.stories.js` are rendered by the in-tree Storybook's own Vite config and carry no packaging entry; the suffix list is closed and documented rather than generalised to "anything with a dotted infix", which would swallow the `*.worker.js` and `*.sys.mjs` that ARE packaged. (4) A deliberately unpackaged source — a type-only mirror whose header says it is never loaded — is the one case FireForge cannot derive from the tree, so it takes a declaration: `buildAudit.unpackaged: [{ path, reason }]` in `fireforge.json`, `reason` required and non-empty because the declaration IS the evidence. It follows the 0.45.0 `--expect-unmanaged` model: admitted paths are LISTED, never silenced, and an admitted path that DOES resolve to a packaged artifact is reported as a STALE carve-out rather than suppressed — the declaration asserts a fact about the tree that has stopped being true. One deliberate divergence from that model: a declaration matching nothing that changed is NOT reported. `--expect-unmanaged` reports its unmet entries because it is a per-invocation flag list where an unmet entry is probably a typo in the command just typed; this is a standing list checked only against the files that happened to change, so "not met" is the normal case and reporting it would put a warning on every build. `**` in a carve-out path is refused outright — a subtree exception is how a reviewed one quietly becomes a blanket one. The `Packaged:` line now names every non-zero skip class with its count, so the four false `missing` cannot recur without a counterpart in the numbers an operator can check. A downstream-shaped fixture (selected branding, unselected branding, ancestor-gated directory, story file, declared mirror) asserts zero warnings and the per-class counts, with a negative control per class — a classifier that skipped unconditionally would also pass a zero-warnings assertion.
+- **Considered and rejected: a header marker instead of the config list.** A first-comment `fireforge: unpackaged` line would keep the declaration next to the file it describes, which is the strongest argument for it, and the 0.45.0 reasoning against standing config lists ("a standing exception nobody re-reads is exactly what this refusal exists to prevent") appears to apply. It does not, and the difference is what decided it: `--expect-unmanaged` guards a REFUSAL, where a forgotten carve-out silently disarms a gate on the next run; this guards a WARNING, and the failure mode is the opposite — nobody can review a suppression they cannot enumerate. A marker is invisible to anyone auditing what a project has admitted, cannot be diffed as a set, and puts the rationale in the one place a reader of `fireforge.json` will not look. The config list is reviewable in one place, is what `git blame` answers questions about, and — because admitted paths are listed on every run and a stale one is reported — cannot rot unnoticed the way the 0.45.0 entry feared.
+- **`fireforge test` preflight refusals were invisible in redirected output.** With stdout redirected, both `fireforge test …` and `fireforge -v test …` printed only `FIREFORGE-VERDICT: FAIL reason=preflight`, and the run log the line named held only the pre-test build. The gates were right; the text was lost twice over, for two independent reasons. `emitFailVerdict` calls `setStdoutSealed(true)` — the seal that keeps the verdict the run's LAST stdout write — and `routeToStderr()` then sends everything the CLI error boundary renders to stderr, so a `> file` capture kept the verdict and dropped the reason. And that rendering happens after `testCommand`'s `finally` has already closed and flushed the run log, so the artifact the verdict's own `log=` key points at never contained the refusal either. The obvious fix — unsealing, or rendering to stdout from the boundary — trades away the contract that made the verdict readable in the first place. Instead the refusal's own text is written to stdout AND into the run log inside `testCommand`'s catch, BEFORE the verdict is emitted: both channels get the reason and the verdict is still last. Preflight gates that classify themselves now throw `PreflightRefusalError`, which carries a stable kebab-case class and reports it as an additive `note=` on the verdict line (`stale-browser`, `coverage-replaced`, `marionette-port-busy`, …). `reason=` is unchanged and still comes from the closed set, `note=` joins the existing additive `log=`/`signal=`/`shards=` keys, and a gate that names no class emits no `note=` — so a consumer tokenising `key=value` pairs is unaffected. `PreflightRefusalError` extends `GeneralError` and keeps exit 1: no exit code moves.
+- **The staged-dependency registration rule was blind to binary-created files, and its other half did not exist.** Patch 102's `xpcshell.toml` registers `support-files = ["fixtures/*.sqlite"]` for a fixture patch 103 creates as `new file mode` + `GIT binary patch`. With the declaration present, lint reported `staged-dependency-unused`; with it removed, lint was equally silent. Two independent defects, and the symmetry is what made them invisible rather than merely absent. First, `detectNewFilesInDiff` does see the binary creation, but `buildPatchQueueContext` then drops it: `extractNewFileContent` correctly refuses to decode a binary body, and the `catch` left the path out of `newFiles` — the map the registration `creates` resolution indexed. So a declared dependency on a binary could never resolve. A new `createdFiles: Set<string>` beside `newFiles` carries every creation regardless of body kind, and the registration index is built from it; `newFiles` stays text-only, because 0.45.0's `buildNewFileTextProjection` reasoning still holds — a binary authors no imports, so the import rules gain nothing from it. A payload-less `Binary files … differ` section counts as a creation too whenever it carries `new file mode`: the file exists after apply either way, and only the body differs. Making the field required forced every projection site (`export --order`, `re-export --files`, `re-export --scan`, `patch split`, `patch move-files`) to supply it, which also collapsed three open-coded copies of the projection onto the existing `projectEntryBody`. Second, there was no "declaration needed" arm for registrations at all: `forward-import` is import-only, and registration metadata was checked for STALENESS once declared and never for absence. A new `forward-registration` rule flags a test manifest that registers a file only a later-ordered patch creates, resolving each `support-files` entry against the manifest's own directory and expanding a `*` within one path segment. Scope is deliberately narrow and the alternative is rejected outright: jar.mn packaging lines and actor/customElements registrations name their targets through indirection the linter cannot resolve without the build system, and a rule that guessed there would refuse correct queues on a Firefox-sized tree. The manifest basename list is closed (`xpcshell`, `mochitest`, `browser`, `chrome`, `a11y`, `.toml` and `.ini`) rather than "anything `.toml`", which would sweep in Cargo and taskcluster manifests whose `support-files`-shaped keys mean something else. Both rules share one apply-order predicate, so the arm that FLAGS an undeclared registration and the arm that VALIDATES a declared one cannot disagree about the same pair of patches. The new rule is an **error**, matching `forward-import` for the identical defect class, and consumers should expect it to find pre-existing instances: measured against the reporting fork's own 338-patch queue it raises 48 findings where there were previously zero cross-patch findings, from exactly three shared test manifests (102's `xpcshell.toml`, 111's and 201's `browser.toml`) whose directories later patches add fixtures to. Those are genuine — applying the queue up to 201 leaves `browser.toml` naming support files that do not exist yet, which is a bisect-time failure — so they are reported rather than tuned away; a rule narrowed until one fork's queue passed would be shaped to that fork's data, and an exact filename is a MORE certain forward reference than the glob the report was about, not less. Each message carries the paste-and-run `patch staged-dependency --add --kind registration` that discharges it, and reordering is the other option.
+- **The `forward-registration` remedy did not discharge the finding it printed.** All 44 unique paste-and-run commands the new rule emitted on the reporting fork's 338-patch queue were run verbatim; the next `lint --per-patch --max-warnings 0` came back with zero `forward-registration` errors and **36 `staged-dependency-unused` warnings** — "the patch does not add that line" — on the declarations the remedy had just told the operator to write. The 0.46.0 claim that both arms "share one apply-order predicate, so the arm that FLAGS and the arm that VALIDATES cannot disagree about the same pair of patches" was true and insufficient: they agreed about ORDER and disagreed about the LINE, and the line is what the operator pastes. The rule resolved a `support-files` ENTRY and synthesised `--line` as `support-files = ["<entry>"]`, while `isRegistrationLinePresent` compares `--line`, whitespace-trimmed, against the lines the patch ADDS — a match only for a manifest whose array is single-line and single-entry. A Firefox tree writes the other two shapes constantly: 201's `browser.toml` lists its support files one per line inside a multi-line array, and 111's and 201's per-test sections use two-entry one-liners, so 36 of 44 synthesised lines matched nothing. `extractSupportFileEntries` now matches quoted tokens per PHYSICAL line instead of over the accumulated array body, so every entry carries the line it is written on, and the printed `--line` is that line — which is what `--line`'s help text has always promised ("as the patch adds it") and what `--remove` matches on. Entries are deduplicated across the manifest, and an entry spelled out on several added lines prints the first and says so: one declaration covers the file either way, because the declared check keys on `--file` and `--creates`. Registration lines carry their own quotes, so both messages that print a command now escape them for the shell. **Considered and rejected: relaxing the used-arm** to treat a declaration as used when the patch adds a line CONTAINING the declared entry as a quoted token. It would also have cleared the 36, and it is the smaller diff, but it makes `--line` mean two different things in the two directions — the add path would accept a line the patch never adds, and `--remove --line` would then have to carry the same relaxed match or a declaration would be unremovable by the command that created it. Printing the truth keeps one meaning. The fork's 44 hand-corrected declarations are exactly the shapes the fixed rule now emits, and a fixture pins each shape so a later change cannot strand them.
+- **The `staged-dependency-unused` remedy named a command that refuses without its arguments, and `--patches` refused the ordinal it advertised.** The warning said to remove the stale declaration with `fireforge patch staged-dependency --remove --kind registration`, but that form refuses without `--file` AND `--line` (`--creates` only disambiguates) — and the `--line` it needs is the stale one the declaration holds, which the warning already had in hand. It now prints the whole command, shell-quoted, so the remedy is paste-and-run in both directions. Separately, `lint --per-patch --patches 102` was refused with "No patch in the queue matches" by a message that offers stems in the same breath; the bare order number is now an alias, both as the manifest records it and as the filename pads it (`2` and `002`).
+- **`fireforge token list` and `token show` are new.** `token add` requires `--category` and refuses one the tokens CSS does not declare, but nothing reported the categories a project has — so naming one meant hand-parsing a neighbouring `= Category =` banner out of the file. `token list [--category <name>] [--json]` reports each banner with its tokens in file order; `token show <name> [--json]` reports the owning category and the value the token takes in every declaring block (base `:root`, the dark `@media` mirror, each `:root[variant]`) with the line of each. Both read through the parser `token add` and `token coverage` already use — a second tokens-CSS reader would let the report and the writer disagree about which section a token lives in, which is exactly the mistake `token list` exists to prevent. Two shapes are reported rather than dropped, because dropping them would make a real file look like a different one: a declaration above the first banner (listed under `(no category)`) and a banner with no tokens under it (still listed — `token add --category` accepts it). An unknown `--category` is refused by naming the ones that exist, since a filter that printed nothing would read as "this category is empty", which is a different fact.
+- **`--refuse-adjacent-unmanaged` named no anchor — and the report's other half is refuted.** The notice named the offending file and the patch but not WHICH of the patch's owned locations the file sits beside, so an unattended run could not triage a refusal on a patch owning files in several directories. Both the per-patch notice and the run-level refusal now name the anchoring directory and state the rule in one clause. The rest of the report does not survive checking: adjacency is NOT scoped to a shared ancestor. `findAdjacentUnmanagedFiles` has always scanned exactly the immediate directories of the patch's own `filesAffected` — there is nothing to narrow. Verified against the fork that reported it: `905-branding-trademark-artwork.patch` owns files only under `…/test/about/` and `…/test/contextMenu/`, so a file under `…/test/hominis-tiles/` cannot be adjacent to it under the current rule; the notice must have named one of the ~150 patches that DO own files in `hominis-tiles`, and the anchor is precisely what would have made that legible. The belt still catches a peer's file in the SAME directory as an owned file, which is the case it exists for, and the 0.45.0 residual blind spot (a cousin directory no owned file lives in) is unchanged.
+- **The mach resource-monitor shim degraded on every 153.x build, and the reported diagnosis was wrong.** Every build printed `FireForge: host resource monitor degraded (SystemResourceMonitor.record_marker() takes 4 positional arguments but 5 were given)`, which reads as a stale arity in the shim's wrapper. It is not: the wrapper has been `(self, *args, **kwargs)` passthrough all along, so making it "signature-agnostic" would have changed nothing. The real cause is a DESCRIPTOR mismatch. In 153, `SystemResourceMonitor.record_marker` and `record_event` are `@staticmethod`s taking no receiver. `getattr(cls, name)` hands back the underlying plain function; setting that back on the class re-binds it as an ordinary instance method, so an instance-qualified call threads the receiver through as a fifth positional and the original raises — which tripped the shim's own degrade path and disabled resource monitoring for the whole build. The install loop now reads the raw class attribute with `inspect.getattr_static`, wraps a `staticmethod`/`classmethod` without injecting a receiver, and re-applies the descriptor it actually had; those wrappers consult the module-level host-degraded flag, since a static method has no instance to carry one. The degrade path is kept for a genuinely incompatible host. Pinned by a python3 harness that declares a 4-argument `@staticmethod record_marker` exactly as 153.0esr does and asserts both call shapes return the real value with no warning; the pre-fix source reproduces the reported message byte for byte. Deliberately NOT folded together with the recognised `stop_time`/`AttributeError` teardown noise `docs/testing.md` annotates — that is cosmetic upstream shutdown noise after `SUITE_END`, this silently disabled a subsystem for the whole run. Also confirmed rather than assumed: the shim directory that ships is the per-user, uid-suffixed `<tmpdir>/fireforge-mach-resource-shim-<uid>`, created `0700` and `lstat`-verified for ownership and mode before it joins `PYTHONPATH` — not the per-dispatch `mkdtemp` the 0.45.0 entry described and did not ship.
+
+### Integrity
+
+- **Checksum verification failed open.** When Mozilla's `SHA256SUMS` could not be fetched — a 404, a captive portal's HTML, a network error — the tarball was accepted on TLS alone with a warning. That is precisely the condition a network-positioned attacker can arrange, and it defeated the whole "trusted baseline + patches" model: an unverified archive became the git baseline. Unpinned downloads now fail closed with a `ChecksumUnavailableError` (exit 3) naming the three ways out: fix connectivity, pin `firefox.sha256`, or set the new `firefox.allowUnverifiedDownload: true` for a trusted mirror (`fireforge config set` accepts the key). A digest that is fetched but does not match is never accepted, opt-out or not. The checksum request also had no timeout and no retry, unlike the tarball fetch; it now goes through the same `fetchWithRetry` — the same 60 s abort ceiling per attempt and the same three-attempt back-off on 429/5xx and network errors — so an unresponsive checksum host cannot hang the command after the tarball has landed, and one dropped connection on the small checksum request does not fail the verification closed and discard a 600 MB archive that downloaded fine.
+- **Archive preflight let `.git` members through.** `isUnsafeArchivePath` rejected only traversal. An archive carrying `firefox-x/.git/config` or `.git/hooks/*` extracted cleanly, and the subsequent `git init`/commit honoured whatever it configured (`core.hooksPath`, `core.fsmonitor`, hooks). Any member with a `.git` path segment at any depth is now rejected before extraction; `.gitmodules` and `.gitignore` remain legitimate upstream files and pass.
+- **The mach PYTHONPATH shim lived at a fixed shared temp path.** The 0.45.0 entry described the shim as "minted per dispatch with `mkdtemp`"; that design did not ship. What shipped wrote `$TMPDIR/fireforge-mach-resource-shim/sitecustomize.py` with the default mode and no ownership check, so on a shared `/tmp` another local account could pre-create the directory and have its Python run inside every build and test dispatch. The directory is now per-user (uid-suffixed via `process.getuid`, not `os.userInfo()`, which throws for a uid with no passwd entry — containers run as an arbitrary uid would otherwise lose every build and test dispatch; username on Windows), created `0700`, and `lstat`-verified as a real directory owned by the current uid and not group/world-writable before it is placed on `PYTHONPATH`; the ownership and mode checks are skipped on Windows, where the per-user name still applies.
+- **Run logs were written unredacted.** The `.fireforge/logs` tee copied every byte, including the environment dumps mach prints. A conservative per-line pass now masks `KEY=value` where `KEY` matches `TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH` (case-insensitive), including the `--password=…` and `-DAUTH_TOKEN=…` spellings mach and configure echo from their argv, and the credential in `Authorization:` headers — file sink only, terminal untouched, lines split across chunks handled. Bare tokens in URLs, space-separated CLI flag values, or JSON fields still pass through; `docs/run-logs.md` now states exactly what is and is not masked instead of "raw bytes". The tee treats a lone `\r` as a line end (progress-bar repaints never send a newline), caps the held partial line at 1 MiB so a newline-free stream cannot grow memory without bound, and is flushed from the SIGINT/SIGTERM path so a killed run's last line survives.
+
+### Locks
+
+- **A failed owner-record write could let two builds into the critical section.** `withFileLock` created the lock directory and then wrote the PID/token file best-effort. A failed write left an owner-less lock, which stale recovery reaps by age after five minutes regardless of whether the holder is alive. The build lock legitimately holds for hours, so a holder whose record failed to write was reaped mid-build and a second `fireforge build` entered. The write is now fatal: it is re-read and verified, and on any failure the just-created directory is removed and a `GeneralError` ("Could not record ownership of lock …") is raised before the operation runs. A read-back that ERRORS (an on-access scanner briefly holding the file on Windows, a FUSE mount's `EIO`) is retried a few times and then reported with its errno, rather than being mistaken for a record that never landed.
+- **A recycled PID kept a dead lock honoured until the waiter's timeout.** Liveness was `process.kill(pid, 0)`, so a crashed holder's PID reused by a long-lived daemon looked alive. On Linux the owner record now carries the holder's own boot-relative start tick (`start-tick=`, field 22 of `/proc/self/stat`), placed among the metadata lines so pre-existing records and readers stay compatible; a stale probe reads the candidate's tick from `/proc/<pid>/stat` and a different tick is a different process, so the lock is stale. Ticks rather than wall-clock times, deliberately: `btime` moves with every clock step on current kernels, so comparing a recorded acquisition time against a `btime`-derived start would have reaped a LIVE build lock after NTP stepped the clock forward. The record also carries `acquired-at-ms=` for diagnostics only. macOS and Windows keep PID-only liveness deliberately: their only start-time source is a `ps`/`wmic` spawn per poll, not worth the cost. `docs/lifecycle-invariants.md` records both contracts and the suites that pin them.
+
+### Exit codes
+
+- **Commander usage errors exited 1, not the documented 8.** An unknown command, unknown option, or missing argument was terminated by commander itself before any command action — and hence before `withErrorHandling` — ran, so `docs/exit-codes.md` was wrong for the most common refusal, and under `--json` there was no envelope at all. The program now installs `exitOverride()`, inherited by every subcommand, and the entry path maps the resulting `CommanderError` to `INVALID_ARGUMENT` with the standard `{"schemaVersion":1,"error":…,"code":"invalid-argument"}` envelope when `--json` is present. `--help` and `--version` still exit 0 with unchanged output, and so does a command group invoked without a subcommand (`fireforge`, `fireforge tree`, `fireforge source`): that is an informational invocation, not a wrong flag, and it now matches the exit 0 `patch`, `token` and `furnace` already gave through an explicit help action (`tree` and `source` gained the same action, so their help lands on stdout).
+- **`GitNotFoundError` exited 4 while the docs said 7.** It extends `GitError` and inherited `GIT_ERROR`; `MachNotFoundError` and `PythonNotFoundError` override to `MISSING_DEPENDENCY`, and CI routing on 7 for "install the toolchain" missed git. It now carries 7 like its siblings. A new contract test instantiates every concrete `FireForgeError` subclass, asserts its code, and parses the table in `docs/exit-codes.md` in both directions — every class has a row, no row names a class that does not exist. The table was also corrected for several classes it never listed.
+- **Manifest invariant failures rendered as "Unexpected error" plus a stack.** `mutatePatchRowsInManifest` re-checked the raw manifest shape after `validatePatchesManifest` had already accepted it and threw bare `Error`. Those conditions cannot be reached by user input, so they are now `assert()` calls raising `InternalInvariantError`, which the CLI formats as a bug report.
+
+### Patch queue
+
+- **`patch compact` could commit renames the operator never confirmed.** After the prompt, it recomputed the rename plan from the manifest under the patch-directory lock and applied whatever came out; a patch exported concurrently between prompt and lock was renumbered without ever appearing in the confirmed summary, and the history entry recorded the run as consented. Compact now applies the same drift gate as `patch reorder` — the recomputed plan must equal the confirmed one, otherwise it refuses with "Patch queue changed while waiting for confirmation" and nothing is renamed.
+
+### Patch bodies
+
+- **A NEW non-UTF-8 text file was corrupted on export, and every hash-keyed check stayed green.** The synthesized new-file body was built from a UTF-8 decode — every Latin-1 high byte became U+FFFD — while the `index` line's blob hash came from `git hash-object` over the real bytes. The patch applied, wrote different bytes than the tree held, and drift detection flagged the file forever because the recorded hash never matched the body. Text-vs-binary for a new file is now decided in one place: a NUL byte or invalid UTF-8 (strict `TextDecoder`, BOM preserved) sends the file down the binary-patch arm. Because git's own NUL-only heuristic would still render a Latin-1 file as a text diff, the binary arm forces `-diff` through a throwaway `core.attributesFile` so `git diff --binary` emits a byte-faithful `GIT binary patch`. A real-git test exports a Latin-1 file through all three arms, applies it in a fresh clone, and asserts byte- and blob-hash-equality. A TRACKED, MODIFIED non-UTF-8 file still goes through plain `git diff --binary HEAD` and remains subject to the same decode loss; that is a separate change.
+- **Worktree-side renames produced a phantom status entry.** `parsePorcelainStatus` consumed the second NUL record (the original path) only when the INDEX column was `R`/`C`, but git ≥ 2.18 with `status.renames` emits an unstaged rename as ` R new\0old\0`. The `old` record was then parsed as its own entry whose status was its first two path characters. Either column being `R`/`C` now consumes the original path.
+
+### Diagnostics
+
+- **A timed-out command threw away everything it had captured.** `exec()` collected stdout and stderr right up to the deadline and then built `ExecTimeoutError` from only the command and budget, so a `git add -A` killed after ten minutes gave no clue what git had been doing. The error now carries `stdout`, `stderr`, and an `outputTruncated` flag, and its user message shows the last 20 lines.
+- **`exec()` accepted `processGroup` and `mirror` and ignored both.** They lived on the shared `ExecOptions` type although only the streaming and inherit variants read them — the "accepted but silently ignored" trap 0.45.0 already closed for `SmokeRunOptions`. The type is split so `exec()` cannot admit them; typecheck confirmed no caller was passing them.
+- **`fireforge test --help` listed six verdict reasons; the type and `docs/machine-output.md` have seven.** `killed` is now in the epilogue with its meaning, and the help test pins the list against `FireforgeVerdictReason`.
+
+### Tooling
+
+- **`@types/node` was two majors ahead of the supported floor, and nothing tested the floor.** `engines` says `>=22.22.2`, `@types/node` was `^26`, and CI ran only the `.nvmrc` version, so code could typecheck against APIs absent on Node 22. The types are now `^22`, which surfaced only test-side differences (path methods no longer `this: void`, `Dirent.path`), and a separate `node-floor` CI job runs the suite on Node 22, 24, and `.nvmrc` on Ubuntu — a new job rather than a wider matrix, so the ruleset-required check names are unchanged.
+- **Three copy-pasted mach test wrappers collapsed.** `testWithOutput`/`xpcshellTestWithOutput`/`mochitestWithOutput` differed only in the mach subcommand and carried a five-positional-argument signature that forced callers to juggle arity. They are one `runMachTestSuite(kind, options)`; argv and env behaviour are unchanged. `initRepository`/`resumeRepository` likewise shared a duplicated stage-and-commit tail, now one helper; `export-flow` and `patch reorder` carried byte-identical rename-map helpers, now `patch-rename-map.ts`; the dry-run preview and `commitExportedPatch` each open-coded the same eleven-field planner input, now `buildPlanExportInput`, so the two paths cannot drift field by field.
+- **`ReturnType<typeof X>` on local imports is now a lint error.** Fourteen files spelled `ReturnType<typeof getProjectPaths>` while `ProjectPaths` was exported beside the function; the structural spelling hides the contract and drifts silently. Every site now uses a named exported type, and `fireforge/no-return-type-of-import` keeps it that way (package imports such as `ReturnType<typeof spinner>` are exempt). `performRenameMutations` also lost four parameters it re-derived under the lock and never read.
+- **Two lint rules were added for cleanups worth doing only once.** `@typescript-eslint/no-unnecessary-type-conversion` keeps `${String(n)}` out of template literals, which `restrict-template-expressions` has allowed unwrapped since it was configured with `allowNumber` — 204 sites spelled it the long way. `prefer-object-has-own` catches the last `Object.prototype.hasOwnProperty.call(...)`. Both were already satisfied when they landed, so neither carries a backlog.
+- **The shared spawned-CLI test helper settled on `'exit'`.** stdio pipes can still hold the final chunk when a child's `'exit'` fires, so the verdict-line assertions that read the last line of stdout could flake on a loaded runner, and a spawn failure left the promise pending until vitest's timeout. It now settles on `'close'`, rejects on `'error'`, and reports signal deaths as 128 + signal like `exec()` does.
+- **Wall-clock test budgets replaced.** The token-scan linearity test asserted an absolute 200 ms budget and the signal-critical test used `Date.now()` bounds, both flaky on loaded runners for reasons unrelated to the code. The linearity test now asserts time(4N)/time(N) stays well under quadratic after a warm-up; the signal test uses fake timers. fast-check property tests now cover diff-section round-trips (spaces, unicode, git octal quoting, CRLF, renames).
+
+### Dead code
+
+- **Twenty-two exports had no caller outside the test suite, and the dead-code gate could not see them.** `knip` treats every `*.test.ts` as an entry point, so an export that only a test reaches counts as used. Under that rule `generateModificationDiff` (a 64-line tempfile diff helper), four superseded `mach` wrappers, `parseFilename`, `findExistingPatchForFile`, `findSupersededPatches`, `isMarionetteFlavor` (orphaned when its caller was replaced in 0.44.x), `getDownloadUrl`, `getTarballFilename`, `applyPatchToContent`, `tryReadRebaseSession`, `saveState`, `hasReadOnlyGitIndexScope`, `isDefined`, `assertDefined`, `isValidPatchCategory`, the `Arch` type, and the never-thrown `MissingFieldError` / `InvalidFieldError` / `DirtyRepositoryError` all stayed alive on test references alone. They are gone, along with the tests that existed only to exercise them and the barrel re-export lines that had no consumer left. `deadcode:check:production` now resolves only from `src/index.ts` and `bin/fireforge.ts` and is part of `release:check`, so this cannot re-accrete; the handful of deliberate test-only seams (`resetResolvedPython`, `resetBrokenPipeHandlerForTests`, `__resetFurnaceOperationStateForTests`, `DOCTOR_CHECK_ORDER`) are tagged `@internal` and exempt by name rather than by accident.
+- **Dead code cascaded once its first layer was removed.** `isNewFilePatch` was reachable only from `findSupersededPatches`, which was itself reachable only from a test; deleting the outer function exposed the inner one. The production gate catches that second layer, which a one-pass sweep does not.
+- **Three "impossible state" fallbacks were removed rather than documented.** `stageAllFilesChunked`'s caller wrapped it in a `try`/`catch` whose two arms both rethrew the error unchanged; `ParamsReturnsContext.skipParams` gated a branch nothing ever set, so the guard was always true; `FireForgeState.lastBuild` was declared, carried through the state-recovery allowlist, and never written or read. `migrateFurnaceConfig` migrated a version 2 that has never existed — its two real range checks moved into `validateFurnaceConfig` and the migration scaffolding went.
+- **`fireforge import --stop-at` is removed.** It was registered as an alias for `--until` in the same commit that introduced `--until`, so it was never a migration path from an older spelling, and no documentation mentioned it.
+
+### Duplication
+
+- **The same delay was written nine times, and the copies disagreed on the thing that matters.** Five modules had a private `sleep`/`delay`/`sweepDelay` and four more inlined `new Promise((resolve) => setTimeout(resolve, ms))`. Whether the pending timer keeps the event loop alive is load-bearing — an unref'd wait between a group SIGTERM and its SIGKILL escalation lets Node exit mid-grace and skip the escalation — yet that distinction was invisible at each call site. One `sleep(ms, { unref })` in `src/utils/sleep.ts` carries both behaviours and the reason for the default. It is deliberately built on the global `setTimeout` rather than `node:timers/promises`, because vitest's fake timers patch the global but not the promisified module, and every retry and grace-period path is driven by fake timers.
+- **Eight `--order`-style flag parsers disagreed on what a valid integer is.** `parsePositiveIntegerFlag` already existed and rejects `"12abc"`, leading zeros and decimals with a strict pattern; five call sites re-implemented the check with `Number.parseInt`, which accepts `"12abc"` as `12`, and threw three different error classes between them. `patch split`, `patch move-files` and `patch rename` now route `--order` through the shared parser, so a typo is refused instead of silently becoming a different order.
+- **A documented identity function sat on every patch write path.** `normalizePatchArtifact` returned its input unchanged at seven call sites, guarded by a comment warning against reintroducing whitespace trimming — a real past corruption, since Firefox sources contain whitespace-only context lines. Its property tests asserted idempotence and byte-preservation, both vacuously true of `x => x`. The warning is what had value, so it moved to the export write site, and the contract it protects is now pinned where it can actually fail: `git-diff-latin1-roundtrip.test.ts` applies an exported patch in a fresh clone and asserts blob-hash equality.
+- **`await ensureGit()` was written before 32 of the 38 `git()` calls, and was not memoised.** Each call spawned `which git`. It is memoised and called inside `git()`; the six remaining explicit calls are the paths that shell out via `exec('git', …)` without going through the wrapper. `execGitWithAllowedExitCodes` was deleted outright: its `allowedExitCodes` parameter was dead at all eight call sites, and the rest of it duplicated `git()`.
+- **One consolidation per repeated shape.** `sha256Hex` (every inlined one-shot `createHash` chain; the two streaming digests, which must not buffer a 500 MB tarball, stay as they are), `normalizePathSlashes` (twenty-seven open-coded `.replace(/\\/g, '/')`), `formatPatchOrder` (eleven `String(order).padStart(3, '0')`), `appendHistoryBestEffort` (eleven copies of the same try/warn block, whose swallow is deliberate and now explained once), `proceedAfterDecision` (eleven copies of the `confirmDestructive` tail, which also settles the dry-run wording as one string), `clearPendingResolution` (five copies of a transactional spread-and-delete), `deriveTestStem` (five copies of the `moz-` strip that `furnace rename` and `furnace remove` must compute identically to `furnace create` or they leave the old test behind), `manifestIncludes` (five near-identical registration probes), `projectEntryBody`, `loadAuthoringFurnaceConfig`, `remedies`, and a shared `spawnTracked` core under `execStream` / `execInherit` / `execInheritCapture`.
+- **`--dry-run`, `--yes` and `--force-unsafe` were documented four different ways each.** `src/types/commands/options.ts` declared `dryRun` on twenty-four interfaces with five different doc comments. Five mixins (`DryRunnable`, `Confirmable`, `UnsafeOverridable`, `EngineLockWaitable`, `PatchLockWaitable`) now state each contract once. The two wait-lock mixins stay separate on purpose: the flag shares a spelling but bounds the engine session lock in one case and the patch directory lock in the other, and a reader needs to know which.
+
+### Test suite
+
+- **The suite tested barrels, layers and coverage thresholds rather than behaviour.** Eleven test files and roughly 5,600 lines are gone with no behavioural assertion lost. `coverage-gaps.test.ts` and `furnace-registration-ast-coverage.test.ts` announced their purpose in their names; five of the former's six blocks re-tested what `git.test.ts`, `patch-parse-helpers.test.ts` and `patch-lock.test.ts` already covered, and its wire-name block declared its own copy of the regex and tested the copy. `furnace-apply.test.ts` re-ran `furnace-registration-ast.test.ts` through a barrel with mocked filesystem calls; `moz-manifest-register.test.ts` did the same for the `register-*` leaves. `build-artifact-preflight.test.ts` asserted two refusals once per command that every per-command file already asserted. `user-messages.test.ts` snapshotted 36 error strings that `src/errors/__tests__` already pins fragment by fragment. Unique cases were relocated, not dropped.
+- **Help output is snapshotted as an inventory, not as prose.** Twenty-one full-text snapshots totalling 486 lines regenerated on every wording or terminal-width change, so nobody read the diff. One 70-line snapshot now records each command with its sorted flag names: removing `--stop-at` showed up as a single changed line, while rewording a description does not touch it at all.
+- **`process-boundary.test.ts` is replaced by the lint rule that already existed.** Its first test walked `src/` grepping for `process.exit(`, which `no-restricted-properties` enforces with a precise location; its second asserted that `bin/fireforge.ts` contains exactly two `process.exit(` and exactly five `exitAfterStdioFlush(` occurrences, a count that any harmless extraction breaks.
+- **Four tests asserted less than they claimed.** A fast-check property titled "exactly the three valid products" filtered against three literals while `FIREFOX_PRODUCTS` has four, and passed only because `fc.string()` never generated the fourth. A logger test asserted the same call twice under a comment claiming it verified a re-print. `run.test.ts`'s `--console-allow` accumulation test asserted only a call count, and its own comment said so; it now feeds two error lines and fails if either repeat is dropped. Three `furnace-index` tests titled "routes … through the engine session lock" never mentioned the lock.
+- **The type-level guards are type-level now.** A 40-line hand-written exhaustive `switch` in `validation.test.ts` conceded in its own comment that its runtime assertions named nothing; it is a `satisfies` operand beside `FIREFOX_PRODUCTS` that fails compilation in both directions, verified by adding a member and watching `tsc` reject it.
+
 ## 0.45.0
 
 ### Patch bodies

package/dist/bin/fireforge.js

@@ -11,6 +11,7 @@ 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';
@@ -102,6 +103,11 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // 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);
         });

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.45.0",
-  "commit": "19d461eb43b89962970510f9a2e655704e9fb952",
-  "shortCommit": "19d461eb43b8",
+  "version": "0.46.0",
+  "commit": "cffe7e47008c7a2af690abbbe352eb685d35d3f8",
+  "shortCommit": "cffe7e47008c",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-09-01T10:47:47.465Z"
+  "buildTime": "2026-09-05T19:28:43.539Z"
 }

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, not 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` additionally
+ * 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, not 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` additionally
+ * 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,7 +6,11 @@ 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; not part of the public surface.
+ */
 export declare function resetBrokenPipeHandlerForTests(): void;
 /**
  * Gets the project root directory.

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,22 +33,6 @@ 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`.
  *
@@ -93,7 +78,11 @@ 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; not part of the public surface.
+ */
 export function resetBrokenPipeHandlerForTests() {
     const state = getProcessState();
     const handleStreamError = state[brokenPipeListenerKey];
@@ -150,8 +139,8 @@ export function withErrorHandling(handler) {
         // 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 {
@@ -191,7 +180,7 @@ export function withErrorHandling(handler) {
                 // Not when a payload already owns stdout: `status --json --fail-on`
                 // 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);
@@ -339,6 +328,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.')
@@ -388,5 +382,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.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.',
@@ -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:');

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';
@@ -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';
@@ -334,7 +332,9 @@ async function runBuildCommandBody(projectRoot, options) {
     // 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}`);
@@ -353,7 +353,16 @@ async function runBuildCommandBody(projectRoot, options) {
  */
 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}`);

package/dist/src/commands/destructive-decision.d.ts

@@ -0,0 +1,19 @@
+import type { DestructiveOpResult } from '../core/destructive.js';
+/**
+ * Closes out a {@link DestructiveOpResult} and says whether to run the
+ * mutation.
+ *
+ * Eleven commands had copied the same tail: `if (decision === 'dry-run') {
+ * outro(…); return; } if (decision === 'declined') { outro(…); return; }`.
+ * The dry-run wording is a user-facing contract that must not drift between
+ * commands, so it lives here; the declined wording is per-command and stays a
+ * parameter.
+ *
+ * `confirmDestructive` never mutates on its own, so a caller that forgets this
+ * check silently performs a "dry run" for real — hence a boolean return the
+ * caller must act on rather than a helper that returns void.
+ * @param decision - The result from `confirmDestructive`.
+ * @param declinedOutro - Outro to print when the operator answered "no".
+ * @returns True when the caller should proceed with the mutation.
+ */
+export declare function proceedAfterDecision(decision: DestructiveOpResult, declinedOutro: string): boolean;

package/dist/src/commands/destructive-decision.js

@@ -0,0 +1,31 @@
+import { outro } from '../utils/logger.js';
+/** The dry-run outro every command prints, spelled once. */
+const DRY_RUN_OUTRO = 'Dry run complete — no changes made';
+/**
+ * Closes out a {@link DestructiveOpResult} and says whether to run the
+ * mutation.
+ *
+ * Eleven commands had copied the same tail: `if (decision === 'dry-run') {
+ * outro(…); return; } if (decision === 'declined') { outro(…); return; }`.
+ * The dry-run wording is a user-facing contract that must not drift between
+ * commands, so it lives here; the declined wording is per-command and stays a
+ * parameter.
+ *
+ * `confirmDestructive` never mutates on its own, so a caller that forgets this
+ * check silently performs a "dry run" for real — hence a boolean return the
+ * caller must act on rather than a helper that returns void.
+ * @param decision - The result from `confirmDestructive`.
+ * @param declinedOutro - Outro to print when the operator answered "no".
+ * @returns True when the caller should proceed with the mutation.
+ */
+export function proceedAfterDecision(decision, declinedOutro) {
+    if (decision === 'dry-run') {
+        outro(DRY_RUN_OUTRO);
+        return false;
+    }
+    if (decision === 'declined') {
+        outro(declinedOutro);
+        return false;
+    }
+    return true;
+}

package/dist/src/commands/doctor-check-core.d.ts

@@ -96,12 +96,6 @@ export interface DoctorCheckDefinition {
      */
     fix?: string;
 }
-/**
- * Resolves a {@link DoctorCheck} to its effective severity. `severity` is the
- * single source of truth; this exists so every consumer of a
- * `DoctorCheck[]` reads it the same way.
- */
-export declare function resolveDoctorSeverity(check: DoctorCheck): 'ok' | 'warning' | 'error';
 /**
  * Builds a DoctorCheck object representing a successful "OK" check.
  */

package/dist/src/commands/doctor-check-core.js

@@ -4,14 +4,6 @@
  * `doctor.ts` and sibling check modules. Kept separate so registries can import
  * these symbols without creating cycles through `doctor.ts`.
  */
-/**
- * Resolves a {@link DoctorCheck} to its effective severity. `severity` is the
- * single source of truth; this exists so every consumer of a
- * `DoctorCheck[]` reads it the same way.
- */
-export function resolveDoctorSeverity(check) {
-    return check.severity;
-}
 /**
  * Builds a DoctorCheck object representing a successful "OK" check.
  */

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

@@ -27,12 +27,6 @@ export interface OrphanedHarnessWorker {
     cpuSeconds: number;
     command: string;
 }
-/**
- * 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;
 /**
  * Scans `ps -axo pid=,ppid=,time=,command=` output for orphaned harness
  * workers: PPID 1 (reparented to init/launchd), a multiprocessing

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

@@ -29,14 +29,6 @@ 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
@@ -57,7 +49,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 +60,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,10 +78,10 @@ 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). ` +