@hominis/fireforge 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.36.0
+
+- **Review-findings remediation for the 0.36.0 release gate**: `fireforge test` no longer has a pathless dead-end — no-path runs now require `--auto`, `--doctor`, or `--canary`, `--auto` forwards mach's own selection mode, stale packaged-engine drift fails fast unless `--build` or `--allow-stale-build` is used, `--kill-stale-marionette` can terminate a recognized stale browser listener, and `--canary [path]` / `test.canaryPath` provides a short green/hang/crash harness probe. Harness verdicts now let real failure lines (`FAIL`, `TEST-UNEXPECTED-*`, nonzero unexpected summaries, assertions) beat resource-monitor traceback classification, while still noting the traceback as secondary noise. Patch naming is normalized consistently for `export --name` and `patch rename --to` (bare, category-prefixed, and full stems converge), and `lint --per-patch --patches` accepts repeated flags, comma lists, filenames, stems, manifest names, category-prefixed slugs, and bare slugs. Furnace-managed jsconfig edits are JSONC-preserving via `jsonc-parser`, the Firefox globals shim now includes JSWindowActor bases and `ChromeUtils.registerWindowActor`, `doctor` can validate opt-in `externalToolchains`, and CLI engine-mutating commands take a `.fireforge/engine-session.lock` plus test-run tree-generation checks to catch concurrent engine mutation.
+- **Fixed a SIGSEGV-truncated test run being reported as PASSED** (corrects the green-summary override shipped in 0.34.0 and still present in 0.35.0): an 8-file browser-chrome run whose parent process crashed at the second file's `TEST_START` (`Main app process: killed by SIGSEGV`) left an embedded summary that read `Passed: 2 / Failed: 0 / Unexpected results: 0` — green only because the crash prevented the other six files from producing any results — and FireForge overrode the mach exit 1 as "non-fatal harness noise", masking a real regression through an entire source-refresh drill while the operator recorded "full matrix green". The override now runs two vetoes first: a crash-marker scan over the RAW output (`Main app process: killed by SIG*` for any signal, `PROCESS-CRASH`, and the mozcrash minidump-processing headers — these also disqualify the summary from vetoing crash-signature classification), and a completeness cross-check that every requested test file produced a `TEST_START`/`TEST_END` (or `TEST-START`/`TEST-OK`) pair, paired positionally because the xpcshell dialect's `TEST_END` lines do not name the file. Either signal fails the run with a dedicated message naming the crash evidence line and the never-started / started-but-never-finished files, in both single and sharded runs. The lenient path survives only when neither signal fires — the resource-monitor/telemetry noise it was built for (green summary, all files paired, monitor traceback owning the exit code) still passes with the override note, and mach exit 0 classification is untouched. Fixture tests pin all four shapes, with the crash lines verbatim from the field log.
+- **Fixed the build toolchain preflight probing a different cbindgen than mach resolves** (corrects 0.35.0): the preflight compared the tree's declared minimum against env-override-or-PATH only, but mach's configure tries the mozbuild state directory FIRST (`~/.mozbuild/cbindgen/cbindgen`, where `fireforge bootstrap` installs; its configure log shows that candidate probed ahead of PATH) — so a host with a current bootstrap-installed 0.29.4 behind a stale `~/.cargo/bin` 0.29.1 was blocked from a build that succeeds (field workaround was `CBINDGEN=… fireforge build`). The probe now enumerates configure's own candidate order — env override (which, when set, is the ONLY candidate: the override wins even over a newer state-dir copy, matching configure), then `$MOZBUILD_STATE_PATH`/`~/.mozbuild` locations, then PATH — and fails only when at least one candidate resolved and NONE meets the minimum, listing every probed candidate in the error; no resolvable candidate still skips silently (fail-soft unchanged). Tests pin all four resolution shapes.
+- **Fixed exact-directory test selection being cosmetic — and its exclusion echo being wrong** (corrects 0.35.0): the trailing-`/` normalization does not defeat mochitest's prefix matching on Firefox 153's mach — in the verifying run all 33 `hominis-tiles` sibling files executed anyway, while the new echo gave the operator positive reason to believe they were excluded. A directory argument now dispatches as its enumerated explicit test-file list (a file list cannot prefix-match a sibling), still in ONE mach invocation so the one-browser-instance semantics of a directory run are preserved (cross-file state carries within the directory; sharding of multi-argument runs is per argument, keeping a directory's files together). The echo now describes the real mechanism, and the rare zero-enumerable-files fallback (raw directory form passed through) explicitly warns that prefix matching may still widen the scope instead of claiming exclusion. `test --help` and the README describe the new mechanism; tests pin the explicit-file-list dispatch, the single-invocation directory run, and the per-argument sharding of a directory + file mix.
+- **Extended the verbatim upstream MPL-2.0 block header acceptance to non-JS block-comment files** (0.35.0 residual — its fix covered new JS files only, per its own "non-JS styles are unchanged"): a derived CSS file carrying the exact same three-line `/* … */` MPL block header still errored `missing-license-header` on an EUPL project without a patch-level lintIgnore, while the derived JS on the same patch passed natively. The carve-out now keys on the comment syntax, accepting the upstream block form (optionally behind a leading editor-directive comment) on JS and CSS; hash-style files (FTL) stay excluded because `/* … */` is not a comment there, and the `// `-style FireForge-generated MPL header still requires the project's own header on non-MPL projects. The acceptance predicate is now a single shared function (`isAcceptableNewFileHeader`) used by both the lint rule and export's interactive header auto-fix, which previously would have offered to stack a second header onto a file the lint already accepts. Lint tests cover accept/reject for CSS and the FTL exclusion.
+- **Fixed the rebase drift-tolerance feature being dead code**: `git apply` has no `--fuzz` flag (that is GNU `patch(1)` syntax), so every escalation level failed with a swallowed usage error and any patch needing context drift was reported as a hard conflict with `.rej` residue — `--max-fuzz` had no effect at all. Reimplemented with git's real knob, `-C<n>` reduced-context matching (exact, then `-C2`/`-C1`/`-C0`, capped at git's default context of 3); `.rej` extraction now parses git's actual `Applying patch <file> with N rejects...` phrasing (the old regex targeted GNU patch output and never matched, so the conflict summary's ".rej files created" hint never fired). The fuzz unit tests were exec-mocked and validated behavior real git cannot produce — they now run against a **real git binary**, and a rebase integration test pins end-to-end drift absorption. User-facing wording now says "context reduction (fuzz-like)"; the `--max-fuzz` flag name is unchanged.
+- Fixed `rebase --max-fuzz` **accepting invalid numbers**: the flag was wired to raw `parseInt`, so `--max-fuzz foo` became `NaN`, `--max-fuzz -1` stayed negative, and `--max-fuzz 1.5` silently truncated to 1. With `NaN` or a negative value the escalation loop in `applyPatchWithFuzz` (`for (fuzz = 0; fuzz <= maxFuzz; …)`) never ran a single iteration — the patch skipped even the exact-match attempt and fell straight through to `git apply --reject`, spraying `.rej` files for patches that would have applied cleanly. The flag now uses the same strict `parsePositiveIntegerFlag` parser as `export --order` and `patch reorder --to`, failing fast at parse time, and `applyPatchWithFuzz` itself rejects a non-integer or negative `maxFuzz` as defense in depth (0 = "exact only" stays legal at the core layer). CLI-parse tests pin `foo`/`-1`/`0`/`1.5`/`01` rejection plus a valid value flowing through; core tests pin the guard.
+- **Fixed a corrupt `patches.json` being silently destroyed on the next export**: `loadPatchesManifest` returned null for "missing" AND "unparseable", so `addPatchToManifest` rebuilt an empty manifest over a hand-edit typo (losing every patch's tiers/descriptions/lintIgnore/staged dependencies) and a failing export's rollback then deleted `patches.json` because the "before" state looked absent. Every mutating path now loads through `loadPatchesManifestForWrite`, which throws a typed `PatchManifestCorruptError` naming the parse error and the repair steps.
+- **Fixed `furnace apply <name>` wiping every other component's checksum state**: named apply ran the batch persist path, whose wholesale `appliedChecksums` replace kept only the named component (deploy documented and avoided this exact trap). Orphan detection and deleted-file undeploy key on that state, so the wiped components' stale engine files became invisible to apply and `furnace validate`. Named apply now mirrors deploy: `persistState: false` plus a per-component merge, both hoisted into `core/furnace-state-persist.ts` as the single owner of state-persistence policy.
+- **Fixed ordinary `config <key> <value>` deleting `--force`-written keys**: the non-force branch round-tripped through `validateConfig`, whose typed clone contains only known schema fields. Both branches now mutate the raw document (validation strength unchanged — the result is still strictly validated for known keys), and the catch only labels genuine validation failures as "Invalid value" — lock timeouts and I/O errors keep their own types instead of misdirecting diagnosis.
+- **Downloads verify against Mozilla's published SHA256SUMS by default**, failing closed on mismatch (artifact deleted) and warning loudly when the checksum file is unavailable; an explicit `firefox.sha256` still takes precedence and always fails closed. TLS-only trust was thin for the artifact that becomes the git baseline every patch builds on.
+- **Closed the silent-degradation class**: the archive-safety preflight streams tar listings line-by-line instead of scanning a silently-truncated 50 MB capture (a padded archive could hide traversal entries past the cap); `export`/`export-all --dry-run` are genuinely read-only (the license-header auto-fix no longer prompts-and-writes into `engine/` mid-"preview"); `furnace sync` refuses to apply while workspace files carry unresolved merge conflict markers or overrides still have baseVersion drift (it used to copy conflict markers into the engine right after warning about them); `bootstrap` propagates error-severity post-check results instead of exiting 0; furnace post-apply consistency failures now trigger rollback (the gate read a pre-check snapshot of step errors); and `.ftl` degradation is a real advisory tier (`StepError.advisory`) instead of a documented-but-false promise — a fork without a locale jar.mn can ship a working component again.
+- **Hardened `applyPatchIdempotent` recovery**: git exit codes checked (a failed restore no longer surfaces as a confusing "already exists" later), pathspecs chunked against `E2BIG`, patch-created leftovers deleted explicitly, and a `protectedFiles` set threaded from both apply loops so an `--allow-overlap` queue's later patch no longer resets shared files a previous patch just modified. Relatedly, rebase re-export skips patches whose files another patch also claims (the cumulative per-file diff used to duplicate shared hunks into every owner, corrupting the queue for the next import) and excludes them from version stamping with a manual-re-export warning.
+- **File locks are race-hardened**: ownership is PID + per-acquisition token, stale reaping is rename-aside (exactly one reaper can win; the live path is never `rm`'d, and a lock re-acquired mid-probe is restored), the stale probe re-runs every ~5 s while waiting (a build-lock holder dying mid-wait no longer stranded waiters for up to 24 h), and release verifies the lock still belongs to this acquisition. The download lock waits up to 30 min with honest messaging instead of failing after 30 s with "remove the lock" advice while a legitimate download was mid-extraction.
+- **Signals**: the bin handler now waits (bounded, 12 s) for spawned children after forwarding SIGINT/SIGTERM, making `execInherit`'s SIGTERM → grace → SIGKILL escalation actually reachable — a hung Firefox is no longer orphaned by Ctrl+C, and a healthy one keeps its AsyncShutdown flush window. `execSmokeRun` forwards parent signals to its detached process group (second signal = group SIGKILL).
+- Fixed Windows smoke-run cleanup **killing only the direct child**: `execSmokeRun` signals the whole POSIX process group on timeout, but the Windows fallback was a bare `child.kill()` — for a `mach → python → firefox → content processes` chain that leaves the Firefox tree running after the smoke deadline. The fallback now runs `taskkill /pid <pid> /T /F` to kill the descendant tree (always forced — Windows has no graceful-signal analogue, so the POSIX SIGTERM→SIGKILL grace window does not exist there), keeping `child.kill()` as a last resort if taskkill is unavailable. The docstring's claim that a best-effort warning was logged on Windows (it never was) is gone, and the README's Windows caveat now names the taskkill strategy as best-effort/untested. A regression test pins that the win32 timeout path spawns `taskkill /T /F` instead of signalling `-pid`.
+- **Windows atomic-write and test-suite correctness** (from the first Windows-runner failure of the cross-platform CI subset): `writeFileAtomic` now retries its final rename on transient `EPERM`/`EACCES`/`EBUSY` — Windows fails a rename onto a target another writer is concurrently replacing (or that an antivirus/indexer briefly holds open), so concurrent atomic writes to the same path spuriously errored where POSIX succeeded; bounded retries with backoff make them reliable there too. Four test-suite fixes make the Windows subset honest: the POSIX process-group kill test pins a non-Windows `process.platform` (the win32 `taskkill` branch has its own test), the git-diff mocks key their `stat`/`hashObjectBatch` lookups on `path.join`-built paths instead of hard-coded forward-slash strings (they missed the backslash paths the source computes on Windows, silently exercising the wrong branch), and the file-mode preservation test is skipped on win32, where no execute bit exists for chmod to preserve.
+- **Machine output**: `status --json`/`--raw` own stdout exclusively — every diagnostic (clack warnings, styled errors, spinner steps, banners) routes to stderr as plain text, so `status --json | jq .` parses even when warnings fire. Truncated untracked directories are reported once, not twice.
+- **Encoding and platform correctness**: all captured/streamed child output decodes through `StringDecoder` (multibyte characters split across pipe chunks no longer corrupt smoke-run allowlist matching or mach error hints); patch parsing is CRLF-tolerant via the new single shared diff walker (`parseDiffSections` — quoted/octal-escaped `diff --git` paths, ` b/`-in-path headers, binary-section detection, one implementation instead of six drifting walkers); `exec` timeouts reject with a typed `ExecTimeoutError` naming the command and budget instead of a bare `AbortError`.
+- **CLI polish**: `--version`/`-V` works alongside other root flags (handled pre-parse; a commander root `.version()` would hijack `source set --version`); option argParsers surface through commander's invalid-argument channel via the `commanderArgParser` wrapper (`run --smoke-exit abc` prints one clean line instead of a fatal dump); `import --until <ordinal>` resolves ordinals with the same matcher as the apply loop (in-range integrity issues can no longer be silently dropped while the loop applies anyway); prompt cancellation exits 130 (`ExitCode.USER_CANCELLED`); a bare `lint cache` explains the cache-vs-path ambiguity.
+- **Furnace authoring safety**: `furnace remove` deletes only the files the component deployed (never `removeDir` of a possibly-shared targetPath; empty dirs pruned; furnace.json warns when two components share a targetPath), and `furnace rename` journals the new-name side (workspace dir + files, test scaffolds, FTL destination) plus furnace-state.json before re-keying, so failed or interrupted renames roll back completely.
+- **Patch-core precision**: `normalizePatchArtifact` is the identity chokepoint (whitespace-only payload lines are preserved byte-for-byte — the old trimming made freshly exported patches fail `git apply --check` and silently changed `+` line content; the worktree whitespace check already excludes `patches/*.patch`); zero-old-count insertion hunks splice after line N per unified-diff convention; the LCS-fallback coalesced hunk emits correct `@@` lengths; auto-resolved new-file originals survive the whole run so a later failure's rollback can restore them; empty new files extract as zero bytes; binary new-file sections refuse auto-resolve instead of writing base85 as text.
+- **Performance**: `validatePatchIntegrity` batches HEAD-existence checks through one chunked `ls-tree` (one spawn instead of one per patch × file), and import's dirty-file classification loads the manifest/patch set once with bounded concurrency instead of O(files × patches) IO.
+- **Structure**: `escapeRegex` (6 copies), `getPrimaryStatusCode` (2), the untracked-directory expander (2 — the shared one now carries the 5000-per-dir cap, and `reset`/`discard` gained status's unborn-HEAD guidance), the pendingRepair-preserving state reset (4 copies → `clearAppliedFurnaceState`), and the cross-patch claim multimap (3 copies → `buildPatchClaims`) are each single implementations; the second patch-delete implementation (`deletePatch`) is gone in favor of `removePatchFileAndManifest`; the furnace batch-apply loops take an `ApplyBatchContext` instead of 12–13 positional parameters; `stripJsComments` tokenizes with acorn so regex literals survive (legacy regex fallback for preprocessor-laden chrome sources).
+- **Follow-up findings** (same review, second pass): `doctor --repair-patches-manifest` now rebuilds `patches.json` **under the patch-directory lock** — the repair used to write the manifest lock-free, so it could race a concurrent export/reorder and clobber the other writer (a lock-wait regression test pins the serialization, alongside the existing `stampPatchVersions` pin). `patch tier` and `patch lint-ignore` now follow the full destructive-operation contract via `confirmDestructive` (summary, `--dry-run`, confirmation or `--yes`, non-TTY refusal with `--yes` guidance) — both accepted `--yes` without ever prompting, so the flag only appeared in the history record; suppressing lint findings in particular is a mutation an operator should consciously approve. The root `--version` edge case flagged in the same pass (`fireforge --verbose --version` failing on the argv-length-3 fast path) was already fixed above; two CLI tests now pin both the multi-flag form and the non-hijacking of `source set --version`.
+- **Infrastructure**: all GitHub Actions are SHA-pinned (release workflow included); `coverage.include: ['src/**']` closes the Vitest 4 hole where never-imported modules were invisible to thresholds (with new per-module pins for the fuzz/state-persist/step-error modules); the ~2-minute pack smoke test runs once via `pack:verify` (own config) instead of in every `npm test` and twice per release:check; CI has concurrency groups and a stable `quality (ubuntu)` job name that `setup-rulesets.sh` now matches (the Node version embedded in the name silently invalidated the required check on every bump); the full-integration runner's masked-build-failure detection works (its `ls obj-*` glob never expanded under spawn); the coverage-pin matcher requires a path-separator boundary; husky hooks only prepend Homebrew paths that exist; `docs/*.md` and `knip.json` are formatted; `isolatedModules` + `verbatimModuleSyntax` are on (zero fallout); the published tarball no longer ships dangling `sourceMappingURL` comments (build emits no maps); machine-mode logging and the lock races have dedicated unit suites; `docs/lifecycle-invariants.md` records the new lock-ownership, manifest-corruption, and state-persistence invariants with their enforcing tests.
+
 ## 0.35.0
 
 - Fixed the **patch symlink-escape guard being dead code**: the check meant to reject patches targeting a symlink that points outside `engine/` normalized the path text with `resolve()` but never followed the link, so it could not reject anything (the path had already passed the relative-containment check). Target validation now resolves the physical write destination with `realpath` — covering the direct symlink, a _dangling_ symlink (whose destination a write would still create), and a symlinked parent directory — and compares it against the real engine root. Regression tests pin all three escape shapes plus the two accept shapes (inside-tree link, plain new file).

package/README.md

@@ -23,7 +23,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 - Node.js 22.22.1+
 - Python 3
 - Git
-- The normal Firefox platform build tools: Xcode command line tools on macOS, `build-essential`-style packages on Linux, Visual Studio Build Tools on Windows (never tested on Windows tbh)
+- The normal Firefox platform build tools: Xcode command line tools on macOS, `build-essential`-style packages on Linux, Visual Studio Build Tools on Windows (never tested on Windows tbh — smoke-run process cleanup there uses `taskkill /T /F` and is best-effort)
 - Watchman, if you want `fireforge watch` (optional)
 
 ## Getting Started
@@ -88,14 +88,39 @@ Queue maintenance lives under `fireforge patch`: `patch compact` closes ordinal
 new one as a single transaction — including staged-dependency owner rewrites — with
 `--dry-run` support.
 
-`fireforge test <directory>` runs exactly that directory: the argument is normalized with a
-trailing `/` so mach's prefix-based path matching cannot silently sweep in sibling
-directories sharing the name prefix (excluded siblings are echoed with their test-file
-counts). Multiple test paths run as sequential per-file shards by default — announced with
-a notice, since isolated instances do not exercise cross-file state (`--no-shard` restores
-one combined invocation). Recognized harness crashes retry up to `--harness-retries <n>`
-times (default 2), and `--perf-samples <path>` publishes a perf-sample artifact path to the
-harness (exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
+`fireforge test <directory>` runs exactly that directory: FireForge enumerates the
+directory's test files and passes the explicit file list to mach in one invocation, so
+mach's prefix-based path matching cannot silently sweep in sibling directories sharing the
+name prefix (excluded siblings are echoed with their test-file counts). Multiple path
+arguments run as sequential shards by default — one browser instance per argument, with a
+directory argument keeping its files together — announced with a notice, since isolated
+instances do not exercise cross-argument state (`--no-shard` restores one combined
+invocation). Recognized harness crashes retry up to `--harness-retries <n>` times (default
+2), and `--perf-samples <path>` publishes a perf-sample artifact path to the harness
+(exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
+Pathless test runs must choose a mode: `--auto` forwards mach's own auto-selection,
+`--doctor` runs the Marionette preflight only, and `--canary [path]` runs one short
+browser-chrome canary (`test.canaryPath` / `test.canaryTimeoutSeconds` in `fireforge.json`
+provide defaults). When packageable engine files changed since the last successful
+FireForge build, `test` fails before launching stale artifacts; use `--build` to refresh
+or `--allow-stale-build` only for intentional out-of-band rebuilds. If an interrupted
+browser holds the Marionette port, `--kill-stale-marionette` terminates recognized browser
+holders and still refuses unrelated listeners. In dev builds, files under `obj-*/dist/bin`
+may be symlinks back into the source tree (notably prefs), so edit source prefs directly
+and keep a backup before bisection experiments.
+
+Patch names are normalized on export/rename: `window-chrome-tests`,
+`ui-window-chrome-tests`, and `235-ui-window-chrome-tests` all resolve to the same
+`<order>-ui-window-chrome-tests.patch` shape. For focused queue checks,
+`lint --per-patch --patches` accepts repeated flags, comma lists, full filenames/stems,
+manifest names, category-prefixed slugs, and bare slugs.
+
+Projects with generated asset prerequisites can declare opt-in `externalToolchains` in
+`fireforge.json`; `fireforge doctor` reports missing required tools as errors and missing
+optional tools as warnings. Seasonal branding on macOS, for example, can declare Apple's
+Icon Composer tool at
+`/Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool`,
+plus `actool` via `xcrun`, `sips`, and `iconutil`.
 Design tokens are managed with `fireforge token add`; pass `--create-category` to declare a
 new category banner and insert the token in one step.
 

package/dist/bin/fireforge.js

@@ -16,6 +16,7 @@ import { installBrokenPipeHandler, main } from '../src/cli.js';
 import { forceReleaseFurnaceLocksForActiveOperations, isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
 import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
 import { CommandError } from '../src/errors/base.js';
+import { waitForActiveChildShutdown } from '../src/utils/process.js';
 /**
  * Upper bound (ms) the signal handler will wait for any in-flight critical
  * section (e.g. rebase apply + session persist) to finish before calling
@@ -23,6 +24,16 @@ import { CommandError } from '../src/errors/base.js';
  * postpone the exit a user requested with Ctrl+C.
  */
 const SIGNAL_CRITICAL_SECTION_TIMEOUT_MS = 5_000;
+/**
+ * Upper bound (ms) the signal handler waits for spawned children (Firefox
+ * 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 actually complete — exiting earlier is what used
+ * to orphan hung Firefox trees. A second Ctrl+C escalates to SIGKILL
+ * immediately, so an impatient operator is never stuck waiting.
+ */
+const CHILD_SHUTDOWN_TIMEOUT_MS = 12_000;
 installBrokenPipeHandler();
 process.on('unhandledRejection', (reason) => {
     console.error('Fatal error (unhandled rejection):', reason instanceof Error ? reason.message : reason);
@@ -45,16 +56,21 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // rather than queueing another rollback that will race the first.
             process.exit(exitCode);
         }
-        // Run furnace rollback and signal-critical-section drain in parallel.
-        // Rebase-style operations register critical sections (apply + session
-        // persist) via `runInSignalCriticalSection`; awaiting them here ensures
-        // the CLI never exits with a patch applied to the engine but a stale
-        // session file that would mis-track progress on `--continue`.
+        // Run furnace rollback, signal-critical-section drain, and child
+        // shutdown in parallel. Rebase-style operations register critical
+        // sections (apply + session persist) via `runInSignalCriticalSection`;
+        // awaiting them here ensures the CLI never exits with a patch applied
+        // to the engine but a stale session file that would mis-track progress
+        // on `--continue`. Waiting on child shutdown keeps the parent alive
+        // through the SIGTERM → grace → SIGKILL escalation that
+        // execInherit/execSmokeRun forward to Firefox/mach — exiting before it
+        // ran is what used to orphan hung child trees.
         void Promise.allSettled([
             rollbackActiveOperationsForSignal(signal).catch((error) => {
                 console.error(`Furnace rollback after ${signal} failed:`, error instanceof Error ? error.message : error);
             }),
             waitForActiveCriticalSections(SIGNAL_CRITICAL_SECTION_TIMEOUT_MS),
+            waitForActiveChildShutdown(CHILD_SHUTDOWN_TIMEOUT_MS),
         ])
             // Force-release the furnace lock directory after rollback completes.
             // `withFileLock`'s `finally { rm }` never runs when we `process.exit`
@@ -79,4 +95,3 @@ main().catch((error) => {
     console.error('Fatal error:', error);
     process.exit(1);
 });
-//# sourceMappingURL=fireforge.js.map

package/dist/src/cli.js

@@ -58,8 +58,9 @@ export function resetBrokenPipeHandlerForTests() {
 }
 /**
  * Maximum number of directory levels to walk when searching for
- * `fireforge.json`. Guards against symlink cycles and pathologically
- * deep trees.
+ * `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.
  */
 const MAX_PROJECT_ROOT_WALK_DEPTH = 50;
 /**
@@ -100,7 +101,10 @@ export function withErrorHandling(handler) {
         catch (error) {
             if (error instanceof CancellationError) {
                 cancel('Operation cancelled');
-                throw new CommandError(ExitCode.GENERAL_ERROR);
+                // 130 (128+SIGINT) is the conventional "user interrupted" code —
+                // scripts/CI can distinguish a deliberate prompt cancellation from
+                // a real failure (which exits 1).
+                throw new CommandError(ExitCode.USER_CANCELLED);
             }
             if (error instanceof FireForgeError) {
                 logError(error.userMessage);
@@ -154,6 +158,11 @@ function buildGroupedHelpFormatter(manifest) {
             const desc = helper.optionDescription(opt);
             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
+        // argv under commander's default parsing, breaking subcommand flags
+        // 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) {
             output.push('Options:');
@@ -256,11 +265,19 @@ export function createProgram() {
  * Main CLI entry point.
  */
 export async function main() {
-    if (process.argv.length === 3 && (process.argv[2] === '--version' || process.argv[2] === '-V')) {
+    // 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.
+    const userArgs = process.argv.slice(2);
+    const hasSubcommand = userArgs.some((arg) => !arg.startsWith('-'));
+    if (!hasSubcommand && userArgs.some((arg) => arg === '--version' || arg === '-V')) {
         process.stdout.write(`${getPackageVersion()}\n`);
         return;
     }
     const program = createProgram();
     await program.parseAsync(process.argv);
 }
-//# sourceMappingURL=cli.js.map

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

@@ -63,4 +63,3 @@ export async function runPostBootstrapChecks(issues) {
     }
     return checks;
 }
-//# sourceMappingURL=bootstrap-checks.js.map

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

@@ -1,9 +1,10 @@
 import { Command } from 'commander';
+import { ExitCode } from '../errors/codes.js';
 import type { CommandContext } from '../types/cli.js';
 /**
  * Runs the bootstrap command.
  * @param projectRoot - Root directory of the project
  */
-export declare function bootstrapCommand(projectRoot: string): Promise<void>;
+export declare function bootstrapCommand(projectRoot: string): Promise<ExitCode>;
 /** Registers the bootstrap command on the CLI program. */
 export declare function registerBootstrap(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/bootstrap.js

@@ -1,8 +1,11 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { Command } from 'commander';
 import { getProjectPaths } from '../core/config.js';
 import { ensureOriginRemote } from '../core/git.js';
 import { bootstrapWithOutput } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { BootstrapError } from '../errors/build.js';
+import { ExitCode } from '../errors/codes.js';
 import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, warn } from '../utils/logger.js';
 import { detectBootstrapIssues, runPostBootstrapChecks } from './bootstrap-checks.js';
@@ -72,16 +75,20 @@ export async function bootstrapCommand(projectRoot) {
         else {
             warn('Bootstrap completed with warnings:');
         }
-        reportDoctorResults(checks);
+        const checksExitCode = reportDoctorResults(checks);
         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
+            // build that could not succeed because error-severity check results
+            // were discarded here.
+            return checksExitCode;
         }
-        else {
-            outro('Build dependencies installed with warnings');
-        }
-        return;
+        outro('Build dependencies installed with warnings');
+        return ExitCode.SUCCESS;
     }
     outro('Build dependencies installed successfully!');
+    return ExitCode.SUCCESS;
 }
 /** Registers the bootstrap command on the CLI program. */
 export function registerBootstrap(program, { getProjectRoot, withErrorHandling }) {
@@ -89,7 +96,9 @@ export function registerBootstrap(program, { getProjectRoot, withErrorHandling }
         .command('bootstrap')
         .description('Install Firefox build dependencies')
         .action(withErrorHandling(async () => {
-        await bootstrapCommand(getProjectRoot());
+        const exitCode = await bootstrapCommand(getProjectRoot());
+        if (exitCode !== ExitCode.SUCCESS) {
+            process.exitCode = exitCode;
+        }
     }));
 }
-//# sourceMappingURL=bootstrap.js.map

package/dist/src/commands/build.js

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
+import { Command, InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
 import { validateBrandOverride } from '../core/brand-validation.js';
 import { auditBuildArtifacts } from '../core/build-audit.js';
 import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, runMach, withBuildLock, } from '../core/mach.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { formatToolchainMismatchMessage, runToolchainPreflight, } from '../core/toolchain-preflight.js';
@@ -361,7 +362,7 @@ export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
         'move, in which case a clean rebuild is still required.',
     ].join('\n'))
         .action(withErrorHandling(async (options) => {
-        await buildCommand(getProjectRoot(), pickDefined(options));
+        const projectRoot = getProjectRoot();
+        await withEngineSessionLock(projectRoot, 'build', () => buildCommand(projectRoot, pickDefined(options)));
     }));
 }
-//# sourceMappingURL=build.js.map

package/dist/src/commands/config.js

@@ -1,5 +1,8 @@
-import { configExists, loadConfig, loadRawConfigDocument, mutateConfig, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, withConfigFileLock, writeConfig, writeConfigDocument, } from '../core/config.js';
+// SPDX-License-Identifier: EUPL-1.2
+import { Command } from 'commander';
+import { configExists, loadRawConfigDocument, mutateConfig, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, validateConfig, withConfigFileLock, writeConfigDocument, } from '../core/config.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { ConfigError } from '../errors/config.js';
 import { toError } from '../utils/errors.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
@@ -154,24 +157,42 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                 // for a *known* key. Apply strict validation whenever the key is
                 // listed in SUPPORTED_CONFIG_PATHS, regardless of --force, and only
                 // skip validation for genuinely unknown key paths.
+                //
+                // BOTH branches seed the mutation from the raw on-disk document.
+                // The known-key branch used to round-trip through `loadConfig` →
+                // `validateConfig`, which builds a typed clone containing only the
+                // known schema fields — so any ordinary `fireforge config <key>
+                // <value>` silently dropped every previously --force-written key
+                // from fireforge.json (2026-07-05 review, finding H4; the --force
+                // branch's comment described this exact hazard for its own path).
                 if (options.force && !keyIsKnown) {
-                    // Seed mutation from the raw on-disk document so previously-forced
-                    // keys (which `validateConfig` would strip) survive the round-trip.
-                    // Without this, writing a second --force key would silently drop
-                    // every earlier forced key from fireforge.json.
                     const updatedConfig = mutateConfig(rawConfig, key, parsedValue, true);
                     await writeConfigDocument(projectRoot, updatedConfig);
                 }
                 else {
-                    const config = await loadConfig(projectRoot);
-                    const updatedConfig = mutateConfig(config, key, parsedValue);
-                    await writeConfig(projectRoot, updatedConfig);
+                    // Mutate the raw document (preserving unknown keys), then run
+                    // strict validation on the RESULT — validateConfig checks the
+                    // known schema fields and ignores unknown keys, so this keeps
+                    // exactly the old validation strength while writing the
+                    // unstripped document.
+                    const updatedConfig = mutateConfig(rawConfig, key, parsedValue, true);
+                    validateConfig(updatedConfig);
+                    await writeConfigDocument(projectRoot, updatedConfig);
                 }
                 return false;
             });
         }
         catch (error) {
-            throw new InvalidArgumentError(`Invalid value for "${key}": ${toError(error).message}`, key);
+            // Only value/validation problems are the user's "invalid value".
+            // Lock-acquisition timeouts and I/O failures must keep their own
+            // types/messages — re-labelling a lock timeout as `Invalid value for
+            // "<key>"` used to point diagnosis at the value (and return the
+            // wrong exit-code class) when the actual problem was a concurrent
+            // fireforge process holding the config lock.
+            if (error instanceof ConfigError) {
+                throw new InvalidArgumentError(`Invalid value for "${key}": ${toError(error).message}`, key);
+            }
+            throw error;
         }
         if (unchanged) {
             info(`${key} = ${formatValue(parsedValue)} (unchanged)`);
@@ -225,4 +246,3 @@ export function registerConfig(program, { getProjectRoot, withErrorHandling }) {
         await configCommand(getProjectRoot(), key, value, pickDefined(options));
     }));
 }
-//# sourceMappingURL=config.js.map

package/dist/src/commands/discard.js

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { confirm } from '@clack/prompts';
+import { Command } from 'commander';
 import { getProjectPaths } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { isGitRepository } from '../core/git.js';
+import { getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { discardStatusEntry } from '../core/git-file-ops.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
@@ -104,6 +105,18 @@ export async function discardCommand(projectRoot, file, options = {}) {
     if (!(await isGitRepository(paths.engine))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
+    // Unborn-HEAD guard (mirrors status): an interrupted download leaves a
+    // repo with no baseline commit, where the entire ~300k-file tree reads
+    // as untracked — a discard against that state is never what the operator
+    // wants, and the guidance names the actual fix.
+    try {
+        await getHead(paths.engine);
+    }
+    catch (headError) {
+        if (!isMissingHeadError(headError))
+            throw headError;
+        throw new GeneralError('Engine repository has no baseline commit yet — a previous "fireforge download" was interrupted before git created the initial Firefox source commit. Re-run "fireforge download --force" to recreate the baseline repository cleanly.');
+    }
     // Check if the file has changes
     const statusEntries = await expandUntrackedDirectoryEntries(paths.engine, await getWorkingTreeStatus(paths.engine));
     const statusEntry = statusEntries.find((entry) => entry.file === file || entry.originalPath === file);
@@ -145,7 +158,10 @@ export async function discardCommand(projectRoot, file, options = {}) {
         }
     }
     if (options.dryRun) {
-        const target = statusEntry.originalPath === file
+        // Show the rename pair regardless of which side the operator passed —
+        // passing the NEW path of a rename used to hide that discarding also
+        // resurrects the old path, exactly when the full picture matters most.
+        const target = statusEntry.originalPath
             ? `${statusEntry.originalPath} -> ${statusEntry.file}`
             : statusEntry.file;
         info(`Would discard changes to: ${target}`);
@@ -194,4 +210,3 @@ export function registerDiscard(program, { getProjectRoot, withErrorHandling })
         await discardCommand(getProjectRoot(), file, pickDefined(options));
     }));
 }
-//# sourceMappingURL=discard.js.map

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

@@ -83,4 +83,3 @@ export const POST_REBASE_AUDIT_CHECK = {
     dependsOn: ['fireforge.json is valid'],
     run: runPostRebaseAudit,
 };
-//# sourceMappingURL=post-rebase-audit.js.map

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

@@ -29,4 +29,3 @@ export function warning(name, message, fix) {
 export function failure(name, message, fix) {
     return { name, passed: false, severity: 'error', message, ...(fix ? { fix } : {}) };
 }
-//# sourceMappingURL=doctor-check-core.js.map

package/dist/src/commands/doctor-external-toolchains.d.ts

@@ -0,0 +1,3 @@
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/** Doctor check for opt-in project-declared external asset/toolchain requirements. */
+export declare const EXTERNAL_TOOLCHAIN_DOCTOR_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-external-toolchains.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { isAbsolute, resolve } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { exec, findExecutable } from '../utils/process.js';
+import { failure, warning } from './doctor-check-core.js';
+async function resolveDeclaredTool(projectRoot, tool) {
+    if (tool.path !== undefined) {
+        const candidate = isAbsolute(tool.path) ? tool.path : resolve(projectRoot, tool.path);
+        return (await pathExists(candidate)) ? candidate : undefined;
+    }
+    if (tool.xcrun === true) {
+        try {
+            const found = await exec('xcrun', ['-find', tool.name], { timeout: 5000 });
+            const line = found.stdout.split(/\r?\n/).find((entry) => entry.trim().length > 0);
+            return found.exitCode === 0 ? line?.trim() : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return findExecutable(tool.name);
+}
+async function runExternalToolchainChecks(ctx) {
+    const toolchains = ctx.config?.externalToolchains;
+    if (!toolchains || toolchains.length === 0)
+        return [];
+    const rows = [];
+    for (const toolchain of toolchains) {
+        for (const tool of toolchain.tools) {
+            const label = `External toolchain: ${toolchain.name}/${tool.name}`;
+            const found = await resolveDeclaredTool(ctx.projectRoot, tool);
+            if (found !== undefined) {
+                rows.push({ name: label, passed: true, severity: 'ok', message: `OK (${found})` });
+                continue;
+            }
+            const required = tool.required !== false;
+            const location = tool.path
+                ? `at ${tool.path}`
+                : tool.xcrun
+                    ? `via xcrun -find ${tool.name}`
+                    : 'on PATH';
+            const message = `${tool.name} was not found ${location}.`;
+            const fix = `Install ${tool.name} or update fireforge.json externalToolchains for ${toolchain.name}.`;
+            rows.push(required ? failure(label, message, fix) : warning(label, message, fix));
+        }
+    }
+    return rows;
+}
+/** Doctor check for opt-in project-declared external asset/toolchain requirements. */
+export const EXTERNAL_TOOLCHAIN_DOCTOR_CHECK = {
+    name: 'External toolchains',
+    dependsOn: ['fireforge.json is valid'],
+    run: runExternalToolchainChecks,
+};

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

@@ -44,4 +44,3 @@ export const furnaceStaleJarRegistrationCheck = {
         }
     },
 };
-//# sourceMappingURL=doctor-furnace-jar.js.map

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

@@ -194,4 +194,3 @@ export const furnaceManifestSyncCheck = {
             'Nothing to repair (orphans surfaced but all were already recoverable).');
     },
 };
-//# sourceMappingURL=doctor-furnace-manifest-sync.js.map

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

@@ -6,6 +6,7 @@ import { hasCustomEngineDrift, hasOverrideEngineDrift } from '../core/furnace-ap
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, } from '../core/furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from '../core/furnace-constants.js';
 import { getFurnaceLockPath, runFurnaceMutation } from '../core/furnace-operation.js';
+import { hasBlockingStepErrors } from '../core/furnace-step-errors.js';
 import { validateAllComponents } from '../core/furnace-validate.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -25,7 +26,7 @@ async function runRepairApply(projectRoot) {
     return runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }), { skipPendingRepairCheck: true });
 }
 function countApplyFailures(applyResult) {
-    const appliedWithStepErrors = applyResult.applied.filter((entry) => (entry.stepErrors?.length ?? 0) > 0).length;
+    const appliedWithStepErrors = applyResult.applied.filter((entry) => hasBlockingStepErrors(entry)).length;
     return applyResult.errors.length + appliedWithStepErrors;
 }
 function firstApplyFailure(applyResult) {
@@ -512,4 +513,3 @@ export const FURNACE_DOCTOR_CHECKS = [
     furnaceComponentValidationCheck,
     furnaceManifestSyncCheck,
 ];
-//# sourceMappingURL=doctor-furnace.js.map

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

@@ -94,4 +94,3 @@ export async function inspectEngineWorkingTree(ctx) {
         : '';
     return warning('Engine working tree', `Engine working tree has ${counts.unmanaged} unmanaged change${counts.unmanaged === 1 ? '' : 's'}.${managedTail}`, 'Use "fireforge status --ownership" to separate patch-backed from unmanaged files, then export, discard, or reset only the unmanaged set.');
 }
-//# sourceMappingURL=doctor-working-tree.js.map

package/dist/src/commands/doctor.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { Command } from 'commander';
 import { configExists, getProjectPaths, loadConfig, loadState, updateState, } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists } from '../core/furnace-config.js';
 import { getCurrentBranch, getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
@@ -12,6 +14,7 @@ import { error, info, intro, outro, success, warn } from '../utils/logger.js';
 import { findExecutable } from '../utils/process.js';
 import { POST_REBASE_AUDIT_CHECK } from './doctor/post-rebase-audit.js';
 import { failure, ok, warning } from './doctor-check-core.js';
+import { EXTERNAL_TOOLCHAIN_DOCTOR_CHECK } from './doctor-external-toolchains.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 import { collectPatchQueueHealth } from './verify.js';
@@ -173,6 +176,7 @@ const DOCTOR_CHECKS = [
         },
         fix: 'Check fireforge.json for syntax errors or missing fields',
     },
+    EXTERNAL_TOOLCHAIN_DOCTOR_CHECK,
     {
         name: 'Engine directory exists',
         run: (ctx) => {
@@ -476,4 +480,3 @@ export function registerDoctor(program, { getProjectRoot, withErrorHandling }) {
         }
     }));
 }
-//# sourceMappingURL=doctor.js.map