@hominis/fireforge 0.51.0 → 0.53.0

package/docs/configuration.md

@@ -21,11 +21,10 @@ uncommitted pin, and the tree is then building a different version than the
 config claims.
 
 `fireforge source set`, `fireforge config <key> <value>` and `furnace init`
-edit `fireforge.json` in place (since 0.50.0). Only the values that change
+edit `fireforge.json` in place. Only the values that change
 are rewritten. Indentation, key order, and objects or arrays kept on one
 line stay as they are, so a pin move is a diff of the `firefox` block alone.
-New keys follow the layout of the object they land in. Before 0.50.0 every
-write re-serialized the whole file and expanded every compact section.
+New keys follow the layout of the object they land in.
 
 `fireforge doctor`'s "Source pin matches engine" check compares the pin with
 the engine's committed `browser/config/version.txt`. That file never carries
@@ -93,7 +92,7 @@ Most globals in it are `any`. `Cu` is typed as `CuShim`, the members of
 `nsIXPCComponents_Utils` (`js/xpconnect/idl/xpccomponents.idl`) with loose
 parameter and result types, so a call to a member `Cu` does not have (such
 as `Cu.now()`, which is `ChromeUtils.now()`) fails `typecheck` and per-patch
-lint instead of throwing at runtime (since 0.50.0). The same shim backs
+lint instead of throwing at runtime. The same shim backs
 `fireforge typecheck`.
 
 - `patchLint.checkJsExtraShim` adds members to the structured shim globals
@@ -137,7 +136,7 @@ lint instead of throwing at runtime (since 0.50.0). The same shim backs
   structured `stagedDeclarations`, so a `lint --per-patch --report` file
   can be applied with one `patch staged-dependency <patch> --add --from
 <report>` per patch instead of one call per edge. The setting is opt-in because a queue
-  that predates it can carry many such edges, and a new error would red a
+  that was never checked for these carriers can carry many such edges, and a new error would red a
   `--max-warnings 0` gate on install. The same census is on the public API as
   `findForwardRegistrations(patchesDir, { scope })`, which defaults to
   `'extended'`, for a consumer that keeps its own ratchet over these edges.
@@ -168,7 +167,7 @@ lint instead of throwing at runtime (since 0.50.0). The same shim backs
   what `file-too-large` counts. `'raw'` counts every line, the way `wc -l`
   does. `'code'` blanks comments with acorn's tokenizer (module first, then
   script, since chrome subscripts are scripts) and counts the lines left
-  non-blank, so JSDoc and blank lines stop counting. A file acorn cannot
+  non-blank, so JSDoc and blank lines do not count. A file acorn cannot
   tokenize is counted in raw lines, the upper bound, and a
   `file-size-unparsed` notice names it. Every message says which unit it
   counted ("lines" or "code lines"). The counter is on the public API as
@@ -260,7 +259,7 @@ lint instead of throwing at runtime (since 0.50.0). The same shim backs
   `@font-feature-values`, `@font-palette-values`, `@page` and its margin
   boxes) are descriptors, not properties, and are not judged.
 
-  Since 0.51.0 a scale also takes:
+  A scale also takes:
 
   - `prefix` as a list (`["--mybrowser-space-", "--mybrowser-gap-"]`) for a
     scale whose steps are spelled more than one way.
@@ -297,21 +296,37 @@ 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.
+`tsBuildInfoFile` are ignored.
 
-`typecheck.litTypes: true` (since 0.51.0, default off) types Lit in the
+`typecheck.litTypes: true` (default off) types Lit in the
 shim: `LitElement` and the helpers of
 `chrome://global/content/vendor/lit.all.mjs`, and `MozLitElement` of
 `chrome://global/content/lit-utils.mjs`. The element classes carry closed
 member lists, as `Cu` does, so a misspelt member of a widget host is an
 error rather than `any`. Template helpers and directives stay loose. It is
 off by default because a reactive property declared only in
-`static properties` or `static queries` then needs a constructor
-assignment or a JSDoc declaration to be known. A project shim can add
-members by merging `interface LitElementShimMembers`; a jsconfig `paths`
-entry that maps these URLs to real sources takes precedence.
+`static properties` or `static queries` then needs a declaration to be
+known. The shim declares the global type
+`MozLitElementWith<Extra>`: a widget casts its base to it, and its
+instances carry `Extra` beside MozLitElement's members. A query getter
+cannot be declared any other way: a class field redefines the getter
+MozLitElement installs and throws, and a constructor declaration reads it
+before `renderRoot` exists.
+
+```js
+const Base = /** @type {MozLitElementWith<{ input: HTMLInputElement }>} */ (MozLitElement);
+export class MozSearch extends Base {
+  static queries = { input: 'input' };
+}
+```
+
+Without `litTypes` (and under per-patch checkJs, which does not type Lit)
+`MozLitElementWith<Extra>` is `any`, as the base is, so the same source
+checks in both. A project shim can add members by merging
+`interface LitElementShimMembers`; a jsconfig `paths` entry that maps these
+URLs to real sources takes precedence.
 
-Per-patch checkJs gives each test script its own program. Since 0.51.0 a
+Per-patch checkJs gives each test script its own program. A
 test's `resource:///` and `chrome://` imports (including a
 `typeof import("…")` cast) resolve to the modules the queue creates up to
 the test's own patch, so a test of an earlier patch's module is checked
@@ -425,11 +440,11 @@ carries `invocationId` (shared by every record one command writes), `pid`,
 `ppid`, and `sessionId` when the environment sets `FIREFORGE_SESSION_ID`, so
 a session sharing the checkout can select its own lines.
 
-Before 0.50.0 the log was `patches/.fireforge-history.jsonl`, inside the
-tracked queue. The first append after upgrading moves it to `history.path`;
-when both files exist, the old records are appended to the new file rather
-than either being overwritten. Setting `history.path` to
-`patches/.fireforge-history.jsonl` keeps the old location.
+If a log exists at `patches/.fireforge-history.jsonl`, inside the tracked
+queue, the next append moves it to `history.path`; when both files exist, its
+records are appended to the `history.path` file rather than either being
+overwritten. Setting `history.path` to `patches/.fireforge-history.jsonl`
+keeps the log at that location.
 
 ## `buildAudit`
 
@@ -595,7 +610,7 @@ The dark and variant blocks mirror it and appear in `token show`.
 - `token-undeclared`: a `var(--<prefix>…)` in the tokens CSS, or in any CSS
   file a patch in the queue touches, names a token no block of the tokens
   CSS declares. A property declared in the same file, and the `furnace.json`
-  `tokenAllowlist` and `runtimeVariables` names, are exempt. Since 0.51.0 a
+  `tokenAllowlist` and `runtimeVariables` names, are exempt. A
   reference with a fallback (`var(--x, 0)`) is optional and not reported,
   and a token a sibling sheet declares counts as declared. Sheets are
   siblings when one queue document links both (`<link rel="stylesheet">`,
@@ -617,7 +632,7 @@ non-CI launches print a warning saying so. Exit codes 12 and 13 separate a
 console regression from a launch failure. See
 [`exit-codes.md`](exit-codes.md).
 
-A smoke run starts on a fresh temporary profile by default (since 0.48.0).
+A smoke run starts on a fresh temporary profile by default.
 The step exists to prove what the build does on a clean start. The
 developer's `obj-*/tmp/profile-default` carries whatever the last session
 left (a pre-reset database, a restored hand-made applet), and those reds
@@ -633,7 +648,7 @@ owning process is gone.
 
 - `--profile <path>` launches with a named profile directory and leaves it
   in place. Under `--smoke-exit` it replaces the fresh default. Firefox also
-  gets `-purgecaches` (since 0.50.0), which discards the profile's startup
+  gets `-purgecaches`, which discards the profile's startup
   cache of compiled chrome scripts. That cache is keyed on the build id, and
   a `build --ui` does not change it, so without the purge a kept profile runs
   the chrome scripts an earlier build cached. `--no-purge-caches` keeps the
@@ -643,12 +658,11 @@ owning process is gone.
   profile.
 
 A smoke run whose browser exits with a clean status before the window
-elapses, without printing any console output, fails with exit 13 (since
-0.50.0). Lines from mach's own log (the timestamped command echo) do not
+elapses, without printing any console output, fails with exit 13.
+Lines from mach's own log (the timestamped command echo) do not
 count as output. A launch that exits silently never reached a window: a
 stale `.parentlock`, or a profile whose run of SIGTERM-ended smoke runs
-counts as a startup-crash streak (`toolkit.startup.recent_crashes`). Before
-0.50.0 such a run passed as a clean exit.
+counts as a startup-crash streak (`toolkit.startup.recent_crashes`).
 
 A plain `run` without either flag keeps mach's `profile-default`. `mach run`'s
 desktop parser has no `--profile` option (its `--profile/-P` belongs to the

package/docs/exit-codes.md

@@ -29,8 +29,7 @@ which error class produces each one.
 
 Usage errors that commander detects itself (an unknown command, an unknown
 or malformed option, a missing required argument) never reach a command
-action. Before 0.46.0 commander terminated the process with its own exit 1
-and printed no refusal envelope under `--json`. `createProgram` now installs
+action. `createProgram` installs
 commander's `exitOverride()`, and the entry point maps the resulting
 `CommanderError` to `INVALID_ARGUMENT` (8) with the standard envelope on
 stdout. `--help` and `--version` take the same path and still exit 0, and so
@@ -46,10 +45,10 @@ action.
 change something, and a retry may then help. `INTERNAL_ERROR` means nothing
 they could change would have helped. Escalate it, do not retry.
 
-**Red, never ran, or thrown away.** These are three different facts, and
-before 0.44.0 two of them shared exit 1.
+**Red, never ran, or thrown away.** These are three different facts, each
+with its own code.
 
-- `BUILD_ERROR` (5) is a suite that failed. Since 0.45.0 it is thrown as
+- `BUILD_ERROR` (5) is a suite that failed. It is thrown as
   `TestFailureError`, which keeps the code but carries test remedies rather
   than build ones (`--json` reports it as `test-failure`).
 - `LOCK_TIMEOUT` (15) is a run that never started, because another FireForge
@@ -59,18 +58,16 @@ before 0.44.0 two of them shared exit 1.
   `engine/` moved underneath it. The code may be perfectly green, so
   reporting it as red is wrong.
 
-A summary line reading `FAIL - exit 1` beside `FAIL - exit 5` invited
-treating opposite facts as the same kind of thing. The codes now separate
-them. The `FIREFORGE-VERDICT:` line's `reason=` key carries the same
+Separate codes keep a summary line from showing opposite facts as the same
+kind of failure, such as `FAIL - exit 1` beside `FAIL - exit 5`. The `FIREFORGE-VERDICT:` line's `reason=` key carries the same
 distinction for humans.
 
 `LockContentionError` backs every lock in FireForge (engine session, patch
 directory, build, furnace), so all four exit 15. That is intentional: the
 fact is the same whichever lock was contended.
 
-**Interrupted or declined.** Before 0.44.0 a Ctrl+C and a deliberate "no" at
-a confirmation both returned the same value and exited 0, so a script could
-not tell them apart. They are now distinct: an interrupt raises
+**Interrupted or declined.** A Ctrl+C and a deliberate "no" at a
+confirmation are distinct, so a script can tell them apart: an interrupt raises
 `CancellationError` and exits 130, and a declined confirmation returns
 normally and exits 0, because the run did what it was asked and the answer
 was no.

package/docs/furnace.md

@@ -115,7 +115,7 @@ warning asking for the entry to be deleted. A run over one component judges
 only that component's entries. `deploy` honours the same entries when it
 validates, but leaves the staleness report to `validate`.
 
-An entry never suppresses an error (since 0.51.0): an error blocks apply,
+An entry never suppresses an error: an error blocks apply,
 and a review record cannot make a broken component deployable. The error
 stays counted, and the entry is reported as a
 `validation-exception-on-error` error until the finding is fixed and the
@@ -136,12 +136,30 @@ entries cover all of them:
 }
 ```
 
+An optional `file` narrows an entry the same way to findings
+in one module of the component, by file name. `hardcoded-text` names the
+modules it found text in, so a vendored bundle whose bytes are pinned (and
+so cannot carry a `furnace-ignore` comment) can be accepted while the
+authored modules beside it keep the check. An entry names a `tag` or a
+`file`, not both:
+
+```json
+{
+  "component": "moz-editor",
+  "check": "hardcoded-text",
+  "file": "moz-editor-codemirror.mjs",
+  "reason": "The vendored bundle's width probe is never rendered."
+}
+```
+
 Accessibility checks judge the composed component: the host
 `<tag>.mjs` and its companion modules (`<tag>-*.mjs`, tests and stories
 left out) read as one source. Moving a template between the component's
-modules therefore no longer changes its findings: a keyboard handler in a
+modules therefore does not change its findings: a keyboard handler in a
 companion covers an `@click` in the host, and an `@click` in a companion
-is judged too. Toolkit's `panel-item` counts as natively
+is judged too. `hardcoded-text` judges each module on its own, so a
+`// furnace-ignore: hardcoded-text` comment covers the file it is in, not
+its siblings. Toolkit's `panel-item` counts as natively
 keyboard-activated, beside `button`, form controls and the `moz-*` buttons.
 
 `minComponents` sets the fewest components a full `furnace validate` must

package/docs/lifecycle-invariants.md

@@ -25,7 +25,7 @@ command, read the decision table at the bottom first.
    exception: it writes nothing, runs its git plumbing on a private index
    (so even the `--intent-to-add` staging an untracked binary needs never
    reaches the shared `.git/index`), and serializes only against other dry
-   runs, so a preview no longer queues behind a peer's build or test run.
+   runs, so a preview does not queue behind a peer's build or test run.
 
 3. **A furnace mutation that does not finish restores the engine or says
    so.** Both a signal (SIGINT or SIGTERM) and a thrown error trigger a
@@ -33,14 +33,11 @@ command, read the decision table at the bottom first.
    `pendingRepair` marker blocks all further furnace mutations until
    `fireforge doctor --repair-furnace` reconciles.
 
-   The thrown-error half landed in 0.43.0. Before it, `runFurnaceMutation`'s
-   `finally` only deregistered the operation, and because it also set
-   `completed`, a body that threw removed itself from the signal handler's
-   view as well. A throw outside a body's own catch therefore left the
-   checkout torn with no marker. `applyAllComponents` was the live instance:
-   it rolls back on collected `result.errors` and `stepErrors`, but a throw
-   from its pre-loop or post-loop work escaped both. The wrapper now runs
-   cleanups, restores the journal, and rethrows the original error. A
+   On a thrown error `runFurnaceMutation` runs cleanups, restores the
+   journal, and rethrows the original error, so a throw outside a body's own
+   catch does not leave the checkout torn with no marker. `applyAllComponents`
+   rolls back on collected `result.errors` and `stepErrors`, but a throw from
+   its pre-loop or post-loop work escapes both and relies on the wrapper. A
    rollback failure becomes a marker plus a warning, never a replacement
    error.
 
@@ -70,17 +67,15 @@ command, read the decision table at the bottom first.
    refusal on structural conflicts (`--force-unsafe` to override), and a
    JSONL history entry appended only after the mutation succeeded. This
    covers metadata mutations too: `patch tier` and `patch lint-ignore` route
-   through `confirmDestructive`. They used to accept `--yes` without ever
-   prompting, so the flag only showed up in the history record. Enforced by
+   through `confirmDestructive`. Enforced by
    `patch-tier-and-lint-ignore.integration.test.ts`.
 
    The history log is write-only: FireForge appends to it and no command
    reads it back, so nothing depends on its contents or location. It lives
    at `.fireforge/history.jsonl` (or `fireforge.json#history.path`), outside
-   the tracked patch queue. Before 0.50.0 it was
-   `patches/.fireforge-history.jsonl`; the first append after upgrading
-   moves that file, and appends its records when both exist rather than
-   overwriting either. Each record carries `invocationId` (one per FireForge
+   the tracked patch queue. If `patches/.fireforge-history.jsonl` exists,
+   the next append moves it there, and appends its records when both exist
+   rather than overwriting either. Each record carries `invocationId` (one per FireForge
    process), `pid`, `ppid`, and `sessionId` when `FIREFORGE_SESSION_ID` is
    set, so a session sharing the checkout can select its own lines.
    Enforced by `history-log-file.test.ts`.
@@ -117,14 +112,14 @@ command, read the decision table at the bottom first.
    and `tree remove` refuses while a live PID holds a tree lock and checks
    that its `rm -rf` target is contained in the tree path.
 
-   In-tree `test` (0.41.0) is the one conditional carve-out, and it is
+   In-tree `test` is the one conditional carve-out, and it is
    marker-gated. mach objdirs embed absolute `topsrcdir` and `topobjdir`
    paths, so `tree create --with-objdir` rewrites the cloned objdir's
    `mozinfo.json` to the tree using the same safe-relocation rewriter that
    `build --rewrite-mozinfo` uses, scrubs the cloned `_virtualenvs` (they
    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
+   regenerated against the tree's paths rather than keeping the primary's.
    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
@@ -151,14 +146,14 @@ command, read the decision table at the bottom first.
    **Both halves of that enforcement fail closed on an unreadable state,
    because "we cannot tell" is not "there is nothing there."** A marker that
    exists but does not parse reports `corrupt`, not `absent`, and refuses the
-   command. Reading it as absent granted a snapshot the full mutating command
-   set on the strength of a file that failed to parse. A lock directory whose
+   command. Reading it as absent would grant a snapshot the full mutating
+   command set on the strength of a file that failed to parse. A lock directory whose
    owner cannot be identified reports `unknown`, not free, and refuses
-   removal. Since 0.45.1 `withFileLock` treats its owner-record write as
+   removal. `withFileLock` treats its owner-record write as
    fatal (`writeLockOwner` in `file-lock-owner.ts` removes the just-created
    directory and throws a `GeneralError` if the record cannot be written or
-   does not read back as written), so an owner-less lock is only ever left by
-   a pre-0.45.1 holder or by a crash inside that write. It is still refused,
+   does not read back as written), so an owner-less lock is left only by a
+   crash inside that write or by a holder that never wrote a record. It is refused,
    for the same reason. The one exception is a lock directory that vanished
    between the probe and the owner read: that is a clean release, and reads
    as free.
@@ -168,7 +163,7 @@ command, read the decision table at the bottom first.
    refusal spares the read-only commands that are unconditionally allowed
    (`status`, `lint`, `typecheck`, `verify`): their verdict never consults
    marker fields, so an unreadable marker cannot change their answer, and
-   blocking them left the operator unable to diagnose the very tree that
+   blocking them would leave the operator unable to diagnose the very tree that
    needs inspecting. `conditional` verdicts can write, and stay refused.
    Enforced by `tree-guard.test.ts` (verdict drift gate and corrupt-marker
    refusal), `tree-store.integration.test.ts` (marker tri-state,
@@ -208,7 +203,7 @@ command, read the decision table at the bottom first.
    `GIT_INDEX_FILE` from the repository's own index so that every refresh
    lands there and is discarded. `typecheck` additionally ignores a
    jsconfig's own `incremental` and `tsBuildInfoFile`, so no sidecar is
-   written under `engine/`. Its incremental build info (0.48.0) lives in the
+   written under `engine/`. Its incremental build info lives in the
    project's `.fireforge/typecheck/`, outside the engine. The scope fails open, meaning an unresolvable git dir
    simply does not install it, and it is not reentrant. This exists so that
    invariant 8 stays evidential: a concurrent `fireforge test` must not be
@@ -221,16 +216,14 @@ command, read the decision table at the bottom first.
     in `<lock>.waiters/` named `<startedAtMs>-<pid>-<uuid>` and deregisters in
     a `finally` that covers both outcomes: acquired the lock, or timed out.
     A newcomer that finds live tickets takes one before trying the lock at
-    all. Since 0.50.0 the tickets decide the grant: only the waiter with no
+    all. The tickets decide the grant: only the waiter with no
     live ticket ahead of it (arrival time, then ticket name) attempts the
-    lock, so "You are next" is a promise. Before, every waiter raced `mkdir`
-    and a waiter whose poll had backed off lost each free moment to later
-    arrivals. Because a ticket now blocks the queue, a dead one must not: a
+    lock, so "You are next" is a promise. Because a ticket blocks the queue, a dead one must not: a
     ticket whose PID is gone (or reused, where the start tick can tell) is
     skipped and removed, and one its owner has not refreshed for 30 s (every
     waiter rewrites its ticket every 5 s) is skipped, which covers a stopped
     waiter and PID reuse elsewhere. A registry that cannot be written falls
-    back to the old unordered contention rather than failing an acquisition.
+    back to unordered contention rather than failing an acquisition.
     This applies to every `withFileLock` lock: the engine-session, patch,
     furnace and build locks among them. `fireforge status --lock` and the
     `--wait-lock` progress lines read it, and the lines name the ordering
@@ -258,7 +251,7 @@ command, read the decision table at the bottom first.
     Enforced by `patch-manifest-repair.test.ts` (real temp queues) and the
     repair cases in `doctor.test.ts`.
 
-## Lock release (0.44.0)
+## Lock release
 
 `releaseLockIfOwned(lockPath)` in `src/core/file-lock.ts` is the
 ownership-checked removal for callers that hold no acquisition token.
@@ -266,13 +259,12 @@ Currently that is the signal-time furnace sweeper
 (`forceReleaseFurnaceLocksForActiveOperations`). It verifies the PID before
 removing, which is the half of `releaseLock`'s guard a sweeper can still
 perform: the sweeper knows which lock paths its own operations opened, but
-not the per-acquisition UUID they minted. The bare `rm` it replaced could
+not the per-acquisition UUID they minted. A bare `rm` could
 delete a lock that a different process had acquired in the window between our
 operation dying and the sweep running.
 
 `completeJournalRollback` in `src/core/furnace-operation.ts` owns the
-mutation-body rollback sequence that eight furnace commands previously
-duplicated verbatim. The ordering is the invariant: `markRolledBack()` runs
+mutation-body rollback sequence that eight furnace commands share. The ordering is the invariant: `markRolledBack()` runs
 before the restore, so a restore that itself fails does not leave the
 lifecycle wrapper replaying the same journal on the way out, and the original
 error is rethrown unless the rollback is what failed.
@@ -297,7 +289,7 @@ seconds while waiting, so a holder dying mid-wait cannot strand waiters until
 The owner-record write is fatal. A failed or unverifiable write releases the
 just-created lock and throws a `GeneralError` instead of running the
 operation. Without that, a lock with no readable owner is reaped by the age
-heuristic after 5 minutes, which for a multi-hour build meant a second holder
+heuristic after 5 minutes, which for a multi-hour build would mean a second holder
 inside the critical section. Covered by `file-lock.test.ts`, "owner record
 write at acquisition": write failure, corrupt read-back, recorded acquisition
 time.
@@ -312,8 +304,7 @@ other layer.
 Wait ergonomics are opt-in: `pollMaxMs` (the poll interval doubles from
 `pollMs` up to the cap) and `waitProgressMs` with `onWaitProgress` (a periodic
 progress callback carrying the holder's PID, liveness, and owner-metadata
-lines from the pid file). All three are inert when unset, so existing callers
-keep byte-identical behavior. Within one poll iteration a due progress probe
+lines from the pid file). All three are inert when unset. Within one poll iteration a due progress probe
 runs before the deadline check, so a wait that times out has always reported
 the holder at least once when its budget exceeds `waitProgressMs`, however
 slow the host (`file-lock.test.ts`, "budget shorter than one iteration").
@@ -321,8 +312,8 @@ slow the host (`file-lock.test.ts`, "budget shorter than one iteration").
 ### `src/core/file-lock-owner.ts`
 
 The owner record (the `pid` file) itself: its format (PID, token,
-`acquired-at-ms=` and `start-tick=` lines, plus free-form metadata, and older
-records without the mechanical lines still parse), the write-and-verify
+`acquired-at-ms=` and `start-tick=` lines, plus free-form metadata; a record
+without the mechanical lines parses too), the write-and-verify
 contract described above (a read-back that errors is retried before it counts
 as a failed write, while a missing or mismatching record fails immediately),
 and PID-reuse liveness.
@@ -333,13 +324,13 @@ re-verification, status snapshot and timeout message uses. Beyond
 tick (`/proc/self/stat` field 22), and the probe reads the candidate's tick
 from `/proc/<pid>/stat`. A different tick means a different process, so the
 lock is stale. A crashed build's PID handed to a long-lived daemon therefore
-no longer keeps the dead lock honoured until the waiter's timeout. It uses
+does not keep the dead lock honoured until the waiter's timeout. It uses
 ticks rather than wall-clock times because `btime` moves with clock steps, and
 a wall-clock comparison would reap a live holder after NTP steps the clock
 forward. macOS and Windows have no cheap start-time source (a `ps` spawn per
 poll is not worth it) and keep the PID-only answer, and so do records without
-a start tick. Enforced by `file-lock-owner.test.ts`: backward-compatible
-parsing, forged mechanical lines dropped, transient read-back error retried
+a start tick. Enforced by `file-lock-owner.test.ts`: parsing of records without the
+mechanical lines, forged mechanical lines dropped, transient read-back error retried
 versus persistent error versus mismatch, fake-procfs tick parsing, reused-PID
 versus genuine-holder verdicts, stepped-clock immunity, and on Linux a
 real-procfs `withFileLock` reap of a live-PID stale record.
@@ -360,9 +351,9 @@ log or the engine-session lock shows one in the window (`re-export-purity-scope.
 
 Contention fails fast after about a second by default, with the fixed message
 "Another FireForge engine-mutating command is already running. Wait for it to
-finish, then retry `<command>`." That message contract is unchanged, and it
-also closes the bounded wait. Each of those commands accepts
-`--wait-lock [seconds]` (bare flag means 60, valid 1 to 3600) for a bounded
+finish, then retry `<command>`." The same message also closes the bounded
+wait. Each of those commands accepts
+`--wait-lock [seconds]` (bare flag means 60, valid 1 to 86400) for a bounded
 operator wait instead: polling backs off exponentially from 100 ms to 2 s, and
 roughly every 5 s a progress line identifies the holder from the lock's
 owner-metadata lines, in the form `Waiting for the FireForge engine lock held
@@ -432,7 +423,7 @@ hold it.
 The destructive-operation contract: `confirmDestructive` (summary, prompt,
 `--yes`, `--dry-run`, conflict refusal, `--force-unsafe`) and the
 append-only history log (`src/core/history-log-file.ts` resolves its path,
-migrates a legacy `patches/.fireforge-history.jsonl`, and stamps each
+moves a `patches/.fireforge-history.jsonl` it finds to that path, and stamps each
 record's invocation and session).
 
 ### `src/core/tree-store.ts`

package/docs/machine-output.md

@@ -2,12 +2,9 @@
 
 # Machine-readable output contract (internal)
 
-The `--json` surface is a contract with scripted consumers. Before 0.44.0 it
-was four unrelated shapes: `status --json` and `tree list --json` shared a
-`schemaVersion: 1` envelope but disagreed on failure, `test` emitted a
-`FIREFORGE-VERDICT:` line, and `lint --per-patch --report` wrote a versioned
-file that nothing ever reads back. This file states what a `--json` command
-has to do, so the next one added does not invent a fifth shape.
+The `--json` surface is a contract with scripted consumers. This file states
+what a `--json` command has to do, so the next one added does not invent a
+shape of its own.
 
 ## The rules
 
@@ -56,11 +53,11 @@ if (options.json === true) {
 | Surface                            | Shape                                                                                                                                                                                                                                                                             | Notes                                                                                                                                                                                                                              |
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `status --json`                    | `{ schemaVersion: 1, … }`                                                                                                                                                                                                                                                         | Error envelope on three engine preconditions                                                                                                                                                                                       |
-| `status --json` under `--check`    | adds `check: { enabled, failOn, allow?, failOnUnknown?, failed, offenders }`                                                                                                                                                                                                      | Since 0.50.0 on the full payload too, not only `--summary`. `allow` and `failOnUnknown` appear only when set. An offender failing only through `--fail-on-unknown` carries `unnamed: true`. `--patches` adds `scope: { patches }`  |
+| `status --json` under `--check`    | adds `check: { enabled, failOn, allow?, failOnUnknown?, failed, offenders }`                                                                                                                                                                                                      | On the full payload too, not only `--summary`. `allow` and `failOnUnknown` appear only when set. An offender failing only through `--fail-on-unknown` carries `unnamed: true`. `--patches` adds `scope: { patches }`               |
 | `furnace validate --json`          | `{ schemaVersion: 1, passed, summary, maxWarnings?, components, issues, excepted, staleExceptions }`                                                                                                                                                                              | `issues` counts after `validationExceptions`, stale-exception warnings included. `excepted` carries each suppressed finding with its `reason`                                                                                      |
 | `check --json`                     | `{ schemaVersion: 1, verdict, reason?, summary, steps }`                                                                                                                                                                                                                          | One entry per step: `name`, `kind`, `command`, `status` (`pass`/`fail`/`skipped`), `exitCode`, `durationMs`, `detail`, and on failure `outputTail` (`timedOut` when killed at its budget). No verdict line under `--json`          |
 | `check` verdict line               | `FIREFORGE-VERDICT: PASS\|FAIL [reason=step-failures\|lock-timeout\|skipped-steps failed=<steps>] steps=<n> skipped=<n> [skipped-steps=<steps>]`                                                                                                                                  | Not JSON. The last stdout line, after the step table, sealed like `test`'s. Its `reason=` set is its own, not `test`'s                                                                                                             |
-| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                                                                                                                                                                                                                                     | Error envelope added in 0.44.0                                                                                                                                                                                                     |
+| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                                                                                                                                                                                                                                     | Error envelope on failure                                                                                                                                                                                                          |
 | `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                                                                                                                                                                    |
 | `token lint --json`                | `{ schemaVersion: 1, tokensCssPath, tokenPrefix, filesScanned, findings }`                                                                                                                                                                                                        | Each finding has `check`, `file`, `line`, `token`, `message`. The document is written even when findings exist; the exit is then non-zero, as with `status --check --json`                                                         |
@@ -80,7 +77,7 @@ it. Follow the rules above rather than inventing a shape.
 
 The run logs behind `log=` are specified in [`run-logs.md`](run-logs.md).
 
-Additive keys since 0.51.0 outside `test`:
+Additive keys outside `test`:
 
 - `check --json`: a skipped step carries `skipKind`, `config` when
   `check.skip` names it and `unavailable` when the project has nothing for
@@ -92,6 +89,8 @@ Additive keys since 0.51.0 outside `test`:
   `@click`). An exception that matched an error adds a
   `validation-exception-on-error` error, and a full run under
   `furnace.json#minComponents` a `component-floor` error on `furnace.json`.
+- `furnace validate --json`: a `hardcoded-text` finding
+  carries `files`, the component's module file names it was found in.
 
 ## Versioning
 
@@ -108,6 +107,7 @@ moved.
 | Reason              | Meaning                                                                                                                                                                                                                                                                                                                                                           |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `crash`             | The harness or the browser died, so there is no trustworthy suite result.                                                                                                                                                                                                                                                                                         |
+| `server-startup`    | A mochitest server never came up (`could not start server on port`, `Timed out while waiting for server startup`) before any test ran. An infrastructure failure, retried like `crash` within `--harness-retries`; this reason is what is left once the budget is spent.                                                                                          |
 | `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.                                                                                                                                                                                                                                                                                                                    |
@@ -124,15 +124,19 @@ developer browser holding the objdir. An unattended reader whose pipe kept
 only the verdict line could not tell those apart, so a preflight refusal that
 can classify itself also emits `note=<class>`.
 
-`note=` is additive, like `log=`, `signal=` and `shards=`. `reason=` is
-unchanged and still comes from the closed set above, so a consumer that
+`note=` is additive, like `log=`, `signal=` and `shards=`. `reason=` always
+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:
 `browser-busy`, `stale-browser`, `stale-browser-kill-failed`, `marionette-port-busy`, `mochitest-port-busy`,
 `coverage-replaced`, `stale-build`, `stale-components`, `no-launchable-binary`, `negative-control` (the
 control diff was refused), `negative-control-pending` (an interrupted run's
-control could not be undone safely). `note=negative-control-restore` rides a
+control could not be undone safely). Also `stale-compiled`
+(compiled sources changed after the binary under test was linked) and
+`control-built` (the binary still carries a compiled negative control whose
+restore build never ran or failed). An `invalid-build-baseline` refusal
+names the first failing field and its value. `note=negative-control-restore` rides a
 `reason=inconclusive` line whose control could not be restored byte-exact.
 
 ### Multi-run invocations: `FIREFORGE-RUN:`, `runs=` and `control=`
@@ -151,7 +155,7 @@ A `FIREFORGE-RUN:` line is never a verdict: the invocation still ends with
 exactly one `FIREFORGE-VERDICT:` line. With more than one planned run it
 carries `runs=<passed>/<planned>` and no count keys; a failed aggregate takes
 the most structural reason among its runs (`inconclusive`, `preflight`,
-`crash`, `harness-arguments`, `no-tests`, `test-failures`) and that run's
+`crash`, `server-startup`, `harness-arguments`, `no-tests`, `test-failures`) and that run's
 `note=`. A run that never started (the invocation stopped at a refusal)
 counts toward `<planned>` but not `<passed>`.
 
@@ -183,7 +187,7 @@ A sharded run prints one `FIREFORGE-SHARD:` line per finished shard, before
 the verdict line:
 
 ```
-FIREFORGE-SHARD: PASS|FAIL [reason=…] [checks=<n>] [unexpected=<n>] shard=<i>/<n> path=<label> [failed-files=<path>,…]
+FIREFORGE-SHARD: PASS|FAIL [reason=…] [checks=<n>] [unexpected=<n>] shard=<i>/<n> path=<label> [failed-files=<path>,…] [ports=http:<n>,ssl:<n>,ws:<n>]
 ```
 
 `path=` is the shard's path argument (whitespace replaced by `_`), or a
@@ -193,13 +197,31 @@ aggregate verdict appends `failed-shards=<label>,…` after `shards=` when any
 shard did not pass; under `--shard-size` `shards=` counts files and
 `failed-shards=` names files. Both are absent on a green run.
 
+`ports=` names the mochitest HTTP server, ssltunnel and
+WebSocket ports the shard's harness reported (its "falling back to port"
+lines), in that order and only those it reported; it is absent when the
+harness reported none (an xpcshell shard, or a harness that died before its
+servers). A shard whose server never started says `reason=server-startup`,
+and the aggregate verdict does too when every crashed shard failed that way.
+
 ### Additive keys of parallel and per-file runs
 
 `jobs=<n>` marks a `--jobs` run, `lock=shared` a run that held the engine
-session lock shared, and `results=<path>` names the `--results` document. A
+session lock shared, and `results=<path>` names the `--results` document.
+A `--jobs` run whose caller set `MOZ_UPLOAD_DIR` appends
+`upload-dirs=<dir>,…`, the per-instance upload directories
+(`<MOZ_UPLOAD_DIR>/job-<i>`, one per instance that ran), and a `--results`
+record whose `test` is `automation.py` (a harness-level result) carries
+`shardFiles`, plus `file` when its shard has exactly one file. A
 run whose engine changed mid-run only in files the running browser cannot
 see keeps its verdict and appends `drift-tolerated=<n>`. A negative control
-on compiled source appends `control-build=compiled`.
+on compiled source appends `control-build=compiled`, and
+`control-restore-build=done|failed` for the full build that recompiles the
+restored source after the last run. Every run that reaches
+dispatch appends `build-id=<BuildID>`, read from the launchable build's
+`application.ini` (absent when that file has no `BuildID`). A raw log
+that starts none of a dispatch's requested files counts as
+`started=0/<m> ... started-source=raw`.
 
 ### The additive `shuffle=` key
 
@@ -219,9 +241,8 @@ preflight, survivors of an earlier run in this objdir under `--reap-orphans`
 or `test.reapOrphans: "reap"`; at teardown, helpers this run's harness
 launched (httpd, websocket server, ssltunnel, process bridge, the browser,
 `moz-http2`) that were still alive after mach exited. Summed across the census, every
-retry attempt and every shard. Absent when nothing was reaped, so a green on
-a quiet machine prints the line it always did, and a green after a reap is
-distinguishable from it. A run ended by SIGTERM or by the parent-exit
+retry attempt and every shard. Absent when nothing was reaped, so a green after a reap is
+distinguishable from a green on a quiet machine. A run ended by SIGTERM or by the parent-exit
 watchdog writes its verdict before the teardown reap runs, so that line never
 carries the key; the reap is reported on stderr instead.
 
@@ -239,10 +260,10 @@ 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
+read from `pmset -g ps`, so charging on AC reads `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
+`reason=inconclusive`. The producer's sample JSON carries an additional
+`fireforgeHost: { start, end, powerSourceChanged }` object, 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.