@hominis/fireforge 0.34.2 → 0.36.0

package/dist/src/core/patch-artifact-normalize.d.ts

@@ -1,10 +1,23 @@
 /**
  * Normalizes generated patch files before they are written to disk.
  *
- * Kept as a narrow chokepoint for future artifact-level fixes. It must keep
- * unified-diff hunk markers intact, but marker-only blank payload lines should
- * not carry extra trailing whitespace (`"+ "` / `"- "` / `"  "`), because raw
- * repository whitespace checks flag those generated patch artifact lines even
- * when the engine diff is clean.
+ * Currently the identity function, kept as a narrow chokepoint for future
+ * artifact-level fixes so every export path (`commitExportedPatch`,
+ * `commitPlacementExport`, `updatePatch`, `patch split`) funnels through
+ * one place.
+ *
+ * History: this used to strip marker lines whose payload was pure
+ * whitespace (`/^[ +-]\s+$/` → bare marker) to appease repository
+ * trailing-whitespace checks. That corrupted real content — Firefox
+ * sources contain whitespace-only lines, so a ` `/`-` line whose payload
+ * was e.g. two spaces no longer matched the pristine tree (the freshly
+ * exported patch failed `git apply --check`), and a `+` line silently
+ * changed what the patch produces, making re-import diverge from the
+ * engine state it was exported from (2026-07-05 review, finding M2).
+ * The whitespace check itself excludes `patches/*.patch`
+ * (scripts/check-worktree-whitespace.mjs), so the trimming had no
+ * remaining justification. Patch bodies are now written byte-for-byte as
+ * git produced them — including the single-space rendering of blank
+ * context lines, which `re-export.integration.test.ts` pins.
  */
 export declare function normalizePatchArtifact(content: string): string;

package/dist/src/core/patch-artifact-normalize.js

@@ -2,21 +2,25 @@
 /**
  * Normalizes generated patch files before they are written to disk.
  *
- * Kept as a narrow chokepoint for future artifact-level fixes. It must keep
- * unified-diff hunk markers intact, but marker-only blank payload lines should
- * not carry extra trailing whitespace (`"+ "` / `"- "` / `"  "`), because raw
- * repository whitespace checks flag those generated patch artifact lines even
- * when the engine diff is clean.
+ * Currently the identity function, kept as a narrow chokepoint for future
+ * artifact-level fixes so every export path (`commitExportedPatch`,
+ * `commitPlacementExport`, `updatePatch`, `patch split`) funnels through
+ * one place.
+ *
+ * History: this used to strip marker lines whose payload was pure
+ * whitespace (`/^[ +-]\s+$/` → bare marker) to appease repository
+ * trailing-whitespace checks. That corrupted real content — Firefox
+ * sources contain whitespace-only lines, so a ` `/`-` line whose payload
+ * was e.g. two spaces no longer matched the pristine tree (the freshly
+ * exported patch failed `git apply --check`), and a `+` line silently
+ * changed what the patch produces, making re-import diverge from the
+ * engine state it was exported from (2026-07-05 review, finding M2).
+ * The whitespace check itself excludes `patches/*.patch`
+ * (scripts/check-worktree-whitespace.mjs), so the trimming had no
+ * remaining justification. Patch bodies are now written byte-for-byte as
+ * git produced them — including the single-space rendering of blank
+ * context lines, which `re-export.integration.test.ts` pins.
  */
 export function normalizePatchArtifact(content) {
-    return content
-        .split('\n')
-        .map((line) => {
-        if (/^[ +-]\s+$/.test(line)) {
-            return line[0] ?? line;
-        }
-        return line;
-    })
-        .join('\n');
+    return content;
 }
-//# sourceMappingURL=patch-artifact-normalize.js.map

package/dist/src/core/patch-export-coverage.js

@@ -100,4 +100,3 @@ export async function findAllPatchesForFilesWithDetails(patchesDir, targetFiles,
     }
     return results;
 }
-//# sourceMappingURL=patch-export-coverage.js.map

package/dist/src/core/patch-export-metadata.js

@@ -36,4 +36,3 @@ export async function mutatePatchMetadata(patchesDir, filename, mutator) {
         return { before: changed.before, after: changed.after };
     });
 }
-//# sourceMappingURL=patch-export-metadata.js.map

package/dist/src/core/patch-export-update.js

@@ -5,7 +5,7 @@ import { pathExists, readText, writeText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { withPatchDirectoryLock } from './patch-apply.js';
 import { normalizePatchArtifact } from './patch-artifact-normalize.js';
-import { loadPatchesManifest, mutatePatchRowsInManifest } from './patch-manifest.js';
+import { loadPatchesManifestForWrite, mutatePatchRowsInManifest } from './patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
 /**
  * Updates a patch file body and its manifest row under the same patch
@@ -14,7 +14,7 @@ import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
  */
 export async function updatePatchAndMetadata(patchesDir, filename, newContent, updates, onCommitted, policyGate) {
     await withPatchDirectoryLock(patchesDir, async () => {
-        const manifest = await loadPatchesManifest(patchesDir);
+        const manifest = await loadPatchesManifestForWrite(patchesDir);
         if (!manifest) {
             throw new Error('Cannot update patch metadata: patches.json is missing.');
         }
@@ -65,4 +65,3 @@ export async function updatePatchAndMetadata(patchesDir, filename, newContent, u
         }
     });
 }
-//# sourceMappingURL=patch-export-update.js.map

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

@@ -30,6 +30,8 @@ export declare function sanitizeName(name: string): string;
  * double-prefix incident) also collapses. Exported for direct testing.
  */
 export declare function stripRedundantCategoryPrefix(sanitizedName: string, category: string): string;
+/** Sanitizes a patch name and drops redundant category/full-stem prefixes. */
+export declare function patchNameSlug(name: string, category: string): string;
 /**
  * Generates the next patch filename with category.
  * @param patchesDir - Path to the patches directory
@@ -99,12 +101,6 @@ export declare function findExistingPatchForFile(patchesDir: string, filePath: s
  * @param newContent - New patch content
  */
 export declare function updatePatch(patchPath: string, newContent: string): Promise<void>;
-/**
- * Deletes a patch file and removes it from the manifest.
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename to delete
- */
-export declare function deletePatch(patchesDir: string, filename: string): Promise<void>;
 /**
  * Fully computed plan for a pending export. Returned from
  * {@link planExport} so that `--dry-run` previews can render the full

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

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
@@ -8,7 +7,7 @@ import { PATCH_CATEGORIES } from '../utils/validation.js';
 import { discoverPatches, withPatchDirectoryLock } from './patch-apply.js';
 import { normalizePatchArtifact } from './patch-artifact-normalize.js';
 import { findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
-import { addPatchToManifest, loadPatchesManifest, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
+import { addPatchToManifest, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
 import { allocatePolicyOrder, enforcePatchPolicy } from './patch-policy.js';
 export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, } from './patch-export-coverage.js';
 export { mutatePatchMetadata, updatePatchMetadata, } from './patch-export-metadata.js';
@@ -46,6 +45,9 @@ export function sanitizeName(name) {
         .replace(/^-+|-+$/g, '')
         .slice(0, 50);
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
  * Operators frequently pass the DESIRED FILENAME stem to `--name`
@@ -56,15 +58,25 @@ export function sanitizeName(name) {
  * double-prefix incident) also collapses. Exported for direct testing.
  */
 export function stripRedundantCategoryPrefix(sanitizedName, category) {
-    const prefix = new RegExp(`^\\d+-${category}-`);
+    const prefixes = [
+        new RegExp(`^\\d+-${escapeRegExp(category)}-`),
+        new RegExp(`^${escapeRegExp(category)}-`),
+    ];
     let stripped = sanitizedName;
-    while (prefix.test(stripped)) {
-        stripped = stripped.replace(prefix, '');
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const prefix of prefixes) {
+            if (prefix.test(stripped)) {
+                stripped = stripped.replace(prefix, '');
+                changed = true;
+            }
+        }
     }
     return stripped.length > 0 ? stripped : sanitizedName;
 }
-/** Sanitizes a patch name and drops a redundant `NNN-<category>-` prefix. */
-function patchNameSlug(name, category) {
+/** Sanitizes a patch name and drops redundant category/full-stem prefixes. */
+export function patchNameSlug(name, category) {
     return stripRedundantCategoryPrefix(sanitizeName(name), category);
 }
 /**
@@ -221,45 +233,6 @@ export async function findExistingPatchForFile(patchesDir, filePath) {
 export async function updatePatch(patchPath, newContent) {
     await writeText(patchPath, normalizePatchArtifact(newContent));
 }
-/**
- * Deletes a patch file and removes it from the manifest.
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename to delete
- */
-export async function deletePatch(patchesDir, filename) {
-    await withPatchDirectoryLock(patchesDir, async () => {
-        const patchPath = join(patchesDir, filename);
-        const manifest = await loadPatchesManifest(patchesDir);
-        const updatedManifest = manifest
-            ? {
-                ...manifest,
-                patches: manifest.patches.filter((patch) => patch.filename !== filename),
-            }
-            : null;
-        // Update manifest first so interrupted deletions leave an explicit repairable
-        // extra patch file rather than silently dropping metadata for an absent file.
-        if (updatedManifest) {
-            await savePatchesManifest(patchesDir, updatedManifest);
-        }
-        if (!(await pathExists(patchPath))) {
-            return;
-        }
-        try {
-            await unlink(patchPath);
-        }
-        catch (error) {
-            if (manifest) {
-                try {
-                    await savePatchesManifest(patchesDir, manifest);
-                }
-                catch (error) {
-                    warn(`Failed to restore manifest after patch deletion error for "${filename}": ${toError(error).message}`);
-                }
-            }
-            throw error;
-        }
-    });
-}
 /**
  * Internal planning helper. Does NOT take the patch directory lock — the
  * caller must already hold it — because the two public entry points
@@ -269,7 +242,11 @@ export async function deletePatch(patchesDir, filename) {
  * instead of by parallel implementations that can drift.
  */
 async function computeExportPlanUnderLock(input) {
-    const manifestBefore = await loadPatchesManifest(input.patchesDir);
+    // ForWrite: a corrupt manifest read as null here would produce a
+    // manifestAfter containing ONLY the new patch — committing that plan
+    // wipes the queue metadata, and the rollback path would then delete
+    // patches.json entirely because manifestBefore looked absent.
+    const manifestBefore = await loadPatchesManifestForWrite(input.patchesDir);
     const policyOrder = input.config !== undefined
         ? allocatePolicyOrder(input.config, manifestBefore?.patches ?? [], input.category)
         : null;
@@ -341,4 +318,3 @@ export async function planExport(input) {
         };
     });
 }
-//# sourceMappingURL=patch-export.js.map

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

@@ -51,4 +51,3 @@ export async function getAllTargetFilesFromPatch(patchPath) {
     const content = await readText(patchPath);
     return extractAffectedFiles(content);
 }
-//# sourceMappingURL=patch-files.js.map

package/dist/src/core/patch-identifier-suggest.js

@@ -105,4 +105,3 @@ export function formatPatchNotFoundError(identifier, patches) {
     }
     return `${lead} No close match found among ${patches.length} patches in the queue. Run "fireforge patch list" to see them.`;
 }
-//# sourceMappingURL=patch-identifier-suggest.js.map

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

@@ -414,4 +414,3 @@ export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, pa
         : { strict };
     return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode);
 }
-//# sourceMappingURL=patch-lint-checkjs.js.map

package/dist/src/core/patch-lint-chrome-jsdoc.js

@@ -84,4 +84,3 @@ export function lintChromeScriptJsDocForFile(file, content, isChromeOwned, mode)
         severity: issue.severity ?? mode,
     }));
 }
-//# sourceMappingURL=patch-lint-chrome-jsdoc.js.map

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

@@ -495,4 +495,3 @@ export function lintPatchQueueForwardImports(ctx) {
 export function lintPatchQueue(ctx) {
     return [...lintPatchQueueDuplicateCreations(ctx), ...lintPatchQueueForwardImports(ctx)];
 }
-//# sourceMappingURL=patch-lint-cross.js.map

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

@@ -169,4 +169,3 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint-css.js.map

package/dist/src/core/patch-lint-diff-tag.js

@@ -105,4 +105,3 @@ export function tagLintIssues(issues, diffFiles) {
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint-diff-tag.js.map

package/dist/src/core/patch-lint-diff.d.ts

@@ -6,7 +6,8 @@
  * cross-patch lint body (in `patch-lint-cross.ts`) can both depend on
  * the same diff walkers without inducing a circular import. Callers
  * should keep importing these through `patch-lint.ts` — this file is
- * an implementation detail.
+ * an implementation detail. The actual line-walking lives in
+ * `parseDiffSections` (patch-parse.ts), the codebase's single diff walker.
  */
 /**
  * Extracts new-file paths from a unified diff by scanning for `new file mode` markers.

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

@@ -7,23 +7,18 @@
  * cross-patch lint body (in `patch-lint-cross.ts`) can both depend on
  * the same diff walkers without inducing a circular import. Callers
  * should keep importing these through `patch-lint.ts` — this file is
- * an implementation detail.
+ * an implementation detail. The actual line-walking lives in
+ * `parseDiffSections` (patch-parse.ts), the codebase's single diff walker.
  */
+import { parseDiffSections } from './patch-parse.js';
 /**
  * Extracts new-file paths from a unified diff by scanning for `new file mode` markers.
  */
 export function detectNewFilesInDiff(diffContent) {
     const newFiles = new Set();
-    const lines = diffContent.split('\n');
-    let currentFile = null;
-    for (const line of lines) {
-        if (line.startsWith('diff --git')) {
-            const match = /^diff --git a\/.+ b\/(.+)$/.exec(line);
-            currentFile = match?.[1] ?? null;
-            continue;
-        }
-        if (line.startsWith('new file mode') && currentFile) {
-            newFiles.add(currentFile);
+    for (const section of parseDiffSections(diffContent)) {
+        if (section.isNewFile) {
+            newFiles.add(section.targetPath);
         }
     }
     return newFiles;
@@ -34,27 +29,18 @@ export function detectNewFilesInDiff(diffContent) {
  */
 export function extractAddedLinesPerFile(diffContent) {
     const result = new Map();
-    const lines = diffContent.split('\n');
-    let currentFile = null;
-    let inHunk = false;
-    for (const line of lines) {
-        if (line.startsWith('diff --git')) {
-            const match = /^diff --git a\/.+ b\/(.+)$/.exec(line);
-            currentFile = match?.[1] ?? null;
-            inHunk = false;
-            continue;
-        }
-        if (line.startsWith('@@')) {
-            inHunk = true;
-            continue;
-        }
-        if (inHunk && currentFile && line.startsWith('+') && !line.startsWith('+++')) {
-            let arr = result.get(currentFile);
-            if (!arr) {
-                arr = [];
-                result.set(currentFile, arr);
+    for (const section of parseDiffSections(diffContent)) {
+        for (const hunk of section.hunks) {
+            for (const line of hunk.lines) {
+                if (!line.startsWith('+'))
+                    continue;
+                let arr = result.get(section.targetPath);
+                if (!arr) {
+                    arr = [];
+                    result.set(section.targetPath, arr);
+                }
+                arr.push(line.slice(1));
             }
-            arr.push(line.slice(1));
         }
     }
     return result;
@@ -81,4 +67,3 @@ export function buildModifiedFileAdditionsFromDiff(diff) {
     }
     return result;
 }
-//# sourceMappingURL=patch-lint-diff.js.map

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

@@ -65,4 +65,3 @@ export function hasRelativeImport(content) {
     }
     return RELATIVE_IMPORT_FALLBACK_PATTERN.test(stripJsComments(content));
 }
-//# sourceMappingURL=patch-lint-imports.js.map

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

@@ -450,4 +450,3 @@ export function validateExportJsDoc(source, options) {
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint-jsdoc.js.map

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

@@ -165,4 +165,3 @@ export function lintObserverTopics(strippedContent, file, binaryName) {
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint-observer.js.map

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

@@ -67,4 +67,3 @@ export function resolvePatchOwnedSysMjs(currentNewFiles, patchQueueCtx) {
 export function resolvePatchOwnedChromeScripts(currentNewFiles, patchQueueCtx) {
     return resolveOwned(currentNewFiles, patchQueueCtx, (file) => file.endsWith('.js') && !file.endsWith('.sys.mjs'));
 }
-//# sourceMappingURL=patch-lint-ownership.js.map

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

@@ -5,4 +5,3 @@
  */
 export { buildPatchQueueContext, collectForwardImportEdges, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
-//# sourceMappingURL=patch-lint-reexports.js.map

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

@@ -1,5 +1,5 @@
 import type { PatchLintIssue } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
+import type { FireForgeConfig, ProjectLicense } from '../types/config.js';
 import { type CommentStyle } from './license-headers.js';
 import { lintPatchedCss } from './patch-lint-css.js';
 export * from './patch-lint-reexports.js';
@@ -26,7 +26,42 @@ export declare function isTestFile(file: string): boolean;
  */
 export declare function commentStyleForFile(file: string): CommentStyle | null;
 /**
- * Checks new files for required license headers.
+ * Decides whether a NEW file's leading header satisfies the
+ * `missing-license-header` rule. Single owner of the acceptance policy —
+ * `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
+ * interactive export fixer) must agree, or the fixer offers to stack a
+ * second header onto a file the lint already accepts.
+ *
+ * Accepted shapes, in order:
+ *  - the project's own header for the file's comment style;
+ *  - under `browser/branding/`, ANY recognised license header in the
+ *    matching style: the setup-generated branding directory is copied
+ *    from Firefox's `unofficial` template and arrives with Mozilla
+ *    MPL-2.0 headers — legitimate for copyright purposes (the assets are
+ *    Mozilla's) even when the fork's own code is 0BSD / EUPL-1.2 /
+ *    GPL-2.0-or-later;
+ *  - on an MPL-2.0 project, any recognised header in the matching style;
+ *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
+ *    behind a leading editor-directive comment) REGARDLESS of the
+ *    project license, on any file whose comment syntax is the block form
+ *    (JS and CSS): a file copied from the Firefox tree legitimately
+ *    keeps Mozilla's header for provenance in an EUPL/GPL/0BSD project
+ *    too. 0.35.0 accepted this on JS only; field verification showed a
+ *    derived CSS file carrying the identical three-line block header
+ *    still needed a patch-level lintIgnore. Only the block form is
+ *    accepted — the `// `-style MPL header is FireForge-generated, not
+ *    upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    because `/* … *\/` is not a comment there.
+ *
+ * @param file - Engine-relative path of the new file
+ * @param content - File content
+ * @param style - Comment style resolved for the file
+ * @param license - The project license
+ */
+export declare function isAcceptableNewFileHeader(file: string, content: string, style: CommentStyle, license: ProjectLicense): boolean;
+/**
+ * Checks new files for required license headers (acceptance policy in
+ * {@link isAcceptableNewFileHeader}).
  *
  * @param repoDir - Absolute path to the engine directory
  * @param newFiles - New file paths (relative to repoDir)

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

@@ -2,7 +2,7 @@
 import { dirname, join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { stripJsComments } from '../utils/regex.js';
-import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, } from './license-headers.js';
+import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, hasUpstreamMplBlockHeader, } from './license-headers.js';
 import { invokePatchLintCheckJs } from './patch-lint-checkjs.js';
 import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
 import { lintPatchedCss } from './patch-lint-css.js';
@@ -211,7 +211,52 @@ export function commentStyleForFile(file) {
 // License header lint
 // ---------------------------------------------------------------------------
 /**
- * Checks new files for required license headers.
+ * Decides whether a NEW file's leading header satisfies the
+ * `missing-license-header` rule. Single owner of the acceptance policy —
+ * `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
+ * interactive export fixer) must agree, or the fixer offers to stack a
+ * second header onto a file the lint already accepts.
+ *
+ * Accepted shapes, in order:
+ *  - the project's own header for the file's comment style;
+ *  - under `browser/branding/`, ANY recognised license header in the
+ *    matching style: the setup-generated branding directory is copied
+ *    from Firefox's `unofficial` template and arrives with Mozilla
+ *    MPL-2.0 headers — legitimate for copyright purposes (the assets are
+ *    Mozilla's) even when the fork's own code is 0BSD / EUPL-1.2 /
+ *    GPL-2.0-or-later;
+ *  - on an MPL-2.0 project, any recognised header in the matching style;
+ *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
+ *    behind a leading editor-directive comment) REGARDLESS of the
+ *    project license, on any file whose comment syntax is the block form
+ *    (JS and CSS): a file copied from the Firefox tree legitimately
+ *    keeps Mozilla's header for provenance in an EUPL/GPL/0BSD project
+ *    too. 0.35.0 accepted this on JS only; field verification showed a
+ *    derived CSS file carrying the identical three-line block header
+ *    still needed a patch-level lintIgnore. Only the block form is
+ *    accepted — the `// `-style MPL header is FireForge-generated, not
+ *    upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    because `/* … *\/` is not a comment there.
+ *
+ * @param file - Engine-relative path of the new file
+ * @param content - File content
+ * @param style - Comment style resolved for the file
+ * @param license - The project license
+ */
+export function isAcceptableNewFileHeader(file, content, style, license) {
+    if (content.startsWith(getLicenseHeader(license, style)))
+        return true;
+    if (file.startsWith('browser/branding/') && hasAnyLicenseHeader(content, style))
+        return true;
+    if (license === 'MPL-2.0' && hasAnyLicenseHeader(content, style))
+        return true;
+    if ((style === 'js' || style === 'css') && hasUpstreamMplBlockHeader(content))
+        return true;
+    return false;
+}
+/**
+ * Checks new files for required license headers (acceptance policy in
+ * {@link isAcceptableNewFileHeader}).
  *
  * @param repoDir - Absolute path to the engine directory
  * @param newFiles - New file paths (relative to repoDir)
@@ -229,27 +274,7 @@ export async function lintNewFileHeaders(repoDir, newFiles, config) {
         if (!(await pathExists(filePath)))
             continue;
         const content = await readText(filePath);
-        const expectedHeader = getLicenseHeader(license, style);
-        // Auto-exempt `browser/branding/` when the file carries ANY recognised
-        // license header in the matching comment style. The setup-generated
-        // branding directory is copied from Firefox's `unofficial` template,
-        // which arrives with Mozilla MPL-2.0 headers — those are legitimate
-        // for copyright purposes (the assets are Mozilla's) even when the
-        // fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later. The narrower
-        // license-match rule would force operators to either rewrite the
-        // copied headers (misrepresenting authorship) or suppress the lint
-        // with `--skip-lint` (hiding real issues elsewhere).
-        if (content.startsWith(expectedHeader))
-            continue;
-        if (file.startsWith('browser/branding/') && hasAnyLicenseHeader(content, style))
-            continue;
-        // Accept the MPL-2.0 block-comment form (`/* ... */` with leading `*`)
-        // for any JS file — that is the canonical upstream Firefox header
-        // shape, and `hasAnyLicenseHeader` above also recognises it. The
-        // explicit guard mirrors the branding carve-out so operators using the
-        // standard Mozilla header on a JS file (e.g. one copied from upstream
-        // browser/base/content) do not need `--skip-lint` to land it.
-        if (license === 'MPL-2.0' && hasAnyLicenseHeader(content, style))
+        if (isAcceptableNewFileHeader(file, content, style, license))
             continue;
         issues.push({
             file,
@@ -609,4 +634,3 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint.js.map

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

@@ -27,4 +27,3 @@ export async function withPatchDirectoryLock(patchesDir, operation) {
         throw new PatchError(toError(error).message);
     });
 }
-//# sourceMappingURL=patch-lock.js.map

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

@@ -4,6 +4,7 @@
  */
 import { stat } from 'node:fs/promises';
 import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
+import { withPatchDirectoryLock } from './patch-lock.js';
 import { loadPatchesManifestState, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
 import { inferPatchMetadataFromFilename } from './patch-manifest-validate.js';
 /**
@@ -89,6 +90,14 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  *   plus the filenames that were reconstructed from generic defaults.
  */
 export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion) {
+    // 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, and a repair racing a
+    // concurrent export/reorder used to be able to clobber the other
+    // writer's manifest. Not reentrant — callers must not already hold it.
+    return withPatchDirectoryLock(patchesDir, () => rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion));
+}
+async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion) {
     const manifestState = await loadPatchesManifestState(patchesDir);
     const existingEntries = new Map();
     if (manifestState.manifest) {
@@ -162,4 +171,3 @@ function normalizeFiles(files) {
 function sameStringArray(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);
 }
-//# sourceMappingURL=patch-manifest-consistency.js.map

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

@@ -37,10 +37,26 @@ export interface PatchManifestRowMutationResult {
 export declare function loadPatchesManifestState(patchesDir: string): Promise<LoadedManifestState>;
 /**
  * Loads the patches manifest if it exists.
+ *
+ * READ-ONLY callers only: this collapses "absent" and "corrupt" into null.
+ * Any code path that will WRITE the manifest (or delete patch files based
+ * on its content) must use {@link loadPatchesManifestForWrite} instead —
+ * treating a corrupt manifest as empty and then saving destroys every
+ * existing patch's metadata.
+ *
  * @param patchesDir - Path to the patches directory
  * @returns PatchesManifest or null if not found
  */
 export declare function loadPatchesManifest(patchesDir: string): Promise<PatchesManifest | null>;
+/**
+ * Loads the patches manifest for a mutating operation.
+ *
+ * Returns null only when the manifest genuinely does not exist; a manifest
+ * that exists but fails to parse/validate throws
+ * {@link PatchManifestCorruptError} so the caller aborts instead of
+ * rebuilding an empty queue over the top of the corrupt file.
+ */
+export declare function loadPatchesManifestForWrite(patchesDir: string): Promise<PatchesManifest | null>;
 /**
  * Saves the patches manifest.
  * @param patchesDir - Path to the patches directory