@hominis/fireforge 0.17.0 → 0.18.1

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

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

package/dist/src/commands/doctor.js

@@ -2,7 +2,6 @@ import { configExists, getProjectPaths, loadConfig, loadState } from '../core/co
 import { furnaceConfigExists as checkFurnaceConfigExists } from '../core/furnace-config.js';
 import { getCurrentBranch, getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { ensureGit } from '../core/git-base.js';
-import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { ensureMach, ensurePython } from '../core/mach.js';
 import { countPatches } from '../core/patch-apply.js';
 import { rebuildPatchesManifest, validatePatchesManifestConsistency, validatePatchIntegrity, } from '../core/patch-manifest.js';
@@ -12,6 +11,7 @@ import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
 import { executableExists } from '../utils/process.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
+import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 /**
  * Builds a DoctorCheck object representing a successful "OK" check.
  * Exported for sibling check modules that declare `DoctorCheckDefinition`
@@ -58,9 +58,6 @@ async function executeCheck(definition, ctx) {
         return [failure(definition.name, toError(err).message, definition.fix)];
     }
 }
-function summarizeWorkingTreeChangeCount(changeCount) {
-    return `Engine working tree has ${changeCount} local change${changeCount === 1 ? '' : 's'}. Some FireForge commands assume a clean baseline and may behave differently until these are exported, discarded, or committed.`;
-}
 /**
  * Runs the subset of engine checks that depend on a healthy git repository
  * and HEAD. This group shares mutable state (currentHead, canValidateBranch),
@@ -89,13 +86,9 @@ async function runEngineGitChecks(ctx) {
             rows.push(ok('Engine state consistency'));
         }
     }
-    const rawStatus = await getWorkingTreeStatus(paths.engine);
-    const workingTreeStatus = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
-    if (workingTreeStatus.length > 0) {
-        rows.push(warning('Engine working tree', summarizeWorkingTreeChangeCount(workingTreeStatus.length), 'Use "fireforge status" to review changes, then export, discard, or reset them as appropriate.'));
-    }
-    else {
-        rows.push(ok('Engine working tree'));
+    const workingTreeRow = await inspectEngineWorkingTree(ctx);
+    if (workingTreeRow) {
+        rows.push(workingTreeRow);
     }
     let branch;
     if (canValidateBranch) {
@@ -227,6 +220,11 @@ const DOCTOR_CHECKS = [
     {
         name: 'Engine is git repository',
         skipIf: (ctx) => !ctx.engineExists,
+        // runEngineGitChecks consults ctx.config for ownership-aware
+        // working-tree classification; declare the dependency so a future
+        // reorder doesn't silently regress the doctor back to the
+        // count-only fallback.
+        dependsOn: ['fireforge.json is valid'],
         run: async (ctx) => {
             const isRepo = await isGitRepository(ctx.paths.engine);
             if (!isRepo) {
@@ -324,7 +322,19 @@ const DOCTOR_CHECKS = [
                 // (only `filesAffected` / ordering drifted) are not flagged.
                 if (repaired.recoveredFilenames.length > 0) {
                     for (const filename of repaired.recoveredFilenames) {
-                        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. Edit patches.json to restore the original description if you have it backed up.`);
+                        // 2026-04-24 eval Finding 6: the repair path used to tell the
+                        // operator to hand-edit patches.json, which contradicts the
+                        // README + Hominis docs that treat the manifest as
+                        // FireForge-owned. Point at the existing `re-export` /
+                        // `export` workflow instead so the fix stays inside the tool:
+                        // re-exporting the same files with an explicit `--description`
+                        // overwrites the recovered entry with operator-supplied
+                        // metadata and supersedes the mtime-based createdAt stamp.
+                        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. ` +
+                            'Re-export the affected files with `fireforge re-export <filename> --description "<your description>"` ' +
+                            '(or `fireforge export <paths...> --name <name> --category <category> --description "<your description>"`) ' +
+                            'to overwrite the reconstructed metadata, or accept the generic description if the original text is not recoverable. ' +
+                            'Avoid hand-editing patches.json — FireForge owns that file and will regenerate it on the next manifest consistency pass.');
                     }
                 }
                 return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.manifest.patches.length} patch${repaired.manifest.patches.length === 1 ? '' : 'es'}${repaired.recoveredFilenames.length > 0 ? ` (${repaired.recoveredFilenames.length} with reconstructed metadata — see warnings above)` : ''}. Review recovered metadata before release.`);

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

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

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

@@ -17,8 +17,14 @@ import type { SpinnerHandle } from '../utils/logger.js';
  *   `--skip-lint` when exactly one advisory rule does not apply to a
  *   specific patch — e.g. `large-patch-lines` on a cohesive branding
  *   bundle that genuinely cannot be split.
+ * @param patchTier - Optional explicit tier override (threaded from
+ *   `PatchMetadata.tier`). Forces the branding-tier thresholds when
+ *   set, independent of the auto-detect allowlist. When the branding
+ *   tier is applied (either via this opt-in or the auto-detect), a
+ *   single `info()` line surfaces the choice so the tier decision is
+ *   visible rather than silent.
  */
-export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>): Promise<void>;
+export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>, patchTier?: 'branding'): Promise<void>;
 /**
  * Resolves patch metadata interactively or from flags, with shared validation.
  * @param options - Export command options

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

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 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 { commentStyleForFile, detectNewFilesInDiff, lintExportedPatch, resolvePatchSizeTier, } 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';
@@ -24,9 +24,27 @@ import { isValidPatchCategory, PATCH_CATEGORIES, validatePatchName } from '../ut
  *   `--skip-lint` when exactly one advisory rule does not apply to a
  *   specific patch — e.g. `large-patch-lines` on a cohesive branding
  *   bundle that genuinely cannot be split.
+ * @param patchTier - Optional explicit tier override (threaded from
+ *   `PatchMetadata.tier`). Forces the branding-tier thresholds when
+ *   set, independent of the auto-detect allowlist. When the branding
+ *   tier is applied (either via this opt-in or the auto-detect), a
+ *   single `info()` line surfaces the choice so the tier decision is
+ *   visible rather than silent.
  */
-export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx, ignoreChecks) {
-    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx, ignoreChecks);
+export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx, ignoreChecks, patchTier) {
+    // Compute the tier decision independently of the lint pipeline so the
+    // decision can be surfaced even when the rule body emitted no issues
+    // (e.g. a branding patch under the soft threshold still benefits from
+    // operators knowing which tier governed the run). The same helper is
+    // reused inside `lintPatchSize`, so the surfaced tier and the tier
+    // that actually drove the thresholds never drift.
+    const tierDecision = resolvePatchSizeTier(filesAffected, patchTier);
+    if (tierDecision.tier === 'branding') {
+        info(tierDecision.source === 'explicit'
+            ? 'Lint: branding threshold tier applied via patches.json `tier: "branding"` opt-in.'
+            : 'Lint: branding threshold tier applied (patch is all under browser/branding/ plus registration siblings).');
+    }
+    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx, ignoreChecks, patchTier);
     if (issues.length === 0)
         return;
     const errors = issues.filter((i) => i.severity === 'error');

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

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

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

@@ -79,17 +79,14 @@ async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasF
     return copiedFiles;
 }
 /**
- * Writes override metadata to disk and updates furnace.json with the new override entry.
- * @param projectRoot - Root directory of the project
- * @param destDir - Override component directory
- * @param componentName - Component tag name
- * @param overrideType - Override mode that was created
- * @param description - Human-readable override description
- * @param details - Source component metadata from the engine scan
- * @param firefoxVersion - Firefox version recorded in the workspace config
- * @param config - Mutable Furnace config object to update
+ * Writes override metadata to disk and updates furnace.json with the new
+ * override entry. Re-reads the current on-disk furnace.json inside the
+ * operation lock and splices the new entry onto the fresh state so two
+ * concurrent `furnace override` commands cannot race their read-modify
+ * -write cycles into a single surviving entry (eval 2: parallel overrides
+ * both reported success but furnace.json kept only the second writer).
  */
-async function saveOverrideConfig(projectRoot, destDir, componentName, overrideType, description, details, firefoxVersion, config, journal, baseCommit) {
+async function saveOverrideConfig(projectRoot, destDir, componentName, overrideType, description, details, firefoxVersion, journal, baseCommit) {
     const overrideJson = {
         type: overrideType,
         description,
@@ -100,14 +97,27 @@ async function saveOverrideConfig(projectRoot, destDir, componentName, overrideT
     const overrideJsonPath = join(destDir, 'override.json');
     await snapshotFile(journal, overrideJsonPath);
     await writeJson(overrideJsonPath, overrideJson);
-    config.overrides[componentName] = {
+    // Re-read the current furnace.json inside the lock. The outer caller
+    // loaded a snapshot before entering `runFurnaceMutation`, but another
+    // furnace mutation (override / init / sync) may have landed in between
+    // — writing back the stale snapshot would drop that concurrent write.
+    const freshConfig = await loadAuthoringFurnaceConfig(projectRoot);
+    freshConfig.overrides[componentName] = {
         type: overrideType,
         description,
         basePath: details.sourcePath,
         baseVersion: firefoxVersion,
         ...(baseCommit ? { baseCommit } : {}),
     };
-    await writeFurnaceConfig(projectRoot, config);
+    // Promote from the stock bucket here, against the fresh state, so the
+    // stock→override transition survives even when another concurrent
+    // override already rewrote furnace.json between the outer read and
+    // this write.
+    const stockIndex = freshConfig.stock.indexOf(componentName);
+    if (stockIndex !== -1) {
+        freshConfig.stock.splice(stockIndex, 1);
+    }
+    await writeFurnaceConfig(projectRoot, freshConfig);
 }
 /**
  * Performs the transactional mutation phase of furnace override under the
@@ -123,7 +133,7 @@ async function performOverrideMutations(args) {
         try {
             const filesCopied = await copyOverrideFiles(args.engineDir, args.srcDir, args.destDir, args.componentName, args.details.hasFTL, args.overrideType, args.ftlDir, journal);
             await snapshotFile(journal, args.furnacePaths.furnaceConfig);
-            await saveOverrideConfig(args.projectRoot, args.destDir, args.componentName, args.overrideType, args.description, args.details, args.firefoxVersion, args.config, journal, args.baseCommit);
+            await saveOverrideConfig(args.projectRoot, args.destDir, args.componentName, args.overrideType, args.description, args.details, args.firefoxVersion, journal, args.baseCommit);
             return filesCopied;
         }
         catch (error) {

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

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

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

@@ -3,9 +3,10 @@ import { readdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { removeCustomFtlJarMnEntry } from '../../core/furnace-apply-ftl.js';
 import { extractComponentChecksums, getOverrideEngineTargetPath, isOverrideCopyCandidate, restoreOverrideFileToBaseline, } from '../../core/furnace-apply-helpers.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { resolveFtlDir } from '../../core/furnace-constants.js';
+import { resolveFtlDir, xpcshellTestParentDir } from '../../core/furnace-constants.js';
 import { recordFurnaceRollbackFailure, runFurnaceMutation } from '../../core/furnace-operation.js';
 import { removeCustomElementRegistration, removeJarMnEntries, } from '../../core/furnace-registration.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -211,6 +212,64 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
     }
     return { partialFailures };
 }
+/**
+ * Removes generated xpcshell test scaffolds associated with a custom
+ * component. 2026-04-24 eval Finding 5: `furnace remove` handled
+ * browser mochitests via `cleanupCustomTestFiles` but never touched the
+ * xpcshell scaffold tree, so an operator who ran
+ * `furnace create --with-tests --xpcshell` followed by `furnace remove`
+ * was left with orphan `xpcshell.toml` + `test_<name>_packaged.js`
+ * files still referencing the removed component. This cleanup pass
+ * mirrors the mochitest one — snapshot before removal, warn-and-
+ * continue semantics, explicit summary when partial failures occur.
+ */
+async function cleanupCustomXpcshellTestFiles(name, projectRoot, journal) {
+    const partialFailures = [];
+    let forgeConfig;
+    try {
+        forgeConfig = await loadConfig(projectRoot);
+    }
+    catch (error) {
+        const msg = `Could not load config for xpcshell test cleanup — ${toError(error).message}. Remove xpcshell test files manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+        return { partialFailures };
+    }
+    const paths = getProjectPaths(projectRoot);
+    const xpcshellRoot = join(paths.engine, xpcshellTestParentDir(forgeConfig.binaryName));
+    const componentXpcshellDir = join(xpcshellRoot, name);
+    if (!(await pathExists(componentXpcshellDir)))
+        return { partialFailures };
+    try {
+        await snapshotDir(journal, componentXpcshellDir);
+        await removeDir(componentXpcshellDir);
+        info(`Deleted xpcshell test scaffold directory: ${componentXpcshellDir.replace(paths.engine + '/', 'engine/')}`);
+    }
+    catch (error) {
+        const msg = `Could not delete xpcshell test scaffold — ${toError(error).message}. Remove it manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+    }
+    // If the xpcshell parent directory is now empty (no other components
+    // had scaffolds), drop it too so `furnace validate` stays quiet about
+    // the empty per-binary tree. Warn-and-continue on any failure.
+    try {
+        if (await pathExists(xpcshellRoot)) {
+            const remaining = await readdir(xpcshellRoot);
+            if (remaining.length === 0) {
+                await snapshotDir(journal, xpcshellRoot);
+                await removeDir(xpcshellRoot);
+                info(`Deleted empty xpcshell parent directory: ${xpcshellRoot.replace(paths.engine + '/', 'engine/')}`);
+            }
+        }
+    }
+    catch (error) {
+        const msg = `Could not clean up xpcshell parent directory — ${toError(error).message}. Remove it manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+    }
+    return { partialFailures };
+}
 function dropChecksumsByPrefix(state, prefix) {
     const result = { ...state };
     if (state.appliedChecksums) {
@@ -353,12 +412,27 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                         await removeFile(ftlPath);
                         info(`Deleted localized file engine/${ftlRel}`);
                     }
+                    // Drop the locale jar.mn chrome registration that `applyCustomFtlFile`
+                    // wrote during deploy — otherwise the engine is left with a
+                    // `locale/.../${name}.ftl` entry pointing at a file we just
+                    // deleted. 2026-04-21 eval (Finding #1): `furnace remove` left
+                    // `browser/locales/jar.mn` referencing the missing FTL, which
+                    // would break the next package-manifest validation.
+                    await removeCustomFtlJarMnEntry(paths.engine, `${name}.ftl`, ftlDir, customConfig, journal);
                 }
             }
             let testCleanupFailures = [];
             if (type === 'custom') {
                 const result = await cleanupCustomTestFiles(name, projectRoot, journal);
                 testCleanupFailures = result.partialFailures;
+                // 2026-04-24 eval Finding 5: also clean up xpcshell scaffolds
+                // generated by `furnace create --with-tests --xpcshell`. The
+                // mochitest cleanup above covers `browser/base/content/test/
+                // <binary>/`, but xpcshell scaffolds live in the sibling
+                // `<binary>-xpcshell/` directory and were orphaned by prior
+                // versions.
+                const xpcshellResult = await cleanupCustomXpcshellTestFiles(name, projectRoot, journal);
+                testCleanupFailures.push(...xpcshellResult.partialFailures);
             }
             // Remove entry from furnace.json
             if (type === 'stock') {

package/dist/src/commands/furnace/rename-xpcshell.d.ts

@@ -0,0 +1,35 @@
+/**
+ * xpcshell scaffold rename helper extracted from `rename.ts`.
+ *
+ * 2026-04-24 eval Finding 5: `furnace create --with-tests --xpcshell`
+ * writes a scaffold at `browser/base/content/test/<binary>-xpcshell/
+ * <name>/` and `furnace rename` did not update it. The helper below
+ * renames the directory, updates the test filename, rewrites the
+ * `xpcshell.toml` section header, and re-writes the test body so word-
+ * boundary occurrences of the old tag / underscored name map to the new
+ * ones.
+ *
+ * Extracted to keep `rename.ts` under the per-file LOC budget —
+ * `rename.ts` already carries mochikit + browser-mochitest + FTL
+ * handling, and tacking xpcshell onto that tree pushed the file past
+ * the limit.
+ */
+import { type RollbackJournal } from '../../core/furnace-rollback.js';
+/**
+ * Renames an xpcshell test scaffold in place. Moves the directory,
+ * rewrites the test filename, updates the `[test_name]` section header
+ * in `xpcshell.toml`, and word-boundary-rewrites occurrences of the
+ * old tag / old underscored name inside the test body.
+ *
+ * Best-effort: any failure logs a warning through the shared logger
+ * but never throws — the component rename itself has already succeeded
+ * at this point, and blocking on a test rewrite would leave the
+ * operator with a half-renamed component.
+ *
+ * @param engineDir - Absolute path to the engine directory under the project.
+ * @param projectRoot - Absolute path to the project root, used to load the binary name.
+ * @param oldName - Pre-rename component tag name.
+ * @param newName - Post-rename component tag name.
+ * @param journal - Rollback journal that the rename mutation writes to before touching files.
+ */
+export declare function renameXpcshellTestFiles(engineDir: string, projectRoot: string, oldName: string, newName: string, journal: RollbackJournal): Promise<void>;