@hominis/fireforge 0.44.0 → 0.44.2

package/dist/src/core/mach.d.ts

@@ -25,6 +25,11 @@ export interface MachOptions {
      * the test dispatchers only.
      */
     annotateKnownTeardownNoise?: boolean;
+    /**
+     * Environment variables to unset for this dispatch. Threaded to the exec
+     * layer's {@link ExecOptions.envUnset}.
+     */
+    envUnset?: readonly string[];
 }
 /**
  * Result of running a mach command while capturing streamed output.
@@ -243,7 +248,7 @@ export declare function test(engineDir: string, testPaths?: string[], args?: str
  *   (merged over `process.env` by the exec layer). Used by
  *   `fireforge test --perf-samples` to publish the artifact-path contract.
  */
-export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;
 /**
  * Runs `mach xpcshell-test` (the suite-specific xpcshell command) while
  * capturing output. Unlike the generic `mach test`, the suite-specific
@@ -254,10 +259,10 @@ export declare function testWithOutput(engineDir: string, testPaths?: string[],
  * Signature mirrors {@link testWithOutput} so the two are interchangeable in
  * the dispatch path.
  */
-export declare function xpcshellTestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+export declare function xpcshellTestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;
 /**
  * Runs `mach mochitest` (covers browser-chrome / mochitest flavors) while
  * capturing output. The suite-specific counterpart to {@link testWithOutput}
  * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
  */
-export declare function mochitestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+export declare function mochitestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;

package/dist/src/core/mach.js

@@ -10,6 +10,7 @@ import { explainMachError } from './mach-error-hints.js';
 import { createKnownTeardownNoiseFilter, createTeardownNoiseContext, } from './mach-known-noise-filter.js';
 import { getPython } from './mach-python.js';
 import { installMachResourceGuard } from './mach-resource-shim.js';
+import { teeToRunLog, writeToActiveRunLog } from './run-log.js';
 import { detectHarnessCrashSignature } from './test-harness-crash.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
 // This block is a frozen compatibility list, not a barrel to grow: every name
@@ -90,6 +91,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
     const exitCode = await execStream(python, [machPath, ...args], {
         cwd: engineDir,
         ...(options.env ? { env: options.env } : {}),
+        ...(options.envUnset ? { envUnset: options.envUnset } : {}),
         // Every capture dispatch (test suites, protected builds, package,
         // storybook) runs as a process-group leader and is group-reaped on
         // exit/abort — see ExecOptions.processGroup.
@@ -99,6 +101,12 @@ export async function runMachCapture(args, engineDir, options = {}) {
             if (stdout.length > CAPTURE_TAIL_LIMIT) {
                 stdout = stdout.slice(-CAPTURE_TAIL_LIMIT);
             }
+            // RAW into the log, filtered into the echo. The log exists to be
+            // re-read after the fact by whoever is diagnosing the run, and the
+            // echo filter's whole purpose is to shorten what a HUMAN scrolls
+            // past — collapsing a traceback in the artifact would reintroduce
+            // the loss this log exists to prevent.
+            writeToActiveRunLog(data);
             process.stdout.write(stdoutFilter ? stdoutFilter.transform(data) : data);
         },
         onStderr: (data) => {
@@ -106,6 +114,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
             if (stderr.length > CAPTURE_TAIL_LIMIT) {
                 stderr = stderr.slice(-CAPTURE_TAIL_LIMIT);
             }
+            writeToActiveRunLog(data);
             process.stderr.write(stderrFilter ? stderrFilter.transform(data) : data);
         },
     });
@@ -133,6 +142,10 @@ export async function runMachInheritCapture(args, engineDir, options = {}) {
     return execInheritCapture(python, [machPath, ...args], {
         cwd: engineDir,
         ...(options.env ? { env: options.env } : {}),
+        ...(options.envUnset ? { envUnset: options.envUnset } : {}),
+        // This path streams through the collectors' mirror rather than per-chunk
+        // callbacks, so the run-log tee rides the mirror. `mach build` is here.
+        mirror: { stdout: teeToRunLog(process.stdout), stderr: teeToRunLog(process.stderr) },
         processGroup: true,
     });
 }
@@ -378,6 +391,31 @@ export async function watchWithOutput(engineDir, options = {}) {
 export async function test(engineDir, testPaths = [], args = []) {
     return runMach(['test', ...testPaths, ...args], engineDir, { inherit: true });
 }
+/**
+ * Environment markers mozbuild reads to decide it is running under a coding
+ * agent (`mozbuild.util.is_running_under_coding_agent`), which quiets
+ * terminal output to warnings and errors.
+ *
+ * The quieting is genuinely useful for BUILDS — that is most of what an
+ * agent session prints — but it applies to test runs too, where it removes
+ * `TEST_START` and console INFO: exactly the lines a hang or stall
+ * diagnosis needs, and the ones FireForge's own classifier reads
+ * (`Ran N checks`, `Unexpected results:`, `TEST-UNEXPECTED-*`). Unsetting
+ * the variable globally would give up the build half as well, so the
+ * dispatchers below unset it per TEST dispatch and leave the build path
+ * alone.
+ */
+const CODING_AGENT_ENV_MARKERS = ['CLAUDECODE'];
+/**
+ * The `envUnset` list for a test dispatch: the coding-agent markers when
+ * full verbosity was requested, nothing otherwise.
+ *
+ * Opt-in rather than unconditional: this changes how much a third party
+ * prints, and an operator who wants mozbuild's quieting should keep it.
+ */
+function testVerbosityEnvUnset(fullOutput) {
+    return fullOutput === true ? CODING_AGENT_ENV_MARKERS : undefined;
+}
 /**
  * Runs mach test while capturing streamed output for better diagnostics.
  *
@@ -388,10 +426,12 @@ export async function test(engineDir, testPaths = [], args = []) {
  *   (merged over `process.env` by the exec layer). Used by
  *   `fireforge test --perf-samples` to publish the artifact-path contract.
  */
-export async function testWithOutput(engineDir, testPaths = [], args = [], env) {
+export async function testWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
     const guard = await installMachResourceGuard(engineDir);
+    const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture(['test', ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
+        ...(envUnset ? { envUnset } : {}),
         annotateKnownTeardownNoise: true,
     });
 }
@@ -405,10 +445,12 @@ export async function testWithOutput(engineDir, testPaths = [], args = [], env)
  * Signature mirrors {@link testWithOutput} so the two are interchangeable in
  * the dispatch path.
  */
-export async function xpcshellTestWithOutput(engineDir, testPaths = [], args = [], env) {
+export async function xpcshellTestWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
     const guard = await installMachResourceGuard(engineDir);
+    const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture(['xpcshell-test', ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
+        ...(envUnset ? { envUnset } : {}),
         annotateKnownTeardownNoise: true,
     });
 }
@@ -417,10 +459,12 @@ export async function xpcshellTestWithOutput(engineDir, testPaths = [], args = [
  * capturing output. The suite-specific counterpart to {@link testWithOutput}
  * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
  */
-export async function mochitestWithOutput(engineDir, testPaths = [], args = [], env) {
+export async function mochitestWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
     const guard = await installMachResourceGuard(engineDir);
+    const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture(['mochitest', ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
+        ...(envUnset ? { envUnset } : {}),
         annotateKnownTeardownNoise: true,
     });
 }

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>;

package/dist/src/core/patch-manifest-files-affected.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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 { GeneralError } from '../errors/base.js';
+import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
+import { withPatchDirectoryLock } from './patch-lock.js';
+import { normalizeAffectedFiles } from './patch-manifest-consistency.js';
+import { loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, } from './patch-manifest-io.js';
+/**
+ * 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 async function repairPatchesFilesAffected(patchesDir, filenames, options = {}) {
+    // Same lock contract as the full rebuild (invariant 2,
+    // docs/lifecycle-invariants.md): a manifest write serializes on the
+    // patch-directory lock, and a dry run reads under it so its projection
+    // cannot be computed against a queue being rewritten underneath.
+    return withPatchDirectoryLock(patchesDir, () => repairPatchesFilesAffectedUnderLock(patchesDir, filenames, options), options);
+}
+async function repairPatchesFilesAffectedUnderLock(patchesDir, filenames, options) {
+    // ForWrite: a corrupt manifest must abort here rather than be treated as
+    // empty. This repair exists precisely so that a one-field drift never
+    // reaches a whole-manifest rewrite, and silently writing over unparseable
+    // metadata would be a larger version of what it avoids.
+    const manifest = await loadPatchesManifestForWrite(patchesDir);
+    if (!manifest) {
+        throw new GeneralError(`Cannot repair filesAffected: ${PATCHES_MANIFEST} does not exist in ${patchesDir}.`);
+    }
+    const patchPathByFilename = new Map((await discoverPatches(patchesDir)).map((patch) => [patch.filename, patch.path]));
+    const rowByFilename = new Map(manifest.patches.map((entry) => [entry.filename, entry]));
+    const repairs = [];
+    const skippedFilenames = [];
+    for (const filename of new Set(filenames)) {
+        const patchPath = patchPathByFilename.get(filename);
+        const row = rowByFilename.get(filename);
+        if (patchPath === undefined || !row) {
+            // A missing patch file or a missing row is a different consistency
+            // issue with a different remedy; this repair reports it rather than
+            // inventing a row or deleting one.
+            skippedFilenames.push(filename);
+            continue;
+        }
+        const before = normalizeAffectedFiles(row.filesAffected);
+        const after = normalizeAffectedFiles(await getAllTargetFilesFromPatch(patchPath));
+        if (sameFiles(before, after))
+            continue;
+        repairs.push({ filename, before, after });
+    }
+    skippedFilenames.sort((left, right) => left.localeCompare(right));
+    if (repairs.length === 0 || options.dryRun === true) {
+        return { repairs, skippedFilenames, written: false };
+    }
+    const correctedByFilename = new Map(repairs.map((repair) => [repair.filename, repair.after]));
+    // Row-scoped mutation, so every untouched entry keeps its exact JSON shape —
+    // no re-sorted `filesAffected` lists and no reader-only fallback fields
+    // serialized into rows this repair has no business touching.
+    await mutatePatchRowsInManifest(patchesDir, [...correctedByFilename.keys()], (existing) => {
+        const corrected = correctedByFilename.get(existing.filename);
+        return corrected ? { set: { filesAffected: corrected } } : null;
+    });
+    return { repairs, skippedFilenames, written: true };
+}
+function sameFiles(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

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

@@ -4,7 +4,8 @@
  * Callers should continue to import from this module; the internal split
  * is an implementation detail.
  */
-export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { type PatchManifestConsistencyIssue, rebuildPatchesManifest, recommendManifestRepair, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { type FilesAffectedRepair, repairPatchesFilesAffected, } from './patch-manifest-files-affected.js';
 export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';

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

@@ -5,7 +5,8 @@
  * Callers should continue to import from this module; the internal split
  * is an implementation detail.
  */
-export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { rebuildPatchesManifest, recommendManifestRepair, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { repairPatchesFilesAffected, } from './patch-manifest-files-affected.js';
 export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';