@hominis/fireforge 0.48.0 → 0.49.0

package/dist/src/core/token-inventory.js

@@ -8,12 +8,12 @@
  * categories a project actually has, so the only way to name one correctly
  * was to hand-parse a neighbouring `= Category =` banner out of the file.
  * This module is that report. It reuses the banner and
- * `:root`-bounds primitives from `token-category.ts` rather than parsing
+ * category-region model from `token-category.ts` rather than parsing
  * tokens CSS a second way: two readers that disagree on what a banner is
  * would put `token list` and `token add` in different sections of the same
  * file.
  */
-import { categoryBannerNameAt, findBaseRootBounds, maskCommentLines } from './token-category.js';
+import { findBaseRootBounds, maskCommentLines, parseTokenCategorySections, } from './token-category.js';
 /** Matches a custom-property declaration and captures its name and value. */
 const DECLARATION_PATTERN = /^\s*(--[A-Za-z0-9_-]+)\s*:\s*([^;]*);?/;
 /**
@@ -32,14 +32,18 @@ export function collectTokenInventory(lines) {
     if (bounds === undefined || bounds.close === -1)
         return [];
     const masked = maskCommentLines(lines);
+    const sections = parseTokenCategorySections(lines);
+    const headers = new Map(sections.map((section) => [section.categoryLine, section]));
     const groups = [];
     let current;
+    let sectionEnd = bounds.close;
     for (let i = bounds.open + 1; i < bounds.close; i++) {
-        // Banners are read from the raw lines: `maskCommentLines` blanks comment
-        // bodies, which is exactly what a banner is.
-        const banner = categoryBannerNameAt(lines, i);
-        if (banner !== undefined) {
-            current = { category: banner, tokens: [] };
+        if (i >= sectionEnd)
+            current = undefined;
+        const section = headers.get(i);
+        if (section !== undefined) {
+            current = { category: section.name, tokens: [] };
+            sectionEnd = section.sectionEnd;
             groups.push(current);
             continue;
         }
@@ -48,6 +52,7 @@ export function collectTokenInventory(lines) {
             continue;
         if (current === undefined) {
             current = { category: null, tokens: [] };
+            sectionEnd = bounds.close;
             groups.push(current);
         }
         current.tokens.push({ name: match[1], line: i + 1, value: (match[2] ?? '').trim() });

package/dist/src/core/typecheck.js

@@ -26,6 +26,7 @@ import { sha256Hex } from '../utils/hash.js';
 import { verbose } from '../utils/logger.js';
 import { getPackageVersion } from '../utils/package-root.js';
 import { normalizePathSlashes } from '../utils/paths.js';
+import { withGeckoDomTypes } from './gecko-dom-types.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 /**
  * Sentinel string surfaced as a `TypecheckIssue.message` when the
@@ -252,7 +253,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
     // filtered out below, so the pass reports failures that do not exist.
     const shimPath = normalizePathSlashes(resolve(projectDir, `.fireforge-${SHIM_FILENAME}`));
     const rootFiles = [...parsed.fileNames, shimPath];
-    const defaultHost = ts.createCompilerHost(options);
+    const defaultHost = withGeckoDomTypes(ts, ts.createCompilerHost(options));
     const host = {
         ...defaultHost,
         getSourceFile(fileName, languageVersion, onError, shouldCreate) {
@@ -293,11 +294,10 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         program = ts.createProgram(rootFiles, options, host);
     }
     else {
-        const builder = ts.createIncrementalProgram({
-            rootNames: rootFiles,
-            options: { ...options, incremental: true, tsBuildInfoFile: buildInfoFile },
-            host: withSourceFileVersions(host),
-        });
+        // Always check the entire project in root order. Restoring TypeScript's
+        // per-file semantic cache makes checkJs inference depend on the first
+        // invalidated importer and can both invent and hide diagnostics.
+        const builder = ts.createEmitAndSemanticDiagnosticsBuilderProgram(rootFiles, { ...options, incremental: true, tsBuildInfoFile: buildInfoFile }, withSourceFileVersions(host));
         program = builder;
         // Under noEmit, emit() writes the build info and nothing else.
         writeBuildInfo = () => {

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

@@ -109,6 +109,8 @@ export interface SourceSetOptions {
  * Options for the build command.
  */
 export interface BuildOptions extends EngineLockWaitable {
+    /** Wait for the objdir browser before deploying/building. */
+    waitBrowser?: number | boolean;
     /** Fast UI-only rebuild */
     ui?: boolean;
     /** Number of parallel jobs */
@@ -368,6 +370,8 @@ export interface ReExportOptions extends EngineLockWaitable {
      * rather than hidden.
      */
     expectUnmanaged?: string[];
+    /** Explicitly retire named absent patch-created files in a scan-less export. */
+    expectRemoved?: string[];
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -551,6 +555,12 @@ export interface RunOptions {
  * Options for the test command.
  */
 export interface TestOptions extends EngineLockWaitable {
+    /** Queue behind a browser using this objdir; bare flag means 60 seconds. */
+    waitBrowser?: number | boolean;
+    /** Queue behind the mochitest/Marionette port holder. */
+    waitPort?: number | boolean;
+    /** Copy a file into the profile at a relative destination (repeatable source=destination). */
+    profileFile?: string[];
     /** Run tests in headless mode */
     headless?: boolean;
     /**
@@ -675,9 +685,10 @@ export interface TestOptions extends EngineLockWaitable {
      */
     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.
+     * Seeded isolated path-argument order for mochitest runs. `true` draws a
+     * fresh seed; a number replays the shard permutation. Native mach
+     * `--shuffle` within a shard remains unseeded. Also exported as
+     * `FIREFORGE_SHUFFLE_SEED` for custom task code and recorded on the verdict.
      */
     shuffle?: number | boolean;
 }

package/dist/src/utils/assert.js

@@ -11,13 +11,8 @@
  * says the opposite: nothing the operator could have done would have
  * prevented it.
  *
- * Every check routes through a helper here rather than being open-coded
- * as `if (!condition) throw`. An inline throw adds a
- * permanently-uncovered branch to every function it appears in, and the
- * per-module coverage floors in `scripts/check-coverage-thresholds.mjs`
- * would pay for it in ~40 places. Routed through a call, the branch lives
- * here once and is covered here once, and the `complexity` ceiling in
- * `eslint.config.js` does not see it at all.
+ * Shared helpers provide consistent classification and TypeScript narrowing,
+ * and keep expensive failure descriptions lazy on successful paths.
  *
  * This module is a leaf: it imports the error class and nothing else, per
  * the dependency-direction note in `src/utils/errors.ts`.

package/dist/src/utils/child-env.d.ts

@@ -1,8 +1,5 @@
 /**
  * Environment construction for spawned children.
- *
- * Its own module rather than a helper inside `process.ts` only because that
- * file sits on a 500-line budget. The logic belongs to the exec layer.
  */
 /** The `env` / `envUnset` slice of exec options this module needs. */
 interface ChildEnvOptions {

package/dist/src/utils/child-env.js

@@ -1,9 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Environment construction for spawned children.
- *
- * Its own module rather than a helper inside `process.ts` only because that
- * file sits on a 500-line budget. The logic belongs to the exec layer.
  */
 /**
  * The child's environment: `process.env`, with `env` merged over it, then

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

@@ -1,8 +1,8 @@
 /**
  * Bounded-concurrency helpers shared by commands that fan out per-file IO
  * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). Kept tiny: one order-preserving mapper, no
- * queues, no cancellation.
+ * the dry-run purity guard). On failure, stop scheduling new items and await
+ * every started operation before rejecting, so callers can safely clean up.
  */
 /** Maps items with at most `limit` in-flight promises. Preserves order. */
 export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/src/utils/concurrency.js

@@ -1,21 +1,32 @@
 /**
  * Bounded-concurrency helpers shared by commands that fan out per-file IO
  * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). Kept tiny: one order-preserving mapper, no
- * queues, no cancellation.
+ * the dry-run purity guard). On failure, stop scheduling new items and await
+ * every started operation before rejecting, so callers can safely clean up.
  */
 /** Maps items with at most `limit` in-flight promises. Preserves order. */
 export async function mapWithConcurrency(items, limit, fn) {
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw new RangeError('Concurrency limit must be a positive integer');
+    }
     const results = new Array(items.length);
     let next = 0;
+    const state = {};
     const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-        for (;;) {
+        while (!state.failure) {
             const index = next++;
             if (index >= items.length)
                 return;
-            results[index] = await fn(items[index], index);
+            try {
+                results[index] = await fn(items[index], index);
+            }
+            catch (error) {
+                state.failure ??= { error };
+            }
         }
     });
     await Promise.all(workers);
+    if (state.failure)
+        throw state.failure.error;
     return results;
 }

package/dist/src/utils/fs.js

@@ -99,7 +99,17 @@ export async function isSymlink(path) {
  */
 export async function copyFile(src, dest) {
     await ensureParentDir(dest);
-    await fsCopyFile(src, dest);
+    // Never follow a destination symlink or truncate a shared hardlink:
+    // build/deploy copies must not write through into components/ or a peer.
+    const tempPath = createAtomicTempPath(dest);
+    try {
+        await fsCopyFile(src, tempPath);
+        await renameWithRetries(tempPath, dest);
+        await syncParentDir(dest);
+    }
+    finally {
+        await rm(tempPath, { force: true });
+    }
 }
 /**
  * Reads a JSON file and parses it.

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

@@ -89,7 +89,22 @@ export declare function resolveWaitLockSeconds(value: string | number | boolean
  */
 export declare function sessionWaitLockMs(): number | undefined;
 /**
- * Recursively gives every command in the tree a `--wait-lock` flag: the
+ * Registers `--wait-lock [seconds]` on a command that takes no lock, so a
+ * scripted sequence can blanket-append the flag without hitting a usage
+ * error. A command that rejects it with "unknown option" kills the whole
+ * sequence with a usage error instead of a lock message.
+ *
+ * The flag is accepted and ignored here, never silently repurposed, and
+ * the help text says so, so nobody reads its presence as evidence that this
+ * command waits for anything.
+ *
+ * The value is parsed and validated exactly as the honoring variant does:
+ * `--wait-lock nonsense` must still be a usage error everywhere, or the
+ * uniformity would be a lie.
+ */
+export declare function addAcceptedWaitLockOption(command: Command): Command;
+/**
+ * Recursively gives every leaf command in the tree a `--wait-lock` flag: the
  * honoring registration where one already exists, the accept-and-ignore
  * one everywhere else.
  */

package/dist/src/utils/options.js

@@ -182,7 +182,7 @@ export function sessionWaitLockMs() {
  * `--wait-lock nonsense` must still be a usage error everywhere, or the
  * uniformity would be a lie.
  */
-function addAcceptedWaitLockOption(command) {
+export function addAcceptedWaitLockOption(command) {
     return command.option('--wait-lock [seconds]', 'Accepted for scripting uniformity and ignored: this command takes no FireForge lock', commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
 }
 /**
@@ -194,13 +194,15 @@ function hasWaitLockOption(command) {
     return command.options.some((option) => option.long === '--wait-lock');
 }
 /**
- * Recursively gives every command in the tree a `--wait-lock` flag: the
+ * Recursively gives every leaf command in the tree a `--wait-lock` flag: the
  * honoring registration where one already exists, the accept-and-ignore
  * one everywhere else.
  */
 export function ensureWaitLockOptionEverywhere(command) {
     for (const sub of command.commands) {
-        if (!hasWaitLockOption(sub))
+        // Commander groups otherwise capture a trailing leaf option before the
+        // action can see it. Register the uniform flag only on actionable leaves.
+        if (sub.commands.length === 0 && !hasWaitLockOption(sub))
             addAcceptedWaitLockOption(sub);
         ensureWaitLockOptionEverywhere(sub);
     }

package/dist/src/utils/paths.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { isAbsolute, relative, resolve } from 'node:path';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 const WINDOWS_ABSOLUTE_PATH = /^[a-zA-Z]:[\\/]/;
 const RELATIVE_PATH_ROOT = resolve('/__fireforge_path_root__');
 /**
@@ -55,7 +55,8 @@ export function isPathInsideRoot(root, candidate) {
         : resolve(resolvedRoot, candidate);
     const relativePath = relative(resolvedRoot, resolvedCandidate);
     return (relativePath === '' ||
-        (!relativePath.startsWith('..') &&
+        (relativePath !== '..' &&
+            !relativePath.startsWith(`..${sep}`) &&
             !isAbsolute(relativePath) &&
             !WINDOWS_ABSOLUTE_PATH.test(relativePath)));
 }

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

@@ -1,6 +1,5 @@
 /**
- * Process-group kill and post-run sweep helpers for the exec layer. Split
- * out of `process.ts` to keep that file within the per-file line budget.
+ * Process-group kill and post-run sweep helpers for the exec layer.
  * Spawn-based rather than `exec`-based so the two modules do not import
  * each other cyclically.
  */

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

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Process-group kill and post-run sweep helpers for the exec layer. Split
- * out of `process.ts` to keep that file within the per-file line budget.
+ * Process-group kill and post-run sweep helpers for the exec layer.
  * Spawn-based rather than `exec`-based so the two modules do not import
  * each other cyclically.
  */

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

@@ -1,9 +1,6 @@
 // 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';

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

@@ -150,8 +150,9 @@ export declare function execStream(command: string, args: string[], options?: St
  * 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 declare function trackChildClosure(): {
     settle: () => void;

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)
@@ -169,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
@@ -176,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.
@@ -194,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);
@@ -265,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/docs/configuration.md

@@ -149,17 +149,18 @@ 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/`.
+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`
 

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.
 

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`: