@hominis/fireforge 0.13.1 → 0.14.0

package/dist/src/commands/patch/reorder.d.ts

@@ -9,7 +9,11 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
-import type { PatchReorderOptions } from '../../types/commands/index.js';
+import type { PatchMetadata, PatchReorderOptions } from '../../types/commands/index.js';
+/** Zero-pads an ordinal number to the given width. */
+export declare function padOrder(value: number, width: number): string;
+/** Builds a new patch filename by replacing the numeric prefix with `newOrder`. */
+export declare function rebuildFilenameForOrder(existing: PatchMetadata, newOrder: number): string;
 /**
  * Runs the `patch reorder` command: computes a rename map moving the
  * target patch to the requested slot, projects the new order through

package/dist/src/commands/patch/reorder.js

@@ -20,10 +20,12 @@ import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
 import { parsePositiveIntegerFlag } from '../../utils/validation.js';
-function padOrder(value, width) {
+/** Zero-pads an ordinal number to the given width. */
+export function padOrder(value, width) {
     return String(value).padStart(width, '0');
 }
-function rebuildFilenameForOrder(existing, newOrder) {
+/** Builds a new patch filename by replacing the numeric prefix with `newOrder`. */
+export function rebuildFilenameForOrder(existing, newOrder) {
     const currentPrefixMatch = /^(\d+)-/.exec(existing.filename);
     const currentPrefix = currentPrefixMatch?.[1] ?? '001';
     const width = Math.max(3, currentPrefix.length, String(newOrder).length);

package/dist/src/commands/re-export.js

@@ -5,7 +5,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
-import { updatePatch, updatePatchMetadata } from '../core/patch-export.js';
+import { updatePatchAndMetadata } from '../core/patch-export.js';
 import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
@@ -102,11 +102,18 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
     }
     else {
-        const patchPath = join(paths.patches, patch.filename);
-        await updatePatch(patchPath, diffContent);
-        await updatePatchMetadata(paths.patches, patch.filename, {
+        // Atomic body + manifest update under a single patch-directory lock.
+        // A split `updatePatch` (lock-free) + `updatePatchMetadata` (lock-guarded)
+        // sequence allows a concurrent `resolve` / `rebase --continue` / `patch
+        // compact` / `patch reorder` to rewrite the manifest between the two
+        // writes and leave patch body and `filesAffected` disagreeing.
+        await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, {
             filesAffected: currentFilesAffected,
         });
+        // Keep the in-memory manifest in sync so subsequent iterations (notably
+        // `--all --scan`, where `getClaimedFiles` reads from this manifest) see
+        // the just-written `filesAffected`. The on-disk write above is the
+        // authority; this is a cache update.
         const patchIndex = manifest.patches.findIndex((pm) => pm.filename === patch.filename);
         if (patchIndex !== -1) {
             const existingEntry = manifest.patches[patchIndex];

package/dist/src/commands/rebase/abort.js

@@ -2,7 +2,7 @@
 /**
  * Rebase abort flow.
  */
-import { getProjectPaths, loadState, saveState } from '../../core/config.js';
+import { getProjectPaths, updateState } from '../../core/config.js';
 import { getFurnacePaths, updateFurnaceState } from '../../core/furnace-config.js';
 import { resetChanges } from '../../core/git.js';
 import { clearRebaseSession, loadRebaseSession } from '../../core/rebase-session.js';
@@ -22,7 +22,8 @@ export async function handleAbort(projectRoot, yes) {
     if (!(await confirmDirtyEngineReset({
         engineDir: paths.engine,
         yes: yes ?? false,
-        nonInteractiveHint: 'Use: fireforge rebase --abort --yes',
+        nonInteractiveCommand: 'fireforge rebase --abort --yes',
+        argumentName: '--yes',
         warningMessage: 'The engine directory has uncommitted changes that will be lost.',
         promptMessage: 'Discard uncommitted changes and abort rebase?',
         cancelMessage: 'Abort cancelled',
@@ -30,27 +31,38 @@ export async function handleAbort(projectRoot, yes) {
         return;
     }
     const s = spinner('Restoring engine to pre-rebase state...');
+    // Step 1: git reset. If this fails, the rebase session MUST stay on disk
+    // so the user can retry the abort — resetChanges is the only irreversible
+    // operation in this handler and everything downstream assumes it ran.
     try {
         await resetChanges(paths.engine);
         s.stop('Engine restored');
-        // Clear Furnace state — the engine has been rolled back to pre-rebase state.
-        const furnacePaths = getFurnacePaths(projectRoot);
-        if (await pathExists(furnacePaths.furnaceState)) {
-            await updateFurnaceState(projectRoot, (current) => ({
-                ...(current.pendingRepair ? { pendingRepair: current.pendingRepair } : {}),
-            }));
-        }
     }
     catch (error) {
         s.error('Failed to restore engine');
         throw error;
     }
-    // Clear pending resolution state if any
-    const state = await loadState(projectRoot);
-    if (state.pendingResolution) {
-        delete state.pendingResolution;
-        await saveState(projectRoot, state);
+    // Step 2: clear Furnace state. A failure here is reported on its own
+    // (rather than labelled "Failed to restore engine", which would be
+    // misleading now that reset already succeeded). The rebase session is
+    // still kept on disk so the user can retry the abort and let it
+    // idempotently re-clear furnace state.
+    const furnacePaths = getFurnacePaths(projectRoot);
+    if (await pathExists(furnacePaths.furnaceState)) {
+        await updateFurnaceState(projectRoot, (current) => ({
+            ...(current.pendingRepair ? { pendingRepair: current.pendingRepair } : {}),
+        }));
     }
+    // Step 3: clear pending resolution transactionally.
+    await updateState(projectRoot, (current) => {
+        if (!current.pendingResolution)
+            return current;
+        const next = { ...current };
+        delete next.pendingResolution;
+        return next;
+    });
+    // Step 4: clear the rebase session LAST so a failure in any prior step
+    // preserves the session on disk and a retry of --abort can succeed.
     await clearRebaseSession(projectRoot);
     success('Rebase aborted and session cleared.');
     outro('Rebase aborted');

package/dist/src/commands/rebase/confirm.d.ts

@@ -5,7 +5,20 @@
 export interface DirtyEngineConfirmationOptions {
     engineDir: string;
     yes: boolean;
-    nonInteractiveHint: string;
+    /**
+     * Full remediation command the user should run in non-interactive mode,
+     * e.g. `"fireforge rebase --abort --yes"`. Rendered inline in the
+     * non-interactive error message so the user gets a paste-ready
+     * command instead of a bare flag name.
+     */
+    nonInteractiveCommand: string;
+    /**
+     * Argument identifier attached to the thrown {@link InvalidArgumentError}
+     * (typically the flag name, e.g. `"--yes"`). Separate from
+     * `nonInteractiveCommand` so the error's `argument` field carries the
+     * canonical flag name for structured handling.
+     */
+    argumentName: string;
     warningMessage: string;
     promptMessage: string;
     cancelMessage: string;
@@ -15,4 +28,4 @@ export interface DirtyEngineConfirmationOptions {
  * Returns true if safe to proceed, false if the user cancelled.
  * Throws in non-interactive mode without --yes.
  */
-export declare function confirmDirtyEngineReset({ engineDir, yes, nonInteractiveHint, warningMessage, promptMessage, cancelMessage, }: DirtyEngineConfirmationOptions): Promise<boolean>;
+export declare function confirmDirtyEngineReset({ engineDir, yes, nonInteractiveCommand, argumentName, warningMessage, promptMessage, cancelMessage, }: DirtyEngineConfirmationOptions): Promise<boolean>;

package/dist/src/commands/rebase/confirm.js

@@ -11,13 +11,13 @@ import { cancel, isCancel, warn } from '../../utils/logger.js';
  * Returns true if safe to proceed, false if the user cancelled.
  * Throws in non-interactive mode without --yes.
  */
-export async function confirmDirtyEngineReset({ engineDir, yes, nonInteractiveHint, warningMessage, promptMessage, cancelMessage, }) {
+export async function confirmDirtyEngineReset({ engineDir, yes, nonInteractiveCommand, argumentName, warningMessage, promptMessage, cancelMessage, }) {
     if (!(await hasChanges(engineDir)) || yes) {
         return true;
     }
     const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
     if (!isInteractive) {
-        throw new InvalidArgumentError('Engine has uncommitted changes and interactive confirmation is not available. Use --yes to proceed.', nonInteractiveHint);
+        throw new InvalidArgumentError(`Engine has uncommitted changes and interactive confirmation is not available. Run: ${nonInteractiveCommand}`, argumentName);
     }
     warn(warningMessage);
     const confirmed = await confirm({

package/dist/src/commands/rebase/continue.js

@@ -3,12 +3,13 @@
  * Rebase --continue flow.
  */
 import { join } from 'node:path';
-import { getProjectPaths, loadState, saveState } from '../../core/config.js';
+import { getProjectPaths, updateState } from '../../core/config.js';
 import { getStagedDiffForFiles } from '../../core/git-diff.js';
 import { stageFiles, unstageFiles } from '../../core/git-file-ops.js';
-import { updatePatch, updatePatchMetadata } from '../../core/patch-export.js';
+import { updatePatchAndMetadata } from '../../core/patch-export.js';
 import { loadPatchesManifest } from '../../core/patch-manifest.js';
 import { loadRebaseSession, saveRebaseSession } from '../../core/rebase-session.js';
+import { runInSignalCriticalSection } from '../../core/signal-critical.js';
 import { GeneralError } from '../../errors/base.js';
 import { NoRebaseSessionError, RebaseError } from '../../errors/rebase.js';
 import { pathExists } from '../../utils/fs.js';
@@ -23,6 +24,17 @@ export async function handleContinue(projectRoot, maxFuzz) {
     if (!session)
         throw new NoRebaseSessionError();
     const paths = getProjectPaths(projectRoot);
+    // Special case: every patch has already applied but a previous run failed
+    // somewhere in the post-apply work (re-export, version stamping). In that
+    // state currentIndex is past the end of the queue; jumping straight back
+    // into runPatchLoop replays the no-op apply loop and re-attempts the
+    // post-apply pipeline. Without this branch the user would be stuck —
+    // there is no failed patch to resolve, but the session is still active.
+    if (session.currentIndex >= session.patches.length) {
+        info('All patches already applied; retrying post-apply re-export and version stamping.');
+        await runPatchLoop(projectRoot, session, paths, maxFuzz);
+        return;
+    }
     // The current patch should be in 'failed' state
     const currentPatch = session.patches[session.currentIndex];
     if (!currentPatch || currentPatch.status !== 'failed') {
@@ -53,9 +65,13 @@ export async function handleContinue(projectRoot, maxFuzz) {
             warn('Either apply your fixes and re-run --continue, or skip this patch (not yet supported).');
             return;
         }
-        const patchPath = join(paths.patches, currentPatch.filename);
-        await updatePatch(patchPath, diffContent);
-        await updatePatchMetadata(paths.patches, currentPatch.filename, {
+        // Write the patch body and the manifest metadata atomically under the
+        // shared patch-directory lock. The previous lock-free sequence of
+        // updatePatch + updatePatchMetadata could interleave with a concurrent
+        // export / re-export / patch reorder / patch compact and leave the
+        // manifest disagreeing with the freshly-written patch body. Mirrors the
+        // v0.14.0 resolve.ts fix.
+        await updatePatchAndMetadata(paths.patches, currentPatch.filename, diffContent, {
             sourceEsrVersion: session.toVersion,
         });
     }
@@ -64,16 +80,24 @@ export async function handleContinue(projectRoot, maxFuzz) {
             await unstageFiles(paths.engine, activeFiles);
         }
     }
-    // Mark resolved and advance
-    currentPatch.status = 'resolved';
-    session.currentIndex++;
-    await saveRebaseSession(projectRoot, session);
-    // Clear pending resolution
-    const state = await loadState(projectRoot);
-    if (state.pendingResolution) {
-        delete state.pendingResolution;
-        await saveState(projectRoot, state);
-    }
+    // Mark resolved and advance. Wrap in a signal-deferred critical section
+    // so SIGINT / SIGTERM between the session update and the pendingResolution
+    // clear is held until both writes land, matching the guarantee the apply
+    // loop in patch-loop.ts provides.
+    await runInSignalCriticalSection(`rebase-continue:${currentPatch.filename}`, async () => {
+        currentPatch.status = 'resolved';
+        session.currentIndex++;
+        await saveRebaseSession(projectRoot, session);
+        // Clear pending resolution transactionally so concurrent state-file
+        // writes to unrelated keys are not clobbered by a stale reload.
+        await updateState(projectRoot, (current) => {
+            if (!current.pendingResolution)
+                return current;
+            const next = { ...current };
+            delete next.pendingResolution;
+            return next;
+        });
+    });
     success(`Resolved ${currentPatch.filename}`);
     // Continue applying remaining patches
     await runPatchLoop(projectRoot, session, paths, maxFuzz);

package/dist/src/commands/rebase/index.js

@@ -66,7 +66,8 @@ async function handleFreshStart(projectRoot, options) {
     if (!(await confirmDirtyEngineReset({
         engineDir: paths.engine,
         yes: options.yes ?? false,
-        nonInteractiveHint: 'Use: fireforge rebase --yes',
+        nonInteractiveCommand: 'fireforge rebase --yes',
+        argumentName: '--yes',
         warningMessage: 'The engine directory has uncommitted changes that will be lost by the rebase.',
         promptMessage: 'Discard uncommitted changes and start rebase?',
         cancelMessage: 'Rebase cancelled',

package/dist/src/commands/rebase/patch-loop.js

@@ -3,14 +3,17 @@
  * Patch application loop and re-export flow.
  */
 import { join } from 'node:path';
-import { loadState, saveState } from '../../core/config.js';
+import { updateState } from '../../core/config.js';
 import { getDiffForFilesAgainstHead } from '../../core/git-diff.js';
 import { applyPatchWithFuzz } from '../../core/patch-apply-fuzz.js';
 import { updatePatch } from '../../core/patch-export.js';
 import { discoverPatches } from '../../core/patch-files.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, stampPatchVersions } from '../../core/patch-manifest.js';
 import { extractConflictingFiles } from '../../core/patch-parse.js';
 import { clearRebaseSession, saveRebaseSession } from '../../core/rebase-session.js';
+import { runInSignalCriticalSection } from '../../core/signal-critical.js';
+import { RebaseError } from '../../errors/rebase.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { error, info, outro, spinner, success, warn } from '../../utils/logger.js';
@@ -34,35 +37,57 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz) {
             continue;
         }
         s.message(`Applying ${entry.filename}...`);
-        const result = await applyPatchWithFuzz(patchFile.path, paths.engine, maxFuzz);
+        // Apply + session persist is wrapped in a signal-deferred critical
+        // section so a SIGINT / SIGTERM between the filesystem mutation and
+        // the session-file update is held until the bookkeeping write lands.
+        // Without this guard, `rebase --continue` could see a patch that is
+        // already in the engine but still marked pending, and would re-apply
+        // it on resume (either failing on duplicate hunks or producing
+        // divergent results).
+        const result = await runInSignalCriticalSection(`rebase-apply:${entry.filename}`, async () => {
+            const applyResult = await applyPatchWithFuzz(patchFile.path, paths.engine, maxFuzz);
+            if (applyResult.success) {
+                if (applyResult.fuzzFactor === 0) {
+                    entry.status = 'applied-clean';
+                }
+                else {
+                    entry.status = 'applied-fuzz';
+                    entry.fuzzFactor = applyResult.fuzzFactor;
+                }
+                session.currentIndex = i + 1;
+                await saveRebaseSession(projectRoot, session);
+            }
+            else {
+                entry.status = 'failed';
+                if (applyResult.error) {
+                    entry.error = applyResult.error;
+                }
+                entry.conflictingFiles = extractConflictingFiles(applyResult.error);
+                session.currentIndex = i;
+                await saveRebaseSession(projectRoot, session);
+            }
+            return applyResult;
+        });
         if (result.success) {
             if (result.fuzzFactor === 0) {
-                entry.status = 'applied-clean';
                 success(`  ${entry.filename} — applied cleanly`);
             }
             else {
-                entry.status = 'applied-fuzz';
-                entry.fuzzFactor = result.fuzzFactor;
                 warn(`  ${entry.filename} — applied with fuzz=${result.fuzzFactor}`);
             }
-            session.currentIndex = i + 1;
-            await saveRebaseSession(projectRoot, session);
         }
         else {
-            entry.status = 'failed';
-            if (result.error) {
-                entry.error = result.error;
-            }
-            entry.conflictingFiles = extractConflictingFiles(result.error);
-            session.currentIndex = i;
-            await saveRebaseSession(projectRoot, session);
-            // Set pendingResolution in state for visibility
-            const state = await loadState(projectRoot);
-            state.pendingResolution = {
-                patchFilename: entry.filename,
-                originalError: result.error ?? 'Unknown error',
-            };
-            await saveState(projectRoot, state);
+            // Set pendingResolution in state for visibility. Kept outside the
+            // critical section — it is advisory UX, not a correctness invariant,
+            // and its absence would at most cause `fireforge status` to omit the
+            // pending-conflict hint until the next state write.
+            await updateState(projectRoot, (current) => ({
+                ...current,
+                pendingResolution: {
+                    patchFilename: entry.filename,
+                    originalError: result.error ?? 'Unknown error',
+                },
+            }));
             s.error(`${entry.filename} failed to apply`);
             if (result.error) {
                 error(`  Error: ${result.error}`);
@@ -79,8 +104,21 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz) {
         }
     }
     s.stop('All patches applied');
-    // Re-export all successfully applied patches
-    await reExportAppliedPatches(session, paths);
+    // Re-export all successfully applied patches. Failures here mean the
+    // engine has been rebased onto the new Firefox version but some .patch
+    // files were not refreshed — the queue would lie about what version each
+    // patch was tested against if we proceeded to stamp. Refuse to claim
+    // success and leave the session in place so the user can recover via
+    // `fireforge rebase --continue` after fixing the underlying cause.
+    const reExportFailures = await reExportAppliedPatches(session, paths);
+    if (reExportFailures.length > 0) {
+        for (const f of reExportFailures) {
+            error(`  ${f.filename}: ${f.error}`);
+        }
+        throw new RebaseError(`Apply succeeded but ${reExportFailures.length} patch(es) failed to re-export. ` +
+            `Versions were not stamped and the rebase session has been kept so you can retry. ` +
+            `Fix the underlying cause shown above, then re-run "fireforge rebase --continue".`);
+    }
     // Stamp versions
     const appliedFilenames = session.patches
         .filter((p) => p.status === 'applied-clean' || p.status === 'applied-fuzz' || p.status === 'resolved')
@@ -91,20 +129,24 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz) {
     // Print summary and clean up
     printSummary(session);
     await clearRebaseSession(projectRoot);
-    // Clear pending resolution if any
-    const state = await loadState(projectRoot);
-    if (state.pendingResolution) {
-        delete state.pendingResolution;
-        await saveState(projectRoot, state);
-    }
+    // Clear pending resolution if any (transactionally, so a concurrent
+    // state write to an unrelated key is not clobbered by a stale reload).
+    await updateState(projectRoot, (current) => {
+        if (!current.pendingResolution)
+            return current;
+        const next = { ...current };
+        delete next.pendingResolution;
+        return next;
+    });
     info('');
     success(`All patches re-exported with sourceEsrVersion=${session.toVersion}`);
     outro('Rebase complete!');
 }
 async function reExportAppliedPatches(session, paths) {
+    const failures = [];
     const manifest = await loadPatchesManifest(paths.patches);
     if (!manifest)
-        return;
+        return failures;
     const s = spinner('Re-exporting patches...');
     for (const entry of session.patches) {
         if (entry.status !== 'applied-clean' && entry.status !== 'applied-fuzz')
@@ -123,13 +165,28 @@ async function reExportAppliedPatches(session, paths) {
             const diffContent = await getDiffForFilesAgainstHead(paths.engine, existingFiles);
             if (diffContent.trim()) {
                 const patchPath = join(paths.patches, entry.filename);
-                await updatePatch(patchPath, diffContent);
+                // Hold the patch directory lock for the body rewrite so a concurrent
+                // manifest-mutating command (`resolve`, `re-export`, `patch compact`,
+                // `patch reorder`) cannot observe a torn patch body mid-write or
+                // persist metadata describing a body this loop is about to overwrite.
+                // Rebase sessions are serialized against each other by
+                // `rebase-session.ts`, so this lock is only defending against other
+                // command classes, not peer rebases.
+                await withPatchDirectoryLock(paths.patches, () => updatePatch(patchPath, diffContent));
             }
         }
         catch (err) {
-            warn(`Failed to re-export ${entry.filename}: ${toError(err).message}`);
+            const message = toError(err).message;
+            warn(`Failed to re-export ${entry.filename}: ${message}`);
+            failures.push({ filename: entry.filename, error: message });
         }
     }
-    s.stop('Patches re-exported');
+    if (failures.length > 0) {
+        s.error(`Re-export failed for ${failures.length} patch(es)`);
+    }
+    else {
+        s.stop('Patches re-exported');
+    }
+    return failures;
 }
 //# sourceMappingURL=patch-loop.js.map

package/dist/src/commands/register.js

@@ -15,6 +15,19 @@ import { pickDefined } from '../utils/options.js';
  */
 export async function registerCommand(projectRoot, filePath, options = {}) {
     intro('Register');
+    // --after is matched as a substring against existing manifest lines;
+    // guard against control characters / line terminators that would either
+    // break the match logic or, worse, inject a second line if the value
+    // is ever echoed back to a manifest writer. Null bytes are explicitly
+    // rejected to mirror the hardening already applied to other user-
+    // supplied identifiers (binaryName, furnace targetPath, …).
+    if (options.after !== undefined) {
+        // eslint-disable-next-line no-control-regex -- control chars in --after would break the manifest match
+        const hasControlChar = /[\u0000-\u001f]/.test(options.after);
+        if (options.after.length === 0 || hasControlChar) {
+            throw new InvalidArgumentError('--after must be a non-empty substring without control characters or line terminators.', 'after');
+        }
+    }
     // Verify the file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);

package/dist/src/commands/resolve.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
-import { getProjectPaths, loadConfig, loadState, saveState } from '../core/config.js';
+import { getProjectPaths, loadConfig, loadState, updateState } from '../core/config.js';
 import { isGitRepository } from '../core/git.js';
 import { getStagedDiffForFiles } from '../core/git-diff.js';
 import { stageFiles, unstageFiles } from '../core/git-file-ops.js';
-import { updatePatch, updatePatchMetadata } from '../core/patch-export.js';
+import { updatePatchAndMetadata } from '../core/patch-export.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError, ResolutionError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
@@ -54,6 +54,17 @@ export async function resolveCommand(projectRoot) {
     if (!patchMetadata) {
         throw new ResolutionError(`Patch ${patchFilename} not found in manifest.`);
     }
+    // Refuse to proceed if the patch file was deleted between the conflict
+    // and the resolve. Without this check, `updatePatchAndMetadata` would
+    // throw a less actionable "patch file is missing" error from inside
+    // the lock; the explicit precondition lets us point the user at the
+    // exact recovery path.
+    const patchPath = join(paths.patches, patchFilename);
+    if (!(await pathExists(patchPath))) {
+        throw new ResolutionError(`Patch file ${patchFilename} is missing on disk. ` +
+            'Delete the "pendingResolution" key from state.json to clear the stale conflict, ' +
+            'or restore the patch file before re-running resolve.');
+    }
     const s = spinner(`Updating ${patchFilename}...`);
     try {
         const existingFiles = patchMetadata.filesAffected;
@@ -89,18 +100,28 @@ export async function resolveCommand(projectRoot) {
             outro('Resolution unchanged');
             return;
         }
-        // Write the new diff content to the patch file
-        const patchPath = join(paths.patches, patchFilename);
-        await updatePatch(patchPath, diffContent);
-        // Update metadata (preserve original createdAt)
+        // Atomically write the patch body and the metadata update under the
+        // shared patch-directory lock. Replaces the previous lock-free
+        // sequence of updatePatch + updatePatchMetadata, which a concurrent
+        // import / export / re-export / patch reorder / patch compact could
+        // interleave with and leave the manifest disagreeing with the
+        // freshly-written patch body.
         const config = await loadConfig(projectRoot);
-        await updatePatchMetadata(paths.patches, patchFilename, {
+        await updatePatchAndMetadata(paths.patches, patchFilename, diffContent, {
             ...(activeFiles.length < existingFiles.length ? { filesAffected: activeFiles } : {}),
             sourceEsrVersion: config.firefox.version,
         });
-        // Cleanup: Clear pendingResolution from state.json
-        delete state.pendingResolution;
-        await saveState(projectRoot, state);
+        // Cleanup: Clear pendingResolution from state.json transactionally so
+        // we don't clobber concurrent updates to unrelated keys (e.g. another
+        // command writing buildMode or baseCommit between our loadState and
+        // saveState). The updater function runs inside the state-file lock
+        // with the freshest on-disk state, so only pendingResolution is
+        // affected.
+        await updateState(projectRoot, (current) => {
+            const next = { ...current };
+            delete next.pendingResolution;
+            return next;
+        });
         s.stop(`Updated ${patchFilename}`);
         success('Patch updated successfully and resolution state cleared.');
         info('Run "fireforge import" to apply the remaining patches.');

package/dist/src/commands/run.js

@@ -2,14 +2,13 @@
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getProjectPaths } from '../core/config.js';
-import { extractComponentChecksums, hasComponentChanged } from '../core/furnace-apply-helpers.js';
-import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from '../core/furnace-config.js';
+import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, hasBuildArtifacts, run } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, removeDir, removeFile } from '../utils/fs.js';
-import { info, intro, verbose, warn } from '../utils/logger.js';
+import { info, intro, verbose } from '../utils/logger.js';
 /**
  * Cleans the dev profile to prevent stale-state startup failures.
  *
@@ -47,47 +46,6 @@ async function cleanDevProfile(engineDir) {
         verbose(`Non-fatal dev profile cleanup failure: ${toError(error).message}`);
     }
 }
-/**
- * Checks whether any Furnace component has changed since the last apply
- * and warns the user. The build command auto-applies, but run does not,
- * so this advisory message prevents the common "forgot to apply" mistake.
- */
-async function warnIfFurnaceStale(projectRoot) {
-    try {
-        if (!(await furnaceConfigExists(projectRoot)))
-            return;
-        const config = await loadFurnaceConfig(projectRoot);
-        const state = await loadFurnaceState(projectRoot);
-        const furnacePaths = getFurnacePaths(projectRoot);
-        if (!state.appliedChecksums)
-            return;
-        const stale = [];
-        for (const name of Object.keys(config.overrides)) {
-            const dir = `${furnacePaths.overridesDir}/${name}`;
-            if (!(await pathExists(dir)))
-                continue;
-            const prev = extractComponentChecksums(state.appliedChecksums, 'override', name);
-            if (await hasComponentChanged(dir, prev))
-                stale.push(name);
-        }
-        for (const name of Object.keys(config.custom)) {
-            const dir = `${furnacePaths.customDir}/${name}`;
-            if (!(await pathExists(dir)))
-                continue;
-            const prev = extractComponentChecksums(state.appliedChecksums, 'custom', name);
-            if (await hasComponentChanged(dir, prev))
-                stale.push(name);
-        }
-        if (stale.length > 0) {
-            warn(`Furnace component${stale.length === 1 ? '' : 's'} modified since last apply: ${stale.join(', ')}. ` +
-                'Run "fireforge furnace apply" (or "fireforge build" which auto-applies) to update the engine.');
-        }
-    }
-    catch {
-        // Non-fatal: a broken furnace config should not block run.
-        verbose('Furnace staleness check skipped due to an error.');
-    }
-}
 /**
  * Runs the run command to launch the built browser.
  * @param projectRoot - Root directory of the project
@@ -120,6 +78,13 @@ export async function runCommand(projectRoot) {
     await cleanDevProfile(paths.engine);
     info('Launching browser...\n');
     const exitCode = await run(paths.engine);
+    // Exit-code whitelist:
+    //   0   — clean shutdown
+    //   130 — SIGINT (Ctrl+C), user-initiated termination
+    //   143 — SIGTERM, graceful-shutdown termination
+    // SIGKILL (137) and other signal-induced codes are intentionally NOT
+    // whitelisted: those indicate abnormal termination the operator should
+    // see surface as a build-time error.
     if (exitCode !== 0 && exitCode !== 130 && exitCode !== 143) {
         throw new BuildError(`Browser exited with code ${exitCode}`, 'mach run');
     }