@hominis/fireforge 0.16.5 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.17.0
+
+### Eval-driven hardening
+
+- **`fireforge config` — serialised writes behind a sidecar lock.** The 2026-04-21 eval reproduced silent data loss by running two `fireforge config` invocations in parallel against the same `fireforge.json`: both commands exited `0`, but only one key survived. Atomic-rename writes (`writeJson`'s temp file + rename) prevented torn files but not lost updates: each writer read the pre-state, mutated its own copy, and the second rename clobbered the first writer's change. A new `withConfigFileLock(projectRoot, operation)` helper in `src/core/config.ts` wraps the read-modify-write cycle in `src/commands/config.ts:configCommand` — both the strict-validated and `--force` write branches now take the lock. Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: atomic rename means readers always see either the pre- or post-state, so only writers need to be serialised. Stale-lock recovery reuses the existing PID-alive probe from `withFileLock` so a crashed `fireforge config` does not wedge the next command.
+- **`fireforge token add --mode override` — dark values land inside the nested `:root { }`.** The previous `insertDarkModeOverride` in `src/core/token-manager.ts` found the outer `@media (prefers-color-scheme: dark) { }` block's closing `}` and spliced the dark-value declaration before that line — which is _after_ the nested `:root { }` had already closed, producing a declaration outside any rule block. The generated tokens CSS was syntactically malformed after every legitimate `token add --mode override` call, and `token coverage` no longer recognised the added tokens. The fix walks the comment-stripped line array to find the `:root {` opener _inside_ the `@media` block, then depth-counts to its own closing `}`, and inserts there. A fallback path (warn + synthesise a fresh nested `:root` before the outer close) handles malformed scaffolds where the nested `:root` was removed, so we never silently drop a dark value or emit a top-level declaration. The test coverage in `src/core/__tests__/token-manager.test.ts` now pins the invariant that the dark entry's line index must be _less_ than the inner `:root`'s closing `}`, so a future refactor cannot regress to the outer-block landing.
+- **`fireforge furnace rename` — cleans up deployed widgets, renames mochikit test + chrome.toml.** The previous `renameTestFiles` helper in `src/commands/furnace/rename.ts` handled the `browser/base/content/test/<binaryName>/` browser-chrome layout but not the `toolkit/content/tests/widgets/` mochikit layout, and `performRenameMutations` made no attempt to clear `engine/<oldTargetPath>/` after deployment. The 2026-04-21 eval renamed `ff-chip-row` → `ff-chip-stack` and ended up with `engine/toolkit/content/widgets/ff-chip-row/` still deployed, `test_ff-chip-row.html` still importing `chrome://global/content/elements/ff-chip-row.mjs`, and the `chrome.toml` entry still naming the old file. Two new helpers pick up the slack: `removeStaleDeployedComponentDir` snapshots + removes `engine/<oldTargetPath>/` so the next `furnace apply` is the sole writer of the new deployment; `renameMochikitTestFiles` snapshots the old scaffold, rewrites the chrome URI + class-test identifiers to the new name, and updates the widgets `chrome.toml` entry. Both run under the same rollback journal as the rest of the rename, so a later failure restores every touched path.
+- **`fireforge furnace create --with-tests` — scaffolded mochikit test runs to completion.** `generateMochikitTestContent` in `src/commands/furnace/create-templates.ts` previously emitted `SimpleTest.waitForExplicitFinish()` alongside an `add_task(...)` and no explicit `SimpleTest.finish()`. The test harness waits forever: `waitForExplicitFinish()` tells the harness not to finish on script end, and the `add_task`-managed finish never fires because the scaffold has no explicit `finish()` body. The 2026-04-21 eval's `fireforge test --headless toolkit/content/tests/widgets/test_ff-chip-row.html` hung until the operator SIGINT'd it. The fix removes the `waitForExplicitFinish()` call — `add_task` already calls `SimpleTest.finish()` when every queued task resolves, matching the convention upstream widget tests (`toolkit/content/tests/widgets/test_moz-button.html` and siblings) use. A regression test in `src/commands/furnace/__tests__/create-mochikit.test.ts` pins the contract that the generated content must not contain `waitForExplicitFinish`.
+- **`fireforge furnace chrome-doc create --with-tests` — packaging test probes the correct packaged CSS path.** `generateChromeDocPackagingTest` in `src/commands/furnace/chrome-doc-tests.ts` probed `<AppDir>/chrome/browser/skin/classic/browser/<name>-chrome.css`, but the `jar.inc.mn` entry in `chrome-doc-templates.ts:chromeDocJarIncMnCssEntry` registers the file at `content/browser/<name>-chrome.css` — so the packaged location is `.../chrome/browser/content/browser/<name>-chrome.css`, not the skin layout. The 2026-04-21 eval's `fireforge test --build` against a scaffolded chrome-doc failed with a spurious "missing" assertion even though the file was correctly packaged. Both the primary probe and the macOS `.app`-bundle fallback now name the `content/browser/` layout, and a negative-match test guards against anyone pinning it back to `skin/classic/browser/` in a future refactor.
+- **`fireforge status --json` — cross-patch ownership conflicts surface as `conflict` with `claimedBy`.** `classifyFiles` in `src/commands/status.ts` tracked patch ownership as a `Set<string>` and collapsed multi-owner paths into the single-owner branch, where the content-compare then routed them into `unmanaged` when the engine content didn't match any single patch's expected result. The 2026-04-21 eval's `status --json` run reported `"classification": "unmanaged"` on two files that `status --ownership` correctly labelled `CONFLICT` — scripts built on the JSON view mis-diagnosed the drift and could have taken the wrong corrective action. The classifier now builds a `Map<string, string[]>` (filename → claiming patch filenames), emits `classification: "conflict"` for entries claimed by two or more patches, and attaches `claimedBy: string[]` to those entries so machine consumers can read the ownership set directly. The human default-mode output now surfaces a `Cross-patch ownership conflicts` section at the top pointing at `status --ownership` and `re-export --files` for recovery. Single-claim entries stay byte-identical to the pre-0.16.0 JSON shape (no unconditional `claimedBy` field) so parsers unaware of the new classification continue to work.
+- **`fireforge furnace init --ftl-base-path` — rejects file-shaped values up-front.** `validateFtlBasePath` in `src/commands/furnace/init.ts` only enforced syntactic safety (no absolute paths, no `..`, no null bytes). A plausible-but-invalid value like `browser/forgefresh.ftl` passed the gate, and the next localized `furnace create` scaffolded a component whose generated `.mjs` referenced `insertFTLIfNeeded("<name>.ftl")` while `furnace.json` never got the component entry — the scaffold was orphaned, every follow-up command failed with "not found in furnace.json", and the 2026-04-21 eval recorded this as Finding #5 (apparent non-registration) whose real root cause was Finding #6 (bad `ftlBasePath`). The validator now refuses any value whose basename carries `.ftl`, `.properties`, or `.dtd` with a message that names the file and points at a locale directory (`toolkit/locales/en-US/toolkit/global` or `browser/locales/en-US/browser`). When the engine directory is present on disk, it additionally probes whether the resolved path is a directory and warns (non-blocking) if the path does not yet exist — a fresh project that has not `fireforge download`-ed yet is legitimate.
+- **`fireforge furnace init` — defaults `tokenPrefix` from `fireforge.json`'s `binaryName`.** `createDefaultFurnaceConfig` previously accepted no arguments and omitted `tokenPrefix` entirely, so every fresh project that ran `furnace init` → `token add` → `token coverage` got `0 tokens` and "all unknown" reports until the operator discovered the missing key and hand-edited `furnace.json`. The helper now accepts `{ binaryName }` and, when passed, seeds `tokenPrefix: \`--${binaryName}-\``so the coverage scan has a prefix to key off immediately.`furnaceInitCommand`best-effort-loads`fireforge.json`and threads the binaryName through — a project that initialises Furnace before`fireforge setup`completes still gets a valid prefix-less default (and`token coverage` continues to warn when invoked without a prefix set).
+- **`fireforge build` + `fireforge build --ui` — per-project build lock prevents overlap.** A second `fireforge build --ui` launched while a full `fireforge build` was still running against the same engine tree raced the `obj-*` directory and failed immediately with `No rule to make target 'XUL'` — mach's downstream consequence of an incomplete backend, not a clue that the overlap was the root cause. A new `withBuildLock(projectRoot, operation)` in `src/core/mach.ts` backs onto `withFileLock` at `.fireforge-build.lock` beside the project root; `buildCommand` in `src/commands/build.ts` wraps both `build()` and `buildUI()` call paths in the lock. The refusal message names the holder PID and points at the stale-lock recovery path. Timeouts are bumped to 24h (a slow full build legitimately exceeds the default 30s) but the lock releases on process exit or via PID-alive stale recovery so a crashed build cannot permanently wedge the next invocation. A dedicated integration test in `src/core/__tests__/build-lock.integration.test.ts` pins the serialisation, throw-propagation, and stale-recovery contracts.
+- **`fireforge wire --dry-run` — insertion-point probe runs in both modes.** The dry-run branch previously skipped the `pathExists(join(paths.engine, domTargetPath))` check that the real-run branch ran, and even with existence confirmed the real run could still throw `Could not find insertion point in chrome document` from deep inside `addDomFragment` when the resolved chrome doc offered neither `#include browser-sets.inc` nor `<html:body>`. The 2026-04-21 eval's `wire ... --dom ... --dry-run` previewed a plausible plan targeting `tokenHostDocuments[0]`, then the same command without `--dry-run` failed against a `furnace chrome-doc create`-scaffolded document that lacked both anchors. A new `probeDomFragmentInsertionPoint` helper in `src/core/wire-dom-fragment.ts` reads the chrome doc and runs the same tokenised + legacy insertion-point scan the real run uses; `wireCommand` now calls it in both modes and surfaces the `Could not find insertion point` error before printing the plan. The dry-run preview now refuses the same cases the real run would refuse, before any operator commits to executing.
+- **`fireforge resolve` — `--yes` escape hatch + clearer two-step messaging.** The command refused any non-interactive invocation even after a CI-assisted manual merge was complete, because the TTY guard ran unconditionally — scripted recovery flows could complete the merge but could not then record the refreshed patch body. A new `--yes` / `-y` flag in `src/commands/resolve.ts` skips the interactive `confirm(...)` prompt and passes through in non-interactive mode; the unconditional TTY refusal fires only when the flag is absent. The command description changes from `Update a broken patch with manual fixes and continue` to `Update a broken patch with manual fixes (then run "fireforge import" to resume the queue)`, and the post-success info line now names the second-step command explicitly — the old copy implied a one-step flow where operators sometimes believed resolve continued the queue itself. Help snapshot under `src/__tests__/__snapshots__/help.test.ts.snap` is refreshed to match; resolve tests cover both the `--yes`-in-non-TTY path and the continuation messaging.
+- **`fireforge test` — marionette port probe catches stale browsers before mach launches.** An interrupted `fireforge test --headless` run can leave a `<binaryName> -marionette` child listening on port `2828` with parent PID `1`. The next `fireforge test` run — potentially in a sibling FireForge project — fails immediately with a mach Marionette bind error that points nowhere near the real cause, and the generic "delete obj-\* and rebuild" guidance wastes operator time. A new `probeMarionettePort` / `assertMarionettePortAvailable` pair in `src/core/marionette-port.ts` runs `lsof -i tcp:2828 -sTCP:LISTEN` (POSIX) or `Get-NetTCPConnection` (Windows) before every test launch; when the holder's basename or command line identifies a Firefox-family browser (including `binaryName` from `fireforge.json` for branded forks), the probe raises a targeted `GeneralError` naming the PID and the exact `kill` command. Unrelated listeners produce a softer "this is not a FireForge-launched browser" error so the operator can tell the two cases apart. The probe is best-effort: missing `lsof`/PowerShell falls back to `{ inUse: false }` rather than failing the test run itself.
+- **`fireforge lint` (default) — aggregate-mode skips tool-managed branding.** `resolveLintDiff` in `src/commands/lint.ts` passed the full `getAllDiff(engineDir)` to `lintExportedPatch` when no file list was supplied, so a fresh-setup workspace with 63 modified branding files fired `large-patch-lines`, `large-patch-files`, and `missing-license-header` on tool-managed content the operator never authored. The 2026-04-21 eval's first `fireforge lint` on a newly-built `fresh/` tree failed with blocking patch-lint errors despite the project being minimal-customisation. The aggregate-mode branch now loads `fireforge.json`'s `binaryName`, partitions the dirty tree with `isBrandingManagedPath`, and passes only the non-branding paths into `getDiffForFilesAgainstHead`. The operator sees a one-line `info()` naming the excluded count so the exclusion is visible, not silent. Explicit-path mode (`fireforge lint <path>`) preserves the previous behaviour — passing a branding path explicitly still lints it, so operators who need to audit generated branding content can do so.
+- **`fireforge doctor --repair-patches-manifest` — names every reconstructed entry.** `rebuildPatchesManifest` previously returned only the rebuilt manifest, silently overwriting `description` / `createdAt` with generic fallback values when the existing entry was missing. FireForge patch files do not carry header metadata that could carry human-written descriptions forward, so full fidelity is impossible — but at least visibility is. The helper now returns `{ manifest, recoveredFilenames }` in `src/core/patch-manifest-consistency.ts`; the doctor repair path prints a per-filename `warn(...)` telling the operator exactly which manifest entry was reconstructed from generic defaults and suggesting they edit `patches.json` if they have the original description backed up. The summary row count now reports both the total patches rebuilt and the subset that needed reconstruction.
+
 ## 0.16.0
 
 ### UX, correctness, and consistency

package/README.md

@@ -174,7 +174,7 @@ When `fireforge import` fails on a patch, fix the `.rej` files in `engine/`, the
 fireforge resolve
 ```
 
-This re-exports the fixed patch and continues applying the remaining stack.
+This re-exports the fixed patch and clears the conflict state. The command is deliberately a single-patch refresh — to continue applying the remainder of the queue, run `fireforge import` afterwards. For scripted or CI-driven recovery, pass `--yes` (or `-y`) to skip the interactive "are you done?" prompt; the flag is the explicit opt-in for non-interactive use once the manual merge is complete.
 
 <details>
 <summary>Patch manifest format</summary>
@@ -211,7 +211,7 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 `fireforge lint` runs automatically during export, export-all and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
 
-By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further; the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
+By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed — with tool-managed branding paths (`browser/branding/<binaryName>/`) excluded. A fresh-setup workspace carries a large generated branding diff that operators did not author directly, and letting it through tripped the patch-size and license-header rules on content that matches the `branding` bucket in `fireforge status`. When the exclusion fires the command prints a one-line note naming the excluded count so the filter is visible. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further — explicit-path mode does lint branding files (the operator's explicit request wins over the branding exclusion); the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
 
 | Check                          | Scope                                                                     | Severity                 |
 | ------------------------------ | ------------------------------------------------------------------------- | ------------------------ |
@@ -409,6 +409,8 @@ fireforge config firefox.version 145.0.0esr
 fireforge config customKey "value" --force
 ```
 
+Writes are serialised behind a sidecar lock — two concurrent `fireforge config` invocations against the same `fireforge.json` (for example, parallel automation steps) queue instead of racing the read-modify-write. The lock is released automatically on process exit; stale locks from a crashed earlier command are reclaimed on the next invocation via the PID-alive probe.
+
 ### Patch queue management
 
 ```bash
@@ -440,7 +442,7 @@ fireforge watch
 fireforge token add --category 'Colors — General' -- --my-color 'light-dark(#fff, #000)'
 ```
 
-Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` also registers the tokens CSS path in `patchLint.rawColorAllowlist` so raw color literals inside it are not flagged by `fireforge lint`.
+Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` also registers the tokens CSS path in `patchLint.rawColorAllowlist` so raw color literals inside it are not flagged by `fireforge lint`, and derives `tokenPrefix: --<binaryName>-` from `fireforge.json`'s `binaryName` so `fireforge token coverage` has a prefix to key off on the very first run. Projects that prefer a different prefix can override it in `furnace.json` after init.
 
 ### Diff-scoped lint (`lint --since`)
 

package/dist/src/commands/build.js

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

package/dist/src/commands/config.js

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

package/dist/src/commands/doctor.js

@@ -314,7 +314,20 @@ const DOCTOR_CHECKS = [
             }
             try {
                 const repaired = await rebuildPatchesManifest(ctx.paths.patches, ctx.config.firefox.version);
-                return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.patches.length} patch${repaired.patches.length === 1 ? '' : 'es'}. Review recovered metadata before release.`);
+                // 2026-04-21 eval (Finding #17): the repair path silently
+                // overwrote useful human-written descriptions on recovered
+                // entries, leaving the queue less trustworthy as an audit
+                // trail. The rebuilder now returns the list of filenames
+                // whose metadata was entirely invented, and we name them
+                // explicitly here so the operator knows exactly which
+                // patches to review. Names that DID have a preserved entry
+                // (only `filesAffected` / ordering drifted) are not flagged.
+                if (repaired.recoveredFilenames.length > 0) {
+                    for (const filename of repaired.recoveredFilenames) {
+                        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. Edit patches.json to restore the original description if you have it backed up.`);
+                    }
+                }
+                return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.manifest.patches.length} patch${repaired.manifest.patches.length === 1 ? '' : 'es'}${repaired.recoveredFilenames.length > 0 ? ` (${repaired.recoveredFilenames.length} with reconstructed metadata — see warnings above)` : ''}. Review recovered metadata before release.`);
             }
             catch (err) {
                 return failure('Patch manifest consistency', toError(err).message, 'Repair failed. Fix the underlying patch metadata issue and retry the doctor command.');

package/dist/src/commands/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/rename.js

@@ -122,6 +122,94 @@ async function renameTestFiles(engineDir, projectRoot, oldName, newName, journal
         }
     }
 }
+/**
+ * Removes the deployed custom-widget directory at the old target path so
+ * a subsequent `furnace apply` is the single writer of the new name's
+ * deployment. Best-effort: logs a warning but never blocks the rename.
+ *
+ * 2026-04-21 eval: renaming `ff-chip-row` → `ff-chip-stack` registered
+ * and deployed the new name correctly but left `engine/toolkit/content/
+ * widgets/ff-chip-row/` in place. Subsequent `furnace sync` runs could
+ * not clear the stale widget, and packaging would have pulled in both
+ * copies. The snapshot is taken before the remove so the rollback
+ * journal restores the old directory if any later step in
+ * `performRenameMutations` fails.
+ */
+async function removeStaleDeployedComponentDir(engineDir, oldTargetPath, journal) {
+    const oldDeployed = join(engineDir, oldTargetPath);
+    if (!(await pathExists(oldDeployed)))
+        return;
+    try {
+        await snapshotDir(journal, oldDeployed);
+        await removeDir(oldDeployed);
+        info(`Removed stale deployed widget directory: ${oldTargetPath}`);
+    }
+    catch (error) {
+        warn(`Could not remove stale deployed widget directory at ${oldTargetPath}: ${toError(error).message}. Remove it manually if needed.`);
+    }
+}
+/**
+ * Renames the mochikit test scaffold produced by `furnace create
+ * --with-tests` when the default test style is used. The scaffold lives
+ * at `engine/toolkit/content/tests/widgets/test_<name>.html`, and the
+ * accompanying `chrome.toml` entry names the same file. Neither piece
+ * was handled by the pre-0.16.0 rename, so operators were left with a
+ * `test_<old>.html` file that still imported `chrome://global/content/
+ * elements/<old>.mjs` and referenced `customElements.whenDefined("<old>")`
+ * — the test ran against a component that no longer existed under that
+ * name and either failed or (if the old component was still deployed)
+ * passed for the wrong reason.
+ *
+ * Best-effort: individual failures log a warning. The same journal used
+ * for the rest of the rename snapshots every touched file so a later
+ * failure rolls the pair back together.
+ */
+async function renameMochikitTestFiles(engineDir, oldName, newName, journal) {
+    const testDir = join(engineDir, 'toolkit/content/tests/widgets');
+    if (!(await pathExists(testDir)))
+        return;
+    const oldTestFileName = `test_${oldName}.html`;
+    const newTestFileName = `test_${newName}.html`;
+    const oldTestPath = join(testDir, oldTestFileName);
+    const newTestPath = join(testDir, newTestFileName);
+    if (await pathExists(oldTestPath)) {
+        try {
+            await snapshotFile(journal, oldTestPath);
+            const content = await readText(oldTestPath);
+            const updatedContent = content
+                .replace(new RegExp(`chrome://global/content/elements/${escapeRegex(oldName)}\\.mjs`, 'g'), `chrome://global/content/elements/${newName}.mjs`)
+                .replace(new RegExp(`customElements\\.whenDefined\\("${escapeRegex(oldName)}"\\)`, 'g'), `customElements.whenDefined("${newName}")`)
+                .replace(new RegExp(`Test the ${escapeRegex(oldName)} `, 'g'), `Test the ${newName} `)
+                .replace(new RegExp(`add_task\\(async function test_${escapeRegex(oldName.replace(/-/g, '_'))}_defined\\(`, 'g'), `add_task(async function test_${newName.replace(/-/g, '_')}_defined(`)
+                .replace(new RegExp(`"${escapeRegex(oldName)} custom element`, 'g'), `"${newName} custom element`);
+            await writeText(newTestPath, updatedContent);
+            await removeFile(oldTestPath);
+            info(`Renamed mochikit test: ${oldTestFileName} → ${newTestFileName}`);
+        }
+        catch (error) {
+            warn(`Could not rename mochikit test file — ${toError(error).message}. Rename it manually if needed.`);
+        }
+    }
+    // Update `chrome.toml` entry if present. The file may live in the
+    // same widgets/tests directory as the test file itself; upstream
+    // convention places exactly one `chrome.toml` there for all widget
+    // scaffolds.
+    const chromeTomlPath = join(testDir, 'chrome.toml');
+    if (await pathExists(chromeTomlPath)) {
+        try {
+            const toml = await readText(chromeTomlPath);
+            if (toml.includes(`["${oldTestFileName}"]`)) {
+                await snapshotFile(journal, chromeTomlPath);
+                const updated = toml.replace(`["${oldTestFileName}"]`, `["${newTestFileName}"]`);
+                await writeText(chromeTomlPath, updated);
+                info(`Updated chrome.toml: ${oldTestFileName} → ${newTestFileName}`);
+            }
+        }
+        catch (error) {
+            warn(`Could not update widgets chrome.toml — ${toError(error).message}. Update it manually if needed.`);
+        }
+    }
+}
 /**
  * Performs the transactional rename mutation inside a furnace lock.
  */
@@ -129,6 +217,11 @@ async function performRenameMutations(args) {
     const { projectRoot, oldName, newName, oldDir, newDir, isCustom, componentType, config } = args;
     const oldClassName = tagNameToClassName(oldName);
     const newClassName = tagNameToClassName(newName);
+    // Capture the pre-rename deployed target path so we know what to
+    // clean up in the engine tree. `updateConfigForCustomRename` rewrites
+    // `targetPath` in-place once the mutation enters phase 2, so we read
+    // it here while it still points at the old name's deployment.
+    const oldCustomTargetPath = isCustom ? config.custom[oldName]?.targetPath : undefined;
     await runFurnaceMutation(projectRoot, 'rename-rollback', async (ctx) => {
         const journal = createRollbackJournal();
         ctx.registerJournal(journal);
@@ -197,6 +290,23 @@ async function performRenameMutations(args) {
             // 7. Rename test files created by `furnace create --with-tests` (custom only).
             if (isCustom && (await pathExists(args.engineDir))) {
                 await renameTestFiles(args.engineDir, projectRoot, oldName, newName, journal);
+                // Mochikit scaffold + widgets/chrome.toml live in a different
+                // tree than browser.toml-registered browser-chrome tests, so
+                // renameTestFiles doesn't reach them. 2026-04-21 eval: a rename
+                // left `engine/toolkit/content/tests/widgets/test_<old>.html`
+                // and its `chrome.toml` entry pointing at the old name, which
+                // either failed the test run outright or (worse) passed for the
+                // wrong component.
+                await renameMochikitTestFiles(args.engineDir, oldName, newName, journal);
+                // Clear the stale deployed component directory so the next
+                // `furnace apply` is the single writer of the new name's
+                // deployment. Without this, eval runs showed the old widget
+                // still living at `engine/toolkit/content/widgets/<old>/`
+                // alongside the newly-deployed `engine/toolkit/content/
+                // widgets/<new>/`, with no signal to `status` / `verify`.
+                if (oldCustomTargetPath) {
+                    await removeStaleDeployedComponentDir(args.engineDir, oldCustomTargetPath, journal);
+                }
             }
             info(`Renamed ${componentType} component: ${oldName} → ${newName}`);
         }