@hominis/fireforge 0.44.2 → 0.44.3

package/CHANGELOG.md

@@ -149,6 +149,9 @@
 - **`fireforge test --doctor` printed the same preflight line three times** on a terminal: a 2026-04-24 fix added an emission for non-TTY capture without removing the two it superseded. The raw writes are gated on non-TTY, which is where the capture requirement applies; the clack framing stays for terminals.
 - **All seven** `--wait-lock` commands that take the patch-directory lock now honour it: `patch tier`, `patch lint-ignore`, `patch staged-dependency`, `export-all`, `resolve`, `doctor` and `rebase`. Each routes through a different lock entry point, so the budget is threaded through `updatePatchMetadata`, `mutatePatchMetadata`, `commitExportedPatch`, `updatePatchAndMetadata`, `rebuildPatchesManifest` and the rebase patch loop.
 - `status --json` outside a project wrote a clack-styled block to **stdout** and exited 2, because the config error is raised before the command body engages machine mode. The boundary now engages it from the flag, so stdout carries exactly one JSON envelope and the human guidance goes to stderr — rule 3 of `docs/machine-output.md`, which was aspirational until now. A payload that already owns stdout (`status --json --fail-on`) suppresses the envelope, so the "exactly one document" half of the contract holds too.
+- **`--variant` refused selectors the matcher had just learned to find.** 0.44.2 widened `rootAttributeSelector` to consume consecutive `[…]` groups and to stop at a pseudo-class tail, so `:root[data-skin="humanist"][data-theme="dark"]` and `:root[data-theme="light"]:not([data-private])` became blocks FireForge can locate and write through. The CLI validator did not move with it: its own regex still accepted exactly one `[attr]` fragment, so `token add --variant '[data-skin=humanist]:not([data-private])'` was refused as "must be a single attribute selector" — a block the tool can FIND was one it would not let you NAME, and the private-exclusion selectors the widening exists for are precisely that shape. Downstream the values were maintained by hand in the allowlisted block instead.
+  The validator now runs the MATCHER'S parse and requires it to consume the whole fragment, rather than carrying a second grammar that can drift from the first again. Character safety stays a separate check, because that parse finds bracket boundaries and validates no characters at all — it is applied one bracket group at a time rather than as a repeated pattern, which is the shape that backtracks (`js/polynomial-redos`), and a linearity test pins that alongside the matcher's own. Normalization to `="value"` now covers every fragment in a run and the `:not(…)` argument, not just a trailing one.
+  `findVariantBlock` had to move with it: it compared a request against a block's ATTRIBUTE run only, so a variant carrying its own qualifier would have matched nothing and spliced a fresh duplicate block on every add. Request and candidate go through the same parse and are compared tail-to-tail. An UNqualified request still matches a qualified block — that is the 0.44.2 behaviour `variantBlockQualifier` exists to report out loud, since silently skipping the block is the worse failure — but a request that names a qualifier means it.
 - `tree list --json` gained the failure envelope `status --json` already emitted, so a scripted consumer no longer gets a parseable refusal from one and a bare non-zero exit from the other. The contract is written down in `docs/machine-output.md`.
 
 ### More correctness
@@ -180,6 +183,8 @@ On the test side: path expectations and mock keys are rendered through a new `na
 - **`test.test.ts` was 2,943 lines under one `describe`.** What made it unsplittable was its own 190-line `vi.mock` header: any split either duplicated the header into each new file or did not happen. The header moved to `test-command-mocks.ts` as one factory per mocked module, called from inside each file's own `vi.mock` callback — hoisting is unaffected and every suite still gets fresh `vi.fn()`s rather than shared call history. The file is now six, largest 952 lines, split on the seams the tests already formed: discovery and failure rewriting, staleness and packaging coverage, xpcshell/mochitest hints, Marionette forwarding, harness resilience, verdict contract.
   The split exposed a real test-isolation bug: `keeps the Marionette preflight for xpcshell-only --doctor runs` had never set a preflight result, and passed only because an `it` roughly 1,000 lines earlier had left one on the shared mock with `mockResolvedValue`. It sets its own now. Coverage of `src/commands/test.ts` is byte-identical before and after the split (95.12 / 94.28 / 100 / 86.23), which is the check that the mock rewiring did not quietly stop exercising anything.
 - Five rollback tests moved from asserting a module-level spy to asserting the persisted pending-repair marker. The spy stopped working when the sequence moved into `completeJournalRollback` (its call to the recorder is intra-module), and the outcome is the better assertion anyway.
+- **Fourteen verdict assertions passed only because writing to a filesystem root fails.** The command suites pass `/project` as the project root and assert the `FIREFORGE-VERDICT:` line by exact string — which holds only while no run log is open, since the line carries an open log's path as a ` log=<path>` key. On POSIX `mkdir('/project/.fireforge/logs')` fails at the root, the best-effort open degrades to "no log", and the assertions passed for a reason none of them stated. On Windows the same path resolves against the CURRENT DRIVE, the mkdir succeeds, and all fourteen failed — while the run also created real `C:\project\.fireforge\logs` directories on the runner. `createRunLogMock()` joins the two factories in `module-mocks.ts` and the five suites state the precondition instead of inheriting it from a permission error. Because mocking the module away removes the suffix's only coverage, `test-verdict.test.ts` gains the opposite assertion: with a log open, the path rides the line, once, as the run's last stdout write.
+- **A lock-wait test decided its result on a `readdir`.** `a wait whose queue position keeps improving > survives a drain longer than its budget` runs on real timers and a real filesystem, and gave each probe about 20 ms of slack inside a 100 ms budget; it also retired its simulated queue with un-awaited `rm` calls, so a retirement could land after the probe meant to observe it and a release could leave `mkdir` seeing `EEXIST` past the intended free. On a Windows runner the second probe missed the deadline, no extension was ever granted, and the wait expired still three from the head — the exact refusal the test exists to prove does NOT happen. The retirement and release are synchronous now (the callback returns `void` and cannot await), and the constants are scaled to ~100 ms of slack per probe while keeping the two invariants that fix them: the budget must span two probes, and the drain must outlast the budget or the sibling test would acquire instead of expiring. No production change — `withFileLock` checking its deadline before probing is correct, since a wait must not extend itself on a probe taken after it expired.
 - `git-readonly-index.test.ts` carried a latent racy-clean flake: it edited `const b = 2;` to `const b = 3;` — the same byte length, within the same second as the index entry — without invalidating the stat cache, so git could report the file unmodified. Its sibling test already guarded for this.
 
 ### Documentation
@@ -187,6 +192,7 @@ On the test side: path expectations and mock keys are rendered through a new `na
 - **README.md had become the reference manual.** Its "Regular Workflow" section had grown into fourteen paragraphs of flag semantics — scan manifests, shard behaviour, packaging-coverage anchors, tree CoW, shim configuration — read by nobody starting out and found by nobody looking for a specific rule, because prose in a getting-started page has no index. The reference material moves to `docs/`, split by the thing a reader is actually doing: `patch-workflow.md`, `testing.md`, `furnace.md`, `verification-trees.md`, `configuration.md`, plus `docs/README.md` as the index. README keeps installation, the loop's shape, rebasing, Furnace's premise, the roadmap and the licence — the parts that are project statement rather than manual — and links out for the rest.
 - **`docs/run-logs.md`** states the `.fireforge/logs/` contract that previously existed only as a table cell in `machine-output.md`: raw bytes rather than the echo filter's form, opened before any preflight, retained 20 deep per command kind, best-effort throughout, and the tee sitting at the two mach capture funnels rather than at the commands.
 - Two documents had gone stale against the code. `machine-output.md`'s surface table omitted `status --raw`, which engages the same stdout discipline through the same argv check in `cli.ts` — a machine surface to which rules 3 and 4 apply and rules 1 and 2 do not — and omitted `build`'s direct log announcement, which exists precisely because `build` prints no verdict line to carry a `log=` key. `lifecycle-invariants.md` still described `--wait-lock` as the engine-session lock's budget alone, which stopped being true when the budget was threaded into the furnace lock as well; both lock rows now state the resolution order (`lockTimeoutMs` → `FIREFORGE_WAIT_LOCK` → the 30 s default) and which mutators each covers.
+- **The package did not ship the `docs/` tree its own README links to.** The `files` allowlist was `dist/`, `templates/` and the three root markdown files, so `node_modules/@hominis/fireforge/docs` did not exist and all eleven relative `docs/…` links dead-ended for a consumer — against a doctrine that names the INSTALLED package as the authority, precisely so an agent never has to leave its repo to answer a tool question. The links resolved on GitHub and on the registry page, which rewrites them, which is why nothing caught it. `docs/` is now published (~100 KB of markdown against a package that already ships `dist/`), and `wrapper-smoke.test.ts` asserts the tree is both packed and present after install, the way it already did for `templates/` — so a future `files` edit that drops it fails the gate rather than the reader.
 - `FIREFORGE_WAIT_LOCK` and the three other environment variables FireForge reads were documented only in help text and JSDoc. They are tabulated in `configuration.md` with their defaults and their behaviour on a malformed value.
 
 ## 0.43.0

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.2",
-  "commit": "d653751d6c8a1be154647943dc346e81cc62b390",
-  "shortCommit": "d653751d6c8a",
+  "version": "0.44.3",
+  "commit": "760172104f6bfe523f63adfe08b8c6e63fd5d1f0",
+  "shortCommit": "760172104f6b",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-08-28T13:39:36.337Z"
+  "buildTime": "2026-08-28T15:34:58.794Z"
 }

package/dist/src/commands/token.js

@@ -180,7 +180,9 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .option('--description <desc>', 'Comment description for the CSS file')
         .option('--dark-value <val>', 'Dark mode value (required if mode is "override")')
         .option('--variant <selector>', 'Attribute selector fragment routing the declaration into a `:root<selector>` block ' +
-        "(e.g. '[data-skin=precision]' or '[data-private]'); creates or updates the block. " +
+        "(e.g. '[data-skin=precision]', '[data-private]', a run such as " +
+        "'[data-skin=precision][data-theme=dark]', or one with a pseudo-class tail such as " +
+        "'[data-skin=precision]:not([data-private])'); creates or updates the block. " +
         'CSS-only — cannot be combined with --mode override or --create-category. To author ' +
         'a new category and its variants, add the BASE token first (with --create-category), ' +
         'then add each variant with --variant.')

package/dist/src/core/token-variant.d.ts

@@ -23,10 +23,20 @@ export type VariantValidation = {
     reason: string;
 };
 /**
- * Validates a `--variant` attribute selector fragment and normalizes any
- * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Validates a `--variant` selector fragment and normalizes any `=value`
+ * form to the double-quoted `="value"` shape (Mozilla convention).
  * Boolean-attribute fragments are returned unchanged.
  *
+ * Structure is decided by {@link rootAttributeSelector} — the matcher's own
+ * parse — rather than by a second regex. That is the point: 0.44.2 widened
+ * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
+ * tail, and the validator did not move with it, so
+ * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
+ * could FIND but would not let you NAME. Running both halves off one parse
+ * is what stops them drifting apart again. Character-level safety stays a
+ * separate, per-group check, because the matcher finds bracket boundaries
+ * and validates no characters at all.
+ *
  * @param raw - Raw `--variant` value from the CLI / programmatic caller.
  */
 export declare function validateVariantSelector(raw: unknown): VariantValidation;

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

@@ -12,36 +12,113 @@
  */
 import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mode.js';
 /**
- * Accepts a single attribute selector fragment: `[data-private]` (boolean
- * attribute) or `[data-skin=precision]` / `[data-skin="precision"]`
- * (attribute with value). The value half is restricted to identifier-safe
+ * ONE attribute selector fragment: `[data-private]` (boolean attribute) or
+ * `[data-skin=precision]` / `[data-skin="precision"]` (attribute with
+ * value). The name and value halves are restricted to identifier-safe
  * characters so the fragment can be spliced into CSS verbatim without
  * escaping concerns.
+ *
+ * A multi-fragment variant is checked one group at a time (see
+ * {@link splitAttributeGroups}) rather than by wrapping this in a `+`: the
+ * repeated form is the shape CodeQL flags as `js/polynomial-redos`, and the
+ * split the matcher already performs is available for free.
+ */
+const ATTRIBUTE_FRAGMENT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
+/**
+ * A pseudo-class tail: `:not(…)`, `:hover`, and friends. The parenthesised
+ * argument is captured rather than validated here — it is a fragment run of
+ * its own and goes through the same per-group check.
  */
-const VARIANT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
+const QUALIFIER_PATTERN = /^:[a-zA-Z][a-zA-Z0-9-]*(?:\(([^()]*)\))?$/;
 /**
- * Validates a `--variant` attribute selector fragment and normalizes any
- * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Splits a run of consecutive attribute fragments into its groups, or
+ * returns `null` when the run is not exactly that — a group that does not
+ * open with `[`, an unclosed group, an empty run, or a group whose name or
+ * value is not identifier-safe.
+ *
+ * @param run - The `[…][…]` text with no `:root` prefix
+ * @returns The individual fragments, or null when the run is not valid
+ */
+function splitAttributeGroups(run) {
+    const groups = [];
+    let cursor = 0;
+    while (cursor < run.length) {
+        if (run[cursor] !== '[')
+            return null;
+        const close = run.indexOf(']', cursor);
+        if (close === -1)
+            return null;
+        const group = run.slice(cursor, close + 1);
+        if (!ATTRIBUTE_FRAGMENT_PATTERN.test(group))
+            return null;
+        groups.push(group);
+        cursor = close + 1;
+    }
+    return groups.length > 0 ? groups : null;
+}
+/** Rewrites `=value` / `='value'` to the double-quoted Mozilla convention. */
+function normalizeAttributeFragment(group) {
+    return group
+        .replace(/='([a-zA-Z0-9_-]+)'\]$/, '="$1"]')
+        .replace(/=([a-zA-Z0-9_-]+)\]$/, '="$1"]');
+}
+/**
+ * Validates a `--variant` selector fragment and normalizes any `=value`
+ * form to the double-quoted `="value"` shape (Mozilla convention).
  * Boolean-attribute fragments are returned unchanged.
  *
+ * Structure is decided by {@link rootAttributeSelector} — the matcher's own
+ * parse — rather than by a second regex. That is the point: 0.44.2 widened
+ * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
+ * tail, and the validator did not move with it, so
+ * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
+ * could FIND but would not let you NAME. Running both halves off one parse
+ * is what stops them drifting apart again. Character-level safety stays a
+ * separate, per-group check, because the matcher finds bracket boundaries
+ * and validates no characters at all.
+ *
  * @param raw - Raw `--variant` value from the CLI / programmatic caller.
  */
 export function validateVariantSelector(raw) {
     if (typeof raw !== 'string') {
         return { ok: false, reason: 'must be a string when set' };
     }
+    const reject = {
+        ok: false,
+        reason: 'must be one or more attribute selectors like [data-private], [data-skin=precision] ' +
+            'or [data-skin=precision][data-theme=dark], optionally followed by a pseudo-class ' +
+            'such as :not([data-private]) (identifier-safe attribute names and values only)',
+    };
     const value = raw.trim();
-    if (!VARIANT_PATTERN.test(value)) {
-        return {
-            ok: false,
-            reason: 'must be a single attribute selector like [data-private] or [data-skin=precision] ' +
-                '(identifier-safe attribute name and value only)',
-        };
+    if (value === '')
+        return reject;
+    const parts = rootAttributeSelector(`:root${value} {`);
+    // The parse must have consumed the WHOLE fragment: anything it declined to
+    // read (a stray space, a trailing combinator) is text the matcher would
+    // not see either, so accepting it would author a block nothing can find.
+    if (parts === null || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
+        return reject;
+    const groups = splitAttributeGroups(parts.attributes.slice(':root'.length));
+    if (groups === null)
+        return reject;
+    let qualifier = '';
+    if (parts.qualifier !== '') {
+        const match = QUALIFIER_PATTERN.exec(parts.qualifier);
+        if (match === null)
+            return reject;
+        const inner = match[1];
+        if (inner === undefined) {
+            qualifier = parts.qualifier;
+        }
+        else {
+            const innerGroups = splitAttributeGroups(inner);
+            if (innerGroups === null)
+                return reject;
+            const name = parts.qualifier.slice(0, parts.qualifier.indexOf('('));
+            qualifier = `${name}(${innerGroups.map(normalizeAttributeFragment).join('')})`;
+        }
     }
-    const normalized = value
-        .replace(/='([a-zA-Z0-9_-]+)'\]$/, '="$1"]')
-        .replace(/=([a-zA-Z0-9_-]+)\]$/, '="$1"]');
-    return { ok: true, value: normalized };
+    return { ok: true, value: `${groups.map(normalizeAttributeFragment).join('')}${qualifier}` };
 }
 /**
  * Reduces a `:root<attr>` selector to a quote- and whitespace-insensitive
@@ -105,12 +182,24 @@ function rootAttributeSelector(line) {
  */
 function findVariantBlock(lines, variant) {
     const stripped = stripBlockCommentsInLines(lines);
-    const want = canonicalSelector(`:root${variant}`);
+    // The request goes through the same parse as the candidate lines, so a
+    // variant carrying its own `:not(…)` tail is compared tail-to-tail rather
+    // than being folded into the attribute run — where it would match nothing
+    // and every add would splice a fresh duplicate block.
+    const requested = rootAttributeSelector(`:root${variant} {`);
+    const want = canonicalSelector(requested?.attributes ?? `:root${variant}`);
+    const wantQualifier = canonicalSelector(requested?.qualifier ?? '');
     for (let i = 0; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
         const selector = rootAttributeSelector(line);
         if (selector === null || canonicalSelector(selector.attributes) !== want)
             continue;
+        // An UNqualified request still matches a qualified block: that is the
+        // 0.44.2 behaviour `variantBlockQualifier` exists to report, since
+        // silently skipping the block is the worse failure. A request that names
+        // a qualifier, though, means it — so it must match.
+        if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)
+            continue;
         let openLine = /\{/.test(line) ? i : -1;
         if (openLine === -1) {
             for (let j = i + 1; j < stripped.length; j++) {

package/docs/README.md

@@ -0,0 +1,35 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# FireForge documentation
+
+[`../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.
+
+## Using FireForge
+
+| File                                           | Covers                                                                               |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [patch-workflow.md](patch-workflow.md)         | Export, re-export, deletions, queue maintenance, per-patch lint, CI gating, rebasing |
+| [testing.md](testing.md)                       | `fireforge test`: scope, modes, build freshness, the verdict line, verbosity         |
+| [furnace.md](furnace.md)                       | Components: overrides, shared CSS fragments, typed cross-module imports              |
+| [verification-trees.md](verification-trees.md) | CoW snapshots for concurrent read-mostly verification                                |
+| [configuration.md](configuration.md)           | `fireforge.json` settings, design tokens, lock waits, environment variables          |
+
+## Contracts for scripts and CI
+
+| File                                   | Covers                                                                      |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| [exit-codes.md](exit-codes.md)         | Every exit code, which error class produces it, and how CI should branch    |
+| [machine-output.md](machine-output.md) | The `--json` / `--raw` / verdict-line output contract and its versioning    |
+| [run-logs.md](run-logs.md)             | `.fireforge/logs/`: what `test` and `build` write, and what survives a pipe |
+
+## Internals
+
+| File                                               | Covers                                                                       |
+| -------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [lifecycle-invariants.md](lifecycle-invariants.md) | Locking, rollback, signal handling, and the decision table for new mutations |
+
+Release history and the reasoning behind individual changes live in
+[`../CHANGELOG.md`](../CHANGELOG.md).

package/docs/configuration.md

@@ -0,0 +1,116 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Configuration
+
+`fireforge.json` at the project root is the project's configuration;
+`furnace.json` holds component configuration. This file covers the settings
+whose behaviour needs more than a schema line, plus the environment variables
+FireForge reads.
+
+## 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.
+
+Seasonal branding on macOS, for example, can declare Apple's Icon Composer
+tool at
+`/Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool`,
+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.
+
+- `patchLint.checkJsExtraShim` adds members to the structured shim globals via
+  TypeScript interface merging, e.g.
+  `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.
+- `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.
+
+## `patchPolicy`
+
+`patchPolicy.ranges` makes `patch compact` range-aware, so closing ordinal
+gaps does not move a patch out of the band its category owns.
+
+## `test`
+
+`test.canaryPath` and `test.canaryTimeoutSeconds` supply the defaults for
+`fireforge test --canary`. See [`testing.md`](testing.md).
+
+## Design tokens
+
+Tokens are managed with `fireforge token add`.
+
+- `--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.
+- `--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.
+- `--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.
+- A token already present in the target block is reported with its location
+  (`already exists in :root[…] (line N), unchanged`) rather than a bare
+  no-op.
+
+## 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).
+
+## 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.
+
+`--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.
+
+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_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.
+
+`fireforge status --lock` reports the current holder and queue depth.
+
+## Environment variables
+
+| Variable                             | Effect                                                                                                                                  |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1–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
+[`testing.md`](testing.md#output-verbosity).

package/docs/exit-codes.md

@@ -0,0 +1,63 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# 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.
+
+| 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`                                            |
+
+## 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.
+
+**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
+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.
+
+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.
+
+**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.
+
+## 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
+an existing code", it does not need one. Add a row here in the same change.

package/docs/furnace.md

@@ -0,0 +1,57 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Furnace components
+
+Furnace is FireForge's answer to UI components. It tracks stock widgets,
+creates new fork-owned widgets, and overrides existing ones. The files still
+land inside the Firefox source directory and end up as part of the regular
+patches to export.
+
+```bash
+npx fireforge furnace scan
+npx fireforge furnace override moz-button -t css-only
+npx fireforge furnace create moz-my-widget
+npx fireforge furnace deploy
+npx fireforge furnace status
+npx fireforge furnace preview
+```
+
+`fireforge furnace --help` lists every subcommand.
+
+## Shared CSS fragments
+
+Cross-widget CSS can be single-sourced. Place the fragment in
+`components/shared/` and reference it from a widget stylesheet with a
+comment:
+
+```css
+/* @fireforge-include base-button.css */
+```
+
+`deploy` expands it into the deployed copy only, so editing the fragment
+surfaces as component drift until the next deploy.
+
+## Typed cross-module imports
+
+For multi-file components, set `furnace.json#typecheckJsconfig` to a
+consumer-owned jsconfig. `deploy` then maintains `compilerOptions.paths`
+entries mapping each deployed
+`chrome://global/content/elements/<file>.mjs` URL to its workspace source.
+
+Entries are recognized as Furnace-managed by containment in the components
+workspace, so a hand-written entry is preserved and a managed entry whose
+helper was deleted is pruned.
+
+## Safety
+
+Every furnace mutation runs through `runFurnaceMutation`: a per-root lock, a
+rollback journal restored on both a signal and a thrown error, and a
+`pendingRepair` marker that blocks further mutations when a rollback was
+incomplete — cleared with `fireforge doctor --repair-furnace`. The full
+contract, including which commands take which locks, is in
+[`lifecycle-invariants.md`](lifecycle-invariants.md).
+
+`apply`, `deploy` and `sync` accept `--wait-lock [seconds]`, whose budget
+covers **both** locks they take. The twelve mutators without the flag pick up
+a session budget from `FIREFORGE_WAIT_LOCK`; see
+[`configuration.md`](configuration.md#lock-waits).