@hominis/fireforge 0.16.5 → 0.18.0

package/dist/src/core/marionette-port.js

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Marionette port probe.
+ *
+ * Gecko's Marionette control channel binds `127.0.0.1:2828` when a
+ * Firefox / ForgeFresh / Hominis instance is launched with
+ * `-marionette`. The `fireforge test` harness spawns the browser with
+ * that flag, so any test run needs the port to be free at start.
+ *
+ * Motivating case (2026-04-21 eval, Finding #20): an interrupted
+ * `fireforge test --headless` left an orphan
+ * `ForgeFresh.app/Contents/MacOS/forgefresh -marionette` process
+ * listening on 2828 with parent PID 1. The next `fireforge test` run
+ * — in a *different* FireForge project — failed immediately with a
+ * Marionette bind error, and FireForge's generic "re-run build" hint
+ * did not mention the stale listener. The probe in this module runs
+ * before every test launch, detects when the port is held, and —
+ * when the holder is a browser process (by command-line `-marionette`
+ * flag or by basename matching a known browser binary) — throws a
+ * targeted `GeneralError` naming the PID and the exact `kill` command
+ * to run.
+ *
+ * Cross-platform implementation:
+ *   - POSIX (macOS / Linux): `lsof -i tcp:<port> -P -n -sTCP:LISTEN`
+ *   - Windows: `Get-NetTCPConnection` via PowerShell, then
+ *     `Get-Process` to resolve the PID into a command line.
+ *
+ * Both paths tolerate missing tooling: if `lsof` / PowerShell isn't
+ * installed, the probe returns `{ inUse: false }` rather than failing
+ * the test run itself — the probe is a best-effort friendliness
+ * check, not a prerequisite.
+ */
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { getPlatform } from '../utils/platform.js';
+import { exec } from '../utils/process.js';
+/** Default Marionette control port set by `-marionette`. */
+export const DEFAULT_MARIONETTE_PORT = 2828;
+/** Basenames of browser binaries that ship a Marionette listener. */
+const BROWSER_BASENAMES = new Set([
+    'firefox',
+    'firefox-bin',
+    'firefox-esr',
+    'forgefresh',
+    'hominis',
+    'thunderbird',
+]);
+/**
+ * Returns `true` when the holder's command basename or command-line
+ * flags clearly identify it as a Firefox-family browser with
+ * Marionette enabled. Used to decide whether to raise a targeted
+ * "stale browser on port" error vs a soft "unrelated listener"
+ * warning.
+ *
+ * Includes the operator-provided `binaryName` from `fireforge.json`
+ * so a fork that ships under a custom name (e.g. Hominis'
+ * `hominis-nightly`) is still recognised as a browser.
+ */
+function isBrowserHolder(holder, binaryName) {
+    if (/\s-marionette(?:\s|$)/.test(holder.commandLine)) {
+        return true;
+    }
+    const name = holder.command.toLowerCase();
+    if (BROWSER_BASENAMES.has(name))
+        return true;
+    if (binaryName && name === binaryName.toLowerCase())
+        return true;
+    return false;
+}
+/**
+ * Probes the given port with `lsof` (macOS / Linux). Returns
+ * `{ inUse: false }` when the port is free OR when `lsof` is not
+ * available — the probe is a best-effort courtesy check, so a
+ * missing tool must not block the test run.
+ */
+async function probeWithLsof(port) {
+    try {
+        // `-sTCP:LISTEN` filters to listeners only; `-P -n` avoids
+        // service/host lookups (faster + no DNS-dependent flakiness).
+        // `-Fpcn` emits a machine-readable format: one field per line,
+        // with `p<pid>`, `c<command>`, `n<name>` records.
+        const result = await exec('lsof', ['-i', `tcp:${port}`, '-P', '-n', '-sTCP:LISTEN', '-Fpcn']);
+        // `lsof` exits 1 when no matches — that's "port is free", not an
+        // error. We key off stdout shape instead of exit code.
+        const stdout = result.stdout;
+        const lines = stdout.split(/\r?\n/).filter((l) => l.length > 0);
+        let pid = -1;
+        let command = '';
+        for (const line of lines) {
+            if (line.startsWith('p'))
+                pid = parseInt(line.slice(1), 10);
+            else if (line.startsWith('c'))
+                command = line.slice(1);
+        }
+        if (!Number.isFinite(pid) || pid < 0 || command === '') {
+            return { inUse: false };
+        }
+        // `lsof` does not return the full command line; `ps` does. A
+        // missing `ps` (exotic Linux container) falls back to `command`
+        // alone, which is still enough to match `BROWSER_BASENAMES`.
+        let commandLine = command;
+        try {
+            const psResult = await exec('ps', ['-p', String(pid), '-o', 'args=']);
+            const psLine = psResult.stdout.split(/\r?\n/).find((l) => l.trim().length > 0);
+            if (psLine)
+                commandLine = psLine.trim();
+        }
+        catch {
+            // ps not available — keep the basename.
+        }
+        return { inUse: true, holder: { pid, command, commandLine } };
+    }
+    catch (error) {
+        // `lsof` missing, or stdout parse failed. Treat as "unknown" ⇒
+        // port probe is silently skipped.
+        const message = toError(error).message;
+        if (/ENOENT|not found|command not found/i.test(message)) {
+            return { inUse: false };
+        }
+        return { inUse: false };
+    }
+}
+/**
+ * Probes the given port with PowerShell (Windows). Uses
+ * `Get-NetTCPConnection` to find listeners, then `Get-Process -Id`
+ * to resolve the process name and command line. Gracefully degrades
+ * when PowerShell is unavailable.
+ */
+async function probeWithPowerShell(port) {
+    const script = `$c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue;` +
+        ` if ($null -eq $c) { exit 0 }` +
+        ` $p = Get-Process -Id $c[0].OwningProcess -ErrorAction SilentlyContinue;` +
+        ` if ($null -eq $p) { exit 0 }` +
+        ` $w = Get-CimInstance Win32_Process -Filter "ProcessId = $($p.Id)" -ErrorAction SilentlyContinue;` +
+        ` Write-Output ("PID=" + $p.Id);` +
+        ` Write-Output ("NAME=" + $p.ProcessName);` +
+        ` if ($w -ne $null) { Write-Output ("CMD=" + $w.CommandLine) }`;
+    try {
+        const result = await exec('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            script,
+        ]);
+        const stdout = result.stdout;
+        const pidMatch = /PID=(\d+)/.exec(stdout);
+        const nameMatch = /NAME=([^\r\n]+)/.exec(stdout);
+        if (!pidMatch || !nameMatch)
+            return { inUse: false };
+        const pid = parseInt(pidMatch[1] ?? '', 10);
+        const command = (nameMatch[1] ?? '').trim();
+        const cmdMatch = /CMD=([^\r\n]+)/.exec(stdout);
+        const commandLine = cmdMatch ? (cmdMatch[1] ?? '').trim() : command;
+        if (!Number.isFinite(pid) || command === '')
+            return { inUse: false };
+        return { inUse: true, holder: { pid, command, commandLine } };
+    }
+    catch {
+        return { inUse: false };
+    }
+}
+/**
+ * Probes whether the Marionette port is currently bound by a
+ * listener. The probe is best-effort: missing tooling returns
+ * `{ inUse: false }` without failing.
+ *
+ * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
+ */
+export async function probeMarionettePort(port = DEFAULT_MARIONETTE_PORT) {
+    let platform;
+    try {
+        platform = getPlatform();
+    }
+    catch {
+        return { inUse: false };
+    }
+    if (platform === 'darwin' || platform === 'linux') {
+        return probeWithLsof(port);
+    }
+    // win32
+    return probeWithPowerShell(port);
+}
+/**
+ * Raises a targeted {@link GeneralError} when the Marionette port
+ * is held by a browser process; raises a softer warning-shaped
+ * error when the holder is unrelated (so the operator still sees
+ * a useful signal but can decide whether to wait it out).
+ *
+ * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
+ * @param options - Extra context for the error message (the project's
+ *   `binaryName` is used to recognise fork-branded browser binaries).
+ */
+export async function assertMarionettePortAvailable(port = DEFAULT_MARIONETTE_PORT, options = {}) {
+    const probe = await probeMarionettePort(port);
+    if (!probe.inUse || !probe.holder)
+        return;
+    const holder = probe.holder;
+    if (isBrowserHolder(holder, options.binaryName)) {
+        const killHint = process.platform === 'win32'
+            ? `Stop-Process -Id ${holder.pid} -Force`
+            : `kill ${holder.pid}  # or "kill -9 ${holder.pid}" if it doesn't exit`;
+        throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
+            `This is usually a browser left running by a previously interrupted "fireforge test" run. ` +
+            `Kill it with "${killHint}", then retry. ` +
+            `(If you expected ${holder.command} to be running on ${port}, stop it manually or pass ` +
+            `"--marionette-port <port>" to launch mach test on a different port.)`);
+    }
+    // Non-browser holder: mach test will still fail to bind, but the
+    // cause is not a stale FireForge-launched browser. Flag it
+    // explicitly so the operator can decide what to do instead of
+    // getting mach's bind error with no FireForge context.
+    throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
+        `This is not a FireForge-launched browser; stop the holder process or free the port before rerunning.`);
+}
+//# sourceMappingURL=marionette-port.js.map

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

@@ -67,10 +67,49 @@ export declare function lintPatchedJs(repoDir: string, affectedFiles: string[],
  * @returns Array of lint issues
  */
 export declare function lintModificationComments(diffContent: string, config: FireForgeConfig): PatchLintIssue[];
+/**
+ * Describes which tier `resolvePatchSizeTier` selected and why.
+ * Consumers that want to surface the tier choice to the operator
+ * (e.g. a one-line `info()` when branding thresholds kick in) read
+ * this alongside the issues array from `lintPatchSize`.
+ */
+export type PatchSizeTierDecision = {
+    tier: 'general';
+} | {
+    tier: 'test';
+} | {
+    tier: 'branding';
+    source: 'auto' | 'explicit';
+};
+/**
+ * Decides which `large-patch-lines` threshold tier applies to a patch.
+ * Exported so `runPatchLint` and the per-patch `lint` command can
+ * surface the tier choice to the operator *without* depending on
+ * `lintPatchSize`'s internal return shape — the rule itself stays a
+ * pure issues-array API, and the decision is computed separately for
+ * the sole purpose of reporting.
+ *
+ * Precedence: test > branding (explicit) > branding (auto) > general.
+ * The test tier beats branding because a table-driven regression test
+ * is legitimately large independent of whether the patch also claims
+ * branding shape, and the test-tier thresholds are already more
+ * permissive than branding — so "tests beat branding" is the
+ * defensive-for-tests choice.
+ */
+export declare function resolvePatchSizeTier(filesAffected: ReadonlyArray<string>, patchTier?: 'branding'): PatchSizeTierDecision;
 /**
  * Checks patch size and emits advisory warnings.
+ *
+ * @param filesAffected - Files touched by the patch
+ * @param lineCount - Non-binary line count of the unified diff
+ * @param patchTier - Optional explicit tier override declared on
+ *   `PatchMetadata.tier`. When `"branding"`, forces the branding
+ *   thresholds regardless of `filesAffected`. Tests still win over
+ *   branding (precedence `test > branding > general`) because the
+ *   test-tier thresholds are already more permissive and an all-tests
+ *   patch that is also branding-shaped is vanishingly rare.
  */
-export declare function lintPatchSize(filesAffected: string[], lineCount: number): PatchLintIssue[];
+export declare function lintPatchSize(filesAffected: string[], lineCount: number, patchTier?: 'branding'): PatchLintIssue[];
 /**
  * Checks that modified (non-new) files with a supported extension still
  * start with a recognized license header.
@@ -94,6 +133,12 @@ export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles:
  *   is advisory-noisy by nature (a cohesive branding bundle, auto-generated
  *   manifest, etc.) can opt out of a specific rule without reaching for the
  *   blunt `--skip-lint` hammer. Not mutated by this function.
+ * @param patchTier - Optional explicit tier override, threaded from
+ *   `PatchMetadata.tier`. When `"branding"` forces the branding
+ *   thresholds on the `large-patch-lines` rule. Callers with a
+ *   per-patch manifest context (re-export, per-patch lint) should
+ *   pass this; aggregate-mode callers without a specific patch
+ *   context skip it and fall through to auto-detection.
  * @returns Array of all lint issues found
  */
-export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
+export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>, patchTier?: 'branding'): Promise<PatchLintIssue[]>;

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

@@ -74,13 +74,49 @@ const PATCH_LINE_THRESHOLDS = {
     branding: { notice: 3000, warning: 8000, error: 20000 },
 };
 /**
- * Returns true when every file in a patch lives under `browser/branding/`.
- * Used by `lintPatchSize` to pick the branding threshold tier.
+ * Fixed allowlist of non-branding sibling paths that real-world Firefox
+ * branding patches legitimately need to touch to register the new
+ * branding flavor with the top-level configure. The 2026-04-21
+ * external eval showed that a branding patch which also touches
+ * `browser/moz.configure` (the canonical registration point) fell
+ * through to the general lint tier because the original predicate
+ * required every file to live under `browser/branding/`. This
+ * allowlist stays intentionally narrow — additions require a real
+ * operator data point, not a speculative expansion. Add new entries
+ * only when a genuine branding patch cannot be expressed without a
+ * specific registration sibling.
+ *
+ * Pinned against ESR 140.x conventions at time of writing.
+ */
+const BRANDING_REGISTRATION_FILES = new Set([
+    'browser/moz.configure',
+    'browser/confvars.sh',
+]);
+/**
+ * Returns true when a patch qualifies for the branding threshold tier:
+ * every file lives either under `browser/branding/` or in the narrow
+ * registration allowlist, AND the patch contains at least one file
+ * under `browser/branding/` (guard against a config-only patch
+ * accidentally qualifying as branding).
+ *
+ * Used by `lintPatchSize` to pick the branding threshold tier. The
+ * explicit `tier: "branding"` field on `PatchMetadata` bypasses this
+ * heuristic and forces the branding tier directly.
  */
 function isBrandingOnlyPatch(files) {
     if (files.length === 0)
         return false;
-    return files.every((file) => file.startsWith('browser/branding/'));
+    let hasBrandingFile = false;
+    for (const file of files) {
+        if (file.startsWith('browser/branding/')) {
+            hasBrandingFile = true;
+            continue;
+        }
+        if (BRANDING_REGISTRATION_FILES.has(file))
+            continue;
+        return false;
+    }
+    return hasBrandingFile;
 }
 /**
  * Returns true if the filename looks like a JS/MJS/JSM file.
@@ -426,13 +462,44 @@ export function lintModificationComments(diffContent, config) {
     }
     return issues;
 }
-// ---------------------------------------------------------------------------
-// Patch size lint (moved from export-shared.ts warnLargePatch)
-// ---------------------------------------------------------------------------
+/**
+ * Decides which `large-patch-lines` threshold tier applies to a patch.
+ * Exported so `runPatchLint` and the per-patch `lint` command can
+ * surface the tier choice to the operator *without* depending on
+ * `lintPatchSize`'s internal return shape — the rule itself stays a
+ * pure issues-array API, and the decision is computed separately for
+ * the sole purpose of reporting.
+ *
+ * Precedence: test > branding (explicit) > branding (auto) > general.
+ * The test tier beats branding because a table-driven regression test
+ * is legitimately large independent of whether the patch also claims
+ * branding shape, and the test-tier thresholds are already more
+ * permissive than branding — so "tests beat branding" is the
+ * defensive-for-tests choice.
+ */
+export function resolvePatchSizeTier(filesAffected, patchTier) {
+    const allTests = filesAffected.length > 0 && filesAffected.every(isTestFile);
+    if (allTests)
+        return { tier: 'test' };
+    if (patchTier === 'branding')
+        return { tier: 'branding', source: 'explicit' };
+    if (isBrandingOnlyPatch(filesAffected))
+        return { tier: 'branding', source: 'auto' };
+    return { tier: 'general' };
+}
 /**
  * Checks patch size and emits advisory warnings.
+ *
+ * @param filesAffected - Files touched by the patch
+ * @param lineCount - Non-binary line count of the unified diff
+ * @param patchTier - Optional explicit tier override declared on
+ *   `PatchMetadata.tier`. When `"branding"`, forces the branding
+ *   thresholds regardless of `filesAffected`. Tests still win over
+ *   branding (precedence `test > branding > general`) because the
+ *   test-tier thresholds are already more permissive and an all-tests
+ *   patch that is also branding-shaped is vanishingly rare.
  */
-export function lintPatchSize(filesAffected, lineCount) {
+export function lintPatchSize(filesAffected, lineCount, patchTier) {
     const issues = [];
     if (filesAffected.length > 5) {
         issues.push({
@@ -447,12 +514,14 @@ export function lintPatchSize(filesAffected, lineCount) {
     // harnesses run into the thousands of lines). Branding patches get their
     // own tier so a first-export of setup-generated branding doesn't fire
     // the general hard limit — see `PATCH_LINE_THRESHOLDS.branding` above
-    // for the eval data motivating this tier.
-    const allTests = filesAffected.length > 0 && filesAffected.every(isTestFile);
-    const branding = !allTests && isBrandingOnlyPatch(filesAffected);
-    const thresholds = allTests
+    // for the eval data motivating this tier. An explicit `patchTier`
+    // opt-in forces branding even when `isBrandingOnlyPatch` cannot reach
+    // the patch's actual shape (a branding patch that also touches a
+    // non-allowlisted sibling like a vendor-specific icon resource).
+    const decision = resolvePatchSizeTier(filesAffected, patchTier);
+    const thresholds = decision.tier === 'test'
         ? PATCH_LINE_THRESHOLDS.test
-        : branding
+        : decision.tier === 'branding'
             ? PATCH_LINE_THRESHOLDS.branding
             : PATCH_LINE_THRESHOLDS.general;
     if (lineCount >= thresholds.error) {
@@ -534,9 +603,15 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  *   is advisory-noisy by nature (a cohesive branding bundle, auto-generated
  *   manifest, etc.) can opt out of a specific rule without reaching for the
  *   blunt `--skip-lint` hammer. Not mutated by this function.
+ * @param patchTier - Optional explicit tier override, threaded from
+ *   `PatchMetadata.tier`. When `"branding"` forces the branding
+ *   thresholds on the `large-patch-lines` rule. Callers with a
+ *   per-patch manifest context (re-export, per-patch lint) should
+ *   pass this; aggregate-mode callers without a specific patch
+ *   context skip it and fall through to auto-detection.
  * @returns Array of all lint issues found
  */
-export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks) {
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier) {
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
@@ -547,7 +622,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),
     ]);
     const modCommentIssues = lintModificationComments(diffContent, config);
-    const sizeIssues = lintPatchSize(affectedFiles, lineCount);
+    const sizeIssues = lintPatchSize(affectedFiles, lineCount, patchTier);
     const issues = [
         ...sizeIssues,
         ...cssIssues,

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

@@ -14,11 +14,31 @@ export interface PatchManifestConsistencyIssue {
  * @returns Consistency issues between manifest metadata and on-disk patch files
  */
 export declare function validatePatchesManifestConsistency(patchesDir: string): Promise<PatchManifestConsistencyIssue[]>;
+/**
+ * Summary of a {@link rebuildPatchesManifest} run. `recoveredFilenames`
+ * lists patches whose manifest entry was reconstructed from filename,
+ * mtime, and diff alone (no pre-existing manifest entry to preserve).
+ * These entries carry generic descriptions and mtime-based
+ * timestamps; callers like `doctor --repair-patches-manifest` surface
+ * a per-patch review warning so operators know which metadata was
+ * invented vs which was restored.
+ */
+export interface RebuildPatchesManifestResult {
+    /** Rebuilt manifest, ready to be re-applied by callers (already persisted). */
+    manifest: PatchesManifest;
+    /**
+     * Filenames whose manifest entry had no pre-existing metadata to
+     * preserve — every descriptive field on these entries is inferred.
+     */
+    recoveredFilenames: string[];
+}
 /**
  * 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.
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - ESR version to use for recovered entries
+ * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
+ *   plus the filenames that were reconstructed from generic defaults.
  */
-export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string): Promise<PatchesManifest>;
+export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string): Promise<RebuildPatchesManifestResult>;

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

@@ -85,6 +85,8 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  * from filename structure, patch contents, and file mtimes.
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - ESR version to use for recovered entries
+ * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
+ *   plus the filenames that were reconstructed from generic defaults.
  */
 export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion) {
     const manifestState = await loadPatchesManifestState(patchesDir);
@@ -96,6 +98,7 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
     }
     const patches = await discoverPatches(patchesDir);
     const rebuiltPatches = [];
+    const recoveredFilenames = [];
     const highestFiniteOrder = patches.reduce((highest, patch) => {
         return Number.isFinite(patch.order) ? Math.max(highest, patch.order) : highest;
     }, 0);
@@ -106,7 +109,27 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
         const patchStats = await stat(patch.path);
         const inferred = inferPatchMetadataFromFilename(patch.filename);
         const recoveredOrder = Number.isFinite(patch.order) ? patch.order : nextRecoveredOrder++;
-        rebuiltPatches.push({
+        if (!existing) {
+            // Track every filename that had no pre-existing manifest entry
+            // so callers can warn the operator per-patch. A missing entry
+            // means every descriptive field (`description`, `createdAt`,
+            // `category`) was invented rather than preserved. FireForge
+            // patch files carry no header metadata that could carry a
+            // human description forward, so full fidelity is impossible —
+            // visibility is the best we can offer. 2026-04-21 eval
+            // (Finding #17) tripped over silent overwrites of useful
+            // human-written descriptions during a recovery run.
+            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
+        // fields 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.
+        const rebuilt = {
             filename: patch.filename,
             order: recoveredOrder,
             category: existing?.category ?? inferred.category,
@@ -116,7 +139,12 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
             createdAt: existing?.createdAt ?? new Date(patchStats.mtimeMs).toISOString(),
             sourceEsrVersion: existing?.sourceEsrVersion ?? fallbackSourceEsrVersion,
             filesAffected,
-        });
+        };
+        if (existing?.lintIgnore !== undefined)
+            rebuilt.lintIgnore = [...existing.lintIgnore];
+        if (existing?.tier !== undefined)
+            rebuilt.tier = existing.tier;
+        rebuiltPatches.push(rebuilt);
     }
     rebuiltPatches.sort((left, right) => left.order - right.order || left.filename.localeCompare(right.filename));
     const rebuiltManifest = {
@@ -124,7 +152,7 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
         patches: rebuiltPatches,
     };
     await savePatchesManifest(patchesDir, rebuiltManifest);
-    return rebuiltManifest;
+    return { manifest: rebuiltManifest, recoveredFilenames };
 }
 function normalizeFiles(files) {
     return Array.from(new Set(files)).sort((left, right) => left.localeCompare(right));

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

@@ -189,6 +189,16 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
                 throw new Error(`Cannot renumber: target patch filename already exists on disk: ${toEntry.newFilename}`);
             }
             await rename(join(patchesDir, staged), targetPath);
+            // Postcondition assert: confirm the target actually exists on
+            // disk before we mark the rename complete. A silent rename
+            // failure would leave the manifest and the filesystem
+            // disagreeing — exactly what the eval 1 Finding #7 report
+            // described: manifest rewrote to new filenames while the old
+            // files stayed on disk. If the assert ever fires, the Phase 2
+            // rollback will undo prior moves before re-throwing.
+            if (!(await pathExists(targetPath))) {
+                throw new Error(`Rename postcondition failed: expected ${toEntry.newFilename} to exist after rename, but it was not found on disk.`);
+            }
             completedFinalRenames.push(stagedEntry);
         }
     }

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

@@ -1,5 +1,24 @@
 import type { PatchMetadata } from '../types/commands/index.js';
 /**
- * Resolves a patch identifier (ordinal number or filename) to its manifest entry.
+ * Resolves a patch identifier to its manifest entry. Accepts:
+ *
+ *   1. An ordinal number (e.g. `2`) — matches `PatchMetadata.order`.
+ *   2. A full filename with `.patch` suffix (e.g. `002-ui-foo.patch`) —
+ *      matches `PatchMetadata.filename`.
+ *   3. A filename without the `.patch` suffix — the command appends it
+ *      before matching (e.g. `002-ui-foo`).
+ *   4. The manifest `name` field (e.g. `eval-furnace-token-override`) —
+ *      matches `PatchMetadata.name`. This is the short logical handle
+ *      the export workflow stamps onto the patch and the natural
+ *      identifier an operator keeps in their notes. 2026-04-21 eval
+ *      (Finding #6): `patch reorder`/`delete` rejected the `name`
+ *      even though the CLI help said `<name>`, forcing the operator
+ *      to copy the full filename from `patches.json` before every
+ *      queue mutation.
+ *
+ * Resolution order is strict: numeric ordinals first, then filename
+ * lookup (with + without `.patch` suffix), then name-field lookup.
+ * The filename lookup beats the name lookup when the two happen to
+ * collide so legacy scripts that pass filenames keep working.
  */
 export declare function resolvePatchIdentifier(identifier: string, patches: PatchMetadata[]): PatchMetadata | null;

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

@@ -1,12 +1,39 @@
 /**
- * Resolves a patch identifier (ordinal number or filename) to its manifest entry.
+ * Resolves a patch identifier to its manifest entry. Accepts:
+ *
+ *   1. An ordinal number (e.g. `2`) — matches `PatchMetadata.order`.
+ *   2. A full filename with `.patch` suffix (e.g. `002-ui-foo.patch`) —
+ *      matches `PatchMetadata.filename`.
+ *   3. A filename without the `.patch` suffix — the command appends it
+ *      before matching (e.g. `002-ui-foo`).
+ *   4. The manifest `name` field (e.g. `eval-furnace-token-override`) —
+ *      matches `PatchMetadata.name`. This is the short logical handle
+ *      the export workflow stamps onto the patch and the natural
+ *      identifier an operator keeps in their notes. 2026-04-21 eval
+ *      (Finding #6): `patch reorder`/`delete` rejected the `name`
+ *      even though the CLI help said `<name>`, forcing the operator
+ *      to copy the full filename from `patches.json` before every
+ *      queue mutation.
+ *
+ * Resolution order is strict: numeric ordinals first, then filename
+ * lookup (with + without `.patch` suffix), then name-field lookup.
+ * The filename lookup beats the name lookup when the two happen to
+ * collide so legacy scripts that pass filenames keep working.
  */
 export function resolvePatchIdentifier(identifier, patches) {
     if (/^\d+$/.test(identifier)) {
         const order = parseInt(identifier, 10);
         return patches.find((p) => p.order === order) ?? null;
     }
+    // Filename lookup — try the input as-is first (covers both the
+    // full `.patch` form and a bare name, because `endsWith` treats the
+    // bare form as a miss and falls through to the appended variant).
     const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
+    const byFilename = patches.find((p) => p.filename === normalized || p.filename === identifier);
+    if (byFilename)
+        return byFilename;
+    // Name-field lookup — the short logical handle stamped into the
+    // manifest at export time. See function docstring.
+    return patches.find((p) => p.name === identifier) ?? null;
 }
 //# sourceMappingURL=patch-manifest-resolve.js.map

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

@@ -23,7 +23,26 @@ export function validatePatchMetadata(data, index) {
         throw new Error(`patches[${index}].sourceEsrVersion must be a valid Firefox version string`);
     }
     const filesAffected = rec.stringArray('filesAffected');
-    return {
+    // Optional fields. These were silently stripped before the 0.17.0
+    // branding-tier work reached in and audited the loader — the 0.16.0
+    // `lintIgnore` escape hatch demonstrably round-tripped only through
+    // test fixtures that mocked `loadPatchesManifest` directly. Real
+    // operator edits to `patches.json` were dropped on every subsequent
+    // load, so any patch that relied on `lintIgnore` to suppress a
+    // specific lint rule was quietly re-tripped the next time the
+    // manifest validated. Preserve both the pre-existing `lintIgnore`
+    // and the new `tier` field here so future-added optional fields
+    // have a ready template to follow.
+    const lintIgnore = rec.optionalStringArray('lintIgnore');
+    const rawTier = rec.raw('tier');
+    let tier;
+    if (rawTier !== undefined) {
+        if (rawTier !== 'branding') {
+            throw new Error(`patches[${index}].tier must be "branding" when present (unknown tier values are rejected, not silently ignored).`);
+        }
+        tier = 'branding';
+    }
+    const result = {
         filename,
         order,
         category,
@@ -33,6 +52,11 @@ export function validatePatchMetadata(data, index) {
         sourceEsrVersion,
         filesAffected,
     };
+    if (lintIgnore !== undefined)
+        result.lintIgnore = lintIgnore;
+    if (tier !== undefined)
+        result.tier = tier;
+    return result;
 }
 /** Validates raw patches.json data and returns the typed manifest shape. */
 export function validatePatchesManifest(data) {