@hominis/fireforge 0.44.0 → 0.44.2

package/CHANGELOG.md

@@ -6,11 +6,11 @@
 
 - **`release:check` ran twice per release**, because `npm publish` re-triggers it through `prepublishOnly`. The explicit step is gone; `prepublishOnly` is the single gate. The redundant third `npm pack` (`pack:dry-run`, already run by `pack:verify`) was dropped from the gate.
 - Branch-protection contexts are stable: the smoke job is `smoke (${{ matrix.os }})` rather than embedding the Node version — the same trap already fixed for `quality (ubuntu)` — and `setup-rulesets.sh` reconciles (GET by name, then PUT or POST) instead of POSTing unconditionally, which is why the live ruleset had drifted to requiring nothing.
+- **CI ran the lint toolchain on a Node version that toolchain excludes.** `eslint-plugin-jsdoc` and its two dependencies (`@es-joy/jsdoccomment`, `jsdoc-type-pratt-parser`) declare `node: ^22.22.2 || >=24.15.0`, and every workflow pinned **22.22.1** — one patch below the floor. `npm ci` only WARNS on an engine mismatch (`npm warn EBADENGINE`), so the gate stayed green while `lint:ci` ran on a combination the plugin's author had ruled out; the next symptom of that is an unexplained eslint crash rather than a version complaint. The pin moves to **22.23.2** (newest on the 22 line). The eight hardcoded `22.22.1` literals across four workflows are gone: all six setup-node steps now read `node-version-file: '.nvmrc'`, so the version is derived exactly the way the npm pin already is, and the drift that let the lockfile's floor climb past the pin cannot recur. `ci.yml`'s smoke matrix loses its now-uniform `node-version` column; the check contexts are unaffected, since `name:` pins them explicitly for the reason recorded above. `engines.node` deliberately moves only to `>=22.22.2`, NOT to the pin: the `^22.22.2` requirement comes from devDependencies, so a consumer of the published package must not be pushed to 22.23.2 for a lint plugin they never install. `.nvmrc` sitting above `engines` is the intended shape, not a number someone should reconcile.
+- **A test repo committed without a committer name, so the gate passed on every developer machine and failed on the runner.** `apply-patch-idempotent.test.ts` was the only repo-creating test that configured `user.email` without `user.name` — the other twenty set both. Git falls back to the OS gecos field for a missing name, which is populated on a workstation and EMPTY for GitHub's `runner` user, so there `git commit -m baseline` died with `fatal: empty ident name` and left HEAD unborn. The helper used `exec`, which returns a non-zero `exitCode` rather than throwing, so the dead commit was discarded silently and the run continued against a repo with no commits; the failure surfaced six steps later inside `restoreFilesToHead` as `fatal: Not a valid object name HEAD`, wearing a `PatchApplyError` whose remedies are all about Firefox version drift. Six of the file's seven tests failed that way and pointed at the wrong subsystem. The helper now sets `user.name` and routes every git call through `runGit` (`src/test-utils/index.ts`), which is `execFile`-backed and REJECTS on non-zero — so a future setup command that fails is reported where it failed rather than as a corrupted repo later. An environment with no ambient git identity (`user.useConfigOnly`) reproduces the old failure exactly and passes on the new code.
 
 ### Multi-session contention
 
-A downstream fork runs this checkout with up to five concurrent agent sessions, where a held lock is the normal state rather than an exceptional one. Four findings from that workload:
-
 - **A `--wait-lock` budget expired one position from the head of the queue** — the worst possible outcome, because it pays the entire wait and gets nothing. `--wait-lock 300` died still-queued where `3600` was needed. The timeout is now a budget against a STALLED queue rather than against wall-clock: each time the observed queue position improves, the wait is granted a fresh budget, up to four times the requested one (ceiling one hour, matching the flag's own bound). A queue that stops moving still starves on exactly the budget you asked for, which is what the timeout is for. The refusal also names the position reached — "you were still 2 from the head of a queue of 3" — so raising the budget is an informed decision instead of a guess. Only `--wait-lock` runs extend; the no-flag ~1 s fail-fast path is untouched.
 - **A wait budget could not be expressed once for a session.** `FIREFORGE_WAIT_LOCK=<seconds>` now supplies the budget for every lock-taking command that was not given an explicit `--wait-lock` (which always wins). An unattended loop threading the flag through every invocation was the shape most likely to be forgotten, and the omission only surfaced as a tail of refusals after the loop had already run. An unusable value is refused rather than silently falling back to fail-fast. Note that `test`, `export` and `re-export` never differed here: all three fail fast at ~1 s without the flag.
 - **A killed run wrote no terminal line**, so a log tail could not distinguish "killed" from "still running" from "never started" — recovery meant checking `ps` and the lock file by hand, at exactly the moment (a mass kill under a usage limit, mid-drain) when the tree's state most needs to be readable. SIGTERM/SIGINT now emit `FIREFORGE-VERDICT: FAIL reason=killed signal=…` before the shutdown drain, so the line survives a drain that times out. It is a no-op unless a test run was actually in flight: a Ctrl+C during `status` must not claim a test run happened.
@@ -20,6 +20,10 @@ A downstream fork runs this checkout with up to five concurrent agent sessions,
   `binaryStagingLock` never covered it — it is a module-level promise chain, so it serializes within one process while `--parallel-verify` lanes are separate processes. The staging now writes a per-call PRIVATE index (`mintDisposableGitIndex`) and throws it away, so the primary `.git/index` never moves, nothing is restored because nothing shared changed, and two concurrent callers get two indexes rather than contending. The 0.43.0 private-index work closed this for read-only commands; this path is the deliberate writer it did not cover, and it could not have been fixed by leaning on that scope — `export` and `re-export` install none, and `withPrivateGitIndex` is fail-open by design, which on a write path means silently mutating the primary checkout.
   The seed is load-bearing rather than tidy: a tracked, unmodified binary reaches the same branch (its `diff HEAD` is empty), and against an empty index it would report as a fresh add. The shared-index path survives as a fallback for when no private index can be minted — refusing there would fail an export over an optimisation. A real-git test polls `git status` throughout the call and asserts the transient entry is never observable; it fails on the old implementation, which is what makes it worth having.
 
+- **`--wait-lock` governed only ONE of the two locks a furnace mutation takes.** `furnace apply`/`deploy`/`sync` routed the resolved budget into the engine session lock and stopped there. `runFurnaceMutation` then acquired `.fireforge/furnace.lock` through `withFileLock`, passing `timeoutMs` only when `options.lockTimeoutMs` was set — and **no production caller ever set it**: the field's only other occurrences were its own declaration and one test, and its doc comment cited a watch-mode caller that does not exist. So the file lock always fell to `DEFAULT_LOCK_TIMEOUT_MS`, a fixed 30 s. A contended `deploy --wait-lock 1800` therefore died at 30 s while its operator believed a half-hour budget was in force, which is the worst shape a budget can have: it pays the entire advertised wait and still refuses. `FIREFORGE_WAIT_LOCK` did not help — it feeds the same resolver into the same single sink.
+  The resolved budget now reaches both. It is threaded explicitly into the three commands that declare the flag (`waitLockMutationOptions` does the seconds-to-milliseconds conversion once, rather than at three call sites where dropping the factor is a silent 1000× error), and `runFurnaceMutation` falls back to `sessionWaitLockMs()` — the environment budget — so the twelve furnace mutators with no flag to thread (`create`, `remove`, `rename`, `refresh`, `scan`, `override`, `chrome-doc`, …) are covered too. An explicit `lockTimeoutMs` still wins, and absent both the ~1 s fail-fast and the 30 s default are untouched.
+  The invisibility was the other half of the defect: the flag's help text said "the contended lock", singular, and the furnace refusal named neither the lock nor the flag — it advised removing a stale lock directory. The help now says the budget covers every lock the command takes, and the refusal names the FURNACE lock, says it is the second of two, and points at `--wait-lock`/`FIREFORGE_WAIT_LOCK`. A test asserts the budget reaches the command options, and a sibling asserts nothing is threaded without the flag.
+
 ### Exit codes
 
 - **Red, never-ran and thrown-away were three facts sharing two exit codes.** `reason=inconclusive` — a suite whose verdict was DISCARDED because `engine/` moved under it — exited **1** beside real test failures' **5**, and a summary line reading `FAIL — exit 1` next to `FAIL — exit 5` invites treating opposites as the same kind of fact: one suite failed, the other's healthy result was thrown away. It now exits **14** (`InconclusiveVerdictError`). `LockContentionError` moves from 1 to **15**: a lock timeout means the run never started, so a script should re-queue it rather than report a failure of the work it asked for. That re-codes patch-directory, build and furnace lock timeouts too — deliberately, since the fact is the same whichever lock was contended. See `docs/exit-codes.md`.
@@ -39,6 +43,15 @@ A downstream fork runs this checkout with up to five concurrent agent sessions,
 - **The packaging-coverage refusal never mentioned `--extend-coverage`.** The cumulative claim shipped in 0.43.0, but under concurrent sessions the operator meets it at the moment a peer's scoped build has replaced coverage they still hold — and the refusal pointed only at a full rebuild. It now offers the union, and states the anchor conditions (unchanged engine HEAD and `engine/mozconfig`) so the operator knows when it will refuse. Coverage still REPLACES by default, for the reason documented on `BuildBaseline.testPackagingCoverage`: a blind union whitewashes an earlier scope's edited fixtures while `obj-*/_tests/` still holds that scope's stale staging.
 - **The no-output-stall census asserted a mechanism it had no evidence for, and its third cause carried no discriminating step.** The `chrome://`-image entry shipped in 0.43.0 stating that a broken image URI on the startup page "stalls first paint"; that mechanism was never established here — it was written on top of a single downstream report which explicitly did not root-cause it, and it is doubtful on its own terms, since a failed image load in Gecko fires `error` without gating the document load event. The entry now states the correlation it actually rests on (one consumer, reproduced and un-reproduced on one variable) and says the mechanism is open, so nobody inherits a guess as a fact. Separately, its remedy — run a known-good control — is the correct opening move for **all three** causes, so attaching it to one entry made reaching that entry informationally empty; the control step is hoisted above the list, and cause 3 gains a probe that actually separates it from the other two (`fireforge run --smoke-exit … --capture-console`, which starts the same browser outside the test harness). No detector is claimed: no log line is known to key on, and `mach-error-hints.ts` sets the bar at an established diagnosis rather than a plausible one. The census moved to `src/core/test-stall-triage.ts` — it is operator advice, not classification, and the rules for editing it are not the rules for editing a classifier.
 
+- **A run's only copy of its own diagnosis died with the pipe.** `fireforge test … 2>&1 | tail -40` keeps the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT broke; it also launders the exit code. Nothing else held the output — `runMachCapture` keeps a 2 MB in-memory tail that dies with the process, and the shard retry loop discards earlier attempts outright — so one downstream failure is now permanently undiagnosable and cost two further full runs to pin as "unreproduced". The operator rule ("never pipe a run") had been written down three times and broken after each writing, which is the tell that it is not an operator problem: piping is the ergonomic default when output is long, and the tool is the only party that can make the log survive the mistake.
+  `test` and `build` now write their own complete output to `.fireforge/logs/<command>-<timestamp>.log` as they stream, retained 20 deep per command kind (per-kind, so a busy `test` loop cannot evict the `build` log an operator needs to read beside it). The tee sits at the two mach capture funnels rather than at the commands, so it covers every dispatch — the three test dispatchers, `package`, and the stdio-inheriting path `mach build` uses, which rides the collectors' existing `mirror` hook rather than growing a second one. The log gets the RAW bytes, never the echo filter's collapsed form: the artifact exists to be re-read by whoever is diagnosing the run, so shortening it would reintroduce the loss it prevents.
+  The path rides the `FIREFORGE-VERDICT:` line as an additive `log=<path>` key. That is deliberate and not a free choice — the verdict must stay the run's LAST stdout write, so a separate announcement after it would break the contract and one before it is the first thing a `tail` cuts. `build`, which prints no verdict line, announces the path directly. Everything here is best-effort: a log that cannot be opened, written or pruned degrades to no log, because a run must never fail over a diagnostic. Opened before any preflight, so a refusal is logged too — those are exactly the runs whose only output a `tail` throws away.
+- **Post-rebuild failure diagnosis promoted recognized teardown noise over the real assertion.** An export shard failed on its file-count assertion; the diagnosis named the known `AttributeError: 'SystemResourceMonitor' object has no attribute 'stop_time'` instead. The raw Error Summary had the assertion right, so the information was present and the SELECTION was wrong — the expensive kind, because the named cause is a real, documented, unrelated upstream defect and therefore reads as an answer.
+  0.44.0 already ships `mach-known-noise-filter.ts`, whose module doc says exactly the right thing about closing the presentation gap — but `findFirstUsefulFailureLine` never consulted it. It matched a bare `/AttributeError:\s+/` among its patterns and selected by first-matching-LINE, not first-matching-pattern, so that arm had precisely the same standing as `TEST-UNEXPECTED-FAIL` and whichever appeared earlier won. The selector now runs two passes: candidates excluding the recognized noise first, the full set only if that finds nothing. The narrowness is preserved exactly — the exclusion is gated on `hasKnownTeardownNoise` for the whole capture, so it still requires both the closed `stop_time`/`poll_interval` allowlist AND a `resourcemonitor.py` frame, and a novel attribute or a traceback from anywhere else stays a real failure. Three tests pin those escape hatches; the one that pins the fix fails on the old code.
+  Worth recording that the misdiagnosis was CONDITIONAL, not universal: the classifier reads stdout then stderr, and the traceback usually lands on stderr while the suite output lands on stdout, so a real `TEST-UNEXPECTED-*` normally won on ordering alone. It bites when the traceback shares or precedes the stream, or when the real failure matches none of the other patterns. The reporter could not have known that, and it does not change the fix — but a defect described as always-firing gets re-opened as "not reproducible" by the next reader.
+- **mozbuild's AI-agent output limiter quieted test runs, not just builds.** `is_running_under_coding_agent()` keys on `CLAUDECODE`, which FireForge inherited into every mach dispatch verbatim — it had no handling of the variable anywhere. The build half of that quieting is genuinely useful; the test half removes `TEST_START` and console INFO, exactly the lines a hang diagnosis needs, and the ones FireForge's own classifier reads (`Ran N checks`, `Unexpected results:`, `TEST-UNEXPECTED-*`), so suppression pushes a run toward `reason=no-tests`. Unsetting the variable for the whole process gives up the build half too.
+  `fireforge test --full-output` now unsets the marker for TEST dispatches only; the build path is untouched. 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. The exec layer gained an explicit `envUnset` for this: `env` can only add or overwrite, and a variable read for its PRESENCE is not unset by an empty value — and the removal is a real delete rather than a `Record<string, string | undefined>` widening, because relying on Node dropping `undefined` env entries would be a semantics gamble at the one layer that must not have any.
+
 ### Build output resolution
 
 - **A second `obj-*` directory made FireForge refuse every command, even when the mozconfig said which one to use.** The refusal is correct where the choice is genuinely ambiguous — building a dev test against a release objdir is exactly the silent corruption it prevents — but `MOZ_OBJDIR` was never read, so an operator whose active configuration had already answered the question was sent to rename a directory to satisfy a scan. An ambiguous glob now consults `engine/mozconfig` (`mk_add_options MOZ_OBJDIR=…` or a bare `export`, `@TOPSRCDIR@` and relative forms resolved to a path segment) and proceeds when the declaration resolves to exactly one candidate — into the existing `mozinfo.json` verification, which is the real safety net. Everything else still refuses, and a declaration that named something the scan cannot see is reported, because that is itself the diagnosis.
@@ -63,6 +76,35 @@ A downstream fork runs this checkout with up to five concurrent agent sessions,
 - The signal-time furnace lock sweeper removed lock directories without checking ownership, so it could delete a lock another process had acquired in the window between our operation dying and the sweep running. It now uses `releaseLockIfOwned`.
 - `killProcessTree`'s POSIX branch swallowed `ESRCH`/`EPERM` from the group kill without falling through to a direct `child.kill`, so a failed group kill left the child running.
 
+- **A DELETION of an upstream file could not be made durable through `re-export`, and the failure was silent.** With eighteen retired files, `rm` left `fireforge status --json` reporting `"status": "D"` with `"classification": "unmanaged"` — correct as a description, fatal as a state, because `check-engine-clean` refuses an unmanaged file precisely because it is not durable through a reset, and a reset would restore every deleted file. No re-export path captured it: `--scan` pruned the path from `filesAffected` and emitted no deletion hunk, `--scan-file` refused it outright, and **`--files` accepted the path and emitted no hunk** — the dangerous shape, because the run reported success while writing a patch that silently CLAIMED a file it did not restore. On a fresh clone that patch applies cleanly and resurrects exactly what the change meant to remove.
+  The cause was one conflation. All three paths filtered "absent from disk" out of the diff scope, on a comment asserting the diff "would fail" on a missing path — true only for a path that was NEVER TRACKED. For a tracked file deleted in the worktree, `git diff HEAD -- <path>` emits a proper `deleted file mode` section, and every downstream consumer already branches on `isDeletedFile`. The two cases are now split by `listTrackedInHead`: a tracked absent path stays in the diff scope and is captured, an untracked one is refused rather than warned about, since the patch cannot express it either way. A captured deletion KEEPS its `filesAffected` entry — the patch is what performs the deletion, so pruning it would leave the body deleting a file the manifest says the patch has nothing to do with — and it still requires the confirmation, because the patch will now remove those files wherever it is applied.
+  The report's priority-1 item — make the silent success LOUD — turned out to need two words, not a feature: the `--files` path already refused when a requested path produced no hunk, but its domain was the post-filter subset, so anything dropped upstream was invisible to the check by construction. It now runs against the full requested list. A real-git test asserts the emitted patch contains `deleted file mode`; it fails on the old implementation.
+  Recorded because the report says otherwise and the next reader should not chase it: **`export` was never affected.** It accepts a `D` status from `getStatusWithCodes` and routes a HEAD-tracked path to `git diff --binary HEAD`, which has always carried the deletion. Only the batched `re-export` paths dropped it.
+- **`token add --mode override` silently skipped a QUALIFIED `[data-theme="light"]` block.** The override path mirrors into both `:root[data-theme="dark"]` and `:root[data-theme="light"]`, guarded by `variantBlockExists` — and that guard compared canonically against a fragment sliced to the LAST `]` before the opening brace. For `:root[data-theme="light"]:not([data-private]) { }` the last `]` is the one inside `:not(…)`, so the computed fragment was `:root[data-theme="light"]:not([data-private]` and the comparison could never match. The unqualified dark block beside it matched fine. That asymmetry was the whole bug: the override wrote dark, skipped light, and said nothing — so a Light choice under a dark OS inherited the new dark token, and the operator met the gap as a theme bug rather than as tool output. `THEME_ATTRIBUTE_VARIANTS`' own doc comment names the failure this feature exists to prevent — "a guaranteed half-finished edit" — and the half-finished edit is what shipped.
+  The last-`]` slice was deliberate, not sloppy: it avoids a `js/polynomial-redos` regex, and taking the last `]` rather than the first keeps a multi-attribute selector comparing as a whole instead of colliding with a single-attribute variant that is its prefix. Both properties survive. The selector is now parsed structurally — consume consecutive `[…]` groups after `:root`, stop at the first character that is not `[` — which is still linear and still matches multi-attribute blocks whole, but excludes a pseudo-class tail instead of swallowing it. A regression test uses a two-attribute block to pin that.
+  The qualifier is reported rather than applied silently. `:not([data-private])` is semantically load-bearing — writing through it narrows where the declaration applies, and that may not be what the operator meant — but matching it is still the right call, because silently skipping it is the worse failure and the one that shipped. So the write happens and a warning names the selector it went through. The pinning test fails on the old matcher.
+- **`token add --variant` required a flag that described nothing, rejected its companion, and reported a no-op as success.** Three separate frictions, all in the variant path. `--category` was an unconditional `requiredOption` that had to name a REAL category even under `--variant`, where the declaration is routed into a `:root<selector>` block and never into a category section — the requirement existed so the argument would not be "silently discarded", a fair goal whose effect was a mandatory argument saying nothing about where the token lands. It is now optional there (still validated when supplied, so a typo is not accepted just because the flag is inert), and its absence on a BASE declaration is refused with the REASON stated rather than commander's bare "required option not specified".
+  `--create-category` is still rejected with `--variant` — the two really are incompatible — but the working create-then-variant order (author the category with the base token, then add each variant) was discoverable only by failing twice. It is now in both the error and `--variant`'s help text.
+  And a token already present in the target variant block was skipped with a bare `{ added: false }`, so a re-run intending to CHANGE a value exited 0 having changed nothing, while the base path had been reporting the category and line for the same situation all along. The variant path now returns the location too, and the skip reads `already exists in :root[…] (line N), unchanged` — the block being the location, since a variant declaration has no category to name.
+
+### Security
+
+- **Six scanners over `tokens.css` were super-linear in the length of a single line** (`js/polynomial-redos`). Worth stating plainly what the input is: `tokens.css` and `docs/design/SRC_TOKENS.md` are files FireForge reads out of a CONSUMER's engine tree, so "attacker-controlled" is the wrong frame — a minified, generated or merge-mangled line that happens to repeat `:root`, `:root[`, `var(` or `/*=` is enough to wedge `token add` with nobody doing anything hostile. Measured on the witnesses now pinned as tests: 4 000 `=` after a `/*` cost the category scanner **8.2 s**, and 20 000-40 000 repetitions cost the other five between **0.8 s and 3.6 s** each. Two distinct causes, and they want different remedies:
+  - _Ambiguous adjacent quantifiers_, where two atoms match the same character so the engine re-partitions the run once per length: `\s*=+\s*(.+?)\s*=+\s*` in the banner reader (`.` matches both `\s` and `=`), `\/\*\s*=.*=\s*\*\/` in the section-end scan, `(^|[\s,{])\s*:root\b` in the dark-mode scan (`[\s,{]` and `\s*` both match a tab), and `:root\[[^{]*\]` in the variant scan (`[^{]` also matches `]`). The dark-mode one is a one-token fix — `(?:^|[\s,{]):root\b` is exactly equivalent, since the last whitespace character of any run satisfies the class on its own. The other three became index arithmetic (`blockCommentBody`, `singleLineBannerName`, `rootAttributeSelector`), which is also where the duplicated "is this a banner comment?" spelling collapsed into one predicate.
+  - _An unanchored prefix that can start at many positions_, which is quadratic even when the pattern itself is unambiguous: `:root[^{}]*\{` restarts at every `:root` in the line, and `value.replace(/var\(([^)]+)\)/, …)` at every `var(`. The docs one is a one-character fix — the branch it sits on has already established `value.startsWith('var(')`, so anchoring is both linear and exact. The other became `rootOpensBraceOnLine`.
+- The variant scanner's replacement deliberately spans to the LAST `]` before the opening brace rather than the first. Taking the first would have been the shorter fix and a silent behaviour change: `:root[data-skin=precision][data-private]` would then satisfy a request for the `[data-skin=precision]` variant it merely starts with, and the declaration would land in the wrong block. A test pins that, and it passes on both implementations — which is the point of it.
+- The regression tests assert wall-clock, because the defect IS a running time; every one of these calls returns the same answer before and after. Each witness fails the old implementation by an order of magnitude or more, and the whole file now runs in ~26 ms.
+- **The prototype-chain guard on `config <key> <value> --force` was correct and invisible** (`js/prototype-pollution-utility`). `mutateConfig` rejected `__proto__`, `constructor` and `prototype` — but once, up front, in a helper, against a `Set`; the descent and the leaf assignment two dozen lines below therefore read as unguarded to anything that is not interprocedural, CodeQL included. The check now happens at the point each segment is USED as a property name, spelled as explicit comparisons, with only the message factored out. That is not just to satisfy the query: a guard that lives at a distance from its write is one refactor of its caller away from being skipped, and the existing tests keep passing untouched because nothing about the behaviour moved.
+- **Two `replace` calls read as incomplete escaping** (`js/incomplete-sanitization`), and both were in fact correct — which is exactly why they are rewritten rather than dismissed, since "correct, trust me" is not a property a scanner can re-derive next quarter. `patch-lint-checkjs` substituted a TypeScript `paths` wildcard with `target.replace('*', captured)`; a target carries at most one `*` and first-occurrence replacement IS the contract, now spelled as index arithmetic mirroring the prefix/suffix split already used on the pattern side, with a test pinning both the wildcard and wildcard-free target shapes. The pack smoke test hand-escaped a version string with `.replace(/\./g, '\\.')`; it now uses `escapeRegex` from `src/utils/regex.ts`, the helper ~40 other call sites already use.
+
+### Manifest repair
+
+- **The rebuild dropped `stagedDependencies` from every entry that had one.** `doctor --repair-patches-manifest` builds each row as an explicit object literal, field by field, from the existing entry — so it preserves exactly the fields someone remembered to list, and silently drops the rest. `stagedDependencies` was never listed, which on a queue that uses it means the `registrations` block that lets a branding `distribution/` directory land with a later patch is gone, and the next `lint` fires on a dependency the operator had declared. A patch body cannot express it, so nothing recomputes it either. The row is now built by spreading the existing entry and overriding only the two fields the rebuild OWNS — `filesAffected` and `order` — so a field a `.patch` cannot carry survives by construction, including whatever is added to `PatchMetadata` next. This is the same failure the `lintIgnore`/`tier` lines were added to fix, one field later; the enumeration was the defect, not the omission.
+- **An unparseable `patches.json` was rebuilt into a wholly invented one, and the report did not see this because it is not what happened to it.** An existing-but-invalid manifest loads as `null`, which the merge cannot tell apart from "no manifest at all" — so every entry was treated as new, and every entry's `description`, `createdAt`, `category` and source version was reinvented from filename, mtime and fallback. `manifest-invalid` is one of the consistency issues that triggers the repair, so `doctor --repair-patches-manifest` reached it directly. It now refuses, naming the parse error and what would be lost, and the escape hatch is explicit (`--allow-metadata-loss`) rather than the default.
+- **A repair that wrote was reported as a run where nothing happened.** The repair runs inside the check loop; the exit code is computed after every check. The repair itself returns a warning, so it never fails the run — but any later failing check makes doctor exit 1 with the manifest already rewritten, and a non-zero exit reads as "the command refused". Doctor now prints what it wrote, immediately before the summary, in every branch including the failing one. The write is not rolled back: the repairs are independent of the checks that follow them, and undoing a successful repair because something unrelated is also wrong would be the larger surprise.
+- **`--repair-patches-manifest` was named as the fix for a one-field drift, by both `import` and doctor's own hint.** `files-affected-mismatch` is a derived list disagreeing with the diff that defines it, and a tool that names a whole-manifest rewrite as the remedy for that will have it run. There is now a narrow repair — `doctor --repair-files-affected` — which recomputes only the drifted lists through `mutatePatchRowsInManifest`, so every untouched row keeps its exact JSON, and which needs no project config, so unlike the rebuild it works on a project whose `fireforge.json` is also broken. The refusals now offer whichever repair fits the issue codes actually present. Both repairs gained `--dry-run`, which `patch lint-ignore` has had all along; neither gained a confirmation prompt, because `confirmDestructive` refuses a non-TTY run and these are run from scripts — the repair flag is itself the explicit opt-in. Manifest rows the rebuild drops because their patch file is gone are now named too.
+- **Two of the report's claims do not hold against this code, and are recorded rather than "fixed".** `lintIgnore`, `tier`, `description`, `category`, `createdAt` and `sourceEsrVersion` were all already preserved on an existing entry — the rebuild has been a merge, not a from-scratch rebuild, since the branding tier landed. Most of the 1823 deletions were `filesAffected` lists being re-sorted (the rebuild normalises them; the narrow repair does too, but only on rows that were already wrong) plus the `stagedDependencies` blocks above. And the three binary-asset patches the report flagged as possible mismatches were an artifact of its own scan: `getAllTargetFilesFromPatch` reads `diff --git` headers, so `GIT binary patch` sections with no `+++ b/` line have been counted correctly since the fix that put them there. Naming what the code actually does is how the next occurrence gets attributed quickly instead of inheriting a guess.
+
 ### Performance
 
 - **`getAllDiff` spawned one `git hash-object` per untracked file, uncapped.** Its sibling `getDiffForFilesAgainstHead` was reshaped into classify → one batched hash → render for exactly this reason; this path kept the per-file form, and it is the only path behind `tree create`, `tree list`, `tree remove --all`, `lint` and `export-all` — against a Firefox tree where "untracked" can mean a very large number of files. Now batched. Everything observable is deliberately unchanged (renames, `ls-files` ordering, tracked-block-first emission, the `'\n'` empty sentinel) because this output is SHA-256'd into every tree fingerprint and written verbatim into `.patch` files; a new real-git test pins those bytes, which nothing did before.
@@ -117,6 +159,20 @@ A downstream fork runs this checkout with up to five concurrent agent sessions,
 - **A `patches.json` from a newer FireForge was reported as malformed.** `patches.json version must be 1` sent the operator looking for damage in a file that only needed a newer build to read it, and the manifest had no migration hook at all. It now refuses by name — naming the found and supported schema versions and telling the operator not to delete the file — while a version below 1 or non-integer keeps the plain malformed message, because that one really is malformed.
 - The three JSDoc walkers in `patch-lint-jsdoc.ts` return their issues instead of pushing into an out-param, matching the ~30 other patch-lint entry points. The new `jsdoc/check-param-names` rule immediately caught the stale `@param issues` the change left behind — which is the point of enabling it.
 
+### Windows
+
+- **`fireforge lint`'s checkJs pass reported ZERO findings on Windows, silently.** `patch-lint-checkjs.ts` keys `ownedAbsolute` / `relByAbsolute` / `pathsResolved` on `resolve(repoDir, rel)` — backslashes — but TypeScript's `CompilerHost` hands `getSourceFile`/`fileExists` a `/`-normalized `fileName` on every platform. Every lookup missed, so the host served an empty synthetic source file for each owned file and the whole pass came back clean. "No diagnostics" is indistinguishable from "no problems", which is why nothing caught it. The maps are now keyed through one `toTsPath()` helper in the TypeScript spelling. `typecheck.ts` had the same defect on its synthetic shim: never served, and its own diagnostics never filtered out.
+- **`furnace diff` reported every overridden file as a new file.** The engine-relative path it hands `git show <ref>:<path>` came from slicing a native path, and git's `ref:path` form only understands forward slashes — so every baseline read missed and the command showed nothing to diff.
+- **Engine-relative paths were recorded in two spellings at once.** `furnace-apply-helpers.ts` and `furnace-apply-ftl.ts` pushed `relative(engineDir, …)` results — backslashes on Windows — into lists whose sibling entries are POSIX literals, and those lists are identifiers: they go to git, into furnace state, and are compared against the POSIX paths `furnace.json` and `jar.mn` already carry. Normalized at the five producing sites.
+- **`build-audit` collapsed to one path segment**, so the same-basename collision heuristic and the stale/missing classification stopped discriminating; **`removeTree` refused every removal** as an escape from the trees directory, because it compared a `join`ed prefix against a `resolve`d root and only the latter carries a drive letter; and **`initRepository` never pinned `core.autocrlf`**, so on a host with git's Windows default the checkout rewrote LF to CRLF — shifting the blob hashes `hashObjectBatch` delegates to git, and with them the bytes patches are exported from and applied to.
+- **`furnace init` accepted `--ftl-base-path ../escape/path` on Windows.** The traversal guard normalized the value and then tested it for a `../` prefix, but the platform `normalize` emits backslashes there, so `..\escape\path` failed the check and the escape was written into `furnace.json`. The guard normalizes with the POSIX rules regardless of host; the sibling absolute-path and null-byte checks were already separator-agnostic.
+- **`furnace` jsconfig sync did nothing on Windows.** `isManagedEntry` decided whether a `compilerOptions.paths` entry pointed into the components workspace with `target.startsWith(resolve(customDir) + '/')`. The hard-coded `/` never matches what `resolve` produces there, so every Furnace-managed entry was classified as hand-written and preserved verbatim: entries whose helper was deleted were never pruned and entries whose target moved were never updated. Containment now goes through `isPathInsideRoot`, the same `relative`-based check the rest of the codebase uses. The failure was silent in the worst way — a clean `+0 added, ~0 updated, -0 pruned` summary reads as "already in sync".
+- **The `build-audit` segment-splitting defect had a second site.** `pathSegments` was normalized above, but `isConfidentMatch` still split candidates on `/` alone, so the non-generic-segment bonus — the signal that keeps a cross-tree re-root like `branding/<name>/content/aboutDialog.css` → `chrome/<area>/content/branding/aboutDialog.css` classified as `stale` — could never fire on Windows, and real staleness was reported as `missing`.
+
+On the test side: path expectations and mock keys are rendered through a new `nativePath()` test helper rather than hard-coded POSIX literals; fixture repos pin `core.autocrlf=false` / `core.eol=lf`; the three modules that branch on `process.platform` directly now have that branch forced rather than inherited from the runner; and the doctor summary count is derived rather than pinned at 16, since the orphaned-harness check is `skipIf` win32. The genuinely POSIX-only suites — `tree`, `tree exec`, `run --smoke-exit`, and the `chmod`-as-refusal tests — are skipped explicitly, and each skip is paired with a new platform-stubbed test that pins the win32 refusal itself, which nothing did before.
+
+`nativePath()` turned out to be the wrong tool for part of that job, and applying it uniformly produced failures of its own. It swaps separators only, which is correct for a value the code built with `join` but wrong for one it passed through `resolve`: on Windows `resolve` also prefixes the current drive, so the expectation has to be `D:\project\x`, not `\project\x`. A sibling `nativeAbsPath()` covers that case, and the assertions that were wrapped despite never touching a separator at all — pure suffix concatenation, a pass-through argument, and a suite whose `getProjectPaths` mock returns POSIX literals on every platform — go back to comparing the literal. Four doctor summary assertions had also kept their POSIX counts inline while the clean-run count next to them was already derived, so the derivation now covers every summary line in the suite. Two more `chmod`-as-refusal tests joined the skip list: they were skipped for `root` but not for Windows, where mode bits are ignored outright, so the "unreadable" setup was a no-op and the code correctly reported success.
+
 ### Test infrastructure
 
 - **`createLoggerMock()` and `createFsMock()`** in `src/test-utils/module-mocks.ts` replace hand-rolled `vi.mock` factories at 110 sites. `utils/logger.js` was mocked in 118 files by 113 full-replacement factories across 55 distinct key-sets, 34 appearing exactly once; `utils/fs.js` had 89 more. Each enumerated a SUBSET of the real module, so adding one export turned it `undefined` everywhere the factory omitted it — which happened twice while writing this release, 106 files each time.
@@ -126,6 +182,13 @@ A downstream fork runs this checkout with up to five concurrent agent sessions,
 - 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.
 - `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
+
+- **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.
+- `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
 
 ### Verdict correctness

package/README.md

@@ -20,10 +20,10 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 
 ## Requirements
 
-- Node.js 22.22.1+
+- Node.js 22.22.2+
 - Python 3
 - Git
-- The normal Firefox platform build tools: Xcode command line tools on macOS, `build-essential`-style packages on Linux, Visual Studio Build Tools on Windows (never tested on Windows tbh — smoke-run process cleanup there uses `taskkill /T /F` and is best-effort)
+- The normal Firefox platform build tools: Xcode command line tools on macOS, `build-essential`-style packages on Linux, Visual Studio Build Tools on Windows.
 - Watchman, if you want `fireforge watch` (optional)
 
 ## Getting Started
@@ -55,122 +55,15 @@ After setup you should have a `fireforge.json`, an `engine/` directory containin
 npx fireforge status
 npx fireforge export browser/base/content/browser.js --name custom-toolbar --category ui
 npx fireforge re-export custom-toolbar
-npx fireforge re-export --scan --scan-files generated-assets.json --dry-run
 npx fireforge lint --per-patch
-npx fireforge lint --per-patch --max-warnings 0
 npx fireforge verify
-npm run whitespace:check
 npx fireforge build
 npx fireforge test browser/base/content/test/browser/
 ```
 
-Use `fireforge --help` for the full set of commands.
-
-For large generated asset batches, `re-export --scan --scan-files <manifest>` assigns files to
-their owner patches without broad directory scanning. The manifest is JSON:
-
-```json
-{
-  "assignments": [
-    { "patch": "002-branding-runtime-icons.patch", "files": ["browser/branding/hominis/icon.svg"] }
-  ]
-}
-```
-
-The command is dry-runnable, refuses ambiguous ownership, and reports each file-to-patch
-assignment before refreshing the patch. For release whitespace checks, use
-`npm run whitespace:check`; it still checks source diffs while excluding generated
-`patches/*.patch` diff syntax.
-
-Queue maintenance lives under `fireforge patch`: `patch compact` closes ordinal gaps
-(range-aware when `patchPolicy.ranges` is configured), `patch reorder` moves a patch, and
-`patch split <source> --files <paths...> --name <name>` carves files out of a patch into a
-new one as a single transaction — including staged-dependency owner rewrites — with
-`--dry-run` support. `patch rename` also supports `--category` and `--order`; every
-queue-mutating patch command accepts `--wait-lock [seconds]`.
-
-Under several concurrent sessions a held lock is the normal state, not an exceptional
-one, so a wait budget is a property of the session rather than of the invocation: set
-`FIREFORGE_WAIT_LOCK=<seconds>` and every lock-taking command that was not given an
-explicit `--wait-lock` uses it. A wait whose queue position keeps improving is granted a
-fresh budget on each advance (up to four times the requested one, capped at an hour), so
-a long-but-moving queue no longer expires one position from the head; a queue that stops
-moving still starves on the budget you asked for, and the refusal names the position you
-reached.
-
-`fireforge test <directory>` runs exactly that directory: FireForge enumerates the
-directory's test files and passes the explicit file list to mach in one invocation, so
-mach's prefix-based path matching cannot silently sweep in sibling directories sharing the
-name prefix (excluded siblings are echoed with their test-file counts). Multiple path
-arguments run as sequential shards by default — one browser instance per argument, with a
-directory argument keeping its files together — announced with a notice, since isolated
-instances do not exercise cross-argument state (`--no-shard` restores one combined
-invocation). Recognized harness crashes retry up to `--harness-retries <n>` times (default
-2), and `--perf-samples <path>` publishes a perf-sample artifact path to the harness
-(exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
-Every test run ends with one machine-readable `FIREFORGE-VERDICT: PASS|FAIL ...` line;
-automation should use it instead of the raw process code and treat a missing verdict as
-failure.
-Pathless test runs must choose a mode: `--auto` forwards mach's own auto-selection,
-`--doctor` runs the Marionette preflight only, and `--canary [path]` runs one short
-browser-chrome canary (`test.canaryPath` / `test.canaryTimeoutSeconds` in `fireforge.json`
-provide defaults). When packageable engine files changed since the last successful
-FireForge build, `test` fails before launching stale artifacts; use `--build` to refresh
-or `--allow-stale-build` only for intentional out-of-band rebuilds. `--build-only`
-packages mixed-harness paths once; `--extend-coverage` safely retains prior scoped
-coverage. `--kill-stale-marionette` terminates recognized stale browsers. In dev builds,
-files under `obj-*/dist/bin`
-may be symlinks back into the source tree (notably prefs), so edit source prefs directly
-and keep a backup before bisection experiments.
-
-Patch names are normalized on export/rename: `window-chrome-tests`,
-`ui-window-chrome-tests`, and `235-ui-window-chrome-tests` all resolve to the same
-`<order>-ui-window-chrome-tests.patch` shape. For focused queue checks,
-`lint --per-patch --patches` accepts repeated flags, comma lists, full filenames/stems,
-manifest names, category-prefixed slugs, and bare slugs.
-
-Projects with generated asset prerequisites can declare opt-in `externalToolchains` in
-`fireforge.json`; `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`.
-Design tokens are managed with `fireforge token add`; pass `--create-category` to declare a
-new category banner and insert the token in one step.
-
-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).
-
-Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals shim that
-tracks upstream WebIDL additions per release; a project's `patchLint.checkJsExtraShim` can
-add members to the structured shim globals via TypeScript interface merging (e.g.
-`interface ChromeUtilsShim { newApi(): any }`). Opting into
-`patchLint.checkJsTestFiles: true` extends the pass to patch-owned test `.js` files
-(`browser_*`/`test_*`/`xpcshell_*` and `/test/` paths), each 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.
-
-For CI enforcement, `fireforge status --check` exits non-zero when any unmanaged,
-drifted, or conflicted file exists (`--fail-on <class,...>` tunes the policy set, and
-`--json` composes — the JSON stays parseable and its `files[]` entries name the owning
-`patch`). `--include-ownership` adds ownership rows to JSON status output. Scan-less
-`re-export` previews drift; `--refuse-foreign-drift --expect <path>` restricts it to
-intended files. `lint --per-patch --report <path>` writes a machine-readable JSON report with
-each patch's line count, tier, active size thresholds, issues, and lintIgnore-suppressed
-issues; the size metrics (`countNonBinaryDiffLines`, `resolvePatchSizeTier`,
-`getPatchSizeThresholds`) are also exported on the programmatic API.
-
-For concurrent read-mostly verification beside a busy primary checkout,
-`fireforge tree create <name>` snapshots the project — applied engine tree included,
-`obj-*` excluded — into `.fireforge/trees/<name>` using filesystem copy-on-write (APFS
-clonefile / btrfs-XFS reflink; ~3 s for a 156 MB applied browser tree). Read-only commands
-and export/re-export dry runs work inside a tree; mutations are refused. `--with-objdir`
-adds a safely relocated build for build-less tests. `tree list` reports staleness,
-`tree remove` deletes (refusing active locks), and `tree exec <name> -- <cmd>` runs a
-command inside a tree. Filesystems without CoW support refuse unless `--force-copy`
-explicitly accepts a full physical copy.
+Use `fireforge --help` for the full set of commands, and
+[`docs/patch-workflow.md`](docs/patch-workflow.md) for what the loop actually
+guarantees.
 
 ## Rebasing Firefox Source
 
@@ -197,16 +90,22 @@ npx fireforge furnace status
 npx fireforge furnace preview
 ```
 
-Use `fireforge furnace --help` for the full set of component commands.
+Use `fireforge furnace --help` for the full set of component commands, and
+[`docs/furnace.md`](docs/furnace.md) for shared CSS fragments and typed
+cross-module imports.
+
+## Documentation
+
+[`docs/`](docs/README.md) holds the reference material:
 
-Cross-widget CSS can be single-sourced as shared fragments: place the fragment in
-`components/shared/` and reference it from a widget stylesheet with a
-`/* @fireforge-include <fragment>.css */` comment — deploy expands it into the deployed
-copy only, and editing the fragment surfaces as component drift until the next deploy.
-For typed cross-module imports of multi-file components, set
-`furnace.json#typecheckJsconfig` to a consumer-owned jsconfig and deploy will maintain
-`compilerOptions.paths` entries mapping each deployed
-`chrome://global/content/elements/<file>.mjs` URL to its workspace source.
+- [Patch workflow](docs/patch-workflow.md) — export, re-export, queue maintenance, per-patch lint, CI gating
+- [Testing](docs/testing.md) — `fireforge test` scope, modes, build freshness, the verdict line
+- [Furnace](docs/furnace.md) — components, shared CSS fragments, typed imports
+- [Verification trees](docs/verification-trees.md) — CoW snapshots for concurrent verification
+- [Configuration](docs/configuration.md) — `fireforge.json`, design tokens, lock waits, environment variables
+- [Exit codes](docs/exit-codes.md) and [machine-readable output](docs/machine-output.md) — the contract for scripts and CI
+- [Run logs](docs/run-logs.md) — what `test` and `build` leave behind
+- [Lifecycle invariants](docs/lifecycle-invariants.md) — locking, rollback and signal handling internals
 
 ## Roadmap
 

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.0",
-  "commit": "93892e54177df3f88391e3b571674fd1189be43d",
-  "shortCommit": "93892e54177d",
+  "version": "0.44.2",
+  "commit": "d653751d6c8a1be154647943dc346e81cc62b390",
+  "shortCommit": "d653751d6c8a",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-08-27T18:55:32.566Z"
+  "buildTime": "2026-08-28T13:39:36.337Z"
 }

package/dist/src/commands/build.js

@@ -8,6 +8,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, runMach, withBuildLock, } from '../core/mach.js';
+import { closeActiveRunLog, getActiveRunLogPath, openRunLog, setActiveRunLog, } from '../core/run-log.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { formatToolchainMismatchMessage, runToolchainPreflight, } from '../core/toolchain-preflight.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
@@ -170,6 +171,22 @@ export async function buildCommand(projectRoot, options) {
     const buildType = options.ui ? 'UI-only' : 'Full';
     const brandInfo = options.brand ? ` [${options.brand}]` : '';
     intro(`FireForge Build (${buildType}${brandInfo})`);
+    // A build's own complete output, kept independently of whatever the
+    // operator piped the run through. `build` prints no FIREFORGE-VERDICT
+    // line, so the path is announced directly at the end of the run.
+    setActiveRunLog(await openRunLog(projectRoot, 'build'));
+    try {
+        await runBuildCommandBody(projectRoot, options);
+    }
+    finally {
+        const logPath = getActiveRunLogPath();
+        await closeActiveRunLog();
+        if (logPath !== undefined)
+            info(`Full build output: ${logPath}`);
+    }
+}
+async function runBuildCommandBody(projectRoot, options) {
+    const buildType = options.ui ? 'UI-only' : 'Full';
     // Load configuration
     const config = await loadConfig(projectRoot);
     const paths = getProjectPaths(projectRoot);

package/dist/src/commands/doctor-check-core.d.ts

@@ -40,6 +40,15 @@ export interface DoctorCheckContext {
      * re-parse the file; undefined when the config could not be loaded.
      */
     furnaceConfig: FurnaceConfig | undefined;
+    /**
+     * State this run actually mutated, one human-readable line per write.
+     * Repairs run inside the check loop while the exit code is computed only
+     * after every check, so a repair can land and the run still exit non-zero
+     * on an unrelated check — and a non-zero exit reads as "nothing happened".
+     * The runner prints these before the summary in every branch so a write is
+     * never invisible.
+     */
+    mutations: string[];
 }
 /**
  * Result a check may return. A single object is the common case; an array

package/dist/src/commands/doctor-patch-manifest.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The patch-manifest consistency check and its two repair paths, split out of
+ * `doctor.ts` for the line budget. Exports a single `DoctorCheckDefinition`
+ * consumed by the doctor registry; no registrar is exported and none is wanted.
+ */
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/** Patch manifest consistency check, with its opt-in repair paths. */
+export declare const PATCH_MANIFEST_CONSISTENCY_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-patch-manifest.js

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The patch-manifest consistency check and its two repair paths, split out of
+ * `doctor.ts` for the line budget. Exports a single `DoctorCheckDefinition`
+ * consumed by the doctor registry; no registrar is exported and none is wanted.
+ */
+import { rebuildPatchesManifest, recommendManifestRepair, repairPatchesFilesAffected, validatePatchesManifestConsistency, } from '../core/patch-manifest.js';
+import { FireForgeError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { info, warn } from '../utils/logger.js';
+import { resolveWaitLockSeconds } from '../utils/options.js';
+import { failure, ok, warning } from './doctor-check-core.js';
+const CHECK_NAME = 'Patch manifest consistency';
+/** Runs the narrow `filesAffected` repair over the drifted rows. */
+async function runFilesAffectedRepair(ctx, issues) {
+    const drifted = issues.filter((issue) => issue.code === 'files-affected-mismatch');
+    const otherCodes = [
+        ...new Set(issues.filter((issue) => issue.code !== 'files-affected-mismatch').map((issue) => issue.code)),
+    ].sort((left, right) => left.localeCompare(right));
+    if (drifted.length === 0) {
+        return failure(CHECK_NAME, `--repair-files-affected has nothing to repair: no filesAffected drift, but ${issues.length} ` +
+            `other issue(s) remain (${otherCodes.join(', ')}).`, recommendManifestRepair(issues));
+    }
+    const dryRun = ctx.options.dryRun === true;
+    const result = await repairPatchesFilesAffected(ctx.paths.patches, drifted.map((issue) => issue.filename), {
+        waitLockSeconds: resolveWaitLockSeconds(ctx.options.waitLock),
+        command: 'doctor --repair-files-affected',
+        dryRun,
+    });
+    for (const repair of result.repairs) {
+        info(`  ${describeFilesAffectedRepair(repair, dryRun)}`);
+    }
+    for (const filename of result.skippedFilenames) {
+        warn(`Skipped ${filename}: it has no manifest row, or no patch file on disk. ` +
+            'That is a different consistency issue — re-run doctor without --repair-files-affected ' +
+            'to see it reported.');
+    }
+    if (result.written) {
+        ctx.mutations.push(`patches/patches.json — filesAffected corrected on ${describeCount(result.repairs.length)} (--repair-files-affected)`);
+    }
+    const remaining = otherCodes.length > 0
+        ? ` ${otherCodes.length} other issue type(s) remain: ${otherCodes.join(', ')}.`
+        : '';
+    if (otherCodes.length > 0) {
+        return failure(CHECK_NAME, `${summarizeFilesAffected(result.repairs.length, dryRun)}${remaining}`, recommendManifestRepair(issues.filter((issue) => issue.code !== 'files-affected-mismatch')));
+    }
+    return warning(CHECK_NAME, summarizeFilesAffected(result.repairs.length, dryRun));
+}
+function describeFilesAffectedRepair(repair, dryRun) {
+    const verb = dryRun ? 'would set' : 'set';
+    return `${repair.filename}: ${verb} filesAffected to ${repair.after.length} file(s) (was ${repair.before.length}).`;
+}
+function summarizeFilesAffected(count, dryRun) {
+    if (count === 0)
+        return 'No filesAffected drift to repair.';
+    return dryRun
+        ? `Dry run — would correct filesAffected on ${describeCount(count)}. Nothing was written.`
+        : `Corrected filesAffected on ${describeCount(count)}. No other manifest field was touched.`;
+}
+function describeCount(count) {
+    return `${count} patch${count === 1 ? '' : 'es'}`;
+}
+/** Runs the whole-manifest rebuild. */
+async function runManifestRebuild(ctx) {
+    // Repair stamps sourceEsrVersion into every recovered entry. If the
+    // earlier "fireforge.json is valid" check failed, ctx.config is
+    // undefined and we must refuse rather than fabricate a fallback —
+    // persisting 'unknown' into manifest metadata is hard to reverse
+    // and would mislead every later command that reads it.
+    if (!ctx.config) {
+        return failure(CHECK_NAME, 'Cannot repair patches.json: fireforge.json could not be loaded, so the Firefox version to stamp into recovered manifest entries is unknown.', 'Fix the fireforge.json errors reported above and re-run "fireforge doctor --repair-patches-manifest". ' +
+            'If the drift is only in filesAffected, "fireforge doctor --repair-files-affected" needs no config.');
+    }
+    const dryRun = ctx.options.dryRun === true;
+    const repaired = await rebuildPatchesManifest(ctx.paths.patches, ctx.config.firefox.version, {
+        waitLockSeconds: resolveWaitLockSeconds(ctx.options.waitLock),
+        command: 'doctor --repair-patches-manifest',
+        dryRun,
+        ...(ctx.options.allowMetadataLoss === true ? { allowMetadataLoss: true } : {}),
+    });
+    // The repair path must not silently overwrite human-written
+    // descriptions on recovered entries, which leaves the queue less
+    // trustworthy as an audit trail. The rebuilder returns the list of
+    // filenames whose metadata was entirely invented, named explicitly
+    // here so the operator knows which patches to review. Entries that
+    // WERE preserved (only `filesAffected` / ordering drifted) are not
+    // flagged.
+    for (const filename of repaired.recoveredFilenames) {
+        // Telling the operator to hand-edit patches.json contradicts the
+        // README and downstream docs, which treat the manifest as
+        // FireForge-owned. Point at the existing `re-export` / `export`
+        // workflow so the fix stays inside the tool: re-exporting the
+        // same files with an explicit `--description` overwrites the
+        // recovered entry with operator-supplied metadata and supersedes
+        // the mtime-based createdAt stamp.
+        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. ` +
+            'Re-export the affected files with `fireforge re-export <filename> --description "<your description>"` ' +
+            '(or `fireforge export <paths...> --name <name> --category <category> --description "<your description>"`) ' +
+            'to overwrite the reconstructed metadata, or accept the generic description if the original text is not recoverable. ' +
+            'Avoid hand-editing patches.json — FireForge owns that file and will regenerate it on the next manifest consistency pass.');
+    }
+    // A row whose patch file is gone is dropped by the rebuild. That is
+    // correct — the patch file is the source of truth — but a manifest that
+    // quietly loses rows is exactly what makes a repair hard to audit
+    // afterwards, so each one is named.
+    for (const filename of repaired.droppedFilenames) {
+        warn(`Dropped the manifest entry for ${filename}: no such patch file on disk. ` +
+            'Restore the .patch file and re-run the repair if the entry should have survived.');
+    }
+    if (repaired.written) {
+        ctx.mutations.push('patches/patches.json — rebuilt from the on-disk patch files (--repair-patches-manifest)');
+    }
+    const patchCount = repaired.manifest.patches.length;
+    const recovered = repaired.recoveredFilenames.length > 0
+        ? ` (${repaired.recoveredFilenames.length} with reconstructed metadata — see warnings above)`
+        : '';
+    return warning(CHECK_NAME, dryRun
+        ? `Dry run — would rebuild patches.json from ${describeCount(patchCount)}${recovered}. Nothing was written.`
+        : `Rebuilt patches.json from ${describeCount(patchCount)}${recovered}. Review recovered metadata before release.`);
+}
+/** Patch manifest consistency check, with its opt-in repair paths. */
+export const PATCH_MANIFEST_CONSISTENCY_CHECK = {
+    name: CHECK_NAME,
+    dependsOn: ['fireforge.json is valid'],
+    run: async (ctx) => {
+        if (!(await pathExists(ctx.paths.patches))) {
+            return [];
+        }
+        const issues = await validatePatchesManifestConsistency(ctx.paths.patches);
+        if (issues.length === 0) {
+            return ok(CHECK_NAME);
+        }
+        const wantsFilesAffected = ctx.options.repairFilesAffected === true;
+        const wantsRebuild = ctx.options.repairPatchesManifest === true;
+        if (!wantsFilesAffected && !wantsRebuild) {
+            return failure(CHECK_NAME, issues.map((issue) => issue.message).join(' '), recommendManifestRepair(issues));
+        }
+        try {
+            return wantsFilesAffected
+                ? await runFilesAffectedRepair(ctx, issues)
+                : await runManifestRebuild(ctx);
+        }
+        catch (err) {
+            const error = toError(err);
+            // A refusal from the repair itself already carries the remedy that
+            // fits it (which flag, which file to fix). Appending the generic hint
+            // under it buries the specific one and reads as a second, vaguer
+            // instruction. Only an unexpected throw gets the generic hint.
+            return error instanceof FireForgeError
+                ? failure(CHECK_NAME, error.message)
+                : failure(CHECK_NAME, error.message, 'Repair failed. Fix the underlying patch metadata issue and retry the doctor command.');
+        }
+    },
+};

package/dist/src/commands/doctor.d.ts

@@ -29,7 +29,7 @@ export declare const DOCTOR_CHECK_ORDER: readonly string[];
  * @param checks - The check results to display
  * @returns The exit code reflecting the overall result
  */
-export declare function reportDoctorResults(checks: DoctorCheck[]): ExitCode;
+export declare function reportDoctorResults(checks: DoctorCheck[], mutations?: readonly string[]): ExitCode;
 /**
  * Result of the doctor command, carrying the exit code so the caller
  * (or test) can inspect it without relying on process.exitCode.