@hominis/fireforge 0.18.0 → 0.18.2

package/CHANGELOG.md

@@ -20,8 +20,8 @@
 - **`fireforge test --doctor` — triple-path PASS footer survives non-TTY clack rendering.** The eval's `test --doctor` captures on both fresh and hominis projects showed `● Running marionette preflight...` and then exited 0 with nothing else — the 0.17.0 `outro(\`Marionette preflight: PASS (...)\`)`was dropped by clack somewhere in the non-TTY render pipeline (exact root cause could not be isolated from captures alone). Rather than chase the rendering bug, the fix triple-writes the result:`success(\`Marionette preflight: PASS (...)\`)`, then `outro('Test completed')`closes the intro frame, then`process.stdout.write(\`${summary}\n\`)`guarantees the line reaches stdout regardless of clack's buffering. A test in`test.test.ts` asserts all three emissions.
 - **`fireforge test` — fork-owned module import failures beat the branding stale-build diagnosis.** The eval's hominis xpcshell test failed loading `resource:///modules/hominis/HominisStore.sys.mjs`; FireForge reported "stale build artifacts, run fireforge build --ui" because the harness teardown also printed a branding warning that matched the narrower stale-build pattern. Re-running the build did nothing — the real failure was that the new module wasn't registered in `browser/modules/hominis/moz.build`. `handleNonZeroTestExit` now checks for `Failed to load resource:///modules/<binaryName>/` BEFORE the branding stale-build branch and surfaces a fork-module-specific diagnostic pointing at `browser/modules/<binary>/moz.build` + `fireforge register`, so the operator sees the correct recovery path on the first try. Existing branding-stale diagnosis is untouched.
 - **`fireforge token coverage` — `--moz-*` platform variables allowlisted by default; untracked CSS directories now scanned.** Two independent token-coverage fixes:
-  - **Platform allowlist** — `src/core/token-coverage.ts` seeds a default `platformPrefixes: ['--moz-']` and treats matches as `allowlisted` rather than `unknown`. A CSS-only Furnace override of `moz-button` with one fork token previously reported 1% coverage because the copied upstream baseline referenced 84 `--moz-*` platform vars; coverage now reports 100% on the same diff, and the one unknown was correctly declared by the fork. Forks can override through a new optional `platformPrefixes?: string[]` field on `furnace.json` — extending the list (e.g. `['--moz-', '--in-content-']`) for forks with additional platform prefixes, or setting an explicit empty array to restore the pre-0.18 strict contract. The field is added to the public `FurnaceConfig` type.
-  - **Untracked-directory expansion** — `src/commands/token-coverage.ts` now reads `getWorkingTreeStatus` + `expandUntrackedDirectoryEntries` instead of `getStatusWithCodes` so CSS files inside a `?? dir/` untracked directory (the common shape for a freshly-imported patch stack adding a new theme tree) show up in the scan. The eval's hominis run saw `?? browser/branding/hominis/content/aboutDialog.css` and `?? browser/themes/shared/hominis-tokens.css` collapse to directory entries that didn't end in `.css`; coverage reported "No modified CSS files". Both CSS files are now scanned.
+- **Platform allowlist** — `src/core/token-coverage.ts` seeds a default `platformPrefixes: ['--moz-']` and treats matches as `allowlisted` rather than `unknown`. A CSS-only Furnace override of `moz-button` with one fork token previously reported 1% coverage because the copied upstream baseline referenced 84 `--moz-*` platform vars; coverage now reports 100% on the same diff, and the one unknown was correctly declared by the fork. Forks can override through a new optional `platformPrefixes?: string[]` field on `furnace.json` — extending the list (e.g. `['--moz-', '--in-content-']`) for forks with additional platform prefixes, or setting an explicit empty array to restore the pre-0.18 strict contract. The field is added to the public `FurnaceConfig` type.
+- **Untracked-directory expansion** — `src/commands/token-coverage.ts` now reads `getWorkingTreeStatus` + `expandUntrackedDirectoryEntries` instead of `getStatusWithCodes` so CSS files inside a `?? dir/` untracked directory (the common shape for a freshly-imported patch stack adding a new theme tree) show up in the scan. The eval's hominis run saw `?? browser/branding/hominis/content/aboutDialog.css` and `?? browser/themes/shared/hominis-tokens.css` collapse to directory entries that didn't end in `.css`; coverage reported "No modified CSS files". Both CSS files are now scanned.
 - **`fireforge patch reorder` + `fireforge patch delete` — accept manifest `name` handle in addition to filename and ordinal.** `resolvePatchIdentifier` in `src/core/patch-manifest-resolve.ts` previously rejected the `name` field even though CLI help says `<name>` and the manifest stores a `name` on every entry. Operators had to copy the full filename from `patches.json` before every queue mutation. The resolver now matches, in order: ordinal number → exact filename → filename-with-`.patch`-appended → `name` field. Filename lookup still wins when a manifest happens to have a `name` identical to a different filename — legacy scripts passing filenames keep working. Error messages on both commands now list filenames AND their `name` counterparts so operators see both forms as valid identifiers.
 - **`fireforge patch reorder` — postcondition assert on each Phase 2 rename.** The eval reported that a two-patch swap updated `patches.json` but left the files at their pre-rename names, and `fireforge verify` then failed ENOENT opening the manifest-renamed file. The code path in `renumberPatchesInManifest` (two-phase staging: stage → final + manifest write) appears correct against both the integration test in `patch-mutations.integration.test.ts` and the shipped 0.17.0 dist — but the eval's operation log shows the manifest was updated while the rename was missing, so a filesystem-specific failure mode exists that the existing integration test does not exercise. Defense-in-depth lands a postcondition `pathExists(newFilename)` assert after every `rename()` in Phase 2, so any silent rename failure aborts the reorder before the manifest write and triggers the Phase 2 rollback (which itself reverses completed final-name moves and unwinds the staging). A second integration test reproduces the exact eval scenario (`001-infra` + `002-ui` swap via `--to 1 --yes`) and asserts both filenames exist on disk after completion.
 - **`fireforge register --dry-run` — honours the rule-level idempotency decision.** `registerFile` in `src/core/manifest-rules.ts` returned `{ skipped: true }` when the rule's `isRegistered(...)` check found the file already present in its manifest, but `registerCommand` in `src/commands/register.ts` ignored the flag on the dry-run branch and always printed `[dry-run] Would register <path>`. The next real invocation correctly reported `Already registered: <path>`. Automation that consumed the dry-run as a plan mis-predicted unnecessary work. Dry-run now prints `[dry-run] Already registered: <path> in <manifest>` when `result.skipped` is true — mirroring the real-run copy — and otherwise prints the registration plan as before.
@@ -30,9 +30,25 @@
 - **`fireforge register` — empty single-line `EXTRA_JS_MODULES += []` lists expand before insertion.** `tokenizeMozBuildList` in `src/core/manifest-tokenizers.ts` tracked opening `[` and closing `]` on separate lines. A freshly-scaffolded `browser/modules/<fork>/moz.build` that wrote `EXTRA_JS_MODULES += []` on one line returned `null` from the tokenizer because the scanner never saw a line STARTING with `]`, and `registerFireForgeModule` failed with `Could not find EXTRA_JS_MODULES in moz.build` — blocking the documented `browser/modules/<fork>/*.sys.mjs` workflow at the first module. The tokenizer now detects the single-line empty-list form `...+= []` at open time, rewrites `lines[i]` to `...+= [` and splices in a `]` at `i + 1`, and emits matched `list-open` / `list-close` tokens for the canonical multi-line shape. Downstream `findAlphabeticalMozBuildPosition` and the register helpers then place the new entry inside the brackets as normal.
 - **`fireforge wire --dry-run` — notice when the subscript file is absent.** The dry-run branch in `src/commands/wire.ts` deliberately skips the subscript-file existence check to support the "wire first, create the file after" scaffolding workflow. Pre-0.18 that deliberate skip produced a plausible plan even when the subscript was genuinely missing, and the real `wire` invocation then refused with `Subscript file not found`. The skip stays (the workflow is legitimate) but dry-run now emits `Note: <subscriptDir>/<name>.js does not exist yet — the real wire command will require it before writing.` so the operator sees the absence in the preview and can create the file before re-running without `--dry-run`.
 - **`fireforge status --unmanaged` + `fireforge register` — browser-chrome test files route to browser.toml, not jar.mn.** The browser-content pattern in `src/core/manifest-rules.ts` matched every `browser/base/content/**/*.{js,mjs,xhtml,css}` path, including test implementation files at `browser/base/content/test/<dir>/browser_*.js`. `status --unmanaged` therefore proposed `fireforge register browser/base/content/test/forgeqa/browser_forgeqa_qa_browser.js` which, if run, would cluttered jar.mn with a test-file chrome URI (the right place for those files is the sibling `browser.toml`). The pattern now excludes the `test/` subtree via a negative lookahead, so these paths fall through to `getUnregistrableAdvice`, which already returns the correct browser.toml-centric guidance for individual test files. `status`, `register`, and `register --dry-run` all now agree that test JS belongs in the test manifest.
+- **`fireforge export-all --exclude-furnace` — refuses patches that would register a furnace component without carrying its source files; `fireforge verify` now flags dangling registrations that slipped through earlier versions.** Finding 1 (High). The evaluator's fresh-project smoke sequence (`furnace init` → `token add` → `furnace override moz-button -t css-only` → `furnace create moz-qa-panel --localized --with-tests --test-style mochikit` → `furnace deploy` → `export-all --exclude-furnace`) produced a patch whose `toolkit/content/customElements.js`, `toolkit/content/jar.mn`, and `toolkit/locales/jar.mn` hunks registered `moz-qa-panel` even though the widget sources were filtered out. `fireforge verify` reported "Verify clean" for the broken queue. The fix lands in two layers: a new `collectPatchRegistrationReferences` scanner in `src/core/patch-registration-refs.ts` extracts component-shaped registration references from any patch body, and `verifyCommand` in `src/commands/verify.ts` now cross-checks each extracted reference against both the aggregate `filesAffected` coverage and the engine working tree — any miss fires a `dangling-registration` error naming the specific patch + target path. `export-all --exclude-furnace` in `src/commands/export-all.ts` calls the same scanner before writing and refuses with a clear message when the hunks would register a furnace-managed component not included in the patch. Tests in `patch-registration-refs.test.ts` + `verify.integration.test.ts` pin both halves.
+- **`fireforge status --unmanaged` — tolerates a missing parent moz.build instead of exiting non-zero.** Finding 2 (Medium). `printUnregisteredWarnings` in `src/commands/status.ts` awaited `Promise.all` on `isFileRegistered` checks, and the manifest-rules layer threw `GeneralError("Manifest not found: ...")` synchronously when the parent `moz.build` was absent — exactly the state an operator hits after scaffolding a new engine module and before running `register`. Status is a read-only reporter; the non-zero exit broke `status --unmanaged` as a discovery tool. The fix wraps each `isFileRegistered` call in a narrowly scoped try/catch, buckets missing-manifest cases into a distinct "registration manifest does not exist yet" warning list, and lets the command exit cleanly. Other error shapes still propagate. A regression test in `status.test.ts` pins the new contract.
+- **`fireforge lint --since HEAD --only-introduced` — aggregate patch-size findings tag as `[introduced]` when the diff set is non-empty.** Finding 4 (Low). The `large-patch-files` and `large-patch-lines` rules emit findings with the synthetic `file: '(patch)'` placeholder, which never matched any entry in the `diffFiles` set. `tagLintIssues` in `src/core/patch-lint-diff-tag.ts` therefore tagged them `[cumulative]` even when the aggregate was entirely the operator's own diff — reading as "pre-existing drift" to an operator asking "what did this task introduce?" The tagger now recognises the synthetic placeholder (exported as `AGGREGATE_PATCH_FILE`) and promotes it to `introduced` whenever the diff set is non-empty. Cumulative semantics are preserved for the empty-diff case. Tests in `patch-lint-diff-tag.test.ts` pin both branches.
+- **`fireforge furnace remove` / `rename` / `validate` — xpcshell scaffolds are cleaned up, renamed, and flagged as orphans.** Finding 5 (Medium). `furnace create --with-tests --xpcshell` scaffolds at `browser/base/content/test/<binary>-xpcshell/<name>/`, but the pre-0.18.1 `furnace remove` only touched the sibling browser-mochitest tree and `furnace rename` never reached the scaffold at all. Operators who ran create → rename → remove were left with an orphan scaffold whose filenames still referenced the original pre-rename component. The path template is now centralised in `xpcshellTestParentDir` in `src/core/furnace-constants.ts`; `create-xpcshell.ts` consumes it, a new `cleanupCustomXpcshellTestFiles` helper in `src/commands/furnace/remove.ts` removes the scaffold under the journal contract, a new `renameXpcshellTestFiles` helper in `src/commands/furnace/rename-xpcshell.ts` (extracted to keep `rename.ts` under the per-file LOC budget) updates the directory, test filename, TOML section header, and word-boundary tag references in the test body, and `findOrphanXpcshellScaffolds` in `src/core/furnace-validate.ts` walks the parent directory reporting any entry whose name is not in furnace.json as an `orphan-xpcshell-scaffold` error. The validator degrades silently on projects that never used xpcshell scaffolding. Test coverage lands in `furnace-validate-xpcshell-orphan.test.ts`.
+- **`fireforge doctor --repair-patches-manifest` — recovery guidance no longer contradicts the docs by telling operators to hand-edit patches.json.** Finding 6 (Low). The per-filename warning emitted on recovered manifest entries ended with "Edit patches.json to restore the original description if you have it backed up." — which directly contradicts the README and Hominis docs that treat the manifest as FireForge-owned. The reworded warning now points at `fireforge re-export <filename> --description "<your description>"` (or the equivalent `fireforge export` invocation) to overwrite the reconstructed metadata through the tool, and explicitly warns against hand-editing. Test coverage in `doctor.test.ts` pins both the presence of the new guidance and the absence of the old "Edit patches.json" string.
+- **`fireforge test --doctor` — PASS/FAIL line written directly to stdout, bypassing any clack flush races.** Finding 7 (Medium). The 0.18.0 "belt-and-suspenders" approach still reproducibly dropped the PASS footer under non-TTY capture — the eval log showed only the intro and `Running marionette preflight...` banner before exit. A new `formatMarionettePreflightLine` helper in `src/core/marionette-preflight.ts` returns the raw banner as a plain string, and `testCommand` in `src/commands/test.ts` writes both the "Running marionette preflight..." intro and the final PASS/FAIL summary via `process.stdout.write` as the authoritative emissions so non-TTY captures always see the summary. The clack `success()` + `outro()` calls are retained for TTY framing. Test coverage in `test.test.ts` now spies on `process.stdout.write` and asserts both the intro and PASS lines are emitted.
+- **`fireforge test` — xpcshell appdir probe prefers the macOS `.app/Contents/Resources/<value>` layout on Darwin.** Finding 8 (High). `resolveAbsoluteAppPath` in `src/core/xpcshell-appdir.ts` probed `dist/bin/<value>` first on every platform. On macOS `dist/bin` is a symlink to `<App>.app/Contents/MacOS/`, so `dist/bin/browser` resolved to the _binaries_ directory rather than the Resources tree where `resource:///modules/` is rooted — the auto-injection logged success, but the injected path did not match where modules actually live. The probe now branches on `process.platform`: on Darwin it prefers `<App>.app/Contents/Resources/<value>` first and falls back to `dist/bin/<value>`; other platforms keep the historical order. The operator-facing `buildXpcshellAppdirMessage` in `src/commands/test.ts` also gains a macOS-specific note recommending the `<appname>-appdir = "browser"` xpcshell.toml migration, which is the most reliable fix on rebranded macOS builds. Test coverage in `xpcshell-appdir.test.ts` now exercises both probe orders via `process.platform` branches.
+- **`fireforge download` — git-indexing timeouts raise a typed `GitIndexingTimeoutError` with env-var recovery guidance, and the monolithic → chunked transition is visible in non-TTY logs.** Finding 10 (High). On a loaded filesystem the fresh Firefox source indexing legitimately exceeded the 10-minute monolithic `git add -A` budget; the chunked fallback then hit its own `AbortSignal.timeout` and surfaced a generic `AbortError: The operation was aborted` with no recovery direction. `src/core/git-base.ts` now exposes `FIREFORGE_GIT_ADD_TIMEOUT_MS` and `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` environment variables that override the monolithic (default 10 min) and chunked (default grew to 30 min) timeouts respectively; the chunked pass's timeout is wrapped into a typed `GitIndexingTimeoutError` in `src/errors/git.ts` that names the elapsed budget, points at the environment variable override, and explains the `fireforge download --force` resume path. The fallback-transition progress banner now names the specific timeout so operators watching a non-TTY log see exactly when the monolithic attempt lost. Test coverage in `git-performance.test.ts` pins both the new error type and the refreshed transition banner.
+- **`fireforge rebase --dry-run` — refuses when the engine has no baseline commit.** Finding 11 (Medium). A partially-initialised engine (e.g. the aftermath of an aborted `download --force`) has `.git/` in place but no valid HEAD; the real `rebase --yes` immediately failed with `fatal: ambiguous argument 'HEAD'` even though dry-run had previously reported "Dry run complete" suggesting the rebase was ready to run. `handleFreshStart` in `src/commands/rebase/index.ts` now calls `getHead(paths.engine)` and, on `isMissingHeadError`, throws a clear `GeneralError` pointing at `fireforge download --force`. The check runs ahead of the dry-run early-exit so dry-run and real-run preconditions stay in sync. Test coverage in `rebase.test.ts` pins both the dry-run and real-run refusal paths.
+- **`fireforge watch` — resolved watchman directory is prepended to the mach subprocess PATH.** Finding 12 (Medium). `fireforge watch` located watchman via the parent shell PATH but the `mach watch` subprocess inherited the Node parent's PATH, which on macOS frequently omits `/opt/homebrew/bin`. `mach watch` then failed at the `watch-project` subscription step with a confusing `FasterBuildException: timed out`. `watch.ts` now resolves watchman's absolute path via `findExecutable`, prepends the containing directory to the subprocess PATH, and threads the composed env through a new optional `options.env` parameter on `watchWithOutput` in `src/core/mach.ts`. The watch-failure diagnostic also gains a line naming the resolved watchman path so operators can distinguish "FireForge didn't find watchman" from "FireForge found watchman but mach still failed to reach it." Test coverage in `watch.test.ts` pins the env plumbing and the de-duplication branch.
+- **`fireforge furnace preview` — first-run banner frames the unavoidable npm noise from `mach storybook`.** Finding 13 (Low). `mach storybook` internally drives a ~1000-package `npm install` when the Storybook workspace's `node_modules/` is absent and emits `npm error code ELSPROBLEMS` + `UNMET DEPENDENCY` lines verbatim. Operators on a fresh Firefox checkout read the npm block as a fatal error even though the command recovers and Storybook starts. `furnacePreviewCommand` in `src/commands/furnace/preview.ts` now checks for the absent `node_modules` before spawning mach and emits a clear pre-banner explaining the npm output is an expected one-time first-run cost; an explicit "Storybook stopped cleanly." line fires on clean exits so the npm noise is visually terminated. The `--install` path skips the banner because `mach storybook upgrade` already runs its install before `mach storybook` launches. Test coverage in `furnace-preview.test.ts` pins both the presence of the banner when node_modules is absent and its absence when node_modules is already populated.
 
 ### Internal
 
+- **Module extractions preserve the per-file LOC budget.** `doctor-working-tree.ts` hosts `inspectEngineWorkingTree` (the ownership-aware working-tree check), `doctor-furnace-manifest-sync.ts` hosts the orphan override / custom detection + repair, `patch-registration-refs.ts` hosts the dangling-registration scanner shared between `verify` and `export-all`, and `rename-xpcshell.ts` hosts the xpcshell scaffold rename path. All spliced into their respective orchestrators from the hosting file, keeping `doctor.ts`, `doctor-furnace.ts`, `rename.ts`, and `preview.ts` under the 500-line `max-lines` rule. The drift test in `manifest.test.ts` classifies each new file as a helper so the top-level command drift check stays clean.
+- **Expanded test coverage.** Every eval3 fix ships with at least one regression test exercising the failing path: `patch-registration-refs.test.ts` + `verify.integration.test.ts` (Finding 1), `status.test.ts` (Finding 2), `patch-lint-diff-tag.test.ts` (Finding 4), `furnace-validate-xpcshell-orphan.test.ts` (Finding 5), `doctor.test.ts` (Finding 6), `test.test.ts` (Finding 7), `xpcshell-appdir.test.ts` (Finding 8), `git-performance.test.ts` (Finding 10), `rebase.test.ts` (Finding 11), `watch.test.ts` (Finding 12), `furnace-preview.test.ts` (Finding 13).
+
+### Internal (0.18.0 original)
+
 - **Two small module extractions preserve the per-file LOC budget.** `doctor-working-tree.ts` hosts `inspectEngineWorkingTree` (the ownership-aware working-tree check), and `doctor-furnace-manifest-sync.ts` hosts the orphan override / custom detection + repair. Both are spliced into their respective registries from the hosting file, keeping `doctor.ts` and `doctor-furnace.ts` under the 500-line `max-lines` rule. The drift test in `manifest.test.ts` is extended to classify both new files as helpers so the top-level command drift check stays clean.
 - **Expanded test coverage — 34 new assertions.** Every fix above ships with at least one new test exercising the regression path: `src/core/__tests__/git-diff.test.ts` gains a `?? dir/` expansion case; `src/commands/__tests__/doctor.test.ts` gains patch-backed / conflict / orphan-override / manifest-sync-repair cases; `furnace-remove.test.ts` + `furnace-rename.test.ts` pin the locale jar.mn re-wire / removal; `furnace-override.test.ts` pins the concurrent-writer read-modify-write; `build.test.ts` pins the stale-configure annotation; `test.test.ts` pins the fork-module diagnostic + triple-path PASS footer; `token-coverage.test.ts` pins the `--moz-*` allowlist + untracked-dir expansion; `patch-manifest-helpers.test.ts` pins name-field resolution; `patch-mutations.integration.test.ts` pins the two-patch swap postcondition; `register.test.ts` pins dry-run idempotency; `wire-init.test.ts` pins the marker; `manifest-tokenizers.test.ts` + `register-module.test.ts` pin the empty-list expansion; `wire.test.ts` pins the dry-run missing-subscript notice; `manifest-register.test.ts` pins the test-file pattern exclusion.
 

package/README.md

@@ -36,7 +36,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 - **Python 3** (required by Firefox's `mach` build system).
 - **Git**
 - Platform build tools: Xcode on macOS, `build-essential` on Linux, Visual Studio Build Tools on Windows.
-- **Watchman** (optional, only required by `fireforge watch`). Install via `brew install watchman` (macOS), `dnf install watchman` (Fedora), or follow the upstream [Meta docs](https://facebook.github.io/watchman/). `fireforge doctor` surfaces a warning row when it is not on `PATH` so the dependency is visible during the usual onboarding sweep rather than at the watch-mode failure site.
+- **Watchman** (optional, only required by `fireforge watch`). Install via `brew install watchman` (macOS), `dnf install watchman` (Fedora), or follow the upstream [Meta docs](https://facebook.github.io/watchman/). `fireforge doctor` surfaces a warning row when it is not on `PATH` so the dependency is visible during the usual onboarding sweep rather than at the watch-mode failure site. `fireforge watch` resolves watchman's absolute path via `which` / `where` and prepends its directory to the subprocess `PATH` it hands mach, so a homebrew-installed watchman at `/opt/homebrew/bin/watchman` (absent from the Node subprocess's default `PATH` on macOS) is still visible to `mach watch` without the operator having to re-export `PATH` manually.
 
 ### Setup
 
@@ -83,6 +83,10 @@ npx fireforge download --force
 npx fireforge rebase
 ```
 
+`fireforge download` indexes the extracted Firefox source into a fresh git repository — a one-time 1–3 minute pass on a cold SSD, longer on slow or loaded disks. The monolithic `git add -A` is capped at 10 minutes by default and falls back to a per-directory chunked pass (30 minutes per chunk) when the cap hits. If indexing still times out, the command now raises `GitIndexingTimeoutError` with recovery guidance: extend the cap via `FIREFORGE_GIT_ADD_TIMEOUT_MS` (monolithic) and/or `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` (chunked) in milliseconds, e.g. `FIREFORGE_GIT_ADD_TIMEOUT_MS=1800000 fireforge download --force` for a 30-minute monolithic budget, then re-run `fireforge download --force` — the resume path picks up from the partial git state so the repeat is not wasted work.
+
+`fireforge rebase --dry-run` refuses when the engine has no baseline commit yet (e.g. the aftermath of an aborted `download --force`), so dry-run and real-run preconditions stay in sync.
+
 ## Patch Workflow
 
 Patches live in `patches/`, applied by numeric filename prefix and tracked in `patches/patches.json`:
@@ -206,7 +210,11 @@ This re-exports the fixed patch and clears the conflict state. The command is de
 
 The optional `lintIgnore` field lists lint check IDs to suppress for that patch specifically. Useful for the class of patch that is advisory-noisy by nature — a cohesive branding bundle, a localised-resource pack, an auto-generated manifest — where `--skip-lint` is too blunt and a per-line marker cannot exist (the `.patch` body is regenerated on every export). Threaded through `export`, `re-export`, `re-export --files`, and `lint --per-patch`. Unknown check IDs are a no-op.
 
-The optional `tier` field (only `"branding"` recognised) forces the branding threshold tier for the `large-patch-lines` rule regardless of what `filesAffected` looks like. The automatic branding-tier detection already fires when every file is under `browser/branding/` plus a narrow allowlist of branding-registration siblings (`browser/moz.configure`, `browser/confvars.sh`) — covering the canonical Firefox fork shape. Declare `tier: "branding"` only when the patch legitimately also touches a non-allowlisted sibling the auto-detector cannot reach (a fork-specific theme override under `browser/themes/<name>/`, a vendor-specific icon resource, etc.). Precedence is `test > branding > general`: a patch of all-tests always gets the more permissive test-tier thresholds even if it declares `tier: "branding"`. Unknown tier values are rejected at load time rather than silently stripped, so a typo surfaces as a loader error. Prefer `tier` over `lintIgnore: ["large-patch-lines"]` when the patch is legitimately branding-shaped — `tier` keeps the rule running at the correct thresholds (so the warning still surfaces if the patch crosses them); `lintIgnore` drops the rule entirely.
+Settable through the CLI in two places. `fireforge export --lint-ignore <check-id>` (repeatable) writes the field on creation; `fireforge re-export <name> --lint-ignore <check-id>` (repeatable, append/union semantics, de-duplicated) adds entries to an existing patch on the next refresh. For metadata-only edits that should **not** regenerate the `.patch` body — including the inverse `--remove` and `--clear` modes that re-export's append-only flag cannot express — use `fireforge patch lint-ignore <name> --add <id> | --remove <id> | --clear`.
+
+The optional `tier` field (only `"branding"` recognised) forces the branding threshold tier for the `large-patch-files` and `large-patch-lines` rules regardless of what `filesAffected` looks like. The automatic branding-tier detection already fires when every file is under `browser/branding/` plus a narrow allowlist of branding-registration siblings (`browser/moz.configure`, `browser/confvars.sh`) — covering the canonical Firefox fork shape. Declare `tier: "branding"` only when the patch legitimately also touches a non-allowlisted sibling the auto-detector cannot reach (a fork-specific theme override under `browser/themes/<name>/`, a vendor-specific icon resource, etc.). Precedence is `test > branding > general`: a patch of all-tests always gets the more permissive test-tier thresholds even if it declares `tier: "branding"`. Unknown tier values are rejected at load time rather than silently stripped, so a typo surfaces as a loader error. Prefer `tier` over `lintIgnore: ["large-patch-lines"]` when the patch is legitimately branding-shaped — `tier` keeps the rule running at the correct thresholds (so the warning still surfaces if the patch crosses them); `lintIgnore` drops the rule entirely.
+
+Settable via `fireforge export --tier branding` on creation, `fireforge re-export <name> --tier branding` on refresh, and `fireforge patch tier <name> --tier branding | --clear` for a metadata-only edit that does not rewrite the `.patch` body. The CLI rejects values other than `branding` up-front (matching the validator's strictness), and `re-export --tier` / `--lint-ignore` refuse `--all` because mass tier/ignore edits across a heterogeneous queue are virtually always footguns.
 
 If the manifest drifts after an interrupted export or manual edits, `fireforge import` will stop rather then silently applying a stale stack. Use `fireforge doctor --repair-patches-manifest` to rebuild it from disk. Because the rebuild is deterministic, the result will always be consistent with what is actually on the filesystem.
 
@@ -219,24 +227,24 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed — with tool-managed branding paths (`browser/branding/<binaryName>/`) excluded. A fresh-setup workspace carries a large generated branding diff that operators did not author directly, and letting it through tripped the patch-size and license-header rules on content that matches the `branding` bucket in `fireforge status`. When the exclusion fires the command prints a one-line note naming the excluded count so the filter is visible. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further — explicit-path mode does lint branding files (the operator's explicit request wins over the branding exclusion); the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
 
-| Check                          | Scope                                                                                           | Severity                 |
-| ------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------ |
-| `missing-license-header`       | New files (JS/CSS/FTL)                                                                          | error                    |
-| `relative-import`              | JS/MJS files                                                                                    | error                    |
-| `token-prefix-violation`       | CSS files (with furnace)                                                                        | error                    |
-| `raw-color-value`              | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                       | error                    |
-| `duplicate-new-file-creation`  | Same path created by multiple patches                                                           | error                    |
-| `forward-import`               | Patch imports from a later-patch file                                                           | error                    |
-| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                                                 | error                    |
-| `missing-modification-comment` | Modified upstream JS/MJS                                                                        | warning                  |
-| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                                            | warning                  |
-| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                    | notice / warning / error |
-| `observer-topic-naming`        | Observer topics with binaryName                                                                 | warning                  |
-| `large-patch-files`            | Patches affecting >5 files                                                                      | warning                  |
-| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 3000/8000/20000 branding) | notice / warning / error |
+| Check                          | Scope                                                                                            | Severity                 |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------ |
+| `missing-license-header`       | New files (JS/CSS/FTL)                                                                           | error                    |
+| `relative-import`              | JS/MJS files                                                                                     | error                    |
+| `token-prefix-violation`       | CSS files (with furnace)                                                                         | error                    |
+| `raw-color-value`              | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                        | error                    |
+| `duplicate-new-file-creation`  | Same path created by multiple patches                                                            | error                    |
+| `forward-import`               | Patch imports from a later-patch file                                                            | error                    |
+| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                                                  | error                    |
+| `missing-modification-comment` | Modified upstream JS/MJS                                                                         | warning                  |
+| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                                             | warning                  |
+| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                     | notice / warning / error |
+| `observer-topic-naming`        | Observer topics with binaryName                                                                  | warning                  |
+| `large-patch-files`            | Patches affecting many files (tiered: >5 general, >5 test, >60 branding)                         | warning                  |
+| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 8000/18000/30000 branding) | notice / warning / error |
 
 **JSDoc validation** uses AST-based analysis (Acorn) to validate exported APIs in patch-owned `.sys.mjs` files. A file is "patch-owned" if it was newly created by the current diff or by an existing patch in the queue. Functions must document every `@param` (names must match) and include `@returns` when the function returns a value. Exported constants and classes require a JSDoc block.
 
@@ -259,17 +267,18 @@ fireforge status --json             # machine-readable classified output
 
 Then fix with the appropriate primitive:
 
-| Problem                                        | Fix                                                                   |
-| ---------------------------------------------- | --------------------------------------------------------------------- |
-| Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files` |
-| A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                 |
-| Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                            |
-| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                             |
-| A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                        |
-| Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                          |
-| Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                       |
+| Problem                                        | Fix                                                                                                          |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files`                                        |
+| A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                                                        |
+| Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                                                                   |
+| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                                                                    |
+| A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                                                               |
+| Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                                                                 |
+| Dangling widget / locale registration in patch | Re-run `fireforge export` without `--exclude-furnace` to capture the source files, or revert furnace changes |
+| Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                                                              |
 
-Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` as the file is owned by FireForge.
+Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` as the file is owned by FireForge — `doctor --repair-patches-manifest` reconstructs missing metadata, and `fireforge re-export <filename> --description "<text>"` overwrites recovered entries with operator-supplied metadata through the tool. `fireforge verify` cross-checks every registration hunk in each patch body against the files the queue and engine supply, so a patch that registers a widget / locale without carrying its source surfaces as a `dangling-registration` error rather than slipping through as "Verify clean"; `fireforge export-all --exclude-furnace` refuses up-front when it would produce that shape.
 
 ## Wiring Custom Code
 
@@ -431,11 +440,21 @@ fireforge patch reorder 003-ui-sidebar.patch --before 001-branding-logo.patch
 
 # Close ordinal gaps after deletes or splits (e.g. 1, 3, 7 → 1, 2, 3)
 fireforge patch compact
+
+# Set or clear the threshold-tier override on a single patch
+# (no .patch body rewrite — manifest entry only)
+fireforge patch tier 001-branding-assets.patch --tier branding
+fireforge patch tier 001-branding-assets.patch --clear
+
+# Edit the lintIgnore list on a single patch (one mode per invocation)
+fireforge patch lint-ignore 001-branding-assets.patch --add large-patch-lines --add large-patch-files
+fireforge patch lint-ignore 001-branding-assets.patch --remove large-patch-lines
+fireforge patch lint-ignore 001-branding-assets.patch --clear
 ```
 
-`delete` and `reorder` accept three identifier forms for their target: the ordinal number (`fireforge patch reorder 3 --to 1`), the full filename (`003-ui-sidebar-tweaks.patch`), or the manifest `name` handle the patch was exported with (`ui-sidebar-tweaks`). Anchors passed to `--before` / `--after` accept the same three forms.
+All `patch <verb>` subcommands accept three identifier forms for their target: the ordinal number (`fireforge patch reorder 3 --to 1`), the full filename (`003-ui-sidebar-tweaks.patch`), or the manifest `name` handle the patch was exported with (`ui-sidebar-tweaks`). Anchors passed to `--before` / `--after` accept the same three forms. All subcommands support `--dry-run` and `--yes`.
 
-All subcommands support `--dry-run` and `--yes`.
+`patch tier` and `patch lint-ignore` are metadata-only edits: they update `patches/patches.json` under the patch directory lock and never rewrite the `.patch` body. Reach for them when an operator-visible advisory (e.g. `large-patch-files` firing on a 56-file fresh-fork branding bundle) needs the threshold-tier override or a per-patch lint suppression but the patch body is already correct — running `re-export` for that case wastes an engine read + diff regeneration. `patch lint-ignore` modes (`--add` / `--remove` / `--clear`) are mutually exclusive; `patch tier` rejects `--tier` and `--clear` together. The history log records each invocation under `operation: "patch-tier"` / `"patch-lint-ignore"` for audit.
 
 ### Additional workflow commands
 
@@ -472,6 +491,8 @@ fireforge lint --since main --only-introduced
 
 The failure message reports how many cumulative errors were suppressed by the flag so a branch that passed only because of the flag still tells the operator what was hidden. Without `--since`, `--only-introduced` is rejected up-front — there is no introduced-vs-cumulative distinction to scope to.
 
+Aggregate patch-size findings (`large-patch-files`, `large-patch-lines`) describe the whole diff rather than a single file. Under `--since` + a non-empty diff they tag `[introduced]` (the aggregate IS the introduced work); with an empty diff they tag `[cumulative]` (the finding describes drift accumulated across earlier commits).
+
 ### Post-build audit and auto-configure
 
 `fireforge build` is a transactional step: after a successful mach build it audits the dist bundle against engine-relative paths touched since the last successful build, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact or whose dist mtime is older than the source. Ends every build with a `Packaged: N updated, M stale, K missing, S skipped` summary. The audit is warn-only — it never fails a build that mach reported green.
@@ -589,9 +610,9 @@ The two flags can be combined — `--with-tests --xpcshell` writes both harnesse
 
 ### xpcshell appdir auto-injection on rebranded forks
 
-`fireforge test` auto-resolves and injects `--app-path=<absolute>` into the underlying `mach test` invocation when the nearest `xpcshell.toml` sets `firefox-appdir = "browser"` and the active build's `appname` is anything other than `firefox`. Without this, every `resource:///modules/<name>.sys.mjs` import inside the harness throws `Failed to load resource:///modules/…` because the upstream xpcshell harness reads the appdir override under the appname-keyed manifest field (`<appname>-appdir`) — the literal `firefox-appdir = "browser"` directive is silently ignored on rebranded forks, `appPath` falls back to `xrePath`, and `resource:///` resolves one level above the real app root. The resolver walks each test path to its nearest manifest, reads `mozinfo.json` for the active appname, prefers any `<appname>-appdir` already in the manifest, and otherwise probes `<objDir>/dist/bin/<value>` and `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` for the absolute target. Operator overrides via `--mach-arg=--app-path=…` always win and skip the resolver silently. Mismatches across multiple test paths and unresolvable manifest values surface as warnings rather than guesses, so triage reaches the underlying cause.
+`fireforge test` auto-resolves and injects `--app-path=<absolute>` into the underlying `mach test` invocation when the nearest `xpcshell.toml` sets `firefox-appdir = "browser"` and the active build's `appname` is anything other than `firefox`. Without this, every `resource:///modules/<name>.sys.mjs` import inside the harness throws `Failed to load resource:///modules/…` because the upstream xpcshell harness reads the appdir override under the appname-keyed manifest field (`<appname>-appdir`) — the literal `firefox-appdir = "browser"` directive is silently ignored on rebranded forks, `appPath` falls back to `xrePath`, and `resource:///` resolves one level above the real app root. The resolver walks each test path to its nearest manifest, reads `mozinfo.json` for the active appname, prefers any `<appname>-appdir` already in the manifest, and otherwise probes the platform-appropriate layout for the absolute target: on macOS, `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` is preferred over `<objDir>/dist/bin/<value>` (the `dist/bin` symlink on Darwin points at the binaries directory, not the Resources tree where modules live); on other platforms `dist/bin/<value>` is preferred and the macOS bundle layout is the fallback. Operator overrides via `--mach-arg=--app-path=…` always win and skip the resolver silently. Mismatches across multiple test paths and unresolvable manifest values surface as warnings rather than guesses, so triage reaches the underlying cause.
 
-The durable fix is to add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the manifest — the harness then reads the appname-keyed value directly without auto-injection. The xpcshell appdir hint that fires when the symptom persists despite injection lists this option first.
+The durable fix is to add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the manifest — the harness then reads the appname-keyed value directly without auto-injection. This is the most reliable fix on rebranded macOS builds where mach's xpcshell runner binds `-a` to the `.app/Contents/Resources` default and may not honour `--app-path` overrides. The xpcshell appdir hint that fires when the symptom persists despite injection lists this option first.
 
 ### Smoke-run mode (`fireforge run --smoke-exit`)
 

package/dist/src/commands/doctor.js

@@ -322,7 +322,19 @@ const DOCTOR_CHECKS = [
                 // (only `filesAffected` / ordering drifted) are not flagged.
                 if (repaired.recoveredFilenames.length > 0) {
                     for (const filename of repaired.recoveredFilenames) {
-                        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. Edit patches.json to restore the original description if you have it backed up.`);
+                        // 2026-04-24 eval Finding 6: the repair path used to tell the
+                        // operator to hand-edit patches.json, which contradicts the
+                        // README + Hominis docs that treat the manifest as
+                        // FireForge-owned. Point at the existing `re-export` /
+                        // `export` workflow instead so the fix stays inside the tool:
+                        // re-exporting the same files with an explicit `--description`
+                        // overwrites the recovered entry with operator-supplied
+                        // metadata and supersedes the mtime-based createdAt stamp.
+                        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. ` +
+                            'Re-export the affected files with `fireforge re-export <filename> --description "<your description>"` ' +
+                            '(or `fireforge export <paths...> --name <name> --category <category> --description "<your description>"`) ' +
+                            'to overwrite the reconstructed metadata, or accept the generic description if the original text is not recoverable. ' +
+                            'Avoid hand-editing patches.json — FireForge owns that file and will regenerate it on the next manifest consistency pass.');
                     }
                 }
                 return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.manifest.patches.length} patch${repaired.manifest.patches.length === 1 ? '' : 'es'}${repaired.recoveredFilenames.length > 0 ? ` (${repaired.recoveredFilenames.length} with reconstructed metadata — see warnings above)` : ''}. Review recovered metadata before release.`);

package/dist/src/commands/export-all.js

@@ -2,13 +2,14 @@
 import { Option } from 'commander';
 import { isBrandingManagedPath } from '../core/branding.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
+import { collectFurnaceManagedPrefixes, furnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
 import { hasChanges, isGitRepository } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { commitExportedPatch, findAllPatchesForFiles } from '../core/patch-export.js';
 import { buildPatchQueueContext, collectNewFileCreatorsByPath, detectNewFilesInDiff, } from '../core/patch-lint.js';
+import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
 import { GeneralError } from '../errors/base.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
@@ -62,6 +63,62 @@ async function resolveFurnaceExclusionPolicy(paths, projectRoot, excludeFurnace)
         'Review them with "fireforge status" or "fireforge furnace status", ' +
         'or pass --exclude-furnace to export the non-Furnace subset of the diff.');
 }
+/**
+ * Refuses the export when the resulting patch would register furnace
+ * component source files it does not itself carry. 2026-04-24 eval
+ * Finding 1: operators running `export-all --exclude-furnace` after
+ * `furnace create --localized --with-tests` ended up with patches that
+ * added `toolkit/content/widgets/moz-qa-panel/*` via jar.mn /
+ * customElements.js / locale jar.mn but excluded the component source
+ * files themselves. The resulting patch queue was structurally broken
+ * and `fireforge verify` stayed silent. We now detect the condition
+ * pre-write and ask the operator to either include the component
+ * sources (skip `--exclude-furnace`) or revert the furnace changes
+ * before exporting.
+ *
+ * The check runs against the synthesised patch body before
+ * `commitExportedPatch` writes anything, so no broken patch is left on
+ * disk when the refusal fires.
+ */
+async function checkDanglingFurnaceRegistrations(projectRoot, diff, furnaceExcluded) {
+    if (furnaceExcluded.size === 0)
+        return;
+    if (!(await furnaceConfigExists(projectRoot)))
+        return;
+    const refs = collectPatchRegistrationReferences(diff);
+    if (refs.length === 0)
+        return;
+    const config = await loadFurnaceConfig(projectRoot);
+    // Build the set of furnace-managed component names so we can tell
+    // "registers moz-qa-panel (furnace-managed)" apart from "registers
+    // moz-button (an upstream widget this patch legitimately touches)".
+    const furnaceComponentNames = new Set([
+        ...Object.keys(config.custom),
+        ...Object.keys(config.overrides),
+        ...config.stock,
+    ]);
+    const dangling = [];
+    for (const ref of refs) {
+        if (!furnaceExcluded.has(ref.targetPath))
+            continue;
+        const tagMatch = /toolkit\/content\/widgets\/([a-z][a-z0-9-]*)\//.exec(ref.targetPath);
+        const ftlMatch = /toolkit\/locales\/en-US\/toolkit\/global\/([a-z][a-z0-9-]*)\.ftl$/.exec(ref.targetPath);
+        const component = tagMatch?.[1] ?? ftlMatch?.[1];
+        if (!component || !furnaceComponentNames.has(component))
+            continue;
+        dangling.push({ component, targetPath: ref.targetPath, source: ref.source });
+    }
+    if (dangling.length === 0)
+        return;
+    const summary = dangling
+        .map((d) => `  • ${d.component} — registered via ${d.source} → ${d.targetPath}`)
+        .join('\n');
+    throw new GeneralError('Export-all --exclude-furnace would produce a patch that registers furnace-managed components without including their source files.\n\n' +
+        `Dangling registrations:\n${summary}\n\n` +
+        'To proceed, either:\n' +
+        '  1. Drop the --exclude-furnace flag so the source files are captured alongside the registration edits.\n' +
+        '  2. Revert the registration hunks (or the whole furnace workflow) before re-running export-all — registrations belong with their components, and splitting them across separate patches is what "verify" catches post-hoc as a dangling-registration error.');
+}
 /**
  * Refuses the export when the aggregate diff would create (new-file-mode) a
  * path that some existing patch in the queue already creates. `verify`
@@ -163,6 +220,11 @@ export async function exportAllCommand(projectRoot, options = {}) {
     // the aggregate would newly create, so it runs here instead of alongside
     // the branding / furnace guards that operate on the raw status list.
     await checkDuplicateNewFileCreations(paths, diff);
+    // Dangling-furnace-registration preflight (Finding 1). Runs after the
+    // diff is assembled so we can inspect the exact hunks the operator is
+    // about to land; runs BEFORE any write so a refusal leaves the
+    // patches directory untouched.
+    await checkDanglingFurnaceRegistrations(projectRoot, diff, furnaceExcluded);
     // Check for non-interactive mode
     const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
     // Auto-fix missing license headers on new files (interactive only)

package/dist/src/commands/export-flow.d.ts

@@ -82,6 +82,10 @@ export interface DryRunPreviewInput {
     filesAffected: string[];
     sourceEsrVersion: string;
     explicitSupersede: boolean;
+    /** Optional `PatchMetadata.tier` opt-in carried from the CLI. */
+    tier?: 'branding';
+    /** Optional `PatchMetadata.lintIgnore` carried from the CLI. */
+    lintIgnore?: string[];
 }
 /**
  * Renders the plain (non-placement) dry-run preview: calls planExport,

package/dist/src/commands/export-flow.js

@@ -314,12 +314,20 @@ export async function renderDryRunPreview(input) {
         description: input.description,
         filesAffected: input.filesAffected,
         sourceEsrVersion: input.sourceEsrVersion,
+        ...(input.tier !== undefined ? { tier: input.tier } : {}),
+        ...(input.lintIgnore !== undefined ? { lintIgnore: input.lintIgnore } : {}),
     });
     info(`\n[dry-run] Would write: patches/${plan.patchFilename}`);
     info(`  category: ${plan.metadata.category}`);
     info(`  order: ${plan.metadata.order}`);
     info(`  description: ${plan.metadata.description || '(none)'}`);
     info(`  filesAffected (${plan.metadata.filesAffected.length}): ${plan.metadata.filesAffected.join(', ')}`);
+    if (plan.metadata.tier !== undefined) {
+        info(`  tier: ${plan.metadata.tier}`);
+    }
+    if (plan.metadata.lintIgnore !== undefined && plan.metadata.lintIgnore.length > 0) {
+        info(`  lintIgnore: ${plan.metadata.lintIgnore.join(', ')}`);
+    }
     if (supersedeDetails.length > 0) {
         info(`\n[dry-run] Would supersede ${supersedeDetails.length} existing patch(es):`);
         for (const detail of supersedeDetails) {

package/dist/src/commands/export.js

@@ -172,7 +172,15 @@ export async function exportCommand(projectRoot, files, options) {
     try {
         // Extract affected files from diff
         const filesAffected = extractAffectedFiles(diff);
-        await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint);
+        // Apply the just-set --tier and --lint-ignore on the lint pass so the
+        // operator's intent takes effect on this invocation, not only on the
+        // next one. Without this, a fresh export with `--tier branding` would
+        // still hit general thresholds because the lint runs before the
+        // metadata is committed.
+        const exportIgnoreChecks = options.lintIgnore && options.lintIgnore.length > 0
+            ? new Set(options.lintIgnore)
+            : undefined;
+        await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint, undefined, exportIgnoreChecks, options.tier);
         // Resolve placement (if any flag was given). Placement is mutually
         // exclusive with supersede — the semantics overlap confusingly.
         let placementPlan = null;
@@ -225,6 +233,10 @@ export async function exportCommand(projectRoot, files, options) {
                 filesAffected,
                 sourceEsrVersion: config.firefox.version,
                 explicitSupersede: options.supersede === true,
+                ...(options.tier !== undefined ? { tier: options.tier } : {}),
+                ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                    ? { lintIgnore: options.lintIgnore }
+                    : {}),
             });
             outro('Dry run complete — no changes made');
             return;
@@ -243,6 +255,10 @@ export async function exportCommand(projectRoot, files, options) {
                 createdAt: new Date().toISOString(),
                 sourceEsrVersion: config.firefox.version,
                 filesAffected,
+                ...(options.tier !== undefined ? { tier: options.tier } : {}),
+                ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                    ? { lintIgnore: options.lintIgnore }
+                    : {}),
             };
             const committedPlan = await commitPlacementExport({
                 patchesDir: paths.patches,
@@ -314,6 +330,10 @@ export async function exportCommand(projectRoot, files, options) {
             diff,
             filesAffected,
             sourceEsrVersion: config.firefox.version,
+            ...(options.tier !== undefined ? { tier: options.tier } : {}),
+            ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                ? { lintIgnore: options.lintIgnore }
+                : {}),
         });
         for (const oldPatch of superseded) {
             info(`Superseded: ${oldPatch.filename}`);
@@ -348,11 +368,15 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('--force-unsafe', 'Bypass cross-patch lint refusal on projected placement')
         .option('--exclude-furnace', 'Exclude furnace-managed file paths from the export')
         .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap (default mode only; the resulting queue fails verify)')
+        .addOption(new Option('--tier <tier>', 'Force a tier override on the new patch (only "branding" recognised)').choices(['branding']))
+        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', (value, prev) => [...prev, value], [])
         .action(withErrorHandling(async (paths, options) => {
-        const { category, ...rest } = options;
+        const { category, tier, lintIgnore, ...rest } = options;
         await exportCommand(getProjectRoot(), paths, {
             ...pickDefined(rest),
             ...(category !== undefined ? { category: category } : {}),
+            ...(tier !== undefined ? { tier: tier } : {}),
+            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
         });
     }));
 }

package/dist/src/commands/furnace/create-xpcshell.js

@@ -5,6 +5,7 @@
  * per-file LOC budget and the scaffolder is unit-testable in isolation.
  */
 import { join } from 'node:path';
+import { xpcshellTestParentDir } from '../../core/furnace-constants.js';
 import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getLicenseHeader } from '../../core/license-headers.js';
 import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
@@ -26,8 +27,9 @@ import { generateXpcshellManifestContent, generateXpcshellTestContent, xpcshellT
  * auto-insertion that guessed wrong would be worse than a note.
  */
 export async function scaffoldXpcshellTestFiles(componentName, license, forgeConfig, paths, journal) {
-    const parentDirName = `${forgeConfig.binaryName}-xpcshell`;
-    const testDir = join(paths.engine, 'browser/base/content/test', parentDirName, componentName);
+    const parentRelDir = xpcshellTestParentDir(forgeConfig.binaryName);
+    const parentDirName = parentRelDir.split('/').slice(-1)[0] ?? `${forgeConfig.binaryName}-xpcshell`;
+    const testDir = join(paths.engine, parentRelDir, componentName);
     if (journal && !(await pathExists(testDir))) {
         recordCreatedDir(journal, testDir);
     }

package/dist/src/commands/furnace/preview.js

@@ -163,6 +163,38 @@ async function assertPreviewPrerequisites(engineDir) {
             'Run "fireforge bootstrap" (or the underlying `mach bootstrap` in the engine) to populate the toolchain config, then rerun "fireforge furnace preview".');
     }
 }
+/**
+ * Emits a framing banner when the Storybook workspace has not yet had
+ * its npm dependencies installed. `mach storybook` will drive the
+ * install internally and print ELSPROBLEMS / UNMET DEPENDENCY lines
+ * verbatim; without this banner operators reliably read the npm output
+ * as a failure (2026-04-24 eval Finding 13).
+ *
+ * Skipped when `--install` was explicitly requested — that path already
+ * runs `mach storybook upgrade` before the preview launches, so the npm
+ * output for the subsequent `mach storybook` invocation is a no-op.
+ */
+async function announceStorybookFirstRunIfNeeded(engineDir, installRequested) {
+    if (installRequested)
+        return;
+    const storybookNodeModules = join(engineDir, 'browser', 'components', 'storybook', 'node_modules');
+    const storybookDepsMissing = !(await pathExists(storybookNodeModules));
+    if (!storybookDepsMissing)
+        return;
+    info('Storybook workspace dependencies are not yet installed. The next step will install ~1000 npm packages via `mach storybook`; expect npm error-style output below. This is a one-time first-run cost — Storybook will start once the install finishes.');
+}
+/**
+ * Surfaces an explicit success banner after a clean mach-storybook
+ * exit so the operator's scrollback visually terminates the npm noise
+ * from the first-run install. Only fires on expected exit codes — non-
+ * zero cases fall through to the existing
+ * `buildStorybookFailureMessage` classification.
+ */
+function announceStorybookCleanExitIfApplicable(exitCode) {
+    if (exitCode === 0 || exitCode === 130 || exitCode === 143) {
+        info('Storybook stopped cleanly.');
+    }
+}
 /**
  * Runs the furnace preview command to start Storybook for component preview.
  * @param projectRoot - Root directory of the project
@@ -269,10 +301,16 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
                 }
                 installSpinner.stop('Storybook dependencies reinstalled');
             }
+            // 2026-04-24 eval Finding 13: frame the npm noise that `mach
+            // storybook` emits on first-run as expected progress rather than a
+            // failure. The banner-before / banner-after helpers are extracted
+            // so the command body stays under the per-function LOC budget.
+            await announceStorybookFirstRunIfNeeded(paths.engine, options.install ?? false);
             // Start Storybook
             info('Starting Storybook...');
             info('Press Ctrl+C to stop\n');
             previewResult = await runMachCapture(['storybook'], paths.engine);
+            announceStorybookCleanExitIfApplicable(previewResult.exitCode);
         }
         catch (error) {
             primaryError = error;