@hominis/fireforge 0.44.3 → 0.45.0

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

@@ -66,13 +66,30 @@ export declare const FULL_SUITE_REQUEST = "(entire suite)";
  */
 export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
 /**
- * Formats the refusal shown when a non-`--build` run requests paths the
- * packaged runtime's scoped `test --build` coverage does not include —
- * enforced on every such run, with or without `--allow-stale-build`. Kept
- * separate from the matcher so tests can pin structure and copy
- * independently (same split as {@link formatStaleBuildWarning}).
+ * Test manifests changed since the recorded build that sit in (or above)
+ * the directory of an uncovered request path — i.e. the manifests that
+ * EXPLAIN why this run needs coverage the build never claimed.
+ *
+ * Best-effort: a probe failure returns an empty list, so the refusal
+ * degrades to exactly its previous text rather than failing differently.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param baseline - Last successful build's baseline
+ * @param uncovered - Uncovered request paths from
+ *   {@link findUncoveredRequestPaths}
+ * @returns Engine-relative manifest paths, capped at
+ *   {@link STALE_PATHS_LIMIT}
+ */
+export declare function findChangedTestManifestsForPaths(engineDir: string, baseline: BuildBaseline | undefined, uncovered: readonly string[]): Promise<string[]>;
+/**
+ * @param uncovered - Request paths the recorded packaging does not cover
+ * @param coverage - The recorded scoped coverage claim
+ * @param changedManifests - Test manifests changed since the recorded
+ *   build that explain an uncovered path (from
+ *   {@link findChangedTestManifestsForPaths}); omitted or empty renders
+ *   nothing
  */
-export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[]): string;
+export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[], changedManifests?: readonly string[]): string;
 /** Result of the compiled-StaticComponents staleness probe. */
 export interface StaticComponentsStaleResult {
     /** True when at least one `components.conf` genuinely diverged from the anchor. */

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

@@ -27,7 +27,7 @@ import { verbose, warn } from '../utils/logger.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
-import { collectChangedEnginePaths } from './engine-changes.js';
+import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
 export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
@@ -60,18 +60,7 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     // and the stale check fires immediately after a successful one. The
     // fingerprints capture "these files had this content when the build ran";
     // a path stays stale only when its live hash diverges.
-    const fingerprints = baseline.packageableFingerprints;
-    if (fingerprints) {
-        const staleAfterHashCheck = [];
-        for (const path of packageable) {
-            const recorded = fingerprints[path];
-            const live = await hashEngineFile(engineDir, path);
-            if (recorded === undefined || live === undefined || recorded !== live) {
-                staleAfterHashCheck.push(path);
-            }
-        }
-        packageable = staleAfterHashCheck;
-    }
+    packageable = await dropPathsMatchingFingerprints(engineDir, packageable, baseline.packageableFingerprints);
     if (packageable.length === 0) {
         return { stale: false, changedPaths: [], truncated: 0, baseline };
     }
@@ -158,7 +147,74 @@ function normalizeCoveragePath(path) {
  * separate from the matcher so tests can pin structure and copy
  * independently (same split as {@link formatStaleBuildWarning}).
  */
-export function formatTestCoverageRefusal(uncovered, coverage) {
+/**
+ * Basenames of the test manifests whose entries decide what a packaged test
+ * runtime stages. A manifest that gained an entry is the single most common
+ * reason a run needs coverage the last build never claimed — and it is a
+ * fact FireForge already holds but never said, leaving the operator to
+ * rediscover it after a correct refusal.
+ */
+const TEST_MANIFEST_BASENAMES = new Set([
+    'xpcshell.toml',
+    'xpcshell.ini',
+    'browser.toml',
+    'browser.ini',
+    'mochitest.toml',
+    'mochitest.ini',
+    'chrome.toml',
+    'chrome.ini',
+    'a11y.toml',
+    'a11y.ini',
+]);
+/** True for a test manifest path (by basename). */
+function isTestManifestPath(path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    return TEST_MANIFEST_BASENAMES.has(base);
+}
+/**
+ * Test manifests changed since the recorded build that sit in (or above)
+ * the directory of an uncovered request path — i.e. the manifests that
+ * EXPLAIN why this run needs coverage the build never claimed.
+ *
+ * Best-effort: a probe failure returns an empty list, so the refusal
+ * degrades to exactly its previous text rather than failing differently.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param baseline - Last successful build's baseline
+ * @param uncovered - Uncovered request paths from
+ *   {@link findUncoveredRequestPaths}
+ * @returns Engine-relative manifest paths, capped at
+ *   {@link STALE_PATHS_LIMIT}
+ */
+export async function findChangedTestManifestsForPaths(engineDir, baseline, uncovered) {
+    let changed;
+    try {
+        changed = await collectChangedEnginePaths(engineDir, baseline, 'Coverage refusal');
+    }
+    catch (error) {
+        verbose(`Coverage refusal: manifest probe failed — ${toError(error).message}`);
+        return [];
+    }
+    const requestDirs = uncovered
+        .filter((p) => p !== FULL_SUITE_REQUEST)
+        .map((p) => toManifestGranule(normalizeCoveragePath(p)));
+    const hits = changed.filter((path) => {
+        if (!isTestManifestPath(path))
+            return false;
+        const dir = path.slice(0, Math.max(0, path.lastIndexOf('/')));
+        return requestDirs.some((req) => req === dir || req.startsWith(`${dir}/`));
+    });
+    return hits.slice(0, STALE_PATHS_LIMIT);
+}
+/**
+ * @param uncovered - Request paths the recorded packaging does not cover
+ * @param coverage - The recorded scoped coverage claim
+ * @param changedManifests - Test manifests changed since the recorded
+ *   build that explain an uncovered path (from
+ *   {@link findChangedTestManifestsForPaths}); omitted or empty renders
+ *   nothing
+ */
+export function formatTestCoverageRefusal(uncovered, coverage, changedManifests = []) {
     const cap = (paths) => {
         const head = paths.slice(0, STALE_PATHS_LIMIT);
         const truncated = paths.length - head.length;
@@ -177,10 +233,16 @@ export function formatTestCoverageRefusal(uncovered, coverage) {
     const rebuildHint = rebuildTargets.length > 0
         ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.${extendHint}`
         : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
+    // Why THIS run needs new coverage, when a changed manifest explains it: a
+    // manifest that gained an entry is not covered by a build claim recorded
+    // for other paths, and a browser-chrome claim never covers xpcshell.
+    const manifestLine = changedManifests.length > 0
+        ? ` This run needs coverage the recorded build never claimed because a test manifest changed since it: ${changedManifests.map((m) => `engine/${m}`).join(', ')} — a manifest that gained an entry stages new support fixtures, and a claim recorded for other paths (or another harness) does not cover them.`
+        : '';
     return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\n` +
         `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
         'fixtures for those manifests may be missing from obj-*/_tests/, and the run can hang ' +
-        `rather than fail. ${rebuildHint} ` +
+        `rather than fail.${manifestLine} ${rebuildHint} ` +
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
 /**

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