@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -5,7 +5,6 @@
  * loop calls {@link reExportSinglePatchWithIndexLockRetry} per selected
  * patch.
  */
-import { getProjectPaths } from '../core/config.js';
 import { stdioIsInteractive } from '../core/destructive.js';
 import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
@@ -14,6 +13,7 @@ import { updatePatchAndMetadata } from '../core/patch-export.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { isGitIndexLockConflict } from '../errors/git.js';
 import { info, success, warn } from '../utils/logger.js';
+import { sleep } from '../utils/sleep.js';
 import { findMissingFiles, reportAdjacentUnmanagedFiles } from './re-export-adjacent.js';
 import { reportForeignDrift } from './re-export-drift.js';
 import { lintReExportedPatch, refreshQueueCtxEntry, storeReExportLintResult, } from './re-export-lint.js';
@@ -23,23 +23,24 @@ const GIT_INDEX_LOCK_RETRY_MS = 300;
  * Retries a single patch re-export exactly once when the failure is
  * transient git `index.lock` contention (an external git process holding
  * the engine repo's index). The retry re-enters `reExportSinglePatch`
- * from the top, so it re-reads clean state; a second lock failure
+ * from the top, so it re-reads clean state. A second lock failure
  * propagates to the loop's honest "N of M" accounting.
  */
-export async function reExportSinglePatchWithIndexLockRetry(patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx) {
+export async function reExportSinglePatchWithIndexLockRetry(args) {
     try {
-        return await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx);
+        return await reExportSinglePatch(args);
     }
     catch (error) {
         if (!isGitIndexLockConflict(error)) {
             throw error;
         }
-        warn(`${patch.filename}: git index.lock contention detected — retrying once after ${String(GIT_INDEX_LOCK_RETRY_MS)} ms...`);
-        await new Promise((resolve) => setTimeout(resolve, GIT_INDEX_LOCK_RETRY_MS));
-        return await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx);
+        warn(`${args.patch.filename}: git index.lock contention detected — retrying once after ${GIT_INDEX_LOCK_RETRY_MS} ms...`);
+        await sleep(GIT_INDEX_LOCK_RETRY_MS);
+        return await reExportSinglePatch(args);
     }
 }
-async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx) {
+async function reExportSinglePatch(args) {
+    const { patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx } = args;
     let currentFilesAffected = [...patch.filesAffected];
     // --- Scan for new/removed files ---
     if (options.scan) {
@@ -52,10 +53,10 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
             ...(options.scanFiles !== undefined ? { scanFiles: options.scanFiles } : {}),
         });
         // Forward-import gate at adoption time (runs in dry-run too): refuse
-        // to adopt unmanaged files that import modules created by LATER
-        // patches — the after-the-fact lint failure this leaves behind is the
-        // field-reported footgun. Applies to broad --scan, --scan-file, and
-        // the --scan-files bulk assignments alike.
+        // to adopt unmanaged files that import modules created by later
+        // patches, because the after-the-fact lint failure this leaves behind
+        // is the field-reported footgun. Applies to broad --scan, --scan-file,
+        // and the --scan-files bulk assignments alike.
         await assertScanAdoptionsHaveNoForwardImports({
             patchesDir: paths.patches,
             engineDir: paths.engine,
@@ -81,7 +82,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         // When neither `--scan` nor `--files` is set and some of the manifest's
         // claimed files no longer exist on disk, the re-export silently writes a
         // refreshed body whose filesAffected still names the vanished paths.
-        // That is the documented contract, but it is also a footgun — a later
+        // That is the documented contract, but it is also a footgun: a later
         // `verify` then fails on manifest-consistency with no obvious trigger.
         // Emit one advisory warning up-front when the drift is cheap to detect,
         // so the operator can re-run with `--scan` or `--files` before the stale
@@ -91,9 +92,9 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
             return false;
     }
     // --- Explicit file-subset path ---
-    // When --files is given, the target filesAffected is authoritative — drop
+    // When --files is given, the target filesAffected is authoritative: drop
     // anything not in the list, add anything new. This is the surgical repair
-    // primitive that replaces hand-editing patches.json; the user has already
+    // primitive that replaces hand-editing patches.json. The user has already
     // acknowledged via confirmDestructive (done in the caller) that any drop
     // is intentional.
     if (options.files !== undefined) {
@@ -108,16 +109,16 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     }
     // Stale-furnace-source gate: re-export captures deployed engine copies, so
     // a component source edited after the last furnace apply would land in the
-    // patch as its OLD deployed content. Refuse (or warn under
+    // patch as its old deployed content. Refuse (or warn under
     // --allow-stale-furnace) before diffing. Runs in dry-run too so the failure
     // surfaces early.
     await enforceFreshFurnaceSources(paths.root, currentFilesAffected, options.allowStaleFurnace === true, 're-export');
     const absentFiles = await findMissingFiles(paths.engine, currentFilesAffected);
-    // A path absent from disk but tracked in engine HEAD is a DELETION, and
+    // A path absent from disk but tracked in engine HEAD is a deletion, and
     // `git diff HEAD` renders it as a real `deleted file mode` section. Only
     // a never-tracked path has nothing to diff. Skipping both alike meant a
     // retired file quietly left the patch body while staying in its file
-    // list — the patch then claimed a file it could not restore.
+    // list, so the patch then claimed a file it could not restore.
     const trackedAbsent = await listTrackedInHead(paths.engine, absentFiles);
     const deletedFiles = absentFiles.filter((f) => trackedAbsent.has(f));
     const untrackedAbsent = absentFiles.filter((f) => !trackedAbsent.has(f));
@@ -147,9 +148,9 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     }
     // Foreign-drift preview + optional hard stop: show which
     // payload lines are about to enter the body that the old body did not
-    // carry — the case where a concurrent session's uncommitted edits in
-    // OWNED files would be silently absorbed. Always previews (including
-    // dry-run and --scan); refuses only under --refuse-foreign-drift.
+    // carry, the case where a concurrent session's uncommitted edits in
+    // owned files would be silently absorbed. Always previews (including
+    // dry-run and --scan). Refuses only under --refuse-foreign-drift.
     if (await reportForeignDrift({
         patch,
         patchesDir: paths.patches,
@@ -166,7 +167,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         command: 're-export',
         forceUnsafe: options.forceUnsafe === true,
     });
-    // Lint against the ONCE-per-invocation hoisted context (queue context +
+    // Lint against the once-per-invocation hoisted context (queue context +
     // queue-wide checkJs program + per-patch result cache) instead of
     // rebuilding ~37 s of setup for every patch in the loop.
     const projectedMetadata = { ...patch, ...updates };
@@ -212,17 +213,24 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
  * directory lock (a split write would let a concurrent queue mutation
  * leave body and `filesAffected` disagreeing), then keeps the run's
  * in-memory state honest: the queue context entry is refreshed and the
- * fresh lint result is stored keyed against the just-written body — the
- * state a repeat invocation will observe — and the in-memory
+ * fresh lint result is stored keyed against the just-written body (the
+ * state a repeat invocation will observe), and the in-memory
  * manifest row mirrors the on-disk write for later loop iterations
  * (notably `--all --scan`, where `getClaimedFiles` reads this manifest).
  */
 async function commitRefreshedPatch(args) {
     const { patch, paths, manifest, options, config, lintCtx, diffContent, updates } = args;
-    const bodyChanged = await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, updates, undefined, {
-        config,
-        command: 're-export',
-        forceUnsafe: options.forceUnsafe === true,
+    const bodyChanged = await updatePatchAndMetadata({
+        patchesDir: paths.patches,
+        filename: patch.filename,
+        newContent: diffContent,
+        updates,
+        onCommitted: undefined,
+        policyGate: {
+            config,
+            command: 're-export',
+            forceUnsafe: options.forceUnsafe === true,
+        },
     });
     refreshQueueCtxEntry(lintCtx, patch.filename, diffContent);
     if (args.lintResult !== null) {
@@ -238,8 +246,8 @@ async function commitRefreshedPatch(args) {
             };
         }
     }
-    // A bulk run refreshes every patch; saying "Re-exported" for one whose body
-    // did not move buries the patches that DID move. The run still counts this
+    // A bulk run refreshes every patch. Saying "Re-exported" for one whose body
+    // did not move buries the patches that did move. The run still counts this
     // patch as successfully refreshed, so `--stamp` completeness is unaffected.
     if (bodyChanged) {
         success(`Re-exported ${patch.filename}`);
@@ -250,7 +258,7 @@ async function commitRefreshedPatch(args) {
 }
 /**
  * Threads the patch's own `lintIgnore` list through so the per-patch
- * suppression honoured by export/export-all is also honoured here — a
+ * suppression honoured by export/export-all is also honoured here. A
  * re-export could otherwise not refresh an advisory-noisy but intentional
  * patch without the blunt `--skip-lint`. The paired `patch.tier` threads the
  * explicit branding-threshold opt-in the same way. The CLI flags `--tier`

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

@@ -9,7 +9,7 @@ import { loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
-import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '../utils/logger.js';
+import { cancel, info, intro, isCancel, outro, spinner, success, warn, } from '../utils/logger.js';
 import { loadScanFilesAssignments, withDryRunPurityGuard, withDryRunReExportLock, } from './re-export-bulk-scan.js';
 import { warnUnseenExpectedDrift } from './re-export-drift.js';
 import { reExportFilesInPlace } from './re-export-files.js';
@@ -26,15 +26,16 @@ async function resolveSelectedPatches(patches, options, manifest) {
         for (const identifier of patches) {
             const match = resolvePatchIdentifier(identifier, manifest.patches);
             if (!match) {
-                // Suggest, never dump: a wrong guess would otherwise print the
-                // whole ~300-entry manifest, burying the error it was reporting.
+                // Suggest close matches instead of dumping the queue: a wrong guess
+                // would otherwise print the whole ~300-entry manifest, burying the
+                // error it was reporting.
                 throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
             }
             selectedPatches.push(match);
         }
         return selectedPatches;
     }
-    // No patches specified — prompt or error
+    // No patches specified: prompt or error
     const isInteractive = stdioIsInteractive();
     if (!isInteractive) {
         throw new InvalidArgumentError('Specify patch identifiers or use --all in non-interactive mode.\n\n' +
@@ -143,7 +144,17 @@ export async function reExportCommand(projectRoot, patches, options) {
             const patchOptions = assignedScanFiles !== undefined ? { ...options, scanFiles: assignedScanFiles } : options;
             progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
             try {
-                const exported = await reExportSinglePatchWithIndexLockRetry(patch, paths, manifest, patchOptions, isDryRun, config, adjacentCtx, driftCtx, lintCtx);
+                const exported = await reExportSinglePatchWithIndexLockRetry({
+                    patch,
+                    paths,
+                    manifest,
+                    options: patchOptions,
+                    isDryRun,
+                    config,
+                    adjacentCtx,
+                    driftCtx,
+                    lintCtx,
+                });
                 if (exported) {
                     reExported++;
                     reExportedFilenames.push(patch.filename);
@@ -166,7 +177,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     }
     // `--stamp` only fires on a run where every selected patch refreshed
     // cleanly. A partial success would leave some patches with a stale body
-    // but a new version — the opposite of the "what I tested, what the
+    // but a new version, the opposite of the "what I tested, what the
     // manifest says" invariant `sourceEsrVersion` exists to record. A
     // non-empty `reExportedFilenames` with fewer entries than `selectedPatches`
     // means a lint failure or missing-file skip landed somewhere in the loop,
@@ -204,7 +215,7 @@ function buildForeignDriftContext(options) {
 /**
  * Names `--expect-unmanaged` paths that were never met this run. A typo'd
  * carve-out silently leaves the refusal armed for the path it was meant to
- * admit — and, worse, reads as an approval that is in force when it is not.
+ * admit, and reads as an approval that is in force when it is not.
  * A warning rather than a refusal: an approved path legitimately goes unmet
  * when the reviewed file has since been adopted into a patch, which is the
  * outcome the carve-out exists to be retired by.
@@ -227,19 +238,26 @@ function warnUnseenApprovedUnmanaged(adjacentCtx) {
 function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
     if (adjacentCtx.refusals.length > 0) {
         progress.error('Re-export refused');
-        const names = adjacentCtx.refusals.map((r) => r.patchFilename).join(', ');
-        throw new GeneralError(`Refused ${String(adjacentCtx.refusals.length)} patch(es) with adjacent unmanaged files ` +
-            `(--refuse-adjacent-unmanaged): ${names}. Adopt reviewed files with --scan --scan-file, ` +
-            `or export them as a new patch.`);
+        // Each offender is named with the owned directory that made it
+        // adjacent: an unattended run reads only this line, and without the
+        // anchor it cannot tell which of a multi-directory patch's locations
+        // the file sits beside.
+        const offenders = adjacentCtx.refusals
+            .map((r) => `${r.patchFilename} (${r.anchored.join(', ')})`)
+            .join('; ');
+        throw new GeneralError(`Refused ${adjacentCtx.refusals.length} patch(es) with adjacent unmanaged files ` +
+            `(--refuse-adjacent-unmanaged): ${offenders}. Adjacent means the file sits in a ` +
+            `directory the patch already owns a file in. Adopt reviewed files with ` +
+            `--scan --scan-file, or export them as a new patch.`);
     }
     if (driftCtx.refusals.length > 0) {
         progress.error('Re-export refused');
         const names = driftCtx.refusals.map((r) => r.patchFilename).join(', ');
         const unreadable = driftCtx.refusals.filter((r) => r.reason === 'baseline-unreadable');
         const unreadablePart = unreadable.length > 0
-            ? ` ${String(unreadable.length)} of these refused because the old patch body was missing or unreadable, so the drift comparison could not run (fail-closed).`
+            ? ` ${unreadable.length} of these refused because the old patch body was missing or unreadable, so the drift comparison could not run (fail-closed).`
             : '';
-        throw new GeneralError(`Refused ${String(driftCtx.refusals.length)} patch(es) whose refreshed body would absorb ` +
+        throw new GeneralError(`Refused ${driftCtx.refusals.length} patch(es) whose refreshed body would absorb ` +
             `engine edits not present in the old patch body (--refuse-foreign-drift): ${names}.${unreadablePart}\n\n` +
             'The flag cannot tell WHO wrote those lines, and the two populations have opposite ' +
             'remedies:\n' +
@@ -254,7 +272,7 @@ function throwRunLevelRefusals(adjacentCtx, driftCtx, progress) {
  * Prints the end-of-run summary and enforces the exit contract: a partial run
  * exits non-zero by default. "Re-exported 2 of 3" printing with exit 0 lets a
  * partial refresh ride an `&&` chain as success. The summary still prints
- * first so the honest "N of M" accounting stays visible; the throw then
+ * first so the honest "N of M" accounting stays visible. The throw then
  * carries the failed/skipped breakdown. Dry-run included: a preview
  * reporting that the real run would partially fail must not read as a passing
  * preview in scripts.
@@ -283,9 +301,9 @@ function reportReExportOutcome(args) {
     if (reExported < selectedCount) {
         const skippedCount = selectedCount - reExported - args.failedFilenames.length;
         const failedPart = args.failedFilenames.length > 0 ? ` Failed: ${args.failedFilenames.join(', ')}.` : '';
-        const skippedPart = skippedCount > 0 ? ` Skipped: ${String(skippedCount)} patch(es) (see warnings above).` : '';
-        throw new GeneralError(`${isDryRun ? '[dry-run] Would re-export' : 'Re-exported'} only ${String(reExported)} of ` +
-            `${String(selectedCount)} selected patch(es).${failedPart}${skippedPart} ` +
+        const skippedPart = skippedCount > 0 ? ` Skipped: ${skippedCount} patch(es) (see warnings above).` : '';
+        throw new GeneralError(`${isDryRun ? '[dry-run] Would re-export' : 'Re-exported'} only ${reExported} of ` +
+            `${selectedCount} selected patch(es).${failedPart}${skippedPart} ` +
             'Partial re-export exits non-zero so it cannot pass as success in scripts; ' +
             'the per-patch errors are listed above.');
     }

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

@@ -2,21 +2,22 @@
 /**
  * Rebase abort flow.
  */
-import { getProjectPaths, updateState } from '../../core/config.js';
+import { getProjectPaths } from '../../core/config.js';
 import { clearAppliedFurnaceState } from '../../core/furnace-config.js';
 import { resetChanges } from '../../core/git.js';
 import { clearRebaseSession, getRebaseSessionPath, readRebaseSession, } from '../../core/rebase-session.js';
 import { NoRebaseSessionError } from '../../errors/rebase.js';
 import { intro, outro, spinner, success, warn } from '../../utils/logger.js';
+import { clearPendingResolution } from '../pending-resolution.js';
 import { confirmDirtyEngineReset } from './confirm.js';
 /**
  * Handles `fireforge rebase --abort`.
  */
 export async function handleAbort(projectRoot, yes) {
     intro('FireForge Rebase — Abort');
-    // Abort is the escape hatch, so it deliberately does NOT require a *valid*
-    // session — only that one is present. Nothing below reads the session
-    // object (the restore works off `paths.engine` and `resetChanges`), and an
+    // Abort is the escape hatch, so it does not require a valid session, only
+    // that one is present. Nothing below reads the session object (the restore
+    // works off `paths.engine` and `resetChanges`), and an
     // `if (!session) throw` would refuse to run against a corrupt file, which
     // is the only thing that could have cleared it.
     const read = await readRebaseSession(projectRoot);
@@ -39,8 +40,8 @@ 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
+    // 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);
@@ -57,14 +58,8 @@ export async function handleAbort(projectRoot, yes) {
     // idempotently re-clear furnace state.
     await clearAppliedFurnaceState(projectRoot);
     // 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
+    await clearPendingResolution(projectRoot);
+    // 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.');

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

@@ -3,7 +3,7 @@
  * Rebase --continue flow.
  */
 import { join } from 'node:path';
-import { getProjectPaths, updateState } from '../../core/config.js';
+import { getProjectPaths } from '../../core/config.js';
 import { getStagedDiffForFiles } from '../../core/git-diff.js';
 import { stageFiles, unstageFiles } from '../../core/git-file-ops.js';
 import { updatePatchAndMetadata } from '../../core/patch-export.js';
@@ -14,13 +14,14 @@ import { GeneralError } from '../../errors/base.js';
 import { CorruptRebaseSessionError, NoRebaseSessionError, RebaseError, } from '../../errors/rebase.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, success, warn } from '../../utils/logger.js';
+import { clearPendingResolution } from '../pending-resolution.js';
 import { runPatchLoop } from './patch-loop.js';
 /**
  * Handles `fireforge rebase --continue`.
  */
 export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
     intro('FireForge Rebase — Continue');
-    // A present-but-unreadable session is NOT "no session in progress" — that
+    // A present-but-unreadable session is not "no session in progress". That
     // conflation is what made a corrupt file unrecoverable. Name the file and
     // point at --abort, which can now clear it.
     const read = await readRebaseSession(projectRoot);
@@ -33,10 +34,10 @@ export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
     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
+    // 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.
+    // 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, waitLockSeconds);
@@ -77,10 +78,15 @@ export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
         // updatePatchMetadata sequence can interleave with a concurrent export /
         // re-export / patch reorder / patch compact and leave the manifest
         // disagreeing with the freshly-written patch body. Mirrors resolve.ts.
-        await updatePatchAndMetadata(paths.patches, currentPatch.filename, diffContent, {
-            sourceEsrVersion: session.toVersion,
-            sourceVersion: session.toVersion,
-            ...(session.toProduct !== undefined ? { sourceProduct: session.toProduct } : {}),
+        await updatePatchAndMetadata({
+            patchesDir: paths.patches,
+            filename: currentPatch.filename,
+            newContent: diffContent,
+            updates: {
+                sourceEsrVersion: session.toVersion,
+                sourceVersion: session.toVersion,
+                ...(session.toProduct !== undefined ? { sourceProduct: session.toProduct } : {}),
+            },
         });
     }
     finally {
@@ -93,9 +99,10 @@ export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
     // 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 () => {
-        // Replaced, not mutated: flipping `status` in place leaves the
-        // failure's `error` and `conflictingFiles` on a now-resolved entry, and
-        // persist that to the session file. The union makes it impossible.
+        // The entry is replaced rather than mutated. Flipping `status` in place
+        // would leave the failure's `error` and `conflictingFiles` on a
+        // now-resolved entry and persist that to the session file. The union
+        // type rules that out.
         session.patches[session.currentIndex] = {
             filename: currentPatch.filename,
             status: 'resolved',
@@ -104,13 +111,7 @@ export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
         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;
-        });
+        await clearPendingResolution(projectRoot);
     });
     success(`Resolved ${currentPatch.filename}`);
     // Continue applying remaining patches

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

@@ -1,5 +1,5 @@
 /**
- * `fireforge rebase` — semi-automated Firefox source version upgrade.
+ * `fireforge rebase`: semi-automated Firefox source version upgrade.
  *
  * Orchestrates the full patch-rebase workflow:
  *   1. Reset engine to baseline

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge rebase` — semi-automated Firefox source version upgrade.
+ * `fireforge rebase`: semi-automated Firefox source version upgrade.
  *
  * Orchestrates the full patch-rebase workflow:
  *   1. Reset engine to baseline
@@ -17,7 +17,7 @@ import { clearAppliedFurnaceState } from '../../core/furnace-config.js';
 import { getHead, resetChanges } from '../../core/git.js';
 import { discoverPatches } from '../../core/patch-files.js';
 import { loadPatchesManifest } from '../../core/patch-manifest.js';
-import { getPatchSourceProduct, getPatchSourceVersion } from '../../core/patch-source-metadata.js';
+import { getPatchSourceVersion } from '../../core/patch-source-metadata.js';
 import { getRebaseSessionPath, readRebaseSession, saveRebaseSession, } from '../../core/rebase-session.js';
 import { GeneralError } from '../../errors/base.js';
 import { CorruptRebaseSessionError, RebaseSessionExistsError } from '../../errors/rebase.js';
@@ -33,7 +33,7 @@ async function handleFreshStart(projectRoot, options) {
     const isDryRun = options.dryRun === true;
     const maxFuzz = options.maxFuzz ?? 3;
     intro(isDryRun ? 'FireForge Rebase (dry run)' : 'FireForge Rebase');
-    // One read decides liveness AND validity: a pathExists pre-probe here left
+    // One read decides liveness and validity: a pathExists pre-probe here left
     // a window where the file vanished between probe and read, reporting
     // "already in progress" with no session on disk.
     const existing = await readRebaseSession(projectRoot);
@@ -59,7 +59,7 @@ async function handleFreshStart(projectRoot, options) {
     }
     // Determine the "from" version from the patches
     const patchVersions = new Set(manifest.patches.map((p) => getPatchSourceVersion(p)));
-    const patchProducts = new Set(manifest.patches.map((p) => getPatchSourceProduct(p)).filter(Boolean));
+    const patchProducts = new Set(manifest.patches.map((p) => p.sourceProduct).filter(Boolean));
     const sortedVersions = [...patchVersions].sort();
     const fromVersion = sortedVersions[0] ?? currentVersion;
     const fromProduct = [...patchProducts].sort()[0] ?? config.firefox.product;
@@ -93,7 +93,7 @@ async function handleFreshStart(projectRoot, options) {
     const resetSpinner = spinner('Resetting engine to baseline...');
     await resetChanges(paths.engine);
     resetSpinner.stop('Engine reset to baseline');
-    // Clear Furnace state — the engine no longer contains deployed components.
+    // Clear Furnace state: the engine no longer contains deployed components.
     await clearAppliedFurnaceState(projectRoot);
     // Create rebase session
     const allPatches = await discoverPatches(paths.patches);

package/dist/src/commands/rebase/patch-loop.d.ts

@@ -1,8 +1,8 @@
 /**
  * Patch application loop and re-export flow.
  */
-import type { getProjectPaths } from '../../core/config.js';
 import type { RebaseSession } from '../../core/rebase-session.js';
+import type { ProjectPaths } from '../../types/config.js';
 /**
  * Runs the patch application loop, re-exports applied patches, and stamps versions.
  *
@@ -12,4 +12,4 @@ import type { RebaseSession } from '../../core/rebase-session.js';
  * @param maxFuzz - Maximum context-reduction steps for `git apply -C<n>`
  * @param waitLockSeconds - `--wait-lock` budget for the patch-directory lock
  */
-export declare function runPatchLoop(projectRoot: string, session: RebaseSession, paths: ReturnType<typeof getProjectPaths>, maxFuzz: number, waitLockSeconds?: number): Promise<void>;
+export declare function runPatchLoop(projectRoot: string, session: RebaseSession, paths: ProjectPaths, maxFuzz: number, waitLockSeconds?: number): Promise<void>;

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

@@ -20,13 +20,14 @@ import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { error, info, outro, spinner, success, warn } from '../../utils/logger.js';
 import { isValidFirefoxVersion } from '../../utils/validation.js';
+import { clearPendingResolution } from '../pending-resolution.js';
 import { buildRebaseConflictSummary } from './conflict-summary.js';
 import { printSummary } from './summary.js';
 /**
  * Builds the session entry for a patch-apply outcome.
  *
- * Constructing a whole entry rather than assigning fields is what the
- * discriminated union buys: a status can never be flipped while the previous
+ * The entry is constructed whole rather than assigned field by field, so the
+ * discriminated union stops a status being flipped while the previous
  * status's payload stays behind, which is how
  * `{ status: 'resolved', error, conflictingFiles }` reaches the session file.
  *
@@ -67,9 +68,10 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
         const patchFile = allPatches.find((p) => p.filename === entry.filename);
         if (!patchFile) {
             warn(`Patch file not found for ${entry.filename}, skipping.`);
-            // Replaced, not mutated: the entry is a discriminated union, so a status
-            // change is a new value rather than a field assignment. That is what
-            // stops a status flip stranding the previous status's payload.
+            // The entry is replaced rather than mutated: it is a discriminated
+            // union, so a status change is a new value rather than a field
+            // assignment, and a status flip cannot strand the previous status's
+            // payload.
             session.patches[i] = { filename: entry.filename, status: 'skipped' };
             session.currentIndex = i + 1;
             await saveRebaseSession(projectRoot, session);
@@ -100,9 +102,9 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
         }
         else {
             // 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.
+            // critical section, since it is advisory UX rather than 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: {
@@ -144,7 +146,7 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
     s.stop('All patches applied');
     // 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
+    // files were not refreshed, so 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.
@@ -163,7 +165,7 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
             `still describe the pre-rebase source. Re-export them manually (e.g. ` +
             `"fireforge re-export") and verify the overlapping hunks before the next import.`);
     }
-    // Stamp versions — only for patches whose .patch file now actually
+    // Stamp versions, only for patches whose .patch file now actually
     // reflects the new source (overlap-skipped ones keep their old stamp so
     // the queue does not lie about what each patch was tested against).
     const overlapSkippedSet = new Set(overlapSkipped);
@@ -176,19 +178,19 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
     }
     // Stamp every Furnace override's `baseVersion` to match the rebased
     // Firefox source version. Without it, a successful source bump leaves
-    // overrides in a doctor-failing drift state — each still claiming the
-    // pre-rebase source as its baseline — and every subsequent
+    // overrides in a doctor-failing drift state, each still claiming the
+    // pre-rebase source as its baseline, and every subsequent
     // `fireforge doctor` fails `Furnace component validation`. The stamp is
     // unconditional per the helper's contract: rebase already succeeded on
     // the patch side, so the operator is committing to the new source
-    // baseline; per-component health checking stays with
+    // baseline. Per-component health checking stays with
     // `fireforge furnace validate` / `doctor --repair-furnace`.
     //
     // "Unconditional" means unconditional on component health, not on the
     // value: `stampFurnaceOverrideBaseVersions` assigns and persists whatever
     // string it is handed, so a session whose `toVersion` is not a real
     // Firefox version would rewrite every override's baseline to that value.
-    // `isValidSession` rejects such a session at read time; this refuses to
+    // `isValidSession` rejects such a session at read time. This refuses to
     // persist it even if a future caller reaches here another way.
     if (!isValidFirefoxVersion(session.toVersion)) {
         throw new RebaseError(`Refusing to stamp Furnace override baseVersion(s): the rebase session's target version ` +
@@ -208,13 +210,7 @@ export async function runPatchLoop(projectRoot, session, paths, maxFuzz, waitLoc
     await clearRebaseSession(projectRoot);
     // 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;
-    });
+    await clearPendingResolution(projectRoot);
     info('');
     success(`All patches re-exported with sourceVersion=${session.toVersion}`);
     outro('Rebase complete!');
@@ -225,13 +221,13 @@ async function reExportAppliedPatches(session, paths, waitLockSeconds) {
     const manifest = await loadPatchesManifest(paths.patches);
     if (!manifest)
         return { failures, overlapSkipped };
-    // Re-export writes `getDiffForFilesAgainstHead(files)` — the CUMULATIVE
+    // Re-export writes `getDiffForFilesAgainstHead(files)`, the cumulative
     // diff of those files. For a file claimed by two patches (a supported
-    // `--allow-overlap` queue), that diff contains BOTH patches' hunks, so
+    // `--allow-overlap` queue), that diff contains both patches' hunks, so
     // rewriting each patch with it would duplicate the shared file's hunks
     // into every owner: the very next import then fails or silently
     // double-materialises. Refuse to auto-re-export any patch whose files
-    // overlap another patch; the operator re-exports those manually where
+    // overlap another patch. The operator re-exports those manually where
     // per-patch attribution is possible.
     const fileOwners = new Map();
     for (const patch of manifest.patches) {