@hominis/fireforge 0.16.3 → 0.17.0

package/CHANGELOG.md

@@ -1,8 +1,46 @@
 # Changelog
 
+## 0.17.0
+
+### Eval-driven hardening
+
+- **`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.
+- **`fireforge furnace create --with-tests` — scaffolded mochikit test runs to completion.** `generateMochikitTestContent` in `src/commands/furnace/create-templates.ts` previously emitted `SimpleTest.waitForExplicitFinish()` alongside an `add_task(...)` and no explicit `SimpleTest.finish()`. The test harness waits forever: `waitForExplicitFinish()` tells the harness not to finish on script end, and the `add_task`-managed finish never fires because the scaffold has no explicit `finish()` body. The 2026-04-21 eval's `fireforge test --headless toolkit/content/tests/widgets/test_ff-chip-row.html` hung until the operator SIGINT'd it. The fix removes the `waitForExplicitFinish()` call — `add_task` already calls `SimpleTest.finish()` when every queued task resolves, matching the convention upstream widget tests (`toolkit/content/tests/widgets/test_moz-button.html` and siblings) use. A regression test in `src/commands/furnace/__tests__/create-mochikit.test.ts` pins the contract that the generated content must not contain `waitForExplicitFinish`.
+- **`fireforge furnace chrome-doc create --with-tests` — packaging test probes the correct packaged CSS path.** `generateChromeDocPackagingTest` in `src/commands/furnace/chrome-doc-tests.ts` probed `<AppDir>/chrome/browser/skin/classic/browser/<name>-chrome.css`, but the `jar.inc.mn` entry in `chrome-doc-templates.ts:chromeDocJarIncMnCssEntry` registers the file at `content/browser/<name>-chrome.css` — so the packaged location is `.../chrome/browser/content/browser/<name>-chrome.css`, not the skin layout. The 2026-04-21 eval's `fireforge test --build` against a scaffolded chrome-doc failed with a spurious "missing" assertion even though the file was correctly packaged. Both the primary probe and the macOS `.app`-bundle fallback now name the `content/browser/` layout, and a negative-match test guards against anyone pinning it back to `skin/classic/browser/` in a future refactor.
+- **`fireforge status --json` — cross-patch ownership conflicts surface as `conflict` with `claimedBy`.** `classifyFiles` in `src/commands/status.ts` tracked patch ownership as a `Set<string>` and collapsed multi-owner paths into the single-owner branch, where the content-compare then routed them into `unmanaged` when the engine content didn't match any single patch's expected result. The 2026-04-21 eval's `status --json` run reported `"classification": "unmanaged"` on two files that `status --ownership` correctly labelled `CONFLICT` — scripts built on the JSON view mis-diagnosed the drift and could have taken the wrong corrective action. The classifier now builds a `Map<string, string[]>` (filename → claiming patch filenames), emits `classification: "conflict"` for entries claimed by two or more patches, and attaches `claimedBy: string[]` to those entries so machine consumers can read the ownership set directly. The human default-mode output now surfaces a `Cross-patch ownership conflicts` section at the top pointing at `status --ownership` and `re-export --files` for recovery. Single-claim entries stay byte-identical to the pre-0.16.0 JSON shape (no unconditional `claimedBy` field) so parsers unaware of the new classification continue to work.
+- **`fireforge furnace init --ftl-base-path` — rejects file-shaped values up-front.** `validateFtlBasePath` in `src/commands/furnace/init.ts` only enforced syntactic safety (no absolute paths, no `..`, no null bytes). A plausible-but-invalid value like `browser/forgefresh.ftl` passed the gate, and the next localized `furnace create` scaffolded a component whose generated `.mjs` referenced `insertFTLIfNeeded("<name>.ftl")` while `furnace.json` never got the component entry — the scaffold was orphaned, every follow-up command failed with "not found in furnace.json", and the 2026-04-21 eval recorded this as Finding #5 (apparent non-registration) whose real root cause was Finding #6 (bad `ftlBasePath`). The validator now refuses any value whose basename carries `.ftl`, `.properties`, or `.dtd` with a message that names the file and points at a locale directory (`toolkit/locales/en-US/toolkit/global` or `browser/locales/en-US/browser`). When the engine directory is present on disk, it additionally probes whether the resolved path is a directory and warns (non-blocking) if the path does not yet exist — a fresh project that has not `fireforge download`-ed yet is legitimate.
+- **`fireforge furnace init` — defaults `tokenPrefix` from `fireforge.json`'s `binaryName`.** `createDefaultFurnaceConfig` previously accepted no arguments and omitted `tokenPrefix` entirely, so every fresh project that ran `furnace init` → `token add` → `token coverage` got `0 tokens` and "all unknown" reports until the operator discovered the missing key and hand-edited `furnace.json`. The helper now accepts `{ binaryName }` and, when passed, seeds `tokenPrefix: \`--${binaryName}-\``so the coverage scan has a prefix to key off immediately.`furnaceInitCommand`best-effort-loads`fireforge.json`and threads the binaryName through — a project that initialises Furnace before`fireforge setup`completes still gets a valid prefix-less default (and`token coverage` continues to warn when invoked without a prefix set).
+- **`fireforge build` + `fireforge build --ui` — per-project build lock prevents overlap.** A second `fireforge build --ui` launched while a full `fireforge build` was still running against the same engine tree raced the `obj-*` directory and failed immediately with `No rule to make target 'XUL'` — mach's downstream consequence of an incomplete backend, not a clue that the overlap was the root cause. A new `withBuildLock(projectRoot, operation)` in `src/core/mach.ts` backs onto `withFileLock` at `.fireforge-build.lock` beside the project root; `buildCommand` in `src/commands/build.ts` wraps both `build()` and `buildUI()` call paths in the lock. The refusal message names the holder PID and points at the stale-lock recovery path. Timeouts are bumped to 24h (a slow full build legitimately exceeds the default 30s) but the lock releases on process exit or via PID-alive stale recovery so a crashed build cannot permanently wedge the next invocation. A dedicated integration test in `src/core/__tests__/build-lock.integration.test.ts` pins the serialisation, throw-propagation, and stale-recovery contracts.
+- **`fireforge wire --dry-run` — insertion-point probe runs in both modes.** The dry-run branch previously skipped the `pathExists(join(paths.engine, domTargetPath))` check that the real-run branch ran, and even with existence confirmed the real run could still throw `Could not find insertion point in chrome document` from deep inside `addDomFragment` when the resolved chrome doc offered neither `#include browser-sets.inc` nor `<html:body>`. The 2026-04-21 eval's `wire ... --dom ... --dry-run` previewed a plausible plan targeting `tokenHostDocuments[0]`, then the same command without `--dry-run` failed against a `furnace chrome-doc create`-scaffolded document that lacked both anchors. A new `probeDomFragmentInsertionPoint` helper in `src/core/wire-dom-fragment.ts` reads the chrome doc and runs the same tokenised + legacy insertion-point scan the real run uses; `wireCommand` now calls it in both modes and surfaces the `Could not find insertion point` error before printing the plan. The dry-run preview now refuses the same cases the real run would refuse, before any operator commits to executing.
+- **`fireforge resolve` — `--yes` escape hatch + clearer two-step messaging.** The command refused any non-interactive invocation even after a CI-assisted manual merge was complete, because the TTY guard ran unconditionally — scripted recovery flows could complete the merge but could not then record the refreshed patch body. A new `--yes` / `-y` flag in `src/commands/resolve.ts` skips the interactive `confirm(...)` prompt and passes through in non-interactive mode; the unconditional TTY refusal fires only when the flag is absent. The command description changes from `Update a broken patch with manual fixes and continue` to `Update a broken patch with manual fixes (then run "fireforge import" to resume the queue)`, and the post-success info line now names the second-step command explicitly — the old copy implied a one-step flow where operators sometimes believed resolve continued the queue itself. Help snapshot under `src/__tests__/__snapshots__/help.test.ts.snap` is refreshed to match; resolve tests cover both the `--yes`-in-non-TTY path and the continuation messaging.
+- **`fireforge test` — marionette port probe catches stale browsers before mach launches.** An interrupted `fireforge test --headless` run can leave a `<binaryName> -marionette` child listening on port `2828` with parent PID `1`. The next `fireforge test` run — potentially in a sibling FireForge project — fails immediately with a mach Marionette bind error that points nowhere near the real cause, and the generic "delete obj-\* and rebuild" guidance wastes operator time. A new `probeMarionettePort` / `assertMarionettePortAvailable` pair in `src/core/marionette-port.ts` runs `lsof -i tcp:2828 -sTCP:LISTEN` (POSIX) or `Get-NetTCPConnection` (Windows) before every test launch; when the holder's basename or command line identifies a Firefox-family browser (including `binaryName` from `fireforge.json` for branded forks), the probe raises a targeted `GeneralError` naming the PID and the exact `kill` command. Unrelated listeners produce a softer "this is not a FireForge-launched browser" error so the operator can tell the two cases apart. The probe is best-effort: missing `lsof`/PowerShell falls back to `{ inUse: false }` rather than failing the test run itself.
+- **`fireforge lint` (default) — aggregate-mode skips tool-managed branding.** `resolveLintDiff` in `src/commands/lint.ts` passed the full `getAllDiff(engineDir)` to `lintExportedPatch` when no file list was supplied, so a fresh-setup workspace with 63 modified branding files fired `large-patch-lines`, `large-patch-files`, and `missing-license-header` on tool-managed content the operator never authored. The 2026-04-21 eval's first `fireforge lint` on a newly-built `fresh/` tree failed with blocking patch-lint errors despite the project being minimal-customisation. The aggregate-mode branch now loads `fireforge.json`'s `binaryName`, partitions the dirty tree with `isBrandingManagedPath`, and passes only the non-branding paths into `getDiffForFilesAgainstHead`. The operator sees a one-line `info()` naming the excluded count so the exclusion is visible, not silent. Explicit-path mode (`fireforge lint <path>`) preserves the previous behaviour — passing a branding path explicitly still lints it, so operators who need to audit generated branding content can do so.
+- **`fireforge doctor --repair-patches-manifest` — names every reconstructed entry.** `rebuildPatchesManifest` previously returned only the rebuilt manifest, silently overwriting `description` / `createdAt` with generic fallback values when the existing entry was missing. FireForge patch files do not carry header metadata that could carry human-written descriptions forward, so full fidelity is impossible — but at least visibility is. The helper now returns `{ manifest, recoveredFilenames }` in `src/core/patch-manifest-consistency.ts`; the doctor repair path prints a per-filename `warn(...)` telling the operator exactly which manifest entry was reconstructed from generic defaults and suggesting they edit `patches.json` if they have the original description backed up. The summary row count now reports both the total patches rebuilt and the subset that needed reconstruction.
+
 ## 0.16.0
 
-### Security — eval-driven hardening for 0.16.0
+### UX, correctness, and consistency
+
+- **`fireforge patch` / `fireforge token` — exit 0 with help (parent-command contract).** `fireforge furnace` exited 0 and printed its status message when run with no subcommand; `fireforge patch` and `fireforge token` silently inherited commander's default help-then-exit-1 path. Scripts probing the CLI surface therefore saw an inconsistent exit contract for three parent commands that do the same job (group related subcommands). Both `patch` and `token` now install a default `.action()` that prints their own help via `outputHelp()` and returns successfully — exit 0, same output shape, no destructive or stateful side effect. A new drift test in `src/commands/__tests__/manifest.test.ts` asserts every group-style parent has a default action installed so a future parent cannot regress back to the exit-1 contract silently.
+- **`fireforge furnace status` — tips now prefix with `fireforge`.** The trailing `info()` line at the end of `furnace status` said `run \`furnace status <name>\``/`furnace --help`, which only worked if the operator happened to have a separate `furnace` binary on PATH. Copy-pasting the suggestion out of FireForge's own output produced a shell error on every fresh project. The message now names the real invocation (`fireforge furnace status <name>`, `fireforge furnace --help`), so the suggested commands are directly runnable.
+- **`fireforge download` — de-duplicated git-init progress in non-TTY logs.** The resume and init `onProgress` callbacks called both `spinner.message(msg)` and `step(msg)` in non-TTY mode, producing two copies of every git-init progress line in CI logs because `src/utils/logger.ts`'s non-TTY spinner fallback already calls `p.log.step(msg)` from `message()`. The explicit `step()` sibling call is removed on both paths, so each progress message appears exactly once regardless of TTY mode. The tests in `download.test.ts` / `download.integration.test.ts` now assert the spinner-handle contract directly instead of the removed `step()` signal.
+- **`fireforge download` — honest closing message on an empty patch queue.** `download` always stopped the restore spinner with `Patch-touched files restored`, even when the project had never exported a patch — a misleading claim of work on a fresh workspace. `cleanPatchTouchedFiles` now returns a structured `{ hadQueue, restored, preserved }` result, and a new `closeRestoreSpinner` helper picks one of three stop messages: `No patches in queue — nothing to restore` (empty queue), `Patch-touched files already match baseline` (queue present, nothing dirty), or the original `Patch-touched files restored` (work actually happened).
+- **`fireforge build` — gecko-profiler bindgen hint now surfaces on Darwin 25.** The `_CharT` / `basic_string___self_view` hint had been registered in `mach-error-hints.ts` since 0.16.0 but never fired against the eval's Darwin 25 build log. Root cause: `build()` and `buildUI()` in `src/core/mach.ts` fed only `result.stderr` to `surfaceMachErrorHints`, but mach's timestamp-prefixing wrapper streamed the `rustc error[E0425]` lines through stdout. The hint surfacer now scans `${result.stderr}\n${result.stdout}` so the existing `_CharT` pattern matches regardless of which stream mach chose. A new regression test in `mach.test.ts` pins the stdout-only failure mode so a future refactor cannot accidentally narrow the capture again.
+- **`fireforge build` — new hint clarifying the post-failure `Configure complete!` epilogue.** When `mach build` fails, mach's own shutdown pipeline runs a `Config object not found by mach. / Configure complete! / Be sure to run |mach build|...` block on the way out. That block is plain upstream mach output, printed after the non-zero exit code has already been established, but it looks deceptively like a success banner. A new `MACH_ERROR_HINTS` entry matches the exact `Config object not found by mach.\s*Configure complete!` signature and surfaces `Ignore the trailing "Config object not found by mach. / Configure complete!" block — that is mach's post-failure configure summary printed after the build already failed, not a sign the build succeeded.` The pattern is narrow enough that a real post-`mach configure` success (which legitimately prints "Configure complete!" alone) does not trigger it.
+- **`fireforge wire --dry-run` — init/destroy validation now matches the real run.** Pre-0.16 the `validateWireName(expression, …)` check only ran inside `addInitToBrowserInit` / `addDestroyToBrowserInit` (the real-execution path), so `fireforge wire eval-startup --init 'void 0' --dry-run` succeeded and rendered a plausible preview — then the same arguments without `--dry-run` failed with `Invalid init expression "void 0": must contain only letters, digits, hyphens, underscores, dots, and $ signs`. Validation is now hoisted into `wireCommand` before the dry-run/real branch, so both paths enforce the identical regex. The library-level call inside addInit/addDestroy remains as defence-in-depth for programmatic callers that bypass the CLI entry point.
+- **`fireforge wire` — coerces bare property chains into function calls.** The init/destroy validator accepted both `Foo.bar` and `Foo.bar()` shapes, but the emitted code template interpolated the expression verbatim — so `fireforge wire eval-startup --init EvalStartup.init` wrote `EvalStartup.init;` (a plain property reference) into `browser-init.js`, silently producing a lifecycle hookup that never invoked the hook. A new `coerceToCall(expression)` helper in `src/core/wire-utils.ts` appends `()` when the expression lacks trailing parens, idempotent when they are already present. Both the AST (`addInitAST`/`addDestroyAST`) and legacy fallback (`legacyAddInit`/`legacyAddDestroy`) code paths route the expression through the coercer so they agree on the emitted block shape. The idempotency regex in `addInitToBrowserInit`/`addDestroyToBrowserInit` also matches against the coerced form, so re-running `wire` with the bare form is correctly a no-op against a file that already contains the coerced call. The dry-run preview (`printWireDryRun`) applies the same coercion so the preview and the real run match.
+- **`fireforge furnace create` — defensive read-back after writing `furnace.json`.** The eval observed a run where `furnace create eval-card --with-tests --localized --allow-prefix-mismatch` reported success and wrote component files under `components/custom/eval-card/`, but `furnace.json` ended up with `"custom": {}` and every subsequent command (`status`, `apply`, `rename`, `remove`) on `eval-card` failed with "not found in furnace.json". Local reproduction with the same source and same arguments writes the entry correctly and the unit-test coverage is green, so the bug could not be pinpointed from source alone. The defensive fix is a read-back verification in `performCreateMutations`: after `writeFurnaceConfig(…, config)` we call `loadFurnaceConfig(projectRoot)` and assert `componentName in persisted.custom`. If the entry is missing, the command throws a `FurnaceError` pointing to the prefix rule and `--allow-prefix-mismatch`, the rollback journal restores the pre-command state, and the operator sees the failure instead of a phantom success. The mock in `furnace-create.test.ts` was updated to reflect `writeFurnaceConfig` into subsequent `loadFurnaceConfig` reads so the unit-test path exercises the same round-trip.
+- **`fireforge token coverage` — scans deployed Furnace custom-component CSS.** Coverage discovery was git-status-based: it read `getStatusWithCodes` and filtered to `.css` files. A `moz-eval-card.css` deployed into `engine/toolkit/content/widgets/moz-eval-card/` by `furnace deploy` never appeared in the scan if it was already tracked in the engine's own git repository (i.e. not dirty in status). The command now loads `furnace.json` (when present) and walks every entry in `config.custom`, probing `${targetPath}/${componentName}.css` under the engine directory. Files that exist on disk are merged with the git-status set and de-duplicated; the tokens CSS itself is still excluded. Projects without `furnace.json` keep the old git-status-only path unchanged. A new test case in `token-coverage.test.ts` pins the augmented discovery against the eval's exact scenario.
+- **`fireforge furnace preview` — backend-artifact failure gets its own diagnosis.** When `mach storybook` failed deep inside `config.status` / `chrome-map.json` because the Firefox build backend was incomplete, the pre-0.16 heuristic's second clause matched the literal string `backend` — which does not appear in the error output — so the generic message sent the operator back to `fireforge furnace preview --install` (the wrong recovery path) after the install had already succeeded. `buildStorybookFailureMessage` is now exported and covered by a dedicated test file (`preview-failure-message.test.ts`). It first checks a narrow set of backend-artifact patterns (`chrome-map.json`, `config.status`, `obj-*/dist/bin/.lldbinit`) against a file-not-found signal; on match it produces a distinct message telling the operator to rerun `fireforge build` and wait for it to finish. The generic "missing Storybook dependencies" and fallthrough branches are preserved for the cases they actually describe.
+- **`fireforge export` / `fireforge export-all` — new `--allow-overlap` gate against silent cross-patch ownership.** Pre-0.16 `export` only caught FULL-coverage supersedes via `findAllPatchesForFiles`. A second export targeting a shared file like `browser/themes/shared/jar.inc.mn` happily created a queue where two patches both listed the same file in `filesAffected`, and `fireforge verify` then immediately failed with "cross-patch filesAffected conflicts". A new `findPartialOwnershipOverlap` helper in `export-shared.ts` walks the manifest and maps each overlapping file to its claiming patches, excluding any patches that the caller already intends to fully supersede. The new `guardOwnershipOverlap` routes the result through a non-interactive refusal or an interactive prompt: without `--allow-overlap`, the command refuses in non-interactive mode and asks for acknowledgement in interactive mode. The refusal message points at `fireforge re-export --files <paths> <patch>` as the right primitive for repartitioning ownership, which replaces the (much more dangerous) manual `patches.json` editing the eval's operator resorted to. Both `export` and `export-all` now expose a matching `--allow-overlap` flag.
+- **`fireforge re-export --scan` — broad expansions require explicit acknowledgement.** Pre-0.16 `--scan` blindly merged every modified or untracked file in a patch's parent directories into its `filesAffected`. The eval scenario: two small patches in adjacent-but-unrelated features shared a directory tree, and a single `re-export --all --scan` silently absorbed the entire neighbour feature (xhtml + xpcshell tests + theme CSS) into the wrong patch. The 0.16.0 gate: when `--scan` would add more than three files, or files spanning more than one directory, the command calls `confirmBroadScanAdditions` — dry-run proceeds silently (previewing is the whole point), `--yes` proceeds silently (the explicit opt-in), interactive mode prompts for confirmation, and non-interactive mode without `--yes` refuses with the expansion summary. Small same-directory additions (the common refresh case) stay frictionless.
+- **`fireforge test --doctor` — closes the intro frame with an explicit outro.** Running `test --doctor` on its own showed `●  Running marionette preflight...` and then exited silently with code 0 in the eval's non-TTY capture — the `Marionette preflight: PASS (…)` line that `reportMarionettePreflight` emitted via `info()` failed to render inside the unclosed clack intro frame. The doctor-only success branch now calls `outro(\`Marionette preflight: PASS (${durationMs}ms)\`)`before returning, which closes the tree and gives scripts a deterministic "done" marker to parse. The failing branch already throws through`GeneralError`, which is routed via the standard error pipeline and does not need the same treatment.
+- **`fireforge run --smoke-exit` — allowlist summary shows both error-class and total counts.** The previous summary only reported `Allowlisted hits: N`, where `N` was incremented only when a line matched both `SMOKE_ERROR_PATTERNS` AND the caller-supplied allowlist. An operator whose `--console-allow RSLoader:` pattern visibly matched `console.warn: RSLoader: …` lines still saw `Allowlisted hits: 0`, because `console.warn:` is not a smoke-error class — the allowlist was never consulted for those lines. The summary now distinguishes two counters: `Allowlisted error hits (suppressed): N` (the exit-contract number: errors the allowlist kept out of the findings list) and `Allowlisted lines total: M` (the mental-model number: every console line that matched the allowlist, regardless of error class). The exit contract itself is unchanged — unallowed errors still fail the smoke window.
+- **`fireforge resolve` — `filesAffected` is always recomputed from the new diff body.** Pre-0.16 the resolve command updated `patches.json.filesAffected` only when `activeFiles.length < existingFiles.length` (files deleted from disk). If the user's manual fix eliminated every hunk for a specific file while the file itself still existed on disk, the metadata kept claiming it — and the next `fireforge import` immediately failed the patch-manifest consistency check with "patches.json declares [...] but the patch file targets [...]". The command now threads the generated `diffContent` through `extractAffectedFiles` (the same helper `export` and the consistency checker use) and unconditionally passes the result as `filesAffected`. Resolve and consistency-check therefore always agree on the set of targeted files. A new round-trip test in `resolve.test.ts` pins the scenario where the diff shrinks but every file still exists on disk.
+
+### Security
 
 - **Release workflow — shell injection via `${{ inputs.version }}` interpolation.** `.github/workflows/release.yml` previously interpolated `${{ inputs.version }}` directly into `npm version "${{ inputs.version }}" --no-git-tag-version`, so anyone with `actions:write` could trigger `workflow_dispatch` with a crafted version string (e.g. `1.0.0"; <command> #`) and execute arbitrary shell inside the job. The release job carries `contents: write`, `id-token: write`, and the `npm` trusted-publishing environment, so that shell would have had an open door to the publish credentials. The fix routes `${{ inputs.version }}` through an `env: INPUT_VERSION:` block on the `Bump version` step and references `"$INPUT_VERSION"` inside the `run:` script, so GitHub Actions substitutes the value into the process environment rather than into the shell source. The `Tag and push` step gets the same treatment for `${{ steps.version.outputs.version }}` — defense-in-depth, since `npm version`'s semver check already filters that interpolation, but the pattern is consistent and cheap.
 - **`fireforge config` — prototype pollution via sentinel key segments.** `mutateConfig` in `src/core/config-mutate.ts` walks a dot-separated key through `getOrCreateChildRecord(parent, segment)` with no filter on `__proto__`, `constructor`, or `prototype`. `fireforge config __proto__.polluted 1 --force` therefore reached `parent["__proto__"]` and wrote a plain property onto `Object.prototype`, polluting every object in the Node process for the rest of the run. `--force` was the motivating pathway (the strict path guard rejects unknown top-level keys for non-sentinels), but the raw sink was also publicly re-exported from `src/core/config.ts`, widening the blast radius to any future caller. The fix rejects sentinel segments up-front in `mutateConfig` with a `ConfigError` before any clone or mutation — a single guard at the entry point covers both the descent loop and the final leaf assignment, and surfaces to the CLI as a normal "invalid key" failure rather than a crash. `readJson`'s existing reviver already strips the sentinels from loads, so input configs can't arrive pre-polluted.

package/README.md

@@ -154,6 +154,10 @@ fireforge re-export --files browser/base/content/browser.js 002-ui-toolbar
 fireforge re-export --all --scan --stamp
 ```
 
+`export` refuses when the new patch's `filesAffected` would overlap with files already claimed by another non-superseded patch. Repartitioning ownership is a deliberate operation: the message points at `fireforge re-export --files <paths> <patch>` as the safe primitive. Pass `--allow-overlap` to acknowledge the conflict and proceed anyway — the resulting queue will fail `fireforge verify` immediately, so this is an intentional escape hatch, not a default.
+
+`re-export --scan` also prompts before broadening a patch with more than a handful of newly discovered files or with files spanning multiple directories. The gate keeps the common refresh case frictionless (small, same-directory additions) while catching the failure mode where `--scan` silently pulls an adjacent feature into the wrong patch. Non-interactive mode requires `--yes` to acknowledge a broad expansion; dry-run previews never require confirmation.
+
 ### Rebasing on top of a new Firefox version
 
 1. Update `firefox.version` in `fireforge.json`
@@ -170,7 +174,7 @@ When `fireforge import` fails on a patch, fix the `.rej` files in `engine/`, the
 fireforge resolve
 ```
 
-This re-exports the fixed patch and continues applying the remaining stack.
+This re-exports the fixed patch and clears the conflict state. The command is deliberately a single-patch refresh — to continue applying the remainder of the queue, run `fireforge import` afterwards. For scripted or CI-driven recovery, pass `--yes` (or `-y`) to skip the interactive "are you done?" prompt; the flag is the explicit opt-in for non-interactive use once the manual merge is complete.
 
 <details>
 <summary>Patch manifest format</summary>
@@ -207,7 +211,7 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 `fireforge lint` runs automatically during export, export-all and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
 
-By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed. 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; the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
+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                 |
 | ------------------------------ | ------------------------------------------------------------------------- | ------------------------ |
@@ -405,6 +409,8 @@ fireforge config firefox.version 145.0.0esr
 fireforge config customKey "value" --force
 ```
 
+Writes are serialised behind a sidecar lock — two concurrent `fireforge config` invocations against the same `fireforge.json` (for example, parallel automation steps) queue instead of racing the read-modify-write. The lock is released automatically on process exit; stale locks from a crashed earlier command are reclaimed on the next invocation via the PID-alive probe.
+
 ### Patch queue management
 
 ```bash
@@ -436,7 +442,7 @@ fireforge watch
 fireforge token add --category 'Colors — General' -- --my-color 'light-dark(#fff, #000)'
 ```
 
-Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` also registers the tokens CSS path in `patchLint.rawColorAllowlist` so raw color literals inside it are not flagged by `fireforge lint`.
+Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` also registers the tokens CSS path in `patchLint.rawColorAllowlist` so raw color literals inside it are not flagged by `fireforge lint`, and derives `tokenPrefix: --<binaryName>-` from `fireforge.json`'s `binaryName` so `fireforge token coverage` has a prefix to key off on the very first run. Projects that prefer a different prefix can override it in `furnace.json` after init.
 
 ### Diff-scoped lint (`lint --since`)
 
@@ -592,6 +598,8 @@ Exit codes are wired distinct from `BUILD_ERROR`:
 
 POSIX only — process-group semantics do not map cleanly onto Windows. A smoke window shorter than 30 s warns up-front because cold-start time alone can consume that budget on a debug build; `--capture-console <file>` mirrors the captured stream so post-exit inspection has the raw log without re-running.
 
+The summary block reports two allowlist counters so operators can tell whether a pattern actually matched anything: `Allowlisted error hits (suppressed)` is the exit-contract number (errors that would have failed the window but were dropped by the allowlist), and `Allowlisted lines total` is the mental-model number (every console line that matched the allowlist, regardless of whether it was an error-class line). A non-zero `total` with a zero `suppressed` count means the allowlist patterns matched benign info/warn lines that never counted toward the exit contract to begin with.
+
 ### Furnace `--shared-ftl` for feature-scoped Fluent bundles
 
 A feature with multiple components (e.g. an eight-component dock) typically wants one shared `.ftl` per feature rather than eight per-component stubs. `furnace create <tag> --localized --shared-ftl <chrome-uri>` participates in an existing feature-scoped bundle:

package/dist/src/commands/build.js

@@ -5,7 +5,7 @@ import { auditBuildArtifacts } from '../core/build-audit.js';
 import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, runMach, } from '../core/mach.js';
+import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, runMach, withBuildLock, } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -129,12 +129,21 @@ export async function buildCommand(projectRoot, options) {
     const startTime = Date.now();
     let exitCode;
     try {
-        if (options.ui) {
-            exitCode = await buildUI(paths.engine);
-        }
-        else {
-            exitCode = await build(paths.engine, jobs);
-        }
+        // Hold the per-project build lock across the mach invocation so two
+        // overlapping `fireforge build` / `fireforge build --ui` commands
+        // against the same engine tree serialise instead of racing through
+        // the same obj-*. 2026-04-21 eval: a `build --ui` launched during
+        // an in-progress full build hit `No rule to make target 'XUL'` in
+        // mach, which is the downstream consequence of an incomplete
+        // 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 () => {
+            if (options.ui) {
+                return buildUI(paths.engine);
+            }
+            return build(paths.engine, jobs);
+        });
     }
     catch (error) {
         throw new BuildError('Build process failed to start', options.ui ? 'mach build faster' : 'mach build', error instanceof Error ? error : undefined);

package/dist/src/commands/config.js

@@ -1,4 +1,4 @@
-import { configExists, loadConfig, loadRawConfigDocument, mutateConfig, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, writeConfig, writeConfigDocument, } from '../core/config.js';
+import { configExists, loadConfig, loadRawConfigDocument, mutateConfig, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, withConfigFileLock, writeConfig, writeConfigDocument, } from '../core/config.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
@@ -112,25 +112,37 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         const parsedValue = parseValue(value, key);
         const keyIsKnown = SUPPORTED_CONFIG_PATHS.includes(key);
         try {
-            // `--force` is intended as an escape hatch for *unknown* keys; it
-            // should not also let the user write a structurally invalid value
-            // for a *known* key. Apply strict validation whenever the key is
-            // listed in SUPPORTED_CONFIG_PATHS, regardless of --force, and only
-            // skip validation for genuinely unknown key paths.
-            if (options.force && !keyIsKnown) {
-                // Seed mutation from the raw on-disk document so previously-forced
-                // keys (which `validateConfig` would strip) survive the round-trip.
-                // Without this, writing a second --force key would silently drop
-                // every earlier forced key from fireforge.json.
-                const rawConfig = await loadRawConfigDocument(projectRoot);
-                const updatedConfig = mutateConfig(rawConfig, key, parsedValue, true);
-                await writeConfigDocument(projectRoot, updatedConfig);
-            }
-            else {
-                const config = await loadConfig(projectRoot);
-                const updatedConfig = mutateConfig(config, key, parsedValue);
-                await writeConfig(projectRoot, updatedConfig);
-            }
+            // Serialise the read → mutate → write round-trip behind the sidecar
+            // config lock so two concurrent `fireforge config` invocations can't
+            // each read the pre-state, mutate their own copy, and clobber each
+            // other on write. Before the lock, the 2026-04-21 eval reproduced
+            // silent data loss with two parallel `fireforge config <key>
+            // <value>` commands writing different keys: both exited 0, one key
+            // survived, the other vanished. Atomic file writes (temp + rename)
+            // were never enough on their own — the lost update happens before
+            // the rename, inside the read-modify step. Readers stay lock-free
+            // (see `withConfigFileLock` docstring).
+            await withConfigFileLock(projectRoot, async () => {
+                // `--force` is intended as an escape hatch for *unknown* keys; it
+                // should not also let the user write a structurally invalid value
+                // for a *known* key. Apply strict validation whenever the key is
+                // listed in SUPPORTED_CONFIG_PATHS, regardless of --force, and only
+                // skip validation for genuinely unknown key paths.
+                if (options.force && !keyIsKnown) {
+                    // Seed mutation from the raw on-disk document so previously-forced
+                    // keys (which `validateConfig` would strip) survive the round-trip.
+                    // Without this, writing a second --force key would silently drop
+                    // every earlier forced key from fireforge.json.
+                    const rawConfig = await loadRawConfigDocument(projectRoot);
+                    const updatedConfig = mutateConfig(rawConfig, key, parsedValue, true);
+                    await writeConfigDocument(projectRoot, updatedConfig);
+                }
+                else {
+                    const config = await loadConfig(projectRoot);
+                    const updatedConfig = mutateConfig(config, key, parsedValue);
+                    await writeConfig(projectRoot, updatedConfig);
+                }
+            });
         }
         catch (error) {
             throw new InvalidArgumentError(`Invalid value for "${key}": ${toError(error).message}`, key);

package/dist/src/commands/doctor.js

@@ -314,7 +314,20 @@ const DOCTOR_CHECKS = [
             }
             try {
                 const repaired = await rebuildPatchesManifest(ctx.paths.patches, ctx.config.firefox.version);
-                return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.patches.length} patch${repaired.patches.length === 1 ? '' : 'es'}. Review recovered metadata before release.`);
+                // 2026-04-21 eval (Finding #17): the repair path silently
+                // overwrote useful human-written descriptions on recovered
+                // entries, leaving the queue less trustworthy as an audit
+                // trail. The rebuilder now returns the list of filenames
+                // whose metadata was entirely invented, and we name them
+                // explicitly here so the operator knows exactly which
+                // patches to review. Names that DID have a preserved entry
+                // (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.`);
+                    }
+                }
+                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.`);
             }
             catch (err) {
                 return failure('Patch manifest consistency', toError(err).message, 'Repair failed. Fix the underlying patch metadata issue and retry the doctor command.');

package/dist/src/commands/download.js

@@ -10,7 +10,7 @@ import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { EngineExistsError, PartialEngineExistsError } from '../errors/download.js';
 import { toError } from '../utils/errors.js';
 import { checkDiskSpace, ensureDir, pathExists, removeDir } from '../utils/fs.js';
-import { info, intro, outro, spinner, step, verbose, warn } from '../utils/logger.js';
+import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 /**
  * Collects the set of patch-touched files from the manifest.
@@ -39,11 +39,13 @@ async function getPatchTouchedFiles(patchesDir) {
  */
 async function cleanPatchTouchedFiles(engineDir, patchesDir, preExistingDirty) {
     const patchFiles = await getPatchTouchedFiles(patchesDir);
-    if (patchFiles.size === 0)
-        return;
+    if (patchFiles.size === 0) {
+        return { hadQueue: false, restored: 0, preserved: 0 };
+    }
     const dirtyFiles = await getDirtyFiles(engineDir, [...patchFiles]);
-    if (dirtyFiles.length === 0)
-        return;
+    if (dirtyFiles.length === 0) {
+        return { hadQueue: true, restored: 0, preserved: 0 };
+    }
     const toClean = preExistingDirty
         ? dirtyFiles.filter((f) => !preExistingDirty.has(f))
         : dirtyFiles;
@@ -65,6 +67,29 @@ async function cleanPatchTouchedFiles(engineDir, patchesDir, preExistingDirty) {
             warn(`  ${file}`);
         }
     }
+    return { hadQueue: true, restored: toClean.length, preserved: preserved.length };
+}
+/**
+ * Stops `restoreSpinner` with a message that reflects what actually
+ * happened. Three branches: empty queue → explicit no-op; queue present but
+ * nothing dirty → "already clean"; queue with dirty files → the usual
+ * "Patch-touched files restored" success line.
+ *
+ * Before 0.16.0 the spinner always closed with "Patch-touched files
+ * restored", so a fresh project with zero patches saw a claim of restore
+ * work that had not happened — misleading and easy to mistake for a
+ * silent retry.
+ */
+function closeRestoreSpinner(restoreSpinner, result) {
+    if (!result.hadQueue) {
+        restoreSpinner.stop('No patches in queue — nothing to restore');
+        return;
+    }
+    if (result.restored === 0 && result.preserved === 0) {
+        restoreSpinner.stop('Patch-touched files already match baseline');
+        return;
+    }
+    restoreSpinner.stop('Patch-touched files restored');
 }
 /**
  * Runs the download command.
@@ -100,11 +125,16 @@ export async function downloadCommand(projectRoot, options) {
                         const resumeSpinner = spinner('Resuming git repository initialization...');
                         try {
                             await resumeRepository(paths.engine, {
+                                // The non-TTY spinner fallback in `src/utils/logger.ts`
+                                // already calls `p.log.step(msg)` from `message()`, so
+                                // forwarding the progress message is the single authority
+                                // in both TTY and non-TTY modes. Before 0.16.0 this
+                                // callback also invoked `step(message)` explicitly when
+                                // stdio was not a TTY, which printed the same step line
+                                // twice in CI logs (once from the fallback, once from
+                                // the explicit call).
                                 onProgress: (message) => {
                                     resumeSpinner.message(message);
-                                    if (!(process.stdout.isTTY && process.stderr.isTTY)) {
-                                        step(message);
-                                    }
                                 },
                             });
                             const baseCommit = await getHead(paths.engine);
@@ -223,11 +253,12 @@ export async function downloadCommand(projectRoot, options) {
     let baseCommit;
     try {
         await initRepository(paths.engine, 'firefox', {
+            // Same one-authority rule as the resume path above: the non-TTY
+            // spinner fallback already emits `step(msg)` internally, so
+            // calling `step()` in addition to `.message()` duplicated every
+            // git-init progress line in CI logs.
             onProgress: (message) => {
                 gitSpinner.message(message);
-                if (!(process.stdout.isTTY && process.stderr.isTTY)) {
-                    step(message);
-                }
             },
         });
         baseCommit = await getHead(paths.engine);
@@ -257,8 +288,8 @@ export async function downloadCommand(projectRoot, options) {
     // reporting success against a dirty engine.
     const restoreSpinner = spinner('Restoring patch-touched files to baseline...');
     try {
-        await cleanPatchTouchedFiles(paths.engine, paths.patches);
-        restoreSpinner.stop('Patch-touched files restored');
+        const restoreResult = await cleanPatchTouchedFiles(paths.engine, paths.patches);
+        closeRestoreSpinner(restoreSpinner, restoreResult);
     }
     catch (error) {
         restoreSpinner.error('Failed to restore patch-touched files');

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

@@ -7,14 +7,14 @@ import { hasChanges, isGitRepository } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getWorkingTreeStatus } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { commitExportedPatch } from '../core/patch-export.js';
+import { commitExportedPatch, findAllPatchesForFiles } from '../core/patch-export.js';
 import { buildPatchQueueContext, collectNewFileCreatorsByPath, detectNewFilesInDiff, } from '../core/patch-lint.js';
 import { GeneralError } from '../errors/base.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { PATCH_CATEGORIES } from '../utils/validation.js';
-import { autoFixLicenseHeaders, confirmSupersedePatches, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
+import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
 async function checkBrandingManagedFiles(paths, config) {
     const changedFiles = await getWorkingTreeStatus(paths.engine);
     const brandingManagedFiles = changedFiles
@@ -177,6 +177,22 @@ export async function exportAllCommand(projectRoot, options = {}) {
         const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
         if (!shouldProceed)
             return;
+        // Overlap gate — see the matching comment in `export.ts`. The same
+        // cross-patch ownership problem applies to `export-all` because a
+        // mixed aggregate diff often touches shared files like manifest
+        // fragments that other patches already claim.
+        const willSupersede = await findAllPatchesForFiles(paths.patches, filesAffected);
+        const supersedingFilenames = new Set(willSupersede.map((p) => p.filename));
+        const shouldProceedPastOverlap = await guardOwnershipOverlap({
+            patchesDir: paths.patches,
+            filesAffected,
+            supersedingFilenames,
+            allowOverlap: options.allowOverlap === true,
+            isInteractive,
+            s,
+        });
+        if (!shouldProceedPastOverlap)
+            return;
         // Get Firefox version for metadata
         const { patchFilename, superseded } = await commitExportedPatch({
             patchesDir: paths.patches,
@@ -213,6 +229,7 @@ export function registerExportAll(program, { getProjectRoot, withErrorHandling }
         .option('--supersede', 'Allow superseding multiple existing patches')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--exclude-furnace', 'Export the non-Furnace subset of the aggregate diff instead of refusing when Furnace-managed files are modified. Furnace-managed files are still deployed by "fireforge furnace apply"; this flag only changes whether export-all aborts or filters in their presence.')
+        .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap with non-superseded patches (the resulting queue fails verify)')
         .action(withErrorHandling(async (options) => {
         const { category, ...rest } = options;
         await exportAllCommand(getProjectRoot(), {

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

@@ -1,3 +1,4 @@
+import type { PatchesManifest } from '../types/commands/index.js';
 import type { ExportOptions, PatchCategory } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import type { SpinnerHandle } from '../utils/logger.js';
@@ -52,3 +53,38 @@ export declare function confirmSupersedePatches(patchesDir: string, filesAffecte
  * @returns true if files were modified on disk (caller must regenerate diff)
  */
 export declare function autoFixLicenseHeaders(engineDir: string, diffContent: string, config: FireForgeConfig, isInteractive: boolean): Promise<boolean>;
+/**
+ * Maps every file in `filesAffected` to the existing patches that already
+ * claim ownership of it, excluding the caller's own patch (when `newFilename`
+ * is provided) and any patches that the caller intends to fully supersede.
+ *
+ * Returns an empty map when no overlap exists. Used by the overlap gate in
+ * `export` and `export-all` to refuse a default-mode export that would
+ * silently create cross-patch ownership conflicts — the same class of
+ * conflict `verify` immediately fails with.
+ */
+export declare function findPartialOwnershipOverlap(manifest: PatchesManifest, filesAffected: string[], excludeFilenames: ReadonlySet<string>): Map<string, string[]>;
+/**
+ * Gate that refuses the default export path when the new patch would
+ * silently claim files that are already tracked by other non-superseded
+ * patches. `findAllPatchesForFiles` already catches the full-coverage
+ * supersede case — this helper fills the gap for partial overlap, which
+ * was the eval finding #12 scenario (two patches both claiming
+ * `browser/themes/shared/jar.inc.mn` after a second export with
+ * `--before`).
+ *
+ * Proceeds silently when there is no overlap, or when the caller passed
+ * `--allow-overlap`. In interactive mode the caller is prompted to
+ * acknowledge the overlap (the proper fix path is `re-export --files` to
+ * repartition ownership, so the prompt surfaces that pointer). In
+ * non-interactive mode the function throws — better to fail fast than
+ * let the queue fall out of sync with verify.
+ */
+export declare function guardOwnershipOverlap(args: {
+    patchesDir: string;
+    filesAffected: string[];
+    supersedingFilenames: ReadonlySet<string>;
+    allowOverlap: boolean;
+    isInteractive: boolean;
+    s: SpinnerHandle;
+}): Promise<boolean>;

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

@@ -4,6 +4,7 @@ import { confirm, select, text } from '@clack/prompts';
 import { addLicenseHeaderToFile, getLicenseHeader } from '../core/license-headers.js';
 import { findAllPatchesForFiles } from '../core/patch-export.js';
 import { commentStyleForFile, detectNewFilesInDiff, lintExportedPatch, } from '../core/patch-lint.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
@@ -222,4 +223,79 @@ export async function autoFixLicenseHeaders(engineDir, diffContent, config, isIn
     }
     return true;
 }
+/**
+ * Maps every file in `filesAffected` to the existing patches that already
+ * claim ownership of it, excluding the caller's own patch (when `newFilename`
+ * is provided) and any patches that the caller intends to fully supersede.
+ *
+ * Returns an empty map when no overlap exists. Used by the overlap gate in
+ * `export` and `export-all` to refuse a default-mode export that would
+ * silently create cross-patch ownership conflicts — the same class of
+ * conflict `verify` immediately fails with.
+ */
+export function findPartialOwnershipOverlap(manifest, filesAffected, excludeFilenames) {
+    const overlap = new Map();
+    const targetSet = new Set(filesAffected);
+    for (const patch of manifest.patches) {
+        if (excludeFilenames.has(patch.filename))
+            continue;
+        for (const file of patch.filesAffected) {
+            if (!targetSet.has(file))
+                continue;
+            const owners = overlap.get(file) ?? [];
+            owners.push(patch.filename);
+            overlap.set(file, owners);
+        }
+    }
+    return overlap;
+}
+/**
+ * Gate that refuses the default export path when the new patch would
+ * silently claim files that are already tracked by other non-superseded
+ * patches. `findAllPatchesForFiles` already catches the full-coverage
+ * supersede case — this helper fills the gap for partial overlap, which
+ * was the eval finding #12 scenario (two patches both claiming
+ * `browser/themes/shared/jar.inc.mn` after a second export with
+ * `--before`).
+ *
+ * Proceeds silently when there is no overlap, or when the caller passed
+ * `--allow-overlap`. In interactive mode the caller is prompted to
+ * acknowledge the overlap (the proper fix path is `re-export --files` to
+ * repartition ownership, so the prompt surfaces that pointer). In
+ * non-interactive mode the function throws — better to fail fast than
+ * let the queue fall out of sync with verify.
+ */
+export async function guardOwnershipOverlap(args) {
+    const { patchesDir, filesAffected, supersedingFilenames, allowOverlap, isInteractive, s } = args;
+    if (allowOverlap)
+        return true;
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return true;
+    const overlap = findPartialOwnershipOverlap(manifest, filesAffected, supersedingFilenames);
+    if (overlap.size === 0)
+        return true;
+    s.stop();
+    const entries = [...overlap.entries()].sort(([a], [b]) => a.localeCompare(b));
+    warn(`This export would create cross-patch ownership overlap on ${String(entries.length)} file${entries.length === 1 ? '' : 's'}:`);
+    for (const [file, owners] of entries) {
+        warn(`  - ${file} already claimed by: ${owners.join(', ')}`);
+    }
+    warn('The queue would fail `fireforge verify` immediately after this export. ' +
+        'To repartition ownership safely, run `fireforge re-export --files <paths> <existing-patch>` ' +
+        'on the overlapping patches first, then re-run the export.');
+    if (!isInteractive) {
+        throw new GeneralError('Refusing to export a queue with cross-patch ownership overlap in non-interactive mode. ' +
+            'Pass --allow-overlap to acknowledge the conflict, or repartition ownership via `fireforge re-export --files`.');
+    }
+    const confirmed = await confirm({
+        message: 'Proceed with overlapping ownership? This will leave the queue in a verify-failing state.',
+        initialValue: false,
+    });
+    if (isCancel(confirmed) || !confirmed) {
+        cancel('Export cancelled');
+        return false;
+    }
+    return true;
+}
 //# sourceMappingURL=export-shared.js.map