@hominis/fireforge 0.15.2 → 0.15.3

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

@@ -0,0 +1,251 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Post-build dist-tree audit.
+ *
+ * Purpose: catch the class of bug where a file under engine/ was edited
+ * but never registered in moz.build, jar.mn, or package-manifest.in, so
+ * the mach build reports success but the packaged bundle carries stale
+ * or missing content. A fork-specific pref file that was never registered
+ * for packaging is the motivating case.
+ *
+ * The audit is best-effort and warn-only:
+ *   - It enumerates engine files changed since the previous build baseline
+ *     (git-tracked diff + workdir modifications).
+ *   - For each file whose path pattern implies packaging, it resolves
+ *     the expected dist artifact under obj-star/dist/binary-name-star.
+ *   - A warning fires when the expected artifact is missing OR when its
+ *     mtime is older than the engine source (the build was reported
+ *     successful but that file's path never flowed through packaging).
+ *   - False positives are acceptable at this stage: fork-specific packaging
+ *     tricks FireForge doesn't know about will surface as warnings an
+ *     operator can investigate. The audit never fails the build.
+ */
+import { stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { info, verbose, warn } from '../utils/logger.js';
+import { hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+/** Path extensions that are conventionally packaged into the Firefox bundle. */
+const PACKAGEABLE_EXTENSIONS = [
+    '.js',
+    '.mjs',
+    '.jsm',
+    '.css',
+    '.ftl',
+    '.xhtml',
+    '.xul',
+    '.html',
+    '.properties',
+];
+/** Path fragments whose contents are packaged regardless of extension. */
+const PACKAGEABLE_PATH_FRAGMENTS = ['/app/profile/', '/chrome/', '/locales/'];
+/** Directories that are build artifacts, not source — never audited. */
+const IGNORE_PATH_FRAGMENTS = ['obj-', 'node_modules/', '.git/', '.cargo/', '.mozbuild/'];
+/*
+ * Finds the first file with the given basename anywhere under the dist
+ * bundle. Scans the darwin Contents/Resources layout and the linux/win
+ * top-level layout with a depth-limited traversal so deeply-nested
+ * node_modules in the dist copy do not dominate the audit wall clock.
+ */
+async function findArtifactByBasename(distRoot, name, maxDepth = 10) {
+    const { readdir } = await import('node:fs/promises');
+    const stack = [{ dir: distRoot, depth: 0 }];
+    while (stack.length > 0) {
+        const entry = stack.pop();
+        if (!entry)
+            break;
+        if (entry.depth > maxDepth)
+            continue;
+        let children;
+        try {
+            children = await readdir(entry.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const child of children) {
+            const fullPath = join(entry.dir, child.name);
+            if (child.isDirectory()) {
+                // Skip the symlinked mozbuild cache tree which contains full copies
+                // and would dominate the scan on macOS.
+                if (child.name.startsWith('.'))
+                    continue;
+                stack.push({ dir: fullPath, depth: entry.depth + 1 });
+                continue;
+            }
+            if (child.name === name) {
+                return fullPath;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Decides whether a source path should be packaged. Returns true for paths
+ * whose extension or directory fragment matches a known-packaged pattern.
+ * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
+ * @returns True when the path implies packaging.
+ */
+export function isPackageablePath(sourcePath) {
+    for (const fragment of IGNORE_PATH_FRAGMENTS) {
+        if (sourcePath.includes(fragment))
+            return false;
+    }
+    for (const ext of PACKAGEABLE_EXTENSIONS) {
+        if (sourcePath.endsWith(ext))
+            return true;
+    }
+    for (const fragment of PACKAGEABLE_PATH_FRAGMENTS) {
+        if (sourcePath.includes(fragment))
+            return true;
+    }
+    return false;
+}
+/**
+ * Collects engine-relative paths changed since the baseline's HEAD SHA.
+ * Always includes modified + untracked workdir paths. When the baseline is
+ * missing or the engine has no HEAD yet, falls back to workdir-only diffs.
+ */
+async function collectChangedFiles(engineDir, baseline) {
+    const collected = new Set();
+    if (baseline?.engineHeadSha) {
+        try {
+            const output = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
+            for (const line of output.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+        }
+        catch (error) {
+            if (!isMissingHeadError(error)) {
+                verbose(`Audit: could not diff against baseline SHA — ${toError(error).message}`);
+            }
+        }
+    }
+    try {
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+            const untracked = await getUntrackedFiles(engineDir);
+            for (const file of untracked) {
+                collected.add(file);
+            }
+        }
+    }
+    catch (error) {
+        verbose(`Audit: could not enumerate workdir changes — ${toError(error).message}`);
+    }
+    return [...collected].sort();
+}
+/*
+ * Finds the unique obj-star directory with a dist subtree, or undefined
+ * when zero or multiple match. The ambiguous case is already rejected
+ * by pre-flight in build.ts, so the auditor only has to handle
+ * one-or-none.
+ */
+async function resolveDistRoot(engineDir) {
+    const { readdir } = await import('node:fs/promises');
+    let entries;
+    try {
+        entries = await readdir(engineDir);
+    }
+    catch {
+        return undefined;
+    }
+    const objDirs = entries.filter((e) => e.startsWith('obj-'));
+    for (const objDir of objDirs) {
+        const distPath = join(engineDir, objDir, 'dist');
+        if (await pathExists(distPath)) {
+            return distPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Runs the post-build audit. Emits per-file warnings for missing or
+ * stale artifacts and a summary info line at the end. Always returns
+ * the summary; never throws on audit failure (the audit itself must
+ * never fail a successful build).
+ * @param projectRoot Root of the project (reserved for future fork-specific rules).
+ * @param engineDir Path to the engine directory.
+ * @param baseline Optional previous-build baseline marker.
+ * @returns Summary of artifact status counts.
+ */
+export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
+    void projectRoot;
+    const summary = {
+        updated: 0,
+        stale: 0,
+        missing: 0,
+        skipped: 0,
+        entries: [],
+    };
+    const distRoot = await resolveDistRoot(engineDir);
+    if (!distRoot) {
+        verbose('Audit skipped: no dist tree found under obj-*/dist/.');
+        return summary;
+    }
+    const changed = await collectChangedFiles(engineDir, baseline);
+    if (changed.length === 0) {
+        return summary;
+    }
+    for (const source of changed) {
+        if (!isPackageablePath(source)) {
+            summary.skipped += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
+            continue;
+        }
+        const sourcePath = join(engineDir, source);
+        let sourceMtime;
+        try {
+            const sourceStat = await stat(sourcePath);
+            sourceMtime = sourceStat.mtimeMs;
+        }
+        catch {
+            // File was deleted since the diff was computed. Skip — a deletion
+            // that didn't propagate to the dist tree is a distinct class of bug
+            // we don't audit yet.
+            summary.skipped += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
+            continue;
+        }
+        const artifact = await findArtifactByBasename(distRoot, basename(source));
+        if (!artifact) {
+            summary.missing += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'missing' });
+            warn(`Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${distRoot}. Missing moz.build / jar.mn / package-manifest.in registration?`);
+            continue;
+        }
+        let artifactMtime;
+        try {
+            const artifactStat = await stat(artifact);
+            artifactMtime = artifactStat.mtimeMs;
+        }
+        catch {
+            // Disappeared after the directory scan; treat as missing.
+            summary.missing += 1;
+            summary.entries.push({ source, artifact, status: 'missing' });
+            warn(`Audit: engine/${source} has no readable packaged artifact at ${artifact} (disappeared during audit).`);
+            continue;
+        }
+        if (artifactMtime + 1 < sourceMtime) {
+            summary.stale += 1;
+            summary.entries.push({ source, artifact, status: 'stale' });
+            warn(`Audit: engine/${source} is newer than its packaged artifact ${artifact}. Build reported success but the file's path may not flow through packaging — check moz.build / jar.mn entries.`);
+            continue;
+        }
+        summary.updated += 1;
+        summary.entries.push({ source, artifact, status: 'updated' });
+    }
+    info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
+    return summary;
+}
+//# sourceMappingURL=build-audit.js.map

package/dist/src/core/build-baseline.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persists a marker describing the state of the engine tree at the time of
+ * the last successful `fireforge build`. Two downstream consumers share this
+ * marker:
+ *
+ *   - `build-audit`: after a build succeeds, compare engine files touched
+ *     since the baseline against the dist bundle to flag silent
+ *     packaging drops (e.g. a pref file never registered in moz.build).
+ *   - `build-prepare`: before a build starts, detect whether any
+ *     `moz.build` / `moz.configure` / `Makefile.in` changed since the
+ *     baseline and run `mach configure` before the build step so the
+ *     recursive-make backend isn't stale.
+ *
+ * The marker lives under `.fireforge/last-build.json`. It is written only
+ * on successful build completion; a failed build does not update it, so a
+ * subsequent run still audits against the last known-good tree.
+ */
+/** Shape of the on-disk baseline marker. */
+export interface BuildBaseline {
+    /** SHA of engine HEAD at the time the build succeeded. */
+    engineHeadSha: string;
+    /**
+     * ISO-8601 timestamp of when the baseline was recorded. Informational —
+     * downstream code keys off `engineHeadSha` for diffs, but the timestamp
+     * helps operators reason about stale markers.
+     */
+    builtAt: string;
+    /**
+     * The binaryName used at build time. Captured so the dist-tree audit
+     * can resolve the expected bundle root under obj-star/dist/ even when
+     * the project has since been renamed.
+     */
+    binaryName: string;
+}
+/** Name of the last-build marker file under `.fireforge/`. */
+export declare const BUILD_BASELINE_FILENAME = "last-build.json";
+/**
+ * Resolves the on-disk path of the build baseline marker.
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path of the marker file
+ */
+export declare function getBuildBaselinePath(projectRoot: string): string;
+/**
+ * Reads the last-build baseline if present. Returns undefined when no
+ * previous successful build has been recorded — callers must tolerate that
+ * path (first build, cleaned workspace).
+ * @param projectRoot - Root directory of the project
+ */
+export declare function readBuildBaseline(projectRoot: string): Promise<BuildBaseline | undefined>;
+/**
+ * Records a successful build by writing a fresh baseline marker. Captures
+ * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
+ * the current binaryName. Caller is responsible for only invoking this
+ * after the build exit code was zero.
+ * @param projectRoot - Root directory of the project
+ * @param engineDir - Path to the engine directory
+ * @param binaryName - Current `binaryName` from fireforge.json
+ */
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string): Promise<void>;

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

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Persists a marker describing the state of the engine tree at the time of
+ * the last successful `fireforge build`. Two downstream consumers share this
+ * marker:
+ *
+ *   - `build-audit`: after a build succeeds, compare engine files touched
+ *     since the baseline against the dist bundle to flag silent
+ *     packaging drops (e.g. a pref file never registered in moz.build).
+ *   - `build-prepare`: before a build starts, detect whether any
+ *     `moz.build` / `moz.configure` / `Makefile.in` changed since the
+ *     baseline and run `mach configure` before the build step so the
+ *     recursive-make backend isn't stale.
+ *
+ * The marker lives under `.fireforge/last-build.json`. It is written only
+ * on successful build completion; a failed build does not update it, so a
+ * subsequent run still audits against the last known-good tree.
+ */
+import { join } from 'node:path';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+import { getHead, isMissingHeadError } from './git.js';
+/** Name of the last-build marker file under `.fireforge/`. */
+export const BUILD_BASELINE_FILENAME = 'last-build.json';
+/**
+ * Resolves the on-disk path of the build baseline marker.
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path of the marker file
+ */
+export function getBuildBaselinePath(projectRoot) {
+    return join(projectRoot, FIREFORGE_DIR, BUILD_BASELINE_FILENAME);
+}
+/**
+ * Reads the last-build baseline if present. Returns undefined when no
+ * previous successful build has been recorded — callers must tolerate that
+ * path (first build, cleaned workspace).
+ * @param projectRoot - Root directory of the project
+ */
+export async function readBuildBaseline(projectRoot) {
+    const path = getBuildBaselinePath(projectRoot);
+    if (!(await pathExists(path))) {
+        return undefined;
+    }
+    try {
+        return await readJson(path);
+    }
+    catch {
+        // A corrupt marker is equivalent to no marker — the audit/auto-configure
+        // will treat it as "first build" rather than block on the inconsistency.
+        return undefined;
+    }
+}
+/**
+ * Records a successful build by writing a fresh baseline marker. Captures
+ * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
+ * the current binaryName. Caller is responsible for only invoking this
+ * after the build exit code was zero.
+ * @param projectRoot - Root directory of the project
+ * @param engineDir - Path to the engine directory
+ * @param binaryName - Current `binaryName` from fireforge.json
+ */
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
+    let engineHeadSha = '';
+    try {
+        engineHeadSha = await getHead(engineDir);
+    }
+    catch (error) {
+        // Engine may be an unborn branch (freshly cloned + reset, or mid-import)
+        // — record an empty SHA and let downstream fall back to "no prior state"
+        // behavior. Any other git failure is bubbled up; we don't want to
+        // silently write a garbage marker.
+        if (!isMissingHeadError(error)) {
+            throw error;
+        }
+    }
+    const baseline = {
+        engineHeadSha,
+        builtAt: new Date().toISOString(),
+        binaryName,
+    };
+    await writeJson(getBuildBaselinePath(projectRoot), baseline);
+}
+//# sourceMappingURL=build-baseline.js.map

package/dist/src/core/build-prepare.d.ts

@@ -3,13 +3,32 @@
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
 import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
+import type { BuildBaseline } from './build-baseline.js';
 /**
  * Result of the build preparation phase.
  */
 export interface BuildPreparation {
     /** Number of Furnace components applied (0 if none or no furnace.json) */
     furnaceApplied: number;
+    /** True when `mach configure` was auto-run to refresh a stale backend. */
+    reconfigured: boolean;
 }
+/** Options for {@link prepareBuildEnvironment}. */
+export interface PrepareBuildOptions {
+    /**
+     * Previous successful-build baseline, used to detect `moz.build` /
+     * `moz.configure` / `Makefile.in` changes that require a fresh
+     * `mach configure` before the build. When undefined, the auto-configure
+     * step is skipped — there's no reference point for what "changed since"
+     * means.
+     */
+    previousBaseline?: BuildBaseline | undefined;
+}
+/**
+ * Returns true when the file path matches a pattern that forces
+ * `mach configure` to regenerate the backend. Exported for testing.
+ */
+export declare function isBackendInvalidatingFile(path: string): boolean;
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Cleans Furnace stories from engine (prevents leaking into production)
@@ -22,4 +41,4 @@ export interface BuildPreparation {
  * @param config - Loaded FireForge configuration
  * @returns Preparation results
  */
-export declare function prepareBuildEnvironment(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig): Promise<BuildPreparation>;
+export declare function prepareBuildEnvironment(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig, options?: PrepareBuildOptions): Promise<BuildPreparation>;

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

@@ -4,14 +4,72 @@
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
 import { FurnaceError } from '../errors/furnace.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, spinner, warn } from '../utils/logger.js';
+import { info, spinner, verbose, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
 import { applyAllComponents } from './furnace-apply.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
 import { runFurnaceMutation } from './furnace-operation.js';
 import { cleanStories } from './furnace-stories.js';
-import { generateMozconfig } from './mach.js';
+import { hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+import { generateMozconfig, runMach } from './mach.js';
+/** Path fragments of files whose edits invalidate the recursive-make backend. */
+const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
+/**
+ * Returns true when the file path matches a pattern that forces
+ * `mach configure` to regenerate the backend. Exported for testing.
+ */
+export function isBackendInvalidatingFile(path) {
+    for (const suffix of BACKEND_INVALIDATING_SUFFIXES) {
+        if (path === suffix || path.endsWith(`/${suffix}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Collects engine-relative paths of files changed since the baseline's HEAD
+ * SHA plus any workdir modifications. Defensive — git failures surface as
+ * verbose lines and return the files collected so far. An empty result
+ * means "no drift we can prove" rather than "no drift occurred".
+ */
+async function collectBackendRelevantChanges(engineDir, baseline) {
+    const collected = new Set();
+    if (baseline.engineHeadSha) {
+        try {
+            const diff = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
+            for (const line of diff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+        }
+        catch (error) {
+            if (!isMissingHeadError(error)) {
+                verbose(`Auto-configure: could not diff engine against baseline — ${toError(error).message}`);
+            }
+        }
+    }
+    try {
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+            for (const file of await getUntrackedFiles(engineDir)) {
+                collected.add(file);
+            }
+        }
+    }
+    catch (error) {
+        verbose(`Auto-configure: could not enumerate workdir changes — ${toError(error).message}`);
+    }
+    return [...collected];
+}
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Cleans Furnace stories from engine (prevents leaking into production)
@@ -24,7 +82,7 @@ import { generateMozconfig } from './mach.js';
  * @param config - Loaded FireForge configuration
  * @returns Preparation results
  */
-export async function prepareBuildEnvironment(projectRoot, paths, config) {
+export async function prepareBuildEnvironment(projectRoot, paths, config, options = {}) {
     // Block the build if Furnace has an unresolved repair marker. This prevents
     // building against an engine that may be in an inconsistent state after a
     // failed rollback.
@@ -36,6 +94,33 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
                 'Run "fireforge doctor --repair-furnace" to reconcile engine state before building.');
         }
     }
+    // Auto-configure: if any backend-invalidating file (moz.build, moz.configure,
+    // Makefile.in) changed since the last successful build, run `mach configure`
+    // before the build step. Prevents incremental builds from silently skipping
+    // work against a stale recursive-make backend.
+    let reconfigured = false;
+    if (options.previousBaseline) {
+        const changed = await collectBackendRelevantChanges(paths.engine, options.previousBaseline);
+        const invalidating = changed.filter(isBackendInvalidatingFile);
+        if (invalidating.length > 0) {
+            info(`Backend config changed; running mach configure first... (${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched)`);
+            const configureSpinner = spinner('Running mach configure...');
+            try {
+                const exitCode = await runMach(['configure'], paths.engine);
+                if (exitCode !== 0) {
+                    configureSpinner.error('mach configure exited non-zero; continuing with build anyway');
+                }
+                else {
+                    configureSpinner.stop('Backend regenerated');
+                    reconfigured = true;
+                }
+            }
+            catch (error) {
+                configureSpinner.error('mach configure failed; continuing with build anyway');
+                verbose(`Auto-configure error: ${toError(error).message}`);
+            }
+        }
+    }
     // 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
@@ -117,6 +202,6 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
         mozconfigSpinner.error('Failed to generate mozconfig');
         throw error;
     }
-    return { furnaceApplied };
+    return { furnaceApplied, reconfigured };
 }
 //# sourceMappingURL=build-prepare.js.map

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

@@ -4,7 +4,8 @@ import { type RollbackJournal } from './furnace-rollback.js';
  * The signal names the lifecycle wrapper knows how to react to. Spelled out
  * as a literal union (rather than `NodeJS.Signals`) so the public type
  * surface does not depend on the NodeJS global namespace — consumers of
- * `@hominis/fireforge` may compile against tsconfigs that omit `@types/node`.
+ * FireForge's published scoped npm package may compile against tsconfigs
+ * that omit `@types/node`.
  */
 export type FurnaceShutdownSignal = 'SIGINT' | 'SIGTERM';
 /**

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

@@ -52,16 +52,22 @@ function withTimeout(promise, ms, label) {
  * timeout so a stuck I/O operation cannot hang the process indefinitely.
  */
 export async function rollbackActiveOperationsForSignal(signal) {
+    // Snapshot the active operations so we don't race with `runFurnaceMutation`
+    // clearing slots during normal completion. Filter completed bodies so a
+    // body sitting in its finally-block cleanup window is not counted as live
+    // work — this would mis-trigger the rollback banner for plain `fireforge
+    // run` (which never registers a mutation but can receive SIGTERM).
+    const snapshot = [...activeOperations.values()].filter((op) => !op.completed);
+    if (snapshot.length === 0) {
+        // Nothing to roll back. Stay silent so commands that never mutated (run,
+        // watch, test, doctor) don't print an alarming "rolling back mutations"
+        // line on Ctrl+C / SIGTERM. Leave `signalRollbackInFlight` false so a
+        // subsequent registrant can still trigger the full path.
+        return;
+    }
     signalRollbackInFlight = true;
     warn(`Received ${signal}; rolling back in-flight furnace mutations…`);
-    // Snapshot the active operations so we don't race with `runFurnaceMutation`
-    // clearing slots during normal completion.
-    const snapshot = [...activeOperations.values()];
     for (const op of snapshot) {
-        // If the body completed successfully and is in its finally-block cleanup
-        // (deleting the token), skip rollback — the mutation committed cleanly.
-        if (op.completed)
-            continue;
         const cleanupErrors = [];
         // Run extra cleanup callbacks first (e.g. preview's cleanStories), so the
         // engine is in its tidiest possible shape before the journal restore

package/dist/src/core/mach-error-hints.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pattern-based translator for cryptic mozbuild / mach errors.
+ *
+ * Each entry maps a stderr regex to an actionable hint. The goal is not to
+ * parse every mach failure — it's to convert the handful of errors whose
+ * message is non-obvious into a one-line "here's what to change". New
+ * entries should only be added when a concrete diagnosis of the cryptic
+ * output has been established; low-confidence hints would train operators
+ * to ignore the translator.
+ */
+/** A single translator entry. */
+export interface MachErrorHint {
+    /** Pattern to search within the captured mach stderr. */
+    pattern: RegExp;
+    /** Actionable, one-line hint to surface alongside the raw mach output. */
+    hint: string;
+}
+/**
+ * Registered hint patterns. Order-sensitive: the first match wins per
+ * pattern, but multiple distinct patterns may fire for the same stderr.
+ */
+export declare const MACH_ERROR_HINTS: MachErrorHint[];
+/**
+ * Scans captured stderr for known mach errors and returns matching hints.
+ * Pure function — safe to call on any string; never throws.
+ * @param stderr Captured mach stderr.
+ * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
+ */
+export declare function explainMachError(stderr: string): string[];

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

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Pattern-based translator for cryptic mozbuild / mach errors.
+ *
+ * Each entry maps a stderr regex to an actionable hint. The goal is not to
+ * parse every mach failure — it's to convert the handful of errors whose
+ * message is non-obvious into a one-line "here's what to change". New
+ * entries should only be added when a concrete diagnosis of the cryptic
+ * output has been established; low-confidence hints would train operators
+ * to ignore the translator.
+ */
+/**
+ * Registered hint patterns. Order-sensitive: the first match wins per
+ * pattern, but multiple distinct patterns may fire for the same stderr.
+ */
+export const MACH_ERROR_HINTS = [
+    {
+        pattern: /mozbuild\.preprocessor\.Preprocessor\.Error[\s\S]*?no preprocessor directives found/,
+        hint: 'A file registered under JS_PREFERENCE_PP_FILES contains no preprocessor directives. ' +
+            'Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.',
+    },
+];
+/**
+ * Scans captured stderr for known mach errors and returns matching hints.
+ * Pure function — safe to call on any string; never throws.
+ * @param stderr Captured mach stderr.
+ * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
+ */
+export function explainMachError(stderr) {
+    if (!stderr) {
+        return [];
+    }
+    const hits = [];
+    const seen = new Set();
+    for (const { pattern, hint } of MACH_ERROR_HINTS) {
+        if (pattern.test(stderr) && !seen.has(hint)) {
+            seen.add(hint);
+            hits.push(hint);
+        }
+    }
+    return hits;
+}
+//# sourceMappingURL=mach-error-hints.js.map