@hominis/fireforge 0.44.0 → 0.44.1

package/dist/src/core/config-mutate.js

@@ -18,21 +18,16 @@ function cloneConfigDocument(config) {
     return cloned;
 }
 /**
- * Key segments that would walk into or rewrite the object prototype chain
- * if used as plain property names. Blocked up-front so the descent in
- * {@link mutateConfig} cannot be weaponized to mutate `Object.prototype`
- * process-wide — e.g. `fireforge config __proto__.polluted 1 --force`
- * would otherwise land in `getOrCreateChildRecord(raw, "__proto__")`.
+ * The error every sentinel-segment refusal raises. Only the MESSAGE lives
+ * here: the comparison itself is spelled inline at each write site, because
+ * that is what both a reader and CodeQL's `js/prototype-pollution-utility`
+ * barrier detection need — the latter is not interprocedural, so a check
+ * hidden behind a helper leaves the descent below looking unguarded.
  */
-const SENTINEL_KEY_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
-function assertNoSentinelSegments(key, parts) {
-    for (const part of parts) {
-        if (SENTINEL_KEY_SEGMENTS.has(part)) {
-            throw new ConfigError(`Config key "${key}" contains a reserved segment "${part}". ` +
-                'Segments "__proto__", "constructor", and "prototype" are not permitted ' +
-                'because they would mutate the object prototype chain.');
-        }
-    }
+function sentinelSegmentError(key, part) {
+    return new ConfigError(`Config key "${key}" contains a reserved segment "${part}". ` +
+        'Segments "__proto__", "constructor", and "prototype" are not permitted ' +
+        'because they would mutate the object prototype chain.');
 }
 function getOrCreateChildRecord(parent, key) {
     const existing = parent[key];
@@ -45,21 +40,27 @@ function getOrCreateChildRecord(parent, key) {
 }
 export function mutateConfig(config, key, value, skipValidation = false) {
     const parts = key.split('.');
-    // Reject prototype-chain sentinel segments before any write so
-    // `--force` cannot be used to mutate Object.prototype. This guard must
-    // run against the original key parts, not any subset — the final leaf
-    // assignment `current[lastPart] = value` would otherwise stay vulnerable.
-    assertNoSentinelSegments(key, parts);
     const raw = cloneConfigDocument(config);
+    // Every segment is checked at the point it is USED as a property name —
+    // the descent below and the leaf assignment — rather than once up front,
+    // so `--force` cannot be used to mutate Object.prototype and neither write
+    // can drift out from behind the guard. `raw` is a private clone, so a
+    // refusal here has mutated nothing the caller can observe.
     let current = raw;
     for (let i = 0; i < parts.length - 1; i++) {
         const part = parts[i];
         if (part === undefined)
             continue;
+        if (part === '__proto__' || part === 'constructor' || part === 'prototype') {
+            throw sentinelSegmentError(key, part);
+        }
         current = getOrCreateChildRecord(current, part);
     }
     const lastPart = parts[parts.length - 1];
     if (lastPart !== undefined) {
+        if (lastPart === '__proto__' || lastPart === 'constructor' || lastPart === 'prototype') {
+            throw sentinelSegmentError(key, lastPart);
+        }
         current[lastPart] = value;
     }
     if (!skipValidation) {

package/dist/src/core/furnace-apply-ftl.js

@@ -14,6 +14,7 @@
 import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { copyFile, pathExists, readText } from '../utils/fs.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
 import { resolveFtlChromeSubPath, resolveFtlLocaleJarMnPath } from './furnace-constants.js';
 import { addLocaleFtlJarMnEntry, removeLocaleFtlJarMnEntry } from './furnace-registration.js';
@@ -133,7 +134,9 @@ export async function applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbac
         await snapshotFile(rollbackJournal, ftlDest);
     }
     await copyFile(ftlSrc, ftlDest);
-    affectedPaths.push(relative(engineDir, ftlDest));
+    // Sibling pushes on this list are POSIX literals (`localeJarRel`); keep
+    // the computed one in the same spelling.
+    affectedPaths.push(normalizePathSlashes(relative(engineDir, ftlDest)));
     const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
     const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
     if (chromeSubPath === undefined || localeJarRel === undefined)

package/dist/src/core/furnace-apply-helpers.js

@@ -6,6 +6,7 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { buildCustomDryRunActions } from './furnace-apply-dry-run.js';
 import { applyCustomFtlFile, applySharedFtlPrune, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
 import { normalizeForChecksum } from './furnace-checksum-utils.js';
@@ -70,7 +71,12 @@ export function getOverrideEngineTargetPath(engineDir, config, fileName, ftlDir)
  * caller should treat that as a successful no-op rather than an error.
  */
 export async function restoreOverrideFileToBaseline(engineDir, enginePath, journal) {
-    const relPath = relative(engineDir, enginePath);
+    // Engine-relative paths are IDENTIFIERS here, not filesystem arguments:
+    // they are handed to git, recorded in furnace state, and compared against
+    // the POSIX paths furnace.json and jar.mn already carry. `relative()`
+    // returns backslashes on Windows, so without this the same file has two
+    // spellings and every cross-check misses.
+    const relPath = normalizePathSlashes(relative(engineDir, enginePath));
     // Snapshot before mutation so a later rollback can undo both restoration
     // (writes whatever content we removed back) and deletion (recreates the
     // file). Snapshotting a missing path records `{ existed: false }`, which
@@ -129,7 +135,7 @@ export async function undeployCustomFiles(engineDir, config, deletedFiles, ftlDi
         }
         if (await pathExists(enginePath)) {
             await removeFile(enginePath);
-            removed.push(relative(engineDir, enginePath));
+            removed.push(normalizePathSlashes(relative(engineDir, enginePath)));
         }
         // When an `.ftl` is deleted from the workspace the corresponding locale
         // jar.mn entry must also be dropped — otherwise the chrome URI points at
@@ -173,7 +179,7 @@ export async function undeployOverrideFiles(engineDir, config, deletedFiles, ftl
     for (const fileName of deletedFiles) {
         const enginePath = getOverrideEngineTargetPath(engineDir, config, fileName, ftlDir);
         const action = await restoreOverrideFileToBaseline(engineDir, enginePath, rollbackJournal);
-        const relPath = relative(engineDir, enginePath);
+        const relPath = normalizePathSlashes(relative(engineDir, enginePath));
         if (action === 'restored')
             restored.push(relPath);
         else if (action === 'removed')
@@ -332,7 +338,7 @@ export async function applyCustomComponent(ctx, config, dryRun = false, rollback
         const src = join(componentDir, entry.name);
         const dest = join(targetDir, entry.name);
         await deployFileWithFragments(src, dest, sharedDir);
-        affectedPaths.push(relative(engineDir, dest));
+        affectedPaths.push(normalizePathSlashes(relative(engineDir, dest)));
         copiedFileNames.push(entry.name);
     }));
     // See buildCustomDryRunActions for the rationale: when `sharedFtl` is set
@@ -425,7 +431,7 @@ export async function applyOverrideComponent(ctx, config, dryRun = false, rollba
         const src = join(componentDir, entry.name);
         const dest = getOverrideEngineTargetPath(engineDir, config, entry.name, ftlDir);
         await copyFile(src, dest);
-        affectedPaths.push(relative(engineDir, dest));
+        affectedPaths.push(normalizePathSlashes(relative(engineDir, dest)));
     }));
     if (affectedPaths.length === 0) {
         throw new FurnaceError(`No matching files found in override directory for "${name}"`, name);

package/dist/src/core/git-base.d.ts

@@ -83,3 +83,17 @@ export declare function chunkPathspecs(paths: string[], budgetBytes?: number): s
  * repositories with hundreds of thousands of files.
  */
 export declare function configureGitPerformance(repoDir: string): Promise<void>;
+/**
+ * Pins the engine repository's line-ending policy to "store and check out
+ * exactly what upstream shipped".
+ *
+ * Git's Windows installer defaults to a global `core.autocrlf=true`, which
+ * rewrites LF to CRLF on checkout and back on staging. FireForge cannot
+ * tolerate that: patch bodies are byte diffs of the working tree, and
+ * `hashObjectBatch` deliberately delegates to git so `.gitattributes` and
+ * `core.autocrlf` DO apply to the hashes `status` compares against. Under the
+ * global default the same tree hashes differently on Windows than everywhere
+ * else, so exported patches and drift detection disagree across machines.
+ * Setting it per-repository leaves the developer's global config alone.
+ */
+export declare function configureGitLineEndings(repoDir: string): Promise<void>;

package/dist/src/core/git-base.js

@@ -120,3 +120,20 @@ export async function configureGitPerformance(repoDir) {
     await git(['config', 'core.fsmonitor', 'false'], repoDir);
     await git(['config', 'feature.manyFiles', 'true'], repoDir);
 }
+/**
+ * Pins the engine repository's line-ending policy to "store and check out
+ * exactly what upstream shipped".
+ *
+ * Git's Windows installer defaults to a global `core.autocrlf=true`, which
+ * rewrites LF to CRLF on checkout and back on staging. FireForge cannot
+ * tolerate that: patch bodies are byte diffs of the working tree, and
+ * `hashObjectBatch` deliberately delegates to git so `.gitattributes` and
+ * `core.autocrlf` DO apply to the hashes `status` compares against. Under the
+ * global default the same tree hashes differently on Windows than everywhere
+ * else, so exported patches and drift detection disagree across machines.
+ * Setting it per-repository leaves the developer's global config alone.
+ */
+export async function configureGitLineEndings(repoDir) {
+    await git(['config', 'core.autocrlf', 'false'], repoDir);
+    await git(['config', 'core.eol', 'lf'], repoDir);
+}

package/dist/src/core/git.js

@@ -9,7 +9,7 @@ import { pathExists, pathExistsStrict, removeFile } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
-import { chunkPathspecs, configureGitPerformance, ensureGit, git, GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, GIT_ADD_CHUNK_TIMEOUT_MS, GIT_ADD_TIMEOUT_MS, } from './git-base.js';
+import { chunkPathspecs, configureGitLineEndings, configureGitPerformance, ensureGit, git, GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, GIT_ADD_CHUNK_TIMEOUT_MS, GIT_ADD_TIMEOUT_MS, } from './git-base.js';
 import { getWorkingTreeStatus } from './git-status.js';
 // ── Functions that remain in this file ──
 /**
@@ -278,6 +278,7 @@ export async function initRepository(dir, branchName = 'main', options = {}) {
     // Enable performance settings for large trees
     reportProgress('Configuring git performance settings...');
     await configureGitPerformance(dir);
+    await configureGitLineEndings(dir);
     // Add a local-only origin remote so that Firefox's mach bootstrap and
     // build scripts (which shell out to `git remote get-url origin`) don't
     // fail.  Nothing is ever fetched from or pushed to this remote.
@@ -318,6 +319,7 @@ export async function resumeRepository(dir, options = {}) {
     // Ensure performance settings are in place (may not have been set)
     reportProgress('Configuring git performance settings...');
     await configureGitPerformance(dir);
+    await configureGitLineEndings(dir);
     // Clean up any stale index lock left by the killed process
     await cleanupIndexLock(dir);
     // Ensure origin remote exists (may have been added before the interrupt)

package/dist/src/core/patch-lint-checkjs.js

@@ -29,10 +29,25 @@ import { basename, resolve } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, TEST_HARNESS_SHIM, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/**
+ * Converts a native path into the form TypeScript uses for `fileName`.
+ *
+ * TypeScript normalizes every path it hands a `CompilerHost` to forward
+ * slashes on ALL platforms, while `resolve()` here yields the platform
+ * separator. On Windows that mismatch made every `ownedAbsolute.has(fileName)`
+ * and `relByAbsolute.get(fileName)` lookup miss, so the host served an empty
+ * source file for each owned file and the whole pass reported zero findings —
+ * silently, because "no diagnostics" is indistinguishable from "clean code".
+ * Every path that crosses the TS boundary goes through here.
+ */
+function toTsPath(path) {
+    return normalizePathSlashes(path);
+}
 /**
  * Builds the host-side module resolver for the checkJs pass: maps an import
  * specifier to a patch-owned absolute path when the specifier's final
@@ -117,8 +132,14 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
                 captured = specifier.slice(prefix.length, specifier.length - suffix.length);
             }
             for (const target of targets) {
-                const rel = target.includes('*') ? target.replace('*', captured) : target;
-                const abs = resolve(baseDir, rel);
+                // A `paths` target carries at most one `*`, and TypeScript substitutes
+                // that one wildcard — spelled as index arithmetic (mirroring the
+                // prefix/suffix split on the pattern side above) rather than
+                // `replace('*', …)`, whose first-occurrence-only behaviour reads as an
+                // incomplete rewrite (CodeQL `js/incomplete-sanitization`).
+                const star = target.indexOf('*');
+                const rel = star === -1 ? target : target.slice(0, star) + captured + target.slice(star + 1);
+                const abs = toTsPath(resolve(baseDir, rel));
                 if (!fileExists(abs))
                     continue;
                 onResolved(abs);
@@ -188,7 +209,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     const ownedAbsolute = new Set();
     const relByAbsolute = new Map();
     for (const rel of resolutionOwned) {
-        const abs = resolve(repoDir, rel);
+        const abs = toTsPath(resolve(repoDir, rel));
         if (await pathExists(abs)) {
             if (rootScope === undefined || rootScope.has(rel))
                 rootFiles.push(abs);
@@ -228,7 +249,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
             ],
         };
     }
-    const shimPath = resolve(repoDir, SHIM_FILENAME);
+    const shimPath = toTsPath(resolve(repoDir, SHIM_FILENAME));
     rootFiles.push(shimPath);
     const strict = mode?.strict === true;
     const strictness = strict

package/dist/src/core/patch-manifest-consistency.d.ts

@@ -15,6 +15,16 @@ export interface PatchManifestConsistencyIssue {
  * @returns Consistency issues between manifest metadata and on-disk patch files
  */
 export declare function validatePatchesManifestConsistency(patchesDir: string): Promise<PatchManifestConsistencyIssue[]>;
+/**
+ * Recovery hint for an unrepaired consistency failure.
+ *
+ * Drift that is only in `filesAffected` is a derived value disagreeing with
+ * the diff it describes, and the narrow repair fixes exactly that. Naming the
+ * whole-manifest rebuild for it — as this hint used to, unconditionally — puts
+ * an operator one keystroke from rewriting every row in the manifest to
+ * correct one list.
+ */
+export declare function recommendManifestRepair(issues: readonly PatchManifestConsistencyIssue[]): string;
 /**
  * Summary of a {@link rebuildPatchesManifest} run. `recoveredFilenames`
  * lists patches whose manifest entry was reconstructed from filename,
@@ -25,21 +35,61 @@ export declare function validatePatchesManifestConsistency(patchesDir: string):
  * invented vs which was restored.
  */
 export interface RebuildPatchesManifestResult {
-    /** Rebuilt manifest, ready to be re-applied by callers (already persisted). */
+    /**
+     * Rebuilt manifest, ready to be re-applied by callers. Persisted unless
+     * the run was a dry run — see {@link RebuildPatchesManifestResult.written}.
+     */
     manifest: PatchesManifest;
     /**
      * Filenames whose manifest entry had no pre-existing metadata to
      * preserve — every descriptive field on these entries is inferred.
      */
     recoveredFilenames: string[];
+    /**
+     * Filenames that had a manifest entry but no patch file on disk, so the
+     * row was dropped. Discarding these silently is how a manifest quietly
+     * loses rows an operator still expected to be there.
+     */
+    droppedFilenames: string[];
+    /** False when the run was a dry run and patches.json was left untouched. */
+    written: boolean;
+}
+/** Options for {@link rebuildPatchesManifest}. */
+export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions {
+    /**
+     * Proceed even when patches.json exists but cannot be parsed, in which case
+     * there is no existing metadata to preserve and every descriptive field on
+     * every entry is invented. Refused without this flag — see
+     * {@link rebuildPatchesManifest}.
+     */
+    allowMetadataLoss?: boolean;
+    /** Compute the rebuilt manifest without writing it. */
+    dryRun?: boolean;
 }
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
- * Existing metadata is preserved when possible; missing entries are recovered
- * from filename structure, patch contents, and file mtimes.
+ *
+ * This is a MERGE, not a from-scratch rebuild: only `filesAffected` and
+ * `order` are recomputed from the patch files, and every other field on an
+ * existing entry is carried forward untouched. Entries with no pre-existing
+ * metadata are recovered from filename structure, patch contents, and file
+ * mtimes.
+ *
+ * Refuses when patches.json exists but cannot be parsed, because that is the
+ * one case where nothing can be carried forward and the "merge" silently
+ * becomes a whole-manifest reinvention. Pass `allowMetadataLoss` to accept it.
+ *
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
- * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
- *   plus the filenames that were reconstructed from generic defaults.
+ * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
+ * @returns {@link RebuildPatchesManifestResult} — the rebuilt manifest, the
+ *   filenames that were reconstructed from generic defaults, and the rows
+ *   dropped because their patch file is gone.
+ */
+export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string, options?: RebuildPatchesManifestOptions): Promise<RebuildPatchesManifestResult>;
+/**
+ * Canonical form of a `filesAffected` list: deduplicated and sorted, so a
+ * comparison between a declared list and one extracted from a patch body is
+ * about membership rather than ordering.
  */
-export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string, lockOptions?: PatchDirectoryLockOptions): Promise<RebuildPatchesManifestResult>;
+export declare function normalizeAffectedFiles(files: string[]): string[];

package/dist/src/core/patch-manifest-consistency.js

@@ -3,6 +3,7 @@
  * Manifest consistency checks and rebuild/recovery operations.
  */
 import { stat } from 'node:fs/promises';
+import { GeneralError } from '../errors/base.js';
 import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
 import { withPatchDirectoryLock } from './patch-lock.js';
 import { loadPatchesManifestState, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
@@ -59,8 +60,8 @@ export async function validatePatchesManifestConsistency(patchesDir) {
             });
             continue;
         }
-        const declaredFiles = normalizeFiles(metadata.filesAffected);
-        const actualFiles = normalizeFiles(await getAllTargetFilesFromPatch(patch.path));
+        const declaredFiles = normalizeAffectedFiles(metadata.filesAffected);
+        const actualFiles = normalizeAffectedFiles(await getAllTargetFilesFromPatch(patch.path));
         if (!sameStringArray(declaredFiles, actualFiles)) {
             issues.push({
                 code: 'files-affected-mismatch',
@@ -80,26 +81,78 @@ export async function validatePatchesManifestConsistency(patchesDir) {
     }
     return issues;
 }
+/**
+ * Recovery hint for an unrepaired consistency failure.
+ *
+ * Drift that is only in `filesAffected` is a derived value disagreeing with
+ * the diff it describes, and the narrow repair fixes exactly that. Naming the
+ * whole-manifest rebuild for it — as this hint used to, unconditionally — puts
+ * an operator one keystroke from rewriting every row in the manifest to
+ * correct one list.
+ */
+export function recommendManifestRepair(issues) {
+    const filesAffectedOnly = issues.length > 0 && issues.every((issue) => issue.code === 'files-affected-mismatch');
+    return filesAffectedOnly
+        ? 'Run "fireforge doctor --repair-files-affected" to recompute filesAffected from the patch ' +
+            'bodies (add --dry-run to preview). It rewrites only the drifted lists and leaves every ' +
+            'other manifest field untouched.'
+        : 'Run "fireforge doctor --repair-patches-manifest" to rebuild patches.json from the patch ' +
+            'files (add --dry-run to preview). Only filesAffected and order are recomputed; every ' +
+            'other field on an existing entry is preserved.';
+}
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
- * Existing metadata is preserved when possible; missing entries are recovered
- * from filename structure, patch contents, and file mtimes.
+ *
+ * This is a MERGE, not a from-scratch rebuild: only `filesAffected` and
+ * `order` are recomputed from the patch files, and every other field on an
+ * existing entry is carried forward untouched. Entries with no pre-existing
+ * metadata are recovered from filename structure, patch contents, and file
+ * mtimes.
+ *
+ * Refuses when patches.json exists but cannot be parsed, because that is the
+ * one case where nothing can be carried forward and the "merge" silently
+ * becomes a whole-manifest reinvention. Pass `allowMetadataLoss` to accept it.
+ *
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
- * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
- *   plus the filenames that were reconstructed from generic defaults.
+ * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
+ * @returns {@link RebuildPatchesManifestResult} — the rebuilt manifest, the
+ *   filenames that were reconstructed from generic defaults, and the rows
+ *   dropped because their patch file is gone.
  */
-export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion, lockOptions = {}) {
+export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion, options = {}) {
     // The whole read → discover → rebuild → save cycle runs under the shared
     // patch-directory lock (invariant 2, docs/lifecycle-invariants.md):
     // manifest writes serialize on this lock, so without it a repair racing a
     // concurrent export/reorder can clobber the other writer's manifest. Not
     // reentrant — callers must not already hold it.
-    return withPatchDirectoryLock(patchesDir, () => rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion), lockOptions);
+    //
+    // A dry run takes the lock too: it reads the same manifest and patch bodies
+    // a real run would, and a projection computed against a queue being
+    // rewritten underneath is worth less than no projection at all.
+    return withPatchDirectoryLock(patchesDir, () => rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion, options), options);
 }
-async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion) {
+async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion, options) {
     const manifestState = await loadPatchesManifestState(patchesDir);
     const existingEntries = new Map();
+    // An unparseable manifest yields `manifest: null`, which the merge below
+    // cannot distinguish from "no manifest at all" — every entry would be
+    // treated as new and every descriptive field reinvented. `filesAffected`
+    // is the only field a .patch body can yield; `stagedDependencies`,
+    // `lintIgnore`, `tier`, `description`, `category`, `createdAt` and the
+    // source version cannot be reconstructed from a diff at all. Refuse rather
+    // than write that, since the write is what makes it unrecoverable on a
+    // queue that is not under version control.
+    if (manifestState.exists && manifestState.parseError && options.allowMetadataLoss !== true) {
+        throw new GeneralError(`Refusing to rebuild ${PATCHES_MANIFEST}: it exists but could not be parsed ` +
+            `(${manifestState.parseError.message}). None of its metadata can be carried ` +
+            'forward, so every entry would be rebuilt with an invented description, an ' +
+            'mtime-based createdAt and an inferred category, and any stagedDependencies, ' +
+            'lintIgnore or tier declarations would be lost — a patch body carries none of ' +
+            'them.\n' +
+            `Fix the JSON in ${PATCHES_MANIFEST} (restore it from version control if you ` +
+            'can) and re-run, or pass --allow-metadata-loss to accept the reinvention.');
+    }
     if (manifestState.manifest) {
         for (const entry of manifestState.manifest.patches) {
             existingEntries.set(entry.filename, entry);
@@ -118,7 +171,7 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
     // sequential because `nextRecoveredOrder` is loop-carried: parallelising
     // the assignment would scramble the recovered ordinals.
     const prefetched = await Promise.all(patches.map(async (patch) => ({
-        filesAffected: normalizeFiles(await getAllTargetFilesFromPatch(patch.path)),
+        filesAffected: normalizeAffectedFiles(await getAllTargetFilesFromPatch(patch.path)),
         patchStats: await stat(patch.path),
     })));
     for (const [index, patch] of patches.entries()) {
@@ -140,15 +193,17 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
             // avoid.
             recoveredFilenames.push(patch.filename);
         }
-        // Preserve optional fields the operator declared on the existing entry —
-        // `lintIgnore` (per-patch lint suppression) and `tier` (explicit
-        // branding-threshold override). Without this, a
-        // `doctor --repair-patches-manifest` run silently strips both from every
-        // entry that had them, and the next `lint` or `re-export` pass fires
-        // rules the operator had intentionally quieted. Mirrors how other
-        // descriptive fields fall back to existing values when the entry is
-        // known.
+        // The rebuild OWNS exactly two fields — `filesAffected` (recomputed from
+        // the patch body) and `order` (from the filename ordinal). Everything
+        // else on an existing entry is carried forward by the spread, so a field
+        // a .patch cannot express — `stagedDependencies`, `lintIgnore`, `tier`,
+        // and whatever is added to PatchMetadata next — survives a repair by
+        // construction rather than by someone remembering to list it here. It was
+        // an enumerated literal until `stagedDependencies` was dropped from every
+        // entry that had one, which is the failure this shape prevents from
+        // recurring.
         const rebuilt = {
+            ...(existing ?? {}),
             filename: patch.filename,
             order: recoveredOrder,
             category: existing?.category ?? inferred.category,
@@ -158,24 +213,42 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
             createdAt: existing?.createdAt ?? new Date(patchStats.mtimeMs).toISOString(),
             sourceEsrVersion: existing?.sourceEsrVersion ?? fallbackSourceEsrVersion,
             sourceVersion: existing?.sourceVersion ?? existing?.sourceEsrVersion ?? fallbackSourceEsrVersion,
-            ...(existing?.sourceProduct !== undefined ? { sourceProduct: existing.sourceProduct } : {}),
             filesAffected,
         };
+        // Copy the arrays rather than aliasing the loaded manifest's, so a caller
+        // mutating the rebuilt entry cannot reach back into `manifestState`.
         if (existing?.lintIgnore !== undefined)
             rebuilt.lintIgnore = [...existing.lintIgnore];
-        if (existing?.tier !== undefined)
-            rebuilt.tier = existing.tier;
         rebuiltPatches.push(rebuilt);
+        existingEntries.delete(patch.filename);
     }
     rebuiltPatches.sort((left, right) => left.order - right.order || left.filename.localeCompare(right.filename));
     const rebuiltManifest = {
         version: 1,
         patches: rebuiltPatches,
     };
+    // Whatever is left in the map had a manifest row but no patch file, so the
+    // rebuild drops it. That is the correct outcome — the file is the source of
+    // truth — but dropping rows without naming them is indistinguishable from
+    // never having had them.
+    const droppedFilenames = [...existingEntries.keys()].sort((left, right) => left.localeCompare(right));
+    if (options.dryRun === true) {
+        return {
+            manifest: rebuiltManifest,
+            recoveredFilenames,
+            droppedFilenames,
+            written: false,
+        };
+    }
     await savePatchesManifest(patchesDir, rebuiltManifest);
-    return { manifest: rebuiltManifest, recoveredFilenames };
+    return { manifest: rebuiltManifest, recoveredFilenames, droppedFilenames, written: true };
 }
-function normalizeFiles(files) {
+/**
+ * Canonical form of a `filesAffected` list: deduplicated and sorted, so a
+ * comparison between a declared list and one extracted from a patch body is
+ * about membership rather than ordering.
+ */
+export function normalizeAffectedFiles(files) {
     return Array.from(new Set(files)).sort((left, right) => left.localeCompare(right));
 }
 function sameStringArray(left, right) {

package/dist/src/core/patch-manifest-files-affected.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Narrow repair for `filesAffected` — the one manifest field a `.patch` body
+ * can actually yield.
+ *
+ * A `files-affected-mismatch` is pure derived-value drift: the manifest's list
+ * disagrees with the diff it describes, and the diff is right by definition.
+ * Rebuilding the whole manifest to fix it is a much larger operation than the
+ * failure calls for, so this repair recomputes one field on the drifted rows
+ * and leaves every other row byte-identical.
+ */
+import type { PatchDirectoryLockOptions } from './patch-lock.js';
+/** One row whose `filesAffected` list disagreed with its patch body. */
+export interface FilesAffectedRepair {
+    /** Patch filename. */
+    filename: string;
+    /** The list the manifest declared, normalized for comparison. */
+    before: string[];
+    /** The list the patch body actually targets. */
+    after: string[];
+}
+/** Summary of a {@link repairPatchesFilesAffected} run. */
+export interface RepairFilesAffectedResult {
+    /** Rows that drifted and were (or would be) corrected. */
+    repairs: FilesAffectedRepair[];
+    /** Requested filenames with no manifest row, or no patch file on disk. */
+    skippedFilenames: string[];
+    /** False when the run was a dry run and patches.json was left untouched. */
+    written: boolean;
+}
+/** Options for {@link repairPatchesFilesAffected}. */
+export interface RepairFilesAffectedOptions extends PatchDirectoryLockOptions {
+    /** Compute the corrections without writing them. */
+    dryRun?: boolean;
+}
+/**
+ * Recomputes `filesAffected` from the patch body for the named patches.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filenames - Patch filenames to repair
+ * @param options - Lock options plus `dryRun`
+ * @returns The corrections applied (or projected) and the filenames skipped
+ */
+export declare function repairPatchesFilesAffected(patchesDir: string, filenames: readonly string[], options?: RepairFilesAffectedOptions): Promise<RepairFilesAffectedResult>;