@hominis/fireforge 0.44.4 → 0.45.0

package/dist/src/core/test-stall-triage.js

@@ -38,33 +38,51 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  *    its manifest from `server.js` on 8888, and a survivor of an
  *    interrupted run keeps the port. Its probe is exact, and the preflight
  *    in `mochitest-server-port.ts` now refuses it before a run starts.
- *  - (3) is a single downstream report (one consumer, 3/3 reproduce and 3/3
- *    restore on one variable) whose MECHANISM was never root-caused. It is
- *    stated as the correlation it is. An earlier revision asserted "stalls
- *    first paint" as fact; that was a causal story written on top of the
- *    correlation, and a doubtful one — a failed image load in Gecko fires
- *    `error` and does not gate the document load event, and the harness's
- *    browser-ready handshake does not wait on image decode. Do not restore
- *    a mechanism claim here without a root cause to cite.
+ *  - (3) is now MECHANICAL and root-caused, replacing the correlation an
+ *    earlier revision recorded. A `chrome://` (or `resource://`) URL that
+ *    resolves to nothing reaches `CheckForBrokenChromeURL`
+ *    (netwerk/base/nsNetUtil.cpp), which outside automation only
+ *    `printf_stderr`s `Missing chrome or resource URL: <uri>` — but under
+ *    `xpc::IsInAutomation()` the same condition is
+ *    `MOZ_CRASH_UNSAFE_PRINTF("Missing chrome or resource URLs: %s")`. A
+ *    downstream reproduction symbolicated the faulting frame as
+ *    `CheckForBrokenChromeURL`, which is the established diagnosis the bar
+ *    in `mach-error-hints.ts` asks for. The discredited "stalls first
+ *    paint" story an even earlier revision asserted must not come back: a
+ *    failed image load in Gecko fires `error` and does not gate the
+ *    document load event.
  *
- * Detection (a named signature, as with the module-resolution SIGSEGV) is
- * not specified for (3) because no log line is known to key on. The bar for
- * adding one is the bar `mach-error-hints.ts` states: an established
- * diagnosis, never a plausible guess.
+ * Detection by log line is deliberately NOT specified for (3), and the
+ * reason is the mechanism itself: in the reproduction the crash landed in a
+ * CONTENT process (`plugin-container`, a child of the browser) with the
+ * crash reporter compiled out, so the harness log carried neither the crash
+ * message nor a crash line — only the no-output timeout, `Ran 0 checks`,
+ * and mochitest's "Can't trigger Breakpad, just killing process". Under
+ * automation the message is in the process that DIED, not in the log, so
+ * the census points at the two artefacts that do carry it: the OS crash
+ * report (whose faulting frame names `CheckForBrokenChromeURL`) and the
+ * out-of-automation smoke probe (which prints the non-crashing spelling
+ * and, since 0.45.0, counts it as an unallowed error so the exit code
+ * agrees with the capture).
  */
 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. Product-side startup: the browser never reaches the state the harness waits for. One ' +
-        'downstream report correlates this stall with a broken `chrome://` image URI on the ' +
-        'startup page (reproduced and un-reproduced on that one variable); the mechanism was ' +
-        'never root-caused, so treat it as a lead, not an explanation. Discriminate with ' +
+    '  3. A broken `chrome://` or `resource://` URL reached from the startup document. Under ' +
+        'automation this is a MOZ_CRASH in whichever process opened the channel ' +
+        '(CheckForBrokenChromeURL, netwerk/base/nsNetUtil.cpp), so the browser dies before the ' +
+        'harness sees anything. Expect the log to name NOTHING: with the crash in a content ' +
+        'process and the crash reporter compiled out, the only artefacts are the OS crash report ' +
+        '(macOS: ~/Library/Logs/DiagnosticReports/plugin-container-*.ips — the faulting frame ' +
+        'reads CheckForBrokenChromeURL) and the smoke probe below. Discriminate with ' +
         '"fireforge run --smoke-exit 60 --headless --capture-console <file>", which launches the ' +
-        'same browser OUTSIDE the test harness: a clean window with no unallowed console errors ' +
-        'means product-side startup is healthy and the stall is harness- or test-side; a hang, a ' +
-        'non-zero exit, or console errors in <file> put it in the startup document.',
+        'same browser OUTSIDE automation, where the same condition only PRINTS ' +
+        '"Missing chrome or resource URL: <uri>" — a line the probe counts as an unallowed ' +
+        'error, so its exit code and its capture now agree. A clean window with no unallowed ' +
+        'console errors means product-side startup is healthy and the stall is harness- or ' +
+        'test-side.',
     '  4. A stale mochitest httpd holding the harness server port (127.0.0.1:8888). A fresh ' +
         "browser connects to THAT server, which cannot serve this run's manifest, so the run " +
         'stalls before TEST_START. Probe with "lsof -nP -iTCP:8888": any listener that is not ' +

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

@@ -9,6 +9,34 @@ export declare class BuildError extends FireForgeError {
     constructor(message: string, command?: string | undefined, cause?: Error);
     get userMessage(): string;
 }
+/**
+ * A test SUITE went red — assertions failed, or sharded runs did not all
+ * pass. Distinct from its {@link BuildError} parent only in what it TELLS
+ * the operator, deliberately not in its exit code: `docs/exit-codes.md`
+ * documents 5 as "a suite that FAILED", and consumers key CI on it.
+ *
+ * The parent's remedies are all build remedies — "check the build output",
+ * "fireforge bootstrap", "delete obj-* directories" — and none of them apply
+ * to a failing assertion. Worse, the first points at the wrong half of the
+ * log, which is exactly the half a `tail` keeps. Ground truth for a test red
+ * is the harness's own output, so the remedies here name the failing tests,
+ * the `FIREFORGE-VERDICT:` line, and the run log that survives a pipe.
+ *
+ * Note that `machineErrorCode` derives the `--json` error code from the class
+ * name, so this reports as `test-failure` rather than `build`.
+ */
+export declare class TestFailureError extends BuildError {
+    /** Rendered TEST-UNEXPECTED blocks, when the verdict carried any. */
+    readonly failureBlocks?: string | undefined;
+    /** The run's complete raw log, when one was opened. */
+    readonly logPath?: string | undefined;
+    constructor(message: string, command?: string, 
+    /** Rendered TEST-UNEXPECTED blocks, when the verdict carried any. */
+    failureBlocks?: string | undefined, 
+    /** The run's complete raw log, when one was opened. */
+    logPath?: string | undefined);
+    get userMessage(): string;
+}
 /**
  * Error thrown when mach is not available.
  */

package/dist/src/errors/build.js

@@ -23,6 +23,55 @@ export class BuildError extends FireForgeError {
         return msg;
     }
 }
+/**
+ * A test SUITE went red — assertions failed, or sharded runs did not all
+ * pass. Distinct from its {@link BuildError} parent only in what it TELLS
+ * the operator, deliberately not in its exit code: `docs/exit-codes.md`
+ * documents 5 as "a suite that FAILED", and consumers key CI on it.
+ *
+ * The parent's remedies are all build remedies — "check the build output",
+ * "fireforge bootstrap", "delete obj-* directories" — and none of them apply
+ * to a failing assertion. Worse, the first points at the wrong half of the
+ * log, which is exactly the half a `tail` keeps. Ground truth for a test red
+ * is the harness's own output, so the remedies here name the failing tests,
+ * the `FIREFORGE-VERDICT:` line, and the run log that survives a pipe.
+ *
+ * Note that `machineErrorCode` derives the `--json` error code from the class
+ * name, so this reports as `test-failure` rather than `build`.
+ */
+export class TestFailureError extends BuildError {
+    failureBlocks;
+    logPath;
+    constructor(message, command, 
+    /** Rendered TEST-UNEXPECTED blocks, when the verdict carried any. */
+    failureBlocks, 
+    /** The run's complete raw log, when one was opened. */
+    logPath) {
+        super(message, command);
+        this.failureBlocks = failureBlocks;
+        this.logPath = logPath;
+    }
+    get userMessage() {
+        let msg = `Test Failure: ${this.message}`;
+        if (this.command) {
+            msg += `\n\nCommand: ${this.command}`;
+        }
+        if (this.failureBlocks) {
+            msg += `\n\n${this.failureBlocks}`;
+        }
+        msg += '\n\nTo fix this:\n';
+        msg += this.failureBlocks
+            ? '  1. Fix the failing assertions listed above, then re-run just those test paths\n'
+            : '  1. Find the TEST-UNEXPECTED-FAIL lines in the output above — they name what broke\n';
+        msg +=
+            '  2. Read the "FIREFORGE-VERDICT:" line for the run\'s ground truth (checks, unexpected)\n';
+        msg +=
+            this.logPath !== undefined
+                ? `  3. The complete raw output is at ${this.logPath} — it survives a piped/tailed terminal`
+                : '  3. Re-run without piping the output, so the failure lines are not cut off by "tail"';
+        return msg;
+    }
+}
 /**
  * Error thrown when mach is not available.
  */

package/dist/src/types/commands/options.d.ts

@@ -322,6 +322,16 @@ export interface ReExportOptions {
      * else still refuses.
      */
     expect?: string[];
+    /**
+     * Engine-relative files that are an APPROVED unmanaged exception
+     * (`--expect-unmanaged`, repeatable; requires
+     * `--refuse-adjacent-unmanaged`). The adjacency refusal is all-or-nothing
+     * without it: a project with a reviewed, deliberately unmanaged path beside
+     * a patch's ownership has to drop the flag entirely and hand-read the
+     * notice, which is a weaker belt than the one being disarmed. Approved
+     * paths are still LISTED — they are carved out of the refusal, not hidden.
+     */
+    expectUnmanaged?: string[];
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -601,6 +611,15 @@ export interface TestOptions {
     marionettePort?: number;
     /** Kill a recognized stale browser process holding the Marionette port, then continue. */
     killStaleMarionette?: boolean;
+    /**
+     * Terminate harness helper processes (`xpcshell` httpd, `pywebsocket`,
+     * `ssltunnel`, `moz-http2`) that survived an earlier run in this
+     * project's objdir. The census itself runs on EVERY test dispatch and is
+     * report-only; this flag opts into the kill. Survivors slow later runs
+     * without appearing in their output, so the visibility is the default and
+     * the termination is the choice.
+     */
+    reapOrphans?: boolean;
     /** Permit tests against packageable engine edits newer than the last successful build. */
     allowStaleBuild?: boolean;
     /**

package/dist/src/types/commands/patches.d.ts

@@ -32,13 +32,24 @@ export interface PatchResult {
     /** Whether the patch was auto-resolved (new file vs existing file conflict) */
     autoResolved?: boolean;
     /**
-     * Pre-existing content of files the auto-resolve overwrote, keyed by
-     * engine-relative path. Kept for the RUN's duration (not just the retry):
-     * if a later patch fails and `rollbackPatches` reverse-applies this one,
-     * reversing a new-file patch DELETES the file — these snapshots are the
-     * only way to restore what was there before the auto-resolve.
+     * Pre-existing BYTES of files the auto-resolve overwrote (or, for a binary
+     * new file, removed), keyed by engine-relative path. Kept for the RUN's
+     * duration (not just the retry): if a later patch fails and
+     * `rollbackPatches` reverse-applies this one, reversing a new-file patch
+     * DELETES the file — these snapshots are the only way to restore what was
+     * there before the auto-resolve.
+     *
+     * Raw bytes rather than decoded text, because the same snapshot has to
+     * restore a binary target byte-for-byte.
+     *
+     * Typed `Uint8Array`, not `Buffer`: this interface is published, and the
+     * emitted `.d.ts` naming a Node global made a consumer without
+     * `@types/node` fail to compile against the package (`TS2591` in the
+     * pack smoke test). Every `Buffer` assigns to it — `Buffer` extends
+     * `Uint8Array` — and `fs.writeFile` accepts it, so nothing at the call
+     * sites changes.
      */
-    autoResolvedOriginals?: Map<string, string>;
+    autoResolvedOriginals?: Map<string, Uint8Array>;
 }
 /**
  * Extended patch information with metadata.

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

@@ -226,6 +226,35 @@ export interface PatchLintCheckJsCompilerOptions {
     /** Module-resolution `paths` mapping (pattern → targets, engine-relative). */
     paths?: Record<string, string[]>;
 }
+/**
+ * Line-count thresholds for one `file-too-large` tier.
+ *
+ * Every field is optional; an omitted field keeps the built-in default.
+ * The three must stay ordered `notice <= warning <= error`, which the
+ * config validator enforces — an out-of-order triple silently disables a
+ * band rather than failing anything.
+ */
+export interface PatchLintFileSizeTier {
+    notice?: number;
+    warning?: number;
+    error?: number;
+}
+/**
+ * Overrides for the `file-too-large` thresholds, per file class.
+ *
+ * These were module constants until 0.45.0, and nothing in `fireforge.json`
+ * could move them. That is a problem specifically because the recommended
+ * gate posture is `--max-warnings 0`: under it the `warning` band is not a
+ * soft limit at all, so a project whose controllers legitimately sit a few
+ * lines over 750 has a hard failure with no dial, at exactly the moment
+ * someone is deciding whether to restructure a file.
+ */
+export interface PatchLintFileSizeThresholds {
+    /** Non-test files. Defaults: notice 500, warning 750, error 900. */
+    general?: PatchLintFileSizeTier;
+    /** Test files. Defaults: notice 1200, warning 1400, error 1600. */
+    test?: PatchLintFileSizeTier;
+}
 /**
  * Configuration for patch lint rules.
  */
@@ -272,6 +301,18 @@ export interface PatchLintConfig {
     checkJsTestShim?: string;
     /** File paths exempt from the raw-color-value check (exact or basename match) */
     rawColorAllowlist?: string[];
+    /**
+     * Per-tier overrides for the `file-too-large` line-count thresholds.
+     * Unset fields keep the built-in defaults.
+     */
+    fileSizeThresholds?: PatchLintFileSizeThresholds;
+    /**
+     * Run the project's Prettier over patch-owned `.sys.mjs` modules, from
+     * inside `engine/` so the engine's own `.prettierrc*`/`.prettierignore`
+     * decide. Default `'off'`: when off, formatting is explicitly out of
+     * scope for the per-patch tier.
+     */
+    prettier?: PatchLintSeverityGate;
     /** Enforce JSDoc on class-method exports in patch-owned .sys.mjs files. Default: 'off'. */
     jsdocClassMethods?: PatchLintSeverityGate;
     /** Require ≥1 assertion in any patch-touched browser_*.js test file (new or modified). Default: 'off'. */

package/dist/src/utils/fs.d.ts

@@ -76,9 +76,11 @@ export declare function writeTextIfChanged(path: string, content: string): Promi
  * Writes content atomically using a temp-file-and-rename strategy.
  * Temp files are created in the destination directory so rename stays atomic.
  * @param path - Destination file path
- * @param content - Content to write
+ * @param content - Content to write. `Uint8Array` rather than `Buffer` so
+ *   published types never name a Node global (every `Buffer` still assigns
+ *   to it, and `fs.writeFile` accepts both).
  */
-export declare function writeFileAtomic(path: string, content: string | Buffer): Promise<void>;
+export declare function writeFileAtomic(path: string, content: string | Uint8Array): Promise<void>;
 /**
  * Copies a directory recursively.
  * @param src - Source directory path

package/dist/src/utils/fs.js

@@ -165,7 +165,9 @@ export async function writeTextIfChanged(path, content) {
  * Writes content atomically using a temp-file-and-rename strategy.
  * Temp files are created in the destination directory so rename stays atomic.
  * @param path - Destination file path
- * @param content - Content to write
+ * @param content - Content to write. `Uint8Array` rather than `Buffer` so
+ *   published types never name a Node global (every `Buffer` still assigns
+ *   to it, and `fs.writeFile` accepts both).
  */
 export async function writeFileAtomic(path, content) {
     await ensureParentDir(path);

package/docs/configuration.md

@@ -7,6 +7,24 @@
 whose behaviour needs more than a schema line, plus the environment variables
 FireForge reads.
 
+## `firefox` — the source pin
+
+`firefox.version` (with `firefox.product`, and optionally `firefox.sha256` and
+`firefox.candidate`) is the source pin `fireforge download` resolves an archive
+from. `fireforge source set` writes it.
+
+The pin lives in `fireforge.json` beside hand-maintained policy sections, which
+is worth knowing when reverting that file: `git checkout -- fireforge.json`
+after an accidental reformat also reverts an **uncommitted** pin, and the tree
+is then building a different version than the config claims.
+
+`fireforge doctor` reports the pin beside what the checkout actually is — the
+engine's own `browser/config/version.txt` and the version the last download
+recorded — and warns when they disagree. It is a report, not a lock: a tree
+may legitimately be mid-migration. `product`, `sha256` and `candidate` have no
+recorded counterpart on disk, so the check does not claim to have verified
+them.
+
 ## External toolchains
 
 Projects with generated asset prerequisites can declare opt-in
@@ -33,6 +51,35 @@ shim that tracks upstream WebIDL additions per release.
 - `patchLint.checkJsTestShim` points at a project `.d.ts` whose typed
   declarations (e.g. a real `TestUtils` interface) override the loose
   baseline, so calls to nonexistent harness members fail at export time.
+- `patchLint.prettier` (`'off'` | `'warning'` | `'error'`, default `'off'`)
+  runs the project's configured Prettier over patch-owned `.sys.mjs`
+  modules. It runs from inside `engine/`, so `engine/.prettierrc*` and
+  `engine/.prettierignore` decide — the same command run from the repo root
+  can report a false pass when the root `.prettierignore` excludes
+  `engine/`. Prettier is resolved from `engine/node_modules`, then the
+  project's, then `npx --no-install`. **Left `'off'`, formatting is out of
+  scope for the per-patch tier**; no other tier checks `.sys.mjs`
+  formatting either.
+- `patchLint.fileSizeThresholds` tunes the `file-too-large` line counts per
+  file class:
+
+  ```json
+  {
+    "patchLint": {
+      "fileSizeThresholds": {
+        "general": { "notice": 500, "warning": 800, "error": 900 },
+        "test": { "warning": 1500 }
+      }
+    }
+  }
+  ```
+
+  Every field is optional and merges over the defaults (general
+  `500/750/900`, test `1200/1400/1600`). The merged triple must satisfy
+  `notice <= warning <= error`, which is validated at config load. Note that
+  under the recommended gate posture `--max-warnings 0` the `warning` band is
+  a hard failure, not a soft limit — which is what these thresholds exist to
+  let you move.
 
 ## `patchPolicy`
 

package/docs/exit-codes.md

@@ -14,7 +14,7 @@ they mean and which class produces each.
 |    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                     | `ConfigError` and subclasses                                   |
 |    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                            | `DownloadError` and subclasses                                 |
 |    4 | `GIT_ERROR`            | A git operation failed.                                                                                                  | `GitError` and subclasses                                      |
-|    5 | `BUILD_ERROR`          | `mach build` failed.                                                                                                     | `BuildError` and subclasses                                    |
+|    5 | `BUILD_ERROR`          | `mach build` failed, or a test suite went red.                                                                           | `BuildError` and subclasses, `TestFailureError`                |
 |    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                        | `PatchError`                                                   |
 |    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                       | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError` |
 |    8 | `INVALID_ARGUMENT`     | The flags were wrong. Usage problem, not an environment one.                                                             | `InvalidArgumentError`                                         |
@@ -35,7 +35,9 @@ change would have helped — escalate it, do not retry.
 
 **Red vs never-ran vs thrown-away.** These are three different facts and,
 before 0.44.0, two of them shared exit 1. `BUILD_ERROR` (5) is a suite that
-FAILED. `LOCK_TIMEOUT` (15) is a run that never started, because another
+FAILED — thrown as `TestFailureError` since 0.45.0, which keeps the code but
+carries test remedies rather than build ones (`--json` reports it as
+`test-failure`). `LOCK_TIMEOUT` (15) is a run that never started, because another
 FireForge process held the lock for the whole budget — nothing about the
 request was wrong, so re-queue it. `INCONCLUSIVE` (14) is a suite whose
 result was DISCARDED, because `engine/` moved underneath it — the code may

package/docs/testing.md

@@ -49,8 +49,13 @@ components):
 - a changed `moz.build` / `moz.configure` / `Makefile.in` runs
   `mach configure` first;
 - a changed `jar.mn` escalates the whole build to a full `mach build`
-  (minutes rather than seconds), so that new install-manifest destinations
-  exist before the run.
+  (minutes rather than seconds) **only** when it is a NEW manifest
+  (untracked in the engine repo, so no install manifest exists for it yet)
+  or when its jar declaration carries a bracketed base-directory prefix,
+  which redirects the install destination away from the default chrome
+  root. An entry added to an existing `dist/bin` manifest no longer
+  escalates. Any probe failure (unreadable manifest, no git) escalates, and
+  the notice names the manifest and the reason.
 
 Each escalation is paid once per actual content change: a `jar.mn` that is
 dirty against HEAD but byte-identical to what the last full build consumed
@@ -60,20 +65,35 @@ carried forward from the previous full build, so a registration made
 between a `build --ui` and the next `test --build` still triggers the full
 build once.
 
-Whether a full build is really required for an entry added to an existing
-`jar.mn` under `dist/bin` is an open question, recorded in the 0.44.0
-changelog: mozbuild regenerates its backend from a newer `jar.mn` on any
-`mach build`, `faster` included, and the FasterMake backend consumes
-`dist/bin` jar manifests. The escalation stays until that is demonstrated
-end to end against a real objdir (`build --ui` after a jar-only
-registration, then a plain `test`), because relaxing a stale-artifact guard
-on source reading alone trades a slow build for a silently wrong test.
+The open question the 0.44.0 changelog recorded here — whether a full build
+is really required for an entry added to an existing `dist/bin` `jar.mn` —
+was settled downstream by exactly the experiment that entry asked for: two
+clean runs where a jar-only registration of a new content file was
+installed by a plain `fireforge build --ui`
+(`faster/install_dist_bin_browser` named the destination, the file reached
+`dist/bin` and the `.app` bundle) and fetched over `chrome://` by a plain
+`fireforge test`. That case no longer escalates. The two halves the
+experiment did NOT exercise — a new `jar.mn` file, and a non-default
+install destination — still do, for the reason the original entry gives:
+relaxing a stale-artifact guard without evidence trades a slow build for a
+silently wrong test.
 
 ## Resilience
 
 - Recognized harness crashes retry up to `--harness-retries <n>` times
   (default 2).
 - `--kill-stale-marionette` terminates recognized stale browsers.
+- Every dispatch runs a **census of orphaned harness helpers** — `xpcshell`
+  (the harness httpd), `pywebsocket`, `ssltunnel`, `moz-http2` — that
+  survived an earlier run in this project's objdir. It runs at preflight,
+  before this run spawns anything, so every hit is a survivor by
+  construction; a match must be objdir-anchored, since `xpcshell` and
+  `server.js` are far too generic to report on their own. Survivors slow
+  every later run without appearing in its output (a three-second suite
+  taking minutes of wall clock is the usual symptom). Report-only by
+  default; `--reap-orphans` terminates them. It never refuses a run.
+  A different shape — reparented Python `multiprocessing` workers — is
+  covered by the `Orphaned harness workers` doctor check.
 - `--perf-samples <path>` publishes a perf-sample artifact path to the
   harness (exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
 
@@ -109,6 +129,38 @@ the build path stays quiet. It is opt-in rather than automatic because it
 changes how much a third party prints, and an operator who wants the quieting
 should keep it.
 
+## Known upstream teardown noise
+
+Recent engines can end a run with a Python traceback at harness teardown:
+
+```
+AttributeError: 'SystemResourceMonitor' object has no attribute 'stop_time'
+```
+
+(or `poll_interval`), raised from `mozsystemmonitor/resourcemonitor.py`. It is
+an upstream defect in the resource monitor's own shutdown, it is cosmetic, and
+it does not affect any verdict. It matters only because it lands exactly where
+a reader looks for the failure summary.
+
+FireForge recognizes this one signature — and only this one. Recognition
+requires **all** of: an `AttributeError` on `SystemResourceMonitor` naming one
+of those two attributes, a `resourcemonitor.py` stack frame, and (in a test
+run) a preceding `SUITE_END`. A novel attribute, a different exception, or the
+same traceback before shutdown is treated as a real failure and printed
+verbatim, always.
+
+The two phases handle it differently, deliberately:
+
+- **Tests** collapse the traceback in the terminal echo to one labeled
+  `[FireForge]` line. Captures and the run log keep the **raw** traceback, and
+  the classifier reads the raw form — a real failure always outranks this
+  signature in diagnosis.
+- **Builds** print it verbatim and add a note naming it. A build has no
+  `SUITE_END` — no boundary separating teardown from work still in progress —
+  so FireForge cannot distinguish cosmetic teardown noise from a real
+  build-time traceback there, and withholding the block would be the wrong
+  risk to take.
+
 ## Concurrency
 
 A test run holds the engine-session lock and snapshots the engine git

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.44.4",
+  "version": "0.45.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",