@hominis/fireforge 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.38.0
+
+- **`status --ownership` reports a furnace-deployed file whose owning patch body went stale as drift** (friction-log item 1, bug — after `furnace deploy` refreshed 12 deployed widget copies, the pre-export "consult ownership" step read clean while the composed gate caught the staleness later on the re-export path): the classifier no longer short-circuits every furnace-prefixed path into the `furnace` bucket — a furnace path claimed by exactly ONE patch now runs the same expected-content comparison as any patch-owned file (`computePatchedContent` vs the deployed copy, deletion and error branches included), classifying as `patch-owned-drift` on divergence and staying `furnace` on a match. Multi-owner and unowned furnace paths keep the old bucket (cross-patch conflicts are already surfaced independently), so the only behavioral change is that stale widget patches now show as drift in the table and in `--json` (machine consumers see those paths move from `"furnace"` to `"patch-owned-drift"`). An integration test pins the exact observed sequence: deploy, export the patch, edit the component source, deploy again, and `status --ownership` reports the owning patch drifted.
+- **Scoped `test --build` and build-less runs refuse a `components.conf` changed since the last FULL build** (friction-log item 2, bug — a new about: module packaged fine under a scoped `test --build` but the child process resolved `NS_ERROR_MALFORMED_URI`, because `components.conf` entries bake into the compiled StaticComponents table that only a full build regenerates; the failure was silent and read as a test bug): the baseline gains `staticComponentsBaseline` (`engineHeadSha` + per-manifest content fingerprints), written fresh only by full-coverage builds and carried forward verbatim through scoped `test --build` writes — so the guard always anchors to the last full build, not the last scoped one. Any scoped `test --build` or non-`--build` run over a changed `components.conf` is refused up front with a message naming the manifest(s), explaining the compiled-table mechanism and the misleading error shape, and advising `fireforge build`; `--allow-stale-build` deliberately does NOT bypass it (it accepts stale packaged content, not a stale compiled registration), while the new `--allow-stale-components` downgrades the refusal to a warning for out-of-band rebuilds. Detection keys on the `components.conf` basename (`isXpcomManifestPath` is the single documented extension point; parsing `moz.build` `XPCOM_MANIFESTS` wiring is out of scope), pre-0.38.0 baselines lack the anchor and degrade to fresh, and probe failures never block a run.
+- **Per-patch size lint agrees with `wc -l` and fires only ABOVE the soft limit** (friction-log item 3, lint bug — three independent recurrences: a file counted one line more than `wc -l` from patch-hunk trailing-newline accounting, and `file-too-large` fired at "750 lines (soft limit: 750)" while a wc-1499 patch reported 1500/1500, each costing 1–2 trim/re-export/lint cycles): line counting now drops the phantom element a trailing newline adds (`countContentLines` for on-disk content, the same correction inside `countNonBinaryDiffLines` for patch bodies, with binary-hunk subtraction kept consistent), and every tier of `file-too-large` and `large-patch-lines` compares strictly (`>`), matching the already-strict `large-patch-files`, so a file or patch sitting exactly AT a notice/soft/hard limit is clean. Boundary tests pin limit−1 / limit / limit+1 for both rules across the general, test, and branding tiers, plus the trailing-newline agreement cases.
+- **Patch-lint accepts both established upstream MPL header wraps** (friction-log item 4, lint — derived files keeping the genuine upstream header of files like `ext-browser.js`, which wrap after "file," instead of the canonical break after "this", were flagged `missing EUPL-1.2 license header`): the upstream-MPL acceptance in `hasAnyLicenseHeader`/`hasUpstreamMplBlockHeader` keeps its exact-prefix fast path and adds a whitespace-normalized fallback — the leading comment span (line-comment run, first block comment, or hash run; anything else never matches) is collapsed to single spaces and must still begin with the full canonical MPL sentence including the URL — so any line-break position within the verbatim text passes while altered wording still fails. Both wraps are tested on JS and CSS comment styles, with and without leading editor directives.
+- **The packaged-test coverage guard accepts same-manifest siblings instead of demanding the exact recorded path set** (friction-log item 5, test inefficiency — a run scoped to `…/hominis-webext/file_A.js` refused `file_B.js` of the SAME manifest, forcing a ~1–2 min repackage per alternation): coverage is now matched at manifest granularity — mozbuild manifests are per-directory and mach stages support-files per manifest, so a request whose manifest granule (a file's containing directory; a directory itself) equals a covered entry's granule is accepted, as are subset paths of a covered directory; genuinely uncovered manifests keep the existing refusal verbatim, and the recorded baseline format is unchanged so 0.37.0 and 0.38.0 baselines interoperate both ways. The entry's second suggestion — unioning covered sets across successive scoped builds to stop concurrent-session ping-pong — was evaluated and rejected as UNSOUND: every baseline write refreshes content fingerprints for ALL dirty packageable paths, so a union would whitewash an earlier scope's edited fixtures while `obj-*/_tests/` still holds that scope's stale staging — precisely the silent-hang class the guard exists to refuse. The verdict is recorded on `testPackagingCoverage`'s doc contract; coverage REPLACES.
+- **Positional inserts refuse with ONE actionable error when they would renumber a reserved range, `patch move-files --create --order <n>` bootstraps a split in one step, and `re-export --scan` refuses forward-import adoptions** (friction-log item 6, patch-tooling ergonomics, three parts): (a) `patch split --before` / positional `export` on a dense queue that would shift patches through a `patchPolicy.reservedRanges` block no longer sprays per-patch reserved-range findings — the placement plan is gated up front (`assertPlacementAvoidsReservedRanges`, subsuming the old inside-range check) with a single error naming the range and computing the remedy: `pass --order <first free number below the reserved block>`, or explicit guidance when no free order exists. (b) `patch move-files` gains `--create --order <n>`: creating the target patch and moving the files is one transaction through the split pipeline (same placement gate, projected cross-patch lint, and staged-dependency owner repointing the manual shrink-then-export dance needed by hand), while the flag-less preview behavior is unchanged. (c) `re-export --scan`/`--scan-file`/`--scan-files` run the forward-import check per adoption candidate BEFORE adopting: a candidate importing a module created by a LATER patch is refused with the later patch and closest legal ordinal named, advising `export --order` / `patch split --order` / `patch staged-dependency --add`; declared staged dependencies and lint-ignores are honored because the gate runs the real cross-patch rule on a projected queue.
+- **Engine-mutating commands can wait for the engine lock instead of failing fast** (friction-log item 7, missing-feature — two sessions on one engine tree had operators hand-rolling `for i in $(seq 1 60); do CMD; sleep 25; done` around "Another FireForge engine-mutating command is already running"): `test`, `build`, `export`, `re-export`, and the engine-locked furnace subcommands gain `--wait-lock [seconds]` (bare flag = 60, validated 1–3600), which polls the lock with exponential backoff (100 ms doubling to a 2 s cap) up to the bound, printing a progress line about every 5 s identifying the holder from the lock's owner metadata (`Waiting for the FireForge engine lock held by PID … (command=…, started=…) — 10s of up to 60s.`), then proceeds when the lock frees or fails with the unchanged standard message. Without the flag, behavior is byte-identical to the 1 s fail-fast; the lock-ownership invariants and their doc (`docs/lifecycle-invariants.md`) are updated to cover the bounded wait.
+- **`furnace validate` credits the implicit wrapping `<label>` association** (friction-log item 8, false positive — `[unlabelled-form-input]` fired on the accessible `<label><input type="radio">…</label>` pattern although the control has an accessible name per the HTML spec): an input/select/textarea nested inside a `<label>` whose content includes real text (tags stripped; a `${…}` binding deliberately counts as text since it is legitimate dynamic label content) is now treated as labelled; a bare input, or one wrapped in an empty or tags-only `<label>`, still warns, and the explicit `for`/`aria-label`/`aria-labelledby` paths are unchanged.
+- **`furnace create --shared-ftl <path>` was already shipped; its validation is now pinned by tests** (friction-log item 9, missing-feature — verified already implemented on current main: the flag sets `sharedFtl` in furnace.json, skips the component-local FTL scaffold, emits the `insertFTLIfNeeded` line for the given path verbatim, and rejects the contradictory `--no-localized` combination): 0.38.0 adds the previously missing direct unit tests for `validateSharedFtl` (trimming, empty/non-string rejection, unsafe-character rejection, localized requirement) and a command-level test pinning the exact CLI rejection wording.
+- **`source set --candidate <buildN>` fetches release-candidate archives** (friction-log item 10, missing-feature — `resolveArchive` hardcoded `pub/firefox/releases/`, so a `candidates/<version>-candidates/buildN/` source, the normal shape for pre-release verification, forced hand-seeding `.fireforge/cache/` with an independently verified tarball + sidecar): `firefox.candidate` (validated `buildN`, also settable via `fireforge config firefox.candidate` and cleared with `--clear-candidate`) switches resolution to `pub/<product>/candidates/<version>-candidates/<buildN>/source/…` with the matching `SHA256SUMS` alongside the build directory; devedition and ESR fall out of the existing product/version handling, cache filenames gain a `-<buildN>` suffix so candidate artifacts never collide with release artifacts, and the sha256-pin trust model is unchanged (an explicit `firefox.sha256` pin still fails closed and takes precedence over the published checksums). Recording the candidate in exported patches' source provenance was considered and deferred — it cascades into `PatchMetadata` schema/validation churn across the manifest round-trip surface.
+
 ## 0.37.0
 
 - **`fireforge test --build` now records the stale-build baseline** (friction-log item 1, inefficiency — "stale-build guard re-arms across invocation shapes"): a green pre-test build refreshes `.fireforge/last-build.json` through the same `writeBuildBaseline` path as `fireforge build`/`build --ui`, so after one `test --build` over a set of edited files, a subsequent plain `fireforge test` over the same files — per-file, per-directory, or full suite — passes the gate without a second redundant `--build` round trip. The baseline is content-fingerprint-based and project-scoped, which is also per-obj-dir (multi-objdir checkouts are already refused up front), so no per-invocation-shape keying is needed; both directions (file-scoped rebuild → full-suite run, and full/directory rebuild → file run) are covered by tests.

package/README.md

@@ -4,7 +4,7 @@
 [![license](https://img.shields.io/npm/l/@hominis/fireforge)](LICENSE.md)
 [![node](https://img.shields.io/node/v/@hominis/fireforge)](package.json)
 
-FireForge is a CLI tool for maintaining Firefox-based browser forks. It downloads Firefoxs source code, lets you export changes as patches, helps apply them and has some neat/mad code quality enforcement, built by taking a lot of learnings from the existing Firefox source code and trying to make the process as robust as can be. Ideally, FireForge makes everything from managing custom UI components to enforcing some rudimentary typechecking much easier, but I'll be honest, there is only so much one can do, so understanding upstream is advised, especially once future updates come into the mix. I cannot guarantee how reliably these will apply, but I did try to assist in that process as much as I can by learning from prior Firefox versions which had major changes made to them, though this is of course still no guarantee for future success or that the methods will remain reliable. Beware of that.
+FireForge is a CLI tool for maintaining Firefox-based browser forks. It downloads Firefoxs source code, lets you export changes as patches, helps apply them and has some neat/mad code quality enforcement, built by taking a lot of learnings from the existing Firefox source code and trying to make the process as robust as can be. Ideally, FireForge makes everything from managing custom UI components to enforcing some rudimentary typechecking much easier, but I'll be honest, there is only so much one can do, so understanding upstream is advised, especially once future updates come into the mix. ~~I cannot guarantee how reliably these will apply, but I did try to assist in that process as much as I can by learning from prior Firefox versions which had major changes made to them, though this is of course still no guarantee for future success or that the methods will remain reliable. Beware of that.~~ Edit 16.07.2026: I have now upgraded and downgraded and sidegraded, really all the graded, across all the versions in many scenarios with modifications so far removed from upstream that I think it's fair to say upgrading is fairly reliable.
 
 Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon](https://github.com/dothq/melon).
 

package/dist/src/commands/build.js

@@ -14,7 +14,7 @@ import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { checkDiskSpace, pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
 import { isPositiveInteger } from '../utils/validation.js';
 function parseJobCount(value) {
     const parsed = Number(value);
@@ -336,7 +336,7 @@ export async function buildCommand(projectRoot, options) {
 }
 /** Registers the build command on the CLI program. */
 export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const build = program
         .command('build')
         .description('Build the browser (auto-applies Furnace components first)')
         .option('--ui', 'Fast UI-only rebuild')
@@ -360,9 +360,9 @@ export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
         'and runs mach configure — preserving up to ~20 GB of obj-* artefacts on',
         'a relocation. The rewriter refuses any change that is not a pure prefix',
         'move, in which case a clean rebuild is still required.',
-    ].join('\n'))
-        .action(withErrorHandling(async (options) => {
+    ].join('\n'));
+    addWaitLockOption(build).action(withErrorHandling(async (options) => {
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 'build', () => buildCommand(projectRoot, pickDefined(options)));
+        await withEngineSessionLock(projectRoot, 'build', () => buildCommand(projectRoot, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

package/dist/src/commands/config.js

@@ -35,6 +35,7 @@ const STRING_TYPED_KEYS = new Set([
     'firefox.version',
     'firefox.product',
     'firefox.sha256',
+    'firefox.candidate',
     'license',
     'wire.subscriptDir',
 ]);

package/dist/src/commands/download.js

@@ -160,7 +160,7 @@ async function restorePreviousEngine(args) {
     }
 }
 async function downloadAndExtractFirefox(args) {
-    const { version, product, engineDir, cacheDir, sha256 } = args;
+    const { version, product, engineDir, cacheDir, sha256, candidate } = args;
     let s = spinner(`Downloading Firefox ${version}...`);
     let lastPercent = 0;
     const phaseState = { value: 'download' };
@@ -181,7 +181,7 @@ async function downloadAndExtractFirefox(args) {
             }
         }, sha256, (message) => {
             s.message(message);
-        });
+        }, candidate);
         s.stop(phaseState.value === 'extract'
             ? `Firefox ${version} extracted`
             : `Firefox ${version} downloaded`);
@@ -402,6 +402,9 @@ export async function downloadCommand(projectRoot, options) {
                 engineDir: installEngineDir,
                 cacheDir,
                 ...(config.firefox.sha256 !== undefined ? { sha256: config.firefox.sha256 } : {}),
+                ...(config.firefox.candidate !== undefined
+                    ? { candidate: config.firefox.candidate }
+                    : {}),
             });
             if (replacementEngineDir && backupEngineDir) {
                 warn('Activating replacement engine directory...');

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

@@ -39,8 +39,12 @@ export declare function computePlacementPlan(manifestPatches: PatchMetadata[], n
 export declare function computeExactPlacementPlan(manifestPatches: PatchMetadata[], newPatchCategory: PatchCategory, newPatchName: string, requestedOrder: number): PlacementPlan;
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
+ * When `config` is provided, positional plans (`--before`/`--after`) are
+ * refused up front if their renumber would touch a reserved range — one
+ * error for the whole shift instead of per-patch policy findings. The
+ * exact `--order` branch never renames, so it bypasses that gate.
  */
-export declare function resolvePlacementPlan(patchesDir: string, options: ExportOptions, category: PatchCategory, name: string): Promise<PlacementPlan>;
+export declare function resolvePlacementPlan(patchesDir: string, options: ExportOptions, category: PatchCategory, name: string, config?: FireForgeConfig): Promise<PlacementPlan>;
 /**
  * Projects the placement through cross-patch lint to detect forward-imports
  * the renumber would introduce *or* that the new patch itself would

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

@@ -20,7 +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 { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
+import { assertPlacementAvoidsReservedRanges } from './export-placement-policy.js';
 import { findPartialOwnershipOverlap } from './export-shared.js';
 function buildFilenameForPlacement(category, name, order, width) {
     const padded = String(order).padStart(Math.max(3, width), '0');
@@ -113,8 +113,12 @@ export function computeExactPlacementPlan(manifestPatches, newPatchCategory, new
 }
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
+ * When `config` is provided, positional plans (`--before`/`--after`) are
+ * refused up front if their renumber would touch a reserved range — one
+ * error for the whole shift instead of per-patch policy findings. The
+ * exact `--order` branch never renames, so it bypasses that gate.
  */
-export async function resolvePlacementPlan(patchesDir, options, category, name) {
+export async function resolvePlacementPlan(patchesDir, options, category, name, config) {
     // ForWrite: placement planning feeds a manifest rewrite; a corrupt
     // manifest read as empty would allocate colliding orders.
     const manifest = await loadPatchesManifestForWrite(patchesDir);
@@ -147,7 +151,9 @@ export async function resolvePlacementPlan(patchesDir, options, category, name)
         }
         targetOrder = anchor.order + 1;
     }
-    return computePlacementPlan(existingPatches, category, name, targetOrder);
+    const plan = computePlacementPlan(existingPatches, category, name, targetOrder);
+    assertPlacementAvoidsReservedRanges(plan, existingPatches, config);
+    return plan;
 }
 /**
  * Extracts the newly-created files a diff would produce and builds the
@@ -225,7 +231,7 @@ export function placementSummary(plan) {
  */
 export async function commitPlacementExport(input) {
     return withPatchDirectoryLock(input.patchesDir, async () => {
-        const currentPlan = await resolvePlacementPlan(input.patchesDir, input.options, input.category, input.name);
+        const currentPlan = await resolvePlacementPlan(input.patchesDir, input.options, input.category, input.name, input.config);
         if (!placementPlansEqual(currentPlan, input.expectedPlan)) {
             throw new InvalidArgumentError('Patch queue changed while waiting for export confirmation. Re-run the command to recompute placement.', 'export placement');
         }
@@ -237,9 +243,6 @@ export async function commitPlacementExport(input) {
                 'do NOT bypass with --force-unsafe. Pass --force-unsafe only for a reviewed placement conflict.', '--force-unsafe');
         }
         const originalManifest = await loadPatchesManifestForWrite(input.patchesDir);
-        if (originalManifest !== null) {
-            assertPlacementPreservesReservedRanges(currentPlan, originalManifest.patches, input.config, input.category);
-        }
         if (input.config !== undefined) {
             const renamed = originalManifest !== null
                 ? applyRenameMapToManifest(originalManifest, currentPlan.renameMap)

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

@@ -12,7 +12,6 @@ import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { outro } from '../utils/logger.js';
 import { placementSummary, projectPlacementForLint, resolvePlacementPlan, } from './export-flow.js';
-import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
 /**
  * Spreadable optional metadata (`tier`, `lintIgnore`) derived from the
  * export flags. Every manifest-row construction site in this command
@@ -41,11 +40,10 @@ export async function gatePlacementPlan(args) {
     if (options.supersede) {
         throw new InvalidArgumentError('Placement flags (--order/--before/--after) cannot be combined with --supersede.', 'export placement');
     }
-    const placementPlan = await resolvePlacementPlan(patchesDir, options, selectedCategory, patchName);
+    // resolvePlacementPlan runs the reserved-range gate itself when config
+    // is passed — one up-front error per run instead of per-patch findings.
+    const placementPlan = await resolvePlacementPlan(patchesDir, options, selectedCategory, patchName, config);
     const currentManifest = await loadPatchesManifest(patchesDir);
-    if (currentManifest !== null) {
-        assertPlacementPreservesReservedRanges(placementPlan, currentManifest.patches, config, selectedCategory);
-    }
     const conflicts = await projectPlacementForLint(patchesDir, placementPlan, diff);
     const renamed = currentManifest !== null
         ? applyRenameMapToManifest(currentManifest, placementPlan.renameMap)

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

@@ -1,7 +1,7 @@
 /**
  * Policy-aware checks for export placement plans.
  */
-import type { PatchCategory, PatchMetadata } from '../types/commands/index.js';
+import type { PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 export interface PlacementPolicyPlan {
     insertionOrder: number;
@@ -10,5 +10,13 @@ export interface PlacementPolicyPlan {
         newOrder: number;
     }>;
 }
-/** Refuses positional export plans that would renumber exact reserved patches. */
-export declare function assertPlacementPreservesReservedRanges(plan: PlacementPolicyPlan, manifestPatches: readonly PatchMetadata[], config: FireForgeConfig | undefined, category: PatchCategory): void;
+/**
+ * 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 declare function assertPlacementAvoidsReservedRanges(plan: PlacementPolicyPlan, manifestPatches: readonly PatchMetadata[], config: FireForgeConfig | undefined): void;

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.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/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.d.ts

@@ -1,6 +1,8 @@
 /**
  * `fireforge patch move-files <from> <to>` previews the explicit
- * re-export choreography needed to move file ownership between two patches.
+ * re-export choreography needed to move file ownership between two
+ * patches. With `--create --order <n>` the target patch is created and
+ * the files move into it as one transaction (see move-files-create.ts).
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';