@hominis/fireforge 0.16.0 → 0.16.1

package/dist/src/commands/wire.js

@@ -10,7 +10,7 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
-import { isContainedRelativePath, isPathInsideRoot, toRootRelativePath } from '../utils/paths.js';
+import { isContainedRelativePath, isExplicitAbsolutePath, isPathInsideRoot, stripEnginePrefix, toRootRelativePath, } from '../utils/paths.js';
 const BROWSER_BASE_DIR = 'browser/base';
 function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPath, options) {
     info('[dry-run] Would wire subscript:');
@@ -113,25 +113,51 @@ export async function wireCommand(projectRoot, name, options = {}) {
         }
         subscriptDir = options.subscriptDir;
     }
-    // Validate DOM fragment file exists and compute path relative to engine root
+    // Validate DOM fragment file exists and compute path relative to engine root.
+    //
+    // Accepts three shapes:
+    //  - Absolute paths (`/project/engine/browser/base/content/foo.inc.xhtml`)
+    //  - Repo-root-relative forms (`engine/browser/base/content/foo.inc.xhtml`)
+    //  - Engine-relative forms (`browser/base/content/foo.inc.xhtml`)
+    //
+    // Before the engine-prefix normalization, passing an `engine/…`-prefixed
+    // relative path from the repo root double-rooted through
+    // `toRootRelativePath(engineDir, …)` — `resolve(engineDir, 'engine/…')`
+    // landed at `engineDir/engine/…`, which is still "inside" engineDir but
+    // named as a second-level `engine/…` entry. The computed `#include`
+    // then read `../../../engine/browser/base/content/foo.inc.xhtml`,
+    // packaging-breaking nonsense. For absolute inputs this pre-existing
+    // contract was fine — `toRootRelativePath` handles absolute candidates
+    // correctly — so we only strip the prefix when the input is relative.
     let domFilePath;
     if (options.dom) {
         const paths = getProjectPaths(projectRoot);
-        if (!(await pathExists(options.dom))) {
+        const domCandidate = isExplicitAbsolutePath(options.dom)
+            ? options.dom
+            : stripEnginePrefix(options.dom);
+        if (!(await pathExists(domCandidate))) {
             throw new InvalidArgumentError(`DOM fragment file not found: ${options.dom}`, 'dom');
         }
-        if (!isPathInsideRoot(paths.engine, options.dom)) {
+        if (!isPathInsideRoot(paths.engine, domCandidate)) {
             throw new InvalidArgumentError(`DOM fragment file must stay within engine/: ${options.dom}`, 'dom');
         }
-        domFilePath = toRootRelativePath(paths.engine, options.dom);
+        domFilePath = toRootRelativePath(paths.engine, domCandidate);
     }
     // Resolve the chrome document the `#include` directive will land in.
     // Only consulted when `--dom` is supplied — we still resolve it here so
     // the dry-run plan can print the target accurately.
-    if (options.target !== undefined && !isContainedRelativePath(options.target)) {
-        throw new InvalidArgumentError(`Target chrome document must stay within engine/: ${options.target}`, 'target');
-    }
-    const domTargetPath = await resolveDomTargetPath(projectRoot, options.target);
+    //
+    // `stripEnginePrefix` is applied so `--target engine/browser/base/browser.xhtml`
+    // and `--target browser/base/browser.xhtml` are treated identically,
+    // matching the `--dom` normalization above. Absolute `--target` paths
+    // stay absolute (the containment check downstream rejects them).
+    const normalizedTarget = options.target !== undefined && !isExplicitAbsolutePath(options.target)
+        ? stripEnginePrefix(options.target)
+        : options.target;
+    if (normalizedTarget !== undefined && !isContainedRelativePath(normalizedTarget)) {
+        throw new InvalidArgumentError(`Target chrome document must stay within engine/: ${options.target ?? ''}`, 'target');
+    }
+    const domTargetPath = await resolveDomTargetPath(projectRoot, normalizedTarget);
     if (domFilePath) {
         const paths = getProjectPaths(projectRoot);
         if (!options.dryRun && !(await pathExists(join(paths.engine, domTargetPath)))) {

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

@@ -31,6 +31,20 @@ export interface BuildBaseline {
      * the project has since been renamed.
      */
     binaryName: string;
+    /**
+     * Content hash per packageable engine path that was dirty at build
+     * time (modified-against-HEAD or untracked). Used by
+     * `checkStaleBuildForTest` to distinguish "this file's content was
+     * already in `dist/` when the build completed" from "this file has
+     * been edited since". Missing on baselines written before 0.16.0; the
+     * stale-check falls back to the path-only comparison in that case,
+     * so older baselines retain their existing behavior.
+     *
+     * Keys are engine-relative POSIX paths. Values are hex-encoded
+     * SHA-256 digests of the file contents at the moment the baseline
+     * was recorded.
+     */
+    packageableFingerprints?: Record<string, string>;
 }
 /** Name of the last-build marker file under `.fireforge/`. */
 export declare const BUILD_BASELINE_FILENAME = "last-build.json";

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

@@ -16,10 +16,17 @@
  * on successful build completion; a failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { isPackageablePath } from './build-audit.js';
 import { FIREFORGE_DIR } from './config-paths.js';
-import { getHead, isMissingHeadError } from './git.js';
+import { getHead, hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
 /** Name of the last-build marker file under `.fireforge/`. */
 export const BUILD_BASELINE_FILENAME = 'last-build.json';
 /**
@@ -73,11 +80,64 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
             throw error;
         }
     }
+    const packageableFingerprints = await collectPackageableFingerprints(engineDir);
     const baseline = {
         engineHeadSha,
         builtAt: new Date().toISOString(),
         binaryName,
+        ...(packageableFingerprints !== undefined ? { packageableFingerprints } : {}),
     };
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }
+/**
+ * Reads the current engine workdir and computes a SHA-256 fingerprint
+ * for every packageable path that is either modified against HEAD or
+ * untracked. The stale-build preflight (`checkStaleBuildForTest`)
+ * compares the live fingerprint for each packageable-dirty file to
+ * the baseline's entry — paths where the hash matches are "the build
+ * already saw this exact content", paths where it differs (or that
+ * are new since the baseline) are genuinely stale.
+ *
+ * Returns `undefined` on any git failure so a broken probe never
+ * corrupts the on-disk baseline with `{}`; the stale-check then falls
+ * back to the pre-0.16.0 "path-only" behavior on the next test run.
+ */
+async function collectPackageableFingerprints(engineDir) {
+    try {
+        const dirtyPaths = new Set();
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    dirtyPaths.add(trimmed);
+            }
+            for (const untracked of await getUntrackedFiles(engineDir)) {
+                dirtyPaths.add(untracked);
+            }
+        }
+        const packageable = [...dirtyPaths].filter(isPackageablePath);
+        if (packageable.length === 0) {
+            return {};
+        }
+        const fingerprints = {};
+        for (const relPath of packageable) {
+            try {
+                const buffer = await readFile(join(engineDir, relPath));
+                fingerprints[relPath] = createHash('sha256').update(buffer).digest('hex');
+            }
+            catch (fileError) {
+                // A file that disappeared between status probe and hash is
+                // expected in concurrent scenarios; skip it without failing the
+                // whole baseline write.
+                verbose(`Build baseline: skipping fingerprint for ${relPath} — ${toError(fileError).message}`);
+            }
+        }
+        return fingerprints;
+    }
+    catch (error) {
+        verbose(`Build baseline: packageable fingerprint probe failed — ${toError(error).message}`);
+        return undefined;
+    }
+}
 //# sourceMappingURL=build-baseline.js.map

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

@@ -12,4 +12,4 @@ import type { FireForgeConfig } from '../types/config.js';
  * @returns The mutated config
  */
 export declare function mutateConfig(config: FireForgeConfig, key: string, value: unknown, skipValidation?: false): FireForgeConfig;
-export declare function mutateConfig(config: FireForgeConfig, key: string, value: unknown, skipValidation: true): Record<string, unknown>;
+export declare function mutateConfig(config: FireForgeConfig | Record<string, unknown>, key: string, value: unknown, skipValidation: true): Record<string, unknown>;

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

@@ -25,6 +25,23 @@ export declare function configExists(root: string): Promise<boolean>;
  * @throws Error if config doesn't exist or is invalid
  */
 export declare function loadConfig(root: string): Promise<FireForgeConfig>;
+/**
+ * Reads the raw `fireforge.json` document without running it through
+ * {@link validateConfig}. Returns every persisted key — including keys
+ * written via `fireforge config <key> --force` that `validateConfig`
+ * would strip from the typed result.
+ *
+ * Callers that need the validated, typed shape must still use
+ * {@link loadConfig}; this helper exists specifically for the `config`
+ * read path so `fireforge config <key>` can surface keys the write path
+ * accepted under `--force`.
+ *
+ * @param root - Root directory of the project
+ * @returns Raw config object as persisted on disk
+ * @throws ConfigNotFoundError when fireforge.json is missing
+ * @throws ConfigError when the file is not valid JSON
+ */
+export declare function loadRawConfigDocument(root: string): Promise<Record<string, unknown>>;
 /**
  * Writes a configuration to fireforge.json.
  * @param root - Root directory of the project

package/dist/src/core/config.js

@@ -50,6 +50,41 @@ export async function loadConfig(root) {
         throw new ConfigError(`Invalid fireforge.json at ${paths.config}: ${toError(error).message}`);
     }
 }
+/**
+ * Reads the raw `fireforge.json` document without running it through
+ * {@link validateConfig}. Returns every persisted key — including keys
+ * written via `fireforge config <key> --force` that `validateConfig`
+ * would strip from the typed result.
+ *
+ * Callers that need the validated, typed shape must still use
+ * {@link loadConfig}; this helper exists specifically for the `config`
+ * read path so `fireforge config <key>` can surface keys the write path
+ * accepted under `--force`.
+ *
+ * @param root - Root directory of the project
+ * @returns Raw config object as persisted on disk
+ * @throws ConfigNotFoundError when fireforge.json is missing
+ * @throws ConfigError when the file is not valid JSON
+ */
+export async function loadRawConfigDocument(root) {
+    const paths = getProjectPaths(root);
+    if (!(await pathExists(paths.config))) {
+        throw new ConfigNotFoundError(paths.config);
+    }
+    try {
+        const data = await readJson(paths.config);
+        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+            throw new ConfigError(`Invalid fireforge.json at ${paths.config}: expected an object`);
+        }
+        return data;
+    }
+    catch (error) {
+        if (error instanceof ConfigError || error instanceof ConfigNotFoundError) {
+            throw error;
+        }
+        throw new ConfigError(`Invalid fireforge.json at ${paths.config}: ${toError(error).message}`);
+    }
+}
 /**
  * Writes a configuration to fireforge.json.
  * @param root - Root directory of the project

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

@@ -23,12 +23,26 @@ export declare function getDownloadUrl(version: string, product?: FirefoxProduct
  * @returns Tarball filename
  */
 export declare function getTarballFilename(version: string, product?: FirefoxProduct): string;
+/**
+ * Lifecycle phase reported by {@link downloadFirefoxSource}. The download
+ * CLI command uses this to swap spinners between the bytes-on-the-wire
+ * phase and the silent tar-xz decompression phase that follows — before
+ * this, a single spinner stuck at "Downloading Firefox … 100%" covered
+ * both phases, making the first-run setup look hung precisely when the
+ * archive was already on disk and `tar` was the long pole.
+ */
+export type FirefoxSourcePhase = 'download' | 'extract';
+/** Callback fired at phase transitions during {@link downloadFirefoxSource}. */
+export type FirefoxSourcePhaseCallback = (phase: FirefoxSourcePhase) => void;
 /**
  * Downloads and extracts Firefox source.
  * @param version - Firefox version to download
  * @param product - Firefox product type
  * @param destDir - Destination directory for extracted source
  * @param cacheDir - Directory to store downloaded tarball
- * @param onProgress - Optional progress callback
+ * @param onProgress - Optional progress callback for the download byte stream
+ * @param onPhase - Optional callback fired when the function transitions
+ *   between phases (`'download'` → `'extract'`). Fires exactly once per
+ *   phase even if the cached archive path skips the wire entirely.
  */
-export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback): Promise<void>;
+export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback, onPhase?: FirefoxSourcePhaseCallback): Promise<void>;

package/dist/src/core/firefox.js

@@ -39,16 +39,21 @@ export function getTarballFilename(version, product = 'firefox') {
  * @param product - Firefox product type
  * @param destDir - Destination directory for extracted source
  * @param cacheDir - Directory to store downloaded tarball
- * @param onProgress - Optional progress callback
+ * @param onProgress - Optional progress callback for the download byte stream
+ * @param onPhase - Optional callback fired when the function transitions
+ *   between phases (`'download'` → `'extract'`). Fires exactly once per
+ *   phase even if the cached archive path skips the wire entirely.
  */
-export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress) {
+export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress, onPhase) {
     const archive = resolveArchive(version, product);
     const tarballPath = join(cacheDir, archive.filename);
     // Ensure cache directory exists
     await ensureDir(cacheDir);
+    onPhase?.('download');
     await ensureCachedArchive(archive, cacheDir, onProgress);
     // Extract to a unique temporary directory so concurrent downloads for
     // the same destination do not clobber each other.
+    onPhase?.('extract');
     const tempDir = `${destDir}.tmp-${randomUUID()}`;
     try {
         await extractTarXz(tarballPath, tempDir);

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

@@ -86,6 +86,29 @@ export declare function loadFurnaceConfig(root: string): Promise<FurnaceConfig>;
  * @param config - Configuration to write
  */
 export declare function writeFurnaceConfig(root: string, config: FurnaceConfig): Promise<void>;
+/**
+ * Stamps every override's `baseVersion` to the supplied version. Used by
+ * `fireforge rebase` after a successful patch re-export so a successful
+ * ESR bump does not leave Furnace overrides in a doctor-failing drift
+ * state. Returns the number of overrides stamped (zero if furnace.json
+ * has no overrides, or if the file is missing).
+ *
+ * Motivating case: a 140.9.0esr → 140.9.1esr rebase stamps patch
+ * `sourceEsrVersion` via `stampPatchVersions`, but before 0.16.0 no
+ * equivalent stamping ran for Furnace override `baseVersion`. `doctor`
+ * then immediately failed Furnace component validation on every
+ * override. The stamp is deliberately unconditional — `fireforge
+ * furnace validate` is the right tool for "does this override still
+ * apply", and rebase already attested that the patch layer re-validated
+ * against the new ESR; the per-override health check belongs in a
+ * separate pass, not inline with the stamp.
+ *
+ * @param root - Root directory of the project
+ * @param version - Firefox version string to stamp onto every override
+ * @returns Number of overrides whose `baseVersion` was updated (either
+ *   because it was missing or because it differed from `version`).
+ */
+export declare function stampFurnaceOverrideBaseVersions(root: string, version: string): Promise<number>;
 /**
  * Creates a default furnace configuration.
  * @returns A valid empty FurnaceConfig

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

@@ -420,6 +420,44 @@ export async function writeFurnaceConfig(root, config) {
     const paths = getFurnacePaths(root);
     await writeJson(paths.furnaceConfig, config);
 }
+/**
+ * Stamps every override's `baseVersion` to the supplied version. Used by
+ * `fireforge rebase` after a successful patch re-export so a successful
+ * ESR bump does not leave Furnace overrides in a doctor-failing drift
+ * state. Returns the number of overrides stamped (zero if furnace.json
+ * has no overrides, or if the file is missing).
+ *
+ * Motivating case: a 140.9.0esr → 140.9.1esr rebase stamps patch
+ * `sourceEsrVersion` via `stampPatchVersions`, but before 0.16.0 no
+ * equivalent stamping ran for Furnace override `baseVersion`. `doctor`
+ * then immediately failed Furnace component validation on every
+ * override. The stamp is deliberately unconditional — `fireforge
+ * furnace validate` is the right tool for "does this override still
+ * apply", and rebase already attested that the patch layer re-validated
+ * against the new ESR; the per-override health check belongs in a
+ * separate pass, not inline with the stamp.
+ *
+ * @param root - Root directory of the project
+ * @param version - Firefox version string to stamp onto every override
+ * @returns Number of overrides whose `baseVersion` was updated (either
+ *   because it was missing or because it differed from `version`).
+ */
+export async function stampFurnaceOverrideBaseVersions(root, version) {
+    if (!(await furnaceConfigExists(root)))
+        return 0;
+    const config = await loadFurnaceConfig(root);
+    let changed = 0;
+    for (const override of Object.values(config.overrides)) {
+        if (override.baseVersion !== version) {
+            override.baseVersion = version;
+            changed++;
+        }
+    }
+    if (changed > 0) {
+        await writeFurnaceConfig(root, config);
+    }
+    return changed;
+}
 /**
  * Creates a default furnace configuration.
  * @returns A valid empty FurnaceConfig

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

@@ -34,6 +34,29 @@ export const MACH_ERROR_HINTS = [
             'after a build that failed late. Re-run "fireforge build" to completion, confirm the app ' +
             'bundle exists under `obj-*/dist/`, and rerun "fireforge package".',
     },
+    {
+        // Upstream bindgen on some macOS libc++ SDK versions emits
+        // `pub type basic_string___self_view = root::std::__1::basic_string_view<_CharT>;`
+        // inside gecko-profiler's generated `bindings.rs`, but `_CharT` is
+        // not in scope where the alias lands — so the Rust compile fails
+        // with "cannot find type `_CharT`". The symptom is obscure and the
+        // fix is external: Hominis ships
+        // `990-infra-bindgen-basic-string-workaround.patch` in its patch
+        // queue, which strips the offending alias line post-generation.
+        // This hint surfaces the workaround pointer alongside the raw
+        // bindgen output so operators don't have to reverse-engineer the
+        // failure.
+        pattern: /cannot find type `_CharT` in this scope[\s\S]*?gecko-profiler-|gecko-profiler-[\s\S]*?cannot find type `_CharT` in this scope/,
+        hint: 'The Rust compile failed on a bindgen-generated `basic_string___self_view` alias in ' +
+            'gecko-profiler/bindings.rs. This is an upstream bindgen output bug against some ' +
+            'macOS libc++ SDK versions and needs a post-generation patch to strip the alias. ' +
+            'The known-working workaround is the `990-infra-bindgen-basic-string-workaround.patch` ' +
+            "Hominis ships in its patch queue — import the equivalent into your fork's patches/, " +
+            'then re-run "fireforge import" + "fireforge build". If you do not use Hominis\' queue, ' +
+            'apply the following post-process to the generated file before the Rust compile: ' +
+            'remove any `pub type basic_string___self_view = …<_CharT>;` line from ' +
+            '`<objdir>/release/build/gecko-profiler-*/out/gecko/bindings.rs`.',
+    },
 ];
 /**
  * Scans captured stderr for known mach errors and returns matching hints.

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

@@ -159,6 +159,17 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
         // Check for non-tokenized custom properties. A variable that is both
         // declared and consumed inside the same file is auto-exempted as a
         // runtime state channel (see furnace.json → runtimeVariables).
+        //
+        // When diff context is available, scope the `var(...)` scan to
+        // added/modified lines only. `cssContent` (full-file) is still the
+        // source of `localDeclarations` so vars declared anywhere in the file
+        // are recognised as same-file refs regardless of where the consuming
+        // `var(...)` appears. Before this scoping change, a small edit to a
+        // Furnace override of a stock component (e.g. moz-card) produced a
+        // `token-prefix-violation` for every stock `var(--moz-card-*)` the
+        // upstream file already carried, because the scanner saw the full
+        // applied file and flagged each inherited reference as if the fork
+        // had introduced it.
         if (tokenPrefix) {
             const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
             const localDeclarations = new Set();
@@ -168,26 +179,38 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
                 if (name)
                     localDeclarations.add(name);
             }
-            const varPattern = /var\(\s*(--[\w-]+)/g;
-            let match;
-            while ((match = varPattern.exec(cssContent)) !== null) {
-                const prop = match[1];
-                if (!prop)
-                    continue;
-                if (prop.startsWith(tokenPrefix))
-                    continue;
-                if (tokenAllowlist?.has(prop))
-                    continue;
-                if (runtimeVariables?.has(prop))
-                    continue;
-                if (localDeclarations.has(prop))
-                    continue;
-                issues.push({
-                    file,
-                    check: 'token-prefix-violation',
-                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
-                    severity: 'error',
-                });
+            const prefixScanSource = addedLinesByFile
+                ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
+                : cssContent;
+            if (prefixScanSource.length > 0) {
+                const varPattern = /var\(\s*(--[\w-]+)/g;
+                const flaggedProps = new Set();
+                let match;
+                while ((match = varPattern.exec(prefixScanSource)) !== null) {
+                    const prop = match[1];
+                    if (!prop)
+                        continue;
+                    if (prop.startsWith(tokenPrefix))
+                        continue;
+                    if (tokenAllowlist?.has(prop))
+                        continue;
+                    if (runtimeVariables?.has(prop))
+                        continue;
+                    if (localDeclarations.has(prop))
+                        continue;
+                    // De-duplicate per (file, prop) pair so the same introduced var
+                    // used five times in the added hunk doesn't produce five
+                    // identical issue entries.
+                    if (flaggedProps.has(prop))
+                        continue;
+                    flaggedProps.add(prop);
+                    issues.push({
+                        file,
+                        check: 'token-prefix-violation',
+                        message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
+                        severity: 'error',
+                    });
+                }
             }
         }
     }

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

@@ -23,6 +23,9 @@
  * plugin, etc.) can legitimately have a fresh `dist/` with no
  * FireForge-recorded baseline update.
  */
+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';
@@ -90,7 +93,32 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
         return { stale: false, changedPaths: [], truncated: 0, baseline: undefined };
     }
     const changed = await collectChangedEnginePaths(engineDir, baseline);
-    const packageable = changed.filter((path) => isPackageablePath(path)).sort();
+    let packageable = changed.filter((path) => isPackageablePath(path)).sort();
+    // Content-hash comparison: when the baseline carries a fingerprint set,
+    // fold each candidate path through a live re-hash and drop paths whose
+    // current content matches the baseline. Pre-0.16.0 baselines have no
+    // `packageableFingerprints` field; those fall through and the
+    // path-only comparison behaves as before (every workdir-dirty
+    // packageable path is reported as stale). The concrete motivating
+    // case: a project with imported patches + Furnace-applied components
+    // always has a persistent workdir diff against HEAD. Before the
+    // fingerprint layer, `git diff --name-only HEAD` returned that diff
+    // on every build, so the stale check fired immediately after a
+    // successful build even though nothing had actually changed. The
+    // fingerprints capture "these files had this content when the build
+    // ran"; a path stays stale only when its live hash diverges.
+    const fingerprints = baseline.packageableFingerprints;
+    if (fingerprints) {
+        const staleAfterHashCheck = [];
+        for (const path of packageable) {
+            const recorded = fingerprints[path];
+            const live = await hashEngineFile(engineDir, path);
+            if (recorded === undefined || live === undefined || recorded !== live) {
+                staleAfterHashCheck.push(path);
+            }
+        }
+        packageable = staleAfterHashCheck;
+    }
     if (packageable.length === 0) {
         return { stale: false, changedPaths: [], truncated: 0, baseline };
     }
@@ -98,6 +126,23 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     const truncated = Math.max(0, packageable.length - head.length);
     return { stale: true, changedPaths: head, truncated, baseline };
 }
+/**
+ * Reads a file under the engine directory and returns a hex-encoded
+ * SHA-256 of its contents, matching the hash the baseline writer
+ * produces. Returns `undefined` on any IO error (missing file,
+ * permission denied, etc.) so the caller can treat the path as still
+ * stale rather than crashing the preflight.
+ */
+async function hashEngineFile(engineDir, relPath) {
+    try {
+        const buffer = await readFile(join(engineDir, relPath));
+        return createHash('sha256').update(buffer).digest('hex');
+    }
+    catch (error) {
+        verbose(`Stale-build preflight: could not hash ${relPath} for baseline comparison — ${toError(error).message}`);
+        return undefined;
+    }
+}
 /**
  * Formats a human-readable warning body from a {@link StaleBuildResult}.
  * Kept separate from the probe so test code can assert on the structured

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

@@ -93,8 +93,56 @@ async function assertTokenCategoryExists(engineDir, tokensCssPath, category) {
             }
         }
     }
-    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}. ` +
-        'Available categories are defined by /* =... category ...= */ comment headers.');
+    const discoveredCategories = discoverCategoryHeaders(lines);
+    const available = discoveredCategories.length > 0
+        ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
+        : 'The file currently has no category headers. Add one by hand near the top of the :root { … } block — the format is "/* = My Category = */" — or run "fireforge furnace init --force" to re-scaffold the default seed set.';
+    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
+        `${available}\n\n` +
+        'Categories are declared by comment headers. Single-line shape: /* = My Category = */. ' +
+        'Multi-line shape: /* =============\\n * My Category\\n * ============= */.');
+}
+/**
+ * Scans a tokens CSS file for category header comments and returns the
+ * category names in document order. Used to enrich the "category not
+ * found" error body with concrete alternatives the operator can copy.
+ *
+ * Mirrors the shapes `findCategorySection` already recognises:
+ * - Single-line: `/* = Foo = *\/`
+ * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
+ *   closing `*\/`.
+ *
+ * This helper exists as a pure inspector; it never throws on malformed
+ * headers and silently skips shapes it cannot parse.
+ */
+function discoverCategoryHeaders(lines) {
+    const categories = new Set();
+    const singleLinePattern = /\/\*\s*=+\s*(.+?)\s*=+\s*\*\//;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const singleMatch = singleLinePattern.exec(line);
+        if (singleMatch?.[1]) {
+            const extracted = singleMatch[1].trim();
+            if (extracted.length > 0)
+                categories.add(extracted);
+            continue;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (/\*\//.test(blockLine))
+                    break;
+                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
+                if (trimmed.length === 0)
+                    continue;
+                if (/^=+$/.test(trimmed))
+                    continue;
+                categories.add(trimmed);
+                break;
+            }
+        }
+    }
+    return [...categories];
 }
 /**
  * Validates token-add inputs without mutating files.
@@ -187,8 +235,13 @@ function findCategorySection(lines, category, tokensCssPath) {
         }
     }
     if (categoryLine === -1) {
-        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}. ` +
-            'Available categories are defined by /* =... category ...= */ comment headers.');
+        const discoveredCategories = discoverCategoryHeaders(lines);
+        const available = discoveredCategories.length > 0
+            ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
+            : 'The file currently has no category headers.';
+        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
+            `${available}\n\n` +
+            'Add a header by hand inside the :root block (format: "/* = My Category = */") or re-run "fireforge furnace init --force" to re-seed the default categories.');
     }
     // Find the end of this category section (next section header or closing })
     // Handles both single-line (/* =...= */) and multi-line (/* ===...) section delimiters