@hominis/fireforge 0.46.2 → 0.47.0

package/dist/src/core/mochitest-server-port.js

@@ -23,6 +23,7 @@
  * port-generic, rather than growing a second probe.
  */
 import { GeneralError } from '../errors/base.js';
+import { isExplicitAbsolutePath, isPathInsideRoot } from '../utils/paths.js';
 import { exec } from '../utils/process.js';
 import { probeMarionettePort } from './marionette-port.js';
 /** Default port the mochitest harness binds its httpd to. */
@@ -43,6 +44,40 @@ export function isMochitestServerHolder(holder) {
         return false;
     return /\bxpcshell\b/.test(line) || /\/obj-[^/\s]*\//.test(line) || /\b_tests\b/.test(line);
 }
+/**
+ * Classifies the holder against this project's engine directory. Every
+ * absolute path on the command line is tested with {@link isPathInsideRoot}
+ * (a token test, not a substring test, so `/a/hominis/engine` does not claim
+ * a holder living under `/a/hominis-2/engine`). On POSIX the command line is
+ * the full `ps -o args=` output, so the objdir path is always present for a
+ * harness httpd; a holder whose paths all lie elsewhere belongs to another
+ * checkout.
+ *
+ * @param holder - The listener found on the port
+ * @param engineDir - Absolute engine directory of THIS project
+ */
+export function classifyMochitestServerHolder(holder, engineDir) {
+    if (!isMochitestServerHolder(holder))
+        return 'unrecognized';
+    const absoluteTokens = holder.commandLine.split(/\s+/).filter(isExplicitAbsolutePath);
+    return absoluteTokens.some((token) => isPathInsideRoot(engineDir, token))
+        ? 'this-checkout'
+        : 'foreign-checkout';
+}
+/**
+ * The objdir a foreign holder is serving from, for the refusal text: the
+ * first absolute command-line token with an `obj-…` segment, cut at that
+ * segment. Falls back to the first absolute token, then to a placeholder.
+ */
+export function describeHolderObjdir(commandLine) {
+    const tokens = commandLine.split(/\s+/).filter(isExplicitAbsolutePath);
+    for (const token of tokens) {
+        const match = /^(.*?[/\\]obj-[^/\\]*)(?:[/\\]|$)/.exec(token);
+        if (match?.[1])
+            return match[1];
+    }
+    return tokens[0] ?? '(no path visible on the command line)';
+}
 /**
  * Refuses a mochitest dispatch when the harness's server port is held. It
  * terminates the holder first only for a recognized stale harness httpd,
@@ -57,16 +92,24 @@ export function isMochitestServerHolder(holder) {
  * Best effort: {@link probeMarionettePort} reports an
  * unprobeable port as free, so a host without `lsof` runs exactly as before.
  *
+ * A recognized httpd from ANOTHER checkout is a refusal and never a kill
+ * either, flag or no flag: it is a peer's live suite, not our debris. The
+ * browser-side probe draws the same line for a bare launch it cannot
+ * attribute; this one can attribute, because the objdir is on the command
+ * line, so it names the other checkout instead of offering `kill -9`.
+ *
  * @param port - Port to probe (default {@link DEFAULT_MOCHITEST_SERVER_PORT})
- * @param options - `killStaleServer` opts into terminating a recognized holder
+ * @param options - `engineDir` is this project's absolute engine directory,
+ *   the ownership boundary; `killStaleServer` opts into terminating a holder
+ *   recognized as THIS checkout's debris
  */
-export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITEST_SERVER_PORT, options = {}) {
+export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITEST_SERVER_PORT, options) {
     const probe = await probeMarionettePort(port);
     if (!probe.inUse || !probe.holder)
         return;
     const holder = probe.holder;
-    const recognized = isMochitestServerHolder(holder);
-    if (recognized && options.killStaleServer === true) {
+    const holderClass = classifyMochitestServerHolder(holder, options.engineDir);
+    if (holderClass === 'this-checkout' && options.killStaleServer === true) {
         try {
             if (process.platform === 'win32') {
                 await exec('powershell.exe', [
@@ -87,16 +130,16 @@ export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITES
             // pretending the port is now free.
         }
     }
-    throw new GeneralError(describeMochitestServerRefusal(port, holder, recognized));
+    throw new GeneralError(describeMochitestServerRefusal(port, holder, holderClass));
 }
 /**
  * Builds the operator-facing refusal. Exported for direct unit testing.
  *
  * @param port - The probed port
  * @param holder - The listener found on it
- * @param recognized - Whether it is the harness's own `server.js`
+ * @param holderClass - Whose harness `server.js` it is, if it is one at all
  */
-export function describeMochitestServerRefusal(port, holder, recognized) {
+export function describeMochitestServerRefusal(port, holder, holderClass) {
     const killHint = process.platform === 'win32'
         ? `Stop-Process -Id ${holder.pid} -Force`
         : `kill -9 ${holder.pid}`;
@@ -106,11 +149,21 @@ export function describeMochitestServerRefusal(port, holder, recognized) {
         "  A browser launched now would connect to THAT server, which cannot serve this run's " +
         'manifest — the run would stall before TEST_START and die on the no-output timeout with ' +
         '"Ran 0 checks".\n';
-    if (recognized) {
+    if (holderClass === 'this-checkout') {
+        return (evidence +
+            "  This is the mochitest harness's own server.js from THIS checkout's objdir, so it is " +
+            'debris from an interrupted run. Retry with "--kill-stale-marionette" to have FireForge ' +
+            `stop it, or stop it yourself with "${killHint}" (a wedged httpd can ignore SIGTERM).`);
+    }
+    if (holderClass === 'foreign-checkout') {
+        // No kill hint on this branch, on purpose: the PID is a peer's live
+        // suite, and "kill -9 <pid>" is exactly the instruction that would have
+        // destroyed it.
         return (evidence +
-            "  This is the mochitest harness's own server.js, so it is debris from an interrupted run. " +
-            'Retry with "--kill-stale-marionette" to have FireForge stop it, or stop it yourself with ' +
-            `"${killHint}" (a wedged httpd can ignore SIGTERM).`);
+            `  This is a mochitest httpd from ANOTHER checkout: ${describeHolderObjdir(holder.commandLine)}. ` +
+            'It is serving a live run there, so FireForge will not stop it and "--kill-stale-marionette" ' +
+            'will not either. Wait for that run to finish or free the port yourself, then retry. ' +
+            `Diagnose with "lsof -nP -iTCP:${port}".`);
     }
     return (evidence +
         "  This is NOT the mochitest harness's server.js, so FireForge will not offer to kill it. " +

package/dist/src/core/patch-lint-imports.js

@@ -54,14 +54,14 @@ export function hasRelativeImport(content) {
     try {
         return astHasRelativeImport(content, 'module');
     }
-    catch (moduleError) {
-        void moduleError;
+    catch {
+        // Not parseable as an ES module; try classic-script mode next.
     }
     try {
         return astHasRelativeImport(content, 'script');
     }
-    catch (scriptError) {
-        void scriptError;
+    catch {
+        // Not parseable at all; fall back to stripped-text matching below.
     }
     return RELATIVE_IMPORT_FALLBACK_PATTERN.test(stripJsComments(content));
 }

package/dist/src/core/smoke-patterns.d.ts

@@ -29,6 +29,12 @@ export interface CompiledAllowlistEntry {
     source: string;
     /** Human-readable origin: `allow.txt:12` or `--console-allow #2`. */
     origin: string;
+    /**
+     * Ceiling from a `# max-hits: N` directive above the entry: how often the
+     * suppressed cause can physically fire in one boot. More hits than this
+     * is a flood wearing an allowlisted shape, and fails the run.
+     */
+    maxHits?: number;
 }
 /**
  * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
@@ -43,8 +49,26 @@ export declare function matchAllowlist(line: string, allow: readonly CompiledAll
  * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
  * pattern throws immediately: better to fail fast at CLI parse time than
  * to silently let a typo match nothing.
+ *
+ * A `# max-hits: N` comment sets the ceiling of the entry that follows it
+ * (other comment lines may sit between). A blank line or end of file with
+ * no entry after the directive is an error rather than a silently dropped
+ * cap, since a cap the operator wrote and the run ignored is the exact
+ * shape of failure this directive exists to prevent.
  */
 export declare function compileAllowlistFromFile(body: string, sourcePath: string): CompiledAllowlistEntry[];
+/** An allowlist entry that matched more lines than its `# max-hits` ceiling. */
+export interface OverCapAllowlistEntry {
+    entry: CompiledAllowlistEntry;
+    hits: number;
+    maxHits: number;
+}
+/**
+ * Entries whose per-entry hit count (every matched line, error-class or
+ * not: the `N×` number the attribution block prints and the operator tunes
+ * against) exceeds their ceiling. Entries without a ceiling never appear.
+ */
+export declare function findOverCapAllowlistEntries(allow: readonly CompiledAllowlistEntry[], hits: readonly number[]): OverCapAllowlistEntry[];
 /**
  * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
  * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.

package/dist/src/core/smoke-patterns.js

@@ -56,6 +56,14 @@ export function matchesSmokeError(line) {
     }
     return false;
 }
+/** `# max-hits: N` on its own comment line, case-insensitive. */
+const MAX_HITS_DIRECTIVE = /^#\s*max-hits:\s*(\S+)\s*$/i;
+function parseMaxHitsDirective(raw, at) {
+    if (!/^[1-9]\d*$/.test(raw)) {
+        throw new Error(`Invalid allowlist max-hits directive at ${at}: expected a positive integer (got "${raw}")`);
+    }
+    return Number.parseInt(raw, 10);
+}
 /**
  * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
  * First-match attribution is deterministic and cheap. A line matching
@@ -71,30 +79,67 @@ export function matchAllowlist(line, allow) {
  * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
  * pattern throws immediately: better to fail fast at CLI parse time than
  * to silently let a typo match nothing.
+ *
+ * A `# max-hits: N` comment sets the ceiling of the entry that follows it
+ * (other comment lines may sit between). A blank line or end of file with
+ * no entry after the directive is an error rather than a silently dropped
+ * cap, since a cap the operator wrote and the run ignored is the exact
+ * shape of failure this directive exists to prevent.
  */
 export function compileAllowlistFromFile(body, sourcePath) {
     const lines = body.split(/\r?\n/);
     const compiled = [];
+    let pending;
+    const assertNoOrphanDirective = () => {
+        if (pending) {
+            throw new Error(`Invalid allowlist max-hits directive at ${pending.at}: no entry follows it (the ceiling applies to the next non-comment line)`);
+        }
+    };
     lines.forEach((raw, index) => {
         const line = raw.trim();
-        if (!line || line.startsWith('#'))
+        const at = `${sourcePath}:${index + 1}`;
+        if (!line) {
+            assertNoOrphanDirective();
             return;
+        }
+        if (line.startsWith('#')) {
+            const directive = MAX_HITS_DIRECTIVE.exec(line);
+            if (directive)
+                pending = { maxHits: parseMaxHitsDirective(directive[1] ?? '', at), at };
+            return;
+        }
         try {
             compiled.push({
                 pattern: new RegExp(line),
                 source: line,
-                origin: `${sourcePath}:${index + 1}`,
+                origin: at,
+                ...(pending ? { maxHits: pending.maxHits } : {}),
             });
         }
         catch (error) {
             const message = toError(error).message;
-            throw new Error(`Invalid allowlist regex at ${sourcePath}:${index + 1}: ${message}`, {
-                cause: error,
-            });
+            throw new Error(`Invalid allowlist regex at ${at}: ${message}`, { cause: error });
         }
+        pending = undefined;
     });
+    assertNoOrphanDirective();
     return compiled;
 }
+/**
+ * Entries whose per-entry hit count (every matched line, error-class or
+ * not: the `N×` number the attribution block prints and the operator tunes
+ * against) exceeds their ceiling. Entries without a ceiling never appear.
+ */
+export function findOverCapAllowlistEntries(allow, hits) {
+    const over = [];
+    allow.forEach((entry, index) => {
+        const count = hits[index] ?? 0;
+        if (entry.maxHits !== undefined && count > entry.maxHits) {
+            over.push({ entry, hits: count, maxHits: entry.maxHits });
+        }
+    });
+    return over;
+}
 /**
  * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
  * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.

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

@@ -655,6 +655,12 @@ export interface TestOptions extends EngineLockWaitable {
      * checkers that consume a sample artifact after the run.
      */
     perfSamples?: string;
+    /**
+     * Seeded file-order shuffle for mochitest runs. `true` draws a fresh seed;
+     * a number replays one. Forwarded as mach `--shuffle` with the seed
+     * exported as `FIREFORGE_SHUFFLE_SEED` and stamped on the verdict line.
+     */
+    shuffle?: number | boolean;
 }
 /**
  * Options for the furnace apply command.

package/docs/configuration.md

@@ -219,6 +219,14 @@ 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).
 
+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
+many lines that entry may match in one run. The attribution block prints
+capped entries as `hits×/N`, and an entry that fires past its ceiling is
+reported and fails the run with exit 12, the same as an unallowed error. A
+directive with no entry after it is refused rather than silently ignored.
+
 ## Lock waits
 
 Every FireForge command that mutates the engine takes the engine-session

package/docs/exit-codes.md

@@ -7,25 +7,25 @@ branches on it, and CI uses it to decide whether to retry or escalate. The
 values live in `src/errors/codes.ts`. This file says what they mean and
 which error class produces each one.
 
-| Code | Name                   | Meaning                                                                                                                 | Produced by                                                                                       |
-| ---: | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined: declining is a successful run that chose not to proceed. | (none)                                                                                            |
-|    1 | `GENERAL_ERROR`        | Unspecified failure the operator has to act on.                                                                         | `GeneralError` (and `PreflightRefusalError`), `ParserFallbackError`, `ExecTimeoutError`           |
-|    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, 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                           |
-|    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`                                                                                    |
-|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                             | `ResolutionError`                                                                                 |
-|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. This is a bug in FireForge, not something the operator can fix.                     | `InternalInvariantError`                                                                          |
-|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw console errors that were not allowed in the smoke window.                                        | `SmokeRunError`                                                                                   |
-|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw the browser exit uncleanly before the window elapsed.                                            | `SmokeRunError`                                                                                   |
-|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away because `engine/` moved while the harness ran. This is not red. Re-run it.         | `InconclusiveVerdictError`                                                                        |
-|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it with a larger `--wait-lock`.                                 | `LockContentionError`                                                                             |
-|  130 | `USER_CANCELLED`       | The operator interrupted a prompt (Esc or Ctrl+C). 128 + SIGINT.                                                        | `CancellationError`                                                                               |
+| Code | Name                   | Meaning                                                                                                                                       | Produced by                                                                                       |
+| ---: | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined: declining is a successful run that chose not to proceed.                       | (none)                                                                                            |
+|    1 | `GENERAL_ERROR`        | Unspecified failure the operator has to act on.                                                                                               | `GeneralError` (and `PreflightRefusalError`), `ParserFallbackError`, `ExecTimeoutError`           |
+|    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, 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                           |
+|    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`                                                                                    |
+|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                                                   | `ResolutionError`                                                                                 |
+|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. This is a bug in FireForge, not something the operator can fix.                                           | `InternalInvariantError`                                                                          |
+|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw console errors that were not allowed in the smoke window, or an allowlisted shape fired past its `# max-hits` ceiling. | `SmokeRunError`                                                                                   |
+|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw the browser exit uncleanly before the window elapsed.                                                                  | `SmokeRunError`                                                                                   |
+|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away because `engine/` moved while the harness ran. This is not red. Re-run it.                               | `InconclusiveVerdictError`                                                                        |
+|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it with a larger `--wait-lock`.                                                       | `LockContentionError`                                                                             |
+|  130 | `USER_CANCELLED`       | The operator interrupted a prompt (Esc or Ctrl+C). 128 + SIGINT.                                                                              | `CancellationError`                                                                               |
 
 Usage errors that commander detects itself (an unknown command, an unknown
 or malformed option, a missing required argument) never reach a command

package/docs/machine-output.md

@@ -53,16 +53,16 @@ if (options.json === true) {
 
 ## Current surfaces
 
-| Surface                            | Shape                                                                | Notes                                                                                                                                                                                                                              |
-| ---------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status --json`                    | `{ schemaVersion: 1, … }`                                            | Error envelope on three engine preconditions                                                                                                                                                                                       |
-| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                        | Error envelope added in 0.44.0                                                                                                                                                                                                     |
-| `token list --json`                | `{ schemaVersion: 1, tokensCssPath, categories }`                    | Categories in file order, each with its tokens (`name`, `line`, `value`)                                                                                                                                                           |
-| `token show --json`                | `{ schemaVersion: 1, name, category, declarations }`                 | One entry per declaring block, with its selector trail and line                                                                                                                                                                    |
-| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [note=<class>] [log=<path>]` | Not JSON. A single final stdout line, sealed by `setStdoutSealed` so nothing can displace it. `log=` names the run's own complete output under `.fireforge/logs/`, so a piped or truncated run still leaves a re-readable artifact |
-| `lint --per-patch --report <path>` | `{ schemaVersion: 1, … }`                                            | Written to a file, never read back by FireForge                                                                                                                                                                                    |
-| `status --raw`                     | `git status --porcelain` lines                                       | Not JSON, but still a machine surface: it engages the same stdout discipline, so rules 3 and 4 apply and rules 1 and 2 do not. A clean tree prints nothing                                                                         |
-| `build` log announcement           | `Full build output: <path>`                                          | Not JSON. `build` prints no verdict line, so it names its run log directly on the way out                                                                                                                                          |
+| Surface                            | Shape                                                                                 | Notes                                                                                                                                                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status --json`                    | `{ schemaVersion: 1, … }`                                                             | Error envelope on three engine preconditions                                                                                                                                                                                       |
+| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                                         | Error envelope added in 0.44.0                                                                                                                                                                                                     |
+| `token list --json`                | `{ schemaVersion: 1, tokensCssPath, categories }`                                     | Categories in file order, each with its tokens (`name`, `line`, `value`)                                                                                                                                                           |
+| `token show --json`                | `{ schemaVersion: 1, name, category, declarations }`                                  | One entry per declaring block, with its selector trail and line                                                                                                                                                                    |
+| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [note=<class>] [shuffle=<seed>] [log=<path>]` | Not JSON. A single final stdout line, sealed by `setStdoutSealed` so nothing can displace it. `log=` names the run's own complete output under `.fireforge/logs/`, so a piped or truncated run still leaves a re-readable artifact |
+| `lint --per-patch --report <path>` | `{ schemaVersion: 1, … }`                                                             | Written to a file, never read back by FireForge                                                                                                                                                                                    |
+| `status --raw`                     | `git status --porcelain` lines                                                        | Not JSON, but still a machine surface: it engages the same stdout discipline, so rules 3 and 4 apply and rules 1 and 2 do not. A clean tree prints nothing                                                                         |
+| `build` log announcement           | `Full build output: <path>`                                                           | Not JSON. `build` prints no verdict line, so it names its run log directly on the way out                                                                                                                                          |
 
 `--raw` is why `cli.ts` reads `process.argv` for `--json` or `--raw` before
 dispatching. Rule 3 is about who owns stdout, and that question is settled
@@ -112,6 +112,18 @@ consumers should treat an unrecognised one as opaque. Current values:
 `stale-browser`, `stale-browser-kill-failed`, `marionette-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 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/testing.md

@@ -101,7 +101,7 @@ a slow build for a silently wrong test.
 Every test run ends with one machine-readable line:
 
 ```
-FIREFORGE-VERDICT: PASS|FAIL reason=… [note=<class>] [log=<path>]
+FIREFORGE-VERDICT: PASS|FAIL reason=… [note=<class>] [shuffle=<seed>] [log=<path>]
 ```
 
 Automation should branch on this line rather than on the raw process code,
@@ -117,6 +117,18 @@ text is written to stdout before the verdict line and into the run log, so a
 redirected run keeps the reason as well as the verdict. See
 [`run-logs.md`](run-logs.md).
 
+## 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.
+
 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
 the run never started. See [`exit-codes.md`](exit-codes.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.46.2",
+  "version": "0.47.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -66,8 +66,8 @@
   "devDependencies": {
     "@eslint/js": "^10.0.0",
     "@types/estree": "^1.0.8",
-    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "^5.0.0",
     "dpdm": "4.3.0",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
@@ -75,14 +75,14 @@
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.32.3",
+    "knip": "6.35.1",
     "lint-staged": "^17.0.4",
     "prettier": "3.9.6",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",
     "vite": "^8.0.7",
-    "vitest": "^4.0.18"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22.22.2"