@hominis/fireforge 0.16.3 → 0.17.0

package/dist/src/commands/test.js

@@ -3,13 +3,14 @@ import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
+import { assertMarionettePortAvailable } from '../core/marionette-port.js';
 import { reportMarionettePreflight, runMarionettePreflight } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, spinner, warn } from '../utils/logger.js';
+import { info, intro, outro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 async function assertTestPathsExist(engineDir, testPaths) {
@@ -148,10 +149,13 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         throw new GeneralError(`Tests require a completed build. ${detail}\n\n` +
             "Run 'fireforge build' first, then run 'fireforge test'.");
     }
+    // Load the project config once so both the build and the port
+    // probe have access to `binaryName` (the port probe uses it to
+    // recognise a fork-branded browser holding the Marionette port).
+    const projectConfig = await loadConfig(projectRoot);
     // Run incremental build if requested
     if (options.build) {
-        const config = await loadConfig(projectRoot);
-        await prepareBuildEnvironment(projectRoot, paths, config);
+        await prepareBuildEnvironment(projectRoot, paths, projectConfig);
         const s = spinner('Running incremental build...');
         const buildExitCode = await buildUI(paths.engine);
         if (buildExitCode !== 0) {
@@ -175,6 +179,15 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             warn(formatStaleBuildWarning(stale));
         }
     }
+    // Stale-browser probe: an interrupted earlier test run can leave a
+    // Firefox/ForgeFresh/Hominis instance listening on the Marionette
+    // control port, which breaks the next mach test launch with a
+    // bind error that points nowhere near the real cause. Raise a
+    // targeted refusal up front instead of letting mach surface the
+    // generic bind failure. 2026-04-21 eval (Finding #20): a stale
+    // `-marionette` process from `fresh/` poisoned a later test run in
+    // the sibling `hominis/` workspace.
+    await assertMarionettePortAvailable(undefined, { binaryName: projectConfig.binaryName });
     // `--doctor` runs a short marionette handshake probe. When test paths are
     // supplied the probe gates the mach test invocation (a FAIL bails out). When
     // no paths are supplied this is the only step — it's the fastest way to tell
@@ -187,6 +200,13 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             if (!preflight.ok) {
                 throw new GeneralError('Marionette preflight reported FAIL — see output above.');
             }
+            // Close the intro frame explicitly. Without an outro, clack's
+            // grouped-output mode left the PASS line hanging inside an
+            // unclosed tree — in the eval's non-TTY capture the info line
+            // itself failed to render, so `test --doctor` looked like it had
+            // exited silently after the spinner start line. The outro also
+            // gives scripts a deterministic "done" marker to parse.
+            outro(`Marionette preflight: PASS (${preflight.durationMs}ms)`);
             return;
         }
         if (!preflight.ok) {

package/dist/src/commands/token-coverage.js

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
 import { getStatusWithCodes, isGitRepository } from '../core/git.js';
 import { measureTokenCoverage } from '../core/token-coverage.js';
 import { getTokensCssPath } from '../core/token-manager.js';
@@ -22,9 +24,19 @@ export async function tokenCoverageCommand(projectRoot) {
     const config = await loadConfig(projectRoot);
     const tokensCssPath = getTokensCssPath(config.binaryName);
     const files = await getStatusWithCodes(paths.engine);
-    const cssFiles = files
+    const statusCssFiles = files
         .filter((f) => f.file.endsWith('.css') && f.file !== tokensCssPath)
         .map((f) => f.file);
+    // Also scan CSS files deployed by Furnace custom components. Deployed
+    // files can be committed (and therefore absent from `git status`) while
+    // still being the primary surface where token adoption matters. Before
+    // 0.16.0, coverage only looked at modified files, which silently
+    // undercounted projects where Furnace writes many component-CSS files
+    // into the engine and they are already tracked.
+    const furnaceCssFiles = await collectFurnaceCustomCssFiles(projectRoot, paths.engine, tokensCssPath);
+    // De-dupe so a file that is both a custom deploy target AND modified is
+    // scanned exactly once.
+    const cssFiles = [...new Set([...statusCssFiles, ...furnaceCssFiles])];
     if (cssFiles.length === 0) {
         info('No modified CSS files');
         outro('Nothing to measure');
@@ -54,4 +66,46 @@ export async function tokenCoverageCommand(projectRoot) {
     }
     outro(`${report.filesScanned} CSS file${report.filesScanned === 1 ? '' : 's'} scanned`);
 }
+/**
+ * Returns engine-relative `.css` paths deployed by every Furnace custom
+ * component registered in `furnace.json`. Only files that actually exist
+ * on disk are included — a component whose deploy target is missing (e.g.
+ * `furnace apply` has not run yet) is skipped silently so a fresh
+ * `furnace init` followed immediately by `token coverage` does not error.
+ *
+ * Returns an empty array when the project has no furnace.json, no custom
+ * components, or when loading the config fails (a warn is emitted in the
+ * last case so the user can diagnose a broken furnace.json without losing
+ * coverage results on the non-furnace CSS files).
+ */
+async function collectFurnaceCustomCssFiles(projectRoot, engineDir, tokensCssPath) {
+    if (!(await furnaceConfigExists(projectRoot))) {
+        return [];
+    }
+    let furnaceConfig;
+    try {
+        furnaceConfig = await loadFurnaceConfig(projectRoot);
+    }
+    catch (error) {
+        warn(`Could not load furnace.json for token coverage — scanning modified files only (${error.message})`);
+        return [];
+    }
+    const results = [];
+    for (const [componentName, customConfig] of Object.entries(furnaceConfig.custom)) {
+        // Upstream Firefox widget layout: every component lives at
+        // `toolkit/content/widgets/<tagName>/` and ships at least
+        // `<tagName>.css`. `targetPath` already resolves to that directory
+        // (the create command writes `toolkit/content/widgets/<name>` into
+        // furnace.json) so we can probe the default layout directly without
+        // walking the whole tree.
+        const candidate = `${customConfig.targetPath}/${componentName}.css`;
+        if (candidate === tokensCssPath)
+            continue;
+        const absolutePath = join(engineDir, candidate);
+        if (await pathExists(absolutePath)) {
+            results.push(candidate);
+        }
+    }
+    return results;
+}
 //# sourceMappingURL=token-coverage.js.map

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')

package/dist/src/commands/wire.js

@@ -4,7 +4,8 @@ import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript } from '../core/browser-wi
 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 { DEFAULT_DOM_TARGET, probeDomFragmentInsertionPoint } 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, '/');
@@ -78,6 +83,34 @@ function validateWireName(name) {
             'Path separators and parent-directory segments are not permitted.', 'name');
     }
 }
+/**
+ * Asserts that the resolved chrome document both exists on disk AND
+ * exposes an insertion anchor (`#include browser-sets.inc` or
+ * `<html:body>`) that `addDomFragment` can splice into. Fires the same
+ * check in dry-run and real-run mode, so the preview and execution
+ * agree on whether the target is wireable before any disk mutations
+ * happen. Before 0.16.0 this check only ran on the real branch, which
+ * let the dry-run produce a plausible-looking plan that the real run
+ * then refused with `Could not find insertion point in chrome document`.
+ */
+async function assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath) {
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(join(paths.engine, domTargetPath)))) {
+        throw new InvalidArgumentError(`Chrome document not found in engine: ${domTargetPath}\n` +
+            'Set "tokenHostDocuments" in furnace.json (first entry is used by wire) ' +
+            'or pass --target <path>.', 'target');
+    }
+    try {
+        await probeDomFragmentInsertionPoint(paths.engine, domFilePath, domTargetPath);
+    }
+    catch (probeError) {
+        throw new InvalidArgumentError(`${probeError instanceof Error ? probeError.message : String(probeError)}\n` +
+            `The resolved chrome document ${domTargetPath} does not expose an insertion anchor ` +
+            'that `fireforge wire` recognises (`#include browser-sets.inc` or `<html:body>`). ' +
+            'Add one of those anchors to the chrome doc, or target a document that has them via ' +
+            '`--target <path>`.', 'target');
+    }
+}
 /**
  * Wires a chrome subscript into the browser.
  *
@@ -95,6 +128,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;
@@ -172,14 +220,12 @@ export async function wireCommand(projectRoot, name, options = {}) {
     }
     const domTargetPath = await resolveDomTargetPath(projectRoot, normalizedTarget);
     if (domFilePath) {
-        const paths = getProjectPaths(projectRoot);
-        if (!options.dryRun && !(await pathExists(join(paths.engine, domTargetPath)))) {
-            throw new InvalidArgumentError(`Chrome document not found in engine: ${domTargetPath}\n` +
-                'Set "tokenHostDocuments" in furnace.json (first entry is used by wire) ' +
-                'or pass --target <path>.', 'target');
-        }
+        await assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath);
     }
-    // Verify the subscript file exists in engine/ (skip for dry-run)
+    // Verify the subscript file exists in engine/ (skip for dry-run:
+    // dry-run is meant to preview the mutation plan without requiring
+    // the subscript to already exist, matching the "plan before write"
+    // pattern operators rely on for setup scripts).
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);
         const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);

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

@@ -52,5 +52,38 @@ export declare function writeConfig(root: string, config: FireForgeConfig): Prom
  * Writes a raw config document to fireforge.json.
  * This is used by CLI `config --force`, where callers may intentionally write
  * keys or value shapes outside the validated FireForgeConfig schema.
+ *
+ * Individual writes are atomic via {@link writeJson} (temp file + rename),
+ * but atomicity alone does not prevent lost updates across concurrent
+ * writers: each writer reads an old copy, mutates its own in-memory view,
+ * and writes it back, so the second writer's rename clobbers the first
+ * writer's changes. Callers that do read → mutate → write must hold
+ * {@link withConfigFileLock} for the full round-trip to serialise
+ * against other writers.
  */
 export declare function writeConfigDocument(root: string, config: FireForgeConfig | Record<string, unknown>): Promise<void>;
+/**
+ * Runs an operation while holding a sidecar lock on `fireforge.json`.
+ *
+ * Motivating case (2026-04-21 eval): two concurrent `fireforge config
+ * <key> <value>` invocations each ran load → mutate → writeJson against
+ * the same on-disk fireforge.json. The second rename landed after the
+ * first, silently dropping the first writer's key — both commands exited
+ * `0`, but only one change survived. This helper turns the same
+ * read-modify-write sequence into a serialised operation so a concurrent
+ * writer now waits for the lock rather than racing on the document.
+ *
+ * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
+ * always use `writeJson`'s atomic temp-file + rename, so a reader observes
+ * either the pre- or post-write document but never a torn file. The lock
+ * only serialises writers against other writers.
+ *
+ * The lock is a sidecar directory `${config}.fireforge-config.lock`, and
+ * `withFileLock` handles stale-lock recovery (PID-alive probe, age-based
+ * fallback) — a crashed writer does not permanently block future writes.
+ *
+ * @param root - Root directory of the project
+ * @param operation - Async function to run while holding the lock
+ * @returns Whatever the operation returns
+ */
+export declare function withConfigFileLock<T>(root: string, operation: () => Promise<T>): Promise<T>;

package/dist/src/core/config.js

@@ -8,11 +8,13 @@
  *   config-mutate.ts   — immutable config mutation
  *   config-state.ts    — state file management
  */
+import { basename } from 'node:path';
 import { ConfigError, ConfigNotFoundError } from '../errors/config.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { getProjectPaths } from './config-paths.js';
 import { validateConfig } from './config-validate.js';
+import { createSiblingLockPath, withFileLock } from './file-lock.js';
 // ---- re-exports ----
 export { mutateConfig } from './config-mutate.js';
 export { CONFIG_FILENAME, CONFIGS_DIR, ENGINE_DIR, FIREFORGE_DIR, getProjectPaths, PATCHES_DIR, SRC_DIR, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
@@ -97,9 +99,50 @@ export async function writeConfig(root, config) {
  * Writes a raw config document to fireforge.json.
  * This is used by CLI `config --force`, where callers may intentionally write
  * keys or value shapes outside the validated FireForgeConfig schema.
+ *
+ * Individual writes are atomic via {@link writeJson} (temp file + rename),
+ * but atomicity alone does not prevent lost updates across concurrent
+ * writers: each writer reads an old copy, mutates its own in-memory view,
+ * and writes it back, so the second writer's rename clobbers the first
+ * writer's changes. Callers that do read → mutate → write must hold
+ * {@link withConfigFileLock} for the full round-trip to serialise
+ * against other writers.
  */
 export async function writeConfigDocument(root, config) {
     const paths = getProjectPaths(root);
     await writeJson(paths.config, config);
 }
+/**
+ * Runs an operation while holding a sidecar lock on `fireforge.json`.
+ *
+ * Motivating case (2026-04-21 eval): two concurrent `fireforge config
+ * <key> <value>` invocations each ran load → mutate → writeJson against
+ * the same on-disk fireforge.json. The second rename landed after the
+ * first, silently dropping the first writer's key — both commands exited
+ * `0`, but only one change survived. This helper turns the same
+ * read-modify-write sequence into a serialised operation so a concurrent
+ * writer now waits for the lock rather than racing on the document.
+ *
+ * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
+ * always use `writeJson`'s atomic temp-file + rename, so a reader observes
+ * either the pre- or post-write document but never a torn file. The lock
+ * only serialises writers against other writers.
+ *
+ * The lock is a sidecar directory `${config}.fireforge-config.lock`, and
+ * `withFileLock` handles stale-lock recovery (PID-alive probe, age-based
+ * fallback) — a crashed writer does not permanently block future writes.
+ *
+ * @param root - Root directory of the project
+ * @param operation - Async function to run while holding the lock
+ * @returns Whatever the operation returns
+ */
+export async function withConfigFileLock(root, operation) {
+    const paths = getProjectPaths(root);
+    return withFileLock(createSiblingLockPath(paths.config, '.fireforge-config.lock'), operation, {
+        onTimeoutMessage: `Timed out waiting to update ${basename(paths.config)}. ` +
+            'If no other fireforge process is running, remove the stale lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale FireForge config lock for ${basename(paths.config)} ` +
+            `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
+    });
+}
 //# sourceMappingURL=config.js.map

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

@@ -111,9 +111,30 @@ export declare function writeFurnaceConfig(root: string, config: FurnaceConfig):
 export declare function stampFurnaceOverrideBaseVersions(root: string, version: string): Promise<number>;
 /**
  * Creates a default furnace configuration.
- * @returns A valid empty FurnaceConfig
+ *
+ * When a `binaryName` is provided, the default config carries a
+ * `tokenPrefix` derived as `--<binaryName>-`. Without that default,
+ * `fireforge token coverage` on a fresh project reports `0 tokens` and
+ * labels every custom-property reference as `unknown` — the scan has
+ * no prefix to key off. The 2026-04-21 eval walked directly into this
+ * state (`furnace init` → `token add` → `token coverage` → zero
+ * tokens), and only recovered after hand-editing furnace.json. Deriving
+ * the prefix from the binary name matches the convention the scaffolded
+ * tokens CSS already uses for its `--<binaryName>-*` declarations.
+ *
+ * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers
+ * on the legacy no-arg call shape (existing tests, programmatic callers
+ * bootstrapping from a not-yet-loaded config) still get a valid config
+ * without a prefix; the CLI init path always has a `binaryName` from
+ * `fireforge.json` and always sets one.
+ *
+ * @param options - Optional init context; pass `{ binaryName }` to
+ *   derive the token prefix.
+ * @returns A valid FurnaceConfig
  */
-export declare function createDefaultFurnaceConfig(): FurnaceConfig;
+export declare function createDefaultFurnaceConfig(options?: {
+    binaryName?: string;
+}): FurnaceConfig;
 /**
  * Loads furnace config if it exists, or creates and writes a default config.
  * @param root - Root directory of the project

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

@@ -460,16 +460,39 @@ export async function stampFurnaceOverrideBaseVersions(root, version) {
 }
 /**
  * Creates a default furnace configuration.
- * @returns A valid empty FurnaceConfig
+ *
+ * When a `binaryName` is provided, the default config carries a
+ * `tokenPrefix` derived as `--<binaryName>-`. Without that default,
+ * `fireforge token coverage` on a fresh project reports `0 tokens` and
+ * labels every custom-property reference as `unknown` — the scan has
+ * no prefix to key off. The 2026-04-21 eval walked directly into this
+ * state (`furnace init` → `token add` → `token coverage` → zero
+ * tokens), and only recovered after hand-editing furnace.json. Deriving
+ * the prefix from the binary name matches the convention the scaffolded
+ * tokens CSS already uses for its `--<binaryName>-*` declarations.
+ *
+ * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers
+ * on the legacy no-arg call shape (existing tests, programmatic callers
+ * bootstrapping from a not-yet-loaded config) still get a valid config
+ * without a prefix; the CLI init path always has a `binaryName` from
+ * `fireforge.json` and always sets one.
+ *
+ * @param options - Optional init context; pass `{ binaryName }` to
+ *   derive the token prefix.
+ * @returns A valid FurnaceConfig
  */
-export function createDefaultFurnaceConfig() {
-    return {
+export function createDefaultFurnaceConfig(options = {}) {
+    const config = {
         version: 1,
         componentPrefix: 'moz-',
         stock: [],
         overrides: {},
         custom: {},
     };
+    if (options.binaryName && options.binaryName.length > 0) {
+        config.tokenPrefix = `--${options.binaryName}-`;
+    }
+    return config;
 }
 /**
  * Loads furnace config if it exists, or creates and writes a default config.

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.d.ts

@@ -73,6 +73,37 @@ export declare function build(engineDir: string, jobs?: number): Promise<number>
  * @returns Exit code
  */
 export declare function buildUI(engineDir: string): Promise<number>;
+/**
+ * Runs an operation while holding a sidecar build lock keyed on the
+ * project root. Concurrent `fireforge build` / `fireforge build --ui`
+ * invocations against the same tree serialise instead of racing through
+ * the mach obj-dir.
+ *
+ * Motivating case (2026-04-21 eval): a `fireforge build --ui` run
+ * kicked off while a full `fireforge build` was still in flight against
+ * the same engine tree accepted the command and handed off to `mach
+ * build faster`, which failed almost immediately with `No rule to make
+ * target 'XUL'`. The real problem is that the first build had not yet
+ * materialised the full backend; the operator was left staring at a
+ * low-level make error with no link to the actual cause (a concurrent
+ * build in flight). The lock intercepts the second invocation before
+ * it touches mach, and the refusal message names the PID currently
+ * holding the lock so the operator can decide whether to wait or
+ * investigate a hung process.
+ *
+ * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but
+ * not the owning process, and `withFileLock` removes the lock on the
+ * next attempt when `process.kill(pid, 0)` shows the owner is gone.
+ *
+ * The project-root variant is the right granularity: a single machine
+ * may have several FireForge projects side by side, and nothing says
+ * they cannot build in parallel. The lock serialises *within* one
+ * project, not across unrelated ones.
+ *
+ * Returns whatever the inner operation returns.
+ */
+export declare function withBuildLock<T>(projectRoot: string, operation: () => Promise<T>): Promise<T>;
 /**
  * Runs the built browser.
  * @param engineDir - Path to the engine directory

package/dist/src/core/mach.js

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
+import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
@@ -111,13 +112,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.
+ *
+ * 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(stderr) {
-    const hints = explainMachError(stderr);
+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 +149,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,10 +162,53 @@ 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;
 }
+/**
+ * Runs an operation while holding a sidecar build lock keyed on the
+ * project root. Concurrent `fireforge build` / `fireforge build --ui`
+ * invocations against the same tree serialise instead of racing through
+ * the mach obj-dir.
+ *
+ * Motivating case (2026-04-21 eval): a `fireforge build --ui` run
+ * kicked off while a full `fireforge build` was still in flight against
+ * the same engine tree accepted the command and handed off to `mach
+ * build faster`, which failed almost immediately with `No rule to make
+ * target 'XUL'`. The real problem is that the first build had not yet
+ * materialised the full backend; the operator was left staring at a
+ * low-level make error with no link to the actual cause (a concurrent
+ * build in flight). The lock intercepts the second invocation before
+ * it touches mach, and the refusal message names the PID currently
+ * holding the lock so the operator can decide whether to wait or
+ * investigate a hung process.
+ *
+ * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but
+ * not the owning process, and `withFileLock` removes the lock on the
+ * next attempt when `process.kill(pid, 0)` shows the owner is gone.
+ *
+ * The project-root variant is the right granularity: a single machine
+ * may have several FireForge projects side by side, and nothing says
+ * they cannot build in parallel. The lock serialises *within* one
+ * project, not across unrelated ones.
+ *
+ * Returns whatever the inner operation returns.
+ */
+export async function withBuildLock(projectRoot, operation) {
+    const lockPath = createSiblingLockPath(join(projectRoot, '.fireforge-build'), '.lock');
+    return withFileLock(lockPath, operation, {
+        // Default lock timeout is 30s; bump to 24h so a slow full build does
+        // not trip the timeout while the second invocation waits. A real
+        // operator will ^C long before 24h elapses; the ceiling is there
+        // purely so a forgotten lock cannot wedge the command forever.
+        timeoutMs: 24 * 60 * 60 * 1000,
+        onTimeoutMessage: `Timed out waiting for the FireForge build lock at ${lockPath}. ` +
+            'If no other `fireforge build` is running, remove the lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale FireForge build lock ${basename(lockPath)} (age: ${Math.round(ageMs / 1000)}s). A previous build process may have crashed.`,
+    });
+}
 /**
  * Runs the built browser.
  * @param engineDir - Path to the engine directory