@hominis/fireforge 0.44.4 → 0.46.0

package/docs/configuration.md

@@ -7,6 +7,45 @@
 whose behaviour needs more than a schema line, plus the environment variables
 FireForge reads.
 
+## `firefox` — the source pin
+
+`firefox.version` (with `firefox.product`, and optionally `firefox.sha256` and
+`firefox.candidate`) is the source pin `fireforge download` resolves an archive
+from. `fireforge source set` writes it.
+
+The pin lives in `fireforge.json` beside hand-maintained policy sections, which
+is worth knowing when reverting that file: `git checkout -- fireforge.json`
+after an accidental reformat also reverts an **uncommitted** pin, and the tree
+is then building a different version than the config claims.
+
+### Archive integrity: `firefox.sha256` and `firefox.allowUnverifiedDownload`
+
+Every fresh download is checked against Mozilla's published `SHA256SUMS` for
+the release, and a mismatch fails the download and discards the archive. The
+check also **fails closed when the published digest cannot be obtained** — a
+404, a captive portal answering with an HTML page, a dropped connection or a
+timeout. TLS alone is thin trust for the artifact that becomes the git
+baseline every patch is built on, and "the checksum host was unreachable" is
+exactly the condition someone positioned on the network can arrange.
+
+- `firefox.sha256` pins the digest. It takes precedence over the published
+  file and is the right answer for reproducible builds and offline mirrors:
+  obtain it out of band and the download verifies with no network beyond the
+  archive itself.
+- `firefox.allowUnverifiedDownload: true` accepts a download when the
+  published digest is **unavailable**, with a loud warning. **This disables
+  the integrity check for that case** — the archive is trusted on TLS alone.
+  Use it only for a mirror you already trust, and prefer pinning `sha256`
+  instead. A digest that IS fetched and does not match is rejected regardless
+  of this setting. Ignored when `sha256` is set.
+
+`fireforge doctor` reports the pin beside what the checkout actually is — the
+engine's own `browser/config/version.txt` and the version the last download
+recorded — and warns when they disagree. It is a report, not a lock: a tree
+may legitimately be mid-migration. `product`, `sha256` and `candidate` have no
+recorded counterpart on disk, so the check does not claim to have verified
+them.
+
 ## External toolchains
 
 Projects with generated asset prerequisites can declare opt-in
@@ -33,6 +72,35 @@ shim that tracks upstream WebIDL additions per release.
 - `patchLint.checkJsTestShim` points at a project `.d.ts` whose typed
   declarations (e.g. a real `TestUtils` interface) override the loose
   baseline, so calls to nonexistent harness members fail at export time.
+- `patchLint.prettier` (`'off'` | `'warning'` | `'error'`, default `'off'`)
+  runs the project's configured Prettier over patch-owned `.sys.mjs`
+  modules. It runs from inside `engine/`, so `engine/.prettierrc*` and
+  `engine/.prettierignore` decide — the same command run from the repo root
+  can report a false pass when the root `.prettierignore` excludes
+  `engine/`. Prettier is resolved from `engine/node_modules`, then the
+  project's, then `npx --no-install`. **Left `'off'`, formatting is out of
+  scope for the per-patch tier**; no other tier checks `.sys.mjs`
+  formatting either.
+- `patchLint.fileSizeThresholds` tunes the `file-too-large` line counts per
+  file class:
+
+  ```json
+  {
+    "patchLint": {
+      "fileSizeThresholds": {
+        "general": { "notice": 500, "warning": 800, "error": 900 },
+        "test": { "warning": 1500 }
+      }
+    }
+  }
+  ```
+
+  Every field is optional and merges over the defaults (general
+  `500/750/900`, test `1200/1400/1600`). The merged triple must satisfy
+  `notice <= warning <= error`, which is validated at config load. Note that
+  under the recommended gate posture `--max-warnings 0` the `warning` band is
+  a hard failure, not a soft limit — which is what these thresholds exist to
+  let you move.
 
 ## `patchPolicy`
 
@@ -44,9 +112,55 @@ gaps does not move a patch out of the band its category owns.
 `test.canaryPath` and `test.canaryTimeoutSeconds` supply the defaults for
 `fireforge test --canary`. See [`testing.md`](testing.md).
 
+## `buildAudit`
+
+The post-build packaging audit is warn-only. Most of what it would otherwise
+report as "missing packaged artifact" is classified away structurally — an
+unselected `--with-branding` tree read from the generated `engine/mozconfig`,
+a directory reached only through a platform-gated `DIRS +=` in an ancestor
+`moz.build`, a Storybook `*.stories.mjs`. One case cannot be derived from the
+tree: a source that is deliberately never packaged, such as a type-only
+mirror whose header says it is never loaded. Declare those:
+
+```json
+{
+  "buildAudit": {
+    "unpackaged": [
+      {
+        "path": "browser/base/content/hominis-tile-host-types.js",
+        "reason": "Type-only mirror of the tile host; never loaded, no jar.mn entry by design."
+      }
+    ]
+  }
+}
+```
+
+- `path` is engine-relative. A `*` may glob **within one path segment**;
+  `**` is refused, because a subtree carve-out is how a reviewed exception
+  quietly becomes a blanket one.
+- `reason` is required and must be non-empty. This is the one audit class
+  FireForge cannot verify against the tree, so the declaration is the
+  evidence; an unexplained carve-out is indistinguishable from a mistake by
+  the time someone reads it.
+- Admitted paths are **listed** in the audit output
+  (`admitted as unpackaged by buildAudit.unpackaged "<path>" — <reason>`),
+  never silenced.
+- A declared path that DOES resolve to a packaged artifact is reported as a
+  **stale carve-out** rather than suppressed: the declaration asserts a fact
+  about the tree that is no longer true.
+- A declaration matching nothing that changed in a given run says nothing.
+  Unlike `--expect-unmanaged`, whose unmet entries are reported because it
+  is a per-invocation flag list, this is a standing list checked only
+  against the files that happened to change — "not met" is the normal case.
+
+The `Packaged:` summary line names each non-zero skip class with its count,
+so a run that dismissed four unselected-branding files reads differently
+from one that dismissed four unregistered sources.
+
 ## Design tokens
 
-Tokens are managed with `fireforge token add`.
+Tokens are managed with `fireforge token add`; `fireforge token list` and
+`fireforge token show` report what is already there.
 
 - `--create-category` declares a new category banner and inserts the token in
   one step. It is incompatible with `--variant`; author the category with the
@@ -71,6 +185,27 @@ Tokens are managed with `fireforge token add`.
   (`already exists in :root[…] (line N), unchanged`) rather than a bare
   no-op.
 
+### Reading the token file
+
+`token add --category` refuses a category the tokens CSS does not declare, so
+`token list` exists to name them without hand-parsing a `= Category =` banner
+out of the file.
+
+- `fireforge token list [--category <name>] [--json]` reports each category
+  banner with the tokens declared under it, in file order. Declarations above
+  the first banner are reported under `(no category)` rather than dropped, and
+  a banner with no tokens is still listed — `token add` accepts it. An unknown
+  `--category` is refused by naming the ones that exist, because a filter that
+  printed nothing would read as "this category is empty".
+- `fireforge token show <token-name> [--json]` reports the owning category and
+  the value the token takes in **every** block that declares it — the base
+  `:root`, the dark `@media` mirror, and each `:root[variant]` — with the line
+  of each. The leading `--` is optional; with it, pass the `--` separator
+  first (`fireforge token show -- --my-token`).
+
+Only the base `:root` block owns a token, so `token list` reports it once;
+the dark and variant blocks mirror it and appear in `token show`.
+
 ## Smoke runs
 
 For unattended smoke checks, `fireforge run --smoke-exit <s> --headless`

package/docs/exit-codes.md

@@ -7,25 +7,37 @@ branches on it, and CI decides whether to retry or escalate. The values live
 in `src/errors/codes.ts`; this file is the operator-facing statement of what
 they mean and which class produces each.
 
-| Code | Name                   | Meaning                                                                                                                  | Produced by                                                    |
-| ---: | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
-|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined — declining is a successful run that chose not to proceed. | —                                                              |
-|    1 | `GENERAL_ERROR`        | Unspecified failure the operator must act on.                                                                            | `GeneralError`, `ParserFallbackError`                          |
-|    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                     | `ConfigError` and subclasses                                   |
-|    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                            | `DownloadError` and subclasses                                 |
-|    4 | `GIT_ERROR`            | A git operation failed.                                                                                                  | `GitError` and subclasses                                      |
-|    5 | `BUILD_ERROR`          | `mach build` failed.                                                                                                     | `BuildError` and subclasses                                    |
-|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                        | `PatchError`                                                   |
-|    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                       | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError` |
-|    8 | `INVALID_ARGUMENT`     | The flags were wrong. Usage problem, not an environment one.                                                             | `InvalidArgumentError`                                         |
-|    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                    | `FurnaceError`                                                 |
-|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                              | `ResolutionError`                                              |
-|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. **A bug in FireForge**, not something the operator can fix.                          | `InternalInvariantError`                                       |
-|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw unallowed console errors in the smoke window.                                                     | `SmokeRunError`                                                |
-|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw a non-clean browser exit before the window elapsed.                                               | `SmokeRunError`                                                |
-|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away: `engine/` moved while the harness ran. **Not red** — re-run it.                    | `InconclusiveVerdictError`                                     |
-|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it, with a larger `--wait-lock`.                                 | `LockContentionError`                                          |
-|  130 | `USER_CANCELLED`       | The operator INTERRUPTED a prompt (Esc / Ctrl+C). 128 + SIGINT.                                                          | `CancellationError`                                            |
+| Code | Name                   | Meaning                                                                                                                  | Produced by                                                                                  |
+| ---: | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined — declining is a successful run that chose not to proceed. | —                                                                                            |
+|    1 | `GENERAL_ERROR`        | Unspecified failure the operator must act on.                                                                            | `GeneralError` (and `PreflightRefusalError`), `ParserFallbackError`, `ExecTimeoutError`      |
+|    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                     | `ConfigError` and subclasses                                                                 |
+|    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                            | `DownloadError` and subclasses                                                               |
+|    4 | `GIT_ERROR`            | A git operation failed.                                                                                                  | `GitError` and subclasses, except `GitNotFoundError`                                         |
+|    5 | `BUILD_ERROR`          | `mach build` failed, or a test suite went red.                                                                           | `BuildError` and subclasses, `TestFailureError`                                              |
+|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                        | `PatchError`, `PatchManifestCorruptError`, `RebaseError` and subclasses                      |
+|    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                       | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError`                               |
+|    8 | `INVALID_ARGUMENT`     | The flags were wrong. Usage problem, not an environment one.                                                             | `InvalidArgumentError`; commander usage errors (unknown command or option, missing argument) |
+|    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                    | `FurnaceError`                                                                               |
+|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                              | `ResolutionError`                                                                            |
+|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. **A bug in FireForge**, not something the operator can fix.                          | `InternalInvariantError`                                                                     |
+|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw unallowed console errors in the smoke window.                                                     | `SmokeRunError`                                                                              |
+|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw a non-clean browser exit before the window elapsed.                                               | `SmokeRunError`                                                                              |
+|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away: `engine/` moved while the harness ran. **Not red** — re-run it.                    | `InconclusiveVerdictError`                                                                   |
+|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it, with a larger `--wait-lock`.                                 | `LockContentionError`                                                                        |
+|  130 | `USER_CANCELLED`       | The operator INTERRUPTED a prompt (Esc / Ctrl+C). 128 + SIGINT.                                                          | `CancellationError`                                                                          |
+
+A usage error commander itself detects — an unknown command, an unknown or
+malformed option, a missing required argument — never reaches a command
+action, so before 0.46.0 commander terminated the process with its own exit
+1 and, under `--json`, no refusal envelope. `createProgram` now 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` travel the same path and still exit 0, and
+so does a command group invoked without a subcommand (`fireforge`,
+`fireforge tree`): commander prints the group's help and the entry point
+treats it as informational rather than as a wrong flag, matching the exit 0
+that `patch`, `token` and `furnace` give through their own help action.
 
 ## The three distinctions that matter for CI
 
@@ -35,7 +47,9 @@ change would have helped — escalate it, do not retry.
 
 **Red vs never-ran vs thrown-away.** These are three different facts and,
 before 0.44.0, two of them shared exit 1. `BUILD_ERROR` (5) is a suite that
-FAILED. `LOCK_TIMEOUT` (15) is a run that never started, because another
+FAILED — thrown as `TestFailureError` since 0.45.0, 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 process held the lock for the whole budget — nothing about the
 request was wrong, so re-queue it. `INCONCLUSIVE` (14) is a suite whose
 result was DISCARDED, because `engine/` moved underneath it — the code may

package/docs/lifecycle-invariants.md

@@ -12,7 +12,9 @@ mutating command, read the decision table at the bottom first.
 
 1. **Only `bin/fireforge.ts` terminates the process.** Library code
    propagates `CommandError` / `FireForgeError`; it never calls
-   `process.exit`. Enforced by the process-boundary test.
+   `process.exit`. Enforced at lint time by `no-restricted-properties`
+   (`eslint.config.js`), which bans `process.exit` everywhere and grants a
+   `bin/**` override.
 2. **At most one real engine/patch mutation runs at a time** per resource:
    CLI build/test/export/re-export/furnace mutations first take the
    `.fireforge/engine-session.lock`, then subsystem locks such as build,
@@ -127,12 +129,15 @@ tree.json` marker plus a default-deny command-verdict table
    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 owner cannot be identified reports
-   `unknown`, not free, and refuses removal — `withFileLock` creates the
-   lock directory before writing its owner record and treats that write
-   as non-fatal, so a live holder legitimately produces a lock with no
-   readable PID (a lock directory that vanished between the probe and the
-   owner read is the one exception: that is a clean release, and reads as
-   free). Each has one named escape (`--ignore-corrupt-tree-marker`,
+   `unknown`, not free, and refuses removal. Since 0.45.1 `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, because
+   "cannot tell" is not "nothing there" (a lock directory that vanished
+   between the probe and the owner read is the one exception: that is a
+   clean release, and reads as free). Each has one named escape (`--ignore-corrupt-tree-marker`,
    `tree remove --force`); neither has a silent one. The corrupt-marker
    refusal spares the unconditionally-**allowed** read-only commands
    (`status`, `lint`, `typecheck`, `verify`): their verdict never consults
@@ -240,11 +245,12 @@ error is rethrown unless the rollback is what failed.
 | Module                            | Owns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bin/fireforge.ts`                | The only `process.exit` call sites; SIGINT/SIGTERM pipeline; re-entrancy guard (a second Ctrl+C exits immediately); exit codes 130/143.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `src/core/file-lock.ts`           | Generic directory-as-lock (`mkdir` atomicity), owner PID **+ per-acquisition token** file, stale recovery via **rename-aside reaping** (dead PID unblocks immediately; ageless fallback after 5 min; the probe re-runs every ~5 s while waiting, so a holder dying mid-wait cannot strand waiters until `timeoutMs`), poll + timeout. Release verifies the lock still carries this acquisition's token before removing — a reaper-replaced lock is never deleted by its previous owner. Enforced by `file-lock.test.ts` (two-waiter reap race, mid-wait holder death, foreign-owner release). Releases in `finally` — which never runs across `process.exit`, hence invariant 5's other layer. Opt-in wait ergonomics: `pollMaxMs` (poll interval doubles from `pollMs` up to the cap) and `waitProgressMs`/`onWaitProgress` (periodic progress callback carrying the holder's PID, liveness, and owner-metadata lines from the pid file). All three are inert when unset — existing callers keep byte-identical behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `src/core/file-lock.ts`           | Generic directory-as-lock (`mkdir` atomicity), owner PID **+ per-acquisition token + acquisition time + start tick** file, stale recovery via **rename-aside reaping** (dead PID unblocks immediately; ageless fallback after 5 min; the probe re-runs every ~5 s while waiting, so a holder dying mid-wait cannot strand waiters until `timeoutMs`), poll + timeout. **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 — a lock with no readable owner is reaped by the age heuristic after 5 min, which for a multi-hour build meant a second holder inside the critical section (`file-lock.test.ts` "owner record write at acquisition": write failure, corrupt read-back, recorded acquisition time). Release verifies the lock still carries this acquisition's token before removing — a reaper-replaced lock is never deleted by its previous owner. Enforced by `file-lock.test.ts` (two-waiter reap race, mid-wait holder death, foreign-owner release). Releases in `finally` — which never runs across `process.exit`, hence invariant 5's other layer. Opt-in wait ergonomics: `pollMaxMs` (poll interval doubles from `pollMs` up to the cap) and `waitProgressMs`/`onWaitProgress` (periodic progress callback carrying the holder's PID, liveness, and owner-metadata lines from the pid file). All three are inert when unset — existing callers keep byte-identical behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `src/core/file-lock-owner.ts`     | The owner record (`pid` file) itself: format (PID, token, `acquired-at-ms=` and `start-tick=` lines, free-form metadata — older records without the mechanical lines still parse), the write-and-verify contract above (a read-back that ERRORS is retried before it counts as a failed write; a missing or mismatching record fails immediately), and **PID-reuse liveness**: `isLockOwnerAlive` is the liveness check every stale probe, reap re-verification, status snapshot and timeout message use. Beyond `isProcessAlive`, on Linux the record carries the writer's boot-relative start tick (`/proc/self/stat` field 22) and the probe reads the candidate's tick from `/proc/<pid>/stat`; a different tick is a different process, so the lock is stale — a crashed build's PID handed to a long-lived daemon no longer keeps the dead lock honoured until the waiter's timeout. Ticks, not wall-clock times: `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; 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 vs persistent error vs mismatch, fake-procfs tick parsing, reused-PID vs genuine-holder verdicts, stepped-clock immunity, and on Linux a real-procfs `withFileLock` reap of a live-PID stale record).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `src/core/engine-session-lock.ts` | Project-wide engine-session lock under `.fireforge/`, stamped with PID, command, and start time metadata. CLI `build`, `test`, `export`, `re-export`, `furnace apply`, `furnace deploy`, and `furnace sync` take it before subsystem locks — unconditionally, dry-runs included: a `re-export --dry-run` over an untracked binary legally touches the git index (temporary `--intent-to-add` staging), so holding the lock serializes even "read-only" previews against real writers. Dry-run purity is separately enforced at runtime by `withDryRunPurityGuard` (`re-export-bulk-scan.ts`), which fingerprints the engine tree and every patch artifact around the dry-run and fails hard on divergence. Contention fails fast after ~1 s 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 also closes the bounded wait. Each of those commands accepts `--wait-lock [seconds]` (bare flag = 60, valid 1..3600) for a bounded operator wait instead: polling backs off exponentially 100 ms → 2 s, and roughly every 5 s a progress line identifies the holder from the lock's owner-metadata lines (`Waiting for the FireForge engine lock held by PID 12345 (command=build, started=…) — 10s of up to 60s.`). The budget is not the engine lock's alone: it covers EVERY lock the command takes, which for the three furnace commands means the per-root furnace lock as well (see the `furnace-operation.ts` row). `FIREFORGE_WAIT_LOCK=<seconds>` sets the same budget for a whole session, parsed by the same bounds as the flag so the two cannot drift; an explicit budget at a call site always wins. Commands that take no lock accept `--wait-lock` and ignore it, so a scripted sequence can blanket-append the flag without a usage error killing the run. `fireforge test` also snapshots the engine git generation before and after the harness run and fails the verdict as invalid if the tree changes mid-run. |
 | `src/core/furnace-operation.ts`   | `runFurnaceMutation` lifecycle wrapper: per-root furnace lock, `pendingRepair` pre-flight refusal, in-flight operation registry (journal + cleanups + `completed` flag), signal rollback with bounded timeouts, `pendingRepair` persistence, furnace-lock force-release sweep. The lock's wait budget is `options.lockTimeoutMs` (threaded from `--wait-lock` by `waitLockMutationOptions`, which does the seconds→ms conversion once) falling back to `sessionWaitLockMs()` (`FIREFORGE_WAIT_LOCK`) and then to `DEFAULT_LOCK_TIMEOUT_MS`. The fallback is what covers the twelve furnace mutators that declare no flag (`create`, `remove`, `rename`, `refresh`, `scan`, `override`, `chrome-doc`, …). A contended refusal here names the FURNACE lock, says it is the second of two, and points at `--wait-lock`/`FIREFORGE_WAIT_LOCK` — a budget that is paid in full and then refuses anyway is the worst shape a budget can have, so the refusal must not read as the engine lock's.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `src/core/furnace-rollback.ts`    | The rollback journal itself: file snapshots and their restoration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `src/utils/assert.ts`             | The runtime-assertion primitive (`assert`, `assertDefined`, `expectDefined`) and, through `InternalInvariantError`, exit code 11. Checks state FireForge itself established — journal-before-mutation, lock-held-before-write, manifest order well-formedness — and is deliberately NOT input validation: anything derived from user input, the filesystem, or a subprocess stays a typed error from `src/errors/`. Every check routes through the helper rather than an inline `if (!c) throw` so the failure branch is covered once here instead of uncovered at every call site.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `src/utils/assert.ts`             | The runtime-assertion primitive (`assert`, `expectDefined`) and, through `InternalInvariantError`, exit code 11. Checks state FireForge itself established — journal-before-mutation, lock-held-before-write, manifest order well-formedness — and is deliberately NOT input validation: anything derived from user input, the filesystem, or a subprocess stays a typed error from `src/errors/`. Every check routes through the helper rather than an inline `if (!c) throw` so the failure branch is covered once here instead of uncovered at every call site.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `src/core/signal-critical.ts`     | Registry of signal-deferred critical sections (`runInSignalCriticalSection`). Pure registry — installs no handlers; the bin pipeline drains it with a bounded wait.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `src/core/patch-lock.ts`          | `withPatchDirectoryLock` — serializes patch filename allocation and manifest read-modify-writes. **Not reentrant**: callers must not already hold it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `src/core/destructive.ts`         | The destructive-operation contract: `confirmDestructive` (summary, prompt, `--yes`, `--dry-run`, conflict refusal, `--force-unsafe`) and the `.fireforge-history.jsonl` audit log.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -283,7 +289,9 @@ On SIGINT/SIGTERM, `bin/fireforge.ts`:
 ## Where this is tested
 
 - `src/core/__tests__/file-lock.test.ts` — lock acquisition, staleness, PID
-  recovery.
+  recovery, fatal owner-record write.
+- `src/core/__tests__/file-lock-owner.test.ts` — owner-record format
+  compatibility and PID-reuse liveness.
 - `src/core/__tests__/furnace-operation.test.ts` — wrapper lifecycle, signal
   rollback outcomes, `pendingRepair` semantics, lock force-release.
 - `src/core/__tests__/signal-critical.test.ts` — the critical-section
@@ -305,5 +313,3 @@ On SIGINT/SIGTERM, `bin/fireforge.ts`:
   stderr.
 - `src/commands/__tests__/tree.integration.test.ts` — real-program in-tree
   refusals and `--with-objdir` end-to-end against a synthetic objdir.
-- `src/__tests__/process-boundary.test.ts` — invariant 1 (`process.exit`
-  only in bin).

package/docs/machine-output.md

@@ -52,14 +52,16 @@ if (options.json === true) {
 
 ## Current surfaces
 
-| Surface                            | Shape                                                 | Notes                                                                                                                                                                                                                              |
-| ---------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status --json`                    | `{ schemaVersion: 1, … }`                             | Error envelope on three engine preconditions                                                                                                                                                                                       |
-| `tree list --json`                 | `{ schemaVersion: 1, trees }`                         | Error envelope added in 0.44.0                                                                                                                                                                                                     |
-| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [log=<path>]` | Not JSON. A single final stdout line, sealed by `setStdoutSealed` so nothing can displace it. `log=` names the run's own complete output under `.fireforge/logs/`, so a piped or truncated run still leaves a re-readable artifact |
-| `lint --per-patch --report <path>` | `{ schemaVersion: 1, … }`                             | Written to a file, never read back by FireForge                                                                                                                                                                                    |
-| `status --raw`                     | `git status --porcelain` lines                        | Not JSON, but a machine surface: it engages the same stdout discipline, so rules 3 and 4 apply and rules 1 and 2 do not. A clean tree prints nothing                                                                               |
-| `build` log announcement           | `Full build output: <path>`                           | Not JSON. `build` prints no verdict line, so it names its run log directly on the way out                                                                                                                                          |
+| Surface                            | Shape                                                                | Notes                                                                                                                                                                                                                              |
+| ---------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status --json`                    | `{ schemaVersion: 1, … }`                                            | Error envelope on three engine preconditions                                                                                                                                                                                       |
+| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                        | Error envelope added in 0.44.0                                                                                                                                                                                                     |
+| `token list --json`                | `{ schemaVersion: 1, tokensCssPath, categories }`                    | Categories in file order, each with its tokens (`name`, `line`, `value`)                                                                                                                                                           |
+| `token show --json`                | `{ schemaVersion: 1, name, category, declarations }`                 | One entry per declaring block, with its selector trail and line                                                                                                                                                                    |
+| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [note=<class>] [log=<path>]` | Not JSON. A single final stdout line, sealed by `setStdoutSealed` so nothing can displace it. `log=` names the run's own complete output under `.fireforge/logs/`, so a piped or truncated run still leaves a re-readable artifact |
+| `lint --per-patch --report <path>` | `{ schemaVersion: 1, … }`                                            | Written to a file, never read back by FireForge                                                                                                                                                                                    |
+| `status --raw`                     | `git status --porcelain` lines                                       | Not JSON, but a machine surface: it engages the same stdout discipline, so rules 3 and 4 apply and rules 1 and 2 do not. A clean tree prints nothing                                                                               |
+| `build` log announcement           | `Full build output: <path>`                                          | Not JSON. `build` prints no verdict line, so it names its run log directly on the way out                                                                                                                                          |
 
 `--raw` is why `cli.ts` reads `process.argv` for `--json` **or** `--raw`
 before dispatching: rule 3 is about who owns stdout, and that question is
@@ -92,3 +94,24 @@ what moved.
 | `inconclusive`  | A result exists but `engine/` moved under it, so it was discarded.                                                                                                                                                   |
 | `lock-timeout`  | The run never started: the engine session lock stayed contended.                                                                                                                                                     |
 | `killed`        | A signal terminated the run. Written from the signal handler so a log tail is always self-describing — a killed run must never be silent, or "killed", "still running" and "never started" become indistinguishable. |
+
+### The additive `note=` key
+
+A `FAIL reason=preflight` line covers every gate before the harness: a
+missing build, a peer's packaging record replacing this session's, a
+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
+classifies 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
+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;
+consumers should treat an unrecognised one as opaque. Current values:
+`stale-browser`, `stale-browser-kill-failed`, `marionette-port-busy`,
+`coverage-replaced`, `stale-build`, `stale-components`.
+
+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).

package/docs/patch-workflow.md

@@ -74,7 +74,8 @@ Every queue-mutating patch command accepts `--wait-lock [seconds]`; see
 ## Linting the queue
 
 `lint --per-patch --patches` accepts repeated flags, comma lists, full
-filenames/stems, manifest names, category-prefixed slugs, and bare slugs.
+filenames/stems, bare order numbers, manifest names, category-prefixed slugs,
+and bare slugs.
 
 `lint --per-patch --max-warnings 0` is the warning-clean form for a release
 gate.

package/docs/run-logs.md

@@ -22,9 +22,32 @@ mistake.
 
 ## The contract
 
-- **Raw bytes, never the echo filter's collapsed form.** The artifact exists
-  to be re-read by whoever is diagnosing the run; shortening it would
-  reintroduce the loss it prevents.
+- **Complete output, never the echo filter's collapsed form.** The artifact
+  exists to be re-read by whoever is diagnosing the run; shortening it would
+  reintroduce the loss it prevents. The one transformation applied is the
+  secret-masking pass below — it changes values, never line structure.
+- **Secret-shaped values are masked in the file, and only in the file.** The
+  terminal already showed every byte to the operator who ran the command; the
+  file is retained twenty deep and gets attached to bug reports, so it gets a
+  narrow redaction pass (`src/core/run-log-redact.ts`), applied per line
+  before the write (a line split across two chunks is held until its
+  terminator arrives — `\n`, or a lone `\r` from progress-bar repaints — or
+  it exceeds 1 MiB, or the log is closed). Exactly what is redacted:
+  - the value of an env-style assignment `KEY=value` whose `KEY` matches
+    `/(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i` — the value up to the
+    next whitespace, or a whole quoted string — is written as
+    `KEY=<redacted>`; the `--password=x` and `-DAUTH_TOKEN=x` spellings that
+    mach and configure echo from their argv are the same shape and are
+    masked too;
+  - the credential of an `Authorization:` header (`Bearer`, `Basic` and
+    `Token` keep the scheme word; any other value is masked whole).
+
+  Nothing else is. A bare token in a URL, a space-separated `--password foo`
+  argument, a JSON `"token": "…"` field, or a cookie passes through unchanged — the pass is a
+  seatbelt against the common accidental leak (mach echoing its environment),
+  not a guarantee that a log is free of secrets. Review a log before sharing
+  it.
+
 - **Opened before any preflight**, so a refusal is logged too. Those are
   exactly the runs whose only output a `tail` throws away.
 - **Retained 20 deep per command kind.** Per-kind, so a busy `test` loop
@@ -37,7 +60,24 @@ mistake.
   degrades to no log. A run must never fail over a diagnostic, so `openRunLog`
   returns `undefined` on failure, a post-open stream error latches `broken`
   and drops every later write, and pruning failures are logged verbosely
-  only.
+  only. The entry point's SIGINT/SIGTERM path closes the active log (also
+  best-effort) before exiting, so the held partial line of a killed run
+  reaches disk.
+
+## Preflight refusals
+
+`fireforge test` opens its run log before any preflight, so a refusal is
+logged too — those are exactly the runs whose only output a `tail` throws
+away. The refusal's own explanatory text is written into the log, and to
+stdout, **before** the verdict line seals stdout.
+
+Both halves are load-bearing. The verdict seal routes everything the CLI
+error boundary renders afterwards to stderr, so a run captured with
+`> file` used to keep `FIREFORGE-VERDICT: FAIL reason=preflight` and nothing
+else; and that rendering 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 trading away 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

@@ -49,8 +49,13 @@ components):
 - a changed `moz.build` / `moz.configure` / `Makefile.in` runs
   `mach configure` first;
 - a changed `jar.mn` escalates the whole build to a full `mach build`
-  (minutes rather than seconds), so that new install-manifest destinations
-  exist before the run.
+  (minutes rather than seconds) **only** when it is a NEW manifest
+  (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 probe failure (unreadable manifest, no git) escalates, and
+  the notice names the manifest and the reason.
 
 Each escalation is paid once per actual content change: a `jar.mn` that is
 dirty against HEAD but byte-identical to what the last full build consumed
@@ -60,20 +65,35 @@ 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.
 
-Whether a full build is really required for an entry added to an existing
-`jar.mn` under `dist/bin` is an open question, recorded in the 0.44.0
-changelog: mozbuild regenerates its backend from a newer `jar.mn` on any
-`mach build`, `faster` included, and the FasterMake backend consumes
-`dist/bin` jar manifests. The escalation stays until that is demonstrated
-end to end against a real objdir (`build --ui` after a jar-only
-registration, then a plain `test`), because relaxing a stale-artifact guard
-on source reading alone trades a slow build for a silently wrong test.
+The open question the 0.44.0 changelog recorded here — whether a full build
+is really required for an entry added to an existing `dist/bin` `jar.mn` —
+was settled downstream by exactly the experiment that entry asked for: two
+clean runs where 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, the file reached
+`dist/bin` and the `.app` bundle) and fetched over `chrome://` by a plain
+`fireforge test`. That case no longer escalates. The two halves the
+experiment did NOT exercise — a new `jar.mn` file, and a non-default
+install destination — still do, for the reason the original entry gives:
+relaxing a stale-artifact guard without evidence trades a slow build for a
+silently wrong test.
 
 ## Resilience
 
 - Recognized harness crashes retry up to `--harness-retries <n>` times
   (default 2).
 - `--kill-stale-marionette` terminates recognized stale browsers.
+- Every dispatch runs a **census of orphaned harness helpers** — `xpcshell`
+  (the harness httpd), `pywebsocket`, `ssltunnel`, `moz-http2` — that
+  survived an earlier run in this project's objdir. It runs at preflight,
+  before this run spawns anything, so every hit is a survivor by
+  construction; a match must be objdir-anchored, since `xpcshell` and
+  `server.js` are far too generic to report on their own. Survivors slow
+  every later run without appearing in its output (a three-second suite
+  taking minutes of wall clock is the usual symptom). Report-only by
+  default; `--reap-orphans` terminates them. It never refuses a run.
+  A different shape — reparented Python `multiprocessing` workers — is
+  covered by the `Orphaned harness workers` doctor check.
 - `--perf-samples <path>` publishes a perf-sample artifact path to the
   harness (exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
 
@@ -82,7 +102,7 @@ on source reading alone trades a slow build for a silently wrong test.
 Every test run ends with one machine-readable line:
 
 ```
-FIREFORGE-VERDICT: PASS|FAIL reason=… [log=<path>]
+FIREFORGE-VERDICT: PASS|FAIL reason=… [note=<class>] [log=<path>]
 ```
 
 Automation should branch on it rather than on the raw process code, and must
@@ -91,6 +111,13 @@ the stdout rules around the line are in
 [`machine-output.md`](machine-output.md); `log=` names the run's own complete
 output, specified in [`run-logs.md`](run-logs.md).
 
+`reason=preflight` covers every gate before the harness, so a refusal that
+classifies itself adds an additive `note=<class>` (`stale-browser`,
+`coverage-replaced`, …) naming which gate fired. The refusal's full text is
+written to stdout before the verdict line and into the run log, so a
+redirected run keeps the reason as well as the verdict — see
+[`run-logs.md`](run-logs.md).
+
 Exit code 14 (`INCONCLUSIVE`) is not red: it means `engine/` moved while the
 harness ran and the result was thrown away. Exit 15 (`LOCK_TIMEOUT`) means the
 run never started. See [`exit-codes.md`](exit-codes.md).
@@ -109,6 +136,38 @@ the build path stays quiet. It is opt-in rather than automatic because it
 changes how much a third party prints, and an operator who wants the quieting
 should keep it.
 
+## Known upstream teardown noise
+
+Recent engines can end a run with a Python traceback at harness teardown:
+
+```
+AttributeError: 'SystemResourceMonitor' object has no attribute 'stop_time'
+```
+
+(or `poll_interval`), raised from `mozsystemmonitor/resourcemonitor.py`. It is
+an upstream defect in the resource monitor's own shutdown, it is cosmetic, and
+it does not affect any verdict. It matters only because it lands exactly where
+a reader looks for the failure summary.
+
+FireForge recognizes this one signature — and only this one. Recognition
+requires **all** of: an `AttributeError` on `SystemResourceMonitor` naming one
+of those two attributes, a `resourcemonitor.py` stack frame, and (in a test
+run) a preceding `SUITE_END`. A novel attribute, a different exception, or the
+same traceback before shutdown is treated as a real failure and printed
+verbatim, always.
+
+The two phases handle it differently, deliberately:
+
+- **Tests** collapse the traceback in the terminal echo to one labeled
+  `[FireForge]` line. Captures and the run log keep the **raw** traceback, and
+  the classifier reads the raw form — a real failure always outranks this
+  signature in diagnosis.
+- **Builds** print it verbatim and add a note naming it. A build has no
+  `SUITE_END` — no boundary separating teardown from work still in progress —
+  so FireForge cannot distinguish cosmetic teardown noise from a real
+  build-time traceback there, and withholding the block would be the wrong
+  risk to take.
+
 ## Concurrency
 
 A test run holds the engine-session lock and snapshots the engine git