@hominis/fireforge 0.35.0 → 0.36.0

package/dist/src/core/token-dark-mode.js

@@ -167,4 +167,3 @@ export function findDarkMediaCloseIndex(lines) {
         return -1;
     return findBlockCloseIndex(stripped, darkMediaLine);
 }
-//# sourceMappingURL=token-dark-mode.js.map

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

@@ -98,4 +98,3 @@ export async function addTokenToDocs(engineDir, options, annotation) {
     await writeText(filePath, lines.join('\n'));
     return { docsAdded, unmappedAdded, countUpdated };
 }
-//# sourceMappingURL=token-docs.js.map

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

@@ -455,4 +455,3 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     await writeText(filePath, content);
     return { added: true, categoryCreated };
 }
-//# sourceMappingURL=token-manager.js.map

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

@@ -71,4 +71,3 @@ ${categoryBlocks}
 }
 `;
 }
-//# sourceMappingURL=token-scaffold.js.map

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

@@ -138,4 +138,3 @@ export function insertVariantDeclaration(lines, variant, declLine) {
     }
     lines.splice(findVariantBlockInsertionPoint(lines), 0, '', `:root${variant} {`, declLine, '}');
 }
-//# sourceMappingURL=token-variant.js.map

package/dist/src/core/toolchain-preflight.d.ts

@@ -14,22 +14,38 @@
  *     the downloaded major differs from the previously downloaded one.
  *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
  *     the minimums the tree itself declares against the host binaries
- *     `mach configure` will resolve. Deliberately FAIL-SOFT: it reports
- *     a mismatch only when a minimum was positively parsed AND the host
- *     binary was found AND its version is definitively lower. Any
- *     uncertainty (file moved upstream, unparseable output, binary not
- *     on PATH) skips silently — the mach-error-hints translator still
- *     catches the real configure failure downstream.
+ *     `mach configure` will resolve, probing configure's own candidate
+ *     order: env override first, then the `~/.mozbuild` state-directory
+ *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
+ *     only, blocking builds whose current tool lived in the state dir
+ *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
+ *     mismatch only when a minimum was positively parsed AND at least
+ *     one candidate resolved AND every resolved candidate is
+ *     definitively lower. Any uncertainty (file moved upstream,
+ *     unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure
+ *     failure downstream.
  */
 /** Tools the preflight knows how to probe. */
 export type ToolchainTool = 'cbindgen' | 'rustc';
+/** One probed candidate binary for a tool. */
+export interface ToolchainCandidate {
+    /** Binary path (or bare name for the PATH candidate). */
+    binary: string;
+    /** Parsed version of the candidate. */
+    version: string;
+}
 /** One definitive host-vs-tree mismatch found by the preflight. */
 export interface ToolchainMismatch {
     tool: ToolchainTool;
-    hostVersion: string;
     minimumVersion: string;
     /** Engine-relative file the minimum was parsed from. */
     declaredIn: string;
+    /**
+     * Every candidate that resolved — all of them below the minimum
+     * (mach-resolution order: env override, mozbuild state dir, PATH).
+     */
+    candidates: ToolchainCandidate[];
 }
 /**
  * Returns the one-line notice to print after a download that hopped the
@@ -49,15 +65,20 @@ export declare function formatMajorVersionHopNotice(previousVersion: string | un
 export declare function readDeclaredToolchainMinimums(engineDir: string): Promise<Partial<Record<ToolchainTool, string>>>;
 /**
  * Compares the tree-declared toolchain minimums against the host binaries
- * `mach configure` will resolve. Returns only DEFINITIVE mismatches; every
- * uncertain probe passes silently (see module header for the rationale).
+ * `mach configure` will resolve, in configure's own candidate order (env
+ * override, mozbuild state dir, PATH). A tool fails ONLY when at least
+ * one candidate resolved and none of them meets the minimum; any single
+ * passing candidate passes the tool (configure will find it), and a tool
+ * with no resolvable candidate skips silently (see module header for the
+ * fail-soft rationale).
  *
  * @param engineDir - Path to the engine directory
  */
 export declare function runToolchainPreflight(engineDir: string): Promise<ToolchainMismatch[]>;
 /**
  * Formats the fail-fast message for definitive preflight mismatches,
- * naming `fireforge bootstrap` as the remedy (mach's own configure error
+ * listing every candidate probed (in mach's resolution order) and naming
+ * `fireforge bootstrap` as the remedy (mach's own configure error
  * suggests `./mach bootstrap`, which is the wrong entry point for a
  * FireForge-managed repo).
  */

package/dist/src/core/toolchain-preflight.js

@@ -15,17 +15,31 @@
  *     the downloaded major differs from the previously downloaded one.
  *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
  *     the minimums the tree itself declares against the host binaries
- *     `mach configure` will resolve. Deliberately FAIL-SOFT: it reports
- *     a mismatch only when a minimum was positively parsed AND the host
- *     binary was found AND its version is definitively lower. Any
- *     uncertainty (file moved upstream, unparseable output, binary not
- *     on PATH) skips silently — the mach-error-hints translator still
- *     catches the real configure failure downstream.
+ *     `mach configure` will resolve, probing configure's own candidate
+ *     order: env override first, then the `~/.mozbuild` state-directory
+ *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
+ *     only, blocking builds whose current tool lived in the state dir
+ *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
+ *     mismatch only when a minimum was positively parsed AND at least
+ *     one candidate resolved AND every resolved candidate is
+ *     definitively lower. Any uncertainty (file moved upstream,
+ *     unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure
+ *     failure downstream.
  */
 import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+/**
+ * Resolves the mach state directory the same way mach itself does:
+ * `$MOZBUILD_STATE_PATH`, else `~/.mozbuild` (same resolution as
+ * `mach-resource-shim.ts`).
+ */
+function mozbuildStateDir() {
+    return process.env['MOZBUILD_STATE_PATH'] ?? join(homedir(), '.mozbuild');
+}
 /** Where each tool's minimum is declared inside the Firefox tree. */
 const MINIMUM_DECLARATIONS = {
     // build/moz.configure/bindgen.configure:
@@ -43,13 +57,30 @@ const MINIMUM_DECLARATIONS = {
         pattern: /MINIMUM_RUST_VERSION\s*=\s*["']([\d.]+)["']/,
     },
 };
-/** How each tool's host binary is resolved and its version parsed. */
+/**
+ * How each tool's host binary is resolved and its version parsed.
+ *
+ * `stateDirRelPaths` are the mach-state-directory locations `fireforge
+ * bootstrap` (via mozboot) installs the tool to. mach's configure tries
+ * the state directory BEFORE the PATH candidates (bindgen.configure's
+ * toolchain search path lists `~/.mozbuild/cbindgen/cbindgen` first — a
+ * configure log shows `trying cbindgen: ~/.mozbuild/cbindgen/cbindgen`
+ * ahead of PATH), so the probe must too. 0.35.0 probed only env-or-PATH,
+ * which failed a build configure would have accepted whenever an old
+ * `~/.cargo/bin/cbindgen` shadowed a current bootstrap-installed copy
+ * (field report: PATH 0.29.1 vs mozbuild 0.29.4, minimum 0.29.4). Rust
+ * has no state-dir install — rustup owns it — so its list is empty.
+ */
 const HOST_PROBES = {
     // `mach configure` honours the CBINDGEN env option (bindgen.configure's
     // `option(env="CBINDGEN", ...)`), so the probe must too — otherwise the
     // preflight could veto a build configure would have accepted.
-    cbindgen: { envVar: 'CBINDGEN', versionPattern: /cbindgen\s+(\d+(?:\.\d+)*)/ },
-    rustc: { envVar: 'RUSTC', versionPattern: /rustc\s+(\d+(?:\.\d+)*)/ },
+    cbindgen: {
+        envVar: 'CBINDGEN',
+        versionPattern: /cbindgen\s+(\d+(?:\.\d+)*)/,
+        stateDirRelPaths: ['cbindgen/cbindgen'],
+    },
+    rustc: { envVar: 'RUSTC', versionPattern: /rustc\s+(\d+(?:\.\d+)*)/, stateDirRelPaths: [] },
 };
 /**
  * Parses a dotted version string into numeric components. Trailing
@@ -126,29 +157,54 @@ export async function readDeclaredToolchainMinimums(engineDir) {
     return minimums;
 }
 /** Runs `<binary> --version` and parses the leading version number. */
-async function probeHostToolVersion(tool) {
-    const probe = HOST_PROBES[tool];
-    const binary = process.env[probe.envVar] ?? tool;
+async function probeBinaryVersion(binary, versionPattern) {
     const output = await new Promise((resolvePromise) => {
         execFile(binary, ['--version'], { timeout: 10_000 }, (err, stdout) => {
             resolvePromise(err ? undefined : stdout);
         });
     });
-    if (output === undefined) {
-        verbose(`Toolchain preflight: "${binary} --version" failed or not found; skipping ${tool}.`);
+    if (output === undefined)
         return undefined;
-    }
-    const match = probe.versionPattern.exec(output);
+    const match = versionPattern.exec(output);
     if (!match?.[1]) {
-        verbose(`Toolchain preflight: could not parse ${tool} version from "${output.trim()}".`);
+        verbose(`Toolchain preflight: could not parse a version from "${output.trim()}" (${binary}).`);
         return undefined;
     }
     return match[1];
 }
+/**
+ * Probes every candidate binary for a tool in mach's resolution order:
+ * the env override (which, when set, is the ONLY candidate — configure
+ * uses it even when a better binary exists elsewhere), then the mozbuild
+ * state-directory copy bootstrap installs, then PATH. Candidates that
+ * fail to run or to parse are dropped silently.
+ */
+async function probeHostToolCandidates(tool) {
+    const probe = HOST_PROBES[tool];
+    const envOverride = process.env[probe.envVar];
+    const binaries = envOverride
+        ? [envOverride]
+        : [...probe.stateDirRelPaths.map((rel) => join(mozbuildStateDir(), rel)), tool];
+    const candidates = [];
+    for (const binary of binaries) {
+        const version = await probeBinaryVersion(binary, probe.versionPattern);
+        if (version !== undefined) {
+            candidates.push({ binary, version });
+        }
+        else {
+            verbose(`Toolchain preflight: "${binary} --version" failed or not found; skipping.`);
+        }
+    }
+    return candidates;
+}
 /**
  * Compares the tree-declared toolchain minimums against the host binaries
- * `mach configure` will resolve. Returns only DEFINITIVE mismatches; every
- * uncertain probe passes silently (see module header for the rationale).
+ * `mach configure` will resolve, in configure's own candidate order (env
+ * override, mozbuild state dir, PATH). A tool fails ONLY when at least
+ * one candidate resolved and none of them meets the minimum; any single
+ * passing candidate passes the tool (configure will find it), and a tool
+ * with no resolvable candidate skips silently (see module header for the
+ * fail-soft rationale).
  *
  * @param engineDir - Path to the engine directory
  */
@@ -159,37 +215,42 @@ export async function runToolchainPreflight(engineDir) {
         const minimum = parseVersionComponents(minimumVersion);
         if (!minimum)
             continue;
-        const hostVersion = await probeHostToolVersion(tool);
-        if (hostVersion === undefined)
+        const candidates = await probeHostToolCandidates(tool);
+        const parsed = candidates.filter((c) => parseVersionComponents(c.version) !== undefined);
+        if (parsed.length === 0)
             continue;
-        const host = parseVersionComponents(hostVersion);
-        if (!host)
+        const satisfying = parsed.find((c) => {
+            const components = parseVersionComponents(c.version);
+            return components !== undefined && !isVersionLower(components, minimum);
+        });
+        if (satisfying) {
+            verbose(`Toolchain preflight: ${tool} ${satisfying.version} (${satisfying.binary}) satisfies minimum ${minimumVersion}.`);
             continue;
-        if (isVersionLower(host, minimum)) {
-            mismatches.push({
-                tool,
-                hostVersion,
-                minimumVersion,
-                declaredIn: MINIMUM_DECLARATIONS[tool].relPath,
-            });
-        }
-        else {
-            verbose(`Toolchain preflight: ${tool} ${hostVersion} satisfies minimum ${minimumVersion}.`);
         }
+        mismatches.push({
+            tool,
+            minimumVersion,
+            declaredIn: MINIMUM_DECLARATIONS[tool].relPath,
+            candidates: parsed,
+        });
     }
     return mismatches;
 }
 /**
  * Formats the fail-fast message for definitive preflight mismatches,
- * naming `fireforge bootstrap` as the remedy (mach's own configure error
+ * listing every candidate probed (in mach's resolution order) and naming
+ * `fireforge bootstrap` as the remedy (mach's own configure error
  * suggests `./mach bootstrap`, which is the wrong entry point for a
  * FireForge-managed repo).
  */
 export function formatToolchainMismatchMessage(mismatches) {
-    const lines = mismatches.map((m) => `  - ${m.tool} ${m.hostVersion} is older than the minimum ${m.minimumVersion} declared by this Firefox source (engine/${m.declaredIn})`);
+    const lines = mismatches.map((m) => {
+        const probed = m.candidates.map((c) => `${c.version} (${c.binary})`).join(', ');
+        return (`  - ${m.tool}: no resolvable candidate meets the minimum ${m.minimumVersion} declared by ` +
+            `this Firefox source (engine/${m.declaredIn}); probed in mach's resolution order: ${probed}`);
+    });
     return ('Toolchain preflight found host tools older than what this Firefox source requires:\n' +
         `${lines.join('\n')}\n\n` +
         'This typically happens after "fireforge download --force" moved the engine to a new ' +
         'Firefox major version. Run "fireforge bootstrap" to update the toolchain, then retry the build.');
 }
-//# sourceMappingURL=toolchain-preflight.js.map

package/dist/src/core/typecheck-shim.js

@@ -60,6 +60,7 @@ interface ChromeUtilsShim {
   defineESModuleGetters(target: any, modules: Record<string, string>): void;
   importESModule(specifier: string): any;
   import(specifier: string): any;
+  registerWindowActor(name: string, options: Record<string, any>): void;
   defineModuleGetter(target: any, name: string, specifier: string): void;
   defineLazyGetter(target: any, name: string, getter: () => any): void;
   generateQI(interfaces: any[]): Function;
@@ -85,6 +86,18 @@ declare var gBrowser: any;
 declare var gURLBar: any;
 declare var gNavigatorBundle: any;
 declare var AppConstants: any;
+declare class JSWindowActorChild {
+  readonly browsingContext: any;
+  readonly contentWindow: any;
+  readonly document: any;
+  sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
+  sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
+}
+declare class JSWindowActorParent {
+  readonly browsingContext: any;
+  sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
+  sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
+}
 // Fluent localization — a stable chrome global. Members stay loose (any),
 // but the constructor shape is declared so "new Localization([...])" and
 // "new Localization([...], true)" typecheck without a local cast. Both
@@ -213,4 +226,3 @@ export async function composeShimSource(projectRoot, extraShimPath) {
         extraShimAppended: true,
     };
 }
-//# sourceMappingURL=typecheck-shim.js.map

package/dist/src/core/typecheck.js

@@ -327,4 +327,3 @@ export function relativeForDisplay(projectRoot, absoluteFile) {
         return absoluteFile;
     return rel;
 }
-//# sourceMappingURL=typecheck.js.map

package/dist/src/core/wire-destroy.js

@@ -121,4 +121,3 @@ export async function addDestroyToBrowserInit(engineDir, expression, marker = DE
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-destroy.js.map

package/dist/src/core/wire-dom-fragment.js

@@ -181,4 +181,3 @@ export async function addDomFragment(engineDir, domFilePath, targetPath = DEFAUL
     await writeText(targetAbsPath, value);
     return true;
 }
-//# sourceMappingURL=wire-dom-fragment.js.map

package/dist/src/core/wire-init.js

@@ -231,4 +231,3 @@ export async function addInitToBrowserInit(engineDir, expression, after, marker
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-init.js.map

package/dist/src/core/wire-subscript.js

@@ -144,4 +144,3 @@ export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAUL
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-subscript.js.map

package/dist/src/core/wire-targets.js

@@ -6,4 +6,3 @@ export { addDestroyToBrowserInit } from './wire-destroy.js';
 export { addDomFragment } from './wire-dom-fragment.js';
 export { addInitToBrowserInit } from './wire-init.js';
 export { addSubscriptToBrowserMain } from './wire-subscript.js';
-//# sourceMappingURL=wire-targets.js.map

package/dist/src/core/wire-utils.js

@@ -349,4 +349,3 @@ export function findMethodBody(ast, methodName) {
     });
     return found;
 }
-//# sourceMappingURL=wire-utils.js.map

package/dist/src/core/xpcshell-appdir.js

@@ -41,6 +41,7 @@
 import { readdir, stat } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 import { pathExists, readJson, readText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
 import { isObject, isString } from '../utils/validation.js';
 /**
  * `[DEFAULT]` section parser shaped to the narrow case we need: pull a
@@ -88,9 +89,6 @@ export function parseAppdirFromToml(tomlText, key) {
     }
     return undefined;
 }
-function escapeRegex(input) {
-    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 function stripQuotes(raw) {
     if (raw.length === 0)
         return undefined;
@@ -305,4 +303,3 @@ export function operatorAlreadySetAppPath(extraArgs) {
     }
     return false;
 }
-//# sourceMappingURL=xpcshell-appdir.js.map

package/dist/src/errors/base.d.ts

@@ -54,6 +54,35 @@ export declare class InvalidArgumentError extends FireForgeError {
     constructor(message: string, argument?: string | undefined, cause?: Error);
     get userMessage(): string;
 }
+/**
+ * Error thrown when a spawned command exceeds its `timeout` option.
+ *
+ * Every `exec*` helper in `src/utils/process.ts` rejects with this type
+ * (instead of Node's bare `AbortError: The operation was aborted`) when the
+ * caller-supplied timeout fires. The bare AbortError bit an operator during
+ * the 2026-04-24 eval (see {@link GitIndexingTimeoutError} in errors/git.ts):
+ * an 854 s git indexing pass died with no command name, no elapsed time, and
+ * no hint that a timeout — not git — was responsible. The git path gained a
+ * site-local typed error then; this class extends the same courtesy to every
+ * other `timeout` caller.
+ */
+export declare class ExecTimeoutError extends FireForgeError {
+    /** Executable that was spawned (argv[0]). */
+    readonly command: string;
+    /** Arguments the executable was spawned with. */
+    readonly args: readonly string[];
+    /** Timeout that elapsed, in milliseconds. */
+    readonly timeoutMs: number;
+    readonly code: 1;
+    constructor(
+    /** Executable that was spawned (argv[0]). */
+    command: string, 
+    /** Arguments the executable was spawned with. */
+    args: readonly string[], 
+    /** Timeout that elapsed, in milliseconds. */
+    timeoutMs: number, cause?: unknown);
+    get userMessage(): string;
+}
 /**
  * Error thrown when the user cancels an interactive prompt.
  */

package/dist/src/errors/base.js

@@ -78,6 +78,41 @@ export class InvalidArgumentError extends FireForgeError {
         return msg;
     }
 }
+/**
+ * Error thrown when a spawned command exceeds its `timeout` option.
+ *
+ * Every `exec*` helper in `src/utils/process.ts` rejects with this type
+ * (instead of Node's bare `AbortError: The operation was aborted`) when the
+ * caller-supplied timeout fires. The bare AbortError bit an operator during
+ * the 2026-04-24 eval (see {@link GitIndexingTimeoutError} in errors/git.ts):
+ * an 854 s git indexing pass died with no command name, no elapsed time, and
+ * no hint that a timeout — not git — was responsible. The git path gained a
+ * site-local typed error then; this class extends the same courtesy to every
+ * other `timeout` caller.
+ */
+export class ExecTimeoutError extends FireForgeError {
+    command;
+    args;
+    timeoutMs;
+    code = ExitCode.GENERAL_ERROR;
+    constructor(
+    /** Executable that was spawned (argv[0]). */
+    command, 
+    /** Arguments the executable was spawned with. */
+    args, 
+    /** Timeout that elapsed, in milliseconds. */
+    timeoutMs, cause) {
+        super(`Command timed out after ${Math.round(timeoutMs / 1000)}s: ${[command, ...args].join(' ')}`, cause);
+        this.command = command;
+        this.args = args;
+        this.timeoutMs = timeoutMs;
+    }
+    get userMessage() {
+        return (`${this.message}\n\n` +
+            'The command was killed because it exceeded its time budget, not because it failed on its own. ' +
+            'If the host is just slow or loaded, re-running may succeed.');
+    }
+}
 /**
  * Error thrown when the user cancels an interactive prompt.
  */
@@ -108,4 +143,3 @@ export class CommandError extends Error {
         this.name = 'CommandError';
     }
 }
-//# sourceMappingURL=base.js.map

package/dist/src/errors/build.js

@@ -111,4 +111,3 @@ export class AmbiguousBuildArtifactsError extends BuildError {
             '  3. Run the command again');
     }
 }
-//# sourceMappingURL=build.js.map

package/dist/src/errors/codes.d.ts

@@ -38,5 +38,11 @@ export declare const ExitCode: {
      * missing profile, etc.).
      */
     readonly SMOKE_LAUNCH_FAILURE: 13;
+    /**
+     * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
+     * conventional "interrupted by the user" code — scripts and CI can tell
+     * a deliberate cancellation apart from a real failure (GENERAL_ERROR).
+     */
+    readonly USER_CANCELLED: 130;
 };
 export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

package/dist/src/errors/codes.js

@@ -39,5 +39,10 @@ export const ExitCode = {
      * missing profile, etc.).
      */
     SMOKE_LAUNCH_FAILURE: 13,
+    /**
+     * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
+     * conventional "interrupted by the user" code — scripts and CI can tell
+     * a deliberate cancellation apart from a real failure (GENERAL_ERROR).
+     */
+    USER_CANCELLED: 130,
 };
-//# sourceMappingURL=codes.js.map

package/dist/src/errors/config.js

@@ -58,4 +58,3 @@ export class InvalidFieldError extends ConfigError {
         this.actualValue = actualValue;
     }
 }
-//# sourceMappingURL=config.js.map

package/dist/src/errors/download.js

@@ -129,4 +129,3 @@ export class PartialEngineExistsError extends DownloadError {
             '  3. Re-run with --verbose for the full underlying error and stack trace');
     }
 }
-//# sourceMappingURL=download.js.map

package/dist/src/errors/furnace.d.ts

@@ -5,6 +5,16 @@ import { FireForgeError } from './base.js';
 export declare class FurnaceError extends FireForgeError {
     readonly component?: string | undefined;
     readonly code: 9;
-    constructor(message: string, component?: string | undefined, cause?: Error);
+    constructor(message: string, component?: string | undefined, cause?: Error, options?: {
+        /**
+         * Suppresses the "run furnace validate" advice line. Set by callers
+         * whose message already tells the user to run validate (or that ARE
+         * the validate command) — an explicit flag, because the previous
+         * `message.includes('furnace validate')` sniffing dropped the advice
+         * from any error that merely MENTIONED the command.
+         */
+        omitValidateAdvice?: boolean;
+    });
+    private readonly omitValidateAdvice;
     get userMessage(): string;
 }

package/dist/src/errors/furnace.js

@@ -7,22 +7,23 @@ import { ExitCode } from './codes.js';
 export class FurnaceError extends FireForgeError {
     component;
     code = ExitCode.FURNACE_ERROR;
-    constructor(message, component, cause) {
+    constructor(message, component, cause, options) {
         super(message, cause);
         this.component = component;
+        this.omitValidateAdvice =
+            options?.omitValidateAdvice ?? message.includes('Run "fireforge furnace validate"');
     }
+    omitValidateAdvice;
     get userMessage() {
         let msg = this.component
             ? `Furnace Error (${this.component}): ${this.message}`
             : `Furnace Error: ${this.message}`;
         msg += '\n\nTo fix this:\n';
         msg += '  1. Check the error message above for specifics\n';
-        // Avoid circular advice when the error is thrown during validation itself.
-        if (!this.message.includes('furnace validate')) {
+        if (!this.omitValidateAdvice) {
             msg += '  2. Run "fireforge furnace validate" to diagnose issues\n';
         }
-        msg += `  ${this.message.includes('furnace validate') ? '2' : '3'}. Use "fireforge doctor --repair-furnace" if state is inconsistent`;
+        msg += `  ${this.omitValidateAdvice ? '2' : '3'}. Use "fireforge doctor --repair-furnace" if state is inconsistent`;
         return msg;
     }
 }
-//# sourceMappingURL=furnace.js.map

package/dist/src/errors/git.js

@@ -135,4 +135,3 @@ export class GitIndexingTimeoutError extends GitError {
             '  3. If the problem persists, check disk throughput and free space; Firefox source indexing on a cold SSD typically completes in 1–3 minutes.');
     }
 }
-//# sourceMappingURL=git.js.map

package/dist/src/errors/patch.d.ts

@@ -1,4 +1,21 @@
 import { FireForgeError } from './base.js';
+/**
+ * Error thrown when `patches.json` exists but cannot be parsed or validated.
+ *
+ * This must be a HARD error on every mutating path. The historical behavior
+ * collapsed "corrupt" into "absent" (`loadPatchesManifest` returned null for
+ * both), so the next `fireforge export` would rebuild the manifest containing
+ * only the new patch — silently destroying every other patch's metadata
+ * (tiers, descriptions, lintIgnore, staged dependencies) — and a failed
+ * export's rollback would then delete `patches.json` outright because the
+ * "before" state looked absent (2026-07-05 review, finding H2).
+ */
+export declare class PatchManifestCorruptError extends FireForgeError {
+    readonly manifestPath: string;
+    readonly code: 6;
+    constructor(manifestPath: string, cause?: Error);
+    get userMessage(): string;
+}
 /**
  * Error thrown when patch operations fail.
  */

package/dist/src/errors/patch.js

@@ -1,6 +1,35 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { FireForgeError } from './base.js';
 import { ExitCode } from './codes.js';
+/**
+ * Error thrown when `patches.json` exists but cannot be parsed or validated.
+ *
+ * This must be a HARD error on every mutating path. The historical behavior
+ * collapsed "corrupt" into "absent" (`loadPatchesManifest` returned null for
+ * both), so the next `fireforge export` would rebuild the manifest containing
+ * only the new patch — silently destroying every other patch's metadata
+ * (tiers, descriptions, lintIgnore, staged dependencies) — and a failed
+ * export's rollback would then delete `patches.json` outright because the
+ * "before" state looked absent (2026-07-05 review, finding H2).
+ */
+export class PatchManifestCorruptError extends FireForgeError {
+    manifestPath;
+    code = ExitCode.PATCH_ERROR;
+    constructor(manifestPath, cause) {
+        super(`patches.json exists but could not be parsed: ${cause?.message ?? 'unknown parse error'}`, cause);
+        this.manifestPath = manifestPath;
+    }
+    get userMessage() {
+        return (`Patch Manifest Error: ${this.message}\n\n` +
+            `Manifest: ${this.manifestPath}\n\n` +
+            'FireForge refuses to modify the patch queue while patches.json is unreadable — ' +
+            'rewriting it now would silently discard the metadata of every patch it lists.\n\n' +
+            'To fix this:\n' +
+            '  1. Open patches.json and repair the syntax error (a recent hand-edit is the usual cause)\n' +
+            '  2. Or restore patches.json from version control\n' +
+            '  3. Then re-run the command');
+    }
+}
 /**
  * Error thrown when patch operations fail.
  */
@@ -23,4 +52,3 @@ export class PatchError extends FireForgeError {
         return msg;
     }
 }
-//# sourceMappingURL=patch.js.map