@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/utils/validation.js

@@ -19,7 +19,7 @@ export function isString(value) {
  * @returns True if value is a finite number
  */
 export function isNumber(value) {
-    // Number.isFinite matches the documented contract: NaN AND ±Infinity are
+    // Number.isFinite matches the documented contract: NaN and ±Infinity are
     // excluded (a JSON config field of 1e999 parses to Infinity and used to
     // validate as a legal number).
     return typeof value === 'number' && Number.isFinite(value);
@@ -42,9 +42,9 @@ export function isPositiveInteger(value) {
  * orders instead of failing fast.
  *
  * Rejects leading-zero forms ("01"), decimals ("1.5"), whitespace, and
- * non-numeric garbage via a strict regex — only the canonical
- * representation is accepted, so there is no ambiguity between what the user
- * typed and what the value becomes on disk.
+ * non-numeric garbage via a strict regex. Only the canonical representation
+ * is accepted, so there is no ambiguity between what the user typed and what
+ * the value becomes on disk.
  *
  * @param flagName - Flag name to include in the error (e.g. `--order`)
  * @param rawValue - Raw string value from Commander
@@ -83,8 +83,8 @@ export function isArray(value) {
  * Narrows a JSON value to a JSON object node (excludes arrays and `null`).
  *
  * Unlike {@link isObject} this accepts only values already known to be JSON
- * data, so the narrowed `JsonObject` keeps its concrete value contract —
- * use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
+ * data, so the narrowed `JsonObject` keeps its concrete value contract.
+ * Use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
  * @param value - JSON value to check
  * @returns True if value is a JSON object node
  */
@@ -110,16 +110,16 @@ export function isValidFirefoxCandidate(candidate) {
 /**
  * Naming contract for this module's checks.
  *
- * `validate*` is easy to spread across incompatible return contracts — some
+ * `validate*` is easy to spread across incompatible return contracts: some
  * throwing and returning void, some returning an issue list, some a parsed
- * value, some a boolean, some an error MESSAGE — and a caller cannot tell
- * which from the name. Passing a THROWING `validate*` to a clack `validate`
+ * value, some a boolean, some an error message. A caller cannot tell which
+ * from the name. Passing a throwing `validate*` to a clack `validate`
  * callback, which expects a returned message, kills the prompt instead of
  * re-prompting.
  *
  * The two dominant contracts keep the prefix:
- *   - `validate*` — throws on failure, or returns an issue list.
- *   - `is*` / `has*` — a type predicate or boolean.
+ *   - `validate*`: throws on failure, or returns an issue list.
+ *   - `is*` / `has*`: a type predicate or boolean.
  * The message-returning minority is `describe*Problem`, which reads as what
  * it is: a description of what is wrong, or `undefined`.
  *
@@ -129,9 +129,9 @@ export function isValidFirefoxCandidate(candidate) {
  * Valid Firefox product identifiers.
  *
  * `satisfies readonly FirefoxProduct[]` links the runtime list to the union
- * in ONE direction: it rejects an entry here that the union does not
- * declare. It cannot see a union member missing from this list — widening a
- * `readonly T[]` check never fails for being short. The reverse direction is
+ * in one direction: it rejects an entry here that the union does not
+ * declare. It cannot see a union member missing from this list, because
+ * widening a `readonly T[]` check never fails for being short. The reverse direction is
  * covered by the `ExhaustiveFirefoxProductList` operand below, which stops
  * compiling when the union grows past this list.
  */
@@ -146,22 +146,21 @@ export const FIREFOX_PRODUCTS = FIREFOX_PRODUCT_VALUES;
  * Validates a Firefox product string.
  *
  * A type predicate, matching its sibling {@link isValidProjectLicense}.
- * Returning plain `boolean` would force
- * `as FirefoxProduct` casts at the call sites even though the `.includes`
- * check IS the runtime proof.
+ * Returning plain `boolean` would force `as FirefoxProduct` casts at the
+ * call sites even though the `.includes` check is the runtime proof.
  */
 export const isValidFirefoxProduct = makeEnumGuard(FIREFOX_PRODUCTS);
 /**
  * Builds a type predicate from a `readonly` tuple of allowed values.
  *
- * Deriving the type from the list — rather than declaring a union and
- * hand-maintaining a matching array — removes a whole class of drift: a
+ * Deriving the type from the list, rather than declaring a union and
+ * hand-maintaining a matching array, removes a whole class of drift: a
  * union can otherwise accept a stale allowlist with no compile error, and a
  * copy of the member list on the `fireforge.json` read path can silently
  * reject a newly added value.
  *
  * Returning a predicate rather than a boolean is what removes the `as`
- * casts: `.includes` IS the runtime proof, so the caller should not have to
+ * casts: `.includes` is the runtime proof, so the caller should not have to
  * re-assert it. `ParsedRecord.stringEnum` (src/utils/parse.ts) consumes
  * exactly this shape.
  *
@@ -311,7 +310,7 @@ export function normalizeTokenName(name) {
  * Normalizes a patch display name against its category:
  * strips a trailing `.patch` and any redundant `NNN-<category>-` /
  * `<category>-` prefixes, case-insensitively and repeatedly, mirroring
- * the filename slug pipeline's require-the-category-token rule — a bare
+ * the filename slug pipeline's require-the-category-token rule. A bare
  * leading number is never stripped, so names like `2-step-verification`
  * survive intact. Falls back to the `.patch`-stripped stem when the
  * strip would empty the name.

package/docs/README.md

@@ -4,8 +4,8 @@
 
 [`../README.md`](../README.md) is the getting-started page. These files are
 the reference material behind it. `fireforge --help` (and
-`fireforge <command> --help`) stays the authority on flags; the docs cover
-what a flag list cannot state.
+`fireforge <command> --help`) is always the authority on flags. These docs
+cover the things a flag list cannot say.
 
 ## Using FireForge
 

package/docs/configuration.md

@@ -2,55 +2,57 @@
 
 # Configuration
 
-`fireforge.json` at the project root is the project's configuration;
+`fireforge.json` at the project root holds the project's configuration, and
 `furnace.json` holds component configuration. This file covers the settings
-whose behaviour needs more than a schema line, plus the environment variables
+whose behavior needs more than a schema line, plus the environment variables
 FireForge reads.
 
-## `firefox` — the source pin
+## `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.
+`firefox.version`, together with `firefox.product` and optionally
+`firefox.sha256` and `firefox.candidate`, is the source pin that
+`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.
+The pin lives in `fireforge.json` next to hand-maintained policy sections,
+which is worth knowing when you revert that file. Running
+`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
+the release. A mismatch fails the download and discards the archive. The
+check also fails closed when the published digest cannot be obtained at all:
+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
+  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.
+  published digest is unavailable, with a loud warning. This disables the
+  integrity check for that case, so 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 either
+  way. The setting is ignored when `sha256` is set.
 
-`fireforge doctor` reports the pin beside what the checkout actually is — the
+`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.
+recorded) and warns when they disagree. It is a report, not a lock, since 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
-`externalToolchains`. `fireforge doctor` reports missing **required** tools as
-errors and missing **optional** tools as warnings.
+`externalToolchains`. `fireforge doctor` reports missing required tools as
+errors and missing optional tools as warnings.
 
 Seasonal branding on macOS, for example, can declare Apple's Icon Composer
 tool at
@@ -59,27 +61,28 @@ plus `actool` via `xcrun`, `sips`, and `iconutil`.
 
 ## `patchLint`
 
-Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals
-shim that tracks upstream WebIDL additions per release.
+Per-patch lint type-checks plain Firefox JS against a built-in
+Firefox-globals shim that tracks upstream WebIDL additions per release.
 
-- `patchLint.checkJsExtraShim` adds members to the structured shim globals via
-  TypeScript interface merging, e.g.
+- `patchLint.checkJsExtraShim` adds members to the structured shim globals
+  via TypeScript interface merging, for example
   `interface ChromeUtilsShim { newApi(): any }`.
 - `patchLint.checkJsTestFiles: true` extends the pass to patch-owned test
-  `.js` files (`browser_*` / `test_*` / `xpcshell_*` and `/test/` paths). Each
-  is checked as its own small script-scope program against a loose built-in
-  harness shim.
+  `.js` files (`browser_*`, `test_*`, `xpcshell_*`, and `/test/` paths). Each
+  one is checked as its own small script-scope program against a loose
+  built-in harness shim.
 - `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'`)
+  declarations (a real `TestUtils` interface, say) override the loose
+  baseline, so calls to harness members that do not exist fail at export
+  time.
+- `patchLint.prettier` (`'off'`, `'warning'` or `'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/.prettierignore` decide the outcome. 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`
+  project's, then `npx --no-install`. Left at `'off'`, formatting is out of
+  scope for the per-patch tier, and no other tier checks `.sys.mjs`
   formatting either.
 - `patchLint.fileSizeThresholds` tunes the `file-too-large` line counts per
   file class:
@@ -96,11 +99,11 @@ shim that tracks upstream WebIDL additions per release.
   ```
 
   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.
+  `500/750/900`, test `1200/1400/1600`). The merged triple has to satisfy
+  `notice <= warning <= error`, which is validated at config load. Under
+  the recommended gate posture `--max-warnings 0`, the `warning` band
+  is a hard failure rather than a soft limit, which is what these thresholds
+  exist to let you move.
 
 ## `patchPolicy`
 
@@ -115,12 +118,13 @@ gaps does not move a patch out of the band its category owns.
 ## `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:
+report as "missing packaged artifact" is classified away from the structure
+of the tree itself: 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
 {
@@ -128,112 +132,114 @@ mirror whose header says it is never loaded. Declare those:
     "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."
+        "reason": "Type-only mirror of the tile host, never loaded, and 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.
+- `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.
+  evidence. By the time someone reads it, an unexplained carve-out is
+  indistinguishable from a mistake.
+- Admitted paths are listed in the audit output, never silenced. The notice
+  reads `admitted as unpackaged by buildAudit.unpackaged "<path>"` followed
+  by the declared reason.
+- A declared path that does resolve to a packaged artifact is reported as a
+  stale carve-out rather than suppressed, because 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.
+  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, so "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.
+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`; `fireforge token list` and
+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
-  base token first, then add each variant.
+  one step. It cannot be combined with `--variant`: author the category with
+  the base token first, then add each variant.
 - `--category` is required for a base declaration and optional under
   `--variant`, where the declaration is routed into a `:root<selector>` block
   and never into a category section. It is still validated when supplied.
 - `--variant` takes the same selector grammar the block matcher understands:
-  one attribute fragment (`[data-private]`, `[data-skin=precision]`), a run of
-  them (`[data-skin=precision][data-theme=dark]`), and an optional pseudo-class
-  tail (`[data-skin=precision]:not([data-private])`). Names and values must be
-  identifier-safe, and `=value` is normalized to `="value"`. A variant naming a
-  qualifier matches only a block carrying that qualifier; one without a
-  qualifier still matches a qualified block, and the write says so.
+  one attribute fragment (`[data-private]`, `[data-skin=precision]`), a run
+  of them (`[data-skin=precision][data-theme=dark]`), and an optional
+  pseudo-class tail (`[data-skin=precision]:not([data-private])`). Names and
+  values must be identifier-safe, and `=value` is normalized to `="value"`. A
+  variant naming a qualifier matches only a block carrying that qualifier.
+  One without a qualifier still matches a qualified block, and the write says
+  so.
 - `--mode override` mirrors into both `:root[data-theme="dark"]` and
   `:root[data-theme="light"]`. A qualified block such as
   `:root[data-theme="light"]:not([data-private])` is matched and written
-  through, with a warning naming the selector — the qualifier is
-  semantically load-bearing, but silently skipping half the mirror is the
-  worse failure.
+  through, with a warning naming the selector. The qualifier carries meaning,
+  but silently skipping half the mirror is the worse failure.
 - A token already present in the target block is reported with its location
-  (`already exists in :root[…] (line N), unchanged`) rather than a bare
+  (`already exists in :root[…] (line N), unchanged`) rather than as 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.
+`token add --category` refuses a category that the tokens CSS does not
+declare, so `token list` exists to name the categories without you
+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`.
+  the first banner are reported under `(no category)` rather than dropped,
+  and a banner with no tokens is still listed, since `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, and if you include 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`
 launches the browser headless. A headed smoke window on a shared desktop
-absorbs live input, which contaminates the console capture — headed 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).
+absorbs live input, which contaminates the console capture, so headed
+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).
 
 ## Lock waits
 
-Every FireForge command that mutates the engine takes the engine-session lock,
-and some take a second subsystem lock as well. Contention fails fast after
-about a second by default.
+Every FireForge command that mutates the engine takes the engine-session
+lock, and some take a second subsystem lock as well. Contention fails fast
+after about a second by default.
 
-`--wait-lock [seconds]` (bare flag = 60, valid 1–3600) replaces that with a
-bounded wait, and the budget covers **every** lock the command takes — for
-`furnace apply`/`deploy`/`sync` that means the furnace lock as well as the
-engine-session lock. While waiting, a progress line roughly every 5 seconds
-identifies the holder by PID, command and start time.
+`--wait-lock [seconds]` (bare flag means 60, valid range 1 to 3600) replaces
+that with a bounded wait, and the budget covers every lock the command takes.
+For `furnace apply`, `deploy` and `sync` that means the furnace lock as well
+as the engine-session lock. While waiting, a progress line roughly every 5
+seconds identifies the holder by PID, command and start time.
 
 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.
+sequence can append the flag everywhere without a usage error killing the
+run.
 
 `FIREFORGE_WAIT_LOCK=<seconds>` applies the same budget to every command in a
 session, using the same bounds as the flag. It is the only way to give a
 budget to the furnace mutators that declare no flag (`create`, `remove`,
-`rename`, `refresh`, `scan`, `override`, `chrome-doc`, …). An explicit
-`--wait-lock` always wins.
+`rename`, `refresh`, `scan`, `override`, `chrome-doc`, and the rest). An
+explicit `--wait-lock` always wins.
 
 `fireforge status --lock` reports the current holder and queue depth.
 
@@ -241,11 +247,11 @@ budget to the furnace mutators that declare no flag (`create`, `remove`,
 
 | Variable                             | Effect                                                                                                                                  |
 | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1–3600). See above.                                                                           |
+| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1 to 3600). See above.                                                                        |
 | `FIREFORGE_MAX_UNTRACKED_FILES`      | Per-directory cap when expanding collapsed untracked directories in `status` (default 5000). A non-positive value warns and is ignored. |
 | `FIREFORGE_GIT_ADD_TIMEOUT_MS`       | Timeout for the monolithic `git add -A` baseline pass (default 10 min). For slow or loaded filesystems.                                 |
 | `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` | Timeout for the chunked `git add -- <dir>` fallback (default 30 min). Paired with the above.                                            |
 
-`CLAUDECODE` is read by mozbuild, not by FireForge, and `fireforge test
---full-output` unsets it for test dispatches only — see
+`CLAUDECODE` is read by mozbuild, not by FireForge. `fireforge test
+--full-output` unsets it for test dispatches only. See
 [`testing.md`](testing.md#output-verbosity).

package/docs/exit-codes.md

@@ -2,76 +2,81 @@
 
 # Exit codes (internal)
 
-The exit code is the machine-readable half of the CLI's contract: a script
-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.
+The exit code is the machine-readable half of the CLI's contract. A script
+branches on it, and CI uses it to decide whether to retry or escalate. The
+values live in `src/errors/codes.ts`. This file says what they mean and
+which error class produces each one.
 
-| Code | Name                   | Meaning                                                                                                                  | Produced by                                                                                  |
-| ---: | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
-|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined — declining is a successful run that chose not to proceed. | —                                                                                            |
-|    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`                                                                          |
+| Code | Name                   | Meaning                                                                                                                 | Produced by                                                                                       |
+| ---: | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined: declining is a successful run that chose not to proceed. | (none)                                                                                            |
+|    1 | `GENERAL_ERROR`        | Unspecified failure the operator has to act on.                                                                         | `GeneralError` (and `PreflightRefusalError`), `ParserFallbackError`, `ExecTimeoutError`           |
+|    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                    | `ConfigError` and subclasses                                                                      |
+|    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                           | `DownloadError` and subclasses                                                                    |
+|    4 | `GIT_ERROR`            | A git operation failed.                                                                                                 | `GitError` and subclasses, except `GitNotFoundError`                                              |
+|    5 | `BUILD_ERROR`          | `mach build` failed, or a test suite went red.                                                                          | `BuildError` and subclasses, `TestFailureError`                                                   |
+|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                       | `PatchError`, `PatchManifestCorruptError`, `RebaseError` and subclasses                           |
+|    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                      | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError`                                    |
+|    8 | `INVALID_ARGUMENT`     | The flags were wrong. A usage problem, not an environment one.                                                          | `InvalidArgumentError`, plus commander usage errors (unknown command or option, missing argument) |
+|    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                   | `FurnaceError`                                                                                    |
+|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                             | `ResolutionError`                                                                                 |
+|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. This is a bug in FireForge, not something the operator can fix.                     | `InternalInvariantError`                                                                          |
+|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw console errors that were not allowed in the smoke window.                                        | `SmokeRunError`                                                                                   |
+|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw the browser exit uncleanly before the window elapsed.                                            | `SmokeRunError`                                                                                   |
+|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away because `engine/` moved while the harness ran. This is not red. Re-run it.         | `InconclusiveVerdictError`                                                                        |
+|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it with a larger `--wait-lock`.                                 | `LockContentionError`                                                                             |
+|  130 | `USER_CANCELLED`       | The operator interrupted a prompt (Esc or Ctrl+C). 128 + SIGINT.                                                        | `CancellationError`                                                                               |
 
-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
+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
+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`,
+stdout. `--help` and `--version` take 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.
+treats that as informational rather than as a wrong flag. That matches the
+exit 0 that `patch`, `token` and `furnace` give through their own help
+action.
 
 ## The three distinctions that matter for CI
 
-**Retry vs escalate.** `GENERAL_ERROR` usually means the operator must change
-something and a retry may help. `INTERNAL_ERROR` means nothing they could
-change would have helped — escalate it, do not retry.
+**Retry or escalate.** `GENERAL_ERROR` usually means the operator has to
+change something, and a retry may then help. `INTERNAL_ERROR` means nothing
+they could 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 — 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
-be perfectly green, and reporting it as red is wrong. A summary line reading
-`FAIL — exit 1` beside `FAIL — exit 5` invited treating opposites as the same
-kind of fact; the codes now separate them mechanically. The
-`FIREFORGE-VERDICT:` line's `reason=` key carries the same distinction for
-humans.
+**Red, never ran, or thrown away.** These are three different facts, and
+before 0.44.0 two of them shared exit 1.
 
-Note that `LockContentionError` backs every lock in FireForge — engine
-session, patch directory, build, furnace — so all four now exit 15. That is
-deliberate: the fact is the same whichever lock was contended.
+- `BUILD_ERROR` (5) is a suite that failed. Since 0.45.0 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
+  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 be perfectly green, so
+  reporting it as red is wrong.
 
-**Interrupted vs declined.** Before 0.44.0 both a Ctrl+C and a deliberate
-"no" at a confirmation returned the same value and exited 0, so a script
-could not tell them apart. They are now distinct: an interrupt raises
-`CancellationError` and exits **130**; a declined confirmation returns
-normally and exits **0**, because the run did what it was asked and the
-answer was no.
+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
+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
+`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.
 
 ## Adding a code
 
 New codes go in `src/errors/codes.ts` with a comment saying what a consumer
-should DO differently on seeing it — if the answer is "nothing different from
+should do differently on seeing it. If the answer is "nothing different from
 an existing code", it does not need one. Add a row here in the same change.