@hominis/fireforge 0.43.0 → 0.44.0

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

@@ -17,12 +17,11 @@ import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOw
 // Cross-patch lint re-exports
 // ---------------------------------------------------------------------------
 //
-// The cross-patch lint infrastructure (queue context builder, duplicate-
-// creation and forward-import rules, ignore marker) lives in
-// `patch-lint-cross.ts` so the per-patch and cross-patch rule bodies can
-// each stay within the project's per-file line budget. Re-export the
-// public surface from `patch-lint-reexports.ts` so callers continue to
-// import from a single module.
+// The cross-patch lint infrastructure (queue context builder,
+// duplicate-creation and forward-import rules, ignore marker) lives in
+// `patch-lint-cross.ts` so the per-patch and cross-patch rule bodies each
+// stay within the per-file line budget. The public surface is re-exported
+// from `patch-lint-reexports.ts` so callers keep importing from one module.
 export * from './patch-lint-reexports.js';
 // The CSS rule bodies live in `patch-lint-css.ts` (same per-file-budget
 // split as the other rule families); re-export the imported binding so
@@ -38,10 +37,10 @@ const FILE_SIZE_THRESHOLDS = {
 };
 /**
  * Counts the lines of `content` the way `wc -l` reports them: a trailing
- * newline terminates the last line rather than starting an empty extra
- * one. A naive `split('\n').length` over-counts by one for any content
- * ending in `\n` (the common case), which made the size rules fire one
- * line early against the operator's own `wc -l` measurement.
+ * newline terminates the last line rather than starting an empty extra one.
+ * A naive `split('\n').length` over-counts by one for any content ending in
+ * `\n` (the common case), making the size rules fire one line early against
+ * the operator's own `wc -l` measurement.
  */
 function countContentLines(content) {
     const lines = content.split('\n');
@@ -94,50 +93,39 @@ const PATCH_LINE_THRESHOLDS = {
      * Branding patches have a legitimate reason to be large: they include
      * every locale's `brand.ftl`, copied upstream CSS/PNG assets, and the
      * fork-specific `configure.sh` / `brand.properties` under a single
-     * `browser/branding/<name>/` subtree. Calibrated against:
+     * `browser/branding/<name>/` subtree.
      *
-     * - The 2026-04-21 eval baseline: a fresh-fork branding export landed
-     *   at 15904 lines (localized brand.ftl across many locales + SVG path
-     *   data + copied upstream CSS).
-     * - The 2026-04-25 operator data point: a freshly setup branding patch
-     *   (post-binary-exclusion, after Phase 1+2 patch splits) landed at
-     *   15650 lines — within 2% of the eval baseline.
-     *
-     * Both data points need to surface as a soft `notice` rather than a
-     * `warning`, since they represent the *minimum* branding diff. The
-     * pre-2026-04-25 calibration {3000/8000/20000} put 15904 firmly in the
-     * `warning` band, contradicting the docstring's "loud but not
-     * actionable" intent. The current calibration moves the warning band
-     * above the eval baseline (with ~13% headroom) and the error band to
-     * roughly 2× the baseline — reaching `error` strongly suggests
-     * non-branding work is bundled in.
+     * Calibrated against a fresh-fork branding export, which lands around
+     * 15–16k lines (localized brand.ftl across many locales + SVG path data +
+     * copied upstream CSS). That is the MINIMUM branding diff, so it must
+     * surface as a soft `notice` rather than a `warning`: the warning band
+     * sits above it with ~13% headroom, and the error band at roughly 2× the
+     * baseline, where non-branding work is probably bundled in.
      *
      * Permissive thresholds are safe because the *gate* into this tier is
-     * narrow (auto-detect requires every file under `browser/branding/`
-     * plus a tight registration allowlist, or an explicit
-     * `PatchMetadata.tier: "branding"` opt-in). A non-branding patch
-     * cannot accidentally land here.
+     * narrow: auto-detect requires every file under `browser/branding/` plus a
+     * tight registration allowlist, or an explicit `PatchMetadata.tier:
+     * "branding"` opt-in. A non-branding patch cannot accidentally land here.
      */
     branding: { notice: 8000, warning: 18000, error: 30000 },
 };
 /**
- * File-count thresholds for the `large-patch-files` rule, mirroring the
- * tier shape of {@link PATCH_LINE_THRESHOLDS}. A single warning-only
- * threshold per tier is intentional — file count expresses scope, not
- * blast radius, and there is no error band that would block export.
+ * File-count thresholds for the `large-patch-files` rule, mirroring the tier
+ * shape of {@link PATCH_LINE_THRESHOLDS}. A single warning-only threshold
+ * per tier is intentional — file count expresses scope, not blast radius,
+ * and there is no error band that would block export.
  *
  * The branding tier sits well above the typical floor because branding
- * patches inherently span many files: PNG/ICO icon assets in 7+ sizes,
- * MSIX manifests, channel-specific configs, locale `.ftl` files,
- * Windows/macOS launcher resources. The 2026-04-25 operator data point
- * reported a 56-file fresh-fork branding bundle as the minimum shape;
- * 60 leaves headroom for additional channels/locales while still firing
- * on a genuinely bloated patch.
+ * patches inherently span many files: PNG/ICO icon assets in 7+ sizes, MSIX
+ * manifests, channel-specific configs, locale `.ftl` files, Windows/macOS
+ * launcher resources. A fresh-fork branding bundle is around 56 files, so 60
+ * leaves headroom for additional channels/locales while still firing on a
+ * genuinely bloated patch.
  *
- * Test tier matches general because a test-only patch rarely touches
- * many files (a single regression test usually adds 1–3 fixtures); the
- * elevation in {@link PATCH_LINE_THRESHOLDS.test} addresses big
- * table-driven test bodies, not file fan-out.
+ * Test tier matches general because a test-only patch rarely touches many
+ * files (a single regression test usually adds 1–3 fixtures); the elevation
+ * in {@link PATCH_LINE_THRESHOLDS.test} addresses big table-driven test
+ * bodies, not file fan-out.
  */
 const PATCH_FILES_THRESHOLDS = {
     general: 5,
@@ -145,29 +133,25 @@ const PATCH_FILES_THRESHOLDS = {
     branding: 60,
 };
 /**
- * Shared remedy sentence for the over-budget findings: the two
- * places an operator stands when a patch outgrows its budget must name the
- * sanctioned one-transaction way out, or they reach for the wrong tools
- * first (the field report tried two before finding it). One constant, four
- * emission sites — the wording cannot drift.
+ * Shared remedy sentence for the over-budget findings. Both places an
+ * operator stands when a patch outgrows its budget must name the sanctioned
+ * one-transaction way out, or they reach for the wrong tools first. One
+ * constant, four emission sites, so the wording cannot drift.
  */
 const SPLIT_HINT = 'Consider splitting into smaller, focused patches — ' +
     '"fireforge patch move-files <from> <to> --file <path> --create --order <n>" ' +
     'moves files into a new patch in one transaction.';
 /**
  * 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.
+ * branding patches legitimately need to touch to register the new branding
+ * flavor with the top-level configure. A predicate requiring every file to
+ * live under `browser/branding/` drops a branding patch that also touches
+ * `browser/moz.configure` — the canonical registration point — into the
+ * general lint tier.
  *
- * Pinned against ESR 140.x conventions at time of writing.
+ * Intentionally narrow: add 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',
@@ -235,33 +219,31 @@ function isBrowserChromeTestFile(file) {
 /**
  * Bare assertion-call detection for the `test-needs-assertion` floor.
  *
- * Each alternative must sit at a call boundary: preceded by something that is
- * not an identifier character, `.`, `#`, or `-`. Until 0.41.0 this was a plain
- * `strippedContent.includes(tok)` over the tokens `Assert.`, `ok(`, `is(`,
- * `isnot(`, `isDeeply(`, so any identifier merely *ending* in one satisfied
- * the gate — `this.axis(3)` contains `is(`, `book(` contains `ok(`,
- * `promiseIsDeeply(` contains `isDeeply(`. An assertion-free smoke test using
- * any such call passed the floor, which is exactly what the rule exists to
- * catch.
+ * Each alternative must sit at a call boundary: preceded by something that
+ * is not an identifier character, `.`, `#`, or `-`. A plain
+ * `strippedContent.includes(tok)` over `Assert.`, `ok(`, `is(`, `isnot(`,
+ * `isDeeply(` lets any identifier merely *ending* in one satisfy the gate —
+ * `this.axis(3)` contains `is(`, `book(` contains `ok(`,
+ * `promiseIsDeeply(` contains `isDeeply(` — so an assertion-free smoke test
+ * using any such call clears the floor.
  *
- * The namespaced arm must name a member and a call. Matching the namespace and
- * its dot alone — as `(?:Assert|SimpleTest)\.` did — re-opened the same hole
- * from the other side: `SimpleTest` is mostly *harness* API, so
- * `SimpleTest.finish()`, `SimpleTest.waitForExplicitFinish()` and
- * `SimpleTest.requestCompleteLog()` each cleared the floor on their own. Those
- * are the exact calls an assertion-free smoke test contains. The enumeration
- * below is the mochitest/xpcshell assertion surface both namespaces share, and
- * it is what the user-facing message already names.
+ * The namespaced arm must name a member AND a call. Matching the namespace
+ * and its dot alone re-opens the same hole from the other side:
+ * `SimpleTest` is mostly *harness* API, so `SimpleTest.finish()`,
+ * `SimpleTest.waitForExplicitFinish()` and `SimpleTest.requestCompleteLog()`
+ * would each clear the floor on their own — the exact calls an
+ * assertion-free smoke test contains. The enumeration below is the
+ * mochitest/xpcshell assertion surface both namespaces share, and it is what
+ * the user-facing message names.
  *
- * Two qualified spellings of the bare four still count: `window.ok(...)` (the
- * globals ARE window properties) and an optional-chained `win?.ok(...)`.
- * Blocking those flagged tests whose only assertions are real as
+ * Two qualified spellings of the bare four also count: `window.ok(...)` (the
+ * globals ARE window properties) and an optional-chained `win?.ok(...)`;
+ * blocking those flags tests whose only assertions are real as
  * assertion-free. `SpecialPowers.ok(` stays excluded — that is API surface,
  * not an assertion.
  *
- * Deliberately still textual, not AST-based: this runs over patch bodies
- * rather than resolvable sources, and the surrounding rule is a floor, not a
- * proof.
+ * Deliberately textual, not AST-based: this runs over patch bodies rather
+ * than resolvable sources, and the surrounding rule is a floor, not a proof.
  */
 const ASSERTION_MEMBERS = [
     'ok',
@@ -318,22 +300,18 @@ export function commentStyleForFile(file) {
  * 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;
+ *    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
+ *    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. 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
@@ -588,16 +566,15 @@ export function lintPatchSize(filesAffected, lineCount, patchTier) {
     const issues = [];
     // Tier selection: test > branding > general. Tests keep their elevated
     // thresholds because a big regression test is legitimate (table-driven
-    // 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`
-    // and `PATCH_FILES_THRESHOLDS.branding` above 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). Both checks read off the
-    // same decision so the file-count and line-count rules cannot
-    // disagree about which tier applies.
+    // harnesses run into the thousands of lines). Branding patches get their
+    // own tier so a first export of setup-generated branding does not fire the
+    // general hard limit — see `PATCH_LINE_THRESHOLDS.branding` and
+    // `PATCH_FILES_THRESHOLDS.branding` above. 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). Both checks read off the
+    // same decision so the file-count and line-count rules cannot disagree
+    // about which tier applies.
     const decision = resolvePatchSizeTier(filesAffected, patchTier);
     const fileThreshold = decision.tier === 'test'
         ? PATCH_FILES_THRESHOLDS.test
@@ -687,23 +664,14 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  * @param affectedFiles - File paths (relative to repoDir) affected by the patch
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
- * @param patchQueueCtx - Optional cross-patch context for ownership resolution
- * @param ignoreChecks - Optional set of per-patch `check` IDs to drop from the
- *   returned issues. Threaded from `PatchMetadata.lintIgnore` so a patch that
- *   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.
- * @param options - Optional behaviour switches; see
- *   {@link LintExportedPatchOptions}.
+ * @param options - Optional context and behaviour switches; see
+ *   {@link LintExportedPatchOptions}. Every optional input lives here
+ *   rather than in a positional tail: four of the five call sites had to
+ *   pass `undefined` placeholders to reach the one member they wanted.
  * @returns Array of all lint issues found
  */
-export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier, options) {
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, options) {
+    const { patchQueueCtx, ignoreChecks, patchTier } = options ?? {};
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);

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

@@ -6,7 +6,7 @@ export interface PatchDirectoryLockOptions {
      * Wait up to this many seconds for the patch directory lock instead of the
      * default ~30 s budget. Enables exponential poll backoff (100 ms → 2 s)
      * and a holder-identified progress line roughly every 5 s. `undefined`
-     * preserves the historical behavior exactly.
+     * keeps the default.
      */
     waitLockSeconds?: number | undefined;
     /** Command name recorded in the lock's owner metadata for holder diagnostics. */

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

@@ -3,7 +3,7 @@
  * Filesystem-based lock for serializing patch directory mutations.
  */
 import { join } from 'node:path';
-import { FireForgeError } from '../errors/base.js';
+import { CommandError, FireForgeError } from '../errors/base.js';
 import { PatchError } from '../errors/patch.js';
 import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
@@ -56,7 +56,24 @@ export async function assertPatchDirectoryLockHeld(patchesDir, context) {
 export async function withPatchDirectoryLock(patchesDir, operation, options = {}) {
     const lockDir = join(patchesDir, PATCH_DIRECTORY_LOCK);
     const { waitLockSeconds, command } = options;
-    return withFileLock(lockDir, operation, {
+    // Tag whatever the BODY throws so the catch below can tell it apart from a
+    // lock-acquire/release failure. Narrowing by origin rather than by error
+    // shape is what "the rewrap is for lock I/O" actually means: an errno test
+    // would still reclassify an EACCES raised while the body writes a .patch
+    // file, and a class test cannot see a bare `new Error` from a body at all.
+    let bodyFailure;
+    let bodyThrew = false;
+    const trackedOperation = async () => {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            bodyThrew = true;
+            bodyFailure = error;
+            throw error;
+        }
+    };
+    return withFileLock(lockDir, trackedOperation, {
         ...(waitLockSeconds !== undefined
             ? {
                 timeoutMs: waitLockSeconds * 1000,
@@ -71,12 +88,12 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
         ...(command !== undefined
             ? { ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`] }
             : {}),
-        // Reason first, remedy second. The remedy is waiting, not
-        // deleting: bulk exports/re-exports legitimately hold this lock for
-        // minutes, FireForge reaps genuinely stale locks on its own, and the
-        // old advice ("rm -rf" while a holder was alive) destroyed a live
-        // lock. The leading sentence is a message contract; extend, don't
-        // reword. withFileLock appends the holder identification.
+        // Reason first, remedy second. The remedy is waiting, not deleting: bulk
+        // exports/re-exports legitimately hold this lock for minutes, and
+        // FireForge reaps genuinely stale locks on its own — advice to `rm -rf`
+        // while a holder is alive destroys a live lock. The leading sentence is
+        // a message contract; extend, do not reword. withFileLock appends the
+        // holder identification.
         onTimeoutMessage: `Timed out waiting for another FireForge command mutating ${patchesDir}.\n` +
             `Pass --wait-lock [seconds] to wait longer (bare --wait-lock waits up to 60 seconds). ` +
             `FireForge removes genuinely stale locks automatically; only if no other fireforge ` +
@@ -84,9 +101,28 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
         onStaleLockMessage: (ageMs) => `Removing stale patch lock (age: ${Math.round(ageMs / 1000)}s). ` +
             'A previous fireforge process may have crashed.',
     }).catch((error) => {
+        // The body's own failures are never ours to reclassify. Rewrapping them
+        // reports an EACCES writing patches.json, a postcondition failure from
+        // renumberPatchesInManifest, or a plain TypeError from a FireForge bug
+        // as a "Patch Error" carrying three fixed remedies about Firefox-version
+        // compatibility and `fireforge reset` — none of which apply. Worse,
+        // src/cli.ts prints a stack only for non-FireForgeError throwables, so
+        // the rewrap moves real bugs into the branch that discards their stack.
+        if (bodyThrew && error === bodyFailure) {
+            throw error;
+        }
         if (error instanceof FireForgeError) {
             throw error;
         }
-        throw new PatchError(toError(error).message);
+        // CommandError is the one class in src/errors/ that does NOT extend
+        // FireForgeError: it is the sentinel carrying an already-rendered exit
+        // code to the entrypoint. The `instanceof FireForgeError` guard above
+        // misses it, so without this the exit code was replaced by PATCH_ERROR.
+        if (error instanceof CommandError) {
+            throw error;
+        }
+        // What remains is a genuine failure to acquire or release the lock.
+        const cause = toError(error);
+        throw new PatchError(cause.message, undefined, cause);
     });
 }

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

@@ -2,6 +2,7 @@
  * Manifest consistency checks and rebuild/recovery operations.
  */
 import type { PatchesManifest } from '../types/commands/index.js';
+import type { PatchDirectoryLockOptions } from './patch-lock.js';
 /** Consistency issue codes for manifest validation. */
 export interface PatchManifestConsistencyIssue {
     code: 'manifest-invalid' | 'manifest-missing' | 'missing-patch-file' | 'untracked-patch-file' | 'files-affected-mismatch' | 'duplicate-manifest-entry';
@@ -41,4 +42,4 @@ export interface RebuildPatchesManifestResult {
  * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
  *   plus the filenames that were reconstructed from generic defaults.
  */
-export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string): Promise<RebuildPatchesManifestResult>;
+export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string, lockOptions?: PatchDirectoryLockOptions): Promise<RebuildPatchesManifestResult>;

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

@@ -89,13 +89,13 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
  *   plus the filenames that were reconstructed from generic defaults.
  */
-export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion) {
+export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion, lockOptions = {}) {
     // 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));
+    // 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);
 }
 async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion) {
     const manifestState = await loadPatchesManifestState(patchesDir);
@@ -113,11 +113,10 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
     }, 0);
     let nextRecoveredOrder = highestFiniteOrder + 1;
     // Prefetch the two independent per-patch reads concurrently. This runs
-    // while the patch-directory lock is held, and it was two serialised awaits
-    // per patch across the whole queue — 58 round-trips on a 29-patch queue.
-    // The fold below stays sequential because `nextRecoveredOrder` is
-    // loop-carried: parallelising the assignment would scramble the recovered
-    // ordinals.
+    // while the patch-directory lock is held, and as two serialised awaits per
+    // patch it costs 58 round-trips on a 29-patch queue. The fold below stays
+    // 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)),
         patchStats: await stat(patch.path),
@@ -131,25 +130,24 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
         const inferred = inferPatchMetadataFromFilename(patch.filename);
         const recoveredOrder = Number.isFinite(patch.order) ? patch.order : nextRecoveredOrder++;
         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.
+            // 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, and FireForge patch files carry no
+            // header metadata that could carry a human description forward — so
+            // visibility is the best available, and silent overwrites of
+            // human-written descriptions during a recovery run are the failure to
+            // 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
-        // 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.
+        // 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.
         const rebuilt = {
             filename: patch.filename,
             order: recoveredOrder,

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

@@ -12,7 +12,7 @@ import { rename } from 'node:fs/promises';
 import { join } from 'node:path';
 import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
-import { PatchManifestCorruptError } from '../errors/patch.js';
+import { PatchError, PatchManifestCorruptError } from '../errors/patch.js';
 import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
@@ -315,7 +315,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
     await assertPatchDirectoryLockHeld(patchesDir, 'renumbering the patch manifest');
     const manifest = await loadPatchesManifestForWrite(patchesDir);
     if (!manifest) {
-        throw new Error('Cannot renumber patches: patches.json is missing.');
+        throw new PatchError('Cannot renumber patches: patches.json is missing.');
     }
     // Phase 1: rename each old filename to a unique temp staging name so the
     // later rename to the final target cannot collide with another entry
@@ -326,7 +326,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         for (const [oldFilename, entry] of renameMap) {
             const oldPath = join(patchesDir, oldFilename);
             if (!(await pathExistsStrict(oldPath))) {
-                throw new Error(`Cannot renumber: patch file is missing on disk: ${oldFilename}`);
+                throw new PatchError(`Cannot renumber: patch file is missing on disk: ${oldFilename}`, oldFilename);
             }
             const stagedName = `.fireforge-renumber-${stagingId}-${oldFilename}`;
             const stagedPath = join(patchesDir, stagedName);
@@ -354,18 +354,16 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
             const { staged, toEntry } = stagedEntry;
             const targetPath = join(patchesDir, toEntry.newFilename);
             if (await pathExistsStrict(targetPath)) {
-                throw new Error(`Cannot renumber: target patch filename already exists on disk: ${toEntry.newFilename}`);
+                throw new PatchError(`Cannot renumber: target patch filename already exists on disk: ${toEntry.newFilename}`, 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.
+            // Postcondition assert: confirm the target actually exists on disk
+            // before marking the rename complete. A silent rename failure leaves
+            // the manifest and the filesystem disagreeing — manifest rewritten to
+            // new filenames while the old files stay on disk. If the assert fires,
+            // the Phase 2 rollback undoes prior moves before re-throwing.
             if (!(await pathExistsStrict(targetPath))) {
-                throw new Error(`Rename postcondition failed: expected ${toEntry.newFilename} to exist after rename, but it was not found on disk.`);
+                throw new PatchError(`Rename postcondition failed: expected ${toEntry.newFilename} to exist after rename, but it was not found on disk.`, toEntry.newFilename);
             }
             completedFinalRenames.push(stagedEntry);
         }
@@ -525,12 +523,10 @@ export async function removePatchFileAndManifest(patchesDir, filename) {
                 await savePatchesManifest(patchesDir, originalManifest);
             }
             catch (rollbackError) {
-                // Compound failure: both the delete and the rollback failed,
-                // so the directory is in a known-inconsistent state. Throw a
-                // dedicated error type that carries both causes so the
-                // operator's log shows the complete picture instead of the
-                // original delete error with a warning about the rollback
-                // buried in stderr.
+                // Compound failure: both the delete and the rollback failed, so the
+                // directory is in a known-inconsistent state. A dedicated error type
+                // carrying both causes shows the complete picture instead of the
+                // original delete error with a rollback warning buried in stderr.
                 throw new PatchDeleteRollbackError(filename, deleteError, toError(rollbackError));
             }
         }

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

@@ -7,18 +7,15 @@ import type { PatchMetadata } from '../types/commands/index.js';
  *      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.
+ *   4. The manifest `name` field (e.g. `furnace-token-override`) — the short
+ *      logical handle the export workflow stamps onto the patch and the
+ *      natural identifier an operator keeps in their notes. The CLI help
+ *      says `<name>`, so rejecting it forces the operator to copy the full
+ *      filename out of `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.
+ * Resolution order is strict: numeric ordinals first, then filename lookup
+ * (with and without the `.patch` suffix), then name-field lookup. The
+ * filename lookup beats the name lookup when the two collide, so scripts
+ * that pass filenames keep working.
  */
 export declare function resolvePatchIdentifier(identifier: string, patches: PatchMetadata[]): PatchMetadata | null;

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

@@ -6,19 +6,16 @@
  *      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.
+ *   4. The manifest `name` field (e.g. `furnace-token-override`) — the short
+ *      logical handle the export workflow stamps onto the patch and the
+ *      natural identifier an operator keeps in their notes. The CLI help
+ *      says `<name>`, so rejecting it forces the operator to copy the full
+ *      filename out of `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.
+ * Resolution order is strict: numeric ordinals first, then filename lookup
+ * (with and without the `.patch` suffix), then name-field lookup. The
+ * filename lookup beats the name lookup when the two collide, so scripts
+ * that pass filenames keep working.
  */
 export function resolvePatchIdentifier(identifier, patches) {
     if (/^\d+$/.test(identifier)) {