@hominis/fireforge 0.32.0 → 0.34.0

package/dist/src/commands/patch/split-plan.d.ts

@@ -7,6 +7,7 @@
  */
 import { type ConflictReport } from '../../core/destructive.js';
 import { buildProjectedManifest } from '../../core/patch-policy.js';
+import type { PatchStagedForwardImport } from '../../types/commands/index.js';
 import type { PatchCategory, PatchMetadata } from '../../types/commands/index.js';
 import type { FireForgeConfig } from '../../types/config.js';
 import { type PlacementPlan } from '../export-flow.js';
@@ -29,6 +30,14 @@ export interface SplitPlan {
     description: string;
     /** Patches (by current filename) whose staged-dependency owners re-point to the new patch. */
     ownerRewrites: string[];
+    /**
+     * Staged forward-import declarations the split introduces, keyed by the
+     * importing patch's post-rename filename. These are the new forward edges
+     * from existing patches into the freshly-created patch (owner known); they
+     * are injected into the projected lint so dry-run matches the real gate,
+     * and persisted on commit so the real per-patch gate stays clean.
+     */
+    stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
 }
 /**
  *
@@ -45,12 +54,19 @@ export declare function buildSplitDiff(engineDir: string, files: readonly string
 export declare function findOwnerRewriteHolders(patches: readonly PatchMetadata[], sourceFilename: string, movedSet: ReadonlySet<string>): string[];
 /** Rewrites split-affected owners on one manifest row. */
 export declare function rewriteSplitOwners(patch: PatchMetadata, sourceFilename: string, movedSet: ReadonlySet<string>, newFilename: string): PatchMetadata;
+/** Merges `decls` into a patch's `stagedDependencies.forwardImports` (no duplicates). */
+export declare function mergeStagedForwardImports(patch: PatchMetadata, decls: readonly PatchStagedForwardImport[]): PatchMetadata;
 /**
  * Projects the full split (renumber + shrunken source + synthetic new
  * patch + owner rewrites) through cross-patch lint, reporting only the
- * regressions the split itself would introduce.
+ * regressions the split itself would introduce. Forward edges into the new
+ * patch are auto-declared (and the declarations returned) so the projection
+ * matches the real per-patch gate the split leaves behind.
  */
-export declare function runProjectedSplitLint(patchesDir: string, plan: SplitPlan): Promise<ConflictReport | null>;
+export declare function runProjectedSplitLint(patchesDir: string, plan: SplitPlan): Promise<{
+    conflicts: ConflictReport | null;
+    stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
+}>;
 /** Builds the projected manifest for policy enforcement. */
 export declare function projectSplitManifest(manifest: {
     version: 1;

package/dist/src/commands/patch/split-plan.js

@@ -10,7 +10,7 @@ import { join } from 'node:path';
 import { getDiffForFilesAgainstHead } from '../../core/git-diff.js';
 import { computeProjectedLintRegressions } from '../../core/lint-projection.js';
 import { extractAffectedFiles } from '../../core/patch-apply.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, detectNewFilesInDiff, lintPatchQueue, } from '../../core/patch-lint.js';
 import { rewriteStagedDependencyOwners } from '../../core/patch-manifest.js';
 import { applyRenameMapToManifest, buildProjectedManifest } from '../../core/patch-policy.js';
 import { buildPatchSourceMetadata } from '../../core/patch-source-metadata.js';
@@ -82,16 +82,12 @@ function buildEntryProjection(diff) {
     }
     return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
 }
-/**
- * Projects the full split (renumber + shrunken source + synthetic new
- * patch + owner rewrites) through cross-patch lint, reporting only the
- * regressions the split itself would introduce.
- */
-export async function runProjectedSplitLint(patchesDir, plan) {
+/** Builds the projected post-split queue entries (renumber + shrunken source + new patch). */
+async function buildProjectedSplitEntries(patchesDir, plan) {
     const movedSet = new Set(plan.movedFiles);
     const ownerLookup = (old) => plan.placement.renameMap.get(old)?.newFilename;
     const baseCtx = await buildPatchQueueContext(patchesDir);
-    const projectedEntries = baseCtx.entries.map((entry) => {
+    const entries = baseCtx.entries.map((entry) => {
         let metadata = entry.metadata;
         if (metadata) {
             metadata = rewriteStagedDependencyOwners(metadata, ownerLookup);
@@ -105,13 +101,90 @@ export async function runProjectedSplitLint(patchesDir, plan) {
             return base;
         return { ...base, ...buildEntryProjection(plan.remainingDiff) };
     });
-    projectedEntries.push({
+    entries.push({
         filename: plan.placement.newFilename,
         order: plan.placement.insertionOrder,
         metadata: null,
         ...buildEntryProjection(plan.movedDiff),
     });
-    projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    entries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    return { baseCtx, entries };
+}
+/**
+ * Computes the staged forward-import declarations the split introduces:
+ * forward edges from existing patches into the freshly-created patch (its
+ * `creates` files are the moved files; the owner is the new patch, so it is
+ * known). Keyed by the importing patch's projected (post-rename) filename.
+ *
+ * These edges did not exist before the split (importer and imported file
+ * lived in the same patch), so they have no declaration yet — without this
+ * the projected lint flags them while the real per-patch gate would resolve
+ * them once declared. Auto-declaring keeps the two in lock-step and lets a
+ * sound split read as sound.
+ */
+function computeSplitStagedDependencyAdditions(projectedEntries, newFilename) {
+    const additions = new Map();
+    for (const edge of collectForwardImportEdges({ entries: projectedEntries })) {
+        if (edge.owner !== newFilename)
+            continue;
+        const decl = {
+            file: edge.sitePath,
+            specifier: edge.specifier,
+            creates: edge.creates,
+            owner: newFilename,
+        };
+        const list = additions.get(edge.entry) ?? [];
+        const dup = list.some((d) => d.file === decl.file &&
+            d.specifier === decl.specifier &&
+            d.creates === decl.creates &&
+            d.owner === decl.owner);
+        if (!dup)
+            list.push(decl);
+        additions.set(edge.entry, list);
+    }
+    return additions;
+}
+/** Merges `decls` into a patch's `stagedDependencies.forwardImports` (no duplicates). */
+export function mergeStagedForwardImports(patch, decls) {
+    if (decls.length === 0)
+        return patch;
+    const existing = patch.stagedDependencies?.forwardImports ?? [];
+    const merged = [...existing];
+    for (const decl of decls) {
+        const dup = merged.some((d) => d.file === decl.file &&
+            d.specifier === decl.specifier &&
+            d.creates === decl.creates &&
+            (d.owner ?? '') === (decl.owner ?? ''));
+        if (!dup)
+            merged.push(decl);
+    }
+    return {
+        ...patch,
+        stagedDependencies: { ...patch.stagedDependencies, forwardImports: merged },
+    };
+}
+/** Injects the computed staged-dependency additions into projected entries' metadata. */
+function injectStagedDependencyAdditions(entries, additions) {
+    for (const entry of entries) {
+        const decls = additions.get(entry.filename);
+        if (!decls?.length || !entry.metadata)
+            continue;
+        entry.metadata = mergeStagedForwardImports(entry.metadata, decls);
+    }
+}
+/**
+ * Projects the full split (renumber + shrunken source + synthetic new
+ * patch + owner rewrites) through cross-patch lint, reporting only the
+ * regressions the split itself would introduce. Forward edges into the new
+ * patch are auto-declared (and the declarations returned) so the projection
+ * matches the real per-patch gate the split leaves behind.
+ */
+export async function runProjectedSplitLint(patchesDir, plan) {
+    const { baseCtx, entries: projectedEntries } = await buildProjectedSplitEntries(patchesDir, plan);
+    // Discover and auto-declare the forward edges this split introduces into
+    // the new patch, then inject them before linting so they resolve.
+    const stagedDependencyAdditions = computeSplitStagedDependencyAdditions(projectedEntries, plan.placement.newFilename);
+    injectStagedDependencyAdditions(projectedEntries, stagedDependencyAdditions);
     const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
     const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
     const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
@@ -119,12 +192,13 @@ export async function runProjectedSplitLint(patchesDir, plan) {
         warn(`Note: projected queue still has ${baselineIssues.length} pre-existing cross-patch ` +
             'error(s) unrelated to this split. Run "fireforge verify" to list them.');
     }
-    if (regressions.length === 0)
-        return null;
-    return {
-        reason: `split would introduce ${regressions.length} cross-patch lint error(s)`,
-        details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
-    };
+    const conflicts = regressions.length === 0
+        ? null
+        : {
+            reason: `split would introduce ${regressions.length} cross-patch lint error(s)`,
+            details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+        };
+    return { conflicts, stagedDependencyAdditions };
 }
 /** Builds the projected manifest for policy enforcement. */
 export function projectSplitManifest(manifest, plan, newMetadata) {

package/dist/src/commands/patch/split.js

@@ -32,7 +32,7 @@ import { info, intro, outro, success, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
 import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, mergeStagedForwardImports, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
 /**
  * Commits a confirmed split under the patch directory lock: renumber →
  * write new patch body → write shrunken source body → single manifest
@@ -74,7 +74,13 @@ async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
             if (!fresh)
                 throw new GeneralError('Manifest disappeared during split commit.');
             const updatedPatches = fresh.patches.map((patch) => {
-                const withOwners = rewriteSplitOwners(patch, effectiveSourceFilename, movedSet, plan.placement.newFilename);
+                let withOwners = rewriteSplitOwners(patch, effectiveSourceFilename, movedSet, plan.placement.newFilename);
+                // Persist the auto-declared forward edges into the new patch so the
+                // real per-patch gate stays clean (keyed by post-rename filename).
+                const decls = plan.stagedDependencyAdditions.get(withOwners.filename);
+                if (decls?.length) {
+                    withOwners = mergeStagedForwardImports(withOwners, decls);
+                }
                 if (patch.filename !== effectiveSourceFilename)
                     return withOwners;
                 return { ...withOwners, filesAffected: plan.remainingFiles };
@@ -199,13 +205,16 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         name: options.name,
         description: options.description ?? '',
         ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
+        // Populated by runProjectedSplitLint below (forward edges into the new patch).
+        stagedDependencyAdditions: new Map(),
     };
     // Per-patch lint both projected bodies, threading the source patch's
     // tier/lintIgnore so an intentional-advisory patch can still split.
     const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
     await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
     await runPatchLint(paths.engine, movedFiles, movedDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
-    const conflicts = await runProjectedSplitLint(paths.patches, plan);
+    const { conflicts, stagedDependencyAdditions } = await runProjectedSplitLint(paths.patches, plan);
+    plan.stagedDependencyAdditions = stagedDependencyAdditions;
     const newMetadata = buildNewPatchMetadata(plan, config);
     enforcePatchPolicy({
         config,

package/dist/src/commands/re-export-options.d.ts

@@ -1,3 +1,29 @@
 import type { ReExportOptions } from '../types/commands/index.js';
+/** Result of {@link normalizeReExportFilesPositionals}. */
+export interface NormalizedReExportArguments {
+    patches: string[];
+    options: ReExportOptions;
+    /** Extra positionals that were folded into the `--files` list. */
+    foldedPaths: string[];
+}
+/**
+ * Accepts the `export`-style space-separated path shape for
+ * `re-export <patch> --files` (0.34.0 field report): commander's
+ * `--files <paths>` consumes one comma-separated value, so
+ * `re-export 006-x --files a/b.js c/d.js` used to park `c/d.js` in the
+ * positional patches and fail with "--files operates on exactly one
+ * target patch" — pointing at the wrong argument. When every positional
+ * beyond the first looks like a file path, fold them into the file list.
+ */
+export declare function normalizeReExportFilesPositionals(patches: readonly string[], options: ReExportOptions): NormalizedReExportArguments;
+/**
+ * Folding wrapper used by the command layer: applies
+ * {@link normalizeReExportFilesPositionals} and logs the folded paths so
+ * the operator sees exactly which positionals became file-list entries.
+ */
+export declare function applyReExportFilesPositionalFolding(patches: string[], options: ReExportOptions): {
+    patches: string[];
+    options: ReExportOptions;
+};
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export declare function validateReExportOptionCombinations(patches: readonly string[], options: ReExportOptions): void;

package/dist/src/commands/re-export-options.js

@@ -1,5 +1,50 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { InvalidArgumentError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
+/**
+ * Heuristic for `--files` positional folding: an extra positional that
+ * contains a path separator and is not a `.patch` filename is an engine
+ * file path, not a patch identifier.
+ */
+function looksLikeFilePath(value) {
+    return value.includes('/') && !value.endsWith('.patch');
+}
+/**
+ * Accepts the `export`-style space-separated path shape for
+ * `re-export <patch> --files` (0.34.0 field report): commander's
+ * `--files <paths>` consumes one comma-separated value, so
+ * `re-export 006-x --files a/b.js c/d.js` used to park `c/d.js` in the
+ * positional patches and fail with "--files operates on exactly one
+ * target patch" — pointing at the wrong argument. When every positional
+ * beyond the first looks like a file path, fold them into the file list.
+ */
+export function normalizeReExportFilesPositionals(patches, options) {
+    if (options.files === undefined || patches.length <= 1) {
+        return { patches: [...patches], options, foldedPaths: [] };
+    }
+    const [first, ...rest] = patches;
+    if (first !== undefined && rest.every(looksLikeFilePath)) {
+        return {
+            patches: [first],
+            options: { ...options, files: [...options.files, ...rest] },
+            foldedPaths: rest,
+        };
+    }
+    return { patches: [...patches], options, foldedPaths: [] };
+}
+/**
+ * Folding wrapper used by the command layer: applies
+ * {@link normalizeReExportFilesPositionals} and logs the folded paths so
+ * the operator sees exactly which positionals became file-list entries.
+ */
+export function applyReExportFilesPositionalFolding(patches, options) {
+    const normalized = normalizeReExportFilesPositionals(patches, options);
+    if (normalized.foldedPaths.length > 0) {
+        info(`--files: treating ${normalized.foldedPaths.length} extra positional path(s) as part ` +
+            `of the file list: ${normalized.foldedPaths.join(', ')}`);
+    }
+    return { patches: normalized.patches, options: normalized.options };
+}
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export function validateReExportOptionCombinations(patches, options) {
     if (options.files !== undefined) {
@@ -10,7 +55,9 @@ export function validateReExportOptionCombinations(patches, options) {
             throw new InvalidArgumentError('--files cannot be combined with --scan-files.', '--files');
         }
         if (patches.length !== 1) {
-            throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier.', '--files');
+            throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier. ' +
+                'File paths can be passed space-separated after --files (path-shaped extras are folded ' +
+                'into the file list automatically) or as one comma-separated --files value.', '--files');
         }
     }
     if (options.scanFiles !== undefined) {

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

@@ -19,7 +19,7 @@ import { pickDefined } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
 import { loadScanFilesAssignments, withDryRunReExportLock } from './re-export-bulk-scan.js';
 import { reExportFilesInPlace } from './re-export-files.js';
-import { validateReExportOptionCombinations } from './re-export-options.js';
+import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
 import { assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
 async function findMissingFiles(engineDir, files) {
     const missingFiles = [];
@@ -286,6 +286,9 @@ export async function reExportCommand(projectRoot, patches, options) {
     }
     const isDryRun = options.dryRun === true;
     intro(isDryRun ? 'FireForge Re-export (dry run)' : 'FireForge Re-export');
+    // Accept export-style space-separated paths after --files by folding
+    // path-shaped extra positionals into the file list (0.34.0 field report).
+    ({ patches, options } = applyReExportFilesPositionalFolding(patches, options));
     validateReExportOptionCombinations(patches, options);
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists

package/dist/src/commands/register.js

@@ -43,7 +43,9 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
             throw new InvalidArgumentError(`File not found in engine: ${engineRelativePath}`, 'path');
         }
     }
-    const result = await registerFile(projectRoot, engineRelativePath, options.dryRun, options.after);
+    const result = await registerFile(projectRoot, engineRelativePath, options.dryRun, options.after, {
+        ...(options.createManifest !== undefined ? { createManifest: options.createManifest } : {}),
+    });
     if (options.dryRun) {
         // 2026-04-21 eval (Finding #8): dry-run always said "Would
         // register" even when the rule's idempotency check already knew
@@ -59,6 +61,9 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
         info(`[dry-run] Would register ${engineRelativePath}`);
         info(`  manifest: ${result.manifest}`);
         info(`  entry: ${result.entry}`);
+        for (const action of result.scaffoldActions ?? []) {
+            info(`  scaffold: ${action.manifest} — ${action.change}`);
+        }
         if (result.previousEntry) {
             info(`  insert after: ${result.previousEntry}`);
         }
@@ -80,6 +85,9 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
         }
         const position = result.previousEntry ? ` (after ${result.previousEntry})` : '';
         success(`Registered ${engineRelativePath} in ${result.manifest}${position}`);
+        for (const action of result.scaffoldActions ?? []) {
+            info(`  scaffold: ${action.manifest} — ${action.change}`);
+        }
         info("hint: Run 'fireforge build --ui' to make the new module available at runtime");
     }
     outro('Done');
@@ -91,6 +99,7 @@ export function registerRegister(program, { getProjectRoot, withErrorHandling })
         .description('Register a file in the appropriate build manifest')
         .option('--dry-run', 'Show what would be changed without writing')
         .option('--after <entry>', 'Place entry after line containing this substring (instead of alphabetical)')
+        .option('--create-manifest', 'Scaffold a missing manifest (directory moz.build with EXTRA_JS_MODULES / XPCSHELL_TESTS_MANIFESTS, or xpcshell.toml) and wire the parent DIRS chain instead of failing with "Manifest not found"')
         .action(withErrorHandling(async (path, options) => {
         await registerCommand(getProjectRoot(), path, pickDefined(options));
     }));

package/dist/src/commands/test-diagnose.js

@@ -183,6 +183,18 @@ export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, p
     if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
         throw new GeneralError(buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts));
     }
+    if (outcome.verdict.kind === 'tests-ran-ok') {
+        // The verdict is authoritative over the raw exit code: a completed
+        // green embedded summary overrides a non-zero exit caused by harness
+        // noise (field report: fully green --no-shard runs exited 1, forcing
+        // operators to parse embedded summaries by hand).
+        if (outcome.verdict.greenSummaryOverride) {
+            info(`Note: mach exited ${outcome.result.exitCode}, but the embedded suite summary completed ` +
+                'green (Unexpected results: 0). FireForge treats the run as passed; the non-zero exit ' +
+                'came from non-fatal harness noise (resource-monitor degradation / telemetry).');
+        }
+        return;
+    }
     if (outcome.verdict.kind === 'no-tests' && outcome.result.exitCode === 0) {
         // The silent false green: exit 0 plus a "Passed: 0"-style summary with
         // zero TEST-START lines must fail, not pass.

package/dist/src/commands/test.js

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, resolve } from 'node:path';
+import { readBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, withBuildLock, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, runProtectedMachBuild, withBuildLock, } from '../core/mach.js';
 import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
-import { buildHarnessCrashMessage, detectHarnessCrashSignature, } from '../core/test-harness-crash.js';
+import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
@@ -102,29 +103,35 @@ async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
 }
 async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries) {
     await withBuildLock(projectRoot, async () => {
-        await prepareBuildEnvironment(projectRoot, paths, projectConfig);
+        // Pass the previous baseline exactly like `fireforge build` does, so
+        // auto-configure runs under the same conditions on both paths. The
+        // pre-test build must never invalidate more of the objdir than a plain
+        // `mach build faster` would (field incident: a failed pre-test build
+        // was followed by a ~64-minute full rebuild where an incremental one
+        // should have sufficed).
+        const previousBaseline = await readBuildBaseline(projectRoot);
+        await prepareBuildEnvironment(projectRoot, paths, projectConfig, { previousBaseline });
         const s = spinner('Running incremental build...');
-        // The pre-test build runs through mach too, so the same resource-monitor
-        // startup crash that aborts `mach test` can abort `mach build faster`.
-        // Run the harness-crash classifier over the build output and retry within
-        // the same `--harness-retries` budget rather than hard-failing with a
-        // bare "Pre-test build failed" (field report E2).
-        const maxAttempts = Math.max(1, harnessRetries + 1);
-        for (let attempt = 1;; attempt += 1) {
-            const buildResult = await buildUI(paths.engine);
-            if (buildResult.exitCode === 0) {
-                s.stop('Build complete');
-                return;
-            }
-            const signature = detectHarnessCrashSignature(`${buildResult.stdout}\n${buildResult.stderr}`);
-            if (signature && attempt < maxAttempts) {
+        // The pre-test build routes through the same protected mach dispatch as
+        // `fireforge build` / `build --ui`: in-venv resource-monitor guard plus
+        // the uniform recognized-crash retry budget, with a fresh mach process
+        // (and fresh guard install) per attempt. prepareBuildEnvironment runs
+        // ONCE, outside the retry loop — retries never re-run mach configure.
+        const result = await runProtectedMachBuild('faster', paths.engine, {
+            retries: harnessRetries,
+            onRetry: (signature, nextAttempt, maxAttempts) => {
                 s.message(`Pre-test build hit a harness crash (${signature.reason}); ` +
-                    `retrying (attempt ${attempt + 1} of ${maxAttempts})...`);
-                continue;
-            }
-            s.error('Pre-test build failed');
-            throw new BuildError(signature ? buildHarnessCrashMessage(signature, attempt) : 'Pre-test build failed', 'mach build faster');
+                    `retrying (attempt ${nextAttempt} of ${maxAttempts})...`);
+            },
+        });
+        if (result.exitCode === 0) {
+            s.stop('Build complete');
+            return;
         }
+        s.error('Pre-test build failed');
+        throw new BuildError(result.crashSignature
+            ? buildHarnessCrashMessage(result.crashSignature, result.attempts, 'mach build faster')
+            : 'Pre-test build failed', 'mach build faster');
     });
 }
 function logTestSelection(normalizedPaths) {

package/dist/src/commands/token.js

@@ -74,12 +74,18 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
             ...(options.description !== undefined ? { description: options.description } : {}),
             ...(options.darkValue !== undefined ? { darkValue: options.darkValue } : {}),
             ...(options.createCategory === true ? { createCategory: true } : {}),
+            ...(options.variant !== undefined ? { variant: options.variant } : {}),
             dryRun: true,
         });
         info('[dry-run] Would add token:');
         info(`  Name: ${tokenName}`);
         info(`  Value: ${value}`);
-        info(`  Category: ${options.category}${options.createCategory === true ? ' (created if missing)' : ''}`);
+        if (options.variant !== undefined) {
+            info(`  Variant: :root${options.variant}`);
+        }
+        else {
+            info(`  Category: ${options.category}${options.createCategory === true ? ' (created if missing)' : ''}`);
+        }
         info(`  Mode: ${options.mode}`);
         if (options.description)
             info(`  Description: ${options.description}`);
@@ -96,6 +102,7 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
         ...(options.description !== undefined ? { description: options.description } : {}),
         ...(options.darkValue !== undefined ? { darkValue: options.darkValue } : {}),
         ...(options.createCategory === true ? { createCategory: true } : {}),
+        ...(options.variant !== undefined ? { variant: options.variant } : {}),
     });
     if (result.skipped) {
         info(`Token ${tokenName} already exists (skipped)`);
@@ -151,6 +158,9 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .makeOptionMandatory(true))
         .option('--description <desc>', 'Comment description for the CSS file')
         .option('--dark-value <val>', 'Dark mode value (required if mode is "override")')
+        .option('--variant <selector>', 'Attribute selector fragment routing the declaration into a `:root<selector>` block ' +
+        "(e.g. '[data-skin=precision]' or '[data-private]'); creates or updates the block. " +
+        'CSS-only — cannot be combined with --mode override.')
         .option('--create-category', 'Declare the category banner in the tokens CSS if it does not exist yet')
         .option('--dry-run', 'Show what would be changed without writing')
         .action(withErrorHandling(async (tokenName, value, options) => {
@@ -162,6 +172,7 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
                 darkValue: options.darkValue,
                 dryRun: options.dryRun,
                 createCategory: options.createCategory,
+                variant: options.variant,
             }),
         });
     }));

package/dist/src/commands/typecheck.js

@@ -16,6 +16,8 @@
  * but do not fail. Designed for CI use.
  */
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
+import { findJsconfigPathsDrift, syncFurnaceJsconfigPaths } from '../core/furnace-jsconfig.js';
 import { relativeForDisplay, runTypecheck } from '../core/typecheck.js';
 import { GeneralError } from '../errors/base.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
@@ -32,6 +34,11 @@ export function resolveTypecheckProjects(configTypecheck, override) {
         return {
             projects: [override],
             ...(configTypecheck?.extraShim !== undefined ? { extraShim: configTypecheck.extraShim } : {}),
+            // Preserve any per-project override for the targeted path so a one-off
+            // `--project` run honours its opt-out / shim override just like a full run.
+            ...(configTypecheck?.projectOverrides !== undefined
+                ? { projectOverrides: configTypecheck.projectOverrides }
+                : {}),
         };
     }
     if (!configTypecheck) {
@@ -64,10 +71,38 @@ export async function typecheckCommand(projectRoot, options) {
     getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
     const cfg = resolveTypecheckProjects(config.typecheck, options.project);
+    // Regenerate a stale Furnace-managed jsconfig before running: the generated
+    // `compilerOptions.paths` shim drifts when components are added/renamed
+    // without a re-deploy, and a stale shim reports type errors in files the
+    // session never touched (e.g. 47 phantom errors from an out-of-date
+    // chrome-module mapping). Run the same reconciler `furnace deploy`/`sync`
+    // use so typecheck checks against the current workspace.
+    await regenerateStaleGeneratedJsconfig(projectRoot);
     info(`Running typecheck across ${String(cfg.projects.length)} project(s): ${cfg.projects.join(', ')}`);
     const results = await runTypecheck(projectRoot, cfg);
     reportResults(projectRoot, results);
 }
+/**
+ * Staleness-checks and regenerates the Furnace-managed jsconfig
+ * (`furnace.json` → `typecheckJsconfig`) before typecheck runs. No-op when
+ * the project has no furnace.json or no `typecheckJsconfig` is configured.
+ * A missing `typecheckJsconfig` file surfaces the reconciler's own clear
+ * error rather than producing phantom type diagnostics.
+ */
+async function regenerateStaleGeneratedJsconfig(projectRoot) {
+    if (!(await furnaceConfigExists(projectRoot)))
+        return;
+    const furnaceConfig = await loadFurnaceConfig(projectRoot);
+    if (!furnaceConfig.typecheckJsconfig)
+        return;
+    const drift = await findJsconfigPathsDrift(projectRoot, furnaceConfig);
+    if (!drift.changed)
+        return;
+    info(`Regenerating stale generated jsconfig ${furnaceConfig.typecheckJsconfig} before typecheck ` +
+        `(+${String(drift.added.length)} added, ~${String(drift.updated.length)} updated, ` +
+        `-${String(drift.pruned.length)} pruned).`);
+    await syncFurnaceJsconfigPaths(projectRoot, furnaceConfig);
+}
 /**
  * Prints all issues, computes the per-project + total counts, and
  * throws on errors. Extracted so it can be exercised directly by

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

@@ -14,9 +14,23 @@ 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, runMach } from './mach.js';
+import { generateMozconfig, runMachCapture } from './mach.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
+/**
+ * Extracts the tail of captured `mach configure` output so the underlying
+ * mozbuild failure (e.g. `mozbuild.util.UnsortedError: ... is not in sorted
+ * order`) is carried into the thrown `BuildError` instead of being reduced to
+ * a bare exit code. mozbuild writes the error and its traceback to stderr;
+ * stdout is included as a fallback for shells that interleave the streams.
+ * Returns an empty string when nothing useful was captured.
+ */
+function extractMachConfigureError(result) {
+    const combined = `${result.stderr}\n${result.stdout}`.trim();
+    if (!combined)
+        return '';
+    return combined.split('\n').slice(-40).join('\n').trim();
+}
 /**
  * Returns true when the file path matches a pattern that forces
  * `mach configure` to regenerate the backend. Exported for testing.
@@ -65,10 +79,16 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
             info(`Backend command: mach configure`);
             const configureSpinner = spinner('Running mach configure...');
             try {
-                const exitCode = await runMach(['configure'], paths.engine);
+                const captured = await runMachCapture(['configure'], paths.engine);
+                const exitCode = captured.exitCode;
                 if (exitCode !== 0) {
                     configureSpinner.error(`mach configure failed with exit code ${exitCode}`);
-                    throw new BuildError(`Backend regeneration failed: mach configure exited with code ${exitCode}. Build stopped because continuing would hide the real configure failure.`, 'mach configure');
+                    // Surface the underlying mozbuild error (e.g. UnsortedError) instead
+                    // of a bare exit code — the generic message hid the actual cause.
+                    const detail = extractMachConfigureError(captured);
+                    throw new BuildError(`Backend regeneration failed: mach configure exited with code ${exitCode}.` +
+                        (detail ? `\n\nmach configure output (tail):\n${detail}` : '') +
+                        '\n\nBuild stopped because continuing would hide the real configure failure.', 'mach configure');
                 }
                 else {
                     configureSpinner.stop('Backend regenerated successfully (mach configure exit code 0)');