@hominis/fireforge 0.47.0 → 0.48.0

package/dist/src/core/harness-orphans.js

@@ -22,10 +22,15 @@
  *    for the same reason. FireForge has no business reporting, let alone
  *    terminating, a process it cannot attribute to the harness.
  *
- * `--reap-orphans` opts into termination. Without it the census is
- * report-only, exactly like the `Orphaned harness workers` doctor check
- * (which covers a different shape: reparented Python multiprocessing
- * workers, matched on PPID 1 and accumulated CPU time).
+ * `--reap-orphans` (or `test.reapOrphans: "reap"` in `fireforge.json`) opts
+ * into termination. Without it the census is report-only, exactly like the
+ * `Orphaned harness workers` doctor check (which covers a different shape:
+ * reparented Python multiprocessing workers, matched on PPID 1 and
+ * accumulated CPU time).
+ *
+ * The anchoring and termination primitives are exported for the teardown
+ * reaper in `harness-helper-pids.ts`, which applies the same objdir rule to
+ * the helpers THIS run launched, after mach has exited.
  */
 import { toError } from '../utils/errors.js';
 import { info, verbose, warn } from '../utils/logger.js';
@@ -33,42 +38,91 @@ import { exec } from '../utils/process.js';
 import { parsePsDuration } from '../utils/ps-duration.js';
 import { sleep } from '../utils/sleep.js';
 /**
- * Harness helper executables/scripts. Every one of these is started by the
- * mochitest/xpcshell harness and is expected to die with it. None of them
- * is a thing a developer runs by hand.
+ * Harness helper binaries, matched on the executable's basename. Every one
+ * of these is started by the mochitest/xpcshell harness and is expected to
+ * die with it. None of them is a thing a developer runs by hand.
+ */
+const HELPER_BINARY = /^(?:xpcshell|ssltunnel|http3server|moz-http2)(?:\.exe)?$/;
+/** Interpreters the harness runs its helper scripts under. */
+const HELPER_INTERPRETER = /^(?:python[\d.]*|Python|node)(?:\.exe)?$/;
+/** Harness helper scripts, matched on the interpreter's script argument. */
+const HELPER_SCRIPT = /(?:^|[/\\])(?:pywebsocket\w*\.py|websocket_server\.py|websocketprocessbridge\.py|moz-http2\.js|http2_server\.js|httpd\.js|server\.js|runtests\.py|runxpcshelltests\.py)$/;
+function basename(token) {
+    const cut = Math.max(token.lastIndexOf('/'), token.lastIndexOf('\\'));
+    return cut === -1 ? token : token.slice(cut + 1);
+}
+/**
+ * True when `command` IS a harness helper: its executable is a helper
+ * binary, or an interpreter whose first argument is a helper script.
+ *
+ * Structural on purpose. An earlier version matched the helper names
+ * anywhere in the command line, which is right for the httpd (`xpcshell -g
+ * … -f …/server.js`) and wrong for everything that merely mentions such a
+ * path: an editor opened on `server.js`, a shell whose command text quotes
+ * it, a `grep` over the objdir. Report-only, that printed a misleading
+ * `kill`; under the reap posture it terminated the operator's shell.
  */
-const HARNESS_HELPER_PATTERN = /\b(?:xpcshell|pywebsocket\w*|websocket_server\.py|ssltunnel|moz-http2|http2_server|httpd\.js|server\.js|runtests\.py|runxpcshelltests\.py)\b/;
+export function matchesHarnessHelper(command) {
+    const [exe, first] = command.trim().split(/\s+/);
+    if (exe === undefined)
+        return false;
+    if (HELPER_BINARY.test(basename(exe)))
+        return true;
+    if (first === undefined || !HELPER_INTERPRETER.test(basename(exe)))
+        return false;
+    return HELPER_SCRIPT.test(first);
+}
 /** Objdir provenance: an explicit objdir path, a `obj-…` path segment, or `_tests/`. */
-function isObjdirAnchored(command, objDir) {
+export function isObjdirAnchored(command, objDir) {
     if (objDir !== undefined && objDir.length > 0 && command.includes(objDir))
         return true;
     if (/[/\\]obj-[^/\\\s]*[/\\]/.test(command))
         return true;
     return /[/\\]_tests[/\\]/.test(command);
 }
+/** Pids of `selfPid` and every ancestor of it, as far as the listing reaches. */
+function ancestorsOf(rows, selfPid) {
+    const parentOf = new Map(rows.map((r) => [r.pid, r.ppid]));
+    const chain = new Set();
+    let cursor = selfPid;
+    while (cursor !== undefined && cursor > 0 && !chain.has(cursor)) {
+        chain.add(cursor);
+        cursor = parentOf.get(cursor);
+    }
+    return chain;
+}
 /**
  * Scans `ps -axo pid=,ppid=,etime=,command=` output for surviving harness
  * helpers. Pure, so it is fixture-testable without spawning anything.
  *
+ * FireForge's own process, its direct children and its ancestors are never
+ * candidates: the terminal shell FireForge runs under can carry the helper
+ * paths in its own command text, and must never be offered for a kill.
+ *
  * @param psOutput - Raw `ps` output
  * @param objDir - Absolute objdir of this project, when known. Widens the
  *   provenance test beyond the generic `obj-…` path segment
- * @param selfPid - This process's pid, excluded so FireForge cannot report
- *   itself
+ * @param selfPid - This process's pid
  */
 export function findOrphanedHarnessProcesses(psOutput, objDir, selfPid = process.pid) {
-    const found = [];
+    const rows = [];
     for (const line of psOutput.split('\n')) {
         const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/.exec(line);
         if (!match)
             continue;
-        const pid = Number(match[1]);
-        const ppid = Number(match[2]);
-        const elapsed = match[3] ?? '';
-        const command = (match[4] ?? '').trim();
-        if (pid === selfPid || ppid === selfPid)
+        rows.push({
+            pid: Number(match[1]),
+            ppid: Number(match[2]),
+            elapsed: match[3] ?? '',
+            command: (match[4] ?? '').trim(),
+        });
+    }
+    const excluded = ancestorsOf(rows, selfPid);
+    const found = [];
+    for (const { pid, ppid, elapsed, command } of rows) {
+        if (excluded.has(pid) || ppid === selfPid)
             continue;
-        if (!HARNESS_HELPER_PATTERN.test(command))
+        if (!matchesHarnessHelper(command))
             continue;
         if (!isObjdirAnchored(command, objDir))
             continue;
@@ -85,6 +139,8 @@ export function findOrphanedHarnessProcesses(psOutput, objDir, selfPid = process
 }
 /** Grace period between SIGTERM and SIGKILL when reaping. */
 const REAP_GRACE_MS = 500;
+/** Wait after SIGKILL before the final liveness probe, so the parent can collect the exit. */
+const KILL_SETTLE_MS = 200;
 /** Longest command excerpt carried into the report line. */
 const COMMAND_EXCERPT_LIMIT = 160;
 /**
@@ -102,7 +158,8 @@ export function formatOrphanReport(orphans) {
         `it):\n${rows}\n` +
         `Survivors like these slow every later run without appearing anywhere in its output — a ` +
         `three-second suite taking minutes of wall clock is the usual symptom. Terminate them with ` +
-        `"kill ${pids}", or re-run with --reap-orphans to have FireForge do it.`);
+        `"kill ${pids}", re-run with --reap-orphans, or set test.reapOrphans to "reap" in ` +
+        `fireforge.json to have FireForge do it at every preflight.`);
 }
 /** Thin exec wrapper for the process listing (tests mock `exec` instead). */
 async function listSystemProcesses() {
@@ -125,63 +182,87 @@ async function listSystemProcesses() {
  * @param objDir - Absolute objdir of this project, when known
  * @param options - `reap` terminates each recognized survivor (SIGTERM,
  *   then SIGKILL for anything that stays)
- * @returns The census, empty when nothing was found or nothing could be probed
+ * @returns The census (empty when nothing was found or nothing could be
+ *   probed) and how many of them are confirmed gone after reaping (0 in
+ *   report-only mode)
  */
 export async function reportOrphanedHarnessProcesses(objDir, options = {}) {
     if (process.platform === 'win32')
-        return [];
+        return { orphans: [], reaped: 0 };
     let psOutput;
     try {
         psOutput = await listSystemProcesses();
     }
     catch (error) {
         verbose(`Orphan preflight: could not scan processes (${toError(error).message}); skipping.`);
-        return [];
+        return { orphans: [], reaped: 0 };
     }
     const orphans = findOrphanedHarnessProcesses(psOutput, objDir);
     if (orphans.length === 0) {
         verbose('Orphan preflight: no surviving harness helper processes.');
-        return [];
+        return { orphans: [], reaped: 0 };
     }
     warn(formatOrphanReport(orphans));
-    if (options.reap === true) {
-        await reapOrphanedHarnessProcesses(orphans);
+    const reaped = options.reap === true ? await terminateHarnessProcesses(orphans, '--reap-orphans') : 0;
+    return { orphans, reaped };
+}
+/** Liveness probe: `kill(pid, 0)` throws for a pid that is gone. */
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
     }
-    return orphans;
 }
 /**
- * Terminates each census entry: SIGTERM first, then SIGKILL for anything
- * still alive. Failures are reported, never thrown. A process that exited
- * between the census and the signal is the common case rather than an error.
+ * Terminates each entry: SIGTERM first, then SIGKILL for anything still
+ * alive after the grace period. Failures are reported, never thrown. A
+ * process that exited between the listing and the signal is the common case
+ * rather than an error.
+ *
+ * @param targets - Processes to terminate, already attributed to the harness
+ *   by the caller (objdir anchor rule)
+ * @param label - Prefix for the log lines, naming which path is reaping
+ *   (`--reap-orphans` at preflight, `teardown` after mach exits)
+ * @returns How many targets are confirmed gone afterwards
  */
-async function reapOrphanedHarnessProcesses(orphans) {
-    for (const orphan of orphans) {
+export async function terminateHarnessProcesses(targets, label) {
+    let reaped = 0;
+    for (const target of targets) {
         try {
-            process.kill(orphan.pid, 'SIGTERM');
+            process.kill(target.pid, 'SIGTERM');
         }
         catch (error) {
-            verbose(`--reap-orphans: SIGTERM to ${orphan.pid} failed (${toError(error).message}).`);
+            verbose(`${label}: SIGTERM to ${target.pid} failed (${toError(error).message}).`);
             continue;
         }
         // Grace period before escalating: the httpd shape in the field
         // incident ignored SIGTERM while spinning, but an ordinary helper exits
         // promptly and must not be SIGKILLed for being slow by a millisecond.
         await sleep(REAP_GRACE_MS);
-        let alive = true;
-        try {
-            process.kill(orphan.pid, 0);
-        }
-        catch {
-            alive = false;
-        }
-        if (alive) {
+        if (isPidAlive(target.pid)) {
             try {
-                process.kill(orphan.pid, 'SIGKILL');
+                process.kill(target.pid, 'SIGKILL');
             }
             catch (error) {
-                verbose(`--reap-orphans: SIGKILL to ${orphan.pid} failed (${toError(error).message}).`);
+                verbose(`${label}: SIGKILL to ${target.pid} failed (${toError(error).message}).`);
             }
+            // A killed process answers kill(0) until its parent (launchd, for a
+            // reparented survivor) has collected it, which takes a moment.
+            await sleep(KILL_SETTLE_MS);
+        }
+        // Counted only when the probe agrees: the verdict line will carry this
+        // number, and a SIGKILL that was sent is not the same as a process that
+        // is gone.
+        if (isPidAlive(target.pid)) {
+            warn(`${label}: PID ${target.pid} is still alive after SIGKILL; inspect it by hand.`);
+        }
+        else {
+            reaped += 1;
+            info(`${label}: terminated PID ${target.pid}.`);
         }
-        info(`--reap-orphans: terminated PID ${orphan.pid}.`);
     }
+    return reaped;
 }

package/dist/src/core/mach-mozconfig.d.ts

@@ -52,5 +52,6 @@ export declare function assertBrandingMozconfigAgreement(engineDir: string, mozc
  * @param configsDir - Path to the configs directory
  * @param engineDir - Path to the engine directory
  * @param config - FireForge configuration
+ * @returns Whether engine/mozconfig was rewritten (its content changed)
  */
-export declare function generateMozconfig(configsDir: string, engineDir: string, config: FireForgeConfig): Promise<void>;
+export declare function generateMozconfig(configsDir: string, engineDir: string, config: FireForgeConfig): Promise<boolean>;

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

@@ -114,6 +114,7 @@ export async function assertBrandingMozconfigAgreement(engineDir, mozconfigPath,
  * @param configsDir - Path to the configs directory
  * @param engineDir - Path to the engine directory
  * @param config - FireForge configuration
+ * @returns Whether engine/mozconfig was rewritten (its content changed)
  */
 export async function generateMozconfig(configsDir, engineDir, config) {
     const platform = getPlatform();
@@ -161,4 +162,5 @@ export async function generateMozconfig(configsDir, engineDir, config) {
     // write, before anything consumes mozconfig) keeps `generateMozconfig`
     // the single source of truth for both the render and the sanity-check.
     await assertBrandingMozconfigAgreement(engineDir, outputPath, config);
+    return wrote;
 }

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

@@ -37,6 +37,16 @@ export interface MachOptions {
      * layer's {@link ExecOptions.envUnset}.
      */
     envUnset?: readonly string[];
+    /**
+     * Observes every raw output chunk of a capture dispatch, on either stream,
+     * before the echo filter. The test dispatchers feed the harness helper-pid
+     * tracker from it. Capture-only, like `annotateKnownTeardownNoise`.
+     */
+    onOutputChunk?: (stream: 'stdout' | 'stderr', chunk: string) => void;
+    /** Exec-layer hook, see {@link ProcessGroupOptions.onProcessGroup}. Capture-only. */
+    onProcessGroup?: (pgid: number) => void;
+    /** Exec-layer hook, see {@link ProcessGroupOptions.postCloseSweep}. Capture-only. */
+    postCloseSweep?: () => Promise<void>;
 }
 /**
  * Result of running a mach command while capturing streamed output.
@@ -247,6 +257,12 @@ export interface MachTestSuiteOptions {
      * markers that quiet it. See {@link CODING_AGENT_ENV_MARKERS}.
      */
     fullOutput?: boolean | undefined;
+    /**
+     * Harness teardown hooks (`fireforge test`): the helper-pid tracker feed,
+     * the process-group announcement, and the post-close reap of the helpers
+     * the harness launched. See {@link MachOptions}.
+     */
+    teardown?: Pick<MachOptions, 'onOutputChunk' | 'onProcessGroup' | 'postCloseSweep'> | undefined;
 }
 /**
  * Runs one mach test command (`mach test` / `mach xpcshell-test` / `mach

package/dist/src/core/mach.js

@@ -96,7 +96,10 @@ export async function runMachCapture(args, engineDir, options = {}) {
         // storybook) runs as a process-group leader and is group-reaped on
         // exit/abort. See ExecOptions.processGroup.
         processGroup: true,
+        ...(options.onProcessGroup ? { onProcessGroup: options.onProcessGroup } : {}),
+        ...(options.postCloseSweep ? { postCloseSweep: options.postCloseSweep } : {}),
         onStdout: (data) => {
+            options.onOutputChunk?.('stdout', data);
             stdout += data;
             if (stdout.length > CAPTURE_TAIL_LIMIT) {
                 stdout = stdout.slice(-CAPTURE_TAIL_LIMIT);
@@ -110,6 +113,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
             process.stdout.write(stdoutFilter ? stdoutFilter.transform(data) : data);
         },
         onStderr: (data) => {
+            options.onOutputChunk?.('stderr', data);
             stderr += data;
             if (stderr.length > CAPTURE_TAIL_LIMIT) {
                 stderr = stderr.slice(-CAPTURE_TAIL_LIMIT);
@@ -407,12 +411,13 @@ function testVerbosityEnvUnset(fullOutput) {
  * @param options - Engine checkout, test paths, extra args, env, verbosity
  */
 export async function runMachTestSuite(kind, options) {
-    const { engineDir, testPaths = [], args = [], env, fullOutput } = options;
+    const { engineDir, testPaths = [], args = [], env, fullOutput, teardown } = options;
     const guard = await installMachResourceGuard(engineDir);
     const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture([kind, ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
         ...(envUnset ? { envUnset } : {}),
+        ...teardown,
         annotateKnownTeardownNoise: true,
     });
 }

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

@@ -154,9 +154,13 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         // (missing dylib, wrong CPU arch, corrupt profile) before the socket
         // poll swallows the full overall budget waiting for bytes that will
         // never come.
+        // Ref'd (sleep's default), like every wait in this probe: the browser is a
+        // detached child, so once it has exited nothing else holds the event
+        // loop, and an unref'd wait here let Node exit 0 mid-preflight with no
+        // `Marionette preflight:` line and no verdict at all.
         const settleDeadline = Math.min(spawnSettleMs, Math.max(0, timeoutMs - elapsed()));
         if (settleDeadline > 0) {
-            await sleep(settleDeadline, { unref: true });
+            await sleep(settleDeadline);
         }
         if (hasChildExited(spawnedChild)) {
             return fail('browser-spawns', `Browser process exited during spawn (exit code ${spawnedChild.exitCode}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
@@ -207,7 +211,9 @@ async function teardownPreflightChild(child, forwarder, closure, profileDir) {
         killProcessTree(child, 'SIGTERM', process.platform !== 'win32');
         // Small escalation: if the child doesn't honour SIGTERM quickly, SIGKILL
         // so we don't leave a ghost mach process around after a failed probe.
-        await sleep(500, { unref: true });
+        // Ref'd: an unref'd wait between a SIGTERM and its escalation lets Node
+        // exit mid-grace and skip the escalation.
+        await sleep(500);
         if (!hasChildExited(child)) {
             killProcessTree(child, 'SIGKILL', process.platform !== 'win32');
         }
@@ -255,7 +261,7 @@ async function waitForMarionetteSocket(port, connectFn, keepTrying) {
         if (result.ok) {
             return { ok: true };
         }
-        await sleep(400, { unref: true });
+        await sleep(400);
     }
     return { ok: false };
 }

package/dist/src/core/parent-exit-watchdog.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Detects the death of FireForge's own parent while a harness runs.
+ *
+ * A supervisor that SIGKILLs the process above `fireforge test` (the
+ * 2026-09-13 incident: a gate killed its `npm` step at the 15-minute bound)
+ * signals nothing below it. FireForge is not told; its stdout pipe merely
+ * breaks, and the broken-pipe handler swallows EPIPE on purpose so `| head`
+ * works. The mach tree it spawned as a separate process group keeps running
+ * under nobody's supervision, and the httpd in that tree spun at 100% CPU
+ * for hours.
+ *
+ * SIGKILL cannot be caught, but reparenting can be observed: once the parent
+ * is gone, `process.ppid` changes (to launchd/init, or to a subreaper). This
+ * watchdog polls for that while a dispatch is in flight and fires once. It
+ * does not decide what to do about it; the test command tears down the
+ * harness tree and ends the run.
+ *
+ * Off on Windows: `process.ppid` is not refreshed there after the parent
+ * exits, and there is no process group to signal in response anyway.
+ */
+/** Options for {@link startParentExitWatchdog}. */
+export interface ParentExitWatchdogOptions {
+    /** Probe interval, default {@link DEFAULT_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Called exactly once, the first time the parent is seen to be gone. */
+    onParentExit: (info: {
+        originalPpid: number;
+        currentPpid: number;
+    }) => void;
+    /**
+     * Reads the current parent pid; default `process.ppid`. Injectable because
+     * `process.ppid` cannot be stubbed on every Node line: redefining the
+     * property is honoured on Node 26 and silently ignored on Node 22, so a
+     * test that stubs it passes on one and never observes a reparent on the
+     * other.
+     */
+    readPpid?: () => number;
+}
+/** Handle for a running watchdog. */
+export interface ParentExitWatchdog {
+    /** Stops probing. Idempotent. A stopped watchdog never fires. */
+    stop(): void;
+}
+/**
+ * True once any watchdog in this process has seen the parent die. The
+ * dispatch loop reads it to end the run instead of classifying the killed
+ * harness as a crash and retrying it under a parent that no longer exists.
+ */
+export declare function parentExited(): boolean;
+/**
+ * Forgets an observed parent exit.
+ *
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
+ */
+export declare function resetParentExitForTests(): void;
+/**
+ * Starts probing `process.ppid`. The timer is unref'd so the watchdog can
+ * never be the thing keeping FireForge alive; while a child runs, the child
+ * does that.
+ */
+export declare function startParentExitWatchdog(options: ParentExitWatchdogOptions): ParentExitWatchdog;

package/dist/src/core/parent-exit-watchdog.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Detects the death of FireForge's own parent while a harness runs.
+ *
+ * A supervisor that SIGKILLs the process above `fireforge test` (the
+ * 2026-09-13 incident: a gate killed its `npm` step at the 15-minute bound)
+ * signals nothing below it. FireForge is not told; its stdout pipe merely
+ * breaks, and the broken-pipe handler swallows EPIPE on purpose so `| head`
+ * works. The mach tree it spawned as a separate process group keeps running
+ * under nobody's supervision, and the httpd in that tree spun at 100% CPU
+ * for hours.
+ *
+ * SIGKILL cannot be caught, but reparenting can be observed: once the parent
+ * is gone, `process.ppid` changes (to launchd/init, or to a subreaper). This
+ * watchdog polls for that while a dispatch is in flight and fires once. It
+ * does not decide what to do about it; the test command tears down the
+ * harness tree and ends the run.
+ *
+ * Off on Windows: `process.ppid` is not refreshed there after the parent
+ * exits, and there is no process group to signal in response anyway.
+ */
+/** How often the parent is probed. Cheap (one syscall), so a short interval is fine. */
+const DEFAULT_INTERVAL_MS = 2000;
+let parentExitObserved = false;
+/**
+ * True once any watchdog in this process has seen the parent die. The
+ * dispatch loop reads it to end the run instead of classifying the killed
+ * harness as a crash and retrying it under a parent that no longer exists.
+ */
+export function parentExited() {
+    return parentExitObserved;
+}
+/**
+ * Forgets an observed parent exit.
+ *
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
+ */
+export function resetParentExitForTests() {
+    parentExitObserved = false;
+}
+/**
+ * Starts probing `process.ppid`. The timer is unref'd so the watchdog can
+ * never be the thing keeping FireForge alive; while a child runs, the child
+ * does that.
+ */
+export function startParentExitWatchdog(options) {
+    if (process.platform === 'win32') {
+        return { stop: () => undefined };
+    }
+    const readPpid = options.readPpid ?? (() => process.ppid);
+    const originalPpid = readPpid();
+    let timer = setInterval(() => {
+        const currentPpid = readPpid();
+        if (currentPpid === originalPpid)
+            return;
+        stop();
+        parentExitObserved = true;
+        options.onParentExit({ originalPpid, currentPpid });
+    }, options.intervalMs ?? DEFAULT_INTERVAL_MS);
+    timer.unref();
+    function stop() {
+        if (timer === undefined)
+            return;
+        clearInterval(timer);
+        timer = undefined;
+    }
+    return { stop };
+}

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

@@ -26,6 +26,18 @@ export interface FuzzyApplyResult {
     /** List of `.rej` files created (when falling through to --reject). */
     rejectFiles?: string[];
 }
+/**
+ * The context-reduction ladder shared by the real apply and the dry-run
+ * replay: step 0 is an exact apply, step k passes `-C(3-k)`.
+ * @param maxFuzz - Maximum context-reduction steps (validated by callers)
+ * @returns One `git apply` argument list per step, in order
+ */
+export declare function contextReductionSteps(maxFuzz: number): string[][];
+/**
+ * Validates a `maxFuzz` value.
+ * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer
+ */
+export declare function assertValidMaxFuzz(maxFuzz: number): void;
 /**
  * Attempts to apply a patch with escalating context reduction.
  *

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

@@ -23,6 +23,29 @@ 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;
+/**
+ * The context-reduction ladder shared by the real apply and the dry-run
+ * replay: step 0 is an exact apply, step k passes `-C(3-k)`.
+ * @param maxFuzz - Maximum context-reduction steps (validated by callers)
+ * @returns One `git apply` argument list per step, in order
+ */
+export function contextReductionSteps(maxFuzz) {
+    const maxSteps = Math.min(maxFuzz, GIT_DEFAULT_CONTEXT);
+    const steps = [];
+    for (let step = 0; step <= maxSteps; step++) {
+        steps.push(step > 0 ? [`-C${GIT_DEFAULT_CONTEXT - step}`] : []);
+    }
+    return steps;
+}
+/**
+ * Validates a `maxFuzz` value.
+ * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer
+ */
+export function assertValidMaxFuzz(maxFuzz) {
+    if (!Number.isInteger(maxFuzz) || maxFuzz < 0) {
+        throw new InvalidArgumentError(`maxFuzz must be a non-negative integer, got ${maxFuzz}.`, 'maxFuzz');
+    }
+}
 // ── Implementation ──
 /**
  * Attempts to apply a patch with escalating context reduction.
@@ -41,14 +64,12 @@ const GIT_DEFAULT_CONTEXT = 3;
  *   (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 ${maxFuzz}.`, 'maxFuzz');
-    }
+    assertValidMaxFuzz(maxFuzz);
     await ensureGit();
     // 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${GIT_DEFAULT_CONTEXT - step}`] : [];
+    const ladder = contextReductionSteps(maxFuzz);
+    const maxSteps = ladder.length - 1;
+    for (const [step, contextArgs] of ladder.entries()) {
         const check = await exec('git', ['apply', '--check', ...contextArgs, '--', patchPath], {
             cwd: engineDir,
         });

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

@@ -63,6 +63,19 @@ export interface PatchedContentContext {
     getAffectingPatches: (filePath: string) => readonly PatchInfo[];
     /** Patch body text, memoized per patch path across the whole batch. */
     readPatchBody: (patch: PatchInfo) => Promise<string>;
+    /**
+     * Reads the HEAD content of every path in one `git cat-file --batch`
+     * and holds it for the next {@link computePatched} of each path, which
+     * otherwise spawns one `git show` per file. Call it before a loop.
+     */
+    prefetchBase: (filePaths: readonly string[]) => Promise<void>;
+    /**
+     * Hashes every live file in one `git hash-object` per ARG_MAX chunk and
+     * holds the hashes for {@link liveBlobHash}.
+     */
+    prefetchLiveBlobHashes: (fullPaths: readonly string[]) => Promise<void>;
+    /** The live blob hash of a file, from the prefetch or a single hash-object. */
+    liveBlobHash: (fullPath: string) => Promise<string | undefined>;
 }
 /**
  * Builds a batched patched-content context that loads the manifest and

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

@@ -11,7 +11,7 @@ import { pathExists, readText, writeFileAtomic, writeText } from '../utils/fs.js
 import { verbose } from '../utils/logger.js';
 import { isContainedRelativePath } from '../utils/paths.js';
 import { applyPatchIdempotent, reversePatch } from './git.js';
-import { getFileContentAtRef } from './git-file-ops.js';
+import { getFileContentAtRef, getFilesContentAtRef, hashObjectBatch } from './git-file-ops.js';
 import { discoverPatches } from './patch-files.js';
 import { loadPatchesManifest } from './patch-manifest.js';
 import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch, parseDiffSections, } from './patch-parse.js';
@@ -395,12 +395,37 @@ export async function createPatchedContentContext(patchesDir, engineDir) {
         return body;
     };
     const getAffectingPatches = (filePath) => affectingByFile.get(filePath) ?? [];
+    // Prefetched HEAD content, consumed on first use so a large scan does not
+    // hold every base file for the life of the context.
+    const baseContent = new Map();
+    const takeBase = async (filePath) => {
+        if (baseContent.has(filePath)) {
+            const content = baseContent.get(filePath) ?? null;
+            baseContent.delete(filePath);
+            return content;
+        }
+        return getFileContentAtRef(engineDir, filePath);
+    };
+    const liveHashes = new Map();
     return {
         manifestPatches: manifest?.patches ?? [],
         getAffectingPatches,
         readPatchBody,
+        prefetchBase: async (filePaths) => {
+            const wanted = filePaths.filter((file) => !baseContent.has(file));
+            for (const [file, content] of await getFilesContentAtRef(engineDir, wanted)) {
+                baseContent.set(file, content);
+            }
+        },
+        prefetchLiveBlobHashes: async (fullPaths) => {
+            const wanted = fullPaths.filter((path) => !liveHashes.has(path));
+            for (const [path, hash] of await hashObjectBatch(engineDir, wanted)) {
+                liveHashes.set(path, hash);
+            }
+        },
+        liveBlobHash: async (fullPath) => liveHashes.get(fullPath) ?? (await hashObjectBatch(engineDir, [fullPath])).get(fullPath),
         computePatched: async (filePath) => {
-            let content = await getFileContentAtRef(engineDir, filePath);
+            let content = await takeBase(filePath);
             for (const patch of getAffectingPatches(filePath)) {
                 content = applyPatchTextToContent(content, await readPatchBody(patch), filePath);
             }