@hominis/fireforge 0.51.0 → 0.53.0

package/docs/patch-workflow.md

@@ -109,7 +109,7 @@ adjacent to it, meaning the re-export would plausibly have to capture it:
   moz.build or test-manifest line, `*` globs included).
 
 A file in a sibling or nested directory is not adjacent, so a peer
-session's unexported test in `test/hominis-tiles/` no longer refuses a
+session's unexported test in `test/hominis-tiles/` does not refuse a
 patch that owns `test/hominis/browser.toml`. The refusal names every file
 with its anchor (`beside engine/<dir>` or `registered by engine/<carrier>`).
 
@@ -139,8 +139,8 @@ fireforge re-export 102 200 --refuse-adjacent-unmanaged --refuse-foreign-drift \
 
 `--expect-from <file>` reads `--expect` paths from a file, one per line,
 with blank lines and `#` comments ignored. Under zsh a list held in one
-variable reaches FireForge as a single argument, and splitting it by hand
-left every path after the first as a positional patch name.
+variable reaches FireForge as a single argument, and a file avoids splitting
+it by hand.
 
 Arguments are checked before the run queues for the engine lock: an empty
 or unknown patch name, a positional that is an engine file (the refusal
@@ -192,6 +192,11 @@ exception. Removing every file would empty the patch and requires `patch
 delete` (or `patch retire`, which keeps the order number) instead.
 `--expect-removed` cannot combine with `--scan`, `--files` or `--all`.
 
+The same run drops every staged declaration, registration or forward
+import, in any patch of the queue, whose `creates` path it retired and no
+other patch still owns. It prints each one (`would drop` in a dry run) and
+records the drop in the history log (`re-export-staged-prune`).
+
 ### Forward imports and new modules
 
 A re-export (plain or `--scan`) refused because a file imports a module a
@@ -203,14 +208,35 @@ placeholder. A refused `--scan` adoption, `patch move-files` or `patch split`
 also writes every declaration it proposes into one lint-report-shaped JSON
 (`--declarations-out <path>`, by default under `.fireforge/declarations/`)
 and names the single `patch staged-dependency <holder> --add --from <file>`
-call per holding patch that discharges them all. Moving tests out of a patch
-that owns a shared manifest no longer needs one declaration typed per
-manifest line.
+call per holding patch that discharges them all, so moving tests out of a
+patch that owns a shared manifest needs no declaration typed per manifest
+line.
+
+For `patch move-files`, `patch split` and a placed `export`:
+
+- The projection of `patch move-files`, `patch split` and a placed `export`
+  lints with the queue's whole lint configuration, as the committed `lint
+--per-patch` gate does. With `patchLint.forwardRegistration: "extended"`,
+  a shared test manifest's suite entries (`["browser_*.js"]`) are projected
+  with the move and written to the `--declarations-out` report, not only its
+  `support-files` lines. A dry run that reads clean stays clean after the
+  move.
+- A refused `move-files --create` or `split` report names the patch the
+  rerun creates as the `owner` (its planned `<order>-<category>-<name>.patch`).
+- The declarations `move-files` and `split` write, and every entry of their
+  report, carry a `reason` naming the move, such as
+  `"201-ui-tests.patch → 236-ui-suites.patch by patch move-files"`. The
+  `--add --from` call the refusal prints then needs no `--reason`; an
+  entry's own reason wins over the flag.
 
 A re-export also drops a staged registration whose `creates` path no patch
 in the queue owns any more, for example after a merge deleted the file it
 registered. The dry run names the drop, and the write records it in the
-history log (`re-export-staged-prune`).
+history log (`re-export-staged-prune`). A registration whose
+`creates` file exists in engine/, or is an `--expect-new` path of the run,
+is kept and named ("kept: file exists but no patch owns it yet"): the
+manifest owner can re-export after the declaration and before the scan
+that adopts the file, in either order.
 
 An `export --order` (or `--before`/`--after`) refused on a new system
 module that no patch registers in moz.build says "register first". When the
@@ -236,13 +262,61 @@ The re-export policy gate checks the `filesAffected` the export will write,
 and only for the patch being written, so one patch's stale row cannot fail
 the other patches in the same call.
 
+### Registering files
+
+`fireforge register <path>` adds a new file's line to the build manifest
+that packages or runs it: a jar.mn, a moz.build list, a test manifest. Most
+manifests are kept in sorted order, and the entry is inserted
+alphabetically. `--after <entry>` places it after the line containing that
+substring instead, where the manifest's rule supports it. Elsewhere the
+flag is ignored with a warning, and an `--after` that matches nothing falls
+back to sorted order with a warning.
+
+An xpcshell test (`test_*.js` outside `browser/base/content/test/`) goes
+into its directory's `xpcshell.toml` as a `["test_*.js"]` section, placed
+as follows:
+
+- The new section is inserted ahead of the `#` comment lines directly above
+  the entry it precedes, never between a comment and the entry it describes.
+- `--after <entry>` places the new section after the named entry's whole
+  block, with its keys and before the next entry's comment. An exact
+  section name matches first, then a substring.
+
+```sh
+fireforge register browser/components/hominis/test/unit/test_HominisStoreQuota.js \
+  --after test_HominisStore.js
+```
+
+`--create-manifest` scaffolds a missing manifest and wires it into the
+nearest moz.build instead of refusing with "Manifest not found".
+
 ## Queue maintenance
 
 Under `fireforge patch`:
 
 - `patch compact` closes ordinal gaps, and is range-aware when
   `patchPolicy.ranges` is configured.
-- `patch reorder` moves a patch.
+- `patch reorder` moves a patch. `patch reorder --shift <n>
+--from <order> [--through <order>]` (no patch name) renumbers a run of
+  patches up by `n` in one transaction, to open room for inserts.
+  `--through` defaults to the end of the run of consecutive occupied orders
+  of `--from`'s category. Retired and reserved slots inside the run move
+  with it (a moved reservation is named, so its holder can be told). A shift
+  that would land on an order a patch or slot holds past the run is refused.
+  Under `patchPolicy.allowGaps: false` the opened orders are recorded as
+  reservations (owner `patch reorder --shift`), so the queue stays valid,
+  and the `export --order` or `split --order` that takes each one fills it.
+  The shift checks the patch policy, projects the cross-patch lint
+  (refusing only on errors the shift adds), and commits under the patch
+  lock, refusing if the plan changed while it waited for confirmation.
+  `--map-out <file>` on `reorder` (every mode) and on `split` writes the
+  committed old-to-new filename map as a JSON object, so references to the
+  renumbered patches can be rewritten from the file:
+
+  ```sh
+  fireforge patch reorder --shift 4 --from 104 --through 128 --map-out shift-map.json --yes
+  ```
+
 - `patch split <source> --files <paths...> --name <name>` carves files out of
   a patch into a new one as a single transaction, including staged-dependency
   owner rewrites, and supports `--dry-run`. `patch move-files <from> <to>
@@ -253,6 +327,23 @@ Under `fireforge patch`:
   declaration whose declaring file moved goes with it, and a declaration the
   move makes unused is dropped. The patch policy, including the gap rule, is
   checked before any lint runs.
+- `patch move-files` covers a whole split in one call:
+  - `--scan-file <path>` (repeatable) adopts a new engine file that no patch
+    owns into the destination (`<to>`, or the patch `--create` makes) in
+    the same transaction. Both bodies are linted as the transaction leaves
+    them, so the source is never judged on a body grown by an adoption the
+    move would shrink again. An owned or missing path is refused.
+  - `--retire-empty` lets a move into an existing patch take every file of
+    the source: the declarations whose `owner` is the source re-point to the
+    destination, the source's own declarations go with its files (one that
+    becomes self-owned is dropped), and the source is retired as by `patch
+retire`, its order kept as a retired slot. Without the flag, a move that
+    would empty the source is refused and names the flag.
+  - A per-patch size refusal on either side names a tier change behind it,
+    for example `Tier change: the source becomes test tier (it was general
+tier): 9634 lines against 6000.` A source that keeps only test files is
+    held to the test tier's ceiling for every line, so move its test files
+    out before its last product file.
 - `patch rename` also supports `--category` and `--order`.
 - `patch retire <name>` removes a patch like `patch delete` (same dependency
   refusal, `--dry-run` and confirmation) but keeps its order number as a
@@ -268,7 +359,7 @@ compact` renumbers through retired slots like any other gap.
   nothing owns it, so `status` would report it unmanaged. Delete those files
   first, or pass `--delete-created` to remove them as part of the confirmed
   operation (under the engine lock as well). Files the patch only modifies
-  keep their edits and become unmanaged, as before.
+  keep their edits and become unmanaged.
 - `patch reserve <order> --category <c> --owner <label> [--reason <text>]`
   holds an order for a patch a session has agreed to export but has not
   exported yet. The reservation lives in `patches.json#reserved`. Like a
@@ -289,22 +380,32 @@ hash-object` and `git update-index`. A collision (two rows at one order) or
   an invalid result is refused before the index is touched. The working copy
   is never changed and nothing is committed. Name a patch the working copy
   no longer has by its HEAD filename to stage its removal, and name both
-  filenames of a renamed patch.
+  filenames of a renamed patch. Every manifest write, a
+  re-export's row update included, puts every row, changed or not, in the one
+  canonical key order that `patch stage` writes, so after a write the working
+  copy and the index do not differ on key order alone.
 - `patch staged-dependency <name> --remove` names the entries to remove by
   any of `--file`, `--specifier`/`--line`, `--creates` and `--owner`. It needs
   `--creates`, or `--file` with the matcher. `--creates` alone removes every
   declaration for that created path, which is the cleanup after a merge
   deletes it. Registration lines compare whitespace-insensitively, as the
-  lint does. A selection that matches nothing is refused with exit 8 (it used
-  to print "no staged registration matched" and exit 0), on a dry run too.
+  lint does. A selection that matches nothing is refused with exit 8, on a
+  dry run too.
 - `patch staged-dependency <name> --add --from <json-file>` adds many
   declarations in one call under one lock hold. The file is a `lint
 --per-patch --report` document (its findings' `stagedDeclarations` for
   that patch) or a JSON array of `{ file, specifier | line, creates, owner?,
 reason?, patch? }` entries; entries naming another patch are skipped, and
   `--reason` fills entries without one. Every `staged-dependency` call logs
-  only its delta (`added` / `removed`) in the history; records written
-  before 0.50.0 carry the whole `before` / `after` lists instead.
+  only its delta (`added` / `removed`) in the history. A history record may
+  carry the whole `before` / `after` lists instead.
+- `--add` (single or `--from`) on a declaration already present
+  (same file, specifier or line, creates and owner) with a different
+  `reason` replaces the reason in place, keeping the entry's position in its
+  list. The summary counts these apart from additions, as in
+  `updated the reason of 87`, and the history logs each as the old entry
+  removed and the new one added. An `--add` without a reason never clears
+  one.
 
 ### Parking a session's edits
 
@@ -332,7 +433,10 @@ resolves.
 
 `lint --per-patch --patches` accepts repeated flags, comma lists, full
 filenames or stems, bare order numbers, manifest names, category-prefixed
-slugs, and bare slugs.
+slugs, and bare slugs. A list is also split on whitespace, so
+a list held in one shell variable (`--patches "$P"` under zsh) selects every
+patch it names. A name that matches no patch is refused with that name, its
+nearest matches and the queue size, not with every patch in the queue.
 
 `lint --per-patch --max-warnings 0` is the warning-clean form for a release
 gate.
@@ -341,8 +445,8 @@ gate.
 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`
+there can be hundreds of them. The default, `--notices full`, prints every
+row. 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
@@ -361,7 +465,7 @@ programmatic API, with the file-size helpers `isTestFile`,
 `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. Since 0.51.0 the API also exports the measurement the size rules
+rule. The API also exports the measurement the size rules
 themselves take, `measurePatchSize(engineDir, diff, filesAffected, config)`
 (lines, test-file lines, files and registration files under the configured
 metric), `isPatchSizeRegistrationFile(file, globs)`, the per-line
@@ -391,8 +495,8 @@ the real type. See
 [`configuration.md`](configuration.md#patchlint) for the project hooks
 (`checkJsExtraShim`, `checkJsTestFiles`, `checkJsTestShim`).
 
-For release whitespace checks, use `npm run whitespace:check`. It still
-checks source diffs while excluding the diff syntax of generated
+For release whitespace checks, use `npm run whitespace:check`. It checks
+source diffs while excluding the diff syntax of generated
 `patches/*.patch` files.
 
 ### Linting single files
@@ -515,13 +619,14 @@ On a shared engine, `--patches <list>` judges only the named patches:
 `status` keeps the files each one owns or claims (and, with `--ownership` or
 the ownership checks, the rows naming it), and `verify` keeps the findings
 that name it. Patches are named the way `lint --per-patch --patches` names
-them (filename, stem, order number, manifest name or slug). A peer's drifted
-patch then no longer turns this session's gate red. The limit is the
+them (filename, stem, order number, manifest name or slug; repeated, or
+separated by commas or whitespace). A peer's drifted
+patch then does not turn this session's gate red. The limit is the
 point: an unmanaged file belongs to no patch, so a scoped run never judges
 unexported files, this session's included. Run the unscoped gate before a
 commit that should cover them. `lint --per-patch --patches` keeps every
 queue finding that names a scoped patch, even on a file the patch no longer
-touches (a stale `staged-dependency-unused` declaration, since 0.51.0). `verify --patches` keeps findings about the
+touches (a stale `staged-dependency-unused` declaration). `verify --patches` keeps findings about the
 queue as a whole (a `patches.json` that does not parse) whatever the scope.
 
 `verify` resolves every `resource:///modules/…` and `resource://gre/modules/…`
@@ -586,7 +691,7 @@ 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 previous pin as "from": `firefox.version` in the
 `fireforge.json` committed at the project's HEAD, the tree the queue was
-last applied to (since 0.50.0). The patch stamps follow on their own line
+last applied to. The patch stamps follow on their own line
 (`Patch stamps: 317 at 153.0esr, 5 at 153.3.0esr`), oldest first and
 compared as versions rather than strings, because patches untouched since an
 older hop keep their older stamp. When no committed pin precedes the target

package/docs/run-logs.md

@@ -8,16 +8,15 @@
 
 ## Why the tool holds the log, not the operator
 
-A run's diagnosis used to exist in exactly one place: the terminal. The
-convenient thing to do when output is long is
+Without a log, a run's diagnosis exists in exactly one place: the terminal.
+The convenient thing to do when output is long is
 `fireforge test … 2>&1 | tail -40`, which keeps the summary, discards the
 `TEST-UNEXPECTED-FAIL` lines that say what broke, and launders the exit code
-as well. Nothing else held the output: `runMachCapture` keeps a 2 MB
+as well. Nothing else holds the output: `runMachCapture` keeps a 2 MB
 in-memory tail that dies with the process, and the shard retry loop discards
 earlier attempts outright.
 
-The operator rule ("never pipe a run") was written down three times
-downstream and broken after each writing. That is a sign it is not an
+An operator rule ("never pipe a run") gets broken, so this is not an
 operator problem. The tool is the only party that can make the log survive
 the mistake.
 
@@ -25,7 +24,7 @@ the mistake.
 
 - **Complete output, never the echo filter's collapsed form.** The artifact
   exists so that whoever is diagnosing the run can re-read it. Shortening it
-  would bring back the loss it prevents. The one transformation applied is
+  would lose what it is kept for. The one transformation applied is
   the secret-masking pass below, which changes values but never line
   structure.
 - **Secret-shaped values are masked in the file, and only in the file.** The
@@ -94,11 +93,11 @@ away. The refusal's own explanatory text is written into the log, and to
 stdout, before the verdict line seals stdout.
 
 Both halves matter. The verdict seal routes everything the CLI error boundary
-renders afterwards to stderr, so a run captured with `> file` used to keep
+renders afterwards to stderr, so a run captured with `> file` would keep
 `FIREFORGE-VERDICT: FAIL reason=preflight` and nothing else. That rendering
 also happens after the run log is closed, so the artifact the verdict's own
-`log=` key pointed at held only the pre-test build. Writing before the seal
-fixes both without giving up the contract: the reason lands on both channels,
+`log=` key points at would hold only the pre-test build. Writing before the
+seal avoids both without giving up the contract: the reason lands on both channels,
 and the verdict is still the run's last stdout line.
 
 ## Where the path is announced

package/docs/testing.md

@@ -29,9 +29,7 @@ them:
 - **Mixed harnesses.** xpcshell and browser/mochitest paths in one request
   run as two consecutive mach invocations, the xpcshell half first. With
   `--build`, one pre-test build packages both halves (its coverage claim is
-  the union), and the second half runs build-less against it. Before 0.50.0
-  a mixed request was refused, and the documented split lost its coverage
-  claim to peers' scoped builds between the steps.
+  the union), and the second half runs build-less against it.
 - **`--repeat <n>`** runs the same selection n times. A `--build` builds
   once, and `--doctor` probes once. Every run is reported, so a flaky suite's
   rate is visible from one invocation.
@@ -108,11 +106,30 @@ and reports `missed`: that result is the signal to target the file the
 browser actually loads.
 
 A control on compiled source (C/C++, Rust, IDL, WebIDL, IPDL or YAML that no
-install manifest ships) can only reach the binary through a build. Without
+install manifest ships) can only reach the binary through a build. A
+header (`.h`, `.hh`, `.hpp`, `.ipdlh`) counts as compiled even when an
+`EXPORTS` install manifest copies it into `dist/include`: that copy only feeds
+other compiles. Without
 `--build` it is refused before the lock. With `--build` it is applied before
 the pre-test build, so the binary under test carries it, stays applied for
 every `--repeat` run, and is restored with a fresh mtime so the next build
-recompiles the original. The verdict adds `control-build=compiled`. A
+recompiles the original. That pre-test build is a full
+`mach build`, with a notice naming the control's files: the default
+`mach build faster` compiles nothing, so the control would still test
+the previous binary and report `missed`. The verdict adds
+`control-build=compiled`.
+
+FireForge also rebuilds after such a control. Restoring the
+source byte-exact does not unbuild the binary, which would keep the mutation
+until the next full build, so every later run would test the control. After the last
+run's restore, still under the same lock hold, it runs one more full
+`mach build` and records a fresh baseline. The verdict adds
+`control-restore-build=done` (or `=failed`). The baseline the control's build
+writes carries a `controlBuild` stamp (diff file, targets, time applied) that
+only a full build clears: if the run is killed before the restore build, or
+that build fails, the next `fireforge test` refuses with `note=control-built`
+until `fireforge build` succeeds, and a `test --build` escalates to a full
+build. `fireforge build --ui` compiles nothing and keeps the stamp. A
 build-less control whose packaging is not current is refused before the
 lock with the advice to add `--build`, instead of ending `inconclusive`
 after a full queue.
@@ -151,15 +168,18 @@ copy outside `engine/` and `components/`, the control targets the old side.
   signal pipeline after the harness has shut down and before the held
   locks are released. A restore already in flight is awaited, not
   repeated.
+- **The binary too.** A compiled control's binary is rebuilt
+  after the restore, under the same hold, and a binary still carrying a
+  control is refused (`note=control-built`) rather than tested. See above.
 - **Even after SIGKILL.** A SIGKILLed FireForge cannot restore, but the
   journal survives it. Every later `fireforge test` checks for it first,
   under the lock, before any gate or build: a file still holding the
   control's bytes is restored, with a notice; any other state refuses with
   `note=negative-control-pending` rather than guess.
 
-The shorthand `--mutate <file> <old> <new>` that was proposed alongside this
-was not added. Commander options take one value, so a three-value option
-would have to swallow the positional test paths. A one-hunk diff expresses
+There is no `--mutate <file> <old> <new>` shorthand. Commander options take
+one value, so a three-value option would have to swallow the positional test
+paths. A one-hunk diff expresses
 the same edit and can be reviewed before it runs.
 
 ## Pathless runs must choose a mode
@@ -196,10 +216,30 @@ the run (and in the refusal, when other edits are stale). On a
 inputs of the sampled test and which lie elsewhere, so a sample whose fixture
 is unaffected can proceed knowingly under `--allow-stale-build`.
 
+### Compiled sources newer than the binary
+
+The packaging check above judges packaged files only. Every run
+also compares the compiled sources changed since the last build (C/C++,
+Rust, IDL, WebIDL, IPDL, and YAML such as `StaticPrefList.yaml`) with the
+time the binary under test was last linked: the newer of the launchable
+binary and the `libxul` beside it. Sources under `test`, `tests`, `gtest`,
+`testing` or `taskcluster` directories never reach that binary and are not
+counted. A newer source means the run would test the binary from before the
+edit, where a red reads as a failed fix. Without `--build` the run refuses
+with `note=stale-compiled`, naming the files and the link time, and suggests
+`fireforge build` or `test --build`; `--allow-stale-build` turns the refusal
+into a warning. With `--build` the pre-test build escalates to a full
+`mach build` with a notice, since `mach build faster` compiles nothing.
+
+Every run that reaches dispatch also stamps the binary's `BuildID` (from the
+`application.ini` beside it, the `moz:buildID` the browser reports) on its
+verdict line as `build-id=`, so a result can be matched to the build it ran
+against.
+
 ### Packaging coverage
 
 `--build-only` packages mixed-harness paths once, and then each harness half
-can run without `--build`. A plain mixed `test --build` now does both in one
+can run without `--build`. A plain mixed `test --build` does both in one
 invocation (see [Several runs under one lock hold](#several-runs-under-one-lock-hold)). Coverage is kept per staged path. Each path of a
 scoped build records its own staging inputs: its manifest directory (the
 nearest directory at or above it with a test manifest) plus whatever a
@@ -210,7 +250,7 @@ moved elsewhere in the engine, including a peer's edits and an engine HEAD
 move that touches none of them. A path whose inputs changed is dropped and
 named, with the inputs that changed. Changed inputs this build restages are
 allowed, and a scoped build of one file restages that file's test manifest
-too: a manifest that gained an entry for the new file no longer drops the
+too: a manifest that gained an entry for the new file does not drop the
 claims of its sibling files. A build-less run's packaging gates also run
 before the lock is requested, so a `coverage-replaced` or `stale-build`
 refusal arrives before the run queues.
@@ -219,15 +259,23 @@ A scoped build after a full build keeps the claim full while nothing outside
 its scope moved. Otherwise it carries the full build's anchor forward, and a
 later build-less run over any path stays covered while that path's own
 staging inputs are unchanged since the full build. A refusal names the inputs
-that did change.
-
-`--extend-coverage` remains accepted. Retention is now the default, so the
-flag only turns a drop into a refusal before the build. Before 0.50.0 a
-scoped build without the flag replaced the claim whenever anything outside
-its scope had changed, and the flag refused unless engine HEAD, the
-mozconfig and every staging input recorded by the previous build were
-unchanged. Baselines without complete staging-input fingerprints (older than
-0.49.0) cannot prove anything unchanged and are dropped once.
+that did change, and who wrote the coverage record: its
+invocation, when, and the writing process's pid (marked `still running`
+while it is), `FIREFORGE_SESSION_ID` and invocation id, the id its history
+records carry. `status --test-coverage` shows the pid and session too. A
+peer whose run a scoped build or a test-file edit refused can tell whose
+build to wait for.
+
+Retention is the default, so `--extend-coverage` only turns a drop into a
+refusal before the build. A baseline without complete staging-input
+fingerprints cannot prove anything unchanged, so its claims are dropped once.
+
+A scoped build records its request paths normalized (no trailing `/`, no
+`./`), as the baseline validator requires. An invalid baseline's refusal
+names the first failing field and its value, and when that field is part of
+the coverage claim it offers rerunning with `--build` as well as
+`fireforge build`. Dirty paths are fingerprinted unquoted, so a non-ASCII
+file name does not make the baseline invalid.
 
 ### Furnace components in a pre-test build
 
@@ -299,22 +347,21 @@ do something better instead: `testing/mochitest/runtests.py` bind-probes
 the HTTP server, ssltunnel and WebSocket ports before starting its servers,
 and the Marionette port before launching the browser, moves each busy one to
 a free port, and routes `mochi.test:8888` to wherever the server landed.
-FireForge's own refusal used to fire before that fallback could. In auto
-mode the mochitest-server and Marionette gates step aside, with a notice
+In the default mode FireForge's own refusal fires before that fallback can.
+In auto mode the mochitest-server and Marionette gates step aside, with a notice
 naming the holder, when the holder is not this checkout's own (a sibling
 checkout's live suite or an unrelated listener). This checkout's own
-leftovers are refused exactly as before, and `--kill-stale-marionette`
+leftovers are refused exactly as in the default mode, and `--kill-stale-marionette`
 still applies to them. Auto mode takes effect only when the engine's
 `runtests.py` carries the fallback; otherwise a notice says so and the
 default refusal stays. It never applies to `--doctor`'s Marionette probe,
-which launches its own browser on that port. The default (`"fixed"`) is
-unchanged.
+which launches its own browser on that port. The default is `"fixed"`.
 
 Every suite samples host load and the highest CPU process before and after
 dispatch. Load at least 4 or a process at least 90% CPU produces a warning;
 verdicts include `host-load` and, when needed, `host-cpu-warning=true`.
 Perf runs include `power-source=ac|battery|unknown`; on macOS this comes from
-`pmset -g ps`, including charging on AC. Sample JSON gains a `fireforgeHost`
+`pmset -g ps`, including charging on AC. Sample JSON carries a `fireforgeHost`
 object with start/end states and `powerSourceChanged`. A known power-source
 transition produces `FAIL reason=inconclusive power-changed=true`.
 Unknown power state is reported without inventing a transition.
@@ -349,7 +396,7 @@ Furnace-applied components:
   (untracked in the engine repo, so no install manifest exists for it yet),
   or when its jar declaration carries a bracketed base-directory prefix,
   which redirects the install destination away from the default chrome root.
-  An entry added to an existing `dist/bin` manifest no longer escalates. Any
+  An entry added to an existing `dist/bin` manifest does not escalate. Any
   probe failure (an unreadable manifest, no git) escalates, and the notice
   names the manifest and the reason.
 
@@ -361,16 +408,13 @@ carried forward from the previous full build, so a registration made between
 a `build --ui` and the next `test --build` still triggers the full build
 once.
 
-The 0.44.0 changelog left an open question here: whether a full build is
-really required for an entry added to an existing `dist/bin` `jar.mn`. It was
-settled downstream by exactly the experiment that entry asked for. In two
-clean runs, a jar-only registration of a new content file was installed by a
-plain `fireforge build --ui` (`faster/install_dist_bin_browser` named the
-destination, and the file reached `dist/bin` and the `.app` bundle) and then
-fetched over `chrome://` by a plain `fireforge test`. That case no longer
-escalates. The two halves the experiment did not cover, a new `jar.mn` file
-and a non-default install destination, still escalate, for the reason the
-original entry gives: relaxing a stale-artifact guard without evidence trades
+An entry added to an existing `dist/bin` `jar.mn` needs no full build: a
+jar-only registration of a new content file is installed by a plain
+`fireforge build --ui` (`faster/install_dist_bin_browser` names the
+destination, and the file reaches `dist/bin` and the `.app` bundle) and is
+then fetched over `chrome://` by a plain `fireforge test`. A new `jar.mn`
+file and a non-default install destination have no such evidence and
+escalate: relaxing a stale-artifact guard without evidence trades
 a slow build for a silently wrong test.
 
 ## Resilience
@@ -465,9 +509,9 @@ FIREFORGE-VERDICT: PASS|FAIL reason=… [note=<class>] [started=<n>/<m> first-un
 ```
 
 The start count reads every line the harness printed, not the last 2 MB of
-captured output: a suite printing more than that (a large browser directory,
-or any run under `--full-output`) used to report files that ran and passed
-as never started. `started-source=` names the evidence. A sharded run also
+captured output, so a suite printing more than that (a large browser
+directory, or any run under `--full-output`) does not report files that ran
+and passed as never started. `started-source=` names the evidence. A sharded run also
 prints a `FIREFORGE-SHARD:` line per shard and names the shards that did not
 pass as `failed-shards=`; see [`machine-output.md`](machine-output.md).
 
@@ -582,10 +626,38 @@ helpers.
 `--jobs <n>` runs a request's shards on n harness instances inside one lock
 hold. Each instance has its own profile and its own Marionette port, and
 auto ports (required) move each instance's mochitest server ports; output
-lines carry a `[job <i>]` prefix in the terminal and the run log. With
-`--no-shard`, or a single directory argument, the files are split in order
-into n contiguous chunks. Parallel browsers raise host load, so measure
-before relying on it.
+lines carry a `[job <i>]` prefix in the terminal and the run log. Each
+instance also writes its own mochitest test list
+(`--testrun-manifest-file`): on the harness's shared default
+`_tests/testing/mochitest/tests.json`, the second instance would run the
+first shard's file and pass, or find none. A `--jobs` run always reads each
+dispatch's mozlog raw log, and a dispatch whose raw log starts none of its
+requested files fails with `started=0/<m>` instead of passing on another
+shard's results. With `--no-shard`, or a single directory argument, the
+files are split in order into n contiguous chunks. Parallel browsers raise
+host load, so measure before relying on it.
+
+When the caller sets `MOZ_UPLOAD_DIR`, each `--jobs` instance gets its own
+`<MOZ_UPLOAD_DIR>/job-<i>` (created up front) instead of the shared
+directory, where instances would replace each other's fixed-name artifacts
+such as the `modifiedPrefs.json` pref census. The verdict names them as
+`upload-dirs=<dir>,<dir>,...` so a caller can merge per-instance artifacts.
+Without `MOZ_UPLOAD_DIR` nothing changes.
+
+A browser `--jobs` run on more than one instance also holds
+placeholder listeners on `127.0.0.1` on the mochitest HTTP, ssltunnel and
+WebSocket ports (8888, 4443, 9988) for the whole parallel hold, after the
+server-port preflight. Desktop mochitest has no flags for these ports, and
+its busy-port probe passes for instances that start together, which then
+race for 8888 and die with `could not start server on port 8888`. With the
+ports held, every instance's probe fails and each falls back to its own
+port; a port that is already busy is left alone. Each `FIREFORGE-SHARD:`
+line carries the ports its instance took as `ports=http:<n>,ssl:<n>,ws:<n>`.
+A harness whose server still fails to start (`could not start server on
+port` or `Timed out while waiting for server startup`, before any test) is
+an infrastructure failure, not `no-tests`: it is retried within the
+`--harness-retries` budget like a harness crash, and reported as
+`reason=server-startup` once the budget is spent.
 
 `--shard-size <n>` dispatches n files per mach invocation (mochitest restarts
 the browser between files), paying the harness start once per chunk instead
@@ -597,7 +669,9 @@ of once per file, and judges each file from mozlog's structured log:
 run-log line where the dispatch began) from mozlog's structured log, which
 each dispatch then writes with `--log-raw`, and names it on the verdict as
 `results=<path>`. A `--log-raw <file>` already forwarded with `--mach-arg` is
-read instead. The checks that need no lock run before it is
+read instead. A harness-level record (`test` is `automation.py`,
+such as a hung browser's no-output TIMEOUT) also carries `shardFiles`, the
+shard's dispatched files, and `file` when the shard has exactly one. The checks that need no lock run before it is
 requested: the launchable binary, the named-file checkJs pass, and the
 `--wait-browser`/`--wait-port` budgets. The run log is open from the start,
 so a `reason=lock-timeout` line carries `log=` too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",