@hominis/fireforge 0.44.0 → 0.44.1

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.
@@ -63,6 +63,24 @@ 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.
 
+### 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 +135,15 @@ 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.
+
+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.
+
 ### 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.

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
@@ -89,15 +89,6 @@ new one as a single transaction — including staged-dependency owner rewrites
 `--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

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.0",
-  "commit": "93892e54177df3f88391e3b571674fd1189be43d",
-  "shortCommit": "93892e54177d",
+  "version": "0.44.1",
+  "commit": "b77a037425f19e19c43a64a5bb1ff79d949af92e",
+  "shortCommit": "b77a037425f1",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-08-27T18:55:32.566Z"
+  "buildTime": "2026-08-27T22:08:53.928Z"
 }

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.

package/dist/src/commands/doctor.js

@@ -6,17 +6,19 @@ import { getCurrentBranch, getHead, isGitRepository, isMissingHeadError } from '
 import { ensureGit } from '../core/git-base.js';
 import { ensureMach, ensurePython } from '../core/mach.js';
 import { countPatches } from '../core/patch-apply.js';
-import { rebuildPatchesManifest, validatePatchesManifestConsistency, validatePatchIntegrity, } from '../core/patch-manifest.js';
+import { validatePatchIntegrity } from '../core/patch-manifest.js';
+import { InvalidArgumentError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
-import { addWaitLockOption, resolveWaitLockSeconds } from '../utils/options.js';
+import { addWaitLockOption } from '../utils/options.js';
 import { findExecutable } from '../utils/process.js';
 import { failure, ok, resolveDoctorSeverity, warning } from './doctor-check-core.js';
 import { EXTERNAL_TOOLCHAIN_DOCTOR_CHECK } from './doctor-external-toolchains.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { ORPHANED_HARNESS_DOCTOR_CHECK } from './doctor-orphaned-harness.js';
+import { PATCH_MANIFEST_CONSISTENCY_CHECK } from './doctor-patch-manifest.js';
 import { POST_REBASE_AUDIT_CHECK } from './doctor-post-rebase-audit.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 import { collectPatchQueueHealth } from './verify.js';
@@ -274,63 +276,7 @@ const DOCTOR_CHECKS = [
             return ok('Patches found', `${patchCount} patch${patchCount === 1 ? '' : 'es'} found`);
         },
     },
-    {
-        name: 'Patch manifest consistency',
-        dependsOn: ['fireforge.json is valid'],
-        run: async (ctx) => {
-            if (!(await pathExists(ctx.paths.patches))) {
-                return [];
-            }
-            const manifestConsistencyIssues = await validatePatchesManifestConsistency(ctx.paths.patches);
-            if (manifestConsistencyIssues.length === 0) {
-                return ok('Patch manifest consistency');
-            }
-            if (!ctx.options.repairPatchesManifest) {
-                return failure('Patch manifest consistency', manifestConsistencyIssues.map((issue) => issue.message).join(' '), 'Run "fireforge doctor --repair-patches-manifest" to rebuild patches.json from patch files.');
-            }
-            // 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('Patch manifest consistency', '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".');
-            }
-            try {
-                const repaired = await rebuildPatchesManifest(ctx.paths.patches, ctx.config.firefox.version, {
-                    waitLockSeconds: resolveWaitLockSeconds(ctx.options.waitLock),
-                    command: 'doctor --repair-patches-manifest',
-                });
-                // 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.
-                if (repaired.recoveredFilenames.length > 0) {
-                    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.');
-                    }
-                }
-                return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.manifest.patches.length} patch${repaired.manifest.patches.length === 1 ? '' : 'es'}${repaired.recoveredFilenames.length > 0 ? ` (${repaired.recoveredFilenames.length} with reconstructed metadata — see warnings above)` : ''}. Review recovered metadata before release.`);
-            }
-            catch (err) {
-                return failure('Patch manifest consistency', toError(err).message, 'Repair failed. Fix the underlying patch metadata issue and retry the doctor command.');
-            }
-        },
-    },
+    PATCH_MANIFEST_CONSISTENCY_CHECK,
     {
         name: 'Patch integrity',
         skipIf: (ctx) => !ctx.engineExists,
@@ -382,7 +328,7 @@ export const DOCTOR_CHECK_ORDER = DOCTOR_CHECKS.map((check) => check.name);
  * @param checks - The check results to display
  * @returns The exit code reflecting the overall result
  */
-export function reportDoctorResults(checks) {
+export function reportDoctorResults(checks, mutations = []) {
     info('');
     let passedCount = 0;
     let warningCount = 0;
@@ -409,6 +355,16 @@ export function reportDoctorResults(checks) {
         }
     }
     info('');
+    // Printed in every branch, including the failing one: a repair that wrote
+    // and then met an unrelated failing check must not be reported as a run
+    // where nothing happened.
+    if (mutations.length > 0) {
+        warn('Repairs applied this run:');
+        for (const mutation of mutations) {
+            warn(`  ${mutation}`);
+        }
+        info('');
+    }
     if (failedCount === 0 && warningCount === 0) {
         outro(`All ${passedCount} checks passed!`);
     }
@@ -421,12 +377,38 @@ export function reportDoctorResults(checks) {
     }
     return ExitCode.SUCCESS;
 }
+/**
+ * Rejects repair-flag combinations that cannot mean what they say.
+ *
+ * The two manifest repairs are different operations on the same file, and
+ * `--dry-run` with nothing to project is a flag that silently does nothing —
+ * the shape most likely to be mistaken for a preview that reported "no
+ * changes".
+ */
+function assertRepairOptions(options) {
+    if (options.repairPatchesManifest === true && options.repairFilesAffected === true) {
+        throw new InvalidArgumentError('--repair-patches-manifest and --repair-files-affected are mutually exclusive. ' +
+            'Use --repair-files-affected for filesAffected drift; use --repair-patches-manifest ' +
+            'when rows are missing, untracked or duplicated.', '--repair-files-affected');
+    }
+    if (options.allowMetadataLoss === true && options.repairPatchesManifest !== true) {
+        throw new InvalidArgumentError('--allow-metadata-loss only applies to --repair-patches-manifest.', '--allow-metadata-loss');
+    }
+    if (options.dryRun === true &&
+        options.repairPatchesManifest !== true &&
+        options.repairFilesAffected !== true) {
+        throw new InvalidArgumentError('--dry-run needs a manifest repair to project. Pass it with ' +
+            '--repair-patches-manifest or --repair-files-affected. ' +
+            '(--repair-furnace has no dry-run: it reconciles engine state, not a manifest.)', '--dry-run');
+    }
+}
 /**
  * Runs the doctor command to diagnose issues.
  * @param projectRoot - Root directory of the project
  */
 export async function doctorCommand(projectRoot, options = {}) {
     intro('FireForge Doctor');
+    assertRepairOptions(options);
     const paths = getProjectPaths(projectRoot);
     const state = await loadState(projectRoot);
     const engineExists = await pathExists(paths.engine);
@@ -440,12 +422,13 @@ export async function doctorCommand(projectRoot, options = {}) {
         config: undefined,
         furnaceConfigExists: furnaceConfigExistsFlag,
         furnaceConfig: undefined,
+        mutations: [],
     };
     const checks = [];
     for (const definition of DOCTOR_CHECKS) {
         checks.push(...(await executeCheck(definition, ctx)));
     }
-    const exitCode = reportDoctorResults(checks);
+    const exitCode = reportDoctorResults(checks, ctx.mutations);
     return { checks, exitCode };
 }
 /** Registers the doctor command on the CLI program. */
@@ -453,7 +436,10 @@ export function registerDoctor(program, { getProjectRoot, withErrorHandling }) {
     const command = program
         .command('doctor')
         .description('Diagnose project issues')
-        .option('--repair-patches-manifest', 'Rebuild patches/patches.json from the current patch files before reporting results')
+        .option('--repair-patches-manifest', 'Rebuild patches/patches.json from the current patch files before reporting results. Only filesAffected and order are recomputed; every other field on an existing entry is preserved')
+        .option('--repair-files-affected', 'Repair only the filesAffected lists that disagree with their patch body, leaving every other manifest field untouched')
+        .option('--allow-metadata-loss', 'With --repair-patches-manifest, rebuild even when patches.json cannot be parsed — every descriptive field on every entry is then reinvented')
+        .option('--dry-run', 'Show what a requested repair would change without writing anything')
         .option('--repair-furnace', 'Reconcile furnace state: clear stale furnace-state.json entries, re-run furnace apply to fix engine drift, and clear the pending-repair marker set by a failed preview teardown')
         .option('--clear-resolution', 'Clear stale pendingResolution state after the patch queue health check reports no errors')
         .option('--post-rebase-audit', 'Check common registration surfaces after a Firefox source rebase');

package/dist/src/commands/furnace/diff.js

@@ -11,6 +11,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists, readText } from '../../utils/fs.js';
 import { formatErrorText, formatSuccessText, info, intro, outro } from '../../utils/logger.js';
+import { normalizePathSlashes } from '../../utils/paths.js';
 /**
  * Renders a multi-hunk unified diff between the two strings and returns a
  * flat list of display-ready lines. Each line has already had its marker
@@ -64,7 +65,11 @@ async function diffOverride(name, projectRoot, config) {
         if (!isComponentSourceFile(entry.name))
             continue;
         // git show takes a repo-relative path. paths.engine IS the repo root.
-        const enginePath = getOverrideEngineTargetPath(paths.engine, overrideConfig, entry.name, ftlDir).slice(paths.engine.length + 1);
+        // The slice leaves the host's separators behind, and `git show <ref>:<path>`
+        // only understands forward slashes — on Windows the unnormalized form makes
+        // every baseline read miss, so every overridden file is reported as a new
+        // file and `furnace diff` shows nothing.
+        const enginePath = normalizePathSlashes(getOverrideEngineTargetPath(paths.engine, overrideConfig, entry.name, ftlDir).slice(paths.engine.length + 1));
         const modifiedPath = join(overrideDir, entry.name);
         const baselineDisplayPath = enginePath;
         let originalContent;

package/dist/src/commands/furnace/remove-mutations.js

@@ -23,6 +23,7 @@ import { isGitRepository } from '../../core/git.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { pathExists, removeDir, removeFile } from '../../utils/fs.js';
 import { info } from '../../utils/logger.js';
+import { normalizePathSlashes } from '../../utils/paths.js';
 import { removeDeployedCustomFiles } from './remove-state.js';
 /**
  * Restores every override-deployed file in `engine/` to its pristine HEAD
@@ -153,7 +154,10 @@ export async function performCustomRemovalMutations(args) {
         if (await pathExists(ftlPath)) {
             await snapshotFile(journal, ftlPath);
             await removeFile(ftlPath);
-            info(`Deleted localized file engine/${ftlRel}`);
+            // `ftlRel` is a native join, so on Windows an interpolated
+            // `engine/${ftlRel}` renders as `engine/toolkit\locales\...` — one
+            // message with both separators. Print the engine-relative form.
+            info(`Deleted localized file engine/${normalizePathSlashes(ftlRel)}`);
         }
         // Drop the locale jar.mn chrome registration that `applyCustomFtlFile`
         // wrote during deploy — otherwise the engine is left with a

package/dist/src/commands/import.js

@@ -8,7 +8,7 @@ import { assertEngineExists } from '../core/engine-precondition.js';
 import { getHead } from '../core/git.js';
 import { getDirtyFiles } from '../core/git-status.js';
 import { applyPatchesWithContinue, countPatches, createPatchedContentContext, discoverPatches, extractAffectedFiles, matchesUntilFilename, PatchError, } from '../core/patch-apply.js';
-import { checkVersionCompatibility, loadPatchesManifest, validatePatchesManifestConsistency, validatePatchIntegrity, } from '../core/patch-manifest.js';
+import { checkVersionCompatibility, loadPatchesManifest, recommendManifestRepair, validatePatchesManifestConsistency, validatePatchIntegrity, } from '../core/patch-manifest.js';
 import { getPatchSourceVersion } from '../core/patch-source-metadata.js';
 import { warnIfStaticComponentsStale } from '../core/test-stale-check.js';
 import { GeneralError } from '../errors/base.js';
@@ -239,7 +239,11 @@ async function assertScopedManifestConsistency(patchesDir, untilFilenameSet, unt
         const issueSummary = scopedManifestIssues.map((issue) => issue.message).join('\n  ');
         throw new GeneralError('Patch manifest consistency check failed. Repair patches/patches.json before importing.\n' +
             `  ${issueSummary}\n\n` +
-            'Run "fireforge doctor --repair-patches-manifest" to rebuild the manifest from on-disk patch files.');
+            // Naming the whole-manifest rebuild for drift that is only in
+            // `filesAffected` puts the operator one keystroke from rewriting every
+            // row to correct one derived list. The narrow repair is the remedy the
+            // failure actually calls for.
+            recommendManifestRepair(scopedManifestIssues));
     }
 }
 /**

package/dist/src/core/build-audit-resolve.js

@@ -20,6 +20,7 @@
 import { readdir } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { pathExists } from '../utils/fs.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 /** Maximum directory depth to traverse when scanning a tree root. */
 const MAX_SCAN_DEPTH = 12;
 /**
@@ -54,11 +55,19 @@ export function isTestPath(sourcePath) {
     return false;
 }
 /**
- * Splits a POSIX path into segments, dropping empties.
- * @param path POSIX-separated path
+ * Splits a path into segments, dropping empties.
+ *
+ * Separators are normalized first because the candidates come from `join()`
+ * over a `readdir` walk of the dist tree: on Windows those carry backslashes,
+ * which a `/`-only split collapses into a SINGLE segment. Every candidate then
+ * scores the same, so the trailing-overlap heuristic that disambiguates
+ * same-basename artifacts (`branding/…/aboutDialog.css` versus
+ * `browser/…/aboutDialog.css`) silently picks an arbitrary one.
+ *
+ * @param path Path in either separator style
  */
 function pathSegments(path) {
-    return path.split('/').filter(Boolean);
+    return normalizePathSlashes(path).split('/').filter(Boolean);
 }
 /**
  * Counts how many trailing segments two paths share. Used to score