@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch split <source> --files <p...> --name <n>` — moves files
+ * `fireforge patch split <source> --files <p...> --name <n>` moves files
  * out of an existing patch into a brand-new patch as one transaction.
  *
  * Splitting a patch whose files have inbound forward-imports otherwise
  * requires a precise manual order: re-point each staged-dependency owner at
  * a not-yet-created patch, shrink the source via
- * `re-export --files --allow-shrink`, then `export --order` — any other
+ * `re-export --files --allow-shrink`, then `export --order`. Any other
  * order refuses or needs `--force-unsafe`. Split performs the shrink, the
  * new-patch creation, and the dependent owner rewrites under one
  * patch-directory lock with rollback, validating only the final projection.
@@ -18,8 +18,8 @@
 import { join } from 'node:path';
 import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
-import { appendHistory, assertConfirmationAvailable, confirmDestructive, } from '../../core/destructive.js';
-import { normalizePatchArtifact } from '../../core/patch-artifact-normalize.js';
+import { assertConfirmationAvailable, confirmDestructive } from '../../core/destructive.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
@@ -30,7 +30,8 @@ import { toError } from '../../utils/errors.js';
 import { readText, removeFile, writeText } from '../../utils/fs.js';
 import { info, intro, outro, success, warn } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
-import { normalizePatchDisplayName } from '../../utils/validation.js';
+import { normalizePatchDisplayName, parsePositiveIntegerFlag } from '../../utils/validation.js';
+import { proceedAfterDecision } from '../destructive-decision.js';
 import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
 import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, mergeStagedForwardImports, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
@@ -68,9 +69,9 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
                 await renumberPatchesInManifest(patchesDir, plan.placement.renameMap);
                 renumberApplied = true;
             }
-            await writeText(newPatchPath, normalizePatchArtifact(plan.movedDiff));
+            await writeText(newPatchPath, plan.movedDiff);
             newPatchWritten = true;
-            await writeText(sourcePathAfter, normalizePatchArtifact(plan.remainingDiff));
+            await writeText(sourcePathAfter, plan.remainingDiff);
             sourceRewritten = true;
             const fresh = await loadPatchesManifest(patchesDir);
             if (!fresh)
@@ -91,31 +92,26 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
             updatedPatches.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
             const updated = validatePatchesManifest({ ...fresh, patches: updatedPatches });
             await savePatchesManifest(patchesDir, updated);
-            try {
-                await appendHistory(patchesDir, {
-                    operation: 'patch-split',
-                    args: {
-                        source: effectiveSourceFilename,
-                        newFilename: plan.placement.newFilename,
-                        order: plan.placement.insertionOrder,
-                        files: plan.movedFiles,
-                        ownerRewrites: plan.ownerRewrites,
-                        renames: [...plan.placement.renameMap.entries()].map(([from, entry]) => ({
-                            from,
-                            to: entry.newFilename,
-                        })),
-                    },
-                    ...(options.yes === true ? { yes: true } : {}),
-                    ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
-                    result: 'ok',
-                });
-            }
-            catch (historyError) {
-                warn(`History log append failed after patch split committed: ${toError(historyError).message}`);
-            }
+            await appendHistoryBestEffort(patchesDir, {
+                operation: 'patch-split',
+                args: {
+                    source: effectiveSourceFilename,
+                    newFilename: plan.placement.newFilename,
+                    order: plan.placement.insertionOrder,
+                    files: plan.movedFiles,
+                    ownerRewrites: plan.ownerRewrites,
+                    renames: [...plan.placement.renameMap.entries()].map(([from, entry]) => ({
+                        from,
+                        to: entry.newFilename,
+                    })),
+                },
+                ...(options.yes === true ? { yes: true } : {}),
+                ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
+                result: 'ok',
+            }, `patch split committed`);
         }
         catch (error) {
-            // Reverse-order rollback; each step warns on its own failure so the
+            // Reverse-order rollback. Each step warns on its own failure so the
             // original error stays visible.
             if (sourceRewritten) {
                 try {
@@ -164,7 +160,7 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
  */
 export async function patchSplitCommand(projectRoot, sourceId, options) {
     intro(options.dryRun ? 'FireForge patch split (dry run)' : 'FireForge patch split');
-    // Refuse a prompt-less run BEFORE the diff/lint work, not after it.
+    // Refuse a prompt-less run before doing the diff/lint work.
     assertConfirmationAvailable('patch split', options);
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
@@ -197,7 +193,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
             (options.order === undefined && options.before === undefined ? source.filename : undefined),
     });
     const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name, config);
-    // The filename slug pipeline strips redundant category prefixes; the
+    // The filename slug pipeline strips redundant category prefixes. The
     // manifest display name must agree with the bare-slug naming policy,
     // exactly as `export --name` already does.
     const displayName = normalizePatchDisplayName(options.name, category);
@@ -226,8 +222,26 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
     // instead of linting each projected body blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
     const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, source.tier);
-    await runPatchLint(paths.engine, movedFiles, movedDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, source.tier);
+    await runPatchLint({
+        engineDir: paths.engine,
+        filesAffected: remainingFiles,
+        diffContent: remainingDiff,
+        config,
+        skipLint: options.skipLint,
+        patchQueueCtx,
+        ignoreChecks,
+        patchTier: source.tier,
+    });
+    await runPatchLint({
+        engineDir: paths.engine,
+        filesAffected: movedFiles,
+        diffContent: movedDiff,
+        config,
+        skipLint: options.skipLint,
+        patchQueueCtx,
+        ignoreChecks,
+        patchTier: source.tier,
+    });
     const { conflicts, stagedDependencyAdditions } = runProjectedSplitLint(plan, patchQueueCtx);
     plan.stagedDependencyAdditions = stagedDependencyAdditions;
     const newMetadata = buildNewPatchMetadata(plan, config);
@@ -246,14 +260,8 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         unsafeOverride: options.forceUnsafe === true,
         conflicts,
     });
-    if (decision === 'dry-run') {
-        outro('Dry run complete — no changes made');
-        return;
-    }
-    if (decision === 'declined') {
-        outro('Split cancelled');
+    if (!proceedAfterDecision(decision, 'Split cancelled'))
         return;
-    }
     await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
     success(`Split ${source.filename}: ${placement.newFilename} now owns ${plan.movedFiles.length} file(s)`);
     if (plan.ownerRewrites.length > 0) {
@@ -273,13 +281,7 @@ export function registerPatchSplit(parent, context) {
         .requiredOption('--name <name>', 'Name for the new patch')
         .option('--category <category>', "Category for the new patch (default: the source patch's)")
         .option('--description <desc>', 'Description for the new patch')
-        .option('--order <n>', 'Exact sparse order for the new patch', commanderArgParser((raw) => {
-        const n = Number.parseInt(raw, 10);
-        if (!Number.isInteger(n) || n <= 0) {
-            throw new InvalidArgumentError(`--order must be a positive integer, got "${raw}".`, '--order');
-        }
-        return n;
-    }))
+        .option('--order <n>', 'Exact sparse order for the new patch', commanderArgParser((raw) => parsePositiveIntegerFlag('--order', raw)))
         .option('--before <patch>', 'Place the new patch before this patch')
         .option('--after <patch>', 'Place the new patch after this patch (default: the source patch)')
         .option('--dry-run', 'Show what would happen without writing')

package/dist/src/commands/patch/staged-dependency-validate.d.ts

@@ -7,7 +7,7 @@ interface StagedDependencyShape {
 }
 /**
  * Validates the `--add` declaration fields against the loaded queue.
- * Throws on a clear flag mixup; warns (only) when `--owner` is
+ * Throws on a clear flag mixup. Warns (only) when `--owner` is
  * well-formed but absent from the queue, because the owner may
  * legitimately be exported moments later and renumbering rewrites owners.
  */

package/dist/src/commands/patch/staged-dependency-validate.js

@@ -2,8 +2,8 @@
 /**
  * Shape validation for `patch staged-dependency --add`.
  *
- * `--creates`/`--file` take engine-relative FILE paths and `--owner` takes a
- * patch FILENAME. Accepting all three as arbitrary strings lets a
+ * `--creates`/`--file` take engine-relative file paths, while `--owner`
+ * takes a patch filename. Accepting all three as arbitrary strings lets a
  * `--creates <patch-name>` mixup produce a declaration nothing can ever
  * discharge, surfacing only later as a `staged-dependency-unused` warning.
  * Refusals here fire only on a clear patch-name shape (slash-free values
@@ -28,7 +28,7 @@ function refusePatchShapedPath(flag, value, role, queuePatches) {
 }
 /**
  * Validates the `--add` declaration fields against the loaded queue.
- * Throws on a clear flag mixup; warns (only) when `--owner` is
+ * Throws on a clear flag mixup. Warns (only) when `--owner` is
  * well-formed but absent from the queue, because the owner may
  * legitimately be exported moments later and renumbering rewrites owners.
  */

package/dist/src/commands/patch/staged-dependency.d.ts

@@ -1,5 +1,5 @@
 /**
- * `fireforge patch staged-dependency <name>` — edits
+ * `fireforge patch staged-dependency <name>` edits
  * PatchMetadata.stagedDependencies without rewriting the .patch body.
  */
 import { Command } from 'commander';

package/dist/src/commands/patch/staged-dependency.js

@@ -1,14 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch staged-dependency <name>` — edits
+ * `fireforge patch staged-dependency <name>` edits
  * PatchMetadata.stagedDependencies without rewriting the .patch body.
  */
 import { Command } from 'commander';
-import { appendHistory } from '../../core/destructive.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { mutatePatchMetadata } from '../../core/patch-export.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
-import { toError } from '../../utils/errors.js';
-import { info, intro, outro, warn } from '../../utils/logger.js';
+import { info, intro, outro } from '../../utils/logger.js';
 import { addWaitLockOption, resolveWaitLockSeconds } from '../../utils/options.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
@@ -86,7 +85,7 @@ function requireRegistrationOptions(options) {
 /**
  * Resolves the `--remove` target for forward-imports:
  * `--file` + `--specifier` suffice when they identify at most one staged
- * entry — `--creates` is inferred from a unique match, an ambiguous match
+ * entry. `--creates` is inferred from a unique match, an ambiguous match
  * refuses with the candidate list, and no match falls through to the
  * honest "no staged forward-import matched" summary.
  */
@@ -113,7 +112,7 @@ function resolveImportRemovalTarget(options, staged) {
         const list = candidates
             .map((entry) => `  - ${dependencyLabel('import', importView(entry))}`)
             .join('\n');
-        throw new GeneralError(`--remove matches ${String(candidates.length)} staged forward-imports on this patch; ` +
+        throw new GeneralError(`--remove matches ${candidates.length} staged forward-imports on this patch; ` +
             `pass --creates to pick one:\n${list}`);
     }
     return { file, specifier, creates: '(no match)' };
@@ -142,7 +141,7 @@ function resolveRegistrationRemovalTarget(options, staged) {
         const list = candidates
             .map((entry) => `  - ${dependencyLabel('registration', registrationView(entry))}`)
             .join('\n');
-        throw new GeneralError(`--remove matches ${String(candidates.length)} staged registrations on this patch; ` +
+        throw new GeneralError(`--remove matches ${candidates.length} staged registrations on this patch; ` +
             `pass --creates to pick one:\n${list}`);
     }
     return { file, line, creates: '(no match)' };
@@ -218,7 +217,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     intro(isDryRun ? 'FireForge patch staged-dependency (dry run)' : 'FireForge patch staged-dependency');
     const mode = modeFromOptions(options);
     const kind = kindFromOptions(options);
-    // The patch queue loads BEFORE the declaration fields resolve so
+    // The patch queue loads before the declaration fields resolve so
     // `--remove` can infer `--creates` from the target patch's staged
     // entries.
     const { paths, manifest } = await requirePatchQueue(projectRoot);
@@ -233,9 +232,9 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
         : mode === 'add'
             ? requireRegistrationOptions(options)
             : resolveRegistrationRemovalTarget(options, targetPatch.stagedDependencies);
-    // Shape-check --add declarations against the loaded queue:
-    // a patch-name-shaped --creates/--file is refused HERE instead of
-    // surfacing later as an undischargeable staged-dependency-unused.
+    // Shape-check --add declarations against the loaded queue: a
+    // patch-name-shaped --creates/--file is refused now instead of surfacing
+    // later as an undischargeable staged-dependency-unused.
     if (mode === 'add') {
         const added = importDependency ?? registrationDependency;
         if (added !== undefined) {
@@ -280,23 +279,18 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     const before = result.before.stagedDependencies;
     const after = result.after.stagedDependencies;
     info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, target)}.`);
-    try {
-        await appendHistory(paths.patches, {
-            operation: 'patch-staged-dependency',
-            args: {
-                filename: targetPatch.filename,
-                mode,
-                kind,
-                before: before ?? {},
-                after: after ?? {},
-            },
-            ...(options.yes === true ? { yes: true } : {}),
-            result: 'ok',
-        });
-    }
-    catch (historyError) {
-        warn(`History log append failed after patch staged-dependency committed (${targetPatch.filename}): ${toError(historyError).message}`);
-    }
+    await appendHistoryBestEffort(paths.patches, {
+        operation: 'patch-staged-dependency',
+        args: {
+            filename: targetPatch.filename,
+            mode,
+            kind,
+            before: before ?? {},
+            after: after ?? {},
+        },
+        ...(options.yes === true ? { yes: true } : {}),
+        result: 'ok',
+    }, `patch staged-dependency committed (${targetPatch.filename})`);
     outro('Patch staged-dependency complete');
 }
 /**

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

@@ -1,9 +1,9 @@
 /**
- * `fireforge patch tier <name>` — sets or clears `PatchMetadata.tier` on a
+ * `fireforge patch tier <name>` sets or clears `PatchMetadata.tier` on a
  * single patch without rewriting the `.patch` file body.
  *
  * Companion to `fireforge re-export <name> --tier <tier>`. Re-export is the
- * right tool when the patch body itself needs regenerating; this subcommand
+ * right tool when the patch body itself needs regenerating. This subcommand
  * covers the metadata-only adjustment, where the operator has discovered
  * (from a `lint --per-patch` warning, say) that the threshold-tier override
  * should be set but the patch body is already correct. Avoiding the

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

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch tier <name>` — sets or clears `PatchMetadata.tier` on a
+ * `fireforge patch tier <name>` sets or clears `PatchMetadata.tier` on a
  * single patch without rewriting the `.patch` file body.
  *
  * Companion to `fireforge re-export <name> --tier <tier>`. Re-export is the
- * right tool when the patch body itself needs regenerating; this subcommand
+ * right tool when the patch body itself needs regenerating. This subcommand
  * covers the metadata-only adjustment, where the operator has discovered
  * (from a `lint --per-patch` warning, say) that the threshold-tier override
  * should be set but the patch body is already correct. Avoiding the
@@ -15,12 +15,13 @@
  * `--clear` must be supplied per invocation.
  */
 import { Command, Option } from 'commander';
-import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { confirmDestructive } from '../../core/destructive.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { updatePatchMetadata } from '../../core/patch-export.js';
 import { InvalidArgumentError } from '../../errors/base.js';
-import { toError } from '../../utils/errors.js';
-import { info, intro, outro, warn } from '../../utils/logger.js';
+import { info, intro, outro } from '../../utils/logger.js';
 import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
+import { proceedAfterDecision } from '../destructive-decision.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
  * Runs the `patch tier` command: updates `PatchMetadata.tier` on the
@@ -34,8 +35,8 @@ export async function patchTierCommand(projectRoot, identifier, options = {}) {
     const isDryRun = options.dryRun === true;
     intro(isDryRun ? 'FireForge patch tier (dry run)' : 'FireForge patch tier');
     // Mode mutex: a single invocation either sets or clears the tier.
-    // Combining both is ambiguous — the operator's intent is not obvious
-    // and silently picking one would mask the typo.
+    // Combining both is ambiguous: the operator's intent is not obvious and
+    // silently picking one would mask the typo.
     const setting = options.tier !== undefined;
     const clearing = options.clear === true;
     if (setting && clearing) {
@@ -71,16 +72,10 @@ export async function patchTierCommand(projectRoot, identifier, options = {}) {
         yes: options.yes === true,
         dryRun: isDryRun,
     });
-    if (decision === 'dry-run') {
-        outro('Dry run complete — no changes made');
+    if (!proceedAfterDecision(decision, 'Cancelled — no changes made'))
         return;
-    }
-    if (decision === 'declined') {
-        outro('Cancelled — no changes made');
-        return;
-    }
     // Single write under the patch directory lock (delegated inside
-    // updatePatchMetadata). Setting routes through `updates`; clearing
+    // updatePatchMetadata). Setting routes through `updates`. Clearing
     // routes through `unsetFields` so TypeScript's exact optional types
     // do not have to carry an explicit `undefined` on the `tier` field.
     if (after !== undefined) {
@@ -92,21 +87,16 @@ export async function patchTierCommand(projectRoot, identifier, options = {}) {
     else {
         await updatePatchMetadata(paths.patches, target.filename, {}, ['tier']);
     }
-    try {
-        await appendHistory(paths.patches, {
-            operation: 'patch-tier',
-            args: {
-                filename: target.filename,
-                ...(before !== undefined ? { before } : {}),
-                ...(after !== undefined ? { after } : {}),
-            },
-            ...(options.yes === true ? { yes: true } : {}),
-            result: 'ok',
-        });
-    }
-    catch (historyError) {
-        warn(`History log append failed after patch tier committed (${target.filename}): ${toError(historyError).message}`);
-    }
+    await appendHistoryBestEffort(paths.patches, {
+        operation: 'patch-tier',
+        args: {
+            filename: target.filename,
+            ...(before !== undefined ? { before } : {}),
+            ...(after !== undefined ? { after } : {}),
+        },
+        ...(options.yes === true ? { yes: true } : {}),
+        result: 'ok',
+    }, `patch tier committed (${target.filename})`);
     info(`${target.filename}: ${action}.`);
     outro('Patch tier complete');
 }

package/dist/src/commands/patch-rename-map.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Structural equality for patch rename maps, shared by the placement-mode
+ * export preview/commit check (`export-flow.ts`) and `patch reorder`'s
+ * under-lock drift check. Both previously carried a byte-identical copy of
+ * the sorted-entries comparison. One helper keeps the two commit gates from
+ * drifting.
+ */
+import type { PatchRenameEntry } from '../core/patch-manifest.js';
+/**
+ * Rename-map entries ordered by target order, so previews, history entries
+ * and equality checks all walk the queue in its final on-disk order.
+ */
+export declare function getSortedRenameEntries(renameMap: Map<string, PatchRenameEntry>): Array<[string, PatchRenameEntry]>;
+/**
+ * Compares two rename maps entry by entry after sorting both by target
+ * order. Equal when every (current filename, new filename, new order)
+ * triple matches positionally.
+ */
+export declare function renameMapsEqual(left: Map<string, PatchRenameEntry>, right: Map<string, PatchRenameEntry>): boolean;

package/dist/src/commands/patch-rename-map.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Structural equality for patch rename maps, shared by the placement-mode
+ * export preview/commit check (`export-flow.ts`) and `patch reorder`'s
+ * under-lock drift check. Both previously carried a byte-identical copy of
+ * the sorted-entries comparison. One helper keeps the two commit gates from
+ * drifting.
+ */
+/**
+ * Rename-map entries ordered by target order, so previews, history entries
+ * and equality checks all walk the queue in its final on-disk order.
+ */
+export function getSortedRenameEntries(renameMap) {
+    return Array.from(renameMap.entries()).sort((a, b) => a[1].newOrder - b[1].newOrder);
+}
+/**
+ * Compares two rename maps entry by entry after sorting both by target
+ * order. Equal when every (current filename, new filename, new order)
+ * triple matches positionally.
+ */
+export function renameMapsEqual(left, right) {
+    const leftEntries = getSortedRenameEntries(left);
+    const rightEntries = getSortedRenameEntries(right);
+    if (leftEntries.length !== rightEntries.length) {
+        return false;
+    }
+    return leftEntries.every(([leftFilename, leftEntry], index) => {
+        const rightTuple = rightEntries[index];
+        if (!rightTuple)
+            return false;
+        const [rightFilename, rightEntry] = rightTuple;
+        return (leftFilename === rightFilename &&
+            leftEntry.newFilename === rightEntry.newFilename &&
+            leftEntry.newOrder === rightEntry.newOrder);
+    });
+}

package/dist/src/commands/pending-resolution.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Clears `pendingResolution` from `state.json` transactionally.
+ *
+ * Five commands (`doctor --clear-resolution`, `resolve`, `rebase --continue`,
+ * `rebase --abort`, and the rebase patch loop) had each copied the same
+ * spread-then-`delete` updater. The clear routes through `updateState` instead
+ * of a load/modify/save pair so the updater runs inside the state-file lock
+ * against the freshest on-disk state: a concurrent write to an unrelated key
+ * (`buildMode`, `baseCommit`) is then not clobbered by a stale reload. Keeping
+ * it in one place stops the copies from drifting apart.
+ *
+ * A no-op when nothing is pending, so callers need no guard of their own.
+ * @param projectRoot - Project root holding `.fireforge/state.json`.
+ */
+export declare function clearPendingResolution(projectRoot: string): Promise<void>;

package/dist/src/commands/pending-resolution.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { updateState } from '../core/config.js';
+/**
+ * Clears `pendingResolution` from `state.json` transactionally.
+ *
+ * Five commands (`doctor --clear-resolution`, `resolve`, `rebase --continue`,
+ * `rebase --abort`, and the rebase patch loop) had each copied the same
+ * spread-then-`delete` updater. The clear routes through `updateState` instead
+ * of a load/modify/save pair so the updater runs inside the state-file lock
+ * against the freshest on-disk state: a concurrent write to an unrelated key
+ * (`buildMode`, `baseCommit`) is then not clobbered by a stale reload. Keeping
+ * it in one place stops the copies from drifting apart.
+ *
+ * A no-op when nothing is pending, so callers need no guard of their own.
+ * @param projectRoot - Project root holding `.fireforge/state.json`.
+ */
+export async function clearPendingResolution(projectRoot) {
+    await updateState(projectRoot, (current) => {
+        if (!current.pendingResolution)
+            return current;
+        const next = { ...current };
+        delete next.pendingResolution;
+        return next;
+    });
+}

package/dist/src/commands/re-export-adjacent.d.ts

@@ -1,5 +1,5 @@
-import type { getProjectPaths } from '../core/config.js';
 import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+import type { ProjectPaths } from '../types/config.js';
 /**
  * Shared per-run context for the adjacency advisory: the classification
  * inputs computed once by `reExportCommand`, plus the collection of
@@ -18,24 +18,46 @@ export interface AdjacentUnmanagedContext {
     approvedUnmanaged: ReadonlySet<string>;
     /** Approved paths actually met this run, so unused ones can be surfaced. */
     approvedSeen: Set<string>;
+    /**
+     * Offenders collected across the loop. `files` stays the bare paths that
+     * downstream consumers already read. `anchored` carries the same entries
+     * with the owned directory that made each one adjacent, so the run-level
+     * refusal can name the anchor without re-deriving it.
+     */
     refusals: {
         patchFilename: string;
         files: string[];
+        anchored: string[];
     }[];
 }
 /** Returns the subset of `files` that no longer exist under `engineDir`. */
 export declare function findMissingFiles(engineDir: string, files: readonly string[]): Promise<string[]>;
+/**
+ * One unmanaged file and the owned directory that made it adjacent.
+ *
+ * The anchor is what an unattended run could not previously recover: the
+ * notice named the offending file and the patch, but not which of the
+ * patch's owned locations the file sits beside, so triaging a refusal on a
+ * patch that owns files in several directories meant re-deriving the
+ * adjacency by hand from the manifest.
+ */
+export interface AdjacentUnmanagedFile {
+    /** Engine-relative path of the unmanaged file. */
+    file: string;
+    /** Directory holding at least one file this patch owns. */
+    anchorDir: string;
+}
 /**
  * Emits the scan-less advisory for one patch: missing manifest files and
  * unmanaged files adjacent to the patch's ownership. When
  * `--refuse-adjacent-unmanaged` is set and any unmanaged adjacent file
- * exists, records the patch into `ctx.refusals` and returns true — the
+ * exists, records the patch into `ctx.refusals` and returns true. The
  * caller then skips the write for this patch and converts the collection
  * into one run-level non-zero refusal after the loop.
  */
 export declare function reportAdjacentUnmanagedFiles(args: {
     patch: PatchMetadata;
-    paths: ReturnType<typeof getProjectPaths>;
+    paths: ProjectPaths;
     manifest: PatchesManifest;
     currentFilesAffected: readonly string[];
     ctx: AdjacentUnmanagedContext;