@hominis/fireforge 0.37.0 → 0.39.0

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

@@ -10,44 +10,47 @@ function findReservedRange(config, order) {
     return (config.patchPolicy?.reservedRanges?.find((range) => order >= range.from && order <= range.to) ??
         null);
 }
-function suggestSparseOrder(config, patches, category, insertionOrder) {
-    const ranges = (config.patchPolicy?.ranges ?? [])
-        .filter((range) => range.category === category)
-        .sort((a, b) => a.from - b.from || a.to - b.to);
+/**
+ * Scans downward from just below the reserved block for the first order
+ * not occupied by an existing patch. Returns null when every positive
+ * order below the block is taken.
+ */
+function firstFreeOrderBelowReservedRange(patches, range) {
     const occupied = new Set(patches.map((patch) => patch.order));
-    for (const range of ranges) {
-        for (let order = Math.max(insertionOrder, range.from); order <= range.to; order++) {
-            if (!occupied.has(order) && findReservedRange(config, order) === null)
-                return order;
-        }
-    }
-    for (const range of ranges) {
-        for (let order = range.from; order <= range.to; order++) {
-            if (!occupied.has(order) && findReservedRange(config, order) === null)
-                return order;
-        }
+    for (let order = range.from - 1; order >= 1; order--) {
+        if (!occupied.has(order))
+            return order;
     }
     return null;
 }
-/** Refuses positional export plans that would renumber exact reserved patches. */
-export function assertPlacementPreservesReservedRanges(plan, manifestPatches, config, category) {
+/**
+ * Refuses positional placement plans whose renumber would touch a
+ * `patchPolicy.reservedRanges` block — either by moving a patch INTO a
+ * reserved range or by moving a patch that currently sits inside one.
+ * Throws a single up-front error for the first reserved range hit (the
+ * per-patch alternative surfaced one confusing finding per shifted
+ * patch), suggesting the first free `--order` below the block when one
+ * exists. Exact `--order` plans have an empty rename map and pass.
+ */
+export function assertPlacementAvoidsReservedRanges(plan, manifestPatches, config) {
     if (config?.patchPolicy === undefined || plan.renameMap.size === 0)
         return;
     const byFilename = new Map(manifestPatches.map((patch) => [patch.filename, patch]));
     for (const [filename, rename] of plan.renameMap) {
-        const patch = byFilename.get(filename);
-        if (!patch)
-            continue;
-        const reserved = findReservedRange(config, patch.order);
+        const oldOrder = byFilename.get(filename)?.order;
+        const reserved = findReservedRange(config, rename.newOrder) ??
+            (oldOrder !== undefined ? findReservedRange(config, oldOrder) : null);
         if (reserved === null)
             continue;
-        const suggestion = suggestSparseOrder(config, manifestPatches, category, plan.insertionOrder);
-        const suggestionText = suggestion !== null
-            ? ` Use --order ${String(suggestion).padStart(3, '0')} to create the new patch in an unused ${category} slot without renumbering reserved patches.`
-            : ` Choose an unused order in the ${category} policy range or adjust patchPolicy.`;
-        throw new InvalidArgumentError(`Positional export would renumber reserved patch ${patch.filename} ` +
-            `from ${String(patch.order).padStart(3, '0')} to ${rename.newFilename} ` +
-            `(reserved range ${reservedRangeLabel(reserved)}).` +
-            suggestionText, 'export placement');
+        const label = reservedRangeLabel(reserved);
+        const freeOrder = firstFreeOrderBelowReservedRange(manifestPatches, reserved);
+        if (freeOrder !== null) {
+            throw new InvalidArgumentError(`Positional insert would renumber the reserved range ${label}; ` +
+                `pass --order ${String(freeOrder).padStart(3, '0')} (first free order below the ` +
+                'reserved block) to place the new patch without renumbering reserved patches.', 'export placement');
+        }
+        throw new InvalidArgumentError(`Positional insert would renumber the reserved range ${label}; ` +
+            'no free order exists below the reserved block. Choose an unused --order outside ' +
+            'the reserved range or adjust patchPolicy.reservedRanges.', 'export placement');
     }
 }

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { confirm, select, text } from '@clack/prompts';
-import { addLicenseHeaderToFile } from '../core/license-headers.js';
+import { addLicenseHeaderToFile, hasThirdPartyPermissiveBanner } from '../core/license-headers.js';
 import { findAllPatchesForFiles } from '../core/patch-export.js';
 import { commentStyleForFile, detectNewFilesInDiff, isAcceptableNewFileHeader, lintExportedPatch, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
@@ -218,6 +218,7 @@ export async function autoFixLicenseHeaders(engineDir, diffContent, config, isIn
     if (newFiles.size === 0)
         return false;
     const filesToFix = [];
+    const vendoredFiles = [];
     for (const file of newFiles) {
         const style = commentStyleForFile(file);
         if (!style)
@@ -231,9 +232,23 @@ export async function autoFixLicenseHeaders(engineDir, diffContent, config, isIn
         // MPL block header on a derived JS/CSS file) would stack a second
         // header on top of a legitimate one.
         if (!isAcceptableNewFileHeader(file, content, style, license)) {
-            filesToFix.push(file);
+            // A recognized third-party permissive banner marks the file as
+            // vendored: prepending the project's own license header would break
+            // byte-identity pins and mislicense upstream code (FORGE F15).
+            if (hasThirdPartyPermissiveBanner(content)) {
+                vendoredFiles.push(file);
+            }
+            else {
+                filesToFix.push(file);
+            }
         }
     }
+    if (vendoredFiles.length > 0) {
+        const vendoredList = vendoredFiles.map((f) => `  - ${f}`).join('\n');
+        info(`${vendoredFiles.length} new file(s) carry a third-party permissive license banner and ` +
+            'were left untouched (vendored); if the missing-license-header lint check flags them, ' +
+            `waive it with --lint-ignore missing-license-header:\n${vendoredList}`);
+    }
     if (filesToFix.length === 0)
         return false;
     if (dryRun) {

package/dist/src/commands/export.js

@@ -20,7 +20,7 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
-import { commanderArgParser, pickDefined } from '../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag } from '../utils/validation.js';
 import { commitPlacementExport, renderDryRunPreview } from './export-flow.js';
@@ -400,7 +400,7 @@ export async function exportCommand(projectRoot, files, options) {
 }
 /** Registers the export command on the CLI program. */
 export function registerExport(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const exportCmd = program
         .command('export <paths...>')
         .description('Export new changes as a patch (use re-export to update existing patches)')
         .option('-n, --name <name>', 'Name for the patch')
@@ -418,8 +418,8 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
         .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap (default mode only; the resulting queue fails verify)')
         .addOption(new Option('--tier <tier>', 'Force a tier override on the new patch (only "branding" recognised)').choices(['branding']))
-        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', (value, prev) => [...prev, value], [])
-        .action(withErrorHandling(async (paths, options) => {
+        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', (value, prev) => [...prev, value], []);
+    addWaitLockOption(exportCmd).action(withErrorHandling(async (paths, options) => {
         const { category, tier, lintIgnore, ...rest } = options;
         const projectRoot = getProjectRoot();
         await withEngineSessionLock(projectRoot, 'export', () => exportCommand(projectRoot, paths, {
@@ -427,6 +427,6 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
             ...(category !== undefined ? { category } : {}),
             ...(tier !== undefined ? { tier: tier } : {}),
             ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
-        }));
+        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { Command, Option } from 'commander';
 import { withEngineSessionLock } from '../../core/engine-session-lock.js';
-import { pickDefined } from '../../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
 import { furnaceApplyCommand } from './apply.js';
 import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
 import { furnaceChromeDocRemoveCommand } from './chrome-doc-remove.js';
@@ -19,61 +19,66 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
-async function runEngineLockedFurnaceCommand(context, command, operation) {
+async function runEngineLockedFurnaceCommand(context, command, operation, waitLockSeconds) {
     const projectRoot = context.getProjectRoot();
-    await withEngineSessionLock(projectRoot, command, () => operation(projectRoot));
+    await withEngineSessionLock(projectRoot, command, () => operation(projectRoot), {
+        waitLockSeconds,
+    });
 }
 function registerFurnaceApplyCommand(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    furnace
+    const apply = furnace
         .command('apply [name]')
         .description('Apply components to the engine (optionally a single component)')
         .option('--dry-run', 'Show what would be changed without writing (reads may overlap concurrent mutations)')
         .option('--force', 'Proceed despite baseVersion drift (stale overrides)')
-        .option('-w, --watch', 'Watch component directories and re-apply on changes')
-        .action(withErrorHandling(async (name, options) => {
-        const parsed = pickDefined(options ?? {});
+        .option('-w, --watch', 'Watch component directories and re-apply on changes');
+    addWaitLockOption(apply).action(withErrorHandling(async (name, options) => {
+        const { waitLock, ...rest } = options ?? {};
+        const parsed = pickDefined(rest);
         const run = (projectRoot) => furnaceApplyCommand(projectRoot, name, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace apply', run);
+        await runEngineLockedFurnaceCommand(context, 'furnace apply', run, resolveWaitLockSeconds(waitLock));
     }));
 }
 function registerFurnaceDeployCommand(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    furnace
+    const deploy = furnace
         .command('deploy [name]')
         .description('Apply components and validate in one step')
         .option('--dry-run', 'Show what would be changed without writing (reads may overlap concurrent mutations)')
         .option('--force', 'Proceed despite baseVersion drift (stale overrides)')
-        .option('--skip-validate', 'Skip the validation step (apply only)')
-        .action(withErrorHandling(async (name, options) => {
-        const parsed = pickDefined(options ?? {});
+        .option('--skip-validate', 'Skip the validation step (apply only)');
+    addWaitLockOption(deploy).action(withErrorHandling(async (name, options) => {
+        const { waitLock, ...rest } = options ?? {};
+        const parsed = pickDefined(rest);
         const run = (projectRoot) => furnaceDeployCommand(projectRoot, name, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace deploy', run);
+        await runEngineLockedFurnaceCommand(context, 'furnace deploy', run, resolveWaitLockSeconds(waitLock));
     }));
 }
 function registerFurnaceSyncCommand(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    furnace
+    const sync = furnace
         .command('sync')
         .description('Refresh drifted overrides and re-apply all components (recommended after fireforge download)')
         .option('--dry-run', 'Show what would change without modifying files (reads may overlap concurrent mutations)')
-        .addOption(new Option('-s, --strategy <strategy>', 'Auto-resolve merge conflicts (ours = keep local, theirs = accept upstream)').choices(['ours', 'theirs']))
-        .action(withErrorHandling(async (options) => {
-        const parsed = pickDefined(options);
+        .addOption(new Option('-s, --strategy <strategy>', 'Auto-resolve merge conflicts (ours = keep local, theirs = accept upstream)').choices(['ours', 'theirs']));
+    addWaitLockOption(sync).action(withErrorHandling(async (options) => {
+        const { waitLock, ...rest } = options;
+        const parsed = pickDefined(rest);
         const run = (projectRoot) => furnaceSyncCommand(projectRoot, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace sync', run);
+        await runEngineLockedFurnaceCommand(context, 'furnace sync', run, resolveWaitLockSeconds(waitLock));
     }));
 }
 /**

package/dist/src/commands/import.js

@@ -8,6 +8,7 @@ import { getDirtyFiles } from '../core/git-status.js';
 import { applyPatchesWithContinue, countPatches, createPatchedContentComputer, discoverPatches, extractAffectedFiles, matchesUntilFilename, PatchError, } from '../core/patch-apply.js';
 import { checkVersionCompatibility, loadPatchesManifest, validatePatchesManifestConsistency, validatePatchIntegrity, } from '../core/patch-manifest.js';
 import { getPatchSourceVersion } from '../core/patch-source-metadata.js';
+import { warnIfStaticComponentsStale } from '../core/test-stale-check.js';
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
@@ -419,6 +420,10 @@ export async function importCommand(projectRoot, options = {}) {
             const suffix = result.autoResolved ? ' (auto-resolved)' : '';
             success(`  ${result.patch.filename}${suffix}`);
         }
+        // The re-applied queue may have moved components.conf away from what
+        // the last full build compiled in — surface that now instead of at the
+        // next test refusal (FORGE F13).
+        await warnIfStaticComponentsStale(projectRoot, paths.engine);
         outro('All patches applied successfully!');
     }
     catch (error) {

package/dist/src/commands/lint-per-patch.js

@@ -56,6 +56,11 @@ async function lintQueuedPatch(patch, lintCtx) {
         });
         const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
         if (cached) {
+            // Returning before the empty-diff probe below is safe: the cache key
+            // hashes every affected engine file's content plus engineHeadSha, so
+            // an engine-side revert that would empty the diff always changes the
+            // key and misses the cache (pinned by the "engine-side content
+            // revert invalidates the per-patch cache" test — FORGE F5).
             return { status: 'cached', existingFiles: existing, rawIssues: cached, usedCheckJs: false };
         }
     }
@@ -115,9 +120,14 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
             continue;
         }
         emitTierNotice(patch.filename, result.existingFiles, patch.tier);
-        // Run-level checkJs errors are emitted once, before the first freshly
-        // linted patch's own issues — matching the serial emit point.
-        if (result.usedCheckJs && checkJs && !globalCheckJsEmitted) {
+        // Run-level checkJs errors are emitted once, before the first
+        // non-skipped patch's own issues — matching the serial emit point.
+        // Deliberately NOT gated on `result.usedCheckJs`: global findings are
+        // run-level, never cached, and an all-cache-hit run previously dropped
+        // them entirely, letting a warm run report fewer errors than a cold
+        // one (FORGE F5 hardening). PerRunCheckJs builds its program lazily,
+        // so the cost only materialises when checkJs is configured.
+        if (checkJs && !globalCheckJsEmitted) {
             globalCheckJsEmitted = true;
             issues.push(...(await checkJs.getGlobal()));
         }
@@ -276,7 +286,7 @@ function buildPerRunCheckJs(projectRoot, paths, config, ctx) {
     return {
         ownedByPatch,
         getGrouped: () => (groupedPromise ??= invokePatchLintCheckJsGrouped(paths.engine, resolvePatchOwnedSysMjs(new Set(), ctx), patchLint, projectRoot)),
-        getGlobal: async () => (groupedPromise ? (await groupedPromise).global : []),
+        getGlobal: async () => (await (groupedPromise ??= invokePatchLintCheckJsGrouped(paths.engine, resolvePatchOwnedSysMjs(new Set(), ctx), patchLint, projectRoot))).global,
     };
 }
 /**
@@ -299,7 +309,7 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
     const subsetNames = new Set(subset.map((p) => p.filename));
     const isSubset = subset.length !== manifest.patches.length;
     const config = await loadConfig(projectRoot);
-    const ctx = await buildPatchQueueContext(paths.patches);
+    const ctx = await buildPatchQueueContext(paths.patches, config);
     // Queue-level findings (policy, cross-patch) are scoped to the requested
     // subset: a 5-patch slice should not fail on a policy or forward-import
     // problem owned entirely by patches the operator did not target.

package/dist/src/commands/lint.js

@@ -461,7 +461,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
     // per-patch ownership resolver and the cross-patch rules.
     let ctx;
     if (await pathExists(paths.patches)) {
-        ctx = await buildPatchQueueContext(paths.patches);
+        ctx = await buildPatchQueueContext(paths.patches, config);
     }
     // Ad-hoc explicit-file-list mode evaluates the patch-size rules per
     // owning patch (see `lintOwningPatchSizes`), so suppress the synthetic

package/dist/src/commands/patch/lint-ignore.js

@@ -26,6 +26,16 @@ import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+/**
+ * Printed whenever `--add` lands a new check id. The waiver this command
+ * writes turns per-patch lint green immediately, but consumer projects
+ * commonly audit lintIgnore lists against a reviewed allow-map — the
+ * discovery that the map also needs updating otherwise costs a full
+ * downstream gate run (FORGE F6).
+ */
+const LINT_IGNORE_REVIEW_WARNING = "This lint waiver is subject to the project's patch-policy review process. " +
+    'Downstream policy audits that mirror lintIgnore lists in a reviewed allow-map ' +
+    'will refuse this patch until the map is updated to include the new ID(s).';
 /**
  * Computes the post-mutation `lintIgnore` list for a given mode.
  * Returns `undefined` when the result should drop the field from the
@@ -114,7 +124,10 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     // the flag only appeared in the history record — and suppressing lint
     // findings is precisely the mutation an operator should consciously
     // approve.
-    const projectedSummary = describeChange(target.lintIgnore ?? [], applyMode(target.lintIgnore ?? [], mode, values) ?? [], mode, values);
+    const currentList = target.lintIgnore ?? [];
+    const projectedList = applyMode(currentList, mode, values) ?? [];
+    const addsNewIds = mode === 'add' && projectedList.length > currentList.length;
+    const projectedSummary = describeChange(currentList, projectedList, mode, values);
     const decision = await confirmDestructive({
         operation: 'patch-lint-ignore',
         title: `Patch lint-ignore: ${target.filename}`,
@@ -123,6 +136,9 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         dryRun: isDryRun,
     });
     if (decision === 'dry-run') {
+        if (addsNewIds) {
+            warn(LINT_IGNORE_REVIEW_WARNING);
+        }
         outro('Dry run complete — no changes made');
         return;
     }
@@ -148,6 +164,9 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     const existing = result.before.lintIgnore ?? [];
     const projected = result.after.lintIgnore ?? [];
     info(`${target.filename}: ${describeChange(existing, projected, mode, values)}.`);
+    if (mode === 'add' && projected.length > existing.length) {
+        warn(LINT_IGNORE_REVIEW_WARNING);
+    }
     try {
         await appendHistory(paths.patches, {
             operation: 'patch-lint-ignore',

package/dist/src/commands/patch/move-files-create.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `fireforge patch move-files <from> <to> --create --order <n>` — creates
+ * the target patch at the requested sparse order and moves the files into
+ * it as one transaction. This is the transactional bootstrap of a split:
+ * without it, moving files into a not-yet-existing patch required a manual
+ * shrink-then-export dance with hand-repointed staged-dependency owners.
+ *
+ * Mirrors `patch split` end-to-end (same planning, projection lint,
+ * policy enforcement, and locked commit); the `<to>` argument becomes the
+ * new patch's name/slug the way `split --name` does.
+ */
+import type { PatchMoveFilesOptions } from '../../types/commands/index.js';
+/**
+ * Runs `patch move-files --create --order <n>`: plans the create+move as a
+ * split, lints the projection, confirms, and commits transactionally.
+ */
+export declare function patchMoveFilesCreateCommand(projectRoot: string, fromIdentifier: string, newPatchName: string, options: PatchMoveFilesOptions & {
+    order: number;
+}): Promise<void>;

package/dist/src/commands/patch/move-files-create.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch move-files <from> <to> --create --order <n>` — creates
+ * the target patch at the requested sparse order and moves the files into
+ * it as one transaction. This is the transactional bootstrap of a split:
+ * without it, moving files into a not-yet-existing patch required a manual
+ * shrink-then-export dance with hand-repointed staged-dependency owners.
+ *
+ * Mirrors `patch split` end-to-end (same planning, projection lint,
+ * policy enforcement, and locked commit); the `<to>` argument becomes the
+ * new patch's name/slug the way `split --name` does.
+ */
+import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { confirmDestructive } from '../../core/destructive.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { enforcePatchPolicy } from '../../core/patch-policy.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { info, intro, outro, success } from '../../utils/logger.js';
+import { resolvePlacementPlan } from '../export-flow.js';
+import { runPatchLint } from '../export-shared.js';
+import { commitPatchSplit } from './split.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, projectSplitManifest, runProjectedSplitLint, } from './split-plan.js';
+/**
+ * Runs `patch move-files --create --order <n>`: plans the create+move as a
+ * split, lints the projection, confirms, and commits transactionally.
+ */
+export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, newPatchName, options) {
+    intro(options.dryRun === true
+        ? 'FireForge patch move-files --create (dry run)'
+        : 'FireForge patch move-files --create');
+    const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const source = resolvePatchIdentifier(fromIdentifier, manifest.patches);
+    if (!source) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(fromIdentifier, manifest.patches), 'patch move-files');
+    }
+    const existingTarget = resolvePatchIdentifier(newPatchName, manifest.patches);
+    if (existingTarget) {
+        throw new InvalidArgumentError(`--create target "${newPatchName}" already exists as ${existingTarget.filename}. ` +
+            'Omit --create to preview a move into the existing patch, or pick a new patch name.', '--create');
+    }
+    const movedFiles = [...new Set((options.file ?? []).map((f) => f.trim()).filter(Boolean))].sort();
+    if (movedFiles.length === 0) {
+        throw new InvalidArgumentError('Specify at least one --file path to move.', '--file');
+    }
+    assertSourceOwnsFiles(source, movedFiles);
+    const movedSet = new Set(movedFiles);
+    const remainingFiles = source.filesAffected.filter((f) => !movedSet.has(f));
+    if (remainingFiles.length === 0) {
+        throw new InvalidArgumentError(`Moving every file out of ${source.filename} would leave it empty. ` +
+            'Use "fireforge patch rename" / "fireforge patch reorder" to repurpose or move the whole patch instead.', '--file');
+    }
+    const movedDiff = await buildSplitDiff(paths.engine, movedFiles, 'moved', source.filename);
+    const remainingDiff = await buildSplitDiff(paths.engine, remainingFiles, 'remaining', source.filename);
+    const category = options.category ?? source.category;
+    const placementOptions = { order: options.order };
+    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, newPatchName, config);
+    const plan = {
+        source,
+        movedFiles,
+        remainingFiles,
+        movedDiff,
+        remainingDiff,
+        placement,
+        placementOptions,
+        category,
+        name: newPatchName,
+        description: options.description ?? '',
+        ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
+        // Populated by runProjectedSplitLint below (forward edges into the new patch).
+        stagedDependencyAdditions: new Map(),
+    };
+    // Per-patch lint both projected bodies, threading the source patch's
+    // tier/lintIgnore so an intentional-advisory patch can still move files.
+    const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
+    await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
+    await runPatchLint(paths.engine, movedFiles, movedDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
+    const { conflicts, stagedDependencyAdditions } = await runProjectedSplitLint(paths.patches, plan);
+    plan.stagedDependencyAdditions = stagedDependencyAdditions;
+    const newMetadata = buildNewPatchMetadata(plan, config);
+    enforcePatchPolicy({
+        config,
+        manifest: projectSplitManifest(manifest, plan, newMetadata),
+        command: 'patch move-files --create',
+        forceUnsafe: options.forceUnsafe === true,
+    });
+    const decision = await confirmDestructive({
+        operation: 'patch-move-files-create',
+        title: `Create ${placement.newFilename} (order ${placement.insertionOrder}) and move ${movedFiles.length} file(s) out of ${source.filename}`,
+        summary: buildSplitSummary(plan),
+        yes: options.yes === true,
+        dryRun: options.dryRun === true,
+        unsafeOverride: options.forceUnsafe === true,
+        conflicts,
+    });
+    if (decision === 'dry-run') {
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    if (decision === 'cancelled') {
+        outro('Move cancelled');
+        return;
+    }
+    await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
+    success(`Created ${placement.newFilename} (order ${String(placement.insertionOrder).padStart(3, '0')}) ` +
+        `and moved ${plan.movedFiles.length} file(s) out of ${source.filename}`);
+    if (plan.ownerRewrites.length > 0) {
+        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
+    }
+    outro('Move complete');
+}

package/dist/src/commands/patch/move-files-into.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Transactional file-ownership move into an EXISTING patch (FORGE F4).
+ *
+ * Before 0.39.0, `patch move-files <from> <to>` with an existing target was
+ * preview-only: it printed two `re-export --files` commands whose real
+ * execution cost three further refusals (`--allow-shrink`, `--yes`, and a
+ * projected `duplicate-new-file-creation` unless the SHRINK landed first —
+ * while the printed plan listed the grow first). This module performs the
+ * same shrink→grow as one transaction under the patch-directory lock with
+ * rollback, mirroring `patch split` / `move-files --create`.
+ *
+ * Preconditions match `re-export`: the engine worktree must currently
+ * reflect both patches' content, because both bodies are regenerated from
+ * the worktree.
+ */
+import type { PatchMetadata, PatchMoveFilesOptions, PatchStagedForwardImport } from '../../types/commands/index.js';
+import type { FireForgeConfig } from '../../types/config.js';
+/** Everything the commit step needs, computed and confirmed up front. */
+export interface MoveIntoPlan {
+    source: PatchMetadata;
+    target: PatchMetadata;
+    movedFiles: string[];
+    sourceAfter: string[];
+    targetAfter: string[];
+    sourceDiff: string;
+    targetDiff: string;
+    /** Patches (by filename) whose staged-dependency owners re-point to the target. */
+    ownerRewrites: string[];
+    /** Forward-import declarations the move introduces, keyed by importing patch. */
+    stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
+}
+/**
+ * Plans, lints, confirms, and commits a file-ownership move into an
+ * existing patch. Called by `patchMoveFilesCommand` after its ownership
+ * pre-checks resolved and validated both patches.
+ */
+export declare function runMoveFilesInto(args: {
+    enginePath: string;
+    patchesDir: string;
+    source: PatchMetadata;
+    target: PatchMetadata;
+    files: string[];
+    sourceAfter: string[];
+    targetAfter: string[];
+    options: PatchMoveFilesOptions;
+    config: FireForgeConfig;
+}): Promise<void>;