@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/commands/doctor-furnace-manifest-sync.js

@@ -15,31 +15,41 @@
  * Lives in a sibling module to keep `doctor-furnace.ts` under the
  * per-file LOC budget.
  */
-import { readdir, rm } from 'node:fs/promises';
+import { readdir, rmdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { withFileLock } from '../core/file-lock.js';
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig } from '../core/furnace-config.js';
+import { getFurnaceLockPath } from '../core/furnace-operation.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readJson } from '../utils/fs.js';
+import { pathExistsStrict, readJson } from '../utils/fs.js';
 import { failure, ok, warning } from './doctor-check-core.js';
+/**
+ * Lists component directories, distinguishing "none" from "could not look".
+ *
+ * A missing directory is genuinely empty. A `readdir` failure is not: this
+ * check exists to detect the concurrent-override orphan race, and swallowing
+ * the error into `[]` made it report clean for the one condition it is here
+ * to catch. The caller surfaces the failure instead.
+ */
 async function listComponentDirs(dir) {
-    if (!(await pathExists(dir)))
-        return [];
-    try {
-        const entries = await readdir(dir, { withFileTypes: true });
-        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
-    }
-    catch {
+    // `pathExistsStrict`, not `pathExists`: the latter answers `false` for EVERY
+    // access error, so an unreadable components directory reported "no orphans",
+    // i.e. a clean check — the same fail-open the comment above rejects for
+    // `readdir`. Only ENOENT means genuinely absent.
+    if (!(await pathExistsStrict(dir)))
         return [];
-    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
 }
 async function recoverOverrideConfig(overrideDir, name) {
     // `furnace override` writes `override.json` alongside the copied files.
     // That sidecar is enough to reconstruct the furnace.json entry lost to
     // a concurrent-write race (eval 2: second override wrote back the
     // outer-snapshot config, dropping the sibling write's addition).
+    // No `pathExists` precheck: it collapses "absent" and "unreadable" into the
+    // same `false`, and both outcomes lead here anyway — a missing file lands in
+    // the catch below with the same `undefined` result.
     const sidecarPath = join(overrideDir, name, 'override.json');
-    if (!(await pathExists(sidecarPath)))
-        return undefined;
     try {
         const raw = await readJson(sidecarPath);
         const type = raw.type;
@@ -59,11 +69,18 @@ async function recoverOverrideConfig(overrideDir, name) {
             baseVersion,
         };
         if (typeof raw.baseCommit === 'string') {
+            // `baseCommit` is already declared optional on OverrideComponentConfig,
+            // so the intersection this replaced widened nothing.
             restored.baseCommit = raw.baseCommit;
         }
         return restored;
     }
     catch {
+        // Unreadable or malformed sidecar. Returning `undefined` here is the same
+        // value as "no sidecar present", so the caller reports the override as
+        // unrecoverable — which is the safe direction (it never invents config),
+        // but the operator sees "no valid override.json" rather than "the
+        // override.json is corrupt". The remediation is identical either way.
         return undefined;
     }
 }
@@ -95,61 +112,139 @@ function formatOrphanSummary(orphans) {
     const description = [overrideLabel, customLabel].filter(Boolean).join(' and ');
     return `Found orphaned component ${overrideCount + customCount === 1 ? 'directory' : 'directories'} on disk: ${description}. furnace.json does not list these — a previous mutation may have lost a concurrent write.`;
 }
-async function repairOrphanOverrides(projectRoot, orphans) {
-    const restored = [];
-    const unrecoverable = [];
-    if (orphans.length === 0)
-        return { restored, unrecoverable };
-    const freshConfig = await loadFurnaceConfig(projectRoot);
+function emptyOutcome() {
+    return {
+        restored: [],
+        unrecoverable: [],
+        reconciled: [],
+        deleted: [],
+        retained: [],
+        errors: [],
+    };
+}
+/**
+ * Re-registers override orphans and deletes empty custom orphan directories,
+ * under ONE furnace lock held across both.
+ *
+ * Two things this must not do, both of which reproduce the lost-write race the
+ * check exists to clean up after:
+ *
+ * 1. Write back a decision made before the lock. The orphan list is computed
+ *    from a config snapshot loaded well before we hold anything, so by the
+ *    time we can write, a concurrent `furnace override` may have registered
+ *    the same name — writing our sidecar-reconstructed entry over it discards
+ *    a live write, and a concurrent `furnace create` registering the name
+ *    under `custom` would leave it in BOTH maps, a state nothing validates.
+ *    Every orphan is therefore re-checked against `freshConfig` inside the
+ *    lock and skipped when it is no longer orphaned.
+ * 2. Delete custom directories outside the lock. `repairCustomOrphans` used to
+ *    run after the lock was released, so a `furnace create` that had
+ *    registered a name and not yet populated its directory had that directory
+ *    deleted underneath it.
+ */
+async function repairOrphans(projectRoot, orphans) {
+    const outcome = emptyOutcome();
+    if (orphans.overrides.length === 0 && orphans.customNames.length === 0)
+        return outcome;
+    const lockPath = getFurnaceLockPath(projectRoot);
+    // One catch covers four distinct phases; naming the one that failed keeps
+    // the report honest — a lock timeout used to render as "failed while
+    // writing furnace.json", the phase least likely to have been reached.
+    // Held in an object rather than two `let`s: the lock callback mutates them
+    // from inside a closure, and TS's control-flow analysis does not propagate
+    // that through the call — it would narrow both to their initial literals in
+    // the catch below.
+    const progress = { phase: 'waiting for the furnace lock', persisted: false };
+    try {
+        await withFileLock(lockPath, async () => {
+            progress.phase = 'loading furnace.json under the lock';
+            const freshConfig = await loadFurnaceConfig(projectRoot);
+            repairOverridesLocked(freshConfig, orphans.overrides, outcome);
+            if (outcome.restored.length > 0) {
+                progress.phase = 'writing furnace.json';
+                await writeFurnaceConfig(projectRoot, freshConfig);
+            }
+            // From here the restore (if any) is on disk; a later failure must not
+            // report the whole repair as if it never happened.
+            progress.persisted = true;
+            progress.phase = 'cleaning custom orphan directories';
+            await deleteEmptyCustomOrphans(projectRoot, freshConfig, orphans.customNames, outcome);
+        }, {
+            onTimeoutMessage: `Timed out waiting for the furnace lock at ${lockPath}. ` +
+                'Another fireforge furnace command may be running; retry the repair once it finishes.',
+        });
+    }
+    catch (err) {
+        if (progress.persisted) {
+            outcome.errors.push(`repair failed while ${progress.phase}: ${toError(err).message}`);
+            return outcome;
+        }
+        return {
+            ...emptyOutcome(),
+            unrecoverable: outcome.unrecoverable,
+            repairError: `while ${progress.phase}: ${toError(err).message}`,
+        };
+    }
+    return outcome;
+}
+/** Override half of {@link repairOrphans}; mutates `freshConfig` in place. */
+function repairOverridesLocked(freshConfig, orphans, outcome) {
     for (const orphan of orphans) {
+        if (orphan.name in freshConfig.overrides || orphan.name in freshConfig.custom) {
+            // Registered while we waited for the lock — no longer an orphan, and
+            // writing over it would either discard that write or duplicate the name
+            // across `overrides` and `custom`.
+            outcome.reconciled.push(orphan.name);
+            continue;
+        }
         if (orphan.recoveredConfig) {
             freshConfig.overrides[orphan.name] = orphan.recoveredConfig;
-            restored.push(orphan.name);
+            outcome.restored.push(orphan.name);
         }
         else {
-            unrecoverable.push(orphan.name);
+            outcome.unrecoverable.push(orphan.name);
         }
     }
-    if (restored.length > 0) {
-        try {
-            await writeFurnaceConfig(projectRoot, freshConfig);
-        }
-        catch (err) {
-            return { restored: [], unrecoverable, writeError: toError(err).message };
-        }
-    }
-    return { restored, unrecoverable };
 }
-async function repairCustomOrphans(projectRoot, customNames) {
-    const deleted = [];
-    const retained = [];
-    const errors = [];
+/** Custom half of {@link repairOrphans}; must run under the same lock. */
+async function deleteEmptyCustomOrphans(projectRoot, freshConfig, customNames, outcome) {
     if (customNames.length === 0)
-        return { deleted, retained, errors };
+        return;
     const furnacePaths = getFurnacePaths(projectRoot);
     for (const name of customNames) {
+        if (name in freshConfig.custom || name in freshConfig.overrides) {
+            // A name that was orphaned in BOTH trees is reconciled once, not once
+            // per tree — the report reads "Skipped 2 names (x, x)" otherwise.
+            if (!outcome.reconciled.includes(name))
+                outcome.reconciled.push(name);
+            continue;
+        }
         const dir = join(furnacePaths.customDir, name);
         let entries;
         try {
             entries = await readdir(dir, { withFileTypes: true });
         }
         catch (err) {
-            errors.push(`${name}: ${toError(err).message}`);
+            outcome.errors.push(`${name}: ${toError(err).message}`);
             continue;
         }
         if (entries.length > 0) {
-            retained.push(name);
+            outcome.retained.push(name);
             continue;
         }
         try {
-            await rm(dir);
-            deleted.push(name);
+            // `rmdir`, not `rm`: `rm` without `{ recursive: true }` throws EISDIR on
+            // a directory, so on a real filesystem this branch always failed and the
+            // "deleted N empty directories" report was unreachable. `rmdir` is also
+            // the exact semantics wanted here — it refuses a non-empty directory,
+            // which keeps the emptiness check above from being the only safeguard.
+            await rmdir(dir);
+            outcome.deleted.push(name);
         }
         catch (err) {
-            errors.push(`${name}: ${toError(err).message}`);
+            outcome.errors.push(`${name}: ${toError(err).message}`);
         }
     }
-    return { deleted, retained, errors };
 }
 export const furnaceManifestSyncCheck = {
     name: 'Furnace manifest sync',
@@ -169,12 +264,15 @@ export const furnaceManifestSyncCheck = {
         if (!ctx.options.repairFurnace) {
             return warning('Furnace manifest sync', summary, 'Run "fireforge doctor --repair-furnace" to re-register override orphans from their override.json sidecars (custom orphans are listed for manual follow-up).');
         }
-        const repairResult = await repairOrphanOverrides(ctx.projectRoot, orphans.overrides);
-        if (repairResult.writeError) {
-            return failure('Furnace manifest sync', `Repair failed while writing furnace.json: ${repairResult.writeError}`, 'Fix the underlying filesystem error and retry the doctor command.');
+        const repairResult = await repairOrphans(ctx.projectRoot, orphans);
+        if (repairResult.repairError) {
+            return failure('Furnace manifest sync', `Repair failed ${repairResult.repairError}`, 'Fix the underlying error and retry the doctor command.');
         }
-        const customRepair = await repairCustomOrphans(ctx.projectRoot, orphans.customNames);
-        const { restored, unrecoverable } = repairResult;
+        const customRepair = repairResult;
+        const { restored, unrecoverable, reconciled } = repairResult;
+        const reconciledDetail = reconciled.length > 0
+            ? ` Skipped ${reconciled.length} name${reconciled.length === 1 ? '' : 's'} (${reconciled.join(', ')}) that furnace.json already listed by the time the repair held the furnace lock — a concurrent furnace command registered ${reconciled.length === 1 ? 'it' : 'them'} first.`
+            : '';
         const restoreDetail = restored.length > 0
             ? `Re-registered ${restored.length} override${restored.length === 1 ? '' : 's'} (${restored.join(', ')}) from their override.json sidecars.`
             : '';
@@ -190,7 +288,7 @@ export const furnaceManifestSyncCheck = {
         const customErrorDetail = customRepair.errors.length > 0
             ? ` Could not inspect or delete ${customRepair.errors.length} custom orphan ${customRepair.errors.length === 1 ? 'directory' : 'directories'} (${customRepair.errors.join('; ')}).`
             : '';
-        return warning('Furnace manifest sync', `${restoreDetail}${unrecoverableDetail}${customDetail}${retainedCustomDetail}${customErrorDetail}`.trim() ||
+        return warning('Furnace manifest sync', `${restoreDetail}${unrecoverableDetail}${customDetail}${retainedCustomDetail}${customErrorDetail}${reconciledDetail}`.trim() ||
             'Nothing to repair (orphans surfaced but all were already recoverable).');
     },
 };

package/dist/src/commands/doctor-furnace.js

@@ -8,7 +8,7 @@ import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from '../core/furnace-const
 import { getFurnaceLockPath, runFurnaceMutation } from '../core/furnace-operation.js';
 import { hasBlockingStepErrors } from '../core/furnace-step-errors.js';
 import { validateAllComponents } from '../core/furnace-validate.js';
-import { toError } from '../utils/errors.js';
+import { isProcessAlive, toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { failure, ok, warning } from './doctor-check-core.js';
 import { furnaceStaleJarRegistrationCheck } from './doctor-furnace-jar.js';
@@ -120,6 +120,9 @@ async function collectFurnaceDrift(projectRoot, engineDir, config, ftlDir) {
             }
         }
         catch {
+            // A drift probe that cannot complete is reported AS drift: the doctor check
+            // must not claim a component is clean when it failed to look. Mirrors the
+            // documented twin above.
             drifted.push(name);
         }
     }
@@ -428,18 +431,11 @@ async function readFurnaceLockPid(lockPath) {
         return Number.isFinite(pid) ? pid : null;
     }
     catch {
+        // No PID file, or it is unreadable/unparseable. The caller falls back to the
+        // age-only staleness heuristic, which is why this is `null` and not a throw.
         return null;
     }
 }
-function isProcessStillRunning(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * "Furnace stale lock" check: detect and (under `--repair-furnace`)
  * remove a `.fireforge/furnace.lock` directory whose owner process is no
@@ -474,7 +470,13 @@ const furnaceStaleLockCheck = {
         //      this bucket; the age gate avoids false positives on a lock
         //      that was just acquired by a concurrent process that hadn't
         //      written its PID yet.
-        const ownerDead = pid !== null && !isProcessStillRunning(pid);
+        //
+        // `isProcessAlive` treats EPERM as ALIVE. The local copy it replaced
+        // returned false for EPERM, so a furnace lock held by a live process
+        // owned by another uid was reported as "owner is no longer running"
+        // and deleted by --repair-furnace, dropping mutual exclusion under a
+        // concurrent furnace operation.
+        const ownerDead = pid !== null && !isProcessAlive(pid);
         const pidMissingAndOld = pid === null && (ageMs ?? 0) > 60_000;
         const isStale = ownerDead || pidMissingAndOld;
         if (!isStale) {

package/dist/src/commands/doctor-orphaned-harness.js

@@ -20,6 +20,7 @@
  * doctor AND/OR `test --canary`, and adding a system-wide process scan to
  * the canary hot path buys no extra coverage over the doctor check.
  */
+import { toError } from '../utils/errors.js';
 import { exec } from '../utils/process.js';
 import { ok, warning } from './doctor-check-core.js';
 /**
@@ -104,7 +105,7 @@ async function runOrphanedHarnessCheck() {
         psOutput = await listSystemProcesses();
     }
     catch (error) {
-        return warning(CHECK_NAME, `Could not scan system processes (${error instanceof Error ? error.message : String(error)}); skipping the orphaned-worker check.`);
+        return warning(CHECK_NAME, `Could not scan system processes (${toError(error).message}); skipping the orphaned-worker check.`);
     }
     const orphans = findOrphanedHarnessWorkers(psOutput);
     if (orphans.length === 0) {

package/dist/src/commands/doctor.js

@@ -13,7 +13,7 @@ import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
 import { findExecutable } from '../utils/process.js';
 import { POST_REBASE_AUDIT_CHECK } from './doctor/post-rebase-audit.js';
-import { failure, ok, warning } from './doctor-check-core.js';
+import { failure, ok, resolveDoctorSeverity, warning } from './doctor-check-core.js';
 import { EXTERNAL_TOOLCHAIN_DOCTOR_CHECK } from './doctor-external-toolchains.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { ORPHANED_HARNESS_DOCTOR_CHECK } from './doctor-orphaned-harness.js';
@@ -406,7 +406,7 @@ export function reportDoctorResults(checks) {
     let warningCount = 0;
     let failedCount = 0;
     for (const check of checks) {
-        const severity = check.severity ?? (check.passed ? (check.warning ? 'warning' : 'ok') : 'error');
+        const severity = resolveDoctorSeverity(check);
         if (severity === 'warning') {
             warn(`! ${check.name}: ${check.message}`);
             if (check.fix) {

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

@@ -195,6 +195,10 @@ export async function exportAllCommand(projectRoot, options = {}) {
     // post-hoc string surgery on the aggregate diff, which keeps the
     // output shape aligned with the single-file `export` command.
     let diff;
+    // Retain the exact scope used to build the aggregate. Interactive
+    // license-header repair mutates engine files and therefore has to rebuild
+    // the diff, but it must not silently widen an --exclude-furnace export.
+    let scopedExportPaths;
     if (furnaceExcluded.size > 0) {
         const rawChanged = await getWorkingTreeStatus(paths.engine);
         const allChanged = await expandUntrackedDirectoryEntries(paths.engine, rawChanged);
@@ -203,6 +207,7 @@ export async function exportAllCommand(projectRoot, options = {}) {
                 .flatMap((entry) => [entry.file, entry.originalPath].filter((value) => !!value))
                 .filter((file) => !furnaceExcluded.has(file))),
         ].sort();
+        scopedExportPaths = nonFurnacePaths;
         if (nonFurnacePaths.length === 0) {
             info(`Excluded ${furnaceExcluded.size} furnace-managed file(s) from export; no non-Furnace changes remain.`);
             outro('Nothing to export');
@@ -234,7 +239,10 @@ export async function exportAllCommand(projectRoot, options = {}) {
     // report-only under --dry-run so the preview never mutates engine/)
     const headersAdded = await autoFixLicenseHeaders(paths.engine, diff, config, isInteractive, isDryRun);
     if (headersAdded) {
-        diff = await getAllDiff(paths.engine);
+        diff =
+            scopedExportPaths === undefined
+                ? await getAllDiff(paths.engine)
+                : await getDiffForFilesAgainstHead(paths.engine, scopedExportPaths);
     }
     const metadata = await promptExportPatchMetadata(options, isInteractive, 'export-all', config);
     if (!metadata)

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

@@ -20,6 +20,7 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
+import { groupProjectedPlacementErrors } from './export-placement-conflicts.js';
 import { assertPlacementAvoidsReservedRanges } from './export-placement-policy.js';
 import { findPartialOwnershipOverlap } from './export-shared.js';
 function buildFilenameForPlacement(category, name, order, width) {
@@ -74,14 +75,22 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
     const sorted = [...manifestPatches].sort((a, b) => a.order - b.order);
     const renameMap = new Map();
     const prefixWidth = prefixWidthForPatches(sorted, requestedOrder);
-    // Every existing patch at requestedOrder or later shifts up by one.
+    // Patches at requestedOrder or later shift up by one, but only until the
+    // cascade reaches a free ordinal — a gap absorbs the insert, so the tail
+    // beyond it (including any reserved block) keeps its numbering.
+    let cursor = requestedOrder;
     for (const patch of sorted) {
-        if (patch.order >= requestedOrder) {
-            const newOrder = patch.order + 1;
-            const currentRest = patch.filename.replace(/^\d+-/, '');
-            const newFilename = `${String(newOrder).padStart(prefixWidth, '0')}-${currentRest}`;
-            renameMap.set(patch.filename, { newOrder, newFilename });
+        if (patch.order < requestedOrder) {
+            continue;
         }
+        if (patch.order > cursor) {
+            break;
+        }
+        const newOrder = cursor + 1;
+        const currentRest = patch.filename.replace(/^\d+-/, '');
+        const newFilename = `${String(newOrder).padStart(prefixWidth, '0')}-${currentRest}`;
+        renameMap.set(patch.filename, { newOrder, newFilename });
+        cursor = newOrder;
     }
     const newFilename = buildFilenameForPlacement(newPatchCategory, newPatchName, requestedOrder, prefixWidth);
     return {
@@ -199,15 +208,24 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
         modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff),
     });
     projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    const policyRest = baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {};
     const projectedIssues = lintPatchQueue({
         entries: projectedEntries,
-        ...(baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {}),
+        ...policyRest,
     }).filter((i) => i.severity === 'error');
     if (projectedIssues.length === 0)
         return null;
+    // Baseline lint over the UN-renumbered queue: an error present here is
+    // pre-existing breakage, not a consequence of this placement — calling
+    // it one would misattribute (FORGE K9). Entries are already in memory,
+    // so this second pass costs no additional IO.
+    const baselineIssues = lintPatchQueue({
+        entries: baseCtx.entries,
+        ...policyRest,
+    }).filter((i) => i.severity === 'error');
     return {
         reason: `placement would introduce ${projectedIssues.length} cross-patch lint error(s)`,
-        details: projectedIssues.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+        details: groupProjectedPlacementErrors(projectedIssues, baselineIssues, plan),
     };
 }
 /**
@@ -240,7 +258,7 @@ export async function commitPlacementExport(input) {
         }
         const conflicts = await projectPlacementForLint(input.patchesDir, currentPlan, input.diff, input.config);
         if (conflicts && input.unsafeOverride !== true) {
-            throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. ` +
+            throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}:\n  ${conflicts.details.join('\n  ')}\n` +
                 'If the conflict names files owned by another patch (e.g. duplicate-new-file-creation), ' +
                 're-run the export with an explicit file list that leaves those files with their owner — ' +
                 'do NOT bypass with --force-unsafe. Pass --force-unsafe only for a reviewed placement conflict.', '--force-unsafe');

package/dist/src/commands/export-placement-conflicts.d.ts

@@ -0,0 +1,17 @@
+import type { PatchRenameEntry } from '../core/patch-manifest.js';
+import type { PatchLintIssue } from '../types/commands/index.js';
+/** Inputs {@link groupProjectedPlacementErrors} needs from the plan. */
+export interface PlacementAttributionPlan {
+    insertionOrder: number;
+    newFilename: string;
+    renameMap: Map<string, PatchRenameEntry>;
+}
+/**
+ * Partitions the projected placement errors into three labeled groups —
+ * defects in the exported content, consequences of the renumbering, and
+ * errors the queue already had — rendered as indented detail lines for
+ * {@link ConflictReport.details}. Grouping travels through the plain
+ * `details: string[]`, so both refusal sites and confirmDestructive's
+ * conflict printer show it without changes.
+ */
+export declare function groupProjectedPlacementErrors(projectedErrors: readonly PatchLintIssue[], baselineErrors: readonly PatchLintIssue[], plan: PlacementAttributionPlan): string[];

package/dist/src/commands/export-placement-conflicts.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Attribution of projected placement lint errors (FORGE K9), split out of
+ * export-flow.ts for the line budget. A placement projection lints one
+ * merged queue — the renumbered existing patches plus a synthetic entry
+ * for the pending patch — so its errors used to render as one flat list
+ * that read as though the NEW patch caused every one of them. A
+ * renumbering that re-evaluates pre-existing staged relationships (455
+ * importing a module created by 456, legal only at their current
+ * ordinals) then sent the operator auditing a perfectly fine export.
+ *
+ * Consumed by export-flow.ts; no top-level registrar is exported and none
+ * is wanted.
+ */
+import { formatPatchLintIssue } from '../core/patch-lint.js';
+/**
+ * Identity for baseline comparison: check + site file + implicated
+ * patches, with projected filenames mapped BACK through the rename map so
+ * a pre-existing error keeps its identity across the renumber. Never
+ * parses the fingerprint — it is documented rename-sensitive.
+ */
+function issueKey(issue, mapBackToOldName) {
+    const patches = (issue.patches ?? []).map(mapBackToOldName).sort((a, b) => a.localeCompare(b));
+    return `${issue.check}|${issue.file}|${patches.join(',')}`;
+}
+/**
+ * Partitions the projected placement errors into three labeled groups —
+ * defects in the exported content, consequences of the renumbering, and
+ * errors the queue already had — rendered as indented detail lines for
+ * {@link ConflictReport.details}. Grouping travels through the plain
+ * `details: string[]`, so both refusal sites and confirmDestructive's
+ * conflict printer show it without changes.
+ */
+export function groupProjectedPlacementErrors(projectedErrors, baselineErrors, plan) {
+    const oldNameByNew = new Map();
+    for (const [oldFilename, rename] of plan.renameMap) {
+        oldNameByNew.set(rename.newFilename, oldFilename);
+    }
+    const mapBack = (name) => oldNameByNew.get(name) ?? name;
+    const baselineKeys = new Set(baselineErrors.map((issue) => issueKey(issue, (name) => name)));
+    const exported = [];
+    const renumbering = [];
+    const preExisting = [];
+    for (const issue of projectedErrors) {
+        // The synthetic entry's filename is unique in the projection, so
+        // membership in `patches` attributes exactly. Issues from older rules
+        // without the field fall back to a message scan, then to "the queue".
+        const implicatesNewPatch = issue.patches?.includes(plan.newFilename) ?? issue.message.includes(plan.newFilename);
+        if (implicatesNewPatch) {
+            exported.push(issue);
+        }
+        else if (baselineKeys.has(issueKey(issue, mapBack))) {
+            preExisting.push(issue);
+        }
+        else {
+            renumbering.push(issue);
+        }
+    }
+    const details = [];
+    const pushGroup = (header, issues) => {
+        if (issues.length === 0)
+            return;
+        details.push(header);
+        for (const issue of issues) {
+            details.push(`  ${formatPatchLintIssue(issue)}`);
+        }
+    };
+    pushGroup(`errors in the exported patch content (${String(exported.length)}):`, exported);
+    pushGroup(`consequences of renumbering existing patches to make room at ordinal ` +
+        `${String(plan.insertionOrder)} (${String(renumbering.length)}) — these come from ` +
+        'renumbering, NOT from the exported content:', renumbering);
+    pushGroup(`errors already present in the queue before this export (${String(preExisting.length)}):`, preExisting);
+    return details;
+}

package/dist/src/commands/export-placement-gate.js

@@ -96,7 +96,7 @@ export async function gatePlacementPlan(args) {
     }
     else if (conflicts && options.forceUnsafe !== true) {
         s.stop();
-        throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. ` +
+        throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}:\n  ${conflicts.details.join('\n  ')}\n` +
             'If the conflict names files owned by another patch (e.g. duplicate-new-file-creation), ' +
             're-run the export with an explicit file list that leaves those files with their owner — ' +
             'do NOT bypass with --force-unsafe. Pass --force-unsafe only for a reviewed placement conflict.', '--force-unsafe');

package/dist/src/commands/export-shared.d.ts

@@ -1,4 +1,4 @@
-import type { PatchesManifest } from '../types/commands/index.js';
+import type { PatchesManifest, PatchLintIssue } from '../types/commands/index.js';
 import type { ExportOptions, PatchCategory } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import type { SpinnerHandle } from '../utils/logger.js';
@@ -25,6 +25,13 @@ import type { SpinnerHandle } from '../utils/logger.js';
  *   visible rather than silent.
  */
 export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>, patchTier?: 'branding'): Promise<void>;
+/**
+ * Prints a patch-lint issue list with `runPatchLint`'s exact severity
+ * buckets and skip-lint semantics, throwing on errors unless `skipLint`.
+ * Factored out so `re-export`'s cached-lint path (FORGE J1) can replay
+ * stored issues through the identical reporter without re-linting.
+ */
+export declare function reportPatchLintOutcome(issues: PatchLintIssue[], skipLint?: boolean): void;
 /**
  * Resolves patch metadata interactively or from flags, with shared validation.
  * @param options - Export command options