@hominis/fireforge 0.37.0 → 0.39.0

package/dist/src/core/patch-lint.js

@@ -10,6 +10,7 @@ import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-dif
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
+import { lintMozBuildSortedLists } from './patch-lint-mozbuild.js';
 import { lintObserverTopics } from './patch-lint-observer.js';
 import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 // ---------------------------------------------------------------------------
@@ -35,15 +36,33 @@ const FILE_SIZE_THRESHOLDS = {
     general: { notice: 500, warning: 750, error: 900 },
     test: { notice: 1200, warning: 1400, error: 1600 },
 };
+/**
+ * Counts the lines of `content` the way `wc -l` reports them: a trailing
+ * newline terminates the last line rather than starting an empty extra
+ * one. A naive `split('\n').length` over-counts by one for any content
+ * ending in `\n` (the common case), which made the size rules fire one
+ * line early against the operator's own `wc -l` measurement.
+ */
+function countContentLines(content) {
+    const lines = content.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines.length;
+}
 /**
  * Counts the total lines in a unified diff and the number of non-binary
  * text lines, so binary hunks do not inflate patch size checks.
  *
+ * Line counting agrees with `wc -l`: a trailing newline does not add a
+ * phantom empty line to either `total` or the binary-hunk accounting.
+ *
  * @param diffContent - Raw unified diff string
  * @returns Object with `total` line count and `textLines` (total minus binary hunk lines)
  */
 export function countNonBinaryDiffLines(diffContent) {
     const lines = diffContent.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
     const total = lines.length;
     let binaryLines = 0;
     let inBinaryHunk = false;
@@ -329,12 +348,12 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
         }
         // 2. File size check (new files only)
         if (isNew) {
-            const lineCount = content.split('\n').length;
+            const lineCount = countContentLines(content);
             const isTest = isTestFile(file);
             const thresholds = isTest ? FILE_SIZE_THRESHOLDS.test : FILE_SIZE_THRESHOLDS.general;
             const label = isTest ? 'Test file' : 'New file';
             const verb = isTest ? 'splitting' : 'decomposing';
-            if (lineCount >= thresholds.error) {
+            if (lineCount > thresholds.error) {
                 issues.push({
                     file,
                     check: 'file-too-large',
@@ -342,7 +361,7 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
                     severity: 'error',
                 });
             }
-            else if (lineCount >= thresholds.warning) {
+            else if (lineCount > thresholds.warning) {
                 issues.push({
                     file,
                     check: 'file-too-large',
@@ -350,7 +369,7 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
                     severity: 'warning',
                 });
             }
-            else if (lineCount >= thresholds.notice) {
+            else if (lineCount > thresholds.notice) {
                 issues.push({
                     file,
                     check: 'file-too-large',
@@ -507,7 +526,7 @@ export function lintPatchSize(filesAffected, lineCount, patchTier) {
             severity: 'warning',
         });
     }
-    if (lineCount >= lineThresholds.error) {
+    if (lineCount > lineThresholds.error) {
         issues.push({
             file: AGGREGATE_PATCH_FILE,
             check: 'large-patch-lines',
@@ -515,7 +534,7 @@ export function lintPatchSize(filesAffected, lineCount, patchTier) {
             severity: 'error',
         });
     }
-    else if (lineCount >= lineThresholds.warning) {
+    else if (lineCount > lineThresholds.warning) {
         issues.push({
             file: AGGREGATE_PATCH_FILE,
             check: 'large-patch-lines',
@@ -523,7 +542,7 @@ export function lintPatchSize(filesAffected, lineCount, patchTier) {
             severity: 'warning',
         });
     }
-    else if (lineCount >= lineThresholds.notice) {
+    else if (lineCount > lineThresholds.notice) {
         issues.push({
             file: AGGREGATE_PATCH_FILE,
             check: 'large-patch-lines',
@@ -598,11 +617,12 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
     const patchOwnedChromeScripts = resolvePatchOwnedChromeScripts(newFiles, patchQueueCtx);
-    const [cssIssues, headerIssues, jsIssues, modifiedHeaderIssues] = await Promise.all([
+    const [cssIssues, headerIssues, jsIssues, modifiedHeaderIssues, mozBuildIssues] = await Promise.all([
         lintPatchedCss(repoDir, affectedFiles, diffContent, config),
         lintNewFileHeaders(repoDir, [...newFiles], config),
         lintPatchedJs(repoDir, affectedFiles, newFiles, config, patchOwnedFiles, patchOwnedChromeScripts),
         lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),
+        lintMozBuildSortedLists(repoDir, affectedFiles),
     ]);
     const modCommentIssues = lintModificationComments(diffContent, config);
     const sizeIssues = options?.skipPatchSize
@@ -615,6 +635,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         ...modifiedHeaderIssues,
         ...jsIssues,
         ...modCommentIssues,
+        ...mozBuildIssues,
     ];
     if (options?.precomputedCheckJs) {
         // Per-patch lint built one queue-wide program and already attributed

package/dist/src/core/patch-policy.d.ts

@@ -7,7 +7,7 @@
  * `patch reorder`, etc.).
  */
 import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
+import type { FireForgeConfig, PatchPolicyConfig, PatchPolicyRange } from '../types/config.js';
 /** Stable issue codes returned by patch policy evaluation. */
 export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap';
 /** A single patch policy validation finding. */
@@ -28,6 +28,19 @@ export interface PatchPolicyEnforcementInput {
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];
 /** Checks whether a category is accepted by legacy defaults or the policy ranges. */
 export declare function isCategoryAllowedByConfig(config: FireForgeConfig, category: string): boolean;
+/**
+ * Human-readable label for a category's configured ranges, e.g. `300-399`.
+ * Exported for the forward-import hint (FORGE F14), which must render the
+ * range it found no legal ordinal in.
+ */
+export declare function categoryRangeLabel(ranges: readonly PatchPolicyRange[], category: string): string;
+/**
+ * Returns the configured range that contains `order` for `category`, or
+ * null when no such range exists. Exported for the forward-import hint
+ * (FORGE F14), which suppresses ordinal suggestions the reorder policy
+ * would refuse.
+ */
+export declare function categoryRangeForOrder(cfg: PatchPolicyConfig, category: string, order: number): PatchPolicyRange | null;
 /** Evaluates an entire patch manifest against the configured policy. */
 export declare function evaluatePatchPolicy(config: FireForgeConfig, manifest: PatchesManifest): PatchPolicyIssue[];
 /** Builds a sorted manifest snapshot from projected patch metadata. */

package/dist/src/core/patch-policy.js

@@ -45,7 +45,12 @@ export function isCategoryAllowedByConfig(config, category) {
 function rangeLabel(range) {
     return `${String(range.from).padStart(3, '0')}-${String(range.to).padStart(3, '0')}`;
 }
-function categoryRangeLabel(ranges, category) {
+/**
+ * Human-readable label for a category's configured ranges, e.g. `300-399`.
+ * Exported for the forward-import hint (FORGE F14), which must render the
+ * range it found no legal ordinal in.
+ */
+export function categoryRangeLabel(ranges, category) {
     const matches = ranges.filter((range) => range.category === category);
     if (matches.length === 0)
         return '(no configured range)';
@@ -54,7 +59,13 @@ function categoryRangeLabel(ranges, category) {
 function reservedRangeForOrder(cfg, order) {
     return cfg.reservedRanges?.find((range) => order >= range.from && order <= range.to) ?? null;
 }
-function categoryRangeForOrder(cfg, category, order) {
+/**
+ * Returns the configured range that contains `order` for `category`, or
+ * null when no such range exists. Exported for the forward-import hint
+ * (FORGE F14), which suppresses ordinal suggestions the reorder policy
+ * would refuse.
+ */
+export function categoryRangeForOrder(cfg, category, order) {
     return (cfg.ranges.find((range) => {
         return range.category === category && order >= range.from && order <= range.to;
     }) ?? null);

package/dist/src/core/status-classify.d.ts

@@ -11,12 +11,21 @@
  *   normal after `fireforge import`.
  * - `patch-owned-drift`: the file is claimed by exactly one patch, but
  *   the live engine content no longer matches that patch's expected
- *   post-apply content.
+ *   post-apply content. This includes furnace-prefixed paths: a path
+ *   can be both Furnace-managed and patch-claimed (export a deployed
+ *   component, then edit the workspace source and `furnace deploy`
+ *   again — the deployed copy now has content the patch body lacks).
+ *   Before 0.38.0 the furnace prefix check ran first and silently
+ *   bucketed such files as `furnace`, so `status` reported the stale
+ *   patch as owned.
  * - `unmanaged`: edits not explained by any patch or tool — local
  *   drift to export or discard.
  * - `branding`: files under tool-managed branding paths, written by
  *   FireForge's branding pipeline.
- * - `furnace`: files under Furnace-managed component prefixes.
+ * - `furnace`: files under Furnace-managed component prefixes. When
+ *   exactly one patch also claims the path, this bucket asserts the
+ *   live content matches that patch's expected post-apply content —
+ *   a mismatch is reported as `patch-owned-drift` instead (see above).
  * - `conflict`: the file is claimed by two or more patches in
  *   `patches.json`. The human `--ownership` mode already surfaces
  *   this bucket as `CONFLICT`; the classification is carried through

package/dist/src/core/status-classify.js

@@ -55,6 +55,40 @@ function isGeneratedBrandingPath(file, binaryName) {
         normalized === `${brandingRoot}/locales/en-US/brand.properties` ||
         normalized === `${brandingRoot}/locales/en-US/brand.ftl`);
 }
+/**
+ * Compares a single-owner file's live engine content against its owning
+ * patch's expected post-apply content. `matchClassification` is what a
+ * clean match reports — `patch-backed` for ordinary patch-claimed paths,
+ * `furnace` for furnace-prefixed paths so healthy deployed components
+ * keep landing in the pinned furnace bucket. Any mismatch (including a
+ * deletion the patch does not expect, or a failed comparison) reports
+ * `patch-owned-drift`.
+ */
+async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassification) {
+    if (getPrimaryStatusCode(entry.status) === 'D') {
+        // Deleted file: content matches only if the patch expects deletion
+        const expected = await computePatchedContent(patchesDir, engineDir, entry.file);
+        return {
+            ...entry,
+            classification: expected === null ? matchClassification : 'patch-owned-drift',
+        };
+    }
+    // File exists on disk — compare actual vs expected
+    try {
+        const [expected, actual] = await Promise.all([
+            computePatchedContent(patchesDir, engineDir, entry.file),
+            readText(join(engineDir, entry.file)),
+        ]);
+        return {
+            ...entry,
+            classification: actual === expected ? matchClassification : 'patch-owned-drift',
+        };
+    }
+    catch (error) {
+        verbose(`Treating ${entry.file} as patch-owned drift because patch-backed classification failed: ${toError(error).message}`);
+        return { ...entry, classification: 'patch-owned-drift' };
+    }
+}
 /**
  * Classifies files into patch-backed, unmanaged, branding, furnace, or
  * conflict buckets.
@@ -104,7 +138,20 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
                 }
             }
             if (isFurnace) {
-                results.push({ ...entry, classification: 'furnace' });
+                // A furnace path claimed by exactly one patch gets the same
+                // expected-vs-actual comparison as any other single-owner path:
+                // after a `furnace deploy` of an edited component the deployed
+                // copy has content the owning patch's body lacks, and the old
+                // unconditional short-circuit silently bucketed that drift as
+                // `furnace`. Multi-owner and unowned furnace paths keep the
+                // short-circuit — the ownership table independently flags
+                // filesAffected conflicts.
+                if (owners && owners.length === 1) {
+                    results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'furnace'));
+                }
+                else {
+                    results.push({ ...entry, classification: 'furnace' });
+                }
                 continue;
             }
         }
@@ -127,30 +174,7 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
             continue;
         }
         // File is claimed by exactly one patch — compare content.
-        if (primaryCode === 'D') {
-            // Deleted file: patch-backed only if patch expects deletion
-            const expected = await computePatchedContent(patchesDir, engineDir, entry.file);
-            results.push({
-                ...entry,
-                classification: expected === null ? 'patch-backed' : 'patch-owned-drift',
-            });
-            continue;
-        }
-        // File exists on disk — compare actual vs expected
-        try {
-            const [expected, actual] = await Promise.all([
-                computePatchedContent(patchesDir, engineDir, entry.file),
-                readText(join(engineDir, entry.file)),
-            ]);
-            results.push({
-                ...entry,
-                classification: actual === expected ? 'patch-backed' : 'patch-owned-drift',
-            });
-        }
-        catch (error) {
-            verbose(`Treating ${entry.file} as patch-owned drift because patch-backed classification failed: ${toError(error).message}`);
-            results.push({ ...entry, classification: 'patch-owned-drift' });
-        }
+        results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'patch-backed'));
     }
     return results;
 }

package/dist/src/core/test-harness-crash.d.ts

@@ -154,6 +154,16 @@ export declare function classifyHarnessRun(exitCode: number, output: string, req
 export declare function buildGreenSummaryRejectedMessage(rejection: GreenSummaryRejection, exitCode: number): string;
 /** Builds the operator-facing failure message after retries are exhausted. */
 export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number, commandLabel?: string): string;
+/**
+ * Optional hint appended to the harness-crash message when a HEADED run on
+ * macOS died at the no-output timeout: the display may have slept and frozen
+ * the headed browser before any test started (FORGE F17). Pure — the
+ * platform is injected so unit tests need no mocking.
+ */
+export declare function headedNoOutputTimeoutHint(signature: HarnessCrashSignature, context: {
+    headless: boolean;
+    platform: string;
+}): string | undefined;
 /**
  * Builds the message for a run that produced no `TEST-START` despite
  * requesting paths — including exit-code-zero runs whose `Passed: 0`

package/dist/src/core/test-harness-crash.js

@@ -537,6 +537,22 @@ export function buildHarnessCrashMessage(signature, attempts, commandLabel = 'ma
         'If it persists across many runs, inspect the mach virtualenv (mach resyncs psutil on its own; ' +
         'patching it manually does not stick).');
 }
+/**
+ * Optional hint appended to the harness-crash message when a HEADED run on
+ * macOS died at the no-output timeout: the display may have slept and frozen
+ * the headed browser before any test started (FORGE F17). Pure — the
+ * platform is injected so unit tests need no mocking.
+ */
+export function headedNoOutputTimeoutHint(signature, context) {
+    if (context.platform !== 'darwin' || context.headless)
+        return undefined;
+    if (!signature.reason.includes('no-output timeout'))
+        return undefined;
+    return ('Hint: this was a HEADED run on macOS that died at the no-output timeout. ' +
+        'A common cause is the display going to sleep mid-run, which freezes the headed browser ' +
+        'before any test starts. Wrap headed runs in `caffeinate -dimsu <command>` to keep the ' +
+        'display awake, or pass --headless.');
+}
 /**
  * Builds the message for a run that produced no `TEST-START` despite
  * requesting paths — including exit-code-zero runs whose `Passed: 0`

package/dist/src/core/test-stale-check.d.ts

@@ -1,4 +1,6 @@
+import { isXpcomManifestPath } from './build-audit.js';
 import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
+export { isXpcomManifestPath };
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */
@@ -53,7 +55,10 @@ export declare const FULL_SUITE_REQUEST = "(entire suite)";
  *
  * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
  * everything. A scoped list covers a request path when the request equals a
- * covered entry or sits beneath a covered directory entry. Both sides are
+ * covered entry, sits beneath a covered directory entry, or shares a
+ * manifest granule with a covered entry ({@link toManifestGranule} — a
+ * scoped `test --build` packages the whole manifest directory, so a
+ * same-manifest sibling of a covered file is packaged too). Both sides are
  * normalized to forward slashes so Windows-style CLI input cannot defeat
  * the prefix rule (baseline paths are POSIX by convention). A request with
  * no paths is a full-suite run and is never covered by a scoped list — the
@@ -68,3 +73,53 @@ export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverag
  * independently (same split as {@link formatStaleBuildWarning}).
  */
 export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[]): string;
+/** Result of the compiled-StaticComponents staleness probe. */
+export interface StaticComponentsStaleResult {
+    /** True when at least one `components.conf` genuinely diverged from the anchor. */
+    stale: boolean;
+    /**
+     * Engine-relative `components.conf` paths changed since the last FULL
+     * build. Sorted; NOT capped — {@link formatStaticComponentsRefusal}
+     * applies the render cap.
+     */
+    changedManifests: string[];
+}
+/**
+ * Probes whether any `components.conf` changed since the last FULL
+ * `fireforge build` — i.e. since the compiled StaticComponents table was
+ * last regenerated. `components.conf` entries bake into compiled code; a
+ * scoped `test --build` packages the file but the child process resolves
+ * the OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a
+ * test bug.
+ *
+ * The diff anchors to the baseline's `staticComponentsBaseline` (the last
+ * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`
+ * which a scoped `test --build` advances. Dirty candidates are hash-checked
+ * against the anchor's fingerprints so only genuine content divergence
+ * counts. No baseline / no anchor (pre-0.38.0 marker) → fresh. Never
+ * throws — the probes it composes degrade to verbose lines and empty
+ * results on git failure, matching {@link checkStaleBuildForTest}.
+ */
+export declare function checkStaticComponentsStale(engineDir: string, baseline: BuildBaseline | undefined): Promise<StaticComponentsStaleResult>;
+/**
+ * Formats the refusal shown when a run would dispatch against a stale
+ * compiled StaticComponents table. Same probe/copy split as
+ * {@link formatStaleBuildWarning} so tests can pin structure and wording
+ * independently.
+ */
+export declare function formatStaticComponentsRefusal(changedManifests: string[]): string;
+/**
+ * Formats the post-mutation advisory printed by `fireforge reset` /
+ * `fireforge import` when `components.conf` diverged from the last full
+ * build (FORGE F13). Same probe as {@link formatStaticComponentsRefusal},
+ * different moment: this fires at mutation time so the operator learns a
+ * full build is needed BEFORE the next gate run refuses.
+ */
+export declare function formatPostMutationStaticComponentsWarning(changedManifests: string[]): string;
+/**
+ * Post-mutation advisory used by `fireforge reset` / `fireforge import`:
+ * warns (never throws, never blocks) when `components.conf` now differs
+ * from the last full-build anchor. Silently skipped when no baseline or
+ * anchor exists, or when any probe fails.
+ */
+export declare function warnIfStaticComponentsStale(projectRoot: string, engineDir: string): Promise<void>;

package/dist/src/core/test-stale-check.js

@@ -27,10 +27,11 @@ import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
-import { isPackageablePath } from './build-audit.js';
+import { verbose, warn } from '../utils/logger.js';
+import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
+export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
 /**
@@ -125,7 +126,10 @@ export const FULL_SUITE_REQUEST = '(entire suite)';
  *
  * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
  * everything. A scoped list covers a request path when the request equals a
- * covered entry or sits beneath a covered directory entry. Both sides are
+ * covered entry, sits beneath a covered directory entry, or shares a
+ * manifest granule with a covered entry ({@link toManifestGranule} — a
+ * scoped `test --build` packages the whole manifest directory, so a
+ * same-manifest sibling of a covered file is packaged too). Both sides are
  * normalized to forward slashes so Windows-style CLI input cannot defeat
  * the prefix rule (baseline paths are POSIX by convention). A request with
  * no paths is a full-suite run and is never covered by a scoped list — the
@@ -141,9 +145,29 @@ export function findUncoveredRequestPaths(coverage, requestedPaths) {
     }
     return requestedPaths.filter((requested) => {
         const path = normalizeCoveragePath(requested);
-        return !covered.some((c) => path === c || path.startsWith(`${c}/`));
+        const granule = toManifestGranule(path);
+        return !covered.some((c) => path === c || path.startsWith(`${c}/`) || granule === toManifestGranule(c));
     });
 }
+/**
+ * Maps a normalized request/coverage path to the "manifest granule" the
+ * packaged runtime actually staged: an extension-bearing basename (a test
+ * FILE) maps to its containing directory, a directory (no dot in the
+ * basename) maps to itself. Purely lexical — the directory-as-manifest
+ * approximation holds because xpcshell/mochitest manifests live next to
+ * their test files and a scoped `test --build` stages the whole manifest
+ * directory into `obj-*`/`_tests/`, not single files. Caveat: a DIRECTORY
+ * whose basename contains a dot is misread as a file and mapped to its
+ * parent, which widens (never narrows) the covered granule.
+ */
+function toManifestGranule(path) {
+    const slash = path.lastIndexOf('/');
+    const base = slash === -1 ? path : path.slice(slash + 1);
+    if (!base.includes('.')) {
+        return path;
+    }
+    return slash === -1 ? '' : path.slice(0, slash);
+}
 /** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
 function normalizeCoveragePath(path) {
     return path.trim().replace(/\\/g, '/').replace(/\/+$/, '');
@@ -171,3 +195,89 @@ export function formatTestCoverageRefusal(uncovered, coverage) {
         `rather than fail. ${rebuildHint} ` +
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
+/**
+ * Probes whether any `components.conf` changed since the last FULL
+ * `fireforge build` — i.e. since the compiled StaticComponents table was
+ * last regenerated. `components.conf` entries bake into compiled code; a
+ * scoped `test --build` packages the file but the child process resolves
+ * the OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a
+ * test bug.
+ *
+ * The diff anchors to the baseline's `staticComponentsBaseline` (the last
+ * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`
+ * which a scoped `test --build` advances. Dirty candidates are hash-checked
+ * against the anchor's fingerprints so only genuine content divergence
+ * counts. No baseline / no anchor (pre-0.38.0 marker) → fresh. Never
+ * throws — the probes it composes degrade to verbose lines and empty
+ * results on git failure, matching {@link checkStaleBuildForTest}.
+ */
+export async function checkStaticComponentsStale(engineDir, baseline) {
+    const anchor = baseline?.staticComponentsBaseline;
+    if (baseline === undefined || anchor === undefined) {
+        return { stale: false, changedManifests: [] };
+    }
+    const changed = await collectChangedEnginePaths(engineDir, { ...baseline, engineHeadSha: anchor.engineHeadSha }, 'Static-components preflight');
+    const changedManifests = [];
+    for (const path of changed.filter((p) => isXpcomManifestPath(p))) {
+        const recorded = anchor.fingerprints[path];
+        const live = await hashEngineFile(engineDir, path);
+        if (recorded === undefined || live === undefined || recorded !== live) {
+            changedManifests.push(path);
+        }
+    }
+    return { stale: changedManifests.length > 0, changedManifests };
+}
+/**
+ * Formats the refusal shown when a run would dispatch against a stale
+ * compiled StaticComponents table. Same probe/copy split as
+ * {@link formatStaleBuildWarning} so tests can pin structure and wording
+ * independently.
+ */
+export function formatStaticComponentsRefusal(changedManifests) {
+    const head = changedManifests.slice(0, STALE_PATHS_LIMIT);
+    const truncated = changedManifests.length - head.length;
+    const list = head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    return (`The compiled StaticComponents table is stale: ${list} changed since the last full "fireforge build".\n` +
+        'components.conf registrations are baked into compiled code that only a FULL build ' +
+        'regenerates — a scoped "fireforge test --build" repackages files but the child process ' +
+        'resolves the old component table and fails with NS_ERROR_MALFORMED_URI that reads as a ' +
+        'test bug. Run "fireforge build" first. (--allow-stale-build does not bypass this check — ' +
+        'it accepts stale packaged content, not a stale compiled registration. Pass ' +
+        '--allow-stale-components only if you rebuilt out-of-band and accept the risk.)');
+}
+/**
+ * Formats the post-mutation advisory printed by `fireforge reset` /
+ * `fireforge import` when `components.conf` diverged from the last full
+ * build (FORGE F13). Same probe as {@link formatStaticComponentsRefusal},
+ * different moment: this fires at mutation time so the operator learns a
+ * full build is needed BEFORE the next gate run refuses.
+ */
+export function formatPostMutationStaticComponentsWarning(changedManifests) {
+    const head = changedManifests.slice(0, STALE_PATHS_LIMIT);
+    const truncated = changedManifests.length - head.length;
+    const list = head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    return (`components.conf changed relative to the last full "fireforge build": ${list}.\n` +
+        'The compiled StaticComponents table in obj-* no longer matches the tree, so the next ' +
+        '"fireforge test" will require a full "fireforge build" first — a scoped ' +
+        '"fireforge test --build" cannot regenerate the compiled table.');
+}
+/**
+ * Post-mutation advisory used by `fireforge reset` / `fireforge import`:
+ * warns (never throws, never blocks) when `components.conf` now differs
+ * from the last full-build anchor. Silently skipped when no baseline or
+ * anchor exists, or when any probe fails.
+ */
+export async function warnIfStaticComponentsStale(projectRoot, engineDir) {
+    try {
+        const baseline = await readBuildBaseline(projectRoot);
+        if (baseline === undefined)
+            return;
+        const result = await checkStaticComponentsStale(engineDir, baseline);
+        if (!result.stale)
+            return;
+        warn(formatPostMutationStaticComponentsWarning(result.changedManifests));
+    }
+    catch (error) {
+        verbose(`Static-components post-mutation check skipped: ${toError(error).message}`);
+    }
+}

package/dist/src/core/token-manager.js

@@ -4,14 +4,14 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { warn } from '../utils/logger.js';
+import { info, warn } from '../utils/logger.js';
 import { escapeRegex } from '../utils/regex.js';
 import { validateTokenName } from '../utils/validation.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
 import { addTokenToDocs } from './token-docs.js';
-import { insertVariantDeclaration, validateVariantSelector, variantBlockHasToken, } from './token-variant.js';
+import { insertVariantDeclaration, validateVariantSelector, variantBlockExists, variantBlockHasToken, } from './token-variant.js';
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export function getTokensCssPath(binaryName) {
     return `browser/themes/shared/${binaryName}-tokens.css`;
@@ -389,6 +389,39 @@ function findCategorySection(lines, category, tokensCssPath) {
     }
     return { categoryLine, sectionEnd };
 }
+/**
+ * Explicit theme-attribute selectors the override path keeps in sync with
+ * the `@media (prefers-color-scheme: dark)` block. Consumer scaffolds that
+ * pair the media query with `:root[data-theme="dark"]` /
+ * `:root[data-theme="light"]` blocks (viewer-toggle theming) require every
+ * themed list to declare identical token sets, so an override add that only
+ * wrote the media block was a guaranteed half-finished edit (FORGE F8).
+ */
+const THEME_ATTRIBUTE_VARIANTS = [
+    { variant: '[data-theme="dark"]', pick: 'dark' },
+    { variant: '[data-theme="light"]', pick: 'light' },
+];
+/**
+ * Mirrors an override's light/dark values into existing top-level
+ * `:root[data-theme="dark"]` / `:root[data-theme="light"]` blocks. Blocks
+ * that do not exist are left alone (scaffolded files have none; behavior is
+ * unchanged there). Idempotent per block. Returns the selectors written.
+ */
+function insertThemeAttributeOverrides(lines, options) {
+    if (options.mode !== 'override' || !options.darkValue)
+        return [];
+    const written = [];
+    for (const { variant, pick } of THEME_ATTRIBUTE_VARIANTS) {
+        if (!variantBlockExists(lines, variant))
+            continue;
+        if (variantBlockHasToken(lines, variant, options.tokenName))
+            continue;
+        const value = pick === 'dark' ? options.darkValue : options.value;
+        insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${value};`);
+        written.push(`:root${variant}`);
+    }
+    return written;
+}
 function insertDarkModeOverride(lines, options) {
     if (options.mode !== 'override' || !options.darkValue)
         return;
@@ -451,6 +484,10 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     }
     lines.splice(insertIndex, 0, ...insertLines);
     insertDarkModeOverride(lines, options);
+    const themeBlocksWritten = insertThemeAttributeOverrides(lines, options);
+    if (themeBlocksWritten.length > 0) {
+        info(`Override also written to ${themeBlocksWritten.join(' and ')}.`);
+    }
     content = lines.join('\n');
     await writeText(filePath, content);
     return { added: true, categoryCreated };

package/dist/src/core/token-variant.d.ts

@@ -29,6 +29,13 @@ export type VariantValidation = {
  * @param raw - Raw `--variant` value from the CLI / programmatic caller.
  */
 export declare function validateVariantSelector(raw: unknown): VariantValidation;
+/**
+ * True when a top-level `:root<variant>` block exists in `lines`. Used by
+ * the override path to write theme-attribute blocks only when the scaffold
+ * already declares them — `insertVariantDeclaration` would otherwise create
+ * the block, which is only wanted for the explicit `--variant` flow.
+ */
+export declare function variantBlockExists(lines: string[], variant: string): boolean;
 /** True when the `:root<variant>` block already declares `tokenName`. */
 export declare function variantBlockHasToken(lines: string[], variant: string, tokenName: string): boolean;
 /**