@hominis/fireforge 0.44.4 → 0.46.0

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

@@ -24,7 +24,7 @@
  * installed the probe returns `{ inUse: false }` rather than failing the
  * test run — it is a best-effort friendliness check, not a prerequisite.
  */
-import { GeneralError } from '../errors/base.js';
+import { PreflightRefusalError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { getPlatform } from '../utils/platform.js';
 import { exec } from '../utils/process.js';
@@ -133,10 +133,10 @@ export async function ensureLaunchableBrowserNotRunning(launchableBinary, option
             return;
         }
         catch (error) {
-            throw new GeneralError(`A browser from this objdir is still running (PID ${holder.pid}), but FireForge could not terminate it: ${toError(error).message}`);
+            throw new PreflightRefusalError(`A browser from this objdir is still running (PID ${holder.pid}), but FireForge could not terminate it: ${toError(error).message}`, 'stale-browser-kill-failed');
         }
     }
-    throw new GeneralError(describeRunningBundleRefusal(holder));
+    throw new PreflightRefusalError(describeRunningBundleRefusal(holder), 'stale-browser');
 }
 /**
  * True when the process was launched BY a test harness — its command line
@@ -349,18 +349,18 @@ export async function assertMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
         const killHint = process.platform === 'win32'
             ? `Stop-Process -Id ${holder.pid} -Force`
             : `kill ${holder.pid}  # or "kill -9 ${holder.pid}" if it doesn't exit`;
-        throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
+        throw new PreflightRefusalError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
             `This is usually a browser left running by a previously interrupted "fireforge test" run. ` +
             `Kill it with "${killHint}", then retry. ` +
             `(If you expected ${holder.command} to be running on ${port}, stop it manually or pass ` +
-            `"--marionette-port <port>" to launch mach test on a different port.)`);
+            `"--marionette-port <port>" to launch mach test on a different port.)`, 'marionette-port-busy');
     }
     // Non-browser holder: mach test will still fail to bind, but the
     // cause is not a stale FireForge-launched browser. Flag it
     // explicitly so the operator can decide what to do instead of
     // getting mach's bind error with no FireForge context.
-    throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
-        `This is not a FireForge-launched browser; stop the holder process or free the port before rerunning.`);
+    throw new PreflightRefusalError(`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.`, 'marionette-port-busy');
 }
 /**
  * Ensures the Marionette port is usable, optionally terminating a stale
@@ -390,8 +390,8 @@ export async function ensureMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
         }
     }
     catch (error) {
-        throw new GeneralError(`Marionette port ${port} is held by stale browser ${holder.command} (PID ${holder.pid}), ` +
-            `but FireForge could not terminate it: ${toError(error).message}`);
+        throw new PreflightRefusalError(`Marionette port ${port} is held by stale browser ${holder.command} (PID ${holder.pid}), ` +
+            `but FireForge could not terminate it: ${toError(error).message}`, 'stale-browser-kill-failed');
     }
 }
 /**
@@ -410,10 +410,7 @@ export async function ensureMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
  *   `undefined`.
  */
 export function extractForwardedMarionettePort(machArgs) {
-    for (let i = 0; i < machArgs.length; i++) {
-        const arg = machArgs[i];
-        if (arg === undefined)
-            continue;
+    for (const [i, arg] of machArgs.entries()) {
         // `--marionette-port=NNNN`
         let match = /^--marionette-port=(\d+)$/.exec(arg);
         if (match?.[1]) {
@@ -452,10 +449,7 @@ export function extractForwardedMarionettePort(machArgs) {
  */
 export function forwardedMachArgsIncludeMarionetteClient(machArgs) {
     const valueLooksLikeHostPort = (token) => /:[0-9]+$/.test(token) || /^\[[^]]+\]:[0-9]+$/.test(token);
-    for (let i = 0; i < machArgs.length; i++) {
-        const arg = machArgs[i];
-        if (arg === undefined)
-            continue;
+    for (const [i, arg] of machArgs.entries()) {
         if (arg.startsWith('--marionette=') && !arg.startsWith('--marionette-port=')) {
             return true;
         }
@@ -473,8 +467,7 @@ export function forwardedMachArgsIncludeMarionetteClient(machArgs) {
  * for runs where the pref is ignored anyway.
  */
 export function hasExplicitXpcshellFlavor(machArgs) {
-    for (let i = 0; i < machArgs.length; i += 1) {
-        const arg = machArgs[i] ?? '';
+    for (const [i, arg] of machArgs.entries()) {
         if (/^--flavor=xpcshell\b/.test(arg) || arg === '--flavor=xpcshell-tests')
             return true;
         if (arg === '--flavor' && /^xpcshell(?:-tests)?$/.test(machArgs[i + 1] ?? ''))
@@ -493,42 +486,3 @@ export function hasExplicitXpcshellFlavor(machArgs) {
 export function shouldAutoForwardMarionettePortToMach(machArgs) {
     return !hasExplicitXpcshellFlavor(machArgs);
 }
-/**
- * Heuristic: do the test paths or forwarded mach args indicate a flavour
- * that actually launches a Marionette-driven browser? Browser-chrome and
- * mochitest do; xpcshell does not. A no-paths invocation (the default "run
- * all tests" shape) is treated as marionette-relevant since it includes
- * browser-chrome.
- *
- * Note: `fireforge test` auto-forward of `--marionette-port` to mach uses
- * {@link shouldAutoForwardMarionettePortToMach} (mach-arg flavor gate) rather
- * than this function alone, so toolkit paths without `/mochitest/` still get
- * the listener pref and harness `--marionette=127.0.0.1:<n>` when appropriate.
- *
- * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
- * @param machArgs - Forwarded mach args (post-`--mach-arg`).
- * @returns `true` when the run is likely to bind a Marionette listener.
- */
-export function isMarionetteFlavor(testPaths, machArgs) {
-    if (hasExplicitXpcshellFlavor(machArgs))
-        return false;
-    for (const arg of machArgs) {
-        if (/^--flavor=(browser-chrome|mochitest|chrome|a11y)\b/.test(arg))
-            return true;
-    }
-    if (testPaths.length === 0)
-        return true;
-    for (const path of testPaths) {
-        const base = path.split('/').pop() ?? path;
-        if (/^browser_.+\.(js|ini|toml)$/.test(base))
-            return true;
-        if (path.includes('/mochitest/') || path.startsWith('mochitest/'))
-            return true;
-        if (path.includes('/browser-chrome/') || path.startsWith('browser-chrome/'))
-            return true;
-        if (path.includes('toolkit/content/tests/') && !path.includes('/tests/xpcshell/')) {
-            return true;
-        }
-    }
-    return false;
-}

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

@@ -22,6 +22,7 @@ import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { installGracefulShutdownForwarder, trackChildClosure } from '../utils/process.js';
 import { killProcessTree, sweepProcessGroup } from '../utils/process-group.js';
+import { sleep } from '../utils/sleep.js';
 import { ensureMach } from './mach.js';
 import { getPython } from './mach-python.js';
 /** Marionette's default TCP port when the browser is launched with `--marionette`. */
@@ -143,7 +144,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         const spawnedChild = child;
         closure = trackChildClosure();
         forwarder = installGracefulShutdownForwarder(spawnedChild, 500, (signal) => {
-            killProcessGroup(spawnedChild, signal);
+            killProcessTree(spawnedChild, signal, process.platform !== 'win32');
         });
         child.stderr?.on('data', (data) => {
             const chunk = data.toString();
@@ -155,10 +156,10 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         // never come.
         const settleDeadline = Math.min(spawnSettleMs, Math.max(0, timeoutMs - elapsed()));
         if (settleDeadline > 0) {
-            await delay(settleDeadline);
+            await sleep(settleDeadline, { unref: true });
         }
         if (hasChildExited(spawnedChild)) {
-            return fail('browser-spawns', `Browser process exited during spawn (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+            return fail('browser-spawns', `Browser process exited during spawn (exit code ${spawnedChild.exitCode}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
                 `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
         }
         // Layer 6: marionette handshake within the remaining budget.
@@ -175,7 +176,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         // Child may have exited before the socket was ever ready — surface that
         // distinctly from "socket never answered" so the operator has a lead.
         if (hasChildExited(spawnedChild)) {
-            return fail('marionette-handshake', `Browser process exited before marionette handshake (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+            return fail('marionette-handshake', `Browser process exited before marionette handshake (exit code ${spawnedChild.exitCode}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
                 `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
         }
         return fail('marionette-handshake', `Marionette socket on 127.0.0.1:${port} did not respond within ${timeoutMs}ms. ` +
@@ -203,12 +204,12 @@ async function teardownPreflightChild(child, forwarder, closure, profileDir) {
     forwarder?.dispose();
     const groupPid = child?.pid;
     if (child && !hasChildExited(child)) {
-        killProcessGroup(child, 'SIGTERM');
+        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 delay(500);
+        await sleep(500, { unref: true });
         if (!hasChildExited(child)) {
-            killProcessGroup(child, 'SIGKILL');
+            killProcessTree(child, 'SIGKILL', process.platform !== 'win32');
         }
     }
     // Reap anything that outlived the group signal. The file's own comments
@@ -237,19 +238,6 @@ async function teardownPreflightChild(child, forwarder, closure, profileDir) {
         warn(`Could not clean up marionette preflight profile: ${toError(error).message}`);
     }
 }
-/**
- * Sends `signal` to the child's whole process group when possible, falling
- * back to a direct `child.kill` for environments that don't support
- * `detached: true` (Windows in particular: Node still returns a pid, but
- * `kill(-pid, …)` is not a supported kernel primitive).
- */
-function killProcessGroup(child, signal) {
-    // Delegates to the shared implementation, which is a strict superset of
-    // the hand-rolled one this replaced: same POSIX `kill(-pid)` with the same
-    // fall-through to a direct `child.kill`, plus a Windows `taskkill /T /F`
-    // branch and an already-exited early return.
-    killProcessTree(child, signal, process.platform !== 'win32');
-}
 function fail(layer, message, durationMs) {
     return {
         ok: false,
@@ -267,7 +255,7 @@ async function waitForMarionetteSocket(port, connectFn, keepTrying) {
         if (result.ok) {
             return { ok: true };
         }
-        await delay(400);
+        await sleep(400, { unref: true });
     }
     return { ok: false };
 }
@@ -312,12 +300,6 @@ function attemptMarionetteConnect(port, connectFn) {
         });
     });
 }
-function delay(ms) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, ms);
-        timer.unref();
-    });
-}
 /** Renders a PASS/FAIL banner to the CLI using the shared logger helpers. */
 export function reportMarionettePreflight(result) {
     if (result.ok) {

package/dist/src/core/mochitest-server-port.js

@@ -100,8 +100,8 @@ export function describeMochitestServerRefusal(port, holder, recognized) {
     const killHint = process.platform === 'win32'
         ? `Stop-Process -Id ${holder.pid} -Force`
         : `kill -9 ${holder.pid}`;
-    const evidence = `The mochitest server port ${String(port)} is already held by ${holder.command} ` +
-        `(PID ${String(holder.pid)}).\n` +
+    const evidence = `The mochitest server port ${port} is already held by ${holder.command} ` +
+        `(PID ${holder.pid}).\n` +
         `  command: ${holder.commandLine}\n` +
         "  A browser launched now would connect to THAT server, which cannot serve this run's " +
         'manifest — the run would stall before TEST_START and die on the no-output timeout with ' +
@@ -115,5 +115,5 @@ export function describeMochitestServerRefusal(port, holder, recognized) {
     return (evidence +
         "  This is NOT the mochitest harness's server.js, so FireForge will not offer to kill it. " +
         `Stop the holder yourself with "${killHint}" if it is yours, or free the port, then retry. ` +
-        `Diagnose with "lsof -nP -iTCP:${String(port)}".`);
+        `Diagnose with "lsof -nP -iTCP:${port}".`);
 }

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

@@ -3,6 +3,7 @@ import { basename, join } from 'node:path';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { registerBrowserContent, registerFireForgeModule, registerSharedCSS, registerTestManifest, registerToolkitWidget, } from './moz-manifest-register.js';
@@ -84,13 +85,30 @@ export function getRules(binaryName, createManifest = false) {
         },
     ];
 }
-async function isSharedCSSRegistered(engineDir, fileName) {
-    const manifestPath = join(engineDir, 'browser/themes/shared/jar.inc.mn');
+/**
+ * Reads an engine manifest and reports whether it contains any of `needles`.
+ *
+ * The five registration probes below share this shape: resolve the manifest
+ * relative to the engine, refuse with the manifest's own path when it is
+ * missing, then substring-match the entry each registrar writes.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param manifestRel - Engine-relative manifest path (forward slashes; also
+ *   the path named in the refusal message)
+ * @param needles - Entry forms that count as registered
+ * @returns True when the manifest contains at least one needle
+ * @throws GeneralError when the manifest does not exist
+ */
+async function manifestIncludes(engineDir, manifestRel, needles) {
+    const manifestPath = join(engineDir, manifestRel);
     if (!(await pathExists(manifestPath))) {
-        throw new GeneralError('Manifest not found: browser/themes/shared/jar.inc.mn');
+        throw new GeneralError(`Manifest not found: ${manifestRel}`);
     }
-    const name = basename(fileName, '.css');
     const content = await readText(manifestPath);
+    return needles.some((needle) => content.includes(needle));
+}
+async function isSharedCSSRegistered(engineDir, fileName) {
+    const name = basename(fileName, '.css');
     // `register` writes the canonical `skin/classic/browser/<name>.css` form;
     // `furnace chrome-doc create` writes a `content/browser/<name>.css` entry
     // because the CSS is loaded by a chrome document via a `chrome://browser/
@@ -98,40 +116,26 @@ async function isSharedCSSRegistered(engineDir, fileName) {
     // chrome-doc scaffolder are not flagged as "potentially unregistered" by
     // `status` and so a re-run of `register` against the same file recognises
     // the existing entry instead of proposing a duplicate.
-    return (content.includes(`skin/classic/browser/${name}.css`) ||
-        content.includes(`content/browser/${name}.css`));
+    return manifestIncludes(engineDir, 'browser/themes/shared/jar.inc.mn', [
+        `skin/classic/browser/${name}.css`,
+        `content/browser/${name}.css`,
+    ]);
 }
 async function isBrowserContentRegistered(engineDir, fileName) {
-    const manifestPath = join(engineDir, 'browser/base/jar.mn');
-    if (!(await pathExists(manifestPath))) {
-        throw new GeneralError('Manifest not found: browser/base/jar.mn');
-    }
-    const content = await readText(manifestPath);
-    return content.includes(`content/browser/${fileName}`);
+    return manifestIncludes(engineDir, 'browser/base/jar.mn', [`content/browser/${fileName}`]);
 }
 async function isTestManifestRegistered(engineDir, testDir) {
-    const manifestPath = join(engineDir, 'browser/base/moz.build');
-    if (!(await pathExists(manifestPath))) {
-        throw new GeneralError('Manifest not found: browser/base/moz.build');
-    }
-    const content = await readText(manifestPath);
-    return content.includes(`content/test/${testDir}/browser.toml`);
+    return manifestIncludes(engineDir, 'browser/base/moz.build', [
+        `content/test/${testDir}/browser.toml`,
+    ]);
 }
 async function isFireForgeModuleRegistered(engineDir, fileName, moduleDir) {
-    const manifestPath = join(engineDir, moduleDir, 'moz.build');
-    if (!(await pathExists(manifestPath))) {
-        throw new GeneralError(`Manifest not found: ${moduleDir}/moz.build`);
-    }
-    const content = await readText(manifestPath);
-    return content.includes(`"${fileName}"`);
+    return manifestIncludes(engineDir, `${moduleDir}/moz.build`, [`"${fileName}"`]);
 }
 async function isToolkitWidgetRegistered(engineDir, _tagName, fileName) {
-    const manifestPath = join(engineDir, 'toolkit/content/jar.mn');
-    if (!(await pathExists(manifestPath))) {
-        throw new GeneralError('Manifest not found: toolkit/content/jar.mn');
-    }
-    const content = await readText(manifestPath);
-    return content.includes(`content/global/elements/${fileName}`);
+    return manifestIncludes(engineDir, 'toolkit/content/jar.mn', [
+        `content/global/elements/${fileName}`,
+    ]);
 }
 /**
  * Checks if a file path matches any known registrable pattern.
@@ -140,7 +144,7 @@ async function isToolkitWidgetRegistered(engineDir, _tagName, fileName) {
  * @returns True if the file matches a known registration pattern
  */
 export function matchesRegistrablePattern(filePath, binaryName) {
-    const normalized = filePath.replace(/\\/g, '/');
+    const normalized = normalizePathSlashes(filePath);
     const rules = getRules(binaryName);
     return rules.some((rule) => rule.pattern.test(normalized));
 }
@@ -197,7 +201,7 @@ export async function isFileRegistered(root, filePath) {
     const { engine: engineDir } = getProjectPaths(root);
     const config = await loadConfig(root);
     const rules = getRules(config.binaryName);
-    const normalizedPath = filePath.replace(/\\/g, '/');
+    const normalizedPath = normalizePathSlashes(filePath);
     for (const rule of rules) {
         const match = normalizedPath.match(rule.pattern);
         if (match) {
@@ -237,7 +241,7 @@ export async function registerFile(root, filePath, dryRun = false, after, option
     const config = await loadConfig(root);
     const rules = getRules(config.binaryName, options.createManifest === true);
     // Normalize path separators
-    const normalizedPath = filePath.replace(/\\/g, '/');
+    const normalizedPath = normalizePathSlashes(filePath);
     for (const rule of rules) {
         const match = normalizedPath.match(rule.pattern);
         if (match) {

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

@@ -42,13 +42,13 @@ const GIT_DEFAULT_CONTEXT = 3;
  */
 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');
+        throw new InvalidArgumentError(`maxFuzz must be a non-negative integer, got ${maxFuzz}.`, '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${String(GIT_DEFAULT_CONTEXT - step)}`] : [];
+        const contextArgs = step > 0 ? [`-C${GIT_DEFAULT_CONTEXT - step}`] : [];
         const check = await exec('git', ['apply', '--check', ...contextArgs, '--', patchPath], {
             cwd: engineDir,
         });
@@ -59,12 +59,12 @@ export async function applyPatchWithFuzz(patchPath, engineDir, maxFuzz = 3) {
             });
             if (apply.exitCode === 0) {
                 if (step > 0) {
-                    verbose(`Patch applied with reduced context (-C${String(GIT_DEFAULT_CONTEXT - step)}): ${patchPath}`);
+                    verbose(`Patch applied with reduced context (-C${GIT_DEFAULT_CONTEXT - step}): ${patchPath}`);
                 }
                 return { success: true, fuzzFactor: step };
             }
             // 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()}`);
+            verbose(`git apply -C${GIT_DEFAULT_CONTEXT - step} --check passed but apply failed: ${apply.stderr.trim()}`);
         }
     }
     // All context-reduction levels failed → generate .rej files for manual resolution

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

@@ -4,10 +4,9 @@
  */
 import type { ImportSummary, PatchInfo, PatchMetadata } from '../types/commands/index.js';
 export { PatchError } from '../errors/patch.js';
-export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
+export { countPatches, discoverPatches } from './patch-files.js';
 export { withPatchDirectoryLock } from './patch-lock.js';
-export { extractAffectedFiles, extractOrder, isNewFileInPatch } from './patch-parse.js';
-export { applyPatchToContent, extractNewFileContent } from './patch-transform.js';
+export { extractAffectedFiles } from './patch-parse.js';
 /**
  * Options for {@link applyPatchesWithContinue}.
  */
@@ -47,10 +46,10 @@ export declare function matchesUntilFilename(patchFilename: string, needle: stri
  * on the first failure to keep the engine directory in a clean state.
  * @param patchesDir - Path to the patches directory
  * @param engineDir - Path to the engine directory
- * @param optionsOrContinue - Options object, or the legacy continueOnFailure boolean
+ * @param options - Application options
  * @returns Import summary with all results
  */
-export declare function applyPatchesWithContinue(patchesDir: string, engineDir: string, optionsOrContinue?: ApplyPatchesOptions | boolean): Promise<ImportSummary>;
+export declare function applyPatchesWithContinue(patchesDir: string, engineDir: string, options?: ApplyPatchesOptions): Promise<ImportSummary>;
 /**
  * Batched patched-content computation shared by status classification,
  * import's unmanaged-dirty guard, and discard baseline planning.

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

@@ -3,25 +3,24 @@
  * Patch orchestration — coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
-import { lstat, readlink, realpath } from 'node:fs/promises';
+import { lstat, readFile, readlink, realpath, rm } from 'node:fs/promises';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { PatchError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readText, writeText } from '../utils/fs.js';
+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 { getFileContentFromHead } from './git-file-ops.js';
+import { getFileContentAtRef } from './git-file-ops.js';
 import { discoverPatches } from './patch-files.js';
 import { loadPatchesManifest } from './patch-manifest.js';
-import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch } from './patch-parse.js';
-import { applyPatchTextToContent, extractNewFileContent } from './patch-transform.js';
+import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch, parseDiffSections, } from './patch-parse.js';
+import { applyPatchTextToContent, extractNewFileContentFromDiff } from './patch-transform.js';
 // Re-export from split modules so existing import sites continue working
 export { PatchError } from '../errors/patch.js';
-export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
+export { countPatches, discoverPatches } from './patch-files.js';
 export { withPatchDirectoryLock } from './patch-lock.js';
-export { extractAffectedFiles, extractOrder, isNewFileInPatch } from './patch-parse.js';
-export { applyPatchToContent, extractNewFileContent } from './patch-transform.js';
+export { extractAffectedFiles } from './patch-parse.js';
 /**
  * Applies a single patch.
  *
@@ -53,28 +52,57 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
         const applyError = toError(error);
         // Check if this is a resolvable "new file" conflict
         let resolvedNewFiles = false;
-        // Save original content for files we might overwrite, so we can restore on failure
+        // Save original BYTES of files we might overwrite, so we can restore on
+        // failure. Raw buffers rather than decoded text: the same snapshot has to
+        // restore a binary target byte-for-byte, and a Buffer round-trips text
+        // losslessly where a utf-8 decode of a binary file does not.
         const savedContents = new Map();
+        // New-file sections keyed by target, so the binary discrimination below
+        // reads the ALREADY-parsed section instead of re-scanning the body per
+        // file.
+        const newFileSections = new Map(parseDiffSections(patchContent)
+            .filter((section) => section.isNewFile)
+            .map((section) => [section.targetPath, section]));
         try {
             for (const file of affectedFiles) {
-                if (isNewFileInPatch(patchContent, file)) {
-                    const targetPath = join(engineDir, file);
-                    if (await pathExists(targetPath)) {
-                        savedContents.set(file, await readText(targetPath));
-                        const content = await extractNewFileContent(patch.path, file);
-                        await writeText(targetPath, content);
-                        resolvedNewFiles = true;
+                if (!isNewFileInPatch(patchContent, file))
+                    continue;
+                const targetPath = join(engineDir, file);
+                if (!(await pathExists(targetPath)))
+                    continue;
+                savedContents.set(file, await readFile(targetPath));
+                const section = newFileSections.get(file);
+                if (section?.isBinary === true) {
+                    // A binary new file cannot be resolved by writing extracted text —
+                    // the payload is base85, whose alphabet includes '+'. It does not
+                    // need to be: `git apply` decodes a `GIT binary patch` itself. So
+                    // the resolution is to REMOVE the blocking file and let the retry
+                    // below create it from the payload, which is exactly what the
+                    // text branch achieves by overwriting.
+                    if (!section.hasBinaryDelta) {
+                        // `Binary files … differ` records THAT the bytes changed and
+                        // carries none of them, so nothing can recreate the file. Fail
+                        // honestly rather than deleting a file we cannot put back.
+                        throw new PatchError(`Cannot resolve the new-file conflict for ${file}: the patch's binary section ` +
+                            'carries no replayable payload (`Binary files … differ` rather than `GIT binary ' +
+                            'patch`), so the file cannot be recreated. Re-export the patch with a binary-aware ' +
+                            'diff.', file);
                     }
+                    await rm(targetPath, { force: true });
                 }
+                else {
+                    await writeText(targetPath, extractNewFileContentFromDiff(patchContent, file));
+                }
+                resolvedNewFiles = true;
             }
         }
         catch (extractError) {
-            // extractNewFileContent threw for a LATER target (e.g. a binary
-            // section) after earlier targets were already overwritten — restore
-            // them before reporting failure, instead of letting the exception
-            // skip the restore loop entirely and crash the whole import.
+            // Resolution threw for a LATER target after earlier targets were
+            // already overwritten or removed — restore them before reporting
+            // failure, instead of letting the exception skip the restore loop
+            // entirely and crash the whole import.
             for (const [file, originalContent] of savedContents) {
-                await writeText(join(engineDir, file), originalContent);
+                await writeFileAtomic(join(engineDir, file), originalContent);
             }
             return { patch, success: false, error: toError(extractError).message };
         }
@@ -91,9 +119,9 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
             }
             catch (retryError) {
                 verbose(`Auto-resolved new-file retry failed for ${patch.filename}: ${toError(retryError).message}`);
-                // Restore original file content before falling through to --reject
+                // Restore original file bytes before falling through to --reject
                 for (const [file, originalContent] of savedContents) {
-                    await writeText(join(engineDir, file), originalContent);
+                    await writeFileAtomic(join(engineDir, file), originalContent);
                 }
             }
         }
@@ -138,7 +166,7 @@ async function rollbackPatches(results, engineDir) {
         if (result.autoResolvedOriginals) {
             for (const [file, originalContent] of result.autoResolvedOriginals) {
                 try {
-                    await writeText(join(engineDir, file), originalContent);
+                    await writeFileAtomic(join(engineDir, file), originalContent);
                     verbose(`Restored pre-existing content of ${file} after rollback`);
                 }
                 catch (restoreError) {
@@ -243,15 +271,10 @@ export function matchesUntilFilename(patchFilename, needle) {
  * on the first failure to keep the engine directory in a clean state.
  * @param patchesDir - Path to the patches directory
  * @param engineDir - Path to the engine directory
- * @param optionsOrContinue - Options object, or the legacy continueOnFailure boolean
+ * @param options - Application options
  * @returns Import summary with all results
  */
-export async function applyPatchesWithContinue(patchesDir, engineDir, optionsOrContinue = false) {
-    // Accept both the legacy boolean positional and the new options object so
-    // existing call sites (tests and rebase) keep working without a rewrite.
-    const options = typeof optionsOrContinue === 'boolean'
-        ? { continueOnFailure: optionsOrContinue }
-        : optionsOrContinue;
+export async function applyPatchesWithContinue(patchesDir, engineDir, options = {}) {
     const continueOnFailure = options.continueOnFailure ?? false;
     const untilFilename = options.untilFilename;
     const patches = await discoverPatches(patchesDir);
@@ -377,7 +400,7 @@ export async function createPatchedContentContext(patchesDir, engineDir) {
         getAffectingPatches,
         readPatchBody,
         computePatched: async (filePath) => {
-            let content = await getFileContentFromHead(engineDir, filePath);
+            let content = await getFileContentAtRef(engineDir, filePath);
             for (const patch of getAffectingPatches(filePath)) {
                 content = applyPatchTextToContent(content, await readPatchBody(patch), filePath);
             }

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

@@ -2,15 +2,6 @@
  * Patch coverage and supersession helpers used by export planning.
  */
 import type { PatchInfo, PatchMetadata } from '../types/commands/index.js';
-/**
- * Finds patches that are completely superseded by newer patches.
- * A patch is superseded if all its affected files are covered by newer patches.
- * @param patchesDir - Path to the patches directory
- * @param newPatchFiles - Files affected by the new patch
- * @param excludeFilename - Filename to exclude from results (the new patch itself)
- * @returns Superseded patches
- */
-export declare function findSupersededPatches(patchesDir: string, newPatchFiles: string[], excludeFilename?: string): Promise<PatchInfo[]>;
 /**
  * Report whether a patch is fully covered by a new export, and which of its
  * files caused the coverage.

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

@@ -2,37 +2,8 @@
 /**
  * Patch coverage and supersession helpers used by export planning.
  */
-import { discoverPatches, isNewFilePatch } from './patch-apply.js';
+import { discoverPatches } from './patch-apply.js';
 import { loadPatchesManifest } from './patch-manifest.js';
-/**
- * Finds patches that are completely superseded by newer patches.
- * A patch is superseded if all its affected files are covered by newer patches.
- * @param patchesDir - Path to the patches directory
- * @param newPatchFiles - Files affected by the new patch
- * @param excludeFilename - Filename to exclude from results (the new patch itself)
- * @returns Superseded patches
- */
-export async function findSupersededPatches(patchesDir, newPatchFiles, excludeFilename) {
-    const manifest = await loadPatchesManifest(patchesDir);
-    if (!manifest)
-        return [];
-    const patches = await discoverPatches(patchesDir);
-    const superseded = [];
-    for (const metadata of manifest.patches) {
-        if (excludeFilename && metadata.filename === excludeFilename)
-            continue;
-        if (metadata.filesAffected.length === 1) {
-            const affectedFile = metadata.filesAffected[0];
-            if (affectedFile && newPatchFiles.includes(affectedFile)) {
-                const patch = patches.find((p) => p.filename === metadata.filename);
-                if (patch && (await isNewFilePatch(patch.path))) {
-                    superseded.push(patch);
-                }
-            }
-        }
-    }
-    return superseded;
-}
 /**
  * Checks whether a patch is fully covered by a new export.
  * A patch is fully covered when every file it affects is present in the new export.