@hominis/fireforge 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,9 +1,46 @@
 # Changelog
 
+## 0.18.0
+
+### Compatibility
+
+- **No re-export required for existing 0.17.0 patches.** Every fix in this release is additive or defensive: the patch body format is unchanged, the `patches.json` schema only gains two optional fields (both already round-tripped through the validator in 0.17.0), and `fireforge import`/`verify` against a 0.17.0-exported queue continues to behave identically. Operators can upgrade in place.
+- **No breaking API changes for downstream `import '@hominis/fireforge'` consumers.** `src/core/mach.ts`'s `build()` / `buildUI()` signatures changed from `Promise<number>` to `Promise<MachCommandResult>` so `fireforge build` can annotate the tail of mach's output (see below), but neither function is exported from `src/index.ts` — the public surface stays the same.
+- **Minor cosmetic drift on wire-generated code and token coverage percentages.** `fireforge wire` now stamps `// <BINARY>: wire-<step> <name>` marker comments (see below). Patches exported before 0.18.0 that captured the pre-fix `// <name> init — must be first…` form continue to apply cleanly — the wire mutator's idempotency check is keyed on the call expression, not the comment, so re-running `wire` against a 0.17.0-wired tree is still a no-op and will not double up. Operators who want the marker in existing patches can either re-run `wire` after deleting the old block, or hand-edit the patch once. Token coverage percentages shift upward on any project that copies `--moz-*` CSS baselines (now counted as allowlisted platform vars instead of unknown) — CI thresholds pinned to 0.17.0 numbers may need a one-time adjustment.
+
+### Hardening
+
+- **`fireforge lint` (aggregate) + `fireforge export-all` — EISDIR crashes on patches that introduce new directories.** `resolveLintDiff` in `src/commands/lint.ts` and `resolveFurnaceExclusionPolicy` / the `--exclude-furnace` branch in `src/commands/export-all.ts` both blended `getModifiedFiles()` + `getUntrackedFiles()` (or raw `getWorkingTreeStatus()`) before handing the path list to `getDiffForFilesAgainstHead`. `git status --porcelain=v1 -z` collapses untracked directories to `?? browser/modules/<fork>/` entries, so `generateNewFileDiff` inside the diff pass called `readText()` on a directory path and crashed with `EISDIR: illegal operation on a directory, read` — the eval's imported hominis queue and its fresh-project register-wire workflow both hit this. The fix plumbs `expandUntrackedDirectoryEntries` (already present for `status --ownership`) through both call sites so only file paths reach the diff pass, and `getDiffForFilesAgainstHead` in `src/core/git-diff.ts` now runs a belt-and-suspenders expansion via `getUntrackedFilesInDir` before reading any candidate as a file — a single bad call site cannot re-introduce the crash at that layer. `fireforge lint --per-patch` already worked; aggregate mode and `export-all` now do too.
+- **`fireforge doctor` — ownership-aware working-tree classification.** `runEngineGitChecks` in `src/commands/doctor.ts` previously emitted a single generic `Engine working tree has <N> local changes` warning for any dirty count and told the operator to `export, discard, or reset them as appropriate`. That advice was destructive on a freshly-imported patch stack (eval: a correctly imported 126-file queue on `hominis` triggered the warning, and the suggested `discard` / `reset` recovery would have dropped the entire import) and spurious on a fresh project with tool-managed branding (eval: 63/64 dirty files after a successful build were classified as `branding` by `fireforge status`, yet `doctor` still told the operator to export / discard them). The new `inspectEngineWorkingTree` helper in `src/commands/doctor-working-tree.ts` (split out to keep `doctor.ts` under max-lines) reuses the shared `classifyFiles` pipeline — same partitioning as `fireforge status --ownership`: `branding` / `furnace` / `patch-backed` / `conflict` / `unmanaged`. Doctor now warns only on the `unmanaged` bucket (and raises a loud distinct warning on `conflict`, with a pointer at `status --ownership` + `verify`); tool-managed buckets pass with an ownership summary (`N tool-managed changes (X patch-backed, Y branding), 0 unmanaged`). A missing config falls back to the legacy count-only warning so a broken project still gets a useful row. Ordering dependency on `fireforge.json is valid` is declared explicitly via `dependsOn`.
+- **`fireforge furnace remove` — drops the locale jar.mn chrome registration for localized custom components.** Before this fix, `furnaceRemoveCommand` in `src/commands/furnace/remove.ts` deleted the `.ftl` file and the component directory but never dropped the `locale/@AB_CD@/<chromeSubPath>/<tag>.ftl` entry that `applyCustomFtlFile` wrote during deploy. The eval's `furnace remove moz-eval-chip --yes` left `engine/browser/locales/jar.mn` pointing at the now-missing FTL; `furnace validate` still passed, and later builds/packaging would have tripped over the stale reference. The fix threads the existing `removeCustomFtlJarMnEntry` helper from `src/core/furnace-apply-ftl.ts` into the localized branch of `furnaceRemoveCommand`, snapshot-protected by the same rollback journal that guards the FTL-file removal so a mid-remove failure restores both together. `fireforge furnace validate` after remove now reports a clean state without a follow-up `apply --dry-run` cleanup plan.
+- **`fireforge furnace rename` — rewires the locale jar.mn entry on localized renames.** `updateEngineRegistrations` in `src/commands/furnace/rename.ts` renamed the `.ftl` file on disk but left the locale jar.mn pointing at `locale/.../${oldName}.ftl`. `fireforge furnace validate` passed anyway because the validator only checked the toolkit `jar.mn` (for `.mjs`/`.css` entries), not the locale jar.mn — the eval reported "validate passed" for two full minutes while the engine carried a stale registration for a file that no longer existed. The fix, gated on `customConfig.localized`, calls `removeLocaleFtlJarMnEntry(oldName)` + `addLocaleFtlJarMnEntry(newName)` against `resolveFtlLocaleJarMnPath(config.ftlBasePath)` inside the same rollback journal as the FTL file rename, so both changes land together or roll back together. Non-localized renames are unaffected.
+- **`fireforge furnace override` — concurrent invocations no longer silently drop each other's manifest entries.** The eval ran two `furnace override` commands in parallel against the same fresh project (one `moz-button`, one `moz-card`): both exited `0`, both override directories landed on disk, but `furnace.json` kept only one entry. Root cause: `performOverrideMutations` acquired the furnace lock via `runFurnaceMutation` but `saveOverrideConfig` wrote back the outer-snapshot config object — each invocation had loaded an empty-overrides state BEFORE entering the lock, and the second writer clobbered the first writer's addition. `saveOverrideConfig` now re-reads fresh furnace.json state inside the lock via `loadAuthoringFurnaceConfig`, splices the new entry plus the stock-bucket removal onto the fresh state, and writes that back — so a sibling writer's addition survives into the final manifest. A concurrent-writer regression test under `furnace-override.test.ts` pins the contract; other furnace mutations (`remove`, `rename`, `deploy`) already re-read inside the lock and need no equivalent fix.
+- **`fireforge doctor --repair-furnace` — detects and recovers orphaned override directories.** New `Furnace manifest sync` check in the new `src/commands/doctor-furnace-manifest-sync.ts` module (spliced into `FURNACE_DOCTOR_CHECKS` so `doctor-furnace.ts` stays under max-lines). Without `--repair-furnace` the check warns when `components/overrides/<name>/` or `components/custom/<name>/` exists on disk but is absent from `furnace.json` — the exact residue left by the concurrent-override race above or by any interrupted mutation. With `--repair-furnace`, override orphans are re-registered by reading the `override.json` sidecar `furnace override` writes during the copy phase (`type`, `description`, `basePath`, `baseVersion`, optional `baseCommit`), folding the recovered entry into a fresh furnace.json read, and persisting. Custom orphans are listed for the operator to either `furnace create` against or delete manually, because custom components have no equivalent sidecar — fabricating `targetPath` / `register` / `localized` values is worse than the orphaned directory itself. Doctor now catches the residue from eval 2's concurrent-override reproduction and the symmetric case where an operator SIGINT's a mutation mid-flight.
+- **`fireforge build` — annotates mach's trailing `config.status is out of date` notice instead of leaving it to read as build failure.** mach's post-build guard prints `config.status is out of date with respect to browser/moz.configure` when a tool-managed edit (most commonly `setupBranding`'s `patchMozConfigure` on first build) landed on `moz.configure` before the build. The guard runs AFTER `Your build was successful!` so operators reading the tail of a successful build saw contradictory signals — the eval recorded this on both a fresh project's first build and a pre-existing hominis build. `build()` and `buildUI()` in `src/core/mach.ts` now return the captured `MachCommandResult` (stdout/stderr tail + exit code) instead of just an exit code; `buildCommand` in `src/commands/build.ts` scans `result.stdout`/`stderr` for `/config\.status is out of date/i` and, on match, emits a one-line `info(...)` explaining the notice is a known side effect of tool-managed branding edits and does not require a rebuild. Test-command `buildUI` callers in `src/commands/test.ts` pick up the new return shape; no caller outside the CLI sees the signature change (neither function is exported from `src/index.ts`).
+- **`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.
+- **`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.
+- **`fireforge wire` — `// <BINARY>:` marker comments in wire-generated code.** `lintModificationComments` in `src/core/patch-lint.ts` checks JS/MJS additions for a `// <binaryName.toUpperCase()>:` marker (case-insensitive) and flags `missing-modification-comment` on upstream file edits that lack it. `fireforge wire` itself wrote comments like `// <name> init — must be first, before Firefox subsystem` — generic text that trips the patch-lint rule on the first export after wiring, so the eval saw `[missing-modification-comment] browser/base/content/browser-init.js` on content generated by FireForge's own command. Each wire mutator (`addInitAST`/`legacyAddInit`, `addDestroyAST`/`legacyAddDestroy`, `addSubscriptAST`/`legacyAddSubscript`) now accepts a `marker: string` parameter (default `'FIREFORGE:'` for back-compat with programmatic callers); `browser-wire.ts:wireSubscript` computes the project-scoped marker as `${config.binaryName.toUpperCase()}:` from `fireforge.json` and threads it through. Emitted blocks now carry `// FRESHFORGE: wire-init <name> — must be first, …` (or the caller's equivalent uppercased binaryName), satisfying the lint rule on the first export. Patches exported before 0.18.0 that captured the old comment format still apply cleanly — patch content is unchanged — they just won't have the marker; operators who want the marker in existing patches can re-run `wire` after deleting the old block (idempotency is keyed on the call expression, so re-running alone is a no-op). `.inc.xhtml` fragments inserted by `--dom` are preprocessor directives, not JS — `lintModificationComments` only checks JS, so no marker is needed there.
+- **`fireforge build --ui` + `fireforge build` — `.inc.xhtml` fragments excluded from the packaging audit.** `isPackageablePath` in `src/core/build-audit.ts` treated `.inc.xhtml` as a `.xhtml` file, so a wire-introduced `browser/base/content/<name>.inc.xhtml` (consumed via `#include` from a registered chrome document and resolved at packaging time) got flagged as "missing packaged artifact" on the next UI build. `register --dry-run` already refuses to register these fragments with explicit guidance — the build audit now matches that contract with an early `sourcePath.endsWith('.inc.xhtml') → false` return. The two sibling checks now agree about this file type.
+- **`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.
+
+### Internal
+
+- **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.
+
 ## 0.17.0
 
 ### Eval-driven hardening
 
+- **`fireforge lint --per-patch` — branding-tier detection tolerates the one-line registration sibling + explicit `tier: "branding"` opt-in, and `lintIgnore` now round-trips through the manifest loader.** The 0.16.0 branding tier (notice 3000 / warning 8000 / error 20000) was gated on `isBrandingOnlyPatch` in `src/core/patch-lint.ts` returning true only when _every_ entry in `filesAffected` began with `browser/branding/`. Real-world branding patches follow the Firefox convention of also touching `browser/moz.configure` (to register the new branding flavor with the top-level configure), so the 2026-04-21 external audit reported that `lint --per-patch` still fired `ERROR [large-patch-lines] 001 (patch): Patch is 15665 lines (hard limit: 3000)` on a minimum branding diff — the 0.16.0 fix only helped forks with trivially scoped branding patches. Two mechanisms land together: (a) the auto-detector now accepts a narrow allowlist of branding-registration siblings (`browser/moz.configure`, `browser/confvars.sh`) in addition to the `browser/branding/` prefix, guarded by a "≥1 file under `browser/branding/`" requirement so a config-only patch cannot accidentally qualify; (b) a new optional `tier?: 'branding'` field on `PatchMetadata` forces the branding thresholds regardless of `filesAffected`, threaded through `runPatchLint`, `export`, `export-all`, `re-export`, `re-export --files`, and `lint --per-patch` — mirroring how `lintIgnore` expresses per-patch intent. Precedence stays `test > branding > general` (tests still win even with explicit `tier: "branding"`). A one-line `info()` surfaces the tier choice when branding applies, distinguishing "all files under browser/branding/ + registration siblings" from "operator declared tier: branding". Coupled with a pre-existing latent bug uncovered during the audit: `validatePatchMetadata` in `src/core/patch-manifest-validate.ts` returned a fresh object enumerating only the required fields, silently stripping `lintIgnore` on every manifest load — so the 0.16.0 escape hatch only round-tripped through tests that mocked `loadPatchesManifest` directly. Real operator edits to `patches.json` evaporated. The validator now preserves `lintIgnore` (via a new `optionalStringArray` helper in `src/utils/parse.ts`) and `tier`, and `rebuildPatchesManifest` in `src/core/patch-manifest-consistency.ts` preserves both fields on `doctor --repair-patches-manifest` so the repair path no longer strips them. Unknown `tier` values are rejected at load time with a clear message rather than silently stripped — a typo like `"Branding"` surfaces as a loader error, matching the strict validation already applied to `category` and `sourceEsrVersion`.
 - **`fireforge config` — serialised writes behind a sidecar lock.** The 2026-04-21 eval reproduced silent data loss by running two `fireforge config` invocations in parallel against the same `fireforge.json`: both commands exited `0`, but only one key survived. Atomic-rename writes (`writeJson`'s temp file + rename) prevented torn files but not lost updates: each writer read the pre-state, mutated its own copy, and the second rename clobbered the first writer's change. A new `withConfigFileLock(projectRoot, operation)` helper in `src/core/config.ts` wraps the read-modify-write cycle in `src/commands/config.ts:configCommand` — both the strict-validated and `--force` write branches now take the lock. Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: atomic rename means readers always see either the pre- or post-state, so only writers need to be serialised. Stale-lock recovery reuses the existing PID-alive probe from `withFileLock` so a crashed `fireforge config` does not wedge the next command.
 - **`fireforge token add --mode override` — dark values land inside the nested `:root { }`.** The previous `insertDarkModeOverride` in `src/core/token-manager.ts` found the outer `@media (prefers-color-scheme: dark) { }` block's closing `}` and spliced the dark-value declaration before that line — which is _after_ the nested `:root { }` had already closed, producing a declaration outside any rule block. The generated tokens CSS was syntactically malformed after every legitimate `token add --mode override` call, and `token coverage` no longer recognised the added tokens. The fix walks the comment-stripped line array to find the `:root {` opener _inside_ the `@media` block, then depth-counts to its own closing `}`, and inserts there. A fallback path (warn + synthesise a fresh nested `:root` before the outer close) handles malformed scaffolds where the nested `:root` was removed, so we never silently drop a dark value or emit a top-level declaration. The test coverage in `src/core/__tests__/token-manager.test.ts` now pins the invariant that the dark entry's line index must be _less_ than the inner `:root`'s closing `}`, so a future refactor cannot regress to the outer-block landing.
 - **`fireforge furnace rename` — cleans up deployed widgets, renames mochikit test + chrome.toml.** The previous `renameTestFiles` helper in `src/commands/furnace/rename.ts` handled the `browser/base/content/test/<binaryName>/` browser-chrome layout but not the `toolkit/content/tests/widgets/` mochikit layout, and `performRenameMutations` made no attempt to clear `engine/<oldTargetPath>/` after deployment. The 2026-04-21 eval renamed `ff-chip-row` → `ff-chip-stack` and ended up with `engine/toolkit/content/widgets/ff-chip-row/` still deployed, `test_ff-chip-row.html` still importing `chrome://global/content/elements/ff-chip-row.mjs`, and the `chrome.toml` entry still naming the old file. Two new helpers pick up the slack: `removeStaleDeployedComponentDir` snapshots + removes `engine/<oldTargetPath>/` so the next `furnace apply` is the sole writer of the new deployment; `renameMochikitTestFiles` snapshots the old scaffold, rewrites the chrome URI + class-test identifiers to the new name, and updates the widgets `chrome.toml` entry. Both run under the same rollback journal as the rest of the rename, so a later failure restores every touched path.

package/README.md

@@ -193,8 +193,12 @@ This re-exports the fixed patch and clears the conflict state. The command is de
       "description": "Replaces default Firefox branding with custom logo",
       "createdAt": "2025-01-15T10:30:00Z",
       "sourceEsrVersion": "140.9.0esr",
-      "filesAffected": ["browser/branding/official/logo.png"],
-      "lintIgnore": ["large-patch-lines", "large-patch-files"]
+      "filesAffected": [
+        "browser/branding/official/logo.png",
+        "browser/themes/custom-shared/tokens.css"
+      ],
+      "lintIgnore": ["large-patch-lines", "large-patch-files"],
+      "tier": "branding"
     }
   ]
 }
@@ -202,6 +206,8 @@ 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.
+
 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.
 
 </details>
@@ -213,24 +219,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)     | 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 >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 |
 
 **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.
 
@@ -427,6 +433,8 @@ fireforge patch reorder 003-ui-sidebar.patch --before 001-branding-logo.patch
 fireforge patch compact
 ```
 
+`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 subcommands support `--dry-run` and `--yes`.
 
 ### Additional workflow commands
@@ -551,6 +559,18 @@ Design tokens imported from the fork's palette are enforced by `tokenPrefix`, bu
 
 Both rules compose with the existing `tokenPrefix` / `tokenAllowlist` checks and apply to both component validation and patch-stack lint.
 
+### Platform variables in Furnace (token coverage)
+
+`fireforge token coverage` partitions `var(--…)` usages into three buckets: fork-owned tokens (matching `tokenPrefix`), allowlisted exceptions (explicit `tokenAllowlist` entries, plus platform prefixes), and unknown. Platform prefixes default to `['--moz-']` so upstream Firefox variables in copied baselines (e.g. the CSS that lands under `toolkit/content/widgets/<name>/` after `furnace override <name> -t css-only`) don't drag the fork-owned coverage percentage down.
+
+```json
+{
+  "platformPrefixes": ["--moz-", "--in-content-"]
+}
+```
+
+Set this in `furnace.json` to extend the list (forks with additional platform prefixes) or pass an empty array to restore the pre-0.18 strict contract where `--moz-*` counted as unknown. Allowlisted usages are reported separately and are NOT counted toward the coverage denominator, so a 100% fork-owned project with a copied upstream baseline reads as `100%` instead of `1%`.
+
 ### Test harness options
 
 `fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest**. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.).

package/dist/src/commands/build.js

@@ -127,7 +127,7 @@ export async function buildCommand(projectRoot, options) {
     }
     info(''); // Empty line before build output
     const startTime = Date.now();
-    let exitCode;
+    let result;
     try {
         // Hold the per-project build lock across the mach invocation so two
         // overlapping `fireforge build` / `fireforge build --ui` commands
@@ -138,7 +138,7 @@ export async function buildCommand(projectRoot, options) {
         // backend — not a clue that a concurrent build was the cause. The
         // lock turns the second invocation's failure into an explicit
         // refusal naming the holder PID.
-        exitCode = await withBuildLock(projectRoot, async () => {
+        result = await withBuildLock(projectRoot, async () => {
             if (options.ui) {
                 return buildUI(paths.engine);
             }
@@ -152,9 +152,23 @@ export async function buildCommand(projectRoot, options) {
     const minutes = Math.floor(duration / 60000);
     const seconds = Math.floor((duration % 60000) / 1000);
     const timeStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
-    if (exitCode !== 0) {
+    if (result.exitCode !== 0) {
         error(`Build failed after ${timeStr}`);
-        throw new BuildError(`Build failed with exit code ${exitCode}`, options.ui ? 'mach build faster' : 'mach build');
+        throw new BuildError(`Build failed with exit code ${result.exitCode}`, options.ui ? 'mach build faster' : 'mach build');
+    }
+    // Tool-managed branding edits that land on `browser/moz.configure`
+    // before the build cause mach's post-build guard to print
+    // "config.status is out of date … Be sure to run |mach build|" even
+    // though the build itself completed cleanly. 2026-04-21 eval finding:
+    // operators read that as "your build is stale" and either rebuilt
+    // (wasting ~10 minutes) or doubted the Fireforge "Build completed"
+    // footer. Annotate the captured output so the operator knows the
+    // warning is expected and not actionable.
+    const staleConfigurePattern = /config\.status is out of date/i;
+    if (staleConfigurePattern.test(result.stdout) || staleConfigurePattern.test(result.stderr)) {
+        info('Note: mach reported "config.status is out of date" after this build. ' +
+            'That notice is a known side effect of tool-managed branding edits applied before the build ' +
+            'and does not require a rebuild — the Fireforge exit code is authoritative.');
     }
     // Warn-only post-build audit: surfaces silent packaging drops (files
     // edited in engine/ but never registered for packaging) against the

package/dist/src/commands/doctor-furnace-manifest-sync.d.ts

@@ -0,0 +1,18 @@
+/**
+ * "Furnace manifest sync" doctor check.
+ *
+ * Surfaces orphaned component directories on disk whose names are missing
+ * from `furnace.json`. The motivating eval case is the concurrent-override
+ * race (eval 2) where two parallel `furnace override` commands both left
+ * their directory on disk but only the second reached
+ * `writeFurnaceConfig`. Under `--repair-furnace`, override orphans are
+ * re-registered from the `override.json` sidecar the command wrote during
+ * the copy phase; custom orphans are listed for the operator to either
+ * re-run `furnace create` against or delete manually, because custom
+ * components have no similar persisted metadata.
+ *
+ * Lives in a sibling module to keep `doctor-furnace.ts` under the
+ * per-file LOC budget.
+ */
+import type { DoctorCheckDefinition } from './doctor.js';
+export declare const furnaceManifestSyncCheck: DoctorCheckDefinition;

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

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * "Furnace manifest sync" doctor check.
+ *
+ * Surfaces orphaned component directories on disk whose names are missing
+ * from `furnace.json`. The motivating eval case is the concurrent-override
+ * race (eval 2) where two parallel `furnace override` commands both left
+ * their directory on disk but only the second reached
+ * `writeFurnaceConfig`. Under `--repair-furnace`, override orphans are
+ * re-registered from the `override.json` sidecar the command wrote during
+ * the copy phase; custom orphans are listed for the operator to either
+ * re-run `furnace create` against or delete manually, because custom
+ * components have no similar persisted metadata.
+ *
+ * Lives in a sibling module to keep `doctor-furnace.ts` under the
+ * per-file LOC budget.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig } from '../core/furnace-config.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readJson } from '../utils/fs.js';
+import { failure, ok, warning } from './doctor.js';
+async function listComponentDirs(dir) {
+    if (!(await pathExists(dir)))
+        return [];
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function recoverOverrideConfig(overrideDir, name) {
+    // `furnace override` writes `override.json` alongside the copied files.
+    // That sidecar is enough to reconstruct the furnace.json entry lost to
+    // a concurrent-write race (eval 2: second override wrote back the
+    // outer-snapshot config, dropping the sibling write's addition).
+    const sidecarPath = join(overrideDir, name, 'override.json');
+    if (!(await pathExists(sidecarPath)))
+        return undefined;
+    try {
+        const raw = await readJson(sidecarPath);
+        const type = raw.type;
+        const description = raw.description;
+        const basePath = raw.basePath;
+        const baseVersion = raw.baseVersion;
+        if ((type !== 'css-only' && type !== 'full') ||
+            typeof description !== 'string' ||
+            typeof basePath !== 'string' ||
+            typeof baseVersion !== 'string') {
+            return undefined;
+        }
+        const restored = {
+            type: type,
+            description,
+            basePath,
+            baseVersion,
+        };
+        if (typeof raw.baseCommit === 'string') {
+            restored.baseCommit = raw.baseCommit;
+        }
+        return restored;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function collectOrphans(projectRoot, config) {
+    const furnacePaths = getFurnacePaths(projectRoot);
+    const overrideDirs = await listComponentDirs(furnacePaths.overridesDir);
+    const overrideOrphans = [];
+    for (const name of overrideDirs) {
+        if (name in config.overrides)
+            continue;
+        const recoveredConfig = await recoverOverrideConfig(furnacePaths.overridesDir, name);
+        overrideOrphans.push({ name, recoveredConfig });
+    }
+    const customDirs = await listComponentDirs(furnacePaths.customDir);
+    const customOrphans = customDirs.filter((name) => !(name in config.custom));
+    return { overrides: overrideOrphans, customNames: customOrphans };
+}
+function formatOrphanSummary(orphans) {
+    const overrideCount = orphans.overrides.length;
+    const customCount = orphans.customNames.length;
+    const overrideLabel = overrideCount > 0
+        ? `${overrideCount} override${overrideCount === 1 ? '' : 's'} ` +
+            `(${orphans.overrides.map((o) => o.name).join(', ')})`
+        : '';
+    const customLabel = customCount > 0
+        ? `${customCount} custom ${customCount === 1 ? 'directory' : 'directories'} ` +
+            `(${orphans.customNames.join(', ')})`
+        : '';
+    const description = [overrideLabel, customLabel].filter(Boolean).join(' and ');
+    return `Found orphaned component ${overrideCount + customCount === 1 ? 'directory' : 'directories'} on disk: ${description}. furnace.json does not list these — a previous mutation may have lost a concurrent write.`;
+}
+async function repairOrphanOverrides(projectRoot, orphans) {
+    const restored = [];
+    const unrecoverable = [];
+    if (orphans.length === 0)
+        return { restored, unrecoverable };
+    const freshConfig = await loadFurnaceConfig(projectRoot);
+    for (const orphan of orphans) {
+        if (orphan.recoveredConfig) {
+            freshConfig.overrides[orphan.name] = orphan.recoveredConfig;
+            restored.push(orphan.name);
+        }
+        else {
+            unrecoverable.push(orphan.name);
+        }
+    }
+    if (restored.length > 0) {
+        try {
+            await writeFurnaceConfig(projectRoot, freshConfig);
+        }
+        catch (err) {
+            return { restored: [], unrecoverable, writeError: toError(err).message };
+        }
+    }
+    return { restored, unrecoverable };
+}
+export const furnaceManifestSyncCheck = {
+    name: 'Furnace manifest sync',
+    dependsOn: ['Furnace configuration'],
+    skipIf: (ctx) => !ctx.furnaceConfigExists || !ctx.furnaceConfig,
+    run: async (ctx) => {
+        const config = ctx.furnaceConfig;
+        if (!config)
+            return [];
+        const orphans = await collectOrphans(ctx.projectRoot, config);
+        const overrideCount = orphans.overrides.length;
+        const customCount = orphans.customNames.length;
+        if (overrideCount === 0 && customCount === 0) {
+            return ok('Furnace manifest sync');
+        }
+        const summary = formatOrphanSummary(orphans);
+        if (!ctx.options.repairFurnace) {
+            return warning('Furnace manifest sync', summary, 'Run "fireforge doctor --repair-furnace" to re-register override orphans from their override.json sidecars (custom orphans are listed for manual follow-up).');
+        }
+        const repairResult = await repairOrphanOverrides(ctx.projectRoot, orphans.overrides);
+        if (repairResult.writeError) {
+            return failure('Furnace manifest sync', `Repair failed while writing furnace.json: ${repairResult.writeError}`, 'Fix the underlying filesystem error and retry the doctor command.');
+        }
+        const { restored, unrecoverable } = repairResult;
+        const restoreDetail = restored.length > 0
+            ? `Re-registered ${restored.length} override${restored.length === 1 ? '' : 's'} (${restored.join(', ')}) from their override.json sidecars.`
+            : '';
+        const unrecoverableDetail = unrecoverable.length > 0
+            ? ` Could not recover ${unrecoverable.length} override${unrecoverable.length === 1 ? '' : 's'} without a valid override.json (${unrecoverable.join(', ')}) — delete components/overrides/<name> or re-run "fireforge furnace override" to restore the entry.`
+            : '';
+        const customDetail = customCount > 0
+            ? ` ${customCount} custom ${customCount === 1 ? 'directory requires' : 'directories require'} manual action: re-run "fireforge furnace create" or delete components/custom/<name>/ to reconcile.`
+            : '';
+        return warning('Furnace manifest sync', `${restoreDetail}${unrecoverableDetail}${customDetail}`.trim() ||
+            'Nothing to repair (orphans surfaced but all were already recoverable).');
+    },
+};
+//# sourceMappingURL=doctor-furnace-manifest-sync.js.map

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

@@ -10,6 +10,7 @@ import { validateAllComponents } from '../core/furnace-validate.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { failure, ok, warning } from './doctor.js';
+import { furnaceManifestSyncCheck } from './doctor-furnace-manifest-sync.js';
 const ENGINE_REPAIRABLE_OPERATIONS = [
     'preview-teardown',
     'apply-rollback',
@@ -507,5 +508,6 @@ export const FURNACE_DOCTOR_CHECKS = [
     furnaceStaleLockCheck,
     furnaceEngineStateCheck,
     furnaceComponentValidationCheck,
+    furnaceManifestSyncCheck,
 ];
 //# sourceMappingURL=doctor-furnace.js.map

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

@@ -0,0 +1,29 @@
+/**
+ * Ownership-aware working-tree check for `fireforge doctor`.
+ *
+ * Partitions engine-tree dirtiness into `branding`, `patch-backed`,
+ * `furnace`, `conflict`, and `unmanaged` buckets, and only warns on the
+ * last two — everything else is tool-managed state that the operator
+ * did not author directly.
+ *
+ * Split out of `doctor.ts` so that file stays under the per-file LOC
+ * budget; see the call site in `runEngineGitChecks`.
+ */
+import type { DoctorCheck } from '../types/commands/index.js';
+import type { DoctorCheckContext } from './doctor.js';
+/**
+ * Inspects the engine working tree and returns a single
+ * `DoctorCheck`. Ownership-aware: patch-backed / branding / furnace
+ * rows are reported as OK with an ownership summary; unmanaged drift
+ * warns; cross-patch conflicts warn loudly with a pointer at
+ * `fireforge status --ownership` + `fireforge verify`.
+ *
+ * Before 0.16.1 this check warned on every dirty row regardless of
+ * ownership and told the operator to export/discard/reset — advice
+ * that was actively destructive on a patch-backed import (eval
+ * Finding: a correctly imported 126-file patch stack was reported as
+ * unhealthy and the suggested fix would have dropped the entire
+ * import). Returns `undefined` when the worktree is clean so the
+ * caller can emit its own ok() row.
+ */
+export declare function inspectEngineWorkingTree(ctx: DoctorCheckContext): Promise<DoctorCheck | undefined>;

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

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Ownership-aware working-tree check for `fireforge doctor`.
+ *
+ * Partitions engine-tree dirtiness into `branding`, `patch-backed`,
+ * `furnace`, `conflict`, and `unmanaged` buckets, and only warns on the
+ * last two — everything else is tool-managed state that the operator
+ * did not author directly.
+ *
+ * Split out of `doctor.ts` so that file stays under the per-file LOC
+ * budget; see the call site in `runEngineGitChecks`.
+ */
+import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
+import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
+import { classifyFiles } from '../core/status-classify.js';
+import { ok, warning } from './doctor.js';
+function summarizeWorkingTreeChangeCount(changeCount) {
+    return `Engine working tree has ${changeCount} local change${changeCount === 1 ? '' : 's'}. Some FireForge commands assume a clean baseline and may behave differently until these are exported, discarded, or committed.`;
+}
+function formatManagedDetail(counts) {
+    return [
+        counts.patchBacked > 0 ? `${counts.patchBacked} patch-backed` : null,
+        counts.branding > 0 ? `${counts.branding} branding` : null,
+        counts.furnace > 0 ? `${counts.furnace} furnace` : null,
+    ]
+        .filter((part) => part !== null)
+        .join(', ');
+}
+/**
+ * Inspects the engine working tree and returns a single
+ * `DoctorCheck`. Ownership-aware: patch-backed / branding / furnace
+ * rows are reported as OK with an ownership summary; unmanaged drift
+ * warns; cross-patch conflicts warn loudly with a pointer at
+ * `fireforge status --ownership` + `fireforge verify`.
+ *
+ * Before 0.16.1 this check warned on every dirty row regardless of
+ * ownership and told the operator to export/discard/reset — advice
+ * that was actively destructive on a patch-backed import (eval
+ * Finding: a correctly imported 126-file patch stack was reported as
+ * unhealthy and the suggested fix would have dropped the entire
+ * import). Returns `undefined` when the worktree is clean so the
+ * caller can emit its own ok() row.
+ */
+export async function inspectEngineWorkingTree(ctx) {
+    const { paths } = ctx;
+    const rawStatus = await getWorkingTreeStatus(paths.engine);
+    const workingTreeStatus = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
+    if (workingTreeStatus.length === 0) {
+        return ok('Engine working tree');
+    }
+    if (!ctx.config) {
+        return warning('Engine working tree', summarizeWorkingTreeChangeCount(workingTreeStatus.length), 'Use "fireforge status" to review changes, then export, discard, or reset them as appropriate.');
+    }
+    const furnacePrefixes = await collectFurnaceManagedPrefixes(ctx.projectRoot);
+    const classified = await classifyFiles(workingTreeStatus.map((entry) => ({ status: entry.status, file: entry.file })), paths.engine, paths.patches, ctx.config.binaryName, furnacePrefixes);
+    const counts = {
+        branding: 0,
+        furnace: 0,
+        patchBacked: 0,
+        conflict: 0,
+        unmanaged: 0,
+    };
+    for (const entry of classified) {
+        if (entry.classification === 'branding')
+            counts.branding++;
+        else if (entry.classification === 'furnace')
+            counts.furnace++;
+        else if (entry.classification === 'patch-backed')
+            counts.patchBacked++;
+        else if (entry.classification === 'conflict')
+            counts.conflict++;
+        else
+            counts.unmanaged++;
+    }
+    if (counts.conflict > 0) {
+        return warning('Engine working tree', `Engine working tree has ${counts.conflict} cross-patch ownership conflict${counts.conflict === 1 ? '' : 's'}. Multiple patches in patches.json claim the same file.`, 'Run "fireforge status --ownership" to see the conflicting patches, then run "fireforge verify" and resolve the overlap.');
+    }
+    const managedTotal = counts.branding + counts.furnace + counts.patchBacked;
+    if (counts.unmanaged === 0) {
+        const managedDetail = formatManagedDetail(counts);
+        return {
+            name: 'Engine working tree',
+            passed: true,
+            severity: 'ok',
+            message: `${managedTotal} tool-managed change${managedTotal === 1 ? '' : 's'} (${managedDetail}), 0 unmanaged. Use "fireforge status --ownership" for details.`,
+        };
+    }
+    const managedTail = managedTotal > 0
+        ? ` (${managedTotal} other change${managedTotal === 1 ? '' : 's'} are tool-managed: ${formatManagedDetail(counts)}).`
+        : '';
+    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

@@ -2,7 +2,6 @@ import { configExists, getProjectPaths, loadConfig, loadState } from '../core/co
 import { furnaceConfigExists as checkFurnaceConfigExists } from '../core/furnace-config.js';
 import { getCurrentBranch, getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { ensureGit } from '../core/git-base.js';
-import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { ensureMach, ensurePython } from '../core/mach.js';
 import { countPatches } from '../core/patch-apply.js';
 import { rebuildPatchesManifest, validatePatchesManifestConsistency, validatePatchIntegrity, } from '../core/patch-manifest.js';
@@ -12,6 +11,7 @@ import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
 import { executableExists } from '../utils/process.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
+import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 /**
  * Builds a DoctorCheck object representing a successful "OK" check.
  * Exported for sibling check modules that declare `DoctorCheckDefinition`
@@ -58,9 +58,6 @@ async function executeCheck(definition, ctx) {
         return [failure(definition.name, toError(err).message, definition.fix)];
     }
 }
-function summarizeWorkingTreeChangeCount(changeCount) {
-    return `Engine working tree has ${changeCount} local change${changeCount === 1 ? '' : 's'}. Some FireForge commands assume a clean baseline and may behave differently until these are exported, discarded, or committed.`;
-}
 /**
  * Runs the subset of engine checks that depend on a healthy git repository
  * and HEAD. This group shares mutable state (currentHead, canValidateBranch),
@@ -89,13 +86,9 @@ async function runEngineGitChecks(ctx) {
             rows.push(ok('Engine state consistency'));
         }
     }
-    const rawStatus = await getWorkingTreeStatus(paths.engine);
-    const workingTreeStatus = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
-    if (workingTreeStatus.length > 0) {
-        rows.push(warning('Engine working tree', summarizeWorkingTreeChangeCount(workingTreeStatus.length), 'Use "fireforge status" to review changes, then export, discard, or reset them as appropriate.'));
-    }
-    else {
-        rows.push(ok('Engine working tree'));
+    const workingTreeRow = await inspectEngineWorkingTree(ctx);
+    if (workingTreeRow) {
+        rows.push(workingTreeRow);
     }
     let branch;
     if (canValidateBranch) {
@@ -227,6 +220,11 @@ const DOCTOR_CHECKS = [
     {
         name: 'Engine is git repository',
         skipIf: (ctx) => !ctx.engineExists,
+        // runEngineGitChecks consults ctx.config for ownership-aware
+        // working-tree classification; declare the dependency so a future
+        // reorder doesn't silently regress the doctor back to the
+        // count-only fallback.
+        dependsOn: ['fireforge.json is valid'],
         run: async (ctx) => {
             const isRepo = await isGitRepository(ctx.paths.engine);
             if (!isRepo) {