@hominis/fireforge 0.38.0 → 0.40.0

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

@@ -67,3 +67,33 @@ export function resolvePatchOwnedSysMjs(currentNewFiles, patchQueueCtx) {
 export function resolvePatchOwnedChromeScripts(currentNewFiles, patchQueueCtx) {
     return resolveOwned(currentNewFiles, patchQueueCtx, (file) => file.endsWith('.js') && !file.endsWith('.sys.mjs'));
 }
+/**
+ * Test-script predicate for the `checkJsTestFiles` pass (FORGE G5):
+ * plain `.js` files (not `.sys.mjs` modules) that live under a `/test/`
+ * path or carry a `browser_` / `test_` / `xpcshell_` basename. Duplicates
+ * `patch-lint.ts`'s `isTestFile` shape rather than importing it —
+ * patch-lint.ts imports this module, so the reverse edge would create an
+ * import cycle (dpdm gate). The agreement is pinned by
+ * `patch-lint-ownership.test.ts`.
+ */
+export function isTestScriptFile(file) {
+    if (!file.endsWith('.js') || file.endsWith('.sys.mjs'))
+        return false;
+    if (file.includes('/test/'))
+        return true;
+    const basename = file.split('/').pop() ?? '';
+    return /^(?:browser_|test_|xpcshell_).*\.js$/.test(basename);
+}
+/**
+ * Returns the set of patch-owned test `.js` files (FORGE G5). Same
+ * ownership semantics as {@link resolvePatchOwnedSysMjs}; consumed by the
+ * `patchLint.checkJsTestFiles` pass, which checks each as its own small
+ * script-scope program.
+ *
+ * @param currentNewFiles - Files newly created in the current diff
+ * @param patchQueueCtx - Optional cross-patch context for queue-wide ownership
+ * @returns Set of patch-owned test-script file paths
+ */
+export function resolvePatchOwnedTestScripts(currentNewFiles, patchQueueCtx) {
+    return resolveOwned(currentNewFiles, patchQueueCtx, isTestScriptFile);
+}

package/dist/src/core/patch-lint-reexports.d.ts

@@ -2,5 +2,5 @@
  * Public re-exports for {@link ./patch-lint.ts}. Split out so the
  * orchestrator stays within the ESLint `max-lines` budget.
  */
-export { buildPatchQueueContext, collectForwardImportEdges, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, type ForwardImportEdge, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
+export { buildPatchQueueContext, collectForwardImportEdges, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';

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

@@ -128,6 +128,21 @@ export type PatchSizeTierDecision = {
  * defensive-for-tests choice.
  */
 export declare function resolvePatchSizeTier(filesAffected: ReadonlyArray<string>, patchTier?: 'branding'): PatchSizeTierDecision;
+/**
+ * Read-only view of the size thresholds a tier enforces (FORGE G9).
+ * Public-API companion to {@link resolvePatchSizeTier} /
+ * {@link countNonBinaryDiffLines} so consumers can build waiver-freshness
+ * checks against the SAME numbers `large-patch-lines` /
+ * `large-patch-files` fire on instead of mirroring them.
+ */
+export declare function getPatchSizeThresholds(tier: 'general' | 'test' | 'branding'): {
+    lines: {
+        notice: number;
+        warning: number;
+        error: number;
+    };
+    maxFiles: number;
+};
 /**
  * Checks patch size and emits advisory warnings.
  *
@@ -179,6 +194,14 @@ export interface LintExportedPatchOptions {
      * attributes findings per patch instead of rebuilding per patch.
      */
     precomputedCheckJs?: readonly PatchLintIssue[];
+    /**
+     * Invoked with the issues DROPPED by the `ignoreChecks` waiver filter,
+     * when any were (FORGE G10). Suppression semantics are unchanged — the
+     * returned issue list still excludes them — but the caller can report
+     * the measurement a waived size finding carried (per-patch NOTICE lines
+     * and the `--report` JSON) instead of losing it entirely.
+     */
+    onSuppressed?: (suppressed: PatchLintIssue[]) => void;
 }
 /**
  * Runs all patch lint checks and returns combined issues.

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

@@ -3,15 +3,16 @@ import { dirname, join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { stripJsComments } from '../utils/regex.js';
 import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, hasUpstreamMplBlockHeader, } from './license-headers.js';
-import { invokePatchLintCheckJs } from './patch-lint-checkjs.js';
+import { invokePatchLintCheckJs, runCheckJsTestFilesGrouped } from './patch-lint-checkjs.js';
 import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
 import { lintPatchedCss } from './patch-lint-css.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 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';
+import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from './patch-lint-ownership.js';
 // ---------------------------------------------------------------------------
 // Cross-patch lint re-exports
 // ---------------------------------------------------------------------------
@@ -480,6 +481,19 @@ export function resolvePatchSizeTier(filesAffected, patchTier) {
         return { tier: 'branding', source: 'auto' };
     return { tier: 'general' };
 }
+/**
+ * Read-only view of the size thresholds a tier enforces (FORGE G9).
+ * Public-API companion to {@link resolvePatchSizeTier} /
+ * {@link countNonBinaryDiffLines} so consumers can build waiver-freshness
+ * checks against the SAME numbers `large-patch-lines` /
+ * `large-patch-files` fire on instead of mirroring them.
+ */
+export function getPatchSizeThresholds(tier) {
+    return {
+        lines: { ...PATCH_LINE_THRESHOLDS[tier] },
+        maxFiles: PATCH_FILES_THRESHOLDS[tier],
+    };
+}
 /**
  * Checks patch size and emits advisory warnings.
  *
@@ -616,11 +630,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
@@ -633,6 +648,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
@@ -641,6 +657,17 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     }
     else if (config.patchLint?.checkJs) {
         issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir), options?.checkJsReportScope)));
+        // Export-time twin of per-patch lint's test-file pass (FORGE G5), so
+        // export/re-export and `lint --per-patch` agree on the checked surface.
+        if (config.patchLint.checkJsTestFiles === true) {
+            const testGrouped = await runCheckJsTestFilesGrouped(repoDir, resolvePatchOwnedTestScripts(newFiles, patchQueueCtx), config.patchLint, dirname(repoDir));
+            issues.push(...testGrouped.global);
+            for (const [rel, list] of testGrouped.byFile) {
+                if (options?.checkJsReportScope && !options.checkJsReportScope.has(rel))
+                    continue;
+                issues.push(...list);
+            }
+        }
     }
     // Filter out ignored checks last so every rule still runs (keeps the
     // implementation uniform) but suppressed rules do not surface. We do not
@@ -648,6 +675,10 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     // inline `fireforge-ignore: <check>` markers work in the CSS and
     // forward-import rules.
     if (ignoreChecks && ignoreChecks.size > 0) {
+        const suppressed = issues.filter((issue) => ignoreChecks.has(issue.check));
+        if (suppressed.length > 0) {
+            options?.onSuppressed?.(suppressed);
+        }
         return issues.filter((issue) => !ignoreChecks.has(issue.check));
     }
     return issues;

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

@@ -5,7 +5,7 @@
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
-export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchManifestRowMutation, type PatchManifestRowMutationResult, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
+export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';
 export { validatePatchesManifest } from './patch-manifest-validate.js';

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/smoke-patterns.d.ts

@@ -22,24 +22,40 @@ export declare const SMOKE_ERROR_PATTERNS: readonly RegExp[];
 /**
  * Returns `true` when `line` matches any pattern in
  * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
- * lives in {@link matchesAllowlist}, so the smoke runner can count
+ * lives in {@link matchAllowlist}, so the smoke runner can count
  * allowlisted hits separately from raw error matches for its summary.
  */
 export declare function matchesSmokeError(line: string): boolean;
 /**
- * Returns `true` when `line` matches any regex in `allow`. Safe to call
- * with an empty allowlist (always returns `false`).
+ * One compiled allowlist entry with its provenance retained so the smoke
+ * summary can attribute hits per entry (FORGE G8) — an entry that silently
+ * stops matching (its suppressed shape changed upstream) is only
+ * detectable when zero-hit entries are visible.
  */
-export declare function matchesAllowlist(line: string, allow: readonly RegExp[]): boolean;
+export interface CompiledAllowlistEntry {
+    pattern: RegExp;
+    /** Verbatim source text of the entry. */
+    source: string;
+    /** Human-readable origin: `allow.txt:12` or `--console-allow #2`. */
+    origin: string;
+}
+/**
+ * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
+ * First-match attribution is deterministic and cheap; a line matching
+ * several entries credits the earliest one. Safe to call with an empty
+ * allowlist (always returns -1).
+ */
+export declare function matchAllowlist(line: string, allow: readonly CompiledAllowlistEntry[]): number;
 /**
  * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
  * lines and `#`-prefixed comments are skipped. Each remaining line is
- * compiled as a RegExp. A bad pattern throws immediately — better to fail
- * fast at CLI parse time than to silently let a typo match nothing.
+ * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
+ * pattern throws immediately — better to fail fast at CLI parse time than
+ * to silently let a typo match nothing.
  */
-export declare function compileAllowlistFromFile(body: string, sourcePath: string): RegExp[];
+export declare function compileAllowlistFromFile(body: string, sourcePath: string): CompiledAllowlistEntry[];
 /**
  * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
  * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.
  */
-export declare function compileAllowlistFromStrings(sources: readonly string[]): RegExp[];
+export declare function compileAllowlistFromStrings(sources: readonly string[]): CompiledAllowlistEntry[];

package/dist/src/core/smoke-patterns.js

@@ -32,7 +32,7 @@ export const SMOKE_ERROR_PATTERNS = [
 /**
  * Returns `true` when `line` matches any pattern in
  * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
- * lives in {@link matchesAllowlist}, so the smoke runner can count
+ * lives in {@link matchAllowlist}, so the smoke runner can count
  * allowlisted hits separately from raw error matches for its summary.
  */
 export function matchesSmokeError(line) {
@@ -44,22 +44,25 @@ export function matchesSmokeError(line) {
     return false;
 }
 /**
- * Returns `true` when `line` matches any regex in `allow`. Safe to call
- * with an empty allowlist (always returns `false`).
+ * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
+ * First-match attribution is deterministic and cheap; a line matching
+ * several entries credits the earliest one. Safe to call with an empty
+ * allowlist (always returns -1).
  */
-export function matchesAllowlist(line, allow) {
-    for (const pattern of allow) {
-        if (pattern.test(line)) {
-            return true;
+export function matchAllowlist(line, allow) {
+    for (let i = 0; i < allow.length; i++) {
+        if (allow[i]?.pattern.test(line)) {
+            return i;
         }
     }
-    return false;
+    return -1;
 }
 /**
  * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
  * lines and `#`-prefixed comments are skipped. Each remaining line is
- * compiled as a RegExp. A bad pattern throws immediately — better to fail
- * fast at CLI parse time than to silently let a typo match nothing.
+ * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
+ * pattern throws immediately — better to fail fast at CLI parse time than
+ * to silently let a typo match nothing.
  */
 export function compileAllowlistFromFile(body, sourcePath) {
     const lines = body.split(/\r?\n/);
@@ -69,7 +72,11 @@ export function compileAllowlistFromFile(body, sourcePath) {
         if (!line || line.startsWith('#'))
             return;
         try {
-            compiled.push(new RegExp(line));
+            compiled.push({
+                pattern: new RegExp(line),
+                source: line,
+                origin: `${sourcePath}:${String(index + 1)}`,
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -88,7 +95,11 @@ export function compileAllowlistFromStrings(sources) {
     const compiled = [];
     sources.forEach((source, index) => {
         try {
-            compiled.push(new RegExp(source));
+            compiled.push({
+                pattern: new RegExp(source),
+                source,
+                origin: `--console-allow #${String(index + 1)}`,
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

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

@@ -49,6 +49,14 @@ export interface ClassifiedFile extends StatusFile {
      * single claim is fully captured by the classification itself.
      */
     claimedBy?: string[];
+    /**
+     * Owning patch filename when exactly one patch claims this path
+     * (patch-backed, patch-owned-drift, and single-owner furnace entries).
+     * Unset for unowned, branding-generated, unowned-furnace, and conflict
+     * entries — conflicts carry `claimedBy` instead. Exposed through
+     * `status --json` as the `patch` field (FORGE G11).
+     */
+    owner?: string;
 }
 /**
  * Builds the file → owning-patch-filenames multimap from manifest rows.
@@ -66,6 +74,14 @@ export declare function buildPatchClaims(manifestPatches: ReadonlyArray<{
  * Single source of truth — status-output.ts renders from the same logic.
  */
 export declare function getPrimaryStatusCode(status: string): string;
+/**
+ * True for the branding paths whose content FireForge generates itself
+ * (configure.sh, brand.properties/ftl, browser/moz.configure). Unlike the
+ * broader branding-root test, a brand-new unowned file under the branding
+ * directory is NOT generated — it is a patch candidate and must stay
+ * visible as unmanaged (the Assets.car precedent).
+ */
+export declare function isGeneratedBrandingPath(file: string, binaryName: string): boolean;
 /**
  * Classifies files into patch-backed, unmanaged, branding, furnace, or
  * conflict buckets.

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

@@ -47,7 +47,14 @@ export function getPrimaryStatusCode(status) {
     }
     return status;
 }
-function isGeneratedBrandingPath(file, binaryName) {
+/**
+ * True for the branding paths whose content FireForge generates itself
+ * (configure.sh, brand.properties/ftl, browser/moz.configure). Unlike the
+ * broader branding-root test, a brand-new unowned file under the branding
+ * directory is NOT generated — it is a patch candidate and must stay
+ * visible as unmanaged (the Assets.car precedent).
+ */
+export function isGeneratedBrandingPath(file, binaryName) {
     const normalized = file.replace(/\\/g, '/');
     const brandingRoot = `browser/branding/${binaryName}`;
     return (normalized === 'browser/moz.configure' ||
@@ -64,13 +71,14 @@ function isGeneratedBrandingPath(file, binaryName) {
  * deletion the patch does not expect, or a failed comparison) reports
  * `patch-owned-drift`.
  */
-async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassification) {
+async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassification, owner) {
     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',
+            owner,
         };
     }
     // File exists on disk — compare actual vs expected
@@ -82,11 +90,12 @@ async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassi
         return {
             ...entry,
             classification: actual === expected ? matchClassification : 'patch-owned-drift',
+            owner,
         };
     }
     catch (error) {
         verbose(`Treating ${entry.file} as patch-owned drift because patch-backed classification failed: ${toError(error).message}`);
-        return { ...entry, classification: 'patch-owned-drift' };
+        return { ...entry, classification: 'patch-owned-drift', owner };
     }
 }
 /**
@@ -146,8 +155,8 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
                 // `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'));
+                if (owners && owners.length === 1 && owners[0] !== undefined) {
+                    results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'furnace', owners[0]));
                 }
                 else {
                     results.push({ ...entry, classification: 'furnace' });
@@ -174,7 +183,12 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
             continue;
         }
         // File is claimed by exactly one patch — compare content.
-        results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'patch-backed'));
+        const owner = owners[0];
+        if (owner === undefined) {
+            results.push({ ...entry, classification: 'unmanaged' });
+            continue;
+        }
+        results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'patch-backed', owner));
     }
     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

@@ -108,3 +108,18 @@ export declare function checkStaticComponentsStale(engineDir: string, baseline:
  * 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,7 +27,7 @@ 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 { 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';
@@ -245,3 +245,39 @@ export function formatStaticComponentsRefusal(changedManifests) {
         '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-category.d.ts

@@ -0,0 +1,40 @@
+/**
+ * True when `lines` contain a category header (single-line or multi-line
+ * banner shape) whose name EQUALS `category`. Shared by the pre-add
+ * assertion, the banner creation path, and the section finder so all
+ * agree on what "exists" means.
+ */
+export declare function categoryHeaderExists(lines: string[], category: string): boolean;
+/**
+ * Asserts the category banner exists (or that creation was requested).
+ * Throws a GeneralError naming the available categories and the
+ * `--create-category` remedy otherwise.
+ */
+export declare function assertTokenCategoryExists(engineDir: string, tokensCssPath: string, category: string, createCategory?: boolean): Promise<void>;
+/**
+ * Splices a new single-line category banner ("= Name =" comment shape, the
+ * same format `discoverCategoryHeaders` recognises) just before the closing
+ * brace of the `:root` block, making the new category the last section.
+ * Mutates `lines` in place.
+ */
+export declare function declareCategoryBanner(lines: string[], category: string, tokensCssPath: string): void;
+/** Locates and bounds the named category section. Throws when absent. */
+export declare function findCategorySection(lines: string[], category: string, tokensCssPath: string): {
+    categoryLine: number;
+    sectionEnd: number;
+};
+/** Location of an existing base-`:root` token declaration. */
+export interface TokenDeclarationLocation {
+    /** 1-based line number in the tokens CSS file. */
+    line: number;
+    /** Nearest enclosing category banner name, when one precedes the declaration. */
+    category?: string;
+}
+/**
+ * Finds an existing declaration of `tokenName` inside the base `:root`
+ * block. Dark `@media` and `:root[variant]` companion blocks are
+ * deliberately excluded — they mirror the base declaration, they do not
+ * own the token. Comment content never matches, and the name match is
+ * exact (`--foo-bar` does not match `--x-foo-bar`).
+ */
+export declare function findTokenDeclarationInRoot(lines: string[], tokenName: string): TokenDeclarationLocation | undefined;