@hominis/fireforge 0.47.1 → 0.49.0

package/dist/src/utils/process.js

@@ -4,6 +4,7 @@ import { constants as osConstants } from 'node:os';
 import { StringDecoder } from 'node:string_decoder';
 import { ExecTimeoutError } from '../errors/base.js';
 import { buildChildEnv } from './child-env.js';
+import { toError } from './errors.js';
 import { dispatchCompleteLines } from './line-dispatch.js';
 import { killProcessTree, sweepProcessGroup } from './process-group.js';
 // 50 MB cap per stream to prevent OOM. Large toolchain builds (e.g. Firefox, Chromium)
@@ -77,7 +78,8 @@ function collectedOutput(out, err) {
         truncated: out.wasTruncated() || err.wasTruncated(),
     };
 }
-function exitCodeFromClose(code, signal) {
+/** A child's exit code, with a signal death mapped to 128 + its number. */
+export function exitCodeFromClose(code, signal) {
     if (code !== null) {
         return code;
     }
@@ -168,6 +170,7 @@ async function spawnTracked(spec) {
             ? installGracefulShutdownForwarder(child, spec.graceMs, killTarget)
             : undefined;
         const closure = trackChildClosure();
+        let rejection;
         child.on('error', (error) => {
             // Abort/startup failure: make sure a partially-started tree does not
             // outlive the dispatch (a mach dying at startup used to strand
@@ -175,15 +178,24 @@ async function spawnTracked(spec) {
             if (options.processGroup === true) {
                 killProcessTree(child, 'SIGKILL', usesProcessGroup);
             }
-            forwarder?.dispose();
-            closure.settle();
-            reject(toExecRejection(error, command, args, options.timeout, spec.rejectionOutput?.()));
+            // An abort emits error before close. Keep the dispatch tracked until
+            // the child closes and both teardown sweeps finish, including on timeout.
+            rejection = toExecRejection(error, command, args, options.timeout, spec.rejectionOutput?.());
         });
         child.on('close', (code, signal) => {
             forwarder?.dispose();
             const finish = () => {
                 closure.settle();
-                resolve(spec.result(code, signal));
+                if (rejection)
+                    reject(rejection);
+                else {
+                    try {
+                        resolve(spec.result(code, signal));
+                    }
+                    catch (error) {
+                        reject(toError(error));
+                    }
+                }
             };
             // Group sweep first (it takes the helpers that stayed in the group),
             // then the caller's own sweep (the ones that did not), then settle.
@@ -193,7 +205,7 @@ async function spawnTracked(spec) {
                     finish();
                     return;
                 }
-                sweep().then(finish, finish);
+                Promise.resolve().then(sweep).then(finish, finish);
             };
             if (groupPid !== undefined) {
                 sweepProcessGroup(groupPid).then(callerSweep, callerSweep);
@@ -264,8 +276,9 @@ const activeChildClosures = new Set();
  * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
  * wait for, and returns the handle that deregisters it.
  *
- * @returns `settle()`. Call from both the child's `close` and `error`
- *   handlers so a dead child never holds the shutdown wait open
+ * @returns `settle()`. Call after child closure and required teardown finish.
+ *   An abort's `error` event does not prove closure; do not settle there.
+ *   A failed start may settle when no live child or teardown remains.
  */
 export function trackChildClosure() {
     let resolveClosed;

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

@@ -68,6 +68,17 @@ export declare function isJsonObject(value: JsonValue | undefined): value is Jso
  * Accepts formats like "140.9.0", "140.9.1", "140.9.0esr", "147.0b1"
  */
 export declare function isValidFirefoxVersion(version: string): boolean;
+/**
+ * Orders two Firefox version strings semantically: major, minor and patch
+ * numerically, with a beta (`153.0b7`) before the release it precedes
+ * (`153.0`). An `esr` suffix does not change the order: `153.3.0esr` and
+ * `153.3.0` compare equal, since the product says which line it is. A
+ * lexical sort, which this replaces in `rebase`, put `153.10.0esr` before
+ * `153.2.0esr` and `99.0` after `140.0esr`. A string that is not a Firefox
+ * version sorts after every one that is, then lexically.
+ * @returns Negative when `a` is older, positive when newer, 0 when equal
+ */
+export declare function compareFirefoxVersions(a: string, b: string): number;
 /**
  * Validates a release-candidate build directory name.
  * Accepts formats like "build1", "build2", "build12" (no leading zero).

package/dist/src/utils/validation.js

@@ -100,6 +100,49 @@ export function isValidFirefoxVersion(version) {
     // Beta: 147.0b1, 147.0b2
     return /^[1-9]\d{0,2}\.\d+(?:b[1-9]\d*|\.\d+(?:esr)?|esr)?$/.test(version);
 }
+/**
+ * Orders two Firefox version strings semantically: major, minor and patch
+ * numerically, with a beta (`153.0b7`) before the release it precedes
+ * (`153.0`). An `esr` suffix does not change the order: `153.3.0esr` and
+ * `153.3.0` compare equal, since the product says which line it is. A
+ * lexical sort, which this replaces in `rebase`, put `153.10.0esr` before
+ * `153.2.0esr` and `99.0` after `140.0esr`. A string that is not a Firefox
+ * version sorts after every one that is, then lexically.
+ * @returns Negative when `a` is older, positive when newer, 0 when equal
+ */
+export function compareFirefoxVersions(a, b) {
+    const left = parseFirefoxVersionOrder(a);
+    const right = parseFirefoxVersionOrder(b);
+    if (left === undefined || right === undefined) {
+        if (left !== undefined)
+            return -1;
+        if (right !== undefined)
+            return 1;
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+    for (let i = 0; i < left.length; i++) {
+        const delta = (left[i] ?? 0) - (right[i] ?? 0);
+        if (delta !== 0)
+            return delta;
+    }
+    return 0;
+}
+/**
+ * `[major, minor, patch, betaRank]`, where a release ranks above every beta
+ * of the same version.
+ */
+function parseFirefoxVersionOrder(version) {
+    const match = /^(\d+)\.(\d+)(?:\.(\d+))?(?:b(\d+))?(?:esr)?$/i.exec(version.trim());
+    if (!match)
+        return undefined;
+    const beta = match[4];
+    return [
+        Number(match[1]),
+        Number(match[2]),
+        Number(match[3] ?? 0),
+        beta === undefined ? Number.MAX_SAFE_INTEGER : Number(beta),
+    ];
+}
 /**
  * Validates a release-candidate build directory name.
  * Accepts formats like "build1", "build2", "build12" (no leading zero).

package/docs/configuration.md

@@ -59,6 +59,19 @@ tool at
 `/Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool`,
 plus `actool` via `xcrun`, `sips`, and `iconutil`.
 
+On macOS, `fireforge doctor` also checks that the bootstrapped clang
+(`~/.mozbuild/clang`, or under `MOZBUILD_STATE_PATH`) can link against the
+SDK the build will use. That is the SDK `engine/mozconfig` selects with
+`--with-macos-sdk`, resolved by sourcing the mozconfig the way mach does,
+or `xcrun --show-sdk-path` when it names none. The check links a trivial C
+program through the toolchain's lld in a temp directory. When that fails, it
+reports a warning with clang's first error and lists the SDKs installed
+under the mozbuild state directory, the Command Line Tools and the active
+Xcode. An Xcode update can ship an SDK the pinned toolchain cannot read, and
+`mach configure` then dies at its linker probe with nothing but `config.log`
+saying why. The check does nothing on other platforms and when no clang has
+been bootstrapped.
+
 ## `patchLint`
 
 Per-patch lint type-checks plain Firefox JS against a built-in
@@ -84,6 +97,28 @@ Firefox-globals shim that tracks upstream WebIDL additions per release.
   project's, then `npx --no-install`. Left at `'off'`, formatting is out of
   scope for the per-patch tier, and no other tier checks `.sys.mjs`
   formatting either.
+- `patchLint.forwardRegistration` (`'support-files'` or `'extended'`,
+  default `'support-files'`) picks which carriers the `forward-registration`
+  queue rule checks for a line naming a file that only a later patch
+  creates. The default checks test-manifest `support-files`. `'extended'`
+  also checks:
+  - jar.mn pair lines (the source in parentheses, relative to the jar.mn);
+  - moz.build path tokens (a quoted string with a `.` or `/`, relative to
+    the moz.build);
+  - test-manifest section headers and `head`;
+  - `customElements.js` `chrome://<pkg>/content/…` URLs, resolved through
+    the jar.mn lines the same queue adds.
+
+  A line whose target cannot be resolved without the build system is left
+  alone: a `%` or `@AB_CD@` substitution, `**`, `!`, a path that leaves the
+  tree, or a chrome URL no queue jar.mn line packages. Each finding prints
+  the same paste-and-run `patch staged-dependency --add --kind registration`
+  command as the `support-files` arm. The setting is opt-in because a queue
+  that predates it can carry many such edges, and a new error would red a
+  `--max-warnings 0` gate on install. The same census is on the public API as
+  `findForwardRegistrations(patchesDir, { scope })`, which defaults to
+  `'extended'`, for a consumer that keeps its own ratchet over these edges.
+
 - `patchLint.fileSizeThresholds` tunes the `file-too-large` line counts per
   file class:
 
@@ -105,6 +140,28 @@ Firefox-globals shim that tracks upstream WebIDL additions per release.
   is a hard failure rather than a soft limit, which is what these thresholds
   exist to let you move.
 
+## `typecheck`
+
+`typecheck.projects` lists the jsconfig files `fireforge typecheck` checks
+as whole projects. `typecheck.extraShim` and `typecheck.projectOverrides`
+add declarations to the Firefox-globals shim, for every project or for one.
+When `patchLint.checkJs` is on, the same command also runs the per-patch
+checkJs pass that `export` enforces, so a green `typecheck` means
+export-clean types.
+
+Project build info is written in `.fireforge/typecheck/`, outside `engine/`,
+with a key covering the shim, TypeScript version, compiler options and
+FireForge version. Diagnostics always use a fresh project
+program: prior incremental diagnostic state is never restored. Cached and
+`--no-cache` runs therefore check the same complete file set. `--no-cache`
+also disables build-info writes. A jsconfig's own `incremental` and
+`tsBuildInfoFile` remain ignored.
+
+Both project and per-patch checkJs provide Gecko DOM constructor
+`isInstance(value)` predicates with instance narrowing, plus
+`MouseEvent.MOZ_SOURCE_PEN`. These declarations retain normal DOM member
+checking; they do not turn constructors or instances into `any`.
+
 ## `patchPolicy`
 
 `patchPolicy.ranges` makes `patch compact` range-aware, so closing ordinal
@@ -225,6 +282,31 @@ non-CI launches print a warning saying so. Exit codes 12 and 13 separate a
 console regression from a launch failure. See
 [`exit-codes.md`](exit-codes.md).
 
+A smoke run starts on a fresh temporary profile by default (since 0.48.0).
+The step exists to prove what the build does on a clean start. The
+developer's `obj-*/tmp/profile-default` carries whatever the last session
+left (a pre-reset database, a restored hand-made applet), and those reds
+say nothing about the tree. FireForge creates the directory under the OS
+temp dir, seeds the two prefs `mach run` writes into profiles it makes
+itself (`browser.shell.checkDefaultBrowser` and
+`browser.aboutConfig.showWarning`), and passes it to Firefox as
+`-profile`. The directory is removed when the run ends. That includes a
+failed run and a SIGINT/SIGTERM, which the signal handler removes after
+the browser tree has shut down. A FireForge that was SIGKILLed cannot clean
+up after itself, so the next `run` removes any temporary profile whose
+owning process is gone.
+
+- `--profile <path>` launches with a named profile directory and leaves it
+  in place. Under `--smoke-exit` it replaces the fresh default.
+- `--temp-profile` gives a plain `run` the same fresh, removed-afterwards
+  profile.
+
+A plain `run` without either flag keeps mach's `profile-default`. `mach run`'s
+desktop parser has no `--profile` option (its `--profile/-P` belongs to the
+Android parser), so the profile is always passed as a program parameter.
+With an explicit profile, mach neither writes its `runprefs` from
+`~/.mozbuild/machrc` nor accepts `--setpref`.
+
 The allowlist (`--console-allow-file`) is count-blind by default: a line that
 matches an entry never counts, however often it fires. A `# max-hits: N`
 comment directly above an entry (other comments may sit between) caps how

package/docs/exit-codes.md

@@ -15,7 +15,7 @@ which error class produces each one.
 |    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                                                 | `DownloadError` and subclasses                                                                    |
 |    4 | `GIT_ERROR`            | A git operation failed.                                                                                                                       | `GitError` and subclasses, except `GitNotFoundError`                                              |
 |    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`, `PatchManifestCorruptError`, `RebaseError` and subclasses                           |
+|    6 | `PATCH_ERROR`          | A patch failed to apply (including a patch `rebase --dry-run` predicts will reject), or the patch queue could not be mutated.                 | `PatchError`, `PatchManifestCorruptError`, `RebaseError` and subclasses                           |
 |    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                                            | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError`                                    |
 |    8 | `INVALID_ARGUMENT`     | The flags were wrong. A usage problem, not an environment one.                                                                                | `InvalidArgumentError`, plus commander usage errors (unknown command or option, missing argument) |
 |    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                                         | `FurnaceError`                                                                                    |

package/docs/lifecycle-invariants.md

@@ -113,11 +113,15 @@ command, read the decision table at the bottom first.
    carry primary shebangs, and mach rebuilds them in-tree), and runs
    `mach configure` inside the tree so the configure-generated root files are
    regenerated against the tree's paths rather than keeping the primary's. It
-   then verifies exactly that set afterwards (config.status, backend.mk,
-   Makefile, config/autoconf.mk, via `findObjdirRelocationViolation`, pinned
-   by `mach-objdir-relocation.test.ts`). Nested Makefiles are products of the
-   verified config.status, and `.deps` build products are out of scope as
-   read-only staleness that the first in-tree rebuild corrects. Finally it
+   Before configure, relocation rewrites old-source symlinks, `.pp`/`.d`,
+   FasterMake and Cargo fingerprint metadata, and removes copied
+   `config.statusd/*/config.track` inventories. Those inventories contain
+   absolute WRITE destinations and must never be consumed from a clone.
+   Aliased objdirs or partial-config directories are refused. Afterwards
+   `findObjdirRelocationViolation` verifies config.status, backend.mk,
+   Makefile, config/autoconf.mk and every remaining objdir symlink for the
+   old source prefix. External toolchain links are allowed; source links
+   must no longer consult the old checkout. Finally it
    copies `last-build.json` so the in-tree stale-build gates anchor
    correctly.
 
@@ -190,9 +194,10 @@ command, read the decision table at the bottom first.
    stages and unstages for real. Each of those commands therefore runs its
    whole body inside `withPrivateGitIndex`, which seeds a temp
    `GIT_INDEX_FILE` from the repository's own index so that every refresh
-   lands there and is discarded. `typecheck` additionally forces
-   `incremental: false` and drops `tsBuildInfoFile`, so no sidecar is written
-   under `engine/`. The scope fails open, meaning an unresolvable git dir
+   lands there and is discarded. `typecheck` additionally ignores a
+   jsconfig's own `incremental` and `tsBuildInfoFile`, so no sidecar is
+   written under `engine/`. Its incremental build info (0.48.0) lives in the
+   project's `.fireforge/typecheck/`, outside the engine. The scope fails open, meaning an unresolvable git dir
    simply does not install it, and it is not reentrant. This exists so that
    invariant 8 stays evidential: a concurrent `fireforge test` must not be
    invalidated by FireForge's own read-only lane. Enforced by

package/docs/machine-output.md

@@ -86,15 +86,16 @@ moved.
 `FIREFORGE-VERDICT: FAIL reason=<reason>` uses a closed set
 (`FireforgeVerdictReason`, `src/commands/test-verdict.ts`):
 
-| Reason          | Meaning                                                                                                                                                                                                                                                                                                                                                           |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `crash`         | The harness or the browser died, so there is no trustworthy suite result.                                                                                                                                                                                                                                                                                         |
-| `no-tests`      | The run dispatched but nothing ran.                                                                                                                                                                                                                                                                                                                               |
-| `test-failures` | The suite ran and reported unexpected results.                                                                                                                                                                                                                                                                                                                    |
-| `preflight`     | The run was refused before the harness was reached.                                                                                                                                                                                                                                                                                                               |
-| `inconclusive`  | A result exists, but `engine/` moved under it, so the result was discarded.                                                                                                                                                                                                                                                                                       |
-| `lock-timeout`  | The run never started: the engine session lock stayed contended.                                                                                                                                                                                                                                                                                                  |
-| `killed`        | A signal terminated the run, or FireForge ended it because its parent process vanished. Written from the signal handler (or the parent-exit watchdog) so that a log tail always describes itself. A killed run must never be silent, or "killed", "still running" and "never started" all look alike. `signal=` names the cause: a signal name, or `parent-exit`. |
+| Reason              | Meaning                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crash`             | The harness or the browser died, so there is no trustworthy suite result.                                                                                                                                                                                                                                                                                         |
+| `harness-arguments` | Profile or other harness argument setup failed before any tests could run; a rebuild is not the repair.                                                                                                                                                                                                                                                           |
+| `no-tests`          | The run dispatched but nothing ran.                                                                                                                                                                                                                                                                                                                               |
+| `test-failures`     | The suite ran and reported unexpected results.                                                                                                                                                                                                                                                                                                                    |
+| `preflight`         | The run was refused before the harness was reached.                                                                                                                                                                                                                                                                                                               |
+| `inconclusive`      | A result exists, but `engine/` moved under it or a perf run changed power source, so the result was discarded.                                                                                                                                                                                                                                                    |
+| `lock-timeout`      | The run never started: the engine session lock stayed contended.                                                                                                                                                                                                                                                                                                  |
+| `killed`            | A signal terminated the run, or FireForge ended it because its parent process vanished. Written from the signal handler (or the parent-exit watchdog) so that a log tail always describes itself. A killed run must never be silent, or "killed", "still running" and "never started" all look alike. `signal=` names the cause: a signal name, or `parent-exit`. |
 
 ### The additive `note=` key
 
@@ -109,20 +110,19 @@ unchanged and still comes from the closed set above, so a consumer that
 tokenises `key=value` pairs is unaffected, and a gate that names no class
 emits no `note=` at all. The classes are not a closed set and may grow, so
 consumers should treat an unrecognised one as opaque. Current values:
-`stale-browser`, `stale-browser-kill-failed`, `marionette-port-busy`,
+`browser-busy`, `stale-browser`, `stale-browser-kill-failed`, `marionette-port-busy`, `mochitest-port-busy`,
 `coverage-replaced`, `stale-build`, `stale-components`.
 
 ### The additive `shuffle=` key
 
-A `fireforge test --shuffle [seed]` run forwards mach's `--shuffle` (an
-unseeded shuffle of file order in the harness) and exports the seed FireForge
-drew or was given as `FIREFORGE_SHUFFLE_SEED` in the harness environment. The
-seed is appended to the verdict line as `shuffle=<seed>` on every emission
-form, so a red found by shuffling carries its own reproduction
-(`fireforge test --shuffle=<seed> …`) on the one line a pipe keeps. Reordering
-tasks _inside_ a file is harness code that reads the exported seed; FireForge
-owns the seed, the plumbing and the record. Absent when the run did not
-shuffle.
+A `fireforge test --shuffle [seed]` run records the seed used to permute
+FireForge's isolated path-argument shards. Repeating the seed and selection
+repeats that shard order. It also forwards native mach `--shuffle`, which
+randomizes files within an invocation without using this seed. `--no-shard`
+disables FireForge's seeded argument permutation. The seed is exported as
+`FIREFORGE_SHUFFLE_SEED` for custom in-file task code and appended as
+`shuffle=<seed>` to every verdict form. This field does not claim replayable
+native harness file order. Absent when shuffle was not requested.
 
 ### The additive `orphans-reaped=` key
 
@@ -141,3 +141,20 @@ A preflight refusal's own text is written to stdout before the verdict line,
 and into the run log, so the verdict stays the last stdout write while the
 reason survives both a redirect and a `tail`. See
 [`run-logs.md`](run-logs.md).
+
+### Additive host and perf keys
+
+`host-load=<number>` records the one-minute load at suite startup. Each suite
+also samples the highest CPU process before and after dispatch. A contention
+warning appends `host-cpu-warning=true`; the diagnostic names the process
+and measured CPU. These diagnostics annotate a test failure without changing
+its classifier reason.
+
+Perf runs append `power-source=ac|battery|unknown`. On macOS the source is
+read from `pmset -g ps`, so charging on AC is correctly `ac`. A known source
+transition appends `power-changed=true` and refuses the run as
+`reason=inconclusive`. The producer's sample JSON retains its fields and
+gains `fireforgeHost: { start, end, powerSourceChanged }`, where each host
+state includes `load`, `power` and an optional `topProcess` with CPU and
+command. Consumers should tolerate this additive object. Unknown power
+state is visible but never treated as a proven transition.

package/docs/patch-workflow.md

@@ -56,6 +56,21 @@ requested path produces no hunk. That is checked against the full requested
 list rather than the subset left after filtering, so nothing dropped upstream
 can pass as a silent success.
 
+An absent file originally created by a selected patch can be retired with
+repeatable `--expect-removed <path>` on scan-less re-export:
+
+```sh
+fireforge re-export 202 --refuse-adjacent-unmanaged --refuse-foreign-drift --expect browser/themes/shared/hominis/widgets.css --expect-removed browser/themes/shared/hominis/stop.svg
+```
+
+The removal must have exactly one selected owner, be absent from disk and
+engine HEAD, and have a `new file mode` section in that owner's patch.
+Every removal is validated before writes, in dry-run too. Other paths keep
+both refusal checks; retirement grants no unmanaged or foreign-drift
+exception. Removing every file would empty the patch and requires `patch
+drop` instead. `--expect-removed` cannot combine with `--scan`, `--files` or
+`--all`.
+
 ## Queue maintenance
 
 Under `fireforge patch`:
@@ -81,11 +96,23 @@ slugs, and bare slugs.
 `lint --per-patch --max-warnings 0` is the warning-clean form for a release
 gate.
 
+`lint --per-patch --notices summary` prints one line per check in place of
+every NOTICE row, for example `NOTICE [large-patch-lines]: 180 across 172
+patch(es), 150 of them suppressed by lintIgnore (see --report)`. On a green
+queue those rows are reviewed waivers and under-threshold measurements, and
+there can be hundreds of them. The default, `--notices full`, prints them
+as before. Errors and warnings always print in full, and the `--report`
+JSON is the same in both modes.
+
 `lint --per-patch --report <path>` writes a machine-readable JSON report with
 each patch's line count, tier, active size thresholds, issues, and issues
 suppressed by `lintIgnore`. The size metrics (`countNonBinaryDiffLines`,
 `resolvePatchSizeTier`, `getPatchSizeThresholds`) are also exported on the
-programmatic API.
+programmatic API. So is `filesMeasuredByFileTooLarge(patchText)`, which
+returns the files `file-too-large` measures in a patch: the JS files it
+creates, and never a modified file or a new file of another kind. The rule
+selects its files through that same function, so an audit that uses it
+cannot drift from the rule.
 
 Per-patch lint type-checks plain Firefox JS against a built-in
 Firefox-globals shim that tracks upstream WebIDL additions per release. See
@@ -116,6 +143,28 @@ npx fireforge download --force
 npx fireforge rebase
 ```
 
+`download --force` is the destructive step of the three, not `rebase`. It
+replaces `engine/` wholesale, so applied patches, unexported edits and
+commits made in `engine/` are gone once the new tree is active. When the
+engine it is about to replace has changed paths against HEAD, or HEAD has
+moved off the recorded base commit, it names the loss (how many changed
+paths match the patch queue and how many do not) and asks first. A
+non-interactive run refuses unless `--yes` is given. A clean engine is
+replaced without a prompt.
+
+`npx fireforge rebase --dry-run` replays the queue onto the engine's HEAD
+without touching `engine/`. It seeds a private index from HEAD and applies
+each patch there with `git apply --cached`, in queue order, walking the same
+context-reduction ladder as the real run (exact, then `-C2`, `-C1`, `-C0`,
+bounded by `--max-fuzz`). Each patch is reported as `clean`, `reduced
+context` (with the step it needed) or `reject` (with the files git named).
+It exits 6 when anything rejects. A reject after an earlier one is marked
+as possibly cascading from it, since the replay continues without the
+rejected patch. Run it after the download, when HEAD is the new source. The
+header names the oldest patch stamp as "from", compared as versions rather
+than strings, prints the spread when the queue carries several stamps, and
+warns when `engine/` is not yet on the pinned version.
+
 If a patch fails, fix the reject inside `engine/`, then run
 `npx fireforge rebase --continue`. A rebase leaves the engine mutated on
 purpose, so its apply-and-persist pairs are held across a signal rather than

package/docs/testing.md

@@ -34,9 +34,59 @@ build, `test` fails before launching stale artifacts. Use `--build` to
 refresh, or `--allow-stale-build` only for intentional out-of-band rebuilds.
 
 `--build-only` packages mixed-harness paths once, and then each harness half
-can run without `--build`. `--extend-coverage` retains prior scoped coverage
-instead of replacing it. It is refused when the build anchor moved (engine
-HEAD, `engine/mozconfig`, or a previously fingerprinted packageable file).
+can run without `--build`. Scoped builds retain prior coverage automatically
+when engine HEAD, `engine/mozconfig` and recorded staging inputs outside the
+rebuilt scope are unchanged. Changed files explicitly included in this
+build are allowed. The fingerprints include test scripts and support files,
+not only packageable chrome sources. A failed anchor narrows the claim and
+prints the dropped paths; `--extend-coverage` instead refuses. Baselines
+without complete staging-input fingerprints require a new build before they
+can retain prior coverage.
+New dirty inputs outside the rebuilt scope invalidate retention conservatively,
+including shared fixtures outside test directories.
+
+When `patchLint.checkJs` and `patchLint.checkJsTestFiles` are enabled, named
+pre-test builds check the selected test scripts before deployment or mach.
+This includes new scripts not yet owned by an exported patch.
+
+### Shared browsers, ports and host state
+
+Browser ownership is checked before a pre-test deployment and before full
+or UI builds. A live or unreadable parent means busy, with its owner named
+when available. `--kill-stale-marionette` requires a dead parent plus harness
+arguments; a profile argument alone does not prove abandonment. A plain
+launchd-parented app remains unattributed and is not automatically killed.
+
+`test --wait-browser [seconds]` waits for this objdir's browser to exit;
+`test --wait-port [seconds]` waits for mochitest and Marionette listeners.
+`build --wait-browser [seconds]` queues a full or UI build behind the browser.
+Bare flags wait 60 seconds; explicit values accept 1–3600 seconds. They are
+independent of the FireForge lock budget. On expiry the normal preflight
+refusal and its remedy are preserved.
+
+Every suite samples host load and the highest CPU process before and after
+dispatch. Load at least 4 or a process at least 90% CPU produces a warning;
+verdicts include `host-load` and, when needed, `host-cpu-warning=true`.
+Perf runs include `power-source=ac|battery|unknown`; on macOS this comes from
+`pmset -g ps`, including charging on AC. Sample JSON gains a `fireforgeHost`
+object with start/end states and `powerSourceChanged`. A known power-source
+transition produces `FAIL reason=inconclusive power-changed=true`.
+Unknown power state is reported without inventing a transition.
+
+### Profile overlays
+
+Use repeatable `--profile-file source=relative/destination` to add files to
+the test profile, for example:
+
+```sh
+fireforge test --perf-samples sample.json --profile-file arm.css=chrome/userChrome.css browser/base/content/test/perf/browser_perf.js
+```
+
+The source resolves from the project root. Destinations must stay relative
+with no traversal. FireForge stages copies and merges only those staged
+directories into the harness profile, preserving existing chrome files.
+A raw `--extra-profile-file` directory collision is classified as
+`reason=harness-arguments` and names this remedy rather than a rebuild.
 
 ### What a pre-test build costs
 
@@ -183,15 +233,16 @@ redirected run keeps the reason as well as the verdict. See
 
 ## Seeded shuffle
 
-`fireforge test --shuffle` runs a mochitest selection in a seeded random file
-order and prints the seed; `--shuffle=<seed>` replays it. FireForge forwards
-mach's own `--shuffle`, exports `FIREFORGE_SHUFFLE_SEED=<seed>` to the harness
-so in-file task reordering (harness `head.js` code, not FireForge) can key off
-the same number, and stamps `shuffle=<seed>` on the verdict line. It is
-mochitest-only: the xpcshell harness has no shuffle, and generic `mach test`
-dispatch would hand the flag to every suite. Write the flag as
-`--shuffle=<seed>` or after the paths, because a bare `--shuffle <path>` reads
-the path as the seed.
+`fireforge test --shuffle` deterministically permutes isolated mochitest path
+arguments and prints the seed; `--shuffle=<seed>` replays that shard order for
+the same input selection. A directory remains one invocation. `--no-shard`
+disables this argument permutation. FireForge also forwards native mach
+`--shuffle` within each invocation, whose file order remains unseeded and is
+not replayed by the FireForge seed. `FIREFORGE_SHUFFLE_SEED=<seed>` is available
+to custom harness `head.js` code for in-file task ordering, and `shuffle=<seed>`
+is recorded on the verdict. The option is mochitest-only. Write
+`--shuffle=<seed>` or place it after the paths because a bare
+`--shuffle <path>` consumes the path as its optional seed.
 
 Exit code 14 (`INCONCLUSIVE`) is not red: it means `engine/` moved while the
 harness ran and the result was thrown away. Exit 15 (`LOCK_TIMEOUT`) means
@@ -256,3 +307,17 @@ instead, use a [verification tree](verification-trees.md).
 In dev builds, files under `obj-*/dist/bin` may be symlinks back into the
 source tree (prefs especially), so edit source prefs directly and keep a
 backup before bisection experiments.
+
+## Repository release gate
+
+Run `npm run release:check` with the exact Node version in `.nvmrc` and npm
+version in `package.json`'s `packageManager`. The gate verifies these pins
+before formatting, whitespace, zero-warning lint, strict typecheck, development
+and production dead-code checks, import cycles, coverage floors, and installed
+package smoke tests. `prepublishOnly` and the CI quality job run the same gate.
+Supported Node-version and OS matrices continue to run ordinary tests separately.
+
+The full-Firefox integration runner is opt-in. It snapshots project files,
+engine changes and the index before arming recovery; a refusal cannot erase an
+existing workspace. Failed recovery fails the run, preserves affected paths and
+writes recovery evidence for manual repair.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.47.1",
+  "version": "0.49.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -39,8 +39,9 @@
     "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\" \"knip.production.json\"",
     "prepare": "node -e \"import('./scripts/prepare.mjs').catch((error) => { if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0); throw error; })\"",
     "prepack": "npm run build && node ./scripts/generate-build-info.mjs --loud",
-    "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run deadcode:check:production && npm run cycles:check && npm run test:coverage && npm run pack:verify",
-    "prepublishOnly": "npm run release:check"
+    "release:check": "npm run toolchain:check && npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run deadcode:check:production && npm run cycles:check && npm run test:coverage && npm run pack:verify",
+    "prepublishOnly": "npm run release:check",
+    "toolchain:check": "node ./scripts/check-release-toolchain.mjs"
   },
   "files": [
     "dist/",
@@ -75,9 +76,9 @@
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.35.1",
+    "knip": "6.37.0",
     "lint-staged": "^17.0.4",
-    "prettier": "3.9.6",
+    "prettier": "3.9.8",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",
@@ -108,5 +109,9 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "allowScripts": {
+    "esbuild@0.28.1": true,
+    "fsevents@2.3.3": true
   }
 }