@hominis/fireforge 0.16.3 → 0.16.5

package/CHANGELOG.md

@@ -2,7 +2,26 @@
 
 ## 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`
@@ -592,6 +596,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/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

package/dist/src/commands/export.js

@@ -10,7 +10,7 @@ import { generateBinaryFilePatch, generateFullFilePatch } from '../core/git-diff
 import { isBinaryFile } from '../core/git-file-ops.js';
 import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } 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 { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
@@ -19,7 +19,7 @@ import { pickDefined } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag, PATCH_CATEGORIES } from '../utils/validation.js';
 import { commitPlacementExport, placementSummary, projectPlacementForLint, renderDryRunPreview, resolvePlacementPlan, } from './export-flow.js';
-import { autoFixLicenseHeaders, confirmSupersedePatches, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
+import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
 async function collectExportFiles(paths, files) {
     const collectedFiles = new Set();
     let fileStatuses;
@@ -286,6 +286,26 @@ export async function exportCommand(projectRoot, files, options) {
         const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
         if (!shouldProceed)
             return;
+        // Overlap gate: pre-0.16.0 `export` only caught FULL-coverage
+        // supersedes, so 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`. `verify`
+        // then failed immediately on "cross-patch filesAffected conflicts".
+        // `confirmSupersedePatches` might already have confirmed full
+        // supersedes above; pass their filenames through so we do not flag
+        // a file claimed by a patch that is about to be removed.
+        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;
         const { patchFilename, superseded } = await commitExportedPatch({
             patchesDir: paths.patches,
             category: selectedCategory,
@@ -327,6 +347,7 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('-y, --yes', 'Skip confirmation for placement renumbers (required for non-TTY)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal on projected placement')
         .option('--exclude-furnace', 'Exclude furnace-managed file paths from the export')
+        .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap (default mode only; the resulting queue fails verify)')
         .action(withErrorHandling(async (paths, options) => {
         const { category, ...rest } = options;
         await exportCommand(getProjectRoot(), paths, {

package/dist/src/commands/furnace/create-readback.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Defensive read-back helper for `furnace create`. Extracted from
+ * `create.ts` so the authoring command stays under the per-file LOC
+ * budget.
+ */
+/**
+ * Asserts that the just-written furnace.json contains the expected
+ * custom component entry. The eval run's finding #9 observed a
+ * scenario where `furnace create --allow-prefix-mismatch` reported
+ * success and wrote the component files, but the subsequent
+ * `furnace status` found `custom: {}` in furnace.json — an invariant
+ * violation with no clear smoking gun in the code path. Local repros
+ * do not trigger it, so the defensive readback is the safest recovery
+ * contract we can offer: if the new entry is not visible on the next
+ * load, throw a `FurnaceError` so the rollback journal restores the
+ * pre-command state and the operator sees the failure instead of a
+ * phantom success.
+ *
+ * @param projectRoot - Root of the FireForge project
+ * @param componentName - Custom-element tag name that must be present
+ *   in `config.custom` after the write. Throws when absent.
+ */
+export declare function assertCustomEntryPersisted(projectRoot: string, componentName: string): Promise<void>;

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

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Defensive read-back helper for `furnace create`. Extracted from
+ * `create.ts` so the authoring command stays under the per-file LOC
+ * budget.
+ */
+import { loadFurnaceConfig } from '../../core/furnace-config.js';
+import { FurnaceError } from '../../errors/furnace.js';
+/**
+ * Asserts that the just-written furnace.json contains the expected
+ * custom component entry. The eval run's finding #9 observed a
+ * scenario where `furnace create --allow-prefix-mismatch` reported
+ * success and wrote the component files, but the subsequent
+ * `furnace status` found `custom: {}` in furnace.json — an invariant
+ * violation with no clear smoking gun in the code path. Local repros
+ * do not trigger it, so the defensive readback is the safest recovery
+ * contract we can offer: if the new entry is not visible on the next
+ * load, throw a `FurnaceError` so the rollback journal restores the
+ * pre-command state and the operator sees the failure instead of a
+ * phantom success.
+ *
+ * @param projectRoot - Root of the FireForge project
+ * @param componentName - Custom-element tag name that must be present
+ *   in `config.custom` after the write. Throws when absent.
+ */
+export async function assertCustomEntryPersisted(projectRoot, componentName) {
+    const persisted = await loadFurnaceConfig(projectRoot);
+    if (!(componentName in persisted.custom)) {
+        throw new FurnaceError(`Wrote furnace.json but "${componentName}" is missing from config.custom on read-back. ` +
+            'This should not happen — please report the issue. As a workaround, ' +
+            're-run the command, or add the entry to furnace.json by hand.', componentName);
+    }
+}
+//# sourceMappingURL=create-readback.js.map

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

@@ -19,6 +19,7 @@ import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils
 import { formatDryRunPlan, formatSuccessNote } from './create-dry-run.js';
 import { resolveCreateFeatures } from './create-features.js';
 import { scaffoldMochikitTestFiles } from './create-mochikit.js';
+import { assertCustomEntryPersisted } from './create-readback.js';
 import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
 import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
 async function loadAuthoringFurnaceConfig(projectRoot) {
@@ -266,6 +267,7 @@ async function performCreateMutations(args) {
         args.config.custom[args.componentName] = customEntry;
         await snapshotFile(journal, args.furnacePaths.furnaceConfig);
         await writeFurnaceConfig(args.projectRoot, args.config);
+        await assertCustomEntryPersisted(args.projectRoot, args.componentName);
         if (args.testStyle === 'browser-chrome') {
             const scafFiles = await scaffoldTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
             testFiles.push(...scafFiles);

package/dist/src/commands/furnace/preview.d.ts

@@ -1,4 +1,16 @@
 import type { FurnacePreviewOptions } from '../../types/commands/index.js';
+/**
+ * Builds a targeted Storybook failure message from captured mach output.
+ *
+ * Exported for the test suite: the heuristic has three branches (backend
+ * artifact missing, Storybook dep missing, generic) and regression
+ * testing each is easier when the classifier is addressable directly.
+ *
+ * @param output - Combined stdout and stderr from the Storybook command
+ * @param installRequested - Whether the caller requested a dependency reinstall first
+ * @returns User-facing guidance for the specific failure mode
+ */
+export declare function buildStorybookFailureMessage(output: string, installRequested: boolean): string;
 /**
  * Runs the furnace preview command to start Storybook for component preview.
  * @param projectRoot - Root directory of the project

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

@@ -72,17 +72,49 @@ function reportPreviewStagingFailures(stageResult) {
     const totalFailures = stageResult.errors.length + appliedWithStepErrorsCount;
     throw new FurnaceError(`${totalFailures} component${totalFailures === 1 ? '' : 's'} failed to stage for preview`);
 }
+/**
+ * Filenames emitted by the Firefox build backend (not by Storybook's npm
+ * package set) — their absence means `mach build` has not produced its
+ * post-configure artifacts, which is a different failure mode from a
+ * missing Storybook workspace dependency tree. The eval log for finding
+ * #11 reported `FileNotFoundError: [...] chrome-map.json` *after* a
+ * successful Storybook `npm install`, and the pre-0.16 heuristic
+ * misdiagnosed it as a dep failure and sent the operator back to
+ * `--install`. Pattern list is narrow on purpose so we only surface the
+ * backend-rebuild hint when we are confident.
+ */
+const BACKEND_ARTIFACT_PATTERNS = [
+    /chrome-map\.json/i,
+    /config\.status/i,
+    /obj-[^\s/]+\/dist\/bin\/\.lldbinit/i,
+];
 /**
  * Builds a targeted Storybook failure message from captured mach output.
+ *
+ * Exported for the test suite: the heuristic has three branches (backend
+ * artifact missing, Storybook dep missing, generic) and regression
+ * testing each is easier when the classifier is addressable directly.
+ *
  * @param output - Combined stdout and stderr from the Storybook command
  * @param installRequested - Whether the caller requested a dependency reinstall first
  * @returns User-facing guidance for the specific failure mode
  */
-function buildStorybookFailureMessage(output, installRequested) {
+export function buildStorybookFailureMessage(output, installRequested) {
     const installHint = installRequested
         ? 'Try running "python3 ./mach storybook upgrade" manually in the engine directory.'
         : 'Run "fireforge furnace preview --install" to bootstrap Storybook dependencies, or run "python3 ./mach storybook upgrade" manually in engine/.';
-    if (/(ENOENT|No such file or directory)/i.test(output) && /storybook|backend/i.test(output)) {
+    const hasFileNotFoundSignal = /(ENOENT|No such file or directory|FileNotFoundError)/i.test(output);
+    // Check backend-artifact signal first — a missing chrome-map.json looks
+    // like any other "No such file" error to a naïve regex, but the fix is
+    // to rerun `fireforge build`, not to reinstall Storybook dependencies.
+    if (hasFileNotFoundSignal && BACKEND_ARTIFACT_PATTERNS.some((p) => p.test(output))) {
+        return ('Storybook failed because the Firefox build backend artifacts are missing or stale ' +
+            '(chrome-map.json / config.status / obj-*/dist/bin/.lldbinit). ' +
+            'This is a Firefox-build completeness issue, not a Storybook dependency issue.\n\n' +
+            'Rerun "fireforge build" and let it finish, then retry "fireforge furnace preview". ' +
+            'A full rebuild regenerates the backend artifacts Storybook reads.');
+    }
+    if (hasFileNotFoundSignal && /storybook|backend/i.test(output)) {
         return ('Storybook failed because the Firefox checkout appears to be missing Storybook workspace files or backend dependencies.\n\n' +
             installHint);
     }

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

@@ -196,7 +196,7 @@ export async function furnaceStatusCommand(projectRoot, name) {
             warn('Engine drift detected since last apply (reset/download/manual edit). Run `fireforge furnace apply` to re-deploy.');
         }
     }
-    info('Tip: run `furnace status <name>` for detailed component info, or `furnace --help` for all subcommands.');
+    info('Tip: run `fireforge furnace status <name>` for detailed component info, or `fireforge furnace --help` for all subcommands.');
     outro('Status complete');
 }
 //# sourceMappingURL=status.js.map

package/dist/src/commands/patch/index.js

@@ -20,7 +20,16 @@ export { patchReorderCommand } from './reorder.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (compact, delete, reorder)');
+        .description('Manage individual patches in the queue (compact, delete, reorder)')
+        // Match `fireforge furnace`'s no-args contract: print the group's help and
+        // exit 0. Without this default action, commander routes `fireforge patch`
+        // (no subcommand) through its own help-then-exit-1 path, so scripts that
+        // probe the CLI surface see a misleading non-zero exit for a purely
+        // informational invocation. The action prints the exact same help commander
+        // would otherwise print, but returns successfully.
+        .action(() => {
+        patch.outputHelp();
+    });
     registerPatchCompact(patch, context);
     registerPatchDelete(patch, context);
     registerPatchReorder(patch, context);