@hominis/fireforge 0.35.0 → 0.36.0

package/dist/src/core/git-status.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { warn } from '../utils/logger.js';
 import { ensureGit, git } from './git-base.js';
 /**
  * Parses NUL-delimited porcelain status output.
@@ -43,22 +45,51 @@ export async function getWorkingTreeStatus(repoDir) {
     await ensureGit();
     return parsePorcelainStatus(await git(['status', '--porcelain=v1', '-z'], repoDir));
 }
+/** Default per-directory cap for untracked-directory expansion. */
+const DEFAULT_MAX_UNTRACKED_FILES_PER_DIR = 5000;
+/**
+ * Resolves the per-directory expansion cap, honoring the same
+ * FIREFORGE_MAX_UNTRACKED_FILES override the status command documents.
+ */
+export function resolveMaxUntrackedFilesPerDir() {
+    const raw = process.env['FIREFORGE_MAX_UNTRACKED_FILES'];
+    if (raw === undefined || raw.length === 0)
+        return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        warn(`Ignoring FIREFORGE_MAX_UNTRACKED_FILES="${raw}" — expected a positive integer. Falling back to ${String(DEFAULT_MAX_UNTRACKED_FILES_PER_DIR)}.`);
+        return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
+    }
+    return parsed;
+}
 /**
  * Expands collapsed untracked directory entries into individual file entries.
  * Git status may report "?? dir/" instead of listing each file underneath.
+ *
+ * Expansion is capped per directory (FIREFORGE_MAX_UNTRACKED_FILES, default
+ * 5000) with a warning on overflow. The cap used to exist only in the
+ * status command's private expander; this shared one — used by reset,
+ * discard, verify, lint, export-all — was unbounded, so e.g. `reset
+ * --dry-run` after an interrupted download (unborn HEAD, the entire ~300k
+ * file tree untracked) enumerated and printed every file.
+ *
  * @param repoDir - Repository directory
  * @param entries - Parsed status entries
  * @returns Status entries with untracked directories expanded to individual files
  */
 export async function expandUntrackedDirectoryEntries(repoDir, entries) {
     const expanded = [];
+    const maxPerDir = resolveMaxUntrackedFilesPerDir();
     for (const entry of entries) {
         if (!entry.isUntracked || !entry.file.endsWith('/')) {
             expanded.push(entry);
             continue;
         }
         const individualFiles = await getUntrackedFilesInDir(repoDir, entry.file);
-        for (const file of individualFiles) {
+        if (individualFiles.length > maxPerDir) {
+            warn(`Untracked directory ${entry.file} contains ${String(individualFiles.length)} files — only the first ${String(maxPerDir)} are listed. Add a .gitignore entry or clean the directory.`);
+        }
+        for (const file of individualFiles.slice(0, maxPerDir)) {
             expanded.push({
                 status: '??',
                 indexStatus: '?',
@@ -125,4 +156,3 @@ export async function getDirtyFiles(repoDir, files) {
     const untracked = untrackedOutput.split('\n').filter((line) => line.trim().length > 0);
     return [...new Set([...tracked, ...untracked])].sort();
 }
-//# sourceMappingURL=git-status.js.map

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

@@ -53,12 +53,21 @@ export declare function applyPatch(patchPath: string, repoDir: string, options?:
  * Applies a patch idempotently using reverse-forward pattern.
  * First tries to reverse the patch (in case it's already applied),
  * then applies it forward.
+ *
  * @param patchPath - Path to the patch file
  * @param repoDir - Repository directory
- * @param options - Application options
+ * @param options.reject - Fall back to `git apply --reject`
+ * @param options.protectedFiles - Files that must NOT be reset to HEAD by
+ *   the recovery step. Callers applying a patch QUEUE pass the files
+ *   already touched by previously applied patches in the same run: two
+ *   overlapping patches (an `--allow-overlap` queue) share files, and the
+ *   blanket `checkout HEAD` used to wipe the earlier patch's changes from
+ *   the shared file before applying the later one — leaving the engine in
+ *   a hybrid state the summary never described.
  */
 export declare function applyPatchIdempotent(patchPath: string, repoDir: string, options?: {
     reject?: boolean;
+    protectedFiles?: ReadonlySet<string>;
 }): Promise<void>;
 /**
  * Reverses a previously applied patch.

package/dist/src/core/git.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { ExecTimeoutError } from '../errors/base.js';
 import { GitError, GitIndexingTimeoutError, GitIndexLockError, PatchApplyError, } from '../errors/git.js';
 import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
@@ -8,7 +9,7 @@ import { pathExists, pathExistsStrict, removeFile } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
-import { configureGitPerformance, ensureGit, git, GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, GIT_ADD_CHUNK_TIMEOUT_MS, GIT_ADD_TIMEOUT_MS, } from './git-base.js';
+import { chunkPathspecs, configureGitPerformance, ensureGit, git, GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, GIT_ADD_CHUNK_TIMEOUT_MS, GIT_ADD_TIMEOUT_MS, } from './git-base.js';
 import { getWorkingTreeStatus } from './git-status.js';
 // ── Functions that remain in this file ──
 /**
@@ -47,6 +48,11 @@ const GIT_ADD_ENV = { GIT_INDEX_THREADS: '0' };
  * detection here needs to recognise that shape too.
  */
 function isTimeoutError(error) {
+    // `exec` now rejects with a typed ExecTimeoutError when its `timeout`
+    // option fires (the raw AbortError check below is kept for defence in
+    // depth against other abort paths).
+    if (error instanceof ExecTimeoutError)
+        return true;
     if (error instanceof Error && error.name === 'AbortError')
         return true;
     if (!(error instanceof GitError))
@@ -410,9 +416,17 @@ export async function applyPatch(patchPath, repoDir, options = {}) {
  * Applies a patch idempotently using reverse-forward pattern.
  * First tries to reverse the patch (in case it's already applied),
  * then applies it forward.
+ *
  * @param patchPath - Path to the patch file
  * @param repoDir - Repository directory
- * @param options - Application options
+ * @param options.reject - Fall back to `git apply --reject`
+ * @param options.protectedFiles - Files that must NOT be reset to HEAD by
+ *   the recovery step. Callers applying a patch QUEUE pass the files
+ *   already touched by previously applied patches in the same run: two
+ *   overlapping patches (an `--allow-overlap` queue) share files, and the
+ *   blanket `checkout HEAD` used to wipe the earlier patch's changes from
+ *   the shared file before applying the later one — leaving the engine in
+ *   a hybrid state the summary never described.
  */
 export async function applyPatchIdempotent(patchPath, repoDir, options = {}) {
     await ensureGit();
@@ -428,15 +442,59 @@ export async function applyPatchIdempotent(patchPath, repoDir, options = {}) {
         const touchedFiles = listResult.stdout
             .split('\n')
             .map((line) => line.split('\t')[2])
-            .filter((f) => !!f);
+            .filter((f) => !!f)
+            .filter((f) => !(options.protectedFiles?.has(f) ?? false));
         if (touchedFiles.length > 0) {
-            // Restore only the files the patch touches
-            await exec('git', ['checkout', 'HEAD', '--', ...touchedFiles], { cwd: repoDir });
+            await restoreFilesToHead(repoDir, patchPath, touchedFiles);
         }
     }
     // Apply forward
     await applyPatch(patchPath, repoDir, options);
 }
+/**
+ * Restores `files` to their HEAD state, deleting files the patch would
+ * CREATE (present on disk from a partial apply but absent in HEAD — for
+ * those, `git checkout HEAD --` fails, and the historical code ignored
+ * that failure entirely, leaving stray files that made the subsequent
+ * forward apply die with "already exists" and no hint why).
+ *
+ * Every git invocation is chunked via {@link chunkPathspecs} so a very
+ * large patch cannot hit `E2BIG`, and every exit code is checked — a
+ * silent failed restore is precisely the confusing state this recovery
+ * step exists to prevent.
+ */
+async function restoreFilesToHead(repoDir, patchPath, files) {
+    // Partition into tracked-in-HEAD (restore via checkout) and absent-in-HEAD
+    // (patch-created leftovers: delete from the worktree).
+    const trackedInHead = new Set();
+    for (const chunk of chunkPathspecs(files)) {
+        const lsTree = await exec('git', ['ls-tree', '-r', '--name-only', 'HEAD', '--', ...chunk], {
+            cwd: repoDir,
+        });
+        if (lsTree.exitCode !== 0) {
+            throw new PatchApplyError(patchPath, new Error(`git ls-tree failed while preparing recovery: ${lsTree.stderr.trim()}`));
+        }
+        for (const line of lsTree.stdout.split('\n')) {
+            if (line.length > 0)
+                trackedInHead.add(line);
+        }
+    }
+    const toCheckout = files.filter((f) => trackedInHead.has(f));
+    const toDelete = files.filter((f) => !trackedInHead.has(f));
+    for (const chunk of chunkPathspecs(toCheckout)) {
+        const checkout = await exec('git', ['checkout', 'HEAD', '--', ...chunk], { cwd: repoDir });
+        if (checkout.exitCode !== 0) {
+            throw new PatchApplyError(patchPath, new Error(`Could not restore patch-touched files to HEAD before applying: ${checkout.stderr.trim()}`));
+        }
+    }
+    for (const file of toDelete) {
+        const target = join(repoDir, file);
+        if (await pathExists(target)) {
+            await removeFile(target);
+            verbose(`Removed stray patch-created file before apply: ${file}`);
+        }
+    }
+}
 /**
  * Reverses a previously applied patch.
  * @param patchPath - Path to the patch file
@@ -524,4 +582,3 @@ export async function getStatusWithCodes(repoDir) {
         file: entry.file,
     }));
 }
-//# sourceMappingURL=git.js.map

package/dist/src/core/license-headers.js

@@ -193,4 +193,3 @@ export async function addLicenseHeaderToFile(filePath, license, style) {
     await writeText(filePath, header + '\n' + content);
     return true;
 }
-//# sourceMappingURL=license-headers.js.map

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

@@ -174,4 +174,3 @@ export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues) {
         updatedAt: new Date().toISOString(),
     };
 }
-//# sourceMappingURL=lint-cache.js.map

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

@@ -41,4 +41,3 @@ export function computeProjectedLintRegressions(baseline, projected) {
     }
     return regressions;
 }
-//# sourceMappingURL=lint-projection.js.map

package/dist/src/core/mach-build-artifacts.js

@@ -285,4 +285,3 @@ export async function attemptMozinfoRewrite(engineDir, objDir) {
         ...(newMozconfig ? { newMozconfig } : {}),
     };
 }
-//# sourceMappingURL=mach-build-artifacts.js.map

package/dist/src/core/mach-error-hints.js

@@ -120,4 +120,3 @@ export function explainMachError(stderr) {
     }
     return hits;
 }
-//# sourceMappingURL=mach-error-hints.js.map

package/dist/src/core/mach-mozconfig.js

@@ -113,4 +113,3 @@ export async function generateMozconfig(configsDir, engineDir, config) {
     // the single source of truth for both the render and the sanity-check.
     await assertBrandingMozconfigAgreement(engineDir, outputPath, config);
 }
-//# sourceMappingURL=mach-mozconfig.js.map

package/dist/src/core/mach-python.js

@@ -123,4 +123,3 @@ export async function getPython(engineDir) {
     }
     return pythonCache.python;
 }
-//# sourceMappingURL=mach-python.js.map

package/dist/src/core/mach-resource-shim.js

@@ -549,4 +549,3 @@ export async function installMachResourceGuard(engineDir) {
     const env = machResourceShimEnv(await ensureSitecustomizeFallback());
     return { env, sitePackagesDirs };
 }
-//# sourceMappingURL=mach-resource-shim.js.map

package/dist/src/core/mach.js

@@ -392,4 +392,3 @@ export async function mochitestWithOutput(engineDir, testPaths = [], args = [],
         env: { ...guard.env, ...env },
     });
 }
-//# sourceMappingURL=mach.js.map

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

@@ -118,4 +118,3 @@ export function findAlphabeticalMozBuildPosition(tokens, newKey) {
     }
     return { insertIndex: insertLineIndex, previousEntry };
 }
-//# sourceMappingURL=manifest-helpers.js.map

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

@@ -64,4 +64,3 @@ export async function registerToolkitWidget(engineDir, tagName, fileName, dryRun
     }
     return { manifest, entry, previousEntry, skipped: false };
 }
-//# sourceMappingURL=manifest-register.js.map

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

@@ -250,4 +250,3 @@ export async function registerFile(root, filePath, dryRun = false, after, option
     }
     throw new InvalidArgumentError(buildUnknownPatternMessage(normalizedPath, config.binaryName), 'path');
 }
-//# sourceMappingURL=manifest-rules.js.map

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

@@ -109,4 +109,3 @@ export function tokenizeMozBuildList(lines, listPattern) {
         return null;
     return { tokens, startLine, endLine };
 }
-//# sourceMappingURL=manifest-tokenizers.js.map

package/dist/src/core/marionette-port.d.ts

@@ -48,6 +48,14 @@ export declare function probeMarionettePort(port?: number): Promise<MarionettePo
 export declare function assertMarionettePortAvailable(port?: number, options?: {
     binaryName?: string;
 }): Promise<void>;
+/**
+ * Ensures the Marionette port is usable, optionally terminating a stale
+ * Firefox-family browser holder first. Unrelated listeners still fail.
+ */
+export declare function ensureMarionettePortAvailable(port?: number, options?: {
+    binaryName?: string;
+    killStaleBrowser?: boolean;
+}): Promise<void>;
 /**
  * Extracts a `--marionette-port=N` (or `--marionette-port N`) argument from
  * a list of forwarded mach args, if present. Used so an operator passing the

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

@@ -56,7 +56,7 @@ const BROWSER_BASENAMES = new Set([
  * so a fork that ships under a custom name (e.g.
  * `mybrowser-nightly`) is still recognised as a browser.
  */
-function isBrowserHolder(holder, binaryName) {
+function isBrowserMarionettePortHolder(holder, binaryName) {
     if (/\s-marionette(?:\s|$)/.test(holder.commandLine)) {
         return true;
     }
@@ -195,7 +195,7 @@ export async function assertMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
     if (!probe.inUse || !probe.holder)
         return;
     const holder = probe.holder;
-    if (isBrowserHolder(holder, options.binaryName)) {
+    if (isBrowserMarionettePortHolder(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`;
@@ -212,6 +212,38 @@ export async function assertMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
     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.`);
 }
+/**
+ * Ensures the Marionette port is usable, optionally terminating a stale
+ * Firefox-family browser holder first. Unrelated listeners still fail.
+ */
+export async function ensureMarionettePortAvailable(port = DEFAULT_MARIONETTE_PORT, options = {}) {
+    const probe = await probeMarionettePort(port);
+    if (!probe.inUse || !probe.holder)
+        return;
+    const holder = probe.holder;
+    const isBrowser = isBrowserMarionettePortHolder(holder, options.binaryName);
+    if (!options.killStaleBrowser || !isBrowser) {
+        await assertMarionettePortAvailable(port, options);
+        return;
+    }
+    try {
+        if (process.platform === 'win32') {
+            await exec('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `Stop-Process -Id ${holder.pid} -Force`,
+            ]);
+        }
+        else {
+            process.kill(holder.pid, 'SIGTERM');
+        }
+    }
+    catch (error) {
+        throw new GeneralError(`Marionette port ${port} is held by stale browser ${holder.command} (PID ${holder.pid}), ` +
+            `but FireForge could not terminate it: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 /**
  * Extracts a `--marionette-port=N` (or `--marionette-port N`) argument from
  * a list of forwarded mach args, if present. Used so an operator passing the
@@ -350,4 +382,3 @@ export function isMarionetteFlavor(testPaths, machArgs) {
     }
     return false;
 }
-//# sourceMappingURL=marionette-port.js.map

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

@@ -307,4 +307,3 @@ export function formatMarionettePreflightLine(result) {
     const status = result.ok ? 'PASS' : 'FAIL';
     return `Marionette preflight: ${status} (${result.durationMs}ms) — ${result.detail}`;
 }
-//# sourceMappingURL=marionette-preflight.js.map

package/dist/src/core/markdown-table.js

@@ -263,4 +263,3 @@ export function updateCellByKey(table, keyColumn, keyValue, targetColumn, newVal
     }
     return false;
 }
-//# sourceMappingURL=markdown-table.js.map

package/dist/src/core/ownership-table.js

@@ -1,4 +1,5 @@
 import { info } from '../utils/logger.js';
+import { buildPatchClaims } from './status-classify.js';
 /**
  * Builds the flat ownership table from the manifest, worktree status, and
  * the duplicate-new-file-creation map produced by cross-patch lint.
@@ -29,14 +30,7 @@ import { info } from '../utils/logger.js';
  *   paths with a `.length > 1` owner list become duplicate-create conflicts
  */
 export function buildOwnershipTable(manifestPatches, worktreeFiles, newFileCreatorsByPath, classifications = new Map()) {
-    const ownersByPath = new Map();
-    for (const patch of manifestPatches) {
-        for (const file of patch.filesAffected) {
-            const existing = ownersByPath.get(file) ?? [];
-            existing.push(patch.filename);
-            ownersByPath.set(file, existing);
-        }
-    }
+    const ownersByPath = buildPatchClaims(manifestPatches);
     // Merge duplicate-new-file-creation findings. The structured helper
     // returns all new-file paths, so we filter to the ones with more
     // than one creator. Paths are added to the table even when no patch
@@ -165,4 +159,3 @@ export function renderOwnershipTable(rows) {
         info(`| ${pad(row.path, pathWidth)} | ${pad(ownerCell, ownerWidth)} | ${pad(stateCell, stateWidth)} |`);
     }
 }
-//# sourceMappingURL=ownership-table.js.map

package/dist/src/core/parser-fallback.js

@@ -40,4 +40,3 @@ export function withParserFallback(primary, fallback, context, rethrowIf) {
         return { value: fallback(), usedFallback: true, fallbackReason: reason };
     }
 }
-//# sourceMappingURL=parser-fallback.js.map

package/dist/src/core/patch-apply-fuzz.d.ts

@@ -1,14 +1,27 @@
 /**
- * Fuzzy patch application with escalating fuzz factors.
+ * Fuzz-like patch application with escalating context reduction.
  *
- * Tries an exact `git apply` first, then retries with increasing `--fuzz=N`
- * values.  If all fuzz levels fail, falls through to `git apply --reject`
- * so the user gets `.rej` files for manual resolution.
+ * Tries an exact `git apply` first, then retries with git's real
+ * drift-tolerance knob: `-C<n>` (reduced context matching). `git apply`
+ * has NO `--fuzz` option — that flag belongs to GNU `patch(1)`. The
+ * original implementation passed `--fuzz=N`, which git rejects with a
+ * usage error (exit 129) that the escalation loop swallowed, so every
+ * "fuzzy" attempt silently failed and patches that would have applied
+ * with context drift were reported as hard conflicts (2026-07-05 review,
+ * finding H1; verified against git 2.50). If all context-reduction levels
+ * fail, falls through to `git apply --reject` so the user gets `.rej`
+ * files for manual resolution.
+ *
+ * Semantics note: GNU fuzz *fuzzily matches* context; `-C<n>` *ignores*
+ * outer context lines instead. Step k maps to `-C(3-k)` (git's default
+ * context width is 3), so the final step `-C0` matches on line positions
+ * and -/+ content alone — the rough analogue of GNU `--fuzz=3` on a
+ * 3-context patch.
  */
 export interface FuzzyApplyResult {
     /** Whether the patch was applied successfully. */
     success: boolean;
-    /** Fuzz factor that succeeded (0 = exact match). */
+    /** Context-reduction steps taken (0 = exact match, k = applied with `-C(3-k)`). */
     fuzzFactor: number;
     /** Error description when `success` is false. */
     error?: string;
@@ -16,14 +29,19 @@ export interface FuzzyApplyResult {
     rejectFiles?: string[];
 }
 /**
- * Attempts to apply a patch with escalating fuzz factors.
+ * Attempts to apply a patch with escalating context reduction.
  *
- * 1. `git apply --check` at fuzz 0 … maxFuzz
- * 2. `git apply --fuzz=N` at the first passing level
+ * 1. `git apply --check` exact, then with `-C2`, `-C1`, `-C0`
+ * 2. `git apply` (same flags) at the first passing level
  * 3. Fall through to `git apply --reject` if nothing succeeds
  *
  * @param patchPath - Absolute path to the `.patch` file
  * @param engineDir - Working directory (engine/)
- * @param maxFuzz   - Maximum fuzz factor to try (default 3)
+ * @param maxFuzz   - Maximum context-reduction steps to try (default 3,
+ *   0 = exact only). Values above 3 are capped: git cannot reduce below
+ *   `-C0`.
+ * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer —
+ *   a NaN or negative value would silently skip every apply attempt
+ *   (including the exact-match one) and fall straight through to `--reject`
  */
 export declare function applyPatchWithFuzz(patchPath: string, engineDir: string, maxFuzz?: number): Promise<FuzzyApplyResult>;

package/dist/src/core/patch-apply-fuzz.js

@@ -1,70 +1,107 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Fuzzy patch application with escalating fuzz factors.
+ * Fuzz-like patch application with escalating context reduction.
  *
- * Tries an exact `git apply` first, then retries with increasing `--fuzz=N`
- * values.  If all fuzz levels fail, falls through to `git apply --reject`
- * so the user gets `.rej` files for manual resolution.
+ * Tries an exact `git apply` first, then retries with git's real
+ * drift-tolerance knob: `-C<n>` (reduced context matching). `git apply`
+ * has NO `--fuzz` option — that flag belongs to GNU `patch(1)`. The
+ * original implementation passed `--fuzz=N`, which git rejects with a
+ * usage error (exit 129) that the escalation loop swallowed, so every
+ * "fuzzy" attempt silently failed and patches that would have applied
+ * with context drift were reported as hard conflicts (2026-07-05 review,
+ * finding H1; verified against git 2.50). If all context-reduction levels
+ * fail, falls through to `git apply --reject` so the user gets `.rej`
+ * files for manual resolution.
+ *
+ * Semantics note: GNU fuzz *fuzzily matches* context; `-C<n>` *ignores*
+ * outer context lines instead. Step k maps to `-C(3-k)` (git's default
+ * context width is 3), so the final step `-C0` matches on line positions
+ * and -/+ content alone — the rough analogue of GNU `--fuzz=3` on a
+ * 3-context patch.
  */
+import { InvalidArgumentError } from '../errors/base.js';
 import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { ensureGit } from './git-base.js';
+/** Git's default diff context width — the ceiling for reduction steps. */
+const GIT_DEFAULT_CONTEXT = 3;
 // ── Implementation ──
 /**
- * Attempts to apply a patch with escalating fuzz factors.
+ * Attempts to apply a patch with escalating context reduction.
  *
- * 1. `git apply --check` at fuzz 0 … maxFuzz
- * 2. `git apply --fuzz=N` at the first passing level
+ * 1. `git apply --check` exact, then with `-C2`, `-C1`, `-C0`
+ * 2. `git apply` (same flags) at the first passing level
  * 3. Fall through to `git apply --reject` if nothing succeeds
  *
  * @param patchPath - Absolute path to the `.patch` file
  * @param engineDir - Working directory (engine/)
- * @param maxFuzz   - Maximum fuzz factor to try (default 3)
+ * @param maxFuzz   - Maximum context-reduction steps to try (default 3,
+ *   0 = exact only). Values above 3 are capped: git cannot reduce below
+ *   `-C0`.
+ * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer —
+ *   a NaN or negative value would silently skip every apply attempt
+ *   (including the exact-match one) and fall straight through to `--reject`
  */
 export async function applyPatchWithFuzz(patchPath, engineDir, maxFuzz = 3) {
+    if (!Number.isInteger(maxFuzz) || maxFuzz < 0) {
+        throw new InvalidArgumentError(`maxFuzz must be a non-negative integer, got ${String(maxFuzz)}.`, 'maxFuzz');
+    }
     await ensureGit();
-    // Try exact match first, then escalate
-    for (let fuzz = 0; fuzz <= maxFuzz; fuzz++) {
-        const fuzzArgs = fuzz > 0 ? [`--fuzz=${fuzz}`] : [];
-        const check = await exec('git', ['apply', '--check', ...fuzzArgs, '--', patchPath], {
+    // Try exact match first, then escalate context reduction.
+    const maxSteps = Math.min(maxFuzz, GIT_DEFAULT_CONTEXT);
+    for (let step = 0; step <= maxSteps; step++) {
+        const contextArgs = step > 0 ? [`-C${String(GIT_DEFAULT_CONTEXT - step)}`] : [];
+        const check = await exec('git', ['apply', '--check', ...contextArgs, '--', patchPath], {
             cwd: engineDir,
         });
         if (check.exitCode === 0) {
             // --check passed: apply for real
-            const apply = await exec('git', ['apply', ...fuzzArgs, '--', patchPath], {
+            const apply = await exec('git', ['apply', ...contextArgs, '--', patchPath], {
                 cwd: engineDir,
             });
             if (apply.exitCode === 0) {
-                if (fuzz > 0) {
-                    verbose(`Patch applied with fuzz=${fuzz}: ${patchPath}`);
+                if (step > 0) {
+                    verbose(`Patch applied with reduced context (-C${String(GIT_DEFAULT_CONTEXT - step)}): ${patchPath}`);
                 }
-                return { success: true, fuzzFactor: fuzz };
+                return { success: true, fuzzFactor: step };
             }
-            // Unlikely: --check passed but apply failed; fall through to next fuzz
-            verbose(`git apply fuzz=${fuzz} --check passed but apply failed: ${apply.stderr.trim()}`);
+            // Unlikely: --check passed but apply failed; fall through to next step
+            verbose(`git apply -C${String(GIT_DEFAULT_CONTEXT - step)} --check passed but apply failed: ${apply.stderr.trim()}`);
         }
     }
-    // All fuzz levels failed → generate .rej files for manual resolution
+    // All context-reduction levels failed → generate .rej files for manual resolution
     const rejectResult = await exec('git', ['apply', '--reject', '--', patchPath], {
         cwd: engineDir,
     });
-    const errorMessage = rejectResult.stderr.trim() || 'All fuzz levels failed';
-    // Extract .rej file paths from stderr
-    const rejectFiles = [];
-    for (const line of rejectResult.stderr.split('\n')) {
-        const match = line.match(/Applying patch .* with (\d+) reject/);
-        if (match)
-            continue;
-        const rejMatch = line.match(/Rejected hunk.*to (.+\.rej)/);
-        if (rejMatch?.[1]) {
-            rejectFiles.push(rejMatch[1]);
-        }
-    }
+    const errorMessage = rejectResult.stderr.trim() || 'All context-reduction levels failed';
     return {
         success: false,
-        fuzzFactor: maxFuzz,
+        fuzzFactor: maxSteps,
         error: errorMessage,
-        rejectFiles,
+        rejectFiles: extractRejectFiles(rejectResult.stderr),
     };
 }
-//# sourceMappingURL=patch-apply-fuzz.js.map
+/**
+ * Extracts `.rej` file paths from `git apply --reject` stderr.
+ *
+ * Git's actual output shape (verified against git 2.50):
+ *
+ *   Applying patch f.txt with 1 reject...
+ *   Rejected hunk #1.
+ *
+ * The reject file is `<file>.rej` next to the target. The previous regex
+ * (`Rejected hunk.*to (.+\.rej)`) targeted GNU `patch(1)`'s "saving
+ * rejects to file X.rej" phrasing, which git never prints — so
+ * `rejectFiles` was always empty and the conflict-summary ".rej files
+ * created" hint never fired.
+ */
+function extractRejectFiles(stderr) {
+    const rejectFiles = [];
+    for (const line of stderr.split('\n')) {
+        const match = /^Applying patch (.+) with \d+ rejects?\.\.\./.exec(line);
+        if (match?.[1]) {
+            rejectFiles.push(`${match[1]}.rej`);
+        }
+    }
+    return rejectFiles;
+}

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

@@ -40,6 +40,28 @@ export interface ApplyPatchesOptions {
      */
     untilFilename?: string | undefined;
 }
+/**
+ * Decides whether a patch filename matches an `--until` identifier.
+ *
+ * The identifier is one of three shapes and the three shapes must stay
+ * disjoint so the operator can reason about which patch they picked:
+ *
+ *   1. **Exact filename** — `005-foo.patch`. Matches only that filename.
+ *   2. **Filename without extension** — `005-foo`. Matches `005-foo.patch`.
+ *   3. **Bare numeric ordinal** — `5` or `005`. Matches the patch whose
+ *      order prefix parses to the same integer (so `5` and `005` both
+ *      match `005-foo.patch`, and `05` matches too because parseInt
+ *      normalizes leading zeros).
+ *
+ * A purely-numeric identifier is treated **only** as an ordinal: it does
+ * not also match a filename that happens to literally equal the digits.
+ * That would require a patch literally named `5` or `005` — which would
+ * collide with the filename prefix anyway — and we prefer the explicit
+ * ordinal interpretation. The earlier form's `patchFilename === needle`
+ * short-circuit was kept behind the numeric gate so the match stays
+ * single-meaning per identifier.
+ */
+export declare function matchesUntilFilename(patchFilename: string, needle: string): boolean;
 /**
  * Enhanced patch application with continue mode.
  * When continueOnFailure is false, rolls back all previously applied patches
@@ -58,3 +80,11 @@ export declare function applyPatchesWithContinue(patchesDir: string, engineDir:
  * @returns Content after all patches applied, or null if file doesn't exist
  */
 export declare function computePatchedContent(patchesDir: string, engineDir: string, filePath: string): Promise<string | null>;
+/**
+ * Builds a batched variant of {@link computePatchedContent} that loads the
+ * manifest and discovers patch files ONCE for many lookups. The per-call
+ * function re-runs `loadPatchesManifest` + `discoverPatches` for every
+ * file — O(dirtyFiles × patches) redundant IO when classifying a broad
+ * engine edit session during `import`.
+ */
+export declare function createPatchedContentComputer(patchesDir: string, engineDir: string): Promise<(filePath: string) => Promise<string | null>>;