@hominis/fireforge 0.15.9 → 0.16.1

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

@@ -100,6 +100,14 @@ async function diffOverride(name, projectRoot, config) {
 /**
  * Diffs a custom component's workspace files against the engine-deployed copy.
  * Shows what would change (or has changed) on the next `furnace apply`.
+ *
+ * `.ftl` files deploy to `engine/<ftlDir>/<name>.ftl` via `applyCustomFtlFile`
+ * — NOT to `customConfig.targetPath` — so the deployment-target lookup has
+ * to branch on extension. Before this branch existed, a component's
+ * localization file always reported "not yet deployed to engine (new
+ * file)" after a successful apply/deploy because diff was looking for it
+ * under the component's `targetPath` while apply had written it into the
+ * locale tree.
  */
 async function diffCustom(name, projectRoot, config) {
     const customConfig = config.custom[name];
@@ -108,6 +116,7 @@ async function diffCustom(name, projectRoot, config) {
     }
     const paths = getProjectPaths(projectRoot);
     const furnacePaths = getFurnacePaths(projectRoot);
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
     const customDir = join(furnacePaths.customDir, name);
     if (!(await pathExists(customDir))) {
         throw new FurnaceError(`Custom component directory not found: components/custom/${name}`, name);
@@ -121,8 +130,19 @@ async function diffCustom(name, projectRoot, config) {
         if (!isComponentSourceFile(entry.name))
             continue;
         const workspacePath = join(customDir, entry.name);
-        const deployedPath = join(engineDir, entry.name);
         const workspaceContent = await readText(workspacePath);
+        // `.ftl` files deploy to the locale tree, not the component's
+        // targetPath; mirror `applyCustomFtlFile`'s target computation so the
+        // diff header and the existence probe name the same path apply
+        // writes to. Any change here must stay in lock-step with
+        // `src/core/furnace-apply-ftl.ts`.
+        const isFtl = entry.name.endsWith('.ftl');
+        const deployedPath = isFtl
+            ? join(paths.engine, ftlDir, entry.name)
+            : join(engineDir, entry.name);
+        const deployedDisplayPath = isFtl
+            ? `engine/${ftlDir}/${entry.name}`
+            : `engine/${customConfig.targetPath}/${entry.name}`;
         if (!(await pathExists(deployedPath))) {
             info(`${entry.name}: not yet deployed to engine (new file)`);
             hasDifferences = true;
@@ -133,7 +153,7 @@ async function diffCustom(name, projectRoot, config) {
             continue;
         }
         hasDifferences = true;
-        info(`--- engine/${customConfig.targetPath}/${entry.name}`);
+        info(`--- ${deployedDisplayPath}`);
         info(`+++ components/custom/${name}/${entry.name}`);
         for (const line of formatUnifiedDiff(deployedContent, workspaceContent)) {
             info(line);

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

@@ -83,6 +83,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
         .option('--shared-ftl <path>', 'Participate in an existing feature-scoped .ftl at this path (e.g. "browser/hominis-dock.ftl"); skips the per-component .ftl scaffold (implies --localized)')
         .option('--dry-run', 'Show the planned file set and furnace.json changes without writing')
+        .option('--allow-prefix-mismatch', 'Create the component even when its name does not start with the configured `componentPrefix` in furnace.json. Without this flag the command refuses to write anything on a prefix mismatch.')
         .action(withErrorHandling(async (name, options) => {
         await furnaceCreateCommand(getProjectRoot(), name, options);
     }));

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

@@ -1,9 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { isAbsolute, normalize } from 'node:path';
+import { dirname, isAbsolute, join, normalize } from 'node:path';
 import { text } from '@clack/prompts';
+import { getProjectPaths, loadConfig, mutateConfig, writeConfig } from '../../core/config.js';
 import { createDefaultFurnaceConfig, furnaceConfigExists, writeFurnaceConfig, } from '../../core/furnace-config.js';
+import { DEFAULT_LICENSE } from '../../core/license-headers.js';
+import { getTokensCssPath } from '../../core/token-manager.js';
+import { generateDefaultTokensCss } from '../../core/token-scaffold.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { cancel, info, intro, isCancel, note, outro, success } from '../../utils/logger.js';
+import { toError } from '../../utils/errors.js';
+import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
+import { cancel, info, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
 /**
  * Validates an FTL base path before writing it to furnace.json. Rejects
  * absolute paths, null bytes, and any normalised segment starting with
@@ -80,10 +86,14 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
     }
     await writeFurnaceConfig(projectRoot, config);
     success('Created furnace.json');
+    const scaffoldResult = await scaffoldTokensCss(projectRoot);
     const lines = [`Component prefix: ${config.componentPrefix}`];
     if (config.ftlBasePath) {
         lines.push(`FTL base path: ${config.ftlBasePath}`);
     }
+    if (scaffoldResult.tokensCssPath) {
+        lines.push(`Tokens CSS:       ${scaffoldResult.tokensCssPath}`);
+    }
     note(lines.join('\n'), 'Configuration');
     info('Next steps:\n' +
         '  fireforge furnace scan        — discover engine components\n' +
@@ -91,4 +101,68 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
         '  fireforge furnace override     — fork an existing component');
     outro('Init complete');
 }
+/**
+ * Scaffolds the default tokens CSS file under the engine and registers
+ * its path in `fireforge.json`'s `patchLint.rawColorAllowlist`. Both
+ * operations are skipped silently when the engine directory does not
+ * yet exist (a fresh project that hasn't `fireforge download`ed yet);
+ * the scaffold is re-driven on the next `furnace init --force`.
+ *
+ * Returns the scaffolded path when the file was actually created, so
+ * the init command can surface it in the summary note.
+ */
+async function scaffoldTokensCss(projectRoot) {
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine))) {
+        info('Skipping tokens CSS scaffold: engine/ not found. Run "fireforge download" followed by "fireforge furnace init --force" to scaffold it.');
+        return {};
+    }
+    let forgeConfig;
+    try {
+        forgeConfig = await loadConfig(projectRoot);
+    }
+    catch (error) {
+        warn(`Skipping tokens CSS scaffold: fireforge.json could not be loaded (${toError(error).message}). Re-run "fireforge furnace init --force" after fixing the config.`);
+        return {};
+    }
+    const tokensCssPath = getTokensCssPath(forgeConfig.binaryName);
+    const tokensCssAbsPath = join(paths.engine, tokensCssPath);
+    if (!(await pathExists(tokensCssAbsPath))) {
+        try {
+            await ensureDir(dirname(tokensCssAbsPath));
+            await writeText(tokensCssAbsPath, generateDefaultTokensCss(forgeConfig.binaryName, forgeConfig.license ?? DEFAULT_LICENSE));
+            success(`Scaffolded tokens CSS at engine/${tokensCssPath}`);
+        }
+        catch (error) {
+            warn(`Could not scaffold tokens CSS at engine/${tokensCssPath}: ${toError(error).message}. Create the file manually before running "fireforge token add".`);
+            return {};
+        }
+    }
+    else {
+        info(`Tokens CSS already present at engine/${tokensCssPath}; leaving it untouched.`);
+    }
+    // Registering the tokens file in `patchLint.rawColorAllowlist` is the
+    // complement to the scaffold itself: the file exists specifically to
+    // carry raw color literals, and without the allowlist entry the very
+    // first `fireforge lint` run against a post-`token add` workspace
+    // fails on raw-color-value issues for tokens the operator just
+    // created. The add is idempotent, so re-running `furnace init --force`
+    // does not duplicate the entry.
+    try {
+        const existingAllowlist = forgeConfig.patchLint?.rawColorAllowlist ?? [];
+        if (!existingAllowlist.includes(tokensCssPath)) {
+            const updatedConfig = mutateConfig(forgeConfig, 'patchLint.rawColorAllowlist', [
+                ...existingAllowlist,
+                tokensCssPath,
+            ]);
+            await writeConfig(projectRoot, updatedConfig);
+            info(`Added ${tokensCssPath} to patchLint.rawColorAllowlist`);
+        }
+    }
+    catch (error) {
+        warn(`Could not register tokens CSS in patchLint.rawColorAllowlist: ${toError(error).message}. ` +
+            `Add "${tokensCssPath}" manually under patchLint.rawColorAllowlist in fireforge.json if lint flags its contents.`);
+    }
+    return { tokensCssPath };
+}
 //# sourceMappingURL=init.js.map

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

@@ -139,23 +139,37 @@ async function performOverrideMutations(args) {
     });
 }
 /**
- * Throws if `componentName` is already classified anywhere in the furnace
- * config. Without this guard, `writeFurnaceConfig` would happily produce a
- * file where the same tag appears under multiple categories (stock +
- * override, custom + override) and later commands would no longer be able
- * to reason about that component cleanly.
+ * Throws if `componentName` is already classified as something `override`
+ * cannot coexist with. A stock-bucket entry is NOT a hard conflict — the
+ * whole point of `override` is to fork a component out of the stock bucket
+ * into the overrides bucket, and requiring manual `furnace.json` surgery
+ * first was a pure footgun. `promoteStockToOverrideIfNeeded` handles the
+ * transition in-memory; this guard only rejects the other two cases where
+ * a rename actually contradicts existing state.
  */
 function assertNoComponentCollision(config, componentName) {
     if (componentName in config.overrides) {
         throw new FurnaceError(`An override for "${componentName}" already exists in furnace.json`, componentName);
     }
-    if (config.stock.includes(componentName)) {
-        throw new FurnaceError(`"${componentName}" is already registered as a stock component. Remove it from config.stock before creating an override.`, componentName);
-    }
     if (componentName in config.custom) {
         throw new FurnaceError(`"${componentName}" is already registered as a custom component. Custom components cannot also be overrides.`, componentName);
     }
 }
+/**
+ * When the operator overrides a component that `furnace scan` previously
+ * classified as stock, splice the name out of `config.stock` in-memory so
+ * the subsequent `writeFurnaceConfig` inside the mutation phase persists
+ * the stock → override promotion atomically alongside the new override
+ * entry. Returns true when a promotion happened so the caller can emit a
+ * one-line note; false when the component was not stock.
+ */
+function promoteStockToOverrideIfNeeded(config, componentName) {
+    const index = config.stock.indexOf(componentName);
+    if (index === -1)
+        return false;
+    config.stock.splice(index, 1);
+    return true;
+}
 /**
  * Runs the furnace override command to fork an existing engine component.
  * @param projectRoot - Root directory of the project
@@ -213,6 +227,10 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
         componentName = selected;
     }
     assertNoComponentCollision(config, componentName);
+    const promotedFromStock = promoteStockToOverrideIfNeeded(config, componentName);
+    if (promotedFromStock) {
+        info(`Promoting "${componentName}" from stock to override.`);
+    }
     // Validate the component exists in engine
     const details = await getComponentDetails(paths.engine, componentName, ftlDir);
     if (!details) {
@@ -323,13 +341,18 @@ export async function furnaceBatchOverrideCommand(projectRoot, names, options =
     const forgeConfig = await loadConfig(projectRoot);
     const state = await loadState(projectRoot);
     // Check for duplicates and pre-existing classifications across every
-    // bucket in furnace.json. Missing these collisions silently double-
-    // classifies a tag (e.g. both stock and override) and leaves the
-    // workspace in a state that later `furnace status`/`apply` cannot
-    // reason about cleanly.
+    // bucket in furnace.json. A stock-bucket entry is promoted in-memory
+    // here (see `promoteStockToOverrideIfNeeded`) rather than rejected —
+    // the operator's intent is to fork that specific stock component. The
+    // collision guard still rejects name conflicts that would double-
+    // classify a tag in a way `writeFurnaceConfig` cannot safely produce
+    // (two overrides, or an override + custom).
     const uniqueNames = [...new Set(names)];
     for (const name of uniqueNames) {
         assertNoComponentCollision(config, name);
+        if (promoteStockToOverrideIfNeeded(config, name)) {
+            info(`Promoting "${name}" from stock to override.`);
+        }
     }
     const succeeded = [];
     const failed = [];

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

@@ -6,7 +6,7 @@ import { furnaceConfigExists, loadFurnaceConfig, updateFurnaceState, } from '../
 import { runFurnaceMutation } from '../../core/furnace-operation.js';
 import { restoreRollbackJournal } from '../../core/furnace-rollback.js';
 import { cleanStories, syncStories } from '../../core/furnace-stories.js';
-import { runMach, runMachCapture } from '../../core/mach.js';
+import { hasBuildArtifacts, runMach, runMachCapture } from '../../core/mach.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -89,6 +89,48 @@ function buildStorybookFailureMessage(output, installRequested) {
     return ('Storybook failed to start. Check the output above for the specific Firefox-side error.\n\n' +
         installHint);
 }
+/**
+ * Preflights the Firefox build + toolchain prerequisites `mach storybook`
+ * quietly assumes. Pre-0.16.0 the preview staged components and launched
+ * a ~1000-package `mach storybook upgrade` npm install before the
+ * backend surfaced a "missing chrome-map.json" / Cargo-config failure;
+ * the preflight below refuses fast and leaves the workspace untouched.
+ *
+ * Extracted from `furnacePreviewCommand` so the main function stays
+ * under the per-function LOC budget as the preflight list grows.
+ *
+ * @param engineDir - Resolved engine directory
+ * @throws FurnaceError when the Firefox build hasn't produced dist/, or
+ *         when `.cargo/config.toml` is absent
+ */
+async function assertPreviewPrerequisites(engineDir) {
+    const buildCheck = await hasBuildArtifacts(engineDir);
+    if (!buildCheck.exists) {
+        throw new FurnaceError('Furnace preview requires a completed Firefox build. ' +
+            '`mach storybook` consumes `obj-*/dist/chrome-map.json` and the packaged chrome resources under `dist/`, neither of which is present before `fireforge build` completes.\n\n' +
+            'Run "fireforge build" and wait for it to finish, then rerun "fireforge furnace preview". ' +
+            'This preflight avoids a multi-minute `mach storybook upgrade` npm install on an engine that cannot start Storybook anyway.');
+    }
+    // Accept either `.cargo/config.toml` (post-configure) or
+    // `.cargo/config.toml.in` (post-bootstrap template, consumed at
+    // `mach configure` time). Pre-0.16.0 the preflight insisted on the
+    // plain file, but `fireforge bootstrap` alone produces only `.in` —
+    // operators who followed the remediation instruction ("run bootstrap
+    // then rerun preview") hit the same refusal on the retry. Either name
+    // is sufficient to prove the Rust toolchain is registered; the stronger
+    // `hasBuildArtifacts` check above already guards against a completely
+    // un-configured tree, so relaxing this to an OR-check does not weaken
+    // the signal we care about.
+    const cargoConfigPath = join(engineDir, '.cargo', 'config.toml');
+    const cargoConfigInPath = join(engineDir, '.cargo', 'config.toml.in');
+    const cargoConfigPresent = (await pathExists(cargoConfigPath)) || (await pathExists(cargoConfigInPath));
+    if (!cargoConfigPresent) {
+        throw new FurnaceError("Furnace preview requires the engine's Rust toolchain to be bootstrapped. " +
+            'Neither `.cargo/config.toml` nor `.cargo/config.toml.in` exists under the engine directory — ' +
+            '`mach storybook` fails deep inside the Storybook backend compile without either of them.\n\n' +
+            'Run "fireforge bootstrap" (or the underlying `mach bootstrap` in the engine) to populate the toolchain config, then rerun "fireforge furnace preview".');
+    }
+}
 /**
  * Runs the furnace preview command to start Storybook for component preview.
  * @param projectRoot - Root directory of the project
@@ -119,6 +161,9 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
     if (!(await pathExists(storybookRoot))) {
         throw new FurnaceError('This Firefox checkout does not contain browser/components/storybook. Furnace preview requires the upstream Storybook workspace to exist before stories can be synced.');
     }
+    // Build + toolchain preflight (Finding #9). Extracted into a helper so
+    // the function below stays under the per-function LOC budget.
+    await assertPreviewPrerequisites(paths.engine);
     let previewResult;
     // True once we are about to (or have) written to engine/.../stories/furnace.
     // Intentionally set BEFORE `syncStories` is awaited so a mid-sync failure

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

@@ -304,14 +304,25 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
         throw new FurnaceError(`A component named "${newName}" already exists in furnace.json.`, newName);
     }
     const componentType = isCustom ? 'custom' : 'override';
+    // `componentType` is the furnace-state key (singular: `custom` /
+    // `override`); the on-disk directory label differs — custom components
+    // live under `components/custom/` (singular) while overrides live under
+    // `components/overrides/` (plural). Before 0.16.0, every rename
+    // user-facing message appended an `s` to `componentType`, which
+    // produced the wrong label `components/customs/` for custom components
+    // and was technically correct for overrides only by coincidence.
+    // `componentDirLabel` centralises the singular/plural pick so every
+    // operator-facing string names the directory that actually exists on
+    // disk.
+    const componentDirLabel = isCustom ? 'custom' : 'overrides';
     const baseDir = isCustom ? furnacePaths.customDir : furnacePaths.overridesDir;
     const oldDir = join(baseDir, oldName);
     const newDir = join(baseDir, newName);
     if (!(await pathExists(oldDir))) {
-        throw new FurnaceError(`Component directory not found: components/${componentType}s/${oldName}`, oldName);
+        throw new FurnaceError(`Component directory not found: components/${componentDirLabel}/${oldName}`, oldName);
     }
     if (await pathExists(newDir)) {
-        throw new FurnaceError(`Target directory already exists: components/${componentType}s/${newName}`, newName);
+        throw new FurnaceError(`Target directory already exists: components/${componentDirLabel}/${newName}`, newName);
     }
     await performRenameMutations({
         projectRoot,
@@ -326,7 +337,7 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
         engineDir: paths.engine,
     });
     note(`Component renamed: ${oldName} → ${newName}\n\n` +
-        `Directory: components/${componentType}s/${newName}/\n\n` +
+        `Directory: components/${componentDirLabel}/${newName}/\n\n` +
         'Next steps:\n' +
         '  1. Review the renamed files for any remaining references\n' +
         '  2. Run "fireforge furnace validate" to verify\n' +

package/dist/src/commands/lint.js

@@ -12,6 +12,7 @@ import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
+import { stripEnginePrefix } from '../utils/paths.js';
 /**
  * Resolves the diff the lint command should run against. Returns `null` when
  * there is nothing to lint (e.g. no matching files, clean tree, or empty
@@ -27,7 +28,15 @@ async function resolveLintDiff(engineDir, files) {
         const collectedFiles = new Set();
         let fileStatuses;
         let untrackedFiles;
-        for (const inputPath of files) {
+        // Strip a leading `engine/` segment up-front so the rest of the lookup
+        // pipeline (directory stat, modified-files-in-dir, status probe) all
+        // see the engine-relative form. Without this, passing
+        // `engine/browser/base/content/foo.js` fell through to "No modified
+        // files found in the specified paths." because git sees every path
+        // relative to engine/. The same normalization runs in `register`,
+        // `test`, and `export` via `stripEnginePrefix`.
+        const normalizedFiles = files.map((inputPath) => stripEnginePrefix(inputPath));
+        for (const inputPath of normalizedFiles) {
             const fullInputPath = join(engineDir, inputPath);
             let isDirectory = false;
             try {
@@ -145,10 +154,25 @@ export async function lintCommand(projectRoot, files, options = {}) {
     // really an artefact of aggregation. Surface a one-line note pointing at
     // `--per-patch` so the operator knows the per-patch scope exists before
     // they read the error message as "my queue is broken".
+    //
+    // In aggregate mode over a multi-patch queue we also downgrade the two
+    // size rules from `error` to `warning`. Before this downgrade, a
+    // fresh-imported patch stack of 20+ patches hard-failed `fireforge lint`
+    // on lines-per-aggregate counts that are mathematically impossible to
+    // satisfy without splitting patches that were already split — the
+    // actionable unit is the individual patch, and `--per-patch` is the
+    // mode that matches. Per-patch mode keeps errors as errors (see
+    // `lintPerPatch` below).
     const aggregateHintApplicable = files.length === 0 && ctx !== undefined && ctx.entries.length > 1;
     if (aggregateHintApplicable &&
         issues.some((i) => i.check === 'large-patch-lines' || i.check === 'large-patch-files')) {
-        info('NOTE: aggregate diff across all applied patches. Use `fireforge lint --per-patch` to lint each patch individually; patch-size rules fire against the sum in aggregate mode.');
+        info('NOTE: aggregate diff across all applied patches. Use `fireforge lint --per-patch` to lint each patch individually; patch-size rules fire against the sum in aggregate mode and are reported as warnings rather than errors here.');
+        for (const issue of issues) {
+            if ((issue.check === 'large-patch-lines' || issue.check === 'large-patch-files') &&
+                issue.severity === 'error') {
+                issue.severity = 'warning';
+            }
+        }
     }
     if (issues.length === 0) {
         success('No lint issues found.');

package/dist/src/commands/package.js

@@ -1,7 +1,8 @@
 import { validateBrandOverride } from '../core/brand-validation.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { buildArtifactMismatchMessage, hasBuildArtifacts, machPackage } from '../core/mach.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, machPackageCapture, } from '../core/mach.js';
+import { explainMachError } from '../core/mach-error-hints.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
@@ -49,9 +50,16 @@ export async function packageCommand(projectRoot, options) {
     info('Creating distribution package...');
     info('This may take a while.\n');
     const startTime = Date.now();
-    let exitCode;
+    let result;
     try {
-        exitCode = await machPackage(paths.engine);
+        // `machPackageCapture` streams output live AND captures the tail for
+        // post-run diagnostics. Previously `machPackage` inherited stdio
+        // only, so a targeted hint translator could not see the failure text.
+        // The captured stderr is fed through `explainMachError` below so
+        // recognised failure modes (notably the `packager.py` NoneType trip
+        // the evaluator hit on `hominis/`) get an actionable hint prepended
+        // to the raw mach output the operator already saw.
+        result = await machPackageCapture(paths.engine);
     }
     catch (error) {
         throw new BuildError('Package process failed to start', 'mach package', error instanceof Error ? error : undefined);
@@ -60,9 +68,12 @@ export async function packageCommand(projectRoot, options) {
     const minutes = Math.floor(duration / 60000);
     const seconds = Math.floor((duration % 60000) / 1000);
     const timeStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
-    if (exitCode !== 0) {
+    if (result.exitCode !== 0) {
         error(`Packaging failed after ${timeStr}`);
-        throw new BuildError(`Packaging failed with exit code ${exitCode}`, 'mach package');
+        const combinedOutput = `${result.stdout}\n${result.stderr}`;
+        const hints = explainMachError(combinedOutput);
+        const hintBlock = hints.length > 0 ? `\n\nHint:\n${hints.map((h) => `  ${h}`).join('\n')}` : '';
+        throw new BuildError(`Packaging failed with exit code ${result.exitCode}.${hintBlock}`, 'mach package');
     }
     info(`\nPackage created in obj-*/dist/`);
     outro(`Packaging completed in ${timeStr}!`);

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

@@ -59,6 +59,31 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     if (options.scan) {
         currentFilesAffected = await scanPatchFiles(currentFilesAffected, paths.engine, manifest, patch.filename, isDryRun);
     }
+    else if (options.files === undefined) {
+        // Finding #16: when neither `--scan` nor `--files` is set and some
+        // of the manifest's claimed files no longer exist on disk, the
+        // re-export silently writes a refreshed body whose filesAffected
+        // still names the vanished paths. That is the documented contract,
+        // but it is also a footgun — a later `verify` then fails on
+        // manifest-consistency with no obvious trigger. Emit one advisory
+        // warning up-front when we can detect the drift cheaply, so the
+        // operator has a chance to re-run with `--scan` or `--files`
+        // before the stale filesAffected lands in patches.json.
+        const missingFiles = [];
+        for (const file of currentFilesAffected) {
+            if (!(await pathExists(join(paths.engine, file)))) {
+                missingFiles.push(file);
+            }
+        }
+        if (missingFiles.length > 0) {
+            warn(`${patch.filename}: some files in patches.json no longer exist on disk ` +
+                `(${missingFiles.join(', ')}). Without --scan, re-export keeps the manifest's ` +
+                `filesAffected unchanged and the missing entries will be preserved — ` +
+                `\`fireforge verify\` may flag manifest inconsistency after this run.\n` +
+                `  Re-run with --scan to reconcile filesAffected with the current worktree, ` +
+                `or pass --files <paths> to set the list explicitly.`);
+        }
+    }
     // --- Explicit file-subset path ---
     // When --files is given, the target filesAffected is authoritative — drop
     // anything not in the list, add anything new. This is the surgical repair

package/dist/src/commands/rebase/patch-loop.js

@@ -4,6 +4,7 @@
  */
 import { join } from 'node:path';
 import { updateState } from '../../core/config.js';
+import { stampFurnaceOverrideBaseVersions } from '../../core/furnace-config.js';
 import { getDiffForFilesAgainstHead } from '../../core/git-diff.js';
 import { applyPatchWithFuzz } from '../../core/patch-apply-fuzz.js';
 import { updatePatch } from '../../core/patch-export.js';
@@ -126,6 +127,24 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz) {
     if (appliedFilenames.length > 0) {
         await stampPatchVersions(paths.patches, appliedFilenames, session.toVersion);
     }
+    // Stamp every Furnace override's `baseVersion` to match the rebased
+    // Firefox version. Before this stamp, a successful ESR bump left
+    // overrides in a doctor-failing drift state (each override still
+    // claimed the pre-rebase ESR as its baseline) and every subsequent
+    // `fireforge doctor` failed `Furnace component validation`. The
+    // stamp is unconditional per the helper's contract: rebase already
+    // succeeded on the patch side, so the operator is committing to the
+    // new ESR baseline; per-component health checking stays with
+    // `fireforge furnace validate` / `doctor --repair-furnace`.
+    try {
+        const overridesStamped = await stampFurnaceOverrideBaseVersions(projectRoot, session.toVersion);
+        if (overridesStamped > 0) {
+            info(`Stamped ${overridesStamped} Furnace override baseVersion(s) to ${session.toVersion}.`);
+        }
+    }
+    catch (furnaceStampError) {
+        warn(`Could not stamp Furnace override baseVersion(s) to ${session.toVersion}: ${toError(furnaceStampError).message}. Update baseVersion in furnace.json by hand or run "fireforge furnace refresh" if validate reports drift.`);
+    }
     // Print summary and clean up
     printSummary(session);
     await clearRebaseSession(projectRoot);

package/dist/src/commands/register.js

@@ -6,23 +6,7 @@ import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
-/**
- * Strips a leading `engine/` segment (either separator flavour) from a
- * user-supplied path so operators can pass either a repo-root-relative
- * path (`engine/browser/base/content/foo.xhtml`) or an engine-relative
- * path (`browser/base/content/foo.xhtml`). The engine-relative form is
- * what the manifest writers expect; without this normalisation, the
- * former failed with a misleading "File not found in engine" pointing
- * at a doubled path like `engine/engine/browser/...` that operators
- * had no way to spot from the error message alone.
- */
-function normalizeEngineRelativePath(filePath) {
-    if (filePath.startsWith('engine/'))
-        return filePath.slice('engine/'.length);
-    if (filePath.startsWith('engine\\'))
-        return filePath.slice('engine\\'.length);
-    return filePath;
-}
+import { stripEnginePrefix } from '../utils/paths.js';
 /**
  * Registers a file in the appropriate build manifest.
  *
@@ -50,7 +34,7 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
     // the former from the output of tab completion or `git status`, and
     // the mismatch used to produce a "File not found" error that named
     // the original path with no hint that dropping `engine/` would fix it.
-    const engineRelativePath = normalizeEngineRelativePath(filePath);
+    const engineRelativePath = stripEnginePrefix(filePath);
     // Verify the file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);

package/dist/src/commands/run.js

@@ -2,9 +2,9 @@
 import { createWriteStream } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectPaths } from '../core/config.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
-import { buildArtifactMismatchMessage, hasBuildArtifacts, run, runMachSmoke, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, run, runMachSmoke, } from '../core/mach.js';
 import { compileAllowlistFromFile, compileAllowlistFromStrings, matchesAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
@@ -94,6 +94,27 @@ export async function runCommand(projectRoot, options = {}) {
         throw new GeneralError(`Run requires a completed build. ${detail}\n\n` +
             "Run 'fireforge build' first, then rerun 'fireforge run'.");
     }
+    // `hasBuildArtifacts` only checks for an `obj-*/dist/` directory; a
+    // build that configured but hasn't yet produced the launchable binary
+    // (common in a long real Firefox compile that the operator stopped
+    // and restarted) passes that check, and `mach run` then fails on the
+    // missing binary path. `hasRunnableBundle` narrows the probe to the
+    // actual executable so `fireforge run` refuses with a targeted
+    // message before handing control to mach. `fireforge watch` stays
+    // permissive and instead surfaces the same information as a banner
+    // suffix; watch is supposed to drive rebuilds of partially-built
+    // trees, so blocking there would defeat the feature.
+    if (buildCheck.objDir) {
+        const config = await loadConfig(projectRoot);
+        const bundleCheck = await hasRunnableBundle(paths.engine, config.binaryName, buildCheck.objDir);
+        if (!bundleCheck.runnable) {
+            const expected = bundleCheck.expectedPath ?? `dist/bin/${config.binaryName}`;
+            throw new GeneralError(`Run requires a completed build that produced the launchable bundle. ` +
+                `Build artifacts exist in ${buildCheck.objDir}/ but the expected binary at ${expected} is missing — ` +
+                `the build may have aborted or is still in progress.\n\n` +
+                "Run 'fireforge build' and wait for it to finish before retrying 'fireforge run'.");
+        }
+    }
     // Warn if Furnace components changed since the last apply
     await warnIfFurnaceStale(projectRoot);
     // Clean stale profile state to prevent silent startup failures