@hominis/fireforge 0.16.2 → 0.16.5

package/dist/src/commands/token.js

@@ -106,7 +106,18 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
 }
 /** Registers token management commands on the CLI program. */
 export function registerToken(program, { getProjectRoot, withErrorHandling }) {
-    const token = program.command('token').description('Design token management');
+    const token = program
+        .command('token')
+        .description('Design token management')
+        // Match `fireforge furnace`'s no-args contract: print the group's help and
+        // exit 0. Without this default action, commander routes `fireforge token`
+        // (no subcommand) through its own help-then-exit-1 path, so scripts that
+        // probe the CLI surface see a misleading non-zero exit for a purely
+        // informational invocation. The action prints the exact same help commander
+        // would otherwise print, but returns successfully.
+        .action(() => {
+        token.outputHelp();
+    });
     token
         .command('add <token-name> <value>')
         .description('Add a design token to CSS and documentation')
@@ -117,7 +128,13 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
     // valid choices up-front. The runtime check in tokenAddCommand remains
     // as a defence-in-depth guard for programmatic callers that bypass
     // Commander's argument parsing.
-    new Option('--mode <mode>', 'Dark mode behavior')
+    // Description ends with `(required)` because Commander's
+    // `makeOptionMandatory` does not render a required marker in `--help`
+    // output — only `.requiredOption` does that, and switching to
+    // `.requiredOption` would lose the `.choices()` enforcement. The
+    // explicit suffix keeps the runtime validation AND surfaces required
+    // status in help alongside the other options that use `.requiredOption`.
+    new Option('--mode <mode>', 'Dark mode behavior (required)')
         .choices(['auto', 'static', 'override'])
         .makeOptionMandatory(true))
         .option('--description <desc>', 'Comment description for the CSS file')

package/dist/src/commands/wire.js

@@ -5,6 +5,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
 import { consumeParserFallbackEvents } from '../core/parser-fallback.js';
 import { DEFAULT_DOM_TARGET } from '../core/wire-dom-fragment.js';
+import { coerceToCall, validateWireName as validateWireExpression } from '../core/wire-utils.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -17,10 +18,14 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPa
     info(`  source: ${subscriptDir}/${name}.js`);
     info(`  browser-main.js: loadSubScript("chrome://browser/content/${name}.js")`);
     if (options.init) {
-        info(`  browser-init.js: ${options.init}`);
+        // Show the coerced form so the preview matches the emitted block.
+        // Before 0.16.0 the preview echoed the raw input ("EvalStartup.init"),
+        // which did not reflect that the real run writes `EvalStartup.init();`
+        // to browser-init.js.
+        info(`  browser-init.js: ${coerceToCall(options.init)}`);
     }
     if (options.destroy) {
-        info(`  browser-init.js onUnload(): ${options.destroy}`);
+        info(`  browser-init.js onUnload(): ${coerceToCall(options.destroy)}`);
     }
     if (domFilePath) {
         const includePath = relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)).replace(/\\/g, '/');
@@ -95,6 +100,21 @@ export async function wireCommand(projectRoot, name, options = {}) {
         // --after and have it forwarded unchanged to the lookup layer.
         validateWireName(options.after);
     }
+    // Validate init/destroy expressions BEFORE the dry-run/real fork so
+    // both paths enforce the same contract. Pre-0.16.0, validation only
+    // ran inside `addInitToBrowserInit`/`addDestroyToBrowserInit` (the
+    // real-execution path), so `--dry-run --init 'void 0'` succeeded and
+    // rendered a plausible-looking preview even though the real run would
+    // reject the same arguments. Dropping `void 0` into the template
+    // silently (or breaking out of the string literal) was already
+    // prevented downstream — this hoist just makes the failure surface
+    // identical in preview mode.
+    if (options.init !== undefined) {
+        validateWireExpression(options.init, 'init expression');
+    }
+    if (options.destroy !== undefined) {
+        validateWireExpression(options.destroy, 'destroy expression');
+    }
     consumeParserFallbackEvents();
     // Resolve subscript directory: CLI flag > fireforge.json > default
     let subscriptDir = DEFAULT_BROWSER_SUBSCRIPT_DIR;

package/dist/src/core/branding.d.ts

@@ -1,4 +1,5 @@
 import { FireForgeError } from '../errors/base.js';
+import type { ProjectLicense } from '../types/config.js';
 /**
  * Error thrown when branding operations fail.
  */
@@ -41,6 +42,15 @@ export interface BrandingConfig {
     appId: string;
     /** Binary/branding directory name (e.g., "mybrowser") */
     binaryName: string;
+    /**
+     * Project license (from fireforge.json). Used to stamp the generated
+     * `configure.sh`, `brand.properties`, and `brand.ftl` files with the
+     * matching header so `patch-lint` does not flag them for
+     * `missing-license-header` when the project is not MPL-2.0. Optional for
+     * backwards compatibility with pre-0.16 callers that did not thread the
+     * license through — falls back to {@link DEFAULT_LICENSE}.
+     */
+    license?: ProjectLicense;
 }
 /**
  * Sets up the custom branding directory for the browser.

package/dist/src/core/branding.js

@@ -4,6 +4,7 @@ import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { copyDir, pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
+import { DEFAULT_LICENSE, getLicenseHeader } from './license-headers.js';
 /**
  * Error thrown when branding operations fail.
  */
@@ -91,9 +92,8 @@ async function createConfigureScript(brandingDir, config) {
     await writeTextIfChanged(configureShPath, buildConfigureScriptContent(config));
 }
 function buildConfigureScriptContent(config) {
-    return `# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    const header = getLicenseHeader(config.license ?? DEFAULT_LICENSE, 'hash');
+    return `${header}
 
 MOZ_APP_DISPLAYNAME="${escapeShellValue(config.name)}"
 MOZ_MACBUNDLE_ID="${escapeShellValue(config.appId)}"
@@ -111,9 +111,8 @@ async function updateBrandProperties(brandingDir, config) {
     await writeTextIfChanged(propsPath, buildBrandPropertiesContent(config));
 }
 function buildBrandPropertiesContent(config) {
-    return `# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    const header = getLicenseHeader(config.license ?? DEFAULT_LICENSE, 'hash');
+    return `${header}
 
 brandShorterName=${escapePropertiesValue(config.name)}
 brandShortName=${escapePropertiesValue(config.name)}
@@ -132,9 +131,8 @@ async function updateBrandFtl(brandingDir, config) {
     await writeTextIfChanged(ftlPath, buildBrandFtlContent(config));
 }
 function buildBrandFtlContent(config) {
-    return `# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    const header = getLicenseHeader(config.license ?? DEFAULT_LICENSE, 'hash');
+    return `${header}
 
 ## Brand names
 ##

package/dist/src/core/build-prepare.js

@@ -123,12 +123,19 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     }
     // Clean stories before build to ensure they don't leak into production binary
     await cleanStories(paths.engine);
-    // Set up custom branding directory and patch moz.configure
+    // Set up custom branding directory and patch moz.configure. Thread the
+    // project license through so `buildConfigureScriptContent` /
+    // `buildBrandPropertiesContent` / `buildBrandFtlContent` stamp the
+    // generated files with a matching SPDX header — otherwise `patch-lint`
+    // flags them with `missing-license-header` on every subsequent export
+    // when the project is not MPL-2.0 (the eval finding: a 0BSD-licensed
+    // fork's first export failed `lint` on its own generated branding).
     const brandingConfig = {
         name: config.name,
         vendor: config.vendor,
         appId: config.appId,
         binaryName: config.binaryName,
+        ...(config.license !== undefined ? { license: config.license } : {}),
     };
     if (!(await isBrandingSetup(paths.engine, brandingConfig))) {
         const brandingSpinner = spinner('Setting up branding...');

package/dist/src/core/file-lock.js

@@ -43,23 +43,39 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     try {
         const lockStat = await stat(lockPath);
         const ageMs = Date.now() - lockStat.mtimeMs;
-        if (ageMs <= staleMs) {
-            return false;
-        }
-        // If the lock directory contains a PID file, check whether the owning
-        // process is still running before removing. This prevents premature
-        // removal when a slow operation (e.g. mach build) legitimately holds
-        // the lock past the stale threshold.
-        try {
-            const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
-            const pid = parseInt(pidContent.trim(), 10);
-            if (Number.isFinite(pid) && isProcessAlive(pid)) {
-                verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${pid} is still running — not removing`);
-                return false;
+        // Check PID FIRST, independent of age. Before this ordering change the
+        // function age-gated everything: a lock younger than `staleMs` (default
+        // 5 minutes) was never removed even when its PID file pointed at a
+        // process that had already exited. That's the exact situation an
+        // operator lands in after SIGINT'ing `furnace preview` — the signal
+        // handler calls `process.exit`, `withFileLock`'s `finally { rm }`
+        // never runs, and the next command has to either wait 5 minutes for
+        // the staleness gate or manually remove the lock directory. With the
+        // PID-first check, an explicitly-dead owner unblocks immediately.
+        const pidCheck = await readLockOwnerPid(lockPath);
+        if (pidCheck.present) {
+            if (!isProcessAlive(pidCheck.pid)) {
+                const staleMessage = onStaleLockMessage?.(ageMs);
+                if (staleMessage) {
+                    warn(staleMessage);
+                }
+                else {
+                    verbose(`Lock at ${lockPath} owner PID ${pidCheck.pid} is no longer running — removing (age: ${Math.round(ageMs / 1000)}s)`);
+                }
+                await rm(lockPath, { recursive: true, force: true });
+                return true;
             }
+            // PID is alive — respect it regardless of age. A slow `mach build`
+            // legitimately holds the lock past the stale threshold and we don't
+            // want to race-remove it.
+            verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${pidCheck.pid} is still running — not removing`);
+            return false;
         }
-        catch {
-            // No PID file or unreadable — fall through to stale removal
+        // No readable PID file. Fall back to the age-only heuristic so locks
+        // written by earlier FireForge releases (which may not have written a
+        // PID file) still clear after the staleness window elapses.
+        if (ageMs <= staleMs) {
+            return false;
         }
         const staleMessage = onStaleLockMessage?.(ageMs);
         if (staleMessage) {
@@ -78,6 +94,24 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
         throw toError(error);
     }
 }
+/**
+ * Reads the owner PID from a lock directory's PID file. Returns `{ present:
+ * false }` when the PID file is missing or the content does not parse as a
+ * finite integer (caller falls back to the age-only staleness heuristic).
+ */
+async function readLockOwnerPid(lockPath) {
+    try {
+        const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
+        const pid = parseInt(pidContent.trim(), 10);
+        if (Number.isFinite(pid)) {
+            return { present: true, pid };
+        }
+    }
+    catch {
+        // PID file missing or unreadable — treat as absent.
+    }
+    return { present: false };
+}
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
 export async function withFileLock(lockPath, operation, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;

package/dist/src/core/furnace-operation.d.ts

@@ -74,6 +74,23 @@ export declare function rollbackActiveOperationsForSignal(signal: FurnaceShutdow
  * touch this directly.
  */
 export declare function getFurnaceLockPath(root: string): string;
+/**
+ * Forcibly removes the furnace lock directory for every active operation.
+ *
+ * The bin-layer signal handler calls `process.exit` after rollback, which
+ * short-circuits Node's normal unwinding — `withFileLock`'s `finally { rm
+ * }` never runs, so the lock directory survives the process. The next
+ * FireForge command then has to either wait out the staleness window or
+ * have the operator remove the lock manually. This sweeper runs inside
+ * the signal-handler pipeline BEFORE `process.exit`, so the lock is gone
+ * by the time the next command starts.
+ *
+ * Errors are logged and swallowed: we do not want a slow I/O failure at
+ * shutdown to prevent the process from exiting. The doctor-side stale
+ * lock check (`src/commands/doctor-furnace.ts`) is the backup path for
+ * any lock that escapes this sweep.
+ */
+export declare function forceReleaseFurnaceLocksForActiveOperations(): Promise<void>;
 /**
  * Runs a furnace-mutating body under the apply-wide lock and registers it
  * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents

package/dist/src/core/furnace-operation.js

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
-import { warn } from '../utils/logger.js';
+import { verbose, warn } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { withFileLock } from './file-lock.js';
 import { loadFurnaceState, updateFurnaceState } from './furnace-config.js';
@@ -136,6 +137,34 @@ async function persistPendingRepair(root, operation, reason) {
 export function getFurnaceLockPath(root) {
     return join(root, FIREFORGE_DIR, FURNACE_LOCK_FILENAME);
 }
+/**
+ * Forcibly removes the furnace lock directory for every active operation.
+ *
+ * The bin-layer signal handler calls `process.exit` after rollback, which
+ * short-circuits Node's normal unwinding — `withFileLock`'s `finally { rm
+ * }` never runs, so the lock directory survives the process. The next
+ * FireForge command then has to either wait out the staleness window or
+ * have the operator remove the lock manually. This sweeper runs inside
+ * the signal-handler pipeline BEFORE `process.exit`, so the lock is gone
+ * by the time the next command starts.
+ *
+ * Errors are logged and swallowed: we do not want a slow I/O failure at
+ * shutdown to prevent the process from exiting. The doctor-side stale
+ * lock check (`src/commands/doctor-furnace.ts`) is the backup path for
+ * any lock that escapes this sweep.
+ */
+export async function forceReleaseFurnaceLocksForActiveOperations() {
+    const paths = new Set([...activeOperations.values()].map((op) => getFurnaceLockPath(op.root)));
+    for (const lockPath of paths) {
+        try {
+            await rm(lockPath, { recursive: true, force: true });
+            verbose(`Removed furnace lock at ${lockPath} during signal teardown`);
+        }
+        catch (error) {
+            verbose(`Could not remove furnace lock at ${lockPath} during signal teardown: ${toError(error).message}`);
+        }
+    }
+}
 /**
  * Runs a furnace-mutating body under the apply-wide lock and registers it
  * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents

package/dist/src/core/furnace-validate-helpers.d.ts

@@ -61,7 +61,39 @@ export declare function stripCssBlockComments(content: string): string;
 export declare function hasRelativeModuleImport(mjsContent: string): boolean;
 /** Detects whether a module defines a custom element at runtime. */
 export declare function hasCustomElementDefineCall(mjsContent: string): boolean;
-/** Checks whether a declared component class extends MozLitElement. */
+/**
+ * Detects whether the module's `customElements.define(...)` call includes a
+ * literal `extends:` option (third argument). That shape is the marker for
+ * a customized built-in element — the class extends a specific
+ * `HTMLxxxElement` rather than the autonomous `MozLitElement` path.
+ *
+ * Firefox's own widgets use this pattern for toolkit anchors (e.g.
+ * `moz-support-link` extends `HTMLAnchorElement` with
+ * `customElements.define("moz-support-link", ..., { extends: "a" })`), and
+ * the validator's `not-moz-lit-element` check must allow them through or
+ * `furnace override` of a valid upstream component fails its own
+ * `furnace validate` pass with nothing the operator can fix.
+ */
+export declare function hasCustomElementExtendsOption(mjsContent: string): boolean;
+/**
+ * Checks whether a declared component class extends a valid element base.
+ *
+ * Two shapes are accepted:
+ *
+ * 1. Autonomous custom element: `class X extends MozLitElement` — the
+ *    default FireForge pattern for fork-authored components and most
+ *    toolkit widgets.
+ * 2. Customized built-in: `class X extends HTML<Something>Element` paired
+ *    with a `customElements.define(..., ..., { extends: "<tagname>" })`
+ *    call. Firefox's `moz-support-link`, `moz-button-group` tabbing
+ *    widgets, and a handful of other toolkit components use this form;
+ *    `furnace override` of those components writes the original source
+ *    verbatim and the validator must not reject them.
+ *
+ * A class that extends a plain `HTMLElement` WITHOUT a `extends:` option
+ * is still rejected — that's the legitimate `not-moz-lit-element` case
+ * the rule was originally designed to catch.
+ */
 export declare function classExtendsMozLitElement(mjsContent: string): boolean;
 /** Collects CSS custom property references used via var(--token-name). */
 export declare function collectCssVariableReferences(cssContent: string): string[];

package/dist/src/core/furnace-validate-helpers.js

@@ -269,7 +269,46 @@ export function hasRelativeModuleImport(mjsContent) {
 export function hasCustomElementDefineCall(mjsContent) {
     return /customElements\.define\s*\(/.test(mjsContent);
 }
-/** Checks whether a declared component class extends MozLitElement. */
+/**
+ * Detects whether the module's `customElements.define(...)` call includes a
+ * literal `extends:` option (third argument). That shape is the marker for
+ * a customized built-in element — the class extends a specific
+ * `HTMLxxxElement` rather than the autonomous `MozLitElement` path.
+ *
+ * Firefox's own widgets use this pattern for toolkit anchors (e.g.
+ * `moz-support-link` extends `HTMLAnchorElement` with
+ * `customElements.define("moz-support-link", ..., { extends: "a" })`), and
+ * the validator's `not-moz-lit-element` check must allow them through or
+ * `furnace override` of a valid upstream component fails its own
+ * `furnace validate` pass with nothing the operator can fix.
+ */
+export function hasCustomElementExtendsOption(mjsContent) {
+    // Match `customElements.define(..., { ..., extends: "..." })`. Tolerant of
+    // whitespace, line breaks, and other object properties. The `[^)]*` stops
+    // the inner greedy match at the closing define call paren so a later
+    // `define` call on a different custom element in the same module does
+    // not bleed its options in.
+    return /customElements\.define\s*\([^)]*\bextends\s*:\s*["'`]/.test(mjsContent);
+}
+/**
+ * Checks whether a declared component class extends a valid element base.
+ *
+ * Two shapes are accepted:
+ *
+ * 1. Autonomous custom element: `class X extends MozLitElement` — the
+ *    default FireForge pattern for fork-authored components and most
+ *    toolkit widgets.
+ * 2. Customized built-in: `class X extends HTML<Something>Element` paired
+ *    with a `customElements.define(..., ..., { extends: "<tagname>" })`
+ *    call. Firefox's `moz-support-link`, `moz-button-group` tabbing
+ *    widgets, and a handful of other toolkit components use this form;
+ *    `furnace override` of those components writes the original source
+ *    verbatim and the validator must not reject them.
+ *
+ * A class that extends a plain `HTMLElement` WITHOUT a `extends:` option
+ * is still rejected — that's the legitimate `not-moz-lit-element` case
+ * the rule was originally designed to catch.
+ */
 export function classExtendsMozLitElement(mjsContent) {
     const hasClassDeclaration = /class\s+\w+\s+extends\s+/.test(mjsContent);
     if (!hasClassDeclaration) {
@@ -278,7 +317,19 @@ export function classExtendsMozLitElement(mjsContent) {
         // structural issues.
         return true;
     }
-    return /class\s+\w+\s+extends\s+MozLitElement\b/.test(mjsContent);
+    if (/class\s+\w+\s+extends\s+MozLitElement\b/.test(mjsContent)) {
+        return true;
+    }
+    // Customized built-in: extend a specific HTMLxxxElement AND the define
+    // call carries an `extends:` option. Both halves are required — a class
+    // that extends `HTMLAnchorElement` without the matching define option is
+    // almost certainly an author mistake, and a define call with `extends:`
+    // without a matching class is unreachable.
+    const extendsCustomizedBuiltin = /class\s+\w+\s+extends\s+HTML[A-Z]\w*Element\b/.test(mjsContent);
+    if (extendsCustomizedBuiltin && hasCustomElementExtendsOption(mjsContent)) {
+        return true;
+    }
+    return false;
 }
 /** Collects CSS custom property references used via var(--token-name). */
 export function collectCssVariableReferences(cssContent) {

package/dist/src/core/git.js

@@ -83,6 +83,15 @@ async function stageAllFilesChunked(dir, options = {}) {
         });
     }
 }
+/**
+ * Interval between heartbeat progress messages during the monolithic
+ * `git add -A`. On a fresh ~600 MB Firefox tree the monolithic add runs
+ * 60–120 seconds, during which git emits nothing to stdout/stderr. Without
+ * a heartbeat the CLI spinner stays pinned on "Indexing Firefox source …"
+ * for the full window, looks hung, and in the eval scenario operators
+ * SIGINT'd mid-way assuming the process had stalled.
+ */
+const GIT_ADD_HEARTBEAT_MS = 15_000;
 /**
  * Stages all files in the repository.
  * Tries a monolithic `git add -A` first; if that times out, falls back to
@@ -90,19 +99,39 @@ async function stageAllFilesChunked(dir, options = {}) {
  */
 export async function stageAllFiles(dir, options = {}) {
     const timeout = options.timeout ?? GIT_ADD_TIMEOUT_MS;
+    const reportProgress = options.onProgress;
+    const heartbeatStartedAt = Date.now();
+    // Periodic heartbeat so non-TTY log scrapers (CI, tail -f) AND operators
+    // watching a spinner both see that the add is still making progress
+    // rather than a dead process. Each tick reports elapsed seconds so the
+    // expected 1–3 minute window (see `download.ts`' info banner) is
+    // observable as it unfolds.
+    const heartbeatTimer = reportProgress
+        ? setInterval(() => {
+            const elapsedS = Math.round((Date.now() - heartbeatStartedAt) / 1000);
+            reportProgress(`Indexing Firefox source (still staging, ${elapsedS}s elapsed)`);
+        }, GIT_ADD_HEARTBEAT_MS)
+        : null;
+    heartbeatTimer?.unref();
     try {
-        await git(['add', '-A'], dir, { timeout, env: GIT_ADD_ENV });
-        return;
-    }
-    catch (error) {
-        if (!isTimeoutError(error)) {
-            throw await maybeWrapIndexLockError(dir, error);
+        try {
+            await git(['add', '-A'], dir, { timeout, env: GIT_ADD_ENV });
+            return;
+        }
+        catch (error) {
+            if (!isTimeoutError(error)) {
+                throw await maybeWrapIndexLockError(dir, error);
+            }
+            options.onProgress?.('Monolithic git add timed out; falling back to chunked staging...');
         }
-        options.onProgress?.('Monolithic git add timed out; falling back to chunked staging...');
+        // The killed process may have left an index lock
+        await cleanupIndexLock(dir);
+        await stageAllFilesChunked(dir, options);
+    }
+    finally {
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
     }
-    // The killed process may have left an index lock
-    await cleanupIndexLock(dir);
-    await stageAllFilesChunked(dir, options);
 }
 /**
  * Initializes a new git repository with an orphan branch.

package/dist/src/core/mach-error-hints.js

@@ -57,6 +57,22 @@ export const MACH_ERROR_HINTS = [
             'remove any `pub type basic_string___self_view = …<_CharT>;` line from ' +
             '`<objdir>/release/build/gecko-profiler-*/out/gecko/bindings.rs`.',
     },
+    {
+        // When `mach build` fails mid-compile, mach's own shutdown pipeline still
+        // runs its trailing "Config object not found by mach. / Configure
+        // complete! / Be sure to run |mach build|..." summary on the way out.
+        // Those three lines are plain upstream mach output, printed AFTER the
+        // non-zero exit code has already been established, and they look
+        // deceptively like a success banner — the eval's Darwin 25 log had
+        // operators double-checking whether `make` had actually failed. We do
+        // not own those lines, but we can give the operator a specific nudge
+        // that they are cosmetic post-failure output rather than a mixed
+        // success/failure signal.
+        pattern: /Config object not found by mach\.[\s\S]*?Configure complete!/,
+        hint: 'Ignore the trailing "Config object not found by mach. / Configure complete!" block — ' +
+            "that is mach's post-failure configure summary printed after the build already failed, " +
+            'not a sign the build succeeded. The real failure is the error above this block.',
+    },
 ];
 /**
  * Scans captured stderr for known mach errors and returns matching hints.

package/dist/src/core/mach.js

@@ -111,13 +111,22 @@ export async function bootstrapWithOutput(engineDir) {
     return runMachInheritCapture(['bootstrap', '--application-choice', 'browser'], engineDir);
 }
 /**
- * Prints any matched {@link MachErrorHint} hints for the captured stderr.
+ * Prints any matched {@link MachErrorHint} hints for the captured mach output.
  * No-op when nothing matches. Always called before a non-zero exit propagates
  * so the hint sits immediately below the raw mach error in the operator's
  * terminal.
- */
-function surfaceMachErrorHints(stderr) {
-    const hints = explainMachError(stderr);
+ *
+ * The scanner is passed the concatenation of stderr AND stdout because mach
+ * streams its subcommand output through a timestamp-prefixing wrapper that
+ * writes both streams to whatever FD the subprocess chose — in practice,
+ * `rustc` errors from `mach build` can land on stdout rather than stderr,
+ * and the eval run's Darwin 25 `_CharT` hint pattern matched the captured
+ * text but our pre-0.16 code only fed `result.stderr` into the scanner, so
+ * the hint never fired.
+ */
+function surfaceMachErrorHints(result) {
+    const combined = `${result.stderr}\n${result.stdout}`;
+    const hints = explainMachError(combined);
     if (hints.length === 0)
         return;
     for (const hint of hints) {
@@ -139,7 +148,7 @@ export async function build(engineDir, jobs) {
     }
     const result = await runMachInheritCapture(args, engineDir);
     if (result.exitCode !== 0) {
-        surfaceMachErrorHints(result.stderr);
+        surfaceMachErrorHints(result);
     }
     return result.exitCode;
 }
@@ -152,7 +161,7 @@ export async function build(engineDir, jobs) {
 export async function buildUI(engineDir) {
     const result = await runMachInheritCapture(['build', 'faster'], engineDir);
     if (result.exitCode !== 0) {
-        surfaceMachErrorHints(result.stderr);
+        surfaceMachErrorHints(result);
     }
     return result.exitCode;
 }

package/dist/src/core/manifest-rules.js

@@ -119,6 +119,22 @@ function getUnregistrableAdvice(filePath) {
             '"fireforge wire <name> --dom <path>" to insert the #include, or add the directive manually ' +
             'in the top-level chrome document.');
     }
+    // xpcshell.toml manifests scaffolded by `furnace create --test-style
+    // xpcshell` or `furnace chrome-doc create --with-tests` live under
+    // `browser/base/content/test/<binary-name>-xpcshell/<component>/`. The
+    // scaffold intentionally does NOT auto-register — wiring
+    // `XPCSHELL_TESTS_MANIFESTS` requires a deliberate choice about which
+    // moz.build should own the entry. `register` surfaces that same guidance
+    // instead of falling through to browser.toml-centric advice, which was
+    // the eval finding (operator saw "register browser.toml" hint for a
+    // path that was xpcshell-shaped and contained no browser.toml).
+    if (filePath.endsWith('/xpcshell.toml')) {
+        return (`xpcshell.toml manifests are not auto-registered by "fireforge register". ` +
+            `Add "XPCSHELL_TESTS_MANIFESTS += ['${basename(filePath)}']" to the ` +
+            `moz.build that covers ${filePath.replace(/\/xpcshell\.toml$/, '/')}, ` +
+            'or let `furnace create --test-style xpcshell` print the warning that names the canonical wiring location. ' +
+            'Browser-chrome tests (browser.toml) are auto-registered via "fireforge register <path>/browser.toml".');
+    }
     const testMatch = filePath.match(/^browser\/base\/content\/test\/([^/]+)\/(?!browser\.toml$).+$/);
     if (testMatch) {
         const dir = testMatch[1];