@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -9,7 +9,7 @@ import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
 import { asEstree, detectIndent, getNodeSource, parseScript, } from './ast-utils.js';
-import { withParserFallback } from './parser-fallback.js';
+import { isInternalInvariantFailure, withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
 /**
@@ -23,10 +23,9 @@ const DEFAULT_MARKER = 'FIREFORGE:';
  * the top of the method body when there is none.
  *
  * Both callers below — the `--after`-target-not-found fallthrough and the
- * no-`--after` default — ran a character-for-character copy of this ladder,
- * including both throw guards. `browser-init.js` is written through those two
- * independent paths and they MUST emit identical blocks, so having one
- * implementation enforces the invariant rather than merely tidying.
+ * no-`--after` default — must emit identical blocks, since `browser-init.js`
+ * is written through both paths. One implementation enforces that invariant
+ * rather than merely tidying.
  */
 function resolveDefaultInsertion(content, body, fireforgeBlocks) {
     if (fireforgeBlocks.length > 0) {
@@ -49,9 +48,8 @@ function resolveDefaultInsertion(content, body, fireforgeBlocks) {
  *
  * `marker` is prepended (uppercased) to the generated comment line so the
  * emitted block carries the patch-lint `// <MARKER>:` signature that
- * `lintModificationComments` looks for. Otherwise the first export after
- * `wire` trips `missing-modification-comment` on wire-generated edits —
- * exactly the eval 1 Finding #9 regression.
+ * `lintModificationComments` looks for; otherwise the first export after
+ * `wire` trips `missing-modification-comment` on wire-generated edits.
  */
 export function addInitAST(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
@@ -206,22 +204,13 @@ export async function addInitToBrowserInit(engineDir, expression, after, marker
     const content = await readText(filePath);
     // Idempotency check — look for the coerced (call) form because that is
     // what the emitter writes. Matching against the raw input would miss a
-    // previous `EvalStartup.init` invocation that the 0.16.0 coercion
-    // already persisted as `EvalStartup.init()`.
+    // bare `X.init` invocation that coercion already persisted as `X.init()`.
     const callExpression = coerceToCall(expression);
     const initPattern = new RegExp(`(?:^|\\W)${escapeRegex(callExpression)}\\s*;?\\s*$`, 'm');
     if (initPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after, marker), () => legacyAddInit(content, expression, after, marker), BROWSER_INIT_JS, 
-    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
-    // …array"): those are programming bugs, and retrying the legacy scanner
-    // cannot fix a broken invariant — it just buries the stack. Everything
-    // else still falls back, which is load-bearing: the AST path raises a raw
-    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
-    // directives), and BuildError when the file's shape is unexpected. Both
-    // are exactly what the legacy scanner is here to handle.
-    (error) => error instanceof GeneralError);
+    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after, marker), () => legacyAddInit(content, expression, after, marker), BROWSER_INIT_JS, isInternalInvariantFailure);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }

package/dist/src/core/wire-subscript.d.ts

@@ -5,9 +5,8 @@
  * AST-based implementation: finds the last try/catch containing
  * `loadSubScript` and inserts a new try/catch block after it.
  *
- * The inserted block carries a `// <MARKER>: wire-subscript ...` comment
- * so the emitted edit satisfies `lintModificationComments` (eval 1
- * Finding #9).
+ * The inserted block carries a `// <MARKER>: wire-subscript ...` comment so
+ * the emitted edit satisfies `lintModificationComments`.
  */
 export declare function addSubscriptAST(content: string, name: string, marker?: string): string;
 /**

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

@@ -8,7 +8,7 @@ import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { asEstree, detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
-import { withParserFallback } from './parser-fallback.js';
+import { isInternalInvariantFailure, withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, findNearestTryLine, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_MAIN_JS = 'browser/base/content/browser-main.js';
 const DEFAULT_MARKER = 'FIREFORGE:';
@@ -16,9 +16,8 @@ const DEFAULT_MARKER = 'FIREFORGE:';
  * AST-based implementation: finds the last try/catch containing
  * `loadSubScript` and inserts a new try/catch block after it.
  *
- * The inserted block carries a `// <MARKER>: wire-subscript ...` comment
- * so the emitted edit satisfies `lintModificationComments` (eval 1
- * Finding #9).
+ * The inserted block carries a `// <MARKER>: wire-subscript ...` comment so
+ * the emitted edit satisfies `lintModificationComments`.
  */
 export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
     const ast = parseScript(content);
@@ -137,15 +136,7 @@ export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAUL
     if (content.includes(`content/${name}.js"`)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name, marker), () => legacyAddSubscript(content, name, marker), BROWSER_MAIN_JS, 
-    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
-    // …array"): those are programming bugs, and retrying the legacy scanner
-    // cannot fix a broken invariant — it just buries the stack. Everything
-    // else still falls back, which is load-bearing: the AST path raises a raw
-    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
-    // directives), and BuildError when the file's shape is unexpected. Both
-    // are exactly what the legacy scanner is here to handle.
-    (error) => error instanceof GeneralError);
+    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name, marker), () => legacyAddSubscript(content, name, marker), BROWSER_MAIN_JS, isInternalInvariantFailure);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_MAIN_JS);
     }

package/dist/src/core/wire-utils.d.ts

@@ -9,15 +9,14 @@ export declare function validateWireName(value: string, label: string): void;
  * Coerces an init/destroy expression into a function call by appending `()`
  * when the caller passed a bare property chain. Idempotent: an expression
  * already ending in `()` is returned unchanged, so operators can pass either
- * `EvalStartup.init` or `EvalStartup.init()` and get the same wired output.
+ * `Startup.init` or `Startup.init()` and get the same wired output.
  *
- * Motivation (eval finding 8): `validateWireName` accepts both shapes, but
- * the generated block interpolated the expression verbatim inside
- * `${expression};`. When a caller passed `EvalStartup.init`, the emitted
- * code was `EvalStartup.init;` — a plain property reference that never
- * invoked the lifecycle hook. The symptom was silent: `wire` reported
- * success and the browser-init block looked plausible, but the hook
- * never fired at runtime. Coercion at the template site closes that gap.
+ * `validateWireName` accepts both shapes, but the generated block
+ * interpolates the expression verbatim inside `${expression};` — so a bare
+ * `Startup.init` emits `Startup.init;`, a plain property reference that
+ * never invokes the lifecycle hook. The symptom is silent: `wire` reports
+ * success and the browser-init block looks plausible, but the hook never
+ * fires at runtime.
  */
 export declare function coerceToCall(expression: string): string;
 /**

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

@@ -21,15 +21,14 @@ export function validateWireName(value, label) {
  * Coerces an init/destroy expression into a function call by appending `()`
  * when the caller passed a bare property chain. Idempotent: an expression
  * already ending in `()` is returned unchanged, so operators can pass either
- * `EvalStartup.init` or `EvalStartup.init()` and get the same wired output.
+ * `Startup.init` or `Startup.init()` and get the same wired output.
  *
- * Motivation (eval finding 8): `validateWireName` accepts both shapes, but
- * the generated block interpolated the expression verbatim inside
- * `${expression};`. When a caller passed `EvalStartup.init`, the emitted
- * code was `EvalStartup.init;` — a plain property reference that never
- * invoked the lifecycle hook. The symptom was silent: `wire` reported
- * success and the browser-init block looked plausible, but the hook
- * never fired at runtime. Coercion at the template site closes that gap.
+ * `validateWireName` accepts both shapes, but the generated block
+ * interpolates the expression verbatim inside `${expression};` — so a bare
+ * `Startup.init` emits `Startup.init;`, a plain property reference that
+ * never invokes the lifecycle hook. The symptom is silent: `wire` reports
+ * success and the browser-init block looks plausible, but the hook never
+ * fires at runtime.
  */
 export function coerceToCall(expression) {
     return expression.endsWith('()') ? expression : `${expression}()`;

package/dist/src/core/xpcshell-appdir.d.ts

@@ -8,33 +8,32 @@
  * The upstream xpcshell harness computes the manifest key for the appdir
  * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
  * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
- * directive is honoured. On a rebranded fork (appname=`mybrowser`, …) the
- * harness looks for `mybrowser-appdir`
- * — the literal `firefox-appdir` line is silently ignored, `appPath` falls
- * back to `xrePath`, and every `resource:///modules/…` import throws
- * `Failed to load resource:///modules/<name>.sys.mjs` because xpcshell now
- * resolves the `resource:///` prefix one level above the real app root.
+ * directive is honoured. On a rebranded fork (appname=`mybrowser`) the
+ * harness looks for `mybrowser-appdir` — the literal `firefox-appdir` line
+ * is silently ignored, `appPath` falls back to `xrePath`, and every
+ * `resource:///modules/…` import throws `Failed to load
+ * resource:///modules/<name>.sys.mjs` because xpcshell resolves the
+ * `resource:///` prefix one level above the real app root.
  *
  * ## Strategy
  *
  * 1. For each test path the operator handed us, find the nearest
  *    `xpcshell.toml`. If none exists, the test is not an xpcshell test and
- *    nothing to inject.
+ *    there is nothing to inject.
  * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
- *    first — if present, the harness already finds it and there's nothing to
- *    do. Fall back to `firefox-appdir`. This ordering matches upstream
- *    precedence and avoids overriding an operator who already migrated.
+ *    first — if present, the harness already finds it. Fall back to
+ *    `firefox-appdir`. This ordering matches upstream precedence and avoids
+ *    overriding an operator who already migrated.
  * 3. If only `firefox-appdir` is present and `appname != "firefox"`, compute
- *    the absolute app dir path against the active `obj-X/dist` tree
- *    (probing `dist/bin/<value>` first, then any `dist/<bundle>.app/Contents/
- *    Resources/<value>` for the macOS packaged layout) and return it as
- *    the value to pass to `--app-path`.
- * 4. If multiple test paths disagree on the resolved value (e.g. one
- *    manifest sets `browser`, another sets `xulrunner`), refuse injection
+ *    the absolute app dir path against the active `obj-X/dist` tree (probing
+ *    `dist/bin/<value>` first, then any
+ *    `dist/<bundle>.app/Contents/Resources/<value>` for the macOS packaged
+ *    layout) and return it as the value to pass to `--app-path`.
+ * 4. If multiple test paths disagree on the resolved value, refuse injection
  *    and return null — the operator can drop down to `--mach-arg`.
  *
- * Operator escape hatches: `--mach-arg=--app-path=…` always wins (handled in
- * test.ts; we skip injection when `--app-path=` already appears in the
+ * Operator escape hatch: `--mach-arg=--app-path=…` always wins (handled in
+ * test.ts, which skips injection when `--app-path=` already appears in the
  * forwarded args).
  */
 /**
@@ -75,15 +74,14 @@ export declare function parseAppdirFromToml(tomlText: string, key: string): {
  * returns the absolute path of the first sibling `xpcshell.toml` found.
  * Stops at `engineDir` (inclusive) and returns null on miss.
  *
- * Special-cases `startPath` itself when it already ends with
- * `xpcshell.toml` — operators sometimes pass a manifest path directly.
+ * Special-cases `startPath` itself when it already ends with `xpcshell.toml`
+ * — operators sometimes pass a manifest path directly.
  *
  * When `startPath` is a DIRECTORY, the walk starts at the directory itself
- * (checking `<dir>/xpcshell.toml` first) rather than at its parent. Field
- * report (0.34.0 cycle): a directory whose own manifest is an
- * `xpcshell.toml` was classified non-xpcshell — the walk began at the
- * parent, missed the manifest, and `fireforge test <dir>` dispatched to
- * the mochitest runner, which found no mochitests.
+ * (checking `<dir>/xpcshell.toml` first) rather than at its parent.
+ * Starting at the parent misses a directory's own manifest, so
+ * `fireforge test <dir>` classifies it non-xpcshell and dispatches to the
+ * mochitest runner, which finds no mochitests.
  */
 export declare function findNearestXpcshellManifest(engineDir: string, startPath: string): Promise<string | null>;
 /**
@@ -96,32 +94,27 @@ export declare function findNearestXpcshellManifest(engineDir: string, startPath
  */
 export declare function readMozinfoAppname(objDirPath: string): Promise<string>;
 /**
- * Probes the obj-dir's `dist/` subtree for the absolute path that the
- * harness would have computed if the manifest key had been honoured.
- * Returns null when no candidate exists — better to skip injection
- * silently than to point the harness at a path that doesn't exist
- * (which fails with a different error than the original `firefox-appdir`
- * symptom and confuses triage).
+ * Probes the obj-dir's `dist/` subtree for the absolute path the harness
+ * would have computed if the manifest key had been honoured. Returns null
+ * when no candidate exists — better to skip injection silently than to point
+ * the harness at a path that does not exist, which fails with a different
+ * error than the original symptom and confuses triage.
  *
  * Probe order differs by host platform:
  *
- * - **macOS (`darwin`)**: prefer `<objDir>/dist/<App>.app/Contents/Resources/
- *   <value>` FIRST, then fall back to `<objDir>/dist/bin/<value>`.
- *   2026-04-24 eval Finding 8: on macOS `dist/bin` is symlinked to
+ * - **macOS (`darwin`)**: prefer
+ *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` FIRST, then fall
+ *   back to `<objDir>/dist/bin/<value>`. On macOS `dist/bin` is symlinked to
  *   `dist/<App>.app/Contents/MacOS/` (the *binaries* directory), so
- *   `dist/bin/browser` actually resolves to `<App>.app/Contents/MacOS/
- *   browser/`. That is NOT where `resource:///modules/` is rooted — on
- *   macOS, `-a` for xpcshell must point at the `.app/Contents/Resources/
- *   <value>` subtree where modules / chrome.manifest live. Returning
- *   `dist/bin/browser` caused the injected `--app-path` to look
- *   successful (the info log showed it) but pointed at a directory
- *   without the modules tree, so every `resource:///modules/…` import
- *   still threw.
- * - **non-macOS**: keep the historical order — `dist/bin/<value>` first,
+ *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/` —
+ *   NOT where `resource:///modules/` is rooted. Injecting that path looks
+ *   successful in the log but points at a directory with no modules tree, so
+ *   every `resource:///modules/…` import still throws.
+ * - **non-macOS**: `dist/bin/<value>` first,
  *   `.app/Contents/Resources/<value>` as fallback.
  *
- * On both platforms the final `.app` fallback iterates every `*.app`
- * entry because a rebranded fork may pick an arbitrary app name.
+ * On both platforms the final `.app` fallback iterates every `*.app` entry
+ * because a rebranded fork may pick an arbitrary app name.
  */
 export declare function resolveAbsoluteAppPath(objDirAbs: string, relativeAppdir: string): Promise<string | null>;
 /**

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

@@ -9,33 +9,32 @@
  * The upstream xpcshell harness computes the manifest key for the appdir
  * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
  * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
- * directive is honoured. On a rebranded fork (appname=`mybrowser`, …) the
- * harness looks for `mybrowser-appdir`
- * — the literal `firefox-appdir` line is silently ignored, `appPath` falls
- * back to `xrePath`, and every `resource:///modules/…` import throws
- * `Failed to load resource:///modules/<name>.sys.mjs` because xpcshell now
- * resolves the `resource:///` prefix one level above the real app root.
+ * directive is honoured. On a rebranded fork (appname=`mybrowser`) the
+ * harness looks for `mybrowser-appdir` — the literal `firefox-appdir` line
+ * is silently ignored, `appPath` falls back to `xrePath`, and every
+ * `resource:///modules/…` import throws `Failed to load
+ * resource:///modules/<name>.sys.mjs` because xpcshell resolves the
+ * `resource:///` prefix one level above the real app root.
  *
  * ## Strategy
  *
  * 1. For each test path the operator handed us, find the nearest
  *    `xpcshell.toml`. If none exists, the test is not an xpcshell test and
- *    nothing to inject.
+ *    there is nothing to inject.
  * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
- *    first — if present, the harness already finds it and there's nothing to
- *    do. Fall back to `firefox-appdir`. This ordering matches upstream
- *    precedence and avoids overriding an operator who already migrated.
+ *    first — if present, the harness already finds it. Fall back to
+ *    `firefox-appdir`. This ordering matches upstream precedence and avoids
+ *    overriding an operator who already migrated.
  * 3. If only `firefox-appdir` is present and `appname != "firefox"`, compute
- *    the absolute app dir path against the active `obj-X/dist` tree
- *    (probing `dist/bin/<value>` first, then any `dist/<bundle>.app/Contents/
- *    Resources/<value>` for the macOS packaged layout) and return it as
- *    the value to pass to `--app-path`.
- * 4. If multiple test paths disagree on the resolved value (e.g. one
- *    manifest sets `browser`, another sets `xulrunner`), refuse injection
+ *    the absolute app dir path against the active `obj-X/dist` tree (probing
+ *    `dist/bin/<value>` first, then any
+ *    `dist/<bundle>.app/Contents/Resources/<value>` for the macOS packaged
+ *    layout) and return it as the value to pass to `--app-path`.
+ * 4. If multiple test paths disagree on the resolved value, refuse injection
  *    and return null — the operator can drop down to `--mach-arg`.
  *
- * Operator escape hatches: `--mach-arg=--app-path=…` always wins (handled in
- * test.ts; we skip injection when `--app-path=` already appears in the
+ * Operator escape hatch: `--mach-arg=--app-path=…` always wins (handled in
+ * test.ts, which skips injection when `--app-path=` already appears in the
  * forwarded args).
  */
 import { readdir, stat } from 'node:fs/promises';
@@ -106,15 +105,14 @@ function stripQuotes(raw) {
  * returns the absolute path of the first sibling `xpcshell.toml` found.
  * Stops at `engineDir` (inclusive) and returns null on miss.
  *
- * Special-cases `startPath` itself when it already ends with
- * `xpcshell.toml` — operators sometimes pass a manifest path directly.
+ * Special-cases `startPath` itself when it already ends with `xpcshell.toml`
+ * — operators sometimes pass a manifest path directly.
  *
  * When `startPath` is a DIRECTORY, the walk starts at the directory itself
- * (checking `<dir>/xpcshell.toml` first) rather than at its parent. Field
- * report (0.34.0 cycle): a directory whose own manifest is an
- * `xpcshell.toml` was classified non-xpcshell — the walk began at the
- * parent, missed the manifest, and `fireforge test <dir>` dispatched to
- * the mochitest runner, which found no mochitests.
+ * (checking `<dir>/xpcshell.toml` first) rather than at its parent.
+ * Starting at the parent misses a directory's own manifest, so
+ * `fireforge test <dir>` classifies it non-xpcshell and dispatches to the
+ * mochitest runner, which finds no mochitests.
  */
 export async function findNearestXpcshellManifest(engineDir, startPath) {
     const absStart = resolve(engineDir, startPath);
@@ -164,32 +162,27 @@ export async function readMozinfoAppname(objDirPath) {
     return 'firefox';
 }
 /**
- * Probes the obj-dir's `dist/` subtree for the absolute path that the
- * harness would have computed if the manifest key had been honoured.
- * Returns null when no candidate exists — better to skip injection
- * silently than to point the harness at a path that doesn't exist
- * (which fails with a different error than the original `firefox-appdir`
- * symptom and confuses triage).
+ * Probes the obj-dir's `dist/` subtree for the absolute path the harness
+ * would have computed if the manifest key had been honoured. Returns null
+ * when no candidate exists — better to skip injection silently than to point
+ * the harness at a path that does not exist, which fails with a different
+ * error than the original symptom and confuses triage.
  *
  * Probe order differs by host platform:
  *
- * - **macOS (`darwin`)**: prefer `<objDir>/dist/<App>.app/Contents/Resources/
- *   <value>` FIRST, then fall back to `<objDir>/dist/bin/<value>`.
- *   2026-04-24 eval Finding 8: on macOS `dist/bin` is symlinked to
+ * - **macOS (`darwin`)**: prefer
+ *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` FIRST, then fall
+ *   back to `<objDir>/dist/bin/<value>`. On macOS `dist/bin` is symlinked to
  *   `dist/<App>.app/Contents/MacOS/` (the *binaries* directory), so
- *   `dist/bin/browser` actually resolves to `<App>.app/Contents/MacOS/
- *   browser/`. That is NOT where `resource:///modules/` is rooted — on
- *   macOS, `-a` for xpcshell must point at the `.app/Contents/Resources/
- *   <value>` subtree where modules / chrome.manifest live. Returning
- *   `dist/bin/browser` caused the injected `--app-path` to look
- *   successful (the info log showed it) but pointed at a directory
- *   without the modules tree, so every `resource:///modules/…` import
- *   still threw.
- * - **non-macOS**: keep the historical order — `dist/bin/<value>` first,
+ *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/` —
+ *   NOT where `resource:///modules/` is rooted. Injecting that path looks
+ *   successful in the log but points at a directory with no modules tree, so
+ *   every `resource:///modules/…` import still throws.
+ * - **non-macOS**: `dist/bin/<value>` first,
  *   `.app/Contents/Resources/<value>` as fallback.
  *
- * On both platforms the final `.app` fallback iterates every `*.app`
- * entry because a rebranded fork may pick an arbitrary app name.
+ * On both platforms the final `.app` fallback iterates every `*.app` entry
+ * because a rebranded fork may pick an arbitrary app name.
  */
 export async function resolveAbsoluteAppPath(objDirAbs, relativeAppdir) {
     const distBinCandidate = join(objDirAbs, 'dist', 'bin', relativeAppdir);

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

@@ -79,13 +79,10 @@ export declare class InvalidArgumentError extends FireForgeError {
  * 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.
+ * instead of Node's bare `AbortError: The operation was aborted`, which
+ * carries no command name, no elapsed time, and no hint that a timeout —
+ * not the command — was responsible. See {@link GitIndexingTimeoutError} in
+ * errors/git.ts for the git-specific variant.
  */
 export declare class ExecTimeoutError extends FireForgeError {
     /** Executable that was spawned (argv[0]). */
@@ -105,23 +102,47 @@ export declare class ExecTimeoutError extends FireForgeError {
     get userMessage(): string;
 }
 /**
- * Error thrown when a file-lock wait times out because another process
- * holds the lock.
+ * Error thrown when a file-lock wait times out because another process holds
+ * the lock.
  *
  * Dedicated subclass so the CLI boundary renders lock contention as the
- * one-line reason-first/remedy-second refusal it is — before this, the
- * timeout surfaced as a plain `Error`, which `withErrorHandling` treats
- * as an internal failure and prints with a five-frame stack. The refusal
- * was always correct; the presentation made it look like a crash.
+ * one-line reason-first/remedy-second refusal it is. As a plain `Error` it
+ * is treated by `withErrorHandling` as an internal failure and printed with
+ * a five-frame stack — a correct refusal that looks like a crash.
+ *
+ * Exit code 15, not 1: the run never started. A script that retries on
+ * failure wants to re-queue this one, not treat it as a failure of the work
+ * it asked for. Every lock in FireForge shares the class and therefore the
+ * code — the fact is the same whichever lock was contended.
  */
 export declare class LockContentionError extends FireForgeError {
-    readonly code: 1;
+    readonly code: 15;
+}
+/**
+ * Error thrown when a test run completed but its verdict cannot be trusted,
+ * because `engine/` changed (or stopped being probeable) while the harness
+ * was running.
+ *
+ * Dedicated subclass for its exit code alone: as a `GeneralError` this
+ * refusal exited 1 beside real test failures' 5, and a summary line reading
+ * `FAIL — exit 1` next to `FAIL — exit 5` invites treating them as the same
+ * kind of fact. They are opposites — one suite failed, the other's result
+ * was discarded — and only a distinct code makes "unknown, re-run"
+ * mechanically separable from "red".
+ */
+export declare class InconclusiveVerdictError extends FireForgeError {
+    readonly code: 14;
 }
 /**
- * Error thrown when the user cancels an interactive prompt.
+ * Error thrown when the user INTERRUPTS an interactive prompt — Esc or
+ * Ctrl+C, i.e. `isCancel(...)`.
+ *
+ * Not for a prompt the operator deliberately answered "no" to: 130 is
+ * 128+SIGINT, which claims an interrupt. A declined confirmation is a
+ * successful run that chose not to proceed, and exits 0.
  */
 export declare class CancellationError extends FireForgeError {
-    readonly code: 1;
+    readonly code: 130;
     constructor();
 }
 /**

package/dist/src/errors/base.js

@@ -113,13 +113,10 @@ export class InvalidArgumentError extends FireForgeError {
  * 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.
+ * instead of Node's bare `AbortError: The operation was aborted`, which
+ * carries no command name, no elapsed time, and no hint that a timeout —
+ * not the command — was responsible. See {@link GitIndexingTimeoutError} in
+ * errors/git.ts for the git-specific variant.
  */
 export class ExecTimeoutError extends FireForgeError {
     command;
@@ -145,23 +142,47 @@ export class ExecTimeoutError extends FireForgeError {
     }
 }
 /**
- * Error thrown when a file-lock wait times out because another process
- * holds the lock.
+ * Error thrown when a file-lock wait times out because another process holds
+ * the lock.
  *
  * Dedicated subclass so the CLI boundary renders lock contention as the
- * one-line reason-first/remedy-second refusal it is — before this, the
- * timeout surfaced as a plain `Error`, which `withErrorHandling` treats
- * as an internal failure and prints with a five-frame stack. The refusal
- * was always correct; the presentation made it look like a crash.
+ * one-line reason-first/remedy-second refusal it is. As a plain `Error` it
+ * is treated by `withErrorHandling` as an internal failure and printed with
+ * a five-frame stack — a correct refusal that looks like a crash.
+ *
+ * Exit code 15, not 1: the run never started. A script that retries on
+ * failure wants to re-queue this one, not treat it as a failure of the work
+ * it asked for. Every lock in FireForge shares the class and therefore the
+ * code — the fact is the same whichever lock was contended.
  */
 export class LockContentionError extends FireForgeError {
-    code = ExitCode.GENERAL_ERROR;
+    code = ExitCode.LOCK_TIMEOUT;
+}
+/**
+ * Error thrown when a test run completed but its verdict cannot be trusted,
+ * because `engine/` changed (or stopped being probeable) while the harness
+ * was running.
+ *
+ * Dedicated subclass for its exit code alone: as a `GeneralError` this
+ * refusal exited 1 beside real test failures' 5, and a summary line reading
+ * `FAIL — exit 1` next to `FAIL — exit 5` invites treating them as the same
+ * kind of fact. They are opposites — one suite failed, the other's result
+ * was discarded — and only a distinct code makes "unknown, re-run"
+ * mechanically separable from "red".
+ */
+export class InconclusiveVerdictError extends FireForgeError {
+    code = ExitCode.INCONCLUSIVE;
 }
 /**
- * Error thrown when the user cancels an interactive prompt.
+ * Error thrown when the user INTERRUPTS an interactive prompt — Esc or
+ * Ctrl+C, i.e. `isCancel(...)`.
+ *
+ * Not for a prompt the operator deliberately answered "no" to: 130 is
+ * 128+SIGINT, which claims an interrupt. A declined confirmation is a
+ * successful run that chose not to proceed, and exits 0.
  */
 export class CancellationError extends FireForgeError {
-    code = ExitCode.GENERAL_ERROR;
+    code = ExitCode.USER_CANCELLED;
     constructor() {
         super('cancelled');
     }

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

@@ -47,6 +47,18 @@ export declare class MozconfigError extends BuildError {
  */
 export declare class AmbiguousBuildArtifactsError extends BuildError {
     readonly objDirs: string[];
-    constructor(objDirs: string[]);
+    /**
+     * Objdir the active mozconfig declared, when one was declared and did
+     * not resolve to exactly one candidate. Reported because a declaration
+     * that names something the scan cannot see is the diagnosis, not noise.
+     */
+    readonly declaredObjDir?: string | undefined;
+    constructor(objDirs: string[], 
+    /**
+     * Objdir the active mozconfig declared, when one was declared and did
+     * not resolve to exactly one candidate. Reported because a declaration
+     * that names something the scan cannot see is the diagnosis, not noise.
+     */
+    declaredObjDir?: string | undefined);
     get userMessage(): string;
 }

package/dist/src/errors/build.js

@@ -97,17 +97,29 @@ export class MozconfigError extends BuildError {
  */
 export class AmbiguousBuildArtifactsError extends BuildError {
     objDirs;
-    constructor(objDirs) {
+    declaredObjDir;
+    constructor(objDirs, 
+    /**
+     * Objdir the active mozconfig declared, when one was declared and did
+     * not resolve to exactly one candidate. Reported because a declaration
+     * that names something the scan cannot see is the diagnosis, not noise.
+     */
+    declaredObjDir) {
         super(`Multiple build artifact directories found: ${objDirs.join(', ')}`);
         this.objDirs = objDirs;
+        this.declaredObjDir = declaredObjDir;
     }
     get userMessage() {
+        const declared = this.declaredObjDir !== undefined
+            ? `The mozconfig declares MOZ_OBJDIR=${this.declaredObjDir}, which does not match exactly one of these candidates — so it could not settle the choice.\n\n`
+            : '';
         return ('Build Error: Multiple build artifact directories were found.\n\n' +
             `Candidates: ${this.objDirs.join(', ')}\n\n` +
+            declared +
             'FireForge will not guess which build output to use.\n\n' +
             'To fix this:\n' +
             '  1. Remove stale obj-* directories you no longer need\n' +
-            '  2. Keep only the active build output directory\n' +
+            '  2. Keep only the active build output directory, or name it with MOZ_OBJDIR in the mozconfig\n' +
             '  3. Run the command again');
     }
 }