@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -3,21 +3,19 @@
  *
  * 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.
+ * `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.
+ * **Do not reintroduce whitespace trimming here.** Stripping marker lines
+ * whose payload is pure whitespace (`/^[ +-]\s+$/` → bare marker) corrupts
+ * real content: Firefox sources contain whitespace-only lines, so a ` `/`-`
+ * line whose payload was e.g. two spaces no longer matches the pristine tree
+ * (the freshly exported patch fails `git apply --check`), and a `+` line
+ * silently changes what the patch produces, making re-import diverge from
+ * the engine state it was exported from. The repository whitespace check
+ * already excludes `patches/*.patch`
+ * (scripts/check-worktree-whitespace.mjs). Patch bodies are 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

@@ -4,22 +4,20 @@
  *
  * 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.
+ * `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.
+ * **Do not reintroduce whitespace trimming here.** Stripping marker lines
+ * whose payload is pure whitespace (`/^[ +-]\s+$/` → bare marker) corrupts
+ * real content: Firefox sources contain whitespace-only lines, so a ` `/`-`
+ * line whose payload was e.g. two spaces no longer matches the pristine tree
+ * (the freshly exported patch fails `git apply --check`), and a `+` line
+ * silently changes what the patch produces, making re-import diverge from
+ * the engine state it was exported from. The repository whitespace check
+ * already excludes `patches/*.patch`
+ * (scripts/check-worktree-whitespace.mjs). Patch bodies are 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;

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

@@ -2,6 +2,7 @@
  * Manifest metadata mutation helpers for patch export commands.
  */
 import type { PatchMetadata } from '../types/commands/index.js';
+import type { PatchDirectoryLockOptions } from './patch-lock.js';
 /**
  * Optional `PatchMetadata` keys safe to clear via the helpers below.
  */
@@ -13,8 +14,11 @@ export type ClearablePatchMetadataField = 'tier' | 'lintIgnore' | 'stagedDepende
  * @param filename - Patch filename
  * @param updates - Field values to set
  * @param unsetFields - Optional fields to remove from the entry
+ * @param lockOptions - `--wait-lock` budget and the command name recorded in
+ *   the lock's owner metadata. Threaded from the CLI so a caller that waits
+ *   is not silently given the default 30s budget.
  */
-export declare function updatePatchMetadata(patchesDir: string, filename: string, updates: Partial<PatchMetadata>, unsetFields?: ReadonlyArray<ClearablePatchMetadataField>): Promise<void>;
+export declare function updatePatchMetadata(patchesDir: string, filename: string, updates: Partial<PatchMetadata>, unsetFields?: ReadonlyArray<ClearablePatchMetadataField>, lockOptions?: PatchDirectoryLockOptions): Promise<void>;
 /** Return shape from a `mutatePatchMetadata` mutator. */
 export interface PatchMetadataMutation {
     /** Field values to set on the entry. */
@@ -32,5 +36,11 @@ export interface PatchMetadataMutationResult {
 /**
  * Reads a patch's metadata under the directory lock, applies a mutator
  * function to compute the update, and writes the result back.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filename - Patch filename
+ * @param mutator - Computes the update from the existing metadata
+ * @param lockOptions - `--wait-lock` budget and owner-metadata command name
+ * @returns Before/after metadata, or null when the patch was not found
  */
-export declare function mutatePatchMetadata(patchesDir: string, filename: string, mutator: (existing: PatchMetadata) => PatchMetadataMutation): Promise<PatchMetadataMutationResult | null>;
+export declare function mutatePatchMetadata(patchesDir: string, filename: string, mutator: (existing: PatchMetadata) => PatchMetadataMutation, lockOptions?: PatchDirectoryLockOptions): Promise<PatchMetadataMutationResult | null>;

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

@@ -11,20 +11,29 @@ import { mutatePatchRowsInManifest } from './patch-manifest.js';
  * @param filename - Patch filename
  * @param updates - Field values to set
  * @param unsetFields - Optional fields to remove from the entry
+ * @param lockOptions - `--wait-lock` budget and the command name recorded in
+ *   the lock's owner metadata. Threaded from the CLI so a caller that waits
+ *   is not silently given the default 30s budget.
  */
-export async function updatePatchMetadata(patchesDir, filename, updates, unsetFields = []) {
+export async function updatePatchMetadata(patchesDir, filename, updates, unsetFields = [], lockOptions = {}) {
     await withPatchDirectoryLock(patchesDir, async () => {
         await mutatePatchRowsInManifest(patchesDir, [filename], () => ({
             set: updates,
             unset: unsetFields,
         }));
-    });
+    }, lockOptions);
 }
 /**
  * Reads a patch's metadata under the directory lock, applies a mutator
  * function to compute the update, and writes the result back.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filename - Patch filename
+ * @param mutator - Computes the update from the existing metadata
+ * @param lockOptions - `--wait-lock` budget and owner-metadata command name
+ * @returns Before/after metadata, or null when the patch was not found
  */
-export async function mutatePatchMetadata(patchesDir, filename, mutator) {
+export async function mutatePatchMetadata(patchesDir, filename, mutator, lockOptions = {}) {
     return await withPatchDirectoryLock(patchesDir, async () => {
         const result = await mutatePatchRowsInManifest(patchesDir, [filename], (existing) => {
             const { set = {}, unset = [] } = mutator(existing);
@@ -34,5 +43,5 @@ export async function mutatePatchMetadata(patchesDir, filename, mutator) {
         if (!changed)
             return null;
         return { before: changed.before, after: changed.after };
-    });
+    }, lockOptions);
 }

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

@@ -1,5 +1,6 @@
 import type { PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
+import type { PatchDirectoryLockOptions } from './patch-lock.js';
 /**
  * Optional post-commit hook for {@link updatePatchAndMetadata}. Runs inside
  * the patch directory lock after the mutation has succeeded but before the
@@ -16,5 +17,16 @@ export interface UpdatePatchPolicyGate {
  * Updates a patch file body and its manifest row under the same patch
  * directory lock. Intended for commands like `re-export --files` where the
  * file body and `filesAffected` metadata must move together.
+ *
+ * The body write is skipped when the normalized new content is byte-identical
+ * to what is already on disk. A bulk `re-export --all` refreshes every patch
+ * in the queue, including ones the working tree never touched; rewriting an
+ * unchanged body churns its mtime and reports "Re-exported" for a patch
+ * nothing happened to, which is exactly the noise that hides a real
+ * unexpected rewrite in `git status`. Metadata still moves either way — only
+ * the redundant byte-for-byte write is elided.
+ *
+ * @returns True when the patch body on disk changed, false when it was
+ *   already byte-identical to the new content.
  */
-export declare function updatePatchAndMetadata(patchesDir: string, filename: string, newContent: string, updates: Partial<PatchMetadata>, onCommitted?: UpdatePatchCommittedHook, policyGate?: UpdatePatchPolicyGate): Promise<void>;
+export declare function updatePatchAndMetadata(patchesDir: string, filename: string, newContent: string, updates: Partial<PatchMetadata>, onCommitted?: UpdatePatchCommittedHook, policyGate?: UpdatePatchPolicyGate, lockOptions?: PatchDirectoryLockOptions): Promise<boolean>;

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
+import { PatchError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
@@ -11,20 +12,31 @@ import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
  * Updates a patch file body and its manifest row under the same patch
  * directory lock. Intended for commands like `re-export --files` where the
  * file body and `filesAffected` metadata must move together.
+ *
+ * The body write is skipped when the normalized new content is byte-identical
+ * to what is already on disk. A bulk `re-export --all` refreshes every patch
+ * in the queue, including ones the working tree never touched; rewriting an
+ * unchanged body churns its mtime and reports "Re-exported" for a patch
+ * nothing happened to, which is exactly the noise that hides a real
+ * unexpected rewrite in `git status`. Metadata still moves either way — only
+ * the redundant byte-for-byte write is elided.
+ *
+ * @returns True when the patch body on disk changed, false when it was
+ *   already byte-identical to the new content.
  */
-export async function updatePatchAndMetadata(patchesDir, filename, newContent, updates, onCommitted, policyGate) {
-    await withPatchDirectoryLock(patchesDir, async () => {
+export async function updatePatchAndMetadata(patchesDir, filename, newContent, updates, onCommitted, policyGate, lockOptions = {}) {
+    return withPatchDirectoryLock(patchesDir, async () => {
         const manifest = await loadPatchesManifestForWrite(patchesDir);
         if (!manifest) {
-            throw new Error('Cannot update patch metadata: patches.json is missing.');
+            throw new PatchError('Cannot update patch metadata: patches.json is missing.', filename);
         }
         const patchIndex = manifest.patches.findIndex((p) => p.filename === filename);
         if (patchIndex === -1) {
-            throw new Error(`Cannot update patch metadata: ${filename} not found in patches.json.`);
+            throw new PatchError(`Cannot update patch metadata: ${filename} not found in patches.json.`, filename);
         }
         const patchPath = join(patchesDir, filename);
         if (!(await pathExists(patchPath))) {
-            throw new Error(`Cannot update patch: patch file is missing on disk: ${filename}`);
+            throw new PatchError(`Cannot update patch: patch file is missing on disk: ${filename}`, filename);
         }
         const originalContent = await readText(patchPath);
         const existingPatch = manifest.patches[patchIndex];
@@ -37,10 +49,14 @@ export async function updatePatchAndMetadata(patchesDir, filename, newContent, u
                 forceUnsafe: policyGate.forceUnsafe === true,
             });
         }
+        const normalized = normalizePatchArtifact(newContent);
+        const bodyChanged = normalized !== originalContent;
         let patchWritten = false;
         try {
-            await writeText(patchPath, normalizePatchArtifact(newContent));
-            patchWritten = true;
+            if (bodyChanged) {
+                await writeText(patchPath, normalized);
+                patchWritten = true;
+            }
             await mutatePatchRowsInManifest(patchesDir, [filename], () => ({ set: updates }));
         }
         catch (error) {
@@ -63,5 +79,6 @@ export async function updatePatchAndMetadata(patchesDir, filename, newContent, u
                     toError(hookError).message);
             }
         }
-    });
+        return bodyChanged;
+    }, lockOptions);
 }

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

@@ -1,6 +1,7 @@
 import type { PatchCategory, PatchesManifest, PatchInfo, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type SupersedeCoverageDetail } from './patch-export-coverage.js';
+import type { PatchDirectoryLockOptions } from './patch-lock.js';
 export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, type SupersedeCoverageDetail, } from './patch-export-coverage.js';
 export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadata.js';
 export { updatePatchAndMetadata } from './patch-export-update.js';
@@ -23,11 +24,11 @@ export declare function sanitizeName(name: string): string;
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
  * Operators frequently pass the DESIRED FILENAME stem to `--name`
- * (`--name 203-ui-foo --category ui`), which 0.33.0 double-prefixed into
- * `203-ui-203-ui-foo.patch`. The filename builders prepend the order and
- * category themselves, so a matching prefix in the name is always
- * redundant. Applied repeatedly so a twice-prefixed slug (from a previous
- * double-prefix incident) also collapses. Exported for direct testing.
+ * (`--name 203-ui-foo --category ui`), which would otherwise double-prefix
+ * into `203-ui-203-ui-foo.patch`. The filename builders prepend the order
+ * and category themselves, so a matching prefix in the name is always
+ * redundant. Applied repeatedly so a twice-prefixed slug also collapses.
+ * Exported for direct testing.
  */
 export declare function stripRedundantCategoryPrefix(sanitizedName: string, category: string): string;
 /**
@@ -36,9 +37,9 @@ export declare function stripRedundantCategoryPrefix(sanitizedName: string, cate
  * A single trailing `.patch` extension is stripped before sanitisation:
  * operators frequently pass a full patch FILENAME where a name is expected
  * (`move-files <from> 348-ui-foo.patch --create`, `rename --to foo.patch`),
- * and 0.38.0 slugged the extension into `-patch`, producing double-suffixed
- * `...-patch.patch` files. A name that deliberately ends in a literal
- * `-patch` slug segment must now be written without the dot form.
+ * and slugging the extension produces double-suffixed `...-patch.patch`
+ * files. A name that deliberately ends in a literal `-patch` slug segment
+ * must be written without the dot form.
  */
 export declare function patchNameSlug(name: string, category: string): string;
 /**
@@ -69,6 +70,12 @@ export interface CommitExportedPatchInput {
     policyCommand?: string;
     /** Whether --force-unsafe was supplied by the mutating command. */
     forceUnsafe?: boolean;
+    /**
+     * `--wait-lock` budget and the command name recorded in the lock's owner
+     * metadata. Threaded from the CLI so a caller that asked to wait is not
+     * silently given the default budget.
+     */
+    lockOptions?: PatchDirectoryLockOptions;
 }
 export interface CommitExportedPatchResult {
     patchFilename: string;

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

@@ -7,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, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
+import { addPatchToManifest, findPatchesAffectingFile, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
 import { requirePatchOrder } from './patch-parse.js';
 import { allocatePolicyOrder, enforcePatchPolicy } from './patch-policy.js';
 export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, } from './patch-export-coverage.js';
@@ -50,11 +50,11 @@ export function sanitizeName(name) {
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
  * Operators frequently pass the DESIRED FILENAME stem to `--name`
- * (`--name 203-ui-foo --category ui`), which 0.33.0 double-prefixed into
- * `203-ui-203-ui-foo.patch`. The filename builders prepend the order and
- * category themselves, so a matching prefix in the name is always
- * redundant. Applied repeatedly so a twice-prefixed slug (from a previous
- * double-prefix incident) also collapses. Exported for direct testing.
+ * (`--name 203-ui-foo --category ui`), which would otherwise double-prefix
+ * into `203-ui-203-ui-foo.patch`. The filename builders prepend the order
+ * and category themselves, so a matching prefix in the name is always
+ * redundant. Applied repeatedly so a twice-prefixed slug also collapses.
+ * Exported for direct testing.
  */
 export function stripRedundantCategoryPrefix(sanitizedName, category) {
     const prefixes = [
@@ -80,9 +80,9 @@ export function stripRedundantCategoryPrefix(sanitizedName, category) {
  * A single trailing `.patch` extension is stripped before sanitisation:
  * operators frequently pass a full patch FILENAME where a name is expected
  * (`move-files <from> 348-ui-foo.patch --create`, `rename --to foo.patch`),
- * and 0.38.0 slugged the extension into `-patch`, producing double-suffixed
- * `...-patch.patch` files. A name that deliberately ends in a literal
- * `-patch` slug segment must now be written without the dot form.
+ * and slugging the extension produces double-suffixed `...-patch.patch`
+ * files. A name that deliberately ends in a literal `-patch` slug segment
+ * must be written without the dot form.
  */
 export function patchNameSlug(name, category) {
     const stem = name.replace(/\.patch$/i, '');
@@ -186,7 +186,7 @@ export async function commitExportedPatch(input) {
             metadata: plan.metadata,
             superseded: plan.supersededPatches,
         };
-    });
+    }, input.lockOptions ?? {});
 }
 /**
  * Parses a patch filename to extract order, category, and name.
@@ -226,7 +226,6 @@ export function parseFilename(filename) {
  * @returns The patch info and metadata, or null if not found
  */
 export async function findExistingPatchForFile(patchesDir, filePath) {
-    const { findPatchesAffectingFile } = await import('./patch-manifest.js');
     const affectingPatches = await findPatchesAffectingFile(patchesDir, filePath);
     if (affectingPatches.length === 0) {
         return null;

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

@@ -12,11 +12,10 @@ export declare function getTargetFileFromPatch(patchPath: string): Promise<strin
  *
  * Delegates to {@link extractAffectedFiles} so `GIT binary patch` sections
  * (which have no `+++ b/…` line, only a `diff --git a/… b/…` header) are
- * included alongside text hunks. Before this delegation the custom regex
- * only matched `+++ b/…` lines, dropping every binary file from
- * `filesAffected` — verify reported `files-affected-mismatch` against
- * branding patches and `doctor --repair-patches-manifest` "repaired" the
- * manifest by rewriting it to the text-only subset, hiding the true scope
- * of the patch.
+ * included alongside text hunks. Matching only `+++ b/…` lines drops every
+ * binary file from `filesAffected`, so verify reports
+ * `files-affected-mismatch` against branding patches and
+ * `doctor --repair-patches-manifest` "repairs" the manifest by rewriting it
+ * to the text-only subset, hiding the true scope of the patch.
  */
 export declare function getAllTargetFilesFromPatch(patchPath: string): Promise<string[]>;

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

@@ -40,12 +40,11 @@ export async function getTargetFileFromPatch(patchPath) {
  *
  * Delegates to {@link extractAffectedFiles} so `GIT binary patch` sections
  * (which have no `+++ b/…` line, only a `diff --git a/… b/…` header) are
- * included alongside text hunks. Before this delegation the custom regex
- * only matched `+++ b/…` lines, dropping every binary file from
- * `filesAffected` — verify reported `files-affected-mismatch` against
- * branding patches and `doctor --repair-patches-manifest` "repaired" the
- * manifest by rewriting it to the text-only subset, hiding the true scope
- * of the patch.
+ * included alongside text hunks. Matching only `+++ b/…` lines drops every
+ * binary file from `filesAffected`, so verify reports
+ * `files-affected-mismatch` against branding patches and
+ * `doctor --repair-patches-manifest` "repairs" the manifest by rewriting it
+ * to the text-only subset, hiding the true scope of the patch.
  */
 export async function getAllTargetFilesFromPatch(patchPath) {
     const content = await readText(patchPath);

package/dist/src/core/patch-identifier-suggest.d.ts

@@ -2,18 +2,13 @@
  * Builds a concise "patch not found" error message with did-you-mean
  * suggestions in place of the full queue enumeration.
  *
- * 2026-04-26 eval Finding 12: pre-fix every `patch` subcommand
- * (`delete`, `reorder`, `tier`, `lint-ignore`) caught a missing
- * identifier by joining every queued patch's filename and (optional)
- * manifest name into a single comma-separated `Available: ...` tail.
- * On a 29-patch queue the resulting line ran ~1500 characters and
- * buried the actual error under noise that was almost never useful in
- * CI. The new shape ranks each known identifier (ordinal,
- * filename-with-and-without-`.patch`, manifest name) by Levenshtein
- * distance from the operator's input, surfaces up to three suggestions
- * close enough to be plausibly the intended target, and falls back to
- * a count-only summary that points at `fireforge patch list` when no
- * close match exists. The full enumeration is no longer ever inlined.
+ * Joining every queued patch's filename and manifest name into a
+ * comma-separated `Available: ...` tail runs ~1500 characters on a 29-patch
+ * queue and buries the actual error. This ranks each known identifier
+ * (ordinal, filename with and without `.patch`, manifest name) by
+ * Levenshtein distance from the operator's input, surfaces up to three
+ * plausible suggestions, and falls back to a count-only summary pointing at
+ * `fireforge patch list` when no close match exists.
  */
 import type { PatchMetadata } from '../types/commands/index.js';
 /**

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

@@ -3,18 +3,13 @@
  * Builds a concise "patch not found" error message with did-you-mean
  * suggestions in place of the full queue enumeration.
  *
- * 2026-04-26 eval Finding 12: pre-fix every `patch` subcommand
- * (`delete`, `reorder`, `tier`, `lint-ignore`) caught a missing
- * identifier by joining every queued patch's filename and (optional)
- * manifest name into a single comma-separated `Available: ...` tail.
- * On a 29-patch queue the resulting line ran ~1500 characters and
- * buried the actual error under noise that was almost never useful in
- * CI. The new shape ranks each known identifier (ordinal,
- * filename-with-and-without-`.patch`, manifest name) by Levenshtein
- * distance from the operator's input, surfaces up to three suggestions
- * close enough to be plausibly the intended target, and falls back to
- * a count-only summary that points at `fireforge patch list` when no
- * close match exists. The full enumeration is no longer ever inlined.
+ * Joining every queued patch's filename and manifest name into a
+ * comma-separated `Available: ...` tail runs ~1500 characters on a 29-patch
+ * queue and buries the actual error. This ranks each known identifier
+ * (ordinal, filename with and without `.patch`, manifest name) by
+ * Levenshtein distance from the operator's input, surfaces up to three
+ * plausible suggestions, and falls back to a count-only summary pointing at
+ * `fireforge patch list` when no close match exists.
  */
 /** Maximum Levenshtein distance accepted as a "did you mean" suggestion. */
 const SUGGESTION_DISTANCE_THRESHOLD = 3;
@@ -93,13 +88,13 @@ function rankSuggestions(identifier, candidates) {
         .map((candidate) => {
         const lower = candidate.toLowerCase();
         // Prefix relation in EITHER direction is a stronger signal than edit
-        // distance and is not bounded by it: a partial ordinal or
-        // an abbreviated slug ("ui-foo" for "002-ui-foo.patch") is many edits
-        // away from the full identifier yet is obviously the intended target.
-        // `lower.startsWith(needle)`: the operator typed an abbreviation of
-        // a real identifier. The reverse relation is only meaningful when
-        // the candidate is substantial — otherwise the single-character
-        // ordinal "9" would "match" every input starting with a 9.
+        // distance and is not bounded by it: a partial ordinal or an
+        // abbreviated slug ("ui-foo" for "002-ui-foo.patch") is many edits away
+        // from the full identifier yet is obviously the intended target.
+        // `lower.startsWith(needle)`: the operator typed an abbreviation of a
+        // real identifier. The reverse relation is only meaningful when the
+        // candidate is substantial — otherwise the single-character ordinal
+        // "9" would "match" every input starting with a 9.
         const prefixMatch = needle.length >= MIN_PREFIX_MATCH_LENGTH &&
             (lower.startsWith(needle) ||
                 (lower.length >= MIN_PREFIX_MATCH_LENGTH && needle.startsWith(lower)));

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

@@ -0,0 +1,51 @@
+/**
+ * Queue-wide lint for binary patch bodies that cannot recreate their file.
+ *
+ * `git diff` has two ways to render a binary change. `git diff --binary`
+ * emits a `GIT binary patch` section carrying the literal/delta payload —
+ * that body can be replayed by `git apply`. Plain `git diff` emits only the
+ * informational `Binary files a/x and b/x differ`, which records THAT the
+ * bytes changed and carries none of them.
+ *
+ * The stub form is dangerous rather than merely lossy because it still
+ * carries a correct `index <old>..<new>` line. Every identity-shaped check in
+ * the codebase — worktree classification, foreign-drift detection — keys on
+ * that hash, matches it against the live file, and concludes the patch is
+ * backed. So a queue can hold a patch that provably cannot rebuild its own
+ * file while every gate reports green, and the loss surfaces only at the next
+ * clean-room apply. This rule is the one check that reads the body itself and
+ * fails closed, whichever command wrote it.
+ *
+ * Body-only by design: it needs no engine checkout, so it runs anywhere the
+ * queue context is available and never pulls an engine dependency into the
+ * cross-patch lint graph.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * The slice of a queue entry this rule reads. Declared structurally rather
+ * than importing `PatchQueueEntry` from `patch-lint-cross.ts`, which imports
+ * this module back — the local shape keeps the dependency edge one-way and
+ * `dpdm` clean, matching `patch-lint-module-registration.ts`.
+ */
+interface BinaryBodyQueueEntry {
+    filename: string;
+    diff: string;
+}
+/** Queue view accepted by {@link lintPatchQueueBinaryBodies}. */
+interface BinaryBodyQueueContext {
+    entries: readonly BinaryBodyQueueEntry[];
+}
+/** Lint check identifier emitted by {@link lintPatchQueueBinaryBodies}. */
+export declare const BINARY_BODY_CHECK = "binary-body-not-reconstructable";
+/**
+ * Flags every binary diff section whose body carries no reconstructable
+ * payload.
+ *
+ * Deletions are exempt: a `deleted file mode` section needs no bytes to
+ * replay, so the informational form is complete for that case.
+ *
+ * @param ctx - Queue context (raw patch bodies in application order)
+ * @returns One error-severity issue per offending file per patch
+ */
+export declare function lintPatchQueueBinaryBodies(ctx: BinaryBodyQueueContext): PatchLintIssue[];
+export {};

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

@@ -0,0 +1,39 @@
+import { parseDiffSections } from './patch-parse.js';
+/** Lint check identifier emitted by {@link lintPatchQueueBinaryBodies}. */
+export const BINARY_BODY_CHECK = 'binary-body-not-reconstructable';
+/**
+ * Flags every binary diff section whose body carries no reconstructable
+ * payload.
+ *
+ * Deletions are exempt: a `deleted file mode` section needs no bytes to
+ * replay, so the informational form is complete for that case.
+ *
+ * @param ctx - Queue context (raw patch bodies in application order)
+ * @returns One error-severity issue per offending file per patch
+ */
+export function lintPatchQueueBinaryBodies(ctx) {
+    const issues = [];
+    for (const entry of ctx.entries) {
+        const seen = new Set();
+        for (const section of parseDiffSections(entry.diff)) {
+            if (!section.isBinary || section.hasBinaryDelta || section.isDeletedFile)
+                continue;
+            const file = section.targetPath;
+            if (seen.has(file))
+                continue;
+            seen.add(file);
+            issues.push({
+                file,
+                check: BINARY_BODY_CHECK,
+                patches: [entry.filename],
+                fingerprint: `${BINARY_BODY_CHECK}|${entry.filename}|${file}`,
+                message: `Binary file "${file}" is recorded in ${entry.filename} as "Binary files … differ", ` +
+                    'which carries no data and cannot recreate the file on apply. ' +
+                    `Re-export the patch from a tree where ${file} is present ` +
+                    `("fireforge re-export ${entry.filename}") so the body carries a GIT binary patch delta.`,
+                severity: 'error',
+            });
+        }
+    }
+    return issues;
+}

package/dist/src/core/{lint-cache.d.ts → patch-lint-cache.d.ts}

@@ -11,8 +11,8 @@ export interface PerPatchLintCacheEntry {
     /** Non-binary diff line count measured by the cached lint run. */
     lineCount: number;
     /**
-     * Sorted lint-ignore waiver ids in force when this entry was computed
-     *. A lookup presenting a different effective set misses.
+     * Sorted lint-ignore waiver ids in force when this entry was computed.
+     * A lookup presenting a different effective set misses.
      */
     lintIgnore: string[];
     updatedAt: string;
@@ -53,9 +53,9 @@ export interface CachedPerPatchLint {
 }
 /**
  * Returns the cached lint payload for a patch when the stored key still
- * matches AND the entry was computed under the same lint-ignore waiver set
- *. A waiver change makes a replayed verdict actively wrong, so
- * the waiver set is compared explicitly rather than trusted to the key.
+ * matches AND the entry was computed under the same lint-ignore waiver set.
+ * A waiver change makes a replayed verdict actively wrong, so the waiver set
+ * is compared explicitly rather than trusted to the key.
  */
 export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, lintIgnore?: Iterable<string>): CachedPerPatchLint | undefined;
 /** Stores the per-patch lint payload after a successful lint calculation. */