@hominis/fireforge 0.47.0 → 0.48.0

package/dist/src/utils/process-input.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Stdin-fed command execution with byte-exact stdout.
+ *
+ * Its own module rather than a function in `process.ts` only because that
+ * file sits on a 500-line budget. The logic belongs to the exec layer.
+ */
+import { spawn } from 'node:child_process';
+import { buildChildEnv } from './child-env.js';
+import { exitCodeFromClose } from './process.js';
+/**
+ * Runs a command, writes `input` to its stdin, and returns stdout as raw
+ * bytes. For batch protocols (`git cat-file --batch`) whose framing counts
+ * bytes: the decoded, 50 MB-capped collector `exec` uses would corrupt
+ * both. The caller bounds the input, and so the output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param input - Bytes written to stdin, which is then closed
+ * @param options - Execution options
+ */
+export async function execWithInput(command, args, input, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: buildChildEnv(options),
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (chunk) => {
+            out.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            err.push(chunk);
+        });
+        // A child that exits before reading all of stdin (a bad ref, say) makes
+        // the write fail with EPIPE. The close handler reports the real outcome.
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(input);
+        child.on('error', reject);
+        child.on('close', (code, signal) => {
+            resolve({
+                stdout: Buffer.concat(out),
+                stderr: Buffer.concat(err).toString('utf8'),
+                exitCode: exitCodeFromClose(code, signal),
+            });
+        });
+    });
+}

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

@@ -85,7 +85,27 @@ export interface ProcessGroupOptions {
      * whenever this option is set.
      */
     processGroup?: boolean;
+    /**
+     * Receives the process-group id (the detached child's pid) right after a
+     * group-leader spawn. Lets a caller expose the group to a supervisor that
+     * cannot signal FireForge itself gracefully (`fireforge test --pgid-file`),
+     * or hold it for a teardown of its own. Not called when no group was
+     * created (`processGroup` unset, or win32).
+     */
+    onProcessGroup?: (pgid: number) => void;
+    /**
+     * Extra teardown the caller owns, awaited after the child's `close` and
+     * the post-run group sweep, before the child's closure settles. Placed
+     * here rather than after the wrapper resolves so the bin signal handler's
+     * `waitForActiveChildShutdown` covers it too: a reap that ran after the
+     * wrapper resolved would race `process.exit` on a forwarded SIGTERM. Must
+     * never throw; a rejection is swallowed so it cannot mask the child's
+     * result.
+     */
+    postCloseSweep?: () => Promise<void>;
 }
+/** A child's exit code, with a signal death mapped to 128 + its number. */
+export declare function exitCodeFromClose(code: number | null, signal: NodeJS.Signals | null): number;
 /**
  * Executes a command and returns its output.
  * @param command - Command to execute

package/dist/src/utils/process.js

@@ -77,7 +77,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;
     }
@@ -154,6 +155,8 @@ async function spawnTracked(spec) {
             detached: usesProcessGroup,
         });
         const groupPid = usesProcessGroup ? child.pid : undefined;
+        if (groupPid !== undefined)
+            options.onProcessGroup?.(groupPid);
         spec.attach?.(child);
         // Group-aware kills route to the whole tree. A non-group child is killed
         // directly by the forwarder's own `child.kill`.
@@ -183,11 +186,21 @@ async function spawnTracked(spec) {
                 closure.settle();
                 resolve(spec.result(code, signal));
             };
+            // 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.
+            const callerSweep = () => {
+                const sweep = options.postCloseSweep;
+                if (sweep === undefined) {
+                    finish();
+                    return;
+                }
+                sweep().then(finish, finish);
+            };
             if (groupPid !== undefined) {
-                sweepProcessGroup(groupPid).then(finish, finish);
+                sweepProcessGroup(groupPid).then(callerSweep, callerSweep);
             }
             else {
-                finish();
+                callerSweep();
             }
         });
     });

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,27 @@ 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.
+
+Each project keeps incremental build info in `.fireforge/typecheck/`, one
+file per project. A warm run re-checks only the files whose content changed
+since the last run. The file name carries a key over everything outside the
+program's own files that can change a verdict: the composed shim, the
+TypeScript version, the compiler options, `typecheck.undefinedIdentifiers`
+and the FireForge version. A change to any of them selects a new file, so a
+stale verdict is never replayed, and the project's other build-info files are
+deleted. `fireforge typecheck --no-cache` checks every project from scratch
+and neither reads nor writes the build info. A jsconfig's own `incremental`
+and `tsBuildInfoFile` are still ignored, so nothing is written under
+`engine/`.
+
 ## `patchPolicy`
 
 `patchPolicy.ranges` makes `patch compact` range-aware, so closing ordinal
@@ -113,7 +169,13 @@ gaps does not move a patch out of the band its category owns.
 ## `test`
 
 `test.canaryPath` and `test.canaryTimeoutSeconds` supply the defaults for
-`fireforge test --canary`. See [`testing.md`](testing.md).
+`fireforge test --canary`.
+
+`test.reapOrphans` is `"report"` (default) or `"reap"`: what the preflight
+census does with a harness helper that survived an earlier run in this
+objdir. `"reap"` terminates it and stamps `orphans-reaped=<n>` on the verdict
+line; `--reap-orphans` does the same for one invocation. The objdir anchor
+rule is the same under both. See [`testing.md`](testing.md).
 
 ## `buildAudit`
 
@@ -219,6 +281,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

@@ -190,9 +190,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
@@ -284,7 +285,10 @@ Wait ergonomics are opt-in: `pollMaxMs` (the poll interval doubles from
 `pollMs` up to the cap) and `waitProgressMs` with `onWaitProgress` (a periodic
 progress callback carrying the holder's PID, liveness, and owner-metadata
 lines from the pid file). All three are inert when unset, so existing callers
-keep byte-identical behavior.
+keep byte-identical behavior. Within one poll iteration a due progress probe
+runs before the deadline check, so a wait that times out has always reported
+the holder at least once when its budget exceeds `waitProgressMs`, however
+slow the host (`file-lock.test.ts`, "budget shorter than one iteration").
 
 ### `src/core/file-lock-owner.ts`
 
@@ -430,10 +434,23 @@ On SIGINT or SIGTERM, `bin/fireforge.ts`:
    - `waitForActiveCriticalSections(5 s)`, which holds the exit for in-flight
      "apply plus persist" pairs (invariant 4). It is bounded so that a stuck
      write cannot postpone the exit the user asked for.
+   - `waitForActiveChildShutdown(12 s)`, which holds the exit until every
+     tracked child has closed. For a process-group dispatch (`mach` under
+     `test`, `build`, `run`) "closed" includes the exec layer's post-close
+     work: the group sweep and the caller's `postCloseSweep` (the harness
+     helper reap in `fireforge test`). Both run before the child's closure
+     settles, so a forwarded SIGTERM cannot race `process.exit` past them.
 3. Force-releases the furnace lock directories of active operations, since
    `withFileLock`'s `finally` will never run past `process.exit`.
 4. Calls `process.exit(130 | 143)`.
 
+A parent that dies without signalling FireForge (SIGKILL on the `npm` above
+it) enters no handler here. `fireforge test` covers that case itself with
+the parent-exit watchdog (`src/core/parent-exit-watchdog.ts`): it writes the
+killed verdict, reaps the mach group and the tracked helpers, and lets the
+dispatch loop end the run; the process then exits through the ordinary
+error path, not through this pipeline.
+
 ## Choosing a primitive for a new mutation
 
 | Your operation                                                                                                       | Use                                                                                            |

package/docs/machine-output.md

@@ -86,15 +86,15 @@ 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. Written from the signal handler 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. |
+| 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`. |
 
 ### The additive `note=` key
 
@@ -124,6 +124,19 @@ 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.
 
+### The additive `orphans-reaped=` key
+
+How many harness processes FireForge terminated itself during the run: at
+preflight, survivors of an earlier run in this objdir under `--reap-orphans`
+or `test.reapOrphans: "reap"`; at teardown, helpers this run's harness
+launched (httpd, websocket server, ssltunnel, process bridge, the browser,
+`moz-http2`) that were still alive after mach exited. Summed across the census, every
+retry attempt and every shard. Absent when nothing was reaped, so a green on
+a quiet machine prints the line it always did, and a green after a reap is
+distinguishable from it. A run ended by SIGTERM or by the parent-exit
+watchdog writes its verdict before the teardown reap runs, so that line never
+carries the key; the reap is reported on stderr instead.
+
 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

package/docs/patch-workflow.md

@@ -81,11 +81,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 +128,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

@@ -87,21 +87,85 @@ a slow build for a silently wrong test.
   earlier run in this project's objdir. It runs at preflight, before this run
   spawns anything, so every hit is necessarily a survivor. A match has to 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
+  report on their own, and structural: the process's executable is a helper
+  binary, or an interpreter whose script argument is a helper script. A
+  process that merely mentions such a path (an editor, a `grep`, the shell
+  FireForge runs under) is not a helper, and FireForge's own ancestors are
+  never candidates. Survivors slow every later run without appearing in
   its output. The usual symptom is a three-second suite taking minutes of
-  wall clock. The census is report-only by default, and `--reap-orphans`
-  terminates what it finds. It never refuses a run. A different shape,
+  wall clock. The census is report-only by default; `--reap-orphans`, or
+  `test.reapOrphans: "reap"` in `fireforge.json`, terminates what it finds
+  (SIGTERM, a 500 ms grace, SIGKILL). It never refuses a run. Every reap is
+  stamped on the verdict line as `orphans-reaped=<n>`. A different shape,
   reparented Python `multiprocessing` workers, is covered by the
   `Orphaned harness workers` doctor check.
+- Every dispatch owns its own kill path. The harness announces what it
+  launches (`runtests.py | Server pid: <n>`, the websocket server, the SSL
+  tunnel, the websocket/process bridge, and the browser as `Application
+pid`); FireForge tracks those pids and, after mach has exited for any
+  reason (a clean finish, a harness crash before a retry, a no-output
+  timeout, a forwarded SIGTERM, the parent-exit watchdog below), terminates
+  any of them still alive. A tracked pid is re-read from `ps` first and must
+  still be anchored to this objdir and still look like the thing that was
+  launched, so a recycled pid is never signalled. One helper is never
+  announced: mozserve starts `moz-http2` in a session of its own and logs no
+  pid, so it is in neither the group nor the announcements. For it, FireForge
+  snapshots the same-objdir helpers before the dispatch spawns and, after
+  mach exits, reaps any helper-shaped process under this checkout's absolute
+  objdir that is new since that snapshot and reparented to launchd. An
+  earlier run's survivor is in the snapshot and stays the census's call. This
+  reap runs inside the exec layer's close path, so the signal handler's
+  bounded child-shutdown wait covers it. The count joins `orphans-reaped=`.
+- FireForge watches its own parent while a dispatch runs. A supervisor that
+  SIGKILLs the process above `fireforge test` (an `npm run` step killed at
+  its bound) signals nothing below it; FireForge notices the reparenting
+  within about two seconds, writes `FIREFORGE-VERDICT: FAIL reason=killed
+signal=parent-exit`, reaps the harness process group and the tracked
+  helpers, and ends the run without classifying or retrying.
 - `--perf-samples <path>` publishes a perf-sample artifact path to the
   harness (exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
 
+## Process groups and supervisors
+
+`fireforge test` spawns mach as the leader of its **own** process group
+(`detached: true`), so that FireForge can signal the whole harness tree with
+one negative-pid kill and sweep the group after mach exits. Two consequences
+for anything that supervises `fireforge test`:
+
+- A supervisor that kills _its own_ process group (`kill -- -<npm pid>`) does
+  not reach mach: mach is not in that group. Killing the `npm`/`node` chain
+  above FireForge leaves the harness tree running.
+- SIGTERM to FireForge is the right signal. FireForge forwards it to the
+  mach group, escalates to SIGKILL after a grace period, sweeps the group,
+  reaps the tracked helpers, and writes `FAIL reason=killed signal=SIGTERM`.
+  (That line, like the watchdog's `signal=parent-exit` line, is written
+  before the teardown reap runs, so it cannot carry `orphans-reaped=`; the
+  reap reports to stderr.)
+- A supervisor that has to SIGKILL FireForge should pass
+  `--pgid-file <path>`. FireForge rewrites the file with the harness group id
+  on every mach spawn (each retry attempt and shard) and removes it when the
+  run ends under its own control. After a SIGKILL the file is still there:
+  `kill -TERM -- -$(cat <path>)`, then `-KILL`, takes mach and every helper
+  that shares its group. Two processes are outside it: the browser
+  (mozprocess puts it in a group of its own) and `moz-http2` (mozserve
+  starts it in its own session). A SIGTERM to the group gives `runtests.py`
+  the chance to run its own cleanup, which normally takes the browser with
+  it; nothing takes `moz-http2`, so after a SIGKILL of FireForge it stays
+  until the next run's census, which is why that run should carry the reap
+  posture. A browser that does survive is the Marionette preflight's and
+  `--kill-stale-marionette`'s to remove.
+
+The mochitest helpers (httpd, websocket server, ssltunnel, process bridge)
+are plain children of `runtests.py` and share mach's group. The browser and
+`moz-http2` do not, which is why the teardown reap above exists alongside the
+group sweep.
+
 ## The verdict line
 
 Every test run ends with one machine-readable line:
 
 ```
-FIREFORGE-VERDICT: PASS|FAIL reason=… [note=<class>] [shuffle=<seed>] [log=<path>]
+FIREFORGE-VERDICT: PASS|FAIL reason=… [note=<class>] [shuffle=<seed>] [orphans-reaped=<n>] [log=<path>]
 ```
 
 Automation should branch on this line rather than on the raw process code,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -75,9 +75,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 +108,9 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "allowScripts": {
+    "esbuild@0.28.1": true,
+    "fsevents@2.3.3": true
   }
 }