@hominis/fireforge 0.16.5 → 0.18.0

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

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

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

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

package/dist/src/commands/doctor.js

@@ -2,7 +2,6 @@ import { configExists, getProjectPaths, loadConfig, loadState } from '../core/co
 import { furnaceConfigExists as checkFurnaceConfigExists } from '../core/furnace-config.js';
 import { getCurrentBranch, getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { ensureGit } from '../core/git-base.js';
-import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { ensureMach, ensurePython } from '../core/mach.js';
 import { countPatches } from '../core/patch-apply.js';
 import { rebuildPatchesManifest, validatePatchesManifestConsistency, validatePatchIntegrity, } from '../core/patch-manifest.js';
@@ -12,6 +11,7 @@ import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
 import { executableExists } from '../utils/process.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
+import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 /**
  * Builds a DoctorCheck object representing a successful "OK" check.
  * Exported for sibling check modules that declare `DoctorCheckDefinition`
@@ -58,9 +58,6 @@ async function executeCheck(definition, ctx) {
         return [failure(definition.name, toError(err).message, definition.fix)];
     }
 }
-function summarizeWorkingTreeChangeCount(changeCount) {
-    return `Engine working tree has ${changeCount} local change${changeCount === 1 ? '' : 's'}. Some FireForge commands assume a clean baseline and may behave differently until these are exported, discarded, or committed.`;
-}
 /**
  * Runs the subset of engine checks that depend on a healthy git repository
  * and HEAD. This group shares mutable state (currentHead, canValidateBranch),
@@ -89,13 +86,9 @@ async function runEngineGitChecks(ctx) {
             rows.push(ok('Engine state consistency'));
         }
     }
-    const rawStatus = await getWorkingTreeStatus(paths.engine);
-    const workingTreeStatus = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
-    if (workingTreeStatus.length > 0) {
-        rows.push(warning('Engine working tree', summarizeWorkingTreeChangeCount(workingTreeStatus.length), 'Use "fireforge status" to review changes, then export, discard, or reset them as appropriate.'));
-    }
-    else {
-        rows.push(ok('Engine working tree'));
+    const workingTreeRow = await inspectEngineWorkingTree(ctx);
+    if (workingTreeRow) {
+        rows.push(workingTreeRow);
     }
     let branch;
     if (canValidateBranch) {
@@ -227,6 +220,11 @@ const DOCTOR_CHECKS = [
     {
         name: 'Engine is git repository',
         skipIf: (ctx) => !ctx.engineExists,
+        // runEngineGitChecks consults ctx.config for ownership-aware
+        // working-tree classification; declare the dependency so a future
+        // reorder doesn't silently regress the doctor back to the
+        // count-only fallback.
+        dependsOn: ['fireforge.json is valid'],
         run: async (ctx) => {
             const isRepo = await isGitRepository(ctx.paths.engine);
             if (!isRepo) {
@@ -314,7 +312,20 @@ const DOCTOR_CHECKS = [
             }
             try {
                 const repaired = await rebuildPatchesManifest(ctx.paths.patches, ctx.config.firefox.version);
-                return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.patches.length} patch${repaired.patches.length === 1 ? '' : 'es'}. Review recovered metadata before release.`);
+                // 2026-04-21 eval (Finding #17): the repair path silently
+                // overwrote useful human-written descriptions on recovered
+                // entries, leaving the queue less trustworthy as an audit
+                // trail. The rebuilder now returns the list of filenames
+                // whose metadata was entirely invented, and we name them
+                // explicitly here so the operator knows exactly which
+                // patches to review. Names that DID have a preserved entry
+                // (only `filesAffected` / ordering drifted) are not flagged.
+                if (repaired.recoveredFilenames.length > 0) {
+                    for (const filename of repaired.recoveredFilenames) {
+                        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. Edit patches.json to restore the original description if you have it backed up.`);
+                    }
+                }
+                return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.manifest.patches.length} patch${repaired.manifest.patches.length === 1 ? '' : 'es'}${repaired.recoveredFilenames.length > 0 ? ` (${repaired.recoveredFilenames.length} with reconstructed metadata — see warnings above)` : ''}. Review recovered metadata before release.`);
             }
             catch (err) {
                 return failure('Patch manifest consistency', toError(err).message, 'Repair failed. Fix the underlying patch metadata issue and retry the doctor command.');

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

@@ -5,7 +5,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } 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';
@@ -41,7 +41,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)));
@@ -129,7 +136,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))

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/chrome-doc-tests.js

@@ -117,9 +117,16 @@ add_task(async function test_${taskSuffix}_files_packaged() {
     ["browser", "chrome", "browser", "content", "browser", "${name}.xhtml"],
     "${name}.xhtml",
   );
+  // The scoped CSS is registered through jar.inc.mn under
+  // \`content/browser/<name>-chrome.css\` (see \`chromeDocJarIncMnCssEntry\`
+  // in \`src/commands/furnace/chrome-doc-templates.ts\`), so the packaged
+  // file lands under \`chrome/browser/content/browser/\`, not under
+  // \`skin/classic/browser/\`. The 2026-04-21 eval's first
+  // \`fireforge test --build\` against a scaffolded chrome-doc reported
+  // a false failure because the probe was looking at the skin layout.
   probeEither(
-    ["chrome", "browser", "skin", "classic", "browser", "${name}-chrome.css"],
-    ["browser", "chrome", "browser", "skin", "classic", "browser", "${name}-chrome.css"],
+    ["chrome", "browser", "content", "browser", "${name}-chrome.css"],
+    ["browser", "chrome", "browser", "content", "browser", "${name}-chrome.css"],
     "${name}-chrome.css",
   );
 });

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

@@ -76,6 +76,17 @@ export declare function mochikitTestFileName(name: string): string;
  * depend on the component's shape; operators can extend the test using
  * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
  * rely on.
+ *
+ * The template deliberately omits `SimpleTest.waitForExplicitFinish()`.
+ * `add_task` owns the test lifecycle: when every queued task resolves,
+ * the task harness calls `SimpleTest.finish()` on its own. Combining
+ * `waitForExplicitFinish()` with `add_task` *and* no explicit
+ * `SimpleTest.finish()` inside the task body makes the harness wait
+ * forever, which the 2026-04-21 eval run tripped into as an indefinite
+ * hang on a `fireforge test --headless` against a scaffolded widget
+ * test. Leaving `waitForExplicitFinish()` out matches the convention
+ * upstream toolkit widget tests use (see `test_moz-button.html` and
+ * siblings under `toolkit/content/tests/widgets/`).
  */
 export declare function generateMochikitTestContent(name: string): string;
 /**

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

@@ -227,6 +227,17 @@ export function mochikitTestFileName(name) {
  * depend on the component's shape; operators can extend the test using
  * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
  * rely on.
+ *
+ * The template deliberately omits `SimpleTest.waitForExplicitFinish()`.
+ * `add_task` owns the test lifecycle: when every queued task resolves,
+ * the task harness calls `SimpleTest.finish()` on its own. Combining
+ * `waitForExplicitFinish()` with `add_task` *and* no explicit
+ * `SimpleTest.finish()` inside the task body makes the harness wait
+ * forever, which the 2026-04-21 eval run tripped into as an indefinite
+ * hang on a `fireforge test --headless` against a scaffolded widget
+ * test. Leaving `waitForExplicitFinish()` out matches the convention
+ * upstream toolkit widget tests use (see `test_moz-button.html` and
+ * siblings under `toolkit/content/tests/widgets/`).
  */
 export function generateMochikitTestContent(name) {
     return `<!DOCTYPE html>
@@ -244,8 +255,6 @@ export function generateMochikitTestContent(name) {
     <script type="module">
       import "chrome://global/content/elements/${name}.mjs";
 
-      SimpleTest.waitForExplicitFinish();
-
       add_task(async function test_${name.replace(/-/g, '_')}_defined() {
         const ctor = await customElements.whenDefined("${name}");
         ok(ctor, "${name} custom element should be defined");

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { dirname, isAbsolute, join, normalize } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { basename, 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';
@@ -11,12 +12,46 @@ 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
- * `..` — the previous `includes('..')` substring check caught the common
- * case but missed `./../../` and absolute paths that are arguably worse.
+ * File extensions that are definitely FTL resources (not locale
+ * directories). A value ending in one of these is almost certainly the
+ * result of the operator pointing at a single FTL file instead of the
+ * locale directory that contains it.
+ *
+ * 2026-04-21 eval: `furnace init --ftl-base-path browser/forgefresh.ftl`
+ * produced a misleading success path — the subsequent
+ * `furnace create --localized` scaffolded an `.mjs` referencing
+ * `insertFTLIfNeeded("<name>.ftl")` while furnace.json had no component
+ * entry, leaving the scaffold orphaned. Switching to a locale directory
+ * (`toolkit/locales/en-US/toolkit/global`) fixed the downstream path.
+ * Rejecting file-shaped values up-front keeps the operator on the
+ * correct path before any partial state is written.
+ */
+const FTL_FILE_EXTENSIONS = new Set(['.ftl', '.properties', '.dtd']);
+function hasFtlFileExtension(value) {
+    const lower = value.toLowerCase();
+    const dotIdx = lower.lastIndexOf('.');
+    const slashIdx = Math.max(lower.lastIndexOf('/'), lower.lastIndexOf('\\'));
+    if (dotIdx <= slashIdx)
+        return false; // No extension in the basename.
+    return FTL_FILE_EXTENSIONS.has(lower.slice(dotIdx));
+}
+/**
+ * Validates an FTL base path before writing it to furnace.json.
+ * Rejects:
+ *  - empty values and null bytes;
+ *  - absolute paths (POSIX or Windows-drive) that escape the engine;
+ *  - `..` segments that escape the engine;
+ *  - file-shaped values ending in `.ftl` / `.properties` / `.dtd`
+ *    (these are locale resources, not directories — the operator
+ *    almost certainly meant to name the parent directory).
+ *
+ * When {@link engineDir} is provided and exists on disk, the resolved
+ * `engine/${value}` path is probed: if it exists but is not a
+ * directory, the same file-shape error fires; if it does not exist yet,
+ * a non-blocking warning is logged (a fresh project that has not
+ * `fireforge download`-ed yet is the legitimate pre-existence case).
  */
-function validateFtlBasePath(value) {
+async function validateFtlBasePath(value, engineDir) {
     if (value.length === 0) {
         throw new FurnaceError('ftlBasePath must not be empty.');
     }
@@ -30,6 +65,40 @@ function validateFtlBasePath(value) {
     if (normalized === '..' || normalized.startsWith('../')) {
         throw new FurnaceError(`ftlBasePath "${value}" must not escape the engine checkout via parent-directory segments.`);
     }
+    if (hasFtlFileExtension(value)) {
+        throw new FurnaceError(`ftlBasePath "${value}" looks like a file (basename "${basename(value)}" ends in .ftl/.properties/.dtd), but FireForge expects a locale directory such as toolkit/locales/en-US/toolkit/global or browser/locales/en-US/browser. Use the parent directory instead.`);
+    }
+    // Shape probe against the real filesystem when we have an engine
+    // directory to anchor against. The probe is best-effort: a missing
+    // engine directory or a not-yet-extracted locale tree is
+    // legitimate (an operator may `furnace init` before `fireforge
+    // download`), so we emit a warning rather than refusing.
+    if (engineDir) {
+        const resolved = join(engineDir, value);
+        try {
+            const info = await stat(resolved);
+            if (!info.isDirectory()) {
+                throw new FurnaceError(`ftlBasePath "${value}" resolves to a non-directory at ${resolved}. FireForge expects a locale directory (for example toolkit/locales/en-US/toolkit/global or browser/locales/en-US/browser).`);
+            }
+        }
+        catch (error) {
+            // FurnaceError (from the `isDirectory()` branch above) is a real
+            // shape failure — re-throw so the operator sees it.
+            if (error instanceof FurnaceError)
+                throw error;
+            // ENOENT is expected on a fresh project before `fireforge
+            // download` has populated engine/; only warn.
+            const code = typeof error === 'object' && error !== null && 'code' in error
+                ? error.code
+                : undefined;
+            if (code === 'ENOENT') {
+                warn(`ftlBasePath "${value}" does not yet exist at ${resolved}. This is fine if you have not run "fireforge download" yet; rerun "fireforge furnace init --force" after the engine is extracted to re-validate.`);
+            }
+            // Any other stat error is also best-effort ignored here — a
+            // permission issue or malformed engine checkout will surface on
+            // the next command that actually reads the FTL tree.
+        }
+    }
 }
 /**
  * Runs the furnace init command to create a default furnace.json with
@@ -42,8 +111,27 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
     if ((await furnaceConfigExists(projectRoot)) && !options.force) {
         throw new FurnaceError('furnace.json already exists. Use --force to overwrite it.');
     }
-    const config = createDefaultFurnaceConfig();
+    const paths = getProjectPaths(projectRoot);
+    // Seed the default furnace config with a tokenPrefix derived from
+    // fireforge.json's binaryName so `token coverage` sees real tokens on
+    // the very first run. The 2026-04-21 eval initialised Furnace, added
+    // tokens, ran coverage, and got `0 tokens / N unknown` — the prefix
+    // default was absent and the scan had nothing to key off. Loading
+    // fireforge.json here is best-effort: a project without one (e.g.
+    // mid-setup) falls through to the prefix-less default, and
+    // `token coverage` emits the existing "no tokenPrefix" warning.
+    let derivedBinaryName;
+    try {
+        const fireForgeConfig = await loadConfig(projectRoot);
+        derivedBinaryName = fireForgeConfig.binaryName;
+    }
+    catch {
+        // Best-effort only: initialising furnace without a fireforge.json is
+        // rare but not forbidden. Skip the prefix default in that case.
+    }
+    const config = createDefaultFurnaceConfig(derivedBinaryName ? { binaryName: derivedBinaryName } : {});
     const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const engineForValidation = (await pathExists(paths.engine)) ? paths.engine : undefined;
     // Resolve componentPrefix
     if (options.prefix !== undefined) {
         config.componentPrefix = options.prefix;
@@ -66,7 +154,7 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
     }
     // Resolve ftlBasePath
     if (options.ftlBasePath !== undefined) {
-        validateFtlBasePath(options.ftlBasePath);
+        await validateFtlBasePath(options.ftlBasePath, engineForValidation);
         config.ftlBasePath = options.ftlBasePath;
     }
     else if (isInteractive) {
@@ -80,7 +168,7 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
         }
         const ftlValue = ftlResult.trim();
         if (ftlValue) {
-            validateFtlBasePath(ftlValue);
+            await validateFtlBasePath(ftlValue, engineForValidation);
             config.ftlBasePath = ftlValue;
         }
     }

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/remove.js

@@ -3,6 +3,7 @@ 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';
@@ -353,6 +354,13 @@ 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 = [];