@hominis/fireforge 0.42.0 → 0.43.1

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

@@ -22,6 +22,7 @@
  * above so the command layer can retry them with a bounded budget instead
  * of reporting phantom test failures (or phantom passes).
  */
+import { hasKnownTeardownNoise } from './mach-known-noise-filter.js';
 const TEST_START_PATTERN = /\bTEST-START\b/;
 /**
  * Structured-log execution marker (`mach xpcshell-test` mozlog output uses
@@ -452,6 +453,21 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     const firstRealFailure = realFailures[0];
     const failureBlocks = collectUnexpectedFailureBlocks(output);
     const secondaryHarnessSignature = firstRealFailure !== undefined ? detectSecondaryHarnessNoise(output) : undefined;
+    // Checked BEFORE signature detection: a suite that ran clean
+    // and then died in KNOWN upstream teardown noise is a PASS, not a crash.
+    // The teardown traceback matches the startup-traceback cluster, and the
+    // existing green-summary veto over that cluster requires a `SUITE_END`
+    // marker — which this very traceback is what prevents from printing. So
+    // a substantively green suite (`Ran N checks` / `Unexpected results: 0`,
+    // no unexpected lines) was reported CRASH, indistinguishable at the
+    // summary level from a red run. Every hard-evidence veto still applies:
+    // a crash marker, a non-zero unexpected count, any real TEST-UNEXPECTED
+    // line, the shutdown-re-entry shape, or a requested file that never
+    // started keeps the run failing. Only the missing shutdown marker is
+    // forgiven, and only when the recognized teardown traceback explains it.
+    if (isGreenSuiteEndedByKnownTeardownNoise(output, counts, realFailures, requestedPaths)) {
+        return { kind: 'tests-ran-ok', note: 'harness teardown noise ignored', ...counts };
+    }
     const signature = detectHarnessCrashSignature(output);
     if (signature) {
         return { kind: 'harness-crash', signature, ...counts };
@@ -505,6 +521,40 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
         ...(secondaryHarnessSignature !== undefined ? { secondaryHarnessSignature } : {}),
     };
 }
+/**
+ * True when the capture shows a substantively GREEN suite whose only
+ * unexplained residue is the recognized mozsystemmonitor teardown
+ * traceback.
+ *
+ * Requires, all of them: tests actually executed; the summary printed
+ * `Ran N checks` with an explicit `Unexpected results: 0`; no non-zero
+ * unexpected count anywhere; no real `TEST-UNEXPECTED-*`/assertion line;
+ * no crash marker; every requested test file both started and ended; and
+ * the recognized teardown traceback is present. Anything short of that
+ * falls through to the normal (failing) chain.
+ */
+function isGreenSuiteEndedByKnownTeardownNoise(output, counts, realFailures, requestedPaths) {
+    if (!hasKnownTeardownNoise(output))
+        return false;
+    if (!hasExecutionSignal(output))
+        return false;
+    if (counts.checks === undefined || counts.unexpected !== 0)
+        return false;
+    if (!GREEN_UNEXPECTED_SUMMARY_PATTERN.test(output))
+        return false;
+    if (NONZERO_UNEXPECTED_SUMMARY_PATTERN.test(output))
+        return false;
+    if (realFailures.length > 0)
+        return false;
+    if (findCrashMarkerLine(output) !== undefined)
+        return false;
+    // The post-green shutdown re-entry shape is deliberately a crash verdict
+    // on an otherwise-green log; it must not be swept up here.
+    if (SHUTDOWN_REENTRY_PATTERN.test(output))
+        return false;
+    const completeness = analyzeTestCompleteness(output, requestedPaths);
+    return completeness.neverStarted.length === 0 && completeness.neverEnded.length === 0;
+}
 /**
  * Parses the numeric counts from the harness's embedded result summary
  * (`Ran N checks` / `Unexpected results: N`). The LAST occurrence of each
@@ -547,15 +597,16 @@ export function formatFireforgeVerdictLine(verdict, shards) {
     const counts = (verdict.checks !== undefined ? ` checks=${verdict.checks}` : '') +
         (verdict.unexpected !== undefined ? ` unexpected=${verdict.unexpected}` : '');
     const shardSuffix = shards ? ` shards=${shards.passed}/${shards.total}` : '';
+    const note = verdict.note !== undefined ? ` (${verdict.note})` : '';
     if (verdict.kind === 'tests-ran-ok') {
-        return `FIREFORGE-VERDICT: PASS${counts}${shardSuffix}`;
+        return `FIREFORGE-VERDICT: PASS${counts}${shardSuffix}${note}`;
     }
     const reason = verdict.kind === 'harness-crash'
         ? 'crash'
         : verdict.kind === 'no-tests'
             ? 'no-tests'
             : 'test-failures';
-    return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${shardSuffix}`;
+    return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${shardSuffix}${note}`;
 }
 /**
  * Builds the operator-facing failure message for a green-looking summary
@@ -592,21 +643,135 @@ export function buildHarnessCrashMessage(signature, attempts, commandLabel = 'ma
         'If it persists across many runs, inspect the mach virtualenv (mach resyncs psutil on its own; ' +
         'patching it manually does not stick).');
 }
+/**
+ * The three recorded causes of the `timed out … with no output` / `Ran 0
+ * checks` signature, ordered so one stall points at the discriminating
+ * next step. Printed verbatim under the hint.
+ */
+const NO_OUTPUT_STALL_TRIAGE = [
+    '  1. A sleeping or locked display on an unattended HEADED run (macOS). The browser never ' +
+        'paints and never reaches its first test.',
+    '  2. A headless SWGL compositor failure — re-run with --headless to separate this from (1): ' +
+        'if --headless passes, the stall was display/compositor-side, not product-side.',
+    '  3. A broken `chrome://` image on the startup page, which stalls first paint. Run a ' +
+        'known-good control test first; if the control stalls too, the cause is not the test ' +
+        'under investigation.',
+];
 /**
  * Optional hint appended to the harness-crash message when a HEADED run on
- * macOS died at the no-output timeout: the display may have slept and frozen
- * the headed browser before any test started (FORGE F17). Pure — the
- * platform is injected so unit tests need no mocking.
+ * macOS died at the no-output timeout.
+ *
+ * When `displayState` names a MEASURED display state, the hint states it
+ * as fact rather than as one of three possibilities — that is the whole
+ * point of probing: an operator staring at a bare test failure should not
+ * have to rediscover that their machine dimmed. `caffeinate` is described
+ * accurately (it prevents sleep; it cannot wake an already-sleeping
+ * display), because the previous wording sent operators to a command that
+ * could not have helped them.
+ *
+ * Pure — the platform and the probed state are injected so unit tests need
+ * no mocking.
+ *
+ * @param signature - The recognized crash shape
+ * @param context - Run mode, platform, and the probed display state
+ * @returns The hint text, or undefined when the shape does not apply
  */
 export function headedNoOutputTimeoutHint(signature, context) {
     if (context.platform !== 'darwin' || context.headless)
         return undefined;
     if (!signature.reason.includes('no-output timeout'))
         return undefined;
-    return ('Hint: this was a HEADED run on macOS that died at the no-output timeout. ' +
-        'A common cause is the display going to sleep mid-run, which freezes the headed browser ' +
-        'before any test starts. Wrap headed runs in `caffeinate -dimsu <command>` to keep the ' +
-        'display awake, or pass --headless.');
+    const lead = context.displayState === 'asleep'
+        ? 'Hint: this was a HEADED run on macOS and the display was MEASURED ASLEEP ' +
+            '(IODisplayWrangler below its awake power state). A headed browser on a sleeping ' +
+            'display never paints and never starts a test, so this stall is environmental — not a ' +
+            'product or test failure.'
+        : context.displayState === 'awake'
+            ? 'Hint: this was a HEADED run on macOS that died at the no-output timeout. The display ' +
+                'was measured AWAKE, so the sleeping-display cause below is ruled out for this run.'
+            : 'Hint: this was a HEADED run on macOS that died at the no-output timeout. The display ' +
+                'state could not be measured, so all three causes below remain open.';
+    const remedy = 'Note that `caffeinate -disu` PREVENTS sleep; it cannot WAKE a display that is already ' +
+        'asleep. Wake the display (or run on an attended machine), or pass --headless.';
+    return `${lead}\n\nKnown causes of this exact signature:\n${NO_OUTPUT_STALL_TRIAGE.join('\n')}\n\n${remedy}`;
+}
+/**
+ * Verdict-line note for a headed no-output stall whose display was
+ * measured asleep. Returned as the parenthetical the verdict line carries,
+ * so the one greppable line an automated consumer reads already names the
+ * environmental cause instead of a bare `FAIL reason=crash`.
+ */
+export function headedDisplayAsleepVerdictNote(signature, context) {
+    if (context.platform !== 'darwin' || context.headless)
+        return undefined;
+    if (context.displayState !== 'asleep')
+        return undefined;
+    if (!signature.reason.includes('no-output timeout'))
+        return undefined;
+    return 'headed run stalled with the display asleep';
+}
+/**
+ * Exit codes that mean "the child died on SIGSEGV": Node reports a
+ * signal-killed child as the negated signal number, while a shell layer
+ * in between reports `128 + signal`. Both shapes reach FireForge
+ * depending on how mach wrapped the harness.
+ */
+const SIGSEGV_EXIT_CODES = new Set([-11, 139]);
+/**
+ * True when a harness run died on SIGSEGV having produced no test evidence
+ * whatsoever.
+ *
+ * `xpcshell return code: -11` with zero output is the signature of an
+ * `.sys.mjs` that a packaged module imports but whose `EXTRA_JS_MODULES`
+ * registration never landed: the module loader faults before any logging
+ * exists, so there is no import error, no stack, no test output — just a
+ * dead process. It is indistinguishable from a genuine product crash
+ * unless someone names the cause.
+ *
+ * "Produced no evidence" is deliberately semantic rather than a byte
+ * budget: no execution signal, no real failure line, and no mozcrash
+ * marker. A run that got far enough to start a test, report a failure, or
+ * leave a crash dump has evidence of its own, and the regular diagnosis
+ * chain reads it — this branch is only for the case where there is
+ * nothing else to say.
+ *
+ * Pure; exported for direct unit testing.
+ *
+ * @param exitCode - The harness process exit code
+ * @param output - Combined stdout/stderr from the run
+ */
+export function isSilentSegfault(exitCode, output) {
+    if (!SIGSEGV_EXIT_CODES.has(exitCode))
+        return false;
+    if (hasExecutionSignal(output))
+        return false;
+    if (realUnexpectedFailureLines(output).length > 0)
+        return false;
+    return findCrashMarkerLine(output) === undefined;
+}
+/**
+ * Names the known cause of a silent SIGSEGV so the operator checks
+ * moz.build registration FIRST instead of paying a full rebuild cycle to
+ * rediscover it.
+ *
+ * @param exitCode - The harness process exit code
+ * @param requestedPaths - Test paths the run requested
+ */
+export function buildSilentSegfaultMessage(exitCode, requestedPaths) {
+    return (`The test harness died on SIGSEGV (exit ${exitCode}) having printed NO output at all.\n\n` +
+        'Known cause, check this FIRST: a `.sys.mjs` imported from a packaged module whose ' +
+        '`EXTRA_JS_MODULES` (or namespaced module list) registration is missing from moz.build. ' +
+        'The module loader faults before any logging exists, so an unregistered module produces ' +
+        'exactly this shape — a dead process with no import error and no stack.\n\n' +
+        'What to do, in order:\n' +
+        '  1. Run `fireforge lint --per-patch`: the unregistered-system-module check names a new ' +
+        'module imported as a resource URL with no moz.build line.\n' +
+        '  2. Run `fireforge verify`: its module-resolution preflight resolves every ' +
+        '`resource:///modules/…` specifier the queue-owned modules import, including imports ' +
+        'added to an EXISTING module — the shape the new-file lint cannot see, and the one that ' +
+        'recurs.\n' +
+        '  3. Only then look for a product crash: a real one prints a crash dump or a stack.\n\n' +
+        `Requested paths: ${requestedPaths.join(', ')}`);
 }
 /**
  * Builds the message for a run that produced no `TEST-START` despite

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

@@ -111,7 +111,7 @@ export declare function formatStaticComponentsRefusal(changedManifests: string[]
 /**
  * Formats the post-mutation advisory printed by `fireforge reset` /
  * `fireforge import` when `components.conf` diverged from the last full
- * build (FORGE F13). Same probe as {@link formatStaticComponentsRefusal},
+ * build. Same probe as {@link formatStaticComponentsRefusal},
  * different moment: this fires at mutation time so the operator learns a
  * full build is needed BEFORE the next gate run refuses.
  */

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

@@ -229,7 +229,7 @@ export function formatStaticComponentsRefusal(changedManifests) {
 /**
  * Formats the post-mutation advisory printed by `fireforge reset` /
  * `fireforge import` when `components.conf` diverged from the last full
- * build (FORGE F13). Same probe as {@link formatStaticComponentsRefusal},
+ * build. Same probe as {@link formatStaticComponentsRefusal},
  * different moment: this fires at mutation time so the operator learns a
  * full build is needed BEFORE the next gate run refuses.
  */

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Category banner and token-declaration helpers for the tokens CSS file
- * (FORGE G3). Split out of `token-manager.ts` to stay inside the per-file
+ *. Split out of `token-manager.ts` to stay inside the per-file
  * line budget.
  *
  * Banner matching is EXACT: the text between the `=` runs (single-line

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

@@ -51,7 +51,7 @@ export interface AddTokenResult {
     /**
      * When the add skipped because the token already lives in the TARGET
      * category, names where the existing base-`:root` declaration sits so
-     * the skip message can point at it (FORGE G3).
+     * the skip message can point at it.
      */
     skippedExisting?: TokenDeclarationLocation;
 }

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

@@ -117,7 +117,7 @@ async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant)
     return { added: true };
 }
 /**
- * Evaluates base-`:root` idempotency for one add (FORGE G3): a token
+ * Evaluates base-`:root` idempotency for one add: a token
  * already declared in the TARGET category skips; a token declared
  * anywhere else in the base block refuses loud — the pre-0.40.0
  * whole-file substring check silently skipped (and discarded
@@ -151,7 +151,7 @@ export async function validateTokenAdd(root, options) {
     validateDarkValue(options);
     // Variant mode targets a `:root<attr>` block, not a category section —
     // but the required --category must still name a REAL category rather
-    // than being silently discarded (FORGE G3 bypass 2).
+    // than being silently discarded (bypass 2).
     if (normalizeVariantOption(options) !== undefined) {
         await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
         return;
@@ -201,7 +201,7 @@ export async function addToken(root, options) {
     // base token is not short-circuited by the global idempotency check.
     if (normalizedVariant !== undefined) {
         // The required --category must name a real category even though the
-        // declaration routes into the variant block (FORGE G3 bypass 2).
+        // declaration routes into the variant block (bypass 2).
         await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
         const { added } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
         return {
@@ -241,7 +241,7 @@ export async function addToken(root, options) {
  * pair the media query with `:root[data-theme="dark"]` /
  * `:root[data-theme="light"]` blocks (viewer-toggle theming) require every
  * themed list to declare identical token sets, so an override add that only
- * wrote the media block was a guaranteed half-finished edit (FORGE F8).
+ * wrote the media block was a guaranteed half-finished edit.
  */
 const THEME_ATTRIBUTE_VARIANTS = [
     { variant: '[data-theme="dark"]', pick: 'dark' },
@@ -298,7 +298,7 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
     const content = await readText(filePath);
     const lines = content.split('\n');
-    // Per-category idempotency (FORGE G3): a declaration in the TARGET
+    // Per-category idempotency: a declaration in the TARGET
     // category skips; a declaration elsewhere in the base :root block
     // throws instead of silently skipping (and silently discarding
     // --create-category).

package/dist/src/core/tree-cow.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Copy-on-write cloning for `fireforge tree` (FORGE G15).
+ * Copy-on-write cloning for `fireforge tree`.
  *
  * Capability is probed BY DOING — a tiny `cp -c` (APFS clonefile) or
  * `cp --reflink=always` (btrfs/XFS) in the actual destination directory —

package/dist/src/core/tree-guard.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Read-only guard for verification trees (FORGE G15).
+ * Read-only guard for verification trees.
  *
  * A tree is a snapshot: its `patches/` and `components/` are copies with
  * no merge-back model, so any command that mutates project or engine
@@ -66,7 +66,7 @@ const TREE_CONDITIONAL_CHECKS = {
     'export-all': ({ options }) => options['dryRun'] === true,
     // Same rule for refreshing existing patches: the dry-run projection is a
     // read (proven side-effect free and runtime-enforced by
-    // withDryRunPurityGuard — FORGE H1/H3); a real re-export writes patches/.
+    // withDryRunPurityGuard); a real re-export writes patches/.
     're-export': ({ options }) => options['dryRun'] === true,
     // `config` with no positional value prints; with a value it writes.
     config: ({ args }) => args.filter((a) => typeof a === 'string').length <= 1,

package/dist/src/core/tree-store.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Verification-tree storage and lifecycle for `fireforge tree` (FORGE G15).
+ * Verification-tree storage and lifecycle for `fireforge tree`.
  *
  * A tree is a FULL project-root CoW snapshot under
  * `.fireforge/trees/<name>` — `getProjectRoot()` walks up from cwd, so

package/dist/src/core/typecheck-shim.d.ts

@@ -15,7 +15,7 @@ export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
  * Loose declarations for Firefox test-harness globals (mochitest
  * browser-chrome and xpcshell), appended AFTER the composed
  * Firefox-globals + consumer shim when `patchLint.checkJsTestFiles`
- * extends the checkJs pass to patch-adopted test scripts (FORGE G5).
+ * extends the checkJs pass to patch-adopted test scripts.
  * Deliberately `any`-typed — the pragmatic posture matches the main
  * shim. A consumer that wants TYPED harness members (so e.g. a call to
  * a method the harness does not declare fails at the patch boundary)
@@ -40,7 +40,7 @@ export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harne
 export declare const SUPPRESSED_DIAGNOSTIC_CODES: ReadonlySet<number>;
 /**
  * Undefined-free-identifier codes, split out of
- * {@link SUPPRESSED_DIAGNOSTIC_CODES} (FORGE F12). Unconditional
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Unconditional
  * suppression let a module reference a name with no import or declaration
  * anywhere and still typecheck with 0 errors — the failure then surfaced
  * as a runtime `ReferenceError`. Both flows now report these at a

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

@@ -133,7 +133,7 @@ declare module 'chrome:*';
  * Loose declarations for Firefox test-harness globals (mochitest
  * browser-chrome and xpcshell), appended AFTER the composed
  * Firefox-globals + consumer shim when `patchLint.checkJsTestFiles`
- * extends the checkJs pass to patch-adopted test scripts (FORGE G5).
+ * extends the checkJs pass to patch-adopted test scripts.
  * Deliberately `any`-typed — the pragmatic posture matches the main
  * shim. A consumer that wants TYPED harness members (so e.g. a call to
  * a method the harness does not declare fails at the patch boundary)
@@ -189,7 +189,7 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
 ]);
 /**
  * Undefined-free-identifier codes, split out of
- * {@link SUPPRESSED_DIAGNOSTIC_CODES} (FORGE F12). Unconditional
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Unconditional
  * suppression let a module reference a name with no import or declaration
  * anywhere and still typecheck with 0 errors — the failure then surfaced
  * as a runtime `ReferenceError`. Both flows now report these at a

package/dist/src/core/typecheck.js

@@ -222,8 +222,18 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         noEmit: true,
         allowJs: parsed.options.allowJs ?? true,
         checkJs: parsed.options.checkJs ?? true,
+        // No incremental sidecar, ever. A user jsconfig under `engine/` that
+        // sets `incremental` (or names a `tsBuildInfoFile`)
+        // would have this command drop a `.tsbuildinfo` inside the primary
+        // engine checkout — a second writer that invalidates a concurrent
+        // `fireforge test`'s engine fingerprint. This command emits nothing,
+        // so the sidecar buys nothing either.
+        incremental: false,
         // skipLibCheck is not forced; the user owns it via their jsconfig.
     };
+    // `exactOptionalPropertyTypes` forbids assigning `undefined` to an
+    // optional `string`, so the sidecar path is dropped rather than unset.
+    delete options.tsBuildInfoFile;
     // 5) The synthetic shim file. Use a project-rooted path with a
     // hidden-style prefix so it is unlikely to collide with any real
     // file — and never write it to disk. The CompilerHost below serves

package/dist/src/core/xpcshell-profile-dir.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Per-invocation xpcshell profile directory (FORGE G15b).
+ * Per-invocation xpcshell profile directory.
  *
  * Firefox's xpcshell harness defaults `XPCSHELL_TEST_PROFILE_DIR` to a
  * FIXED path (`$TMPDIR/firefox/xpcshellprofile`), so two overlapping

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

@@ -25,6 +25,27 @@ export declare abstract class FireForgeError extends Error {
 export declare class GeneralError extends FireForgeError {
     readonly code: 1;
 }
+/**
+ * Raised when one of FireForge's own internal invariants did not hold —
+ * the failure of a runtime assertion from `src/utils/assert.ts`.
+ *
+ * Dedicated subclass (rather than raw GeneralError) because an invariant
+ * failure is categorically different from every other error the CLI
+ * raises: it is a bug in FireForge, not something the operator did or can
+ * fix. That difference is worth carrying all the way to the exit status
+ * (see {@link ExitCode.INTERNAL_ERROR}) so a CI job can escalate it
+ * instead of retrying it, and it is the one error class the CLI boundary
+ * prints a stack trace for — the stack is the report.
+ *
+ * Assertions exist so that a violated invariant stops the run at the
+ * first inconsistency instead of continuing to write. In the mutating
+ * paths that means the surrounding rollback journal restores the engine
+ * before this reaches the operator; see `docs/lifecycle-invariants.md`.
+ */
+export declare class InternalInvariantError extends FireForgeError {
+    readonly code: 11;
+    get userMessage(): string;
+}
 /**
  * Raised when a legacy regex/brace-depth fallback parser decides it
  * cannot safely perform its mutation — e.g. because a block it expected
@@ -85,7 +106,7 @@ export declare class ExecTimeoutError extends FireForgeError {
 }
 /**
  * Error thrown when a file-lock wait times out because another process
- * holds the lock (FORGE H5).
+ * 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

package/dist/src/errors/base.js

@@ -36,6 +36,37 @@ export class FireForgeError extends Error {
 export class GeneralError extends FireForgeError {
     code = ExitCode.GENERAL_ERROR;
 }
+/**
+ * Raised when one of FireForge's own internal invariants did not hold —
+ * the failure of a runtime assertion from `src/utils/assert.ts`.
+ *
+ * Dedicated subclass (rather than raw GeneralError) because an invariant
+ * failure is categorically different from every other error the CLI
+ * raises: it is a bug in FireForge, not something the operator did or can
+ * fix. That difference is worth carrying all the way to the exit status
+ * (see {@link ExitCode.INTERNAL_ERROR}) so a CI job can escalate it
+ * instead of retrying it, and it is the one error class the CLI boundary
+ * prints a stack trace for — the stack is the report.
+ *
+ * Assertions exist so that a violated invariant stops the run at the
+ * first inconsistency instead of continuing to write. In the mutating
+ * paths that means the surrounding rollback journal restores the engine
+ * before this reaches the operator; see `docs/lifecycle-invariants.md`.
+ */
+export class InternalInvariantError extends FireForgeError {
+    code = ExitCode.INTERNAL_ERROR;
+    get userMessage() {
+        return (`Internal error: ${this.message}\n\n` +
+            'This is a bug in FireForge itself, not a problem with your project — ' +
+            'no configuration change on your side would have prevented it. The ' +
+            'operation stopped at the first inconsistency rather than continuing ' +
+            'to write.\n\n' +
+            'To report this:\n' +
+            '  1. Keep the full output above, including the stack trace.\n' +
+            '  2. Note the command you ran and what the project looked like at the time.\n' +
+            '  3. Open an issue at https://github.com/HominisBrowser/FireForge/issues');
+    }
+}
 /**
  * Raised when a legacy regex/brace-depth fallback parser decides it
  * cannot safely perform its mutation — e.g. because a block it expected
@@ -115,7 +146,7 @@ export class ExecTimeoutError extends FireForgeError {
 }
 /**
  * Error thrown when a file-lock wait times out because another process
- * holds the lock (FORGE H5).
+ * 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

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

@@ -25,6 +25,16 @@ export declare const ExitCode: {
     readonly FURNACE_ERROR: 9;
     /** Patch conflict resolution error */
     readonly RESOLUTION_ERROR: 10;
+    /**
+     * An internal invariant did not hold — a bug in FireForge itself, not a
+     * user or environment failure. Distinct from GENERAL_ERROR because the
+     * two call for opposite responses: a GENERAL_ERROR usually means the
+     * operator must change something (fix a config, free a lock, retry), and
+     * an INTERNAL_ERROR means nothing the operator can change would have
+     * helped and the run should be reported instead. Scripts and CI that
+     * retry on failure want to retry the former and escalate the latter.
+     */
+    readonly INTERNAL_ERROR: 11;
     /**
      * `fireforge run --smoke-exit` observed one or more unallowed console
      * error lines inside the smoke window. Distinct from BUILD_ERROR so CI

package/dist/src/errors/codes.js

@@ -26,6 +26,16 @@ export const ExitCode = {
     FURNACE_ERROR: 9,
     /** Patch conflict resolution error */
     RESOLUTION_ERROR: 10,
+    /**
+     * An internal invariant did not hold — a bug in FireForge itself, not a
+     * user or environment failure. Distinct from GENERAL_ERROR because the
+     * two call for opposite responses: a GENERAL_ERROR usually means the
+     * operator must change something (fix a config, free a lock, retry), and
+     * an INTERNAL_ERROR means nothing the operator can change would have
+     * helped and the run should be reported instead. Scripts and CI that
+     * retry on failure want to retry the former and escalate the latter.
+     */
+    INTERNAL_ERROR: 11,
     /**
      * `fireforge run --smoke-exit` observed one or more unallowed console
      * error lines inside the smoke window. Distinct from BUILD_ERROR so CI